# nfap9 个人知识库全文聚合

> 生成时间：2026-06-30T02:26:47.904Z
> 站点：https://nfap9.github.io
> 本文档包含所有博客文章和笔记的完整 Markdown 内容，供 LLM 检索和分析使用。
> 文章总数：16（博客 14 篇 + 笔记 2 条）


---

# 用 Node.js 从零构建一个 Agent 运行时：基于 aura-agent 的架构拆解

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/nodejs-agent-architecture/
> **分类**：工程化
> **标签**：nodejs, agent, ai, mcp, react, architecture
> **发布日期**：2026-06-18
> **描述**：基于真实开源项目 aura-agent，拆解 Agent 的六大核心要素：ReAct 循环、工具系统、记忆系统、MCP 协议、技能注入、流式传输。不讲故事，直接看代码。


> 本文基于开源项目 [aura-agent](https://github.com/nfap9/aura-agent) 的真实代码，逐层拆解一个 Node.js Agent 运行时的实现。所有代码片段均来自项目源码，不做虚构。

---

## 一、Agent 的本质：一个编排循环

Agent 不是魔法，它就是一个**带状态的循环**。

```
接收输入 → 注入上下文 → 调用 LLM → 解析响应 → 执行工具 → 把结果喂回去 → 再次调用 LLM
```

这个循环在 aura-agent 中叫做 `runLoop`，最大迭代 10 次：

```typescript
// packages/core/src/agent/agent.ts
const MAX_ITERATIONS = 10;

private async *runLoop(
  inputMessages: Message[],
  options?: ChatCompletionOptions,
  events?: AgentEvents
): AsyncGenerator<StreamChunk> {
  // 1. 注入记忆上下文
  if (this.memory && inputMessages.length > 0) {
    const memoryContext = await this.memory.getRelevantContext(query);
    // 把记忆塞进第一条用户消息前面
  }

  this.thread.addMessages(inputMessages);
  this.thread.trim(); // 截断超长的上下文

  let continueLoop = true;
  let iteration = 0;

  while (continueLoop && iteration < MAX_ITERATIONS) {
    iteration++;
    const messages = this.thread.getMessages();

    // 2. 匹配技能并注入
    const apiMessages = await this.buildMessagesWithSkills(userQuery, events);

    // 3. 调用 LLM（流式）
    const stream = this.provider.chatStream({
      model: this.model,
      messages: apiMessages,
      tools: this.tools.getToolSchemas(),
    });

    let content = "";
    let hasToolCall = false;

    for await (const chunk of stream) {
      if (chunk.type === "content") {
        content += chunk.delta;
        yield chunk; // 流式吐给外层
      } else if (chunk.type === "tool_call") {
        hasToolCall = true;
        // 收集工具调用参数
      }
    }

    // 4. 把 assistant 的回复加入对话历史
    this.thread.addMessages([assistantMessage]);

    if (!hasToolCall) {
      continueLoop = false; // 没有工具调用，任务结束
    } else {
      // 5. 执行工具，把结果以 tool 角色塞回历史
      for (const toolCall of toolCalls) {
        const result = await this.tools.execute(name, parseArgs);
        this.thread.addMessages([
          { role: "tool", content: result, tool_call_id: toolCall.id }
        ]);
      }
      // 循环继续，LLM 看到工具结果后再次推理
    }
  }
}
```

这就是 ReAct 的核心：**LLM 不直接给答案，而是输出 "我要调用某某工具"，Agent 执行工具后把结果还回去，LLM 基于结果再推理下一步**。一轮不够就再来一轮，直到 LLM 说"不用工具了，这就是答案"。

---

## 二、工具系统：让 LLM 能动手

### 2.1 工具的组成

一个工具 = 定义（告诉 LLM 有什么参数）+ 处理器（实际执行）。

```typescript
// packages/core/src/capabilities/tools/types.ts
export interface ToolDefinition {
  name: string;
  description: string;
  parameters: {
    type: string;
    properties: Record<string, any>;
    required?: string[];
  };
}

export type ToolHandler = (args: Record<string, any>) => Promise<string> | string;
```

注册时把两者绑定在一起：

```typescript
// packages/core/src/capabilities/tools/registry.ts
export class ToolRegistry implements ToolSource {
  private tools = new Map<string, Tool>();

  register(definition: ToolDefinition, handler: ToolHandler): void {
    this.tools.set(definition.name, { definition, handler });
  }

  getToolSchemas(): ChatCompletionTool[] {
    return Array.from(this.tools.values()).map((t) => ({
      type: "function",
      function: {
        name: t.definition.name,
        description: t.definition.description,
        parameters: t.definition.parameters,
      },
    }));
  }

  async execute(name: string, args: Record<string, any>): Promise<string> {
    const tool = this.tools.get(name);
    return await tool.handler(args);
  }
}
```

`getToolSchemas()` 返回的格式就是 OpenAI 的 `tools` 参数，LLM 收到后就知道自己有哪些工具可用。

### 2.2 内置工具示例：bash

```typescript
// packages/core/src/capabilities/tools/native/bash.ts
export const bashDefinition: ToolDefinition = {
  name: "bash",
  description: "执行 shell 命令...",
  parameters: {
    type: "object",
    properties: {
      command: { type: "string", description: "要执行的 shell 命令" },
      timeout: { type: "number", description: "超时时间（毫秒）" },
    },
    required: ["command"],
  },
};

export async function executeBash(args: Record<string, any>): Promise<string> {
  const { command, timeout = 60000 } = args;
  const { stdout, stderr } = await execAsync(command, { timeout, maxBuffer: 1024 * 1024 });
  return stdout || "(命令执行完成，无输出)";
}
```

注册时调用：

```typescript
registry.register(bashDefinition, (args) => executeBash(args));
```

---

## 三、MCP：连接外部工具生态

MCP（Model Context Protocol）是 Anthropic 推出的标准协议，让外部工具服务器和 Agent 之间用统一格式通信。aura-agent 的 MCP 实现支持 stdio 和 HTTP 两种传输方式。

### 3.1 连接 MCP 服务器

```typescript
// packages/core/src/capabilities/tools/mcp.ts
export class MCPClientManager {
  private connections: Map<string, ServerConnection> = new Map();

  async connect(config: MCPConfig): Promise<void> {
    for (const serverConfig of config.servers) {
      await this.connectServer(serverConfig);
    }
  }

  private async connectServer(config: MCPServerConfig): Promise<void> {
    const client = new Client({ name: "agent-mcp-client", version: "1.0.0" }, { capabilities: {} });

    let transport: Transport;
    if (config.transport === "stdio") {
      transport = new StdioClientTransport({
        command: config.command,
        args: config.args,
      });
    } else {
      transport = new StreamableHTTPClientTransport(new URL(config.url!));
    }

    await client.connect(transport);

    // 获取服务器暴露的工具列表
    const toolsResult = await client.listTools();
    const tools: ToolDefinition[] = toolsResult.tools.map((t) => ({
      name: t.name,
      description: t.description ?? "",
      parameters: {
        type: "object",
        properties: t.inputSchema.properties ?? {},
        required: t.inputSchema.required ?? [],
      },
    }));

    this.connections.set(config.name, { config, client, transport, tools });
  }
}
```

### 3.2 命名空间隔离

不同 MCP 服务器可能定义同名工具（比如两个服务器都有 `read_file`），所以 aura-agent 给工具名加上服务器前缀：

```typescript
private makeUniqueToolName(serverName: string, toolName: string): string {
  return `${serverName}_${toolName}`; // e.g. "filesystem_read_file"
}
```

LLM 看到的是 `filesystem_read_file`，调用时由 `MCPClientManager` 解析出原始服务器名和工具名，转发给对应的服务器。

### 3.3 执行与结果转换

MCP 工具返回的结果格式多样（text / resource / image），aura-agent 统一转成字符串：

```typescript
private async executeTool(uniqueName: string, args: Record<string, any>): Promise<string> {
  const result = await conn.client.callTool({ name: originalToolName, arguments: args });

  if ("content" in result && Array.isArray(result.content)) {
    const texts = result.content
      .filter((c: any) => c.type === "text")
      .map((c: any) => c.text)
      .join("\n");
    if (texts) return texts;

    const images = result.content
      .filter((c: any) => c.type === "image")
      .map((c: any) => `[image data: ${c.mimeType}]`)
      .join("\n");
    if (images) return images;
  }

  return JSON.stringify(result);
}
```

配置一个 MCP 服务器只需要一个 JSON 文件：

```json
{
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/data"]
    }
  ]
}
```

---

## 四、记忆系统：让 Agent 有长期记忆

没有记忆的 Agent 每次对话都是白板。aura-agent 的记忆系统基于 **TF-IDF + 余弦相似度** 做检索，纯算法实现，不依赖向量数据库。

### 4.1 记忆的数据结构

```typescript
// packages/core/src/capabilities/memory/types.ts
export interface MemoryEntry {
  id: string;
  content: string;
  category: string;      // 分类，如 "fact", "preference"
  importance: number;    // 1-10，重要性评分
  createdAt: string;
  updatedAt: string;
  accessCount: number;   // 被检索次数
  metadata?: Record<string, any>;
}
```

### 4.2 检索：TF-IDF + 余弦相似度

```typescript
// packages/core/src/capabilities/memory/retriever.ts
export function retrieveMemories(
  query: string,
  entries: MemoryEntry[],
  limit: number = 5,
  minScore: number = 0.05
): MemoryResult[] {
  const queryTokens = tokenize(query);        // 分词
  const queryTf = termFrequency(queryTokens);  // 词频

  // 预计算所有文档的 TF
  const docTfs = entries.map((e) => termFrequency(tokenize(e.content)));

  // 计算 IDF（逆文档频率）
  const idf = computeIdf(docTfs);

  // 加权查询向量
  const weightedQuery = applyIdf(queryTf, idf);

  for (let i = 0; i < entries.length; i++) {
    const weightedDoc = applyIdf(docTfs[i]!, idf);
    let score = cosineSimilarity(weightedQuery, weightedDoc);

    // 时间衰减：越老的记忆权重越低（半衰期 30 天）
    score *= timeDecay(entry.createdAt);
    // 重要性加权
    score *= 0.5 + entry.importance / 10;
    // 访问频率加权
    score *= 1 + Math.log1p(entry.accessCount) * 0.1;

    if (score >= minScore) results.push({ entry, score });
  }

  return results.sort((a, b) => b.score - a.score).slice(0, limit);
}
```

分词策略：英文按单词分，中文按字分。这样实现简单，在中小规模记忆库（几百条）上效果足够好。

### 4.3 自动合并与智能清理

保存记忆时，如果检测到相似度 > 0.8 的已有记忆，直接合并更新而不是新增：

```typescript
async saveMemory(content: string, category = "fact", importance = 5): Promise<MemoryEntry> {
  const similar = retrieveMemories(content, this.entries, 1, 0.8);
  if (similar.length > 0) {
    const existing = similar[0]!.entry;
    existing.content = this.mergeContent(existing.content, content);
    existing.updatedAt = now;
    existing.importance = Math.max(existing.importance, importance);
    existing.accessCount++;
    await this.persist();
    return existing;
  }
  // ... 创建新记忆
}
```

当记忆超过 500 条时，触发清理。评分公式：

```
score = 新鲜度(30%) + 重要性(40%) + 访问频率(30%)
```

```typescript
async cleanup(targetCount?: number): Promise<void> {
  const scored = this.entries.map((entry) => {
    const daysOld = (now - new Date(entry.createdAt).getTime()) / (1000 * 60 * 60 * 24);
    const recencyScore = Math.exp(-daysOld / 30);       // 指数衰减
    const importanceScore = entry.importance / 10;
    const accessScore = Math.log1p(entry.accessCount) / Math.log1p(100);
    const totalScore = recencyScore * 0.3 + importanceScore * 0.4 + accessScore * 0.3;
    return { entry, score: totalScore };
  });

  scored.sort((a, b) => b.score - a.score);
  this.entries = scored.slice(0, target).map((s) => s.entry);
}
```

存储层可插拔：默认 `InMemoryStorage`，生产环境用 `FileMemoryStorage` 持久化到 JSON 文件。

### 4.4 记忆如何注入对话

Agent 在每次循环开始前，用用户查询去检索记忆，把结果塞进第一条用户消息前面：

```typescript
const memoryContext = await this.memory.getRelevantContext(query);
// 结果格式：
// ## 相关历史记忆
// 1. [fact] 用户喜欢使用 Vue 3 Composition API
// 2. [preference] 项目使用 pnpm 管理依赖
```

这样 LLM 在推理时自然能看到相关背景，无需额外机制。

---

## 五、技能系统：动态注入领域知识

Skill 是从 `SKILL.md` 文件加载的领域知识片段，运行时根据用户查询语义匹配，注入到对话上下文中。

### 5.1 Skill 文件格式

```markdown
---
name: web-search
description: 网络搜索技能，帮助用户查找最新信息
---

## 使用场景

当用户询问实时信息、新闻、股价等需要联网查询的内容时，主动调用搜索工具。

## 搜索策略

1. 提取关键词
2. 使用 search_web 工具
3. 综合结果回答用户
```

### 5.2 匹配机制

基于关键词匹配，简单但有效：

```typescript
// packages/core/src/capabilities/skills/registry.ts
match(query: string): Skill[] {
  const lowerQuery = query.toLowerCase();
  const keywords = lowerQuery.split(/\s+/).filter((w) => w.length >= 1 && !isStopWord(w));

  for (const skill of this.skills.values()) {
    if (skill.metadata.hidden === true) continue;

    const haystack = `${skill.name} ${skill.description} ${skill.content}`.toLowerCase();
    let score = 0;
    for (const kw of keywords) {
      if (haystack.includes(kw)) score += 1;
    }
    if (score > 0) scored.push({ skill, score });
  }

  scored.sort((a, b) => b.score - a.score);
  return scored.slice(0, this.maxActiveSkills).map((s) => s.skill); // 默认最多 3 个
}
```

匹配到的 Skill 会作为一条 `system` 消息注入：

```typescript
const skillMsg: Message = {
  role: "system",
  content: `[Skills]\n## web-search\n网络搜索技能...\n\n## 使用场景\n...`,
};
```

放在已有 system prompt 之后，这样 LLM 既能看到全局指令，也能看到当前场景下的特定技能指导。

---

## 六、流式传输：实时响应

### 6.1 LLM 层：流式调用

```typescript
// packages/core/src/llm/openai.ts
async *chatStream(params: { ... }): AsyncGenerator<StreamChunk> {
  const requestOptions = {
    model: params.model,
    messages: params.messages,
    tools: params.tools,
    tool_choice: params.options?.tool_choice ?? "auto",
    stream: true, // 关键
  };

  const stream = await this.client.chat.completions.create(requestOptions);

  for await (const chunk of stream) {
    const delta = chunk.choices[0]?.delta;

    if (delta?.content) {
      yield { type: "content", delta: delta.content };
    }
    if (delta?.reasoning_content) {
      yield { type: "reasoning", delta: delta.reasoning_content };
    }
    if (delta?.tool_calls) {
      for (const tc of delta.tool_calls) {
        yield {
          type: "tool_call",
          delta: "",
          toolCall: { index: tc.index ?? 0, id: tc.id, name: tc.function?.name, arguments: tc.function?.arguments },
        };
      }
    }
  }
}
```

### 6.2 Agent 层：逐块转发

Agent 不缓存完整内容，而是把流式块逐块 yield 出去：

```typescript
for await (const chunk of stream) {
  if (chunk.type === "content") {
    content += chunk.delta;
    events?.onContentChunk?.(chunk.delta); // 触发外部事件
    yield chunk; // 继续流给更外层
  } else if (chunk.type === "tool_call") {
    hasToolCall = true;
    // 累加工具调用参数（流式拼接）
    yield chunk;
  }
}
```

### 6.3 CLI 层：实时展示

```typescript
// apps/cli/src/interfaces/cli/index.ts
for await (const chunk of chat.chatStream(userInput, preset, events)) {
  if (chunk.type === "reasoning") {
    io.write(`${C.gray}  💭 `);  // 灰色思考前缀
    io.write(chunk.delta);
  } else if (chunk.type === "content") {
    io.write(`${C.brightCyan}● AI:${C.reset} `);
    io.write(chunk.delta); // 逐字输出
  } else if (chunk.type === "tool_call") {
    io.output(`${C.gray}  🔧 准备调用工具...${C.reset}`);
  }
}
```

三层流式：`OpenAI SDK` → `Provider` → `Agent` → `CLI`，每一层都是 `AsyncGenerator`，没有中间缓存，用户感受到的是逐字输出。

---

## 七、Thread：对话历史与上下文截断

`Thread` 只负责一件事：管理消息列表和 Token 估算。

```typescript
// packages/core/src/agent/thread.ts
export class Thread {
  private messages: Message[] = [];
  private maxContextTokens: number;

  addSystemPrompt(content: string): void { ... }
  addMessages(messages: Message[]): void { ... }
  getMessages(): Message[] { ... }
  trim(): void { ... } // 截断超长上下文
}
```

Token 估算采用混合策略：有精确 tokenizer 就用，没有则按字符数估算（中文字符算 1 token，其他字符算 0.25 token）。

截断策略：保留 system prompt，从最早的消息开始删，但至少保留最近 2 条。这样避免上下文爆炸导致 API 费用飙升。

```typescript
trim(): void {
  let totalTokens = 0;
  for (const msg of this.messages) {
    totalTokens += this.estimateMessageTokens(msg);
  }
  if (totalTokens <= this.maxContextTokens) return;

  const startIndex = this.messages[0]?.role === "system" ? 1 : 0;
  const minKeepCount = 2;

  while (totalTokens > this.maxContextTokens && this.messages.length - startIndex > minKeepCount) {
    const removed = this.messages[startIndex]!;
    totalTokens -= this.estimateMessageTokens(removed);
    this.messages.splice(startIndex, 1); // 从头部删除
  }
}
```

---

## 八、架构总览

```
CLI 交互层
  └─ chatStream() → 消费 StreamChunk，实时渲染

Agent 编排层
  ├─ runLoop() → ReAct 循环，最多 10 轮
  ├─ buildMessagesWithSkills() → 动态注入技能
  ├─ Thread → 消息历史 + Token 截断
  └─ MemorySource → 检索相关记忆注入上下文

能力层
  ├─ ToolRegistry → 本地工具注册与执行
  ├─ MCPClientManager → 外部 MCP 服务器连接
  ├─ MemoryManager → TF-IDF 检索 + 自动合并/清理
  └─ SkillRegistry → 关键词匹配 + 动态注入

模型层
  └─ Provider → OpenAI / Anthropic / Gemini 统一抽象
```

---

## 九、关键设计决策

| 决策 | 理由 |
|------|------|
| TF-IDF 而非向量数据库 | 无需外部依赖，几百条记忆上效果足够，代码自包含 |
| 纯 AsyncGenerator 流式 | 无中间缓存，内存友好，三层直通 |
| 工具名加服务器前缀 | 避免 MCP 工具命名冲突，逻辑清晰 |
| 记忆合并阈值 0.8 | 平衡去重与保留细节，避免记忆膨胀 |
| Skill 关键词匹配 | 实现简单，运行时零依赖，效果在多数场景够用 |
| Thread 头部截断 | 保留 system + 最近消息，丢失的是 oldest 而非 newest |
| 最大 10 轮迭代 | 防止无限循环，同时覆盖绝大多数多步任务 |

---

## 十、如何运行

```bash
git clone https://github.com/nfap9/aura-agent.git
cd aura-agent
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 填入 API_KEY 和 BASE_URL

npm run dev:cli
```

输入问题，看 Agent 如何一步步思考、调用工具、返回结果。

---

> 本文所有代码均来自 [aura-agent](https://github.com/nfap9/aura-agent) 仓库，可直接对照阅读。Agent 的实现不需要框架，理解循环、工具、记忆、流式这几个核心概念后，用几十行代码就能搭出一个最小可用版本。

---

# Docker 与 Docker Compose 实战指南

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/docker-compose-guide/
> **分类**：工程化
> **标签**：docker, docker-compose, 容器化, 部署, 运维, 工程化
> **发布日期**：2026-06-17
> **更新日期**：2026-06-17
> **描述**：以 tenant-hub 项目为例，讲解 Docker 容器化与 Docker Compose 多容器编排的实际应用


> 本文以 [tenant-hub](https://github.com/nfap9/tenant-hub) 项目（公寓物业管理系统）为例，讲解 Docker 和 Docker Compose 的实际使用。该项目使用 pnpm monorepo 架构，包含后端 API、前端 Web 和小程序三个应用。

---

## 核心概念

**镜像（Image）**

镜像是一个只读模板，包含运行应用所需的完整文件系统、依赖库和配置。基于 Dockerfile 构建生成。每一层构建指令创建一个新层，Docker 通过层缓存加速重复构建。

**容器（Container）**

容器是镜像的运行实例。拥有独立的进程空间、文件系统和网络，但共享宿主机内核。相比虚拟机，容器启动更快、资源占用更少。

**卷（Volume）**

容器停止后数据会丢失。卷用于将容器内的数据持久化到宿主机，或者在容器之间共享数据。

---

## 安装配置

### Ubuntu / Debian

```bash
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

### macOS

```bash
brew install --cask docker
```

安装完启动 Docker Desktop 应用，确保 daemon 在运行。

### 验证

```bash
docker --version
docker compose version
```

### 免 sudo 使用

