一次真实项目从 Next.js (Cloudflare Pages) 迁移到 vinext (Cloudflare Workers) 的全过程记录，涵盖构建、部署、运行时、国际化、认证等 16+ 个坑位及其解决方案。

项目简介

本文基于开源项目 edge-next-starter 的真实迁移经验撰写。

edge-next-starter 是一个面向 Cloudflare 全栈开发的 Next.js 生产级启动模板，集成了 D1 数据库、R2 对象存储、KV 缓存、better-auth 认证、next-intl 国际化、Stripe 支付等企业级能力，开箱即用。项目采用 Repository 模式 + Edge Runtime 架构设计，所有代码均运行在 Cloudflare Workers 全球边缘网络上。

GitHub: github.com/TangSY/edge… ⭐ 欢迎 Star

背景与动机

2026 年 2 月 24 日，Cloudflare 发布了一篇震动 Web 开发社区的博客：How we rebuilt Next.js with AI in one week。一名 Cloudflare 工程师 Steve Faulkner 使用 Anthropic 的 Claude AI 模型，仅花费约 1100 美元的 token 费用，在一周内从零重建了 Next.js 94% 的 API。产物就是 vinext（发音 "vee-next"）—— 一个基于 Vite 构建的 Next.js 替代实现，专门针对 Cloudflare Workers 优化。

Cloudflare CTO Dane Knecht 称之为「Next.js 的解放日」。项目绝大部分代码由 AI 编写，人类负责架构方向、优先级和设计决策。

vinext 相比传统的 @cloudflare/next-on-pages 或 OpenNext 方案，有以下显著优势：

• 原生 Workers 部署：不再需要逆向工程 Next.js 的构建输出，一条命令直接部署
• Vite 构建：取代 Turbopack/webpack，生产构建速度最高提升 4 倍
• 更小的 bundle：客户端包体积最高缩小 57%
• 开发环境一致性：vite dev 直接在 Workers 运行时中运行，可以测试 D1、KV、Durable Objects 等平台 API
• RSC 原生支持：完整的 React Server Components、流式渲染、Server Actions 支持

但 vinext 仍处于实验阶段（🚧 Experimental），迁移过程远非一帆风顺 — 本文记录了我们在真实生产项目中遇到的 16 个坑位。

项目技术栈

组件	技术
框架	Next.js App Router (RSC)
运行时	Cloudflare Workers (Edge Runtime)
数据库	Cloudflare D1 (SQLite)
ORM	Prisma + @prisma/adapter-d1
认证	better-auth (从 NextAuth v5 迁移)
国际化	next-intl (en/zh)
存储	Cloudflare R2
缓存	Cloudflare KV
包管理	pnpm

迁移概览

整个迁移涉及 25 个 commits，修改了 50+ 个文件。问题主要集中在以下几个维度：

构建阶段 ─── Prisma Client 模块解析 (3 次迭代)
          └── Wrangler 配置格式转换

运行时 ───── ESM 导入方式变更
          ├── Proxy 导出签名
          ├── 环境变量访问方式
          └── NextURL 只读属性

框架兼容 ─── Middleware matcher 语法
          ├── notFound() 错误处理
          ├── RSC 条件导出
          ├── .rsc 请求处理
          └── Link 组件 vs 原生 <a>

认证系统 ─── Date ↔ Int 类型转换
          ├── OAuth State 清理查询
          ├── VerificationToken 主键
          ├── String ↔ Int ID 转换
          └── emailVerified Boolean → Int

---

第一关：Vite 构建 — Prisma Client 解析

症状：pnpm build 失败，报 No such module ".prisma/client/default"

原因：Prisma 生成的客户端使用 .prisma/client/default 作为裸模块标识符 (bare specifier)。虽然它以 . 开头，但并不是相对路径 — Node.js 会从 node_modules 中解析它。Vite 把它当作相对路径处理，找不到模块后将其标记为 external，导致 Workers 运行时报错。

踩坑过程（3 次迭代）：

第一次：resolve.alias（失败）

// vite.config.ts — 第一次尝试
export default defineConfig({
  resolve: {
    alias: {
      '.prisma/client/default': resolve(import.meta.dirname, 'node_modules/.prisma/client/wasm.js'),
    },
  },
});

问题：import.meta.dirname 在 Vite 编译 TypeScript 配置时，可能解析到临时目录而非项目根目录，导致 CI 环境路径错误。

第二次：process.cwd()（部分成功）

// 改用 process.cwd()
'.prisma/client/default': resolve(
  process.cwd(),
  'node_modules/.prisma/client/wasm.js'
),

问题：在 pnpm 的 store 布局下，.prisma/client/wasm.js 不在 node_modules 直接目录中，ENOENT 错误。

第三次：Vite resolveId 插件（最终方案）

