第九章：Vite API 参考手册

第九章：Vite API 参考手册

9.1 核心 API

createServer

创建 Vite 开发服务器

import { createServer } from 'vite'

const server = await createServer({
  configFile: false,
  root: __dirname,
  server: { port: 3000 }
})

await server.listen()
console.log('服务器启动在', server.config.server.port)

build

以编程方式构建

import { build } from 'vite'

await build({
  root: './',
  build: {
    outDir: 'dist',
    rollupOptions: {
      input: 'index.html'
    }
  }
})

resolveConfig

解析配置

import { resolveConfig } from 'vite'

const config = await resolveConfig({}, 'build', 'production')
console.log(config.base)

9.2 插件 API

Plugin 接口

interface Plugin {
  name: string
  
  // 钩子
  buildStart?: (options: InputOptions) => void
  resolveId?: (source: string, importer: string | undefined) => string | null
  load?: (id: string) => string | null
  transform?: (code: string, id: string) => TransformResult
  buildEnd?: () => void
  generateBundle?: (options: OutputOptions, bundle: { [fileName: string]: OutputAsset | OutputChunk }) => void
  
  // Vite 特有
  config?: (config: UserConfig, env: { command: string, mode: string }) => UserConfig | null
  configResolved?: (config: ResolvedConfig) => void
  configureServer?: (server: ViteDevServer) => void
  transformIndexHtml?: (html: string, ctx: TransformIndexHtmlContext) => string | HtmlTagDescriptor[]
  handleHotUpdate?: (ctx: HmrContext) => ModuleNode[] | void
}

TransformResult

interface TransformResult {
  code: string
  map?: SourceMap | null
  deps?: string[]
}

9.3 配置 API

defineConfig

import { defineConfig } from 'vite'

export default defineConfig({
  // 配置项
})

// 异步配置
export default defineConfig(async ({ command, mode }) => {
  const plugins = await import('./plugins')
  return {
    plugins: [plugins.default()]
  }
})

loadConfigFromFile

import { loadConfigFromFile } from 'vite'

const { config, deps } = await loadConfigFromFile({
  command: 'serve',
  mode: 'development'
}, './vite.config.js')

9.4 开发服务器 API

ViteDevServer 接口

interface ViteDevServer {
  config: ResolvedConfig
  middlewares: Connect.Server
  
  listen(port?: number, isRestart?: boolean): Promise<ViteDevServer>
  close(): Promise<void>
  
  transformRequest(url: string, options?: TransformOptions): Promise<ModuleNode | null>
  
  ws: WebSocketServer
  
  moduleGraph: ModuleGraph
  pluginContainer: PluginContainer
  
  hotUpdate(module: ModuleNode): Promise<void>
}

使用示例

const server = await createServer()

// 添加自定义中间件
server.middlewares.use((req, res, next) => {
  console.log(`${req.method} ${req.url}`)
  next()
})

// 监听 WebSocket 消息
server.ws.on('connection', (socket) => {
  console.log('客户端连接')
})

await server.listen()

9.5 模块图 API

ModuleNode

interface ModuleNode {
  id: string
  file: string
  url: string
  
  importers: Set<ModuleNode>
  importedModules: Set<ModuleNode>
  
  transformResult: TransformResult | null
  ssrTransformResult: TransformResult | null
  
  lastHMRTimestamp: number
  
  acceptHmrDeps: Set<ModuleNode>
  acceptedHmrDeps: Set<ModuleNode>
}

访问模块图

const modules = server.moduleGraph.getModules()
for (const module of modules) {
  console.log(module.id, module.importedModules.size)
}

9.6 插件容器 API

interface PluginContainer {
  resolveId(id: string, importer?: string): Promise<string | null>
  load(id: string): Promise<LoadResult | null>
  transform(code: string, id: string): Promise<TransformResult | null>
  
  buildStart(options: InputOptions): Promise<void>
  buildEnd(): Promise<void>
}

9.7 工具函数

normalizePath

路径规范化

import { normalizePath } from 'vite'

const path = normalizePath('src\\components\\Button.vue')
// 'src/components/Button.vue'

createLogger

创建日志器

import { createLogger } from 'vite'

const logger = createLogger('info')
logger.info('信息消息')
logger.warn('警告消息')
logger.error('错误消息')

isCSSRequest

检查是否为 CSS 请求

import { isCSSRequest } from 'vite'

if (isCSSRequest(id)) {
  console.log('这是 CSS 文件')
}

9.8 环境变量 API

loadEnv

加载环境变量

import { loadEnv } from 'vite'

const env = loadEnv('development', process.cwd(), 'VITE')
console.log(env.VITE_API_URL)

envPrefix

envPrefix: 'VITE_'  // 默认，只有 VITE_ 开头的变量暴露

9.9 预构建 API

optimizeDeps

import { optimizeDeps } from 'vite'

await optimizeDeps({
  config: {
    root: process.cwd(),
    optimizeDeps: {
      include: ['vue', 'vue-router']
    }
  }
})

9.10 热更新 API

HmrContext

interface HmrContext {
  file: string
  timestamp: number
  modules: ModuleNode[]
  read: () => string | Promise<string>
  server: ViteDevServer
}

自定义 HMR

handleHotUpdate({ file, server, modules }) {
  if (file.endsWith('.custom')) {
    server.ws.send({
      type: 'custom',
      event: 'custom-update',
      data: { file }
    })
    return []
  }
  return modules
}

9.11 构建 API

build 选项

interface BuildOptions {
  target?: 'modules' | string[]
  outDir?: string
  assetsDir?: string
  assetsInlineLimit?: number
  cssCodeSplit?: boolean
  sourcemap?: boolean | 'inline' | 'hidden'
  rollupOptions?: RollupOptions
  minify?: boolean | 'esbuild' | 'terser'
  terserOptions?: TerserOptions
  write?: boolean
  emptyOutDir?: boolean
  manifest?: boolean | string
  lib?: LibraryOptions
  ssr?: boolean | string
  ssrManifest?: boolean | string
}

9.12 服务器选项

ServerOptions

interface ServerOptions {
  host?: string | boolean
  port?: number
  strictPort?: boolean
  https?: boolean | HttpsOptions
  open?: boolean | string
  proxy?: Record<string, string | ProxyOptions>
  cors?: CorsOptions | boolean
  headers?: Record<string, string>
  fs?: {
    strict?: boolean
    allow?: string[]
  }
  hmr?: HmrOptions | boolean
  watch?: WatchOptions
  middlewareMode?: boolean
}

9.13 预构建选项

DepOptimizationOptions

interface DepOptimizationOptions {
  include?: string[]
  exclude?: string[]
  entries?: string[]
  esbuildOptions?: EsbuildOptions
  force?: boolean
}

9.14 完整类型定义

所有类型定义都可以从 Vite 包中导入：

import type { 
  UserConfig, 
  ConfigEnv, 
  Plugin, 
  ViteDevServer,
  BuildOptions,
  ServerOptions,
  DepOptimizationOptions
} from 'vite'

---

本章小结

API 参考手册提供了 Vite 的核心 API 文档：

• 编程方式使用 Vite
• 插件开发接口
• 开发服务器控制
• 模块图操作
• 工具函数

这些 API 可用于构建工具、插件和自动化脚本。