asciinema 3.2.1 介绍与选型指南

目标：讲清 asciinema 的项目定位、版本形态、核心格式与工作原理，并给出与 script/scriptreplay、termtosvg、ttyd 等邻近方案的量化选型对比，帮助判断「什么场景该选 asciinema、选哪个版本」。本文全部外部数据（版本号、Stars、发布日期、维护状态）于 2026-10-28 从 GitHub Releases、GitHub 仓库页面与官方文档 docs.asciinema.org 实地查询；Ubuntu 22.04 环境下的 v2/v3 双版本安装、录制与回放行为基于同期在 Ubuntu 22.04.5 LTS 服务器上的实测结果。

一、项目认知：asciinema 是什么

1.1 项目定位与生态组成

asciinema 是一款开源的终端会话录制工具，由 Marcin Kulik（sxhder，也须写作 "Marcin Kulik"）创建并持续维护。与传统的屏幕录像不同，asciinema 录制的不是视频像素，而是终端的文本事件流——每一个字符输出都带精确的时间戳，因此录制产物体积小、可复制粘贴、可用 Git 管理差异，天然适合嵌入文档、博客与技术分享。

整个 asciinema 生态由三部分组成，理解这个分工是选型的前提：

• asciinema CLI：核心组件，负责录制（record）、回放（play）、格式转换（convert）、拼接（cat）与上传（upload）。当前主线 v3 使用 Rust 实现，编译产物是单文件静态二进制，无运行时依赖；旧线 v2 使用 Python 实现，仍广泛存在于各发行版仓库中。
• asciinema.org：官方运营的公共托管平台。asciinema upload 可把本地 .cast 文件上传为可分享的网页链接（如 https://asciinema.org/a/<id>），网页内置官方播放器。本文实测中，一份录制文件成功上传并返回了可访问的录制页链接，同时平台提示：未与账号绑定的设备上传的录像会在 7 天后自动删除，长期保存需通过 asciinema auth/connect 链接绑定账号。
• asciinema server：官方开源的自托管服务端。需要注意，其当前实现为 Elixir 语言 + Phoenix 框架（GitHub 仓库 asciinema/asciinema-server），并非旧文档常见的 Python/Django 版本；官方在 docs.asciinema.org 提供了完整的 Self-hosting 文档（Quick start、Configuration、Upgrading、Administration 等）。截至 2026-10-28，本文未对 server 自托管做部署实测，本文的交付口径以 CLI 为主：不依赖任何服务端的「纯本地 .cast 录制 + asciinema play 终端回放 + 官方 asciinema-player 静态网页播放器聚合」即可覆盖绝大多数录制分享需求，server 自托管仅作为需要集中检索、直播与账号体系时的进阶选项，实施前请按官方文档另行验证。

1.2 版本形态：v2 与 v3 的关键差异

asciinema 目前同时存在两条版本线，Ubuntu 服务器上很容易两者并存，选型时必须先分清手上是哪个版本：

本文实测中最直观的差异是：在同一台无交互终端的服务器上执行录制，v2 抛出 OSError: [Errno 25] Inappropriate ioctl for device 并崩溃，而 v3 打印 TTY not available, recording in headless mode 后正常产出 .cast 文件。此外 v2 的 cat 子命令是「打印原始输出」，v3 的 cat 语义已变更为「拼接多个录制文件」，打印原始输出需改用 convert -f raw。

1.3 维护状态与上游动态（查询日期 2026-10-28）

• asciinema/asciinema（CLI）：主线活跃，最新 Release 为 v3.2.1（发布于 2026-06-16），仓库 Star 约 17,900（2026-10-28 查询），许可证 GPLv3。Releases 页面按平台提供 asciinema-x86_64-unknown-linux-gnu、asciinema-x86_64-unknown-linux-musl、asciinema-aarch64-unknown-linux-gnu 等单文件资产。
• asciinema/asciinema-player（网页播放器）：最新版本 v3.17.0（2026-10-28 查询 Releases 列表），提供 player.js/player.css 静态资产，可将本地 .cast 文件直接嵌入自建网页播放，这是「不上传云端也能在浏览器分享」的官方路径。
• asciinema/asciinema-server（自托管服务端）：仓库持续存在并有 Self-hosting 文档，但社区活跃度远低于 CLI；选型时若只需要「录、播、分享」，优先考虑不依赖 server 的纯本地方案，需要集中管理时再评估 server。

