vf_react/docs/ENVIRONMENT_SETUP.md

# 环境配置指南

本文档详细说明项目的环境配置和启动方式。

## 📊 环境模式总览

| 模式 | 命令 | 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
**维护者：** 前端团队