本地安装的npm模块正常，从npmjs安装的在NextJS中报模块未找到错误？

我开发了一个npm模块，在本地通过文件夹路径安装（npm i <path to my package>）时，NextJS项目执行next build或npm run build完全正常；但从npm仓库安装（npm i localisr@dev）后，构建时会抛出模块找不到的错误。该模块在CRA React项目和NodeJS应用中运行都没问题，只有NextJS出现这个问题。

模块内的代码 #

LocalisrClient.js #

export class LocalisrClient {
    client;
    language = 'en';
    constructor(authorizationToken, projectToken) {
        this.client = new HttpClient(authorizationToken, projectToken);
    }
    // ...其他方法
}

index.js #

import { LocalisrClient } from './LocalisrClient';
export { LocalisrClient };

报错信息 #

unhandledRejection Error [ERR_MODULE_NOT_FOUND]: Cannot find module '<path to project>/node_modules/localisr/dist/mjs/LocalisrClient' imported from <path to project>/node_modules/localisr/dist/mjs/index.js

可能的解决思路 #

• 检查package.json的导出与文件配置
  确认模块的package.json中exports字段是否正确映射了ES模块路径，同时确保files字段包含dist目录，避免npm发布时遗漏文件：

  "exports": {
    ".": {
      "import": "./dist/mjs/index.js",
      "require": "./dist/cjs/index.js"
    }
  },
  "files": [
    "dist"
  ]
  

• 验证构建后的文件完整性
  本地执行构建命令后，检查dist/mjs目录下是否存在LocalisrClient.js。若构建脚本只打包了index.js却遗漏了依赖模块，会导致npm安装后找不到文件。

• 配置NextJS转译第三方模块
  在NextJS项目的next.config.js中添加transpilePackages，强制NextJS转译你的模块：

  /** @type {import('next').NextConfig} */
  const nextConfig = {
    transpilePackages: ['localisr'],
  }
  module.exports = nextConfig;
  

  NextJS默认不会转译node_modules中的ES模块，未转译的语法或路径规则可能引发解析错误。

• 补全导入路径的扩展名
  ES模块解析要求显式文件扩展名，修改index.js中的导入语句：

  import { LocalisrClient } from './LocalisrClient.js';
  

  本地安装时可能因软链接或本地解析规则忽略扩展名，但npm安装后的真实路径需要完整扩展名。

• 确认npm发布包的内容
  用npm pack生成本地发布包，解压后检查dist/mjs目录文件是否与本地构建一致，排查是否存在发布时漏传文件的情况。

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