1. 理解问题本质
在使用 Docker 和 Docker Compose 构建 Node.js 项目时，一个常见的问题是：即使执行了 npm install，在容器中运行时仍然提示模块找不到。这通常是因为容器中的 node_modules 被宿主机的目录挂载覆盖了。
根本原因在于：Docker 在构建镜像时确实安装了依赖，但当你在 docker-compose.yml 中使用 volumes 挂载本地目录时，宿主机的项目目录会覆盖容器内原有的内容。如果宿主机上没有 node_modules，容器中原本安装好的依赖就会被“隐藏”，从而导致模块找不到的错误。
✅ 这是一个典型的 Docker 卷挂载陷阱，尤其是开发环境下频繁使用 bind mount 的时候。
2. 示例项目结构
我们以一个典型的项目结构为例，说明问题和解决方案：
project/
│── web/
│ └─ Dockerfile
│── worker/
│ └─ Dockerfile
└── docker-compose.yml
我们重点关注 worker 目录下的 Node.js 应用。
worker/Dockerfile
FROM node:14
WORKDIR /worker
COPY package.json /worker/
RUN npm install
COPY . /worker/
docker-compose.yml
version: '3'
services:
web:
build: ./web
ports:
- "5000:5000"
worker:
build: ./worker
command: npm start
ports:
- "9730:9730"
volumes:
- ./worker:/worker
links:
- redis
redis:
image: redis
构建时 npm install 是成功的，但运行时却提示模块找不到。问题出在 volumes 挂载了 ./worker:/worker，覆盖了容器内的 /worker，导致 node_modules 被隐藏。
3. 解决方案一：将 node_modules 安装到其他目录
我们可以通过修改 Dockerfile，把依赖安装到一个独立的目录中，避免被 volume 覆盖。
修改后的 Dockerfile
FROM node:14
WORKDIR /install
COPY package.json /install/
RUN npm install
ENV NODE_PATH=/install/node_modules
WORKDIR /worker
COPY . /worker/
这样，node_modules 会被安装在 /install/node_modules，而 /worker 依然可以挂载宿主机的目录。
优点
- 实现简单
- 不需要修改
docker-compose.yml
缺点
- 需要设置
NODE_PATH，可能影响某些模块的加载方式 - 如果项目中有动态加载模块的逻辑，可能需要额外适配
4. 解决方案二：容器启动时自动安装依赖
我们也可以在容器启动时再执行 npm install，这样能确保每次运行时都使用最新的 package.json。
修改 Dockerfile
FROM node:14
WORKDIR /worker
COPY package.json /worker/
COPY . /worker/
CMD ["sh", "-c", "npm install && npm start"]
修改 docker-compose.yml
worker:
build: ./worker
command: sh -c "npm install && npm start"
ports:
- "9730:9730"
volumes:
- ./worker:/worker
优点
- 依赖始终与当前代码同步
- 适合开发环境，代码频繁变更
缺点
- 容器启动变慢，每次都要安装依赖
- 不适合生产环境使用
5. 解决方案三：使用命名卷保存 node_modules
这是推荐的做法之一：**使用 bind mount 挂载源码目录，同时使用 named volume 挂载 node_modules**，确保依赖不被覆盖。
修改 docker-compose.yml
version: '3'
services:
worker:
build: ./worker
command: npm start
ports:
- "9730:9730"
volumes:
- ./worker:/worker
- worker_node_modules:/worker/node_modules
links:
- redis
volumes:
worker_node_modules:
优点
- 依赖持久化，重启容器不丢失
- 开发时可实时同步代码
- 适合中大型项目
缺点
- 需要管理额外的卷
- 卷数据不会自动清理，需手动处理
6. 高级技巧：优化 npm 缓存加快构建
如果你发现每次构建都重新下载依赖影响效率，可以利用 npm cache 加速构建过程。
使用多阶段构建优化缓存
# Stage 1: Build
FROM node:14 AS builder
WORKDIR /worker
COPY package.json package-lock.json ./
RUN npm install --prefer-offline --no-audit --progress=false
COPY . .
# Stage 2: Runtime
FROM node:14-alpine
WORKDIR /worker
COPY --from=builder /worker .
CMD ["npm", "start"]
说明
--prefer-offline：优先使用缓存- 多阶段构建：构建阶段用完整镜像，运行阶段用轻量镜像
- 利用 Docker 的 layer 缓存机制，提升构建效率
7. 总结与建议
| 方案 | 优点 | 缺点 | 推荐场景 |
|---|---|---|---|
| 安装到其他目录 | 简单，不改 yml | 需设置 NODE_PATH | 小型项目 |
| 启动时安装依赖 | 依赖与代码同步 | 容器启动慢 | 开发环境 |
| 命名卷挂载 node_modules | 依赖持久化 | 管理复杂 | 中大型项目 |
| 多阶段 + 缓存优化 | 构建速度快 | 略复杂 | 所有场景 |
✅ 推荐做法：使用命名卷（named volume）挂载 node_modules，同时 bind mount 源码目录。这是目前最稳定、最灵活的方案，兼顾了开发效率和依赖管理。
⚠️ 踩坑提醒：不要直接在容器中修改依赖，也不要忽略 .dockerignore 的设置，避免不必要的文件被复制进镜像。