原文：How to Create a CSS-only Elastic Text Effect

翻译：TUARAN

欢迎关注 前端周刊，每周更新国外论坛的前端热门文章，紧跟时事，掌握前端技术动态。

每个字母单独动画的文字效果总是很酷、很吸睛。这类错峰动画通常依赖 JavaScript 库实现，对我们要实现的这种相对轻量的设计效果来说，代码往往偏重。本文将探索只用 CSS、无需 JavaScript 实现 fancy 文字效果的技巧（意味着需要手动拆分字符）。

截至撰写时，仅 Chrome 和 Edge 完全支持我们使用的特性。

将鼠标悬停在下方演示的文字上，即可看到效果：

CodePen Embed Fallback

很酷吧？仅靠 CSS 就实现了逼真的弹性效果，而且灵活易调。在深入代码之前，先做一个重要声明。这个效果不错，但有几个明显的缺点。

关于可访问性的重要声明

我们要做的效果依赖于把单词拆成单个字母，一般来说这种做法非常不推荐。

一个简单链接通常是这样写的：

<a href="#">About</a>Code language: HTML, XML (xml)

但要分别控制每个字母的样式，我们会改成这样：

<a href="#">
  <span>A</span><span>b</span><span>o</span><span>u</span><span>t</span>
</a>Code language: HTML, XML (xml)

这会带来可访问性问题。

很容易想到用 aria-* 属性来弥补。至少我之前是这么想的。网上有不少资料推荐类似下面的结构：

<a href="#" aria-label="About">
  <span aria-hidden="true">
    <span>A</span><span>b</span><span>o</span><span>u</span><span>t</span>
  </span>
</a>Code language: HTML, XML (xml)

看起来没问题吧？不！这种结构依然很糟糕。实际上，网上能找到的大多数结构都有问题。我不是这个领域的专家，所以请教了一些人，发现 Adrian Roselli 的两篇博客很有参考价值：

• You Know What? Just Don't Split Words into Letters
• Barriers from Links with ARIA

强烈建议读一读，理解为什么把单词拆成字母是个坏主意（以及可能的替代方案）。

那我为什么还要做这个演示？

我更倾向于把它当作一次探索现代 CSS 特性的实验。这个效果里可能有很多你还不熟悉的属性，是了解它们的好机会。可以用在娱乐或 side project 中，但在广泛使用或关键场景中引入前，请三思。

好了，声明完毕，我们开始。

原理说明

思路是使用 offset() 属性，定义字母沿一条路径运动。这条路径是一条曲线，我们沿曲线做动画。offset() 是一个被低估的特性，但潜力很大，尤其配合现代 CSS 使用时。我曾用它做过无限跑马灯动画、让元素沿圆精确排布、做图片画廊等。

下面是一个简化示例，帮助理解我们要用的技巧：

CodePen Embed Fallback

上面的演示使用了来自 SVG 的 path() 值。三个字母最初沿第一条路径，悬停时切换到第二条路径。借助 transition，就形成了平滑的效果。

可惜的是，使用 SVG 并不理想，因为你只能创建静态、基于像素的路径，无法用 CSS 控制。因此我们将转而使用新的 shape() 函数，它可以定义复杂形状（包括曲线），并方便地用 CSS 控制。

本文只用到 shape() 的简单用法（只需要一条曲线），如果想深入了解这个强大函数，可以参考我之前的文章：

• Better CSS Shapes Using shape()
• Creating Blob Shapes using clip-path: shape()
• Creating Flower Shapes using clip-path: shape()

开始写代码

用到的 HTML：

<ul>
  <li>
    <a href="#"><span>A</span><span>b</span><span>o</span><span>u</span><span>t</span></a>
  </li>
  <!-- 更多 li 元素 -->
</ul>Code language: HTML, XML (xml)

CSS：

ul li a {
  display: flex;
  font-family: monospace;
}
ul li a span {
  offset-path: shape(???);
  offset-distance: ???;
}
ul li a:hover {
  offset-path: shape(???);
}Code language: CSS (css)

目前还比较朴素

CodePen Embed Fallback

用 flex 让字母并排，并用等宽字体，确保每个字母宽度一致。

接下来用下面的代码定义路径：

offset-path: shape(from Xa Ya, curve to Xb Yb with Xc Yc / Xd Yd );Code language: CSS (css)

这里用 curve 命令在 A 到 B 之间画贝塞尔曲线，控制点为 C 和 D。

然后通过调整控制点的坐标（尤其是 Y 值）来驱动曲线动画。当 Y 与 A、B 的 Y 相同时是直线；更大时变成曲线。

曲线的代码大致如下：

offset-path: shape(from Xa Y, curve to Xb Y with Xc Y1 / Xd Y1);

直线的代码如下：

offset-path: shape(from Xa Y, curve to Xb Y with Xc Y / Xd Y);

注意我们只改控制点的 Y，其他保持不变。

现在来确定各参数。使用 offset 时有两个要点：

1. 默认以元素中心作为在路径上的位置。
2. 定义在子元素上，但参考框是父容器。

第一个字母应在路径起点，最后一个在终点，所以 A 是第一个字母中心，B 是最后一个字母中心：

Y = 50%Xa = .5chXb = 100% - Xa = 100% - .5ch

C 和 D 的 X 没有固定规则，可以任意指定。我选 Xc = 30%，Xd = 100% - Xc = 70%。你可以自己调整这些值试验不同的曲线形态。

路径现在可以这样写：

offset-path: shape(from .5ch 50%, curve to calc(100% - .5ch) 50% with 30% Y / 70% Y);

Y 是变量，可以是 50%（与 A、B 相同）或别的值，我们设成 50% - H。H 越大，弹性越强。

试试看：

CodePen Embed Fallback

一团糟！因为我们没定义 offset-distance，所有字母都叠在一起了。

是不是要给每个字母单独设位置？那太麻烦了。

我们必须给每个字母不同的位置，好在可以用一个公式配合 sibling-index() 和 sibling-count() 搞定。

第一个字母在 0%，最后一个在 100%。共 N 个字母，步长为 100%/(N - 1)，字母从 0% 到 100% 依次排布，公式为：

offset-distance: (100% * i)/(N - 1)

其中 i 从 0 开始。

写成 CSS：

offset-distance: calc(100%*(sibling-index() - 1)/(sibling-count() - 1))Code language: CSS (css)

CodePen Embed Fallback

几乎完美。除了最后一个字母外都位置正确。由于某种原因，0% 和 100% 被当成同一个点。offset-distance 不限于 0%–100%，可以取任意值（包括负值），有一种取模行为形成环路。你可以从 0% 到 100% 走完整条路径，到 100% 后又回到起点，还能继续从 100% 到 200%，如此往复。

虽然有点反直觉，但修复很简单：把 100% 换成 99.9%。有点 hack，但有效！

CodePen Embed Fallback

现在排布完美了，悬停时可以看到直线变成曲线的过程。

最后加上 transition，就大功告成！

CodePen Embed Fallback

可能还不算完全搞定，因为动画似乎有些异常。这很可能是 bug（我已在此提交），不过问题不大，因为我本来就打算重构，避免重复写两次 shape，改为动画一个变量：

@property --_s {
  syntax: "<number>";
  initial-value: 0;
  inherits: true;
}
ul li a {
  --h: 20px; /* 控制效果强度 */
 
  display: flex;
  font: bold 40px monospace;
  transition: --_s .3s;
}
ul li a:hover {
  --_s: 1;
}
ul li a span {
  offset-path: 
    shape(
      from .5ch 50%, curve to calc(100% - .5ch) 50% 
      with 30% calc(50% - var(--_s)*var(--h)) / 70% calc(50% - var(--_s)*var(--h))
    );
  offset-distance: calc(99.9%*(sibling-index() - 1)/(sibling-count() - 1));
}Code language: CSS (css)

现在有了 --h 变量来调节路径曲率，以及一个内部变量在 0 到 1 之间动画，实现从直线到曲线的过渡。

CodePen Embed Fallback

嗒哒！动画完美了！但弹性感呢？

要得到弹性效果，需要调整缓动，用到 linear()。这是最简单的部分，我用生成器生成取值。

多调几次直到满意。我得到的是：

CodePen Embed Fallback

效果已经不错，但如果微调曲线还能更好。目前所有单词的曲线「高度」是一样的，理想情况是根据单词长度变化。为此我会在公式里加入 sibling-count()，让单词越宽时高度越大。

CodePen Embed Fallback

让效果具备方向感知

效果已经可用，但既然做到这里，不妨再进一步：根据鼠标方向决定曲线向上还是向下。

向上的曲线已经通过 --_s: 1 实现：

ul li a:hover {
  --_s: 1;
}Code language: CSS (css)

若改为 -1，就得到向下的曲线：

CodePen Embed Fallback

现在需要把两种情况结合起来。从上方悬停时，使用向下曲线 --_s: -1；从下方悬停时，使用向上曲线 --_s: 1。

首先给 li 加一个伪元素，填满上半部分并位于链接上方：

ul li {
  position: relative;
}
ul li:after {
  content: "";
  position: absolute;
  inset: 0 0 50%;
  cursor: pointer;
}Code language: CSS (css)

CodePen Embed Fallback

然后定义两个不同的选择器。当悬停伪元素时，相当于也悬停了 li，所以可以用：

ul li:hover a {
  --_s: -1;
}Code language: CSS (css)

悬停 a 时，同样会悬停 li，上面的规则也会生效。但若悬停的是伪元素，则没有悬停 a，因此可以用：

ul li:has(a:hover) a {
  --_s: 1;
}Code language: CSS (css)

有点绕？没关系，我们把两个选择器放在一起看：

ul li:hover a {
  --_s: -1;
}
ul li:has(a:hover) a {
  --_s: 1;
}Code language: CSS (css)

我们可以从上方（通过伪元素）或从下方（通过 a）悬停。前者会触发第一个选择器，因为我们在悬停 li，但不会触发第二个，因为 li「并没有悬停其 a」。当我们悬停 a 时，两个选择器都会触发，后者会胜出。

方向感知就这么实现了！

CodePen Embed Fallback

能用，但不如开头的演示那么流畅。当鼠标移动穿过整个元素时，会突然停止一个动画并切换到另一个。

可以调整伪元素的大小来改善。悬停时让它覆盖整个元素，这样就不会再触达下方的 a，第二个动画就不会触发。而悬停 a 时，把伪元素高度设为 0，就无法悬停它，从而不会触发第一个动画。

CodePen Embed Fallback

好多了！把伪元素设为透明，效果就很自然。

CodePen Embed Fallback

小结

希望你喜欢这次 CSS 小实验。再提醒一次：在项目中投入使用前请三思。这是一个很好的 demos 来了解 shape()、linear()、sibling-index() 等现代特性，但为这类效果牺牲可访问性并不值得。

Vue 底层原理 & 新特性

本文深入探讨 Vue 的底层架构演进、核心原理以及最新版本带来的突破性特性，面向面试和技术提升。

原文地址

墨渊书肆/Vue 底层原理 & 新特性

Vue 版本变动历史

Vue 自发布以来经历了多个重要版本的迭代，每个版本的改动都带来了架构优化和新特性，同时也伴随着一些 Breaking Changes。以下是 Vue 各个重要版本的变动概述：

Vue 2.0 (2016年)

• 引入 Virtual DOM：Vue2 正式引入了虚拟 DOM，这是框架性能提升的关键技术。
• 组件系统增强：增加了异步组件、生命周期钩子调整等特性。
• 支持 SSR：原生支持服务器端渲染，提升了 SEO 和首屏加载性能。
• Vuex 与 Vue Router：作为官方解决方案提供状态管理和路由管理。

Vue 2.5 - 2.7 (2017-2022年)

• Vue 2.5：改进了 TypeScript 支持，增强了响应式系统。
• Vue 2.6：引入了新的模板编译策略，插槽语法改进。
• Vue 2.7：作为 Vue2 最后的大版本，引入了一些 Composition API 的向下兼容实现，为 Vue3 迁移做铺垫。

Vue 3.0 (2022年)

• Composition API：引入了全新的组合式 API，提供了更灵活的逻辑组织方式。
• Proxy 响应式系统：使用 Proxy 替代 Object.defineProperty，解决了 Vue2 响应式的诸多痛点。
• Teleport & Fragments：新增内置组件，支持跨 DOM 层级渲染和多根节点模板。
• 性能提升：更快的解析速度和更小的运行时体积，渲染性能提升约 100%。
• 更好的 TypeScript 支持：原生支持 TypeScript，类型推导更加完善。
• 自定义渲染器 API：增强的渲染器 API，便于跨平台开发。

Vue 3.1 - 3.4 (2023-2024年)

• Vue 3.1：引入了 defineOptions 宏，改进编译优化。
• Vue 3.3：进一步改进宏支持，类型化 props/emits 更加方便，简化了泛型组件的使用。
• Vue 3.4：性能进一步提升，响应式系统优化，编译器效率改进。

Vue 3.5 及未来 (2024-2025年)

• Vue 3.5：引入了响应式解构语法（Reactivity Transform），改善了大型应用的开发体验。
• Vapor Mode：Vue 团队正在实验的全新渲染策略，跳过虚拟 DOM直接生成高效的 JavaScript 代码。
• 更完善的生态集成：与 Vite 5、Pinia、Vue Router 4 的深度整合。

响应式原理深度解析

响应式系统是 Vue 的核心，也是面试中的高频考点。Vue2 和 Vue3 在响应式实现上有着本质的区别。

Vue2：Object.defineProperty

Vue2 使用 Object.defineProperty 来劫持数据的 getter 和 setter：

function defineReactive(obj, key, val) {
  // 为每个属性创建 Dep 实例
  const dep = new Dep()
  
  Object.defineProperty(obj, key, {
    enumerable: true,
    configurable: true,
    get: function reactiveGetter() {
      // 依赖收集
      if (Dep.target) {
        dep.depend()
      }
      return val
    },
    set: function reactiveSetter(newVal) {
      if (newVal === val) return
      // 通知更新
      dep.notify()
    }
  })
}

Vue2 响应式的局限性：

1. 无法检测对象属性的添加/删除：Object.defineProperty 只能劫持已存在的属性，对于新增属性无能为力。
2. 数组操作无法响应：通过下标修改数组元素 arr[0] = value 不会触发更新。
3. 深层监听需要递归：对深层对象的监听会带来性能开销。

解决方案：Vue2 提供了 Vue.set / Vue.delete 以及重写数组方法来应对这些场景。

Vue3：Proxy

Vue3 使用 ES6 的 Proxy 来实现响应式：

function reactive(target) {
  return new Proxy(target, {
    get(target, key, receiver) {
      // 依赖收集
      track(target, key)
      const result = Reflect.get(target, key, receiver)
      // 如果是对象，递归代理实现深层响应式
      return isObject(result) ? reactive(result) : result
    },
    set(target, key, value, receiver) {
      const result = Reflect.set(target, key, value, receiver)
      // 触发更新
      trigger(target, key)
      return result
    },
    deleteProperty(target, key) {
      const result = Reflect.deleteProperty(target, key)
      trigger(target, key)
      return result
    }
  })
}

Vue3 响应式的优势：

1. 原生支持属性增删：Proxy 可以拦截对象的所有操作，包括新增和删除属性。
2. 数组操作完全响应：下标赋值、数组长度变化等都能被正确拦截。
3. 更好的性能：Proxy 是懒执行的，只有当访问属性时才会进行依赖收集。
4. API 统一：ref 和 reactive 内部实现统一，简化了学习成本。

依赖收集与触发机制

Vue 的响应式系统遵循观察者模式，包含三个核心角色：

1. Observer（观察者）：负责劫持数据，收集依赖。
2. Dep（依赖管理器）：存储依赖，管理订阅者。
3. Watcher（订阅者）：在数据变化时执行更新回调。

// Dep 实现
class Dep {
  constructor() {
    this.subs = new Set() // 存储 Watcher
  }
  
  depend() {
    if (Dep.target) {
      this.subs.add(Dep.target)
    }
  }
  
  notify() {
    this.subs.forEach(watcher => watcher.update())
  }
}

// Watcher 实现
class Watcher {
  constructor(fn) {
    this.getter = fn
    this.value = this.get()
  }
  
  get() {
    Dep.target = this
    const value = this.getter()
    Dep.target = null
    return value
  }
  
  update() {
    this.value = this.getter()
  }
}

模板编译原理

Vue 的模板编译是将模板字符串转换为可执行渲染函数的过程，主要分为三个阶段。

1. 解析阶段（Parse）

将模板字符串解析为 AST（抽象语法树）：

// 模板
<div class="container">
  <h1>{{ title }}</h1>
</div>

// AST 结构
{
  type: 'Element',
  tag: 'div',
  props: [{ type: 'Attribute', name: 'class', value: 'container' }],
  children: [
    {
      type: 'Element',
      tag: 'h1',
      children: [{ type: 'Interpolation', content: { expression: 'title' } }]
    }
  ]
}

2. 优化阶段（Optimize）

Vue3 的编译器会进行静态节点提升（Static Hoisting）：

• 静态节点：不包含任何响应式依赖的节点（如纯文本、静态属性）。
• 事件缓存：对于不响应式变化的事件处理函数，进行缓存处理。

// 优化前
render() {
  return h('button', { onClick: this.handleClick }, 'Click')
}

// 优化后 - 事件函数被缓存
const handleClick = this.handleClick
render() {
  return h('button', { onClick: handleClick }, 'Click')
}

3. 代码生成阶段（Generate）

将 AST 转换为渲染函数：

// 生成的渲染函数
function render() {
  return _vue.createVNode('div', { class: 'container' }, [
    _vue.createVNode('h1', null, _vue.toDisplayString(this.title))
  ])
}

虚拟 DOM 与 Diff 算法

虚拟 DOM 的本质

虚拟 DOM 是真实 DOM 的 JavaScript 对象表示：

// VNode 结构
const vnode = {
  type: 'div',
  props: { class: 'container' },
  children: [
    { type: 'h1', children: 'Hello' }
  ],
  el: null // 关联的真实 DOM 引用
}

虚拟 DOM 的优势：

1. 跨平台渲染：同一套 VNode 结构可以渲染到不同平台。
2. 减少 DOM 操作：在内存中进行对比，只更新必要的真实 DOM。
3. 声明式开发：开发者只需关注数据变化，框架自动处理 DOM 更新。

Vue2 Diff：单端比较

Vue2 采用传统的 Diff 算法，从左到右依次对比：

function updateChildren(oldChildren, newChildren) {
  let oldStartIndex = 0
  let newStartIndex = 0
  let oldEndIndex = oldChildren.length - 1
  let newEndIndex = newChildren.length - 1
  
  while (oldStartIndex <= oldEndIndex && newStartIndex <= newEndIndex) {
    // 简单比较...O(n) 复杂度
  }
}

Vue3 Diff：双端比较 + 最长递增子序列

Vue3 采用了更高效的 Diff 算法：

1. 双端比较：同时从新旧列表的首尾进行对比。
2. key 映射：通过 Map 快速定位相同 key 的节点。
3. 最长递增子序列：对于需要移动的节点，使用 LIS 算法最小化移动次数。

// Vue3 Diff 核心逻辑
function diffChildren(n1, n2, parent) {
  const c1 = n1.children
  const c2 = n2.children
  const oldStart = 0
  const newStart = 0
  const oldEnd = c1.length - 1
  const newEnd = c2.length - 1
  
  // 双端比较策略
  while (oldStart <= oldEnd && newStart <= newEnd) {
    if (c1[oldStart].key === c2[newStart].key) {
      // 节点相同，继续
      patch(c1[oldStart], c2[newStart], parent)
      oldStart++
      newStart++
    } else if (c1[oldEnd].key === c2[newEnd].key) {
      // 尾部匹配
      patch(c1[oldEnd], c2[newEnd], parent)
      oldEnd--
      newEnd--
    }
    // ... 更多比较策略
  }
}

组件生命周期与更新机制

Vue2 生命周期

Vue3 生命周期

组件更新流程

数据变化 → 触发 setter → Dep 通知 Watcher → 
触发 update() → 重新执行 render() 生成新的 VNode → 
Diff 对比 → 更新真实 DOM

Vue3 新特性深度解析

1. Composition API

组合式 API 是 Vue3 最重要的变化，提供了更灵活的逻辑组织方式：

// setup 函数 - 组件逻辑入口
import { ref, computed, onMounted, watch } from 'vue'

export default {
  setup() {
    const count = ref(0)
    const doubled = computed(() => count.value * 2)
    
    function increment() {
      count.value++
    }
    
    onMounted(() => {
      console.log('Component mounted!')
    })
    
    watch(count, (newVal) => {
      console.log(`Count changed to ${newVal}`)
    })
    
    return { count, doubled, increment }
  }
}

ref vs reactive：

• ref：用于原始类型，创建包含 .value 的响应式对象。
• reactive：用于对象，创建深层响应式对象。

import { ref, reactive } from 'vue'

const count = ref(0)        // 原始类型
const state = reactive({   // 对象类型
  user: { name: 'Vue' }
})

// 模板中自动解包
console.log(count.value)   // JS 中需要 .value
console.log(state.user)    // reactive 直接访问

2. Teleport

将组件渲染到指定 DOM 位置，常用于模态框：

<Teleport to="body">
  <div v-if="show" class="modal">
    <p>Modal Content</p>
  </div>
</Teleport>

3. Fragments

支持多根节点模板：

<!-- Vue3 允许 -->
<template>
  <div>A</div>
  <div>B</div>
</template>

4. Suspense

处理异步组件加载状态：

<Suspense>
  <template #default>
    <AsyncComponent />
  </template>
  <template #fallback>
    Loading...
  </template>
</Suspense>

Vue vs React：核心差异对比

响应式实现

模板 vs JSX

• Vue：模板语法，HTML-like，学习成本低，编译器优化。
• React：JSX，JavaScript 表达式，更灵活，但需要一定学习曲线。

状态管理

• Vue：Pinia（推荐）或 Vuex，采用模块化设计。
• React：Redux/Zustand/Jotai，函数式风格。

渲染性能

Vue3 由于模板编译优化和 Proxy 响应式，在大多数场景下性能优于 React。React 的优势在于 Fiber 架构带来的精细化控制和并发渲染能力。

性能优化策略

1. 渲染优化

// 使用 v-once 静态内容
<div v-once>{{ staticContent }}</div>