function prismaClientResolve(): Plugin {
  const _require = createRequire(import.meta.url);
  let prismaDir: string | null = null;

  // 策略 1: 项目根目录直接查找
  const directPath = resolve(process.cwd(), 'node_modules', '.prisma', 'client');

  // 策略 2: 从 @prisma/client 包位置反向查找（兼容 pnpm store）
  let pnpmPath: string | null = null;
  try {
    const prismaClientPkg = _require.resolve('@prisma/client/package.json');
    pnpmPath = resolve(dirname(prismaClientPkg), '..', '..', '.prisma', 'client');
  } catch {}

  // 选择第一个存在的路径
  for (const candidate of [directPath, pnpmPath].filter(Boolean) as string[]) {
    if (existsSync(candidate)) {
      prismaDir = candidate;
      break;
    }
  }

  return {
    name: 'prisma-client-resolve',
    enforce: 'pre',
    resolveId(source) {
      if (!source.startsWith('.prisma/client')) return null;
      if (!prismaDir) return null;

      const subpath = source === '.prisma/client' ? '' : source.slice('.prisma/client/'.length);

      if (subpath === 'default' || subpath === '') {
        // 优先使用 wasm.js（Workers WASM 引擎）
        const wasmPath = resolve(prismaDir, 'wasm.js');
        if (existsSync(wasmPath)) return wasmPath;

        // 回退到 default.js
        const defaultPath = resolve(prismaDir, 'default.js');
        if (existsSync(defaultPath)) return defaultPath;
      }
      return null;
    },
  };
}

关键点：

• 使用 createRequire 从 @prisma/client 的实际位置反向定位 .prisma/client
• existsSync 检查避免路径猜测
• 优先 wasm.js（Workers 兼容）而非 default.js（Node.js 专用）

---

第二关：Wrangler 配置 — Pages → Workers 格式转换

症状：部署到 Cloudflare 后，环境变量显示为 "preview" 而非 "production"

原因：vinext 使用 Workers 部署（wrangler deploy），但项目的 wrangler 配置还是 Cloudflare Pages 格式。

修改前（Pages 格式）：

pages_build_output_dir = ".vercel/output/static"

修改后（Workers 格式）：

main = "dist/server/index.js"
no_bundle = true

# vinext 的构建产物是预打包的，告诉 Wrangler 不要重新用 esbuild 打包
[[rules]]
type = "ESModule"
globs = ["**/*.js", "**/*.mjs"]

[assets]
not_found_handling = "none"
directory = "dist/client"

关键点：

• no_bundle = true 是必须的，否则 Wrangler 会用 esbuild 重新打包 vinext 的构建产物，遇到 .prisma/client/default 外部导入时直接报错
• [[rules]] ESModule 类型声明让 Wrangler 正确处理 vinext 输出的 ES Module 文件
• [assets] 替代 pages_build_output_dir，指向 vinext 的客户端构建产物

---

第三关：Workers 运行时 — ESM 与 Proxy 导出

症状：部署后访问任何页面返回 500，Workers 日志无明显错误

问题 1：cloudflare:workers 模块必须用静态 ESM 导入

// ❌ 错误 — CJS 动态导入在 Workers 中不工作
const { env } = require('cloudflare:workers');

// ✅ 正确 — 静态 ESM 导入
import { env as cloudflareEnv } from 'cloudflare:workers';

问题 2：vinext 要求 proxy 使用命名导出而非默认导出

// ❌ 错误 — Next.js middleware 的默认导出
export default function middleware(req) { ... }

// ✅ 正确 — vinext 要求命名导出 { proxy }
export async function proxy(req: NextRequest) { ... }

Vitest 兼容：cloudflare:workers 在测试环境中不存在，需要 mock：

// vitest.cloudflare-stub.ts
export const env = {};
export default { env };

// vitest.config.ts
resolve: {
  alias: {
    'cloudflare:workers': resolve(__dirname, 'vitest.cloudflare-stub.ts'),
  },
}

---

第四关：Middleware → Proxy — matcher 语法不兼容

症状：所有页面返回 404，/en 路径抛出 Error 1101（next-intl locale context 缺失）

原因：vinext 的 matchMiddlewarePath 实现中对 matcher pattern 做了 .replace(/\./g, "\\.") 处理。这会破坏 Next.js 标准的正则表达式 matcher：

// Next.js 标准 matcher（包含正则语法）
export const config = {
  matcher: ['/((?!api|_next/static|_next/image|.*\\..*).*)'],
};
// 经过 vinext 的 .replace 后变成：
// /((?!api|_next/static|_next/image|.*\\.\\..*)\\..*)
// 完全无法匹配任何路径 → proxy 永远不执行

解决方案：使用 vinext 支持的 :param 语法：

export const config = {
  matcher: ['/:path*'],
};
// vinext 将 :path* 转换为 (?:.*) → 匹配所有路径

附带说明：在 Workers 中不需要排除 _next/static 等静态资源路径，因为 Cloudflare CDN 在请求到达 Worker 之前就会直接提供静态文件。但为了安全，我们在 proxy 中增加了静态文件扩展名检测：

const STATIC_EXTENSIONS =
  /\.(ico|png|jpg|jpeg|gif|svg|webp|css|js|map|woff2?|ttf|eot|webmanifest|txt|xml|json)$/i;

