在当前的 LLM 应用开发中，我们经常陷入两个极端的场景：

1. 记性好的话痨：类似于 ChatBot，能记住上下文，聊天体验流畅，但输出全是不可控的自然语言。
2. 一次性的 API：类似于信息提取工具，能返回标准的 JSON 数据，但它是“无状态”的，每一轮调用都是全新的开始。

然而，在复杂的业务系统中，我们往往需要二者兼备：既要像人一样拥有记忆上下文的能力，又要像传统 API 一样返回严格的结构化数据（JSON）。

本文将基于 LangChain (LCEL) 体系，讲解如何将 Memory (记忆模块)  与 OutputParser (输出解析器)  结合，打造一个既懂业务逻辑又能规范输出的智能助手。

第一部分：记忆的载体 (Review)

我们在之前的工程实践中已经明确：LLM 本身是无状态的（Stateless）。为了维持对话的连续性，我们需要在应用层手动维护历史消息。

在 LangChain 中，RunnableWithMessageHistory 是实现这一功能的核心容器。它的工作原理非常直观：

1. 读取：在调用大模型前，从存储介质（Memory）中读取历史对话。
2. 注入：将历史对话填充到 Prompt 的占位符（Placeholder）中。
3. 保存：模型返回结果后，将“用户输入”和“AI 回复”追加到 Memory 中。

这是让 AI “拥有记忆”的基础设施。

第二部分：输出的规整 (The Parser)

模型原生的输出是 BaseMessage 或纯文本字符串。直接在业务代码中使用 JSON.parse() 处理模型输出是非常危险的，原因如下：

