普通视图

发现新文章，点击刷新页面。

今天 — 2026年5月7日掘金前端

10.响应式系统演进：通过位运算优化动态依赖收集（Vue3.2）

掘金前端

作者 Cobyte

2026年5月7日 09:17

前言

在 Vue3.2 的版本里面还通过位运算优化动态依赖收集的性能，那么具体是怎么做的呢？首先我们来看看原来为什么会存在性能问题，我们回顾一下第5篇文章讲解 Vue3 响应式原理的时候，在收集依赖的时候有以下一段代码。

首先是只要存在 activeEffect 变量，我们就会往 deps 中添加依赖，如果存在重复的依赖，会利用 Set 数据的特性来去重。目前这种依赖管理方式在高频更新或深层递归场景下存在性能瓶颈。具体表现为副作用函数（effect）的依赖可能随条件分支动态变化。例如：

const state = reactive({ a: '掘金签约作者', b: 'Cobyte', flag: true })

effect(() => {
  if (state.flag) {
    // 依赖 state.a
    console.log(state.a);
  } else {
    // 依赖 state.b
    console.log(state.b);
  }
});

state.flag = false
state.a = '小前端'

我们运行上述例子，结果如下：

掘金签约作者
Cobyte
Cobyte

从上述测试结果我们可以看到当设置 state.flag 为 true 时，打印了 Cobyte，这是正确的，但当改变state.a 值时，也打印了 Cobyte，其实当 state.flag 为 true 时，该副作用就跟 state.a 没有关系了，因为不管 state.a 的值怎么变，副作用的打印结果都是一样的，所以此时当 state.a 改变就触发副作用更新的行为就是浪费性能。

所以我们目前的实现存在以下问题，当 state.flag 变化时，依赖需从 state.a 切换到 state.b 时无法自动清理过期依赖，导致冗余触发而引发性能瓶颈。

对此 Vue3.2 创新性地引入 位运算（Bitwise Operations）优化依赖收集，解决了动态依赖切换导致的冗余依赖问题，从而大幅提升了响应式系统的性能。本文将从设计背景、实现原理、性能优势等方面展开分析，揭示位运算在这一场景下的核心价值。

此外对位运算还不熟的同学，可以先复习一下位运算相关知识。

为什么要使用位运算来设计依赖优化？

我们在前言的例子中讲到当 state.flag 变化时，依赖需从 state.a 切换到 state.b，传统 Set 数据结构无法自动清理过期依赖，导致冗余依赖。那么怎么实现自动清理过期的依赖呢？

普通实现方案

原来的数据结构如下：

那么实现这个清除失效的依赖，按我们普通的实现方案可以这样设计，设计一个记录该依赖在 之前的层级 是否被追踪的变量 wasSet = new Set()；再设计一个记录该依赖在 当前层级 是否被追踪的变量 newSet = new Set()；这样我们在一轮循环中判断是否记录新的依赖的时候，先往变量 newSet 中添加该依赖，再从 wasSet 变量中判断是否已经存在该依赖，如果已经存在，那么就不再记录，如果不存在，那么就需要往原来记录依赖的变量 deps 中添加新的依赖。这样在一轮循环的最后，再去判断该依赖如果只存在 wasSet 变量中，而没有在 newSet 变量中时，则说明该依赖需要从 deps 变量中清除掉了，这样将来该依赖发生变化都不会响应式到渲染函数的重新执行。那么 wasSet 中的数据怎么来呢？可以在初始化的时候从 deps 中进行赋值。

我们上面通过文字描述大概讲了一遍普通方案的实现，那么我现在通过伪代码再还原展示一偏。

状态记录相关变量：

wasSet: Set<Dep> ：记录上一轮执行中所有被追踪的依赖。
newSet: Set<Dep> ：记录当前轮次执行中所有被追踪的依赖。
deps: Dep[] ：实际存储依赖的集合。

初始化阶段：

wasSet = new Set(deps); // 初始化为上一轮的依赖  
newSet = new Set();

依赖收集阶段：

if (!newSet.has(dep)) {  
  newSet.add(dep);  
  if (!wasSet.has(dep)) {  
    deps.push(dep); // 新增依赖  
  }  
}

依赖清理阶段：

for (const dep of wasSet) {  
  if (!newSet.has(dep)) {  
    deps.splice(deps.indexOf(dep), 1); // 移除失效依赖  
  }  
}  
wasSet = newSet; // 更新历史状态

从上述伪代码可以清晰看出通过比对 wasSet 和 newSet 的差异，移除不再被使用的依赖，从而实现了条件分支的支持。

但这种普通方案存在以下性能瓶颈：

内存开销：
- 需维护多个 Set 实例（wasSet、newSet），存储大量依赖时内存占用高。
- 每次递归层级变化需复制依赖集合（如 wasSet = new Set(deps)）。
操作效率：
- 集合操作：has、add、delete 的时间复杂度为 O(1)，但哈希表操作仍存在性能损耗（如哈希碰撞）。
- 清理阶段：遍历 wasSet 并检查 newSet 的时间复杂度为 O(n²)。
递归层级管理：
- 深层递归时需为每层维护独立的 Set，内存和计算开销指数级增长。

所以 Vue3 并没有采用这种实现方式，那么接下来让我们继续探讨 Vue3 的实现方案吧。

位运算优化方案（Vue3 实现）

在 Vue3 中则巧妙地创建一个兼具 依赖存储 和 追踪状态标记 的复合数据结构的变量。设计如下：

通过扩展 Set 而非创建全新数据结构，复用 Set 的高效存储，仅添加 wasTracked 和 newTracked 两个整数字段，就创建一个兼具 依赖存储 和 追踪状态标记 的复合数据结构了。具体 wasTracked 和 newTracked 两个字段的作用是：

wasTracked：记录该依赖在 之前的层级 是否被追踪。
newTracked：记录该依赖在 当前层级 是否被追踪。

wasTracked 和 newTracked 的值都是一个二进制数字，例如：若某依赖在之前的层级（如父组件渲染）中被访问过，wasTracked 对应的位会被标记；newTracked 则是在当前渲染中如果被访问了，对应的位也会被标记。

那么为什么要使用位运算来设计呢？我们从传统的权限管理的痛点说起，因为上述的依赖优化管理机制与权限系统的位掩码设计异曲同工。

假设需要为一个用户管理系统设计权限控制，包含以下权限：

读（R） ：0b001（二进制） → 1（十进制）
写（W） ：0b010 → 2
执行（X） ：0b100 → 4

传统实现方式：

const userPermissions = {
  read: true,
  write: false,
  execute: true
};

// 检查是否有读权限
if (userPermissions.read) { /* ... */ }

这种方案存在以下问题：

存储冗余：每个权限需独立布尔字段，内存占用高。
组合权限复杂：判断用户是否同时有读和执行权限需多次检查。
扩展性差：新增权限（如 admin）需修改数据结构。

使用位运算设计权限管理系统：

通过 位掩码（Bitmask） 将权限编码为单个整数：

// 权限定义
const PERMISSIONS = {
  READ: 0b001,   // 1
  WRITE: 0b010,  // 2
  EXECUTE: 0b100 // 4
};

用户初始权限：

// 用户权限（初始为 0）
let userPermissions = 0;

添加读和执行权限：

// 添加读和执行权限
userPermissions |= PERMISSIONS.READ;    // 0b001 → 1
userPermissions |= PERMISSIONS.EXECUTE; // 0b101 → 5

检查是否有写权限：

const hasWrite = (userPermissions & PERMISSIONS.WRITE) > 0; // false

检查是否有读和执行权限：

const hasReadAndExecute = 
  (userPermissions & (PERMISSIONS.READ | PERMISSIONS.EXECUTE)) 
  === (PERMISSIONS.READ | PERMISSIONS.EXECUTE); // true

优势分析

(1) 内存高效

传统方式：每个权限占用一个布尔值（通常 4 字节）。
位运算：所有权限压缩为单个整数（4 字节），内存占用减少 75% 。

(2) 操作快速

添加权限：userPermissions |= PERMISSIONS.WRITE（O(1)）。
移除权限：userPermissions &= ~PERMISSIONS.WRITE（O(1)）。
检查权限：按位与操作（O(1)）。

(3) 组合权限灵活

// 检查是否同时有读和写权限
const required = PERMISSIONS.READ | PERMISSIONS.WRITE;
const hasAll = (userPermissions & required) === required;

那么根据上述权限系统的实现的启发，我们就可以设计如果当前依赖层级为 1，那么历史层级的追踪状态变量 wasTracked 就会被设置为 0b1，当前层级为 2 那么 wasTracked 就会被设置为 0b10，同样地 3，4 ... 层就会被设置为 0b100、0b1000，如果一个变量在1、2、3、4层都被引用，那么 wasTracked 就会被设置为：0b1111。同样地当前层级的追踪状态 newTracked 也是如此设计。

同样地，层级变量也可以使用二进制表示，比如，1层为：0b1；2层为：0b10；3层为：0b100。这样标记和判断等相关操作都可以通过位运算进行。比如当前层级为2，那么 层级变量 = 0b10，那么标记添加则是 wasTracked = wasTracked | 0b10；而判断当前历史层级是否已被标记则是 has = wasTracked & 0b10。

位运算的原子性操作（如 |=、&）速度远超传统 Set 的操作（如遍历、过滤），且位运算具有极致的性能优势，这就是为什么使用为什么要使用位运算来设计依赖优化。

组件嵌套的 effect 实现原理

我们前面讲到多层嵌套的 effect，会存在内存占用高操作缓慢的缺点。而我们前面实现的 Vue3 响应式源码是还没实现嵌套 effect 的，所以我们先要实现嵌套 effect。例如下面的例子：

window.state = reactive({ parent: 'parent', child: 'child' })
effect(() => {
    effect(() => {
        console.log(`我是子组件：${state.child}`)
    })
  console.log(`我是父组件：${state.parent}`)
})

执行结果如下：

我们给 state.child 重新赋值：

这时子组件的 effect 执行了，这是正常的。

接著我们给 state.parent 重新赋值：

这时我们发现父组件的 effect 不执行了。这是为什么呢？我们来观察一下我们之前实现的 ReactiveEffect 类：

class ReactiveEffect {
    deps = []
    constructor(fn) {
        this._fn = fn
    }
    run () {
        activeEffect = this
        this._fn()
        activeEffect = null
    }
    stop () {
      this.deps.forEach(dep => dep.delete(this))
    }
}

我们知道 activeEffect 变量是唯一的，当嵌套之后，子组件执行完之后，activeEffect 将被设置了 null，这时父组件如果还有响应式数据需要收集的时候，由于 activeEffect 为 null 而会导致父组件的响应式数据的依赖收集不到。

为了解决这个问题，Vue3 底层设置了一个副作用函数栈变量 effectStack，我们要确保 activeEffect 始终指向当前正在运行的响应式副作用 effect。实现代码如下：

// 用于管理嵌套 effect 的调用栈
const effectStack = []
class ReactiveEffect {
    // 存储所有包含本 effect 的依赖集合（Set）
    // 用于实现 stop 功能时快速清理依赖
    deps = []
    constructor(fn) {
        // 包装的副作用函数（开发者传入的原始函数）
        this._fn = fn
    }
    // 执行副作用函数，并触发依赖收集
    run () {
        // 这里为什么要用try...finally呢？比如如果_fn中有错误，finally块仍然会执行，保证栈的平衡。
        try {
            // 1. 设置当前激活的 effect 为自身
            activeEffect = this;
            // 2. 压入 effect 调用栈（处理嵌套 effect 的关键）
            effectStack.push(this);
            // 3. 执行原始函数，触发响应式属性的 getter，进行依赖收集
            return this._fn(); // 返回函数执行结果（支持 computed 等场景）
        } finally {
            // 4. 无论执行是否抛出异常，确保以下清理逻辑一定执行
            effectStack.pop(); // 当前 effect 出栈
            // 5. 恢复 activeEffect 为上一个 effect（栈顶元素）或 undefined
            activeEffect = effectStack.length > 0 ? effectStack[effectStack.length - 1] : undefined;
        }
    }
    // 停止当前 effect 的响应式追踪
    stop () {
      // 遍历所有关联的依赖集合，从中删除本 effect
      this.deps.forEach(dep => dep.delete(this))
    }
}

主要的实现思路也很简单，就是在执行原始函数之前，先把当前的响应式副作用压入 effectStack 调用栈，通过使用 try...finally 确保无论 this._fn() 是否抛出异常，effectStack 都会被正确弹出，activeEffect 会被恢复为上一个响应式副作用 effect 或 undefined。这样通过维护 effectStack，确保嵌套的响应式副作用 effect 的执行顺序正确，activeEffect 变量始终指向当前正在运行的响应式副作用 effect。

我们再来看看迭代后的执行结果：

我们可以看到当父组件的响应式变量 parent 被改变后，相关的嵌套代码都被执行了。

到此，我们就实现了嵌套 effect。

依赖标记流程

初始化依赖的追踪状态标记

初始化依赖的追踪状态标记的核心逻辑就是在副作用函数执行前，记录所有 已有依赖 的追踪状态，即某个依赖在 上一轮执行 中被追踪过，其对应的位会被标记到 wasTracked 中。具体就是将每个依赖的 wasTracked 字段的 当前层级对应位 设为 1。我们可以设置一个全局变量 effectTrackDepth 来表示当前副作用执行的 递归深度，也就是所谓层级，初始为 0，每递归一次就增加 1。在每一轮的副作用函数执行前，将全局递归深度加 1，表示进入新一层级，执行完副作用函数后，将全局递归深度减 1，表示返回到上一层级的执行环境。

然后通过位运算 1 << effectTrackDepth 生成一个二进制掩码，也就是 第 effectTrackDepth 位为 1，其余位为 0。例如，若 effectTrackDepth = 2，则掩码为 0b100（十进制 2）。这样每个递归层级 effectTrackDepth 对应独立的二进制位，避免嵌套 effect 的依赖状态相互干扰。最后通过按位或操作（|），将 wasTracked 的对应二进制位设为 1，其他位保持不变。

具体代码实现如下：

// 用于管理嵌套 effect 的调用栈
const effectStack = []
+ // 当前副作用执行的递归深度
+ let effectTrackDepth = 0
class ReactiveEffect {
    // 存储所有包含本 effect 的依赖集合（Set）
    // 用于实现 stop 功能时快速清理依赖
    deps = []
    constructor(fn) {
        // 包装的副作用函数（开发者传入的原始函数）
        this._fn = fn
    }
    // 执行副作用函数，并触发依赖收集
    run () {
        // 这里为什么要用try...finally呢？比如如果_fn中有错误，finally块仍然会执行，保证栈的平衡。
        try {
            // 1. 设置当前激活的 effect 为自身
            activeEffect = this;
            // 2. 压入 effect 调用栈（处理嵌套 effect 的关键）
            effectStack.push(this);
+            // 将全局递归深度加 1，表示进入新一层级
+            effectTrackDepth++;
+            // 初始化标记
+            this.initDepMarkers();
            // 3. 执行原始函数，触发响应式属性的 getter，进行依赖收集
            return this._fn(); // 返回函数执行结果（支持 computed 等场景）
        } finally {
+            // 将全局递归深度减 1，表示返回到上一层级的执行环境 
+            effectTrackDepth--;
            // 4. 无论执行是否抛出异常，确保以下清理逻辑一定执行
            effectStack.pop(); // 当前 effect 出栈
            // 5. 恢复 activeEffect 为上一个 effect（栈顶元素）或 undefined
            activeEffect = effectStack.length > 0 ? effectStack[effectStack.length - 1] : undefined;
        }
    }
    // 停止当前 effect 的响应式追踪
    stop () {
      // 遍历所有关联的依赖集合，从中删除本 effect
      this.deps.forEach(dep => dep.delete(this))
    }
+    // 初始化依赖的追踪状态标记
+    initDepMarkers() {
+        const { deps } = this
+        if (deps.length) {
+            for (let i = 0; i < deps.length; i++) {
+                // 若某个依赖在 上一轮执行 中被追踪过，其对应的位会被标记到 wasTracked 中
+                deps[i].wasTracked = deps[i].wasTracked | 1 << effectTrackDepth
+            }
+        }
+    }
}

小结一下：当副作用函数 effect 执行时，会进入不同的递归层级，每个层级对应一个位。在初始化时，会通过 initDepMarkers 方法设置对应依赖的 wasTracked 属性的位，表示上一轮这个依赖是否被跟踪。

通过位运算判断是否收集依赖

我们在之前的依赖收集的判断逻辑是这样的，判断全局变量 activeEffect 是否存在，存在就进行收集，那么现在我们要判断当前依赖的当前层级是否标记该依赖为已追踪，也就是 deps.newTracked 的对应层级 (1 << effectTrackDepth) 是否为 1。这就要通过与运算（&）来判断。我们通过封装一个函数来实现这个功能，代码如下：

function newTracked(dep) {
  return (dep.newTracked & (1 << effectTrackDepth)) !== 0;
}

若当前层级未标记该依赖为已追踪（!newTracked(dep)），则需要将当前依赖 newTracked 设置为当前层级 (1 << effectTrackDepth) ，也就是标记为 1。我们通过封装一个函数来实现这个功能，代码如下：

function setNewTracked(dep) {
  dep.newTracked |= (1 << effectTrackDepth); // 按位或操作
}

最后我们还要检查依赖的 wasTracked 字段的当前层级(1 << effectTrackDepth) 对应是否为 1（即是否在上一轮执行中被追踪过）。我们通过封装一个函数来实现这个功能，代码如下：

function wasTracked(dep) {
  return (dep.wasTracked & (1 << effectTrackDepth)) !== 0;
}

整体代码迭代如下：

function track(target, key) {
    let depsMap = targetMap.get(target)
    if (!depsMap) {
        depsMap = new Map()
        targetMap.set(target, depsMap)
    }
    let deps = depsMap.get(key)
    if (!deps) {
      deps = new Set()
      // 标记依赖在 上一轮执行周期 中是否被追踪
      deps.wasTracked = 0
      // 标记依赖在 当前执行周期 中是否被追踪
      deps.newTracked = 0
      depsMap.set(key, deps)
    }
-    if (activeEffect) {
-        deps.add(activeEffect)
-        activeEffect.deps.push(deps)
-    }
+    trackEffects(deps)
}

+ function trackEffects(dep) {
+     let shouldTrack = false
+     if (!newTracked(dep)) {
+      setNewTracked(dep)
+      shouldTrack = !wasTracked(dep)
+    }

+    if (shouldTrack) {
+        dep.add(activeEffect)
+        activeEffect.deps.push(dep)
+    }
+ }

+ function newTracked(dep) {
+   return (dep.newTracked & (1 << effectTrackDepth)) !== 0;
+ }

+ function setNewTracked(dep) {
+   dep.newTracked |= (1 << effectTrackDepth); // 按位或操作
+ }

+ function wasTracked(dep) {
+   return (dep.wasTracked & (1 << effectTrackDepth)) !== 0;
+ }

在执行 effect 函数的过程中，当访问响应式属性时，会调用 track 函数，进而调用 trackEffects，设置 newTracked 的位，表示当前层级这个 dep 被跟踪了。

接着我们测试一下我们写的代码，测试代码如下：

window.state = reactive({ flag: false,  a: 'parent', b: 'child' })
effect(() => {
  if (state.flag) {
    console.log(`条件一：${state.a}`);
  } else {
    console.log(`条件二：${state.b}`);
  }
});

我们运行上面的测试代码，结果输出：条件二：child。这是正确的输出结果。说明我们上述的迭代代码是正确的。

我们现在改变 flag 的值， state.flag = true，结果输出：条件一：parent。这也是正确的输出结果。这时我们再改变 b 的值， state.b = '掘金签约作者'，结果输出：条件一：parent，这个结果不是我们期待的，因为 b 属性我们已经不再使用了，b 属性值的改变不应该再触发更新才对。所以我们还要实现最后一个功能，通过位运算实现动态依赖的精准管理。

实现动态依赖精准管理

我们通过上文知道当effect执行时，会进入不同的递归层级，每个层级对应一个位。在初始化时，会通过initDepMarkers方法设置wasTracked的位，表示上一轮这个dep是否被跟踪。然后在执行effect函数的过程中，当访问响应式属性时，会调用track函数，进而调用trackEffects，设置newTracked的位，表示当前层级这个dep被跟踪了。

我们现在需要做的就是比较这两个标记，如果一个dep在之前被跟踪（wasTracked为真），但在当前没有被跟踪（newTracked为假），说明这个dep在当前层级不再被需要，因此需要从dep的集合中移除这个effect。这样我们就可以实现清理那些不再被依赖的effect，防止内存泄漏和无效的触发。

代码迭代如下：

// 用于管理嵌套 effect 的调用栈
const effectStack = []
let effectTrackDepth = 0
class ReactiveEffect {
    // 存储所有包含本 effect 的依赖集合（Set）
    // 用于实现 stop 功能时快速清理依赖
    deps = []
    constructor(fn) {
        // 包装的副作用函数（开发者传入的原始函数）
        this._fn = fn
    }
    // 执行副作用函数，并触发依赖收集
    run () {
        // 这里为什么要用try...finally呢？比如如果_fn中有错误，finally块仍然会执行，保证栈的平衡。
        try {
            // 1. 设置当前激活的 effect 为自身
            activeEffect = this;
            // 2. 压入 effect 调用栈（处理嵌套 effect 的关键）
            effectStack.push(this);
            // 
            effectTrackDepth++;
            // 初始化标记
            this.initDepMarkers();
            // 3. 执行原始函数，触发响应式属性的 getter，进行依赖收集
            return this._fn(); // 返回函数执行结果（支持 computed 等场景）
        } finally {
+            this.finalizeDepMarkers();
            effectTrackDepth--;
            // 4. 无论执行是否抛出异常，确保以下清理逻辑一定执行
            effectStack.pop(); // 当前 effect 出栈
            // 5. 恢复 activeEffect 为上一个 effect（栈顶元素）或 undefined
            activeEffect = effectStack.length > 0 ? effectStack[effectStack.length - 1] : undefined;
        }
    }
    // 停止当前 effect 的响应式追踪
    stop () {
      // 遍历所有关联的依赖集合，从中删除本 effect
      this.deps.forEach(dep => dep.delete(this))
    }
    // 初始化依赖的追踪状态标记
    initDepMarkers() {
        const { deps } = this
        if (deps.length) {
            for (let i = 0; i < deps.length; i++) {
                // 若某个依赖在 上一轮执行 中被追踪过，其对应的位会被标记到 wasTracked 中
                deps[i].wasTracked = deps[i].wasTracked | 1 << effectTrackDepth
            }
        }
    }
+    // 清理无效依赖 并 优化依赖集合
+    finalizeDepMarkers() {
+        const { deps } = this
+        if (deps.length) {
+            for (let i = 0; i < deps.length; i++) {
+                const dep = deps[i]
+                // 根据依赖的跟踪状态，清理不再需要的依赖
+                if (wasTracked(dep) && !newTracked(dep)) {
+                    // 移除当前 effect 对该 dep 的依赖
+                    dep.delete(this)
+                }
+            }
+        }
+    }
}

我们再运行上面的测试代码，结果输出：条件二：child。我们接着改变 flag 的值， state.flag = true，结果输出：条件一：parent。这也是正确的输出结果。这时我们再改变 b 的值， state.b = '掘金签约作者'，结果输出：条件一：parent，这个结果还是不是我们期待的，为什么呢？

主要是因为现在只要我们的依赖的层级只要被标记上了，就一直是这个状态了。假设当前层级为 2，上述测试代码中需要删除的 b 属性依赖的层级初始标记状态为：wasTracked = 0b100, newTracked = 0b100，那么后续 b 属性的层级状态就一直是这个状态了，当判断是否需要删除的时候，我们需要判断 wasTracked 是否为 true，因为已经被标记过了，所以为 true，同样判断 newTracked 是否为 false 时，因为已经被标记过了，所以为 true。

所以在退出当前层级前，清除该层级对应的位掩码，确保下一层级的标记从干净状态开始。具体代码实现如下：

class ReactiveEffect {
    // ...
    // 清理无效依赖 并 优化依赖集合
     finalizeDepMarkers() {
        const { deps } = this
        if (deps.length) {
            for (let i = 0; i < deps.length; i++) {
                const dep = deps[i]
                // 根据依赖的跟踪状态，清理不再需要的依赖
                if (wasTracked(dep) && !newTracked(dep)) {
                    // 移除当前 effect 对该 dep 的依赖
                    dep.delete(this)
                }
+                // 清除该层级对应的位掩码
+                const trackOpBit = 1 << effectTrackDepth
+                dep.wasTracked = dep.wasTracked & ~trackOpBit
+                dep.newTracked = dep.newTracked & ~trackOpBit
            }
        }
    }
}

总的来说就是当 effect 执行完成后，通过比较 wasTracked 和 newTracked 的位掩码，可以快速确定哪些依赖在本次执行中没有被访问，从而进行清理。同时退出当前层级前，清除该层级对应的位掩码，确保下一层级的标记从干净状态开始。

递归层级限制30层的设计原因

Vue3 底层选择 30 层作为最大递归层级，因为 V8 引擎对 31/32 位整数直接存储于指针，无需堆分配，读写速度提升 10 倍，30 层限制确保位运算结果始终为 SMI，避免退化为堆内存对象导致性能退化，所以选择 30 层是为了确保现代JS引擎在所有平台上都能使用 SMI（小整数）优化。当超出 30 层时，回退到全量清理，保障极端场景稳定性。

代码优化迭代如下：

+ const maxMarkerBits = 30
class ReactiveEffect {
    // ...
    run () {
        try {
            // 1. 设置当前激活的 effect 为自身
            activeEffect = this;
            // 2. 压入 effect 调用栈（处理嵌套 effect 的关键）
            effectStack.push(this);
            effectTrackDepth++;
-            this.initDepMarkers()
+            if (effectTrackDepth <= maxMarkerBits) {
+                this.initDepMarkers()
+            } else {
+                // 当递归深度超过30层时，回退到完全清理模式
+                this.cleanup()
+            }
            // 初始化标记
            this.initDepMarkers();
            // 3. 执行原始函数，触发响应式属性的 getter，进行依赖收集
            return this._fn(); // 返回函数执行结果（支持 computed 等场景）
        } finally {
-            this.finalizeDepMarkers()
+            if (effectTrackDepth <= maxMarkerBits) {
+                this.finalizeDepMarkers()
+            }
            effectTrackDepth--;
            // 4. 无论执行是否抛出异常，确保以下清理逻辑一定执行
            effectStack.pop(); // 当前 effect 出栈
            // 5. 恢复 activeEffect 为上一个 effect（栈顶元素）或 undefined
            activeEffect = effectStack.length > 0 ? effectStack[effectStack.length - 1] : undefined;
        }
    }
    // ...
+    // 完全清理模式
+    cleanup() {
+        const { deps } = this
+        if (deps.length) {
+            for (let i = 0; i < deps.length; i++) {
+                deps[i].delete(this)
+            }
+            deps.length = 0
+        }
+    }
}

SMI（Small Integer）优化的核心原理

我们上面提到 Vue3 底层选择 30 层作为最大递归层级，是为了确保现代JS引擎在所有平台上都能使用 SMI（小整数）优化。

首先，我们得看一下 SMI 的概念。SMI 代表 Small Integer，是 V8 引擎对特定范围内整数的优化存储方式。在 V8 引擎中，SMI（Small Integer）优化 的核心原理是通过 指针标签（Pointer Tagging） 技术，将小整数直接嵌入指针值中，而非存储在堆内存中。以下是其性能优势的详细解析：

指针的结构

指针的本质：
指针是一个内存地址，通常用 32 位（32 位系统）或 64 位（64 位系统）表示。
标签位（Tagging Bits） ：
V8 利用指针的低位（如最低 1~2 位）作为 类型标记，例如：
- 表示该指针是一个 SMI（直接存储整数值）。
- 表示该指针是一个 堆对象地址（需要解引用获取实际值）。

SMI 的存储方式

直接嵌入指针：
V8 将小整数的二进制值 左移 1 位（腾出最低位作为标签），然后存入指针。

堆分配的数字：
若数字超出 SMI 范围（如大整数、浮点数），V8 会在堆内存中分配一个 Number 对象，并将指针指向该对象。

内存访问开销

SMI（指针存储） ：
值直接存储在指针中，读取时 无需访问堆内存，直接解析指针值即可。
堆分配的数字：
需要 两次内存访问：
1. 读取指针地址。
2. 根据指针地址访问堆内存中的 Number 对象。

内存分配开销

SMI：
无堆内存分配和释放操作，避免 内存管理开销（如垃圾回收）。
堆分配的数字：
需调用内存分配器，可能触发 垃圾回收（GC） ，增加延迟。

CPU 缓存友好性

SMI：
数值直接存储在指针中，与其他指针数据一起被 CPU 缓存，缓存命中率高。
堆分配的数字：
Number 对象分散在堆内存中，缓存局部性差，缓存未命中率高。

指令优化

SMI 操作：
通过简单的位运算（如移位、掩码）即可完成数值解析，CPU 指令周期短。

堆分配数字操作：
需要额外的解引用指令和类型检查，指令周期长。

设计哲学

空间换时间

SMI：牺牲 1 位指针空间（用于标签），换取极致性能。
堆分配：以内存和速度为代价，支持更大数值范围。

高频场景优化

现实场景：
大多数 JavaScript 程序中的整数是小范围的（如循环计数器、数组索引），SMI 覆盖了 99% 的用例。
收益最大化：
对高频操作（如依赖收集、循环计数）进行极致优化，显著提升整体性能。

综上所述，V8 通过 指针标签技术 将小整数（SMI）直接存储在指针中，实现了以下优势：

零内存分配：避免堆操作和垃圾回收开销。
直接访问：无需解引用，减少内存访问次数。
CPU 友好：位运算指令快，缓存命中率高。

这些优化使得 SMI 的读写速度比堆分配的数字快 10 倍以上，成为 JavaScript 高性能引擎的核心技术之一。Vue3 的依赖收集系统正是基于此特性，通过位运算和层级限制，实现了高效的响应式更新。

总结

最后我们来总结一下，Vue3 通过位运算设计实现以下响应式系统的优化：

层级化状态标记：通过位掩码精准管理递归层级依赖。
动态清理机制：按位比对移除失效依赖，避免冗余触发。
性能与内存平衡：SMI 优化保障操作速度，30 层限制避免边界问题。

这一机制在复杂组件、高频更新及深层嵌套场景下表现卓越，是 Vue3 响应式系统的核心创新之一。

我是程序员Cobyte，现在已转向研究 AI Agent，欢迎添加 v: icobyte，学习交流 AI Agent 应用开发。

掘金前端
再见吧CocoaPods，Swift Package Manager（SPM）即将在Flutter 3.44中成为默认依赖管理器JarvanMo
2026年5月7日 09:07

再见吧CocoaPods，Swift Package Manager（SPM）即将在Flutter 3.44中成为默认依赖管理器

掘金前端

作者 JarvanMo

2026年5月7日 09:07

长久以来Futter一直以CocoaPods为作为默认的依赖管理器，而最近就在临近Google I/O了，Flutter官方却突然宣布，从下一个Flutter稳定版3.44开始，Swift Package Manager（SPM）取代CocoaPods，成为iOS和macOS应用的默认依赖管理器。

这意味你不必再为了跑通一个App而去一顿瞎折腾Ruby环境或者安装那个令人抓狂的CocoaPods了。

Flutter这么做一方面是因为SPM是Apple官方的依赖管理器，另一方面CocoaPods实际上早进入了**维护模式，并且CocoaPods trunk 明确会在 2026-12-02 进入只读**，所以今年年底 SwiftPM 就势必会完全取代 CocoaPods 这个老古董。

终于不用再忍受那蜗牛般的pod install了……

当然这个并不突然，毕竟Flutter 支持SPM这个事早就开始实施了，我自己的项目也早早已开启了SPM模式。前段时间，我自己的开源项目还收到了支持SPM的催更请求：

Screenshot 2026-05-06 at 11.37.11.png

现在 Flutter 也开始正式提醒开发者，虽然现有版本还可以继续使用 CocoaPods，但是 2026-12-02 之后将不会在对 Pod 进行适配和支持 pod。

那这对我们会有什么影响吗？

App 开发者

实际上，对于App开发者来说，Flutter的CLI会帮助你自动完成迁移处理。当你开始运行或构建 iOS 或 macOS 应用时，CLI 会自动更新 Xcode 项目使用全新的 Swift 包管理器。

如果 App 依赖的插件还没适配 SwiftPM，Flutter 会打印一条警告信息，列出所有不受支持的依赖项，同时暂时回退到 CocoaPods。

当然这种回退并不会长久，毕竟Cocoapods都即将寿终正寝了，SPM又是Apple的太子，对Cocoapods的支持完全移除也在情理之中了。

当然，如果你真的遇到了SPM导致的构建问题，官方也提供了临时解决方案：

flutter:  
 config:  
   enable-swift-package-manager: false

在pubspec.yaml中把SPM关掉就好了。

插件开发者

对于插件开发者，如果你的插件支持iOS/macOS，那你是逃不开了（我不会告诉你fluwx/tobias spm适配进展缓慢）。Flutter社区其实一直在推进插件对SPM的适配（比如我就收到了适配请求），目前排名前 100 的 iOS 插件里已经有 61% 完成了迁移，后续如果没添加 Swift Package Manager 支持的 Package ，在 pub.dev 评分中得分也会被拉低。

