普通视图

发现新文章,点击刷新页面。
昨天 — 2026年5月6日技术

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

作者 王若风
2026年5月6日 22:47

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

大家好,我是若风。

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

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

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

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

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

先说结论

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

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

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

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

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

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

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

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

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

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

选择一:用 Zig,不是 Rust

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

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

选择二:JavaScriptCore,不是 V8

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

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

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

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

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

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

第一阶段:萌芽期(2021-2022.7)

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

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

第二阶段:品牌爆发期(2022.7-2023.9)

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

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

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

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

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

第三阶段:平台化与兼容攻坚期(2023.9-2025.10)

Bun 1.0(2023.9.8):第一次完成产品定义

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

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

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

Bun 1.1(2024.4.1):补上 Windows,从明星项目走向平台项目

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

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

Bun 1.2(2025.1.22):方法论升级

很多人看 Bun 1.2,会先看到新增能力:Bun.s3Bun.sqlbun.lock 文本锁文件。

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

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

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

Bun 1.3(2025.10.10):从 runtime 推向 full-stack substrate

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

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

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

第四阶段:AI 基础设施绑定期(2025.12 至今)

被 Anthropic 收购

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

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

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

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

2026 年:继续打磨底层

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

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

竞争格局:Bun vs Node vs Deno

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

Bun vs Node.js

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

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

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

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

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

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

Bun vs Deno

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

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

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

三条路径,三种气质:

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

Bun vs 传统工具链

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

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

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

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

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

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

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

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

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

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

未来会怎样?

我觉得有三种剧本。

最可能:外围切入,向中心渗透

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

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

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

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

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

写在最后

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

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

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

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

对于普通开发者,我的建议是:

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

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

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

参考来源

Web 性能优化完全指南

作者 顾昂_
2026年5月6日 20:40

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

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

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

目录

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

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

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

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

根据 2025 年的行业数据:

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

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

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

2021 年,Google 正式将 Core Web Vitals(核心网页指标)纳入搜索排名算法。这意味着:

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

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

1.3 用户体验的心理学

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

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

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

1.4 前端性能的三个维度

理解性能优化,需要从三个维度思考:

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

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


第二章:Web 性能指标全景

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

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

LCP(Largest Contentful Paint,最大内容绘制)

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

阈值标准

  • 良好:< 2.5 秒
  • 需改进:2.5 秒 ~ 4 秒
  • 差:> 4 秒

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

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

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

INP(Interaction to Next Paint,与下一次绘制的交互)

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

INP 的三个阶段

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

阈值标准

  • 良好:< 200 毫秒
  • 需改进:200 ~ 500 毫秒
  • 差:> 500 毫秒

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

CLS(Cumulative Layout Shift,累积布局偏移)

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

计算方式

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

阈值标准

  • 良好:< 0.1
  • 需改进:0.1 ~ 0.25
  • 差:> 0.25

2.2 其他重要性能指标

FCP(First Contentful Paint,首次内容绘制)

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

阈值:良好 < 1.8 秒

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

TTFB(Time to First Byte,首字节时间)

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

阈值:良好 < 200 毫秒

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

TTI(Time to Interactive,可交互时间)

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

TTI 要求满足:

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

TBT(Total Blocking Time,总阻塞时间)

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

阈值:良好 < 200 毫秒

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

2.3 指标之间的关联关系

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

    CLS(布局稳定性)─── 贯穿整个加载过程

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


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

3.1 工具概览

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

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

3.2 Lighthouse 面板实战

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

使用步骤

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

📸 Lighthouse 面板配置界面(设备类型、分析类别、清除缓存选项):

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

读懂 Lighthouse 报告

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

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

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

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

3.3 Performance 面板深度使用

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

录制性能分析

  1. 打开 Performance 面板
  2. 点击左上角的 录制按钮(圆圈图标) 开始录制
  3. 在页面上执行你想分析的操作(如点击按钮、滚动页面)
  4. 点击 停止 按钮
  5. 等待分析完成,查看时间线

📸 录制控制按钮位置(左上角圆形录制键,右下角也有一个快捷键):

读懂 Performance 面板

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

① 概览区域(Overview)

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

📸 Overview 概览区域(上方 CPU/NET 条带 + 下方时间线选区):

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

② 主线程区域(Main)

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

📸 Main 主线程区域(每个色块是一个任务,底部是 Summary 详情):

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

③ 识别长任务(最重要)

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

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

📸 Long Task 标记(红色三角形 + 超出 50ms 部分用红色斜线标注):

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

④ 火焰图(Flame Chart)——找到最耗时函数

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

📸 火焰图详情(点击 click 事件后可看到完整调用链):

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

⑤ 性能时间点标记(FCP / LCP / DCL / Load)

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

📸 关键时间点标记线(FCP 绿线、LCP 绿线、DCL 蓝线、Load 红线):

  • FCP(绿色) :第一块内容出现的时间
  • LCP(绿色,更靠后) :最大内容出现的时间
  • DCL(蓝色) :HTML 解析完成
  • Load(红色) :所有资源加载完成

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

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

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

3.4 Chrome DevTools 2025 新特性

Live Metrics 实时指标面板

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

使用方法:

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

📸 Live Metrics 实时面板(左侧本地实测值 + 右侧 CrUX 字段真实用户数据):

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

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

INP 交互日志(Interactions Track)

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

📸 Interactions 轨道(每次交互显示 Input Delay + Processing + Presentation 三段时间条):

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

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

AI 驱动的性能 Insights

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

校准节流(Calibrated Throttling)

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

3.5 Network 面板分析资源加载

找到 LCP 图片的加载时间

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

Timing 标签页会显示:

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

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

如何判断问题所在

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

查看资源加载优先级

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

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

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

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

  1. 打开 Coverage 面板(可以通过 Ctrl+Shift+P 搜索 "Coverage" 打开)
  2. 点击录制按钮
  3. 刷新页面并操作
  4. 停止录制,查看结果

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


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

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

第四章:LCP 优化深度指南

4.1 LCP 的计算原理

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

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

LCP 计算会排除的元素

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

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

4.2 诊断 LCP 慢的原因

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

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

诊断步骤

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

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

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

4.3 LCP 图片优化技术

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

技术四:GIF 首帧优化

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

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

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

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

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

  return { isGif, displayUrl };
};

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

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

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

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

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

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

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

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

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

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

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

原理

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

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

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

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

第五章:INP 优化深度指南

5.1 INP 慢的根本原因

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

主线程阻塞的常见来源

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

5.2 使用 Chrome DevTools 定位 INP 问题

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

  1. 打开 Performance 面板的 Live Metrics
  2. 在页面上进行各种交互(点击、输入、滚动)
  3. 观察 INP 数值,找到使数值变大的操作

步骤二:录制性能分析

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

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

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

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

5.3 三种核心优化技术

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

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

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

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

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

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

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

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

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

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

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

三种调度策略对比

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

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

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

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

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

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

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

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

使用 performance-utils SDK:

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

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

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

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

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

技术二:taskSplitPoint - 长任务切片

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

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

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

// ── runTasks 实际源码(async generator 模式)────────────────

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

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

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

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

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

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

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

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

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

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

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

使用 SDK:

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

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

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

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

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

实测对比数据

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

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

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

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

import { useState, useTransition } from 'react';

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

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

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

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

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

使用场景总结

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

5.4 优化 Input Delay

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

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

解决方案:

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

第六章:CLS 优化深度指南

6.1 CLS 的计算原理

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

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

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

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

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

6.2 CLS 的常见原因与修复

原因一:图片无尺寸

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

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

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

对于响应式图片,使用 aspect-ratio CSS 属性:

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

原因二:动态注入的内容

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

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

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

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

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

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

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

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

原因三:Web 字体导致的文本偏移(FOUT/FOIT)

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

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

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

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

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

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

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

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

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

6.3 用 Chrome DevTools 诊断 CLS

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

第七章:TTFB 与网络优化

7.1 TTFB 慢的诊断

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

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

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

7.2 CDN 优化

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

配置 CDN 的关键点

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

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

前端资源的内容哈希

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

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

7.3 HTTP/2 和 HTTP/3

HTTP/2 的优势

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

验证是否使用 HTTP/2

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

7.4 资源预连接

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

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

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

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

8.1 代码分割(Code Splitting)

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

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

8.2 路由级别的懒加载

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

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

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

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

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

8.3 组件级别的懒加载

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

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

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

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

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

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

8.4 Tree Shaking

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

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

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

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

对于 UI 组件库

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

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

8.5 Web Workers

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

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

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

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

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

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

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

8.6 虚拟列表

当列表数据量很大(数百到数万条)时,不应该渲染所有 DOM 节点,而应该使用虚拟列表:

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

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

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

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

8.7 React 性能优化

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

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

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

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

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

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

9.1 场景描述

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

9.2 第一步:建立基准数据

在优化之前,先测量现状,建立基准:

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

假设 Lighthouse 报告如下:

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

9.3 第二步:定位 TTFB 瓶颈

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

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

解决方案

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

9.4 第三步:分析 LCP 问题

TTFB 处理后,关注 LCP:

  1. 在 Lighthouse 报告中找到 LCP 截图,查看被识别为 LCP 的元素

  2. 假设 LCP 元素是一张 600KB 的 PNG 主图

  3. 在 Network 面板中找到该图片的请求,查看:

    1. Priority:Low(加载优先级低!)
    2. Content-Encoding:(none)(没有压缩)
    3. 下载时间:1.8s(文件太大)

优化方案

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

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

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

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

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

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

假设发现:

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

优化方案

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

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

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

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

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

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

9.6 第五步:修复 CLS 问题

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

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

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

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

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

9.7 第六步:验证优化效果

再次运行 Lighthouse,对比数据:

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

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

9.8 优化的优先级原则

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

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

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

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

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

真实用户监控(RUM, Real User Monitoring)

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

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

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

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

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

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

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

10.3 性能预算

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

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

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

# .gitlab-ci.yml
performance_test:
  stage: test
  script:
    # 使用 Lighthouse CI 进行性能测试
    - npx lhci autorun
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
// lighthouserc.js
module.exports = {
  ci: {
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        // LCP 必须低于 2500ms,否则 CI 失败
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        // INP 必须低于 200ms
        'experimental-interaction-to-next-paint': ['warn', { maxNumericValue: 200 }],
        // TBT 必须低于 300ms
        'total-blocking-time': ['error', { maxNumericValue: 300 }],
      },
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
};

10.4 建立性能优化文化

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

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

10.5 性能优化 Checklist

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

加载性能

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

代码质量

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

交互性能

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

布局稳定性

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

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

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

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

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

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

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

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

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


附录:工具资源

在线分析工具

npm 包

  • web-vitalsnpm i web-vitals):Google 官方的 Core Web Vitals 收集库
  • performance-utilsnpm i performance-utils):性能优化工具集
  • react-windownpm i react-window):虚拟列表
  • react-virtualizednpm i react-virtualized):更完整的虚拟化方案

学习资源

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

Ant Design Pro v6.0.0 发布

2026年5月6日 19:57

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

🌟 v6 背后的蚂蚁生态

  • Ant Design V6 — 企业级设计系统。Pro v6 全面采用 antd 6,启用 CSS 变量模式(cssVar),支持 Default、Dark、Glass 等多种风格预设,渲染性能显著提升。

  • Ant Design X — AI 界面解决方案,基于 RICH 设计范式将 GUI 与自然语言交互有机融合。Pro v6 内置的 AI 助手页面基于 Ant Design X 构建,开箱即用。

  • Ant Design CLI — 官方命令行工具(npx antd),查询组件 API、获取示例代码、诊断项目配置一步到位。Pro v6 已内置集成,告别频繁翻文档。

  • utoo — 基于 Turbopack 的 Rust 构建引擎,提供极速冷启动和毫秒级 HMR。Pro v6 默认使用 utoopack 构建,生产构建提速约 42%。

🚀 框架升级

React 19 + antd 6

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

Umi Max 4

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

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

ProComponents v3

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

💎 样式体系重构

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

  • Tailwind CSS v4:原子化 CSS,布局和间距不再需要写自定义样式

  • antd-style v4:消费 antd Design Token 的 CSS-in-JS 方案,主题切换零成本

  • CSS Modules:组件级样式隔离,避免命名冲突

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

⚡ 构建提速

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

版本

构建工具

生产构建耗时

v5.2.0

webpack 5 (mfsu)

~15.5s

v6.0.0

utoopack (Turbopack)

~9.0s

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

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

🤖 AI 能力

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

🔧 工具链现代化

  • Biome 替代 ESLint + Prettier — 一个工具搞定 lint + format,速度快 10 倍以上,告别多个配置文件的繁琐

  • React Query 替代 useRequest — 缓存管理、请求去重、乐观更新、无限滚动,中后台最常见的需求都有了现成方案

  • yorkie → husky · moment → dayjs · lodash → 原生 API / clsx · Class 组件 → 函数式组件

  • Docker 配置移除 · pro-cli → git clone + npm run simple

🌐 Cloudflare Worker 后端

v6 的演示 API 迁移到 Cloudflare WorkersHono 框架)。cloudflare-worker/ 目录独立于主项目,有自己的 package.jsontsconfig.json,可以独立部署。

📊 D3 地图可视化

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

📖 Cheatsheet 速查文档(取代 pro.ant.design)

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

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

🔄 升级指南

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

  1. 依赖替换umi@umijs/max,分散的 ProComponents → @ant-design/pro-components

  2. 样式迁移:Less → Tailwind + antd-style + CSS Modules

  3. 导入路径from 'umi'from '@umijs/max'

  4. 请求方式useRequest@tanstack/react-query

  5. 代码检查:ESLint + Prettier → Biome

  6. 日期库:moment → dayjs

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

🙏 致谢

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

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

本文使用 mdnice 排版

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

2026年5月6日 19:01

背景:为什么传统监控不够?

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

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

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

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

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

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

整体架构

关键技术选型

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

核心能力:有源 Ping 原理

H3C 有源 Ping 命令

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

示例:

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

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

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

核心指标集

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

接入步骤

安装 DataKit

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

开启 Pythond 采集器

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

编辑 pythond.conf

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

在 route_demo 下新建 route_demo.py 文件,内容如下:

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

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


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

重启 DataKit

datakit service -R

监控视图

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

总结

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

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

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

2026年5月6日 18:43

一、DeepSeek TUI 是什么?

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

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

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

核心亮点速览

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

二、架构设计

2.1 分派器架构

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

deepseek (CLI 分派器)
    └── deepseek-tui (TUI 进程)
            └── 异步引擎 (Agent 循环)
                    ├── LLM 流式客户端
                    ├── 工具注册表
                    │   ├── 文件操作
                    │   ├── Shell 执行
                    │   ├── Git 管理
                    │   ├── MCP 客户端
                    │   └── RLM 子代理
                    └── 会话管理器
  • deepseek:轻量级 CLI 分派器,负责参数解析和进程管理
  • deepseek-tui:实际的 TUI 进程,使用 Ratatui 框架渲染界面
  • 引擎:异步 Agent 循环,处理用户输入 → LLM 调用 → 工具调用 → 结果返回的完整链路
  • 两个二进制文件都不可或缺

2.2 三种交互模式

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

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

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


三、技术栈

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

四、快速安装

系统要求

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

安装方式

# 方式一:npm(推荐)
npm install -g deepseek-tui

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

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

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

认证配置

# 方式一(推荐):交互式设置
deepseek auth set --provider deepseek

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

支持的大模型供应商

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

五、核心特性深度解析

5.1 1M Token 超长上下文

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

这意味着你可以:

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

5.2 推理模式(Thinking Mode)

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

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

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

5.3 原生 RLM 批处理

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

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

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

5.4 会话与工作区管理

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

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

5.5 LSP 集成

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

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

5.6 技能系统

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

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

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

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

5.7 MCP 协议支持

兼容 Model Context Protocol,可以接入任意 MCP 服务器:

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

六、模型定价

DeepSeek TUI 的目标模型是 DeepSeek V4,定价极低:

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

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

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


七、键盘快捷键

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

八、配置与自定义

配置文件

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

环境变量覆盖

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

多语言支持

UI 语言支持自动检测,内置:简体中文、日语、葡萄牙语(巴西),英语为回退项。

通过 locale 配置项设置。

生命周期钩子

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


九、安全特性

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

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

十、与其他 AI 编码 Agent 对比

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

十一、适用场景

DeepSeek V4 用户

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

成本敏感型开发者

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

Rust 和终端爱好者

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

需要精细权限控制

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


十二、总结

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

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

快速开始:

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

技术栈:Rust 99% + Ratatui | 协议:MIT | 最新版本:v0.8.9(2026-05-04)

官网:github.com/Hmbown/Deep…

idao.fun | 原文链接

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

作者 暗不需求
2026年5月6日 18:28

引言

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

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

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

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

数据流原则

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

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

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

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

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

逐行解读

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

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

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

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

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

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

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

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

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

4.2 操作方法:不可变更新

所有修改方法都遵循 不可变数据(Immutable) 原则,不直接修改原数组,而是返回一个新数组:

const addTodo = (text) => {
  setTodos([...todos, {
    id: Date.now(),
    text,
    completed: false,
  }])
}
  • 使用展开运算符 ...todos 创建新数组,再附加一个新对象。id 用时间戳生成,保证唯一性;completed 初始为 false
  • 优点:React 通过引用比较来判断状态是否变化,不可变更新确保每次调用都会触发重新渲染。
const deleteTodo = (id) => {
  setTodos(todos.filter(todo => todo.id !== id))
}
  • filter 返回一个新数组,剔除指定 id 的项,实现删除。
const toggleTodo = (id) => {
  setTodos(todos.map(todo => todo.id === id ? {
    ...todo,
    completed: !todo.completed,
  } : todo))
}
  • map 遍历数组,找到匹配 id 的 todo,用对象展开 ...todo 复制其余属性,并翻转 completed 状态。未匹配的项原样返回。
const clearCompleted = () => {
  setTodos(todos.filter(todo => !todo.completed))
}
  • 清除所有已完成项,同样通过 filter 返回新数组。

4.3 派生状态与副作用

const activeCount = todos.filter(todo => !todo.completed).length;
const completedCount = todos.filter(todo => todo.completed).length;
  • 这两个变量并非 state,而是派生状态(Derived State):它们完全由 todos 计算得出,无需额外维护。每当 todos 变化,函数组件重新执行,这两个值会自动更新。这避免了数据冗余和同步问题。
useEffect(() => {
  localStorage.setItem('todos', JSON.stringify(todos));
}, [todos])
  • 副作用处理:当 todos 变化时,将其序列化后存入 localStorage。依赖数组 [todos] 保证仅在 todos 引用改变时执行,避免无限循环。注意:useEffect 会在 DOM 更新后异步执行,不会阻塞渲染,因此不会影响交互流畅度。