```bash
sudo usermod -aG docker $USER
newgrp docker
```

`newgrp docker` 使当前终端立即生效，其他终端需重新登录。

---

## Docker 核心命令

### 镜像操作

```bash
docker search nginx          # 搜索镜像
docker pull nginx:latest     # 拉取镜像
docker images                # 列出本地镜像
docker rmi nginx:latest      # 删除镜像
docker history nginx:latest  # 查看构建层
```

### 容器操作

```bash
# 前台运行
docker run -it nginx

# 后台运行，端口映射
docker run -d -p 8080:80 --name my-nginx nginx

# 参数说明
# -it      交互式 + 伪终端
# -d       后台运行
# -p 8080:80  端口映射（宿主机:容器）
# -v       卷挂载
# --name   指定容器名
# --rm     停止后自动删除
# -e       环境变量

docker ps                    # 查看运行中容器
docker ps -a                 # 查看所有容器

docker stop my-nginx         # 停止
docker start my-nginx        # 启动
docker restart my-nginx      # 重含

docker logs -f my-nginx      # 查看日志
docker exec -it my-nginx /bin/bash  # 进入容器

docker rm my-nginx           # 删除
docker rm -f my-nginx        # 强制删除运行中容器
```

### 卷管理

```bash
docker volume create my-data          # 创建命名卷
docker volume ls                      # 列表
docker run -d -v my-data:/data nginx  # 挂载卷
docker run -d -v $(pwd)/data:/app/data nginx  # 绑定挂载
docker volume prune                   # 清理未使用卷
```

绑定挂载将宿主机目录直接映射到容器，开发时常用。生产环境建议使用 Docker 管理的命名卷，避免宿主机与容器权限不一致的问题。

### 网络管理

```bash
docker network ls                              # 列表
docker network create my-network               # 创建
docker run -d --network my-network --name web nginx  # 指定网络
docker network inspect my-network              # 详情
```

自定义网络中，容器通过服务名互访，无需记录 IP。

---

## Dockerfile 编写

以 tenant-hub 项目的后端 API 为例。该项目使用 pnpm monorepo，需要在工作空间中管理多个子项目的依赖。

### 后端 API Dockerfile

```dockerfile
FROM node:22-alpine AS base
ENV PNPM_HOME=/pnpm
ENV PATH=$PNPM_HOME:$PATH
RUN sed -i 's|dl-cdn.alpinelinux.org|mirrors.aliyun.com|g' /etc/apk/repositories \
  && corepack enable \
  && apk add --no-cache openssl wget
WORKDIR /app

FROM base AS deps
ENV HUSKY=0
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.base.json ./
COPY apps/api/package.json apps/api/package.json
RUN pnpm install --frozen-lockfile

FROM deps AS development
COPY apps/api apps/api
EXPOSE 4000
CMD ["sh", "-c", "pnpm --filter @tenant-hub/api prisma generate && pnpm --filter @tenant-hub/api dev"]

FROM deps AS build
COPY apps/api apps/api
RUN pnpm --filter @tenant-hub/api prisma generate
RUN pnpm --filter @tenant-hub/api build

FROM base AS production
ENV HUSKY=0
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.base.json ./
COPY apps/api/package.json apps/api/package.json
COPY apps/api/prisma apps/api/prisma
RUN pnpm install --frozen-lockfile --prod
RUN pnpm --filter @tenant-hub/api prisma generate
COPY --from=build /app/apps/api/dist apps/api/dist
WORKDIR /app/apps/api
EXPOSE 4000
CMD ["sh", "-c", "pnpm prisma migrate deploy && node dist/server.js"]
```

### 关键细节

**多阶段构建**

该 Dockerfile 定义了 5 个阶段：

1. **base** —— 基础镜像，设置 pnpm 环境和安装系统依赖（openssl、wget）
2. **deps** —— 安装生产依赖，利用缓存加速
3. **development** —— 开发环境，包含 Prisma generate 和 dev 命令
4. **build** —— 构建产物
5. **production** —— 生产环境，仅包含构建产物和生产依赖，体积最小

**层缓存优化**

先复制依赖文件（`package.json`、`pnpm-lock.yaml`），再复制代码。这样代码修改时，依赖层缓存不会失效，构建速度大幅提升。

**生产环境启动**

```
CMD ["sh", "-c", "pnpm prisma migrate deploy && node dist/server.js"]
```

生产环境启动时先执行数据库迁移，确保数据库 schema 与代码一致，然后启动应用。

### 前端 Web Dockerfile

```dockerfile
FROM node:22-alpine AS base
ENV PNPM_HOME=/pnpm
ENV PATH=$PNPM_HOME:$PATH
RUN corepack enable
WORKDIR /app

FROM base AS deps
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.base.json ./
COPY apps/tenant-web/package.json apps/tenant-web/package.json
RUN pnpm install --frozen-lockfile

FROM deps AS development
COPY apps/tenant-web apps/tenant-web
EXPOSE 5173
CMD ["pnpm", "--filter", "@tenant-hub/tenant-web", "dev"]

FROM deps AS build
ARG VITE_API_BASE_URL=http://localhost:4000/api
ENV VITE_API_BASE_URL=$VITE_API_BASE_URL
COPY apps/tenant-web apps/tenant-web
RUN pnpm --filter @tenant-hub/tenant-web build

FROM nginx:1.27-alpine AS production
COPY apps/tenant-web/nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /app/apps/tenant-web/dist /usr/share/nginx/html
EXPOSE 80
```

前端构建产物是静态文件，最终用 Nginx 作为静态服务器。构建时通过 `ARG` 传入 API 基础地址，生成环境相关的静态资源。

---

## Docker Compose 多容器编排

### 基础结构

以下是 tenant-hub 项目的生产环境 Compose 配置：

```yaml
version: "3.9"

services:
  postgres:
    image: postgres:16-alpine
    container_name: tenant-hub-postgres
    restart: unless-stopped
    env_file:
      - .env.production
    environment:
      POSTGRES_DB: tenant_hub
      POSTGRES_USER: postgres
    volumes:
      - /home/ubuntu/tenant-hub-data/postgres:/var/lib/postgresql/data
    ports:
      - '5432:5432'
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 3s
      retries: 10

  api:
    build:
      context: .
      dockerfile: apps/api/Dockerfile
      target: production
    container_name: tenant-hub-api
    restart: unless-stopped
    env_file:
      - .env.production
    environment:
      NODE_ENV: production
      DATABASE_URL: postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/tenant_hub?schema=public
    ports:
      - '4000:4000'
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ['CMD-SHELL', 'wget -qO- http://localhost:4000/health || exit 1']
      interval: 10s
      timeout: 3s
      retries: 12

  tenant-web:
    build:
      context: .
      dockerfile: apps/tenant-web/Dockerfile
      target: production
      args:
        - VITE_API_BASE_URL=${VITE_API_BASE_URL}
    container_name: tenant-hub-tenant-web
    restart: unless-stopped
    ports:
      - '80:80'
    depends_on:
      api:
        condition: service_healthy
    healthcheck:
      test: ['CMD-SHELL', 'wget -qO- http://localhost:80/ || exit 1']
      interval: 10s
      timeout: 3s
      retries: 12
```

### 服务依赖

配置中使用了 `depends_on` 的 `condition: service_healthy` 语法：

- `tenant-web` 等待 `api` 健康后才启动
- `api` 等待 `postgres` 健康后才启动

这样确保服务启动顺序正确，应用不会在数据库还未就绪时尝试连接。

### 环境变量管理

敏感配置放在 `.env.production` 文件中：

```
POSTGRES_PASSWORD=*** =***
```

通过 `env_file` 引入到各个服务，配置与代码分离。

---

## 核心命令

```bash
# 启动所有服务（前台）
docker compose up

# 后台启动
docker compose up -d

# 重新构建镜像并启动（代码变更后）
docker compose up -d --build

# 查看日志
docker compose logs -f
docker compose logs -f api  # 仅查看 api 服务

# 停止并删除容器
docker compose down

# 停止并删除容器 + 卷（数据丢失）
docker compose down -v

# 查看状态
docker compose ps

# 进入容器
docker compose exec api /bin/sh

# 重启单个服务
docker compose restart api
```

---

## 生产环境注意事项

### 日志限制

Docker 默认日志驱动无限增长，必须限制：

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

或全局配置 `/etc/docker/daemon.json`：

```json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
```

修改后 `sudo systemctl restart docker` 生效。注意此操作会停止所有容器。

### 数据库备份

```bash
# 备份
docker compose exec db pg_dump -U postgres tenant_hub > backup.sql

# 恢复
docker compose exec -T db psql -U postgres tenant_hub < backup.sql
```

`-T` 禁用 TTY 分配，避免 stdin 交互问题。

定时备份脚本：

```bash
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
docker compose exec -T db pg_dump -U postgres tenant_hub > /backup/tenant_hub_${DATE}.sql
find /backup -name "tenant_hub_*.sql" -mtime +7 -delete
```

### 时区配置

容器默认 UTC 时区。同步宿主机时区：

```yaml
services:
  api:
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone:ro
```

### 端口冲突

如果 80/443 被宿主机进程占用，可修改端口映射：

```yaml
ports:
  - "8080:80"
```

或者停止宿主机已有服务：

```bash
sudo lsof -i :80
sudo ss -tlnp | grep 80
```

### 数据库连接问题

`depends_on` 仅保证容器启动顺序，不保证服务 ready。如果应用在数据库初始化期间尝试连接，会报错。

解决方案：

1. 在应用层实现重试逻辑
2. 添加 wait 脚本：

```bash
#!/bin/sh
until nc -z postgres 5432; do
  echo "Waiting for PostgreSQL..."
  sleep 1
done
exec "$@"
```

在 Dockerfile 中 CMD 改为 `CMD ["./wait-for-db.sh", "node", "dist/server.js"]`

### 权限管理

生产环境不建议使用绑定挂载。宿主机目录权限与容器内用户可能不一致，导致应用无法读写文件。优先使用 Docker 管理的命名卷。

---

## 常用维护

### 清理空间

```bash
docker container prune     # 删除已停止容器
docker image prune -a      # 删除未使用镜像
docker volume prune        # 删除未使用卷
docker system prune -a --volumes  # 一键清理（慎用）
```

执行前建议 `docker system df` 查看磁盘占用。

### 查看资源占用

```bash
docker stats
```

实时显示所有容器的 CPU、内存、网络、IO 使用情况。

### 镜像导出导入

```bash
docker save -o tenant-hub.tar tenant-hub-api:latest

# 在目标机器加载
docker load -i tenant-hub.tar
```

适用于内网环境无法直接 `docker pull` 的场景。

---

## 总结

Docker 的核心价值在于环境一致性和快速部署。以 tenant-hub 项目为例，实际使用流程为：

1. 编写 Dockerfile 定义构建流程（多阶段构建、层缓存优化）
2. 编写 docker-compose.yml 定义服务编排（应用、数据库、前端、依赖关系）
3. 使用 `docker compose up -d --build` 构建并启动整个技术栈
4. 生产环境配置日志限制、健康检查、数据备份

学习路径建议先掌握单容器运行，再引入 Compose 处理多服务协作。具体问题查阅官方文档比通读大全更有效。


---

# Claude Code 实战笔记

> **类型**：笔记
> **URL**：https://nfap9.github.io/notes/claude-code-guide/
> **分类**：工程化
> **标签**：claude-code, ai-coding, 工具, ccswitch, 国产模型
> **发布日期**：2026-06-17
> **更新日期**：2026-06-18
> **描述**：Claude Code 接入国产模型、工程化配置与高效使用指南


> 把 Claude Code 当 IDE 用，而不是当聊天工具。

---

## 接入国产模型

Anthropic Claude API 费用较高，生产环境推荐接入国产模型。编码能力与工程化效果已达到可用水平，成本却低一个数量级。

### 模型推荐排序（2026-06）

| 排名 | 模型 | 特点 | API 端点 |
|------|------|------|----------|
| 1 | **GLM-5.2** (智谱) | 编码能力最强，推理深度提升，适合大型工程 | `https://open.bigmodel.cn/api/paas/v4/` |
| 2 | **Kimi K2.7** (月之暗面) | 长文本+推理增强，代码理解能力大幅提升 | `https://api.moonshot.cn/v1` |
| 3 | **DeepSeek V4 Pro** | 数学/逻辑极强，性价比依然最高 | `https://api.deepseek.com/v1` |
| 4 | **MiniMax M3** | 多模态+工具调用稳定，适合复杂 Agent 场景 | `https://api.minimax.chat/v1` |

其他备选：Qwen3-Max、Baichuan5、Step-2。建议每个模型都重试 5 分钟自己的主力项目，看看哪个在自己代码库上表现最好。

### ccswitch 安装与配置

推荐用 `ccswitch` 管理多个模型配置，一键切换。

```bash
# 安装
npm install -g claude-settings-switch

# 添加 GLM 配置
ccs add glm https://open.bigmodel.cn/api/paas/v4/ <glm-api-key>

# 添加 Kimi 配置
ccs add kimi https://api.moonshot.cn/v1 <kimi-api-key>

# 添加 DeepSeek 配置
ccs add ds https://api.deepseek.com/v1 <deepseek-api-key>

# 查看已有配置
ccs list

# 切换到 GLM
ccs sw glm

# 查看当前使用的配置
ccs current
```

配置文件存储在 `~/.ccswitcher/configs.json`，Claude Code 配置在 `~/.claude/settings.json`。

### 手动配置（不用 ccswitch）

直接修改 `~/.claude/settings.json`：

```json
{
  "provider": "openai",
  "model": "glm-4",
  "apiKey": "<glm-api-key>",
  "apiUrl": "https://open.bigmodel.cn/api/paas/v4/"
}
```

各家提供商的 OpenAI 兼容格式略有不同，具体参考对方文档。一般只需改 `apiUrl` 和 `apiKey`，`model` 填对应模型名即可。

---

## 目录结构

Claude Code 会自动读取项目目录下的特定文件，作为项目级指令和自定义命令。

```
项目根目录/
├── .claude/
│   ├── CLAUDE.md          # 项目级系统指令，每次对话自动带入上下文
│   └── commands/          # 自定义命令，每个 .md 文件就是一个命令
│       ├── review.md      # 代码审查
│       ├── refactor.md    # 重构提示
│       └── test.md        # 生成测试
├── AGENTS.md               # 项目概述、架构说明
└── ...
```

### 文件作用

| 文件 | 作用 | 生效范围 |
|------|------|---------|
| `~/.claude/CLAUDE.md` | 全局系统指令 | 所有项目 |
| `.claude/CLAUDE.md` | 项目级系统指令 | 当前项目 |
| `.claude/commands/*.md` | 自定义命令 | 当前项目 |
| `CLAUDE.md` (根目录) | 项目级指令 | 当前项目 |

项目级 `CLAUDE.md` 会覆盖全局的内容。建议每个代码库都放一个 `.claude/CLAUDE.md`。

### AGENTS.md 链接到 CLAUDE.md

如果你已有 `AGENTS.md` 写了项目概述，不需要重复写一份。在 `CLAUDE.md` 中直接引用即可：

```markdown
# 项目指令

参见项目概述: [AGENTS.md](../AGENTS.md)

## 编码规约

- 使用 TypeScript，严格模式
- 不允许使用 `any`
- 所有 API 调用必须有类型定义
```

Claude Code 会自动跟踪相对路径并读取文件。也可以用符号链接：

```bash
ln -s AGENTS.md .claude/AGENTS.md
```

然后在 `CLAUDE.md` 中引用 `./AGENTS.md`。

### 自定义命令示例

创建 `.claude/commands/review.md`：

```markdown
# 代码审查

对当前文件进行代码审查，重点关注：
1. 类型安全性
2. 错误处理
3. 性能问题
4. 可读性

输出格式：每个问题一行，带具体代码位置。
```

使用时输入 `/review` 即可触发。命令名就是文件名（不含 `.md`）。

---

## 常用指令

### 内置命令

| 指令 | 作用 |
|------|------|
| `/clear` | 清空当前对话上下文，不影响文件系统状态 |
| `/compact` | 压缩对话历史，节省 token |
| `/cost` | 查看当前会话的费用 |
| `/exit` | 退出 Claude Code |
| `/help` | 查看命令帮助 |
| `/models` | 查看当前可用模型 |
| `/terminal` | 打开终端模式（只返回命令，不解释） |

### 文件操作

| 指令 | 作用 |
|------|------|
| `find` | 搜索文件，支持正则 |
| `read` | 读取文件内容，支持行范围 |
| `edit` | 精确编辑文件，必须指定行号 |
| `write` | 全重写文件 |
| `grep` | 文件内容搜索 |
| `ls` | 列出目录 |

### 执行命令

| 指令 | 作用 |
|------|------|
| `bash` | 执行 shell 命令，需要确认 |
| `cat` | 查看文件内容 |
| `git` | Git 操作，需要确认 |
| `npm` / `pnpm` / `yarn` | 包管理操作 |

Claude Code 执行可能改变状态的命令（如 `git commit`、`npm install`）时会弹出确认提示，输入 `y` 确认。

### 实用模式

**仅读模式**

不想让 Claude 修改文件时：

```
只读查看这个文件的结构，不要改。
```

或者用带引号的问句，不包含修改指令。

**任务式对话**

对于复杂任务，先让 Claude 列出计划，确认后逐步执行：

```
实现用户登录功能，包含：1. JWT token 管理 2. 登录状态缓存 3. 登出逻辑。
请先列出实现步骤，我确认后你再开始写代码。
```

**结果限制**

限制输出长度，避免滚屏：

```
给出最重要的 3 个修改建议，每条不超过 50 字。
```

---

## 工程化配置

### 全局 CLAUDE.md

`~/.claude/CLAUDE.md` 里放通用编码规范：

```markdown
# 全局编码规范

## 通用原则

- 使用 TypeScript，严格模式
- 禁止使用 `any`
- 所有函数必须有返回类型
- 所有 API 调用必须有错误处理
- 优先使用显式返回而非隐式转换

## 文件操作

- 修改文件前先读取完整内容
- 使用精确的行号编辑，避免全重写
- 不要删除未使用的 import，除非确认无用
```

### 项目级 CLAUDE.md

`.claude/CLAUDE.md` 里放项目特定规范：

```markdown
# 项目指令

参见项目概述: [AGENTS.md](../AGENTS.md)

## 技术栈

- Next.js 15 + App Router
- Prisma ORM + PostgreSQL
- Tailwind CSS
- pnpm monorepo

## 架构约定

- API 放在 `apps/api/src`
- 组件放在 `apps/web/components`
- 工具函数放在 `packages/shared`
- 不跨应用直接引用内部路径

## 提交规范

- 使用 Conventional Commits
- 测试通过后才提交
```

### 自定义命令集

常用的自定义命令放在 `.claude/commands/`：

**review.md** —— 代码审查
```markdown
# 代码审查

对当前文件进行审查，重点：
1. 类型安全
2. 错误处理
3. 性能
4. 可读性

每个问题一行，带具体位置。
```

**refactor.md** —— 重构提示
```markdown
# 重构建议

分析当前代码，给出重构建议。
不要直接修改，只给出建议列表。
```

**test.md** —— 生成测试
```markdown
# 生成测试

为当前文件生成单元测试，覆盖主要路径。
使用 vitest，测试文件放在同目录的 __tests__ 下。
```

---

## 效率技巧

### 减少 Token 消耗

1. **使用 `/compact`** —— 对话变长后压缩历史，保留文件状态但清空对话记录
2. **小步进行** —— 每次只给一个具体任务，而非整个需求文档
3. **限制范围** —— 指定具体文件或目录，避免让 Claude 扫描整个代码库
4. **使用自定义命令** —— 封装常用模式，减少每次重复解释

### 多模型切换策略

**开发阶段**：用国产模型做大部分工作，成本极低，效率很高。

**复杂逻辑**：遇到国产模型反复出错的复杂算法/架构问题，切换到 Claude 或 GPT-4 处理。

**审查阶段**：重要代码审查用原版 Claude，确保没有潜在问题。

### 快捷键

| 快捷键 | 作用 |
|--------|------|
| Tab | 补全建议 |
| Ctrl+C | 取消当前操作 |
| Ctrl+D | 退出（等同 `/exit`） |
| ↑ / ↓ | 浏览历史记录 |
| Ctrl+R | 搜索历史记录 |

---

## 常见问题

### Claude Code 启动失败

```bash
# 检查 Node 版本
node -v  # 需要 18+

# 重新登录
claude auth login

# 清理配置
rm -rf ~/.claude
```

### 国产模型返回格式不对

部分国产模型的 OpenAI 兼容层不完整，可能出现：
- 不支持 function calling → 文件操作可能出问题
- 不支持流式输出 → 响应变慢
- 不支持某些系统提示 → 行为与原版不一致

解决方案：支持较完整的模型（GLM-5.2 / Kimi K2.7 / DeepSeek V4 Pro），开发环境可以尝试更多选择。

### 网络不稳定

国产模型 API 有时会出现超时或限流：
- 配置重试逻辑（大部分 ccswitch 已内置）
- 开发环境可以用本地模型（Ollama 等）
- 生产环境选择有 SLA 保障的提供商

### 文件编辑不精确

Claude Code 的编辑是基于行号的精确编辑，如果文件太大或结构复杂，可能会出现偏移。建议：
- 先让 Claude 列出要修改的行号，确认后再执行
- 对于大文件，先拆分成小任务
- 修改后用 `git diff` 检查结果


---