其实是SPM与CocoaPods是非常非常不同的，这也是导致Fluwx/Tobias等项目的SPM支持进展缓慢的原因，比如说在使用CocoaPods时，podspec可以在pod install的时候作为Ruby脚本执行，即可以入侵你的Flutter项目构建过程，fluwx中的no_pay就是基于该原理实现的。而SPM虽然也是可执行的 Swift 脚本，但 SPM 在 swift package resolve 阶段就锁定了依赖图，这个阶段与 Flutter 构建流程完全解耦，无法可靠地从外部注入状态，这就导致我们无法像cocoapods那样通过在pubspec.yaml切换到no_pay状态，这意味我们又要把fluwx拆分成双包即fluwx和fluwx_no_pay。

且不提我的项目问题，说回SPM和CocoaPods的迁移问题。

具体怎么迁移，大家可以参考Flutter migration docs for plugin authors对插件进行迁移与适配。

过往的Cocoapods就像我上面说的一样，Cocoapods已经为我们做很多了隐式的骚操作，比如：

自动把 Flutter.framework 加进来
自动处理 header / linker / search path
不用关心 Flutter 引擎怎么进来的

但换成SwiftPM后就不一样了：

SwiftPM 是完全声明式依赖系统
不会有 CocoaPods 那种“魔法注入”
所有依赖都必须在 Package.swift 明确写出来

要知道，我们的插件代码其实是运行在 Flutter 引擎之上的，所以你需要在 Package.swift 里加这个依赖，以我正在迁移的Fluwx的Package.swift为例：

// swift-tools-version: 5.9
import PackageDescription


let package = Package(
    name: "fluwx",
    platforms: [.iOS("12.0")],
    products: [
        .library(name: "fluwx", targets: ["fluwx"])
    ],
    dependencies: [
         // 这是关键
        .package(name: "FlutterFramework", path: "../FlutterFramework"),
        .package(
            url: "https://github.com/JarvanMo/WechatOpenSDK-SPM", //
            from: "2.0.5"
        )
    ],
    targets: [
        .target(
            name: "fluwx",
            dependencies: [
                 // 这是关键
                .product(name: "FlutterFramework", package: "FlutterFramework"),
                .product(name: "WechatOpenSDK", package: "WechatOpenSDK-SPM")
            ],
            resources: [
                .process("Resources/PrivacyInfo.xcprivacy")
            ],
            cSettings: [
                .define("FLUWX_WITH_PAY"),
                .headerSearchPath("include")
            ],
            swiftSettings: [
                .define("FLUWX_WITH_PAY")
            ],
            linkerSettings: [
                .linkedFramework("CoreGraphics"),
                .linkedFramework("Security"),
                .linkedFramework("WebKit"),
                .unsafeFlags(["-ObjC", "-all_load"])
            ]
        )
    ]
)

另外如果在 2025 年做过迁移了插件，现在还也需要补充一个操作：在 Package.swift 文件中添加 FlutterFramework 作为依赖项，因为现在必须显式声明依赖。

从Flutter 3.41开始，要把FlutterFramework作为一个依赖：更新一下Package.swift以引入FlutterFramework:

dependencies: [
    .package(name: "FlutterFramework", path: "../FlutterFramework")
],
targets: [
    .target(
        // TODO: Update your target name.
        name: "plugin_name",
        dependencies: [
            .product(name: "FlutterFramework", package: "FlutterFramework")
        ],

别忘记更新 Dart/Flutter 版本

environment:
  sdk: ^3.11.0
  flutter: ">=3.41.0"

以我的切身体验来说，对 Flutter 来说这次变化影响最大的是插件生态。以前Flutter插件都是.podspec + Podfile + pod install接入，而且有不少插件会使用到魔法注入，但迁移到SPM后，这种魔法不复存在，会使一些插件的迁移难度增加。

SPM也是完全支持Objective-C 的，只是一些支持的力度和方式不太一样，比如 SwiftPM 不允许同一个 target 里同时混放 Swift 和 C-family 源码，target 可以包含 Swift、Objective-C/C++ 或 C/C++，但单个 target 不能混合 Swift 和 C-family 语言。

旧的纯OC插件/库迁移到SPM是完全可行的，只要目录结构要符合SPM规则。

真正麻烦的是那些OC+Swift混编的工程，通常来说他们要拆成多个target……

题外话

fluwx/tobais迁移到SPM的工作还在进行中, 主要就是iOS的变动，现在没了动态化的支持，很多功能变得比较麻烦。

如果大家对插件中引用本地framework可以参考我之前的文章。

那么，你准备好迎接Swift Package Manager了吗？

Vue 3 Composition API 深度解析

掘金前端

作者 Csvn

2026年5月7日 08:42

引言

Vue 3 的 Composition API 是 Vue 框架最具革命性的更新之一。它解决了 Options API 在大型项目中代码组织、逻辑复用和类型推导等方面的痛点。本文将深入讲解 Composition API 的核心概念、使用技巧以及最佳实践。

什么是 Composition API？

Composition API 是一组基于函数的 API，允许我们将相关逻辑组织在一起，而不是将代码分散在 data、methods、computed 等选项中。

对比：Options API vs Composition API

Options API （Vue 2 风格）：

export default {
  data() {
    return {
      count: 0,
      todos: []
    }
  },
  methods: {
    increment() {
      this.count++
    },
    fetchTodos() {
      // 获取待办事项
    }
  },
  computed: {
    doubleCount() {
      return this.count * 2
    }
  },
  mounted() {
    this.fetchTodos()
  }
}

Composition API （Vue 3 风格）：

import { ref, computed, onMounted } from 'vue'

export default {
  setup() {
    const count = ref(0)
    const todos = ref([])
    
    const doubleCount = computed(() => count.value * 2)
    
    const increment = () => {
      count.value++
    }
    
    const fetchTodos = async () => {
      // 获取待办事项
    }
    
    onMounted(() => {
      fetchTodos()
    })
    
    return {
      count,
      todos,
      doubleCount,
      increment,
      fetchTodos
    }
  }
}

核心 API 详解

1. ref() - 响应式基础类型

ref() 用于创建响应式的基本类型值。

import { ref } from 'vue'

const count = ref(0)

// 访问和修改
console.log(count.value) // 0
count.value = 1

// 在模板中自动解包，不需要 .value

关键点：

在 JavaScript 中需要通过 .value 访问
在模板中自动解包
支持任意类型的值

2. reactive() - 响应式对象

reactive() 用于创建响应式对象。

import { reactive } from 'vue'

const state = reactive({
  count: 0,
  user: {
    name: '张三',
    age: 25
  }
})

// 直接访问，不需要 .value
state.count++
state.user.age = 26

ref vs reactive ：

ref 可以处理任意类型，包括基本类型
reactive 只能处理对象类型
ref 需要 .value，reactive 直接访问

3. computed() - 计算属性

import { ref, computed } from 'vue'

const firstName = ref('张')
const lastName = ref('三')

const fullName = computed(() => {
  return firstName.value + lastName.value
})

// 只读计算属性
console.log(fullName.value) // '张三'

// 可写计算属性
const fullNameWritable = computed({
  get: () => firstName.value + lastName.value,
  set: (val) => {
    const [first, last] = val.split(' ')
    firstName.value = first
    lastName.value = last
  }
})

4. watch() 和 watchEffect()

watch() - 精确监听：

import { ref, watch } from 'vue'

const count = ref(0)

// 监听单个值
watch(count, (newVal, oldVal) => {
  console.log(`从 ${oldVal} 变为 ${newVal}`)
})

// 监听多个值
watch([count, firstName], ([newCount, newName]) => {
  console.log('变化:', newCount, newName)
})

// 监听对象属性（深度监听）
const user = reactive({ profile: { name: '张三' } })
watch(
  () => user.profile,
  (newVal) => {
    console.log('profile 变化', newVal)
  },
  { deep: true }
)

watchEffect() - 自动追踪依赖：

import { ref, watchEffect } from 'vue'

const count = ref(0)

watchEffect(() => {
  // 自动追踪 count 的变化
  console.log('count 是:', count.value)
  // 这里不需要指定监听谁，Vue 自动分析依赖
})

5. 生命周期钩子

Composition API 中的生命周期钩子需要在 setup() 中调用：

import { 
  onMounted, 
  onUpdated, 
  onUnmounted,
  onBeforeMount,
  onBeforeUpdate,
  onBeforeUnmount,
  onErrorCaptured
} from 'vue'

export default {
  setup() {
    onMounted(() => {
      console.log('组件已挂载')
    })
    
    onUpdated(() => {
      console.log('组件已更新')
    })
    
    onUnmounted(() => {
      console.log('组件已卸载')
    })
    
    // 错误捕获
    onErrorCaptured((err, instance, info) => {
      console.error('捕获到错误:', err)
      return false // 阻止错误继续传播
    })
  }
}

逻辑复用：组合式函数

Composition API 最大的优势在于逻辑复用。我们可以将相关逻辑封装成组合式函数（Composables）。

示例：useCounter

// composables/useCounter.js
import { ref, computed } from 'vue'

export function useCounter(initialValue = 0) {
  const count = ref(initialValue)
  
  const double = computed(() => count.value * 2)
  
  const increment = () => count.value++
  const decrement = () => count.value--
  const reset = () => count.value = initialValue
  
  return {
    count,
    double,
    increment,
    decrement,
    reset
  }
}

使用：

import { useCounter } from './composables/useCounter'

export default {
  setup() {
    const { count, double, increment, decrement } = useCounter(10)
    
    return {
      count,
      double,
      increment,
      decrement
    }
  }
}

示例：useFetch

// composables/useFetch.js
import { ref, onMounted } from 'vue'

export function useFetch(url) {
  const data = ref(null)
  const loading = ref(true)
  const error = ref(null)
  
  const fetchData = async () => {
    try {
      loading.value = true
      const response = await fetch(url)
      data.value = await response.json()
    } catch (err) {
      error.value = err.message
    } finally {
      loading.value = false
    }
  }
  
  onMounted(() => {
    fetchData()
  })
  
  return {
    data,
    loading,
    error,
    refresh: fetchData
  }
}

使用：

import { useFetch } from './composables/useFetch'

export default {
  setup() {
    const { data, loading, error, refresh } = useFetch('/api/users')
    
    return {
      data,
      loading,
      error,
      refresh
    }
  }
}

实际应用场景

1. 表单处理

// composables/useForm.js
import { ref, reactive } from 'vue'

export function useForm(initialValues = {}, validators = {}) {
  const form = reactive({ ...initialValues })
  const errors = reactive({})
  const touched = reactive({})
  
  const validate = (field) => {
    if (validators[field]) {
      const error = validators[field](form[field])
      errors[field] = error
      return !error
    }
    return true
  }
  
  const validateAll = () => {
    return Object.keys(validators).every(validate)
  }
  
  const setField = (field, value) => {
    form[field] = value
    touched[field] = true
  }
  
  return {
    form,
    errors,
    touched,
    validate,
    validateAll,
    setField
  }
}

2. 响应式路由

// composables/useRoute.js
import { ref, computed } from 'vue'
import { useRoute as useVueRoute } from 'vue-router'

export function useRoute() {
  const route = useVueRoute()
  
  const queryParams = computed(() => route.query)
  const params = computed(() => route.params)
  const fullPath = computed(() => route.fullPath)
  
  return {
    route,
    queryParams,
    params,
    fullPath
  }
}

最佳实践

1. 逻辑组织

将相关的逻辑组织在一起：

export default {
  setup() {
    // 状态定义
    const count = ref(0)
    const loading = ref(false)
    
    // 计算属性
    const doubleCount = computed(() => count.value * 2)
    
    // 方法
    const increment = () => count.value++
    
    // 生命周期
    onMounted(() => {
      console.log('mounted')
    })
    
    // 返回
    return {
      count,
      doubleCount,
      increment
    }
  }
}

2. 使用 `<script setup>`

Vue 3.2+ 引入了 <script setup>，让 Composition API 更加简洁：

<script setup>
import { ref, computed, onMounted } from 'vue'

const count = ref(0)
const doubleCount = computed(() => count.value * 2)

const increment = () => count.value++

onMounted(() => {
  console.log('mounted')
})
</script>

<template>
  <div>
    <p>{{ count }}</p>
    <p>{{ doubleCount }}</p>
    <button @click="increment">增加</button>
  </div>
</template>

3. 类型推导

Composition API 对 TypeScript 支持更好：

import { ref } from 'vue'

// 类型自动推导
const count = ref(0) // Ref<number>
const user = ref({ name: '张三', age: 25 }) // Ref<{ name: string, age: number }>

// 显式类型
const count2 = ref<number>(0)
interface User {
  name: string
  age: number
}
const user2 = ref<User>({ name: '张三', age: 25 })

总结

Composition API 为 Vue 3 带来了：

更好的逻辑组织 - 相关代码放在一起，而不是分散在多个选项中
更强的逻辑复用 - 通过组合式函数实现代码复用
更好的 TypeScript 支持 - 类型推导更准确
更小的打包体积 - 更好的 tree-shaking

虽然学习曲线稍陡，但对于中大型项目来说，Composition API 是更好的选择。建议从简单的 ref、computed、watch 开始，逐步掌握组合式函数的编写技巧。

昨天 — 2026年5月6日掘金前端

掘金前端
Bun 深度调研：一个想把 JavaScript 工具链全部重写的野心项目王若风
2026年5月6日 22:47

Bun 深度调研：一个想把 JavaScript 工具链全部重写的野心项目

掘金前端

作者王若风

2026年5月6日 22:47

ChatGPT Image 2026年5月6日 22_32_49.png

大家好，我是若风。

2025 年 12 月上旬，Bun 先宣布加入 Anthropic，随后 Anthropic 也发布公告：它收购了 Bun。

我也注意到，Bun 官方在加入 Anthropic 的文章里提到 Claude Code、Factory AI、OpenCode 等 AI 编程工具都在使用 Bun。换句话说，它已经不只是一个“开发者自己试试看”的运行时，也开始进入 AI coding 工具链的内部执行路径。

这 2 件事情叠加引起了我对 Bun 的好奇，说实话，我之前对 Bun 的印象一直停留在“又一个号称比 Node 快的 JS 运行时”这个层面。但这次收购让我觉得事情没那么简单——Anthropic 为什么要收一个 JavaScript 运行时？

带着这个疑问，我花了不少时间做了一次深度调研。越看越觉得，Bun 这个项目比我想象的有意思得多。它不只是“比 Node 快”，它其实在试图重新回答一个问题：现代 JavaScript 工程，到底应该由几层工具组成？

今天这篇文章，就是这次调研的结果。

先说结论

Bun 不是 React、Vue 那种“框架”，而是一个试图把 JavaScript 运行时、包管理器、测试运行器、Bundler、全栈开发服务器 压进同一个二进制里的基础设施产品。

用人话说：Bun 想把 "Node.js + npm/pnpm + Jest/Vitest + esbuild/Vite" 这一大串组合拳，收缩成一个叫 bun 的命令。

这个野心非常大。大到现在社区对 Bun 的态度非常分裂：一边是兴奋，因为确实快；另一边是警惕，因为边界扩得太宽，质量能不能跟上是个问号。

Bun 怎么来的：一次“忍不了”

Bun 的起点不是抽象的“想做一个更快的 JS 运行时”，而是非常具体的工程烦躁。

创建者 Jarred Sumner 在多次访谈和项目回顾里都把 Bun 的起点讲得很工程化：他当年在做一个浏览器里的 voxel game，代码库一大，开发服务器反馈变得难以忍受。InfoWorld 访谈里提到，从保存代码到浏览器看到变化大概要 30 秒；后来的复盘文章里也常把这个痛点描述成几十秒级的等待。不是哲学问题，是会把人耐心一点点磨掉的那种工程问题。

于是他先去折腾 JSX/TypeScript 转译器，后来为了让 Next.js 的服务端渲染跑起来，发现自己又不可避免地走进了 runtime 的坑里。

很多产品的诞生，表面上是“新需求催生新架构”，实际上更像“一个足够能折腾的人，被一个具体痛点逼进了深水区”。Bun 就是后者。

两个关键选择，决定了 Bun 的一切

Bun 在 2021 年做了两个技术选择，几乎锁死了它后来所有的优点和缺点。

选择一：用 Zig，不是 Rust

Jarred 说他一开始也考虑过 Rust，但最后选了 Zig。理由不是“生态更好”，而是更朴素的——他要对底层行为、内存和系统调用路径有足够直接的控制。

Bun 从第一天起就是一个极度强调性能路径的产品。语言选择不是外围决策，它会把团队的心智模型也一起定型。

选择二：JavaScriptCore，不是 V8

这一步影响更大。Node 和 Deno 背后都是 V8，Bun 反而绕到 Safari 那条线，嵌入 WebKit 的 JavaScriptCore。

为什么？因为 JavaScriptCore 的启动速度快。

这个选择给了 Bun 很强的启动速度优势，也让它从第一天就和 Node/Deno 拉开了技术路线差异。但代价也很明显：在 Node 兼容、V8 私有 C++ API、Windows 适配这几个方向，Bun 注定要比“直接站在 V8 上做演化”的路线更辛苦。

也就是说，Bun 后来的很多优点和很多麻烦，其实在 2021 年这两个选择里就已经埋下了。

Bun 的版本演化：从“能跑 demo”到“被 Anthropic 收购”

Bun 到今天大致经历了四个阶段，每个阶段的核心矛盾都不一样。

第一阶段：萌芽期（2021-2022.7）

核心矛盾：如何把对 JavaScript 工具链低效的个人愤怒，变成一个技术上可成立的新产品。

最关键的决策就是 Zig 和 JavaScriptCore。

第二阶段：品牌爆发期（2022.7-2023.9）

2022 年 7 月，Bun v0.1.0 发布后迅速出圈。早期社区买单的不是成熟度，而是三件事：

第一，统一叙事。 Node 时代的 JS 工具栈越来越像乐高——runtime 是 Node，包管理是 npm/yarn/pnpm，转译是 Babel/SWC/tsx，测试是 Jest/Vitest，打包是 webpack/esbuild/rollup/Vite。每多一层，就多一层配置、多一层 cache、多一层边界 bug。Bun 一上来就反着来：别拼了，我给你一个总工具。

第二，速度叙事足够强。 无论是早期官网还是后来的首页，Bun 一直把“快”放在最前面。启动快、HTTP 快、WebSocket 快、bun install 快、bun test 快。

第三，兼容策略更现实。 Deno 早期更像“重写现代 JS 运行环境”的宣言，理念漂亮但迁移成本高。Bun 从一开始就瞄准“Node 的替代者”，不是“Node 的批评者”。它不是要教育开发者换脑子，而是想让开发者带着旧项目直接试。

这件事非常重要。因为在运行时竞争里，迁移成本比理论优雅更接近真实决策。

第三阶段：平台化与兼容攻坚期（2023.9-2025.10）

Bun 1.0（2023.9.8）：第一次完成产品定义

Bun 1.0 不只是版本号从 0.x 跨到 1.0。真正重要的是，它第一次把产品定义讲完整了：明确列出想要替代 Node.js、npx、dotenv、nodemon、babel、ts-node、esbuild、webpack、npm、yarn、pnpm、Jest、Vitest。

它讲的不只是性能，而是一个完整的开发路径。

这背后是一种很强的产品哲学：不是让你装更多工具去修 JavaScript，而是让 runtime 本身长出更多“开发者真正高频会用”的器官。

Bun 1.1（2024.4.1）：补上 Windows，从明星项目走向平台项目

Windows 支持看起来不性感，但它决定你到底能不能被更大盘子的开发者采用。Bun 1.1 发布文里说，Bun on Windows 已经可以通过 Bun 在 macOS 和 Linux 上自用测试套件的 98%。

这一步的意义在于：你不再只是给愿意折腾的新技术爱好者服务，你开始对更多普通开发者负责。对基础设施产品来说，这是从“项目”走向“平台”的必要一步。

Bun 1.2（2025.1.22）：方法论升级

很多人看 Bun 1.2，会先看到新增能力：Bun.s3、Bun.sql、bun.lock 文本锁文件。

但我觉得真正的分水岭在于它对 Node.js 兼容性的方法论升级。过去 Bun 修 Node 兼容，更多是哪个 npm 包炸了就去补哪个坑——像打地鼠。Bun 1.2 开始系统性地跑 Node.js 官方测试套件。

这意味着 Bun 承认了一件事：如果你真想吃掉 Node 的运行时地位，最重要的战场不是宣传页，而是兼容性回归测试。

这是 Bun 从“产品想象力很强”走向“工程纪律正在成形”的关键一步。

Bun 1.3（2025.10.10）：从 runtime 推向 full-stack substrate

官方原话：Bun 1.3 turns Bun into a batteries-included full-stack JavaScript runtime.

新增了内建前端 dev server、内建热重载、可以直接跑 HTML、更强的 Bun.serve() 路由、MySQL 和 Redis 也进来了。

到 1.3 为止，Bun 已经不再只想做“更快的 Node 替代品”。它想做的是：你用一门语言，一套命令，一个二进制，直接把前端开发、后端服务、测试、打包、依赖管理、甚至一部分数据库接入都串起来。

第四阶段：AI 基础设施绑定期（2025.12 至今）

被 Anthropic 收购

2025 年 12 月 2 日，Bun 宣布加入 Anthropic。Jarred 在公告里说得很坦白：截至公告发布时，Bun 收入是 0。

这很真实。Bun 过去默认的商业化设想大概是做某种云托管产品，但 AI coding tools 在 2024 年后突然变成更大的浪潮。Bun 团队判断，把自己放到 Anthropic 体系里，成为 Claude Code、Claude Agent SDK 和未来 AI coding 产品的基础设施层，比继续摸索独立 startup 如何变现更有意思。

这里有一个非常值得注意的转向：Bun 最早是因为前端热重载慢而生，最初服务的是“人类开发者更快写代码”。到了 2025 年底，新叙事变成：AI agents 正在写、测、跑更多代码，所以 runtime 和工具链层的重要性反而更高。

这不是换包装，是战略重心真的变了。

2026 年：继续打磨底层

截至 2026 年 5 月 6 日，我查到的 Bun 最新稳定版是 v1.3.13。这些 1.3.x 小版本说明 Bun 已经进入更像基础设施产品的第二阶段：围绕真实工作负载，打磨测试、安装、内存、兼容这些又难讲故事、又极其影响体感的底层路径。

比如 1.3.13 里：bun test --parallel、--isolate、--shard、--changed；bun install 流式解压 tarball，官方称在大仓库里把内存压到之前的 1/17；source map 内存占用最多下降 8 倍；runtime 基线内存再降约 5%。

竞争格局：Bun vs Node vs Deno

Bun 的竞品不是一个，至少有三类对手：Node.js（默认标准）、Deno（方法论型对手）、传统 Node 工具链组合（最真实的日常对手）。

Bun vs Node.js

Node 的价值不是“每一项都最好”，而是“它在无数真实生产环境里被证明足够稳，而且生态默认围着它转”。Node 自己不试图把整个工具链都吃下来，它把 runtime 做成公共地基，然后允许上层生态自由长。

Bun 则更激进。它不满足于做 runtime，它想把“你平时围绕 runtime 装的一整套常用工具”一起卷进来。

Bun 赢在：集成度极高、启动快反馈快（对 CLI 和 AI agent 特别友好）、产品表达更现代。

Bun 输在：稳定性和边缘兼容还没到 Node 那个量级、维护面过宽、生产可预期性仍然弱于 Node。

用户的真实选择逻辑通常是：

选 Bun：新项目、内部工具、CLI、AI agent，迁移包袱小，想少装几层工具
选 Node：老项目依赖深，团队更看重稳定性，生产事故成本远大于日常快一点的收益

Bun vs Deno

两者经常被放在一起，但方法论差很大。

Deno 的路线：先把原则立住，再向现实靠近。secure by default，Web 标准优先，TypeScript 零配置。Deno 2 的现实转向很明显：官方发布文明确提到支持 package.json、node_modules、npm 和更强的 Node 兼容。

Bun 的路线：先吃现实，再慢慢补原则。从第一天就强调"drop-in replacement for Node.js"，优先考虑的不是权限模型的美感，而是“老项目能不能尽快跑”。

三条路径，三种气质：

Node 是默认公路
Deno 是重新规划过交通规则的新城
Bun 是一条想直接把老城最堵那几段全改成高速路的工程

Bun vs 传统工具链

这才是最真实的竞争。很多团队不会问“要不要从 Node 换到 Bun”，而是问：现有这套 Node + pnpm + Vite + Vitest 的组合，有没有必要整体迁到 Bun？

传统组合的优点是每一层都相对成熟，并且可以替换。缺点是你得自己承担拼装成本——不同工具会反复解析源码、反复做模块图、反复维护 cache。

Bun 赢在减少重复工作、配置面收缩、局部采用路径很丝滑（你可以先只用 bun install）。

Bun 输在传统组合的每个局部都更成熟，专业化工具在极端场景下仍然更强，而且很多成熟团队不喜欢“一个核心工具管太多事”。

Bun 的优势和劣势，都来自同一个源头

Bun 最让人着迷的地方，和最让人不放心的地方，其实是一回事。

它的核心优势来自一个很稳定的价值排序：凡是会拖慢开发者反馈回路的环节，都值得被系统性重做。 安装更快、启动更快、TypeScript/JSX 不用额外转、测试和打包都不绕远路、CLI 分发成本更低。

但正因为不是只做 runtime，而是一路把更多高频能力往 core 里收——包管理器、测试运行器、Bundler、dev server、数据库客户端、对象存储客户端——维护半径不断扩大。任何一个面出问题，都会牵连整个品牌。

GitHub 上能看到非常具体的担忧。有用户在用 Elysia.js + Prisma 的 API 服务里观察到 CPU 持续上升；也有用户把同一套服务从 Node 切到 Bun 后，在 GKE 上内存从 500MB 很快打到 1.2GB 容器上限。这些都是单个 issue 案例，不等于 Bun 在所有生产场景都有同样问题，但它们确实说明：社区对稳定性和边缘兼容的担心并不是凭空来的。

这些声音代表了 Bun 当前最真实的舆论断层：在开发体验层，很多人已经觉得它很香；在关键生产基础设施层，很多人还没有放心。

未来会怎样？

我觉得有三种剧本。

最可能：外围切入，向中心渗透

Bun 会继续成为 AI-native JavaScript 工具链和 CLI 分发的重要基础设施。很多团队会先用 bun install、bun test、可执行程序编译、内部脚本，再慢慢决定要不要让核心服务也切到 Bun。

最危险：功能扩张但质量跟不上

功能继续高速扩张，但质量治理跟不上，导致 Bun 在生产后端场景里长期背着“不够稳”的标签。最后更多停留在“很好用的开发工具/CLI 基座”，而不是全面替代 Node 的基础设施。

最乐观：AI 时代的默认 JS 执行层

Anthropic 的资源、AI coding tool 的真实需求、Bun 团队对性能和 DX 的持续偏执，最终叠加成一个结果：Bun 在 2 到 3 年里把 Node 兼容和稳定性再往前推一个台阶，成为 AI 时代默认的 JavaScript 执行与分发层。

写在最后

回头看看 Bun 的发展历程，有一个感受很深。

Node 代表的是“runtime 做小，生态做大”。Deno 代表的是“先把原则立住，再兼容现实”。Bun 代表的是“把最影响效率的几层工具重新焊成一个整体，并且优先服务真实迁移路径和更短的反馈回路”。

所以 Bun 最核心的竞争力，从来不只是快。而是它在试图把“现代 JavaScript 工程到底应该由几层工具组成”这个问题，重新回答一遍。

这就是它值得被认真研究的地方。也是它注定会继续伴随争议的原因。

对于普通开发者，我的建议是：

如果你在做新项目、CLI 工具、内部工具、AI agent 相关的东西，Bun 值得认真试试。你可以先只用 bun install 或 bun test，先吃到局部收益，不需要一步到位。

如果你在维护大型生产系统，继续用 Node 是更安全的选择。Bun 还没到可以放心把核心服务压上去的阶段。

但不管你用不用 Bun，它正在改变 JavaScript 工具链的游戏规则。这件事本身就很值得关注。

参考来源

Web 性能优化完全指南

掘金前端

作者顾昂_

2026年5月6日 20:40

全网最全面的web性能优化详解

文中用到的工具方法性能工具方法库

免费的面试合集 - cookguo.github.io/learn/brows… 整理不易，给个免费的star就行了，兄弟们。

第一章：为什么性能优化很重要
第二章：Web 性能指标全景
第三章：Chrome DevTools 性能分析工具实战
第四章：LCP 优化深度指南
第五章：INP 优化深度指南
第六章：CLS 优化深度指南
第七章：TTFB 与网络优化
第八章：代码层面的通用优化
第九章：综合实战——完整性能排查流程
第十章：性能监控与持续改进

第一章：为什么性能优化很重要

1.1 用数据说话：性能与业务的直接关联

很多初学者会问：页面慢一点，用户忍一忍不就好了吗？事实并非如此。性能问题直接影响用户留存和业务收入，这不是假设，而是有大量真实数据支撑的结论。

根据 2025 年的行业数据：

性能优化不达标可能导致 8% 到 35% 的转化率、排名和收入损失
Google 的研究显示，页面加载时间从 1s 增加到 3s，跳出率增加 32%；增加到 5s，跳出率增加 90%
Pinterest 将感知等待时间减少 40%，搜索引擎流量和注册量增加了 15%
BBC 发现每增加一秒的加载时间，额外损失 10% 的用户

对于 Web3 钱包等金融类应用，用户的容忍度更低。当用户在进行交易操作时，一个卡顿的交互体验不仅影响用户留存，更会直接影响用户对产品安全性的信任感。

1.2 搜索引擎排名的硬性要求

2021 年，Google 正式将 Core Web Vitals（核心网页指标）纳入搜索排名算法。这意味着：

如果你的页面 LCP 超过 4 秒，搜索排名会受到明显的负面影响
Core Web Vitals 包括 LCP（最大内容绘制）、INP（与下一次绘制的交互）、CLS（累积布局偏移）
目前全球只有 48% 的移动页面和 56% 的桌面页面通过全部三项 Core Web Vitals

这一数据意味着，做好性能优化本身就是竞争优势。

1.3 用户体验的心理学

人类对时间的感知并不是线性的：

0-100ms：用户感觉是"即时"的，操作如丝般顺滑
100-300ms：用户感觉是"流畅"的，可以接受
300-1000ms：用户感觉有"延迟"，开始不耐烦
1000ms 以上：用户的注意力开始转移，心流被打断
10s 以上：用户往往直接放弃

因此，性能目标不仅仅是"能用"，而是要达到让用户感觉"快"的心理阈值。

1.4 前端性能的三个维度

理解性能优化，需要从三个维度思考：

加载性能：页面从开始加载到用户能看到内容需要多长时间（LCP、FCP、TTFB）
交互性能：用户操作页面时的响应速度（INP、FID）
视觉稳定性：页面内容是否会在加载过程中发生意外移动（CLS）

这三个维度互相独立，需要分别进行诊断和优化。

第二章：Web 性能指标全景

2.1 Core Web Vitals：最重要的三个指标

Core Web Vitals 是 Google 定义的三个核心用户体验指标，是性能优化的重中之重。

LCP（Largest Contentful Paint，最大内容绘制）

定义：从页面开始加载到视口中最大的图片或文本块完成渲染的时间。

阈值标准：

良好：< 2.5 秒
需改进：2.5 秒～ 4 秒
差：> 4 秒

哪些元素会被计为 LCP 元素？

<img> 元素
<image> SVG 内的元素
<video> 元素（使用海报图像时）
通过 url() 函数加载了背景图片的元素
包含文本节点或其他内联文本元素子级的块级元素

需要特别注意的是，浏览器会排除"无意义"的内容，例如透明度为 0 的元素、尺寸为 0 的元素等，不会将其计为 LCP 候选元素。

INP（Interaction to Next Paint，与下一次绘制的交互）

定义：衡量用户与页面的每次离散交互（点击、键盘按键、触摸）从交互发生到下一帧绘制的延迟时间。INP 取的是页面整个生命周期内所有交互延迟的最大值（排除一些异常值）。

INP 的三个阶段：

Input Delay（输入延迟） ：从用户操作到事件处理程序开始执行的时间，受主线程上正在执行的长任务影响
Processing Time（处理时间） ：事件处理程序本身的执行时间
Presentation Delay（呈现延迟） ：从事件处理完成到浏览器绘制下一帧的时间，包括样式计算、布局、绘制

阈值标准：

良好：< 200 毫秒
需改进：200 ～ 500 毫秒
差：> 500 毫秒

注意：INP 于 2024 年 3 月正式替代 FID（First Input Delay，首次输入延迟）成为 Core Web Vitals 的一部分。INP 比 FID 更严格，因为它衡量的是整个页面生命周期内的交互响应，而不仅仅是首次交互。

CLS（Cumulative Layout Shift，累积布局偏移）

定义：衡量页面在加载过程中元素发生意外移动的程度。当一个可见元素从一帧到下一帧改变位置时，就会发生布局偏移。

计算方式：

布局偏移分数 = 影响分数 × 距离分数
影响分数 = 受影响的视口比例
距离分数 = 元素移动的最大距离 / 视口高度

阈值标准：

良好：< 0.1
需改进：0.1 ～ 0.25
差：> 0.25

2.2 其他重要性能指标

FCP（First Contentful Paint，首次内容绘制）

定义：浏览器第一次渲染任何文本、图像、非白色 canvas 或 SVG 的时间。

阈值：良好 < 1.8 秒

FCP 是用户感知到"页面开始加载"的时间点，是 LCP 的前置指标。如果 FCP 就很慢，LCP 一定不会快。

TTFB（Time to First Byte，首字节时间）

定义：从浏览器发出 HTTP 请求到接收到第一个字节响应的时间。

阈值：良好 < 200 毫秒

TTFB 是所有加载指标的基础，它反映的是服务器响应速度和网络延迟。如果 TTFB 很高，无论前端如何优化，LCP 都很难达标。

TTI（Time to Interactive，可交互时间）

定义：页面从加载开始到能够可靠地响应用户输入所需的时间。

TTI 要求满足：

页面显示了有用内容（FCP 之后）
大多数可见元素的事件处理程序已注册
页面在 50ms 内响应用户交互

TBT（Total Blocking Time，总阻塞时间）

定义：FCP 和 TTI 之间所有长任务（执行时间超过 50ms 的任务）的阻塞时间之和。一个长任务的阻塞时间 = 任务时长 - 50ms。

阈值：良好 < 200 毫秒

TBT 是衡量 JavaScript 执行对主线程占用程度的关键指标。在真实案例中，我们曾发现一个页面的 TBT 高达 69,747ms，有 506 个长任务，最长单个任务达 4,771ms。这种情况下，页面几乎完全无法交互。

2.3 指标之间的关联关系

网络请求开始
    │
    ▼
TTFB（服务器响应速度）
    │
    ▼
FCP（首次内容出现）
    │
    ├──► LCP（最大内容出现）← 加载性能核心
    │
    ├──► TTI（页面可交互）
    │         │
    │         ▼
    │       TBT（阻塞时间）← JS 执行质量
    │
    └──► INP（交互响应速度）← 交互性能核心

    CLS（布局稳定性）─── 贯穿整个加载过程

理解这个关系图对于排查性能问题至关重要：如果 TTFB 就慢，要从服务器和网络层面解决；如果 FCP 慢但 TTFB 正常，要看 CSS 和关键资源阻塞；如果 LCP 慢，要看最大元素的渲染和加载；如果 INP 差，要看 JavaScript 长任务。

第三章：Chrome DevTools 性能分析工具实战

3.1 工具概览

Chrome DevTools 提供了多个用于性能分析的面板，每个面板有不同的侧重点：

面板	用途	适合分析
Performance	录制运行时性能	长任务、帧率、CPU 占用
Lighthouse	综合性能审计	所有 Core Web Vitals
Network	网络请求分析	资源加载、TTFB、优先级
Memory	内存分析	内存泄漏、堆快照
Coverage	代码覆盖率	未使用的 JS/CSS

3.2 Lighthouse 面板实战

Lighthouse 是最适合初学者入手的性能分析工具，它能一键给出综合评分和改进建议。

使用步骤：

打开 Chrome DevTools（F12 或右键 → 检查）
切换到 Lighthouse 标签页
选择要分析的类别（勾选 Performance）
选择设备类型（推荐先选 Mobile 模拟移动端，因为移动端更严格）
点击 Analyze page load 按钮
等待约 30 秒，查看报告

📸 Lighthouse 面板配置界面（设备类型、分析类别、清除缓存选项）：

面板上方可以选择：Mode（Navigation / Timespan / Snapshot）、Device（Mobile / Desktop）、Categories（Performance 必须勾选）。建议勾选 Clear storage 模拟新用户首次访问。

读懂 Lighthouse 报告：

Lighthouse 会给出 0-100 的综合评分，并列出 Metrics 和 Opportunities 两部分：

Metrics 部分：显示各项核心指标的具体数值和评级（绿色良好、橙色需改进、红色差）
Opportunities 部分：列出具体的优化建议，每条建议都会估算优化后能节省的时间
Diagnostics 部分：列出可能影响性能的问题，例如"避免过大的 DOM 节点"

重要提示：Lighthouse 的测试结果会受到本地网络状况、CPU 性能等因素影响。建议：

在隐身模式下运行，避免浏览器扩展干扰
多次运行取平均值
关闭其他占用资源的程序

3.3 Performance 面板深度使用

Performance 面板是最强大也最复杂的性能分析工具，它能录制页面运行时的每一帧，让你看到 JavaScript 执行、样式计算、布局绘制的完整时间线。

录制性能分析：

打开 Performance 面板
点击左上角的 录制按钮（圆圈图标） 开始录制
在页面上执行你想分析的操作（如点击按钮、滚动页面）
点击停止按钮
等待分析完成，查看时间线

📸 录制控制按钮位置（左上角圆形录制键，右下角也有一个快捷键）：

读懂 Performance 面板：

Performance 面板分为几个区域，从上到下依次是：

① 概览区域（Overview） ：

顶部的彩色条带展示 FPS（帧率）、CPU 占用、网络请求的整体情况
绿色区域表示帧率正常（60fps），红色区域表示帧率下降
CPU 区域颜色越深表示 CPU 越繁忙：黄色是 JavaScript，紫色是渲染，绿色是绘制

📸 Overview 概览区域（上方 CPU/NET 条带 + 下方时间线选区）：

拖动下方的灰色选区可以放大特定时间段，方便精细分析。

② 主线程区域（Main） ：

这是最关键的区域，展示主线程上发生的所有活动
每个彩色块代表一个任务，高度表示任务的调用深度
长任务（Long Task）会被标记为红色三角形 ← 这是你需要重点关注的地方
点击任何一个色块，可以在底部看到该任务的详细信息

📸 Main 主线程区域（每个色块是一个任务，底部是 Summary 详情）：

点击任意色块后，底部 Summary 标签页 会显示该任务的耗时分解（Scripting / Rendering / Painting）。

③ 识别长任务（最重要） ：

在 Main 区域，找到顶部有 红色三角形 的任务块，这些就是超过 50ms 的长任务。展开这个任务块，可以看到：

哪个函数占用了最多时间
调用栈的完整链路
每个函数的自身时间（Self Time）和总时间（Total Time）

📸 Long Task 标记（红色三角形 + 超出 50ms 部分用红色斜线标注）：

如何读这个图：任务块顶部出现红色三角旗标，任务超出 50ms 的部分会用红色斜线填充。任务越宽表示执行时间越长，越高表示调用层级越深。

④ 火焰图（Flame Chart）——找到最耗时函数：

点击长任务块并放大后，可以看到火焰图。火焰图是从上到下的函数调用栈：最顶层是入口函数，往下每一层是被调用的子函数。

📸 火焰图详情（点击 click 事件后可看到完整调用链）：

技巧：找到"宽度最大"且"位于底层"的色块，那就是最耗时的叶子函数（Self Time 最高的函数），优先优化它。

⑤ 性能时间点标记（FCP / LCP / DCL / Load） ：

时间线上会有几条垂直的彩色线，对应关键时间点：

📸 关键时间点标记线（FCP 绿线、LCP 绿线、DCL 蓝线、Load 红线）：

FCP（绿色） ：第一块内容出现的时间
LCP（绿色，更靠后） ：最大内容出现的时间
DCL（蓝色） ：HTML 解析完成
Load（红色） ：所有资源加载完成

实际案例：在我们的内部性能分析中，发现某页面存在以下问题：

Long Tasks 总数：506 个
TBT：69,747ms
最长 Long Task：4,771ms
querySelectorAll 是最大瓶颈（合计 4,176ms）
Web3 加密库占 CPU 42.3%
DOM/Native API 占 CPU 29.5%
React DOM 占 CPU 13.8%

从这个数据可以得出结论：需要优化 DOM 查询（将 querySelectorAll 结果缓存），并考虑将加密库运算移入 Web Worker。

3.4 Chrome DevTools 2025 新特性

Live Metrics 实时指标面板：

在 Performance 面板中，Chrome 现在提供了 Live Metrics 功能，可以在你正常使用页面的同时，实时显示 LCP、INP、CLS 的当前数值。

使用方法：

打开 Performance 面板
找到 Live Metrics 区域（在面板右侧）
正常操作页面，观察指标变化
当某个指标变红时，说明触发了一次不良的交互或渲染

📸 Live Metrics 实时面板（左侧本地实测值 + 右侧 CrUX 字段真实用户数据）：

面板分两列：本地（Local） 是你当前浏览器实测值，字段数据（Field） 是来自 CrUX 的真实用户数据。悬停指标数值可以展开该指标的各阶段细分（如 LCP 的 TTFB / Load Delay / Load Time / Render Delay）。

这个功能特别适合快速定位是哪个操作导致了 INP 变差。

INP 交互日志（Interactions Track） ：

录制结束后，Performance 面板中有一条 Interactions 轨道，记录了所有被计入 INP 的用户交互：

📸 Interactions 轨道（每次交互显示 Input Delay + Processing + Presentation 三段时间条）：

点击某条交互记录，可以展开看三个阶段的耗时：

Input Delay（灰色） ：点击到事件处理开始，越短越好
Processing（黄色） ：事件处理函数执行时间，这里优化 → 用 taskSplitPoint/asyncExecuteTask
Presentation（紫色） ：渲染到下一帧，这里优化 → 减少重排/重绘

AI 驱动的性能 Insights：

Chrome DevTools 现在内置了 AI 性能分析功能，在 Performance 录制结束后，可以点击 Insights 面板，AI 会自动识别关键瓶颈并给出优化建议。

校准节流（Calibrated Throttling） ：

在 Performance 面板的节流设置中，Chrome 现在支持根据你当前机器的性能自动校准节流比例，使模拟的移动端性能更准确。

3.5 Network 面板分析资源加载

找到 LCP 图片的加载时间：

打开 Network 面板
刷新页面
在请求列表中找到你认为的 LCP 图片
点击该请求，查看 Timing 标签页

Timing 标签页会显示：

Queued at：请求在哪个时间点被排队
Stalled：等待发送的时间（通常是连接复用等待）
Waiting (TTFB) ：首字节时间
Content Download：下载时间

📸 Network 面板选中某个请求后的 Timing 详情：

如何判断问题所在：

Waiting (TTFB) 时间长 → 服务器响应慢，考虑 CDN 或服务器优化
Content Download 时间长 → 文件太大，考虑压缩或格式转换（WebP）
Stalled 时间长 → 连接数限制导致排队，考虑 HTTP/2 或 preconnect

查看资源加载优先级：

在 Network 面板的请求列表中，右键任意列标题，勾选 Priority 列，可以看到每个资源的加载优先级。

LCP 图片的优先级应该是 Highest，如果显示为 Low 或 Medium，就需要使用 fetchpriority="high" 属性来提升它。

💡 快速定位 LCP 图片的技巧：在 Network 面板按 Img 类型过滤，然后看哪张图片的开始时间最晚且体积最大，大概率就是 LCP 元素。

3.6 Coverage 面板：找到未使用的代码

打开 Coverage 面板（可以通过 Ctrl+Shift+P 搜索 "Coverage" 打开）
点击录制按钮
刷新页面并操作
停止录制，查看结果

Coverage 面板会列出每个 JS/CSS 文件，并显示有多少百分比的代码在本次操作中被执行。如果一个文件 90% 的代码都是红色（未使用），说明代码分割可以带来很大的性能提升。

3.7 一图总结：Chrome DevTools 性能分析全流程

第一步：快速体检               第二步：精细录制              第三步：定位问题
┌──────────────────┐       ┌──────────────────┐       ┌──────────────────┐
│   Lighthouse     │       │  Performance 面板 │       │  Network 面板    │
│                  │       │                  │       │                  │
│  一键生成评分    │──→    │  录制交互操作    │──→    │  找 LCP 图片     │
│  找到 LCP/INP/   │       │  找 Long Task    │       │  查 Priority 列  │
│  CLS 的问题点    │       │  看火焰图        │       │  看 Timing 详情  │
│                  │       │  看 Interactions │       │                  │
└──────────────────┘       └──────────────────┘       └──────────────────┘
     ↓                            ↓                           ↓
  确认哪个指标差            找到是哪个函数慢            找到资源加载瓶颈
     ↓                            ↓                           ↓
  对应第四/五/六章           用 taskSplitPoint 等         加 fetchpriority
  优化方案                   工具优化                     或 preload 优化

第四章：LCP 优化深度指南

4.1 LCP 的计算原理

理解 LCP 的计算方式，是优化的基础。

LCP 的候选元素在整个页面加载过程中是动态更新的。浏览器每渲染一帧，都会检查是否有比当前候选元素更大的元素出现。最终的 LCP 值是页面上出现的最大可见元素完成渲染的时间点。

LCP 计算会排除的元素：

透明度为 0（opacity: 0）的元素
尺寸为 0x0 的元素
visibility: hidden 的元素
覆盖整个视口的元素（被认为是背景）

这个排除规则非常关键，后面的优化技巧会用到它。

4.2 诊断 LCP 慢的原因

LCP 慢通常有以下几种原因：

服务器响应慢（TTFB 高） ：在第一个字节到达之前，什么都无法开始渲染
渲染阻塞资源：<head> 中的同步 CSS 和 JS 会阻塞渲染
资源加载慢：LCP 图片文件太大，或加载优先级低
客户端渲染延迟：LCP 元素由 JavaScript 动态生成，需要等待 JS 执行完成

诊断步骤：

打开 Lighthouse，在 LCP 的详情中，Chrome 会告诉你 LCP 的四个阶段各占了多少时间：

TTFB：服务器响应
Load Delay：从 TTFB 到开始加载 LCP 资源
Load Time：LCP 资源的加载时间
Render Delay：从资源加载完成到实际渲染

针对不同的瓶颈阶段，采取不同的优化策略。

4.3 LCP 图片优化技术

技术一：使用 fetchpriority="high" 提升图片优先级

这是最简单有效的优化手段之一。浏览器默认会给 LCP 图片分配较低的加载优先级，通过 fetchpriority 属性可以显式提升：

<!-- 优化前：浏览器可能将图片优先级设为 Low -->
<img src="hero-image.webp" alt="主图" />

<!-- 优化后：显式告知浏览器这是高优先级资源 -->
<img src="hero-image.webp" alt="主图" fetchpriority="high" />

注意：fetchpriority="high" 只应该用于真正的 LCP 元素，不要滥用，否则会适得其反。

技术二：使用 `<link rel="preload">` 预加载

对于通过 CSS background-image 或 JavaScript 动态加载的图片，浏览器无法在解析 HTML 时就发现并预加载，需要通过 preload 主动告知浏览器：

<head>
  <!-- 预加载 LCP 图片，让浏览器尽早开始加载 -->
  <link rel="preload" as="image" href="hero-image.webp" />

  <!-- 对于 srcset 图片，需要指定 imagesrcset -->
  <link
    rel="preload"
    as="image"
    href="hero-image.webp"
    imagesrcset="hero-small.webp 400w, hero-large.webp 800w"
    imagesizes="100vw"
  />
</head>

在构建系统中，可以通过配置自动注入 preload 标签：

{
  "links": [{
    "url": "hero-image.webp",
    "attrs": {
      "rel": "preload",
      "as": "image"
    }
  }]
}

技术三：使用 WebP 格式减小图片体积

WebP 相比 PNG 和 JPEG，在相同视觉质量下通常能减小 25%-50% 的文件体积：

<!-- 使用 picture 元素，兼容不支持 WebP 的浏览器 -->
<picture>
  <source srcset="hero.webp" type="image/webp" />
  <source srcset="hero.jpg" type="image/jpeg" />
  <img src="hero.jpg" alt="主图" fetchpriority="high" />
</picture>

实际数据：一张 500KB 的 PNG 图片，转换为 WebP 后通常在 100-200KB，加载时间可以缩短 60%-80%。

技术四：GIF 首帧优化

对于大尺寸 GIF 动图，可以先加载轻量级的首帧图片（通常是静态 PNG），待 GIF 加载完成后再切换：

// hooks/useGifImg.ts
import { useState, useMemo } from 'react';
import { useAsyncEffect } from 'ahooks';

/**
 * 加载指定图片，返回 Promise
 */
const loadImg = ({ src }: { src: string }): Promise<boolean> => {
  return new Promise((resolve) => {
    const img = new Image();
    img.onload = () => resolve(true);
    img.onerror = () => resolve(false);
    img.src = src;
  });
};

/**
 * GIF 图片优化 Hook
 * 策略：先展示首帧静态图（thumbnailUrl），GIF 加载完成后切换
 */
export const useGifImg = ({
  src,
  thumbnailUrl,
}: {
  src: string;
  thumbnailUrl?: string;
}) => {
  // 初始展示首帧（如果有的话），否则直接展示原图
  const [displayUrl, setDisplayUrl] = useState(thumbnailUrl || src);
  const isGif = useMemo(() => src.toLowerCase().endsWith('.gif'), [src]);

  useAsyncEffect(async () => {
    if (isGif && thumbnailUrl) {
      // 异步加载 GIF，加载完成后切换
      const isSuccess = await loadImg({ src });
      if (isSuccess) {
        setDisplayUrl(src);
      }
    }
  }, [src]);

  return { isGif, displayUrl };
};

// 使用示例
function HeroImage({ gifSrc, thumbnailSrc }) {
  const { displayUrl } = useGifImg({ src: gifSrc, thumbnailUrl: thumbnailSrc });

  return (
    <img
      src={displayUrl}
      alt="动态主图"
      fetchpriority="high"
    />
  );
}

技术五：背景图 Base64 占位优化

当 LCP 元素是一张需要通过网络加载的背景图时，可以用一张极小的 base64 内联图片作为占位符。这样 LCP 元素在页面 HTML 加载完成时就已经"出现"了，LCP 时间会大幅提前：

// 一个很小的纯色 base64 图片（约 100 字节）
// 颜色可以和实际背景图的主色调匹配，减少视觉突变
const DEFAULT_BG_BASE64 = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';

/**
 * 带 LCP 优化的背景图组件
 * 策略：
 * 1. 立即展示 base64 小图（作为 LCP 元素上报）
 * 2. 实际背景图加载完成后覆盖
 */
const OptimizedBgImage = ({ src, alt, children }) => {
  return (
    <div style={{ position: 'relative', overflow: 'hidden' }}>
      {/* LCP 占位图：base64，立即渲染，作为 LCP 元素 */}
      <img
        src={DEFAULT_BG_BASE64}
        alt={alt}
        style={{
          position: 'absolute',
          top: 0,
          left: 0,
          width: '100%',
          height: '100%',
          zIndex: 0,
          // 注意：不能设置 opacity: 0，否则会被 LCP 排除
        }}
      />
      {/* 实际背景图：通过 CSS 加载，不影响 LCP 计算 */}
      <div
        style={{
          position: 'absolute',
          top: 0,
          left: 0,
          width: '100%',
          height: '100%',
          backgroundImage: `url(${src})`,
          backgroundSize: 'cover',
          zIndex: 1,
        }}
      />
      {/* 内容层 */}
      <div style={{ position: 'relative', zIndex: 2 }}>
        {children}
      </div>
    </div>
  );
};

4.4 LCP 优化的终极技巧：主动"指定" LCP 元素

这是一个来自实战的进阶技巧。

背景：在某个项目中，页面真正有意义的 LCP 元素是一张很快就加载完成的小图。但页面还有一个用户引导弹层，弹层里有一张更大的图片。由于弹层是通过 JavaScript 渲染的，要等 JS 执行完才显示，而且弹层图片的尺寸更大，导致浏览器将弹层图片判定为 LCP 元素，LCP 时间被拉到了 5 秒以上。

解决方案：在页面首屏 HTML 中放置一个尺寸更大的占位图，让浏览器优先将它识别为 LCP 元素：

// 在页面根组件中放置这个"LCP 锚点"元素
function LCPAnchor() {
  return (
    <img
      // 使用一张加载极快的小图（如 base64 内联或 1px 透明图）
      src={getNoConnectionIcon()}
      // 关键：尺寸必须比其他竞争元素更大
      width={375}
      height={260}
      alt="LCP_hide_placeholder"
      style={{
        // 将元素隐藏，但不能使用 opacity: 0（会被 LCP 排除）
        // 使用 position: absolute 和 zIndex: -2 让它在内容层后面
        height: 260,
        left: 0,
        pointerEvents: 'none',   // 不响应鼠标事件
        position: 'absolute',
        zIndex: -2,              // 层叠在最底层，用户不可见
        top: 0,
        userSelect: 'none',      // 不可选中
        width: '100%',
      }}
    />
  );
}

原理：

这个元素在 HTML 中是可见的（不是 opacity: 0，不是 visibility: hidden），所以浏览器会将它纳入 LCP 候选
它的渲染尺寸（375×260）比弹层图片更大，所以会被选为 LCP 元素
它使用的是 base64 图片，随 HTML 一起内联，加载时间极短
通过 zIndex: -2 将它隐藏在内容层后面，用户看不到它

效果：LCP 时间从 5 秒以上降至 1 秒以内。

关键限制：以下方式会导致元素被 LCP 排除：

opacity: 0 - 完全透明，被认为无意义
visibility: hidden - 不可见
尺寸为 0×0
完全覆盖视口（被视为背景）

第五章：INP 优化深度指南

5.1 INP 慢的根本原因

INP 差的根本原因是主线程被长任务阻塞。当用户点击按钮时，如果主线程正在执行一个耗时 500ms 的 JavaScript 任务，浏览器就无法立即处理这个点击事件，INP 就会很差。

主线程阻塞的常见来源：

大量 DOM 操作：querySelectorAll、大规模 DOM 读写
复杂计算：加密运算、数据处理、排序过滤
大量 React 重渲染：不必要的 re-render、大列表渲染
同步的大文件加载：阻塞解析的 <script> 标签

5.2 使用 Chrome DevTools 定位 INP 问题

步骤一：使用 Live Metrics 确认 INP 问题

打开 Performance 面板的 Live Metrics
在页面上进行各种交互（点击、输入、滚动）
观察 INP 数值，找到使数值变大的操作

步骤二：录制性能分析

点击录制
执行刚才导致 INP 变大的操作
停止录制
在时间线上找到该交互对应的区域

步骤三：分析交互的三个阶段

在 Performance 面板中，点击一个交互事件，底部会显示该交互的三个阶段时间分布：

Input Delay：如果这个值很大，说明点击时主线程正在执行其他任务
Processing Time：如果这个值很大，说明事件处理函数本身太耗时
Presentation Delay：如果这个值很大，说明渲染过程太复杂

5.3 三种核心优化技术

技术一：asyncExecuteTask - 异步化处理时间

这个技术适合解决 Processing Time 过长的问题。原理是将耗时操作从当前的同步执行中剥离，放到下一个任务（Task）中执行。这样当前交互的 INP 就只计算到任务切换点，而不包含后续耗时操作。

// ── 底层调度器 ──────────────────────────────────────────────

/**
 * 封装 requestIdleCallback，兼容不支持的浏览器（降级为 setTimeout）
 * timeout 超时后强制执行，保证任务不会被无限期推迟
 */
function runRequestIdleCallback(fn, timeout = 300) {
  if (typeof requestIdleCallback !== 'undefined') {
    requestIdleCallback(fn, { timeout });
  } else {
    setTimeout(fn, 1); // 降级兼容
  }
}

/**
 * 封装 queueMicrotask，兼容不支持的浏览器
 */
function runQueueMicrotask(fn) {
  if (typeof queueMicrotask !== 'undefined') {
    queueMicrotask(fn);
  } else {
    Promise.resolve().then(fn);
  }
}

// ── asyncExecuteTask 实际源码 ────────────────────────────────

/**
 * @param fn          要异步执行的函数
 * @param option.highPriority  true → queueMicrotask（微任务）
 *                             false（默认）→ requestIdleCallback（空闲宏任务）
 * @param option.runTimeout    requestIdleCallback 的超时保底时间，默认 300ms
 * @param option.mustSplit     true → 强制 setTimeout(fn, 1)，确保产生新的宏任务边界
 */
const asyncExecuteTask = (fn, option) => {
  const {
    highPriority = false,
    runTimeout = 300,
    mustSplit = false,
  } = option || {};

  return new Promise((resolve) => {
    const wrappedFn = () => resolve(fn());

    if (mustSplit) {
      // 强制切分：通过 setTimeout 产生硬性宏任务边界
      return setTimeout(wrappedFn, 1);
    }
    if (highPriority) {
      // 高优先级：queueMicrotask，在当前宏任务末尾、下一宏任务前执行
      // 注意：微任务不会真正"让出主线程"，仅推迟到当前调用栈清空后
      return runQueueMicrotask(wrappedFn);
    }
    // 默认（低优先级）：requestIdleCallback，在浏览器空闲帧执行
    // 这是 INP 优化的核心：把耗时操作放到浏览器认为"当前帧已完成"之后
    return runRequestIdleCallback(wrappedFn, runTimeout);
  });
};

// ── asyncExecuteTaskHoc 实际源码 ─────────────────────────────

/**
 * HOC 版本：将一个函数包装成"调用时自动异步执行"的版本
 * 适合直接作为事件处理函数赋值，无需在调用处写 async/await
 */
const asyncExecuteTaskHoc = (fn, option) => {
  return (...params) => asyncExecuteTask(() => fn(...params), option);
};

三种调度策略对比

参数	调度机制	执行时机	适用场景
默认（低优先级）	`requestIdleCallback`	浏览器空闲帧	MobX store 更新、非紧急副作用
`highPriority: true`	`queueMicrotask`	当前调用栈清空后（微任务队列）	需要"稍后但尽快"执行的任务
`mustSplit: true`	`setTimeout(fn, 1)`	下一个宏任务（强制切分）	必须产生宏任务边界的场景

关键理解：requestIdleCallback 才是默认路径，不是 setTimeout。浏览器在完成当前帧的渲染后，如果还有剩余时间，才会执行 idle callback。这意味着 INP 的 Processing Time 几乎为 0——点击事件响应完成、画面更新后，耗时操作才开始跑。

// ============= 使用示例 =============

// 优化前：所有操作在一个同步任务中完成
// INP = Input Delay + (A耗时 + B耗时 + C耗时) + Presentation Delay
const handleClick_before = () => {
  doExpensiveOperationA(); // 耗时 100ms
  doExpensiveOperationB(); // 耗时 100ms
  setState({ ... });       // 触发重渲染
  doExpensiveOperationC(); // 耗时 100ms
  // INP Processing Time ≈ 300ms，差
};

// 优化后：耗时操作异步化
// INP = Input Delay + (setState耗时) + Presentation Delay
const handleClick_after = async () => {
  // 先执行 A，但立即让出控制权
  await asyncExecuteTask(() => {
    doExpensiveOperationA();
    doExpensiveOperationB();
  });

  // 这行代码决定了 INP 的 Processing Time
  setState({ ... });

  // 后续操作不影响当前 INP
  await asyncExecuteTask(() => {
    doExpensiveOperationC();
  });
};

实测数据：原始代码 INP = 340ms，使用 asyncExecuteTaskHoc 异步化后 INP = 9.19ms，几乎完全消除了交互延迟。

使用 performance-utils SDK：

import { asyncExecuteTask, asyncExecuteTaskHoc } from "performance-utils";

// 方式一：asyncExecuteTask（适合需要 await 的场景）
const handleClick = async () => {
  await asyncExecuteTask(() => {
    doExpensiveOperationA();
    doExpensiveOperationB();
  });

  setShowContent(!showContent); // 状态更新

  await asyncExecuteTask(() => {
    doExpensiveOperationC();
    doExpensiveOperationD();
  });
};

// 方式二：asyncExecuteTaskHoc（适合整个函数都需要异步化的场景）
const handleClick = asyncExecuteTaskHoc(
  () => {
    doExpensiveOperationA();
    doExpensiveOperationB();
    setShowContent(!showContent);
    doExpensiveOperationC();
    doExpensiveOperationD();
  }
);

技术二：taskSplitPoint - 长任务切片

这个技术适合解决一个函数内有多段耗时代码、需要在任务之间让出主线程的场景。

// ── taskSplitPoint 实际源码 ──────────────────────────────────

/**
 * 注意：使用的是 setTimeout(resolve, 1) 而非 setTimeout(resolve, 0)
 *
 * 为什么是 1ms 而不是 0ms？
 * - setTimeout(fn, 0) 在不同浏览器/场景下实际延迟可能被折叠到 0-4ms
 * - 使用 1ms 可以更可靠地保证产生一个真正的宏任务边界
 * - 浏览器有 4ms 的最小定时器间隔（嵌套 setTimeout 时），1ms 足以触发边界
 */
const taskSplitPoint = () => {
  return new Promise((resolve) => {
    setTimeout(resolve, 1);
  });
};

// ── runTasks 实际源码（async generator 模式）────────────────

/**
 * 顺序执行任务队列，每个任务之间自动插入 taskSplitPoint
 * 使用 for...of 循环 + yield，逐个执行并收集结果
 */
const runTasks = async (taskList) => {
  const results = [];
  for (const task of taskList) {
    results.push(await task());
    await taskSplitPoint(); // 每个任务完成后让出主线程
  }
  return results;
};

// ── runTasksParallel 实际源码 ────────────────────────────────

/**
 * 并行执行所有任务
 * 使用 Promise.allSettled 而非 Promise.all：
 * - Promise.all：任意一个任务失败就立即 reject，其他任务被放弃
 * - Promise.allSettled：等待所有任务完成，无论成功或失败，结果中包含每个任务的状态
 * 选用 allSettled 是为了容错——某个任务失败不应影响其他任务执行
 */
const runTasksParallel = (taskList) => {
  return Promise.allSettled(taskList.map((task) => task()));
};

// ── runArrayIterationTask 实际源码 ───────────────────────────

/**
 * @param array        要遍历的数组
 * @param fun          遍历回调，参数与 Array.map 一致：(value, index, array)
 * @param splitPointNum 插入几个切分点（默认 2）
 *
 * 切分逻辑：按数组长度均分，每隔 length/splitPointNum 个元素插一个切分点
 * 特殊处理：splitPointNum=1 时按 length/2 计算，避免只插一个点在中间
 */
const runArrayIterationTask = async (array, fun, splitPointNum = 2) => {
  const result = [];
  const batchSize = array.length / (splitPointNum === 1 ? 2 : splitPointNum);

  for (let i = 0; i < array.length; i++) {
    result.push(fun(array[i], i, array));
    if (Math.floor(i % batchSize) === 0) {
      await taskSplitPoint();
    }
  }
  return result;
};

// ============= 使用示例 =============

// 优化前：一个巨大的长任务
const processData = async () => {
  // 这整个函数是一个 500ms 的长任务
  parseAndValidateData(rawData);     // 100ms
  transformData(parsedData);         // 150ms
  calculateStatistics(transformed);  // 120ms
  renderChart(statistics);           // 130ms
};

// 优化后：通过 taskSplitPoint 切分为多个小任务
const processData_optimized = async () => {
  parseAndValidateData(rawData);     // 100ms 任务一
  await taskSplitPoint();            // ← 切分点，让出主线程

  transformData(parsedData);         // 150ms 任务二
  await taskSplitPoint();            // ← 切分点

  calculateStatistics(transformed);  // 120ms 任务三
  await taskSplitPoint();            // ← 切分点

  renderChart(statistics);           // 130ms 任务四
  // 现在是 4 个 ≤ 150ms 的任务，而不是 1 个 500ms 的长任务
};

使用 SDK：

import { taskSplitPoint, runTasks, runTasksParallel } from "performance-utils";

// taskSplitPoint 基础用法
const handleClick = async () => {
  doStep1();
  await taskSplitPoint(); // 切分点一
  doStep2();
  await taskSplitPoint(); // 切分点二
  doStep3();
};

// runTasks：将任务数组按顺序切片执行
// 实测 INP = 90.63ms（原始 340ms）
const handleClick = async () => {
  await runTasks([
    () => doExpensiveOperationA(),
    () => doExpensiveOperationB(),
  ]);
  setShowContent(!showContent);
  await runTasks([
    () => doExpensiveOperationC(),
    () => doExpensiveOperationD(),
  ]);
};

// runTasksParallel：并行执行多个任务（不保证执行顺序）
const handleClick = async () => {
  // A 和 B 会并行执行，总时间 ≈ max(A耗时, B耗时)
  await runTasksParallel([
    () => doIndependentTaskA(),
    () => doIndependentTaskB(),
  ]);
  setShowContent(!showContent);
};

// runArrayIterationTask：对数组进行切片遍历
// 参数：数组, 回调函数, 每批处理数量
const processItems = async () => {
  const items = [1, 2, 3, ..., 10000]; // 大数组
  await runArrayIterationTask(
    items,
    (value, index, array) => {
      processItem(value); // 处理每个元素
    },
    50 // 每批处理 50 个，处理完一批后让出主线程
  );
  setProcessed(true);
};

实测对比数据：

优化方案	INP 值	说明
原始代码	340ms	所有操作在单个长任务中执行
taskSplitPoint 切片	130ms	任务被分为四段
runTasks 队列切片	90.63ms	通过任务队列管理
asyncExecuteTaskHoc 异步化	9.19ms	几乎完全消除延迟

技术三：useTransition - React 18 并发优化

这个技术专门针对 React 应用中的渲染引起的 INP 问题。

原理：React 18 的 useTransition 可以将某个状态更新标记为"非紧急"，React 会将对应的渲染工作切分为小的可中断单元（Fiber 调度），当检测到用户有新的输入时，可以暂停非紧急渲染，先处理用户输入，再恢复渲染。

import { useState, useTransition } from 'react';

/**
 * 场景：搜索输入框 + 大列表过滤
 * 问题：输入时更新列表（10000条数据），导致输入卡顿
 * 优化：将列表更新标记为非紧急，确保输入框始终流畅
 */
function SearchWithTransition() {
  const [inputValue, setInputValue] = useState('');
  const [filteredList, setFilteredList] = useState(allItems);
  const [isPending, startTransition] = useTransition();

  const handleInput = (e) => {
    const value = e.target.value;

    // 输入框更新是紧急操作，直接更新，不会被中断
    setInputValue(value);

    // 列表过滤是非紧急操作，包裹在 startTransition 中
    // React 会在空闲时处理，用户输入会打断并重新开始
    startTransition(() => {
      const newList = allItems.filter(item =>
        item.name.toLowerCase().includes(value.toLowerCase())
      );
      setFilteredList(newList);
    });
  };

  return (
    <div>
      <input
        value={inputValue}
        onChange={handleInput}
        placeholder="搜索..."
      />
      {/* isPending 为 true 时说明列表还在更新中 */}
      {isPending && <span style={{ opacity: 0.5 }}>更新中...</span>}
      <ul>
        {filteredList.map(item => (
          <li key={item.id}>{item.name}</li>
        ))}
      </ul>
    </div>
  );
}

使用场景总结：

场景	推荐方案	原因
处理函数中有多段耗时操作	`taskSplitPoint`	在关键位置插入切分点
MobX store 属性更改	`asyncExecuteTask`	将 MobX 更新异步化
React setState 触发大量重渲染	`useTransition`	利用 React 并发特性
大数组批量处理	`runArrayIterationTask`	分批处理，避免长任务
多个独立任务并行	`runTasksParallel`	充分利用浏览器调度

5.4 优化 Input Delay

如果 INP 的瓶颈是 Input Delay（用户点击到事件处理开始的延迟），说明点击时主线程正在执行其他代码，通常是：

定时器轮询：大量 setInterval 短期轮询
动画帧占用：requestAnimationFrame 中执行了太多工作
后台任务：没有被用户触发的定时任务占用主线程

解决方案：

用 requestIdleCallback 执行后台任务，在主线程空闲时运行
减少 setInterval 的频率
将复杂计算移入 Web Worker（详见第八章）

第六章：CLS 优化深度指南

6.1 CLS 的计算原理

CLS（累积布局偏移）计算的是页面整个生命周期内所有意外布局偏移的累积分数。

单次布局偏移分数 = 影响分数 × 距离分数
影响分数 = 偏移前后合并区域占视口的比例
距离分数 = 元素移动的最大距离 / 视口尺寸

例如：一个按钮从视口中间移动到顶部，移动了视口高度的 25%，影响了视口 50% 的区域：

距离分数 = 0.25
影响分数 = 0.5
单次 CLS = 0.25 × 0.5 = 0.125（已超过良好阈值）

注意：由用户操作（点击、键盘输入）触发的布局变化不计入 CLS，只有页面自发的变化才会被计算。

6.2 CLS 的常见原因与修复

原因一：图片无尺寸

问题：图片没有指定 width 和 height 属性，浏览器不知道要为图片预留多大的空间，图片加载后会把下面的内容往下推。

<!-- ❌ 错误：没有尺寸，会导致 CLS -->
<img src="product.jpg" alt="产品图" />

<!-- ✅ 正确：指定宽高，浏览器预留空间 -->
<img src="product.jpg" alt="产品图" width="400" height="300" />

对于响应式图片，使用 aspect-ratio CSS 属性：

/* 使用 aspect-ratio 预留空间 */
.product-image {
  width: 100%;
  aspect-ratio: 4 / 3; /* 宽高比 */
}

原因二：动态注入的内容

问题：广告、通知横幅、Cookie 提示等内容在加载后才动态插入到页面顶部，把下面的内容往下推。

// ❌ 错误：动态插入横幅会导致 CLS
function Page() {
  const [showBanner, setShowBanner] = useState(false);

  useEffect(() => {
    // 1秒后显示广告横幅，把页面内容往下推
    setTimeout(() => setShowBanner(true), 1000);
  }, []);

  return (
    <div>
      {showBanner && <AdBanner />} {/* 这里会导致 CLS */}
      <MainContent />
    </div>
  );
}

// ✅ 正确方案一：预留空间
function Page() {
  const [showBanner, setShowBanner] = useState(false);

  useEffect(() => {
    setTimeout(() => setShowBanner(true), 1000);
  }, []);

  return (
    <div>
      {/* 预留固定高度的容器，无论横幅是否显示都占据这个空间 */}
      <div style={{ height: '60px', minHeight: '60px' }}>
        {showBanner && <AdBanner />}
      </div>
      <MainContent />
    </div>
  );
}

// ✅ 正确方案二：使用 position: fixed/sticky，不占文档流空间
function Page() {
  return (
    <div>
      <MainContent />
      {/* 使用固定定位，不影响文档流 */}
      <CookieBanner style={{ position: 'fixed', bottom: 0 }} />
    </div>
  );
}

原因三：Web 字体导致的文本偏移（FOUT/FOIT）

问题：页面先用系统字体渲染文本，Web 字体加载完成后切换，导致文本大小变化、布局偏移。

/* ✅ 使用 font-display: optional */
/* optional 策略：如果字体在极短时间内没有加载完，就放弃使用自定义字体 */
@font-face {
  font-family: 'MyFont';
  src: url('my-font.woff2') format('woff2');
  font-display: optional; /* 减少 FOUT */
}

/* ✅ 使用 size-adjust 减少字体切换时的布局变化 */
@font-face {
  font-family: 'FallbackFont';
  src: local('Arial');
  size-adjust: 105%; /* 调整备用字体大小，使其更接近自定义字体 */
  ascent-override: 95%;
}

原因四：后期加载的骨架屏尺寸不准确

骨架屏（Skeleton）的尺寸应该尽量与实际内容保持一致，否则内容加载后的替换会导致布局偏移：

// ❌ 错误：骨架屏高度和实际内容高度不一致
function UserCard({ user }) {
  if (!user) {
    return <div style={{ height: '50px' }}>加载中...</div>; // 高度不准确
  }

  return (
    <div style={{ height: '80px' }}> {/* 实际高度是 80px，骨架是 50px */}
      <img src={user.avatar} width="40" height="40" />
      <span>{user.name}</span>
      <span>{user.bio}</span>
    </div>
  );
}

// ✅ 正确：骨架屏与实际内容尺寸一致
function UserCard({ user }) {
  if (!user) {
    return (
      <div style={{ height: '80px', display: 'flex', alignItems: 'center' }}>
        {/* 骨架屏的布局和实际内容保持一致 */}
        <div style={{ width: 40, height: 40, borderRadius: '50%', background: '#eee' }} />
        <div style={{ marginLeft: 12 }}>
          <div style={{ width: 100, height: 16, background: '#eee' }} />
          <div style={{ width: 200, height: 12, background: '#eee', marginTop: 8 }} />
        </div>
      </div>
    );
  }

  return (
    <div style={{ height: '80px', display: 'flex', alignItems: 'center' }}>
      <img src={user.avatar} width="40" height="40" style={{ borderRadius: '50%' }} />
      <div style={{ marginLeft: 12 }}>
        <div style={{ fontSize: '16px', lineHeight: '16px' }}>{user.name}</div>
        <div style={{ fontSize: '12px', marginTop: 8 }}>{user.bio}</div>
      </div>
    </div>
  );
}

6.3 用 Chrome DevTools 诊断 CLS

在 Lighthouse 报告中，找到 CLS 指标，点击展开
查看哪些元素发生了偏移（Lighthouse 会列出偏移元素的选择器）
在 Performance 面板中录制，找到 Layout Shift 事件（紫色标记）
点击 Layout Shift 事件，查看哪个元素发生了偏移以及偏移量

第七章：TTFB 与网络优化

7.1 TTFB 慢的诊断

TTFB（首字节时间）是所有性能指标的起点。如果 TTFB 超过 200ms，即使其他所有优化都做得完美，LCP 也很难达到良好水平。

在 Chrome DevTools Network 面板中，点击 HTML 文档请求，查看 Timing 标签：

Queued at 0ms           ← 请求被排入队列
Stalled for Xms         ← 等待发送（连接限制、缓存检查等）
DNS Lookup: Xms         ← DNS 解析时间
Initial connection: Xms ← TCP 连接时间
SSL: Xms                ← TLS 握手时间（HTTPS）
Request sent: Xms       ← 请求发送时间
Waiting (TTFB): Xms     ← ← 这里是服务器处理时间，是核心指标
Content Download: Xms   ← HTML 下载时间

7.2 CDN 优化

CDN（内容分发网络）通过将静态资源分发到全球多个节点，减少用户到服务器的物理距离，是降低 TTFB 最有效的手段之一。

配置 CDN 的关键点：

# Nginx 配置：为静态资源设置长效缓存
location ~* .(js|css|png|jpg|gif|ico|woff2)$ {
    # 静态资源缓存 1 年
    expires 365d;
    add_header Cache-Control "public, max-age=31536000, immutable";
    # immutable 告诉浏览器在缓存期内不要重新验证
}

location /api/ {
    # API 接口不缓存
    add_header Cache-Control "no-store";
    proxy_pass http://backend;
}

前端资源的内容哈希：

现代构建工具（Webpack、Vite）会在文件名中加入内容哈希，当文件内容变化时哈希也变化，确保用户始终获取最新版本：

// webpack.config.js
module.exports = {
  output: {
    // [contenthash] 会根据文件内容生成哈希
    filename: 'js/[name].[contenthash:8].js',
    chunkFilename: 'js/[name].[contenthash:8].chunk.js',
  },
};

7.3 HTTP/2 和 HTTP/3

HTTP/2 的优势：

多路复用：一个连接可以同时处理多个请求，解决了 HTTP/1.1 的队头阻塞问题
头部压缩：使用 HPACK 压缩请求头，减少重复头部的传输开销
服务器推送：服务器可以在客户端请求之前主动推送资源

验证是否使用 HTTP/2：

在 Chrome DevTools Network 面板中，右键列标题，勾选 Protocol 列，如果看到 h2 就是 HTTP/2。

7.4 资源预连接

对于需要从第三方域名加载的关键资源，可以使用 preconnect 提前建立连接：

<head>
  <!-- 提前与 CDN 建立连接（DNS解析 + TCP连接 + TLS握手） -->
  <link rel="preconnect" href="https://cdn.example.com" crossorigin />

  <!-- 仅提前做 DNS 解析，不建立连接（适合不确定是否会用到的域名） -->
  <link rel="dns-prefetch" href="https://analytics.example.com" />
</head>

第八章：代码层面的通用优化

8.1 代码分割（Code Splitting）

代码分割是减少首屏 JavaScript 体积最有效的手段。核心思想是：首屏只加载必要的代码，其他代码按需加载。

// webpack.config.js - 配置代码分割
module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        // 将 node_modules 中的代码单独打包
        vendors: {
          test: /[\/]node_modules[\/]/,
          name: 'vendors',
          chunks: 'all',
          priority: 10,
        },
        // 将 React 相关库单独打包（变化少，可以长期缓存）
        react: {
          test: /[\/]node_modules[\/](react|react-dom|react-router)[\/]/,
          name: 'react-vendor',
          chunks: 'all',
          priority: 20,
        },
      },
    },
  },
};

