名称: shell 描述: Shell脚本编写最佳实践，用于编写安全、可移植、可维护的bash/sh脚本。在编写、审查或重构shell脚本、Dockerfile RUN命令、Makefile配方、CI管道脚本、cron作业或systemd ExecStart指令时使用。触发关键词：bash、sh、POSIX、ShellCheck、错误处理、引用、变量、set -euo pipefail。
Shell脚本最佳实践（社区版）
全面的shell脚本编写最佳实践指南，专为AI代理和LLMs设计。包含9个类别中的49条规则，按影响从关键（安全、便携性）到增量（风格）进行优先级排序。每条规则包括详细解释、现实世界示例比较错误与正确实现，以及具体影响指标。
何时应用
在以下情况参考这些指南：
- 编写新的bash或POSIX shell脚本
- 审查shell脚本以查找安全漏洞
- 调试静默失败或行为异常的脚本
- 在Linux、macOS和容器之间移植脚本
- 优化shell脚本性能
- 设置带有shell脚本的CI/CD管道
规则类别按优先级排序
| 优先级 | 类别 | 影响 | 前缀 | 规则数量 |
|---|---|---|---|---|
| 1 | 安全与安全性 | 关键 | safety- |
6 |
| 2 | 便携性 | 关键 | port- |
5 |
| 3 | 错误处理 | 高 | err- |
8 |
| 4 | 变量与数据 | 高 | var- |
5 |
| 5 | 引用与展开 | 中高 | quote- |
6 |
| 6 | 函数与结构 | 中 | func- |
5 |
| 7 | 测试与条件 | 中 | test- |
5 |
| 8 | 性能 | 低中 | perf- |
6 |
| 9 | 风格与格式化 | 低 | style- |
3 |
快速参考
1. 安全与安全性（关键）
safety-command-injection- 防止用户输入导致的命令注入safety-eval-avoidance- 避免使用eval执行动态命令safety-absolute-paths- 使用绝对路径调用外部命令safety-temp-files- 创建安全的临时文件safety-suid-forbidden- 切勿在shell脚本上使用SUID/SGIDsafety-argument-injection- 使用双破折号防止参数注入
2. 便携性（关键）
port-shebang-selection- 根据便携性需求选择shebangport-avoid-bashisms- 在POSIX脚本中避免bash特有功能port-printf-over-echo- 使用printf替代echo以提高便携性port-export-syntax- 使用便携的export语法port-test-portability- 使用便携的测试结构
3. 错误处理（高）
err-strict-mode- 使用严格模式检测错误err-exit-codes- 使用有意义的退出码err-trap-cleanup- 使用trap在退出时进行清理err-stderr-messages- 将错误消息发送到stderrerr-pipefail- 使用pipefail捕获管道错误err-check-commands- 显式检查命令成功err-shellcheck- 使用ShellCheck进行静态分析err-debug-tracing- 使用set -x和PS4进行调试追踪
4. 变量与数据（高）
var-use-arrays- 使用数组替代字符串处理列表var-local-scope- 在函数中使用local声明局部变量var-naming-conventions- 遵循变量命名约定var-readonly-constants- 使用readonly声明常量var-default-values- 使用参数展开设置默认值
5. 引用与展开（中高）
quote-always-quote-variables- 始终引用变量展开quote-dollar-at- 使用"$@"传递参数quote-command-substitution- 引用命令替换quote-brace-expansion- 使用花括号提高变量清晰度quote-here-documents- 使用here文档处理多行字符串quote-glob-safety- 显式控制通配符展开
6. 函数与结构（中）
func-main-pattern- 使用main()函数模式func-single-purpose- 编写单一用途的函数func-return-values- 正确使用返回值func-documentation- 使用头部注释文档化函数func-avoid-aliases- 优先使用函数而非别名
7. 测试与条件（中）
test-double-brackets- 在bash中使用[[ ]]进行测试test-arithmetic- 使用(( ))进行算术比较test-explicit-empty- 使用显式的空/非空字符串测试test-file-operators- 使用正确的文件测试操作符test-case-patterns- 使用case进行模式匹配
8. 性能（低中）
perf-builtins-over-external- 使用内置命令替代外部命令perf-avoid-subshells- 避免不必要的子shellperf-process-substitution- 使用进程替换处理临时文件perf-read-files- 高效读取文件perf-parameter-expansion- 使用参数展开进行字符串操作perf-batch-operations- 批量操作替代循环
9. 风格与格式化（低）
style-indentation- 使用一致的缩进style-file-structure- 遵循一致的文件结构style-comments- 编写有用的注释
如何使用
阅读单独的参考文件以获取详细解释和代码示例：
参考文件
| 文件 | 描述 |
|---|---|
| AGENTS.md | 完整的编译指南，包含所有规则 |
| references/_sections.md | 类别定义和排序 |
| assets/templates/_template.md | 新规则的模板 |
| metadata.json | 版本和参考信息 |