构建时外部包突然抛出相对引用错误问题排查

核心原因 #

你配置的build.rollupOptions.external是告诉Vite/Rollup不将这些包打包进最终产物，运行时需要从外部环境获取对应模块。但浏览器原生ES模块系统只支持相对路径、绝对路径的模块引用，完全不识别@uniswap/v3-sdk这种npm包名，因此会抛出模块解析错误。

之前没有报错，大概率是因为：

• 当时运行环境存在这些包的全局变量（比如通过CDN脚本引入，全局暴露了对应变量）；
• 之前是在Node.js环境（比如SSR）运行，Node本身支持解析npm包名；
• 近期Vite/Rollup版本更新，external的默认处理逻辑发生了调整。

解决方案 #

1. 移除external配置（最直接）
   如果不需要将这两个包设为外部依赖，直接从external数组中删掉它们，让Vite正常打包即可解决问题。

2. 保留external但补充全局变量映射
   如果必须用external（比如要减小包体积、通过CDN加载），需要两步操作：

   • 在HTML中通过CDN引入这两个包的UMD/IIFE版本，确保全局环境存在对应的变量（比如@uniswap/v3-sdk通常全局变量为UniswapV3SDK，具体以CDN包的说明为准）；
   • 在Vite配置中添加output.globals映射，告诉Rollup打包时将npm包名替换为全局变量名：

     export default defineConfig({
       build: {
         rollupOptions: {
           external: ['@uniswap/v3-sdk', '@uniswap/sdk-core'],
           output: {
             globals: {
               '@uniswap/v3-sdk': 'UniswapV3SDK',
               '@uniswap/sdk-core': 'UniswapSDKCore'
             }
           }
         }
       }
     })
     

3. 排查环境变更
   检查近期是否有以下操作：移除了页面中的CDN引入脚本、从SSR部署切换为纯静态前端部署，这些变更都会导致外部依赖无法被浏览器识别。

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