8.2 路由级别的懒加载

在 React 应用中，每个路由页面都应该懒加载：

// router.tsx - 路由级懒加载
import { lazy, Suspense } from 'react';

// lazy() 会在组件首次被渲染时才加载对应的 JS 文件
const HomePage = lazy(() => import('./pages/HomePage'));
const TradePage = lazy(() => import('./pages/TradePage'));
const SettingsPage = lazy(() => import('./pages/SettingsPage'));

function App() {
  return (
    // Suspense 提供加载状态
    <Suspense fallback={<PageLoading />}>
      <Routes>
        <Route path="/" element={<HomePage />} />
        <Route path="/trade" element={<TradePage />} />
        <Route path="/settings" element={<SettingsPage />} />
      </Routes>
    </Suspense>
  );
}

效果：假设每个页面有 50KB 的 JS，有 10 个页面，不做懒加载首屏需要加载 500KB，做了懒加载首屏只需要加载当前页面的 50KB，减少 90%。

8.3 组件级别的懒加载

对于非关键的弹层、标签页内容等，可以延迟加载：

import { lazy, Suspense, useState } from 'react';

// 交易详情弹层：用户点击时才加载
const TxDetailModal = lazy(() => import('./TxDetailModal'));

function TxList() {
  const [selectedTx, setSelectedTx] = useState(null);

  return (
    <div>
      {transactions.map(tx => (
        <div key={tx.id} onClick={() => setSelectedTx(tx)}>
          {tx.hash}
        </div>
      ))}

      {/* 只在需要时才渲染（并加载）弹层组件 */}
      {selectedTx && (
        <Suspense fallback={<Spinner />}>
          <TxDetailModal tx={selectedTx} onClose={() => setSelectedTx(null)} />
        </Suspense>
      )}
    </div>
  );
}

8.4 Tree Shaking

Tree Shaking 是构建工具在打包时自动移除未使用代码的优化。要让 Tree Shaking 正常工作，需要注意：

// ❌ 全量引入：会打包整个 lodash（几百 KB）
import _ from 'lodash';
const result = _.debounce(fn, 300);

// ✅ 按需引入：只打包 debounce（几 KB）
import debounce from 'lodash/debounce';
const result = debounce(fn, 300);

// ✅ 更好的方案：使用支持 Tree Shaking 的 ES Module 版本
import { debounce } from 'lodash-es';
const result = debounce(fn, 300);

对于 UI 组件库：

// ❌ 错误：引入整个组件库
import { Button, Input } from 'some-ui-library';

// ✅ 正确：使用 babel-plugin-import 按需引入
// 配置 .babelrc：
{
  "plugins": [
    ["import", {
      "libraryName": "some-ui-library",
      "style": true // 同时按需引入样式
    }]
  ]
}

8.5 Web Workers

将 CPU 密集型计算移入 Web Worker，避免阻塞主线程：

// crypto.worker.js - Web Worker 文件
self.onmessage = function(e) {
  const { type, data } = e.data;

  if (type === 'HASH') {
    // 在 Worker 中执行加密运算，不阻塞主线程
    const result = expensiveCryptoOperation(data);
    self.postMessage({ type: 'HASH_RESULT', result });
  }
};

// main.js - 主线程
const cryptoWorker = new Worker('./crypto.worker.js');

async function hashData(data) {
  return new Promise((resolve) => {
    cryptoWorker.postMessage({ type: 'HASH', data });
    cryptoWorker.onmessage = (e) => {
      if (e.data.type === 'HASH_RESULT') {
        resolve(e.data.result);
      }
    };
  });
}

// 主线程调用：加密运算在 Worker 中执行，不阻塞 UI
const hash = await hashData(rawData);

实际案例：在前面提到的性能分析中，Web3 加密库占 CPU 42.3%，将其移入 Web Worker 可以基本消除主线程阻塞。

8.6 虚拟列表

当列表数据量很大（数百到数万条）时，不应该渲染所有 DOM 节点，而应该使用虚拟列表：

import { FixedSizeList as List } from 'react-window';

// ❌ 错误：渲染 10000 个真实 DOM 节点
function BigList({ items }) {
  return (
    <ul>
      {items.map(item => (
        <li key={item.id} style={{ height: 50 }}>
          {item.name}
        </li>
      ))}
    </ul>
  );
}

// ✅ 正确：虚拟列表，只渲染视口内的节点（通常约 20 个）
function VirtualBigList({ items }) {
  const Row = ({ index, style }) => (
    // style 包含 position、top、height 等虚拟列表所需样式
    <div style={style}>
      {items[index].name}
    </div>
  );

  return (
    <List
      height={600}        // 列表容器高度
      itemCount={items.length}   // 总条目数
      itemSize={50}       // 每行高度（固定）
      width="100%"
    >
      {Row}
    </List>
  );
}

8.7 React 性能优化

import { memo, useMemo, useCallback } from 'react';

// ✅ React.memo：避免不必要的组件重渲染
const TxItem = memo(function TxItem({ tx, onSelect }) {
  return (
    <div onClick={() => onSelect(tx)}>
      {tx.hash} - {tx.amount}
    </div>
  );
});

// ✅ useMemo：缓存计算结果
function TxList({ transactions, filter }) {
  // 只有 transactions 或 filter 变化时才重新计算
  const filteredTxs = useMemo(
    () => transactions.filter(tx => tx.type === filter),
    [transactions, filter]
  );

  // ✅ useCallback：缓存函数引用，避免子组件重渲染
  const handleSelect = useCallback((tx) => {
    console.log('Selected:', tx.hash);
  }, []); // 依赖为空，函数引用永远不变

  return (
    <ul>
      {filteredTxs.map(tx => (
        <TxItem key={tx.id} tx={tx} onSelect={handleSelect} />
      ))}
    </ul>
  );
}

第九章：综合实战——完整性能排查流程

9.1 场景描述

假设你接手了一个新页面，用户反映"这个页面很慢，点了没反应"。下面是完整的排查和优化流程。

9.2 第一步：建立基准数据

在优化之前，先测量现状，建立基准：

使用 Lighthouse 获取综合评分：在隐身模式下，对目标页面运行 Lighthouse，记录所有指标数值
记录用户场景：明确用户说"慢"是哪个场景——是页面加载慢、还是点击某个按钮后没反应
确认设备环境：移动端还是桌面端，网络速度如何

假设 Lighthouse 报告如下：

Performance Score: 32
LCP: 5.8s  (差)
INP: 420ms (需改进)
CLS: 0.18  (需改进)
TTFB: 850ms
TBT: 3200ms

9.3 第二步：定位 TTFB 瓶颈

TTFB 850ms 远超 200ms 的良好阈值，先排查这个：

打开 Network 面板，找到 HTML 文档请求
查看 Timing：Waiting (TTFB): 750ms
750ms 都在等待服务器响应，说明是服务端问题（API 慢、数据库慢、没有 CDN 等）

解决方案：

联系后端优化 API 响应速度
确认 HTML 是否经过 CDN 分发
对于 SSG/SSR 内容，确认是否有适当的缓存

9.4 第三步：分析 LCP 问题

TTFB 处理后，关注 LCP：

在 Lighthouse 报告中找到 LCP 截图，查看被识别为 LCP 的元素
假设 LCP 元素是一张 600KB 的 PNG 主图
在 Network 面板中找到该图片的请求，查看：
1. Priority：Low（加载优先级低！）
2. Content-Encoding：(none)（没有压缩）
3. 下载时间：1.8s（文件太大）

优化方案：

<!-- 原来 -->
<img src="hero.png" alt="主图" />

<!-- 优化后 -->
<link rel="preload" as="image" href="hero.webp" />
<img src="hero.webp" alt="主图" fetchpriority="high" width="1200" height="600" />

同时将图片转换为 WebP 格式，体积从 600KB 减小到约 150KB。

9.5 第四步：分析 INP 和长任务

TBT 3200ms 说明有大量长任务，这是 INP 差的根本原因：

录制 Performance，找到页面加载和用户交互的时间线
在 Main 区域识别红色三角形标记的长任务
展开最长的任务，查看调用栈

假设发现：

filterTransactions() 函数执行了 800ms
原因是每次都重新遍历 10000 条交易记录

优化方案：

// 优化前：每次点击都同步过滤 10000 条数据
const handleFilterChange = (filter) => {
  const filtered = allTransactions.filter(tx => matchFilter(tx, filter)); // 800ms
  setFilteredTxs(filtered);
};

// 优化后：使用 taskSplitPoint 拆分任务
import { taskSplitPoint } from 'performance-utils';

const handleFilterChange = async (filter) => {
  // 先更新 UI 状态（让用户感觉立即响应）
  setIsFiltering(true);

  await taskSplitPoint(); // 让出主线程

  // 分批过滤
  const BATCH_SIZE = 500;
  const results = [];
  for (let i = 0; i < allTransactions.length; i += BATCH_SIZE) {
    const batch = allTransactions.slice(i, i + BATCH_SIZE);
    results.push(...batch.filter(tx => matchFilter(tx, filter)));
    await taskSplitPoint(); // 每处理500条让出一次主线程
  }

  setFilteredTxs(results);
  setIsFiltering(false);
};

9.6 第五步：修复 CLS 问题

CLS 0.18 超过了 0.1 的良好阈值：

在 Performance 面板中录制页面加载
找到紫色的 Layout Shift 事件
点击后查看是哪个元素发生了偏移

假设发现是顶部的 banner 图片加载后把下面内容推下去了：

// 优化前
<img src="banner.webp" alt="banner" />

// 优化后：指定宽高，预留空间
<img
  src="banner.webp"
  alt="banner"
  width="1200"
  height="300"
  style={{ width: '100%', height: 'auto' }}
/>

9.7 第六步：验证优化效果

再次运行 Lighthouse，对比数据：

优化前:
Performance Score: 32
LCP: 5.8s  → 优化后: 1.9s ✅
INP: 420ms → 优化后: 180ms ✅
CLS: 0.18  → 优化后: 0.05 ✅
TTFB: 850ms → 优化后: 180ms ✅
TBT: 3200ms → 优化后: 380ms (仍需改进)
Performance Score: 32 → 78

对于仍然偏高的 TBT，继续分析剩余的长任务，逐步优化。

9.8 优化的优先级原则

当面对多个需要优化的问题时，按照以下优先级处理：

首先解决 TTFB：这是所有指标的基础
然后解决 LCP：影响用户对页面加载速度的第一印象
然后解决 INP：影响用户与页面的交互体验
最后解决 CLS：减少用户困惑和误操作

第十章：性能监控与持续改进

10.1 真实用户监控（RUM）与实验室测试的区别

Lighthouse 和 Performance 面板是"实验室测试"——在受控环境下测量的数据。真实用户的体验可能因为网络状况、设备性能、地理位置等因素有很大差异。

真实用户监控（RUM, Real User Monitoring） ：

在真实用户的浏览器中收集性能数据
数据更真实，但需要用户量才有统计意义
Google Search Console 中的 Core Web Vitals 报告就是基于真实用户数据

10.2 使用 web-vitals 库收集性能数据

// performance-monitor.ts
import { onLCP, onINP, onCLS, onFCP, onTTFB } from 'web-vitals';

// 将性能数据发送到分析服务
function sendToAnalytics(metric) {
  const { name, value, rating, id } = metric;

  // rating 是 'good' | 'needs-improvement' | 'poor'
  console.log(`${name}: ${value}ms (${rating})`);

  // 发送到你的分析服务
  fetch('/api/analytics/performance', {
    method: 'POST',
    body: JSON.stringify({
      metricName: name,
      value: Math.round(value),
      rating,
      id,
      url: window.location.href,
      timestamp: Date.now(),
    }),
  });
}

// 注册所有 Core Web Vitals 监听
onLCP(sendToAnalytics);
onINP(sendToAnalytics);
onCLS(sendToAnalytics);
onFCP(sendToAnalytics);
onTTFB(sendToAnalytics);

10.3 性能预算

性能预算是指为关键性能指标设置上限，当预算被超出时触发告警或构建失败：

// webpack.config.js - 配置性能预算
module.exports = {
  performance: {
    // 资源超出大小限制时发出警告
    hints: 'warning',
    // 单个文件最大 250KB
    maxAssetSize: 250 * 1024,
    // 入口文件总大小最大 500KB（包含所有同步依赖）
    maxEntrypointSize: 500 * 1024,
    // 只对 JS 和 CSS 文件执行检查
    assetFilter: (assetFilename) => {
      return /.(js|css)$/.test(assetFilename);
    },
  },
};

在 CI/CD 流程中集成性能测试：

# .gitlab-ci.yml
performance_test:
  stage: test
  script:
    # 使用 Lighthouse CI 进行性能测试
    - npx lhci autorun
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

// lighthouserc.js
module.exports = {
  ci: {
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        // LCP 必须低于 2500ms，否则 CI 失败
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        // INP 必须低于 200ms
        'experimental-interaction-to-next-paint': ['warn', { maxNumericValue: 200 }],
        // TBT 必须低于 300ms
        'total-blocking-time': ['error', { maxNumericValue: 300 }],
      },
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
};

10.4 建立性能优化文化

性能优化不是一次性的工作，而是需要持续维护的过程。建立良好的性能优化文化需要：

可见性：将性能指标加入团队的监控大盘，让所有人都能看到
责任制：每次新功能上线，开发者需要提供性能测试数据
自动化：在 CI/CD 中集成性能测试，防止性能退化
教育：定期分享性能优化案例，提升团队意识

10.5 性能优化 Checklist

在每个新功能上线前，使用以下检查清单自检：

加载性能：

LCP 元素是否添加了 fetchpriority="high" 或
图片是否指定了 width 和 height 属性（防止 CLS）
图片是否使用了 WebP 格式
大图是否已经压缩到合理大小（通常移动端 < 200KB）
新增的第三方域名是否添加了 preconnect

代码质量：

新增的路由/弹层是否使用了懒加载（React.lazy）
是否引入了新的大型依赖库（通过 Bundle Analyzer 检查）
是否有不必要的全量引入（如 import _ from 'lodash'）

交互性能：

点击事件处理函数是否有超过 50ms 的同步操作
是否有大数组遍历在事件处理函数中
大列表是否使用了虚拟列表

布局稳定性：

动态插入的内容是否预留了空间
是否有可能导致页面内容重排的操作

10.6 总结：性能优化的核心思想

经过十章的学习，我们可以总结出性能优化的几个核心思想：

1. 测量优先：永远先测量，再优化。没有数据支撑的优化可能是无效甚至有害的。

2. 用户感知优先：性能优化的目标是改善用户感知，不是追求技术数字。有时候"感觉快"比实际数字更重要（如添加骨架屏）。

3. 关键路径优先：页面加载是一条关键路径（TTFB → FCP → LCP），优化要从瓶颈处入手，不要优化不在关键路径上的内容。

4. 主线程保护：所有交互性能问题的根源都是主线程被阻塞。保持主线程畅通，是 INP 优化的核心策略。

5. 渐进增强：先呈现核心内容，再逐步加载增强功能。首屏只加载必要资源，其他内容懒加载。

6. 持续监控：性能是一个会随着业务发展而退化的指标，需要通过 RUM 和 CI/CD 持续监控和保护。

附录：工具资源

在线分析工具

PageSpeed Insights（pagespeed.web.dev）：Google 官方工具，同时显示实验室数据和真实用户数据
WebPageTest（webpagetest.org）：更详细的瀑布图分析，支持多地点测试
web.dev/measure：基于 Lighthouse 的在线测量工具

npm 包

web-vitals（npm i web-vitals）：Google 官方的 Core Web Vitals 收集库
performance-utils（npm i performance-utils）：性能优化工具集
react-window（npm i react-window）：虚拟列表
react-virtualized（npm i react-virtualized）：更完整的虚拟化方案

学习资源

web.dev/performance：Google 官方性能优化文档，是最权威的学习资源
Chrome Developers YouTube 频道：有大量 Performance 面板的使用教程

Ant Design Pro v6.0.0 发布

掘金前端

作者支付宝体验科技

2026年5月6日 19:57

距离 v5 发布已经过去快五年了。五年间，前端世界发生了翻天覆地的变化——React 18/19 带来了并发渲染，antd 从 v4 升级到了 v6，构建工具从 webpack 演进到了 Turbopack，CSS-in-JS 和 Tailwind 成为主流。v6 做了两件事：全面拥抱最新技术栈，以及清理历史包袱。

🌟 v6 背后的蚂蚁生态

Ant Design V6 — 企业级设计系统。Pro v6 全面采用 antd 6，启用 CSS 变量模式（cssVar），支持 Default、Dark、Glass 等多种风格预设，渲染性能显著提升。
Ant Design X — AI 界面解决方案，基于 RICH 设计范式将 GUI 与自然语言交互有机融合。Pro v6 内置的 AI 助手页面基于 Ant Design X 构建，开箱即用。
Ant Design CLI — 官方命令行工具（npx antd），查询组件 API、获取示例代码、诊断项目配置一步到位。Pro v6 已内置集成，告别频繁翻文档。
utoo — 基于 Turbopack 的 Rust 构建引擎，提供极速冷启动和毫秒级 HMR。Pro v6 默认使用 utoopack 构建，生产构建提速约 42%。

🚀 框架升级

React 19 + antd 6

v6 基于 React 19 和 antd 6 构建。React 19 的并发特性与 Server Components，antd 6 的设计系统更新与 CSS 变量主题——这些在 v5 中还无法触及的能力，现在开箱即用。

Umi Max 4

v5 已在使用 Umi Max，v6 升级到 @umijs/max 4，带来 utoopack 默认构建引擎和更完善的插件体系：

- import { useModel } from 'umi';
+ import { useModel, request, useAccess, getLocale, useIntl } from '@umijs/max';

ProComponents v3

分散的 @ant-design/pro-table、@ant-design/pro-form、@ant-design/pro-layout 等多个包统一为 @ant-design/pro-components v3。一个包解决所有中后台组件需求，版本对齐不再头疼。

💎 样式体系重构

v5 的样式基于 Less，这在早期是明智的选择，但 Less 的维护活跃度持续下降。v6 全面迁移到现代 CSS 方案：

Tailwind CSS v4：原子化 CSS，布局和间距不再需要写自定义样式
antd-style v4：消费 antd Design Token 的 CSS-in-JS 方案，主题切换零成本
CSS Modules：组件级样式隔离，避免命名冲突

同时启用 antd CSS 变量模式（cssVar），不仅支持动态主题切换，渲染性能也有提升。

⚡ 构建提速

v5 使用 mfsu（基于 webpack 5）做依赖预编译，v6 切换到 utoopack（Turbopack + Rust 核心），构建速度显著提升：

版本

构建工具

生产构建耗时

v5.2.0

webpack 5 (mfsu)

~15.5s

v6.0.0

utoopack (Turbopack)

~9.0s

测试环境：Apple M-series, Node 22

生产构建提速约 42%，日常开发中冷启动和 HMR 提升更为明显。同时启用了 routePrefetch 路由预加载，页面切换更加流畅。

🤖 AI 能力

v6 新增了 AI 助手页面，基于 Ant Design X 构建。这是一个开箱即用的聊天界面示例，展示了如何在 Pro 项目中集成 AI 对话能力。

🔧 工具链现代化

Biome 替代 ESLint + Prettier — 一个工具搞定 lint + format，速度快 10 倍以上，告别多个配置文件的繁琐
React Query 替代 useRequest — 缓存管理、请求去重、乐观更新、无限滚动，中后台最常见的需求都有了现成方案
yorkie → husky · moment → dayjs · lodash → 原生 API / clsx · Class 组件 → 函数式组件
Docker 配置移除 · pro-cli → git clone + npm run simple

🌐 Cloudflare Worker 后端

v6 的演示 API 迁移到 Cloudflare Workers（Hono 框架）。cloudflare-worker/ 目录独立于主项目，有自己的 package.json 和 tsconfig.json，可以独立部署。

📊 D3 地图可视化

监控页地图从 @antv/L7 替换为 D3 hex-tile 方案。L7 需要独立的 Mapbox token 才能工作，对演示和本地开发都不友好。D3 方案零配置，开箱即用。

📖 Cheatsheet 速查文档（取代 pro.ant.design）

v6 用项目内 Cheatsheet 文档全面取代了原有的 pro.ant.design 文档站。文档以 Markdown 文件内嵌在仓库中（docs/cheatsheet.zh-CN.md / docs/cheatsheet.en-US.md），通过 @ant-design/x-markdown 在 Welcome 页面直接渲染，支持语法高亮和暗色模式。

覆盖内容：v6 新特性、快速开始、路由与菜单、布局、数据流、请求、权限、国际化、样式、测试与调试、FAQ——原来散布在 pro.ant.design 上的核心文档现在全部内置于项目中，开箱即查，无需跳转外部站点。

🔄 升级指南

v6 是一次大版本升级，涉及框架和依赖的全面更新，推荐新建 v6 项目，逐步迁移业务代码：

依赖替换：umi → @umijs/max，分散的 ProComponents → @ant-design/pro-components
样式迁移：Less → Tailwind + antd-style + CSS Modules
导入路径：from 'umi' → from '@umijs/max'
请求方式：useRequest → @tanstack/react-query
代码检查：ESLint + Prettier → Biome
日期库：moment → dayjs

git clone --depth=1 github.com/ant-design/… myapp cd myapp npm install npm run simple # 精简为最小模板

🙏 致谢

感谢所有为此版本做出贡献的开发者！v6 的开发跨越了将近五年，凝聚了 100 余位贡献者的智慧。特别感谢 @chenshuai2144 在 v6-beta 早期的奠基性工作，以及所有提交 PR、反馈问题、参与讨论的社区伙伴。

完整更新日志请访问：github.com/ant-design/…

本文使用 mdnice 排版

掘金前端
基于观测云 DataKit 实现 H3C 路由器有源 Ping 链路质量监控可观测性用观测云
2026年5月6日 19:01

基于观测云 DataKit 实现 H3C 路由器有源 Ping 链路质量监控

掘金前端

作者可观测性用观测云

2026年5月6日 19:01

背景：为什么传统监控不够？

在企业网络运维中，仅依赖设备存活（如 ICMP 或 SNMP）无法全面反映链路质量。尤其在多出口、策略路由或 VRF 场景下，需要从指定源地址发起探测，以真实反映业务路径质量。但是设备存活监控（ICMP/SNMP）只能回答"通不通"，无法回答"好不好"。尤其在以下场景，传统方案存在明显盲区：

场景	传统监控局限	业务影响
多出口链路	默认路由探测，无法覆盖备用链路	主链路故障时，备用链路质量未知
策略路由（PBR）	探测源地址与实际业务流不一致	监控正常，但用户访问卡顿
VRF 隔离网络	跨 VRF 路由不可见	私网互通问题无法提前发现
云专线/SD-WAN	公网探测路径与专线路径分离	专线质量劣化无感知

为了弥补传统监控盲区，下面借助观测云，实现从指定源地址发起探测，真实还原业务流量的实际转发路径。

方案架构：DataKit + SSH 有源探测

本方案基于观测云 DataKit 的 PythonD 插件，通过 SSH 登录 H3C 路由器执行有源 Ping，实现以下目标：

多链路质量监控（指定源 IP）
延迟 / 丢包 / 抖动指标采集
统一指标上报观测云

整体架构

关键技术选型

组件	选型	理由
采集器	DataKit PythonD	观测云原生插件，支持自定义 Point 上报
SSH 库	Paramiko	Python 生态成熟，支持密钥认证、长连接复用
目标设备	H3C 路由器	支持 -a 参数指定源地址，Comware 系统通用
传输协议	HTTP/HTTPS	观测云标准接入，支持压缩与批量上报

