别再发截图了！用这一行命令，让你的终端代码“动”起来
简介
- asciinema: 一个轻量级、纯文本的终端录制工具。它不录制视频，而是记录终端的输入输出文本流（
.cast文件），因此体积非常小，且可以在网页上以文本形式复制。 - agg (asciinema gif generator): 一个基于 Rust 编写的高性能工具，用于将 asciinema 录制的
.cast文件转换为高质量的 GIF 动图。
第一部分：asciinema (录制工具)
官方网站为：https://asciinema.org/ ，项目主页：https://github.com/asciinema
1. 安装 (Installation)
macOS
使用 Homebrew 安装：
brew install asciinema
Linux
大多数发行版的仓库中都包含 asciinema。
-
Ubuntu/Debian:
sudo apt install asciinema -
Arch Linux:
sudo pacman -S asciinema -
Fedora:
sudo dnf install asciinema
Windows
Windows 有两种主要方式：
-
使用 Python (推荐，适用于 PowerShell/CMD):
如果你安装了 Python，直接使用 pip 安装：pip install asciinema -
WSL (Windows Subsystem for Linux):
在 WSL (Ubuntu) 中，参考上述 Linux 安装方法。这是体验最好的方式，因为通过 WSL 录制的 Shell 环境更标准。
2. 基础使用 (Usage)
开始录制
最简单的录制命令：
asciinema rec demo.cast
- 如果不指定文件名，asciinema 会生成一个临时文件，并在结束时询问你是否上传。
- 输入命令后，你会看到提示 "recording started"，此时你在终端的所有操作都会被记录。
结束录制
有两种方式结束录制：
- 输入
exit命令。 - 按下快捷键
Ctrl + D。
退出时会提示是否保存到本地还是上传到 https://asciinema.org 网站，不涉及隐私内容可上传到网站得到分享连接 分享给其他用户（通过在线播放，方便复制命令以及控制播放）。
例如生成的在线链接地址：
https://asciinema.org/a/HOyLKG6awFjQr9TqPEsBhiPMn
主要针对于 依赖包和源码包分开打包的场景，需要修改源码包中的 MANIFEST.MF文件
而且官方提供多种方式很容易嵌入到自己对网站使用。
我们可以使用以下参数控制播放：
| 参数 | 说明 | 默认值 |
|---|---|---|
| t | 控制开始时间，可用格式有 ss，mm:ss，hh:mm:ss | 0 |
| autoplay | 是否自动开始播放，如果指令了开始时间 t，则默认为自动播放 | 0 |
| loop | 是否循环播放 | 0 |
| speed | 播放速度，如果是 2 代表 2 倍速度 | 1 |
| theme | 终端界面样式，可用样式有： asciinema、tango、solarized-dark、solarized-light、monokai | asciinema |
| cols | 终端界面宽度 | 默认为用户录制时界面的 width |
| rows | 终端界面高度 | 默认为用户录制界面的 height |
| preload | 是否预加载 | asciinema.org 站内使用是 1，站外调用为 0 |
如以下连接：从第 5 s开始的3被速度播放
https://asciinema.org/a/HOyLKG6awFjQr9TqPEsBhiPMn?t=5&speed=3&theme=solarized-dark
回放录制
在本地终端查看刚才录制的效果：
asciinema play demo.cast
- 你可以随时按
空格键暂停/继续。 - 按
Ctrl + C退出回放。
常用参数
-
覆盖空闲时间 (
-i): 如果你在录制时发呆了 10 秒，回放时不想让观众等。# 将所有超过 2 秒的停顿压缩为 2 秒 asciinema rec -i 2 demo.cast -
追加录制 (
--append): 接着上次的内容继续录。asciinema rec --append demo.cast -
覆盖文件 (
--overwrite): 如果文件已存在，直接覆盖。asciinema rec --overwrite demo.cast
第二部分：agg (GIF 转换工具)
虽然 asciinema 官方提供了网页播放器，但在 Github Readme 或文章中，GIF 仍然是最通用的格式。agg 是目前效果最好的转换器。
1. 安装 (Installation)
macOS
brew install agg
Linux / Windows / macOS (通用方法)
由于 agg 是用 Rust 编写的，最好的安装方式是下载预编译的二进制文件，或者使用 Cargo。
方法 A: 下载二进制文件 (推荐新手)
- 访问 Github Releases 页面: https://github.com/asciinema/agg/releases
- 下载对应系统的压缩包：
- Linux:
agg-x86_64-unknown-linux-gnu - Windows:
agg-x86_64-pc-windows-msvc.exe - macOS:
agg-aarch64-apple-darwin(M1/M2) 或x86_64(Intel)
- Linux:
- 解压并将可执行文件放入你的系统 PATH 路径中（例如 Linux/Mac 的
/usr/local/bin，Windows 需手动添加环境变量）。 - linux / mac /windows 在 WSL (Windows Subsystem for Linux) 下使用：
#curl -L https://github.com/asciinema/agg/releases/latest/download/agg-x86_64-unknown-linux-gnu -o agg
wget https://github.com/asciinema/agg/releases/latest/download/agg-x86_64-unknown-linux-gnu -O agg
chmod +x agg
sudo mv agg /usr/local/bin/
方法 B: 使用 Cargo (如果你是 Rust 开发者)
cargo install agg
2. 详细使用教程 (Usage)
基础转换
将录制好的 .cast 文件转换为 .gif：
agg demo.cast demo.gif
转换完成后，你就可以打开 demo.gif 查看效果了。
进阶美化 (Customization)
agg 强大的地方在于它允许你自定义 GIF 的外观，而无需重新录制。
1. 设置字体大小 (--font-size)
默认字体可能较小，适合网页展示通常需要调大：
agg --font-size 20 demo.cast demo.gif
2. 设置主题 (--theme)
agg 内置了多种配色方案，如 monokai, solarized-dark, dracula, github-light 等。
agg --theme dracula demo.cast demo.gif
提示：如果不指定，它默认使用 asciinema 的默认暗色主题。
3. 调整播放速度 (--speed)
嫌录制时打字太慢？或者演示太快看不清？
# 2倍速播放 且将所有超过 1.5秒的停顿压缩为 1.5秒
agg --speed 2 --idle-time-limit 1.5 demo.cast demo.gif
# 0.5倍速 (慢放) 且将所有超过 1.5秒的停顿压缩为 1.5秒
agg --speed 0.5 --idle-time-limit 1.5 demo.cast demo.gif
4. 指定字体 (--font-family)
你可以使用系统内安装的任何等宽字体（Nerd Fonts 也可以，这样可以显示图标）。
# Windows/Linux 示例
# linux 如果没有字体，可以换成 Liberation Mono 等系统安装的字体
agg --font-family "JetBrains Mono" demo.cast demo.gif
# macOS 示例
agg --font-family "Menlo" demo.cast demo.gif
5. 调整行数和列数 (--rows, --cols)
强制裁剪或扩展画面的大小。
agg --rows 20 --cols 80 demo.cast demo.gif
6. 去除窗口装饰 (--no-loop)
默认情况下 GIF 是循环播放的。如果你不想循环：
agg --no-loop demo.cast demo.gif
3. 账户绑定 (管理云端录像)
如果你把录像上传到了 asciinema.org，你需要认领这些录像以便管理（删除、修改标题）。
-
运行认证命令：
Bash
asciinema auth -
终端会显示一个以
https://asciinema.org/connect/开头的长链接。 -
在浏览器中打开该链接，登录你的邮箱，即可将当前的终端环境与你的账户绑定。
-
绑定后，你所有从这台机器上传的录像都会自动归入你的账户。
4. 进阶使用场景
A. 追加录制 (Append)
如果你发现刚才录制少了一段，可以接着录：
Bash
asciinema rec --append existing_demo.cast
B. 嵌入到网页 (JS 播放器)
如果你想在个人博客中以“播放器”形式展示（不仅是 GIF 图片），可以使用官方的 JS 播放器：
HTML
<script src="https://asciinema.org/a/你的录像ID.js" id="asciicast-你的录像ID" async></script>
第三部分：完整工作流演示 (Best Practices)
假设你要演示如何在终端中安装一个 Node.js 包，并生成一个漂亮的 GIF 放在 Readme 中。
第一步：准备录制
打开你的终端，准备好环境。
第二步：录制 (带空闲压缩)
运行以下命令开始：
asciinema rec -i 2 install-demo.cast
- 执行演示操作：
npm install axios - 等待完成。
- 按
Ctrl+D结束。
第三步：预览检查
asciinema play install-demo.cast
检查有没有拼写错误，或者不想展示的敏感信息（虽然 agg 不能剪辑内容，如果错了建议重录，因为成本很低）。
第四步：生成高颜值 GIF
我们希望字体大一点，使用 Dracula 主题，并且速度稍微快一点：
agg --theme dracula --font-size 24 --speed 1.5 --font-family "JetBrains Mono" install-demo.cast output.gif
综合实战示例
假设你录制了一个名为 install_demo.cast 的文件，现在你想生成一个放在 GitHub Readme 上的演示图。你希望：
- 字体清晰（使用 "Fira Code"）。
- 字体稍微大一点（20px）。
- 去除我思考时的长停顿（限制空闲时间为 1 秒）。
- 稍微加快一点节奏（1.5倍速）。
- 使用深色主题（Solarized Dark）。
完整命令如下：
agg --font-family "Fira Code" \
--font-size 20 \
--idle-time-limit 1 \
--speed 1.5 \
--theme solarized-dark \
install_demo.cast \
output.gif
第五步：查看结果
在文件管理器中打开 output.gif，你将看到一个清晰、配色优美且进度流畅的终端演示动图。
一键录制脚本
一个简单的 Shell 脚本，能够一键完成“录制 -> 自动转 GIF -> 自动压缩体积”的全流程？ 这样就不需要每次都敲一堆参数了
脚本内容：record_gif.sh
请将以下代码保存为 record_gif.sh。
#!/bin/bash
# =============================================================================
# 脚本名称: record_gif.sh
# 描述: 一站式终端录制、转换 GIF 及按需压缩工具
# 依赖: asciinema, agg, gifsicle (可选)
# =============================================================================
# --- 1. 配置区域 (默认设置) ---
DEFAULT_FILENAME="demo"
IDLE_LIMIT=2 # 录制时最大空闲时间(秒)
THEME="dracula" # agg 渲染主题
FONT_SIZE=20 # 字体大小
SPEED=1.5 # 播放倍速
# 留空则 agg 会使用其内置的默认字体
FONT_FAMILY="Liberation Mono" # 字体 (如果系统没有 Liberation Mono 字体，可以将其置空字符串，agg 会回退到默认)
# --- 2. 颜色定义 (用于美化输出) ---
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# --- 3. 辅助函数 ---
log_info() {
echo -e "${BLUE}[INFO]${NC} $1"
}
log_success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}
log_warn() {
echo -e "${YELLOW}[WARN]${NC} $1"
}
log_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
check_dependency() {
if ! command -v "$1" &> /dev/null; then
log_error "未找到命令: $1"
echo "请先安装它。例如 (macOS): brew install $1"
exit 1
fi
}
# --- 4. 环境检查 ---
log_info "正在检查环境依赖..."
check_dependency "asciinema"
check_dependency "agg"
# gifsicle 是可选的，但在压缩阶段会再次检查
# --- 5. 参数解析 ---
# 如果用户提供了参数，将其作为基本文件名
BASENAME="${1:-$DEFAULT_FILENAME}"
CAST_FILE="${BASENAME}.cast"
GIF_FILE="${BASENAME}.gif"
OPT_GIF_FILE="${BASENAME}_optimized.gif"
# --- 6. 开始录制 (asciinema) ---
echo "----------------------------------------------------"
log_info "准备开始录制。文件将保存为: ${CAST_FILE}"
log_info "按下 ${YELLOW}Ctrl + D${NC} 或输入 ${YELLOW}exit${NC} 结束录制。"
log_info "最大空闲时间已限制为: ${IDLE_LIMIT}秒"
echo "----------------------------------------------------"
# 等待用户按键开始
read -p "按 [Enter] 键开始录制..."
# 执行录制
# -y: 覆盖已存在文件
# -i: 压缩空闲时间
asciinema rec -y -i "$IDLE_LIMIT" "$CAST_FILE"
if [ $? -ne 0 ]; then
log_error "录制异常退出。"
exit 1
fi
echo ""
log_success "录制完成: ${CAST_FILE}"
# --- 7. 转换为 GIF (agg) ---
log_info "正在渲染 GIF (Theme: $THEME, Speed: $SPEED)..."
FONT_ARG=""
if [ -n "$FONT_FAMILY" ]; then
FONT_ARG="--font-family $FONT_FAMILY"
fi
agg --theme "$THEME" \
--font-size "$FONT_SIZE" \
$FONT_ARG \
--speed "$SPEED" \
"$CAST_FILE" "$GIF_FILE"
if [ $? -ne 0 ]; then
log_error "GIF 转换失败。"
exit 1
fi
log_success "GIF 生成完毕: ${GIF_FILE}"
# --- 8. 压缩决策 (Gifsicle) ---
# 获取当前文件大小
FILE_SIZE=$(du -h "$GIF_FILE" | cut -f1)
log_info "当前 GIF 文件大小: ${YELLOW}${FILE_SIZE}${NC}"
# 检查是否有 gifsicle
if ! command -v gifsicle &> /dev/null; then
log_warn "未检测到 gifsicle，跳过压缩步骤。"
log_info "您可以手动安装: brew install gifsicle"
exit 0
fi
echo "----------------------------------------------------"
read -p "❓ 是否要压缩 GIF 体积? (推荐用于 Web/Github) [y/N]: " COMPRESS_CHOICE
if [[ "$COMPRESS_CHOICE" =~ ^[Yy]$ ]]; then
log_info "正在使用 gifsicle 进行高压缩 (Level 3, 256 colors)..."
gifsicle -O3 --colors 256 "$GIF_FILE" -o "$OPT_GIF_FILE"
if [ $? -eq 0 ]; then
OLD_SIZE=$(du -k "$GIF_FILE" | cut -f1)
NEW_SIZE=$(du -k "$OPT_GIF_FILE" | cut -f1)
READABLE_NEW_SIZE=$(du -h "$OPT_GIF_FILE" | cut -f1)
# 计算压缩率
SAVED=$(( 100 - (NEW_SIZE * 100 / OLD_SIZE) ))
log_success "压缩完成！"
log_success "新文件: ${OPT_GIF_FILE} (${READABLE_NEW_SIZE})"
log_success "体积减少了约: ${SAVED}%"
# 询问是否覆盖原文件
read -p "是否用压缩版覆盖原版 GIF? [y/N]: " OVERWRITE_CHOICE
if [[ "$OVERWRITE_CHOICE" =~ ^[Yy]$ ]]; then
mv "$OPT_GIF_FILE" "$GIF_FILE"
log_success "已覆盖原文件: ${GIF_FILE}"
else
log_info "保留了两个版本。"
fi
else
log_error "压缩过程中出错。"
fi
else
log_info "已跳过压缩。"
fi
echo "----------------------------------------------------"
log_success "所有任务完成！👋"
使用教程
1. 赋予执行权限
在终端中运行一次即可：
Bash
chmod +x record_gif.sh
2. 运行脚本
场景 A：直接运行（使用默认文件名 demo）
Bash
./record_gif.sh
场景 B：指定文件名 如果你想生成 install_guide.gif：
Bash
./record_gif.sh install_guide
3. 脚本执行流程演示
- 环境检查：脚本会先看你有没有安装
asciinema和agg。 - 录制：按下回车后开始录制。脚本会自动设置
--idle-time-limit 2，这意味着你发呆 10 秒，录像里只会显示 2 秒。 - 渲染：录制结束后，自动调用
agg生成高清 GIF。 - 交互式压缩：
- 脚本会显示当前 GIF 大小（例如
5.2M）。 - 询问：
❓ 是否要压缩 GIF 体积? [y/N] - 如果你选
y，它会调用gifsicle进行优化，并计算出减少了多少体积（例如体积减少了约: 45%）。 - 最后询问是否覆盖原文件。
- 脚本会显示当前 GIF 大小（例如
常见问题 (FAQ)
1. Windows 下 PowerShell 字体乱码怎么办？
确保你在 PowerShell 属性中设置了支持中文和特殊符号的字体（如 "MesloLGS NF" 或 "Cascadia Code"）。在使用 agg 生成时，务必加上 --font-family "你的字体名称"。
2. 生成的 GIF 体积太大怎么办？
GIF 格式本质上体积较大。
- 尝试减小
--font-size。 - 减少录制时长。
- 使用
--speed加速播放。 - 如果必须极小体积，考虑直接使用 asciinema 的网页嵌入代码（Embed），而不是转 GIF。
3. 如何在 GIF 中显示 Shell 的图标（如 Starship/Oh-my-zsh）？
你需要确保运行 agg 的机器上安装了对应的 Nerd Font，并在生成时通过 --font-family 指定该 Nerd Font。否则图标会显示为方框。
4. 想要 mp4 格式而不是 GIF？
agg 专注于 GIF。如果你需要 mp4，可以使用 ffmpeg 将生成的 gif 转为 mp4，或者寻找其他工具（如 vhs，这是另一个基于脚本的录制工具，也很强大）。
5. GIF 文件过大怎么办？
agg 生成的是高质量 GIF，没有经过有损压缩，文件通常较大。建议在生成后使用 gifsicle 进行压缩。
-
安装 gifsicle:
brew install gifsicle或apt install gifsicle -
压缩命令:
Bash
# 优化级别 3 (最高)，并将颜色减少到 256 色或是更少以减小体积 gifsicle -O3 --colors 256 < output.gif > output_optimized.gif
Q.E.D.
