Evidence 40.1.8 常用 CLI 命令详解
Evidence 40.1.8 CLI 七个子命令（dev/build/build:strict/sources/preview/env-debug/upgrade）参数、透传机制与退出码全量实测，含五条排障实录
Evidence 40.1.8 常用 CLI 命令详解
目标：逐命令讲清开源 CLI
@evidence-dev/evidence40.1.8 的全部子命令（dev / build / build:strict / sources / preview / env-debug / upgrade）的参数、透传机制与退出码。本文全部命令与回显均在 Ubuntu 26.04.1 LTS 服务器上以双数据源（DuckDB + PostgreSQL）实测项目逐条跑出，含 5 条排障实录（非 strict 挂起、-l短参数报错、hashed 数据路径 404、dev 崩溃、build:sources 废弃别名）。
一、环境信息
- 操作系统：Ubuntu 26.04.1 LTS（x86_64）
- Node.js / npm（实测）：
$ node --version
v24.22.1
$ npm --version
11.19.1
- CLI 包版本（实测，
--version不可用时以npm ls为准，见 9.2）：
$ npm ls @evidence-dev/evidence
my-evidence-project@0.0.1 /opt/evidence/my-report
└── @evidence-dev/evidence@40.1.8
- 实测项目
my-report：DuckDB 源needful_things（orders 表 10000 行）+ PostgreSQL 16 源web_analytics（127.0.0.1:5433，库analytics，daily_visits 表 122 行），页面pages/index.md、pages/visits.md。项目构建过程见《Evidence 40.1.8 安装与项目初始化指南》。 - 端口使用：dev 服务器 8137，preview 服务器 8138 / 8139。
二、工具概览
40.1.8 的 CLI 用 sade 框架实现，顶层帮助实测回显共 7 个子命令：
$ npx evidence --help
Usage
$ evidence <command> [options]
Available Commands
dev launch the local evidence development environment
env-debug Prints out Evidence variables from the environment and .env file
build build production outputs
build:strict build production outputs and fails on error
sources creates .parquet files from source queries
preview preview the production build
upgrade upgrade evidence to the latest version
For more info, run any command with the `--help` flag
$ evidence dev --help
$ evidence env-debug --help
Options
-v, --version Displays current version
-h, --help Displays this message
| 子命令 | 作用 | 底层实现（包内 cli.js 源码实测核对） |
|---|---|---|
sources | 执行全部 .sql 查询，产出 Parquet 快照 + manifest | 转交 @evidence-dev/sdk/legacy-compat 的 cli |
dev | Vite 开发服务器，改页面即时热更 | npx vite dev --port 3000 <透传参数>，工作目录 .evidence/template |
build | 产出纯静态站 ./build | npx vite build（SvelteKit + adapter-static） |
build:strict | 同 build，坏查询直接失败退出 | build + enableStrictMode() |
preview | 本地静态服务验证构建产物 | npx serve build <透传参数> |
env-debug | 打印 EVIDENCE_ 前缀环境变量 | 纯本地，读 .env 白名单 |
upgrade | 升级 evidence 依赖到最新版 | 转交 SDK cli |
两条关键机制（源码 cli.js 实测核对）：
- 透传：
dev/preview自身几乎没有业务参数，追加的参数原样拼给底层vite/serve；sources/upgrade则把process.argv整体转交 SDK。所以「某命令支持什么参数」取决于底层工具，--help列表只反映 evidence 自己声明的部分。 - 内存自抬：除
env-debug外各命令启动时若NODE_OPTIONS未含--max-old-space-size，自动追加--max-old-space-size=4096（increaseNodeMemoryLimit()），大项目构建 OOM 时改这个值即可，见《Evidence 40.1.8 配置参数详解》第七节。
三、前置条件
本文全部命令在项目根目录（含 package.json、sources/、pages/）执行，依赖已装好：
$ cd /opt/evidence/my-report
$ ls
README.md evidence.config.yaml package.json pages/ sources/ static/ node_modules/
PostgreSQL 源需可连（.env 凭据注入规则见《Evidence 40.1.8 配置参数详解》6.2）：
$ PGPASSWORD=q1w2e3r4 psql -h 127.0.0.1 -p 5433 -U postgres -d analytics -c "SELECT count(*) FROM daily_visits;"
count
-------
122
四、evidence sources：查询物化为 Parquet
sources 是数据面核心命令：连接各数据源执行 sources/<源>/*.sql，把结果写成 <查询>.parquet + manifest.json，dev/build 都消费这份快照。
4.1 --help：参数与示例全量回显
$ npx evidence sources --help
Description
creates .parquet files from source queries
Usage
$ evidence sources [options]
Aliases
$ evidence build:sources
Options
--changed only build sources whose queries have changed
--sources only build queries from the specified source directories
--queries only build the specified queries
--debug show debug output
--strict Fail when a source query fails
-h, --help Displays this message
Examples
$ evidence npx evidence sources --changed
$ evidence npx evidence sources --sources needful_things --queries orders,reviews
$ evidence npx evidence sources --queries needful_things.orders,needful_things.reviews
$ evidence npx evidence sources --sources needful_things,social_media
$ evidence npx evidence sources --strict
--sources 按源目录过滤、--queries 按查询过滤（<源>.<查询> 逗号分隔），--changed 按查询内容哈希走缓存——三者行为见 4.3~4.5 实测。
4.2 全量执行（基线）
$ npx evidence sources
- Loading plugins & sources
✔ Loading plugins & sources
-----
[Processing] needful_things
- Processing...
needful_things ⚠ No results returned.
- Processing...
orders ✔ Finished, wrote 10000 rows.
-----
[Processing] web_analytics
- Processing...
daily_visits ✔ Finished, wrote 122 rows.
-----
[INFO]: Evaluated sources, saving manifest
[INFO]: ✅ Done!
退出码 echo $? 为 0。needful_things ⚠ No results returned. 是源目录自身的占位行（目录不是查询），非错误。产物默认落 .evidence/template/static/data/（EVIDENCE_DATA_DIR 可改，见 4.6）。
4.3 --sources 按源过滤
$ npx evidence sources --sources needful_things
- Loading plugins & sources
✔ Loading plugins & sources
-----
[Processing] needful_things
- Processing...
needful_things ⚠ No results returned.
- Processing...
orders ✔ Finished, wrote 10000 rows.
-----
1 source were not run due to filters
[INFO]: Evaluated sources, saving manifest
[INFO]: ✅ Done!
被过滤掉的 web_analytics 源以 1 source were not run due to filters 明示，退出码 0。
4.4 --queries 按查询过滤
$ npx evidence sources --queries web_analytics.daily_visits
- Loading plugins & sources
✔ Loading plugins & sources
-----
[Processing] needful_things
- Processing...
needful_things ℹ Skipped
- Processing...
orders ℹ Skipped
-----
[Processing] web_analytics
- Processing...
daily_visits ✔ Finished, wrote 122 rows.
-----
[INFO]: Evaluated sources, saving manifest
[INFO]: ✅ Done!
未命中的查询标 ℹ Skipped。注意：manifest 会按本次执行范围重写，只跑部分查询后 dev/build 看到的快照以最新 manifest 为准，全量刷新再构建更稳妥。
4.5 --changed 增量（缓存）
$ npx evidence sources --changed
- Loading plugins & sources
✔ Loading plugins & sources
-----
[Processing] needful_things
- Processing...
needful_things ⚠ No results returned.
- Processing...
orders ℹ From Cache
-----
[Processing] web_analytics
- Processing...
daily_visits ℹ From Cache
-----
[INFO]: Evaluated sources, saving manifest
[INFO]: ✅ Done!
SQL 内容与上次一致时标 ℹ From Cache 不重查；改动任一 .sql 后重跑，该查询会重新执行。适合定时刷新任务只重跑变更查询。
4.6 EVIDENCE_DATA_DIR 改产物目录
$ EVIDENCE_DATA_DIR=./custom-data npx evidence sources --queries needful_things.orders
- Loading plugins & sources
✔ Loading plugins & sources
-----
[Processing] needful_things
- Processing...
needful_things ℹ Skipped
- Processing...
orders ✔ Finished, wrote 10000 rows.
-----
[Processing] web_analytics
- Processing...
daily_visits ℹ Skipped
-----
[INFO]: Evaluated sources, saving manifest
[INFO]: ✅ Done!
$ find custom-data -type f
custom-data/manifest.json
custom-data/needful_things/orders/orders.schema.json
custom-data/needful_things/orders/orders.parquet
环境变量前缀写法生效（.env 里同样支持，白名单规则见《Evidence 40.1.8 配置参数详解》6.1），产物目录整体平移到 ./custom-data/。
4.7 废弃别名 build:sources：警告后仍报 Unknown command
$ npx evidence build:sources
[!!] build:sources is deprecated and has been renamed to sources. Expect it to be removed in the future.
[!!] You can fix this in your package.json file ("evidence build:sources" becomes "evidence sources")
[ ! ] Unknown command `build:sources`
退出码 1。sade 层注册了 alias，但真正接参数的 SDK 解析器不认 build:sources——老项目 package.json 里残留的 evidence build:sources 脚本必须改成 evidence sources，否则 CI 直接失败。
4.8 --strict 与非 strict：坏查询的两种结局（排障实录）
造一条坏查询 sources/web_analytics/broken.sql：
select * from table_does_not_exist
非 strict：报错但继续，其余查询照常物化——但进程在 ✅ Done! 之后不退出（实测挂起 10 分钟以上，只能 Ctrl+C / kill）：
$ npx evidence sources
- Loading plugins & sources
✔ Loading plugins & sources
-----
[Processing] needful_things
- Processing...
orders ✔ Finished, wrote 10000 rows.
-----
[Processing] web_analytics
broken ✖ Error: Cannot read properties of undefined (reading 'rows')
- Processing...
daily_visits ✔ Finished, wrote 122 rows.
-----
[INFO]: Evaluated sources, saving manifest
[INFO]: ✅ Done!
（此处进程挂起不返回提示符，等待超时被外部终止）
strict：同样报错，但立即以退出码 1 终止：
$ npx evidence sources --strict
[INFO]: Enabling strict mode
- Loading plugins & sources
✔ Loading plugins & sources
-----
[Processing] needful_things
- Processing...
needful_things ⚠ No results returned.
- Processing...
orders ✔ Finished, wrote 10000 rows.
-----
[Processing] web_analytics
broken ✖ Error: Cannot read properties of undefined (reading 'rows')
[ ! ] Cannot read properties of undefined (reading 'rows')
web_analytics/broken failed to execute
$ echo $?
1
结论：CI/定时任务一律用 --strict——非 strict 模式下坏查询不仅不置失败，还会让进程挂起，把流水线卡到超时。删除 broken.sql 后重跑 npx evidence sources，回显恢复 daily_visits ✔ Finished, wrote 122 rows. + Done!，退出码 0。
五、evidence dev：开发服务器
5.1 --help 与参数透传
$ npx evidence dev --help
Description
launch the local evidence development environment
Usage
$ evidence dev [options]
Options
--debug Enables verbose console logs
-h, --help Displays this message
evidence 自己只声明 --debug；--port、--host、--open 等全部透传给 Vite（底层命令 npx vite dev --port 3000 <追加参数>，后出现的 --port 覆盖默认 3000）。
5.2 指定端口与对外暴露（实测）
$ npx evidence dev --port 8137 --host 0.0.0.0
VITE v5.4.21 ready in 2281 ms
➜ Local: http://localhost:8137/
➜ Network: http://192.168.1.200:8137/
➜ Network: http://10.89.59.1:8137/
➜ Network: http://10.89.60.1:8137/
页面验证（/visits/ 为双源混排报表页）：
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8137/
200
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8137/visits/
200
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8137/nope/
404
不存在的路径返回 404，且 dev 控制台同步打日志（实测）：
[ERROR]: Not Found | { url: 'http://localhost:8137/nope/', status: 404 }
dev 为前台进程，Ctrl+C 即停，无常驻服务。
5.3 缺 manifest 时的警告（不阻断）
数据快照未生成（没跑过 sources）时启动 dev，先打黄色警告、服务器照常起：
$ npx evidence dev --port 8137
[!] Unable to load source manifest
This likely means you have no source data, and need to generate it.
Running npm run sources will generate the needed data. See npm run sources --help for more usage information
Documentation: https://docs.evidence.dev/core-concepts/data-sources/
VITE v5.4.21 ready in 1881 ms
➜ Local: http://localhost:8137/
➜ Network: use --host to expose
页面此时能打开但图表无数据，按提示先跑 npx evidence sources。
5.4 排障实录：dev 运行中崩溃 ENOENT ... +page.server.js
实测踩坑：dev 服务器运行期间，同一项目里并发执行 evidence build（或页面目录被批量改写）时，dev 进程会崩溃，回显：
6:55:14 AM [vite] page reload build/index.html
6:55:14 AM [vite] page reload build/visits/index.html
node:fs:483
return binding.readFileUtf8(path, stringToFlags(options.flag));
^
Error: ENOENT: no such file or directory, open 'src/pages/settings/+page.server.js'
at Object.readFileSync (node:fs:483:20)
at createProxy (.../node_modules/@sveltejs/kit/src/core/sync/write_types/index.js:520:31)
at ensureProxies (.../node_modules/@sveltejs/kit/src/core/sync/write_types/index.js:506:20)
at update_types (.../node_modules/@sveltejs/kit/src/core/sync/write_types/index.js:281:29)
定位：build/sources 启动时 populateTemplate() 会清空并重建隐藏工作区 .evidence/template/（保留 static/ 数据），正在运行的 dev 进程里 SvelteKit 的类型同步恰好读到被删文件即崩。解决：dev 与 build/sources 不要并发跑；崩溃后直接重启 npx evidence dev（实测重启即恢复，见 5.2）。
六、evidence build / build:strict：产出静态站
6.1 --help
$ npx evidence build --help
Description
build production outputs
Usage
$ evidence build [options]
Options
--debug Enables verbose console logs
-h, --help Displays this message
与 dev 同理，其余参数透传 npx vite build。
6.2 全量构建（实测）
$ npx evidence build
...（vite 编译输出，节选）
Run npm run preview to preview your production build locally.
> Using @sveltejs/adapter-static
Wrote site to "./build"
✔ done
Build complete --> ./build
$ echo $?
0
$ du -sh build
87M build
产物 build/ 为纯静态目录（页面 HTML + Parquet 数据 + 浏览器端 DuckDB-WASM 运行时），可直接丢 Nginx/对象存储/GitHub Pages。Build complete --> ./build 中的目录受 EVIDENCE_BUILD_DIR 控制。
6.3 build:strict（实测）
$ npx evidence build:strict
[INFO]: Enabling strict mode
...（vite 编译输出，节选）
> Using @sveltejs/adapter-static
Wrote site to "./build"
✔ done
Build complete --> ./build
$ echo $?
0
正常项目下与 build 产物一致；差异在坏查询/坏页面时：strict 以非零码失败退出（与 4.8 的 sources --strict 同理）。build:strict 是独立子命令（顶层帮助单列），而 sources 的 strict 是选项 --strict，写法别混。
七、evidence preview：本地验证构建产物
7.1 --help：无业务参数
$ npx evidence preview --help
Description
preview the production build
Usage
$ evidence preview [options]
Options
-h, --help Displays this message
preview 只是 npx serve build 的包装，端口等参数全部由 serve 解析。
7.2 指定端口起服 + 页面验证（实测）
$ npx evidence preview --listen 8138
INFO Accepting connections at http://localhost:8138
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8138/
200
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8138/visits/
200
serve 端同步打访问日志（实测节选）：
HTTP 11/3/2026 7:25:41 AM ::1 GET /visits/
HTTP 11/3/2026 7:25:41 AM ::1 Returned 200 in 2 ms
7.3 数据 URL 带内容哈希：直接猜路径会 404（排障实录）
按 sources 产物路径直觉请求 /data/needful_things/orders/orders.parquet，404：
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8138/data/needful_things/orders/orders.parquet
404
原因：build 会把数据文件挪进一层 md5 哈希目录做缓存指纹（cli.js 内 createHash('md5') 重命名逻辑）。实际路径：
$ find build/data -name '*.parquet'
build/data/web_analytics/daily_visits/95456e05d3f00cef464aede94fca6ec2/daily_visits.parquet
build/data/needful_things/orders/0710a0bd11ce3540d22511eef3ee8142/orders.parquet
$ curl -s -o /dev/null -w "%{http_code} %{size_download}\n" \
http://localhost:8138/data/needful_things/orders/0710a0bd11ce3540d22511eef3ee8142/orders.parquet
200 428224
$ curl -s -o /dev/null -w "%{http_code} %{size_download}\n" http://localhost:8138/data/manifest.json
200 236
页面不感知哈希——浏览器端从 manifest.json 解析真实数据 URL。排查「图表没数据」时先看 manifest，别按磁盘路径硬猜。
7.4 短参数 -l 报错：ArgError: unknown or unexpected option: --l（排障实录）
serve 支持 -l，但经 evidence 转发后失败：
$ npx evidence preview -l 8139
/root/.npm/_npx/aab42732f01924e5/node_modules/arg/index.js:132
throw new ArgError(
^
ArgError: unknown or unexpected option: --l
at arg (/root/.npm/_npx/aab42732f01924e5/node_modules/arg/index.js:132:13)
at parseArguments (file:///root/.npm/_npx/aab42732f01924e5/node_modules/serve/build/main.js:414:28)
...
Node.js v24.22.1
定位：evidence 的 flattenArguments() 把单短横参数统一改写成双短横（-l → --l）再拼给 npx serve build，serve 的参数解析器（arg 包）只注册了 --listen，不认 --l。给 preview 传参一律用长参数（--listen <port>），短参数在 dev（Vite）侧同理慎用。
7.5 无 build 目录：快速失败（实测）
$ npx evidence preview
[!] No build directory found
Run npm run build to create a build
$ echo $?
1
与 dev 的「警告后照常起」不同，preview 没有产物就直接退出。
八、evidence env-debug：配置注入核对
8.1 --help
$ npx evidence env-debug --help
Description
Prints out Evidence variables from the environment and .env file
Usage
$ evidence env-debug [options]
Options
--include-values Includes Environment Variable Values, this will show secrets!
-h, --help Displays this message
8.2 默认只列键名（实测）
$ npx evidence env-debug
┌─────────┬────────────────────────────────────────────┐
│ (index) │ Values │
├─────────┼────────────────────────────────────────────┤
│ 0 │ 'EVIDENCE_SOURCE__web_analytics__password' │
└─────────┴────────────────────────────────────────────┘
来源包括进程环境与 .env（仅 EVIDENCE_/VITE_ 前缀白名单，见《Evidence 40.1.8 配置参数详解》6.1）。凭据注入是否生效，跑一条命令就能确认键在不在。
8.3 --include-values 打印值（实测，含泄密警告）
$ npx evidence env-debug --include-values
┌──────────────────────────────────────────┬────────────┐
│ (index) │ Values │
├──────────────────────────────────────────┼────────────┤
│ EVIDENCE_SOURCE__web_analytics__password │ 'q1w2e3r4' │
└──────────────────────────────────────────┴────────────┘
--help 原文就警告 "this will show secrets!"——排障用完立刻去掉该参数，别把回显贴进工单/CI 日志。
九、evidence upgrade 与版本查询
9.1 upgrade --help（实测）
$ npx evidence upgrade --help
Description
upgrade evidence to the latest version
Usage
$ evidence upgrade [options]
Options
-h, --help Displays this message
upgrade 无业务参数，执行时会把项目内 @evidence-dev/* 依赖升级到 npm 最新版并更新 package.json——40.1.8 已是开源 CLI 的最后一个稳定版（后续主线转向 Evidence Studio 新 CLI，见《Evidence 40.1.8 介绍与选型指南》第三节），实测环境未执行真实升级以免改变钉住的版本。
9.2 --version 显示 0.0.0：CLI 未注册版本号（实测）
$ npx evidence --version
evidence, 0.0.0
$ echo $?
0
顶层帮助虽列了 -v, --version，但 sade 程序没绑定真实版本：退出码虽是 0，输出却恒为占位的 0.0.0，完全不能用来确认版本。确认实际版本用 npm ls @evidence-dev/evidence（见「一、环境信息」实测回显）。
十、注意事项
- 退出码速查（全部实测）：
| 命令场景 | 退出码 |
|---|---|
sources / build / build:strict 正常完成 | 0 |
sources --strict 遇坏查询 | 1 |
sources（非 strict）遇坏查询 | 不退出（挂起，需外部终止） |
preview 无 build 目录 | 1 |
build:sources 别名 | 1（Unknown command） |
| 无参数 / 无效子命令 | 1 |
--version | 0（但输出恒为占位 0.0.0，不可用于版本确认，见 9.2） |
- dev/build/preview 是前台进程，Ctrl+C 即停；服务器形态不需要任何托管（无常驻服务）。
- 透传参数生效前提是底层工具认这个长参数；短参数会被改写成
--x形态而报错（7.4）。 - dev 与 build/sources 并发会触发工作区重建竞态崩溃（5.4），串行执行。
- CLI 启动时自动抬 Node 堆到 4096MB（
NODE_OPTIONS已含--max-old-space-size时不覆盖）。 sources/dev/build/preview启动时均调用@evidence-dev/telemetry的logQueryEvent（cli.js源码实测核对），匿名遥测失败不阻断本地执行；遥测档案为工作区内.profile.json（populateTemplate()的保留清单成员，删依赖重装不丢）。
十一、常见问题
Q1： CI 里 evidence sources 明明打印了 ✅ Done! 却永远不结束？
A： 命中 4.8——某条查询报错但非 strict 模式继续跑完，进程挂起不退出。CI 一律用 evidence sources --strict，坏查询立即失败退出（码 1）。
Q2： evidence build:sources 报 Unknown command？
A： 别名已废弃且 SDK 解析器不认（4.7），把脚本改成 evidence sources。
Q3： preview -l 3000 报 ArgError: unknown or unexpected option: --l？
A： 短参数被 CLI 改写成 --l 后 serve 不识别（7.4），改用 --listen 3000。
Q4： 浏览器/脚本直连产物里的 parquet 路径 404？
A： build 给数据文件加了 md5 哈希目录层（7.3），真实 URL 在 build/data/manifest.json 里，让页面自己解析，不要硬编码路径。
Q5： dev 页面全空、控制台报 Unable to load source manifest？
A： 还没跑过 sources 生成快照（5.3），先 npx evidence sources 再起 dev。
Q6： dev 用着用着崩在 ENOENT ... +page.server.js？
A： 并发 build/sources 重建了 .evidence/template 工作区（5.4），停掉 dev 重新启动即可恢复。
十二、参考链接
- Evidence 40.1.8 CLI 源码：npm 包
@evidence-dev/evidence@40.1.8内cli.js（本文机制核对来源） - Legacy 文档（40.x 对应）：https://legacy-docs.evidence.dev/
- 新 CLI 参考（非 40.x，仅作对照）：https://docs.evidence.dev/cli/
- serve 参数说明：https://github.com/vercel/serve
- 同专栏：《Evidence 40.1.8 安装与项目初始化指南》《Evidence 40.1.8 配置参数详解》《Evidence 40.1.8 介绍与选型指南》