• 幻觉与废话：模型可能会在 JSON 前后添加 "Here is your JSON" 之类的自然语言。
• 格式错误：Markdown 代码块符号（```json）会破坏 JSON 结构。
• 字段缺失：模型可能忘记输出某些关键字段。

LangChain 提供了 OutputParser 组件来充当“翻译官”和“校验员”。

1. StringOutputParser

最基础的解析器。它将模型的输出（Message 对象）转换为字符串，并自动去除首尾的空白字符。这在处理简单的文本生成任务时非常有用。

2. StructuredOutputParser (重点)

这是工程化中最常用的解析器。它通常与 Zod 库结合使用，能够：

• 生成提示词：自动生成一段 Prompt，告诉模型“你需要按照这个 JSON Schema 输出”。
• 解析结果：将模型返回的文本清洗并解析为标准的 JavaScript 对象。
• 校验数据：确保返回的数据类型符合定义（如 age 必须是数字）。

第三部分：核心实战 (The Fusion)

接下来，我们将构建一个**“用户信息收集助手”**。
需求：助手与用户对话，记住用户的名字（Memory），并根据对话内容提取用户的详细信息（Parser），最终输出包含 { name, age, job } 的标准 JSON 对象。

以下是基于 LangChain LCEL 的完整实现代码：

1. 环境准备与依赖

确保安装了 @langchain/core, @langchain/deepseek, zod。

2. 代码实现

JavaScript

import { ChatDeepSeek } from "@langchain/deepseek";
import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";
import { RunnableWithMessageHistory } from "@langchain/core/runnables";
import { InMemoryChatMessageHistory } from "@langchain/core/chat_history";
import { StructuredOutputParser } from "@langchain/core/output_parsers";
import { z } from "zod";
import 'dotenv/config';

// 1. 定义输出结构 (Schema)
// 我们希望模型最终返回的数据格式
const parser = StructuredOutputParser.fromZodSchema(
  z.object({
    name: z.string().describe("用户的姓名，如果未知则为 null"),
    age: z.number().nullable().describe("用户的年龄，如果未知则为 null"),
    job: z.string().nullable().describe("用户的职业，如果未知则为 null"),
    response: z.string().describe("AI 对用户的自然语言回复")
  })
);

// 获取格式化指令，这会自动生成一段类似 "You must format your output as a JSON value..." 的文本
const formatInstructions = parser.getFormatInstructions();

// 2. 初始化模型
const model = new ChatDeepSeek({
  model: "deepseek-chat", // 使用适合对话的模型
  temperature: 0, // 设为 0 以提高结构化输出的稳定性
});

// 3. 构建 Prompt 模板
// 关键点：
// - history: 用于存放历史记忆
// - format_instructions: 用于告诉模型如何输出 JSON
const prompt = ChatPromptTemplate.fromMessages([
  ["system", "你是一个用户信息收集助手。你的目标是从对话中提取用户信息。\n{format_instructions}"],
  ["placeholder", "{history}"], // 历史消息占位符
  ["human", "{input}"]
]);

// 4. 构建处理链 (Chain)
// 数据流向：Prompt -> Model -> Parser
const chain = prompt.pipe(model).pipe(parser);

// 5. 挂载记忆模块
// 使用内存存储历史记录 (生产环境应替换为 Redis 等)
const messageHistory = new InMemoryChatMessageHistory();

const chainWithHistory = new RunnableWithMessageHistory({
  runnable: chain,
  getMessageHistory: async (sessionId) => {
    // 实际业务中应根据 sessionId 获取对应的历史记录
    return messageHistory;
  },
  inputMessagesKey: "input",
  historyMessagesKey: "history",
});

// 6. 执行与测试
async function run() {
  const sessionId = "user_session_123";

  console.log("--- 第一轮对话 ---");
  const res1 = await chainWithHistory.invoke(
    {
      input: "你好，我叫陈总，我是一名全栈工程师。",
      format_instructions: formatInstructions // 注入格式化指令
    },
    { configurable: { sessionId } }
  );
  
  // 此时 res1 已经是一个标准的 JSON 对象，而不是字符串
  console.log("解析后的输出:", res1);
  // 输出示例: { name: '陈总', age: null, job: '全栈工程师', response: '你好陈总，很高兴认识你！' }

  console.log("\n--- 第二轮对话 ---");
  const res2 = await chainWithHistory.invoke(
    {
      input: "我今年35岁了。",
      format_instructions: formatInstructions
    },
    { configurable: { sessionId } }
  );

  console.log("解析后的输出:", res2);
  // 输出示例: { name: '陈总', age: 35, job: '全栈工程师', response: '好的，记录下来了，你今年35岁。' }
}

run();

第四部分：工程化思考

在将 Memory 和 Parser 结合时，有几个关键的工程细节需要注意：

1. 数据流向与调试

在上面的代码中，数据流向是：
User Input -> Prompt Template (注入 History + Format Instructions) -> LLM -> String Output -> Output Parser -> JSON Object。

如果你发现报错，通常是因为模型没有严格遵循 formatInstructions。建议在开发阶段使用 ConsoleCallbackHandler 或 LangSmith 监控中间步骤，查看传递给模型的最终 Prompt 是否包含了正确的 JSON Schema 定义。

2. 记忆存储的内容

这是一个极其容易被忽略的点：Memory 中到底存了什么？

在 RunnableWithMessageHistory 的默认行为中，它会尝试存储 Chain 的输入和输出。

• 输入：{ input: "..." } (文本)
• 输出：经过 Parser 处理后的 JSON 对象。

当下一轮对话开始时，LangChain 会尝试将这个 JSON 对象注入到 Prompt 的 {history} 中。虽然 LangChain 会尝试将其序列化为字符串，但为了保证 Prompt 的语义清晰，建议模型生成的 response 字段专门用于维持对话上下文，而结构化数据则用于业务逻辑处理。

3. Token 消耗

引入 StructuredOutputParser 会显著增加 Prompt 的长度（因为它注入了复杂的 Schema 定义）。在多轮对话中，如果历史记录也越来越长，很容易超出上下文窗口或导致 API 费用激增。务必配合 ConversationSummaryMemory（摘要记忆）或限制历史消息条数。

结语

LangChain 的魅力在于其组件的积木式组合。通过将 RunnableWithMessageHistory（状态管理）与 StructuredOutputParser（输出规整）串联，我们将 LLM 从一个“不可控的聊天机器人”进化为了一个“有状态的业务处理单元”。

掌握这一套组合拳，是在生产环境构建复杂 AI Agent 的必经之路。

在React的江湖中，组件就像是各大门派的武林人士。有的位高权重如“父组件”，有的初出茅庐如“子组件”。在这个世界里，内功心法（数据）的传递有着森严的等级和规矩。

很多初学者在面对组件通信时，往往会被各种 Props、Callback、Context 搞得晕头转向。其实，只要搞懂了数据的流向，这套武功秘籍也就融会贯通了。

今天，我们就用一套“武林法则”，彻底拆解React中的四种核心通信方式。

一、父传子：盟主传授“单向秘籍”

这是最基础的招式。想象一下，父组件是武林盟主，手里有一本绝世武功《九阴真经》（State），他想把这套武功传给刚入门的小徒弟（子组件）。

江湖规矩：

1. 授受不亲：盟主必须亲手把秘籍递给徒弟（在子组件标签上绑定属性）。
2. 只读铁律：徒弟拿到秘籍后，只能研读修炼，绝对不能擅自涂改秘籍上的文字！如果徒弟试图修改 Props，就会走火入魔（报错）。

代码演练：

父组件（盟主）将 name 传给子组件：

JavaScript

// 父组件 Parent.jsx
import Child from "./Child";

export default function Parent() {
    const state = {
        name: '九阴真经' // 盟主手里的秘籍
    };
    return (
        <div>
            <h2>武林盟主（父组件）</h2>
            {/* 盟主发功：将秘籍打包成 msg 属性传给徒弟 */}
            <Child msg={state.name} />
        </div>
    );
}

子组件（徒弟）接收秘籍，谨记只读：

JavaScript

// 子组件 Child.jsx
export default function Child(props) {
    // props.msg = '葵花宝典'; // 错误示范：徒弟不能擅自篡改秘籍，否则报错！
    
    return (
        <div>
            {/* 徒弟展示学到的招式 */}
            <h3>入室弟子（子组件）-- 习得：{props.msg}</h3>
        </div>
    );
}

核心心法：Props 是只读（Read-Only）的。数据流向是从上至下的单向流动，这保证了数据源的纯净和可追溯。

二、子传父：徒弟呈递“飞鸽传书”

有时候，青出于蓝而胜于蓝。徒弟（子组件）自己悟出了一套新招式（State），想要上报给盟主（父组件）。但江湖规矩森严，徒弟不能直接把招式塞进盟主的脑子里。

江湖规矩：

1. 锦囊妙计：盟主需要先给徒弟一个“空锦囊”（函数）。
2. 装入招式：徒弟在适当时机，把自己的新招式装进锦囊（调用函数并传参）。
3. 飞鸽回传：锦囊一旦封好，就会自动飞回盟主手中，盟主打开锦囊，更新自己的内力（setState）。

代码演练：

父组件准备“锦囊”（函数）：

JavaScript

// 父组件 Parent.jsx
import { useState } from "react";
import Child from "./Child";

export default function Parent() {
    const [count, setCount] = useState(0);

    // 定义锦囊：这是一个用来接收徒弟数据的函数
    const receiveMove = (n) => {
        setCount(n); // 盟主收到招式后，更新自己的内力
    }

    return (
        <div>
            <h2>盟主内力值：{count}</h2>
            {/* 把锦囊（函数）传给徒弟 */}
            <Child getNum={receiveMove} />
        </div>
    );
}

子组件使用“锦囊”回传数据：

JavaScript

// 子组件 Child.jsx
export default function Child(props) {
    const state = {
        num: 100 // 徒弟自创的新招式
    };

    function send() {
        // 关键一步：调用父组件给的函数，把数据作为参数传回去
        props.getNum(state.num);
    }

    return (
        <div>
            <h3>入室弟子</h3>
            <button onClick={send}>飞鸽传书给盟主</button>
        </div>
    )
}

核心心法：React 中没有直接的“子传父”语法，本质是父组件将函数作为 Props 传递给子组件，子组件执行该函数。

三、兄弟组件：盟主充当“中间人”

现在有两个徒弟：大师兄（Child1）和二师弟（Child2）。大师兄想把自己的内力传给二师弟，怎么办？他们之间没有直接的经脉相连（无直接通信渠道）。

江湖规矩：

1. 中转站：必须由师父（父组件）出面。
2. 状态提升：大师兄先把内力传给师父（子传父），师父收到后，再把内力传给二师弟（父传子）。

这在武学中被称为“移花接木”，在 React 中叫状态提升（Lifting State Up） 。

代码演练：

父组件作为枢纽：

JavaScript

// 父组件 Parent.jsx
import { useState } from "react";
import Child1 from "./Child1";
import Child2 from "./Child2";

export default function Parent() {
    const [message, setMessage] = useState("等待传功...");

    // 接收大师兄数据的锦囊
    const getFromChild1 = (msg) => {
        setMessage(msg);
    }

    return (
        <div>
            <h2>武林盟主（中转站）</h2>
            {/* 接收端：把函数给大师兄 */}
            <Child1 transfer={getFromChild1} />
            {/* 发送端：把收到的数据给二师弟 */}
            <Child2 msg={message} />
        </div>
    )
}

大师兄（发送方）：

JavaScript

// Child1.jsx
export default function Child1(props) {
    const energy = "混元霹雳手"; 
    return (
        <div>
            <button onClick={() => props.transfer(energy)}>
                大师兄：发送内力
            </button>
        </div>
    )
}

二师弟（接收方）：

JavaScript

// Child2.jsx
export default function Child2(props) {
    return (
        <div>
            {/* 展示从师父那里转交过来的大师兄的内力 */}
            <h3>二师弟：接收到的招式 -- {props.msg}</h3>
        </div>
    )
}

核心心法：兄弟不分家，全靠父当家。遇到兄弟通信，先找共同的父组件，把状态提升上去。

四、跨组件通信：狮子吼“全域广播”

如果门派等级森严，盟主要把消息传给徒弟的徒弟的徒弟（孙组件、重孙组件），一层层传 Props 实在是太慢了，而且容易出错（Prop Drilling）。

这时候，盟主会使用绝学“千里传音”或“狮子吼”（Context API）。

江湖规矩：

1. 建立广播台：使用 createContext 创建一个信号塔。
2. 发功（Provider） ：盟主在高处使用 Provider 发出信号，笼罩在信号范围内的所有后代。
3. 接收（Consumer/useContext） ：任何层级的徒子徒孙，只要有 useContext 这个接收器，就能直接听到盟主的声音，无需中间人转述。

代码演练：

建立广播台（Context）：

JavaScript

// Context.js
import { createContext } from 'react';
export const SectContext = createContext(); // 创建门派广播台

父组件发功：

JavaScript

// Parent.jsx
import { SectContext } from './Context';
import Child from "./Child";

export default function Parent() {
    return (
        <SectContext.Provider value={'武林至尊，宝刀屠龙'}>
            <div>
                <h2>盟主发出狮子吼</h2>
                <Child /> {/* 子组件内部包裹着孙组件 */}
            </div>
        </SectContext.Provider>
    );
}

孙组件（无需经过子组件）直接接收：

JavaScript

// Grandson.jsx
import { useContext } from 'react';
import { SectContext } from './Context';

export default function Grandson() {
    // 越级接收：直接获取上下文中的数据
    const secret = useContext(SectContext);
    
    return (
        <div>
            <h4>徒孙接收到的广播：{secret}</h4>
        </div>
    );
}

核心心法：Context 能够打破组件层级的限制，实现数据的“隔空传送”，非常适合处理主题颜色、用户登录状态等全局数据。

五、结语：武功谱总结

React 的组件通信，归根结底就是数据流向的管理。不要死记硬背代码，要理解数据是从哪里来，要到哪里去。

最后，附上一份“武功谱”供各位少侠修炼参考：

愿各位在 React 的江湖中，内功深厚，Bug 不侵！

前言

众所周知，code agent 是无法判断出生成的代码是否正确的。也就是只有生成环节，没有验证环节，所以需要我们一点点做 debug，这也是很多人最开始不看好 ai 的原因。

但反过来想，是不是解决了验证环节，ai 的体验就会获得大幅提升呢。

锁定问题

要想解决验证环节，可以先思考我们是如何做 debug 的。

对于前端，一般而言都是先安装依赖，看看代码有没有爆红。然后运行，看项目是否能正常启动，最后打开页面和控制台，点一点看哪里有问题。

拆解来看，其实分为了几个问题：

• 是否能正常安装依赖
• 代码是否直接在编辑器就出现了错误（静态检测/开发时错误）
• 项目是否能正常启动（构建时错误）
• 控制台是否报错（运行时错误）

所以，我们的目标是依次解决这些问题。

解决方案

能否正常安装依赖

这一步其实相对简单，运行 npm i 就行了。需要注意的点有：

1. npm 安装依赖存在不少问题，它使用扁平化所有依赖，并逐个进行下载的做法，这可能会导致幽灵依赖（能引用到没安装 package.json 的部分包），安装缓慢（内存存储双爆炸），依赖冲突（子依赖使用了不同版本）等问题。为了解决这些问题，pnpm 出现了，目前大部分前端项目都会优先考虑使用 pnpm
2. 关于锁文件的问题

真正决定安装版本的是锁文件，其生成依赖于 package.json。但不要手动修改锁文件。

安装会有很多种情况

情况1：当有锁文件，且与 package.json 中包一致时，执行安装，会完全按照锁文件进行安装，这是最常见且最安全的情况。

情况2：当有锁文件，且与 package.json 中包不一致（比如手动在 package.json 中更新了包），执行安装，锁文件会更新有变化的部分。锁文件更新后，后续再进行安装就会进入到情况1

情况3：当没有锁文件，执行安装依赖时，会按 package.json 里的依赖

• 精确版本号时，会选择精确版本（"axios": "1.5.0" 会安装 1.5.0）
• 有 ^ 时，允许小版本自动更新（"axios": "^1.5.0" 会选择最新且小于 2.0.0 的版本）
• 有 ~ 时，允许小特性自动更新（"axios": "~1.5.0" 会安装最新且小于 1.6.0 的版本）

根据这些规则，会选择出所有适合的包，生成锁文件，接着进入情况1，使后续该项目使用的包稳定，不会出现突然升级的问题。

暂时无法在昆仑万维文档外展示此内容

最佳实践：安装/更新新依赖，最好还是走命令行

npm i xxx // 安装
npm i xxx@latest // 更新最新版，也可以指定版本如 xxx@1.0.0

这样能自动同时更新 package.json 和锁文件，且不影响其他包。

退而求其次，是手动修改 package.json，随后再进行 npm i 重新安装，这样也能让锁文件进行更新，

如果单独修改 package.json 文件，可能是无效的，比如：package.json 中 "axios": "^1.5.0"，lock 中 1.5.2，此时你将 package.json 的 ^1.5.0 改为 ^1.5.1，由于 lock 中的 1.5.2 仍符合^1.5.1，所以是无事发生，不会产生任何更新。

是否直接在编辑器就出现了错误

ai 的很多错误，其实在前端通常都能很直接的看到，如下：

这里的报错其实有两个原因：eslint 报错与 ts 报错

我们可以通过这两个命令扫描出对应的错误：

npx eslint ./
npx tsc --noEmit -p tsconfig.app.json --strict

我们可以在对应的文件中，配置对应的规则集，eslint 的配置位于 eslint.config.js 中；ts 的配置位于 tsconfig.app.json。

严格的规则，有助于 ai 生成产物的稳定，更不容易出现白屏报错等问题，但相对的时间会更长，因为要解决更多 error。宽松的规则，则对应 token 的减少，时间更快。

在我们的项目中，使用了默认的规则集，基本上就够用了，不过有几个模型经常报错、但不影响主流程的，我们还是降低为了 warn，从而规避修复所需要花费的成本。

"@typescript-eslint/no-unused-vars": "warn", // 未使用变量降为 warn
"@typescript-eslint/no-empty-object-type": "warn", // 空对象类型降为 warn
"@typescript-eslint/no-explicit-any": "warn", // any 类型降为 warn，这个可能还有待商榷，过多的使用 any 本质上就是忽略报错

项目是否能正常启动

在大部分情况下，如果前两个步骤是正确的，最后一步 build 大概率不会有问题。即使有问题，模型也能在 build 后也能看到构建报错，从而直接进行修复。

如果想要验证也简单，跑一个构建命令就行了

npm run build

控制台是否报错

前面三个环节，都可以用命令行进行验证和 debug，也就是 agent 有办法感知到。但控制台的报错，属于运行时错误，很难报给 agent，所以我们需要设计一套上报机制来解决这个问题。

也就是这个需求 【Websites】增加手动Debug模式，简单来说，就是控制台的所有报错都暴露出来发给 agent

要实现这点，关键在于拦截所有报错，我们来看常见的报错，逐个进行解决。

1. 普通 js 同步报错，也是最常见的一种，语法问题等引起

解法：可以用 window.onerror 进行回调处理

2. promise reject 未处理报错，类似 try catch 问题

解法：可以使用 window.addEventListener("unhandledrejection", event => {}) 来做回调处理

3. 接口报错 / 资源加载失败

虽然严格意义上，不算代码的问题，但是也有必要让 agent 感知到

解法：通信使用 axios 包，并且在其响应拦截器中做处理，如果不是 200，则进行 error 回调

主要的报错就这三种，我们可以基于此封装一套错误抛出的机制。不过 github 实际上有现成的更完备的库，可以考虑直接使用 Sentry 来做这件事。sentry 本身是用于错误上报的，不过我们可以将其拦截掉，在 callback 中只执行我们的逻辑即可。

  Sentry.init({
    dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0', // 使用假 DSN 来启用错误捕获功能
    enabled: true, // 启用 Sentry
    attachStacktrace: true, // 附加堆栈跟踪
    
    // 在发送前处理错误
    beforeSend(event, hint) {
      const error = hint.originalException || hint.syntheticException
      dosomething(error, event)
      // 返回 null 阻止实际上报到 Sentry
      return null
    },
  })

当你的模版中接入了这套流程后，你就可以将错误向 agent 抛出了，比如说：

1. skywork 中，产物是在 iframe 里，那么我们可以利用 postMessage 将错误反馈到主应用，从而在输入框中引用到错误并发送给 agent

2. 如果产物完全独立，可以考虑将错误打到接口中，之后的通信让 agent 先去访问这些错误，修复后再做操作

总结

所以最终这个机制有以下几个部分构成：

1. 安装、更新依赖时走命令行（且最好使用 pnpm 而非 npm）

npm i xxx // 安装
npm i xxx@latest // 更新最新版，也可以指定版本如 xxx@1.0.0

2. build 前先扫描错误并修复（要使用 typescript 而非 js，要接入 eslint）

npx eslint ./
npx tsc --noEmit -p tsconfig.app.json --strict

3. 跑 build 看有没有问题

npm run build

4. 在模版中接入运行时错误监控，并将监控的结果传递给 agent

  Sentry.init({
    dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0', // 使用假 DSN 来启用错误捕获功能
    enabled: true, // 启用 Sentry
    attachStacktrace: true, // 附加堆栈跟踪
    
    // 在发送前处理错误
    beforeSend(event, hint) {
      const error = hint.originalException || hint.syntheticException
      dosomething(error, event) // 自定义实现
      // 返回 null 阻止实际上报到 Sentry
      return null
    },
  })
  

一、环境准备

后端采用Python + FastApi，Redis和MySQL都在云服务器上，通过docker安装的，向外暴露接口实现的远程连接。

服务部署

前面介绍过fastapi的基本语法，但是缺了部署这个环节，在这里补充下。

我的安装环境都是在阿里云的云服务器上，采用的是pm2来管理fastapi项目，首先在centos上安装相关依赖和环境：

# 1. 更新系统
sudo yum update -y

# 2. 安装 EPEL 源（Python 虚拟环境需要）
sudo yum install -y epel-release

# 3. 安装 Python3 和 pip
sudo yum install -y python3 python3-pip python3-venv python3-wheel

# 确认 Python 安装
python3 -V
pip3 -V

# 4. 安装 Node.js (使用官方源安装最新 LTS)
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs

# 确认 Node 和 npm 安装
node -v
npm -v

# 5. 安装 PM2 全局
sudo npm install -g pm2
pm2 -v

准备测试脚本：

首先准备下虚拟环境：

python3 -m venv venv

venv\Scripts\activate

新建main.py

from datetime import datetime

from fastapi import FastAPI, HTTPException, Query
import pymysql


app = FastAPI(title="Simple MySQL Query Service")


def get_connection() -> pymysql.connections.Connection:
    """创建并返回一个 MySQL 连接。"""

    return pymysql.connect(
        host="118.31.xxx",
        port=3307,
        user="root",
        password="xxx",
        database="blog",
        cursorclass=pymysql.cursors.DictCursor,
        charset="utf8mb4",
    )


@app.get("/hello")
async def hello():
    """返回 你好 + 当前时间（年月日 时分秒）。"""

    now = datetime.now()
    current_time = now.strftime("%Y年%m月%d日 %H:%M:%S")
    return {"message": f"你好，当前时间是：{current_time}"}


@app.get("/student_score")
async def get_student_score(number: str = Query(..., description="学生编号")):
    """根据 number 查询 blog 库中 student_score 表的 subject 和 score。"""

    try:
        conn = get_connection()
        with conn:
            with conn.cursor() as cursor:
                sql = (
                    "SELECT subject, score "
                    "FROM student_score "
                    "WHERE number = %s"
                )
                cursor.execute(sql, (number,))
                rows = cursor.fetchall()
    except pymysql.MySQLError as exc:  # 数据库连接或执行出错
        detail = (
            exc.args[1]
            if len(exc.args) > 1
            else str(exc)
        )
        raise HTTPException(status_code=500, detail=f"数据库错误: {detail}") from exc

    if not rows:
        raise HTTPException(status_code=404, detail="未找到该 number 对应的成绩")

    return {"number": number, "results": rows}


if __name__ == "__main__":
    import uvicorn

    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

本地运行下python mian.py，然后测试下我们的接口，看来是没问题的。就着手开始部署到线上。

新建Gunicorn配置文件gunicorn_config.py：

bind = "0.0.0.0:8011"          # 对外端口
workers = 2                    # worker 数量，看 CPU 调整
worker_class = "uvicorn.workers.UvicornWorker"
timeout = 60
accesslog = "logs/access.log"
errorlog = "logs/error.log"
loglevel = "info"

开始新建项目依赖requirements.txt

fastapi
uvicorn[standard]
pymysql

同时我的nginx的代理转发的配置文件，是这样的

location /fastapi/query/ {
        proxy_pass http://127.0.0.1:8011/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
    }

接下来将项目文件压缩成zip包，拖到服务器的指定目录，运行unzip query.zip解压即可。

然后开始安装依赖：

首先开启虚拟环境：
python3 -m venv venv
source venv/bin/activate

然后安装依赖
pip install -r requirements.txt

这一步可能安装巨慢，建议切换阿里云的下载链接

这里巨坑，折腾了我一个多小时，阿里云的python版本默认是3.6.8，使用Gunicorn需要3.10以上的，一开始安装依赖一直卡住了，也不报错，换了好几个源，还是不行，我以为我服务器带宽小导致的，换成本地安装，然后拖到服务器上，这才发现是版本的原因，然后安装3.11.9后删除虚拟环境，重新安装才成功。

安装成功后，就可以啦。

测试下：运行gunicorn -c gunicorn_config.py main:app，在开启一个服务器连接，

输入：
curl "http://127.0.0.1:8011/hello"
{"message":"你好，当前时间是：2026年02月08日 15:38:53"}[root@iZbp1f9urggte5qz3ri1riZ ~]# 
curl "http://127.0.0.1:8011/student_score?number=20180101"
{"number":"20180101","results":[{"subject":"母猪的产后护理","score":78},{"subject":"论萨达姆的战争准备","score":88}]}[root@iZbp1f9urg

可以看到我们的服务器已经正常运行了，二级域名已经解析了，nginx代理也已经配置了，

输入curl http://api.jinxudong.com/fastapi/query/hello可以看到正常的接口输出的，说明我们的脚本已经部署成功了，但是这种部署方式还是比较原始的，而且后续服务肯定不止这个一个，我打算采用pm2来管理这些服务。

在项目的根目录写上配置文件ecosystem.config.js

module.exports = {
  apps: [
    {
      name: "query",
      script: "bash",
      args: "-c '/var/www/python/query/venv/bin/gunicorn -c gunicorn_config.py main:app'",
      cwd: "/var/www/python/query"
    }
  ]
};

运行脚本pm2 start ecosystem.config.js就可以看到我们的服务了，在设置下开机自启：

pm2 save
pm2 startup

我们的服务已经正常部署到线上啦，可以通过域名去访问

https://api.jinxudong.com/fastapi/query/student_score?number=20180101

{"number":"20180101","results":[{"subject":"母猪的产后护理","score":78},{"subject":"论萨达姆的战争准备","score":88}]}

压测工具介绍

一个系统上线后，是必须要经过压测的，就是模拟大量用户同时访问服务，找到系统的极限QPS，极限并发，找出性能瓶颈，避免线上事故。

接下来介绍两个常见的压测工具：

1. ab

   这是Apache自带的压测工具，非常的简轻量，很适合小接口测试，做下简单的性能验证。

   首先安装下这个工具

   yum install httpd-tools
   

   使用也很简单

   ab -n 1000 -c 50 https://api.jinxudong.com/fastapi/query/student_score?number=20180101
   

   用50的并发完成1000次请求，看下ab的输出日志

   Server Software:        nginx/1.20.1
   Server Hostname:        api.jinxudong.com
   Server Port:            443
   SSL/TLS Protocol:       TLSv1.2,ECDHE-RSA-AES256-GCM-SHA384,2048,256
   Server Temp Key:        X25519 253 bits
   TLS Server Name:        api.jinxudong.com
   
   Document Path:          /fastapi/query/student_score?number=20180101
   Document Length:        133 bytes
   
   Concurrency Level:      50
   Time taken for tests:   17.659 seconds
   Complete requests:      1000
   Failed requests:        0
   Total transferred:      283000 bytes
   HTML transferred:       133000 bytes
   Requests per second:    56.63 [#/sec] (mean)
   Time per request:       882.956 [ms] (mean)
   Time per request:       17.659 [ms] (mean, across all concurrent requests)
   Transfer rate:          15.65 [Kbytes/sec] received
   
   Connection Times (ms)
                 min  mean[+/-sd] median   max
   Connect:       11   56 119.1     13    1471
   Processing:    32  810 212.6    807    1854
   Waiting:       30  810 212.6    806    1854
   Total:         48  866 258.9    828    2290
   
   Percentage of the requests served within a certain time (ms)
     50%    828
     66%    911
     75%    998
     80%   1041
     90%   1195
     95%   1295
     98%   1559
     99%   1798
    100%   2290 (longest request)
   

   看下几个核心指标

   1. Request per second，也就是常说的QPS，也就是每秒可以处理56个请求

   2. Time per request，平均响应时间

      Time per request:       882.956 [ms] (mean)
      Time per request:       17.659 [ms] (mean, across all concurrent requests)
      

      第一个时间单个请求平均耗时，这是用户真实的体验时间，第二个时间是平均耗时/并发数

   3. 延迟分布

      Percentage of the requests served within a certain time (ms)
        50%    828
        66%    911
        75%    998
        80%   1041
        90%   1195
        95%   1295
        98%   1559
        99%   1798
       100%   2290 (longest request)
      

      第一个数字是百分比，第二个是耗时，换成表格是这样

      百分位	含义
      P50	50%请求 < 828ms
      P90	90%请求 < 1195ms
      P95	95%请求 < 1295ms
      P99	99%请求 < 1798ms
      max	最慢请求 2290ms

   4. 连接时间分析

      Connection Times (ms)
                    min  mean[+/-sd] median   max
      Connect:       11   56 119.1     13    1471
      Processing:    32  810 212.6    807    1854
      Waiting:       30  810 212.6    806    1854
      Total:         48  866 258.9    828    2290
      

      这里的Connect就是TCP握手简历链接的时间，Processing就是后端处理的时间

2. wrk

wrk目前是后端常用的压测工具，支持多线程和Lua脚本，可以模拟真实并发。

首先在服务器上安装下

#先安装编译工具
sudo yum groupinstall "Development Tools" -y
sudo yum install git -y
#下载
curl -L -o wrk.zip https://codeload.github.com/wg/wrk/zip/refs/heads/master
unzip wrk.zip
cd wrk-master

#编译
make

#复制到全局路径
sudo cp wrk /usr/local/bin/

安装成功以后，直接测试：

wrk -t4 -c100 -d30s --latency https://api.jinxudong.com/fastapi/query/student_score?number=20180101

意思就是四个线程，100的并发，测试30秒

  4 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     1.18s    66.72ms   1.42s    96.70%
    Req/Sec    36.35     26.08   100.00     54.00%
  Latency Distribution
     50%    1.18s 
     75%    1.19s 
     90%    1.20s 
     99%    1.23s 
  2483 requests in 30.07s, 698.34KB read
Requests/sec:     82.58
Transfer/sec:     23.22KB

可以看到，Requests/sec就是吞吐量82，每秒可以处理82个请求，平均延迟1.23秒，

压测还是比较简单的，就是利用工具查看qps和延迟时间，当qps不涨，延迟时间飞涨甚至于报错，那说明就到达极限了。

下面就开始实战环节了。

二、信息查询系统

这是一个查询商品信息的系统，就是查询商品详情，为了增加系统的吞吐量，常见的做法就是增加一个缓存层，流程就是：请求接口来了，先去查询redis缓存层，缓存命中就直接返回；如果未命中再去查库。这也是前面介绍的旁路缓存，用内存换取数据库压力。

系统架构图如下

客户端 (浏览器/APP)
        |
        v
    FastAPI 接口层
        |
    -----------------
    |               |
Redis 缓存         MySQL 数据库

环境准备

数据库设计

CREATE TABLE products (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(255) NOT NULL,
    price DECIMAL(10,2) NOT NULL,
    stock INT NOT NULL,
    description TEXT,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

id 是主键

name, price, stock, description 是商品核心信息

updated_at 商品的更新时间，可以用于后面缓存过期策略（缓存失效时刷新）

然后插入一些测试数据

INSERT INTO products (name, price, stock, description)
SELECT
    CONCAT('商品-', t.num),
    ROUND(RAND() * 500 + 10, 2),
    FLOOR(RAND() * 100),
    CONCAT('这是商品 ', t.num, ' 的描述')
FROM (
    SELECT a.n + b.n * 10 + c.n * 100 + 1 AS num
    FROM
        (SELECT 0 n UNION SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 4
         UNION SELECT 5 UNION SELECT 6 UNION SELECT 7 UNION SELECT 8 UNION SELECT 9) a,
        (SELECT 0 n UNION SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 4
         UNION SELECT 5 UNION SELECT 6 UNION SELECT 7 UNION SELECT 8 UNION SELECT 9) b,
        (SELECT 0 n UNION SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 4
         UNION SELECT 5 UNION SELECT 6 UNION SELECT 7 UNION SELECT 8 UNION SELECT 9) c
) t
WHERE t.num <= 1000;

准备工作已经就绪，接下来开始编写代码啦

系统编写

代码也比较简单，就是一个查询接口，和前面是实例基本一致

@app.get("/get_product")
async def get_product(id: int = Query(..., description="商品编号")):
    """根据商品 id 查询商品信息。"""
    try:
        conn = get_connection()
        with conn:
            with conn.cursor() as cursor:
                sql = (
                    "SELECT * "
                    "FROM products "
                    "WHERE id = %s"
                )
                cursor.execute(sql, (id,))
                rows = cursor.fetchall()
    except pymysql.MySQLError as exc:  # 数据库连接或执行出错
        detail = (
            exc.args[1]
            if len(exc.args) > 1
            else str(exc)
        )
        raise HTTPException(status_code=500, detail=f"数据库错误: {detail}") from exc

    if not rows:
        raise HTTPException(status_code=404, detail="未找到该 id 对应的商品信息")

    return {"id": id, "results": rows}


if __name__ == "__main__":
    import uvicorn

    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

然后运行python main.py，http://localhost:8000/get_product?id=22是可以看到数据返回的。

说明我们的代码是没问题的，接下来就开始部署，然后再服务器上做压测，看下当前的服务器的最大QPS是多大。

部署方案和前面介绍的一致，记得更改nginx配置和pm2的配置文件，通过公网访问下我们的接口

https://api.jinxudong.com/fastapi/queryDetail/get_product?id=122
可以看到如下输出：
{
  "id": 122,
  "results": [
    {
      "id": 122,
      "name": "商品-172",
      "price": 461.79,
      "stock": 72,
      "description": "这是商品 172 的描述",
      "updated_at": "2026-02-10T04:13:17"
    }
  ]
}

说明接口已经部署成功了，下面就开始压测，要知道这个接口的最大QPS，接下来使用ab来开始压测

第一次压测

首先使用20的并发，看下压测报告：

ab -n 1000 -c 20 https://api.jinxudong.com/fastapi/queryDetail/get_product?id=122

压测报告截取：
Requests per second:    54.99 [#/sec] (mean)  
Time per request:       363.704 [ms] (mean)  
50%    307ms
75%    417ms
90%    512ms
99%   1282ms

可以看到QPS54，平均时间363ms，延迟分布中50%的请求小于307ms

第二次压测

使用40的并发，看下压测报告：

ab -n 1000 -c 40 https://api.jinxudong.com/fastapi/queryDetail/get_product?id=122
 
压测报告截取：
Requests per second:    53.87 [#/sec] (mean)
Time per request:       742.486 [ms] (mean)
  50%    712
  66%    769
  75%    826
  80%    850
  90%    926

QPS53，延迟时间和平均请求时间都在增大，有一种步子迈大了的感觉，减少并发试试

第三次压测

使用10的并发，看下压测报告

 ab -n 1000 -c 10 https://api.jinxudong.com/fastapi/queryDetail/get_product?id=122
 
 压测报告截取：
 Requests per second:    55.53 [#/sec] (mean)
Time per request:       180.081 [ms] (mean)
  50%    135
  66%    154
  75%    173
  80%    181
  90%    332

QPS55，平均时间和延迟时间都降低了，但是QPS确实没怎么变化，可以断定当前系统的最大吞吐量就是55，下面增加一个缓存层，然后看下系统的吞吐量是否发生变化

存增加缓存层

首先回顾下旁路缓存，当查询时首先去缓存中查找，如果缓存命中就直接返回；如果未命中就去查询数据库，然后将值写到缓存中，如果数据库也没有，就写一个空值到缓存中，防止穿透。这就是下面要写的代码的逻辑。

直接看下接口代码

@app.get("/get_product")
async def get_product(id: int = Query(..., description="商品编号")):
    """根据商品 id 查询商品信息。"""

    cache_key = _make_product_cache_key(id)

    # 1. 先查 Redis 缓存
    try:
        cached = redis_client.get(cache_key)
        if cached is not None:
            rows = json.loads(cached)
            # 缓存命中空列表，说明数据库也没有，直接返回 404，防止缓存穿透
            if not rows:
                raise HTTPException(status_code=404, detail="未找到该 id 对应的商品信息")
            return {"id": id, "results": rows}
    except redis.RedisError:
        # 缓存异常时，降级为直接查数据库
        pass

    try:
        conn = get_connection()
        with conn:
            with conn.cursor() as cursor:
                sql = (
                    "SELECT * "
                    "FROM products "
                    "WHERE id = %s"
                )
                cursor.execute(sql, (id,))
                rows = cursor.fetchall()
    except pymysql.MySQLError as exc:  # 数据库连接或执行出错
        detail = (
            exc.args[1]
            if len(exc.args) > 1
            else str(exc)
        )
        raise HTTPException(status_code=500, detail=f"数据库错误: {detail}") from exc

    if not rows:
        # 数据库未命中，也写入空列表到缓存，防止穿透
        try:
            redis_client.setex(cache_key, 60, json.dumps([]))
        except redis.RedisError:
            pass
        raise HTTPException(status_code=404, detail="未找到该 id 对应的商品信息")

    # 查询到数据后写入缓存
    try:
        encoded_rows = jsonable_encoder(rows)
        redis_client.setex(cache_key, 300, json.dumps(encoded_rows, ensure_ascii=False))
    except (redis.RedisError, TypeError, ValueError):
        # 缓存写入失败不影响接口主流程
        pass

    return {"id": id, "results": rows}

首先在接口请求时，一开始就构建了缓存的key，_make_product_cache_key的方法是这样的

def _make_product_cache_key(product_id: int) -> str:
    """生成商品缓存 key。"""

    return f"product:{product_id}"

构建的key就是product:{product_id}，然后就先查询缓存，如果缓存命中就直接返回，未命中就查库；命中时也有个非空判断，如果是写入的空数组，表明是数据库也没有的，直接返回404，防止穿透。查询数据库就是和前面一样的逻辑了，加了个写入缓存的逻辑：redis_client.setex(cache_key, 300, json.dumps(encoded_rows, ensure_ascii=False))。当数据库也没有时，就写个空，防止穿透：redis_client.setex(cache_key, 60, json.dumps([]))，然后返回错误。

部署到线上后，https://api.jinxudong.com/fastapi/queryDetail/get_product?id=5接口有正常的返回，看下redis数据库，也有相关的product:5作为key，表明我们的更改是成功的。

要想证明我们的更改效果，就需要做压测了，

第一次压测

直接使用40的并发

ab -n 1000 -c 40 https://api.jinxudong.com/fastapi/queryDetail/get_product?id=122

Requests per second: 73.80 [#/sec] (mean) 
Time per request: 542.007 [ms] (mean)

我以为这个QPS会变得非常大，才是73，而没加redis是53，我查看了redis数据库，缓存是存在的，虽然说QPS增加了，但是并不是很明显，看来影响系统的吞吐量的并不只是查询数据库，还有TCP连接，因为这个接口多了一层nginx转发，

第二次压测

这次不走nginx转发了，直接走系统的服务

ab -n 1000 -c 40 http://127.0.0.1:8012/get_product?id=122

Requests per second:    365.20 [#/sec] (mean)
Time per request:       109.528 [ms] (mean)

QPS一下子就起来了，而且平均响应时间也降低了。

两次测试结果有点出乎意料，都说redis毫秒级别的响应，但是QPS并没有指数级别的上升，看来对于小型应用，提升QPS来说，redis的作用其实并没有那么大，我的服务器宽带只有2M，费这么大劲，还不如去增加点带宽效果来的明显。

The git revert command creates a new commit that undoes the changes introduced by a specified commit. Unlike git reset , which rewrites the commit history, git revert preserves the full history and is the safe way to undo changes that have already been pushed to a shared repository.

This guide explains how to use git revert to undo one or more commits with practical examples.

Quick Reference #

Syntax #

The general syntax for the git revert command is:

git revert [OPTIONS] COMMIT

• OPTIONS — Flags that modify the behavior of the command.
• COMMIT — The commit hash or reference to revert.

git revert vs git reset #

Before diving into examples, it is important to understand the difference between git revert and git reset, as they serve different purposes:

• git revert — Creates a new commit that undoes the changes from a previous commit. The original commit remains in the history. This is safe to use on branches that have been pushed to a remote repository.
• git reset — Moves the HEAD pointer backward, effectively removing commits from the history. This rewrites the commit history and should not be used on shared branches without coordinating with your team.

As a general rule, use git revert for commits that have already been pushed, and git reset for local commits that have not been shared.

Reverting the Last Commit #

To revert the most recent commit, run git revert followed by HEAD:

git revert HEAD

Git will open your default text editor so you can edit the revert commit message. The default message looks like this:

Revert "Original commit message"

This reverts commit abc1234def5678...

Save and close the editor to complete the revert. Git will create a new commit that reverses the changes from the last commit.

To verify the revert, use git log to see the new revert commit in the history:

git log --oneline -3

a1b2c3d (HEAD -> main) Revert "Add new feature"
f4e5d6c Add new feature
b7a8c9d Update configuration

The original commit (f4e5d6c) remains in the history, and the new revert commit (a1b2c3d) undoes its changes.

Reverting a Specific Commit #

You do not have to revert the most recent commit. You can revert any commit in the history by specifying its commit hash.

First, find the commit hash using git log:

git log --oneline

a1b2c3d (HEAD -> main) Update README
f4e5d6c Add login feature
b7a8c9d Fix navigation bug
e0f1a2b Add search functionality

To revert the “Fix navigation bug” commit, pass its hash to git revert:

git revert b7a8c9d

Git will create a new commit that undoes only the changes introduced in commit b7a8c9d, leaving all other commits intact.

Reverting Without Opening an Editor #

If you want to use the default revert commit message without opening an editor, use the --no-edit option:

git revert --no-edit HEAD

[main d5e6f7a] Revert "Add new feature"
2 files changed, 0 insertions(+), 15 deletions(-)

This is useful when scripting or when you do not need a custom commit message.

Reverting Without Committing #

By default, git revert automatically creates a new commit. If you want to stage the reverted changes without committing them, use the --no-commit (or -n) option:

git revert --no-commit HEAD

The changes will be applied to the working directory and staging area, but no commit is created. You can then review the changes, make additional modifications, and commit manually:

git status
git commit -m "Revert feature and clean up related code"

This is useful when you want to combine the revert with other changes in a single commit.

Reverting Multiple Commits #

Reverting a Range of Commits #

To revert a range of consecutive commits, specify the range using the .. notation:

git revert --no-commit HEAD~3..HEAD

This reverts the last three commits. The --no-commit option stages all the reverted changes without creating individual revert commits, allowing you to commit them as a single revert:

git commit -m "Revert last three commits"

Without --no-commit, Git will create a separate revert commit for each commit in the range.

Reverting Multiple Individual Commits #

To revert multiple specific (non-consecutive) commits, list them one after another:

git revert --no-commit abc1234 def5678 ghi9012
git commit -m "Revert selected commits"

Reverting a Merge Commit #

Merge commits have two parent commits, so Git needs to know which parent to revert to. Use the -m option followed by the parent number (usually 1 for the branch you merged into):

git revert -m 1 MERGE_COMMIT_HASH

In the following example, we revert a merge commit and keep the main branch as the base:

git revert -m 1 a1b2c3d

• -m 1 — Tells Git to use the first parent (the branch the merge was made into, typically main or master) as the base.
• -m 2 — Would use the second parent (the branch that was merged in).

You can check the parents of a merge commit using:

git log --oneline --graph

Handling Conflicts During Revert #

If the code has changed since the original commit, Git may encounter conflicts when applying the revert. When this happens, Git will pause the revert and show conflicting files:

CONFLICT (content): Merge conflict in src/app.js
error: could not revert abc1234... Add new feature
hint: After resolving the conflicts, mark the corrected paths
hint: with 'git add <paths>' and run 'git revert --continue'.

To resolve the conflict:

1. Open the conflicting files and resolve the merge conflicts manually.

2. Stage the resolved files:

   Terminal

   git add src/app.js

3. Continue the revert:

   Terminal

   git revert --continue

If you decide not to proceed with the revert, you can abort it:

git revert --abort

This restores the repository to the state before you started the revert.

Pushing a Revert to a Remote Repository #

Since git revert creates a new commit rather than rewriting history, you can safely push it to a shared repository using a regular push:

git push origin main

There is no need for --force because the commit history is not rewritten.

Common Options #

The git revert command accepts several options:

• --no-edit — Use the default commit message without opening an editor.
• --no-commit (-n) — Apply the revert to the working directory and index without creating a commit.
• -m parent-number — Specify which parent to use when reverting a merge commit (usually 1).
• --abort — Cancel the revert operation and return to the pre-revert state.
• --continue — Continue the revert after resolving conflicts.
• --skip — Skip the current commit and continue reverting the rest.

Troubleshooting #

Revert is in progress
If you see a message that a revert is in progress, either continue with git revert --continue after resolving conflicts or cancel with git revert --abort.

Revert skips a commit
If Git reports that a commit was skipped because it was already applied, it means the changes are already present. You can proceed or use git revert --skip to continue.

FAQ #

What is the difference between git revert and git reset?
git revert creates a new commit that undoes changes while preserving the full commit history. git reset moves the HEAD pointer backward and can remove commits from the history. Use git revert for shared branches and git reset for local, unpushed changes.

Can I revert a commit that has already been pushed?
Yes. This is exactly what git revert is designed for. Since it creates a new commit rather than rewriting history, it is safe to push to shared repositories without disrupting other collaborators.

How do I revert a merge commit?
Use the -m option to specify the parent number. For example, git revert -m 1 MERGE_HASH reverts the merge and keeps the first parent (usually the main branch) as the base.

Can I undo a git revert?
Yes. Since a revert is just a regular commit, you can revert the revert commit itself: git revert REVERT_COMMIT_HASH. This effectively re-applies the original changes.

What happens if there are conflicts during a revert?
Git will pause the revert and mark the conflicting files. You need to resolve the conflicts manually, stage the files with git add, and then run git revert --continue to complete the operation.

Conclusion #

The git revert command is the safest way to undo changes in a Git repository, especially for commits that have already been pushed. It creates a new commit that reverses the specified changes while keeping the full commit history intact.

If you have any questions, feel free to leave a comment below.

日期: 2025-02-10
影响范围: 主应用 apps/main、共享包 packages/ui、所有子应用

一、现状诊断

1.1 样式文件分布（主应用）

当前主应用存在 3 个互不关联的样式目录，没有统一入口：

apps/main/src/
├── assets/
│   ├── main.css              ← Vue 脚手架残留 + Tailwind 入口
│   ├── base.css              ← Vue 脚手架残留 CSS Reset + 变量
│   └── styles/
│       └── micro-app.css     ← 微前端"隔离"样式（!important 硬覆盖）
├── styles/
│   ├── index.scss            ← 样式入口（⚠️ 从未被任何文件引用！）
│   ├── var.css               ← 布局 + 主题 CSS 变量
│   ├── dark.css              ← 暗色主题变量
│   ├── resizeStyle.scss      ← 632 行巨型文件（EP 覆盖 + 布局 + 业务混杂）
│   ├── dialog.scss           ← 弹窗尺寸
│   ├── theme.scss            ← 空文件（全注释）
│   ├── variables.scss        ← 仅 2 个 SCSS 变量
│   └── global.module.scss    ← 导出命名空间给 JS

1.2 main.ts 样式导入链

main.ts
  ├── assets/main.css           → @import base.css + @import tailwindcss
  ├── assets/styles/micro-app.css
  ├── element-plus 组件样式 ×4（message-box / message / notification / loading）
  └── @cmclink/ui/styles        → variables + element-override + base + utilities + animations + tailwindcss

关键发现：styles/index.scss（包含 var.css、resizeStyle.scss、dialog.scss）在整个项目中没有被任何文件 import。这意味着 632 行的 Element Plus 覆盖样式、布局变量、暗色主题等可能完全没有生效，或者曾经生效但在某次重构中被遗漏。

1.3 核心问题清单

1.4 @cmclink/ui 样式包分析

packages/ui/src/styles/ 已经有一套相对完整的设计体系：

• variables.scss — 完整的设计令牌（颜色、字体、间距、圆角、阴影等）+ CSS 变量映射
• mixins.scss — 响应式断点、文本截断、布局、按钮变体等混合器
• base.scss — 全局 reset、标题、段落、表格、滚动条、打印、暗色、无障碍
• element-override.scss — Element Plus 样式覆盖
• utilities.scss — CMC 专用工具类（cmc-* 前缀）
• animations.scss — 动画库（1250 行，含大量与 Tailwind 重复的工具类）

问题：@cmclink/ui 的 animations.scss 中有大量 .translate-*、.scale-*、.rotate-*、.duration-* 等类名，与 Tailwind CSS 完全重复。

二、目标架构设计

2.1 设计原则

1. 单一真相源（Single Source of Truth）：设计令牌只在 @cmclink/ui 中定义一次
2. 分层隔离：全局样式、主题变量、EP 覆盖、布局样式、业务样式严格分层
3. 微前端天然隔离：依赖 wujie 的 CSS 沙箱（WebComponent + iframe），而非 !important
4. Tailwind 唯一入口：整个主应用只在一个地方引入 Tailwind CSS
5. 可维护性：每个文件职责单一，命名语义化，新人 5 分钟能理解结构

2.2 目标目录结构

apps/main/src/
├── styles/                          ← 主应用样式唯一目录
│   ├── index.scss                   ← ⭐ 唯一入口文件（main.ts 只 import 这一个）
│   ├── tailwind.css                 ← Tailwind CSS 唯一引入点
│   │
│   ├── tokens/                      ← 主应用级设计令牌（覆盖/扩展 @cmclink/ui）
│   │   ├── _variables.scss          ← SCSS 变量（供 SCSS 文件内部使用）
│   │   └── _css-variables.scss      ← CSS 自定义属性（布局变量、主应用专属变量）
│   │
│   ├── themes/                      ← 主题系统
│   │   ├── _light.scss              ← 亮色主题变量
│   │   └── _dark.scss               ← 暗色主题变量
│   │
│   ├── overrides/                   ← Element Plus 样式覆盖（主应用级）
│   │   ├── _button.scss             ← 按钮覆盖
│   │   ├── _table.scss              ← 表格覆盖
│   │   ├── _form.scss               ← 表单覆盖（filterBox 等）
│   │   ├── _dialog.scss             ← 弹窗覆盖
│   │   ├── _message-box.scss        ← 消息框覆盖
│   │   ├── _select.scss             ← 下拉框覆盖
│   │   ├── _tag.scss                ← 标签覆盖
│   │   ├── _tabs.scss               ← 标签页覆盖
│   │   └── _index.scss              ← EP 覆盖汇总入口
│   │
│   ├── layout/                      ← 布局样式
│   │   ├── _app-view.scss           ← AppViewContent / AppViewScroll
│   │   ├── _login.scss              ← 登录页样式
│   │   └── _index.scss              ← 布局汇总入口
│   │
│   ├── vendors/                     ← 第三方库样式适配
│   │   └── _nprogress.scss          ← NProgress 主题色适配
│   │
│   └── legacy/                      ← 遗留业务样式（逐步迁移到组件 scoped 中）
│       ├── _si-detail.scss          ← 出口单证详情
│       ├── _marketing.scss          ← 营销模块
│       └── _index.scss              ← 遗留样式汇总入口
│
├── assets/                          ← 仅保留静态资源
│   └── images/                      ← 图片资源
│       ├── avatar.gif
│       ├── cmc-logo.png
│       └── ...

2.3 入口文件设计

styles/index.scss（唯一入口）：

// =============================================================================
// CMCLink 主应用样式入口
// 加载顺序严格按照优先级排列，请勿随意调整
// =============================================================================

// 1️⃣ Tailwind CSS（最先加载，作为基础原子类层）
@use './tailwind.css';

// 2️⃣ 主应用级设计令牌（覆盖/扩展 @cmclink/ui 的变量）
@use './tokens/css-variables';

// 3️⃣ 主题系统
@use './themes/light';
@use './themes/dark';

// 4️⃣ Element Plus 样式覆盖
@use './overrides/index';

// 5️⃣ 布局样式
@use './layout/index';

// 6️⃣ 第三方库适配
@use './vendors/nprogress';

// 7️⃣ 遗留业务样式（逐步清理）
@use './legacy/index';

main.ts（重构后）：

// 样式：唯一入口
import './styles/index.scss'

// Element Plus 反馈组件样式（非按需导入的全局组件）
import 'element-plus/es/components/message-box/style/css'
import 'element-plus/es/components/message/style/css'
import 'element-plus/es/components/notification/style/css'
import 'element-plus/es/components/loading/style/css'

// 组件库样式（@cmclink/ui 提供设计令牌 + 基础样式 + EP 覆盖）
import '@cmclink/ui/styles'

// 其余保持不变...

注意：@cmclink/ui/styles 中的 Tailwind CSS 引入需要移除，改为只在主应用的 styles/tailwind.css 中引入一次。

2.4 样式加载顺序

┌─────────────────────────────────────────────────────────┐
│ 1. Tailwind CSS（原子类基础层）                           │
├─────────────────────────────────────────────────────────┤
│ 2. @cmclink/ui/styles                                   │
│    ├── variables.scss  → 设计令牌 + CSS 变量映射          │
│    ├── base.scss       → 全局 reset + 排版               │
│    ├── element-override.scss → 组件库级 EP 覆盖           │
│    ├── utilities.scss  → CMC 工具类                       │
│    └── animations.scss → 动画（需清理与 Tailwind 重复部分）│
├─────────────────────────────────────────────────────────┤
│ 3. Element Plus 反馈组件样式（message/notification 等）    │
├─────────────────────────────────────────────────────────┤
│ 4. 主应用 styles/index.scss                              │
│    ├── tokens/    → 主应用级变量（布局尺寸、主题色扩展）    │
│    ├── themes/    → 亮色/暗色主题                         │
│    ├── overrides/ → 主应用级 EP 覆盖                      │
│    ├── layout/    → 页面布局                              │
│    ├── vendors/   → 第三方库适配                          │
│    └── legacy/    → 遗留业务样式                          │
├─────────────────────────────────────────────────────────┤
│ 5. 组件 <style scoped>（组件级样式，天然隔离）             │
└─────────────────────────────────────────────────────────┘

三、微前端样式隔离策略

3.1 wujie CSS 沙箱机制

wujie 使用 WebComponent（shadowDOM）+ iframe 双重沙箱：

• JS 沙箱：子应用 JS 运行在 iframe 中，天然隔离
• CSS 沙箱：子应用 DOM 渲染在 WebComponent 的 shadowDOM 中，样式天然隔离

这意味着：

• ✅ 子应用的样式不会泄漏到主应用
• ✅ 主应用的样式不会侵入子应用（shadowDOM 边界）
• ⚠️ 但是：Element Plus 的弹窗（Dialog/Drawer/MessageBox）默认挂载到 document.body，会逃逸出 shadowDOM

3.2 弹窗逃逸问题的正确解决方案

当前做法（错误）：在主应用 micro-app.css 中用 !important 覆盖子应用弹窗样式。

正确做法：在子应用中配置 Element Plus 的 teleported 和 append-to 属性，让弹窗挂载到子应用自身的 DOM 容器内，而非 document.body。

方案 A：子应用全局配置（推荐）

在子应用的入口文件中配置 Element Plus 的全局属性：

// 子应用 main.ts
import { createApp } from 'vue'
import ElementPlus from 'element-plus'

const app = createApp(App)
app.use(ElementPlus, {
  // 弹窗不使用 teleport，保持在子应用 DOM 树内
  // 这样弹窗样式就在 shadowDOM 内，天然隔离
})

同时在子应用的弹窗组件中统一设置：

<!-- 子应用中使用 Dialog -->
<el-dialog :teleported="false">
  <!-- 内容 -->
</el-dialog>

<!-- 或者指定挂载到子应用容器 -->
<el-dialog append-to=".child-app-root">
  <!-- 内容 -->
</el-dialog>

方案 B：wujie 插件拦截（自动化）

通过 wujie 的插件系统，自动为子应用的弹窗组件注入配置：

// plugins/wujie.ts 中增加插件配置
import { setupApp } from 'wujie'

setupApp({
  name: 'child-app',
  // ... 其他配置
  plugins: [
    {
      // CSS loader：可以在子应用 CSS 加载时做处理
      cssLoader: (code: string) => code,
      // JS loader：可以在子应用 JS 加载时做处理
      jsLoader: (code: string) => code,
    }
  ]
})

方案 C：共享样式包（兜底方案）

如果确实需要主应用和子应用共享某些样式（如统一的弹窗规范），应该通过 @cmclink/ui 包来分发，而非在主应用中硬写覆盖：

packages/ui/src/styles/
├── shared/                    ← 可被子应用独立引入的共享样式
│   ├── dialog-standard.scss   ← 弹窗标准样式
│   └── form-standard.scss     ← 表单标准样式

子应用按需引入：

// 子应用 main.ts
import '@cmclink/ui/styles/shared/dialog-standard.scss'

3.3 样式隔离总结

3.4 删除 micro-app.css

重构完成后，assets/styles/micro-app.css 应该被完全删除。其中的内容处理方式：

四、主色统一方案

4.1 现状：三处主色定义

4.2 统一方案

以 @cmclink/ui 的设计令牌为唯一真相源。

1. 确认最终主色值（与设计团队对齐）：

   • 如果设计稿是 #004889 → 主应用的 var.css 需要同步修改
   • 如果设计稿是 #005aae → @cmclink/ui 的 variables.scss 需要同步修改

2. 主应用中所有硬编码的颜色值，改为引用 CSS 变量：

   // ❌ 错误
   background-color: #005aae;
   
   // ✅ 正确
   background-color: var(--el-color-primary);
   

3. 主应用的 tokens/_css-variables.scss 只定义布局相关的变量，颜色变量全部继承 @cmclink/ui。

五、文件迁移映射

5.1 需要删除的文件

5.2 需要拆分的文件

styles/var.css（154 行）→ 拆分为：

styles/resizeStyle.scss（632 行）→ 拆分为：

styles/index.scss（126 行）→ 拆分为：

styles/dark.css（85 行）→ 迁移到：

styles/dialog.scss（17 行）→ 迁移到：

5.3 @cmclink/ui 需要调整的部分

六、实施步骤

Phase 1：基础清理（低风险，可立即执行）

预计耗时：1-2 小时

1. 创建新目录结构

   • 创建 styles/tokens/、styles/themes/、styles/overrides/、styles/layout/、styles/vendors/、styles/legacy/

2. 创建 styles/tailwind.css

   @import "tailwindcss";
   

3. 删除废文件

   • styles/theme.scss（空文件）

4. 统一主色

   • 与设计团队确认最终主色值
   • 更新所有硬编码颜色为 CSS 变量引用

Phase 2：文件拆分迁移（中风险，需逐步验证）

预计耗时：3-4 小时

1. 拆分 resizeStyle.scss（632 行 → 8 个文件）
2. 拆分 var.css（布局变量 → tokens/_css-variables.scss）
3. 迁移 dark.css → themes/_dark.scss
4. 迁移 dialog.scss → overrides/_dialog.scss
5. 拆分 index.scss（NProgress → vendors，业务 → legacy）
6. 创建新的 styles/index.scss 入口文件

Phase 3：入口重构（高风险，需完整回归测试）

预计耗时：1-2 小时

1. 修改 main.ts

   • 移除 import './assets/main.css'
   • 移除 import './assets/styles/micro-app.css'
   • 添加 import './styles/index.scss'
   • 调整 @cmclink/ui/styles 的导入顺序

2. 删除旧文件

   • assets/main.css
   • assets/base.css
   • assets/styles/micro-app.css
   • assets/styles/ 目录

3. 完整回归测试

   • 登录页样式
   • 主布局（侧边栏、顶部导航、标签页）
   • 表格页面（筛选框、表格、分页）
   • 弹窗/抽屉
   • 暗色主题切换
   • 子应用加载和样式隔离

Phase 4：微前端隔离优化（需子应用配合）

预计耗时：2-3 小时（每个子应用）

1. 子应用配置弹窗不逃逸

   • 全局配置 :teleported="false" 或 append-to
   • 在 @cmclink/micro-bootstrap 中提供统一配置能力

2. 删除 micro-app.css

3. 验证子应用样式隔离

   • 主应用样式不侵入子应用
   • 子应用样式不泄漏到主应用
   • 弹窗/抽屉样式正确

Phase 5：@cmclink/ui 优化（独立进行）

预计耗时：2-3 小时

1. 移除 Tailwind CSS 引入（从 @cmclink/ui/styles/index.scss）
2. 清理 animations.scss 中与 Tailwind 重复的工具类（约 800 行）
3. 审查 utilities.scss 中与 Tailwind 重复的部分

七、风险评估与回退方案

7.1 风险点

7.2 回退方案

每个 Phase 独立提交 Git，如果出现问题可以精确回退到任意阶段：

feat(styles): phase-1 基础清理和目录结构
feat(styles): phase-2 文件拆分迁移
feat(styles): phase-3 入口重构
feat(styles): phase-4 微前端隔离优化
feat(styles): phase-5 @cmclink/ui 优化

八、验证清单

8.1 样式正确性

• 登录页样式正常（背景、表单、按钮）
• 主布局样式正常（侧边栏展开/收起、顶部导航、面包屑）
• 标签页样式正常（激活态、hover、关闭按钮）
• 表格页面样式正常（筛选框、表头、行、分页）
• 弹窗/抽屉样式正常（大/中/小尺寸）
• 表单样式正常（输入框、下拉框、日期选择器）
• 按钮样式正常（主要、链接、危险、禁用）
• NProgress 进度条颜色正确
• 暗色主题切换正常

8.2 微前端隔离

• 子应用加载后样式正常
• 主应用样式未侵入子应用
• 子应用样式未泄漏到主应用
• 子应用弹窗样式正确（不逃逸到主应用 body）
• 多个子应用切换时样式无残留

8.3 构建产物

• 构建无报错
• CSS 产物体积不增长（预期减少 30%+）
• 无重复的 Tailwind CSS 输出
• 无重复的 CSS Reset

8.4 开发体验

• HMR 样式热更新正常
• 新增样式时知道该放在哪个文件
• SCSS 变量和 CSS 变量可正常引用

九、预期收益

setState

语法：

this.setState(updater, [callback])

写法总结：

// 语法：this.setState({ newState })
this.setState({ count: 1 });

// 推荐使用，尤其是状态更新依赖于前一次状态时。它可以接收当前 state 和 props
// 语法：this.setState((state, props) => { return { newState } })
this.setState((state, props) => ({
  count: state.count + 1
}));

// 在 setState 更新完成并重新渲染界面后执行，可确保获取到最新状态
this.setState({ count: 1 }, () => {
  console.log('更新后的状态:', this.state.count);
});

特性：

• setState 是异步的：React 会将多个 setState 调用合并（batch）成一次更新，以提升性能。
• 在事件处理函数（如 onClick）中，setState 是批量的。
• 在原生事件、setTimeout、Promise 等异步上下文中，setState 可能不会自动批处理（但在 React 18+ 中已改进），可能表现为`同步状态。