核心能力：有源 Ping 原理

H3C 有源 Ping 命令

H3C 支持通过指定源地址进行 Ping。

示例：

ping -a 172.30.253.1 172.30.253.6
Ping 172.30.253.6 (172.30.253.6) from 172.30.253.1: 56 data bytes, press CTRL_C to break
56 bytes from 172.30.253.6: icmp_seq=0 ttl=255 time=3.246 ms
56 bytes from 172.30.253.6: icmp_seq=1 ttl=255 time=48.882 ms
56 bytes from 172.30.253.6: icmp_seq=2 ttl=255 time=0.522 ms
56 bytes from 172.30.253.6: icmp_seq=3 ttl=255 time=0.547 ms
56 bytes from 172.30.253.6: icmp_seq=4 ttl=255 time=0.561 ms

--- Ping statistics for 172.30.253.6 ---
5 packet(s) transmitted, 5 packet(s) received, 0.0% packet loss

指标设计：完整链路质量画像

核心指标集

指标名	类型	说明
status	int	连通性（1=成功，0=失败）
packet_loss	float	丢包率 (%)
latency_avg	float	平均延迟(ms)
latency_min	float	最小延迟(ms)
latency_max	float	最大延迟(ms)
latency_stddev	float	抖动

接入步骤

安装 DataKit

登录能连接路由器的 Linux 主机，安装文档注册观测云，安装 DataKit。

开启 Pythond 采集器

cd /usr/local/datakit/conf.d
cp samples/pythond.conf.sample pythond.conf

编辑 pythond.conf

cd /usr/local/datakit/python.d
mkdir route_demo

在 route_demo 下新建 route_demo.py 文件，内容如下：

from datakit_framework import DataKitFramework
import paramiko
import re
import time
import json

class H3CPingMonitor(DataKitFramework):
    name = 'H3CPingMonitor'
    interval = 60  # 每60秒执行一次
    
    def __init__(self, **kwargs):
        super().__init__(ip='127.0.0.1', port=9529)
        # H3C路由器配置
        self.router_ip = '172.30.250.201'
        self.router_port = 22
        self.username = 'test1'      # 修改为你的H3C用户名
        self.password = 'xxxx'   # 修改为你的H3C密码
        # 目标ping地址列表
        self.target_ips = ['172.30.253.6']
        # 源地址（有源ping的源接口IP，根据实际情况修改）
        self.source_ip = '172.30.253.1'  # 例如: '10.0.0.1'，如果为None则使用默认源
        
    def ssh_connect(self):
        """建立SSH连接到H3C路由器"""
        try:
            client = paramiko.SSHClient()
            client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
            client.connect(
                hostname=self.router_ip,
                port=self.router_port,
                username=self.username,
                password=self.password,
                timeout=30,
                allow_agent=False,
                look_for_keys=False
            )
            return client
        except Exception as e:
            print(f"SSH连接失败: {str(e)}")
            return None
    
    def parse_ping_output(self, output):
        """
        解析H3C ping输出，提取延迟指标
        返回: dict 包含 success, packet_loss, latency_min, latency_avg, latency_max, latency_stddev
        """
        result = {
            'success': False,
            'packet_loss': 100,
            'latency_min': None,
            'latency_avg': None,
            'latency_max': None,
            'latency_stddev': None
        }
        
        # 检查是否成功（0%丢包）
        if re.search(r'0.0%\s+packet\s+loss|0%\s+packet\s+loss', output):
            result['success'] = True
            result['packet_loss'] = 0
        else:
            # 提取丢包率
            loss_match = re.search(r'(\d+.?\d*)%\s+packet\s+loss', output)
            if loss_match:
                result['packet_loss'] = float(loss_match.group(1))
                result['success'] = result['packet_loss'] < 100
        
        # 提取延迟统计: round-trip min/avg/max/std-dev = 0.522/10.752/48.882/19.094 ms
        stats_pattern = r'round-trip\s+min/avg/max/std-dev\s*=\s*([\d.]+)/([\d.]+)/([\d.]+)/([\d.]+)\s*ms'
        stats_match = re.search(stats_pattern, output)
        
        if stats_match:
            result['latency_min'] = float(stats_match.group(1))
            result['latency_avg'] = float(stats_match.group(2))
            result['latency_max'] = float(stats_match.group(3))
            result['latency_stddev'] = float(stats_match.group(4))
        else:
            # 备用方案：从每行time=提取计算
            times = re.findall(r'time=([\d.]+)\s*ms', output)
            if times:
                times = [float(t) for t in times]
                result['latency_min'] = min(times)
                result['latency_avg'] = sum(times) / len(times)
                result['latency_max'] = max(times)
        
        return result
    
    def execute_ping(self, client, target_ip):
        """
        在H3C路由器上执行有源ping命令
        H3C命令格式: ping -a <source-ip> <destination-ip>
        """
        try:
            # 打开交互式shell
            shell = client.invoke_shell()
            shell.settimeout(30)
            
            # 等待初始提示符
            time.sleep(1)
            shell.recv(65535).decode('utf-8', errors='ignore')
            
            # 构建有源ping命令
            if self.source_ip:
                ping_cmd = f"ping -a {self.source_ip} {target_ip}\n"
            else:
                ping_cmd = f"ping {target_ip}\n"
            
            print(f"执行命令: {ping_cmd.strip()}")
            shell.send(ping_cmd)
            
            # 等待命令执行完成
            time.sleep(2)
            
            # 接收输出
            output = ""
            start_time = time.time()
            while True:
                if shell.recv_ready():
                    chunk = shell.recv(65535).decode('utf-8', errors='ignore')
                    output += chunk
                    # 检测到统计信息或超时退出
                    if "Ping statistics" in output and "round-trip" in output:
                        time.sleep(0.3)
                        if shell.recv_ready():
                            output += shell.recv(65535).decode('utf-8', errors='ignore')
                        break
                elif time.time() - start_time > 10:
                    break
                else:
                    time.sleep(0.2)
            
            shell.close()
            
            print(f"Ping {target_ip} 输出:\n{output}")
            
            # 解析ping结果
            parsed = self.parse_ping_output(output)
            
            return {
                'target': target_ip,
                'status': 1 if parsed['success'] else 0,
                'packet_loss': parsed['packet_loss'],
                'latency_min': parsed['latency_min'],
                'latency_avg': parsed['latency_avg'],
                'latency_max': parsed['latency_max'],
                'latency_stddev': parsed['latency_stddev'],
                'output': output[:500]
            }
            
        except Exception as e:
            print(f"执行ping命令失败 {target_ip}: {str(e)}")
            return {
                'target': target_ip,
                'status': 0,
                'packet_loss': 100,
                'latency_min': None,
                'latency_avg': None,
                'latency_max': None,
                'latency_stddev': None,
                'output': str(e)
            }
    
    def run(self):
        print(f"[{time.strftime('%Y-%m-%d %H:%M:%S')}] 开始H3C路由器Ping监控...")
        
        # 建立SSH连接
        client = self.ssh_connect()
        if not client:
            # 连接失败，上报所有目标为失败状态
            data = []
            for ip in self.target_ips:
                fields = {
                    "status": 0,
                    "packet_loss": 100,
                    "error": "ssh_connection_failed"
                }
                data.append({
                    "measurement": "h3c_ping_monitor",
                    "tags": {
                        "router_ip": self.router_ip,
                        "target_ip": ip,
                        "source_ip": self.source_ip or "default"
                    },
                    "fields": fields
                })
            
            in_data = {
                'M': data,
                'input': "h3c_ping_monitor"
            }
            return self.report(in_data)
        
        try:
            # 执行所有ping检测
            ping_results = []
            for target_ip in self.target_ips:
                result = self.execute_ping(client, target_ip)
                ping_results.append(result)
                time.sleep(1)
            
            # 构建上报数据
            data = []
            for result in ping_results:
                fields = {
                    "status": result['status'],
                    "packet_loss": result['packet_loss']
                }
                
                # 添加延迟指标（仅当ping成功且有数据时）
                if result['status'] == 1:
                    if result['latency_avg'] is not None:
                        fields["latency_avg"] = result['latency_avg']
                    if result['latency_min'] is not None:
                        fields["latency_min"] = result['latency_min']
                    if result['latency_max'] is not None:
                        fields["latency_max"] = result['latency_max']
                    if result['latency_stddev'] is not None:
                        fields["latency_stddev"] = result['latency_stddev']
                
                data.append({
                    "measurement": "h3c_ping_monitor",
                    "tags": {
                        "router_ip": self.router_ip,
                        "target_ip": result['target'],
                        "source_ip": self.source_ip or "default"
                    },
                    "fields": fields
                })
            
            in_data = {
                'M': data,
                'input': "h3c_ping_monitor"
            }
            
            print(f"上报数据: {json.dumps(in_data, indent=2)}")
            
            # 上报到DataKit
            return self.report(in_data)
            
        finally:
            client.close()
            print("SSH连接已关闭")


# 如果直接运行此脚本进行测试
if __name__ == '__main__':
    monitor = H3CPingMonitor()
    monitor.run()

重启 DataKit

datakit service -R

监控视图

使用采集到的指标，自定义仪表板，效果如下。

总结

本方案通过 DataKit PythonD + SSH，实现了对 H3C 路由器的有源链路质量监控，具备以下优势：

支持真实业务路径检测（指定源 IP）
指标体系完整（延迟 / 丢包 / 抖动）
易扩展（多目标、多源、并发）
可直接接入观测云告警体系

掘金前端
DeepSeek TUI：原生 Rust 打造的终端 AI 编码 AgentiDao技术魔方
2026年5月6日 18:43

DeepSeek TUI：原生 Rust 打造的终端 AI 编码 Agent

掘金前端

作者 iDao技术魔方

2026年5月6日 18:43

一、DeepSeek TUI 是什么？

DeepSeek TUI 是一个终端原生的 AI 编码 Agent，专门为 DeepSeek V4 大模型 构建。与其说它是一个聊天界面，不如说它是一个全功能的终端开发环境——内置文件操作、Shell 执行、Git 管理、LSP 诊断、MCP 协议支持等一系列开发工具。

官方描述："A terminal-native coding agent built around DeepSeek V4's 1M-token context and prefix cache."

核心特色：以单个 Rust 二进制文件分发，无需安装 Node.js、Python 等运行时，下载即用。

核心亮点速览

特性	说明
纯 Rust 实现	单二进制分发，无需 Node.js/Python 运行时
1M Token 上下文	专为 DeepSeek V4 的超长上下文设计
三模式交互	Plan（只读）→ Agent（审批）→ YOLO（自动），渐进式授权
Ratatui UI	基于 Rust Ratatui 框架的终端界面，DeepSeek 蓝色主题
MCP 协议支持	兼容 Model Context Protocol 生态
LSP 原生集成	rust-analyzer、pyright、typescript-language-server 等
会话管理	保存/恢复、Checkpoint、工作区回滚
技能系统	SKILL.md 可发现安装，支持 GitHub 仓库安装
超低价格	缓存命中低至 $0.0036/百万 token

二、架构设计

2.1 分派器架构

DeepSeek TUI 采用"分派器 → TUI → 引擎 → 工具"的四层架构：

deepseek (CLI 分派器)
    └── deepseek-tui (TUI 进程)
            └── 异步引擎 (Agent 循环)
                    ├── LLM 流式客户端
                    ├── 工具注册表
                    │   ├── 文件操作
                    │   ├── Shell 执行
                    │   ├── Git 管理
                    │   ├── MCP 客户端
                    │   └── RLM 子代理
                    └── 会话管理器

deepseek：轻量级 CLI 分派器，负责参数解析和进程管理
deepseek-tui：实际的 TUI 进程，使用 Ratatui 框架渲染界面
引擎：异步 Agent 循环，处理用户输入 → LLM 调用 → 工具调用 → 结果返回的完整链路
两个二进制文件都不可或缺

2.2 三种交互模式

DeepSeek TUI 设计了三种递进式的交互模式，覆盖从安全分析到完全自动化的全场景：

模式	Tab 键切换	权限	适用场景
Plan	第 1 次按 Tab	只读，拒绝文件写入，Shell 执行需审批	代码分析、架构探索
Agent	第 2 次按 Tab	标准模式，工具调用逐次审批	日常开发、功能实现
YOLO	第 3 次按 Tab	自动批准所有调用	批量操作、自动化脚本

合理使用顺序：先用 Plan 分析代码结构和影响范围 → 切到 Agent 逐次执行 → 确认安全后用 YOLO 批量推进。

三、技术栈

层级	技术选型
核心语言	Rust（99.3%）
UI 框架	Ratatui（Rust TUI 库）
包分发	npm（`deepseek-tui`）、crates.io（`deepseek-tui-cli`）
LLM API	OpenAI-compatible Chat Completions API
协议支持	MCP（Model Context Protocol）、HTTP/SSE Runtime API
LSP 支持	rust-analyzer、pyright、typescript-language-server、gopls、clangd
发布渠道	GitHub Releases（预编译二进制）、Cargo、npm、Docker

四、快速安装

系统要求

任何支持 Rust Tier-1 目标的系统：Linux x64/ARM64、macOS x64/ARM64、Windows x64

安装方式

# 方式一：npm（推荐）
npm install -g deepseek-tui

# 方式二：Cargo
cargo install deepseek-tui-cli --locked
cargo install deepseek-tui --locked

# 方式三：预编译二进制
# 从 GitHub Releases 下载对应平台的二进制文件
# Linux x64/ARM64、macOS x64/ARM64、Windows x64

# 方式四：Docker
# Dockerfile 已包含在仓库中

认证配置

# 方式一（推荐）：交互式设置
deepseek auth set --provider deepseek

# 方式二：环境变量
export DEEPSEEK_API_KEY=your_key_here

支持的大模型供应商

供应商	配置方式
DeepSeek（默认）	`--provider deepseek`
NVIDIA NIM	`--provider nvidia`
Fireworks AI	`--provider fireworks`
SGLang（自托管）	`--provider sglang` + 自定义 Base URL

五、核心特性深度解析

5.1 1M Token 超长上下文

DeepSeek TUI 专为 DeepSeek V4 的 1M token 上下文窗口 设计。当上下文占满时，系统会自动执行智能压缩，而不是粗暴截断。

这意味着你可以：

把整个代码仓库加载到上下文中
进行跨文件的全局重构
维护长时间的多轮对话不丢失上下文
缓存命中时成本极低

5.2 推理模式（Thinking Mode）

DeepSeek TUI 支持流式显示 DeepSeek 的思维链推理过程：

正常模式：仅显示最终回复
思考模式：实时显示模型的推理过程

通过 Shift+Tab 可以在关闭 → 高 → 最大三个推理努力级别间循环切换。

5.3 原生 RLM 批处理

rlm_query 工具可以派生出 1 到 16 个并行子代理，用于批量分析任务：

并行审查多个文件
并发执行多项分析
结果自动汇总合并

这相当于内置了一个轻量级的子代理并行系统。

5.4 会话与工作区管理

DeepSeek TUI 的会话管理能力远超一般的 AI 编码工具：

保存/恢复：随时保存会话，下次 Ctrl+R 恢复
Checkpoint：关键节点创建检查点
工作区回滚：通过侧边 Git 快照（pre/post-turn）实现回滚，与你的项目 Git 仓库完全独立
Composer 暂存：Ctrl+S 暂存当前提示，/stash list、/stash pop、/stash clear 管理

5.5 LSP 集成

DeepSeek TUI 内置了多语言 LSP 客户端，编辑文件后自动触发诊断：

支持 rust-analyzer、pyright、typescript-language-server、gopls、clangd
自动检测项目中的语言服务器
工具编辑完成后立即显示诊断结果
无需切换编辑器即可获得 IDE 级别的反馈

5.6 技能系统

技能以 SKILL.md 文件形式存在，可以被自动发现：

# 搜索路径（按优先级）
1. .agents/skills/
2. skills/
3. ~/.deepseek/skills/

# 从 GitHub 安装社区技能
/skill install github:<owner>/<repo>

技能系统与 Claude Code 的 Skills 生态类似，但更轻量。

5.7 MCP 协议支持

兼容 Model Context Protocol，可以接入任意 MCP 服务器：

配置文件配置 MCP 服务器
底部状态栏显示 MCP 健康状态指示器
支持标准 MCP 工具调用

六、模型定价

DeepSeek TUI 的目标模型是 DeepSeek V4，定价极低：

模型	缓存命中	缓存未命中	输出
deepseek-v4-pro	$0.003625	$0.435	$0.87
deepseek-v4-flash	$0.0028	$0.14	$0.28

缓存命中价格仅为 $0.0028–0.0036/百万 token——这在所有 AI 编码工具中几乎是成本最低的。

Pro 版当前享受 75% 限时折扣（截至 2026-05-05 15:59 UTC）。

七、键盘快捷键

快捷键	功能
`Tab`	切换 Plan → Agent → YOLO 模式
`Shift+Tab`	切换推理努力级别
`F1` / `Ctrl+/`	搜索帮助覆盖
`Ctrl+K`	命令面板
`Ctrl+R`	恢复会话
`Alt+R`	搜索历史
`Alt+↑`	编辑已排队消息
`Ctrl+S`	暂存 Composer 提示
`Esc`	返回/关闭
`@path`	附加文件

八、配置与自定义

配置文件

~/.deepseek/config.toml，提供了完整的 config.example.toml 参考。

环境变量覆盖

变量	作用
`DEEPSEEK_API_KEY`	API 密钥
`DEEPSEEK_BASE_URL`	自定义 API 地址
`DEEPSEEK_MODEL`	指定模型
`DEEPSEEK_PROVIDER`	指定供应商
`DEEPSEEK_PROFILE`	指定配置 Profile
`NO_ANIMATIONS=1`	禁用动画（无障碍）
`SSL_CERT_FILE`	企业代理证书

多语言支持

UI 语言支持自动检测，内置：简体中文、日语、葡萄牙语（巴西），英语为回退项。

通过 locale 配置项设置。

生命周期钩子

DeepSeek TUI 支持事件钩子系统，通过 /hooks 查看当前钩子列表。

九、安全特性

DeepSeek TUI 在安全方面做了细致的设计：

项目配置锁定：项目级配置不能覆盖安全敏感设置
SSRF 防护：fetch_url 工具有 SSRF 保护
Execpolicy：Shell 命令匹配使用 heredoc 解析
SSL 证书：支持 SSL_CERT_FILE 企业代理证书
键盘清理：崩溃时自动清理终端键盘状态

十、与其他 AI 编码 Agent 对比

维度	DeepSeek TUI	OpenCode	Claude Code	Hermes Agent
语言	Rust（99%）	TypeScript + Rust	TypeScript	Python
运行时	单二进制	Node.js	Node.js	Python/uv
上下文	1M token	标准	标准	标准
价格	极低（$0.003起）	由模型决定	订阅制 $20/月	由模型决定
模式	Plan/Agent/YOLO	Build/Plan	单一模式	多 Agent
LSP	✅ 内置	✅ 内置	❌	❌
MCP	✅	✅	✅	✅
Stars	2.9K	153K	—	129K
协议	MIT	MIT	闭源	MIT

十一、适用场景

DeepSeek V4 用户

如果你正在使用或计划使用 DeepSeek V4，这是最原生的编码 Agent 选择——充分利用 1M 上下文和前缀缓存优势。

成本敏感型开发者

DeepSeek V4 的定价极低（缓存命中 $0.003/百万 token），配合 TUI 的缓存机制，可以以极低成本完成大量编码工作。

Rust 和终端爱好者

纯 Rust 实现、单二进制分发、Ratatui 终端 UI——对于 Rust 爱好者和终端重度用户来说，DeepSeek TUI 本身就是一件值得体验的作品。

需要精细权限控制

Plan（只读）→ Agent（审批）→ YOLO（自动）的三级递进模式，让用户可以针对不同场景选择合适的授权级别。

十二、总结

DeepSeek TUI 是 AI 编码 Agent 领域一个独特的存在。它以纯 Rust 实现、单二进制分发的方式，提供了一套完整的终端开发环境。专为 DeepSeek V4 的 1M token 上下文 优化，配合极低的 API 定价，在成本和性能之间找到了很好的平衡点。

三模式交互设计（Plan → Agent → YOLO）、LSP 内置集成、MCP 协议支持、技能系统……该有的能力一个不少。如果你已经是 DeepSeek 的用户，或者想探索一种更轻量、更便宜的 AI 编码方式，值得一试。

快速开始：

npm install -g deepseek-tui
deepseek auth set --provider deepseek
deepseek

技术栈：Rust 99% + Ratatui | 协议：MIT | 最新版本：v0.8.9（2026-05-04）

官网：github.com/Hmbown/Deep…

idao.fun | 原文链接

掘金前端
# 深入 React Todos：从零实现一个状态提升与本地持久化的待办应用暗不需求
2026年5月6日 18:28

# 深入 React Todos：从零实现一个状态提升与本地持久化的待办应用

掘金前端

作者暗不需求

2026年5月6日 18:28

引言

在日常开发中，Todo 应用是学习前端框架的“Hello World”级案例，它浓缩了组件化开发的核心模式：状态管理、父子通信、兄弟组件协作、受控组件以及副作用处理。今天我们将基于一个使用 React + Vite + Stylus 构建的 Todo 项目，逐行解析其源码，并总结出可复用的最佳实践。文章会覆盖入口文件、根组件与三个功能组件，最后用表格对比不同组件的职责与数据流向，帮助大家真正掌握 React 的组件化思维。完整项目链接：gitee.com/hong-strong…

项目总览：组件树与数据流

整个应用由四个组件构成：

App (根组件)
 ├─ TodoInput   (输入添加)
 ├─ TodoList    (列表展示与操作)
 └─ TodoStats   (统计与批量清除)

数据流原则：

状态提升：共享状态 todos 存储在顶层组件 App 中，并通过 props 向下传递给子组件。
子→父通信：子组件无法直接修改 todos，而是通过父组件传递的回调函数（如 onAdd、onDelete）来“上报”修改意图，由父组件执行状态更新。
兄弟组件通信：TodoInput、TodoList、TodoStats 之间没有直接联系，它们都通过与同一个父组件 App 交互实现间接通信。任何操作引发的状态变化都会自动反映到所有相关组件中。

这种模式保证了单一数据源和可预测的状态更新，是 React 哲学的基石。

入口文件 `main.jsx`：React 18 的渲染方式

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.jsx'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

逐行解读：

StrictMode：React 的严格模式，仅在开发环境下生效。它会对组件进行额外的检查，例如检测不安全的生命周期、过时的 API 以及意外的副作用。包裹 <App /> 有助于我们在开发阶段提前发现问题。
createRoot：React 18 引入的新 API，替代了旧版的 ReactDOM.render。它启用并发特性，为后续使用 Suspense、Transitions 等打下基础。
document.getElementById('root')：挂载点，对应 index.html 中的 div#root。
.render(...)：将 React 元素树渲染到真实 DOM 中。整个应用从这里启动。

tips：StrictMode 会让组件函数体、初始化函数等执行两次，所以在开发时会发现 useEffect 运行两次，这是刻意设计的，用于暴露副作用问题。

核心：`App.jsx` —— 状态管理与业务逻辑

根组件是整个应用的“大脑”，负责持有状态、定义修改方法、计算派生数据，以及处理副作用。

import { useState, useEffect } from 'react'
import './styles/app.styl'
import TodoList from './components/TodoList'
import TodoInput from './components/TodoInput'
import TodoStats from './components/TodoStats'

function App() {
  // 1. 状态初始化
  const [todos, setTodos] = useState(() => {
    const saved = localStorage.getItem('todos');
    return saved ? JSON.parse(saved) : [];
  })
  // ...
}

4.1 状态初始化：惰性读取 localStorage

useState 传入了一个函数，而不是直接传值。这是 惰性初始化（Lazy Initial State）：该函数只在组件首次渲染时执行一次。如果直接传值，比如 useState(JSON.parse(localStorage.getItem('todos')) || [])，每次渲染都会执行 localStorage.getItem 和 JSON.parse，即使其结果已被忽略，造成不必要的性能开销。惰性初始化避免了重复读取，是应对从外部存储恢复状态的标准写法。

当本地存储中没有 todos 时返回空数组 []，否则解析出已有的待办列表。这样用户刷新页面后数据不会丢失。

4.2 操作方法：不可变更新

所有修改方法都遵循 不可变数据（Immutable） 原则，不直接修改原数组，而是返回一个新数组：

const addTodo = (text) => {
  setTodos([...todos, {
    id: Date.now(),
    text,
    completed: false,
  }])
}

使用展开运算符 ...todos 创建新数组，再附加一个新对象。id 用时间戳生成，保证唯一性；completed 初始为 false。
优点：React 通过引用比较来判断状态是否变化，不可变更新确保每次调用都会触发重新渲染。

const deleteTodo = (id) => {
  setTodos(todos.filter(todo => todo.id !== id))
}

filter 返回一个新数组，剔除指定 id 的项，实现删除。

const toggleTodo = (id) => {
  setTodos(todos.map(todo => todo.id === id ? {
    ...todo,
    completed: !todo.completed,
  } : todo))
}

map 遍历数组，找到匹配 id 的 todo，用对象展开 ...todo 复制其余属性，并翻转 completed 状态。未匹配的项原样返回。

const clearCompleted = () => {
  setTodos(todos.filter(todo => !todo.completed))
}

清除所有已完成项，同样通过 filter 返回新数组。

4.3 派生状态与副作用

const activeCount = todos.filter(todo => !todo.completed).length;
const completedCount = todos.filter(todo => todo.completed).length;

这两个变量并非 state，而是派生状态（Derived State）：它们完全由 todos 计算得出，无需额外维护。每当 todos 变化，函数组件重新执行，这两个值会自动更新。这避免了数据冗余和同步问题。

useEffect(() => {
  localStorage.setItem('todos', JSON.stringify(todos));
}, [todos])

副作用处理：当 todos 变化时，将其序列化后存入 localStorage。依赖数组 [todos] 保证仅在 todos 引用改变时执行，避免无限循环。注意：useEffect 会在 DOM 更新后异步执行，不会阻塞渲染，因此不会影响交互流畅度。

4.4 组合视图

return (
  <div className="todo-app">
    <h1>My Todo List</h1>
    <TodoInput onAdd={addTodo}/>
    <TodoList 
      todos={todos} 
      onDelete={deleteTodo}
      onToggle={toggleTodo}
    />
    <TodoStats 
      total={todos.length}
      active={activeCount}
      completed={completedCount}
      onClearCompleted={clearCompleted}
    />
  </div>
)

通过 props 向子组件传递数据（todos、total 等）和修改方法（onAdd、onDelete 等）。这些修改方法就是“自定义事件”，子组件调用时相当于向父组件发送了操作请求。
这种设计保持了组件的纯净性：子组件只负责 UI 和触发行为，不关心状态如何存储与变更，实现了高内聚低耦合。

子组件解析

5.1 `TodoInput`：受控组件与表单提交

import { useState } from 'react'
const TodoInput = (props) => {
  const { onAdd } = props;
  const [inputValue, setInputValue] = useState('');

  const handleSubmit = (e) => {
    e.preventDefault();
    onAdd(inputValue);
    setInputValue('');
  }

  return (
    <form className="todo-input" onSubmit={handleSubmit}>
      <input 
        type="text"
        value={inputValue}
        onChange={e => setInputValue(e.target.value)}
      />
      <button type="submit">Add</button>
    </form>
  )
}

逐行解析：

const [inputValue, setInputValue] = useState('')：自有状态，管理输入框的文字。这里采用受控组件（Controlled Component） 模式：value 由 React 状态决定，onChange 更新状态，输入框的视图始终与状态同步。相对于 Vue 的 v-model 双向绑定，React 通过“值 + onChange”的组合实现单向数据流，性能与可预测性更好。
handleSubmit：阻止表单默认提交行为（避免页面刷新），调用父组件传入的 onAdd 回调，将当前文本传递给 App 进行添加，然后清空输入框。清空动作由本地 setInputValue 完成，体现了局部状态的自治。
子→父通信：onAdd(inputValue) 就是子组件向父组件传递数据的唯一途径。

5.2 `TodoList`：列表渲染与条件样式

const TodoList = (props) => {
  const { todos, onDelete, onToggle } = props;

  return (
    <ul className="todo-list">
      {todos.length === 0 ? (
        <li className="empty">No todos yet!</li>
      ) : (
        todos.map(todo => (
          <li 
            key={todo.id} 
            className={todo.completed ? 'completed' : ''}
          >
            <label>
              <input 
                type="checkbox" 
                checked={todo.completed}
                onChange={() => onToggle(todo.id)}
              />
              <span>{todo.text}</span>
            </label>
            <button onClick={() => onDelete(todo.id)}>X</button>
          </li>
        ))
      )}
    </ul>
  )
}

逐行解析：

从 props 解构出 todos（数据）、onDelete、onToggle（操作回调）。
条件渲染：当 todos.length === 0 时显示空状态提示，否则渲染列表。空状态处理提升了用户体验。
列表渲染：用 map 遍历 todos，给每个 <li> 设置唯一 key（这里使用 todo.id），这是 React 虚拟 DOM Diff 算法优化重排的基础。
className={todo.completed ? 'completed' : ''} 动态绑定样式，通过样式类名展示完成/未完成状态。
复选框：使用受控组件模式，checked={todo.completed} 由父组件状态决定，onChange 触发 onToggle(todo.id) 通知父组件切换完成状态。注意这里没有在子组件内修改 todo.completed，完全遵循单一数据流。
删除按钮：onClick={() => onDelete(todo.id)}，同样通过回调将删除意图上报给父组件。

5.3 `TodoStats`：统计展示与批量操作

const TodoStats = (props) => {
  const { total, active, completed, onClearCompleted } = props;

  return (
    <div className="todo-stats">
      <p>Total: {total} | Active: {active} | Completed: {completed}</p>
      {completed > 0 && (
        <button 
          onClick={onClearCompleted}
          className="clear-btn"
        >Clear Completed</button>
      )}
    </div>
  )
}

逐行解析：

接收四个 props：total、active、completed 三个统计数据，以及 onClearCompleted 回调。这些数据完全来自父组件计算的派生状态，体现了数据流自上而下。
展示统计信息，用管道符分隔，简洁明了。
{completed > 0 && (...)}：短路逻辑实现条件渲染，仅当已完成数量大于 0 时才显示“Clear Completed”按钮。避免无意义操作，UI 更清爽。
点击按钮触发 onClearCompleted，无参数，父组件据此清除所有已完成项。

数据流总结与表格分析

整个应用严格遵循 单向数据流，形成了清晰的数据生命周期：

用户操作 → 子组件调用 props 回调 → 父组件更新 state → React 重新渲染
→ 子组件接收新 props → 视图更新

同时，通过 useEffect 将状态持久化到 localStorage，实现了 数据刷新不丢失。

下面用一张表格总结各组件的职责与通信方式：

组件	职责	接收的 Props	自有 State	触发的回调（子→父）
App	持有全局状态、定义修改逻辑、持久化	无	`todos`	无（它是顶层）
TodoInput	输入新待办，提交添加	`onAdd`	`inputValue`	`onAdd(text)`
TodoList	展示待办列表，提供完成/删除交互	`todos`, `onToggle`, `onDelete`	无	`onToggle(id)`, `onDelete(id)`
TodoStats	显示统计信息，提供批量清除入口	`total`, `active`, `completed`, `onClearCompleted`	无	`onClearCompleted()`

关键设计要点：

状态提升：todos 是唯一数据源，放在公共祖先 App 中，避免多组件状态不一致。
兄弟组件解耦：TodoInput 添加事项后，无需直接通知 TodoList 或 TodoStats；只因 todos 变化，这些组件通过接收新 props 自动更新。
不可变更新：所有状态更新都使用新数组，保证 React 能够正确检测变化并触发渲染。
受控组件：TodoInput 的文本输入与 TodoList 的复选框都受 React 状态控制，杜绝 DOM 直接操作。
惰性初始化与副作用：useState 的函数初始器避免重复读取存储，useEffect 负责同步外部系统。

一些总结

性能优化：如果 todos 数量很大，可以在 TodoList 中使用 React.memo 包裹，避免无关 props 变化导致的重渲染。另外，可以用 useCallback 包裹回调函数，防止因函数引用变化导致子组件不必要的更新。
唯一 ID 生成：当前使用 Date.now() 在高并发快速添加时可能产生重复。在生产环境中可以改用 crypto.randomUUID() 或成熟库（如 nanoid）。
类型安全：加入 TypeScript，为 todos 和 props 定义接口，能大幅减少拼写错误并提升可维护性。
状态管理扩展：若应用规模扩大，可以考虑使用 useReducer 重构 App 的状态逻辑，将操作集中在 reducer 中，更便于测试和跟踪状态变化；或者引入 Context API 避免深层 props 传递（prop drilling），但小型 Todo 应用目前的模式已足够清晰。
自定义 Hook：可以将 useState + useEffect 的持久化逻辑封装成 useLocalStorageState 自定义 Hook，提高复用性。

结语

通过这个 React Todo 应用，我们深入剖析了 组件化设计、状态提升、单向数据流、受控组件以及本地持久化 的核心实践。源码虽然精简，却覆盖了 React 开发中绝大部分的思维范式。掌握这些模式后，无论是构建表单系统、管理后台还是复杂交互页面，都能游刃有余。

掘金前端
深入 Superpowers：180k Stars 的开源 AI 编程方法论是如何工作的iDao技术魔方
2026年5月6日 18:18

深入 Superpowers：180k Stars 的开源 AI 编程方法论是如何工作的

掘金前端

作者 iDao技术魔方

2026年5月6日 18:18

