---
title: "配置"
description: "在 evlog.config.ts 中一次配置 evlog。这里介绍所有选项，以及框架选项如何覆盖它。"
canonical_url: "https://evlog.zhcndoc.com/reference/configuration"
---
# 配置

> 在 evlog.config.ts 中一次配置 evlog。这里介绍所有选项，以及框架选项如何覆盖它。

evlog 从应用根目录的 `evlog.config.ts` 读取选项。同一个文件同时驱动服务端和 [CLI](https://evlog.zhcndoc.com/cli/config)。

## 配置文件

```typescript [evlog.config.ts]
import { defineEvlog } from 'evlog'
import { createAxiomDrain } from 'evlog/axiom'

export default defineEvlog({
  service: 'my-api',
  sampling: { rates: { info: 10 }, keep: [{ status: 400 }] },
  drain: createAxiomDrain(),
})
```

`npx evlog init` 会为你写入这个文件。

evlog 会从应用目录开始向上查找 `evlog.config.ts`、`.mts`、`.js` 或 `.mjs`，直到工作区根目录。离应用最近的文件优先，因此单仓库根目录的一个文件可以覆盖所有没有单独配置的应用。

## 加载配置

Nuxt、Nitro 和 TanStack Start 会自动加载该文件。其他框架需要导入它：

```typescript [src/index.ts]
import { initLogger, toLoggerConfig, toMiddlewareOptions } from 'evlog'
import { evlog } from 'evlog/hono'
import config from '../evlog.config'

initLogger(toLoggerConfig(config))
app.use(evlog(toMiddlewareOptions(config)))
```

`toLoggerConfig` 传递日志器选项，`toMiddlewareOptions` 传递请求选项。每个[框架页面](https://evlog.zhcndoc.com/integrate/frameworks/overview)都展示准确的代码行。

## 优先级

配置文件先应用，然后由你传给框架的选项覆盖它。

在 Nuxt 和 Nitro 中，覆盖项会按键与配置文件合并。文件中的 `drain`、`enrich` 和 `keep` 永远不会被覆盖：它们会与 `evlog:*` hook 一起运行，因此事件会到达两边。在其他框架中，和配置文件一起传入的字段（例如 `evlog({ ...toMiddlewareOptions(config), exclude: ['/health'] })`）会替换对应字段，而不是合并。

## 选项

<table>
<thead>
  <tr>
    <th>
      选项
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      默认值
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        service
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        SERVICE_NAME
      </code>
      
       或 <code>
        'app'
      </code>
    </td>
    
    <td>
      每个事件上的服务名称
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        environment
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        NODE_ENV
      </code>
      
       或 <code>
        'development'
      </code>
    </td>
    
    <td>
      环境名称
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        enabled
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      为 <code>
        false
      </code>
      
       时所有调用都变为空操作
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pretty
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      开发环境中为 <code>
        true
      </code>
    </td>
    
    <td>
      输出树形格式而非 JSON
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        silent
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      不输出到控制台，但事件仍会到达 drain
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        stringify
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      关闭 <code>
        pretty
      </code>
      
       时输出 JSON 字符串
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        minLevel
      </code>
    </td>
    
    <td>
      <code>
        LogLevel
      </code>
    </td>
    
    <td>
      <code>
        'debug'
      </code>
    </td>
    
    <td>
      <code>
        log
      </code>
      
       API 的最低级别。请求事件使用 <code>
        sampling
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sampling
      </code>
    </td>
    
    <td>
      <code>
        SamplingConfig
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      头部速率和尾部 <code>
        keep
      </code>
      
       规则。参见<a href="https://evlog.zhcndoc.com/learn/sampling">
        采样
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        redact
      </code>
    </td>
    
    <td>
      <code>
        boolean | RedactConfig
      </code>
    </td>
    
    <td>
      生产环境中为 <code>
        true
      </code>
    </td>
    
    <td>
      参见<a href="https://evlog.zhcndoc.com/learn/redaction">
        脱敏
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        drain
      </code>
    </td>
    
    <td>
      <code>
        (ctx) => void
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      事件的去向。参见<a href="https://evlog.zhcndoc.com/integrate/adapters/overview">
        适配器
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        plugins
      </code>
    </td>
    
    <td>
      <code>
        EvlogPlugin[]
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      参见<a href="https://evlog.zhcndoc.com/extend/plugins">
        插件
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        include
      </code>
      
       / <code>
        exclude
      </code>
    </td>
    
    <td>
      <code>
        string[]
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      要记录或跳过的路由 glob
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        routes
      </code>
    </td>
    
    <td>
      <code>
        Record<string, { service }>
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      按路由设置服务名称
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        enrich
      </code>
    </td>
    
    <td>
      <code>
        (ctx) => void
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      在 drain 前添加字段
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        keep
      </code>
    </td>
    
    <td>
      <code>
        (ctx) => void
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      自定义尾部采样
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dev
      </code>
    </td>
    
    <td>
      <code>
        'evlog' | 'nitro' | 'both' | object
      </code>
    </td>
    
    <td>
      <code>
        'evlog'
      </code>
    </td>
    
    <td>
      开发终端输出。参见<a href="https://evlog.zhcndoc.com/learn/structured-errors#development-terminal-output">
        结构化错误
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        extends
      </code>
    </td>
    
    <td>
      <code>
        EvlogConfig
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      基于共享预设构建。参见<a href="https://evlog.zhcndoc.com/cli/config#share-settings-with-extends">
        共享设置
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        map
      </code>
      
      , <code>
        logs
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      -
    </td>
    
    <td>
      仅供 CLI 使用。参见 <a href="https://evlog.zhcndoc.com/cli/config">
        <code>
          evlog config
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

Nuxt 还会在 `nuxt.config.ts` 中读取 `console` 和 `transport`。参见 [Nuxt](https://evlog.zhcndoc.com/integrate/frameworks/nuxt)。

## 脚本中的内联配置

对于小型独立脚本，直接在启动日志器的文件中向 `initLogger` 传入选项即可：

```typescript [scripts/sync.ts]
import { initLogger } from 'evlog'

initLogger({ env: { service: 'sync-job' } })
```

---

- [采样](https://evlog.zhcndoc.com/learn/sampling)
- [Drain 适配器](https://evlog.zhcndoc.com/integrate/adapters/overview)


## Sitemap

See the full [sitemap](https://evlog.zhcndoc.com/sitemap.md) for all pages.