// 正确使用 key
<li v-for="item in items" :key="item.id">{{ item.name }}</li>

// v-if vs v-show 选择
<div v-if="show">很少切换</div>
<div v-show="show">频繁切换</div>

2. 响应式优化

import { shallowRef, markRaw } from 'vue'

// 浅层响应式 - 适合大型数据
const largeList = shallowRef([])

// 非响应式数据 - 适合不需要响应式的对象
const plainObj = markRaw({ /* ... */ })

3. 组件懒加载

// 路由懒加载
const Home = () => import('./views/Home.vue')

// 异步组件
import { defineAsyncComponent } from 'vue'
const AsyncComp = defineAsyncComponent(() => import('./AsyncComp.vue'))

4. KeepAlive 缓存

<KeepAlive include="Home,About">
  <router-view />
</KeepAlive>

面试常见问题汇总

1. Vue2 和 Vue3 响应式的区别？

Vue2 使用 Object.defineProperty，需要递归监听所有属性，无法检测新增/删除属性；Vue3 使用 Proxy，原生支持属性增删，性能更好。

2. Vue 的依赖收集是如何实现的？

通过 Dep 类管理订阅者，Watcher 在读取响应式属性时将自身添加到 Dep，属性变化时 Dep 通知所有 Watcher 更新。

3. Vue3 Diff 算法相比 Vue2 有什么优化？

Vue3 采用 双端比较 策略，结合 最长递增子序列 算法，最小化 DOM 移动次数，复杂度从 O(n³) 优化到 O(n)。

4. Vue3 的 Composition API 有什么优势？

• 更好的 TypeScript 支持
• 代码更容易复用和抽取
• 逻辑相关代码组织在一起，而不是按选项分散

5. Vue3 的性能为什么比 Vue2 好？

• Proxy 替代 Object.defineProperty，深层监听懒执行
• 模板编译优化：静态节点提升、事件缓存
• 优化的 Diff 算法
• 更小的打包体积

6. Vue 的 nextTick 原理？

Vue 使用 Promise + MutationObserver + setTimeout 实现异步队列，在 DOM 更新后通过微任务执行回调。

7. keep-alive 的实现原理？

通过缓存 VNode，保存组件实例和状态，切换时复用而非重新创建。activated/deactivated 钩子用于感知缓存状态变化。

8. Vue 的模板编译过程？

解析 → 优化（静态节点提升）→ 代码生成（渲染函数）

总结

Vue 作为一个渐进式框架，在保持易用性的同时不断深化底层技术的实现。Vue3 通过 Composition API、Proxy 响应式系统、优化的 Diff 算法等特性，显著提升了开发体验和运行性能。理解这些底层原理不仅有助于应对面试，更能在实际开发中做出更好的技术决策。

Vue 团队正在探索的 Vapor Mode 未来可能带来更大的性能突破，值得持续关注。

Vue 基础理论 & API 使用

本文主要记录 Vue 的基础理论、核心概念与常用 API 使用方法，面向面试和日常开发参考。

原文地址

墨渊书肆/Vue 基础理论 & API 使用

Vue 简介

Vue 是一个渐进式 JavaScript 框架，由尤雨溪于 2014 年创建。Vue 核心库聚焦于视图层，易于学习和集成，同时能够驱动复杂的单页应用程序（SPA）开发。

核心特点：

• 响应式数据绑定 （MVVM 模式）
• 组件化开发
• 虚拟 DOM
• 指令系统
• 渐进式架构

安装与项目创建

Vite（推荐）

# 创建 Vue3 项目
npm create vue@latest

# 或使用 Vite 直接创建
npm create vite@latest my-vue-app -- --template vue

Vue CLI

npm install -g @vue/cli
vue create my-project

基础指令

v-model 双向绑定

v-model 是 Vue 中用于表单输入和数据双向绑定的核心指令，本质是 v-bind + v-on 的语法糖。

基本用法：

<input v-model="message">
<p>{{ message }}</p>

修饰符：

自定义 v-model（Vue 3.4+）：

// 子组件
defineProps(['modelValue'])
defineEmits(['update:modelValue'])

// 父组件
<MyInput v-model:title="title" />

v-if / v-show 条件渲染

<div v-if="type === 'A'">A</div>
<div v-else-if="type === 'B'">B</div>
<div v-else>C</div>

v-for 列表渲染

<li v-for="(item, index) in items" :key="item.id">
  {{ index }} - {{ item.name }}
</li>

注意事项：

• 必须使用 :key 绑定唯一标识
• 不建议使用数组索引作为 key
• Vue2 中 v-for 优先级高于 v-if，Vue3 中相反

v-bind / v-on 属性与事件

<!-- 绑定属性 -->
<img :src="url">

<!-- 绑定多个属性 -->
<img v-bind="attrs">

<!-- 事件监听 -->
<button @click="handleClick">Click</button>

<!-- 事件修饰符 -->
<button @click.stop="handle">阻止冒泡</button>
<button @click.prevent="handle">阻止默认行为</button>

组件选项

data

组件的响应式数据源，必须返回纯对象：

export default {
  data() {
    return {
      count: 0,
      user: { name: 'Vue' }
    }
  }
}

props

父子组件通信的重要方式，支持类型校验和默认值：

export default {
  props: {
    // 基础类型
    title: String,
    // 多个类型
    age: [Number, String],
    // 带默认值
    size: {
      type: String,
      default: 'medium'
    },
    // 必需
    id: {
      type: Number,
      required: true
    },
    // 自定义校验
    score: {
      validator: (value) => value >= 0 && value <= 100
    }
  }
}

Vue3 组合式 API：

const props = defineProps({
  title: String,
  count: { type: Number, default: 0 }
})

computed 计算属性

缓存计算结果，只在依赖变化时重新计算：

export default {
  data() { return { count: 1 } },
  computed: {
    // 只读
    doubled() { return this.count * 2 },
    // 可写
    plusOne: {
      get() { return this.count + 1 },
      set(val) { this.count = val - 1 }
    }
  }
}

methods 方法

处理业务逻辑，每次渲染都会重新创建：

export default {
  methods: {
    handleClick() { /* ... */ }
  }
}

watch 监听器

监听数据变化并执行回调：

export default {
  data() { return { count: 0 } },
  watch: {
    count(newVal, oldVal) {
      console.log(`变化: ${oldVal} → ${newVal}`)
    },
    // 深度监听
    'obj.data': {
      handler() { /* ... */ },
      deep: true
    },
    // 立即执行
    name: {
      handler() { /* ... */ },
      immediate: true
    }
  }
}

Composition API

Vue3 引入的组合式 API，提供了更灵活的逻辑组织方式。

ref / reactive 响应式

import { ref, reactive } from 'vue'

// ref - 原始类型
const count = ref(0)
count.value++

// reactive - 对象
const state = reactive({
  user: { name: 'Vue' }
})
state.user.name = 'Vue3'

区别：

| 特性 | ref | reactive | | ----- -| ----- | ---------- | | 适用类型 | 任意类型 | 对象/数组 | | 访问方式 | .value | 直接属性 | | 重新赋值 | 响应式 | 替换整个对象 |

toRefs / toRef

将 reactive 对象解构为独立的 ref：

import { reactive, toRefs } from 'vue'

const state = reactive({ name: 'Vue', age: 25 })
const { name, age } = toRefs(state)

// 或创建单个 ref
const nameRef = toRef(state, 'name')

computed() 计算属性

import { ref, computed } from 'vue'

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

watch / watchEffect

import { ref, watch, watchEffect } from 'vue'

// watch - 显式监听
watch(count, (newVal, oldVal) => { /* ... */ })
watch(() => state.name, (newVal) => { /* ... */ })

// watchEffect - 自动收集依赖
watchEffect(() => {
  console.log(count.value) // 自动追踪
})

执行时机控制：

• watch：默认同步执行
• watchEffect：默认 pre（在组件更新前）
• watchPostEffect：在组件更新后执行
• watchSyncEffect：同步执行

生命周期钩子

import { 
  onMounted, 
  onUpdated, 
  onUnmounted 
} from 'vue'

export default {
  setup() {
    onMounted(() => { console.log('mounted') })
    onUpdated(() => { console.log('updated') })
    onUnmounted(() => { console.log('unmounted') })
  }
}

组件通信

Props / $emit

// 父组件
<Child :count="count" @update="handleUpdate" />

// 子组件
const props = defineProps({ count: Number })
const emit = defineEmits(['update'])
emit('update', props.count + 1)

Provide / Inject

祖先向后代跨级传值：

// 祖先组件
provide('key', 'value')

// 后代组件
const value = inject('key')

响应式：

// 祖先
const count = ref(0)
provide('count', count)

// 后代 - 修改会影响所有后代
const count = inject('count')

$attrs /$attrs/listeners

透传属性和事件：

<!-- 透传所有 -->
<Child v-bind="$attrs" v-on="$listeners" />

Pinia 状态管理

Vue3 推荐的状态管理方案：

import { defineStore } from 'pinia'

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

内置组件

Transition

为元素添加过渡动画：

<Transition name="fade">
  <div v-if="show">Content</div>
</Transition>

.fade-enter-active,
.fade-leave-active {
  transition: opacity 0.3s;
}
.fade-enter-from,
.fade-leave-to {
  opacity: 0;
}

过渡类名：

• v-enter-from / v-leave-from：起始状态
• v-enter-active / v-leave-active：过渡中
• v-enter-to / v-leave-to：结束状态

KeepAlive

缓存组件实例：

<KeepAlive include="A,B" exclude="C">
  <component :is="current" />
</KeepAlive>

生命周期：

• activated：激活时
• deactivated：停用时

Teleport

渲染到指定 DOM 位置：

<Teleport to="#modal-root">
  <div class="modal">Content</div>
</Teleport>

Suspense

处理异步组件（实验性）：

<Suspense>
  <template #default>
    <AsyncComponent />
  </template>
  <template #fallback>
    Loading...
  </template>
</Suspense>

生命周期

Options API

父子组件执行顺序

挂载：父 created → 子 created → 子 mounted → 父 mounted

更新：父 beforeUpdate → 子 beforeUpdate → 子 updated → 父 updated

销毁：父 beforeUnmount → 子 beforeUnmount → 子 unmounted → 父 unmounted

常用技巧

动态类名

<div :class="{ active: isActive, 'text-center': isCenter }">
<div :class="[activeClass, errorClass]">

条件类名

<div :class="[isActive && 'active']">

动态绑定 style

<div :style="{ color: textColor, fontSize: fontSize + 'px' }">

函数式组件

export default {
  functional: true,
  props: { msg: String },
  render(h, context) {
    return h('div', context.props.msg)
  }
}

异步组件

import { defineAsyncComponent } from 'vue'

const AsyncComp = defineAsyncComponent({
  loader: () => import('./Async.vue'),
  loadingComponent: Loading,
  errorComponent: Error,
  delay: 200,
  timeout: 3000
})

面试常见问题

1. v-model 的原理？

本质是 v-bind:value + @input 的语法糖，监听 input 事件并更新数据。

2. v-for 中 key 的作用？

帮助 Vue 识别节点身份，实现高效的 DOM 复用。推荐使用数据唯一 ID，避免使用数组索引。

3. computed 和 watch 的区别？

• computed：计算属性，依赖变化自动计算，缓存结果
• watch：监听器，监听数据变化，执行异步或复杂逻辑

4. Vue2 和 Vue3 的区别？

• 响应式：Object.defineProperty → Proxy
• API：Options API → Composition API
• 多根节点：不支持 → 支持
• 生命周期：beforeDestroy → beforeUnmount

5. 组件通信方式有哪些？

• props / $emit：父子
• provide / inject：祖先-后代
• $attrs /$attrs/listeners：透传
• 事件总线：兄弟/任意
• Pinia/Vuex：全局状态

6. Vue 的响应式原理？

通过 Proxy/Object.defineProperty 劫持数据访问，在 getter 中收集依赖，setter 中触发更新。

总结

Vue 以其简洁的 API 和渐进式的设计理念，成为前端开发的主流框架。掌握 Vue 的基础理论、常用 API 以及组件通信方式，是 Vue 开发者的必备技能。Vue3 的 Composition API 提供了更现代化的开发范式，建议在实际项目中优先使用。

Radio Group Pattern 详解：构建无障碍单选按钮组件

单选按钮（Radio Button）是表单中用于从一组互斥选项中选择单个项目的控件。本文基于 W3C WAI-ARIA Radio Pattern 规范，详解如何构建无障碍的单选按钮组件。

一、Radio 的定义与核心概念

单选按钮允许用户从一组相关但互斥的选项中选择一个且仅一个选项。当用户选择一个选项时，同组中之前被选中的选项会自动取消选中。

1.1 核心特性

• 互斥性：同一组内只能有一个选项被选中
• 预设选中：通常有一个选项默认被选中
• 分组依赖：通过相同的 name 属性（HTML）或 aria-label（ARIA）进行分组

1.2 与 Checkbox 的区别

二、WAI-ARIA 角色与属性

2.1 基本角色

单选按钮具有 role="radio"。

2.2 状态属性

• aria-checked="true"：单选按钮被选中
• aria-checked="false"：单选按钮未被选中

2.3 分组属性

单选按钮必须分组，以便辅助技术理解它们之间的关系：

• 使用 role="radiogroup" 包裹一组单选按钮
• 使用 aria-labelledby 引用组标签的 ID
• 或使用 aria-label 直接设置组的标签

<div
  role="radiogroup"
  aria-labelledby="group-label">
  <h3 id="group-label">选择支付方式</h3>
  <div
    role="radio"
    aria-checked="true"
    tabindex="0">
    信用卡
  </div>
  <div
    role="radio"
    aria-checked="false"
    tabindex="-1">
    支付宝
  </div>
  <div
    role="radio"
    aria-checked="false"
    tabindex="-1">
    微信支付
  </div>
</div>

2.4 可访问标签

每个单选按钮的可访问标签可以通过以下方式提供：

• 可见文本内容：直接包含在具有 role="radio" 的元素内的文本
• aria-labelledby：引用包含标签文本的元素的 ID
• aria-label：直接在单选按钮元素上设置标签文本

2.5 描述属性

如果包含额外的描述性静态文本，使用 aria-describedby：

<div
  role="radio"
  aria-checked="false"
  aria-describedby="option-desc">
  高级会员
</div>
<p id="option-desc">包含所有高级功能，每月 99 元</p>

三、键盘交互规范

3.1 基本键盘操作

当单选按钮获得焦点时：

3.2 方向键导航（可选但推荐）

四、实现方式

4.1 原生 HTML 实现（推荐）

原生 HTML <input type="radio"> 提供完整的无障碍支持：

<fieldset>
  <legend>选择性别</legend>
  <label>
    <input
      type="radio"
      name="gender"
      value="male"
      checked />
    男
  </label>
  <label>
    <input
      type="radio"
      name="gender"
      value="female" />
    女
  </label>
  <label>
    <input
      type="radio"
      name="gender"
      value="other" />
    其他
  </label>
</fieldset>

4.2 ARIA 实现（自定义样式）

<div
  role="radiogroup"
  aria-labelledby="payment-label">
  <h3 id="payment-label">选择支付方式</h3>

  <div
    role="radio"
    aria-checked="true"
    tabindex="0"
    onclick="selectRadio(this)"
    onkeydown="handleKeydown(event, this)">
    <span
      class="radio-icon"
      aria-hidden="true"></span>
    信用卡
  </div>

  <div
    role="radio"
    aria-checked="false"
    tabindex="-1"
    onclick="selectRadio(this)"
    onkeydown="handleKeydown(event, this)">
    <span
      class="radio-icon"
      aria-hidden="true"></span>
    支付宝
  </div>

  <div
    role="radio"
    aria-checked="false"
    tabindex="-1"
    onclick="selectRadio(this)"
    onkeydown="handleKeydown(event, this)">
    <span
      class="radio-icon"
      aria-hidden="true"></span>
    微信支付
  </div>
</div>

<script>
  function selectRadio(selectedRadio) {
    const radioGroup = selectedRadio.closest('[role="radiogroup"]');
    const radios = radioGroup.querySelectorAll('[role="radio"]');

    radios.forEach((radio) => {
      const isSelected = radio === selectedRadio;
      radio.setAttribute('aria-checked', isSelected);
      radio.setAttribute('tabindex', isSelected ? '0' : '-1');
    });
  }

  function handleKeydown(event, radio) {
    const radioGroup = radio.closest('[role="radiogroup"]');
    const radios = Array.from(radioGroup.querySelectorAll('[role="radio"]'));
    const currentIndex = radios.indexOf(radio);

    switch (event.key) {
      case 'ArrowDown':
      case 'ArrowRight':
        event.preventDefault();
        const nextIndex = (currentIndex + 1) % radios.length;
        radios[nextIndex].focus();
        selectRadio(radios[nextIndex]);
        break;
      case 'ArrowUp':
      case 'ArrowLeft':
        event.preventDefault();
        const prevIndex = (currentIndex - 1 + radios.length) % radios.length;
        radios[prevIndex].focus();
        selectRadio(radios[prevIndex]);
        break;
      case ' ':
        event.preventDefault();
        selectRadio(radio);
        break;
    }
  }
</script>

4.3 水平布局的单选按钮组

<fieldset class="radio-group-horizontal">
  <legend>选择评分</legend>
  <div class="radio-options">
    <label class="radio-label">
      <input
        type="radio"
        name="rating"
        value="1" />
      <span>1 星</span>
    </label>
    <label class="radio-label">
      <input
        type="radio"
        name="rating"
        value="2" />
      <span>2 星</span>
    </label>
    <label class="radio-label">
      <input
        type="radio"
        name="rating"
        value="3"
        checked />
      <span>3 星</span>
    </label>
    <label class="radio-label">
      <input
        type="radio"
        name="rating"
        value="4" />
      <span>4 星</span>
    </label>
    <label class="radio-label">
      <input
        type="radio"
        name="rating"
        value="5" />
      <span>5 星</span>
    </label>
  </div>
</fieldset>

4.4 带描述的选项

<fieldset
  role="radiogroup"
  aria-labelledby="plan-label">
  <legend id="plan-label">选择套餐</legend>

  <label class="radio-card">
    <input
      type="radio"
      name="plan"
      value="basic"
      checked />
    <div class="radio-content">
      <strong>基础版</strong>
      <span class="price">¥29/月</span>
      <p class="description">适合个人用户，包含基础功能</p>
    </div>
  </label>

  <label class="radio-card">
    <input
      type="radio"
      name="plan"
      value="pro" />
    <div class="radio-content">
      <strong>专业版</strong>
      <span class="price">¥99/月</span>
      <p class="description">适合小型团队，包含高级功能</p>
    </div>
  </label>

  <label class="radio-card">
    <input
      type="radio"
      name="plan"
      value="enterprise" />
    <div class="radio-content">
      <strong>企业版</strong>
      <span class="price">¥299/月</span>
      <p class="description">适合大型企业，包含全部功能</p>
    </div>
  </label>
</fieldset>

五、常见应用场景

5.1 性别选择

<fieldset>
  <legend>性别</legend>
  <label
    ><input
      type="radio"
      name="gender"
      value="male" />
    男</label
  >
  <label
    ><input
      type="radio"
      name="gender"
      value="female" />
    女</label
  >
  <label
    ><input
      type="radio"
      name="gender"
      value="other" />
    其他</label
  >
  <label
    ><input
      type="radio"
      name="gender"
      value="secret"
      checked />
    保密</label
  >
</fieldset>

5.2 支付方式选择

<fieldset>
  <legend>选择支付方式</legend>
  <label class="payment-option">
    <input
      type="radio"
      name="payment"
      value="credit-card"
      checked />
    <img
      src="credit-card-icon.svg"
      alt="" />
    信用卡
  </label>
  <label class="payment-option">
    <input
      type="radio"
      name="payment"
      value="alipay" />
    <img
      src="alipay-icon.svg"
      alt="" />
    支付宝
  </label>
  <label class="payment-option">
    <input
      type="radio"
      name="payment"
      value="wechat" />
    <img
      src="wechat-icon.svg"
      alt="" />
    微信支付
  </label>
</fieldset>

5.3 主题切换

<fieldset class="theme-selector">
  <legend>选择主题</legend>
  <div class="theme-options">
    <label class="theme-option">
      <input
        type="radio"
        name="theme"
        value="light"
        checked />
      <span class="theme-preview light"></span>
      浅色
    </label>
    <label class="theme-option">
      <input
        type="radio"
        name="theme"
        value="dark" />
      <span class="theme-preview dark"></span>
      深色
    </label>
    <label class="theme-option">
      <input
        type="radio"
        name="theme"
        value="auto" />
      <span class="theme-preview auto"></span>
      跟随系统
    </label>
  </div>
</fieldset>

六、最佳实践

6.1 优先使用原生单选按钮

原生 HTML <input type="radio"> 提供完整的无障碍支持，包括：

• 自动键盘交互（方向键导航）
• 自动互斥选择
• 屏幕阅读器自动播报状态
• 浏览器原生样式和焦点管理

6.2 始终设置默认选中

为避免用户忘记选择，通常应该预设一个默认选项：

<!-- 推荐：预设默认选项 -->
<fieldset>
  <legend>选择语言</legend>
  <label
    ><input
      type="radio"
      name="language"
      value="zh"
      checked />
    中文</label
  >
  <label
    ><input
      type="radio"
      name="language"
      value="en" />
    English</label
  >
</fieldset>

6.3 使用 fieldset 和 legend 分组

始终使用 <fieldset> 和 <legend> 对单选按钮进行语义化分组：

<fieldset>
  <legend>选择尺寸</legend>
  <label
    ><input
      type="radio"
      name="size"
      value="s" />
    S</label
  >
  <label
    ><input
      type="radio"
      name="size"
      value="m"
      checked />
    M</label
  >
  <label
    ><input
      type="radio"
      name="size"
      value="l" />
    L</label
  >
  <label
    ><input
      type="radio"
      name="size"
      value="xl" />
    XL</label
  >
</fieldset>

6.4 提供清晰的视觉指示

确保选中和未选中状态有清晰的视觉区别：

/* 自定义单选按钮样式 */
input[type='radio'] {
  width: 20px;
  height: 20px;
  accent-color: #005a9c;
}

input[type='radio']:focus {
  outline: 2px solid #005a9c;
  outline-offset: 2px;
}

6.5 避免嵌套交互元素

不要在单选按钮标签内嵌套其他交互元素：