export async function proxy(req: NextRequest) {
  if (STATIC_EXTENSIONS.test(req.nextUrl.pathname)) {
    return NextResponse.next();
  }
  // ...
}

---

第五关：next-intl — NextURL.port 只读属性

症状：访问任何页面抛出 TypeError: Cannot set property port which has only a getter

原因：next-intl 的 createIntlMiddleware 内部会修改 NextURL 对象的 port 属性。在标准 Next.js 中 NextURL.port 是可读写的，但 vinext 的 Workers 运行时将其实现为只读 getter。

解决方案：用轻量级的自定义 i18n 路由处理器替代 createIntlMiddleware：

function handleI18nRouting(req: NextRequest): NextResponse {
  const { locales, defaultLocale } = routing;
  const pathname = req.nextUrl.pathname;

  // 路径已包含 locale 前缀，直接通过
  const hasLocale = locales.some(
    locale => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
  );
  if (hasLocale) return NextResponse.next();

  // 从 Accept-Language 检测首选 locale
  const acceptLanguage = req.headers.get('accept-language') || '';
  let detectedLocale = defaultLocale;
  for (const locale of locales) {
    if (acceptLanguage.toLowerCase().includes(locale)) {
      detectedLocale = locale;
      break;
    }
  }

  // 使用原生 URL 重定向（避免 NextURL setter 问题）
  const url = new URL(req.url);
  url.pathname = `/${detectedLocale}${pathname}`;
  return NextResponse.redirect(url);
}

关键点：使用 new URL(req.url) 而非 req.nextUrl.clone()，因为后者会触发 NextURL 的 setter 逻辑。

---

第六关：环境变量 — cloudflare:workers vs process.env

症状：认证功能在本地开发正常，部署后报 CLIENT_ID_AND_SECRET_REQUIRED

原因：通过 wrangler secret put 设置的密钥（如 GOOGLE_CLIENT_ID、NEXTAUTH_SECRET），只能通过 cloudflare:workers 的 env 绑定访问，不会出现在 process.env 中。

// ❌ 在 Workers 中永远是 undefined
const secret = process.env.NEXTAUTH_SECRET;

// ✅ 正确方式
import { env as cloudflareEnv } from 'cloudflare:workers';
const secret = (cloudflareEnv as Record<string, unknown>).NEXTAUTH_SECRET;

最终方案：创建统一的环境变量解析函数：

function getEnvVar(key: string): string | undefined {
  // 优先从 Cloudflare Workers 绑定读取
  const cfEnv = cloudflareEnv as Record<string, unknown>;
  if (cfEnv?.[key]) return String(cfEnv[key]);
  // 回退到 process.env（本地开发、测试环境）
  return process.env[key];
}

---

第七关：notFound() 异常 — NEXT_NOT_FOUND 未捕获

症状：某些页面间歇性返回 500，日志显示 NEXT_NOT_FOUND 异常

原因：vinext 在错误恢复时会用 undefined params 重新渲染 locale layout。代码中的 notFound()（来自 next/navigation）抛出 NEXT_NOT_FOUND 错误，但 vinext 不会像标准 Next.js 那样捕获它，导致整个 RSC 渲染链崩溃。

// ❌ vinext 中不工作
export default async function LocaleLayout({ params }: Props) {
  const { locale } = await params;
  if (!routing.locales.includes(locale)) {
    notFound(); // 抛出 NEXT_NOT_FOUND → 500
  }
}

// ✅ 回退到默认 locale
export default async function LocaleLayout({ params }: Props) {
  const resolvedParams = await params;
  const locale = routing.locales.includes(resolvedParams?.locale)
    ? resolvedParams.locale
    : routing.defaultLocale;
  // 继续渲染...
}

---

第八关：NextIntlClientProvider — RSC 条件导出冲突

症状：所有页面路由报 Error 1101，日志显示 headers() is not a function

原因：next-intl 的 NextIntlClientProvider 使用了 package.json 的 exports 条件导出。在 vinext 的 RSC 环境中，它解析到了一个异步服务端版本，该版本会调用 headers()（来自 next/headers）。但 vinext 不支持在该上下文中调用 headers()。

解决方案：创建本地的 'use client' 包装组件：

// app/[locale]/intl-provider.tsx
'use client';

import { IntlProvider } from 'use-intl';

export function ClientIntlProvider({
  locale,
  messages,
  children,
}: {
  locale: string;
  messages: Record<string, unknown>;
  children: React.ReactNode;
}) {
  return (
    <IntlProvider locale={locale} messages={messages as IntlMessages}>
      {children}
    </IntlProvider>
  );
}

关键点：

• 直接从 use-intl（next-intl 的底层库）导入 IntlProvider
• 'use client' 指令确保 vinext 将其序列化为客户端引用
• 不使用 NextIntlClientProvider，避免触发服务端条件导出

---

第九关：RSC 导航 — .rsc 请求被 Auth 拦截

症状：浏览器前进/后退按钮导致页面空白

