Docker Compose启动Vue容器失败，手动Docker命令正常的问题排查

问题背景 #

使用Dockerfile容器化Vue应用时，手动执行Docker命令构建并运行完全正常，但通过docker-compose启动时，应用抛出Cannot find module @rollup/rollup-linux-x64-gnu错误，无法启动。

相关配置与日志 #

docker-compose.yml

services:
  backend:
    build:
      context: .
      dockerfile: Dockerfile  # Dockerfile for FastAPI app
    networks:
      - restonet
    ports:
      - "443:443"  # Changed to use port 8443 for development
    volumes:
      - ./:/app  # Volume for hot-reload during development
    container_name: fastapi-backend
    image: fastapi-backend-img
    restart: "no"

  frontend:
    build:
      context: ./src
      dockerfile: Dockerfile  # Dockerfile for Vue.js app
    networks:
      - restonet
    ports:
      - "5174:5174"  # Changed to match the Vite development port
    volumes:
      - ./src:/app  # Volume for hot-reload during development
    depends_on:
      - backend
    container_name: vue-frontend
    image: vue-frontend-img
    restart: "no"

networks:
  restonet:
    driver: bridge  # Let Docker Compose create an internal network

Dockerfile

FROM node:20

WORKDIR /app

COPY . .

RUN npm install

EXPOSE 5174

# Command to run the Vite development server
CMD npm run dev -- --port 5174 --host 0.0.0.0

docker-compose启动错误输出

2024-10-13 20:18:39 
2024-10-13 20:18:39 > src@0.0.0 dev
2024-10-13 20:18:39 > vite --port 5174 --host 0.0.0.0
2024-10-13 20:18:39 
2024-10-13 20:18:39 /app/node_modules/rollup/dist/native.js:59
2024-10-13 20:18:39             throw new Error(
2024-10-13 20:18:39                   ^
2024-10-13 20:18:39 
2024-10-13 20:18:39 Error: Cannot find module @rollup/rollup-linux-x64-gnu. npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). Please try `npm i` again after removing both package-lock.json and node_modules directory.
2024-10-13 20:18:39     at requireWithFriendlyError (/app/node_modules/rollup/dist/native.js:59:9)
2024-10-13 20:18:39     at Object.<anonymous> (/app/node_modules/rollup/dist/native.js:68:76)
2024-10-13 20:18:39     ... 3 lines matching cause stack trace ...
2024-10-13 20:18:39     at Module._load (node:internal/modules/cjs/loader:1104:12)
2024-10-13 20:18:39     at cjsLoader (node:internal/modules/esm/translators:346:17)
2024-10-13 20:18:39     at ModuleWrap.<anonymous> (node:internal/modules/esm/translators:286:7)
2024-10-13 20:18:39     at ModuleJob.run (node:internal/modules/esm/module_job:234:25)
2024-10-13 20:18:39     at async ModuleLoader.import (node:internal/modules/esm/loader:473:24) {
2024-10-13 20:18:39   [cause]: Error: Cannot find module '@rollup/rollup-linux-x64-gnu'
2024-10-13 20:18:39   Require stack:
2024-10-13 20:18:39   - /app/node_modules/rollup/dist/native.js
2024-10-13 20:18:39       at Module._resolveFilename (node:internal/modules/cjs/loader:1225:15)
2024-10-13 20:18:39       at Module._load (node:internal/modules/cjs/loader:1051:27)
2024-10-13 20:18:39       at Module.require (node:internal/modules/cjs/loader:1311:19)
2024-10-13 20:18:39       at require (node:internal/modules/helpers:179:18)
2024-10-13 20:18:39       at requireWithFriendlyError (/app/node_modules/rollup/dist/native.js:41:10)
2024-10-13 20:18:39       at Object.<anonymous> (/app/node_modules/rollup/dist/native.js:68:76)
2024-10-13 20:18:39       at Module._compile (node:internal/modules/cjs/loader:1469:14)
2024-10-13 20:18:39       at Module._extensions..js (node:internal/modules/cjs/loader:1548:10)
2024-10-13 20:18:39       at Module.load (node:internal/modules/cjs/loader:1288:32)
2024-10-13 20:18:39       at Module._load (node:internal/modules/cjs/loader:1104:12) {
2024-10-13 20:18:39     code: 'MODULE_NOT_FOUND',
2024-10-13 20:18:39     requireStack: [ '/app/node_modules/rollup/dist/native.js' ]
2024-10-13 20:18:39   }
2024-10-13 20:18:39 }
2024-10-13 20:18:39 
2024-10-13 20:18:39 Node.js v20.18.0

