local-dev-setup

本地开发环境配置技能

为某项服务或项目编写完整的本地开发环境配置指南，带领新工程师从零开始（使用干净的笔记本电脑），在 30 分钟内搭建好本地环境并通过测试。优秀的配置指南可以缩短入职时间，避免“在我的机器上可以运行”的问题，并帮助工程师自信地提交第一份贡献。将每个步骤写成具体的命令或操作，而不是对需要完成的事项进行描述。

必需输入

如果尚未提供，请询问以下信息：

• 服务名称及其功能
• 技术栈——语言、框架、数据库、缓存、消息队列和任何外部服务
• 依赖项——数据库、缓存、消息队列和外部服务（使用模拟服务或真实服务）
• 测试框架——如何运行测试，以及测试套件涵盖的内容
• CI/CD 平台——GitHub Actions、CircleCI、Jenkins 等（用于说明“本地通过 CI”意味着什么）

输出格式

---

本地开发环境配置：[服务名称]

技术栈：[语言 + 版本] | [框架] | [数据库] | [缓存] **预计配置时间：**在干净的机器上需要 [20–30 分钟] 上次验证时间：[日期]，环境为 [macOS Ventura 13.x / Ubuntu 22.04] **有问题？**请在 [Slack：#[team-channel]] 提问，或联系 [@tech-lead-handle]

**首次贡献？**请先完成环境配置（本文档），然后阅读 [CONTRIBUTING.md]，了解代码规范和 PR 流程。

---

前置条件

开始前请安装以下工具。列出的版本是最低要求；较新的补丁版本可以使用，较新的主版本可能会有兼容性问题。

必需工具

工具	所需版本	安装方式
[Git]	2.x+	大多数系统均已预装；或运行 brew install git
[语言运行时 — 例如 Go]	[1.22+]	[https://go.dev/dl/ 或 brew install go]
[Docker]	24.x+	[https://docs.docker.com/get-docker/]
[Docker Compose]	2.x+	随 Docker Desktop 附带；或运行 brew install docker-compose
[Make]	任意	macOS/Linux 已预装
[工具 — 例如 Node.js]	[20.x+]	[brew install node 或 https://nodejs.org]
[工具 — 例如 psql 客户端]	[15+]	brew install postgresql@15（仅客户端）

可选但建议安装

工具	用途	安装方式
[direnv]	自动加载 .envrc 环境变量	brew install direnv + 设置说明
[jq]	在终端中美化输出 JSON	brew install jq
[k9s]	Kubernetes 集群 UI（如果在本地使用 K8s）	brew install k9s
[mkcert]	本地 HTTPS 证书	brew install mkcert

必需的账户和访问权限

开始前，请确保你已获得以下权限：

• 可访问 GitHub 上的 [org/repo]——通过 [权限申请流程 / Slack：#it-help] 申请
• 可访问 [开发环境] 的 [AWS / GCP / Azure] 账户——通过 [流程] 申请
• 可用于获取开发密钥的 [内部工具 — 例如 1Password]——通过 [流程] 申请
• 如需访问内部服务，请申请 [VPN 访问权限]——通过 [流程] 申请

---

1. 配置代码仓库

# Clone the repository
git clone [email protected]:[org]/[repo-name].git
cd [repo-name]

# Install git hooks (required — enforces commit message format and runs pre-commit checks)
make install-hooks
# Or manually:
# cp scripts/hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

# Verify your git setup
git config user.name   # should be your name
git config user.email  # should be your work email

**如果克隆时看到权限被拒绝错误：**说明你的 SSH 密钥尚未添加到 GitHub。请按照 GitHub 的 SSH 密钥指南 操作，或者改用带个人访问令牌的 HTTPS。

---

2. 环境变量

该服务需要环境变量进行配置。切勿将真实密钥提交到代码仓库。

步骤 1 — 复制示例文件

cp .env.example .env.local

第 2 步 — 填写值

在编辑器中打开 .env.local。以下是每个变量的说明及其值的获取方式：

变量	说明	获取方式	示例（非真实值）
APP_ENV	环境名称	设置为 development	development
APP_PORT	服务监听的端口	本地设置为 8080	8080
DATABASE_URL	PostgreSQL 连接字符串	使用 Docker Compose 中的值（第 3 节）	postgres://app:password@localhost:5432/[service]_dev
REDIS_URL	Redis 连接字符串	使用 Docker Compose 中的值	redis://localhost:6379
SECRET_KEY	应用密钥	使用以下命令生成：openssl rand -hex 32	[random 64-char hex]
[EXTERNAL_SERVICE]_API_KEY	[External Service] 的 API 密钥	从 [1Password vault: "Dev API Keys"] 获取，或询问 [name]	—
[EXTERNAL_SERVICE]_BASE_URL	[External Service] 的基础 URL	使用沙盒 URL：https://sandbox.[external-service].com	https://sandbox.stripe.com
LOG_LEVEL	日志详细程度	本地开发时设置为 debug	debug
[FEATURE_FLAG_SDK_KEY]	功能标记平台 SDK 密钥	从 [LaunchDarkly/Split dev project] 获取	—

使用 direnv（推荐）： 将 .env.local 重命名为 .envrc，在文件顶部添加 dotenv，然后运行 direnv allow。当你使用 cd 进入项目目录时，变量会自动加载。

---

3. 本地服务依赖项

所有基础设施依赖项都通过 Docker Compose 运行。你无需在本地安装 PostgreSQL、Redis 或 Kafka。

# Start all dependencies (PostgreSQL, Redis, and any other services)
docker compose up -d

# Verify all containers are healthy
docker compose ps
# Expected output: all services show "healthy" status

# View logs if something is not healthy
docker compose logs [service-name]

Docker Compose 启动的服务

服务	端口	用途	健康检查
PostgreSQL [version]	5432	主数据库	pg_isready -U app
Redis [version]	6379	缓存和会话存储	redis-cli ping
[Kafka + Zookeeper]	9092 / 2181	消息队列	kafka-topics.sh --list
[Mock server — e.g. WireMock]	8089	测试中用于模拟外部 API	curl localhost:8089/__admin
[LocalStack]	4566	AWS 服务模拟（S3、SQS 等）	aws --endpoint-url=http://localhost:4566 s3 ls

如果容器立即退出： 请参阅“故障排除”部分——常见原因包括端口冲突和 Docker 内存限制。

停止依赖项

# Stop containers (preserves data volumes)
docker compose stop

# Stop and remove containers (clears data — use when you want a fresh start)
docker compose down -v

---

4. 安装依赖项并构建

# Install language dependencies
# Go:
go mod download

# Node.js:
npm install   # or: yarn install / pnpm install

# Python:
python -m venv .venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt

# Verify build compiles cleanly
make build
# Expected: no errors; binary or compiled output in [./bin/ or ./dist/]

---

5. 数据库设置和填充数据

# Run database migrations (creates tables and schema)
make db-migrate
# Or directly:
# [Migration command — e.g. "go run ./cmd/migrate up" or "alembic upgrade head" or "npm run db:migrate"]

# Verify migrations applied
# psql $DATABASE_URL -c "\dt"  # should list all tables

# Seed the database with development data
make db-seed
# Or directly:
# [Seed command — e.g. "go run ./cmd/seed" or "python scripts/seed.py" or "npm run db:seed"]

# Verify seed data is present
# psql $DATABASE_URL -c "SELECT COUNT(*) FROM [primary-table]"
# Expected: [N] rows

填充数据会创建：

• [N] 个测试用户账户（凭据见 [scripts/seed/README.md or .env.example]）
• [N] 个用于开发和测试的示例 [resources]
• 管理员账户：[[email protected]] / 密码：开发环境密码变量见 .env.example

重置为干净状态：

docker compose down -v   # wipe database volume
docker compose up -d     # start fresh
make db-migrate
make db-seed

---

6. 运行服务

# Run the service locally
make run
# Or directly:
# [Run command — e.g. "go run ./cmd/server" or "python app.py" or "npm run dev"]

# Expected output:
# [Example of healthy startup log lines — e.g.:]
# {"level":"info","message":"Database connected","host":"localhost","port":5432}
# {"level":"info","message":"Redis connected","host":"localhost","port":6379}
# {"level":"info","message":"Server listening","port":8080}

验证服务是否正常运行

# Health check
curl http://localhost:8080/health
# Expected: {"status":"ok","version":"[git-sha]"}

# Test a key endpoint (authenticated)
# First, get a dev token:
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[dev-user-from-seed]@example.com","password":"[dev-password-from-env]"}'
# Copy the token from the response, then:

curl http://localhost:8080/api/v1/[resource] \
  -H "Authorization: Bearer [token-from-above]"
# Expected: 200 with JSON response

热重载（用于开发）

# Run with hot reload — service restarts automatically on file changes
make run-dev
# Or:
# [Hot reload command — e.g. "air" for Go / "uvicorn --reload" for Python / "npm run dev" for Node]

---

7. 运行测试

# Run the full test suite
make test
# Or:
# [Test command — e.g. "go test ./..." or "pytest" or "npm test"]

# Run tests with coverage report
make test-coverage
# Coverage report: [./coverage.html or stdout]

# Run a specific test file or test case
# Go: go test ./pkg/[package]/... -run TestFunctionName
# Python: pytest tests/test_[module].py::TestClass::test_method -v
# Node: npm test -- --testPathPattern=[filename]

# Run only unit tests (fast — no external dependencies)
make test-unit

# Run only integration tests (requires Docker Compose dependencies running)
make test-integration

预期测试结果：

• 单元测试：[N] 项，全部通过，耗时 [<30] 秒
• 集成测试：[N] 项，全部通过，耗时 [<2] 分钟
• 覆盖率：[≥80]%（在 CI 中强制执行——低于此阈值时测试会失败）

推送 PR 前，请务必运行：

make lint      # code linting — must pass
make test      # full test suite — must pass
make build     # verify compilation — must pass

---

8. IDE 设置

VS Code（推荐）

安装推荐的扩展（VS Code 会自动提示）：

// .vscode/extensions.json — already in the repository
{
  "recommendations": [
    "[language-extension — e.g. golang.go]",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-azuretools.vscode-docker",
    "eamodio.gitlens"
  ]
}

工作区设置位于 .vscode/settings.json 中——已启用保存时格式化，并自动配置了代码检查工具。

[Language] 专属设置：

[e.g. Go: The gopls language server is installed automatically by the Go extension.
 Run "Go: Install/Update Tools" from the command palette after installing the extension.]

JetBrains（IntelliJ / GoLand / PyCharm / WebStorm）

• 将项目根目录作为项目目录打开
• [Language SDK]：设置为 [version] — 文件 → 项目结构 → SDK
• 运行配置已纳入版本控制，位于 .idea/runConfigurations/ 中——会自动显示
• 在设置 → 工具 → 保存时操作中启用“保存时运行格式化工具”

---

9. 常见问题和故障排除

Docker 容器启动后立即退出

现象： docker compose ps 显示容器在启动几秒后状态为 Exited (1)。

# Check the container logs for the error
docker compose logs [container-name]

# Common causes:
# 1. Port already in use — find and kill the conflicting process:
lsof -ti tcp:[port] | xargs kill -9

# 2. Docker doesn't have enough memory — allocate at least 4GB in Docker Desktop:
# Docker Desktop → Settings → Resources → Memory → 4GB

# 3. M1/M2 Mac architecture mismatch — add platform directive to docker-compose.yml:
# platform: linux/amd64

数据库连接被拒绝

**症状：**服务启动失败，并显示“connection refused”或“dial tcp localhost:5432: connect: connection refused”

# Is PostgreSQL actually running?
docker compose ps postgres
# If not running: docker compose up -d postgres

# Is it on the right port?
lsof -i :5432

# Can you connect manually?
psql postgres://app:password@localhost:5432/[service]_dev -c "SELECT 1"

# If using a custom DATABASE_URL, verify it matches the docker-compose.yml settings exactly

迁移失败，并显示“relation already exists”

症状：make db-migrate 报错，显示“ERROR: relation [table] already exists”

# Check current migration state
[migration status command — e.g. "go run ./cmd/migrate status" or "alembic current"]

# The database may be in a partial state — reset it:
docker compose down -v
docker compose up -d
make db-migrate  # should now succeed on a clean database

测试失败，并显示“connection refused”或依赖项错误

**症状：**集成测试失败，因为无法连接到 PostgreSQL 或 Redis。

# Integration tests need Docker Compose running
docker compose up -d

# Verify all containers are healthy before running tests
docker compose ps   # all should show "healthy"

# If containers are running but tests still fail, check environment variables:
make test-integration  # should pick up .env.local automatically
# If not: source .env.local && make test-integration

在全新检出代码后，make lint 失败

**症状：**未修改过的文件也出现 lint 错误。

# Formatting issue — auto-fix with:
# Go:
gofmt -w .
goimports -w .

# Python:
black .
isort .

# Node/TypeScript:
npm run lint:fix
# Or: npx eslint --fix . && npx prettier --write .

# Re-run lint to confirm
make lint

环境变量未加载

**症状：**服务启动后立即失败，并显示“missing required environment variable: [VAR]”

# Verify .env.local exists and has all required variables
cat .env.local | grep "^[A-Z]" | awk -F= '{print $1}'

# Compare against required variables in .env.example
diff <(grep "^[A-Z_]*=" .env.example | cut -d= -f1 | sort) \
     <(grep "^[A-Z_]*=" .env.local | cut -d= -f1 | sort)

# Missing variables are shown in left column only (< prefix)

---

10. 首次贡献检查清单

提交首个拉取请求前，请确认：

完成设置：

• make build 执行成功，没有错误
• make test 执行成功——所有测试均通过
• make lint 执行成功——没有 lint 错误
• 服务已启动，健康检查返回 200
• 你可以完成身份验证并调用至少一个 API 端点

Git 和 GitHub：

• 你已阅读 [CONTRIBUTING.md]——了解代码规范、提交消息格式和 PR 流程
• 你的 git user.name 和 user.email 已正确设置
• 已安装 pre-commit 钩子（ls .git/hooks/pre-commit 应能找到该文件）
• 你从 main 分支创建了分支（没有直接向 main 提交）

开发工作流：

• 你知道如何运行指定测试：[test command for single test]
• 你知道如何重置数据库：docker compose down -v && docker compose up -d && make db-migrate && make db-seed
• 你已加入 [Slack: #[team-channel]]，以及 [#[service-consumers-channel]（如适用）]
• 你已阅读[架构概览文档 / README]——了解此服务的功能

首个 PR：

• 更改范围小且聚焦——每个 PR 只包含一项逻辑更改
• 已针对你的更改添加或更新测试
• 在请求评审前，已在本地通过 make test && make lint && make build
• PR 描述说明了更改内容和原因（如有需要，可使用 [pr-description-writer 技能]）

---

质量检查

• 一位对项目毫无了解的新工程师可以从头到尾遵循本指南，无需向任何人求助
• 所有命令都在干净环境中经过测试——不是凭记忆编写并想当然地认为可行
• 环境变量表涵盖 .env.example 中的每个变量——没有未记录的变量
• 故障排除部分涵盖入职过程中观察到的 5 个最常见实际问题——而非理论问题
• 明确说明 Docker Compose 版本和 Docker Desktop 内存要求
• 关键命令都提供了“预期输出”，方便工程师确认步骤是否成功
• 如实估算设置耗时——通过为实际入职过程计时进行验证，而不是估算

反模式

• 不要不经测试就在干净机器上凭记忆编写设置步骤——省略隐含知识的步骤会让新工程师遇到问题
• 不要遗漏环境变量文档——.env.example 中的每个变量都必须出现在 Variables 表中，并附有说明和来源
• 不要为理论问题编写故障排除条目——只收录实际入职过程中确实发生过的问题
• 不要假设 Docker Desktop 配置正确——必须明确说明内存限制和平台（M1/M2）兼容性
• 不要省略关键命令的预期输出——没有“预期输出”，工程师就无法判断步骤是成功了还是悄然失败了