⚠️ 注意：React 18 开始，无论在哪里调用 setState，默认都会自动批处理（automatic batching）。

底层原理（React 16+ Fiber 架构）

• 调用 setState 会触发 enqueueSetState。
• React 将更新放入一个更新队列（Update Queue） ，并标记该 Fiber 节点为“需要更新”。
• 在渲染阶段（render phase） ，React 会遍历 Fiber 树，收集所有待更新的节点。
• 在提交阶段（commit phase） ，应用 DOM 更新并触发副作用（如生命周期方法）。

关键点：setState 并不立即修改 this.state，而是创建一个更新对象（update object），由 React 调度器（Scheduler）决定何时处理。

useState

它允许你向组件添加一个 状态变量，语法：

const [state, setState] = useState(initialState)

• 参考

  • useState(initialState)
  • set 函数，例如 setSomething(nextState)

它没有回调函数；

特性：

• 和 setState 一样，useState 的 setXXX 也是异步且批量更新的。
• React 18 后，在任何上下文中（包括 setTimeout）都会自动批处理。

底层原理（Hooks 机制）

• useState 是 React Hooks 的一部分，其状态存储在 Fiber 节点的 memoizedState 字段中。

• 每个 Hook（如 useState, useEffect）在 Fiber 节点上按调用顺序形成一个链表（Hook 链表） 。

