通用命令

用于身份验证、遥测和 shell 补全的通用 Wrangler 命令。

docs

在默认浏览器中打开 Cloudflare 开发者文档。

npx wrangler docs [SEARCH]

yarn wrangler docs [SEARCH]

pnpm wrangler docs [SEARCH]

• [SEARCH]string

  Enter search terms (e.g. the wrangler command) you want to know more about

• --yesboolean alias: --y

  Takes you to the docs, even if search fails

使用 OAuth 授权 Wrangler 访问你的 Cloudflare 账户。Wrangler 将尝试自动打开 Web 浏览器以使用 Cloudflare 账户登录。

如果你更喜欢使用 API 令牌进行身份验证（例如在无头或持续集成环境中），请参阅在 CI/CD 中运行 Wrangler。

wrangler login [OPTIONS]

• --scopes-list stringoptional
  • 列出所有可用的 OAuth 作用域及其描述。
• --scopes stringoptional
  • 允许你选择 OAuth 作用域集。作用域集必须以空格分隔的列表输入， 例如 npx wrangler login --scopes account:read user:read。
• --callback-host stringoptional
  • 默认为 localhost。设置 Wrangler 监听 OAuth 回调的 IP 或主机名。
• --callback-port stringoptional
  • 默认为 8976。设置 Wrangler 监听 OAuth 回调的端口。
• --use-keyring booleanoptional
  • 将 OAuth 凭据存储在操作系统密钥链中，而不是默认的明文 TOML 文件。有关详情，请参阅在操作系统密钥链中存储 OAuth 凭据。使用 --no-use-keyring 选择退出。该选择会在 Wrangler 调用之间持久保存。

以下全局标志适用于每个命令：

• --help boolean
  • 显示帮助。
• --config string（Pages 不支持）
  • 指向你的 Wrangler 配置文件的路径。
• --cwd string
  • 在指定目录中运行，而不是当前工作目录。

如果 Wrangler 无法打开浏览器，你可以将终端中 wrangler login 生成的 URL 复制并粘贴到浏览器中登录。

如果你从远程机器使用 Wrangler，但从本地浏览器运行登录流程，登录后你将收到以下错误消息：This site can't be reached。

要完成登录流程，请运行 wrangler login 并在浏览器中完成登录流程：

npx wrangler login

 ⛅️ wrangler 2.1.6
-------------------
Attempting to login via OAuth...
Opening a link in your default browser: https://dash.cloudflare.com/oauth2/auth?xyz...

浏览器登录流程会将你重定向到机器上的 localhost URL。

保持登录流程活动。打开第二个终端会话。在该第二个终端会话中，在远程机器上使用 curl 或等效的请求库获取此 localhost URL。复制并粘贴 wrangler login 流程期间生成的 localhost URL 并运行：

curl <LOCALHOST_URL>

Cloudflare OAuth 提供程序始终重定向到 localhost:8976 的回调服务器。如果你在容器内运行 Wrangler，主机浏览器的浏览器可能无法访问此服务器——即使授权连接后，登录命令也会挂起。

你必须配置容器，将主机机器上的端口 8976 映射到 Wrangler OAuth 回调服务器的端口（默认为 8976）。

例如，如果你在 Docker 容器中运行 Wrangler：

docker run -p 8976:8976 <your-image>

在容器内运行 npx wrangler login 时，将回调主机设置为监听所有网络接口：

npx wrangler login --callback-host=0.0.0.0

现在当浏览器重定向到 localhost:8976 时，请求将转发到容器内 0.0.0.0:8976 上运行的 Wrangler。

如果需要在容器内使用不同端口，请同时使用 --callback-port 并相应调整端口映射，例如：

# When starting your container
docker run -p 8976:9000 <your-image>

# Inside the container
npx wrangler login --callback-host=0.0.0.0 --callback-port=9000

默认情况下，Wrangler 将 wrangler login 返回的 OAuth 访问令牌和刷新令牌存储在全局 Wrangler 配置目录下的明文 TOML 文件中（通常为 ~/.config/.wrangler/config/default.toml）。传递 --use-keyring 以选择使用操作系统密钥链的更安全的存储路径：

npx wrangler login --use-keyring