# AI Coding：前端 UI 规范笔记

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/ai-coding-ui-guidelines/
> **分类**：AI Coding
> **标签**：ai-coding, ui-guidelines, frontend, skill, 设计规范
> **发布日期**：2026-06-16
> **描述**：前端在 AI Coding 中如何保证样式一致性——通过制定可被 AI 理解和遵循的 UI 规范体系，并将规范编码为 Skill 约束契约，让 Agent 写出的代码天然符合设计规范。


> 前端在 AI Coding 中如何保证样式一致性——当 AI 生成的代码散落在项目各处，用着各自不同的颜色、字号和间距时，技术债就开始以指数速度累积。本文分享一套**可被 AI 理解和遵循**的 UI 规范体系，以及如何通过 Skill 将其编码为可复用的约束契约，让 Agent 写出的代码天然符合设计规范。

---

## 一、制定 UI 规范

### 1.1 变量：全局通用 CSS 变量

前端样式的基础就是各种属性的值，统一色彩、字体、间距、边框、阴影这些直接与视觉相关的属性值能很好的统一视觉效果；

制定变量时应遵循以下原则：

**语义化命名**：变量名描述"用途"而非"具体值"。例如 `--color-primary` 而非 `--color-blue`，`--spacing-md` 而非 `--spacing-16px`。这样当设计调整时，修改变量值即可，不需要改动所有引用。

**全面覆盖**：颜色、字体、间距、圆角、阴影、过渡等视觉维度必须全部定义，不能留空白。任何空白都会被 AI 用"魔法数字"填充。

**与框架对齐**：如果使用了第三方组件库，自定义变量应与其内部变量一一对应，仅做命名映射或值覆盖。这样 AI 在使用框架组件或自定义样式时，心智模型一致。

**有层级**：按语义组织，如每种颜色都有主色、多个浅色阶、深色阶、以及 RGB 值。让 AI 在需要 hover 背景、轻提示、重强调时都能直接选择对应的变量。

**有兼容层**：对于已有但即将废弃的历史变量，保留在兼容层中，同时引导新代码使用新变量。避免存量代码因变量删除而大面积报错。

此外，如果使用了第三方 UI 库，还需要维护一个**桥接层**，将自定义变量映射到库的内置变量。例如，使用 Element Plus 时，将 `--color-primary` 映射到 `--el-color-primary`，让框架组件在不经额外配置的情况下也自动符合品牌规范。

### 1.2 组件：使用优先级与分层封装

组件的意义不仅能减少反复造轮子也能统一同类视图的效果，第二点在 AI Coding 尤为重要，不要"让 AI 每次都从零写"，而是**用已有的封装来减少 LLM 决策**。

**组件使用优先级**：

```
项目自定义组件  >  第三方组件库组件  >  手写组件
```

使用这样的策略能最大化组件复用的比例也能保证特殊视觉效果的需求

**在项目封装层解决差异，让业务层只管复用。**

### 1.3 页面布局：为典型场景制定规范

由于页面内容千变万化，我们不可能遍历所有场景，但可以最大化统一典型场景；

向 AI 定义如何划分视图**并不是一个路由页面就是一个视图，而是一个独立业务场景就是一个 layout**，实践中一个 tab 页面、一个弹窗、一个抽屉可以很容易判断为一个视图，但当页面组合了多个组件时 ai 难以区分；可根据项目中的习惯使用标题、分割线区分不同视图；

---

## 二、使用 Skill 解决 AI Coding 的风格漂移

以上规范如果停留在文档层面，只能解决人类开发者的问题。AI 不会主动去查文档，它需要被**程序化地约束**。Skill 就是这个约束机制——它是 AI 的"可加载规范"，在每次生成代码时自动注入到上下文中。

### 2.1 编写 Skill 要注意的六个要点

#### 要点一：用"禁止 + 必须"代替"建议"

Skill 中的规则必须是命令式的，不能有"可以""建议""最好"这样的模糊词。AI 对模糊词的理解是弹性的，会倾向选择最省力的方案——通常就是硬编码。

给每条规则配一个**反面教材**（Forbidden）和一个**正确示范**（Required）。这让 AI 不只是知道"该做什么"，还知道"什么算违规"。

例如：

```
禁止使用硬编码颜色值。所有颜色必须使用 CSS 变量。
Forbidden: color: #0d8891; color: blue; color: rgb(0,0,0).
Required: var(--color-primary); var(--text-color-regular); var(--border-color).
```

#### 要点二：提供决策树，而不是列举

当 AI 面对"我该用什么组件"时，它需要的是**决策流程**，而不是一张罗列。决策树能减少模糊地带。

例如：

```
需要对话框/模态框？
  → 标准布局（标题 + 底部操作按钮）？→ 使用 BaseDialog
  → 自定义布局（特殊结构、无标准底部）？→ 使用 el-dialog

需要展示状态？
  → 二进制状态（成功/失败）？→ 使用 StatusTag
  → 多状态或简单标签？→ 使用 el-tag

需要展示数值统计？
  → 单值 + 标签 + 可选副标签？→ 使用 StatCard
  → 多值、图表或复杂卡片？→ 使用标准卡片类 + 自定义内容
```

#### 要点三：Token 表按"使用场景"组织，而不是按字母顺序

AI 查 Token 时不是"我想找某个变量名"，而是"我需要这个场景下的颜色/间距"。因此 Token 表必须按使用场景组织，并在表头注明用途。

例如：

| 变量 | 使用场景 |
|------|----------|
| --color-primary | 主操作按钮、品牌标识、关键链接 |
| --color-primary-light-9 | 主色的浅背景，如 hover 状态、提示框背景 |
| --color-success | 成功状态、完成标记、正向指标 |
| --color-success-light-9 | 成功状态标签背景 |
| --spacing-sm | 表单元素间小间隙、按钮内图标与文字间距 |
| --spacing-lg | 卡片内边距、模块间标准间距 |
| --spacing-2xl | 页面区块间距、大卡片内边距 |

#### 要点四：渐进式加载，不要一次性塞满

Skill 的上下文窗口是有限资源。不要把所有 Token 表、所有组件说明都塞进 SKILL.md 主文件。应该分层：

```
skills/
└── ui-guidelines/
    ├── SKILL.md                    ← 第一层：触发规则 + 核心禁令（必须常驻上下文）
    └── references/
        ├── design-tokens.md        ← 第二层：完整 Token 表（需要时加载）
        ├── component-guide.md      ← 第二层：组件决策树（需要时加载）
        └── layout-templates.md     ← 第二层：页面布局模板（需要时加载）
```

SKILL.md 只保留最核心的禁令（约 10 条以内），确保触发时就能加载。详细的 Token 值、组件接口、布局模板放在 references 中，当 AI 需要查具体色值或组件用法时按需读取。这样可以避免每次对话都浪费大量 token 在"可能用不到"的参考信息上。

#### 要点五：全局默认值必须写入 Skill

很多规范不是通过 Token 体现，而是通过全局配置（如框架默认 props）体现的。AI 必须知道这些全局默认值，否则它会在每次使用时重复添加，或者不知道某些行为已经内置。

例如：

```
全局默认行为（无需在组件中重复声明）：
- el-table 已全局开启 stripe（斑马纹），不需要在任何表格上加 stripe 属性
- el-form 已全局设置 label-position="top"，不需要在任何表单上加 label-position 属性
- 表单控件标准高度为 44px，通过全局设置或变量控制
```

如果 AI 不知道这些全局设置，它可能在每次写表格时都加上 stripe，在每次写表单时都加上 label-position="top"，导致代码冗余且破坏全局一致性。

#### 要点六：规则必须可验证，最好有代码对比

Skill 不能只写"该怎么做"，还应该包含有/无 Skill 的代码对比，让 AI 能直观理解规范的实际效果。

例如，展示一段无 Skill 的违规代码（硬编码色值、字号、间距、圆角），然后列出问题清单，再展示一段有 Skill 的规范代码（全部使用变量）。这种对比不仅帮助 AI 学习，也方便人类审查时快速判断 AI 是否遵循了规范。

### 2.2 Skill 的标准结构

综合以上要点，一个 UI 规范 Skill 的标准结构如下：

**SKILL.md（主文件，常驻上下文）**包含：

- 元数据（触发条件描述）：让 AI 知道何时加载该 Skill
- 核心禁令（约 10 条）：用"禁止/必须"写成的命令式规则，每条配反面教材和正确示范
- 文件索引：告诉 AI 去哪里查更详细的 Token 表、组件决策树和布局模板

**references/design-tokens.md**：按使用场景组织的完整 Token 速查表（颜色、字体、间距、圆角、阴影、过渡、布局常量）。

**references/component-guide.md**：组件决策树 + 自定义组件列表 + 第三方组件映射 + 全局工具类索引 + Vue SFC 模板规范。

**references/layout-templates.md**：典型页面布局模板（列表页、表单页、卡片网格、仪表盘、按钮集合），每个模板包含结构示意、使用的 Token/组件、间距关系、响应式策略。

### 2.3 迭代与维护

Skill 不是写完就冻结的文档。随着项目演进，它需要持续迭代：

- **从代码审查中收集反模式**：每次发现 AI 硬编码了值，就检查是 Token 缺失还是 Skill 规则不足。如果是规则问题，更新 SKILL.md 的 Mandatory Rules。
- **组件新增时同步更新**：当项目新增自定义组件时，立即更新 component-guide.md 的决策树。否则 AI 会继续用旧的组件拼凑。
- **Token 变更时三方同步**：如果新增或修改变量，同步更新源码变量文件、桥接层、以及 design-tokens.md。三者必须一致。
- **定期用 AI 自检**：让 AI 审查现有代码，检查是否还有硬编码值。这是 Skill 的反向应用——不仅用于生成规范代码，也用于检查和修复历史代码。

---

## 三、总结

一套好的 UI 规范 + Skill 体系应该满足：

1. **Token 全覆盖**：颜色、字体、间距、圆角、阴影、过渡全部定义，不留空白让 AI 自由发挥
2. **组件分层**：自定义组件优先于第三方库，第三方库优先于手写，每层都有清晰的迁移路径
3. **布局模板化**：典型页面有标准结构，AI 按模板组装而不是每次自由发挥
4. **Skill 命令化**：用"禁止/必须"代替"建议"，用决策树代替列举，用反面教材让 AI 理解违规
5. **渐进式加载**：核心禁令常驻上下文，详细参考按需加载，不浪费 token
6. **可迭代**：从代码审查中收集反模式，从新增组件中更新决策树，从 Token 变更中同步三方文档

**规范不是给人类看的文档，而是给 AI 执行的契约。当 AI 在写代码时自动引用规范变量和自定义组件时，契约就生效了。**


---

# Vue 项目代码与 UI 规范：从团队约定到可落地实践

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/vue-project-code-guidelines/
> **分类**：工程化
> **标签**：vue, typescript, element-plus, 代码规范, 设计系统, 团队开发, ai-coding
> **发布日期**：2026-06-16
> **描述**：总结一套面向 Vue + TypeScript + Element Plus 技术栈的项目级代码规范，覆盖组件架构、函数设计、TypeScript 约束、状态管理、API 请求层以及设计 Token 与布局模式，可直接作为团队开发约定与代码审查清单。


> 这套规范来自一个实际 Vue + TypeScript + Element Plus 项目的迭代总结。它的目标不是写出一份“完美文档”，而是让团队里的每个开发者（包括 AI Agent）在写代码时，能做出一致且可维护的决策。文中既包含原则，也包含可直接执行的行数限制、命名约定、组件选择决策树和审查清单。

---

## 一、核心原则

在动笔写代码之前，先统一三条最基本的原则。它们会贯穿后续的每一条具体规则。

### 1.1 单一职责

一个组件只做一件事，一个函数只做一件事。当某个文件开始同时处理数据获取、数据转换、UI 渲染和事件分发时，它就具备了被拆分的信号。

### 1.2 禁止魔法数字

所有视觉值必须使用 CSS 变量（全局或组件级），所有逻辑中的硬编码值必须提取为具名常量。魔法数字是技术债中最隐蔽也最难批量替换的一种。

### 1.3 优先组合而非重复

复用项目组件、工具函数和组合式函数。不要复制粘贴相似代码。重复代码会在 AI 或新人参与开发时被再次复制，导致问题呈指数扩散。

---

## 二、代码架构规则

### 2.1 组件大小限制

| 目标 | 最大行数 | 超出后的处理 |
|------|---------|-------------|
| 单个 Vue SFC | 300–400 行 | 拆分为子组件，或将逻辑移到 composable / utils |
| 单个函数 | 50–60 行 | 提取为具有描述性名称的子函数 |
| `<script setup>` 块 | 应一眼可读 | 将复杂逻辑移到组合式函数或工具文件 |

组件太长往往意味着职责过多，阅读、测试和后续修改成本都会上升。

### 2.2 组件拆分原则

满足以下任一条件时，就应当拆分组件：

- **复用**：同一个 UI 模式出现在多个页面或模块中 → 提取到 `src/components/`。
- **复杂度**：一个组件同时承担数据获取、转换、渲染、事件处理，或拥有超过 3 个不同视觉区块 → 拆分为子组件。
- **视图分层**：页面包含多个由标题或分割线分隔的独立业务区块 → 每个区块下沉到页面 `components/` 目录。
- **逻辑过重**：一个组件中有超过 100 行纯逻辑（computed、watch、异步函数、数据转换）→ 移到 `composables/` 或 `utils/`。

推荐的目录结构：

```
src/
├── components/              → 全局可复用组件
│   ├── BaseDialog.vue
│   ├── StatCard.vue
│   └── ...
├── views/
│   ├── some-page/
│   │   ├── index.vue        → 页面入口（轻量，委托给子组件）
│   │   └── components/      → 页面局部组件
│   │       ├── SearchFilter.vue
│   │       └── DataTable.vue
│   └── ...
```

### 2.3 函数设计规则

- **一个函数，一个动作**：要么获取数据、要么转换数据、要么渲染、要么处理事件，不要同时做四件事。
- **尽早提取**：如果一个函数需要注释来解释其步骤，这些步骤应该成为独立函数。
- **优先纯函数**：`src/utils/` 中的工具函数应无副作用。副作用属于事件处理器、生命周期钩子、组合式函数或 Pinia actions。
- **按意图命名**：`fetchUserList` 优于 `getData`，`handleSubmit` 优于 `clickBtn`。

| 差的 | 好的 | 原因 |
|------|------|------|
| `getData()` | `fetchUserList()` | 意图清晰 |
| `clickBtn()` | `handleSubmit()` | 意图清晰 |
| `doSomething()` | `validateForm()` | 具体动作 |
| `tmp1`, `tmp2` | `filteredUsers`, `sortedColumns` | 自解释 |
| `flag` | `isLoading`, `hasError` | 布尔意图明确 |

### 2.4 命名约定

| 目标 | 约定 | 示例 |
|------|------|------|
| Vue 组件 | PascalCase | `BaseDialog.vue`, `StatCard.vue` |
| TS 文件 / 组合式函数 | camelCase | `useUserStore.ts`, `formatDate.ts` |
| CSS 类 | kebab-case | `.base-dialog`, `.stat-card` |
| Props | camelCase | `modelValue`, `confirmText` |
| Emits | camelCase | `update:modelValue`, `confirm` |
| Pinia stores | camelCase，后缀 `Store` | `userStore`, `datasetStore` |

### 2.5 TypeScript 规则

- 所有 `props` 必须用 `defineProps` 显式定义类型。
- 所有 `emit` 事件必须用 `defineEmits` 定义类型。
- 避免 `any`。类型不确定时使用 `unknown` + 类型守卫。
- 对象结构优先用 `interface`，联合类型 / 别名用 `type`。
- 可复用类型提取到模块目录的 `types.ts` 或 `models/` 中。

```typescript
// 好的
interface User {
  id: number;
  name: string;
  role: 'admin' | 'user' | 'guest';
}

const props = defineProps<{
  title: string;
  width?: string;
  showFooter?: boolean;
}>();

const emit = defineEmits<{
  (e: 'update:modelValue', value: boolean): void;
  (e: 'confirm'): void;
}>();
```

### 2.6 状态管理规则

| 范围 | 方案 | 示例 |
|------|------|------|
| 单个组件 | `ref`、`reactive`、`computed` | 表单输入值、本地开关、对话框可见性 |
| 父组件 + 直接子组件 | `provide` / `inject` | 深层表单数据、深层嵌套 UI 状态 |
| 跨组件 / 页面级 | Pinia store | 用户信息、应用配置、缓存数据 |
| 服务端缓存 | 请求层 + Pinia | API 响应列表、查询表 |

- **严禁**直接修改 props。使用 `emit` + `v-model` 或回调 props。
- **严禁**在组件中放置 API 响应缓存逻辑。

### 2.7 API 请求规则

- 所有 API 调用必须在 `src/request/` 中定义，不要在组件内直接写原生 axios。
- 每个请求模块按业务域组织，导出 DTO/VO 类型和请求函数。
- 统一使用 `async/await` + `try/catch` 处理加载和错误状态。

```typescript
// src/request/userRequest.ts
export interface LoginDTO {
  username: string;
  password: string;
}

export interface UserVO {
  id: number;
  username: string;
  role: string;
}

export function login(data: LoginDTO) {
  return request.post<UserVO>('/user/login', data);
}
```

错误处理示例：

```typescript
async function handleSubmit() {
  try {
    await login(formData);
    ElMessage.success('登录成功');
    router.push('/');
  } catch (error) {
    ElMessage.error('登录失败，请检查账号密码');
  }
}
```

---

## 三、UI 规则与设计系统

### 3.1 变量类别：只使用这些，禁止硬编码

编写样式时，从以下类别中选择变量，不要手写任何具体颜色、字号、间距或圆角值。

- **语义颜色**：`primary`、`success`、`warning`、`danger`、`error`、`info`，每种都有深浅变体
- **文本颜色**：`primary`、`regular`、`secondary`、`placeholder`、`disabled`
- **边框颜色**：`border`、`light`、`lighter`、`extra-light`、`dark`、`darker`
- **填充颜色**：`fill`、`light`、`lighter`、`extra-light`、`dark`、`darker`、`blank`
- **背景颜色**：`bg`、`page`、`overlay`
- **字号**：`extra-small`、`small`、`base`、`medium`、`large`、`extra-large`、`3xl`
- **字重**：`primary`（500）、`semibold`（600）、`bold`（700）
- **间距**：`3xs`、`2xs`、`xs`、`sm`、`md`、`lg`、`xl`、`2xl`、`3xl`、`4xl`
- **圆角**：`small`、`base`、`round`、`circle`
- **阴影**：`box-shadow`、`light`、`lighter`
- **过渡**：`fast`、`normal`
- **布局**：`form-control-height`、`content-padding`、`content-max-width`

### 3.2 颜色选择决策

按**含义**选择颜色，而非按外观：

| 含义 | 颜色族 |
|------|--------|
| 品牌 / 主操作 | `primary` |
| 完成 / 成功 / 正向 | `success` |
| 警告 / 需注意 | `warning` |
| 错误 / 删除 / 危险 | `danger` / `error` |
| 信息 / 链接 / 次要 | `info` |

同一颜色族内的深浅用法：

- 主色 → 主文字、按钮、浅色背景上的边框
- `light-3` → hover 状态、浅色点缀、次要边框
- `light-9` → 背景底色、标签背景、hover 背景
- `dark-2` → 按下 / 激活状态、浅色底色上的文字
- `rgb` → CSS `rgba()` 自定义透明度组合

### 3.3 间距选择决策

按**关系紧密程度**选择间距：

| Token | 关系 | 典型用途 |
|-------|------|---------|
| `3xs` | 微 | 图标与文字间隙、微调 |
| `2xs` | 紧密 | 行内元素间隙、标签内部间距 |
| `xs` | 接近 | 小按钮内边距、紧凑列表项间距 |
| `sm` | 标准小 | 表单元素间隙、按钮图标间隙 |
| `md` | 标准 | 按钮水平内边距、表单项间距、对话框内部间隙 |
| `lg` | 标准大 | 卡片内边距、区块内部间距 |
| `xl` | 宽松 | 对话框内边距、区块间距 |
| `2xl` | 页面级 | 页面区块间距、大卡片内边距 |
| `3xl` | 主要 | 主要页面模块间隙 |
| `4xl` | 主区块 | 大布局间隙、页面边缘内边距 |

决策规则：**选择不感觉拥挤的最小 Token**。不要在 Token 之间使用任意 `px` 值。

### 3.4 组件选择优先级

```
项目自定义组件 → Element Plus 组件 → 手写 HTML
```

常见场景的决策：

- 标准对话框（标题 + 底部按钮）→ `BaseDialog`
- 标准列表 / 表格 → `BaseTable`
- 标准分页（带信息文本）→ `AppPagination`
- 单指标（标签 + 数值 + 副标签）→ `StatCard`
- 二进制状态（成功 / 危险）→ `StatusTag`
- 权限展示（部门 / 个人）→ `PermissionTag`
- 设置页头部（返回导航）→ `SettingPageHeader`
- 无自定义组件覆盖 → `Element Plus`
- Element Plus 无法覆盖 → 手写 HTML + CSS + JS

### 3.5 常用工具类

不需要完整组件但想复用标准视觉模式时，直接使用这些 CSS 类：

