1. 项目概述一个专为Next.js部署到Cloudflare的“智能工具箱”如果你正在为一个Next.js项目寻找Vercel之外的部署方案尤其是看中了Cloudflare Pages的全球边缘网络和免费额度但又被官方迁移工具对Next.js 16支持不佳、各种隐晦的报错和文档缺失搞得焦头烂额那么这个项目可能就是为你准备的。它不是另一个泛泛的教程而是一个从真实、复杂的生产迁移中淬炼出来的“实战工具箱”。这个名为metasal1/openclaw-skill-cloudflare的项目核心是一个为OpenClaw AI智能体设计的“技能”Skill。但即便你完全不使用OpenClaw它里面打包的脚本、配置模板和避坑指南其价值也远超一个普通的工具库。它直击两个最痛的痛点一是如何将基于App Router的现代Next.js应用特别是16版本稳定、正确地部署到Cloudflare Pages二是如何解决在此过程中必然会遇到的、官方文档语焉不详的那些“坑”比如边缘数据库Turso的适配、API路由的运行时冲突、以及那个导致部署后全是404的“Worker组装问题”。我自己在迁移一个中型Next.js 15项目到Cloudflare Pages时几乎踩遍了这里提到的所有雷。项目作者将这些经验系统化形成了包含完整检查清单、自动化部署脚本和关键组件替换方案的“迁移剧本”。接下来我会带你深入拆解这个工具箱的每一部分不仅告诉你“怎么做”更会解释“为什么必须这么做”以及我在类似场景下验证过的那些细节。2. 核心迁移策略与工具选型解析2.1 为什么是opennextjs/cloudflare而非官方适配器这是整个迁移的基石选错工具后续所有工作都可能白费。Cloudflare官方提供的cloudflare/next-on-pages适配器在Next.js 15及更早版本上表现尚可但它对Next.js 16的支持存在滞后性和兼容性问题。根据社区反馈和实际测试在Next.js 16上使用它你可能会遇到构建失败、运行时错误或部分App Router特性无法使用的情况。opennextjs/cloudflare是一个社区维护的替代方案它诞生的目的就是为了更好地支持Next.js的现代特性尤其是App Router和更新版本。它的工作原理与官方适配器不同它通过一个更深入的转换过程将Next.js的构建输出包括服务端组件、路由处理器等打包成与Cloudflare Workers和Pages环境高度兼容的格式。简单来说它更像一个“翻译官”能更准确地理解Next.js 16的“语言”并将其“翻译”成Cloudflare边缘运行时能高效执行的“语言”。关键决策点如果你的项目基于Next.js 16或更新版本opennextjs/cloudflare是目前更可靠的选择。它的迭代速度通常能跟上Next.js的更新节奏社区活跃遇到问题时也更容易找到解决方案。2.2 项目结构深度解读什么才是“开箱即用”这个技能包的文件结构非常精简但每一部分都针对一个具体痛点scripts/cf-deploy.js这是项目的“灵魂”。为什么需要它因为opennextjs/cloudflare构建后输出文件是分散在.open-next/目录下的一个模块化结构。而wrangler pages deploy命令期望上传的是一个包含所有依赖的、扁平化的目录。直接部署.open-next/会导致Worker找不到动态导入的模块从而引发404错误。这个脚本自动化了文件收集、重命名worker.js-_worker.js和目录组装的过程是部署成功的关键。references/turso-edge.md这是解决数据库问题的“钥匙”。在边缘运行时Edge Runtime中许多传统的Node.js数据库客户端包括Turso的官方libsql/client无法工作因为它们依赖了Node.js特有的API如fs,net模块。这份参考文档提供了一个基于原生fetchAPI的、轻量级的Turso HTTP客户端实现是边缘函数与Turso数据库通信的可行方案。references/dns.md虽然迁移主要关注部署但将域名指向新的Cloudflare Pages站点是上线前的最后一步。这份指南整理了通过Cloudflare API管理DNS记录的常见模式便于自动化或作为手动操作的参考。这种结构反映了一个务实的原则不提供大而全的框架而是提供解决关键障碍的精准工具和文档。3. 逐步迁移实操手册与避坑指南3.1 环境准备与基础配置在开始之前请确保你拥有一个Cloudflare账户并且已经将你的域名添加到Cloudflare中管理或者你打算使用Cloudflare分配的*.pages.dev子域名。首先在你的Next.js项目根目录下安装必要的依赖npm install -D opennextjs/cloudflare wrangler这里安装的是开发依赖-D因为适配器和CLI工具只在构建和部署阶段需要。接下来创建项目核心配置文件。1. 创建wrangler.jsonc这个文件告诉Wrangler工具如何管理你的Pages项目。使用.jsonc格式允许添加注释更清晰。{ $schema: node_modules/wrangler/config-schema.json, name: your-awesome-app, // 你的项目名称会体现在Cloudflare仪表板中 pages_build_output_dir: .open-next/assets, // 关键指向适配器生成的静态资源目录 compatibility_date: 2025-04-01, // 使用一个较新的兼容日期以支持最新特性 compatibility_flags: [nodejs_compat] // 启用Node.js兼容模式许多NPM包需要它 }2. 创建open-next.config.ts这是opennextjs/cloudflare适配器本身的配置文件。对于大多数项目默认配置即可。import { defineConfig } from opennextjs/cloudflare; export default defineConfig({ // 目前可以留空使用默认配置。 // 未来如果需要自定义中间件行为、缓存规则等可以在这里配置。 });3. 处理环境变量文件.dev.varsCloudflare Pages在开发和生产环境使用不同的机制管理秘密值。本地开发时Wrangler会读取.dev.vars文件。# .dev.vars DATABASE_URL你的Turso数据库连接URL NEXT_PUBLIC_API_KEY你的公开API密钥 NEXTJS_ENVproduction # 确保Next.js以生产模式运行重要提示务必立即将.dev.vars添加到.gitignore文件中避免敏感信息泄露。# .gitignore 追加 .open-next/ .deploy/ .dev.vars3.2 代码改造移除不兼容的“钉子户”这是迁移中最需要细心的一步涉及对现有代码的修改。1. 清理API路由的运行时配置在App Router中你可能会在app/api/.../route.ts文件中看到export const runtime edge;这样的声明目的是让该API在Vercel的边缘网络上运行。然而opennextjs/cloudflare适配器不支持这种显式的edge runtime声明。如果保留API路由会悄无声息地返回500错误。操作你需要移除所有API路由文件中的这行代码。可以使用命令行工具批量操作操作前建议备份# 在项目根目录执行 # macOS: find . -name route.ts -path */api/* -exec sed -i /export const runtime edge;/d {} \; # Linux: find . -name route.ts -path */api/* -exec sed -i /export const runtime edge;/d {} \;手动检查几个重要的API路由文件确认该行已被移除。2. 替换Turso数据库客户端如前所述libsql/client在边缘运行时中会失败。你需要参考项目中的turso-edge.md实现一个基于HTTP的客户端。这里提供一个简化的示例展示核心思路// lib/turso-edge.ts export async function execute(sql: string, params: any[] []) { const url https://${process.env.TURSO_DB_NAME}-${process.env.TURSO_ORG}.turso.io/v2/pipeline; const response await fetch(url, { method: POST, headers: { Authorization: Bearer ${process.env.TURSO_AUTH_TOKEN}, Content-Type: application/json, }, body: JSON.stringify({ requests: [{ type: execute, stmt: { sql, args: params } }] }) }); const result await response.json(); // Turso HTTP API返回的数据结构需要处理 const rows result.results?.[0]?.response?.result?.rows || []; // 转换数据格式使其接近原客户端的返回结构 return { rows: rows.map(row row.map(cell cell.value)) }; }3. 移除Vercel特定包vercel/analytics等Vercel生态的包在非Vercel环境可能行为异常甚至导致React水合Hydration失败表现为页面框架存在但内容空白。卸载包npm uninstall vercel/analytics检查并清理app/layout.tsx以及所有客户端组件中对此包的导入和使用。vercel/og用于生成Open Graph图片通常与运行时无关可以保留。4. 简化next.config.ts移除所有为Vercel或特定环境设置的、可能干扰Cloudflare构建的配置。// next.config.ts /** type {import(next).NextConfig} */ const nextConfig { // 移除 distDir 配置Cloudflare Pages有固定的目录结构 // distDir: .next, // 删除或注释掉这行 // 移除与turbopack相关的开发配置如果存在 // experimental: { turbopack: { resolveAlias: {...} } } // 删除 }; export default nextConfig;3.3 构建、部署与上线流程1. 配置构建脚本更新package.json中的scripts部分集成自动化部署流程。{ scripts: { build: next build, // 原有的Next.js构建命令 pages:build: npx opennextjs/cloudflare build, // 生成Cloudflare适配的构建产物 pages:deploy: npm run pages:build node scripts/cf-deploy.js --project-name your-awesome-app, preview: npx opennextjs/cloudflare build npx wrangler pages dev .open-next } }2. 部署脚本 (cf-deploy.js) 的工作流程理解这个脚本在做什么有助于在出错时进行调试。检查确认.open-next目录已由pages:build生成。组装创建一个新的.deploy临时目录。将.open-next/assets/下的所有内容主要是_next静态文件夹复制进去。将.open-next/下的其他关键子目录server-functions/,cloudflare/,middleware/也复制进去。将.open-next/worker.js复制并重命名为_worker.js放在.deploy根目录。部署执行wrangler pages deploy .deploy --project-name your-awesome-app命令。清理部署成功后删除.deploy临时目录。3. 设置生产环境机密本地开发的变量在.dev.vars中生产环境需要通过Wrangler命令行上传。# 在项目根目录执行 echo your-production-database-url | npx wrangler pages secret put DATABASE_URL --project-name your-awesome-app echo your-production-api-key | npx wrangler pages secret put NEXT_PUBLIC_API_KEY --project-name your-awesome-app这些秘密值会被加密存储并注入到生产环境的Pages Worker中通过process.env.VAR_NAME访问。4. 执行部署运行一条命令完成构建和部署。npm run pages:deploy命令行会输出构建和上传进度。成功后你会获得一个*.pages.dev的预览URL。在Cloudflare仪表板的Pages服务中你也能看到这次部署记录。5. 配置自定义域名可选如果你有自己的域名在Cloudflare Pages项目的设置中添加自定义域名并按照提示修改DNS记录通常是一个CNAME记录。references/dns.md文件里提供了通过API自动化此过程的思路。4. 疑难杂症排查与性能调优4.1 常见问题与即时解决方案即使按照指南操作你可能还是会遇到一些棘手的问题。下面这个表格是我根据经验和社区反馈整理的快速排查清单现象可能原因排查步骤与解决方案部署成功但访问页面全是404Worker组装不正确_worker.js未找到或依赖缺失。1. 确认使用了cf-deploy.js脚本。2. 检查.deploy目录部署前是否包含_worker.js以及server-functions等文件夹。3. 在Cloudflare仪表板中查看Pages项目的“部署详情”-“函数日志”看是否有运行时错误。API路由返回500错误无详细日志代码中残留export const runtime edge;。使用全局搜索确认所有route.ts文件中已移除该行声明。页面部分交互失效控制台有Hydration错误客户端组件中使用了不兼容的第三方库如未清理的vercel/analytics。1. 检查浏览器开发者控制台的错误信息。2. 使用npm ls检查并移除所有Vercel特有的前端包。3. 尝试将可疑组件用dynamic导入并设置{ ssr: false }进行隔离测试。数据库查询返回奇怪的对象{type:text,value:...}使用了原始的Turso HTTP API响应未进行数据提取。确保你使用了类似turso-edge.md中提供的extractValue()辅助函数来处理API返回的单元格数据。本地预览 (wrangler pages dev) 正常生产环境报错生产环境机密变量未设置或名称错误。1. 使用npx wrangler pages secret list --project-name xxx核对已设置的秘密。2. 确保代码中process.env.XXX的变量名与设置的完全一致大小写敏感。静态资源图片、CSS加载失败静态资源路径引用错误或未正确复制到部署目录。1. 检查构建后.open-next/assets目录下是否存在_next文件夹。2. 确保cf-deploy.js正确复制了assets/下的所有内容到.deploy根目录。网站样式错乱Next.js的静态资源加载基路径basePath或资产前缀配置冲突。检查next.config.js中是否配置了basePath或assetPrefix。在Cloudflare Pages上部署到根域名时通常不需要也不应配置这些。4.2 性能优化与缓存策略迁移到Cloudflare边缘网络后你可以利用其强大的缓存能力提升用户体验。1. 利用Cloudflare CDN缓存静态资源Next.js构建生成的JS、CSS、图片等静态文件默认已经通过_next/static路径提供。Cloudflare会自动缓存这些资源。你可以在Cloudflare仪表板的“规则”-“页面规则”中为你的域名添加更激进的静态资源缓存规则例如缓存所有_next/static下的资源1个月。2. 谨慎使用Next.js服务端缓存在Next.js的fetch请求中你可能见过{ next: { revalidate: 60 } }这样的配置。这是Vercel平台上的增量静态再生ISR机制。在Cloudflare Pages上这个next选项是无效的必须移除。否则它可能会阻止数据更新。替代方案是使用Cloudflare自身的缓存API在你的数据获取函数如React Server Component或Route Handler中实现边缘缓存// 在App Router的Server Component或API Route中 export const revalidate 3600; // 每3600秒1小时重新验证页面数据 // 或者在fetch时使用标准的Cache-Control头更推荐更通用 async function getData() { const res await fetch(https://api.example.com/data, { // next: { revalidate: 60 } // 删除这行 headers: { Cache-Control: public, s-maxage60, // 告诉Cloudflare边缘缓存60秒 }, }); return res.json(); }3. 优化边缘函数冷启动保持你的Server Component和API Route逻辑简洁避免巨大的依赖包。opennextjs/cloudflare会进行树摇优化但引入庞大的库如某些全量的UI组件库仍会增加Worker的体积和冷启动时间。考虑按需引入或使用更轻量的替代方案。5. 进阶技巧与生态整合思考5.1 将部署流程集成到CI/CD对于团队项目自动化部署是必须的。你可以将pages:deploy脚本集成到GitHub Actions、GitLab CI等流程中。以下是一个GitHub Actions工作流的简单示例# .github/workflows/deploy-to-cf-pages.yml name: Deploy to Cloudflare Pages on: push: branches: [ main ] jobs: deploy: runs-on: ubuntu-latest permissions: contents: read deployments: write steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 20 cache: npm - name: Install Dependencies run: npm ci - name: Build and Deploy run: npm run pages:deploy env: CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} # 其他构建时需要的环境变量你需要在你代码仓库的Settings - Secrets and variables - Actions中添加一个名为CLOUDFLARE_API_TOKEN的密钥其值是在Cloudflare面板创建的、具有Pages编辑权限的API令牌。5.2 与OpenClaw AI智能体协同工作可选这个项目的初衷是作为一个OpenClaw Skill。如果你使用OpenClaw安装此技能后你可以用自然语言指挥AI助手完成部署工作“将我当前的项目部署到Cloudflare Pages。”“帮我配置生产环境的数据库连接密钥。”“从Vercel迁移这个Next.js应用到Cloudflare需要注意什么”AI会基于这个技能包里的知识SKILL.md来执行操作或给出建议极大简化了复杂流程的记忆负担。即使你不常用AI助手将这些操作沉淀为可重复执行的脚本和清单本身也是工程效率的提升。5.3 监控与日志分析部署上线只是开始监控运行状态至关重要。Cloudflare Pages提供了基础的函数日志你可以在每个部署的详情页查看。对于更复杂的调试可以考虑使用console.log在Server Component和API Route中输出的日志可以在Cloudflare仪表板的“Workers Pages” - 你的项目 - “日志”中查看。集成错误监控使用像Sentry这样的服务其Cloudflare Workers SDK可以捕获并上报运行时错误。性能监控Cloudflare自身的Analytics提供了关于请求量、缓存命中率、边缘性能的宏观数据对于评估迁移效果很有帮助。整个迁移过程从技术选型、代码改造、自动化部署到上线后的优化是一个系统工程。这个openclaw-skill-cloudflare项目提供了一套经过实战检验的“脚手架”和“避坑地图”。我的体会是最大的挑战往往不是技术本身而是那些未被明确记录的细节差异和隐性冲突。按照这份指南系统地处理每一个环节能够将迁移的风险和不确定性降到最低最终在Cloudflare的全球边缘网络上获得一个快速、稳定且成本可控的应用部署方案。如果在具体操作中遇到表格未覆盖的怪问题回头检查“代码改造”部分和构建部署日志十有八九能找到线索。
Next.js 16+ 项目迁移 Cloudflare Pages 实战：避坑指南与自动化部署
发布时间：2026/6/26 13:12:49
1. 项目概述一个专为Next.js部署到Cloudflare的“智能工具箱”如果你正在为一个Next.js项目寻找Vercel之外的部署方案尤其是看中了Cloudflare Pages的全球边缘网络和免费额度但又被官方迁移工具对Next.js 16支持不佳、各种隐晦的报错和文档缺失搞得焦头烂额那么这个项目可能就是为你准备的。它不是另一个泛泛的教程而是一个从真实、复杂的生产迁移中淬炼出来的“实战工具箱”。这个名为metasal1/openclaw-skill-cloudflare的项目核心是一个为OpenClaw AI智能体设计的“技能”Skill。但即便你完全不使用OpenClaw它里面打包的脚本、配置模板和避坑指南其价值也远超一个普通的工具库。它直击两个最痛的痛点一是如何将基于App Router的现代Next.js应用特别是16版本稳定、正确地部署到Cloudflare Pages二是如何解决在此过程中必然会遇到的、官方文档语焉不详的那些“坑”比如边缘数据库Turso的适配、API路由的运行时冲突、以及那个导致部署后全是404的“Worker组装问题”。我自己在迁移一个中型Next.js 15项目到Cloudflare Pages时几乎踩遍了这里提到的所有雷。项目作者将这些经验系统化形成了包含完整检查清单、自动化部署脚本和关键组件替换方案的“迁移剧本”。接下来我会带你深入拆解这个工具箱的每一部分不仅告诉你“怎么做”更会解释“为什么必须这么做”以及我在类似场景下验证过的那些细节。2. 核心迁移策略与工具选型解析2.1 为什么是opennextjs/cloudflare而非官方适配器这是整个迁移的基石选错工具后续所有工作都可能白费。Cloudflare官方提供的cloudflare/next-on-pages适配器在Next.js 15及更早版本上表现尚可但它对Next.js 16的支持存在滞后性和兼容性问题。根据社区反馈和实际测试在Next.js 16上使用它你可能会遇到构建失败、运行时错误或部分App Router特性无法使用的情况。opennextjs/cloudflare是一个社区维护的替代方案它诞生的目的就是为了更好地支持Next.js的现代特性尤其是App Router和更新版本。它的工作原理与官方适配器不同它通过一个更深入的转换过程将Next.js的构建输出包括服务端组件、路由处理器等打包成与Cloudflare Workers和Pages环境高度兼容的格式。简单来说它更像一个“翻译官”能更准确地理解Next.js 16的“语言”并将其“翻译”成Cloudflare边缘运行时能高效执行的“语言”。关键决策点如果你的项目基于Next.js 16或更新版本opennextjs/cloudflare是目前更可靠的选择。它的迭代速度通常能跟上Next.js的更新节奏社区活跃遇到问题时也更容易找到解决方案。2.2 项目结构深度解读什么才是“开箱即用”这个技能包的文件结构非常精简但每一部分都针对一个具体痛点scripts/cf-deploy.js这是项目的“灵魂”。为什么需要它因为opennextjs/cloudflare构建后输出文件是分散在.open-next/目录下的一个模块化结构。而wrangler pages deploy命令期望上传的是一个包含所有依赖的、扁平化的目录。直接部署.open-next/会导致Worker找不到动态导入的模块从而引发404错误。这个脚本自动化了文件收集、重命名worker.js-_worker.js和目录组装的过程是部署成功的关键。references/turso-edge.md这是解决数据库问题的“钥匙”。在边缘运行时Edge Runtime中许多传统的Node.js数据库客户端包括Turso的官方libsql/client无法工作因为它们依赖了Node.js特有的API如fs,net模块。这份参考文档提供了一个基于原生fetchAPI的、轻量级的Turso HTTP客户端实现是边缘函数与Turso数据库通信的可行方案。references/dns.md虽然迁移主要关注部署但将域名指向新的Cloudflare Pages站点是上线前的最后一步。这份指南整理了通过Cloudflare API管理DNS记录的常见模式便于自动化或作为手动操作的参考。这种结构反映了一个务实的原则不提供大而全的框架而是提供解决关键障碍的精准工具和文档。3. 逐步迁移实操手册与避坑指南3.1 环境准备与基础配置在开始之前请确保你拥有一个Cloudflare账户并且已经将你的域名添加到Cloudflare中管理或者你打算使用Cloudflare分配的*.pages.dev子域名。首先在你的Next.js项目根目录下安装必要的依赖npm install -D opennextjs/cloudflare wrangler这里安装的是开发依赖-D因为适配器和CLI工具只在构建和部署阶段需要。接下来创建项目核心配置文件。1. 创建wrangler.jsonc这个文件告诉Wrangler工具如何管理你的Pages项目。使用.jsonc格式允许添加注释更清晰。{ $schema: node_modules/wrangler/config-schema.json, name: your-awesome-app, // 你的项目名称会体现在Cloudflare仪表板中 pages_build_output_dir: .open-next/assets, // 关键指向适配器生成的静态资源目录 compatibility_date: 2025-04-01, // 使用一个较新的兼容日期以支持最新特性 compatibility_flags: [nodejs_compat] // 启用Node.js兼容模式许多NPM包需要它 }2. 创建open-next.config.ts这是opennextjs/cloudflare适配器本身的配置文件。对于大多数项目默认配置即可。import { defineConfig } from opennextjs/cloudflare; export default defineConfig({ // 目前可以留空使用默认配置。 // 未来如果需要自定义中间件行为、缓存规则等可以在这里配置。 });3. 处理环境变量文件.dev.varsCloudflare Pages在开发和生产环境使用不同的机制管理秘密值。本地开发时Wrangler会读取.dev.vars文件。# .dev.vars DATABASE_URL你的Turso数据库连接URL NEXT_PUBLIC_API_KEY你的公开API密钥 NEXTJS_ENVproduction # 确保Next.js以生产模式运行重要提示务必立即将.dev.vars添加到.gitignore文件中避免敏感信息泄露。# .gitignore 追加 .open-next/ .deploy/ .dev.vars3.2 代码改造移除不兼容的“钉子户”这是迁移中最需要细心的一步涉及对现有代码的修改。1. 清理API路由的运行时配置在App Router中你可能会在app/api/.../route.ts文件中看到export const runtime edge;这样的声明目的是让该API在Vercel的边缘网络上运行。然而opennextjs/cloudflare适配器不支持这种显式的edge runtime声明。如果保留API路由会悄无声息地返回500错误。操作你需要移除所有API路由文件中的这行代码。可以使用命令行工具批量操作操作前建议备份# 在项目根目录执行 # macOS: find . -name route.ts -path */api/* -exec sed -i /export const runtime edge;/d {} \; # Linux: find . -name route.ts -path */api/* -exec sed -i /export const runtime edge;/d {} \;手动检查几个重要的API路由文件确认该行已被移除。2. 替换Turso数据库客户端如前所述libsql/client在边缘运行时中会失败。你需要参考项目中的turso-edge.md实现一个基于HTTP的客户端。这里提供一个简化的示例展示核心思路// lib/turso-edge.ts export async function execute(sql: string, params: any[] []) { const url https://${process.env.TURSO_DB_NAME}-${process.env.TURSO_ORG}.turso.io/v2/pipeline; const response await fetch(url, { method: POST, headers: { Authorization: Bearer ${process.env.TURSO_AUTH_TOKEN}, Content-Type: application/json, }, body: JSON.stringify({ requests: [{ type: execute, stmt: { sql, args: params } }] }) }); const result await response.json(); // Turso HTTP API返回的数据结构需要处理 const rows result.results?.[0]?.response?.result?.rows || []; // 转换数据格式使其接近原客户端的返回结构 return { rows: rows.map(row row.map(cell cell.value)) }; }3. 移除Vercel特定包vercel/analytics等Vercel生态的包在非Vercel环境可能行为异常甚至导致React水合Hydration失败表现为页面框架存在但内容空白。卸载包npm uninstall vercel/analytics检查并清理app/layout.tsx以及所有客户端组件中对此包的导入和使用。vercel/og用于生成Open Graph图片通常与运行时无关可以保留。4. 简化next.config.ts移除所有为Vercel或特定环境设置的、可能干扰Cloudflare构建的配置。// next.config.ts /** type {import(next).NextConfig} */ const nextConfig { // 移除 distDir 配置Cloudflare Pages有固定的目录结构 // distDir: .next, // 删除或注释掉这行 // 移除与turbopack相关的开发配置如果存在 // experimental: { turbopack: { resolveAlias: {...} } } // 删除 }; export default nextConfig;3.3 构建、部署与上线流程1. 配置构建脚本更新package.json中的scripts部分集成自动化部署流程。{ scripts: { build: next build, // 原有的Next.js构建命令 pages:build: npx opennextjs/cloudflare build, // 生成Cloudflare适配的构建产物 pages:deploy: npm run pages:build node scripts/cf-deploy.js --project-name your-awesome-app, preview: npx opennextjs/cloudflare build npx wrangler pages dev .open-next } }2. 部署脚本 (cf-deploy.js) 的工作流程理解这个脚本在做什么有助于在出错时进行调试。检查确认.open-next目录已由pages:build生成。组装创建一个新的.deploy临时目录。将.open-next/assets/下的所有内容主要是_next静态文件夹复制进去。将.open-next/下的其他关键子目录server-functions/,cloudflare/,middleware/也复制进去。将.open-next/worker.js复制并重命名为_worker.js放在.deploy根目录。部署执行wrangler pages deploy .deploy --project-name your-awesome-app命令。清理部署成功后删除.deploy临时目录。3. 设置生产环境机密本地开发的变量在.dev.vars中生产环境需要通过Wrangler命令行上传。# 在项目根目录执行 echo your-production-database-url | npx wrangler pages secret put DATABASE_URL --project-name your-awesome-app echo your-production-api-key | npx wrangler pages secret put NEXT_PUBLIC_API_KEY --project-name your-awesome-app这些秘密值会被加密存储并注入到生产环境的Pages Worker中通过process.env.VAR_NAME访问。4. 执行部署运行一条命令完成构建和部署。npm run pages:deploy命令行会输出构建和上传进度。成功后你会获得一个*.pages.dev的预览URL。在Cloudflare仪表板的Pages服务中你也能看到这次部署记录。5. 配置自定义域名可选如果你有自己的域名在Cloudflare Pages项目的设置中添加自定义域名并按照提示修改DNS记录通常是一个CNAME记录。references/dns.md文件里提供了通过API自动化此过程的思路。4. 疑难杂症排查与性能调优4.1 常见问题与即时解决方案即使按照指南操作你可能还是会遇到一些棘手的问题。下面这个表格是我根据经验和社区反馈整理的快速排查清单现象可能原因排查步骤与解决方案部署成功但访问页面全是404Worker组装不正确_worker.js未找到或依赖缺失。1. 确认使用了cf-deploy.js脚本。2. 检查.deploy目录部署前是否包含_worker.js以及server-functions等文件夹。3. 在Cloudflare仪表板中查看Pages项目的“部署详情”-“函数日志”看是否有运行时错误。API路由返回500错误无详细日志代码中残留export const runtime edge;。使用全局搜索确认所有route.ts文件中已移除该行声明。页面部分交互失效控制台有Hydration错误客户端组件中使用了不兼容的第三方库如未清理的vercel/analytics。1. 检查浏览器开发者控制台的错误信息。2. 使用npm ls检查并移除所有Vercel特有的前端包。3. 尝试将可疑组件用dynamic导入并设置{ ssr: false }进行隔离测试。数据库查询返回奇怪的对象{type:text,value:...}使用了原始的Turso HTTP API响应未进行数据提取。确保你使用了类似turso-edge.md中提供的extractValue()辅助函数来处理API返回的单元格数据。本地预览 (wrangler pages dev) 正常生产环境报错生产环境机密变量未设置或名称错误。1. 使用npx wrangler pages secret list --project-name xxx核对已设置的秘密。2. 确保代码中process.env.XXX的变量名与设置的完全一致大小写敏感。静态资源图片、CSS加载失败静态资源路径引用错误或未正确复制到部署目录。1. 检查构建后.open-next/assets目录下是否存在_next文件夹。2. 确保cf-deploy.js正确复制了assets/下的所有内容到.deploy根目录。网站样式错乱Next.js的静态资源加载基路径basePath或资产前缀配置冲突。检查next.config.js中是否配置了basePath或assetPrefix。在Cloudflare Pages上部署到根域名时通常不需要也不应配置这些。4.2 性能优化与缓存策略迁移到Cloudflare边缘网络后你可以利用其强大的缓存能力提升用户体验。1. 利用Cloudflare CDN缓存静态资源Next.js构建生成的JS、CSS、图片等静态文件默认已经通过_next/static路径提供。Cloudflare会自动缓存这些资源。你可以在Cloudflare仪表板的“规则”-“页面规则”中为你的域名添加更激进的静态资源缓存规则例如缓存所有_next/static下的资源1个月。2. 谨慎使用Next.js服务端缓存在Next.js的fetch请求中你可能见过{ next: { revalidate: 60 } }这样的配置。这是Vercel平台上的增量静态再生ISR机制。在Cloudflare Pages上这个next选项是无效的必须移除。否则它可能会阻止数据更新。替代方案是使用Cloudflare自身的缓存API在你的数据获取函数如React Server Component或Route Handler中实现边缘缓存// 在App Router的Server Component或API Route中 export const revalidate 3600; // 每3600秒1小时重新验证页面数据 // 或者在fetch时使用标准的Cache-Control头更推荐更通用 async function getData() { const res await fetch(https://api.example.com/data, { // next: { revalidate: 60 } // 删除这行 headers: { Cache-Control: public, s-maxage60, // 告诉Cloudflare边缘缓存60秒 }, }); return res.json(); }3. 优化边缘函数冷启动保持你的Server Component和API Route逻辑简洁避免巨大的依赖包。opennextjs/cloudflare会进行树摇优化但引入庞大的库如某些全量的UI组件库仍会增加Worker的体积和冷启动时间。考虑按需引入或使用更轻量的替代方案。5. 进阶技巧与生态整合思考5.1 将部署流程集成到CI/CD对于团队项目自动化部署是必须的。你可以将pages:deploy脚本集成到GitHub Actions、GitLab CI等流程中。以下是一个GitHub Actions工作流的简单示例# .github/workflows/deploy-to-cf-pages.yml name: Deploy to Cloudflare Pages on: push: branches: [ main ] jobs: deploy: runs-on: ubuntu-latest permissions: contents: read deployments: write steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 20 cache: npm - name: Install Dependencies run: npm ci - name: Build and Deploy run: npm run pages:deploy env: CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} # 其他构建时需要的环境变量你需要在你代码仓库的Settings - Secrets and variables - Actions中添加一个名为CLOUDFLARE_API_TOKEN的密钥其值是在Cloudflare面板创建的、具有Pages编辑权限的API令牌。5.2 与OpenClaw AI智能体协同工作可选这个项目的初衷是作为一个OpenClaw Skill。如果你使用OpenClaw安装此技能后你可以用自然语言指挥AI助手完成部署工作“将我当前的项目部署到Cloudflare Pages。”“帮我配置生产环境的数据库连接密钥。”“从Vercel迁移这个Next.js应用到Cloudflare需要注意什么”AI会基于这个技能包里的知识SKILL.md来执行操作或给出建议极大简化了复杂流程的记忆负担。即使你不常用AI助手将这些操作沉淀为可重复执行的脚本和清单本身也是工程效率的提升。5.3 监控与日志分析部署上线只是开始监控运行状态至关重要。Cloudflare Pages提供了基础的函数日志你可以在每个部署的详情页查看。对于更复杂的调试可以考虑使用console.log在Server Component和API Route中输出的日志可以在Cloudflare仪表板的“Workers Pages” - 你的项目 - “日志”中查看。集成错误监控使用像Sentry这样的服务其Cloudflare Workers SDK可以捕获并上报运行时错误。性能监控Cloudflare自身的Analytics提供了关于请求量、缓存命中率、边缘性能的宏观数据对于评估迁移效果很有帮助。整个迁移过程从技术选型、代码改造、自动化部署到上线后的优化是一个系统工程。这个openclaw-skill-cloudflare项目提供了一套经过实战检验的“脚手架”和“避坑地图”。我的体会是最大的挑战往往不是技术本身而是那些未被明确记录的细节差异和隐性冲突。按照这份指南系统地处理每一个环节能够将迁移的风险和不确定性降到最低最终在Cloudflare的全球边缘网络上获得一个快速、稳定且成本可控的应用部署方案。如果在具体操作中遇到表格未覆盖的怪问题回头检查“代码改造”部分和构建部署日志十有八九能找到线索。
