chezmoi 模板函数 protonPassJSON：从 Proton Pass 提取结构化密钥数据

开发工具CLI配置管理【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址https://gitcode.com/gh_mirrors/ch/chezmoi点击查看免费下载本篇技术指南讲解 chezmoi 点文件管理器中内置的模板函数protonPassJSON它以 Proton Pass 的pass://URI 为入参调用 Proton Pass CLI 并以 JSON 结构返回该条目下的全部字段数据从而在点文件模板中按需取用密码、WiFi 凭据、TOTP 等敏感信息。读完本文你将掌握protonPassJSON的调用语法、返回结构、缓存与安全语义并能结合仓库源码与测试用例确认其真实行为边界。函数签名与核心用途protonPassJSON是 chezmoi 内置的 Proton Pass 模板函数族protonPass*之一与protonPass、protonPassAttachment共同构成 Proton Pass 集成能力。其文档定义如下protonPassJSON *uri*入参一个pass://形式的 Proton Pass 条目 URI返回值与该 URI 对应的结构化数据JSON 对象可直接用模板语法逐层取字段。典型示例来自官方文档 protonPassJSON.md{{ (protonPassJSON pass://$SHARE_ID/$ITEM_ID).item.content.content.key.password }}其中$SHARE_ID、$ITEM_ID是占位符实际使用时替换为真实的共享库shareID 与条目itemID。该表达式依次穿透 JSON 层级item→content→content→ 具体条目类型如Wifi、Login、key等→ 目标字段最终得到密码等敏感值并写入模板输出。返回结构JSON 对象而非文本protonPassJSON与protonPass的关键区别在于返回类型protonPass返回pass-cli item view的原始文本输出stringprotonPassJSON则在调用时追加--outputjson参数并将输出解析为 Go 的map[string]any后返回因此在模板中可以直接进行结构化字段访问。从实现看internal/cmd/protonpasstemplatefuncs.go 中func (c *Config) protonPassJSONTemplateFunc(item string) any { chezmoi.SkipTemplateIf(c.skipSecrets) args : []string{item, view, item, --outputjson} output : mustValue(c.protonPassOutput(args)) var result map[string]any must(json.Unmarshal(output, result)) return result }即底层执行的是pass-cli item view uri --outputjson随后用标准库encoding/json反序列化为 map。这意味着 JSON 中数组会变为[]any对象会变为map[string]any数字按 Go JSON 规则解码。以仓库测试 protonpass.txtar 中模拟的pass-cli输出为例调用protonPassJSON pass://MyVault/My-Wifi-Item会返回形如{ item: { id: ..., share_id: ..., vault_id: ..., content: { title: My Wifi, content: { Wifi: { ssid: My Wifi SSID, password: MyWifiPassword, security: WPA2, sections: [] } }, extra_fields: [] }, state: Active, create_time: 2025-10-27T11:11:22 }, attachments: [] }因此模板中可用链式访问精确取值且不需要额外trimprotonPassJSON返回的是解析后的结构而非带换行的原始文本。底层调用链URI 如何变成密码从源码可以梳理protonPassJSON的完整调用链internal/cmd/protonpasstemplatefuncs.go模板引擎按 internal/cmd/config.go 中注册的映射protonPassJSON: c.protonPassJSONTemplateFunc找到实现函数将入参拼接为pass-cli item view uri --outputjson参数列表protonPassOutput以exec.Command启动pass-cli并透传 stdincmd.Stdin os.Stdin、透传 stderrcmd.Stderr os.Stderr——前者让 CLI 可以交互式解锁密钥库或确认操作后者让错误信息直接呈现命令失败时通过newCmdOutputError包装错误并 panic模板渲染随之终止并暴露给用户成功后将 stdout 作为该参数组合的缓存结果返回。可验证的运行示例与测试脚本等价chezmoi execute-template {{ (protonPassJSON pass://MyVault/My-Wifi-Item).item.content.content.Wifi.password }} # 输出: MyWifiPassword对应测试断言位于 internal/cmd/testdata/scripts/protonpass.txtar。命令配置与 doctor 诊断protonPassJSON实际调用的可执行文件名通过配置项protonPass.command控制默认值为pass-cli# ~/.config/chezmoi/chezmoi.yaml protonPass: command: pass-cli # 默认值可改为绝对路径或 PATH 中的别名证据来源internal/cmd/config.goProtonPass: protonPassConfig{Command: pass-cli}internal/cmd/config.goProtonPass protonPassConfig json:protonPass mapstructure:protonPass yaml:protonPassassets/chezmoi.io/docs/reference/configuration-file/variables.md.yamlprotonPass.command默认值pass-cli类型为字符串。chezmoi doctor会检查该命令是否存在及版本是否合规internal/cmd/doctorcmd.go检查项名称protonpass-command未配置时报告checkResultWarning二进制不存在时报告checkResultInfo通过--version验证输出匹配^Proton Pass CLI (\d\.\d\.\d)。因此即使protonPassJSON首次调用失败也可先用chezmoi doctor快速定位是命令缺失、版本不匹配还是 URI 错误。安全语义与缓存行为protonPassJSON受skipSecrets开关约束函数入口调用chezmoi.SkipTemplateIf(c.skipSecrets)internal/cmd/protonpasstemplatefuncs.go。当用户启用跳过密钥如--skip-secrets或相关配置时该函数会静默跳过渲染防止在无需密钥的场合如公开模板演练泄露凭据。同时protonPassOutput内置了输出缓存internal/cmd/protonpasstemplatefuncs.gokey : strings.Join(args, \x00) if data, ok : c.ProtonPass.outputCache[key]; ok { return data, nil }缓存键由全部参数以\x00连接而成。这意味着在**同一次 chezmoi 运行apply / execute-template 等**中多次以相同 URI 调用protonPassJSON只会真正执行一次pass-cli后续命中缓存显著减少对外部密码管理器的重复调用。每次进程退出后缓存清空不会跨运行持久化。另外值得注意若模板同时使用protonPass文本输出与protonPassJSONJSON 输出两者参数不同后者带--outputjson因此缓存键不同会各自独立执行一次。与同族函数的分工Proton Pass 模板函数族在 internal/cmd/config.go 中统一注册三者分工互补函数入参返回典型场景protonPasspass://$SHARE_ID/$ITEM_ID/$FIELD原始文本string直接取单个字段值如{{ protonPass pass://S/I/password }}protonPassJSONpass://$SHARE_ID/$ITEM_IDJSON 对象map取多字段、嵌套字段、数组等结构化数据protonPassAttachmentshare-iditem-idattachment-id附件内容string下载并读取条目附件如 SSH 私钥protonPassAttachment同样具备缓存attachmentCache键为shareID\x00itemID\x00attachmentID且因pass-cli输出冗长默认不连接 stdout/stderr仅在--debug时透传internal/cmd/protonpasstemplatefuncs.go。实战在点文件模板中组合使用protonPassJSON最常见的落地方式是配合 Go 模板的条件与遍历语法动态生成仅含当前机器所需凭据的配置文件{{- $item : protonPassJSON pass://MyVault/My-Wifi-Item -}} # /etc/wpa_supplicant.conf 模板片段 network{ ssid{{ $item.item.content.content.Wifi.ssid }} psk{{ $item.item.content.content.Wifi.password }} key_mgmtWPA-PSK }实现要点用{{- $item : ... -}}将返回值暂存到模板变量避免多次调用也避免多次命中缓存的边际开销每一层.item.content.content.类型.字段的路径由pass-cli --outputjson的真实结构决定可用chezmoi execute-template配合debug先观察原始 JSONchezmoi execute-template {{ protonPassJSON pass://MyVault/My-Wifi-Item | toJson }}借助toJson模板函数将 map 序列化输出即可核对字段路径若取不到字段错误会由mustValue/must在模板渲染期直接暴露便于排查。总结protonPassJSON是 chezmoi 与 Proton Pass 深度集成的结构化取数入口它以pass://URI 定位条目经由pass-cli item view --outputjson获取 JSON再返回可直接链式访问的模板对象。源码确认其具备 stdin 透传支持 CLI 交互解锁、skipSecrets跳过语义与进程内输出缓存三项关键行为chezmoi doctor提供了独立的命令健康检查。对于需要在多台机器上安全同步点文件、又不希望把明文密码写进仓库的用户protonPassJSON提供了「模板即查询」的优雅方案。更多相关参考protonPass文本函数见 protonPass.md附件函数见 protonPassAttachment.md模板函数总览见 index.md测试用例见 protonpass.txtar。赞分享开发工具CLI配置管理【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址https://gitcode.com/gh_mirrors/ch/chezmoi点击查看免费下载相关推荐免费苹方字体包快速接入指南6种字重双格式一次终结跨平台字体混乱免费苹方字体包快速接入指南6种字重双格式一次终结跨平台字体混乱 你在公司群里被前端同事艾特这个页面到我电脑上怎么变成宋体了点开截图一看标题塌了、正开发工具CLI配置管理chezmoi 模板函数 passFields 完全指南从 pass 密码库提取结构化键值数据chezmoi 模板函数 passFields 完全指南从 pass 密码库提取结构化键值数据 导读 passFields 是 chezmoi 内置的模板函数开发工具CLI配置管理chezmoi 模板函数 keeperDataFields从 Keeper Commander CLI 提取结构化凭据数据chezmoi 模板函数 keeperDataFields 从 Keeper Commander CLI 提取结构化凭据数据 keeperDataFields开发工具CLI配置管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考