📚 课程目录第4章开发环境搭建

4. 开发环境搭建：本地开发环境配置、Docker容器化环境、版本控制（Git）工作流、CI/CD流水线设计

说实话，我见过太多团队在环境搭建上栽跟头。有的项目上线前才发现开发环境和生产环境差了三个大版本，有的新同事入职第一周全在配环境。这些坑，我自己都踩过不止一次。

这一章，我把这些年积累的环境搭建经验拆开揉碎了讲。从本地配置到容器化，从Git工作流到CI/CD流水线，咱们一步步来。

4.1 本地开发环境配置

本地环境是开发的起点。我的原则是：可复现、可隔离、可清理。

4.1.1 语言运行时管理

别用系统自带的包管理器装语言运行时。我推荐用版本管理工具：

Node.js：用 nvm 或 fnm
Python：用 pyenv + virtualenv 或 poetry
Java：用 sdkman
Go：用 gvm

我的习惯：每个项目根目录放一个 .nvmrc 或 .python-version 文件。这样团队成员切到项目目录时，工具能自动切换版本。省心。

4.1.2 编辑器与插件

我个人偏好 VS Code，但这不是重点。重点是编辑器配置要纳入版本控制。

项目根目录下建一个 .vscode 文件夹，把 settings.json、launch.json、extensions.json 都放进去。新成员拉下代码就能一键安装推荐插件，调试配置也现成的。

注意：别把个人偏好塞进项目配置。比如缩进用2空格还是4空格，这个可以统一。但主题、字体、快捷键这些，留在用户级别的 settings.json 里。

4.1.3 环境变量管理

我曾经见过有人把数据库密码直接写在代码里……嗯，那是个难忘的周一。

正确做法：

用 .env.example 模板文件提交到 Git
真实的 .env 文件加入 .gitignore
敏感信息走密钥管理服务（如 Vault、AWS Secrets Manager）

# .env.example
DB_HOST=localhost
DB_PORT=5432
DB_USER=app_user
DB_PASSWORD=your_password_here
REDIS_URL=redis://localhost:6379

4.2 Docker容器化环境

本地环境配得再好，也架不住「我机器上能跑啊」这种经典台词。Docker 就是来解决这个问题的。

4.2.1 Dockerfile 最佳实践

写 Dockerfile 有几个原则：

分层构建：把不常变的层放在前面，利用缓存
多阶段构建：构建环境和运行环境分离
最小镜像：用 alpine 或 distroless 基础镜像

# 多阶段构建示例
# 第一阶段：构建
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

# 第二阶段：运行
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/index.js"]

4.2.2 Docker Compose 编排

微服务开发时，用 Docker Compose 把依赖的服务（数据库、缓存、消息队列）都拉起来。我习惯在项目根目录放一个 docker-compose.yml：

version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - db
      - redis
    environment:
      - DB_HOST=db
      - REDIS_HOST=redis

  db:
    image: postgres:15-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=app_dev

  redis:
    image: redis:7-alpine

volumes:
  pgdata:

  关键点：开发环境用 Docker Compose，生产环境用 Kubernetes。别把 Compose 文件直接往生产扔。

4.3 版本控制（Git）工作流

Git 工作流选型，我经历过好几个阶段。从最早的 Git Flow，到后来的 GitHub Flow，再到现在的 Trunk-Based Development。没有银弹，看团队规模和发布节奏。

4.3.1 分支策略对比

工作流	适用场景	分支数量	发布频率
Git Flow	固定版本发布（如移动端）	多（master, develop, release, hotfix, feature）	低（周/月）
GitHub Flow	持续交付的 Web 服务	少（main + feature）	高（天/小时）
Trunk-Based	高频发布的微服务	极少（main + 短期 feature）	极高（多次/天）

我个人推荐中小团队用 GitHub Flow。简单，够用。别整太复杂的分支策略，团队记不住。

4.3.2 Commit 规范

Commit message 写清楚，不是为了好看，是为了以后查问题能少死几个脑细胞。

我团队用 Conventional Commits 规范：

feat: 添加用户注册功能
fix: 修复登录页面空指针异常
docs: 更新 API 文档
refactor: 重构订单模块的数据库查询逻辑
test: 添加支付接口的单元测试
chore: 升级依赖版本

小技巧：配合 commitlint 和 husky，在提交时自动校验格式。不符合规范的提交直接拒绝。

4.3.3 Code Review 流程

Code Review 不是走过场。我见过太多「LGTM」式的 Review，那跟没 Review 一样。

PR 不要太大，200行以内最好
Reviewer 要真正理解改动
用 GitHub 的 Review 功能，别在 IM 群里发代码截图

4.4 CI/CD流水线设计

CI/CD 是开发流程的「高速公路」。路修好了，代码才能顺畅地从开发环境跑到生产环境。

4.4.1 流水线阶段划分

一个标准的 CI/CD 流水线，我一般分这几个阶段：

代码检查：lint、格式化检查、安全扫描
单元测试：跑最快的测试，快速反馈
构建：编译、打包、生成镜像
集成测试：启动依赖服务，跑端到端测试
部署：推送到测试环境/预发布环境
验收：冒烟测试、性能测试

  原则：流水线要快。如果一次 CI 跑 30 分钟，开发者会想办法绕过它。我见过最夸张的团队，CI 跑 2 小时……后来他们改成了 8 分钟。

4.4.2 流水线配置示例（GitHub Actions）

name: CI/CD Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run lint
      - run: npm test

  build-and-deploy:
    needs: lint-and-test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: docker build -t myapp:${{ github.sha }} .
      - run: docker push myapp:${{ github.sha }}
      - run: kubectl set image deployment/myapp myapp=myapp:${{ github.sha }}

4.4.3 流水线设计原则

快速失败：最可能失败的步骤放前面
幂等性：同一份代码，跑多少次结果都一样
可追溯：每个构建产物都能追溯到代码版本
环境一致性：开发、测试、生产用同一份 Dockerfile

我曾经踩过的坑：测试环境用 Docker Compose，生产环境用 Kubernetes，结果镜像标签策略不一致，导致测试通过的版本部署到生产就挂了。后来我统一了镜像标签规范：<服务名>:<Git SHA>，所有环境都用同一个镜像。

4.5 知识体系总览

下面这张图，把本章的核心脉络串起来了。你可以把它当作环境搭建的「检查清单」。

环境搭建这件事，说白了就是把「人肉操作」变成「自动化流程」。你想想看，如果每次新成员加入都要花两天配环境，那这项目迟早要出问题。把这些基础设施做好，后面才能专心写业务代码。