• 调用 setCount 时，React 会：

  1. 创建一个更新对象（类似类组件的 update）。
  2. 将其加入对应 Hook 的更新队列。
  3. 触发组件重新渲染（schedule update）。

• 在下一次渲染时，React 会遍历 Hook 链表，应用所有 pending updates，计算出新的 state。

📌 关键：Hooks 的状态与组件实例绑定，通过 Fiber 节点维持状态，而不是像类组件那样通过 this.state。

setState vs useState 对比

💡 注意：useState 不会自动合并对象！

底层共通机制（React 18+）

无论是 setState 还是 useState，最终都依赖于：

1. Fiber 架构：每个组件对应一个 Fiber 节点，状态和更新都挂载其上。
2. 更新队列（Update Queue） ：存放待处理的状态变更。
3. 调度器（Scheduler） ：基于优先级（如用户交互高优先级）决定何时执行更新。
4. 协调（Reconciliation） ：通过 diff 算法生成最小 DOM 操作。
5. 自动批处理（Automatic Batching） ：React 18 起，所有状态更新默认批处理。

问题背景

在页面中，用户可以通过表格中的开关（Switch）组件快速切换计划的启用/禁用状态。系统的预期行为是：

• 点击第一行的开关从"开启"切换到"关闭"
• 立即点击第二行的开关从"关闭"切换到"开启"
• 预期结果：第一行变关闭，第二行变开启

但实际发生的问题是：两行的开关状态会变成一样，要么都变成开启，要么都变成关闭。

问题现象

这个问题在刷新页面后首次操作时必现，尤其是在以下场景：

1. 用户快速连续点击多行的状态开关
2. 点击第一行后，在接口请求还未返回时，立即点击第二行
3. 两个请求基本同时发出

技术实现（错误版本）

原始代码

// src/page/UpgradePlan/index.js

const [appList, setAppList] = useState([]) // 表格数据列表

/**
 * 处理计划状态变更
 * @param {object} record - 当前行数据
 * @param {string} newStatus - 新状态值 ('ACTIVE' 或 'INACTIVE')
 */
const handlePlanStatusChange = (record, newStatus) => {
  // ❌ 问题代码：基于闭包捕获的 appList
  const updatedList = appList.map(item => {
    if (item.planId === record.planId) {
      return {
        ...item,
        planStatus: newStatus,
      }
    }
    return item
  })
  setAppList(updatedList)
}

表格状态渲染

// src/page/UpgradePlan/UpgradePlanTable.js

const columns = [
  {
    title: '计划状态',
    width: 100,
    dataIndex: 'planStatus',
    fixed: 'left',
    render: (text, record) => {
      return (
        <Switch
          checked={text === 'ACTIVE' ? true : false}
          checkedChildren="开启"
          unCheckedChildren="关闭"
          loading={loadingPlanIds.has(record.planId)}
          onChange={checked => {
            handlePlanStatusChange(checked, record, text)
          }}
        />
      )
    },
  },
  // ... 其他列
]

问题根源分析

1. 闭包陷阱

这是一个经典的 React 状态闭包问题：

// ❌ 每次 handlePlanStatusChange 执行时，appList 都是被闭包捕获的"旧值"
const handlePlanStatusChange = (record, newStatus) => {
  const updatedList = appList.map(item => {  // appList 来自闭包，可能已过时
    if (item.planId === record.planId) {
      return { ...item, planStatus: newStatus }
    }
    return item
  })
  setAppList(updatedList)
}

2. 执行流程演示

假设初始状态：

appList = [
  { planId: 1, planStatus: 'ACTIVE' },   // 第一行：开启
  { planId: 2, planStatus: 'INACTIVE' }  // 第二行：关闭
]

快速点击两行的执行流程：

时刻 T0: 初始 appList = [{id:1, status:'ACTIVE'}, {id:2, status:'INACTIVE'}]

时刻 T1: 用户点击第一行开关 (ACTIVE → INACTIVE)
         └─ 调用 handlePlanStatusChange(record1, 'INACTIVE')
         └─ 函数内捕获的 appList 仍是 T0 时刻的值
         └─ updatedList = [{id:1, status:'INACTIVE'}, {id:2, status:'INACTIVE'}]
         └─ setAppList(updatedList)  // 开始异步更新

时刻 T2: 用户立即点击第二行开关 (INACTIVE → ACTIVE)  [此时第一个更新还未完成]
         └─ 调用 handlePlanStatusChange(record2, 'ACTIVE')
         └─ 函数内捕获的 appList 仍是 T0 时刻的值 ⚠️ 关键问题！
         └─ updatedList = [{id:1, status:'ACTIVE'}, {id:2, status:'ACTIVE'}]
         └─ setAppList(updatedList)  // 这个更新会覆盖 T1 的更新

时刻 T3: React 处理状态更新
         └─ 第二个 setAppList 覆盖了第一个
         └─ 最终结果：[{id:1, status:'ACTIVE'}, {id:2, status:'ACTIVE'}]
         └─ ❌ 第一行的状态变更丢失了！

3. 问题本质

• 闭包捕获过时值：handlePlanStatusChange 函数体内的 appList 是在函数定义时捕获的，不是执行时的最新值
• 异步状态更新：两个 setAppList 调用都会加入 React 的更新队列，但都基于同一时刻的旧状态快照
• 后者覆盖前者：第二个 setAppList 执行时，会用包含过时数据的 updatedList 覆盖第一个的更新

改正措施

解决方案：使用函数式状态更新

// ✅ 改正后的代码

/**
 * 处理计划状态变更
 * @param {object} record - 当前行数据
 * @param {string} newStatus - 新状态值
 */
const handlePlanStatusChange = (record, newStatus) => {
  // ✅ 使用函数式更新，prevAppList 始终是最新的状态
  setAppList(prevAppList => {
    return prevAppList.map(item => {
      if (item.planId === record.planId) {
        return {
          ...item,
          planStatus: newStatus,
        }
      }
      return item
    })
  })
}

改正后的执行流程

时刻 T0: 初始 appList = [{id:1, status:'ACTIVE'}, {id:2, status:'INACTIVE'}]

时刻 T1: 用户点击第一行开关 (ACTIVE → INACTIVE)
         └─ 调用 setAppList(prevAppList => {...})
         └─ prevAppList = T0 时刻的值
         └─ updatedList = [{id:1, status:'INACTIVE'}, {id:2, status:'INACTIVE'}]
         └─ 加入更新队列

时刻 T2: 用户立即点击第二行开关 (INACTIVE → ACTIVE)
         └─ 调用 setAppList(prevAppList => {...})
         └─ ⚠️ 但此时 prevAppList = T1 更新后的值！
         └─ prevAppList = [{id:1, status:'INACTIVE'}, {id:2, status:'INACTIVE'}]
         └─ 只更新 id:2，保留 id:1 的状态
         └─ updatedList = [{id:1, status:'INACTIVE'}, {id:2, status:'ACTIVE'}]
         └─ 加入更新队列

时刻 T3: React 处理状态更新（批处理）
         └─ 先执行 T1 的更新
         └─ 再执行 T2 的更新（基于 T1 的结果）
         └─ 最终结果：[{id:1, status:'INACTIVE'}, {id:2, status:'ACTIVE'}]
         └─ ✅ 两行状态都正确！

关键区别对比

❌ 错误方式：直接访问闭包变量

const handlePlanStatusChange = (record, newStatus) => {
  // appList 是闭包捕获的，在快速连续调用时是同一时刻的值
  const updatedList = appList.map(...)
  setAppList(updatedList)
}

问题：

• 多次快速调用时，所有调用都基于同一时刻的 appList
• 后面的调用会覆盖前面的结果
• 状态变更会丢失

✅ 正确方式：函数式状态更新

const handlePlanStatusChange = (record, newStatus) => {
  // prevAppList 参数由 React 提供，始终是最新的状态
  setAppList(prevAppList => {
    return prevAppList.map(...)
  })
}

优势：

• React 保证每次调用时，prevAppList 都是最新的状态
• 多次快速调用时，每次都基于前一次更新的结果
• 状态更新会正确链式执行
• 充分利用 React 的批处理机制

深入理解

React 状态更新的本质

React 的状态更新机制：

// React 内部维护的更新队列
const updateQueue = []

// 当调用 setAppList(newValue) 时
setAppList(newValue) 
  // React 会加入队列
  updateQueue.push({ type: 'direct', value: newValue })

// 当调用 setAppList(prevValue => newValue) 时
setAppList(prevValue => newValue)
  // React 会记录更新函数，并在需要时执行
  updateQueue.push({ type: 'function', fn: (prevValue) => newValue })

批处理时：

// ❌ 直接值更新（会被覆盖）
setAppList(value1)  // → queue: [{ type: 'direct', value: value1 }]
setAppList(value2)  // → queue: [{ type: 'direct', value: value2 }] 覆盖前一个
// 最终结果：只有 value2 生效

// ✅ 函数式更新（会链式执行）
setAppList(prev => newValue1(prev))  // → queue: [fn1]
setAppList(prev => newValue2(prev))  // → queue: [fn1, fn2]
// 执行：fn1(initialState) → state1
//     fn2(state1) → state2
// 最终结果：两个更新都生效

应用场景

这个问题常见于以下场景：

1. 列表行操作：快速切换表格中多行的状态
2. 表单快速提交：连续提交多个表单项
3. 购物车操作：快速添加/删除多个商品
4. 批量操作：连续执行多个列表项的操作

总结

核心要点

最佳实践

在 React 中更新状态时，如果新状态依赖于旧状态，始终使用函数式更新：

// ✅ 推荐写法（避免闭包陷阱）
setState(prevState => {
  return {
    ...prevState,
    // 基于 prevState 的更新
  }
})

// ❌ 避免（容易踩坑）
setState({
  ...state,
  // 基于当前 state 的更新
})

参考资源

• React 官方文档 - 函数式更新
• JavaScript 闭包 - MDN
• React 批处理机制

教训： 在 React 中处理依赖于前一状态的更新时，永远优先考虑使用函数式状态更新，这是避免闭包陷阱最直接有效的方法。

DeepSeek-OCR-2 开源 OCR 模型的技术

OCR应用的场景和类型很广，本次使用Qwen2的架构，解决看的全（扫码方式优化）、看的的准（内容识别、视觉标记、降低重复率），多裁剪策略提取核心信息。和其他OCR模型项目还是看自己的引用场景，通用场景还是建议使用最新的模型，识别准、理解准、排版准。

2025-2026年，OCR（光学字符识别）领域迎来了开源大模型的黄金时代。继 DeepSeek 在自然语言处理领域掀起波澜之后，其于 2026 年 1 月 27 日开源的 DeepSeek-OCR-2 再次引发行业关注。几乎同期，腾讯也在 2025 年底开源了 HunyuanOCR（混元OCR）——一个仅 1B 参数却斩获多项 SOTA 的轻量级模型。

这两款模型代表了当前开源 OCR 技术的两大发展方向：DeepSeek-OCR-2 主打视觉因果流（Visual Causal Flow）的创新架构，而 HunyuanOCR 则以极致轻量化+端到端统一见长。本文将深入分析这两款模型的技术特点，并与 PaddleOCR、Qwen-VL、GOT-OCR2.0 等主流方案进行对比，帮助开发者理解各模型的适用场景。

一、DeepSeek-OCR-2：视觉因果流的革新

1.1 核心创新：DeepEncoder V2

DeepSeek-OCR-2 最引人注目的创新在于其 DeepEncoder V2 视觉编码器。传统 OCR 模型（包括大多数 VLM）采用固定的栅格扫描方式（从左到右、从上到下）处理图像，这种方式与人类阅读习惯相悖，尤其在处理复杂版面（如多栏文档、表格、图文混排）时容易产生逻辑错误。

DeepEncoder V2 引入了**视觉因果流（Visual Causal Flow）**机制：

• 全局理解优先：模型首先建立对整页文档的全局语义理解
• 语义驱动阅读顺序：根据内容逻辑动态确定处理顺序，而非机械扫描
• 类人类阅读模式：能够正确处理多栏排版、表格单元格关联、图文穿插等复杂场景

技术亮点：DeepEncoder V2 采用轻量级 LLM 架构（基于 Qwen2-0.5B）替换了传统的 CLIP 视觉编码器，配合双流注意力机制——视觉 token 使用双向注意力提取全局特征，文本生成使用因果注意力保证阅读顺序合理性。

1.2 模型规格与性能

动态分辨率配置：

• 默认方案：(0-6)×768×768 + 1×1024×1024
• Token 数：(0-6)×144 + 256

1.3 核心能力

1. 复杂版面解析：在表格、多栏文档、公式混排等场景表现出色
2. Markdown/结构化输出：支持将文档直接转换为带格式的 Markdown
3. 多语言支持：基于 DeepSeek 的多语言优势，支持主流语种
4. 推理加速：支持 vLLM 和 Transformers 两种推理方式

二、HunyuanOCR：轻量级全能选手

2.1 端到端一体化设计

腾讯 HunyuanOCR 采用端到端训推一体架构，这是其与传统 OCR 系统的根本差异：

传统 OCR 流水线：

图像 → 版面分析 → 文本检测 → 文本识别 → 后处理 → 输出

HunyuanOCR 端到端流程：

图像 → 单次推理 → 直接输出结构化结果

这种设计彻底消除了级联误差累积问题，同时大幅简化了部署流程。

2.2 架构组成

XD-RoPE（扩展相对位置编码） 是 HunyuanOCR 的关键创新，它使模型能够：

• 理解跨栏排版的逻辑关系
• 处理跨页文档的长距离依赖
• 保持复杂表格的行列对应关系

2.3 性能表现

三、技术对比：DeepSeek-OCR-2 vs HunyuanOCR

3.1 关键差异解读

1. 阅读顺序理解

DeepSeek-OCR-2 的 Visual Causal Flow 在处理非线性阅读顺序的文档时具有理论优势，例如：

• 报纸版面（多栏穿插）
• 学术论文（图表与正文引用关系）
• 复杂表格（跨行跨列单元格）

HunyuanOCR 则通过 XD-RoPE 在位置关系建模上达到类似效果，实测在 OmniDocBench 上取得更高分数。

2. 部署与成本

HunyuanOCR 的 1B 参数设计明显瞄准边缘部署场景，20GB 显存即可运行，适合：

• 中小企业私有化部署
• 移动端/嵌入式设备
• 高并发 API 服务

DeepSeek-OCR-2 的 3B 参数提供更强的语义理解能力，适合：

• 复杂文档的深度解析
• 需要上下文压缩降本的大规模文档处理
• 与 LLM 配合的多模态 RAG 系统

3. 功能覆盖

HunyuanOCR 功能更全面，内置：

• 拍照翻译（14 种语言互译）
• 视频字幕提取
• 开放字段信息抽取（JSON 输出）

DeepSeek-OCR-2 更专注于文档到结构化文本的转换，强调与下游 LLM 的协同。

四、与其他主流 OCR 方案的对比

4.1 PaddleOCR：工业级成熟方案

对比结论：PaddleOCR 适合需要精细控制和低资源占用的传统 OCR 任务，而 DeepSeek-OCR-2 和 HunyuanOCR 更适合需要端到端理解复杂文档的场景。

4.2 GOT-OCR2.0：学术界的统一模型

对比结论：GOT-OCR2.0 与 DeepSeek-OCR-2 理念相近，但后者在视觉编码器创新和工程化（vLLM 支持）方面更进一步。

4.3 Qwen2-VL：通义千问多模态

对比结论：Qwen2-VL 是"通用选手"，OCR 只是其能力之一；DeepSeek-OCR-2 和 HunyuanOCR 是"OCR 专家"，在文档解析专项上更精专。

4.4 综合对比表

五、选型建议：如何选择适合你的 OCR 方案

5.1 按应用场景选择

5.2 按技术栈选择

如果你的系统已经基于 vLLM：

• DeepSeek-OCR-2 和 HunyuanOCR 都提供原生 vLLM 支持，集成成本低

如果你需要与现有 CV 流水线集成：

• PaddleOCR 提供更细粒度的模块化控制

如果你正在构建 LLM 应用（如知识库问答）：

• DeepSeek-OCR-2 的上下文压缩特性可以显著降低文档预处理成本

六、总结与展望

DeepSeek-OCR-2 和 HunyuanOCR 的开源，标志着 OCR 技术进入了一个新的阶段——从传统的"字符识别"进化为"文档理解"。

核心趋势

1. 端到端统一：告别检测→识别→后处理的级联流水线，单次推理直接输出结构化结果
2. 轻量高效：1B-3B 参数即可达到商业级精度，降低部署门槛
3. 复杂版面理解：不再局限于简单的文字识别，而是理解文档的逻辑结构和阅读顺序
4. 多模态融合：OCR 与翻译、问答、信息抽取等功能深度融合

技术选型核心观点

• 追求极致轻量和功能全面 → 选 HunyuanOCR
• 专注复杂文档解析和 LLM 协同 → 选 DeepSeek-OCR-2
• 传统场景、资源极度受限 → 选 PaddleOCR
• 通用多模态理解需求 → 选 Qwen2-VL

这两款中国团队开源的 OCR 模型，不仅在技术指标上达到 SOTA，更重要的是它们代表了开源社区对"文档智能"这一核心场景的深度思考。对于开发者而言，2026 年是 OCR 技术选型最优的一年——既有成熟的传统方案，也有前沿的端到端模型，且都是免费开源的。

参考链接

• DeepSeek-OCR-2: github.com/deepseek-ai…
• HunyuanOCR: github.com/Tencent-Hun…
• PaddleOCR: github.com/PaddlePaddl…
• GOT-OCR2.0: github.com/Ucas-Haoran…
• Qwen2-VL: github.com/QwenLM/Qwen…

本文整理自 MDN: HTTP Cookie 与 RFC 6265: HTTP State Management Mechanism。

一、什么是 Cookie

HTTP Cookie（也称 Web Cookie、浏览器 Cookie）是服务器通过 HTTP 响应发送到用户浏览器并保存在本地的一小块数据。浏览器会存储这些 Cookie，并在下次向同一服务器再发起请求时，通过请求头自动携带发送。通常用于告知服务端：两个请求是否来自同一浏览器，从而在无状态的 HTTP 协议上维持稳定状态（如保持用户登录）[MDN]。

• 发明与历史：Lou Montulli（Netscape，1994）；RFC 2109、RFC 2965 已被 RFC 6265（2011）取代，Cookie2/Set-Cookie2 已废弃 [RFC 6265]。
• 标准：RFC 6265 定义 Cookie 与 Set-Cookie 两个头部，并指出 Cookie 存在诸多历史遗留的安全与隐私问题，但仍被广泛使用。

二、Cookie 的三大用途 [MDN]

注意：Cookie 曾作为客户端唯一存储手段被滥用；现在若不需要在每次请求中携带数据，推荐使用现代存储 API（如 Web Storage、IndexedDB），以减少请求头体积与性能开销，尤其在移动端 [MDN]。 在浏览器中查看 Cookie：开发者工具 → 存储/Storage → Storage Inspector → 选中 Cookie [MDN]。

三、创建与传递：Set-Cookie 与 Cookie 头

3.1 基本流程

1. 服务器在 HTTP 响应头里添加一个或多个 Set-Cookie。
2. 浏览器保存这些 Cookie，之后向同一服务器发请求时，在 Cookie 请求头里一并发送 [MDN]。

示例 [MDN]：

HTTP/1.0 200 OK
Content-type: text/html
Set-Cookie: yummy_cookie=choco
Set-Cookie: tasty_cookie=strawberry

[页面内容]

后续请求：

GET /sample_page.html HTTP/1.1
Host: www.example.org
Cookie: yummy_cookie=choco; tasty_cookie=strawberry

注意：不应将多个 Set-Cookie 折叠成一行（HTTP 头部折叠可能改变语义，因为逗号在 Set-Cookie 中有特殊含义）[RFC 6265]。 服务端如何设置 Set-Cookie 可参考 MDN 示例：PHP、Node.js、Python、Ruby on Rails 等 [MDN]。

3.2 语法概要（RFC 6265）

• Set-Cookie 格式：Set-Cookie: <cookie-name>=<cookie-value>，后可跟若干属性（; Expires=...、; Max-Age=...、; Domain=...、; Path=...、; Secure、; HttpOnly 等）。
• Cookie 请求头：Cookie: cookie-pair *( "; " cookie-pair )，仅包含名值对，不包含过期时间、域、路径、Secure、HttpOnly 等属性，服务端无法从 Cookie 头 alone 得知这些元数据 [RFC 6265]。

四、Cookie 的生命周期

4.1 会话期 vs 持久性 [MDN][RFC 6265]

• 会话期 Cookie（Session Cookie）

  • 不设置 Expires 且不设置 Max-Age（或 Max-Age=0）。
  • 在当前会话结束后被删除。注意：“当前会话”由浏览器定义，部分浏览器在重启时会做会话恢复，可能导致会话 Cookie 被保留更久 [MDN]。
  • RFC 6265：此类 Cookie 的 persistent-flag 为 false，expiry-time 为“会话结束”。

