官方文档里的环境说明
先来看看官方文档是怎么展示构建镜像信息的。下面这两张截图来自 Cloudflare 官方文档，清晰展示了构建系统支持的语言和工具：
第一步：查看构建系统镜像环境
文档页面明确列出了当前构建镜像的默认环境，包括 Node.js、Python、Ruby 等语言的版本信息：
Cloudflare 正在逐步推进 v3 构建镜像，v1 将于 2026 年 9 月 15 日自动迁移，v2 则是 2027 年 2 月 23 日。建议提前适配，避免到时候构建突然炸掉。
第二步：环境变量设置入口
文档还说明了如何通过环境变量或配置文件来覆盖默认版本，这是后续自定义安装的基础：
实战操作：自定义依赖安装
看完文档，接下来进入真正的操作环节。下面是我实际在 Cloudflare Dashboard 上配置的完整流程。
第三步：搜索 Pages 项目
登录 Cloudflare Dashboard，进入 Workers & Pages 页面，搜索你要配置的项目：
第四步：选中目标项目
点击项目名称进入详情页：
第五步：进入已有项目的设置
找到你的 Pages 项目后，点击 Settings（设置）进入配置页面：
如果你是从头新建项目，流程也大同小异，只是在初始化配置阶段就设置好。
第六步：修改环境变量（关键！）
这一步分两个子动作：
6.1 添加 SKIP_DEPENDENCY_INSTALL
新增一个环境变量，Name 填 SKIP_DEPENDENCY_INSTALL，Value 填 1：
6.2 修改构建命令
把原来的构建命令（比如 npm run build）改成你自定义的完整流程 。例如，如果你想用 pnpm 安装依赖并构建：
bash
npm install -g pnpm && pnpm install && pnpm run build或者你项目里有特殊的预安装脚本，也可以一并写进去：
bash
corepack enable && corepack prepare pnpm@latest --activate && pnpm install --frozen-lockfile && pnpm run build
这里的关键思路是：既然跳过了默认安装，那你就要对整条构建链路负责。从包管理器的准备、依赖安装到最终构建，都得自己写清楚。
第七步：重新部署验证
保存配置后，触发一次新的部署。如果一切顺利，构建日志里会显示你自定义的命令被执行，而不是默认的 npm install：
一些踩坑提醒
| 坑点 | 说明 |
|---|---|
| v3 不支持 Node.js codename | 比如 hydrogen 或 lts/hydrogen 这种写法在 v3 构建镜像里不识别，必须写具体版本号 |
| Yarn/pnpm 版本不会自动从 lock 文件检测 | v3 不再根据 yarn.lock 或 pnpm-lock.yaml 推断包管理器版本，必须显式指定 |
| package.json engines 字段被忽略 | 别指望 "engines": { "node": ">=20" } 能生效，还是要靠环境变量或配置文件 |
| pipenv 和 Pipfile 支持已移除 | v3 构建镜像不再支持，Python 项目建议用 requirements.txt 或 Poetry |
什么时候需要自定义安装
不是每个项目都需要这么折腾。以下几种场景比较值得动手：
- 需要特定版本的包管理器：比如项目强制要求 pnpm 9.x，而默认是 10.x
- 需要预安装系统级依赖：某些 npm 包编译时需要系统库，默认环境可能缺
- 构建流程复杂：需要先跑脚本生成代码，再安装依赖，最后构建
- monorepo 场景 ：需要用
pnpm --filter之类的命令精准安装子包依赖 - 迁移旧项目：从 v1/v2 构建镜像迁移到 v3 时，默认行为变了，需要手动锁定版本
总结
Cloudflare Pages 的构建系统远比表面看起来灵活。通过 SKIP_DEPENDENCY_INSTALL 这个环境变量，我们可以完全接管依赖安装过程，配合丰富的语言版本环境变量 和配置文件覆盖机制，几乎能满足各种奇奇怪怪的构建需求。
一言以蔽之：默认流程够用就省事儿，不够用了也有后门可以走------这就是 Cloudflare Pages 构建系统的真实写照。
如果你也在用 Cloudflare Pages 部署项目，建议提前了解一下 官方构建镜像文档，
Cloudflare Pages自定义依赖安装实践
作者：xingwangzhe
本文链接： xingwangzhe.fun/posts/cf-pa...
本文采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。