JSDoc (Github地址) 是一种用于 JavaScript 代码的 API 文档生成工具，它允许开发者通过注释的方式为代码添加文档说明。JSDoc 可以解析这些注释，并生成 HTML 格式的文档，帮助开发者更好地理解和使用代码。JSDoc 采用了 Apache License 2.0 开源协议。VS Code 内置了对 JSDoc 风格注释的支持，在 Javascript 和 TypeScript 代码中书写 JSDoc 风格的注释会自动高亮。

JSDoc 的实现原理

JSDoc 的实现原理主要基于注释解析。开发者在 JavaScript 代码中使用特定格式的注释（通常是以 /** 开头的多行注释），JSDoc 工具会扫描这些注释并提取信息。提取的信息包括函数的参数、返回值、类型、描述等。然后，JSDoc 会将这些信息转换为结构化的文档格式（如 HTML），并生成相应的文档。

JSDoc 常见用法

1. 基本注释格式：

1
2
3
4
5
6
7
8

/**
 * 函数描述
 * @param {类型} 参数名 参数描述
 * @returns {类型} 返回值描述
 */
function example(param) {
  return param;
}

2. 类型注释：
   可以使用 {} 来指定参数和返回值的类型，例如：

1
2
3
4
5
6
7
8

/**
 * @param {string} name 用户名
 * @param {number} age 用户年龄
 * @returns {boolean} 是否成年
 */
function isAdult(name, age) {
  return age >= 18;
}

3. 模块和类注释：
   JSDoc 也支持模块和类的文档注释：

1
2
3
4
5
6
7
8
9
10
11
12

/**
 * @class
 */
class Person {
  /**
   * @constructor
   * @param {string} name
   */
  constructor(name) {
    this.name = name;
  }
}

5. 使用名称路径
   如果涉及到一个 JavaScript 变量，这个变量在文档中的其他地方，你必须提供一个唯一标识符映射到该变量。名称路径提供了一种这样做的方法，并且消除实例成员，静态成员和内部变量之间的歧义

1
2
3
4
5
6
7
8

/**
 * Person#say  // 名为"say"的实例方法
 * Person.say  // 名为"say"的静态方法
 * Person~say  // 名为"say"的内部函数
 * @module foo/bar // 名为"foo/bar"的模块
 * @external String // 内置的 string 对象
 * @event module:foo/bar.event:MyEvent // 一个名为 module:foo/bar.event:MyEvent 的事件
 */

JSDoc 块标签与内联标签

JSDoc支持两种不同类型的标签：

· 块标签(Block): 这是在一个 JSDoc 注释的最高级别。
· 内联标签(inline): 块标签文本中的标签或说明。

块标签通常会提供有关代码的详细信息，如一个函数接受的参数。内联标签通常链接到文件的其他部分，类似于HTML中的锚（<a>）标记。

块标签总是以 @ 符号开头。除了 JSDoc 注释中最后一个块标记，每个块标签后面必须跟一个换行符。

内联标签也以 @ 符号开。然而，内联标签及其文本必须用花括号 { 与 } 括起来。 { 表示行内联标签的开始，而 } 表示内联标签的结束。如果标签文本中包含 }，则必须用 \ 进行转义。在内联标签后，你并不需要使用一个换行符。

大多数 JSDoc 标签是块标签。一般来说，当这个网站上说“JSDoc 标签”，我们真正的意思是“块标签”。block-tags 记录了在 JSDoc 中所有识别的块标签。

如下是一个示例，@param 是一个块标签，而 {@link} 是一个内联标签：

1
2
3
4
5
6
7
8

/**
 * Set the shoe's color. Use {@link Shoe#setSize} to set the shoe size.
 *
 * @param {string} color - The shoe's color.
 */
Shoe.prototype.setColor = function (color) {
  // ...
};

JSDoc 命令行

JSDoc 可以使用命令行工具生成文档：

1
2

npm install -g jsdoc
jsdoc yourfile.js

执行该命令后，JSDoc 会在 /out 目录下生成当前目录的文档。JSDoc 支持大量的命令行选项，其中许多选项有长和短两种形式。

JSDoc 配置文件

JSDoc 的命令行选项也可以在配置文件中指定。要使用配置文件运行 JSDoc，需要使用 -c 命令行选项（例如，jsdoc -c /path/to/conf.json 或 jsdoc -c /path/to/conf.js）。

默认配置如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "plugins": [], // 无插件加载
  "recurseDepth": 10, // 如果使用 -r 命令行标志启用递归，JSDoc 将搜索 10 层深的文件
  "source": { // 源代码配置
    "includePattern": ".+\\.js(doc|x)?$", // 只有以 .js、.jsdoc 和 .jsx 结尾的文件将会被处理
    "excludePattern": "(^|\\/|\\\\)_" // 任何文件或目录如果以 _ 开始将被忽略
  },
  "sourceType": "module", // "script"，表示脚本文件，"module" 表示模块文件
  "tags": { // 标签配置
    "allowUnknownTags": true, // 允许使用未知的标签
    "dictionaries": ["jsdoc", "closure"] // 允许使用 jsdoc 标签 和 [closure 标签](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags)
  },
  "templates": { // 模板配置
    "cleverLinks": false, // 链接到源码
    "monospaceLinks": false // 源码行号
  }
}

JSDoc 插件

在 JSDoc 中，插件的作用是扩展 JSDoc 的功能，比如添加新的标签、解析新的语法等。首先，需要创建一个包含插件代码的 Javascript 模块，然后将该模块添加到 JSDoc 的配置文件 plugin 参数中，以启用插件。

一个 JSDoc 插件可以：
· 定义事件处理程序
· 定义自定义标签，如 @author、@version 等。
· 定义一个抽象的解析器，用于解析自定义标签。

JSDoc 插件的事件处理程序包括：
Event: parseBegin: JSDoc 开始加载和解析源文件之前，parseBegin 事件被触发。插件可以通过修改事件的内容，来控制哪些文件将被 JSDoc 解析。(>=JSDoc@3.2.0)
Event: fileBegin: 当解析器即将解析一个文件 fileBegin 事件触发。如果需要，插件可以使用此事件触发每个文件的初始化。
Event: beforeParse: beforeParse 事件在解析开始之前被触发。插件可以使用此方法来修改将被解析的源代码。
Event: jsdocCommentFound: 每当 JSDoc 注释被发现，jsdocCommentFound 事件就会被触发。注释可以或不与任何代码相关联。你可以在注释被处理之前使用此事件修改注释的内容。(>=JSDoc@3.5.0)
Event: symbolFound: 当解析器在代码中遇到一个可能需要被文档化的标识符时，symbolFound 事件就会被触发。
Event: newDoclet: newDoclet事件是最高级别的事件。新的 doclet 已被创建时，它就会被触发。这意味着一个 JSDoc 注释或标识符已被处理，并且实际传递给模板的 doclet 已被创建。
Event: fileComplete: 当解析器解析完一个文件时，fileComplete 事件就会被触发。插件可以使用这个事件来触发每个文件的清理。
Event: parseComplete: JSDoc 解析所有指定的源文件之后，parseComplete 事件就会被触发。(>=JSDoc@3.2.0)
Event: processingComplete: JSDoc 更新反映继承和借来的标识符的解析结果后，processingComplete 事件被触发。(>=JSDoc@3.2.1)

JSDoc 包含一个 Markdown 插件来自动将 Markdown 格式文本转换成 HTML。可以通过如下配置开启：

1
2
3
4
5
6
7
8
9

{
    "plugins": ["plugins/markdown"],
    "markdown": {
      "tags": ["foo", "bar"], // 扩展需解析 markdown 的标签
      "excludeTags": ["author"],  // 不解析 markdown 的标签
      "hardwrap": true, // 是否强制换行(>=JSDoc@3.4.0)
      "idInHeadings": true, // 是否在标题中添加 id(>=JSDoc@3.4.0)
    }
}

Markdown 插件默认只解析特定的 JSDoc 标签（@author,@classdesc,@description,@param,@property,@return,@see,@throws），可以通过在配置文件的 markdown.tags 字段中添加标签来扩展解析范围。可以通过 markdown.excludeTags 字段来排除默认标签的解析。

其他功能

· JSDoc 支持通过 --tutorials 或 -u 选项提供 JSDoc 要搜索的教程目录从而为 API 文档添加教程。
· JSDoc 支持通过 --package 或 -P 选项指定 package.json 文件的路径从而在生成文档的时候自动使用 package.json 的信息。(>=JSDoc@3.3.0)
· JSDoc 支持通过 --readme 或 -R 选项指定将 README 文件中的信息合并到文档中。(>=JSDoc@3.3.0)

alias 命令用于为命令创建别名，以便简化输入和提高效率。

用法示例

1

alias ll='ls -la'

这个命令会创建一个别名 ll，用于执行 ls -la 命令。

常见用法

• 创建简单别名：

1

alias gs='git status'

这个命令会创建一个别名 gs，用于快速查看 Git 状态。

• 创建带参数的别名：

1

alias rm='rm -i'

这个命令会创建一个别名 rm，在删除文件时提示确认。

• 查看当前所有别名：

1

alias

这个命令会列出当前会话中所有已定义的别名。

• 删除别名：

1

unalias ll

这个命令会删除别名 ll。

• 将别名永久保存：
  可以将别名添加到用户的 ~/.bashrc 或 ~/.bash_aliases 文件中，以便在每次登录时自动加载。

1
2

echo "alias ll='ls -la'" >> ~/.bashrc
source ~/.bashrc

• 创建复杂的别名（使用函数）：

1

alias mygrep='grep --color=auto'

这个命令会创建一个别名 mygrep，在使用 grep 时自动启用颜色高亮。

• 使用别名时显示帮助信息：

1

alias h='history'

这个命令会创建一个别名 h，用于快速查看命令历史。

awk

awk 是一个强大的文本处理工具，主要用于模式扫描和处理。它可以从文本文件中提取和处理数据。

用法示例

1

awk '{print $1}' filename.txt

这个命令会打印 filename.txt 文件中每一行的第一个字段。

常见用法

• 统计文件中的行数：

1

awk 'END {print NR}' filename.txt

• 计算某一列的总和：

1

awk '{sum += $1} END {print sum}' filename.txt

• 过滤特定模式的行：

1

awk '/pattern/' filename.txt

cat

cat 命令用于连接文件并打印到标准输出，常用于查看文件内容。

用法示例

1

cat filename.txt

这个命令会打印 filename.txt 文件的所有内容。

常见用法

• 查看多个文件的内容：

1

cat file1.txt file2.txt

• 将文件内容输出到另一个文件：

1

cat filename.txt > newfile.txt

• 追加文件内容到另一个文件：

1

cat filename.txt >> existingfile.txt

• 显示行号：

1

cat -n filename.txt

cd

cd 命令用于更改当前工作目录。

用法示例

1

cd /path/to/directory

这个命令会将当前工作目录更改为指定的目录。

常见用法

• 返回上一级目录：

1

cd ..

• 返回用户主目录：

1

cd ~

• 切换到上一次访问的目录：

1

cd -

• 使用相对路径切换目录：

1

cd subdirectory/

这个命令会切换到当前目录下的 subdirectory 目录。

• 切换到多个目录（使用 pushd 和 popd）：

1
2
3

pushd /path/to/directory
# ... 在新目录中工作 ...
popd

这个命令会将当前目录推入目录栈并切换到指定目录，popd 则会返回到之前的目录。

chmod

