XunDoc开发之旅：当AI医生遇上家庭健康管家

当我在生活中目睹家人为管理复杂的健康数据、用药提醒而手忙脚乱时，一个想法冒了出来：我能否打造一个App，像一位贴心的家庭健康管家，把全家人的健康都管起来？它不仅要能记录数据，还要够聪明，能解答健康疑惑，能主动提醒。这就是 XunDoc App。

1. 搭建家庭的健康数据中枢

起初，我转向AI助手寻求架构指导。我的构想很明确：一个以家庭为单位，能管理成员信息、记录多种健康指标（血压、血糖等）的系统。AI很快给出了基于SwiftUI和MVVM模式的代码框架，并建议用UserDefaults来存储数据。

但对于一个完整的应用而言，我马上遇到了第一个问题：数据如何在不同视图间高效、准确地共享？ 一开始我简单地使用@State，但随着功能增多，数据流变得一团糟，经常出现视图数据不同步的情况。

接着在Claude解决不了的时候我去询问Deepseek，它一针见血地指出：“你的数据管理太分散了，应该使用EnvironmentObject配合单例模式，建立一个统一的数据源。” 这个建议成了项目的转折点。我创建了FamilyShareManager和HealthDataManager这两个核心管家。当我把家庭成员的增删改查、健康数据的录入与读取都交给它们统一调度后，整个应用的数据就像被接通了任督二脉，立刻流畅稳定了起来。

2. 请来AI医生：集成Moonshot API

基础框架搭好，接下来就是实现核心的“智能”部分了。我想让用户能通过文字和图片，向AI咨询健康问题。我再次找到AI助手，描述了皮肤分析、报告解读等四种咨询场景，它很快帮我写出了调用Moonshot多模态API的代码。

然而，每件事都不能事事如意的。文字咨询很顺利，但一到图片上传就频繁失败。AI给出的代码在处理稍大一点的图片时就会崩溃，日志里满是编码错误。我一度怀疑是网络问题，但反复排查后，我询问Deepseek，他告诉我：“多模态API对图片的Base64编码和大小有严格限制，你需要在前端进行压缩和校验。”

我把他给我的建议给到了Claude。claude帮我编写了一个“图片预处理”函数，自动将图片压缩到4MB以内并确保编码格式正确。当这个“关卡”被设立后，之前桀骜不驯的图片上传功能终于变得温顺听话。看着App里拍张照就能得到专业的皮肤分析建议，那种将前沿AI技术握在手中的感觉，实在令人兴奋。

3. 打造永不遗忘的智能提醒系统

健康管理，贵在坚持，难在记忆。我决心打造一个强大的医疗提醒模块。我的想法是：它不能是普通的闹钟，而要像一位专业的护士，能区分用药、复查、预约等不同类型，并能灵活设置重复。

AI助手根据我的描述，生成了利用UserNotifications框架的初始代码。但很快，我发现了一个新问题：对于“每周一次”的重复提醒，当用户点击“完成”后，系统并不会自动创建下一周的通知。这完全违背了“提醒”的初衷。

“这需要你自己实现一个智能调度的逻辑，在用户完成一个提醒时，计算出下一次触发的时间，并重新提交一个本地通知。” 这是deepseek告诉我的，我把这个需求告诉给了Claude。于是，在MedicalNotificationManager中， claude加入了一个“重新调度”的函数。当您标记一个每周的用药提醒为“已完成”时，App会悄无声息地为您安排好下一周的同一时刻的提醒。这个功能的实现，让XunDoc从一个被动的记录工具，真正蜕变为一个主动的健康守护者。

4. 临门一脚：App Store上架“渡劫”指南

当XunDoc终于在模拟器和我的测试机上稳定运行后，我感觉胜利在望。但很快我就意识到，从“本地能跑”到“商店能下”，中间隔着一道巨大的鸿沟——苹果的审核。证书、描述文件、权限声明、截图尺寸……这些繁琐的流程让我一头雾水。

这次，我直接找到了DeepSeek：“我的App开发完了，现在需要上传到App Store，请给我一个最详细、针对新手的小白教程。”

DeepSeek给出的回复堪称保姆级，它把整个过程拆解成了“配置App ID和证书”、“在App Store Connect中创建应用”、“在Xcode中进行归档打包”三大步。我就像拿着攻略打游戏，一步步跟着操作：

• 创建App ID：在苹果开发者后台，我按照说明创建了唯一的App ID com.[我的ID].XunDoc。


• 搞定证书：最让我头疼的证书环节，DeepSeek指导我分别创建了“Development”和“Distribution”证书，并耐心解释了二者的区别。


• 设置权限：因为App需要用到相机（拍照诊断）、相册（上传图片）和通知（医疗提醒），我根据指南，在Info.plist文件中一一添加了对应的权限描述，确保审核员能清楚知道我们为什么需要这些权限。

一切准备就绪，我在Xcode中点击了“Product” -> “Archive”。看着进度条缓缓填满，我的心也提到了嗓子眼。打包成功！随后通过“Distribute App”流程，我将我这两天的汗水上传到了App Store Connect。当然不是一次就通过上传的。

5. 从“能用”到“好用”：三次UI大迭代的觉醒

应用上架最初的兴奋感过去后，我陆续收到了一些早期用户的反馈：“功能很多，但不知道从哪里开始用”、“界面有点拥挤，找东西费劲”。这让我意识到，我的产品在工程师思维里是“功能完备”，但在用户眼里可能却是“复杂难用”。

我决定重新设计UI。第一站，我找到了国产的Mastergo。我将XunDoc的核心界面截图喂给它，并提示：“请为这款家庭健康管理应用生成几套更现代、更友好的UI设计方案。”

Mastergo给出的方案让我大开眼界。它弱化了我之前强调的“卡片”边界，采用了更大的留白和更清晰的视觉层级。它建议将底部的标签栏导航做得更精致，并引入了一个全局的“+”浮动按钮，用于快速记录健康数据。这是我第一套迭代方案的灵感来源：从“功能堆砌”转向“简洁现代” 。

然而，Mastergo的方案虽然美观，但有些交互逻辑不太符合iOS的规范。于是，第二站，我请来了Stitch。我将完整的产品介绍、所有功能模块的说明，以及第一版的设计图都给了它，并下达指令：“请基于这些材料，完全重现XunDoc的完整UI，但要遵循iOS Human Interface Guidelines，并确保信息架构清晰，新用户能快速上手。”等到他设计好了后 我将我的设计图UI截图给Claude，让他尽可能的帮我生成。

（以上是我的Stitch构建出来的页面）
Claude展现出了惊人的理解力。它不仅仅是在画界面，而是在重构产品的信息架构。它建议将“AI咨询”的四种模式（皮肤、症状、报告、用药）从并列排列，改为一个主导航入口，进去后再通过图标和简短说明让用户选择。同时，它将“首页”重新定义为真正的“健康概览”，只显示最关键的数据和今日提醒，其他所有功能都规整地收纳入标签栏。这形成了我的第二套迭代方案：从“简洁现代”深化为“结构清晰” 。

拿着Claude的输出，我结合Mastergo和Stitch的视觉灵感，再让Cluade一步一步的微调。我意识到，颜色不仅是美观，更是传达情绪和功能的重要工具。我将原本统一的蓝色系，根据功能模块进行了区分：健康数据用沉稳的蓝色，AI咨询用代表智慧的紫色，医疗提醒用醒目的橙色。图标也设计得更加线性轻量，减少了视觉负担。（其实这是Deepseek给我的建议）这就是最终的第三套迭代方案：在清晰的结构上，注入温暖与亲和力。

这次从Stitch到Claude的UI重塑之旅，让我深刻意识到，一个成功的产品不仅仅是代码的堆砌。它是一次与用户的对话，而设计，就是这门对话的语言。通过让不同的AI助手在我的引导下“协同创作”，我成功地让XunDoc从一個工程师的作品，蜕变成一个真正为用户着想的产品。

现在这款app已经成功上架到了我的App store上 大家可以直接搜索下来进行使用和体验，我希望大家可以在未来可以一起解决问题！

前言

给大家分享一下个人在探索开发three.js编辑器项目期间发现的一些比较不错的3D编辑器类型的开源项目，如果你也正打算做类似相关的项目，那么这些开源项目会是一个不错的参考借鉴

以下排名不分先后🙏🏻

项目一：Astral3D

描述：基于Vue3 + THREE.JS 免费开源的三维引擎及配套编辑器，包含BIM轻量化、CAD解析预览、粒子系统、插件系统等功能。

特点：强大的3D场景内容元素的编辑和保存功能和丰富多样的3D元素内容，同时支持BIM和CAD等工业建模文件的加载渲染

注意⚠️：项目是Apache-2.0 license 的开源协议，项目作者本人也声明了项目可用于个人学习，如有商用需要向作者申请商用授权

界面：

在线地址：editor.astraljs.com/#/

Github: github.com/mlt131220/A…

项目二：thebrowserlab

描述：一个「运行在浏览器里的 3D 编辑器 + 创意编码 (creative-coding) 环境」

特点：支持加载视频、文本、图片、粒子等内容并提供了丰富的编辑表单参数可视化编辑配置，同时还支持在线代码的脚本内容写入设置3D场景内容。

注意⚠️：项目使用 MIT 授权 (MIT license)，意味着你可以自由地 fork、修改、商用 (遵守 MIT 即可)

界面：

在线地址：thebrowserlab.com/

Github: github.com/icurtis1/th…

项目三：threepipe

描述：一个基于 Three.js 构建的现代 3D 框架

特点：项目基于了Three.js进行了二次封装，提供了不少高级功能，使其适合从简单 3D 模型预览到复杂 交互 / 渲染应用，通过简单的API 使用就可以快速创建复杂的3D模型预览器，模型编辑器等内容。

注意⚠️：既然是封装好的框架，在享受使用的便利时，新的学习成本也是不可避免的，项目使用 Apache-2.0-1协议，商用也许需要授权，不过毕竟是歪果仁开发的，即使未授权也难以知晓

界面：

在线地址：editor.threepipe.org/

Github: github.com/repalash/th…

项目四：ShadowEditor

描述：基于Three.js、Go语言和MongoDB的跨平台的3D场景编辑器，支持桌面版和Web版。

特点：跨平台的支持 Windows / Linux / Mac，在桌面 (desktop) 和浏览器 (web) 中都能运行，前后端一体的项目

注意⚠️：使用 MIT 许可证的项目，可以自由用于学习、实验或商业用途。从界面不难看出，应该是属于上古时期的项目了，three.js版本也是107的。作者也推出了商业版的，如有需要也可以试用一下商业版的

界面：

在线地址：http://www.hylab.cn/shadowedito…

Github: gitee.com/tengge1/Sha…

项目五：three-editor

描述：一个基于 Three.js 的 可视化 / 低代码 3D 编辑器 / 内核／框架。它的目标是降低使用 Three.js 的门槛，让构建 Web 3D 场景更简单、更迅速

特点：提供了一整套“可视化 + 配置 + 编辑 + 渲染”的能力，使得即使不深入了解 Three.js，也能快速构建 3D 场景 / 项目，：如果你只是想在网页中展示某个 3D 模型、场景或交互，而不想编写大量 Three.js boilerplate，three-editor 能极大降低门槛

注意⚠️：因为场景内容都是封装处理好的，提供的可编辑参数内容配置并不多，如果你的自定义需求很多的话使用这个项目前需要谨慎考虑一下

界面：

在线地址：z2586300277.github.io/threejs-edi…

Github: github.com/z2586300277…

项目六：scene-editor

描述：vis-three/scene-editor 是基于 vis-three 框架构建的 —— vis-three 本身是一个封装自 Three.js 的前端 3D 开发框架，用于简化 Web3D 开发

特点：基于vis-three 衍生开发的一个3D编辑器提供了一套较为完整的 Web 3D 场景编辑功能 — 目标是让你即使对 3D 或 Three.js 不熟，也能比较轻松地 “拖／配／编辑” 出一个 3D 场景

注意⚠️：仓库地址的代码是Vue3项目编译打包后的，作者并没有直接提供Vue3项目的源代码，如果有二次开发需求，无法直接性修改源代码

界面：

在线地址：z2586300277.github.io/threejs-edi…

Github: github.com/Shiotsukika…

Gitee:gitee.com/vis-three/s…

项目七： three.js官方编辑器

描述：Three.js（著名的 WebGL / Web 3D 渲染库）自带 / 官方提供的可视化编辑器，接触过three.js的应该都知道吧

特点：3D编辑器的鼻祖了也是唯一一个能和three.js最新版本保持随时同步的编辑器，很多现有的商业项目和开源项目的功能，或多或少都参考了这个项目去实现的

注意⚠️：使用原生js 去实现的，二次开发和扩展功能成本较大

界面：

在线地址：threejs.org/editor/

Github: github.com/mrdoob/thre…

项目八： threejs-3dmodel-edit

描述：一个基于 Three.js + Vue 3 + TypeScript + Pinia 的前端 3D 模型编辑器 / 可视化编辑平台

特点：是一个比较完整、现代、易用的 Web-based 3D 模型编辑器 — 它把 Three.js 的功能通过 Vue / TS / Pinia 封装起来，让非专业 3D 建模背景的人也能比较容易地加载 /编辑 /导出 /展示 3D 模型。基于企业级项目代码开发的标准规范，如果你正在开发自己的第一个企业级Three.js 项目那么这个项目的代码设计思路将会是一个不错的参考

注意⚠️：作者本人的3D开源项目，毛遂自荐一下，哈哈哈哈

界面：

在线地址：threeflowx.cn/open/#/

Github: github.com/zhangbo126/…

Gitee:gitee.com/ZHANG_6666/…

结语

ok以上就是作者本人已知的一些不错的开源3D编辑器合集了，如果你还知道一些好的3D编辑器项目欢迎评论区补充

AntD 6 发布之后，网上很多人都在观望：

“要不要升级？”

“会不会炸？”

“我的项目能不能扛得住？”

其实 AntD 官方已经在文档里把升级路径写得非常清楚，只是稍显简略。

下面我用更真实、更工程化的方式，把 v5 → v6 的升级步骤 做了一次加强版讲解，

让你升级时不至于踩坑。

① 第一步：升级到 v5 最新版本（必须执行）

在升级到 AntD 6 之前，官方强烈建议你先把项目从 v5 升到 v5 最新版本：5.29.1。

为什么？

✔ v5 的最新版本会给出所有废弃 API 的 warning

✔ 不处理这些 warning，到 v6 会直接报错

✔ v5 → v6 是平滑升级路径，只要你处理掉 v5 的 warning，升级 v6 就不会炸

执行命令：

npm install antd@5

装完以后，启动项目，务必一条一条看控制台 warning。

比如：

• 某个 API 将被移除


• 某个 props 已废弃


• 某个组件 v6 即将删除

所有 warning 都处理完，再继续下一步。

这阶段非常关键，等于是在做“升级前全身检查”。

其实你只要用了5的版本基本没啥大问题

② 第二步：确保项目运行在 React 18（或以上）

AntD 6 不再支持 React 17 及以下版本。

AntD 官方的态度非常明确：

“React 17，我们不救了。”

好消息是：绝大多数前端项目早就 React 18 了。

如果你还停留在 React 17，那建议你别升级 AntD，

你升级 React 本身都要做好打仗的准备。

检查你的 package.json：

"react": "^18.x.x",

"react-dom": "^18.x.x"

如果不是，那你真的得升级个 der（官方术语：赶紧升 😅）。

React 17 升到 React 18 已经是必经之路，

Suspense、Concurrent、SSR 都已经进入新阶段，不升会拖累整个项目生态。

③ 第三步：开干！升级到 AntD 6

前面两步做完，你的项目基本已经“具备上 6 条件”了。

现在就可以正式开刀：

npm install --save antd@6

或者你爱用的包管理器：

yarn add antd@6

# or

pnpm add antd@6

# or

npm install antd@latest

安装完成后，你的项目就是 AntD 6 正式用户。

④ 第四步：启动项目，处理残留 warning

升级完成以后，重启项目。

你可能会看到一些：

• 类型定义变动 warning


