- 发布于
Next.js 博客迁移到 Cloudflare Workers:静态导出、部署配置与域名接入
- 作者

- 姓名
- 刘琦
这次博客迁移的起因很直接:原来的 Vercel 部署被暂停,网站返回了 402 DEPLOYMENT_DISABLED。
最开始容易把它当成构建失败,但项目里的生产部署状态仍然是 READY。查看控制台后才确认,原因是 Hobby 套餐的 Fast Origin Transfer 超出限额。
最终采用的方案是:Next.js 静态导出 + Cloudflare Workers Static Assets,少量动态接口由 Worker 单独处理。
一、先判断博客是否适合静态导出
项目使用 Next.js 15.5.7,文章保存在 MDX 文件中。首页、文章、标签和分页都可以在构建时生成,搜索也是前端读取静态索引。RSS 和 sitemap 同样可以输出为静态文件。
不过,项目还有邮件订阅接口,需要单独处理。首页能打开,并不意味着所有功能都完成了迁移。如果项目依赖登录状态、请求时渲染、Server Actions 或复杂服务端接口,就要另行评估完整 Next.js 运行方案。
二、静态导出卡在标签路由
首次构建时遇到了:
dynamicParams: true cannot be used with output: export
问题出在两个标签路由:
app/tags/[tag]/page.tsx
app/tags/[tag]/page/[page]/page.tsx
它们已经实现了 generateStaticParams(),但同时设置了 dynamicParams = true。静态部署不能在请求到来时临时生成新页面,因此改为:
export const dynamicParams = false
之后新增文章或标签,需要重新构建并发布。对于通过 Git 管理内容的博客,这符合原来的更新流程。
三、构建成功,不代表部署命令正确
最初准备的是 Pages 静态部署方案,实际在 Cloudflare 控制台创建的是 Workers 项目。日志显示 Next.js 页面和 RSS 已生成成功,失败发生在后面的 npx wrangler deploy。
当时项目缺少明确的 Wrangler 配置,部署工具进入了 Next.js 自动适配流程,尝试执行 OpenNext 迁移,最后报 Cannot find package 'wrangler'。
解决方法是明确指定静态产物 out 和一个轻量 Worker 入口。核心配置如下:
{
"name": "my-next-blog",
"main": "worker.mjs",
"compatibility_date": "2026-11-16",
"assets": {
"directory": "./out",
"binding": "ASSETS",
"html_handling": "drop-trailing-slash",
"not_found_handling": "404-page",
"run_worker_first": ["/api/newsletter", "/api/newsletter/*"]
}
}
普通页面由静态资源处理,只有订阅接口优先进入 Worker。404 使用真实的 404 页面,而不是把所有不存在的路径都重写到首页。具体 URL 处理方式还要结合站点现有路径检查,尤其是中文标签、分页和 RSS。
四、单独保留动态接口
邮件订阅需要在请求时执行,因此通过 Worker 入口转交现有订阅处理逻辑:
import { onRequest as newsletter } from './functions/api/newsletter.js'
export default {
async fetch(request, env) {
const { pathname } = new URL(request.url)
if (pathname === '/api/newsletter' || pathname.startsWith('/api/newsletter/')) {
return newsletter({ request, env })
}
return env.ASSETS.fetch(request)
},
}
订阅服务的密钥应放在 Cloudflare 运行时 Secret 中,不能放进前端代码或 NEXT_PUBLIC_* 变量。
需要区分接口部署和真实订阅成功:这次线上检查确认 GET 请求返回了不支持该方法的响应,但没有用真实邮箱发起订阅,实际投递仍需单独验收。
五、保留项目自己的构建入口
项目构建除了 Next.js 本身,还有 RSS 生成等后处理。因此需要使用项目的完整构建脚本,而不是只执行平台默认的 next build。
这次使用 Node 22 和项目已有的 Yarn 3.6.1,执行 yarn build:pages 生成静态文件,再通过 npx wrangler deploy --dry-run 做部署预检。
预检通过只能说明配置、构建和打包过程基本正确,不能代替线上验证。另外,如果控制台和 Wrangler 配置都执行了完整构建,可能会重复构建,后续可以统一入口以减少发布时间。
六、图片和响应头也要迁移
静态导出关闭了 Next.js 服务端图片优化,图片按原文件提供。这样减少了服务端依赖,但仍要检查图片大小、格式和加载性能。
next.config.js 中的 headers() 也不会自动变成静态平台的响应头规则,因此需要迁移到 Cloudflare 使用的 _headers 文件。原来依赖 Vercel 的统计组件也要检查或替换。
七、域名接入与 DNS 冲突
添加自定义域时,Cloudflare 提示主机名已有外部管理的 DNS 记录。处理时先导出 DNS 备份,确认目标主机名对应的 A、AAAA 或 CNAME,再删除已确认的冲突记录,重新添加 Worker 自定义域。
不能清空整个 DNS 列表:MX、TXT、验证记录和其他子域名都要保留。裸域和 www 也是两个独立主机名,需要分别检查。
域名注册商转移并不是网站迁移的前提。域名可以在一个注册商续费,同时使用 Cloudflare DNS 和 Workers。
八、验收不能只看构建成功
部署后继续检查了首页、文章、中文标签、搜索、RSS、sitemap、404 和订阅接口路由。正式首页、RSS 和 sitemap 已恢复访问。
还有几项需要继续收尾:真实订阅投递尚未验证,主域与 canonical 策略需要统一;另外一次后续构建失败仍需查看完整日志。已经上线的版本可访问,不代表未来每次自动发布都已验证。
这次迁移的关键是:把适合构建时生成的内容导出为静态文件,用明确的 Wrangler 配置部署,再单独处理少量动态能力。对于以 MDX 为主的博客,这既保留了 Next.js 开发体验,也避免每次访问都依赖服务端渲染。