<!-- 不推荐 -->
<label>
  <input
    type="radio"
    name="option"
    value="a" />
  选项 A <a href="/details">查看详情</a>
</label>

<!-- 推荐 -->
<div>
  <label>
    <input
      type="radio"
      name="option"
      value="a" />
    选项 A
  </label>
  <a href="/details">查看详情</a>
</div>

6.6 考虑移动端触摸区域

确保单选按钮有足够的触摸区域（至少 44x44px）：

.radio-label {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 12px;
  min-height: 44px;
}

七、Radio 与 Select 的选择

八、总结

构建无障碍的单选按钮组件需要关注三个核心：正确的语义化分组（<fieldset> 和 <legend>）、清晰的选中状态指示、以及良好的键盘导航支持（方向键切换）。与 Checkbox 不同，Radio 强调互斥选择，适用于需要从一组选项中精确选择单一项目的场景。

遵循 W3C Radio Pattern 规范，我们能够创建既美观又包容的单选按钮组件，为不同能力的用户提供一致的体验。

文章同步于 an-Onion 的 Github。码字不易，欢迎点赞。

在前端开发中，我们几乎绕不开一个核心问题：状态（state）该放在哪里？

随着项目复杂度的提升，状态的存放位置也会经历一次次“升级”：

子组件 → 父组件 → Hook（组合式函数）→ Pinia（全局状态管理）

这篇文章，我会带你一步步拆解这个“状态提升”的演进过程，并结合VUE代码示例，帮你理解每一次升级背后的动机和设计思想。

一、第一阶段：状态在子组件中（局部状态）

在项目早期，我们通常会把状态直接写在子组件内部。

示例：一个计数器组件

<!-- Counter.vue -->
<script setup>
import { ref } from 'vue'

const count = ref(0)

const increment = () => {
  count.value++
}
</script>

<template>
  <div>
    <p>{{ count }}</p>
    <button @click="increment">+1</button>
  </div>
</template>

特点

• 状态封装在组件内部
• 简单直观
• 适合完全独立的 UI 组件

问题

如果有两个组件都需要用到这个 count 呢？

比如：

<Counter />
<Display />

Display 组件也想显示这个 count，怎么办？

这时我们就需要第一次升级。

二、第二阶段：从子组件提升到父组件

当多个子组件共享状态时，我们会把状态“提升”到它们的共同父组件。

这和 React 的“状态提升”思想是一致的。

父组件管理状态

<!-- Parent.vue -->
<script setup>
import { ref } from 'vue'
import Counter from './Counter.vue'
import Display from './Display.vue'

const count = ref(0)

const increment = () => {
  count.value++
}
</script>

<template>
  <Counter :count="count" @increment="increment" />
  <Display :count="count" />
</template>

子组件只负责展示和触发

<!-- Counter.vue -->
<script setup>
defineProps({
  count: Number
})

defineEmits(['increment'])
</script>

<template>
  <button @click="$emit('increment')">+1</button>
</template>

优点

• 状态集中管理
• 数据流清晰（单向数据流）

缺点

• 层级一深就会出现：

  • props drilling（层层传参）
  • 事件层层冒泡

• 父组件变得“臃肿”

当项目规模扩大后，这种方式开始吃力。

于是我们进行第二次升级。

三、第三阶段：从父组件提升到 Hook（组合式函数）

在 Vue 3 中，Composition API 让我们可以把逻辑抽离成 Hook（组合式函数）。

我们把状态抽离到一个独立文件中。

创建一个 useCounter.ts

// useCounter.ts
import { ref } from 'vue'

export function useCounter() {
  const count = ref(0)

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

  return {
    count,
    increment
  }
}

在组件中使用

<script setup>
import { useCounter } from './useCounter'

const { count, increment } = useCounter()
</script>

优点

• 逻辑复用
• 代码结构更清晰
• 组件变“干净”
• 可测试性更强

但问题来了

如果两个组件都调用 useCounter()：

const a = useCounter()
const b = useCounter()

它们的 count 是：

❌ 不共享的
每调用一次都会创建新的状态实例。

如果我们希望多个组件共享同一个状态怎么办？

这时候，Hook 已经不够用了。

于是我们迎来终极升级。

四、第四阶段：从 Hook 升级到 Pinia

当状态需要在多个页面、多个模块、多个层级中共享时，我们就需要真正的状态管理工具。

在 Vue 生态中，主流选择是：

• Vuex（旧）
• Pinia（官方推荐）

这里我们使用 Pinia。

什么是 Pinia？

Pinia 是 Vue 官方推荐的状态管理库，支持 Vue 3，API 设计非常现代化。

它的理念是：

Store = 可复用的全局 Hook

创建一个 Counter Store

// stores/counter.ts
import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)

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

  return { count, increment }
})

在组件中使用

<script setup>
import { useCounterStore } from '@/stores/counter'

const counter = useCounterStore()
</script>

<template>
  <button @click="counter.increment">
    {{ counter.count }}
  </button>
</template>

关键特性

• 所有组件共享同一个 store
• 自动响应式
• DevTools 支持
• 模块化管理

状态升级的本质

我们来总结一下这四个阶段：

设计哲学：状态放在哪里？

可以用一句话概括：

状态应该放在“刚好需要它的最上层”

• 只一个组件用 → 放子组件
• 两个兄弟组件用 → 放父组件
• 多个地方用但不共享 → Hook
• 全局共享 → Pinia

这是一种“按需升级”的架构策略。

不要一开始就上 Pinia

不要直接提升到pinia，这会带来：

• 不必要的全局耦合
• 难以维护
• 状态污染

记住：

全局状态是一种“权力”，不要滥用。

应该从下至上，找到最合适的地方，随着需求的变更，代码也跟随变更。

架构升级的思维模型

这个升级过程，本质上体现的是：

• 局部化 → 抽象化 → 全局化
• 组件驱动 → 逻辑驱动 → 状态驱动

这也是现代前端架构演进的核心路线。

结语

Vue 的状态管理不是非黑即白的选择，而是一个“渐进增强”的过程。

当你理解了：

• 为什么提升状态
• 什么时候该提升
• 提升的边界在哪里

你就真正掌握了 Vue 状态管理的设计思想。

思考

• 如果所有的父子组件都需要这个状态呢？（Provide/Inject）

核心观点

当 AI 成为程序员的标配，真正拉开差距的不是工具本身，而是使用方式。

Boris（Claude Code 创始人）首次公开团队内部使用手册，这些技巧来自 Claude Code 核心团队的真实工作场景，可以让工作效率比以前高出 5–10 倍。他的原话颇具代表性：

"我已有 6 个月没写过一行 SQL 代码了。"

十大效率技巧

1. 并行作业：构建多线程作战环境

这是团队给出的 Top 1 建议。

同时开启 3–5 个 git 工作树（worktree），每个运行独立的 Claude 会话：

• 一个 Claude 负责重构代码
• 一个 Claude 负责写测试
• 一个 Claude 负责分析日志

进阶技巧： 给工作树命名并设置 shell 别名（如 za、zb、zc），一键切换不同任务环境。也可专门维护一个「分析专用」工作树，只用来跑 BigQuery 和看日志。

2. 计划模式（Plan Mode）：复杂任务必须先规划

团队铁律：每个复杂任务都从计划模式开始，而不是直接编码。

• 把精力投入计划阶段，让 Claude 一次性完美实现
• 进阶玩法： 让一个 Claude 写方案，开第二个 Claude 扮演「主任架构师」审核
• 避坑指南： 代码一旦跑偏，立刻跳回 Plan Mode 重新规划，而不是反复打补丁

3. CLAUDE.md：让 AI「记住」你的所有规则

这是 Claude 的长期记忆系统，也是普通用户最容易忽视的一点。

每次 Claude 犯错后，在反馈末尾加上：

Update your CLAUDE.md so you don't make this mistake again.

Boris 透露，Claude 非常擅长给自己写规则。持续迭代 CLAUDE.md 文件直到错误率显著下降。有经验的工程师甚至让 Claude 为每个任务/项目维护专门的笔记目录，每次 PR 后更新，并在 CLAUDE.md 中引用这些笔记。

4. 重复的事，一定要变成 Skill

原则：如果某件事每天重复做超过两次，就该把它写成 Skill，提交到 git，在所有项目间复用。

真实案例：

• /techdebt：每天结束前扫描重复代码
• 一个 Slash Skill：同步 7 天的 Slack / GDrive / Asana / GitHub 数据
• 数据工程 Agent：写 dbt、Review、测试

Claude Code 的威力，不在「对话」，而在可复用能力的积累。

5. 90% 的 Bug，Claude 可以自己修

Claude 团队修 Bug 的方式非常「反直觉」——不要去教 Claude 怎么 fix，让 Claude 自己决定。

操作示例：

• 开 Slack MCP，把一个 Bug 讨论串丢给 Claude，只说一个字：fix
• 或者直接：Go fix the failing CI tests.（不指定步骤、不微操）
• 分布式系统中：直接把 docker logs 给 Claude 分析

6. 提升 Prompt 技巧：从「请示」到「挑战」

不要只会求 AI 帮写代码，要学会「挑战」它，像对待高级同事一样协作。

三个改变游戏规则的 Prompt 技巧：

1. 角色反转审查："证明给我看这能工作"，让 Claude 对比主分支和功能分支的行为差异
2. 优雅重构："已知目前所有条件，把这个垃圾删了，重写一个优雅的方案。"
3. 详细规格：提前编写详细规格说明，减少歧义——你越具体，输出质量越高

示例 Prompt："质问我这些变更，直到我通过你的测试才创建 PR。"

7. 终端环境优化：工具配置决定效率上限

Claude Code 团队的偏爱配置：

• 终端：Ghostty（同步渲染、24-bit 颜色、Unicode）
• 状态栏：用 /statusline 显示当前 git 分支 + Context 使用率
• 多任务：tmux / 多 tab，每个标签对应一个任务/worktree，并对标签进行颜色编码和命名

一个被严重低估的技巧：语音输入。 说话比打字快 3 倍，Prompt 质量反而更高。

8. 子代理（Subagents）：更多算力，但不污染主上下文

使用原则：

• 在任何请求后加「使用子代理」，让 Claude 投入更多算力
• 把单个任务卸载给子代理，保持主代理的上下文窗口干净聚焦
• 通过 hook 将权限请求路由到 Opus 4.5，自动扫描并批准安全请求，实现权限管理自动化

9. 数据分析：告别手写 SQL 的时代

Claude 团队几乎已经不用手写 SQL。

• 使用 Claude Code 调用 bq 命令行工具即时拉取和分析指标
• 在代码库中维护 BigQuery 技能，团队每个成员直接在 Claude Code 中进行分析查询
• 这种方法适用于任何有 CLI、MCP 或 API 的数据库

实战示例："帮我分析上周用户增长异常的原因"——AI 会自动写 SQL、拉数据、出图表、给结论。

10. 用 Claude 学习：而不只是让它干活

Claude 团队内部的学习用法：

• 在 /config 中开启「Learning / Explanatory」输出模式，让 Claude 解释改动背后的原因
• 对于不熟悉的代码，让 Claude 生成可视化 HTML 演示文稿
• 要求 Claude 绘制新协议和代码库的 ASCII 图表，帮助理解
• 构建间隔重复学习 Skill（你讲 → 它追问 → 存储）

Claude 不只是生产工具，也是放大理解力的杠杆。

总结

Boris 在开头就强调：使用 Claude Code 没有唯一正确的方式，每个人的设置都不同。

这 10 条技巧只是起点，真正的效率提升来自于：

• 大胆实验，找到适合自己工作流的方式
• 持续迭代，不断优化技能和配置
• 分享交流，从团队中汲取智慧

AI 时代的编程，拼的不是打字速度，而是定义问题的边界以及调度算力的能力。

写在前面

关注前端工具链的人应该都注意到了，Rust 正在「入侵」这个领域。SWC 被 Next.js 采用，Biome 在蚕食 ESLint 和 Prettier 的地盘，而 Oxc 作为新一代 Rust 工具链，性能数据更是夸张——比 SWC 还快好几倍。

更值得关注的是 Vite 的动向。Evan You 团队正在开发 Rolldown，一个用 Rust 重写的 Rollup，底层就是基于 Oxc。按照 roadmap，Rolldown 会逐步集成到 Vite 中，届时整个构建流程都将是 Rust 实现。

既然大势所趋，为什么不提前体验一下？Oxc 的各个模块（oxc-transform、oxc-resolver、oxc-minify）都已经通过 npm 包发布了，完全可以在当前的 Vite 项目中直接使用。于是我动手写了 vite-plugin-oxc，把 Oxc 的能力接入 Vite 的插件体系，算是在 Rolldown 正式落地前的一次提前尝鲜。

这就是这个插件的由来。

项目源码：github.com/Sunny-117/v…

一、JavaScript 编译工具的前世今生

在聊具体实现之前，有必要回顾一下 JavaScript 编译工具这些年的演进。这不是为了炒冷饭，而是理解这个演进脉络，才能明白为什么 Oxc 的出现是一种必然。

1.1 Babel：开创性的存在

2014 年，当 ES6 规范还在草案阶段，6to5（后来更名为 Babel）横空出世。那时候浏览器对新语法的支持参差不齐，Babel 让开发者可以放心使用箭头函数、解构赋值、类等新特性，然后转译成 ES5 代码跑在老旧浏览器上。

Babel 的架构设计很经典：

源代码 → Parser（解析成 AST）→ Transformer（插件转换）→ Generator（生成代码）

这套架构的优势在于插件系统的灵活性。任何人都可以写一个 Babel 插件，操作 AST 实现自定义的代码转换。十年过去了，Babel 生态里积累了数以万计的插件，覆盖了几乎所有你能想到的代码转换需求。

但问题也很明显：慢。

Babel 是纯 JavaScript 实现的。JavaScript 是单线程、解释执行、带 GC 的语言，天生就不是性能敏感型任务的最佳选择。当项目规模膨胀到几十万行代码时，Babel 的编译时间会变得令人抓狂。我见过一些大型 monorepo 项目，光 Babel 编译就要好几分钟。

另一个痛点是配置复杂度。@babel/preset-env、@babel/plugin-transform-runtime、core-js、browserslist……这些概念交织在一起，新手很容易迷失在配置地狱里。我至今还记得当年为了搞清楚 useBuiltIns: 'usage' 和 useBuiltIns: 'entry' 的区别，翻了多少遍文档。

1.2 esbuild：用 Go 重写一切

2020 年，esbuild 的出现彻底改变了游戏规则。

作者 Evan Wallace（Figma 联合创始人）用 Go 语言重写了一个 JavaScript/TypeScript 打包器，性能数据令人瞠目结舌：比 Webpack 快 10-100 倍。这不是什么黑魔法，原因很朴素：

1. Go 是编译型语言，执行效率远高于 JavaScript
2. Go 的并发模型让 esbuild 可以充分利用多核 CPU
3. 从零设计，没有历史包袱，数据结构和算法都针对性能优化过
4. All-in-one，解析、转换、打包、压缩一条龙，减少中间环节的开销

Vite 选择 esbuild 做预构建（pre-bundling）正是看中了这一点。在开发模式下，esbuild 可以在几百毫秒内把 node_modules 里的依赖打包好，让 Vite 的冷启动时间保持在秒级。

但 esbuild 也有它的局限：

• 不做类型检查。它只剥离 TypeScript 类型，不验证类型正确性。
• 插件系统相对简单。不像 Babel 那样可以精细操作 AST，esbuild 的插件主要用于自定义模块解析和加载。
• 不追求 100% 兼容。一些边缘场景的语法转换可能和 Babel 结果不一致。
• 作者明确表示不会支持某些特性，比如装饰器的旧版实现。

对于大多数项目来说，这些局限不是问题。但在某些场景下，你可能还是得请出 Babel。

1.3 SWC：Rust 阵营的第一枪

2019 年，韩国开发者 Donny（강동윤）用 Rust 启动了 SWC 项目。名字来源于 "Speedy Web Compiler"，目标很直接：做一个更快的 Babel 替代品。

SWC 的策略是 兼容 Babel。它实现了大部分 Babel 的转换能力，配置项也尽量保持一致，让迁移成本降到最低。性能方面，SWC 号称比 Babel 快 20 倍以上。

2021 年，SWC 被 Vercel 收购，成为 Next.js 12 的默认编译器。这是一个标志性事件——Rust 编写的前端工具链开始进入主流视野。

SWC 的优势在于：

• Rust 的性能。编译型语言、零成本抽象、无 GC 停顿。
• 良好的 Babel 兼容性。支持大部分 Babel 插件的功能。
• 持续的投入。有 Vercel 背书，项目维护有保障。

但 SWC 也有一些问题。最常被吐槽的是 编译产物的稳定性。早期版本偶尔会出现一些边缘情况的 bug，导致生产环境翻车。另外，SWC 的架构设计主要服务于 Next.js 的需求，作为通用工具使用时，某些场景的支持不够完善。

1.4 工具演进的本质规律

回顾这段历史，可以看到一个清晰的趋势：

这个演进本质上是在解决同一个问题：如何在保证功能的前提下，榨干硬件的每一分性能。

JavaScript 天生不适合这类 CPU 密集型任务，所以社区开始用系统级语言重写。Go 和 Rust 之争，目前看来 Rust 略占上风——主要是因为 Rust 的零成本抽象和更精细的内存控制，在极致性能场景下更有优势。

二、Oxc 凭什么更快

Oxc（Oxidation Compiler）是 2023 年开始崭露头角的新项目，作者是 Boshen Chen。相比前辈们，Oxc 有几个独特的特点。

2.1 不只是编译器，是完整工具链

Oxc 的野心不止于一个编译器。它的目标是提供一整套高性能 JavaScript 工具链：

• oxc-parser：JavaScript/TypeScript 解析器
• oxc-transform：代码转换器（JSX、TypeScript 等）
• oxc-resolver：模块路径解析器
• oxc-minify：代码压缩器
• oxc-linter：代码检查器（对标 ESLint）
• oxc-formatter：代码格式化器（对标 Prettier）

每个模块都可以独立使用，通过 npm 包的形式分发（底层是 Rust 编译成 N-API 原生模块）。这种模块化设计让你可以按需引入，而不是大包大揽。

2.2 性能数据

根据 Oxc 官方的 benchmark，在 parser 层面：

• 比 SWC 快 3 倍
• 比 Babel parser 快 40+ 倍

在 transformer 层面，处理 TypeScript 的速度大约是 SWC 的 4 倍。

这些数字看起来很夸张，但我自己跑过测试，差距确实存在。Oxc 的作者在性能优化上下了很大功夫，比如：

• 使用 bumpalo 这种 arena allocator 来减少内存分配开销
• AST 节点设计更紧凑，减少内存占用
• 大量使用 SIMD 指令加速字符串处理
• 零拷贝解析，尽量复用源代码字符串

2.3 兼容性策略

Oxc 的兼容性策略比较务实。它不追求 100% 兼容 Babel 的每一个行为，而是覆盖 实际生产中最常用的转换场景：

• TypeScript 类型剥离
• JSX 转换（classic 和 automatic 两种模式）
• ES target 降级（async/await、optional chaining 等）
• React Fast Refresh 注入

对于大多数项目来说，这些功能已经够用了。

三、vite-plugin-oxc 的设计思路

有了前面的背景铺垫，现在进入正题：如何把 Oxc 接入 Vite？

3.1 需求分析

我给自己定的目标是：

1. 替代 Vite 内置的 esbuild 做代码转换。包括 TypeScript 类型剥离、JSX 转换。
2. 提供模块解析能力。用 oxc-resolver 替代 Vite 的默认解析逻辑（可选）。
3. 提供代码压缩能力。用 oxc-minify 在生产构建时压缩代码。
4. 支持 React Fast Refresh。开发模式下的 HMR 必须正常工作。
5. 零配置可用。默认配置就能满足大多数项目的需求。

3.2 Vite 插件机制简介

Vite 的插件系统基于 Rollup，但做了一些扩展。一个 Vite 插件本质上是一个对象，包含若干个 hook 函数。和我们这个插件相关的主要有：

• config：修改 Vite 配置
• configResolved：配置解析完成后的回调，可以拿到最终配置
• resolveId：自定义模块 ID 解析
• load：自定义模块加载
• transform：代码转换
• transformIndexHtml：转换 HTML 入口文件
• generateBundle：生成产物后的回调，可以修改最终产物

另外还有一个关键配置：enforce。它决定插件的执行顺序：

• enforce: 'pre'：在 Vite 核心插件之前执行
• 不设置：在 Vite 核心插件之后、用户插件之前执行
• enforce: 'post'：在所有插件之后执行

对于代码转换类插件，通常需要设置 enforce: 'pre'，这样才能在 Vite 的默认处理之前介入。

3.3 整体架构

┌─────────────────────────────────────────────────────────────┐
│                     vite-plugin-oxc                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │  Transform   │  │   Resolve    │  │     Minify       │   │
│  │  (oxc-       │  │  (oxc-       │  │   (oxc-minify)   │   │
│  │  transform)  │  │  resolver)   │  │                  │   │
│  └──────────────┘  └──────────────┘  └──────────────────┘   │
│         │                 │                   │             │
│         ▼                 ▼                   ▼             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                React Fast Refresh                    │   │
│  │               (HMR 边界检测 + 运行时)                 │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

这个插件由三个核心功能模块组成，加上一套 React Fast Refresh 的支持逻辑。下面逐一拆解。

四、Transform 模块：代码转换的核心

代码转换是整个插件最核心的功能。它的职责是把 TypeScript、JSX 这些浏览器不认识的语法，转换成标准的 JavaScript。

4.1 基本实现

先看核心代码：

import { transformSync as oxcTransform } from 'oxc-transform'

// 在 transform hook 中
transform(code, id, transformOptions) {
  if (!filter(id) || options.transform === false) return null

  const isJsxFile = /\.[jt]sx$/.test(id)
  const enableRefresh = isDev && options.reactRefresh && isJsxFile

  const result = oxcTransform(id, code, {
    ...transformOpts,
    sourceType: guessSourceType(id, transformOptions?.format),
    sourcemap: options.sourcemap,
    jsx: {
      ...jsxOpts,
      development: isDev,
      refresh: enableRefresh ? {} : undefined,
    },
  })

  if (result.errors.length) {
    throw new SyntaxError(
      result.errors.map((error) => error.message).join('\n')
    )
  }

  return {
    code: result.code,
    map: result.map,
  }
}

