Next.js升级至v15.2.4后Yarn Monorepo兄弟工作区修改不触发热重载

问题背景 #

我有一个包含多个包（如ui-components、logging等）的Monorepo，这些包被导入到同级的app包中，app是基于React和Redux的Next.js应用。将Next.js从v14.2.21升级到v15.2.4后，热重载功能出现异常：修改ui-components包的代码后，运行yarn workspace @my-repo/app的app应用不再触发热重载。

相关配置信息 #

根目录package.json（部分内容） #

{
    "workspaces": [
        "packages/*"
    ],
    "packageManager": "yarn@4.5.3",
    "resolutions": {
        "@types/react": "^19",
        "next": "^15.2.4",
        "request": "^2.88.2",
        "webpack": "^5.94.0",
        "webpack-dev-middleware": "^5.3.4",
        "serve-static": "^1.16.0"
    }
}

packages/app/package.json（部分内容） #

{
    "dependencies": {
        "@my-repo/ui-components": "workspace:packages/ui-components",
        "@next/bundle-analyzer": "^15.2.1",
        "@reduxjs/toolkit": "^2.6.0",
        "next": "^15.2.4",
        "react": "^19.0.0",
        "react-dom": "^19.0.0",
        "react-redux": "^9.2.0",
        "ts-node": "^10.9.2",
        "typescript": "^5.8.2"
    }
}

next.config.js配置 #

transpilePackages: ['@my-repo/ui-components']

排查思路与解决办法 #

1. 完善transpilePackages配置 #

Next.js 15对内部包的转译监听逻辑可能有调整，确保所有需要热重载的内部包都被加入配置数组，比如同时用到logging包时：

transpilePackages: ['@my-repo/ui-components', '@my-repo/logging']

也可以尝试用绝对路径替代包名，避免包名解析问题：

const path = require('path');
module.exports = {
  transpilePackages: [path.resolve(__dirname, '../ui-components')]
};

2. 修复Yarn工作区链接状态 #

运行yarn workspaces list确认@my-repo/ui-components已正确关联到app包。如果链接异常，执行yarn install或yarn workspace @my-repo/app add @my-repo/ui-components@workspace重新建立链接。

3. 显式配置Webpack文件监听规则 #

在next.config.js中添加watchOptions，强制Webpack监听内部包的文件变更：

const path = require('path');
module.exports = {
  transpilePackages: ['@my-repo/ui-components'],
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.watchOptions = {
        poll: 1000,
        aggregateTimeout: 300,
        ignored: /node_modules/,
        include: [path.resolve(__dirname, '../ui-components/src')]
      };
    }
    return config;
  }
};

4. 清理缓存并重启服务器 #

Next.js 15的缓存机制可能留存旧代码，执行以下操作：

• 删除项目根目录的.next文件夹和node_modules/.cache目录
• 启动开发服务器时添加--no-cache参数：yarn workspace @my-repo/app dev --no-cache

5. 检查内部包的配置合理性 #

确认ui-components的package.json中：

• main/module字段指向正确的入口文件
• 未设置sideEffects: false（该配置可能导致Webpack跳过热重载逻辑）
• TypeScript项目的tsconfig.json中declaration设为true，types字段路径正确

6. 排除Redux兼容性干扰 #

暂时移除app中Redux相关的配置和代码，测试热重载是否恢复。如果恢复，说明Redux中间件或配置与Next.js 15存在兼容性问题，需要调整react-redux或@reduxjs/toolkit的使用方式。

7. 查看开发服务器详细日志 #

启动服务器时添加--verbose参数：yarn workspace @my-repo/app dev --verbose，查看日志中是否有文件监听被忽略、转译失败等提示信息，定位具体问题。

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