从 Cloudflare Pages 迁移静态博客到 Workers

2026年2月8日字数统计：517

Cloudflare 去年开始就宣布不再维护 Pages，推荐迁移到 Workers，今年甚至已经把创建 Pages 的入口变成了创建 Worker 页面底部的一行字，因此迁移到 Workers 确实需要划入日程。

本文假定使用的博客框架是静态博客，并且使用 Cloudflare 提供的 Github/Gitlab 绑定。

实际上迁移方法非常简单：

在仓库根目录中添加一个 wrangler.json 或者 wrangler.toml：

JSON

{
    "name": "blog",
    "compatibility_date": "2026-02-08",
    "workers_dev": false,
    "preview_urls": false,
    "assets": {
        "directory": "_site",
        "not_found_handling": "404-page"
    }
}

创建一个 Workers 应用，选择 Github 或者 Gitlab，然后编辑构建命令，对于 Jekyll 来说是 bundle install && bundle exec jekyll build，对于 Node.js 来说是 npm run build，然后取消“非生产分支构建”复选框。
点击部署即可将博客部署在 Cloudflare Worker 上。
如果你先前在 Wrangler 配置文件中不使用 Cloudflare 提供的域名，此时需要在 Worker 设置中手动添加需要的域名。
此时，可以检查博客是否正常运行，然后就可以删除过时的 Pages 应用。

其中 name 字段需要在后续步骤匹配 Workers 的项目名，注意它可以和现有的 Pages 项目名重名。

compatibility_date 字段是必须的，可以和我一样填为 2026-02-08。

worker_dev 字段决定是否开启 Cloudflare 提供的 project.user.workers.dev 域名，如果有自己的域名，设置为 false。

preview_urls 字段决定是否开启 Cloudflare 提供的非生产环境域名，一般不需要所以设置为 false。

assets.directory 字段用于设置静态网站构建目录，一般来说是 _site 或者 dist。

assets.not_found_handling 用于控制 404 页面，它可以被设置为 single-page-application、404-page 或者 none，如果设
为 none 则使用 Cloudflare 提供的 404 页面，如果设置为 404-page 则会使用构建目录下的 404.html。

Wrangler 配置文件的文档在 Configuration。