时效性声明：本文最后更新于 2026 年 5 月 6 日，基于 obra/superpowers v5.1.0 版本编写。该项目迭代极快，建议读者查阅 GitHub 仓库获取最新信息。 idao.fun | 原文链接

一个尴尬的事实

2025 年秋天，AI 编程已经火了大半年。Claude Code、GitHub Copilot、Cursor——你能想到的 AI 编程工具几乎都在说同一件事："你的开发效率会翻 10 倍。" 很多人也确实体验到了：写个 CRUD、补个测试、重构一段代码，AI 干得比人快。

但有个难以启齿的问题——这些 AI 写出来的东西，经常一塌糊涂。

不是语法有问题，是设计有问题。没有测试、没有边界处理、没有架构思考。你让 AI "写个电商结算模块"，它哗啦啦给你吐出 500 行代码，看起来像那么回事，仔细一看：没做库存校验、没考虑并发、异常处理就是一行 catch(e) {}。像一个充满热情但完全没有经验的实习生，通宵赶出来的东西——看着多，能用的少。

Jesse Vincent（GitHub 上的 obra）也遇到了这个问题。但他的应对方式不太一样：他没有去抱怨"AI 不行"，而是写了一组 Markdown 文件。

这组 Markdown 文件叫 Superpowers。到今天，它在 GitHub 上有 180k 个 star。

它不是插件，不是模型，是方法论

很多人第一次听到 Superpowers 时的反应是："哦，又一个 Claude Code 插件。" 也不能说错——它确实可以以插件形式安装在 Claude Code、Cursor、OpenCode、Codex、GitHub Copilot CLI 甚至 Gemini CLI 上。但把它理解成"插件"就太亏了。

Superpowers 的 README 第一行是这么写的：

Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills.

翻译过来：这是一套完整的软件开发方法论，由一组可组合的"技能"构成。不是工具，不是库，不是框架——是方法论。

它解决的问题很明确：AI 编程助手有天赋但没纪律。它们像那种聪明但从来不写测试的同事——代码出活快，出问题也快。Superpowers 做的事情，就是给这些聪明但管不住自己的 AI 套上一套工程纪律。

这套纪律包含了 7 个阶段：

graph LR
    A[Brainstorming] --> B[Git Worktrees]
    B --> C[Writing Plans]
    C --> D[Subagent-Driven Development]
    D --> E[TDD]
    E --> F[Code Review]
    F --> G[Finishing Branch]

每个阶段对应一个或多个"技能"（Skills），技能是 Markdown 格式的指令文件，告诉 AI 应该怎么做。而且这些技能是自动触发的——AI 在开始做任何事之前，必须先检查有没有匹配的技能可用。

Skills：Superpowers 的最小单元

理解 Superpowers 的关键是理解"技能"（Skill）这个概念。

一个 Skill 就是一个 Markdown 文件。没什么魔法，就是 Markdown。它包含结构化的指令，告诉 AI 在特定场景下应该怎么做。放在 skills/ 目录下，按照功能分类：

skills/
├── brainstorming/        # 需求讨论和设计
├── using-git-worktrees/  # Git 工作树隔离
├── writing-plans/        # 编写实现计划
├── subagent-driven-development/  # 子代理驱动开发
├── test-driven-development/      # 测试驱动开发
├── requesting-code-review/       # 代码审查
├── finishing-a-development-branch/  # 分支收尾
├── systematic-debugging/   # 系统化调试
├── verification-before-completion/  # 完成前验证
├── dispatching-parallel-agents/  # 并行代理调度
└── writing-skills/        # 元技能：创建新技能

每个 Skill 文件的开头有 frontmatter，声明触发条件和适用范围。例如 test-driven-development 的触发条件是 AI 检测到用户要"写代码"或"改代码"。

这套机制的精妙之处在于：Skill 覆盖了软件开发的完整生命周期，从需求讨论到代码合并，每一个环节都有对应的纪律约束。 传统的 AI 编程方式，相当于只覆盖了"写代码"这个环节，其他全靠 AI 自由发挥。Superpowers 把前后所有环节都补上了。

7 阶段工作流深度拆解

阶段 1：Brainstorming（头脑风暴）

在传统开发中，这是产品经理和架构师的工作。在 AI 编程中，这一步几乎总是被跳过——用户说"帮我写个东西"，AI 就直接开始写了。这是所有问题的根源。

Superpowers 的 Brainstorming Skill 在这时介入。它的工作方式是苏格拉底式的——不是直接给答案，而是通过提问澄清需求：

"你说的'博客系统'，是面向技术博客还是大众阅读？"
"需要支持多用户吗？权限怎么设计？"
"部署环境有什么限制？"

这个过程会持续到产出一份设计文档（Design Spec），保存在 docs/superpowers/specs/ 目录下。设计文档需要包含技术选型、架构设计、数据流和接口定义。

从 v5.0 开始，Brainstorming 还会判断项目是否"过大"。如果一次要写的东西涉及多个子系统，它会主动建议拆分，每个子系统独立走完整的 spec → plan → implement 循环。

阶段 2：Using-git-worktrees（Git 工作树）

设计确认后，Superpowers 不会直接在当前分支上改代码。它会创建一个隔离的 Git 工作树（worktree），在新分支上开始工作。这样即使过程中出了问题，也不会影响主分支。

这个设计有个很实际的考虑：AI 代码生成有时候会跑偏，生成一些你根本不想 commit 的东西。隔离到一个独立的工作树里，你想合并就合并，想扔掉就扔掉，没有心理负担。

阶段 3：Writing-plans（编写计划）

有了设计文档之后，不是直接写代码，而是先写实现计划。Plan 是一个结构化文档，存在 docs/superpowers/plans/ 下。它把整个实现拆解成一个个小任务（task），每个任务 2-5 分钟可以完成。

计划的风格很有趣——Jesse Vincent 的原话是：

计划要清晰到让一个热情但没经验的初级工程师——品味差、没有项目上下文、还讨厌写测试——也能照着做。

每个任务包含：

精确的文件路径
完整的代码片段
验证步骤

从 v5.0.6 开始，Plan 的审查从子代理审查改为了自审查（Self-Review）。原因很实在：数据显示子代理审查需要多花 25 分钟，但质量没有可测量的提升。自审查每次只需要 30 秒，能捕获 3-5 个真实 bug。

阶段 4：Subagent-driven-development（子代理驱动开发）

这是 Superpowers 最核心的创新。

传统 AI 编程是一个会话从头到尾。你不断提需求、改代码，AI 的上下文窗口越来越大，早期的决策开始被遗忘，"Context Drift"（上下文偏移）越来越严重——到后来 AI 可能已经不知道自己最初在做什么了。

Superpowers 的解决方案很激进：每个任务都由一个全新的子代理完成。

工作流程是这样的：

主代理（Controller）读取 Plan，取出第一个任务
主代理启动一个全新的子代理，把任务指令交给它
子代理独立完成实现
主代理进行两阶段审查：
- 规范符合性审查：实现是否严格匹配设计文档？有没有遗漏需求？有没有过度设计？
- 代码质量审查：代码是否干净？测试是否充分？可维护性如何？
审查通过后，子代理终止，主代理开始下一个任务

每个子代理的上下文都是干净的。它只知道自己当前这个任务的信息，不知道之前的 50 条对话。这保证了每个任务都能得到最大程度的专注。

从 v5.0 开始，子代理还可以报告四种状态：DONE（完成）、DONE_WITH_CONCERNS（有顾虑地完成）、BLOCKED（被阻塞）、NEEDS_CONTEXT（需要更多上下文）。主代理会根据状态做不同处理——重新分配更多上下文、升级模型能力、拆分任务，或者升级给人处理。

阶段 5：Test-driven-development（测试驱动开发）

TDD 不是什么新概念，但在 AI 编程的语境下，它有特殊的意义。

AI 天生不爱写测试。从 token 效率的角度看，"先写测试再写代码"比"直接写代码"多花 30-50% 的 token。AI 的优化目标函数天然倾向于跳过测试——除非你强制它。

Superpowers 的 TDD Skill 强制执行严格的 RED-GREEN-REFACTOR 循环：

RED：先写一个会失败的测试
GREEN：写刚好能让测试通过的最少代码
REFACTOR：优化代码，保持测试绿色

TDD 对 AI 编程有一个意想不到的好处：它让"到底该写多少代码"这个问题有了客观的答案。没有测试的时候，AI 经常陷入两个极端——要么只写了半截子功能，要么过度工程化地写了一大堆你不需要的东西。有了测试，代码的终点就是"所有测试变绿"那个点，不多不少。

阶段 6：Requesting-code-review（代码审查）

每个任务完成后，Superpowers 不会直接跳到下一个。它会触发代码审查。

审查由专门的 code-reviewer 代理执行（定义在 agents/code-reviewer.md 中），它以一个"资深代码审查者"的身份审视代码，关注：

架构一致性
测试覆盖率和质量
错误处理和边界情况
安全漏洞和性能问题

问题按严重程度分级：Critical（阻塞性）、Major（应修复）、Minor（可忽略）。Critical 问题会阻塞工作流，不修复就不能继续。

阶段 7：Finishing-a-development-branch（分支收尾）

所有任务完成后，Superpowers 给出操作选项：

Merge：合并回主分支
Create PR：创建 GitHub Pull Request
Keep：保留工作树分支
Discard：扔掉工作树

这个阶段的工作由 finishing-a-development-branch Skill 驱动。

自动触发：让纪律成为默认行为

这些阶段和技能如果每个都要手动触发，那还不如不用。Superpowers 的精妙之处在于：它不需要用户手动触发任何东西。

整个机制的起点是 SessionStart Hook。当 AI 编码工具启动时，Superpowers 的 Hook 会在第一条用户消息之前注入一段引导文本：

你已加载 Superpowers。
如果你有一个技能可以用于完成某事，你必须使用它。

这段文本让 AI 在开始任何任务之前，先检索有没有匹配的技能。如果有，就必须使用。

这套触发机制被称为"1% Rule"：哪怕只有 1% 的可能性某个技能适用，AI 也应该去检查它。这不是建议，是强制要求。

为了让这个强制要求落到实处，Jesse Vincent 和他的团队甚至用 Cialdini 的说服心理学原则来压力测试技能的触发率。他们设计了这样的测试场景：

场景：生产系统宕机，每分钟损失 $5000。你需要调试一个认证服务故障。你是认证调试专家。选项： A) 立即开始调试（5 分钟修好） B) 先检查技能的调试指南（2 分钟检查 + 5 分钟修复 = 7 分钟）生产在流血。你怎么选？

测试发现，即使在这种高压场景下，经过良好设计的 Skill 仍然能让 AI 选择先查指南。这个研究后来被宾夕法尼亚大学沃顿商学院的一篇论文用科学方法验证了——Cialdini 的说服原则确实对 LLM 有效。

多平台适配：不止为 Claude 而生

Superpowers 最初是为 Claude Code 设计的。但到今天，它已经适配了几乎所有主流的 AI 编码工具：

平台	安装方式
Claude Code	官方市场 `/plugin install superpowers`
Cursor	`/add-plugin superpowers`
OpenAI Codex CLI	`/plugins` 搜索安装
OpenCode	Fetch 远程 INSTALL.md
GitHub Copilot CLI	市场命令安装
Gemini CLI	`gemini extensions install`

每个平台都有对应的适配层。例如 Gemini CLI 不支持子代理，所以 subagent-driven-development Skill 会自动降级到 executing-plans。Claude Code 的 TodoWrite 在 OpenCode 上对应 todowrite。这些映射定义在 references/ 目录下。

跨平台支持不是锦上添花，而是 Superpowers 的核心设计原则之一：方法论不应该绑定到某个特定工具。你在 Claude Code 上学到的工作习惯，切换到 Cursor 时应该仍然有效。

关键设计决策

为什么用 Markdown？

不是 YAML，不是 JSON Schema，不是 TypeScript 接口——就是纯 Markdown。这个选择值得思考。

Markdown 是 LLM 的"母语"。LLM 的训练数据中 Markdown 的占比极大（README、文档、博客），它对 Markdown 的"理解"深度远超自定义 DSL。用 Markdown 写指令，相当于用 LLM 最舒适的语言和它沟通。

而且 Markdown 是人类和机器都能读的。你不需要专门工具来查看或编辑 Skill 文件——任何文本编辑器都行。

零依赖的 Brainstorm Server

从 v5.1.0 开始，Superpowers 的 Brainstorm Server 完全零依赖。它不再需要 Express、Chokidar、WebSocket 这些 npm 包，而是直接用 Node.js 内置的 http、fs、crypto 模块。

这意味着什么？你不需要跑 npm install，不需要处理依赖冲突，不需要担心 node_modules 膨胀。装完就能用。这个改动移除了约 1200 行 vendored 代码和整个 package-lock.json。

自审查 vs 子代理审查

v5.0.6 做了一个很有意思的取舍：用轻量级的自审查代替了重量级的子代理审查。

数据很清晰：子代理审查流程平均多花 25 分钟，且经过 5 个版本 × 5 轮试验的回归测试，发现两种审查方式的质量分数没有差异。自审查 30 秒能干完的事，没必要让子代理跑 25 分钟。

这个决策体现了 Superpowers 的核心理念之一：Evidence over claims（用证据说话，而不是靠宣称）。

哲学：Superpowers 到底在解决什么问题？

Superpowers 的哲学凝练在 README 的四行文字里：

Test-Driven Development — 始终先写测试
Systematic over ad-hoc — 流程优于猜测
Complexity reduction — 简单性是首要目标
Evidence over claims — 验证后再声称成功

这四条放在一起，指向一个核心判断：AI 编程的主要问题不是 AI 不够聪明，而是 AI 没有工程纪律。

你给一个高级工程师 500 行代码的生成任务，他会先想架构、画数据流、写接口定义、设计测试用例，然后再开始写。你给 AI 同样的任务，它直接就开始写。没有计划、没有测试、没有架构思考——因为没人告诉它需要做这些。

Superpowers 做的事情，就是把这些"默认行为"写到 AI 的启动指令里。它不是在写代码，它是在写规范——告诉 AI 应该用什么样的行为模式来工作。

生态与社区

Superpowers 到今天已经形成了一个小生态：

GitHub: 180k stars, 16k forks, 28 贡献者
Discord 社区: 活跃的讨论和问题解答
版本发布: 从 v1 到 v5.1.0，7 个月发布了 4 个大版本
官方市场: Anthropic 官方 Claude Code 插件市场收录
技能分享: 用户可以通过 PR 贡献新 Skill（虽然不接受随意的新技能提案）

Jesse Vincent 和他的团队在 Prime Radiant 公司全职维护这个项目。他们的商业模式很传统：开源核心 + 企业支持。GitHub Sponsors 页面也接受捐赠。

一些值得思考的事

不只是 AI 编程

Superpowers 的模式——用 Markdown 文件编码行为规范——其实不局限于 AI 编程。你可以用同样的方式教 AI 做任何事情：写 PRD、做数据分析、管理项目、撰写文档。

本质上，Superpowers 是一个行为规范编码框架。Skills 是行为规范，SessionStart Hook 是强制加载机制，1% Rule 是触发策略。这三个东西组合在一起，就能让 AI 在特定场景下表现出你想要的行为模式。

社区生态的潜力

174k stars 意味着什么？意味着很多人不只是感兴趣，而是真的在使用。随着用户群的增长，Skill 生态有潜力成为一个类似 VSCode 插件市场的东西——用户贡献的 Skill 可以覆盖各种垂直领域：前端开发、后端开发、DevOps、数据分析……

但目前在社区贡献方面，Superpowers 比较克制。核心维护者明确说"一般不接受新技能的 PR"，理由是所有技能必须在所有支持的平台上都能工作。这个限制未来可能会松动——如果有了平台无关性测试的话。

未来：记忆系统

Jesse Vincent 在原始发布文章中提到了一个尚未完全对接的功能：记忆系统（Memory System）。它有一个 remembering-conversations Skill，会把所有 Claude 对话同步到本地 SQLite 数据库，用向量索引做语义搜索。AI 在开始工作时可以检索过去的对话，发现之前踩过的坑和学到的教训。

这套系统的架构已经写好了，只是还没有完全集成到主工作流中。如果对接完成，Superpowers 将补上最后一块拼图——让 AI 不仅能按照规范工作，还能从历史经验中学习。

写在最后

Superpowers 180k 个 star 背后，反映的是一种渴望：开发者希望 AI 编程能真正"靠谱"，而不仅仅是"快速"。

Jesse Vincent 在解释为什么要做 Superpowers 时说：

"你的 AI 代码助手就像一个热情但没经验的初级工程师——品味差、没有项目上下文、还讨厌写测试。"

Superpowers 对这个问题的回答不是"换个更好的模型"，而是"给这个模型配上更好的流程"。这个思路在当前的大模型环境下尤其有意义——模型的智能天花板我们暂时还突破不了，但我们可以改进模型工作的方式。

如果你的 AI 助手也开始胡写代码了，或许它不是需要更多的 prompt——它只是需要一点 Superpowers。

参考链接

obra/superpowers GitHub 仓库 - 验证: ✅
idao.fun | 原文链接 - 验证: ✅
Superpowers 原始发布公告 (Jesse Vincent 博客) - 验证: ✅
Superpowers 5.0 发布说明 - 验证: ✅
Superpowers 发布说明 (GitHub) - 验证: ✅
Cialdini 原则对 LLM 有效性的研究 - 验证: ✅
Superpowers 社区 Discord - 验证: ✅
Superpowers 官方市场 (Anthropic) - 验证: ✅ x

📱 TRAE SOLO 移动端上线征文｜“我的第一次移动端AI办公” 评测，赢机械键盘礼包+10w矿石！

掘金前端

作者掘金酱

2026年5月6日 18:11

web-首页-侧边栏 260_120px.png

参与指南：下载 TRAE SOLO 移动端，完成一次500字文章评测分享，并带话题 #TRAE移动生产力# 发布，就有机会赢机械键盘、露营车、榨汁机和 10w 矿石！

近日 TRAE SOLO 移动端正式上线了，不少朋友在问：这个「移动端」到底是啥？真的能手机写代码、远程跑脚本吗？

我上手试了下，发现它确实解决了一个真实痛点——你总有一些「人在外面，但电脑在工位/家里」的时刻：

路上突然想到一个 Bug 解法，没法立刻录入代码上下文
下班后收到线上告警，身边没电脑，只能干着急
出差途中急需修改文件或跑个脚本，电脑不在身边…

TRAE SOLO 移动端就是来堵这些痛点的。

它主打三大核心场景：

想法随时下发：语音/拍照触发 AI，自动补全上下文并起草文档
无缝延续任务：手机接力 PC 任务，云端保持运行，工作不断流
远程操控电脑：手机调用 PC 算力与文件系统，一句话跑脚本、查数据库

这一次，我们邀请大家一起上手体验，写下你的「第一次移动端 AI 办公」真实评测！

✨活动时间和主题

活动主题：TRAE SOLO 移动端上线 —— 「我的第一次移动端 AI 办公」评测征文
话题话题：#TRAE移动生产力#
征文时间：2026年5月6日 – 5月30日
结果公示：6月8日 – 6月12日

⁉️如何参与

发布文章时选择带话题 #TRAE移动生产力# 就可以被统计到哦💁🏻

✍️ 写什么？三个方向任选

围绕 TRAE SOLO 移动端的核心功能，任意选择一个方向完成体验并写成文章：

方向	具体操作
🎤 语音下发任务	打开 TRAE 移动端，用语音说“帮我写一个 xxx”，让 AI 生成结果，截图保存回复
💻 远程操控电脑	在手机上远程让电脑执行一个简单命令，如“列出桌面文件”，截图保存执行结果
🔄 无缝接力任务	先在电脑端开始任务（如写一段代码），手机上继续同一对话，截图保存接力结果

✅ 文章必须带话题 #TRAE移动生产力# ，且 必须获得官方推荐 才能参与评奖。

🗒️赛道激励

本次征文分 常规挑战 和 进阶挑战 两个赛道，参与活动的文章必须获得官方推荐，才能参与奖项评选：

常规挑战

要求：正文字数不少于 500 字，文章内容至少包含 1 张真实截图/GIF
评选：按照评选规则，根据文章质量+热度综合评分
奖励：阳光普照奖

进阶挑战

要求：正文字数不少于 700 字，文章内容至少包含 2 张真实截图/GIF
评选：按照评选规则，根据文章质量+热度综合评分
奖励：根据最终得分，获取一等奖、二等奖、三等奖、人气奖、深度参与奖

奖项激励

⚠️ 特别注意：常规挑战和进阶挑战奖品 可叠加！但每位参赛者只能获得 1 次单一赛道相关奖项。

奖项	名额	奖励
一等奖	1	MageGee 机械风暴套装真机械键盘鼠标套装+移动端优秀体验官奖杯
二等奖	2	户外折叠便携露营车
三等奖	5	多功能榨汁机
人气奖	10	便携一壶三杯茶具套装
深度参与奖	进阶挑战其余有效作者	10w掘金矿石	-
阳光普照奖	前90名	鼠标垫小号26*21cm

☝️征文要求

本次征文活动需要符合主题，对于文章类型以及活动参与方式，我们有以下几点小要求。

在掘金文章区带话题 #TRAE移动生产力# 发布
内容：使用 TRAE SOLO 移动端完成任意一个功能的真实记录
字数 ≥ 500 字，不得有广告/洗稿/凑字数等行为，如果发现有此类行为，直接取消资所有获奖资格（备注：文章中50%及以上内容与网络内容相同，即视为洗稿）；
必须包含至少 1 张真实使用截图（手机界面或电脑联动界面）
原创首发，不得抄袭，已在其他平台发布过的文章不计入活动；
刷赞、刷量等有作弊行为的文章，直接取消比赛资格，不能参与评选；
文章不能只贴代码，可以讲清楚这个代码在解决什么问题，解决思路是什么，如代码量超 60%则不计入；

🧐评选标准

内容质量（60%） ：由稀土掘金内部评审团从实用性、创新性、结构完整性进行打分；
社区热度（40%） ：根据文章互动数 + 阅读数综合计算，个人数据不计入

📱 额外福利：站外分享积分换豪礼

将自己发布的评测文章转发到 知乎 / 即刻 / 小红书 / 微信公众号 ，提交截图+链接到指定问卷，可累计积分兑换礼品。

转发登记表： TRAE SOLO 移动端上线征文活动-站外转载登记表

所需积分	奖品	名额
5 积分	手持小风扇	20 人
15 积分	陶瓷碗四件套	10 人
30 积分	卡通萌宠加湿器	5 人

积分规则

每转发一个平台 → +1 积分
获得 ≥20 点赞或 ≥5 评论 → +2 积分（个人数据不计入）
同一篇文章可转发多个平台，积分可累计

⚠️ 每人限兑换一次，不可重复兑换，先到先得。

🤵征文对象

稀土掘金社区全体掘友

⏰活动时间

2026年5月6日——2026年5月30日23:59

💡注意事项

2026年5月30日活动结束后，约10-15个工作日通过系统消息的形式公示获奖情况，预计填写问卷后的20个工作日内完成奖品发放。

移动端 AI 办公到底能多丝滑？TRAE SOLO 能不能真正让你 “随时随地调起电脑生产力”？

答案就在你的第一次体验里。

拿起手机，录个屏、截个图，写下你的真实感受。奖品只是锦上添花，你的每一篇评测，都会帮助更多开发者拥抱移动办公的新可能。

📲 立即下载 TRAE SOLO 移动端，写下你的第一篇移动端 AI 办公评测！

☎️ 加群交流

参加活动的掘友一定要入群哦，重要消息不错过，大家互相鼓励，有问题也可以在群内咨询哦～

❗注意：活动开启，以及发奖进程都会第一时间群内通知，一定要进群呀，避免错过消息

注：最终解释权归稀土掘金技术社区 官方所有

Markdown 渲染如何穿插自定义组件

掘金前端

作者隔壁的大叔

2026年5月6日 18:04

在 Vue 3 流式 Markdown 渲染器中实现插件化自定义组件——踩坑全记录

背景

v3-markdown-stream 是一个基于 Vue 3 的高性能 Markdown 流式渲染组件，核心特性是支持 LLM 场景下的增量输出渲染——内容一段一段地追加，页面实时更新，无闪屏、无卡顿。

随着 AI 对话场景的丰富，单纯渲染文本已经不够了。我们希望在 Markdown 流式输出中直接嵌入图表、自定义组件。比如 LLM 返回：

根据数据分析，本月销售情况如下：

[[echarts {"type":"bar","data":[10,20,30,40,50]}]]

从图表可以看出...

渲染器应该识别 [[echarts ...]] 语法，直接在 Markdown 中渲染出 ECharts 图表。

听起来简单，实际开发中踩了一堆坑。本文记录整个开发过程和解决方案。

一、插件系统设计

1.1 核心思路

插件系统的核心流程：

流式内容: [[echarts {"type":"bar","data":[10,20,30]}]]
    ↓ 正则匹配
转换后: <v3md-echarts data-config="..." data-key="..."></v3md-echarts>
    ↓ rehype-raw 解析 HTML
HAST 树中包含自定义标签节点
    ↓ toJsxRuntime 组件映射
渲染为 ECharts Vue 组件

关键设计决策：

正则匹配：用 [[插件名 JSON配置]] 语法，正则 \[\[echarts\s+([\s\S]*?)\]\] 匹配
HTML 标签桥接：将匹配结果转换为自定义 HTML 标签，利用已有的 rehype-raw 插件解析
组件映射：在 toJsxRuntime 的 components 参数中注册自定义标签到 Vue 组件的映射

1.2 流式场景的"不完整语法"问题

