Cloudflare Pages自定义依赖安装实践

发布时间： 2026-05-15 20:03:36

🕒 阅读时间：3 分钟 📝 字数：1174 👀 阅读量： Loading...

折腾 Cloudflare Pages 的时候，我一度以为它只能跑默认的 npm install，但事实并非如此——Cloudflare Pages 的构建系统其实相当灵活。

官方文档里的环境说明

先来看看官方文档是怎么展示构建镜像信息的。下面这两张截图来自 Cloudflare 官方文档，清晰展示了构建系统支持的语言和工具：

第一步：查看构建系统镜像环境

文档页面明确列出了当前构建镜像的默认环境，包括 Node.js、Python、Ruby 等语言的版本信息：

Cloudflare 正在逐步推进 v3 构建镜像，v1 将于 2026 年 9 月 15 日自动迁移，v2 则是 2027 年 2 月 23 日。建议提前适配，避免到时候构建突然炸掉。

第二步：环境变量设置入口

文档还说明了如何通过环境变量或配置文件来覆盖默认版本，这是后续自定义安装的基础：

实战操作：自定义依赖安装

看完文档，接下来进入真正的操作环节。下面是我实际在 Cloudflare Dashboard 上配置的完整流程。

第三步：搜索 Pages 项目

第四步：选中目标项目

点击项目名称进入详情页：

第五步：进入已有项目的设置

找到你的 Pages 项目后，点击 Settings（设置）进入配置页面：

如果你是从头新建项目，流程也大同小异，只是在初始化配置阶段就设置好。

第六步：修改环境变量（关键！）

这一步分两个子动作：

6.1 添加 `SKIP_DEPENDENCY_INSTALL`

新增一个环境变量，Name 填 SKIP_DEPENDENCY_INSTALL，Value 填 1：

6.2 修改构建命令

把原来的构建命令（比如 npm run build）改成你自定义的完整流程。例如，如果你想用 pnpm 安装依赖并构建：

1
npm install -g pnpm && pnpm install && pnpm run build

或者你项目里有特殊的预安装脚本，也可以一并写进去：

1
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 部署项目，建议提前了解一下官方构建镜像文档，

参考链接