asciinema 3.2.1 配置参数详解

目标：逐项讲清 asciinema 的配置体系——v3（Rust 线）的 ~/.config/asciinema/config.toml 与 v2（Python 线）的 ~/.config/asciinema/config，每项参数给出实测生效证据或明确标注来源边界。全部实测于 2026-10-28 在 Ubuntu 22.04.5 LTS 服务器完成，CLI 版本为 v3.2.1 与 v2.1.0 双版本并存。

一、配置体系总览

1.1 配置文件位置与两代格式

asciinema 两个版本线的配置文件共用同一目录但文件名不同：

该目录下还有两个非配置文件，了解即可：

• install-id：首次运行时自动生成的设备标识（上传 asciinema.org 时用于识别来源设备）；
• config.toml.bak：v3 改写配置前的自动备份（详见排障一节）。

1.2 优先级：命令行参数 > 环境变量 > 配置文件

v3 各子命令 --help 中反复出现同一句式：「Can also be set via the config file option session.command」——含义是命令行参数与配置文件可以表达同一配置，命令行参数覆盖配置文件。服务器URL 则存在三级覆盖：--server-url 参数 > ASCIINEMA_SERVER_URL 环境变量 > 配置文件 server.url（upload --help 原文，实测环境变量方式已验证可用）。排障时的第一原则：先确认是不是命令行参数或环境变量覆盖了预期。

二、v3 config.toml：[session] 录制节

2.1 session.command：默认录制命令

rec -c/--command 的配置文件等价物。写入配置后，不带 -c 执行 rec 也会按配置录制。完整实测过程：

$ mkdir -p ~/.config/asciinema
$ cat > ~/.config/asciinema/config.toml <<'EOF'
[session]
command = "bash -c \"echo from-config-command\""
EOF
$ asciinema3 rec cfgtest.cast
::: TTY not available, recording in headless mode
::: asciinema session started
::: Recording to cfgtest.cast
::: asciinema session ended
::: Recorded to cfgtest.cast
$ head -1 cfgtest.cast
{"version":3,"term":{"cols":80,"rows":24},"timestamp":1793156890,"idle_time_limit":1.5,"command":"bash -c \"echo from-config-command\""}

header 的 command 字段与配置值完全一致，证明 session.command 生效。注意 TOML 转义：内嵌引号需 \"，拼接复杂命令时建议先在命令行验证再落配置。

2.2 session.idle_time_limit：空闲时间上限

对应 rec -i/--idle-time-limit <秒>。语义要点（rec --help 原文归纳）：该值不修改原始时间戳，而是写入录制文件元数据，由播放器在回放时执行截断——这意味着录制后仍可调整上限，比 v2「录制时永久裁剪」的语义友好得多。

实测：配置 idle_time_limit = 3.0 后录制，header 直接体现：

$ cat > ~/.config/asciinema/config.toml <<'EOF'
[session]
idle_time_limit = 3.0
EOF
$ asciinema3 rec t3.cast -c "bash -c 'echo t3'"
$ head -1 t3.cast
{"version":3,"term":{"cols":80,"rows":24},"timestamp":1793157502,"idle_time_limit":3.0,"command":"bash -c \"echo t3\""}

回放时可用 play -i <秒> 临时覆盖文件内与配置内的值（play --help 原文：This overrides any idle time limit set in the recording itself or in your config file）。

2.3 session.capture_input 与 session.capture_env

• capture_input（对应 -I/--capture-input）：开启后键盘输入也作为 i 事件录入。安全红线：开启后 sudo 密码等敏感输入会以明文进入 .cast 文件，仅在演示类录制中短期开启。
• capture_env（对应 --capture-env <VARS>）：控制哪些环境变量写入 header 的 env 字段，默认仅 SHELL。实测指定 USER,SHELL,TERM：

$ USER=tester SHELL=/bin/bash TERM=xterm-256color \
    asciinema3 rec envtest.cast --capture-env "USER,SHELL,TERM" -c "bash -c 'echo env-capture-test'"
