asciinema 3.2.1 命令与运维实战

目标：以 Ubuntu 22.04.5 LTS 服务器为操作面，完整走通 asciinema 的录制、文件解析、回放、格式加工与托管分享全链路，沉淀可直接复用的命令链与排障经验。本文命令于 2026-10-28 实测（v3.2.1 与 v2.1.0 双版本并存，asciinema3 指 v3、asciinema 指 v2），回显均为真实输出；受无交互终端限制无法直接验证的命令，均给出「命令 + 预期结果」并明确标注。

一、命令体系总览

1.1 两代子命令对照

v3.2.1（asciinema3 --help 实测）共 8 个子命令；v2.1.0 仅 5 个。对照如下：

1.2 版本判别与命令选择

双版本并存环境先判别再操作：

$ asciinema --version && asciinema3 --version
asciinema 2.1.0
asciinema 3.2.1

原则：交互式人工录制用哪个都行，自动化脚本一律用 v3（headless 能力、--return 退出码透传、稳定输出格式都是脚本需要的）；历史遗留脚本若依赖 v2 cat 的「打印原始输出」行为，迁移时改用 asciinema3 convert -f raw。

二、录制命令链

2.1 基础录制

交互终端中最简单的录制：

$ asciinema3 rec demo.cast -t "v3-demo"

结束方式：按 ctrl+d 或输入 exit；录制中途按 ctrl+\ 可暂停/恢复捕获（rec --help 原文：Press ctrl+\ to pause/resume capture of the session），适合录制过程中整理思路再继续。默认情况下目标文件已存在时 v3 会拒绝写入（防误覆盖），实测覆盖需显式加 --overwrite。

指定被录命令而不进子 shell：

$ asciinema3 rec demo.cast -c "bash -c 'echo hello; uname -r'"

2.2 常用选项组合（实测）

$ asciinema3 rec build.cast -c "./build.sh" --title "构建演示" --idle-time-limit 2

高频选项（全部来自 rec --help 实测原文）：

• -c, --command <COMMAND>：录制指定命令而非默认 shell；
• -t, --title <TITLE>：标题写入元数据，播放器可展示；
• -i, --idle-time-limit <SECS>：空闲截断（写入元数据，回放侧解释，详见配置篇 2.2）；
• -I, --capture-input：记录键盘输入（含密码等敏感输入，慎用）；
• -a, --append：续录到已有文件（时间自动衔接），与 --overwrite 互斥；
• --return：让 asciinema 以被录命令的退出码退出，CI 判断成败必备；
• --window-size 80x24：固定录制尺寸，保证不同终端下画面一致。

2.3 headless：无人值守录制

v3 在无交互终端环境自动降级 headless，实测回显：

$ asciinema3 rec demo.cast -t "v3-demo" -c "bash -c 'echo hello-from-v3; uname -r; date +%F'"
::: TTY not available, recording in headless mode
::: asciinema session started
::: Recording to demo.cast
::: asciinema session ended
::: Recorded to demo.cast

配合 --return 可嵌入流水线：asciinema3 rec ci.cast -c "./deploy.sh" --return，deploy.sh 失败则整条命令以非零退出。v2 没有此能力（无 TTY 直接崩溃，见安装篇 5.2），自动化场景必须用 v3。

三、.cast 文件结构解析与审计

3.1 用 jq 解析 header 与事件

.cast 是 JSON Lines：首行 header 对象，其余为 [时间偏移, 事件类型, 数据] 数组。以 2.3 节实测产物为例：

$ head -1 demo.cast
{"version":3,"term":{"cols":80,"rows":24},"timestamp":1793156859,"command":"bash -c \"echo hello-from-v3; uname -r; date +%F\"","title":"v3-demo"}

逐行提取事件（jq 实测输出）：

$ jq -c 'select(type=="array")' demo.cast
[0.002,"o","hello-from-v3\r\n"]
[0.001,"o","7.0.0-38-generic\r\n"]
[0.001,"o","2026-10-28\r\n"]
[0,"x","0"]
$ jq -r 'select(type=="array" and .[1]=="o") | .[2]' demo.cast | cat -v
hello-from-v3^M
7.0.0-38-generic^M
2026-10-28^M

