Evidence 40.1.8 介绍与选型指南

目标：为评估「SQL 驱动的报表站点生成器」的读者讲清 Evidence 40.1.8 的定位、架构、功能生态与选型取舍。版本与生态数据联网实查（查询日期 2026-11-03），架构与产物数据来自本专栏实测项目（Ubuntu 26.04.1 LTS + Node v24.22.1）。

Evidence（GitHub：evidence-dev/evidence）是一个 SQL 优先的 BI 报表站点生成器：报表页面用 Markdown 编写，数据逻辑用 .sql 文件表达，构建产物是纯静态网站，可托管在任何静态 Web 服务器上。它的形态是「Node.js CLI 工具 + 静态站点」，没有任何常驻守护服务——开发期靠 evidence dev 起临时预览服务器，发布期 evidence build 一次性产出静态目录后即结束进程。因此本专栏的安装篇按 《Evidence 40.1.8 安装与项目初始化指南》 组织，而非「服务端部署指南」。

一、环境信息

• 本专栏实测环境（四篇共用同一工程）：Ubuntu 26.04.1 LTS（x86_64）、Node.js v24.22.1、npm 11.19.1（均实测回显，见安装篇）。
• 实测对象：开源 CLI 包 @evidence-dev/evidence 最新稳定版 40.1.8（npm registry dist-tags.latest 实查，发布于 2026-02-06T16:07:30.925Z）。
• 数据源：DuckDB（模板自带示例库，10000 行 orders 表）+ PostgreSQL 16（自建 analytics 库，122 行 daily_visits 表）。
• 联网实查日期：2026-11-03（registry.npmjs.org、GitHub、docs.evidence.dev、legacy-docs.evidence.dev）。

💡 技术拓展：「报表即代码（Reports-as-Code）」赛道不止 Evidence 一种形态——

形态	代表	特点	取舍
SQL+Markdown 编译成纯静态站	Evidence 40.x（本文）	零后端运维，Git 管理，浏览器端查询	数据为构建期快照
Web 建模 + 常驻服务	Metabase / Superset	实时查询、自助点选	需运维服务与元数据库
笔记本/语义层托管	Evidence Studio / dbt + 语义层	托管、协作、治理	依赖平台账号

本文聚焦第一形态：自托管纯静态路线，即开源 CLI 40.1.8。

二、Evidence 是什么

一句话：把「SQL + Markdown」编译成 BI 报表网站。

一个 Evidence 项目的核心只有两类文件：