• 某些行为变更 warning


• 某些组件结构调整提示


• mask blur 带来的视觉差异


• 你自己写的样式被 DOM 改动影响

这些属于正常“升级后适配”。

根据提示处理即可。

建议你重点检查以下区域：

✔ 自定义覆盖类名（AntD 6 DOM 有变化）

✔ Modal、Drawer 的 mask 是否出现模糊效果

✔ Table、Form 是否有类型冲突

✔ 已废弃 API 是否仍然使用

✔ 第三方依赖是否引用了 AntD 内部 class

通常处理 1-2 小时就可以全部解决 （ 不解决也行，能跑就行😉）。

⑤ 最终：你就正式吃上了 AntD 6 的“螃蟹”

完成以上步骤后，你就完成了整个升级链路：

• 清理 v5 废弃 API


• 升到 React 18（如果你的项目还没）


• 升到 AntD 6


• 修复升级后剩余 warning

从此以后：

• 你可以用 Masonry 瀑布流


• 你可以用更快的 Tooltip


• 你可以享受 ZeroRuntime


• 你可以用语义化 DOM 更好写主题


• 你的项目正式进入 2025 年的前端栈

一句话：

你是第一个吃螃蟹的人，但这次螃蟹真的不难吃，而且还挺香，哥们已经升级，满嘴流油了。

效果展示

所有操作均在浏览器进行，先来看看最终效果：

🌐 在线演示: mvp-onlyoffice.vercel.app/

🔗 GitHub仓库: mvp-onlyoffice

基本示例

多实例示例

多tab示例

。。。。。。。。。。

核心功能演示

• ✅ 文档上传：支持本地文件直接上传


• ✅ 实时编辑：流畅的文档编辑体验


• ✅ 格式转换：基于WASM的文档格式转换


• ✅ 导出保存：一键导出编辑后的文档


• ✅ 模式切换：只读/可编辑模式自由切换


• ✅ 多语言支持：中英文界面无缝切换


• ✅ 多实例支持：同时运行多个独立编辑器实例（Word/Excel/PPT）


• ✅ 资源隔离：每个实例独立的图片上传和媒体资源管理

技术架构

核心技术栈

• React 19 + Next.js 15：现代化前端框架


• OnlyOffice SDK：官方JavaScript SDK，提供文档编辑核心能力


• WebAssembly (x2t-wasm)：文档格式转换引擎


• TypeScript：类型安全的开发体验


• EventBus：事件驱动的架构设计


• IndexedDB：WASM文件缓存优化


• EditorManagerFactory：多实例管理器工厂模式

tip: 事实上不依赖于 react，你可以拿到 项目中的 src/onlyoffice-comp ,然后接入到任何系统中去，接入层可以参考 src/app/excel/page.tsx等应用层文件

架构流程图

用户上传文档

    ↓

React组件层

    ↓

EditorManagerFactory (多实例管理器工厂)

    ↓

EditorManager (编辑器管理器)

    ↓

X2T Converter (WASM转换器)

    ↓

OnlyOffice SDK (文档编辑器)

    ↓

EventBus (事件总线)

    ↓

导出/保存文档

WASM文档转换核心流程

转换流程图解

用户选择文件

    ↓

浏览器读取文件

    ↓

WASM虚拟文件系统

    ↓

X2T引擎执行转换

    ↓

生成二进制数据 + 媒体资源

    ↓

OnlyOffice编辑器加载

核心代码实现

// src/onlyoffice-comp/lib/x2t.ts



/**

 * X2T 工具类 - 负责文档转换功能

 */

class X2TConverter {

  private x2tModule: EmscriptenModule | null = null;

  

  // 支持的文件类型映射

  private readonly DOCUMENT_TYPE_MAP: Record<string, DocumentType> = {

    docx: 'word',

    doc: 'word',

    odt: 'word',

    rtf: 'word',

    txt: 'word',

    xlsx: 'cell',

    xls: 'cell',

    ods: 'cell',

    csv: 'cell',

    pptx: 'slide',

    ppt: 'slide',

    odp: 'slide',

  };



  /**

   * 转换文档格式

   */

  async convertDocument(file: File): Promise<ConversionResult> {

    // 初始化WASM模块

    await this.ensureReady();

    

    // 写入虚拟文件系统

    const data = await file.arrayBuffer();

    this.x2tModule!.FS.writeFile('/working/origin', new Uint8Array(data));

    

    // 执行C++编译的转换模块

    this.executeConversion('/working/params.xml');

    

    // 提取转换结果和媒体文件

    return {

      bin: this.x2tModule!.FS.readFile('/working/output.bin'),

      media: this.collectMediaFiles() // 提取图片等资源

    };

  }

}

编辑器管理器：多实例架构设计

项目采用工厂模式管理多个编辑器实例，每个实例都有独立的容器ID和资源管理：

// src/onlyoffice-comp/lib/editor-manager.ts



// EditorManagerFactory - 多实例管理器工厂

class EditorManagerFactory {

  private static instance: EditorManagerFactory;

  private managers: Map<string, EditorManager> = new Map();

  

  // 创建或获取编辑器管理器实例

  create(containerId?: string): EditorManager {

    if (containerId) {

      // 如果已存在，返回现有实例

      if (this.managers.has(containerId)) {

        return this.managers.get(containerId)!;

      }

      // 创建新实例

      const manager = new EditorManager(containerId);

      this.managers.set(containerId, manager);

      return manager;

    }

    // 创建默认实例

    return this.createDefault();

  }

  

  // 获取指定容器ID的实例

  get(containerId: string): EditorManager | undefined {

    return this.managers.get(containerId);

  }

  

  // 销毁指定实例

  destroy(containerId: string): void {

    const manager = this.managers.get(containerId);

    if (manager) {

      manager.destroy();

      this.managers.delete(containerId);

    }

  }

  

  // 销毁所有实例

  destroyAll(): void {

    this.managers.forEach(manager => manager.destroy());

    this.managers.clear();

  }

}



// EditorManager - 单个编辑器管理器

class EditorManager {

  private instanceId: string;

  private containerId: string;

  private editor: DocEditor | null = null;

  

  constructor(containerId?: string) {

    this.instanceId = nanoid(); // 生成唯一实例ID

    this.containerId = containerId || `onlyoffice-editor-${this.instanceId}`;

  }

  

  // 获取实例ID

  getInstanceId(): string {

    return this.instanceId;

  }

  

  // 获取容器ID

  getContainerId(): string {

    return this.containerId;

  }

  

  // 导出文档（事件驱动）

  async export(): Promise<SaveDocumentData> {

    const editor = this.get();

    if (!editor) {

      throw new Error('Editor not available');

    }

    

    // 触发保存

    (editor as any).downloadAs();

    

    // 等待保存事件

    const result = await onlyofficeEventbus.waitFor(

      ONLYOFFICE_EVENT_KEYS.SAVE_DOCUMENT, 

      10000

    );

    

    return result;

  }

  

  // 设置只读模式

  async setReadOnly(readOnly: boolean): Promise<void> {

    // 实现逻辑...

  }

}

事件驱动架构：EventBus解耦设计

项目采用事件总线机制，实现组件间的松耦合通信：

// src/onlyoffice-comp/lib/eventbus.ts



class EventBus {

  private listeners: Map<EventKey, Array<(data: any) => void>> = new Map();

  

  // 监听事件

  on<K extends EventKey>(key: K, callback: (data: EventDataMap[K]) => void): void {

    if (!this.listeners.has(key)) {

      this.listeners.set(key, []);

    }

    this.listeners.get(key)!.push(callback);

  }

  

  // 等待事件触发（返回 Promise）

  waitFor<K extends EventKey>(key: K, timeout?: number): Promise<EventDataMap[K]> {

    return new Promise((resolve, reject) => {

      const timeoutId = timeout

        ? setTimeout(() => {

            this.off(key, handleEvent);

            reject(new Error(`Event ${key} timeout after ${timeout}ms`));

          }, timeout)

        : null;



      const handleEvent = (data: EventDataMap[K]) => {

        if (timeoutId) clearTimeout(timeoutId);

        this.off(key, handleEvent);

        resolve(data);

      };



      this.on(key, handleEvent);

    });

  }

}

支持的事件类型

• saveDocument - 文档保存完成事件


• documentReady - 文档加载就绪事件


• loadingChange - 加载状态变化事件

核心功能特性

1. 多实例支持

支持同时创建和管理多个独立的编辑器实例，每个实例都有独立的容器ID和资源管理：

import { createEditorView } from '@/onlyoffice-comp/lib/x2t';

import { editorManagerFactory } from '@/onlyoffice-comp/lib/editor-manager';



// 创建第一个编辑器实例

const manager1 = await createEditorView({

  isNew: true,

  fileName: 'Document1.docx',

  containerId: 'editor-1', // 指定容器ID

});



// 创建第二个编辑器实例

const manager2 = await createEditorView({

  isNew: true,

  fileName: 'Document2.xlsx',

  containerId: 'editor-2', // 不同的容器ID

});



// 分别操作不同实例

const result1 = await manager1.export();

const result2 = await manager2.export();



// 销毁指定实例

editorManagerFactory.destroy('editor-1');



// 销毁所有实例

editorManagerFactory.destroyAll();

关键特性：

• 容器隔离：每个实例使用唯一的容器ID，通过 data-onlyoffice-container-id 属性精确定位


• 资源隔离：每个实例管理独立的媒体资源映射，图片上传不会相互干扰


• 独立事件处理：每个实例通过 createWriteFileHandler(manager) 创建独立的图片上传处理函数

2. 国际化支持

项目内置多语言支持，可自由切换中英文界面。在多实例场景下，切换语言会重新创建所有编辑器实例：

// 切换语言（多实例场景）

const handleLanguageSwitch = async () => {

  const newLang = currentLang === 'zh' ? 'en' : 'zh';

  setCurrentLang(newLang);

  

  // 保存每个编辑器实例的文档信息

  const editorDocuments = {

    manager1: { fileName: 'Doc1.docx', file: file1 },

    manager2: { fileName: 'Doc2.xlsx', file: file2 },

  };

  

  // 重新创建所有编辑器以应用新语言

  if (editorDocuments.manager1) {

    await createEditorView({

      fileName: editorDocuments.manager1.fileName,

      file: editorDocuments.manager1.file,

      containerId: 'editor-1',

      lang: newLang,

    });

  }

  

  if (editorDocuments.manager2) {

    await createEditorView({

      fileName: editorDocuments.manager2.fileName,

      file: editorDocuments.manager2.file,

      containerId: 'editor-2',

      lang: newLang,

    });

  }

};

3. 导入导出功能

完整的文档导入导出能力：

// 导出文档

const result = await editorManager.export();

// result 包含: { fileName, fileType, binData, media }



// 转换并下载

const buffer = await convertBinToDocument(

  result.binData, 

  result.fileName,

  FILE_TYPE.XLSX, 

  result.media

);



const blob = new Blob([buffer.data], {

  type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'

});

// 执行下载操作

4. 只读/可编辑模式切换

灵活的权限控制，支持动态切换编辑模式：

// 设置为只读模式

await editorManager.setReadOnly(true);



// 切换为可编辑模式

await editorManager.setReadOnly(false);



// 查询当前模式

const isReadOnly = editorManager.getReadOnly();

实现原理：

• 从只读切换到可编辑：重新创建编辑器实例


• 从可编辑切换到只读：使用processRightsChange命令

5. IndexedDB缓存优化

使用IndexedDB缓存WASM文件，大幅提升二次加载速度：

// 拦截 fetch，缓存 WASM 文件到 IndexedDB

private interceptFetch(): void {

  const originalFetch = window.fetch;

  

  window.fetch = async function(input: RequestInfo | URL): Promise<Response> {

    // 先尝试从缓存读取

    const cached = await this.getCachedWasm(url);

    if (cached) {

      return new Response(cached, {

        headers: { 'Content-Type': 'application/wasm' }

      });

    }

    

    // 缓存未命中，从网络加载并缓存

    const response = await originalFetch(input);

    const arrayBuffer = await response.arrayBuffer();

    await this.cacheWasm(url, arrayBuffer);

    

    return response;

  };

}

使用示例

基本使用（单实例）

import { createEditorView } from '@/onlyoffice-comp/lib/x2t';

import { editorManagerFactory } from '@/onlyoffice-comp/lib/editor-manager';



// 创建编辑器视图（使用默认实例）

await createEditorView({

  file: fileObject,        // File 对象（可选）

  fileName: 'document.xlsx', // 文件名

  isNew: false,            // 是否新建文档

  readOnly: false,        // 是否只读

  lang: 'zh',             // 界面语言

});



// 获取默认实例并导出文档

const defaultManager = editorManagerFactory.getDefault();

const result = await defaultManager.export();

console.log('导出成功:', result);

多实例使用

import { createEditorView } from '@/onlyoffice-comp/lib/x2t';

import { editorManagerFactory } from '@/onlyoffice-comp/lib/editor-manager';



// 创建多个编辑器实例

const manager1 = await createEditorView({

  isNew: true,

  fileName: 'Doc1.docx',

  containerId: 'editor-1',

  lang: 'zh',

});



const manager2 = await createEditorView({

  isNew: true,

  fileName: 'Doc2.xlsx',

  containerId: 'editor-2',

  lang: 'zh',

});



const manager3 = await createEditorView({

  isNew: true,

  fileName: 'Doc3.pptx',

  containerId: 'editor-3',

  lang: 'zh',

});



// 分别导出

const result1 = await manager1.export();

const result2 = await manager2.export();

const result3 = await manager3.export();

React组件集成（多实例）

// src/app/multi/page.tsx

function MultiInstancePageContent() {

  const [managers, setManagers] = useState({

    manager1: null,

    manager2: null,

    manager3: null,

  });

  

  // 保存文档信息，用于语言切换

  const [editorDocuments, setEditorDocuments] = useState({

    manager1: null,

    manager2: null,

    manager3: null,

  });

  

  // 创建编辑器

  const handleView = async (editorKey: string, fileName: string, file?: File) => {

    const containerId = `editor-${editorKey.replace('manager', '')}`;

    

    const manager = await createEditorView({

      file,

      fileName,

      isNew: !file,

      containerId, // 指定容器ID

      lang: getOnlyOfficeLang(),

    });

    

    setManagers(prev => ({

      ...prev,

      [editorKey]: manager,

    }));

    

    // 保存文档信息

    setEditorDocuments(prev => ({

      ...prev,

      [editorKey]: { fileName, file: file || undefined },

    }));

  };

  

  // 语言切换（重新创建所有编辑器）

  const handleLanguageSwitch = async () => {

    const newLang = currentLang === 'zh' ? 'en' : 'zh';

    

    // 重新创建所有编辑器

    if (editorDocuments.manager1) {

      const doc = editorDocuments.manager1;

      await handleView('manager1', doc.fileName, doc.file);

    }

    // ... 其他实例

  };

  

  return (

    <div className="grid grid-cols-3 gap-4">

      {/* 编辑器容器 - 使用 data-onlyoffice-container-id 属性 */}

      <div className="onlyoffice-container" data-onlyoffice-container-id="editor-1">

        <div id="editor-1" className="absolute inset-0" />

      </div>

      <div className="onlyoffice-container" data-onlyoffice-container-id="editor-2">

        <div id="editor-2" className="absolute inset-0" />

      </div>

      <div className="onlyoffice-container" data-onlyoffice-container-id="editor-3">

        <div id="editor-3" className="absolute inset-0" />

      </div>

    </div>

  );

}

项目结构

mvp-onlyoffice/

├── src/

│   ├── app/              # Next.js 应用页面

│   │   ├── excel/        # Excel 编辑器页面

│   │   ├── docs/         # Word 编辑器页面

│   │   ├── ppt/          # PowerPoint 编辑器页面

│   │   └── multi/        # 多实例演示页面

│   ├── onlyoffice-comp/  # OnlyOffice 组件库

│   │   └── lib/

│   │       ├── editor-manager.ts  # 编辑器管理器（支持多实例）

│   │       ├── x2t.ts             # 文档转换模块

│   │       ├── eventbus.ts        # 事件总线

