企业官网建设流程全解析

• 开发工具
• CLI

consola 是一款面向 Node.js 与浏览器环境的优雅控制台日志库，其 CHANGELOG.md 完整记录了从 0.1.0 到 3.4.2 的全部演进轨迹。本文以该变更记录为骨架，逐版本解读 3.x 时代的 TypeScript 重写、子路径导出、交互式 prompt、box 与 tree 工具函数等关键能力，并结合仓库源码（src、test、examples）给出可验证的实现细节，帮助你理解每个版本背后的设计决策、破坏性变更与踩坑修复，从而在项目中安全升级、合理选用 API。

一、版本脉络总览：从 0.1.0 到 3.4.2

根据 CHANGELOG.md，consola 的演进可划分为三个时代：

当前仓库 package.json 中版本号为3.4.2，与 CHANGELOG 顶部最新条目一致。整个演进的核心脉络是：从"控制台包装器"逐步走向"带交互提示、可插拔 reporter、可轻量裁剪的通用日志与 CLI 工具集"。

二、v3.0.0：TypeScript 重写与两大破坏性变更

v3.0.0 是 consola 历史上最重大的转折点，CHANGELOG 明确标注了两项 Breaking Changes：

2.1 ⚠️ 用 TypeScript 重写整个项目

此前 consola 以 JavaScript 实现，v3.0.0 起全部代码迁移到 TypeScript（对应提交4479d2f）。从源码结构可以印证：当前 src 目录下所有实现（consola.ts、constants.ts、types.ts、prompt.ts 等）均为.ts文件，且配套提供了 basic.d.ts、browser.d.ts、core.d.ts、utils.d.ts 等顶层类型声明文件，同时开启严格类型检查（Strict typechecks）。

伴随重写还有一系列内部重构：

• 日志级别与类型收敛到常量模块：⚠️ 将LogLevels、LogTypes移至 src/constants.ts，并合并LogTypeLiteral与logtype为统一的LogType类型；
• 移除json与winston两个 reporter：为瘦身砍掉内置的 JSON 与 winston 输出，JSON 输出改为通过自定义 reporter 实现（参见 examples/json.ts）；
• 所有选项收敛到consola.options：不再在多处重复保存配置（Move all options to consola.options without duplication）；
• spam 防刷逻辑收敛进_lastLog对象：见 src/consola.ts 的_lastLog字段；
• 移除全局async选项、移除globalThis缓存，并统一global改为globalThis。

2.2 新增能力：prompt、fail、trace 与 createConsola

v3.0.0 一口气引入了多个对使用者影响深远的 API：

• consola.prompt交互式提示（PR #170）：支持text、confirm、select、multiselect四种类型，底层交互体验由clack提供，完整用法见 examples/prompt.ts；
• consola.fail日志级别（PR #153）：与success相对，表示操作失败，级别同为 3（见 src/constants.ts）；
• consola.trace输出堆栈（PR #151）：type 为trace时，fancy reporter 会构造 Error 并渲染堆栈，见 src/reporters/fancy.ts；
• 暴露createConsola与命名导出（ef6e5e5）：从此import { consola, createConsola } from "consola"成为标准用法，src/index.ts、src/core.ts 均从./shared重新导出Consola、LogLevels、LogTypes及各类类型；
• 支持字面量形式的 logLevel（PR #133）：level既可传数字也可传日志类型名，src/consola.ts 的_normalizeLogLevel负责解析；
• 测试环境下默认 logLevel 为 1（PR #134）：src/index.ts 中_getDefaultLogLevel在isTest时返回LogLevels.warn（即 1）。test/consola.test.ts 直接断言createConsola().level为 1，可验证该行为。

2.3 性能优化：chalk → colorette，移除 dayjs

v3.0.0 将颜色库从chalk换成更轻量的colorette（当前 src/utils/color.ts 即基于 colorette 实现，并内联了 ANSI 颜色定义），同时移除dayjs时间依赖，从依赖层面大幅压缩体积。这两项属于"性能提升"而非"功能增强"，CHANGELOG 以 🔥 Performance 分类标注。

2.4 修复与细节

