chezmoi 模板函数 `dopplerProjectJson`：以结构化 JSON 方式获取 Doppler 密钥

• 开发工具
• CLI
• 配置管理

dopplerProjectJson是 chezmoi 内置的模板函数，用于在渲染 dotfiles 模板时，通过 Doppler CLI 以 JSON 结构化数据的形式获取指定项目（project）与环境（config，Doppler 中亦称 environment）中的密钥（secret）。本指南完整讲解该函数的签名、参数回退逻辑、底层命令调用链、chezmoi 配置变量以及来自仓库测试用例的实战用法，帮助你安全地把 Doppler 托管的密钥注入到跨机器管理的 dotfiles 中。

函数签名与返回值

dopplerProjectJson的完整签名定义在 dopplerProjectJson.md 中：

dopplerProjectJson [*project* [*config*]]

• *project*：Doppler 项目名（可选）。
• *config*：Doppler 配置名，即环境名（可选），如dev、staging、prod。

函数返回一个json结构化数据对象，其中包含目标项目与配置下的全部密钥。与单值获取函数doppler（返回指定单个 key 的明文值，见 doppler.md）不同，dopplerProjectJson返回的是整个密钥集合的 JSON 对象，因此可以在模板中通过属性访问语法直接取用任意字段，例如：

{{ (dopplerProjectJson "project_name" "configuration_name").SECRET_NAME }}

从源码结构看，chezmoi 将返回值注册为通用any类型并解析为map[string]any，因此除了点号访问，你还可以继续把某个字段管道给其他模板函数做二次加工（详见下文“与 fromJson 组合”一节）。

参数省略时的回退逻辑

如果*project*或*config*为空或省略，chezmoi 会回退使用配置文件中doppler.project与doppler.config配置变量的值（前提是它们被设置且非空）。

这一回退逻辑在 dopplertemplatefuncs.go 的appendDopplerAdditionalArgs中实现：当模板参数存在且非空字符串时优先采用模板参数，否则读取c.Doppler.Project/c.Doppler.Config。也就是说，即使模板里不写任何项目与配置名，只要在 chezmoi 配置中声明了默认值，函数依然能正确工作：

{{ dopplerProjectJson.PASSWORD }}

注意，此时函数以无参数形式调用，返回值（整个 JSON 对象）直接作为后续访问的根对象，这是 Go 模板中对函数返回值直接做点号访问的合法写法。仓库的 txtar 测试脚本 doppler.txtar 中对该用法做了验证：exec chezmoi execute-template '{{ dopplerProjectJson.PASSWORD }}'期望输出correcthorsebatterystaple。

参数个数的校验

源码中对参数个数有严格的 panic 保护（dopplertemplatefuncs.go）：

• 附加参数（不含函数名本身）超过 2 个时，立即 panic：expected 0 to 2 arguments, got %d。

因此该函数最多只接受project与config两个位置参数。

底层命令与调用链

无论传参与否，dopplerProjectJson最终都会调用 Doppler CLI 的下载命令，并追加项目与配置参数：

doppler secrets download --json --no-file [--project <project>] [--config <config>]

这条命令链在 dopplertemplatefuncs.go 中由appendDopplerAdditionalArgs构造。此外，还有几个值得注意的底层行为：

1. 工作目录：命令在c.DestDirAbsPath（目标目录）中执行（dopplertemplatefuncs.go），源码注释明确指出：这是因为 Doppler 会使用相对路径查找其.doppler.json配置文件。如果你的 dotfiles 通过.doppler.json关联特定项目，务必知晓此行为。
2. 结果缓存：每次调用都会把「参数组合 → 输出」存入outputCache（以\x00拼接参数作为 key），相同参数的重复调用不会重复执行 CLI（dopplertemplatefuncs.go）。
3. 密钥跳过：函数开头调用chezmoi.SkipTemplateIf(c.skipSecrets)（dopplertemplatefuncs.go），当用户启用密钥跳过配置时，该函数会直接跳过渲染，避免在不应输出密钥的场合泄露数据。
4. CLI 配置：实际执行的命令名与额外参数来自doppler配置节（见下节），并会拼接上c.Doppler.Args中的额外参数。

