asciinema 3.2.1 安装部署指南

Ubuntu 22.04.5 LTS 服务器上 asciinema 双版本安装实战：apt 安装 v2.1.0 与 GitHub Releases 安装 Rust v3.2.1 单文件二进制并存、PATH 优先级布局、首次录制验证与排障实录，全部命令实测。

asciinemaasciinema终端工具Ubuntu22.042026/10/28

asciinema 3.2.1 安装部署指南

目标：在一台 Ubuntu 22.04.5 LTS 服务器上完成 asciinema 的安装——发行版仓库的 v2.x（Python 实现）与 GitHub Releases 的 v3.x（Rust 单文件二进制）双版本并存，完成版本确认与首次录制验证。本文全部命令于 2026-10-28 在 Ubuntu 22.04.5 LTS 服务器实测执行，输出为真实回显；版本信息同期从 GitHub Releases 与 apt 仓库实查。

一、安装路径总览与选型

1.1 官方支持的安装方式

官方文档（docs.asciinema.org → CLI → Installation，2026-10-28 查询）列出的安装路径包括：

  • 各发行版包管理器：Arch pacman -S asciinema、Debian/Ubuntu apt install asciinema、Fedora dnf install asciinema 等；
  • 从 GitHub Releases 页面下载最新版的预编译静态二进制（官方推荐的获取最新版本方式）；
  • PyPI：仅覆盖 2.x 旧线（pipx install asciinema）；
  • 从源码构建（v3 为 Rust，cargo build --release）。

对 Ubuntu 22.04 需要特别建立预期：apt 仓库里装到的是 2.x 旧线（jammy/universe 中为 2.1.0-1，Python 实现），而最新功能（headless 录制、convert、stream、TOML 配置）都在 3.x 线。生产服务器的稳妥做法是本文采用的双版本并存：apt 的 v2 保留系统默认习惯，Releases 的 v3 单文件放置即用，互不干扰。

1.2 前置条件检查

$ lsb_release -ds
Ubuntu 22.04.5 LTS
$ uname -m
x86_64

v3 二进制按架构分发，x86_64 服务器选 asciinema-x86_64-unknown-linux-musl（静态链接，任何 x86_64 Linux 都能跑）或 asciinema-x86_64-unknown-linux-gnu；ARM 服务器选 aarch64 对应资产。

二、安装 v2.x：发行版仓库

2.1 apt 安装与版本确认

Ubuntu 22.04 的 asciinema 位于 universe 仓库，先确认候选版本再安装：

$ apt-cache policy asciinema
asciinema:
  Installed: (none)
  Candidate: 2.1.0-1
  Version table:
     2.1.0-1 500
        500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages

候选版本 2.1.0-1 来自 jammy/universe，与预期一致（2.x 旧线）。执行安装：

$ sudo apt install -y asciinema
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
  python3-pkg-resources