v3.0.0 还修复了一批类型与行为问题：给 mock 函数补充.raw（987dadc）、修正颜色格式工具的默认值、CONSOLA_LEVEL环境变量正确传入 defaults（PR #129，见 src/index.ts）、fancy reporter 在无法确定终端宽度时把时间与 tag 显示在右侧（PR #128）等；构建侧则改用向后兼容的 CJS wrapper 承载默认导出（e2e6aa6）。

三、v3.0.1 ~ v3.0.2：稳定性与边界修复

这两个补丁版本聚焦真实运行环境的边界问题：

• Worker 支持：utils 改用默认的stream.write（PR #173），避免在 worker 线程中因自定义 write 导致异常；
• wrapStd 包装 stdout/stderr：wrapStd现在会正确包装options.stdout与options.stderr（ab59db6），而不仅是进程默认流，相关实现见 src/consola.ts；
• fancy 徽章降级：无法确定宽度时改用更精简的徽章样式（ad24029）；
• mockTypes 基于 options.types 进行 mock（f9d86b6）：修复了不按自定义 types mock 的问题；
• reporters 改为具名导出：BasicReporter、FancyReporter、BrowserReporter以具名导出方式暴露，便于按需引用。

四、v3.1.0：子路径导出与 fancy 开关

v3.1.0 是"按需裁剪"理念落地的关键版本：

• /basic、/core、/browser子路径导出（PR #178）：从 package.json 的exports字段可以看到./basic、./core、./utils、./browser均有独立的 import/require/types 映射。其中consola/basic使用纯 BasicReporter（src/basic.ts）、consola/browser使用 BrowserReporter 与浏览器原生prompt/confirm（src/browser.ts）、consola/core仅包含核心类不带任何 reporter（src/core.ts），可节省约 80% 的包体积；
• fancy选项（PR #177）：createConsola({ fancy: true | false })可显式控制是否使用 fancy reporter。默认逻辑是isCI || isTest时回退到 BasicReporter（见 src/index.ts），该行为源自 v2.2.4 "仅 CI 与测试环境使用 basic reporter" 的延续。

五、v3.2.x：box、utils 子路径与 fancy 视觉增强

v3.2.x 集中补齐了"输出美化"的工具矩阵：

5.1consola.box边框输出（PR #193）

新增box日志类型与box()工具函数，实现在 src/utils/box.ts：

• 内置 8 种边框预设：solid、double、doubleSingle、doubleSingleRounded、singleThick、singleDouble、singleDoubleRounded、rounded（src/utils/box.ts）；
• 样式选项borderColor（默认white）、valign（默认center）、padding（默认 2）、marginLeft/marginTop/marginBottom（默认 1），见 src/utils/box.ts；
• v3.2.1 修复了singleThick预设命名问题（PR #201）；
• v3.2.3 将box的 style 选项放宽为Partial<BoxStyle>（PR #210），允许只覆盖部分样式；
• 完整示例见 examples/box.ts。

5.2consola/utils子路径与 Color utils（PR #199、#200）

新增consola/utils子路径导出，把纯函数工具独立成可复用集合，当前包含：

• 字符串处理：stripAnsi、centerAlign、rightAlign、leftAlign、align（src/utils/string.ts）；
• 颜色工具：colors、getColor、colorize（src/utils/color.ts）；
• 边框：box（src/utils/box.ts）；
• 树形：formatTree（v3.3.0 加入，见下文）。

5.3 fancy reporter 支持下划线与其他修复

• 下划线样式（PR #191）：_underlined_文本会被渲染为下划线样式，由 src/reporters/fancy.ts 的characterFormat处理；v3.2.1 进一步修正了带前后空格的下划线样式（PR #203）；
• 保留 tag 大小写（PR #190）：不再把 tag 强制小写；
• mock 继承（PR #183）：create/withTag产生的子实例会继承父实例的 mock 行为，src/consola.ts 中create()会检查this._mockFn并对新实例重新mockTypes；
• select/multiselect 返回类型修正（PR #197）：修复了单/多选的类型推断。

六、v3.3.x：formatTree、prompt 取消策略与 error cause

v3.3.x 是"交互体验与错误诊断"深度打磨的版本：

6.1formatTree树形输出（PR #223、#267）

