Docker容器无法监听NestJS文件变更问题求助

问题概述 #

使用NestJS+Docker+docker-compose开发后端6个月，此前文件变更可正常触发Docker内服务重载，近期突发异常：本地直接运行yarn start:dev可正常监听变更，但Docker环境下虽显示Starting compilation in watch mode...，修改本地文件后容器内文件已同步更新，但服务未重启重载。尝试过替换启动命令为npm run start:dev、清理重启Docker均无效。

配置文件参考 #

Dockerfile #

FROM node:14-alpine

ENV NODE_ENV development

ENV NODE_OPTIONS=--max_old_space_size=8192

RUN mkdir -p /usr/src/app

WORKDIR /usr/src/app

COPY . .

RUN yarn install

ENTRYPOINT ["yarn", "start:dev"]

docker-compose.yml #

services:
  api:
    image: cacao-be
    container_name: cacao-be-api
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - '3000:3000'
    depends_on:
      - postgres
    volumes:
      - ./src:/usr/src/app/src
    networks:
      - default
    links:
      - redis
    env_file:
      - .env
volumes:
  db_data:
  admin_data:
  redis_data:
    driver: local

package.json 启动脚本 #

"scripts": {
    "prebuild": "rimraf dist",
    "build": "nest build",
    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
    "start": "nest start",
    "start:dev": "nest start --watch"
}

tsconfig.json（已修正原配置的JSON语法错误） #

{
  "compilerOptions": {
    "jsx": "react",
    "module": "commonjs",
    "declaration": true,
    "removeComments": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "target": "es2017",
    "sourceMap": true,
    "outDir": "./dist",
    "baseUrl": "./",
    "incremental": true,
    "resolveJsonModule": true,
    "skipLibCheck": true
  }
}

注：原配置中"skipLibCheck": true末尾的多余逗号会导致JSON解析错误，可能引发编译异常，已修正。

tsconfig.build.json #

{
  "extends": "./tsconfig.json",
  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
}

排查与解决步骤 #

1. 强制启用轮询式文件监听 #

Node.js默认的文件监听依赖主机系统的通知机制，在macOS/Windows的Docker环境下可能存在兼容性问题。强制使用轮询模式可规避该问题：

• 修改package.json的启动脚本：

  "start:dev": "nest start --watch --watch-poll"
  

• 或者直接在docker-compose.yml中覆盖启动命令：

  command: yarn start:dev --watch-poll
  

2. 隔离容器内的node_modules依赖 #

当前挂载src目录时，若本地node_modules与容器内依赖版本不一致，可能导致监听逻辑异常：

• 在docker-compose.yml的volumes中添加匿名卷，保留容器内的依赖：

  volumes:
    - ./src:/usr/src/app/src
    - /usr/src/app/node_modules  # 避免本地目录覆盖容器内依赖
  

• 重新构建镜像：docker-compose build --no-cache api

3. 排查增量编译的缓存问题 #

tsconfig.json中启用的"incremental": true可能导致文件变更未被正确检测：

• 临时关闭增量编译，修改tsconfig.json：

  "incremental": false
  

• 重启容器测试，若恢复正常，可清理容器内的tsbuildinfo文件后重新启用增量编译。

4. 修正文件权限问题 #

容器内用户权限与本地目录权限不匹配，可能导致文件变更通知失效：

• 在Dockerfile中添加用户权限配置：

  RUN chown -R node:node /usr/src/app
  USER node
  

• 重建镜像并重启容器。

5. 验证NestJS版本一致性 #

近期若更新过NestJS依赖，可能出现版本不兼容：

• 本地执行nest --version，容器内执行docker exec cacao-be-api nest --version，确认版本一致
• 若版本不一致，在package.json中固定@nestjs/cli和@nestjs/core的版本号后重新构建镜像

内容的提问来源于stack exchange，提问作者Juan Pedro Pont Vergès