Vite plugin configureServer 怎样读取开发服务器

Vite 插件通过 configureServer(server) 的参数读取开发服务器实例。这个参数是 ViteDevServer，可以访问解析后的配置、开发中间件等能力；它不是 vite.config 中的 server 配置片段。需要在别的钩子里使用时，可把实例保存在插件工厂的闭包中，并处理生产构建期间没有实例的情况。

官方地址：https://vite.dev/

假设本地插件需要增加一个只返回开发模式信息的诊断地址。把逻辑放在配置解析钩子里会遇到一个问题：那里拿到的是配置，没有可直接注册 HTTP 中间件的开发服务器对象。迁移时应先分清“读配置”和“用服务器”，再移动相应逻辑，无需重新创建第二个 Vite 服务器。以下示例不依赖某条版本发布事件，也不虚构升级前后的实测结果。

在 configureServer 参数里读取实例

将下面内容放入一个已有 Vite 项目的 vite.config.ts。如果项目已有插件，把这里的 localServerInfo() 合并进原 plugins 数组，不要覆盖其他配置。

import { defineConfig, type Plugin } from 'vite'

function localServerInfo(): Plugin {
  return {
    name: 'local-server-info',
    configureServer(server) {
      // 此处读取的是解析后的配置，不是原始配置草稿
      const mode = server.config.mode

      server.middlewares.use((req, res, next) => {
        // 只处理一个固定诊断路径，其他请求继续交给后续中间件
        const pathname = (req.url ?? '').split('?')[0]
        if (pathname !== '/__local_plugin_state__') {
          next()
          return
        }

        // 示例只提供读请求，不返回根目录、环境变量或凭据
        if (req.method !== 'GET') {
          res.statusCode = 405
          res.setHeader('Allow', 'GET')
          res.end()
          return
        }

        res.setHeader('Content-Type', 'application/json; charset=utf-8')
        res.end(JSON.stringify({ plugin: 'local-server-info', mode }))
      })
    },
  }
}

export default defineConfig({
  // 工厂调用产生插件实例，每次创建使用自己的闭包
  plugins: [localServerInfo()],
})

官方插件文档规定了 configureServer 的服务器参数。示例中 config 提供 mode，middlewares 注册请求处理器。对不匹配的路径调用 next()，匹配并结束响应以后就不再调用它，避免把同一个响应继续交给其他处理器。

把配置读取和服务器依赖分开迁移

如果原来把配置对象命名成 server，容易误以为它能调用 middlewares.use。迁移时先把这个变量改为 resolvedConfig，再仅把依赖实例的部分放进 configureServer。这样命名与对象职责一致，构建期逻辑也不会无意依赖开发服务器。

以下是独立的闭包访问写法，展示其他钩子如何保护开发态引用。它不需要和前面的完整配置同时复制；可按插件实际需求合并。

import type { Plugin, ViteDevServer } from 'vite'

export function rememberDevServer(): Plugin {
  // 每个插件工厂实例保存自己的引用，避免使用模块级共享变量
  let devServer: ViteDevServer | undefined

  return {
    name: 'remember-dev-server',
    configureServer(server) {
      devServer = server
    },
    transform(_source, id) {
      // 构建期未调用 configureServer，不能直接使用未赋值的引用
      if (!devServer) return null
      if (id.endsWith('/src/local-diagnostic.ts')) {
        // 只输出按需诊断信息；示例不修改模块源码
        devServer.config.logger.debug('本地诊断模块已进入转换钩子')
      }
      return null
    },
  }
}

configResolved、ResolvedConfig、configureServer、实例闭包、开发态钩子与生产构建的关系如图。这里把闭包理解为引用存放处即可；它不是服务器重新创建的入口，也不应该被拿来跨不同开发服务器共享可变状态。

拿到实例不代表 HTTP 已经监听

按照ViteDevServer 接口文档，httpServer 在中间件模式下可以为 null；resolvedUrls 在没有监听端口或中间件模式下也可能为 null。因此不能在 configureServer 里直接假设 server.resolvedUrls.local[0] 存在，也不能用非空断言掩盖 httpServer 的模式差异。

如果只安装中间件，就不必读取实际端口，也不必自行调用 server.listen()。如果确实需要访问监听后的地址，应按当前运行模式安排读取时机并处理 null。配置中的期望端口与最终可用地址也不应混为一谈。本文的诊断响应只返回 mode，从而不依赖这些尚未就绪的值。

返回函数用于后置注册，不是关闭清理

configureServer 在内部中间件安装之前调用。在钩子体内直接 use，注册的是默认靠前的自定义处理器；若要在内部中间件安装后注册，可以返回一个函数：

// 插件对象中的钩子片段：仅演示后置注册方式
configureServer(server) {
  return () => {
    server.middlewares.use((req, _res, next) => {
      // 只观察尚未被前面处理器结束的请求，并继续传递
      if (req.method === 'GET') {
        server.config.logger.debug('后置观察中间件收到 GET 请求')
      }
      next()
    })
  }
}

这是一项注册位置选择，不代表所有请求都能到达后置处理器：如果前面的中间件已经结束响应，就不会继续传下去。上面的片段应放在插件对象中，不能作为独立文件顶层语句粘贴。返回函数也不是销毁回调，不要把关闭监听器或释放资源的逻辑误写在这里。

接入后分别看开发、构建和预览

在已有项目使用平常的开发启动命令后，访问开发服务器同源的 /__local_plugin_state__。按第一个示例，GET 应得到 JSON，其中 plugin 固定为 local-server-info，mode 来自当前解析配置；它不是一个用来披露完整配置的接口。这是读者的预期判断方法，不是本文已执行的运行记录。

然后分别考虑三个范围：开发态诊断地址由 configureServer 提供；生产构建不会调用它；预览阶段若也需要独立能力，应使用 configurePreviewServer，而不是假定已经保存了开发实例。新旧插件写法迁移时，保留这个范围对照，比只确认 TypeScript 不报错更有帮助。

只想读 root 或 mode，还要保存服务器吗？

通常不需要。只依赖最终配置的逻辑放在 configResolved 即可，避免额外持有开发服务器引用。

为什么 build 时 devServer 是 undefined？

configureServer 不参与生产构建，这正是闭包引用需要判断的原因。不要为了消除 undefined 而在构建钩子里启动开发服务器。

诊断地址可以当生产业务 API 吗？

这个示例只属于开发服务器扩展。正式业务接口应由对应服务提供，不能依赖 configureServer 随产物部署后继续存在。