新增formatTree工具（src/utils/tree.ts），可将嵌套结构渲染为带├─/└─分支的树：

• 节点支持字符串或{ text, children?, color? }对象；
• 选项支持color（整体颜色）、prefix（默认两个空格）、maxDepth（PR #267 新增的最大深度截断）与ellipsis（默认...）；
• 示例见 examples/tree.ts。

6.2 prompt：可配置取消策略（PR #325）与类型导出（PR #301）

此前用户按 Ctrl+C 取消 prompt 时一律按默认值解析；v3.3.0 起可通过{ cancel: ... }配置五种策略，实现在 src/prompt.ts 的handleCancel中：

• "default"：以default或initial值解析（默认行为）；
• "undefined"：以undefined解析；
• "null"：以null解析；
• "symbol"：以Symbol.for("cancel")解析（即kCancel）；
• "reject"：抛出一个名为ConsolaPromptCancelledError的 Error 拒绝 Promise。

同时所有 prompt 选项类型（TextPromptOptions、ConfirmPromptOptions、SelectPromptOptions、MultiSelectOptions、PromptOptions）从 src/prompt.ts 具名导出，并在 src/shared.ts 统一 re-export。

6.3 错误报告支持cause链（PR #308）

当 Error 带有cause时，BasicReporter 会递归格式化整条 cause 链，并以[cause]:前缀与逐级缩进区分层级，见 src/reporters/basic.ts（errorLevel每深入一层递增 1）。

6.4 其他修复

• select/multiselect 使用initial（PR #232）：修复初始值不生效的问题；
• box 标题颜色与边框一致（PR #236）：标题不再单独取色；
• fancy 在Intl不可用时回退（v3.3.1，PR #326）：src/reporters/fancy.ts 中stringWidth会先检测Intl.Segmenter，不可用则退回stripAnsi(str).length；
• 构建与类型：修复子路径类型（PR #265）、为浏览器构建补充require条件（PR #243）、修复select类型返回值（PR #238）；
• 工程化：引入 vitest 测试框架（PR #182），当前 test/consola.test.ts 即基于 vitest。

七、v3.4.x：@clack/prompts 上游化与宽度计算修复

v3.4.x 把 prompt 交互层切换到官方上游@clack/prompts（v3.4.0，PR #332），并围绕"宽度计算"做了两轮精准修复：

• v3.4.0：box 宽度计算排除 ANSI 转义序列字符（PR #336），即 src/utils/box.ts 中宽度计算使用stripAnsi(line).length而非原始长度，避免着色文本撑破边框；
• v3.4.2：box 宽度计算纳入标题宽度（PR #362），src/utils/box.ts 的Math.max(..., opts.title ? stripAnsi(opts.title).length : 0)正是该修复的实现；
• v3.4.1：从堆栈中移除所有 message 行（PR #356），让 src/utils/error.ts 的parseStack只保留干净的调用帧；
• v3.4.2：导出 tree utils（PR #349），formatTree及相关类型可通过consola/utils稳定引用；同时清理无用依赖（PR #361）；
• 构建：v3.4.0 更新 exports 以适配 node16 的 TypeScript 解析（PR #331）；该改动曾于 v3.3.2 引入（同时为 string-width 打了 node 14 补丁）、v3.3.3 回退，最终在 v3.4.0 重新落地——这一来一回正好说明node16 module resolution 的 exports 调整需要谨慎验证，升级时务必关注此类构建层变更。

八、回溯 2.x：spam 防刷、mock 与全局接管

v2.x 奠定了 consola 的经典能力，CHANGELOG 记录了它们的诞生顺序：

8.1 spam 防刷机制（v2.8.0 ~ v2.14.0）

• v2.8.0 引入 spam 预防（7da806b），v2.9.0 支持统计重复次数（197a6b3），v2.14.0 改进 throttle 逻辑（5314eee）；
• 当前实现位于 src/consola.ts：相同日志在throttle（默认 1000ms）窗口内重复超过throttleMin（默认 5）次会被合并，最终输出时追加(repeated N times)提示；
• test/consola.test.ts 精确验证了该行为：10 次相同日志最终只输出 7 条，末条 args 为["SPAM", "(repeated 4 times)"]。