chmod 命令用于更改文件或目录的权限。

用法示例

1

chmod 755 filename.txt

这个命令会将 filename.txt 的权限更改为可读、可写和可执行（所有者），可读和可执行（组和其他用户）。

常见用法

• 递归更改目录及其内容的权限：

1

chmod -R 755 directory_name

• 仅添加执行权限：

1

chmod +x filename.sh

• 仅移除写权限：

1

chmod -w filename.txt

• 设置特定权限（如只读）：

1

chmod 444 filename.txt

• 使用符号模式更改权限：

1
2
3

chmod u+x filename.txt  # 为文件所有者添加执行权限
chmod g-w filename.txt  # 从组中移除写权限
chmod o=r filename.txt  # 设置其他用户为只读权限

chown

chown 命令用于更改文件或目录的所有者和所属组。

用法示例

1

chown user:group filename.txt

这个命令会将 filename.txt 的所有者更改为 user，所属组更改为 group。

常见用法

• 仅更改文件的所有者：

1

chown user filename.txt

• 仅更改文件的所属组：

1

chown :group filename.txt

• 递归更改目录及其内容的所有者和所属组：

1

chown -R user:group directory_name

• 显示当前文件的所有者和所属组：

1

ls -l filename.txt

• 更改多个文件的所有者：

1

chown user1:usergroup file1.txt file2.txt

cp

cp 命令用于复制文件和目录。

用法示例

1

cp source.txt destination.txt

这个命令会将 source.txt 文件复制到 destination.txt。

常见用法

• 复制文件到另一个目录：

1

cp filename.txt /path/to/directory/

• 复制目录及其内容（使用 -r 选项）：

1

cp -r sourcedir/ targetdir/

• 复制并重命名文件：

1

cp filename.txt newname.txt

• 交互式复制（在覆盖文件前提示确认）：

1

cp -i filename.txt destination.txt

• 复制文件并保留文件属性：

1

cp -p filename.txt destination.txt

curl

curl 是一个用于在命令行中进行数据传输的工具，支持多种协议，包括 HTTP、HTTPS、FTP 等。

用法示例

1

curl http://example.com

这个命令会从 http://example.com 下载内容并打印到标准输出。

常见用法

• 下载文件：

1

curl -O http://example.com/file.txt

• 发送 POST 请求：

1

curl -X POST -d "param1=value1&param2=value2" http://example.com/api

• 添加请求头：

1

curl -H "Authorization: Bearer TOKEN" http://example.com/api

• 显示请求和响应的详细信息：

1

curl -v http://example.com

• 保存输出到文件：

1

curl -o output.txt http://example.com

df

df 命令用于显示文件系统的磁盘空间使用情况。

用法示例

1

df

这个命令会显示所有挂载的文件系统的磁盘使用情况。

常见用法

• 以人类可读的格式显示（例如，KB、MB、GB）：

1

df -h

• 显示特定文件系统的信息：

1

df /path/to/directory

• 显示所有文件系统，包括虚拟文件系统：

1

df -a

• 显示 inode 使用情况：

1

df -i

这个命令会显示每个文件系统的 inode 使用情况。

du

du 命令用于显示目录或文件的磁盘使用情况。

用法示例

1

du /path/to/directory

这个命令会显示指定目录及其子目录的磁盘使用情况。

常见用法

• 显示指定目录的总大小：

1

du -sh /path/to/directory

这个命令会以人类可读的格式（如 KB、MB、GB）显示指定目录的总大小。

• 显示每个子目录的大小：

1

du -h /path/to/directory

这个命令会以人类可读的格式显示指定目录下每个子目录的大小。

• 递归显示所有子目录的大小：

1

du -ah /path/to/directory

这个命令会显示指定目录及其所有子目录和文件的大小。

• 按大小排序显示：

1

du -sh /path/to/directory/* | sort -h

这个命令会显示指定目录下每个文件和子目录的大小，并按大小排序。

• 显示特定深度的目录大小：

1

du -h --max-depth=1 /path/to/directory

这个命令会显示指定目录下的每个子目录的大小，但只显示到第一层深度。

• 显示文件系统的使用情况：

1

du -x /path/to/directory

这个命令会限制 du 只计算指定目录所在的文件系统的大小。

echo

echo 命令用于在终端输出文本或变量的值。

用法示例

1

echo "Hello, World!"

这个命令会在终端打印 Hello, World!。

常见用法

• 输出变量的值：

1
2

name="Alice"
echo "Hello, $name!"

• 输出带有换行符的文本：

1

echo -e "Line 1\nLine 2"

• 不输出换行符：

1

echo -n "This is on the same line."

• 输出带有特殊字符的文本：

1

echo "This is a dollar sign: \$"

find

find 命令用于在目录中查找文件和目录，支持多种搜索条件。

用法示例

1

find /path/to/directory -name "filename.txt"

这个命令会在指定目录中查找名为 filename.txt 的文件。

常见用法

• 查找特定类型的文件：

1

find /path/to/directory -type f -name "*.txt"

这个命令会查找所有以 .txt 结尾的文件。

• 按文件大小查找：

1

find /path/to/directory -size +10M

这个命令会查找大于 10MB 的文件。

• 按修改时间查找：

1

find /path/to/directory -mtime -7

这个命令会查找最近 7 天内修改过的文件。

• 查找并执行命令：

1

find /path/to/directory -name "*.log" -exec rm {} \;

这个命令会查找所有 .log 文件并删除它们。

• 查找并显示详细信息：

1

find /path/to/directory -name "*.txt" -print

这个命令会查找所有 .txt 文件并打印其路径。

• 查找空文件：

1

find /path/to/directory -type f -empty

这个命令会查找所有空文件。

• 查找特定用户的文件：

1

find /path/to/directory -user username

这个命令会查找属于指定用户的文件。

grep

grep 命令用于在文件中搜索指定的模式，并打印匹配的行。

用法示例

1

grep "pattern" filename.txt

这个命令会在 filename.txt 文件中搜索包含 pattern 的行并打印出来。

常见用法

• 忽略大小写搜索：

1

grep -i "pattern" filename.txt

• 显示行号：

1

grep -n "pattern" filename.txt

• 递归搜索目录中的文件：

1

grep -r "pattern" /path/to/directory/

• 只显示匹配的部分：

1

grep -o "pattern" filename.txt

• 反向匹配（显示不包含模式的行）：

1

grep -v "pattern" filename.txt

head

head 命令用于显示文件的开头部分，默认情况下显示前 10 行。

用法示例

1

head filename.txt

这个命令会打印 filename.txt 文件的前 10 行。

常见用法

• 显示指定行数的开头部分：

1

head -n 5 filename.txt

这个命令会打印 filename.txt 文件的前 5 行。

• 显示多个文件的开头部分：

1

head file1.txt file2.txt

• 显示文件的字节数：

1

head -c 20 filename.txt

这个命令会打印 filename.txt 文件的前 20 个字节。

history

history 命令用于显示用户在当前会话中输入的命令历史记录。

用法示例

1

history

这个命令会列出当前用户在终端中输入的所有命令。

常见用法

• 显示最近的命令数量：

1

history 10

这个命令会显示最近输入的 10 条命令。

• 重新执行某条命令：

1

!n

其中 n 是命令在历史记录中的编号。例如，!5 会重新执行历史记录中编号为 5 的命令。

• 清空命令历史：

1

history -c

这个命令会清空当前会话的命令历史记录。

• 将历史记录保存到文件：

1

history > history.txt

这个命令会将当前会话的命令历史保存到 history.txt 文件中。

• 使用 grep 搜索历史记录：

1

history | grep "pattern"

这个命令会在历史记录中搜索包含 pattern 的命令。

• 在命令行中使用上一个命令：

1

!!

这个命令会重新执行上一个输入的命令。

kill/killall

kill 命令用于向进程发送信号，通常用于终止进程。

用法示例

1

kill PID

这个命令会向指定的进程 ID（PID）发送终止信号。

常见用法

• 强制终止进程：

1

kill -9 PID

这个命令会强制终止指定的进程。

• 发送其他信号（如停止进程）：

1

kill -STOP PID

• 查看所有进程并找到 PID：

1

ps aux | grep process_name

• 终止所有匹配的进程：

1

killall process_name

ls

ls 命令用于列出目录中的文件和子目录。

用法示例

1

ls

这个命令会列出当前目录中的所有文件和子目录。

常见用法

• 列出详细信息（包括权限、所有者、大小等）：

1

ls -l

• 列出所有文件，包括隐藏文件（以点开头的文件）：

1

ls -a

• 以人类可读的格式显示文件大小：

1

ls -lh

• 按时间排序列出文件：

1

ls -lt

• 递归列出所有子目录中的文件：

1

ls -R

• 列出特定类型的文件（例如，只列出目录）：

1

ls -d */

man

man 命令用于查看其他命令的手册页，提供命令的详细信息和用法。

用法示例

1

man command_name

这个命令会显示 command_name 的手册页。

常见用法

• 查看特定命令的手册页：

1

man ls

• 搜索手册页中的关键字：

1

man -k keyword

这个命令会列出所有包含 keyword 的手册页。

• 查看手册页的特定部分（例如，用户命令、系统调用等）：

1
2
3

man 1 command_name  # 用户命令
man 2 command_name  # 系统调用
man 3 command_name  # 库函数

• 在手册页中向上或向下滚动：
  使用 ↑ 和 ↓ 键进行滚动，使用 q 键退出手册页。

• 查看手册页的帮助信息：

1

man man

这个命令会显示 man 命令本身的手册页。

mv

mv 命令用于移动或重命名文件和目录。

用法示例

1

mv oldname.txt newname.txt

这个命令会将 oldname.txt 文件重命名为 newname.txt。

常见用法

• 移动文件到另一个目录：

1

mv filename.txt /path/to/directory/

• 移动并重命名文件：

1

mv filename.txt /path/to/directory/newname.txt

• 交互式移动（在覆盖文件前提示确认）：

1

mv -i filename.txt /path/to/directory/

• 强制移动（不提示确认）：

1

mv -f filename.txt /path/to/directory/

ps

ps 命令用于显示当前运行的进程信息。

用法示例

1

ps

这个命令会列出当前用户的所有进程。

常见用法

• 显示所有进程，包括其他用户的进程：

1

ps -e

• 显示详细信息：

1

ps -f

• 显示进程树：

1

ps -ejH

• 显示特定用户的进程：

1

ps -u username

• 显示与特定命令相关的进程：

1

ps -C command_name

pwd

pwd 命令用于显示当前工作目录的完整路径。

用法示例

1

pwd

这个命令会打印当前工作目录的绝对路径。

常见用法

• 在脚本中使用 pwd 获取当前目录：

1
2

current_dir=$(pwd)
echo "当前目录是: $current_dir"

• 与其他命令结合使用：

1

cd /path/to/directory && pwd

这个命令会切换到指定目录并显示该目录的路径。

rm

rm 命令用于删除文件和目录。

用法示例

1

rm filename.txt

这个命令会删除 filename.txt 文件。

常见用法

• 删除多个文件：

1

rm file1.txt file2.txt

• 递归删除目录及其内容（使用 -r 选项）：

1

rm -r directory_name

• 强制删除文件（不提示确认）：

1

rm -f filename.txt

• 交互式删除（在删除前提示确认）：

1

rm -i filename.txt

• 删除空目录：

1

rmdir directory_name

scp

scp 命令用于在本地和远程主机之间安全地复制文件。

用法示例

