Shell脚本最佳实践指南：49条规则提升安全性、可移植性与错误处理

shell by pproenca/dot-skills

251 周安装量

91 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/pproenca/dot-skills --skill shell

代码规范命令行工具安全

🇨🇳中文介绍

Shell 脚本最佳实践（社区版）

专为 AI 代理和 LLM 设计的全面 Shell 脚本最佳实践指南。包含 9 大类共 49 条规则，按影响程度从关键（安全性、可移植性）到渐进（风格）进行优先级排序。每条规则都包含详细解释、对比错误与正确实现的真实示例，以及具体的影响指标。

适用场景

在以下情况下参考本指南：

编写新的 bash 或 POSIX shell 脚本时
审查 shell 脚本是否存在安全漏洞时
调试静默失败或行为异常的脚本时
在 Linux、macOS 和容器之间移植脚本时
优化 shell 脚本性能时
使用 shell 脚本设置 CI/CD 流水线时

按优先级划分的规则类别

优先级	类别	影响程度	前缀	规则数量
1	安全与防护	关键	`safety-`	6
2	可移植性	关键	`port-`	5

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

1. 安全与防护（关键）

safety-command-injection - 防止来自用户输入的命令注入
safety-eval-avoidance - 避免使用 eval 执行动态命令
safety-absolute-paths - 为外部命令使用绝对路径
safety-temp-files - 创建安全的临时文件
safety-suid-forbidden - 切勿在 shell 脚本上使用 SUID/SGID
safety-argument-injection - 使用双破折号防止参数注入

2. 可移植性（关键）

port-shebang-selection - 根据可移植性需求选择 shebang
port-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 - 将错误信息发送到 stderr
err-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 documents
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 - 避免不必要的子 shell
perf-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	版本和参考信息

🇺🇸English

Shell Scripts Best Practices (Community)

Comprehensive best practices guide for shell scripting, designed for AI agents and LLMs. Contains 49 rules across 9 categories, prioritized by impact from critical (safety, portability) to incremental (style). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics.

When to Apply

Reference these guidelines when:

Writing new bash or POSIX shell scripts
Reviewing shell scripts for security vulnerabilities
Debugging scripts that fail silently or behave unexpectedly
Porting scripts between Linux, macOS, and containers
Optimizing shell script performance
Setting up CI/CD pipelines with shell scripts

Rule Categories by Priority

Priority	Category	Impact	Prefix	Rules
1	Safety & Security	CRITICAL	`safety-`	6
2	Portability	CRITICAL	`port-`	5
3	Error Handling	HIGH	`err-`	8
4	Variables & Data	HIGH	`var-`	5
5	Quoting & Expansion	MEDIUM-HIGH	`quote-`	6
6	Functions & Structure	MEDIUM	`func-`	5
7	Testing & Conditionals	MEDIUM	`test-`	5
8	Performance	LOW-MEDIUM	`perf-`	6
9	Style & Formatting	LOW	`style-`	3

Quick Reference

1. Safety & Security (CRITICAL)

safety-command-injection - Prevent command injection from user input
safety-eval-avoidance - Avoid eval for dynamic commands
safety-absolute-paths - Use absolute paths for external commands
safety-temp-files - Create secure temporary files
safety-suid-forbidden - Never use SUID/SGID on shell scripts
safety-argument-injection - Prevent argument injection with double dash

2. Portability (CRITICAL)

port-shebang-selection - Choose shebang based on portability needs
port-avoid-bashisms - Avoid bashisms in POSIX scripts
port-printf-over-echo - Use printf instead of echo for portability
port-export-syntax - Use portable export syntax
port-test-portability - Use portable test constructs

3. Error Handling (HIGH)

err-strict-mode - Use strict mode for error detection
err-exit-codes - Use meaningful exit codes
err-trap-cleanup - Use trap for cleanup on exit
err-stderr-messages - Send error messages to stderr
err-pipefail - Use pipefail to catch pipeline errors
err-check-commands - Check command success explicitly

4. Variables & Data (HIGH)

var-use-arrays - Use arrays for lists instead of strings
var-local-scope - Use local for function variables
var-naming-conventions - Follow variable naming conventions
var-readonly-constants - Use readonly for constants
var-default-values - Use parameter expansion for defaults

5. Quoting & Expansion (MEDIUM-HIGH)

quote-always-quote-variables - Always quote variable expansions
quote-dollar-at - Use "$@" for argument passing
quote-command-substitution - Quote command substitutions
quote-brace-expansion - Use braces for variable clarity
quote-here-documents - Use here documents for multi-line strings
quote-glob-safety - Control glob expansion explicitly

6. Functions & Structure (MEDIUM)

func-main-pattern - Use main() function pattern
func-single-purpose - Write single-purpose functions
func-return-values - Use return values correctly
func-documentation - Document functions with header comments
func-avoid-aliases - Prefer functions over aliases

7. Testing & Conditionals (MEDIUM)

test-double-brackets - Use [[ ]] for tests in bash
test-arithmetic - Use (( )) for arithmetic comparisons
test-explicit-empty - Use explicit empty/non-empty string tests
test-file-operators - Use correct file test operators
test-case-patterns - Use case for pattern matching

8. Performance (LOW-MEDIUM)

perf-builtins-over-external - Use builtins over external commands
perf-avoid-subshells - Avoid unnecessary subshells
perf-process-substitution - Use process substitution for temp files
perf-read-files - Read files efficiently
perf-parameter-expansion - Use parameter expansion for string operations
perf-batch-operations - Batch operations instead of loops

9. Style & Formatting (LOW)

style-indentation - Use consistent indentation
style-file-structure - Follow consistent file structure
style-comments - Write useful comments

How to Use

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

Reference Files

File	Description
AGENTS.md	Complete compiled guide with all rules
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

Key Sources

Weekly Installs

218

Repository

pproenca/dot-skills

GitHub Stars

First Seen

Jan 22, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex187

gemini-cli184

opencode184

github-copilot177

cursor170

amp158

xdrop 文件传输脚本：Bun 环境下安全上传下载工具，支持加密分享

28,800 周安装

err-shellcheck - Use ShellCheck for static analysis

err-debug-tracing - Use debug tracing with set -x and PS4