二、核心概念与工作原理

2.1 asciicast 文件格式（v1/v2/v3）

asciinema 的录制产物统称 asciicast 文件，推荐扩展名 .cast，本质是 JSON Lines：首行为头部元数据，其后每行一个带时间戳的事件。本文在 Ubuntu 22.04 上用 v3.2.1 实际录制生成的文件内容如下（原样摘录）：

{"version":3,"term":{"cols":80,"rows":24},"timestamp":1793156859,"command":"bash -c \"echo hello-from-v3; uname -r; date +%F\"","title":"v3-demo"}
[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.000, "x", "0"]

• 首行 header：version 为格式版本，term 为录制时的终端尺寸，timestamp 为 Unix 时间戳，还可包含 command、title、idle_time_limit、env、capture_input 等字段。
• 事件行为三元素数组 [时间偏移秒, 事件类型, 数据]，实测可见的类型包括：
  • o：终端输出（含 ANSI 转义序列）；
  • i：键盘输入（需显式开启 --capture-input，注意密码等敏感输入也会被录下）；
  • m：marker（标记点，可在回放时暂停定位）；
  • r：终端尺寸变化；
  • x：会话结束与退出码（实测 "x","0" 表示录制命令以退出码 0 结束）。
• v2 头部为 {"version": 2, "width": ..., "height": ..., "timestamp": ..., "env": {...}}，事件结构相同但时间偏移为浮点秒。v1 则是单 JSON 对象格式，现已少用；v3 的 convert 子命令可在 v1/v2/v3/raw/txt 之间互转。

这个格式设计的直接收益：文件可以用 jq 逐行解析做审计（本文在命令运维篇有完整实测）、可以用 Git 做版本管理、可以流式追加，播放器按时间偏移重放事件即可 1:1 还原终端画面，包括颜色、光标移动与全屏程序（如 vim、htop）的界面。

2.2 录制—回放—分享工作流

一条最短可用路径是：

asciinema rec demo.cast      # 录制（结束按 ctrl+d 或输入 exit）
asciinema play demo.cast     # 在本机终端回放
asciinema upload demo.cast   # 上传 asciinema.org 得到分享链接

v3 还增加了两类进阶能力：stream/session 子命令支持把录制过程实时直播到 asciinema server；录制过程中按 ctrl+\ 可暂停/恢复捕获（官方 help 原文：Press ctrl+\ to pause/resume capture of the session），适合录制中途整理思路。回放侧支持倍速（--speed）、循环（--loop）、空闲截断（--idle-time-limit）与按 marker 暂停（--pause-on-markers）。

2.3 云托管与自托管边界（如实说明）

asciinema.org 是免费的官方公共实例，upload 无需预注册（未绑定账号的录像 7 天后自动删除，绑定账号后长期保留）。若因数据合规不便使用公共云托管，可选路径有两条，均不涉及自建服务端：

• 纯本地：.cast 文件留在本机，用 asciinema play 回放，或拷贝给同事用其本机的 asciinema 回放；
• 静态网页聚合：下载官方 asciinema-player 的 player.js/player.css，写一个引用 .cast 文件的 HTML 页面，用任意静态文件服务（如 python3 -m http.server）分发即可在浏览器播放。本文在命令运维篇对该方案做了实际验证。

官方 asciinema server 自托管（Elixir/Phoenix）在此之外提供了账号、检索与直播能力，属于另一量级的运维投入，本文未实测，不作部署承诺。

三、量化选型对比

3.1 对比维度与数据来源