oxcTransform 是 oxc-transform 提供的同步转换函数。它接收三个参数：

1. 文件路径（用于 sourcemap 和错误信息）
2. 源代码字符串
3. 转换选项

返回值包含转换后的代码和 sourcemap。

4.2 sourceType 推断

一个容易被忽略的细节是 sourceType 的处理。JavaScript 有两种模块类型：

• module：ESM，支持 import/export
• script：传统脚本，支持 CommonJS

如果 sourceType 判断错误，转换结果可能出问题。比如把 ESM 代码当成 script 处理，import 语句就会报语法错误。

我实现了一个 guessSourceType 函数来推断：

export function guessSourceType(
  id: string,
  format?: string
): 'module' | 'script' | undefined {
  // 优先使用上游传递的 format 信息
  if (format === 'module' || format === 'module-typescript') {
    return 'module'
  } else if (format === 'commonjs' || format === 'commonjs-typescript') {
    return 'script'
  }

  // 根据文件扩展名推断
  const moduleFormat = getModuleFormat(id)
  if (moduleFormat) {
    return moduleFormat === 'module' ? 'module' : 'script'
  }
}

export function getModuleFormat(
  id: string
): 'module' | 'commonjs' | 'json' | undefined {
  const ext = path.extname(id)
  switch (ext) {
    case '.mjs':
    case '.mts':
      return 'module'
    case '.cjs':
    case '.cts':
      return 'commonjs'
    case '.json':
      return 'json'
    case '.jsx':
    case '.tsx':
      return 'module' // JSX/TSX 默认当 ESM 处理
  }
}

这里有个约定：.mjs/.mts 是 ESM，.cjs/.cts 是 CommonJS，.jsx/.tsx 默认当 ESM。对于 .js/.ts，则依赖上游的 format 信息或者返回 undefined 让 Oxc 自己判断。

4.3 与 Vite 内置 esbuild 的协同

Vite 默认会用 esbuild 处理 TypeScript 和 JSX。如果我们的插件也处理这些文件，就会重复转换，结果不可预期。

解决方案是在 config hook 里禁用 esbuild 对 JSX/TSX 的处理：

config(_userConfig, { command }) {
  return {
    esbuild: {
      // 让 esbuild 只处理纯 .ts 文件
      include: /\.ts$/,
      // 排除 JSX/TSX，交给我们的插件处理
      exclude: /\.[jt]sx$/,
    },
    optimizeDeps: {
      esbuildOptions: {
        jsx: 'automatic',
      },
    },
  }
}

这样配置后，.ts 文件继续走 esbuild（速度也很快），而 .jsx、.tsx、.js 走我们的 Oxc 转换。

不过说实话，这个设计有点 trade-off。理想情况下应该完全接管所有 JS/TS 文件的转换，但考虑到 Vite 生态的兼容性，保持这种混合模式可能更稳妥。

4.4 JSX 转换配置

JSX 转换有两种模式：

1. Classic：转换成 React.createElement 调用
2. Automatic：转换成 _jsx/_jsxs 调用，自动引入 react/jsx-runtime

React 17+ 推荐使用 automatic 模式，这也是我们插件的默认行为。配置项支持自定义：

const jsxOpts = transformOpts.jsx && typeof transformOpts.jsx === 'object'
  ? transformOpts.jsx
  : {}

oxcTransform(id, code, {
  jsx: {
    ...jsxOpts,
    development: isDev, // 开发模式启用额外的调试信息
    refresh: enableRefresh ? {} : undefined, // Fast Refresh 注入
  },
})

development: true 会在转换结果中加入 __source 和 __self 等调试信息，方便在 React DevTools 里看到组件的源码位置。

五、Resolve 模块：模块解析

模块解析看起来简单，实际上是个大坑。import './foo' 这行代码，到底应该解析成哪个文件？

• ./foo.js？
• ./foo.ts？
• ./foo/index.js？
• ./foo/index.ts？
• 还是 ./foo.json？

这取决于项目配置、Node.js 版本、模块类型等一系列因素。

5.1 为什么要自己做解析

Vite 内部已经有一套解析逻辑，为什么我们还要用 oxc-resolver 再来一套？

两个原因：

1. 性能。Oxc resolver 是 Rust 实现的，解析速度比 Vite 的 JavaScript 实现更快。在大型项目中，模块解析的开销不可忽视。
2. 一致性。既然 transform 用了 Oxc，resolver 也用 Oxc，整个工具链的行为会更一致。

当然，这是可选功能，默认开启但可以关闭。

5.2 基本实现

import { ResolverFactory } from 'oxc-resolver'

let resolver: InstanceType<typeof ResolverFactory> | null = null

// 在 configResolved 中初始化
configResolved(config) {
  if (options.resolve !== false) {
    resolver = new ResolverFactory({
      extensions: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json', '.node'],
      conditionNames: ['import', 'require', 'browser', 'node', 'default'],
      builtinModules: true,
      moduleType: true,
      ...options.resolve,
    })
  }
}

// 在 resolveId hook 中使用
resolveId(id, importer, _resolveOptions) {
  // 处理 React Refresh 虚拟模块
  if (id === '/@react-refresh') {
    return id
  }

  if (!resolver || options.resolve === false) return null

  // 默认跳过 node_modules，除非显式启用
  if (
    !options.resolveNodeModules &&
    id[0] !== '.' &&
    !path.isAbsolute(id)
  ) {
    return null
  }

  try {
    const directory = importer ? path.dirname(importer) : process.cwd()
    const resolved = resolver.sync(directory, id)

    // 处理 Node.js 内置模块
    if (resolved.error?.startsWith('Builtin module')) {
      return {
        id,
        external: true,
        moduleSideEffects: false,
      }
    }

    if (resolved.path) {
      const format = getModuleFormat(resolved.path) || resolved.moduleType || 'commonjs'
      return {
        id: resolved.path,
        format,
      }
    }
  } catch (error) {
    // 解析失败，交给 Vite 的默认逻辑处理
    return null
  }

  return null
}

5.3 性能优化：跳过 node_modules

一个重要的优化是 默认不解析 node_modules：

if (
  !options.resolveNodeModules &&
  id[0] !== '.' &&          // 不是相对路径
  !path.isAbsolute(id)       // 不是绝对路径
) {
  return null  // 交给 Vite 处理
}

为什么？因为 Vite 的预构建机制已经把 node_modules 里的依赖处理好了，我们没必要再去解析一遍。只解析项目内的相对路径和绝对路径，性能开销可控。

如果某些场景确实需要解析 node_modules，可以通过配置项开启：

oxc({
  resolveNodeModules: true
})

5.4 内置模块处理

Node.js 有一些内置模块（fs、path、http 等），在浏览器环境是不存在的。当 oxc-resolver 遇到这些模块时，会返回一个特殊的 error：

if (resolved.error?.startsWith('Builtin module')) {
  return {
    id,
    external: true,
    moduleSideEffects: false,
  }
}

把它标记为 external，告诉 Vite 这个模块不需要处理。

六、Minify 模块：代码压缩

生产构建时，代码压缩是必不可少的一环。oxc-minify 提供了和 Terser 类似的压缩能力，但性能更好。

6.1 在 generateBundle 中压缩

代码压缩放在 generateBundle hook 里做：

async generateBundle(_outputOptions, bundle) {
  if (options.minify === false) return

  const { minifySync } = await import('oxc-minify')

  for (const fileName of Object.keys(bundle)) {
    const chunk = bundle[fileName]
    if (chunk.type !== 'chunk') continue

    try {
      const result = minifySync(fileName, chunk.code, {
        ...(options.minify === true ? {} : options.minify),
        sourcemap: options.sourcemap,
      })
      chunk.code = result.code

      // SourceMap 合并...
    } catch (error) {
      this.error(`Failed to minify ${fileName}: ${error}`)
    }
  }
}

这里有几个设计考量：

1. 为什么在 generateBundle 而不是 transform？ 因为压缩应该在所有代码转换完成后、输出文件前进行。此时代码已经是最终形态，压缩效果最好。

2. 为什么用动态 import？ oxc-minify 只在生产构建时需要，开发模式下不需要加载这个依赖，动态 import 可以减少冷启动时间。

3. 为什么跳过非 chunk 类型？ bundle 对象里既有 JS chunk，也有 CSS、图片等 asset。我们只压缩 JS。

6.2 SourceMap 合并

压缩代码会改变代码的行列位置，如果项目需要 sourcemap，必须把压缩前后的 sourcemap 合并，才能正确映射到源码。

这个合并逻辑用 @ampproject/remapping 来做：

import remapping, { type EncodedSourceMap } from '@ampproject/remapping'

if (result.map && chunk.map) {
  const minifyMap: EncodedSourceMap = {
    version: 3,
    file: result.map.file,
    sources: result.map.sources,
    sourcesContent: result.map.sourcesContent,
    names: result.map.names,
    mappings: result.map.mappings,
  }
  const chunkMap: EncodedSourceMap = {
    version: 3,
    file: chunk.map.file,
    sources: chunk.map.sources,
    sourcesContent: chunk.map.sourcesContent,
    names: chunk.map.names,
    mappings: chunk.map.mappings,
  }

  // 合并两个 sourcemap
  const merged = remapping([minifyMap, chunkMap], () => null)

  chunk.map = {
    file: merged.file ?? '',
    mappings: merged.mappings as string,
    names: merged.names,
    sources: merged.sources as string[],
    sourcesContent: merged.sourcesContent as string[],
    version: merged.version,
    toUrl() {
      return `data:application/json;charset=utf-8;base64,${Buffer.from(JSON.stringify(this)).toString('base64')}`
    },
  }
}

remapping 函数接收一个 sourcemap 数组，按顺序合并。第一个是最终代码的 map（压缩后），第二个是上一步的 map（压缩前）。合并后的 map 可以从最终代码直接映射回原始源码。

6.3 压缩选项透传

oxc-minify 支持 Terser 风格的压缩选项：

// 默认压缩
oxc({ minify: true })

// 自定义选项
oxc({
  minify: {
    mangle: true,        // 变量名混淆
    compress: {
      dropConsole: true, // 删除 console.log
    },
  }
})

// 禁用压缩
oxc({ minify: false })

这些选项原封不动传给 minifySync，插件层只加了一个 sourcemap 选项的处理。

七、React Fast Refresh：HMR 的核心

React Fast Refresh 是 React 官方的热更新方案，可以在修改组件代码后保留组件状态，只更新改变的部分。要让它正常工作，需要在编译时注入一些运行时代码。

这部分是整个插件最复杂的地方。

7.1 Fast Refresh 的工作原理

Fast Refresh 的基本原理是：

1. 编译时：在每个模块末尾注入代码，把模块导出的组件注册到 Fast Refresh runtime。
2. 运行时：当模块热更新时，runtime 对比新旧导出，判断是否可以安全刷新。
3. 刷新执行：如果可以安全刷新，runtime 触发 React 重新渲染更新后的组件，同时保留状态。

关键在于「安全刷新」的判断。Fast Refresh 只能处理「纯组件变更」的情况。如果模块导出了非组件内容（比如常量、工具函数），且这些内容发生了变化，就必须做完整刷新。

7.2 运行时模块

我实现了一个虚拟模块 /@react-refresh，提供 Fast Refresh 的运行时代码：

const refreshRuntimeCode = `
import RefreshRuntime from 'react-refresh/runtime';

export function injectIntoGlobalHook(globalObject) {
  RefreshRuntime.injectIntoGlobalHook(globalObject);
}

export function register(type, id) {
  RefreshRuntime.register(type, id);
}

export function createSignatureFunctionForTransform() {
  return RefreshRuntime.createSignatureFunctionForTransform();
}

export function performReactRefresh() {
  return RefreshRuntime.performReactRefresh();
}

// 判断是否是 React 组件
export function isLikelyComponentType(type) {
  if (typeof type !== 'function') return false;
  if (type.prototype != null && type.prototype.isReactComponent) return true;
  if (type.$$typeof) return false;
  const name = type.name || type.displayName;
  return typeof name === 'string' && /^[A-Z]/.test(name);
}

// 注册模块导出的组件
export function registerExportsForReactRefresh(filename, moduleExports) {
  for (const key in moduleExports) {
    if (key === '__esModule') continue;
    const exportValue = moduleExports[key];
    if (isLikelyComponentType(exportValue)) {
      RefreshRuntime.register(exportValue, filename + ' export ' + key);
    }
  }
}

// 防抖更新
let enqueueUpdateTimer = null;
function enqueueUpdate() {
  if (enqueueUpdateTimer === null) {
    enqueueUpdateTimer = setTimeout(() => {
      enqueueUpdateTimer = null;
      RefreshRuntime.performReactRefresh();
    }, 16);
  }
}

// 验证刷新边界并触发更新
export function validateRefreshBoundaryAndEnqueueUpdate(id, prevExports, nextExports) {
  // 检查导出是否发生不兼容的变化
  for (const key in prevExports) {
    if (key === '__esModule') continue;
    if (!(key in nextExports)) {
      return 'Could not Fast Refresh (export removed)';
    }
  }
  for (const key in nextExports) {
    if (key === '__esModule') continue;
    if (!(key in prevExports)) {
      return 'Could not Fast Refresh (new export)';
    }
  }

  let hasExports = false;
  for (const key in nextExports) {
    if (key === '__esModule') continue;
    hasExports = true;
    const value = nextExports[key];
    if (isLikelyComponentType(value)) continue;
    if (prevExports[key] === nextExports[key]) continue;
    return 'Could not Fast Refresh (non-component export changed)';
  }

  if (hasExports) {
    enqueueUpdate();
  }
  return undefined;
}

export const __hmr_import = (module) => import(/* @vite-ignore */ module);
`

这段代码做了几件事：

1. 组件注册：registerExportsForReactRefresh 遍历模块导出，把看起来像组件的函数注册到 runtime。
2. 边界验证：validateRefreshBoundaryAndEnqueueUpdate 检查新旧导出的差异，判断是否可以安全刷新。
3. 防抖更新：enqueueUpdate 用 16ms 的防抖，避免短时间内多次触发刷新。

7.3 HTML Preamble 注入

Fast Refresh 需要在页面加载之前初始化全局钩子。通过 transformIndexHtml hook 注入：

transformIndexHtml() {
  if (!isDev || !options.reactRefresh) return []

  return [
    {
      tag: 'script',
      attrs: { type: 'module' },
      children: `
import { injectIntoGlobalHook } from "/@react-refresh";
injectIntoGlobalHook(window);
window.$RefreshReg$ = () => {};
window.$RefreshSig$ = () => (type) => type;
`,
    },
  ]
}

这段脚本会被插入到 HTML 的 <head> 中，在任何业务代码执行之前运行。它做两件事：

1. 调用 injectIntoGlobalHook(window) 初始化 runtime。
2. 在 window 上挂载两个占位函数 $RefreshReg$ 和 $RefreshSig$，防止业务代码报错。

7.4 模块尾部代码注入

最后，需要在每个 JSX/TSX 模块末尾注入 HMR 边界检测代码：

if (enableRefresh && transformedCode.includes('$RefreshReg$')) {
  const refreshFooter = `
import * as RefreshRuntime from "/@react-refresh";
const inWebWorker = typeof WorkerGlobalScope !== 'undefined' && self instanceof WorkerGlobalScope;
if (import.meta.hot && !inWebWorker) {
  if (!window.$RefreshReg$) {
    throw new Error(
      "vite-plugin-oxc can't detect preamble. Something is wrong."
    );
  }

  RefreshRuntime.__hmr_import(import.meta.url).then((currentExports) => {
    RefreshRuntime.registerExportsForReactRefresh(${JSON.stringify(id)}, currentExports);
    import.meta.hot.accept((nextExports) => {
      if (!nextExports) return;
      const invalidateMessage = RefreshRuntime.validateRefreshBoundaryAndEnqueueUpdate(
        ${JSON.stringify(id)},
        currentExports,
        nextExports
      );
      if (invalidateMessage) import.meta.hot.invalidate(invalidateMessage);
    });
  });
}
function $RefreshReg$(type, id) {
  return RefreshRuntime.register(type, ${JSON.stringify(id)} + ' ' + id)
}
function $RefreshSig$() {
  return RefreshRuntime.createSignatureFunctionForTransform();
}
`
  transformedCode = transformedCode + refreshFooter
}

这段代码的逻辑：

1. 动态导入自身：RefreshRuntime.__hmr_import(import.meta.url) 拿到当前模块的导出。
2. 注册导出：把导出的组件注册到 runtime。
3. 接受热更新：通过 import.meta.hot.accept 监听更新，拿到新的导出后验证边界。
4. 判断刷新方式：如果边界验证失败（invalidateMessage 不为空），调用 invalidate 触发完整刷新；否则自动执行 Fast Refresh。

注意这里有个细节：只有当转换后的代码包含 $RefreshReg$ 时才注入。因为 Oxc 只会在检测到组件定义时才插入这些调用，如果模块里没有组件（比如纯工具函数文件），就不需要这套逻辑。

7.5 Web Worker 兼容

代码里有个判断：

const inWebWorker = typeof WorkerGlobalScope !== 'undefined' && self instanceof WorkerGlobalScope;
if (import.meta.hot && !inWebWorker) {
  // ...
}

Web Worker 环境没有 window 对象，也不支持 HMR，所以需要跳过。

八、文件过滤：控制处理范围

不是所有文件都需要经过 Oxc 处理。CSS、图片、JSON 这些应该跳过。

8.1 Filter 实现

export function createFilter(
  include?: FilterPattern,
  exclude?: FilterPattern
): (id: string) => boolean {
  const includePatterns = normalizePatterns(include)
  const excludePatterns = normalizePatterns(exclude)

  return (id: string) => {
    // 先检查 exclude，命中则跳过
    if (excludePatterns.length > 0) {
      for (const pattern of excludePatterns) {
        if (testPattern(pattern, id)) {
          return false
        }
      }
    }

    // 再检查 include
    if (includePatterns.length === 0) {
      return true // 没有 include 规则则默认处理
    }

    for (const pattern of includePatterns) {
      if (testPattern(pattern, id)) {
        return true
      }
    }

    return false
  }
}

function testPattern(pattern: string | RegExp, id: string): boolean {
  if (typeof pattern === 'string') {
    return id.includes(pattern)
  }
  return pattern.test(id)
}

这个实现遵循一个简单的规则：exclude 优先于 include。如果一个文件同时匹配 include 和 exclude，以 exclude 为准。

8.2 默认配置

include: options.include || [/\.[cm]?[jt]sx?$/],
exclude: options.exclude || [/node_modules/],

默认配置的含义：

• include: 处理所有 .js、.jsx、.ts、.tsx、.mjs、.mts、.cjs、.cts 文件
• exclude: 跳过 node_modules 目录

[cm]? 这个正则匹配可选的 c（CommonJS）或 m（Module）前缀，覆盖了 Node.js 的各种模块扩展名约定。

九、配置系统设计

一个好的插件应该做到「零配置可用，有需要时可配」。

9.1 类型定义

export interface VitePluginOxcOptions {
  include?: FilterPattern          // 文件包含规则
  exclude?: FilterPattern          // 文件排除规则
  enforce?: 'pre' | 'post'         // 插件执行顺序
  transform?: TransformOptions | false  // 转换选项，false 禁用
  resolve?: NapiResolveOptions | false  // 解析选项，false 禁用
  resolveNodeModules?: boolean     // 是否解析 node_modules
  minify?: MinifyOptions | boolean // 压缩选项
  sourcemap?: boolean              // SourceMap 生成
  reactRefresh?: boolean           // React Fast Refresh
}

每个配置项都可以是具体的选项对象、布尔值、或不设置（使用默认值）。

9.2 选项解析

export function resolveOptions(
  options: VitePluginOxcOptions,
  isDev: boolean
): ResolvedOptions {
  return {
    include: options.include || [/\.[cm]?[jt]sx?$/],
    exclude: options.exclude || [/node_modules/],
    enforce: options.enforce,
    transform: options.transform !== false ? (options.transform || {}) : false,
    resolve: options.resolve !== false ? (options.resolve || {}) : false,
    resolveNodeModules: options.resolveNodeModules || false,
    minify: options.minify !== false ? (options.minify || false) : false,
    sourcemap: options.sourcemap ?? isDev,  // 开发模式默认开启
    reactRefresh: options.reactRefresh ?? true,  // 默认开启
  }
}

几个设计决策：

1. transform 和 resolve 默认开启，可以传 false 禁用
2. minify 默认关闭，需要显式传 true 或选项对象开启
3. sourcemap 根据环境决定，开发模式默认开启，生产模式默认关闭
4. reactRefresh 默认开启，因为大部分 React 项目都需要

9.3 enforce 处理

enforce 的处理比较特殊：

const plugin: Plugin = {
  name: 'vite-plugin-oxc',
  enforce: 'pre',  // 默认值
  // ...
}

// 如果用户显式设置了 enforce，覆盖默认值
if ('enforce' in rawOptions) {
  plugin.enforce = rawOptions.enforce
}

为什么不直接用 options.enforce || 'pre'？因为用户可能想显式设置 enforce: undefined，表示不要任何 enforce 约束。用 'enforce' in rawOptions 可以区分「没传」和「传了 undefined」两种情况。

十、测试策略

工程化项目离不开测试。这个插件的测试主要覆盖以下场景。

10.1 单元测试结构

import { describe, it, expect, vi, beforeEach } from 'vitest'
import vitePluginOxc from '../src/index'

// Mock oxc-transform
vi.mock('oxc-transform', () => ({
  transformSync: vi.fn((_id: string, code: string, _options?: unknown) => ({
    code: `// Transformed: ${code}`,
    map: null,
    errors: [],
  })),
}))

// Mock oxc-resolver
vi.mock('oxc-resolver', () => ({
  ResolverFactory: class MockResolverFactory {
    sync(_directory: string, id: string) {
      return {
        path: `/resolved/${id}`,
        moduleType: 'module',
      }
    }
  },
}))

// Mock oxc-minify
vi.mock('oxc-minify', () => ({
  minifySync: vi.fn((fileName: string, code: string) => ({
    code: `/* Minified */ ${code.replace(/\s+/g, ' ').trim()}`,
    map: null,
  })),
}))

为什么要 mock Oxc 的依赖？因为：