1

scp localfile.txt user@remotehost:/path/to/destination

这个命令会将本地的 localfile.txt 文件复制到远程主机的指定路径。

常见用法

• 从远程主机复制文件到本地：

1

scp user@remotehost:/path/to/remotefile.txt /local/path

• 递归复制整个目录：

1

scp -r localdir user@remotehost:/path/to/destination

• 使用特定端口进行连接：

1

scp -P 2222 localfile.txt user@remotehost:/path/to/destination

• 复制文件并保留文件属性：

1

scp -p localfile.txt user@remotehost:/path/to/destination

• 显示详细的传输过程：

1

scp -v localfile.txt user@remotehost:/path/to/destination

sed

sed 是一个流编辑器，用于对文本进行基本的转换和处理。

用法示例

1

sed 's/old/new/' filename.txt

这个命令会将 filename.txt 文件中每一行的第一个 old 替换为 new。

常见用法

• 替换文件中的所有匹配项：

1

sed 's/old/new/g' filename.txt

• 在特定行进行替换：

1

sed '2s/old/new/' filename.txt

这个命令会在第二行中将 old 替换为 new。

• 删除特定行：

1

sed '3d' filename.txt

这个命令会删除 filename.txt 文件的第三行。

• 直接修改文件（使用 -i 选项）：

1

sed -i 's/old/new/g' filename.txt

• 显示行号：

1

sed = filename.txt | sed 'N;s/\n/ /'

ssh

ssh 命令用于安全地远程登录到另一台计算机。

用法示例

1

ssh user@remotehost

这个命令会以 user 用户身份登录到 remotehost。

常见用法

• 使用特定端口进行连接：

1

ssh -p 2222 user@remotehost

• 在登录时执行命令：

1

ssh user@remotehost 'command_to_run'

• 使用密钥文件进行身份验证：

1

ssh -i /path/to/private_key user@remotehost

• 进行端口转发：

1

ssh -L local_port:remotehost:remote_port user@remotehost

• 复制文件到远程主机（使用 scp）：

1

scp localfile.txt user@remotehost:/path/to/destination

tail

tail 命令用于显示文件的结尾部分，默认情况下显示最后 10 行。

用法示例

1

tail filename.txt

这个命令会打印 filename.txt 文件的最后 10 行。

常见用法

• 显示指定行数的结尾部分：

1

tail -n 5 filename.txt

这个命令会打印 filename.txt 文件的最后 5 行。

• 实时查看文件的新增内容（类似于日志文件）：

1

tail -f filename.txt

• 显示多个文件的结尾部分：

1

tail file1.txt file2.txt

• 显示文件的字节数：

1

tail -c 20 filename.txt

这个命令会打印 filename.txt 文件的最后 20 个字节。

tar

tar 命令用于打包和压缩文件，常用于备份和传输文件。

用法示例

• 创建一个 tar 包：

1

tar -cvf archive.tar /path/to/directory

这个命令会将指定目录打包成 archive.tar 文件。

常见用法

• 创建一个压缩的 tar.gz 包：

1

tar -czvf archive.tar.gz /path/to/directory

这个命令会将指定目录打包并压缩成 archive.tar.gz 文件。

• 解压 tar 包：

1

tar -xvf archive.tar

这个命令会解压 archive.tar 文件。

• 解压 tar.gz 包：

1

tar -xzvf archive.tar.gz

这个命令会解压 archive.tar.gz 文件。

• 查看 tar 包内容：

1

tar -tvf archive.tar

这个命令会列出 archive.tar 文件中的内容。

top

top 命令用于实时显示系统中正在运行的进程和系统资源的使用情况。

用法示例

1

top

这个命令会打开一个动态更新的界面，显示当前系统的进程信息和资源使用情况。

常见用法

• 显示进程的详细信息：
  在 top 界面中，可以按 Shift + M 按内存使用量排序，按 Shift + P 按 CPU 使用量排序。

• 结束进程：
  在 top 界面中，按 k 键，然后输入要结束的进程 ID（PID），最后按 Enter。

• 刷新间隔：
  在 top 界面中，按 d 键可以设置刷新间隔（以秒为单位）。

• 显示帮助信息：
  在 top 界面中，按 h 键可以查看帮助信息。

• 退出 top：
  在 top 界面中，按 q 键可以退出。

touch

touch 命令用于创建空文件或更新文件的时间戳。

用法示例

1

touch filename.txt

这个命令会创建一个名为 filename.txt 的空文件，如果文件已存在，则更新其最后修改时间。

常见用法

• 创建多个空文件：

1

touch file1.txt file2.txt file3.txt

• 更新文件的时间戳：

1

touch existingfile.txt

• 创建带有特定时间戳的文件：

1

touch -t 202301010101 filename.txt

这个命令会将 filename.txt 的时间戳设置为 2023 年 1 月 1 日 01:01。

• 使用当前时间戳创建文件：

1

touch -a filename.txt

这个命令会更新 filename.txt 的访问时间为当前时间。

vi

vi 是一个强大的文本编辑器，广泛用于 Unix 和 Linux 系统中。

用法示例

打开文件：

1

vi filename.txt

这个命令会打开 filename.txt 文件进行编辑。

常见用法

• 进入插入模式：
  在命令模式下，按 i 进入插入模式，可以开始编辑文本。

• 保存并退出：
  在命令模式下，输入 :wq 保存文件并退出 vi。

• 仅保存：
  在命令模式下，输入 :w 仅保存文件而不退出。

• 退出不保存：
  在命令模式下，输入 :q! 强制退出而不保存更改。

• 删除行：
  在命令模式下，输入 dd 删除当前行。

• 撤销操作：
  在命令模式下，输入 u 撤销上一步操作。

• 查找文本：
  在命令模式下，输入 /pattern 查找指定的 pattern。

• 替换文本：
  在命令模式下，输入 :%s/old/new/g 将文件中的所有 old 替换为 new。

vim

vim 是 vi 的增强版，提供了更多功能和更好的用户体验。

用法示例

打开文件：

1

vim filename.txt

这个命令会打开 filename.txt 文件进行编辑。

常见用法

• 进入插入模式：
  在命令模式下，按 i 进入插入模式，可以开始编辑文本。

• 保存并退出：
  在命令模式下，输入 :wq 保存文件并退出 vim。

• 仅保存：
  在命令模式下，输入 :w 仅保存文件而不退出。

• 退出不保存：
  在命令模式下，输入 :q! 强制退出而不保存更改。

• 删除行：
  在命令模式下，输入 dd 删除当前行。

• 撤销操作：
  在命令模式下，输入 u 撤销上一步操作。

• 查找文本：
  在命令模式下，输入 /pattern 查找指定的 pattern。

• 替换文本：
  在命令模式下，输入 :%s/old/new/g 将文件中的所有 old 替换为 new。

• 显示行号：
  在命令模式下，输入 :set number 显示行号。

• 语法高亮：
  在命令模式下，输入 :syntax on 启用语法高亮。

wget

wget 是一个用于从网络下载文件的命令行工具，支持 HTTP、HTTPS 和 FTP 协议。

用法示例

1

wget http://example.com/file.txt

这个命令会从指定的 URL 下载 file.txt 文件。

常见用法

• 下载文件并指定输出文件名：

1

wget -O newname.txt http://example.com/file.txt

• 递归下载整个网站：

1

wget -r http://example.com

• 限制下载速度：

1

wget --limit-rate=200k http://example.com/file.txt

• 继续未完成的下载：

1

wget -c http://example.com/file.txt

• 下载时不显示进度条：

1

wget -q http://example.com/file.txt

• 下载多个文件：

1

wget -i filelist.txt

这个命令会从 filelist.txt 文件中读取 URL 并下载。

xargs

xargs 命令用于将标准输入的数据转换为命令行参数，常用于处理大量数据。

用法示例

1

echo "file1.txt file2.txt file3.txt" | xargs rm

这个命令会删除 file1.txt、file2.txt 和 file3.txt 文件。

常见用法

• 从文件中读取参数：

1

xargs -a filelist.txt rm

这个命令会从 filelist.txt 文件中读取文件名并删除它们。

• 限制每次执行的命令参数数量：

1

find . -name "*.txt" | xargs -n 2 rm

这个命令会每次删除两个 .txt 文件。

• 使用自定义分隔符：

1

echo "file1.txt,file2.txt,file3.txt" | xargs -d ',' rm

这个命令会使用逗号作为分隔符来删除文件。

• 与其他命令结合使用：

1

find . -name "*.log" | xargs grep "error"

这个命令会在所有 .log 文件中搜索包含 “error” 的行。

开发用：
big.js: A small, fast, easy-to-use library for arbitrary-precision decimal arithmetic
brace: browserify compatible version of the ace editor.
classnames: A simple utility for conditionally joining classNames together
pako: zlib port to javascript - fast, modularized, with browser support
crypto-js: JavaScript library of crypto standards.
day.js: 2KB immutable date time library alternative to Moment.js with the same modern API
dom-to-image: Generates an image from a DOM node using HTML5 canvas and SVG
echarts: Apache ECharts is a powerful, interactive charting and data visualization library for browser
echarts-gl: Extension pack of ECharts providing 3D plots and globe visualization
encryptlong: js encrypt
file-saver: An HTML5 saveAs() FileSaver implementation
handsontable: Handsontable is a JavaScript Spreadsheet Component available for React, Angular and Vue.
immutability-helper: https://github.com/kolodny/immutability-helper#readme
localForage: Offline storage, improved.
lodash: Lodash modular utilities.

编译用：

cross-env: Run scripts that set and use environment variables across platforms
eslint: An AST-based pattern checker for JavaScript.
husky: Modern native Git hooks made easy
prettier: Prettier is an opinionated code formatter
stylelint: A mighty CSS linter that helps you avoid errors and enforce conventions.
cssnano: A modular minifier, built on top of the PostCSS ecosystem.
autoprefixer: Parse CSS and add vendor prefixes to CSS rules using values from the Can I Use website
assert: The assert module from Node.js, for the browser.
buffer: Node.js Buffer API, for the browser
chalk: Terminal string styling done right
crypto-browserify: implementation of crypto for the browser
browserify-zlib: Full zlib module for the browser
fs-extra: fs-extra contains methods that aren’t included in the vanilla Node.js fs package. Such as recursive mkdir, copy, and remove.
get-port: Get an available port
glob: the most correct and second fastest glob implementation in JavaScript
ip: IP address tools for node.js
minimist: parse argument options
path-browserify: the path module from node core for browsers
stream-browserify: the stream module from node core for browsers
url: The core url packaged standalone for use with Browserify.
util: Node.js’s util module for all engines
vm: vm module for the browser
inquirer: A collection of common interactive command line user interfaces.
unzipper: Unzip cross-platform streaming API
rimraf: The UNIX command rm -rf for node.

Homebrew 是 macOS 上最流行的软件包管理工具，允许用户轻松安装和管理软件包。
Homebrew

优点

• 简单易用，命令直观。
• 拥有丰富的软件库。
• 社区活跃，更新频繁。

缺点

• 主要针对 macOS，Windows 支持有限。
• 某些软件包可能不够稳定。

Chocolatey

Chocolatey 是 Windows 平台上的软件包管理工具，基于 NuGet。
Chocolatey

优点

• 支持大量 Windows 软件。
• 可以通过命令行轻松安装和更新软件。
• 与 Windows PowerShell 集成良好。

缺点

• 依赖于 .NET Framework。
• 有些软件包可能需要额外配置。

