Next.js/React项目更新后本地链接的TypeScript库出现Module not found错误

看起来你在升级Next.js和React到新版本后，本地通过file:路径链接的TypeScript库突然找不到了——这种情况在框架跨大版本更新时特别常见，尤其是Next.js 15和React 19这类迭代较大的版本，模块解析规则往往会有不少调整。我整理了几个针对性的排查和解决步骤，你可以一步步试：

1. 补全本地库的package.json配置 #

新版本的模块解析逻辑会更严格，你的test-project-lib很可能缺少关键配置字段，导致Next.js无法正确识别它的入口文件和类型定义。你需要在test-project-lib的根目录创建一个package.json（如果还没有的话），至少包含这些核心字段：

{
  "name": "test-project-lib",
  "version": "0.1.0",
  "main": "index.ts",
  "types": "index.ts",
  "files": [
    "index.ts",
    "src/**/*"
  ]
}

如果你的库需要先编译为JS（比如用tsc构建），那main要指向编译后的输出文件（比如dist/index.js），types对应dist/index.d.ts，同时把dist目录加入files数组。

2. 配置Next.js转译本地库 #

Next.js 15对未转译的第三方库处理更严格，而本地symlink的库本质上属于你的项目源码，需要被框架转译才能正常识别。你需要在项目根目录的next.config.js中添加transpilePackages配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['test-project-lib'],
  // 保留你原有的其他配置
}

export default nextConfig

这一步是解决本地库解析问题的核心，很多人升级后忽略了这个配置，导致框架跳过了对本地库的转译。

3. 彻底清理缓存并重新安装依赖 #

升级框架后，旧的依赖缓存和构建缓存很可能残留了冲突的配置，导致奇怪的模块解析问题。你可以按以下步骤彻底清理：

• 删除项目的node_modules目录：rm -rf node_modules（Windows系统用rmdir /s /q node_modules）
• 删除根目录的package-lock.json文件
• 删除Next.js的构建缓存目录：rm -rf .next
• 重新安装依赖：npm install
• 重启开发服务器：先试试不带--turbopack的命令npm run dev，排除Turbopack的兼容性问题

4. 排查Turbopack的兼容性问题 #

你当前的dev脚本用了--turbopack参数，但Turbopack在处理本地symlink模块时，规则和传统Webpack有差异，尤其是Next.js 15的Turbopack还处于优化阶段。如果前面的步骤都没用，可以先暂时关闭Turbopack：

"scripts": {
  "dev": "next dev",
  // 保留其他脚本不变
}

如果关闭Turbopack后问题解决，那大概率是Turbopack对本地file:依赖的支持存在bug，可以等Next.js后续补丁修复，或者暂时用Webpack开发模式。

5. 验证Symlink的有效性 #

虽然你提到symlink已经存在，但还是可以手动验证一下：

• 进入项目的node_modules目录，找到test-project-lib，检查它的实际指向路径是否正确
• 可以手动删除这个symlink，然后重新执行npm install让它自动重建
• 也可以尝试改用npm link的方式：先在test-project-lib目录执行npm link，再在test-project-app目录执行npm link test-project-lib，这种方式有时候比file:路径更稳定

如果以上步骤都试过还是无法解决，可以检查一下项目的tsconfig.json，确保compilerOptions中的moduleResolution设置为bundler（Next.js 15推荐的模块解析模式），且baseUrl和paths配置没有和本地库的导入路径冲突。

内容来源于stack exchange