📦 logger

用于语义格式化控制台消息的封装日志器。

¥An encapsulated logger for semantically formatting console messages.

鼓励 Docusaurus 生态系统中的包的作者使用此包来提供统一的日志格式。

¥Authors of packages in the Docusaurus ecosystem are encouraged to use this package to provide unified log formats.

API

它导出单个对象作为默认导出：logger。logger 具有以下特性：

¥It exports a single object as default export: logger. logger has the following properties:

• 一些有用的颜色。

  ¥Some useful colors.

  • red

  • yellow

  • green

  • bold

  • dim

• 格式化程序。这些函数都有签名 (msg: unknown) => string。请注意，不保证它们的实现。你应该只关心它们的语义。

  ¥Formatters. These functions all have the signature (msg: unknown) => string. Note that their implementations are not guaranteed. You should only care about their semantics.

  • path：格式化文件路径。

    ¥path: formats a file path.

  • url：格式化 URL。

    ¥url: formats a URL.

  • name：格式化标识符。

    ¥name: formats an identifier.

  • code：格式化代码片段。

    ¥code: formats a code snippet.

  • subdue：抑制文本。

    ¥subdue: subdues the text.

  • num：格式化一个数字。

    ¥num: formats a number.

• interpolate 功能。它是一个模板字面量标签。语法如下。

  ¥The interpolate function. It is a template literal tag. The syntax can be found below.

• 记录功能。所有日志记录函数都可以用作普通函数（类似于 console.log 系列，但只接受一个参数）或模板字面量标记。

  ¥Logging functions. All logging functions can both be used as normal functions (similar to the console.log family, but only accepts one parameter) or template literal tags.

  • info：打印信息。

    ¥info: prints information.

  • warn：打印出应注意的警告。

    ¥warn: prints a warning that should be paid attention to.

  • error：打印一个错误（不一定会停止程序），表明存在严重问题。

    ¥error: prints an error (not necessarily halting the program) that signals significant problems.

  • success：打印一条成功消息。

    ¥success: prints a success message.

• report 功能。它采用 ReportingSeverity 值（ignore、log、warn、throw）并根据严重性报告消息。

  ¥The report function. It takes a ReportingSeverity value (ignore, log, warn, throw) and reports a message according to the severity.

error formatter一句话

请注意，error 消息即使没有挂起程序，也可能会引起混乱。当用户检查日志并发现 [ERROR] 时，即使构建成功，他们也会认为出现了问题。谨慎使用它。

¥Beware that an error message, even when it doesn't hang the program, is likely going to cause confusion. When users inspect logs and find an [ERROR], even when the build succeeds, they will assume something is going wrong. Use it sparingly.

Docusaurus 仅在抛出错误之前立即打印消息时，或者当用户将 onBrokenLink 等的报告严重性设置为 "error" 时才使用 logger.error。

¥Docusaurus only uses logger.error when printing messages immediately before throwing an error, or when user has set the reporting severity of onBrokenLink, etc. to "error".

此外，warn 和 error 将为整个消息着色，以便更好地引起注意。如果要打印大段有关错误的帮助文本，最好使用 logger.info。

¥In addition, warn and error will color the entire message for better attention. If you are printing large blocks of help text about an error, better use logger.info.

使用模板字面量标签

¥Using the template literal tag

模板字面量标记评估嵌入的模板和表达式。interpolate 返回一个新字符串，而其他日志记录函数则打印它。下面是一个典型用法：

¥The template literal tag evaluates the template and expressions embedded. interpolate returns a new string, while other logging functions prints it. Below is a typical usage:

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]+= 形式的标志（几个小写字母，后跟一个等号，直接位于嵌入表达式之前）。如果表达式前面没有任何标志，则按原样打印出来。否则，它会使用格式化程序之一进行格式化：

¥An embedded expression is optionally preceded by a flag in the form [a-z]+= (a few lowercase letters, followed by an equals sign, directly preceding the embedded expression). If the expression is not preceded by any flag, it's printed out as-is. Otherwise, it's formatted with one of the formatters:

• path=：path

• url=：url

• name=：name

• code=：code

• subdue=：subdue

• number=：num

如果表达式是一个数组，则其格式为 \n- ${array.join('\n- ')}\n（注意它会自动获取前导行结尾）。每个成员都单独格式化，项目符号不格式化。所以你会看到上面的消息打印为：

¥If the expression is an array, it's formatted by `\n- ${array.join('\n- ')}\n` (note it automatically gets a leading line end). Each member is formatted by itself and the bullet is not formatted. So you would see the above message printed as: