Workers Builds 使用支持多种语言和工具的构建镜像,例如 Node.js、Python、PHP、Ruby 和 Go。
Workers Builds 支持多种运行时、语言和工具。除非检测到或指定自定义版本,否则构建将使用下面列出的默认版本。你可以使用环境变量或版本文件覆盖默认版本。所有版本均可覆盖。
| 工具 | 默认版本 | 环境变量 | 文件 |
|---|---|---|---|
| Go | 1.27.3 | GO_VERSION |
|
| Node.js | 24.22.1 | NODE_VERSION |
.nvmrc、.node-version |
| Python | 3.14.8 | PYTHON_VERSION |
.python-version、runtime.txt |
| Ruby | 3.4.11 | RUBY_VERSION |
.ruby-version |
构建镜像预安装了 Node.js 22.23.4 和 24.22.1。
| 工具 | 默认版本 | 环境变量 | 文件 |
|---|---|---|---|
| Bun | 1.4.4 | BUN_VERSION |
package.json 中的 packageManager 字段 |
| Hugo | extended_0.147.7 | HUGO_VERSION |
|
| npm | 10.9.2 | package.json 中的 packageManager 字段 |
|
| yarn | 4.18.1 | YARN_VERSION |
package.json 中的 packageManager 字段 |
| pnpm | 9.10.0 | PNPM_VERSION |
package.json 中的 packageManager 字段 |
| pip | 26.2.2 | ||
| gem | 3.6.9 | ||
| poetry | 2.4.3 | ||
| pipx | 1.17.2 | ||
| bundler | 2.6.9 | ||
| uv | 0.13.4 |
有关 packageManager 字段的详细信息,请参阅包管理器版本。
如果你需要覆盖镜像中语言或工具的特定版本,可以将其指定为构建环境变量,或如上所示在源代码中设置相关文件。
要使用构建环境变量设置版本,可以:
- 找到语言和工具的环境变量名称及所需版本(例如
NODE_VERSION = 22) - 在 Worker 项目中前往 Settings(设置) > Build > Build Variables and Secrets,在仪表板上添加并保存环境变量
或者,要通过向项目添加文件来设置版本,可以:
- 找到语言和工具的文件名(例如
.nvmrc) - 将指定的文件名添加到根目录,并将所需版本号设置为文件内容。例如,如果版本号为 22,文件应包含 '22'。
要设置 npm、yarn、pnpm 或 Bun 的版本,请将 packageManager ↗ 字段添加到 package.json。这是更改 npm 版本的唯一方法。
{
"packageManager": "[email protected]"
}- Workers Builds 从项目根目录中的
package.json读取packageManager。如果根目录不是仓库的顶层目录,Workers Builds 还会读取仓库顶层的package.json。如果两个文件都设置了packageManager,请在两者中使用相同的值。 - 请使用确切版本,例如
[email protected]。不要使用npm@^11之类的版本范围。 package.json中的engines.npm字段不会设置 npm 版本。如果只设置engines.npm,Workers Builds 会使用默认的 npm 版本,并且 npm 会输出EBADENGINE警告,而不会失败。packageManager设置包管理器的版本。仓库中的锁文件仍决定使用哪个包管理器安装依赖项。
Workers Builds 通过 Corepack ↗ 运行 pnpm。使用默认 Corepack 设置时,版本选择遵循以下顺序:
package.json中的顶层packageManager字段。package.json中的devEngines.packageManager(当其指定pnpm和版本时)。PNPM_VERSION构建变量。- 构建镜像的默认 pnpm 版本。
项目版本要求的优先级高于 PNPM_VERSION。请使用确切版本以保持构建一致。devEngines.packageManager 中的版本范围可能导致不同构建选择不同版本。pnpm-lock.yaml 中记录的 pnpm 版本不会固定 Corepack 运行的版本。
日志行 Detected the following tools from environment 报告的是 Corepack 应用 devEngines.packageManager 之前的工具选择。请查看 pnpm 的安装输出,以确定实际运行的版本。
你可以添加以下构建变量以禁用自动依赖安装,改为运行自定义安装命令。
| 构建变量 | 值 |
|---|---|
SKIP_DEPENDENCY_INSTALL |
1 或 true |
在下表中查看构建镜像中预装的软件包。这些软件包使用 apt(Linux 发行版的包管理器)安装。
curl |
libbz2-dev |
libreadline-dev |
git |
libc++1 |
libssl-dev |
git-lfs |
libdb-dev |
libvips-dev |
unzip |
libgdbm-dev |
libyaml-dev |
autoconf |
libgdbm6 |
tzdata |
build-essential |
libgbm1 |
wget |
bzip2 |
libgmp-dev |
zlib1g-dev |
gnupg |
liblzma-dev |
zstd |
libffi-dev |
libncurses5-dev |
Workers Builds 在以下环境中运行:
| 构建环境 | Ubuntu 24.04 |
| 架构 | x86_64 |
构建命令使用构建镜像中安装于 /etc/ssl/certs/ca-certificates.crt 的 CA 证书。Workers Builds 会设置以下环境变量,以便自带 CA 证书的运行时也使用这些证书,包括通过版本覆盖选择的旧版本:
| 环境变量 | 值 |
|---|---|
SSL_CERT_FILE |
/etc/ssl/certs/ca-certificates.crt |
PIP_CERT |
/etc/ssl/certs/ca-certificates.crt |
REQUESTS_CA_BUNDLE |
/etc/ssl/certs/ca-certificates.crt |
NODE_OPTIONS |
--use-openssl-ca |
如果您将这些变量中的任何一个设置为构建变量,您的值会替换默认值。除非您自己的 NODE_OPTIONS 已包含 --use-openssl-ca 或 --use-bundled-ca,否则会向其中添加 --use-openssl-ca。
预装软件(语言和工具)将在到达生命周期结束(EOL)之前更新。这些更新仅在你未覆盖默认版本时适用。
- 次要版本更新:可能会在没有通知的情况下更新到最新的可用次要版本。对于不遵循语义化版本控制的工具(例如 Bun 或 Hugo),可能包含破坏性更改的更新将提前 3 个月通知。
- 主要版本更新:更新到下一个稳定的长期支持(LTS)版本,提前 3 个月通知。
你将如何收到通知(对于需要通知的更改):
- Cloudflare 更新日志 ↗
- 将收到更新的项目的仪表板通知
- 发送给项目所有者的电子邮件通知
要维护特定版本并避免自动更新,请覆盖默认版本。
为避免意外的构建失败:
- 关注公告:查看 Cloudflare 更新日志 ↗、控制面板通知和电子邮件
- 固定特定版本:通过覆盖默认版本固定关键预装软件的特定版本