123 lines
2.3 KiB
Markdown
123 lines
2.3 KiB
Markdown
# TraceStudio 开发环境设置指南
|
||
|
||
## 前置要求
|
||
|
||
- **Python 3.11+**（推荐使用 Conda）
|
||
- **Node.js 18+**
|
||
- **npm 或 yarn**
|
||
|
||
## 快速启动（推荐）
|
||
|
||
### Windows PowerShell
|
||
|
||
```powershell
|
||
# 1. 安装后端依赖
|
||
cd server
|
||
pip install -r requirements.txt
|
||
|
||
# 2. 安装前端依赖
|
||
cd ../web
|
||
npm install
|
||
|
||
# 3. 返回根目录，使用启动脚本
|
||
cd ..
|
||
.\start.ps1
|
||
```
|
||
|
||
启动脚本会同时启动前后端服务。
|
||
|
||
## 手动启动
|
||
|
||
### 1. 启动后端
|
||
|
||
```powershell
|
||
cd server
|
||
python main.py
|
||
```
|
||
|
||
后端服务将在 `http://127.0.0.1:8000` 启动。
|
||
|
||
### 2. 启动前端
|
||
|
||
在**新的终端窗口**中：
|
||
|
||
```powershell
|
||
cd web
|
||
npm run dev
|
||
```
|
||
|
||
前端服务将在 `http://localhost:5173` 启动。
|
||
|
||
## 访问应用
|
||
|
||
- **前端界面**: http://localhost:5173
|
||
- **后端 API**: http://127.0.0.1:8000
|
||
- **API 文档**: http://127.0.0.1:8000/docs
|
||
|
||
## 开发工具
|
||
|
||
### 推荐的 VS Code 插件
|
||
|
||
- **ESLint** - JavaScript/TypeScript 代码检查
|
||
- **Prettier** - 代码格式化
|
||
- **Tailwind CSS IntelliSense** - Tailwind 智能提示
|
||
- **Python** - Python 语言支持
|
||
- **Pylance** - Python 类型检查
|
||
|
||
### 热重载
|
||
|
||
- **前端**: Vite 自动热重载，修改文件后立即生效
|
||
- **后端**: Uvicorn 自动重载，修改 Python 文件后自动重启
|
||
|
||
## 常见问题
|
||
|
||
### 前端无法连接后端
|
||
|
||
确保后端服务已启动在 `http://127.0.0.1:8000`。
|
||
|
||
### 端口被占用
|
||
|
||
如果端口 8000 或 5173 被占用，可以修改：
|
||
- **后端端口**: 在 `server/main.py` 的 `uvicorn.run()` 中修改 `port` 参数
|
||
- **前端端口**: 在 `web/vite.config.ts` 中添加 `server.port` 配置
|
||
|
||
### Python 依赖安装失败
|
||
|
||
推荐使用 Conda 环境：
|
||
|
||
```powershell
|
||
conda create -n tracestudio python=3.11
|
||
conda activate tracestudio
|
||
pip install -r server/requirements.txt
|
||
```
|
||
|
||
### Node 依赖安装失败
|
||
|
||
尝试清除缓存后重新安装：
|
||
|
||
```powershell
|
||
cd web
|
||
rm -r node_modules
|
||
rm package-lock.json
|
||
npm install
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
TraceStudio/
|
||
├── web/ # React 前端
|
||
│ ├── src/
|
||
│ ├── public/
|
||
│ └── package.json
|
||
├── server/ # FastAPI 后端
|
||
│ ├── main.py
|
||
│ └── requirements.txt
|
||
├── start.ps1 # 启动脚本
|
||
└── SETUP.md # 本文档
|
||
```
|
||
|
||
## 下一步
|
||
|
||
查看 [PHASE1_COMPLETE.md](PHASE1_COMPLETE.md) 了解已完成的功能和测试用例。
|