TraceStudio-dev/docs/web1.0/SETUP.md

TraceStudio 开发环境设置指南

前置要求

• Python 3.11+（推荐使用 Conda）
• Node.js 18+
• npm 或 yarn

快速启动（推荐）

Windows PowerShell

# 1. 安装后端依赖
cd server
pip install -r requirements.txt

# 2. 安装前端依赖
cd ../web
npm install

# 3. 返回根目录，使用启动脚本
cd ..
.\start.ps1

启动脚本会同时启动前后端服务。

手动启动

1. 启动后端

cd server
python main.py

后端服务将在 http://127.0.0.1:8000 启动。

2. 启动前端

在新的终端窗口中：

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 环境：

conda create -n tracestudio python=3.11
conda activate tracestudio
pip install -r server/requirements.txt

Node 依赖安装失败

尝试清除缓存后重新安装：

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