• 持久性 Cookie（Persistent Cookie）

  • 通过 Expires（日期/时间）或 Max-Age（秒数）指定存活期。
  • 在过期前会一直存在（除非用户或浏览器策略清除）。
  • Max-Age 优先于 Expires；若两者都存在，以 Max-Age 为准。若 Max-Age 为 0 或负数，表示立即过期 [RFC 6265]。

示例 [MDN]：

Set-Cookie: id=a3fWa; Expires=Wed, 21 Oct 2015 07:28:00 GMT;

重要：Expires 的日期时间是客户端解释的，与服务器时区无关 [MDN]。 若站点对用户做身份验证，建议在每次验证时重新生成并重新发送会话 Cookie（包括已存在的），以减轻会话固定攻击（Session Fixation）[MDN]。

4.2 删除 Cookie

服务端可通过发送同名、同 Domain、同 Path 的 Cookie，并将 Expires 设为过去的时间（或 Max-Age=0）来删除 Cookie [RFC 6265][MDN]。

五、限制 Cookie 的访问与发送

5.1 Secure

• 带 Secure 的 Cookie 仅应通过安全通道（通常为 HTTPS/TLS）发送，不会在不安全的 HTTP 请求中发送（本地主机除外）[MDN]。
• 不安全的站点（URL 为 http:）无法设置带 Secure 的 Cookie [MDN]。
• 注意：Secure 只保护机密性（传输中不被窃听），不提供完整性。主动网络攻击者仍可能通过不安全通道注入或覆盖 Cookie，破坏其完整性 [RFC 6265]。

5.2 HttpOnly

• 带 HttpOnly 的 Cookie 不能被 JavaScript 的 document.cookie 等“非 HTTP API”访问，仅用于 HTTP 请求 [MDN][RFC 6265]。
• 服务端会话 Cookie 通常不需要对 JS 可见，应设置 HttpOnly，以缓解 XSS 窃取会话 [MDN]。

示例 [MDN]：

Set-Cookie: id=a3fWa; Expires=Wed, 21 Oct 2015 07:28:00 GMT; Secure; HttpOnly

六、定义 Cookie 的发送范围：Domain、Path、SameSite

6.1 Domain [MDN][RFC 6265]

• 不指定 Domain：默认为当前 host，不包含子域（即仅当前域名）。
• 指定 Domain：如 Domain=mozilla.org，则子域（如 developer.mozilla.org）也会收到该 Cookie。指定 Domain 会扩大作用域。
• 用户代理会拒绝 Domain 不包含当前 origin 的 Cookie；许多浏览器还会拒绝将 公共后缀（如 com、co.uk）设为 Domain，以防止恶意站点为整片顶级域设置 Cookie [RFC 6265]。

6.2 Path [MDN][RFC 6265]

• Path 指定 URL 路径前缀；只有请求的 URL 路径与该 Path 匹配（或为其子路径）时才会发送 Cookie。
• 路径以 %x2F（"/"）为分隔符；子路径会匹配。例如 Path=/docs 会匹配：
  • /docs、/docs/、/docs/Web/、/docs/Web/HTTP
• 不匹配：/、/docsets、/fr/docs [MDN]。
• 若省略 Path，默认值为当前请求 URI 的路径的“目录”部分 [RFC 6265]。
• 安全提醒：Path 不能作为安全边界依赖；同一主机上不同路径的互不信任服务不应仅靠 Path 隔离敏感 Cookie [RFC 6265]。

6.3 SameSite [MDN]

• SameSite 控制是否在跨站请求中发送 Cookie（“站点”由注册域和协议 http/https 共同定义），用于减轻 CSRF。
• 取值：
  • Strict：仅在同站请求中发送。
  • Lax：与 Strict 类似，但在用户从外站导航到该站时（如点击链接）也会发送。
  • None：同站与跨站请求都会发送；必须同时设置 Secure（即仅在安全上下文中）[MDN]。
• 未设置 SameSite 时，现代浏览器多将其视为 Lax（此前默认行为是更宽松的“始终发送”）[MDN]。
• 同一注册域下，若协议不同（http vs https），视为不同站点 [MDN]。

示例：

Set-Cookie: mykey=myvalue; SameSite=Strict

七、Cookie 前缀（__Host- 与 __Secure-）[MDN]

由于 Cookie 机制无法让服务端确认 Cookie 是否在安全来源设置、甚至无法确认最初设置者，子域上的漏洞可能通过 Domain 为父域设置 Cookie，被用于会话劫持。作为深度防御，可使用 Cookie 前缀：

• __Host- 仅当同时满足以下条件时，浏览器才接受 Set-Cookie：

  • 带 Secure；
  • 从安全来源发送；
  • 不包含 Domain；
  • Path 为 /。 此类 Cookie 可视为“锁定到当前 host”。

• __Secure- 仅当带 Secure 且从安全来源发送时才接受，限制弱于 __Host-。

不符合前缀要求的 Cookie 会被浏览器拒绝。应用服务器必须校验完整 Cookie 名称；用户代理在发送 Cookie 头时不会去掉前缀 [MDN]。

八、浏览器存储模型与发送规则（RFC 6265 要点）

• 用户代理为每个 Cookie 存储：name、value、expiry-time、domain、path、creation-time、last-access-time、persistent-flag、host-only-flag、secure-only-flag、http-only-flag。
• 发送 Cookie 时：只发送与请求的 host（或 Domain 匹配）、Path 匹配、未过期、且满足 Secure（若为 secure-only）的 Cookie；若通过“非 HTTP API”生成请求（如 document.cookie），则不包含 http-only-flag 为 true 的 Cookie。
• Eviction（驱逐）：过期 Cookie 会先被删除；若单域或全局 Cookie 数量超限，可按实现定义的策略删除（RFC 建议优先删过期，再删同域过多的，再删全局过多的；同优先级时删 last-access-time 最早的）。
• 实现建议下限：每 Cookie 至少 4096 字节（名+值+属性总长）、每域至少 50 个 Cookie、全局至少 3000 个 Cookie；服务端应尽量少而小，并做好用户代理未返回某些 Cookie 时的降级 [RFC 6265]。

九、JavaScript 与 Document.cookie [MDN]

• 通过 Document.cookie 可创建新 Cookie，也可读取现有 Cookie（仅限未设置 HttpOnly 的）。
• 由 JavaScript 创建的 Cookie 不能包含 HttpOnly [MDN]。

示例 [MDN]：

document.cookie = "yummy_cookie=choco";
document.cookie = "tasty_cookie=strawberry";
console.log(document.cookie);
// 输出 "yummy_cookie=choco; tasty_cookie=strawberry"

安全：Cookie 值可被用户或脚本访问与修改，需注意 XSS。敏感场景建议使用服务端查证的不透明标识符，或考虑 JWT 等替代方案；在不可信环境中不要通过 HTTP Cookie 存储或传输敏感信息 [MDN]。

十、安全考量 [MDN][RFC 6265]

10.1 缓解措施

• 使用 HttpOnly 防止通过 JS 读取 Cookie。
• 敏感 Cookie（如身份验证）应生存期短，并设置 SameSite=Strict 或 Lax，避免在跨站请求中发送 [MDN]。

10.2 常见风险

• 环境权威（Ambient Authority）与 CSRF：Cookie 随请求自动携带，易被跨站请求伪造；应配合 SameSite、CSRF Token 等 [RFC 6265]。
• 明文传输：非 HTTPS 时 Cookie 明文传输，易被窃听与篡改；敏感 Cookie 应配合 Secure 与 HTTPS [RFC 6265]。
• 会话固定（Session Fixation）：攻击者将已知会话 ID 植入受害者浏览器 → 受害者用该 ID 登录 → 攻击者用同一 ID 冒充。缓解：每次认证后重新签发会话 Cookie [MDN][RFC 6265]。
• 弱机密性：Cookie 不按端口、不按协议（http/https）隔离，同一 host 不同端口/协议可能共享 Cookie；不可在同一主机上对互不信任的服务依赖 Cookie 做敏感隔离 [RFC 6265]。
• 弱完整性：同父域下不同子域可互相覆盖 Domain 为父域的 Cookie；主动攻击者还可通过 HTTP 响应注入 Set-Cookie，影响 HTTPS 站点的 Cookie。加密/签名 Cookie 内容可部分缓解，但无法防止重放 [RFC 6265]。
• 依赖 DNS：Cookie 安全依赖 DNS；DNS 被篡改时，Cookie 提供的安全属性可能失效 [RFC 6265]。

十一、跟踪与隐私 [MDN][RFC 6265]

11.1 第一方 vs 第三方 Cookie

• 第一方 Cookie：Cookie 的域和协议与当前页面一致（或为当前页面的子域等符合 Domain 规则）。
• 第三方 Cookie：由页面中引用的其他域（如广告、统计）设置；同一第三方在不同站点可收到同一 Cookie，从而跨站跟踪用户 [MDN][RFC 6265]。
• 许多浏览器已限制或计划淘汰第三方 Cookie（如 Firefox 默认阻止已知跟踪器）；服务器可通过 SameSite 控制是否在跨站场景下发送 [MDN]。

11.2 法规与合规 [MDN]

涉及 Cookie 的法规包括（具有全球影响）：

• 欧盟 GDPR（通用数据保护条例）
• 欧盟 ePrivacy 指令
• 加州 CCPA（加州消费者隐私法；通常适用于年收入超过一定规模的实体）

常见要求：向用户告知使用 Cookie、允许用户拒绝部分或全部 Cookie、在用户拒绝 Cookie 时仍能使用主要服务。部分公司提供“Cookie 横幅”等方案以辅助合规 [MDN]。

11.3 各浏览器对第三方 Cookie 的政策（按浏览器与版本）

不同浏览器、不同版本对第三方 Cookie 的限制差异很大；以下按浏览器与版本范围整理，便于兼容性判断与迁移规划。策略会随版本更新变化，以各厂商官方文档为准。

Safari（WebKit）

小结：Safari 13.1+（macOS/iOS/iPadOS 对应版本起）默认即“全阻”第三方 Cookie；更早版本通过 ITP 逐步收紧，仍以“限制跟踪域 + 分区/短期”为主，而非一刀切全阻。

Firefox

小结：Firefox 当前（ETP 默认 + TCP 默认）下，第三方 Cookie 被“按站隔离”，等同阻止跨站跟踪；用户仍可在设置中按站点允许 Cookie。

Chrome（Chromium）

小结：Chrome 目前仍以 SameSite 默认 Lax 为主，未全局默认“阻第三方”；淘汰时间表与 Privacy Sandbox 绑定，会随政策与反馈调整。

Microsoft Edge（Chromium）

小结：Edge 默认不“全阻”第三方 Cookie，而是按跟踪列表 + 参与度启发式限制；Strict 模式最严，Balanced 在隐私与兼容之间折中。

其他浏览器（简要）

• Brave：自 2019 年 11 月 1.0 起默认阻止广告与跟踪器，第三方跟踪 Cookie 默认被阻。
• Opera：约 2019 年 10 月起内置反跟踪，策略类似“阻止已知跟踪列表”，非全阻第三方 Cookie。

汇总表（当前默认行为，约 2024–2025）

开发建议：若依赖跨站 Cookie（如嵌入式登录、跨站分析），应显式设置 SameSite=None; Secure，并尽早评估 Storage Access API、CHIPS（Partitioned Cookie）、Related Website Sets 等替代方案，以兼容 Safari 与未来 Chrome 的变更。

十二、其他浏览器存储方式 [MDN]

“僵尸”Cookie（Zombie Cookie）：在 Cookie 被删后通过其他存储或脚本重新创建 Cookie。此类做法损害用户隐私与控制权，可能违反数据隐私法规并带来法律风险，不应使用 [MDN]。

十三、小结

• Cookie 由服务端通过 Set-Cookie 下发，浏览器在后续符合域、路径、安全、SameSite 等条件的请求中通过 Cookie 头自动携带，用于在无状态 HTTP 上维持状态 [MDN][RFC 6265]。
• 通过 Expires/Max-Age、Domain、Path、Secure、HttpOnly、SameSite 及前缀 __Host- / __Secure- 可控制生命周期、作用域与安全性。
• 在浏览器中，发送逻辑由用户代理按 RFC 与扩展（如 SameSite）实现；JS 仅能读写非 HttpOnly 的 Cookie。
• 建议：敏感 Cookie 使用 HttpOnly + Secure + SameSite，配合 CSRF 防护与短生存期；避免用 Cookie 存敏感明文；关注第三方 Cookie 限制与隐私法规。

参考

• MDN: HTTP Cookie
• RFC 6265: HTTP State Management Mechanism
• MDN: Set-Cookie
• MDN: Document.cookie

迎接马年新春，历时三周爆肝迭代研发uni-app+vue3对接deepseek-v3.2聊天大模型。新增深度思考、katex数学公式、代码高亮/复制代码等功能。

H5端还支持mermaid图表渲染，小程序端支持复制代码。

使用技术

• 开发工具：HbuilderX 4.87
• 技术框架：uni-app+vue3+pinia2+vite5
• 大模型框架：DeepSeek-V3.2
• 组件库：uni-ui+uv-ui
• 高亮插件：highlight.js
• markdown解析：ua-markdown+mp-html
• 本地缓存：pinia-plugin-unistorage

编译支持

另外还支持运行到web端，以750px显示页面布局结构。

如果想要了解更多的项目介绍，可以去看看这篇文章。

uniapp+deepseek流式ai助理|uniapp+vue3对接deepseek三端Ai问答模板

往期推荐

2026最新款Vue3+DeepSeek-V3.2+Arco+Markdown网页端流式生成AI Chat

Electron39.2+Vue3+DeepSeek从0-1手搓AI模板桌面应用Exe

2026最新款Vite7+Vue3+DeepSeek-V3.2+Markdown流式输出AI会话

electron38.2-vue3os系统|Vite7+Electron38+Pinia3+ArcoDesign桌面版OS后台管理

基于electron38+vite7+vue3 setup+elementPlus电脑端仿微信/QQ聊天软件

2025最新款Electron38+Vite7+Vue3+ElementPlus电脑端后台系统Exe

自研2025版flutter3.38实战抖音app短视频+聊天+直播商城系统

基于uni-app+vue3+uvui跨三端仿微信app聊天模板【h5+小程序+app】

基于uniapp+vue3+uvue短视频+聊天+直播app系统

基于flutter3.32+window_manager仿macOS/Wins风格桌面os系统

flutter3.27+bitsdojo_window电脑端仿微信Exe应用

自研tauri2.0+vite6.x+vue3+rust+arco-design桌面版os管理系统Tauri2-ViteOS

一、背景与问题

在微前端架构下，主应用长期积累了 5 套图标方案并存 的混乱局面：

核心痛点：

• 子应用无法共享主应用图标，每个应用各自维护
• 同一个图标可能通过 3 种不同方式引用
• iconfont JS 全量加载 115KB，无法按需
• 1962 行硬编码图标列表，维护成本极高
• 中后台系统 90% 以上使用通用图标，不需要每个应用单独管理

二、治理目标

统一入口 + 集中管理 + 零配置共享

• 一个组件：<CmcIcon> 统一消费所有图标
• 一个图标包：@cmclink/icons 集中管理 SVG 资源
• 零配置：子应用迁入 Monorepo 后自动获得所有共享图标
• 按需加载：Element Plus 图标异步 import，不影响首屏

三、方案架构

┌──────────────────────────────────────────────────────┐
│                    使用层（所有子应用）                  │
│                                                      │
│  <CmcIcon name="Home" />           — SVG Sprite 图标  │
│  <CmcIcon name="ep:Edit" />        — Element Plus 图标 │
│  <CmcIcon name="Star" size="lg" color="primary" />   │
├──────────────────────────────────────────────────────┤
│               @cmclink/ui — CmcIcon 组件              │
│                                                      │
│  ┌─────────────┐    ┌──────────────────┐             │
│  │ SVG Sprite  │    │ Element Plus     │             │
│  │ <svg><use>  │    │ 动态 import      │             │
│  │ 无前缀      │    │ ep: 前缀         │             │
│  └─────────────┘    └──────────────────┘             │
├──────────────────────────────────────────────────────┤
│            @cmclink/icons — 共享图标资源包              │
│                                                      │
│  packages/icons/src/svg/                             │
│  ├── Home.svg                                        │
│  ├── Star.svg                                        │
│  ├── Logo.svg                                        │
│  └── ... (30+ 通用图标)                               │
├──────────────────────────────────────────────────────┤
│           @cmclink/vite-config — 构建自动集成           │
│                                                      │
│  vite-plugin-svg-icons 自动扫描：                      │
│  1. packages/icons/src/svg/  （共享图标，优先）          │
│  2. apps/{app}/src/assets/svgs/ （本地图标，可覆盖）     │
└──────────────────────────────────────────────────────┘

四、CmcIcon 组件设计

4.1 Props 接口

interface CmcIconProps {
  /**
   * 图标名称
   * - 无前缀: SVG Sprite 图标（如 "Home"、"Star"）
   * - "ep:" 前缀: Element Plus 图标（如 "ep:Edit"、"ep:Delete"）
   */
  name: string
  /** 尺寸：数字(px) | 预设('xs'|'sm'|'md'|'lg'|'xl') | CSS 字符串 */
  size?: number | string | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
  /** 颜色：CSS 值 | 主题色('primary'|'success'|'warning'|'danger'|'info') */
  color?: string
  /** 旋转角度 */
  rotate?: number
  /** 旋转动画 */
  spin?: boolean
  /** 禁用状态 */
  disabled?: boolean
  /** 可点击 */
  clickable?: boolean
}

4.2 预设尺寸

4.3 主题色

使用 CSS 变量自动跟随 Element Plus 主题：

const colorMap = {
  primary: 'var(--el-color-primary, #004889)',
  success: 'var(--el-color-success, #10b981)',
  warning: 'var(--el-color-warning, #f59e0b)',
  danger:  'var(--el-color-danger, #ef4444)',
  info:    'var(--el-color-info, #3b82f6)',
}

4.4 Element Plus 图标异步加载

// ep: 前缀触发异步加载，不影响首屏 bundle
watch(
  () => props.name,
  async (name) => {
    if (!name.startsWith('ep:')) return
    const iconName = name.slice(3) // "ep:Edit" → "Edit"
    const icons = await import('@element-plus/icons-vue')
    elIconComponent.value = icons[iconName] ?? null
  },
  { immediate: true }
)

五、Vite 构建集成

5.1 主应用配置（main-app.ts）

createSvgIconsPlugin({
  iconDirs: [
    // 共享图标库（@cmclink/icons）— 所有子应用共享
    resolve(root, '../../packages/icons/src/svg'),
    // 应用本地图标（可覆盖共享图标，或放置业务特有图标）
    resolve(root, 'src/assets/svgs'),
  ],
  symbolId: 'icon-[dir]-[name]',
  svgoOptions: true,
})

5.2 子应用配置（child-app.ts）

// svgIcons 选项默认 true，子应用零配置即可共享图标
export interface ChildAppOptions {
  svgIcons?: boolean  // 默认 true
  // ...
}

关键设计：iconDirs 数组中共享图标在前、本地图标在后，本地同名 SVG 可覆盖共享图标，实现灵活的图标定制能力。

六、迁移实施

6.1 迁移映射表

6.2 实施清单

已完成 ✅

6.3 收益量化

七、使用指南

7.1 SVG Sprite 图标（推荐）

<!-- 基础用法 -->
<CmcIcon name="Home" />

<!-- 预设尺寸 -->
<CmcIcon name="Star" size="lg" />

<!-- 自定义像素 -->
<CmcIcon name="Document" :size="32" />

<!-- 主题色 -->
<CmcIcon name="Warning" color="danger" />

<!-- 旋转动画 -->
<CmcIcon name="Loading" spin />

<!-- 可点击 -->
<CmcIcon name="Close" clickable @click="handleClose" />

7.2 Element Plus 图标

<!-- ep: 前缀，异步加载 -->
<CmcIcon name="ep:Edit" />
<CmcIcon name="ep:Delete" color="danger" />
<CmcIcon name="ep:Search" :size="18" />
<CmcIcon name="ep:Loading" spin />

7.3 添加新图标

1. 将 SVG 文件放入 packages/icons/src/svg/
2. 文件名即图标名（如 MyIcon.svg → <CmcIcon name="MyIcon" />）
3. 无需任何额外配置，Vite HMR 自动生效
4. 所有子应用自动可用

7.4 应用级图标覆盖

如果某个子应用需要定制某个图标的样式：

1. 在 apps/{app}/src/assets/svgs/ 放入同名 SVG
2. 本地版本自动覆盖共享版本
3. 其他子应用不受影响

八、目录结构

packages/
├── icons/                          # 共享图标包
│   ├── package.json                # @cmclink/icons
│   ├── README.md                   # 使用文档
│   └── src/
│       ├── index.ts                # 导出图标目录路径常量
│       └── svg/                    # 所有共享 SVG 图标
│           ├── Home.svg
│           ├── Star.svg
│           ├── UnStar.svg
│           ├── Logo.svg
│           ├── TopMenu.svg
│           └── ...
├── ui/
│   └── src/base/CmcIcon/
│       ├── index.ts
│       └── src/CmcIcon.vue         # 统一图标组件
└── vite-config/
    └── src/
        ├── main-app.ts             # iconDirs: [共享, 本地]
        └── child-app.ts            # svgIcons 选项

九、FAQ

Q: IconSelect 组件删除后，图标选择功能怎么办？

A: IconSelect 依赖已删除的 data.ts（1962 行硬编码列表）。如果业务确实需要图标选择器，建议基于 @element-plus/icons-vue 的导出列表动态生成，而非硬编码。后续可在 @cmclink/ui 中实现新版 CmcIconPicker。

Q: 子应用还在外部独立仓库，如何使用共享图标？

A: 当前 child-app.ts 的 iconDirs 使用相对路径 ../../packages/icons/src/svg，仅适用于 Monorepo 内的子应用。外部子应用迁入 Monorepo 后自动生效。迁入前可通过 extraPlugins 自行配置 vite-plugin-svg-icons。

Q: 第三方图标库（如 Font Awesome）怎么处理？