1. 数据源查询：sources/<源名>/<查询名>.sql，每个文件就是一条 SQL；构建时 Evidence 连到源库执行，把结果落成 Parquet 文件（如实测的 static/data/web_analytics/daily_visits/daily_visits.parquet）。
2. 报表页面：pages/*.md，Markdown 里嵌 ```sql 代码块引用查询结果，再用内置组件渲染：

  select
      date,
      sum(visits) as visits
  from web_analytics.daily_visits
  group by date
  order by date

组件用属性直接消费查询结果（data={daily}），无需写前端代码。这套写法在 40.1.8 上实测可完整构建出静态站点（见 《Evidence 40.1.8 安装与项目初始化指南》）。

与「装一个 BI 服务、在 Web 界面里点选建模」的传统路线不同，Evidence 把报表当作代码工程：Git 版本管理、代码评审、CI 构建、静态托管，天然契合 dbt/数仓团队的既有工作流。

三、2026 年的产品格局：先分清「开源 CLI 40.1.8」和「新主线」

这是 2026 年选型 Evidence 最关键的一条信息，全部联网实查（查询日期 2026-11-03）：

解读：

• 开源 CLI 40.1.8 仍是 npm 上可安装、可用的最新稳定版，dev/build/sources/preview 全链路本专栏已实测跑通；但它已进入「不再演进」状态。
• 官方主线转向 Evidence Studio + 新 CLI：新 CLI 面向「Agent-ready」工作流（query/describe/schema 等机器友好命令），报表语法从 Svelte 换成 Markdoc，数据接入以仓库型数仓（Snowflake/BigQuery 直连或托管 Evidence Warehouse）为主，不再内置 DuckDB WASM 静态站点路线。
• 迁移指南明确：40.x 项目不能自动迁移（组件语法不兼容），需按新语法重写；40.x 项目可无限期继续运行，但不再有功能更新。

选型结论：需要「纯静态、自托管、DuckDB/Postgres 直连、无账号依赖」的报表站，40.1.8 是当前唯一成熟选择，本专栏即按此实测；如果团队在 Snowflake/BigQuery 上且接受托管平台，应直接评估新 CLI + Evidence Studio，不要在 40.x 上开新项目。

四、架构与运行模型（40.1.8）

数据流一条线（各环节本专栏均实测，见 《Evidence 40.1.8 配置参数详解》、《Evidence 40.1.8 常用 CLI 命令详解》）：

sources/<源>/connection.yaml   ← 数据源连接（duckdb/postgres/bigquery…）
sources/<源>/<查询>.sql        ← 每条 SQL 一个文件
        │  evidence sources / dev / build 时执行
        ▼
static/data/<源>/<查询>/<查询>.parquet + manifest.json   ← 查询结果快照（EVIDENCE_DATA_DIR 可改目录，实测）
        │  浏览器端 DuckDB-WASM 直接查询 parquet
        ▼
pages/*.md（```sql 块 + 组件）  ← 报表页面
        │  evidence build（SvelteKit + adapter-static）
        ▼
build/ 纯静态目录（实测 87M，含全部 parquet 与 wasm）→ 任意静态服务器托管

形态特征：

• 无常驻服务：dev 是 Vite 开发服务器（改页面即时刷新，Ctrl+C 即停）；build 一次性产出；preview 只是本地起一个静态文件服务验证产物。
• 查询在浏览器里跑：DuckDB-WASM 加载 Parquet 快照，Web 服务器/对象存储即可支撑访问，无需后端算力。
• 代价：数据是构建期快照，实时性取决于重跑 evidence sources/build 的频率；大表需预聚合，否则静态产物膨胀（实测 122 行 + 10000 行两表产物即 87M，大头是 DuckDB-WASM 运行时本身）。

五、数据源与组件生态

evidence.config.yaml 的 plugins.datasources 出厂声明了 12 个数据源插件（实测模板原文）：@evidence-dev/bigquery、csv、databricks、duckdb、mssql、mysql、postgres、source-javascript、snowflake、sqlite、trino、motherduck。组件侧由 @evidence-dev/core-components 提供折线/柱状/热力图/桑基/地图/表格/输入控件等（legacy 文档 Components 目录完整列举）。本专栏实测覆盖 DuckDB（模板自带示例库，10000 行 orders 表）与 PostgreSQL 16（自建 analytics 库，122 行 daily_visits 表）双源混排一页。

六、上手路径（最小可用示例）

按本专栏顺序走一遍即可在 Ubuntu/任意 Node 环境跑通双源报表站：

1. 《Evidence 40.1.8 安装与项目初始化指南》——脚手架、DuckDB/Postgres 双源接入、dev 服务器实测。
2. 《Evidence 40.1.8 配置参数详解》——evidence.config.yaml、connection.yaml、凭据注入与环境变量全表。
3. 《Evidence 40.1.8 常用 CLI 命令详解》——dev/build/sources/preview/env-debug 逐命令实测与排障。

最小可用路径三步（详细回显见安装篇）：git clone 模板并钉住开源版提交 → npm ci && npx evidence sources → npx evidence dev 起预览，浏览器打开 http://localhost:3000/ 即见示例报表。

七、适用与不适用清单

适用：

1. 数仓/dbt 团队的「最后一公里」：把模型表变成可分享报表站，构建进 CI，产物丢 GitHub Pages/对象存储/内网 Nginx。
2. 轻量指标周报/月报站：定时重跑 evidence sources && evidence build 即刷新，无需任何服务运维。
3. 完全离线/内网隔离环境：40.1.8 全链路无账号依赖，dev/build/sources 实测均无需任何登录（依赖装好后离线可跑）。

不适用/慎用：

1. 需要实时查询与自助分析（快照模型 + 无点选建模）。
2. 需要告警、行级权限、审计等治理能力（交给 Studio 或传统 BI）。
3. 新项目押注 40.x 长期演进（官方已转向，见第三节）。

八、与同类工具的量化选型对比

同赛道常被对比的两款开源 BI（星数/license 查询日期 2026-11-03，api.github.com）：

选型判断：

• 选 Evidence：报表逻辑就是 SQL、团队有 Git/CI 习惯、希望零后端运维（静态托管）、可接受 T+小时级数据新鲜度。
• 选 Metabase/Superset：需要业务人员自助点选探索、实时查询、行级权限等企业功能。
• 不选 Evidence 40.x：需要官方持续演进 → 看新 CLI + Studio；需要浏览器直连大表实时查询 → 快照模型不匹配。

九、参考链接

• npm 包页：https://www.npmjs.com/package/@evidence-dev/evidence
• GitHub 仓库：https://github.com/evidence-dev/evidence（MIT License）
• 官方模板仓库：https://github.com/evidence-dev/template
• 40.x 对应文档（legacy）：https://legacy-docs.evidence.dev/
• 新 CLI 与 Evidence Studio 文档：https://docs.evidence.dev/

数据来源汇总（查询日期 2026-11-03）：registry.npmjs.org（@evidence-dev/evidence dist-tags/time）；api.github.com（evidence-dev/evidence、evidence-dev/template commits、metabase/metabase、apache/superset）；docs.evidence.dev（quickstart、cli/index、cli/commands、cli/connections、migration-guide）；legacy-docs.evidence.dev（安装/组件/部署目录）。