本地开发和运行手册

目的

这份文档回答新人最常问的问题：

我本地要装什么？
项目怎么跑起来？
有哪些环境？
改代码时跑什么命令？
数据库、缓存、队列这些依赖怎么启动？
环境变量从哪里来？
跑不起来怎么办？

组织级文档只给通用规则。每个具体项目必须在 docs/PROJECT.md 写清自己的实际命令。

常见环境

环境 用途 谁用 数据特点 允许做什么
Local 本地开发和调试 工程师 本地假数据或开发数据 随时 reset、seed、debug
Test 自动化测试 CI / 工程师 临时测试数据 跑单测、集成测试、contract test
Preview PR 预览 工程、产品、设计 隔离或沙箱数据 验证单个 PR 的 UI/API
Staging 接近生产的集成验证 工程、QA、产品 脱敏或测试数据 发布前 smoke、跨服务验证
Production 真实用户 值班 / 发布负责人 真实数据 只能按发布和事故流程操作

新人默认只需要 Local、Test、Preview。不要一开始申请 Production 权限。

本地开发需要哪些东西

每个项目的 docs/PROJECT.md 必须写清楚这些项：

类别 要写什么 示例
语言版本 Node/Go/Python/Rust/Java 等版本 node 20、go 1.22
包管理器 如何安装依赖 pnpm install、go mod download
本地依赖服务 DB、Redis、queue、object storage、fake server docker compose up -d postgres redis
环境变量 .env.example 怎么复制，哪些变量必须填 cp .env.example .env.local
Migration 数据库结构怎么初始化 pnpm db:migrate、alembic upgrade head
Seed 本地测试数据怎么生成 pnpm db:seed
启动命令 Web/API/worker 怎么启动 pnpm dev
检查命令 改完代码跑什么 pnpm check、go test ./...
Smoke 怎么验证核心路径 pnpm smoke:local

三角色本地开发责任

角色 负责确认
技术负责人 项目必须能被新人按文档跑起，否则不算可维护
产品负责人 preview / staging 能让产品验收用户可见变化
平台 / 资深工程师 本地依赖、环境变量、migration、seed、检查命令都可复制执行

第一次运行项目

通用流程：

1. 拉代码
2. 确认语言版本
3. 安装依赖
4. 复制环境变量模板
5. 启动本地依赖服务
6. 跑 migration
7. 如需要，导入 seed 数据
8. 启动应用
9. 打开本地页面或调用 health check
10. 跑本地快速检查

JS/TS 常见例子：

pnpm install
cp .env.example .env.local
docker compose up -d postgres redis
pnpm db:migrate
pnpm db:seed
pnpm dev
pnpm check

Go 常见例子：

go mod download
cp .env.example .env.local
docker compose up -d postgres redis
go run ./cmd/migrate
go run ./cmd/server
go test ./...

Python 常见例子：

uv sync
cp .env.example .env.local
docker compose up -d postgres redis
alembic upgrade head
uvicorn app:app --reload
pytest
ruff check .

Rust 常见例子：

cargo fetch
cp .env.example .env.local
docker compose up -d postgres redis
sqlx migrate run
cargo run
cargo test
cargo clippy

这些只是示例。项目实际命令以 docs/PROJECT.md 为准。

日常开发怎么跑

日常开发通常不需要每次从零开始。推荐节奏：

同步 main
-> 启动依赖服务
-> 启动应用
-> 改代码
-> 跑相关测试
-> 跑本地快速检查
-> 提 PR

常见命令类型：

动作 JS/TS 示例 Go 示例 Python 示例 Rust 示例
启动应用 pnpm dev go run ./cmd/server uvicorn app:app --reload cargo run
跑单测 pnpm test go test ./... pytest cargo test
跑指定测试 pnpm test path/to.test.ts go test ./pkg/foo pytest tests/foo_test.py cargo test test_name
格式 / lint pnpm lint gofmt -w . && go vet ./... ruff check . cargo fmt && cargo clippy
类型 / 编译 pnpm typecheck go test ./... mypy . 或 pyright cargo check
构建 pnpm build go build ./... python -m build cargo build
合并前检查 pnpm check go test ./... pytest && ruff check . cargo test && cargo clippy

pnpm check 不是通用标准，只是 JS/TS 项目常见的聚合命令。真正要写清楚的是它覆盖了哪些检查。

本地依赖服务

项目常见本地依赖：

服务 本地怎么跑 注意点
Postgres / MySQL Docker Compose 需要 migration 和 seed
Redis Docker Compose 注意 TTL、缓存清理
Queue Docker Compose / fake queue 本地要能消费 job
Object storage MinIO / fake storage 不要连生产 bucket
第三方 API fake server / sandbox 不要默认打真实生产 API
Webhook local tunnel / recorded fixture 签名和 payload 要可测

docker-compose.yml 或等价脚本必须说明：

  1. 启动哪些服务。
  2. 端口是多少。
  3. 数据卷在哪里。
  4. 如何 reset。
  5. 如何看日志。

环境变量怎么处理

每个项目至少有：

文件 用途
.env.example 公开模板，不含真实 secret
.env.local 本地开发，不提交
.env.test 或 CI env 测试环境
部署环境变量 Staging / Production

规则：

  1. 新增环境变量必须更新 .env.example。
  2. .env.example 要写变量用途和示例值。
  3. Secret 不得写进文档、截图、群聊或 PR comment。
  4. 本地默认连 fake、sandbox 或 dev 资源，不连 production。
  5. 如果变量缺失，应用应给出可读错误，不要静默失败。

数据库怎么处理

本地数据库必须能做 4 件事：

创建空库
-> 跑 migration
-> seed 基础数据
-> reset 到干净状态

项目应提供命令：

动作 示例
migrate pnpm db:migrate
seed pnpm db:seed
reset pnpm db:reset
inspect pnpm db:studio 或数据库客户端

如果改了 schema，PR 必须说明：

  1. migration 做了什么。
  2. 是否兼容旧代码。
  3. 是否需要 backfill。
  4. 是否可回滚，不能回滚时怎么 forward-fix。

跑不起来怎么办

先按这个顺序查：

  1. 语言版本是否正确。
  2. 依赖是否安装。
  3. Docker 是否启动。
  4. 本地依赖服务是否 healthy。
  5. .env.local 是否缺变量。
  6. migration 是否执行。
  7. 端口是否被占用。
  8. 是否有旧缓存、旧 volume、旧 lockfile。

求助时不要只发“跑不起来”。按这个格式发：

项目：
分支 / commit：
执行的命令：
完整错误：
已经试过：
怀疑原因：
需要谁帮忙：

如果最后发现是文档缺失，补到 docs/PROJECT.md 或创建文档修复任务。

项目必须写清的本地开发字段

docs/PROJECT.md 至少要有这些字段：

语言和版本：
包管理器：
本地依赖服务：
环境变量准备：
安装依赖：
启动依赖：
数据库 migration：
seed / reset：
启动 Web：
启动 API：
启动 worker：
本地检查：
核心 smoke：
常见问题：

没有这些字段，新人就只能靠问人和猜命令，本地开发闭环就不成立。

下一步阅读

读完或填完这份文档后，通常继续看：