│   │       └── utils.ts            # 工具函数

│   └── components/       # 通用组件

├── public/               # 静态资源

│   ├── web-apps/         # OnlyOffice Web 应用资源

│   ├── sdkjs/            # OnlyOffice SDK 资源

│   └── wasm/             # WebAssembly 转换器

└── onlyoffice-x2t-wasm/  # x2t-wasm 源码

部署方案

Vercel一键部署

项目已配置静态导出，可直接部署到Vercel：

# 安装依赖

npm install



# 构建项目

npm run build



# Vercel 会自动检测并部署

🌐 在线演示: mvp-onlyoffice.vercel.app/

静态文件部署

项目支持静态导出，构建后的文件可部署到任何静态托管服务：

# 构建静态文件

npm run build



# 输出目录: out/

# 可直接部署到 GitHub Pages、Netlify、Nginx 等

技术优势总结

技术原理

使用x2t-wasm替代OnlyOffice服务

传统OnlyOffice集成需要：

本方案通过WASM技术：

多实例架构设计

• 工厂模式：使用 EditorManagerFactory 统一管理多个编辑器实例


• 容器隔离：每个实例使用唯一的容器ID，通过 data-onlyoffice-container-id 属性精确定位


• 资源隔离：每个实例管理独立的媒体资源映射，图片上传通过独立的 writeFile 处理函数


• 事件隔离：虽然使用全局 EventBus，但每个实例的事件处理函数是独立的

参考项目

• Qihoo360/se-office - se-office扩展，提供基于开放标准的全功能办公生产力套件


• cryptpad/onlyoffice-x2t-wasm - CryptPad WebAssembly文件转换工具


• ranuts/document - 参考静态资源实现

开源地址

🔗 GitHub仓库: mvp-onlyoffice

总结

本项目提供了一个完整的纯前端OnlyOffice集成方案，通过WASM技术实现了文档格式转换的本地化，结合React和OnlyOffice SDK，打造了一个功能完善、性能优秀的文档编辑器。

核心亮点：

• 🚀 纯前端架构，无需后端服务


• 🔒 数据完全本地化，保护隐私安全


• ⚡ 基于WASM的高性能转换


• 🌏 内置国际化支持


• 📦 支持导入导出


• 🔐 灵活的权限控制


• 🎯 多实例支持：同时运行多个独立编辑器，资源完全隔离

欢迎Star和Fork，一起推动前端Office编辑技术的发展！

相关阅读：

• OnlyOffice API 文档


• WebAssembly 官方文档


• Next.js 静态导出

分享 20 个 2025 年依旧「少人知道、却能立竿见影」的原生 API。

收藏 = 省下一个工具库 + 少写 100 行代码！

1. ResizeObserver

精准监听任意 DOM 宽高变化，图表自适应、虚拟滚动必备。

new ResizeObserver(([e]) => chart.resize(e.contentRect.width))

  .observe(chartDom);

2. IntersectionObserver

检测元素进出视口，一次搞定懒加载 + 曝光埋点，性能零损耗。

new IntersectionObserver(entrieList =>

  entrieList.forEach(e => e.isIntersecting && loadImg(e.target))

).observe(img);

3. Page Visibility

侦测标签页隐藏，自动暂停视频、停止轮询，移动端省电神器。

document.addEventListener('visibilitychange', () =>

  document.hidden ? video.pause() : video.play()

);

4. Web Share

一键唤起系统分享面板，直达微信、微博、Telegram，需 HTTPS。

navigator.share?.({ title: '好文', url: location.href });

5. Wake Lock

锁定屏幕常亮，直播、PPT、阅读器不再自动息屏。

await navigator.wakeLock.request('screen');

6. Broadcast Channel

同域标签实时广播消息，登录态秒同步，告别 localStorage 轮询。

const bc = new BroadcastChannel('auth');

bc.onmessage = () => location.reload();

7. PerformanceObserver

无侵入采集 FCP、LCP、FID，一行代码完成前端性能监控。

new PerformanceObserver(list =>

  list.getEntries().forEach(sendMetric)

).observe({ type: 'largest-contentful-paint', buffered: true });

8. requestIdleCallback

把埋点、日志丢进浏览器空闲时间，首帧零阻塞。

requestIdleCallback(() => sendBeacon('/log', data));

9. scheduler.postTask

原生优先级任务队列，低优任务后台跑，主线程丝滑。

scheduler.postTask(() => sendBeacon('/log', data), { priority: 'background' });

10. AbortController

随时取消 fetch，路由切换不再旧请求竞态，兼容 100%。

const ac = new AbortController();

fetch(url, { signal: ac.signal });

ac.abort();

11. ReadableStream

分段读取响应流，边下载边渲染，大文件内存零爆涨。

const reader = response.body.getReader();

while (true) {

  const { done, value } = await reader.read();

  if (done) break;

  appendChunk(value);

}

12. WritableStream

逐块写入磁盘或网络，实时保存草稿、上传大文件更稳。

const writer = stream.writable.getWriter();

await writer.write(chunk);

13. Background Fetch

PWA 后台静默下载，断网恢复继续，课程视频提前缓存。

await registration.backgroundFetch.fetch('video', ['/course.mp4']);

14. File System Access

读写本地真实文件，需用户授权，Web IDE 即开即用。

const [fh] = await showOpenFilePicker();

editor.value = await (await fh.getFile()).text();

15. Clipboard

异步读写剪贴板，无需第三方库，HTTPS 环境安全复制。

await navigator.clipboard.writeText('邀请码 9527');

16. URLSearchParams

解析、修改、构造 URL 查询串，告别手写正则。

const p = new URLSearchParams(location.search);

p.set('page', 2);

history.replaceState({}, '', `?${p}`);

17. structuredClone

深拷贝对象、数组、Map、Date，循环引用也能完美复制。

const copy = structuredClone(state);

18. Intl.NumberFormat

千分位、货币、百分比一次格式化，国际化零配置。

new Intl.NumberFormat('zh-CN', { style: 'currency', currency: 'CNY' })

  .format(1234567); // ¥1,234,567.00

19. EyeDropper

浏览器级吸管工具，像素级取色，设计系统直接调用。

const { sRGBHex } = await new EyeDropper().open();

20. WebCodecs

原生硬解码音视频，4K 60 帧流畅播放，CPU 占用直降。

const decoder = new VideoDecoder({

  output: frame => ctx.drawImage(frame, 0, 0),

  error: console.error

});

decoder.configure({ codec: 'vp09.00.10.08' });

写给小公司前端的 UI 规范

大部分小公司前端开发是不是都会有个困扰，一天到晚做的都是后台管理系统，而且百分之 80 都是表格的增删改查，导致领导觉得前端简单的很，所以连个 UI 都没有，但是每次写完页面又被老大吐槽没有审美，而且如果整个系统多个人开发，每个的风格都不一样，导致整个系统看起来很乱，想要统一又不知道从何入手，所以今天我给大家分享一下我们团队的针对后台管理系统的 UI 规范，希望对大家有帮助。

叠个甲：这个只是我们遵循的规范，因为交互和设计这种东西每个人的感受不一样，你觉得你这个规范我觉得不合理，没关系，你可以按照自己的想法来也可以，只要遵循一个原则，那就是整个系统风格保持一致性即可，所以这个规范仅供参考。

大家都知道后台管理主要就是几部分：表格、表单、弹窗，所以我们的 UI 规范也是围绕这三部分来的。

表格

自适应形式

• 最小页面宽度+自适应的综合运用，最小自适应页面宽度 1366px(小于此宽度则不再自适应，超出页面的内容使用滚动条查看)，单元格字段过长一行展示不下时，不换行并出现省略号，鼠标移入，提示框显示完整字段。

表格内行高

表格内对齐方式

• 表头和文字内容：采用左对齐


• 表头和普通数字：采用左对齐


• 表头和具有比较场景的数字： 采用右对齐


• 表头和操作项： 采用左对齐

分页器

分页器元素：

• 数据总量、单页面展示数量、翻页部分

对齐方式：

• 数据总量左对齐，单页面展示数量&翻页部分右对齐(依次顺序为数据总量、单页面展示数量、翻页部分)

分页器位置:

• 表格为页面全部内容时，表格超出一页分页器固定及底，表格未超出一页分页器跟随表格下方


• 表格仅为页面部分内容时，分页器跟随表格下方

表格操作区

按钮类型:

• 新增数据类按钮 &面向已有数据类的操作按钮(包含可合并类操作按钮)。

对齐方式:

• 操作区居右，主按钮居右。

视觉样式:

• 新增数据类按钮样式-【文字+主色底】或【文字+图标+主色底文字+中性色线框】


• 面向已有数据类的操作按钮样式-【文字+主色底】或【文字+图标+主色底文字+中性色线框】

按钮个数：

• 小于等于 4 个全部展示


• 大于四个时候，最后一个按钮为【更多】按钮，点击【更多】按钮后，下拉展示全部按钮

表格筛选区域

• 一行最多四个筛选条件，不超过四个的时候查询按钮和重置按钮跟在筛选项后


• 超过四个筛选条件时，出现【展示更多】按钮，点击【展示更多】按钮后，下拉展示全部筛选条件，【展示更多】变成【收起更多】按钮


• 如果是时间范围 比如开始时间和结束时间 他独占两个筛选项


• 默认 label 最多四个字 建议两个字或者四个字


• 筛选项的宽度建议 200px

表格滑块

表格为页面全部内容时:

• 内容无超出:滚动不出现


• 横向内容有超出:表格内横向滚动条，且默认固定操作和标题列


• 纵向内容有超出:页面滚动条，表头到达页面顶部，吸顶固定

表格仅为页面部分内容时:

• 表格区最大高度为 10 行数据+分页器，当 10 行数据+分内器超出页面容器时，表格区最大高度将限制为页面容器的 90%


• 内容无超出:滚动不出现


• 横向内容有超出:表格内横向滚动条，且默认固定操作项和标题列


• 纵向内容有超出:表格内滚动条，固定表头&分页器

表单

表单项 Label 与控件的对齐方式&必填标识

• 表单项 Label 和控件对齐方式


• 当表单项 Label 过长(6 个中文字符以上)，采用顶对齐方式布局。当表单项 Label 在 6 个中文字符以内，使用右对齐方式布局。
  对齐布局;


• 当表单项在 15 个以下时，采用单列布局方式，当表单项在 15 个以上时，采用多列顶对齐方式布局。


• 表单项 Label 和必填标识对齐方式


• 表单项 Label 右对齐布局时，必填示识放在标题前;


• 表单项 Label 顶对齐布局时，必填示识放在标题后;

提交/取消操作按钮位置&对齐方式

操作按钮统一采用左对齐的方式，表单域未超出一屏时跟在表单项下方，若超出一屏则固定吸底。

表单页自适应方式&lnput 框长度

• 当只有单列时，表单域左对齐且定宽 、输入框&选择框长度为 480px、文本框长度为 640px，支持表单项 Label 顶对齐和右对齐。


• 当出现双列时，表单域左对齐，表单域宽度为页面容器宽度的 80%，自适应布局，仅支持表单项 Label 顶对齐。


• 当出现三列时，表单域占满整个页面容器，自适应布局，仅支持表单项 Label 顶对齐。

弹窗

弹窗尺寸:

• 在未达到弹窗最大尺寸(弹窗最大宽高<页面宽高的 80%)时，弾窗尺寸由内容决定，弹窗内容距离弹窗边距 20px。


• 滚动条出现在弹窗上，不要出现在整个页面上

弹窗位置:

• 页面居中。

操作按钮位置:

• 固定在弹窗底部，整体居左，主按钮在左侧。

总 结

我之前也在小公司待过，能充分了解小公司的现状，别说 UI 了，有的直接是连前端都不要，管你什么 UI，时间长了就麻木了，想进步却找不到方向，所以希望这个规范能帮助到你，让你在 UI 规范方面有所提升。
因为只是我们总结的一套规范，其实还有很多不足，你完全可以在这个基础上，根据自己的需求，进行修改和优化，比如你觉得表格删除按钮必须是红色，弹窗的按钮放在右下角更合理，不喜欢筛选项有什么展开收缩等等这些你都可以根据自己的需求进行修改，还是那句话，整个系统风格保持统一。
如果大家有自己团队的规范，也可以评论区发出来共享一下大家相互学习一下。

在网页开发中，图片处理是每个前端开发者都会遇到的基础任务。面对 <img> 和 <picture> 这两个标签，很多人存在误解：要么认为它们是互相替代的关系，要么在不合适的场景下使用了复杂的解决方案。今天，我们来彻底理清这两个标签的真正用途。

<img> 标签

<img> 是 HTML 中最基础且强大的图片标签，但它远比很多人想象的要智能。

基本语法：

<img src="image.jpg" alt="图片描述">

核心属性：

• src：图片路径（必需）


• alt：替代文本（无障碍必需）


• srcset：提供多分辨率图片源


• sizes：定义图片显示尺寸


• loading：懒加载控制

<img> 的响应式能力被低估了

很多人认为 <img> 不具备响应式能力，这是错误的认知：

<img 

  src="image-800w.jpg"

  srcset="image-320w.jpg 320w,

          image-480w.jpg 480w,

          image-800w.jpg 800w"

  sizes="(max-width: 600px) 100vw,

         (max-width: 1200px) 50vw,

         33vw"

  alt="响应式图片示例"

>

这种写法的优势：

• 浏览器自动选择最适合当前屏幕分辨率的图片


• 根据视口大小动态调整加载的图片尺寸


• 代码简洁，性能优秀

<picture> 标签

<picture> 不是为了替代 <img>，而是为了解决 <img> 无法处理的特定场景。

<picture> 解决的三大核心问题

1. 艺术指导（Art Direction）
在不同设备上显示不同构图或裁剪的图片：

<picture>

  <!-- 桌面端：宽屏全景 -->

  <source media="(min-width: 1200px)" srcset="hero-desktop.jpg">

  <!-- 平板端：适中裁剪 -->

  <source media="(min-width: 768px)" srcset="hero-tablet.jpg">

  <!-- 移动端：竖版特写 -->

  <img src="hero-mobile.jpg" alt="产品展示">

</picture>

2. 现代格式降级
优先使用高效格式，同时兼容老旧浏览器：

<picture>

  <source type="image/avif" srcset="image.avif">

  <source type="image/webp" srcset="image.webp">

  <img src="image.jpg" alt="格式优化示例">

</picture>

3. 复杂条件组合
同时考虑屏幕尺寸和图片格式：

<picture>

  <!-- 大屏 + AVIF -->

  <source media="(min-width: 1200px)" type="image/avif" srcset="large.avif">

  <!-- 大屏 + WebP -->

  <source media="(min-width: 1200px)" type="image/webp" srcset="large.webp">

  <!-- 大屏降级 -->

  <source media="(min-width: 1200px)" srcset="large.jpg">

  

  <!-- 移动端方案 -->

  <img src="small.jpg" alt="复杂条件图片">

</picture>

关键区别与选择指南

常见误区纠正

误区一：<picture> 用于响应式图片

• 事实： <img> 配合 srcset 和 sizes 已经能处理大多数响应式需求


• 真相： <picture> 主要用于艺术指导和格式降级

误区二：<picture> 更现代，应该优先使用

• 事实： 在不需要艺术指导或格式降级的场景下，<img> 是更好的选择


• 真相： 合适的工具用在合适的场景才是最佳实践

误区三：响应式图片一定要用 <picture>

• 事实： 很多响应式场景用 <img> + srcset 更合适


• 真相： 评估需求，选择最简单的解决方案

场景分析

应该使用 <img> 的场景

网站Logo：

<img src="logo.svg" alt="公司Logo" width="120" height="60">

用户头像：

<img 

  src="avatar.jpg"

  srcset="avatar.jpg 1x, avatar@2x.jpg 2x"

  alt="用户头像"

  width="80" 

  height="80"

>

文章配图：

<img 

  src="article-image.jpg"

  srcset="article-image-600w.jpg 600w,

          article-image-1200w.jpg 1200w"

  sizes="(max-width: 768px) 100vw, 600px"

  alt="文章插图"

  loading="lazy"

