Vanilla Extract Vite 插件 v5.0.0 重大更新解析

Vanilla Extract 是一个流行的 CSS-in-JS 解决方案，它允许开发者使用 TypeScript 编写样式，并通过编译生成静态 CSS 文件。其 Vite 插件 @vanilla-extract/vite-plugin 近日发布了 5.0.0 版本，带来了一些重要的变更和改进。

主要变更内容

插件命名规范化

新版本将插件名称从 "vanilla-extract" 变更为更符合 Vite 插件命名惯例的 "vite-plugin-vanilla-extract"。这一变更使得插件更容易被识别为 Vite 生态的一部分，同时也遵循了 Vite 官方的插件命名规范。

Vite 版本支持调整

5.0.0 版本更新了 Vite 的 peer 依赖范围，现在要求至少使用 Vite 5.0.0 或 6.0.0 版本。这意味着 Vite 4 及以下版本将不再受支持。这一变更是为了确保插件能够充分利用 Vite 最新版本的特性和性能优化。

插件转发机制重构

这是一个重要的架构变更。在之前的版本中，除了少数已知不兼容的插件外，所有用户配置的 Vite 插件都会被自动转发到 Vanilla Extract 编译器。这种做法在实践中带来了不少问题，因为许多框架特定的插件或处理构建输出的插件实际上并不适用于 Vanilla Extract 的编译过程，有时甚至会导致问题。

新版本默认只转发 vite-tsconfig-paths 插件，这是一个已知兼容且常用的插件。对于需要转发其他插件的特殊情况，开发者现在可以通过 unstable_pluginFilter 选项进行自定义配置：

vanillaExtractPlugin({
  unstable_pluginFilter: ({ name, mode }) => 
    plugin.name === 'vite-plugin-foo'
})

需要注意的是，当使用自定义插件过滤器时，vite-tsconfig-paths 插件也不再默认转发，需要显式包含在过滤条件中。这个 API 目前标记为不稳定，意味着在未来版本中可能会有调整。

升级建议

对于现有项目，升级到 5.0.0 版本需要注意以下几点：

1. 确保项目使用的 Vite 版本至少为 5.0.0
2. 检查是否有依赖特定插件转发的场景，必要时配置 unstable_pluginFilter
3. 更新构建配置中引用插件的方式，使用新的命名规范

这些变更总体上提高了插件的稳定性和可预测性，减少了因插件转发导致的各种边缘情况问题。对于大多数项目来说，升级应该是相对平滑的，特别是那些没有使用复杂插件配置的项目。