JavaScript API

Vite 的 JavaScript API 具有完整的类型定义，建议使用 TypeScript 或在 VS Code 中启用 JS 类型检查以利用智能提示和验证。

createServer

类型签名

async function createServer(inlineConfig?: InlineConfig): Promise<ViteDevServer>

示例用法

import { fileURLToPath } from 'node:url'
import { createServer } from 'vite'

const __dirname = fileURLToPath(new URL('.', import.meta.url))

const server = await createServer({
  // any valid user config options, plus `mode` and `configFile`
  configFile: false,
  root: __dirname,
  server: {
    port: 1337,
  },
})
await server.listen()

server.printUrls()
server.bindCLIShortcuts({ print: true })

注意

在同一个 Node.js 进程中使用 createServer 和 build 时，这两个函数都依赖于 process.env.NODE_ENV 来正常工作，这也取决于 mode 配置选项。为了防止冲突行为，将 process.env.NODE_ENV 或这两个 API 的 mode 设置为 development。否则，您可以生成一个子进程来分别运行这些 API。

注意

当使用 中间件模式 结合 WebSocket 的代理配置 时，应在 middlewareMode 中提供父 http 服务器以正确绑定代理。

示例

import http from 'http'
import { createServer } from 'vite'

const parentServer = http.createServer() // or express, koa, etc.

const vite = await createServer({
  server: {
    // Enable middleware mode
    middlewareMode: {
      // Provide the parent http server for proxy WebSocket
      server: parentServer,
    },
    proxy: {
      '/ws': {
        target: 'ws://localhost:3000',
        // Proxying WebSocket
        ws: true,
      },
    },
  },
})

parentServer.use(vite.middlewares)

InlineConfig

InlineConfig 接口扩展了 UserConfig，并添加了额外的属性

• configFile: 指定要使用的配置文件。如果未设置，Vite 将尝试从项目根目录自动解析一个配置文件。设置为 false 以禁用自动解析。
• envFile: 设置为 false 以禁用 .env 文件。

ResolvedConfig

ResolvedConfig 接口具有与 UserConfig 相同的所有属性，但大多数属性已解析且不为 undefined。它还包含一些实用程序，例如

• config.assetsInclude: 用于检查 id 是否被视为资源的函数。
• config.logger: Vite 的内部日志记录器对象。

ViteDevServer

interface ViteDevServer {
  /**
   * The resolved Vite config object.
   */
  config: ResolvedConfig
  /**
   * A connect app instance
   * - Can be used to attach custom middlewares to the dev server.
   * - Can also be used as the handler function of a custom http server
   *   or as a middleware in any connect-style Node.js frameworks.
   *
   * https://github.com/senchalabs/connect#use-middleware
   */
  middlewares: Connect.Server
  /**
   * Native Node http server instance.
   * Will be null in middleware mode.
   */
  httpServer: http.Server | null
  /**
   * Chokidar watcher instance. If `config.server.watch` is set to `null`,
   * returns a noop event emitter.
   * https://github.com/paulmillr/chokidar#api
   */
  watcher: FSWatcher
  /**
   * Web socket server with `send(payload)` method.
   */
  ws: WebSocketServer
  /**
   * Rollup plugin container that can run plugin hooks on a given file.
   */
  pluginContainer: PluginContainer
  /**
   * Module graph that tracks the import relationships, url to file mapping
   * and hmr state.
   */
  moduleGraph: ModuleGraph
  /**
   * The resolved urls Vite prints on the CLI. null in middleware mode or
   * before `server.listen` is called.
   */
  resolvedUrls: ResolvedServerUrls | null
  /**
   * Programmatically resolve, load and transform a URL and get the result
   * without going through the http request pipeline.
   */
  transformRequest(
    url: string,
    options?: TransformOptions,
  ): Promise<TransformResult | null>
  /**
   * Apply Vite built-in HTML transforms and any plugin HTML transforms.
   */
  transformIndexHtml(
    url: string,
    html: string,
    originalUrl?: string,
  ): Promise<string>
  /**
   * Load a given URL as an instantiated module for SSR.
   */
  ssrLoadModule(
    url: string,
    options?: { fixStacktrace?: boolean },
  ): Promise<Record<string, any>>
  /**
   * Fix ssr error stacktrace.
   */
  ssrFixStacktrace(e: Error): void
  /**
   * Triggers HMR for a module in the module graph. You can use the `server.moduleGraph`
   * API to retrieve the module to be reloaded. If `hmr` is false, this is a no-op.
   */
  reloadModule(module: ModuleNode): Promise<void>
  /**
   * Start the server.
   */
  listen(port?: number, isRestart?: boolean): Promise<ViteDevServer>
  /**
   * Restart the server.
   *
   * @param forceOptimize - force the optimizer to re-bundle, same as --force cli flag
   */
  restart(forceOptimize?: boolean): Promise<void>
  /**
   * Stop the server.
   */
  close(): Promise<void>
  /**
   * Bind CLI shortcuts
   */
  bindCLIShortcuts(options?: BindCLIShortcutsOptions<ViteDevServer>): void
  /**
   * Calling `await server.waitForRequestsIdle(id)` will wait until all static imports
   * are processed. If called from a load or transform plugin hook, the id needs to be
   * passed as a parameter to avoid deadlocks. Calling this function after the first
   * static imports section of the module graph has been processed will resolve immediately.
   * @experimental
   */
  waitForRequestsIdle: (ignoredId?: string) => Promise<void>
}

