Vercel部署失败：无法解析@开头依赖模块问题求助

问题概述 #

在React.js/Next.js环境中开发自定义TypeScript库，本地运行正常，但部署到Vercel时出现模块找不到错误，涉及@mantine/core、@material-ui/icons/ArrowRightAlt、@mantine/hooks三个依赖。

错误信息 #

./helper/react-gutenberg/dist/blocks/common/audio.js
    13:06:35.878    Module not found: Can't resolve '@mantine/core' in '/vercel/path0/helper/react-gutenberg/dist/blocks/common'
    13:06:35.879    
    13:06:35.879    Import trace for requested module:
    13:06:35.880    ./helper/react-gutenberg/dist/blocks/common/audio.js
    13:06:35.880    ./helper/react-gutenberg/dist/blocks/common/index.js
    13:06:35.881    ./helper/react-gutenberg/dist/blocks/index.js
    13:06:35.881    ./helper/react-gutenberg/dist/index.js
    13:06:35.881    ./helper/react-gutenberg/index.js
    13:06:35.881    
    13:06:35.881    ./helper/react-gutenberg/dist/blocks/common/audio.js
    13:06:35.881    Module not found: Can't resolve '@material-ui/icons/ArrowRightAlt' in '/vercel/path0/helper/react-gutenberg/dist/blocks/common'
    13:06:35.881    
    13:06:35.881    Import trace for requested module:
    13:06:35.881    ./helper/react-gutenberg/dist/blocks/common/audio.js
    13:06:35.881    ./helper/react-gutenberg/dist/blocks/common/index.js
    13:06:35.881    ./helper/react-gutenberg/dist/blocks/index.js
    13:06:35.881    ./helper/react-gutenberg/dist/index.js
    13:06:35.881    ./helper/react-gutenberg/index.js
    13:06:35.881    
    13:06:35.882    ./helper/react-gutenberg/dist/blocks/common/audio.js
    13:06:35.882    Module not found: Can't resolve '@mantine/hooks' in '/vercel/path0/helper/react-gutenberg/dist/blocks/common'

原因分析 #

问题并非@符号本身导致，而是以下两类配置问题：

1. 依赖声明错误：自定义库的package.json中未正确声明这些依赖（如误放入devDependencies，或未声明为peerDependencies），导致Vercel部署时未安装对应依赖。
2. TypeScript编译配置问题：tsconfig.json的模块解析规则设置错误，导致编译后的JS文件无法正确识别npm包的导入路径。

解决方案 #

1. 修正库的package.json依赖配置 #

根据依赖的使用场景调整声明：

• 如果这些依赖是库运行时必须的核心依赖，将其放入dependencies；
• 如果这些依赖是宿主项目（你的Next.js项目）应该提供的UI框架类依赖，将其放入peerDependencies（同时在devDependencies中安装一份供本地开发）。

示例配置：

{
  "name": "react-gutenberg",
  "version": "1.0.0",
  "dependencies": {},
  "peerDependencies": {
    "@mantine/core": "^6.0.0",
    "@mantine/hooks": "^6.0.0",
    "@material-ui/icons": "^4.11.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "@mantine/core": "^6.0.0",
    "@mantine/hooks": "^6.0.0",
    "@material-ui/icons": "^4.11.0",
    "typescript": "^5.0.0"
    // 其他开发依赖
  }
}

2. 调整TypeScript编译配置（tsconfig.json） #

确保tsconfig.json的模块解析规则符合Node.js规范：

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "node",
    "target": "ES2020",
    "outDir": "./dist",
    "declaration": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

• moduleResolution: "node"：启用Node.js的模块解析逻辑，正确识别@开头的npm包；
• esModuleInterop: true：确保CommonJS和ES模块之间的兼容性。

3. 验证Vercel部署流程 #

• 确保主项目的package.json中正确引用自定义库，例如使用本地路径引用：

  "dependencies": {
    "react-gutenberg": "file:./helper/react-gutenberg"
  }
  

• 如果使用pnpm，在项目根目录的.npmrc中添加auto-install-peers=true，确保自动安装peer依赖；
• 检查Vercel的构建命令，确保先编译自定义库再构建主项目，例如在package.json的scripts中添加：

  "scripts": {
    "prebuild": "cd helper/react-gutenberg && npm run build",
    "build": "next build"
  }
  

4. 检查编译后的文件 #

确认dist/blocks/common/audio.js中的导入语句未被错误修改，例如应保持import { ... } from '@mantine/core'，而非被转换为错误的相对路径。

内容的提问来源于stack exchange，提问作者Rudy Prévaud