再进一步可做审计统计与状态提取：

$ jq -s '[.[] | select(type=="array")] | length' demo.cast
4
$ jq -r 'select(type=="array" and .[1]=="x") | .[2]' demo.cast
0

事件类型小结（实测 + 官方格式文档 docs.asciinema.org/manual/asciicast/v3）：o 终端输出、i 键盘输入（需开启捕获）、m marker 标记、r 尺寸变化、x 退出码。巡检留痕场景可写一条 jq 管道输出「会话时间轴报告」，或 asciinema3 convert -f txt demo.cast - 直接得到无转义纯文本。

3.2 敏感信息清理

误录键盘输入后，分享前可按事件类型清洗（去掉全部 i 事件再重打包）：

$ (head -1 secret.cast; jq -c 'select(type!="array" or .[1]!="i")' secret.cast) > clean.cast

更稳妥的做法是源头控制：录制演示时不加 -I/--capture-input；确需录入时用 --capture-env 收敛环境变量范围（默认仅 SHELL，见配置篇 2.3）。

四、回放与格式加工

4.1 play 与回放控制

交互终端中的回放及控制键（play --help 实测）：

$ asciinema3 play demo.cast            # 原速回放
$ asciinema3 play --speed 2 --loop demo.cast   # 两倍速循环
$ asciinema3 play --pause-on-markers demo.cast # 在 marker 处自动暂停

控制键：ctrl+c 中断、space 暂停/继续、. 单步前进、] 跳到下一个 marker；-r 可尝试让终端尺寸匹配录制原始尺寸。play 也支持直接播放远程 URL（如 asciinema3 play https://asciinema.org/a/569727，官方 help 示例）。

环境说明：play 需要 /dev/tty。本文实测环境无交互终端，执行时报 Error: No such device or address (os error 6)——此为环境限制而非命令故障；在真实 SSH 会话中上述命令预期正常回放（标注：命令 + 预期结果）。无终端环境验证内容可用 4.2 的 convert。

4.2 convert：导出 raw 与 txt

