插件钩子中的 this.environment

::: tip 反馈
欢迎在 Environment API 反馈讨论 中给我们提出建议

在 Vite 6 之前，仅存在两个环境：client 和 ssr。resolveId、load 和 transform 钩子中单一的 options.ssr 参数允许插件作者在处理模块时区分这两种环境。而在 Vite 6 中，一个 Vite 应用可以根据需要定义任意数量的命名环境。为此，我们在插件上下文中引入了 this.environment，以便在钩子中与当前模块所属的环境进行交互。

影响范围：Vite 插件作者 warning 未来弃用计划
this.environment 在 v6.0 中引入。options.ssr 的弃用计划定于未来的某个主版本。届时，我们将开始建议插件迁移到新的 API。要检测你的使用情况，请在 Vite 配置中设置 future.removePluginHookSsrArgument 为 "warn"。
:::

动机

this.environment 不仅让插件钩子实现能够知晓当前环境的名称，还能访问环境配置选项、模块图信息以及转换管线（environment.config、environment.moduleGraph、environment.transformRequest()）。在上下文中获取环境实例，使插件作者无需依赖整个开发服务器（通常在启动时通过 configureServer 钩子缓存）。

迁移指南

对于现有插件，若需快速迁移，在 resolveId、load 和 transform 钩子中将 options.ssr 参数替换为 this.environment.config.consumer === 'server'：

import { Plugin } from 'vite'

export function myPlugin(): Plugin {
  return {
    name: 'my-plugin',
    resolveId(id, importer, options) {
      // 旧写法
      const isSSR = options.ssr
      // 新写法
      const isSSR = this.environment.config.consumer === 'server'

      if (isSSR) {
        // SSR 专属逻辑
      } else {
        // 客户端专属逻辑
      }
    },
  }
}

为了实现更稳健的长期方案，插件钩子应针对多个环境使用细粒度的环境选项来处理，而不是依赖环境名称。