>

应该使用 <picture> 的场景

英雄横幅（不同裁剪）：

<picture>

  <source media="(min-width: 1024px)" srcset="hero-wide.jpg">

  <source media="(min-width: 768px)" srcset="hero-square.jpg">

  <img src="hero-mobile.jpg" alt="产品横幅" loading="eager">

</picture>

产品展示（格式优化）：

<picture>

  <source type="image/avif" srcset="product.avif">

  <source type="image/webp" srcset="product.webp">

  <img src="product.jpg" alt="产品详情" loading="lazy">

</picture>

最佳实践

1. 始终遵循的规则

<!-- 正确：始终提供 alt 属性 -->

<img src="photo.jpg" alt="描述文本">



<!-- 错误：缺少 alt 属性 -->

<img src="photo.jpg">



<!-- 装饰性图片使用空 alt -->

<img src="decoration.jpg" alt="">

2. 性能优化策略

<!-- 优先加载关键图片 -->

<img src="hero.jpg" alt="重要图片" loading="eager" fetchpriority="high">



<!-- 非关键图片延迟加载 -->

<img src="content-image.jpg" alt="内容图片" loading="lazy">



<!-- 指定尺寸避免布局偏移 -->

<img src="product.jpg" alt="商品" width="400" height="300">

3. 现代图片格式策略

<picture>

  <!-- 优先使用AVIF，压缩率最高 -->

  <source type="image/avif" srcset="image.avif">

  <!-- 其次WebP，广泛支持 -->

  <source type="image/webp" srcset="image.webp">

  <!-- 最终回退到JPEG -->

  <img src="image.jpg" alt="现代格式示例">

</picture>

总结

<img> 和 <picture> 不是竞争关系，而是互补的工具：

• <img>：处理大多数日常图片需求，特别是分辨率适配


• <picture>：解决特定复杂场景，如艺术指导和格式降级

核心建议：

掌握这两个标签的正确用法，你就能在各种场景下都做出最合适的技术选择，既保证用户体验，又避免过度工程化。

希望这篇指南能帮助你彻底理解这两个重要的HTML标签！

本文首发于公众号：程序员刘大华，专注分享前后端开发的实战笔记。关注我，少走弯路，一起进步！

📌往期精彩

《SpringBoot+Vue3 整合 SSE 实现实时消息推送》

《这20条SQL优化方案，让你的数据库查询速度提升10倍》

《SpringBoot 动态菜单权限系统设计的企业级解决方案》

《Vue3和Vue2的核心区别？很多开发者都没完全搞懂的10个细节》

上周，JavaScript 语言的掌舵者们齐聚东京。在 Sony Interactive Entertainment 的主持下，Ecma 国际 TC39 委员会召开了第 104 次全体会议，一系列围绕 迭代器（Iterator） 和 Promise 的提案取得了重要进展。这些新特性将让 JavaScript 开发者写出更简洁、更函数式的代码。

让我们一起来看看这些即将改变你编码方式的新特性。

科普：TC39 与提案流程

在深入了解新特性之前，我们先来快速了解一下它们背后的组织和流程。

TC39 是什么？

TC39 (Technical Committee 39) 是 Ecma International 旗下的技术委员会，专门负责 ECMAScript 标准（即 JavaScript 的规范）的制定和维护。其成员由主流浏览器厂商（如 Google, Mozilla, Apple, Microsoft）以及其他对 Web 技术有影响力的科技公司和专家组成。

提案如何成为标准？

一个新特性从提出到最终进入标准，通常需要经历 5 个阶段（The TC39 Process）：

• Stage 0 (Strawman - 稻草人): 任何想法或建议，用于开启讨论。


• Stage 1 (Proposal - 提案): 确定问题和解决方案，展示潜在的 API 形式。


• Stage 2 (Draft - 草稿): 具体的语法和语义描述，此时特性已基本定型。


• Stage 3 (Candidate - 候选): 规范文本已完成，需要浏览器厂商的实现反馈和用户测试。


• Stage 4 (Finished - 完成): 至少有两个独立的浏览器实现并通过了测试，准备纳入下一版 ECMAScript 标准。

大概需要多久？

这个过程没有固定的时间表，取决于提案的复杂度和争议程度：

• 简单特性：可能在 1-2 年内走完流程。


• 复杂特性：可能需要在 Stage 2 或 Stage 3 停留数年（例如 Temporal 提案）。

通常来说，一旦提案进入 Stage 3，就意味着它极有可能在不久的将来成为标准的一部分，各大浏览器也会开始逐步支持。

1. Iterator Sequencing（迭代器序列化）— Stage 3

提案地址: proposal-iterator-sequencing

解决什么问题？

你是否曾经需要把多个迭代器"串联"起来，当作一个来用？在以前，你得用生成器函数配合 yield* 来实现：

let lows = Iterator.from([0, 1, 2, 3]);

let highs = Iterator.from([6, 7, 8, 9]);

​

// 以前的写法，略显繁琐

let combined = function* () {

  yield* lows;

  yield* highs;

}();

​

Array.from(combined); // [0, 1, 2, 3, 6, 7, 8, 9]

新写法

现在只需一行：

let combined = Iterator.concat(lows, highs);

Array.from(combined); // [0, 1, 2, 3, 6, 7, 8, 9]

​

// 还可以在中间插入其他值

let digits = Iterator.concat(lows, [4, 5], highs);

Array.from(digits); // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

Iterator.concat() 接受多个可迭代对象，惰性地按顺序产出所有值。这不仅代码更简洁，而且因为是惰性求值，处理大数据集时内存效率也更高。

2. Await Dictionary of Promises（Promise 字典等待）— Stage 1

提案地址: proposal-await-dictionary

解决什么问题？

当你需要并发等待多个 Promise 时，Promise.all 返回的是数组，你得靠下标来取值：

const [shape, color, mass] = await Promise.all([

  getShape(),

  getColor(),

  getMass(),

]);

// 顺序错了？很容易出 bug

新写法

使用 Promise.allKeyed()，用对象的键来命名你的结果：

const { shape, color, mass } = await Promise.allKeyed({

  shape: getShape(),

  color: getColor(),

  mass: getMass(),

});

// 再也不用担心顺序问题了！

该提案还支持 Promise.allSettledKeyed()，用于处理可能失败的场景：

const results = await Promise.allSettledKeyed({

  shape: getShape(),

  color: getColor(),

  mass: getMass(),

});

​

if (results.shape.status === "fulfilled") {

  console.log(results.shape.value);

} else {

  console.error(results.shape.reason);

}

这个 API 设计有意与 Iterator.zipKeyed() 保持一致，体现了 TC39 在语言设计上的系统性思考。

3. Joint Iteration（联合迭代）— Stage 2.7

提案地址: proposal-joint-iteration

解决什么问题？

Python 开发者对 zip() 函数再熟悉不过了——它能把多个序列"拉链式"地组合在一起。JavaScript 一直缺少这个功能。

新写法

Iterator.zip() 和 Iterator.zipKeyed() 填补了这个空白：

// 位置对应的组合

Array.from(Iterator.zip([

  [0, 1, 2],

  [3, 4, 5],

]))

// 结果: [[0, 3], [1, 4], [2, 5]]

​

// 用键名组合

Iterator.zipKeyed({

  a: [0, 1, 2],

  b: [3, 4, 5, 6],

  c: [7, 8, 9],

}).toArray()

// 结果: [

//   { a: 0, b: 3, c: 7 },

//   { a: 1, b: 4, c: 8 },

//   { a: 2, b: 5, c: 9 }

// ]

还支持三种模式来处理长度不等的迭代器：

• mode: 'shortest'（默认）：最短的迭代器耗尽时停止


• mode: 'longest'：最长的迭代器耗尽时停止，可以指定填充值


• mode: 'strict'：如果长度不等则抛出错误

Iterator.zipKeyed({

  a: [0, 1, 2],

  b: [3, 4, 5, 6],

  c: [7, 8, 9],

}, {

  mode: 'longest',

  padding: { c: 10 },

}).toArray()

// 结果包含: { a: undefined, b: 6, c: 10 }

4. Iterator Join（迭代器连接）— 新提案

提案地址: proposal-iterator-join

解决什么问题？

Array.prototype.join() 能把数组元素用分隔符连接成字符串。但如果你有一个迭代器呢？现在你得先转成数组：

myIterator.toArray().join(', ') // 先全部加载到内存

新写法

Iterator.prototype.join() 让你直接在迭代器上操作：

Iterator.from(['a', 'b', 'c']).join(', ')

// 结果: "a, b, c"

这对于处理大型或无限序列（只取部分）时特别有用，避免了不必要的内存分配。

5. Typed Array Find Within（类型数组范围查找）

解决什么问题？

现有的 TypedArray.prototype.indexOf() 只能从数组开头或指定位置向后搜索。当你需要在特定范围内查找时，现有 API 不够灵活。

新能力

这个提案为 TypedArray 添加了在指定范围内进行查找的能力，让二进制数据处理更加高效。这对于处理音视频数据、WebGL 缓冲区、以及其他需要精确控制搜索范围的场景非常有用。

迭代器生态的完善

如果你一直关注 TC39 的动态，你会发现这次会议推进的提案有一个共同主题：完善 JavaScript 的迭代器生态。

参考链接：

• TC39 GitHub


• TC39 Proposals 追踪


• TC39 会议议程

在前端开发中，网页截图是个常用功能。从前，html2canvas 是大家的常客，但随着网页越来越复杂，它的性能问题也逐渐暴露，速度慢、占资源，用户体验不尽如人意。

好在，现在有了 SnapDOM，一款性能超棒、还原度超高的截图新秀，能完美替代 html2canvas，让截图不再是麻烦事。

什么是 SnapDOM

SnapDOM 就是一个专门用来给网页元素截图的工具。

它能把 HTML 元素快速又准确地存成各种图片格式，像 SVG、PNG、JPG、WebP 等等，还支持导出为 Canvas 元素。

它最厉害的地方在于，能把网页上的各种复杂元素，比如 CSS 样式、伪元素、Shadow DOM、内嵌字体、背景图片，甚至是动态效果的当前状态，都原原本本地截下来，跟直接看网页没啥两样。

SnapDOM 优势

快得飞起

测试数据显示，在不同场景下，SnapDOM 都把 html2canvas 和 dom-to-image 这俩老前辈远远甩在身后。

尤其在超大元素（4000×2000）截图时，速度是 html2canvas 的 93.31 倍，比 dom-to-image 快了 133.12 倍。这速度，简直就像坐火箭。

还原度超高

SnapDOM 截图出来的效果，跟在网页上看到的一模一样。

各种复杂的 CSS 样式、伪元素、Shadow DOM、内嵌字体、背景图片，还有动态效果的当前状态，都能精准还原。

无论是简单的元素，还是复杂的网页布局，它都能轻松拿捏。

格式任你选

不管你是想要矢量图 SVG，还是常用的 PNG、JPG，或者现代化的 WebP，又或者是需要进一步处理的 Canvas 元素，SnapDOM 都能满足你。

多种格式，任你挑选，适配各种需求。

三、怎么用 SnapDOM

安装

SnapDOM 的安装超简单，有好几种方式：

用 NPM 或 Yarn：在命令行里输

# npm

npm i @zumer/snapdom



# yarn

yarn add @zumer/snapdom

就能装好。

用 CDN 在 HTML 文件里加一行:

<script src="https://unpkg.com/@zumer/snapdom@latest/dist/snapdom.min.js"></script>

直接就能用。

要是项目里用的是 ES Module:

import { snapdom } from '@zumer/snapdom

基础用法示例

一键截图

const card = document.querySelector('.user-card');

const image = await snapdom.toPng(card);

document.body.appendChild(image);

这段代码就是找个元素，然后直接截成 PNG 图片，再把图片加到页面上。简单粗暴，一步到位。

高级配置

const element = document.querySelector('.chart-container');

const capture = await snapdom(element, {

    scale: 2,

    backgroundColor: '#fff',

    embedFonts: true,

    compress: true

});

const png = await capture.toPng();

const jpg = await capture.toJpg({ quality: 0.9 });

await capture.download({

    format: 'png',

    filename: 'chart-report-2024'

});

这儿可以对截图进行各种配置。比如 scale 能调整清晰度，backgroundColor 能设置背景色，embedFonts 可以内嵌字体，compress 能压缩优化。配置好后，还能把截图存成不同格式，或者直接下载到本地。

和其他库比咋样

和 html2canvas、dom-to-image 比起来，SnapDOM 的优势很明显：

五、用的时候注意点

用 SnapDOM 时，有几点得注意：

跨域资源

要是截图里有外部图片等跨域资源，得确保这些资源支持 CORS，不然截不出来。

iframe 限制

SnapDOM 不能截 iframe 内容，这是浏览器的安全限制，没办法。

Safari 浏览器兼容性

在 Safari 里用 WebP 格式时，会自动变成 PNG。

大型页面截图

截超大页面时，建议分块截，不然可能会内存溢出。

六、SnapDOM 能干啥及代码示例

社交分享

async function shareAchievement() {

    const card = document.querySelector('.achievement-card');

    const image = await snapdom.toPng(card, { scale: 2 });

    navigator.share({

        files: [new File([await snapdom.toBlob(card)], 'achievement.png')],

        title: '我获得了新成就！'

    });

}

报表导出

async function exportReport() {

    const reportSection = document.querySelector('.report-section');

    await preCache(reportSection);

    await snapdom.download(reportSection, {

        format: 'png',

        scale: 2,

        filename: `report-${new Date().toISOString().split('T')[0]}`

    });

}

海报导出

async function generatePoster(productData) {

    document.querySelector('.poster-title').textContent = productData.name;

    document.querySelector('.poster-price').textContent = `¥${productData.price}`;

    document.querySelector('.poster-image').src = productData.image;

    await new Promise((resolve) => setTimeout(resolve, 100));

    const poster = document.querySelector('.poster-container');

    const blob = await snapdom.toBlob(poster, { scale: 3 });

    return blob;

}

写在最后

SnapDOM 就是这么一款简单、快速、准确，还零依赖的网页截图神器。

无论是社交分享、报表导出、设计保存，还是营销推广，它都能轻松搞定。

而且它是免费开源的，背后还有活跃的社区支持。要是你还在为网页截图的事儿发愁，赶紧试试 SnapDOM 吧。

要是你在用 SnapDOM 的过程中有啥疑问，或者碰上啥问题，可以去下面这些地方找答案：

• 项目地址 ：github.com/zumerlab/sn…


• 在线演示 ：zumerlab.github.io/snapdom/


• 详细文档 ：github.com/zumerlab/sn…

长久以来，"用 Vue 3 写真正的原生 App" 一直是块短板。

uni-app 虽然"一套代码多端运行"，但性能瓶颈、厂商锁仓、原生能力羸弱的问题常被开发者诟病。

整个 Vue 生态始终缺少一个能与 React Native 并肩的"真·原生"跨平台方案

直到 NativeScript-Vue 3 的横空出世，并被 尤雨溪 亲自点赞。

为什么是时候说 goodbye 了？

"我们只是想要一个 Vue 语法 + 真原生渲染 + 社区插件开箱即用 的解决方案。"

—— 这，正是 NativeScript-Vue 给出的答案。

尤雨溪推特背书

2025-10-08，Evan You 转发 NativeScript 官方推文：

"Try Vite + NativeScript-Vue today — HMR, native APIs, live reload."

配图是一段 <script setup> + TypeScript 的实战 Demo，意味着：

• 真正的 Vue 3 语法（Composition API）


• Vite 秒级热重载


• 直接调用 iOS / Android 原生 API

获创始人的公开推荐，无疑给社区打了一剂强心针。

NativeScript-Vue 是什么？

一句话：Vue 的自定义渲染器 + NativeScript 原生引擎

• 运行时 没有 WebView，JS 在 V8 / JavaScriptCore 中执行


• <template> 标签 → 原生 UILabel / android.widget.TextView


• 支持 NPM、CocoaPods、Maven/Gradle 全部原生依赖


• 与 React Native 同级别的性能，却拥有 Vue 完整开发体验