...
Setting up python3-pkg-resources (59.6.0-1.2ubuntu0.22.04.3) ...
Setting up asciinema (2.1.0-1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

确认版本与安装位置：

$ asciinema --version
asciinema 2.1.0
$ which asciinema
/usr/bin/asciinema
$ dpkg -S $(which asciinema)
asciinema: /usr/bin/asciinema

2.2 可选：PPA 源说明

官方文档提到 David Adam（zanchey）维护的 PPA（ppa:zanchey/asciinema），提供方式为：

$ sudo apt-add-repository ppa:zanchey/asciinema
$ sudo apt update
$ sudo apt install asciinema

该 PPA 同样面向 2.x 旧线；本文未启用（universe 源已满足 v2 需求），如需使用请自行评估第三方源信任问题。

三、安装 v3.x：GitHub Releases 单文件二进制

3.1 查询最新版本并下载

2026-10-28 实查 GitHub Releases（api.github.com/repos/asciinema/asciinema/releases/latest）：最新版 v3.2.1，发布于 2026-06-16，资产为单文件二进制（musl/gnu × x86_64/aarch64 × Linux/macOS）。下载放置到 /usr/local/bin：

$ cd /tmp
$ curl -fLO https://github.com/asciinema/asciinema/releases/download/v3.2.1/asciinema-x86_64-unknown-linux-musl
$ chmod +x asciinema-x86_64-unknown-linux-musl
$ sudo mv asciinema-x86_64-unknown-linux-musl /usr/local/bin/asciinema3

说明：文件名保持可辨识（本文以 asciinema3 命名 v3，asciinema 仍指向 apt 的 v2），也可先装成 asciinema-v3 观察一段时间再定名。若从浏览器下载，务必校验文件可执行位与架构（file 命令应显示 static-pie linked）。

3.2 版本确认与自检

$ asciinema3 --version
asciinema 3.2.1
$ which asciinema3
/usr/local/bin/asciinema3
$ asciinema3 --help
Terminal session recorder, streamer, and player

Usage: asciinema3 [OPTIONS] <COMMAND>

Commands:
  record   Record a terminal session [aliases: rec]
  stream   Stream a terminal session
  session  Record and stream a terminal session
  play     Play back a terminal session
  upload   Upload a recording to an asciinema server
  auth     Authenticate this CLI with an asciinema server account
  cat      Concatenate multiple recordings
  convert  Convert a recording to another format
  help     Print this message or the help of the given subcommand(s)

单文件二进制无任何运行时依赖，--help 能正常输出即安装成功。

四、双版本并存管理

4.1 并存布局与 PATH 优先级

当前布局：

$ which asciinema asciinema3
/usr/bin/asciinema
/usr/local/bin/asciinema3
  • /usr/bin/asciinema = v2.1.0（apt 管理，包升级随 apt upgrade 走）；
  • /usr/local/bin/asciinema3 = v3.2.1（手工管理，升级需手动替换文件）。

注意默认 PATH 中 /usr/local/bin 优先于 /usr/bin——这也是不要把 v3 直接命名成 /usr/local/bin/asciinema 的原因：一旦命名，asciinema 命令将从 apt 的 v2 被静默切换为 v3，而 v2/v3 的子命令语义并不完全相同（如 cat），可能造成脚本行为漂移。想让 v3 成为全局默认时，应显式建立符号链接或别名并同步回归测试既有脚本。

4.2 命令别名建议

在 ~/.bashrc 中为新版本建立顺手别名（按个人偏好选用其一）：

$ alias a3='asciinema3'          # 短别名
$ alias arec='asciinema3 rec'    # 高频录制入口
$ source ~/.bashrc

升级 v3 的完整流程：

$ asciinema3 --version          # 记录旧版本
$ cd /tmp && curl -fLO https://github.com/asciinema/asciinema/releases/download/v<新版本>/asciinema-x86_64-unknown-linux-musl
$ chmod +x asciinema-x86_64-unknown-linux-musl
$ sudo mv asciinema-x86_64-unknown-linux-musl /usr/local/bin/asciinema3
$ asciinema3 --version          # 确认新版本

卸载：v2 用 sudo apt remove asciinema；v3 直接 sudo rm /usr/local/bin/asciinema3，配置文件位于 ~/.config/asciinema/（两版共用目录但文件名不同，见配置篇）。

五、首次运行验证

5.1 v3 首次录制（含 headless 提示）

在交互终端执行 asciinema3 rec /tmp/hello.cast 即进入录制（结束后按 ctrl+d 或输入 exit）。在无交互终端的自动化环境执行同命令，v3 会自动降级为 headless 模式，实测回显：

$ asciinema3 rec /tmp/hello.cast -c "bash -c 'echo hello-from-v3'"
::: TTY not available, recording in headless mode
::: asciinema session started
::: Recording to /tmp/hello.cast
::: asciinema session ended
::: Recorded to /tmp/hello.cast
$ head -1 /tmp/hello.cast
{"version":3,"term":{"cols":80,"rows":24},"timestamp":1793156859,...}

5.2 v2 首次录制（需要真实终端）

v2 无 headless 能力，必须在有伪终端的交互会话中使用。在交互终端执行 asciinema rec /tmp/v2hello.cast -c "echo hello-from-v2" 正常录制并提示 asciicast saved to ...；同样的命令在无 TTY 环境直接失败，实测回显（截取）：

OSError: [Errno 25] Inappropriate ioctl for device
...
subprocess.CalledProcessError: Command '['tput', 'cols']' returned non-zero exit status 2.

若确需在非交互环境中使用 v2，须先为其分配伪终端（如 script -qec "asciinema rec ..." /dev/null 实测可绕过），但更推荐直接使用 v3。

六、排障实录

问题 1：GitHub 下载缓慢或超时。 服务器直连 GitHub Releases 下载 v3 二进制缓慢时，可让 curl 走内部代理出口，实测：

$ curl -fL -x http://<内网代理地址>:7897 \
    -o asciinema3 \
    https://github.com/asciinema/asciinema/releases/download/v3.2.1/asciinema-x86_64-unknown-linux-musl

（代理地址按实际环境替换；下载后 --version 验证。）

问题 2：apt install asciinema 找不到候选版本。 检查 universe 仓库是否启用：apt-cache policy asciinema 无候选时执行 sudo add-apt-repository universe && sudo apt update 后重试。

问题 3：asciinema 命令的版本与预期不符。 先用 which asciinema 定位实际解析路径，两种症状两种根因：

  • 版本停在 2.1.0 而你期望 v3：asciinema 仍指向 /usr/bin/asciinema（v2），v3 应调用 asciinema3；
  • 版本变成 3.x 而你期望 v2：/usr/local/bin 在默认 PATH 中优先于 /usr/bin，一旦把 v3 二进制命名为 /usr/local/bin/asciinema 就会静默接管 asciinema 命令。本文实测踩中此坑：asciinema cat demo.cast 突然报 error: 2 values required by '<FILE> <FILE>...'（那是 v3 的新 cat 语义要求至少两个文件，v2 的 cat 是单文件打印原始输出），删除误置文件后 asciinema --version 立即恢复 2.1.0。这正是 4.1 节强调不要把 v3 直接命名为 asciinema 的原因。

问题 4：架构选错导致 cannot execute binary file。 ARM 服务器误下 x86_64 资产会报此错，用 uname -m 复核架构后换 aarch64-unknown-linux-musl 资产。

安装完成后，推荐继续阅读：