8.2 mockTypes 与别名体系（v2.1.0）

v2.1.0 引入mockTypes（a332890）与别名机制（cbea7bd）。当前 src/consola.ts 维护了完整的向后兼容别名：add、remove、clear、withScope、mock、pause、resume。README 中的 mock 用法（Jest 的jest.fn()、Vitest 的vi.fn()）配合wrapAll()可在测试中拦截全部日志输出。

8.3 全局接管与暂停恢复

v2.0.0 起提供wrapConsole/restoreConsole、wrapStd/restoreStd、pauseLogs/resumeLogs。实现细节：

• wrapConsole把 console 各方法备份为__type后替换为对应类型的.raw（src/consola.ts）；
• wrapStd包装 stdout/stderr 的write为log.raw（src/consola.ts）；
• 暂停时日志进入全局队列，恢复时按序重放（src/consola.ts）；
• 配套示例见 examples/wrap-console.ts、examples/wrap-std.ts。

8.4 formatOptions 与浏览器能力（v2.2.0 ~ v2.15.0）

• v2.2.0 支持formatOptions（7ed640f），v2.15.0 允许formatOptions.date隐藏时间（PR #101）；
• v2.11.0 浏览器端支持 printf 风格格式化字符串（PR #66）；
• v2.7.0 优化宽度逻辑：宽度 < 80 时始终隐藏右侧信息（07d8246），并在空间不足时智能隐藏时间与 tag（00a375f）——这些行为在 src/reporters/fancy.ts 中仍可看到痕迹（space > 0 && columns >= 80才把 tag/date 放到右侧）；
• v2.12.0 补齐 reporter 的 TypeScript 定义（PR #94）。

九、回溯 1.x：从 0.1.0 到 2.0 的奠基

• v0.1.0（2018-03-31）：首个版本，提供与 console 兼容的日志类型（96a8162）；
• v1.1.0：不依赖ora重写 FancyReporter（73c1ddc）；
• v1.2.0：basic reporter 支持additional字段（b50cad8）、按需引入 lodash 方法优化体积（91065e4）；
• v1.3.0：支持额外日志参数（8b6d3d2）、防止多版本 consola 实例冲突（0bce262）；
• v1.4.0：支持自定义附加样式（PR #18）、fancy 支持icon字段（0123bed）；
• v1.4.4：暴露global.consola（558cae5）。

十、结合源码的关键实现速览

把 CHANGELOG 的条目映射到当前源码，可以得到几条"版本演进即代码现状"的印证链：

十一、如何在项目中跟随版本演进

1. 升级前阅读对应版本段：CHANGELOG 中带 ⚠️ 的条目即为 Breaking Changes（v3.0.0 的 TypeScript 重写、constants 收敛，以及 2.0 时代的 internal 重构与additionalStyle→additionalColor重命名），升级 v2 → v3 前务必确认这两处；
2. 按需裁剪入口：体积敏感场景使用consola/basic或consola/core，Node 服务端默认入口用 fancy，浏览器用consola/browser（src/browser.ts 内置了基于confirm/prompt的浏览器 prompt 实现）；
3. 对照示例验证行为：prompt、box、tree、spam 防刷、raw 输出、std/console 接管均有对应示例（examples），其中 examples/raw.ts 演示了.raw强制按纯对象输出、examples/spam.ts 演示防刷合并效果；
4. 用环境变量控制级别：Node 与 basic 构建支持CONSOLA_LEVEL环境变量覆盖日志级别（src/index.ts、src/basic.ts），但 browser 与 core 构建不支持（README 已明确说明）；
5. 关注构建层变更：v3.3.2 → v3.3.3 → v3.4.0 的node16exports 反复调整表明，使用 TS 的node16/nodenextmoduleResolution 时需在升级后重跑类型检查。

综上，consola 的 CHANGELOG 不只是"变更流水账"，它完整记录了项目从单文件 console 包装器走向模块化、类型安全、可交互、可裁剪的通用日志工具的架构决策全过程。对使用者而言，理解这份演进史，就等于理解了当前 API 的设计动机与取舍边界。

• 开发工具
• CLI