手动Docker命令操作成功日志

(.venv) PS D:\Dev\RestoR\saas-backend\src> docker build -t vue-frontend-img .
[+] Building 5.2s (10/10) FINISHED                                                                                                                                                                                  docker:desktop-linux 
 => [internal] load build definition from Dockerfile                                                                                                                                                                                0.0s 
 => => transferring dockerfile: 360B                                                                                                                                                                                                0.0s 
 => [internal] load metadata for docker.io/library/node:20                                                                                                                                                                          1.4s 
 => [auth] library/node:pull token for registry-1.docker.io                                                                                                                                                                         0.0s 
 => [internal] load .dockerignore                                                                                                                                                                                                   0.0s 
 => => transferring context: 75B                                                                                                                                                                                                    0.0s 
 => [1/4] FROM docker.io/library/node:20@sha256:fffa89e023a3351904c04284029105d9e2ac7020886d683775a298569591e5bb                                                                                                                    0.0s 
 => [internal] load build context                                                                                                                                                                                                   1.4s 
 => => transferring context: 39.36MB                                                                                                                                                                                                1.4s 
 => CACHED [2/4] WORKDIR /app                                                                                                                                                                                                       0.0s 
 => [3/4] COPY . .                                                                                                                                                                                                                  0.2s 
 => [4/4] RUN npm install                                                                                                                                                                                                           1.8s 
 => exporting to image                                                                                                                                                                                                              0.3s 
 => => exporting layers                                                                                                                                                                                                             0.2s 
 => => writing image sha256:912e0d118e0caf3b9448fa60c15373b271219286c4af40080c52b2a6bccfee88                                                                                                                                        0.0s 
 => => naming to docker.io/library/vue-frontend-img                                                                                                                                                                                 0.0s 

 1 warning found (use --debug to expand):
 - JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 16)

View build details: docker-desktop://dashboard/build/desktop-linux/desktop-linux/x0ufxchcnkox43jjyqdo3eyge
(.venv) PS D:\Dev\RestoR\saas-backend\src> docker run -it --volume "./src:/app" -p "5174:5174" --restart "no" --rm vue-frontend-img /bin/bash
root@9d8b8bd6bdf8:/app# npm run dev -- --port 5174 --host 0.0.0.0

> src@0.0.0 dev
> vite --port 5174 --host 0.0.0.0


  VITE v5.4.8  ready in 282 ms       

  ➜  Local:   http://localhost:5174/ 
  ➜  Network: http://172.17.0.2:5174/
  ➜  press h + enter to show help    

问题原因 #

核心矛盾在于卷挂载的覆盖行为：

1. 手动构建镜像时，RUN npm install是在Linux容器环境下执行的，安装的是适配Linux系统的依赖包（包括@rollup/rollup-linux-x64-gnu）。
2. 手动运行容器时，本地./src目录大概率没有Windows环境下安装的node_modules，因此挂载后容器内的/app/node_modules仍使用镜像中构建好的Linux版本依赖，运行正常。
3. docker-compose启动时，本地./src目录已经存在Windows环境下安装的node_modules，挂载后容器内的/app/node_modules被本地的Windows版本完全覆盖。Windows版本的依赖包中没有Linux系统需要的@rollup/rollup-linux-x64-gnu，因此触发模块找不到的错误。

解决方法 #

方法1：保留容器内的node_modules（推荐） #

修改docker-compose.yml中frontend服务的卷配置，添加一条匿名卷来保留容器内的node_modules，避免被本地目录覆盖：

frontend:
  # ... 其他配置不变
  volumes:
    - ./src:/app
    - /app/node_modules  # 这条配置会让Docker保留容器内的node_modules目录

此方法既能保留本地代码挂载的热重载功能，又能使用镜像中适配Linux的依赖包，是开发环境的最优解。

方法2：清理本地依赖后重新构建 #

如果本地不需要保留Windows环境的依赖文件，可以先清理本地的依赖，再重新构建：

1. 在本地./src目录执行清理命令：

   # Linux/macOS
   rm -rf node_modules package-lock.json
   # Windows
   rd /s /q node_modules && del package-lock.json
   

2. 重新用docker-compose构建并启动：

   docker-compose build --no-cache
   docker-compose up
   

方法3：启动时重新安装依赖（临时方案） #

修改Dockerfile的启动命令，在启动容器时重新安装依赖（不推荐长期使用，因为每次启动都要重新安装，效率低）：

CMD npm install && npm run dev -- --port 5174 --host 0.0.0.0

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