跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

构建镜像

最后更新 查看 MarkdownAgent 设置

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 字段的详细信息,请参阅包管理器版本。

高级设置

覆盖默认版本

如果你需要覆盖镜像中语言或工具的特定版本,可以将其指定为构建环境变量,或如上所示在源代码中设置相关文件。

要使用构建环境变量设置版本,可以:

  1. 找到语言和工具的环境变量名称及所需版本(例如 NODE_VERSION = 22)
  2. 在 Worker 项目中前往 Settings(设置) > Build > Build Variables and Secrets,在仪表板上添加并保存环境变量

或者,要通过向项目添加文件来设置版本,可以:

  1. 找到语言和工具的文件名(例如 .nvmrc)
  2. 将指定的文件名添加到根目录,并将所需版本号设置为文件内容。例如,如果版本号为 22,文件应包含 '22'。

包管理器版本

要设置 npm、yarn、pnpm 或 Bun 的版本,请将 packageManager ↗ 字段添加到 package.json。这是更改 npm 版本的唯一方法。

package.jsonjson
{
    "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 设置包管理器的版本。仓库中的锁文件仍决定使用哪个包管理器安装依赖项。

pnpm 版本选择

Workers Builds 通过 Corepack ↗ 运行 pnpm。使用默认 Corepack 设置时,版本选择遵循以下顺序:

  1. package.json 中的顶层 packageManager 字段。
  2. package.json 中的 devEngines.packageManager(当其指定 pnpm 和版本时)。
  3. PNPM_VERSION 构建变量。
  4. 构建镜像的默认 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 个月通知。

你将如何收到通知(对于需要通知的更改):

要维护特定版本并避免自动更新,请覆盖默认版本。

最佳实践

为避免意外的构建失败:

这篇文档对您有帮助吗?