1. 从一次静态站点部署的纠结说起Cloudflare Pages 这个玩意儿我第一次认真用是在给一个前端小项目找落脚点的时候——纯静态产物、没有数据库、没有后台服务就一堆 HTML、JS、CSS 外加几张图片。看着简单真要选个地方放上去麻烦事一堆构建流水线要自己搭每次改一行文案就得重新走一遍上传团队里两个人同时改还得手动合并产物客户要看预览版只能打个压缩包发过去。那阵子我前后试过三种托管方式每种都能跑但每种都有一两处让人别扭的地方直到把项目迁到 Cloudflare Pages 上这套流程才算真正顺下来。Cloudflare Pages 本质上是面向前端产物的托管服务你把代码仓库连上去它按你给的命令跑一次构建把输出目录里的文件推到它分布在全球的边缘节点上然后给你一个可以直接访问的域名。听起来跟其他同类服务差别不大但它把几件事揉在了一起——分支自动生成预览地址、构建产物与函数逻辑放在同一个项目里、静态资源和边缘逻辑共用一套域名与证书配置。适合的人群也很明确写前端但不想碰服务器的人、需要给非技术同事快速看效果的人、想用一份配置文件把静态站和少量后端接口一起管起来的人。哪怕你只会npm run build这一条命令也能在十几分钟内把一个站点跑起来。我用它的这段时间踩过的坑不算少但绝大多数都不是它本身的问题而是我对构建和部署这两个阶段的边界没想清楚。下面就把这套东西从设计思路到实操细节完整拆一遍尽量把每一步为什么这么做讲透让你少走我走过的弯路。2. 整体设计思路与选型拆解2.1 构建产物 边缘分发这条主线用 Pages 之前得先在心里建立一个清晰的模型它管的是产物不管你的源码长什么样。你在代码托管平台上放的是什么框架、用什么包管理器、跑几条构建脚本它都不关心它只关心一件事——你把命令写对之后输出目录里有没有一个可以直接被浏览器读取的文件树。这条主线决定了后面所有的配置项根目录决定它在哪个子目录里执行命令构建命令决定产物怎么生成输出目录决定它去哪里捡文件。这三件事想清楚了剩下的都是锦上添花。这个模型带来的最大好处是产物即契约。本地跑npm run build生成的dist目录和线上跑出来的是同一套东西。我习惯在上线前先把本地构建产物用静态服务器起一遍确认无误再推代码这样能把九成以上的线上白屏问题挡在门外。反过来说如果你的项目依赖了只在特定环境才有的变量或者构建脚本里偷偷读了本地文件那这套模型就会立刻暴露问题——因为它只认命令执行的结果。另一个容易忽略的点是构建和分发是两个独立阶段。构建失败的时候线上还是上一次成功的产物站点不会挂分发阶段出问题比如文件太大、路径大小写不一致你会在部署日志里看到明确的报错。把这两个阶段分开看排查问题的速度会快很多我后面整理的排查表就是按这个顺序组织的。2.2 几类托管方案的横向对照选型这事没有绝对优劣只有场景匹配。我把自己实际用过的几类方案按几个关键维度列了一张表都是我在真实项目里比较在意的点维度Cloudflare Pages对象存储直传自建轻量服务器构建流水线内置连仓库即用需自己写脚本需自己写脚本或搭流水线分支预览地址每个分支自动生成需额外配置需额外配置回滚到历史版本控制台点一下即可需自己管理版本目录靠备份文件麻烦边缘缓存默认内置按文件粒度需手动配缓存策略需自己配 CDN少量接口逻辑同项目内写函数需另找服务自己写服务进程证书与域名绑定域名后自动签发需自行处理需自行续期对象存储直传的优势是便宜、可控、不依赖构建缺点是每次发布都得自己写上传脚本、处理缓存刷新、处理文件删除增量同步很容易留垃圾文件。自建服务器的优势是自由度最高能装任何东西缺点是安全补丁、证书续期、进程守护这些事永远在消耗你的时间。Pages 处在中间它把流水线和分发替你做了代价是你得接受它的一些约定比如构建环境是干净的容器、构建时长和并发次数有配额。我的判断标准很简单——如果这个项目未来半年内不太可能需要长连接或本地磁盘那就别自建。2.3 免费额度的真实边界在哪里很多人上来就问免费额度够不够用我的回答通常是对个人项目和小团队内部站来说绰绰有余对流量型商业站得先算清楚构建次数。写这篇文章时的免费档大致是这样具体数字以控制台和官方文档为准因为这类配额会调整配额项免费档大致量级实际影响每月构建次数数百次提交频繁的项目要留意同时进行的构建1 个多人同时推代码会排队单站点文件数两万级图片多的站要提前规划单文件大小二十几 MiB大视频别往这里放静态请求与流量不单独计量静态站基本不用担心函数请求每天十万级接口调用量大的要注意真正会卡住人的不是流量是构建次数。我有个项目当时把每次推送都触发构建一段时间里提交了几百次小改动配额很快就见底了。后来改成功能分支推代码不构建、合并到主分支才构建配额一下就宽松了。这个细节后面第 6 节会展开。提示配额数字会变动手前先去控制台的用量页面看一眼当期数值别拿旧文章的数字当准绳。3. 核心概念与关键配置要点3.1 构建命令、输出目录与根目录三件套这三个配置项决定了构建能不能跑通我见过的新手问题里至少一半出在这里。根目录是相对仓库根的位置如果你的前端代码在web/子目录里这里就得填web否则它在仓库根执行命令会找不到package.json。构建命令就是你在本地跑的那条命令npm run build、pnpm build、yarn generate都行但要注意包管理器要和仓库里的锁文件一致——仓库里有pnpm-lock.yaml你就别写npm install否则依赖版本可能对不上本地好好的线上炸。输出目录是最容易写错的一个。不同框架的默认产物目录完全不一样有的叫dist有的叫build有的叫public还有的生成到.output/public这种嵌套路径里。我第一次用的时候就填错了构建日志显示成功访问却是一个空白页或者 404折腾了半天才发现文件全在另一个目录。判断方法很简单本地跑一次构建然后看哪个目录里生成了index.html那个目录就是输出目录。注意输出目录填的是相对仓库根或根目录配置的路径不是绝对路径。填/dist这种写法大概率会报错。还有一个隐性坑有些框架默认会把源码也输出到产物目录里或者生成体积很大的 source map。上线前扫一眼产物大小几百 KB 的 JS 是正常的几十 MB 就说明配置有问题先压缩、分包、关掉生产环境的 map再推上去。3.2 环境变量与多环境隔离环境变量这块Pages 的设计思路是按环境分别配置。生产环境和预览环境可以有两套完全不同的变量值这个设计非常实用——你的预览环境可以指向测试接口、测试数据源生产环境指向正式接口两边互不干扰。配置位置在项目的设置页里分生产环境和预览环境两组添加时还可以选择是明文还是加密存储。加密存储这个选项很多人不用我觉得凡是带密钥性质的都该勾上。明文变量在构建日志里可能会被打印出来尤其是你在构建脚本里echo调试的时候而加密变量在任何界面都不会回显原值只能覆盖不能查看。我自己有过一次教训为了排查一个接口地址拼接错误在构建脚本里加了一行打印全部环境变量的命令跑完之后立刻删掉了但那一次日志里已经留下了完整内容。从那以后凡是密钥类的一律加密。变量命名上有个小约定值得遵守前端框架通常只把带特定前缀的变量注入到客户端代码里比如NEXT_PUBLIC_、VITE_这类不带前缀的只在构建阶段可用不会被打包进浏览器。这个机制是保护措施别为了图省事把所有变量都加上前缀等于把自己的密钥明码发到浏览器里。判断标准是这个值如果被任何访客按 F12 看到会不会出问题会就别加前缀。3.3 分支预览与预览地址的用法分支预览是我最喜欢的功能没有之一。你推一个分支上去它自动给这个分支生成一个独立的访问地址指向这次提交的构建产物。产品同事要看效果把链接发过去就行不用等合并、不用手动部署。更妙的是每次往同一个分支推新提交这个地址的内容会自动更新等于一个随代码走的演示环境。实际用的时候有几个细节值得注意。第一预览地址和正式域名是分开的预览地址默认带一段随机子域不要把它当成正式入口发给外部用户。第二如果某个分支你不想让它构建比如纯文档改动、依赖升级的实验分支可以在设置里配置分支包含/排除规则只让特定分支触发构建这是省配额最直接的手段。第三预览环境同样可以绑定自定义域名团队内部站可以给它配一个preview.开头的子域方便记忆。提示把预览地址自动贴在代码评审里做成习惯评审的人点一下就能看到实际效果比看代码 diff 高效得多。我在团队里推这套流程的时候还额外定了一条规矩任何涉及视觉改动的提交必须在描述里附上预览链接和一张关键区域截图。这条规矩执行了几个月之后来回沟通的成本明显下降。3.4 Functions把少量后端逻辑贴在边缘Pages 提供了一层函数能力把接口逻辑和静态产物放在同一个项目里路径以/functions目录为约定。你在functions/api/hello.js里导出一个处理函数它就会响应/api/hello这个路径的请求。这个能力的定位很清楚——处理轻量逻辑读取请求头做重定向、校验一个签名、调用一个外部接口并做一层数据裁剪、给静态页面注入一点动态内容。它不是给你跑长时间任务或者连数据库连接池的。一个最小的处理函数长这样// functions/api/hello.js export async function onRequestGet(context) { const { request, env } context; const url new URL(request.url); const name url.searchParams.get(name) || 访客; return new Response(JSON.stringify({ hello: name }), { headers: { content-type: application/json; charsetutf-8 } }); }env里能拿到你在项目设置里配的环境变量这一点很关键——函数用的变量和构建用的变量是同一套但要注意函数的变量是在运行时读取的改了之后不需要重新构建就能生效这是它和构建期变量最大的区别。我刚开始没意识到这点改完变量还傻等了一次构建。在这里写逻辑有两条经验。一是别把重活放进来单个请求的执行时间是有上限的跑批量数据迁移这种事一定会超时那种任务该放到别的地方。二是做好错误兜底函数抛异常时返回的是通用错误页体验很差我习惯在最外层包一层 try/catch出错时返回一个结构化的 JSON 和合适的状态码。3.5 自定义域名、_headers 与 _redirects绑定自定义域名这一步没什么难度在项目设置里添加域名按提示在域名解析那边加一条记录就行证书会自动签发和续期。需要注意的只有一点如果你同时有根域和www子域建议选一个做正式入口另一个用重定向指过去避免出现两份内容被搜索引擎当成重复页面。真正体现功力的是产物根目录下的两个特殊文件_headers和_redirects。它们不是标准协议的一部分是这套服务认的约定文件放在输出目录根部就会生效。_headers用来给路径批量设置响应头。下面这段是我常用的模板第一段给所有资源加上基础安全头第二段给带哈希的静态资源设置长缓存/* X-Content-Type-Options: nosniff X-Frame-Options: DENY Referrer-Policy: strict-origin-when-cross-origin /assets/* Cache-Control: public, max-age31536000, immutable_redirects用来做跳转和单页应用的路由回退。单页应用刷新子路由会 404这是最常见的抱怨加一行规则就解决了/old-page /new-page 301 /* /index.html 200注意最后这条是 200 而不是 301意思是内部返回 index.html 但地址栏不变这是单页应用回退的标准写法。写成 301 会让所有子路由都跳到首页地址用户体验直接崩掉。这个坑我踩过一次当时还以为是前端路由配置写错了。_headers里还有一个实用技巧给特定路径单独设置缓存策略。带内容哈希的构建产物文件名里有一串随机字符可以设一年缓存并标记为不可变HTML 入口文件则要设短缓存甚至不缓存否则用户会一直看到旧页面。这个入口短缓存、资源长缓存的组合是所有静态站缓存策略的通用套路。4. 从零上线一个项目的完整实操4.1 上线前本地自检我现在的习惯是任何项目上线前先在本地把构建产物当成品跑一遍而不是只跑开发服务器。开发服务器和构建产物之间的差异比想象中大环境变量注入方式不同、代码压缩可能引入问题、静态资源路径在生产模式下可能变成绝对路径。具体操作就是构建完之后在产物目录下起一个本地静态服务器看一眼。npm run build npx serve ./dist打开提示的地址把主要页面点一遍重点看三处首屏样式有没有加载、控制台有没有报错、刷新一个子路由会不会 404。第三点尤其重要很多人只在开发服务器里点链接从来没试过直接刷新子路由上线之后才发现需要配回退规则。这一步还有个小作用能提前发现产物体积异常。我有个项目本地构建出来单文件三十多 MB原因是把一个数据文件当模块引入了构建工具把它整个打进了主包。这种问题在开发服务器上看不出来在构建产物上一眼就能发现。4.2 Git 集成方式的操作步骤这是最省心的接入方式适合长期维护的项目。思路是把代码托管平台上的仓库授权给 Pages之后每次推送自动触发构建。落地步骤大致如下在控制台新建项目选择连接代码仓库按提示完成授权选中目标仓库。选择要跟踪的分支通常是主分支这一条决定了哪些分支的提交会产出正式版本。填写根目录、构建命令、输出目录三项也就是 3.1 节说的三件套。展开环境变量区域把生产和预览两套变量分别填好密钥类勾选加密。点保存并触发首次构建盯着日志从头看到尾。第一次构建我建议逐行看日志别只看最后那个成功标记。日志里会告诉你实际用的运行时版本、装了哪些依赖、产物有多少个文件。我曾经因为在仓库里放了一个.nvmrc指定了一个较老的运行时版本导致构建工具报语法错误而报错信息出现在日志很靠前的位置只看结尾根本发现不了。4.3 命令行直传方式与 wrangler 配置有些场景不适合连仓库产物是本地生成的、你在做一次性迁移、或者你想在流水线里手动控制发布时机。这时候用官方提供的命令行工具直传更方便。项目里放一个配置文件把项目名、产物目录、兼容日期写清楚# wrangler.toml name demo-site pages_build_output_dir ./dist compatibility_date 2024-09-01然后在本地执行npx wrangler pages deploy ./dist --project-namedemo-site --branchmain--branch这个参数决定了这次部署算正式版还是预览版。用main之类的正式分支名就是生产部署用别的名字就是预览部署会生成独立地址。这个机制在手动发版时特别有用想先给别人看一眼就用一个临时分支名传上去确认没问题再传一次正式分支。本地调试函数也在这个工具里npx wrangler pages dev ./dist它会起一个本地服务把functions目录下的逻辑一起挂上行为和线上接近。我一般改函数之后先在这里验证省得反复推代码。注意命令行直传不会触发构建你传什么上去就是什么。所以本地一定要先构建好、验证好别把开发模式的产物传上去。4.4 上线后的验收清单部署完成不代表事情结束我有一套固定的验收动作五分钟左右能走完能挡掉绝大多数线上事故检查项怎么看不合格的表现首屏渲染无痕窗口打开首页白屏、样式缺失子路由刷新直接在子路由地址上按刷新返回 404资源缓存头开发者工具看响应头HTML 被设了长缓存环境变量页面里展示的接口地址指向了测试环境函数响应直接访问接口路径返回通用错误页移动端手机或模拟器打开布局错乱、点击区域过小我特别强调无痕窗口这一步。普通窗口里可能有旧缓存、有登录态、有扩展注入的脚本很多问题在普通窗口里根本复现不出来。我有一次线上样式错乱折腾了半小时最后发现是自己浏览器缓存了旧的 CSS 文件无痕窗口一开就是好的。5. 常见问题与排查技巧实录5.1 构建阶段的失败构建失败的原因高度集中在三类。第一类是依赖装不上锁文件和包管理器不匹配、私有依赖没配访问凭据、某个包在构建环境里没有对应的二进制版本。这类问题的特征是日志里明确出现ERR或not found处理办法是按日志提示改配置实在不行就在本地用干净的目录重新装一遍复现。第二类是命令执行出错比如构建脚本里引用了某个只在本地存在的文件、或者用了只有本地才装的全局命令。构建环境是一个干净容器你本地全局装的工具它没有所以任何构建依赖都必须写进项目的依赖声明里。我遇到过一次本地因为之前装过某个格式化工具所以能跑线上直接报命令不存在最后把那工具加进了开发依赖。第三类是资源超限单文件太大、文件总数太多、构建时间太长。这类问题的日志往往不够直白需要你自己核对产物。处理思路是拆分和裁剪——大图做压缩和按需加载把不必要的东西从产物目录里移出去关掉生产环境的 source map。5.2 路由与 404 的典型症状404 是这套东西上用起来最容易撞的问题但症状不同原因完全不同得分清楚首页正常子路由直接访问 404缺单页应用回退规则加/* /index.html 200。首页正常某个具体路径 404 但文件明明在文件名大小写不一致。本地文件系统不区分大小写线上区分About.js被引用成about.js就找不到。所有页面都 404但日志显示构建成功输出目录填错了它去空目录里捡文件。资源请求 404页面结构还在但没样式静态资源的基础路径配置有问题检查构建配置里的 base 路径。大小写这个问题我被坑过两次现在处理办法很土但有效在本地做一次全量检查把所有引用路径和实际文件名对一遍。更省事的做法是在项目里加一条提交前检查专门查这个。5.3 缓存与更新延迟我明明改了怎么还是旧的——这个问题分两种情况。第一种是浏览器缓存用户本地存了旧文件。解决办法不是让用户清缓存而是从一开始就把缓存策略设计对入口 HTML 短缓存带哈希的资源长缓存。这样用户每次拿到的都是新的入口文件入口里引用的资源哈希也变了自然就拿到新资源。第二种是你看到的确实是旧版本部署本身没生效。判断方法很简单看部署记录里的时间戳和提交号对不上的话就是构建没触发或者触发了但失败了。构建失败时线上仍然是上一次成功的产物这个设计是好事但也会让人误以为改了没生效。还有一种更隐蔽的情况文件内容变了但文件名没变缓存策略又设了长缓存用户就一直拿旧的。这正是带哈希的文件名存在的意义——内容一变哈希就变文件名就变缓存自然失效。如果你用的构建工具没做这个得手动配。5.4 问题速查表把上面这些整理成一张表出问题的时候按顺序对一遍比漫无目的地翻日志快得多症状最可能原因第一步动作构建失败依赖相关报错包管理器与锁文件不一致统一命令与锁文件构建失败命令不存在依赖未写进项目补进开发依赖部署成功但首页 404输出目录配置错误核对产物目录层级子路由刷新 404缺回退规则加_redirects规则部分资源 404路径大小写不一致逐条比对引用路径改了内容不生效入口文件被长缓存调整_headers策略函数返回通用错误页逻辑抛异常未兜底加 try/catch 与状态码函数读不到变量变量配在构建环境未配运行时检查环境变量分组提示排查顺序建议固定为部署记录 → 构建日志 → 产物目录 → 响应头 → 页面控制台。从上游往下游查比一上来就怀疑代码有效得多。6. 成本控制与工程化的一点经验6.1 构建次数是怎么被消耗掉的配额里最先见底的通常是构建次数而消耗它的往往不是代码改得多是触发得太随意。我梳理过自己一个月的构建记录接近四成是文档改动、README 更新、依赖版本试探这类完全不需要构建的提交。找到这个规律之后我做了两件事一是配了分支过滤规则只让主分支和feature/*触发构建docs/*这类分支直接不构建二是把一些频繁的小改动攒一攒再推。还有一个容易忽略的点是同时进行的构建数量。免费档通常只允许一个构建同时跑多人同时推代码就会排队排在后面的等得久很容易让人误以为卡住了。团队里我的做法是约定主干合并的时间窗口避免几个人同时往主分支推。真正需要每次提交都构建的项目其实不多。判断标准是这次构建的产物会不会有人看如果答案是不会那这次构建就是纯消耗。6.2 预览环境保护与团队协作预览环境默认是公开可访问的这一点很多人在接外部客户项目时会忽略。如果你的预览版本里有未发布的文案、测试数据、内部链接直接发个地址出去是有风险的。处理办法有两层一是利用访问控制能力把预览环境限制在团队范围内二是在预览构建里注入一套测试数据环境变量让预览版本本身就不含真实内容。我在团队里还加了一条约定预览地址的命名要能看出用途。默认生成的随机子域很难辨认我们统一用一个固定前缀加上分支名这样几十个预览地址挂在书签栏里也不至于搞混。同时约定预览环境不绑定正式域名避免有人误把它当成正式入口分享出去。团队协作上还有个小技巧值得分享把构建状态和预览链接接进日常沟通流程。我们用的方式是在代码评审的模板里固定留一栏预览地址提交时填上评审的人点开就能看到实际效果。这个动作看起来只是省了一次复制粘贴实际效果是让看效果变成了评审的默认环节而不是可选项。这套东西用到现在我最大的体会是它把部署从一个需要专门安排时间的事变成了一个顺手就完成的事。真正的门槛不在工具本身而在于你有没有把构建命令、输出目录、环境变量这三件事想清楚以及有没有把缓存策略和路由回退这些细节提前配好。这些地方花半小时配一次后面能省下几十次排查。最后再分享一个我一直在用的小习惯每个项目的产物根目录里放一个简单的说明文件写清楚构建命令、输出目录、特殊配置文件的用途隔三个月再回来改的时候这份说明能救你不少时间。
1. 从一次静态站点部署的纠结说起Cloudflare Pages 这个玩意儿我第一次认真用是在给一个前端小项目找落脚点的时候——纯静态产物、没有数据库、没有后台服务就一堆 HTML、JS、CSS 外加几张图片。看着简单真要选个地方放上去麻烦事一堆构建流水线要自己搭每次改一行文案就得重新走一遍上传团队里两个人同时改还得手动合并产物客户要看预览版只能打个压缩包发过去。那阵子我前后试过三种托管方式每种都能跑但每种都有一两处让人别扭的地方直到把项目迁到 Cloudflare Pages 上这套流程才算真正顺下来。Cloudflare Pages 本质上是面向前端产物的托管服务你把代码仓库连上去它按你给的命令跑一次构建把输出目录里的文件推到它分布在全球的边缘节点上然后给你一个可以直接访问的域名。听起来跟其他同类服务差别不大但它把几件事揉在了一起——分支自动生成预览地址、构建产物与函数逻辑放在同一个项目里、静态资源和边缘逻辑共用一套域名与证书配置。适合的人群也很明确写前端但不想碰服务器的人、需要给非技术同事快速看效果的人、想用一份配置文件把静态站和少量后端接口一起管起来的人。哪怕你只会npm run build这一条命令也能在十几分钟内把一个站点跑起来。我用它的这段时间踩过的坑不算少但绝大多数都不是它本身的问题而是我对构建和部署这两个阶段的边界没想清楚。下面就把这套东西从设计思路到实操细节完整拆一遍尽量把每一步为什么这么做讲透让你少走我走过的弯路。2. 整体设计思路与选型拆解2.1 构建产物 边缘分发这条主线用 Pages 之前得先在心里建立一个清晰的模型它管的是产物不管你的源码长什么样。你在代码托管平台上放的是什么框架、用什么包管理器、跑几条构建脚本它都不关心它只关心一件事——你把命令写对之后输出目录里有没有一个可以直接被浏览器读取的文件树。这条主线决定了后面所有的配置项根目录决定它在哪个子目录里执行命令构建命令决定产物怎么生成输出目录决定它去哪里捡文件。这三件事想清楚了剩下的都是锦上添花。这个模型带来的最大好处是产物即契约。本地跑npm run build生成的dist目录和线上跑出来的是同一套东西。我习惯在上线前先把本地构建产物用静态服务器起一遍确认无误再推代码这样能把九成以上的线上白屏问题挡在门外。反过来说如果你的项目依赖了只在特定环境才有的变量或者构建脚本里偷偷读了本地文件那这套模型就会立刻暴露问题——因为它只认命令执行的结果。另一个容易忽略的点是构建和分发是两个独立阶段。构建失败的时候线上还是上一次成功的产物站点不会挂分发阶段出问题比如文件太大、路径大小写不一致你会在部署日志里看到明确的报错。把这两个阶段分开看排查问题的速度会快很多我后面整理的排查表就是按这个顺序组织的。2.2 几类托管方案的横向对照选型这事没有绝对优劣只有场景匹配。我把自己实际用过的几类方案按几个关键维度列了一张表都是我在真实项目里比较在意的点维度Cloudflare Pages对象存储直传自建轻量服务器构建流水线内置连仓库即用需自己写脚本需自己写脚本或搭流水线分支预览地址每个分支自动生成需额外配置需额外配置回滚到历史版本控制台点一下即可需自己管理版本目录靠备份文件麻烦边缘缓存默认内置按文件粒度需手动配缓存策略需自己配 CDN少量接口逻辑同项目内写函数需另找服务自己写服务进程证书与域名绑定域名后自动签发需自行处理需自行续期对象存储直传的优势是便宜、可控、不依赖构建缺点是每次发布都得自己写上传脚本、处理缓存刷新、处理文件删除增量同步很容易留垃圾文件。自建服务器的优势是自由度最高能装任何东西缺点是安全补丁、证书续期、进程守护这些事永远在消耗你的时间。Pages 处在中间它把流水线和分发替你做了代价是你得接受它的一些约定比如构建环境是干净的容器、构建时长和并发次数有配额。我的判断标准很简单——如果这个项目未来半年内不太可能需要长连接或本地磁盘那就别自建。2.3 免费额度的真实边界在哪里很多人上来就问免费额度够不够用我的回答通常是对个人项目和小团队内部站来说绰绰有余对流量型商业站得先算清楚构建次数。写这篇文章时的免费档大致是这样具体数字以控制台和官方文档为准因为这类配额会调整配额项免费档大致量级实际影响每月构建次数数百次提交频繁的项目要留意同时进行的构建1 个多人同时推代码会排队单站点文件数两万级图片多的站要提前规划单文件大小二十几 MiB大视频别往这里放静态请求与流量不单独计量静态站基本不用担心函数请求每天十万级接口调用量大的要注意真正会卡住人的不是流量是构建次数。我有个项目当时把每次推送都触发构建一段时间里提交了几百次小改动配额很快就见底了。后来改成功能分支推代码不构建、合并到主分支才构建配额一下就宽松了。这个细节后面第 6 节会展开。提示配额数字会变动手前先去控制台的用量页面看一眼当期数值别拿旧文章的数字当准绳。3. 核心概念与关键配置要点3.1 构建命令、输出目录与根目录三件套这三个配置项决定了构建能不能跑通我见过的新手问题里至少一半出在这里。根目录是相对仓库根的位置如果你的前端代码在web/子目录里这里就得填web否则它在仓库根执行命令会找不到package.json。构建命令就是你在本地跑的那条命令npm run build、pnpm build、yarn generate都行但要注意包管理器要和仓库里的锁文件一致——仓库里有pnpm-lock.yaml你就别写npm install否则依赖版本可能对不上本地好好的线上炸。输出目录是最容易写错的一个。不同框架的默认产物目录完全不一样有的叫dist有的叫build有的叫public还有的生成到.output/public这种嵌套路径里。我第一次用的时候就填错了构建日志显示成功访问却是一个空白页或者 404折腾了半天才发现文件全在另一个目录。判断方法很简单本地跑一次构建然后看哪个目录里生成了index.html那个目录就是输出目录。注意输出目录填的是相对仓库根或根目录配置的路径不是绝对路径。填/dist这种写法大概率会报错。还有一个隐性坑有些框架默认会把源码也输出到产物目录里或者生成体积很大的 source map。上线前扫一眼产物大小几百 KB 的 JS 是正常的几十 MB 就说明配置有问题先压缩、分包、关掉生产环境的 map再推上去。3.2 环境变量与多环境隔离环境变量这块Pages 的设计思路是按环境分别配置。生产环境和预览环境可以有两套完全不同的变量值这个设计非常实用——你的预览环境可以指向测试接口、测试数据源生产环境指向正式接口两边互不干扰。配置位置在项目的设置页里分生产环境和预览环境两组添加时还可以选择是明文还是加密存储。加密存储这个选项很多人不用我觉得凡是带密钥性质的都该勾上。明文变量在构建日志里可能会被打印出来尤其是你在构建脚本里echo调试的时候而加密变量在任何界面都不会回显原值只能覆盖不能查看。我自己有过一次教训为了排查一个接口地址拼接错误在构建脚本里加了一行打印全部环境变量的命令跑完之后立刻删掉了但那一次日志里已经留下了完整内容。从那以后凡是密钥类的一律加密。变量命名上有个小约定值得遵守前端框架通常只把带特定前缀的变量注入到客户端代码里比如NEXT_PUBLIC_、VITE_这类不带前缀的只在构建阶段可用不会被打包进浏览器。这个机制是保护措施别为了图省事把所有变量都加上前缀等于把自己的密钥明码发到浏览器里。判断标准是这个值如果被任何访客按 F12 看到会不会出问题会就别加前缀。3.3 分支预览与预览地址的用法分支预览是我最喜欢的功能没有之一。你推一个分支上去它自动给这个分支生成一个独立的访问地址指向这次提交的构建产物。产品同事要看效果把链接发过去就行不用等合并、不用手动部署。更妙的是每次往同一个分支推新提交这个地址的内容会自动更新等于一个随代码走的演示环境。实际用的时候有几个细节值得注意。第一预览地址和正式域名是分开的预览地址默认带一段随机子域不要把它当成正式入口发给外部用户。第二如果某个分支你不想让它构建比如纯文档改动、依赖升级的实验分支可以在设置里配置分支包含/排除规则只让特定分支触发构建这是省配额最直接的手段。第三预览环境同样可以绑定自定义域名团队内部站可以给它配一个preview.开头的子域方便记忆。提示把预览地址自动贴在代码评审里做成习惯评审的人点一下就能看到实际效果比看代码 diff 高效得多。我在团队里推这套流程的时候还额外定了一条规矩任何涉及视觉改动的提交必须在描述里附上预览链接和一张关键区域截图。这条规矩执行了几个月之后来回沟通的成本明显下降。3.4 Functions把少量后端逻辑贴在边缘Pages 提供了一层函数能力把接口逻辑和静态产物放在同一个项目里路径以/functions目录为约定。你在functions/api/hello.js里导出一个处理函数它就会响应/api/hello这个路径的请求。这个能力的定位很清楚——处理轻量逻辑读取请求头做重定向、校验一个签名、调用一个外部接口并做一层数据裁剪、给静态页面注入一点动态内容。它不是给你跑长时间任务或者连数据库连接池的。一个最小的处理函数长这样// functions/api/hello.js export async function onRequestGet(context) { const { request, env } context; const url new URL(request.url); const name url.searchParams.get(name) || 访客; return new Response(JSON.stringify({ hello: name }), { headers: { content-type: application/json; charsetutf-8 } }); }env里能拿到你在项目设置里配的环境变量这一点很关键——函数用的变量和构建用的变量是同一套但要注意函数的变量是在运行时读取的改了之后不需要重新构建就能生效这是它和构建期变量最大的区别。我刚开始没意识到这点改完变量还傻等了一次构建。在这里写逻辑有两条经验。一是别把重活放进来单个请求的执行时间是有上限的跑批量数据迁移这种事一定会超时那种任务该放到别的地方。二是做好错误兜底函数抛异常时返回的是通用错误页体验很差我习惯在最外层包一层 try/catch出错时返回一个结构化的 JSON 和合适的状态码。3.5 自定义域名、_headers 与 _redirects绑定自定义域名这一步没什么难度在项目设置里添加域名按提示在域名解析那边加一条记录就行证书会自动签发和续期。需要注意的只有一点如果你同时有根域和www子域建议选一个做正式入口另一个用重定向指过去避免出现两份内容被搜索引擎当成重复页面。真正体现功力的是产物根目录下的两个特殊文件_headers和_redirects。它们不是标准协议的一部分是这套服务认的约定文件放在输出目录根部就会生效。_headers用来给路径批量设置响应头。下面这段是我常用的模板第一段给所有资源加上基础安全头第二段给带哈希的静态资源设置长缓存/* X-Content-Type-Options: nosniff X-Frame-Options: DENY Referrer-Policy: strict-origin-when-cross-origin /assets/* Cache-Control: public, max-age31536000, immutable_redirects用来做跳转和单页应用的路由回退。单页应用刷新子路由会 404这是最常见的抱怨加一行规则就解决了/old-page /new-page 301 /* /index.html 200注意最后这条是 200 而不是 301意思是内部返回 index.html 但地址栏不变这是单页应用回退的标准写法。写成 301 会让所有子路由都跳到首页地址用户体验直接崩掉。这个坑我踩过一次当时还以为是前端路由配置写错了。_headers里还有一个实用技巧给特定路径单独设置缓存策略。带内容哈希的构建产物文件名里有一串随机字符可以设一年缓存并标记为不可变HTML 入口文件则要设短缓存甚至不缓存否则用户会一直看到旧页面。这个入口短缓存、资源长缓存的组合是所有静态站缓存策略的通用套路。4. 从零上线一个项目的完整实操4.1 上线前本地自检我现在的习惯是任何项目上线前先在本地把构建产物当成品跑一遍而不是只跑开发服务器。开发服务器和构建产物之间的差异比想象中大环境变量注入方式不同、代码压缩可能引入问题、静态资源路径在生产模式下可能变成绝对路径。具体操作就是构建完之后在产物目录下起一个本地静态服务器看一眼。npm run build npx serve ./dist打开提示的地址把主要页面点一遍重点看三处首屏样式有没有加载、控制台有没有报错、刷新一个子路由会不会 404。第三点尤其重要很多人只在开发服务器里点链接从来没试过直接刷新子路由上线之后才发现需要配回退规则。这一步还有个小作用能提前发现产物体积异常。我有个项目本地构建出来单文件三十多 MB原因是把一个数据文件当模块引入了构建工具把它整个打进了主包。这种问题在开发服务器上看不出来在构建产物上一眼就能发现。4.2 Git 集成方式的操作步骤这是最省心的接入方式适合长期维护的项目。思路是把代码托管平台上的仓库授权给 Pages之后每次推送自动触发构建。落地步骤大致如下在控制台新建项目选择连接代码仓库按提示完成授权选中目标仓库。选择要跟踪的分支通常是主分支这一条决定了哪些分支的提交会产出正式版本。填写根目录、构建命令、输出目录三项也就是 3.1 节说的三件套。展开环境变量区域把生产和预览两套变量分别填好密钥类勾选加密。点保存并触发首次构建盯着日志从头看到尾。第一次构建我建议逐行看日志别只看最后那个成功标记。日志里会告诉你实际用的运行时版本、装了哪些依赖、产物有多少个文件。我曾经因为在仓库里放了一个.nvmrc指定了一个较老的运行时版本导致构建工具报语法错误而报错信息出现在日志很靠前的位置只看结尾根本发现不了。4.3 命令行直传方式与 wrangler 配置有些场景不适合连仓库产物是本地生成的、你在做一次性迁移、或者你想在流水线里手动控制发布时机。这时候用官方提供的命令行工具直传更方便。项目里放一个配置文件把项目名、产物目录、兼容日期写清楚# wrangler.toml name demo-site pages_build_output_dir ./dist compatibility_date 2024-09-01然后在本地执行npx wrangler pages deploy ./dist --project-namedemo-site --branchmain--branch这个参数决定了这次部署算正式版还是预览版。用main之类的正式分支名就是生产部署用别的名字就是预览部署会生成独立地址。这个机制在手动发版时特别有用想先给别人看一眼就用一个临时分支名传上去确认没问题再传一次正式分支。本地调试函数也在这个工具里npx wrangler pages dev ./dist它会起一个本地服务把functions目录下的逻辑一起挂上行为和线上接近。我一般改函数之后先在这里验证省得反复推代码。注意命令行直传不会触发构建你传什么上去就是什么。所以本地一定要先构建好、验证好别把开发模式的产物传上去。4.4 上线后的验收清单部署完成不代表事情结束我有一套固定的验收动作五分钟左右能走完能挡掉绝大多数线上事故检查项怎么看不合格的表现首屏渲染无痕窗口打开首页白屏、样式缺失子路由刷新直接在子路由地址上按刷新返回 404资源缓存头开发者工具看响应头HTML 被设了长缓存环境变量页面里展示的接口地址指向了测试环境函数响应直接访问接口路径返回通用错误页移动端手机或模拟器打开布局错乱、点击区域过小我特别强调无痕窗口这一步。普通窗口里可能有旧缓存、有登录态、有扩展注入的脚本很多问题在普通窗口里根本复现不出来。我有一次线上样式错乱折腾了半小时最后发现是自己浏览器缓存了旧的 CSS 文件无痕窗口一开就是好的。5. 常见问题与排查技巧实录5.1 构建阶段的失败构建失败的原因高度集中在三类。第一类是依赖装不上锁文件和包管理器不匹配、私有依赖没配访问凭据、某个包在构建环境里没有对应的二进制版本。这类问题的特征是日志里明确出现ERR或not found处理办法是按日志提示改配置实在不行就在本地用干净的目录重新装一遍复现。第二类是命令执行出错比如构建脚本里引用了某个只在本地存在的文件、或者用了只有本地才装的全局命令。构建环境是一个干净容器你本地全局装的工具它没有所以任何构建依赖都必须写进项目的依赖声明里。我遇到过一次本地因为之前装过某个格式化工具所以能跑线上直接报命令不存在最后把那工具加进了开发依赖。第三类是资源超限单文件太大、文件总数太多、构建时间太长。这类问题的日志往往不够直白需要你自己核对产物。处理思路是拆分和裁剪——大图做压缩和按需加载把不必要的东西从产物目录里移出去关掉生产环境的 source map。5.2 路由与 404 的典型症状404 是这套东西上用起来最容易撞的问题但症状不同原因完全不同得分清楚首页正常子路由直接访问 404缺单页应用回退规则加/* /index.html 200。首页正常某个具体路径 404 但文件明明在文件名大小写不一致。本地文件系统不区分大小写线上区分About.js被引用成about.js就找不到。所有页面都 404但日志显示构建成功输出目录填错了它去空目录里捡文件。资源请求 404页面结构还在但没样式静态资源的基础路径配置有问题检查构建配置里的 base 路径。大小写这个问题我被坑过两次现在处理办法很土但有效在本地做一次全量检查把所有引用路径和实际文件名对一遍。更省事的做法是在项目里加一条提交前检查专门查这个。5.3 缓存与更新延迟我明明改了怎么还是旧的——这个问题分两种情况。第一种是浏览器缓存用户本地存了旧文件。解决办法不是让用户清缓存而是从一开始就把缓存策略设计对入口 HTML 短缓存带哈希的资源长缓存。这样用户每次拿到的都是新的入口文件入口里引用的资源哈希也变了自然就拿到新资源。第二种是你看到的确实是旧版本部署本身没生效。判断方法很简单看部署记录里的时间戳和提交号对不上的话就是构建没触发或者触发了但失败了。构建失败时线上仍然是上一次成功的产物这个设计是好事但也会让人误以为改了没生效。还有一种更隐蔽的情况文件内容变了但文件名没变缓存策略又设了长缓存用户就一直拿旧的。这正是带哈希的文件名存在的意义——内容一变哈希就变文件名就变缓存自然失效。如果你用的构建工具没做这个得手动配。5.4 问题速查表把上面这些整理成一张表出问题的时候按顺序对一遍比漫无目的地翻日志快得多症状最可能原因第一步动作构建失败依赖相关报错包管理器与锁文件不一致统一命令与锁文件构建失败命令不存在依赖未写进项目补进开发依赖部署成功但首页 404输出目录配置错误核对产物目录层级子路由刷新 404缺回退规则加_redirects规则部分资源 404路径大小写不一致逐条比对引用路径改了内容不生效入口文件被长缓存调整_headers策略函数返回通用错误页逻辑抛异常未兜底加 try/catch 与状态码函数读不到变量变量配在构建环境未配运行时检查环境变量分组提示排查顺序建议固定为部署记录 → 构建日志 → 产物目录 → 响应头 → 页面控制台。从上游往下游查比一上来就怀疑代码有效得多。6. 成本控制与工程化的一点经验6.1 构建次数是怎么被消耗掉的配额里最先见底的通常是构建次数而消耗它的往往不是代码改得多是触发得太随意。我梳理过自己一个月的构建记录接近四成是文档改动、README 更新、依赖版本试探这类完全不需要构建的提交。找到这个规律之后我做了两件事一是配了分支过滤规则只让主分支和feature/*触发构建docs/*这类分支直接不构建二是把一些频繁的小改动攒一攒再推。还有一个容易忽略的点是同时进行的构建数量。免费档通常只允许一个构建同时跑多人同时推代码就会排队排在后面的等得久很容易让人误以为卡住了。团队里我的做法是约定主干合并的时间窗口避免几个人同时往主分支推。真正需要每次提交都构建的项目其实不多。判断标准是这次构建的产物会不会有人看如果答案是不会那这次构建就是纯消耗。6.2 预览环境保护与团队协作预览环境默认是公开可访问的这一点很多人在接外部客户项目时会忽略。如果你的预览版本里有未发布的文案、测试数据、内部链接直接发个地址出去是有风险的。处理办法有两层一是利用访问控制能力把预览环境限制在团队范围内二是在预览构建里注入一套测试数据环境变量让预览版本本身就不含真实内容。我在团队里还加了一条约定预览地址的命名要能看出用途。默认生成的随机子域很难辨认我们统一用一个固定前缀加上分支名这样几十个预览地址挂在书签栏里也不至于搞混。同时约定预览环境不绑定正式域名避免有人误把它当成正式入口分享出去。团队协作上还有个小技巧值得分享把构建状态和预览链接接进日常沟通流程。我们用的方式是在代码评审的模板里固定留一栏预览地址提交时填上评审的人点开就能看到实际效果。这个动作看起来只是省了一次复制粘贴实际效果是让看效果变成了评审的默认环节而不是可选项。这套东西用到现在我最大的体会是它把部署从一个需要专门安排时间的事变成了一个顺手就完成的事。真正的门槛不在工具本身而在于你有没有把构建命令、输出目录、环境变量这三件事想清楚以及有没有把缓存策略和路由回退这些细节提前配好。这些地方花半小时配一次后面能省下几十次排查。最后再分享一个我一直在用的小习惯每个项目的产物根目录里放一个简单的说明文件写清楚构建命令、输出目录、特殊配置文件的用途隔三个月再回来改的时候这份说明能救你不少时间。
