手动运行项目

一键部署功能目前仅支持 Windows 系统。如果你使用 macOS 或 Linux，或者希望对运行过程有更细粒度的控制，可以按照本指南手动启动项目。

前置要求

• 前端和后端代码已下载
• 相关环境已安装（Node.js / Java / Python）
• 两边的依赖都已安装（pnpm install）

方式一：两个终端（推荐新手）

最简单直观的方式，可以分别查看前后端日志。

终端 1 - 启动后端：

cd backend && pnpm run start:dev

终端 2 - 启动前端：

cd frontend && pnpm run dev

优点：简单直观，日志分离，出错容易定位。

方式二：使用 concurrently

在根目录同时启动两个服务。

安装

pnpm add -D concurrently

配置 package.json

在根目录的 package.json 添加脚本：

{
  "scripts": {
    "dev": "concurrently \"pnpm --filter backend run start:dev\" \"pnpm --filter frontend run dev\"",
    "dev:backend": "pnpm --filter backend run start:dev",
    "dev:frontend": "pnpm --filter frontend run dev"
  }
}

运行

pnpm run dev

前后端如何连接

前端通过 API 请求与后端通信，需要确保跨域配置正确。

配置前端 API 地址

在前端项目的 .env 文件中配置：

VITE_API_URL=http://localhost:3000

确保后端 CORS 已配置

后端需要允许前端地址的跨域请求。

NestJS:

app.enableCors({
  origin: 'http://localhost:5173'
});

Express:

app.use(cors({
  origin: 'http://localhost:5173'
}));

使用 Vite 代理避免 CORS（推荐）

在前端 vite.config.ts 中配置代理：

export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  }
})

这样前端请求 /api/users 会自动代理到 http://localhost:3000/users，无需配置 CORS。

环境变量

使用环境变量区分开发与生产环境：

.env.development:

VITE_API_URL=http://localhost:3000

.env.production:

VITE_API_URL=https://api.your-domain.com

验证连接

检查后端

curl http://localhost:3000/health

应该返回类似 {"status":"ok"} 的响应。

检查前端 API 调用

1. 打开浏览器开发者工具（F12）
2. 切换到 Network 面板
3. 操作页面触发 API 请求
4. 检查请求是否成功

常见问题

CORS 错误

Access to XMLHttpRequest at 'http://localhost:3000/api'
from origin 'http://localhost:5173' has been blocked by CORS policy

解决方法：

1. 后端配置 CORS（见上方）
2. 或使用前端 Vite 代理（见上方）

端口冲突

如果端口被占用，可以修改：

后端（NestJS/.env）:

PORT=3001

前端（vite.config.ts）:

server: {
  port: 5174
}

API 请求超时

1. 确认后端服务正在运行
2. 检查 API 地址是否正确
3. 查看后端日志是否有错误

服务端口总览

服务	默认端口	用途
前端开发服务器	5173	Vite 开发服务器
NestJS 后端	3000	API 服务
Spring Boot 后端	8080	API 服务
FastAPI/Django 后端	8000	API 服务
PostgreSQL	5432	数据库
MySQL	3306	数据库