$ head -1 envtest.cast
{"version":3,"term":{"cols":80,"rows":24},"timestamp":1793157456,"idle_time_limit":2.0,"command":"bash -c \"echo env-capture-test\"","env":{"TERM":"xterm-256color","USER":"tester","SHELL":"/bin/bash"}}

env 字段与 --capture-env 列表一一对应，审计场景（记录操作者 USER）与脱敏场景（只留 SHELL）都靠这一项收敛。默认不配置时 header 无 env 残留敏感值，符合最小暴露。

三、v3 config.toml：回放与服务端节

3.1 playback.speed（节名以实测观察为准）

play -s/--speed 的配置等价物。此处有一个实测发现的命名出入：v3.2.1 的 play --help 写作「config file option playback.speed」，但自动生成的配置样例中观察到的是 [play] 节下 speed = 1.5。由于无交互终端环境无法完整验证 play 的运行时行为，本文建议：回放速度优先用命令行参数 --speed（实测确定可用），配置文件方式仅作了解，需要固化时以本机 asciinema3 play --help 输出为准并小步验证。

$ asciinema3 play --speed 2.0 demo.cast     # 两倍速回放（官方 help 示例）
$ asciinema3 play --idle-time-limit 2 demo.cast
$ asciinema3 play --loop demo.cast

3.2 server.url 与 ASCIINEMA_SERVER_URL

上传目标服务器的配置入口，三级优先：upload --server-url > 环境变量 ASCIINEMA_SERVER_URL > 配置 [server] url。都不配置时首次 upload 会交互式询问（默认 asciinema.org）并把选择保存为默认。实测中通过环境变量指定官方站点成功上传：

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

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

自托管或走内网网关时改写该值即可；配置文件写法为 [server] 节 url = "..."（官方 upload --help 声明，环境变量方式经实测验证）。

四、v2 INI 配置（旧线）

4.1 [record]/[playback]/[api] 三节

v2 的 INI 配置写入 ~/.config/asciinema/config（无扩展名），三节结构：

[record]
command = /bin/bash
idle_time_limit = 2

[playback]
speed = 1.5

[api]
hostname = asciinema.org

• [record]：录制默认值，command/idle_time_limit 对应 v2 的 -c/-i；注意 v2 的 idle_time_limit 是录制时直接裁剪时间戳（不可逆），与 v3 的「元数据声明、回放时解释」语义不同；
• [playback]：回放默认值（如 speed）；
• [api]：hostname 指向托管站点，v2 仅支持 asciinema.org 一类官方/兼容站点，无 v3 的环境变量与多级覆盖。

4.2 两代语义差异速查

双版本并存的服务器上，两文件互不干扰（文件名不同），按调用命令区分：asciinema 读 INI，asciinema3 读 TOML。

五、排障实录

问题 1：改了配置但不生效。 按优先级倒查：命令行是否带了同名参数 → 环境变量（env | grep ASCIINEMA）→ 是否改错了文件（v3 必须是 config.toml，写错成 INI 文件不读）。终验手段：录制后 head -1 xxx.cast 看 header，配置项是否进入元数据一目了然（本文所有验证均以此法闭环）。

问题 2：config.toml 被自动改写。 实测中观察到一次：自定义配置文件被重写为短小内容，原文件自动备份为 config.toml.bak。教训有二：其一，重要配置建议纳入个人 dotfiles 管理可随时恢复；其二，改写后先 diff config.toml config.toml.bak 再决定恢复或接受，随后用 2.1 节的 header 验证法确认当前生效值。

问题 3：TOML 语法错误导致配置整体失效。 嵌套引号漏转义是高发点（见 2.1 示例的 \" 写法）。症状是「配置像没写一样」，实际是解析失败回退默认值；用任意 TOML 校验器或逐字符比对官方示例定位。

问题 4：v2 的 [record] 不影响 v3。 两个版本线配置完全独立（文件名不同），反之亦然；混用是双版本并存环境最常见的「配置不生效」根因。

配置就绪后，进入日常操作：

• 录制/回放/上传全链路：《asciinema 3.2.1 命令与运维实战》
• 双版本安装背景：《asciinema 3.2.1 安装部署指南》
• 项目定位与对比：《asciinema 3.2.1 介绍与选型指南》