hexo-deployer-wrangler

基于 Wrangler CLI (v4+) 将 Hexo 站点部署到 Cloudflare Pages 和 Cloudflare Workers 的插件。

要求 Node.js >= 18.0.0

前置条件

• Pages 模式：在 Cloudflare 控制台中已创建好 Pages 项目。
• Worker 模式：项目根目录存在 wrangler.toml 配置文件，且已通过 wrangler deploy 创建过 Worker。
• Cloudflare 认证（以下三种方式任选其一）：
  • API Token（推荐）：拥有 Pages:Edit / Workers Scripts:Edit 权限的 Token，创建地址
  • 本地登录：运行 npx wrangler login 完成 OAuth 登录，凭证保存在本地 ~/.wrangler/ 目录
  • Global API Key：通过 CLOUDFLARE_API_KEY + CLOUDFLARE_EMAIL 环境变量提供

安装

npm install hexo-deployer-wrangler

配置

1. 认证方式

插件支持三种认证方式，按优先级依次为：

| 优先级 | 方式 | 说明 | |---|---|---| | 1 | API Token | 设置 CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID 环境变量 | | 2 | Global API Key | 设置 CLOUDFLARE_API_KEY + CLOUDFLARE_EMAIL + CLOUDFLARE_ACCOUNT_ID 环境变量 | | 3 | 本地 OAuth 登录 | 运行 npx wrangler login 后在 ~/.wrangler/ 目录中保存的凭证 |

方式一：API Token（推荐）

export CLOUDFLARE_API_TOKEN="你的-api-token"
export CLOUDFLARE_ACCOUNT_ID="你的-account-id"

方式二：本地 OAuth 登录

npx wrangler login
# 浏览器中完成授权后即可使用，无需设置环境变量

方式三：Global API Key

export CLOUDFLARE_API_KEY="你的-global-api-key"
export CLOUDFLARE_EMAIL="你的[email protected]"
export CLOUDFLARE_ACCOUNT_ID="你的-account-id"

Account ID 也可以通过项目根目录的 wrangler.toml 文件中的 account_id 字段提供。

2. 修改 Hexo 配置

在 _config.yml 中添加 deploy 段落。通过 target 切换部署目标（默认 pages）：

# 部署到 Cloudflare Pages
deploy:
  type: wrangler
  target: pages
  project_name: my-hexo-blog

# 部署到 Cloudflare Workers
deploy:
  type: wrangler
  target: worker
  # Worker 配置由 wrangler.toml 管理，此处提供覆盖选项

配置项说明

通用配置

| 配置项 | 类型 | 默认值 | 说明 | |---|---|---|---| | target | string | pages | 部署目标：pages 或 worker | | compat_date | string | — | 传给 wrangler 的兼容性日期 | | compat_flags | string|array | — | 兼容性标志（逗号分隔字符串或数组） |

Pages 专用配置

| 配置项 | 类型 | 默认值 | 说明 | |---|---|---|---| | project_name | string | 必填 | Cloudflare Pages 项目名称 | | branch | string | main | 部署时记录的 Git 分支名 | | commit_dirty | boolean | false | 工作区有未提交更改时是否仍允许部署 | | commit_hash | string | — | 自定义部署记录的 commit hash | | commit_message | string | — | 自定义部署记录的 commit message | | skip_bundle | boolean | false | 跳过 wrangler 的打包步骤（建议 Hexo 开启） |

Worker 专用配置

| 配置项 | 类型 | 默认值 | 说明 | |---|---|---|---| | env | string | — | 部署环境（如 production、staging） | | name | string | — | Worker 名称，覆盖 wrangler.toml 中的设置 | | dry_run | boolean | false | 空跑模式，只输出将部署的内容 | | tsconfig | string | — | TypeScript 配置文件路径 | | outdir | string | — | Worker 打包产物输出目录 | | routes | string|array | — | 路由列表（逗号分隔或数组） | | vars | object|string | — | Worker 变量（对象或 key:value,... 格式字符串） |

完整配置示例

# Pages 部署
deploy:
  type: wrangler
  target: pages
  project_name: my-hexo-blog
  branch: production
  commit_dirty: true
  skip_bundle: true
  # compat_date: '2025-01-01'
  # compat_flags: 'nodejs_compat,streams'

# Worker 部署
deploy:
  type: wrangler
  target: worker
  env: production
  dry_run: false
  routes: 'example.com/*,api.example.com/*'
  vars:
    API_URL: 'https://api.example.com'
    DEBUG: 'false'
  # 或者 vars: 'API_URL:https://api.example.com,DEBUG:false'
  # compat_date: '2025-01-01'
  # compat_flags: 'nodejs_compat'

配置优先级