1. 隔离测试范围。单元测试关注的是插件的集成逻辑，不是 Oxc 本身的转换行为。
2. 测试执行速度。原生依赖的加载需要时间，mock 后测试更快。
3. 确定性。Oxc 的版本更新可能改变输出，mock 可以保证测试稳定。

10.2 核心测试用例

describe('vite-plugin-oxc', () => {
  it('should create plugin with default options', () => {
    const plugin = vitePluginOxc()
    expect(plugin.name).toBe('vite-plugin-oxc')
    expect(plugin.enforce).toBe('pre')
    expect(typeof plugin.transform).toBe('function')
  })

  it('should allow overriding enforce option', () => {
    const pluginPost = vitePluginOxc({ enforce: 'post' })
    expect(pluginPost.enforce).toBe('post')

    const pluginNone = vitePluginOxc({ enforce: undefined })
    expect(pluginNone.enforce).toBeUndefined()
  })
})

describe('generateBundle - oxc-minify integration', () => {
  it('should minify chunk code using oxc-minify', async () => {
    const plugin = vitePluginOxc({ minify: true })
    ;(plugin.configResolved as Function)({ command: 'build' })

    const bundle = {
      'index.js': {
        type: 'chunk',
        code: 'function hello() { console.log("hi"); }',
        map: null,
      },
    }

    await (plugin.generateBundle as Function).call({ error: vi.fn() }, {}, bundle)

    expect(bundle['index.js'].code).toContain('Minified')
  })

  it('should skip minification when minify is false', async () => {
    const plugin = vitePluginOxc({ minify: false })
    ;(plugin.configResolved as Function)({ command: 'build' })

    const originalCode = 'function hello() { console.log("hi"); }'
    const bundle = {
      'index.js': { type: 'chunk', code: originalCode, map: null },
    }

    await (plugin.generateBundle as Function).call({ error: vi.fn() }, {}, bundle)

    expect(bundle['index.js'].code).toBe(originalCode)
  })

  it('should merge sourcemaps when both exist', async () => {
    // 测试 sourcemap 合并逻辑
  })
})

测试覆盖了：

• 插件创建和默认配置
• 配置覆盖
• 压缩功能的开启/关闭
• SourceMap 合并
• 错误处理

十一、性能实测

说了这么多理论，实际效果如何？我用一个中型 React 项目做了测试。

11.1 测试环境

• 项目规模：约 200 个 TypeScript/TSX 文件，5 万行代码
• 机器配置：MacBook Pro M2，16GB 内存
• Node.js：v20.10.0

11.2 开发模式冷启动

开发模式差距不大，因为 Vite 的预构建已经很快了。

11.3 生产构建

Transform 阶段提速明显（约 33%），开启 oxc-minify 后总体时间也有优势，且压缩效果略好于默认的 esbuild。

11.4 HMR 响应时间

修改一个组件文件后：

HMR 场景下 Oxc 的优势更明显，因为单文件转换时 Oxc 的启动开销比例更低。

十二、踩过的坑

开发过程中遇到了不少问题，记录几个典型的。

12.1 esbuild 的 JSX 处理冲突

最开始没有禁用 esbuild 的 JSX 处理，导致 JSX 被转换了两次，结果代码里出现了奇怪的双重嵌套。

解决方案就是在 config hook 里配置 esbuild 跳过 JSX/TSX：

config() {
  return {
    esbuild: {
      include: /\.ts$/,
      exclude: /\.[jt]sx$/,
    },
  }
}

12.2 SourceMap 合并顺序

第一版 sourcemap 合并写反了顺序：

// 错误写法
const merged = remapping([chunkMap, minifyMap], () => null)

// 正确写法
const merged = remapping([minifyMap, chunkMap], () => null)

remapping 的数组是从「最终代码」到「原始代码」的顺序。压缩后的 map 在前，压缩前的 map 在后。

12.3 React Refresh 的 preamble 时机

Fast Refresh 的 preamble 必须在任何业务代码之前执行。最开始我用 transform hook 在第一个 JSX 文件转换时注入，结果时机不稳定。

后来改用 transformIndexHtml hook，直接往 HTML 里插入 <script>，稳定多了。

12.4 模块格式推断

有些项目混用 ESM 和 CommonJS，如果模块格式判断错误，会导致语法错误或运行时问题。

最后的方案是综合多个信息源：

1. 上游传递的 format 参数
2. 文件扩展名（.mjs/.cjs 等）
3. Oxc resolver 返回的 moduleType
4. 兜底默认值

12.5 虚拟模块的处理

/@react-refresh 是个虚拟模块，不存在于文件系统。需要在 resolveId 和 load 两个 hook 里配合处理：

resolveId(id) {
  if (id === '/@react-refresh') {
    return id  // 告诉 Vite 这个 ID 我来处理
  }
}

load(id) {
  if (id === '/@react-refresh') {
    return refreshRuntimeCode  // 返回模块内容
  }
}

十三、未来展望

13.1 Rolldown 的影响

Vite 团队正在开发 Rolldown，一个用 Rust 重写的 Rollup。一旦 Rolldown 成熟，Vite 的整个构建流程都会是 Rust 实现，性能会再上一个台阶。

Rolldown 底层使用的就是 Oxc 的 parser 和 transformer，所以 vite-plugin-oxc 的很多逻辑可能会被 Vite 原生支持。到那时，这个插件的历史使命可能就完成了。

实际上，官方文档里已经提到：

这个包已弃用。请使用 @vitejs/plugin-react，因为 rolldown-vite 已自动启用基于 Oxc 的 Fast Refresh 转换。

这说明方向是对的，只是时机早了一点。

13.2 工具链的 Rust 化趋势

纵观前端工具链的演进，Rust 化是一个明确的趋势：

• Bundler：Rolldown、Turbopack
• Compiler：SWC、Oxc
• Linter：oxlint、Biome
• Formatter：dprint、Biome
• Package Manager：pnpm（部分 Rust）、Bun（Zig）

JavaScript 工具用 JavaScript 写的时代正在过去。对于开发者来说，这意味着更快的开发体验，但也意味着参与工具开发的门槛变高了——你得会 Rust。

13.3 这个插件的定位

虽然 Rolldown 出来后这个插件可能就没用了，但它的价值在于：

1. 作为学习材料。展示了如何把一个 Rust 工具链集成到现有的 JavaScript 生态中。
2. 作为过渡方案。在 Rolldown 正式发布前，想尝鲜 Oxc 的人可以用这个插件。
3. 作为参考实现。React Fast Refresh 的集成逻辑，sourcemap 合并的处理，这些代码可以被其他项目借鉴。

十四、总结

回到开头的问题：2026 年了，前端构建为什么还是慢？

答案是：工具链正在追赶硬件的脚步，只是还没追上。

从 Babel 到 esbuild，从 SWC 到 Oxc，每一代工具都在压榨更多性能。vite-plugin-oxc 是我在这条路上的一次尝试——用 Oxc 这套 Rust 工具链，给 Vite 的构建流程提提速。

核心实现其实不复杂：

• Transform：调用 oxc-transform 做代码转换，处理好 sourceType 推断和 JSX 配置
• Resolve：用 oxc-resolver 做模块解析，默认跳过 node_modules 保证性能
• Minify：在 generateBundle 阶段用 oxc-minify 压缩，注意 sourcemap 合并
• React Fast Refresh：虚拟模块 + HTML preamble + 模块尾部注入，三件套配合

难点在于细节：与 Vite 内置 esbuild 的配合、sourcemap 合并的顺序、模块格式的正确推断、HMR 边界检测的实现……这些东西文档不会告诉你，只能靠踩坑。

这个插件的代码开源在 GitHub 上，欢迎 star 和 PR。虽然它可能很快就会被 Rolldown 取代，但在那之前，希望它能给想了解 Vite 插件开发、Oxc 集成的同学一些参考。

前端工具链的进化永远不会停止。今天是 Oxc，明天可能是更快的东西。作为开发者，保持学习、保持好奇，可能是我们能做的最重要的事。

项目源码：github.com/Sunny-117/v… 欢迎 Star、Issue 和 PR！

参考资料

• Oxc 官方文档
• Vite 插件开发指南
• React Fast Refresh 原理
• esbuild 设计思路
• SWC 官方博客
• @ampproject/remapping 文档

^ 关注我，带你一起学GIS ^

通过上一节ArcPy，一个基于 Python 的 GIS 开发库简介[1]，我们知道了ArcPy作为ArcGIS桌面软件随附的一部分，要么集成在ArcGIS Desktop、ArcGIS Pro中，要么存在于ArcGIS Engine或者ArcGIS Server中。

文中以ArcGIS Pro3.5为例进行讲解。

1. 开发环境

本文使用如下开发环境，以供参考。

时间：2026年

系统：Windows 11

ArcGIS Pro：3.5

Python：3.11.11

2. 安装Arcpy

❝

ArcPy包是默认 Python 分布 arcgispro-py3（ArcGIS Pro 和 ArcGIS Server 随附）的一部分。通过克隆 arcgispro-py3 使用 ArcPy 创建环境。 可以使用 ArcGIS Pro 中的软件包管理器，或 Python 命令提示符中的 conda 命令行应用程序来克隆环境。

从 ArcGIS Pro 2.7 开始，当 ArcPy 包版本不冲突时，可将其添加到现有 Python 3 环境中。 要添加 ArcPy，可以使用 conda 从 Anaconda Cloud 上的 Esri 频道安装 ArcPy。 从 Python 命令提示符中，使用适当的版本号运行以下命令：

conda install arcpy=3.6 -c esri

需要注意的是即使ArcPy可以下载安装，但包仍需要ArcGIS Pro，必须安装它才能使用ArcPy。

3. 创建环境

3.1. 创建基础环境

随附在ArcGIS Pro、arcgispro-py3中的默认Python环境包含了对用于支持所有ArcGIS Pro Python使用案例的 200 多个软件包的访问权限。在某些情况下，此环境中包含的内容可能远远超出您的需求。 如果你只需要一个简单的环境，即仅包含运行地理处理工具和核心 ArcPy函数所需的最少依赖项的环境，则请使用arcpy-base环境。

arcpy-base明显小于 arcgispro-py3，其中仅包含几十个依赖项。要创建基于arcpy-base的环境，请运行以下conda命令：

conda create -n my-env arcpy-base

凭借一组有限的库，arcpy-base无法完全支持所有基于Python的ArcGIS Pro功能。arcpy-base仍可用于运行几乎所有地理处理工具和ArcPy函数，其中包括NumPy、GDAL 和Pandas等软件包。

仅使用 arcpy-base将限制对Notebooks（从 ArcGIS Pro 内部和外部）、ArcGIS API for Python 以及许多其他库（包括 matplotlib、pillow、pytest、requests、scipy、sqalachemy 和 swat）的访问权限。

3.2. 克隆arcgispro-py3环境

可以使用ArcGIS Pro包管理器来克隆arcgispro-py3环境。

打开ArcGIS Pro软件，点击Project（工程）。

点击包管理器Package Manager，可以看到当前Python环境已经下载的依赖。

右侧矩形红框查看当前的Python环境，可以点击设置按钮添加Python环境。

可以新建环境，也可以复制环境。

4. 注意事项

官方的建议是不要修改默认环境，否则很可能会影响ArcGIS Pro软件运行。

小小声说一下，我本地为了方便，一直使用的是默认arcgispro-py3环境，到目前为止，还没出现什么问题（何时因为环境问题导致ArcGIS Pro软件无法运行，我还会发文进行说明的）。

参考资料[1] 

ArcPy，一个基于 Python 的 GIS 开发库简介

❝

GIS之路-开发示例数据下载，请在公众号后台回复：vector

全国信息化工程师－GIS 应用水平考试资料，请在公众号后台回复：GIS考试

❝

GIS之路 公众号已经接入了智能 助手，可以在对话框进行提问，也可以直接搜索历史文章进行查看。

都看到这了，不要忘记点赞、收藏 + 关注 哦 ！

本号不定时更新有关 GIS开发 相关内容，欢迎关注 

GeoTools 开发合集（全）

OpenLayers 开发合集(全)

GDAL 开发合集（全）

GIS 影像数据源介绍

GeoJSON 数据源介绍

GIS 名词解释

ArcPy，一个基于 Python 的 GIS 开发库简介

GIS 开发库 Turf 介绍

GIS 开发库 GeoTools 介绍

GIS 开发库 GDAL 介绍

地图网站大全

从微信指数看当前GIS框架的趋势

Landsat 卫星数据介绍

OGC：开放地理空间联盟简介

中国地图 GeoJSON 数据集网站介绍

一、两者定位本质差异

这两个项目解决的是 AI 辅助开发流程中完全不同层面的问题，理解这一点是最关键的。

OpenSpec 解决的是 "做什么"（What） 的问题 —— 它是一个规格驱动开发（Spec-Driven Development）框架。核心理念是：在 AI 写代码之前，先让人和 AI 就需求规格达成共识。它通过 proposal → specs → design → tasks 的制品（artifact）依赖图来管理每一个变更的完整生命周期。

ECC 解决的是 "怎么做"（How） 的问题 —— 它是一个AI 编码助手的配置工具箱。核心理念是：提供一整套生产就绪的 agents、skills、hooks、commands、rules 和 MCP 配置，让 Claude Code（以及 Cursor/OpenCode/Codex）的执行能力最大化。

打个比方：OpenSpec 相当于项目经理的需求管理系统，ECC 相当于开发者的瑞士军刀。

二、核心机制对比

OpenSpec 的核心机制

OpenSpec 的核心是一个 制品依赖图引擎（Artifact DAG）。每个变更（change）被组织为一个独立文件夹，包含四类制品：

proposal.md 记录意图和范围，specs/ 通过 Delta 格式（ADDED/MODIFIED/REMOVED）描述行为变化，design.md 记录技术方案和架构决策，tasks.md 则是带复选框的实施清单。这些制品形成有向无环图的依赖关系，状态通过文件系统存在性自动检测（BLOCKED → READY → DONE）。

它的 OPSX 工作流打破了传统线性阶段的限制，采用流动式操作：你可以在实施过程中随时回头修改设计，不存在阶段门禁。同时它支持 24+ AI 编码工具（Claude Code、Cursor、Windsurf、Gemini CLI、GitHub Copilot、Kiro 等），做到了真正的工具无关性。

特别值得一提的是它的 Delta Spec 概念 —— 不是重写整个规格，而是描述变化量，这对存量项目（brownfield）极其友好。变更完成后通过 archive 操作将 delta 合并回主规格，形成持续演进的系统行为文档。

ECC 的核心机制

ECC 是一套模块化的配置组件库，包含 13 个专用子代理（planner、architect、tdd-guide、code-reviewer、security-reviewer 等），56 个 skills 覆盖前后端模式、持续学习、安全审计等领域，32 个斜杠命令（/plan、/tdd、/code-review、/e2e 等），以及 hooks 系统实现会话记忆持久化、自动格式化、战略性上下文压缩等自动化行为。

它的 Instinct 持续学习系统（v2）是亮点：自动从会话中提取模式，赋予置信度评分，支持跨团队导入导出，并可通过 /evolve 命令将相关直觉聚合为技能。

此外 ECC 的 AgentShield 安全扫描器（1282 个测试、102 条规则）可以扫描你的 AI 配置（CLAUDE.md、hooks、MCP 等）中的漏洞和注入风险，甚至支持三个 Opus 代理的红队/蓝队/审计流水线。

三、各自优缺点

OpenSpec

优点： 工具无关性是它最大的战略优势。支持 24+ AI 工具意味着团队不会被锁定在某个特定 IDE 或 AI 提供商上，前端用 Cursor、后端用 Claude Code 的团队可以共享同一套规格流程。Delta Spec 机制为存量项目提供了优雅的增量规格管理。自定义 schema 能力让团队可以定义自己的制品类型和依赖关系，比如加入 research 步骤。作为 npm 包分发（openspec init 一条命令初始化）降低了团队推广门槛。同时，制品文件夹结构天然支持 Git 版本控制和代码评审。

缺点： 它不涉及代码执行层面的优化，不提供 agent、hook 或 coding skill。对于小型快速迭代任务（hotfix、小 bug）流程可能显得重。需要团队养成写规格的习惯，存在文化适配成本。它也没有 token 优化、上下文管理、会话持久化等运行时增强能力。

ECC

优点： 开箱即用的生产级配置经过了实际产品构建的验证（Anthropic 黑客松获奖作品）。token 优化策略具体且实用（模型选择、thinking token 限制、compaction 阈值），能显著降低成本。多语言 rules 架构（common/ + typescript/ + python/ + golang/）适配不同技术栈。Instinct 学习系统让团队经验可以积累和传承。AgentShield 安全扫描填补了 AI 配置安全性的空白。同时跨平台支持（Claude Code、Cursor、Codex CLI、OpenCode）也相当完善。

缺点： 以 Claude Code 为主要目标，对其他工具的支持虽在扩展但存在功能差距。缺少需求-设计-实施的结构化流程管理，/plan 命令只是调用 planner agent 生成蓝图，不像 OpenSpec 那样有制品依赖图和生命周期管理。配置项繁多（56 skills + 32 commands），新用户需要时间理解哪些组件适合自己。Rules 无法通过插件自动分发（Claude Code 平台限制），需要手动安装。

四、最佳实践姿势

OpenSpec 最佳实践

适合的场景是中大型功能、跨团队协作、需要需求对齐的工作。推荐的流程是：对于明确需求用 /opsx:propose 快速启动然后 /opsx:apply 实施；对于模糊需求先用 /opsx:explore 探索再决定方案；保持每个 change 聚焦于一个逻辑单元；archive 前用 /opsx:verify 验证实现与规格的一致性。

命名规范也很重要：用 add-dark-mode、fix-login-redirect 这种描述性名称，避免 feature-1、wip 这种模糊命名。

ECC 最佳实践

token 管理是关键：默认使用 sonnet，只在复杂架构推理时切换 opus；将 MAX_THINKING_TOKENS 设为 10000，CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 设为 50；MCP 服务器保持 10 个以内，工具总数 80 以内。

工作流模式上：新功能用 /plan → /tdd → /code-review 三步走；修复 bug 先用 /tdd 写失败测试再修复；发布前用 /security-scan + /e2e + /test-coverage 三重验证。任务之间用 /clear 重置上下文，逻辑断点处用 /compact 压缩。

五、面向公司前后端团队的整合方案

基于对两者的深入分析，我推荐的整合策略是 OpenSpec 做流程骨架 + ECC 做执行引擎，两者互补而非替代。

第一层：需求与规格管理（OpenSpec）

在项目根目录执行 openspec init 初始化，所有非 trivial 的功能开发都从 /opsx:propose 或 /opsx:explore 开始。前端和后端开发者在同一个 openspec/changes/ 目录下协作，但各自维护各自领域的 specs（如 specs/api/、specs/ui/）。利用 OpenSpec 的工具无关性，让用不同 IDE 的团队成员共享同一套规格流程。

第二层：编码执行增强（ECC）

在每个开发者的环境中安装 ECC 插件并配置对应语言的 rules（前端装 common/ + typescript/，后端根据栈选择 python/ 或 golang/）。利用 ECC 的 agents 体系：planner 和 architect 辅助 OpenSpec 的 proposal 和 design 阶段，tdd-guide 和 code-reviewer 在 /opsx:apply 实施阶段提供质量保障。配置 token 优化策略统一降本。

第三层：质量与安全闭环

实施完成后，用 /opsx:verify 验证规格一致性（OpenSpec），同时用 ECC 的 /security-scan、/test-coverage、/e2e 进行技术层面验证。用 AgentShield 定期扫描团队的 AI 配置安全性。

第四层：知识积累与传承

利用 ECC 的 Instinct 系统自动学习团队模式，定期 /instinct-export 导出分享。OpenSpec 的 archive 机制自动积累系统行为规格，新人 onboard 时直接阅读 openspec/specs/ 了解系统当前行为。

推荐的完整工作流

一个典型的功能开发流程如下：

1. PM/开发者启动 → /opsx:explore（OpenSpec，厘清需求）
2. 需求明确后 → /opsx:propose（OpenSpec，生成 proposal + specs + design + tasks）
3. 前后端评审制品 → 在 Git PR 中 review openspec/changes/feature-name/
4. 实施阶段 → /opsx:apply + ECC 的 /tdd 和 /code-review（OpenSpec 管进度，ECC 保质量）
5. 验证阶段 → /opsx:verify + /security-scan + /e2e
6. 完成归档 → /opsx:archive（delta specs 合并回主规格）

这套方案的核心价值是：OpenSpec 确保团队在写代码前达成共识（减少返工），ECC 确保写代码时效率和质量最大化（降低成本）。两者结合覆盖了从需求到交付的完整 AI 辅助开发链路。

今晚小米巴塞罗那发布会的第一个 Ultra，是一辆滑板车。

发布会详尽展示了小米电动滑板车 6 Ultra 全方位的硬件升级，尤其是「Ultra 级」的性能。台上的产品经理强调，超大杯的命名，来源于设计与全地形能力的全面提升。

是的，滑板车也讲究全地形能力……

不过，暂时就先不在这里展开介绍这辆滑板车了，因为今晚真正的重磅产品是——小米 Vision Gran Turismo 概念超跑（下文简称小米 Vision GT）。

小米汽车首席设计师李田原上来就说，小米 Vision GT 在直线极速和弯道下压力之间找到了一个完美的平衡点。

对于这辆车的外观，最直观的感受就是「克制」，它并没有很复杂的空气动力学套件。

小米 Vision GT 整车采用自然风雕刻的极简设计理念，车身上的每一个线条和开孔都具备真实的空气动力学功能，没有任何纯粹服务于视觉审美的多余部件。

从侧面观察车身，驾驶舱呈现出悬浮的水滴状结构，外部气流可以直接越过车顶或穿过座舱下方的通道；底部的主动式扰流板会根据行驶状态，实时调节风阻与下压力的平衡。

车身尾部采用了独特的船型结构设计，外围有一个巨大的环形出风口，贯穿式的镂空尾灯很好地融入了出风口结构中。

李田原在现场抛出了三个工程数据：小米 Vision GT 的风阻系数做到了 0.29Cd， 下压力达到 1.2 吨，气动效率高达 4.1。

李田原表示，实现这些亮眼数据依靠两项非常特别的工程设计。

第一项是主动尾流控制系统。

小米在 Vision GT 的尾灯周围布置了密集的微孔，系统会根据车速和转向角度主动向后方喷射高压气流，来「推开」尾部产生的乱流。