相关配置变量

chezmoi 在配置文件（chezmoi.toml/chezmoi.yaml等）中通过doppler配置节控制该函数的 CLI 行为，字段定义见 variables.md.yaml：

这些字段直接映射到源码中的 dopplerConfig 结构体（同时支持json、mapstructure、yaml标签，因此三种配置格式均可使用）。例如，在chezmoi.toml中声明默认项目与环境：

[doppler] command = "doppler" project = "default-project" config = "default-config"

仓库测试脚本 doppler.txtar 的home3/user/.config/chezmoi/chezmoi.toml正是这样配置的，随后验证了「不传参数使用配置默认值」的完整路径：{{ (dopplerProjectJson).DOPPLER_PROJECT }}输出default-project，{{ (dopplerProjectJson "default-project").DOPPLER_CONFIG }}输出default-config。

在模板中的实战用法

1. 直接取单个密钥

指定项目与配置，点号访问目标密钥：

{{ (dopplerProjectJson "project" "config").PASSWORD }}

对应测试用例见 doppler.txtar：mock CLI 返回的 JSON 中PASSWORD_123的值为staplebatteryhorsecorrect，模板输出与该值一致。

2. 与fromJson组合解析嵌套 JSON 密钥

Doppler 允许密钥本身存储一段 JSON 字符串（如审计信息、凭证对象）。此时可先取出该字段，再管道给fromJson函数展开为可访问的嵌套结构：

{{ ((dopplerProjectJson "project" "config").JSON_SECRET | fromJson).created_by.email }}

测试脚本 doppler.txtar 用JSON_SECRET字段验证了这一链路，期望输出user@example.com。这也是dopplerProjectJson相比单值函数doppler的典型优势：先拿到整体结构，再按需解析。

3. 省略部分参数

• 只给项目名、配置走默认值：

  {{ (dopplerProjectJson "project").PASSWORD }}

• 项目与配置均给空字符串，等价于全部走 chezmoi 配置默认值：

  {{ (dopplerProjectJson "" "").PASSWORD }}

这两类用法在 doppler.txtar 中均有断言覆盖。

4. 典型使用场景

在 dotfiles 中，dopplerProjectJson最常见的用途是让模板按机器或环境拉取不同的配置，例如：

{{ $secrets := dopplerProjectJson (include "project" .) (include "config" .) }} export API_TOKEN={{ $secrets.API_TOKEN }}

更完整的 Doppler 集成说明（包括认证前提、与doppler单值函数的对比示例）可参考 用户指南：Doppler，模板函数总览见 模板参考索引。

模板函数注册与使用前提

dopplerProjectJson在 config.go 中被注册进模板函数表（"dopplerProjectJson": c.dopplerProjectJSONTemplateFunc），因此无需额外导入即可在任意.tmpl模板中使用。

使用时需满足的前提：

• 本机安装并可执行 Doppler CLI（doppler命令，或通过doppler.command指定其他可执行文件）；
• 已通过doppler login完成认证，且目标目录下存在可供 Doppler 识别项目/配置的上下文（源码注释明确提到.doppler.json相对路径查找行为）；
• 若不想在模板里写死项目与配置名，请在 chezmoi 配置中设置doppler.project与doppler.config。

小结

dopplerProjectJson让 chezmoi 模板以 JSON 结构化数据的方式消费 Doppler 的全部密钥：既能点号直达单个密钥，也能与fromJson等函数组合解析嵌套 JSON；项目与环境参数既可显式传入，也可由doppler.project/doppler.config配置变量统一管理。其底层实现（参数拼接、目标目录执行、输出缓存、密钥跳过）与配套 txtar 测试用例均已在源码中验证，可放心在跨机器 dotfiles 的模板渲染中使用。

• 开发工具
• CLI
• 配置管理