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️⃣ 本地混合模式（推荐）

启动命令

npm start
# 或
npm run start:local

配置文件

.env.local

特点

• 🎯 MSW 智能拦截：
  • 已定义 Mock 的接口 → 返回 Mock 数据
  • 未定义 Mock 的接口 → 自动转发到远程后端
• 💡 最佳效率：前端独立开发，部分依赖真实数据
• 🚀 快速迭代：无需等待后端，无需本地运行后端
• 🔄 自动端口清理：启动前自动清理 3000 端口

适用场景

• ✅ 日常前端 UI 开发
• ✅ 页面布局调整
• ✅ 组件开发测试
• ✅ 样式优化

工作流程

# 1. 启动项目
npm start

# 2. 观察控制台
# ✅ MSW 启动成功
# ✅ PostHog 初始化
# ✅ 拦截日志显示

# 3. 开发测试
# - Mock 接口：立即返回假数据
# - 真实接口：请求远程后端

PostHog 配置

编辑 .env.local：

# 仅控制台 debug（初期开发）
REACT_APP_POSTHOG_KEY=

# 控制台 + PostHog Cloud（完整测试）
REACT_APP_POSTHOG_KEY=phc_your_test_key_here

---

2️⃣ 本地全栈模式

启动命令

npm run start:test

配置文件

.env.test

特点

• 🖥️ 前后端都在本地：
  • 前端：localhost:3000
  • 后端：localhost:5001
• 🗄️ 本地数据库：数据隔离，不影响团队
• 🔍 完整调试：可以打断点调试后端代码
• 📊 性能分析：测试数据库查询、接口性能

适用场景

• ✅ 调试后端 Python 代码
• ✅ 测试数据库查询优化
• ✅ 性能测试和压力测试
• ✅ 离线开发（无网络）
• ✅ 数据迁移脚本测试

工作流程

# 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️⃣ 远程开发模式

启动命令

npm run start:dev

配置文件

.env.development

特点

• 🌐 连接远程后端：http://49.232.185.254:5001
• 📡 真实数据：远程开发数据库
• 🤝 团队协作：与后端团队联调
• ⚡ 无需本地后端：专注前端开发

适用场景

• ✅ 联调后端最新代码
• ✅ 测试真实数据表现
• ✅ 验证接口文档
• ✅ 跨服务功能测试

工作流程

# 1. 启动前端（连接远程后端）
npm run start:dev

# 2. 观察控制台
# ✅ 所有请求发送到远程服务器
# ✅ 无 MSW 拦截

# 3. 联调测试
# - 测试最新后端接口
# - 反馈问题给后端团队

---

4️⃣ 纯 Mock 模式

启动命令

npm run start:mock

配置文件

.env.mock

特点

• 📦 完全 Mock：所有请求都被 MSW 拦截
• ⚡ 完全离线：无需任何后端服务
• 🎨 纯前端：专注 UI/UX 开发

适用场景

• ✅ 后端接口未开发完成
• ✅ 完全独立的前端开发
• ✅ UI 原型展示

---

🔧 PostHog 配置说明

双模式运行

PostHog 支持两种模式：

模式 1：仅控制台 Debug（推荐初期）

REACT_APP_POSTHOG_KEY=  # 留空

效果：

• ✅ 控制台打印所有事件日志
• ✅ 验证事件触发逻辑
• ✅ 检查事件属性
• ❌ 不实际发送到 PostHog 服务器

控制台输出示例：

✅ PostHog initialized successfully
📊 PostHog Analytics initialized
📍 Event tracked: community_page_viewed { ... }

模式 2：控制台 + PostHog Cloud（完整测试）

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 文件

推荐配置

# 本地开发（.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 端口：

# 自动执行
npm start
# → 先执行 kill-port 3000
# → 再执行 craco start

手动清理端口

npm run kill-port

---

📁 环境变量文件说明

文件	提交Git	用途	优先级
.env	✅	生产环境	低
.env.local	✅	本地混合模式	高
.env.test	✅	本地测试环境	高
.env.development	✅	远程开发环境	中
.env.mock	✅	纯 Mock 模式	中

---

🐛 常见问题

Q1: 端口 3000 被占用

解决方案：

# 方案 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 文件

---

🚀 快速开始

新成员入职

# 1. 克隆项目
git clone <repository>
cd vf_react

# 2. 安装依赖
npm install

# 3. 启动项目（默认本地混合模式）
npm start

# 4. 浏览器访问
# http://localhost:3000

日常开发流程

# 早上启动
npm start

# 开发中...
# - 修改代码
# - 热更新自动生效
# - 查看控制台日志

# 需要调试后端时
npm run start:test

# 需要联调时
npm run start:dev

---

📚 相关文档

• PostHog 集成文档
• PostHog 事件追踪文档
• 项目配置说明

---

🤝 团队协作建议

1. 统一环境：团队成员使用相同的启动命令
2. 独立测试：测试新功能时使用 start:test 隔离数据
3. 及时反馈：发现接口问题及时在群里反馈
4. 代码审查：提交前检查是否误提交 API Key

---

最后更新： 2025-01-15 维护者： 前端团队