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://127.0.0.1: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`,
   * it will not watch any files and calling `add` or `unwatch` will have no effect.
   * https://github.com/paulmillr/chokidar/tree/3.6.0#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 (URL-encoded). Returns `null`
   * in middleware mode or if the server is not listening on any port.
   */
  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 开发服务器按需加载特性的功能的开发体验。启动时，像 Tailwind 这样的工具可以使用它来延迟生成应用程序 CSS 类，直到应用程序代码被看到，从而避免样式更改的闪烁。当此函数在加载或转换钩子中使用时，并且使用默认的 HTTP1 服务器，则六个 http 通道之一将被阻塞，直到服务器处理所有静态导入。Vite 的依赖项优化器目前使用此函数来避免在缺少依赖项时进行全页面重新加载，方法是延迟加载预打包的依赖项，直到从静态导入的源中收集所有导入的依赖项。Vite 可能会在未来的主要版本中切换到不同的策略，默认情况下将 optimizeDeps.crawlUntilStaticImports: false 设置为 false 以避免在大型应用程序的冷启动期间造成性能损失。

build

类型签名

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

使用示例

vite.config.js

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 (URL-encoded). Returns `null`
   * if the server is not listening on any port.
   */
  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 配置文件。

preprocessCSS

• 实验性： 提供反馈

类型签名

async function preprocessCSS(
  code: string,
  filename: string,
  config: ResolvedConfig,
): Promise<PreprocessCSSResult>

interface PreprocessCSSResult {
  code: string
  map?: SourceMapInput
  modules?: Record<string, string>
  deps?: Set<string>
}

将 .css、.scss、.sass、.less、.styl 和 .stylus 文件预处理为纯 CSS，以便可以在浏览器中使用或由其他工具解析。类似于内置 CSS 预处理器支持，如果使用，则必须安装相应的预处理器。

使用的预处理器根据 filename 扩展名推断。如果 filename 以 .module.{ext} 结尾，则将其推断为CSS 模块，并且返回的结果将包含一个 modules 对象，该对象将原始类名映射到转换后的类名。

请注意，预处理不会解析 url() 或 image-set() 中的 URL。