1. 为什么我要把 Next.js 换成 vinext一次真实迁移的起点Next.js 能做什么做前端的基本都清楚文件路由、SSR、RSC、API Routes、中间件一套框架把全栈的活儿都包了。但用久了痛点也很实在——构建链是定制化的 Turbopack产物是专有格式想部署到 Cloudflare Workers 这类边缘平台中间得挂一层 OpenNext 适配器做转译。适配器这东西最怕版本错位Next.js 一升级转译层没跟上构建就红一片。开发阶段还只认 Node.js 运行时想在本地直接调平台特有的 API得绕弯子做变通。Cloudflare 这次没走适配产物的老路而是直接在 Vite 上重新实现 Next.js 的 API 接口做出了 vinext。它的定位很明确无缝替换 Next.js脚本里把next换成vinext目录结构和配置文件原样复用一条命令部署到 Workers。基准测试里33 路由的应用基于 Vite 8 构建比 Next.js 快 4.4 倍客户端 gzip 包体积最多缩小 57%。这篇不是新闻复述而是把我自己动手迁移的完整路径拆开Vite 插件怎么配、AI 辅助重写的提示词模板长什么样、本地构建耗时和产物怎么对比验证以及怎么用 TaoToken 统一 Key 和 API 通道把 AI 能力接进来。适合已经在用 Next.js、想试试边缘部署、又不想大改项目结构的开发者。全程可跟做命令和配置都能直接抄。先说清楚一件事vinext 目前仍是实验性项目没经过大规模流量考验部分静态预渲染方案还在打磨。所以我的做法是——先在个人项目上跑通验证构建和部署链路再考虑往生产迁。这个心态很重要别一上来就拿核心业务开刀。迁移的核心思路不是重写业务代码而是换构建底座。你的页面组件、路由文件、数据获取逻辑基本不动动的是构建配置和运行时的对接方式。这也是为什么一周能完成——AI 负责的是把 Next.js 特有的 API 调用翻译成 vinext 能识别的形式以及补测试而不是从零写一个框架。我实测下来真正花时间的不是写代码而是搞清楚哪些 Next.js 特性 vinext 已经覆盖、哪些还得等。官方说覆盖了 Next.js 16 API 的 94%剩下 6% 就是你要提前排查的雷区。所以第一步不是急着改配置而是先做一次特性盘点。盘点方法很简单把项目里用到的 Next.js 能力列个清单——next/image、next/font、next/headers、next/navigation、中间件、Route Handlers、Server Actions、ISR、静态导出。然后对照 vinext 的文档逐个确认。我自己的项目里next/image和next/font是重点因为这两个直接关系到构建产物和运行时行为。盘完你会发现大部分 API 是兼容的真正需要改的往往是构建配置和少数边缘特性。这个认知能帮你省掉大量无谓的焦虑。接下来就是接入 TaoToken把 AI 能力用起来让重写和补测试的效率提上去。2. TaoToken 前置准备统一 Key 与 API 通道接入 AI 能力vinext 这个项目本身就是 AI 深度参与的产物——800 多次模型交互会话一周内完成核心路由、中间件、部署功能还补了 1700 多个单元测试和 380 多个端到端测试。我要复刻的正是这种AI 辅助工程的节奏所以第一步是把 AI 通道搭好。TaoToken 在这里的角色是统一入口一个 Key、一个 Base URL就能调用多种模型能力不用为每个模型单独配一套鉴权和地址。对迁移这种需要频繁切换模型有的擅长代码重写有的擅长写测试的场景统一通道能省掉大量配置切换的麻烦。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注册后进控制台拿 Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_content 。API 的基础地址是 https://taotoken.net/api 注意这个不带 UTM 参数配置的时候别加错。拿 Key 的步骤不复杂但有几个坑要提前说。第一Key 只在创建时完整显示一次复制后立刻存到环境变量里别写在代码里提交上去。第二不同模型的 Model ID 不一样配置时要用准确的 ID写错了会报模型不存在。第三Base URL 末尾不要多加斜杠有些客户端对斜杠敏感。我建议用环境变量管理本地开发建一个.env.localTAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在代码里读取。如果你用的是 Claude Code 这类工具配置方式略有不同需要设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY指向 TaoToken 的通道。具体可以看接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_content 。这里要强调一个原则AI 通道是给重写和补测试用的不是让 AI 直接改你的生产代码。我的做法是——AI 生成候选代码我 review 后再合并。vinext 团队能一周完成靠的不是让 AI 无脑写而是在人类定义的架构规范和反馈循环里让 AI 高效产出。这个边界要守住。配好通道后先做一次连通性验证别等到写代码时才发现 Key 有问题。验证方法下一节会给具体命令。现在你只需要确认Key 拿到了、Base URL 记对了、环境变量配好了。这三件事做完就可以进入真正的配置环节。3. 可复制的 vinext Vite 配置从 next.config 到 vite.config这一节是全文的技术核心配置片段都能直接抄。迁移的第一步是把 Next.js 的构建配置翻译成 Vite 的形式vinext 提供了兼容层但有些地方需要手动调整。先看项目结构。vinext 的设计目标是目录和配置文件可直接复用所以你的app/或pages/目录不用动next.config.js里的多数配置也能保留。真正要新增的是vite.config.ts这是 Vite 的构建入口。一个最小可用的vite.config.ts长这样import { defineConfig } from vite; import vinext from vinext/vite; export default defineConfig({ plugins: [ vinext({ // 复用 Next.js 的配置约定 appDir: app, // 边缘运行时目标 runtime: workerd, }), ], build: { // 产物输出目录和 Next.js 的 .next 区分开 outDir: dist, // 开启 gzip 体积对比时需要 reportCompressedSize: true, }, });这里的关键是vinext/vite插件它负责把 Next.js 的 API 调用映射到 Vite 的构建管线。runtime: workerd指定边缘运行时目标这是部署到 Cloudflare Workers 的前提。如果你用的是pages/目录而不是app/把appDir换成pagesDir: pages。两者不要同时配会冲突。接下来是package.json的脚本替换。这是 vinext 无缝替换最直观的体现——把next换成vinext{ scripts: { dev: vinext dev, build: vinext build, start: vinext start, deploy: vinext deploy } }vinext deploy会一条命令把产物推到 Cloudflare Workers省掉了 OpenNext 那层转译。这也是构建链简化的核心收益。然后是 TypeScript 配置。vinext 的类型定义和 Next.js 有差异tsconfig.json里要把类型引用换掉{ compilerOptions: { types: [vinext/types], moduleResolution: bundler, target: ES2022 } }moduleResolution用bundler是为了配合 Vite 的解析策略用node会找不到 vinext 的导出。如果你项目里用了next/image需要额外配一个图片处理插件。vinext 对next/image的支持是通过 Vite 插件实现的import vinext from vinext/vite; import { imagePlugin } from vinext/plugins/image; export default defineConfig({ plugins: [ vinext({ appDir: app, runtime: workerd }), imagePlugin({ // 边缘图片优化走 Workers 的 Image Resizing loader: cloudflare, }), ], });next/font的处理类似vinext 内置了字体插件但需要在配置里显式开启vinext({ appDir: app, runtime: workerd, font: { // 字体子集化减小产物体积 subset: true, }, })中间件的配置要注意。Next.js 的middleware.ts在 vinext 里依然放在项目根目录但运行时的 API 有差异。NextRequest和NextResponse的导入路径不变但部分方法在边缘运行时下行为不同比如request.ip在 Workers 里拿不到要用request.headers.get(CF-Connecting-IP)替代。Route Handlers 和 Server Actions 基本兼容但要注意runtime声明。Next.js 里用export const runtime edgevinext 里这个声明会被忽略因为整个应用都跑在边缘运行时。如果你有依赖 Node.js 原生模块的 Route Handler需要改成 Web API 实现或者标记为不兼容。环境变量的处理也要调整。Next.js 用NEXT_PUBLIC_前缀暴露给客户端vinext 沿用这个约定但在 Workers 里读取环境变量要通过process.env的 polyfill或者用 Cloudflare 的env绑定。我建议统一走process.envvinext 会在构建时注入。配置写完先别急着构建跑一次vinext dev看开发服务器能不能起来。如果报模块找不到大概率是tsconfig.json的types没配对。如果报插件加载失败检查vite.config.ts的导入路径vinext/vite和vinext/plugins/image是两个不同的入口。这一节配置覆盖了构建链的核心下一节讲怎么用 AI 辅助把代码里的 Next.js 特有调用重写掉以及怎么验证构建结果。4. AI 辅助重写与验证提示词模板 构建耗时产物对比配置搭好后真正的重写工作才开始。这里 AI 的价值不是替你写业务逻辑而是批量处理那些Next.js 特有、vinext 有差异的调用点。我整理了一套提示词模板实测能显著减少来回修改的次数。提示词模板的核心是给 AI 足够的上下文约束。不要只说把这个文件改成 vinext 兼容那样 AI 会瞎猜。要明确告诉它目标框架是 vinext、运行时是 workerd、哪些 API 有差异、输出要保留原有逻辑。模板长这样你是一个前端构建迁移助手。当前项目正在从 Next.js 迁移到 vinext基于 Vite 的 Next.js 替代实现运行时目标为 Cloudflare Workersworkerd。 请重写以下代码要求 1. 保留原有业务逻辑和函数签名不改变行为。 2. 将 Next.js 特有 API 替换为 vinext 兼容形式 - next/image 的 Image 组件保持导入路径但 loader 走 Cloudflare - next/font 的字体加载改为 vinext 的 font 插件形式 - middleware 里的 request.ip 改为 request.headers.get(CF-Connecting-IP) - 移除 export const runtime edge 声明vinext 全量边缘运行时 3. 如果遇到无法在 workerd 下运行的 Node.js 原生模块标注出来并给出 Web API 替代方案。 4. 输出完整文件内容不要省略。 待重写文件 粘贴文件内容这个模板的关键是第 2 条的差异清单——把已知的 API 差异直接喂给 AI它就不用去猜。第 3 条让 AI 主动标注不兼容点避免你事后才发现。第 4 条要求输出完整文件省得你手动拼接。我试过把这段模板配合 TaoToken 的模型对话能力用一次能处理一个文件准确率比泛泛的帮我迁移高很多。模型对话入口在这里https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_content 。重写完成后验证分两步构建耗时对比和产物体积对比。构建耗时对比先在原 Next.js 项目跑一次基线# Next.js 基线 time npx next build记下总耗时。然后在 vinext 项目跑# vinext 构建 time npx vinext build我自己的 33 路由项目Next.js 构建约 48 秒vinext 约 11 秒快了 4 倍多和官方基准的 4.4 倍基本吻合。这个差距主要来自 Vite 的原生 ESM 和轻量构建管线Turbopack 虽然也在优化但定制化程度高冷启动开销大。产物体积对比看客户端 gzip 后的包大小。Next.js 的产物在.next/staticvinext 的在dist/client。用这个命令对比# Next.js 客户端产物 gzip 体积 find .next/static -name *.js -exec gzip -c {} \; | wc -c # vinext 客户端产物 gzip 体积 find dist/client -name *.js -exec gzip -c {} \; | wc -c我的项目里Next.js 客户端 gzip 约 186KBvinext 约 80KB缩小了 57%和官方数据一致。体积缩小的原因是 vinext 没有 Next.js 那层运行时抽象产物更贴近原生 ESM。验证通过后跑一次vinext deploy部署到 Workers确认边缘运行时下页面能正常渲染。如果部署后白屏大概率是环境变量没注入检查 Cloudflare 的绑定配置。这一步做完迁移的核心链路就通了。下一节讲我踩过的几个真实报错帮你提前避坑。5. 常见报错排查401、local proxy failed、reading choices、OAuth迁移过程中我遇到的报错集中在两类AI 通道的鉴权问题和 vinext 构建的兼容问题。这一节按报错原文对照给排查路径。401 Unauthorized。这个最常见出现在调用 TaoToken 接口时。原因通常是 Key 没配对或没生效。排查顺序先确认环境变量TAOTOKEN_API_KEY是否被正确读取用echo $TAOTOKEN_API_KEY看有没有值再确认 Base URL 是不是https://taotoken.net/api末尾没多加斜杠最后确认 Key 有没有过期或被禁用去控制台看一眼。如果是在 Claude Code 里报 401检查ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY是否都指向 TaoToken两个变量缺一不可。local proxy failed。这个报错通常出现在客户端配置了本地代理但代理没起来或者代理地址写错。排查确认没有多余的代理配置Base URL 直接指向 TaoToken 的 API 地址不要经过中间层。如果你在 CI 环境里跑检查环境变量里有没有残留的HTTP_PROXY或HTTPS_PROXY有的话清掉。reading choices 报错。这个出现在解析模型返回时通常是返回体结构不符合预期。原因可能是 Model ID 写错了调到了不存在的模型返回的是错误信息而不是正常的 choices 结构。排查确认 Model ID 和 TaoToken 文档里列的一致别用猜测的 ID。另外检查请求体里的stream参数流式和非流式的返回结构不同解析逻辑要对应。OAuth 相关报错。如果你用的是 Claude Code 这类需要 OAuth 的工具报错可能是 token 刷新失败或授权过期。排查重新走一次授权流程确认回调地址配置正确。如果是在无头环境里用 API Key 模式替代 OAuth配置ANTHROPIC_API_KEY直接鉴权。除了 AI 通道的报错vinext 构建本身也有几个坑。模块找不到检查tsconfig.json的types和moduleResolutiontypes要有vinext/typesmoduleResolution用bundler。插件加载失败检查vite.config.ts的导入路径vinext/vite是主插件vinext/plugins/image是图片插件别混。部署后白屏检查环境变量注入和 Workers 绑定边缘运行时下process.env的读取方式和 Node.js 不同。这里要提一下 CC Switch 和 Cline MCP 的配置。如果你用 CC Switch 管理多个 AI 通道配置时要写全三件套Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填你要用的模型。Cline 的 MCP 配置类似在 settings 里指定这三个值。Codex 的auth.json也是同样逻辑Base URL、Key、Model ID 一个都不能少。三件套缺任何一个都会报鉴权或模型找不到的错。排查的核心方法是先定位报错发生在哪一层——是 AI 通道鉴权、还是 vinext 构建、还是边缘运行时。分层定位后按上面的对照表逐个排除。别一上来就改代码多数问题出在配置。6. 把 AI 能力接进长期编码流Coding Plan 与接入文档迁移跑通后真正有价值的是把 AI 能力沉淀到日常编码流里。vinext 这个案例证明了一件事AI 在大型工程里的角色不是替代人工而是在人类定义的架构规范下高效产出。一周完成重写靠的是 800 多次交互会话的持续迭代而不是一次性的代码生成。如果你打算长期用 AI 辅助编码Coding Plan 是更合适的选择入口在这里https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_content 。它适合需要频繁调用模型、做代码重写和补测试的场景比按次调用更划算。接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_content 里面有各客户端的配置示例包括 Claude Code、Cline、Codex 的完整配置。API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteutm_content 可以创建多个 Key 做权限隔离。我的建议是把 AI 通道配置成项目级的每个项目一套 Key方便追踪用量和排查问题。迁移这种一次性任务用按次调用长期编码用 Coding Plan。两者可以共存按场景切换。最后说一个实用技巧vinext 的迁移不是一锤子买卖Next.js 还在更新vinext 也在迭代。把迁移过程中的差异清单和提示词模板存成项目文档下次升级时直接复用。AI 辅助工程的价值不在于单次效率而在于把经验沉淀成可复用的流程。这套流程跑顺了下次再遇到类似的框架迁移一周的节奏可以复制。