5 分钟极速上手

1. 环境配置（一次过）

# Node ≥ 18

npm i -g nativescript

ns doctor                # 按提示安装 JDK / Android Studio / Xcode

# 全部绿灯即可

2. 创建项目

ns create myApp \

  --template @nativescript-vue/template-blank-vue3@latest

cd myApp

模板已集成 Vite + Vue3 + TS + ESLint

3. 运行 & 调试

# 真机 / 模拟器随你选

ns run ios

ns run android

保存文件 → 毫秒级 HMR，console.log 直接输出到终端。

4. 目录速览

myApp/

├─ app/

│  ├─ components/          // 单文件 .vue

│  ├─ app.ts               // createApp()

│  └─ stores/              // Pinia 状态库

├─ App_Resources/

└─ vite.config.ts          // 已配置 nativescript-vue-vite-plugin

5. 打包上线

ns build android --release   # 生成 .aab / .apk

ns build ios --release       # 生成 .ipa

签名、渠道、自动版本号——标准原生流程，CI 友好。

Vue 3 生态插件兼容性一览

检测小技巧：

npm i xxx

grep -r "document\|window\|HTMLElement" node_modules/xxx || echo "大概率安全"

调试神器：Vue DevTools 支持

NativeScript-Vue 3 已提供 官方 DevTools 插件

• 组件树、Props、Events、Pinia 状态 实时查看


• 沿用桌面端调试习惯，无需额外学习成本

👉 配置指南：https://nativescript-vue.org/docs/essentials/vue-devtools

插件生态 & 原生能力

• 700+ NativeScript 官方插件
  
  ns plugin add @nativescript/camera | bluetooth | sqlite...


• iOS/Android SDK 直接引入
  
  CocoaPods / Maven 一行配置即可：

 // 调用原生 CoreBluetooth

 import { CBCentralManager } from '@nativescript/core'

• 自定义 View & 动画
  
  注册即可在 <template> 使用，与 React Native 造组件体验一致。

结语：这一次，Vue 开发者不再低人一等

React Native 有 Facebook 撑腰，Flutter 有 Google 背书，

现在 Vue 3 也有了自己的 真·原生跨平台答案 —— NativeScript-Vue。

它让 Vue 语法第一次 完整、无损、高性能 地跑在 iOS & Android 上，

并获得 尤雨溪 公开点赞与 Vite 官方生态加持。

弃用 uni-app，拥抱 NativeScript-Vue，

让 性能、原生能力、工程化 三者兼得，

用你最爱的 .vue 文件，写最硬核的移动应用！

🔖 一键直达资源

• 官网 & 文档：https://nativescript-vue.org


• 插件兼容列表：https://nativescript-vue.org/docs/essentials/vue-plugins


• DevTools 配置：https://nativescript-vue.org/docs/essentials/vue-devtools


• 环境安装指南：https://docs.nativescript.org/setup/

一、历史背景 + 时间轴

网页一旦需要 “实时” ，麻烦就开始了：数据在不断变化，用户却只能等下一次刷新；

• 刷新解决不了的延迟，用短轮询凑数，又被无数空请求反噬；
• 再加长轮询，试图把“有了新数据再说”变成一种伪推送，却仍困在请求—响应的笼子里。
• 开发者于是继续前探：让连接不再频繁重建，尝试分块直输，把事件像水一样持续送达，于是有了更顺滑的 Streaming 与标准化的 SSE。

直到某一刻，我们不再满足于“更聪明的单向”，而是迈向真正的“同时说话与倾听”——WebSocket 把通信从一次次请求，变成一条持久而通透的通道。此后，

• HTTP/2、HTTP/3 与 QUIC 又在底层为效率和时延开了绿灯，甚至提供了可选可靠与无序传输的更多可能。

接下来，我们就沿着这条主线，层层展开：它们各自解决了什么、在哪些场景最合拍、又如何在你的系统里形成清晰的选型边界。

01｜从整页刷新出发：减少浪费的一条链路

这一块是为了解决“整页刷新导致的高延迟与带宽浪费”，逐级细化与优化。

a. 早期网页：整页刷新

• 背景与问题：每次更新都整页请求，体验割裂、带宽浪费、延迟高。
• 直接影响：促使前端与服务端思考“只取变化”。

b. 短轮询（Short Polling）为解决整页刷新的低效

• 解决：改为“隔一段时间拉一次”，显著减少整页重载带来的浪费。
• 局限：高频请求带来大量空响应与服务器开销。
• 承接改进：为减少空转，演进到长轮询；同时催生更流式的思路（Streaming/SSE）。

c. 长轮询（Comet/挂起请求）为减少短轮询的空转

• 解决：请求挂起，服务器有新数据才返回，接近“伪推送”，显著降低空转。
• 局限：本质仍是请求-响应；连接频繁重建；难做真正双向。
• 承接改进：
  • 单向推送更稳：SSE 标准化单向事件流。
  • 若要真双向与二进制：交给 WebSocket（见独立块）。

d. HTTP Streaming（分块传输/持续输出）为进一步降低重连与延迟

• 解决：保持连接，分块持续输出，适合连续文本/事件流，重连更少、延迟更低。
• 局限：多为单向，受代理/中间件影响，兼容性不一。
• 承接改进：单向事件由 SSE 标准化；双向场景仍需 WebSocket。

e. SSE（Server-Sent Events）单向推送的标准化终点

• 解决：以标准事件流语义提供单向推送，浏览器原生支持，资源占用低。
• 适配范围：通知、进度、日志/监控等文本或事件流。
• 位置关系：在“只需单向推送”的场景中，SSE 是这一链条的稳定落点，而非过渡技术。

---

02｜范式跃迁：WebSocket（独立大块）

这不是前面链条的“又一改良”，而是从请求-响应转向全双工持久连接的范式变化。

WebSocket（全双工、持久、低开销）

• 解决：真正的双向实时通信，降低握手与头部开销，支持文本与二进制，端到端延迟低。
• 典型场景：聊天、协同编辑、在线游戏、行情推送、IoT。
• 与上一链条的关系：
  • 在“需要双向实时”的主战场，实质上取代了短轮询/长轮询等过渡方案。
  • 与 SSE 并存：若只有单向通知/事件流，SSE 更简单更省资源；若需要双向或二进制，WebSocket 更合适。

• 运维关注：连接状态管理、容量与反压、企业代理/负载均衡兼容。

---

03｜底座升级与新选项：HTTP/2·HTTP/3·QUIC 家族

这部分不是替代前两块，而是提供更高效的承载与更灵活的传输语义。

WS over H2/H3

• 价值：与同域请求复用连接、更好穿透与效率、更低握手成本。
• 作用：让 WebSocket 的部署与网络效率更优。

WebTransport（基于 QUIC）

• 价值：可选可靠与有序/无序、更低延迟，适合实时媒体、游戏、定制协议。
• 关系：不是取代 WebSocket/SSE 的通吃方案，而是当你需要“更细粒度的可靠性与顺序控制”时的新工具。

二、速查表

实时推送的目标是“低延迟、双向或单向地把数据从服务端送到客户端”。主流技术选型包括：

三、WebSocket 核心定义（重要）

WebSocket 是 HTML5 推出的一种全双工(Full-Duplex)、持久化(Persistent)的网络通信协议， 基于TCP协议构建，允许客户端(浏览器)与服务器之间建立一条长期稳定的连接通道，实现「服务器主动向客户端推送数据」和「客户端实时向服务器发送数据」的双向通信，无需频繁建立/断开连接。

其核心特点可概括为：

• 全双工：通信双方可同时发送/接收数据(区别于HTTP的「请求-响应」单向通信)；
• 持久连接：连接建立后长期保持，避免HTTP每次通信都需重新握手的开销；
• 轻量协议：数据帧头部信息简洁(仅2-14字节)，传输效率远高于HTTP；
• 协议标识：客户端发起连接时使用ws：//(非加密)或wss：//(加密，基于TLS，类似HTTPS)作为协议前缀。

从零开始的完整流程

下面是一条你在前端真实会走的链路：创建连接 → HTTP 握手与协议切换 → 进入 WebSocket 双向通信 → 启动心跳检测 → 发现异常并重连 → 重连成功后的补偿 → 服务端跨域放行 → 正常/异常关闭。

---

1) 创建连接（入口）

你写下第一行代码时，要解决两件事：用对协议前缀、绑定好事件。

• 如果网页是 HTTPS 必须用 wss://，HTTP 页面用 ws://
• 立刻绑定 onopen/onmessage/onerror/onclose，以便后续重用。

示意代码（精简）：

• new WebSocket(url)
• 绑定事件：initWebSocketEvents(ws)

---

2) HTTP 握手与协议切换（从“请求”到“长连”）

客户端(浏览器) 创建 WebSocket 实例时，会发起一个特殊的 HTTP - GET，核心目的是 「请求将协议从HTTP升级为WebSocket」。服务端验证通过后返回 101，双方切换到 WebSocket 帧通信。

WebSocket 帧是双向通信中的最小传输结构，携带 “ 数据类型 、 是否为消息的最后一段 、 负载长度 、 掩码/密钥 、 实际数据 ” 。消息可以被拆成多帧连续发送，也可以一个帧就送完。

客户端发起「协议升级请求」(HTTP - GET 请求)

请求头中关键字段(面试高频考点)：

• GET /ws-endpoint HTTP/1.1：请求方法为 GET，路径为服务器的 WebSocket 端点(如/ws)；
• Host：example.com：服务器域名；
• Upgrade：websocket：核心字段，告知服务器「要升级协议为 WebSocket」；
• Connection：Upgrade：配合 Upgrade，表示「这是一个协议升级请求」；
• Sec-WebSocket-Key：dGhlIHNhbXBsZSBub25jzQ==：客户端生成的随机字符串(Base64 编码，长度 16 字节)，用于服务器验证(防止恶意连接)；
• Sec-WebSocket-Version：13：WebSocket 协议版本(当前主流为 13，需服务器支持)；
• Sec-WebSocket-Origin：https：//example.com：客户端所在域名(用于服务器跨域验证)。

服务器响应「协议升级成功」(HTTP - 101状态码)

服务器收到请求后，若支持 WebSocket 协议且验证通过(如 Sec-WebSocket-Key 验证、跨域验证) ，会返回HTTP - 101(SwitchingProtocols)状态码，表示「同意协议升级」。

响应头中关键字段 (面试高频考点)：

• HTTP/1.1 101 Switching Protocols：101 状态码是协议切换的标志；
• Upgrade： websocket：确认升级为WebSocket 协议；
• Connection：Upgrade：确认连接用于协议升级；
• Sec-WebSocket-Accept：s3pPLMBiTxaQ9kYGzzhZRbK+xOo=：服务器对Sec-WebSocket-Key 的处理结果(核心验证逻辑)：
  1. 服务器将客户端发送的 Sec-WebSocket-Key 与固定字符串 258EAFA5-E914-47DA-95CA-C5AB0DC85B11 拼接；
  2. 对拼接后的字符串进行 SHA-1 哈希计算；
  3. 将哈希结果转为 Base64 编码，即为 Sec-WebSocket-Accept 的值；
  4. 客户端会验证该值是否正确，若不正确则拒绝建立连接(防止伪造响应)。

---

3) 进入通信阶段（双向数据 + 基础发送）

握手通过，onopen 会触发。此时做两件事：

• 发送初始化数据（如身份、订阅主题）
• 启动心跳（下一步会讲）

通信注意：

• onmessage 既可能是字符串，也可能是二进制（Blob/ArrayBuffer）
• bufferedAmount 可用来做背压控制（积压太大时暂停继续 send）

---

4) 启动心跳（让连接“活着”且可感知）

持久连接会遭遇 Wi‑Fi 抖动、防火墙清理等问题。心跳=周期性发 ping，超时未收到 pong 就判死链。

推荐参数（可按业务调优）：

• HEARTBEAT_INTERVAL ≈ 30s
• HEARTBEAT_TIMEOUT ≈ 10s

实操要点：

• 启动前先清理旧定时器，避免重复
• 收到 pong 立即清除超时定时器
• onclose/onerror 必须停止心跳

---

5) 异常→重连（恢复连接但不过载）

一旦 onerror、onclose(code ≠ 1000) 或心跳判定超时，进入重连。

目标是：能恢复、不过载、可被用户停止。

策略三件套：

• 指数退避：1s → 2s → 4s … 最多 30s
• 次数上限：如 10 次（达到即停）
• 可控停止：提供“停止重连”或页面关闭时停

补偿机制：

• 在断开前缓存“待发送”数据（例如未发出的聊天消息）
• 重连成功后按序补发，确保业务连续性

---

6) 服务器放行跨域（握手能否过关的关键）

虽然 WebSocket 原生“支持跨域”，但握手是 HTTP，服务端需要对 Sec-WebSocket-Origin 做白名单校验。

否则会 403 或直接关闭。

• Node.js（ws）
  • 读取 req.headers['sec-websocket-origin']
  • 不在 allowedOrigins 列表：关闭 1008 “Cross-origin access denied”

• Spring Boot
  • registry.addHandler(...).setAllowedOrigins("https://a.com", "https://b.com")
  • 需要时 .withSockJS()提供降级

---

7) 正常关闭与资源清理（善始善终）

• 用户离开页面或主动退出：ws.close(1000, '用户主动退出')
• onclose 中停止心跳与重连，清空定时器与队列，避免泄漏
• 记录关闭原因码：1000 正常、1006 常见于异常/心跳超时

四、面试题

面试关注点通常围绕“协议对比、连接管理、消息语义、可靠性与扩展性、安全与运维成本”。

1、WebSocket 与 SSE 的差异与使用场景，HTTP轮询呢？

WebSocket（全双工，二进制/文本）

• 适用：即时聊天、协作编辑、游戏状态同步、行情推送、需要客户端→服务端主动上行的实时交互。
• 优点：低延迟、头开销小、全双工、支持二进制、可自定义子协议。
• 注意：需处理心跳、重连、背压、鉴权与扇出扩展；代理/LB 要正确透传 Upgrade 和超时设置。

Server-Sent Events（SSE，单向 server→client）

• 适用：通知流、日志流、监控事件、流式生成文本（如增量输出）、只需服务端下行的实时更新。
• 优点：浏览器原生 EventSource、文本流、自动重连、支持 Last-Event-ID 断点续传；实现简单。
• 注意：单向、仅文本（可 base64 二进制）、连接数限制与代理超时需要关注；移动端网络切换要做容错。

HTTP 轮询/长轮询（兼容兜底）

• 适用：对实时性要求不高的小流量场景、受网络环境或企业防火墙限制无法使用 WS/SSE 时的兜底。
• 优点：最易落地、与缓存/鉴权/监控体系天然兼容；对中间设备最友好。
• 注意：延迟更高、资源利用低；高频轮询会带来成本与限流压力。

✅ 重点

• WebSocket 通过 HTTP/1.1 Upgrade → 101 完成切换，此后是帧协议的全双工通道；Keep-Alive 仅是复用 TCP，不改变 HTTP 的请求-响应语义。
• 选型规则：需要双向实时交互选 WebSocket；单向事件流选 SSE；受限或低实时性场景用轮询作兜底。

2、如何设计一个可水平扩展的实时推送系统？

在可水平扩展的实时推送系统中，WebSocket 连接会分布在多台网关节点上。

核心挑战是如何在连接与消息不在同一台机器时，仍能把消息快速路由到正确的连接。可行的范式是

• 网关层负责连接
• 管道层负责路由与发布订阅
• 存储层负责状态与回放

🔌 网关层（负责连接）

• 终止 TLS/WS，维持心跳与速率限制，保持无状态实例。
• 建立本地索引：connectionId → 订阅集合，userId → connectionIds。
• 将连接元数据上报共享存储：connectionId、userId、nodeId、订阅、最近心跳。
• 仅订阅“与自己有关的分片”：按 userId/topic 的哈希分片从管道层拉取，减少无关扇出。
• 写通道背压与优先级：控制帧/关键消息优先，低优先级可丢尾或抽样。

---

🚇 管道层（负责路由与发布订阅）

