脚本仓库

这里存放可直接取用的脚本。每个脚本都是同一份文件，两种用途：页面上高亮展示源码，同时提供原文件下载。

目录约定

位置	作用
docs/public/scripts/	脚本原文件，会被原样发布，可直接下载
docs/scripts/	说明页面，负责讲解用法、展示源码

disk-report.sh —— 磁盘占用速览

快速查看指定目录下谁最占空间。只读操作，不修改、不删除任何文件。

用法

# 查看当前目录，默认显示前 10 项
./disk-report.sh

# 指定目录
./disk-report.sh ~/Documents

# 指定目录并显示前 20 项
./disk-report.sh ~/Documents 20

首次运行前记得赋予执行权限：

chmod +x disk-report.sh

输出示例

==============================================
 磁盘占用报告
 目标目录：/Users/admin/Documents
 生成时间：2026-08-31 18:20:14
==============================================

【总览】
文件系统      容量   已用   可用  使用率
/dev/disk3s5  460Gi  372Gi   88Gi    81%

【占用最多的 10 个子目录】
    12.4G  /Users/admin/Documents/Projects
     3.1G  /Users/admin/Documents/Design

源码

下面这段代码不是手抄的，而是用 <<< 语法从 public/scripts/disk-report.sh 实时引入的。脚本改了，这里自动跟着变，永远不会有"文档和文件对不上"的问题。

#!/usr/bin/env bash
#
# disk-report.sh —— 磁盘占用速览
#
# 用途：快速查看指定目录下谁最占空间，只读操作，不修改任何文件。
# 用法：./disk-report.sh [目录路径] [显示条数]
#
set -euo pipefail

TARGET_DIR="${1:-.}"
TOP_N="${2:-10}"

# 参数校验：目录必须存在
if [[ ! -d "$TARGET_DIR" ]]; then
    echo "错误：目录不存在 —— $TARGET_DIR" >&2
    exit 1
fi

# 参数校验：显示条数必须是正整数
if ! [[ "$TOP_N" =~ ^[0-9]+$ ]] || [[ "$TOP_N" -lt 1 ]]; then
    echo "错误：显示条数必须是正整数 —— $TOP_N" >&2
    exit 1
fi

echo "=============================================="
echo " 磁盘占用报告"
echo " 目标目录：$(cd "$TARGET_DIR" && pwd)"
echo " 生成时间：$(date '+%Y-%m-%d %H:%M:%S')"
echo "=============================================="
echo

echo "【总览】"
df -h "$TARGET_DIR" | awk 'NR==1 {print "文件系统      容量   已用   可用  使用率"} NR==2 {printf "%-12s %6s %6s %6s %6s\n", $1, $2, $3, $4, $5}'
echo

echo "【占用最多的 ${TOP_N} 个子目录】"
du -h -d 1 "$TARGET_DIR" 2>/dev/null \
    | sort -rh \
    | head -n $((TOP_N + 1)) \
    | tail -n +2 \
    | awk -F'\t' '{printf "%10s  %s\n", $1, $2}'

echo
echo "提示：想看更深的层级，把 du 的 -d 1 改成 -d 2 或 -d 3。"

下载

下载 disk-report.sh

这里用 withBase() 而不是直接写 /scripts/...，是为了让站点将来部署到子路径时，链接依然正确。它会自动把配置里的 base 拼到前面。

---

如何添加新脚本

三步，不用改配置：

1. 丢文件 —— 把 your-script.sh 放进 docs/public/scripts/
2. 建页面 —— 在 docs/scripts/ 下新建 your-script.md
3. 展示源码 —— 页面中写一行即可：

<<< @/public/scripts/your-script.sh

想突出某几行，在大括号里写行号：

<<< @/public/scripts/your-script.sh{15,16}

别用代码块包住它

<<< 是块级语法，外面不能套 ``` 围栏。套了就变成普通代码块，引入不会生效，页面上只会原样显示这行文本。这是最容易踩的一个坑。

下载按钮照抄上面的 <a> 标签，把文件名换掉即可。

引申：为什么用 <<< 而不是复制粘贴

文档最怕的不是写得差，而是和代码脱节。复制粘贴的那一刻两者就分家了，代码一改，文档就开始骗人，而骗人的文档比没有文档更糟。

<<< 让文档在构建时去读真实文件。这背后的原则值得记住：

凡是能被机器自动同步的信息，就不要靠人手动维护。