原因：vinext 使用 .rsc 后缀进行客户端 RSC payload 请求（例如 /en/dashboard.rsc）。proxy 将这些请求当作普通页面请求处理，检查认证状态后重定向到 /login。但 .rsc 请求期望的是 RSC 流数据，收到重定向后 React 无法解析，导致页面空白。

解决方案：在 proxy 中对 .rsc 请求只做 i18n 路由，跳过 auth 检查：

if (pathname.endsWith('.rsc')) {
  // 去掉 .rsc 后缀检查 i18n 路由
  const cleanPath = pathname.slice(0, -4);
  const hasLocale = locales.some(
    locale => cleanPath.startsWith(`/${locale}/`) || cleanPath === `/${locale}`
  );

  if (hasLocale) return NextResponse.next();

  // 添加 locale 前缀并重定向
  const url = new URL(req.url);
  url.pathname = `/${detectedLocale}${pathname}`;
  return NextResponse.redirect(url);
}

安全性：认证在服务端组件层（getSessionSafe()）强制执行，不依赖 proxy。

---

第十关：Link 组件与 API 路由 — RSC 流损坏

症状：用 <Link> 跳转到 API 端点后，浏览器后退显示原始 JSON 而非页面

原因：Next.js 的 <Link> 组件触发客户端 RSC 导航。API 端点返回 JSON 而非 RSC payload，React 尝试解析 JSON 作为 RSC 流失败，破坏了浏览器历史记录中的 React 根节点。

解决方案：对 API 链接使用原生 <a> 标签：

// ❌ 会触发 RSC 导航
<Link href="/api/health">Health Check</Link>

// ✅ 强制全页面导航
<a href="/api/health" target="_blank" rel="noopener noreferrer">
  Health Check
</a>

---

第十一关：better-auth — Date ↔ Int 类型不匹配

症状：better-auth 的所有数据库写入操作失败

原因：better-auth 内部所有日期字段使用 JavaScript Date 对象，但我们的 Prisma schema 使用 Int（Unix 时间戳，秒）来兼容 D1/SQLite。Prisma 的 SQLite provider 不会自动做这个转换。

解决方案：创建 Prisma Client Proxy，拦截所有 auth 相关模型的操作：

// lib/db/auth-prisma-proxy.ts
const AUTH_DATE_FIELDS: Record<string, string[]> = {
  user: ['emailVerified', 'createdAt', 'updatedAt'],
  account: ['expiresAt', 'createdAt', 'updatedAt'],
  session: ['expires', 'createdAt', 'updatedAt'],
  verificationToken: ['expires', 'createdAt', 'updatedAt'],
};

function deepConvertInputs(obj: unknown, parentKey?: string): unknown {
  if (obj instanceof Date) return Math.floor(obj.getTime() / 1000);
  if (Array.isArray(obj)) return obj.map(item => deepConvertInputs(item));
  if (obj !== null && typeof obj === 'object') {
    const result: Record<string, unknown> = {};
    for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
      result[key] = deepConvertInputs(value, key);
    }
    return result;
  }
  return obj;
}

export function createAuthPrismaProxy<T>(prisma: T): T {
  return new Proxy(prisma as object, {
    get(target, prop, receiver) {
      const value = Reflect.get(target, prop, receiver);
      if (typeof prop !== 'string') return value;
      const modelKey = resolveModelKey(prop);
      if (!modelKey) return value;

      // 为 auth 模型的每个方法创建代理
      return new Proxy(value as object, {
        get(modelTarget, methodName, modelReceiver) {
          const method = Reflect.get(modelTarget, methodName, modelReceiver);
          if (typeof method !== 'function') return method;
          if (!ALL_OPS.has(methodName as string)) return method.bind(modelTarget);

          return async function (...args: any[]) {
            // 输入：递归转换 Date → Unix timestamp
            if (args[0] && typeof args[0] === 'object') {
              args[0] = deepConvertInputs(args[0]);
            }
            const result = await method.apply(modelTarget, args);
            // 输出：Unix timestamp → Date（仅已知日期字段）
            return convertOutputDates(result, modelKey);
          };
        },
      });
    },
  }) as T;
}

使用方式：

// lib/auth/index.ts
export const auth = betterAuth({
  database: prismaAdapter(createAuthPrismaProxy(prisma), { provider: 'sqlite' }),
  // ...
});

---

第十二关：OAuth 状态管理 — deleteMany 中的 Date 未转换

症状：Google OAuth 回调后重定向到 ?error=please_restart_the_process

原因：better-auth 的 OAuth 流程中，findVerificationValue 函数在查找状态后会执行清理操作：

// better-auth 内部代码 (state.mjs)
await adapter.deleteMany({
  model: 'verification',
  where: [{ field: 'expiresAt', operator: 'lt', value: new Date() }],
});

我们的 proxy 第一版只拦截了 create、update、find 操作，且只转换 data 和 create/update 字段中的 Date。deleteMany 的 where 子句中的 new Date() 没有被转换，导致 SQLite 比较失败。

修复：将拦截范围扩展到所有 Prisma 操作（ALL_OPS），并使用递归的 deepConvertInputs 处理整个 args 树：