Scoop

Scoop 是一个 Windows 软件包管理工具，提供了命令行式的安装过程。
Scoop

优点

• 安装过程简单，不需要管理员权限。
• 支持从 GitHub 等源安装软件。
• 轻量级，易于使用。

缺点

• 软件库相对较小。
• 主要针对开发者，普通用户可能不太友好。

APT

APT（Advanced Package Tool）是 Debian 和 Ubuntu 系统的包管理工具。常用命令为 apt-get。
APT

优点

• 提供强大的依赖管理。
• 软件库丰富，更新频繁。
• 支持图形界面和命令行操作。

缺点

• 主要针对 Debian 系列的 Linux 发行版。
• 对于新手用户，命令行操作可能有一定学习曲线。

YUM

YUM（Yellowdog Updater, Modified）是 Red Hat 和 CentOS 系统的包管理工具。

优点

• 支持自动解决依赖关系。
• 提供丰富的软件库。
• 可以通过命令行轻松管理软件包。

缺点

• 主要针对 Red Hat 系列的 Linux 发行版。
• 在某些情况下，更新速度可能较慢。

NPM

NPM（Node Package Manager）是 Node.js 的包管理工具。

优点

• 拥有庞大的 JavaScript 库。
• 支持快速安装和更新 Node.js 包。
• 与 Node.js 生态系统紧密集成。

缺点

• 依赖管理有时可能会出现问题。
• 对于大型项目，可能会导致依赖树过于复杂。

cURL

cURL 是一个命令行数据传输工具，它支持 DICT、FILE、FTP、FTPS、Gopher、HTTP、HTTPS、IMAP、IMAPS、LDAP、LDAPS、POP3、POP3S、RTMP、RTSP、SCP、SFTP、SMB、SMBS、SMTP、SMTPS、Telnet 与 TFTP 等协议。
cURL

优点

• 支持多种协议，灵活性高。
• 可以处理复杂的请求，如表单提交和文件上传。
• 支持代理和认证。

缺点

• 对新手用户可能不太友好，学习曲线较陡。
• 在某些情况下，错误信息不够明确。

wget

wget 是 linux 上的命令行下载工具。这是一个 GPL 许可证下的自由软件。wget 支持 HTTP 和 FTP 协议，支持代理服务器和断点续传功能，能够自动递归远程主机的目录，找到合乎条件的文件并将其下载到本地硬盘上；如果必要，wget 将恰当地转换页面中的超链接以在本地生成可浏览的镜像。

wget

优点

• 简单易用，适合批量下载。
• 支持断点续传，下载中断后可以继续。
• 可以递归下载整个网站。

缺点

• 对于复杂的请求支持有限。
• 处理 HTTPS 时可能需要额外配置。

aira2

aria2是一个轻量级的多协议、多源、跨平台下载实用程序，在命令行中运行。它支持 HTTP/HTTPS、FTP、SFTP、BitTorrent 和 Metalink 。

比较

• 平台支持：Homebrew 主要用于 macOS，Chocolatey 和 Scoop 主要用于 Windows，APT 和 YUM 主要用于 Linux，NPM 主要用于 Node.js。
• 易用性：Homebrew 和 Scoop 的安装过程相对简单，而 Chocolatey 和 APT 需要一些额外的配置。
• 软件库：Homebrew 和 NPM 的软件库最为丰富，Chocolatey、APT 和 YUM 的软件库也相对较大，而 Scoop 的软件库较小。
• 社区支持：Homebrew 和 NPM 拥有最活跃的社区，更新频繁。

glob 通配符早于正则表达式出现，没有正则表达式强大，但提供了简单方便的功用于匹配符合指定模式的文件集合。

glog 通配符现在常用于执行 命令行 例如 ls *.js 或者在一些 ignore 文件，例如 .gitignore 中，或者用到路径匹配功能的工具，例如代理工具 whistle 支持 glob 路径匹配。

glob 语法

注意事项

1. 通配符是先解释，再执行
   Bash 接收到命令以后，发现里面有通配符，会进行通配符扩展，然后再执行命令。

   1 2	$ ls a*.txt ab.txt

   上面命令的执行过程是，Bash 先将 a*.txt 扩展成 ab.txt ，然后再执行 ls ab.txt。
2. 通配符不匹配，会原样输出
   Bash 扩展通配符的时候，发现不存在匹配的文件，会将通配符原样输出。

   1 2 3

   # 不存在 r 开头的文件名 $ echo r* r*

   上面代码中，由于不存在 r 开头的文件名，r* 会原样输出。
