二次开发
本章节介绍 Vibany 项目的开发规范和扩展方法,帮助开发者定制功能或进行二次开发。
技术栈
| 技术 | 版本 | 用途 |
|---|---|---|
| Next.js | 16.x | React 框架,App Router |
| React | 19.x | UI 库 |
| TypeScript | 5.x | 类型安全 |
| Tailwind CSS | 3.x | 样式方案 |
| shadcn/ui | latest | 组件库 |
| Drizzle ORM | latest | 数据库 ORM |
| PostgreSQL | 15+ | 数据库 |
| Clerk | latest | 认证系统 |
| Zustand | latest | 状态管理 |
开发环境
1. 环境要求
- Node.js 18.x 或更高版本
- PostgreSQL 数据库(本地或远程)
- Git
2. 快速开始
# 克隆项目
git clone https://github.com/your-repo/vibany-next.git
cd vibany-next
# 安装依赖
npm install
# 配置环境变量
cp .env.example .env.local
# 编辑 .env.local 配置必要变量
# 启动开发服务器
npm run dev
项目结构
├── app/ # Next.js App Router
│ ├── page.tsx # 首页
│ ├── layout.tsx # 根布局
│ ├── draw/ # AI 绘图页面
│ ├── explore/ # 探索/分享页面
│ ├── admin/ # 管理后台
│ ├── api/ # API 路由
│ └── manuals/ # 文档页面
├── components/ # React 组件
│ ├── ui/ # shadcn/ui 组件
│ ├── draw/ # 绘图组件
│ ├── admin/ # 管理后台组件
│ └── global/ # 全局组件
├── lib/ # 业务逻辑
│ ├── db/ # 数据库
│ │ ├── schema.ts # 表结构定义
│ │ └── queries.ts # 查询函数
│ ├── ai/ # AI 模型集成
│ ├── draw/ # 绘图逻辑
│ ├── payment/ # 支付系统
│ ├── storage/ # 文件存储
│ └── utils.ts # 工具函数
├── store/ # Zustand stores
├── constants/ # 常量配置
│ ├── draw/models.ts # 绘图模型配置
│ └── chat/models.ts # LLM 配置
├── contents/manuals/ # MDX 文档
└── drizzle/ # 数据库迁移
开发规范
代码风格
- 语言:TypeScript(严格模式)
- 路径别名:使用
@/*指向项目根目录 - 组件命名:PascalCase(如
MyComponent.tsx) - 文件命名:kebab-case(如
my-component.ts) - 缩进:2 个空格
重要模式
认证(Route Handlers):
// ✅ 正确:使用 @clerk/nextjs/server 的 auth()
import { auth } from "@clerk/nextjs/server";
export async function GET(request: Request) {
const { userId } = await auth();
// ...
}
// ❌ 错误:使用 currentUser
import { currentUser } from "@clerk/nextjs";
ID 生成:
// ✅ 正确:使用 nanoid
import { nanoid } from "nanoid";
const id = nanoid();
// ❌ 错误:使用 uuid
import { v4 as uuidv4 } from "uuid";
const id = uuidv4();
Toast 通知:
// ✅ 正确:使用自定义 useToast hook
import { useToast } from "@/lib/hooks/use-toast";
const { toast } = useToast();
// ❌ 错误:使用 sonner
import { toast } from "sonner";
常见开发任务
新增页面
// app/my-feature/page.tsx
import { auth } from "@clerk/nextjs/server";
export default async function MyFeaturePage() {
const { userId } = await auth();
if (!userId) redirect("/login");
return (
<div className="container py-8">
<h1>新功能</h1>
</div>
);
}
新增 API
// app/api/my-feature/route.ts
import { auth } from "@clerk/nextjs/server";
import { NextResponse } from "next/server";
export async function GET(request: Request) {
const { userId } = await auth();
if (!userId) {
return new NextResponse("Unauthorized", { status: 401 });
}
// 业务逻辑...
return NextResponse.json({ data: result });
}
修改数据库
// 1. 编辑 lib/db/schema.ts
export const myTable = pgTable("my_table", {
id: text("id").primaryKey(),
name: text("name").notNull(),
createdAt: timestamp("created_at").defaultNow().notNull(),
});
// 2. 生成迁移
npm run db:generate
// 3. 应用迁移
npm run db:push # 开发环境
npm run db:migrate # 生产环境
安装 shadcn/ui 组件
npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add dialog
开发命令
| 命令 | 说明 |
|---|---|
npm run dev | 启动开发服务器 |
npm run build | 构建生产版本 |
npm run lint | 运行 ESLint |
npm run db:generate | 生成数据库迁移 |
npm run db:push | 推送 schema 到数据库 |
npm run db:studio | 打开 Drizzle Studio |
./dev.sh | 安装依赖并启动开发 |
部署
Vercel 部署
- 连接 GitHub 仓库到 Vercel
- 配置环境变量
- 自动部署
VPS 部署
# 使用 PM2 部署脚本
./pm2/deploy.sh
# 查看状态
./pm2/status.sh
# 停止应用
./pm2/stop.sh
开发资源
文档
外部资源
贡献指南
- Fork 项目仓库
- 创建功能分支:
git checkout -b feature/my-feature - 提交更改:
git commit -m "feat: add my feature" - 推送分支:
git push origin feature/my-feature - 创建 Pull Request
技术支持
遇到问题?
- 查阅故障排除手册
- 查看 GitHub Issues
- 联系技术支持团队