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) 了解已完成的功能和测试用例。
|