📦 logger

一个用于语义化格式化控制台消息的封装日志工具。

道格龙（Docusaurus）生态内的包作者建议使用此包，以实现统一的日志格式。

API

默认导出单个对象：logger。logger 具有以下属性：

• 一些常用颜色：
  • red
  • yellow
  • green
  • bold
  • dim
• 格式化器。这些函数签名均为 (msg: unknown) => string。注意其具体实现不保证稳定，仅需关注其语义：
  • path：格式化文件路径。
  • url：格式化 URL。
  • name：格式化标识符。
  • code：格式化代码片段。
  • subdue：弱化文本显示。
  • num：格式化数字。
• interpolate 函数。它是一个模板字符串标签，语法见下文。
• 日志输出函数。所有日志函数既可作为普通函数（类似 console.log，但只接受一个参数），也可作为模板字符串标签使用：
  • info：输出信息。
  • warn：输出需要注意的警告。
  • error：输出错误（不一定终止程序），用于提示严重问题。
  • success：输出成功消息。
• report 函数。接收一个 ReportingSeverity 值（ignore、log、warn、throw），并根据严重性输出消息。

关于 error 格式化器的说明

请注意，即使 error 消息不会导致程序挂起，也极易引起用户困惑。当用户在日志中看到 [ERROR] 时，即使构建成功，也会以为出现了问题。请谨慎使用。

道格龙仅在抛出错误前，或用户将如 onBrokenLink 等报告级别设为 "error" 时，才会使用 logger.error。

此外，warn 和 error 会为整条消息着色以增强提示。如果你要输出大段错误帮助文本，建议使用 logger.info。

模板字符串标签的用法

模板字符串标签会对模板和插入表达式进行求值。interpolate 返回新字符串，其他日志函数则直接输出。典型用法如下：

import logger from '@docusaurus/logger';

logger.info`Hello name=${name}! You have number=${money} dollars. Here are the ${
  items.length > 1 ? 'items' : 'item'
} on the shelf: ${items}
To buy anything, enter code=${'buy x'} where code=${'x'} is the item's name; to quit, press code=${'Ctrl + C'}.`;

插入表达式前可选加上 [a-z]+= 形式的标志（小写字母加等号，紧挨表达式）。无标志时按原样输出，有标志时用对应格式化器处理：

• path=：path
• url=：url
• name=：name
• code=：code
• subdue=：subdue
• number=：num

如果表达式是数组，会被格式化为 `\n- ${array.join('\n- ')}\n`（自动带前导换行）。每个成员单独格式化，项目符号不做特殊处理。所以上述消息会被打印为：