preserveSymlinks 在 Vite 中怎么配置
在 vite 项目中，preservesymlinks 选项需要在 vite.config.js 的顶层配置对象中直接设置为 true。该配置会改变模块解析策略，使 node.js 遵循符号链接的真实路径而非目标路径进行查找，从而解决因软链导致的模块重复或找不到的问题。
启用后模块解析路径有何变化
开启 preserveSymlinks 后，Node.js 不再将符号链接视为其指向的目标文件，而是将其视为独立的实体。这意味着当项目通过软链引入依赖时，解析器会保留软链的路径结构，而不是跳转到实际代码所在的物理目录。这种机制对于使用 yarn workspaces 或 pnpm 等包管理工具的项目尤为重要，因为它们大量使用软链来管理依赖。
// vite.config.js
import { defineConfig } from 'vite';
export default defineConfig({
// 核心配置项
preserveSymlinks: true,
});
上述代码展示了最基础的配置方式。在大多数现代构建场景中，只需添加这一行即可生效。如果项目使用的是 ESM 格式的配置文件，确保导出的是包含此属性的对象。配置生效后，再次运行 dev 或 build 命令，Vite 底层的 rollup 和 node_modules 解析逻辑将依据新的路径规则执行。
什么情况下必须使用该配置
通常在使用 yarn workspaces 或 pnpm 的多包管理结构中，或者在开发环境中需要严格区分本地源码与安装依赖时，必须启用此配置。如果不启用，Node.js 可能会因为路径折叠而认为同一个模块被加载了两次，导致类型检查错误或运行时异常。例如，当你在本地开发一个库并通过软链链接到主应用时，若不开启此选项，主应用可能无法正确识别库中的内部引用。
// 验证配置的简单测试
import fs from 'fs';
import path from 'path';
// 假设存在一个软链
const linkPath = './node_modules/my-link';
if (fs.existsSync(linkPath)) {
console.log('Link exists');
}
在实际操作中，可以通过检查 node_modules 中的软链状态来辅助判断是否需要开启此配置。如果项目结构复杂且出现难以追踪的模块未找到错误，尝试开启 preserveSymlinks 是排查此类问题的有效手段。需要注意的是，该配置主要影响开发服务器和构建过程中的模块解析，对最终打包输出的代码结构没有直接影响，但能确保开发环境的一致性。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
