二次开发

本章节介绍 Vibany 项目的开发规范和扩展方法,帮助开发者定制功能或进行二次开发。

技术栈

技术版本用途
Next.js16.xReact 框架,App Router
React19.xUI 库
TypeScript5.x类型安全
Tailwind CSS3.x样式方案
shadcn/uilatest组件库
Drizzle ORMlatest数据库 ORM
PostgreSQL15+数据库
Clerklatest认证系统
Zustandlatest状态管理

开发环境

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

访问 http://localhost:3000

项目结构

├── 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 部署

  1. 连接 GitHub 仓库到 Vercel
  2. 配置环境变量
  3. 自动部署

VPS 部署

# 使用 PM2 部署脚本
./pm2/deploy.sh

# 查看状态
./pm2/status.sh

# 停止应用
./pm2/stop.sh

开发资源

文档

外部资源

贡献指南

  1. Fork 项目仓库
  2. 创建功能分支:git checkout -b feature/my-feature
  3. 提交更改:git commit -m "feat: add my feature"
  4. 推送分支:git push origin feature/my-feature
  5. 创建 Pull Request

技术支持

遇到问题?

© copyright Justin 2026. All rights reserved.