A: 当前 CmcIcon 支持 SVG Sprite 和 Element Plus 两种源。如需扩展第三方图标库，可在 CmcIcon 中增加新的前缀识别（如 fa: → Font Awesome），通过异步 import 按需加载。但中后台系统建议优先使用 Element Plus 图标，保持设计一致性。

1. 前言：为什么我要写这篇文章？

作为一名在大厂摸爬滚打多年的前端工程师，我见过太多因为性能问题而被用户吐槽的Vue应用：

• 首屏白屏3-5秒，用户直接关闭页面
• 列表滚动卡顿，万条数据渲染让页面直接卡死
• 表单输入延迟，复杂表单每次输入都要等半秒
• 内存泄漏严重，页面用久了越来越慢

Vue 3.5 正式发布后，我花了2个月时间在生产环境中实践新特性，通过10个核心优化技巧，成功将我们的企业级应用性能提升了300%：

• ✅ 首屏加载时间：从 4.2s 降至 1.4s
• ✅ 列表渲染性能：万条数据从卡顿3秒到流畅滚动
• ✅ 内存占用：减少 40% 的内存泄漏
• ✅ 打包体积：减小 35% 的bundle大小

读完这篇文章，你将收获：

• Vue 3.5 最新性能优化API的实战用法
• 10个立即可用的性能优化技巧
• 完整的性能监控和测试方案
• 企业级应用的最佳实践经验

2. 背景知识快速说明

Vue 3.5 性能提升核心亮点

Vue 3.5 在性能方面有三大突破：

1. 响应式系统优化：新增 effectScope API，提供更精确的副作用管理
2. 渲染性能提升：v-memo 指令优化，智能缓存渲染结果
3. 编译时优化：更激进的 Tree-shaking，减少 30% 的运行时代码

性能优化的三个维度

• 运行时性能：响应式更新、组件渲染、内存管理
• 加载时性能：代码分割、资源预加载、缓存策略
• 开发时性能：构建速度、热更新效率

3. 核心实现思路（重点）

Step1：响应式系统精细化管理

通过 effectScope、shallowRef、readonly 等API，精确控制响应式的粒度和范围，避免不必要的响应式开销。

Step2：组件渲染智能优化

利用 v-memo、KeepAlive、异步组件等特性，减少重复渲染和DOM操作，提升用户交互体验。

Step3：构建与加载策略优化

通过代码分割、Tree-shaking、预加载等技术，优化应用的加载性能和运行时体积。

4. 完整代码示例（必须可运行）

技巧1：effectScope 精确管理副作用

在Vue 3.5中，effectScope 是解决内存泄漏的神器。传统方式下，我们需要手动清理每个 watch 和 computed，现在可以批量管理：

// 传统方式 - 容易遗漏清理
export default defineComponent({
  setup() {
    const counter = ref(0)
    const doubled = computed(() => counter.value * 2)
    
    const stopWatcher1 = watch(counter, (val) => {
      console.log('Counter changed:', val)
    })
    
    const stopWatcher2 = watchEffect(() => {
      document.title = `Count: ${counter.value}`
    })
    
    // 组件卸载时需要手动清理 - 容易遗漏
    onUnmounted(() => {
      stopWatcher1()
      stopWatcher2()
    })
    
    return { counter, doubled }
  }
})

// Vue 3.5 优化方式 - 自动批量清理
export default defineComponent({
  setup() {
    const scope = effectScope()
    
    const { counter, doubled } = scope.run(() => {
      const counter = ref(0)
      const doubled = computed(() => counter.value * 2)
      
      // 所有副作用都在scope中管理
      watch(counter, (val) => {
        console.log('Counter changed:', val)
      })
      
      watchEffect(() => {
        document.title = `Count: ${counter.value}`
      })
      
      return { counter, doubled }
    })!
    
    // 组件卸载时一键清理所有副作用
    onUnmounted(() => {
      scope.stop()
    })
    
    return { counter, doubled }
  }
})

性能提升：内存泄漏减少90%，组件卸载速度提升50%

技巧2：shallowRef 优化大对象性能

对于图表数据、配置对象等大型数据结构，使用 shallowRef 可以显著提升性能：

// 传统方式 - 深度响应式导致性能问题
const chartData = ref({
  datasets: [
    {
      label: 'Sales',
      data: new Array(10000).fill(0).map(() => Math.random() * 100),
      backgroundColor: 'rgba(75, 192, 192, 0.2)'
    }
  ],
  options: {
    responsive: true,
    plugins: {
      legend: { position: 'top' },
      title: { display: true, text: 'Sales Chart' }
    }
  }
})

// 每次数据更新都会触发深度响应式检查 - 性能差

// Vue 3.5 优化方式 - 浅层响应式
const chartData = shallowRef({
  datasets: [
    {
      label: 'Sales', 
      data: new Array(10000).fill(0).map(() => Math.random() * 100),
      backgroundColor: 'rgba(75, 192, 192, 0.2)'
    }
  ],
  options: {
    responsive: true,
    plugins: {
      legend: { position: 'top' },
      title: { display: true, text: 'Sales Chart' }
    }
  }
})

// 更新数据的正确方式
const updateChartData = (newData: number[]) => {
  // 直接修改不会触发更新
  chartData.value.datasets[0].data = newData
  
  // 手动触发更新 - 精确控制更新时机
  triggerRef(chartData)
}

// 在组合式函数中的应用
export function useChartData() {
  const chartData = shallowRef({
    datasets: [],
    options: {}
  })
  
  const updateData = (newDatasets: any[]) => {
    chartData.value.datasets = newDatasets
    triggerRef(chartData)
  }
  
  const updateOptions = (newOptions: any) => {
    chartData.value.options = { ...chartData.value.options, ...newOptions }
    triggerRef(chartData)
  }
  
  return {
    chartData: readonly(chartData),
    updateData,
    updateOptions
  }
}

性能提升：大对象更新性能提升80%，内存占用减少40%

技巧3：v-memo 智能缓存大列表渲染

v-memo 是Vue 3.5中最强大的渲染优化指令，特别适合大列表场景：

<template>
  <!-- 传统方式 - 每次都重新渲染 -->
  <div class="traditional-list">
    <div 
      v-for="item in expensiveList" 
      :key="item.id"
      class="list-item"
    >
      <ExpensiveComponent :data="item" />
    </div>
  </div>

  <!-- Vue 3.5 优化方式 - 智能缓存 -->
  <div class="optimized-list">
    <div 
      v-for="item in expensiveList" 
      :key="item.id"
      v-memo="[item.id, item.status, item.selected]"
      class="list-item"
    >
      <ExpensiveComponent :data="item" />
    </div>
  </div>

  <!-- 复杂场景：结合计算属性的缓存策略 -->
  <div class="advanced-list">
    <div 
      v-for="item in processedList" 
      :key="item.id"
      v-memo="[item.memoKey]"
      class="list-item"
    >
      <ComplexComponent 
        :data="item"
        :user="currentUser"
        :permissions="userPermissions"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
interface ListItem {
  id: string
  name: string
  status: 'active' | 'inactive'
  selected: boolean
  data: any[]
  lastModified: number
}

const expensiveList = ref<ListItem[]>([])
const currentUser = ref({ id: '1', name: 'John' })
const userPermissions = ref(['read', 'write'])

// 计算属性优化：预计算memo key
const processedList = computed(() => {
  return expensiveList.value.map(item => ({
    ...item,
    // 将多个依赖项合并为单个memo key
    memoKey: `${item.id}-${item.status}-${item.selected}-${currentUser.value.id}-${userPermissions.value.join(',')}`
  }))
})

// 性能监控：对比渲染次数
const renderCount = ref(0)
const memoHitCount = ref(0)

// 模拟大量数据
const generateLargeList = () => {
  expensiveList.value = Array.from({ length: 10000 }, (_, index) => ({
    id: `item-${index}`,
    name: `Item ${index}`,
    status: Math.random() > 0.5 ? 'active' : 'inactive',
    selected: false,
    data: Array.from({ length: 100 }, () => Math.random()),
    lastModified: Date.now()
  }))
}

// 批量更新优化
const batchUpdateItems = (updates: Partial<ListItem>[]) => {
  // 使用 nextTick 确保批量更新
  nextTick(() => {
    updates.forEach(update => {
      const index = expensiveList.value.findIndex(item => item.id === update.id)
      if (index !== -1) {
        Object.assign(expensiveList.value[index], update)
      }
    })
  })
}

onMounted(() => {
  generateLargeList()
})
</script>

性能提升：大列表渲染性能提升200%，滚动帧率从30fps提升到60fps

技巧4：KeepAlive 智能缓存策略

合理使用 KeepAlive 可以显著提升路由切换性能：

<!-- 路由级别的KeepAlive配置 -->
<template>
  <router-view v-slot="{ Component, route }">
    <KeepAlive 
      :include="cacheableRoutes"
      :exclude="noCacheRoutes"
      :max="maxCacheCount"
    >
      <component 
        :is="Component" 
        :key="route.meta.keepAliveKey || route.fullPath"
      />
    </KeepAlive>
  </router-view>
</template>

<script setup lang="ts">
// 智能缓存策略配置
const cacheableRoutes = ref([
  'UserList',      // 用户列表页 - 数据加载慢，适合缓存
  'ProductDetail', // 商品详情页 - 复杂计算，适合缓存
  'Dashboard'      // 仪表盘 - 图表渲染慢，适合缓存
])

const noCacheRoutes = ref([
  'Login',         // 登录页 - 安全考虑，不缓存
  'Payment',       // 支付页 - 实时性要求，不缓存
  'Settings'       // 设置页 - 状态变化频繁，不缓存
])

const maxCacheCount = ref(10) // 最多缓存10个组件

// 动态缓存管理
const cacheManager = {
  // 根据用户行为动态调整缓存策略
  adjustCacheStrategy(route: RouteLocationNormalized) {
    const { meta } = route
    
    // 高频访问页面优先缓存
    if (meta.visitCount && meta.visitCount > 5) {
      if (!cacheableRoutes.value.includes(route.name as string)) {
        cacheableRoutes.value.push(route.name as string)
      }
    }
    
    // 内存占用过高时清理缓存
    if (performance.memory && performance.memory.usedJSHeapSize > 100 * 1024 * 1024) {
      maxCacheCount.value = Math.max(3, maxCacheCount.value - 2)
    }
  },
  
  // 手动清理特定缓存
  clearCache(routeName: string) {
    const index = cacheableRoutes.value.indexOf(routeName)
    if (index > -1) {
      cacheableRoutes.value.splice(index, 1)
      // 触发重新渲染
      nextTick(() => {
        cacheableRoutes.value.push(routeName)
      })
    }
  }
}

// 组件级别的缓存优化
export default defineComponent({
  name: 'ExpensiveComponent',
  setup() {
    // 缓存激活时的数据恢复
    onActivated(() => {
      console.log('Component activated from cache')
      // 恢复滚动位置
      restoreScrollPosition()
      // 刷新实时数据
      refreshRealTimeData()
    })
    
    // 缓存失活时的清理工作
    onDeactivated(() => {
      console.log('Component deactivated to cache')
      // 保存滚动位置
      saveScrollPosition()
      // 暂停定时器
      pauseTimers()
    })
    
    const restoreScrollPosition = () => {
      const savedPosition = sessionStorage.getItem('scrollPosition')
      if (savedPosition) {
        window.scrollTo(0, parseInt(savedPosition))
      }
    }
    
    const saveScrollPosition = () => {
      sessionStorage.setItem('scrollPosition', window.scrollY.toString())
    }
    
    return {}
  }
})
</script>

性能提升：路由切换速度提升150%，用户体验显著改善

技巧5：异步组件与代码分割优化

通过异步组件实现精细化的代码分割：

// 传统方式 - 全量导入
import UserList from '@/components/UserList.vue'
import ProductDetail from '@/components/ProductDetail.vue'
import Dashboard from '@/components/Dashboard.vue'

