Bash heredoc 引号实战：生成配置时，哪些内容会被提前展开
脚本用 heredoc 写配置时，文件中本来应该保留的变量名却变成了当前环境的值，常见原因是结束标记没有引用。heredoc 并非简单的多行字符串，它是一种重定向结构，正文是否展开由标记的写法决定。本文在 Linux 与 Bash 5.2.37 执行，所有输出只写入新建的临时目录。
AI生成概念图：一组符号在开放通道中发生变化，另一组在边界内保持原样。仅作概念说明，不代表实际界面或实测数据。
先做两份内容相同的模板
下面两段正文完全相同，都包含变量、命令替换和算术表达式。第一段使用未引用的 EOF，第二段使用单引号包住的 EOF。示例中的命令只输出固定文字，便于安全观察；整段交给 Bash 执行，结束时清理刚创建的目录。
( set -eu work=$(mktemp -d) trap 'rm -rf -- "$work"' EXIT name=river cat > "$work/expanded.txt" <<EOF name=$name command=$(printf READY) number=$((2 + 3)) EOF cat > "$work/literal.txt" <<'EOF' name=$name command=$(printf READY) number=$((2 + 3)) EOF printf '%s\n' 'expanded:' cat "$work/expanded.txt" printf '%s\n' 'literal:' cat "$work/literal.txt" test "$(head -n 1 "$work/expanded.txt")" = 'name=river' test "$(head -n 1 "$work/literal.txt")" = 'name=$name' printf 'all checks passed\n' )
第一份得到 name=river、command=READY 和 number=5，说明正文已经由当前 shell 展开。第二份保留美元符号、括号和原始表达式。决定区别的是开头重定向位置的标记，而不是正文里有没有双引号，更不是文件扩展名。写成配置文件并不会阻止 shell 先处理它。
引用结束标记，正文就按字面传递
标记中只要有部分受到引用，Bash 会在去掉引用后确定真正的结束标记，并停止对正文做这些展开。用完整单引号包住标记最容易读懂。结束行仍写不带引号的 EOF，且不能在后面附加空格或注释；否则 shell 不会把它当成预期的结束位置。
如果正文自身可能出现独占一行的 EOF，就换一个不与内容冲突的标记。标记是文档边界，不是固定关键字。代码生成器、嵌套脚本和长配置尤其应检查这一点，否则后半段可能被当作外层 shell 命令解析，错误位置也会离真正原因很远。
需要插值时，先明确由哪一层负责
有些模板确实需要当前 shell 填入变量，这时未引用标记可以使用，但要逐个检查正文中的美元符号与命令替换。不要因为只想替换一个路径，就把整份复杂模板都交给不受控制的展开。对于结构化配置，更适合使用对应格式的生成工具，处理引号、换行和转义。
还有一个容易混淆的边界：变量值展开出来的文本不会自动再次作为 shell 源码执行。危险通常来自模板本身写了命令替换，或者后续又使用 eval 等方式重新解释内容。应避免追加这类二次解释，而不是依靠替换几个字符来声称模板安全。
缩进与字面输出分别验收
带减号的 heredoc 形式能够去掉行首制表符，但不会把普通空格当成相同的缩进。编辑器自动把制表符转成空格后，效果可能改变。为了让教程可以直接复制，示例将正文和结束标记都顶格放置，不依赖任何看不见的缩进字符。
生成完成后先读回文件，再交给目标程序的语法检查器。shell 成功退出，只能说明重定向与命令执行结束，不等于生成的配置符合目标格式。验收样本应包含空值、空格、反斜杠和需要保留的美元符号，核对字节内容，避免肉眼看终端时遗漏转义差异。
把“模板生成时展开”和“目标程序运行时解释”写进脚本注释，可以减少维护时的误改。如果下游程序还会处理占位符，就让那部分在生成阶段保持字面形式，并明确它最终由谁、在什么时候替换。每一层只负责自己的语法，生成文件才更容易预测。
