Evidence 40.1.8 配置参数详解

目标：逐项讲清 Evidence 40.1.8 的四类配置载体（evidence.config.yaml、sources/<源>/connection.yaml、.env、页面组件属性）的参数含义、生效时机与凭据注入机制。本文全部结论来自 Ubuntu 26.04.1 LTS 服务器上 40.1.8 实测与 CLI/SDK 源码核对（@evidence-dev/evidence 与 @evidence-dev/sdk 包内文件路径随文标注）。

一、环境信息

• 操作系统：Ubuntu 26.04.1 LTS（x86_64）；Node.js v24.22.1、npm 11.19.1（实测）。
• 组件：@evidence-dev/evidence 40.1.8；实测工程 /opt/evidence/my-report（DuckDB 源 needful_things + PostgreSQL 16 源 web_analytics，构建过程见 《Evidence 40.1.8 安装与项目初始化指南》）。
• 本文引用的源码路径均指 npm 包 @evidence-dev/evidence@40.1.8、@evidence-dev/sdk 安装后的包内文件。

二、前置条件

已有一个 Evidence 40.x 工程且依赖装好（node_modules 就位），本文全部命令在项目根目录执行；涉及数据源的验证需 PostgreSQL 可连（127.0.0.1:5433，库 analytics，演示账号 postgres / 密码 q1w2e3r4）。

三、配置体系总览

Evidence 40.1.8 没有单一「总配置文件」，配置分散在四类载体：

模板工程不含 svelte.config.js / vite.config.js（实测文件不存在）：SvelteKit/Vite 配置由 CLI 生成在隐藏工作区 .evidence/template/ 内，日常无需也不应直接维护。

四、evidence.config.yaml 逐项详解

模板出厂文件实测全文可分三段。

4.1 appearance：外观模式

appearance:
  default: system    # light | dark | system
  switcher: true     # 页面是否显示明暗切换按钮

4.2 theme：主题色板

出厂实测原文（colorPalettes 的 light 与 dark 出厂为同一组 10 色，colorScales 同理）：

theme:
  colorPalettes:     # 图表系列色循环表
    default:
      light:
        - "#236aa4"
        - "#45a1bf"
        - "#a5cdee"
        - "#8dacbf"
        - "#85c7c6"
        - "#d2c6ac"
        - "#f4b548"
        - "#8f3d56"
        - "#71b9f4"
        - "#46a485"
      dark:
        - "#236aa4"
        - "#45a1bf"
        - "#a5cdee"
        - "#8dacbf"
        - "#85c7c6"
        - "#d2c6ac"
        - "#f4b548"
        - "#8f3d56"
        - "#71b9f4"
        - "#46a485"
  colorScales:       # 顺序型色阶（热力图等）
    default:
      light:
        - "#ADD8E6"
        - "#00008B"
      dark:
        - "#ADD8E6"
        - "#00008B"
  colors:            # 语义色，light/dark 成对
    primary:
      light: "#2563eb"
      dark: "#3b82f6"
    accent:
      light: "#c2410c"
      dark: "#fdba74"
    base:
      light: "#ffffff"
      dark: "#09090b"
    info:
      light: "#0284c7"
      dark: "#38bdf8"
    positive:
      light: "#16a34a"
      dark: "#4ade80"
    warning:
      light: "#f8c900"
      dark: "#fbbf24"
    negative:
      light: "#dc2626"
      dark: "#f87171"

💡 技术拓展：色板只是主题的一种做法，常见主题机制对比——

机制	说明	在 Evidence 40.1.8
明暗模式（light/dark/system）	整套语义色成对切换	appearance + 各色的 light/dark 对
系列色板（categorical palette）	图表系列颜色循环表	theme.colorPalettes
顺序色阶（sequential scale）	热力图/分级着色渐变	theme.colorScales
品牌主题打包分发	主题作为插件安装	40.1.8 不支持，仅 YAML 直改

本文工程实际采用出厂默认色板未改动；改色只需覆盖对应键。

4.3 plugins：组件与数据源插件

plugins:
  components:
    "@evidence-dev/core-components": {}   # 出厂图表/表格/输入组件库
  datasources:
    "@evidence-dev/bigquery": { }
    "@evidence-dev/csv": { }
    "@evidence-dev/databricks": { }
    "@evidence-dev/duckdb": { }
    "@evidence-dev/mssql": { }
    "@evidence-dev/mysql": { }
    "@evidence-dev/postgres": { }
    "@evidence-dev/source-javascript": { }
    "@evidence-dev/snowflake": { }
    "@evidence-dev/sqlite": { }
    "@evidence-dev/trino": { }
    "@evidence-dev/motherduck": { }

出厂声明 12 个数据源插件（实测原文）。注释原文写明：新增数据源要同时加 npm 包（package.json）和这里的声明；反之删减声明可缩小构建产物。type: 字段取值即此处插件名对应的源类型。

五、数据源连接：sources/<源名>/connection.yaml

5.1 两种写法均实测可用

模板自带源用列表式：

sources:
  - name: needful_things
    type: duckdb
    options:
      filepath: ./needful_things.duckdb

本文实测新增的 Postgres 源用平铺式（同样通过）：

name: web_analytics
type: postgres
options:
  host: 127.0.0.1
  port: 5433
  database: analytics
  user: postgres
  ssl: null
  timeout: 180000

一个目录 = 一个源；目录名建议与 name 一致（环境变量注入按 name 匹配）。同目录下的每个 .sql 是一条查询，查询在页面/组件中的引用名为 <目录名>.<文件名>（如 web_analytics.daily_visits）。

5.2 常用 type 的 options

password 等敏感值不要写进 connection.yaml（该文件会进 Git），注入机制见第六节。

