239 lines
5.6 KiB
Markdown
239 lines
5.6 KiB
Markdown
# TraceStudio Web Frontend
|
||
|
||
基于 React 19 + TypeScript + Vite 的现代化前端应用。
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
# 或
|
||
pnpm install
|
||
```
|
||
|
||
### 2. 配置环境变量（可选）
|
||
|
||
复制 `.env.example` 为 `.env.local` 并修改配置：
|
||
|
||
```bash
|
||
cp .env.example .env.local
|
||
```
|
||
|
||
编辑 `.env.local`：
|
||
|
||
```env
|
||
# API 服务器地址（可选，默认自动检测）
|
||
VITE_API_BASE_URL=http://127.0.0.1:8000
|
||
```
|
||
|
||
**注意**：如果不设置环境变量，前端会自动检测：
|
||
- **开发环境**：使用 `http://127.0.0.1:8000`
|
||
- **生产环境**：使用当前域名的 8000 端口或相对路径
|
||
|
||
### 3. 启动开发服务器
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
访问 http://localhost:5173
|
||
|
||
### 4. 构建生产版本
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
构建产物在 `dist/` 目录。
|
||
|
||
## 🔧 环境变量
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `VITE_API_BASE_URL` | 后端API地址 | 开发: `http://127.0.0.1:8000`<br>生产: 自动检测 |
|
||
|
||
## 📡 API 配置
|
||
|
||
API 基础地址的优先级：
|
||
|
||
1. **环境变量** `VITE_API_BASE_URL`（最高优先级）
|
||
2. **开发模式** `import.meta.env.DEV` → `http://127.0.0.1:8000`
|
||
3. **生产模式** 根据 `window.location` 动态生成
|
||
|
||
示例场景：
|
||
|
||
```typescript
|
||
// 开发环境
|
||
http://127.0.0.1:8000
|
||
|
||
// 生产环境（同域部署）
|
||
https://tracestudio.com:8000
|
||
|
||
// 生产环境（自定义域名）
|
||
VITE_API_BASE_URL=https://api.tracestudio.com
|
||
```
|
||
|
||
## 🛠️ 开发
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
src/
|
||
├── components/ # React 组件
|
||
│ ├── AppShell.tsx
|
||
│ ├── HeaderBar.tsx
|
||
│ ├── Inspector.tsx
|
||
│ ├── NodePalette.tsx
|
||
│ ├── Workspace.tsx
|
||
│ └── FileExplorer.tsx
|
||
├── stores/ # Zustand 状态管理
|
||
│ └── useStore.ts
|
||
├── utils/ # 工具函数
|
||
│ ├── api.ts # API 通讯层
|
||
│ └── nodeRegistry.ts
|
||
└── i18n.ts # 国际化
|
||
```
|
||
|
||
### API 通讯层
|
||
|
||
所有后端请求统一通过 `src/utils/api.ts` 管理：
|
||
|
||
```typescript
|
||
import { getPlugins, executeGraph, listFiles } from './utils/api'
|
||
|
||
// 获取节点列表
|
||
const result = await getPlugins()
|
||
|
||
// 执行图
|
||
const result = await executeGraph({ nodes, edges })
|
||
|
||
// 列出文件
|
||
const result = await listFiles('path/to/dir')
|
||
```
|
||
|
||
## 🌐 部署
|
||
|
||
### 部署到服务器
|
||
|
||
1. 构建生产版本：
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
2. 配置环境变量（如果需要）：
|
||
```bash
|
||
echo "VITE_API_BASE_URL=https://api.your-domain.com" > .env.production
|
||
npm run build
|
||
```
|
||
|
||
3. 将 `dist/` 目录部署到服务器
|
||
|
||
### Nginx 配置示例
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name tracestudio.com;
|
||
|
||
root /var/www/tracestudio/dist;
|
||
index index.html;
|
||
|
||
# 前端路由
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
# 代理后端API
|
||
location /api {
|
||
proxy_pass http://127.0.0.1:8000;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 📝 技术栈
|
||
|
||
- **框架**: React 19
|
||
- **语言**: TypeScript 5
|
||
- **构建**: Vite 6
|
||
- **状态管理**: Zustand 5
|
||
- **流程图**: React Flow 11
|
||
- **国际化**: 自定义 i18n
|
||
- **样式**: CSS + Tailwind CSS
|
||
|
||
---
|
||
|
||
## React + Vite 模板说明
|
||
|
||
Currently, two official plugins are available:
|
||
|
||
- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
|
||
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
|
||
|
||
## React Compiler
|
||
|
||
The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
|
||
|
||
## Expanding the ESLint configuration
|
||
|
||
If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
|
||
|
||
```js
|
||
export default defineConfig([
|
||
globalIgnores(['dist']),
|
||
{
|
||
files: ['**/*.{ts,tsx}'],
|
||
extends: [
|
||
// Other configs...
|
||
|
||
// Remove tseslint.configs.recommended and replace with this
|
||
tseslint.configs.recommendedTypeChecked,
|
||
// Alternatively, use this for stricter rules
|
||
tseslint.configs.strictTypeChecked,
|
||
// Optionally, add this for stylistic rules
|
||
tseslint.configs.stylisticTypeChecked,
|
||
|
||
// Other configs...
|
||
],
|
||
languageOptions: {
|
||
parserOptions: {
|
||
project: ['./tsconfig.node.json', './tsconfig.app.json'],
|
||
tsconfigRootDir: import.meta.dirname,
|
||
},
|
||
// other options...
|
||
},
|
||
},
|
||
])
|
||
```
|
||
|
||
You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
|
||
|
||
```js
|
||
// eslint.config.js
|
||
import reactX from 'eslint-plugin-react-x'
|
||
import reactDom from 'eslint-plugin-react-dom'
|
||
|
||
export default defineConfig([
|
||
globalIgnores(['dist']),
|
||
{
|
||
files: ['**/*.{ts,tsx}'],
|
||
extends: [
|
||
// Other configs...
|
||
// Enable lint rules for React
|
||
reactX.configs['recommended-typescript'],
|
||
// Enable lint rules for React DOM
|
||
reactDom.configs.recommended,
|
||
],
|
||
languageOptions: {
|
||
parserOptions: {
|
||
project: ['./tsconfig.node.json', './tsconfig.app.json'],
|
||
tsconfigRootDir: import.meta.dirname,
|
||
},
|
||
// other options...
|
||
},
|
||
},
|
||
])
|
||
```
|