Docker部署Strapi应用时Webpack编译卡住问题求助

1. 检查服务器资源占用 #

Webpack编译（尤其是生产构建）对CPU和内存消耗较大，服务器资源不足会直接导致编译挂起：

• 用top或htop查看服务器整体资源使用情况，确认CPU、内存是否已耗尽
• 运行docker stats查看Strapi容器的实时资源占用，重点关注内存使用率是否接近容器限制（如果设置了mem_limit）
• 检查系统日志dmesg或/var/log/syslog，排查是否有OOM（内存不足）杀死进程的记录

2. 开启Webpack详细日志 #

默认日志粒度不足，通过环境变量强制输出编译细节：

• 在docker-compose.yml的Strapi服务中添加环境变量：

  environment:
    - WEBPACK_LOG_LEVEL=verbose
    - NODE_ENV=production # 确保和本地构建模式一致，消除模式差异影响
  

• 重新运行docker compose up --build，观察日志中Webpack的编译步骤，定位具体卡住的环节（比如某个模块、loader处理阶段）

3. 对比本地与服务器的环境差异 #

• 检查Docker版本：本地和服务器分别运行docker --version、docker compose --version，避免版本兼容性问题
• 确认镜像一致性：本地和服务器使用的Strapi/Node镜像标签完全相同（比如node:18-alpine，不要混用不同版本或系统镜像）
• 检查挂载卷权限：服务器上挂载的本地目录（比如./src:/app/src）权限是否正确，运行ls -l查看目录权限，确保容器内的node用户有读写权限，必要时用chown -R 1000:1000 ./src调整

4. 隔离问题场景 #

• 跳过Docker直接编译：在服务器上克隆代码，安装依赖后直接运行npm run build，如果仍然挂起，说明问题出在服务器环境而非Docker
• 简化容器配置：暂时去掉docker-compose.yml中的挂载卷、自定义配置，用纯镜像构建运行，排除外部配置干扰
• 测试网络连通性：如果服务器网络受限，在容器内测试npm源连通性：

  docker exec -it <strapi-container-name> npm ping npmjs.com
  

  若无法连通，在Dockerfile中添加国内镜像源配置：RUN npm config set registry https://registry.npmmirror.com/

5. 调整Webpack编译参数 #

修改Strapi的Webpack配置，降低资源消耗：

• 在项目根目录创建webpack.config.js，覆盖默认配置：

  module.exports = (config) => {
    // 禁用并行编译，减少CPU占用
    config.parallel = false;
    // 禁用缓存，避免缓存文件权限或损坏问题
    config.cache = false;
    return config;
  };
  

• 重新构建容器，观察编译是否正常完成

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