SuperAPI AI 工具集

migrate-to-vinext

编程与开发

查看项目

更新于 10-15 19:50

技能介绍

用途:把 Next.js 项目迁移到 vinext。vinext 在 Vite 上重实现 Next.js API,现有 app/、pages/ 与 next.config.js 可原样工作,迁移只需换包、生成配置并转为 ESM,无需修改应用代码。

前置检查:确认 package.json 的 dependencies 或 devDependencies 含 next,否则不适用。按锁文件判断包管理器(pnpm-lock.yaml→pnpm,yarn.lock→yarn,bun.lockb/bun.lock→bun,package-lock.json 或无→npm)。根目录或 src/ 下有 app/ 即 App Router,仅有 pages/ 即 Pages Router,两者可共存。

主要命令:vinext check 扫描兼容性并给出评分报告;vinext init 自动迁移(装依赖、生成配置、转 ESM);npx vite dev 开发服务器;npx vite build 生产构建;vinext start 本地生产服务器;npx @vinext/cloudflare deploy 或 vp exec vinext-cloudflare deploy 构建并部署到 Cloudflare Workers。

流程:先运行 vinext check 查看报告,存在严重不兼容时先告知用户。推荐运行 vinext init,它会执行兼容检查、安装 vite(App Router 另装 @vitejs/plugin-rsc)、在 package.json 加 "type": "module"、把 CJS 配置重命名为 .cjs、添加 dev:vinext 与 build:vinext 脚本、生成最小 vite.config.ts、把 /dist/ 与 .vinext/ 加入 .gitignore;该过程非破坏性,原 Next.js 配置仍可用。若 init 失败或需手动控制,则手动替换包(卸载 next、安装 vinext 与 vite)、更新脚本(next dev→vite dev、next build→vite build、next start→vinext start、next lint→vinext lint)、转 ESM、生成 vite.config.ts 并更新 .gitignore。

部署:Cloudflare Workers 推荐用原生集成,通过 import { env } from "cloudflare:workers" 访问 D1、R2、KV、AI 等绑定,绑定需在 wrangler.jsonc 定义,类型用 wrangler types 生成;不要用 getPlatformProxy()、getRequestContext() 或自定义 worker 入口。其他平台可加 Nitro Vite 插件,用 NITRO_PRESET=vercel/netlify/deno_deploy/node npx vite build 构建。

限制:next/image 远程图走 @unpic、无构建期优化;next/font/google 走 CDN 非自托管;不支持基于域名的 i18n(路径前缀可用);不支持 next/jest,改用 Vitest;Turbopack/webpack 配置被忽略,改用 Vite 插件;runtime/preferredRegion 放置被忽略;PPR 改用 "use cache"。不要改写 next/* 导入,不要复制 webpack 配置,不要删除 next.config.js(除非替换为 .ts/.mjs)。