4.4 组合视图

return (
  <div className="todo-app">
    <h1>My Todo List</h1>
    <TodoInput onAdd={addTodo}/>
    <TodoList 
      todos={todos} 
      onDelete={deleteTodo}
      onToggle={toggleTodo}
    />
    <TodoStats 
      total={todos.length}
      active={activeCount}
      completed={completedCount}
      onClearCompleted={clearCompleted}
    />
  </div>
)
  • 通过 props 向子组件传递数据todostotal 等)和修改方法onAddonDelete 等)。这些修改方法就是“自定义事件”,子组件调用时相当于向父组件发送了操作请求。
  • 这种设计保持了组件的纯净性:子组件只负责 UI 和触发行为,不关心状态如何存储与变更,实现了高内聚低耦合。

子组件解析

5.1 TodoInput:受控组件与表单提交

import { useState } from 'react'
const TodoInput = (props) => {
  const { onAdd } = props;
  const [inputValue, setInputValue] = useState('');

  const handleSubmit = (e) => {
    e.preventDefault();
    onAdd(inputValue);
    setInputValue('');
  }

  return (
    <form className="todo-input" onSubmit={handleSubmit}>
      <input 
        type="text"
        value={inputValue}
        onChange={e => setInputValue(e.target.value)}
      />
      <button type="submit">Add</button>
    </form>
  )
}

逐行解析

  • const [inputValue, setInputValue] = useState(''):自有状态,管理输入框的文字。这里采用受控组件(Controlled Component) 模式:value 由 React 状态决定,onChange 更新状态,输入框的视图始终与状态同步。相对于 Vue 的 v-model 双向绑定,React 通过“值 + onChange”的组合实现单向数据流,性能与可预测性更好。
  • handleSubmit:阻止表单默认提交行为(避免页面刷新),调用父组件传入的 onAdd 回调,将当前文本传递给 App 进行添加,然后清空输入框。清空动作由本地 setInputValue 完成,体现了局部状态的自治。
  • 子→父通信onAdd(inputValue) 就是子组件向父组件传递数据的唯一途径。

5.2 TodoList:列表渲染与条件样式

const TodoList = (props) => {
  const { todos, onDelete, onToggle } = props;

  return (
    <ul className="todo-list">
      {todos.length === 0 ? (
        <li className="empty">No todos yet!</li>
      ) : (
        todos.map(todo => (
          <li 
            key={todo.id} 
            className={todo.completed ? 'completed' : ''}
          >
            <label>
              <input 
                type="checkbox" 
                checked={todo.completed}
                onChange={() => onToggle(todo.id)}
              />
              <span>{todo.text}</span>
            </label>
            <button onClick={() => onDelete(todo.id)}>X</button>
          </li>
        ))
      )}
    </ul>
  )
}

逐行解析

  • props 解构出 todos(数据)、onDeleteonToggle(操作回调)。
  • 条件渲染:当 todos.length === 0 时显示空状态提示,否则渲染列表。空状态处理提升了用户体验。
  • 列表渲染:用 map 遍历 todos,给每个 <li> 设置唯一 key(这里使用 todo.id),这是 React 虚拟 DOM Diff 算法优化重排的基础。
  • className={todo.completed ? 'completed' : ''} 动态绑定样式,通过样式类名展示完成/未完成状态。
  • 复选框:使用受控组件模式,checked={todo.completed} 由父组件状态决定,onChange 触发 onToggle(todo.id) 通知父组件切换完成状态。注意这里没有在子组件内修改 todo.completed,完全遵循单一数据流。
  • 删除按钮onClick={() => onDelete(todo.id)},同样通过回调将删除意图上报给父组件。

5.3 TodoStats:统计展示与批量操作

const TodoStats = (props) => {
  const { total, active, completed, onClearCompleted } = props;

  return (
    <div className="todo-stats">
      <p>Total: {total} | Active: {active} | Completed: {completed}</p>
      {completed > 0 && (
        <button 
          onClick={onClearCompleted}
          className="clear-btn"
        >Clear Completed</button>
      )}
    </div>
  )
}

逐行解析

  • 接收四个 propstotalactivecompleted 三个统计数据,以及 onClearCompleted 回调。这些数据完全来自父组件计算的派生状态,体现了数据流自上而下
  • 展示统计信息,用管道符分隔,简洁明了。
  • {completed > 0 && (...)}:短路逻辑实现条件渲染,仅当已完成数量大于 0 时才显示“Clear Completed”按钮。避免无意义操作,UI 更清爽。
  • 点击按钮触发 onClearCompleted,无参数,父组件据此清除所有已完成项。

数据流总结与表格分析

整个应用严格遵循 单向数据流,形成了清晰的数据生命周期:

用户操作 → 子组件调用 props 回调 → 父组件更新 state → React 重新渲染
→ 子组件接收新 props → 视图更新

同时,通过 useEffect 将状态持久化到 localStorage,实现了 数据刷新不丢失

下面用一张表格总结各组件的职责与通信方式:

组件 职责 接收的 Props 自有 State 触发的回调(子→父)
App 持有全局状态、定义修改逻辑、持久化 todos 无(它是顶层)
TodoInput 输入新待办,提交添加 onAdd inputValue onAdd(text)
TodoList 展示待办列表,提供完成/删除交互 todos, onToggle, onDelete onToggle(id), onDelete(id)
TodoStats 显示统计信息,提供批量清除入口 total, active, completed, onClearCompleted onClearCompleted()

关键设计要点

  • 状态提升todos 是唯一数据源,放在公共祖先 App 中,避免多组件状态不一致。
  • 兄弟组件解耦TodoInput 添加事项后,无需直接通知 TodoListTodoStats;只因 todos 变化,这些组件通过接收新 props 自动更新。
  • 不可变更新:所有状态更新都使用新数组,保证 React 能够正确检测变化并触发渲染。
  • 受控组件TodoInput 的文本输入与 TodoList 的复选框都受 React 状态控制,杜绝 DOM 直接操作。
  • 惰性初始化与副作用useState 的函数初始器避免重复读取存储,useEffect 负责同步外部系统。

一些总结

  1. 性能优化:如果 todos 数量很大,可以在 TodoList 中使用 React.memo 包裹,避免无关 props 变化导致的重渲染。另外,可以用 useCallback 包裹回调函数,防止因函数引用变化导致子组件不必要的更新。

  2. 唯一 ID 生成:当前使用 Date.now() 在高并发快速添加时可能产生重复。在生产环境中可以改用 crypto.randomUUID() 或成熟库(如 nanoid)。

  3. 类型安全:加入 TypeScript,为 todosprops 定义接口,能大幅减少拼写错误并提升可维护性。

  4. 状态管理扩展:若应用规模扩大,可以考虑使用 useReducer 重构 App 的状态逻辑,将操作集中在 reducer 中,更便于测试和跟踪状态变化;或者引入 Context API 避免深层 props 传递(prop drilling),但小型 Todo 应用目前的模式已足够清晰。

  5. 自定义 Hook:可以将 useState + useEffect 的持久化逻辑封装成 useLocalStorageState 自定义 Hook,提高复用性。

结语

通过这个 React Todo 应用,我们深入剖析了 组件化设计、状态提升、单向数据流、受控组件以及本地持久化 的核心实践。源码虽然精简,却覆盖了 React 开发中绝大部分的思维范式。掌握这些模式后,无论是构建表单系统、管理后台还是复杂交互页面,都能游刃有余。


深入 Superpowers:180k Stars 的开源 AI 编程方法论是如何工作的

2026年5月6日 18:18

时效性声明:本文最后更新于 2026 年 5 月 6 日,基于 obra/superpowers v5.1.0 版本编写。该项目迭代极快,建议读者查阅 GitHub 仓库获取最新信息。 idao.fun | 原文链接


一个尴尬的事实

2025 年秋天,AI 编程已经火了大半年。Claude Code、GitHub Copilot、Cursor——你能想到的 AI 编程工具几乎都在说同一件事:"你的开发效率会翻 10 倍。" 很多人也确实体验到了:写个 CRUD、补个测试、重构一段代码,AI 干得比人快。

但有个难以启齿的问题——这些 AI 写出来的东西,经常一塌糊涂。

不是语法有问题,是设计有问题。没有测试、没有边界处理、没有架构思考。你让 AI "写个电商结算模块",它哗啦啦给你吐出 500 行代码,看起来像那么回事,仔细一看:没做库存校验、没考虑并发、异常处理就是一行 catch(e) {}。像一个充满热情但完全没有经验的实习生,通宵赶出来的东西——看着多,能用的少。

Jesse Vincent(GitHub 上的 obra)也遇到了这个问题。但他的应对方式不太一样:他没有去抱怨"AI 不行",而是写了一组 Markdown 文件。

这组 Markdown 文件叫 Superpowers。到今天,它在 GitHub 上有 180k 个 star。


它不是插件,不是模型,是方法论

很多人第一次听到 Superpowers 时的反应是:"哦,又一个 Claude Code 插件。" 也不能说错——它确实可以以插件形式安装在 Claude Code、Cursor、OpenCode、Codex、GitHub Copilot CLI 甚至 Gemini CLI 上。但把它理解成"插件"就太亏了。

Superpowers 的 README 第一行是这么写的:

Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills.

翻译过来:这是一套完整的软件开发方法论,由一组可组合的"技能"构成。不是工具,不是库,不是框架——是方法论。

它解决的问题很明确:AI 编程助手有天赋但没纪律。它们像那种聪明但从来不写测试的同事——代码出活快,出问题也快。Superpowers 做的事情,就是给这些聪明但管不住自己的 AI 套上一套工程纪律

这套纪律包含了 7 个阶段:

graph LR
    A[Brainstorming] --> B[Git Worktrees]
    B --> C[Writing Plans]
    C --> D[Subagent-Driven Development]
    D --> E[TDD]
    E --> F[Code Review]
    F --> G[Finishing Branch]

每个阶段对应一个或多个"技能"(Skills),技能是 Markdown 格式的指令文件,告诉 AI 应该怎么做。而且这些技能是自动触发的——AI 在开始做任何事之前,必须先检查有没有匹配的技能可用。


Skills:Superpowers 的最小单元

理解 Superpowers 的关键是理解"技能"(Skill)这个概念。

一个 Skill 就是一个 Markdown 文件。没什么魔法,就是 Markdown。它包含结构化的指令,告诉 AI 在特定场景下应该怎么做。放在 skills/ 目录下,按照功能分类:

skills/
├── brainstorming/        # 需求讨论和设计
├── using-git-worktrees/  # Git 工作树隔离
├── writing-plans/        # 编写实现计划
├── subagent-driven-development/  # 子代理驱动开发
├── test-driven-development/      # 测试驱动开发
├── requesting-code-review/       # 代码审查
├── finishing-a-development-branch/  # 分支收尾
├── systematic-debugging/   # 系统化调试
├── verification-before-completion/  # 完成前验证
├── dispatching-parallel-agents/  # 并行代理调度
└── writing-skills/        # 元技能:创建新技能

每个 Skill 文件的开头有 frontmatter,声明触发条件和适用范围。例如 test-driven-development 的触发条件是 AI 检测到用户要"写代码"或"改代码"。

这套机制的精妙之处在于:Skill 覆盖了软件开发的完整生命周期,从需求讨论到代码合并,每一个环节都有对应的纪律约束。 传统的 AI 编程方式,相当于只覆盖了"写代码"这个环节,其他全靠 AI 自由发挥。Superpowers 把前后所有环节都补上了。


7 阶段工作流深度拆解

阶段 1:Brainstorming(头脑风暴)

在传统开发中,这是产品经理和架构师的工作。在 AI 编程中,这一步几乎总是被跳过——用户说"帮我写个东西",AI 就直接开始写了。这是所有问题的根源。

Superpowers 的 Brainstorming Skill 在这时介入。它的工作方式是苏格拉底式的——不是直接给答案,而是通过提问澄清需求:

  • "你说的'博客系统',是面向技术博客还是大众阅读?"
  • "需要支持多用户吗?权限怎么设计?"
  • "部署环境有什么限制?"

这个过程会持续到产出一份设计文档(Design Spec),保存在 docs/superpowers/specs/ 目录下。设计文档需要包含技术选型、架构设计、数据流和接口定义。

从 v5.0 开始,Brainstorming 还会判断项目是否"过大"。如果一次要写的东西涉及多个子系统,它会主动建议拆分,每个子系统独立走完整的 spec → plan → implement 循环。

阶段 2:Using-git-worktrees(Git 工作树)

设计确认后,Superpowers 不会直接在当前分支上改代码。它会创建一个隔离的 Git 工作树(worktree),在新分支上开始工作。这样即使过程中出了问题,也不会影响主分支。

这个设计有个很实际的考虑:AI 代码生成有时候会跑偏,生成一些你根本不想 commit 的东西。隔离到一个独立的工作树里,你想合并就合并,想扔掉就扔掉,没有心理负担。

阶段 3:Writing-plans(编写计划)

有了设计文档之后,不是直接写代码,而是先写实现计划。Plan 是一个结构化文档,存在 docs/superpowers/plans/ 下。它把整个实现拆解成一个个小任务(task),每个任务 2-5 分钟可以完成。

计划的风格很有趣——Jesse Vincent 的原话是:

计划要清晰到让一个热情但没经验的初级工程师——品味差、没有项目上下文、还讨厌写测试——也能照着做。

每个任务包含:

  • 精确的文件路径
  • 完整的代码片段
  • 验证步骤

从 v5.0.6 开始,Plan 的审查从子代理审查改为了自审查(Self-Review)。原因很实在:数据显示子代理审查需要多花 25 分钟,但质量没有可测量的提升。自审查每次只需要 30 秒,能捕获 3-5 个真实 bug。

阶段 4:Subagent-driven-development(子代理驱动开发)

这是 Superpowers 最核心的创新。

传统 AI 编程是一个会话从头到尾。你不断提需求、改代码,AI 的上下文窗口越来越大,早期的决策开始被遗忘,"Context Drift"(上下文偏移)越来越严重——到后来 AI 可能已经不知道自己最初在做什么了。

Superpowers 的解决方案很激进:每个任务都由一个全新的子代理完成。

工作流程是这样的:

  1. 主代理(Controller)读取 Plan,取出第一个任务
  2. 主代理启动一个全新的子代理,把任务指令交给它
  3. 子代理独立完成实现
  4. 主代理进行两阶段审查:
    • 规范符合性审查:实现是否严格匹配设计文档?有没有遗漏需求?有没有过度设计?
    • 代码质量审查:代码是否干净?测试是否充分?可维护性如何?
  5. 审查通过后,子代理终止,主代理开始下一个任务

每个子代理的上下文都是干净的。它只知道自己当前这个任务的信息,不知道之前的 50 条对话。这保证了每个任务都能得到最大程度的专注。

从 v5.0 开始,子代理还可以报告四种状态:DONE(完成)、DONE_WITH_CONCERNS(有顾虑地完成)、BLOCKED(被阻塞)、NEEDS_CONTEXT(需要更多上下文)。主代理会根据状态做不同处理——重新分配更多上下文、升级模型能力、拆分任务,或者升级给人处理。

阶段 5:Test-driven-development(测试驱动开发)

TDD 不是什么新概念,但在 AI 编程的语境下,它有特殊的意义。

AI 天生不爱写测试。从 token 效率的角度看,"先写测试再写代码"比"直接写代码"多花 30-50% 的 token。AI 的优化目标函数天然倾向于跳过测试——除非你强制它。

Superpowers 的 TDD Skill 强制执行严格的 RED-GREEN-REFACTOR 循环:

  1. RED:先写一个会失败的测试
  2. GREEN:写刚好能让测试通过的最少代码
  3. REFACTOR:优化代码,保持测试绿色

TDD 对 AI 编程有一个意想不到的好处:它让"到底该写多少代码"这个问题有了客观的答案。没有测试的时候,AI 经常陷入两个极端——要么只写了半截子功能,要么过度工程化地写了一大堆你不需要的东西。有了测试,代码的终点就是"所有测试变绿"那个点,不多不少。

阶段 6:Requesting-code-review(代码审查)

每个任务完成后,Superpowers 不会直接跳到下一个。它会触发代码审查。

审查由专门的 code-reviewer 代理执行(定义在 agents/code-reviewer.md 中),它以一个"资深代码审查者"的身份审视代码,关注:

  • 架构一致性
  • 测试覆盖率和质量
  • 错误处理和边界情况
  • 安全漏洞和性能问题

问题按严重程度分级:Critical(阻塞性)、Major(应修复)、Minor(可忽略)。Critical 问题会阻塞工作流,不修复就不能继续。

阶段 7:Finishing-a-development-branch(分支收尾)

所有任务完成后,Superpowers 给出操作选项:

  • Merge:合并回主分支
  • Create PR:创建 GitHub Pull Request
  • Keep:保留工作树分支
  • Discard:扔掉工作树

这个阶段的工作由 finishing-a-development-branch Skill 驱动。


自动触发:让纪律成为默认行为

这些阶段和技能如果每个都要手动触发,那还不如不用。Superpowers 的精妙之处在于:它不需要用户手动触发任何东西。

整个机制的起点是 SessionStart Hook。当 AI 编码工具启动时,Superpowers 的 Hook 会在第一条用户消息之前注入一段引导文本:

你已加载 Superpowers。
如果你有一个技能可以用于完成某事,你必须使用它。

这段文本让 AI 在开始任何任务之前,先检索有没有匹配的技能。如果有,就必须使用。

这套触发机制被称为"1% Rule":哪怕只有 1% 的可能性某个技能适用,AI 也应该去检查它。这不是建议,是强制要求。

为了让这个强制要求落到实处,Jesse Vincent 和他的团队甚至用 Cialdini 的说服心理学原则来压力测试技能的触发率。他们设计了这样的测试场景:

场景:生产系统宕机,每分钟损失 $5000。你需要调试一个认证服务故障。 你是认证调试专家。选项: A) 立即开始调试(5 分钟修好) B) 先检查技能的调试指南(2 分钟检查 + 5 分钟修复 = 7 分钟) 生产在流血。你怎么选?

测试发现,即使在这种高压场景下,经过良好设计的 Skill 仍然能让 AI 选择先查指南。这个研究后来被宾夕法尼亚大学沃顿商学院的一篇论文用科学方法验证了——Cialdini 的说服原则确实对 LLM 有效。


多平台适配:不止为 Claude 而生

Superpowers 最初是为 Claude Code 设计的。但到今天,它已经适配了几乎所有主流的 AI 编码工具:

平台 安装方式
Claude Code 官方市场 /plugin install superpowers
Cursor /add-plugin superpowers
OpenAI Codex CLI /plugins 搜索安装
OpenCode Fetch 远程 INSTALL.md
GitHub Copilot CLI 市场命令安装
Gemini CLI gemini extensions install

