Docker化Strapi与NextJS：解决构建依赖启动等待问题

问题核心 #

1. Docker Compose的depends_on仅控制容器启动顺序，不影响镜像构建阶段——你当前的NextJS Dockerfile在镜像构建时就执行npm run build-prod，此时Strapi容器还未启动，自然无法连接。
2. 等待脚本使用localhost:1337错误：在NextJS容器内，localhost指向容器自身，而非Strapi容器，需使用Docker服务名portfolio-strapi进行跨容器访问。

分步解决方案 #

1. 调整NextJS构建时机：从镜像构建阶段移到容器启动阶段 #

修改NextJS的Dockerfile，将构建步骤放到容器启动时执行，这样可以先等待Strapi就绪再构建：

FROM node:18-alpine

WORKDIR "/app"

COPY package.json package-lock.json ./
RUN npm install --frozen-lockfile

COPY . .

EXPOSE 3000

# 先执行等待脚本，再构建启动
CMD ["sh", "-c", "node wait-for-strapi.js && npm run build-prod && npm start"]

2. 修正等待脚本的访问地址与逻辑 #

将等待脚本的目标地址改为Docker服务名，并修复异步逻辑的错误处理，保存为client/wait-for-strapi.js：

const MAX_RETRIES = 10;
let retries = 0;

const waitForStrapi = async () => {
  while (retries < MAX_RETRIES) {
    console.log(`[ATTEMPT ${retries + 1}] 尝试连接Strapi...`);
    try {
      const res = await fetch("http://portfolio-strapi:1337");
      if (res.ok) {
        console.log("Strapi已就绪！");
        return;
      }
    } catch (e) {
      console.log("Strapi未就绪，等待30秒后重试...");
      await new Promise((resolve) => setTimeout(resolve, 30000));
    }
    retries++;
  }
  console.error("[ERROR] 无法连接到Strapi，重试次数已达上限");
  process.exit(1);
};

// 确保异步逻辑执行完成后再继续后续步骤
waitForStrapi().catch(err => {
  console.error(err);
  process.exit(1);
});

3. 给Strapi配置健康检查，确保服务真正就绪 #

修改docker-compose.yaml中portfolio-strapi的配置，添加健康检查让Docker识别服务状态：

portfolio-strapi:
  build:
    context : ./server
  ports:
    - "1337:1337"
  volumes:
    - ./portfolio-strapi:/usr/src/app
  environment:
    - NODE_ENV=development
  networks:
    - portfolio-network
  depends_on:
    - db
  # 添加健康检查
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:1337/health"] # Strapi v4默认提供/health端点
    interval: 30s
    timeout: 10s
    retries: 5
    start_period: 60s # 给Strapi和数据库足够的初始化时间

4. 让NextJS容器等待Strapi健康检查通过后启动 #

修改docker-compose.yaml中portfolio-nextjs的depends_on配置：

portfolio-nextjs:
  build:
    context : ./client
  ports:
    - "3000:3000"
  volumes:
    - ./portfolio-nextjs:/usr/src/app
  environment:
    - NODE_ENV=development
  networks:
    - portfolio-network
  depends_on:
    portfolio-strapi:
      condition: service_healthy # 等待Strapi健康检查通过后再启动

额外注意事项 #

• 若需在生产环境提前构建NextJS镜像，可先单独启动Strapi服务：docker-compose up -d portfolio-strapi，等待就绪后本地执行NextJS构建，再构建镜像。
• 根据你的数据库初始化速度，可调整Strapi健康检查的start_period参数，避免过早触发检查导致失败。
• 确认Strapi的/health端点已启用：Strapi v4默认开启，若未启用可在配置文件中手动开启。

内容的提问来源于stack exchange，提问作者Louis Lecouturier