| 类 | 效果 | 使用场景 |
|----|------|---------|
| `.bg-model-card` | 白色背景、标准内边距、圆角、浅色边框、微妙阴影 | 标准卡片容器 |
| `.main-button` | 胶囊描边按钮，主色边框和文字 | 次要操作、筛选按钮、取消操作 |
| `.main-button-primary` | 胶囊渐变填充按钮，白色文字 | 主操作、提交、确认、创建 |
| `.flex-center` | Flex 水平垂直居中 | 任何需要居中的元素 |
| `.ellipsis` | 单行文本截断 | 列表、表格中的长文本 |
| `.text-white` | 白色文字 | 彩色背景上的文字 |

### 3.6 组件级变量

全局变量是默认选择。只有在以下场景下，才允许在组件内部定义局部 CSS 变量：

- 组件有独特的内边距 / 尺寸，不适合全局间距层级。
- 组件有特有的动画时长或缓动曲线。
- 组件需要局部计算值（如 `calc(100% - var(--spacing-lg))`）。
- 复杂组件的子元素需要统一的局部 token。

命名规范：

```
--{component-name}--{property}
--{component-name}__{element}--{property}
```

示例：

```css
--base-dialog--header-padding
--stat-card__value--font-size
```

禁止用组件级变量替代语义颜色，或用它逃避全局间距规范。如果一个值在多个组件中重复出现，应提取到全局变量。

决策流程：

```
需要定义一个值？
  → 全局变量已覆盖？→ 使用全局变量
  → 仅该组件需要？→ 定义组件级变量
  → 多个组件都需要但全局没有？→ 补充到全局变量，然后使用全局变量
```

### 3.7 全局默认值（不要在组件中重复）

这些已在 `src/main.ts` 中全局设置，重复声明会导致不一致：

| 设置 | 全局值 | 不要添加 |
|------|--------|---------|
| `el-table` 斑马纹 | `true`（默认） | 任何 `el-table` 的 `stripe` 属性 |
| `el-form` 标签位置 | `"top"`（默认） | 任何 `el-form` 的 `label-position` 属性 |
| 表单控件高度 | `44px` 通过变量 | 输入框的内联高度样式 |

---

## 四、Vue SFC 模板

每个新 Vue 组件必须遵循此结构：

```vue
<template>
  <!-- 组件标记，使用 Element Plus 或自定义组件 -->
</template>

<script setup lang="ts">
// TypeScript 逻辑：导入、props、emits、状态、computed、函数、生命周期
</script>

<style lang="less" scoped>
/* 所有样式使用 CSS 变量。禁止硬编码值。 */
</style>
```

- 组件特定样式用 `<style lang="less" scoped>`。
- 仅在覆盖 Element Plus 内部样式时，才使用无 scope 的 `<style lang="less">` 块。

---

## 五、典型布局模式

一个页面往往不是单一布局，每个由标题或分割线分隔的独立业务区块都是一个独立布局。

### 5.1 列表页（表格 + 操作）

```
页面头部
  ├─ 标题 + 副标题（左侧）
  └─ 主操作按钮（右侧）
筛选栏
  ├─ 筛选输入框
  ├─ 重置按钮（次要）
  └─ 查询按钮（主要）
数据表格
  ├─ 列（适当处可排序）
  └─ 操作列（小型文字按钮）
分页
  ├─ 信息文本（左侧）
  └─ 页码按钮（右侧）
```

Token 要点：页面标题用 `font-size-large` + `font-weight-bold` + `text-color-primary`；主要区块间距用 `spacing-2xl`；表格使用 `el-table`（斑马纹已全局，不要加 `stripe`）。

### 5.2 表单页

```
页面头部
  ├─ 返回按钮（左侧）
  ├─ 标题
  └─ 副标题（可选）
表单容器
  ├─ 表单字段（标签在输入框上方）
  └─ 提交按钮
      ├─ 取消（次要）
      └─ 提交（主要）
```

Token 要点：表单容器限制最大宽度 `content-max-width`；字段间距用 `spacing-xl`；提交按钮用 `main-button-primary` 或 `el-button type="primary"`。

### 5.3 卡片网格 / 仪表盘

```
页面头部
  ├─ 标题
  └─ 操作按钮（可选）
卡片网格
  ├─ 卡片 1（.bg-model-card）
  ├─ 卡片 2（.bg-model-card）
  └─ 卡片 N（.bg-model-card）
```

响应式策略：小屏单列，中屏 2 列，大屏 3 列或更多。卡片网格间距用 `spacing-lg` 或 `spacing-xl`。

### 5.4 仪表盘 / 概览（统计 + 图表 + 列表）

```
页面标题
统计行
  ├─ 统计卡片 1（StatCard）
  ├─ 统计卡片 2
  └─ ...
内容行
  ├─ 左侧面板（图表或表格）
  └─ 右侧面板（列表或详情）
```

统计卡片使用语义颜色（`primary`、`success`、`danger`、`info`），面板容器使用 `.bg-model-card`。

### 5.5 通用布局规则

1. 主要页面区块间使用 `spacing-2xl` 或 `spacing-3xl`。
2. 标准页面内容内边距为 `content-padding`（24px）或 `spacing-2xl`。
3. 内容区域遵守 `content-max-width`（72rem），超宽时居中。
4. 背景层级：页面根节点用 `bg-color-page`，卡片 / 浮层面板用 `bg-color`，微妙区块用 `fill-color` 或 `fill-color-light`。

---

## 六、代码审查清单

审查 AI 生成或人工编写的代码时，逐条检查：

- [ ] 无硬编码 CSS 值（颜色、尺寸、间距、圆角）
- [ ] 无组件超过 300–400 行
- [ ] 无函数超过 50–60 行
- [ ] Props 和 emits 已显式类型化
- [ ] 无无正当理由的 `any` 类型
- [ ] 无 `.vue` 文件中的原生 `axios` 调用
- [ ] 未直接修改 props
- [ ] 在适用时优先使用自定义组件而非 Element Plus 等价物
- [ ] 未冗余声明全局默认值（表格斑马纹、表单标签位置）
- [ ] 可复用逻辑已提取到组合式函数或工具，未重复

---

## 七、文件结构提示

```
src/styles/variables.less          → 自定义 Design Tokens（无 --el- 前缀）
src/styles/element-plus-theme.less → Element Plus 变量覆盖（桥接层）
src/styles/legacy-variables.less   → 向后兼容别名
src/styles/components.less         → 可复用 CSS 类（.bg-model-card、.main-button）
src/styles/utilities.less          → 工具类（.ellipsis、.flex-center、.text-white）
src/components/                    → 全局可复用组件（BaseDialog、StatCard 等）
src/request/                       → API 请求模块（按业务域）
src/store/modules/                 → Pinia stores（按业务域）
src/composables/                   → 可复用 Vue 组合式逻辑
src/utils/                         → 纯工具函数
src/index.less                     → 全局样式入口
src/main.ts                        → 全局默认 props、应用启动
```

桥接层说明：自定义 Token 通过 `src/styles/element-plus-theme.less` 映射到 Element Plus 变量。项目代码中始终使用不带 `--el-` 前缀的自定义 Token，让 Element Plus 组件在不需要逐个覆盖的情况下自动匹配品牌规范。

---

## 八、写在最后

这套规范的价值不在于“约束 creativity”，而在于**把低层次的重复决策交给规则，把高层次的创造性工作留给开发者**。当颜色、间距、组件选择、目录结构都有默认答案时，团队就能把更多精力放在业务逻辑和用户体验上。

如果你在 AI Coding 场景下使用这套规范，建议把它进一步编码为 Skill 文件，通过“禁止 + 必须”的命令式语句、决策树和代码示例，让 Agent 在每次生成代码时都能自动遵循这些约定。


---

# agent-browser Skill 速查

> **类型**：笔记
> **URL**：https://nfap9.github.io/notes/agent-browser-skill/
> **分类**：工具
> **标签**：mcp, agent, browser, skill
> **发布日期**：2025-05-19
> **描述**：记录 agent-browser skill 的核心用法和常用命令


## 核心能力

`agent-browser` 是用于浏览器自动化的 MCP 工具，支持导航、点击、填表、截图、数据提取等。

## 常用命令

| 命令 | 用途 |
|------|------|
| `browser_navigate` | 导航到 URL |
| `browser_click` | 点击元素 |
| `browser_type` | 在输入框中输入文本 |
| `browser_fill_form` | 批量填写表单 |
| `browser_snapshot` | 获取页面可访问性快照（比截图更适合 agent 理解） |
| `browser_take_screenshot` | 截图 |
| `browser_evaluate` | 执行 JavaScript |

## 使用建议

- 优先使用 `browser_snapshot` 而非截图来理解页面结构
- 填表时优先用 `browser_fill_form` 批量处理
- 截图用 `browser_take_screenshot` 保存到文件，方便后续查看


---

# 从手动到自动化：前端项目 Commit 规范与 CI/CD 发布实践

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/ci-cd-practice/
> **分类**：工程化
> **标签**：cicd, git, commit, github-actions, 工程化
> **发布日期**：2025-03-28
> **描述**：面向前端团队，从零搭建代码提交规范校验与自动化发布流水线，覆盖 Husky、Conventional Commits、语义化版本管理与 GitHub Actions 全链路


> 本文面向前端团队，从零搭建一套完整的代码提交规范校验与自动化发布流水线。适合 Monorepo 和单仓库项目，覆盖 Husky、Conventional Commits、语义化版本管理与 GitHub Actions 全链路。

---

## 前言：为什么要规范化发布流程

在团队规模扩大后，代码提交和版本发布往往会变成一场"灾难"：

- **提交信息随意** —— `fix bug`、`update`、`111` 这样的提交历史让 `git log` 几乎无法阅读
- **CHANGELOG 手写** —— 每次发版都要人工整理改了什么，既耗时又容易遗漏
- **版本号混乱** —— 有人用日期版本，有人随便升 major，依赖关系一团糟
- **发布全靠手工** —— 本地 build、手动改版本、打 tag、传 npm，一步出错就要重来

这套流程的核心目标是：**让开发者只关注代码，把重复且易出错的机械操作交给机器**。

我们将构建一条从代码提交到 npm 发布的完整自动化链路：

```
代码提交 → 规范校验 → CI 测试 → 版本选择 → CHANGELOG 生成 → Git 标签 → npm 发布 → GitHub Release
```

---

## 一、Commit Message 规范与校验

### 1.1 为什么选择 Conventional Commits

