docs: 将所有文档迁移到 docs/ 目录
- 移动42个文档文件到 docs/ 目录 - 更新 .gitignore 允许 docs/ 下的 .md 文件 - 删除根目录下的重复文档文件 📁 文档分类： - StockDetailPanel 重构文档（3个） - PostHog 集成文档（6个） - 系统架构和API文档（33个） 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
zdl
376
docs/ENVIRONMENT_SETUP.md
Normal file
376
docs/ENVIRONMENT_SETUP.md
Normal file
@@ -0,0 +1,376 @@
|
||||
# 环境配置指南
|
||||
|
||||
本文档详细说明项目的环境配置和启动方式。
|
||||
|
||||
## 📊 环境模式总览
|
||||
|
||||
| 模式 | 命令 | Mock | 后端位置 | PostHog | 适用场景 |
|
||||
|------|------|------|---------|---------|---------|
|
||||
| **本地混合** | `npm start` | ✅ 智能穿透 | 远程 | 可选双模式 | 日常前端开发（推荐） |
|
||||
| **本地全栈** | `npm run start:test` | ❌ | 本地 | 可选双模式 | 后端调试、性能测试 |
|
||||
| **远程开发** | `npm run start:dev` | ❌ | 远程 | 可选双模式 | 联调真实后端 |
|
||||
| **纯 Mock** | `npm run start:mock` | ✅ 完全拦截 | 无 | 可选双模式 | 前端完全独立开发 |
|
||||
| **生产构建** | `npm run build` | ❌ | 生产服务器 | ✅ 仅上报 | 部署上线 |
|
||||
|
||||
---
|
||||
|
||||
## 1️⃣ 本地混合模式（推荐）
|
||||
|
||||
### 启动命令
|
||||
```bash
|
||||
npm start
|
||||
# 或
|
||||
npm run start:local
|
||||
```
|
||||
|
||||
### 配置文件
|
||||
`.env.local`
|
||||
|
||||
### 特点
|
||||
- 🎯 **MSW 智能拦截**：
|
||||
- 已定义 Mock 的接口 → 返回 Mock 数据
|
||||
- 未定义 Mock 的接口 → 自动转发到远程后端
|
||||
- 💡 **最佳效率**：前端独立开发，部分依赖真实数据
|
||||
- 🚀 **快速迭代**：无需等待后端，无需本地运行后端
|
||||
- 🔄 **自动端口清理**：启动前自动清理 3000 端口
|
||||
|
||||
### 适用场景
|
||||
- ✅ 日常前端 UI 开发
|
||||
- ✅ 页面布局调整
|
||||
- ✅ 组件开发测试
|
||||
- ✅ 样式优化
|
||||
|
||||
### 工作流程
|
||||
```bash
|
||||
# 1. 启动项目
|
||||
npm start
|
||||
|
||||
# 2. 观察控制台
|
||||
# ✅ MSW 启动成功
|
||||
# ✅ PostHog 初始化
|
||||
# ✅ 拦截日志显示
|
||||
|
||||
# 3. 开发测试
|
||||
# - Mock 接口：立即返回假数据
|
||||
# - 真实接口：请求远程后端
|
||||
```
|
||||
|
||||
### PostHog 配置
|
||||
编辑 `.env.local`：
|
||||
```env
|
||||
# 仅控制台 debug（初期开发）
|
||||
REACT_APP_POSTHOG_KEY=
|
||||
|
||||
# 控制台 + PostHog Cloud（完整测试）
|
||||
REACT_APP_POSTHOG_KEY=phc_your_test_key_here
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2️⃣ 本地全栈模式
|
||||
|
||||
### 启动命令
|
||||
```bash
|
||||
npm run start:test
|
||||
```
|
||||
|
||||
### 配置文件
|
||||
`.env.test`
|
||||
|
||||
### 特点
|
||||
- 🖥️ **前后端都在本地**：
|
||||
- 前端：localhost:3000
|
||||
- 后端：localhost:5001
|
||||
- 🗄️ **本地数据库**：数据隔离，不影响团队
|
||||
- 🔍 **完整调试**：可以打断点调试后端代码
|
||||
- 📊 **性能分析**：测试数据库查询、接口性能
|
||||
|
||||
### 适用场景
|
||||
- ✅ 调试后端 Python 代码
|
||||
- ✅ 测试数据库查询优化
|
||||
- ✅ 性能测试和压力测试
|
||||
- ✅ 离线开发（无网络）
|
||||
- ✅ 数据迁移脚本测试
|
||||
|
||||
### 工作流程
|
||||
```bash
|
||||
# 1. 启动全栈（自动启动前后端）
|
||||
npm run start:test
|
||||
|
||||
# 观察日志：
|
||||
# [backend] Flask 服务器启动在 5001 端口
|
||||
# [frontend] React 启动在 3000 端口
|
||||
|
||||
# 2. 或手动分别启动
|
||||
# 终端 1
|
||||
python app_2.py
|
||||
|
||||
# 终端 2
|
||||
npm run frontend:test
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
- ⚠️ 确保本地安装了 Python 环境
|
||||
- ⚠️ 确保安装了 requirements.txt 中的依赖
|
||||
- ⚠️ 确保本地数据库已配置
|
||||
|
||||
---
|
||||
|
||||
## 3️⃣ 远程开发模式
|
||||
|
||||
### 启动命令
|
||||
```bash
|
||||
npm run start:dev
|
||||
```
|
||||
|
||||
### 配置文件
|
||||
`.env.development`
|
||||
|
||||
### 特点
|
||||
- 🌐 **连接远程后端**：http://49.232.185.254:5001
|
||||
- 📡 **真实数据**：远程开发数据库
|
||||
- 🤝 **团队协作**：与后端团队联调
|
||||
- ⚡ **无需本地后端**：专注前端开发
|
||||
|
||||
### 适用场景
|
||||
- ✅ 联调后端最新代码
|
||||
- ✅ 测试真实数据表现
|
||||
- ✅ 验证接口文档
|
||||
- ✅ 跨服务功能测试
|
||||
|
||||
### 工作流程
|
||||
```bash
|
||||
# 1. 启动前端（连接远程后端）
|
||||
npm run start:dev
|
||||
|
||||
# 2. 观察控制台
|
||||
# ✅ 所有请求发送到远程服务器
|
||||
# ✅ 无 MSW 拦截
|
||||
|
||||
# 3. 联调测试
|
||||
# - 测试最新后端接口
|
||||
# - 反馈问题给后端团队
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4️⃣ 纯 Mock 模式
|
||||
|
||||
### 启动命令
|
||||
```bash
|
||||
npm run start:mock
|
||||
```
|
||||
|
||||
### 配置文件
|
||||
`.env.mock`
|
||||
|
||||
### 特点
|
||||
- 📦 **完全 Mock**：所有请求都被 MSW 拦截
|
||||
- ⚡ **完全离线**：无需任何后端服务
|
||||
- 🎨 **纯前端**：专注 UI/UX 开发
|
||||
|
||||
### 适用场景
|
||||
- ✅ 后端接口未开发完成
|
||||
- ✅ 完全独立的前端开发
|
||||
- ✅ UI 原型展示
|
||||
|
||||
---
|
||||
|
||||
## 🔧 PostHog 配置说明
|
||||
|
||||
### 双模式运行
|
||||
|
||||
PostHog 支持两种模式：
|
||||
|
||||
#### 模式 1：仅控制台 Debug（推荐初期）
|
||||
```env
|
||||
REACT_APP_POSTHOG_KEY= # 留空
|
||||
```
|
||||
|
||||
**效果：**
|
||||
- ✅ 控制台打印所有事件日志
|
||||
- ✅ 验证事件触发逻辑
|
||||
- ✅ 检查事件属性
|
||||
- ❌ 不实际发送到 PostHog 服务器
|
||||
|
||||
**控制台输出示例：**
|
||||
```javascript
|
||||
✅ PostHog initialized successfully
|
||||
📊 PostHog Analytics initialized
|
||||
📍 Event tracked: community_page_viewed { ... }
|
||||
```
|
||||
|
||||
#### 模式 2：控制台 + PostHog Cloud（完整测试）
|
||||
```env
|
||||
REACT_APP_POSTHOG_KEY=phc_your_test_key_here
|
||||
```
|
||||
|
||||
**效果：**
|
||||
- ✅ 控制台打印所有事件日志
|
||||
- ✅ 同时发送到 PostHog Cloud
|
||||
- ✅ 在 PostHog Dashboard 查看 Live Events
|
||||
- ✅ 测试完整的分析功能
|
||||
|
||||
### 获取 PostHog API Key
|
||||
|
||||
1. 登录 PostHog：https://app.posthog.com
|
||||
2. 创建项目（建议创建独立的测试项目）
|
||||
3. 进入项目设置 → Project API Key
|
||||
4. 复制 API Key（格式：`phc_xxxxxxxxxxxxxx`）
|
||||
5. 填入对应环境的 `.env` 文件
|
||||
|
||||
### 推荐配置
|
||||
|
||||
```bash
|
||||
# 本地开发（.env.local）
|
||||
REACT_APP_POSTHOG_KEY= # 留空，仅控制台
|
||||
|
||||
# 测试环境（.env.test）
|
||||
REACT_APP_POSTHOG_KEY=phc_test_key # 测试项目 Key
|
||||
|
||||
# 开发环境（.env.development）
|
||||
REACT_APP_POSTHOG_KEY=phc_dev_key # 开发项目 Key
|
||||
|
||||
# 生产环境（.env）
|
||||
REACT_APP_POSTHOG_KEY=phc_prod_key # 生产项目 Key
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 端口管理
|
||||
|
||||
### 自动清理 3000 端口
|
||||
|
||||
所有 `npm start` 命令会自动执行 `prestart` 钩子，清理 3000 端口：
|
||||
|
||||
```bash
|
||||
# 自动执行
|
||||
npm start
|
||||
# → 先执行 kill-port 3000
|
||||
# → 再执行 craco start
|
||||
```
|
||||
|
||||
### 手动清理端口
|
||||
|
||||
```bash
|
||||
npm run kill-port
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 环境变量文件说明
|
||||
|
||||
| 文件 | 提交Git | 用途 | 优先级 |
|
||||
|------|--------|------|--------|
|
||||
| `.env` | ✅ | 生产环境 | 低 |
|
||||
| `.env.local` | ✅ | 本地混合模式 | 高 |
|
||||
| `.env.test` | ✅ | 本地测试环境 | 高 |
|
||||
| `.env.development` | ✅ | 远程开发环境 | 中 |
|
||||
| `.env.mock` | ✅ | 纯 Mock 模式 | 中 |
|
||||
|
||||
---
|
||||
|
||||
## 🐛 常见问题
|
||||
|
||||
### Q1: 端口 3000 被占用
|
||||
|
||||
**解决方案：**
|
||||
```bash
|
||||
# 方案 1：自动清理（推荐）
|
||||
npm start # 会自动清理
|
||||
|
||||
# 方案 2：手动清理
|
||||
npm run kill-port
|
||||
```
|
||||
|
||||
### Q2: PostHog 事件没有上报
|
||||
|
||||
**检查清单：**
|
||||
1. 检查 `REACT_APP_POSTHOG_KEY` 是否填写
|
||||
2. 打开浏览器控制台，查看是否有初始化日志
|
||||
3. 检查网络面板，是否有请求发送到 PostHog
|
||||
4. 登录 PostHog Dashboard → Live Events 查看
|
||||
|
||||
### Q3: Mock 数据没有生效
|
||||
|
||||
**检查清单：**
|
||||
1. 确认 `REACT_APP_ENABLE_MOCK=true`
|
||||
2. 检查控制台是否显示 "MSW enabled"
|
||||
3. 检查 `src/mocks/handlers/` 中是否定义了对应接口
|
||||
4. 查看浏览器控制台的 MSW 拦截日志
|
||||
|
||||
### Q4: 本地全栈模式启动失败
|
||||
|
||||
**可能原因：**
|
||||
1. Python 环境未安装
|
||||
2. 后端依赖未安装：`pip install -r requirements.txt`
|
||||
3. 数据库未配置
|
||||
4. 端口 5001 被占用：`lsof -ti:5001 | xargs kill -9`
|
||||
|
||||
### Q5: 环境变量不生效
|
||||
|
||||
**解决方案：**
|
||||
1. 重启开发服务器（React 不会热更新环境变量）
|
||||
2. 检查环境变量名称是否以 `REACT_APP_` 开头
|
||||
3. 确认使用了正确的 `.env` 文件
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 新成员入职
|
||||
|
||||
```bash
|
||||
# 1. 克隆项目
|
||||
git clone <repository>
|
||||
cd vf_react
|
||||
|
||||
# 2. 安装依赖
|
||||
npm install
|
||||
|
||||
# 3. 启动项目（默认本地混合模式）
|
||||
npm start
|
||||
|
||||
# 4. 浏览器访问
|
||||
# http://localhost:3000
|
||||
```
|
||||
|
||||
### 日常开发流程
|
||||
|
||||
```bash
|
||||
# 早上启动
|
||||
npm start
|
||||
|
||||
# 开发中...
|
||||
# - 修改代码
|
||||
# - 热更新自动生效
|
||||
# - 查看控制台日志
|
||||
|
||||
# 需要调试后端时
|
||||
npm run start:test
|
||||
|
||||
# 需要联调时
|
||||
npm run start:dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- [PostHog 集成文档](./POSTHOG_INTEGRATION.md)
|
||||
- [PostHog 事件追踪文档](./POSTHOG_EVENT_TRACKING.md)
|
||||
- [项目配置说明](./CLAUDE.md)
|
||||
|
||||
---
|
||||
|
||||
## 🤝 团队协作建议
|
||||
|
||||
1. **统一环境**：团队成员使用相同的启动命令
|
||||
2. **独立测试**：测试新功能时使用 `start:test` 隔离数据
|
||||
3. **及时反馈**：发现接口问题及时在群里反馈
|
||||
4. **代码审查**：提交前检查是否误提交 API Key
|
||||
|
||||
---
|
||||
|
||||
**最后更新：** 2025-01-15
|
||||
**维护者：** 前端团队
|
||||
Reference in New Issue
Block a user