• 选型具备分片与回放能力的总线（Kafka/Pulsar/NATS/Redis Streams）。
• 分片策略：
  • 点推：按 userId/connectionId 一致性哈希到分区，保证单用户局部有序。
  • 主题推送：按 topic 分区，网关本地再做订阅过滤与扇出。

• 路由方式：
  • 生产者只需写对的分片；总线按分区把消息送到订阅该分片的网关。
  • 广播/超大房间采用“分层扇出”：先到分片，再由各网关本地扇出，必要时加中间扇出代理。

• 去重与幂等：messageId 或 (topic, partition, offset) 作为幂等键，网关/客户端各自维护短期去重集合。

---

🗃️ 存储层（负责状态与回放）

• 会话与订阅状态：使用 Redis Cluster 或 KV 服务存 userId→connectionIds、connectionId→nodeId、订阅清单、心跳时间。
• 游标与回放：在总线层保留 offset；客户端重连携带 resumeToken，网关据此恢复订阅并按 offset 增量补发。
• 一致性与更新：订阅变更写事件流，相关网关消费后刷新本地索引；用版本号/逻辑时钟避免乱序覆盖。

3、如何保证消息不丢、不重、按序？

1. 不丢： 消息先落到能持久化、带副本确认的总线里（像“写盘且多副本到位才算成功”），写失败就退避重试；消费侧是“先送到用户手里或进可靠下行队列，再更新位点”，断线后拿着 resumeToken+offset 从保留的历史里把漏掉的补回来。
2. 不重： 每条消息都有一个不会撞车的“指纹”（messageId 或 topic-partition-offset）；网关用一小块内存做近端去重，只有第一次真正写入才前进位点，重复的一概忽略；客户端也按同一指纹做幂等处理，避免业务状态被二次改动。
3. 按序： 把需要有序的对象（userId/roomId）哈希到同一分区，借用分区内天然顺序；同一个键在网关里串行发送、同队列内重试，不跨分区不并行穿插，这样即使重试和补发也不会把顺序打乱。

4、心跳如何设计？超时如何判定？

这里的心跳，目标是 “保活、探测、可平滑重连”。

1. 不失联： 用应用层 ping/pong，客户端主发、服务端回；
   1. 间隔 20–60s，加±10%抖动
   2. 未知网络时取 20–30s，确保小于最短 NAT 空闲回收。

2. 怎么判死： 别一跳不回就拍板。记录 lastSeen，允许 2–3 次心跳未达或 now-lastSeen 超过 2–3 个周期再判断；进入“Suspect”时降级写入，仍有业务流量即立刻恢复。
3. 断了咋办：重连走指数退避并带抖动，携带 resumeToken/offset 补发；移动端切网优先复用会话，失败再重建。监控 RTT/丢包与 Suspect 比例，自动调心跳与阈值。

5、如何在 Nginx/Envoy 反向代理后稳定运行 WebSocket？

核心思路：让代理“不瞎操心”、连接“常被看见”、后端“可续上”。

• 代理设置：开启 WebSocket 升级；调大超时，禁用缓冲与压缩；保持 TCP keepalive，HTTP/2 用 CONNECT（H2/WebSocket）。
• 心跳与保活：应用层 ping/pong 20–30s（±10%抖动），保证小于代理/NAT空闲回收；大连接数用轻量负载均衡（hash by userId/roomId）避免跨节点迁移。
• 断线与重连：客户端指数退避+抖动，带会话 token/offset 续传；后端幂等去重，重放不重不丢。
• 运维与观测：开代理层指标（升级成功率、idle 关闭数、5xx）、RTT/丢包与重连率，异常时自适应缩短心跳或放宽超时。

6、如何做鉴权与权限隔离？

握手前校验 JWT；Subprotocol 指定租户/版本；频道级 ACL；避免敏感数据从客户端请求非授权频道。

• 握手前校验 JWT：在 HTTP Upgrade前验证 iss/aud/exp/签名并解析 tenant_id/user_id/scopes，避免建立长连后再踢。
• Subprotocol 指定租户/版本：用 Sec-WebSocket-Protocol 携带 tenant 和策略版本做白名单匹配，确保连接上下文一致。
• 频道级 ACL：频道强制以租户前缀命名，每次 subscribe/publish 依据 RBAC+scope 前缀（到资源或前缀）做服务端授权。
• 避免敏感数据越权：仅按服务器维护的“已授权订阅集合”下发数据，忽略客户端自报筛选请求并拒绝未授权频道。

7、如何评估性能与成本？

• 每连接内存占用： 用基线压测量出 MB/1k 连接的实际占用，结合目标并发外推单机上限并监控 GC/碎片。
• 每秒消息数（fanout×频率）： 用发布频率×平均扇出得到总吞吐，核算带宽与发送队列容量，识别热点频道放大效应。
• 尾延迟 P95/P99： 持续跟踪端到端延迟长尾并关联队列深度与CPU/GC事件，确保在SLA红线下仍稳定。
• 压测考虑广播峰值与重连风暴： 分别模拟大扇出瞬时广播与大量短时间内握手重连，验证背压、限速和握手路径的韧性。

8、遇到“重连风暴”怎么处理？

• 抖动退避（指数退避 + 随机抖动）： 客户端按指数退避间隔重试并加入随机抖动，避免同相位同时重连造成尖峰。
• 分批恢复： 将连接恢复按固定批次/时间片发放（如每 100ms 开放 N 个），把尖峰摊平到更长窗口。
• 服务端限流与排队： 在握手与认证路径设置并发/速率上限与队列，超限直接返回可重试错误或延迟令牌。
• 灰度放量： 按租户/区域/版本逐步提升允许重连比例，结合健康度与错误率自动调节放量速度。

9、前端如何封装一个健壮的 WebSocket 客户端？

• 状态机（ CONNECTING / OPEN / CLOSING / CLOSED ）： 用有限状态机驱动所有事件与迁移，单航道控制避免并发重连与回调竞态。
• 心跳/重连策略： 按固定心跳探活与半开检测，重连采用指数退避叠加随机抖动并设上限与冷却期。
• 消息序列化： 统一 envelope（type/id/ts/payload），默认 JSON，性能敏感时切 Protobuf/MessagePack 并保持向后兼容。
• 离线缓存与去重： 未连通时将待发入队、跨刷新用 IndexedDB，按 seq/uuid 去重并用 last-seq 做断点续传。
• 可观测日志： 记录连接尝试/关闭码/重连次数/心跳RTT/队列长度等指标与事件，便于快速定位长尾与故障。

作者：HiStewie
来源：juejin.cn/post/7572539461478907947

📝项目背景

​ 最近时间比较闲,摸鱼的时间越来越多了,人一闲下来就会想做点什么。说干就干，立马行动。

在刷了半小时pdd之后我买了张ui图，并根据这个ui做了一个大屏。

​ 最终效果如下：

📦项目地址

​ 这里附上项目地址，如果你觉得不错的话，帮我点一个小小的start。

👉 点我访问项目源码，欢迎 Star

🌐在线预览

这个预览地址是vercel的地址，如果你没有挂梯子的话，会访问不了。访问不了的话，建议直接本地跑项目。

在线预览

🛠️ 技术栈

​ 项目主要是vue3+echarts的组合，整个项目主要都是一些图表的应用。下面会介绍一些模块的实现思路。

💻一些模块的实现

🗺️中间地图

DataV的地址

​ 第一步先获取地图行政区的geo数据，以我这个项目为例，我需要获取山东省的地图数据。

打开dataV，找到数据可视化学院，在里面找到需要的行政区，把它的geojson下载下来。

下载下来的数据长这样

​ 这就是我们需要的geojson数据了。

​ 拿到数据之后，就需要将其渲染出来。

​ 这里我用的是echarts的地图。因为这个项目的地图，基本没有交互，就纯纯的数据展示。使用echarts来做的 效果会比，cesium那些更好。

注册地图

import * as echarts from 'echarts'

import sdData from '@/assets/data/山东省'

echarts.registerMap('sd', sdData as any)

先将前面下载来的数据geojson数据注册到echarts里面，并配置echarts的geo选项

{

    geo: [

      // 最外围发光边界

      {

        map: 'sd',

        aspectScale: 0.85,

        layoutCenter: ['50%', '50%'], //地图位置

        layoutSize: '100%',

        z: 12,

        emphasis: {

          disabled: true

        },

        itemStyle: {

          normal: {

            borderColor: 'rgb(180, 137, 81)',

            borderWidth: 8,

            shadowColor: 'rgba(218, 163, 88, 0.4)',

            shadowBlur: 20

          }

        }

      },

    ],

  }

这时候渲染出来的地图是纯色的，什么都没有 也没有立体。

因为这个geo是一个平面的地图，想要立体效果，可以通过堆叠地图，并且设置位移的方式实现

比如我这边就通过这种方式去实现

通过叠加多个图层，并且每个图层的layoutCenter都不同

最终就可以实现这种看起来很立体的二维地图

具体实现代码可以访问我的github仓库看，这里只介绍一下大致思路

🔢底部的数字字体和轮播

可以看到我底部的数字字体很特别，这不是图片，这是一种电子屏风格的数字字体。

我们在网上找一个类似的字体，将其下载下来，并用css的@font-face将其引入。然后在需要的地方用font-family使用即可。

除了这个，这里还有一个数字的轮播效果，我是用vue3-odometer实现的。

为什么用这个库呢，主要是使用方便，不用配置一堆乱七八糟的。

📊其他图表

​ 其它图表就比较常规了，这里就不做过多介绍，具体可以看源码的实现。

🔚 结尾

​ 这个大屏虽然只有一个页面，但是做的时候，相关的图表配置调整还是挺多的。后续打算开发一个mini版的后台管理，用来管理大屏数据，并且这个后台管理的接口用node开发，用来当作node后端的练习。

前端学习记录第5波，每半年一次。对前四次学习内容感兴趣的可以去我的掘金专栏“每周学习记录”进行了解。

第1周 12.30-1.5

本周学习了一个新的CSS媒体查询prefers-reduced-transparency，如果用户在系统层面选择了降低或不使用半透明，这个媒体查询就能够匹配，此特性与用户体验密切相关的。

更多内容参见我撰写的这篇文章：一个新的CSS媒体查询prefers-reduced-transparency —— http://www.zhangxinxu.com/wordpress/?…

第2周 1.6-1.12

这周新学习了一个名为Broadcast Channel的API，可以实现一种全新的广播式的跨页面通信。

过去的postMessage通信适合点对点，但是广播式的就比较麻烦。

而使用BroadcastChannel就会简单很多。

这里有个演示页面：http://www.zhangxinxu.com/study/20250…

左侧点击按钮发送消息，右侧两个内嵌的iframe页面就能接收到。

此API的兼容性还是很不错的：

更多内容可以参阅此文：“Broadcast Channel API简介，可实现Web页面广播通信” —— http://www.zhangxinxu.com/wordpress/?…

第3周 1.13-1.19

这周学习的是SVG半圆弧语法，因为有个需求是实现下图所示的图形效果，其中几段圆弧的长度占比每个人是不一样的，因此，需要手写SVG路径。

圆弧的SVG指令是A，语法如下：

M x1 y1 A rx ry x-axis-rotation large-arc-flag sweep-flag x2 y2

看起来很复杂，其实深究下来还好：

详见这篇文章：“如何手搓SVG半圆弧，手把手教程” - http://www.zhangxinxu.com/wordpress/?…

第4周-第5周 1.20-2.2

春节假期，学什么学，high起来。

第6周 2.3-2.9

本周学习Array数组新增的with等方法，这些方法在数组处理的同时均不会改变原数组内容，这在Vue、React等开发场景中颇为受用。

例如，在过去，想要不改变原数组改变数组项，需要先复制一下数组：

现在有了with方法，一步到位：

类似的方法还有toReversed()、toSorted()和toSpliced()。

更新内容参见这篇文章：“JS Array数组新的with方法，你知道作用吗？” - http://www.zhangxinxu.com/wordpress/?…

第7周 2.10-2.16

本周学习了两个前端新特性，一个JS的，一个是CSS的。

1. Set新增方法

JS Set新支持了intersection, union, difference等方法，可以实现类似交集，合集，差集的数据处理，也支持isDisjointFrom()是否相交，isSubsetOf()是否被包含，isSupersetOf()是否包含的判断。

详见此文：“JS Set新支持了intersection, union, difference等方法” - http://www.zhangxinxu.com/wordpress/?…

2. font-size-adjust属性

CSS font-size-adjust属性，可以基于当前字形的高宽自动调整字号大小，以便各种字体的字形表现一致，其解决的是一个比较细节的应用场景。

例如，16px的苹方和楷体，虽然字号设置一致，但最终的图形表现楷体的字形大小明显小了一圈：

此时，我们可以使用font-size-adjust进行微调，使细节完美。

p {  font-size-adjust: 0.545;}

此时的中英文排版效果就会是这样：

更新细节知识参见我的这篇文章：“不要搞混了，不是text而是CSS font-size-adjust属性” - http://www.zhangxinxu.com/wordpress/?…

第8周 2.17-2.23

本周学习的是HTML permission元素和Permissions API。

这两个都是与Web浏览器的权限申请相关的。

在Web开发的时候，我们会经常用到权限申请，比方说摄像头，访问相册，是否允许通知，又或者地理位置信息等。

但是，如果用户不小心点击了“拒绝”，那么用户就永远没法使用这个权限，这其实是有问题的，于是就有了元素，权限按钮直接暴露在网页中，直接让用户点击就好了。

但是，根据我后来的测试，Chrome浏览器放弃了对元素的支持，因此，此特性大家无需关注。

那Permissions API又是干嘛用的呢？

在过去，不同类型的权限申请会使用各自专门的API去进行，这就会导致开始使用的学习和使用成本比较高。

既然都是权限申请，且系统出现的提示UI都近似，何必来个大统一呢？在这种背景下，Permissions API被提出来了。

所有的权限申请全都使用一个统一的API名称入口，使用的方法是Permissions.query()。

完整的介绍可以参见我撰写的这篇文章：“HTML permission元素和Permissions API简介” - http://www.zhangxinxu.com/wordpress/?…

第9周 2.24-3.2

CSS offset-path属性其实在8年前就介绍过了，参见：“使用CSS offset-path让元素沿着不规则路径运动” - http://www.zhangxinxu.com/wordpress/?…

不过那个时候的offset-path属性只支持不规则路径，也就是path()函数，很多CSS关键字，还有基本形状是不支持的。

终于，盼星星盼月亮。

从Safari 18开始，CSS offset-path属性所有现代浏览器全面支持了。

因此，很多各类炫酷的路径动画效果就能轻松实现了。例如下图的蚂蚁转圈圈动画：

详见我撰写的此文：“终于等到了，CSS offset-path全浏览器全支持” - http://www.zhangxinxu.com/wordpress/?…

第10周 3.3-3.9

CSS @supports规则新增两个特性判断，分别是font-tech()和font-format()函数。

1. font-tech()

font-tech()函数可以检查浏览器是否支持用于布局和渲染的指定字体技术。

例如，下面这段CSS代码可以判断浏览器是否支持COLRv1字体（一种彩色字体技术）技术。

@supports font-tech(color-COLRv1) {}

2. font-format()

font-format()这个比较好理解，是检测浏览器是否支持指定的字体格式的。

@supports font-format(woff2) {   /* 浏览器支持woff2字体 */ }

不过这两个特性都不实用。

font-tech()对于中文场景就是鸡肋特性，因为中文字体是不会使用这类技术的，成本太高。

font-format()函数的问题在于出现得太晚了。例如woff2字体的检测，这个所有现代浏览器都已经支持了，还有检测的必要吗，没了，没有意义了。

不过基于衍生的特性还是有应用场景的，具体参见此文：“CSS supports规则又新增font-tech,font-format判断” - http://www.zhangxinxu.com/wordpress/?…

第11周 3.10-3.16

本周学习了一种更好的文字隐藏的方法，那就是使用::first-line伪元素，CSS世界这本书有介绍。

::first-line伪元素可以在不改变元素color上下文的情况下变色。

