rich 的富文本功能必须通过 console 实例调用，因为其颜色、emoji、换行等依赖内部状态；直接使用 print 无法触发渲染，logging 需配合 richhandler，progress 和 emoji 渲染也需按规范配置。
Rich 能直接替换 print 和 tqdm，但必须用 console.print() 和 console.progress()，原生 print 不会触发样式渲染。
为什么 print("✨") 不显示颜色，而 console.print("✨") 可以？
Rich 不劫持 Python 的内置 print，所有富文本能力都封装在 Console 实例里。终端颜色、emoji 渲染、自动换行截断等都依赖 console 的内部状态（比如是否启用 color system、是否检测到支持 emoji 的终端）。
常见错误：
- 直接用
print("[bold red]Error[/]")—— 方括号语法不会被解析，只会原样输出 - 忘记初始化：没写
from rich.console import Console; console = Console() - 在非交互式环境（如 cron、CI 日志流）中强制启用颜色，导致日志出现乱码控制字符
正确做法是统一走 console.print()，并根据环境自动降级：
from rich.console import Console
console = Console(color_system="auto") # auto 会检测 TERM 和 stdout.isatty()
console.print("[bold cyan]Starting...[/]", emoji=True)
如何让 logging 模块输出带样式的日志？
Rich 提供了 RichHandler，它不是装饰器，而是 logging 的 handler 替代品，需显式注册。默认的 StreamHandler 不认识 Rich 的标记语法。
关键点：
- 必须把
RichHandler加到 logger 的 handlers 列表中，而不是替换 root logger 的 level -
rich_tracebacks=True能让异常堆栈变可折叠、带代码高亮，但仅对未捕获异常或logger.exception()生效 - 日志级别标签（INFO/ERROR）默认用不同颜色，但格式字符串里的
{levelname}不会被自动着色 —— 要靠console.highlighter或自定义render方法
最小可用示例：
图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
import logging
from rich.logging import RichHandler
<p>logging.basicConfig(
level="INFO",
format="%(message)s",
datefmt="[%X]",
handlers=[RichHandler(rich_tracebacks=True, tracebacks_show_locals=True)]
)
log = logging.getLogger("myapp")
log.info("Loaded config from [green]/etc/app.yaml[/]")</p>
进度条卡住、不刷新或显示两行？
Progress 是 Rich 最容易出问题的组件，核心矛盾在于：它需要独占一行 + 实时覆盖重绘，但任何意外换行（比如日志插进来、print() 调用、异常 traceback）都会破坏这个假设。
避坑要点：
- 不要在
with Progress()块内调用print()或其他非console输出；改用console.log()（它会自动跳过进度条所在行） - 任务总数必须提前知道；如果边迭代边生成，要用
add_task(total=None)+ 后续update(task_id, total=N) - 多线程下不能共用一个
Progress实例；每个线程应创建独立Progress(console=Console(record=True))，否则刷新冲突 - 在 GitHub Actions 等无 TTY 环境中，
Progress默认静默；加console=Console(force_terminal=True)强制启用（但可能输出大量 \r 控制符）
典型用法：
from rich.progress import Progress
<p>with Progress() as progress:
task = progress.add_task("[cyan]Processing...", total=100)
for i in range(100):</p><h1>do_work()</h1><pre class="brush:php;toolbar:false;"><code> progress.update(task, advance=1)</code>
Emoji 显示成方块、中文乱码或宽度错位？
Rich 默认按 Unicode 标准计算字符宽度，但某些字体（尤其 Windows CMD、旧版 iTerm）对 emoji 和 CJK 字符宽度判断不准，导致对齐崩坏或换行异常。
实际对策：
- 优先用
console.print("✅ Done", emoji=True, justify="center")而非手写\u2705，因为emoji=True会启用 Rich 内置的 emoji 名称映射和宽度修正 - 中文场景下，禁用自动 justify：去掉
justify参数，或显式设justify="left"；Rich 的 center/right 对中文支持不稳定 - 若必须用宽字符做进度条填充（如用 ▰ 代替 █），确认终端字体支持「等宽 emoji」，否则换回 ASCII 字符（
bar_format="{task.description} {bar}| {task.completed}/{task.total}"）
真正麻烦的是混合输出：当一行里同时有 emoji、ANSI 颜色、中文、自动换行时，Rich 的 layout 引擎可能误判宽度。这时候最稳的方式是拆成多行 console.print()，放弃单行富文本幻想。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