const ALL_OPS = new Set([
  'create',
  'createMany',
  'update',
  'updateMany',
  'upsert',
  'delete',
  'deleteMany',
  'findFirst',
  'findUnique',
  'findMany',
  'count',
  'aggregate',
]);

---

第十三关：VerificationToken — 主键缺失与 ID 类型错误

症状：Google OAuth 回调返回 internal_server_error，Workers 日志显示两个错误

错误 1：verificationToken.delete({ where: { id: null } })

原因：VerificationToken 模型的 id 字段定义为 String?（可选），没有设置为主键。配合 generateId: false，better-auth 不会为 VerificationToken 生成 ID，导致删除操作传入 id: null。

错误 2：user.findFirst({ where: { id: "1" } })

原因：better-auth 内部使用 z.coerce.string() 将所有 ID 转换为字符串。但 Prisma schema 中 User 的 id 是 Int，字符串 "1" 无法匹配整数 1。

修复：

1. 数据库迁移 — 重建 verification_tokens 表：

-- 0007_fix_verification_token_pk.sql
CREATE TABLE IF NOT EXISTS verification_tokens_new (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  identifier TEXT NOT NULL,
  token TEXT NOT NULL UNIQUE,
  expires INT NOT NULL,
  created_at INT DEFAULT (strftime('%s', 'now')),
  updated_at INT DEFAULT (strftime('%s', 'now')),
  UNIQUE(identifier, token)
);
INSERT INTO verification_tokens_new (identifier, token, expires, created_at, updated_at)
  SELECT identifier, token, expires, created_at, updated_at FROM verification_tokens;
DROP TABLE verification_tokens;
ALTER TABLE verification_tokens_new RENAME TO verification_tokens;
CREATE INDEX idx_verification_tokens_expires ON verification_tokens(expires);

2. Prisma schema 更新：

model VerificationToken {
  id    Int    @id @default(autoincrement())  // 原来是 String?
  // ...
}

3. 启用 useNumberId — better-auth 内置的 String ↔ Int ID 转换：

// lib/auth/index.ts
export const auth = betterAuth({
  advanced: {
    database: {
      useNumberId: true, // 替代 generateId: false
    },
  },
});

useNumberId: true 让 better-auth 的适配器层自动做 String → Number（输入）和 Number → String（输出）的 ID 转换。

---

第十四关：emailVerified — Boolean vs Int

症状：Google OAuth 登录时，创建用户失败

原因：当用户通过 Google OAuth 登录时，better-auth 认为邮箱已被 Google 验证，设置 emailVerified: true（布尔值）。但 schema 中 emailVerified 是 Int?（Unix 时间戳）。

修复：在 proxy 的 deepConvertInputs 中添加布尔值 → 时间戳转换：

const BOOLEAN_TO_TIMESTAMP_FIELDS = new Set(['emailVerified']);

function deepConvertInputs(obj: unknown, parentKey?: string): unknown {
  if (obj instanceof Date) return Math.floor(obj.getTime() / 1000);

  // 特定字段的 boolean → timestamp 转换
  if (typeof obj === 'boolean' && parentKey && BOOLEAN_TO_TIMESTAMP_FIELDS.has(parentKey)) {
    return obj ? Math.floor(Date.now() / 1000) : null;
  }

  // ... 递归处理
}

---

第十五关：D1 迁移 — ALTER TABLE 不支持动态默认值

症状：wrangler d1 migrations apply 报错 non-constant default

原因：SQLite 的 ALTER TABLE ADD COLUMN 语句不允许使用非常量默认值（如 strftime('%s', 'now')）。

-- ❌ 错误
ALTER TABLE accounts ADD COLUMN created_at INT DEFAULT (strftime('%s', 'now'));

-- ✅ 正确 — 先用常量默认值，再用 UPDATE 回填
ALTER TABLE accounts ADD COLUMN created_at INT DEFAULT 0;
UPDATE accounts SET created_at = strftime('%s', 'now') WHERE created_at = 0;

---

第十六关：CI/CD — Workers 域名包含账户子域

症状：GitHub Actions 部署成功但健康检查失败（HTTP 000）

原因：Cloudflare Workers 的默认域名格式是 <worker-name>.<account-subdomain>.workers.dev，而不是 <worker-name>.workers.dev。CI 配置中的回退 URL 少了账户子域。

# ❌ 错误
DEPLOYMENT_URL="https://my-worker.workers.dev"

# ✅ 正确
DEPLOYMENT_URL="https://my-worker.t-ac5.workers.dev"

最佳实践：在 GitHub Repository Variables 中配置 TEST_DEPLOYMENT_URL 和 PRODUCTION_DEPLOYMENT_URL，不要依赖 hardcoded 回退值。

---

核心代码清单

迁移后的核心文件结构：

