构建配置与预览部署

连接 Git 仓库只是走通部署流程的第一步，真正决定构建能不能成功、产物对不对的，是背后的构建配置。构建命令写错、依赖版本不对、环境变量缺失，任何一个都会让构建挂掉。这一篇把 Pages 构建配置的每一项讲清楚，再讲预览分支和部署别名这两个让团队协作更顺手的特性。

构建配置项总览

Pages 项目的构建配置在仪表盘的项目设置 → 构建和部署里，所有控制项集中在一张表里。

配置项	作用	常见取值
框架预设	自动填好构建命令和输出目录	Vite、Next.js、Hexo、None
构建命令	执行构建的 shell 命令	npm run build、npx hexo generate
构建输出目录	构建产物所在的目录	dist、public、build
根目录	构建执行的根路径，monorepo 时用到	默认为仓库根目录
环境变量	注入到构建过程的变量	API_KEY、NODE_VERSION
构建系统版本	构建环境的基础系统	版本 1、版本 2

框架预设只是辅助填值，最终生效的还是构建命令和输出目录这两项。就算预设识别错了，手动改过来一样能跑。

构建命令就是你在本地打包时执行的那条命令，Pages 把它放到构建环境里跑一遍。输出目录是命令执行完后产物所在的位置，Pages 会把这个目录里的文件全部上传。

常见框架的配置如下。

构建命令留空表示不执行构建，适用于纯静态文件直接上传的场景。输出目录填错是最常见的构建失败原因，明明构建成功了但部署后页面空白，多半是输出目录路径不对。

输出目录支持相对路径，比如 dist 或 build。如果产物在子目录，填 packages/web/dist 这种完整相对路径即可。

很多前端项目构建时需要读取环境变量，比如接口地址、API 密钥、功能开关。Pages 允许你在构建时注入这些变量，分两种类型。

类型	说明	适用场景
明文变量	在仪表盘可见，注入到构建过程	接口地址、公开配置
加密变量	加密存储，设置后不可再查看	API 密钥、私有 Token

设置路径在项目设置 → 环境变量，每个变量还能选择只对生产环境生效、只对预览环境生效、或两者都生效。

环境	何时使用变量
生产环境	推送到生产分支触发的构建
预览环境	推送到非生产分支触发的构建

把生产接口地址和测试接口地址分开注入，就能让预览部署访问测试环境，生产部署访问正式环境，避免用同一套配置导致预览页面打到生产库。

需要特别说明，这些环境变量是构建时注入的，会打包进静态产物，任何能访问站点的人都能在浏览器里看到。真正的敏感数据不要放这里，应该放到 Pages Functions 的运行时环境变量里，这部分后面会讲。

构建环境默认带一个 Node 版本，但很多项目依赖特定版本才能构建成功。Pages 提供三种方式指定 Node 版本，优先级从高到低如下。

最推荐用 .nvmrc 文件，它和本地开发用的 nvm 工具兼容，团队每个人本地和线上构建用的是同一个版本，避免”我这能构建，CI 挂了”的问题。

.nvmrc 文件内容就一行版本号。

18.17.0

也可以只写主版本号，Pages 会用该主版本最新的小版本。

不指定版本时，Pages 用构建系统默认的 Node 版本，这个版本会随平台升级而变化。建议始终显式指定，别让构建依赖一个会变的默认值。

除了 Node，其他运行时也能通过环境变量控制版本，常用的有下面几个。

上一篇已经提到，非生产分支的每次推送都会生成预览部署。实际团队协作中通常会有多个长期存在的功能分支，比如开发分支、测试分支。Pages 允许给特定分支开启预览部署，并配置哪个分支算生产分支。

配置在项目设置 → 构建和部署 → 预览部署里，常见选项如下。

选项	说明
非生产分支部署预览	开关，关闭后非生产分支不再触发构建
生产分支	默认 main 或 master，可改成其他分支

生产分支决定哪次推送会上线到 项目名.pages.dev 这个主域名。如果团队用 production 分支发布，把这里改成 production 即可，推到 main 就只生成预览不再上线。

预览部署的地址格式是 随机哈希.项目名.pages.dev，每次部署哈希都不同。除了哈希地址，还能给分支绑定固定别名，下面讲。

别名就是给某次部署或某个分支起一个好记的固定地址。Pages 支持两类别名。

别名类型	格式	特点
分支别名	分支名.项目名.pages.dev	分支每次部署都更新到同一地址
自定义别名	别名.项目名.pages.dev	手动指定，适合临时演示

分支别名最实用。给 staging 分支绑定别名后，访问 staging.项目名.pages.dev 始终看到的是这个分支的最新部署，不用每次都去仪表盘翻哈希地址。

在仪表盘的某次部署详情页可以手动添加别名，也能用命令行工具 Wrangler（Cloudflare 的命令行开发工具）给指定部署打别名。

npx wrangler pages deployment --branch staging --project-name my-site

日常团队协作靠分支别名就够用了，临时演示地址再手动加。

除了 Git 集成，Pages 还支持直接上传文件部署，不依赖 Git 仓库。适合把一批现成的静态文件快速上线，或者从其他平台迁移历史站点。

两种方式可以上传。

方式	操作
仪表盘拖拽	创建项目时选直接上传，拖文件夹到浏览器
Wrangler 命令	npx wrangler pages deploy ./dist

Wrangler 命令行上传适合写进脚本做自动化，比如本地构建完直接推上去，不必每次走 Git。

npx wrangler pages deploy ./dist --project-name my-site

直接上传的部署没有 Git 提交记录关联，回滚要靠仪表盘的历史部署列表。需要版本管理的项目还是推荐 Git 集成，直接上传只作为补充手段。

到这里构建配置的关键项就讲完了。构建命令和输出目录决定产物，环境变量按环境分离注入，Node 版本用 .nvmrc 锁定，预览分支和部署别名让团队协作更顺畅。下一篇讲自定义域名和重定向规则，让站点用上自己的域名并控制访问路径。