使用package.json本地路径依赖时Vite构建报错问题求助

问题背景 #

我的项目package.json中配置了本地路径依赖：

{
  "dependencies": {
    "~shared": "file:../shared",
  }
}

其中../shared是多个前端项目共享的React组件、工具函数和样式目录。使用Vite打包时，出现以下解析错误：

[vite]: Rollup failed to resolve import "~shared/components/button" from "/web/path-to-a-file.tsx".
This is most likely unintended because it can break your application at runtime

尝试过用Vite的resolve.alias配置，但会丢失本地依赖的独立解析能力——原本shared目录下的文件会从自身node_modules导入React，而项目自身文件从项目的node_modules导入，使用alias后这个逻辑被破坏，引发更多问题。我不想引入yarn workspaces、lerna这类工具，目前备选方案是将shared目录软链接到每个项目中。

可行解决方案 #

方案1：调整Vite配置，保留解析链 #

不用粗暴替换alias，而是通过配置让Vite正确识别本地依赖的解析规则。修改vite.config.js：

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

export default defineConfig({
  plugins: [react()],
  resolve: {
    // 保留软链接的原始路径，避免解析混乱
    preserveSymlinks: true,
    alias: [
      {
        find: /^~shared\/(.*)/,
        replacement: '../shared/$1'
      }
    ]
  }
});

preserveSymlinks: true会让Vite保留依赖的原始路径，确保shared目录下的文件优先从自身node_modules解析依赖，而项目文件仍使用自身的node_modules。正则式的alias仅做路径映射，不会破坏原生依赖解析逻辑。

方案2：规范shared目录的package.json #

给../shared目录添加合法的package.json，并配置exports字段明确模块入口：

// ../shared/package.json
{
  "name": "~shared",
  "version": "1.0.0",
  "exports": {
    ".": "./index.js",
    "./components/*": "./components/*",
    "./utils/*": "./utils/*",
    "./styles/*": "./styles/*"
  }
}

配置后，Vite会通过npm的本地依赖规则自动解析~shared/components/button这类导入，无需额外alias配置，同时完整保留各自的node_modules依赖链。

方案3：优化软链接方案 #

直接将../shared软链接到项目的node_modules/~shared目录：

# 在当前项目根目录执行
ln -s ../../shared node_modules/~shared

这样npm和Vite会将其视为普通node_modules依赖，自动处理模块解析，同时保留shared自身的依赖链。注意必须确保shared目录有合法的package.json，否则npm无法识别该依赖。

方案对比 #

• 方案1：无需修改shared目录，配置简单快速，适合临时或小项目场景
• 方案2：符合npm模块规范，长期维护更清晰，适合多项目共享的场景
• 方案3：最贴近原生npm依赖体验，但需要手动维护软链接（可编写shell脚本批量执行）

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