终端录制是个小众但需求稳定的领域，常见的四个候选是 asciinema、script/scriptreplay（util-linux 自带）、termtosvg 与 ttyd。下表数据来源：asciinema 与 ttyd 的 Star 数、termtosvg 的最后发布时间均于 2026-10-28 从 GitHub 页面查询；script 版本取自实测服务器 script --version（util-linux 2.41.3）；asciinema 版本取自 GitHub Releases。

3.2 四款方案横向对比

三点解读：

1. 产物可复用性：script 产出的是原始字节流 + 时间文件，无法携带元数据、不便审计与二次加工；asciinema 的 asciicast 是结构化 JSON Lines，jq 可直接解析，且一份文件同时服务终端回放与网页播放器。
2. 网页嵌入路线：termtosvg 曾以「一步生成 SVG 动画」见长，但其最后版本发布停留在 2020-01，对新终端特性的跟进已停止；asciinema 官方播放器（asciinema-player v3.17.0）以 JS/CSS 静态资产方式持续维护，配合 .cast 文件是当前更稳妥的网页嵌入路线。
3. 实时共享：ttyd 解决的是「让别人实时操作/看到你的终端」，与「把过程录制下来异步观看」是不同需求；若两者都要，asciinema v3 的 stream/session 提供了面向自托管 server 的直播能力，可作为补充。

3.3 场景化选型建议

• 写运维文档/教程，需要可复制的命令过程：选 asciinema。文本事件流保证读者能从播放器里复制粘贴命令，这是任何屏幕视频都做不到的。
• 服务器巡检留痕、事后审计：选 asciinema v3（headless 可自动化、.cast 可入 Git、convert -f txt 可出纯文本报告）；零依赖场景可用 script 兜底。
• 博客/文档页嵌入可交互式演示：asciinema + asciinema-player 静态聚合（或上传 asciinema.org 拿嵌入代码）；仅当强烈偏好 SVG 且不介意项目停更时考虑 termtosvg。
• 远程协助/实时演示：ttyd 或 asciinema server 直播，录制归档交给 asciinema。
• CI 中自动录制构建过程：asciinema v3 的 headless 模式是四款中唯一为此设计的（实测无 TTY 直接可用）。

四、适用边界与局限性

4.1 适合的场景

• 命令行教学、SOP 沉淀、故障复盘：时间轴精确、可倍速、可复制。
• 自动化录制：headless + -c 指定命令，退出码可通过 --return 透传给 CI 判断。
• 敏感环境内部分享：--capture-env 精确控制环境变量收录范围（默认仅 SHELL），不开启 --capture-input 即不记录键盘输入，配合本地文件分发即可不经过任何云端。

4.2 不适合或需要注意的场景

• 需要视觉动效的营销展示：文本动画不如视频渲染灵活，强需求请选屏幕录制工具。
• 密码等敏感输入：默认不录键盘输入，但只要开启 --capture-input，sudo 密码等也会以明文事件进入 .cast，务必在脱敏场景禁用或在分享前用 jq 清洗。
• 像素级界面还原：asciicast 依赖终端模拟器重放，个别高级转义序列在低端播放器中可能有细微差异；官方播放器内置虚拟终端（avt），还原度最高。
• 非交互服务器的 v2：v2 在无 TTY 环境直接崩溃（本文实测），自动化场景必须使用 v3，或为 v2 手动分配伪终端。

五、小结与阅读路线

asciinema 以「结构化时间轴 + 文本事件流」重新定义了终端录制：体积小、可解析、可托管、可嵌入，是 Linux 服务器视角下录制类需求的默认答案；v3（Rust）补齐了 headless 自动化、格式转换与直播能力，v2（Python）作为发行版自带版本仍可用但能力停留在「录、播、传」。结合上文对比：教学沉淀、审计留痕、网页嵌入三条主线选 asciinema，实时共享选 ttyd，零安装兜底选 script。

后续实践请按序阅读：

• 安装落地：《asciinema 3.2.1 安装部署指南》
• 参数调优：《asciinema 3.2.1 配置参数详解》
• 日常操作：《asciinema 3.2.1 命令与运维实战》