AI Coding Agent 开发环境配置：Dev Container、Compose 和镜像预检

1. 问题背景

团队开始让 AI Coding Agent 处理小任务后，最常见的失败点不是"代码不会改"，而是环境跑不起来。

我遇到过几类典型日志：

text 复制代码

npm test
# error: The engine "node" is incompatible with this module

pytest
# error: pg_config executable not found

npx playwright test
# error: Host system is missing dependencies to run browsers

docker compose up -d
# api connects postgres before postgres is ready

这些问题对人来说都能绕：切一下 Node 版本、装个系统库、手工起数据库、重新跑一遍测试。但 AI Coding Agent 只能按仓库里的显式配置执行。环境没有写清楚，它就会先卡在 setup 阶段。

本文给一套可复制的配置思路：

用 Dev Container 固定语言运行时和系统依赖。
用 Docker Compose 固定 Postgres、Redis 等依赖服务。
用脚本固定 test、lint、dev、migrate 入口。
用镜像预检提前排掉 pull 阶段的不确定性。

2. 推荐目录结构

先把环境文件放进仓库，而不是放在个人电脑里。

text 复制代码

.
├── .devcontainer/
│   ├── devcontainer.json
│   └── Dockerfile
├── compose.dev.yaml
├── .env.example
├── package.json
├── Makefile
└── README.md

建议分工：

文件	作用
`.devcontainer/devcontainer.json`	定义开发容器、端口、启动后命令
`.devcontainer/Dockerfile`	固定语言版本和系统依赖
`compose.dev.yaml`	固定数据库、缓存、对象存储等依赖服务
`.env.example`	给新环境和 AI agent 明确变量入口
`package.json` / `Makefile`	提供统一任务入口
`README.md`	解释背景，不承载全部机器步骤

README 可以保留说明，但机器要执行的步骤要尽量进配置。

3. Dev Container 配置

最小 devcontainer.json：

json 复制代码

{
  "name": "ai-ready-dev",
  "build": {
    "dockerfile": "Dockerfile"
  },
  "forwardPorts": [3000],
  "postCreateCommand": "npm ci",
  "remoteEnv": {
    "NODE_ENV": "development"
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint"
      ]
    }
  }
}

对应 Dockerfile：

dockerfile 复制代码

FROM docker.1ms.run/node:22-alpine

RUN apk add --no-cache \
    bash \
    curl \
    git \
    python3 \
    make \
    g++ \
    libc6-compat

WORKDIR /workspace

这里解决三件事：

Node 版本固定，不再依赖本机。
native module 需要的构建工具提前装好。
AI 执行 npm ci 时环境一致。

如果是 Python 项目，也可以用类似方式固定：

dockerfile 复制代码

FROM docker.1ms.run/python:3.12-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    libpq-dev \
    curl \
    git \
  && rm -rf /var/lib/apt/lists/*

WORKDIR /workspace

4. Compose 固定依赖服务

AI Coding Agent 跑接口测试时，最容易踩到数据库和缓存状态不一致。

示例 compose.dev.yaml：

yaml 复制代码

services:
  app:
    image: docker.1ms.run/node:22-alpine
    working_dir: /workspace
    volumes:
      - .:/workspace
    command: sh -c "npm ci && npm run dev"
    ports:
      - "3000:3000"
    env_file:
      - .env.example
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  postgres:
    image: docker.1ms.run/postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 3s
      retries: 20

  redis:
    image: docker.1ms.run/redis:7
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 20

注意：depends_on.condition: service_healthy 只能解决"服务还没 ready 就连接"的一部分问题，业务代码里仍然要有连接重试。

5. 固定 AI 可执行命令

不要只给 AI 写"帮我跑一下项目"。建议把命令固定到 Makefile 或 package.json。

示例 package.json：

json 复制代码

{
  "scripts": {
    "dev": "vite --host 0.0.0.0",
    "lint": "eslint .",
    "test": "vitest run",
    "test:e2e": "playwright test",
    "db:migrate": "prisma migrate deploy",
    "db:seed": "node scripts/seed.js"
  }
}

示例 Makefile：

makefile 复制代码

setup:
	docker compose -f compose.dev.yaml pull
	docker compose -f compose.dev.yaml up -d
	npm ci

check:
	npm run lint
	npm test

e2e:
	npm run test:e2e

给 AI Coding Agent 的任务可以写成：

bash 复制代码

make setup
make check

这样失败时，日志能定位在 setup、lint、unit test、E2E 或数据库初始化阶段。

6. 镜像预检

开发容器和依赖服务通常至少包含这些镜像：

Node / Python / Go / Java 运行时。
Postgres / MySQL / Redis / MinIO。
Playwright / Chromium 相关运行时。
Nginx / Caddy 等本地代理。

建议在 AI 任务开始前做固定 tag 预检：

bash 复制代码

docker pull docker.1ms.run/node:22-alpine
docker pull docker.1ms.run/python:3.12-slim
docker pull docker.1ms.run/postgres:16
docker pull docker.1ms.run/redis:7

毫秒镜像（1ms.run）在这里解决的是镜像入口和拉取稳定性问题。它不是 AI Coding Agent，也不能替代测试、review 和权限控制。它适合放在 Dev Container 基础镜像、Compose 服务镜像、CI 预拉镜像这些位置。

7. 验证步骤

建议按下面顺序验证，不要一上来就让 AI 改业务代码：

bash 复制代码

docker compose -f compose.dev.yaml pull
docker compose -f compose.dev.yaml up -d
docker compose -f compose.dev.yaml ps
npm ci
npm run lint
npm test

如果有 Playwright：

bash 复制代码

npx playwright install --with-deps
npm run test:e2e

如果有数据库迁移：

bash 复制代码

npm run db:migrate
npm run db:seed

8. 常见问题排查

现象	优先检查
`npm ci` 失败	Node 版本、lockfile、native module 系统依赖
`pytest` 缺库	Python 镜像、`libpq-dev`、`build-essential`
API 连不上数据库	`.env.example`、Compose 网络、healthcheck
`docker compose up` 成功但接口 500	迁移和 seed 是否执行
Playwright 报浏览器依赖	浏览器依赖是否进入容器
AI 改完代码无法验证	`test`/`lint` 是否有固定入口

9. 小结

AI Coding Agent 进入团队后，开发环境会从"人能凑合"变成"机器必须复现"。

实操优先级建议是：

固定语言版本和系统依赖。
固定 Postgres、Redis 等依赖服务。
固定测试、lint、迁移命令。
固定基础镜像 tag 并提前预检。
让 AI 在同一套 setup -> check -> run 链路里工作。

先让项目跑起来，再讨论 AI 改得好不好。