├── vite.config.ts              # Vite 配置 + Prisma resolveId 插件
├── proxy.ts                    # 替代 middleware.ts（i18n + auth + CORS/CSRF）
├── wrangler.toml               # 本地开发配置（Workers 格式）
├── wrangler.test.toml          # 测试环境配置
├── wrangler.prod.toml          # 生产环境配置
├── vitest.cloudflare-stub.ts   # cloudflare:workers 测试 mock
├── lib/
│   ├── auth/
│   │   ├── index.ts            # better-auth 配置 + getEnvVar
│   │   ├── session.ts          # getSessionSafe (RSC 安全包装)
│   │   └── password.ts         # PBKDF2 密码哈希（Edge 兼容）
│   └── db/
│       ├── client.ts           # Prisma 单例 + cloudflare:workers ESM 导入
│       └── auth-prisma-proxy.ts # Date↔Int + Boolean→Int 类型转换代理
├── app/[locale]/
│   └── intl-provider.tsx       # 本地 'use client' IntlProvider 包装
└── migrations/
    └── 0007_fix_verification_token_pk.sql  # VerificationToken 主键修复

总结

从 Next.js 迁移到 vinext 不是简单的"换个构建工具"那么简单。主要挑战来自三个层面：

1. Vite vs webpack 的模块解析差异：Prisma 的裸模块标识符、条件导出的解析优先级等，在两个构建系统中行为完全不同。

2. Workers vs Node.js 运行时差异：process.env 不可用、NextURL 属性只读、notFound() 未被捕获 — 这些都是 Workers 运行时的限制。

3. 第三方库假设：next-intl 假设 NextURL.port 可写，better-auth 假设日期字段是 Date 对象 — 这些假设在标准 Next.js 中成立，但在 vinext 的 Workers 环境中全部失效。

核心教训：vinext 不是 Next.js 的替代品，而是 Next.js API 在 Workers 运行时上的重新实现。任何依赖 Next.js 实现细节（而非公开 API）的代码，都可能需要适配。

本文基于 2026 年 2 月的实际迁移经验，vinext 仍在快速迭代中，部分问题可能在后续版本中得到解决。

12 篇文章、一个完整的小程序、从需求分析到性能优化，这是我和 AI 协作开发心动恋聊的全过程。这篇文章作为系列收官，分享项目的完整回顾、AI 协作的心得体会、以及对未来开发模式的思考。

系列专栏：【AI 编程实战】专栏目录

本篇主题：项目总结与 AI 协作心得

实战项目：心动恋聊 - AI 恋爱聊天助手

一、项目回顾：从 0 到 1 的历程

1.1 项目概览

心动恋聊是一个 AI 恋爱聊天助手小程序，帮助用户在社交场景中获得更好的聊天回复建议。

📊 项目规模：

技术栈：
- 前端：UniApp + Vue 3 + TypeScript + Pinia
- 后端：Next.js + Prisma + AI API
- UI：UnoCSS + UView Pro

代码量：
- 前端代码：~15,000 行
- 组件数量：30+ 个
- 页面数量：15+ 个
- Hooks：10+ 个

开发周期：
- 总耗时：约 4 周
- 迭代次数：3 个大版本

1.2 系列文章脉络

📚 12 篇文章的完整脉络：

【基础搭建】（第 1-5 篇）
├── 第 1 篇：项目启动 - 需求分析、技术选型、AI 配置
├── 第 2 篇：创建项目 - UniApp 项目初始化与配置
├── 第 3 篇：页面结构 - 首页布局与 TabBar 配置
├── 第 4 篇：样式系统 - UnoCSS 原子化 CSS 实战
└── 第 5 篇：状态管理 - Pinia 持久化与用户状态

【核心功能】（第 6-9 篇）
├── 第 6 篇：网络请求 - HTTP 封装与拦截器设计
├── 第 7 篇：登录流程 - 微信授权与多步骤弹窗
├── 第 8 篇：组件封装 - 可复用组件设计方法
└── 第 9 篇：Hooks 封装 - 逻辑复用的最佳实践

【质量保障】（第 10-12 篇）
├── 第 10 篇：错误处理 - 防御性编程与边界情况
├── 第 11 篇：性能优化 - 分包、懒加载、缓存策略
└── 第 12 篇：项目总结 - 回顾与 AI 协作心得（本篇）

1.3 每篇文章的核心产出

篇章	主题	核心产出
第 1 篇	项目启动	需求文档、技术架构图
第 2 篇	创建项目	项目脚手架、目录结构
第 3 篇	页面结构	首页布局、TabBar 配置
第 4 篇	样式系统	UnoCSS 配置、主题色方案
第 5 篇	状态管理	userStore、持久化方案
第 6 篇	网络请求	HTTP 封装、拦截器
第 7 篇	登录流程	LoginModal、多步骤流程
第 8 篇	组件封装	XButton、Modal、VipCard
第 9 篇	Hooks	useRequest、useUpload
第 10 篇	错误处理	Toast 封装、防御性编程
第 11 篇	性能优化	分包、懒加载、缓存
第 12 篇	项目总结	方法论、心得体会

二、AI 协作的正确姿势

2.1 什么样的对话最有效

通过 12 篇文章的实践，我总结出和 AI 对话的几个关键点：

❌ 低效的对话方式：

我：帮我写一个登录功能

这样的提问太宽泛，AI 不知道：

