企业官网建设流程全解析

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

导读

chezmoi 的data子命令用于把**计算完成后的模板数据（template data）**以 JSON 或 YAML 格式输出到标准输出，是排查模板变量、调试.chezmoidata文件、验证配置文件data字段是否正确注入的首选工具。读完本文，你将掌握chezmoi data的完整用法、输出内容的结构与数据来源，并理解其背后的源码实现与合并顺序，从而在编写复杂 dotfiles 模板时快速定位数据问题。

命令概览：chezmoi data

在 commands/data.md 中，官方对这条命令的定义只有一句话：

Write the computed template data to stdout.

即：将计算后的模板数据写入标准输出。注意 "computed" 一词——它输出的不是原始配置，而是经过模板执行、多层数据合并之后的最终结果。

从源码看，data命令属于模板命令组（groupIDTemplate），且被标注为只读模式，不会修改持久化状态：

• 定义位置：datacmd.go
• 无参数（cobra.NoArgs），不做文件补全
• 注解persistentStateModeReadOnly，保证只读执行

// internal/cmd/datacmd.go dataCmd := &cobra.Command{ GroupID: groupIDTemplate, Use: "data", Short: "Print the template data", Args: cobra.NoArgs, RunE: c.runDataCmd, Annotations: newAnnotations( persistentStateModeReadOnly, ), }

基本用法

直接运行即可输出 JSON 格式的模板数据：

chezmoi data

以 YAML 格式输出：

chezmoi data --format=yaml

两种格式均支持长选项与短选项形式：

chezmoi data -f json chezmoi data -f yaml

-f/--format参数说明

| 参数 | 取值 | 默认值 | | - | - | - | |-f,--format|json|yaml|json|

根据 common-flags/format.md 的定义，该参数设置输出格式，默认是json。若传入非法值，源码中的marshal函数会直接报错：

// internal/cmd/config.go func (c *Config) marshal(dataFormat string, data any) error { var format chezmoi.Format switch dataFormat { case formatJSON: format = chezmoi.FormatJSON case formatYAML: format = chezmoi.FormatYAML default: return fmt.Errorf("%s: invalid format", dataFormat) } ... }

输出内容的结构

chezmoi data输出的顶层对象包含两类内容：

1. chezmoi键：由 chezmoi 自动注入的内置变量，例如chezmoi.config（当前配置的镜像）、chezmoi.sourceDir（源目录绝对路径）等；
2. 用户数据键：来自配置文件的data字段、.chezmoidata数据文件以及命令行/环境注入的数据。

从测试用例 datacmd_test.go 可以清楚地看到输出结构：配置文件中设置了data.test = true、mode: symlink、encryption: age后，chezmoi data输出中既包含chezmoi.config.age、chezmoi.sourceDir等内置字段，也包含顶层test字段（用户数据）。

测试还验证了一个细节：源码路径会被规范化处理，例如配置中的/my-age-identity会经chezmoi.NormalizePath标准化后再输出（见 datacmd_test.go）。

实际运行示例

$ chezmoi data { "chezmoi": { "config": { "mode": "symlink", "encryption": "age" }, "sourceDir": "/home/user/.local/share/chezmoi" }, "test": true }

$ chezmoi data --format=yaml chezmoi: config: mode: symlink encryption: age sourceDir: /home/user/.local/share/chezmoi test: true

（以上结构取自 datacmd_test.go 中测试配置的期望输出形态，实际字段取决于你的配置与机器环境。）

模板数据从何而来：多源合并

chezmoi data输出的数据并非单一来源，而是经过SourceState.TemplateData()按固定顺序递归合并（RecursiveMerge）的结果。从 sourcestate.go 的源码可以看到合并顺序：

// internal/chezmoi/sourcestate.go RecursiveMerge(s.templateData, s.defaultTemplateData) // 1. 默认数据（内置变量） RecursiveMerge(s.templateData, s.userTemplateData) // 2. 用户数据（配置 data 字段、.chezmoidata 文件等） RecursiveMerge(s.templateData, s.priorityTemplateData) // 3. 高优先级数据

数据来源包括：

| 来源 | 说明 | 依据 | | - | - | - | | 默认数据 | chezmoi 内置的chezmoi.*变量，由defaultTemplateDataFunc提供，惰性初始化（首次访问时计算一次） | sourcestate.go | | 用户数据 | 配置文件中的data字段，以及源目录中的.chezmoidata数据文件（读取逻辑见 sourcestate.go） | data.txtar | | 高优先级数据 | 通过WithPriorityTemplateData注入的数据（例如部分命令的交互式输入或环境变量） | sourcestate.go |

配置文件中的data字段

在 chezmoi 配置文件中可以通过data字段直接注入模板数据，支持 TOML、YAML、JSON 等所有配置格式。端到端测试 data.txtar 验证了这一行为：

# ~/.config/chezmoi/chezmoi.toml [data] uniqueKey = "uniqueValue"

运行chezmoi data后，输出中会出现：

"uniqueKey": "uniqueValue"

而--format=yaml则输出uniqueKey: uniqueValue。

.chezmoidata数据文件

除了配置文件，chezmoi 还支持在源目录中放置.chezmoidata.<format>数据文件（如.chezmoidata.json、.chezmoidata.toml、.chezmoidata.yaml）。从源码看，SourceState在遍历源目录时会识别名为.chezmoidata的文件（fileInfo.Name() == dataName）以及带格式后缀的变体（isPrefixDotFormat(fileInfo.Name(), dataName)），并读取其中内容合并进模板数据（sourcestate.go）。

模板数据在命令执行中的角色

data命令本身以WithTemplateDataOnly(true)的方式构建 SourceState，表示只需要模板数据、无需完整遍历源状态（datacmd.go）。而在普通模板渲染场景中，这份数据会被模板执行引擎使用，例如：

• 模板中通过{{ .chezmoi.hostname }}、{{ .email }}等引用数据；
• 执行模板数据时，chezmoi.sourceFile与chezmoi.targetFile会被临时注入（见 sourcestate.go）。

这也是chezmoi data输出的数据与模板中可用变量高度一致的原因——你可以在模板里放心使用chezmoi data能看到的所有键。

实战场景

1. 调试模板变量

模板渲染出错、变量值为空或类型不对时，先运行chezmoi data确认数据是否正确：

chezmoi data | jq '.email'

2. 以 YAML 检查复杂嵌套结构

嵌套较深的数据用 JSON 不易阅读，改用 YAML：

chezmoi data -f yaml

3. 配合脚本消费模板数据

由于输出是标准 stdout，可以轻松管道给其他工具：

chezmoi data --format=json | jq -r '.chezmoi.sourceDir'

4. 验证多机差异

在每台机器上运行chezmoi data并对比输出，可以直观检查hostname、os、arch等机器相关变量是否符合预期，辅助排查"同源不同机"的差异问题。

源码与测试速查

• 命令定义与执行逻辑：datacmd.go
• 输出格式校验与序列化：config.go
• 模板数据合并与拷贝：sourcestate.go
• 单元测试（JSON/YAML 输出结构验证）：datacmd_test.go
• 端到端测试（配置文件data字段注入）：data.txtar

小结

chezmoi data是查看 chezmoi 模板数据全貌的最快途径：json为默认输出格式，--format=yaml可切换为 YAML。理解其输出内容来自默认数据、用户数据与高优先级数据的三层递归合并，能帮助你准确预判模板中的变量取值；结合jq等工具，它完全可以作为日常调试 dotfiles 模板的"数据体检工具"。

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