3. 只适用于单层路径
   上面所有通配符只匹配单层路径，不能跨目录匹配，即无法匹配子目录里面的文件。或者说，? 或 * 这样的通配符，不能匹配路径分隔符 （/）。
   如果要匹配子目录里面的文件，可以写成下面这样：

   1	$ ls */*.txt

4. 可用于文件名
   Bash 允许文件名使用通配符。这时，引用文件名的时候，需要把文件名放在单引号里面。

   1 2 3

   $ touch 'fo*' $ ls fo*

gitignore

git 中的 .gitignore 文件可以使用 glob 模式匹配，另外还有一些规则：

• 所有空行或者以 # 开头的行都会被 Git 忽略
• 匹配模式可以以 / 开头防止递归
• 匹配模式可以以 / 结尾指定目录
• 要忽略指定模式以外的文件或目录，可以在模式前加上惊叹号 ! 取反

vite

Vite 支持使用特殊的 import.meta.glob 函数从文件系统导入多个模块：

1

const modules = import.meta.glob('./dir/*.js');

以上将会被转译为下面的样子：

1
2
3
4
5

// vite 生成的代码
const modules = {
  './dir/foo.js': () => import('./dir/foo.js'),
  './dir/bar.js': () => import('./dir/bar.js')
};

你可以遍历 modules 对象的 key 值来访问相应的模块：

1
2
3
4
5

for (const path in modules) {
  modules[path]().then(mod => {
    console.log(path, mod);
  });
}

匹配到的文件默认是懒加载的，通过动态导入实现，并会在构建时分离为独立的 chunk。如果你倾向于直接引入所有的模块（例如依赖于这些模块中的副作用首先被应用），你可以传入 { eager: true } 作为第二个参数：

1

const modules = import.meta.glob('./dir/*.js', { eager: true });

以上会被转译为下面的样子：

1
2
3
4
5
6
7

// vite 生成的代码
import * as __glob__0_0 from './dir/foo.js';
import * as __glob__0_1 from './dir/bar.js';
const modules = {
  './dir/foo.js': __glob__0_0,
  './dir/bar.js': __glob__0_1
};

相关 node 库

https://github.com/mrmlnc/fast-glob
https://github.com/isaacs/node-glob
https://github.com/sindresorhus/globby

Pinia 应用示例

通过 defineStore 先创建一个 Store:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

import { defineStore } from 'pinia';

export const useCounterStore = defineStore('counter', {
  state: () => {
    return { count: 0 };
  },
  // 也可以这样定义
  // state: () => ({ count: 0 })
  actions: {
    increment() {
      this.count++;
    }
  }
});

在组件中引入该 Store 并使用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<script setup>
// setup() 函数
import { useCounterStore } from '@/stores/counter';
const counter = useCounterStore();
counter.count++;
// 自动补全
counter.$patch({ count: counter.count + 1 });
// 或使用 action 代替
counter.increment();
</script>
<template>
  <!-- 直接从 store 中访问 state -->
  <div>Current Count: {{ counter.count }}</div>
</template>

Pinia 也提供了一组类似 Vuex 的映射 state 的辅助函数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  getters: {
    double: state => state.count * 2
  },
  actions: {
    increment() {
      this.count++;
    }
  }
});

const useUserStore = defineStore('user', {
  // ...
});

export default defineComponent({
  computed: {
    // 其他计算属性
    // ...
    // 允许访问 this.counterStore 和 this.userStore
    ...mapStores(useCounterStore, useUserStore),
    // 允许读取 this.count 和 this.double
    ...mapState(useCounterStore, ['count', 'double'])
  },
  methods: {
    // 允许读取 this.increment()
    ...mapActions(useCounterStore, ['increment'])
  }
});

Pinia 应用方式

使用包管理器安装 Pinia:

• Yarn: yarn add pinia
• NPM: npm install pinia

Pinia 使用到了组合式 API，如果你是用的 Vue<2.7版本，还需要安装组合式API包： @vue/composition-api 。

在 Vue3 中，创建一个 pinia 实例 并将其传递给应用：

1
2
3
4
5
6
7
8
9

import { createApp } from 'vue';
import { createPinia } from 'pinia';
import App from './App.vue';

const pinia = createPinia();
const app = createApp(App);

app.use(pinia);
app.mount('#app');

在 Vue2 中，还需要安装一个插件：

1
2
3
4
5
6
7
8
9
10
11
12
13

import { createPinia, PiniaVuePlugin } from 'pinia';

Vue.use(PiniaVuePlugin);
const pinia = createPinia();

new Vue({
  el: '#app',
  // 其他配置...
  // ...
  // 请注意，同一个`pinia'实例
  // 可以在同一个页面的多个 Vue 应用中使用。
  pinia
});

Pinia 概念

Store

Store 是一个保存状态和业务逻辑的实体，它并不与你的组件树绑定，承载着全局状态。一个 Store 应该包含可以在整个应用中访问的数据，你应该避免在 Store 中引入那些原本可以在组件中保存的本地数据。

Store 是用 defineStore() 定义的，它的第一个参数要求是一个唯一的名字，用作id，返回一个函数，为了符合组合式函数风格，通常命名为 use<id>Store。defineStore() 的第二个参数可接受两类值：Setup 函数或 Option 对象

当第二个参数使用 Option 对象时，可以传入一个带有 state 、action、getters 属性的 Option 对象。

1
2
3
4
5
6
7
8
9
10
11

export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  getters: {
    double: state => state.count * 2
  },
  actions: {
    increment() {
      this.count++;
    }
  }
});

第二个参数使用 Setup 函数时，该函数定义了一些响应式属性和方法，并且返回一个带有我们想暴露出去的属性和方法的对象：

1
2
3
4
5
6
7
8

export const useCounterStore = defineStore('counter', () => {
  const count = ref(0);
  function increment() {
    count.value++;
  }

  return { count, increment };
});

在 Setup Store 中：

• ref() 就是 state 属性
• computed() 就是 getters
• function() 就是 actions

Store 在使用 <script setup> 调用 useStore() (或者调用 setup() 函数)时，会被创建。

1
2
3
4
5

<script setup>
import { useCounterStore } from '@/stores/counter';
// 可以在组件中的任意位置访问 `store` 变量
const store = useCounterStore();
</script>

为了从 store 中提取属性时保持其响应性，你需要使用 storeToRefs()，它将为每一个响应式属性创建引用。

1
2
3
4
5
6
7
8
9
10

<script setup>
import { storeToRefs } from 'pinia';
const store = useCounterStore();
// `name` 和 `doubleCount` 是响应式的 ref
// 同时通过插件添加的属性也会被提取为 ref
// 并且会跳过所有的 action 或非响应式 (不是 ref 或 reactive) 的属性
const { name, doubleCount } = storeToRefs(store);
// 作为 action 的 increment 可以直接解构
const { increment } = store;
</script>

State

state 被定义为一个返回初始状态的函数，代表了应用中的状态。

默认情况下，可以通过 store 实例访问 state，并进行读写。

1
2

const store = useStore();
store.count++;

使用选项式 API 时，可以通过调用 $reset 方法将 state 重置。

1
2

const store = useStore();
store.$reset();

可以通过调用 $patch 方法同时修改多个属性：

1
2
3
4
5

store.$patch({
  count: store.count + 1,
  age: 120,
  name: 'DIO'
});

$patch 方法也接受一个函数来对集合进行修改：

1
2
3
4

store.$patch(state => {
  state.items.push({ name: 'shoes', quantity: 1 });
  state.hasChanged = true;
});

你不能完全替换掉 store 的 state，因为那样会破坏其响应性。但是，你可以通过 $patch 方法替换它：

1
2
3
4

// 这实际上并没有替换`$state`
store.$state = { count: 24 };
// 在它内部调用 `$patch()`：
store.$patch({ count: 24 });

你可以通过 store 的 $subscribe 方法侦听 state 及其变化,相当于组件中的 watch(), 比起普通的 watch()，使用 $subscribe() 的好处是 subscriptions 在 patch 后只触发一次 (例如，当使用上面的函数版本时)。

Getter

Getter 完全等同于 store 的 state 的计算值（computed value）。推荐使用箭头函数，并且它将接收 state 作为第一个参数。在使用常规函数定义 getter 时，我们也可以通过 this 访问到整个 store 实例，从而访问其他 getter。

你可以访问其他 store 的 getter:

1
2
3
4
5
6
7
8
9
10
11
12
13

import { useOtherStore } from './other-store';

export const useStore = defineStore('main', {
  state: () => ({
    // ...
  }),
  getters: {
    otherGetter(state) {
      const otherStore = useOtherStore();
      return state.localData + otherStore.data;
    }
  }
});

Action

Action 相当于组件中的 method，它们定义了业务逻辑。action 也可通过 this 访问整个 store 实例。action 也可以是异步的，可以像函数或方法一样被调用，也可以在另一个 store 的 action 中被调用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

import { useAuthStore } from './auth-store';

export const useSettingsStore = defineStore('settings', {
  state: () => ({
    preferences: null
    // ...
  }),
  actions: {
    async fetchUserPreferences() {
      const auth = useAuthStore();
      if (auth.isAuthenticated) {
        this.preferences = await fetchPreferences();
      } else {
        throw new Error('User must be authenticated');
      }
    }
  }
});

你可以通过 store.$onAction() 来监听 action 和他们的结果。传递给它的回调函数会在 action 本身之前执行。after 允许在 promise 解决之后执行回调函数。onError 允许在 action 抛出错误或 reject 时执行回调函数。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

const unsubscribe = someStore.$onAction(
  ({
    name, // action 名称
    store, // store 实例，类似 `someStore`
    args, // 传递给 action 的参数数组
    after, // 在 action 返回或解决后的钩子
    onError // action 抛出或拒绝的钩子
  }) => {
    // 为这个特定的 action 调用提供一个共享变量
    const startTime = Date.now();
    // 这将在执行 "store "的 action 之前触发。
    console.log(`Start "${name}" with params [${args.join(', ')}].`);

    // 这将在 action 成功并完全运行后触发。
    // 它等待着任何返回的 promise
    after(result => {
      console.log(`Finished "${name}" after ${Date.now() - startTime}ms.\nResult: ${result}.`);
    });

    // 如果 action 抛出或返回一个拒绝的 promise，这将触发
    onError(error => {
      console.warn(`Failed "${name}" after ${Date.now() - startTime}ms.\nError: ${error}.`);
    });
  }
);

// 手动删除监听器
unsubscribe();

Pinia 插件

Pinia 支持通过 pinia.use() 添加插件，Pinia 插件是一个函数，可以选择性地返回要添加到 store 的属性。它接收一个可选参数，即 context：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import { createPinia } from 'pinia';

// 创建的每个 store 中都会添加一个名为 `secret` 的属性。
// 在安装此插件后，插件可以保存在不同的文件中
function SecretPiniaPlugin(context) {
  // context.pinia // 用 `createPinia()` 创建的 pinia。
  // context.app // 用 `createApp()` 创建的当前应用(仅 Vue 3)。
  // context.store // 该插件想扩展的 store
  // context.options // 定义传给 `defineStore()` 的 store 的可选对象。
  return { secret: 'the cake is a lie' };
}

const pinia = createPinia();
// 将该插件交给 Pinia
pinia.use(SecretPiniaPlugin);

// 在另一个文件中
const store = useStore();
store.secret; // 'the cake is a lie'

以下为插件可扩展的内容：

• 为 store 添加新的属性
• 定义 store 时增加新的选项
• 为 store 增加新的方法
• 包装现有的方法
• 改变甚至取消 action
• 实现副作用，如本地存储
• 仅应用插件于特定 store

当添加外部属性、第三方库的类实例或非响应式的简单值时，你应该先用 markRaw() 来包装一下它，再将它传给 pinia。下面是一个在每个 store 中添加路由器的例子：

1
2
3
4
5
6
7

import { markRaw } from 'vue';
// 根据你的路由器的位置来调整
import { router } from './router';

pinia.use(({ store }) => {
  store.router = markRaw(router);
});

Pinia 与 Vuex 区别

Pinia 是 Vue3 推荐的状态管理库，而 Vuex 将不再更迭，从事件顺序上看，Pinia 可以看做是 Vuex5 。

1. Pinia 提供了更简单的 API，也提供了符合组合式 API 风格的 API，搭配 Typescript 一起使用时有可靠的类型推断支持。
2. Pinia API 已经稳定，新功能需要经过 RFC 流程。Vuex 不再更新。
3. Vuex3.x 只适配 Vue2，Vuex 4.x 适配 Vue3, Pinia 适配 Vue3 和 Vue2。
4. Pinia 没有 mutation，Vuex 中使用 mutation 记录数据的更新。
   Pinia 在 action 执行完成后会自动发布给订阅者，所以不需要 mutation。
5. Pinia 无需要创建自定义的复杂包装器来支持 TypeScript。
6. Pinia 无过多的魔法字符串注入，只需要导入函数并调用它们。
7. Pinia 无需动态添加 Store，默认即是动态的。
8. Pinia 不再有嵌套结构的模块，提供扁平的 Store 结构。
9. Pinia 不再有可命名的模块。

MobX 应用示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

import React from 'react';
import ReactDOM from 'react-dom';
import { makeAutoObservable } from 'mobx';
import { observer } from 'mobx-react';

// 对应用状态进行建模。
class Timer {
  secondsPassed = 0;

  constructor() {
    makeAutoObservable(this);
  }

  increase() {
    this.secondsPassed += 1;
  }

  reset() {
    this.secondsPassed = 0;
  }
}

// 生成应用状态实例
const myTimer = new Timer();

// 构建一个使用 observable 状态的“用户界面”。
const TimerView = observer(({ timer }) => (
  <button onClick={() => timer.reset()}>已过秒数：{timer.secondsPassed}</button>
));

ReactDOM.render(<TimerView timer={myTimer} />, document.body);

// 每秒更新一次‘已过秒数：X’中的文本。
setInterval(() => {
  myTimer.increase();
}, 1000);

围绕 React 组件 TimerView 的 observer 包装会自动侦测到依赖于 observable timer.secondsPassed 的渲染——即使这种依赖关系没有被明确定义出来。 响应性系统会负责在未来恰好那个字段被更新的时候将组件重新渲染。
每个事件（onClick 或 setInterval）都会调用一个用来更新 observable 状态 myTimer.secondsPassed 的 action（myTimer.increase 或 myTimer.reset）。Observable 状态的变更会被精确地传送到 TimerView 中所有依赖于它们的计算和副作用里。

状态流转概念图如下所示：

MobX 应用方式

MobX 有两种 React 绑定方式，其中 mobx-react-lite 仅支持函数组件，mobx-react 还支持基于类的组件。可以使用 Yarn、NPM、CDN 集成 MobX 到项目中：

• Yarn: yarn add mobx
• NPM: npm install --save mobx
• CDN: https://cdnjs.com/libraries/mobx 或者 https://unpkg.com/mobx/dist/mobx.umd.production.min.js

因为使用到了类属性特性，在与 Typescript 或 Babel 一起使用时且计划使用类时，需要转换类字段。

• Babel: 版本>7.12 使用 @babel/plugin-proposal-class-properties 插件，配置 ["@babel/plugin-proposal-class-properties", { "loose": false }]
• Typescript: 在 tsconfig.json 中启用编译器选项 "useDefineForClassFields": true

MobX 使用到了 Proxy 特性，如果在不支持 Proxy 特性的运行时上使用 MobX ，需要明确启用降级方案：

1
2

import { configure } from 'mobx';
configure({ useProxies: 'never' }); // Or "ifavailable".

在 MobX6 中，为了与标准 Javascript 兼容，放弃了装饰器语法，如果需要使用 @observable 等装饰器，需要明确启用同时使用 Typescript 或 Babel 进行转译：

• Typescript：在 tsconfig.json 中启用编译器选项 "experimentalDecorators": true 和 "useDefineForClassFields": true。
• Babel: 使用 @babel/plugin-proposal-class-properties 和 @babel/plugin-proposal-decorators 插件，配置：

1
2
3
4
5
6
7

{
  "plugins": [
    ["@babel/plugin-proposal-decorators", { "legacy": true }],
    ["@babel/plugin-proposal-class-properties", { "loose": false }]
    // 与MobX 4/5不同的是, "loose" 必须为 false!    ^
  ]
}

MobX 概念

MobX区分了应用程序中的以下三个概念：

• State(状态)
• Actions(动作)
• Derivations(派生)

State(状态): 是驱动你的应用程序的数据。通常来说，状态有领域 特定状态 和 视图状态。State 可以使用任何数据结构，但是需要被标记为 observable 从而使 MobX 可跟踪它。
Action(动作) : 是任意可以改变 State(状态) 的代码，比如用户事件处理、后端推送数据处理、调度器事件处理等等。
Derivation(派生): 任何 来源是 State(状态) 并且不需要进一步交互的东西都是 Derivation(派生)。
Mobx 区分了两种 Derivation :

• Computed values：总是可以通过纯函数从当前的可观测 State 中派生
• Reactions：当 State 改变时需要自动运行的副作用 (命令式编程和响应式编程之间的桥梁)

MobX 数据流向

Mobx 使用单向数据流，利用 action 改变 state ，进而更新所有受影响的 view:

1. 所有的 derivations 将在 state 改变时自动且原子化地更新。因此不能观察中间值。
2. 所有的 derivations 默认将会同步更新，这意味着 action 可以在 state 改变之后安全的直接获得 computed value。
3. computed value 的更新是惰性的，任何 computed value 在需要他们的副作用发生之前都是不激活的。
4. 所有的 computed value 都应是纯函数，他们不应该修改 state。

MobX核心

创建可观察(observable) state

makeObservable

用法： makeObservable(target, annotations?, options?)

makeObservable 为每个属性指定一个注解:

• observable 定义一个存储 state 的可追踪字段。
• action 将一个方法标记为可以修改 state 的 action。
• computed 标记一个可以由 state 派生出新的值并且缓存其输出的 getter。
• flow 创建一个 flow 管理异步进程。
• override 用于子类覆盖继承的 action，flow，computed，action.bound
• autoAction 不应被显式调用，但 makeAutoObservable 内部会对其进行调用，以便根据调用上下文将方法标识为 action 或者派生值。

一般情况下，makeObservable 是在类的构造函数中调用的，并且它的第一个参数是 this 。

所有带注解 的字段都是 不可配置的。
所有的不可观察（无状态）的字段（action, flow）都是 不可写的。

makeAutoObservable

用法：makeAutoObservable(target, overrides?, options?)

makeAutoObservable 就像是加强版的 makeObservable，在默认情况下它将推断所有的属性。makeAutoObservable 不能被用于带有 super 的类或 子类。

推断规则：

• 所有 _自有_ 属性都成为 observable。
• 所有 getters 都成为 computed。
• 所有 setters 都成为 action。
• 所有 prototype 中的 functions 都成为 autoAction。
• 所有 prototype 中的 generator functions 都成为 flow。（需要注意，generators 函数在某些编译器配置中无法被检测到，如果 flow 没有正常运行，请务必明确地指定 flow 注解。）
• 在 overrides 参数中标记为 false 的成员将不会被添加注解。例如，将其用于像标识符这样的只读字段。

observable

用法：observable(source, overrides?, options?)

observable 注解可以作为一个函数进行调用，从而一次性将整个对象变成可观察的，之后被添加到这个对象中的属性也将被侦测并使其转化为可观察对象。

使用 actions 更新 state

action

用法：

• action （注解）
• action(fn)
• action(name, fn)

action 注解表示了一段修改 state 的代码。
Actions 可以帮助你更好的组织你的代码并提供以下性能优势：

1. 它们在 transactions 内部运行。任何可观察对象在最外层的 action 完成之前都不会被更新，这一点保证了在 action 完成之前，action 执行期间生成的中间值或不完整的值对应用程序的其余部分都是不可见的。
2. 默认情况下，不允许在 actions 之外改变 state。这有助于在代码中清楚地对状态更新发生的位置进行定位。

action 注解应该仅用于会修改 state 的函数。带有 action 注解的成员是不可枚举的。

action.bound

用法： action.bound （注解）

action.bound 注解可用于将方法自动绑定到正确的实例，这样 this 会始终被正确绑定在函数内部。

runInAction

用法：runInAction(fn)

使用这个工具函数来创建一个会被立即调用的临时 action。

flow

用法：

• flow （注解）
• flow(function* (args) { })

flow 包装器是一个可选的 async / await 替代方案，它让 MobX action 使用起来更加容易。

flow 将一个 generator 函数 作为唯一输入。 在 generator 内部，你可以使用 yield 串联 Promise（使用 yield somePromise 代替 await somePromise）。 flow 机制将会确保 generator 在 Promise resolve 之后继续运行或者抛出错误。

带有 flow 注解的成员是不可枚举的。 flow 的返回值是一个 Promise，在 generator 函数运行完成时它将会被 resolve。 返回的 Promise 中还有一个 cancel() 方法，该方法可以打断正在运行的 generator 并取消它。 所有 try / finally 语句仍然会被运行。

flow.bound

用法： flow.bound （注解）

flow.bound 注解可用于将方法自动绑定到正确的实例，这样 this 会始终被正确绑定在函数内部。

通过 computeds 派生信息

computed

用法：

• computed （注解）
• computed(options) （注解）
• computed(fn, options?)

computed 可以用来从其他可观察对象中派生信息。

使用 computed value 时，需遵循以下规则：

1. 它们不应该有副作用或者更新其他可观察对象
2. 避免创建和返回新的可观察对象
3. 它们不应该依赖非可观察对象的值

使用 reactions 处理副作用

autorun

autorun 函数接受一个函数作为参数，每当该函数所观察的值发生变化时，它都应该运行。
autorun 通过在响应式上下文运行 effect 来工作。在给定的函数执行期间，MobX 会持续跟踪被 effect 直接或间接读取过的所有可观察对象和计算值。 一旦函数执行完毕，MobX 将收集并订阅所有被读取过的可观察对象，并等待其中任意一个再次发生改变。 一旦有改变发生，autorun 将会再次触发，重复整个过程。

reaction

reaction 类似于 autorun，但可以让你更加精细地控制要跟踪的可观察对象。 它接受两个函数作为参数：第一个，data 函数，其是被跟踪的函数并且其返回值将会作为第二个函数，effect 函数，的输入。 重要的是要注意，副作用只会对 data 函数中被访问过的数据做出反应，这些数据可能少于 effect 函数中实际使用的数据。
一般的模式是在 data 函数中返回你在副作用中需要的所有数据， 并以这种方式更精确地控制副作用触发的时机。 与 autorun 不同，副作用在初始化时不会自动运行，而只会在 data 表达式首次返回新值之后运行。

when

when 会观察并运行给定的 predicate 函数，直到其返回 true。 一旦 predicate 返回了 true，给定的 effect 函数就会执行并且自动执行器函数将会被清理掉。
如果你没有传入 effect 函数，when 函数返回一个 Promise 类型的 disposer，并允许你手动取消。

使用 reactive context 需要遵守一些规则：

1. 默认情况下，如果可观察对象发生了改变，受其影响的 reactions 会立即（同步）运行。然而，它们直到当前最外层的 (trans)action 执行结束后才会运行。
2. autorun 只会跟踪给定函数在同步执行过程中所读取的可观察对象，不会跟踪异步发生的变化。
3. autorun 不会跟踪被其调用的 action 所读取的可观察对象，因为 action 始终不会被追踪。
4. reactions 总是会返回一个 disposer 函数，一旦不再需要这些方法中的副作用时，需要调用它们所返回的 disposer 函数。 否则可能导致内存泄漏。

使用 mobx-react 等库时，绑定中的 observer 等方式会间接创建 reaction，无需手动创建。在手动创建 reaction 之前，需要检查是否符合以下原则：

1. 只有在引起副作用的一方与副作用之间没有直接关系的情况下才使用 reaction
2. reactions 不应该更新其他可观察对象
3. reactions 应该是独立的

MobX 和 Redux 的区别

参见 Redux 和 MobX 的区别

当目录中出现了 tsconfig.json 文件，则说明该目录是 TypeScript 项目的根目录。tsconfig.json 文件指定了编译项目所需的根目录下的文件以及编译选项。

JavaScript 项目可以使用 jsconfig.json 文件，它的作用与 tsconfig.json 基本相同，只是默认启用了一些 JavaScript 相关的编译选项。

一个项目将以下列之一的方式使用 tsconfig.json 或者 jsconfig.json 进行编译：

• 在调用 tsc 命令并且没有其它输入文件参数时，编译器将由当前目录开始向父级目录寻找包含 tsconfig 文件的目录。

• 调用 tsc 命令并且没有其他输入文件参数，可以使用 --project （或者只是 -p）的命令行选项来指定包含了 tsconfig.json 的目录，或者包含有效配置的 .json 文件路径。

当在命令行上指定输入文件时，tsconfig.json 文件将被忽略。

一个 tsconfig.json 的示例如下所示：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "compilerOptions": {
    "module": "system",
    "noImplicitAny": true,
    "removeComments": true,
    "preserveConstEnums": true,
    "outFile": "../../built/local/tsc.js",
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

基本的 tsconfig

根据你要在其中运行代码的不同的 JavaScript 运行时环境，你可以在 github.com/tsconfig/bases 上寻找一个合适的基本配置。 你可以通过扩展（extends）这些已经处理过不同的 JavaScript 运行时环境的 tsconfig.json 文件来简化你项目中的 tsconfig.json 。

可选的基本 tsconfig 如下所示：

tsconfig 配置参考

详细参考见 https://www.typescriptlang.org/tsconfig

compilerOptions

compilerOptions 构成了 TypeScript 配置的大部分内容，它涵盖了语言应该如何工作。

大致包括以下部分：

1. 类型检查 Type Checking
2. 模块 Modules
3. 发布 Emit
4. JavaScript 支持 JavaScript Support
5. 编辑器支持 Editor Support
6. 交互限制 Interop Constraints
7. 向后兼容性 Backwards Compatibility
8. 语言与环境 Language and Environment
9. 编译器诊断 Compiler Diagnostics
10. 项目 Projects
11. 输出格式化 Output Formatting
12. 完整性 Completeness
13. 命令行 Command Line
14. 监视选项 Watch Options

详见 编译选项

files

类型：array<string>
默认值： false
指定要包含在程序中的文件的允许列表。如果找不到任何文件，就会发生错误。
当只有少量文件并且不需要使用 glob 模式来引用多个文件时，可以使用 files。其他情况使用 include。

extends

类型： string
默认值： false
指定包含要从中继承的另一个配置文件的路径。路径可能使用 Node.js 样式的解析。
首先加载基本文件中的配置，然后由继承配置文件中的那些配置覆盖。在配置文件中找到的所有相对路径都将相对于它们源自的配置文件进行解析。配置之间不允许循环继承。references 无法被继承。

include

类型：array
默认值：如果有 file 则默认为 [] 否则默认为 **/*
指定要包含在程序中的文件名或模式的数组。这些文件名是相对于包含 tsconfig.json 文件的目录解析的。

