Docker中Node.js TypeScript热重载失效问题排查

问题背景 #

本地运行Node.js TypeScript项目时热重载功能正常，确认nodemon与ts-node配置无问题。环境为Node.js 20.x + PostgreSQL 15，相关配置如下：

Dockerfile 末尾片段 #

WORKDIR /home/node/app
COPY package*.json ./
COPY nodemon.json ./
COPY . .

CMD npm install && npm run start:dev

compose.yaml 配置 #

services:
  server:
    container_name: stoopid
    build: .
    image: base
    ports:
      - "3000:3000"
    volumes:
      - ./src:/home/node/app/src

本地.ts文件均存放在./src目录，执行docker compose build和docker compose up -d启动容器后，本地文件修改能同步到容器内，但服务器未触发重启，热重载失效。

核心原因及解决方法 #

1. nodemon文件监听机制适配问题 #

默认情况下，nodemon依赖系统的inotify文件变更通知，但Docker挂载的目录可能无法正常触发该机制，导致nodemon检测不到文件变化。

解决：在nodemon配置中开启轮询模式，强制定期检查文件状态：

• 修改nodemon.json：

  {
    "watch": ["src"],
    "ext": "ts",
    "exec": "ts-node src/index.ts",
    "poll": true,
    "pollingInterval": 1000
  }
  

• 或者直接在package.json的启动命令中添加参数：

  "scripts": {
    "start:dev": "nodemon --watch src --poll src/index.ts"
  }
  

2. 容器内依赖安装时机不合理 #

当前CMD中每次启动容器都会执行npm install，虽然不直接导致热重载失效，但会增加启动时间，且可能因依赖安装过程干扰nodemon运行。

解决：将npm install移到镜像构建阶段：

WORKDIR /home/node/app
COPY package*.json ./
RUN npm install
COPY nodemon.json ./
COPY . .

CMD npm run start:dev

3. 挂载目录权限不匹配 #

本地src目录的权限与容器内运行的node用户权限不一致时，nodemon可能无法读取或监听文件变化。

解决：在compose.yaml中指定与本地用户一致的UID/GID：

services:
  server:
    # ... 其他配置
    user: "${UID}:${GID}"

启动容器时传递本地用户的UID和GID：

UID=$(id -u) GID=$(id -g) docker compose up -d

4. 后台运行导致日志无法排查 #

使用up -d后台启动容器时，nodemon的日志不会输出到前台，无法确认是否检测到文件变化。

解决：临时前台启动容器查看日志：

docker compose up server

修改本地文件后，观察控制台是否有nodemon的重启日志，以此确认监听是否生效。

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