Debian/Ubuntu直接apt安装最稳，sudo apt install asciinema即可，需先运行sudo apt update；若失败则因发行版过旧，可改用pip3安装，但须确保Python 3.7+以避免功能缺失。
Debian/Ubuntu 直接 apt 安装最稳
绝大多数情况下，sudo apt install asciinema 就够用，不用额外加 PPA 或 pip。系统源里的版本（如 Ubuntu 22.04+ 自带 v2.4.0+）已支持 --idle-time-limit、--speed 等常用参数，且与系统 Python 兼容性好。
常见错误现象：E: Unable to locate package asciinema —— 多因未更新索引，先运行 sudo apt update 再装；若仍失败，说明发行版太老（如 Ubuntu 16.04），可换 pip 方式。
- 不要用
apt-get install python3-pip && pip3 install asciinema混合安装，容易因 pip 版本或权限导致asciinema: command not found - 装完验证：运行
asciinema --version，输出类似asciinema 2.5.0即成功 - 首次运行
asciinema rec会提示登录，按回车跳过即可本地保存，不强制上传
CentOS/RHEL 8+ 推荐 dnf，别碰 yum
yum install asciinema 在 CentOS 7 及更早版本中可能失败，因为默认仓库不含该包；RHEL/CentOS 8+ 已转向 dnf，且 EPEL 仓库默认启用，直接 sudo dnf install asciinema 即可。
如果提示 No match for argument: asciinema，先确认 EPEL 是否启用：sudo dnf install epel-release，再重试。
- 避免手动编译或从源码 git clone —— 依赖
python3-setuptools和python3-wheel，缺一不可，容易卡在ImportError: No module named 'setuptools' - CentOS 7 用户若无法启用 EPEL，可用 pip：确保
python3-pip已装，然后pip3 install --user asciinema，再把$HOME/.local/bin加入$PATH
用 pip 安装时必须注意 Python 环境
Asciinema 是纯 Python 工具，但只支持 Python 3.7+；很多 Linux 发行版默认 Python 仍是 3.6 或更旧（如 CentOS 7 自带 Python 3.6.8），pip3 install asciinema 会静默降级到旧版（v2.1.x），缺失关键功能如 --raw 或宽屏适配。
验证方式：运行 asciinema rec test.cast 后执行 ls -l test.cast，若文件大小
- 先查 Python 版本：
python3 --version，低于 3.7 就别硬 pip 装，换系统包管理器或升级 Python - 不要用
sudo pip3 install—— 可能污染系统 site-packages，引发其他 Python 工具冲突 - 推荐用户级安装：
pip3 install --user asciinema，然后确保~/.local/bin在$PATH中（检查echo $PATH，必要时加到~/.bashrc）
录制前务必确认终端宽度和环境变量
Asciinema 默认按当前终端尺寸（$COLUMNS × $LINES）记录，如果录制时缩放窗口或远程 SSH 连接未传尺寸，回放会错位或截断。这不是安装问题，但常被误认为“装了不能用”。
典型表现：播放时命令显示不全、光标乱跳、中文字符堆叠 —— 其实是录制时 TERM 或尺寸没捕获准。
- 录制前运行
stty size看当前行列数，再执行asciinema rec -w $(stty size | awk '{print $2}') -h $(stty size | awk '{print $1}') demo.cast手动锁定尺寸 - 重要环境变量如
SHELL、TERM默认已捕获，但自定义 prompt（如 starship）可能导致录制时渲染异常，可加--env=TERM,SHELL,PWD显式指定 - 不要在 tmux 或 screen 里直接
asciinema rec—— 它会记录嵌套控制序列，播放时乱码；应先退出 multiplexer，或用asciinema rec -c "bash"显式启动干净 shell
--raw 或 --stdin —— 那些只在调试自动化脚本时才需要。 
