快速开始

启动你的 vinext 项目

请使用下方的官方初始化命令。它们是创建或迁移 vinext 项目的推荐方式， 因为它们会替你配置依赖、scripts、Vite 以及部署目标。

pnpm create vinext-app@latest my-app

npx vinext init

该 skill 可以与 Claude Code、OpenCode、Cursor、Codex 以及数十种其他 AI 编程工具配合使用：

npx skills add cloudflare/vinext

然后在任意受支持的工具中打开你的 Next.js 项目并输入：

migrate this project to vinext

该 skill 会处理兼容性检查、依赖安装、配置生成，以及开发服务器启动。它了解 vinext 支持哪些能力，并会标记出需要人工介入的地方。

npm install vinext
npm install -D vite @vitejs/plugin-react

npm install react-server-dom-webpack
npm install -D @vitejs/plugin-rsc

import { defineConfig } from "vite";
import vinext from "vinext";

export default defineConfig({
  plugins: [vinext()],
});

3. 用 Vite 进行开发与构建

{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "start": "vinext start"
  }
}

npx vite dev        # 带 HMR 的开发服务器
npx vite build      # 生产构建
npx @vinext/cloudflare deploy  # 构建并部署到 Cloudflare Workers

你已有的 pages/、app/、next.config.js、public/目录都可以原样工作。先运行 vinext check扫描已知兼容性问题，或使用 vinext init 来自动化完成整次迁移。

vinext dev 与vinext build仍然作为项目本地 Vite 命令的轻量别名存在。它们需要一个 Vite 配置；如果缺失，请先运行vinext init。 这两个命令的选项、输出与退出行为都由 Vite 掌管。对于较早配置好的项目，这些别名仍会在 Vite 读取配置前预加载 dotenv， 并在某个明确的默认 Vite 配置需要 ESM 迁移时添加"type": "module"（把已知的 CommonJS 配置文件重命名为 .cjs）。 显式的 "type": "commonjs"永远不会被改动。直接使用 vite dev 与vite build 不会执行这些包装层兼容性步骤。

node dist/standalone/server.js

新项目请使用 create-vinext-app。 它会创建一个带 Tailwind CSS 的 TypeScript App Router 项目，然后运行与已有应用相同的 vinext init 流程：

pnpm create vinext-app@latest my-app

生成的项目默认已准备好部署到 Cloudflare Workers。如果你想要 Node 目标，传入--platform=node。

1. 1

   运行 vinext check 扫描兼容性问题

2. 2

   将 vinext 运行时包安装为依赖，将 Vite/插件工具安装为 devDependencies

3. 3

   把 CJS 配置文件（例如 postcss.config.js → .cjs）重命名以避免 ESM 冲突

4. 4

   向 package.json 添加 "type": "module"

5. 5

   向 package.json 添加 dev:vinext、build:vinext、start:vinext 脚本

6. 6

   提示选择部署平台（默认 Cloudflare，或 Node）

7. 7

   生成对应的 vite.config.ts

8. 8

   对于 Cloudflare，为 cf 与 Cloudflare Vite plugin v2 生成 cloudflare.config.ts

npm run dev:vinext    # 启动 vinext 开发服务器（端口 3001）
npm run build:vinext  # 用 vinext 构建生产输出
npm run start:vinext  # 启动 vinext 生产服务器
npm run dev           # 仍像以前一样运行 Next.js

vinext 面向 Vite 8，后者默认使用 Rolldown、Oxc、Lightning CSS，以及更新的浏览器基线。 如果你从更旧的配置带来自定义的 Vite 配置或插件，请优先使用oxc、optimizeDeps.rolldownOptions、build.rolldownOptions， 而非旧的 esbuild 与build.rollupOptions 开关； 如果你仍然需要支持旧浏览器，请覆盖 build.target。 如果某个依赖因更严格的 CommonJS 默认导入处理而报错，请修正导入，或临时使用legacy.inconsistentCjsInterop: true 作为逃生舱。 详见 Vite 8 迁移指南。

vinext 会自动为 dev、build、start、deploy 加载 dotenv 文件。 Vite 会在插件钩子之前、不论导入顺序地求值所有静态配置导入。vinext dev 与vinext build会在移交给 Vite 之前，从项目根目录预加载 dotenv，从而保留旧 CLI 在配置期的这种行为。 直接用 vite dev 与vite build 则不会。 为了让配置期的值在两种命令下都可用，请在配置工厂中使用 Vite 的loadEnv(mode, process.cwd(), "")， 并读取它返回的值，而不是在静态导入中依赖 process.env。 空前缀会包含仅服务端的变量；如果你有自己的 envDir，请用它替换 process.cwd()。