在 Linux 系统中，注释主要通过井号（#）实现单行注释，使用多行注释块（: ‘…’ 或 <<EOF … EOF）实现多段文本忽略，这是 Shell 脚本和配置文件中最基础的语法规范。
很多刚接触 Linux 的朋友在编写脚本或修改配置文件时，经常会被各种符号搞晕，Linux 的注释逻辑非常直观，它不像某些编程语言那样有复杂的块状语法，而是遵循“所见即所得”的简单原则，理解这些规则，不仅能让你写出更清晰的代码,还能避免因为误操作导致系统配置出错。
Shell 脚本中的单行注释规范
在 Bash、Zsh 等常见的 Linux Shell 环境中，注释的核心符号是井号（#），这个符号告诉解释器：“从这行开始，后面的内容都是给人看的，机器请忽略。”
基本语法与位置要求
单行注释的使用场景非常广泛，主要用于解释某一行命令的作用,或者临时屏蔽某段代码进行调试。
- 行首注释：这是最标准的写法，井号必须位于行的第一个非空白字符位置，如果前面有空格，解释器可能会把空格后的内容当作命令执行,从而报错。
- 行尾注释：你也可以在命令后面加上注释，用于解释该命令的参数。
ls -l # 列出详细信息，注意，井号前通常需要加一个空格,以便区分命令和注释。
常见误区与避坑指南
很多初学者容易犯的一个错误是在井号前没有处理好空格,或者在引号内误用了井号。
- 空格问题：如果写成
# comment（前面有空格），Shell 会尝试执行前面的空白或命令，导致command not found错误。 - 引号内的井号：在双引号或单引号字符串中，井号只是普通字符，不会被当作注释。
echo "#include <stdio.h>"，这里会打印出井号,而不是注释掉代码。
多行注释的高级技巧
Linux Shell 原生并没有像 C 语言那样标准的 多行注释块，通过一些巧妙的语法技巧，我们可以轻松实现多行注释的效果，业内专家指出，掌握这两种方法足以应对 99% 的场景。
使用冒号与单引号
这是最简洁、最推荐的多行注释方式，利用 Shell 中冒号（:）作为空命令的特性，配合单引号包裹多行文本,即可实现注释。
: ' 这是第一行注释 这是第二行注释在这里都会被忽略 '
- 原理：冒号是 Shell 的内建命令，它什么都不做，直接返回成功状态，单引号内的所有内容被视为一个参数传递给冒号,因此被忽略。
- 优点：语法简单，无需额外定义变量，兼容性好，几乎所有 Shell 都支持。
- 注意中不能包含单引号（’），否则会提前结束字符串，导致语法错误，如果必须包含单引号，可以使用双引号包裹，或者使用下面的 EOF 方法。
使用 Here Document（EOF）
中包含单引号，或者你需要注释大段包含变量的文本时，Here Document 是更好的选择。
<< 'COMMENT' 这里可以包含单引号 ' 也可以包含双引号 " 甚至包含反引号 ` COMMENT
- 原理：
<< 'COMMENT'告诉 Shell 读取直到遇到COMMENT为止的所有输入，并将其作为标准输入传递给前面的命令（默认为空命令或true）。 - 关键细节：引号的使用至关重要。
<< 'COMMENT'：单引号包裹分隔符，表示不展开变量和命令替换，这是做注释时的最佳实践，防止注释中的$VAR被误执行。<< COMMENT：无引号，表示
展开
变量，如果注释中写了$HOME，它会被替换为实际路径，虽然不影响执行，但会让注释内容变得混乱,不建议使用。
配置文件中的注释差异
除了 Shell 脚本，Linux 中的配置文件（如 /etc/nginx/nginx.conf、/etc/my.cnf 等）也广泛使用注释，虽然大部分遵循 规则,但不同格式的配置解析器可能有细微差别。
通用规则：井号优先
绝大多数基于文本的配置文件（INI, conf, properties 等）都使用 作为注释符。
- 行首注释：
# 这是 Nginx 的服务器名称 - 行尾注释：
server_name example.com; # 指定域名
特殊情况：YAML 与 JSON
随着云原生技术的发展，YAML 和 JSON 配置文件越来越常见。
- YAML：使用 进行注释，注意，YAML 对缩进非常敏感，注释必须与键值对保持正确的缩进层级,否则可能导致解析错误。
- JSON：标准 JSON 不支持注释，如果你需要在 JSON 中添加说明，通常需要使用非标准的注释扩展（如 JSONC），或者在代码层面通过注释文件处理，在 Linux 运维中，尽量避免在纯 JSON 配置中依赖注释,因为解析器会直接报错。
环境变量文件的注释
在 /etc/environment 或 .bashrc 等文件中，注释同样使用 。
- 示例：
# 设置 Java 路径 export JAVA_HOME=/usr/lib/jvm/java-11-openjdk
- 注意：在
.bashrc中，注释不会影响环境变量的加载,但能帮助你在未来修改配置时快速定位。
最佳实践与代码维护建议
注释不仅仅是为了“解释”，更是为了“沟通”，好的注释能让其他开发者（或三个月后的你自己）迅速理解代码意图。
原则
- 解释“为什么”，而非“是什么”：代码本身应该清晰易懂，如果代码已经说明了“做什么”，注释应解释“为什么这么做”，避免写
# 增加 1，而应写# 增加 1 以补偿时区差异。 - 保持更新：过时的注释比没有注释更糟糕，修改代码时,务必同步更新相关注释。
- 避免冗余：不要注释显而易见的代码。
x = 5 # 将 x 设为 5是无效的注释。
使用注释进行临时调试
在排查复杂脚本问题时,注释是强大的调试工具。
- 逐步屏蔽：如果脚本出错，可以逐行注释掉代码块,定位问题所在。
- 保存上下文：在重构代码前，将旧代码注释保留，而不是直接删除，这样可以在需要时快速恢复,同时保持代码库的整洁。
常见问题解答
Linux 如何注释多行代码
Linux Shell 没有原生的块注释语法，但可以通过 或 << 'EOF' ... EOF 实现，推荐使用 ，因为它简洁且兼容性好，注意注释内容中不要包含单引号，否则需改用 << 'EOF' 方式。
配置文件中的注释符号是什么
绝大多数 Linux 配置文件（如 Nginx、MySQL、SSH 配置）使用井号（#）作为注释符，YAML 文件也使用 #，但需注意缩进，JSON 标准不支持注释，如需注释需使用 JSONC 格式或在外部维护说明。
为什么我的注释会导致脚本报错
常见原因有三：一是井号前有多余空格，导致 Shell 尝试执行空格前的内容；二是多行注释中包含了未转义的单引号，导致字符串提前结束；三是在 JSON 等非注释支持格式中使用了 #，导致解析器无法识别,检查语法结构和引号匹配即可解决。
首发原创文章，作者：王坚，如若转载，请注明出处：https://idctop.com/article/468963.html
