跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

系统环境变量

最后更新 查看 MarkdownAgent 设置

系统环境变量是可改变 Wrangler 行为的本地环境变量。有三种设置系统环境变量的方式：

  1. 在项目目录中创建 .env 文件。在 .env 文件中设置环境变量的值。这是设置这些变量的推荐方式，因为它会在 Wrangler 会话之间保留值。

  2. 在 Wrangler 命令中内联值。例如，WRANGLER_LOG="debug" npx wrangler deploy 将为此命令执行设置 WRANGLER_LOG 的值为 "debug"。

  3. 在 shell 环境中设置值。例如，如果你使用 Z shell，将 export CLOUDFLARE_API_TOKEN=... 添加到 ~/.zshrc 文件会将此令牌设置为 shell 配置的一部分。

支持的环境变量

Wrangler 支持以下环境变量：

  • CLOUDFLARE_ACCOUNT_ID stringoptional

  • CLOUDFLARE_API_TOKEN stringoptional

    • Cloudflare 账户的 API 令牌，可用于 CI/CD 和其他自动化等场景的身份验证。

  • CLOUDFLARE_API_KEY stringoptional

    • Cloudflare 账户的 API 密钥，通常与 CLOUDFLARE_EMAIL= 一起用于较旧的身份验证方法。

  • CLOUDFLARE_EMAIL stringoptional

    • 与 Cloudflare 账户关联的电子邮件地址，通常与 CLOUDFLARE_API_KEY= 一起用于较旧的身份验证方法。

  • CLOUDFLARE_ACCESS_CLIENT_ID stringoptional

    • Cloudflare Access 服务令牌 的 Client ID，用于在 CI/CD 流水线等非交互式环境中与 Access 保护的域进行身份验证。必须与 CLOUDFLARE_ACCESS_CLIENT_SECRET 一起设置。当两个变量都设置时，Wrangler 使用服务令牌进行身份验证，而不是启动 cloudflared access login。有关完整的 Access 策略和服务令牌设置，请参阅连接到 Access 保护的 Workers。

  • CLOUDFLARE_ACCESS_CLIENT_SECRET stringoptional

  • CLOUDFLARE_AUTH_USE_KEYRING booleanoptional

    • 此选项为 true 和 false。默认为未设置。覆盖 wrangler login --use-keyring / --no-use-keyring 设置的持久首选项，仅用于单次调用。当为 true 时，Wrangler 将 OAuth 凭据存储在加密文件中，加密密钥保存在操作系统密钥链中，如果密钥链后端不可用则退出并报错。当为 false 时，Wrangler 使用旧版明文 TOML 文件，即使启用了持久首选项。有关详情，请参阅在操作系统密钥链中存储 OAuth 凭据。

  • CLOUDFLARE_ENV stringoptional

    • 用于 Wrangler 命令的环境。这允许你在不使用 --env 标志的情况下选择环境。例如，CLOUDFLARE_ENV=production wrangler deploy 将部署到 production 环境。--env 命令行参数优先于此环境变量。

  • NODE_ENV stringoptional

    • 设置 Worker 代码中 process.env.NODE_ENV 的值。对于 wrangler dev 默认为 "development"，对于 wrangler deploy 和 wrangler versions upload 默认为 "production"。有关更多信息，请参阅打包。

  • WRANGLER_SEND_METRICS booleanoptional

    • 此选项为 true 和 false。默认为 true。控制 Wrangler 是否可为此项目向 Cloudflare 发送匿名使用数据。你可以在数据政策 ↗中了解更多信息。

  • WRANGLER_SEND_ERROR_REPORTS booleanoptional

    • 此选项为 true 和 false。默认为 undefined。控制 Wrangler 是否可为此项目向 Cloudflare 发送非用户错误报告。如果为 undefined，Wrangler 将在每次出现非用户错误时询问用户是否发送错误报告。

  • CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>stringoptional

    • 在本地开发中使用 Hyperdrive 时数据库的本地连接字符串。例如，如果你的 Hyperdrive 绑定名为 PROD_DB，则为 CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_PROD_DB="postgres://user:password@127.0.0.1:5432/testdb"。每个 Hyperdrive 由绑定名称唯一区分。

  • CLOUDFLARE_API_BASE_URL stringoptional

    • 默认值为 "https://api.cloudflare.com/client/v4"。

  • WRANGLER_LOG stringoptional

    • 日志级别选项为 "none"、"error"、"warn"、"info"、"log" 和 "debug"。级别不区分大小写，默认为 "log"。如果指定无效级别，Wrangler 将回退到默认值。日志可以包括对 Cloudflare API 的请求、正在收集的任何使用数据以及更详细的错误日志。

  • WRANGLER_LOG_PATH stringoptional

    • Wrangler 将写入调试日志的文件或目录路径。如果路径以 .log 结尾，Wrangler 将视其为所有日志的写入路径。否则，Wrangler 将路径视为目录，并使用时间戳作为文件名写入一个或多个日志文件。

  • WRANGLER_LOG_SANITIZE booleanoptional

    • 此选项为 true 和 false。默认为 true。控制 Wrangler 是否将从日志写入控制台或日志文件的任何敏感信息进行脱敏。敏感信息包括 API 令牌、电子邮件地址、账户 ID 等。

  • FORCE_COLOR stringoptional

    • 通过将此设置为 0，可以禁用 Wrangler 的彩色输出，这在某些终端设置下更易于阅读。例如 FORCE_COLOR=0。

  • WRANGLER_HTTPS_KEY_PATH stringoptional

    • 运行 wrangler dev 时自定义 HTTPS 证书密钥的路径，与 WRANGLER_HTTPS_CERT_PATH 一起使用。

  • WRANGLER_HTTPS_CERT_PATH stringoptional

    • 运行 wrangler dev 时自定义 HTTPS 证书的路径，与 WRANGLER_HTTPS_KEY_PATH 一起使用。

  • DOCKER_HOST stringoptional

    • 用于 Containers 的本地开发。Wrangler 将尝试自动找到与容器引擎通信的正确 socket。如果不起作用（通常在尝试连接 Container 时表现为 internal error），你可以尝试使用此环境变量设置 socket 路径。

  • WRANGLER_R2_SQL_AUTH_TOKEN stringoptional

    • 用于执行 R2 SQL 查询的 API 令牌。

  • WRANGLER_OUTPUT_FILE_PATH stringoptional

    • 指定 Wrangler 将以 ND-JSON ↗（换行分隔 JSON）格式写入输出数据的文件路径。文件中的每一行是包含 Wrangler 操作（如部署、版本上传和错误）信息的单独 JSON 对象。这对于需要以编程方式访问部署信息的 CI/CD 流水线和自动化工具很有用。如果同时设置 WRANGLER_OUTPUT_FILE_PATH 和 WRANGLER_OUTPUT_FILE_DIRECTORY，WRANGLER_OUTPUT_FILE_PATH 优先。

  • WRANGLER_OUTPUT_FILE_DIRECTORY stringoptional

    • 指定 Wrangler 将创建随机命名文件（格式：wrangler-output-<timestamp>-<random>.json）以 ND-JSON ↗ 格式写入输出数据的目录。当你想在特定目录中组织输出文件但不需要控制确切文件名时很有用。如果同时设置 WRANGLER_OUTPUT_FILE_PATH 和 WRANGLER_OUTPUT_FILE_DIRECTORY，WRANGLER_OUTPUT_FILE_PATH 优先。

  • WRANGLER_CACHE_DIR stringoptional

    • Wrangler 缓存文件的自定义目录。设置时，这将覆盖默认缓存位置（node_modules/.cache/wrangler）。对于不使用传统 node_modules 目录的环境（如 Yarn PnP）很有用。

  • MINIFLARE_CACHE_DIR stringoptional

    • Miniflare 的 cf.json 缓存文件的自定义目录，在 wrangler dev 本地开发期间使用。设置时，这将覆盖默认缓存位置（node_modules/.mf）。对于不使用传统 node_modules 目录的环境（如 Yarn PnP）很有用。

  • CLOUDFLARE_CF_FETCH_ENABLED stringoptional

    • 控制 Miniflare 在本地开发期间是否从 Cloudflare 获取包含 Request.cf 属性的 cf.json 文件。设置为 "false" 或 "0" 可完全禁用获取并使用回退数据。禁用时不会创建 node_modules/.mf/cf.json 文件。默认为 "true"。这对于不希望自动创建 node_modules 目录的非 JavaScript 项目（如 Rust 或 Go Workers）特别有用。Miniflare API 中的显式 cf 选项优先于此环境变量。

  • CLOUDFLARE_CF_FETCH_PATH stringoptional

    • 指定缓存 cf.json 文件的自定义路径，覆盖默认的 node_modules/.mf/cf.json 位置。这对于想要共享缓存位置的多项目设置，或想要将缓存存储在 node_modules 之外的项目很有用。Miniflare API 中的显式 cf 选项优先于此环境变量，CLOUDFLARE_CF_FETCH_ENABLED=false 优先于此变量。

