React项目修改后Docker容器不生效，需重启/重建的问题排查

问题概述 #

项目包含Nginx、React等四个组件，所有容器均可正常运行，但存在以下问题：React容器对代码修改无响应——既不会自动更新页面，即使通过Ctrl+F5强制刷新也无法看到修改效果，仅在重启或重建容器后修改才会生效。操作系统为Windows 10。

相关配置片段 #

docker-compose.yaml（部分）

frontend:
  container_name: ${PROJECT_NAME}-frontend
  build:
    context: ./frontend
  volumes:
    - ./api:${API_DIRECTORY}
  networks:
    dockertemplate:
      ipv4_address: ${FRONTEND_IPV4}

nginx:
  container_name: ${PROJECT_NAME}-nginx
  build:
    context: ./docker/nginx
  volumes:
    - ./api:${API_DIRECTORY}
    - ./frontend:${FRONTEND_DIRECTORY}
  depends_on:
    - api
  environment:
    API_DIRECTORY: ${API_DIRECTORY}
    FRONTEND_DIRECTORY: ${FRONTEND_DIRECTORY}
  networks:
    dockertemplate:
      ipv4_address: ${NGINX_IPV4}

docker-compose.local.yaml（部分）

frontend:
  build:
    dockerfile: ../docker/frontend/Dockerfile
  restart: unless-stopped
  command: npm start
  stdin_open: true
  tty: true
  volumes:
    - ./frontend:${FRONTEND_DIRECTORY}
  environment:
    NODE_ENV: dev
    CHOKIDAR_USEPOLLING: true
    WDS_SOCKET_PORT: 0

nginx:
  build:
    dockerfile: Dockerfile
  restart: unless-stopped
  volumes:
    - ./docker/certs/local:/etc/nginx/certs
  ports:
    - 80:80
    - 443:443
    - 8443:8443
  environment:
    NGINX_HOST: ${NGINX_HOST_LOCAL}
    NGINX_PORT: ${NGINX_PORT_LOCAL}
    NGINX_CERT_CRT: ${NGINX_CERT_CRT_LOCAL}
    NGINX_CERT_KEY: ${NGINX_CERT_KEY_LOCAL}

Nginx配置

server {
    listen 80;
    server_name ${NGINX_HOST};

    return 301 https://${NGINX_HOST};
}

server {
    listen ${NGINX_PORT} ssl http2;
    server_name ${NGINX_HOST};

    ssl_certificate /etc/nginx/certs/${NGINX_CERT_CRT};
    ssl_certificate_key /etc/nginx/certs/${NGINX_CERT_KEY};

    root ${API_DIRECTORY}/public;

    location / {
        proxy_pass http://frontend:3000;
        root ${FRONTEND_DIRECTORY}/public;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        add_header Cache-Control "private, must-revalidate, max-age=3153600";
    }

    location ~ ^/(/|static/|images/|img/|javascript/|js/|css/|dist/|media/|locales/|logo192.png|robots.txt|favicon.ico|manifest.json|.+.hot-update.js) {
       proxy_pass http://frontend:3000;
       root ${FRONTEND_DIRECTORY}/public;
       access_log off;
       add_header Cache-Control no-cache;
       expires 1s;
    }

    location /api {
        proxy_pass http://api:5000;
        try_files $uri /index.php$is_args$args;
        root ${API_DIRECTORY}/public;
    }

    location ~ \.php$ {
        try_files $uri /index.php$is_args$args;
        fastcgi_pass api:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        internal;
    }

    location ~* .+\.(jpg|jpeg|gif|png|ico|css|zip|tgz|gz|rar|bz2|doc|xls|exe|pdf|ppt|txt|js|tar|wav|bmp|rtf|mp4|svg|svgz)$ {
        root ${API_DIRECTORY}/public;
        add_header Cache-Control "private, max-age=3153600";
    }
}