// Vue 3.5 优化方式 - 异步组件 + 预加载策略
const AsyncUserList = defineAsyncComponent({
  loader: () => import('@/components/UserList.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorComponent,
  delay: 200,
  timeout: 3000,
  suspensible: true
})

// 高级异步组件配置
const createAsyncComponent = (
  loader: () => Promise<any>,
  options: {
    preload?: boolean
    priority?: 'high' | 'low'
    chunkName?: string
  } = {}
) => {
  return defineAsyncComponent({
    loader: () => {
      const componentPromise = loader()
      
      // 预加载策略
      if (options.preload) {
        // 在空闲时间预加载
        if ('requestIdleCallback' in window) {
          requestIdleCallback(() => {
            componentPromise.catch(() => {}) // 静默处理预加载错误
          })
        }
      }
      
      return componentPromise
    },
    loadingComponent: defineComponent({
      template: `
        <div class="loading-container">
          <div class="loading-spinner"></div>
          <p>Loading ${options.chunkName || 'component'}...</p>
        </div>
      `
    }),
    errorComponent: defineComponent({
      props: ['error'],
      template: `
        <div class="error-container">
          <p>Failed to load component: {{ error.message }}</p>
          <button @click="$emit('retry')">Retry</button>
        </div>
      `
    }),
    delay: 200,
    timeout: 5000,
    suspensible: true
  })
}

// 路由级别的代码分割
const routes = [
  {
    path: '/users',
    name: 'UserList',
    component: createAsyncComponent(
      () => import(/* webpackChunkName: "user-module" */ '@/views/UserList.vue'),
      { preload: true, priority: 'high', chunkName: 'User List' }
    )
  },
  {
    path: '/products/:id',
    name: 'ProductDetail',
    component: createAsyncComponent(
      () => import(/* webpackChunkName: "product-module" */ '@/views/ProductDetail.vue'),
      { preload: false, priority: 'low', chunkName: 'Product Detail' }
    )
  }
]

// 智能预加载管理器
class PreloadManager {
  private preloadedComponents = new Set<string>()
  private preloadQueue: Array<() => Promise<any>> = []
  
  // 根据用户行为预加载组件
  preloadByUserBehavior(routeName: string) {
    if (this.preloadedComponents.has(routeName)) return
    
    const route = routes.find(r => r.name === routeName)
    if (route && 'requestIdleCallback' in window) {
      requestIdleCallback(() => {
        route.component.loader().then(() => {
          this.preloadedComponents.add(routeName)
          console.log(`Preloaded component: ${routeName}`)
        })
      })
    }
  }
  
  // 批量预加载高优先级组件
  preloadHighPriorityComponents() {
    const highPriorityRoutes = routes.filter(r => r.component.priority === 'high')
    
    highPriorityRoutes.forEach(route => {
      this.preloadQueue.push(route.component.loader)
    })
    
    this.processPreloadQueue()
  }
  
  private async processPreloadQueue() {
    while (this.preloadQueue.length > 0) {
      const loader = this.preloadQueue.shift()!
      try {
        await loader()
        // 控制预加载速度，避免影响主线程
        await new Promise(resolve => setTimeout(resolve, 100))
      } catch (error) {
        console.warn('Preload failed:', error)
      }
    }
  }
}

const preloadManager = new PreloadManager()

// 在应用启动时预加载关键组件
onMounted(() => {
  preloadManager.preloadHighPriorityComponents()
})

性能提升：首屏加载时间减少60%，按需加载命中率提升90%

5. 企业级最佳实践

项目结构建议

src/
├── components/
│   ├── base/           # 基础组件（高频使用，打包到vendor）
│   ├── business/       # 业务组件（按模块异步加载）
│   └── lazy/          # 懒加载组件（低频使用）
├── composables/
│   ├── usePerformance.ts  # 性能监控
│   ├── useCache.ts        # 缓存管理
│   └── usePreload.ts      # 预加载管理
├── utils/
│   ├── performance.ts     # 性能工具函数
│   └── memory.ts         # 内存管理工具
└── views/
    ├── critical/      # 关键页面（预加载）
    └── secondary/     # 次要页面（懒加载）

可维护性建议

1. 性能监控体系

// composables/usePerformance.ts
export function usePerformance() {
  const metrics = ref({
    renderTime: 0,
    memoryUsage: 0,
    componentCount: 0
  })
  
  const measureRenderTime = (componentName: string) => {
    const start = performance.now()
    
    onMounted(() => {
      const end = performance.now()
      metrics.value.renderTime = end - start
      
      // 上报性能数据
      reportPerformance({
        component: componentName,
        renderTime: end - start,
        timestamp: Date.now()
      })
    })
  }
  
  return { metrics, measureRenderTime }
}

2. 内存泄漏检测

// utils/memory.ts
export class MemoryMonitor {
  private intervals: number[] = []
  
  startMonitoring() {
    const interval = setInterval(() => {
      if (performance.memory) {
        const { usedJSHeapSize, totalJSHeapSize } = performance.memory
        const usage = (usedJSHeapSize / totalJSHeapSize) * 100
        
        if (usage > 80) {
          console.warn('High memory usage detected:', usage + '%')
          this.triggerGarbageCollection()
        }
      }
    }, 5000)
    
    this.intervals.push(interval)
  }
  
  private triggerGarbageCollection() {
    // 清理缓存
    // 释放不必要的引用
    // 触发组件重新渲染
  }
  
  cleanup() {
    this.intervals.forEach(clearInterval)
    this.intervals = []
  }
}

常见错误与规避

1. 过度使用响应式

// ❌ 错误：对大对象使用深度响应式
const largeData = ref({
  items: new Array(10000).fill({})
})

// ✅ 正确：使用shallowRef
const largeData = shallowRef({
  items: new Array(10000).fill({})
})

2. v-memo使用不当

<!-- ❌ 错误：memo依赖项过多 -->
<div v-memo="[a, b, c, d, e, f, g]">

<!-- ✅ 正确：合并依赖项 -->
<div v-memo="[computedMemoKey]">

3. KeepAlive缓存过多

// ❌ 错误：无限制缓存
<KeepAlive>

// ✅ 正确：限制缓存数量
<KeepAlive :max="10">

6. 总结（Checklist）

通过本文的10个优化技巧，你可以立即提升Vue应用性能：

响应式优化

• ✅ 使用 effectScope 批量管理副作用，避免内存泄漏
• ✅ 对大对象使用 shallowRef 减少响应式开销
• ✅ 用 readonly 包装只读数据，提升渲染性能

渲染优化

• ✅ 在大列表中使用 v-memo 智能缓存渲染结果
• ✅ 合理配置 KeepAlive 缓存策略和数量限制
• ✅ 拆分复杂组件，避免不必要的重渲染
• ✅ 使用异步组件实现按需加载

构建优化

• ✅ 开启 Tree-shaking 减少打包体积
• ✅ 实现路由级别的代码分割
• ✅ 配置智能预加载策略

立即实践建议

• ✅ 先从最耗时的组件开始优化（使用Vue DevTools分析）
• ✅ 建立性能监控体系，持续跟踪优化效果
• ✅ 在开发环境中集成性能检测工具

Vue 3.5的性能优化之路还在继续，这10个技巧只是开始。在实际项目中，你可能还会遇到更多复杂的性能挑战。

如果这篇文章对你有帮助，欢迎点赞收藏！ 你的支持是我持续分享技术干货的动力。

评论区交流你的实践经验：

• 你在Vue性能优化中遇到过哪些坑？
• 这些技巧在你的项目中效果如何？
• 还有哪些性能优化技巧想要了解？

我会在评论区和大家深入讨论，也欢迎分享你的优化案例和数据对比！

Vue3 手绘风爆款实用笔记合集（含避坑+实战+API）

✏️ 开篇说明 🎨

合集主打「爆款实用」，每篇聚焦1个Vue3高频需求，随手记、轻松学，核心知识点+极简可复制示例，新手友好、进阶可用，有错欢迎指出来～

📌 第一篇：Vue3 新手必看避坑指南（90%的人都踩过！）

新手学Vue3，最容易栽在细节上！这篇汇总高频坑点，附解决方案，帮你少走弯路、快速上手～

一、响应式数据踩坑（最高频！）

坑1：ref在JS里忘加.value

<script setup>
import { ref } from 'vue'
const count = ref(0)

// ❌ 错误：JS里操作ref忘了加.value，数据不更新
const add = () => {
  count++ 
}

// ✅ 正确：JS里必须加.value，模板里不用
const add = () => {
  count.value++ 
}
</script>

坑2：reactive绑简单类型无效

<script setup>
import { reactive } from 'vue'

// ❌ 错误：reactive只能绑对象/数组，简单类型无效
const count = reactive(0) // 不会触发响应式更新

// ✅ 正确：简单类型用ref，或包成对象用reactive
const count = ref(0)
// 或
const data = reactive({ count: 0 })
</script>

坑3：解构reactive数据丢失响应式

<script setup>
import { reactive } from 'vue'
const user = reactive({ name: '手绘君', age: 20 })

// ❌ 错误：解构后的数据不是响应式的
const { name } = user
name = '新名字' // 页面不更新

// ✅ 正确：用toRefs解构，保留响应式
import { reactive, toRefs } from 'vue'
const { name } = toRefs(user)
name.value = '新名字' // 正常更新
</script>

二、组件相关避坑

坑4：

🚨 重点：

<script setup>
import { ref } from 'vue'
const count = ref(0)

// ❌ 错误：setup语法糖里没有this
const add = () => {
  this.count.value++ 
}

// ✅ 正确：直接用变量名
const add = () => {
  count.value++ 
}
</script>

坑5：组件传值忘了defineProps/defineEmits

<!-- 子组件 ❌ 错误示例 -->
<script setup>
// 忘了defineProps，直接用props会报错
console.log(props.msg)

// 忘了defineEmits，直接emit会报错
emit('change')
</script>

<!-- 子组件 ✅ 正确示例 -->
<script setup>
// 父传子：defineProps声明
const props = defineProps({
  msg: String
})

// 子传父：defineEmits声明
const emit = defineEmits(['change'])
const send = () => {
  emit('change', '子组件消息')
}
</script>

三、其他高频避坑

• 🚨 坑6：Vue3移除了filter，用computed替代

• 🚨 坑7：v-model绑定reactive对象，不用加.value（模板里）

• 🚨 坑8：onMounted等生命周期，不用写在methods里，直接在setup里调用

💡 小总结：新手避坑核心——记住ref/reative用法、setup语法糖无this、传值需声明！

📌 第二篇：Pinia 极简实战笔记（Vue3状态管理首选）

Vue3官方推荐用Pinia替代Vuex，更轻量、更简洁、不用配置modules，新手也能快速上手，这篇吃透核心用法～

一、快速上手（3步搞定）

1. 安装Pinia

# npm安装
npm install pinia
# yarn安装
yarn add pinia

2. 全局注册Pinia（main.js）

// main.js
import { createApp } from 'vue'
import { createPinia } from 'pinia' // 引入Pinia
import App from './App.vue'

const app = createApp(App)
app.use(createPinia()) // 注册Pinia
app.mount('#app')

3. 创建Store（核心文件）

在src目录下新建store文件夹，创建index.js（或单独创建userStore.js），用defineStore定义仓库。

// src/store/index.js
import { defineStore } from 'pinia'

// 第一个参数：仓库名（唯一，不能重复）
// 第二个参数：配置对象（state/actions/getters）
export const useUserStore = defineStore('user', {
  // 状态（类似Vue2的data）
  state: () => ({
    name: '手绘君',
    age: 20,
    isLogin: false
  }),
  // 方法（类似Vue2的methods，可修改state）
  actions: {
    // 修改单个状态
    setName(newName) {
      this.name = newName // 这里的this指向state，不用.value！
    },
    // 修改多个状态
    login(userInfo) {
      this.name = userInfo.name
      this.isLogin = true
    }
  },
  // 计算属性（类似Vue2的computed）
  getters: {
    // 简单计算
    doubleAge() {
      return this.age * 2
    },
    // 带参数的计算（返回一个函数）
    getAgeAdd(n) {
      return this.age + n
    }
  }
})

二、组件中使用Store

<script setup>
// 1. 引入创建好的Store
import { useUserStore } from '@/store'

// 2. 实例化Store
const userStore = useUserStore()

// 3. 使用state（3种方式）
console.log(userStore.name) // 方式1：直接使用
console.log(userStore.$state.age) // 方式2：通过$state访问

// 4. 调用actions（直接调用，不用dispatch！）
userStore.setName('新名字')
userStore.login({ name: '测试君' })

// 5. 使用getters（直接调用，不用加括号，带参数除外）
console.log(userStore.doubleAge) // 40
console.log(userStore.getAgeAdd(5)) // 25

// 6. 重置state（一键恢复初始值）
const reset = () => {
  userStore.$reset()
}
</script>

<template>
  <div>
    <p>姓名：{{ userStore.name }}</p>
    <p>年龄：{{ userStore.age }}</p>
    <p>年龄翻倍：{{ userStore.doubleAge }}</p>
    <button @click="userStore.setName('小明')">修改姓名</button>
  </div>
</template>

三、核心优势（为什么用Pinia？）

• ✅ 无需配置modules：一个文件就是一个仓库，不用嵌套

• ✅ 不用commit/mutations：直接在actions里修改state，更简洁

• ✅ TypeScript友好：自动推导类型，不用手动声明

• ✅ 体积小：仅1KB左右，比Vuex轻量很多

• ✅ 支持热更新：修改Store不用重启项目

💡 小总结：Pinia用法=定义仓库+实例化+直接使用，新手无脑冲就对了！

📌 第三篇：Vue Router 4 实战手册（Vue3配套路由）

Vue3配套Vue Router 4，单页面应用（SPA）必备，这篇覆盖路由核心用法：路由配置、跳转、传参、守卫，极简示例可直接复制！

一、快速上手（4步搞定）

1. 安装Vue Router 4

# 注意：Vue3必须装vue-router@4版本
npm install vue-router@4
yarn add vue-router@4

2. 创建路由配置文件

src目录下新建router文件夹，创建index.js：

// src/router/index.js
import { createRouter, createWebHistory } from 'vue-router'

// 1. 引入组件（两种方式）
// 方式1：普通引入（适合首页、高频组件）
import Home from '@/views/Home.vue'
// 方式2：懒加载（适合非首页，优化性能）
const About = () => import('@/views/About.vue')

// 2. 路由规则配置
const routes = [
  // 首页路由
  {
    path: '/', // 路由路径（url地址）
    name: 'Home', // 路由名称（唯一）
    component: Home, // 对应组件
    meta: {
      title: '首页', // 页面标题（可自定义）
      requireAuth: false // 是否需要登录（自定义）
    }
  },
  // 关于页路由
  {
    path: '/about',
    name: 'About',
    component: About,
    meta: { title: '关于我们' }
  },
  // 动态路由（参数传递）
  {
    path: '/user/:id', // :id是动态参数
    name: 'User',
    component: () => import('@/views/User.vue'),
    meta: { title: '用户中心' }
  },
  // 404路由（匹配所有未定义路由）
  {
    path: '/:pathMatch(.*)*', // 匹配所有路径
    name: 'NotFound',
    component: () => import('@/views/NotFound.vue'),
    meta: { title: '页面不存在' }
  }
]

// 3. 创建路由实例
const router = createRouter({
  history: createWebHistory(), // 哈希模式用createWebHashHistory()
  routes // 传入路由规则
})

// 4. 导出路由
export default router

3. 全局注册路由（main.js）

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import router from './router' // 引入路由

const app = createApp(App)
app.use(router) // 注册路由
app.mount('#app')

4. 配置路由出口（App.vue）

<template>
  &lt;div id="app"&gt;
    <!-- 路由导航（类似a标签） -->
    <nav>
      <router-link to="/">首页</router-link>
      <router-link to="/about">关于我们</router-link>
      <router-link :to="{ name: 'User', params: { id: 123 } }"&gt;用户中心&lt;/router-link&gt;
    &lt;/nav&gt;
    
    <!-- 路由出口：匹配的组件会渲染到这里 -->
    <router-view></router-view>
  </div>
</template>

二、核心用法（高频刚需）

1. 路由跳转（3种方式）

<script setup>
import { useRouter, useRoute } from 'vue-router'

// 实例化路由
const router = useRouter() // 用于跳转
const route = useRoute() // 用于获取路由信息

// 方式1：router-link（模板中使用，最简洁）
// <router-link to="/home">首页</router-link>

// 方式2：编程式跳转（JS中使用）
const goHome = () => {
  router.push('/home') // 直接传路径
  // 或传对象（推荐，可传参数）
  router.push({
    name: 'Home', // 用路由名称跳转（更稳定）
    query: { name: '手绘君' } // 拼接在url上的参数
  })
}

// 方式3：替换当前路由（不会留下历史记录，适合登录页）
const goLogin = () => {
  router.replace('/login')
}

// 后退/前进
const goBack = () => {
  router.back() // 后退
  // router.forward() // 前进
}
</script>

2. 路由传参（2种方式）

方式1：query传参（url拼接，类似get请求）

// 跳转页：传参
router.push({
  name: 'About',
  query: { id: 1, msg: '测试' }
})
// url会变成：/about?id=1&msg=测试

// 接收页：获取参数
const route = useRoute()
console.log(route.query.id) // 1
console.log(route.query.msg) // 测试

方式2：params传参（动态路由，url不拼接，类似post请求）

// 1. 先配置动态路由（router/index.js）
{
  path: '/user/:id', // :id是动态参数
  name: 'User',
  component: User
}

// 2. 跳转页：传参
router.push({
  name: 'User', // 必须用name跳转，不能用path
  params: { id: 123, name: '手绘君' }
})

// 3. 接收页：获取参数
const route = useRoute()
console.log(route.params.id) // 123
console.log(route.params.name) // 手绘君

3. 路由守卫（权限控制核心）

以全局前置守卫为例（登录拦截），其他守卫用法类似：

// router/index.js
router.beforeEach((to, from, next) => {
  // to：要跳转到的路由
  // from：从哪个路由跳转过来
  // next：放行/跳转的函数

  // 1. 设置页面标题
  document.title = to.meta.title || 'Vue3笔记'

  // 2. 登录拦截（只有登录才能访问/user路由）
  const isLogin = localStorage.getItem('isLogin') // 模拟登录状态
  if (to.name === 'User' && !isLogin) {
    // 未登录，跳转到登录页
    next('/login')
  } else {
    // 已登录/无需登录，放行
    next()
  }
})

💡 小总结：路由核心=配置路由+跳转+传参+守卫，掌握这4点，满足90%的项目需求！

📌 第四篇：Vue3 组件封装实战（新手也能学会）

组件封装是Vue3的核心优势，能大幅提高代码复用率、简化开发，这篇以3个高频组件（按钮、输入框、弹窗）为例，教你从零封装可复用组件！

一、封装核心原则

• ✅ 单一职责：一个组件只做一件事（比如按钮组件只负责按钮展示和点击）

• ✅ 可复用：通过props传参，适配不同场景

• ✅ 可扩展：通过slot插槽，支持自定义内容

• ✅ 易维护：代码简洁，注释清晰，逻辑分离

二、实战1：封装通用按钮组件（Btn.vue）

<!-- src/components/Btn.vue -->
<template>
  <button 
    class="custom-btn"
    :class="['btn-' + type, { 'btn-disabled': disabled }]"
    @click="handleClick"
    :disabled="disabled"
  &gt;
    <!-- 插槽：自定义按钮内容 -->
    <slot>默认按钮</slot>
  </button>
</template>

<script setup>
// 1. 接收父组件传参（props）
const props = defineProps({
  // 按钮类型（primary/success/danger/default）
  type: {
    type: String,
    default: 'default' // 默认值
  },
  // 是否禁用
  disabled: {
    type: Boolean,
    default: false
  }
})

// 2. 子传父：点击事件
const emit = defineEmits(['click'])
const handleClick = () => {
  // 禁用状态下不触发事件
  if (!props.disabled) {
    emit('click')
  }
}
</script>

<style scoped>
.custom-btn {
  padding: 6px 16px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 14px;
}
/* 不同类型按钮样式 */
.btn-default {
  background: #f5f5f5;
  color: #333;
}
.btn-primary {
  background: #42b983; /* Vue绿 */
  color: #fff;
}
.btn-success {
  background: #67c23a;
  color: #fff;
}
.btn-danger {
  background: #f56c6c;
  color: #fff;
}
/* 禁用样式 */
.btn-disabled {
  cursor: not-allowed;
  opacity: 0.6;
}
</style>

组件使用示例

<template>
  <div>
    <Btn @click="handleClick">默认按钮</Btn>
    <Btn type="primary" @click="handleClick">主要按钮</Btn>
    <Btn type="success" @click="handleClick">成功按钮</Btn>
    <Btn type="danger" disabled>禁用按钮</Btn>
    <!-- 插槽自定义内容 -->
    <Btn type="primary">
      <i class="icon">✓</i> 带图标按钮
    </Btn>
  </div>
</template>

<script setup>
import Btn from '@/components/Btn.vue'

const handleClick = () => {
  console.log('按钮被点击了')
}
</script>

三、实战2：封装通用输入框组件（Input.vue）

<!-- src/components/Input.vue -->
<template>
  &lt;div class="custom-input"&gt;
    <!-- 标签插槽 -->
    <label class="input-label" v-if="label">{{ label }}</label>
    <input
      class="input-content"
      :type="type"
      :placeholder="placeholder"
      :value="modelValue"
      @input="handleInput"
      :disabled="disabled"
    />
  </div>
</template>

<script setup>
// 1. 接收父组件传参
const props = defineProps({
  // 输入框类型（text/password/number）
  type: {
    type: String,
    default: 'text'
  },
  // 占位提示
  placeholder: {
    type: String,
    default: ''
  },
  // 绑定值（v-model）
  modelValue: {
    type: [String, Number],
    default: ''
  },
  // 标签文本
  label: {
    type: String,
    default: ''
  },
  // 是否禁用
  disabled: {
    type: Boolean,
    default: false
  }
})

// 2. 子传父：同步输入值（配合v-model使用）
const emit = defineEmits(['update:modelValue'])
const handleInput = (e) => {
  emit('update:modelValue', e.target.value)
}
</script>

<style scoped>
.custom-input {
  display: flex;
  align-items: center;
  margin: 10px 0;
}
.input-label {
  width: 80px;
  font-size: 14px;
  margin-right: 10px;
}
.input-content {
  padding: 6px 12px;
  border: 1px solid #ddd;
  border-radius: 4px;
  font-size: 14px;
  width: 200px;
}
.input-content:disabled {
  background: #f5f5f5;
  cursor: not-allowed;
}
</style>

组件使用示例（v-model绑定）

<template>
  <div>
    <Input 
      label="用户名" 
      placeholder="请输入用户名" 
      v-model="username"
    />
    <Input 
      label="密码" 
      type="password" 
      placeholder="请输入密码" 
      v-model="password"
    />
    <Input 
      label="手机号" 
      type="number" 
      placeholder="请输入手机号" 
      v-model="phone"
      disabled
    />
  </div>
</template>

<script setup>
import Input from '@/components/Input.vue'
import { ref } from 'vue'

const username = ref('')
const password = ref('')
const phone = ref('13800138000')
</script>

四、实战3：封装通用弹窗组件（Modal.vue）

<!-- src/components/Modal.vue -->
<template>
  <div class="modal-mask" v-if="visible" @click="handleMaskClick">
    &lt;div class="modal-content" @click.stop&gt;
      <!-- 弹窗标题 -->
      <div class="modal-header">
        <h3 class="modal-title">{{ title }}</h3>
        <button class="modal-close" @click="handleClose">×</button>
      </div>
      <!-- 弹窗内容（插槽，自定义） -->
      <div class="modal-body">
        <slot>默认弹窗内容</slot>
      </div&gt;
      <!-- 弹窗底部（插槽，自定义按钮） -->
      <div class="modal-footer">
        <slot name="footer">
          <Btn @click="handleClose">取消</Btn>
          <Btn type="primary" @click="handleConfirm">确认</Btn>
        </slot>
      </div>
    </div>
  </div>
</template>

<script setup>
import Btn from './Btn.vue' // 引入之前封装的按钮组件

// 接收父组件传参
const props = defineProps({
  // 是否显示弹窗
  visible: {
    type: Boolean,
    default: false
  },
  // 弹窗标题
  title: {
    type: String,
    default: '提示'
  },
  // 点击遮罩是否关闭
  maskClose: {
    type: Boolean,
    default: true
  }
})

// 子传父：关闭、确认事件
const emit = defineEmits(['close', 'confirm'])
// 关闭弹窗
const handleClose = () => {
  emit('close')
}
// 确认按钮
const handleConfirm = () => {
  emit('confirm')
}
// 点击遮罩关闭
const handleMaskClick = () => {
  if (props.maskClose) {
    emit('close')
  }
}
</script>

<style scoped>
/* 遮罩层 */
.modal-mask {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  background: rgba(0, 0, 0, 0.5);
  display: flex;
  align-items: center;
  justify-content: center;
  z-index: 999;
}
/* 弹窗内容 */
.modal-content {
  width: 400px;
  background: #fff;
  border-radius: 8px;
  overflow: hidden;
}
/* 弹窗标题 */
.modal-header {
  padding: 16px;
  border-bottom: 1px solid #eee;
  display: flex;
  justify-content: space-between;
  align-items: center;
}
.modal-title {
  font-size: 16px;
  margin: 0;
}
.modal-close {
  border: none;
  background: none;
  font-size: 20px;
  cursor: pointer;
  color: #999;
}
/* 弹窗内容 */
.modal-body {
  padding: 20px;
  font-size: 14px;
}
/* 弹窗底部 */
.modal-footer {
  padding: 16px;
  border-top: 1px solid #eee;
  display: flex;
  justify-content: flex-end;
  gap: 10px;
}
</style>

组件使用示例

<template>
  <div>
    <Btn type="primary" @click="showModal = true">打开弹窗</Btn>
    
    <Modal
      :visible="showModal"
      title="提示弹窗"
      :mask-close="false"
      @close="showModal = false"
      @confirm="handleConfirm"
    >
      <!-- 自定义弹窗内容 -->
      <p>确定要执行这个操作吗？</p>
      <Input placeholder="请输入备注" v-model="remark" />
      <!-- 自定义底部按钮（覆盖默认） -->
      <template #footer>
        <Btn @click="showModal = false">取消</Btn>
        <Btn type="danger" @click="handleDelete">删除</Btn>
        <Btn type="primary" @click="handleConfirm">确认</Btn>
      </template>
    </Modal>
  </div>
</template>

<script setup>
import Modal from '@/components/Modal.vue'
import Input from '@/components/Input.vue'
import Btn from '@/components/Btn.vue'
import { ref } from 'vue'

const showModal = ref(false)
const remark = ref('')

const handleConfirm = () => {
  console.log('确认操作，备注：', remark.value)
  showModal.value = false
}

const handleDelete = () => {
  console.log('执行删除操作')
  showModal.value = false
}
</script>

💡 小总结：组件封装=props传参+slot插槽+emit传事件，掌握这三点，能封装任何你需要的组件！

📌 第五篇：Vue3+Vite 优化实战（打包提速+页面优化）

Vue3+Vite 本身就比Vue2+Webpack快，但项目变大后仍会出现打包慢、页面卡顿，这篇汇总5个高频优化技巧，新手也能轻松操作，直接提升项目性能！

一、Vite 基础优化（打包提速）

1. 优化依赖预构建

Vite会预构建依赖，减少打包时间，修改vite.config.js配置，指定预构建的依赖：

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  // 优化依赖预构建
  optimizeDeps: {
    // 强制预构建的依赖（高频使用的第三方库）
    include: ['vue', 'vue-router', 'pinia', 'axios'],
    // 排除不需要预构建的依赖
    exclude: ['lodash-es']
  }
})

2. 打包压缩优化（减小体积）

安装压缩插件，打包时自动压缩JS/CSS/HTML，减小文件体积，提升加载速度：

# 安装压缩插件
npm install vite-plugin-compression --save-dev

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import compression from 'vite-plugin-compression'

export default defineConfig({
  plugins: [
    vue(),
    // 打包压缩（gzip格式）
    compression({
      algorithm: 'gzip', // 压缩算法
      threshold: 10240, // 超过10KB的文件才压缩
      deleteOriginFile: false // 不删除原文件
    })
  ]
})

二、代码层面优化（页面提速）

1. 组件懒加载（路由懒加载）

之前路由配置中提到的懒加载，是最核心的优化技巧，减少首页加载时间：

// router/index.js
// ❌ 错误：全部引入，首页加载慢
import Home from '@/views/Home.vue'
import About from '@/views/About.vue'

// ✅ 正确：懒加载，只有访问时才加载组件
const Home = () => import('@/views/Home.vue')
const About = () => import('@/views/About.vue')

// 进阶：分块打包（相同模块打包到一个文件）
const User = () => import(/* webpackChunkName: "user" */ '@/views/User.vue')
const UserInfo = () => import(/* webpackChunkName: "user" */ '@/views/UserInfo.vue')

2. 图片优化（减小图片体积）

Vite自带图片处理，配合插件优化图片，支持webp格式（体积更小）：

# 安装图片优化插件
npm install vite-plugin-imagemin --save-dev

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import imagemin from 'vite-plugin-imagemin'

export default defineConfig({
  plugins: [
    vue(),
    // 图片优化
    imagemin({
      gifsicle: {
        optimizationLevel: 7, // gif优化等级
        interlaced: false
      },
      optipng: {
        optimizationLevel: 7 // png优化等级
      },
      mozjpeg: {
        quality: 80 // jpg质量（0-100）
      },
      pngquant: {
        quality: [0.8, 0.9], // png质量范围
        speed: 4
      },
      svgo: {
        plugins: [
          { name: 'removeViewBox' },
          { name: 'removeEmptyAttrs', active: false }
        ]
      }
    })
  ],
  // 配置图片路径，优化加载
  assetsInclude: ['**/*.png', '**/*.jpg', '**/*.webp'],
  build: {
    assetsInlineLimit: 4096 // 小于4KB的图片转base64，减少请求
  }
})

3. 减少不必要的响应式数据

Vue3的响应式会消耗性能，非响应式数据不用ref/reactive包裹：

<script setup>
import { ref, reactive } from 'vue'

// ✅ 正确：非响应式数据，直接定义（不会变化的数据）
const staticData = {
  name: '手绘君',
  age: 20
}

// ✅ 正确：响应式数据，用ref/reactive（会变化的数据）
const count = ref(0)
const user = reactive({
  name: '测试君'
})
</script>

4. 虚拟列表（长列表优化）

当列表数据超过1000条时，会出现卡顿，用虚拟列表只渲染可视区域的内容：

# 安装虚拟列表插件（vue3专用）
npm install vue-virtual-scroller@next --save

<template>
  <!-- 虚拟列表组件 -->
  <RecycleScroller
    class="scroller"
    :items="longList" // 长列表数据
    :item-size="50" // 每个列表项的高度
    key-field="id" // 唯一标识字段
  >
    <template #default="{ item }">
      <div class="list-item">{{ item.name }}</div>
    </template>
  </RecycleScroller>
</template>

<script setup>
import { RecycleScroller } from 'vue-virtual-scroller'
import 'vue-virtual-scroller/dist/vue-virtual-scroller.css'

// 模拟10000条长列表数据
const longList = Array.from({ length: 10000 }, (_, i) => ({
  id: i + 1,
  name: `列表项 ${i + 1}`
}))
</script>

<style scoped>
.scroller {
  height: 500px; // 必须设置固定高度
  width: 100%;
}
.list-item {
  height: 50px; // 和item-size一致
  line-height: 50px;
  border-bottom: 1px solid #eee;
}
</style>

三、优化总结

• 🚀 打包优化：依赖预构建+压缩+图片优化，减小体积、提升打包速度

• 🚀 页面优化：路由懒加载+虚拟列表，减少首页加载时间、解决长列表卡顿

• 🚀 代码优化：减少不必要的响应式数据，降低性能消耗

💡 小技巧：优化后可以用 npm run build 查看打包体积，用浏览器开发者工具（Network）查看加载速度！

✏️ 合集持续更新ing，每篇都是爆款实用向，有错欢迎指出来～ 收藏起来，学Vue3不迷路！

（注：文档部分内容可能由 AI 生成）

JavaScript 异步编程进化史：从回调地狱到 async/await

前言