第二项是磁悬浮低风阻轮毂盖。

小米 Vision GT 的轮毂外部覆盖了一层半透明的面板，车辆高速行驶时，它会依靠磁力系统保持静止，让两侧的气流顺利通过。与此同时，内部的轮毂会飞速转动，持续为高负荷运转的制动系统提供风冷效果。

视线转向座舱内部。

开超跑通常是一件体力活，运动化的座舱通常很难让人放松下来。为了追求极致的路感反馈。性能车里塞满的总是非常狭窄且僵硬的硬核座椅。

小米为了甩掉这种让人浑身紧绷的刻板印象，为 Vision GT 做了一套舒展的环抱式沙发座舱。

它的座舱没有任何生硬的物理隔断，整个内饰完全连成了一体。李田原称，坐进这辆车里的真实体验更接近于待在一间充满现代感的起居室里，驾驶员既可以挺直腰板去挑战赛道，跑累了也能完全放松地仰靠在宽大的座椅里。

驾驶员前方的方向盘采用 X 型设计，右手边还有一排做工上乘的实体按键。至于智能座舱该有的交互功能，在这里也被处理得非常克制。

作为一辆超跑，小米 Vision GT 的车机界面完全去除了繁杂的菜单层级， 屏幕只会跟随当前的驾驶模式自适应呈现最关键的行驶数据，信息流动的方式非常自然。

在这辆车上，人与车的交互被处理成了日常交谈的舒缓节奏，系统会通过视觉系统感知用户的状态，主动调整座舱的环境氛围。

发布会的最后，小米还展示了一款配套硬件——一套专门为这台跑车打造的模拟器。

虽然咱们买不到小米 Vision GT，但还是可以在《GT 赛车 7》里稍微体验一下的。

#欢迎关注爱范儿官方微信公众号：爱范儿（微信号：ifanr），更多精彩内容第一时间为您奉上。

爱范儿 | 原文链接 · 查看评论 · 新浪微博

一、需求来源

当页面元素特别多，比较杂，又必须获取某个组件尺寸位置时，一个个加 GlobalKey 有太麻烦，这是使用一个封装好的组件就特别有用了。然后就有了 NRenderBox 组件，可以打印出子组件的位置及尺寸。

二、使用

NRenderBox(
  child: Container(
    padding: EdgeInsets.symmetric(horizontal: 8, vertical: 4),
    decoration: BoxDecoration(
      color: Colors.transparent,
      border: Border.all(color: Colors.blue),
      borderRadius: BorderRadius.all(Radius.circular(0)),
    ),
    child: Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        NNetworkImage(
          width: 50,
          height: 60,
          url: AppRes.image.urls.random ?? '',
        ),
        Text("选项"),
      ],
    ),
  ),
)

flutter: NRenderBox rect: Rect.fromLTRB(88.5, 322.0, 157.5, 413.0)

三、NRenderBox源码

import 'package:flutter/material.dart';

/// 点击打印尺寸
class NRenderBox extends StatefulWidget {
  const NRenderBox({
    super.key,
    required this.child,
  });

  final Widget child;

  @override
  State<NRenderBox> createState() => _NRenderBoxState();
}

class _NRenderBoxState extends State<NRenderBox> {
  final renderKey = GlobalKey();

  RenderBox? get renderBox {
    final ctx = renderKey.currentContext;
    if (ctx == null) {
      return null;
    }
    final box = ctx.findRenderObject() as RenderBox?;
    return box;
  }

  Offset? get renderPosition {
    return renderBox?.localToGlobal(Offset.zero);
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      key: renderKey,
      onTap: () {
        if (renderBox == null) {
          return;
        }
        final position = renderPosition;
        final size = renderBox!.size;
        final rect = Rect.fromLTWH(position!.dx, position.dy, size.width, size.height);
        debugPrint("$widget rect: $rect");
      },
      child: widget.child,
    );
  }
}

github

top is a command-line utility that displays running processes and system resource usage in real time. It helps you inspect CPU usage, memory consumption, load averages, and process activity from a single interactive view.

This guide explains how to use top to monitor your system and quickly identify resource-heavy processes.

top Command Syntax #

The syntax for the top command is as follows:

top [OPTIONS]

Run top without arguments to open the interactive monitor:

top

Understanding the top Output #

The screen is split into two areas:

• Summary area — system-wide metrics displayed in the header lines
• Task area — per-process metrics listed below the header

A typical top header looks like this:

top - 14:32:01 up 3 days, 4:12, 2 users, load average: 0.45, 0.31, 0.28
Tasks: 213 total, 1 running, 212 sleeping, 0 stopped, 0 zombie
%Cpu(s): 3.2 us, 1.1 sy, 0.0 ni, 95.3 id, 0.2 wa, 0.0 hi, 0.1 si, 0.0 st
MiB Mem : 15886.7 total, 8231.4 free, 4912.5 used, 2742.8 buff/cache
MiB Swap: 2048.0 total, 2048.0 free, 0.0 used. 10374.2 avail Mem
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
1234 www-data 20 0 123456 45678 9012 S 4.3 0.3 0:42.31 nginx
987 mysql 20 0 987654 321098 12345 S 1.7 2.0 3:12.04 mysqld
5678 root 20 0 65432 5678 3456 S 0.0 0.0 0:00.12 sshd

CPU State Percentages #

The %Cpu(s) line breaks CPU time into the following states:

• us — time running user-space (non-kernel) processes
• sy — time running kernel processes
• ni — time running user processes with a manually adjusted nice value
• id — idle time
• wa — time waiting for I/O to complete
• hi — time handling hardware interrupt requests
• si — time handling software interrupt requests
• st — time stolen from this virtual machine by the hypervisor (relevant on VMs)

High wa typically points to a disk or network I/O bottleneck. High us or sy points to CPU pressure. For memory details, see the free command. For load average context, see uptime .

Task Area Columns #

Common Interactive Controls #

Press these keys while top is running:

Refresh Interval and Batch Mode #

To change the refresh interval (seconds), use -d:

top -d 2

To run top in batch mode (non-interactive), use -b. This is useful for scripts and logs:

top -b -n 1

To capture multiple snapshots:

top -b -n 5 -d 1 > top-snapshot.txt

Filtering and Sorting #

Start top with a user filter:

top -u root

To monitor a specific process by PID, use -p:

top -p 1234

Pass a comma-separated list to monitor multiple PIDs at once:

top -p 1234,5678

To show individual threads instead of processes, use -H:

top -H

Thread view is useful when profiling multi-threaded applications — each thread appears as a separate row with its own CPU and memory usage.

Inside top, use:

• P to sort by CPU
• M to sort by memory
• u to show a specific user

For deeper process filtering, combine top with ps , pgrep , and kill .

Quick Reference #

Troubleshooting #

top is not installed Install the procps package (procps-ng on some distributions), then run top again.

Display refresh is too fast or too slow Use -d to tune the refresh rate, for example top -d 2.

Cannot kill or renice a process You may not own the process. Use sudo or run as a user with sufficient privileges.

FAQ #

What is the difference between top and htop? top is available by default on most Linux systems and is lightweight. htop provides a richer interactive UI with color coding, mouse support, and easier navigation, but requires a separate installation.

What does load average mean? Load average shows the average number of runnable or uninterruptible tasks over the last 1, 5, and 15 minutes. A value above the number of CPU cores indicates the system is under pressure. See uptime for more detail.

What is a zombie process? A zombie process has finished execution but its entry remains in the process table because the parent process has not yet read its exit status. A small number of zombie processes is harmless; a growing count may indicate a bug in the parent application.

What do VIRT, RES, and SHR mean? VIRT is the total virtual address space the process has reserved. RES is the actual physical RAM currently in use. SHR is the portion of RES that is shared with other processes (for example, shared libraries). RES minus SHR gives the memory used exclusively by that process.

Can I save top output to a file? Yes. Use batch mode, for example: top -b -n 1 > top.txt.

Conclusion #

The top command is one of the fastest ways to inspect process activity and system load in real time. Learn the interactive keys and sort options to diagnose performance issues quickly.

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

出品|虎嗅汽车组

作者|邢书博

头图|AI生成

“德国汽车在华销量疲软是战略失误。”

2月25日-26日，德国总理默茨开启访华之旅，在访谈期间罕见德对德国车企提出了批评。

随行的商业代表团中，宝马集团董事长齐普策、梅赛德斯-奔驰集团股份公司董事会主席康林松、大众汽车集团管理董事会主席奥博穆这三位德系车企“一把手”同台参访。

规格很高，意味着德系车厂商，在华市场疲软问题需要解决，且时间紧迫。

默茨访华来源新华社

针对德国车企认为中国市场不够开放等问题，默兹认为“中国汽车市场已足够开放，允许外资独立设厂，华晨宝马、大众安徽等德方持股比例颇高，但德系车仍然销量不佳。” 公开资料显示，宝马在华合资车占比75%，大众安徽合资公司占比也是75%。德方事实上主导了这两家合资公司的产品研发销售品牌。

默兹认为销量不佳的主要原因是德系车在华战略失误：2016年大众推出廉价燃油车战略导致错失电动化机遇，且对插电混动技术不屑一顾。默兹强调说：“德国汽车应承认在插混领域落后，向中国车企学习，尊重中国市场和用户需求，如此才有未来。”

《经济学人》载文指出，越来越多的德国企业正在中国推进“本土化”战略：利用中国的供应链，和当地员工共同开发产品，将利润重新投资于中国。

德国车企不仅在插混领域缺失话语权，在三电系统、智能化方面也有不足之处；但在机械素质、底盘调教和长期品质等方面依然处于领先地位。

燃油车优势和新能源不足如同天平两端的砝码，德系车该如何取舍才能获得市场与口碑的平衡？

宝马奔驰死磕智驾三电，震荡中寻求突破

批评归批评，合作成果也要有。报道称默茨访问期间，在汽车领域双方企业达成了十余项商业协议。宝马与宁德时代围绕降低电动汽车整车碳足迹达成合作；奔驰中国与中国科技企业Momenta宣布进一步深化双方在未来出行领域的合作。

首当其中的是宝马。

“忽略中国广博市场与广阔创新潜力的企业，必将错失全球经济增长和商业成功的重大机遇。”宝马董事长齐普策公开表示。中国是宝马全球第二大销售市场，2025前三季度占比超26%，但同比下滑11.2%，市占率回到了十年前的水平。

为了重振中国市场，宝马已在沈阳生产基地累计投资超1200亿元，在华布局四大研发创新基地与三家软件公司，构建起完整的本土化研发、生产与供应体系。

一个重要的里程碑是，宝马首款国产新世代车型——新世代BMW iX3长轴距版，将于2026年4月北京车展全球首发。智驾底盘电池都与国产厂商深度绑定。宝马进行了最大程度的本土化研发，希望以此重新赢得中国消费者青睐。

慕尼黑车展中展示的新世代BMW iX3

 其最大亮点底盘性能，号称“刹车无感”，看来宝马还是希望在底盘架构和人机操控方面打动人心。这与其一贯的品牌形象相一致。

不过对于宝马老车主来说，对智驾还是人驾有自己的看法。

“宝马现在语音助手都做得一般。我今早喊了好几遍‘你好宝马，导航到某处’，车机愣是在显示地址后就停滞不动了，无法继续用语音完成导航任务。感觉整个行业陷入了智能化内卷，很多时候忽视了汽车作为交通工具的安全属性。”

街访中有宝马车主表示，如果类似语音导航等智能化功能做不好，不如一开始就不要放到车上，反而会增加安全风险。他认为有时智能功能没有反而会提高人的安全意识：“自动大灯开久了忘了驾校学的手动怎么打灯了。有时候需要变道忘了打灯很危险。”车主说。

首先普及自动大灯的是奔驰。自适应巡航、车身稳定系统、自动紧急制动等自动化功能也是如此。

可以说燃油时代奔驰不仅是豪华代名词，也是科技先锋队。

但在2026年，对奔驰来说，尽快让旗下车型从传统豪华步入科技豪华才是当务之急。

2月14日，奔驰发布一项重大人事调整：段建军因个人原因辞去总裁兼首席执行官职务，他的职位自3月1日起由李德思（Daniel Lescow）接任。

段建军在去年的奔驰新品发布会上对当下新势力恶意对标表达不满，称“奔驰不怕被对比，对不合理的、错误的对标，奔驰不会放弃做出严正交涉。”。此前余承东在尊界发布会上对标迈巴赫，视频中显示奔驰在雪地中出现打滑甩尾问题。段建军则认为打滑是“人为刻意加大了方向盘角度，延迟回正”。

“豪华不止一种诠释方式，客户体验最重要。 ”

段建军希望通过正面反驳让潜在车主继续认可奔驰的豪华认知和江湖地位。

然而事与愿违，强调奔驰品牌魅力并不能让市场认可。2025年，奔驰在中国市场交付了55.19万辆新车，同比下滑19%，这是其销量连续第二年下滑超过10%。说到底，一台台消费者开上路的奔驰车，才是奔驰品牌魅力的来源。品牌的基石还是产品本身。

新任奔驰中国掌门人李德思则是产品出身。他被视为“最懂中国的德国人”，曾深度参与Smart品牌的重塑和电动化转型，并主导了奔驰的数字化业务。

奔驰近期宣布，2026年奔驰与momenta合作的智驾方案已搭载于全新纯电CLA。2026年，奔驰将于年内落地9款新车型，覆盖高速、城区、泊车全场景。

基于MB.EA专属纯电平台也将于今年发布，告别了过去“BBA油改电”的刻板印象。奔驰还提出了“油电同智”战略，让油车也能和电车一样步入智能化时代。

大众发力“油电同智”，胜算大吗？

“油电同智”不止奔驰一家在提。大众作为燃油时代无可争议的行业霸主，在电动时代一样有紧迫感。

大众在燃油车方面依旧能打，2025年交付量超257万辆，占中国燃油车市场超22%的份额，蝉联合资车企销量第一、燃油车销量第一，增长了0.6%。但新能源车进展缓慢。新能源车合并销量之后，大众在华整体销量下滑8%，且连续两年下滑。

因此，大众提出“油电同智”理念，既是为了海量油车老车主，不改变油车使用习惯也能用上新智驾；也是为了新能源销量，通过老带新实现增长。

不过理想很很美好，油车智驾功能还是存在着现实问题。

过去大家都认为电车比油车在智能化上更有优势，因为有大电池。

但实际上，电车的大电池只用来给动力系统使用。智驾系统上电动车和燃油车一样，都是使用的车内的低压电池，如12V/48V电源。这为“油电同智“提供了可能性。

真正阻碍油车上智驾的，不仅仅是电力系统问题，还有电器架构、市场和品牌等问题。

店内实拍大众油电共进标语

具体说来有三个方面的问题——

第一，电器架构上油车先天“生理”缺陷。

燃油车采用分布式电子电气架构，车辆由几十个独立ECU（电子控制单元）分散控制。这就像多个“小作坊”各自为政，算力分散且无法OTA升级。而智驾需要集中式架构和强大的中央计算平台，燃油车在供电电压、散热设计、通信速率上均难以支持高功耗的智驾芯片。动力曲线方面，燃油车智驾匹配也是大问题，短期内很难追上系能源；

第二，市场上油车智驾，老百姓不认可。

智驾依赖硬件预埋和软件持续迭代，成本高昂。燃油车销量下滑导致利润摊薄，车企不敢将巨额研发投入在“非走量”的传统车型上。

同时消费者普遍认知“智能是新势力的标签”，导致油车即便配了智驾也难以产生溢价，形成“越不投入越落后，越落后越没人买”的恶性循环。比如大众途昂 Pro，搭载 IQ.Pilot 智驾系统，支持高快NOA，销量惨淡。 被批评为“反向创新”，入门版配置严重阉割，完整智驾需高价选装，导致上市首月订单仅832辆。

第三，最关键一点，无论大众还是奔驰宝马，不愿“革自己的命”。

燃油车时代，品牌溢价依赖于发动机、变速箱等机械素质。成本低利润高。而全面转向智驾需要企业重构供应链（从博世等Tier1转向英伟达等科技公司）和改变盈利模式。传统车企的核心利润仍来自燃油车，若在油车上普及智驾，会加速蚕食原有高利润车型的市场，因此态度上犹豫不决。

最早智驾从2016年就开始发展，但2016年大众缺没有发力智驾，而是选择通过简配低价卖更多的平价燃油车。保利润还是保增长，大众选择了后者。

而现在，大众一面要保证燃油车的口碑和市场，一面要发力纯电和插混，那么“油电同智”就成了必选项。

目前，大众已于地平线成立合资芯片公司酷睿程，入股电池厂商国轩高科并成为第一大股东，以弥补其在芯片、电池等方面的短板。

大众集团CEO奥博穆明确表示，“中国对大众而言远不止是销售市场，更是全球核心创新中心与技术策源地。”

可以说，无论大众的“油电同智”战略胜算几何，大众也必须一条路走到黑。无论从保市场还是保技术，都没有第二条路。

最后的话

最后来看，无论奔驰宝马还是大众，作为全球车企，均在急切地智能化转型与中国供应链深度绑定。从过去引领市场建立标准，到目前在智驾、电池、插混方面全方位与中方共建。

除了为保住中国燃油车市场份额，更重要的是希望借助中国的供应链和相对廉价的生产成本，用来返销欧洲等全球市场。

事实上，中德车企方面的合作信号在今年春节期间已有端倪。2026年2月10号，欧盟宣布大众安徽公司生产的CUPRA Tavascan车型，出口欧洲将减免20.7%的反补贴税。成为首例获得欧盟豁免的国产车型。CUPRA Tavascan与大众旗下与众06共享技术平台，后者在国内亦有销售。

这是中欧汽车经贸博弈走向缓和的标志，也是跨国车企在全球化逆风下寻求顺势而为的缩影。与其说是德系车在补新能源课，不如说是中德共建，寻求燃油车与新能源的新平衡。

尤其是在中国市场，如何能让三亿燃油车主用户上智能化的燃油车，这是奔驰宝马大众都需要思考的问题。

下载虎嗅APP，第一时间获取深度独到的商业科技资讯，连接更多创新人群与线下活动

前阵子，我无意中发现我们的应用在 App Store 上悄然出现了几条差评，但团队里似乎没人注意到。这让我意识到一个严重的问题：如果我们不能及时听到用户的声音，怎么能及时发现应用的不足，留住用户呢？ 更令人担忧的是，潜在用户在下载前往往会浏览评论区，一条未被回应的负面评价，可能就足以让他们转身离开，影响新增转化。

如果能在用户留下评论（尤其是差评）的第一时间收到通知，我们就能快速响应、修复问题、安抚情绪，甚至将一次不满转化为一次忠诚度的提升。更重要的是，积极、真诚地回复用户评论，不仅能展现团队的专业与负责，还能向所有观望者传递一个信号：我们在乎每一位用户。

本篇文章将从实操角度出发，为不熟悉苹果和谷歌开发者后台的开发或运营同学，讲解如何监控苹果谷歌商店的评分评论，以及如何回复用户评论，为大家提供一些帮助。

一、苹果

苹果开发者后台 appstoreconnect.apple.com/，需要 客户支持 权限。

1、如何监控评分和评论

苹果后台目前不支持收到新的评分评论后邮件通知开发者。只支持“开发者回复”（当顾客编辑你已回复的评论时，你将收到电子邮件），如需开启“开发者回复”邮件通知，按下面步骤操作：

登录 App Store Connect。
点击右上角的用户头像，进入 “用户和访问”。
选择你的账户，在左侧菜单点击 “通知”。

Tips：“收到评分评论后邮件通知开发者”，这个功能在旧版 iTunes Connect 中曾经存在，但在新版 App Store Connect 中已被移除。猜测苹果可能不想开发者过度关注单条评分评论。

如果目前想要监控苹果商店的评分评论，有几个方案可参考：
1、使用官方的 App Store Connect App，每天刷一刷，自己主动去看。App内可以设置“接收用户评分”通知，但不确定现在还是否有效。
2、苹果官方提供了App Store Connect API，可以自己开发程序拉取用户评分，再进一步做监控。
3、滴答清单定个周期性提醒，每天上班打开商店详情瞅一眼，现在苹果上线了Web版AppStore了，瞅一眼也很方便。
4、借助第三方平台。

2、查看和回复用户评论

（1）通过网页端查看

登录苹果开发者后台，appstoreconnect.apple.com/

评分评论入口：分发 - 评分和评论

点击“回复”可以回复用户评论

（2）通过官方App "App Store Connect" 查看

iOS端下载地址：apps.apple.com/cn/app/app-…
（如果你搜不到可能是你手机系统版本太低了。没有安卓端。）

App Store Connect App核心功能：
-- 销售与趋势监控（查看 App 的下载量、销售额）
-- 版本状态管理（跟踪审核状态，回复审核）
-- 用户评论处理（查看和回复评论）

App Store Connect内查看评分及评论入口：

3、重置总评分

发布新版本到 App Store 时（必须更包），你可以重置 App 总评分。重置后，你的 App Store 产品页面将显示说明，提示顾客 App 的总评分最近已重置。此说明将一直显示，直到有足够多的顾客对新版本进行了评分且页面出现新的总评分。

请注意，重置总评分并不会重置顾客评论，App Store 仍将继续显示历史的顾客评论。

二、Google

Google开发者后台 play.google.com/console/dev…，需要 用户反馈 权限。

1、如何监控评分和评论

Google官方支持收到新的评论后邮件提醒开发者，并支持按应用、评分星级设置不同的提醒开关。注意：邮件提醒默认是关闭的，需要手动开启。请按下列步骤操作。

Google开发者后台 - 设置 - 个人邮件通知（这个只会改你个人的通知设置，不会改整个团队的）

按需将邮件提醒开关打开，修改后记得保存。

如果你的账号拥有开发者账号下多个App的权限，默认是所有应用都给你发邮件，点击下图位置，可以选择哪些应用接收邮件。

收到新的评论后，Google会给你推邮件，模板样式如下，包含了应用名称、评分星级、评论内容，不用打开Google后台就能看到评论内容，很方便。
注意：如果你接收了多个应用的邮件，请留意邮件标题里App的名字。

2、查看和回复用户评论

（1）网页端

Google后台 - 应用 - 监控与改进 - 评分与评价。

Google后台的评论，Google会默认帮你翻译成你的语言，很贴心。如果你想看原始评论，点击“显示原评论”查看。你也可以在这里回复用户的评论。

