企业官网建设流程全解析

listr2 的 5 种 renderer 怎么挑？CLI 展示效果终极对比指南

【免费下载链接】listr2NodeJS Task List derived from the best! Create beautiful CLI interfaces via easy and logical to implement task lists that feel alive and interactive.项目地址: https://gitcode.com/gh_mirrors/li/listr2

listr2 是一款流行的 NodeJS CLI 任务清单库，它能把普通的命令行脚本变成"会动、有状态、可交互"的终端界面。在 listr2 中，renderer（渲染器）就是负责把任务状态"画"到终端上的展示层，官方一共内置了 5 种：default、simple、verbose、silent和test。本文从 CLI 展示效果的角度逐一横向对比，帮你 30 秒选出最适合自己的那一个。

📋 5 种 renderer 速览：一张表看懂差异

一句话总结：想要"活的"终端效果选default；日志/CI 环境选simple或verbose；完全静默选silent；写测试选test。

🎬 1. DefaultRenderer：交互 CLI 的首选

default是 listr2 的默认渲染器，专为 TTY（真实终端）环境设计：它会持续重绘终端输出，任务进行中显示转圈动画，完成打勾、失败打叉，展示效果最接近"活的"进度条。

• 依赖vt100终端兼容，并通过 ProcessOutput 接管终端输出
• 支持大量自定义选项（图标、颜色、动画速度等），可在 Listr、子任务、单个任务三级分别配置
• 从 v11 起采用差分更新，只重写真正变化的行，动画更顺滑、几乎不闪屏

适用场景：交互式命令行工具、脚手架（如npx create-xxx那种带旋转图标和彩色状态的效果）。

✍️ 2. SimpleRenderer：非交互环境的平替

simple是default的"日志式"替代方案：它不刷新终端，而是像 logger 一样一行一行往下追加输出，每个任务状态变化都会留下一行记录。

• 不使用 prompts（交互式提问）时，可以在非 TTY 环境（管道、CI）正常工作
• 自 v6.0.0 起，它就是非 TTY 环境的默认 fallback 渲染器
• 展示效果介于"炫"与"纯"之间：有状态图标，但不清屏重绘

适用场景：构建脚本、CI 流水线、输出需要被| tee或重定向保存日志的场景——因为这些环境里"重绘"动画会变成乱码，逐行日志才是正道。

📝 3. VerboseRenderer：纯文本日志流

verbose是一个完全基于文本的渲染器，行为最接近传统 logger：任务开始、完成、失败都以纯文本行打印，不做任何终端重绘技巧。

• 在 v6.0.0 之前它曾是非 TTY 环境的默认渲染器
• 终端兼容性要求最低，几乎任何环境都能稳定输出
• 展示效果最朴素：适合把"发生了什么"看得清清楚楚

适用场景：旧式终端、串口/受限控制台，或你只想要一份干净、可读、可 grep 的执行流水。

🤫 4. SilentRenderer：什么都不输出

silent的行为极简：完全静默，终端零输出。它把 listr2 变成一个纯粹的"逻辑任务编排器"——顺序、并发、重试、rollback 都在正常工作，但界面交给你自己。

• 你可以接自己的 logger、上报系统或 Web UI 来呈现状态
• 子任务（Subtask）内部也会用它，避免和父任务的渲染器"抢画面"

适用场景：listr2 只当任务引擎用、输出走自己的日志/监控系统，或嵌入 Electron、Web 等无需终端 UI 的环境。

🧪 5. TestRenderer：为自动化测试而生

test是测试专用的渲染器：它按事件逐行输出 JSON，方便在 e2e 测试中断言任务的状态流转（开始、完成、跳过、失败……）。

• 输出格式可通过 renderer 选项定制
• 属于内部事件协议，理解成本略高，一般只在测试里使用

适用场景：给 CLI 工具写快照测试、状态断言。项目自带大量使用它的 e2e 测试可参考：tests/

🧭 三步选对 renderer：决策指南

1. 用户在真实终端里交互运行？→ 选default（不配置时它本来也是默认值）
2. 输出会被重定向、跑在 CI/无 TTY 环境？→ 选simple（或更朴素的verbose）
3. 根本不想有终端输出，或正在写测试？→ 选silent/test

另外 listr2 还有个贴心机制：自动降级（fallback）。当你选择了default，但环境被检测为非 TTY 时，会自动回退到fallbackRenderer（默认即simple），无需手动判断环境。也可以通过fallbackRendererCondition、silentRendererCondition传入自定义条件，在满足条件时自动切换，细节见 docs/renderer/fallback-condition.md。

💡 小技巧：颜色、Unicode 图标也支持环境变量控制——FORCE_COLOR=1强制开色、NO_COLOR=1强制关色、LISTR_FORCE_TTY=1强制 TTY 模式，调试展示效果时非常好用。

📚 相关文档与示例文件

想深入了解每个渲染器的选项和效果，建议按这份清单逛一逛：

• 渲染器总览：docs/renderer/renderer.md
• 各渲染器文档：default、simple、verbose、silent、test
• 渲染器源码：packages/listr2/src/renderer/
• 可运行示例：renderer-default.example.ts、renderer-simple.example.ts、renderer-verbose.example.ts、renderer-fallback-condition.example.ts

选对 renderer，你的 CLI 工具既能"炫"得起，也能在任何环境下稳定输出——这就是 listr2 渲染体系最大的价值。

【免费下载链接】listr2NodeJS Task List derived from the best! Create beautiful CLI interfaces via easy and logical to implement task lists that feel alive and interactive.项目地址: https://gitcode.com/gh_mirrors/li/listr2