写脚本这件事，写得越久越会发现一个尴尬的事实：单行注释用#谁都会，可一旦要临时屏蔽一整段逻辑、给一段复杂函数写使用说明、或者把调试代码整块"雪藏"起来，很多人就开始现场发挥——有人连敲十几行#，有人干脆把代码删了再靠记忆恢复，还有人用if false; then ... fi这种"伪注释"糊弄过去。shell脚本里的多行注释，看着是个小问题，实际上是个能把人坑到半夜的细节活。它没有统一标准，不同 shell 解释器行为还不完全一样，写法选错了轻则注释失效，重则脚本直接报语法错误跑不起来。
这篇内容就是围绕"shell 脚本中的多行注释"这个主题，把我这些年踩过的坑、验证过的写法、以及每种写法背后的取舍逻辑，一次性讲透。不管你是刚接触 shell 的新手，还是写了几年脚本但一直靠#硬怼的老手，都能从里面找到能直接抄作业的方案。核心会覆盖：heredoc 伪注释的原理与陷阱、: <<'EOF'这种主流写法的细节、if false方案的适用边界、注释块嵌套时的处理、以及不同 shell 环境下的兼容性差异。全程讲人话，配可直接复现的代码，重点解释"为什么这么写"而不是只给结论。
1. 先搞清楚：shell 为什么没有原生多行注释
1.1 单行注释的机制决定了没有"块注释"语法
要理解多行注释为什么在 shell 里这么别扭，得先回到 shell 解析器的工作方式。shell 是逐行读取、逐条执行的解释型语言，#的处理规则非常朴素：当#出现在一个词的起始位置（或者说前面是空白、行首、或者命令分隔符）时，从#到行尾的所有内容都被当作注释丢弃。注意这里的关键词是"到行尾"，也就是说#的注释作用域天然被换行符截断了。
这跟 C、Java、Python 那种有明确块级语法（/* */、""" """）的语言完全不同。shell 的语法设计里压根就没有"块"这个概念——它没有语句块的花括号语义（{}在 shell 里是命令组），也没有跨行的注释定界符。所以所谓"多行注释"，本质上都是借用其他语法结构来达到"这段内容不执行"的效果，是一种模拟，而不是语言特性。
这个认知很重要，因为它直接决定了后面所有方案的共同特点：它们都不是"真正的注释"，而是"让解释器把这段内容当成别的东西处理掉"。既然是借用，就一定有借用的代价和边界，理解这一点，你才不会在某个诡异场景下被反噬。
1.2 常见误区：把"不执行"等同于"被注释"
很多人有个思维定式：只要这段代码不运行，就等于注释掉了。这个理解在简单场景下没错，但在 shell 里会出问题。因为"不执行"和"被解析器忽略"是两码事。被#注释掉的内容，解析器根本不会去看它的语法；而用 heredoc 或if false包裹的内容，解析器仍然会解析它，只是不执行而已。
这个区别带来的直接后果是：如果你注释掉的代码块里含有不配对的引号、未闭合的括号、或者特殊字符，用#逐行注释是安全的，但用 heredoc 伪注释就可能报错。我见过太多人兴冲冲地用: <<'EOF'包了一大段含单引号的 SQL 语句，结果脚本直接unexpected EOF挂掉，排查半天才发现是引号配对问题。所以后面讲每种方案时，我都会明确标注它的"解析行为"，这是选型的第一依据。
2. 主流方案逐个拆：五种多行注释写法对比
2.1 方案一：逐行加#，最笨但最稳
这是最原始的做法，一行一个#。听起来很蠢，但它的优点恰恰是其他方案比不了的：绝对安全，零解析风险。因为每一行都被#截断，解析器压根不碰内容，无论里面有多少引号、反引号、$符号、括号，都不会出问题。
实际操作中，如果你用的是 vim，可以进入可视行模式（V）选中多行，然后:normal I#批量加注释，或者用:'<,'>s/^/#/正则替换。VS Code 里选中后Ctrl + /直接搞定。所以"逐行加"在编辑器辅助下并不算太痛苦。
它的真正短板在于可维护性：注释块一长，视觉上全是#，想恢复时得一行行删；而且如果注释块里本来就有#开头的行，恢复时容易误删。我的经验是，临时调试屏蔽用逐行#最省心，长期保留的说明性注释块则不适合，因为维护成本会随时间累积。
2.2 方案二：heredoc 伪注释，: <<'EOF'是主流
这是社区里流传最广的写法，核心结构是这样：
: <<'EOF' 这里是被"注释"掉的多行内容 可以随便写 echo "这行不会执行" EOF拆解一下原理。:是 shell 的内置命令，等价于true，它什么都不做，只返回成功状态码。<<'EOF'是 heredoc 重定向语法，意思是"把后续直到单独一行EOF为止的所有内容，作为标准输入喂给前面的命令"。于是整句话变成：把一大段文本喂给一个什么都不做的命令，文本被消费掉了，自然就不会被执行。
这里有个关键细节：<<'EOF'里的EOF加了单引号，这叫"引用式 heredoc"，作用是禁止变量展开和命令替换。如果不加引号写成<<EOF，那么注释块里的$变量、`命令`、$(命令)都会被真实求值——虽然结果被:丢弃了，但求值过程本身可能产生副作用（比如命令替换里的命令真的会执行），而且如果变量未定义还可能触发set -u报错。所以写 heredoc 伪注释，定界符一定要加引号，这是铁律。
定界符本身用什么词无所谓，EOF、COMMENT、END、__NOTE__都行，只要保证块内不会出现单独一行的同名标识即可。我习惯用__COMMENT__这种带下划线的，因为业务代码里几乎不可能出现，能最大程度避免"提前闭合"的意外。
2.3 方案三：if false; then ... fi，语义清晰但要注意解析
这个方案的思路很直白：把要注释的内容放进一个永远不成立的条件分支里。
if false; then echo "这段不会执行" rm -rf /tmp/something fi优点是语义极其清晰，任何人一眼就知道这是"故意不执行的代码"，比 heredoc 那种"看起来像注释其实是重定向"的写法更符合直觉。而且它天然支持嵌套（虽然嵌套if会让代码变丑），块内也可以正常写各种 shell 语法而不担心引号问题——因为它是合法的 shell 代码块，解析器本来就该解析它。
但要注意两个坑。第一，块内代码仍然会被完整解析，如果里面有语法错误（比如if没配对、函数定义不完整），脚本照样报错。第二，如果脚本开头有set -e，虽然if false分支不执行，但某些 shell 对条件判断的退出码处理有细微差异，实测在主流 bash 下没问题，但如果你追求极致稳妥，可以在块首加个:兜底。另外，用if false时块内的变量赋值、函数定义都不会生效，这点和真注释一致，可以放心。
2.4 方案四：函数包裹法，适合"归档"大段逻辑
还有一种偏门但好用的写法：把要注释的内容塞进一个从不调用的函数里。
_comment_block_20240101() { echo "归档的旧逻辑" do_something_old } # 注意：这个函数从不被调用这种写法的价值不在于"注释"，而在于归档——当你有一段逻辑暂时不用但又舍不得删，想留着以后参考时，包成函数比 heredoc 更好，因为函数体是合法语法，编辑器能正常高亮、能跳转、能静态检查，不会像 heredoc 那样把整块变成"字符串"导致语法高亮失效。缺点是函数定义本身会占用一点解析开销（微乎其微），而且如果函数名重复会覆盖，所以命名要带日期或版本号。
2.5 方案五：<<配合cat或read，不推荐但要知道
网上还能见到cat <<'EOF' > /dev/null ... EOF或者read -r -d '' _ <<'EOF' ... EOF这类变体。前者把内容重定向到/dev/null丢弃，后者读进一个丢弃变量。功能上能达到注释效果，但都比:方案多了一次无谓的 IO 或变量赋值，纯属画蛇添足。知道有这么回事即可，实际写脚本没必要用。
2.6 五种方案横向对比表
| 方案 | 解析安全性 | 块内含特殊字符 | 可读性 | 恢复便利度 | 推荐场景 |
|---|---|---|---|---|---|
逐行# | 最高 | 完全安全 | 一般 | 一般 | 临时调试屏蔽 |
: <<'EOF' | 高（需引号定界符） | 安全（引用式） | 较好 | 好 | 大段说明/临时屏蔽 |
if false | 中（块内需合法语法） | 安全 | 最好 | 好 | 语义化屏蔽 |
| 函数包裹 | 高 | 安全 | 好 | 好 | 长期归档旧逻辑 |
cat/read变体 | 高 | 安全 | 差 | 一般 | 不推荐 |
这张表是我选型的核心依据。日常写脚本，我的默认选择是：临时屏蔽用逐行#（编辑器批量操作），需要保留大段说明或屏蔽含复杂字符的代码块用: <<'__COMMENT__'，需要表达"这段逻辑故意停用"的语义用if false，长期归档用函数包裹。四种场景对应四种方案，没有银弹，关键是知道每种方案的边界在哪。
3. 实操细节：heredoc 伪注释的完整避坑指南
3.1 定界符的选择与"提前闭合"陷阱
heredoc 的结束条件是"遇到单独一行、内容完全等于定界符的行"。这里有两个容易翻车的点。第一，定界符必须独占一行且前后不能有多余空格（除非你用<<-配合 tab 缩进，但<<-只对 tab 生效，对空格无效，而大多数编辑器默认用空格缩进，所以<<-经常失效）。第二，如果注释块内部恰好有一行内容等于定界符，heredoc 会在这里提前闭合，后面的内容就变成真实代码执行了——这是最危险的情况，因为它不报错，只是行为诡异。
我的做法是定界符一律用__COMMENT_END__这种"业务代码里绝不可能出现"的字符串，并且养成习惯：写完 heredoc 块后，用grep -n "__COMMENT_END__" script.sh检查一下是不是只有预期的那一处。这个检查动作花不了两秒，但能避免一类极难排查的 bug。
3.2 引用式与非引用式定界符的行为差异实测
前面强调过定界符要加引号，这里给个实测对比，让你直观看到差异：
#!/bin/bash NAME="world" # 非引用式：变量会被展开 : <<EOF hello $NAME $(echo "命令替换也执行了") EOF # 引用式：原样保留，不求值 : <<'EOF' hello $NAME $(echo "这行不会执行") EOF跑一下就能看到，非引用式那段里$(echo ...)的命令替换真的执行了（虽然输出被丢弃），如果换成$(rm -rf xxx)这种破坏性命令，后果不堪设想。所以引用式定界符不是"建议"，是"必须"。这一点我在团队里做代码评审时是硬性检查项，见到<<EOF不带引号直接打回。
3.3 注释块里含单引号、反引号、$的处理
引用式 heredoc 的一个巨大优势是：块内所有字符都按字面量处理，不需要任何转义。这意味着你可以放心地在注释块里写 SQL（含单引号）、写正则（含反引号和$）、写 JSON（含双引号和花括号），完全不用担心。这比逐行#还省心，因为逐行#虽然也安全，但视觉上#会干扰内容本身的阅读。
不过有个例外要提醒：如果注释块里含有未配对的 heredoc 定界符（比如你注释掉的代码里本身也有<<EOF），那么外层 heredoc 的解析可能会被内层的EOF干扰。这种情况虽然罕见，但一旦遇到就是灾难。解决办法是外层定界符用足够独特的字符串，并且注释块内的 heredoc 尽量保持配对完整。
3.4 在函数内部和循环内部使用 heredoc 注释
heredoc 伪注释可以放在任何位置，包括函数体、循环体、case分支里，因为它本质是一条独立命令。但要注意缩进问题：如果 heredoc 块在if或for内部，块内容不需要缩进（缩进会被当成内容的一部分），只有: <<'EOF'这一行和EOF这一行需要跟随代码缩进。很多人为了让块内容对齐而给每行加空格，结果这些空格成了注释内容的一部分——虽然不影响功能，但看起来乱。我的建议是块内容顶格写，视觉上用空行和上下文隔开即可。
4. 兼容性与环境差异：不同 shell 下的表现
4.1 bash、sh、zsh、dash 的行为一致性
好消息是，: <<'EOF'和if false这两种主流方案在 bash、zsh、dash、以及 POSIX sh 下行为基本一致，因为它们用的都是 POSIX 标准语法。:是 POSIX 内置命令，heredoc 是 POSIX 特性，if更是基础中的基础。所以跨 shell 移植时，这两种方案最省心。
需要留意的是<<-（带 tab 缩进的 heredoc）在某些极简 shell 实现里支持不完整，以及函数包裹法在sh下如果用了 bash 特有的函数语法（如function name {}）会不兼容。所以如果你写的脚本要跑在/bin/sh环境（很多容器的默认 shell 是 dash），函数包裹法请用 POSIX 写法name() { ... }。
4.2set -e、set -u对注释块的影响
set -e（出错即退出）和set -u（未定义变量报错）是两个常见的严格模式开关，它们对注释块的影响值得单独说。对于: <<'EOF'引用式 heredoc，因为块内不求值，set -u完全不受影响，安全。对于if false方案，块内代码不执行，set -e也不会触发，安全。但如果用了非引用式 heredoc，块内的$UNDEFINED_VAR在set -u下会直接让脚本退出——这又是一个必须用引用式定界符的理由。
4.3 脚本被 source 时的特殊行为
如果你的脚本会被source（或.）加载而不是直接执行，那么注释块的处理要格外小心。source时整个文件在当前 shell 上下文里逐行执行，heredoc 伪注释依然有效（因为:命令照常执行），但如果注释块里有exit之类的命令且没被正确包裹，可能影响当前 shell。这也是为什么我倾向于在会被 source 的脚本里用if false或函数包裹，语义更明确，不容易误伤。
5. 常见问题排查速查表与实战心得
5.1 典型报错与对应原因
| 报错现象 | 最可能原因 | 解决方向 |
|---|---|---|
unexpected EOF while looking for matching | heredoc 定界符未闭合，或块内含未配对引号 | 检查定界符是否独占一行、块内引号是否配对 |
| 注释块后面的代码莫名不执行 | 定界符提前闭合，后续内容被吞 | 换更独特的定界符，grep 检查出现次数 |
bad substitution | 非引用式 heredoc 里含$特殊写法 | 定界符加单引号改为引用式 |
| 注释块内命令被执行了 | 用了<<EOF而非<<'EOF' | 加引号 |
syntax error near unexpected token | if false块内语法不完整 | 补全块内语法或改用 heredoc |
这张表基本覆盖了我遇到过的九成问题。其中"注释块后面的代码莫名不执行"是最阴险的，因为它不报错，只是静默吞掉后续内容，排查时容易怀疑到别的地方去。遇到这种"灵异现象"，第一反应就该是检查 heredoc 定界符。
5.2 我的三条实战心得
心得一：临时调试屏蔽，别用 heredoc，用逐行#。因为调试屏蔽是高频、短时的操作，编辑器批量加#一秒搞定，恢复也快。heredoc 适合"我要保留这段说明文字"或"我要长期屏蔽一大段含复杂字符的代码"，不适合频繁开关。
心得二：注释块也要写"为什么注释"。我见过太多脚本里躺着一大段被 heredoc 包起来的代码，没人知道为什么屏蔽、什么时候能恢复。正确做法是在: <<'EOF'上方加一行真注释，写明屏蔽原因和恢复条件，比如# 2024-01 旧版对账逻辑，等新接口上线后删除。这个习惯能救未来的自己和接手的人。
心得三：CI 里加一道注释块检查。如果团队脚本多，可以在 CI 里加个简单检查：grep -rn "<<EOF" scripts/找出所有非引用式 heredoc，人工确认是否该加引号。这个检查成本极低，但能拦住一类高危写法。
5.3 一个容易被忽略的细节：注释块与代码格式化的冲突
如果你用shfmt之类的格式化工具，heredoc 块的内容通常不会被格式化（工具会原样保留），这是好事。但if false块内的代码会被正常格式化，如果你不希望格式化工具动它，可以在块首加# shfmt: disable之类的指令（具体语法看工具版本）。这个细节在多人协作、统一格式化的项目里值得注意，否则你的"归档代码"可能被格式化得面目全非。
6. 选型决策：什么场景用什么写法
把前面的内容收束成一个可执行的决策逻辑。当你需要"注释掉多行"时，先问自己三个问题：这段内容是临时屏蔽还是长期保留？块内是否含有复杂特殊字符（引号、$、反引号）？这段代码未来是否需要快速恢复？
如果是临时屏蔽、块内字符简单、需要快速恢复——逐行#，编辑器批量操作最快。如果是长期保留的说明性文字或含复杂字符的代码块——: <<'__COMMENT_END__'，引用式定界符，块内容顶格写。如果是"这段逻辑故意停用"需要语义清晰——if false; then ... fi。如果是归档旧逻辑、希望保留语法高亮和可检索性——函数包裹，命名带日期。如果脚本要跨多种 shell 运行——优先:和if false这两种 POSIX 方案。
我个人在实际操作中的体会是，多行注释这件事没有"最佳实践"，只有"场景匹配"。真正让人踩坑的从来不是不会写，而是在错误的场景用了错误的方案——比如用非引用式 heredoc 屏蔽含$的代码导致命令被执行，或者用if false包裹语法不完整的代码导致报错。把每种方案的解析行为和边界记牢，比背十种写法都有用。最后再分享一个小技巧：无论用哪种方案，写完注释块后都跑一遍bash -n script.sh做语法检查，这个动作能拦住绝大多数"注释块没闭合"的低级错误，成本几乎为零，收益却很高。