输出文件示例

设置这些环境变量时，Wrangler 将每个 JSON 对象作为一行写入输出文件。每个条目包含 timestamp 字段和指示操作类型的 type 字段。以下是运行 wrangler deploy 后文件可能包含内容的示例：

{"type":"wrangler-session","version":1,"wrangler_version":"3.78.0","command_line_args":["deploy"],"log_file_path":"/path/to/logs/wrangler-2024-11-03_12-00-00_abc.log","timestamp":"2024-11-03T12:00:00.000Z"}
{"type":"deploy","version":1,"worker_name":"my-worker","worker_tag":"abc123def456","version_id":"v1-abc123","targets":["https://my-worker.example.workers.dev"],"worker_name_overridden":false,"wrangler_environment":"production","timestamp":"2024-11-03T12:00:05.000Z"}

wrangler-session 条目在 Wrangler 启动时写入，包含有关正在运行的命令的信息。deploy 条目在部署成功完成时写入，包括 worker 名称、版本 ID 和部署 URL。

其他条目类型包括：

  • version-upload - 由 wrangler versions upload 写入，包含版本 ID 和预览 URL
  • version-deploy - 由 wrangler versions deploy 写入，包含部署信息
  • pages-deploy - 由 wrangler pages deploy 写入，包含 Pages 部署详情
  • command-failed - 命令失败时写入，包括错误代码和消息

.env 文件示例

以下是 .env 文件示例：

CLOUDFLARE_ACCOUNT_ID=<YOUR_ACCOUNT_ID_VALUE>
CLOUDFLARE_API_TOKEN=<YOUR_API_TOKEN_VALUE>
CLOUDFLARE_EMAIL=<YOUR_EMAIL>
WRANGLER_SEND_METRICS=true
CLOUDFLARE_API_BASE_URL=https://api.cloudflare.com/client/v4
WRANGLER_LOG=debug
WRANGLER_LOG_PATH=../Desktop/my-logs/my-log-file.log
WRANGLER_R2_SQL_AUTH_TOKEN=<YOUR_R2_API_TOKEN_VALUE>
CLOUDFLARE_CF_FETCH_ENABLED=false

已弃用的全局变量

以下变量已弃用。使用上面列出的新变量以防止任何问题或不需要的消息。

  • CF_ACCOUNT_ID
  • CF_API_TOKEN
  • CF_API_KEY
  • CF_EMAIL
  • CF_API_BASE_URL

这篇文档对您有帮助吗？