配置项按以下优先级解析（高到低）：

| 优先级 | 来源 | 说明 | |---|---|---| | 1 | CLI 参数 | 通过 hexo deploy -- <key> <value> 传入 | | 2 | _config.yml | Hexo 博客的 deploy 配置段 | | 3 | wrangler.toml | 博客根目录的 Wrangler 配置文件（自动读取） |

wrangler.toml 自动映射

插件会自动读取博客根目录的 wrangler.toml 作为默认配置。以下字段会自动映射：

| wrangler.toml 字段 | 对应 _config.yml 配置项 | 适用目标 | |---|---|---| | name | project_name (Pages) / name (Worker) | Pages / Worker | | account_id | CLOUDFLARE_ACCOUNT_ID 环境变量 | 通用 | | compatibility_date | compat_date | 通用 | | compatibility_flags | compat_flags | 通用 | | [vars] | vars | Worker | | [[routes]] | routes | Worker | | [env.<name>] | 对应环境的覆盖配置 | Worker |

示例：只需在 wrangler.toml 中维护一份配置，_config.yml 中只写最简内容。

# wrangler.toml
name = "my-hexo-site"
account_id = "abcd1234..."
compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat"]

[vars]
API_URL = "https://api.example.com"

[[routes]]
pattern = "example.com/*"

# _config.yml - 极简配置，其余全从 wrangler.toml 读取
deploy:
  type: wrangler
  target: worker
  env: production

使用方式

构建并部署：

hexo generate
hexo deploy

或合并为一行命令：

hexo generate --deploy
# 或者
hexo deploy --generate

工作原理

Pages 模式 (target: pages)：

1. 执行 hexo generate 在 public/ 目录中生成静态文件。
2. 调用 wrangler pages deploy <public_dir> 将构建产物上传至 Cloudflare Pages。
3. Wrangler 自动处理资源哈希、CDN 分发和 DNS 路由。

Worker 模式 (target: worker)：

1. 调用 wrangler deploy 部署 Worker 脚本（配置由 wrangler.toml 提供）。
2. 通过 _config.yml 中的 Worker 专用配置可覆盖或补充 CLI 参数。

统一使用 npx wrangler 命令行工具，工作目录锁定为博客根目录（确保 wrangler 能读取 wrangler.toml），跨平台兼容 Windows / macOS / Linux。

常见问题

提示 CLOUDFLARE_API_TOKEN 未设置

设置对应环境变量，或通过 wrangler login 创建全局认证配置。在 CI/CD 环境中建议使用 API Token 方式。

Windows 用户请注意：通过「系统属性 → 环境变量」设置的用户/系统级 CLOUDFLARE_API_TOKEN， 只对之后新启动的进程生效。已打开的终端 / IDE（如 PowerShell、Windows Terminal、VS Code） 不会自动继承新变量。设置后请重启终端再执行 hexo deploy。

插件同样兼容 wrangler 常用的别名变量：CF_API_TOKEN（同 CLOUDFLARE_API_TOKEN）、 CF_API_KEY（同 CLOUDFLARE_API_KEY）与 CF_ACCOUNT_ID（同 CLOUDFLARE_ACCOUNT_ID）。

提示 CLOUDFLARE_ACCOUNT_ID 未设置

在 Cloudflare Dashboard 侧边栏找到 Account ID，或运行：

wrangler whoami

提示找不到项目

确认 _config.yml 中的 project_name 与 Cloudflare Pages 中已创建的项目名称一致。可在 Cloudflare Dashboard 中创建新项目。

本地登录后仍未生效

确认 ~/.wrangler/config/default.toml 文件存在且包含认证信息（access_token、refresh_token 等字段）。Windows 用户请注意 os.homedir() 在某些终端（如 MSYS）下可能返回非预期路径，插件会优先使用 USERPROFILE 环境变量定位。

如果登录过期，重新运行 npx wrangler login。

提示「本地 wrangler 登录已过期」

~/.wrangler/config/default.toml 中保存的 OAuth 凭证带有 expiration_time，过期后 wrangler 无法自动刷新（尤其是在非交互式终端中）。插件现在会识别这种已过期的本地登录并提前提醒，避免 误判为「已登录」却部署失败。

处理方式二选一：

1. 重新运行 npx wrangler login 完成 OAuth 授权；
2. 设置 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID 环境变量（优先级高于本地登录）。

部署成功但提示"未检测到认证方式"

如果 npx wrangler whoami 可以正常输出，但插件仍提示「未检测到认证方式」并且拒绝部署， 说明当前使用的认证方式不在插件识别范围内。此时请显式设置 CLOUDFLARE_API_TOKEN （或别名 CF_API_TOKEN），或重新运行 npx wrangler login。

协议

MIT