自定义npm包在Next.js运行时无法找到模块的问题求助

针对你遇到的编译阶段TypeScript识别正常，但运行时提示Module not found: Can't resolve '@my-org/ncw-client'的问题，以下是具体排查方向和解决方案：

1. 统一打包工具，消除产物冲突 #

你当前同时使用microbundle和tsc两个打包工具，二者输出的文件会互相覆盖，导致dist目录结构混乱，模块解析失败：

• microbundle默认生成ES模块（index.m.js）、CommonJS模块（index.js）、UMD模块（index.umd.js）
• tsc根据你的tsconfig.json会生成CommonJS格式的index.js，直接覆盖microbundle的输出

解决方案：
选择单一打包工具，比如保留microbundle并修改构建脚本：

// package.json
"scripts": {
  "clean": "rm -rf dist",
  "build": "npm run clean && microbundle --tsconfig tsconfig.json --no-sourcemap --format es,cjs,umd"
}

执行npm run build后，检查dist目录是否生成了对应格式的文件，避免文件覆盖。

2. 修正package.json的exports字段配置 #

你的exports字段中指定的./dist/index.modern.js可能不存在（microbundle默认不生成该文件名），导致Next.js解析模块时找不到入口文件。调整exports字段，匹配microbundle的实际输出：

// package.json
"exports": {
  "import": "./dist/index.m.js", // ES模块入口
  "require": "./dist/index.js", // CommonJS模块入口
  "default": "./dist/index.m.js" // 默认入口
},
"main": "./dist/index.js",
"module": "./dist/index.m.js",
"types": "./dist/index.d.ts"

确保每个字段指向的文件在dist目录中真实存在。

3. 解决npm link的软链接解析问题 #

npm link创建的软链接可能导致Next.js模块解析器无法正确识别包路径，替代方案：
在测试项目中使用本地文件路径安装包：

npm install ../path_to_ncw_client

这种方式会将包硬拷贝到测试项目的node_modules，避免软链接带来的解析异常。

4. 配置Next.js转译自研包 #

Next.js默认不会转译node_modules中的第三方包，如果你的自研包使用了未转译的ES语法，会导致运行时解析失败。在测试项目的next.config.js中添加transpilePackages配置：

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@my-org/ncw-client'],
};

module.exports = nextConfig;

该配置会让Next.js转译指定的包，确保语法兼容性。

5. 修正导入方式不匹配问题 #

你的包中是默认导出WallabyClient：

// src/index.ts
export default class WallabyClient { /* ... */ }

但测试项目中使用的是命名导入：

import { WallabyClient } from '@my-org/ncw-client';

这会导致模块导入后WallabyClient为undefined，需修正导入方式：

// 方式1：使用默认导入
import WallabyClient from '@my-org/ncw-client';

// 方式2：修改包的导出为命名导出
export class WallabyClient { /* ... */ }

6. 验证打包产物的有效性 #

手动检查dist目录下的文件：

• 确认index.js（CommonJS）和index.m.js（ES模块）语法正确，无编译错误
• 确认index.d.ts正确导出了WallabyClient类型，确保TypeScript类型提示正常

内容的提问来源于stack exchange，提问作者Tarek Al Beb