如果你问一个前端初学者："JavaScript 最让你头疼的是什么？"，十有八九会听到"异步编程"这个答案。从回调地狱到 Promise 链，再到如今优雅的 async/await，JavaScript 的异步编程经历了一场漫长的进化。今天，我们就来聊聊这段充满血泪的历史。

远古时期：同步的世界（1995-2009）

历史背景

1995 年，Brendan Eich 在 Netscape 公司用 10 天时间创造了 JavaScript（最初叫 LiveScript）。当时的设计初衷非常简单：为浏览器提供简单的页面交互能力，比如表单验证、按钮点击响应等。

那个年代，网页还很简单：

<!-- 1995 年的网页长这样 -->
<form onsubmit="return validateForm()">
  <input type="text" name="username" />
  <button type="submit">提交</button>
</form>

<script>
function validateForm() {
  var username = document.forms[0].username.value;
  if (username === '') {
    alert('用户名不能为空！');
    return false;
  }
  return true;
}
</script>

这个时期的 JavaScript 只需要处理简单的同步操作：

// 计算
var result = 1 + 2;

// DOM 操作
document.getElementById('btn').onclick = function() {
  alert('你点击了按钮');
};

// 表单验证
function validate(value) {
  return value.length > 0;
}

为什么只有同步？

因为当时的网页交互非常简单，不需要复杂的异步操作。即使有网络请求，也是通过表单提交刷新整个页面来完成的。

转折点：AJAX 的诞生

2005 年，Google 推出了 Gmail 和 Google Maps，展示了 AJAX（Asynchronous JavaScript and XML）的强大能力。突然间，网页可以在不刷新的情况下与服务器通信了！

这标志着 JavaScript 正式进入异步时代。

Callback 时期：回调地狱的噩梦（2005-2015）

标志性事件

• 2005 年：AJAX 技术被广泛应用
• 2009 年：Node.js 诞生，JavaScript 进入服务端，异步 I/O 成为核心
• 2010 年：回调函数成为异步编程的主流模式

解决的问题

回调函数让 JavaScript 能够处理异步操作，不会阻塞主线程：

// 发起网络请求
function getUserData(userId, callback) {
  var xhr = new XMLHttpRequest();
  xhr.open('GET', '/api/user/' + userId);
  
  xhr.onload = function() {
    if (xhr.status === 200) {
      callback(null, JSON.parse(xhr.responseText));
    } else {
      callback(new Error('请求失败'));
    }
  };
  
  xhr.send();
}

// 使用
getUserData(123, function(err, user) {
  if (err) {
    console.error(err);
    return;
  }
  console.log('用户信息:', user);
});

新的矛盾：回调地狱（Callback Hell）

当你需要执行多个依赖的异步操作时，代码会变成这样：

// 😱 真实的回调地狱代码
getUserData(123, function(err, user) {
  if (err) {
    console.error('获取用户失败:', err);
    return;
  }
  
  // 获取用户的订单列表
  getOrders(user.id, function(err, orders) {
    if (err) {
      console.error('获取订单失败:', err);
      return;
    }
    
    // 获取第一个订单的详情
    getOrderDetail(orders[0].id, function(err, detail) {
      if (err) {
        console.error('获取订单详情失败:', err);
        return;
      }
      
      // 获取订单中的商品信息
      getProducts(detail.productIds, function(err, products) {
        if (err) {
          console.error('获取商品失败:', err);
          return;
        }
        
        // 计算总价
        calculateTotal(products, function(err, total) {
          if (err) {
            console.error('计算总价失败:', err);
            return;
          }
          
          // 终于可以显示结果了！
          console.log('订单总价:', total);
        });
      });
    });
  });
});

回调地狱的痛点：

1. 代码横向发展：嵌套层级越来越深，形成"金字塔"结构
2. 错误处理重复：每一层都要写 if (err) 判断
3. 可读性极差：很难理解代码的执行流程
4. 难以维护：修改一个环节可能影响整个调用链
5. 调试困难：错误堆栈信息混乱

再看一个 Node.js 的例子：

// 😱 Node.js 文件操作的回调地狱
fs.readFile('config.json', 'utf8', function(err, config) {
  if (err) throw err;
  
  var parsedConfig = JSON.parse(config);
  
  fs.readFile(parsedConfig.dataFile, 'utf8', function(err, data) {
    if (err) throw err;
    
    var processedData = processData(data);
    
    fs.writeFile('output.json', JSON.stringify(processedData), function(err) {
      if (err) throw err;
      
      fs.readFile('output.json', 'utf8', function(err, result) {
        if (err) throw err;
        
        console.log('处理完成:', result);
      });
    });
  });
});

社区开始意识到：必须找到更好的方式来处理异步代码！

Promise 时期：链式调用的曙光（2012-2017）

标志性事件

• 2012 年：Promise/A+ 规范发布
• 2015 年：ES6 正式将 Promise 纳入标准
• 2015 年：各大浏览器开始原生支持 Promise

解决的问题

Promise 通过链式调用解决了回调地狱的嵌套问题：

// ✅ 使用 Promise 改写
getUserData(123)
  .then(user => getOrders(user.id))
  .then(orders => getOrderDetail(orders[0].id))
  .then(detail => getProducts(detail.productIds))
  .then(products => calculateTotal(products))
  .then(total => {
    console.log('订单总价:', total);
  })
  .catch(err => {
    console.error('出错了:', err);
  });

Promise 的优势：

1. 扁平化：不再横向嵌套，而是纵向链式调用
2. 统一错误处理：一个 .catch() 捕获所有错误
3. 状态管理：pending、fulfilled、rejected 三种状态清晰
4. 可组合：Promise.all()、Promise.race() 等工具方法

新的矛盾：Promise 链的三角形代码

虽然 Promise 解决了回调地狱，但在复杂场景下，仍然会出现新的问题：

// 😱 Promise 的三角形代码
function processUserOrder(userId) {
  return getUserData(userId)
    .then(user => {
      return getOrders(user.id)
        .then(orders => {
          return getOrderDetail(orders[0].id)
            .then(detail => {
              return getProducts(detail.productIds)
                .then(products => {
                  // 这里需要同时访问 user、orders、detail、products
                  return {
                    user: user,
                    orders: orders,
                    detail: detail,
                    products: products
                  };
                });
            });
        });
    })
    .then(result => {
      console.log('用户:', result.user.name);
      console.log('订单数:', result.orders.length);
      console.log('商品:', result.products);
    });
}

问题分析：

当你需要在后续步骤中访问前面的变量时，不得不：

1. 要么嵌套 Promise（又回到了嵌套地狱）
2. 要么在外层定义变量（污染作用域）

// 😱 方案1：嵌套 Promise（又回到地狱）
getUserData(userId)
  .then(user => {
    return getOrders(user.id)
      .then(orders => {
        return getOrderDetail(orders[0].id)
          .then(detail => {
            // 可以访问 user、orders、detail
            return processData(user, orders, detail);
          });
      });
  });

// 😱 方案2：污染外层作用域
let user, orders, detail;

getUserData(userId)
  .then(u => {
    user = u;
    return getOrders(user.id);
  })
  .then(o => {
    orders = o;
    return getOrderDetail(orders[0].id);
  })
  .then(d => {
    detail = d;
    // 现在可以访问 user、orders、detail
    return processData(user, orders, detail);
  });

其他痛点：

// 😱 条件分支变得复杂
getUserData(userId)
  .then(user => {
    if (user.isVip) {
      return getVipOrders(user.id)
        .then(orders => {
          return { user, orders, isVip: true };
        });
    } else {
      return getNormalOrders(user.id)
        .then(orders => {
          return { user, orders, isVip: false };
        });
    }
  })
  .then(result => {
    // 处理结果...
  });

// 😱 循环中的 Promise
function processItems(items) {
  let promise = Promise.resolve();
  
  items.forEach(item => {
    promise = promise.then(() => {
      return processItem(item);
    });
  });
  
  return promise;
}

社区再次呼唤：能不能像写同步代码一样写异步？

Async/Await 时期：异步编程的终极形态（2017-至今）

标志性事件

• 2017 年：ES8（ES2017）正式引入 async/await
• 2017 年：Node.js 7.6+ 原生支持 async/await
• 2018 年：主流浏览器全面支持

解决的问题

async/await 让异步代码看起来像同步代码：

// ✅ 使用 async/await 改写
async function processUserOrder(userId) {
  try {
    const user = await getUserData(userId);
    const orders = await getOrders(user.id);
    const detail = await getOrderDetail(orders[0].id);
    const products = await getProducts(detail.productIds);
    const total = await calculateTotal(products);
    
    console.log('订单总价:', total);
    
    // 可以轻松访问所有变量
    console.log('用户:', user.name);
    console.log('订单数:', orders.length);
    console.log('商品:', products);
    
  } catch (err) {
    console.error('出错了:', err);
  }
}

对比三个时代的代码：

// 😱 Callback 版本
getUserData(123, function(err, user) {
  if (err) return console.error(err);
  
  getOrders(user.id, function(err, orders) {
    if (err) return console.error(err);
    
    console.log('用户:', user.name);
    console.log('订单数:', orders.length);
  });
});

// 😐 Promise 版本
let user;
getUserData(123)
  .then(u => {
    user = u;
    return getOrders(user.id);
  })
  .then(orders => {
    console.log('用户:', user.name);
    console.log('订单数:', orders.length);
  })
  .catch(err => console.error(err));

// ✅ Async/Await 版本
async function process() {
  try {
    const user = await getUserData(123);
    const orders = await getOrders(user.id);
    
    console.log('用户:', user.name);
    console.log('订单数:', orders.length);
  } catch (err) {
    console.error(err);
  }
}

Async/Await 的优势

1. 代码可读性极高

// ✅ 像写同步代码一样清晰
async function checkout() {
  const cart = await getCart();
  const address = await getAddress();
  const payment = await processPayment(cart.total);
  const order = await createOrder(cart, address, payment);
  
  return order;
}

2. 错误处理更自然

// ✅ 使用熟悉的 try-catch
async function fetchData() {
  try {
    const data = await fetch('/api/data');
    const json = await data.json();
    return json;
  } catch (err) {
    console.error('请求失败:', err);
    throw err;
  }
}

3. 条件分支更简洁

// ✅ 条件判断很自然
async function processUser(userId) {
  const user = await getUserData(userId);
  
  if (user.isVip) {
    const vipOrders = await getVipOrders(user.id);
    return processVipOrders(vipOrders);
  } else {
    const normalOrders = await getNormalOrders(user.id);
    return processNormalOrders(normalOrders);
  }
}

4. 循环处理更直观

// ✅ 顺序处理
async function processItems(items) {
  for (const item of items) {
    await processItem(item);
  }
}

// ✅ 并行处理
async function processItemsParallel(items) {
  await Promise.all(items.map(item => processItem(item)));
}

5. 调试体验更好

// ✅ 可以直接打断点，查看变量
async function debug() {
  const user = await getUserData(123);
  debugger; // 可以在这里查看 user
  
  const orders = await getOrders(user.id);
  debugger; // 可以在这里查看 orders
  
  return orders;
}

实战案例

案例 1：文件处理

// Callback 版本 😱
fs.readFile('input.txt', 'utf8', function(err, data) {
  if (err) throw err;
  
  const processed = processData(data);
  
  fs.writeFile('output.txt', processed, function(err) {
    if (err) throw err;
    
    fs.readFile('output.txt', 'utf8', function(err, result) {
      if (err) throw err;
      console.log('完成:', result);
    });
  });
});

// Async/Await 版本 ✅
async function processFile() {
  try {
    const data = await fs.promises.readFile('input.txt', 'utf8');
    const processed = processData(data);
    await fs.promises.writeFile('output.txt', processed);
    const result = await fs.promises.readFile('output.txt', 'utf8');
    console.log('完成:', result);
  } catch (err) {
    console.error('出错:', err);
  }
}

案例 2：并发请求

// Promise 版本 😐
Promise.all([
  fetch('/api/user'),
  fetch('/api/orders'),
  fetch('/api/products')
])
  .then(responses => {
    return Promise.all(responses.map(r => r.json()));
  })
  .then(([user, orders, products]) => {
    console.log(user, orders, products);
  });

// Async/Await 版本 ✅
async function fetchAll() {
  const [user, orders, products] = await Promise.all([
    fetch('/api/user').then(r => r.json()),
    fetch('/api/orders').then(r => r.json()),
    fetch('/api/products').then(r => r.json())
  ]);
  
  console.log(user, orders, products);
}

案例 3：错误重试

// ✅ 实现带重试的请求
async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url);
      return await response.json();
    } catch (err) {
      if (i === maxRetries - 1) throw err;
      console.log(`重试 ${i + 1}/${maxRetries}`);
      await sleep(1000 * (i + 1)); // 指数退避
    }
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

常见陷阱与最佳实践

陷阱 1：忘记 await

// ❌ 错误：忘记 await
async function bad() {
  const data = fetchData(); // 返回 Promise，不是数据！
  console.log(data); // Promise { <pending> }
}

// ✅ 正确
async function good() {
  const data = await fetchData();
  console.log(data); // 实际数据
}

陷阱 2：串行执行导致性能问题

// ❌ 错误：串行执行，耗时 3 秒
async function slow() {
  const user = await fetchUser();      // 1 秒
  const orders = await fetchOrders();  // 1 秒
  const products = await fetchProducts(); // 1 秒
  return { user, orders, products };
}

// ✅ 正确：并行执行，耗时 1 秒
async function fast() {
  const [user, orders, products] = await Promise.all([
    fetchUser(),
    fetchOrders(),
    fetchProducts()
  ]);
  return { user, orders, products };
}

陷阱 3：循环中的 await

// ❌ 错误：串行处理，很慢
async function processItemsSlow(items) {
  const results = [];
  for (const item of items) {
    results.push(await processItem(item)); // 一个一个处理
  }
  return results;
}

// ✅ 正确：并行处理，快速
async function processItemsFast(items) {
  return await Promise.all(items.map(item => processItem(item)));
}

陷阱 4：错误处理不当

// ❌ 错误：错误被吞掉
async function bad() {
  await fetchData(); // 如果出错，错误会被忽略
}

// ✅ 正确：捕获错误
async function good() {
  try {
    await fetchData();
  } catch (err) {
    console.error('出错:', err);
    throw err; // 或者处理错误
  }
}

进化史总结

未来展望

虽然 async/await 已经很完美，但 JavaScript 的异步编程仍在进化：

1. Top-level await（ES2022）

// ✅ 模块顶层直接使用 await
const data = await fetch('/api/data');
export default data;

2. AsyncIterator 和 for-await-of

// ✅ 异步迭代器
async function* generateData() {
  for (let i = 0; i < 10; i++) {
    await sleep(100);
    yield i;
  }
}

for await (const num of generateData()) {
  console.log(num);
}

3. Promise.allSettled / Promise.any

// ✅ 等待所有 Promise 完成（无论成功失败）
const results = await Promise.allSettled([
  fetch('/api/1'),
  fetch('/api/2'),
  fetch('/api/3')
]);

// ✅ 返回第一个成功的 Promise
const fastest = await Promise.any([
  fetch('/api/1'),
  fetch('/api/2'),
  fetch('/api/3')
]);

总结

从回调地狱到 async/await，JavaScript 的异步编程经历了三次重大进化：

1. Callback：解决了异步问题，但带来了回调地狱
2. Promise：解决了回调地狱，但带来了三角形代码
3. Async/Await：让异步代码像同步代码一样优雅

如今，async/await 已经成为 JavaScript 异步编程的事实标准。它不仅解决了前辈们的问题，还提供了极佳的开发体验。

最佳实践建议：

• ✅ 优先使用 async/await
• ✅ 注意并行执行优化性能
• ✅ 使用 try-catch 处理错误
• ✅ 理解 Promise 的底层原理
• ✅ 善用 Promise.all/race/allSettled/any

异步编程的进化史告诉我们：好的语言特性不是一蹴而就的，而是在不断解决实际问题中逐步完善的。

如果这篇文章对你有帮助，欢迎点赞收藏！有任何问题欢迎在评论区讨论 🎉

参考资料

• MDN - async function
• Promise/A+ 规范
• ECMAScript 2017 Language Specification
• JavaScript: The First 20 Years

ps.本文中的第八条包含讲解所用到的所有代码。

一、先忘掉已知编码“模式”，想一个真实问题

假设现在要写一个人员列表页：

• 上面有搜索框（姓名、账号、手机号）
• 中间一个表格（数据 + 分页）
• 每一行有：编辑、分配角色、改密码、删除
• 点编辑/改密码/分配角色会弹出对话框

如果全写在一个 .vue 文件里，会怎样？

• <template> 还好，主要是布局
• <script> 里会堆满：搜索表单数据、表格数据、分页、好几个弹窗的显示/隐藏、每个按钮的点击函数、每个弹窗的确认/关闭……

一个文件动不动就 500 行、几十个变量和函数，改一处要翻半天，也不好复用。

所以我们要解决的是两件事：

1. 把“逻辑”从“页面”里拆出来，让页面只负责“长什么样、点哪里”
2. 拆出来的逻辑要能复用，比如别的页面也要“列表+分页+弹窗”时可以直接用

这种「逻辑从页面里抽出去、按功能组织、可复用」的写法，在 Vue 3 里就对应两样东西：

• 组合式 API：用 ref、reactive、onMounted 等写逻辑的方式
• 组合式函数（Composables） - 音标：/kəm'pəuzəblz/：把一段逻辑封装成一个“以 use 开头的函数”，在页面里调一下就能用

下面分步讲。

二、第一步：认识“组合式 API”（在页面里写逻辑）

以前 Vue 2 常见的是「选项式 API」：一个组件里分好几块 —— data、methods、mounted 等，逻辑按“类型”分，而不是按“功能”分。

Vue 3 的组合式 API 换了一种思路：在 setup（或 <script setup>）里，像写普通 JS 一样，用变量和函数把“和某块功能相关的所有东西”写在一起。

例如“搜索”这一块功能，可以这样写在一起：

// 和“搜索”相关的都放一起
const searchForm = reactive({ userName: '', userAccount: '' })
const handleSearch = () => { /* 调用接口、刷新列表 */ }
const handleReset = () => { searchForm.userName = ''; ... }

“分页”又是一块：

const pagination = reactive({ currentPage: 1, pageSize: 10, total: 0 })
const handleSizeChange = (val) => { ... }
const handleCurrentChange = (val) => { ... }

这样写，同一个功能的数据和函数挨在一起，读起来是“一块一块”的，而不是 data 一堆、methods 又一堆。这就是“组合式”的意思：按逻辑块组合，而不是按选项类型分。

用到的两个基础工具要知道：

• ref(值)：存“一个会变的值”，用的时候要 .value；在模板里可以省略 .value
• reactive(对象)：存“一组会变的属性”，用的时候直接 .属性名 就行

到这里，你只需要记住：在 <script setup> 里用 ref/reactive + 函数，把同一块功能的逻辑写在一起，这就是“组合式 API”的用法。

三、第二步：逻辑太多时，把“一整块”搬出去

当这一页的逻辑越来越多（搜索、表格、分页、编辑弹窗、改密码弹窗、角色弹窗……），<script setup> 里会变得很长。下一步很自然：把“一整块逻辑”原样搬到一个单独的 .ts 文件里。

做法就三步：

1. 新建一个文件，比如 usePersonnelList.ts
2. 在里面写一个函数，函数名按约定用 use 开头，比如 usePersonnelList
3. 把原来在页面里的那一大坨（ref、reactive、所有 handleXxx）剪过去，放进这个函数里，最后 return 出页面需要用的东西

例如：

// usePersonnelList.ts
import { ref, reactive } from 'vue'

export function usePersonnelList() {
  const searchForm = reactive({ userName: '', userAccount: '' })
  const tableData = reactive([])
  const handleSearch = () => { ... }
  const handleReset = () => { ... }
  // ... 其他状态和方法

  return {
    searchForm,
    tableData,
    handleSearch,
    handleReset,
    // 页面要用啥就 return 啥
  }
}

页面里就只做一件事：调用这个函数，把 return 出来的东西拿来用：

<script setup>
import { usePersonnelList } from './composables/usePersonnelList'

const {
  searchForm,
  tableData,
  handleSearch,
  handleReset,
} = usePersonnelList()
</script>

<template>
  <!-- 用 searchForm、tableData，绑定 handleSearch、handleReset -->
</template>

这种“以 use 开头、封装一块有状态逻辑、return 给组件用”的函数，官方名字就叫「组合式函数」（Composable，英文文档里会看到这个词）。

当前看到的「编码模式」核心就是：页面只负责布局和调用 useXxx()，具体逻辑都在 useXxx 里。

可能有的同学看到 状态 这个词的时候不能理解，不能理解的同学我想应该同样也想不明白vuex或pinia为什么叫状态管理而不叫变量管理或者常量管理或者容器管理。可以理解的同学可直接看下一步，接下来的小内容则是给不能理解的同学补补课。

讲解：首先状态和变量一样，都是存储数据的容器。区别在于状态和 UI 是 “双向绑定” 的，变量不一定。普通 JS 变量（比如 let a = 1）改了就是改了，页面不会有任何反应；但 Vue 的状态（比如 const a = ref(1)）改 a.value = 2 时，页面里用到 a 的地方会自动更新 —— 这是 “状态” 最核心的特征：状态是 “活的”，和 UI 联动。

简单粗暴:

• 所以不理解的同学可以简单粗暴的将状态理解为可以引动UI变化的变量就是状态。 新手同学理解到这里就可以了，至于状态更精准的理解感兴趣的同学可以自行搜索学习。

不用过多的纠结，可以理解这个简单粗暴的定义就足够你看懂后面的讲解了。

四、用一句话串起来

• 组合式 API：在 script 里用 ref/reactive + 函数，按“功能块”写逻辑。
• 组合式函数：把某一整块逻辑搬进 useXxx()，页面里 const { ... } = useXxx() 拿来用。

所以：
“组合式 API”是说“怎么写逻辑”；“组合式函数”是说“把写好的逻辑封装成 useXxx，方便复用和组织”。
当前人员模块的写法，就是：用组合式 API 在 usePersonnelList 里写逻辑，在 index.vue 里只调用 usePersonnelList()，这就是官方主推的这种模式。

五、和当前示例对上号