• 是什么平台？小程序/H5/App？
• 用什么登录方式？微信/手机号/密码？
• 登录后跳哪里？需要什么回调？
• UI 是弹窗还是页面？

✅ 高效的对话方式：

我：需要设计一套登录系统，要求：
    1. 微信小程序环境
    2. 支持微信登录 + 手机号授权
    3. 新用户要引导填性别和年龄
    4. 任意页面都能触发登录弹窗
    5. 登录成功后能执行回调

这样 AI 能给出精准的方案，因为：

• 明确了环境（小程序）
• 明确了功能（微信登录 + 手机号）
• 明确了流程（新用户引导）
• 明确了交互（弹窗 + 回调）

2.2 对话的层次感

我发现最有效的对话是分层推进的：

第一轮：说清楚要做什么
我：需要封装一个通用的请求 Hook

第二轮：AI 询问细节，我补充
AI：需要支持哪些功能？immediate？初始数据？
我：需要立即执行选项，需要初始数据

第三轮：AI 给出设计，我确认
AI：我来设计接口结构...
我：开始吧

第四轮：AI 生成代码，我追问
AI：（生成代码）
我：为什么用 Promise 链式而不是 try-catch？

第五轮：AI 解释原理，我学到了
AI：两种写法对比...

这种层层递进的对话，比一次性给出"完美 Prompt"更有效，因为：

1. 渐进明确：需求是在对话中逐步清晰的
2. 双向确认：AI 的设计决策需要你确认
3. 深度学习：追问"为什么"让你真正理解

2.3 AI 不是银弹

在实践中，我也发现了 AI 的局限：

📊 AI 擅长的事：

✅ 生成样板代码（CRUD、配置）
✅ 解释技术概念
✅ 分析代码问题
✅ 提供多种方案对比
✅ 重构和优化建议

📊 AI 不擅长的事：

❌ 理解业务上下文（需要你提供）
❌ 做产品决策（需要你判断）
❌ 处理边界情况（需要你验证）
❌ 了解项目历史（需要你说明）

核心认知：AI 是工具，不是替代品。你需要：

• 清晰地描述需求
• 评估 AI 给出的方案
• 验证生成的代码
• 理解背后的原理

三、效率提升的真实数据

3.1 开发效率对比

📊 单项任务耗时对比：

| 任务 | 传统方式 | AI 辅助 | 提升倍数 |
|------|---------|---------|----------|
| HTTP 封装 | 4 小时 | 1 小时 | 4x |
| 登录弹窗 | 8 小时 | 3 小时 | 2.7x |
| 组件封装 | 6 小时 | 2 小时 | 3x |
| Hooks 设计 | 4 小时 | 1.5 小时 | 2.7x |
| 错误处理 | 3 小时 | 1 小时 | 3x |
| 性能优化 | 6 小时 | 2 小时 | 3x |

3.2 效率提升的来源

📊 效率提升分析：

1. 减少"从零开始"的时间
   - 传统：Google 搜索 → 看文档 → 试错
   - AI：描述需求 → 获得可用代码 → 微调

2. 减少"踩坑"的时间
   - 传统：遇到问题 → Stack Overflow → 找答案
   - AI：描述问题 → 获得解决方案 → 理解原因

3. 减少"重复劳动"
   - 传统：复制粘贴 → 手动修改
   - AI：描述模式 → 批量生成

4. 加速"学习理解"
   - 传统：看源码 → 猜测用法
   - AI：问"为什么" → 获得解释

3.3 质量提升的体现

📊 代码质量对比：

【代码规范性】
- 一致的命名风格
- 完整的类型定义
- 合理的代码注释

【架构合理性】
- 清晰的分层设计
- 合理的职责划分
- 可扩展的接口设计

【可维护性】
- 抽象复用的组件
- 封装良好的 Hooks
- 统一的错误处理

四、最佳实践总结

4.1 项目结构最佳实践

📂 推荐的项目结构：

src/
├── api/              # API 接口定义
│   ├── user.ts
│   └── chat.ts
├── components/       # 通用组件
│   ├── XButton.vue
│   ├── Modal.vue
│   └── LoadingIndicator.vue
├── composables/      # 组合式函数
│   ├── useLoginFlow.ts
│   └── useSystemInfo.ts
├── hooks/            # 通用 Hooks
│   ├── useRequest.ts
│   └── useUpload.ts
├── http/             # HTTP 封装
│   ├── http.ts
│   ├── interceptor.ts
│   └── types.ts
├── pages/            # 页面
│   ├── index/
│   └── my/
├── store/            # 状态管理
│   ├── user.ts
│   └── loginModal.ts
├── subPackages/      # 分包
│   ├── vip/
│   └── agreement/
└── utils/            # 工具函数
    ├── toast.ts
    └── platform.ts

4.2 代码规范最佳实践

// ✅ 推荐的代码风格

// 1. 类型定义清晰
interface Props {
  text?: string;
  loading?: boolean;
  disabled?: boolean;
}

// 2. 默认值合理
const props = withDefaults(defineProps<Props>(), {
  text: '',
  loading: false,
  disabled: false,
});

