hexo-deployer-wrangler 1.0.3

package/README.md

@@ -0,0 +1,246 @@
+# hexo-deployer-wrangler
+
+基于 [Wrangler CLI (v4+)](https://developers.cloudflare.com/workers/wrangler/) 将 Hexo 站点部署到 [Cloudflare Pages](https://pages.cloudflare.com/) 和 [Cloudflare Workers](https://workers.cloudflare.com/) 的插件。
+
+> 要求 Node.js >= 18.0.0
+
+## 前置条件
+
+- **Pages 模式**：在 Cloudflare 控制台中已创建好 [Pages 项目](https://pages.cloudflare.com/)。
+- **Worker 模式**：项目根目录存在 `wrangler.toml` 配置文件，且已通过 `wrangler deploy` 创建过 Worker。
+- Cloudflare 认证（以下三种方式任选其一）：
+  - **API Token**（推荐）：拥有 **Pages:Edit** / **Workers Scripts:Edit** 权限的 Token，[创建地址](https://dash.cloudflare.com/profile/api-tokens)
+  - **本地登录**：运行 `npx wrangler login` 完成 OAuth 登录，凭证保存在本地 `~/.wrangler/` 目录
+  - **Global API Key**：通过 `CLOUDFLARE_API_KEY` + `CLOUDFLARE_EMAIL` 环境变量提供
+
+## 安装
+
+```bash
+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（推荐）**
+
+```bash
+export CLOUDFLARE_API_TOKEN="你的-api-token"
+export CLOUDFLARE_ACCOUNT_ID="你的-account-id"
+```
+
+**方式二：本地 OAuth 登录**
+
+```bash
+npx wrangler login
+# 浏览器中完成授权后即可使用，无需设置环境变量
+```
+
+**方式三：Global API Key**
+
+```bash
+export CLOUDFLARE_API_KEY="你的-global-api-key"
+export CLOUDFLARE_EMAIL="你的-email@example.com"
+export CLOUDFLARE_ACCOUNT_ID="你的-account-id"
+```
+
+> Account ID 也可以通过项目根目录的 `wrangler.toml` 文件中的 `account_id` 字段提供。
+
+### 2. 修改 Hexo 配置
+
+在 `_config.yml` 中添加 deploy 段落。通过 `target` 切换部署目标（默认 `pages`）：
+
+```yaml
+# 部署到 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,...` 格式字符串） |
+
+### 完整配置示例
+
+```yaml
+# 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` 中只写最简内容。
+
+```toml
+# 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/*"
+```
+
+```yaml
+# _config.yml - 极简配置，其余全从 wrangler.toml 读取
+deploy:
+  type: wrangler
+  target: worker
+  env: production
+```
+
+## 使用方式
+
+构建并部署：
+
+```bash
+hexo generate
+hexo deploy
+```
+
+或合并为一行命令：
+
+```bash
+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 方式。
+
+### 提示 `CLOUDFLARE_ACCOUNT_ID` 未设置
+
+在 [Cloudflare Dashboard](https://dash.cloudflare.com/) 侧边栏找到 Account ID，或运行：
+
+```bash
+wrangler whoami
+```
+
+### 提示找不到项目
+
+确认 `_config.yml` 中的 `project_name` 与 Cloudflare Pages 中已创建的项目名称一致。可在 [Cloudflare Dashboard](https://dash.cloudflare.com/pages) 中创建新项目。
+
+### 本地登录后仍未生效
+
+确认 `~/.wrangler/config/default.toml` 文件存在且包含认证信息（`access_token`、`refresh_token` 等字段）。Windows 用户请注意 `os.homedir()` 在某些终端（如 MSYS）下可能返回非预期路径，插件会优先使用 `USERPROFILE` 环境变量定位。
+
+如果登录过期，重新运行 `npx wrangler login`。
+
+### 部署成功但提示"未检测到认证方式"
+
+这是插件启动时的预检警告，实际部署由 wrangler 自行完成。如果 `npx wrangler whoami` 能正常输出则表示认证无问题，可忽略该警告。该问题通常已在最新版本修复。
+
+## 协议
+
+MIT

package/index.js

@@ -0,0 +1 @@
+"use strict";const{spawn:spawn}=require("child_process"),path=require("path"),fs=require("fs"),os=require("os"),{parse:parseToml}=require("smol-toml");function readWranglerToml(e){const r=path.join(e||"","wrangler.toml");try{return parseToml(fs.readFileSync(r,"utf-8"))}catch(e){return null}}function buildPagesArgs(e,r,o){const n=e.config.deploy||{},s=["pages","deploy",path.resolve(e.public_dir||"public")],t=r.project_name||n.project_name||n.projectName||o&&o.name;t&&s.push("--project-name",t);const c=r.branch||n.branch;c&&s.push("--branch",c);const a=r.commit_hash||n.commit_hash||n.commitHash;a&&s.push("--commit-hash",a);const i=r.commit_message||n.commit_message||n.commitMessage;i&&s.push("--commit-message",i);(void 0!==r.commit_dirty?r.commit_dirty:n.commit_dirty||n.commitDirty)&&s.push("--commit-dirty");return(void 0!==r.skip_bundle?r.skip_bundle:n.skip_bundle||n.skipBundle)&&s.push("--no-bundle"),s}function buildWorkerArgs(e,r){const o=e.config.deploy||{},n=["deploy"],s=r.env||o.env;s&&n.push("--env",s);const t=r.name||o.name;t&&n.push("--name",t);(void 0!==r.dry_run?r.dry_run:o.dry_run||o.dryRun)&&n.push("--dry-run");const c=r.tsconfig||o.tsconfig;c&&n.push("--tsconfig",c);const a=r.outdir||o.outdir;return a&&n.push("--outdir",a),n}function buildArgs(e,r){const o=e.config.deploy||{},n=r.target||o.target||"pages",s=e.base_dir||process.cwd(),t=readWranglerToml(s);return t&&e.log.info("已读取 wrangler.toml 配置"),"worker"===n?{argv:buildWorkerArgs(e,r),baseDir:s}:{argv:buildPagesArgs(e,r,t),baseDir:s}}function runWrangler(e,r,o){return new Promise((n,s)=>{const t="win32"===process.platform?"npx.cmd":"npx";r.log.info("npx wrangler %s",e.join(" "));const c=spawn(t,["wrangler",...e],{stdio:"inherit",env:process.env,cwd:o||process.cwd(),shell:"win32"===process.platform});c.on("close",e=>{0===e?n():s(new Error(`wrangler exited with code ${e}`))}),c.on("error",s)})}function checkLocalLogin(){let e=process.env.WRANGLER_HOME;e||(e="win32"===process.platform&&process.env.USERPROFILE?path.join(process.env.USERPROFILE,".wrangler"):path.join(os.homedir(),".wrangler"));const r=path.join(e,"config","default.toml");try{const e=parseToml(fs.readFileSync(r,"utf-8"));return!!(e.access_token||e.oauth_token||e.refresh_token||e.api_token||e.oauth&&(e.oauth.refresh_token||e.oauth.access_token))}catch(e){return!1}}function checkWranglerTomlAccount(e){const r=readWranglerToml(e);return!(!r||!r.account_id)}function validate(e){const r=!!process.env.CLOUDFLARE_API_TOKEN,o=!!process.env.CLOUDFLARE_API_KEY,n=!!process.env.CLOUDFLARE_ACCOUNT_ID,s=checkLocalLogin(),t=checkWranglerTomlAccount(e.base_dir||process.cwd());r?e.log.info("检测到 CLOUDFLARE_API_TOKEN 环境变量，使用 API Token 认证"):o?e.log.info("检测到 CLOUDFLARE_API_KEY 环境变量，使用 Global API Key 认证"):s&&e.log.info("检测到本地 wrangler 登录状态，使用 OAuth 认证"),n?e.log.info("检测到 CLOUDFLARE_ACCOUNT_ID: %s",process.env.CLOUDFLARE_ACCOUNT_ID):t&&e.log.info("检测到 wrangler.toml 中的 account_id"),r||o||s||(e.log.warn(""),e.log.warn("⚠  未检测到任何 Cloudflare 认证方式，部署可能失败！"),e.log.warn("   方式1 (推荐): 设置 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID 环境变量"),e.log.warn("   方式2: 运行 npx wrangler login 进行本地 OAuth 登录"),e.log.warn("   方式3: 设置 CLOUDFLARE_API_KEY 和 CLOUDFLARE_EMAIL 环境变量"),e.log.warn("")),n||t||e.log.info("未显式设置 CLOUDFLARE_ACCOUNT_ID，wrangler 将尝试自动推断")}function deploy(e,r){const o=this,n=async()=>{try{validate(o);const r="worker"===(e.target||o.config.deploy.target||"pages")?"Cloudflare Workers":"Cloudflare Pages";o.log.info("Deploying to %s via Wrangler...",r);const{argv:n,baseDir:s}=buildArgs(o,e);o.log.info("wrangler %s",n.join(" ")),await runWrangler(n,o,s),o.log.info("Deployment successful!")}catch(e){if(o.log.error("Deployment failed: %s",e.message),r)return void r(e);throw e}r&&r()};if("function"!=typeof r)return n();n()}hexo.extend.deployer.register("wrangler",deploy);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "hexo-deployer-wrangler",
+  "version": "1.0.3",
+  "description": "Hexo deployer plugin for Cloudflare Pages via Wrangler CLI (v3+)",
+  "main": "index.js",
+  "keywords": [
+    "hexo",
+    "deployer",
+    "cloudflare",
+    "wrangler",
+    "pages"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "hexo": ">=5.0.0"
+  },
+  "dependencies": {
+    "smol-toml": "^1.6.1",
+    "wrangler": "^4.91.0"
+  },
+  "files": [
+    "index.js"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/llxlr/hexo-deployer-wrangler.git"
+  }
+}