Docker环境中Strapi项目启动命令失败：documentation插件Bootstrap函数报错求助

我之前也踩过类似的Strapi容器化坑，结合你的报错信息和配置来看，这个问题大概率和数据库初始化顺序、卷挂载路径冲突，或者插件的文档生成逻辑有关，下面一步步拆解原因和解决方案：

错误原因分析 #

1. 数据库就绪状态不匹配
   你本地环境的数据库是现成的，Strapi启动时能直接读取到完整的模型数据；但Docker里的depends_on只是保证服务启动顺序，不保证MySQL完全初始化完成。当documentation插件在bootstrap阶段尝试生成API文档时，数据库还没准备好，导致读取模型定义时出现undefined，进而触发Cannot read property 'attributes' of undefined错误。

2. 卷挂载路径冲突
   你的Dockerfile把项目文件复制到了/usr/srv/app/backend/，但docker-compose里给Strapi服务挂载了./app:/srv/app——这会导致容器内的/srv/app被本地目录覆盖，而Strapi的工作目录是/usr/srv/app/backend/，很可能出现文件路径混乱，插件找不到正确的模型配置文件。

3. documentation插件的自动生成时机问题
   这个插件会在Strapi启动时自动扫描模型生成文档，容器化环境中首次启动时，模型数据还没和数据库同步，插件就提前执行，导致读取到未定义的模型对象。

解决方案建议 #

1. 确保数据库完全就绪后再启动Strapi #

depends_on不保证数据库服务可用，我们可以给Strapi加个启动前的等待逻辑：

• 方法一：修改Strapi的Dockerfile，添加wait-for-it脚本等待MySQL端口：

  FROM strapi/strapi:3.6.8-node12
  ENV NODE_ENV staging
  WORKDIR /usr/srv/app/backend/
  
  # 安装wait-for-it工具
  RUN apt-get update && apt-get install -y wget
  RUN wget -O /usr/local/bin/wait-for-it https://raw.githubusercontent.com/vishnubob/wait-for-it/master/wait-for-it.sh
  RUN chmod +x /usr/local/bin/wait-for-it
  
  COPY ./backend/package.json .
  RUN npm install
  COPY ./backend/favicon.ico .
  COPY ./backend/public/robots.txt ./public/
  COPY ./backend/extensions/ ./extensions/
  COPY ./backend/api/ ./api/
  COPY ./backend/config/ ./config/
  COPY ./backend/data/ ./data/
  COPY ./backend/public/ ./public/
  RUN npm run build --clean
  
  # 先等待mysql_db的3306端口可用，再启动Strapi
  ENTRYPOINT ["wait-for-it", "mysql_db:3306", "--", "npm", "start"]
  

• 方法二：在docker-compose的strapi服务里添加等待命令（需要容器内有nc工具，若没有可在Dockerfile里安装netcat）：

  strapi:
    container_name: strapi
    build:
      context: .
      dockerfile: ./docker/backend/Dockerfile
    volumes:
      - ./app:/srv/app
    environment:
      # ...你的环境变量
    ports:
      - "1337:1337"
    depends_on:
      - mysql_db
    # 添加等待逻辑
    command: sh -c "until nc -z mysql_db 3306; do sleep 1; done; npm start"
    networks:
      - strapi
  

2. 调整卷挂载路径，避免文件覆盖 #

把docker-compose里Strapi的卷挂载路径改成和Dockerfile工作目录一致：

strapi:
  # ...其他配置
  volumes:
    - ./backend:/usr/srv/app/backend

这样本地的backend目录会直接映射到容器内的Strapi工作目录，不会覆盖其他路径的文件，保证插件能找到正确的模型配置。

3. 临时禁用或延迟documentation插件的自动生成 #

如果暂时不需要API文档，可以先禁用插件验证Strapi是否能正常启动：
在backend/config/plugins.js里添加配置：

module.exports = {
  // ...其他插件配置
  documentation: {
    enabled: false,
  },
};

如果需要保留插件，等Strapi完全启动后，手动访问/admin/plugins/documentation/generate触发文档生成。

4. 修复容器内的文件权限 #

确保容器内的项目文件属于strapi用户，避免读取权限问题：
在Dockerfile最后添加：

RUN chown -R strapi:strapi /usr/srv/app/backend

5. 清理插件缓存 #

有时候插件的缓存会导致异常，启动前清理缓存试试：
在docker-compose的strapi服务里修改命令：

strapi:
  command: sh -c "rm -rf /usr/srv/app/backend/node_modules/strapi-plugin-documentation/.cache; npm start"

验证步骤 #

调整配置后，彻底清理旧容器和卷，重新构建启动：

docker-compose down -v
docker-compose build --no-cache
docker-compose up

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