Vite 6 中 npm 包导入解析的变更与解决方案

问题背景

在 Vite 6 版本中，用户在使用某些 npm 包时可能会遇到导入解析错误。具体表现为当尝试导入类似 @brillout/json-serializer/stringify 这样的子路径时，系统会报错提示"没有已知的条件"。

技术分析

这个问题的根源在于 Vite 6 对 resolve.conditions 默认值做出的重大变更。在 Vite 6 之前，系统会自动包含一些默认的解析条件（conditions），但在 Vite 6 中，这些默认条件被移除了。

resolve.conditions 是 Vite 用来解析 package.json 中 exports 字段的配置项。当导入一个 npm 包的子路径时，Vite 会根据这些条件来匹配 package.json 中定义的导出规则。

解决方案

要解决这个问题，开发者需要显式地配置 resolve.conditions。具体来说，可以在 vite.config.js 中添加以下配置：

export default defineConfig({
  resolve: {
    conditions: ['import', 'module', 'browser', 'default']
  }
})

这些条件分别对应：

• import：用于 ESM 导入
• module：模块化导入
• browser：浏览器环境
• default：默认回退条件

最佳实践

1. 明确指定条件：在 Vite 6 中，应该始终明确指定需要的解析条件，而不是依赖默认值。

2. 了解包的导出结构：检查你使用的 npm 包的 package.json 中的 exports 字段，了解它支持哪些条件。

3. 环境区分：根据你的运行环境（浏览器/Node.js）选择合适的条件。

4. 版本兼容：如果你的项目需要同时支持 Vite 5 和 6，可以考虑使用条件配置来保持兼容性。

总结

Vite 6 的这一变更虽然带来了短期的适配成本，但从长远来看，它使模块解析行为更加明确和可控。开发者通过显式配置解析条件，可以更精确地控制模块解析行为，避免潜在的隐式行为带来的不确定性。

对于从 Vite 5 升级到 6 的项目，检查并更新 resolve.conditions 配置应该是升级过程中的重要步骤之一。