fischerX/docs/development/migration-guide.md

迁移指南

> 文档版本: v1.0.0 > 创建日期: 2026-05-25 > 适用范围: FischerX 项目开发人员

目录

• v1.x → v2.x 迁移
• 破坏性变更说明
• 迁移步骤
• 常见问题

---

v1.x → v2.x 迁移

概述

v2.0 带来了以下重大改进：

• 升级到 Next.js 16
• 升级到 NestJS 11
• 升级到 Prisma 6
• 引入 Monorepo 架构
• 重构了认证系统

---

破坏性变更说明

Next.js 变更

Pages Router → App Router

v1.x:

// pages/index.tsx
export default function Home() {
  return <div>Home</div>;
}

v2.x:

// app/page.tsx
export default function HomePage() {
  return <div>Home</div>;
}

图片组件变更

v1.x:

import Image from 'next/image';

<Image src="/logo.png" width={100} height={100} />

v2.x:

import Image from 'next/image';

<Image src="/logo.png" width={100} height={100} alt="Logo" />

Prisma 变更

枚举值变更

v1.x:

enum Role {
  ADMIN
  USER
}

v2.x:

enum Role {
  ADMIN
  USER
  GUEST @default(USER)
}

API 变更

认证端点

v1.x:

POST /auth/login
POST /auth/register

v2.x:

POST /api/v1/auth/login
POST /api/v1/auth/register
POST /api/v1/auth/refresh

---

迁移步骤

1. 备份数据

# 备份数据库
pg_dump fischerx > backup_v1.sql

2. 更新代码

# 拉取新版本
git fetch origin
git checkout v2.0.0

3. 更新依赖

# 安装新依赖
pnpm install

4. 数据库迁移

# 运行新迁移
cd services/api
pnpm prisma migrate deploy

5. 更新环境变量

# 添加新的环境变量
NEXT_PUBLIC_API_URL=http://localhost:4000/api/v1

6. 测试

# 运行测试
pnpm test

---

常见问题

Q: 我的自定义 Hooks 需要改吗？

A: 大部分不需要，除非它们依赖旧的 Next.js API。

Q: 数据库迁移会丢失数据吗？

A: 我们的迁移是安全的，但建议先备份。

Q: 旧的 API 端点还能用吗？

A: 我们提供了向后兼容层，但建议尽快迁移。

---

下一步

• 常见问题 - 查看更多问题

---

> 文档维护: 本文档由开发团队维护，如有问题或建议请提交 Issue。 > 最后更新: 2026-05-25