可以让按钮隐藏文字的时候，里面的图标依然保持和原本的文字颜色一致。

详见这篇文章：“一种更好的文字隐藏的方法-::first-line伪元素” - http://www.zhangxinxu.com/wordpress/?…

第12周 3.17-3.23

本周学习了下attachInternals方法，这个方法很有意思，给任意自定义元素使用，可以让普通元素也有原生表单控件元素一样的特性。

比如浏览器自带的验证提示：

比如说提交的时候的FormData或者查询字符串：

有兴趣的同学可以访问“研究下attachInternals方法，可让普通元素有表单特性”这篇文章继续了解 - http://www.zhangxinxu.com/wordpress/?…

第13周 3.24-3.30

本周学习了一个新支持的HTML属性，名为blocking 属性。

它主要用于控制资源加载时对渲染的阻塞行为。

blocking 属性允许开发者对资源加载的优先级和时机进行精细控制，从而影响页面的渲染流程。浏览器在解析 HTML 文档时，会根据 blocking 属性的值来决定是否等待资源加载完成后再继续渲染页面，这对于优化页面性能和提升用户体验至关重要。

blocking 属性目前支持的HTML元素包括

使用示意：

更多内容参见我撰写的这篇文章：“光速了解script style link元素新增的blocking属性” - http://www.zhangxinxu.com/wordpress/?…

第14周 3.31-4.6

本周学习了JS EditContext API。

EditContext API 是 Microsoft Edge 浏览器提供的一个 Web API，它允许开发者在网页中处理文本输入事件，以便在原生输入事件（如 keydown、keypress 和 input）之外，实现更高级的文本编辑功能。

详见我撰写的这篇文章：“JS EditContext API 简介” - http://www.zhangxinxu.com/wordpress/?…

第15周 4.7-4.13

本周学习一个DOM新特性，名为caretPositionFromPoint API。

caretPositionFromPoint可以基于当前的光标位置，返回光标所对应元素的位置信息，在之前，此特性使用的是非标准的caretRangeFromPoint方法实现的。

和elementsFromPoint()方法的区别在于，前者返回节点及其偏移、尺寸等信息，而后者返回元素。

比方说有一段

元素文字描述信息，点击这段描述的某个文字，caretPositionFromPoint()方法可以返回精确的文本节点以及点击位置的字符偏移值，而elementsFromPoint()方法只能返回当前

元素。

不过此方法的应用场景比较小众，例如点击分词断句这种，大家了解下即可。

详见我撰写的这篇文章：“DOM新特性之caretPositionFromPoint API” - http://www.zhangxinxu.com/wordpress/?…

第16周 4.14-4.20

本周学习的是getHTML(), setHTMLUnsafe()和parseHTMLUnsafe()这三个方法，有点类似于可读写的innerHTML属性，区别在于setHTMLUnsafe()似乎对Shadow DOM元素的设置更加友好。

parseHTMLUnsafe则是个document全局方法，用来解析HTML字符串的。

这几个方法几乎是同一时间支持的，如下截图所示：

具体参见我写的这篇文章：介绍两个DOM新方法setHTMLUnsafe和getHTML - http://www.zhangxinxu.com/wordpress/?…

第17周 4.21-4.27

光速了解HTML shadowrootmode属性的作用。

shadowRoot的mode是个只读属性，可以指定其模式——打开或关闭。

这定义了影子根的内部功能是否可以从JavaScript访问。

当影子根的模式为“关闭”时，影子根的实现内部无法从JavaScript访问且不可更改，就像元素的实现内部不能从JavaScript访问或不可更改一样。

属性值是使用传递给Element.attachShadow()的对象的options.mode属性设置的，或者在声明性创建影子根时使用<template>元素的shadowrootmode属性设置的。

类似的属性总共有4个：

• shadowRootClonable 标示可复制状态


• shadowRootDelegatesFocus 标示聚焦委托状态（子元素点击，ShadowRoot获得焦点）


• shadowRootMode 标示开放状态


• shadowRootSerializable 标示序列化状态

这些属性都是与Web Components开发相关的，我看还有人用在SSR中，可以遍历组件元素内部的信息。

详见我整理的这篇文章：“光速了解HTML shadowrootmode等属性的作用” - http://www.zhangxinxu.com/wordpress/?…

第18周 4.28-5.4

最近已经在正式项目中使用scale, rotate, translate属性了（注意，没有skew属性），很赞，毕竟这几个特性已经支持4年多了。

告别transform属性，直接使用scale、rotate和translate属性，是 CSS 发展的一个新趋势。它们不仅语法简洁、易于使用，而且能让我们更方便地对元素的变形效果进行独立控制，提高代码的可维护性和性能。在未来的前端开发中，我们应该积极拥抱这些新特性，让我们的 CSS 代码更加简洁、高效。

详见此文：告别transform，是时候直接使用scale, rotate属性啦 - http://www.zhangxinxu.com/wordpress/?…

第19周 5.5-5.11

本周学习CSS animation-composition属性，该属性可以让动画效果累加。

演示页面地址见这里：不同值混合后的动画效果demo - http://www.zhangxinxu.com/study/20250…

支持replace、add和accumulate这三个值，其中后面两个值很容易混淆，add直接就是属性值累加，accumulate则是属性的计算值累加。

animation-composition特别适合用在transform定位的同时需要transform动画的场景中。

详见我写的这篇文章：“CSS animation-composition可以让动画效果累加” - http://www.zhangxinxu.com/wordpress/?…

第20周 5.12-5.18

这是这周才知道的一个知识，那就是输入框的value值也能直接返回数值类型。

已知输入框元素： 

<input id="number" min="1" max="10" type="number" />

平常我们获取输入框的值都是使用 number.value 获取的，但是这个属性的返回值是个字符串。

其实现在浏览器支持直接返回数值类型的，使用numer.valueAsNumber即可。

类似的还有valueAsDate属性，适合时间类型的输入框。

详见此文：你知道吗，输入框的value值也能直接返回数值类型 - http://www.zhangxinxu.com/wordpress/?…

第21周 5.19-5.25

Chrome 133实现了attr()函数所有CSS属性都支持，这个特性可就厉害了。

举个例子，有一个链接地址是图片，那么，无需img元素介入，纯CSS就能让这个地址以图片的方式显示出来。

代码示意：

<a href="example.jpg">图片？</a>

[href]::before {   

  content: '';   

  display: block;  

  width: 150px; height: 200px;   

  background: image-set(attr(href));   

  background-size: cover;

}

此时，图片显示的效果就可以实现了。

关于attr()函数更多内容，可以参加此文：“震惊，有生之年居然看到CSS attr()全属性支持” - http://www.zhangxinxu.com/wordpress/?…

第22周 5.26-6.1

本周学习的是JS PageSwapEvent事件，乍一看，以为是页面切换触发的事件。

后来细细一研究，并不是，这个事件发生在，如果页面设置了页面级别的Page Transition过渡效果（URL跳转的页面之间也能平滑过渡，参见下面GIF图），在页面离开的时候，会触发。

主要是方便开发者精确控制页面间的动画细节用的。

这么一看，此事件算是比较小众的，平常开发使用机会并不大，了解下即可。

详见此文：“JS PageSwap PageReveal事件干嘛用的？” -http://www.zhangxinxu.com/wordpress/?…

第23周 6.2-6.8

本周学习的是CSS新的伪元素::scroll-button，其通过特定语法，可以给滚动容器创建自定义的滚动定位按钮，例如：

ul::scroll-button(left) { content: "◄"; } 

ul::scroll-button(right){content:"►";}

配合Scroll Snap，可以纯CSS实现slider效果：

更多内容容我本周继续深入学习。

第24周 6.9-6.15

本周学习::scroll-marker伪元素。

上周学习的::scroll-button()伪元素函数可以给Carousel 效果增加左右切换按钮

这周学习的::scroll-marker则可以给Scroll Snap交互的列表元素创建索引切换按钮，以便定位到具体的元素上，效果参见：

::scroll-marker需要配合scroll-marker-group属性和::scroll-marker-group伪元素一起使用才能生效。

另外，同时被浏览器支持的还有::column伪元素，如果Snap效果是使用columns布局实现的时候使用。

更多内容，可以访问这篇文章：“CSS ::scroll-button ::scroll-marker伪元素又是干嘛用的？” - http://www.zhangxinxu.com/wordpress/?…

第25周 6.16-6.22

本周学习了text-wrap的两个子属性和两个新值。

text-wrap:pretty声明和text-wrap:wrap是一样的，区别在于text-wrap:pretty更注重排版，而非性能，也就是wrap的算法速度更快。

text-wrap:stable可以让编辑内容前面的行内容保持稳定，而不会整个文本内容发生排版变化。

两个子属性，一个是text-wrap-mode，还有一个是text-wrap-style。

更多相关内容参见这篇文章：text-wrap进化:支持两子属性和pretty stable新值 - http://www.zhangxinxu.com/wordpress/?…

第26周 6.23-6.29

本周学习clip-path shape()函数。

之前的路径剪裁使用的是path()函数，但是会有尺寸无法自适应的问题。

因为SVG路径里面的数值都是固定的像素px大小，在SVG元素中，这些大小与SVG外部尺寸关联，不会有问题，但是，放在CSS图像中，那就问题大了。

例如，Font Awesome小图标SVG基本尺寸都是512*512，其path坐标值都是好几百的值。

但是，CSS小图标的尺寸是20*20，如果应用几百数值的剪裁路径，小图标肯定就有问题，对不对？

要么path坐标等比例缩小，要么CSS小图标尺寸也设成512像素，然后再zoom缩放，但这样实现就很麻烦。

于是，在这个背景下，clip-path的shape()函数应运而生。

.use-shape {  

  clip-path: shape(from 50% 0%,curve to 0% 50% with 22.38% 0%/0% 22.38%,smooth by 50% 50% with 22.38% 50%,smooth by 50% -50% with 50% -22.38%,smooth to 50% 0% with 77.62% 0%,close);

}

支持百分比值，和CSS calc等数学函数，自动和元素尺寸相适应，就很厉害！

对此，我还专门开发了一个CSS clip-path path() to shape()函数转换工具 - http://www.zhangxinxu.com/sp/path2sha…

详见我撰写的这篇文章：“CSS小图标剪裁终极解决方案clip-path shape()函数” - http://www.zhangxinxu.com/wordpress/?…

-------------

好，以上就是我这个40岁的老前端上半年学习的内容，下半年我还将继续学习，继续保持对前端的好奇心，欢迎关注，转发，一起进步。

你给后台管理系统加了一个「企业风采」模块，运营同学一口气上传了 200 张 8K 宣传海报。首屏直接飙到 8.3 s，LCP 红得发紫。

老板一句「能不能像朋友圈那样滑到哪看到哪？」——于是你把懒加载重新翻出来折腾了一轮。

解决方案：三条技术路线，你全踩了一遍

1. 最偷懒：原生 loading="lazy"

一行代码就能跑，浏览器帮你搞定。

<img

  src="https://cdn.xxx.com/poster1.jpg"

  loading="lazy"

  decoding="async"

  width="800" height="450"

/>

🔍 关键决策点

• loading="lazy" 2020 年后现代浏览器全覆盖，IE 全军覆没。


• 必须写死 width/height，否则 CLS 会抖成 PPT。

适用场景：内部系统、用户浏览器可控，且图片域名已开启 Accept-Ranges: bytes（支持分段加载）。

2. 最稳妥：scroll 节流 + getBoundingClientRect

老项目里还有 5% 的 IE11 用户，我们只能回到石器时代。

// utils/lazyLoad.js

const lazyImgs = [...document.querySelectorAll('[data-src]')];

let ticking = false;



const loadIfNeeded = () => {

  if (ticking) return;

  ticking = true;

  requestAnimationFrame(() => {

    lazyImgs.forEach((img, idx) => {

      const { top } = img.getBoundingClientRect();

      if (top < window.innerHeight + 200) { // 提前 200px 预加载

        img.src = img.dataset.src;

        lazyImgs.splice(idx, 1); // 🔍 及时清理，防止重复计算

      }

    });

    ticking = false;

  });

};



window.addEventListener('scroll', loadIfNeeded, { passive: true });

🔍 关键决策点

• 用 requestAnimationFrame 把 30 ms 的节流降到 16 ms，肉眼不再掉帧。


• 预加载阈值 200 px，实测 4G 网络滑动不白屏。

缺点：滚动密集时 CPU 占用仍高，列表越长越卡。

3. 最优雅：IntersectionObserver 精准观测

新项目直接上 Vue3 + TypeScript，我们用 IntersectionObserver 做统一调度。

// composables/useLazyLoad.ts

export const useLazyLoad = (selector = '.lazy') => {

  onMounted(() => {

    const imgs = document.querySelectorAll<HTMLImageElement>(selector);

    const io = new IntersectionObserver(

      (entries) => {

        entries.forEach((e) => {

          if (e.isIntersecting) {

            const img = e.target as HTMLImageElement;

            img.src = img.dataset.src!;

            img.classList.add('fade-in'); // 🔍 加过渡动画

            io.unobserve(img);            // 观测完即销毁

          }

        });

      },

      { rootMargin: '100px', threshold: 0.01 } // 🔍 提前 100px 触发

    );

    imgs.forEach((img) => io.observe(img));

  });

};

原理剖析：从「事件驱动」到「观测驱动」

一句话总结：把「我每隔 16 ms 问一次」变成「浏览器你告诉我啥时候到」。

应用扩展：把懒加载做成通用指令

在 Vue3 项目里，我们干脆封装成 v-lazy 指令，任何元素都能用。

// directives/lazy.ts

const lazyDirective = {

  mounted(el: HTMLImageElement, binding) {

    const io = new IntersectionObserver(

      ([entry]) => {

        if (entry.isIntersecting) {

          el.src = binding.value; // 🔍 binding.value 就是 data-src

          io.disconnect();

        }

      },

      { rootMargin: '50px 0px' }

    );

    io.observe(el);

  },

};



app.directive('lazy', lazyDirective);

模板里直接写：

<img v-lazy="item.url" :alt="item.title" />

举一反三：三个变体场景思路

小结

• 浏览器新特性能救命的，就别再卷节流函数了。


• 写死尺寸、加过渡、及时 unobserve，是懒加载不翻车的三件套。


• 把观测器做成指令/组合式函数，后续业务直接零成本接入。

现在你的「企业风采」首屏降到 1.2 s，老板滑得开心，运营继续传 8K 图，世界和平。

从前端到爆点！抖音级 H5 如何炼成？

在万物互联的时代，H5 页面已成为产品推广的利器。当产品经理丢给你一个“像抖音一样流畅的 H5”任务时，是挑战还是机遇？别慌，今天就带你走进抖音 H5 的前端魔法世界。

一、先看清本质：抖音 H5 为何丝滑？

抖音 H5 之所以让人欲罢不能，核心在于两点：极低的卡顿率和极致的交互反馈。前者靠性能优化，后者靠精心设计的交互逻辑。比如，你刷视频时的流畅下拉、点赞时的爱心飞舞，背后都藏着前端开发的“小心机”。

二、性能优化：让页面飞起来

（一）懒加载与预加载协同作战

懒加载是 H5 性能优化的经典招式，只在用户即将看到某个元素时才加载它。但光靠懒加载还不够，聪明的抖音 H5 还会预加载下一个可能进入视野的元素。以下是一个基于 IntersectionObserver 的懒加载示例：

document.addEventListener('DOMContentLoaded', () => {

  const lazyImages = [].slice.call(document.querySelectorAll('img.lazy'));

  if ('IntersectionObserver' in window) {

    let lazyImageObserver = new IntersectionObserver((entries) => {

      entries.forEach((entry) => {

        if (entry.isIntersecting) {

          let lazyImage = entry.target;

          lazyImage.src = lazyImage.dataset.src;

          lazyImageObserver.unobserve(lazyImage);

        }

      });

    });

 lazy   Images.forEach((lazyImage) => {

      lazyImageObserver.observe(lazyImage);

    });

  }

});

（二）图片压缩技术大显神威

