advich-content-frontend/docs/QUICK_START.md

快速开始指南

1. 环境准备

必需环境

• Node.js >= 20.19+
• pnpm >= 8.0

安装 pnpm

npm install -g pnpm

2. 项目初始化

克隆项目

git clone <repository-url>
cd content-frontend

安装依赖

pnpm install

3. 配置后端地址

复制环境变量文件

cp .env.example .env.development

修改后端地址

编辑 .env.development：

# 修改为你的后端地址
VITE_API_BASE_URL=http://localhost:8080

4. 启动开发服务器

pnpm dev

项目将在 http://localhost:3000 启动。

5. 代理配置说明

开发环境

开发环境下，所有 API 请求会通过 Vite 代理转发到后端：

前端: http://localhost:3000
后端: http://localhost:8080

请求流程:
http://localhost:3000/sys/user/list
    ↓ (Vite 代理)
http://localhost:8080/sys/user/list

代理规则

在 vite.config.ts 中配置：

proxy: {
  "/api": {
    target: "http://localhost:8080",
    changeOrigin: true,
    rewrite: (path) => path.replace(/^\/api/, ""),
  },
  "/sys": {
    target: "http://localhost:8080",
    changeOrigin: true,
  },
}

6. 测试接口连接

方式一：浏览器控制台

打开浏览器控制台，执行：

fetch('/sys/user/list')
  .then(r => r.json())
  .then(console.log)

方式二：使用示例页面

访问示例页面测试 API：

http://localhost:3000/examples/api-usage

7. 常见问题

问题 1: 端口被占用

错误信息：

Port 3000 is in use

解决方案：

修改 vite.config.ts 中的端口：

server: {
  port: 3001, // 改为其他端口
}

问题 2: 代理不生效

原因： 请求路径不匹配代理规则

解决方案：

确保 API 请求路径以 /api 或 /sys 开头：

// ✅ 正确
http.get("/sys/user/list");

// ❌ 错误
http.get("http://localhost:8080/sys/user/list");

问题 3: 跨域问题

原因： 后端未配置 CORS

解决方案：

1. 使用 Vite 代理（推荐）
2. 或在后端配置 CORS

问题 4: Token 无法携带

原因： Cookie 配置问题

解决方案：

在代理配置中添加：

"/api": {
  target: "http://localhost:8080",
  changeOrigin: true,
  cookieDomainRewrite: "localhost",
}

8. 构建生产版本

构建

pnpm build

构建产物在 dist 目录。

预览

pnpm preview

生产环境配置

编辑 .env.production：

# 生产环境后端地址
VITE_API_BASE_URL=https://api.example.com

9. 部署

方式一：静态文件部署

将 dist 目录部署到任意静态文件服务器（Nginx、Apache 等）。

方式二：Docker 部署

FROM nginx:alpine
COPY dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Nginx 配置示例

server {
    listen 80;
    server_name example.com;

    root /usr/share/nginx/html;
    index index.html;

    # 前端路由
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /api {
        proxy_pass http://backend:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /sys {
        proxy_pass http://backend:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

10. 开发建议

目录结构

src/
├── layouts/      # 布局组件
├── pages/        # 页面组件
├── components/   # 通用组件
├── services/     # API 服务
├── hooks/        # 自定义 Hooks
├── contexts/     # React Context
├── utils/        # 工具函数
└── types/        # 类型定义

代码规范

• 使用 TypeScript 严格模式
• 组件使用函数式组件
• 使用 Hooks 管理状态
• API 请求使用封装的服务层

Git 提交规范

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
test: 测试相关
chore: 构建/工具相关

11. 下一步

• 阅读 权限系统使用指南
• 阅读 API 请求封装指南
• 阅读 Vite 代理配置指南
• 查看示例代码 src/examples/

12. 获取帮助

• 查看项目文档
• 提交 Issue
• 联系开发团队