hexo-deployer-wrangler 部署指南

§ 背景

Hexo 官方部署器生态主要面向 GitHub Pages、GitLab Pages、Rsync 等传统方式。部署到 Cloudflare Pages 通常需要额外手动执行 wrangler pages deploy 命令，无法通过 hexo deploy 一键完成。

hexo-deployer-wrangler 填补了这一空缺——它是一个 Hexo 部署器插件，在 hexo deploy 阶段自动调用 Wrangler CLI，将生成的静态站点推送到 Cloudflare Pages（默认）或 Cloudflare Workers。

§ 安装

pnpm add hexo-deployer-wrangler

依赖：自动安装 wrangler (v4+) 作为 peer dependency。需要 Node >= 18。

仓库地址：llxlr/hexo-deployer-wrangler

§ 源码架构

整套插件压缩在单个 index.js（约 160 行），由以下几个核心模块组成：

§ 模块说明

§ 认证方式

插件在部署前依次检测以下认证方式（任一满足即可）：

§ 方式一：API Token（推荐）

设置环境变量：

export CLOUDFLARE_API_TOKEN="your-api-token"

export CLOUDFLARE_ACCOUNT_ID="your-account-id"

API Token 可在 Cloudflare Dashboard 创建，权限选择 Account > Cloudflare Pages > Edit。

§ 方式二：Global API Key

export CLOUDFLARE_API_KEY="your-global-api-key"

export CLOUDFLARE_EMAIL="your-email@example.com"

export CLOUDFLARE_ACCOUNT_ID="your-account-id"

Global API Key 权限过大，不推荐在生产环境使用。

§ 方式三：本地 OAuth 登录

npx wrangler login

登录后令牌存储在 ~/.wrangler/config/default.toml，插件会自动检测。

§ 认证检测逻辑

// validate () 的核心逻辑

const hasToken = !!process.env.CLOUDFLARE_API_TOKEN;

const hasKey = !!process.env.CLOUDFLARE_API_KEY;

const hasLocalLogin = checkLocalLogin();   // 检查 ~/.wrangler/config/default.toml

const hasTomlAccount = checkWranglerTomlAccount();  // 检查 wrangler.toml 中的 account_id

如果四种认证方式均未检测到，插件会打印警告并列出可用的认证方式，但不会阻止部署（可能仍然成功，取决于 wrangler.toml 配置和本地状态）。

§ 配置

§ Pages 模式（默认）

在 _config.yml 中添加：

deploy:

  type: wrangler

  target: pages            # 默认值，可省略

  project_name: my-blog    # Cloudflare Pages 项目名

  branch: main             # 部署分支

  commit_dirty: false      # 是否提交脏工作区

  skip_bundle: true        # 跳过 wrangler 的构建步骤（Hexo 已完成构建）

部署命令：

hexo deploy

# 等价于：

# wrangler pages deploy public --project-name my-blog --branch main

§ Worker 模式

deploy:

  type: wrangler

  target: worker

  name: my-worker

  env: production

  dry_run: false

  tsconfig: tsconfig.json

  outdir: dist

部署命令：

hexo deploy

# 等价于：

# wrangler deploy --name my-worker --env production

§ 配置优先级

同一配置项在多处出现时，优先级从高到低为：

1. hexo deploy 的命令行参数（args）
2. _config.yml 中 deploy 配置段
3. 项目根目录 wrangler.toml 中的配置

例如 project_name：

• args.project_name > deploy.project_name > deploy.projectName > wrangler.toml 的 name 字段

§ 多环境部署

通过环境变量切换不同配置：

# 部署到生产环境

CLOUDFLARE_API_TOKEN=$PROD_TOKEN hexo deploy

# 部署到预览环境

CLOUDFLARE_API_TOKEN=$PREVIEW_TOKEN hexo deploy -- --branch preview

§ 与 cloudflare 命令对比

§ 构建脚本集成

在 package.json 中配置一条龙部署：

{

  "scripts": {

    "build": "hexo clean && hexo generate",

    "deploy": "hexo deploy",

    "ship": "pnpm run build && pnpm run deploy"

  }

}

§ 相关提交

§ 参考链接