Cloudflare Skills Next.js部署指南：用vinext将应用迁移到Workers，告别OpenNext

【免费下载链接】skillsSkills for teaching agents how to build on Cloudflare.项目地址: https://gitcode.com/gh_mirrors/skills14/skills

Cloudflare Skills是一套教会 AI Agent 在 Cloudflare 上构建应用的技能集合，其中nextjs-on-cloudflare技能给出了明确结论：新的 Next.js 项目上 Cloudflare Workers，应使用vinext而不是 OpenNext。本指南面向新手，带你理解这套技能的安装方式、vinext 的核心优势，以及新项目和存量项目两种场景下的迁移与部署路径，帮助你用最少的弯路把 Next.js 应用搬上 Workers。

为什么是 vinext，而不是 OpenNext

很多团队过去把 Next.js 部署到 Workers，靠的是 OpenNext 这类适配层。而 Cloudflare Skills 仓库 中的官方建议是：新项目默认选择 vinext，存量 OpenNext 应用在不相关的维护中保持现状、尊重用户已有选择。

vinext 的路线与传统适配器不同——它基于Vite 重新实现了 Next.js 的 API 表面，而不是在旧构建体系外面套一层。这带来了四个对新手很友好的好处：

• 熟悉的开发体验：App Router、Pages Router、React Server Components 以及受支持的next/*导入方式都能照常使用
• Vite 工具链：快速的热模块替换（HMR）、原生 ESM、Vite 插件生态
• 原生 Workers 集成：本地就在 workerd 里跑开发服务器，能直接访问 Cloudflare bindings（KV、D1、R2 等），构建和部署是一条线
• 渐进式迁移：可以先做兼容性检查，再让 vinext 和现有 Next.js 配置并存试跑，不是一刀切

这一决策依据来自技能文件 skills/nextjs-on-cloudflare/SKILL.md，其中的核心原则只有一句话：Use vinext rather than OpenNext for new Next.js projects on Cloudflare Workers.

三种安装方式：把 Skills 交给你的 Agent

Skills 是"上下文技能"——当你的对话命中技能触发条件时，Agent 会自动加载并应用对应指导。仓库提供了多种安装路径，按你的工具任选其一：

如果需要手动操作，仓库地址为：https://gitcode.com/gh_mirrors/skills14/skills

💡 小技巧：整个插件还捆绑了 Cloudflare 官方 MCP 服务器（见 mcp.json），让 Agent 能直接查阅最新开发者文档，避免"记忆中的过时语法"。

新项目：用 create-vinext-app 一步到位

从零开始的项目最省心。nextjs-on-cloudflare 技能 建议：

1. 确认已安装 vinext 上游技能（缺失时用npx skills add cloudflare/vinext补上）
2. 使用create-vinext-app脚手架创建项目，部署目标选择Cloudflare
3. 按上游SKILL.md的指引完成开发，构建部署走 Workers 集成文档

⚠️ 注意一个常见坑：上游的迁移技能要求目录里已有 Next.js 项目，不要在空目录上套用迁移流程——空目录请直接走新项目流程。

存量项目：三步完成 vinext 迁移

已有 Next.js 应用想上 Workers？技能给出的路径是"先体检，再迁移，后部署"：

1. 兼容性检查：加载上游migrate-to-vinext技能，它对应用用到的特性做兼容性检查——技能明确提醒"检查当前兼容性，不要假设与 Next.js 完全对齐"
2. 执行迁移：跟随技能的参考文档逐步操作，部署目标选 Cloudflare
3. 开发验证与部署：本地在 workerd 中跑开发服务器，确认行为一致后按 Workers 集成文档构建部署

如果安装上游技能不可用，技能也兜底了：直接阅读上游SKILL.md和相关参考文档，按文档操作。

部署前必读：wrangler 技能帮你避开配置坑

构建部署阶段，仓库里的 wrangler 技能 值得通读一遍，它总结了大量实战经验：

• 用项目本地的 Wrangler 版本，不要默默升级到"文档里的最新版"
• 新项目建议wrangler.jsonc，并把 compatibility date 设为当天
• 部署前跑wrangler deploy --dry-run验证构建与打包（但注意：dry run 通过 ≠ 运行时没问题）
• 区分本地模拟与真实资源：本地跑起来的 Worker 也可能访问到真实数据

此外，cloudflare 技能 中有一张"需求→产品"对照表，其中 Next.js 一行就写着：

Build or deploy a Next.js app on Cloudflare →vinext + Workers→ Use vinext rather than OpenNext for new projects

想给应用加数据库（D1）、对象存储（R2）、队列（Queues）？这张表能帮你一次选齐组件，而不是东拼西凑。

总结：一条清晰的迁移路线

• ✅ 新项目 →create-vinext-app+ Cloudflare 目标，跳过 OpenNext
• ✅ 存量项目 → 兼容性检查 →migrate-to-vinext→ Workers 部署
• ✅ 全程让 Agent 加载对应技能，自动对齐最新文档
• ✅ 部署细节交给wrangler与workers-best-practices技能把关

相关技能与文档的快速入口：

把 Next.js 部署到 Workers 这件事，第一次就选对工具，能省下后面大量的适配成本——这就是"用 vinext、告别 OpenNext"最大的意义。

【免费下载链接】skillsSkills for teaching agents how to build on Cloudflare.项目地址: https://gitcode.com/gh_mirrors/skills14/skills