跳到主要内容
Linux脚本库

脚本开发规范:script.yaml 字段与 body 约定

更新于 #脚本开发#script.yaml#参数类型#退出码#回滚

这份规范写给要投稿或维护脚本的人。它描述 script.yaml 与 body 片段怎么写,以及构建期会强制检查哪些规则——不满足就直接构建失败,脚本无法上线。

目录结构

src/content/scripts/<slug>/
├── script.yaml
└── body/
├── 10-check.sh
└── 20-main.sh
  • 目录名必须与 slug 一致,否则加载失败。
  • body/ 至少有一个 .sh 文件,所有片段按文件名排序后拼接;用 10-、20- 这类编号控制顺序。
  • 以 _ 开头的目录不会被加载,可以放模板。
  • 片段里不要写 shebang、set -eu、umask,这些由生成器统一注入;也不要重复定义公共函数。

script.yaml 字段

基本信息

字段 含义 约束
slug URL 与产物标识 小写字母/数字/连字符,2–48 位
title 标题 4–40 字
summary 一句话摘要 10–80 字,用于卡片和列表
intro 详情页引言 可选,最多 4 段,每段 10–500 字
category / subcategory 一级/二级分类 必须存在于分类注册表,二级分类还必须在所属分类下
tags 标签 1–10 个,每个不超过 16 字
version 版本号 语义化 x.y.z
status 状态 draft / beta / stable / deprecated
license 许可证 如 MIT
authors 作者 1–6 项,每项含 name,可选 url
updated 更新日期 YYYY-MM-DD
draft 草稿 为 true 时不参与构建与列表

兼容、运行与风险

字段 含义 约束
shell 脚本方言 posix 或 bash
distros 兼容矩阵 至少 1 项,每项 { id, min, max, tested };id 用 /etc/os-release 的发行版 ID
arch 支持架构 可选,如 x86_64、aarch64
requiresRoot / requiresNetwork 是否需要 root / 网络 布尔,必填
requiresTty 是否需要交互终端 布尔,可选
danger 危险等级 read / change / destructive
idempotent / dryRun 是否幂等 / 是否支持预演 布尔,必填
rollback 回滚声明 { supported, how };danger 不是 read 时必须 supported: true
changesPaths 改动路径 字符串数组,最多 20 项

参数、预设与文档

字段 含义 约束
params 参数定义 最多 20 个,key 唯一且小写字母开头
presets 预设组合 最多 12 个,key 唯一,只能引用已声明参数
faq 常见问题 可选,最多 10 条,q / a 问答对
related 相关脚本 可选,最多 8 个脚本 slug
references 外部参考 可选,最多 10 项,title / url 数组
seo SEO 覆盖 可选,title / description / keywords

8 种参数类型

类型 适合什么 校验与安全边界
enum 有限选项,如镜像站、模式 必须给 options,default 必须在其中,运行时再校验一次
bool 开关 渲染为 0 / 1,只接受这两种值
int 数量、阈值 用 min / max 限定范围,不接受小数
port 端口 整数,1–65535
path 绝对路径 以 / 开头,不允许空格、引号、反引号、$、反斜杠与 ..
url 下载地址 只接受 http(s),不允许空白、引号、反引号、$ 与反斜杠
hostname 主机名或 IP 校验主机名与 IPv4 格式
text 自由文本 拒绝换行与控制字符,默认限长 200,可用 max / pattern 收紧

原则是能用 enum 就不选 text:选项越少,运行时越不容易进到奇怪的分支。参数只作为数据,以 LM_<KEY> 变量形式注入,绝不拼进命令位置;不要设计“参数值本身就是一条命令”的参数。

body 片段约定

  • 可直接使用生成器注入的公共函数:die、log、warn、has_cmd、need_cmd、need_root、need_os_release、in_container、has_systemd。
  • 系统识别统一读 /etc/os-release 的 ID、ID_LIKE、VERSION_ID,不要读 /etc/redhat-release。
  • 变更前备份到 /var/backups/linuxmirror/<脚本 ID>/<时间戳>/,结束时打印回滚命令。
  • 并发保护用 flock;临时目录用 mktemp -d 加 trap 清理。
  • systemd 服务分 systemctl enable 和 systemctl start 两步操作。
  • 不自动执行 setenforce 0;默认不修改防火墙,只有显式要求时才按探测到的防火墙类型操作。
  • 重复执行应是 no-op;--dry-run 只打印改动,不写任何文件。
  • 网络下载使用 curl --proto '=https' --tlsv1.2 -fsSL --retry 3 --connect-timeout 5,不要加 -k。

参数变量与元信息

参数 key: format 会渲染成 LM_FORMAT='text',布尔值渲染成 LM_DETAIL='1' 或 '0'。生成器还会注入 LM_SCRIPT_ID、LM_SCRIPT_VERSION、LM_SCRIPT_BUILD、LM_DOC_URL,用于 banner 与文档链接。正文只引用这些变量,不要用 eval 展开。

退出码

退出码 含义 用法
0 成功 正常结束
1 通用失败 命令失败且无法归类时
2 用法错误 参数非法、缺少参数
3 环境不符 发行版不支持、缺依赖命令、没有 /etc/os-release
4 需要 root 未以 root 执行

统一用 die <退出码> "消息" 退出,错误消息写到 stderr。

构建期校验清单

以下任一项不满足,astro build 就会失败,脚本无法上线:

  • 分类与二级分类存在于注册表;
  • slug 与目录名一致,version 是 x.y.z;
  • 参数 key 唯一,且以小写字母开头;
  • enum 必须有 options,默认值在选项内;
  • 预设 key 唯一,只引用已声明参数,枚举值合法;
  • danger: destructive 必须 dryRun: true;
  • danger 不是 read 时必须声明 rollback.supported;
  • body/ 存在且至少有一个 .sh 文件。

参考

本文提到的脚本

输入关键词开始搜索。脚本名、发行版、分类、文档标题都会被索引。

↑↓ 选择 · Enter 打开浏览全部脚本