server {
    listen 13306 ssl;
    server_name ${NGINX_HOST};

    ssl_certificate /etc/nginx/certs/${NGINX_CERT_CRT};
    ssl_certificate_key /etc/nginx/certs/${NGINX_CERT_KEY};

    location / {
        proxy_pass http://mysql:13306;
    }
}

Frontend Dockerfile

ARG NODE_VERSION=20.11

FROM node:${NODE_VERSION}

WORKDIR /var/www/dockertemplate/frontend

COPY package*.json ./

RUN npm install

RUN npm cache clean -f
RUN npm cache verify
RUN npm install -g react-scripts
#RUN npm audit fix

COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
ENTRYPOINT ["docker-entrypoint.sh"]

docker-entrypoint.sh

#!/bin/sh

npm install

set -e

if [ "${1#-}" != "${1}" ] || [ -z "$(command -v "${1}")" ]; then
  set -- node "$@"
fi

exec "$@"

核心原因分析 #

• 卷映射路径不匹配：Dockerfile设置的工作目录为/var/www/dockertemplate/frontend，若${FRONTEND_DIRECTORY}环境变量值与该路径不一致，本地代码修改无法同步到容器内React项目的工作目录，导致WDS（Webpack Dev Server）无法检测到变化。
• Nginx缓存策略冲突：主location /配置中的max-age=3153600会让浏览器长期缓存页面，即使React生成新内容，浏览器也优先读取缓存；同时该location中设置的root会让Nginx直接读取本地静态文件，绕过React的WDS。
• WebSocket代理缺失：React热重载依赖WebSocket传递更新信号，当前Nginx配置未专门处理WDS的WebSocket路径（如/sockjs-node/），可能导致连接失败，热重载信号无法到达浏览器。
• Windows文件系统限制：Windows下Docker Desktop或WSL2对跨系统文件事件的监听存在延迟，卷挂载的文件权限也可能导致WDS无法读取文件变化。

解决步骤 #

1. 修正卷映射路径一致性 #

• 检查.env文件，确保FRONTEND_DIRECTORY=/var/www/dockertemplate/frontend，与Dockerfile的WORKDIR完全一致。
• 若环境变量配置无误但同步失效，直接修改卷映射：

  volumes:
    - ./frontend:/var/www/dockertemplate/frontend
  

• 执行docker-compose exec frontend ls -l /var/www/dockertemplate/frontend，确认本地修改的文件已同步到容器内。

2. 调整Nginx缓存与代理配置 #

• 修改主location /配置，移除静态文件根路径并禁用缓存：

  location / {
      proxy_pass http://frontend:3000;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection 'upgrade';
      proxy_set_header Host $host;
      proxy_cache_bypass $http_upgrade;
      # 禁用浏览器缓存
      add_header Cache-Control "no-cache, no-store, must-revalidate";
      add_header Pragma "no-cache";
      add_header Expires 0;
  }
  

• 新增WebSocket专属代理配置：

  location /sockjs-node/ {
      proxy_pass http://frontend:3000;
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";
      proxy_set_header Host $host;
  }
  

3. 优化Windows文件监听 #

• 若使用WSL2，将项目目录迁移至WSL2内部文件系统（如~/projects/），避免使用Windows挂载目录（/mnt/c/等），提升文件事件监听可靠性。
• 调整热重载轮询配置，添加轮询间隔：

  environment:
    CHOKIDAR_USEPOLLING: true
    CHOKIDAR_INTERVAL: 100
  

• 修复容器内文件权限：

  docker-compose exec frontend chown -R node:node /var/www/dockertemplate/frontend
  

4. 验证热重载功能 #

• 启动容器后，查看frontend日志：docker-compose logs -f frontend，确认代码修改时出现Compiling...和webpack compiled successfully的输出。
• 打开浏览器开发者工具（F12），切换到Network标签，检查WebSocket连接状态为101 Switching Protocols，确认连接成功。

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