projects

快速开始

启动开发服务器

coze dev

构建生产版本

coze build

启动生产服务器

coze start

项目结构

src/
├── app/ # Next.js App Router 目录
│ ├── layout.tsx # 根布局组件
│ ├── page.tsx # 首页
│ ├── globals.css # 全局样式(包含 shadcn 主题变量)
│ └── [route]/ # 其他路由页面
├── components/ # React 组件目录
│ └── ui/ # shadcn/ui 基础组件(优先使用)
│ ├── button.tsx
│ ├── card.tsx
│ └── ...
├── lib/ # 工具函数库
│ └── utils.ts # cn() 等工具函数
└── hooks/ # 自定义 React Hooks(可选)
server/
├── index.ts # 自定义服务器入口
├── tsconfig.json # Server TypeScript 配置
└── dist/ # 编译输出目录(自动生成)

核心开发规范

1. 组件开发

// ✅ 推荐:使用 shadcn 基础组件
import { Button } from '@/components/ui/button';
import { Card, CardContent, CardHeader } from '@/components/ui/card';
import { Input } from '@/components/ui/input';
export default function MyComponent() {
 return (
 <Card>
 <CardHeader>标题</CardHeader>
 <CardContent>
 <Input placeholder="输入内容" />
 <Button>提交</Button>
 </CardContent>
 </Card>
 );
}

2. 路由开发

# 创建新路由 /about
src/app/about/page.tsx
# 创建动态路由 /posts/[id]
src/app/posts/[id]/page.tsx
# 创建路由组(不影响 URL)
src/app/(marketing)/about/page.tsx
# 创建 API 路由
src/app/api/users/route.ts

// src/app/about/page.tsx
import { Button } from '@/components/ui/button';
export const metadata = {
 title: '关于我们',
 description: '关于页面描述',
};
export default function AboutPage() {
 return (
 <div>
 <h1>关于我们</h1>
 <Button>了解更多</Button>
 </div>
 );
}

// src/app/posts/[id]/page.tsx
export default async function PostPage({
 params,
}: {
 params: Promise<{ id: string }>;
}) {
 const { id } = await params;
 return <div>文章 ID: {id}</div>;
}

// src/app/api/users/route.ts
import { NextResponse } from 'next/server';
export async function GET() {
 return NextResponse.json({ users: [] });
}
export async function POST(request: Request) {
 const body = await request.json();
 return NextResponse.json({ success: true });
}

3. 依赖管理

# ✅ 安装依赖
pnpm install
# ✅ 添加新依赖
pnpm add package-name
# ✅ 添加开发依赖
pnpm add -D package-name
# ❌ 禁止使用 npm 或 yarn
# npm install # 错误!
# yarn add # 错误!

4. 样式开发

// 使用 Tailwind 类名
<div className="flex items-center gap-4 p-4 rounded-lg bg-background">
 <Button className="bg-primary text-primary-foreground">
 主要按钮
 </Button>
</div>
// 使用 cn() 工具函数合并类名
import { cn } from '@/lib/utils';
<div className={cn(
 "base-class",
 condition && "conditional-class",
 className
)}>
 内容
</div>

5. 表单开发

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import * as z from 'zod';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
const formSchema = z.object({
 username: z.string().min(2, '用户名至少 2 个字符'),
 email: z.string().email('请输入有效的邮箱'),
});
export default function MyForm() {
 const form = useForm({
 resolver: zodResolver(formSchema),
 defaultValues: { username: '', email: '' },
 });
 const onSubmit = (data: z.infer<typeof formSchema>) => {
 console.log(data);
 };
 return (
 <form onSubmit={form.handleSubmit(onSubmit)}>
 <Input {...form.register('username')} />
 <Input {...form.register('email')} />
 <Button type="submit">提交</Button>
 </form>
 );
}

6. 数据获取

// src/app/posts/page.tsx
async function getPosts() {
 const res = await fetch('https://api.example.com/posts', {
 cache: 'no-store', // 或 'force-cache'
 });
 return res.json();
}
export default async function PostsPage() {
 const posts = await getPosts();
 return (
 <div>
 {posts.map(post => (
 <div key={post.id}>{post.title}</div>
 ))}
 </div>
 );
}

'use client';
import { useEffect, useState } from 'react';
export default function ClientComponent() {
 const [data, setData] = useState(null);
 useEffect(() => {
 fetch('/api/data')
 .then(res => res.json())
 .then(setData);
 }, []);
 return <div>{JSON.stringify(data)}</div>;
}

常见开发场景

添加新页面

创建业务组件

添加全局状态

// src/lib/store.ts
import { create } from 'zustand';
interface Store {
 count: number;
 increment: () => void;
}
export const useStore = create<Store>((set) => ({
 count: 0,
 increment: () => set((state) => ({ count: state.count + 1 })),
}));

集成数据库

技术栈

参考文档

重要提示