（2）官方 Google Play Console App

Google也像苹果一样，提供了官方的供开发者维护自己App的应用，Google Play Console App。你可以通过它在移动端方便的看评分和回复评论。

iOS端：apps.apple.com/cn/app/goog…
安卓端：play.google.com/store/apps/…

Google Play Console App 核心功能：

• 查看数据指标：监控安装量、卸载量、更新量以及应用的崩溃率（ANR/Crash）。
• 回复用户评论：及时查看并回复用户的评价，这对于维护 App 评分至关重要。
• 订单管理：查看应用内购买和订阅的订单详情，甚至可以进行简单的退款操作。
• 发布状态监控：跟踪应用版本的审核进度和发布状态。

3、Google不支持重置评分评论

Google不像苹果那样可以主动重置评分。虽然你不能手动重置，但 Google Play 的评分系统是动态权重的，更加偏重于近期（Recent）的用户评分权重会更高。

这意味着：
（1）如果你的应用过去因为有 Bug 而评分很低，只要你在新版本中修复了问题，随着新用户和老用户在近期的好评增多，你的平均分会逐渐回升。
（2）时间是最好的解药：只要新版本的体验确实提升了，评分曲线会自动向好的方向修正。

三、结束语

其实维护应用商店的评论，并不需要多么复杂的流程或高深的技巧，但你做了和没做，用户感受是不一样的，每个人都希望被尊重，用真诚打动你的用户吧！

希望这篇文章能给你一点帮助。如果你有更好的监控方法，欢迎留言交流。

参考文档
【苹果官方文档】查看评分和评论

📋 目录

• 一、Kingfisher 概述与历史演进
  • 1. 框架简介
  • 2. 技术演进与版本脉络
  • 3. 图层处理在整体架构中的位置
• 二、图像处理管线（ImageProcessor Pipeline）
  • 1. ImageProcessItem 与双态输入
  • 2. ImageProcessor 协议与标识符
  • 3. 下采样（Downsampling）与 Resizing 的区分
  • 4. 多处理器链式组合
• 三、解码、缓存与处理器的协同
  • 1. 检索流程与缓存键
  • 2. CacheSerializer 与磁盘格式
  • 3. 应用场景与选型
• 四、类结构图分析
  • 1. 核心类总览
  • 2. 模块划分与依赖关系
  • 3. 加载与缓存类结构
  • 4. 处理管线与 Processor 类结构
  • 5. View 扩展与调用链
• 五、与系统及业界实践的衔接
  • 1. Apple 图像与图形最佳实践
  • 2. 与 SDWebImage 的对比
• 六、设计模式与编程思想
  • 1. 设计模式应用
  • 2. 编程思想精华
• 七、使用示例与最佳实践
• 延伸阅读（掘金系列）
• 参考文献

一、Kingfisher 概述与历史演进

1. 框架简介

Kingfisher 是一款面向 Apple 平台（iOS / macOS / tvOS / watchOS）的纯 Swift 异步图片下载与缓存库，由 onevcat（王巍）维护。其「图层处理」相关能力以 ImageProcessor 为核心：在「从数据到图像」以及「从图像到图像」的管线中，完成解码、缩放、圆角、模糊、着色等处理，并与 ImageCache（内存 + 磁盘）、ImageDownloader 协同，形成「请求 → 缓存查询 → 下载 → 处理 → 缓存 → 展示」的完整流程 [1][2]。

与 SDWebImage（Objective-C 为主）相比，Kingfisher 采用协议导向与 Options 模式，图层处理通过统一的 ImageProcessor 协议和 ImageProcessItem 双态输入抽象，便于扩展与组合。

2. 技术演进与版本脉络

Kingfisher 的图层处理能力随版本逐步增强，并与缓存、下载模块解耦清晰。

5.0 是重要分水岭：处理管线与缓存键（含 processorIdentifier）深度结合，使「同一 URL + 不同 Processor」对应不同缓存条目，原图与处理后图可并存。

3. 图层处理在整体架构中的位置

下图概括从「资源（URL / ImageDataProvider）」到「显示到视图」的流程，并标出 ImageProcessor 所在阶段。

flowchart LR
    subgraph 输入
        A[URL / ImageDataProvider]
    end
    subgraph 获取数据
        B[ImageDownloader / Provider.data]
    end
    subgraph 处理层
        C[Data]
        D[ImageProcessor 管线]
        E[KFCrossPlatformImage]
    end
    subgraph 缓存与输出
        F[ImageCache]
        G[ImageView / KFImage]
    end
    A --> B --> C --> D --> E --> F --> G

要点：

• ImageProcessor 的输入可以是 Data（未解码）或 Image（已解码）；输出为 Image。因此它同时覆盖「Data → Image」（如 DefaultImageProcessor、DownsamplingImageProcessor）和「Image → Image」（如 RoundCorner、Blur、Resizing）两类操作。
• 处理在 KingfisherManager 协调下、通常在后台队列执行，避免阻塞主线程，符合 Apple 图像最佳实践 [8]。

二、图像处理管线（ImageProcessor Pipeline）

1. ImageProcessItem 与双态输入

Kingfisher 用 ImageProcessItem 表示处理器的输入，有两种情况 [9]：

public enum ImageProcessItem: Sendable {
    /// 已解码的图像，处理器在其上做几何/像素变换
    case image(KFCrossPlatformImage)
    /// 原始数据，处理器需负责解码（或解码+变换）
    case data(Data)
}

设计意图：

• 统一接口：同一套管线既可处理「仅解码」（Data → Image），也可处理「仅变换」（Image → Image），或「解码 + 变换」（Data 经多个 Processor 最终得到 Image）。
• 避免重复解码：当管线中第一个 Processor 已将 Data 转为 Image 后，后续 Processor 收到 .image(...)，只需做几何/滤镜等操作，无需再次解码。

数据流概念：

flowchart LR
    subgraph 管线输入
        I[Data]
    end
    subgraph P1[Processor 1]
        I --> D1[解码/下采样]
        D1 --> O1[Image]
    end
    subgraph P2[Processor 2]
        O1 --> D2[圆角/缩放等]
        D2 --> O2[Image]
    end
    O2 --> Out[输出]

2. ImageProcessor 协议与标识符

ImageProcessor 协议是 Kingfisher 图层处理的核心抽象 [9][10]：

协议 ImageProcessor:
    属性 identifier: String   // 唯一标识，参与缓存键
    方法 process(item: ImageProcessItem, options: KingfisherParsedOptionsInfo) -> KFCrossPlatformImage?

• identifier：相同功能/参数的 Processor 应返回相同字符串，用于缓存键。官方建议使用反向域名（如 com.onevcat.Kingfisher.RoundCornerImageProcessor(20)），且不要与 DefaultImageProcessor 的 "" 冲突。
• process：返回 nil 表示处理失败，管线会报错并中止；若输入已是 .image 且当前步骤可透传，可返回原图以继续后续 Processor。

伪代码：管线执行：

函数 runPipeline(item: ImageProcessItem, processors: [ImageProcessor], options) -> Image?:
    current = item
    对每个 p in processors:
        若 current 为 .data 且 p 只支持 .image:
            current = .image(DefaultImageProcessor.default.process(current, options))
        若 current 为 nil: 返回 nil
        next = p.process(current, options)
        若 next 为 nil: 返回 nil
        current = .image(next)
    返回 current

许多内置 Processor（如 RoundCorner、Blur）在收到 .data 时，会先通过 DefaultImageProcessor.default |> self 将 Data 解码为 Image，再对 Image 做自身变换，从而复用同一套协议。

3. 下采样（Downsampling）与 Resizing 的区分

Kingfisher 明确区分两种「变小」的方式，对应不同的内存与 CPU 成本 [10][11]。

3.1 DownsamplingImageProcessor

• 输入：仅 Data（压缩数据）。在解码阶段直接生成小尺寸位图，而不是先解码全图再缩放。
• 实现：基于 ImageIO 的 CGImageSourceCreateThumbnailAtIndex，通过 kCGImageSourceThumbnailMaxPixelSize 等选项限制最大边长，在解码器内部只生成缩略图级像素缓冲。
• 优势：内存占用与目标尺寸相关，避免「先全图解码」的峰值；大图列表、头像等场景推荐使用。

下采样算法步骤（与 Kingfisher / ImageIO 语义一致）：

函数 Downsample(data: Data, size: CGSize) -> Image?:
    1. maxDimensionInPixels = max(size.width, size.height) * scale
    2. source = CGImageSourceCreateWithData(data, nil)
    3. options = {
         kCGImageSourceCreateThumbnailFromImageAlways: true,
         kCGImageSourceCreateThumbnailWithTransform: true,
         kCGImageSourceShouldCacheImmediately: true,
         kCGImageSourceThumbnailMaxPixelSize: maxDimensionInPixels
       }
    4. cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options)
    5. 由 cgImage 构造 UIImage/NSImage 并返回

注意：size 不能为 (0, 0)，否则会触发 "Processing image failed. Processor: DownsamplingImageProcessor" [11]；在列表 cell 中应使用 cell 或目标视图的 bounds 计算合理 size。

3.2 ResizingImageProcessor

• 输入：一般为 Image（或通过 DefaultImageProcessor 先解码的 Data）。对已解码的位图做缩放，支持 ContentMode（如 aspectFit、aspectFill）。
• 实现：在像素缓冲上做几何变换（绘制到目标尺寸），会先占用全图解码的内存，再产生缩放后的新缓冲。
• 适用：已解码图、或必须对 Image 做精确尺寸/比例控制时使用；若从 Data 缩小，应优先 DownsamplingImageProcessor。

对比小结：

4. 多处理器链式组合

Kingfisher 支持将多个 ImageProcessor 串联成一条管线，按顺序执行：前一个的输出作为后一个的输入（.image(...)）[10]。

组合方式：通过 append(another:) 或 |> 运算符（Kingfisher 在 ImageProcessor 扩展中定义 |> 为调用 append(another:)）：

// 先模糊，再圆角
let processor = BlurImageProcessor(blurRadius: 4) |> RoundCornerImageProcessor(cornerRadius: 20)
imageView.kf.setImage(with: url, options: [.processor(processor)])

组合后的 identifier："\(p1.identifier)|>\(p2.identifier)"，用于缓存键，保证「同一 URL + 同一处理器链」唯一对应一条缓存。

链式执行语义（伪代码）：

函数 GeneralProcessor.process(item, options):
    image1 = self.process(item, options)
    若 image1 为 nil: 返回 nil
    返回 another.process(.image(image1), options)

因此，若链中第一个 Processor 能处理 .data（如 DefaultImageProcessor 或 DownsamplingImageProcessor），后续 Processor 将始终收到 .image(...)。

三、解码、缓存与处理器的协同

1. 检索流程与缓存键

Kingfisher 的检索顺序可概括为 [2][3]：

1. 使用 cacheKey + processorIdentifier 查内存缓存；
2. 若未命中，查磁盘缓存（同样 key + processorIdentifier）；
3. 若仍未命中，通过 ImageDownloader 或 ImageDataProvider 获取 Data；
4. 对 Data 执行 ImageProcessor 管线，得到 Image；
5. 将结果写入内存与磁盘缓存，并交给视图或完成回调。

缓存键：缓存的唯一标识是 cacheKey + processorIdentifier（DefaultImageProcessor 的 identifier 为空字符串）。因此：

• 同一 URL，不同 Processor（或不同链）会得到不同缓存条目；
• 原图（DefaultImageProcessor）与下采样/圆角等版本可并存；
• 判断或读取缓存时若请求中指定了非 Default 的 Processor，需传入相同 processorIdentifier，例如：cache.isCached(forKey: cacheKey, processorIdentifier: processor.identifier)、cache.retrieveImage(forKey: cacheKey, options: [.processor(processor)], ...)。

flowchart TD
    A[请求: URL + Processor] --> B[构造 cacheKey + processorIdentifier]
    B --> C{内存缓存?}
    C -->|命中| D[返回 Image]
    C -->|未命中| E{磁盘缓存?}
    E -->|命中| F[解码/反序列化]
    F --> D
    E -->|未命中| G[下载 / Provider]
    G --> H[Processor 管线]
    H --> I[写内存+磁盘]
    I --> D

2. CacheSerializer 与磁盘格式

CacheSerializer 负责「Image ↔ Data」在磁盘缓存中的序列化与反序列化 [10]：

• 存储：data(with:original:)，将当前要缓存的 Image 转为 Data（可结合 original Data 决定格式）；
• 读取：image(with:options:)，将磁盘上的 Data 转回 Image。

调用时机（便于理解与扩展）：

• Processor.process：① 网络下载成功或 ImageDataProvider 返回 Data 后，将 Data 加工为 Image；② 从磁盘读取到原始 Data 后，先经 CacheSerializer 反序列化为 Image，再经 Processor 处理（若请求中指定了 Processor）。因此磁盘命中「已处理图」时直接返回，命中「原图」时会再走一次 Processor。
• CacheSerializer.image：从磁盘读取到 Data 后，用于将 Data 反序列化为 Image。
• CacheSerializer.data：需要写入磁盘时，将 Image 序列化为 Data 再落盘。

默认行为：尽量保持原始数据格式（如 JPEG 仍存为 JPEG）。但当使用 RoundCornerImageProcessor 等会引入透明通道的处理器时，若原图是 JPEG（无透明通道），直接按 JPEG 存会丢失圆角透明区域。此时可指定 FormatIndicatedCacheSerializer.png，强制以 PNG 缓存处理后的图像：

imageView.kf.setImage(with: url,
    options: [.processor(RoundCornerImageProcessor(cornerRadius: 20)),
              .cacheSerializer(FormatIndicatedCacheSerializer.png)])

3. 内置 Processor 一览

4. 应用场景与选型

RoundCornerImageProcessor 指定圆角：除四角统一圆角外，可指定部分角，如仅左上与右下：RoundCornerImageProcessor(cornerRadius: 20, roundingCorners: [.topLeft, .bottomRight])。

四、类结构图分析

1. 核心类总览

Kingfisher 的类可按职责分为：入口与协调、加载、缓存、处理管线、视图扩展 五类。下表给出核心类/协议及其职责。

2. 模块划分与依赖关系

下图从「模块」维度表示各层之间的依赖方向：视图扩展与 Prefetcher 依赖 KingfisherManager，Manager 依赖 Downloader/Cache，处理管线在 Manager 内执行（Processor 链与 CacheSerializer 参与缓存键与磁盘格式）。

flowchart TB
    subgraph 视图层
        V1[ImageView.kf / KFImage]
        V2[ImagePrefetcher]
    end
    subgraph 协调层
        M[KingfisherManager]
    end
    subgraph 加载层
        L[ImageDownloader]
        P[ImageDataProvider 实现]
    end
    subgraph 缓存层
        C[ImageCache]
    end
    subgraph 处理管线层
        IP[ImageProcessor 实现]
        CS[CacheSerializer]
    end
    V1 --> M
    V2 --> M
    M --> L
    M --> P
    M --> C
    M --> IP
    M --> CS

3. 加载与缓存类结构

ImageDownloader 负责从网络获取 Data；ImageDataProvider 可提供本地或自定义 Data；ImageCache 负责内存与磁盘的读写。KingfisherManager 持有 cache 与 downloader，在单次请求中先查缓存（key = cacheKey + processorIdentifier），未命中再通过 downloader 或 provider 取数据，经 Processor 管线后写回缓存。

classDiagram
    class KingfisherManager {
        -cache: ImageCache
        -downloader: ImageDownloader
        +retrieveImage(with:options:progressBlock:completionHandler:)
        -loadAndCacheImage(source:options:completionHandler:)
    }
    class ImageCache {
        -memoryStorage: MemoryStorage
        -diskStorage: DiskStorage
        +retrieveImage(forKey:options:callbackQueue:completionHandler:)
        +store(_:forKey:options:toDisk:completionHandler:)
        +removeImage(forKey:fromMemory:fromDisk:completionHandler:)
    }
    class ImageDownloader {
        -session: URLSession
        -downloadQueue: OperationQueue
        +downloadImage(with:options:completionHandler:)
    }
    class ImageDataProvider {
        <<protocol>>
        +data(handler:)
        +cacheKey
    }
    KingfisherManager --> ImageCache : 使用
    KingfisherManager --> ImageDownloader : 使用
    KingfisherManager ..> ImageDataProvider : 支持 Source.provider

• KingfisherManager：对外通过 retrieveImage(with:...) 接收 Source（.network(URL) 或 .provider(ImageDataProvider)），先查 ImageCache（key 含 processorIdentifier），未命中则调 downloader 或 provider 取 Data，再跑 Processor 管线并写回缓存。
• ImageCache：5.0+ 将内存与磁盘拆为 MemoryStorage / DiskStorage，可配置 count/cost、过期时间；存储时由 CacheSerializer 决定 Image → Data 的格式（如 PNG 保留圆角透明）。
• ImageDownloader：基于 URLSession，单次下载封装为 ImageDownloaderOperation，支持并发数、超时、RequestModifier；与 Provider 一起构成「数据来源」的两种方式。

4. 处理管线与 Processor 类结构

ImageProcessor 协议是图层处理的核心：输入为 ImageProcessItem（.data 或 .image），输出为 KFCrossPlatformImage。Manager 在「取得 Data 后」按 options 中的 processor（或链）依次执行；链的 identifier 拼接后参与缓存键，实现「同一 URL + 不同 Processor」对应不同缓存条目。

classDiagram
    class KingfisherManager {
        -runProcessors(_:data:options:)
    }
    class ImageProcessItem {
        <<enumeration>>
        +image(KFCrossPlatformImage)
        +data(Data)
    }
    class ImageProcessor {
        <<protocol>>
        +identifier: String
        +process(item: ImageProcessItem, options: KingfisherParsedOptionsInfo): KFCrossPlatformImage?
    }
    class DefaultImageProcessor {
        +process(item:options:)
    }
    class DownsamplingImageProcessor {
        +size: CGSize
        +process(item:options:)
    }
    class RoundCornerImageProcessor {
        +cornerRadius: CGFloat
        +process(item:options:)
    }
    class ImageProcessorGroup {
        -processors: [ImageProcessor]
        +append(another:)
        +identifier
    }
    class CacheSerializer {
        <<protocol>>
        +data(with:original:)
        +image(with:options:)
    }
    ImageProcessItem --> ImageProcessor : 输入
    ImageProcessor <|.. DefaultImageProcessor : 实现
    ImageProcessor <|.. DownsamplingImageProcessor : 实现
    ImageProcessor <|.. RoundCornerImageProcessor : 实现
    ImageProcessor <|.. ImageProcessorGroup : 链式组合
    KingfisherManager ..> ImageProcessor : 执行管线
    KingfisherManager ..> CacheSerializer : 磁盘序列化

• ImageProcessItem：双态设计使同一管线既可处理「Data → Image」（解码/下采样），也可处理「Image → Image」（圆角、模糊、缩放），或混合链式处理；收到 .data 的 Processor 可先通过 DefaultImageProcessor.default |> self 解码再变换。
• ImageProcessor 链：通过 append(another:) 或 |> 组合，链的 identifier 为各子 Processor identifier 用 "|>" 拼接，参与缓存键；执行时前一个输出作为后一个的 .image(...) 输入。
• CacheSerializer：磁盘存储时由 data(with:original:) 将 Image 转为 Data，读取时由 image(with:options:) 反序列化；圆角等带透明通道的结果可选用 FormatIndicatedCacheSerializer.png 避免 JPEG 丢失透明。

5. View 扩展与调用链

视图扩展（如 ImageView.kf、SwiftUI 的 KFImage）是业务最常接触的入口：内部将 Resource（URL 或 ImageDataProvider）、placeholder、options 交给 KingfisherManager，并把返回的 DownloadTask 与 view 关联，以便在复用时取消。

sequenceDiagram
    participant V as ImageView
    participant KF as ImageView.kf
    participant M as KingfisherManager
    participant C as ImageCache
    participant D as ImageDownloader

    V->>KF: setImage(with: url, options: [.processor(...)])
    KF->>KF: cancelDownloadTask()
    KF->>M: retrieveImage(with: .network(url), options: ...)
    M->>C: retrieveImage(forKey: cacheKey+processorIdentifier)
    alt 缓存命中
        C-->>M: image (memory/disk)
        M-->>KF: completion(image, .memory/.disk)
    else 未命中
        M->>D: downloadImage(with: url, ...)
        D-->>M: data
        M->>M: Processor 管线处理
        M->>C: store(image, forKey: ...)
        M-->>KF: completion(image, .none)
    end
    KF->>V: imageView.image = image

• kf.setImage(with: placeholder: options: progressBlock: completionHandler:)：先对当前 view 取消未完成的 DownloadTask，再调 KingfisherManager.shared.retrieveImage(with: source, options: options, ...)；在 completion 中把得到的 image 赋给 imageView.image（并可选执行 transition）。
• kf.cancelDownloadTask()：取消与该 view 绑定的任务，避免 cell 复用时旧请求覆盖新图。
• KFImage (SwiftUI)：通过 KFImage 传入 url、processor、placeholder 等，内部同样走 KingfisherManager，支持 progressiveJPEG（8.3+）等选项。

将上述「核心类总览」「模块依赖」「加载与缓存类图」「Processor 与管线类图」「View 调用链」串联起来，即可形成对 Kingfisher 类结构图 的完整分析：入口在视图扩展（kf / KFImage），核心协调在 KingfisherManager，加载（Downloader/Provider）、缓存（ImageCache + CacheSerializer）、处理（ImageProcessor + ImageProcessItem）均为协议导向的可插拔设计，便于扩展与测试。

五、与系统及业界实践的衔接

1. Apple 图像与图形最佳实践

Apple 在 WWDC 2018「Image and Graphics Best Practices」[8] 中强调：

• 在后台线程解码与下采样，避免主线程卡顿；
• 解码时即做下采样，使解码后缓冲与显示尺寸匹配，降低内存峰值；
• 预取：在列表等场景提前准备即将显示的图像。

Kingfisher 的 DownsamplingImageProcessor 直接对应「解码时下采样」；处理管线在 KingfisherManager 的队列中执行，满足「后台处理」；配合 ImagePrefetcher 与 UICollectionViewDataSourcePrefetching 等可实现预取 [10]。与 SDWebImage 类似，其设计与此类最佳实践一致。

2. 与 SDWebImage 的对比