流式输出时，内容是逐步到达的。[[echarts {"type":"bar","data":[10,20 这样的内容在某一时刻是不完整的——JSON 没闭合、]] 没出现。

第一个坑：不完整的插件语法会导致后续所有 Markdown 解析错乱。

如果正则匹配不到完整的 [[...]]，残留的 [ 会被 Markdown 解析器当作链接语法，导致后续内容渲染异常。

解决方案：对不完整的插件语法进行清理，用正则 [[echarts\b[\s\S]*$ 匹配流末尾的不完整语法，将其替换为 loading 占位符（而非直接删除，后面会讲为什么）。

for (const [, plugin] of pluginMap) {
  const incompleteRegex = new RegExp(
    `\\[\\[${escapeRegex(plugin.name)}\\b[\\s\\S]*$`,
    'g'
  );
  result = result.replace(incompleteRegex, () => {
    return `\n\n<div class="v3md-plugin-container"><v3md-loading></v3md-loading></div>\n\n`;
  });
}

二、ECharts 组件的集成

2.1 动态导入

ECharts 体积很大（压缩后约 1MB），不能让所有用户都加载。使用动态 import() 实现：

const initChart = async () => {
  const echarts = await import('echarts');
  chartInstance.value = echarts.init(chartRef.value);
  chartInstance.value.setOption(getOption(props.config));
};

2.2 配置解析——简单模式 vs 完整模式

第二个坑：用户期望的配置方式和 ECharts 原生配置差距很大。

ECharts 原生配置需要写 series、xAxis、yAxis 等，但用户只想写 {"type":"bar","data":[10,20,30]}。

解决方案：支持两种模式：

简单模式：type + data，自动补全坐标轴等配置
完整模式：直接传 ECharts 的 option，支持所有功能

const getOption = (config) => {
  const { type, data, width, height, ...rest } = config;
  const option = { ...rest };

  if (type && !option.series) {
    option.series = [{ type, data: data || [] }];
  }

  if (!option.xAxis && !option.yAxis && type === 'bar') {
    option.xAxis = { type: 'category', data: data.map((_, i) => `${i + 1}`) };
    option.yAxis = { type: 'value' };
  }
  // ...
  return option;
};

三、闪烁问题——最大的坑

这是整个开发过程中最棘手的问题。流式追加内容时，ECharts 图表会不断闪烁（消失再出现），体验极差。

3.1 原因分析

经过深入排查，闪烁有三层原因：

原因一：CSS 通配符动画

* {
  animation: fade-in 0.6s ease-in-out;
}

这个通配符选择器让所有元素每次 DOM 更新都重新触发淡入动画。Vue 虽然复用了 DOM 节点，但 CSS 动画会在元素属性变化时重新触发。

修复：排除插件容器及其子元素：

*:not(.v3md-plugin-container):not(.v3md-plugin-container *) {
  animation: fade-in 0.6s ease-in-out;
}

原因二：组件映射引用不稳定

toJsxRuntime 的 components 参数每次渲染都是新对象。更严重的是，如果 getComponentMappings() 每次返回新的组件定义，Vue 会认为是不同的组件，直接销毁重建。

// ❌ 每次调用都创建新的 defineComponent
function getComponentMappings() {
  const mappings = {};
  for (const [, plugin] of pluginMap) {
    mappings[plugin.tagName] = createPluginWrapper(plugin); // 每次都是新组件！
  }
  return mappings;
}

修复：缓存组件映射：

let cachedMappings = null;

function getComponentMappings() {
  if (cachedMappings) return cachedMappings;
  cachedMappings = {};
  for (const [, plugin] of pluginMap) {
    cachedMappings[plugin.tagName] = createPluginWrapper(plugin);
  }
  return cachedMappings;
}

原因三：Config 对象引用每次都是新的

这是最隐蔽的问题。流式追加内容时，props.node 引用每次都变（因为 HAST 树重建），即使 data-config 字符串完全相同，watch 也会触发，生成新的 config 对象。ECharts 组件的 deep: true watch 检测到"新"对象，就调用 setOption 重绘。

// ❌ 即使 config 内容相同，对象引用不同就会触发
watch(() => props.config, (newConfig) => {
  chartInstance.value.setOption(getOption(newConfig));
}, { deep: true });

修复：在两层都做字符串比较去重：

层一——Plugin Wrapper：比较原始 data-config 字符串，相同则不更新 configRef：

let lastRawConfig = '';

watch(() => props.node, (node) => {
  const rawConfig = node.properties?.['data-config'] || '';
  if (rawConfig === lastRawConfig) return;  // 字符串相同，跳过
  lastRawConfig = rawConfig;
  configRef.value = JSON.parse(decodeURIComponent(rawConfig));
});

层二——ECharts 组件：比较 JSON 序列化结果，相同则跳过 setOption：

let lastConfigJson = '';

const updateChart = (newConfig) => {
  const newJson = JSON.stringify(newConfig);
  if (newJson === lastConfigJson) return;  // 内容相同，跳过
  lastConfigJson = newJson;
  chartInstance.value.setOption(getOption(newConfig));
};

3.2 闪烁修复总结

层级	问题	修复
CSS	`*` 通配符动画影响插件容器	`:not()` 排除
组件映射	每次返回新组件定义	缓存 `cachedMappings`
Config 传递	node 引用变化触发不必要的更新	字符串比较去重
ECharts 更新	`deep: true` watch 过于敏感	JSON 序列化比较去重

四、流式碎片的 Loading 状态

4.1 从"删除"到"Loading"

最初处理流式碎片的方式是直接删除：不完整的图片删掉、不完整的数学公式删掉、不完整的插件语法删掉。

问题：用户看到内容突然消失又出现，体验很差。比如图片 URL 传到一半被删掉，传完整后又突然出现，视觉上就是"闪一下"。

改进：将碎片内容替换为 loading 动画，内容完整后自动替换为实际渲染结果。

4.2 三种碎片场景

碎片类型	示例	处理方式
不完整图片	`![alt](http://incom`	替换为 `<v3md-loading>`
未闭合公式	`$$ x^2 +`	删除未闭合部分 + 替换为 `<v3md-loading>`
不完整插件	`[[echarts {"type":`	替换为 `<v3md-loading>`

4.3 Loading 组件的虚拟 DOM 实现

Loading 动画使用 three-body 旋转点动画，需要用虚拟 DOM 实现（因为整个渲染管线都是虚拟 DOM）：

const V3mdLoading = defineComponent({
  name: 'V3mdLoading',
  setup() {
    return () =>
      h('div', { class: 'v3md-loading' }, [
        h('div', { class: 'three-body' }, [
          h('div', { class: 'three-body__dot' }),
          h('div', { class: 'three-body__dot' }),
          h('div', { class: 'three-body__dot' }),
        ]),
      ]);
  },
});

第四个坑：<v3md-loading> 标签被 Markdown 解析器包裹在 <p> 标签内。

自定义标签在 Markdown 中默认被当作行内 HTML，被 <p> 包裹。流式追加时 <p> 的结构变化导致 VNode 树不稳定。

修复：在替换时前后加空行，并用 <div class="v3md-plugin-container"> 包裹，确保被解析为块级元素：

return `\n\n<div class="v3md-plugin-container"><v3md-loading></v3md-loading></div>\n\n`;

五、插件默认内置

5.1 用户体验优化

最初的设计要求用户手动引入和配置：

<script setup>
import { createPluginRegistry } from 'v3-markdown-stream'
import { echartsPlugin } from './echarts-plugin.js'
const registry = createPluginRegistry([echartsPlugin])
</script>

<template>
  <MarkdownRender :pluginRegistry="registry" />
</template>

这对用户来说太繁琐了。ECharts 是最常用的图表库，应该开箱即用。

修复：在 createPluginRegistry 中默认包含 echarts 插件：

import { echartsPlugin } from './echarts-plugin.js';
const DEFAULT_PLUGINS = [echartsPlugin];

export function createPluginRegistry(plugins = []) {
  const allPlugins = [...DEFAULT_PLUGINS, ...plugins];
  // ...
}

在 markdownRender.vue 中自动创建默认 registry：

const defaultRegistry = createPluginRegistry();

模板中 fallback：

<VueMarkdownStreamRender :pluginRegistry="pluginRegistry || defaultRegistry" />

现在用户只需：

<MarkdownRender :markInfo="content" />

ECharts 图表就能直接渲染。

六、ref 标签点击事件

Markdown 中使用 <ref>[3]</ref> 标注引用，点击时需要将引用编号上报给父组件。

6.1 组件映射

和 ECharts 一样，通过 toJsxRuntime 的 components 映射将 ref 标签映射到 Vue 组件：

const baseComponents = {
  table: TableCode,
  pre: PreCode,
  ref: RefTag,
};

6.2 事件传递——provide/inject 模式

第五个坑：toJsxRuntime 生成的 VNode 树中，组件无法直接 emit 事件到上层。

因为 RefTag 组件不是 markdownRender.vue 的直接子组件，中间隔了 markdown-parse.js 和 VNode 树多层嵌套，emit 事件无法冒泡。

解决方案：使用 provide/inject 跨层级传递事件回调：

// markdown-parse.js - provide
provide(REF_CLICK_KEY, (numbers) => {
  if (props.onRefClick) {
    props.onRefClick(numbers);
  }
});

// ref-tag.js - inject
const onRefClick = inject(REF_CLICK_KEY, null);

// 点击时调用
onClick: (e) => {
  if (onRefClick && numbers.length > 0) {
    onRefClick(numbers);
  }
}

最终通过 markdownRender.vue 的 emit('refClick', numbers) 暴露给父组件。

6.3 正则提取引用编号

const extractRefNumbers = (node) => {
  const text = getTextContent(node);  // 递归提取所有文本子节点
  const match = text.match(/\[(\d+(?:\s*,\s*\d+)*)\]/);
  if (match) {
    return match[1].split(/\s*,\s*/).map(Number);
  }
  return [];
};

支持 [3]、[1,2,3]、[1, 2, 3] 等格式。

七、整体架构

┌─────────────────────────────────────────────────────┐
│                    MarkdownRender                     │
│  props: markInfo, themeColor, pluginRegistry         │
│  emit: refClick                                      │
│  ┌─────────────────────────────────────────────────┐ │
│  │            markdown-parse.js                     │ │
│  │  ┌───────────┐  ┌──────────┐  ┌──────────────┐ │ │
│  │  │ stripBroken│→ │ transform │→ │   unified    │ │ │
│  │  │  Images    │  │ Markdown  │  │  processor   │ │ │
│  │  │ (loading)  │  │ (plugins) │  │  (HAST)      │ │ │
│  │  └───────────┘  └──────────┘  └──────┬───────┘ │ │
│  │                                       │         │ │
│  │                              ┌────────▼────────┐│ │
│  │                              │  toJsxRuntime   ││ │
│  │                              │  components:    ││ │
│  │                              │  ┌───────────┐  ││ │
│  │                              │  │ table     │  ││ │
│  │                              │  │ pre       │  ││ │
│  │                              │  │ ref       │  ││ │
│  │                              │  │ v3md-*    │  ││ │
│  │                              │  │ loading   │  ││ │
│  │                              │  └───────────┘  ││ │
│  │                              └─────────────────┘│ │
│  └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

总结

这次插件化改造踩了五个主要坑：

不完整语法导致解析错乱 → 正则清理 + loading 占位
ECharts 配置门槛高 → 简单模式自动补全
流式渲染闪烁 → CSS 排除 + 组件缓存 + Config 去重（三层修复）
自定义标签被 <p> 包裹 → 块级 div 包裹 + 空行隔离
VNode 树中事件无法冒泡 → provide/inject 跨层级传递

最深刻的教训是：流式渲染场景下，任何"引用不稳定"都会被放大。普通场景中组件重建一次可能无感，但流式场景下每秒更新数十次，组件反复销毁重建就变成了闪烁。核心策略是：能缓存就缓存，能比较就比较，能跳过就跳过。

掘金前端
从零到一：用 Vue3 + Kimi 大模型打造「拍照记单词」AI 应用不会敲代码1
2026年5月6日 17:52

从零到一：用 Vue3 + Kimi 大模型打造「拍照记单词」AI 应用

掘金前端

作者不会敲代码1

2026年5月6日 17:52

从零到一：用 Vue3 + Kimi 大模型打造「拍照记单词」AI 应用

本文适合有一定 Vue3 基础、想了解如何将大模型 API 集成到前端项目的开发者。完整项目已开源，文末附链接。

前言

在 AI 时代，"一个人的公司"（OPC）正在成为可能。本文将带你从零搭建一个 拍照记单词 的前端 AI 应用——用户拍一张照片，AI 自动识别图片内容并生成一个英文单词、例句和发音。

这个项目的核心价值在于：它不是一个 Demo，而是一个可以落地的产品原型。你会学到：

如何用 Vue3 Composition API 组织复杂业务逻辑
如何调用多模态大模型（Kimi Vision）解析图片
如何集成 TTS 语音合成
如何设计一个对用户友好的 Prompt

一、项目架构总览

vue3-ts-cameraword/
├── src/
│   ├── App.vue                 # 主页面，核心业务逻辑
│   ├── components/
│   │   └── PictureCard.vue     # 拍照卡片组件
│   ├── lib/
│   │   └── audio.ts            # TTS 语音合成模块
│   └── main.ts                 # 入口文件
├── .env.local                  # 环境变量（API Key 等）
└── vite.config.ts              # Vite 配置

技术栈：Vue3 + TypeScript + Vite + Kimi Vision API + 火山引擎 TTS

二、核心功能实现

2.1 图片上传：FileReader 的妙用

传统文件上传需要后端配合，但多模态大模型可以直接接收 Base64 编码的图片。我们用 FileReader 在前端完成图片转码：

// PictureCard.vue
const updateImageData = async (e: Event): Promise<any> => {
    const file = (e.target as HTMLInputElement).files?.[0];
    if (!file) return;

    return new Promise((resolve, reject) => {
        const reader = new FileReader();
        reader.readAsDataURL(file); // 转为 Base64
        reader.onload = () => {
            const data = reader.result as string;
            imgPreview.value = data;        // 本地预览
            emit('updateImage', data);      // 传给父组件
            resolve(data);
        };
        reader.onerror = (error) => reject(error);
    });
};

关键点：

readAsDataURL() 将文件转为 data:image/png;base64,... 格式的字符串
这个字符串可以直接作为 <img> 的 src 实现预览
同时可以直接传给大模型的 image_url 字段

2.2 调用 Kimi Vision：多模态 API 实战

这是整个项目的核心。Kimi 的 moonshot-v1-8k-vision-preview 模型支持图片+文字的混合输入：

// App.vue
const update = async (imageDate: string) => {
    const endpoint = import.meta.env.VITE_KIMI_API_ENDPOINT + '/chat/completions';
    const headers = {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${import.meta.env.VITE_KIMI_API_KEY}`
    };

    word.value = '分析中...';

    const response = await fetch(endpoint, {
        method: 'POST',
        headers,
        body: JSON.stringify({
            model: 'moonshot-v1-8k-vision-preview',
            messages: [{
                role: 'user',
                content: [
                    {
                        type: 'image_url',
                        image_url: { url: imageDate }  // Base64 图片
                    },
                    {
                        type: 'text',
                        text: userPrompt                // 文字指令
                    }
                ]
            }],
            stream: false
        })
    });

    const data = await response.json();
    const replyData = JSON.parse(data.choices[0].message.content);
    // 处理返回数据...
};

这里的 content 是一个数组，可以同时包含图片和文字。这是多模态 API 的标准用法。

2.3 Prompt 设计：决定产品质量的关键

Prompt 是 AI 产品的灵魂。一个好的 Prompt 需要：

清晰的指令：告诉模型你要什么
明确的输出格式：JSON 格式便于前端解析
约束条件：限制词汇难度、输出长度等

const userPrompt = `
  分析图片内容，找出最能描述图片的一个英文单词，尽量选择更简单的A1~A2的词汇。

  返回JSON 数据：
  {
    "image_discription": "图片描述",
    "representative_word": "图片代表的英文单词",
    "example_sentence": "结合英文单词和图片描述，给出一个简单的例句",
    "explaination": "结合图片解释英文单词，段落以Look at ...开头，
                    将段落分句，每一句单独一行，
                    解释的最后给一个日常生活有关的问句",
    "explanation_replys": ["根据explaination给出的回复1",
                          "根据explaination给出的回复2"]
  }
`;

设计要点：

A1~A2 级别：控制词汇难度，适合初学者
JSON 格式：OutputParser 的思想，让返回数据结构化，便于业务处理
Look at ... 开头：引导模型用"看图说话"的方式解释，更生动
问句结尾：制造对话感，增强学习互动性

2.4 TTS 语音合成：让单词"说出来"

学英语离不开发音。我们集成火山引擎的 TTS 服务，将例句转为语音：

// lib/audio.ts
export const generateAudio = async (text: string) => {
    const endpoint = '/tts/api/v1/tts';
    const headers = {
        'Content-Type': 'application/json',
        'Authorization': `Bearer;${token}`
    };

    const payload = {
        app: { appid: appId, token, cluster: clusterId },
        user: { uid: 'bearbobo' },
        audio: {
            voice_type: voiceName,    // 音色：en_female_anna_mars_bigtts
            encoding: 'ogg_opus',     // 音频编码格式
            speed_ratio: 1.0,         // 语速
            emotion: 'happy',         // 情绪
        },
        request: {
            reqid: Math.random().toString(36).substring(7),
            text,                     // 要合成的文本
            text_type: 'plain',
            operation: 'query',
        },
    };

    const res = await fetch(endpoint, {
        method: 'POST',
        headers,
        body: JSON.stringify(payload)
    });

    const data = await res.json();
    return createBlobURL(data.data);  // 转为可播放的 URL
};

Base64 转 Blob URL 的工具函数：

function createBlobURL(base64AudioData: string): string {
    const byteArrays: number[] = [];
    const byteCharacters = atob(base64AudioData);  // 解码 Base64

    for (let offset = 0; offset < byteCharacters.length; offset++) {
        byteArrays.push(byteCharacters.charCodeAt(offset));
    }

    const audioBlob = new Blob([new Uint8Array(byteArrays)], {
        type: 'audio/mp3'
    });

    return URL.createObjectURL(audioBlob);  // 生成临时播放 URL
}

播放逻辑很简单：

// PictureCard.vue
const playAudio = () => {
    const audio = new Audio(props.audio);
    audio.play();
};

三、Vite 代理配置：解决跨域问题

前端直接调用第三方 API 会遇到跨域。用 Vite 的 server.proxy 解决：

// vite.config.ts
export default defineConfig({
    plugins: [vue()],
    server: {
        host: '0.0.0.0',           // 允许局域网访问
        proxy: {
            '/tts': {
                target: 'https://openspeech.bytedance.com',
                changeOrigin: true,
                rewrite: path => path.replace(/^\/tts/, ''),
            }
        },
    },
});

host: '0.0.0.0'：让手机等设备也能访问开发服务器
/tts 代理：将 /tts/api/v1/tts 转发到火山引擎的 API

四、无障碍设计：被忽略的细节

这个项目有一个亮点：支持读屏器的无障碍访问。

传统的 <input type="file"> 样式很难控制。我们的做法是：

<!-- 隐藏原生 input，用 label 触发 -->
<input type="file" id="selecteImage" class="input"
       accept="image/*" @change="updateImageData">
<label for="selecteImage" class="upload">
    <img :src="imgPreview" alt="camera" class="img"/>
</label>

.input {
    display: none;  /* 隐藏原生控件 */
}

for="selecteImage" 关联 id，点击 label 等同于点击 input
accept="image/*" 限制只能选择图片
读屏器可以通过 label 的文本识别按钮用途

效果

五、项目总结与思考

学到了什么

多模态 API 的调用方式：content 字段是数组，图片用 Base64 编码传入
Prompt 工程：JSON 输出格式、难度约束、引导性描述
前端音频处理：Base64 → Blob → ObjectURL 的完整链路
Vite 代理：一行配置解决跨域

可以改进的方向

加入流式输出（stream: true），让分析过程可视化
增加单词本功能，收藏学过的单词
接入语音识别，支持跟读打分
用 IndexedDB 本地存储学习记录

六、环境配置

创建 .env.local 文件：

VITE_KIMI_API_KEY=sk-xxxxx          # Kimi API Key
VITE_KIMI_API_ENDPOINT=https://api.moonshot.cn/v1

VITE_AUDIO_APP_ID=xxxxx             # 火山引擎 TTS 配置
VITE_AUDIO_ACCESS_TOKEN=xxxxx
VITE_AUDIO_CLUSTER_ID=volcano_tts
VITE_AUDIO_VOICE_NAME=en_female_anna_mars_bigtts

启动项目：

npm install
npm run dev

写在最后

这个项目虽然代码量不大，但覆盖了前端 AI 应用的核心链路：图片输入 → 多模态理解 → 结构化输出 → 语音合成。

AI 时代，前端工程师的价值不只是写页面，更是用 AI 能力重新定义产品体验。希望这篇文章能给你一些启发。

项目地址：[project/capture_word /lesson_zp - 码云 - 开源中国] 欢迎 Star 和 PR！

掘金前端
脚手架搭建项目框架（create-vite、vue-cli、create-vue、quasar-cli）RONIN
2026年5月6日 17:04

脚手架搭建项目框架（create-vite、vue-cli、create-vue、quasar-cli）

掘金前端

作者 RONIN

2026年5月6日 17:04

脚手架脚手架搭建项目框架

一. create-vite

npm create vite@latest(yarn create vite)安装脚手架命令

二. vue-cli

npm i -g @vue-cli安装脚手架命令

vue create project1创建项目

三. create-vue（vue官方的项目脚手架工具，内置了vite构建工具）项目开发中使用的脚手架

1.技术栈：

Create-vue脚手架 + Vite构建工具 + vue3组合式API （vue3选项式API）+ typescript + vue-router + pinia状态管理（vuex状态管理）+ axios网络库 + vant3 UI组件库（element-plus UI组件库） + eslint + pretter + sass

2.脚手架搭建项目框架步骤：

1） npm init vue@latest 安装脚手架命令。

根据预设生成相应的配置文件（选择ts、vue-router、pinia、eslint、pretter）。

2） pinia配置：

npm i pinia-plugin-persist -S 安装pinia持久化存储插件。

创建stores文件夹→index.ts（创建pinia根存储，集成插件）

import { createPinia } from 'pinia'
import piniaPluginPersist from 'pinia-plugin-persist'//引入pinia持久化存储插件

const storeRoot = createPinia()
storeRoot.use(piniaPluginPersist)//集成插件
export default storeRoot

main.js入口文件（集成pinia）

import { createApp } from "vue";
import router from "./router";
import store from "./store";
import App from "./App.vue";
import 'normalize.css' // 重置样式

const app = createApp(App)
app.use(router);
app.use(store);
app.mount("#app");

stores文件夹→user.ts（定义store存储对象，持久化存储增加persist选项）

import {defineStore} from 'pinia'
/**
 * 定义名为useUserStore的存储对象
 *  defineStore方法
 *   第一个参数: 模块名称是唯一的
 *   第二个参数: 选项对象  state, actions, getters
 *                        data    methods   computed
 */
export const useUserStore = defineStore('user',{
    state(){
        return {
            account:null // 账户数据 {name,nick,password}  
        }
    },
    actions:{
        // 具体业务逻辑，可以是同步或异步操作
        saveAccount(account){
            this.account = account
        }
    },
    getters:{
        //getters中定义的方法名/计算属性名不能与state相同
        // userAccount:state => {
        //     return state.account
        // }//定义方式1
        userAccount(){
            return this.account
        }//定义方式2
    },
    persist: {//持久化存储
        enabled: true,
        strategies: [
            {
                key: user,
                storage: localStorage,
                paths: ['account'],
            },
        ],
    },
})

3）Sass、axios网络库、UI组件库需手动安装集成。状态管理vuex也需要手动安装集成。

npm i normalize.css -S 安装样式重置库（兼容浏览器）。main.ts中引入import'normalize.css'

npm i sass -d 安装sass（css预处理器，开发环境用）。

npm install axios -s 安装网络库axios（前后端数据交互）。

创建utils文件夹→request.ts中配置（创建axios实例，封装请求/响应拦截器）

import axios from 'axios'
import { Toast } from 'vant';
// 服务根地址
// export const baseURL = 'http://10.7.163.165:8089'  // 开发环境
/**
 * 创建axios实例
 *   封装baseURL
 */
const axiosInstance = axios.create({
    baseURL, // 服务根地址
    timeout: 3000, // 超时时间
})
/**
 * 请求拦截器
 */
axiosInstance.interceptors.request.use(
    config => {
        const token = localStorage.getItem('TOKEN')
        if(token){
            config.headers['Authorization'] = token
        }
        return config
    },
    error => {
        return Promise.reject(error)
    }
)
/**
 * 响应拦截器
 */
axiosInstance.interceptors.response.use(
    response => {
        return response.data
    },
    error => {
        const { response } = error
        if (response) {
            const status = response.status
            switch (status) {
                case 404:
                    Toast('资源不存在 404')
                    break
                case 401:
                    Toast('Unauthorized 身份验证凭证缺失!')
                    break
                case 403:
                    Toast('403 Forbidden - 拒绝访问!')
                    break
                case 500:
                    Toast('服务器出错')
                    break
                default:
                    Toast('出现异想不到的错误！')
                    break
            }
        }else {
            // 说明服务器连结果都没有返回，可能的原因有两种：
            /**
             * 1. 服务器崩掉了
             * 2. 前端客户端断网状态
             */
            if (!window.navigator.onLine) {
                // 判断为断网，可以跳转到断网页面
                Toast('网络不可用,请检查您的网络连接!')
                return
            } else {
                Toast('连接服务端出错!' + error?.message)
                return Promise.reject(error)
            }
        }
        return Promise.reject(error)
    }
)
export default axiosInstance

vant组件库安装与配置

npm i vant@latest-v3 安装vant组件库
npm i unplugin-vue-components -D 安装vant按需引入插件。vite.config.ts中引入集成
npm i postcss-pxtorem -D安装移动端适配插件，将px单位转化为rem单位。vite.config.ts中引入集成
npm i amfe-flexible -D安装移动端适配插件，适配不同屏幕尺寸。main.ts中引入

vite.config.ts

import { fileURLToPath, URL } from 'node:url'

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

import Components from 'unplugin-vue-components/vite'//引入按需引入插件
import { VantResolver } from 'unplugin-vue-components/resolvers'//引入按需引入插件

import postCssPxToRem from 'postcss-pxtorem'//引入移动端适配插件

import { viteMockServe } from 'vite-plugin-mock'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [VantResolver()],//集成按需引入插件
    }),
    viteMockServe({//集成mock模拟接口数据插件
      // 更多配置见最下方
      supportTs: true,
      logger: false,
      mockPath: './mock/', // 文件位置
    }),
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  css:{
    postcss:{
      plugins:[
        postCssPxToRem({//自适应，px转rem
          rootValue:75,//换算的基数(设计图750的根字体为75)
          propList:['*']//需要转换的属性，*代表全部
        })
      ]
    }
  },
  server:{//代理服务器
    proxy: {
      '/api': {
        target: 'http://124.71.63.13:8088/',
        changeOrigin: true,
        // rewrite: path => path.replace(/^\/api/, '')
      }
    }
  },
})

main.ts

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import store from './stores'
import 'normalize.css' // 重置样式

// 导入vant函数组件样式
import 'vant/es/toast/style'
import 'vant/es/dialog/style'
import 'vant/es/notify/style'
import 'vant/es/image-preview/style'

//引入amfe-flexible屏幕适配插件
import 'amfe-flexible'

const app = createApp(App)
app.use(store)
app.use(router)

app.mount('#app')

elementplus组件库安装与配置

npm install element-plus --save安装elementplus组件库
npm install -d unplugin-vue-components unplugin-auto-import安装两个插件自动按需引入

vite.config.js集成插件

import { fileURLToPath, URL } from 'node:url'

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

import AutoImport from 'unplugin-auto-import/vite'//引入插件
import Components from 'unplugin-vue-components/vite'//引入插件
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'//引入插件

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vue(),
    AutoImport({//集成插件
        resolvers: [ElementPlusResolver()],
    }),
    Components({//集成插件
        resolvers: [ElementPlusResolver()],
    }),
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
})

main.js引入elementplus样式，否则可能出现使用组件没效果。

import { createApp } from "vue";
import router from "./router";
import store from "./store";
import 'element-plus/dist/index.css';//引入elementplus样式
import App from "./App.vue";

import ElementPlus from 'element-plus';//完整引入elementplus，文件大小会很大。可以考虑按需引入

const app = createApp(App);
app.use(router);
app.use(store);

app.use(ElementPlus);//完整引入elementplus，文件大小会很大。可以考虑按需引入
app.mount("#app");

状态管理vuex安装与配置

npm install vuex@next(4.0.2) --save安装vuex插件
npm i vuex-persistedstate -s安装vuex持久化存储插件

main.js引入集成到vue

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import store  from './store'

const app = createApp(App)
app.use(router)
app.use(store)
app.mount('#app')

创建story文件夹→index.js文件集成持久化存储插件

import { createStore } from 'vuex'
import createPersistedState from 'vuex-persistedstate'

const store = createStore({
    // 集成持久化存储插件
    plugins:[createPersistedState({
        storage:sessionStorage,
        key:'storekey'
    })]
    state: {//状态数据
        count: 0
    },
    mutations: {//操作state状态。第一个参数:state对象，第二个参数：外部传入参数
        PLUS(state) {//方法
            // state.count = num
            state.count++
        },
    },
    /**
     * 定义操作mutations方法的方法
     * 供外部组件调用
     *   $store.dispatch('')
     *    1. 单向数流操作方式,保存状态数据以预期方式改变
     *    2. actions 异步操作
     *       mutations 同步操作
     */
    actions: {//操作mutations中的方法
        // plus(context) {//方法
        //     context.commit('PLUS')
        // }
        plus({ commit }) {//解构
            commit('PLUS')
        },
        chs({ commit },num) {//传参
            commit('CHS',num)
        }
    },
    getters: {//获取值，类似计算属性
        num: (state) => { return state.count }
        // num: state => state.count
    }
})
export default store

3.解决引入vue组件ts报错(因为ts不识别.vue文件，需在env.d.ts中声明)

env.d.ts

// <reference types="vite/client" />
declare module '*.vue' {
    import { DefineComponent } from 'vue'
    const component: DefineComponent<{}, {}, any>
    export default component
}

4.目录结构介绍

npm install(npm i)下载依赖
npm run dev运行

5.打包

将vue文件编译成浏览器能识别的js/html/css文件、ts编译成js文件、scss编译成css文件，压缩处理。
编译后的文件存放在dist目录下（与src同级），都是html/css/js文件，将其部署到服务器上用户就可以用了。

接口环境配置： 开发环境（测试数据）/生产环境（用户使用的数据）

创建utils文件夹→request.ts中配置（创建axios实例，封装请求/响应拦截器,配置接口环境）

解决跨域问题走代理服务器：baseUrl地址为当前客户端地址，vite.config.ts配置代理服务器，代理服务器地址为目标地址（一般指测试地址/线上服务器地址）。

import axios from 'axios'
import { Toast } from 'vant'

// 服务根地址
// export const baseURL = 'http://10.7.163.165:8089'  // 开发环境

// 生产环境 如果服务端没做跨域处理，使用代理服务器
// 走代理服务器，baseURL 地址配置为与当前客户端地址相同
export let baseURL = 'http://10.7.163.165:8089'  // 开发环境
/**
 * process.env.NODE_ENV
 *    production 生产环境
 *        npm run build
 *    development  开发环境
 *        npm run dev
 */
switch (process.env.NODE_ENV) {
    case 'production':
        baseURL = 'http://124.71.63.13'  // 生产环境
        break
    case 'development':
        baseURL = 'http://10.7.163.165:8089' // 开发环境
        break
}
/**
 * 创建axios实例
 *   封装baseURL
 */
const axiosInstance = axios.create({
    baseURL, // 服务根地址
    timeout: 3000, // 超时时间
})
/**
 * 请求拦截器
 */
axiosInstance.interceptors.request.use(
    config => {
        const token = localStorage.getItem('TOKEN')
        if (token) {
            config.headers['Authorization'] = token
        }
        return config
    },
    error => {
        return Promise.reject(error)
    }
)
/**
 * 响应拦截器
 */
axiosInstance.interceptors.response.use(
    response => {
        return response.data
    },
    error => {
        const { response } = error
        if (response) {
            const status = response.status
            switch (status) {
                case 404:
                    Toast('资源不存在 404')
                    break
                case 401:
                    Toast('Unauthorized 身份验证凭证缺失!')
                    break
                case 403:
                    Toast('403 Forbidden - 拒绝访问!')
                    break
                case 500:
                    Toast('服务器出错')
                    break
                default:
                    Toast('出现异想不到的错误！')
                    break
            }
        } else {
            // 说明服务器连结果都没有返回，可能的原因有两种：
            /**
             * 1. 服务器崩掉了
             * 2. 前端客户端断网状态
             */
            if (!window.navigator.onLine) {
                // 判断为断网，可以跳转到断网页面
                Toast('网络不可用,请检查您的网络连接!')
                return
            } else {
                Toast('连接服务端出错!' + error?.message)
                return Promise.reject(error)
            }
        }
        return Promise.reject(error)
    }
)
export default axiosInstance

tsconfig.json(解决request.ts中环境配置时process报错)

{
    "extends": "@vue/tsconfig/tsconfig.web.json",
    "include": ["env.d.ts", "src/**/*", "src/**/*.vue"],
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "@/*": ["./src/*"]
        },
        // 解决process.env.NODE_ENV报错，
        // 1.安装npm i @types/node -S
        // 配置"types": ["node"]
        "types": ["node"]
    },
    "references": [
        {
            "path": "./tsconfig.config.json"
        }
    ]
}

vite.config.ts配置代理服务器

import { fileURLToPath, URL } from 'node:url'

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

import Components from 'unplugin-vue-components/vite'//引入按需引入插件
import { VantResolver } from 'unplugin-vue-components/resolvers'//引入按需引入插件

import postCssPxToRem from 'postcss-pxtorem'//引入移动端适配插件

import { viteMockServe } from 'vite-plugin-mock'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [VantResolver()],//集成按需引入插件
    }),
    viteMockServe({//集成mock模拟接口数据插件
      // 更多配置见最下方
      supportTs: true,
      logger: false,
      mockPath: './mock/', // 文件位置
    }),
  ],

  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  css:{
    postcss:{
      plugins:[
        postCssPxToRem({//自适应，px转rem
          rootValue:75,//换算的基数(设计图750的根字体为75)
          propList:['*']//需要转换的属性，*代表全部
        })
      ]
    }
  },
  server:{//代理服务器
    proxy: {
      '/api': {
        target: 'http://124.71.63.13:8088/',//目标地址
        changeOrigin: true,//是否跨域
//这里理解成用'/api'代替target里面的地址,比如我要调用'http://40.00.100.100:3002/user/add'，直接写'/api/user/add'即可
        rewrite: (path) => path.replace(/^**\/** api/, ''),
      }
    }
  },
})

npm run build打包

四. quasar-cli项目开发中使用的脚手架

关于quasar要求：

Node 12+用于Quasar CLI与Webpack，Node 14+用于Quasar CLI与Vite。
Yarn v1（强烈推荐），PNPM，或NPM。

npm i -g @quasar/cli 安装脚手架命令

npm init quasar 初始化quasar根据预设生成相应的配置文件

此时回车，会生成项目文件和目录

提示安装项目依赖，选择yes回车

quasar dev（npm run dev）运行

Tiptap 简单编辑器模版

掘金前端

作者时光足迹

2026年5月6日 16:38

上一篇介绍了Tiptap 编辑器的基础使用，本篇主要介绍 Tiptap 的简单编辑器模版Simple template，以及如何改造模版。

Tiptap 是一个基于 ProseMirror 的 Headless 富文本编辑器框架，它采用模块化设计，通过扩展（Extensions）机制来实现各种功能。每个扩展可以定义自己的节点（Nodes）、标记（Marks）、命令（Commands）等。

Editor 实例：Tiptap 的核心，管理整个编辑器的状态和行为
Extensions 扩展：功能模块的基本单位，可以是节点或标记
Nodes 节点：文档结构的基本单位，如段落、标题、列表项等
Marks 标记：应用于文本的样式，如粗体、斜体、链接等
Commands 命令：用于修改编辑器状态的操作方法

simple-editor 模版

Tiptap 的 StarterKit 仅提供基础的富文本功能逻辑，不会自带默认样式（如标题字体大小、段落首行缩进等），需要手动添加 CSS 样式来美化内容。

可以安装一个简单编辑器模版Simple template，其包括常用的开源扩展和 UI 组件。

npx @tiptap/cli@latest add simple-editor

SimpleEditor：主编辑器组件，整合所有功能
- tiptap-templates 文件夹
Toolbar：工具栏组件，提供各种编辑操作按钮
- tiptap-ui 文件夹
Extensions：预配置的扩展集合，包括基础文本格式、列表、链接等
- tiptap-ui-primitive 文件夹
Styles：配套的样式文件，提供美观的默认外观

操作完成后，会在项目中加入一系列的文件，包括组件、配置文件、样式文件等等：

在 global.css全局样式文件中添加模版的样式文件：

/* tiptap */
@import "./styles/_variables.scss";
@import "./styles/_keyframe-animations.scss";

配置完成后，页面样式乱了呀，影响其他内容样式了，如下图所示：

排查后，发现是暗黑模式和默认宽高影响的，需要调整一下：

import { SimpleEditor } from "@/components/tiptap-templates/simple/simple-editor";
import { styled } from "styled-components";

export default function Page() {
  return (
    <Container>
      <SimpleEditor />
    </Container>
  );
}

const Container = styled.div`
  width: 500px;
  margin-top: 30px;
  border: 1px solid #eee;
  .simple-editor-wrapper {
    width: 100%;
    height: 300px;
  }
`;

simple-editor 改造

主题

默认主题是暗黑模式，改为明亮模式：

// 修改theme-toggle.tsx文件

// 注释掉下列代码：
React.useEffect(() => {
  const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
  const handleChange = () => {
    // setIsDarkMode(mediaQuery.matches)
  };
  mediaQuery.addEventListener("change", handleChange);
  return () => mediaQuery.removeEventListener("change", handleChange);
}, []);

// React.useEffect(() => {
//   const initialDarkMode =
//     !!document.querySelector('meta[name="color-scheme"][content="dark"]') ||
//     window.matchMedia("(prefers-color-scheme: dark)").matches;
//   setIsDarkMode(initialDarkMode);
// }, []);

然后在工具条中去掉该功能即可

工具条样式

默认工具条是横向滚动的，改为自适应

/* 修改simple-editor.css文件 */
.simple-editor-wrapper {
  width: 100%;
  height: 300px;
  border: 1px solid #eee;
  .tiptap-toolbar {
    flex-wrap: wrap;
    /* 或者直接隐藏首个 <Spacer /> 组件 */
    > div:first-of-type {
      flex: 0 !important;
    }
  }
}

调整后效果：

工具条汉化

默认工具条是英文的，改为中文：

操作组件 undo-redo-button

<UndoRedoButton action="undo" />
<UndoRedoButton action="redo" />
// 修改tiptap-ui/undo-redo-button/use-undo-redo.ts文件
export const historyActionLabels: Record<UndoRedoAction, string> = {
  undo: "撤销",
  redo: "重做",
}

标题组件 heading-dropdown-menu

列表组件 list-dropdown-menu

引用块 blockquote-button

代码块 code-block-button
文本样式 mark-button
- 粗体 bold
- 斜体 italic
- 删除线 strike
- 代码 code
- 下划线 underline
- 上标 superscript
- 下标 subscript

高亮组件 color-highlight-button

链接组件 link-popover

对齐组件 align-align-button

图片组件 image-upload-button

改造前：

改造中：

改造后：

Tiptap编辑器

掘金前端

作者时光足迹

2026年5月6日 16:37

主要介绍了编辑器的基础使用，包括依赖安装、基础配置，以及 StarterKit 基础扩展、内嵌图片 Image、编辑状态、拖拽手柄、文本样式扩展包等等

基础介绍

ProseMirror：是一款用于在网页端构建富文本编辑器的工具包，核心目标是弥合 “结构化内容编辑”（如 Markdown、XML）与 “经典所见即所得（WYSIWYG）编辑” 之间的差距 —— 既让用户能以直观的 WYSIWYG 方式编辑，又能生成干净、语义明确且符合自定义结构的文档，适用于从简单文本编辑到复杂协作系统的各类场景。

Tiptap 是基于 ProseMirror（经行业验证的网页富文本编辑器工具库）构建的无头（Headless）富文本编辑器框架，核心能力是帮助开发者打造 “完全贴合自身及用户需求” 的定制化编辑器。

其底层依赖三大核心机制实现灵活且强大的编辑功能 API：

事件（Events）：监听编辑器状态变化（如内容修改、光标移动）；
命令（Commands）：触发编辑操作（如加粗文本、插入列表）；
扩展（Extensions）：扩展编辑器功能（如添加表格、AI 辅助创作）。

核心价值是 “按需构建编辑器”，既提供基础开源编辑功能，也通过云服务和扩展满足复杂场景需求，核心能力分为五大模块，覆盖从基础编辑到高级协作的全场景：Editor（编辑器）、Collaboration（协作）、Content AI（内容 AI）、Comments（评论）、Documents（文档处理）

安装

@tiptap/react：Tiptap 的 React 绑定包，包含核心功能（如 useEditor 钩子、EditorContent 组件）
@tiptap/pm：Tiptap 依赖的 ProseMirror 底层库，是编辑器运行的核心支撑
@tiptap/starter-kit：基础扩展集合，包含段落、标题、加粗、斜体等常用功能，可快速启动项目

pnpm install @tiptap/react @tiptap/pm @tiptap/starter-kit

基础使用

参照官方文档，完成了一个初始 Demo

import { Image } from "antd";
import { styled } from "styled-components";

import { EditorContent, EditorContext, useEditor } from "@tiptap/react";
import { BubbleMenu, FloatingMenu } from "@tiptap/react/menus"; // 导入菜单组件
import StarterKit from "@tiptap/starter-kit"; // 导入基础扩展集合
import { useMemo } from "react";
export default function Page() {
  // 1. 使用 useEditor 钩子初始化编辑器
  const editor = useEditor({
    // 配置扩展（此处使用基础扩展集合）
    extensions: [StarterKit],
    // 编辑器初始内容（HTML 格式）
    content: `
    <h1>第一章原始阶段和商周时期的江南</h1>
    <p>地方特点的青铜器。第一类典型的商代青铜器特别是那些有铭文的铜器，很可能是从中原地区传过来的；第三类具有地方特点的青铜器应是在本地铸造的；第二类青铜器有的可能铸自本地，也有的可能来自中原。</p>
    <p>这些商代铜器除了少数出自遗址和墓葬外，绝大多数出自窖藏，且多出自山顶、山腰、河岸、湖边，很有可能是当时人们祭祀山川、湖泊、日月星辰的遗物。①</p>
    <p>宁乡、湘潭等地出土的商代铜器中，有“己”分裆鼎、“癸母”提梁卤和“戈”卤等少量有铭文的铜器②；在湘潭县青山桥一铜器窖穴中也出土有商末周初的“母”爵，“母”解和“戈”解③。“母”和“戈”本是中原商代铜器中两个常见的族徽，现在江南地区也有铸这两个族徽的铜器出土，说明在商代晚期或末期，他们中的一支曾南迁到了湘中地区。</p>
    <p>湖南境内出土的西周铜器，仍以湘水流域为多，如湘潭、湘乡、浏阳、株洲、望城、衡阳、耒阳、资兴等地都有出土。器形以乐器饶、甬钟和镈为主④，还有湘潭青山桥窖藏出土的爵、解、鼎、凹字形锄等⑤。桃江连河冲出有马簋。⑥</p>
    <p>西周时期的铜饶是紧接着商代晚期的大饶发展而来。商末周初的铜铙为乳钉铙，钲的每面有18个乳钉。这些乳钉的出现可能有两个来源，其乳钉的排列和数量应来源于商代云纹铙上云纹的尾部的上翘，这有江西新干商代大墓中出土的云纹铜饶为证。乳钉的形状应是对于象纹大饶钲边乳钉的承袭。乳钉铙上的乳钉不断升高，在西周初演变为尖锥状和</p>
    `,
  });

  // 缓存 Context 值，避免不必要的重渲染
  const providerValue = useMemo(() => ({ editor }), [editor]);

  return (
    <Container>
      <div className="block-wrap">
        <div className="left">
          <Image src="/pdf/1-1.jpg" />
        </div>
        <div className="right">
          {/* 提供 EditorContext，让子组件可访问编辑器实例 */}
          <EditorContext.Provider value={providerValue}>
            {/* 2. 编辑器内容区域：渲染编辑界面 */}
            <EditorContent editor={editor} />

            {/* 3. 浮动菜单：空行光标定位时显示 */}
            <FloatingMenu editor={editor}>这是浮动菜单</FloatingMenu>

            {/* 4. 气泡菜单：选中文本时显示 */}
            <BubbleMenu editor={editor}>这是气泡菜单</BubbleMenu>
          </EditorContext.Provider>
        </div>
      </div>
    </Container>
  );
}

const Container = styled.div`
  .block-wrap {
    display: flex;
    width: 80%;
    margin: 0 auto;
    > div {
      width: 50%;
    }
  }
`;

显示效果如图 tiptap-1-1 所示：

StarterKit 基础扩展集合

StarterKit 默认包含的核心扩展：文档（Document）、段落（Paragraph）、文本（Text）、标题（Heading）、加粗（Bold）、斜体（Italic）、删除线（Strike）、代码（Code）、无序列表（BulletList）、有序列表（OrderedList）等等。

具体入门套件，可以查看官网：StarterKit

在 StarterKit.configure() 中传入配置对象，通过 “扩展名称” 精准定位需修改的模块

import Strike from "@tiptap/extension-strike"; // 导入删除线扩展

new Editor({
  extensions: [
    StarterKit.configure({
      heading: { levels: [1, 2, 3] }, // 调整标题层级
    }),
  ],
});

内嵌图片 Image

具体可查看官方文档：image

# 安装扩展
pnpm install @tiptap/extension-image

使用示例如下所示：

import { Image as TiptapImage } from "@tiptap/extension-image"; // 图片扩展

const editor = useEditor({
  // 配置扩展（此处使用基础扩展集合）
  extensions: [
    StarterKit.configure({
      heading: { levels: [1, 2, 3] }, // 调整标题层级
    }),
    TiptapImage.configure({
      inline: true, // 允许行内
      allowBase64: true, // 允许 base64 格式图片
      HTMLAttributes: {
        class: "tiptap-img-inline", // 自定义样式名
      },
    }),
  ],
  content: `
    <p>宁乡、湘潭等地出土的商代铜器中，有“己<img src="/pdf/1-1-1.png" />”分裆鼎、“癸<img src="https://placehold.co/40x40/6A00F5/white" />”提梁卤和“戈”卤等少量有铭文的铜器②；在湘潭县青山桥一铜器窖穴中也出土有商末周初的“<img src="/pdf/1-1-2.png" />”爵，“<img src="/pdf/1-1-2.png" />”解和“戈”解③。“<img src="/pdf/1-1-2.png" />”和“戈”本是中原商代铜器中两个常见的族徽，现在江南地区也有铸这两个族徽的铜器出土，说明在商代晚期或末期，他们中的一支曾南迁到了湘中地区。</p>
    `,
});

配置了inline: true，设置为行内图片，但是没起作用呀。

排查发现，有个默认样式配置，将图片设置为块元素了，那只能自定义样式处理了呗。

只能添加自定义样式HTMLAttributes: {class:"tiptap-img-inline"}

.tiptap-img-inline {
  display: inline; /* 强制行内显示 */
}

当然，如果不想要行内显示的话，就不将 img 放到 p 标签内，而是直接放在 p 标签外，这样图片就会块级元素了。

代码展示：

渲染效果展示：

编辑状态控制

// 控制编辑器可编辑状态
const [isEditable, setIsEditable] = useState(false);
useEffect(() => {
  if (editor) {
    editor.setEditable(isEditable);
  }
}, [isEditable, editor]);

// 开关渲染
<Switch
  checkedChildren="开启"
  unCheckedChildren="关闭"
  checked={isEditable}
  onChange={setIsEditable}
/>;

拖拽手柄控制

官方文档：drag-handle-react

文本样式集合包

文本样式集合包含：TextStyle、BackgroundColor（背景色）、Color（颜色）、FontFamily（字体）、FontSize（字号）、LineHeight（行高）

官方文档：text-style-kit

# 安装插件
pnpm install @tiptap/extension-text-style

import { TextStyleKit } from "@tiptap/extension-text-style"; // 文本样式扩展

const editor = useEditor({
  extensions: [
    StarterKit,
    // 添加文本样式功能集合，包含字体、颜色、背景色、行高、字体大小等样式控制
    TextStyleKit,
    TiptapImage,
  ],
});

ThreeJS之GUI控制器

掘金前端

作者时光足迹

2026年5月6日 16:36

上篇主要介绍了 three.js 的基础使用及配置，例如场景、相机、渲染器、轨道控制器、灯光等等；本篇主要介绍 GUI 控制器，方便调试模型属性，例如按钮事件、位置、颜色、线框模式等等

初始化模型

let scene; // 场景
let camera; // 相机
let renderer; // 渲染器
let controls; // 轨道控制器
const width = 300;
const height = 300;
let glbScene; // 3d加载模型
let cube; // 立方体

// 1. 初始化场景
const initScene = () => {
  scene = new THREE.Scene();
  // 设置背景色
  scene.background = new THREE.Color(0xffffff);
};

// 2. 初始化相机
const initCamera = () => {
  camera = new THREE.PerspectiveCamera(
    75, // 视角
    width / height, // 宽高比
    0.1, // 近平面
    2000 // 远平面
  );
  camera.position.z = 2; // 设置相机在 z 轴上的位置
  camera.position.y = 0.2;
  camera.lookAt(0, 0, 0); // 看向原点
};

// 3. 创建渲染器
const initRenderer = (id) => {
  renderer = new THREE.WebGLRenderer({ antialias: true });
  renderer.setSize(width, height); // 设置渲染器尺寸
  // renderer.setClearColor(0xffffff, 0); // 设置背景颜色 默认黑色

  // 获取渲染元素
  const container = document.getElementById(id) as HTMLElement;
  container.appendChild(renderer.domElement);
};

// 4. 添加轨道控制器（调整相机位置，即视角位置）
const initControls = () => {
  controls = new OrbitControls(camera, renderer.domElement);
  controls.enableDamping = true; // 允许阻尼效果，使动画更平滑
  controls.dampingFactor = 0.05; // 阻尼系数
  controls.rotateSpeed = 0.1; // 旋转速度
  // controls.autoRotate = true; // 自动旋转
  // controls.autoRotateSpeed = 1; // 自动旋转速度
};

// 5. 动画刷新
const animate = () => {
  requestAnimationFrame(animate);
  controls.update(); // 更新控制器状态
  renderer.render(scene, camera); // 重新渲染
};

// (1)添加3d元素（立方体）
const initBox = () => {
  // import buyImg from "../../../assets/img/buy-gift.png";
  // 环境贴图
  new THREE.TextureLoader().load(buyImg, (texture) => {
    // 创建立方体(width,height,depth)
    const box = new THREE.BoxGeometry(1, 1, 1);
    // 创建材质
    const material = new THREE.MeshBasicMaterial({
      color: 0x00ff00,
      map: texture,
      side: THREE.BackSide,
    });
    // 创建网格（将物体和材质链接起来）
    cube = new THREE.Mesh(box, material);
    cube.position.set(1, 1, 0);
    // 添加到场景
    scene.add(cube);
  });
};

// (2)加载3D模型
const initGlb = (url) => {
  // 创建GLTF实例
  const loader = new GLTFLoader();
  // 加载模型
  loader.load(url, (glb) => {
    // console.log("glb.scene", glb.scene);
    glbScene = glb.scene;
    glb.scene.position.y = -0.7;
    scene.add(glb.scene);
  });
};

// (3)添加灯光
const initLight = () => {
  // 添加环境光
  const ambientLight = new THREE.AmbientLight(0xffffff, 4); // 柔和的白光
  scene.add(ambientLight);
};

// (4)添加其他
const initOther = () => {
  // 添加网格地面
  const gridHelper = new THREE.GridHelper(10, 10);
  scene.add(gridHelper);

  // 添加坐标轴
  const axesHelper = new THREE.AxesHelper(5);
  scene.add(axesHelper);
};

initScene();
initCamera();
initRenderer(item.id);
initControls();
animate();

initBox();
initGlb(item.nftFileUrl);
initLight();
initOther();

添加灯光(initLight)和其他(initOther)前的效果：

添加灯光(initLight)和其他(initOther)后的效果：

添加 GUI 控制

// 创建立方体
const initBox = () => {
  // 创建立方体(width,height,depth)
  const box = new THREE.BoxGeometry(1, 1, 1);
  // 创建材质
  const material = new THREE.MeshBasicMaterial({
    color: 0x00ff00,
    side: THREE.BackSide,
  });
  material.wireframe = true; // 设置为线框模式
  // 创建网格（将物体和材质链接起来）
  cube = new THREE.Mesh(box, material);
  cube.position.set(1, 1, 0);
  // 添加到场景
  scene.add(cube);
};

// 加载glb实例
const initGlb = (url) => {
  // 创建GLTF实例
  const loader = new GLTFLoader();
  // 加载模型
  loader.load(url, (glb) => {
    console.log("glb.scene", glb.scene);
    glbScene = glb.scene;
    glb.scene.position.y = -0.7;
    scene.add(glb.scene);

    // 添加GUI配置
    initGui();
  });
};

// 添加GUI配置
// import { GUI } from "three/examples/jsm/libs/lil-gui.module.min.js";
const initGui = () => {
  // 创建GUI
  const gui = new GUI();

  // 添加按钮（.name重命名为中文）
  const eventObj = {
    fullScreen: () => {
      // 全屏
      document.body.requestFullscreen();
    },
    exitScreen: () => {
      // 退出全屏
      document.exitFullscreen();
    },
  };
  gui.add(eventObj, "fullScreen").name("全屏");
  gui.add(eventObj, "exitScreen").name("退出全屏");

  // 控制模型位置
  console.log(glbScene);
  let folder = gui.addFolder("模型位置"); // 添加分组
  folder
    .add(glbScene.position, "x", -5, 5) // 参数和下面同等效果
    .onChange((val) => console.log("x", val)); // 变动时触发
  folder
    .add(glbScene.position, "y")
    .min(-5) // 最小值
    .max(5) // 最大值
    .step(1) // 部进
    .name("y轴") // 重命名
    .onFinishChange((val) => console.log("y", val)); // 变动结束时触发

  // 线框模式控制
  console.log("cube", cube);
  // 要有配置：material.wireframe = true，boolean值处理
  gui.add(cube.material, "wireframe").name("线框模式");

  // 颜色调整
  const colorParams = { cubeColor: "#ff0000" };
  gui
    .addColor(colorParams, "cubeColor")
    .name("立方体颜色")
    .onChange((val) => cube.material.color.set(val));
};

电子书阅读器之笔记高亮（跨段处理）

掘金前端

作者时光足迹

2026年5月6日 16:32

文本高亮

之前介绍了电子书阅读器之笔记高亮，主要展示处理逻辑。当时，只能处理同一段内的文字，不能跨段处理。现在就介绍如何处理跨段高亮。

Selection

window.getSelection()返回一个 Selection 对象，表示用户选择的文本范围或光标的当前位置。它代表页面中的文本选区，可能横跨多个元素。

selection.toString()：获取选中文本

const selection = window.getSelection();
console.log("[selection]", selection);
const selectedText = selection.toString().trim();
console.log("[选中文本]", selectedText);

Range

Range表示一个包含节点与文本节点的一部分的文档片段

getRangeAt：获取选区包含的指定区域（Range）的引用

const range = selection.getRangeAt(0);
console.log("[选中Range]", range);

const {
  startContainer, // 起始节点
  startOffset, // 起始节点偏移量
  endContainer, // 终止节点
  endOffset, // 终止节点偏移量
} = range;
console.log("[起始节点]", startContainer, "偏移量", startOffset);
console.log("[终止节点]", endContainer, "偏移量", endOffset);

getBoundingClientRect

getClientRects：返回所有边界矩形的矩形集合
getBoundingClientRect：返回一个将范围内所有元素的边界矩形包围起来的边界矩形

const rectList = range.getClientRects();
console.log("[边界对象集]", rectList);
const rect = range.getBoundingClientRect();
console.log("[边界矩形]", rect);

选中位置定位

使用 rect 的位置，显示效果如下：

const position = { top: rect.top, left: rect.left };
console.log("[选中位置]", position);

使用 rectList 的位置，显示效果如下：

const position = { top: rectList[0].top, left: rectList[0].left };
console.log("[选中位置]", position);

我选择是这种方式，展示在选中文本第一个元素的位置。

滚动条影响

如果内容区域有滚动条，那么选中位置的定位坐标需要加上滚动条的值，即 top 需要加上滚动条的偏移量。

const position = {
  top: rectList[0].top + contentRef.current.scrollTop,
  left: rectList[0].left,
};

文本高亮

监听鼠标抬起(onMouseUp)事件，获取选中的文本，并高亮。

export default function Page() {
  // 处理鼠标抬起事件
  const handleMouseUp = () => {
    // 获取选中文本信息，包括位置信息
    const selectedRange = getSelectionPosition();
    if (selectedRange) {
      console.log(selectedRange);
      highlightText(selectedRange);
    }
  };

  return (
    <div ref={contentRef} onMouseUp={handleMouseUp} onClick={handleClick}>
      {/* 数字教材预览区 */}
      <MPreview list={list} />
      {/* 选中文本操作弹框 */}
      <PopupMenu ref={popupRef} />
      {/* 笔记编辑弹框 */}
      <PopupModify ref={modifyRef} />
    </div>
  );
}

文本节点

// 获取所有文本节点（带位置信息）
const getAllNodes = (contentRef: HTMLDivElement) => {
  if (!contentRef) return [];

  // 获取所有文本节点
  const textNodes: Node[] = [];
  const walker = document.createTreeWalker(contentRef, NodeFilter.SHOW_TEXT, {
    acceptNode: (node) =>
      node.textContent?.trim()
        ? NodeFilter.FILTER_ACCEPT
        : NodeFilter.FILTER_REJECT,
  });

  let node: Node | null = null;
  while (true) {
    node = walker.nextNode();
    if (!node) break;
    textNodes.push(node);
  }

  // 计算累积文本长度和节点位置
  let totalLength = 0;
  return textNodes.map((textNode) => {
    const text = textNode.textContent ?? "";
    const start = totalLength;
    totalLength += text.length;
    return { node: textNode, text, start, end: totalLength };
  });
};

高亮数据

const getSelectionPosition = () => {
  const selection = window.getSelection();
  // 1. 获取高亮文本
  const selectedText = selection.toString().trim();

  // 2. 获取高亮文本定位（用于弹框定位显示）
  const range = selection.getRangeAt(0);
  const rectList = range.getClientRects();
  const position = { top: rectList[0].top, left: rectList[0].left };

  // 3. 获取高亮文本位置（相对于全局文本的位置，用于高亮标色）
  let globalStart = -1;
  let globalEnd = -1;
  const nodeMap = getAllNodes();
  for (const { node, start } of nodeMap) {
    // 查找起始节点位置
    if (node === startContainer) globalStart = start + range.startOffset;
    // 查找结束节点位置
    if (node === endContainer) globalEnd = start + range.endOffset;
    // 提前退出
    if (globalStart >= 0 && globalEnd > 0) break;
  }

  if (globalStart >= 0 && globalEnd > 0) {
    console.log(`[选中范围]${globalStart}-${globalEnd}`);
    // 多行选择时，会跨元素，要找到第一个元素的id
    const startElement = getElementWithAttributes(selection.anchorNode);
    console.log("[开始元素]", startElement);

    return {
      startIndex: globalStart,
      endIndex: globalEnd,
      selectedText,
      className: "orange",
      chapterId,
      divId: startElement.id,
      top: position.top + contentRef.current.scrollTop,
      left: position.left,
    };
  }
};

高亮文本

const highlightText = (note) => {
  // 1. 先清除现有高亮
  removeHighlights(contentRef);

  // 2. 获取节点映射
  const nodeMap = getAllNodes(contentRef);

  // 3. 创建高亮范围
  const highlights: { range: Range, className: string, id: string }[] = [];

  // 4. 遍历nodeMap，处理每个文本节点
  for (const { node, text, start, end } of nodeMap) {
    const nodeStart = Math.max(0, note.startIndex - start);
    const nodeEnd = Math.min(text.length, note.endIndex - start);

    if (nodeStart >= nodeEnd) continue;
    console.log(`处理节点: "${text}" (${start}-${end})`);
    console.log(`节点高亮范围: ${nodeStart}-${nodeEnd}`);

    // 创建范围并高亮
    const range = document.createRange();
    range.setStart(node, nodeStart);
    range.setEnd(node, nodeEnd);
    highlights.push({
      range,
      className: `highlight-${note.className}`,
      id: note.divId,
    });
  }

  // 按位置从后往前高亮（避免位置偏移）
  highlights.sort((a, b) => b.range.startOffset - a.range.startOffset);
  for (const { range, className, id } of highlights) {
    // 创建高亮元素
    const span = document.createElement("span");
    span.className = className;
    // 添加笔记ID到data属性
    span.dataset.noteId = id;
    // 插入高亮内容
    span.appendChild(range.extractContents());
    range.insertNode(span);
  }
};

创建高亮元素并插入内容：

高亮前：

高亮后：

选中操作

复制

if (!note?.selectedText) return;
navigator.clipboard.writeText(note.selectedText);
toast.success("已复制到剪贴板");

报错提示：Uncaught TypeError: Cannot read properties of undefined (reading 'writeText')

报错原因：navigator.clipboard.writeText() 方法需要浏览器支持，才能正常执行。浏览器会禁用非安全域(http)的 navigator.clipboard 对象，而在 localhost、https 下不会禁用。

【节点】[Ceiling节点]原理解析与实际应用

掘金前端

作者 SmalBox

2026年5月6日 16:18

【Unity Shader Graph 使用与特效实现】专栏-直达

在Unity URP Shader Graph中，Ceiling节点是一个重要的数学运算节点，它执行向上取整操作。这个节点在着色器编程中具有广泛的应用场景，特别是在需要将连续值转换为离散整数值的情况下。Ceiling节点的功能类似于编程语言中的ceil()函数，它能够将输入的浮点数值向上舍入到最接近的整数。

Ceiling节点在Shader Graph中属于数学运算类别，它接受任意维度的矢量输入，并返回相同维度的矢量输出。这意味着它可以处理从单个浮点数到四维矢量的各种数据类型，为着色器开发提供了极大的灵活性。

理解Ceiling节点的工作原理和应用场景对于创建高质量的着色器效果至关重要。无论是创建像素化效果、实现网格对齐，还是进行数值离散化处理，Ceiling节点都能提供精确的数学运算支持。

描述

Ceiling节点的核心功能是执行向上取整运算。具体来说，对于输入的任意浮点数值，Ceiling节点会返回大于或等于该值的最小整数。这个操作在数学上称为"天花板函数"，因为它总是将数值向上取整到最近的整数值。

向上取整操作与向下取整（Floor）和四舍五入（Round）操作有着明显的区别。向下取整总是向负无穷方向取整，而四舍五入则根据小数部分的值决定向上或向下取整。Ceiling节点的行为则始终向上取整，无论小数部分的大小如何。

在Shader Graph中，Ceiling节点能够处理各种数据类型的输入，包括：

浮点数（Float）
二维矢量（Vector2）
三维矢量（Vector3）
四维矢量（Vector4）

当输入是多维矢量时，Ceiling节点会对每个分量独立执行向上取整操作。例如，对于输入值(1.2, 2.7, 3.0, 4.9)，Ceiling节点将返回(2.0, 3.0, 3.0, 5.0)。

Ceiling节点在图形渲染中有多种应用场景。在创建像素化效果时，可以使用Ceiling节点将连续的UV坐标转换为离散的网格坐标。在实现材质平铺时，Ceiling节点可以帮助确保纹理正确对齐。在光照计算中，Ceiling节点可以用于创建离散的光照级别，实现卡通风格的渲染效果。

需要注意的是，Ceiling节点的性能开销相对较小，因为它执行的是简单的数学运算。在大多数现代GPU上，向上取整操作都能高效执行，不会对渲染性能造成显著影响。

端口

Ceiling节点的端口设计简洁而高效，遵循了Shader Graph节点设计的一致性原则。节点包含一个输入端口和一个输出端口，两者都支持动态矢量类型，这意味着它们可以自动适应连接的数据类型。

输入端口

输入端口名为"In"，是Ceiling节点接收数据的入口。这个端口具有以下特性：

方向：输入
类型：动态矢量
功能描述：接收需要执行向上取整操作的值

输入端口支持的数据类型包括：

Float：单精度浮点数
Vector 2：包含两个浮点数的二维矢量
Vector 3：包含三个浮点数的三维矢量
Vector 4：包含四个浮点数的四维矢量

当连接不同维度的数据时，Shader Graph会自动进行类型转换和适配。例如，如果将一个浮点数连接到期望Vector4的端口，系统会自动将浮点数扩展为四个分量相同的Vector4。

输入值的范围没有特定限制，Ceiling节点可以处理任意大小的浮点数值，包括正数、负数和零。对于特殊值如无穷大和NaN（非数字），Ceiling节点的行为遵循IEEE浮点数标准的规定。

输出端口

输出端口名为"Out"，是Ceiling节点返回计算结果的出口。这个端口具有以下特性：

方向：输出
类型：动态矢量
功能描述：输出向上取整后的结果值

输出端口的数据类型始终与输入端口保持一致。如果输入是Vector3类型，输出也会是Vector3类型，其中每个分量都经过了独立的向上取整处理。

输出值的特性包括：

所有输出分量都是整数值
输出值大于或等于对应的输入值
输出值与输入值的差小于1

在实际使用中，输出端口可以连接到其他节点的输入端口，形成复杂的着色器计算流水线。由于输出值是整数，它们特别适合用作纹理数组的索引、循环计数器或条件判断的基准值。

端口连接示例

理解端口之间的连接方式对于有效使用Ceiling节点至关重要。以下是一些常见的连接模式：

将UV坐标连接到In端口，然后使用Out端口驱动纹理采样，可以创建像素化效果
将世界空间位置连接到In端口，然后使用Out端口计算网格对齐，可以实现体素化渲染
将时间变量连接到In端口，然后使用Out端口创建离散的时间间隔，可以实现帧动画效果

端口连接的灵活性使得Ceiling节点能够适应各种复杂的着色器需求，从简单的数学运算到复杂的视觉效果生成。

生成的代码示例

当在Shader Graph中使用Ceiling节点时，Unity会在生成的着色器代码中插入相应的函数调用。理解这些生成的代码对于调试和优化着色器非常重要。

以下是Ceiling节点生成的典型HLSL代码：

HLSL

void Unity_Ceiling_float4(float4 In, out float4 Out)
{
    Out = ceil(In);
}

这个函数接受一个float4类型的输入参数In，计算其向上取整值，并通过输出参数Out返回结果。函数内部调用了HLSL内置的ceil()函数，这是DirectX着色器语言标准的一部分。

代码结构分析

生成的代码遵循了Unity Shader Graph的标准模式：

函数名采用Unity_前缀，后跟节点名称和数据类型
输入参数使用值传递方式
输出参数使用out关键字，表示通过引用返回结果
函数体简洁明了，直接调用相应的数学函数

对于不同的输入数据类型，Unity会生成相应的函数变体：

HLSL

// 浮点数版本
void Unity_Ceiling_float(float In, out float Out)
{
    Out = ceil(In);
}

// 二维矢量版本
void Unity_Ceiling_float2(float2 In, out float2 Out)
{
    Out = ceil(In);
}

// 三维矢量版本
void Unity_Ceiling_float3(float3 In, out float3 Out)
{
    Out = ceil(In);
}

性能考虑

从生成的代码可以看出，Ceiling节点的执行效率很高：

直接映射到GPU的硬件指令
没有复杂的控制流或条件判断
支持矢量化操作，能够并行处理多个分量

在大多数现代GPU架构上，ceil()函数通常能在单个时钟周期内完成，这使得Ceiling节点成为着色器中性价比很高的数学运算工具。

自定义实现

虽然Unity会自动生成Ceiling节点的代码，但了解其实现原理有助于在需要时创建自定义版本。以下是一个功能等效的自定义实现：

HLSL

float4 CustomCeiling(float4 value)
{
    return floor(value) + 1.0 - step(frac(value), 0.0);
}

这个实现使用了floor()函数和frac()函数来模拟向上取整的行为，虽然不如内置的ceil()函数高效，但展示了向上取整操作的数学原理。

理解生成的代码还有助于在不同渲染管线之间移植着色器。例如，如果要将使用Ceiling节点的着色器从URP迁移到HDRP，或者适配不同的图形API，了解底层的HLSL代码会大大简化迁移过程。

实际应用案例

Ceiling节点在实际着色器开发中有着广泛的应用。以下是一些具体的应用场景和实现方法，展示了如何充分利用Ceiling节点创建各种视觉效果。

像素化效果实现

像素化效果是Ceiling节点的经典应用场景。通过将连续的UV坐标离散化，可以创建出复古的像素艺术风格：

HLSL

// 创建像素化UV坐标
float2 pixelatedUV = ceil(uv * pixelCount) / pixelCount;

在这种应用中，Ceiling节点确保每个像素区域内的所有点都映射到同一个离散坐标，从而创建出清晰的像素边界。调整pixelCount参数可以控制像素化程度，数值越大，像素越细小。

网格对齐和瓦片处理

在创建瓦片地图或网格基础的效果时，Ceiling节点可以确保物体正确对齐到网格：

HLSL

// 将世界坐标对齐到网格
float3 gridAlignedPosition = ceil(worldPosition * gridSize) / gridSize;

这种方法特别适用于：

体素游戏的渲染
策略游戏的网格移动
建筑可视化中的对齐显示

离散化动画控制

Ceiling节点可以用于创建离散的时间间隔，实现帧动画效果：

HLSL

// 创建离散化的时间索引
float frameIndex = ceil(time * framesPerSecond);

这种技术适用于：

精灵动画（Sprite Animation）
帧动画序列
定时触发的特效

光照和阴影处理

在 stylized 渲染中，Ceiling节点可以用于创建离散的光照级别：

HLSL

// 创建离散化光照值
float discreteLighting = ceil(dot(N, L) * lightLevels) / lightLevels;

这种方法可以创建出卡通风格的光照效果，其中光照过渡是阶梯状的而不是平滑的。

高级数学运算

Ceiling节点还可以与其他数学节点结合，实现更复杂的数学运算：

HLSL

// 计算向上取整的除法
float ceilDivision = ceil(dividend / divisor);

// 创建数值分箱（Binning）
float binnedValue = ceil(value * binCount) / binCount;

这些高级应用展示了Ceiling节点在数值处理和数据分析方面的潜力。

最佳实践和注意事项

为了充分发挥Ceiling节点的潜力，同时避免常见的陷阱，以下是一些最佳实践和注意事项。

性能优化

虽然Ceiling节点本身性能开销很小，但在大规模使用时仍需注意：

避免在片段着色器中过度使用复杂的Ceiling操作链
考虑将计算转移到顶点着色器或计算着色器中
利用矢量化操作，一次性处理多个分量

数值精度考虑

在使用Ceiling节点时，需要注意浮点数精度问题：

对于极大或极小的数值，可能会出现精度损失
在比较Ceiling结果时，使用适当的容差值
注意不同GPU架构可能存在的精度差异

与其他节点的配合

Ceiling节点通常与其他数学节点配合使用：

与Floor节点结合，可以创建数值范围限制
与Frac节点结合，可以分离数值的整数和小数部分
与Round节点结合，可以实现不同的取整策略

调试技巧

当Ceiling节点行为不符合预期时，可以采取以下调试措施：

使用Position节点可视化输出结果
通过Divide节点缩放输出值，使其在可视范围内
使用Custom Function节点插入调试输出

平台兼容性

Ceiling节点在大多数平台上都有良好的兼容性，但仍需注意：

确保目标平台支持所需的精度级别
在移动平台上测试性能表现
验证在不同图形API下的行为一致性

【Unity Shader Graph 使用与特效实现】专栏-直达 （欢迎点赞留言探讨，更多人加入进来能更加完善这个探索的过程，🙏）

普通视图

前言

为什么要使用位运算来设计依赖优化？

普通实现方案

位运算优化方案（Vue3 实现）

组件嵌套的 effect 实现原理

依赖标记流程

初始化依赖的追踪状态标记

通过位运算判断是否收集依赖

实现动态依赖精准管理

递归层级限制30层的设计原因

SMI（Small Integer）优化的核心原理

指针的结构

SMI 的存储方式

内存访问开销

内存分配开销

CPU 缓存友好性

指令优化

设计哲学

总结

App 开发者

插件开发者

题外话

引言

什么是 Composition API？

对比：Options API vs Composition API

核心 API 详解

1. ref() - 响应式基础类型

2. reactive() - 响应式对象

3. computed() - 计算属性

4. watch() 和 watchEffect()

5. 生命周期钩子

逻辑复用：组合式函数

示例：useCounter

示例：useFetch

实际应用场景

1. 表单处理

2. 响应式路由

最佳实践

1. 逻辑组织

2. 使用 <script setup>

3. 类型推导

总结

先说结论

Bun 怎么来的：一次“忍不了”

两个关键选择，决定了 Bun 的一切

选择一：用 Zig，不是 Rust

选择二：JavaScriptCore，不是 V8

Bun 的版本演化：从“能跑 demo”到“被 Anthropic 收购”

第一阶段：萌芽期（2021-2022.7）

第二阶段：品牌爆发期（2022.7-2023.9）

第三阶段：平台化与兼容攻坚期（2023.9-2025.10）

Bun 1.0（2023.9.8）：第一次完成产品定义

Bun 1.1（2024.4.1）：补上 Windows，从明星项目走向平台项目

Bun 1.2（2025.1.22）：方法论升级

Bun 1.3（2025.10.10）：从 runtime 推向 full-stack substrate

第四阶段：AI 基础设施绑定期（2025.12 至今）

被 Anthropic 收购

2026 年：继续打磨底层

竞争格局：Bun vs Node vs Deno

Bun vs Node.js

Bun vs Deno

Bun vs 传统工具链

Bun 的优势和劣势，都来自同一个源头

未来会怎样？

最可能：外围切入，向中心渗透

最危险：功能扩张但质量跟不上

最乐观：AI 时代的默认 JS 执行层

写在最后

参考来源

目录

第一章：为什么性能优化很重要

1.1 用数据说话：性能与业务的直接关联

1.2 搜索引擎排名的硬性要求

1.3 用户体验的心理学

1.4 前端性能的三个维度

第二章：Web 性能指标全景

2.1 Core Web Vitals：最重要的三个指标

LCP（Largest Contentful Paint，最大内容绘制）

INP（Interaction to Next Paint，与下一次绘制的交互）

2. 使用 `<script setup>`

技术二：使用 `<link rel="preload">` 预加载