CF Static Export Pro 部署手册

📋 目录

1. 前置准备

2. 部署步骤

3. 关键配置说明

4. 常见问题排查

5. 维护与更新

前置准备

需要的账号和服务

服务器环境要求

部署步骤

第一步：在 Cloudflare 创建资源

1.1 创建 R2 存储桶

1. 登录 Cloudflare 仪表盘

2. 左侧菜单 → R2 → 创建存储桶

3. 名称填写：wordpress（或你的自定义名称）

4. 区域选择：亚太地区 (APAC)（离你最近）

5. 点击创建

6. 不要启用"公共开发 URL"（流量走 Worker）

1.2 创建 D1 数据库

1. 左侧菜单 → Workers & Pages → D1 → 创建数据库

2. 名称填写：wordpress

3. 点击创建

4. 进入数据库 → 查询 选项卡 → 执行 schema.sql（见下方）

schema.sql 内容：

-- 文章索引表
CREATE TABLE IF NOT EXISTS posts (
  wp_id           INTEGER PRIMARY KEY,
  slug            TEXT UNIQUE NOT NULL,
  title           TEXT NOT NULL,
  content         TEXT,
  excerpt         TEXT,
  date            DATETIME NOT NULL,
  modified        DATETIME,
  categories      TEXT,
  tags            TEXT,
  status          TEXT DEFAULT 'published',
  featured_image  TEXT,
  created_at      DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 分类/标签统计表
CREATE TABLE IF NOT EXISTS taxonomies (
  slug        TEXT PRIMARY KEY,
  type        TEXT NOT NULL,
  name        TEXT,
  post_ids    TEXT DEFAULT '',
  updated_at  DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 索引
CREATE INDEX IF NOT EXISTS idx_posts_date ON posts(date DESC);
CREATE INDEX IF NOT EXISTS idx_posts_status ON posts(status);
CREATE INDEX IF NOT EXISTS idx_posts_slug ON posts(slug);
CREATE INDEX IF NOT EXISTS idx_taxonomies_type ON taxonomies(type);

1.3 创建 KV 命名空间

1. 左侧菜单 → Workers & Pages → KV → 创建命名空间

2. 名称填写：KV_CACHE

3. 点击创建

4. 复制生成的 ID（32位字符串）

1.4 获取 Account ID

1. 仪表盘右上角 → 头像 → 右侧显示 "Account ID"

2. 复制保存

1.5 创建 API Token

1. 仪表盘右上角 → 我的个人资料 → API Tokens → 创建令牌

2. 选择 "创建自定义令牌"

3. 配置权限：

4. 点击 "继续以显示摘要" → "创建令牌"

5. 立即复制并保存 Token（只显示一次）

第二步：配置 Worker

2.1 修改 wrangler.toml

name = "wp-static-pro"
main = "src/index.js"
compatibility_date = "2024-01-01"

[vars]
ENABLE_COMPRESSION = true
WORDPRESS_URL = ""  # 回源地址，通常留空

[[r2_buckets]]
binding = "R2_BUCKET"
bucket_name = "wordpress"  # 你的 R2 存储桶名称

[[d1_databases]]
binding = "D1_DATABASE"
database_id = "your-d1-database-id"  # 你的 D1 ID
database_name = "wordpress"

[[kv_namespaces]]
binding = "KV_CACHE"
id = "your-kv-namespace-preview-id"  # 你的 KV ID

[observability]
enabled = true
head_sampling_rate = 0.1

2.2 部署 Worker

cd /path/to/worker

# 安装依赖
npm install

# 登录 Wrangler（会打开浏览器授权）
npx wrangler login

# 设置 Auth Key Secret（与 WordPress 插件保持一致）
npx wrangler secret put AUTH_KEY_SECRET
# 输入强密码，例如：s3cur3-k3y-98765

# 部署 Worker
npx wrangler deploy --env=""

2.3 绑定自定义域名（可选）

1. Cloudflare 仪表盘 → Workers & Pages → wp-static-pro

2. 点击 "触发器" → "添加自定义域"

3. 输入域名（如 doc.yuebin.uk）

4. 按提示在域名注册商处添加 CNAME 记录

没有自定义域名时：使用 Worker 默认域名 https://wp-static-pro.workers.dev

第三步：安装 WordPress 插件

3.1 上传插件

# 将 cf-static-export-pro.php 上传到
/var/www/html/wp-content/plugins/cf-static-export-pro/

或通过 WordPress 后台 → 插件 → 安装插件 → 上传插件。

3.2 激活插件

WordPress 后台 → 插件 → 找到 "CF静态导出Pro" → 点击 "启用"。

第四步：配置插件

WordPress 后台 → 设置 → CF静态导出，填写以下配置：

高级选项

关键配置说明

⚠️ WordPress 固定链接（Permalink）设置

必须设置为 /%postname%/！

1. WordPress 后台 → 设置 → 固定链接

2. 选择 "文章名"（/%postname%/）

3. 点击保存

原因：插件依赖 $post->post_name 生成 R2 路径。如果使用默认的 ?p=123，post_name 可能为空，导致导出失败。

⚠️ WP_HOME 和 WP_SITEURL 设置

建议强制固定，避免内部抓取时 URL 解析错误：

// wp-config.php 中
define('WP_HOME', 'https://doc.yuebin.uk');
define('WP_SITEURL', 'https://doc.yuebin.uk');
define('FORCE_SSL_ADMIN', true);

⚠️ PHP 内存限制

批量导出大量文章时，需要增加内存：

// wp-config.php 中
define('WP_MEMORY_LIMIT', '512M');
define('WP_MAX_MEMORY_LIMIT', '512M');

常见问题排查

1. 批量导出报 "R2上传失败"

原因：max_retries 被清空为 0。

解决：

1. 进入插件设置页

2. 确认 "上传重试次数" 已填写（如 3）

3. 点击保存

2. 文章页访问 404

原因：插件和 Worker 路径不一致。

解决：

1. 确认使用 v2.2.3 版本

2. 确认 routes.js 中查找路径为 posts/{slug}/index.html（无前导 /）

3. 重新部署 Worker

3. 中文显示乱码

原因：Worker 写入时用了 TextEncoder。

解决：

1. 确认 routes.js 中 handleUpload 用 Uint8Array 解码

2. 重新部署 Worker

3. 重新导出文章

4. 首页显示 "共 0 篇文章"

原因：依赖了不存在的 site_meta.total_posts。

解决：使用 v2.2.3+ 版本，首页直接统计 D1 中的文章数。

5. 分类/标签页 404

检查项：

1. D1 数据库中 taxonomies 表是否有数据

2. 文章是否已写入 D1

3. 分类/标签的 slug 是否正确

6. cf-debug 目录有文件但 R2 没有

原因：Worker 上传失败。

排查：

1. 检查 AUTH_KEY_SECRET 是否一致

2. 检查 Worker 日志：npx wrangler tail

3. 检查 R2 绑定是否正确

维护与更新

日常维护

Worker 日志查看

cd /path/to/worker
npx wrangler tail

更新插件

1. 下载新版 cf-static-export-pro.php

2. 上传替换旧文件

3. 保存一次插件配置

4. 重新部署 Worker（如有配套更新）

📋 部署检查清单

部署完成后，逐项确认：

• □ 

  Cloudflare 资源已创建（R2/D1/KV）

• □ 

  D1 数据库表已创建（posts + taxonomies）

• □ 

  Worker 已成功部署

• □ 

  WordPress 固定链接设置为 /%postname%/

• □ 

  WordPress 插件已激活

• □ 

  插件配置已填写并保存

• □ 

  AUTH_KEY_SECRET 与插件 Worker Auth Key 一致

• □ 

  关闭 R2 的"公共开发 URL"

• □ 

  至少一篇文章导出成功

• □ 

  文章页可正常访问（/posts/{slug}/）

• □ 

  首页显示正确文章数

• □ 

  分类/标签页可正常访问

 最终建议

1. 关闭调试模式：生产环境请关闭"调试模式"，避免 cf-debug 目录堆积文件。

2. 关闭 Gzip 压缩：如果 Worker 不支持 contentEncoding 元数据，可以关闭，Cloudflare 会自动压缩。

3. 定期查看日志：wp-content/cf-static-export.log 会记录所有操作，便于排查问题。

部署完成后，你的 WordPress 站点就变成了一台"内容生产机器"，前端完全托管在 Cloudflare 上。🎉