---
name: shell-scripting
description: Shell 脚本规范。用于本仓库脚本新增或修改时，保证路径安全、错误处理健壮、run.sh 行为一致。
---

# Shell 脚本规范

## 基础安全

- 脚本头使用：`#!/bin/bash`
- 默认开启：`set -euo pipefail`
- 错误输出到 `stderr`

## 路径规则

- 路径从脚本自身位置推导：

```bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
```

- 禁止依赖执行时 `pwd`
- 禁止硬编码脆弱相对路径（如裸 `../build`）
- 变量引用统一加双引号

## run.sh 约束

- 标准流程：构建 -> 停旧进程 -> 启动新进程
- 杀进程优先 `pgrep -x <name>` 精确匹配
- 禁止默认使用 `pgrep -f` 误杀
- `kill` 后短暂等待再启动，避免端口未释放

## 编写习惯

- 变量名使用大写下划线（如 `BUILD_DIR`）
- 函数内部变量用 `local`
- 新脚本创建后补 `chmod +x`