图片是 H5 的“体重”大户。抖音 H5 常用 WebP 格式，它在保证画质的同时，能将图片体积压缩到 JPEG 的一半。你可以用以下代码轻松实现图片格式转换：

function compressImage(inputImage, quality) {

  return new Promise((resolve) => {

    const canvas = document.createElement('canvas');

    const ctx = canvas.getContext('2d');

    canvas.width = inputImage.naturalWidth;

    canvas.height = inputImage.naturalHeight;

    ctx.drawImage(inputImage, 0, 0, canvas.width, canvas.height);

    const compressedImage = new Image();

    compressedImage.src = canvas.toDataURL('image/webp', quality);

    compressedImage.onload = () => {

      resolve(compressedImage);

    };

  });

}

三、交互设计：让用户欲罢不能

（一）微动画营造沉浸感

在点赞、评论等关键操作上，抖音 H5 会加入精巧的微动画。比如点赞时的爱心从手指位置飞出，这其实是一个 CSS 动画加 JavaScript 事件监听的组合拳。以下是一个简易版的点赞动画代码：

@keyframes flyHeart {

  0% {

    transform: scale(0) translateY(0);

    opacity: 0;

  }

  50% {

    transform: scale(1.5) translateY(-10px);

    opacity: 1;

  }

  100% {

    transform: scale(1) translateY(-20px);

    opacity: 0;

  }

}

.heart {

  position: fixed;

  width: 30px;

  height: 30px;

  background-image: url('../assets/heart.png');

  background-size: contain;

  background-repeat: no-repeat;

  animation: flyHeart 1s ease-out;

}

document.querySelector('.like-btn').addEventListener('click', function(e) {

  const heart = document.createElement('div');

  heart.className = 'heart';

  heart.style.left = e.clientX + 'px';

  heart.style.top = e.clientY + 'px';

  document.body.appendChild(heart);

  setTimeout(() => {

    heart.remove();

  }, 1000);

});

（二）触摸事件优化

在移动设备上，触摸事件的响应速度直接影响用户体验。抖音 H5 通过精准控制触摸事件的捕获和冒泡阶段，减少了延迟。以下是一个优化触摸事件的示例：

const touchStartHandler = (e) => {

  e.preventDefault(); // 防止页面滚动干扰

  // 处理触摸开始逻辑

};



const touchMoveHandler = (e) => {

  // 处理触摸移动逻辑

};



const touchEndHandler = (e) => {

  // 处理触摸结束逻辑

};



const element = document.querySelector('.scrollable-container');

element.addEventListener('touchstart', touchStartHandler, { passive: false });

element.addEventListener('touchmove', touchMoveHandler, { passive: false });

element.addEventListener('touchend', touchEndHandler);

四、音频处理：让声音为 H5 增色

抖音 H5 的音频体验也很讲究。它会根据用户的操作实时调整音量，甚至在不同视频切换时平滑过渡音频。以下是一个简单的声音控制示例：

const audioContext = new (window.AudioContext || window.webkitAudioContext)();

const audioElement = document.querySelector('audio');

const audioSource = audioContext.createMediaElementSource(audioElement);

const gainNode = audioContext.createGain();

audioSource.connect(gainNode);

gainNode.connect(audioContext.destination);



// 调节音量

function setVolume(level) {

  gainNode.gain.value = level;

}



// 音频淡入效果

function fadeInAudio() {

  gainNode.gain.setValueAtTime(0, audioContext.currentTime);

  gainNode.gain.linearRampToValueAtTime(1, audioContext.currentTime + 1);

}



// 音频淡出效果

function fadeOutAudio() {

  gainNode.gain.linearRampToValueAtTime(0, audioContext.currentTime + 1);

}

五、跨浏览器兼容：让 H5 无处不在

抖音 H5 能在各种浏览器上保持一致的体验，这离不开前端开发者的兼容性优化。常用的手段包括使用 Autoprefixer 自动生成浏览器前缀、为老浏览器提供 Polyfill 等。以下是一个为 CSS 动画添加前缀的示例：

const autoprefixer = require('autoprefixer');

const postcss = require('postcss');



const css = '.example { animation: slidein 2s; } @keyframes slidein { from { transform: translateX(0); } to { transform: translateX(100px); } }';



postcss([autoprefixer]).process(css).then(result => {

  console.log(result.css);

  /*

   输出：

   .example {

     animation: slidein 2s;

   }

   @keyframes slidein {

     from {

       -webkit-transform: translateX(0);

              transform: translateX(0);

     }

     to {

       -webkit-transform: translateX(100px);

              transform: translateX(100px);

     }

   }

  */

});

打造一个像抖音一样的流畅 H5，需要前端开发者在性能优化、交互设计、音频处理和跨浏览器兼容等方面全方位发力。希望这些技术点能为你的 H5 开发之旅提供助力，让你的产品在激烈的市场竞争中脱颖而出！

大多数前端开发者在公司里，很少需要直接操心“部署”这件事——那通常是运维或 DevOps 的工作。

但一旦回到个人项目，情况就完全不一样了。写个小博客、搭个文档站，或者搞个 demo 想给朋友看，部署往往成了最大的拦路虎。

常见的选择无非是 Vercel、Netlify 或 GitHub Pages。它们表面上“一键部署”，但细节其实并不轻松：要注册平台账号、要配置域名，还得接受平台的各种限制。国内的一些云服务商（比如阿里云、腾讯云）管控更严格，操作门槛也更高。更让人担心的是，一旦平台宕机，或者因为地区网络问题导致访问不稳定，你的项目可能随时“消失”在用户面前。虽然这种情况不常见，但始终让人心里不踏实。

很多时候，我们只是想快速上线一个小页面，不想被部署流程拖累，有没有更好的方法？

一个更轻的办法

前段时间我发现了一个开源工具 PinMe，主打的就是“极简部署”。

它的使用体验非常直接：

• 不需要服务器


• 不用注册账号


• 在项目目录敲一条命令，就能把项目打包上传到 IPFS 网络


• 很快，你就能拿到一个可访问的地址

实际用起来的感受就是一个字：爽。

整个过程几乎没有繁琐配置，不需要绑定平台账号，也不用担心流量限制或收费。

这让很多场景变得顺手：

• 临时展示一个 demo，不必折腾服务器


• 写了个静态博客，不想搞 CI/CD 流程


• 做了个活动页或 landing page，随时上线就好

以前这些需求可能要纠结“用 GitHub Pages 还是 Vercel”，现在有了 PinMe，直接一键上链就行。

体验一把

接下来看看它在真实场景下的表现：部署流程有多简化？访问速度如何？和传统方案相比有没有优势？

测试项目

为了覆盖不同体量的场景，这次我选了俩类项目来测试：

• 小型项目：fuwari（开源的个人博客项目），打包体积约 4 MB。


• 中大型项目：Soybean Admin（开源的后台管理系统），打包体积约 15 MB。

部署项目

PinMe 提供了两种方式：命令行 和 可视化界面。

这两种方式我们都来试一下。

命令行部署

先全局安装：

npm install -g pinme

然后一条命令上传：

pinme upload <folder/file-path>

比如上传 Soybean Admin，文件大小 15MB：

输入命令之后，等着就可以了：

只用了两分钟，终端返回的 URL 就能直接访问项目的控制页面。还能绑定自己的域名：

点击网站链接就可以看到已经部署好的项目，访问速度还是挺快的：

同样地，上传个人博客也是一样的流程。

部署完成：

可视化部署

不习惯命令行？PinMe 也提供了网页上传，进度条实时显示：

部署完成后会自动进入管理页面：

经过测试，部署速度和命令行几乎一致。

其他功能

历时记录

部署过的网站都能在主页的 History 查看：

历史部署记录：

也可以用命令行：

pinme list

历史部署记录：

删除网站

如果不再需要某个项目，执行以下命令即可：

pinme rm

PinMe 背后的“硬核支撑”

如果只看表层，PinMe 就像一个极简的托管工具。但要理解它为什么能做到“不依赖平台”，还得看看它背后的底层逻辑。

PinMe 的底层依赖 IPFS，这是一个去中心化的分布式文件系统。

要理解它的意义，得先聊聊“去中心化”这个概念。

传统互联网是中心化的：你访问一个网站时，浏览器会通过 DNS 找到某台服务器，然后从这台服务器获取内容。这条链路依赖强烈，一旦 DNS 被劫持、服务器宕机、服务商下线，网站就无法访问。

去中心化的思路完全不同：

• 数据不是放在单一服务器，而是分布在全球节点中


• 访问不依赖“位置”，而是通过内容哈希来检索


• 只要有节点存储这份内容，就能访问到，不怕单点故障

这意味着：

• 更稳定：即使部分节点宕机，内容依然能从其他节点获取。


• 防篡改：文件哪怕改动一个字节，对应的 CID 也会完全不同，从机制上保障了前端资源的完整性和安全性。


• 更自由：不再受制于中心化平台，文件真正由用户自己掌控。

当然，IPFS 地址（哈希）太长，不适合直接记忆和分享。这时候就需要 ENS（Ethereum Name Service）。它和 DNS 类似，但记录存储在以太坊区块链上，不可能被篡改。比如你可以把 myblog.eth 指向某个 IPFS 哈希，别人只要输入 ENS 域名就能访问，不依赖传统 DNS，自然也不会被劫持。

换句话说：

ENS + IPFS = 内容去中心化 + 域名去中心化

前端个人项目瞬间就有了更高的自由度和安全性。

一点初步感受

PinMe 并不是要取代 Vercel 这类成熟平台，但它带来了一种新的选择：更简单、更自由、更去中心化。

如果你只是想快速上线一个小项目，或者对去中心化部署感兴趣，PinMe 值得一试。

• 官网：pinme.eth.limo/


• Github：github.com/glitternetw…

这是一个完全开源的项目，开发团队也会持续更新。如果你在测试过程中有想法或需求，不妨去 GitHub 提个 Issue —— 这不仅能帮助项目成长，也能让它更贴近前端开发的实际使用场景！

从“版本号打架”到 30 秒内提醒用户刷新：一个微前端团队的实践

1. 背景与痛点

我们团队维护着一个微前端子应用集群，每个子应用都需要同时服务 dev / test / release / online 多套环境。分支策略（master / release / test / dev / hotfix / feature_x.x.x）加上 Jenkins 自动化，让“一天多次发布”成为常态。但真正影响交付效率的并不是发布次数，而是一个顽固的问题：测试同学常年停留在旧版本页面。

1.1 真实场景

• 测试在早上打开 dev 页面，下午我们发布了新的组件样式；
• 他们继续在旧页面里回归，反馈的问题我们一眼看出“这是老版本”；
• 群里喊“刷新一下”并不靠谱，于是“无效缺陷 + 反复沟通”成了常态。

更严重的一次事故，是我们在版本检查逻辑里同时使用了 webpack DefinePlugin 与自定义插件，各自调用了一次 getAppVersion()。结果前端控制台打印的是 0.8.3-release-202511210828，而 version.json 里是 0.8.3-release-202511210829。两边只差 1 秒钟，却让线上用户始终被提示刷新，形象地被团队称为“版本号打架”。

1.2 我们的诉求

0. 用户在 30 秒内感知版本更新；
1. 弹窗里能看到“当前版本 / 最新版本 / 环境”；
2. 支持“立即刷新 / 稍后再说”，不给用户造成中断；
3. 方案需兼容现有微前端架构与 CI/CD 流程，不依赖后端改造。

2. 方案探索与取舍

在动手前，我们列出几种可行方式：

方案	实现复杂度	实时性	依赖	适配场景	关键优缺点
纯前端轮询 version.json	低	中（30s）	前端 + Nginx	多环境微前端	成本最低；轻微网络开销
Service Worker/PWA	中	较高	现代浏览器	PWA 应用	缓存控制好，但改造量大
WebSocket 推送	高	最高	后端服务	强实时场景	需要额外服务端开发
后端接口统一管理	中	中	前后端	版本集中管理	带来跨团队耦合

综合团队资源与落地速度，我们选择了 纯前端轮询 + 静态版本文件 的做法，并明确两个原则：

• 版本号唯一，可追溯：基础版本号-环境-时间戳；
• 发布零侵入：Jenkins 仍旧运行 npm run build-xxx，无需新增步骤。

3. 技术方案总览

0. 构建阶段生成 version.json：在 vue.config.js 中提前计算版本号，既注入到前端（process.env.APP_VERSION），也写入输出目录的 version.json；
1. 前端轮询比对：应用启动后每 30 秒请求一次 version.json，禁用缓存并携带时间戳，比较版本号；
2. 交互提示：复用 Ant Design Vue 的 Modal.confirm，展示当前/最新版本与环境；
3. 缓存策略：Nginx 对 HTML/version.json 禁止缓存，对 JS/CSS/图片继续长缓存；
4. CI/CD 配合：所有环境沿用既有脚本，只是构建产物目录多了一份实时的 version.json。

4. 关键落地细节

4.1 版本号只生成一次（Build-time Deterministic Versioning）

vue.config.js 抽象 buildEnvName、buildVersion，并在 DefinePlugin 与生成 version.json 时复用：

const buildEnvName = getEnvName();

const buildVersion = getAppVersion();



module.exports = {

  configureWebpack: {

    plugins: [

      new webpack.DefinePlugin({

        "process.env.APP_VERSION": JSON.stringify(buildVersion),

        "process.env.APP_ENV": JSON.stringify(buildEnvName),

      }),

    ],

  },

  chainWebpack(config) {

    config.plugin("generate-version-json").use({

      apply(compiler) {

        compiler.hooks.done.tap("GenerateVersionJsonPlugin", () => {

          fs.writeFileSync(

            path.resolve(__dirname, "edu/version.json"),

            JSON.stringify(

              {

                version: buildVersion,

                env: buildEnvName,

                timestamp: new Date().toISOString(),

                publicPath: "/child/edu",

              },

              null,

              2

            )

          );

        });

      },

    });

  },

};

这样即使构建过程持续 5～10 分钟，注入的版本号和静态文件里的版本仍保持一致。这其实是把“构建产物视为不可变工件”的原则落地——保证任何使用该工件的入口看到的元数据都是同一个快照。

4.2 版本检查器（Runtime Polling & Cache Busting）

class VersionChecker {

  currentVersion = process.env.APP_VERSION;

  publicPath = "/child/edu";

  checkInterval = 30 * 1000;



  init() {

    console.log(`📌 当前前端版本：${this.currentVersion}（${process.env.APP_ENV}）`);

    this.startChecking();

    document.addEventListener("visibilitychange", () => {

      if (document.visibilityState === "visible" && !this.hasNotified) {

        this.checkForUpdate();

      }

    });

  }



  async checkForUpdate() {

    const url = `${this.publicPath}/version.json?t=${Date.now()}`;

    const response = await fetch(url, { cache: "no-store" });

    if (!response.ok) return;

    const latestInfo = await response.json();

    if (latestInfo.version !== this.currentVersion && !this.hasNotified) {

      this.hasNotified = true;

      this.stopChecking();

      this.showUpdateModal(latestInfo.version, latestInfo.env);

    }

  }

}

这里有两个容易被忽略的细节：

0. fetch 显式加 cache: "no-store"，再叠加时间戳参数，防止 CDN / 浏览器任何一层干预；
1. visibilitychange 监听，保证窗口重新激活时立即比对，避免用户在后台等了很久才看到弹窗。

入口 main.ts 在应用 mount 之后调用 versionChecker.init()，即可把整个检测链路串起来。

4.3 Nginx 缓存策略（Precise Cache Partition）

location / {

    if ($request_filename ~* .html$) {

        add_header Cache-Control "no-store, no-cache, must-revalidate";

    }

}



location /child/edu {

    if ($request_filename ~* .html$) {

        add_header Cache-Control "no-store, no-cache, must-revalidate";

    }

}



location ~* /child/edu/version.json$ {

    add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate";

    add_header Pragma "no-cache";

    add_header Expires "0";

    add_header Surrogate-Control "no-store";

}

这一层的思路是把资源分成两类：需要实时性（HTML、version.json）就 no-store，其余走长缓存。再配合 try_files 兜底 history 路由，微前端子应用的独立部署不会互相影响。