进阶指南从figures源码学起如何自己动手实现一个CLI符号降级库附设计思路与代码【免费下载链接】figuresUnicode symbols with fallbacks for older terminals项目地址: https://gitcode.com/gh_mirrors/fi/figures开发 Node.js 命令行工具的同学可能都遇到过这种糟心场景在你自己机器上一切正常用户却在老版本 Windows 终端里看到一排乱码和豆腐块。开源项目figures正是为解决这个问题而生的一个 CLI 符号降级库Unicode symbols with fallbacks for older terminals——它能在运行时刻自动检测终端的 Unicode 支持情况把✔这样的符号安全地降级为√。整个库的核心实现只有 280 行左右是学习 CLI 工程化设计的绝佳小样本。为什么老终端会显示乱码先理解降级二字Windows 控制台Console Host / CMD只支持有限的字符集CP437。像✔、ℹ、⚠这些 Unicode 符号在这些终端上根本无法渲染直接输出就会变成问号或空白。所以符号降级库的目标很明确检测——判断当前终端是否支持 Unicode切换——支持就输出精美符号不支持就输出一套长得像但肯定能显示的替代符号透明——业务代码只写一套逻辑切换过程完全无感。figures 在 readme.md 里给出的效果对比符号名支持 Unicode降级后tick✔√cross✘×pointer❯checkboxOff☐[ ]smiley㋡☺3分钟读懂 figures4 个核心导出打开 index.js你会发现整个库对外只暴露了 4 个导出这也是整个降级库设计的骨架导出类型作用figures默认导出对象自动适配的符号表绝大多数场景用这个就够了mainSymbols对象终端支持 Unicode 时使用的原始符号fallbackSymbols对象不支持时使用的降级符号replaceSymbols(string)函数把一段已含符号的字符串整体做降级替换核心决策逻辑在 index.js 第 277-279 行只有三行const shouldUseMain isUnicodeSupported(); const figures shouldUseMain ? mainSymbols : fallbackSymbols; export default figures;注意这里的关键设计环境检测只发生一次在模块加载时完成之后每次取符号都是普通对象属性访问零运行时开销。检测能力来自依赖is-unicode-supported见 package.json 的 dependencies它综合考虑了 Windows 版本、TERM 环境变量等因素——这一点后面造自己的库时会展开讲。设计思路一符号表拆成公共层 特化层如果你直接数 index.js 会发现里面有个 190 多行的common对象第 3-198 行盒线─│┌└、箭头↑↓→、数学符号≈≤∞、分数½⅓¾……这些符号在 CP437 终端上本来就能正常显示根本不需要降级。真正需要降级的只有 34 个特化符号所以作者把它们单独拆出来specialMainSymbols第 200-235 行tick: ✔、info: ℹ这类原始符号specialFallbackSymbols第 237-272 行一一对应的降级符号tick: √、info: i。然后通过对象展开合成两套完整符号表第 274-275 行export const mainSymbols {...common, ...specialMainSymbols}; export const fallbackSymbols {...common, ...specialFallbackSymbols};这个公共层 特化层的分层是整个设计里最值得抄的作业维护符号表时你只需要保证 34 对降级映射的正确性剩下 200 多个符号两套表天然共享既省代码又杜绝了两套表不一致的隐患。设计思路二replaceSymbols 只替换特化符号很多业务代码里已经硬编码了符号字符串比如日志模板✔ 构建完成。这时没法重新引用符号表figures 就提供了 index.js 第 284-294 行的replaceSymbols函数const replacements Object.entries(specialMainSymbols); export const replaceSymbols string { if (shouldUseMain) { return string; // 现代终端直接短路返回 } for (const [key, mainSymbol] of replacements) { string string.replaceAll(mainSymbol, fallbackSymbols[key]); } return string; };两个细节值得注意短路返回现代终端上直接return string不遍历不替换函数几乎零成本只遍历特化层替换表用的是specialMainSymbols的 34 个条目而不是 200 多个公共符号——因为公共符号根本不需要替换。动手实践实现一个迷你符号降级库把上面的设计思路串起来你自己也能写一个迷你版。下面按模块拆解完整工程可先克隆源码对照git clone https://gitcode.com/gh_mirrors/fi/figures。第一步定义特化符号对const common { bullet: ●, ellipsis: …, arrowRight: →, line: ─, lineVertical: │, // 这些老终端都能显示两套表共享 }; const specialMain { tick: ✔, cross: ✘, pointer: ❯, }; const specialFallback { tick: √, cross: ×, pointer: , }; export const mainSymbols {...common, ...specialMain}; export const fallbackSymbols {...common, ...specialFallback};第二步运行时刻检测一次环境import isUnicodeSupported from is-unicode-supported; const shouldUseMain isUnicodeSupported(); export default shouldUseMain ? mainSymbols : fallbackSymbols; 如果不想引依赖最简方案是判断process.platform win32且TERM_PROGRAM不是WindowsTerminal但这会漏掉大量情况生产环境仍建议用成熟检测库。第三步提供字符串替换兜底export const replaceSymbols string { if (shouldUseMain) return string; for (const [key, main] of Object.entries(specialMain)) { string string.replaceAll(main, fallbackSymbols[key]); } return string; };第四步用类型声明补齐最后一块拼图打开 index.d.ts共 268 行可以看到作者为每个符号都声明了readonly string类型让 TypeScript 用户在输入figures.时直接获得自动补全。符号表这种属性数量多但结构固定的对象手写类型反而是最直观的方案。至此一个麻雀虽小五脏俱全的 CLI 符号降级库就完成了结构可以和 figures 的 index.js 逐行对照。进阶技巧测试与工程化细节用结果等价断言写测试test.js 的写法很聪明。环境检测结果会随运行平台变化硬编码期望值必然在另一种平台上挂掉所以它定义了一个 helper第 5 行const result (main, fallback) isUnicodeSupported() ? main : fallback;断言写成t.is(figures.tick, result(✔, √))——在任意平台上运行测试都成立这正是测试环境相关代码的正确姿势。另外第 31-35 行还有个兜底测试遍历所有符号断言非空字符串防止将来有人往表里加空值导致降级后输出空白。生产环境的三个注意事项ESM 优先package.json 声明了type: module且要求 Node18新库直接跟进现代模块规范检测只做一次千万不要在每次取符号时都重新探测终端模块顶层算一次缓存即可降级符号也要长得像☐→[ ]而不是X视觉语义的一致性决定了降级体验的上下限挑选时可以在目标终端里逐个验证。小结figures 源码里的 3 个可复用设计公共层 特化层只维护真正需要降级的那部分映射大幅降低维护成本加载时检测一次 短路返回把环境判断的成本压缩到接近于零对象展开合成符号表{...common, ...special}让两套表永远结构对齐。这三个模式不仅适用于符号降级库对任何按运行环境切换资源的 CLI 工程主题、进度条样式、日志格式都有参考价值。下次再遇到老终端乱码你已经有底气自己动手造轮子了。【免费下载链接】figuresUnicode symbols with fallbacks for older terminals项目地址: https://gitcode.com/gh_mirrors/fi/figures创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考