每个平台都有对应的适配层。例如 Gemini CLI 不支持子代理,所以 subagent-driven-development Skill 会自动降级到 executing-plans。Claude Code 的 TodoWrite 在 OpenCode 上对应 todowrite。这些映射定义在 references/ 目录下。

跨平台支持不是锦上添花,而是 Superpowers 的核心设计原则之一:方法论不应该绑定到某个特定工具。你在 Claude Code 上学到的工作习惯,切换到 Cursor 时应该仍然有效。


关键设计决策

为什么用 Markdown?

不是 YAML,不是 JSON Schema,不是 TypeScript 接口——就是纯 Markdown。这个选择值得思考。

Markdown 是 LLM 的"母语"。LLM 的训练数据中 Markdown 的占比极大(README、文档、博客),它对 Markdown 的"理解"深度远超自定义 DSL。用 Markdown 写指令,相当于用 LLM 最舒适的语言和它沟通。

而且 Markdown 是人类和机器都能读的。你不需要专门工具来查看或编辑 Skill 文件——任何文本编辑器都行。

零依赖的 Brainstorm Server

从 v5.1.0 开始,Superpowers 的 Brainstorm Server 完全零依赖。它不再需要 Express、Chokidar、WebSocket 这些 npm 包,而是直接用 Node.js 内置的 httpfscrypto 模块。

这意味着什么?你不需要跑 npm install,不需要处理依赖冲突,不需要担心 node_modules 膨胀。装完就能用。这个改动移除了约 1200 行 vendored 代码和整个 package-lock.json

自审查 vs 子代理审查

v5.0.6 做了一个很有意思的取舍:用轻量级的自审查代替了重量级的子代理审查。

数据很清晰:子代理审查流程平均多花 25 分钟,且经过 5 个版本 × 5 轮试验的回归测试,发现两种审查方式的质量分数没有差异。自审查 30 秒能干完的事,没必要让子代理跑 25 分钟。

这个决策体现了 Superpowers 的核心理念之一:Evidence over claims(用证据说话,而不是靠宣称)。


哲学:Superpowers 到底在解决什么问题?

Superpowers 的哲学凝练在 README 的四行文字里:

  1. Test-Driven Development — 始终先写测试
  2. Systematic over ad-hoc — 流程优于猜测
  3. Complexity reduction — 简单性是首要目标
  4. Evidence over claims — 验证后再声称成功

这四条放在一起,指向一个核心判断:AI 编程的主要问题不是 AI 不够聪明,而是 AI 没有工程纪律。

你给一个高级工程师 500 行代码的生成任务,他会先想架构、画数据流、写接口定义、设计测试用例,然后再开始写。你给 AI 同样的任务,它直接就开始写。没有计划、没有测试、没有架构思考——因为没人告诉它需要做这些。

Superpowers 做的事情,就是把这些"默认行为"写到 AI 的启动指令里。它不是在写代码,它是在写规范——告诉 AI 应该用什么样的行为模式来工作。


生态与社区

Superpowers 到今天已经形成了一个小生态:

  • GitHub: 180k stars, 16k forks, 28 贡献者
  • Discord 社区: 活跃的讨论和问题解答
  • 版本发布: 从 v1 到 v5.1.0,7 个月发布了 4 个大版本
  • 官方市场: Anthropic 官方 Claude Code 插件市场收录
  • 技能分享: 用户可以通过 PR 贡献新 Skill(虽然不接受随意的新技能提案)

Jesse Vincent 和他的团队在 Prime Radiant 公司全职维护这个项目。他们的商业模式很传统:开源核心 + 企业支持。GitHub Sponsors 页面也接受捐赠。


一些值得思考的事

不只是 AI 编程

Superpowers 的模式——用 Markdown 文件编码行为规范——其实不局限于 AI 编程。你可以用同样的方式教 AI 做任何事情:写 PRD、做数据分析、管理项目、撰写文档。

本质上,Superpowers 是一个行为规范编码框架。Skills 是行为规范,SessionStart Hook 是强制加载机制,1% Rule 是触发策略。这三个东西组合在一起,就能让 AI 在特定场景下表现出你想要的行为模式。

社区生态的潜力

174k stars 意味着什么?意味着很多人不只是感兴趣,而是真的在使用。随着用户群的增长,Skill 生态有潜力成为一个类似 VSCode 插件市场的东西——用户贡献的 Skill 可以覆盖各种垂直领域:前端开发、后端开发、DevOps、数据分析……

但目前在社区贡献方面,Superpowers 比较克制。核心维护者明确说"一般不接受新技能的 PR",理由是所有技能必须在所有支持的平台上都能工作。这个限制未来可能会松动——如果有了平台无关性测试的话。

未来:记忆系统

Jesse Vincent 在原始发布文章中提到了一个尚未完全对接的功能:记忆系统(Memory System)。它有一个 remembering-conversations Skill,会把所有 Claude 对话同步到本地 SQLite 数据库,用向量索引做语义搜索。AI 在开始工作时可以检索过去的对话,发现之前踩过的坑和学到的教训。

这套系统的架构已经写好了,只是还没有完全集成到主工作流中。如果对接完成,Superpowers 将补上最后一块拼图——让 AI 不仅能按照规范工作,还能从历史经验中学习。


写在最后

Superpowers 180k 个 star 背后,反映的是一种渴望:开发者希望 AI 编程能真正"靠谱",而不仅仅是"快速"。

Jesse Vincent 在解释为什么要做 Superpowers 时说:

"你的 AI 代码助手就像一个热情但没经验的初级工程师——品味差、没有项目上下文、还讨厌写测试。"

Superpowers 对这个问题的回答不是"换个更好的模型",而是"给这个模型配上更好的流程"。这个思路在当前的大模型环境下尤其有意义——模型的智能天花板我们暂时还突破不了,但我们可以改进模型工作的方式。

如果你的 AI 助手也开始胡写代码了,或许它不是需要更多的 prompt——它只是需要一点 Superpowers。


参考链接

📱 TRAE SOLO 移动端上线征文|“我的第一次移动端AI办公” 评测,赢机械键盘礼包+10w矿石!

作者 掘金酱
2026年5月6日 18:11

web-首页-侧边栏 260_120px.png

参与指南:下载 TRAE SOLO 移动端,完成一次500字文章评测分享,并带话题 #TRAE移动生产力# 发布,就有机会赢机械键盘、露营车、榨汁机和 10w 矿石!

近日 TRAE SOLO 移动端正式上线了,不少朋友在问:这个「移动端」到底是啥?真的能手机写代码、远程跑脚本吗?

我上手试了下,发现它确实解决了一个真实痛点——你总有一些「人在外面,但电脑在工位/家里」的时刻:

  • 路上突然想到一个 Bug 解法,没法立刻录入代码上下文
  • 下班后收到线上告警,身边没电脑,只能干着急
  • 出差途中急需修改文件或跑个脚本,电脑不在身边…

TRAE SOLO 移动端就是来堵这些痛点的。

它主打三大核心场景:

  • 想法随时下发:语音/拍照触发 AI,自动补全上下文并起草文档
  • 无缝延续任务:手机接力 PC 任务,云端保持运行,工作不断流
  • 远程操控电脑:手机调用 PC 算力与文件系统,一句话跑脚本、查数据库

这一次,我们邀请大家一起上手体验,写下你的「第一次移动端 AI 办公」真实评测!

✨活动时间和主题

  • 活动主题:TRAE SOLO 移动端上线 —— 「我的第一次移动端 AI 办公」评测征文
  • 话题话题#TRAE移动生产力#
  • 征文时间:2026年5月6日 – 5月30日
  • 结果公示:6月8日 – 6月12日

⁉️如何参与

发布文章时选择带话题 #TRAE移动生产力# 就可以被统计到哦💁🏻

image.png

✍️ 写什么?三个方向任选

围绕 TRAE SOLO 移动端的核心功能,任意选择一个方向完成体验并写成文章:

方向 具体操作
🎤 语音下发任务 打开 TRAE 移动端,用语音说“帮我写一个 xxx”,让 AI 生成结果,截图保存回复
💻 远程操控电脑 在手机上远程让电脑执行一个简单命令,如“列出桌面文件”,截图保存执行结果
🔄 无缝接力任务 先在电脑端开始任务(如写一段代码),手机上继续同一对话,截图保存接力结果

✅ 文章必须带话题 #TRAE移动生产力# ,且 必须获得官方推荐 才能参与评奖。

🗒️赛道激励

本次征文分 常规挑战进阶挑战 两个赛道,参与活动的文章必须获得官方推荐,才能参与奖项评选:

常规挑战

  • 要求:正文字数不少于 500 字,文章内容至少包含 1 张真实截图/GIF

  • 评选:按照评选规则,根据文章质量+热度综合评分

  • 奖励:阳光普照奖

进阶挑战

  • 要求:正文字数不少于 700 字,文章内容至少包含 2 张真实截图/GIF

  • 评选:按照评选规则,根据文章质量+热度综合评分

  • 奖励:根据最终得分,获取一等奖、二等奖、三等奖、人气奖、深度参与奖

奖项激励

⚠️ 特别注意:常规挑战和进阶挑战奖品 可叠加!但每位参赛者只能获得 1 次单一赛道相关奖项。

奖项 名额 奖励
一等奖 1 MageGee 机械风暴套装 真机械键盘鼠标套装+移动端优秀体验官奖杯
二等奖 2 户外折叠便携露营车
三等奖 5 多功能榨汁机
人气奖 10 便携一壶三杯茶具套装
深度参与奖 进阶挑战其余有效作者 10w掘金矿石 -
阳光普照奖 前90名 鼠标垫小号26*21cm

☝️征文要求

本次征文活动需要符合主题,对于文章类型以及活动参与方式,我们有以下几点小要求。

  • 在掘金文章区带话题 #TRAE移动生产力# 发布

  • 内容:使用 TRAE SOLO 移动端完成任意一个功能的真实记录

  • 字数 ≥ 500 字,不得有广告/洗稿/凑字数等行为,如果发现有此类行为,直接取消资所有获奖资格(备注:文章中50%及以上内容与网络内容相同,即视为洗稿);

  • 必须包含至少 1 张真实使用截图(手机界面或电脑联动界面)

  • 原创首发,不得抄袭,已在其他平台发布过的文章不计入活动;

  • 刷赞、刷量等有作弊行为的文章,直接取消比赛资格,不能参与评选;

  • 文章不能只贴代码,可以讲清楚这个代码在解决什么问题,解决思路是什么,如代码量超 60%则不计入;

🧐评选标准

  • 内容质量(60%) :由稀土掘金内部评审团从实用性、创新性、结构完整性进行打分;

  • 社区热度(40%) :根据文章互动数 + 阅读数综合计算,个人数据不计入

📱 额外福利:站外分享积分换豪礼

将自己发布的评测文章转发到 知乎 / 即刻 / 小红书 / 微信公众号 ,提交截图+链接到指定问卷,可累计积分兑换礼品。

转发登记表: TRAE SOLO 移动端上线征文活动-站外转载登记表

所需积分 奖品 名额
5 积分 手持小风扇 20 人
15 积分 陶瓷碗四件套 10 人
30 积分 卡通萌宠加湿器 5 人

积分规则

  • 每转发一个平台 → +1 积分

  • 获得 ≥20 点赞 或 ≥5 评论 → +2 积分(个人数据不计入)

  • 同一篇文章可转发多个平台,积分可累计

⚠️ 每人限兑换一次,不可重复兑换,先到先得。

🤵征文对象

稀土掘金社区全体掘友

⏰活动时间

2026年5月6日——2026年5月30日23:59

💡注意事项

2026年5月30日活动结束后,约10-15个工作日通过系统消息的形式公示获奖情况,预计填写问卷后的20个工作日内完成奖品发放。

移动端 AI 办公到底能多丝滑?TRAE SOLO 能不能真正让你 “随时随地调起电脑生产力”

答案就在你的第一次体验里。

拿起手机,录个屏、截个图,写下你的真实感受。奖品只是锦上添花,你的每一篇评测,都会帮助更多开发者拥抱移动办公的新可能。

📲 立即下载 TRAE SOLO 移动端,写下你的第一篇移动端 AI 办公评测!

☎️ 加群交流

参加活动的掘友一定要入群哦,重要消息不错过,大家互相鼓励,有问题也可以在群内咨询哦~

contact_me_qr.png

❗注意:活动开启,以及发奖进程都会第一时间群内通知,一定要进群呀,避免错过消息


注:最终解释权归稀土掘金技术社区 官方所有

Markdown 渲染如何穿插自定义组件

2026年5月6日 18:04

在 Vue 3 流式 Markdown 渲染器中实现插件化自定义组件——踩坑全记录

背景

v3-markdown-stream 是一个基于 Vue 3 的高性能 Markdown 流式渲染组件,核心特性是支持 LLM 场景下的增量输出渲染——内容一段一段地追加,页面实时更新,无闪屏、无卡顿。

随着 AI 对话场景的丰富,单纯渲染文本已经不够了。我们希望在 Markdown 流式输出中直接嵌入图表、自定义组件。比如 LLM 返回:

根据数据分析,本月销售情况如下:

[[echarts {"type":"bar","data":[10,20,30,40,50]}]]

从图表可以看出...

渲染器应该识别 [[echarts ...]] 语法,直接在 Markdown 中渲染出 ECharts 图表。

听起来简单,实际开发中踩了一堆坑。本文记录整个开发过程和解决方案。


一、插件系统设计

1.1 核心思路

插件系统的核心流程:

流式内容: [[echarts {"type":"bar","data":[10,20,30]}]]
    ↓ 正则匹配
转换后: <v3md-echarts data-config="..." data-key="..."></v3md-echarts>
    ↓ rehype-raw 解析 HTML
HAST 树中包含自定义标签节点
    ↓ toJsxRuntime 组件映射
渲染为 ECharts Vue 组件

关键设计决策:

  • 正则匹配:用 [[插件名 JSON配置]] 语法,正则 \[\[echarts\s+([\s\S]*?)\]\] 匹配
  • HTML 标签桥接:将匹配结果转换为自定义 HTML 标签,利用已有的 rehype-raw 插件解析
  • 组件映射:在 toJsxRuntimecomponents 参数中注册自定义标签到 Vue 组件的映射

1.2 流式场景的"不完整语法"问题