启用 --use-keyring 时，Wrangler 将凭据写入 AES-256-GCM ↗ 加密文件（default.enc，与旧版 default.toml 位置并列），并将 32 字节加密密钥存储在 OS 密钥链中：

• macOS 通过 /usr/bin/security 使用内置 Keychain ↗。
• Linux 通过 libsecret-tools 包中的 secret-tool CLI 使用 libsecret ↗。如果 secret-tool 不可用，Wrangler 将打印每个发行版的安装提示。
• Windows 通过 @napi-rs/keyring ↗ 使用 Credential Manager ↗，Wrangler 在你首次选择加入时延迟安装（约 1.9 MB 一次性下载）。在 CI 等非交互式环境中，请提前使用 npm install -g @napi-rs/keyring@<version> 安装绑定，或保持默认明文路径。

首次选择加入时如果存在明文凭据文件，Wrangler 会读取它，将内容加密到新 .enc 文件中，并删除明文文件。

该选择会在 Wrangler 调用之间持久保存。要验证凭据当前存储位置，请运行 wrangler whoami：

npx wrangler whoami

👋 You are logged in with an OAuth Token, associated with the email [email protected].
🔐 Credentials are stored in: Encrypted file (~/.config/.wrangler/config/default.enc) with key in macOS Keychain (service=wrangler, account=default)

要选择退出，请传递 --no-use-keyring：

npx wrangler login --no-use-keyring

选择退出会删除加密文件和密钥链条目。Wrangler 故意不会将现有凭据解密到磁盘——在选择退出期间写入明文会抵消你刚刚选择禁用的静态保护。后续登录流程将新凭据写入明文 TOML 文件。

环境变量 CLOUDFLARE_AUTH_USE_KEYRING 覆盖单次调用的持久首选项：

# Force the keychain backend for this command only
CLOUDFLARE_AUTH_USE_KEYRING=true npx wrangler deploy

# Force the plaintext file backend for this command only
CLOUDFLARE_AUTH_USE_KEYRING=false npx wrangler deploy

当环境变量设置为 true 且密钥链后端不可用时（例如 Linux 上缺少 secret-tool），Wrangler 会退出并报错，而不是静默回退到明文文件。仅设置持久首选项时，Wrangler 回退到明文文件并打印一次性警告，这样损坏的密钥链不会将你锁定。

--use-keyring 选择加入不会改变 API 令牌的解析方式：CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_API_KEY/CLOUDFLARE_EMAIL 继续优先于任何存储的 OAuth 凭据，在 CI/CD 中运行 Wrangler 指南仍适用于非交互式环境。

移除 Wrangler 访问账户的授权。此命令将使当前 OAuth 令牌失效并删除存储的凭据。当密钥链存储处于活动状态时，加密凭据文件和密钥链条目都会被移除。

wrangler logout

以下全局标志适用于每个命令：

• --help boolean
  • 显示帮助。
• --config string（Pages 不支持）
  • 指向你的 Wrangler 配置文件的路径。
• --cwd string
  • 在指定目录中运行，而不是当前工作目录。

如果你使用 CLOUDFLARE_API_TOKEN 而不是 OAuth，可以通过在 Cloudflare 仪表板中删除 API 令牌来注销：

1. 在 Cloudflare 仪表板中，转到 Account API tokens（账户 API 令牌） 页面。

   Go to Account API tokens ↗

2. 在 Wrangler 令牌上选择三点菜单。

3. 选择 Delete（删除）。

管理身份验证，包括用于跨多个账户工作的命名身份验证配置文件。

检索当前身份验证令牌或凭据，供其他工具和脚本使用。

wrangler auth token [OPTIONS]

• --json booleanoptional
  • 以 JSON 返回输出并包含令牌类型信息。这也支持检索 API key/email 凭据。

该命令按以下优先级顺序返回当前配置的身份验证方法：

• 来自 CLOUDFLARE_API_TOKEN 环境变量的 API 令牌
• 来自 CLOUDFLARE_API_KEY 和 CLOUDFLARE_EMAIL 环境变量的 API key/email（需要 --json 标志，因为此方法使用两个值而不是单个令牌）
• 来自 wrangler login 的 OAuth 令牌（过期时自动刷新）

使用 --json 时，输出包含令牌类型：