二者都遵循「解码/下采样 + 变换 + 缓存」的管线思想，Kingfisher 通过 ImageProcessItem 将「解码」与「变换」统一进同一协议，便于从 Data 直接到最终 Image 的一体化处理。

3. 动图加载（GIF）与 AnimatedImageView

Kingfisher 加载 GIF 的两种方式：UIImageView 与 AnimatedImageView（继承自 UIImageView），调用方式相同，内部行为不同 [12]。

• UIImageView：shouldPreloadAllAnimation() 扩展返回 true，即 preloadAllAnimationData 被设为 true，GIF 会先解码为所有帧的 UIImage 数组，再通过 UIImage.animatedImage(with:duration:) 展示。适合帧数少的动图。
• AnimatedImageView：重写 shouldPreloadAllAnimation() 返回 false，不预加载全部帧；通过关联的 CGImageSource 与 Animator 按需解码（默认仅预加载前若干帧），用 CADisplayLink 在每帧刷新时更新 layer.contents（重写 display(_ layer:)）。更省内存，CPU 略高。

AnimatedImageView 独有：runLoopMode、backgroundDecode、framePreloadCount、autoPlayAnimatedImage、repeatCount 等。若需在列表或详情中播放 GIF 且控制内存，建议使用 AnimatedImageView。

六、设计模式与编程思想

1. 设计模式应用

Kingfisher 在架构上大量运用经典设计模式，与纯 Swift、协议导向的风格结合，使扩展与维护成本可控。

类图关系（概念层）：

classDiagram
    class KingfisherManager {
        -cache: ImageCache
        -downloader: ImageDownloader
        +retrieveImage(with:options:progressBlock:completionHandler:)
    }
    class ImageCache {
        +retrieveImage(forKey:options:callbackQueue:completionHandler:)
        +store(_:forKey:options:toDisk:completionHandler:)
    }
    class ImageDownloader {
        +downloadImage(with:options:completionHandler:)
    }
    class ImageProcessor {
        <<protocol>>
        +identifier: String
        +process(item: ImageProcessItem, options:): KFCrossPlatformImage?
    }
    class ImageDataProvider {
        <<protocol>>
        +data(handler:)
        +cacheKey
    }
    KingfisherManager --> ImageCache : 使用
    KingfisherManager --> ImageDownloader : 使用
    KingfisherManager ..> ImageProcessor : 处理时选用
    KingfisherManager ..> ImageDataProvider : Source.provider

2. 编程思想精华

Kingfisher 的编程思想可提炼为以下几点，对理解与模仿其设计很有帮助。

2.1 协议导向与「可替换实现」

• ImageProcessor、CacheSerializer、ImageDataProvider 均以协议呈现，具体实现可替换、可组合。
• 新增一种图像处理或一种磁盘格式，只需实现对应协议并通过 options 传入（如 .processor(...)、.cacheSerializer(...)），无需改动 KingfisherManager 核心流程。这体现了开闭原则：对扩展开放，对修改关闭。

2.2 管线化与单一职责

• 把「从 Source 到屏幕」拆成：获取数据（Downloader/Provider）→ Processor 管线（解码/下采样 + 变换）→ 缓存 → 展示，每一步只做一件事。
• Processor 只关心 ImageProcessItem → Image，Cache 只关心存储与查找，Downloader 只关心网络 Data。单一职责使每块可独立测试、优化和扩展；管线化则使数据流清晰，便于加日志与监控。

2.3 双态输入与「解码+变换」统一

• ImageProcessItem 的 .data / .image 双态设计，使同一 ImageProcessor 协议既能表达「Data → Image」（如 Default、Downsampling），也能表达「Image → Image」（如 RoundCorner、Blur），还能通过链式组合在一次管线中完成解码与多步变换。
• 避免「解码器」与「变换器」两套抽象，降低概念数量，便于链式组合与缓存键一致（整条链一个 identifier 串）。

2.4 缓存键与「同一资源多形态」

• 通过 cacheKey + processorIdentifier 的设计，同一 URL 可以对应「原图」「下采样图」「圆角图」等多条缓存，避免重复下载，又满足不同场景对尺寸/形态的需求。这体现了用键设计表达业务差异的思想。

2.5 后台处理与主线程回调

• 下载、Processor 管线、磁盘 I/O 均在后台队列执行，completionHandler 通过 CallbackQueue.mainAsync 等派发到主线程，兼顾性能与 UI 安全。这是移动端异步加载库的通用范式：重活放后台，结果回主线程。

2.6 取消与生命周期绑定

• 视图扩展（如 ImageView.kf）会把「当前正在进行的 DownloadTask」与 view 绑定，当对同一 view 发起新请求时先取消旧任务，避免错位和浪费。这体现了生命周期与请求绑定的思想，在列表 cell 复用时尤为重要。

2.7 配置通过 Options 透传

• 不通过全局单例属性堆砌配置，而是通过 KingfisherOptionsInfo（如 .processor、.cacheSerializer、.callbackQueue）在单次请求中传入，使「同一 App 内不同页面/模块」可使用不同 Processor 与缓存策略，且易于单元测试时注入 mock。

Kingfisher 编程思想精华一览：

七、使用示例与最佳实践

1. 基础加载与圆角

let processor = RoundCornerImageProcessor(cornerRadius: 20)
imageView.kf.setImage(with: url, options: [.processor(processor)])

2. 列表缩略图（下采样）

let size = imageView.bounds.size
let processor = DownsamplingImageProcessor(size: size)
imageView.kf.setImage(with: url, options: [.processor(processor)])
// 注意：size 不可为 .zero

3. 多处理器链与强制 PNG 缓存

let processor = BlurImageProcessor(blurRadius: 4) |> RoundCornerImageProcessor(cornerRadius: 20)
imageView.kf.setImage(with: url, options: [
    .processor(processor),
    .cacheSerializer(FormatIndicatedCacheSerializer.png)
])

4. 自定义 Processor（仅做示意）

struct MyProcessor: ImageProcessor {
    let identifier = "com.example.myprocessor"
    func process(item: ImageProcessItem, options: KingfisherParsedOptionsInfo) -> KFCrossPlatformImage? {
        switch item {
        case .image(let image): return image // 或对 image 做变换
        case .data(let data): return DefaultImageProcessor.default.process(item: item, options: options)
        }
    }
}

5. 预取与列表

// 配合 UICollectionViewDataSourcePrefetching
func collectionView(_ collectionView: UICollectionView, prefetchItemsAt indexPaths: [IndexPath]) {
    let urls = indexPaths.compactMap { URL(string: model(at: $0).imageURL) }
    ImagePrefetcher(urls: urls).start()
}

6. Cell 完整示例（复用、下采样、进度与完成回调）

列表 Cell 中需在 prepareForReuse 中取消任务并清空，在 configure 中按目标尺寸下采样并可选显示进度。

class PhotoCell: UITableViewCell {
    static let reuseId = "PhotoCell"
    @IBOutlet weak var photoImageView: UIImageView!
    @IBOutlet weak var progressView: UIProgressView!

    override func prepareForReuse() {
        super.prepareForReuse()
        photoImageView.kf.cancelDownloadTask()
        photoImageView.image = nil
        progressView.progress = 0
        progressView.isHidden = true
    }

    func configure(with url: URL) {
        let size = photoImageView.bounds.size
        let processor = DownsamplingImageProcessor(size: size.isEmpty ? CGSize(width: 120, height: 120) : size)
        photoImageView.kf.setImage(
            with: url,
            placeholder: UIImage(named: "placeholder"),
            options: [.processor(processor), .scaleFactor(UIScreen.main.scale)],
            progressBlock: { [weak self] received, total in
                guard let self = self, total > 0 else { return }
                DispatchQueue.main.async {
                    self.progressView.isHidden = false
                    self.progressView.progress = Float(received) / Float(total)
                }
            },
            completionHandler: { [weak self] result in
                DispatchQueue.main.async {
                    self?.progressView.isHidden = true
                    if case .failure = result { /* 可设置失败占位图 */ }
                }
            }
        )
    }
}

7. UIButton 设置网络图片

为 UIButton 的不同 state 设置网络图片，可配合 Processor 与完成回调。

// 设置 normal / highlighted 等状态的图片
button.kf.setImage(with: url, for: .normal, placeholder: UIImage(named: "btn_placeholder"))
button.kf.setImage(with: highlightedURL, for: .highlighted)
button.kf.setBackgroundImage(with: backgroundURL, for: .normal)

// 带圆角与完成回调
let processor = RoundCornerImageProcessor(cornerRadius: 8)
button.kf.setImage(
    with: url,
    for: .normal,
    placeholder: nil,
    options: [.processor(processor), .cacheSerializer(FormatIndicatedCacheSerializer.png)],
    completionHandler: { result in
        if case .failure = result { print("加载失败") }
    }
)

8. 占位图、进度与过渡动画

使用占位图、下载进度条，并在图片加载完成后执行淡入等过渡动画。

imageView.kf.setImage(
    with: url,
    placeholder: UIImage(named: "placeholder"),
    options: [
        .transition(ImageTransition.fade(0.3)),
        .retryFailed
    ],
    progressBlock: { [weak progressView] received, total in
        guard let pv = progressView, total > 0 else { return }
        DispatchQueue.main.async {
            pv.progress = Float(received) / Float(total)
            pv.isHidden = false
        }
    },
    completionHandler: { [weak progressView] result in
        DispatchQueue.main.async {
            progressView?.isHidden = true
            if case .failure = result { /* 可显示失败占位或提示 */ }
        }
    }
)

9. 自定义缓存键与请求修饰（RequestModifier）

同一 URL 在不同业务下需要不同缓存键时，可通过 KingfisherOptionsInfo 传入自定义 cacheKey；需要鉴权或自定义 Header 时使用 ImageDownloadRequestModifier。

// 自定义缓存键：列表用 thumb key、详情用原图 key
let listResource = ImageResource(downloadURL: url, cacheKey: "list_\(url.absoluteString)")
let detailResource = ImageResource(downloadURL: url, cacheKey: "detail_\(url.absoluteString)")
listImageView.kf.setImage(with: listResource, options: [.processor(DownsamplingImageProcessor(size: thumbSize))])
detailImageView.kf.setImage(with: detailResource)

// 请求修饰：Header、Token、超时
struct AuthModifier: ImageDownloadRequestModifier {
    let token: String
    func modified(for request: URLRequest) -> URLRequest? {
        var r = request
        r.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
        r.setValue("image/webp,image/*,*/*;q=0.8", forHTTPHeaderField: "Accept")
        return r
    }
}
imageView.kf.setImage(with: url, options: [.requestModifier(AuthModifier(token: userToken))])

10. 缓存查询与手动存储

不经过视图加载流程，直接使用 ImageCache 查询、存储或移除缓存。

let cache = ImageCache.default
let key = url.absoluteString  // 或自定义 cacheKey（与 Processor 组合时由框架自动拼接 processorIdentifier）

// 查询是否已缓存
cache.imageCachedType(forKey: key) { result in
    switch result {
    case .success(let cached):
        switch cached {
        case .none:   print("未缓存")
        case .memory: print("在内存")
        case .disk:   print("在磁盘")
        }
    case .failure: break
    }
}

// 从缓存读取（不触发下载）
cache.retrieveImage(forKey: key, options: nil) { result in
    switch result {
    case .success(let value):
        if let image = value.image { imageView.image = image }
    case .failure: break
    }
}

// 手动写入缓存（如本地生成或从相册来的图）
cache.store(image, forKey: key, options: nil, toDisk: true) { _ in }

11. 自定义 Processor 完整示例（加边框）

实现 ImageProcessor 协议，对已解码图像做自定义绘制（如加灰色边框）。

struct GrayBorderProcessor: ImageProcessor {
    let identifier = "com.example.grayborder(\(borderWidth))"
    let borderWidth: CGFloat

    init(borderWidth: CGFloat = 2) { self.borderWidth = borderWidth }

    func process(item: ImageProcessItem, options: KingfisherParsedOptionsInfo) -> KFCrossPlatformImage? {
        switch item {
        case .image(let image):
            let size = image.size
            let renderer = UIGraphicsImageRenderer(size: size)
            return renderer.image { ctx in
                image.draw(at: .zero)
                UIColor.gray.setStroke()
                let rect = CGRect(origin: .zero, size: size).insetBy(dx: borderWidth/2, dy: borderWidth/2)
                ctx.stroke(rect, with: .color(.gray), lineWidth: borderWidth)
            }
        case .data:
            return DefaultImageProcessor.default.process(item: item, options: options)
        }
    }
}

// 使用
imageView.kf.setImage(with: url, options: [.processor(GrayBorderProcessor(borderWidth: 3))])

12. SwiftUI KFImage 与 async/await

在 SwiftUI 中使用 KFImage，并配合渐进式 JPEG、占位与异步加载。

// 基础用法
KFImage(url)
    .placeholder { ProgressView() }
    .fade(duration: 0.25)
    .resizable()
    .aspectRatio(contentMode: .fit)

// 带 Processor 与圆角
KFImage(url)
    .setProcessor(RoundCornerImageProcessor(cornerRadius: 12))
    .placeholder { Color.gray.opacity(0.2) }
    .cacheSerializer(FormatIndicatedCacheSerializer.png)

// 8.3+ 渐进式 JPEG
KFImage(url)
    .progressiveJPEG(ImageProgressive(isBlur: true, isFastestScan: true, scanInterval: 0.1))

// 使用 async/await（Kingfisher 提供的异步 API）
Task {
    let result = await KingfisherManager.shared.retrieveImage(with: url)
    if case .success(let value) = result {
        await MainActor.run { imageView.image = value.image }
    }
}

13. ImageDataProvider（本地与 Base64）用法

不依赖网络 URL 时，可用 ImageDataProvider 从本地文件或 Base64 字符串加载，并同样走缓存与 Processor 管线。

// 本地文件
let fileURL = Bundle.main.url(forResource: "avatar", withExtension: "jpg")!
let provider = LocalFileImageDataProvider(fileURL: fileURL)
imageView.kf.setImage(with: provider)

// Base64 数据（如接口返回的 data URL）
let base64String = "data:image/png;base64,iVBORw0KGgo..."
if let provider = Base64ImageDataProvider(base64String: base64String, cacheKey: "custom_key") {
    imageView.kf.setImage(with: provider, options: [.processor(RoundCornerImageProcessor(cornerRadius: 10))])
}

// 自定义 Provider：从相册、加密存储等获取 Data
struct MyImageDataProvider: ImageDataProvider {
    var cacheKey: String { "my_\(id)" }
    let id: String
    func data(handler: @escaping (Result<Data, Error>) -> Void) {
        // 异步获取 Data 后调用 handler(.success(data)) 或 handler(.failure(...))
    }
}
imageView.kf.setImage(with: MyImageDataProvider(id: "123"))

14. 其他常用选项速览

imageView.kf.setImage(with: url, options: [.forceRefresh, .retryFailed, .callbackQueue(.mainAsync)])

15. Options 详解（延伸）

• targetCache / originalCache：默认为 nil 时使用 ImageCache(name: "default")。targetCache 为最终展示图的缓存（含 Processor 处理后的图），originalCache 为原始数据的缓存，可用于「列表用处理图、详情用原图」等分离策略。
• transition：图片加载完成后的展示动画；forceTransition 为 true 时即使命中缓存也执行 transition，为 false 时仅在不使用缓存（新下载）时执行。
• callbackQueue / processingQueue：callbackQueue 可选 .mainAsync、.mainCurrentOrAsync（当前线程为主线程则直接执行，否则主线程异步）、.untouch、.dispatch(DispatchQueue)，默认多为 .mainCurrentOrAsync；processingQueue 为 Processor 执行所在队列，默认串行子队列。
• memoryCacheAccessExtendingExpiration：从内存/磁盘取图时是否延长过期时间，可选 .none（不延长）、.cacheTime（当前时间 + 原过期时长）、.expirationTime(StorageExpiration)（延长到指定时长）。

16. 指示器、Placeholder 与 Transition 类型

• 指示器（Indicator）：imageView.kf.indicatorType 可选 .none、.activity（UIActivityIndicatorView）、.image(imageData: Data)（GIF 等）、.custom(indicator: Indicator)，自定义需实现 Indicator 协议（startAnimatingView / stopAnimatingView）。
• Placeholder：除 UIImage 外，可实现 Placeholder 协议的自定义 View（如 class MyPlaceholder: UIView, Placeholder {}），设置 imageView.kf.setImage(with: url, placeholder: myPlaceholderView)。
• ImageTransition：none、fade(TimeInterval)、flipFromLeft/Right/Top/Bottom(TimeInterval)、custom(duration:options:animations:completion:)。

17. 缓存配置与清除

内存缓存（cache.memoryStorage.config）：totalCostLimit（默认约物理内存 1/4）、countLimit、expiration（默认 300 秒）、cleanInterval（清除过期缓存的时间间隔，仅初始化可设）。单张可设 .memoryCacheExpiration(.never)；访问时延长策略用 .memoryCacheAccessExtendingExpiration(.cacheTime)。

磁盘缓存（cache.diskStorage.config）：sizeLimit、expiration（默认 7 天）、pathExtension、usesHashedFileName（文件名是否用 key 的 MD5）。超出容量时按最后访问时间排序，删除最旧文件直至低于 sizeLimit 的一半。

清除：cache.clearMemoryCache() / cache.cleanExpiredMemoryCache()；cache.clearDiskCache() / cache.cleanExpiredDiskCache()；删除指定 key 可用 cache.removeImage(forKey:processorIdentifier:fromMemory:fromDisk:completionHandler:)。获取磁盘占用：cache.calculateDiskStorageSize { result in ... }。

18. ImagePrefetcher 与请求修饰、重定向

ImagePrefetcher：除 start() 外，提供 completionHandler（参数为 [Resource] 的 skipped/failed/completed）与 completionSourceHandler（参数为 [Source]），分别对应用 URL/Resource 初始化与用 Source 初始化的场景；progressBlock / progressSourceBlock 同理。maxConcurrentDownloads 控制并发数。stop() 会取消当前未完成的下载任务，并将剩余未加载项计入「完成回调」的 skipped；若调用 stop 时已全部完成，则不会再次触发完成回调。

请求修饰：通过 AnyModifier 或实现 ImageDownloadRequestModifier 在请求前添加 Header、Token 等，例如 let modifier = AnyModifier { var r = $0; r.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization"); return r }，options 中加 .requestModifier(modifier)。超时：ImageDownloader.default.downloadTimeout = 60。重定向：通过 .redirectHandler(AnyRedirectHandler { ... }) 自定义 302 等重定向后的请求。

19. 扩展 WebP 支持（Processor + CacheSerializer）

Kingfisher 默认不包含 WebP 编解码，可借助 Processor 与 CacheSerializer 扩展 [13]。依赖 libwebp 实现 Data ↔ Image 后，定义 WebPProcessor（在 process 中若为 .data 则用 WebP 解码为 Image，若为 .image 则透传）与 WebPCacheSerializer（data(with:original:) 返回 WebP 编码、image(with:options:) 返回 WebP 解码），使用时设置 options: [.processor(WebPProcessor.default), .cacheSerializer(WebPCacheSerializer.default)] 即可对 .webp URL 加载并缓存。

延伸阅读（掘金系列）

以下为同一作者的 Kingfisher 源码解析系列文章，可按需跳转深入阅读（链接与标题保持一致）：

参考文献

[1] Kingfisher. Cheat Sheet. GitHub Wiki.
[2] Kingfisher. Image Manager Structure. studyraid.com / Agent Docs.
[3] Kingfisher. CHANGELOG / Releases — 3.10.0 cache retrieval with ImageProcessor.
[4] Kingfisher. Release 5.0.0. GitHub.
[5] Kingfisher. Release 5.3.0 — Downsampling scale/memory fix.
[6] Kingfisher. Release 7.8.1 — Animated image from disk cache with processor.
[7] Kingfisher. Release 8.3.0 — Progressive JPEG for KFImage.
[8] Apple. Image and Graphics Best Practices. WWDC 2018, Session 219.
[9] Kingfisher. ImageProcessor.swift. GitHub (onevcat/Kingfisher).
[10] Kingfisher. Cheat Sheet — Processor, Cache, Downloader. GitHub Wiki.
[11] Stack Overflow / Kingfisher Issues. DownsamplingImageProcessor size (0,0) and processing failure.

📋 目录

• 一、SDWebImage 概述与历史演进
  • 0. 框架结构概览与功能简介
  • 1. 框架简介
  • 2. 技术演进与版本脉络
  • 3. 图层处理在整体架构中的位置
• 二、图像解码管线（Decoder Pipeline）
  • 1. 解码的基础概念与双缓冲模型
  • 2. 缩略图与下采样（Downsampling）
  • 3. 渐进式解码（Progressive Decoding）
  • 4. 编解码器扩展与多格式支持
• 三、图像变换管线（Transformer Pipeline）
  • 1. 变换器的设计思想与协议
  • 2. 内置变换器与组合管线
  • 3. 变换与缓存的协同
• 四、类结构图分析
  • 1. 核心类总览
  • 2. 模块划分与依赖关系
  • 3. 加载与缓存类结构
  • 4. 解码与变换类结构
  • 5. View 扩展与调用链
• 五、与系统及业界实践的衔接
  • 1. Apple 图像与图形最佳实践
  • 2. 移动端图像管线研究简述
• 六、使用案例与原理分析
  • 0. 框架结构速览
  • 1. 典型使用案例
  • 2. 更多使用案例与代码
  • 3. 核心流程原理分析
• 七、设计模式与编程思想
  • 1. 设计模式应用
  • 2. 编程思想精华
• 八、使用示例与最佳实践
• 九、常见面试题
• 参考文献

一、SDWebImage 概述与历史演进

0. 框架结构概览与功能简介

SDWebImage 的框架结构

SDWebImage 的图片下载分类，只要一行代码就可以实现图片异步下载和缓存功能。

功能简介

1. 一个添加了 web 图片加载和缓存管理的 UIImageView 分类
2. 一个异步图片下载器
3. 一个异步的内存加磁盘综合存储图片并且自动处理过期图片
4. 支持动态 gif 图
   • 4.0 之前的动图效果并不是太好
   • 4.0 以后基于 FLAnimatedImage 加载动图
5. 支持 webP 格式的图片
6. 后台图片解压处理
7. 确保同样的图片 url 不会下载多次
8. 确保伪造的图片 url 不会重复尝试下载
9. 确保主线程不会阻塞