[Conventional Commits](https://www.conventionalcommits.org/) 是目前业界广泛采用的提交规范。它不仅能让提交历史清晰可读，更重要的是**可以被工具解析**，自动生成 CHANGELOG 和确定版本号。

一条规范的提交信息长这样：

```
feat(compiler): add template optimization for v-if
```

格式分解：`type(scope): subject`

| 字段 | 说明 | 示例 |
|------|------|------|
| `type` | 提交类型（必填） | feat, fix, docs... |
| `scope` | 影响范围（可选） | compiler, api, docs |
| `subject` | 简短描述（必填） | add template optimization |

### 1.2 完整的类型定义

不同团队对类型的划分略有差异，建议从以下 13 种类型中选择，避免过度设计：

| 类型 | 含义 | 是否生成 CHANGELOG | 版本号变化 |
|------|------|:------------------:|-----------|
| `feat` | 新功能 | ✅ 是 | minor +1 |
| `fix` | 修复 Bug | ✅ 是 | patch +1 |
| `perf` | 性能优化 | ✅ 是 | patch +1 |
| `refactor` | 重构（不影响功能） | ❌ 否 | — |
| `docs` | 文档变更 | ❌ 否 | — |
| `style` | 代码格式（空格、分号等） | ❌ 否 | — |
| `test` | 补充或修改测试 | ❌ 否 | — |
| `chore` | 构建工具、依赖更新 | ❌ 否 | — |
| `ci` | CI/CD 配置变更 | ❌ 否 | — |
| `build` | 构建脚本变更 | ❌ 否 | — |
| `dx` | 开发者体验改进 | ❌ 否 | — |
| `types` | 类型定义变更 | ❌ 否 | — |
| `wip` | 工作中（临时提交） | ❌ 否 | — |

> 💡 **建议**：团队刚开始推行时，可以先只要求 `feat` 和 `fix` 出现在 CHANGELOG 中，降低上手门槛。

### 1.3 用 Husky 拦截不规范提交

光有规范还不够，必须通过工具强制执行。[Husky](https://typicode.github.io/husky/) 是 Git hooks 的管理工具，可以在提交前自动校验。

#### 安装与配置

```bash
# 安装 husky（v9 语法）
npm install -D husky
npx husky init

# 添加 commit-msg hook
echo 'node scripts/verify-commit.js' > .husky/commit-msg
```

> ⚠️ **注意版本差异**：Husky v9+ 的初始化语法发生了变化。如果你使用的是 v8，命令是 `npx husky install && npx husky add .husky/commit-msg 'node scripts/verify-commit.js'`。建议直接升级到 v9，配置更简洁。

#### 校验脚本实现

创建 `scripts/verify-commit.js`：

```javascript
const fs = require('fs')
const path = require('path')

// 读取 Git 临时文件中的提交信息
const msgPath = path.resolve('.git/COMMIT_EDITMSG')
const msg = fs.readFileSync(msgPath, 'utf-8').trim()

// 匹配规则：可选 revert: 前缀 + type(可选scope) + : + 1-50字符描述
const commitRE = /^(revert: )?(feat|fix|docs|dx|style|refactor|perf|test|workflow|build|ci|chore|types|wip)(\(.+\))?: .{1,50}/

if (!commitRE.test(msg)) {
  console.error('\n❌ Invalid commit message format.\n')
  console.error('Expected format: type(scope): subject')
  console.error('Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, types, wip')
  console.error('\nExamples:')
  console.error('  feat(compiler): add template optimization')
  console.error('  fix(v-model): handle blur event correctly')
  console.error('  docs: update installation guide\n')
  process.exit(1)
}
```

关键设计说明：

- **读取 `.git/COMMIT_EDITMSG`** —— Git 在提交时会将消息写入这个临时文件，hook 从中读取
- **支持 `revert:` 前缀** —— 回滚操作需要特殊处理，避免误判为不规范
- **限制 subject 长度 50 字符** —— 保证 `git log --oneline` 的可读性
- **失败时输出帮助信息** —— 不要只抛错误，告诉开发者正确的格式是什么

---

## 二、自动化版本管理与发布

### 2.1 语义化版本（SemVer）策略

版本号格式为 `MAJOR.MINOR.PATCH`，增量规则如下：

| 场景 | 版本变化 | 示例 | 触发方式 |
|------|---------|------|---------|
| 修复 Bug | patch +1 | `1.2.0` → `1.2.1` | `fix:` 提交 |
| 新增功能 | minor +1 | `1.2.0` → `1.3.0` | `feat:` 提交 |
| 破坏性变更 | major +1 | `1.2.0` → `2.0.0` | `BREAKING CHANGE` 声明 |
| 手动指定 | 自定义 | 任意版本 | 交互式选择 |

**如何声明破坏性变更**（在提交信息 footer 中）：

```
fix(api): remove deprecated /old/endpoint

BREAKING CHANGE: The /old/endpoint has been removed.
Please migrate to /v2/endpoint before upgrading.
```

### 2.2 交互式发布脚本

下面是一个完整的 `release.js` 实现，包含版本选择、CHANGELOG 生成和 Git 操作：

```javascript
// scripts/release.js
const { prompt } = require('enquirer')
const semver = require('semver')
const { execSync } = require('child_process')
const fs = require('fs')
const path = require('path')

async function main() {
  // 读取当前版本
  const pkgPath = path.resolve('package.json')
  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
  const currentVersion = pkg.version

  console.log(`Current version: ${currentVersion}\n`)

  // 交互式选择版本类型
  const versionIncrements = ['patch', 'minor', 'major']
  const { release } = await prompt({
    type: 'select',
    name: 'release',
    message: 'Select release type',
    choices: versionIncrements.map(i => {
      const nextVer = semver.inc(currentVersion, i)
      return { name: `${i} (${nextVer})`, value: i }
    })
  })

  // 提取版本类型（从选择中解析）
  const releaseType = release.match(/^(\w+)/)[1]
  const targetVersion = semver.inc(currentVersion, releaseType)

  // 确认发布
  const { confirm } = await prompt({
    type: 'confirm',
    name: 'confirm',
    message: `Releasing v${targetVersion}. Confirm?`,
    initial: true
  })

  if (!confirm) {
    console.log('Cancelled.')
    process.exit(0)
  }

  // ========== 发布流程 ==========

  // 1. 更新版本号
  updatePackageVersion(targetVersion)
  console.log(`✅ Version updated to ${targetVersion}`)

  // 2. 生成 CHANGELOG
  execSync('pnpm run changelog', { stdio: 'inherit' })
  console.log('✅ CHANGELOG generated')

  // 3. 提交版本变更
  execSync(
    `git add -A && git commit -m "release: v${targetVersion}"`,
    { stdio: 'inherit' }
  )
  console.log('✅ Version commit created')

  // 4. 打 Git 标签
  execSync(`git tag v${targetVersion}`)
  console.log(`✅ Tag v${targetVersion} created`)

  // 5. 推送代码和标签（触发 CI/CD）
  console.log('🚀 Pushing to remote...')
  execSync('git push && git push --tags', { stdio: 'inherit' })

  console.log(`\n🎉 Release v${targetVersion} is on its way!`)
}

/**
 * 更新 package.json 版本号
 * 如果是 Monorepo，需要同步更新所有子包的版本
 */
function updatePackageVersion(version) {
  // 更新根 package.json
  const rootPkgPath = path.resolve('package.json')
  const rootPkg = JSON.parse(fs.readFileSync(rootPkgPath, 'utf-8'))
  rootPkg.version = version
  fs.writeFileSync(rootPkgPath, JSON.stringify(rootPkg, null, 2) + '\n')

  // Monorepo 场景：同步更新 packages/* 下的所有子包
  const packagesDir = path.resolve('packages')
  if (fs.existsSync(packagesDir)) {
    const packages = fs.readdirSync(packagesDir)
    for (const dir of packages) {
      const pkgPath = path.join(packagesDir, dir, 'package.json')
      if (!fs.existsSync(pkgPath)) continue

      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
      pkg.version = version

      // 同时更新子包之间的相互引用
      updateInternalDeps(pkg, version)

      fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
    }
  }
}

/**
 * 更新子包之间的内部依赖版本
 * 例如 packages/a 依赖 packages/b，需要同步版本号
 */
function updateInternalDeps(pkg, version) {
  const depTypes = ['dependencies', 'devDependencies', 'peerDependencies']
  for (const depType of depTypes) {
    const deps = pkg[depType]
    if (!deps) continue

    // 假设内部包都以 @scope/ 开头
    for (const depName of Object.keys(deps)) {
      if (deps[depName].startsWith('workspace:') || deps[depName].startsWith('^0.0.0')) {
        deps[depName] = '^' + version
      }
    }
  }
}

main().catch(err => {
  console.error(err)
  process.exit(1)
})
```

### 2.3 package.json 脚本配置

```json
{
  "scripts": {
    "release": "node scripts/release.js",
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
  },
  "devDependencies": {
    "husky": "^9.0.0",
    "conventional-changelog-cli": "^4.0.0",
    "enquirer": "^2.4.0",
    "semver": "^7.6.0"
  }
}
```

---

## 三、GitHub Actions 自动化流水线

### 3.1 CI 工作流：持续集成

每次 push 或 PR 时自动运行测试，确保代码质量。

```yaml
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: ['**']      # 所有分支的 push
  pull_request:
    branches: [main]      # 针对 main 分支的 PR

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true    # 同一分支的新提交取消旧任务

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 9

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: '.node-version'    # 从文件读取版本，统一管理
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile    # 锁定依赖版本，保证一致性

      - name: Lint
        run: pnpm lint

      - name: Build
        run: pnpm build

      - name: Test
        run: pnpm test
```

**关键设计点**：

- **`--frozen-lockfile`** —— CI 环境必须锁定依赖版本，避免锁文件不一致导致的构建问题
- **`concurrency` 配置** —— 快速迭代时避免队列堆积，节省 CI 分钟数
- **`.node-version` 文件** —— 将 Node 版本纳入版本控制，团队开发环境保持一致

### 3.2 Release 工作流：自动发布

当发布脚本推送 tag 后，自动执行构建、发布到 npm、创建 GitHub Release。

```yaml
# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'     # 只匹配 v 开头的标签，如 v1.2.0

permissions:
  contents: write    # 创建 GitHub Release 需要写入权限

jobs:
  # 第一步：运行完整测试，确保发布质量
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version-file: '.node-version'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm test

  # 第二步：发布到 npm 并创建 GitHub Release
  publish:
    needs: [test]              # 测试通过后才执行
    runs-on: ubuntu-latest
    environment: Release       # 可配置审批流（如需要人工确认）
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0       # 获取完整历史，CHANGELOG 生成需要

      - uses: pnpm/action-setup@v2
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version-file: '.node-version'
          registry-url: 'https://registry.npmjs.org'
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile
      - run: pnpm build

      - name: Publish to npm
        run: pnpm publish --no-git-checks
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Create GitHub Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref_name }}
          release_name: ${{ github.ref_name }}
          body: |
            See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details.
```

**关键设计点**：

- **`needs: [test]`** —— 发布强依赖测试通过，防止有问题的代码流入生产
- **`environment: Release`** —— GitHub Environments 支持设置审批人和保护规则，适合需要人工确认的发布流程
- **`permissions: contents: write`** —— `actions/create-release` 需要写入仓库内容的权限，显式声明更安全
- **`fetch-depth: 0`** —— `conventional-changelog` 需要完整的 Git 历史来生成 CHANGELOG

---

## 四、完整工作流图解

以下是开发者从编码到发布的完整操作链路：

```
┌──────────┐     git commit      ┌──────────────┐
│          │ ──────────────────> │              │
│ 开发者   │                     │  commit-msg  │
│          │ <────────────────── │   hook 校验   │
│          │      ✓ 通过         │              │
└──────────┘                     └──────────────┘
     │                                  │
     │         git push                 │
     │ ─────────────────────────────────────────>
     │                              ┌──────────────┐
     │                              │  GitHub CI   │
     │                              │  lint/test   │
     │                              │   build      │
     │ <────────────────────────────────────────── │
     │                                   ✓ 通过    │
     │                              └──────────────┘
     │         pnpm release
     │         1. 选择版本类型
     │         2. 更新版本号
     │         3. 生成 CHANGELOG
     │         4. git commit "release: v1.2.0"
     │         5. git tag v1.2.0
     │         6. git push --tags
     │ ─────────────────────────────────────────>
     │                              ┌──────────────┐
     │                              │ Release 流程  │
     │                              │ test → build │
     │                              │ → publish    │
     │                              │ → GitHub Rel │
     │ <────────────────────────────────────────── │
     │                                   ✅ 完成    │
                                  └──────────────┘
```

---

## 五、快速上手指南

### 5.1 初始化步骤

```bash
# 1. 安装依赖
pnpm add -D husky conventional-changelog-cli enquirer semver

# 2. 初始化 Husky（v9）
npx husky init

# 3. 创建 commit-msg hook
echo 'node scripts/verify-commit.js' > .husky/commit-msg

# 4. 将 verify-commit.js 和 release.js 复制到 scripts/ 目录
#    （参考上方完整代码）

# 5. 在 package.json 中添加 scripts
#    "release": "node scripts/release.js"
#    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"

# 6. 创建 .github/workflows/ 下的 CI 和 Release workflow 文件
```

### 5.2 日常开发流程

```bash
# 正常开发提交（自动校验）
git commit -m "feat(compiler): add template optimization for v-if"

# 推送触发 CI
git push

# 准备发布（交互式选择版本）
pnpm release
# ? Select release type
#   patch (1.2.1)
#   minor (1.3.0)
#   major (2.0.0)
# ? Releasing v1.3.0. Confirm? Yes
```

---

## 六、常见问题与踩坑记录

### Q1: Husky hook 不生效，提交没有触发校验

```bash
# 检查 hook 是否已注册
cat .git/hooks/commit-msg

# 确保 Husky 已初始化
npx husky init

# 旧版本升级后可能需要重新安装
git config core.hooksPath .husky
```

### Q2: CI 中 pnpm install 失败，提示 lockfile 不匹配

CI 环境必须使用 `--frozen-lockfile`，确保 lock 文件与 package.json 一致：

```bash
# 本地更新 lock 文件后重新提交
pnpm install

# 如果确实需要更新
pnpm install --no-frozen-lockfile
```

### Q3: GitHub Actions 创建 Release 失败（403 错误）

检查 workflow 是否声明了正确的权限：

```yaml
permissions:
  contents: write    # 必须有这一行
```

或者在仓库 Settings → Actions → General → Workflow permissions 中选择 "Read and write permissions"。

### Q4: 发布到 npm 时 401 Unauthorized

需要配置 `NPM_TOKEN` secret：

1. 在 [npm](https://www.npmjs.com/) 生成 Access Token（选择 "Automation" 类型）
2. 在 GitHub 仓库 Settings → Secrets and variables → Actions 中添加 `NPM_TOKEN`
3. 确认 workflow 中设置了 `registry-url` 和 `NODE_AUTH_TOKEN`

### Q5: CHANGELOG 生成不完整

`conventional-changelog` 依赖 tag 来计算变更范围。确保：

1. 本地有完整的 Git 历史（`git fetch --tags`）
2. CI 中 checkout 使用 `fetch-depth: 0`
3. 已存在至少一个 `v*` 格式的 tag 作为基准

---

## 七、总结

本文搭建了一套完整的自动化发布体系，核心链路可以概括为：

| 环节 | 工具/方案 | 解决的问题 |
|------|----------|-----------|
| 提交校验 | Husky + verify-commit.js | 强制规范提交信息 |
| 版本管理 | semver + 交互式脚本 | 语义化版本，避免人为错误 |
| CHANGELOG | conventional-changelog | 自动生成，不再手写 |
| CI 测试 | GitHub Actions | 每次提交自动验证 |
| 自动发布 | GitHub Actions + npm | tag 推送后全自动发布 |

这套流程的优势在于：

- **开发者体验好** —— 提交时即时反馈，发布时一键完成
- **可追溯性强** —— 每个版本都有清晰的提交历史和变更记录
- **错误率低** —— 机械操作交给机器，减少人为失误
- **团队对齐** —— 统一的规范让协作更顺畅

建议团队在实际落地时，可以先从 **Commit 规范** 和 **CI 测试** 开始，这是投入产出比最高的两个环节。等团队适应后再逐步引入自动发布流程。

---

## 参考与延伸阅读

- [Conventional Commits 规范](https://www.conventionalcommits.org/)
- [Semantic Versioning 语义化版本](https://semver.org/)
- [Husky 官方文档](https://typicode.github.io/husky/)
- [GitHub Actions 文档](https://docs.github.com/en/actions)
- [conventional-changelog 配置](https://github.com/conventional-changelog/conventional-changelog)


---

# Vue 源码中的工程化设计：五个可复用的团队开发范式

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/vue-engineering-patterns/
> **分类**：Vue
> **标签**：vue, 工程化, 源码, 架构, 团队开发
> **发布日期**：2025-03-28
> **描述**：从 Vue 源码中提炼五个可落地的工程化设计范式，覆盖架构分层、条件编译、测试策略、代码规范与发布自动化


> 本文从 Vue 源码的工程实践中提炼出五个可落地的设计范式，覆盖架构分层、条件编译、测试策略、代码规范与发布自动化。适合前端团队负责人和架构师参考，将 Vue 验证过的工程化思想迁移到自己的项目中。

---

## 一、分层架构与依赖治理

**核心思想：用物理边界约束架构，防止代码腐化。**

Vue 源码的包结构是工程化设计的典范。编译器（`@vue/compiler-core`）和运行时（`@vue/runtime-core`）是两个独立的包，二者互不直接引用，只通过共享的 `@vue/shared` 进行通信。这种单向依赖图确保了架构的清晰性。

### Vue 的依赖治理实践

| 实践 | 具体做法 | 可借鉴点 |
|------|---------|---------|
| 单向依赖图 | 编译器 → 共享包 ← 运行时，二者互不引用 | 同层级模块禁止互相依赖 |
| 共享包收敛 | 所有跨包工具收敛到 `@vue/shared` | 提取公共依赖，避免重复和循环引用 |
| 私有包隔离 | `packages-private/` 目录物理隔离 | 防止内部工具被误发布到 npm |

### 前端项目三层划分建议

基于 Vue 的设计思想，前端项目可以按以下三层组织：

```
┌─────────────────────────────────────┐
│     视图层 (UI Layer)               │  页面组件、通用组件库
├─────────────────────────────────────┤
│     业务层 (Business Layer)          │  状态管理、业务逻辑、hooks
├─────────────────────────────────────┤
│     基础层 (Infrastructure Layer)    │  工具函数、API 封装、类型定义、常量
└─────────────────────────────────────────────────────────────┘
         依赖方向：上层可引用下层，下层禁止引用上层
```

**依赖规则**：

- ✅ 视图层 → 业务层、基础层
- ✅ 业务层 → 基础层
- ❌ 禁止同层级相互引用（如业务模块 A 引用业务模块 B）
- ❌ 禁止反向依赖（如基础层引用业务层）

### 用 ESLint 强制约束依赖方向

安装插件：

```bash
pnpm add -D eslint-plugin-import
```

配置 `.eslintrc.cjs`：

```js
module.exports = {
  rules: {
    'import/no-restricted-paths': ['error', {
      zones: [
        // 规则1：基础层（utils）禁止引用业务层
        {
          target: 'src/utils',
          from: 'src/business',
          message: '基础设施层禁止依赖业务层',
        },
        // 规则2：基础层禁止引用视图层
        {
          target: 'src/utils',
          from: 'src/views',
          message: '基础设施层禁止依赖视图层',
        },
        // 规则3：业务层禁止引用视图层
        {
          target: 'src/business',
          from: 'src/views',
          message: '业务层禁止依赖视图层',
        },
        // 规则4：同层级业务模块间禁止互相引用
        {
          target: 'src/business/module-a',
          from: 'src/business/module-b',
          message: '同层级业务模块禁止互相依赖，公共逻辑应下沉到 utils',
        },
      ],
    }],
  },
};
```

> 💡 **如何落地**：先配置规则为 `warn` 级别，让团队有时间重构现有代码，清理完毕后再切换为 `error`。

### Monorepo 依赖治理进阶

在 Monorepo 场景下，依赖治理需要额外关注三个问题：

**1. 共享包版本同步**

```json
// packages/shared/package.json
{
  "name": "@my-org/shared",
  "version": "1.2.0"
}

// packages/app/package.json
{
  "dependencies": {
    "@my-org/shared": "workspace:^"
  }
}
```

使用 pnpm workspace 协议（`workspace:^`），发布时自动替换为实际版本号，避免手动同步。

**2. 循环依赖检测**

```bash
# 使用 madge 检测循环依赖
npx madge --circular src/
```

发现循环依赖后，将公共部分提取到 `shared` 包中打破循环。

**3. 共享包内容取舍原则**

- **应该进 shared**：纯工具函数（`isObject`、`capitalize`）、类型定义、通用常量
- **不应该进 shared**：业务逻辑、组件实现、框架特定的封装
- **判断标准**：如果删除该函数会影响多个包的正常运行，它就应该在 shared 中

---

## 二、条件编译与环境标志

**核心思想：在构建时消除不需要的代码，不让调试代码和平台特定逻辑进入生产包。**

Vue 大量使用全局标志（`__DEV__`、`__SSR__`、`__TEST__`）控制代码分支。这些标志不是普通的运行时变量，而是在构建阶段通过 esbuild 的 `define` 功能直接替换为布尔值。条件分支在打包后会被 Tree Shaking 彻底移除。

### Vue 的条件编译实现

```js
// 源码中的写法
if (__DEV__) {
  console.warn('Invalid vnode type');
  checkComponentName(validName);
}

// 生产环境构建后，整块代码被直接移除
// （相当于这一段从未存在过）
```

Vue 的 `rollup.config.js` 中通过 `define` 配置实现替换：

```js
// rollup.config.js
const esbuildPlugin = esbuild({
  define: {
    __DEV__: JSON.stringify(!isProduction),
    __SSR__: JSON.stringify(target === 'node'),
    __TEST__: 'false',
  },
});
```

### 前端项目实践

**1. Vite 中配置构建时环境变量**

```ts
// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig(({ mode }) => ({
  define: {
    // 构建时直接替换，不是运行时 process.env 读取
    __DEV__: JSON.stringify(mode === 'development'),
    __MOCK__: JSON.stringify(mode === 'development' || mode === 'staging'),
  },
}));
```

在代码中使用：

```ts
// types/global.d.ts 中先声明全局变量
declare const __DEV__: boolean;
declare const __MOCK__: boolean;

// 业务代码中使用
if (__DEV__) {
  console.log('[Debug] Current user:', user);
  setupDevTools();
}

if (__MOCK__) {
  import('./mock').then(({ setupMock }) => setupMock());
}
```

**2. .env 文件管理环境差异**

```bash
# .env.development
VITE_API_BASE_URL=http://localhost:3000
VITE_UPLOAD_ENDPOINT=http://localhost:3000/upload

# .env.production
VITE_API_BASE_URL=https://api.example.com
VITE_UPLOAD_ENDPOINT=https://cdn.example.com/upload
```

> ⚠️ **关键区别**：`define` 中的变量在构建时被替换（代码会直接消失），而 `import.meta.env` 中的变量是运行时读取的字符串。调试代码和开发期工具应该用 `define`，API 地址等运行时配置用 `.env`。

**3. 验证产物是否干净**

```bash
# 构建后搜索残留的开发代码
grep -n "console.log\|console.warn" dist/assets/*.js

# 或使用 rollup-plugin-visualizer 分析产物组成
npx vite-bundle-visualizer
```

理想的构建产物中，`__DEV__` 包裹的代码块应该完全消失，不占任何体积。

---

## 三、平台无关的测试策略

**核心思想：测试粒度与运行时环境解耦，能用 Node 跑的测试绝不走浏览器。**

### Vue 的三层测试架构

| 层级 | 运行环境 | 测试范围 | 执行速度 | 占比建议 |
|------|---------|---------|---------|---------|
| 单元测试 | Node (纯 JS) | 逻辑、算法、编译器输出 | ⚡ 极快（毫秒级） | ~70% |
| 组件测试 | jsdom | DOM 操作、事件处理、组件交互 | 🔄 中等（秒级） | ~20% |
| E2E 测试 | Puppeteer / Playwright | 真实浏览器行为、跨页面流程 | 🐢 较慢（分钟级） | ~10% |

Vue 最巧妙的设计是 `runtime-test` 包——用纯 JavaScript 对象模拟 DOM，让 VDOM 的 `mount`、`patch` 等核心逻辑在 Node 环境中即可完成测试，完全不依赖 jsdom 或浏览器。

### runtime-test 的核心原理

```ts
// 用普通 JS 对象模拟 DOM 节点
interface TestElement {
  nodeType: number;
  tagName: string;
  props: Record<string, any>;
  children: TestNode[];
  parentNode: TestNode | null;
  eventListeners: Record<string, Function[]>;
}

function createElement(tag: string): TestElement {
  return {
    nodeType: 1,
    tagName: tag.toUpperCase(),
    props: {},
    children: [],
    parentNode: null,
    eventListeners: {},
  };
}

function patchVNode(oldVNode: TestNode, newVNode: TestNode) {
  // VDOM diff 逻辑：完全在纯 JS 环境中执行
  // 不涉及任何浏览器 API
}
```

借助这个模拟层，Vue 的 VDOM 测试可以在 **毫秒级** 完成，而不需要启动 jsdom。

### 前端项目实践

**1. Vitest 统一测试框架配置**

```ts
// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'jsdom',      // 组件测试默认用 jsdom
    globals: true,             // 无需手动导入 describe/it
    coverage: {
      reporter: ['text', 'json', 'html'],
      thresholds: {
        lines: 80,
        functions: 80,
        branches: 70,
        statements: 80,
      },
    },
  },
});
```

**2. 分层测试代码示例**

纯逻辑测试（Node 环境，最快）：

```ts
// composables/usePagination.spec.ts
import { describe, it, expect } from 'vitest';
import { usePagination } from './usePagination';

describe('usePagination', () => {
  it('should calculate correct page range', () => {
    const { pageRange } = usePagination({
      total: 100,
      pageSize: 10,
      currentPage: 5,
    });

    expect(pageRange.value).toEqual([3, 4, 5, 6, 7]);
  });

  it('should handle edge case: total is 0', () => {
    const { totalPages } = usePagination({
      total: 0,
      pageSize: 10,
      currentPage: 1,
    });

    expect(totalPages.value).toBe(0);
  });
});
```

组件测试（jsdom，测试 DOM 交互）：

```ts
// components/Pagination.spec.ts
import { describe, it, expect } from 'vitest';
import { mount } from '@vue/test-utils';
import Pagination from './Pagination.vue';

describe('Pagination.vue', () => {
  it('should emit page-change event when clicking page number', async () => {
    const wrapper = mount(Pagination, {
      props: { total: 100, pageSize: 10, modelValue: 1 },
    });

    await wrapper.find('[data-testid="page-3"]').trigger('click');

    expect(wrapper.emitted('update:modelValue')).toBeTruthy();
    expect(wrapper.emitted('update:modelValue')[0]).toEqual([3]);
  });

  it('should disable prev button on first page', () => {
    const wrapper = mount(Pagination, {
      props: { total: 100, pageSize: 10, modelValue: 1 },
    });

    const prevButton = wrapper.find('[data-testid="prev-btn"]');
    expect(prevButton.attributes('disabled')).toBeDefined();
  });
});
```

**3. CI 中分层执行策略**

```yaml
# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  # PR 阶段只跑单元测试（最快，2-3 分钟）
  unit-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: pnpm install
      - run: pnpm test:unit        # 只跑 Node 环境的测试

  # 合并到 main 后跑全量测试
  full-test:
    if: github.ref == 'refs/heads/main'
    needs: unit-test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: pnpm install
      - run: pnpm test:unit
      - run: pnpm test:component   # jsdom 测试
      - run: pnpm test:e2e         # Playwright 测试
```

> 💡 **关键原则**：
> - **测试下沉**：能用 Node 就不走 jsdom，能走 jsdom 就不开浏览器
> - **80/20 法则**：80% 的测试应该是单元测试，它们运行快、定位准
> - **给测试加 `data-testid`**：不要用 class 或文本来定位元素，避免样式重构导致测试失败

---

## 四、代码规范的三层防护

**核心思想：规范不是写在文档里的建议，而是焊死在工具链里的强制约束。**

Vue 的 ESLint 配置是编译时的硬约束，不是可忽略的建议。这套思路推广到前端项目中，可以构建三层防护体系。

### 三层防护链路

```
第一层：编辑器实时提示  →  第二层：提交前自动修复  →  第三层：CI 红线拦截
    （最快反馈）              （兜底机制）               （最终防线）
```

### 第一层：编辑器实时提示

VSCode 配置 `.vscode/settings.json`：

```json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": ["javascript", "typescript", "vue"]
}
```

### 第二层：pre-commit Hook

安装依赖：

```bash
pnpm add -D husky lint-staged

# Husky v9 初始化
npx husky init
```

配置 `package.json`：

```json
{
  "lint-staged": {
    "*.{ts,vue}": ["eslint --fix"],
    "*.{css,scss}": ["stylelint --fix"],
    "*": ["prettier --write --ignore-unknown"]
  }
}
```

> ⚠️ **注意**：lint-staged v10+ 会自动处理 `git add`，不需要在配置中手动添加。

创建 hook：

```bash
# Husky v9 语法
echo 'npx lint-staged' > .husky/pre-commit
```

### 第三层：CI 强制检查

```yaml
# .github/workflows/lint.yml
name: Code Quality

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm type-check    # 同时跑 TypeScript 类型检查
```

### 构建时强制拦截

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import eslint from 'vite-plugin-eslint2';

export default defineConfig({
  plugins: [
    eslint({
      lintOnStart: true,        // 启动时检查
      failOnWarning: true,      // ⚠️ Warning 也会中断构建
    }),
  ],
});
```

> 💡 **建议**：本地开发时 `failOnWarning` 可以设为 `false`，但在 CI 构建脚本中通过 `ESLINT_FAIL_ON_WARNING=true pnpm build` 强制开启。

---

## 五、Commit 规范与发布自动化

**核心思想：让提交信息成为可解析的数据源，驱动 CHANGELOG 生成和版本管理。**

### Commit 规范格式

采用 Angular Commit Convention：

```
type(scope): subject

[可选的 body]

[可选的 footer]
```

示例：

```
feat(compiler): add template optimization for v-if

The compiler now generates optimized code for v-if
blocks with single static children.

Closes #123
```

### 用 Husky 拦截不规范提交

```js
// scripts/verify-commit.js
const fs = require('fs');
const path = require('path');

const msgPath = path.resolve('.git/COMMIT_EDITMSG');
const msg = fs.readFileSync(msgPath, 'utf-8').trim();

const commitRE = /^(revert: )?(feat|fix|docs|dx|style|refactor|perf|test|workflow|build|ci|chore|types|wip)(\(.+\))?: .{1,50}/;

if (!commitRE.test(msg)) {
  console.error('\n  ❌ Invalid commit message format.\n');
  console.error('  Expected format: type(scope): subject\n');
  console.error('  Valid types:');
  console.error('    feat     → New feature (triggers minor version)');
  console.error('    fix      → Bug fix (triggers patch version)');
  console.error('    refactor → Code change that neither fixes a bug nor adds a feature');
  console.error('    docs     → Documentation changes');
  console.error('    test     → Adding or correcting tests');
  console.error('    chore    → Build tools and dependency changes\n');
  console.error('  Examples:');
  console.error('    feat(compiler): add template optimization');
  console.error('    fix(v-model): handle blur event correctly');
  console.error('    docs: update installation guide\n');
  process.exit(1);
}
```

配置 hook：

```bash
# Husky v9
echo 'node scripts/verify-commit.js' > .husky/commit-msg
```

### 语义化版本映射

| 提交类型 | 版本变化 | 示例 |
|---------|---------|------|
| `feat(xxx):` | minor +1 | `1.2.0` → `1.3.0` |
| `fix(xxx):` | patch +1 | `1.2.0` → `1.2.1` |
| `BREAKING CHANGE:` in footer | major +1 | `1.2.0` → `2.0.0` |
| 手动指定 | 任意版本 | 交互式选择 |

**声明破坏性变更**：

```
fix(api): remove deprecated /old/endpoint

BREAKING CHANGE: The /old/endpoint has been removed.
Please migrate to /v2/endpoint before upgrading.
```

### 自动化发布流水线

```js
// scripts/release.js
const { prompt } = require('enquirer');
const semver = require('semver');
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');

async function main() {
  const pkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
  const current = pkg.version;
  const increments = ['patch', 'minor', 'major'];

  const { release } = await prompt({
    type: 'select',
    name: 'release',
    message: `Current: v${current}. Select release type:`,
    choices: increments.map(i => ({
      name: `${i} (${semver.inc(current, i)})`,
      value: i,
    })),
  });

  const type = release.match(/^(\w+)/)[1];
  const target = semver.inc(current, type);

  const { confirm } = await prompt({
    type: 'confirm',
    name: 'confirm',
    message: `Release v${target}?`,
    initial: true,
  });

  if (!confirm) {
    console.log('Cancelled.');
    process.exit(0);
  }

  // 更新版本号
  pkg.version = target;
  fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');

  // 生成 CHANGELOG
  execSync('pnpm changelog', { stdio: 'inherit' });

  // Git 提交、打标签、推送
  execSync(`git add -A && git commit -m "release: v${target}"`, { stdio: 'inherit' });
  execSync(`git tag v${target}`);
  execSync('git push && git push --tags', { stdio: 'inherit' });

  console.log(`\n🎉 v${target} released!`);
}

main().catch(err => {
  console.error(err);
  process.exit(1);
});
```

`package.json` 配置：

```json
{
  "scripts": {
    "release": "node scripts/release.js",
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
  }
}
```

### GitHub Actions 自动发布

```yaml
# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm build
      - run: pnpm test

  publish:
    needs: [test]
    runs-on: ubuntu-latest
    environment: Release
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0    # CHANGELOG 生成需要完整历史
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          registry-url: 'https://registry.npmjs.org'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm publish --no-git-checks
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      - name: Create GitHub Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref_name }}
          release_name: ${{ github.ref_name }}
          body: |
            See [CHANGELOG.md](./CHANGELOG.md) for details.
```

---

## 总结：在自己项目中最值得优先落地的 3 件事

| 优先级 | 事项 | 投入 | 收益 |
|-------|------|------|------|
| 🥇 P0 | **依赖方向约束** | 低（ESLint 规则） | 极高（防止架构腐化） |
| 🥈 P1 | **测试分层** | 中（配置 + 补测试） | 高（缩短反馈循环） |
| 🥉 P2 | **规范自动化** | 低（ Husky + CI） | 高（减少人为失误） |

### 1. 画好"依赖地图"

用 `import/no-restricted-paths` 明确每个目录的职责和依赖方向。这是防止代码腐化最有效、成本最低的手段。

### 2. 测试分层守护

单元测试（Node）→ 组件测试（jsdom）→ E2E（浏览器），按速度由快到慢、覆盖范围由小到大递进。CI 中按分支策略分层执行，PR 阶段只跑单元测试，合并后跑全量。

### 3. 规范焊死在工具链

能自动化的不要靠人记，能编译时拦截的不要留到运行时。Commit 规范 + CHANGELOG 自动生成 + 语义化版本，让发布变成一条命令的事。

---

## 参考与延伸阅读

- [Vue 源码仓库](https://github.com/vuejs/core) —— 工程化设计的最佳教材
- [Conventional Commits 规范](https://www.conventionalcommits.org/)
- [Semantic Versioning](https://semver.org/)
- [Vitest 文档](https://vitest.dev/)
- [pnpm Workspace 协议](https://pnpm.io/workspaces)


---

# Vue3 虚拟 DOM 与 Diff 算法

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/vue3-vdom-diff/
> **分类**：Vue
> **标签**：vue3, 虚拟DOM, diff, 源码, 渲染器
> **发布日期**：2025-03-28
> **描述**：深入 Vue3 源码，解析虚拟 DOM 的实现机制与核心 Diff 算法的执行流程


Vue3 中虚拟 DOM 的实现在 `runtime-core/src/renderer.ts` 文件中。其中包含虚拟 DOM 更新流程和核心的 Diff 算法。

`renderer.ts` 中的关键实现是 `baseCreateRenderer`，`baseCreateRenderer` 返回 `render`、`hydrate`（SSR 相关）、`createApp`。

`createApp` 中可以看到常用的方法：`use`、`mixin`、`component`、`directive`、`mount`、`onUnmount`、`unmount`、`provide`。这些都非常熟悉不再赘述。

`baseCreateRenderer` 中最核心的是 **Patch** 方法。我们从这个方法可以了解到整个虚拟DOM挂载和更新的流程；

---

## 一、Patch 递归

**Patch 方法是 Diff 算法入口**，通过递归对 VNode "打补丁" 更新 DOM。`patch` 会接受新旧节点，判断两个 VNode 的关系并执行相应操作：

1. **相同节点**（`n1 === n2`）→ 直接返回
2. **类型不同** → 卸载旧树，挂载新树
3. **按 `type` 分发处理**：

| type | 处理函数 | 说明 |
|------|---------|------|
| `Text` | `processText` | 文本节点 |
| `Comment` | `processCommentNode` | 注释节点 |
| `Static` | `mountStaticNode` / `patchStaticNode` | 编译优化后的静态节点 |
| `Fragment` | `processFragment` | 片段 |
| Element | `processElement` → `mountElement` / `patchElement` | 普通元素 |
| Component | `processComponent` → `mountComponent` / `updateComponent` | 组件 |
| Teleport | 调用 Teleport 自身的 process | 传送门 |
| Suspense | 调用 Suspense 自身的 process | 异步组件 |

### patchFlag 优化

**patchFlag** 是在生成 VNode 阶段产生的，它标记了元素哪些部分是动态的，用来在 Diff 中进行性能优化。

### 流程图

```mermaid
graph TD
    A["patch(n1, n2)"] --> B{"n1 === n2?"}
    B -->|是| Z["节点没变，不需要更新"]
    B -->|否| C{"同类型?"}

    C -->|否| D["unmount旧节点<br/>n1 = null"]
    D --> E

    C -->|是| E{"根据 n2.type 分支"}

    E -->|Element| J{"首次挂载?"}

    J -->|是| J1["挂载新元素"]
    J -->|否| J2["匹配旧元素"]

    J2 --> J3{"有动态子元素?"}
    J3 -->|否| J5["patchChildren 全量 diff"]
    J3 -->|是| J4["patchBlockChildren 只遍历动态节点"]
```

---

## 二、Diff 核心

Diff 算法是降低 DOM 渲染频率以提升 Vue 性能的算法。算法的思想是降低真实DOM的增删操作，尽量复用旧的节点。

在 Patch 递归过程中只能处理单节点嵌套，而消耗大量性能的多子节点更新最终会在 `patchChildren` 中处理。

### 两种情形

- **有 key**：进行头尾匹配，再对中间无序区间进行最长递增子序列进行节点移动性能优化
- **无 key**：按索引一一对比，多余旧节点卸载，多余新节点挂载

其中对于有 key 属性的子节点处理就是整个 Diff 性能优化最核心的地方。

### 有 key 的 Diff 流程

1. **从头同步**：双指针从开头向中间移动，逐个比对，相同则 patch
2. **从尾同步**：双指针从结尾向中间移动，逐个比对，相同则 patch
3. **处理剩余**：
   - 旧节点先遍历完 → 剩余新节点挂载
   - 新节点先匹配完 → 剩余旧节点卸载
4. **乱序处理**：构建新节点 key → index 映射，遍历旧节点匹配更新，通过最长递增子序列计算最少移动

**伪代码**：

```
function patchKeyedChildren(旧列表, 新列表):
    i = 0                    // 起始指针
    e1 = 旧列表.length - 1   // 旧列表末尾
    e2 = 新列表.length - 1   // 新列表末尾

    // 1. 头同步：从头逐个比对，相同则 patch，指针后移
    while i <= e1 && i <= e2 && 旧列表[i] 与 新列表[i] 类型相同:
        patch(旧列表[i], 新列表[i])
        i++

    // 2. 尾同步：从尾逐个比对，相同则 patch，末尾前移
    while i <= e1 && i <= e2 && 旧列表[e1] 与 新列表[e2] 类型相同:
        patch(旧列表[e1], 新列表[e2])
        e1--; e2--

    // 3. 剩余处理
    if i > e1:                // 旧节点遍历完，新节点还有
        挂载剩余新节点
    else if i > e2:          // 新节点匹配完，旧节点还有
        卸载剩余旧节点
    else:
        // 4. 乱序部分
        建立 新列表 key → index 的映射表

        遍历旧列表:
            根据 key 在映射表中查找对应新节点
            if 找到:
                patch 该节点
                记录"新节点位置 → 旧节点位置"的对应关系
                判断是否需要移动（位置递减 = 需要移动）
            else:
                卸载该旧节点

        计算最长递增子序列（基于记录的对应关系）

        从后向前遍历新列表:
            if 从未匹配过:
                挂载该新节点
            else if 需要移动且不在递增序列中:
                移动该节点到正确位置
```

**核心思想**：通过最长递增子序列找出不需要移动的节点，只移动必须移动的节点，最小化 DOM 操作。

---

## 三、组件更新

组件更新流程分为两种触发方式：**内部状态变化** 和 **父组件更新**。

### 触发方式

| 触发方式 | 说明 |
|---------|------|
| 内部状态变化 | 组件自己的响应式数据变化，触发 `instance.update()` |
| 父组件更新 | 父组件传入新的 VNode，触发 patch |

### 核心流程

```mermaid
graph TD
    A["组件状态变化"] --> B["instance.update()"]
    B --> C["componentUpdateFn"]
    C --> D{"shouldUpdateComponent?"}

    D -->|是| E["updateComponentPreRender"]
    D -->|否| F["复用旧 VNode"]

    E --> G["renderComponentRoot 渲染新 VNode"]
    G --> H["patch prevTree, nextTree"]
    H --> I["Diff 比对 + DOM 更新"]

    F --> J[结束]
    I --> J
```

#### 1. `updateComponent` - 判断是否需要更新

```
function updateComponent(旧VNode, 新VNode):
    从 新VNode 获取组件实例

    if 应该更新(旧VNode, 新VNode):
        if 是异步组件且未解析完成:
            只更新 props 和 slots
        else:
            缓存新 VNode
            触发组件的响应式 effect（执行渲染函数）
    else:
        直接复用旧 VNode 的 DOM 元素
```

#### 2. `componentUpdateFn` - 渲染 effect 核心

```
function componentUpdateFn():
    if 未挂载:
        执行挂载流程
    else:
        // 更新流程
        if 有待处理的 VNode:
            更新组件的 props 和 slots

        执行 beforeUpdate 生命周期钩子

        // 渲染
        新子树 = 执行组件的 render 函数（生成新 VNode）
        旧子树 = 当前保存的子树

        // 比对
        patch(旧子树, 新子树)

        执行 updated 生命周期钩子
```

#### 3. `updateComponentPreRender` - 更新组件内部状态

```
function updateComponentPreRender(组件实例, 新VNode):
    更新组件实例的 vnode 引用
    清空待处理的 next
    更新 props
    更新 slots
    刷新前置队列中的回调
```

### 生命周期顺序

```
beforeUpdate → 渲染新 VNode → patch → updated
```

---

## 四、Fragment & Teleport 等特殊 VNode 的处理

### Fragment

Fragment 用于处理多个根节点的情况，如模板编译产生的 `<></>` 或 `v-for` 生成的片段。

**特点**：没有单个 DOM 元素作为根，需要用两个锚点（startAnchor/endAnchor）包裹。

#### 语义化描述

```
function processFragment(旧VNode, 新VNode, 容器, 锚点):
    // 创建两个锚点标记片段边界
    创建片段起始锚点
    创建片段结束锚点

    if 首次挂载:
        将两个锚点插入容器
        遍历子节点逐个挂载到两个锚点之间
    else:
        if 是稳定片段且有动态子节点:
            只 patch 动态子节点（快速路径）
        else:
            全量比对子节点列表
```

#### 两种更新路径

| 路径 | 条件 | 说明 |
|------|------|------|
| 快速路径 | `STABLE_FRAGMENT` + `dynamicChildren` | 子节点顺序不变，只更新动态节点 |
| 全量路径 | 其他情况 | 调用 `patchChildren` 全量比对 |

---

### Teleport

Teleport 用于将子节点渲染到当前组件 DOM 树以外的位置，如 Modal、Toast 等场景。

**核心概念**：

- `to`：目标容器，可以是 CSS 选择器或 DOM 元素
- `disabled`：是否禁用 teleport
- `targetAnchor`：`to` 容器中的插入锚点

#### 语义化描述

```
function processTeleport(旧VNode, 新VNode, 容器, 锚点):
    if 首次挂载:
        // 1. 在原始位置插入占位锚点
        创建 teleport start 锚点
        创建 teleport end 锚点

        // 2. 挂载到目标容器
        if 未禁用:
            解析目标容器
            将子节点挂载到目标容器中

    else:
        // 更新流程
        复用旧 VNode 的锚点引用

        // 1. 处理子节点更新
        if 有动态子节点:
            快速路径 patch
        else:
            全量比对子节点

        // 2. 处理目标容器变化
        if 禁用状态变化:
            移动到对应容器（主容器或目标容器）
        else if 目标容器变化:
            移动到新的目标容器
```

#### 三种移动类型

| 类型 | 说明 |
|------|------|
| `TOGGLE` | enabled ↔ disabled 状态切换 |
| `TARGET_CHANGE` | 目标容器（`to` prop）变化 |
| `GLOBAL` | 未知原因需要全局移动 |

---

### Suspense

Suspense 用于处理异步组件加载状态，展示加载中/失败等 fallback UI。

（详见 `packages/runtime-core/src/components/Suspense.ts`）


---

# 生成器和可迭代对象

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/genetator-iterator/
> **分类**：JavaScript
> **标签**：Javascript
> **发布日期**：2025-03-27
> **描述**：学习js中的生成器和可迭代对象


> JavaScript 中的**可迭代对象（Iterables）**和**生成器（Generators）**是处理序列数据的核心机制，它们让异步操作、惰性计算和数据流处理变得优雅。


## 一、可迭代对象

如果一个对象实现了 **`[Symbol.iterator]`** 方法，并且该方法返回一个遵循**迭代器协议**的对象（即具有 `next()` 方法，返回 `{ value, done }`），那么它就是可迭代的。

### 内置的可迭代对象

JavaScript 内置了多种可迭代对象，可以直接使用 `for...of` 遍历：

```js
// 字符串 —— 按 Unicode 字符遍历
for (const char of "hello") {
  console.log(char); // h, e, l, l, o
}

// 数组
for (const item of [10, 20, 30]) {
  console.log(item);
}

// Map（保留插入顺序）和 Set（去重）
const map = new Map([['a', 1], ['b', 2]]);
for (const [key, value] of map) {
  console.log(key, value);
}
```

### `for...of` 的底层原理

`for...of` 本质上是这样工作的：

```js
const iterable = [10, 20, 30];

// 1. 获取迭代器
const iterator = iterable[Symbol.iterator]();

// 2. 反复调用 next()，直到 done 为 true
let result = iterator.next();
while (!result.done) {
  console.log(result.value); // 10, 20, 30
  result = iterator.next();
}
```

理解这个机制，有助于你更好地自定义可迭代行为。

### 自定义可迭代对象

手动实现 `[Symbol.iterator]` 方法：

```js
const range = {
  from: 1,
  to: 5,
  [Symbol.iterator]() {
    return {
      current: this.from,
      last: this.to,
      next() {
        return this.current <= this.last
          ? { done: false, value: this.current++ }
          : { done: true, value: undefined };  // done: true 时 value 可省略，但建议显式写出
      }
    };
  }
};

console.log([...range]); // [1, 2, 3, 4, 5]
```

---

## 二、生成器

生成器是 ES6 引入的特殊函数，用 `function*` 声明。它最大的特点是**可以在执行过程中暂停和恢复**，通过 `yield` 关键字交出控制权。

### 基本语法

```js
function* idGenerator() {
  let id = 1;
  while (true) {
    yield id++; // 每次在这里暂停，返回当前 id
  }
}

const gen = idGenerator();
console.log(gen.next().value); // 1
console.log(gen.next().value); // 2
console.log(gen.next().value); // 3
// 不会无限循环，每次 yield 都会把控制权交还调用方
```

### 生成器与可迭代的关系

**生成器对象同时满足迭代器协议和可迭代协议**——它既是迭代器（有 `next()` 方法），也是可迭代对象（`[Symbol.iterator]` 返回自身）。这意味着生成器可以无缝接入任何需要可迭代对象的场景。

```js
function* countdown(n) {
  while (n >= 0) {
    yield n;
    n--;
  }
}

// 生成器可以直接用于 for...of
for (const num of countdown(5)) {
  console.log(num); // 5, 4, 3, 2, 1, 0
}

// 也可以展开
console.log([...countdown(3)]); // [3, 2, 1, 0]

// 还能解构
const [first, second] = countdown(10);
console.log(first, second); // 10, 9
```

### `return` 在生成器中的特殊行为

生成器内的 `return` 会结束迭代，将 `done` 设为 `true`：

```js
function* withReturn() {
  yield 1;
  yield 2;
  return 3;  // 结束生成器，value 3 通常被忽略
  yield 4;   // 不会执行
}

const g = withReturn();
console.log(g.next()); // { value: 1, done: false }
console.log(g.next()); // { value: 2, done: false }
console.log(g.next()); // { value: 3, done: true } ← return 的值
console.log(g.next()); // { value: undefined, done: true }
```

> 注意：`return` 的值虽然会出现在最后一个 `next()` 的结果中，但 `for...of` 和展开运算符会忽略它。

### 生成器的 `return()` 和 `throw()`

作为调用方，你可以主动控制生成器的生命周期：

```js
function* gen() {
  try {
    yield 1;
    yield 2;
    yield 3;
  } finally {
    console.log('清理资源');  // finally 会在生成器被终止时执行
  }
}

const g = gen();
console.log(g.next());        // { value: 1, done: false }
console.log(g.return(100));   // { value: 100, done: true } —— 提前终止
// 输出："清理资源"

const g2 = gen();
g2.next();                    // 先启动到第一个 yield
g2.throw(new Error('出错了')); // 向生成器内部注入异常
// Error: 出错了
```

这两个方法在需要**提前终止生成器**或**处理生成器内部异常**时非常有用。

### `yield*` —— 委托迭代

`yield*` 可以将迭代工作委托给另一个可迭代对象，避免手动逐个 `yield`：

```js
function* combined() {
  yield* [1, 2, 3];
  yield 'end';
}

// 上面的代码等效于：
function* combinedManual() {
  yield 1;
  yield 2;
  yield 3;
  yield 'end';
}

console.log([...combined()]); // [1, 2, 3, 'end']
```

`yield*` 还可以递归委托给另一个生成器，常用于遍历树形结构。

### 双向通信

生成器不仅可以向外产出值，还可以通过 `next(value)` 向内部传入数据：

```js
function* chat() {
  const name = yield "你叫什么名字？";
  yield `你好，${name}！`;
}

const g = chat();
console.log(g.next().value);         // "你叫什么名字？"
console.log(g.next("Alice").value);  // "你好，Alice！"
```

第一次调用 `g.next()` 启动生成器，之后每次传入的参数会成为上一个 `yield` 表达式的返回值。这种双向通信让生成器可以实现**协程**模式。

---

## 三、异步生成器

ES2018 引入了异步生成器（`async function*`）和 `for await...of` 语法，用于处理异步数据流。它的核心是：

- 用 `async function*` 定义异步生成器
- 内部可以 `await` 异步操作，也可以 `yield` 值
- 外部用 `for await...of` 消费

```js
// 异步生成器：每 500ms 产出一个值
async function* asyncCounter() {
  let i = 0;
  while (i < 3) {
    await new Promise(resolve => setTimeout(resolve, 500));
    yield i++;
  }
}

// 消费异步生成器
(async () => {
  for await (const num of asyncCounter()) {
    console.log(num); // 0, 1, 2（每 500ms 输出一个）
  }
})();
```

异步生成器是连接"异步操作"与"迭代器模式"的桥梁，也是接下来两个实战场景的基础。

---

## 四、实际应用场景

掌握基础概念后，我们来看看生成器在真实项目中如何解决实际问题。

### 1. 无限滚动

将分页 API 封装成异步生成器后，调用方完全不需要关心分页逻辑：

```js
// 封装层：自动翻页，对调用方来说就像个无限数组
async function* fetchAllUsers(pageSize = 20) {
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(`/api/users?page=${page}&size=${pageSize}`);
    const { data, total } = await response.json();

    for (const user of data) {
      yield user; // 每次产出一个用户，而不是一整页
    }

    hasMore = page * pageSize < total;
    page++;
  }
}

// 消费层：完全不需要关心分页逻辑
async function renderUserList() {
  const container = document.getElementById('users');

  // 甚至可以配合 Intersection Observer，每次滚动到底部只取 10 条
  for await (const user of fetchAllUsers()) {
    const div = document.createElement('div');
    div.textContent = `${user.name} - ${user.email}`;
    container.appendChild(div);

    // 控制节奏：每渲染 50 条暂停，等用户继续滚动
    if (container.children.length % 50 === 0) {
      await waitForScroll(); // 伪代码：等待用户滚动到底部再继续
    }
  }
}
```

### 2. 流式传输（SSE）

处理 ChatGPT 这类流式接口时，异步生成器可以将底层的 SSE（Server-Sent Events）格式封装成干净的数据流：

```js
// 封装层：把 fetch SSE 流转成异步生成器
async function* streamChatGPT(messages) {
  const response = await fetch('/api/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ messages, stream: true })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  try {
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      const chunk = decoder.decode(value, { stream: true });
      // SSE 格式：每行以 "data: " 开头
      for (const line of chunk.split('\n')) {
        if (line.startsWith('data: ')) {
          const json = line.slice(6);
          if (json === '[DONE]') return;

          const parsed = JSON.parse(json);
          const content = parsed.choices?.[0]?.delta?.content;
          if (content) yield content;  // 逐字/逐句产出
        }
      }
    }
  } finally {
    reader.releaseLock(); // 确保资源释放
  }
}

// 消费层：业务代码完全感知不到流的复杂性
async function chat() {
  const messages = [{ role: 'user', content: '讲个故事' }];

  // 就像在处理一个普通数组，但是是异步、流式的
  for await (const token of streamChatGPT(messages)) {
    process.stdout.write(token);  // 逐字打印，无需等待全部响应
  }
}
```

---

## 总结

| 特性 | 可迭代对象 | 生成器 | 异步生成器 |
|------|----------|--------|-----------|
| 定义方式 | 实现 `[Symbol.iterator]` | `function*` | `async function*` |
| 协议 | 迭代器协议 | 迭代器 + 可迭代协议 | 异步迭代器 + 异步可迭代协议 |
| 消费方式 | `for...of` / `...` | `for...of` / `...` | `for await...of` |
| 核心能力 | 遍历序列 | **暂停/恢复**、双向通信 | 暂停/恢复 + **异步操作** |

理解生成器的关键在于：**它把"遍历数据"变成了"控制流程"**。`yield` 不只是返回值，更是一种流程控制的工具——这让无限数据流、延迟计算、资源清理等场景变得异常优雅。


---

# 关于vue的问题

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/vue-questions/
> **分类**：Vue
> **标签**：vue, 面试, 问题汇总
> **发布日期**：2024-03-15
> **描述**：Vue 常见问题汇总，包含基础与进阶知识点索引


## 基础

### [vue3和vue2的区别](./vue3-vs-vue2)

## 进阶

### [vue中的diff算法](./vue-diff)

### [vue的响应式](./vue-reactivity)


---

# vue响应式原理

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/vue-reactivity/
> **分类**：Vue
> **标签**：vue, 响应式, 原理, 源码
> **发布日期**：2024-03-10
> **描述**：从零实现一个简易 Vue，深入理解 Vue 响应式系统的核心原理


## VUE响应式原理

本文实现一个简单的Vue：

- 接收初始化的参数，这里只举几个简单的例子 el data options
- 通过私有方法 _proxyData 把data 注册到 Vue 中 转成getter setter
- 使用 observer 把 data 中的属性转为 响应式 添加到 自身身上
- 使用 observer 方法监听 data 的所有属性变化来 通过观察者模式 更新视图
- 使用 compiler 编译元素节点上面指令 和 文本节点差值表达式

### 1、vue.js

```ts
class Vue {
  constructor(options){
    
  }
}
```


---

# vue3和vue2的区别

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/vue3-vs-vue2/
> **分类**：Vue
> **标签**：vue, vue3, vue2, 对比
> **发布日期**：2024-03-05
> **描述**：全面解析 Vue3 与 Vue2 的差异，包括响应式原理、Composition API、编译优化等


# vue3和vue2的区别

1、vue3使用ts重写。

2、支持composition Api

3、响应式原理改用proxy实现，可监听动态新增删除属性，以及数组变化。

```js
// vue2的响应式使用defineProperty实现
const data = {
  name: '123',
  age: 18
}
const obj = {}
function proxyData(){
  Object.keys(data).forEach(key => {
    Object.defineProperty(obj, key, {
      get(){
        return data[key]
      },
      set(value){
        if(newValue === data[key]) return 
        data[key] = value
        // 附加响应式逻辑
      }
    })
  })
}
proxyData()

// vue3

const data = {
  name: '123',
  age: 18,
}

const vm = new Proxy(data, {
  get(target, key){
    return target[key]
  },
  set(target, key, value){
    if(target[key] === value) return
    target[key] = value
    // 响应式逻辑
  }
})
```

4、编译优化，vue2通过编辑静态根节点优化diff，vue3标记和提升所有静态根节点，diff的时候只需要对比动态节点内容

5、移除了一些不常用的api（inline-template、filter）

6、生命周期的变化：使用setup代替了之前的beforeCreate和created

7、vue3的template模板支持多个根标签

8、Vuex状态管理：创建实例的方式改变，vue2为new Store，vue3为createStore

9、Route获取页面实例与路由信息：vue2通过**this**获取router实例，vue3通过使用getCurrentInstance/useRoute和useRouter方法获取当前组件实例

10、Props的使用变化：vue2通过this获取props里面的内容，vue3直接通过defineProps

11、父子组件传值：vue3向父组件传回数据时，如使用自定义名称需要使用defineEmits


---

# Vue2和Vue3中diff算法对比

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/vue-diff/
> **分类**：Vue
> **标签**：vue, diff, 算法, 虚拟DOM
> **发布日期**：2024-03-01
> **描述**：详细对比 Vue2 和 Vue3 的 diff 算法实现原理


# diff算法

Diff 算法是 Vue 虚拟 DOM（Virtual DOM）渲染器的核心机制，其目标是用**最小的性能代价**找出新旧虚拟节点（VNode）之间的差异，并高效地更新真实 DOM。完整对比两棵 DOM 树的差异时间复杂度为 O(n³)，这在实际应用中是性能灾难。Vue 通过一系列优化策略将复杂度降至 O(n)，而 Vue 3 在此基础上进一步优化了算法实现。

---

## vue2 diff算法

### 核心思想：双端比较（Double-Ended Diff）

Vue 2 的 diff 算法基于 snabbdom 修改而来，核心策略是**同层比较**和**双端比较**。算法通过四个指针分别指向新旧列表的头尾，进行四种假设性匹配，尽可能复用已有的 DOM 节点。

#### 四个核心指针

| 指针 | 含义 |
|------|------|
| `oldStartIdx` | 指向旧子节点列表头部 |
| `oldEndIdx` | 指向旧子节点列表尾部 |
| `newStartIdx` | 指向新子节点列表头部 |
| `newEndIdx` | 指向新子节点列表尾部 |

#### 五步匹配策略

算法在 `while` 循环中运行，终止条件是任一方的头指针越过尾指针。每一轮循环按**固定顺序**进行以下匹配：

**① 头-头匹配（oldStart vs newStart）**

检查两个列表的第一个节点是否相同（key 和 tag 均相同）。若匹配，调用 `patchVnode` 更新节点，两个 `Start` 指针同时后移（+1）。

**② 尾-尾匹配（oldEnd vs newEnd）**

检查两个列表的最后一个节点是否相同。若匹配，调用 `patchVnode` 更新节点，两个 `End` 指针同时前移（-1）。

**③ 旧头-新尾匹配（oldStart vs newEnd）**

适用于"首节点移到了尾部"的场景。若匹配，更新节点后将 `oldStart` 指向的 DOM 移动到 `oldEnd` 对应 DOM 的后面。`oldStartIdx++`，`newEndIdx--`。

**④ 旧尾-新头匹配（oldEnd vs newStart）**

适用于"尾节点移到了头部"的场景。若匹配，更新节点后将 `oldEnd` 指向的 DOM 移动到 `oldStart` 对应 DOM 的前面。`oldEndIdx--`，`newStartIdx++`。

**⑤ 乱序匹配**

若以上四种匹配全部失败，则以旧列表剩余节点的 `key` 建立哈希映射表，用新头节点的 `key` 去查找：

- **找到了**：复用该节点，将其 DOM 移动到 `oldStart` 前面
- **没找到**：创建新 DOM 节点插入到 `newStartIdx` 位置

#### 循环结束后的收尾

- **旧列表先遍历完**（`oldStartIdx > oldEndIdx`）：新列表剩余节点为新增，批量挂载
- **新列表先遍历完**（`newStartIdx > newEndIdx`）：旧列表剩余节点为多余，批量卸载

#### 代码流程示意

```javascript
function updateChildren(oldCh, newCh) {
  let oldStartIdx = 0, newStartIdx = 0;
  let oldEndIdx = oldCh.length - 1, newEndIdx = newCh.length - 1;
  let oldStartVnode = oldCh[0], newStartVnode = newCh[0];
  let oldEndVnode = oldCh[oldEndIdx], newEndVnode = newCh[newEndIdx];

  while (oldStartIdx <= oldEndIdx && newStartIdx <= newEndIdx) {
    if (sameVnode(oldStartVnode, newStartVnode)) {
      // 头-头匹配
      patchVnode(oldStartVnode, newStartVnode);
      oldStartVnode = oldCh[++oldStartIdx];
      newStartVnode = newCh[++newStartIdx];
    } else if (sameVnode(oldEndVnode, newEndVnode)) {
      // 尾-尾匹配
      patchVnode(oldEndVnode, newEndVnode);
      oldEndVnode = oldCh[--oldEndIdx];
      newEndVnode = newCh[--newEndIdx];
    } else if (sameVnode(oldStartVnode, newEndVnode)) {
      // 旧头-新尾匹配（需要移动DOM）
      patchVnode(oldStartVnode, newEndVnode);
      parentElm.insertBefore(oldStartVnode.el, oldEndVnode.el.nextSibling);
      oldStartVnode = oldCh[++oldStartIdx];
      newEndVnode = newCh[--newEndIdx];
    } else if (sameVnode(oldEndVnode, newStartVnode)) {
      // 旧尾-新头匹配（需要移动DOM）
      patchVnode(oldEndVnode, newStartVnode);
      parentElm.insertBefore(oldEndVnode.el, oldStartVnode.el);
      oldEndVnode = oldCh[--oldEndIdx];
      newStartVnode = newCh[++newStartIdx];
    } else {
      // 乱序匹配：建立key映射表查找
      // ...
    }
  }

  // 处理新增或删除的节点
  if (oldStartIdx > oldEndIdx) {
    // 挂载新节点
  } else if (newStartIdx > newEndIdx) {
    // 卸载旧节点
  }
}
```

#### Vue 2 diff 算法的特点与局限

**优势：**
- 对于列表在两端增删的场景（最常见），双端对比能迅速收窄范围
- 通过头尾交叉检测，能有效优化"倒序"或"首尾互换"场景
- 时间复杂度为 O(n)，相比简单 diff 的 O(n²) 大幅优化

**局限：**
- 处理长列表的复杂乱序时，频繁创建 key 映射表存在额外性能开销
- 无法保证 DOM 移动次数是最少的，偶尔会产生多余的移动操作
- 全量对比属性，无法精准只对比变化的部分

---

## vue3 diff算法

### 核心思想：快速 Diff + 最长递增子序列（Quick Diff + LIS）

Vue 3 借鉴了 inferno 框架的算法思路，引入了**预处理**和**最长递增子序列（LIS）**算法。其核心思想是：先通过预处理缩小需要处理的乱序区间，再对剩余节点使用 LIS 算法找出相对顺序不需要改变的最大集合，只移动不在序列中的节点，从而将 DOM 移动次数降至理论上的最低值。

#### 五步优化策略

**① 预处理前置节点（从前往后比较）**

新旧列表从头部开始逐个比较，直到遇到不同类型的节点。所有匹配的前置节点直接 `patch` 复用。

```
旧列表：[A, B, C, D, E]
新列表：[A, B, D, C, E]
         ↑↑ 匹配，i = 2
```

**② 预处理后置节点（从后往前比较）**

跳过前置匹配后，从尾部继续向前比较，直到遇到不同类型节点。

```
旧列表：[A, B, C, D, E]
新列表：[A, B, D, C, E]
                     ↑ 匹配，E 相同，e1--, e2--
```

**③ 处理仅有新增节点的情况**

若旧节点已遍历完（`i > e1`），但新节点还有剩余，说明剩余部分为新增节点，批量挂载。

**④ 处理仅有卸载节点的情况**

若新节点已遍历完（`i > e2`），但旧节点还有剩余，说明剩余部分为多余节点，批量卸载。

**⑤ 处理混合复杂情况（核心 diff）**

当前后预处理后仍有未处理的节点，说明存在乱序、新增、删除、移动的混合场景。此时进入核心 diff 流程：

- **建立新节点索引表**（`keyToNewIndexMap`）：以 key 为键，新列表中的索引为值
- **构建新旧位置映射**（`newIndexToOldIndexMap`）：遍历旧节点，在映射表中查找可复用的节点，记录其在新列表中的位置
- **获取最长递增子序列**：对 `newIndexToOldIndexMap` 求 LIS，得到不需要移动的节点集合
- **逆向遍历移动节点**：从后向前遍历新节点列表，不在 LIS 中的节点执行移动操作

#### 最长递增子序列（LIS）的作用

最长递增子序列是 Vue 3 diff 算法最核心的优化点。其作用是：在乱序节点中，找出一个**相对顺序已经正确**的最大节点集合，这些节点不需要移动，只需要移动不在序列中的节点。

**示例：**

```
旧列表：[A, B, C, D, E]
新列表：[A, C, E, B, D]

// 预处理后（A 已匹配）
剩余旧：[B, C, D, E]
剩余新：[C, E, B, D]

// 新节点在旧列表中的位置映射
newIndexToOldIndexMap = [2, 4, 1, 3]  // C(2), E(4), B(1), D(3)

// 最长递增子序列
LIS = [1, 3]  // 对应 B(1), D(3) 或 C(2), E(4)

// 结果：不在 LIS 中的节点需要移动
```

LIS 使用**贪心 + 二分查找**算法实现，时间复杂度为 O(n log n)。

#### 完整代码流程

```typescript
function patchKeyedChildren(c1, c2, container, parentAnchor) {
  let i = 0;
  const e1 = c1.length - 1;
  const e2 = c2.length - 1;
  let e1p = e1, e2p = e2;

  // 1. 同步头部
  while (i <= e1p && i <= e2p) {
    if (isSameVNodeType(c1[i], c2[i])) {
      patch(c1[i], c2[i], container);
      i++;
    } else {
      break;
    }
  }

  // 2. 同步尾部
  while (i <= e1p && i <= e2p) {
    if (isSameVNodeType(c1[e1p], c2[e2p])) {
      patch(c1[e1p], c2[e2p], container);
      e1p--;
      e2p--;
    } else {
      break;
    }
  }

  // 3. 处理仅有新增
  if (i > e1p) {
    for (let j = i; j <= e2p; j++) {
      patch(null, c2[j], container, anchor);
    }
    return;
  }

  // 4. 处理仅有卸载
  if (i > e2p) {
    for (let j = i; j <= e1p; j++) {
      unmount(c1[j]);
    }
    return;
  }

  // 5. 处理未知序列（核心diff）
  const s1 = i, s2 = i;
  const keyToNewIndexMap = new Map();
  for (i = s2; i <= e2p; i++) {
    keyToNewIndexMap.set(c2[i].key, i);
  }

  const toBePatched = e2p - s2 + 1;
  const newIndexToOldIndexMap = new Array(toBePatched).fill(0);

  // 遍历旧节点，寻找可复用节点
  for (i = s1; i <= e1p; i++) {
    const oldVNode = c1[i];
    const newIndex = keyToNewIndexMap.get(oldVNode.key);
    if (newIndex === undefined) {
      unmount(oldVNode); // 旧节点不存在于新列表中
    } else {
      newIndexToOldIndexMap[newIndex - s2] = i + 1; // +1 区分0（新增）
      patch(oldVNode, c2[newIndex], container);
    }
  }

  // 获取最长递增子序列
  const increasingNewIndexSequence = getSequence(newIndexToOldIndexMap);
  let j = increasingNewIndexSequence.length - 1;

  // 逆向遍历移动节点
  for (i = toBePatched - 1; i >= 0; i--) {
    const nextIndex = s2 + i;
    const nextChild = c2[nextIndex];
    const anchor = nextIndex + 1 < c2.length ? c2[nextIndex + 1].el : parentAnchor;

    if (newIndexToOldIndexMap[i] === 0) {
      patch(null, nextChild, container, anchor); // 新增节点
    } else {
      if (j < 0 || i !== increasingNewIndexSequence[j]) {
        container.insertBefore(nextChild.el, anchor); // 移动节点
      } else {
        j--; // 在LIS中，不需要移动
      }
    }
  }
}
```

---

## Vue 2 与 Vue 3 diff 算法对比

### 核心差异

| 特性 | Vue 2 | Vue 3 |
|------|-------|-------|
| **算法核心** | 双端比较（Double-Ended Diff） | 快速 Diff + 最长递增子序列 |
| **对比方式** | 四个指针从两端向中间靠拢 | 先预处理前缀后缀，再处理中间乱序 |
| **节点移动策略** | 头尾交叉检测 + 乱序哈希查找 | LIS 算法找出最小移动集合 |
| **乱序处理** | 建立 key→index 映射表逐个查找 | 建立映射 + LIS 批量优化 |
| **DOM 移动次数** | 非最优，可能有多余移动 | 理论最少 |
| **属性对比** | 全量对比所有属性 | Patch Flags 精准对比动态属性 |
| **静态节点** | 每次渲染都重新生成 VNode | 静态提升，仅生成一次 |
| **时间复杂度** | O(n) | O(n) ~ O(n log n) |

### 为什么 Vue 3 更快？

1. **更少的 DOM 移动操作**：通过 LIS 算法，Vue 3 能计算出最少的节点移动次数，而 Vue 2 的双端比较在某些复杂乱序场景下会产生多余的移动

2. **预处理缩小范围**：Vue 3 的前后置预处理能快速排除不需要处理的节点，而 Vue 2 需要逐一轮询

3. **静态节点提升**：Vue 3 在编译阶段将静态节点提升，渲染时直接复用，不参与 diff 比较

4. **Patch Flags 靶向更新**：Vue 3 通过编译时标记动态节点，diff 时只对比变化的属性，而非全量对比

### 关键概念总结

**为什么 key 很重要？**

- `key` 是节点的唯一标识，帮助算法精准匹配新旧节点
- 有 `key` 时，算法将"销毁-再创建"变为"低开销的移动"
- 避免使用 `index` 作为 `key`，当列表排序、插入、删除时会导致误判

**Vue 2 的适用场景：**

- 列表变更主要在两端增删（性能已足够好）
- 简单倒序或首尾互换

**Vue 3 的优势场景：**

- 复杂乱序排列的长列表
- 包含大量静态内容的页面（静态提升收益大）
- 需要最少 DOM 操作的高频更新场景

---

## 总结

Vue 2 的双端 diff 算法是一种成熟且高效的实现，通过四个指针的巧妙配合，将时间复杂度从 O(n²) 优化到 O(n)，能很好地处理大多数列表更新场景。而 Vue 3 的快速 diff 算法在此基础上引入了最长递增子序列算法，进一步优化了乱序场景下的 DOM 移动次数，配合静态提升和 Patch Flags 等编译期优化，使得 Vue 3 在大型应用中的渲染性能有了显著提升。

从本质上讲，Vue 2 是在"勤奋"地对比每一处差异，而 Vue 3 是通过"聪明"的编译分析和数学优化，让自己**尽量少干活、只干精准的活**。


---

# 跨域

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/cross_origin_guide/
> **分类**：网络
> **标签**：cors, 跨域, 同源策略
> **发布日期**：2024-01-20
> **描述**：深入理解浏览器的同源策略及多种跨域解决方案


# 跨域（Cross-Origin）详解与解决方案

## 一、什么是跨域？

### 1.1 同源策略（Same-Origin Policy）

**同源策略**是浏览器最核心的安全策略之一，由 Netscape 公司于 1995 年引入。它限制了一个源（origin）的文档或脚本如何与另一个源的资源进行交互。这是一个用于隔离潜在恶意文件的重要安全机制。

> **同源的定义**：如果两个 URL 的**协议（protocol）、域名（host）、端口（port）**都相同，则它们是同源的。

| URL | 与 `http://www.example.com:80/page.html` 是否同源 | 原因 |
|:---|:---|:---|
| `http://www.example.com:80/page2.html` | 同源 | 协议、域名、端口均相同 |
| `http://www.example.com/page2.html` | 同源 | 默认端口 80 可省略 |
| `https://www.example.com/page.html` | 跨域 | 协议不同（http vs https） |
| `http://api.example.com/page.html` | 跨域 | 域名不同（子域不同） |
| `http://www.example.com:8080/page.html` | 跨域 | 端口不同（80 vs 8080） |
| `http://www.other.com/page.html` | 跨域 | 域名完全不同 |

### 1.2 跨域的场景

浏览器在执行以下操作时，会受到同源策略的限制：

- **AJAX/Fetch 请求**：XMLHttpRequest 和 Fetch API 默认只能请求同源资源
- **Cookie、LocalStorage、IndexedDB**：无法读取非同源的存储数据
- **DOM 操作**：无法获取非同源页面的 DOM 节点
- **Canvas/WebGL**：使用跨域图片时可能被污染（tainted canvas）

> **注意**：跨域限制是**浏览器的行为**，服务器之间或命令行工具（如 curl、Postman）请求不受同源策略限制。

---

## 二、AJAX 跨域解决方法

### 2.1 JSONP（JSON with Padding）

JSONP 是一种利用 `<script>` 标签不受同源策略限制特性的跨域解决方案。

**原理**：
- `<script>`、`<img>`、`<link>` 等标签的 `src` 属性可以加载跨域资源
- 服务端将数据包装在一个回调函数中返回
- 浏览器执行该回调函数，获取数据

**前端代码示例**：

```javascript
function handleResponse(data) {
  console.log('获取到的数据:', data);
}

// 动态创建 script 标签
function jsonpRequest(url, callbackName) {
  const script = document.createElement('script');
  script.src = `${url}?callback=${callbackName}`;
  document.body.appendChild(script);
  
  // 清理
  script.onload = function() {
    document.body.removeChild(script);
  };
}

// 使用
jsonpRequest('https://api.example.com/data', 'handleResponse');
```

**服务端返回格式**：

```javascript
handleResponse({ "name": "张三", "age": 25 });
```

**JSONP 的优缺点**：

| 优点 | 缺点 |
|:---|:---|
| 兼容性好，支持老旧浏览器 | 只支持 GET 请求，不支持 POST/PUT/DELETE |
| 实现简单，无需服务端复杂配置 | 存在 XSS 安全风险（服务端注入恶意代码） |
| 不需要浏览器端 CORS 支持 | 无法获取详细的错误信息 |
| | 需要服务端配合支持 |

> **安全提醒**：JSONP 存在被恶意网站利用的风险，现在已逐渐被 CORS 取代，建议优先使用 CORS。

### 2.2 跨域资源共享（CORS）

CORS（Cross-Origin Resource Sharing）是 W3C 标准，目前最主流的跨域解决方案。它允许服务器通过设置特定的 HTTP 响应头来告知浏览器是否允许跨域请求。

#### CORS 请求分类

**（1）简单请求（Simple Request）**

需同时满足以下条件：
- 方法为 `GET`、`HEAD`、`POST` 之一
- 头部字段仅限于：`Accept`、`Accept-Language`、`Content-Language`、`Content-Type`
- `Content-Type` 仅限于：`application/x-www-form-urlencoded`、`multipart/form-data`、`text/plain`

简单请求流程：
```
浏览器直接发送请求，自动在请求头中添加 Origin 字段
服务器返回 Access-Control-Allow-Origin 响应头
浏览器判断该响应头是否允许当前源访问
```

**（2）预检请求（Preflight Request）**

对于非简单请求，浏览器会先发送 `OPTIONS` 预检请求：

```
OPTIONS /api/data HTTP/1.1
Origin: http://example.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: Content-Type,Authorization
```

服务端响应：
```
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400  // 预检结果缓存时间（秒）
```

#### 服务端 CORS 配置示例

**Node.js / Express**：
```javascript
const express = require('express');
const app = express();

// 方式一：使用 cors 中间件
const cors = require('cors');
app.use(cors({
  origin: 'http://localhost:3000',  // 允许的源，* 表示允许所有
  methods: ['GET', 'POST', 'PUT', 'DELETE'],  // 允许的方法
  allowedHeaders: ['Content-Type', 'Authorization'],  // 允许的头部
  credentials: true  // 允许携带 Cookie
}));

// 方式二：手动设置响应头
app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', 'http://localhost:3000');
  res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
  res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With');
  res.header('Access-Control-Allow-Credentials', 'true');
  
  if (req.method === 'OPTIONS') {
    res.sendStatus(200);  // 预检请求直接返回
  } else {
    next();
  }
});
```

**Nginx 配置**：
```nginx
server {
    listen 80;
    server_name api.example.com;
    
    location / {
        # 允许的源
        add_header 'Access-Control-Allow-Origin' 'https://app.example.com' always;
        add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization' always;
        add_header 'Access-Control-Allow-Credentials' 'true' always;
        add_header 'Access-Control-Max-Age' 1728000 always;
        
        # 处理预检请求
        if ($request_method = 'OPTIONS') {
            return 204;
        }
        
        proxy_pass http://backend_server;
    }
}
```

#### 前端 withCredentials 配置

当需要携带 Cookie 或认证信息时，前后端都需要配置：

```javascript
// XMLHttpRequest
const xhr = new XMLHttpRequest();
xhr.open('GET', 'https://api.example.com/data');
xhr.withCredentials = true;  // 允许携带 Cookie
xhr.send();

// Fetch API
fetch('https://api.example.com/data', {
  method: 'GET',
  credentials: 'include'  // 允许携带 Cookie
})
.then(response => response.json())
.then(data => console.log(data));

// Axios
axios.defaults.withCredentials = true;
// 或单条请求
axios.get('https://api.example.com/data', { withCredentials: true });
```

> **重要**：当 `withCredentials: true` 时，服务端**不能**将 `Access-Control-Allow-Origin` 设置为 `*`，必须指定具体的域名！

### 2.3 Flash 跨域（已废弃）

Flash 曾经提供 `crossdomain.xml` 机制来实现跨域。由于 Flash 已于 2020 年底停止支持，**此方法已不再推荐使用**。

如果维护遗留系统，只需了解 Flash 会读取目标域名根目录下的 `crossdomain.xml`：

```xml
<?xml version="1.0"?>
<cross-domain-policy>
    <allow-access-from domain="*.example.com" />
</cross-domain-policy>
```

### 2.4 服务端代理（反向代理）

通过在同源的服务器端设置代理，让服务器代替浏览器访问跨域资源，再将结果返回给浏览器。浏览器始终只与同源的代理服务器通信，完美避开跨域限制。

**实现方式**：

**（1）开发环境代理（Webpack DevServer）**：
```javascript
// vue.config.js 或 webpack.config.js
module.exports = {
  devServer: {
    proxy: {
      '/api': {
        target: 'https://api.example.com',  // 目标 API 服务器
        changeOrigin: true,  // 改变请求源头
        pathRewrite: {
          '^/api': ''  // 重写路径：/api/users → /users
        },
        secure: false,  // 接受 https 自签名证书
        // 可选：添加自定义请求头
        headers: {
          'X-Custom-Header': 'foobar'
        }
      }
    }
  }
};
```

前端请求时代码无需任何特殊处理：
```javascript
// 直接请求同源的 /api 路径，实际被代理到 https://api.example.com
axios.get('/api/users').then(res => console.log(res));
```

**（2）生产环境 Nginx 反向代理**：
```nginx
server {
    listen 80;
    server_name app.example.com;
    
    # 前端静态资源
    location / {
        root /var/www/app;
        try_files $uri $uri/ /index.html;
    }
    
    # API 代理
    location /api/ {
        proxy_pass https://api.example.com/;
        proxy_set_header Host api.example.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

**（3）Node.js 代理服务器**：
```javascript
const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');

const app = express();

app.use('/api', createProxyMiddleware({
  target: 'https://api.example.com',
  changeOrigin: true,
  pathRewrite: { '^/api': '' },
  onProxyRes: function(proxyRes, req, res) {
    // 可在这里统一处理响应
  }
}));

app.listen(3000);
```

**代理方案的优缺点**：

| 优点 | 缺点 |
|:---|:---|
| 无需处理复杂的 CORS 配置 | 增加了一层网络转发，可能带来延迟 |
| 前端代码无需任何修改 | 需要额外的服务器资源 |
| 可以统一处理认证、日志、缓存等 | 需要配置和维护代理服务 |
| 隐藏了真实后端地址，更安全 | |

---

## 三、前端跨域通信（iframe 场景）

当页面中使用 `<iframe>` 嵌入不同源的页面时，两者之间直接的 JavaScript 访问会受到同源策略限制。以下是几种解决方案：

### 3.1 document.domain + iframe（仅限子域）

**适用场景**：主域相同，仅子域不同。如 `a.example.com` 和 `b.example.com`。

**原理**：将两个页面的 `document.domain` 都设置为主域 `example.com`，浏览器即认为它们同源。

**代码示例**：

`http://a.example.com/page.html`：
```html
<!DOCTYPE html>
<html>
<body>
  <iframe id="iframe" src="http://b.example.com/page.html"></iframe>
  <script>
    // 必须双方都设置
    document.domain = 'example.com';
    
    window.onload = function() {
      const iframe = document.getElementById('iframe');
      // 现在可以访问 iframe 的内容
      console.log(iframe.contentWindow.document.body.innerHTML);
    };
  </script>
</body>
</html>
```

`http://b.example.com/page.html`：
```html
<!DOCTYPE html>
<html>
<body>
  <p>我是 B 页面的内容</p>
  <script>
    document.domain = 'example.com';
    // 也可以访问父页面
    console.log(window.parent.document.title);
  </script>
</body>
</html>
```

> **限制**：
> - 只能用于**主域相同、子域不同**的场景
> - 设置 `document.domain` 后**不可逆**，且只能设置为当前域的父域
> - 现代浏览器中此方法逐渐被淘汰，建议优先使用 `postMessage`

### 3.2 location.hash + iframe

**原理**：利用 `location.hash` 的改变不会触发页面刷新，且可以被同域页面读取的特性。通过中间代理页实现跨域通信。

**架构**：
```
A页面 (a.com) 
  → iframe 嵌套 B页面 (b.com)
    → B页面 iframe 嵌套 C页面 (a.com/proxy.html)  // C与A同源
```

**代码示例**：

`http://a.com/a.html`（父页面）：
```html
<iframe id="iframe" src="http://b.com/b.html"></iframe>
<script>
  // 1. 向 B 页面传递数据
  const iframe = document.getElementById('iframe');
  
  function sendMessageToB(data) {
    // 通过修改 B 页面的 hash 来传递数据
    iframe.src = `http://b.com/b.html#${encodeURIComponent(JSON.stringify(data))}`;
  }
  
  // 2. 监听 C 代理页面传回的数据
  function checkHash() {
    const hash = location.hash;
    if (hash && hash.length > 1) {
      const data = JSON.parse(decodeURIComponent(hash.substring(1)));
      console.log('收到 B 页面的回复:', data);
      location.hash = '';  // 清理 hash
    }
  }
  
  setInterval(checkHash, 100);  // 轮询监听 hash 变化
  sendMessageToB({ action: 'getUserInfo', userId: 123 });
</script>
```

`http://b.com/b.html`（跨域子页面）：
```html
<script>
  // 1. 监听 hash 变化，获取 A 页面传来的数据
  window.onhashchange = function() {
    const hash = location.hash.substring(1);
    const data = JSON.parse(decodeURIComponent(hash));
    console.log('收到 A 页面的消息:', data);
    
    // 2. 处理数据后，通过同域的 C 页面将结果传回 A
    const result = { status: 'success', userInfo: { name: '张三', age: 25 } };
    
    // C 页面与 A 页面同源（都在 a.com 下）
    const proxyIframe = document.createElement('iframe');
    proxyIframe.src = `http://a.com/proxy.html#${encodeURIComponent(JSON.stringify(result))}`;
    document.body.appendChild(proxyIframe);
  };
</script>
```

`http://a.com/proxy.html`（代理页面，与 A 同源）：
```html
<script>
  // 读取 hash 数据，传递给父页面（A）
  const hash = location.hash;
  if (window.parent !== window) {
    window.parent.parent.location.hash = hash;  // 跨两层 iframe 传给 A
  }
</script>
```

> **缺点**：
> - 实现复杂，需要三个页面配合
> - 使用轮询监听 hash，性能较差
> - 数据暴露在 URL 中，有长度限制且不安全
> - **已过时**，仅作为了解

### 3.3 window.name

**原理**：`window.name` 属性有一个特殊特性——页面跳转后它的值保持不变，且没有同源限制。利用这一特性可以实现跨域数据传递。

**代码示例**：

`http://a.com/a.html`（父页面）：
```html
<iframe id="iframe" src="http://b.com/b.html"></iframe>
<script>
  let state = 0;
  const iframe = document.getElementById('iframe');
  
  iframe.onload = function() {
    if (state === 0) {
      // 第一次加载：B 页面正在设置 window.name
      // 将 iframe 指向同源的代理页面，以便读取 name
      iframe.src = 'http://a.com/proxy.html';
      state = 1;
    } else if (state === 1) {
      // 第二次加载：现在可以读取到 window.name 了
      console.log('获取到数据:', iframe.contentWindow.name);
      // 数据使用完后清理
      iframe.contentWindow.name = '';
    }
  };
</script>
```

`http://b.com/b.html`（数据页面）：
```html
<script>
  // 将要传递的数据写入 window.name
  window.name = JSON.stringify({
    users: [
      { id: 1, name: '张三' },
      { id: 2, name: '李四' }
    ],
    total: 100
  });
</script>
```

`http://a.com/proxy.html`（空白代理页，仅用于切换同源）：
```html
<!DOCTYPE html>
<html>
<body></body>
</html>
```

> **缺点**：
> - 需要 iframe 两次加载，体验不佳
> - `window.name` 只能存储字符串，且有大小限制（约 2MB）
> - 安全性较低，其他脚本也能修改 `window.name`
> - **已过时**，建议用 `postMessage` 替代

### 3.4 postMessage（推荐）

`postMessage` 是 HTML5 引入的现代跨域通信 API，是目前**最推荐**的跨域通信方案。它安全、简洁、功能强大。

**API 说明**：

```javascript
// 发送消息
otherWindow.postMessage(message, targetOrigin, [transfer]);

/**
 * @param {any} message - 要发送的数据（会被结构化克隆算法序列化）
 * @param {string} targetOrigin - 目标窗口的源，如 'http://example.com'，'*' 表示不限制
 * @param {Transferable[]} [transfer] - 可选，可转移对象
 */

// 接收消息
window.addEventListener('message', function(event) {
  // event.source - 发送消息的窗口引用
  // event.origin - 发送消息的源（协议+域名+端口）
  // event.data - 接收到的数据
});
```

**代码示例**：

`http://a.com/parent.html`（父页面）：
```html
<iframe id="iframe" src="http://b.com/child.html"></iframe>
<script>
  const iframe = document.getElementById('iframe');
  
  // 等待 iframe 加载完成
  iframe.onload = function() {
    // 向子页面发送消息
    iframe.contentWindow.postMessage(
      { type: 'REQUEST_USER_INFO', userId: 123 },
      'http://b.com'  // 明确指定目标源，不要使用 *
    );
  };
  
  // 监听子页面的回复
  window.addEventListener('message', function(event) {
    // 必须验证消息来源！
    if (event.origin !== 'http://b.com') return;
    
    // 验证消息类型
    if (event.data.type === 'USER_INFO_RESPONSE') {
      console.log('收到用户信息:', event.data.payload);
    }
  });
</script>
```

`http://b.com/child.html`（iframe 子页面）：
```javascript
// 监听父页面的消息
window.addEventListener('message', function(event) {
  // 安全校验：验证消息来源
  if (event.origin !== 'http://a.com') {
    console.warn('收到来自未知源的消息:', event.origin);
    return;
  }
  
  const { type, userId } = event.data;
  
  if (type === 'REQUEST_USER_INFO') {
    // 处理请求
    const userInfo = getUserInfo(userId);
    
    // 回复父页面
    event.source.postMessage(
      { 
        type: 'USER_INFO_RESPONSE', 
        payload: userInfo 
      },
      event.origin  // 使用 event.origin 确保回复到正确的源
    );
  }
});

function getUserInfo(id) {
  return { id, name: '张三', email: 'zhangsan@example.com' };
}
```

**`postMessage` 安全最佳实践**：

```javascript
window.addEventListener('message', function(event) {
  // 1. 始终验证消息来源
  if (!['https://trusted-parent.com', 'https://partner.com'].includes(event.origin)) {
    return;
  }
  
  // 2. 验证数据格式（防止注入攻击）
  if (!event.data || typeof event.data !== 'object') return;
  
  // 3. 使用白名单校验消息类型
  const ALLOWED_TYPES = ['USER_INFO', 'SETTINGS', 'LOGOUT'];
  if (!ALLOWED_TYPES.includes(event.data.type)) return;
  
  // 4. 处理消息
  handleMessage(event.data, event.source, event.origin);
});
```

**各 iframe 跨域方案对比**：

| 方案 | 适用场景 | 双向通信 | 浏览器兼容性 | 推荐度 |
|:---|:---|:---|:---|:---|
| `document.domain` | 仅子域不同 | 支持 | 所有浏览器 | 逐渐淘汰 |
| `location.hash` | 任意跨域 | 支持 | 所有浏览器 | 已过时 |
| `window.name` | 任意跨域 | 单向 | 所有浏览器 | 已过时 |
| `postMessage` | 任意跨域 | 支持 | IE8+ | 强烈推荐 |

---

## 四、其他跨域解决方案

### 4.1 WebSocket

WebSocket 协议本身不受同源策略限制，它的跨域控制通过服务端在握手阶段检查 `Origin` 头部来实现。

```javascript
// 客户端
const ws = new WebSocket('wss://api.example.com/socket');

ws.onopen = () => {
  ws.send(JSON.stringify({ action: 'subscribe', channel: 'notifications' }));
};

ws.onmessage = (event) => {
  console.log('收到消息:', JSON.parse(event.data));
};

// Node.js 服务端（ws 库）
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', (ws, req) => {
  // 验证 Origin
  const origin = req.headers.origin;
  const allowedOrigins = ['https://app.example.com', 'https://admin.example.com'];
  
  if (!allowedOrigins.includes(origin)) {
    ws.close();
    return;
  }
  
  ws.on('message', (message) => {
    console.log('收到:', message.toString());
  });
});
```

### 4.2 跨域图片与 Canvas

当 Canvas 使用跨域图片时，需要设置 `crossOrigin` 属性：

```javascript
const img = new Image();
img.crossOrigin = 'anonymous';  // 或使用 'use-credentials'
img.onload = function() {
  const canvas = document.createElement('canvas');
  const ctx = canvas.getContext('2d');
  ctx.drawImage(img, 0, 0);
  
  // 如果未设置 crossOrigin，以下操作会抛出 SECURITY_ERR
  const dataURL = canvas.toDataURL();  // 导出图片
  const pixel = ctx.getImageData(0, 0, 1, 1);  // 读取像素
};
img.src = 'https://cdn.example.com/image.jpg';
```

服务端需要返回 CORS 图片头：
```
Access-Control-Allow-Origin: *
```

---

## 五、方案选择建议

### 5.1 决策流程图

```
是否需要 iframe 跨域通信？
├── 否（AJAX 请求跨域）
│   ├── 有服务端控制权？→ 使用 CORS（推荐）
│   ├── 仅开发环境？→ 配置开发服务器代理
│   ├── 生产环境无服务端权限？→ 搭建 Nginx/Node 代理
│   └── 兼容 IE9-？→ JSONP（不推荐）
│
└── 是（iframe 跨域通信）
    ├── 主域相同仅子域不同？→ document.domain 或 postMessage
    └── 完全不同域？→ postMessage（强烈推荐）
```

### 5.2 推荐方案总结

| 场景 | 首选方案 | 备选方案 |
|:---|:---|:---|
| 现代 Web 应用 API 请求 | CORS | 反向代理 |
| 前端开发调试 | DevServer Proxy | — |
| 微前端/嵌入第三方页面 | postMessage | — |
| 遗留系统维护（IE 兼容） | JSONP / Flash | — |
| 实时双向通信 | WebSocket | SSE（Server-Sent Events）|

---

## 六、安全注意事项

1. **CORS 不是安全机制**：CORS 只是浏览器的访问控制机制，不能替代身份认证和权限校验。服务端仍需验证用户身份。

2. **不要滥用 `Access-Control-Allow-Origin: ***`：在生产环境中，尽量明确指定允许的域名，尤其是涉及敏感数据或需要携带 Cookie 时。

3. **`postMessage` 必须验证 `origin`**：接收方一定要检查 `event.origin`，避免处理来自恶意网站的消息。

4. **避免使用已废弃的方案**：JSONP、`location.hash`、`window.name` 等方法存在安全风险或兼容性问题，新项目应避免使用。

5. **使用 HTTPS**：生产环境务必启用 HTTPS，防止中间人攻击篡改 CORS 头部。

---

## 参考与扩展阅读

- [MDN - 同源策略](https://developer.mozilla.org/zh-CN/docs/Web/Security/Same-origin_policy)
- [MDN - 跨域资源共享（CORS）](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/CORS)
- [MDN - Window.postMessage](https://developer.mozilla.org/zh-CN/docs/Web/API/Window/postMessage)
- [MDN - WebSocket](https://developer.mozilla.org/zh-CN/docs/Web/API/WebSocket)


---

# js中判断数据类型的方法

> **类型**：博客
> **URL**：https://nfap9.github.io/blog/js-type-check/
> **分类**：JavaScript
> **标签**：javascript, 数据类型
> **发布日期**：2024-01-15
> **描述**：介绍 JavaScript 中判断数据类型的多种方法，包括 typeof、constructor、instanceof、Object.prototype.toString 等


## 1、typeof运算符

typeof是最基本的判断数据类型的方法，它可以返回一个变量的数据类型。typeof对于基本数据类型（如字符串、数字、布尔值）非常有效，但对于引用类型（如对象、数组）就不太准确了。例如，typeof null会返回"object"，这是一个历史遗留问题。使用typeof时，需要注意这些特殊情况。

```js
console.log(typeof 123); // "number"
console.log(typeof "hello"); // "string"
console.log(typeof true); // "boolean"
console.log(typeof undefined); // "undefined"
console.log(typeof null); // "object"
console.log(typeof []); // "object"
console.log(typeof {}); // "object"
console.log(typeof function(){}); // "function"
```

## 2、constructor属性

constructor属性指向创建该对象的构造函数。
constructor属性可以被改写。

```js
const arr = [1, 2, 3];
console.log(arr.constructor === Array); // true

const obj = { name: "云牧", age: 18 };
console.log(obj.constructor === Object); // true
```