构建镜像

Cloudflare Pages 的构建环境广泛支持多种语言，例如 Ruby、Node.js、Python、PHP 和 Go。

若需使用特定版本的语言（例如 Node.js 或 Ruby），可在构建配置中提供相应的环境变量，或在源代码中设置相关文件。

在下表中，查看 Cloudflare Pages 构建镜像中预装的语言和工具版本，以及可用于覆盖预装版本的环境变量和/或文件：

要使用框架的特定版本，请在项目的包管理器配置文件中指定。 例如，若使用 Gatsby，package.json 应包含以下内容：

"dependencies": {
	"gatsby": "^5.13.7",
}

构建开始时，若尚未缓存，将通过 npm install 安装 Gatsby 5.13.7 版本。

要覆盖构建系统中语言和工具的默认版本，可通过环境变量设置所需版本，或在项目中添加文件。

通过环境变量设置版本的步骤：

1. 在此表中查找语言或工具的环境变量名称。
2. 在仪表板中为 Pages 项目前往 Settings（设置） > Environment variables（环境变量） 添加环境变量，或通过 Wrangler 添加环境变量。

或通过向项目添加文件来设置版本：

1. 在此表中查找语言或工具的文件名。
2. 在项目根目录添加指定文件名，并将所需版本号作为文件内容。

例如，若你之前依赖 v1 构建系统中 Node.js 的默认版本，迁移到 v2 时必须指定 Node.js 12.18.0，可通过设置 NODE_VERSION = 12.18.0 环境变量，或在项目中添加 .node-version 或 .nvmrc 文件并将 12.18.0 作为内容。

你可以添加以下环境变量以禁用自动依赖安装，并改为运行自定义安装命令。

v3 构建系统将默认工具、库和语言更新为截至 2025 年 5 月的 LTS 版本。

要在仪表板中配置 Pages 项目设置以迁移到新版本：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Pages 项目。

3. 前往 Deployments（部署） > All deployments（所有部署），并选择最新版本。

若你之前依赖构建系统中任何语言或工具的默认版本，迁移到 v3 时构建可能会失败。要解决此问题，必须通过覆盖默认版本来指定要使用的版本。

使用 v3 构建系统时，目前不支持以下功能：

• 将 Node.js 版本指定为代号（例如 hydrogen 或 lts/hydrogen）。
• 从 yarn.lock 文件版本检测 Yarn 版本。
• 根据 pnpm-lock.yaml 文件版本检测 pnpm 版本。
• 从 package.json -> "engines" 检测 Node.js 和包管理器。
• pipenv 和 Pipfile 支持。

Cloudflare Pages 构建在 gVisor ↗ 容器中运行。

若你当前使用 v1 或 v2 构建镜像，项目将自动迁移到 v3：

• v1 构建镜像：若使用 Pages v1 构建镜像，项目将于 2026 年 9 月 15 日自动迁移到 v3。
• v2 构建镜像：若使用 Pages v2 构建镜像，项目将于 2027 年 2 月 23 日自动迁移到 v3。

弃用日期前 6 个月，你将通过 Cloudflare 更新日志、仪表板通知和电子邮件收到通知。

今后，v3 构建镜像将根据以下策略对预装软件进行滚动更新，不会再有进一步的构建镜像版本变更。

预装软件（语言和工具）将在到达生命周期结束（EOL）前更新。这些更新仅适用于你未覆盖默认版本的情况。

• 次要版本更新：可能在不通知的情况下更新到最新可用次要版本。对于不遵循语义化版本的工具（例如 Bun 或 Hugo），可能包含破坏性变更的更新将提前 3 个月通知。
• 主要版本更新：提前 3 个月通知后，更新到下一个稳定的长期支持（LTS）版本。

需要通知的变更的通知方式：

• Cloudflare 更新日志
• 针对将收到更新的项目的仪表板通知
• 向项目所有者发送的电子邮件通知

若要维持特定版本并避免自动更新，请覆盖默认版本。

为避免意外的构建失败：

• 通过 Cloudflare 更新日志、仪表板通知和电子邮件关注公告
• 收到更新通知时规划迁移
• 通过覆盖默认版本固定关键预装软件的特定版本