如何在Vite项目中正确安装基于file:的本地依赖？

问题 #

在CRA项目中，通过npm install file:../foo安装上级目录的foo依赖后，无论是import foo/dist/foo.js还是import { ... } from 'foo'都能正常导入代码。

但在标准Vite项目中执行相同安装命令后，启动开发模式npm run dev会出现两种错误：

• 使用import foo/dist/foo.js时，报错：[plugin:vite:import-analysis] Failed to resolve import "foo/dist/foo.js" from "src/App.jsx". Does the file exist?
• 使用import { Bar } from 'foo'时，报错：The requested module '/@fs/Users/areynolds/Developer/Github/foo/dist/foo.js' does not provide an export named 'Bar' (at App.jsx:11:3)

另外发现node_modules/foo的符号链接路径错误（实际为../../foo，正确应为../foo），但手动修复后问题依旧。需要调整Vite的package.json或配置文件，让本地file:依赖正常工作。

解决方案 #

1. 修正本地依赖foo的package.json配置 #

先检查foo项目的package.json，确保入口相关字段配置准确：

• main：指向CommonJS格式的入口文件（比如dist/foo.js）
• module：指向ES模块格式的入口文件（比如dist/foo.esm.js）
• 推荐使用exports字段明确不同环境的入口规则，示例：

{
  "exports": {
    ".": {
      "import": "./dist/foo.esm.js",
      "require": "./dist/foo.js"
    },
    "./dist/foo.js": "./dist/foo.js"
  }
}

该配置能让Vite精准解析不同方式的导入请求。

2. 配置Vite的预构建排除规则 #

在Vite项目根目录的vite.config.js（或.ts）中，添加optimizeDeps.exclude配置，避免Vite预构建本地依赖时出现路径解析异常：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  optimizeDeps: {
    exclude: ['foo']
  }
})

此配置会让Vite直接读取本地依赖的原始文件，跳过预构建环节可能引发的路径问题。

3. 添加Vite路径别名（可选兜底方案） #

如果上述配置仍未解决问题，可以通过别名直接映射到本地foo目录，绕开node_modules符号链接的潜在问题：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      'foo': path.resolve(__dirname, '../foo')
    }
  }
})

4. 重新安装依赖并清理缓存 #

完成配置后，执行以下命令确保依赖和缓存状态正确：

rm -rf node_modules
rm package-lock.json # 若用yarn/pnpm则删除对应lock文件
npm install
npm run dev

注意：不要手动修改node_modules内的符号链接，npm会根据项目路径自动生成正确链接，手动修改可能引发其他异常。

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