include 和 exclude 支持通配符以生成 glob 模式：

• * 匹配零个或多个字符（不包括目录分隔符）
• ? 匹配任何一个字符（不包括目录分隔符）
• **/ 匹配嵌套到任何级别的任何目录

如果模式中的最后一个路径段不包含文件扩展名或通配符，则将其视为一个目录，并包括该目录中具有支持扩展名的文件（例如，默认情况下为 .ts 、.tsx 和 .d.ts ，如果 allowJs 设置为 true ，则使用 .js 和 .jsx ）。

exclude

类型：array
默认值：['node_modules', 'bower_components', 'jspm_packages', '%outDir%']
指定在解析include时应跳过的文件名或模式的数组。

重要提示：exclude 仅排除由于 include 设置而包含的文件。exclude 指定的文件仍然可以成为代码库的一部分，这是由于代码中的 import 语句、types 包含、///<reference 指令或在 files 列表中指定。

references

项目引用是一种将 TypeScript 程序解构成更小部分的方法。使用项目引用可以极大地缩短构建和编辑器交互时间，强制组件之间的逻辑分离，并以新的和改进的方式组织代码。详见 Project References。

编译选项 compilerOptions

类型检查 Type Checking

allowUnreachableCode

允许无法访问的代码

• undefined（默认）将建议作为警告提供给编辑器

• true 忽略无法访问的代码

• false 引发关于无法访问代码的编译器错误

allowUnusedLabels

允许未使用的标签（label）

• undefined（默认）将建议作为警告提供给编辑器

• true 忽略未使用的标签

• false 引发关于未使用标签的编译器错误

alwaysStrict

确保在 ECMAScript 严格模式下解析文件，并为每个源文件添加 use strict 。

默认值：如果有 strict 则默认为 true 否则为 false 。

exactOptionalPropertyTypes

启用 exactOptionalPropertyTypes 后，TypeScript 对具有 ? 前缀的类型或接口的属性启用更加精确的规则。

noFallthroughCasesInSwitch

在 switch 语句中进入穿透分支时报告错误。确保 switch 语句中的任何非空分支都包括 break、return 或 throw 。这意味着你不会意外地遇到穿透分支的bug。

noImplicitAny

在某些不存在类型注释的情况下，当 TypeScript 无法推断变量的类型时，它将回退到 any 类型。

默认值：如果有 strict 则默认为 true 否则为 false 。

noImplicitOverride

当处理使用继承的类时，子类可能会与在基类中重命名时重载的函数“不同步”（隐式重载）。
使用 noImplicitOverride 可以确保重载的函数必需包含关键字 override ，从而确保子类永远不会失去同步。

