做前端这十几年部署这件事的变化挺有意思。早些年接一个企业官网流程是买台主机、开 FTP、把打包好的 dist 拖上去改一次文案就得从头再来一遍后来容器化流行又开始写 Dockerfile、配 Nginx、盯着证书到期日。直到我把手上几个纯静态项目陆续迁到Cloudflare Pages上才算真正体会到“推代码就上线”是什么感觉。Cloudflare Pages 是 Cloudflare 推出的一套面向前端项目的静态站点托管与部署平台它把构建、全球分发、HTTPS 证书、预览环境这几件原本分散的事收进了一条流水线仓库连上去填两行配置之后每次 push 都自动出一套新环境。它不是那种“上传一个压缩包就完事”的网盘式托管也不是要你租机器自己运维的云服务器定位卡在中间——你只管写代码剩下的构建机、CDN、证书、回滚全部由平台兜住。这篇东西写给三类人看正在给公司官网或文档站找落地方案的开发手里有博客、作品集想低成本上线的个人以及已经用过但总觉得没摸透构建配置和 Functions 边界的同学。我会把架构链路、实操参数、踩过的坑和配额限制都摊开讲能直接抄的部分我会给完整配置。1. Cloudflare Pages 到底解决的是哪一类问题1.1 从 FTP 上传到 Git 驱动部署省掉的到底是什么很多人第一次接触这类平台会觉得“不就是个静态托管嘛对象存储挂个 CDN 也能干”。这么理解没错但漏掉了最值钱的那部分——部署流程本身被重构成了代码的一部分。传统方式里构建发生在你自己的机器上打包、上传、清缓存是三个手动动作出问题只能靠人回忆“上次到底动了什么”。Git 驱动部署把这三个动作绑在了同一次提交上哪次 commit 对应哪份产物、谁推的、什么时候生效全都有记录回滚就是把指针拨回去重放一次构建。这个变化在单人项目上感知不强一旦团队超过三个人就开始值钱了。我见过一个典型场景市场同事要改落地页的一段文案以前得找开发在本地改、打包、上传来来回回半小时现在他自己提个 PR平台自动生成一个预览链接发到群里谁都能点开看效果确认了合并就上线。开发和市场的边界一下子清楚了开发不用当人肉发布机市场也不用排队等。再往深一层说它解决的是环境一致性问题。本地能构建、线上构建失败这个经典难题以前要花大量时间对日志而 Pages 的做法是把构建环境固定成一套镜像Node 版本、包管理器版本都由你显式声明剩下的差异被压缩到了最小。你不需要再去猜“线上那台机器装的是什么版本的 node-gyp”。1.2 它和“对象存储 CDN”方案的本质差异对象存储加 CDN 这套组合拳费用低、稳定很多人第一反应是用它来托管静态站。但真用起来会发现几个绕不开的坑索引文档要手动配访问目录默认返回 404 而不是 index.html得单独指定默认首页、SPA 路由天然不支持前端路由刷新就 404需要靠错误页重定向兜、缓存刷新是手工活每次发布要主动 purge否则用户看到旧资源、没有预览环境想给非技术人员看效果只能先发到测试域名。Cloudflare Pages 这些都是一等公民。SPA 的 fallback 用一行_redirects规则就解决缓存靠文件名哈希做长期缓存加 HTML 短缓存发布即刻生效不用手动刷每次提交自带独立预览域名。差别不在于“能不能做到”而在于“要不要自己搭一套胶水”。胶水本身不难难的是它常年无人维护等到半年后有人接手时那套脚本已经没人敢动了。当然也要承认代价这类平台对产物有体积和文件数量的上限超大资源比如几十 GB 的视频、数据集不适合往里塞那本来就该扔对象存储页面里挂外链就好。静态站托管平台和对象存储不是替代关系而是分工关系我自己的项目就是页面走 Pages、大文件和用户上传走 R2 这类对象存储。1.3 什么样的项目适合上什么样的别硬上按我这几年观察最舒服的几类项目是这样的文档站和博客内容以 Markdown 为主构建产物是纯静态、营销落地页更新频繁但结构固定需要预览和 A/B 版本、前端框架应用React、Vue、Svelte、Astro、Next 的静态导出都行、作品集和小工具访问量不大但要求随时可访问、证书不出岔子。反过来这几种情况我一般会劝人别硬上。第一种是服务端渲染依赖强交互的项目如果每个页面都要实时查库拼 HTML纯静态产物满足不了得走 Functions 或干脆换运行环境。第二种是构建时间极长的项目比如带大型图像处理、模型编译的站点免费额度下每次构建都像在赌运气得提前算好时间成本。第三种是有强合规要求、必须固定出口 IP 或部署在指定机房的业务这类需求不在它的设计目标里。还有一种容易被忽略的情况项目依赖的某些原生模块在构建镜像里编不出来。这时候别急着换平台先看是不是能换成纯 JS 实现或者干脆把这一步挪到构建前、把产物提交进仓库。硬碰硬没意义绕过去往往更快。2. 一次访问背后的链路把架构摊开看2.1 构建产物是怎么落到边缘节点上的理解这条链路配置起来心里才有底。整个流程大致是四段拉取代码 → 在隔离的构建容器里执行构建命令 → 把输出目录里的文件上传成一份不可变快照 → 这份快照被推送到全球边缘网络。注意第三步是“快照”每次部署都是一个独立版本不会覆盖上一次这也是回滚能瞬间生效的原因——回滚本质上是把流量切回某个旧快照不需要重新构建。访问发生时用户的请求会先到就近的边缘节点。如果这个节点上有该快照的缓存副本直接返回没有的话回源取一次之后按缓存策略驻留。所以首次访问某地区可能稍慢之后基本是本地读取。这也解释了一个常见疑惑为什么刚发布完有些地方立刻看到新版本有些地方还显示旧的——通常不是没发布成功而是浏览器或中间层缓存了 HTML。我的习惯是给 HTML 配短缓存甚至不缓存给带哈希的静态资源配一年期强缓存这样既保证更新及时又保住了资源加载速度。这里有个实操细节值得单独说构建产物里不要出现对绝对路径的硬编码。我曾经在一个项目里把资源前缀写死成线上域名结果预览环境的资源全从生产域名加载看起来“能用”实际测的根本不是当前分支的代码。用相对路径或基于环境变量注入的 base 路径预览环境才有意义。2.2 免费额度为什么敢给得这么大方很多人第一次看配额表会怀疑自己看错了静态请求和带宽基本不设限构建次数按天或按月给一个不小的量。这套逻辑其实很朴素——静态资源的边际分发成本已经极低而这类平台真正想卖的是配套的计算、存储和数据库产品。静态托管相当于入口把你带进来之后需要动态能力时自然会去用 Functions、KV、D1、R2 这些东西后者的计费才是重头。对我们使用者来说这意味着两件事。第一纯静态站的成本几乎可以忽略哪怕流量涨十倍账单也不会有明显变化这点和按流量计费的 CDN 差别很大。第二要对自己的使用方式有数。免费额度里最容易超的通常不是流量而是构建次数和并发构建数。免费档一般只允许一个构建同时跑团队里几个人同时推代码后面的就得排队遇到紧急修复会很焦虑。我一般的做法是日常改动合并到主分支批量构建紧急修复单独走一次直接部署避免把构建队列堵死。提示配额政策会随时间调整动手前务必去官方文档核对当前数值。别人博客里写的额度可能已经是两年前的版本照着做容易踩空。2.3 Pages 与 Functions 的职责边界Pages 负责静态Functions 负责动态这个划分听起来简单实际用起来最容易搞混的是什么该放进 Functions什么该在构建期就解决掉。我的判断标准是如果这段逻辑对每个用户返回的结果都一样就放构建期只有依赖请求头、Cookie、查询参数或后端状态的才放 Functions。举个具体例子。站点页脚的“当前年份”完全可以在构建时算好没必要每次请求跑一遍函数而“根据用户语言返回不同文案”就得放 Functions因为构建期不知道访客是谁。再比如调用第三方接口拿数据展示如果数据一天变一次用定时构建或构建钩子就够了如果必须实时那才用 Functions 去代理顺便把密钥藏在服务端避免暴露在前端代码里。这条边界划错代价不小放错方向的直接后果是请求成本和响应延迟都上去了而收益为零。我见过一个项目把整个内容目录在函数里现读现拼访问慢、还经常超时其实那些内容一年也改不了几次构建期生成成纯 HTML 就完事了。3. 从本地项目到公网可访问完整落地流程3.1 动手前的本地自检清单我踩过最亏的一次坑是本地开发服务器跑得好好的直接连仓库构建结果线上白屏。事后复盘问题出在本地 dev 模式和产线构建的路径逻辑不一样。所以现在我的习惯是连仓库之前先在本地跑一遍真正的构建命令用静态服务器起产物看效果确认无误再往上推。这份清单我基本每次都过一遍执行一次完整构建命令不是 dev 模式确认产物目录生成且体积正常用本地静态服务器打开产物确认首页、二级页、404 页都能访问检查是否依赖了只在本地存在的文件比如.env.local确认 Node 版本需求写进.nvmrc或配置文件别指望线上默认版本刚好匹配检查依赖锁文件已提交避免线上按宽松版本范围装出另一套依赖树确认所有文件名大小写一致Linux 构建环境对大小写敏感从某些系统迁过来的项目经常在这里翻车最后一条我单独强调大小写问题是最隐蔽的一类故障。本地不报错、构建也不报错只有运行到具体页面时才 404而且只在部分路由出现。定位方法是把产物目录里所有文件名列出来和代码里的引用逐一比对别靠肉眼扫写个脚本更快。3.2 连接仓库与构建参数怎么填接入流程本身很直白授权代码托管平台选中仓库填构建配置。真正需要动脑的是那几栏参数。下面是我常用的配置参考不同框架按需替换配置项典型填法说明生产分支main或master只有这个分支的提交会发布到正式域名构建命令npm run build用项目里定义好的脚本别在这里堆一长串命令输出目录dist/build/.next的静态导出目录填错是构建“成功但 404”的头号原因根目录留空或填子目录路径单仓库多项目时必填Node 版本通过环境变量声明如NODE_VERSION20不声明就跟随镜像默认值可能随时变化环境变量按需注入敏感值用加密变量构建期可见注意别把密钥打进前端产物关于输出目录我要多说一句。很多框架默认输出目录和平台预设不一样比如某些工具的产物在out或者public下如果照着默认值填构建日志一片绿打开域名却是 404。遇到“构建成功但访问 404”第一件事永远是去构建日志里找输出文件列表看它到底往哪个目录写了东西。这个动作三十秒能定位九成问题。还有一个细节构建命令尽量只调一个脚本把复杂逻辑写进package.json或单独的脚本文件里。原因很实际——平台那栏输入框对超长命令和特殊字符的处理并不总是友好而且写在那儿的东西本地没法复现排查时很被动。3.3 环境变量、分支预览与生产发布环境变量这块我的原则是分环境分开管别图省事一套走天下。预览环境应该指向测试用的接口和测试库生产环境才连正式资源。如果两边共用一套变量某天有人在预览环境里点了“清空数据”后果你自己想。平台一般支持给生产环境和预览环境分别配置多花两分钟能省掉一次事故。分支预览是这套工具里我最喜欢的功能。默认情况下非生产分支的每次提交都会生成一个独立地址URL 里带分支名和提交标识。用它的正确姿势是主分支保持可发布状态功能开发一律走分支PR 描述里贴预览链接让产品和设计直接点开验收合并前确认预览环境的数据是隔离的合并到生产分支自动触发正式发布这套流程跑顺之后“你能不能先发个测试环境我看看”这类对话基本消失了。唯一要注意的是预览地址默认可能被搜索引擎收录如果项目敏感记得给预览环境加访问控制或者noindex头别让半成品页面出现在搜索结果里。发布完成之后部署列表里会保留历史版本。真出了线上事故回滚动作是选一个旧版本重新发布通常几十秒内生效。我建议每次大改动前手动记一下当前生产版本的时间戳虽然列表里看得到但事故现场人是慌的有个明确锚点能省不少时间。3.4 绑定自定义域名与证书的几个细节绑定自定义域名这一步流程是把域名加进去、按提示配置 DNS 记录、等状态变成有效。如果域名本来就在同一家解析服务商下通常几条记录自动带出来几乎不用手填跨服务商的话手动加记录注意别和已有的冲突记录打架。证书是自动签发和续期的这块基本不用操心。真正容易出问题的是域名层级和重定向。比如同时绑定example.com和www.example.com最好明确谁是主域名另一个做 301 跳转别让两个都能访问否则搜索引擎会认为是重复内容。跳转用_redirects写就行比在 DNS 层面折腾省事。还有一个经验先绑域名再切流量。正确顺序是把域名加进去、等证书状态正常、用一个测试路径验证解析已经指向新地址最后再改主域名的解析。反过来做的话中间会有一段证书没就绪、访问报错的窗口期用户投诉就来了。我吃过一次这个亏半夜切解析结果证书签发排队白白折腾一小时。4. 进阶能力Functions、重定向与请求头控制4.1 Pages Functions 的目录约定与路由匹配Functions 的用法很“文件即路由”在项目根目录建一个约定好的函数目录里面的文件路径直接映射成 URL 路径。比如functions/api/hello.js对应/api/hellofunctions/users/[id].js里的方括号表示动态参数。这种设计上手成本低缺点是路径和文件结构强绑定重构时要同步挪文件。一个最小的接口长这样// functions/api/hello.js export async function onRequestGet(context) { const { request, env, params } context; const url new URL(request.url); return new Response( JSON.stringify({ ok: true, q: url.searchParams.get(q), ts: Date.now() }), { headers: { content-type: application/json; charsetutf-8 } } ); }几个实操要点。第一按方法导出onRequestGet、onRequestPost比统一用onRequest再自己判断方法更清晰也少写分支。第二中间件放在约定目录下的特定文件名里可以对一批路由统一做鉴权、加头、日志不用每个函数复制一遍。第三环境变量和各类绑定通过env拿密钥不会出现在前端代码里这是用 Functions 代理第三方接口最大的价值。关于路由优先级容易踩的一个坑是静态文件和函数路径重名。比如你既有public/api/hello.json又有functions/api/hello.js实际命中哪个要按规则判断不是凭直觉。我的做法是干脆从源头上避免重叠静态资源放一类前缀接口放另一类前缀别搅在一起。4.2_redirects与_headers的实战写法这两个文件要放在输出目录的根不是源码根目录位置错了不生效这是新手最常见的失误。如果框架会清空输出目录就把它们放在public这类会被原样拷贝的目录里。_redirects的用法是这样# 旧路径迁移保留权重 /old-blog/* /posts/:splat 301 # 反向代理到外部接口 /api/* https://api.example.com/:splat 200 # SPA 兜底放最后 /* /index.html 200三条规则对应三种典型场景。第一条是站点改版后做路径迁移301 让搜索引擎把权重带过去顺序很重要具体规则要写在通配规则前面否则会被兜底规则先吃掉。第二条是反向代理把外部服务挂到同域下省掉跨域配置注意这种方式会消耗函数调用额度。第三条是单页应用的兜底让所有未匹配路径返回首页由前端路由接管——这条必须放最后一行放前面整个站点的静态资源都会被它拦掉。_headers用来给响应加头写法是按路径分组/* X-Frame-Options: DENY X-Content-Type-Options: nosniff Referrer-Policy: strict-origin-when-cross-origin /assets/* Cache-Control: public, max-age31536000, immutable /*.html Cache-Control: public, max-age0, must-revalidate这里体现的就是前面说的缓存思路带哈希的资源长期缓存HTML 每次校验。安全头建议默认加上尤其是X-Content-Type-Options和Referrer-Policy两条加起来成本几乎为零但能挡掉一类低级风险。内容安全策略CSP别一次性写死先观察模式跑一段时间看看有哪些内联脚本和外部资源被拦了再逐步收紧否则很容易把站点自己搞挂。4.3 缓存策略与构建体积优化缓存这块除了响应头还有一层是平台自身的边缘缓存。默认行为对大多数站点够用但在“发布后必须立刻全量生效”的场景下我会给 HTML 明确设置短缓存避免用户看到旧页面里的旧资源引用。体积优化上有两个硬性约束值得记在心里单文件大小上限和单次部署的文件数量上限。前者通常卡在几十 MB 量级后者在两万个文件左右。正常项目很难碰到但如果你把高清图、字体全集、视频素材一股脑塞进产物目录很容易撞墙而且构建时间会明显变长。我的处理方式分三层。第一层图片在构建期处理转成现代格式、按展示尺寸生成多套、懒加载单张图控制在几百 KB 以内。第二层字体做子集化中文字体全集动辄几 MB按实际用到的字符裁剪能压到几十 KB。第三层大文件外置视频、PDF、数据集放对象存储页面里挂链接。做完这三层绝大多数项目能稳稳落在限制之内构建速度也能提上来。另一件事是构建缓存。平台一般会缓存依赖目录让第二次构建跳过重复安装。这个机制是自动的但会被一些写法破坏比如每次构建都强制清缓存重装、或者没有提交锁文件导致依赖树每次都不一样。提交锁文件这件事看起来小实际影响构建稳定性和耗时别嫌它占仓库空间。5. 踩坑实录构建失败、路由 404 与配额问题5.1 构建阶段高频故障排查表我把这些年遇到的构建问题归了类大部分落在下面这张表里。排查顺序建议从下往上——先看日志最后报的错再往回找上下文。现象常见成因处理方式构建命令报“找不到模块”锁文件未提交或依赖装在开发依赖里但构建环境跳过了提交锁文件确认构建命令包含完整安装步骤构建成功但访问 404输出目录填错或产物实际写在别的子目录翻日志找输出文件列表核对目录名构建耗时突然翻倍依赖数量增长或某步做了全量重算检查依赖树把一次性任务挪到本地或缓存提示 Node 版本不兼容未声明版本跟随了镜像默认值显式设置版本环境变量加版本声明文件内存溢出被杀进程打包器并行度太高或处理了大体积资源调低并行度把大文件移出构建链路环境变量读不到变量配在了另一个环境或构建期未注入核对生产/预览两套配置确认变量名拼写关于最后一条有个细节容易忽略前端框架只有在变量名带特定前缀时才会注入到客户端代码。所以你配了变量构建日志里也能读到但浏览器里就是 undefined八成是前缀不对。这个规则各框架不同查一下文档比瞎试快。5.2 页面能打开但资源 404 的三种典型成因这类问题最磨人因为首页是好的肉眼看不出毛病。我总结下来主要三种。第一种是绝对路径问题。项目部署在子路径下时产物里以斜杠开头的资源引用会指到域名根自然 404。解决办法是配置构建时的基础路径或者全程用相对路径引用。判断方法很简单打开开发者工具看请求的资源地址如果少了那层子路径就是这个问题。第二种是大小写不一致。前面提过这里再强调一次因为它在本地几乎不可能复现。构建环境是区分大小写的代码里写Header.js而文件名是header.js本地无感线上直接崩。我现在的做法是在构建流程里加一步检查把所有引用路径和实际文件名做比对早发现早修。第三种是路由和静态文件的冲突。单页应用加了兜底规则之后某些本该返回真实文件比如robots.txt、sitemap.xml、站点验证文件的请求被兜底规则截走了返回的是 HTML浏览器解析失败。处理办法是在兜底规则之前给这些固定路径加显式的放行规则或者把它们放在优先级更高的匹配位置。5.3 配额、上限与成本控制的实操心得免费额度对个人项目基本够用但团队协作时几个点要提前想清楚。构建并发是最容易卡住的地方。免费档通常只允许一个构建同时进行几个人同时推代码就得排队。我的做法是把日常改动攒着一起合减少构建次数紧急修复单独走一次直接部署通道不经过完整流水线。这不是什么高深技巧但能把等待时间从半小时压到几分钟。构建时长也值得盯。有些项目在本地构建五分钟线上要十五分钟原因是构建机性能和缓存命中率不同。如果构建时间持续增长说明有该优化的地方——通常是依赖太多、或某一步在做重复工作。我遇到过一次某插件每次构建都重新下载一份字典文件后来改成构建前预取并缓存时间直接砍掉一半。函数调用次数是另一个容易被忽略的成本项。前面提到的反向代理方案每一次请求都算一次函数调用如果代理的是高频接口量会涨得很快。静态资源走 CDN 不计这部分但任何经过函数的请求都要算。我一般会问自己一句这个接口真的需要实时吗能用构建期生成的就别用函数。注意额度相关的具体数值随时可能调整做容量规划时以官方当前文档为准别拿旧数据做决策。还有一点部署数量也有限制。每次提交都生成一份部署长期高频提交的项目会积累大量历史版本。一般不影响使用但如果要做归档或审计最好自己在外部记一份发布记录标记清楚哪个版本对应哪次上线。6. 横向选型什么场景该选它什么场景该换方案6.1 四类部署方案的对比视角我不太喜欢“哪个最好”这种问法更有意义的是“在我的约束下哪个最省事”。下面这张表是我在做技术选型时会摆出来的对比维度用类别描述具体产品各自去对照。方案类型上手成本预览环境动态能力成本特征适合场景静态托管平台Git 驱动低自带需配套函数服务静态流量成本极低计算按量文档站、博客、营销页、前端应用对象存储 CDN中需自建无存储和流量分开计费大文件分发、资源托管、成本敏感型传统虚拟主机 / 面板低无支持脚本固定月费老项目维护、需要传统运行环境容器化自建高需自建完全自由机器固定成本弹性差复杂后端、需要完全控制运行时从这张表能看出静态托管平台的优势集中在流程内置预览、回滚、证书、缓存策略都有默认答案你少写很多胶水。代价是灵活度受限遇到平台不支持的能力就只能绕。容器化方案的灵活度最高但所有东西都得自己搭包括那套最容易腐化的部署脚本。我的实际组合通常是前端产物走静态托管平台大文件和用户上传走对象存储需要服务端逻辑的部分走函数或独立服务。三者各管一段谁也不越界。这个组合的好处是每层都能单独替换某天要换平台迁移成本是可控的。6.2 迁移时的注意事项与数据可带走性选型时有个问题值得提前问如果哪天要迁走成本有多大这个问题能帮你避开很多坑。静态托管这块迁走的成本其实很低因为产物就是一堆静态文件换个地方重新部署就行。真正需要留意的是平台特有能力的绑定程度。比如你在函数里大量用了某个平台的键值存储、数据库、对象存储绑定迁移时这部分代码得重写。我的做法是把平台特有能力包一层薄薄的适配层业务代码只调适配层将来换实现只改一个文件。这层抽象不用做得太重几十行就够但能救你一次。域名和 DNS 这块也要提前想。如果域名解析也托管在同一家迁移时涉及解析记录的同步切换需要规划一个低峰时段并且提前把新环境的证书和解析都验证好别等到切换当天才发现某条记录没配。还有个小细节重定向和请求头规则是平台私有的格式迁走时不能直接复用得翻译成目标平台的写法。规则不多的话手动改就行规则多的话建议在仓库里维护一份“语义化”的原始清单各平台配置由脚本生成避免以后再次面对一堆散落的配置。最后分享一点个人体会。这类平台最大的价值不是省钱也不是省机器而是把发布这件事从“需要专门操作”变成“代码提交的自然结果”。这个转变一旦发生团队的迭代节奏会明显不一样——小步提交变得自然回滚不再可怕非技术角色也能参与到验收环节里。我自己的几个项目迁过去之后最大的变化不是访问速度而是“改点东西发上去看看”这个动作变得毫无心理负担而这恰恰是大部分项目能持续改进的前提。至于构建排队、产物体积这些限制用久了自然会有感觉提前把锁文件、输出目录、缓存策略这几件事做对剩下的基本都是小问题。
做前端这十几年部署这件事的变化挺有意思。早些年接一个企业官网流程是买台主机、开 FTP、把打包好的 dist 拖上去改一次文案就得从头再来一遍后来容器化流行又开始写 Dockerfile、配 Nginx、盯着证书到期日。直到我把手上几个纯静态项目陆续迁到Cloudflare Pages上才算真正体会到“推代码就上线”是什么感觉。Cloudflare Pages 是 Cloudflare 推出的一套面向前端项目的静态站点托管与部署平台它把构建、全球分发、HTTPS 证书、预览环境这几件原本分散的事收进了一条流水线仓库连上去填两行配置之后每次 push 都自动出一套新环境。它不是那种“上传一个压缩包就完事”的网盘式托管也不是要你租机器自己运维的云服务器定位卡在中间——你只管写代码剩下的构建机、CDN、证书、回滚全部由平台兜住。这篇东西写给三类人看正在给公司官网或文档站找落地方案的开发手里有博客、作品集想低成本上线的个人以及已经用过但总觉得没摸透构建配置和 Functions 边界的同学。我会把架构链路、实操参数、踩过的坑和配额限制都摊开讲能直接抄的部分我会给完整配置。1. Cloudflare Pages 到底解决的是哪一类问题1.1 从 FTP 上传到 Git 驱动部署省掉的到底是什么很多人第一次接触这类平台会觉得“不就是个静态托管嘛对象存储挂个 CDN 也能干”。这么理解没错但漏掉了最值钱的那部分——部署流程本身被重构成了代码的一部分。传统方式里构建发生在你自己的机器上打包、上传、清缓存是三个手动动作出问题只能靠人回忆“上次到底动了什么”。Git 驱动部署把这三个动作绑在了同一次提交上哪次 commit 对应哪份产物、谁推的、什么时候生效全都有记录回滚就是把指针拨回去重放一次构建。这个变化在单人项目上感知不强一旦团队超过三个人就开始值钱了。我见过一个典型场景市场同事要改落地页的一段文案以前得找开发在本地改、打包、上传来来回回半小时现在他自己提个 PR平台自动生成一个预览链接发到群里谁都能点开看效果确认了合并就上线。开发和市场的边界一下子清楚了开发不用当人肉发布机市场也不用排队等。再往深一层说它解决的是环境一致性问题。本地能构建、线上构建失败这个经典难题以前要花大量时间对日志而 Pages 的做法是把构建环境固定成一套镜像Node 版本、包管理器版本都由你显式声明剩下的差异被压缩到了最小。你不需要再去猜“线上那台机器装的是什么版本的 node-gyp”。1.2 它和“对象存储 CDN”方案的本质差异对象存储加 CDN 这套组合拳费用低、稳定很多人第一反应是用它来托管静态站。但真用起来会发现几个绕不开的坑索引文档要手动配访问目录默认返回 404 而不是 index.html得单独指定默认首页、SPA 路由天然不支持前端路由刷新就 404需要靠错误页重定向兜、缓存刷新是手工活每次发布要主动 purge否则用户看到旧资源、没有预览环境想给非技术人员看效果只能先发到测试域名。Cloudflare Pages 这些都是一等公民。SPA 的 fallback 用一行_redirects规则就解决缓存靠文件名哈希做长期缓存加 HTML 短缓存发布即刻生效不用手动刷每次提交自带独立预览域名。差别不在于“能不能做到”而在于“要不要自己搭一套胶水”。胶水本身不难难的是它常年无人维护等到半年后有人接手时那套脚本已经没人敢动了。当然也要承认代价这类平台对产物有体积和文件数量的上限超大资源比如几十 GB 的视频、数据集不适合往里塞那本来就该扔对象存储页面里挂外链就好。静态站托管平台和对象存储不是替代关系而是分工关系我自己的项目就是页面走 Pages、大文件和用户上传走 R2 这类对象存储。1.3 什么样的项目适合上什么样的别硬上按我这几年观察最舒服的几类项目是这样的文档站和博客内容以 Markdown 为主构建产物是纯静态、营销落地页更新频繁但结构固定需要预览和 A/B 版本、前端框架应用React、Vue、Svelte、Astro、Next 的静态导出都行、作品集和小工具访问量不大但要求随时可访问、证书不出岔子。反过来这几种情况我一般会劝人别硬上。第一种是服务端渲染依赖强交互的项目如果每个页面都要实时查库拼 HTML纯静态产物满足不了得走 Functions 或干脆换运行环境。第二种是构建时间极长的项目比如带大型图像处理、模型编译的站点免费额度下每次构建都像在赌运气得提前算好时间成本。第三种是有强合规要求、必须固定出口 IP 或部署在指定机房的业务这类需求不在它的设计目标里。还有一种容易被忽略的情况项目依赖的某些原生模块在构建镜像里编不出来。这时候别急着换平台先看是不是能换成纯 JS 实现或者干脆把这一步挪到构建前、把产物提交进仓库。硬碰硬没意义绕过去往往更快。2. 一次访问背后的链路把架构摊开看2.1 构建产物是怎么落到边缘节点上的理解这条链路配置起来心里才有底。整个流程大致是四段拉取代码 → 在隔离的构建容器里执行构建命令 → 把输出目录里的文件上传成一份不可变快照 → 这份快照被推送到全球边缘网络。注意第三步是“快照”每次部署都是一个独立版本不会覆盖上一次这也是回滚能瞬间生效的原因——回滚本质上是把流量切回某个旧快照不需要重新构建。访问发生时用户的请求会先到就近的边缘节点。如果这个节点上有该快照的缓存副本直接返回没有的话回源取一次之后按缓存策略驻留。所以首次访问某地区可能稍慢之后基本是本地读取。这也解释了一个常见疑惑为什么刚发布完有些地方立刻看到新版本有些地方还显示旧的——通常不是没发布成功而是浏览器或中间层缓存了 HTML。我的习惯是给 HTML 配短缓存甚至不缓存给带哈希的静态资源配一年期强缓存这样既保证更新及时又保住了资源加载速度。这里有个实操细节值得单独说构建产物里不要出现对绝对路径的硬编码。我曾经在一个项目里把资源前缀写死成线上域名结果预览环境的资源全从生产域名加载看起来“能用”实际测的根本不是当前分支的代码。用相对路径或基于环境变量注入的 base 路径预览环境才有意义。2.2 免费额度为什么敢给得这么大方很多人第一次看配额表会怀疑自己看错了静态请求和带宽基本不设限构建次数按天或按月给一个不小的量。这套逻辑其实很朴素——静态资源的边际分发成本已经极低而这类平台真正想卖的是配套的计算、存储和数据库产品。静态托管相当于入口把你带进来之后需要动态能力时自然会去用 Functions、KV、D1、R2 这些东西后者的计费才是重头。对我们使用者来说这意味着两件事。第一纯静态站的成本几乎可以忽略哪怕流量涨十倍账单也不会有明显变化这点和按流量计费的 CDN 差别很大。第二要对自己的使用方式有数。免费额度里最容易超的通常不是流量而是构建次数和并发构建数。免费档一般只允许一个构建同时跑团队里几个人同时推代码后面的就得排队遇到紧急修复会很焦虑。我一般的做法是日常改动合并到主分支批量构建紧急修复单独走一次直接部署避免把构建队列堵死。提示配额政策会随时间调整动手前务必去官方文档核对当前数值。别人博客里写的额度可能已经是两年前的版本照着做容易踩空。2.3 Pages 与 Functions 的职责边界Pages 负责静态Functions 负责动态这个划分听起来简单实际用起来最容易搞混的是什么该放进 Functions什么该在构建期就解决掉。我的判断标准是如果这段逻辑对每个用户返回的结果都一样就放构建期只有依赖请求头、Cookie、查询参数或后端状态的才放 Functions。举个具体例子。站点页脚的“当前年份”完全可以在构建时算好没必要每次请求跑一遍函数而“根据用户语言返回不同文案”就得放 Functions因为构建期不知道访客是谁。再比如调用第三方接口拿数据展示如果数据一天变一次用定时构建或构建钩子就够了如果必须实时那才用 Functions 去代理顺便把密钥藏在服务端避免暴露在前端代码里。这条边界划错代价不小放错方向的直接后果是请求成本和响应延迟都上去了而收益为零。我见过一个项目把整个内容目录在函数里现读现拼访问慢、还经常超时其实那些内容一年也改不了几次构建期生成成纯 HTML 就完事了。3. 从本地项目到公网可访问完整落地流程3.1 动手前的本地自检清单我踩过最亏的一次坑是本地开发服务器跑得好好的直接连仓库构建结果线上白屏。事后复盘问题出在本地 dev 模式和产线构建的路径逻辑不一样。所以现在我的习惯是连仓库之前先在本地跑一遍真正的构建命令用静态服务器起产物看效果确认无误再往上推。这份清单我基本每次都过一遍执行一次完整构建命令不是 dev 模式确认产物目录生成且体积正常用本地静态服务器打开产物确认首页、二级页、404 页都能访问检查是否依赖了只在本地存在的文件比如.env.local确认 Node 版本需求写进.nvmrc或配置文件别指望线上默认版本刚好匹配检查依赖锁文件已提交避免线上按宽松版本范围装出另一套依赖树确认所有文件名大小写一致Linux 构建环境对大小写敏感从某些系统迁过来的项目经常在这里翻车最后一条我单独强调大小写问题是最隐蔽的一类故障。本地不报错、构建也不报错只有运行到具体页面时才 404而且只在部分路由出现。定位方法是把产物目录里所有文件名列出来和代码里的引用逐一比对别靠肉眼扫写个脚本更快。3.2 连接仓库与构建参数怎么填接入流程本身很直白授权代码托管平台选中仓库填构建配置。真正需要动脑的是那几栏参数。下面是我常用的配置参考不同框架按需替换配置项典型填法说明生产分支main或master只有这个分支的提交会发布到正式域名构建命令npm run build用项目里定义好的脚本别在这里堆一长串命令输出目录dist/build/.next的静态导出目录填错是构建“成功但 404”的头号原因根目录留空或填子目录路径单仓库多项目时必填Node 版本通过环境变量声明如NODE_VERSION20不声明就跟随镜像默认值可能随时变化环境变量按需注入敏感值用加密变量构建期可见注意别把密钥打进前端产物关于输出目录我要多说一句。很多框架默认输出目录和平台预设不一样比如某些工具的产物在out或者public下如果照着默认值填构建日志一片绿打开域名却是 404。遇到“构建成功但访问 404”第一件事永远是去构建日志里找输出文件列表看它到底往哪个目录写了东西。这个动作三十秒能定位九成问题。还有一个细节构建命令尽量只调一个脚本把复杂逻辑写进package.json或单独的脚本文件里。原因很实际——平台那栏输入框对超长命令和特殊字符的处理并不总是友好而且写在那儿的东西本地没法复现排查时很被动。3.3 环境变量、分支预览与生产发布环境变量这块我的原则是分环境分开管别图省事一套走天下。预览环境应该指向测试用的接口和测试库生产环境才连正式资源。如果两边共用一套变量某天有人在预览环境里点了“清空数据”后果你自己想。平台一般支持给生产环境和预览环境分别配置多花两分钟能省掉一次事故。分支预览是这套工具里我最喜欢的功能。默认情况下非生产分支的每次提交都会生成一个独立地址URL 里带分支名和提交标识。用它的正确姿势是主分支保持可发布状态功能开发一律走分支PR 描述里贴预览链接让产品和设计直接点开验收合并前确认预览环境的数据是隔离的合并到生产分支自动触发正式发布这套流程跑顺之后“你能不能先发个测试环境我看看”这类对话基本消失了。唯一要注意的是预览地址默认可能被搜索引擎收录如果项目敏感记得给预览环境加访问控制或者noindex头别让半成品页面出现在搜索结果里。发布完成之后部署列表里会保留历史版本。真出了线上事故回滚动作是选一个旧版本重新发布通常几十秒内生效。我建议每次大改动前手动记一下当前生产版本的时间戳虽然列表里看得到但事故现场人是慌的有个明确锚点能省不少时间。3.4 绑定自定义域名与证书的几个细节绑定自定义域名这一步流程是把域名加进去、按提示配置 DNS 记录、等状态变成有效。如果域名本来就在同一家解析服务商下通常几条记录自动带出来几乎不用手填跨服务商的话手动加记录注意别和已有的冲突记录打架。证书是自动签发和续期的这块基本不用操心。真正容易出问题的是域名层级和重定向。比如同时绑定example.com和www.example.com最好明确谁是主域名另一个做 301 跳转别让两个都能访问否则搜索引擎会认为是重复内容。跳转用_redirects写就行比在 DNS 层面折腾省事。还有一个经验先绑域名再切流量。正确顺序是把域名加进去、等证书状态正常、用一个测试路径验证解析已经指向新地址最后再改主域名的解析。反过来做的话中间会有一段证书没就绪、访问报错的窗口期用户投诉就来了。我吃过一次这个亏半夜切解析结果证书签发排队白白折腾一小时。4. 进阶能力Functions、重定向与请求头控制4.1 Pages Functions 的目录约定与路由匹配Functions 的用法很“文件即路由”在项目根目录建一个约定好的函数目录里面的文件路径直接映射成 URL 路径。比如functions/api/hello.js对应/api/hellofunctions/users/[id].js里的方括号表示动态参数。这种设计上手成本低缺点是路径和文件结构强绑定重构时要同步挪文件。一个最小的接口长这样// functions/api/hello.js export async function onRequestGet(context) { const { request, env, params } context; const url new URL(request.url); return new Response( JSON.stringify({ ok: true, q: url.searchParams.get(q), ts: Date.now() }), { headers: { content-type: application/json; charsetutf-8 } } ); }几个实操要点。第一按方法导出onRequestGet、onRequestPost比统一用onRequest再自己判断方法更清晰也少写分支。第二中间件放在约定目录下的特定文件名里可以对一批路由统一做鉴权、加头、日志不用每个函数复制一遍。第三环境变量和各类绑定通过env拿密钥不会出现在前端代码里这是用 Functions 代理第三方接口最大的价值。关于路由优先级容易踩的一个坑是静态文件和函数路径重名。比如你既有public/api/hello.json又有functions/api/hello.js实际命中哪个要按规则判断不是凭直觉。我的做法是干脆从源头上避免重叠静态资源放一类前缀接口放另一类前缀别搅在一起。4.2_redirects与_headers的实战写法这两个文件要放在输出目录的根不是源码根目录位置错了不生效这是新手最常见的失误。如果框架会清空输出目录就把它们放在public这类会被原样拷贝的目录里。_redirects的用法是这样# 旧路径迁移保留权重 /old-blog/* /posts/:splat 301 # 反向代理到外部接口 /api/* https://api.example.com/:splat 200 # SPA 兜底放最后 /* /index.html 200三条规则对应三种典型场景。第一条是站点改版后做路径迁移301 让搜索引擎把权重带过去顺序很重要具体规则要写在通配规则前面否则会被兜底规则先吃掉。第二条是反向代理把外部服务挂到同域下省掉跨域配置注意这种方式会消耗函数调用额度。第三条是单页应用的兜底让所有未匹配路径返回首页由前端路由接管——这条必须放最后一行放前面整个站点的静态资源都会被它拦掉。_headers用来给响应加头写法是按路径分组/* X-Frame-Options: DENY X-Content-Type-Options: nosniff Referrer-Policy: strict-origin-when-cross-origin /assets/* Cache-Control: public, max-age31536000, immutable /*.html Cache-Control: public, max-age0, must-revalidate这里体现的就是前面说的缓存思路带哈希的资源长期缓存HTML 每次校验。安全头建议默认加上尤其是X-Content-Type-Options和Referrer-Policy两条加起来成本几乎为零但能挡掉一类低级风险。内容安全策略CSP别一次性写死先观察模式跑一段时间看看有哪些内联脚本和外部资源被拦了再逐步收紧否则很容易把站点自己搞挂。4.3 缓存策略与构建体积优化缓存这块除了响应头还有一层是平台自身的边缘缓存。默认行为对大多数站点够用但在“发布后必须立刻全量生效”的场景下我会给 HTML 明确设置短缓存避免用户看到旧页面里的旧资源引用。体积优化上有两个硬性约束值得记在心里单文件大小上限和单次部署的文件数量上限。前者通常卡在几十 MB 量级后者在两万个文件左右。正常项目很难碰到但如果你把高清图、字体全集、视频素材一股脑塞进产物目录很容易撞墙而且构建时间会明显变长。我的处理方式分三层。第一层图片在构建期处理转成现代格式、按展示尺寸生成多套、懒加载单张图控制在几百 KB 以内。第二层字体做子集化中文字体全集动辄几 MB按实际用到的字符裁剪能压到几十 KB。第三层大文件外置视频、PDF、数据集放对象存储页面里挂链接。做完这三层绝大多数项目能稳稳落在限制之内构建速度也能提上来。另一件事是构建缓存。平台一般会缓存依赖目录让第二次构建跳过重复安装。这个机制是自动的但会被一些写法破坏比如每次构建都强制清缓存重装、或者没有提交锁文件导致依赖树每次都不一样。提交锁文件这件事看起来小实际影响构建稳定性和耗时别嫌它占仓库空间。5. 踩坑实录构建失败、路由 404 与配额问题5.1 构建阶段高频故障排查表我把这些年遇到的构建问题归了类大部分落在下面这张表里。排查顺序建议从下往上——先看日志最后报的错再往回找上下文。现象常见成因处理方式构建命令报“找不到模块”锁文件未提交或依赖装在开发依赖里但构建环境跳过了提交锁文件确认构建命令包含完整安装步骤构建成功但访问 404输出目录填错或产物实际写在别的子目录翻日志找输出文件列表核对目录名构建耗时突然翻倍依赖数量增长或某步做了全量重算检查依赖树把一次性任务挪到本地或缓存提示 Node 版本不兼容未声明版本跟随了镜像默认值显式设置版本环境变量加版本声明文件内存溢出被杀进程打包器并行度太高或处理了大体积资源调低并行度把大文件移出构建链路环境变量读不到变量配在了另一个环境或构建期未注入核对生产/预览两套配置确认变量名拼写关于最后一条有个细节容易忽略前端框架只有在变量名带特定前缀时才会注入到客户端代码。所以你配了变量构建日志里也能读到但浏览器里就是 undefined八成是前缀不对。这个规则各框架不同查一下文档比瞎试快。5.2 页面能打开但资源 404 的三种典型成因这类问题最磨人因为首页是好的肉眼看不出毛病。我总结下来主要三种。第一种是绝对路径问题。项目部署在子路径下时产物里以斜杠开头的资源引用会指到域名根自然 404。解决办法是配置构建时的基础路径或者全程用相对路径引用。判断方法很简单打开开发者工具看请求的资源地址如果少了那层子路径就是这个问题。第二种是大小写不一致。前面提过这里再强调一次因为它在本地几乎不可能复现。构建环境是区分大小写的代码里写Header.js而文件名是header.js本地无感线上直接崩。我现在的做法是在构建流程里加一步检查把所有引用路径和实际文件名做比对早发现早修。第三种是路由和静态文件的冲突。单页应用加了兜底规则之后某些本该返回真实文件比如robots.txt、sitemap.xml、站点验证文件的请求被兜底规则截走了返回的是 HTML浏览器解析失败。处理办法是在兜底规则之前给这些固定路径加显式的放行规则或者把它们放在优先级更高的匹配位置。5.3 配额、上限与成本控制的实操心得免费额度对个人项目基本够用但团队协作时几个点要提前想清楚。构建并发是最容易卡住的地方。免费档通常只允许一个构建同时进行几个人同时推代码就得排队。我的做法是把日常改动攒着一起合减少构建次数紧急修复单独走一次直接部署通道不经过完整流水线。这不是什么高深技巧但能把等待时间从半小时压到几分钟。构建时长也值得盯。有些项目在本地构建五分钟线上要十五分钟原因是构建机性能和缓存命中率不同。如果构建时间持续增长说明有该优化的地方——通常是依赖太多、或某一步在做重复工作。我遇到过一次某插件每次构建都重新下载一份字典文件后来改成构建前预取并缓存时间直接砍掉一半。函数调用次数是另一个容易被忽略的成本项。前面提到的反向代理方案每一次请求都算一次函数调用如果代理的是高频接口量会涨得很快。静态资源走 CDN 不计这部分但任何经过函数的请求都要算。我一般会问自己一句这个接口真的需要实时吗能用构建期生成的就别用函数。注意额度相关的具体数值随时可能调整做容量规划时以官方当前文档为准别拿旧数据做决策。还有一点部署数量也有限制。每次提交都生成一份部署长期高频提交的项目会积累大量历史版本。一般不影响使用但如果要做归档或审计最好自己在外部记一份发布记录标记清楚哪个版本对应哪次上线。6. 横向选型什么场景该选它什么场景该换方案6.1 四类部署方案的对比视角我不太喜欢“哪个最好”这种问法更有意义的是“在我的约束下哪个最省事”。下面这张表是我在做技术选型时会摆出来的对比维度用类别描述具体产品各自去对照。方案类型上手成本预览环境动态能力成本特征适合场景静态托管平台Git 驱动低自带需配套函数服务静态流量成本极低计算按量文档站、博客、营销页、前端应用对象存储 CDN中需自建无存储和流量分开计费大文件分发、资源托管、成本敏感型传统虚拟主机 / 面板低无支持脚本固定月费老项目维护、需要传统运行环境容器化自建高需自建完全自由机器固定成本弹性差复杂后端、需要完全控制运行时从这张表能看出静态托管平台的优势集中在流程内置预览、回滚、证书、缓存策略都有默认答案你少写很多胶水。代价是灵活度受限遇到平台不支持的能力就只能绕。容器化方案的灵活度最高但所有东西都得自己搭包括那套最容易腐化的部署脚本。我的实际组合通常是前端产物走静态托管平台大文件和用户上传走对象存储需要服务端逻辑的部分走函数或独立服务。三者各管一段谁也不越界。这个组合的好处是每层都能单独替换某天要换平台迁移成本是可控的。6.2 迁移时的注意事项与数据可带走性选型时有个问题值得提前问如果哪天要迁走成本有多大这个问题能帮你避开很多坑。静态托管这块迁走的成本其实很低因为产物就是一堆静态文件换个地方重新部署就行。真正需要留意的是平台特有能力的绑定程度。比如你在函数里大量用了某个平台的键值存储、数据库、对象存储绑定迁移时这部分代码得重写。我的做法是把平台特有能力包一层薄薄的适配层业务代码只调适配层将来换实现只改一个文件。这层抽象不用做得太重几十行就够但能救你一次。域名和 DNS 这块也要提前想。如果域名解析也托管在同一家迁移时涉及解析记录的同步切换需要规划一个低峰时段并且提前把新环境的证书和解析都验证好别等到切换当天才发现某条记录没配。还有个小细节重定向和请求头规则是平台私有的格式迁走时不能直接复用得翻译成目标平台的写法。规则不多的话手动改就行规则多的话建议在仓库里维护一份“语义化”的原始清单各平台配置由脚本生成避免以后再次面对一堆散落的配置。最后分享一点个人体会。这类平台最大的价值不是省钱也不是省机器而是把发布这件事从“需要专门操作”变成“代码提交的自然结果”。这个转变一旦发生团队的迭代节奏会明显不一样——小步提交变得自然回滚不再可怕非技术角色也能参与到验收环节里。我自己的几个项目迁过去之后最大的变化不是访问速度而是“改点东西发上去看看”这个动作变得毫无心理负担而这恰恰是大部分项目能持续改进的前提。至于构建排队、产物体积这些限制用久了自然会有感觉提前把锁文件、输出目录、缓存策略这几件事做对剩下的基本都是小问题。
