NextJS模块及类型声明找不到，阻碍Turbo/Yarn构建发布求助

问题背景 #

NextJS应用本地运行正常，但IDE持续报错Cannot find module 'next/router'，同时next/link、next/image等所有NextJS相关模块及其类型声明都无法被解析。该错误直接导致turbo build和yarn build命令执行失败，无法发布到生产环境。已尝试过重启TS服务器、卸载重装升级NextJS、重新执行yarn install，以及调整tsconfig.json的moduleResolution为node或node16（node模式下本地包cachetesting无法导入，node16模式下NextJS导入错误依旧）。

解决方案 #

1. 修复TS配置的模块解析逻辑 #

NextJS 13+推荐使用bundler模块解析策略，替换node或node16。修改tsconfig.json的compilerOptions：

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "baseUrl": ".", // 确保baseUrl指向项目根目录
    // 保留其他原有配置...
  }
}

该配置既适配NextJS的模块解析，又能避免本地包导入问题。

2. 强制修复NextJS类型依赖 #

虽然NextJS自带类型声明，但依赖树混乱可能导致类型文件丢失。执行命令强制安装并修复类型：

yarn add -D next@latest --force

安装完成后检查node_modules/next/types目录是否存在，确保类型文件完整。

3. 彻底清理缓存 #

缓存堆积是这类问题的常见诱因，执行以下命令完全清理各类缓存：

# 删除NextJS构建缓存
rm -rf .next
# 清理Yarn全局缓存
yarn cache clean
# 删除Turbo构建缓存
rm -rf .turbo
# 重新安装依赖
yarn install

完成后重启IDE的TS服务器（VSCode可通过Ctrl+Shift+P调出命令面板，选择TypeScript: Restart TS Server）。

4. 检查Monorepo工作区配置（若使用Turbo） #

如果是Turbo Monorepo结构：

• 确认package.json中的workspaces配置包含了当前应用目录，避免依赖安装到错误路径
• 检查turbo.json的pipeline配置，确保构建任务的依赖顺序正确，不会在NextJS模块未就绪时执行构建

5. 排查依赖版本冲突 #

执行命令查看核心依赖的版本一致性：

yarn list next react react-dom

确保next、react、react-dom的版本互相兼容（例如NextJS 14需要React 18.2+）。若存在版本不一致，可通过resolutions字段强制统一版本：

{
  "resolutions": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

添加后重新执行yarn install。

6. 移除错误的路径映射 #

检查tsconfig.json的paths配置，确保没有自定义映射覆盖next/*模块，例如类似以下的错误配置需要删除：

{
  "paths": {
    "next/*": ["./src/next/*"] // 这会导致NextJS模块被错误解析
  }
}

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