发布为npm包的UI库使用Next.js特性时遇模块找不到问题

问题描述 #

我开发了一个已发布的UI组件库，想在组件里用next/image处理图片，但消费该库的应用启动时触发以下错误：

error - Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'path\to\node_modules\next\image' imported from path\to\node_modules\@mynpmpackage\public-widgets\index.js Did you mean to import next/image.js? 
at new NodeError (node:internal/errors:371:5) 
at finalizeResolution (node:internal/modules/esm/resolve:418:11) 
at moduleResolve (node:internal/modules/esm/resolve:983:10) 
at defaultResolve (node:internal/modules/esm/resolve:1080:11) 
at ESMLoader.resolve (node:internal/modules/esm/loader:530:30) 
at ESMLoader.getModuleJob (node:internal/modules/esm/loader:251:18) 
at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:79:40) 
at link (node:internal/modules/esm/module_job:78:36) { code: 'ERR_MODULE_NOT_FOUND', page: '/' }

我的npm包已经正确声明了peerDependency："next": ">13.1.0"，消费应用也安装了符合要求的next@13.1.6版本。我想确认这种在组件库中使用Next.js特性的方案是否可行，以及使用useRouter、Image这类特性时需要注意哪些事项。目前其他第三方包都能正常工作，唯独next/image、next/router这类Next.js子模块无法被正确识别。

问题原因与解决步骤 #

1. 修正导入路径的扩展名 #

Next.js的ESM模块解析要求严格匹配文件扩展名，错误提示中的"Did you mean to import next/image.js?"已经给出明确指向。修改组件库中的导入语句：

// 原错误写法
import Image from 'next/image'
import { useRouter } from 'next/router'

// 修正后写法
import Image from 'next/image.js'
import { useRouter } from 'next/router.js'

2. 确保组件库模块格式与Next.js兼容 #

• 若使用TypeScript开发，检查tsconfig.json配置，建议设置：

  {
    "module": "ESNext",
    "moduleResolution": "NodeNext"
  }
  

• 打包工具（如Rollup、Vite）需配置为输出ESM格式，且将next标记为外部依赖（不打包进组件库代码，保留peerDependency的依赖关系）。

3. 验证peerDependency配置正确性 #

确保package.json中的peerDependency无语法错误，且版本范围覆盖消费应用的Next.js版本：

{
  "peerDependencies": {
    "next": ">13.1.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

注意：不要将next添加到dependencies或devDependencies中，避免组件库打包时内置Next.js代码。

在组件库中使用Next.js特性的注意事项 #

• 明确组件库的适用场景：如果组件库需要支持非Next.js应用（如Create React App），不要直接依赖Next.js专属API，建议封装适配层，或提供独立的Next.js专属组件入口。
• 关注版本兼容性：next/image、useRouter属于Next.js公开API，但不同版本可能存在变更，peerDependency的版本范围要精准，避免跨版本API不兼容。
• 本地测试要充分：搭建Next.js测试项目验证组件导入和运行逻辑，避免发布后才发现路径解析或依赖问题。
• 兼容ESM与CJS双格式：若组件库需同时支持两种模块格式，通过打包工具生成双格式输出，确保不同环境下的导入路径都能正确解析。

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