// API token
{ "type": "api_token", "token": "..." }

// OAuth token
{ "type": "oauth", "token": "..." }

// API key/email (only available with --json)
{ "type": "api_key", "key": "...", "email": "..." }

如果没有可用的身份验证方法，或在未使用 --json 的情况下配置了 API key/email，则返回错误。

以下全局标志适用于每个命令：

• --help boolean
  • 显示帮助。
• --config string（Pages 不支持）
  • 指向你的 Wrangler 配置文件的路径。
• --cwd string
  • 在指定目录中运行，而不是当前工作目录。

auth create

Create or re-authenticate a named auth profile

npx wrangler auth create [NAME]

yarn wrangler auth create [NAME]

pnpm wrangler auth create [NAME]

• [NAME]string required

  Name for the auth profile

• --browserboolean default: true

  Automatically open the OAuth link in a browser

• --scopesstring

  Pick the set of applicable OAuth scopes when logging in

• --callback-hoststring default: localhost

  Use the ip or host address for the temporary login callback server.

• --callback-portnumber default: 8976

  Use the port for the temporary login callback server.

auth activate

Bind a named auth profile to a directory

npx wrangler auth activate [NAME] [DIR]

yarn wrangler auth activate [NAME] [DIR]

pnpm wrangler auth activate [NAME] [DIR]

• [NAME]string required

  Name of the auth profile to activate

• [DIR]string

  Directory to bind the profile to (defaults to current directory)

auth deactivate

Remove the auth profile binding from a directory

npx wrangler auth deactivate [DIR]

yarn wrangler auth deactivate [DIR]

pnpm wrangler auth deactivate [DIR]

• [DIR]string

  Directory to unbind (defaults to current directory). Must be the exact directory the profile was bound to.

auth list

List all auth profiles

npx wrangler auth list

yarn wrangler auth list

pnpm wrangler auth list

auth delete

Delete a named auth profile

npx wrangler auth delete [NAME]

yarn wrangler auth delete [NAME]

pnpm wrangler auth delete [NAME]

• [NAME]string required

  Name of the auth profile to delete

whoami

🕵️ Retrieve your user information

npx wrangler whoami

yarn wrangler whoami

pnpm wrangler whoami

• --accountstring

  Show membership information for the given account (id or name).

• --jsonboolean default: false

  Return user information as JSON. Exits with a non-zero status if not authenticated.

Cloudflare 收集匿名使用数据以改进 Wrangler。你可以在数据政策 ↗中了解更多信息。

你可以随时使用这些命令管理使用数据共享。

禁用 Wrangler 的遥测收集。

wrangler telemetry disable

启用 Wrangler 的遥测收集。

wrangler telemetry enable

检查遥测收集当前是否启用。返回结果特定于你运行命令的目录。

这将解析由 wrangler telemetry disable / enable 设置的全局状态、环境变量 WRANGLER_SEND_METRICS 以及 Wrangler 配置文件 中的 send_metrics 键。

wrangler telemetry status

以下全局标志适用于每个命令：

• --help boolean
  • 显示帮助。
• --config string（Pages 不支持）
  • 指向你的 Wrangler 配置文件的路径。
• --cwd string
  • 在指定目录中运行，而不是当前工作目录。

为 Wrangler 命令生成 shell 补全脚本。Shell 补全允许你在输入时按 Tab 自动补全命令、子命令和标志。

wrangler complete <SHELL>

• SHELL stringrequired
  • 要生成补全的 shell。支持的值：bash、zsh、fish、powershell。

生成补全脚本并将其添加到 shell 配置文件：

wrangler complete bash >> ~/.bashrc

wrangler complete zsh >> ~/.zshrc

wrangler complete fish >> ~/.config/fish/config.fish

wrangler complete powershell >> $PROFILE

设置完成后，按 Tab 自动补全命令、子命令和标志：

wrangler d<TAB>          # completes to 'deploy', 'dev', 'd1', etc.
wrangler kv <TAB>        # shows subcommands: namespace, key, bulk

以下全局标志适用于每个命令：

• --help boolean
  • 显示帮助。
• --config string（Pages 不支持）
  • 指向你的 Wrangler 配置文件的路径。
• --cwd string
  • 在指定目录中运行，而不是当前工作目录。