---
title: "evlog CLI"
description: "使用 evlog CLI 检查受支持源文件中的日志模式、诊断设置并控制遥测。包括标志和退出代码。"
canonical_url: "https://evlog.zhcndoc.com/cli/overview"
---
# evlog CLI

> 使用 evlog CLI 检查受支持源文件中的日志模式、诊断设置并控制遥测。包括标志和退出代码。

`evlog` 可执行文件随 `evlog` 软件包提供。它独立于你的应用运行：你可以在本地或 CI 中使用它来检查源代码、配置 evlog 并处理遥测。

从 [`evlog map`](https://evlog.zhcndoc.com/cli/map) 开始，检查 evlog 日志模式支持的入口点，并获取带有建议修复项的静态可观测性评分。除非传入 `--no-write`，否则它会写入 `evlog.map.json`。该评分描述的是已识别的源代码模式，而不是你的处理程序在生产环境中生成的日志。

[`evlog init`](https://evlog.zhcndoc.com/cli/init) 会将 evlog 配置添加到应用中。[`evlog logs`](https://evlog.zhcndoc.com/cli/logs) 会读取 fs drain 写入的事件：最新请求、失败请求、最慢请求，或完整的某个请求。[`evlog agents`](https://evlog.zhcndoc.com/cli/agents) 会为在仓库中工作的 AI agents 写入日志约定。[`evlog.config.ts`](https://evlog.zhcndoc.com/cli/config) 保存 `evlog map` 和 `evlog logs` 使用的设置，以及应用导入的采样和脱敏配置。

<warning icon="i-lucide-flask-conical">

**早期阶段。** `evlog map` 目前适配 Nuxt、Nitro、Next.js App Router、TanStack Start、Hono、Express 和 Fastify。每个适配器都会识别特定的入口点形态。在解读评分之前，请检查检测到的框架和入口点数量。规则可能会在不同版本之间发生变化，因此当你根据数量对 CI 进行门控时，请[固定版本](https://evlog.zhcndoc.com/cli/ci#pin-the-version)

</warning>

<code-group>

```bash [pnpm]
pnpm evlog map
```

```bash [bun]
bunx evlog map
```

```bash [npm]
npx evlog map
```

</code-group>

如果已安装 CLI，可执行文件会运行 [`@evlog/cli`](https://npmjs.com/package/@evlog/cli)；否则会使用启动它的包管理器获取 CLI。因此，`evlog` 不会向项目添加依赖，`npx evlog init` 也能在尚未安装任何内容的项目中运行。全局安装的 `@evlog/cli` 会交给项目安装的副本处理，因此项目始终运行自己固定的版本。为了固定版本并立即运行（这正是 CI 所需要的），请安装 CLI：

<code-group>

```bash [pnpm]
pnpm add -D @evlog/cli
```

```bash [bun]
bunx @evlog/cli map
```

```bash [npm]
npm install --save-dev @evlog/cli
```

</code-group>

<callout color="neutral" icon="i-lucide-info">

CLI 需要 Node 22 或更高版本。

</callout>

## 命令

<card-group>
<card color="neutral" icon="i-lucide-wand-sparkles" title="init" to="https://evlog.zhcndoc.com/cli/init">

安装 evlog，注册框架集成，并写入本地 drain。

</card>

<card color="neutral" icon="i-lucide-bot" title="agents" to="https://evlog.zhcndoc.com/cli/agents">

将 evlog 约定写入 AGENTS.md，并安装代理技能。

</card>

<card color="neutral" icon="i-lucide-radar" title="map" to="https://evlog.zhcndoc.com/cli/map">

评估每个入口点的广泛事件覆盖率，并标出最先需要修复的项。

</card>

<card color="neutral" icon="i-lucide-stethoscope" title="doctor" to="https://evlog.zhcndoc.com/cli/doctor">

检查 evlog 是否已安装、可解析，并在你预期的位置写入日志。

</card>

<card color="neutral" icon="i-lucide-settings-2" title="config" to="https://evlog.zhcndoc.com/cli/config">

Show the evlog.config that applies here and where each setting comes from.

</card>

<card color="neutral" icon="i-lucide-bar-chart-3" title="telemetry" to="https://evlog.zhcndoc.com/cli/telemetry">

显示、启用或禁用 CLI 自身的匿名使用遥测。

</card>
</card-group>

## 全局标志

每个命令都接受以下标志：

<table>
<thead>
  <tr>
    <th>
      标志
    </th>
    
    <th>
      作用
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      在标准输出上输出机器可读的 JSON，而不是报告
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --debug
      </code>
    </td>
    
    <td>
      打印本次运行的调试摘要，并将其作为宽事件发出
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --noHeader
      </code>
    </td>
    
    <td>
      跳过品牌化页眉
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cwd <dir>
      </code>
    </td>
    
    <td>
      针对其他目录运行，而不是当前目录
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --help
      </code>
    </td>
    
    <td>
      命令的用法说明
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --version
      </code>
    </td>
    
    <td>
      打印 CLI 版本并退出
    </td>
  </tr>
</tbody>
</table>

## 人类输出写入 stderr

你读到的报告会写入 **stderr**。stdout 保留给 `--json`，因此一次运行可以通过管道传给 `jq`，而不会让报告干扰输出：

```bash [Terminal]
evlog map --json | jq '.map.score'
```

不使用 `--json` 时，stdout 完全不会写入任何内容。当 stdout 不是 TTY 或设置了 `NO_COLOR` 时，颜色会被移除；报告会根据分配给它的宽度自行布局，因此可以设置 `COLUMNS` 以固定宽度进行渲染。

## 退出代码

<table>
<thead>
  <tr>
    <th>
      代码
    </th>
    
    <th>
      含义
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        0
      </code>
    </td>
    
    <td>
      命令已运行且没有任何失败
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        1
      </code>
    </td>
    
    <td>
      某项检查失败，或未达到 <code>
        --min-score
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        2
      </code>
    </td>
    
    <td>
      用法错误 — 未知标志或无效值
    </td>
  </tr>
</tbody>
</table>

<warning>

管道会将 `$?` 替换为其中 *最后一个* 命令的退出代码，因此 `evlog map --min-score 90 \| head` 总是看起来成功。当你对受限运行进行管道处理时，请使用 `set -o pipefail`。

</warning>

## 当检查出错时

每个判定都可以针对其相关代码被关闭，因此假阳性永远不会成为停止运行工具的理由：

```ts [server/api/health.get.ts]
// evlog-map-disable-next-line wide-event, context -- 存活探针，故意保持静默
export default defineEventHandler(() => ({ ok: true }))
```

检查结果会变为 `n/a`，并附带你的理由，不会扣分，也不会导致门控失败；报告还会统计项目禁用的检查数量，因此这个数字保持真实。[完整语法](https://evlog.zhcndoc.com/cli/rules#disabling-a-check)。

## 单一仓库

`init`、`map` 和 `doctor` 都会解析工作目录上方最近的 `package.json`，然后将该 package 视为项目。在 pnpm 或 npm 工作区中，从 `apps/web` 运行时会扫描 `apps/web`，而不是仓库根目录。

`evlog map` 一次只扫描一个应用。从没有可检测框架的裸工作区根目录运行它，会报错，而不是返回空报告：

```bash [Terminal]
cd apps/web && evlog map
# or
evlog map --cwd apps/web
```

## 调试一次运行

`--debug` 会打印命令执行的内容：经历的步骤、解析出的目录以及所有发现的问题，并将相同信息作为 evlog 宽事件发出：

```bash [Terminal]
evlog map --debug
```

```text [Output]
── 调试 ────────────────────────────────
command  map
env      development
cwd      /Users/you/apps/web
steps    resolveProject → detectFramework → resolveEvlog → scan → writeMapFile → done
──────────────────────────────────────────
完整事件 → --json --debug  （stderr）
```

添加 `--json` 可获取完整事件而不是摘要。`EVLOG_CLI_DEBUG=1` 的作用与该标志相同，这在你无法轻易修改的 CI 作业中很有用。

## 下一步

- [`evlog init`](https://evlog.zhcndoc.com/cli/init)：将 evlog 接入尚未安装它的应用
- [`evlog map`](https://evlog.zhcndoc.com/cli/map)：它会扫描什么，以及如何阅读报告
- [规则](https://evlog.zhcndoc.com/cli/rules)：每项检查、满足条件以及修复方法
- [评分](https://evlog.zhcndoc.com/cli/scoring)：数字的计算方式
- [CI](https://evlog.zhcndoc.com/cli/ci)：根据分数对 pull request 进行门控

---

- [evlog map](https://evlog.zhcndoc.com/cli/map)
- [规则](https://evlog.zhcndoc.com/cli/rules)


## Sitemap

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