// 3. 事件定义明确
const emit = defineEmits<{
  click: [];
  success: [data: any];
  error: [error: Error];
}>();

// 4. 计算属性缓存
const formattedData = computed(() =>
  rawData.value.map(item => ({
    ...item,
    displayName: formatName(item.name),
  }))
);

// 5. 错误处理完整
const handleSubmit = async () => {
  if (loading.value) return;

  loading.value = true;
  try {
    const res = await doSubmit();
    emit('success', res.data);
  } catch (error) {
    console.error('提交失败:', error);
    toast.error('提交失败，请重试');
  } finally {
    loading.value = false;
  }
};

4.3 AI 协作最佳实践

📋 AI 协作清单：

【开始前】
□ 明确功能需求
□ 了解技术约束
□ 准备上下文信息

【对话中】
□ 分层描述需求
□ 确认设计方案
□ 追问实现原理
□ 要求代码解释

【生成后】
□ 阅读理解代码
□ 验证功能正确
□ 检查边界情况
□ 优化代码细节

五、踩过的坑与解决方案

5.1 常见问题汇总

📊 开发中遇到的典型问题：

1. Token 获取位置
   ❌ 从 Store 获取（拦截器执行时 Store 未初始化）
   ✅ 从 Storage 获取

2. 响应式数据依赖
   ❌ 静态对象引用 store 数据
   ✅ 使用 computed 保持响应式

3. 枚举类型存储
   ❌ 字符串存储（'男'/'女'）
   ✅ 数字枚举（1/2）

4. 条件编译位置
   ❌ 运行时判断平台
   ✅ 使用 #ifdef 编译时判断

5. 组件职责边界
   ❌ 组件内处理业务逻辑
   ✅ 组件只负责 UI，业务逻辑在 Store/Service

5.2 避坑指南

// 1. Token 获取
// ❌ 错误
const { token } = userStore.userInfo;

// ✅ 正确
const token = uni.getStorageSync('token');

// 2. 响应式依赖
// ❌ 错误
const menuItems = {
  label: userStore.genderDisplay
};

// ✅ 正确
const menuItems = computed(() => ({
  label: userStore.genderDisplay
}));

// 3. 平台判断
// ❌ 错误
if (process.env.UNI_PLATFORM === 'mp-weixin') {
  // ...
}

// ✅ 正确
// #ifdef MP-WEIXIN
// 小程序专用代码
// #endif

六、对未来的思考

6.1 AI 辅助开发的趋势

📊 我的观察：

【现在】
- AI 生成代码片段
- 人工整合和调试
- 需要理解才能用

【未来可能】
- AI 理解整个项目上下文
- 自动化测试和修复
- 更智能的代码审查

【不变的是】
- 需求分析能力
- 架构设计能力
- 问题诊断能力

6.2 开发者的核心竞争力

📊 AI 时代的开发者能力：

1. 问题定义能力
   - 把模糊需求转化为清晰描述
   - 识别真正要解决的问题

2. 方案评估能力
   - 评估 AI 给出的多种方案
   - 选择最适合当前场景的

3. 架构设计能力
   - 理解系统整体结构
   - 做出合理的技术决策

4. 持续学习能力
   - 通过 AI 加速学习新技术
   - 保持技术敏感度

七、系列总结

7.1 本系列的价值

📚 这个系列想传达的：

1. AI 辅助开发是可行的
   - 不是概念，是实践
   - 有真实的效率提升

2. 对话比 Prompt 更重要
   - 不是"写好 Prompt 就行"
   - 而是"多轮对话逐步明确"

3. 理解比复制更重要
   - 不是"复制代码就完了"
   - 而是"理解原理才能用好"

4. 人的判断不可替代
   - AI 是工具，不是替代
   - 技术决策需要人来做

7.2 给读者的建议

📋 如果你想开始 AI 辅助开发：

1. 从小项目开始
   - 不要一开始就用于生产项目
   - 先在 Side Project 中积累经验

2. 保持学习心态
   - 每次对话都是学习机会
   - 追问"为什么"比"给我代码"更重要

3. 建立验证习惯
   - AI 生成的代码要验证
   - 边界情况要自己考虑

4. 积累对话模式
   - 总结有效的对话方式
   - 建立自己的"提问模板"

7.3 最后的话

心动恋聊从一个想法，到一个完整的小程序，
再到这 12 篇文章，是我和 AI 协作的一次深度实践。

我最大的感受是：
AI 没有让编程变得"不需要思考"，
反而让我更清晰地思考"该怎么做"。

因为你需要：
- 清晰地描述需求
- 评估多种方案
- 理解生成的代码
- 验证实际效果

这些，都需要思考。

希望这个系列对你有帮助。
如果有问题，欢迎评论区交流！

---

系列完结！

12 篇文章，完整记录了心动恋聊小程序从 0 到 1 的开发过程。

这不是教你"如何写 Prompt"，而是展示如何和 AI 协作解决实际问题。

如果这个系列对你有帮助，请点赞、收藏、转发！