六、凭据与环境变量：三套机制，别混用

这是 40.1.8 最容易踩错的配置面（《Evidence 40.1.8 安装与项目初始化指南》 8.2 节有完整试错实录）。

6.1 .env 的前缀白名单

CLI 用 Vite 的 loadEnv 加载 .env，只收 EVIDENCE_ 与 VITE_ 前缀的变量（@evidence-dev/evidence 包 cli.js 的 loadEnvFile()），其余键一律不注入进程环境。

6.2 connection.yaml 的凭据注入：EVIDENCE_SOURCE__<源名>__<选项名>

正确姿势（实测）：connection.yaml 中省略 password，.env 写：

EVIDENCE_SOURCE__web_analytics__password=q1w2e3r4

规则（@evidence-dev/sdk 包 src/plugins/datasources/loadSourceConfig.js 实测源码）：

• 匹配形如 EVIDENCE_SOURCE__<源名>__<选项> 的环境变量，源名部分大小写不敏感前缀匹配，选项名按原文写入 options（故用小写 password 与连接器键名一致）；
• 多个凭据可走 EVIDENCE_SOURCE__<源名>__auth 整包注入；
• connection.yaml 的值域不做 ${} 插值——写 password: ${POSTGRES_PASSWORD} 会把字面量 ${POSTGRES_PASSWORD} 当密码发给数据库，报 password authentication failed（实测）。

6.3 备选：connection.options.yaml（base64）

同目录可放 connection.options.yaml，值需 base64 编码（源码同上：Buffer.from(value, 'base64').toString('utf-8')），面向托管平台的密钥管理场景；自托管用 6.2 即可。

6.4 SQL 查询内的变量替换：EVIDENCE_VAR__<变量名>

.sql 文件里的 ${var} 占位符由环境变量 EVIDENCE_VAR__<var> 替换（源码 src/plugins/datasources/sub-source-vars.js），未命中会告警 Missed substition on the variable "${...}"。典型用法：把 schema 名参数化。

七、数据目录与构建行为环境变量

CLI 读取的数据与构建行为环境变量，含义与默认值均按 @evidence-dev/evidence@40.1.8 包内 cli.js 源码核对（--help 不回显这些变量，来源别搞错）：

八、package.json scripts 与组件配置

模板出厂 scripts 实测全文：

{
  "build": "evidence build",
  "build:strict": "evidence build:strict",
  "dev": "evidence dev --open /",
  "test": "evidence build",
  "sources": "evidence sources",
  "sources:strict": "evidence sources --strict",
  "preview": "evidence preview"
}

页面级组件配置以属性传入（实测 《Evidence 40.1.8 安装与项目初始化指南》 第十节 visits.md）：图表用 data={查询}、x=/y= 指定列、title= 标题；<DataTable data={by_page} viewBox=false /> 关闭表格视图框。SQL 块的名字（sql daily）即页面内变量名。

九、配置核对工具箱

改完配置先验证再构建：

$ npx evidence env-debug --include-values
┌──────────────────────────────────────────┬────────────┐
│ (index)                                  │ Values     │
├──────────────────────────────────────────┼────────────┤
│ EVIDENCE_SOURCE__web_analytics__password │ 'q1w2e3r4' │
└──────────────────────────────────────────┴────────────┘

只列 EVIDENCE_ 前缀变量（6.1 白名单），一眼确认凭据是否注入成功；--include-values 打印值，调试完务必去掉。连接执行细节用 npx evidence sources --debug。命令全量参数见 《Evidence 40.1.8 常用 CLI 命令详解》，产品形态与选型背景见 《Evidence 40.1.8 介绍与选型指南》。

十、生产配置模板（推荐）

适用场景：内网自托管、PostgreSQL 单源、16GB 内存构建机的常规报表工程。

evidence.config.yaml          # 只改 theme/appearance；datasources 删到实际用到的插件
sources/
  pg_main/connection.yaml     # host/port/database/user/ssl/timeout，无密码
  pg_main/*.sql
.env                          # 不进 Git：EVIDENCE_SOURCE__pg_main__password=...
package.json                  # scripts 保持出厂；CI 里 npm ci + evidence sources --strict + build

要点：sources --strict/build:strict 让坏查询直接失败退出（非 strict 会「报错但继续」甚至挂起，见 《Evidence 40.1.8 常用 CLI 命令详解》 4.8 节排障实录），适合 CI 门禁；.env 与 connection.options.yaml 二选一管理凭据，切勿把明文密码提交进仓库。

十一、常见问题（FAQ）

Q1： connection.yaml 里写了 password: ${POSTGRES_PASSWORD} 不生效，仍报 password authentication failed？ A： 该文件的值域不做 ${} 插值，占位符按字面量发给数据库（6.2 实测）。删掉 password 行，用 .env 的 EVIDENCE_SOURCE__<源名>__password 注入。

Q2： .env 里写了变量，evidence sources 却读不到？ A： .env 只加载 EVIDENCE_/VITE_ 前缀（6.1），其余键一律不注入。用 npx evidence env-debug 核对（第九节实测）。

Q3： 想改查询结果 Parquet 的输出目录？ A： 设 EVIDENCE_DATA_DIR（第七节），实测 EVIDENCE_DATA_DIR=./custom-data npx evidence sources --queries needful_things.orders 产物整体落到 custom-data/ 下。

十二、参考链接

• npm 包页：https://www.npmjs.com/package/@evidence-dev/evidence
• 40.x 对应文档（legacy）：https://legacy-docs.evidence.dev/
• GitHub 仓库：https://github.com/evidence-dev/evidence
• 同专栏：《Evidence 40.1.8 安装与项目初始化指南》、《Evidence 40.1.8 常用 CLI 命令详解》