noImplicitReturns

启用后，TypeScript 将检查函数中的所有代码路径，以确保它们返回值。

noImplicitThis

在具有隐含 “any” 类型的 “this” 表达式上引发错误。

noPropertyAccessFromIndexSignature

此设置可确保通过点（obj.key）语法和索引（obj["key"]）访问字段以及在类型中声明属性的方式之间的一致性。如果没有此标志，TypeScript 将允许你使用点语法访问未定义的字段。

noUncheckedIndexedAccess

TypeScript 有一种方法可以通过索引签名来描述对象上具有未知键但已知值的对象。
启用 noUncheckedIndexedAccess 将向类型中任何未声明的字段添加 undefined 类型。

noUnusedLocals

对未使用的局部变量报告错误。

noUnusedParameters

对函数中未使用的参数报告错误。

strict

严格标志可以实现广泛的类型检查行为，从而为程序的正确性提供更强的保证。启用此选项相当于启用以下列出的所有严格模式族选项（以 strict 开头的选项）。然后，你可以根据需要关闭单独的严格模式族检查。

strictBindCallApply

设置后，TypeScript 将检查函数 call、bind 和 apply 的内置方法是否使用基础函数的正确参数调用。

strictFunctionTypes

启用时，此标志会使函数参数得到更正确的检查。

strictNullChecks

当 strictNullChecks 为 false 时，语言会有效地忽略 null 和 undefined 。这可能会导致运行时出现意外错误。
当 strictNullChecks 为 true 时， null 和 undefined 有各自不同的类型，如果你试图在需要具体值的地方使用它们，则会出现类型错误。

strictPropertyInitialization

当设置为 true 时，当类属性已声明但未在构造函数中设置时，TypeScript 将引发错误。

useUnknownInCatchVariables

在 TypeScript 4.0 中添加了新的功能，允许将 catch 子句中变量的类型从 any 更改为 unknown 。
这种模式确保错误处理代码变得更加全面，因为你不能提前保证抛出的对象是 error 子类。
启用了 useUnknownCatchVariables 标志后，就不需要额外的语法（:unknown）或 linter 规则来强制执行此行为。

Modules 模块

allowArbitraryExtensions

在 TypeScript 5.0 中，当导入路径的扩展名不是已知的 JavaScript 或 TypeScript 文件扩展名时，编译器将为该路径查找一个形式为 {file-basename}.d.{extension}.ts 的声明文件。
默认情况下，此导入会引发一个错误，让你知道 TypeScript 不理解此文件类型，并且你的运行时可能不支持导入它。但是，如果你已将运行时或打包器配置为可以处理它，则可以使用新的 --allowArbitraryExtensions 编译器选项来抑制该错误。

allowImportingTsExtensions

--allowImportingTsExtensions 允许 TypeScript 文件使用 TypeScript 特定的扩展名（如 .ts、.mts 或 .tsx）相互导入。
只有启用 --noEmit 或 --emitDeclarationOnly 时才允许使用此标志，因为这些导入路径在运行时无法在 JavaScript 输出文件中解析。这里的期望是，你的解析器（例如，你的打包器、运行时或其他工具）将会做这些在 .ts 文件之间的导入工作。

allowUmdGlobalAccess

当设置为 true 时， allowUmdGlobalAccess 允许你从模块文件内部访问作为全局变量的 UMD 导出。模块文件是具有导入和/或导出功能的文件。如果没有此标志，使用 UMD 模块的导出需要导入声明。

baseUrl

设置要从中解析非相对模块名称的基本目录。
使用 "baseUrl"："./" 时，TypeScript 将查找与 tsconfig.json 位于同一文件夹的文件。

customConditions

--customConditions 获取 TypeScript 从 package.json 的导出或导入字段解析时应成功的附加条件列表。这些条件将添加到解析程序默认使用的任何现有条件中。
该字段仅在 --moduleSolution 为 node16 、nodenext 或 bundler 时有效。

module

设置应用程序的模块系统。改变 module 会影响 moduleResolution。

默认值：如果 target 为 ES3 或者 ES5 那么 module 默认为 CommonJS，否则默认为 ES6/ES2015 。

以下为该文件的一些例子输出：

1
2
3

import { valueOfPi } from "./constants";

export const twoPi = valueOfPi * 2;

1
2
3
4
5

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.twoPi = void 0;
const constants_1 = require("./constants");
exports.twoPi = constants_1.valueOfPi * 2;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

(function (factory) {
    if (typeof module === "object" && typeof module.exports === "object") {
        var v = factory(require, exports);
        if (v !== undefined) module.exports = v;
    }
    else if (typeof define === "function" && define.amd) {
        define(["require", "exports", "./constants"], factory);
    }
})(function (require, exports) {
    "use strict";
    Object.defineProperty(exports, "__esModule", { value: true });
    exports.twoPi = void 0;
    const constants_1 = require("./constants");
    exports.twoPi = constants_1.valueOfPi * 2;
});

1
2
3
4
5
6

