开发环境搭建指南

---

本指南面向新入职成员，按顺序执行约 　　 分钟可完成搭建并跑通本地服务。遇到问题先查「常见问题」，仍未解决请在 　　　　群求助。

一、前置依赖

依赖	版本要求	安装方式	验证命令
Git	≥ 2.30	系统包管理器	git --version
Node.js	LTS（用 nvm 安装）	nvm install	node -v
包理器 pnpm	≥	npm i -g pnpm	pnpm -v
运行时
MySQL 8	8.0.x	Docker 镜像（推荐）	mysql --version

二、获取代码与安装依赖

# 1) 克隆仓库（内网走 SSH，需先配置公钥）
git clone git@　　:　　/　　.git && cd

# 2) 安装依赖（锁定版本，勿用 npm/yarn 混装）
pnpm install

# 3) 初始化子模块 / 生成代码
git submodule update --init
make generate

三、本地配置

复制环境模板并按需填写（真实密钥严禁提交，配置文件已被 .gitignore 忽略）：

cp .env.example .env.local

配置项	说明	本地默认值
DATABASE_URL	本地数据库连接串	root@tcp(127.0.0.1:3306)/
REDIS_ADDR	本地 Redis 地址	127.0.0.1:6379
LLM_API_KEY	内网中转平台申请	—
AUTH_CLIENT_ID	联调统一认证应用 ID

四、初始化数据与启动

1. 导入基础数据：make db-migrate && make db-seed；
2. 启动依赖服务：docker compose up -d（MySQL / Redis）；
3. 启动应用：make dev，首次启动自动执行迁移；
4. 验证：浏览器打开 http://localhost:　　，用测试账号 　　　　登录。

• 首页可正常访问，登录成功
• 核心链路 　　　　冒烟通过
• 运行 make test 本地全绿

五、常见问题

Q1：依赖安装失败 / 下载超时？

切换内网镜像源：pnpm config set registry https://　　；仍失败删除 node_modules 与锁文件缓存后重试。

Q2：端口被占用？

lsof -i :　　 查找进程；本地端口可在 .env.local 中通过 　　　　修改。

Q3：数据库连接失败？

确认容器已启动且账号密码与 .env.local 一致；首次导入需先执行建库语句 CREATE DATABASE 　　;。