---
name: easy-env
description: 开发环境体检 CLI：检测环境变量、工具安装与来源、PATH 规范，输出机器可读 JSON 报告；支持把工具的路径根写入用户级环境变量（可回滚）。
---

# easy-env

本地工具，不联网。GUI（`easy_env.exe`）能做的，CLI（`easy-env`）全部覆盖，两者共用同一份报告契约与同一份规则文件。

## 安装

```bash
# 开发期
cd src-tauri && cargo build --release   # 产物 target/release/easy-env(.exe)
# 发布包随安装器分发（CLI 与 GUI 同包）
# macOS: ./build-mac.sh 出 dmg + .app（CLI 用 cargo 单独编，见 docs/MACOS-BUILD.md）
```

macOS/Linux 上 CLI 读的是**登录 shell 的环境**（`$SHELL -ilc env`），不是启动它的那个进程的环境；
自定义路径写 `~/.zshrc`（Linux 为 `~/.profile`）的受管块，写前有快照，可回滚。

## 命令清单

| 命令 | 说明 |
| --- | --- |
| `easy-env check [--json] [--only env\|tool\|package\|path]` | 跑体检；退出码 0 = 无 fail，2 = 有 fail |
| `easy-env list [--json]` | 列出规则目标与当前值 |
| `easy-env config <target>` | 查看目标当前值与期望值 |
| `easy-env config <target> --set <path> [--dry-run] [--yes]` | 自定义路径：默认只预览，`--yes` 才写用户级变量 |
| `easy-env snapshots [--json]` | 最近的自定义路径快照 |
| `easy-env rollback <snapshot-id>` | 回滚一次写入 |
| `easy-env version / help` | 版本 / 用法 |

`target` 形态：`env:<变量名>`（如 `env:VOLTA_HOME`）或 `tool:<工具名>`（如 `tool:node`）。

## 典型调用示例

```bash
# CI/agent 消费：只看 JSON 与退出码
easy-env check --json > report.json; echo $?

# 只查路径类规则
easy-env check --only path

# 把 Node 的数据根改到 D 盘（先预览）
easy-env config tool:node --set "D:/dev/volta"

# 确认写入（等价 GUI 的确认弹窗），随后可回滚
easy-env config tool:node --set "D:/dev/volta" --yes
easy-env snapshots
easy-env rollback <snapshot-id>
```

## 报告契约（稳定，只增不改义）

```json
{
  "schema": 1,
  "generatedAt": "2026-10-28T14:30:39+08:00",
  "platform": "windows",
  "profile": { "id": "company", "name": "...", "version": "2026-10-28" },
  "summary": { "ok": 31, "warn": 1, "fail": 0, "skipped": 1 },
  "items": [
    {
      "id": "tool:node", "kind": "tool", "title": "Node.js",
      "status": "ok|warn|fail|skipped",
      "expected": ">= 24.13.0", "actual": "24.22.1",
      "code": "tool_ok", "detail": "path=C:\\Program Files\\Volta\\node.exe",
      "fix": "...", "pathEnv": "VOLTA_HOME"
    }
  ]
}
```

`code` 是稳定机器键（UI 用它做双语文案），`detail` 只放值不写句子。