Windows11 WSL2 Docker容器内Next.js热重载不工作问题

热重载失效的核心原因是你的项目存放在Windows系统盘的WSL挂载路径 /mnt/c/Users/liang/OneDrive/Desktop/open_source/frontend 下。WSL2对Windows宿主文件系统的inotify文件变更事件支持存在已知兼容性缺陷，Docker Desktop挂载这类跨系统目录时，容器内运行的Next.js开发服务无法接收到代码保存触发的文件变更通知，只能靠重启服务重新读取文件才能加载修改内容。

方案1：将项目迁移到WSL2原生文件系统（最优，无性能损耗） #

这是Docker官方推荐的WSL2开发最佳实践，可彻底解决文件监听问题，同时项目读写性能比放在/mnt/c挂载路径下高3-10倍：

• 打开WSL2终端，在WSL用户主目录下创建工作目录：mkdir -p ~/projects
• 将整个frontend项目从Windows挂载路径移动到WSL原生目录：mv /mnt/c/Users/liang/OneDrive/Desktop/open_source/frontend ~/projects/
• 调整Docker挂载配置，将容器内的项目目录映射到WSL原生路径 ~/projects/frontend
• 重启开发容器，热重载即可正常工作。

开发时直接用VS Code的WSL远程连接功能打开WSL内的项目即可，编辑体验和本地打开Windows文件完全一致，不需要把文件挪回Windows桌面。

方案2：启用Next.js文件轮询监听（无需迁移项目，兼容方案） #

如果暂时不想调整项目存储位置，可以让Next.js放弃依赖系统inotify事件，改用定时轮询检查文件变更：

1. 打开项目根目录的next.config.js文件（不存在则新建），添加webpack监听配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { dev }) => {
    if (dev) {
      config.watchOptions = {
        poll: 1000, // 每1秒扫描一次文件变更
        aggregateTimeout: 300,
      }
    }
    return config
  },
}

module.exports = nextConfig

2. 修改package.json中的dev启动命令，强制底层文件监听模块启用轮询：

"scripts": {
  "dev": "CHOKIDAR_USEPOLLING=true WATCHPACK_POLLING=true next dev -p 4000",
  // 其余脚本保持原有配置不变
}

3. 重建Docker开发容器镜像并重启服务，热重载即可恢复。该方案的缺点是轮询会额外占用少量CPU资源，超大型项目下可能存在轻微延迟。

方案3：排查Docker与系统配置问题 #

如果上述方案操作后仍有问题，逐一检查以下配置：

• 打开Docker Desktop设置，进入「Resources -> WSL Integration」页面，确认当前使用的WSL发行版集成开关已开启
• 检查Docker挂载配置（docker run命令或docker-compose.yml），确认项目目录挂载没有添加:ro只读参数，标准挂载写法参考：

# docker-compose.yml volumes配置示例
volumes:
  - ./:/app
  - /app/node_modules

• 暂停项目所在目录的OneDrive同步功能，避免OneDrive文件锁拦截文件变更事件，也可以直接把项目移出OneDrive目录存放。

环境配置截图 #

• 环境配置截图1
• 环境配置截图2
• 环境配置截图3

现有package.json配置 #

{
  "name": "frontend",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev -p 4000",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "test": "jest",
    "test.watch": "jest --watch",
    "db.clear": "mongosh \"mongodb://localhost:27017/ramses?readPreference=primary&ssl=false\" --eval 'db.dropDatabase(\"ramses\")'",
    "db.init": "mongosh \"mongodb://localhost:27017/ramses?readPreference=primary&ssl=false\" .submodules/ecommerce/db/nosql/*"
  },
  "dependencies": {
    "@babel/cli": "7.16.0",
    "@babel/core": "7.16.5",
    "@elastic/elasticsearch": "^8.2.1",
    "@elastic/react-search-ui": "^1.13.0",
    "@elastic/react-search-ui-views": "^1.13.0",
    "@elastic/search-ui": "^1.12.1",
    "@elastic/search-ui-app-search-connector": "^1.13.0",
    "@elastic/search-ui-elasticsearch-connector": "^1.14.0",
    "@headlessui/react": "^1.6.4",
    "@heroicons/react": "^1.0.6",
    "@hookform/resolvers": "^2.8.8",
    "@material-ui/core": "^4.12.3",
    "@sendgrid/mail": "^7.7.0",
    "@tailwindcss/forms": "^0.5.2",
    "autoprefixer": "latest",
    "babel-loader": "^8.2.3",
    "bcryptjs": "^2.4.3",
    "bl": "^5.0.0",
    "browserify-fs": "^1.0.0",
    "enhanced-resolve": "^5.8.3",
    "eslint": "^8.6.0",
    "eslint-config-next": "^12.0.7",
    "follow-redirects": "^1.14.8",
    "form-data": "^4.0.0",
    "mailgun": "^0.5.0",
    "moment": "^2.29.3",
    "mongodb": "^4.7.0",
    "mongoose": "^6.3.8",
    "multer": "^1.4.5-lts.1",
    "nanoid": "^3.2.0",
    "next": "^12.1.6",
    "next-auth": "^4.5.0",
    "next-auth-client": "^1.5.0",
    "next-connect": "^0.12.2",
    "next-i18next": "^11.0.0",
    "node-fetch": "^3.2.6",
    "nodemailer": "^6.7.2",
    "nodemon": "^2.0.16",
    "object-keys": "^1.1.1",
    "path-browserify": "^1.0.1",
    "postcss": "^8.4.12",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "react-hook-form": "^7.25.0",
    "react-responsive-carousel": "^3.2.22",
    "react-table": "^7.7.0",
    "react-test-renderer": "17.0.2",
    "react-toastify": "^8.2.0",
    "semver": "^7.3.5",
    "sharp": "^0.30.5",
    "stripe": "^9.5.0",
    "tailwind-styled-components": "^2.1.7",
    "tailwindcss": "^3.1.3",
    "typescript": "^4.7.3",
    "uuid": "^8.3.2",
    "webpack": "^5.73.0",
    "yup": "^0.32.11"
  },
  "devDependencies": {
    "@testing-library/jest-dom": "5.14.1",
    "@testing-library/react": "12.1.2",
    "babel-jest": "27.3.1",
    "identity-obj-proxy": "3.0.0",
    "jest": "27.3.1"
  }
}

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