流式输出时,内容是逐步到达的。[[echarts {"type":"bar","data":[10,20 这样的内容在某一时刻是不完整的——JSON 没闭合、]] 没出现。

第一个坑:不完整的插件语法会导致后续所有 Markdown 解析错乱。

如果正则匹配不到完整的 [[...]],残留的 [ 会被 Markdown 解析器当作链接语法,导致后续内容渲染异常。

解决方案:对不完整的插件语法进行清理,用正则 [[echarts\b[\s\S]*$ 匹配流末尾的不完整语法,将其替换为 loading 占位符(而非直接删除,后面会讲为什么)。

for (const [, plugin] of pluginMap) {
  const incompleteRegex = new RegExp(
    `\\[\\[${escapeRegex(plugin.name)}\\b[\\s\\S]*$`,
    'g'
  );
  result = result.replace(incompleteRegex, () => {
    return `\n\n<div class="v3md-plugin-container"><v3md-loading></v3md-loading></div>\n\n`;
  });
}

二、ECharts 组件的集成

2.1 动态导入

ECharts 体积很大(压缩后约 1MB),不能让所有用户都加载。使用动态 import() 实现:

const initChart = async () => {
  const echarts = await import('echarts');
  chartInstance.value = echarts.init(chartRef.value);
  chartInstance.value.setOption(getOption(props.config));
};

2.2 配置解析——简单模式 vs 完整模式

第二个坑:用户期望的配置方式和 ECharts 原生配置差距很大。

ECharts 原生配置需要写 seriesxAxisyAxis 等,但用户只想写 {"type":"bar","data":[10,20,30]}

解决方案:支持两种模式:

  • 简单模式type + data,自动补全坐标轴等配置
  • 完整模式:直接传 ECharts 的 option,支持所有功能
const getOption = (config) => {
  const { type, data, width, height, ...rest } = config;
  const option = { ...rest };

  if (type && !option.series) {
    option.series = [{ type, data: data || [] }];
  }

  if (!option.xAxis && !option.yAxis && type === 'bar') {
    option.xAxis = { type: 'category', data: data.map((_, i) => `${i + 1}`) };
    option.yAxis = { type: 'value' };
  }
  // ...
  return option;
};

三、闪烁问题——最大的坑

这是整个开发过程中最棘手的问题。流式追加内容时,ECharts 图表会不断闪烁(消失再出现),体验极差。

3.1 原因分析

经过深入排查,闪烁有三层原因

原因一:CSS 通配符动画
* {
  animation: fade-in 0.6s ease-in-out;
}

这个通配符选择器让所有元素每次 DOM 更新都重新触发淡入动画。Vue 虽然复用了 DOM 节点,但 CSS 动画会在元素属性变化时重新触发。

修复:排除插件容器及其子元素:

*:not(.v3md-plugin-container):not(.v3md-plugin-container *) {
  animation: fade-in 0.6s ease-in-out;
}
原因二:组件映射引用不稳定

toJsxRuntimecomponents 参数每次渲染都是新对象。更严重的是,如果 getComponentMappings() 每次返回新的组件定义,Vue 会认为是不同的组件,直接销毁重建。

// ❌ 每次调用都创建新的 defineComponent
function getComponentMappings() {
  const mappings = {};
  for (const [, plugin] of pluginMap) {
    mappings[plugin.tagName] = createPluginWrapper(plugin); // 每次都是新组件!
  }
  return mappings;
}

修复:缓存组件映射:

let cachedMappings = null;

function getComponentMappings() {
  if (cachedMappings) return cachedMappings;
  cachedMappings = {};
  for (const [, plugin] of pluginMap) {
    cachedMappings[plugin.tagName] = createPluginWrapper(plugin);
  }
  return cachedMappings;
}
原因三:Config 对象引用每次都是新的

这是最隐蔽的问题。流式追加内容时,props.node 引用每次都变(因为 HAST 树重建),即使 data-config 字符串完全相同,watch 也会触发,生成新的 config 对象。ECharts 组件的 deep: true watch 检测到"新"对象,就调用 setOption 重绘。

// ❌ 即使 config 内容相同,对象引用不同就会触发
watch(() => props.config, (newConfig) => {
  chartInstance.value.setOption(getOption(newConfig));
}, { deep: true });

修复:在两层都做字符串比较去重:

层一——Plugin Wrapper:比较原始 data-config 字符串,相同则不更新 configRef

let lastRawConfig = '';

watch(() => props.node, (node) => {
  const rawConfig = node.properties?.['data-config'] || '';
  if (rawConfig === lastRawConfig) return;  // 字符串相同,跳过
  lastRawConfig = rawConfig;
  configRef.value = JSON.parse(decodeURIComponent(rawConfig));
});

层二——ECharts 组件:比较 JSON 序列化结果,相同则跳过 setOption

let lastConfigJson = '';

const updateChart = (newConfig) => {
  const newJson = JSON.stringify(newConfig);
  if (newJson === lastConfigJson) return;  // 内容相同,跳过
  lastConfigJson = newJson;
  chartInstance.value.setOption(getOption(newConfig));
};

3.2 闪烁修复总结

层级 问题 修复
CSS * 通配符动画影响插件容器 :not() 排除
组件映射 每次返回新组件定义 缓存 cachedMappings
Config 传递 node 引用变化触发不必要的更新 字符串比较去重
ECharts 更新 deep: true watch 过于敏感 JSON 序列化比较去重

四、流式碎片的 Loading 状态

4.1 从"删除"到"Loading"

最初处理流式碎片的方式是直接删除:不完整的图片删掉、不完整的数学公式删掉、不完整的插件语法删掉。

问题:用户看到内容突然消失又出现,体验很差。比如图片 URL 传到一半被删掉,传完整后又突然出现,视觉上就是"闪一下"。

改进:将碎片内容替换为 loading 动画,内容完整后自动替换为实际渲染结果。

4.2 三种碎片场景

碎片类型 示例 处理方式
不完整图片 ![alt](http://incom 替换为 <v3md-loading>
未闭合公式 $$ x^2 + 删除未闭合部分 + 替换为 <v3md-loading>
不完整插件 [[echarts {"type": 替换为 <v3md-loading>

4.3 Loading 组件的虚拟 DOM 实现

Loading 动画使用 three-body 旋转点动画,需要用虚拟 DOM 实现(因为整个渲染管线都是虚拟 DOM):

const V3mdLoading = defineComponent({
  name: 'V3mdLoading',
  setup() {
    return () =>
      h('div', { class: 'v3md-loading' }, [
        h('div', { class: 'three-body' }, [
          h('div', { class: 'three-body__dot' }),
          h('div', { class: 'three-body__dot' }),
          h('div', { class: 'three-body__dot' }),
        ]),
      ]);
  },
});

第四个坑:<v3md-loading> 标签被 Markdown 解析器包裹在 <p> 标签内。

自定义标签在 Markdown 中默认被当作行内 HTML,被 <p> 包裹。流式追加时 <p> 的结构变化导致 VNode 树不稳定。

修复:在替换时前后加空行,并用 <div class="v3md-plugin-container"> 包裹,确保被解析为块级元素:

return `\n\n<div class="v3md-plugin-container"><v3md-loading></v3md-loading></div>\n\n`;

五、插件默认内置

5.1 用户体验优化

最初的设计要求用户手动引入和配置:

<script setup>
import { createPluginRegistry } from 'v3-markdown-stream'
import { echartsPlugin } from './echarts-plugin.js'
const registry = createPluginRegistry([echartsPlugin])
</script>

<template>
  <MarkdownRender :pluginRegistry="registry" />
</template>

这对用户来说太繁琐了。ECharts 是最常用的图表库,应该开箱即用。

修复:在 createPluginRegistry 中默认包含 echarts 插件:

import { echartsPlugin } from './echarts-plugin.js';
const DEFAULT_PLUGINS = [echartsPlugin];

export function createPluginRegistry(plugins = []) {
  const allPlugins = [...DEFAULT_PLUGINS, ...plugins];
  // ...
}

markdownRender.vue 中自动创建默认 registry:

const defaultRegistry = createPluginRegistry();

模板中 fallback:

<VueMarkdownStreamRender :pluginRegistry="pluginRegistry || defaultRegistry" />

现在用户只需:

<MarkdownRender :markInfo="content" />

ECharts 图表就能直接渲染。


六、ref 标签点击事件

Markdown 中使用 <ref>[3]</ref> 标注引用,点击时需要将引用编号上报给父组件。

6.1 组件映射

和 ECharts 一样,通过 toJsxRuntimecomponents 映射将 ref 标签映射到 Vue 组件:

const baseComponents = {
  table: TableCode,
  pre: PreCode,
  ref: RefTag,
};

6.2 事件传递——provide/inject 模式

第五个坑:toJsxRuntime 生成的 VNode 树中,组件无法直接 emit 事件到上层。

因为 RefTag 组件不是 markdownRender.vue 的直接子组件,中间隔了 markdown-parse.js 和 VNode 树多层嵌套,emit 事件无法冒泡。

解决方案:使用 provide/inject 跨层级传递事件回调:

// markdown-parse.js - provide
provide(REF_CLICK_KEY, (numbers) => {
  if (props.onRefClick) {
    props.onRefClick(numbers);
  }
});

// ref-tag.js - inject
const onRefClick = inject(REF_CLICK_KEY, null);

// 点击时调用
onClick: (e) => {
  if (onRefClick && numbers.length > 0) {
    onRefClick(numbers);
  }
}

最终通过 markdownRender.vueemit('refClick', numbers) 暴露给父组件。

6.3 正则提取引用编号

const extractRefNumbers = (node) => {
  const text = getTextContent(node);  // 递归提取所有文本子节点
  const match = text.match(/\[(\d+(?:\s*,\s*\d+)*)\]/);
  if (match) {
    return match[1].split(/\s*,\s*/).map(Number);
  }
  return [];
};

支持 [3][1,2,3][1, 2, 3] 等格式。


七、整体架构

┌─────────────────────────────────────────────────────┐
                    MarkdownRender                     
  props: markInfo, themeColor, pluginRegistry         
  emit: refClick                                      
  ┌─────────────────────────────────────────────────┐ 
              markdown-parse.js                      
    ┌───────────┐  ┌──────────┐  ┌──────────────┐  
     stripBroken│→  transform │→    unified      
      Images       Markdown      processor     
     (loading)     (plugins)     (HAST)        
    └───────────┘  └──────────┘  └──────┬───────┘  
                                                   
                                ┌────────▼────────┐│ 
                                  toJsxRuntime   ││ 
                                  components:    ││ 
                                  ┌───────────┐  ││ 
                                   table       ││ 
                                   pre         ││ 
                                   ref         ││ 
                                   v3md-*      ││ 
                                   loading     ││ 
                                  └───────────┘  ││ 
                                └─────────────────┘│ 
  └─────────────────────────────────────────────────┘ 
└─────────────────────────────────────────────────────┘

总结

这次插件化改造踩了五个主要坑:

  1. 不完整语法导致解析错乱 → 正则清理 + loading 占位
  2. ECharts 配置门槛高 → 简单模式自动补全
  3. 流式渲染闪烁 → CSS 排除 + 组件缓存 + Config 去重(三层修复)
  4. 自定义标签被 <p> 包裹 → 块级 div 包裹 + 空行隔离
  5. VNode 树中事件无法冒泡 → provide/inject 跨层级传递

最深刻的教训是:流式渲染场景下,任何"引用不稳定"都会被放大。普通场景中组件重建一次可能无感,但流式场景下每秒更新数十次,组件反复销毁重建就变成了闪烁。核心策略是:能缓存就缓存,能比较就比较,能跳过就跳过

从零到一:用 Vue3 + Kimi 大模型打造「拍照记单词」AI 应用

2026年5月6日 17:52

从零到一:用 Vue3 + Kimi 大模型打造「拍照记单词」AI 应用

本文适合有一定 Vue3 基础、想了解如何将大模型 API 集成到前端项目的开发者。完整项目已开源,文末附链接。

前言

在 AI 时代,"一个人的公司"(OPC)正在成为可能。本文将带你从零搭建一个 拍照记单词 的前端 AI 应用——用户拍一张照片,AI 自动识别图片内容并生成一个英文单词、例句和发音。

这个项目的核心价值在于:它不是一个 Demo,而是一个可以落地的产品原型。你会学到:

  • 如何用 Vue3 Composition API 组织复杂业务逻辑
  • 如何调用多模态大模型(Kimi Vision)解析图片
  • 如何集成 TTS 语音合成
  • 如何设计一个对用户友好的 Prompt

一、项目架构总览

vue3-ts-cameraword/
├── src/
│   ├── App.vue                 # 主页面,核心业务逻辑
│   ├── components/
│   │   └── PictureCard.vue     # 拍照卡片组件
│   ├── lib/
│   │   └── audio.ts            # TTS 语音合成模块
│   └── main.ts                 # 入口文件
├── .env.local                  # 环境变量(API Key 等)
└── vite.config.ts              # Vite 配置

技术栈:Vue3 + TypeScript + Vite + Kimi Vision API + 火山引擎 TTS


二、核心功能实现

2.1 图片上传:FileReader 的妙用

传统文件上传需要后端配合,但多模态大模型可以直接接收 Base64 编码的图片。我们用 FileReader 在前端完成图片转码:

// PictureCard.vue
const updateImageData = async (e: Event): Promise<any> => {
    const file = (e.target as HTMLInputElement).files?.[0];
    if (!file) return;

    return new Promise((resolve, reject) => {
        const reader = new FileReader();
        reader.readAsDataURL(file); // 转为 Base64
        reader.onload = () => {
            const data = reader.result as string;
            imgPreview.value = data;        // 本地预览
            emit('updateImage', data);      // 传给父组件
            resolve(data);
        };
        reader.onerror = (error) => reject(error);
    });
};

关键点:

  • readAsDataURL() 将文件转为 data:image/png;base64,... 格式的字符串
  • 这个字符串可以直接作为 <img>src 实现预览
  • 同时可以直接传给大模型的 image_url 字段

2.2 调用 Kimi Vision:多模态 API 实战

这是整个项目的核心。Kimi 的 moonshot-v1-8k-vision-preview 模型支持图片+文字的混合输入:

// App.vue
const update = async (imageDate: string) => {
    const endpoint = import.meta.env.VITE_KIMI_API_ENDPOINT + '/chat/completions';
    const headers = {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${import.meta.env.VITE_KIMI_API_KEY}`
    };

    word.value = '分析中...';

    const response = await fetch(endpoint, {
        method: 'POST',
        headers,
        body: JSON.stringify({
            model: 'moonshot-v1-8k-vision-preview',
            messages: [{
                role: 'user',
                content: [
                    {
                        type: 'image_url',
                        image_url: { url: imageDate }  // Base64 图片
                    },
                    {
                        type: 'text',
                        text: userPrompt                // 文字指令
                    }
                ]
            }],
            stream: false
        })
    });

    const data = await response.json();
    const replyData = JSON.parse(data.choices[0].message.content);
    // 处理返回数据...
};

这里的 content 是一个数组,可以同时包含图片和文字。这是多模态 API 的标准用法。

2.3 Prompt 设计:决定产品质量的关键

Prompt 是 AI 产品的灵魂。一个好的 Prompt 需要:

  1. 清晰的指令:告诉模型你要什么
  2. 明确的输出格式:JSON 格式便于前端解析
  3. 约束条件:限制词汇难度、输出长度等
const userPrompt = `
  分析图片内容,找出最能描述图片的一个英文单词,尽量选择更简单的A1~A2的词汇。

  返回JSON 数据:
  {
    "image_discription": "图片描述",
    "representative_word": "图片代表的英文单词",
    "example_sentence": "结合英文单词和图片描述,给出一个简单的例句",
    "explaination": "结合图片解释英文单词,段落以Look at ...开头,
                    将段落分句,每一句单独一行,
                    解释的最后给一个日常生活有关的问句",
    "explanation_replys": ["根据explaination给出的回复1",
                          "根据explaination给出的回复2"]
  }
`;

设计要点:

  • A1~A2 级别:控制词汇难度,适合初学者
  • JSON 格式OutputParser 的思想,让返回数据结构化,便于业务处理
  • Look at ... 开头:引导模型用"看图说话"的方式解释,更生动
  • 问句结尾:制造对话感,增强学习互动性

2.4 TTS 语音合成:让单词"说出来"

学英语离不开发音。我们集成火山引擎的 TTS 服务,将例句转为语音:

// lib/audio.ts
export const generateAudio = async (text: string) => {
    const endpoint = '/tts/api/v1/tts';
    const headers = {
        'Content-Type': 'application/json',
        'Authorization': `Bearer;${token}`
    };

    const payload = {
        app: { appid: appId, token, cluster: clusterId },
        user: { uid: 'bearbobo' },
        audio: {
            voice_type: voiceName,    // 音色:en_female_anna_mars_bigtts
            encoding: 'ogg_opus',     // 音频编码格式
            speed_ratio: 1.0,         // 语速
            emotion: 'happy',         // 情绪
        },
        request: {
            reqid: Math.random().toString(36).substring(7),
            text,                     // 要合成的文本
            text_type: 'plain',
            operation: 'query',
        },
    };

    const res = await fetch(endpoint, {
        method: 'POST',
        headers,
        body: JSON.stringify(payload)
    });

    const data = await res.json();
    return createBlobURL(data.data);  // 转为可播放的 URL
};

Base64 转 Blob URL 的工具函数:

function createBlobURL(base64AudioData: string): string {
    const byteArrays: number[] = [];
    const byteCharacters = atob(base64AudioData);  // 解码 Base64

    for (let offset = 0; offset < byteCharacters.length; offset++) {
        byteArrays.push(byteCharacters.charCodeAt(offset));
    }

    const audioBlob = new Blob([new Uint8Array(byteArrays)], {
        type: 'audio/mp3'
    });

    return URL.createObjectURL(audioBlob);  // 生成临时播放 URL
}

播放逻辑很简单:

// PictureCard.vue
const playAudio = () => {
    const audio = new Audio(props.audio);
    audio.play();
};

三、Vite 代理配置:解决跨域问题

前端直接调用第三方 API 会遇到跨域。用 Vite 的 server.proxy 解决:

// vite.config.ts
export default defineConfig({
    plugins: [vue()],
    server: {
        host: '0.0.0.0',           // 允许局域网访问
        proxy: {
            '/tts': {
                target: 'https://openspeech.bytedance.com',
                changeOrigin: true,
                rewrite: path => path.replace(/^\/tts/, ''),
            }
        },
    },
});
  • host: '0.0.0.0':让手机等设备也能访问开发服务器
  • /tts 代理:将 /tts/api/v1/tts 转发到火山引擎的 API

四、无障碍设计:被忽略的细节

这个项目有一个亮点:支持读屏器的无障碍访问

传统的 <input type="file"> 样式很难控制。我们的做法是:

<!-- 隐藏原生 input,用 label 触发 -->
<input type="file" id="selecteImage" class="input"
       accept="image/*" @change="updateImageData">
<label for="selecteImage" class="upload">
    <img :src="imgPreview" alt="camera" class="img"/>
</label>
.input {
    display: none;  /* 隐藏原生控件 */
}
  • for="selecteImage" 关联 id,点击 label 等同于点击 input
  • accept="image/*" 限制只能选择图片
  • 读屏器可以通过 label 的文本识别按钮用途

效果

image.png

image.png

五、项目总结与思考

学到了什么

  1. 多模态 API 的调用方式content 字段是数组,图片用 Base64 编码传入
  2. Prompt 工程:JSON 输出格式、难度约束、引导性描述
  3. 前端音频处理:Base64 → Blob → ObjectURL 的完整链路
  4. Vite 代理:一行配置解决跨域

可以改进的方向

  • 加入流式输出stream: true),让分析过程可视化
  • 增加单词本功能,收藏学过的单词
  • 接入语音识别,支持跟读打分
  • IndexedDB 本地存储学习记录

六、环境配置

创建 .env.local 文件:

VITE_KIMI_API_KEY=sk-xxxxx          # Kimi API Key
VITE_KIMI_API_ENDPOINT=https://api.moonshot.cn/v1

VITE_AUDIO_APP_ID=xxxxx             # 火山引擎 TTS 配置
VITE_AUDIO_ACCESS_TOKEN=xxxxx
VITE_AUDIO_CLUSTER_ID=volcano_tts
VITE_AUDIO_VOICE_NAME=en_female_anna_mars_bigtts

启动项目:

npm install
npm run dev

写在最后

这个项目虽然代码量不大,但覆盖了前端 AI 应用的核心链路:图片输入 → 多模态理解 → 结构化输出 → 语音合成

AI 时代,前端工程师的价值不只是写页面,更是用 AI 能力重新定义产品体验。希望这篇文章能给你一些启发。

项目地址:[project/capture_word /lesson_zp - 码云 - 开源中国] 欢迎 Star 和 PR!

脚手架搭建项目框架(create-vite、vue-cli、create-vue、quasar-cli)

作者 RONIN
2026年5月6日 17:04

脚手架脚手架搭建项目框架

一. create-vite

npm create vite@latest(yarn create vite)安装脚手架命令

二. vue-cli

npm i -g @vue-cli安装脚手架命令

vue create project1创建项目

三. create-vue(vue官方的项目脚手架工具,内置了vite构建工具)项目开发中使用的脚手架

1.技术栈:

Create-vue脚手架 + Vite构建工具 + vue3组合式API (vue3选项式API)+ typescript + vue-router + pinia状态管理 (vuex状态管理)+ axios网络库 + vant3 UI组件库(element-plus UI组件库) + eslint + pretter + sass

2.脚手架搭建项目框架步骤:

1) npm init vue@latest 安装脚手架命令。

根据预设生成相应的配置文件(选择ts、vue-router、pinia、eslint、pretter)。

image.png

2) pinia配置:

npm i pinia-plugin-persist -S 安装pinia持久化存储插件。

创建stores文件夹→index.ts(创建pinia根存储,集成插件)

import { createPinia } from 'pinia'
import piniaPluginPersist from 'pinia-plugin-persist'//引入pinia持久化存储插件

const storeRoot = createPinia()
storeRoot.use(piniaPluginPersist)//集成插件
export default storeRoot

main.js入口文件(集成pinia)

import { createApp } from "vue";
import router from "./router";
import store from "./store";
import App from "./App.vue";
import 'normalize.css' // 重置样式

const app = createApp(App)
app.use(router);
app.use(store);
app.mount("#app");

stores文件夹→user.ts(定义store存储对象,持久化存储增加persist选项)

import {defineStore} from 'pinia'
/**
 * 定义名为useUserStore的存储对象
 *  defineStore方法
 *   第一个参数: 模块名称是唯一的
 *   第二个参数: 选项对象  state, actions, getters
 *                        data    methods   computed
 */
export const useUserStore = defineStore('user',{
    state(){
        return {
            account:null // 账户数据 {name,nick,password}  
        }
    },
    actions:{
        // 具体业务逻辑,可以是同步或异步操作
        saveAccount(account){
            this.account = account
        }
    },
    getters:{
        //getters中定义的方法名/计算属性名不能与state相同
        // userAccount:state => {
        //     return state.account
        // }//定义方式1
        userAccount(){
            return this.account
        }//定义方式2
    },
    persist: {//持久化存储
        enabledtrue,
        strategies: [
            {
                key: user,
                storagelocalStorage,
                paths: ['account'],
            },
        ],
    },
})

3)Sass、axios网络库、UI组件库需手动安装集成。状态管理vuex也需要手动安装集成。

npm i normalize.css -S 安装样式重置库(兼容浏览器)。main.ts中引入import'normalize.css'
npm i sass -d 安装sass(css预处理器,开发环境用)。
npm install axios -s 安装网络库axios(前后端数据交互)。

创建utils文件夹→request.ts中配置(创建axios实例,封装请求/响应拦截器)

import axios from 'axios'
import { Toast } from 'vant';
// 服务根地址
// export const baseURL = 'http://10.7.163.165:8089'  // 开发环境
/**
 * 创建axios实例
 *   封装baseURL
 */
const axiosInstance = axios.create({
    baseURL, // 服务根地址
    timeout: 3000, // 超时时间
})
/**
 * 请求拦截器
 */
axiosInstance.interceptors.request.use(
    config => {
        const token = localStorage.getItem('TOKEN')
        if(token){
            config.headers['Authorization'] = token
        }
        return config
    },
    error => {
        return Promise.reject(error)
    }
)
/**
 * 响应拦截器
 */
axiosInstance.interceptors.response.use(
    response => {
        return response.data
    },
    error => {
        const { response } = error
        if (response) {
            const status = response.status
            switch (status) {
                case 404:
                    Toast('资源不存在 404')
                    break
                case 401:
                    Toast('Unauthorized 身份验证凭证缺失!')
                    break
                case 403:
                    Toast('403 Forbidden - 拒绝访问!')
                    break
                case 500:
                    Toast('服务器出错')
                    break
                default:
                    Toast('出现异想不到的错误!')
                    break
            }
        }else {
            // 说明服务器连结果都没有返回,可能的原因有两种:
            /**
             * 1. 服务器崩掉了
             * 2. 前端客户端断网状态
             */
            if (!window.navigator.onLine) {
                // 判断为断网,可以跳转到断网页面
                Toast('网络不可用,请检查您的网络连接!')
                return
            } else {
                Toast('连接服务端出错!' + error?.message)
                return Promise.reject(error)
            }
        }
        return Promise.reject(error)
    }
)
export default axiosInstance
vant组件库安装与配置
  • npm i vant@latest-v3 安装vant组件库
  • npm i unplugin-vue-components -D 安装vant按需引入插件。vite.config.ts中引入集成
  • npm i postcss-pxtorem -D安装移动端适配插件,将px单位转化为rem单位。vite.config.ts中引入集成
  • npm i amfe-flexible -D安装移动端适配插件,适配不同屏幕尺寸。main.ts中引入

vite.config.ts

import { fileURLToPath, URLfrom 'node:url'

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

import Components from 'unplugin-vue-components/vite'//引入按需引入插件
import { VantResolverfrom 'unplugin-vue-components/resolvers'//引入按需引入插件

import postCssPxToRem from 'postcss-pxtorem'//引入移动端适配插件

import { viteMockServe } from 'vite-plugin-mock'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [VantResolver()],//集成按需引入插件
    }),
    viteMockServe({//集成mock模拟接口数据插件
      // 更多配置见最下方
      supportTstrue,
      loggerfalse,
      mockPath'./mock/', // 文件位置
    }),
  ],
  resolve: {
    alias: {
      '@'fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  css:{
    postcss:{
      plugins:[
        postCssPxToRem({//自适应,px转rem
          rootValue:75,//换算的基数(设计图750的根字体为75)
          propList:['*']//需要转换的属性,*代表全部
        })
      ]
    }
  },
  server:{//代理服务器
    proxy: {
      '/api': {
        target'http://124.71.63.13:8088/',
        changeOrigintrue,
        // rewrite: path => path.replace(/^\/api/, '')
      }
    }
  },
})

main.ts

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import store from './stores'
import 'normalize.css' // 重置样式

// 导入vant函数组件样式
import 'vant/es/toast/style'
import 'vant/es/dialog/style'
import 'vant/es/notify/style'
import 'vant/es/image-preview/style'

//引入amfe-flexible屏幕适配插件
import 'amfe-flexible'

const app = createApp(App)
app.use(store)
app.use(router)

app.mount('#app')
elementplus组件库安装与配置
  • npm install element-plus --save安装elementplus组件库
  • npm install -d unplugin-vue-components unplugin-auto-import安装两个插件自动按需引入

vite.config.js集成插件

import { fileURLToPath, URL } from 'node:url'

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

import AutoImport from 'unplugin-auto-import/vite'//引入插件
import Components from 'unplugin-vue-components/vite'//引入插件
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'//引入插件

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vue(),
    AutoImport({//集成插件
        resolvers: [ElementPlusResolver()],
    }),
    Components({//集成插件
        resolvers: [ElementPlusResolver()],
    }),
  ],
  resolve: {
    alias: {
      '@'fileURLToPath(new URL('./src', import.meta.url))
    }
  },
})

main.js引入elementplus样式,否则可能出现使用组件没效果。

import { createApp } from "vue";
import router from "./router";
import store from "./store";
import 'element-plus/dist/index.css';//引入elementplus样式
import App from "./App.vue";

import ElementPlus from 'element-plus';//完整引入elementplus,文件大小会很大。可以考虑按需引入

const app = createApp(App);
app.use(router);
app.use(store);

app.use(ElementPlus);//完整引入elementplus,文件大小会很大。可以考虑按需引入
app.mount("#app");
状态管理vuex安装与配置
  • npm install vuex@next(4.0.2) --save安装vuex插件
  • npm i vuex-persistedstate -s安装vuex持久化存储插件

main.js引入集成到vue

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import store  from './store'

const app = createApp(App)
app.use(router)
app.use(store)
app.mount('#app')

创建story文件夹→index.js文件集成持久化存储插件

import { createStore } from 'vuex'
import createPersistedState from 'vuex-persistedstate'

const store = createStore({
    // 集成持久化存储插件
    plugins:[createPersistedState({
        storage:sessionStorage,
        key:'storekey'
    })]
    state: {//状态数据
        count0
    },
    mutations: {//操作state状态。第一个参数:state对象,第二个参数:外部传入参数
        PLUS(state) {//方法
            // state.count = num
            state.count++
        },
    },
    /**
     * 定义操作mutations方法的方法
     * 供外部组件调用
     *   $store.dispatch('')
     *    1. 单向数流操作方式,保存状态数据以预期方式改变
     *    2. actions 异步操作
     *       mutations 同步操作
     */
    actions: {//操作mutations中的方法
        // plus(context) {//方法
        //     context.commit('PLUS')
        // }
        plus({ commit }) {//解构
            commit('PLUS')
        },
        chs({ commit },num) {//传参
            commit('CHS',num)
        }
    },
    getters: {//获取值,类似计算属性
        num(state) => { return state.count }
        // num: state => state.count
    }
})
export default store

3.解决引入vue组件ts报错(因为ts不识别.vue文件,需在env.d.ts中声明)

env.d.ts

// <reference types="vite/client" />
declare module '*.vue' {
    import { DefineComponent } from 'vue'
    const componentDefineComponent<{}, {}, any>
    export default component
}

4.目录结构介绍

image.png

  • npm install(npm i)下载依赖
  • npm run dev运行

5.打包

  • 将vue文件编译成浏览器能识别的js/html/css文件、ts编译成js文件、scss编译成css文件,压缩处理。
  • 编译后的文件存放在dist目录下(与src同级),都是html/css/js文件,将其部署到服务器上用户就可以用了。

接口环境配置: 开发环境(测试数据)/生产环境(用户使用的数据)

创建utils文件夹→request.ts中配置(创建axios实例,封装请求/响应拦截器,配置接口环境)

解决跨域问题走代理服务器:baseUrl地址为当前客户端地址,vite.config.ts配置代理服务器,代理服务器地址为目标地址(一般指测试地址/线上服务器地址)。

import axios from 'axios'
import { Toastfrom 'vant'

// 服务根地址
// export const baseURL = 'http://10.7.163.165:8089'  // 开发环境

// 生产环境 如果服务端没做跨域处理,使用代理服务器
// 走代理服务器,baseURL 地址配置为与当前客户端地址相同
export let baseURL = 'http://10.7.163.165:8089'  // 开发环境
/**
 * process.env.NODE_ENV
 *    production 生产环境
 *        npm run build
 *    development  开发环境
 *        npm run dev
 */
switch (process.env.NODE_ENV) {
    case 'production':
        baseURL = 'http://124.71.63.13'  // 生产环境
        break
    case 'development':
        baseURL = 'http://10.7.163.165:8089' // 开发环境
        break
}
/**
 * 创建axios实例
 *   封装baseURL
 */
const axiosInstance = axios.create({
    baseURL, // 服务根地址
    timeout3000, // 超时时间
})
/**
 * 请求拦截器
 */
axiosInstance.interceptors.request.use(
    config => {
        const token = localStorage.getItem('TOKEN')
        if (token) {
            config.headers['Authorization'] = token
        }
        return config
    },
    error => {
        return Promise.reject(error)
    }
)
/**
 * 响应拦截器
 */
axiosInstance.interceptors.response.use(
    response => {
        return response.data
    },
    error => {
        const { response } = error
        if (response) {
            const status = response.status
            switch (status) {
                case 404:
                    Toast('资源不存在 404')
                    break
                case 401:
                    Toast('Unauthorized 身份验证凭证缺失!')
                    break
                case 403:
                    Toast('403 Forbidden - 拒绝访问!')
                    break
                case 500:
                    Toast('服务器出错')
                    break
                default:
                    Toast('出现异想不到的错误!')
                    break
            }
        } else {
            // 说明服务器连结果都没有返回,可能的原因有两种:
            /**
             * 1. 服务器崩掉了
             * 2. 前端客户端断网状态
             */
            if (!window.navigator.onLine) {
                // 判断为断网,可以跳转到断网页面
                Toast('网络不可用,请检查您的网络连接!')
                return
            } else {
                Toast('连接服务端出错!' + error?.message)
                return Promise.reject(error)
            }
        }
        return Promise.reject(error)
    }
)
export default axiosInstance

tsconfig.json(解决request.ts中环境配置时process报错)

{
    "extends": "@vue/tsconfig/tsconfig.web.json",
    "include": ["env.d.ts", "src/**/*", "src/**/*.vue"],
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "@/*": ["./src/*"]
        },
        // 解决process.env.NODE_ENV报错,
        // 1.安装npm i @types/node -S
        // 配置"types": ["node"]
        "types": ["node"]
    },
    "references": [
        {
            "path": "./tsconfig.config.json"
        }
    ]
}

vite.config.ts配置代理服务器

import { fileURLToPath, URLfrom 'node:url'

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

import Components from 'unplugin-vue-components/vite'//引入按需引入插件
import { VantResolverfrom 'unplugin-vue-components/resolvers'//引入按需引入插件

import postCssPxToRem from 'postcss-pxtorem'//引入移动端适配插件

import { viteMockServe } from 'vite-plugin-mock'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [VantResolver()],//集成按需引入插件
    }),
    viteMockServe({//集成mock模拟接口数据插件
      // 更多配置见最下方
      supportTstrue,
      loggerfalse,
      mockPath'./mock/', // 文件位置
    }),
  ],

  resolve: {
    alias: {
      '@'fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  css:{
    postcss:{
      plugins:[
        postCssPxToRem({//自适应,px转rem
          rootValue:75,//换算的基数(设计图750的根字体为75)
          propList:['*']//需要转换的属性,*代表全部
        })
      ]
    }
  },
  server:{//代理服务器
    proxy: {
      '/api': {
        target'http://124.71.63.13:8088/',//目标地址
        changeOrigintrue,//是否跨域
//这里理解成用'/api'代替target里面的地址,比如我要调用'http://40.00.100.100:3002/user/add',直接写'/api/user/add'即可
        rewrite(path) => path.replace(/^**\/** api/, ''),
      }
    }
  },
})

npm run build打包

四. quasar-cli项目开发中使用的脚手架

关于quasar要求:

  • Node 12+用于Quasar CLI与Webpack,Node 14+用于Quasar CLI与Vite。
  • Yarn v1(强烈推荐),PNPM,或NPM。

npm i -g @quasar/cli 安装脚手架命令

npm init quasar 初始化quasar根据预设生成相应的配置文件

image.png

此时回车,会生成项目文件和目录

image.png

提示安装项目依赖,选择yes回车

image.png

quasar dev(npm run dev)运行

Tiptap 简单编辑器模版

作者 时光足迹
2026年5月6日 16:38

上一篇介绍了Tiptap 编辑器的基础使用,本篇主要介绍 Tiptap 的简单编辑器模版Simple template,以及如何改造模版。

Tiptap 是一个基于 ProseMirror 的 Headless 富文本编辑器框架,它采用模块化设计,通过扩展(Extensions)机制来实现各种功能。每个扩展可以定义自己的节点(Nodes)、标记(Marks)、命令(Commands)等。

  1. Editor 实例:Tiptap 的核心,管理整个编辑器的状态和行为
  2. Extensions 扩展:功能模块的基本单位,可以是节点或标记
  3. Nodes 节点:文档结构的基本单位,如段落、标题、列表项等
  4. Marks 标记:应用于文本的样式,如粗体、斜体、链接等
  5. Commands 命令:用于修改编辑器状态的操作方法

simple-editor 模版

Tiptap 的 StarterKit 仅提供基础的富文本功能逻辑,不会自带默认样式(如标题字体大小、段落首行缩进等),需要手动添加 CSS 样式来美化内容。

可以安装一个简单编辑器模版Simple template,其包括常用的开源扩展UI 组件

npx @tiptap/cli@latest add simple-editor
  1. SimpleEditor:主编辑器组件,整合所有功能
    • tiptap-templates 文件夹
  2. Toolbar:工具栏组件,提供各种编辑操作按钮
    • tiptap-ui 文件夹
  3. Extensions:预配置的扩展集合,包括基础文本格式、列表、链接等
    • tiptap-ui-primitive 文件夹
  4. Styles:配套的样式文件,提供美观的默认外观

tiptap-2-1.png

tiptap-2-2.png

操作完成后,会在项目中加入一系列的文件,包括组件、配置文件、样式文件等等:

tiptap-2-3.png

global.css全局样式文件中添加模版的样式文件:

/* tiptap */
@import "./styles/_variables.scss";
@import "./styles/_keyframe-animations.scss";

配置完成后,页面样式乱了呀,影响其他内容样式了,如下图所示:

tiptap-2-4.png

排查后,发现是暗黑模式默认宽高影响的,需要调整一下:

import { SimpleEditor } from "@/components/tiptap-templates/simple/simple-editor";
import { styled } from "styled-components";

export default function Page() {
  return (
    <Container>
      <SimpleEditor />
    </Container>
  );
}

const Container = styled.div`
  width: 500px;
  margin-top: 30px;
  border: 1px solid #eee;
  .simple-editor-wrapper {
    width: 100%;
    height: 300px;
  }
`;

tiptap-2-5.png

simple-editor 改造

主题

默认主题是暗黑模式,改为明亮模式:

// 修改theme-toggle.tsx文件

// 注释掉下列代码:
React.useEffect(() => {
  const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
  const handleChange = () => {
    // setIsDarkMode(mediaQuery.matches)
  };
  mediaQuery.addEventListener("change", handleChange);
  return () => mediaQuery.removeEventListener("change", handleChange);
}, []);

// React.useEffect(() => {
//   const initialDarkMode =
//     !!document.querySelector('meta[name="color-scheme"][content="dark"]') ||
//     window.matchMedia("(prefers-color-scheme: dark)").matches;
//   setIsDarkMode(initialDarkMode);
// }, []);

然后在工具条中去掉该功能即可

工具条样式

默认工具条是横向滚动的,改为自适应

/* 修改simple-editor.css文件 */
.simple-editor-wrapper {
  width: 100%;
  height: 300px;
  border: 1px solid #eee;
  .tiptap-toolbar {
    flex-wrap: wrap;
    /* 或者直接隐藏首个 <Spacer /> 组件 */
    > div:first-of-type {
      flex: 0 !important;
    }
  }
}

调整后效果:

tiptap-2-6.png

工具条汉化

默认工具条是英文的,改为中文:

  1. 操作组件 undo-redo-button
<UndoRedoButton action="undo" />
<UndoRedoButton action="redo" />
// 修改tiptap-ui/undo-redo-button/use-undo-redo.ts文件
export const historyActionLabels: Record<UndoRedoAction, string> = {
  undo: "撤销",
  redo: "重做",
}
  1. 标题组件 heading-dropdown-menu

tiptap-2-7.png

  1. 列表组件 list-dropdown-menu

tiptap-2-8.png

  1. 引用块 blockquote-button

tiptap-2-9.png

  1. 代码块 code-block-button
  2. 文本样式 mark-button
    • 粗体 bold
    • 斜体 italic
    • 删除线 strike
    • 代码 code
    • 下划线 underline
    • 上标 superscript
    • 下标 subscript

tiptap-2-10.png

  1. 高亮组件 color-highlight-button

tiptap-2-11.png

  1. 链接组件 link-popover

tiptap-2-12.png

  1. 对齐组件 align-align-button

tiptap-2-13.png

  1. 图片组件 image-upload-button

改造前: tiptap-2-14.png

改造中: tiptap-2-15.png

改造后:

tiptap-2-16.png

Tiptap编辑器

作者 时光足迹
2026年5月6日 16:37

主要介绍了编辑器的基础使用,包括依赖安装、基础配置,以及 StarterKit 基础扩展、内嵌图片 Image、编辑状态、拖拽手柄、文本样式扩展包等等

基础介绍

ProseMirror:是一款用于在网页端构建富文本编辑器的工具包,核心目标是弥合 “结构化内容编辑”(如 Markdown、XML)与 “经典所见即所得(WYSIWYG)编辑” 之间的差距 —— 既让用户能以直观的 WYSIWYG 方式编辑,又能生成干净、语义明确且符合自定义结构的文档,适用于从简单文本编辑到复杂协作系统的各类场景。

Tiptap 是基于 ProseMirror(经行业验证的网页富文本编辑器工具库)构建的无头(Headless)富文本编辑器框架,核心能力是帮助开发者打造 “完全贴合自身及用户需求” 的定制化编辑器。

其底层依赖三大核心机制实现灵活且强大的编辑功能 API:

  1. 事件(Events):监听编辑器状态变化(如内容修改、光标移动);
  2. 命令(Commands):触发编辑操作(如加粗文本、插入列表);
  3. 扩展(Extensions):扩展编辑器功能(如添加表格、AI 辅助创作)。

核心价值是 “按需构建编辑器”,既提供基础开源编辑功能,也通过云服务和扩展满足复杂场景需求,核心能力分为五大模块,覆盖从基础编辑到高级协作的全场景:Editor(编辑器)、Collaboration(协作)、Content AI(内容 AI)、Comments(评论)、Documents(文档处理)

安装

  1. @tiptap/react:Tiptap 的 React 绑定包,包含核心功能(如 useEditor 钩子、EditorContent 组件)
  2. @tiptap/pm:Tiptap 依赖的 ProseMirror 底层库,是编辑器运行的核心支撑
  3. @tiptap/starter-kit:基础扩展集合,包含段落、标题、加粗、斜体等常用功能,可快速启动项目
pnpm install @tiptap/react @tiptap/pm @tiptap/starter-kit

基础使用

参照官方文档,完成了一个初始 Demo

import { Image } from "antd";
import { styled } from "styled-components";

import { EditorContent, EditorContext, useEditor } from "@tiptap/react";
import { BubbleMenu, FloatingMenu } from "@tiptap/react/menus"; // 导入菜单组件
import StarterKit from "@tiptap/starter-kit"; // 导入基础扩展集合
import { useMemo } from "react";
export default function Page() {
  // 1. 使用 useEditor 钩子初始化编辑器
  const editor = useEditor({
    // 配置扩展(此处使用基础扩展集合)
    extensions: [StarterKit],
    // 编辑器初始内容(HTML 格式)
    content: `
    <h1>第一章原始阶段和商周时期的江南</h1>
    <p>地方特点的青铜器。第一类典型的商代青铜器特别是那些有铭文的铜器,很可能是从中原地区传过来的;第三类具有地方特点的青铜器应是在本地铸造的;第二类青铜器有的可能铸自本地,也有的可能来自中原。</p>
    <p>这些商代铜器除了少数出自遗址和墓葬外,绝大多数出自窖藏,且多出自山顶、山腰、河岸、湖边,很有可能是当时人们祭祀山川、湖泊、日月星辰的遗物。①</p>
    <p>宁乡、湘潭等地出土的商代铜器中,有“己”分裆鼎、“癸母”提梁卤和“戈”卤等少量有铭文的铜器②;在湘潭县青山桥一铜器窖穴中也出土有商末周初的“母”爵,“母”解和“戈”解③。“母”和“戈”本是中原商代铜器中两个常见的族徽,现在江南地区也有铸这两个族徽的铜器出土,说明在商代晚期或末期,他们中的一支曾南迁到了湘中地区。</p>
    <p>湖南境内出土的西周铜器,仍以湘水流域为多,如湘潭、湘乡、浏阳、株洲、望城、衡阳、耒阳、资兴等地都有出土。器形以乐器饶、甬钟和镈为主④,还有湘潭青山桥窖藏出土的爵、解、鼎、凹字形锄等⑤。桃江连河冲出有马簋。⑥</p>
    <p>西周时期的铜饶是紧接着商代晚期的大饶发展而来。商末周初的铜铙为乳钉铙,钲的每面有18个乳钉。这些乳钉的出现可能有两个来源,其乳钉的排列和数量应来源于商代云纹铙上云纹的尾部的上翘,这有江西新干商代大墓中出土的云纹铜饶为证。乳钉的形状应是对于象纹大饶钲边乳钉的承袭。乳钉铙上的乳钉不断升高,在西周初演变为尖锥状和</p>
    `,
  });

  // 缓存 Context 值,避免不必要的重渲染
  const providerValue = useMemo(() => ({ editor }), [editor]);

  return (
    <Container>
      <div className="block-wrap">
        <div className="left">
          <Image src="/pdf/1-1.jpg" />
        </div>
        <div className="right">
          {/* 提供 EditorContext,让子组件可访问编辑器实例 */}
          <EditorContext.Provider value={providerValue}>
            {/* 2. 编辑器内容区域:渲染编辑界面 */}
            <EditorContent editor={editor} />

            {/* 3. 浮动菜单:空行光标定位时显示 */}
            <FloatingMenu editor={editor}>这是浮动菜单</FloatingMenu>

            {/* 4. 气泡菜单:选中文本时显示 */}
            <BubbleMenu editor={editor}>这是气泡菜单</BubbleMenu>
          </EditorContext.Provider>
        </div>
      </div>
    </Container>
  );
}

const Container = styled.div`
  .block-wrap {
    display: flex;
    width: 80%;
    margin: 0 auto;
    > div {
      width: 50%;
    }
  }
`;

显示效果如图 tiptap-1-1 所示:

tiptap-1-1.png

StarterKit 基础扩展集合

StarterKit 默认包含的核心扩展:文档(Document)、段落(Paragraph)、文本(Text)、标题(Heading)、加粗(Bold)、斜体(Italic)、删除线(Strike)、代码(Code)、无序列表(BulletList)、有序列表(OrderedList)等等。

具体入门套件,可以查看官网:StarterKit

在 StarterKit.configure() 中传入配置对象,通过 “扩展名称” 精准定位需修改的模块

import Strike from "@tiptap/extension-strike"; // 导入删除线扩展

new Editor({
  extensions: [
    StarterKit.configure({
      heading: { levels: [1, 2, 3] }, // 调整标题层级
    }),
  ],
});

内嵌图片 Image

具体可查看官方文档:image

# 安装扩展
pnpm install @tiptap/extension-image

使用示例如下所示:

import { Image as TiptapImage } from "@tiptap/extension-image"; // 图片扩展

const editor = useEditor({
  // 配置扩展(此处使用基础扩展集合)
  extensions: [
    StarterKit.configure({
      heading: { levels: [1, 2, 3] }, // 调整标题层级
    }),
    TiptapImage.configure({
      inline: true, // 允许行内
      allowBase64: true, // 允许 base64 格式图片
      HTMLAttributes: {
        class: "tiptap-img-inline", // 自定义样式名
      },
    }),
  ],
  content: `
    <p>宁乡、湘潭等地出土的商代铜器中,有“己<img src="/pdf/1-1-1.png" />”分裆鼎、“癸<img src="https://placehold.co/40x40/6A00F5/white" />”提梁卤和“戈”卤等少量有铭文的铜器②;在湘潭县青山桥一铜器窖穴中也出土有商末周初的“<img src="/pdf/1-1-2.png" />”爵,“<img src="/pdf/1-1-2.png" />”解和“戈”解③。“<img src="/pdf/1-1-2.png" />”和“戈”本是中原商代铜器中两个常见的族徽,现在江南地区也有铸这两个族徽的铜器出土,说明在商代晚期或末期,他们中的一支曾南迁到了湘中地区。</p>
    `,
});

配置了inline: true,设置为行内图片,但是没起作用呀。

排查发现,有个默认样式配置,将图片设置为块元素了,那只能自定义样式处理了呗。

tiptap-1-2.png

只能添加自定义样式HTMLAttributes: {class:"tiptap-img-inline"}

.tiptap-img-inline {
  display: inline; /* 强制行内显示 */
}

tiptap-1-3.png

当然,如果不想要行内显示的话,就不将 img 放到 p 标签内,而是直接放在 p 标签外,这样图片就会块级元素了。

代码展示:

tiptap-1-4.png

渲染效果展示:

tiptap-1-5.png

编辑状态控制

// 控制编辑器可编辑状态
const [isEditable, setIsEditable] = useState(false);
useEffect(() => {
  if (editor) {
    editor.setEditable(isEditable);
  }
}, [isEditable, editor]);

// 开关渲染
<Switch
  checkedChildren="开启"
  unCheckedChildren="关闭"
  checked={isEditable}
  onChange={setIsEditable}
/>;

tiptap-1-6.png

拖拽手柄控制

官方文档:drag-handle-react

文本样式集合包

文本样式集合包含:TextStyle、BackgroundColor(背景色)、Color(颜色)、FontFamily(字体)、FontSize(字号)、LineHeight(行高)

官方文档:text-style-kit

# 安装插件
pnpm install @tiptap/extension-text-style
import { TextStyleKit } from "@tiptap/extension-text-style"; // 文本样式扩展

const editor = useEditor({
  extensions: [
    StarterKit,
    // 添加文本样式功能集合,包含字体、颜色、背景色、行高、字体大小等样式控制
    TextStyleKit,
    TiptapImage,
  ],
});

ThreeJS之GUI控制器

作者 时光足迹
2026年5月6日 16:36

上篇主要介绍了 three.js 的基础使用及配置,例如场景、相机、渲染器、轨道控制器、灯光等等;本篇主要介绍 GUI 控制器,方便调试模型属性,例如按钮事件、位置、颜色、线框模式等等

初始化模型

let scene; // 场景
let camera; // 相机
let renderer; // 渲染器
let controls; // 轨道控制器
const width = 300;
const height = 300;
let glbScene; // 3d加载模型
let cube; // 立方体

// 1. 初始化场景
const initScene = () => {
  scene = new THREE.Scene();
  // 设置背景色
  scene.background = new THREE.Color(0xffffff);
};

// 2. 初始化相机
const initCamera = () => {
  camera = new THREE.PerspectiveCamera(
    75, // 视角
    width / height, // 宽高比
    0.1, // 近平面
    2000 // 远平面
  );
  camera.position.z = 2; // 设置相机在 z 轴上的位置
  camera.position.y = 0.2;
  camera.lookAt(0, 0, 0); // 看向原点
};

// 3. 创建渲染器
const initRenderer = (id) => {
  renderer = new THREE.WebGLRenderer({ antialias: true });
  renderer.setSize(width, height); // 设置渲染器尺寸
  // renderer.setClearColor(0xffffff, 0); // 设置背景颜色 默认黑色

  // 获取渲染元素
  const container = document.getElementById(id) as HTMLElement;
  container.appendChild(renderer.domElement);
};

// 4. 添加轨道控制器(调整相机位置,即视角位置)
const initControls = () => {
  controls = new OrbitControls(camera, renderer.domElement);
  controls.enableDamping = true; // 允许阻尼效果,使动画更平滑
  controls.dampingFactor = 0.05; // 阻尼系数
  controls.rotateSpeed = 0.1; // 旋转速度
  // controls.autoRotate = true; // 自动旋转
  // controls.autoRotateSpeed = 1; // 自动旋转速度
};

// 5. 动画刷新
const animate = () => {
  requestAnimationFrame(animate);
  controls.update(); // 更新控制器状态
  renderer.render(scene, camera); // 重新渲染
};

// (1)添加3d元素(立方体)
const initBox = () => {
  // import buyImg from "../../../assets/img/buy-gift.png";
  // 环境贴图
  new THREE.TextureLoader().load(buyImg, (texture) => {
    // 创建立方体(width,height,depth)
    const box = new THREE.BoxGeometry(1, 1, 1);
    // 创建材质
    const material = new THREE.MeshBasicMaterial({
      color: 0x00ff00,
      map: texture,
      side: THREE.BackSide,
    });
    // 创建网格(将物体和材质链接起来)
    cube = new THREE.Mesh(box, material);
    cube.position.set(1, 1, 0);
    // 添加到场景
    scene.add(cube);
  });
};

// (2)加载3D模型
const initGlb = (url) => {
  // 创建GLTF实例
  const loader = new GLTFLoader();
  // 加载模型
  loader.load(url, (glb) => {
    // console.log("glb.scene", glb.scene);
    glbScene = glb.scene;
    glb.scene.position.y = -0.7;
    scene.add(glb.scene);
  });
};

// (3)添加灯光
const initLight = () => {
  // 添加环境光
  const ambientLight = new THREE.AmbientLight(0xffffff, 4); // 柔和的白光
  scene.add(ambientLight);
};

// (4)添加其他
const initOther = () => {
  // 添加网格地面
  const gridHelper = new THREE.GridHelper(10, 10);
  scene.add(gridHelper);

  // 添加坐标轴
  const axesHelper = new THREE.AxesHelper(5);
  scene.add(axesHelper);
};

initScene();
initCamera();
initRenderer(item.id);
initControls();
animate();

initBox();
initGlb(item.nftFileUrl);
initLight();
initOther();

添加灯光(initLight)和其他(initOther)前的效果:

3d-4.png

添加灯光(initLight)和其他(initOther)后的效果:

3d-5.png

添加 GUI 控制

// 创建立方体
const initBox = () => {
  // 创建立方体(width,height,depth)
  const box = new THREE.BoxGeometry(1, 1, 1);
  // 创建材质
  const material = new THREE.MeshBasicMaterial({
    color: 0x00ff00,
    side: THREE.BackSide,
  });
  material.wireframe = true; // 设置为线框模式
  // 创建网格(将物体和材质链接起来)
  cube = new THREE.Mesh(box, material);
  cube.position.set(1, 1, 0);
  // 添加到场景
  scene.add(cube);
};

// 加载glb实例
const initGlb = (url) => {
  // 创建GLTF实例
  const loader = new GLTFLoader();
  // 加载模型
  loader.load(url, (glb) => {
    console.log("glb.scene", glb.scene);
    glbScene = glb.scene;
    glb.scene.position.y = -0.7;
    scene.add(glb.scene);

    // 添加GUI配置
    initGui();
  });
};

// 添加GUI配置
// import { GUI } from "three/examples/jsm/libs/lil-gui.module.min.js";
const initGui = () => {
  // 创建GUI
  const gui = new GUI();

  // 添加按钮(.name重命名为中文)
  const eventObj = {
    fullScreen: () => {
      // 全屏
      document.body.requestFullscreen();
    },
    exitScreen: () => {
      // 退出全屏
      document.exitFullscreen();
    },
  };
  gui.add(eventObj, "fullScreen").name("全屏");
  gui.add(eventObj, "exitScreen").name("退出全屏");

  // 控制模型位置
  console.log(glbScene);
  let folder = gui.addFolder("模型位置"); // 添加分组
  folder
    .add(glbScene.position, "x", -5, 5) // 参数和下面同等效果
    .onChange((val) => console.log("x", val)); // 变动时触发
  folder
    .add(glbScene.position, "y")
    .min(-5) // 最小值
    .max(5) // 最大值
    .step(1) // 部进
    .name("y轴") // 重命名
    .onFinishChange((val) => console.log("y", val)); // 变动结束时触发

  // 线框模式控制
  console.log("cube", cube);
  // 要有配置:material.wireframe = true,boolean值处理
  gui.add(cube.material, "wireframe").name("线框模式");

  // 颜色调整
  const colorParams = { cubeColor: "#ff0000" };
  gui
    .addColor(colorParams, "cubeColor")
    .name("立方体颜色")
    .onChange((val) => cube.material.color.set(val));
};

3d-6.png

电子书阅读器之笔记高亮(跨段处理)

作者 时光足迹
2026年5月6日 16:32

文本高亮

之前介绍了电子书阅读器之笔记高亮,主要展示处理逻辑。当时,只能处理同一段内的文字,不能跨段处理。现在就介绍如何处理跨段高亮。

Selection

window.getSelection()返回一个 Selection 对象,表示用户选择的文本范围或光标的当前位置。它代表页面中的文本选区,可能横跨多个元素

  • selection.toString():获取选中文本
const selection = window.getSelection();
console.log("[selection]", selection);
const selectedText = selection.toString().trim();
console.log("[选中文本]", selectedText);

highlight-1.png

Range

Range表示一个包含节点与文本节点的一部分的文档片段

  • getRangeAt:获取选区包含的指定区域(Range)的引用
const range = selection.getRangeAt(0);
console.log("[选中Range]", range);

const {
  startContainer, // 起始节点
  startOffset, // 起始节点偏移量
  endContainer, // 终止节点
  endOffset, // 终止节点偏移量
} = range;
console.log("[起始节点]", startContainer, "偏移量", startOffset);
console.log("[终止节点]", endContainer, "偏移量", endOffset);

highlight-2.png

getBoundingClientRect

const rectList = range.getClientRects();
console.log("[边界对象集]", rectList);
const rect = range.getBoundingClientRect();
console.log("[边界矩形]", rect);

highlight-3.png

highlight-4.png

选中位置定位

  1. 使用 rect 的位置,显示效果如下:
const position = { top: rect.top, left: rect.left };
console.log("[选中位置]", position);

highlight-5.png

  1. 使用 rectList 的位置,显示效果如下:
const position = { top: rectList[0].top, left: rectList[0].left };
console.log("[选中位置]", position);

highlight-6.png

我选择是这种方式,展示在选中文本第一个元素的位置。

  1. 滚动条影响

如果内容区域有滚动条,那么选中位置的定位坐标需要加上滚动条的值,即 top 需要加上滚动条的偏移量。

const position = {
  top: rectList[0].top + contentRef.current.scrollTop,
  left: rectList[0].left,
};

文本高亮

监听鼠标抬起(onMouseUp)事件,获取选中的文本,并高亮。

export default function Page() {
  // 处理鼠标抬起事件
  const handleMouseUp = () => {
    // 获取选中文本信息,包括位置信息
    const selectedRange = getSelectionPosition();
    if (selectedRange) {
      console.log(selectedRange);
      highlightText(selectedRange);
    }
  };

  return (
    <div ref={contentRef} onMouseUp={handleMouseUp} onClick={handleClick}>
      {/* 数字教材预览区 */}
      <MPreview list={list} />
      {/* 选中文本操作弹框 */}
      <PopupMenu ref={popupRef} />
      {/* 笔记编辑弹框 */}
      <PopupModify ref={modifyRef} />
    </div>
  );
}

文本节点

// 获取所有文本节点(带位置信息)
const getAllNodes = (contentRef: HTMLDivElement) => {
  if (!contentRef) return [];

  // 获取所有文本节点
  const textNodes: Node[] = [];
  const walker = document.createTreeWalker(contentRef, NodeFilter.SHOW_TEXT, {
    acceptNode: (node) =>
      node.textContent?.trim()
        ? NodeFilter.FILTER_ACCEPT
        : NodeFilter.FILTER_REJECT,
  });

  let node: Node | null = null;
  while (true) {
    node = walker.nextNode();
    if (!node) break;
    textNodes.push(node);
  }

  // 计算累积文本长度和节点位置
  let totalLength = 0;
  return textNodes.map((textNode) => {
    const text = textNode.textContent ?? "";
    const start = totalLength;
    totalLength += text.length;
    return { node: textNode, text, start, end: totalLength };
  });
};

highlight-11.png

高亮数据

const getSelectionPosition = () => {
  const selection = window.getSelection();
  // 1. 获取高亮文本
  const selectedText = selection.toString().trim();

  // 2. 获取高亮文本定位(用于弹框定位显示)
  const range = selection.getRangeAt(0);
  const rectList = range.getClientRects();
  const position = { top: rectList[0].top, left: rectList[0].left };

  // 3. 获取高亮文本位置(相对于全局文本的位置,用于高亮标色)
  let globalStart = -1;
  let globalEnd = -1;
  const nodeMap = getAllNodes();
  for (const { node, start } of nodeMap) {
    // 查找起始节点位置
    if (node === startContainer) globalStart = start + range.startOffset;
    // 查找结束节点位置
    if (node === endContainer) globalEnd = start + range.endOffset;
    // 提前退出
    if (globalStart >= 0 && globalEnd > 0) break;
  }

  if (globalStart >= 0 && globalEnd > 0) {
    console.log(`[选中范围]${globalStart}-${globalEnd}`);
    // 多行选择时,会跨元素,要找到第一个元素的id
    const startElement = getElementWithAttributes(selection.anchorNode);
    console.log("[开始元素]", startElement);

    return {
      startIndex: globalStart,
      endIndex: globalEnd,
      selectedText,
      className: "orange",
      chapterId,
      divId: startElement.id,
      top: position.top + contentRef.current.scrollTop,
      left: position.left,
    };
  }
};

highlight-7.png

高亮文本

const highlightText = (note) => {
  // 1. 先清除现有高亮
  removeHighlights(contentRef);

  // 2. 获取节点映射
  const nodeMap = getAllNodes(contentRef);

  // 3. 创建高亮范围
  const highlights: { range: Range, className: string, id: string }[] = [];

  // 4. 遍历nodeMap,处理每个文本节点
  for (const { node, text, start, end } of nodeMap) {
    const nodeStart = Math.max(0, note.startIndex - start);
    const nodeEnd = Math.min(text.length, note.endIndex - start);

    if (nodeStart >= nodeEnd) continue;
    console.log(`处理节点: "${text}" (${start}-${end})`);
    console.log(`节点高亮范围: ${nodeStart}-${nodeEnd}`);

    // 创建范围并高亮
    const range = document.createRange();
    range.setStart(node, nodeStart);
    range.setEnd(node, nodeEnd);
    highlights.push({
      range,
      className: `highlight-${note.className}`,
      id: note.divId,
    });
  }

  // 按位置从后往前高亮(避免位置偏移)
  highlights.sort((a, b) => b.range.startOffset - a.range.startOffset);
  for (const { range, className, id } of highlights) {
    // 创建高亮元素
    const span = document.createElement("span");
    span.className = className;
    // 添加笔记ID到data属性
    span.dataset.noteId = id;
    // 插入高亮内容
    span.appendChild(range.extractContents());
    range.insertNode(span);
  }
};

创建高亮元素并插入内容:

highlight-10.png

高亮前:

highlight-8.png

高亮后:

highlight-9.png

选中操作

复制

if (!note?.selectedText) return;
navigator.clipboard.writeText(note.selectedText);
toast.success("已复制到剪贴板");

报错提示:Uncaught TypeError: Cannot read properties of undefined (reading 'writeText')

报错原因:navigator.clipboard.writeText() 方法需要浏览器支持,才能正常执行。浏览器会禁用非安全域(http)的 navigator.clipboard 对象,而在 localhosthttps 下不会禁用。

【节点】[Ceiling节点]原理解析与实际应用

作者 SmalBox
2026年5月6日 16:18

【Unity Shader Graph 使用与特效实现】专栏-直达

在Unity URP Shader Graph中,Ceiling节点是一个重要的数学运算节点,它执行向上取整操作。这个节点在着色器编程中具有广泛的应用场景,特别是在需要将连续值转换为离散整数值的情况下。Ceiling节点的功能类似于编程语言中的ceil()函数,它能够将输入的浮点数值向上舍入到最接近的整数。

Ceiling节点在Shader Graph中属于数学运算类别,它接受任意维度的矢量输入,并返回相同维度的矢量输出。这意味着它可以处理从单个浮点数到四维矢量的各种数据类型,为着色器开发提供了极大的灵活性。

理解Ceiling节点的工作原理和应用场景对于创建高质量的着色器效果至关重要。无论是创建像素化效果、实现网格对齐,还是进行数值离散化处理,Ceiling节点都能提供精确的数学运算支持。

描述

Ceiling节点的核心功能是执行向上取整运算。具体来说,对于输入的任意浮点数值,Ceiling节点会返回大于或等于该值的最小整数。这个操作在数学上称为"天花板函数",因为它总是将数值向上取整到最近的整数值。

向上取整操作与向下取整(Floor)和四舍五入(Round)操作有着明显的区别。向下取整总是向负无穷方向取整,而四舍五入则根据小数部分的值决定向上或向下取整。Ceiling节点的行为则始终向上取整,无论小数部分的大小如何。

在Shader Graph中,Ceiling节点能够处理各种数据类型的输入,包括:

  • 浮点数(Float)
  • 二维矢量(Vector2)
  • 三维矢量(Vector3)
  • 四维矢量(Vector4)

当输入是多维矢量时,Ceiling节点会对每个分量独立执行向上取整操作。例如,对于输入值(1.2, 2.7, 3.0, 4.9),Ceiling节点将返回(2.0, 3.0, 3.0, 5.0)。

Ceiling节点在图形渲染中有多种应用场景。在创建像素化效果时,可以使用Ceiling节点将连续的UV坐标转换为离散的网格坐标。在实现材质平铺时,Ceiling节点可以帮助确保纹理正确对齐。在光照计算中,Ceiling节点可以用于创建离散的光照级别,实现卡通风格的渲染效果。

需要注意的是,Ceiling节点的性能开销相对较小,因为它执行的是简单的数学运算。在大多数现代GPU上,向上取整操作都能高效执行,不会对渲染性能造成显著影响。

端口

Ceiling节点的端口设计简洁而高效,遵循了Shader Graph节点设计的一致性原则。节点包含一个输入端口和一个输出端口,两者都支持动态矢量类型,这意味着它们可以自动适应连接的数据类型。

输入端口

输入端口名为"In",是Ceiling节点接收数据的入口。这个端口具有以下特性:

  • 方向:输入
  • 类型:动态矢量
  • 功能描述:接收需要执行向上取整操作的值

输入端口支持的数据类型包括:

  • Float:单精度浮点数
  • Vector 2:包含两个浮点数的二维矢量
  • Vector 3:包含三个浮点数的三维矢量
  • Vector 4:包含四个浮点数的四维矢量

当连接不同维度的数据时,Shader Graph会自动进行类型转换和适配。例如,如果将一个浮点数连接到期望Vector4的端口,系统会自动将浮点数扩展为四个分量相同的Vector4。

输入值的范围没有特定限制,Ceiling节点可以处理任意大小的浮点数值,包括正数、负数和零。对于特殊值如无穷大和NaN(非数字),Ceiling节点的行为遵循IEEE浮点数标准的规定。

输出端口

输出端口名为"Out",是Ceiling节点返回计算结果的出口。这个端口具有以下特性:

  • 方向:输出
  • 类型:动态矢量
  • 功能描述:输出向上取整后的结果值

输出端口的数据类型始终与输入端口保持一致。如果输入是Vector3类型,输出也会是Vector3类型,其中每个分量都经过了独立的向上取整处理。

输出值的特性包括:

  • 所有输出分量都是整数值
  • 输出值大于或等于对应的输入值
  • 输出值与输入值的差小于1

在实际使用中,输出端口可以连接到其他节点的输入端口,形成复杂的着色器计算流水线。由于输出值是整数,它们特别适合用作纹理数组的索引、循环计数器或条件判断的基准值。

端口连接示例

理解端口之间的连接方式对于有效使用Ceiling节点至关重要。以下是一些常见的连接模式:

  • 将UV坐标连接到In端口,然后使用Out端口驱动纹理采样,可以创建像素化效果
  • 将世界空间位置连接到In端口,然后使用Out端口计算网格对齐,可以实现体素化渲染
  • 将时间变量连接到In端口,然后使用Out端口创建离散的时间间隔,可以实现帧动画效果

端口连接的灵活性使得Ceiling节点能够适应各种复杂的着色器需求,从简单的数学运算到复杂的视觉效果生成。

生成的代码示例

当在Shader Graph中使用Ceiling节点时,Unity会在生成的着色器代码中插入相应的函数调用。理解这些生成的代码对于调试和优化着色器非常重要。

以下是Ceiling节点生成的典型HLSL代码:

HLSL

void Unity_Ceiling_float4(float4 In, out float4 Out)
{
    Out = ceil(In);
}

这个函数接受一个float4类型的输入参数In,计算其向上取整值,并通过输出参数Out返回结果。函数内部调用了HLSL内置的ceil()函数,这是DirectX着色器语言标准的一部分。

代码结构分析

生成的代码遵循了Unity Shader Graph的标准模式:

  • 函数名采用Unity_前缀,后跟节点名称和数据类型
  • 输入参数使用值传递方式
  • 输出参数使用out关键字,表示通过引用返回结果
  • 函数体简洁明了,直接调用相应的数学函数

对于不同的输入数据类型,Unity会生成相应的函数变体:

HLSL

// 浮点数版本
void Unity_Ceiling_float(float In, out float Out)
{
    Out = ceil(In);
}

// 二维矢量版本
void Unity_Ceiling_float2(float2 In, out float2 Out)
{
    Out = ceil(In);
}

// 三维矢量版本
void Unity_Ceiling_float3(float3 In, out float3 Out)
{
    Out = ceil(In);
}

性能考虑

从生成的代码可以看出,Ceiling节点的执行效率很高:

  • 直接映射到GPU的硬件指令
  • 没有复杂的控制流或条件判断
  • 支持矢量化操作,能够并行处理多个分量

在大多数现代GPU架构上,ceil()函数通常能在单个时钟周期内完成,这使得Ceiling节点成为着色器中性价比很高的数学运算工具。

自定义实现

虽然Unity会自动生成Ceiling节点的代码,但了解其实现原理有助于在需要时创建自定义版本。以下是一个功能等效的自定义实现:

HLSL

float4 CustomCeiling(float4 value)
{
    return floor(value) + 1.0 - step(frac(value), 0.0);
}

这个实现使用了floor()函数和frac()函数来模拟向上取整的行为,虽然不如内置的ceil()函数高效,但展示了向上取整操作的数学原理。

理解生成的代码还有助于在不同渲染管线之间移植着色器。例如,如果要将使用Ceiling节点的着色器从URP迁移到HDRP,或者适配不同的图形API,了解底层的HLSL代码会大大简化迁移过程。

实际应用案例

Ceiling节点在实际着色器开发中有着广泛的应用。以下是一些具体的应用场景和实现方法,展示了如何充分利用Ceiling节点创建各种视觉效果。

像素化效果实现

像素化效果是Ceiling节点的经典应用场景。通过将连续的UV坐标离散化,可以创建出复古的像素艺术风格:

HLSL

// 创建像素化UV坐标
float2 pixelatedUV = ceil(uv * pixelCount) / pixelCount;

在这种应用中,Ceiling节点确保每个像素区域内的所有点都映射到同一个离散坐标,从而创建出清晰的像素边界。调整pixelCount参数可以控制像素化程度,数值越大,像素越细小。

网格对齐和瓦片处理

在创建瓦片地图或网格基础的效果时,Ceiling节点可以确保物体正确对齐到网格:

HLSL

// 将世界坐标对齐到网格
float3 gridAlignedPosition = ceil(worldPosition * gridSize) / gridSize;

这种方法特别适用于:

  • 体素游戏的渲染
  • 策略游戏的网格移动
  • 建筑可视化中的对齐显示

离散化动画控制

Ceiling节点可以用于创建离散的时间间隔,实现帧动画效果:

HLSL

// 创建离散化的时间索引
float frameIndex = ceil(time * framesPerSecond);

这种技术适用于:

  • 精灵动画(Sprite Animation)
  • 帧动画序列
  • 定时触发的特效

光照和阴影处理

在 stylized 渲染中,Ceiling节点可以用于创建离散的光照级别:

HLSL

// 创建离散化光照值
float discreteLighting = ceil(dot(N, L) * lightLevels) / lightLevels;

这种方法可以创建出卡通风格的光照效果,其中光照过渡是阶梯状的而不是平滑的。

高级数学运算

Ceiling节点还可以与其他数学节点结合,实现更复杂的数学运算:

HLSL

// 计算向上取整的除法
float ceilDivision = ceil(dividend / divisor);

// 创建数值分箱(Binning)
float binnedValue = ceil(value * binCount) / binCount;

这些高级应用展示了Ceiling节点在数值处理和数据分析方面的潜力。

最佳实践和注意事项

为了充分发挥Ceiling节点的潜力,同时避免常见的陷阱,以下是一些最佳实践和注意事项。

性能优化

虽然Ceiling节点本身性能开销很小,但在大规模使用时仍需注意:

  • 避免在片段着色器中过度使用复杂的Ceiling操作链
  • 考虑将计算转移到顶点着色器或计算着色器中
  • 利用矢量化操作,一次性处理多个分量

数值精度考虑

在使用Ceiling节点时,需要注意浮点数精度问题:

  • 对于极大或极小的数值,可能会出现精度损失
  • 在比较Ceiling结果时,使用适当的容差值
  • 注意不同GPU架构可能存在的精度差异

与其他节点的配合

Ceiling节点通常与其他数学节点配合使用:

  • 与Floor节点结合,可以创建数值范围限制
  • 与Frac节点结合,可以分离数值的整数和小数部分
  • 与Round节点结合,可以实现不同的取整策略

调试技巧

当Ceiling节点行为不符合预期时,可以采取以下调试措施:

  • 使用Position节点可视化输出结果
  • 通过Divide节点缩放输出值,使其在可视范围内
  • 使用Custom Function节点插入调试输出

平台兼容性

Ceiling节点在大多数平台上都有良好的兼容性,但仍需注意:

  • 确保目标平台支持所需的精度级别
  • 在移动平台上测试性能表现
  • 验证在不同图形API下的行为一致性

【Unity Shader Graph 使用与特效实现】专栏-直达 (欢迎点赞留言探讨,更多人加入进来能更加完善这个探索的过程,🙏)

mock模拟后端,生成伪数据接口

作者 RONIN
2026年5月6日 15:51

官网:github.com/nuysoft/Moc…

1. 安装

npm i mockjs vite-plugin-mock 安装 mockjs和 vite-plugin-mock插件

2. vite.config.ts中集成插件

import { fileURLToPath, URLfrom 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

import Components from 'unplugin-vue-components/vite'//引入按需引入vant插件

import { VantResolverfrom 'unplugin-vue-components/resolvers'

import { viteMockServe } from 'vite-plugin-mock'//引入mock插件

// https://vitejs.dev/config/

export default defineConfig({

  plugins: [

    vue(),

    Components({

      resolvers: [VantResolver()],

    }),

    viteMockServe({//配置mock插件

      // 更多配置见最下方

      supportTstrue,

      loggerfalse,

      mockPath'./mock/', // 文件位置

    }),

  ],

  resolve: {

    alias: {

      '@'fileURLToPath(new URL('./src', import.meta.url))

    }

  }

})

3. mock文件夹mock接口数据

scr同级创建mock文件夹→account.ts(模块拆分,post请求config.body取参)


const accountList = []

/**

 * 用户注册

 */

export const mockRegister = {

    url:'/mock/account/register',

    method:'post',

    response:(config)=>{

        // 注册业务逻辑

        // 1. 获取用户名和密码

        const {username,password,headerimg} = config.body

        // 2. 保存用户信息

        // localStorage.setItem('USER',JSON.stringify({username,password,headerimg}))

        const user = {username,password,headerimg}

        accountList.push(user)

        // 3. 响应内容

        return {

            resultCode:1,

            resultInfo:'注册成功'

        }

    }

}

 

/**

 * 用户登录

 */

export const mockLogin = {

    url:'/mock/account/login',

    method:'post',

    response:(config)=>{

        // 登录业务逻辑

        // 1. 获取用户名和密码

        const {username,password,headerimg} = config.body

        // 2. 判断用户是否注册

        // let userstr = localStorage.getItem('USER')

        // let user = userstr? JSON.parse(userstr):''

        const user = accountList.find(item=>item.username==username && item.password==password)

        if(user){

            return {

                resultCode:1,

                resultInfo: {

                        username,

                        password,

                        headerimg

                }

            }

        }else{

            return {

                resultCode:-1,

                resultInof:'账户出错'

            }

        }

    }

}

scr同级创建mock文件夹→good.ts(模块拆分,get请求config.query取参)

import { goodsListData, bannerListData } from './data/goodsData'

/**

 * 商品列表

 */

export const goodsList = {

    url'/mock/goods/list',

    method'get',

    response(config:any) => {

        //get请求参数

        let { pageNo, pageSize } = config.query

        pageNo = pageNo || 1

        pageSize = pageSize || 10

        console.log('pageNo ', pageNo, ' pageSize :', pageSize)

        // 分页

        const startIndex = (pageNo - 1) * pageSize

        const endIndex = pageNo * pageSize

        const list = goodsListData.slice(startIndex, endIndex)

        if(list.length>0){

            return {

                resultCode1,

                resultInfo: {

                    list,

                },

            }

        }else{

            return {

                resultCode:-1,

                resultInfo:'没有数据'

            }

        }

    },

}

 

/**

 *  banner轮播

 */

export const bannerList = {

    url'/mock/banner',

    method'get',

    response() => {

        return {

            resultCode1,

            resultInfo: {

                list: bannerListData,

            },

        }

    },

}

scr同级创建mock文件夹→data文件夹→goodsData.ts(模块拆分,存放数据)


export const goodsListData = [

    {

        id49,

        shop'【苏宁生鲜】鲜美来东海带鱼600g 海鲜水产 鲜活冷冻',

        picture:

            'https://image1.suning.cn/uimg/b2c/newcatentries/0010128947-000000000614428161_1_800x800.jpg',

        product'【苏宁生鲜】鲜美来东海带鱼600g 海鲜水产 鲜活冷冻',

        price18.88,

        oldprice69,

        putaway1,

        detailnull,

        categoryname'川湘菜',

        categoryId3,

    },

    {

        id48,

        shop'【苏宁生鲜】恒都巴西牛腩块1kg 进口牛肉 精选肉类',

        picture:

            'https://image1.suning.cn/uimg/b2c/newcatentries/0010128947-000000000614167327_1_800x800.jpg',

        product'【苏宁生鲜】恒都巴西牛腩块1kg 进口牛肉 精选肉类',

        price18.98,

        oldprice49,

        putaway1,

        detailnull,

        categoryname'川湘菜',

        categoryId3,

    },

    {

        id45,

        shop'贝克巴斯(BECBAS)E50 厨房家用食物垃圾处理器 厨余垃圾粉碎机 无线开关免打孔',

        picture:

            'https://image3.suning.cn/uimg/b2c/newcatentries/0000000000-000000000616963357_2_800x800.jpg',

        product:

            '贝克巴斯(BECBAS)E50 厨房家用食物垃圾处理器 厨余垃圾粉碎机 无线开关免打孔',

        price38,

        oldprice67,

        putaway1,

        detailnull,

        categoryname'大家电',

        categoryId9,

    },

    {

        id44,

        shop'科龙(Kelon) 正1.5匹 定速 冷暖 空调挂机 ',

        picture:

            'https://image4.suning.cn/uimg/b2c/newcatentries/0000000000-000000000178605073_1_800x800.jpg',

        product'科龙(Kelon) 正1.5匹 定速 冷暖 空调挂机 ',

        price156.9,

        oldprice190,

        putaway1,

        detail'这个商品不错',

        categoryname'排骨',

        categoryId7,

    },

    {

        id42,

        shop'华帝浴室花洒 增压花洒 主体全铜花洒 沐浴莲蓬头【自营】H-CS0014-B1D.W',

        picture:

            'https://image2.suning.cn/uimg/b2c/newcatentries/0000000000-000000000604135232_1_800x800.jpg',

        product:

            '华帝浴室花洒 增压花洒 主体全铜花洒 沐浴莲蓬头【自营】H-CS0014-B1D.W',

        price18.87,

        oldprice90,

        putaway1,

        detailnull,

        categoryname'排骨',

        categoryId7,

    },

    {

        id41,

        shop'长虹(CHANGHONG) 大1匹 冷暖定频 快速制冷热 空调挂机 KFR-26GW/DHID(W1-J)+2',

        picture:

            'https://image2.suning.cn/uimg/b2c/newcatentries/0000000000-000000000126066901_1_800x800.jpg',

        product:

            '长虹(CHANGHONG) 大1匹 冷暖定频 快速制冷热 空调挂机 KFR-26GW/DHID(W1-J)+2',

        price18.48,

        oldprice35,

        putaway1,

        detailnull,

        categoryname'火锅',

        categoryId8,

    },

    {

        id40,

        shop'小米智米(SMARTMI)智能马桶盖 家用全自动冲洗即热式加热外置过滤器杀菌洁便器',

        picture:

            'https://image4.suning.cn/uimg/b2c/newcatentries/0000000000-000000000673521926_1_800x800.jpg',

        product:

            '小米智米(SMARTMI)智能马桶盖 家用全自动冲洗即热式加热外置过滤器杀菌洁便器',

        price34.98,

        oldprice47,

        putaway1,

        detailnull,

        categoryname'火锅',

        categoryId8,

    },

]

 

/**

 * 轮播数据

 */

export const bannerListData = [

    {

        id1,

        url'https://img.alicdn.com/imgextra/i3/2053469401/O1CN01g8ituT2JJiCsKjmDz_!!2053469401.png',

        content'商家1',

        number1,

    },

    {

        id11,

        url'https://img2.baidu.com/it/u=717979571,3244631707&fm=253&fmt=auto&app=138&f=JPEG?w=1280&h=400',

        content'舒适度满分',

        number1,

    },

    {

        id12,

        url'https://img1.baidu.com/it/u=1733684228,4177721799&fm=253&fmt=auto&app=138&f=JPEG?w=1200&h=500',

        content'曲线在召唤',

        number1,

    },

]

scr同级创建创建mock文件夹→index.ts(模块集成暴露)


import { bannerList, goodsList } from './goods'

import { mockRegister, mockLogin } from './account'

 

const goods = [bannerList, goodsList]  // 商品模块接口

const account = [mockLogin, mockRegister] // 个人中心接口

 

export default [...goods,...account]

4. utils文件夹→requestMock.ts(封装axios,不封装直接使用axios也行)

import axios from 'axios'
import { Toastfrom 'vant'

export let baseURL = 'http://10.7.163.159:5173'  

/**

 * 创建axios实例

 *   封装baseURL

 */

const axiosInstance = axios.create({

    baseURL, // 服务根地址

    timeout3000, // 超时时间

})

 

/**

 * 请求拦截器

 */

axiosInstance.interceptors.request.use(

    config => {

        const token = localStorage.getItem('TOKEN')

        if (token) {

            config.headers['Authorization'] = token

        }

        return config

    },

    error => {

        return Promise.reject(error)

    }

)

/**

 * 响应拦截器

 */

axiosInstance.interceptors.response.use(

    response => {

        return response.data

    },

    error => {

        const { response } = error

        if (response) {

            const status = response.status

            switch (status) {

                case 404:

                    Toast('资源不存在 404')

                    break

                case 401:

                    Toast('Unauthorized 身份验证凭证缺失!')

                    break

                case 403:

                    Toast('403 Forbidden - 拒绝访问!')

                    break

                case 500:

                    Toast('服务器出错')

                    break

                default:

                    Toast('出现异想不到的错误!')

                    break

            }

        } else {

            // 说明服务器连结果都没有返回,可能的原因有两种:

            /**

             * 1. 服务器崩掉了

             * 2. 前端客户端断网状态

             */

            if (!window.navigator.onLine) {

                // 判断为断网,可以跳转到断网页面

                Toast('网络不可用,请检查您的网络连接!')

                return

            } else {

                Toast('连接服务端出错!' + error?.message)

                return Promise.reject(error)

            }

        }

        return Promise.reject(error)

    }

)

export default axiosInstance

5. api文件夹→index.ts文件中定义接口

import axiosInstance from '@/utils/request'
import axiosMockInstance from '@/utils/requestMock'
import type{IResponse} from '@/types/types'


/**

 * 产品列表

 *   shopKey: 店铺名称

 *   productKey: 产品名称

 * @returns 

 */

export const RequestShopList = (pageNo:number,pageSize:number):Promise<IResponse>=>{

    return axiosInstance({

        method:'get',

        url:'/api/shop',

        params:{

            pageSize,

            pageNo,

        }

    })

}

/**

 * 轮播

 */

export const RequestBanner = ():Promise<IResponse>=>{

    return axiosInstance({

        method:'get',

        url:'/api/banner'

    })

}

/**

 * 登录

 */

export const RequestLogin = (username:string,password:string):Promise<IResponse>=>{

    return axiosMockInstance({

        method:'post',

        // url:'/api/member/login',

        url:'/mock/account/login',

        data:{

            username,

            password

        }

    })

}

/**

 * 注册

 */

export const RequestRegister = (username:string,password:string,headerimg:string):Promise<IResponse>=>{

    return axiosMockInstance({

        method:'post',

        url:'/mock/account/register',

        data:{

            username,

            password,

            headerimg

        }

    })

}

.vue文件中引入使用即可

JavaScript原型,原型链

作者 薯老板
2026年5月5日 20:45

原型和构造函数密切相关,了解原型之前,我们先回顾一下构造函数。

一、构造函数

像 Object 和 Array 这样的原生构造函数,运行时可以直接在执行环境中使用。当然也可以自定义构造函数,以函数的形式为自己的对象类型定义属性和方法。——JavaScript高级程序设计

function Person(name, age){
    this.name = name
    this.age = age
    this.hobby= function(){
        console.log('sport')
    }
}
const person1= new Person('Lisa', 18)
const person2 = new Person('Jony', 20)

person1.hobby()
person2.hobby()

需要注意的是,构造函数名称的首字母都是要大写的。函数体内使用this关键字,代表所要生成的对象实例。任何函数只要使用 new 操作符调用就是构造函数。

构造函数虽然有用,但是也存在着浪费内存的问题:每创建一个对象,都会在堆内存空间中新开辟一个空间来存储方法。这个问题可以通过引入原型对象来解决。

二、原型

原型就是一个对象,也叫原型对象。

1. 理解原型

  • 每个函数都会创建一个 prototype 属性,属性值是一个普通对象。
function Person(){}
console.dir(Person)

1.png

  • 原型上默认有一个叫做constructor的属性,指向这个构造函数本身。
console.log(Person.prototype.constructor === Person) // true
  • 使用原型对象的好处是,在它上面定义的属性和方法可以被对象实例共享。原来在构造函数中直接赋给对象实例的值,可以直接赋值给它们的原型。
function Person(){}
Person.prototype.name = "Mike";
Person.prototype.age = 7;
// 公共的方法写到原型对象上  节约了内存
Person.prototype.hobby= function(){
    console.log('sport')
}

let person1 = new Person()
const res = person1.name 
console.log(res)  // "Mike"

let person2 = new Person()
const res = person2.name 
console.log(res)  // "Mike"

console.log(person1.hobby== person2.hobby)  // true

2. __proto__隐式原型

  • 所有对象,都有一个__proto__属性,指向原型对象。
  • 实例通过__proto__访问原型对象。
  • 对象的隐式原型指向构造函数的显示原型
console.log(person1.__proto__ === Person.prototype)   //true

proto 表示了实例和原型之间的一个关系,相当于就是一个桥梁,实例通过它访问原型。

三、构造函数、原型、实例的关系

  1. 构造函数.prototype ——> 原型对象
  2. 原型对象.constructor ——> 构造函数
  3. 实例对象.__ proto__ ——> 原型对象
  4. 构造函数 new , 创建出实例对象

2.png

实例与构造函数原型之间有直接的联系,但实例与构造函数之间没有直接联系。

四、原型的五条规则

  1. 所有的引用类型(对象 数组 函数),都具有对象的特征,可以自由扩展属性。
  2. 每一个对象都有一个__proto__属性,这个属性是一个对象。
  3. 所有的函数都有一个 prototype 属性,这个属性也是一个对象。
  4. 所有对象的__proto__属性值,都指向它的构造函数 prototype 属性值。
  5. 实例化对象想要获取的属性值如果构造函数没有,它会向构造函数的原型中寻找,如果原型也没有,则会向原型的__proto__中寻找,直到拿到或没有该属性值。

五、原型链

原型对象也可能拥有原型,并从中继承方法和属性,一层一层、以此类推。这种关系常被称为原型链,它解释了为何一个对象会拥有定义在其他对象中的属性和方法。

function Person(name){
    this.name = name
}
const person = new Person()
  1. 对象的隐式原型指向构造函数的显示原型。
console.log(person.__proto__ === Person.prototype)  // true
  1. 所有的对象都有一个__proto__,属性值也是一个对象,Person.prototype 也是一个对象,所以,它也有__proto__属性,属性值也是对象。原型上默认有一个 constructor 属性,指回的构造函数,所以 Person.prototype 的构造函数是 Object。
console.log(Person.prototype.__proto__)  // __proto__ 访问到原型
// Person.prototype 这个原型对象 是Object这个构造函数创建的
console.log(Person.prototype.__proto__ === Object.prototype)  // true

3. Object 是一个构造函数,Object.prototype 得到的也是一个原型,所以 Object.prototype 这个原型上默认有一个constructor属性,指向构造函数本身。

Object.prototype.constructor === Object  // Object.prototype指向构造函数本身
console.log(Person.prototype.__proto__ === Object.prototype)    // true

4. Object.prototype 也是一个原型对象,所以它也有一个__proto__属性。

// 正常的原型链终止到Object.prototype, 也就是 Object.prototype.__proto__ === null
console.log(Object.prototype.__proto__ === null)  // true

根据以上结论,我们用一张图来更加清晰的理解原型链:

3.png

简单概况一下:

每个对象通过__proto__属性都能访问到它的原型对象,原型对象也有它的原型对象,当访问一个对象属性或方法的时候,先在自身中寻找,如果没有,就会沿着__proto__这条链向上查找,直到最顶层 Object.prototype 为止,最后 Object.prototype.proto === null。

数据的源头 —— JSX

作者 发大财chd
2026年5月5日 05:21

著有《React18 设计原理》《javascript地月星》等多个专栏。 欢迎关注。

创作不易,有帮助别忘了点赞,收藏,评论 ~ 你的鼓励是我继续挖干货的动力。

本文全部都是原创内容,商业转载请联系作者获得授权,非商业转载需注明出处,感谢理解 ~

推荐指数(值得一读):⭐️⭐️⭐️⭐️⭐️⭐️⭐️⭐️⭐️⭐️⭐️⭐️

原文 👉 juejin.cn/post/763192…

React.createElement

创建新的 Fiber,new FiberNode 是没有数据的,对于 Fiber 节点的节点类型、样式、事件、子节点等属性一无所知。这些数据来自我们在 JSX 的声明。看一个的例子。

  • 原组件
//LazyComp.jsx
export default function LazyComp() {
  return <h1>✅Hello !</h1>;
}
//App.jsx
const LazyComp = lazy(() => {
  return new Promise(resolve => {
    setTimeout(() => {
      resolve(import('./LazyComp'));
    }, 2000); // 模拟 2 秒延迟
  });
});
export default function App() {
  return (
    <div>
      <Suspense fallback={<div>Loading...2</div>}>
        <LazyComp />
      </Suspense>
    </div>
  );
}
  • 编译后
//LazyComp-BtMAPHcf.js
function LazyComp() {
  return /* @__PURE__ */ React.createElement("h1", null, "✅Hello !");
}
//App-BBcglL-c.js
const LazyComp = lazy( () => {
    return new Promise( (resolve) => {
        setTimeout( () => {
            resolve(import("/dist/assets/LazyComp-BtMAPHcf.js")); //上面的LazyComp本体
        }
        , 8e3);
    }
    );
}
function App() {
  return /* @__PURE__ */
    React.createElement("div", null, /* @__PURE__ */
    React.createElement(Suspense, {
        fallback: /* @__PURE__ */
        React.createElement("div", null, "Loading...2")
    }, /* @__PURE__ */
    React.createElement(LazyComp, null)));
}

function renderWithHooks(current, workInProgress, Component, props, secondArg, nextRenderLanes) {
  ...
  var children = Component(props, secondArg); //function App(){...  return React.createElement('div',{},React.createElement('p',{}, 'xx'))}
  ...
  return children;
}

从内到外的嵌套顺序执行,最里面的 React.createElement(LazyComp, null) 是最先完成的。

按组件单位生成一次 react element。 完成这一步就有信息可以生成这一部分的 Fiber 树了。
Jsx 变成对象后就是 React Element 对象 :

react ele 节点与它的属性 props

function Comp(){
    return (<div 属性/事件/样式/...>子节点...</div>)
}

var element = {
    $$typeof: REACT_ELEMENT_TYPE,
    type: type, //'div'
    key: key, //null
    ref: ref, //null
    props: props, //props是节点的属性。属性/事件/样式/子节点
    _owner: owner
  };

props = {children, style, onXX, 其他属性}
-   props.children // 子级element
-   props.fallback; // 如果是Suspense,有fallback
-   props.style //样式;
-   props.onXXX //事件
-   props.xxx //其他属性

组件也是这样子的:
<MyComp 属性/事件/样式...></MyComp>
不过我们不会在组件上直接写子节点:
<MyComp 属性/事件/样式...>❌子节点...</MyComp> 不会显示这个子节点。
本来就是按照组件为单位生成子节点,父组件不应该生成 MyComp 组件的子节点的。

代码

var ReactElement = function (type, key, ref, self, source, owner, props) {
  var element = {
    $$typeof: REACT_ELEMENT_TYPE,
    type: type,
    key: key,
    ref: ref,
    props: props,
    _owner: owner
  };

  {
  
    element._store = {}; 

    //ele._store.validated  不可配置、不可枚举、可写
    Object.defineProperty(element._store, 'validated', {
      configurable: false,
      enumerable: false,
      writable: true,
      value: false
    }); 
    //ele._self  不可配置、不可枚举、不可写、只读
    Object.defineProperty(element, '_self', {
      configurable: false,
      enumerable: false,
      writable: false,
      value: self
    });
    //ele._source  不可配置、不可枚举、不可写、只读
    Object.defineProperty(element, '_source', {
      configurable: false,
      enumerable: false,
      writable: false,
      value: source
    });
    // react ele是只读的 props是children/样式/事件等属性,也是只读的
    // 不可变类型: 不是freeze;没有做任何检查和约束,但是直接设置值不会生效。
    // freeze可以作为不可变的实现。
    // 常量:大写、对象类型的属性也不可变。冻结:state是否也是一个freeze的?不是。  
    if (Object.freeze) {
      Object.freeze(element.props);
      Object.freeze(element);
    }
  }

  return element;
};

//React.createElement(Suspense/'div', {fallback:, style:, onXXX:, key:,}, React.createElement())
function createElement(type, config, children) {
  var propName; 

  var props = {};
  var key = null;
  var ref = null;
  var self = null;
  var source = null;

  // react ele的ref和key 、 react ele的props的其他属性
  if (config != null) {
    // ref
    if (hasValidRef(config)) {
      ref = config.ref;

      {
        warnIfStringRefCannotBeAutoConverted(config);
      }
    }
    // key
    if (hasValidKey(config)) {
      {
        checkKeyStringCoercion(config.key);
      }

      key = '' + config.key;
    }

    // react ele的props的其他属性 style/onXXX/fallback
    self = config.__self === undefined ? null : config.__self;
    source = config.__source === undefined ? null : config.__source;
    for (propName in config) {
      if (hasOwnProperty.call(config, propName) && !RESERVED_PROPS.hasOwnProperty(propName)) {
        props[propName] = config[propName];
      }
    }
  } 

  //react ele的props的children=children/[...]
  //children=children单个子节点、children = []多个子节点
  var childrenLength = arguments.length - 2;
  if (childrenLength === 1) {
    props.children = children;
  } else if (childrenLength > 1) {
    var childArray = Array(childrenLength);

    for (var i = 0; i < childrenLength; i++) {
      childArray[i] = arguments[i + 2];
    }

    {
      if (Object.freeze) {
        Object.freeze(childArray);
      }
    }

    props.children = childArray;
  } 

  // 例如App.defaultProps
  if (type && type.defaultProps) {
    var defaultProps = type.defaultProps;

    for (propName in defaultProps) {
      if (props[propName] === undefined) {
        props[propName] = defaultProps[propName];
      }
    }
  }

  {
    if (key || ref) {
      var displayName = typeof type === 'function' ? type.displayName || type.name || 'Unknown' : type;

      if (key) {
        defineKeyPropWarningGetter(props, displayName);
      }

      if (ref) {
        defineRefPropWarningGetter(props, displayName);
      }
    }
  }

  return ReactElement(type, key, ref, self, source, ReactCurrentOwner.current, props);
}

hooks 的信息也来自 JSX

function App() {
  // 这些是hooks
  const [isPending, startTransition] = useTransition();
  const [inputValue, setInputValue] = useState("");
  const [list, setList] = useState([]);
  const [show, setShow] = React.useState(false);
  const [show2, setShow2] = React.useState(true);
  
  return /* @__PURE__ */
    React.createElement("div", null, /* @__PURE__ */
    React.createElement(Suspense, {
        fallback: /* @__PURE__ */
        React.createElement("div", null, "Loading...2")
    }, /* @__PURE__ */
    React.createElement(LazyComp, null)));
}
❌
❌