define(["require", "exports", "./constants"], function (require, exports, constants_1) {
    "use strict";
    Object.defineProperty(exports, "__esModule", { value: true });
    exports.twoPi = void 0;
    exports.twoPi = constants_1.valueOfPi * 2;
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

System.register(["./constants"], function (exports_1, context_1) {
    "use strict";
    var constants_1, twoPi;
    var __moduleName = context_1 && context_1.id;
    return {
        setters: [
            function (constants_1_1) {
                constants_1 = constants_1_1;
            }
        ],
        execute: function () {
            exports_1("twoPi", twoPi = constants_1.valueOfPi * 2);
        }
    };
});

1
2

import { valueOfPi } from "./constants";
export const twoPi = valueOfPi * 2;

1
2

import { valueOfPi } from "./constants";
export const twoPi = valueOfPi * 2;

除了 ES2015/ES6 的基本功能外，ES2020 还增加了对动态导入和 import.meta 的支持，而 ES2022 则进一步增加了对 top await 的支持。

1
2
3
4
5

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.twoPi = void 0;
const constants_1 = require("./constants");
exports.twoPi = constants_1.valueOfPi * 2;

moduleResolution

指定模块解析策略：

• node16 或者 nodenext 表示使用 Node.js 的现代版本。Node.js v12及更高版本同时支持 ECMAScript import 和 CommonJS require
• node10（以前称为 node ）适用于 v10 以内的 Node.js 版本，仅支持 CommonJS require。
• 用于打包器的 bundler。与 node16 和 nodenext 一样，该模式支持 package.json 的 “imports” 和 “exports” ，但与 Node.js 解析模式不同，bundler 在导入中不需要相对路径上的文件扩展名。
• 在 1.6 版本之前，TypeScript 中使用了 classic。

默认值：如果 module 是 AMD,UMD,System 或者 ES6/ES2015 则默认值是 Calssic；如果 module 是 node16 或者 nodenext，则与之相匹配; 否则默认值为 Node 。

moduleSuffixes

类型：array<string>
提供一种在解析模块时覆盖要搜索的文件名后缀的默认列表的方法。

noResolve

默认情况下，TypeScript 将检查 import 和 reference 指令的初始文件集，并将这些解析的文件添加到程序中。
如果设置了 noResolve ，则不会发生此过程。但是，import 语句仍然会被检查，以查看它们是否解析为有效的模块，因此你需要确保通过其他方式满足这一要求。

paths

将 paths 中所列出的一系列条目的 import 重新映射，如果设置了 baseUrl，则相对于 baseUrl 进行查找，否则相对于 tsconfig 文件本身的位置进行查找。通过设置 paths，TypeScript 文件解析器可以支持自定义前缀来查找代码引入路径。

resolveJsonModule

允许导入带有 .json 扩展名的模块，这是 node 项目中的常见做法。这包括基于静态 JSON 形状为 import 生成一个类型。

resolvePackageJsonExports

--resolvePackageJsonExports 强制 TypeScript 在读取 node_modules 中的包时，查阅 package.json 文件的 exports 字段。

默认值：当 moduleResolution 是 node16 , nodenext 或者 bundler 时，默认值为 true, 否则为 false。

resolvePackageJsonImports

--resolvePackageJsonImports 强制 TypeScript 在从祖先目录包含 package.json 的文件执行以 # 开头的查找时，查阅 package.json 文件的 imports 字段。

默认值：当 moduleResolution 是 node16 , nodenext 或者 bundler 时，默认值为 true, 否则为 false。

rootDir

根节点。

默认值：所有非声明输入文件的最长公共路径。如果设置了 composite，则默认为包含 tsconfig.json 文件的目录。

rootDirs

使用 rootDirs ，你可以通知编译器有许多“虚拟”目录充当单个根目录。这允许编译器解析这些“虚拟”目录中的相对模块导入，就好像它们被合并到一个目录中一样。

typeRoots

默认情况下，所有可见的 @types 包都包含在编译中。如果指定了 typeRoots ，则只包括 typeRoots 下的包。所有路径都是相对于 tsconfig.json 的。

types

默认情况下，所有可见的 @types 包都包含在编译中。如果指定了 types，则只有列出的包才会包含在全局作用域中。

Emit 生成

declaration

为项目中的每个 TypeScript 或 JavaScript 文件生成 .d.ts 文件。这些 .d.ts 文件是描述模块的外部API的类型定义文件。有了 .d.ts 文件，像 TypeScript 这样的工具可以为正在键入的代码提供智能提示和准确的类型。

默认值：如果 composite 则默认值为 true ，否则为 false 。

declarationDir

提供了一种配置根目录的方法，该根目录用于生成类型描述文件( .d.ts )。

declarationMap

为映射回原始 .ts 源文件的 .d.ts 文件生成源映射。这将允许 VS Code 等编辑器在使用 go to Definition 等功能时转到原始 .ts 文件。

downlevelIteration

如果存在 Symbol.iterator 的实现，那么 downlevelIteration 允许在 ES5 环境中更准确地使用这些迭代方法的原始语法。

emitBOM

控制 TypeScript 在写入输出文件时是否会生成字节顺序标记（BOM）。一些运行时环境需要 BOM 来正确解释 JavaScript 文件；其他人则要求它不存在。默认值 false 通常是最好的，除非你有理由更改它。

emitDeclarationOnly

仅生成 .d.ts 文件；不生成 .js 文件。

importHelpers

对于某些降级操作，TypeScript 使用一些辅助代码来执行诸如继承类、扩展数组或对象以及异步操作等。默认情况下，这些辅助代码会插入到使用它们的文件中。如果在许多不同的模块中使用相同的辅助代码，这可能会导致代码重复。如果 importHelpers 标志处于启用状态，则这些辅助函数将改为从 tslib 模块导入。你需要确保 tslib 模块能够在运行时导入。这只会影响模块；全局脚本文件将不会尝试导入模块。

importsNotUsedAsValues

此标志控制 import 的工作方式，有三个不同的选项：

• remove：删除仅引用类型的 import 语句。
• preserve：保留其值或类型从未使用过的所有 import 语句。这可能会导致保留 引入/副作用。
• error：这将保留所有 import（与 preserve 选项相同），但当 import 仅用作类型时会出错。如果你希望确保没有意外导入值，但仍然显式导入副作用，那么这可能会很有用。

这个标志之所以有效，是因为你可以使用 import type 显式地创建一个 import 语句，而该语句永远不应该被生成到 JavaScript 中。

inlineSourceMap

设置后，TypeScript 将把源映射内容嵌入 .js 文件中，而不是生成 .js.map 文件来提供源映射。

inlineSources

设置后，TypeScript 将把 .ts 文件的原始内容作为嵌入字符串包含在源映射中（使用源映射的 sourcesContent 属性）。

mapRoot

指定调试器应该定位映射文件的位置，而不是生成的位置。

newLine

指定在生成文件时使用的行尾序列:’ CRLF ‘ (dos)或’ LF ‘ (unix)。

noEmit

不要生成编译器输出文件，如 JavaScript 源代码、源映射或声明。
这为 Babel 或 swc 等其他工具腾出了空间来处理将 TypeScript 文件转换为可以在 JavaScript 环境中运行的文件。

noEmitHelpers

你可以在全局作用域中为你使用的帮助程序提供一种实现，而不是使用 importthelpers 导入帮助程序，并完全关闭生成或帮助函数。

noEmitOnError

如果报告了任何错误，不要生成编译器输出文件，如 JavaScript 源代码、源映射或声明。

默认值：false

outDir

如果指定，.js （以及 .d.ts .js.Map 等）文件将被生成到该目录。

outFile

如果指定，所有全局（非模块）文件将被连接到指定的单个输出文件中。

preserveConstEnums

不要在生成的代码中删除 const enum 声明。const enum 提供了一种在运行时通过生成枚举值而不是引用来减少应用程序总体内存占用的方法。

preserveValueImports

preserveValueImports 会阻止 TypeScript 移除 import，即使它看起来没有被使用。

removeComments

当转换为 JavaScript 时，从 TypeScript 文件中删除所有注释。

默认值：false

sourceMap

允许生成源映射文件。

sourceRoot

指定调试器应该定位 TypeScript 文件的位置，而不是相对源位置。

stripInternal

不要为 JSDoc 注释中有 @internal 注释的代码生成声明文件。

Javascript 支持

allowJs

允许在项目中导入 JavaScript 文件，而不仅仅是 .ts 和 .tsx 文件。

checkJs

与 allowJs 协同工作。当 checkJs 被启用时，会在 JavaScript 文件中报告错误。这相当于在项目中包含的所有 JavaScript 文件的顶部包含 // @ts-check 。

maxNodeModuleJsDepth

在 node_modules 下搜索和加载 JavaScript 文件的最大依赖深度。仅 allowJs 开启时有效。

编辑器支持

disableSizeLimit

为了避免在处理非常大的 JavaScript 项目时可能出现的内存膨胀问题，TypeScript 会分配一个内存上限。打开此标志将取消限制。

plugins

要在编辑器中运行的语言服务插件列表。

交互限制

allowSyntheticDefaultImports

当设置为true时，allowsyntheticdefaulultimports允许你编写这样的导入:

1

import React from "react";

而不是：

1

import * as React from "react";

当模块未显式指定默认导出时。

esModuleInterop

默认情况下（esModuleInterop 为 false 或未设置）d，TypeScript 对待 CommonJS/AMD/UMD 模块的方式与对待 ES6 模块类似。在此过程中，有两个部分被证明是有缺陷的：

• 像 import * as moment from "moment" 这样的命名空间导入与 const moment = require("moment") 的作用相同

• 像 import moment from "moment" 这样的默认导入与 const moment = require("moment").default 的作用相同

这种不匹配导致了以下两个问题:

ES6 模块规范规定，命名空间 import (import * as x) 只能是一个对象，通过让 TypeScript 像对待= require("x") 一样对待它，那么 TypeScript 就允许将导入作为一个函数来对待，并且可以被调用。根据 Javascript 说明书，这是无效的。

虽然符合 ES6 模块规范，但大多数带有 CommonJS/AMD/UMD 模块的库并不像 TypeScript 的实现那样严格遵守规范。

打开 esModuleInterop 会在 TypeScript 编译的代码中修复这两个问题。第一个改变了编译器中的行为，第二个通过两个新的帮助函数修复，这两个帮助函数提供了一个机制，以确保所生成的 JavaScript 可以兼容。

forceConsistentCasingInFileNames

当设置了这个选项后，如果一个程序试图用不同于磁盘上的大小写来引入一个文件，TypeScript 会提示一个错误。

isolatedModules

设置 isolatedModules 标志告诉 TypeScript，如果你写的某些代码不能被单文件编译过程正确解释，它会警告你。

preserveSymlinks

该配置与 Node.js 中相同的标志含义相同;不解析符号链接的实际路径。

verbatimModuleSyntax

任何没有 type 修饰符的导入或导出都将保留。任何使用 type 修饰符的内容都将被完全删除。

向后兼容性

以下为废弃的或向后兼容配置：

charset keyofStringsOnly noImplicitUseStrict noStrictGenericChecks out suppressExcessPropertyErrors suppressImplicitAnyIndexErrors reactNamespace skipDefaultLibCheck

语言与环境

emitDecoratorMetadata

与模块 reflect-metadata 共同使用，启用对装饰器（decorator）生成类型元数据（metadata）的实现性支持。

experimentalDecorators

启用对 decorator 的实验性支持。

jsx

控制文件中 JSX 结构如何生成 JavaScript。只影响 .tsx 文件。

jsxFactory

使用 JSX 运行时编译 JSX 元素时，更改 .js 文件中调用的函数。最常见的更改是使用 h 或 preact.h，而不是默认的 React.createElement（如果使用 preact）。

jsxFragmentFactory

指定在带有 jsxFactory 编译器选项的目标 react JSX 生成时要使用的 JSX fragment 工厂函数，例如 Fragment。

jsxImportSource

当 jsx 属性为为 “react jsx” 或 “react jsonxdev” 时，声明用于导入 jsx 和 jsxs 工厂函数的模块说明符。

默认值： react

lib

用于使 TypeScript 包括与你指定的目标匹配的 JS 新功能的 API 的类型声明。

moduleDetection

此设置控制 TypeScript 如何确定文件是脚本还是模块。

noLib

禁用自动包含任何库文件。如果设置了此选项，则会忽略 lib 配置项。

target

target 配置项决定了哪些 JS 特性降级了，哪些保持不变。

useDefineForClassFields

这个标志被用作迁移到即将到来的 class 字段标准版本的一部分。

默认值：如果 target 是 ES2022 或者更高版本（包括 ESNext） 则为 true，否则为 false

编译诊断

diagnostics

输出诊断信息，用于调试。

explainFiles

打印 TypeScript 认为是你项目一部分的文件名，以及它们成为编译一部分的原因。

extendedDiagnostics

你可以使用这个标志来发现 TypeScript 在编译时把时间花在了哪里。这是一个用于全面了解代码库性能特征的工具。

generateCpuProfile

这个选项让你有机会让 TypeScript 在编译器运行期间输出 v8 CPU 配置文件。CPU 配置文件可以深入了解构建可能缓慢的原因。

默认值： profile.cpuprofile

listEmittedFiles

将编译过程中生成的文件的名称打印到终端。

listFiles

打印编译过程中文件的名称。

traceResolution

让 TypeScript 为每个处理过的文件打印有关它的解析过程的信息。

项目

composite

composite 选项强制了某些约束，使得构建工具（包括 TypeScript 本身，在 -—build 模式下）能够快速确定项目是否已经构建完成。

disableReferencedProjectLoad

如果你的项目很大，你可以使用 disableReferencedProjectLoad 标志来禁用所有项目的自动加载。相反，当你通过编辑器打开文件时，会动态加载项目。

disableSolutionSearching

当使用复合 TypeScript 项目时，该选项提供了一种方式来声明，当使用诸如 查找所有引用 或在编辑器中 跳转到定义 之类的特性时，你不希望包含某个项目。

disableSourceOfProjectReferenceRedirect

当使用复合 TypeScript 项目时，该选项提供了一种回到 Typescript 3.7 之前的行为的方法，在 Typescript 3.7 之前，d.ts 文件被用作模块之间的边界。

incremental

告诉 TypeScript 将上次编译时的项目图信息保存到存储在磁盘上的文件 .tsbuildinfo 中。

默认值：如果 composite 配置项为 true 则为 true，否则为 false。

tsBuildInfoFile

这个设置允许你指定一个文件来存储增量编译信息，作为复合项目的一部分，这样可以更快地构建更大的 TypeScript 代码库。

默认值：.tsbuildinfo

输出格式化

noErrorTruncation

不要截断错误消息。

preserveWatchOutput

是否将过时的控制台输出保持在监视模式，而不是每次发生更改时清除屏幕。

pretty

使用颜色和上下文对错误和消息进行风格化，默认开启。

完整性

skipLibCheck

跳过声明文件的类型检查。

监视选项

assumeChangesOnlyAffectDirectDependencies

当启用这个选项时，TypeScript 将避免重新检查/重建所有真正可能受到影响的文件，只重新检查/重建那些已经改变的文件，以及那些直接导入它们的文件。

一个 EventSource 实例会对 HTTP 服务器开启一个持久化的连接，以 text/event-stream 格式发送事件，此连接会一直保持开启直到通过调用 EventSource.close() 关闭。一旦连接开启，来自服务端传入的消息会以事件的形式分发至客户端中，如果接收消息中有一个 event 字段，触发的事件与 event 字段的值相同。如果不存在 event 字段，则将触发通用的 message 事件。

与 WebSocket 不同的是，服务器发送事件是单向的。数据消息只能从服务端发送到客户端（如用户的浏览器）。这使其成为不需要从客户端往服务器发送消息的情况下的最佳选择。

构造函数

EventSource()

创建一个新的 EventSource，用于从指定的 URL 接收服务器发送事件，可以选择开启凭据模式。

用法： cosnt pc = new EventSource(url, configuration);

url 表示远程资源的位置，configuration 为配置新连接提供选项，目前只有一个可选项 withCredentials，默认为 false，指示 CORS 是否应包含凭据。

实例属性

此接口从其父接口 EventTarget 继承属性。

• EventSource.readyState 只读
  一个代表连接状态的数字。可能值是 CONNECTING（0）、OPEN（1）或 CLOSED（2）。

• EventSource.url 只读
  一个表示事件源的 URL 字符串。

• EventSource.withCredentials 只读
  一个布尔值，表示 EventSource 对象是否使用跨域资源共享（CORS）凭据来实例化（true），或者不使用（false，即默认值）。

实例方法

此接口从其父接口 EventTarget 继承方法。

• EventSource.close()
  关闭连接（如果有），并将 readyState 属性设置为 CLOSED。如果连接已经关闭，则该方法不执行任何操作。

事件

• error
  在事件源连接未能打开时触发。

• message
  在从事件源接收到数据时触发。

• open
  在与事件源的连接打开时触发。

此外，事件源本身可以发送具有 event 字段的消息，这将创建一个以该值为键的特定事件。

示例

在这个基本的例子中，创建了一个 EventSource 来从服务器接收未命名的事件；一个名为 sse.php 的页面负责生成这些事件。

1
2
3
4
5
6
7
8
9
10

const evtSource = new EventSource("sse.php?message=hello");
const eventList = document.querySelector("ul");

evtSource.onmessage = (e) => {
  const newElement = document.createElement("li");

  newElement.textContent = `message: ${e.data}`;
  eventList.appendChild(newElement);
  evtSource.close();
};

每个接收到的事件都会导致我们的 EventSource 对象的 onmessage 事件处理程序运行。它会创建一个新的 <li> 元素，并将消息的数据写入其中，然后将新元素附加到文档中已有的列表元素中。

要监听具名事件，你需要为每种类型的事件添加一个监听器。