root
248 lines
5.3 KiB
Markdown
248 lines
5.3 KiB
Markdown
# NextApp - 门户系统使用说明
|
||
|
||
基于 Next.js 15 + Prisma 6 + SQLite 构建的最小化门户网站。
|
||
|
||
## 环境要求
|
||
|
||
- Node.js 18.x 或更高版本
|
||
- npm 或 yarn
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 2. 数据库初始化
|
||
|
||
项目使用 SQLite 数据库，数据存储在 `dev.db` 文件中。
|
||
|
||
```bash
|
||
# 生成 Prisma 客户端
|
||
npx prisma generate
|
||
|
||
# 应用数据库迁移（创建表结构）
|
||
npx prisma migrate dev
|
||
|
||
# 种子数据（添加初始页面）
|
||
curl http://localhost:3000/api/seed
|
||
# 或在浏览器访问: http://localhost:3000/api/seed
|
||
```
|
||
|
||
### 3. 启动开发服务器
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
服务器启动后，访问 **http://localhost:3000**
|
||
|
||
### 4. 停止服务器
|
||
|
||
在运行服务器的终端按 `Ctrl + C`，或：
|
||
|
||
```bash
|
||
# 查找进程
|
||
ps aux | grep "next"
|
||
|
||
# 结束进程
|
||
kill -9 <PID>
|
||
# 或
|
||
pkill -f "next-server"
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `npm run dev` | 启动开发服务器（支持热重载）|
|
||
| `npm run build` | 构建生产版本 |
|
||
| `npm run start` | 启动生产服务器 |
|
||
| `npm run lint` | 代码检查 |
|
||
|
||
## 数据库操作
|
||
|
||
### Prisma 命令
|
||
|
||
```bash
|
||
# 生成 Prisma 客户端
|
||
npx prisma generate
|
||
|
||
# 创建新迁移
|
||
npx prisma migrate dev --name <迁移名称>
|
||
|
||
# 重置数据库（清空所有数据）
|
||
npx prisma migrate reset
|
||
|
||
# 打开 Prisma Studio（数据库可视化工具）
|
||
npx prisma studio
|
||
```
|
||
|
||
### 数据库文件
|
||
|
||
- **位置**: `prisma/dev.db`
|
||
- **类型**: SQLite
|
||
- **工具**: 可使用 `npx prisma studio` 或 SQLite 客户端（如 DB Browser for SQLite）查看
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
nextapp/
|
||
├── app/ # Next.js App Router
|
||
│ ├── api/ # API 路由
|
||
│ │ ├── pages/ # 页面相关 API
|
||
│ │ │ ├── route.ts # GET/POST 所有页面
|
||
│ │ │ └── [slug]/
|
||
│ │ │ └── route.ts # GET 单个页面
|
||
│ │ └── seed/
|
||
│ │ └── route.ts # 种子数据接口
|
||
│ ├── components/ # React 组件
|
||
│ │ └── TestButton.tsx # 测试按钮组件
|
||
│ ├── lib/
|
||
│ │ └── prisma.ts # Prisma 客户端实例
|
||
│ ├── globals.css # 全局样式
|
||
│ ├── layout.tsx # 根布局
|
||
│ └── page.tsx # 首页
|
||
├── prisma/
|
||
│ ├── schema.prisma # 数据模型定义
|
||
│ └── migrations/ # 数据库迁移文件
|
||
├── dev.db # SQLite 数据库（运行时生成）
|
||
├── .env # 环境变量
|
||
├── package.json
|
||
└── tsconfig.json
|
||
```
|
||
|
||
## API 端点
|
||
|
||
### 页面相关
|
||
|
||
| 方法 | 端点 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/pages` | 获取所有页面 |
|
||
| POST | `/api/pages` | 创建新页面 |
|
||
| GET | `/api/pages/[slug]` | 获取指定页面 |
|
||
| GET | `/api/seed` | 初始化种子数据 |
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
# 获取所有页面
|
||
curl http://localhost:3000/api/pages
|
||
|
||
# 创建新页面
|
||
curl -X POST http://localhost:3000/api/pages \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"slug":"contact","title":"联系我们","content":"<h1>联系我们</h1><p>联系方式...</p>"}'
|
||
|
||
# 获取指定页面
|
||
curl http://localhost:3000/api/pages/home
|
||
```
|
||
|
||
## 数据模型
|
||
|
||
### Page（页面）
|
||
|
||
```prisma
|
||
model Page {
|
||
id Int @id @default(autoincrement())
|
||
slug String @unique # 页面标识（如：home, about）
|
||
title String # 页面标题
|
||
content String # 页面内容（HTML）
|
||
createdAt DateTime @default(now())
|
||
updatedAt DateTime @updatedAt
|
||
}
|
||
```
|
||
|
||
### Setting（设置）
|
||
|
||
```prisma
|
||
model Setting {
|
||
id Int @id @default(autoincrement())
|
||
key String @unique # 设置键名
|
||
value String # 设置值
|
||
createdAt DateTime @default(now())
|
||
updatedAt DateTime @updatedAt
|
||
}
|
||
```
|
||
|
||
## 功能说明
|
||
|
||
### 首页
|
||
|
||
- 访问 `/` 显示 slug 为 `home` 的页面内容
|
||
- 导航栏包含 Logo 和"测试按钮"
|
||
- 点击"测试按钮"弹出 "hello" 提示
|
||
|
||
### 测试按钮
|
||
|
||
- 位置：导航栏右侧
|
||
- 功能：点击弹出 alert 提示 "hello"
|
||
- 实现：`app/components/TestButton.tsx`（客户端组件）
|
||
|
||
## 生产部署
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
### 启动生产服务器
|
||
|
||
```bash
|
||
npm run start
|
||
```
|
||
|
||
生产服务器默认运行在 **http://localhost:3000**
|
||
|
||
## 注意事项
|
||
|
||
1. **数据库文件**：`dev.db` 包含数据库，不要手动编辑
|
||
2. **环境变量**：数据库 URL 配置在 `.env` 文件中
|
||
3. **Prisma 客户端**：修改 `schema.prisma` 后需运行 `npx prisma generate`
|
||
4. **迁移**：修改数据模型后需创建新的迁移：`npx prisma migrate dev --name <描述>`
|
||
5. **热重载**：开发模式下代码修改会自动刷新浏览器
|
||
|
||
## 技术栈
|
||
|
||
- **框架**: Next.js 15 (App Router)
|
||
- **ORM**: Prisma 6
|
||
- **数据库**: SQLite
|
||
- **样式**: Tailwind CSS 4
|
||
- **语言**: TypeScript
|
||
|
||
## 故障排查
|
||
|
||
### 数据库不同步
|
||
|
||
```bash
|
||
npx prisma migrate reset
|
||
npx prisma migrate dev
|
||
```
|
||
|
||
### Prisma 客户端未生成
|
||
|
||
```bash
|
||
npx prisma generate
|
||
```
|
||
|
||
### 端口被占用
|
||
|
||
```bash
|
||
# 修改端口启动
|
||
npm run dev -- -p 3001
|
||
```
|
||
|
||
### 清除缓存重新构建
|
||
|
||
```bash
|
||
rm -rf .next node_modules/.cache
|
||
npm run dev
|
||
```
|
||
|
||
## 许可证
|
||
|
||
MIT
|