信息

waitForRequestsIdle 旨在用作一种应急措施，以改善无法按照 Vite 开发服务器的按需性质实现的功能的 DX。它可以在启动期间由 Tailwind 等工具使用，以延迟生成应用程序 CSS 类，直到应用程序代码被看到，从而避免样式更改的闪烁。当此函数在加载或转换钩子中使用，并且使用默认的 HTTP1 服务器时，六个 http 通道之一将被阻塞，直到服务器处理完所有静态导入。Vite 的依赖优化器目前使用此函数来避免在缺少依赖项时进行全页面重新加载，方法是延迟加载预打包的依赖项，直到从静态导入的源中收集到所有导入的依赖项。Vite 可能会在未来的主要版本中切换到不同的策略，默认情况下将 optimizeDeps.crawlUntilStaticImports 设置为 false，以避免在大型应用程序的冷启动期间出现性能下降。

build

类型签名

async function build(
  inlineConfig?: InlineConfig,
): Promise<RollupOutput | RollupOutput[]>

示例用法

import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { build } from 'vite'

const __dirname = fileURLToPath(new URL('.', import.meta.url))

await build({
  root: path.resolve(__dirname, './project'),
  base: '/foo/',
  build: {
    rollupOptions: {
      // ...
    },
  },
})

preview

类型签名

async function preview(inlineConfig?: InlineConfig): Promise<PreviewServer>

示例用法

import { preview } from 'vite'

const previewServer = await preview({
  // any valid user config options, plus `mode` and `configFile`
  preview: {
    port: 8080,
    open: true,
  },
})

previewServer.printUrls()
previewServer.bindCLIShortcuts({ print: true })

PreviewServer

interface PreviewServer {
  /**
   * The resolved vite config object
   */
  config: ResolvedConfig
  /**
   * A connect app instance.
   * - Can be used to attach custom middlewares to the preview server.
   * - Can also be used as the handler function of a custom http server
   *   or as a middleware in any connect-style Node.js frameworks
   *
   * https://github.com/senchalabs/connect#use-middleware
   */
  middlewares: Connect.Server
  /**
   * native Node http server instance
   */
  httpServer: http.Server
  /**
   * The resolved urls Vite prints on the CLI.
   * null before server is listening.
   */
  resolvedUrls: ResolvedServerUrls | null
  /**
   * Print server urls
   */
  printUrls(): void
  /**
   * Bind CLI shortcuts
   */
  bindCLIShortcuts(options?: BindCLIShortcutsOptions<PreviewServer>): void
}

resolveConfig

类型签名

async function resolveConfig(
  inlineConfig: InlineConfig,
  command: 'build' | 'serve',
  defaultMode = 'development',
  defaultNodeEnv = 'development',
  isPreview = false,
): Promise<ResolvedConfig>

command 值在开发和预览中为 serve，在构建中为 build。

mergeConfig

类型签名

function mergeConfig(
  defaults: Record<string, any>,
  overrides: Record<string, any>,
  isRoot = true,
): Record<string, any>

深度合并两个 Vite 配置。isRoot 表示正在合并的 Vite 配置中的级别。例如，如果您正在合并两个 build 选项，则将其设置为 false。

注意

mergeConfig 仅接受对象形式的配置。如果您有回调形式的配置，则应在将其传递给 mergeConfig 之前调用它。

您可以使用 defineConfig 帮助程序将回调形式的配置与另一个配置合并

export default defineConfig((configEnv) =>
  mergeConfig(configAsCallback(configEnv), configAsObject),
)

searchForWorkspaceRoot

类型签名

function searchForWorkspaceRoot(
  current: string,
  root = searchForPackageRoot(current),
): string

相关： server.fs.allow

如果满足以下条件，则搜索潜在工作区的根目录，否则将回退到 root

• package.json 中包含 workspaces 字段
• 包含以下文件之一
  • lerna.json
  • pnpm-workspace.yaml

loadEnv

类型签名

function loadEnv(
  mode: string,
  envDir: string,
  prefixes: string | string[] = 'VITE_',
): Record<string, string>

相关： .env 文件

加载 envDir 中的 .env 文件。默认情况下，仅加载以 VITE_ 为前缀的环境变量，除非更改 prefixes。

normalizePath

类型签名

function normalizePath(id: string): string

相关： 路径规范化

规范化路径以在 Vite 插件之间互操作。

transformWithEsbuild

类型签名

async function transformWithEsbuild(
  code: string,
  filename: string,
  options?: EsbuildTransformOptions,
  inMap?: object,
): Promise<ESBuildTransformResult>

使用 esbuild 转换 JavaScript 或 TypeScript。对于希望匹配 Vite 的内部 esbuild 转换的插件很有用。

loadConfigFromFile

类型签名

async function loadConfigFromFile(
  configEnv: ConfigEnv,
  configFile?: string,
  configRoot: string = process.cwd(),
  logLevel?: LogLevel,
  customLogger?: Logger,
): Promise<{
  path: string
  config: UserConfig
  dependencies: string[]
} | null>

使用 esbuild 手动加载 Vite 配置文件。