---
title: "Vite 插件"
description: "为任何基于 Vite 的框架提供构建时优化。自动初始化、调试剥离、源代码位置注入，以及可选的自动导入。"
canonical_url: "https://evlog.zhcndoc.com/reference/vite-plugin"
---
# Vite 插件
> 为任何基于 Vite 的框架提供构建时优化。自动初始化、调试剥离、源代码位置注入，以及可选的自动导入。
`evlog/vite` 插件为任何基于 Vite 的项目添加了构建时的 DX 特性。它适用于 SvelteKit、Hono、Express、Fastify、Elysia，以及任何使用 Vite 作为构建工具的框架。
**Nuxt 用户**：这些功能已通过 `strip` 和 `sourceLocation` 选项集成到 `evlog/nuxt` 模块中。你无需单独安装 Vite 插件。
## 快速开始
### 1. 安装
```bash [pnpm]
pnpm add evlog
```
```bash [bun]
bun add evlog
```
```bash [yarn]
yarn add evlog
```
```bash [npm]
npm install evlog
```
### 2. 添加到 `vite.config.ts`
```typescript [vite.config.ts]
import { defineConfig } from 'vite'
import evlog from 'evlog/vite'
export default defineConfig({
plugins: [
evlog({
service: 'my-api',
environment: 'production',
}),
],
})
```
就这样。插件会自动：
- 在编译时初始化日志记录器（无需调用 `initLogger()`）
- 从生产构建中剥离 `log.debug()` 调用
## 特性
该插件会在构建时转换源代码：从输出中删除 `log.debug()` 调用，在对象形式的日志调用中注入 `__source: 'file:line'`，并通过 Vite 的 `define` 钩子接入 `initLogger()`，因此你无需再手动调用它。
### 自动初始化
该插件通过 Vite 的 `define` 钩子在编译时注入日志记录器配置。`service`、`environment`、`pretty`、`silent`、`enabled` 和 `sampling` 选项会在构建时被序列化并注入，因此 `log`、`createLogger()` 和 `createRequestLogger()` 无需调用 `initLogger()` 即可立即工作。
### 调试剥离
默认情况下，所有 `log.debug()` 调用都会从生产构建中移除。这是一个编译时的转换，调用会被完全消除，而不仅仅是静音。
```typescript [vite.config.ts]
evlog({
service: 'my-api',
// 默认：在生产构建中剥离调试日志
// strip: ['debug'],
// 在生产环境中剥离调试和 info：
// strip: ['debug', 'info'],
// 禁用剥离：
// strip: [],
})
```
剥离仅在 `vite build` 时激活（不会在 `vite dev` 时）。
### 源代码位置注入
启用后，插件会在对象形式的日志调用中注入 `__source: 'file:line'`，让你准确知道每条日志来自哪个文件和行号。
```typescript [vite.config.ts]
evlog({
service: 'my-api',
sourceLocation: true, // 始终注入
// sourceLocation: 'dev', // 仅在开发环境注入
})
```
### 自动导入（可选）
自动检测并导入 evlog 符号（`log`、`createEvlogError`、`parseError` 等），无需手动写入导入语句。默认禁用。
```typescript [vite.config.ts]
evlog({
service: 'my-api',
autoImports: true,
})
```
启用后，插件会：
1. 扫描代码中的 evlog 符号
2. 自动添加正确的 `import` 语句
3. 为 TypeScript 生成 `.d.ts` 文件
自动导入的错误构造函数是 `createEvlogError`，而不是 `createError`。这可以避免与框架内置的 `createError`（如 Nuxt、Nitro、h3）发生冲突。独立的 `createError` 仍可通过显式导入从 `evlog` 获取。
### 客户端注入
当提供 `client` 选项时，插件会将 `