$ asciinema3 convert -f txt demo.cast -
hello-from-v3
7.0.0-38-generic
2026-10-28
$ asciinema3 convert -f raw demo2.cast - | cat -v
^[[8;0;0thello-from-v2^M
2026-10-28^M

txt 去除颜色与控制序列（适合入报告、发消息）；raw 保留全部原始字节（适合管道喂给其他工具）。convert 也接受 HTTP(S) URL 输入与文件输出（convert -f v2 demo.cast demo.v2.cast 可降级给仍用 v2 播放器的同事）。

4.3 cat：拼接多段录制（v3 新语义）

v3 的 cat 把多段录制顺序拼接、时间自动衔接，实测把一段 v2 录制与一段 v3 录制合并：

$ asciinema3 cat demo.cast demo2.cast > combined.cast
$ cat combined.cast
{"version":3,"term":{"cols":80,"rows":24},"timestamp":1793156859,...,"title":"v3-demo"}
[0.002, "o", "hello-from-v3\r\n"]
...
[0.003, "o", "hello-from-v2\r\n"]
[0.000, "o", "2026-10-28\r\n"]

要点：输出统一为 v3 格式（v2 输入自动归一），header 取自第一段。v2 的 cat 是单文件打印原始输出，且需要终端（本文实测无 /dev/tty 时报 OSError: [Errno 6] No such device or address）；v3 环境下等价行为用 convert -f raw，二者不可混用（安装篇问题 3 即此语义差异引发）。

五、托管、分享与网页播放

5.1 upload 到 asciinema.org（实测成功）

$ ASCIINEMA_SERVER_URL=https://asciinema.org asciinema3 upload demo.cast
View the recording at:

    https://asciinema.org/a/9gH95sT47gyt8lM9

This asciinema CLI hasn't been linked to any asciinema.org account.

Recordings uploaded from unrecognized systems, such as this one, are automatically
deleted 7 days after upload.

If you want to preserve all recordings uploaded from this machine,
authenticate this CLI with your asciinema.org account by opening the following link:

    https://asciinema.org/connect/69248577-ea86-4bd2-87f5-382a9087dac9

实测要点（2026-10-28）：上传无需预注册，返回的录制页链接经 curl -L 验证 HTTP 200 可访问；未绑定账号的录像 7 天后自动删除，长期保留需访问 connect 链接完成账号绑定（或用 asciinema3 auth）。公开性可用 upload --visibility public|unlisted|private 控制，标题/描述可同传。

5.2 纯静态网页播放器聚合（不依赖云端）

官方 asciinema-player（v3.17.0，2026-10-28 查询 GitHub Releases）提供两个静态资产：asciinema-player.min.js 与 asciinema-player.css。本地聚合三步：

1. 建目录放入 player.js、player.css 与要播放的 demo.cast；
2. 写 index.html（核心三行）：

<link rel="stylesheet" href="player.css">
<div id="demo"></div>
<script src="player.js"></script>
<script>AsciinemaPlayer.create('demo.cast', document.getElementById('demo'));</script>

3. 用任意静态文件服务分发，实测在 8143 端口验证：

$ python3 -m http.server 8143 --bind 0.0.0.0
$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8143/demo.cast
200

实测 index.html、player.js、player.css、demo.cast 四项均返回 200，浏览器访问 http://<服务器IP>:8143/ 即可在网页内播放本地录像。生产使用建议加访问控制并改用常驻的静态服务（如 nginx 的静态目录），python3 -m http.server 仅适合临时演示。

5.3 server 自托管与 auth 的边界（如实说明）

需要集中检索、账号体系与直播时，官方提供自托管服务端（Elixir/Phoenix 实现，官方文档 docs.asciinema.org/manual/server/self-hosting 含 Quick start/Configuration/Upgrading/Administration 全套章节）。本文未对服务端部署做实测，不作部署结论；在引入服务端前，5.2 的静态聚合 + 本地 .cast 入 Git 已能满足「录制—存档—分发」闭环。upload --server-url 与 ASCIINEMA_SERVER_URL（配置篇 3.2）是将来切换自托管站点的配置入口。

六、排障实录

问题 1：asciinema cat 突然要求两个文件参数。 报 error: 2 values required by '<FILE> <FILE>...' 说明实际执行的是 v3 的 cat（新语义：拼接至少两段），而非 v2 的「打印原始输出」。用 which asciinema 确认版本与路径（多为 /usr/local/bin 优先级劫持，见安装篇问题 3），或直接改用 asciinema3 convert -f raw demo.cast -。

问题 2：play 报 No such device or address (os error 6)。 play 需要 /dev/tty，定时任务与流水线中必然失败；无终端环境验证录制内容改用 convert -f txt，需要「无人值守回放」时考虑先转 raw 再静态网页方案。

问题 3：上传后录像「消失」。 未绑定账号的设备上传的录像 7 天后自动删除（5.1 回显原文），并非丢失故障；用 connect 链接或 asciinema3 auth 绑定账号即可长期保留，绑定前的重要录像先在本地留档。

问题 4：--overwrite 与 -a 报互斥错误。 两者都作用于已有文件但方向相反（覆盖/续录），一次只能选一个；续录前确认目标文件未被并发写入，避免时间轴交错。

问题 5：录制文件在低版本播放器显示异常。 v3 默认产出 asciicast v3 格式，旧工具链（含 v2 播放器）可能不识别；用 asciinema3 convert -f v2 demo.cast demo.v2.cast 降级后再分发。

全链路回顾与延伸阅读：

• 录制参数与配置文件的对应关系：《asciinema 3.2.1 配置参数详解》
• 双版本安装与布局原则：《asciinema 3.2.1 安装部署指南》
• 项目定位与方案对比：《asciinema 3.2.1 介绍与选型指南》