普通视图

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

今天 — 2026年2月12日掘金前端

掘金前端
React性能优化三剑客：useEffect、useMemo与useCallback实战手册QLuckyStar
2026年2月12日 11:48

React性能优化三剑客：useEffect、useMemo与useCallback实战手册

掘金前端

作者 QLuckyStar

2026年2月12日 11:48

废话不多说，直接上干货，兄弟们，注意了，我要开始装逼了：

一、`useEffect`：副作用管理

核心作用

处理与渲染无关的副作用（如数据获取、订阅事件、定时器、DOM 操作等），并支持清理逻辑。

基本语法

useEffect(() => {
  // 副作用逻辑
  return () => {
    // 清理逻辑（可选）
  };
}, [依赖项]);

使用场景

数据获取

useEffect(() => {
  fetch("/api/data")
    .then(res => setData(res));
}, []); // 仅在挂载时获取

事件监听

useEffect(() => {
  const handleResize = () => setWidth(window.innerWidth);
  window.addEventListener("resize", handleResize);
  return () => window.removeEventListener("resize", handleResize);
}, []); // 清理监听器

定时器

useEffect(() => {
  const timer = setInterval(() => setCount(c => c + 1), 1000);
  return () => clearInterval(timer);
}, []); // 清理定时器

最佳实践

依赖数组：精确控制执行时机，避免遗漏依赖导致闭包问题。
清理函数：移除订阅、清除定时器，防止内存泄漏。
避免无限循环：若副作用中修改状态，使用函数式更新（如 setCount(prev => prev + 1)）。

二、`useMemo`：计算结果缓存

核心作用

缓存复杂计算结果，避免重复执行高开销操作（如排序、过滤、深拷贝）。

基本语法

const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);

使用场景

复杂计算

const filteredList = useMemo(() => 
  list.filter(item => item.price > 100), 
  [list] // 仅当 list 变化时重新计算
);

避免重复渲染

const userInfo = useMemo(() => ({ name, age }), [name, age]);
return <Child user={userInfo} />; // 稳定引用，避免子组件重渲染

最佳实践

依赖项完整：包含所有影响计算结果的变量。
避免滥用：简单计算无需缓存，直接执行即可。
**配合 React.memo**：缓存子组件，提升渲染性能。

三、`useCallback`：函数引用缓存

核心作用

缓存函数引用，避免因父组件重新渲染导致子组件不必要的重渲染。

基本语法

const memoizedFn = useCallback(() => {
  doSomething(a, b);
}, [a, b]);

使用场景

传递回调函数

const handleClick = useCallback(() => {
  console.log("Clicked");
}, []);
return <Button onClick={handleClick} />;

**配合 useEffect**

const fetchData = useCallback(async () => {
  const data = await fetch("/api");
  setData(data);
}, []);
useEffect(() => fetchData(), [fetchData]);

最佳实践

依赖项精准：确保函数内部使用的变量均包含在依赖数组中。
避免过度优化：仅在需要稳定引用时使用（如传递给 React.memo 子组件）。

四、三者的核心区别

Hook	核心用途	返回值	典型场景
`useEffect`	处理副作用（数据获取、订阅）	无（返回清理函数）	API 请求、事件监听
`useMemo`	缓存计算结果	计算后的值	复杂计算、避免重复渲染
`useCallback`	缓存函数引用	函数	传递回调、优化子组件渲染

五、`useEffect` 最佳实践与闭包陷阱规避

1. 依赖项管理

核心原则：依赖数组必须包含所有在 effect 中使用的 外部变量（包括 state、props、上下文等）。

// 错误示例：未包含依赖项，导致闭包捕获旧值
const [count, setCount] = useState(0);
useEffect(() => {
  const timer = setInterval(() => {
    console.log(count); // 始终输出初始值 0
  }, 1000);
  return () => clearInterval(timer);
}, []); // ❌ 依赖数组为空

// 正确做法：将 count 加入依赖数组
useEffect(() => {
  const timer = setInterval(() => {
    console.log(count); // 实时输出最新值
  }, 1000);
  return () => clearInterval(timer);
}, [count]); // ✅

问题根源：未声明依赖项时，effect 仅在挂载时执行一次，闭包中捕获的 count 是初始值。

2. 清理函数

场景：定时器、事件监听、DOM 操作等需在组件卸载或依赖变化时清理。

useEffect(() => {
  const handleResize = () => console.log("窗口大小变化");
  window.addEventListener("resize", handleResize);
  return () => window.removeEventListener("resize", handleResize); // ✅ 清理监听器
}, []);

3. 避免无限循环

问题：effect 中修改状态且依赖该状态。

// 错误示例：依赖项包含 state，导致循环触发
const [data, setData] = useState([]);
useEffect(() => {
  fetchData().then((res) => setData(res)); // 触发重新渲染 → effect 重新执行
}, [data]); // ❌

解决方案：移除冗余依赖，或使用函数式更新：

useEffect(() => {
  fetchData().then((res) => setData((prev) => [...prev, ...res])); // ✅ 无依赖
}, []);

4. 复杂异步操作

最佳实践：在 effect 内部定义异步函数，避免直接 async 修饰回调。

useEffect(() => {
  let isMounted = true; // 防止卸载后更新状态
  const fetchData = async () => {
    const res = await api.getData();
    if (isMounted) setData(res);
  };
  fetchData();
  return () => { isMounted = false; }; // 清理标志位
}, []);

六、`useMemo` 和 `useCallback` 的真正使用场景

1. `useMemo`：缓存计算结果

适用场景：
- 高开销计算：如大数据排序、复杂公式、深拷贝。
- 派生状态：根据 state/props 生成新对象或数组。
- DOM 节点引用：如 useRef 存储 DOM 元素（需配合 useLayoutEffect）。

避免滥用：

简单计算（如 a + b）无需缓存。
频繁变化的依赖项（如 useMemo 依赖项变化频繁时反而降低性能）。

// 正确使用：缓存复杂计算
const filteredData = useMemo(() => {
  return data.filter(item => item.price > 100);
}, [data]);

// 错误使用：缓存简单值
const simpleValue = useMemo(() => 42, []); // ❌ 无意义

2. `useCallback`：缓存函数引用

适用场景：
- 传递回调给子组件：子组件使用 React.memo 时，避免因父组件重渲染导致子组件无效更新。
- 依赖外部变量的函数：如事件处理器中依赖 state/props。

避免滥用：

仅在需要稳定引用时使用（如传递给 useEffect 或子组件）。
内部函数无需缓存（如仅在组件内部使用的函数）。

// 正确使用：缓存事件处理器
const handleClick = useCallback(() => {
  console.log("Clicked");
}, []);

// 错误使用：缓存内部函数
const internalFn = useCallback(() => {
  // 仅在组件内部使用，无需缓存
}, []);

七、避免过度优化的关键原则

1. 性能问题驱动优化

先定位瓶颈：使用 React DevTools 的 Profiler 分析组件渲染开销。
针对性优化：仅在渲染耗时或计算密集型场景使用 useMemo/useCallback。

2. 依赖项管理

完整声明：使用 ESLint 的 react-hooks/exhaustive-deps 规则强制检查。
避免冗余依赖：如 useMemo 依赖项中包含未使用的变量。

3. 简单场景优先

优先使用普通变量：如 const value = someData; 而非 useMemo(() => someData, [])。
函数内部使用：无需缓存仅在组件内部调用的函数。

八、实战案例对比

场景：商品列表筛选

未优化版本（频繁重渲染）：

const ProductList = ({ products, filter }) => {
  const filtered = products.filter(/* 复杂逻辑 */);
  return <List items={filtered} />;
};

优化后版本：

const ProductList = ({ products, filter }) => {
  const filtered = useMemo(() => {
    return products.filter(/* 复杂逻辑 */);
  }, [products, filter]); // 仅当数据或筛选条件变化时重新计算
  return <List items={filtered} />;
};

九、总结

Hook	核心用途	避坑指南
`useEffect`	副作用管理（数据获取、订阅）	依赖项完整、清理函数、避免循环
`useMemo`	缓存计算结果	仅高开销计算、避免简单值缓存
`useCallback`	缓存函数引用	仅传递给 memo 子组件、避免内部函数

关键口诀：
“无必要，不优化；有性能问题，再针对性解决”。过度使用 Hooks 反而会增加代码复杂度和内存开销。

模块联邦 2.0 稳定版发布：兼顾开发效率与极致性能

掘金前端

作者 WebInfra

2026年2月12日 11:37

Frame 1912055630@2x (2).png

本文作者为 Web Infra 团队 - 2heal1

一年前，我们将模块联邦 2.0 预览版正式开源，收获了社区众多宝贵的反馈与建议。我们深知，一个成熟的微前端解决方案，不仅要能提升协同开发的效率，更需具备驱动极致性能的内核。因此，我们选择用一年的时间进行深度打磨与能力拓展。

今天，我们很高兴地宣布：模块联邦 2.0 稳定版正式发布。它不仅带来了强大的性能优化能力，还覆盖了更全面的部署场景，并对开发者体验进行了深度优化。

全链路性能优化体系

模块联邦 2.0 从 构建、资源加载、渲染到数据获取 四个层面，对微前端应用的性能路径进行了系统性重构。

这些能力并非孤立存在，而是协同工作，形成一套面向模块联邦场景的端到端性能优化体系。

所有能力均支持渐进式接入，你可以按需启用，不需要一次性改造现有架构，也不会影响已有系统的稳定性。

共享依赖 Tree Shaking

传统共享依赖虽然避免了重复加载，但为了保证完整性，shared 库往往会被 整库构建并暴露，即使只用到一小部分，也必须加载全部内容，导致包体积持续膨胀。

在模块联邦 2.0 中，这一问题被解决：

共享依赖也支持 Tree Shaking 了。

只需开启 treeShaking，MF 即可在不破坏模块联邦动态性的前提下，对共享依赖进行按需裁剪，仅保留真正可能被用到的模块，大幅减少 shared bundle 体积，并保持对现有项目的完全兼容。

模块联邦 2.0 提供两种模式来适配不同场景：

runtime-infer :零依赖、即开即用。运行时优先复用已加载的 Tree-Shaken 共享包，若能力不足则自动回退加载完整依赖，保证功能完备；可通过 usedExports 提升复用率。
server-calc :通过服务端或 CI 统一分析多个应用的依赖使用情况，生成全局最优的共享裁剪结果，适用于大型系统。

同时配套可视化分析页面，让共享依赖的使用情况与体积收益一目了然。

以 Ant Design 这类大型组件库为例，当应用仅使用 Badge、Button、List 三个组件时，在未启用共享依赖 Tree Shaking 的情况下，共享产物体积约为 1404.2 KB；启用该能力后，实际加载体积降至 344.0 KB，减少了约 75.5% 的非必要代码。

分析结果

服务端渲染（SSR）

SSR 通过在服务器端直接生成完整 HTML 并返回给浏览器，使页面无需等待客户端渲染即可显示，大幅提升首屏加载速度与SEO 表现。在中大型 Web 应用中，SSR 已成为事实上的标准能力。

但在微前端架构下，SSR 一直难以落地。早期 MF 并未覆盖这一能力，开发者不得不在架构灵活性与性能收益 之间做取舍。

在模块联邦 2.0 中，这一矛盾被消除。

你可以在 Modern.js 中直接使用 MF SSR，让微前端应用同样具备高性能的服务端渲染能力。

同构的数据预取方案

模块联邦 2.0 提供了一套全新的 同构数据获取方案，同时支持 SSR 与 CSR 场景，并内置 prefetch 与 cache API，用于统一数据预取与缓存管理，在不同渲染模式下都能获得稳定、可预测的性能收益。

通过预加载与缓存机制，页面可以在渲染前就准备好关键数据，避免重复请求和瀑布流，从而显著优化首屏与交互响应速度。

能力锈化

在大型项目中，Manifest 生成常常成为构建阶段的性能瓶颈。模块联邦 2.0 将这一核心能力迁移至 Rust 实现，充分利用其高性能与内存安全特性，大幅降低 Manifest 生成的时间开销。

同时，AsyncStartUp 也已完成 Rust 化升级。你不再需要配置异步入口即可获得同等能力，相关的首屏性能隐患也被彻底消除，使应用启动路径更加简洁、稳定且高效。

更强大的调试体系

模块联邦 2.0 围绕可观测性与可调试性 构建了一套完整的调试体系，使共享依赖、模块关系以及潜在副作用都可以被 直观查看、精确定位与提前发现，大幅降低动态应用在开发与接入过程中的不确定性。

副作用检测工具

在接入远程模块前，消费者往往需要评估其是否会污染全局变量、注册事件监听或影响样式作用域，这些不确定性是微前端接入成本的重要来源。

模块联邦 2.0 提供 Side Effect Scanner，对产物进行静态分析并识别以下副作用：

全局变量
事件监听
CSS 选择器影响范围

配套的 CLI 工具 可自动完成扫描并输出结果，使消费者在接入前即可掌握风险，从而显著降低联邦模块的集成成本。

Chrome 插件依赖可视化

我们对原有 Chrome 插件进行了全面升级，提供了全新的 UI 与更强的调试能力，让模块联邦的运行状态 可见、可查、可验证。

智能侧边栏同步插件面板会随当前页面自动切换，无需手动刷新或重连，调试体验更加流畅。
共享依赖可视化新增 Shared 面板，可直观查看当前页面的共享依赖加载情况，例如：- React 是否被成功共享 - 实际生效的共享版本 - 帮助你快速确认共享策略是否生效。

依赖关系快速定位

支持在依赖图谱中搜索任意模块，并以清晰的层级结构展示其上下游关系，让复杂依赖一目了然。

依赖图谱

数据裁剪模式在模块数量较多时，可开启裁剪模式以减少代理数据体积，避免因 localStorage 限制导致的注入失败。 被裁剪的数据仅影响预加载分析，不影响实际功能，可安全开启。

更丰富的生态

MF 已覆盖主流的 构建工具、应用框架与 UI 技术栈，可以在不同技术体系下稳定运行，帮助团队在不改变既有技术选型的前提下引入模块联邦能力。

Bundler：Webpack / Rspack / Rollup / Rolldown
Build Tool：Rsbuild / Vite / Metro
Framework/Tool：Modern.js / Next.js / Rspress / Rslib / Storybook
UI Library：React / Vue / React Native

模块联邦 2.0 生态

在此基础上，模块联邦 2.0 进一步将模块联邦能力延伸到更多关键的开发与交付场景中：

Node.js 场景

模块联邦现已可以在 Node.js 运行时中直接使用，使远程模块不仅可以被浏览器加载，也可以在 SSR、BFF 以及 Node 服务层被统一消费，实现前后端一致的模块交付模型。

Rspress 文档分治场景

在 Rspress 中，MF 支持按文档或路由维度拆分并加载远程模块，使大型文档站点可以通过 模块联邦进行分治与独立发布，非常适合多团队协作的文档与知识平台。

Rstest

在 Rstest 测试框架中，模块联邦可以以真实运行时方式加载远程模块，使微前端与模块联邦应用能够进行 更贴近生产环境的集成测试与端到端测试，避免测试与实际运行环境割裂。

变更项

版本变更

我们注重 稳定性与兼容性，因此本次升级不含破坏性变更，仅包含以下微小变更，以下是核心变更说明：

微小变更

library.type 的默认值由 var 变更为 global。
runtimePlugins 支持配置参数。

What's Next?

React Server Component

RSC 是 React 生态的革命性演进。相比 MF x SSR，MF x RSC 组合将带来更极致的性能（体积大幅减少）和更安全的数据操作。我们已在基础 Demo 中跑通该方案，并将在 Modern.js 中提供更好的适配与支持。

AI-friendly Design

我们正在为 MF 逐步补齐 AI 使用组件与模块所需的上下文与元数据，包括能力边界、使用约束、运行环境与依赖关系，并引入可量化的评分与可信度机制，让组件资产能够被 AI 理解、评估与选择。

优化使用 Nuxt3 开发的官网首页，秒开！

掘金前端

作者唐诗

2026年2月12日 11:36

一年前接了个官网的开发的活（这个文章其实也写了一年了！），使用 nuxt3 进行开发，使用 SSG 模式即执行 nuxt generate 后将产物进行部署

测试环境： mac m1 16、谷歌 136

开发部署完成后客户反应说打开速度有点慢，实际测试了下发现确实有点慢，直接看图

在无痕模式禁用缓存的情况需要近 20 多秒才能加载完成，它不正常！

再来看下优化后的加载情况

一秒内！几乎是秒开了，那我都干了什么呢？

开启 http 2.0

让 gpt 先做个总结

特性	HTTP/1.1	HTTP/2.0
协议格式	文本格式	二进制格式
多路复用	不支持，一个连接一次只处理一个请求	支持，一个连接可同时处理多个请求
头部压缩	无（头部冗余较多）	使用 HPACK 进行头部压缩
服务器推送	不支持	支持，服务器可主动推送资源
连接复用	多个请求需多个 TCP 连接或排队	所有请求共享一个 TCP 连接
队头阻塞（HOL）	存在，阻塞严重	解决，通过帧分片并异步处理
加密（TLS）	可选	可选（多数实现默认启用）

还有一个很重要的点是 同一域名下的并发连接数限制 http 1.1 是最多 6个， http 2.0 则是所有请求复用单一连接，通过多路复用并发处理，效率更高

开启 gzip

nuxt3 貌似并没有提供 gzip 压缩的相关操作，这个项目使用 docker 部署在镜像 nginx 中配置了 gzip 压缩

调试面板这样显示表示 gzip 配置成功！

使用 NuxtPicture 优化图片加载

<NuxtPicture
  format="avif,webp"
  :src="getImg('/about/banner.png')"
  :alt="$t('about.title')"
  :img-attrs="{ style: 'width: 100%' }"
  width="1920"
  height="578"
  placeholder
  loading="lazy"
/>

loading img 原生属性图片可见时加载

format 响应式图片加载，单从图片压缩后大小来看 avif < webp < jpg < png 这里是如果浏览器支持 avif or webp 就使用否则使用原始图片也就是 src 设置的图片

响应式图片加载

这里以首页封面图为例

<picture>
  <source type="image/avif" srcset="home/banner.avif">
  <source type="image/webp" srcset="home/banner.webp">
  <img src="home/banner.png" alt="用中文链接世界"class="w-full">
</picture>

<picture> 元素：用于为不同的设备或浏览器条件提供不同的图片资源。
<source> 标签：指定不同格式的图片（如 AVIF、WebP）。
降级加载（Fallback） ：如果浏览器不支持 AVIF，会加载 WebP；都不支持则加载 PNG。

格式	压缩类型	浏览器兼容性	文件大小（相同质量）	加载速度	适用场景
AVIF	有损/无损	较新浏览器支持良好	最小（高压缩率）	快	现代 Web，体积敏感场景
WebP	有损/无损	主流浏览器广泛支持	较小	快	Web 图片优化
PNG	无损	全面支持	大	慢	图标、透明图、高质量图像
JPG	有损	全面支持	中	快	摄影、背景图等色彩丰富图片

通过上边的表格可以看出来同样质量的图片 AVIF、WebP 体积要小于 PNG、JPG 下边来对比一下

AVIF 440KB -> 156KB 减少了 65%

WebP 440KB -> 156KB 减少了 65%

看到这里你觉得也许不过如此！但是如果把图片质量下降到 70 AVIF 图片的体积可以减少到 35KB 减少 92% 的体积

AVIF 与 PNG 加载速度对比

AVIF- 34ms

PNG 3.36秒

1. 字体文件放到 cdn 2. 延迟字体加载

另一个拖慢加载的元凶是字体加载

最初的方式是创建一个 font.scss 文件

@font-face {
  font-family: 'AlibabaPuHuiTi-3-55-Regular';
  src: url('/public/fonts/AlibabaPuHuiTi/AlibabaPuHuiTi-3-55-Regular.woff2') format('woff2');
  font-weight: normal;
  font-style: normal;
  font-display: swap;
}

在 index.scss 中引入

@use './font.scss';

然后配置 nuxt.config.ts

css: [
    '~/assets/style/index.scss',
],

这样做会导致字体文件参与打包并和其他js、css 等文件同时加载

可以这样改把 font.scss 改为 font.css 放到 public/fonts/font.css 中

然后修改 nuxt.config.ts

  app: {
    head: {
      link: [
        {
          rel: 'stylesheet',
          href: '/fonts/font.css',
          media: 'print',
          onload: 'this.media=\'all\'',
        },
      ],
    },
  },

这样 font.css 就会延迟加载从而延迟加载字体文件且字体文件不会参与打包

合理优化图片可以让官网加载速度提升

首页打开加载完成时间从 26 秒减少到 2 秒，性能提升了约 92.31% ，即 13 倍。

总结

通过使用 http2.0 、gzip、图片懒加载、响应式图片加载、延迟字体加载等操作可以让首页达到秒开的效果

就这么简单的几步就可以让首页加载速度提升一个级别

这还是无痕禁用缓存下的数据，如果不禁用缓存还会更快

图片压缩工具是 squoosh.app

学习Three.js--柱状图

掘金前端

作者造轮子的猪

2026年2月12日 11:25

学习Three.js--柱状图

前置核心说明

开发目标

基于Three.js实现ECharts标准风格的3D柱状图，还原ECharts的视觉特征（配色、标签样式、坐标轴风格），同时具备3D场景的交互性与真实光影效果，核心能力包括：

视觉风格还原：精准复刻ECharts柱状图的配色、坐标轴样式、标签样式（轴刻度、轴名称、柱顶数值），兼顾3D立体感与2D可视化的简洁性；
3D场景构建：通过几何体、材质、光照系统打造真实的3D视觉效果，阴影系统增强立体感，避免3D场景的平面化；
2D标签渲染：借助CSS2D渲染器实现灵活的文字标签，解决Three.js原生文字渲染样式受限的问题，贴合ECharts的标签风格；
流畅交互体验：通过轨道控制器实现360°拖拽旋转、滚轮缩放，且启用阻尼效果提升交互顺滑度；
响应式适配：适配不同屏幕尺寸，保证柱状图在PC/平板等设备上无拉伸变形；
循环动画驱动：通过帧动画循环维持交互阻尼与场景渲染的流畅性。

核心技术栈（关键知识点）

技术点	作用
`THREE.Scene/Camera/Renderer`	搭建3D场景基础框架，定义视角、渲染尺寸、抗锯齿等核心属性，是所有3D效果的载体
`THREE.OrbitControls`	实现3D场景的轨道交互（拖拽旋转、滚轮缩放），启用阻尼让交互更自然，适配3D柱状图的查看需求
`CSS2DRenderer/CSS2DObject`	将HTML/CSS创建的文字标签（轴刻度、柱顶数值）绑定到3D空间坐标，实现灵活的样式控制，还原ECharts标签风格
`THREE.MeshStandardMaterial/LineBasicMaterial`	分别实现几何体（柱子、地面）的物理材质（支持光影）和线条（坐标轴）的基础材质，保证视觉质感
`THREE.BoxGeometry/CircleGeometry/BufferGeometry`	构建柱子（立方体）、地面（圆形）、坐标轴（线条）的几何形态，是3D物体的形状基础
`THREE.DirectionalLight/AmbientLight/PointLight`	组合环境光、方向光、点光源，打造分层级的光照效果，增强3D柱子的立体感与真实感
`THREE.ShadowMap`（阴影系统）	开启软阴影并配置阴影参数，让柱子投射自然阴影到地面，提升场景的真实度
响应式窗口监听（`resize`事件）	动态更新相机比例与渲染器尺寸，保证柱状图在不同屏幕下无拉伸变形
`requestAnimationFrame`	驱动动画循环，维持轨道控制器阻尼更新与场景渲染的流畅性（60帧/秒）

核心开发流程

graph TD
    A["初始化场景/相机/渲染器/轨道控制器"] --> B["初始化CSS2D渲染器（标签渲染）"]
    B --> C["构建光照系统（环境光+主光源+辅助光）"]
    C --> D["定义图表数据与视觉配置参数"]
    D --> E["构建地面与网格辅助线（视觉锚点）"]
    E --> F["构建坐标轴系统（X/Y轴+刻度+名称标签）"]
    F --> G["构建柱状图主体（几何体+材质+柱顶数值标签）"]
    G --> H["添加辅助线/装饰元素（Z轴短线、原点装饰）"]
    H --> I["绑定窗口resize事件（响应式适配）"]
    I --> J["启动动画循环（更新控制器+渲染场景）"]

分步开发详解

步骤1：基础环境搭建（场景/相机/渲染器/控制器）

搭建Three.js 3D场景的核心框架，为柱状图提供基础的展示载体与交互能力，兼顾视角合理性与渲染清晰度。

1.1 核心代码（对应原代码1）

// 初始化场景、相机、渲染器
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xf5f7fa); // 柔和灰白背景，贴合ECharts容器

const camera = new THREE.PerspectiveCamera(
    45, // 更小视角，减少畸变，更接近2D感
    window.innerWidth / window.innerHeight,
    0.1,
    1000
);
camera.position.set(9, 7, 14);
camera.lookAt(4, 3, 0);

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.shadowMap.enabled = true;        // 开启阴影，更真实
renderer.shadowMap.type = THREE.PCFSoftShadowMap;
renderer.setPixelRatio(window.devicePixelRatio);
document.body.appendChild(renderer.domElement);

// 轨道控制器，带阻尼
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;
controls.dampingFactor = 0.06;
controls.autoRotate = false;
controls.enableZoom = true;
controls.target.set(4, 3, 0);
controls.minDistance = 8;
controls.maxDistance = 30;

1.2 关键说明

相机参数优化：
- 视角45°：相比默认的75°，更小的视角减少3D畸变，让柱状图更接近ECharts的2D视觉风格，同时保留3D纵深；
- 位置(9,7,14)+注视点(4,3,0)：采用“斜上方俯视”视角，既可以清晰看到柱子的高度与X轴分类，又能体现3D立体感，避免视角过平/过陡导致的视觉失衡。
渲染器核心配置：
- antialias: true：开启抗锯齿，让柱子边缘、坐标轴线条更细腻，避免“锯齿边”；
- shadowMap.type = PCFSoftShadowMap：启用软阴影，让柱子投射的阴影边缘更柔和，贴合真实物理效果，避免硬阴影的生硬感；
- setPixelRatio：适配Retina屏幕，保证高清渲染，标签文字与柱子细节无模糊。
轨道控制器优化：
- 阻尼系数0.06：拖拽旋转场景后，控制器会自然减速，交互更顺滑；
- 缩放范围8~30：限制最小/最大缩放距离，避免缩放过近导致柱子遮挡、过远导致细节丢失；
- autoRotate: false：关闭自动旋转，让用户自主控制查看视角，更贴合数据可视化的使用场景。

步骤2：CSS2D渲染器初始化（标签渲染核心）

初始化CSS2D渲染器，为坐标轴标签、柱顶数值标签提供渲染载体，解决Three.js原生文字渲染样式不灵活的问题。

2.1 核心代码（对应原代码2）

const labelRenderer = new CSS2DRenderer();
labelRenderer.setSize(window.innerWidth, window.innerHeight);
labelRenderer.domElement.style.position = 'absolute';
labelRenderer.domElement.style.top = '0px';
labelRenderer.domElement.style.left = '0px';
labelRenderer.domElement.style.pointerEvents = 'none'; // 不阻挡点击
document.body.appendChild(labelRenderer.domElement);

2.2 关键说明

CSS2D渲染器的核心价值：将HTML元素（<div>标签）映射到3D空间坐标，既能利用CSS灵活控制文字样式（颜色、字体、背景、圆角等），又能跟随3D场景的旋转/缩放同步更新位置，完美还原ECharts的标签风格。
pointerEvents: none：关闭标签的鼠标事件响应，避免标签遮挡轨道控制器的交互（如拖拽旋转时点击到标签无反应）。

步骤3：光照系统构建（光影质感核心）

组合环境光、方向光、点光源，打造分层级的光照效果，增强柱子的立体感，同时避免光线过亮/过暗导致的视觉失衡。

3.1 核心代码（对应原代码3）

// 环境光提供基础照明
const ambientLight = new THREE.AmbientLight(0xffffff, 0.6);
scene.add(ambientLight);

// 主光源 - 产生阴影
const mainLight = new THREE.DirectionalLight(0xfff5e6, 1.0);
mainLight.position.set(8, 12, 8);
mainLight.castShadow = true;
mainLight.receiveShadow = true;
mainLight.shadow.mapSize.width = 1024;
mainLight.shadow.mapSize.height = 1024;
mainLight.shadow.camera.near = 0.5;
mainLight.shadow.camera.far = 30;
mainLight.shadow.camera.left = -15;
mainLight.shadow.camera.right = 15;
mainLight.shadow.camera.top = 15;
mainLight.shadow.camera.bottom = -15;
scene.add(mainLight);

// 辅助背光，增加柱子暗部细节
const backLight = new THREE.DirectionalLight(0xe0f0ff, 0.5);
backLight.position.set(-5, 0, 10);
scene.add(backLight);

// 补充侧光
const fillLight = new THREE.PointLight(0xccddff, 0.3);
fillLight.position.set(2, 5, 12);
scene.add(fillLight);

3.2 关键说明

光照分层逻辑：
- 环境光（强度0.6）：提供基础照明，避免场景暗部全黑，保证所有元素的基础可见性；
- 主方向光（强度1.0）：模拟主光源（如自然光），同时开启阴影，是柱子立体感的核心；
- 背光（强度0.5）：补充柱子暗部细节，避免暗部“死黑”，提升光影层次感；
- 点光源（强度0.3）：柔和填充侧光，进一步优化光影过渡，让柱子的材质质感更真实。
阴影参数优化：
- shadow.mapSize = 1024x1024：设置阴影贴图分辨率，数值越高阴影越清晰（但性能开销越大），1024是“清晰度+性能”的平衡值；
- 阴影相机范围(-15~15)：覆盖整个柱状图场景，保证所有柱子的阴影都能被正确渲染。

步骤4：图表数据与配置参数定义

定义柱状图的业务数据与视觉配置参数，实现“数据与样式解耦”，便于后续调整视觉风格。

4.1 核心代码（对应原代码4）

// 图表数据（ECharts 标准：一月到六月，数值清晰）
const chartData = [
    { label: '一月', value: 2 },
    { label: '二月', value: 3 },
    { label: '三月', value: 4 },
    { label: '四月', value: 5 },
    { label: '五月', value: 6 },
    { label: '六月', value: 7 }
];

// 配置参数 —— 完全符合柱状图审美
const config = {
    columnWidth: 0.9,          // 柱子宽一些，更饱满
    columnDepth: 0.9,          // Z轴厚度
    yMax: 10,                 // Y轴最大值固定为10，留白更ECharts（原数据最大7，顶部留空间显示数值）
    xStep: 2.1,              // 柱间距适中
    yStep: 2,                // Y轴刻度步长
    axisColor: 0x5d6d7e,     // 轴体深蓝灰，专业感
    axisLineWidth: 2.2,      // 轴线条加粗
    columnColors: [0x5470c6, 0x91cc75, 0xfac858, 0xee6666, 0x73c0de, 0x3ba272], // ECharts 经典配色
    columnXOffset: 1.8,      // 柱子起点与Y轴留白，避免拥挤（ECharts风格）
    groundOpacity: 0.15,      // 地面极浅，仅作视觉参考
    shadowOpacity: 0.3
};

4.2 关键说明

数据结构设计：chartData采用“标签+数值”的对象数组，贴合ECharts的数据格式，便于后续对接真实业务数据；
配置参数的ECharts适配：
- yMax: 10：预留顶部空间（原数据最大7），避免柱顶数值标签与柱子顶部重叠，符合ECharts的留白审美；
- columnColors：使用ECharts经典配色数组，按柱子循环使用，保证视觉风格一致；
- xStep: 2.1/columnXOffset: 1.8：控制柱子间距与X轴偏移，避免柱子与Y轴拥挤，贴合ECharts的轴边距风格。

步骤5：地面与网格辅助线构建

构建地面几何体与网格辅助线，为3D场景提供视觉锚点，增强坐标感，同时接收柱子的阴影。

5.1 核心代码（对应原代码5）

// 地面（接收阴影，视觉锚点）
const groundGeometry = new THREE.CircleGeometry(30, 32); // 圆形地面更柔和
const groundMaterial = new THREE.MeshStandardMaterial({
    color: 0xe9ecef,
    roughness: 0.8,
    metalness: 0.1,
    transparent: true,
    opacity: config.groundOpacity,
    side: THREE.DoubleSide
});
const ground = new THREE.Mesh(groundGeometry, groundMaterial);
ground.rotation.x = -Math.PI / 2;
ground.position.y = -0.1;
ground.receiveShadow = true;
scene.add(ground);

// 添加一个极细的网格辅助线（可选，增强坐标感，但不抢眼）
const gridHelper = new THREE.GridHelper(26, 20, 0x9aa6b2, 0xcbd5e0);
gridHelper.position.y = -0.09;
scene.add(gridHelper);

5.2 关键说明

地面设计优化：
- 圆形地面（CircleGeometry）：相比方形地面更柔和，避免直角的生硬感；
- 透明度0.15：地面仅作视觉锚点，不抢夺柱状图的视觉焦点；
- receiveShadow: true：开启阴影接收，让柱子的阴影投射到地面，增强3D真实感。
网格辅助线：
- 位置y=-0.09：略高于地面，避免与地面重叠导致的视觉混乱；
- 浅灰色调：增强坐标感的同时，不干扰主视觉，符合数据可视化“辅助元素不抢戏”的原则。

步骤6：坐标轴系统构建（X/Y轴+刻度+标签）

构建符合ECharts风格的X/Y坐标轴，包括轴线、刻度线、分类/数值标签、轴名称，是数据可视化的核心骨架。

6.1 核心代码（对应原代码6，以X轴为例）

// 坐标轴材质
const axisMaterial = new THREE.LineBasicMaterial({ 
    color: config.axisColor,
    linewidth: config.axisLineWidth
});

// ===== X轴 =====
const xAxisStart = -0.5;
const xAxisEnd = (chartData.length - 1) * config.xStep + config.columnXOffset + 1.2;
const xAxisPoints = [new THREE.Vector3(xAxisStart, 0, 0), new THREE.Vector3(xAxisEnd, 0, 0)];
const xAxisGeo = new THREE.BufferGeometry().setFromPoints(xAxisPoints);
const xAxisLine = new THREE.Line(xAxisGeo, axisMaterial);
scene.add(xAxisLine);

// X轴刻度与分类标签
chartData.forEach((item, i) => {
    const xPos = i * config.xStep + config.columnXOffset;
    
    // 刻度线（向下，长度0.6，清晰可见）
    const tickPoints = [
        new THREE.Vector3(xPos, 0, 0),
        new THREE.Vector3(xPos, -0.6, 0)
    ];
    const tickGeo = new THREE.BufferGeometry().setFromPoints(tickPoints);
    const tick = new THREE.Line(tickGeo, axisMaterial);
    scene.add(tick);

    // 分类标签 (CSS2D) —— ECharts风格：居中，字体适中
    const labelDiv = document.createElement('div');
    labelDiv.className = 'axis-tick-label';
    labelDiv.textContent = item.label;
    labelDiv.style.transform = 'translate(-50%, 0)';
    labelDiv.style.fontWeight = '500';
    labelDiv.style.color = '#2e4053';
    const labelObj = new CSS2DObject(labelDiv);
    labelObj.position.set(xPos, -1.1, 0);
    scene.add(labelObj);
});

// X轴名称 “月份” (ECharts标准：置于轴末端附近，加粗)
const xNameDiv = document.createElement('div');
xNameDiv.className = 'axis-name-label';
xNameDiv.textContent = '月份';
xNameDiv.style.transform = 'translate(-50%, 0)';
const xNameLabel = new CSS2DObject(xNameDiv);
xNameLabel.position.set(xAxisEnd - 0.3, -1.8, 0);
scene.add(xNameLabel);

6.2 关键说明

轴线长度自适应：xAxisEnd通过chartData.length动态计算，保证X轴长度适配数据条数，避免硬编码导致的适配问题；
刻度线与标签对齐：
- 刻度线长度0.6：清晰可见且不突兀，符合ECharts的刻度线尺寸；
- 标签位置y=-1.1：位于刻度线下方，避免与轴线/刻度线重叠；
- transform: translate(-50%, 0)：让标签水平居中对齐刻度线，保证视觉整齐；
轴名称样式：采用加粗、深色、末端放置的样式，完全复刻ECharts的轴名称风格，增强数据可读性。

步骤7：柱状图主体构建（几何体+材质+标签）

构建3D柱子几何体，配置贴合ECharts风格的材质，同时添加柱顶数值标签，是数据可视化的核心展示层。

7.1 核心代码（对应原代码7）

chartData.forEach((item, i) => {
    const xPos = i * config.xStep + config.columnXOffset;
    const height = item.value;     // 实际数值
    const color = config.columnColors[i % config.columnColors.length];

    // 柱子材质：轻微光泽，略带透明感但清晰
    const columnMaterial = new THREE.MeshStandardMaterial({
        color: color,
        roughness: 0.45,
        metalness: 0.2,
        emissive: new THREE.Color(color).multiplyScalar(0.1),
        emissiveIntensity: 0.2,
        transparent: true,
        opacity: 0.95
    });

    const columnGeo = new THREE.BoxGeometry(
        config.columnWidth,
        height,
        config.columnDepth
    );
    const column = new THREE.Mesh(columnGeo, columnMaterial);
    column.castShadow = true;
    column.receiveShadow = true;
    column.position.set(xPos, height / 2, 0);
    scene.add(column);

    // 柱顶数值标签（核心要求：每一个柱子顶部显示相应的值，ECharts 风格）
    const valueDiv = document.createElement('div');
    valueDiv.className = 'bar-value-label';
    valueDiv.textContent = item.value;   // 简洁显示数值
    // 仿ECharts: 白色底框+红褐色字，小圆角
    valueDiv.style.background = 'rgba(255, 255, 255, 0.8)';
    valueDiv.style.border = '1px solid ' + new THREE.Color(color).getStyle();
    valueDiv.style.color = new THREE.Color(color).multiplyScalar(0.6).getStyle();
    
    const valueLabel = new CSS2DObject(valueDiv);
    // 标签置于柱子顶部上方0.8处，醒目不重叠
    valueLabel.position.set(xPos, height + 0.8, 0);
    scene.add(valueLabel);

    // 柱顶圆点装饰
    const topDotGeo = new THREE.SphereGeometry(0.1);
    const topDotMat = new THREE.MeshStandardMaterial({ color: color, emissive: color, emissiveIntensity: 0.2 });
    const topDot = new THREE.Mesh(topDotGeo, topDotMat);
    topDot.position.set(xPos, height, 0);
    topDot.castShadow = false;
    scene.add(topDot);
});

7.2 关键说明

柱子位置计算：position.set(xPos, height / 2, 0)，Three.js的立方体几何体锚点在中心，因此Y轴位置需设置为height/2，保证柱子底部对齐X轴（y=0）；
材质风格优化：
- roughness: 0.45/metalness: 0.2：轻微的金属光泽，让柱子有质感但不刺眼；
- emissive：轻微自发光，增强柱子的视觉层次感，贴合ECharts的高亮风格；
- 透明度0.95：略带透明感，避免柱子过于厚重，符合现代数据可视化的轻盈风格；
柱顶标签优化：
- 位置height + 0.8：位于柱子顶部上方，避免与柱子重叠；
- 背景半透+圆角：复刻ECharts的数值标签样式，增强可读性；
- 颜色适配：标签边框/文字颜色与柱子颜色联动，保证视觉统一性。

步骤8：辅助线与装饰元素构建

添加Z轴短线、背面辅助线等装饰元素，增强3D场景的方位感，同时不干扰主视觉。

8.1 核心代码（对应原代码8）

// Z轴短线示意（虽然2D柱状图，但3D空间给出方位）
const zAxisPoints = [new THREE.Vector3(0, 0, -2), new THREE.Vector3(0, 0, 2)];
const zAxisGeo = new THREE.BufferGeometry().setFromPoints(zAxisPoints);
const zAxisLine = new THREE.Line(zAxisGeo, new THREE.LineBasicMaterial({ color: 0xb0bec5, linewidth: 1 }));
scene.add(zAxisLine);

// 背面辅助线，增加空间感
const helperExtent = 14;
const axisHelperMaterial = new THREE.LineBasicMaterial({ color: 0xd0d8e0, linewidth: 1 });
const backLine1 = [new THREE.Vector3(-1, 0, -1.5), new THREE.Vector3(xAxisEnd, 0, -1.5)];
const backLineGeo1 = new THREE.BufferGeometry().setFromPoints(backLine1);
const backLineObj1 = new THREE.Line(backLineGeo1, axisHelperMaterial);
scene.add(backLineObj1);

8.2 关键说明

Z轴短线：提示3D场景的纵深方向，让用户感知柱子的厚度（Z轴），避免误以为是纯2D图表；
背面辅助线：浅灰色细线条，增强场景的空间层次感，同时不抢夺柱状图的视觉焦点。

步骤9：响应式窗口适配

监听窗口尺寸变化，动态更新相机比例、渲染器尺寸，保证柱状图在不同屏幕下无拉伸变形。

9.1 核心代码（对应原代码9）

window.addEventListener('resize', onWindowResize, false);
function onWindowResize() {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();
    renderer.setSize(window.innerWidth, window.innerHeight);
    labelRenderer.setSize(window.innerWidth, window.innerHeight);
}

9.2 关键说明

camera.updateProjectionMatrix()：窗口尺寸变化后，相机的宽高比会修改，必须调用该方法更新投影矩阵，否则柱状图会出现拉伸变形；
同步更新labelRenderer尺寸：保证CSS2D标签与3D场景同步适配，避免标签位置偏移。

步骤10：动画循环驱动

通过requestAnimationFrame驱动动画循环，维持轨道控制器阻尼更新与场景渲染的流畅性。

10.1 核心代码（对应原代码10）

function animate() {
    requestAnimationFrame(animate);
    controls.update(); // 启用阻尼后需要每帧更新
    renderer.render(scene, camera);
    labelRenderer.render(scene, camera);
}
animate();

10.2 关键说明

controls.update()：轨道控制器启用阻尼后，必须在每帧动画中调用该方法，否则阻尼效果失效；
双渲染器调用：同时渲染3D场景（renderer）和CSS2D标签（labelRenderer），保证标签与3D场景同步显示。

核心技术深度解析

1. CSS2D标签渲染的核心逻辑

CSS2D标签是还原ECharts风格的关键，其核心渲染逻辑如下：

graph LR
    A["创建HTML div标签（设置样式/文字）"] --> B["封装为CSS2DObject（绑定3D坐标）"]
    B --> C["添加到Three.js场景"] --> D["动画循环中调用labelRenderer.render"]
    D --> E["标签随3D场景旋转/缩放同步更新位置"]

核心优势：相比Three.js原生的TextGeometry，CSS2D标签支持任意CSS样式（背景、圆角、文字阴影、毛玻璃等），完全复刻ECharts的标签风格，且渲染性能更高。

2. 光影系统的层次感实现

柱状图的3D立体感核心来自分层光照设计，其逻辑如下：

graph LR
    A["环境光（基础照明，0.6强度）"] --> B["主方向光（核心光影+阴影，1.0强度）"]
    B --> C["背光（补充暗部细节，0.5强度）"] --> D["点光源（柔和填充侧光，0.3强度）"]
    D --> E["柱子材质（roughness/metalness/emissive）"] --> F["自然的3D光影质感"]

核心亮点：主光源负责阴影和主要光照，背光和点光源补充细节，避免暗部死黑，让柱子的材质质感更真实。

3. ECharts风格视觉还原的核心

代码通过三大维度精准复刻ECharts风格：

配色维度：使用ECharts经典配色数组，轴体采用深蓝灰（专业感），标签采用分级配色（刻度浅灰、轴名深灰、数值醒目色）；
布局维度：Y轴预留顶部空间、柱子与Y轴留白、刻度线长度统一、标签位置对齐，完全贴合ECharts的布局审美；
样式维度：标签的文字阴影、半透背景、圆角，柱子的轻微光泽/透明感，轴线条加粗，均复刻ECharts的视觉细节。

核心参数速查表（快速调整视觉/交互效果）

参数分类	参数名	当前取值	核心作用	修改建议
场景配置	相机视角 `camera.fov`	45	控制3D场景的视角，越小畸变越少	改为30：更接近2D视觉；改为60：3D纵深感更强
场景配置	相机位置 `camera.position`	(9,7,14)	控制观察视角（斜上方俯视）	改为(0,10,15)：正面视角；改为(15,5,10)：侧方视角
视觉配置	柱子尺寸 `columnWidth/columnDepth`	0.9/0.9	控制柱子的宽度/厚度	改为0.7/0.7：柱子更纤细；改为1.2/1.2：柱子更粗壮
视觉配置	柱间距 `xStep`	2.1	控制X轴上柱子的间距	改为1.5：柱子更密集；改为3.0：柱子更稀疏
视觉配置	Y轴最大值 `yMax`	10	控制Y轴高度（预留标签空间）	改为8：Y轴更紧凑；改为15：Y轴更宽松
视觉配置	轴线条宽度 `axisLineWidth`	2.2	控制坐标轴线的粗细	改为1.5：轴线更细；改为3.0：轴线更粗
数据配置	图表数据 `chartData`	6组（一月-六月）	柱状图的业务数据	新增/删除数组元素：适配更多/更少分类；修改value：调整柱子高度
光照配置	主光源强度 `mainLight.intensity`	1.0	控制主光源的亮度	改为0.7：光线更柔和；改为1.5：光线更明亮
交互配置	控制器阻尼 `dampingFactor`	0.06	控制拖拽旋转的顺滑度	改为0.03：阻尼更弱（旋转更快）；改为0.1：阻尼更强（旋转更慢）
交互配置	缩放范围 `minDistance/maxDistance`	8/30	控制滚轮缩放的最小/最大距离	改为5/20：缩放范围更小；改为10/40：缩放范围更大

完整代码

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>Three.js 柱状图 · ECharts 标准风格</title>
    <style>
        body {
            margin: 0;
            overflow: hidden;
            font-family: "Microsoft YaHei", sans-serif;
        }
        canvas {
            display: block;
        }
        /* 坐标轴标签：清爽灰色，无干扰 */
        .axis-tick-label {
            color: #4a4a4a;
            font-size: 13px;
            font-weight: normal;
            white-space: nowrap;
            pointer-events: none;
            text-shadow: 0 0 2px rgba(255,255,255,0.8);
        }
        /* 轴名称标签 (ECharts 风格：加粗，深色) */
        .axis-name-label {
            color: #2c3e50;
            font-size: 16px;
            font-weight: 600;
            white-space: nowrap;
            pointer-events: none;
            text-shadow: 0 0 3px rgba(255,255,255,0.9);
        }
        /* 柱顶数值标签：醒目红褐色，类似ECharts 强调 */
        .bar-value-label {
            color: #c0392b;
            font-size: 14px;
            font-weight: 600;
            white-space: nowrap;
            pointer-events: none;
            text-shadow: 0 0 5px rgba(255,255,255,0.8);
            background: rgba(255, 255, 255, 0.6);
            padding: 2px 6px;
            border-radius: 10px;
            border: 1px solid rgba(192, 57, 43, 0.3);
            backdrop-filter: blur(2px);
        }
        /* 简单辅助：去掉滚动条，干净视图 */
    </style>
</head>
<body>
    <script type="module">
        import * as THREE from 'https://esm.sh/three@0.174.0';
        import { OrbitControls } from 'https://esm.sh/three@0.174.0/examples/jsm/controls/OrbitControls.js';
        import { CSS2DRenderer, CSS2DObject } from 'https://esm.sh/three@0.174.0/examples/jsm/renderers/CSS2DRenderer.js';

        // ---------- 1. 初始化场景、相机、渲染器（增强抗锯齿与性能）----------
        const scene = new THREE.Scene();
        scene.background = new THREE.Color(0xf5f7fa); // 柔和灰白背景，类似ECharts容器

        const camera = new THREE.PerspectiveCamera(
            45, // 更小视角，减少畸变，更接近2D感
            window.innerWidth / window.innerHeight,
            0.1,
            1000
        );
        camera.position.set(9, 7, 14);
        camera.lookAt(4, 3, 0);

        const renderer = new THREE.WebGLRenderer({ antialias: true });
        renderer.setSize(window.innerWidth, window.innerHeight);
        renderer.shadowMap.enabled = true;        // 开启阴影，更真实
        renderer.shadowMap.type = THREE.PCFSoftShadowMap;
        renderer.setPixelRatio(window.devicePixelRatio);
        document.body.appendChild(renderer.domElement);

        // 轨道控制器，带阻尼
        const controls = new OrbitControls(camera, renderer.domElement);
        controls.enableDamping = true;
        controls.dampingFactor = 0.06;
        controls.autoRotate = false;
        controls.enableZoom = true;
        controls.target.set(4, 3, 0);
        controls.minDistance = 8;
        controls.maxDistance = 30;

        // ---------- 2. CSS2渲染器（用于所有文字标签：轴刻度、轴名称、柱顶数值）----------
        const labelRenderer = new CSS2DRenderer();
        labelRenderer.setSize(window.innerWidth, window.innerHeight);
        labelRenderer.domElement.style.position = 'absolute';
        labelRenderer.domElement.style.top = '0px';
        labelRenderer.domElement.style.left = '0px';
        labelRenderer.domElement.style.pointerEvents = 'none'; // 不阻挡点击
        document.body.appendChild(labelRenderer.domElement);

        // ---------- 3. 灯光系统（呈现立体感，但不刺眼）----------
        // 环境光提供基础照明
        const ambientLight = new THREE.AmbientLight(0xffffff, 0.6);
        scene.add(ambientLight);

        // 主光源 - 产生阴影
        const mainLight = new THREE.DirectionalLight(0xfff5e6, 1.0);
        mainLight.position.set(8, 12, 8);
        mainLight.castShadow = true;
        mainLight.receiveShadow = true;
        mainLight.shadow.mapSize.width = 1024;
        mainLight.shadow.mapSize.height = 1024;
        mainLight.shadow.camera.near = 0.5;
        mainLight.shadow.camera.far = 30;
        mainLight.shadow.camera.left = -15;
        mainLight.shadow.camera.right = 15;
        mainLight.shadow.camera.top = 15;
        mainLight.shadow.camera.bottom = -15;
        scene.add(mainLight);

        // 辅助背光，增加柱子暗部细节
        const backLight = new THREE.DirectionalLight(0xe0f0ff, 0.5);
        backLight.position.set(-5, 0, 10);
        scene.add(backLight);

        // 补充侧光
        const fillLight = new THREE.PointLight(0xccddff, 0.3);
        fillLight.position.set(2, 5, 12);
        scene.add(fillLight);

        // ---------- 4. 图表数据（ECharts 标准：一月到六月，数值清晰）----------
        const chartData = [
            { label: '一月', value: 2 },
            { label: '二月', value: 3 },
            { label: '三月', value: 4 },
            { label: '四月', value: 5 },
            { label: '五月', value: 6 },
            { label: '六月', value: 7 }
        ];

        // 配置参数 —— 完全符合柱状图审美
        const config = {
            columnWidth: 0.9,          // 柱子宽一些，更饱满
            columnDepth: 0.9,          // Z轴厚度
            yMax: 10,                 // Y轴最大值固定为10，留白更ECharts（原数据最大7，顶部留空间显示数值）
            xStep: 2.1,              // 柱间距适中
            yStep: 2,                // Y轴刻度步长
            axisColor: 0x5d6d7e,     // 轴体深蓝灰，专业感
            axisLineWidth: 2.2,      // 轴线条加粗
            columnColors: [0x5470c6, 0x91cc75, 0xfac858, 0xee6666, 0x73c0de, 0x3ba272], // ECharts 经典配色
            columnXOffset: 1.8,      // 柱子起点与Y轴留白，避免拥挤（ECharts风格）
            groundOpacity: 0.15,      // 地面极浅，仅作视觉参考
            shadowOpacity: 0.3
        };

        // ---------- 5. 地面（接收阴影，视觉锚点）----------
        const groundGeometry = new THREE.CircleGeometry(30, 32); // 圆形地面更柔和
        const groundMaterial = new THREE.MeshStandardMaterial({
            color: 0xe9ecef,
            roughness: 0.8,
            metalness: 0.1,
            transparent: true,
            opacity: config.groundOpacity,
            side: THREE.DoubleSide
        });
        const ground = new THREE.Mesh(groundGeometry, groundMaterial);
        ground.rotation.x = -Math.PI / 2;
        ground.position.y = -0.1;
        ground.receiveShadow = true;
        scene.add(ground);

        // 添加一个极细的网格辅助线（可选，增强坐标感，但不抢眼）
        const gridHelper = new THREE.GridHelper(26, 20, 0x9aa6b2, 0xcbd5e0);
        gridHelper.position.y = -0.09;
        scene.add(gridHelper);

        // ---------- 6. 坐标轴系统（完全参照ECharts：轴线明显，刻度清晰，轴标签明确）----------
        const axisMaterial = new THREE.LineBasicMaterial({ 
            color: config.axisColor,
            linewidth: config.axisLineWidth
        });

        // ===== X轴 =====
        const xAxisStart = -0.5;
        const xAxisEnd = (chartData.length - 1) * config.xStep + config.columnXOffset + 1.2;
        const xAxisPoints = [new THREE.Vector3(xAxisStart, 0, 0), new THREE.Vector3(xAxisEnd, 0, 0)];
        const xAxisGeo = new THREE.BufferGeometry().setFromPoints(xAxisPoints);
        const xAxisLine = new THREE.Line(xAxisGeo, axisMaterial);
        scene.add(xAxisLine);

        // X轴刻度与分类标签
        chartData.forEach((item, i) => {
            const xPos = i * config.xStep + config.columnXOffset;
            
            // 刻度线（向下，长度0.6，清晰可见）
            const tickPoints = [
                new THREE.Vector3(xPos, 0, 0),
                new THREE.Vector3(xPos, -0.6, 0)
            ];
            const tickGeo = new THREE.BufferGeometry().setFromPoints(tickPoints);
            const tick = new THREE.Line(tickGeo, axisMaterial);
            scene.add(tick);

            // 分类标签 (CSS2D) —— ECharts风格：居中，字体适中
            const labelDiv = document.createElement('div');
            labelDiv.className = 'axis-tick-label';
            labelDiv.textContent = item.label;
            labelDiv.style.transform = 'translate(-50%, 0)';
            labelDiv.style.fontWeight = '500';
            labelDiv.style.color = '#2e4053';
            const labelObj = new CSS2DObject(labelDiv);
            labelObj.position.set(xPos, -1.1, 0);
            scene.add(labelObj);
        });

        // X轴名称 “月份” (ECharts标准：置于轴末端附近，加粗)
        const xNameDiv = document.createElement('div');
        xNameDiv.className = 'axis-name-label';
        xNameDiv.textContent = '月份';
        xNameDiv.style.transform = 'translate(-50%, 0)';
        const xNameLabel = new CSS2DObject(xNameDiv);
        xNameLabel.position.set(xAxisEnd - 0.3, -1.8, 0);
        scene.add(xNameLabel);

        // ===== Y轴 =====
        const yAxisStart = 0;
        const yAxisEnd = config.yMax;
        const yAxisPoints = [new THREE.Vector3(0, yAxisStart, 0), new THREE.Vector3(0, yAxisEnd, 0)];
        const yAxisGeo = new THREE.BufferGeometry().setFromPoints(yAxisPoints);
        const yAxisLine = new THREE.Line(yAxisGeo, axisMaterial);
        scene.add(yAxisLine);

        // Y轴刻度和数值标签（0到10，步长2，完全展示）
        for (let val = 0; val <= config.yMax; val += config.yStep) {
            // 刻度线（向左，长度0.6）
            const tickPoints = [
                new THREE.Vector3(0, val, 0),
                new THREE.Vector3(-0.6, val, 0)
            ];
            const tickGeo = new THREE.BufferGeometry().setFromPoints(tickPoints);
            const tick = new THREE.Line(tickGeo, axisMaterial);
            scene.add(tick);

            // 数值标签
            const labelDiv = document.createElement('div');
            labelDiv.className = 'axis-tick-label';
            labelDiv.textContent = val;
            labelDiv.style.transform = 'translate(0, -50%)';
            labelDiv.style.fontWeight = '500';
            const labelObj = new CSS2DObject(labelDiv);
            labelObj.position.set(-1.2, val, 0);
            scene.add(labelObj);
        }

        // Y轴名称 “数值” (ECharts风格：垂直居中，加粗)
        const yNameDiv = document.createElement('div');
        yNameDiv.className = 'axis-name-label';
        yNameDiv.textContent = '数值';
        yNameDiv.style.transform = 'translate(0, -50%)';
        const yNameLabel = new CSS2DObject(yNameDiv);
        yNameLabel.position.set(-2.4, config.yMax / 2, 0);
        scene.add(yNameLabel);

        // ===== 原点装饰（加强视觉）=====
        const originDotGeo = new THREE.SphereGeometry(0.08);
        const originDotMat = new THREE.MeshStandardMaterial({ color: 0x2c3e50, emissive: 0x1a2630, emissiveIntensity: 0.2 });
        const originDot = new THREE.Mesh(originDotGeo, originDotMat);
        originDot.position.set(0, 0, 0);
        scene.add(originDot);

        // ---------- 7. 柱状图主体（每个柱子带阴影、柱顶数值标签，严格按ECharts标准）----------
        chartData.forEach((item, i) => {
            const xPos = i * config.xStep + config.columnXOffset;
            const height = item.value;     // 实际数值
            const color = config.columnColors[i % config.columnColors.length];

            // 柱子材质：轻微光泽，略带透明感但清晰
            const columnMaterial = new THREE.MeshStandardMaterial({
                color: color,
                roughness: 0.45,
                metalness: 0.2,
                emissive: new THREE.Color(color).multiplyScalar(0.1),
                emissiveIntensity: 0.2,
                transparent: true,
                opacity: 0.95
            });

            const columnGeo = new THREE.BoxGeometry(
                config.columnWidth,
                height,
                config.columnDepth
            );
            const column = new THREE.Mesh(columnGeo, columnMaterial);
            column.castShadow = true;
            column.receiveShadow = true;
            column.position.set(xPos, height / 2, 0);
            scene.add(column);

            // ----- 柱顶数值标签（核心要求：每一个柱子顶部显示相应的值，ECharts 风格）-----
            const valueDiv = document.createElement('div');
            valueDiv.className = 'bar-value-label';
            valueDiv.textContent = item.value;   // 简洁显示数值
            // 仿ECharts: 白色底框+红褐色字，小圆角
            valueDiv.style.background = 'rgba(255, 255, 255, 0.8)';
            valueDiv.style.border = '1px solid ' + new THREE.Color(color).getStyle();
            valueDiv.style.color = new THREE.Color(color).multiplyScalar(0.6).getStyle();
            
            const valueLabel = new CSS2DObject(valueDiv);
            // 标签置于柱子顶部上方0.8处，醒目不重叠
            valueLabel.position.set(xPos, height + 0.8, 0);
            scene.add(valueLabel);

            // ----- 额外加一个微小的柱顶圆点，提升细节 (ECharts有时会有标记) -----
            const topDotGeo = new THREE.SphereGeometry(0.1);
            const topDotMat = new THREE.MeshStandardMaterial({ color: color, emissive: color, emissiveIntensity: 0.2 });
            const topDot = new THREE.Mesh(topDotGeo, topDotMat);
            topDot.position.set(xPos, height, 0);
            topDot.castShadow = false;
            scene.add(topDot);
        });

        // ---------- 8. 添加一个轻量的Z轴短线示意（虽然2D柱状图，但3D空间给出方位）----------
        const zAxisPoints = [new THREE.Vector3(0, 0, -2), new THREE.Vector3(0, 0, 2)];
        const zAxisGeo = new THREE.BufferGeometry().setFromPoints(zAxisPoints);
        const zAxisLine = new THREE.Line(zAxisGeo, new THREE.LineBasicMaterial({ color: 0xb0bec5, linewidth: 1 }));
        scene.add(zAxisLine);

        // 添加微弱的辅助环境线框，不干扰主视觉
        const helperExtent = 14;
        const axisHelperMaterial = new THREE.LineBasicMaterial({ color: 0xd0d8e0, linewidth: 1 });

        // 简单在背面加两根平行线，增加空间感（可选）
        const backLine1 = [new THREE.Vector3(-1, 0, -1.5), new THREE.Vector3(xAxisEnd, 0, -1.5)];
        const backLineGeo1 = new THREE.BufferGeometry().setFromPoints(backLine1);
        const backLineObj1 = new THREE.Line(backLineGeo1, axisHelperMaterial);
        scene.add(backLineObj1);

        // ---------- 9. 响应式窗口----------
        window.addEventListener('resize', onWindowResize, false);
        function onWindowResize() {
            camera.aspect = window.innerWidth / window.innerHeight;
            camera.updateProjectionMatrix();
            renderer.setSize(window.innerWidth, window.innerHeight);
            labelRenderer.setSize(window.innerWidth, window.innerHeight);
        }

        // ---------- 10. 动画循环----------
        function animate() {
            requestAnimationFrame(animate);
            controls.update(); // 启用阻尼后需要每帧更新
            renderer.render(scene, camera);
            labelRenderer.render(scene, camera);
        }
        animate();

        // 控制台提示
        console.log('ECharts 风格柱状图已加载，坐标轴标签、柱顶数值完整展示');
    </script>
</body>
</html>

总结与扩展建议

核心总结

视觉还原核心：通过CSS2D标签、ECharts经典配色、轴样式/布局优化，精准复刻ECharts柱状图的视觉风格，同时保留3D立体感；
光影构建核心：分层光照（环境光+主方向光+背光+点光源）+软阴影系统，打造真实的3D光影质感，避免场景平面化；
交互适配核心：轨道控制器阻尼优化+响应式窗口适配，保证3D交互的顺滑性与多设备的兼容性；
性能核心：通过合理的几何体/材质配置、阴影分辨率平衡，保证在普通设备上60帧流畅渲染。

扩展建议

动态数据更新：
- 新增updateData函数，修改chartData后重新构建柱子几何体，实现数据动态刷新（如实时监控数据）；
- 为柱子添加高度过渡动画，让数据更新时柱子平滑升降，提升视觉体验。
多系列柱状图：
- 在Z轴方向扩展，为每个分类添加多个柱子（如每月的“销量”“利润”），实现多系列对比；
- 新增图例组件（CSS2D标签），标注不同系列的颜色与含义，贴合ECharts多系列图表风格。
交互增强：
- 添加tooltip交互：监听鼠标点击/悬浮事件，显示柱子的详细信息（如“一月：2（同比增长10%）”）；
- 柱子高亮效果：鼠标悬浮时修改柱子材质（如提高emissiveIntensity），增强交互反馈。
视觉主题切换：
- 新增主题配置（如浅色/深色主题），修改scene.background、axisColor、columnColors等参数，实现一键切换；
- 适配ECharts的官方主题（如dark、macarons），提升视觉多样性。
性能优化：
- 使用InstancedMesh替代普通Mesh，批量渲染相同样式的柱子，减少DrawCall，支持更多分类数据；
- 视锥体裁剪：剔除屏幕外的柱子/标签，减少渲染开销，适配大量数据场景。

🚀 图片与点云数据缓存全攻略：从内存到文件系统的性能优化实践

掘金前端

作者波哥学开发

2026年2月12日 11:12

摘要：在智驾、机器人标注工具等可视化场景中，图片和点云数据的缓存策略直接影响应用性能。本文深入剖析各种缓存模式的原理、性能差异，并提供针对 Canvas 2D 和 WebGL 的最佳实践方案。

📋 目录

引言：为什么缓存策略如此重要？

在开发智驾标注工具、机器人可视化平台时，我们经常面临以下挑战：

🖼️ 海量图片：单个项目可能包含数千张高清图像
📦 点云数据：单帧点云可达数百万个点，体积庞大
⚡ 实时交互：标注、缩放、旋转等操作要求流畅响应
💾 离线支持：野外作业场景需要离线缓存能力

错误的缓存策略会导致：

❌ 首屏加载慢（3-5秒）
❌ 内存溢出（OOM）
❌ 标注卡顿（FPS < 30）
❌ 存储空间浪费（体积膨胀 5-10 倍）

本文将带你深入理解各种缓存模式，找到最适合你场景的方案。

图片缓存的五种模式

1. HTMLImageElement（传统 DOM Image）

const img = new Image();
img.src = 'image.jpg';
img.onload = () => {
  // 使用 img...
};

特点：

✅ 浏览器原生支持，使用简单
✅ 内存占用较小（保留压缩格式）
❌ 首次绘制时才解码，可能卡顿
❌ 不支持 Worker 环境

适用场景： 静态展示、简单应用

2. ImageBitmap（现代高性能方案）

const response = await fetch('image.jpg');
const blob = await response.blob();
const bitmap = await createImageBitmap(blob, {
  resizeQuality: 'medium',
  colorSpaceConversion: 'none'
});

特点：

✅ 创建时即解码，绘制零延迟
✅ 性能比 DOM Image 快 15-30%
✅ 支持 Worker 和 Transfer（零拷贝）
✅ 支持裁剪、缩放等预处理

适用场景： 高性能渲染、Worker 处理、视频帧

3. ImageData（像素级操作）

const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d')!;
const imageData = ctx.createImageData(width, height);

// 直接操作像素
const data = imageData.data;
data[0] = 255; // R
data[1] = 0;   // G
data[2] = 0;   // B
data[3] = 255; // A

特点：

✅ 直接访问像素数据，修改极快
✅ 适合频繁修改的场景
❌ 内存占用大（未压缩）
❌ 绘制性能较差（putImageData 慢）

适用场景： 标注框绘制、滤镜处理、像素级编辑

4. Blob（压缩格式存储）

const response = await fetch('image.jpg');
const blob = await response.blob();

// 存储到 IndexedDB 或 FileSystem
await cache.store(url, blob);

特点：

✅ 体积小（保留压缩格式）
✅ 适合长期缓存
✅ 可直接用于 createImageBitmap
❌ 读取时需要解码

适用场景： 离线缓存、网络资源缓存

5. ArrayBuffer / TypedArray（原始二进制）

const arrayBuffer = await blob.arrayBuffer();
const uint8Array = new Uint8Array(arrayBuffer);

// 直接操作二进制数据
uint8Array[0] = 0xFF;

特点：

✅ 最底层的数据表示
✅ 无额外封装开销
✅ 适合自定义格式
❌ 需要手动解析

适用场景： 自定义文件格式、点云数据、二进制协议

存储层：内存、IndexedDB、FileSystem API

1. 内存缓存（最快）

class MemoryCache {
  private cache = new Map<string, ImageBitmap>();
  private maxSize = 10; // 最多缓存 10 个

  set(key: string, value: ImageBitmap) {
    if (this.cache.size >= this.maxSize) {
      const oldestKey = this.cache.keys().next().value;
      this.cache.get(oldestKey)?.close();
      this.cache.delete(oldestKey);
    }
    this.cache.set(key, value);
  }

  get(key: string): ImageBitmap | undefined {
    return this.cache.get(key);
  }
}

性能： ~1ms 读取
限制： 刷新即丢失，内存有限
适用： 热点数据、频繁访问

2. IndexedDB（结构化存储）

class IDBCache {
  async store(key: string, blob: Blob) {
    const db = await this.openDB();
    const tx = db.transaction('images', 'readwrite');
    const store = tx.objectStore('images');
    
    await store.put({ id: key, blob, timestamp: Date.now() });
  }

  async get(key: string): Promise<ImageBitmap | null> {
    const db = await this.openDB();
    const tx = db.transaction('images', 'readonly');
    const store = tx.objectStore('images');
    
    const record = await new Promise(resolve => {
      const req = store.get(key);
      req.onsuccess = () => resolve(req.result);
    });

    if (!record) return null;
    return await createImageBitmap(record.blob);
  }
}

性能： ~50-100ms 读取（含反序列化）
限制： 有存储配额（通常 50-80% 磁盘空间）
特点： ✅ 有结构化克隆开销
适用： 中期缓存、结构化数据

3. File System Access API（文件系统）

class FileSystemCache {
  private dirHandle: FileSystemDirectoryHandle | null = null;

  async init() {
    this.dirHandle = await window.showDirectoryPicker({ mode: 'readwrite' });
  }

  async store(filename: string, bitmap: ImageBitmap) {
    if (!this.dirHandle) throw new Error('Not initialized');

    // 转换为 Blob
    const offscreen = new OffscreenCanvas(bitmap.width, bitmap.height);
    const ctx = offscreen.getContext('2d')!;
    ctx.drawImage(bitmap, 0, 0);
    const blob = await offscreen.convertToBlob({ type: 'image/webp', quality: 0.9 });

    // 写入文件（无序列化开销）
    const fileHandle = await this.dirHandle.getFileHandle(filename, { create: true });
    const writable = await fileHandle.createWritable();
    await writable.write(blob); // ✅ 直接写入，无序列化
    await writable.close();
  }

  async get(filename: string): Promise<ImageBitmap | null> {
    if (!this.dirHandle) return null;

    try {
      const fileHandle = await this.dirHandle.getFileHandle(filename);
      const file = await fileHandle.getFile();
      return await createImageBitmap(file); // ✅ 直接读取，无反序列化
    } catch {
      return null;
    }
  }
}

性能： ~80-120ms 读取（纯 I/O，无序列化）
限制： 需要用户授权
特点： ❌ 无序列化/反序列化开销
适用： 大文件、离线项目、长期存储

Canvas 2D 中的性能对比

绘制性能测试

class Canvas2DPerformanceTest {
  async run() {
    const canvas = document.createElement('canvas');
    canvas.width = 1920;
    canvas.height = 1080;
    const ctx = canvas.getContext('2d')!;

    // 准备测试数据
    const img = new Image();
    img.src = 'test.jpg';
    await img.decode();

    const response = await fetch('test.jpg');
    const blob = await response.blob();
    const bitmap = await createImageBitmap(blob);

    const imageData = ctx.createImageData(img.width, img.height);

    console.log('=== Canvas 2D 绘制性能 (1000次) ===\n');

    // 测试1：drawImage (DOM Image)
    console.time('drawImage (DOM Image)');
    for (let i = 0; i < 1000; i++) {
      ctx.drawImage(img, 0, 0);
    }
    console.timeEnd('drawImage (DOM Image)'); // ~18ms ⭐

    // 测试2：drawImage (ImageBitmap)
    console.time('drawImage (ImageBitmap)');
    for (let i = 0; i < 1000; i++) {
      ctx.drawImage(bitmap, 0, 0);
    }
    console.timeEnd('drawImage (ImageBitmap)'); // ~12ms ⭐⭐

    // 测试3：putImageData
    console.time('putImageData');
    for (let i = 0; i < 1000; i++) {
      ctx.putImageData(imageData, 0, 0);
    }
    console.timeEnd('putImageData'); // ~55ms ❌

    bitmap.close();
  }
}

Canvas 2D 性能排名

方法	耗时 (1000次)	性能	适用场景
`drawImage(ImageBitmap)`	~12ms	⭐⭐⭐	高性能渲染
`drawImage(HTMLImageElement)`	~18ms	⭐⭐	普通渲染
`drawImage(OffscreenCanvas)`	~15ms	⭐⭐	Worker 渲染
`putImageData(ImageData)`	~55ms	⭐	像素级操作

结论：

✅ 优先使用 ImageBitmap + drawImage
✅ 避免频繁使用 putImageData
✅ 使用离屏 Canvas 批量绘制

WebGL 中的性能对比

纹理上传性能

class WebGLPerformanceTest {
  async run() {
    const renderer = new THREE.WebGLRenderer();
    const gl = renderer.getContext();

    const img = new Image();
    img.src = 'test.jpg';
    await img.decode();

    const response = await fetch('test.jpg');
    const blob = await response.blob();
    const bitmap = await createImageBitmap(blob);

    const canvas = document.createElement('canvas');
    canvas.width = img.width;
    canvas.height = img.height;
    const ctx = canvas.getContext('2d')!;
    ctx.drawImage(img, 0, 0);
    const imageData = ctx.getImageData(0, 0, img.width, img.height);
    const data = new Uint8Array(imageData.data);

    console.log('=== WebGL 纹理上传性能 ===\n');

    // 测试1：HTMLImageElement
    console.time('WebGL - HTMLImageElement');
    const tex1 = gl.createTexture();
    gl.bindTexture(gl.TEXTURE_2D, tex1);
    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);
    console.timeEnd('WebGL - HTMLImageElement'); // ~3-5ms

    // 测试2：ImageBitmap
    console.time('WebGL - ImageBitmap');
    const tex2 = gl.createTexture();
    gl.bindTexture(gl.TEXTURE_2D, tex2);
    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, bitmap);
    console.timeEnd('WebGL - ImageBitmap'); // ~2-3ms ⭐

    // 测试3：ImageData (首次)
    console.time('WebGL - ImageData (first)');
    const tex3 = gl.createTexture();
    gl.bindTexture(gl.TEXTURE_2D, tex3);
    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, img.width, img.height, 0, gl.RGBA, gl.UNSIGNED_BYTE, data);
    console.timeEnd('WebGL - ImageData (first)'); // ~2-3ms

    // 测试4：ImageData (更新)
    console.time('WebGL - ImageData (update)');
    gl.bindTexture(gl.TEXTURE_2D, tex3);
    gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, img.width, img.height, gl.RGBA, gl.UNSIGNED_BYTE, data);
    console.timeEnd('WebGL - ImageData (update)'); // ~0.5-1ms ⭐⭐

    bitmap.close();
  }
}

WebGL 纹理更新策略

// 频繁更新场景：使用 DataTexture + texSubImage2D
class DynamicTexture {
  private texture: THREE.DataTexture;
  private needsUpdate = false;

  constructor(width: number, height: number) {
    const data = new Uint8Array(width * height * 4);
    this.texture = new THREE.DataTexture(data, width, height);
  }

  // 局部更新（性能最优）
  updateRegion(x: number, y: number, width: number, height: number, newData: Uint8Array) {
    const gl = renderer.getContext();
    const texture = this.texture.__webglTexture;

    gl.bindTexture(gl.TEXTURE_2D, texture);
    gl.texSubImage2D(
      gl.TEXTURE_2D,
      0,
      x, y,
      width, height,
      gl.RGBA,
      gl.UNSIGNED_BYTE,
      newData
    );

    this.needsUpdate = true;
  }

  // 标记更新
  markUpdate() {
    if (this.needsUpdate) {
      this.texture.needsUpdate = true;
      this.needsUpdate = false;
    }
  }
}

WebGL 性能排名

操作	耗时	性能	适用场景
`texSubImage2D` (局部更新)	~0.5-1ms	⭐⭐⭐	频繁更新
`texImage2D` (ImageData)	~2-3ms	⭐⭐	首次上传
`texImage2D` (ImageBitmap)	~2-3ms	⭐⭐	首次上传
`texImage2D` (HTMLImageElement)	~3-5ms	⭐	普通上传

结论：

✅ 首次上传：ImageBitmap 或 ImageData 均可
✅ 频繁更新：ImageData + texSubImage2D
✅ 避免重复上传整个纹理

点云数据的缓存策略

点云数据与图片不同，具有以下特点：

📊 数据量大：单帧可达 10-100 万点
🎯 结构化：每个点包含位置、颜色、法向量等
🔧 需要处理：滤波、分割、配准等

1. 点云数据结构

interface PointCloudData {
  positions: Float32Array;  // [x, y, z, x, y, z, ...]
  colors?: Uint8Array;       // [r, g, b, a, r, g, b, a, ...]
  normals?: Float32Array;    // [nx, ny, nz, nx, ny, nz, ...]
  intensities?: Float32Array;
  count: number;             // 点数量
}

// 内存占用估算
// positions: count * 3 * 4 bytes
// colors: count * 4 * 1 bytes
// 100万点 ≈ 16MB

2. 点云缓存模式

方案1：ArrayBuffer（推荐）

class PointCloudCache {
  // 存储为 ArrayBuffer（无额外开销）
  async store(key: string, pointCloud: PointCloudData) {
    // 序列化为 ArrayBuffer
    const metadata = new Uint32Array([pointCloud.count]);
    const positions = new Float32Array(pointCloud.positions);
    const colors = pointCloud.colors ? new Uint8Array(pointCloud.colors) : null;

    // 合并为单个 ArrayBuffer
    const totalSize = 4 + positions.byteLength + (colors?.byteLength || 0);
    const buffer = new ArrayBuffer(totalSize);
    const view = new DataView(buffer);

    // 写入元数据
    view.setUint32(0, pointCloud.count, true);

    // 写入位置
    new Float32Array(buffer, 4).set(positions);

    // 写入颜色（如果有）
    if (colors) {
      new Uint8Array(buffer, 4 + positions.byteLength).set(colors);
    }

    // 存储到 IndexedDB 或 FileSystem
    await this.storage.set(key, buffer);
  }

  // 读取（快速反序列化）
  async get(key: string): Promise<PointCloudData | null> {
    const buffer = await this.storage.get(key);
    if (!buffer) return null;

    const view = new DataView(buffer);
    const count = view.getUint32(0, true);

    const positions = new Float32Array(buffer, 4, count * 3);
    const colors = new Uint8Array(buffer, 4 + count * 3 * 4, count * 4);

    return {
      positions,
      colors,
      count
    };
  }
}

优势：

✅ 无额外序列化开销
✅ 内存布局紧凑
✅ 直接用于 WebGL（BufferAttribute）

方案2：压缩存储（节省空间）

class CompressedPointCloudCache {
  // 使用 Draco 压缩
  async storeCompressed(key: string, pointCloud: PointCloudData) {
    // 引入 Draco 编码器
    const DracoEncoder = (await import('draco3dgltf')).DracoEncoder;
    const encoder = new DracoEncoder();

    // 配置压缩参数
    encoder.SetSpeed(5); // 0-10, 越高速度越快，压缩率越低
    encoder.SetAttributeQuantization(
      DracoEncoder.POSITION,
      14 // 位置精度
    );

    // 编码
    const encodedBuffer = encoder.Encode(pointCloud.positions, pointCloud.colors);

    // 存储压缩后的数据
    await this.storage.set(key, encodedBuffer);
  }

  // 读取并解压
  async getCompressed(key: string): Promise<PointCloudData | null> {
    const compressedBuffer = await this.storage.get(key);
    if (!compressedBuffer) return null;

    const DracoDecoder = (await import('draco3dgltf')).DracoDecoder;
    const decoder = new DracoDecoder();

    // 解码
    const pointCloud = decoder.Decode(compressedBuffer);

    return pointCloud;
  }
}

压缩效果：

原始：100万点 ≈ 16MB
Draco 压缩：100万点 ≈ 2-4MB（压缩比 4-8x）
解压时间：~50-100ms

方案3：分块加载（流式渲染）

class ChunkedPointCloudLoader {
  private chunkSize = 100000; // 每块 10 万点

  // 分块存储
  async store(key: string, pointCloud: PointCloudData) {
    const chunks = Math.ceil(pointCloud.count / this.chunkSize);

    for (let i = 0; i < chunks; i++) {
      const start = i * this.chunkSize;
      const end = Math.min(start + this.chunkSize, pointCloud.count);

      const chunkPositions = pointCloud.positions.slice(start * 3, end * 3);
      const chunkColors = pointCloud.colors?.slice(start * 4, end * 4);

      const chunkBuffer = this.serializeChunk(chunkPositions, chunkColors);
      await this.storage.set(`${key}_chunk_${i}`, chunkBuffer);
    }

    // 存储元数据
    await this.storage.set(`${key}_metadata`, {
      count: pointCloud.count,
      chunks,
      chunkSize: this.chunkSize
    });
  }

  // 按需加载（视锥体裁剪）
  async loadInView(camera: THREE.Camera, frustum: THREE.Frustum) {
    const metadata = await this.storage.get(`${key}_metadata`);
    const chunksToLoad: number[] = [];

    // 视锥体裁剪，确定需要加载的块
    for (let i = 0; i < metadata.chunks; i++) {
      const chunkBounds = await this.getChunkBounds(`${key}_chunk_${i}`);
      if (frustum.intersectsBox(chunkBounds)) {
        chunksToLoad.push(i);
      }
    }

    // 并发加载可见块
    const chunks = await Promise.all(
      chunksToLoad.map(i => this.loadChunk(`${key}_chunk_${i}`))
    );

    return this.mergeChunks(chunks);
  }
}

优势：

✅ 减少初始加载时间
✅ 支持超大点云（千万级）
✅ 节省内存

3. 点云在 WebGL 中的优化

class OptimizedPointCloudRenderer {
  private geometry: THREE.BufferGeometry;
  private material: THREE.PointsMaterial;
  private points: THREE.Points;

  constructor() {
    this.geometry = new THREE.BufferGeometry();
    this.material = new THREE.PointsMaterial({
      size: 0.01,
      vertexColors: true,
      sizeAttenuation: true
    });
    this.points = new THREE.Points(this.geometry, this.material);
  }

  // 使用 BufferAttribute（避免重复创建）
  updatePointCloud(pointCloud: PointCloudData) {
    // 位置属性
    let positionAttribute = this.geometry.getAttribute('position') as THREE.BufferAttribute;
    if (!positionAttribute) {
      positionAttribute = new THREE.BufferAttribute(pointCloud.positions, 3);
      this.geometry.setAttribute('position', positionAttribute);
    } else {
      // 局部更新（性能最优）
      positionAttribute.copyArray(pointCloud.positions);
      positionAttribute.needsUpdate = true;
    }

    // 颜色属性
    if (pointCloud.colors) {
      let colorAttribute = this.geometry.getAttribute('color') as THREE.BufferAttribute;
      if (!colorAttribute) {
        colorAttribute = new THREE.BufferAttribute(pointCloud.colors, 4);
        this.geometry.setAttribute('color', colorAttribute);
      } else {
        colorAttribute.copyArray(pointCloud.colors);
        colorAttribute.needsUpdate = true;
      }
    }

    // 更新包围盒
    this.geometry.computeBoundingBox();
    this.geometry.computeBoundingSphere();
  }

  // 渐进式加载
  async progressiveLoad(pointCloudCache: PointCloudCache, key: string) {
    const metadata = await pointCloudCache.getMetadata(key);
    const totalChunks = metadata.chunks;

    for (let i = 0; i < totalChunks; i++) {
      const chunk = await pointCloudCache.loadChunk(key, i);
      this.mergeChunk(chunk);

      // 每加载一块，渲染一帧
      renderer.render(scene, camera);

      // 让出主线程
      await new Promise(resolve => setTimeout(resolve, 0));
    }
  }
}

实战：混合缓存架构设计

针对标注工具的完整缓存架构：

class HybridCacheSystem {
  // 三层缓存
  private memoryCache = new MemoryCache<ImageBitmap>();      // L1: 内存
  private idbCache = new IDBCache();                         // L2: IndexedDB
  private fsCache = new FileSystemCache();                   // L3: FileSystem

  private pointCloudCache = new PointCloudCache();           // 点云专用

  // 智能获取图片
  async getImage(url: string): Promise<ImageBitmap> {
    const cacheKey = this.generateKey(url);

    // L1: 内存缓存（最快）
    const memoryHit = this.memoryCache.get(cacheKey);
    if (memoryHit) {
      console.log('L1 Cache Hit (Memory)');
      return memoryHit;
    }

    // L2: IndexedDB（中速）
    const idbBitmap = await this.idbCache.get(url);
    if (idbBitmap) {
      console.log('L2 Cache Hit (IndexedDB)');
      this.memoryCache.set(cacheKey, idbBitmap);
      return idbBitmap;
    }

    // L3: FileSystem（慢速但容量大）
    if (this.fsCache.initialized) {
      const fsBitmap = await this.fsCache.get(`${cacheKey}.webp`);
      if (fsBitmap) {
        console.log('L3 Cache Hit (FileSystem)');
        this.memoryCache.set(cacheKey, fsBitmap);
        await this.idbCache.store(url, await this.bitmapToBlob(fsBitmap));
        return fsBitmap;
      }
    }

    // 网络加载
    console.log('Cache Miss, Loading from Network');
    return await this.loadFromNetwork(url);
  }

  // 预加载策略
  async preload(urls: string[], priority: 'high' | 'low' = 'low') {
    const batchSize = priority === 'high' ? 10 : 5;

    for (let i = 0; i < urls.length; i += batchSize) {
      const batch = urls.slice(i, i + batchSize);

      // 并发加载
      await Promise.all(batch.map(async (url) => {
        const bitmap = await this.getImage(url);
        
        // 高优先级：预热到内存
        if (priority === 'high') {
          this.memoryCache.set(this.generateKey(url), bitmap);
        }
      }));

      // 让出主线程
      await new Promise(resolve => setTimeout(resolve, 50));
    }
  }

  // 点云加载
  async getPointCloud(key: string): Promise<PointCloudData> {
    // 优先从内存加载
    const memoryPCD = this.memoryCache.get(`pcd_${key}`);
    if (memoryPCD) return memoryPCD;

    // 从专用缓存加载
    const pointCloud = await this.pointCloudCache.get(key);
    if (pointCloud) {
      this.memoryCache.set(`pcd_${key}`, pointCloud);
      return pointCloud;
    }

    throw new Error(`PointCloud not found: ${key}`);
  }

  private async loadFromNetwork(url: string): Promise<ImageBitmap> {
    const response = await fetch(url);
    const blob = await response.blob();
    const bitmap = await createImageBitmap(blob);

    const cacheKey = this.generateKey(url);

    // 并行写入多层缓存
    await Promise.all([
      this.idbCache.store(url, blob),
      this.fsCache.initialized 
        ? this.fsCache.store(`${cacheKey}.webp`, bitmap) 
        : Promise.resolve(),
      Promise.resolve().then(() => {
        this.memoryCache.set(cacheKey, bitmap);
      })
    ]);

    return bitmap;
  }

  private generateKey(url: string): string {
    return url.replace(/[^a-zA-Z0-9]/g, '_');
  }

  private async bitmapToBlob(bitmap: ImageBitmap): Promise<Blob> {
    const offscreen = new OffscreenCanvas(bitmap.width, bitmap.height);
    const ctx = offscreen.getContext('2d')!;
    ctx.drawImage(bitmap, 0, 0);
    return await offscreen.convertToBlob({ type: 'image/webp', quality: 0.9 });
  }
}

性能测试数据

图片缓存性能对比（1920x1080，100张）

操作	内存缓存	IndexedDB	FileSystem API
写入 100 张	~10ms	~800ms	~600ms
读取 100 张	~20ms	~500ms	~400ms
序列化开销	无	有（~30%）	无
存储体积	~800MB	~50MB	~50MB
持久化	❌	✅	✅

Canvas 2D 绘制性能（1000次）

方法	耗时	相对性能
`drawImage(ImageBitmap)`	12ms	100% ⭐
`drawImage(HTMLImageElement)`	18ms	67%
`drawImage(OffscreenCanvas)`	15ms	80%
`putImageData(ImageData)`	55ms	22%

WebGL 纹理上传性能

操作	耗时	适用场景
`texSubImage2D` (局部更新)	0.5-1ms	频繁更新 ⭐
`texImage2D` (ImageData)	2-3ms	首次上传
`texImage2D` (ImageBitmap)	2-3ms	首次上传 ⭐
`texImage2D` (HTMLImageElement)	3-5ms	普通上传

点云数据性能（100万点）

操作	原始格式	Draco 压缩
存储体积	16MB	2-4MB (4-8x)
加载时间	~50ms	~100ms
解压时间	无	~50ms
内存占用	16MB	16MB

最佳实践总结

📌 图片缓存策略

场景	推荐方案	理由
静态展示	`ImageBitmap` + 内存缓存	零延迟绘制
频繁更新	`ImageData` + `texSubImage2D`	局部更新最快
离线缓存	`FileSystem API` + `Blob`	无序列化开销
网络资源	`IndexedDB` + `Blob`	结构化查询
Worker 处理	`ImageBitmap` + `Transfer`	零拷贝

📌 点云缓存策略

场景	推荐方案	理由
小规模点云 (< 100万点)	`ArrayBuffer` + 内存	快速访问
大规模点云 (> 100万点)	`Draco 压缩` + 分块加载	节省空间
实时更新	`BufferAttribute` 局部更新	避免重建
离线项目	`FileSystem API`	大容量存储

📌 通用优化技巧

使用 ImageBitmap 替代 HTMLImageElement

// ❌ 不推荐
const img = new Image();
img.src = url;

// ✅ 推荐
const bitmap = await createImageBitmap(await fetch(url).then(r => r.blob()));

避免频繁的 putImageData

// ❌ 不推荐
for (let i = 0; i < 100; i++) {
  ctx.putImageData(imageData, 0, 0);
}

// ✅ 推荐
const offscreen = new OffscreenCanvas(width, height);
const offCtx = offscreen.getContext('2d')!;
offCtx.putImageData(imageData, 0, 0);
const bitmap = offscreen.transferToImageBitmap();

for (let i = 0; i < 100; i++) {
  ctx.drawImage(bitmap, 0, 0);
}

WebGL 纹理局部更新

// ❌ 不推荐
texture.needsUpdate = true; // 重新上传整个纹理

// ✅ 推荐
gl.texSubImage2D(...); // 只更新变化的部分

分层缓存架构

L1: Memory Cache (10 items)       - 1ms
L2: IndexedDB Cache (100 items)   - 50ms
L3: FileSystem Cache (unlimited)  - 100ms
Network Fallback                  - 500ms+

预加载策略

// 用户空闲时预加载
if ('requestIdleCallback' in window) {
  requestIdleCallback(() => {
    cache.preload(nextBatchUrls);
  }, { timeout: 2000 });
}

🎯 总结

在智驾、机器人标注工具等可视化场景中，选择正确的缓存策略至关重要：

核心要点

图片缓存：
- ✅ 优先使用 ImageBitmap（性能最优）
- ✅ 长期存储用 FileSystem API（无序列化开销）
- ✅ 频繁更新用 ImageData + texSubImage2D
点云缓存：
- ✅ 小规模：ArrayBuffer + 内存
- ✅ 大规模：Draco 压缩 + 分块加载
- ✅ 实时更新：BufferAttribute 局部更新
存储层选择：
- 内存缓存：热点数据（最快，易失）
- IndexedDB：中期缓存（有查询能力）
- FileSystem API：长期存储（无序列化开销）
性能优化：
- 避免重复解码
- 使用局部更新
- 分块加载大文件
- 预加载策略

最终建议

对于标注工具这类应用，推荐采用混合缓存架构：

// 三层缓存 + 智能预加载
const cache = new HybridCacheSystem();

// 图片：ImageBitmap + FileSystem API
const bitmap = await cache.getImage('image.jpg');

// 点云：Draco 压缩 + 分块加载
const pointCloud = await cache.getPointCloud('scan_001');

通过合理的缓存策略，可以将首屏加载时间从 3-5 秒优化到 0.5-1 秒，标注操作的帧率从 20-30 FPS 提升到 60 FPS，大幅提升用户体验！

📚 参考资料：

💬 互动： 你在项目中遇到过哪些缓存相关的性能问题？欢迎在评论区分享你的经验和解决方案！

本文首发于掘金，转载请注明出处。关注我，获取更多前端可视化、WebGL、性能优化干货！ 🚀

Vue3文本差异对比器实现方案

掘金前端

作者滕青山

2026年2月12日 11:00

Vue3文本差异对比器实现方案

本文将介绍本项目中 文本差异对比器 (Text Diff Checker) 工具的技术实现细节。该工具基于 Vue 3 框架开发，核心对比逻辑采用原生的 JavaScript 实现，通过动态加载的方式与 Vue 组件进行交互。

在线工具网址：see-tool.com/diff-checke…
工具截图：

1. 架构设计

为了保证核心算法的独立性和复用性，我们将 Diff 算法逻辑封装在 public/js/diff-checker.js 中，而 Vue 组件 pages/diff-checker.vue 仅负责 UI 交互和数据展示。

数据层 (Core JS): 负责文本的预处理、Diff 算法计算、HTML 渲染字符串生成以及统计信息计算。
视图层 (Vue): 负责用户输入、选项配置、调用核心方法并展示结果。

2. 核心算法实现 (diff-checker.js)

核心逻辑是一个基于 最长公共子序列 (LCS, Longest Common Subsequence) 的 Diff 算法。

2.1 文本预处理与并在

根据用户选择的“对比模式”，我们将输入文本分割成不同的单元：

行模式 (Line): 使用 split('\n') 按换行符分割。
词模式 (Word): 使用 split(/\s+/) 按空白字符分割。
字符模式 (Char): 使用 split('') 逐字符分割。

同时，根据配置选项处理“忽略空格”和“忽略大小写”：

if (ignoreWhitespace) {
    processedText1 = processedText1.replace(/\s+/g, ' ').trim();
    processedText2 = processedText2.replace(/\s+/g, ' ').trim();
}
// 忽略大小写则统一转为小写

2.2 LCS 算法与回溯

使用动态规划构建 DP 表，计算最长公共子序列的长度：

// DP 表构建
for (let i = 1; i <= m; i++) {
    for (let j = 1; j <= n; j++) {
        if (arr1[i - 1] === arr2[j - 1]) {
            dp[i][j] = dp[i - 1][j - 1] + 1;
        } else {
            dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
        }
    }
}

构建完成后，通过回溯 (Backtrack) 找出具体的 LCS 路径。

2.3 构建 Diff 结果

根据 LCS 路径，遍历原始序列，确定哪些部分是“新增 (added)”、“删除 (removed)”或“未变 (unchanged)”。

如果当前元素在 LCS 中，标记为 unchanged。
如果原序列中有但 LCS 中没有，标记为 removed。
如果新序列中有但 LCS 中没有，标记为 added。

2.4 结果渲染

为了提高性能，Diff 的结果直接由 JS 生成 HTML 字符串，而不是在 Vue 中使用 v-for 渲染成千上万个 DOM 节点。生成的 HTML 包含了行号、差异标识（+/-）以及高亮样式类。

/* 生成的 HTML 结构示例 */
<div class="diff-line diff-line-removed">
  <span class="diff-line-number">1</span>
  <span class="diff-line-number"></span>
  <span class="mr-2">-</span>
  Content
</div>

3. Vue 组件实现 (diff-checker.vue)

3.1 动态加载脚本

Vue 组件在挂载或需要使用时，通过创建 <script> 标签动态加载核心 JS 文件。为了防止重复加载，我们通过检查 window.DiffChecker 是否存在来判断。

const loadDiffCheckerScript = () => {
  if (window.DiffChecker) return Promise.resolve();
  // 创建 script 标签加载 /js/diff-checker.js
  // 监听 onload 和 onerror 事件
}

3.2 调用对比

当用户点击“开始对比”时，组件收集 leftText、rightText 以及 compareMode、ignoreWhitespace 等选项，调用核心对象的 compare 方法：

const result = window.DiffChecker.compare(leftText.value, rightText.value, compareMode.value, {
  ignoreWhitespace: ignoreWhitespace.value,
  ignoreCase: ignoreCase.value,
  showLineNumbers: showLineNumbers.value
})

3.3 结果展示

核心方法返回的 result 对象中包含了 diffHtml（差异内容的 HTML）和 statisticsHtml（统计信息的 HTML）。Vue 组件直接使用 v-html 指令将其渲染到页面上：

<div v-if="statisticsHtml" v-html="statisticsHtml"></div>
<div ref="diffOutput" v-html="diffOutputHtml"></div>

通过这种 Vue 处理交互 + 原生 JS 处理计算密集任务的分离模式，我们既保持了前端框架的开发效率，又保证了对比功能的性能与灵活性。

iframe → wujie 迁移收益分析与子应用集成方案

掘金前端

作者大象的鼻子那么长

2026年2月12日 10:58

一、背景

当前 CMCLink 平台存在两种微前端集成方案并行：

旧方案：原生 iframe 嵌入 + postMessage 通信（mkt、doc、ibs-manage 等子应用在用）
新方案：wujie iframe 沙箱 + bus 通信（template 子应用模板已验证，ibs-manage 已完成迁移试点）

本文档从决策层面和工程层面两个维度分析：

为什么要从 iframe 迁移到 wujie？投入产出比如何？
如何将子应用集成复杂度降到最低，让不同部门愿意迁移？

二、旧 iframe 方案的真实痛点

以下痛点均来自 ibs-manage 子应用迁移前的实际代码，非理论推演。

2.1 通信机制：postMessage 的脆弱性

旧方案代码（子应用 App.vue）：

// 子应用监听主应用消息
window.addEventListener('message', (event: MessageEvent) => {
  if (typeof event.data?.type === 'string') {
    if (event.data.type === 'router-change') {
      router.push({ path: event.data.payload.route })
    } else if (event.data.type === 'close-all-tab') {
      tagsViewStore.delAllViews()
    }
  }
})

// 主应用通知子应用
window.parent.postMessage({ type: 'router-change', payload: { route } }, origin)

问题：

问题	影响
消息类型是字符串魔法值，无 TypeScript 类型约束	拼写错误不会编译报错，只能运行时排查
数据需要序列化（不支持函数、循环引用）	复杂数据传递受限
跨域时 `origin` 校验容易出错	安全隐患或消息丢失
每个子应用独立实现消息协议	协议不统一，新增事件需要双端同步修改
无法追踪消息链路	调试困难，`console.log` 满天飞

wujie 方案：

// 统一的 EventEmitter 模式，有类型约束
bus.$emit('CHILD_ROUTE_CHANGE', { appName, path, name, query })
bus.$on('ROUTE_CHANGE_TO_CHILD', (data) => { router.push(data.path) })

2.2 路由同步：hack 堆叠

旧方案代码（子应用 App.vue）：

// 路由恢复：3 层 fallback
const restoreRoute = () => {
  let targetPath = ''
  // 1. 尝试从父页面 URL 参数获取
  try {
    if (window.parent !== window && window.parent.location.hostname === window.location.hostname) {
      targetPath = new URLSearchParams(window.parent.location.search).get('childPath') || ''
    }
  } catch { /* 跨域失败 */ }
  // 2. 回退到 localStorage
  if (!targetPath) {
    targetPath = localStorage.getItem('ibs-manage-latest-path') || ''
  }
  // 3. 兜底空路径
  router.replace(targetPath || '')
}

问题：

问题	影响
跨域部署时 `parent.location` 不可访问	路由恢复完全失效
localStorage 在多 Tab 场景下互相覆盖	Tab A 刷新可能恢复到 Tab B 的路由
主应用 URL 不反映子应用当前路由	无法通过 URL 分享/收藏具体页面
每个子应用独立实现恢复逻辑	代码重复，bug 各异

wujie 方案：

# 主应用 URL 自动同步子应用路由（sync 模式）
http://localhost:3000/ibs-manage/operation/xxx?ibs-manage={~}/operation/xxx

# F5 刷新时 wujie 自动从 URL query 恢复子应用路由，零代码

2.3 状态共享：Token 传递的安全隐患

旧方案：

Token 通过 URL 参数传递给 iframe → 明文暴露在浏览器历史记录和服务器日志中
或依赖同域 Cookie → 跨域部署时失效
或通过 postMessage 传递 → 需要手动管理刷新/过期同步

wujie 方案：

// 主应用通过 props 注入，子应用通过 __WUJIE.props 读取
// 内存传递，不经过 URL/Cookie，不序列化
const sharedAuth = (window as any).__WUJIE?.props?.$shared?.auth
// token、userInfo、permissions、menus 一次性获取

2.4 性能：首屏加载体验

指标	iframe 方案	wujie 方案
首次打开子应用	2-5 秒白屏（iframe 从零加载 HTML + JS + CSS）	<500ms（preloadApp 预加载 + alive 保活）
切换已访问子应用	1-3 秒（iframe 重新加载或从 bfcache 恢复）	瞬切（alive 模式保持 Vue 实例不销毁）
子应用内部路由切换	正常	正常
keep-alive 页面缓存	❌ 不支持（iframe 销毁即丢失）	✅ 支持（alive 模式 + 自动缓存同步）

2.5 开发体验

维度	iframe 方案	wujie 方案
DevTools 调试	需切换 iframe context	同一 DevTools 窗口
HMR 热更新	正常	正常
独立运行	✅ 支持	✅ 支持
联调成本	高（需同时启动主应用 + 子应用，调试 postMessage 链路）	低（bus 事件可在 DevTools 中直接观察）

三、迁移投入成本

3.1 一次性投入（已完成）

项目	工时	状态
`@cmclink/micro-bootstrap` 子应用启动器	2 人天	✅ 已完成
`@cmclink/micro-bridge` 通信桥接 + 注册表	2 人天	✅ 已完成
`@cmclink/vite-config` 统一构建配置	1 人天	✅ 已完成
主应用 AuthenticatedLayout WujieVue 容器	1 人天	✅ 已完成
主应用 shared-provider 状态广播	1 人天	✅ 已完成
template 子应用模板验证	0.5 人天	✅ 已完成
ibs-manage 迁移试点	1 人天	✅ 已完成
合计	~8.5 人天	已完成

3.2 单个子应用迁移成本

基于 ibs-manage 实际迁移数据：

步骤	工时	说明
改 vite.config.ts	15 分钟	替换为 `createChildAppConfig`
改 src/main.ts	30 分钟	替换为 `bootstrapMicroApp`
改 src/App.vue	2-4 小时	wujie 适配（共享数据注入 + 路由恢复）
改 src/router/index.ts	15 分钟	删除旧通知逻辑
改 env + package.json	15 分钟	端口 + 依赖
主应用配置	15 分钟	env + 路由 + 注册表
联调验证	2-4 小时	路由 + 状态 + Tab + 刷新
合计	0.5-1.5 人天	视子应用复杂度而定

3.3 长期维护成本对比

场景	iframe 方案	wujie 方案
新增通信事件	双端各加 postMessage 处理（~30 行/事件）	注册表加类型 + bus.$on（~5 行/事件）
新增子应用	复制粘贴 ~150 行通信代码 + 调试适配	`bootstrapMicroApp` 一行启动
修复路由同步 bug	每个子应用独立排查	统一在 micro-bridge 修复，所有子应用受益
升级 Vue/Router 版本	每个子应用独立处理	micro-bootstrap 统一兼容

四、风险评估

4.1 迁移风险

风险	概率	影响	缓解措施
wujie 框架停止维护	低（GitHub 活跃，腾讯开源）	中	wujie 核心代码量小（~3000 行），可 fork 自维护
子应用版本不兼容	中	低	micro-bootstrap 已放宽类型约束，支持 vue@3.4/3.5 共存
样式隔离不完美	低	低	WebComponent shadowDOM 隔离 + teleported=false 弹窗隔离
迁移期间两套方案并存	确定	低	App.vue 中 `isWujie` / `isInIframe` 分支兼容，可渐进迁移

4.2 不迁移的风险

风险	概率	影响
postMessage 协议碎片化加剧	高	高 — 新子应用接入成本持续增加
路由同步 bug 反复出现	高	中 — 用户体验差，开发疲于修补
无法实现 keep-alive 缓存	确定	中 — 表单填写中途切换 Tab 数据丢失
首屏性能无法优化	确定	中 — 每次切换子应用白屏 2-5 秒

五、子应用集成简化方案（v2 提案）

5.1 问题：当前集成仍然太重

ibs-manage 迁移后，App.vue 中仍有 ~80 行 wujie 适配代码：

injectSharedDataFromWujie()     — 25 行（从 props.$shared 注入 token/user/menus）
wujie 路由恢复                   — 15 行（await generateRoutes + router.replace）
isWujie 环境检测                 — 3 行
document.title / localStorage 分支 — 10 行
旧 iframe 兼容逻辑               — 30 行

这些代码对每个子应用都是几乎相同的模板代码。如果其他部门（mkt、doc、finance 等）迁移时都要手动写这些，集成意愿度会很低。

5.2 目标：子应用 App.vue 零 wujie 感知

理想状态：子应用开发者完全不需要知道 wujie 的存在。App.vue 只写业务逻辑，所有微前端适配在 bootstrapMicroApp 中自动完成。

5.3 方案：micro-bootstrap 新增 `sharedData` 配置

在 BootstrapOptions 中新增一个配置项，让 micro-bootstrap 自动完成共享数据注入：

// ===== 子应用 main.ts（简化后）=====
bootstrapMicroApp({
  app: App,
  router,
  pinia: store,
  appId: '#ibs-manage',
  appName: 'ibs-manage',
  tagsViewStore: () => useTagsViewStore(store),
  plugins: [setupI18n, setupElementPlus, setupGlobCom],

  // 🆕 共享数据注入配置（micro-bootstrap 自动处理 wujie props → 本地缓存）
  sharedData: {
    // 缓存适配器：告诉 bootstrap 如何读写子应用的本地缓存
    cache: {
      get: (key: string) => wsCache.get(key),
      set: (key: string, value: any) => wsCache.set(key, value),
    },
    // 缓存 key 映射
    keys: {
      accessToken: 'ACCESS_TOKEN',
      refreshToken: 'REFRESH_TOKEN',
      user: 'USER',  // 对应 CACHE_KEY.USER
    },
  },

  // 🆕 动态路由注册回调（可选，有动态路由的子应用才需要）
  onBeforeMount: async ({ router, cache }) => {
    const userInfo = cache.get('USER')
    if (userInfo?.menus) {
      userStore.menus = userInfo.menus
      await generateRoutes()
    }
  },
})

子应用 App.vue 变化：

  // ========== 应用初始化 ==========
  const init = async () => {
-   // wujie 环境：从主应用共享数据注入 token 和用户信息
-   if (isWujie) {
-     injectSharedDataFromWujie()
-   }
-
-   // 从缓存加载用户信息并生成动态路由
-   const userInfo = wsCache.get(CACHE_KEY.USER)
-   if (userInfo) {
-     if (userInfo.menus) {
-       userStore.menus = userInfo.menus
-       await generateRoutes()
-     }
-     if (userInfo.user) {
-       userInfoRef.value = userInfo.user
-     }
-   }
+   // 共享数据注入 + 动态路由注册已由 micro-bootstrap 自动处理
+   // 此处只需读取缓存中的用户信息用于 UI 显示
+   const userInfo = wsCache.get(CACHE_KEY.USER)
+   if (userInfo?.user) {
+     userInfoRef.value = userInfo.user
+   }

    if (getAccessToken()) {
      userStore.setUserInfoAction()
    }

-   // wujie 环境：动态路由注册后重新匹配当前路径
-   if (isWujie) {
-     const currentPath = router.currentRoute.value.fullPath
-     if (currentPath && currentPath !== '/') {
-       await router.replace(currentPath)
-     }
-   }
-
-   // 非 wujie 环境：从 localStorage / 父页面恢复路由
-   restoreRouteForLegacyMode()
+   // 路由恢复已由 micro-bootstrap 自动处理（wujie sync / localStorage fallback）
  }

减少 ~50 行 wujie 适配代码，App.vue 只剩纯业务逻辑。

5.4 micro-bootstrap 内部实现要点

// micro-bootstrap 内部（伪代码）
async function bootstrapMicroApp(options: BootstrapOptions) {
  const isWujie = !!(window as any).__WUJIE

  // ... 创建 app、安装插件 ...

  // 🆕 自动注入共享数据（mount 之前）
  if (isWujie && options.sharedData) {
    injectSharedData(options.sharedData)
  }

  // 🆕 执行用户自定义的 mount 前回调（动态路由注册等）
  if (options.onBeforeMount) {
    await options.onBeforeMount({
      router,
      cache: options.sharedData?.cache,
    })
  }

  // 挂载应用
  mount()

  // 🆕 wujie 环境：动态路由注册后自动恢复路由
  if (isWujie) {
    const currentPath = router.currentRoute.value.fullPath
    if (currentPath && currentPath !== '/') {
      await router.replace(currentPath)
    }
  }
}

function injectSharedData(config: SharedDataConfig) {
  const sharedAuth = (window as any).__WUJIE?.props?.$shared?.auth
  if (!sharedAuth) return

  const { cache, keys } = config
  if (sharedAuth.token) cache.set(keys.accessToken, sharedAuth.token)
  if (sharedAuth.refreshToken) cache.set(keys.refreshToken, sharedAuth.refreshToken)
  if (sharedAuth.userInfo) {
    const cachedUser = cache.get(keys.user) || {}
    cachedUser.user = sharedAuth.userInfo
    cachedUser.permissions = sharedAuth.permissions || []
    cachedUser.roles = sharedAuth.roles || []
    if (sharedAuth.menus) cachedUser.menus = sharedAuth.menus
    cache.set(keys.user, cachedUser)
  }
}

5.5 集成复杂度对比

维度	旧 iframe 方案	wujie 当前（v1）	wujie 简化后（v2 提案）
main.ts	~185 行（手动生命周期）	~53 行（bootstrapMicroApp）	~53 行（不变）
App.vue wujie 代码	0（但有 ~150 行 postMessage 代码）	~80 行	~10 行（仅读缓存用于 UI）
router/index.ts	~71 行（含旧通知）	~52 行	~52 行（不变）
子应用需要理解的概念	postMessage 协议、origin 校验、序列化	wujie props、bus、sync、prefix	只需知道 bootstrapMicroApp 的配置项
新增子应用工时	1-2 人天	0.5-1.5 人天	2-4 小时

5.6 对不同子应用类型的适配

子应用类型	sharedData	onBeforeMount	说明
新子应用（无动态路由）	✅ 配置	不需要	最简单，2 小时搞定
存量子应用（有动态路由）	✅ 配置	✅ 提供回调	需要在回调中注册动态路由
存量子应用（有旧 iframe 兼容）	✅ 配置	✅ 提供回调	App.vue 保留 `isInIframe` 分支，渐进清理

六、推荐迁移策略

6.1 渐进式迁移路线

阶段一（已完成）：基础设施 + ibs-manage 试点
    ↓
阶段二（当前）：实现 v2 简化方案 + 迁移 doc 子应用验证
    ↓
阶段三：推广到 mkt、finance 等子应用（各部门自行迁移，提供文档 + 模板）
    ↓
阶段四：清理旧 iframe 兼容代码 + 统一 vue/vue-router 版本

6.2 并行兼容期

迁移期间，子应用 App.vue 通过 isWujie / isInIframe 分支同时支持两种模式：

const isWujie = !!(window as any).__WUJIE
const isInIframe = !isWujie && window.parent !== window

// wujie 环境：由 micro-bootstrap 自动处理
// 旧 iframe 环境：保留原有 postMessage 逻辑
// 独立运行：正常启动

旧 iframe 方案不需要立即下线，可以在所有子应用迁移完成后统一清理。

6.3 各部门迁移支持

支持项	内容
迁移文档	`docs/migration/ibs-manage-wujie-集成迁移指南.md`（已产出）
子应用模板	`apps/template/`（可直接 copy 作为新子应用骨架）
排错指南	迁移文档第 7 章（8 个常见问题 + 排查步骤）
培训文档	`docs/training/`（5 章，覆盖 L1-L3 三个梯队）
Code Review	首个迁移子应用由架构组 review，后续自行迁移

七、决策建议

迁移的核心论点

基础设施投入（8.5 人天）已完成且沉没。单个子应用迁移成本仅 0.5-1.5 人天（v2 简化后降至 2-4 小时），但能获得：

首屏性能提升 5-10 倍（预加载 + alive 保活）

消除 ~150 行/子应用的重复通信代码

F5 刷新可靠恢复（wujie sync 机制，零代码）

keep-alive 页面缓存（iframe 方案无法实现）

统一的通信协议（有类型约束，bug 减少）

不迁移的隐性成本（每次新功能都要在 postMessage 协议上打补丁、路由同步 bug 反复出现、无法实现缓存）远大于一次性迁移成本。

建议行动项

评审本方案，确认 v2 简化方案的 API 设计
实现 v2 简化，在 micro-bootstrap 中落地 sharedData + onBeforeMount
用 doc 子应用验证 v2 简化方案的实际效果
发布迁移通知，各部门按优先级排期迁移
设定清理时间线，在所有子应用迁移完成后统一清理旧 iframe 代码

附录：术语表

术语	说明
wujie	腾讯开源的微前端框架，基于 iframe 沙箱 + WebComponent 容器
alive 模式	wujie 保活模式，切换子应用时不销毁 Vue 实例
sync 模式	wujie 路由同步模式，子应用路由写入主应用 URL query
prefix	wujie sync 短路径映射，压缩 URL query 长度
micro-bootstrap	CMCLink 子应用统一启动器，封装 wujie 生命周期
micro-bridge	CMCLink 通信桥接层，封装 wujie bus + 子应用注册表
shared-provider	主应用状态广播器，将 Pinia store 数据广播给子应用

基于 Vue + Node.js 自动发布服务脚本

掘金前端

作者赤兔之神

2026年2月12日 10:57

基于 Vue 和 Node.js 的自动化发布服务脚本实现方案，该方案主要依赖 node-ssh（用于服务器 SSH 连接）和 archiver（用于文件压缩打包）两大核心模块。通过与 package.json 中配置的多环境部署脚本协同工作，在 deploy 目录下构建完整的发布流程。以下将详细介绍脚本开发、环境配置及使用说明，确保完全符合您的项目需求。

一、环境准备：依赖安装

请在 Vue 项目根目录执行以下命令安装必要依赖（包括 rimraf 清理工具，该依赖已在您的 package.json 中配置，建议一并确认安装状态）：

# 核心依赖：ssh连接、压缩打包
npm i node-ssh archiver -D
# 清理依赖（若未安装）
npm i rimraf -D
# ssh
npm i node-ssh -D

二、项目目录结构

在 Vue 项目根目录新建 deploy 文件夹，最终目录结构如下（新增文件已标注）：

三、编写 deploy 文件夹下的核心文件

deploy/index.js ：部署入口文件核心逻辑：解析命令行的环境参数 → 执行 Vue 打包 → 压缩 dist 目录为 zip 包 → SSH 连接服务器 → 上传压缩包并解压 → 清理临时文件 → 完成部署，全程自动化，无需手动操作：

 * 自动化部署脚本
 * @description 实现项目打包、压缩、上传、备份、解压等自动化部署功能
 */
const { NodeSSH } = require("node-ssh");
const archiver = require("archiver");
const fs = require("fs");
const path = require("path");
const { exec } = require("child_process");
const util = require("util");
const execPromise = util.promisify(exec);

/**
 * 获取环境配置
 * @returns {Object} 配置对象
 */
function getConfig() {
  // 从命令行参数获取环境，例如: node deploy/index.js --env=test
  const args = process.argv.slice(2);
  let env = "prod"; // 默认生产环境

  // 解析命令行参数
  for (const arg of args) {
    if (arg.startsWith("--env=")) {
      env = arg.split("=")[1];
    }
  }

  // 如果有环境变量 DEPLOY_ENV，优先使用
  if (process.env.DEPLOY_ENV) {
    env = process.env.DEPLOY_ENV;
  }

  // 处理 production 别名
  if (env === "production") {
    env = "prod";
  }

  // 直接根据环境名称构建配置文件路径
  const configFile = `./config.${env}.js`;
  const configPath = path.join(__dirname, configFile);

  // 检查配置文件是否存在
  if (!fs.existsSync(configPath)) {
    throw new Error(
      `配置文件不存在: ${configFile}\n` +
        `请创建 deploy/config.${env}.js 文件，或使用已有的环境配置。\n` +
        `可用环境示例: test, prod, xj, mj`
    );
  }

  console.log(`\x1b[36m[INFO]\x1b[0m 使用配置环境: ${env}`);
  console.log(`\x1b[36m[INFO]\x1b[0m 配置文件: ${configFile}`);

  return require(configFile);
}

const config = getConfig();

const ssh = new NodeSSH();

/**
 * 输出带颜色的日志
 */
const log = {
  info: (msg) => console.log(`\x1b[36m[INFO]\x1b[0m ${msg}`),
  success: (msg) => console.log(`\x1b[32m[SUCCESS]\x1b[0m ${msg}`),
  error: (msg) => console.log(`\x1b[31m[ERROR]\x1b[0m ${msg}`),
  warning: (msg) => console.log(`\x1b[33m[WARNING]\x1b[0m ${msg}`),
};

/**
 * 步骤1: 执行项目打包
 * @returns {Promise<void>}
 */
async function buildProject() {
  log.info("开始执行项目打包...");
  try {
    const { stdout, stderr } = await execPromise(config.build.command);
    if (stderr && !stderr.includes("warning")) {
      log.warning(`构建警告: ${stderr}`);
    }
    log.success("项目打包完成!");
    return true;
  } catch (error) {
    log.error(`项目打包失败: ${error.message}`);
    throw error;
  }
}

/**
 * 步骤2: 压缩dist文件夹为zip
 * @returns {Promise<string>} 返回zip文件路径
 */
async function compressDistToZip() {
  log.info("开始压缩dist文件夹...");

  const { localDistPath, localZipName } = config.deploy;
  const zipPath = path.join(process.cwd(), localZipName);

  // 如果已存在zip文件，先删除
  if (fs.existsSync(zipPath)) {
    fs.unlinkSync(zipPath);
  }

  // 检查 dist 目录是否存在
  if (!fs.existsSync(localDistPath)) {
    throw new Error(`dist目录不存在: ${localDistPath}`);
  }

  return new Promise((resolve, reject) => {
    const output = fs.createWriteStream(zipPath);
    const archive = archiver("zip", {
      zlib: { level: 9 }, // 压缩级别
    });

    let fileCount = 0;

    output.on("close", () => {
      const size = (archive.pointer() / 1024 / 1024).toFixed(2);
      log.success(`压缩完成! 文件大小: ${size} MB, 文件数: ${fileCount}`);
      log.info(`压缩包路径: ${zipPath}`);
      resolve(zipPath);
    });

    archive.on("error", (err) => {
      log.error(`压缩失败: ${err.message}`);
      reject(err);
    });

    archive.on("warning", (err) => {
      if (err.code === "ENOENT") {
        log.warning(`压缩警告: ${err.message}`);
      } else {
        reject(err);
      }
    });

    // 监听文件添加事件
    archive.on("entry", (entry) => {
      fileCount++;
    });

    archive.pipe(output);

    // 将dist文件夹内容添加到压缩包根目录
    // false 参数表示不包含 dist 文件夹本身，直接将其内容放在 zip 根目录
    archive.directory(localDistPath, false);

    archive.finalize();
  });
}

/**
 * 步骤3: 连接SSH服务器
 * @returns {Promise<void>}
 */
async function connectSSH() {
  log.info("正在连接SSH服务器...");
  try {
    await ssh.connect({
      host: config.server.host,
      port: config.server.port,
      username: config.server.username,
      password: config.server.password,
    });
    log.success(`成功连接到服务器: ${config.server.host}`);
  } catch (error) {
    log.error(`SSH连接失败: ${error.message}`);
    throw error;
  }
}

/**
 * 步骤4: 备份服务器上的dist目录
 * @returns {Promise<void>}
 */
async function backupRemoteDist() {
  log.info("正在备份服务器上的dist目录...");

  const { remoteDir, remoteDist, backupDir } = config.deploy;
  const remoteDistPath = `${remoteDir}/${remoteDist}`;

  // 生成时间戳：格式如 20260204_153045
  const now = new Date();
  const year = now.getFullYear();
  const month = String(now.getMonth() + 1).padStart(2, "0");
  const day = String(now.getDate()).padStart(2, "0");
  const hours = String(now.getHours()).padStart(2, "0");
  const minutes = String(now.getMinutes()).padStart(2, "0");
  const seconds = String(now.getSeconds()).padStart(2, "0");
  const timestamp = `${year}${month}${day}_${hours}${minutes}${seconds}`;

  const backupPath = `${backupDir}/${remoteDist}_backup_${timestamp}`;
  log.info(`备份时间: ${year}-${month}-${day} ${hours}:${minutes}:${seconds}`);

  try {
    // 检查dist目录是否存在
    const checkCmd = `[ -d "${remoteDistPath}" ] && echo "exists" || echo "not_exists"`;
    const checkResult = await ssh.execCommand(checkCmd);

    if (checkResult.stdout.trim() === "exists") {
      // 创建备份目录
      await ssh.execCommand(`mkdir -p ${backupDir}`);

      // 备份dist目录
      const backupCmd = `cp -r ${remoteDistPath} ${backupPath}`;
      await ssh.execCommand(backupCmd);
      log.success(`备份完成: ${backupPath}`);
    } else {
      log.warning("服务器上不存在dist目录，跳过备份");
    }
  } catch (error) {
    log.error(`备份失败: ${error.message}`);
    throw error;
  }
}

/**
 * 步骤5: 上传zip文件到服务器（已合并到步骤6）
 * @deprecated 此步骤已合并
 */

/**
 * 步骤6: 上传zip文件到服务器
 * @param {string} zipPath 本地zip文件路径
 * @returns {Promise<void>}
 */
async function uploadZipToServer(zipPath) {
  log.info("正在上传dist.zip到服务器...");

  const { remoteDir, localZipName } = config.deploy;
  const remoteZipPath = `${remoteDir}/${localZipName}`;

  try {
    // 获取文件大小
    const stats = fs.statSync(zipPath);
    const fileSize = stats.size;
    const fileSizeMB = (fileSize / 1024 / 1024).toFixed(2);
    log.info(`文件大小: ${fileSizeMB} MB`);

    // 上传文件并显示进度（提高并发数加速上传）
    await ssh.putFile(zipPath, remoteZipPath, null, {
      concurrency: 20, // 提高并发数，加速上传
      chunkSize: 32768, // 32KB 块大小
      step: (transferred, chunk, total) => {
        const percent = ((transferred / total) * 100).toFixed(2);
        const transferredMB = (transferred / 1024 / 1024).toFixed(2);
        const totalMB = (total / 1024 / 1024).toFixed(2);
        const speed = (chunk / 1024 / 1024).toFixed(2);
        // 使用\r回到行首，实现进度条效果
        process.stdout.write(
          `\r\x1b[36m[INFO]\x1b[0m 上传进度: ${percent}% (${transferredMB}MB / ${totalMB}MB) 速度: ${speed}MB/s`
        );
      },
    });

    // 上传完成后换行
    console.log("");
    log.success(`上传完成: ${remoteZipPath}`);
  } catch (error) {
    console.log(""); // 确保错误信息另起一行
    log.error(`上传失败: ${error.message}`);
    throw error;
  }
}

/**
 * 步骤7: 在服务器上解压zip文件并替换dist
 * @returns {Promise<void>}
 */
async function unzipAndReplaceDist() {
  log.info("正在解压dist.zip并准备替换...");

  const { remoteDir, localZipName, remoteDist } = config.deploy;
  const remoteZipPath = `${remoteDir}/${localZipName}`;
  const remoteDistPath = `${remoteDir}/${remoteDist}`;

  try {
    // 检查zip文件是否存在
    const checkZipCmd = `[ -f "${remoteZipPath}" ] && echo "exists" || echo "not_exists"`;
    const checkZipResult = await ssh.execCommand(checkZipCmd);

    if (checkZipResult.stdout.trim() !== "exists") {
      throw new Error("服务器上的zip文件不存在");
    }

    log.info("正在检查zip文件内容...");
    const listZipCmd = `unzip -l ${remoteZipPath} | head -20`;
    const listResult = await ssh.execCommand(listZipCmd);
    log.info("zip文件内容预览:");
    console.log(listResult.stdout);

    // 创建临时目录并解压
    const tempDir = `${remoteDir}/temp_dist_${Date.now()}`;
    log.info(`解压到临时目录: ${tempDir}`);

    // 解压命令：使用 -o 覆盖已存在文件
    const unzipCmd = `mkdir -p ${tempDir} && unzip -o -q ${remoteZipPath} -d ${tempDir}`;
    const unzipResult = await ssh.execCommand(unzipCmd);

    if (unzipResult.code !== 0) {
      log.error(`解压错误: ${unzipResult.stderr}`);
      // 清理临时目录
      await ssh.execCommand(`rm -rf ${tempDir}`);
      throw new Error(`解压失败: ${unzipResult.stderr}`);
    }

    // 检查解压后的内容和文件数量
    const checkContentCmd = `ls -lah ${tempDir} | head -20 && echo "--- 文件统计 ---" && find ${tempDir} -type f | wc -l`;
    const contentResult = await ssh.execCommand(checkContentCmd);
    log.info("解压后的内容:");
    console.log(contentResult.stdout);

    // 删除旧dist并用临时目录替换（使用原子操作）
    log.info(`正在替换目标目录: ${remoteDistPath}`);

    // 方案：先删除旧的，再重命名新的（更可靠）
    const deleteOldCmd = `rm -rf ${remoteDistPath}`;
    const deleteResult = await ssh.execCommand(deleteOldCmd);

    if (deleteResult.code !== 0 && deleteResult.stderr) {
      log.warning(`删除旧目录警告: ${deleteResult.stderr}`);
    }

    const moveCmd = `mv ${tempDir} ${remoteDistPath}`;
    const moveResult = await ssh.execCommand(moveCmd);

    if (moveResult.code !== 0) {
      log.error(`移动失败: ${moveResult.stderr}`);
      throw new Error(`替换文件失败: ${moveResult.stderr}`);
    }

    log.success("替换完成");

    // 验证最终结果 - 显示详细信息
    log.info("正在验证部署结果...");
    const verifyCmd = `
      echo "=== 目录内容 ===" && 
      ls -lah ${remoteDistPath} | head -20 && 
      echo "" && 
      echo "=== 文件统计 ===" && 
      echo "总文件数: $(find ${remoteDistPath} -type f | wc -l)" && 
      echo "总目录数: $(find ${remoteDistPath} -type d | wc -l)" && 
      echo "总大小: $(du -sh ${remoteDistPath} | cut -f1)" &&
      echo "" &&
      echo "=== index.html 信息 ===" &&
      ls -lh ${remoteDistPath}/index.html 2>/dev/null || echo "index.html 不存在"
    `;
    const verifyResult = await ssh.execCommand(verifyCmd);
    console.log(verifyResult.stdout);

    if (verifyResult.code !== 0) {
      log.warning("验证过程中出现警告，但部署已完成");
    }

    // 删除zip文件
    await ssh.execCommand(`rm -f ${remoteZipPath}`);
    log.success("清理临时文件完成");
  } catch (error) {
    log.error(`操作失败: ${error.message}`);
    // 清理可能的临时目录
    await ssh.execCommand(`rm -rf ${remoteDir}/temp_dist_*`);
    throw error;
  }
}

/**
 * 步骤8: 清理本地zip文件
 * @param {string} zipPath 本地zip文件路径
 * @returns {void}
 */
function cleanupLocalZip(zipPath) {
  log.info("正在清理本地临时文件...");
  try {
    if (fs.existsSync(zipPath)) {
      fs.unlinkSync(zipPath);
      log.success("本地临时文件清理完成");
    }
  } catch (error) {
    log.warning(`清理本地文件失败: ${error.message}`);
  }
}

/**
 * 主部署流程
 */
async function deploy() {
  const startTime = Date.now();
  console.log("\n");
  log.info("========================================");
  log.info("          开始自动化部署流程");
  log.info("========================================");
  log.info(`目标服务器: ${config.server.host}`);
  log.info(`部署目录: ${config.deploy.remoteDir}/${config.deploy.remoteDist}`);
  log.info(`构建模式: ${config.build.mode}`);
  log.info("========================================\n");

  let zipPath = "";

  try {
    // 1. 打包项目
    await buildProject();
    console.log("\n");

    // 2. 压缩dist
    zipPath = await compressDistToZip();
    console.log("\n");

    // 3. 连接SSH
    await connectSSH();
    console.log("\n");

    // 4. 备份服务器dist
    await backupRemoteDist();
    console.log("\n");

    // 5. 上传zip
    await uploadZipToServer(zipPath);
    console.log("\n");

    // 6. 解压zip并替换dist
    await unzipAndReplaceDist();
    console.log("\n");

    // 8. 清理本地zip
    cleanupLocalZip(zipPath);
    console.log("\n");

    const duration = ((Date.now() - startTime) / 1000).toFixed(2);
    log.info("========================================");
    log.success(`       部署成功! 耗时: ${duration}秒`);
    log.info("========================================\n");
  } catch (error) {
    log.error(`\n部署失败: ${error.message}\n`);
    // 清理本地文件
    if (zipPath) {
      cleanupLocalZip(zipPath);
    }
    process.exit(1);
  } finally {
    // 断开SSH连接
    if (ssh.isConnected()) {
      ssh.dispose();
      log.info("SSH连接已关闭");
    }
  }
}

// 执行部署
if (require.main === module) {
  deploy();
}

module.exports = { deploy };

deploy/config.XX.js ：多环境服务器配置文件
集中管理 prod/xj/mj/test 四个环境的SSH 连接信息、服务器部署目录，后续修改环境配置仅需改此文件，按需替换你的实际配置：

 * 测试环境部署配置
 * @description 测试服务器配置
 */
module.exports = {
  // 服务器配置
  server: {
    host: "1.1.1.1",
    port: 22,
    username: "admin",
    password: "123",
  },

  // 部署配置
  deploy: {
    localDistPath: "./dist",
    localZipName: "dist.zip",
    remoteDir: "/home/web",
    remoteDist: "dist",
    backupDir: "/home/web/backup",
  },

  // 构建配置
  build: {
    command: "npm run build:test",
    mode: "test",
  },
};

四、package.json 脚本说明（你的原有配置，无需修改）

你的 package.json 中已配置好多环境启动、打包、部署脚本，对应关系如下，直接执行即可：

  // 本地启动脚本（按环境区分，无需修改）
  "serve": "vue-cli-service serve",
  "dev": "vue-cli-service serve",
  "test": "vue-cli-service serve --mode test",
  "start": "npm run dev",
  // 核心部署脚本：执行后自动打包+发布到对应服务器
  "deploy:prod": "node deploy/index.js --env=prod",
  "deploy:xj": "node deploy/index.js --env=xj",
  "deploy:mj": "node deploy/index.js --env=mj",
  "deploy:test": "node deploy/index.js --env=test",
}

五、使用说明

修改配置：先修改 deploy/config.js 中四个环境的服务器 IP、账号、密码、部署目录，确保信息正确；
执行部署：在项目根目录执行对应环境的部署命令，全程自动化，示例：

npm run deploy:prod
# 部署到测试环境
npm run deploy:test

部署流程：执行命令后，脚本会自动完成「环境打包 → 压缩 dist → SSH 连服务器 → 上传解压 → 清理临时文件」，全程控制台输出彩色日志，成功 / 失败一目了然。

六、关键注意事项

服务器准备：

安装unzip工具（CentOS执行yum install unzip -y，Ubuntu执行apt install unzip -y）确保部署目录具有读写权限（推荐使用root账户或授权对应账号）打包配置：默认test环境执行npm run build:test 其他环境执行npm run build 日志与错误处理：

任一环节失败时自动终止流程，并输出红色错误提示自动清理临时文件并断开SSH连接，确保无资源残留部署说明：

安装核心依赖：npm i node-ssh archiver rimraf -D 主要配置文件： deploy/config.xx.js（多环境服务器配置） deploy/index.js（自动化部署逻辑）执行命令：npm run deploy:xxx，自动完成「打包→压缩→上传→解压」全流程服务器准备：确保服务器安装了 unzip 命令（用于解压，若未安装执行 yum install unzip -y（CentOS）或 apt install unzip -y（Ubuntu））；服务器部署目录需有读写权限（建议用 root 或赋予对应账号权限）；打包匹配：脚本中默认 test 环境执行 npm run build:test，其他环境执行 npm run build，若 xj/mj 需单独打包，可在 buildProject 函数中新增判断；日志输出：脚本使用 stdio: “inherit” 让打包、解压的日志直接输出到控制台，方便排查问题；错误处理：任意步骤失败都会终止脚本，并输出红色错误信息，同时清理临时文件、断开 SSH 连接，避免资源残留。

七、总结

核心依赖为 node-ssh（SSH 连接）和 archiver（压缩），需先执行 npm i node-ssh archiver rimraf -D 安装；核心文件是 deploy/config.js（多环境服务器配置）和 deploy/index.js（自动化部署逻辑），无需修改原有 package.json；部署命令直接用你原有配置的 npm run deploy:xxx，全程自动化完成「打包→压缩→上传→解压」，无需手动操作服务器；

掘金前端
从 Nuxt 架构到 GSC 治理：全栈工程师的 SEO 性能调优实战一拳不是超人
2026年2月12日 10:49

从 Nuxt 架构到 GSC 治理：全栈工程师的 SEO 性能调优实战

掘金前端

作者一拳不是超人

2026年2月12日 10:49

什么是 SEO？

SEO (Search Engine Optimization) ，即搜索引擎优化。从技术角度看，它是一场**“翻译”工程**：我们将复杂的业务内容，翻译成搜索引擎（Google, Bing, Baidu）能够高效抓取、精准理解并愿意优先推荐给用户的结构化数据。

SEO 的核心目标是提升网站在自然搜索结果中的排名 (Ranking) ，从而获取高质量的免费流量。

技术 SEO：构建搜索引擎友好的架构

1. 渲染模式的权衡

渲染方案决定了爬虫第一眼看到的是“白屏”还是“内容”。

CSR (Client-Side Rendering) ：爬虫需运行 JS 才能看到内容，对部分低级爬虫不友好，索引慢。
SSR (Server-Side Rendering) ：如 Nuxt.js/Next.js，服务端直接返回 HTML，索引效率最高。
SSG (Static Site Generation) ：预渲染静态 HTML，加载速度极致，是文档和博客的首选。

2. TDK 与语义化标签

代码的语义化是 SEO 的骨架。

<header>
  <nav></nav>
</header>
<main>
  <article>
    <h1>核心关键词：如何学习 SEO</h1> <section>
      <h2>技术 SEO 基础</h2>
      <p>内容段落...</p>
    </section>
  </article>
</main>

3. 多语言 SEO：Hreflang 策略

如果你的站点面向全球，必须告诉 Google 页面之间的语言对应关系，防止被判定为“重复内容”。

Nuxt 3 代码示例：

// 在 nuxt.config.ts 或页面组件中使用
useHead({
  link: [
    { rel: 'alternate', hreflang: 'en', href: 'https://example.com/en' },
    { rel: 'alternate', hreflang: 'zh-CN', href: 'https://example.com/zh' },
    { rel: 'alternate', hreflang: 'x-default', href: 'https://example.com/' }
  ]
})

结构化数据与爬虫指令

1. 结构化数据 (JSON-LD)

通过 application/ld+json 告诉 Google 你的页面是一个产品、一篇博客还是一个 FAQ。

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "2026 SEO 优化实战",
  "image": ["https://example.com/photos/1x1/photo.jpg"],
  "author": { "@type": "Person", "name": "Gemini" },
  "publisher": { "@type": "Organization", "name": "TechBlog" },
  "datePublished": "2026-02-12"
}
</script>

2. Robots.txt 与 Sitemap

Sitemap (站点地图) ：建议使用 @nuxtjs/sitemap 模块动态生成。

Robots.txt：明确“禁止区”。

User-agent: *
Disallow: /admin/
Disallow: /api/
Sitemap: https://example.com/sitemap.xml

性能优化：为 Core Web Vitals 而战

性能是 Google 的核心排名因素。我们需要关注 LCP（最大内容绘制）、FID（首次输入延迟）和 CLS（累积布局偏移）。

1. 图片优化实战

在 Nuxt 中，通过 @nuxt/image 自动化处理：

<NuxtImg
  src="/images/seo-guide.png"
  alt="SEO实战指南图解"
  width="800"
  height="400"
  loading="lazy"
  format="webp"
  placeholder
/>

2. Nuxt 打包优化

Tree Shaking：清理未使用的依赖。
Route Rules：对非 SEO 敏感页面（如个人中心）直接开启 ssr: false。
组件异步导入：使用 defineAsyncComponent 减少主包体积。

站点治理：冗杂页面的处理艺术

方案 1：有承接页 (A -> C) —— 权重平滑转移

301 跳转：服务器端配置永久重定向。
内链清理：全站搜索并替换旧链接，保持内链指向的一致性。
状态监控：在 GSC 观察权重转移，无需手动申请移除。

方案 2：纯移除 (无承接页) —— 快速清理索引

410 Gone：返回 410 状态码。410 的信号强度远高于 404，能缩短搜索引擎“反复确认”的时间。
清理 Sitemap：确保地图中不再包含已删除的 URL。
内链删除：防止用户在站内点击到死链，造成跳出率上升。

数据驱动：SEO 分析工具链

Google Search Console (GSC) ：
- 覆盖率报告：查看哪些页面被索引，哪些被排除。
- 排名趋势：追踪特定关键词的排名变化。
Google Analytics 4 (GA4) ：
- 追踪自然搜索流量的转化率。
- 分析页面跳出率，识别内容质量问题。

结语

SEO 是一场关于“信任”的持久战。从代码底层的渲染架构，到页面层面的语义化标签，再到站点级的链接治理，每一个细节都在向搜索引擎证明：你的内容值得排在第一页。

Tailwind CSS 4.0 完整指南：从入门到精通

掘金前端

作者 _Eleven

2026年2月12日 10:38

Tailwind CSS 4.0 完整指南：从入门到精通

一、引言

Tailwind CSS 是当今最受欢迎的原子化 CSS 框架之一，它彻底改变了前端开发者编写样式的方式。2024 年，Tailwind Labs 发布了 Tailwind CSS 4.0，这是一个里程碑式的重大版本更新。Tailwind CSS 4.0 代表了框架从 JavaScript 配置向纯 CSS 配置的重大转变，同时带来了显著的性能提升和更现代化的开发体验。

Tailwind CSS 4.0 的设计目标是支持 Safari 16.4+、Chrome 111+ 和 Firefox 128+ 等现代浏览器。这意味着框架充分利用了最新的 CSS 特性，如 @property 和 color-mix() 函数，从而实现更强大和更高效的功能。Tailwind CSS 4.0 不仅仅是一次简单的版本迭代，更是对整个 CSS 开发范式的重新思考和革新。

在过去的几年中，CSS 语言本身发生了巨大的变化。原生 CSS 变量（自定义属性）、强大的容器查询、现代颜色函数等新特性的出现，使得许多原本需要 JavaScript 辅助的功能现在可以直接在 CSS 中实现。Tailwind CSS 4.0 正是抓住了这一机遇，将框架与现代 CSS 标准深度融合，为开发者提供了一种更加自然、更加高效的样式编写方式。

Tailwind CSS 4.0 的核心改进包括：完全重写的引擎架构、简化的配置方式、显著的性能提升、增强的开发者体验，以及对现代 CSS 特性的全面支持。这些改进使得 Tailwind CSS 4.0 不仅保持了其原有的优势，还解决了许多长期困扰开发者的问题。无论你是 Tailwind CSS 的老用户，还是刚刚接触这个框架的新手，Tailwind CSS 4.0 都将为你带来前所未有的开发体验。

二、新特性概览

2.1 CSS 优先配置

Tailwind CSS 4.0 引入了一种全新的配置方式——CSS 优先配置。在之前的版本中，开发者通常需要在一个 JavaScript 文件（通常是 tailwind.config.js）中定义主题、颜色、间距等配置。这种方式虽然灵活，但也带来了额外的构建复杂性和学习成本。Tailwind CSS 4.0 完全改变了这一范式，允许开发者直接在 CSS 文件中使用原生 CSS 变量和 @theme 指令来定义和定制主题。

这种 CSS 优先的配置方式带来了诸多好处。首先，它消除了对额外配置文件的需求，让样式定义更加集中和直观。其次，它利用了浏览器原生支持的 CSS 变量，使得主题值可以在运行时动态调整，无需重新编译。此外，这种方式与现代 CSS 工作流更加契合，开发者可以使用任何他们熟悉的 CSS 预处理工具或原生 CSS 编写方式。

在 Tailwind CSS 4.0 中，你可以通过以下方式定义主题：

@import "tailwindcss";

@theme {
  --font-display: "Satoshi", "sans-serif";
  --color-brand-50: #f0f9ff;
  --color-brand-100: #e0f2fe;
  --color-brand-200: #bae6fd;
  --color-brand-500: #0ea5e9;
  --color-brand-600: #0284c7;
  --color-brand-700: #0369a1;
  --breakpoint-3xl: 120rem;
  --spacing-128: 32rem;
}

这种配置方式不仅简洁明了，而且完全兼容原生 CSS 的任何功能。你可以自由地使用 CSS 变量计算、媒体查询、容器查询等所有现代 CSS 特性来定义你的主题。Tailwind CSS 4.0 会自动扫描你的 CSS 文件，识别 @theme 块中定义的变量，并生成相应的工具类。这种声明式的配置方式使得主题定义变得更加声明式和可维护。

2.2 性能优化

Tailwind CSS 4.0 在性能方面实现了质的飞跃。根据官方基准测试，新版本在编译速度上比 v3 快约 25 倍，在开发服务器启动时间上快约 5 倍。这一显著的性能提升主要得益于全新的引擎架构和对现代浏览器特性的充分利用。

新引擎采用了增量编译策略，只处理发生变化的文件和类名，而不是每次都重新扫描整个项目。这意味着当你修改一个组件的样式时，Tailwind CSS 4.0 只需要更新相关的 CSS 输出，而不需要重新生成整个样式表。对于大型项目来说，这种优化可以节省大量的开发时间。

Tailwind CSS 4.0 还引入了一种全新的类名检测机制，使用 Rust 编写的高性能扫描器可以更快速地分析 HTML 模板和 JavaScript 文件，识别出实际使用的工具类。这种机制不仅提高了编译速度，还减少了最终生成的 CSS 文件大小，因为它可以更精确地确定哪些工具类真正被项目使用。

在生产构建方面，Tailwind CSS 4.0 使用了更高效的 CSS 生成算法，生成的 CSS 文件通常比 v3 版本小 10% 到 20%。这是因为新引擎可以更好地识别和消除未使用的样式，同时利用现代 CSS 特性的组合能力来减少重复代码。此外，新版本还支持 CSS 变量的智能内联，可以在保持开发体验的同时优化生产构建的体积。

2.3 现代浏览器支持

Tailwind CSS 4.0 专为现代浏览器设计，充分利用了 CSS 的最新特性。这种设计决策使得框架可以摆脱对旧版浏览器的兼容负担，从而提供更强大、更简洁的功能集。以下是 Tailwind CSS 4.0 所依赖的主要现代 CSS 特性。

@property 是 CSS Houdini API 的一部分，它允许开发者定义自定义属性的类型、继承行为和默认值。Tailwind CSS 4.0 使用 @property 来注册颜色、间距、字体大小等工具类对应的 CSS 变量，这使得这些变量可以支持过渡动画、计算颜色等高级功能。

color-mix() 函数是 CSS Color Level 4 规范中引入的一个强大功能，它允许在运行时混合两种颜色。Tailwind CSS 4.0 使用 color-mix() 来实现透明度修饰符（如 bg-red-500/50），这比之前的实现方式更加简洁和高效。

容器查询（Container Queries）是响应式设计的一个重要补充，它允许元素根据其父容器的尺寸而不是视口尺寸来调整样式。Tailwind CSS 4.0 完全支持容器查询，并提供了一组新的 @ 工具类来配合 @container 使用。

三、安装与配置

3.1 使用 Vite 安装

对于现代前端项目，Vite 是一个优秀的构建工具选择。Tailwind CSS 4.0 提供了官方的 Vite 插件，可以实现无缝集成和最佳的开发体验。以下是使用 Vite 和 Tailwind CSS 4.0 搭建项目的完整步骤。

首先，确保你的 Node.js 版本不低于 20。然后创建一个新的 Vite 项目：

npm create vite@latest my-project -- --template vue-ts
cd my-project

接下来，安装 Tailwind CSS 4.0 和相关的 Vite 插件：

npm install tailwindcss @tailwindcss/vite

然后，在你的 vite.config.ts 文件中配置 Tailwind CSS：

import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [vue(), tailwindcss()],
});

最后，在你的主 CSS 文件（通常是 src/style.css 或 src/main.css）中引入 Tailwind CSS：

@import "tailwindcss";

这样，你就完成了 Tailwind CSS 4.0 的基本配置。现在你可以开始在项目中使用 Tailwind 的所有工具类了。Vite 会自动处理 Tailwind CSS 的编译和优化，你只需要专注于编写代码即可。

3.2 使用 PostCSS 安装

如果你的项目使用的是其他构建工具或者自定义的 PostCSS 配置，你仍然可以使用 Tailwind CSS 4.0。Tailwind CSS 4.0 提供了一个官方的 PostCSS 插件，可以轻松集成到现有的工作流中。

首先，安装 Tailwind CSS 4.0 和 PostCSS 插件：

npm install tailwindcss @tailwindcss/postcss

然后，在你的 postcss.config.js 或 postcss.config.mjs 文件中配置插件：

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

在你的 CSS 文件中引入 Tailwind CSS：

@import "tailwindcss";

值得注意的是，在 Tailwind CSS 4.0 中，你不再需要 postcss-import、autoprefixer 或 tailwindcss（旧版插件）。@tailwindcss/postcss 插件已经内置了这些功能，可以自动处理 CSS 导入和浏览器前缀添加。这大大简化了 PostCSS 配置，减少了依赖项数量。

3.3 使用 Tailwind CLI

对于简单的项目或者不想使用完整构建工具的场景，你可以直接使用 Tailwind CSS 4.0 提供的命令行工具。Tailwind CSS CLI 是一个独立的可执行文件，可以快速地将 Tailwind CSS 编译成普通的 CSS 文件。

首先，安装 CLI 工具：

npm install -D @tailwindcss/cli

然后，你可以使用 CLI 工具来编译 CSS：

npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css

你也可以创建一个 package.json 脚本来简化这个过程：

{
  "scripts": {
    "build:css": "@tailwindcss/cli -i ./src/input.css -o ./dist/output.css",
    "dev:css": "@tailwindcss/cli -i ./src/input.css -o ./dist/output.css --watch"
  }
}

Tailwind CSS CLI 还支持配置文件。如果你需要自定义主题，可以在 CSS 文件中使用 @theme 指令，或者使用 --config 参数指定一个单独的配置文件。

四、核心概念与用法

4.1 工具类基础

Tailwind CSS 的核心思想是提供大量的、细粒度的工具类，让开发者可以直接在 HTML 中组合使用这些类来构建界面。这种原子化的方法与传统 CSS 方法（如 BEM）形成了鲜明对比，后者通常需要为每个组件编写大量的自定义 CSS。

Tailwind CSS 4.0 提供了以下主要类别的工具类：

布局类：控制元素的显示模式、位置、尺寸、对齐方式等。包括 flex、grid、absolute、relative、fixed、sticky、z-index、top、right、bottom、left 等。

间距类：控制元素的内边距和外边距。格式为 <属性><方向>-<尺寸>，如 p-4（所有方向的内边距）、mt-2（上边距）、mx-auto（水平方向自动边距）、gap-3（网格间隙）等。

尺寸类：控制元素的宽度和高度。包括 w-*、h-*、min-w-*、max-w-*、min-h-*、max-h-* 等，如 w-full、h-screen、max-w-4xl 等。

颜色类：控制文本颜色、背景颜色、边框颜色等。包括 text-*、bg-*、border-*、decoration-*、accent-* 等，支持通过斜杠语法添加透明度，如 bg-red-500/50、text-black/75 等。

排版类：控制文本的各种属性。包括 font-*、text-*、leading-*、tracking-*、whitespace-*、break-* 等，如 font-bold、text-lg、leading-relaxed、tracking-wide 等。

边框类：控制边框的宽度、颜色、样式和圆角。包括 border-*、rounded-*、divide-* 等，如 border-2、rounded-lg、divide-y 等。

效果类：控制阴影、透明度、混合模式、滤镜等。包括 shadow-*、opacity-*、mix-blend-*、blur-*、brightness-* 等。

动画类：控制过渡效果和动画。包括 transition-*、animate-* 等，如 transition-all、animate-spin、animate-pulse 等。

4.2 响应式设计

Tailwind CSS 4.0 提供了完整的响应式设计支持，允许你根据不同的视口宽度应用不同的样式。响应式工具类使用前缀 sm:、md:、lg:、xl:、2xl: 来分别对应不同的断点。

默认的断点配置如下：

前缀	最小宽度	典型设备
`sm`	640px	小型平板手机
`md`	768px	大型平板手机
`lg`	1024px	笔记本电脑
`xl`	1280px	台式电脑
`2xl`	1536px	大型台式电脑

使用响应式工具类时，样式只会在满足条件时生效。例如：

<div class="text-sm md:text-base lg:text-lg xl:text-xl">
  这个文本在不同屏幕尺寸下会有不同的大小
</div>

在默认情况下（移动端），文本大小为 text-sm（0.875rem）。当视口宽度达到 768px 或更大时，文本大小变为 text-base（1rem）。依此类推，直到 xl 断点时变为 text-xl（1.25rem）。

Tailwind CSS 4.0 还支持自定义断点。你可以在 @theme 块中定义自己的断点：

@theme {
  --breakpoint-3xl: 120rem;
}

然后你就可以使用 3xl: 前缀来针对超大型屏幕应用样式。

Tailwind CSS 4.0 的响应式工具类遵循移动优先的设计原则。这意味着你定义的默认样式会应用于所有屏幕尺寸，而带有断点前缀的样式会作为增强，在更大的屏幕上生效。这种方法符合现代网页设计最佳实践，确保你的网站在移动设备上也能良好显示。

4.3 状态变体

状态变体允许你根据元素的不同状态应用不同的样式。Tailwind CSS 4.0 支持丰富的状态变体，包括交互状态、表单状态、媒体状态等。

交互状态：

hover: - 鼠标悬停状态
focus: - 获得焦点状态
active: - 激活状态（如按钮被按下）
visited: - 已访问链接状态

<button class="bg-blue-500 hover:bg-blue-600 focus:ring-2 focus:ring-blue-300">
  点击我
</button>

表单状态：

disabled: - 禁用状态
required: - 必填状态
checked: - 选中状态（复选框、单选框）
invalid: - 无效状态

<input 
  type="email" 
  class="border-gray-300 focus:border-blue-500 focus:ring-blue-500 disabled:bg-gray-100"
  required
/>

其他状态：

first: - 第一个子元素
last: - 最后一个子元素
odd: - 奇数子元素
even: - 偶数子元素
empty: - 空内容元素
in-range: - 输入值在范围内
out-of-range: - 输入值超出范围

<ul class="divide-y">
  <li class="py-2 first:pt-0 last:pb-0 odd:bg-gray-50 even:bg-white">
    项目 1
  </li>
  <li class="py-2 first:pt-0 last:pb-0 odd:bg-gray-50 even:bg-white">
    项目 2
  </li>
</ul>

4.4 暗色模式

Tailwind CSS 4.0 提供了便捷的暗色模式支持。使用 dark: 前缀可以定义在暗色模式下生效的样式：

<div class="bg-white text-gray-900 dark:bg-gray-900 dark:text-white">
  白天和夜晚显示不同的颜色
</div>

Tailwind CSS 4.0 使用 media 策略来检测暗色模式偏好（默认行为），这意味着暗色模式会根据操作系统的设置自动切换。如果你希望提供手动控制的能力，可以切换到 selector 策略：

@theme {
  --color-dark-bg: #1a1a1a;
}

.dark {
  color-scheme: dark;
}

然后在 HTML 中添加 class="dark" 到 html 或 body 元素来启用暗色模式。

五、主题定制

5.1 使用 @theme 指令

Tailwind CSS 4.0 引入了一个全新的主题定制方式——@theme 指令。这种方式允许你直接在 CSS 文件中定义和定制主题，完全摆脱了对 JavaScript 配置文件的依赖。

@theme 指令可以定义以下类型的变量：

颜色变量：使用 --color-<name> 格式定义颜色。

@theme {
  --color-primary-50: #f0f9ff;
  --color-primary-100: #e0f2fe;
  --color-primary-200: #bae6fd;
  --color-primary-300: #7dd3fc;
  --color-primary-400: #38bdf8;
  --color-primary-500: #0ea5e9;
  --color-primary-600: #0284c7;
  --color-primary-700: #0369a1;
  --color-primary-800: #075985;
  --color-primary-900: #0c4a6e;
}

间距变量：使用 --spacing-<name> 格式定义间距。

@theme {
  --spacing-18: 4.5rem;
  --spacing-22: 5.5rem;
  --spacing-30: 7.5rem;
}

字体大小变量：使用 --font-size-<name> 格式定义字体大小。

@theme {
  --font-size-display: clamp(2.5rem, 5vw, 5rem);
  --font-size-h1: clamp(2rem, 4vw, 3.75rem);
  --font-size-h2: clamp(1.5rem, 3vw, 2.5rem);
}

圆角变量：使用 --radius-<name> 格式定义圆角大小。

@theme {
  --radius-xl: 1rem;
  --radius-2xl: 1.5rem;
  --radius-3xl: 2rem;
}

断点变量：使用 --breakpoint-<name> 格式定义响应式断点。

@theme {
  --breakpoint-3xl: 120rem;
  --breakpoint-4xl: 160rem;
}

动画变量：使用 --animate-<name> 格式定义动画。

@theme {
  --animate-bounce-slow: bounce 2s infinite;
  --animate-fade-in: fadeIn 0.5s ease-out;
  --animate-slide-up: slideUp 0.3s ease-out;
}

Tailwind CSS 4.0 会自动将 @theme 中定义的变量转换为相应的工具类。例如，定义 --color-primary-500 后，你就可以使用 bg-primary-500、text-primary-500 等工具类。

5.2 扩展默认主题

除了完全重写主题，你还可以扩展 Tailwind CSS 的默认主题。这种方式保留了所有预设的工具类，同时添加你自己的自定义工具类。

@theme {
  --color-avocado-100: oklch(0.99 0 0);
  --color-avocado-200: oklch(0.98 0.04 113.22);
  --color-avocado-300: oklch(0.94 0.11 115.03);
  --color-avocado-400: oklch(0.92 0.15 117.08);
  --color-avocado-500: oklch(0.87 0.18 118.82);
  
  --font-display: "Satoshi", "sans-serif";
  --font-body: "Inter", "sans-serif";
}

扩展默认主题的好处是你可以渐进式地添加自定义样式，而不需要一次性替换所有内容。这对于维护大型项目或与团队协作时特别有用。

5.3 使用 CSS 变量

Tailwind CSS 4.0 完全支持 CSS 变量，你可以在任何地方使用 CSS 变量来定义主题值：

@theme {
  --color-brand: var(--brand-color);
  --spacing-container: var(--container-padding);
  --font-size-base: var(--base-size, 1rem);
}

CSS 变量的一个强大特性是支持回退值。如果某个变量未定义，可以使用第二个参数作为默认值：

font-size: var(--font-size-xl, 1.25rem);

你还可以使用 calc() 函数与 CSS 变量结合：

@theme {
  --spacing-128: calc(var(--spacing-32) * 4);
}

Tailwind CSS 4.0 会自动识别并处理这些变量用法，确保生成的工具类正确引用这些 CSS 变量。

六、从 v3 升级指南

6.1 主要变更概览

Tailwind CSS 4.0 虽然带来了许多改进，但也包含了一些不兼容的变更。对于从 v3 升级的项目，了解这些变更是成功迁移的关键。以下是 v3 到 v4 的主要变更概览。

移除的 @tailwind 指令：v4 使用标准的 @import "tailwindcss" 替代了 @tailwind base、@tailwind components 和 @tailwind utilities 指令。

移除的废弃工具类：v4 移除了所有在 v3 中已废弃的工具类，包括 bg-opacity-*、text-opacity-*、border-opacity-*、flex-shrink-*、flex-grow-* 等。这些应该使用透明度修饰符替代，如 bg-red-500/50。

重命名的工具类：多个工具类被重命名以保持一致性和可预测性，如 shadow-sm 改为 shadow-xs、rounded-sm 改为 rounded-xs、blur-sm 改为 blur-xs 等。

引入的重要修饰符语法变更：v4 中重要修饰符 ! 应该放在类名的最后，如 class="flex! bg-red-500!" 而不再是 class="!flex bg-red-500"。

变更的选择器：space-x-*、space-y-*、divide-x-* 和 divide-y-* 的选择器从 > :not([hidden]) ~ :not([hidden]) 改为 > :not(:last-child)，这解决了大型页面的性能问题。

6.2 使用升级工具

Tailwind Labs 提供了一个官方升级工具，可以自动处理大部分迁移工作。这个工具可以更新依赖项、迁移配置文件、修改模板文件等，大大简化了升级过程。

使用升级工具非常简单，只需在项目根目录运行以下命令：

npx @tailwindcss/upgrade

运行该命令前，请确保：

Node.js 版本不低于 20
项目已经初始化了 Git（建议在新的分支上运行）
所有依赖项已经安装

升级工具会执行以下操作：

更新 package.json 中的 Tailwind CSS 相关依赖
将 tailwind.config.js 转换为 CSS 配置
更新 CSS 文件中的 @tailwind 指令
修改模板文件中的废弃用法

升级完成后，你需要：

仔细检查工具生成的 diff
在浏览器中测试项目
手动修复任何工具未处理的问题

6.3 手动升级步骤

如果升级工具无法满足你的需求，或者你更喜欢手动控制升级过程，可以按照以下步骤进行手动升级。

第一步：更新依赖

npm uninstall tailwindcss postcss autoprefixer
npm install tailwindcss @tailwindcss/postcss

第二步：更新 CSS 文件

将：

@tailwind base;
@tailwind components;
@tailwind utilities;

改为：

@import "tailwindcss";

第三步：迁移配置文件

将 tailwind.config.js 中的配置迁移到 CSS 文件的 @theme 块中。例如：

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#f0f9ff',
          500: '#0ea5e9',
        },
      },
      fontFamily: {
        display: ['Satoshi', 'sans-serif'],
      },
    },
  },
};

迁移为：

@theme {
  --color-brand-50: #f0f9ff;
  --color-brand-500: #0ea5e9;
  --font-display: "Satoshi", "sans-serif";
}

第四步：更新工具类使用

根据前面提到的变更列表，更新项目中使用的工具类。

第五步：测试和验证

运行项目，确保所有样式正确显示。注意检查：

响应式断点是否正常工作
状态变体是否正确应用
自定义主题是否正确应用
暗色模式是否正常切换

6.4 常见问题与解决方案

问题一：升级后样式丢失

这通常是因为 @theme 配置不正确或 CSS 导入路径错误。检查 @theme 块中的变量名是否正确，确保所有自定义颜色、间距等都有对应的变量定义。

问题二：PostCSS 配置错误

如果你使用的是自定义 PostCSS 配置，确保只使用 @tailwindcss/postcss 插件，移除 tailwindcss（旧版插件）和 autoprefixer。新插件已经内置了这些功能。

问题三：JavaScript 配置文件不生效

在 v4 中，JavaScript 配置文件不再是自动检测的。如果你仍然需要使用 tailwind.config.js，必须在 CSS 文件中显式引用它：

@config "../../tailwind.config.js";

问题四：工具类不工作

Tailwind CSS 4.0 需要扫描你的 HTML 模板和 JavaScript 文件来检测使用的工具类。确保你的构建配置包含了正确的扫描路径。大多数情况下，默认配置应该能正常工作，但如果你有特殊的目录结构，可能需要手动配置扫描路径。

七、高级功能

7.1 自定义工具类

Tailwind CSS 4.0 提供了 @utility 指令，允许你创建完全自定义的工具类。这对于添加 Tailwind CSS 没有内置的功能特别有用。

创建自定义工具类：

@utility scrollbar-hide {
  -ms-overflow-style: none;
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}

@utility text-balance {
  text-wrap: balance;
}

@utility truncate-2-lines {
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

使用自定义工具类：

<div class="scrollbar-hide text-balance">
  这是一个长文本段落
</div>

Tailwind CSS 4.0 的自定义工具类会自动获得完整的变体支持：

<button class="hover:truncate-2-lines">
  悬停时截断文本
</button>

7.2 自定义变体

Tailwind CSS 4.0 允许你使用 @custom-variant 指令创建自己的变体。这在处理复杂的交互逻辑时特别有用。

@custom-variant group-hover (&:where(:has(.group:hover)));

@custom-variant disabled (&:where(:disabled, [disabled]));

使用自定义变体：

<div class="group">
  <button class="group-hover:bg-blue-500">
    悬停父元素时改变样式
  </button>
</div>

<input type="text" class="disabled:opacity-50" disabled />

你还可以基于媒体查询或功能查询创建变体：

@custom-variant landscape (@media (orientation: landscape));

@custom-variant reduced-motion (@media (prefers-reduced-motion: reduce));

7.3 容器查询

Tailwind CSS 4.0 完全支持 CSS 容器查询，这是一种强大的响应式设计技术，允许组件根据其容器尺寸而不是视口尺寸来调整样式。

首先，需要将元素标记为容器：

<div class="@container">
  <div class="bg-white p-4 @lg:bg-blue-100 @xl:bg-blue-200">
    根据容器尺寸改变背景
  </div>
</div>

容器查询断点使用 @ 前缀，这与普通的响应式断点（使用 : 前缀）形成对比：

<div class="@container">
  <div class="text-sm @md:text-base @lg:text-lg">
    在容器宽度达到 md 断点时增大文本
  </div>
</div>

容器查询特别适用于创建可复用的组件库，这些组件可以在不同的上下文中正常工作，无论它们被放置在多大的容器中。

7.4 颜色函数

Tailwind CSS 4.0 充分利用了现代 CSS 颜色函数，特别是 color-mix() 函数，这使得颜色操作变得更加灵活和强大。

使用 color-mix() 直接在 CSS 中混合颜色：

@theme {
  --color-mixed: color-mix(in oklch, var(--color-blue-500), var(--color-red-500) 50%);
}

使用 CSS 变量与 Tailwind 颜色混合：

<div class="bg-[color-mix(in_oklch,var(--color-blue-500),var(--color-red-500)30%)]">
  使用颜色混合的背景
</div>

Tailwind CSS 4.0 的透明度修饰符实际上是建立在 color-mix() 基础上的：

<div class="bg-red-500/50">
  相当于 bg-red-500 添加 50% 透明度
</div>

7.5 过渡和动画增强

Tailwind CSS 4.0 提供了更强大的过渡和动画支持，允许你创建更加流畅和复杂的交互效果。

动画关键帧：

@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

@keyframes slide-up {
  from { transform: translateY(10px); opacity: 0; }
  to { transform: translateY(0); opacity: 1; }
}

@theme {
  --animate-fade-in: fade-in 0.5s ease-out;
  --animate-slide-up: slide-up 0.3s ease-out;
  --animate-slide-down: slide-down 0.3s ease-out;
}

使用动画：

<div class="animate-fade-in animate-slide-up">
  元素将同时应用淡入和上滑动画
</div>

过渡增强：

<button class="transition-all duration-300 ease-in-out hover:scale-105 active:scale-95">
  带有平滑过渡效果的按钮
</button>

Tailwind CSS 4.0 还支持自定义过渡属性：

@theme {
  --transition-all-properties: all;
  --transition-colors-properties: background-color, border-color, color, fill, stroke;
  --transition-opacity-properties: opacity;
  --transition-shadow-properties: box-shadow;
  --transition-transform-properties: transform;
}

八、最佳实践

8.1 项目结构组织

良好的项目结构是维护大型 Tailwind CSS 项目的基础。以下是推荐的项目组织方式：

CSS 文件结构：

/* src/styles/main.css */
@import "tailwindcss";

/* 主题变量定义 */
@theme {
  --color-brand-500: #0ea5e9;
  --font-display: "Satoshi", "sans-serif";
}

/* 自定义工具类 */
@utility scrollbar-hide { ... }

/* 自定义变体 */
@custom-variant hocus (&:hover, &:focus) { ... }

组件级样式：

对于需要特定样式的组件，可以在组件文件中使用 @apply：

<!-- Button.vue -->
<template>
  <button class="btn-primary">
    <slot />
  </button>
</template>

<style>
@reference "../../styles/main.css";

.btn-primary {
  @apply bg-blue-500 text-white px-4 py-2 rounded-lg 
         hover:bg-blue-600 active:bg-blue-700 
         transition-colors duration-200;
}
</style>

8.2 性能优化技巧

Tailwind CSS 4.0 本身已经非常高效，但遵循以下最佳实践可以让你的项目更加快速：

合理使用 JIT 模式：Tailwind CSS 4.0 默认使用即时编译，只生成实际使用的工具类。避免在 HTML 中写太多永远不会用到的工具类。

使用 @utility 而不是 CSS 类：自定义工具类会自动获得 Tailwind CSS 的优化和缓存机制。

利用 CSS 变量：对于需要动态改变的值，使用 CSS 变量而不是多个工具类：

<!-- 不推荐 -->
<div class="bg-red-500 md:bg-blue-500 lg:bg-green-500">

<!-- 推荐 -->
<div class="bg-[var(--theme-color)]">

压缩和清理：在生产构建时，确保 CSS 被正确压缩和清理。Tailwind CSS 4.0 的 CLI 和 Vite 插件会自动处理这些。

8.3 与设计系统集成

Tailwind CSS 4.0 非常适合构建和管理设计系统。以下是一些集成建议：

定义设计令牌：将设计系统中的颜色、字体、间距等定义为 CSS 变量：

@theme {
  /* 颜色令牌 */
  --color-primary-50: var(--ds-color-primary-50);
  --color-primary-500: var(--ds-color-primary-500);
  --color-primary-900: var(--ds-color-primary-900);
  
  /* 字体令牌 */
  --font-heading: var(--ds-font-heading);
  --font-body: var(--ds-font-body);
  
  /* 间距令牌 */
  --spacing-layout: var(--ds-spacing-layout);
}

组件库构建：使用 Tailwind CSS 构建组件库时，利用 @layer 和 @utility 来组织样式：

@layer components {
  .card {
    @apply bg-white rounded-xl shadow-lg p-6;
  }
  
  .card-header {
    @apply text-xl font-bold mb-4;
  }
}

与设计工具同步：使用工具将 Figma 或 Sketch 中的设计令牌导出为 Tailwind CSS 配置文件，保持设计和代码的一致性。

8.4 团队协作建议

在团队环境中使用 Tailwind CSS 4.0 时，以下实践可以提高协作效率：

建立组件库：创建团队共享的组件库，确保 UI 的一致性。使用 Storybook 或类似的工具来文档化组件。

编码规范：制定团队内部的 Tailwind CSS 编码规范，包括类名顺序、命名约定等。可以使用 ESLint 插件来强制执行这些规范。

代码审查：在代码审查时特别关注样式的使用，确保没有冗余或不必要的工具类。

文档化：为团队创建 Tailwind CSS 使用指南，包括常用的工具类组合、自定义主题的使用方法等。

九、常见问题解答

问题一：Tailwind CSS 4.0 与 v3 有什么主要区别？

Tailwind CSS 4.0 的主要区别包括：CSS 优先配置替代 JavaScript 配置文件、显著的性能提升、移除废弃工具类、新的 @theme 和 @utility 指令，以及对现代 CSS 特性的全面支持。

问题二：是否必须升级到 Tailwind CSS 4.0？

不是强制的，但建议升级。Tailwind CSS 4.0 提供了更好的开发体验和性能改进。v3 仍然会得到安全更新，但新功能只会添加到 v4。

问题三：升级后原来的 tailwind.config.js 还能用吗？

可以，但需要显式引用。升级工具会自动将配置迁移到 CSS 文件。如果你想保留 JS 配置文件，可以使用 @config 指令引用它。

问题四：Tailwind CSS 4.0 是否支持旧版浏览器？

不支持。Tailwind CSS 4.0 专为现代浏览器设计，需要 Safari 16.4+、Chrome 111+ 或 Firefox 128+。如果需要支持旧版浏览器，请继续使用 v3.4。

问题五：如何处理透明度修饰符和 opacity- 工具类的区别？*

在 v4 中，应该使用透明度修饰符（如 bg-red-500/50）替代已移除的 bg-opacity-* 工具类。透明度修饰符更简洁、更灵活，支持任意颜色和透明度值的组合。

问题六：Tailwind CSS 4.0 如何处理暗色模式？

v4 使用 color-scheme: dark 来控制暗色模式，而不是之前的 media 策略。你可以继续使用 dark: 前缀来定义暗色模式下的样式。

问题七：如何使用 Sass、Less 或 Stylus 与 Tailwind CSS 4.0？

Tailwind CSS 4.0 官方不支持与 Sass、Less 或 Stylus 等 CSS 预处理器一起使用。这是因为 v4 本身就是基于现代 CSS 的构建工具，不需要额外的预处理步骤。建议直接使用原生 CSS 或 PostCSS 插件。

十、总结与展望

Tailwind CSS 4.0 代表了原子化 CSS 框架的一个重要进化。通过转向 CSS 优先的配置方式、利用现代 CSS 特性，以及显著的性能优化，Tailwind CSS 4.0 为前端开发者提供了一个更加强大、更加高效的工具。

这个版本的核心优势包括：

简化的配置：直接使用 CSS 定义主题，减少了配置文件和构建复杂性。
显著的性能提升：编译速度提高 25 倍，启动时间加快 5 倍。
更好的开发者体验：即时的反馈、更快的热更新、更清晰的错误信息。
现代 CSS 集成：充分利用 @property、color-mix()、容器查询等现代 CSS 特性。
更小的生产包体积：优化的 CSS 生成算法减少了最终产物的体积。

展望未来，Tailwind CSS 团队将继续致力于改进框架的性能和功能。随着 CSS 标准的不断发展，Tailwind CSS 将继续整合新的特性，为开发者提供最前沿的工具。我们鼓励所有开发者尝试 Tailwind CSS 4.0，体验它带来的改进，并在官方文档和社区中获取更多资源。

无论是新项目还是现有项目的升级，Tailwind CSS 4.0 都是一个值得考虑的选择。它不仅解决了许多长期存在的问题，还为 CSS 开发设定了新的标准。现在就开始你的 Tailwind CSS 4.0 之旅吧！

ArkTs版图库预览

掘金前端

作者胖子不胖

2026年2月11日 17:59

本文基于鸿蒙系统，用600行代码实现类似图库预览效果

新建MediaDialogUtil.ets工具类，然后在工程下import 导入使用即可

import {MediaParams, MediaDialogUtil} from ./MediaDialogUtil.ets


build() {
    Stack() {
      Text('点击打开弹窗')
        .border({
          width: 10,
          color: '#000000'
        })
        .onClick(() => {
          const data: MediaParams[] = [
            new MediaParams('https://img1.baidu.com/it/u=3858873910,2096255234&fm=253&fmt=auto&app=138&f=JPEG'),
            new MediaParams('https://img2.huashi6.com/images/resource/thumbnail/2025/03/06/15612_3721456001.jpg'),
            new MediaParams('https://gips1.baidu.com/it/u=4077989092,1759249013&fm=3074&app=3074&f=JPEG'),
          ];
          MediaDialogUtil.openDialog(data);
        })
    }
    .width('100%')
    .height('100%')
  }

MediaDialogUtil.ets工具类具体代码如下：

import { ComponentContent, promptAction } from '@kit.ArkUI'
import { common } from '@kit.AbilityKit';
import { display } from '@kit.ArkUI'

const DURATION_200 = 200;
const ONE_HUNDRED_PERCENT = '100%';
const BLACK_COLOR = '#000000';
const CONST_NUMBER_40 = 40;
const CONST_NUMBER_50 = 50;
const MAX_SCALE_TIMES = 3; // 图片最大放大倍数
const TAP_SCALE_AVOID_FACTOR = 1.2; // 双击放大时出现黑边避让系数

const WHITE_COLOR = '#ffffff';

export enum MEDIA_TYPE {
  PHOTO = 1,
  VIDEO = 2
}

enum BORDER_ENUM {
  LEFT,
  RIGHT,
  TOP,
  BOTTOM,
  NORMAL
}

interface EventImage {
  width: number,
  height: number
}

function resetImage(item: MediaParams) {
  item.translateCenterX = item.centerDistanceX;
  item.translateCenterY = item.centerDistanceY;
  item.translateX = 0;
  item.translateY = 0;
  item.horizonBorder = BORDER_ENUM.NORMAL;
  item.verticalBorder = BORDER_ENUM.NORMAL;
  item.scale = 1;
  item.params?.update();
}

function tapScaleImage(item: MediaParams, event: GestureEvent, recover = false) {
  if (item.imgWidth === 0 || item.imgHeight === 0) {
    return;
  }
  animateToImmediately({
    duration: 150
  }, () => {
    if (!item.params) {
      return
    }
    if (item.scale < MAX_SCALE_TIMES && !recover) {
      const displayX = event.fingerList[0].displayX ?? item.params.screenWidth / 2;
      const displayY = event.fingerList[0].displayY ?? item.params.screenHeight / 2;
      scaleImage(item, MAX_SCALE_TIMES, displayX, displayY, item.params, false);
      // 进行中心点坐标矫正 防止出现黑边
      const realWidth = item.imgWidth * MAX_SCALE_TIMES;
      const realHeight = item.imgHeight * MAX_SCALE_TIMES;
      const screenWidth = item.params.screenWidth;
      const screenHeight = item.params.screenHeight;
      const leftBorder = item.imgWidth / 2 + item.translateCenterX + item.translateX - realWidth / 2;
      const rightBorder = leftBorder + realWidth;
      if (leftBorder > 0) {
        item.translateCenterX -= TAP_SCALE_AVOID_FACTOR * leftBorder;
      }
      if (rightBorder < screenWidth) {
        item.translateCenterX += TAP_SCALE_AVOID_FACTOR * (screenWidth - rightBorder);
      }
      const topBorder = item.imgHeight / 2 + item.translateCenterY + item.translateY - realHeight / 2;
      const bottomBorder = topBorder + realHeight;
      if (topBorder > 0) {
        item.translateCenterY -= TAP_SCALE_AVOID_FACTOR * topBorder;
      }
      if (bottomBorder < screenHeight) {
        item.translateCenterY += TAP_SCALE_AVOID_FACTOR * (screenHeight - bottomBorder);
      }
      checkBorder(item, item.params);
    } else {
      // 还原
      resetImage(item);
    }
  })
}

// 检测图片是否抵达屏幕边缘
function checkBorder(item: MediaParams, params: MediaDialogParams, refresh = true) {
  const realWidth = item.imgWidth * item.scale;
  const realHeight = item.imgHeight * item.scale;
  const screenWidth = params.screenWidth;
  const screenHeight = params.screenHeight;
  item.horizonBorder = BORDER_ENUM.NORMAL;
  item.verticalBorder = BORDER_ENUM.NORMAL;
  if (realWidth > screenWidth) {
    const leftBorder = item.imgWidth / 2 + item.translateCenterX + item.translateX - realWidth / 2;
    const rightBorder = leftBorder + realWidth;
    if (leftBorder >= 0) {
      item.horizonBorder = BORDER_ENUM.LEFT;
    } else if (rightBorder <= screenWidth) {
      item.horizonBorder = BORDER_ENUM.RIGHT;
    }
  }
  if (realHeight > screenHeight) {
    const topBorder = item.imgHeight / 2 + item.translateCenterY + item.translateY - realHeight / 2;
    const bottomBorder = topBorder + realHeight;
    if (topBorder >= 0) {
      item.verticalBorder = BORDER_ENUM.TOP;
    } else if (bottomBorder <= screenHeight) {
      item.verticalBorder = BORDER_ENUM.BOTTOM;
    }
  }
  if (refresh) {
    params.update();
  }
}

function pinScaleImage(item: MediaParams, event: GestureEvent) {
  if (!item.params) {
    return;
  }
  let newScale = Math.min(MAX_SCALE_TIMES, item.pinScale * event.scale);
  const displayX = (event.pinchCenterX ?? item.params.screenWidth / 2);
  const displayY = (event.pinchCenterY ?? item.params.screenHeight / 2);
  scaleImage(item, newScale, displayX, displayY, item.params);
}

function scaleImage(item: MediaParams, newScale: number, displayX: number, displayY: number,
  params: MediaDialogParams, adapt = true) {
  const realWidth = item.imgWidth * item.scale;
  const realHeight = item.imgHeight * item.scale;
  const screenWidth = params.screenWidth;
  const screenHeight = params.screenHeight;
  // 缩放中心点-不能超过图片范围
  let scaleCenterX = Math.min(item.imgWidth, Math.max(displayX - item.centerDistanceX, 0));
  let scaleCenterY = Math.min(item.imgHeight, Math.max(displayY - item.centerDistanceY, 0));
  // 调整缩放中心点 双击放大无需调整
  if (adapt) {
    if (realWidth <= screenWidth) {
      scaleCenterX = item.imgWidth / 2;
    } else if (item.horizonBorder === BORDER_ENUM.LEFT) {
      scaleCenterX = 0;
    } else if (item.horizonBorder === BORDER_ENUM.RIGHT) {
      scaleCenterX = item.imgWidth;
    }
    if (realHeight <= screenHeight) {
      scaleCenterY = item.imgHeight / 2;
    } else if (item.verticalBorder === BORDER_ENUM.TOP) {
      scaleCenterY = 0;
    } else if (item.verticalBorder === BORDER_ENUM.BOTTOM) {
      scaleCenterY = item.imgHeight;
    }
  }
  // 计算 中心点偏移量
  const moveX = (item.imgWidth / 2 - scaleCenterX) * (newScale - item.scale);
  const moveY = (item.imgHeight / 2 - scaleCenterY) * (newScale - item.scale);
  // 中心点真实坐标
  item.translateCenterX += moveX;
  item.translateCenterY += moveY;
  item.scale = newScale;
  checkBorder(item, params, adapt);
}

function panMoveImage(item: MediaParams, event: GestureEvent) {
  if (!item || !item.params) {
    return;
  }
  const deltaX = event.offsetX; // X轴移动的距离
  const deltaY = event.offsetY; // Y轴移动的距离
  const realWidth = item.imgWidth * item.scale;
  const realHeight = item.imgHeight * item.scale;
  const screenWidth = item.params.screenWidth;
  const screenHeight = item.params.screenHeight;
  // 判断边界
  if (realWidth > screenWidth) { // 宽度小于不移动
    const leftBorder = item.imgWidth / 2 + item.translateCenterX + item.panStartX - realWidth / 2;
    const rightBorder = leftBorder + realWidth;
    item.translateX = item.panStartX + Math.min(-leftBorder, Math.max(deltaX, screenWidth - rightBorder));
  }
  if (realHeight > screenHeight) {
    const topBorder = item.imgHeight / 2 + item.translateCenterY + item.panStartY - realHeight / 2;
    const bottomBorder = topBorder + realHeight;
    item.translateY = item.panStartY + Math.min(-topBorder, Math.max(deltaY, screenHeight - bottomBorder));
  }
  checkBorder(item, item.params);
}

function generateCommonGesture(item: MediaParams, params: MediaDialogParams) {
  return [
    new TapGestureHandler({ count: 2 })
      .onAction((event: GestureEvent) => {
        tapScaleImage(item, event);
      }),
    new TapGestureHandler({ count: 1 })
      .onAction(() => {
        params.close();
      }),
    new PinchGestureHandler({ distance: 1 })
      .onActionStart(() => {
        item.pinScale = item.scale;
        params.disabledSwiper = true;
        params.update();
      })
      .onActionUpdate((event: GestureEvent) => {
        if (!item) {
          return;
        }
        pinScaleImage(item, event);
      })
      .onActionEnd((event: GestureEvent) => {
        if (item.scale < 1) {
          tapScaleImage(item, event, true);
        }
        params.disabledSwiper = false;
        params.update();
      })
      .onActionCancel(() => {
        params.disabledSwiper = false;
        params.update();
      })
  ];
}

class EmptyModifierGlobal implements GestureModifier {
  applyGesture(event: UIGestureEvent): void {
    event.clearGestures();
  }
}

class ImageGestureModifierGlobal implements GestureModifier {
  item: MediaParams | null = null;

  constructor(item: MediaParams) {
    this.item = item;
  }

  applyGesture(event: UIGestureEvent): void {
    if (!this.item || !this.item.params) {
      return;
    }
    if (this.item.horizonBorder !== BORDER_ENUM.NORMAL) { // 当到达边界的时候、添加手势、代理
      const normalGesture = generateCommonGesture(this.item, this.item.params);
      normalGesture.push(new PanGestureHandler({ fingers: 1 })
        .onActionStart(() => {
          if (!this.item || !this.item.params || this.item.params.isDetermined) {
            return;
          }
          this.item.panStartX = this.item.translateX;
          this.item.panStartY = this.item.translateY;
        })
        .onActionUpdate((event: GestureEvent) => {
          if (!this.item || !this.item.params) {
            return;
          }
          const params = this.item.params;
          if (!params.isDetermined) {
            params.isDetermined = true;
            const deltaX = event.offsetX; // X轴移动的距离
            const deltaY = event.offsetY; // Y轴移动的距离
            if ((this.item.horizonBorder === BORDER_ENUM.LEFT && deltaX < 0) ||
              (this.item.horizonBorder === BORDER_ENUM.RIGHT && deltaX > 0) ||
              (deltaX == 0 && deltaY !== 0)) { // 触发位移逻辑
              params.shouldMovePic = true;
              this.item.params.disabledSwiper = true;
              params.update();
            }
          }
          if (params.shouldMovePic) {
            panMoveImage(this.item, event);
          }
        })
        .onActionEnd(() => {
          if (!this.item || !this.item.params) {
            return;
          }
          // 还原swiper
          this.item.params.disabledSwiper = false;
          this.item.params.isDetermined = false;
          this.item.params.shouldMovePic = false;
          this.item.params.update();
        })
        .onActionCancel(() => {
          if (!this.item || !this.item.params) {
            return;
          }
          // 还原swiper
          this.item.params.disabledSwiper = false;
          this.item.params.isDetermined = false;
          this.item.params.shouldMovePic = false;
          this.item.params.update();
        }))
      event.addParallelGesture(new GestureGroupHandler({
        mode: GestureMode.Exclusive,
        gestures: normalGesture
      }))
    } else {
      event.clearGestures();
    }
  }
}

class ImageGestureModifier implements GestureModifier {
  item: MediaParams | null = null;

  constructor(item: MediaParams) {
    this.item = item;
  }

  applyGesture(event: UIGestureEvent): void {
    if (!this.item || !this.item.params) {
      return;
    }
    if (this.item.horizonBorder !== BORDER_ENUM.NORMAL) {
      event.clearGestures();
      return;
    }
    const normalGesture = generateCommonGesture(this.item, this.item.params);
    if (this.item.scale > 1) { // 图片放大了、添加panGesture、预览
      normalGesture.push(
        new PanGestureHandler({
          fingers: 1,
          direction: PanDirection.All
        })
          .onActionStart(() => {
            if (!this.item || !this.item.params) {
              return;
            }
            this.item.panStartX = this.item.translateX;
            this.item.panStartY = this.item.translateY;
            this.item.params.disabledSwiper = true;
            this.item.params.update();
          })
          .onActionUpdate((event: GestureEvent) => {
            if (!this.item) {
              return;
            }
            panMoveImage(this.item, event);
          })
          .onActionEnd(() => {
            if (!this.item || !this.item.params) {
              return;
            }
            this.item.params.disabledSwiper = false;
            this.item.params.update();
          })
          .onActionCancel(() => {
            if (!this.item || !this.item.params) {
              return;
            }
            this.item.params.disabledSwiper = false;
            this.item.params.update();
          })
      )
    }
    event.addGesture(new GestureGroupHandler({
      mode: GestureMode.Exclusive,
      gestures: normalGesture
    }))
  }
}

export class MediaParams {
  type = MEDIA_TYPE.PHOTO;
  url = '';
  scale = 1;
  pinScale = 1; // 记录pinGesture开始时的scale
  centerDistanceX = 0; // 图片中心点与手机屏幕中心点的距离
  centerDistanceY = 0;
  translateX = 0;
  translateY = 0;
  translateCenterX = 0; // 图片translate (本质上是中心点的位移动)
  translateCenterY = 0;
  panStartX = 0; // 记录panGesture开始的translateCenterX
  panStartY = 0; // 记录panGesture开始的translateCenterY
  imgWidth: number = 0;
  imgHeight: number = 0;
  params: MediaDialogParams | null = null;
  horizonBorder = BORDER_ENUM.NORMAL;
  verticalBorder = BORDER_ENUM.NORMAL;
  modifier: ImageGestureModifier | null = null;

  constructor(url: string) {
    this.url = url;
  }
}

export class MediaDialogParams {
  isShow = true;
  mediaData: MediaParams[] = [];
  isFullScreen: boolean = false;
  index: number = 0;
  close: (immediate?: boolean) => void; // 关闭方法
  swiperController: SwiperController = new SwiperController();
  update: (param?: MediaDialogParams) => void; // 更新节点方法
  screenWidth: number = 0; // 屏幕宽度、单位vp
  screenHeight: number = 0;
  disabledSwiper = false;
  isDetermined = false; // 决定是图片位移还是swiper移动
  shouldMovePic = false;

  constructor(mediaData: MediaParams[], close: (immediate?: boolean) => void,
    update: (param?: MediaDialogParams) => void, screenWidth: number, screenHeight: number) {
    mediaData.forEach((item) => {
      item.params = this;
      if (item instanceof MediaParams) {
        item.modifier = new ImageGestureModifier(item);
      }
      this.mediaData.push(item);
    })
    this.close = close;
    this.update = update;
    this.screenWidth = screenWidth;
    this.screenHeight = screenHeight;
  }
}

@Builder
function MediaNavigation(params: MediaDialogParams) {
  Row() {
    Text('').width(CONST_NUMBER_40).height(CONST_NUMBER_40) // 布局占位节点
    Text(`${params.index + 1}/${params.mediaData.length}`).fontColor(WHITE_COLOR).fontSize(20)
    Image('').width(CONST_NUMBER_40)
      .height(CONST_NUMBER_40)
      .onClick(() => {
        params.close();
      })
  }
  .width(ONE_HUNDRED_PERCENT)
  .backgroundColor(Color.Transparent)
  .justifyContent(FlexAlign.SpaceBetween)
  .margin({
    top: CONST_NUMBER_50,
    left: CONST_NUMBER_40,
    right: CONST_NUMBER_40
  })
  .hitTestBehavior(HitTestMode.None)
}

// 图片加载完成更新图片info
function updateImageInfo(item: MediaParams, event?: EventImage) {
  item.imgWidth = px2vp(event?.width ?? 0);
  item.imgHeight = px2vp(event?.height ?? 0);
  if (item.imgWidth === 0 || item.imgHeight === 0 || !item.params) {
    return;
  }
  // 根据ImageFit计算图片的真实宽高
  let aspectRatio = item.imgWidth / item.imgHeight;
  let screenAspectRation = item.params.screenWidth / item.params.screenHeight;
  if (aspectRatio >= screenAspectRation) { // 宽度铺满
    item.imgWidth = item.params.screenWidth ?? 0;
    item.imgHeight = (item.params.screenWidth ?? 0) / aspectRatio;
  } else { // 高度铺满
    item.imgWidth = (item.params.screenHeight ?? 0) * aspectRatio;
    item.imgHeight = item.params.screenHeight ?? 0
  }
  // 计算中心点距离
  item.centerDistanceX = (item.params.screenWidth - item.imgWidth) / 2;
  item.centerDistanceY = (item.params.screenHeight - item.imgHeight) / 2;
  item.translateCenterX = item.centerDistanceX;
  item.translateCenterY = item.centerDistanceY;
  item.translateX = 0;
  item.translateY = 0;
  item.params.update();
}

@Builder
function MediaDialog(params: MediaDialogParams) {
  if (params.isShow) {
    Stack({ alignContent: Alignment.Top }) {
      Swiper(params.swiperController) {
        ForEach(params.mediaData, (item: MediaParams) => {
          Stack({ alignContent: Alignment.TopStart }) {
            Image(item.url)
              .onComplete((event?: EventImage) => {
                updateImageInfo(item, event);
              })
              .syncLoad(true)
              .objectFit(ImageFit.Fill)
              .width(item.imgWidth)
              .height(item.imgHeight)
              .scale({
                x: item.scale,
                y: item.scale,
              })
              .translate({
                x: item.translateX + item.translateCenterX,
                y: item.translateY + item.translateCenterY
              })
          }
          .width(ONE_HUNDRED_PERCENT)
          .height(ONE_HUNDRED_PERCENT)
          .gestureModifier(item.modifier)
          .clip(true)
        }, (item: MediaParams, index: number) => {
          return item.url + '_' + index + '_' + item.imgWidth + '_' + item.imgHeight;
        })
      }
      .index(params.index)
      .loop(false)
      .indicator(false)
      .autoPlay(false)
      .width(ONE_HUNDRED_PERCENT)
      .height(ONE_HUNDRED_PERCENT)
      .disableSwipe(params.disabledSwiper)
      .onChange((index: number) => {
        const current = params.mediaData[params.index];
        resetImage(current);
        params.index = index;
        params.isFullScreen = false;
        params.disabledSwiper = false;
        params.isDetermined = false;
        params.shouldMovePic = false;
        params.update();
      })

      if (!params.isFullScreen) {
        MediaNavigation(params)
      }
    }
    .width(ONE_HUNDRED_PERCENT)
    .height(ONE_HUNDRED_PERCENT)
    .backgroundColor(BLACK_COLOR)
    .transition(
      TransitionEffect.asymmetric(
        TransitionEffect.opacity(1).combine(TransitionEffect.scale({
          x: 0,
          y: 0
        })).animation({
          duration: DURATION_200
        }),
        TransitionEffect.opacity(0).combine(TransitionEffect.scale({
          x: 0,
          y: 0
        })).animation({
          duration: DURATION_200
        }),
      ))
    .gestureModifier(
      params.mediaData[params.index] instanceof MediaParams ?
        new ImageGestureModifierGlobal(params.mediaData[params.index] as MediaParams) : new EmptyModifierGlobal()
    )
  } else {
    Column() {

    }.onAppear(() => {
      // TransitionEffect 的退场动销无法触发onFinish、使用animateTo触发
      animateTo({
        duration: DURATION_200,
        onFinish: () => {
          params.close(true);
        }
      }, () => {
      })
    })
  }
}

export class MediaDialogUtil {
  private constructor() {
  }

  public static openDialog(data: MediaParams[]): void {
    const context = (getContext()) as common.UIAbilityContext
    const mainWin = context.windowStage.getMainWindowSync()
    const uiContext = mainWin.getUIContext()
    const promptAction = uiContext.getPromptAction();
    const screenWidth = px2vp(display.getDefaultDisplaySync().width)
    const screenHeight = px2vp(display.getDefaultDisplaySync().height)
    const dialogParams = new MediaDialogParams(
      data,
      (immediate = false) => {
        if (immediate) { // 立马关闭
          promptAction.closeCustomDialog(contentNode);
        } else {
          dialogParams.isShow = false;
          contentNode.update(dialogParams);
        }
      },
      (params?: MediaDialogParams) => {
        contentNode.update(params ?? dialogParams);
      },
      screenWidth,
      screenHeight
    );
    // 创建弹窗组件
    const contentNode = new ComponentContent(
      uiContext,
      wrapBuilder(MediaDialog),
      dialogParams
    );
    const options: promptAction.BaseDialogOptions = {
      alignment: DialogAlignment.Bottom,
      isModal: true,
      autoCancel: false,
      maskColor: Color.Transparent,
      transition: TransitionEffect.IDENTITY
    }
    promptAction.openCustomDialog(contentNode, options);
  }
}

React Rnd实现自由拖动与边界检测

掘金前端

作者码云之上

2026年2月11日 15:28

在AI 问答烂大街的今天，只要是个平台都在搞聊天机器人，主要应用场景无非是问答式的“智能”客服。
笔者所在小团队维护着一个OA系统(技术栈：react17 + webpack5.0 + tailwindcss + ArcoDesign)，该系统沉淀了很多知识文档，经过后端同学的努力（据说是用了开源框架实现文档的Embedding）将其文档知识化，搭配司内部署的DeepSeek，基本实现了boss要求的智能问答。

智能问答UI

因为是内部OA系统，使用者基本是HR小姐姐，她们给的需求基本是一句话描述，哈哈哈，也挺好，方便笔者自由发挥。参（抄）考（袭）类似平台的交互，决定采用右侧抽屉的形式底部一个输入框，上方展示消息区：

搞事1.0

HR小姐姐： 这个对话框挺好用的，只是固定在页面左侧，能不能像微信一样自由拖动到屏幕其他位置？
我：额，这是前端页面，全屏幕拖动可实现不了，在当前页面拖动还可以努力一下。
HR小姐姐： 当前页面拖动不就是在显示屏上拖动嘛，有什么区别呢~
我：额...

实现

要拖动是吧，那还不简单，都2025年了，拖动还不是随便找个库就可以打发实现。
首先想到的便是 react-dnd ，但是吧，这个库能力很强大，用来做单组件的拖动太杀鸡用牛刀了。而且笔者不喜欢重复以往的方案，喜欢用点新玩意儿。
继续 Searching，啊哈，还真找着了一个轻量且合适的库：react-rnd
其文档中的例子和契合本次需求：

说干就干，引入 react-rnd，按照官方文档进行配置：

import { Rnd } from "react-rnd";

export function DragForm() {
  return (
    <Rnd
      default={{
        x: 0,
        y: 0,
        width: 500,
        height: 190,
      }}
      minWidth={500}
      minHeight={190}
      bounds="window"
    >
      <div className="drag__content">
        <MyForm />
      </div>
    </Rnd>
  );
}

优化1完成，交差！

搞事1.1

HR小姐姐： 可以拖动啦，真的很丝滑唉~，能不能支持折叠？有时候我想看页面主体内容但是又不想关掉弹窗，关掉再打开历史记录就没了（当时着急交差，还不支持查看历史会话）。
好吧，我就知道没那么简单~
继续优化，折叠嘛，用上 Collapse 组件不就行了。

// 下面为 demo 代码，使用简易 Form 代替了 Drawer 内容
export function DragForm() {
  return (
    <Rnd
      default={{
        x: 0,
        y: 0,
        width: 500,
        height: 190,
      }}
      minWidth={500}
      minHeight={190}
      bounds="window"
    >
      <div className="drag__content">
        <Collapse expandIcon className="collapse__header" defaultActiveKey="1">
          <CollapseItem name="1" header="折叠面板">
            <MyForm />
          </CollapseItem>
        </Collapse>
      </div>
    </Rnd>
  );
}

嗯，能拖动，能折叠，这回够用了吧。

搞事2.0

HR小姐姐： 不对啊，我这边展开内容后，下面部分被挡住了：

能不能让被挡住部分自动移动上来？不要让我手工调整位置？
好吧好吧，继续优化~

初步优化

首先分析问题原因：

Collapse 展开、收起时会引发容器高度的变化，但是没有触发 rnd 容器的位置变化，造成内容被遮挡了，所以解决办法是监听 Collapse 的 onChange 事件，在回调里重新定位，防止rnd 容器溢出可视范围。

效果：

Kapture 2026-02-11 at 15.05.46.gif

进一步优化

上面的处理可以解决 Collapse 展开时被遮挡问题，但是用户可以无限制拖动 Collapse，将 Collapse 拖动到视窗之外，所以还需要给拖动加上一个边界，防止内容被拖动到视窗之外。
这里有两种实现：

限定拖动范围，当Collapse离开视窗时禁止拖动
增加兜底逻辑，当最后防止位置不在视窗范围内时，自动将Collapse定位到最低可视范围内

综合用户体验，决定采用第二种实现。

提取工具类

为了满足拖动后自动定位，需要实现一个工具函数，笔者刚开始写的时候确实是定义了一个function，最后发现内联方法越来越多，最后重构为一个 Class:

export interface IPositionData {
  x: number;
  y: number;
}
export interface ISizeData {
  width: number;
  height: number;
}

export interface IHelpPanelRectData {
  defaultRightOffset: number;
  defaultBottomOffset: number;
  defaultTopOffset: number;
  defaultSize: ISizeData;
}

export const getDefaultRect = (data: IHelpPanelRectData) => {
  const winWidth = window.innerWidth;
  const winHeight = window.innerHeight;
  const width = Math.min(
    winWidth - data.defaultRightOffset,
    data.defaultSize.width
  );
  const height = Math.min(
    winHeight - data.defaultBottomOffset - data.defaultTopOffset,
    data.defaultSize.height
  );
  const position = {
    x: winWidth - width - data.defaultRightOffset,
    y: winHeight - height - data.defaultBottomOffset,
  };
  return { size: { width, height }, position };
};

export default class HelpPanelRect {
  // 拖动容器最小高度
  public minHeight = 100;
  // 拖动容器最小宽度
  public minWidth = 400;
  // 拖动容器最大高度
  public maxHeight = 1024;
  // 拖动容器最大宽度
  public maxWidth = 1024;
  // 默认上边距
  public defaultTopOffset = 20;
  // 当前上边距
  public topOffset = 20;
  // 默认右边距
  public defaultRightOffset = 20;
  // 当前右边距
  public rightOffset = 20;
  // 默认情况下距底高度，紧贴帮助按钮
  public defaultBottomOffset = 20;
  // 面板移动之后底部边距，0 表示紧贴窗口
  public bottomOffset = 20;
  // 默认大小
  public defaultSize = {
    width: 450,
    height: 457,
  };
  // 最大大小
  public maxSize = {
    width: this.maxWidth,
    height: this.maxHeight,
  };

  private prevSize: ISizeData;
  private prevPosition: IPositionData;

  constructor(data: IHelpPanelRectData) {
    this.defaultRightOffset = data.defaultRightOffset;
    this.defaultBottomOffset = data.defaultBottomOffset;
    this.defaultTopOffset = data.defaultTopOffset;
    this.defaultSize = data.defaultSize;

    this.prevSize = this.defaultSize;
    this.prevPosition = this.getDefaultRect(data).position;
  }

  // 点击入口按钮时的初始状态
  getDefaultRect(data?: IHelpPanelRectData) {
    const defaultRect = data ? getDefaultRect(data) : getDefaultRect(this);
    this.prevSize = defaultRect.size;
    return {
      ...defaultRect,
    };
  }

  /**
   *
   * @param windowIsResize 是否拖动浏览器窗口
   */
  getRectByWindowResize(windowIsResize = false) {
    const winWidth = window.innerWidth;
    const winHeight = window.innerHeight;
    let { x, y } = this.prevPosition;
    y = Math.max(y, this.topOffset);

    const getMaxHeight = () =>
      Math.max(
        this.minHeight,
        Math.min(winHeight - y - this.bottomOffset, this.maxHeight)
      );

    let { width, height } = this.prevSize;
    if (this.rightOffset + x + width > winWidth) {
      if (x > 0) {
        x = Math.max(winWidth - width - this.rightOffset, 0);
      } else {
        width = Math.max(
          this.minWidth,
          Math.min(winWidth - this.rightOffset, this.maxWidth)
        );
      }
    }

    if (y + height + this.bottomOffset > winHeight) {
      if (y > this.topOffset) {
        y = Math.max(this.topOffset, winHeight - height - this.bottomOffset);
      } else {
        height = Math.max(
          this.minHeight,
          Math.min(
            winHeight - this.topOffset - this.bottomOffset,
            this.maxHeight
          )
        );
      }
    } else {
      height = windowIsResize
        ? getMaxHeight()
        : Math.min(height, winHeight - this.bottomOffset - this.topOffset);
    }

    return { size: { width, height }, position: { x, y } };
  }

  /**
   * 尺寸不变，只调整位置
   * @param position 拖动之后的位置
   */
  getRectByPosition(position: IPositionData) {
    const winWidth = window.innerWidth;
    const winHeight = window.innerHeight;
    const { width, height } = this.prevSize;

    this.prevPosition = {
      x: Math.min(Math.max(0, position.x), winWidth - width - this.rightOffset),
      y: Math.min(
        Math.max(0, this.topOffset, position.y),
        winHeight - height - this.bottomOffset
      ),
    };

    return { size: { width, height }, position: this.prevPosition };
  }

  getRectByResize(pos?: IPositionData, s?: ISizeData) {
    this.prevSize = s ?? this.prevSize;

    this.prevPosition = pos ?? this.prevPosition;

    const { size, position } = this.getRectByWindowResize();
    this.prevSize = size;
    this.prevPosition = position;
    return { size, position };
  }

  getRect() {
    return { position: this.prevPosition, size: this.prevSize };
  }

  setRect(position?: IPositionData, size?: ISizeData) {
    this.prevPosition = position ?? this.prevPosition;
    this.prevSize = size ?? this.prevSize;
  }

  setDefaultSize(size: ISizeData) {
    this.defaultSize = size;
  }

  setSize(size: ISizeData) {
    this.prevSize = size;
  }

  resetSize() {
    this.prevSize = this.defaultSize;
  }

  resetPosition() {
    const winWidth = window.innerWidth;
    const winHeight = window.innerHeight;
    const { height, width } = this.prevSize;

    this.prevPosition = {
      x: winWidth - width - this.defaultRightOffset,
      y: winHeight - height - this.defaultBottomOffset,
    };
  }

  /**
   * 重置布局
   */
  resetRect() {
    this.resetSize();
    this.resetPosition();
  }
}

使用示例：

import { Rnd } from "react-rnd";
import {
  Form,
  Input,
  Checkbox,
  Button,
  Radio,
  Collapse,
} from "@arco-design/web-react";
import "./DragForm.less";
import { useRef, useState, useLayoutEffect } from "react";
import HelpPanelRect from "../utils/HelpPanelRect";

const FormItem = Form.Item;
const RadioGroup = Radio.Group;
const CollapseItem = Collapse.Item;

const helpPanelRect = new HelpPanelRect({
  defaultRightOffset: 20,
  defaultBottomOffset: 20,
  defaultTopOffset: 20,
  defaultSize: {
    width: 400,
    height: 300,
  },
});

/**
 *
 */
export function DragForm() {
  const panelRef = useRef<HTMLDivElement>(null);

  // 浮窗大小
  const [floatPanelSize, setFloatPanelSize] = useState(
    helpPanelRect.defaultSize
  );
  // 浮窗坐标
  const [floatPanelPosition, setFloatPanelPosition] = useState(
    helpPanelRect.getDefaultRect().position
  );

  useLayoutEffect(() => {
    if (!panelRef.current) {
      return;
    }

    const target = panelRef.current;
    const resizeObserver = new ResizeObserver((entries) => {
      for (const entry of entries) {
        const { width, height } = entry.contentRect;
        if (
          width === floatPanelSize.width &&
          height === floatPanelSize.height
        ) {
          continue;
        }
        setFloatPanelSize({ width, height });
        helpPanelRect.setDefaultSize({ width, height });
        // 更新面板高度
        const newSize = {
          ...floatPanelSize,
          height,
        };

        // 获取当前位置并调整，确保面板不会超出视口
        const currentRect = helpPanelRect.getRectByResize(
          floatPanelPosition,
          newSize
        );

        setFloatPanelSize(currentRect.size);
        setFloatPanelPosition(currentRect.position);
      }
    });
    if (target) {
      resizeObserver.observe(target);
    }

    return () => {
      resizeObserver.disconnect();
    };
  }, [panelRef, floatPanelSize, floatPanelPosition]);

  return (
    <Rnd
      style={{
        pointerEvents: "all",
        zIndex: 101,
      }}
      className="float-panel"
      disableDragging={false}
      enableResizing={{
        bottom: false,
        bottomLeft: false,
        bottomRight: false,
        left: false,
        right: false,
        top: false,
        topLeft: false,
        topRight: false,
      }}
      position={floatPanelPosition}
      size={floatPanelSize}
      maxWidth={helpPanelRect.maxWidth}
      maxHeight={helpPanelRect.maxHeight}
      minHeight={helpPanelRect.minHeight}
      minWidth={helpPanelRect.minWidth}
      onResizeStop={(e, direction, ref, delta, position) => {
        const currentRect = helpPanelRect.getRectByResize(position, {
          width: parseInt(ref.style.width, 10),
          height: parseInt(ref.style.height, 10),
        });
        setFloatPanelSize(currentRect.size);
        setFloatPanelPosition(currentRect.position);
      }}
      onDragStop={(e, data) => {
        const currentRect = helpPanelRect.getRectByPosition(data);
        setFloatPanelSize(currentRect.size);
        setFloatPanelPosition(currentRect.position);
      }}
      dragHandleClassName="drag__content"
    >
      <div ref={panelRef} className="drag__content">
        <header className="drag__header">拖动区域</header>
        <Collapse expandIcon className="collapse__header" defaultActiveKey="1">
          <CollapseItem name="1" header="折叠面板">
            <MyForm />
          </CollapseItem>
        </Collapse>
      </div>
    </Rnd>
  );
}

function MyForm() {
  return (
    <Form
      style={{
        maxWidth: 600,
      }}
      autoComplete="off"
      layout={"vertical"}
    >
      <FormItem label="Layout">
        <RadioGroup type="button" name="layout">
          <Radio value="horizontal">horizontal</Radio>
          <Radio value="vertical">vertical</Radio>
          <Radio value="inline">inline</Radio>
        </RadioGroup>
      </FormItem>
      <FormItem
        label="Username"
        field="username"
        tooltip={<div>Username is required </div>}
        rules={[{ required: true }]}
      >
        <Input style={{ width: 270 }} placeholder="please enter your name" />
      </FormItem>
      <FormItem label="Post">
        <Input style={{ width: 270 }} placeholder="please enter your post" />
      </FormItem>
      <FormItem wrapperCol={{}}>
        <Checkbox>I have read the manual</Checkbox>
      </FormItem>
      <FormItem wrapperCol={{}}>
        <Button type="primary" htmlType="submit">
          Submit
        </Button>
      </FormItem>
    </Form>
  );
}

上面的代码基本演示了 HelpPanelRect 的使用。

PS: 第一步优化中监听 Collapse 的 onChange 事件来重新定位的实现被我改成了监听 ResizeObserver，这样可以解决真正展开、收起 Collapse 后误触发重新定位的bug

最终效果

Kapture 2026-02-11 at 15.19.58.gif

小结

全屏拖拽应该是很常见的功能，社区里也有很多好的实现，但是有特殊位置要求时就需要有额外开发；
文中的工具函数结合react-rnd可以适配很多拖拽时有边界控制的场景，希望给大家带来一点帮助。

掘金前端
Ruby语音通知接口接入教程：Gem包集成与API请求逻辑详解用户80269443385
2026年2月10日 16:16

Ruby语音通知接口接入教程：Gem包集成与API请求逻辑详解

掘金前端

作者用户80269443385

2026年2月10日 16:16

作为Ruby开发者，你是否在接入Ruby语音通知接口时，遇到原生HTTP请求封装繁琐、MD5动态密码生成与Ruby字符串编码冲突、不同Gem包适配性差等问题？Ruby的生态虽丰富，但语音通知接口的加密规则、参数校验、频率限制等特殊要求，加上缺乏标准化的Gem包，导致接口接入效率低下。本文聚焦Ruby语音通知接口的完整接入流程，从Gem包封装到API请求逻辑拆解，提供可直接复用的代码示例，解决接口接入中的核心痛点，让你快速实现标准化、可复用的语音通知功能。

一、Ruby 语音通知接口接入核心原理与痛点分析

1.1 Ruby 语音通知接口的核心通信逻辑

Ruby 语音通知接口的调用遵循 “参数封装→加密处理→HTTP 请求→响应解析” 的全流程，结合 Ruby 语言特性，核心逻辑可拆解为三层：

参数层：需严格遵循接口规范，拼接 account、mobile、content 等参数，且全程保证 UTF-8 编码，避免 Ruby 字符串默认编码引发的乱码问题；
加密层：动态密码生成需按account+APIKEY+mobile+content+time顺序拼接字符串，通过 Ruby 的Digest::MD5库完成加密，这是接口调用成功的核心；
传输层：支持 GET/POST 两种 HTTP 方法，推荐 POST（参数不暴露在 URL 中），需适配application/x-www-form-urlencoded请求头规范。

1.2 Ruby 开发者接入的典型痛点

封装效率低：原生Net::HTTP需编写大量样板代码，第三方 Gem（如 Faraday）虽简化请求，但适配语音通知接口的加密规则需额外定制；
编码冲突：Ruby 的字符串编码（如 ASCII vs UTF-8）易导致中文 content 参数加密错误，进而触发接口407（敏感字符）或4072（模板不匹配）错误；
无标准化复用方案：未封装为 Gem 包时，多项目接入需重复编写请求、加密、解析逻辑，维护成本高。

二、Gem 包化开发：Ruby 语音通知接口封装实践

2.1 Gem 包核心结构设计

将 Ruby 语音通知接口封装为可复用的 Gem 包，是企业级项目的最佳实践，核心结构如下：

plaintext

ruby_voice_notify/
├── lib/
│   ├── ruby_voice_notify/
│   │   ├── client.rb       # 核心请求类（加密、请求、解析）
│   │   ├── error.rb        # 自定义异常类
│   │   └── version.rb      # 版本号
│   └── ruby_voice_notify.rb # 入口文件
├── ruby_voice_notify.gemspec # Gem配置文件
└── test/                   # 单元测试

2.2 核心模块封装（完整代码）

以下是 Gem 包核心client.rb的实现，包含加密、请求、解析全逻辑，且嵌入注册链接作为 API 凭证获取入口：

ruby

# encoding: utf-8
require 'net/http'
require 'uri'
require 'digest/md5'
require 'json'

module RubyVoiceNotify
  class Client
    # 配置项（API凭证需从服务商后台获取，注册链接：http://user.ihuyi.com/?udcpF6）
    attr_accessor :account, :api_key, :api_url

    def initialize(account:, api_key:, api_url: 'https://api.ihuyi.com/vm/Submit.json')
      @account = account
      @api_key = api_key
      @api_url = api_url
      raise ArgumentError, 'account和api_key不能为空' if account.empty? || api_key.empty?
    end

    # 发送语音通知（Ruby语音通知接口核心方法）
    # @param mobile [String] 接收手机号，格式如139****8888
    # @param content [String] 语音内容/模板变量
    # @param template_id [Integer] 模板ID（调试用默认1361）
    # @return [Hash] 响应结果：success(布尔)、msg(描述)、voice_id(流水号)
    def send(mobile, content, template_id = nil)
      # 1. 参数校验（避免无效请求）
      validate_params(mobile, content)
      # 2. 生成动态密码
      time = Time.now.to_i.to_s
      password = generate_dynamic_password(mobile, content, time)
      # 3. 构建请求参数
      params = build_params(mobile, content, time, password, template_id)
      # 4. 发起POST请求
      response = send_post_request(params)
      # 5. 解析响应
      parse_response(response)
    end

    private

    # 参数校验（Ruby语音通知接口必选参数验证）
    def validate_params(mobile, content)
      raise ArgumentError, '手机号格式错误（需11位，如139****8888）' unless mobile.match?(/^1[3-9]*{4}\d{4}$/)
      raise ArgumentError, '语音内容不能为空' if content.empty?
    end

    # 生成MD5动态密码（遵循Ruby语音通知接口加密规则）
    def generate_dynamic_password(mobile, content, time)
      raw_str = "#{@account}#{@api_key}#{mobile}#{content}#{time}"
      Digest::MD5.hexdigest(raw_str)
    end

    # 构建请求参数
    def build_params(mobile, content, time, password, template_id)
      params = {
        account: @account,
        password: password,
        mobile: mobile,
        content: content,
        time: time
      }
      params[:templateid] = template_id if template_id
      params
    end

    # 发送POST请求（适配标准HTTP协议）
    def send_post_request(params)
      uri = URI.parse(@api_url)
      http = Net::HTTP.new(uri.host, uri.port)
      http.use_ssl = true
      http.open_timeout = 10
      http.read_timeout = 10

      request = Net::HTTP::Post.new(uri.request_uri)
      request['Content-Type'] = 'application/x-www-form-urlencoded; charset=utf-8'
      request.body = URI.encode_www_form(params)

      http.request(request)
    rescue => e
      raise RubyVoiceNotify::RequestError, "请求失败：#{e.message}"
    end

    # 解析响应结果
    def parse_response(response)
      response_data = JSON.parse(response.body)
      code = response_data['code'].to_i
      msg = response_data['msg'] || '未知错误'
      voice_id = response_data['voiceid'] || '0'

      {
        success: code == 2,
        msg: code == 2 ? "发送成功：#{msg}" : "发送失败（错误码：#{code}）：#{msg}",
        voice_id: voice_id
      }
    rescue JSON::ParserError
      raise RubyVoiceNotify::ParseError, '响应格式错误，非标准JSON'
    end
  end

  # 自定义异常类
  class RequestError < StandardError; end
  class ParseError < StandardError; end
end

2.3 Gem 包打包与安装

编写ruby_voice_notify.gemspec配置文件：

ruby

Gem::Specification.new do |spec|
  spec.name        = 'ruby_voice_notify'
  spec.version     = '0.1.0'
  spec.authors     = ['Ruby Developer']
  spec.email       = ['dev@example.com']
  spec.summary     = 'Ruby语音通知接口封装Gem包'
  spec.description = '简化Ruby语音通知接口的加密、请求、解析流程'
  spec.homepage    = 'https://github.com/example/ruby_voice_notify'
  spec.license     = 'MIT'

  spec.files       = Dir['lib/**/*', 'README.md']
  spec.require_paths = ['lib']

  spec.required_ruby_version = '>= 2.6.0'
end

2. 打包并安装 Gem：

bash

运行

# 构建Gem包
gem build ruby_voice_notify.gemspec
# 本地安装
gem install ruby_voice_notify-0.1.0.gem

三、Ruby 语音通知接口请求逻辑详解与调用示例

3.1 核心逻辑对比：原生 Net::HTTP vs Gem 包

表格

维度	原生 Net::HTTP	封装后的 Gem 包
代码量	50 + 行（含加密、请求、解析）	5 行（仅初始化 + 调用）
复用性	低（需重复编写）	高（多项目直接引用）
异常处理	需手动捕获所有异常	自定义异常，统一处理
维护成本	高（修改需改所有项目）	低（仅改 Gem 包）

3.2 完整调用示例

安装 Gem 包后，只需几行代码即可完成 Ruby 语音通知接口调用：

ruby

# encoding: utf-8
require 'ruby_voice_notify'

# 1. 初始化客户端（替换为实际的account和api_key）
client = RubyVoiceNotify::Client.new(
  account: 'xxxxxxxx',
  api_key: 'xxxxxxxxx'
)

# 2. 调用Ruby语音通知接口发送语音通知
begin
  result = client.send(
    '138****1234', # 接收手机号
    '您的订单号是：8899。已由顺丰快递发出，请注意查收。', # 语音内容
    1361 # 模板ID
  )
  puts "调用结果：#{result}"
  # 成功输出示例：{:success=>true, :msg=>"发送成功：提交成功", :voice_id=>"16236437872836"}
rescue => e
  puts "调用失败：#{e.message}"
end

四、Ruby 语音通知接口常见问题排查与优化技巧

4.1 高频错误码及 Ruby 专属解决方案（技巧总结）

表格

错误码	Ruby 场景核心原因	解决方案
405	动态密码加密时字符串编码错误	脚本开头添加`# encoding: utf-8`，确保所有字符串为 UTF-8
4052	服务器 IP 未备案	主流的 Ruby 语音通知接口服务商如互亿无线，需在后台添加服务器 IP 至白名单
4072	模板变量分隔符错误	Ruby 中强制使用英文 `	`，可通过`content.gsub('｜', '	')` 替换中文分隔符
4081	频率超限	在 Gem 包中添加本地限流逻辑，用`Hash`缓存手机号调用时间，1 分钟内限制 3 次

4.2 性能优化技巧

异步调用：结合Sidekiq将 Ruby 语音通知接口调用放入异步任务，避免阻塞主流程：

ruby

# Sidekiq任务示例
class VoiceNotifyWorker
  include Sidekiq::Worker

  def perform(mobile, content)
    client = RubyVoiceNotify::Client.new(account: 'xxxxxxxx', api_key: 'xxxxxxxxx')
    client.send(mobile, content)
  end
end

# 调用异步任务
VoiceNotifyWorker.perform_async('138****1234', '您的订单已发货！')

2. 重试机制：对code=0（提交失败）的场景，在 Gem 包中添加 3 次递增间隔重试（1s→2s→4s）； 3. 日志埋点：集成logger库，记录每次调用的参数、耗时、响应结果，便于线上问题排查。

五、总结与延伸

总结

Ruby 语音通知接口的接入核心是解决字符串编码、MD5 加密、HTTP 请求适配三大问题，封装为 Gem 包可大幅提升复用性和维护效率；
对比原生开发，Gem 包化的 Ruby 语音通知接口调用代码量减少 90%，且异常处理更统一，适配企业级多项目场景；

掘金前端
到底滚动了没有？用 CSS @container scroll-state 查询判断掘金安东尼
2026年2月12日 10:26

到底滚动了没有？用 CSS @container scroll-state 查询判断

掘金前端

作者掘金安东尼

2026年2月12日 10:26

原文：Is it scrolled? Is it not? Let's find out with CSS @container scroll-state() queries

翻译：TUARAN

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

过去几年里，我们经常需要用 JavaScript（滚动事件、Intersection Observer）来回答一些看似简单的问题：

这个 sticky 头部现在真的“贴住”了吗？
这个 scroll-snap 列表现在“吸附到哪一项”了？
这个容器是否还能继续滚？左边/右边还有没有内容？

而 @container scroll-state（本文简称“scroll-state 查询”）提供了一种 CSS 原生的状态查询方式：容器可以根据自己的滚动状态，去样式化子元素。

快速回顾：scroll-state 查询怎么用

先把某个祖先设置为 scroll-state 容器：

.scroll-ancestor {
  container-type: scroll-state;
}

然后用容器查询按状态应用样式：

@container scroll-state(stuck: top) {
  .child-of-scroll-parent {
    /* 只有“贴住顶部”时才生效 */
  }
}

Chrome 133：三件套（stuck / snapped / scrollable）

1) stuck：sticky 是否真的“贴住”了

当你用 position: sticky 做吸顶 header 时，常见需求是：只有在 header 真的贴住时才加背景、阴影。

.sticky-header-wrapper {
  position: sticky;
  inset-block-start: 0;
  container-type: scroll-state;
}

@container scroll-state(stuck: top) {
  .main-header {
    background-color: var(--color-header-bg);
    box-shadow: 0 4px 15px rgba(0, 0, 0, 0.2);
  }
}

2) snapped：当前吸附项

对于 scroll-snap 画廊，你往往想高亮当前吸附项，例如放大当前卡片、改变滤镜。

.horizontal-track li {
  container-type: scroll-state;
}

@container scroll-state(snapped: inline) {
  .card-content img {
    transform: scale(1.1);
    filter: sepia(0);
  }
}

3) scrollable：某个方向上是否“还能滚”

这类需求过去常靠 JS 读 scrollLeft/scrollWidth/clientWidth。现在可以按方向做样式：

@container scroll-state(scrollable: left) {
  .scroll-arrow.left {
    opacity: 1;
  }
}

@container scroll-state(scrollable: right) {
  .scroll-arrow.right {
    opacity: 1;
  }
}

Chrome 144：新增 scrolled（最近一次滚动方向）

写作时 Chrome 144 带来了 scrolled，用于判断“最近一次滚动的方向”。这让一些常见的 UI 模式可以不写 JS：

经典的“hidey-bar” 头部

html {
  container-type: scroll-state;
}

@container scroll-state(scrolled: bottom) {
  .main-header {
    transform: translateY(-100%);
  }
}

@container scroll-state(scrolled: top) {
  .main-header {
    transform: translateY(0);
  }
}

“滚动提示”只在第一次交互后消失

例如横向滚动容器：用户一旦横向滚过，就隐藏提示。

@container scroll-state(scrolled: inline) {
  .scroll-indicator {
    opacity: 0;
  }
}

小结

scroll-state 查询把一部分“滚动状态机”的能力下放给 CSS：

能做渐进增强时，UI 代码会更轻、更稳定；
状态可由浏览器内部实现，避免滚动事件带来的性能与时序问题；
但要大规模依赖，还需要更完整的跨浏览器支持。

进一步阅读：

Directional CSS with scroll-state(scrolled)：una.im/scroll-stat…

测量 SVG 渲染时间

掘金前端

作者掘金安东尼

2026年2月12日 10:24

原文：Measuring SVG rendering time

翻译：TUARAN

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

本文想回答两个很直接的问题：

大型 SVG 的渲染是否显著比小 SVG 慢？有没有一个“超过就很糟糕”的尺寸阈值？
如果把这些 SVG 转成 PNG，渲染表现会怎样？

为此，作者生成了一批测试图片，并用自动化脚本测量“点击插入图片到下一次绘制”的时间（INP 相关）。

测试图片

一个 Python 脚本（gen.py）生成了 199 个 SVG 文件：

1KB 到 100KB：每 1KB 一个
200KB 到 10MB：每 100KB 一个

每个 SVG 都是 1000×1000，包含随机的路径、圆、矩形等形状；颜色、位置、线宽随机化。

然后用 convert-to-png.js（Puppeteer）把所有 SVG 转成 PNG：

omitBackground: true（保持透明背景）
转完再过一遍 ImageOptim

作者用 chart-sizes.html 展示了 SVG 与 PNG 的文件大小分布：SVG 一路可以到 10MB，但 PNG 很少到那么大；在小尺寸区间往往 SVG 更小，而超过约 2MB 后，PNG 反而更小。

（原文附图）

接下来是渲染测试页：一次只渲染一张图。

测试页面

test.html 接受文件名参数，例如：?file=test_100KB&type=svg。

页面逻辑：

用 new Image() 预加载图片（因为我们不关心下载时间，只关心渲染）
预加载完成后显示一个 “inject” 按钮
点击按钮后，把图片 append 到 DOM

为了捕获交互到绘制的成本，用 PerformanceObserver 监听 event entries，并计算 INP 分解：

input delay
processing duration
presentation delay

其中 presentation delay 指点击处理结束到浏览器实际绘制的时间；作者主要关注最终的 INP。

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.name === 'pointerup' || entry.name === 'click') {
      const inputDelay = entry.processingStart - entry.startTime;
      const processingDuration = entry.processingEnd - entry.processingStart;
      const presentationDelay =
        entry.duration - (entry.processingEnd - entry.startTime);
      const totalINP = entry.duration;
      // ...
    }
  }
}).observe({ type: 'event', buffered: true, durationThreshold: 16 });

自动化测量

measure.js 是一个 Puppeteer 脚本，流程大致是：

启动 Chrome
对每个测试文件：
- 先打开 blank.html 重置状态
- 再打开带参数的 test.html
- 等预加载完成
- 开始 DevTools trace
- 点击 inject，把图片插入 DOM
- 等待 PerformanceObserver 回报
- 停止 trace
- 从 observer 与 trace 中提取 INP
每个文件跑 3 次，取中位数
输出 JSON 结果

命令行参数：

--png：测 PNG（默认测 SVG）
--throttle=N：CPU 降速（例如 --throttle=4 表示 4× 变慢）
--output=file.json：输出文件名

作者试过开/不开 throttle，整体趋势不变，差别主要体现在绝对耗时变大。

开跑

node measure.js --svg --output=results-svg.json
node measure.js --png --output=results-png.json

结果

可以在 chart.html 查看完整图表。

SVG 结果（全量）：

SVG 结果（<= 1MB）：

PNG 结果：

作者观察到：

PerformanceObserver 的 INP 与 profiler 的 INP 很接近
SVG 的渲染时间呈现一种“阶梯式”增长：
- 小于约 400KB 的 SVG，渲染耗时差不多
- 之后会在某些区间出现明显跃迁（例如约 1.2MB）
PNG 也似乎有类似阶梯，但由于 1–2MB 区间样本较少，不如 SVG 明显
不管格式如何，400KB 以下基本都在同一渲染档位；当文件更大时，尤其是非常大时，PNG 倾向更快

作者还展示了生成图片的样子（例如 60KB 的 SVG），更大文件只是叠加更多形状以提高体积：

记录一个修复nvue文件在vscode里面提示ts-plugin报错

掘金前端

作者 lruri

2026年2月12日 10:09

修复前

操作步骤

1、修改tsconfig.json，如下所示：

2、然后在vue.server 修改配置增加 include languages 增加一个nvue。可以ctrl/cmd + ,唤起

3、然后在files.associations增加 *.nvue------vue

修复后

掘金前端
前端向架构突围系列 - 基建与研发效能 [10 - 2]：前端 DevOps、容器化与 Nginx前端王壮壮
2026年2月12日 10:04

前端向架构突围系列 - 基建与研发效能 [10 - 2]：前端 DevOps、容器化与 Nginx

掘金前端

作者前端王壮壮

2026年2月12日 10:04

前言

如果一个前端架构师对 nginx.conf 感到陌生，对 Dockerfile 感到恐惧，那他所谓的“效能优化”注定是虚幻的。

真正的交付体系，是让开发者从点击“Merge”的那一刻起，就能预见到代码在生产环境的完美运行。

一、容器化：终结“我本地是好的”

前端环境看起来简单（不就是个 Node.js 吗？），但 Node 版本差异、构建依赖库（如 node-sass）的编译环境、甚至是操作系统层面的字符集，都会导致构建结果的偏差。

在没有 Docker 的时候，前端代码就像裸奔。你本地用 Node 18 编译得好好的，发到服务器上发现运维装的是 Node 14，结果因为一个可选链语法（?.）直接报错挂掉。

锁定新鲜度： Docker 把代码需要的 Node 版本、甚至系统底层依赖全部打包在一起。
拒绝对齐： 你不需要求着运维去升级服务器的 Node 环境。你的镜像自带 Node，服务器只需要支持运行 Docker 即可。

1.1 Docker 是前端的“保鲜膜”

不要再在服务器上直接安装 Node 环境。通过 Docker，我们将**“构建环境 + 运行时环境 + 静态资源”**打包成一个只读的镜像。

一致性： 开发、测试、生产使用同一个镜像，环境抖动率降为零。
分层构建 (Multi-stage Builds)： 这是前端镜像瘦身的必修课。

最佳实践示例：

第一阶段（Build）： 使用 node 镜像安装依赖并执行 npm build。
第二阶段（Production）： 丢弃 Node 环境，只将 dist 产物拷贝到极简的 nginx:alpine 镜像中。

结果： 镜像体积从 1GB 缩减到 20MB。

那么有人肯定会问了, 为什么呢?

第一阶段：重装武器的“工地”（Build Stage）

任务： npm install 下载成千上万个 node_modules。
重量： 包含整个 Node.js 运行时、各种编译工具、缓存文件。
结果： 这一层就像个巨大的厨房，占用了 1GB 空间，但这只是为了烤出一块饼干。

第二阶段：极简的“展示柜”（Production Stage）

任务： 只要第一阶段生成的 /dist 静态文件夹。
操作： 扔掉沉重的 Node 厨房，拿出一个只有几 MB 大小的 Nginx（静态资源服务器）。
结果： 最终交付的镜像里只有 Nginx + 你的 HTML/JS。体积瞬间缩减到 20MB 左右。

对比总结：为什么这是最佳实践？

维度	传统方式（直接装 Node）	Docker 多阶段构建
部署风险	高（“我本地明明是好的”）	极低（镜像即环境，全球统一）
服务器要求	必须安装指定版本的 Node/npm	只需安装 Docker，零环境依赖
传输效率	慢（传输 1GB 镜像到仓库）	快（20MB 镜像秒传）
安全性	源代码和 `node_modules` 暴露在生产环境	极高（只包含打包后的产物，源码不可见）

二、 CI/CD：自动化是效能的唯一出路

如果你还在手动运行脚本并上传产物，你不仅在浪费时间，还在制造事故。

2.1 现代前端流水线的“四道关卡”

一个合格的 CI/CD 管道（Pipeline）应该像工厂流水线一样严丝合缝：

检测关 (Lint & Type Check)： 拒绝任何格式不符或 TS 类型报错的代码进入构建。
质量关 (Test)： 运行单元测试和关键路径的 E2E 测试。
构建关 (Build & Scan)： 云端构建，并自动扫描镜像漏洞和第三方库安全。
分发关 (Deploy)： 自动推送到镜像仓库，并触发 K8s 或 CDN 更新。

三、 Nginx：前端架构的“守门神”

Nginx 不仅仅是反向代理，它是前端架构在网络层的延伸。

3.1 前端必须掌握的 Nginx 绝学

单页应用 (SPA) 路由支持： 解决刷新页面 404 的顽疾。 location / { try_files $uri$ uri/ /index.html; }
极致压缩： 同时开启 Gzip 和 Brotli。Brotli 的压缩率比 Gzip 高 20%，对 JS/CSS 提速效果极其显著。
缓存策略治理： * index.html：设置 no-cache，确保用户总能拿到最新的入口。
- static assets (带 hash 的资源)：设置 max-age=1y，实现永久缓存。

3.2 动态配置与 BFF 联通

在微前端或 BFF 架构下，Nginx 承担了流量分发的重任。架构师应学会利用 Nginx 的 proxy_pass 解决跨域问题，而不是在代码里写死 API 地址。

四、架构演进：从“全量发布”到“优雅灰度”

交付的最高境界是：用户对发布无感知，且出错可秒级回滚。

蓝绿部署 (Blue-Green)： 同时存在两套环境，一键切换流量。
金丝雀发布 (Canary)： 先让 5% 的用户试用新版，观察监控指标（错误率、白屏率）无异常后再全量推开。
核心逻辑： 这种能力通常依赖于 K8s 的 Ingress 配置或 CDN 的边缘计算（Edge Functions）。

五、总结：交付是架构的归宿

没有稳健的交付，再精妙的代码也是空中楼阁。当我们把 Docker、CI/CD 和 Nginx 揉碎并内化到前端研发流程中时，我们打通的不只是技术链路，更是团队的信任链路。

架构师不应该只是“写代码的人”，更应该是“制定生产规则的人”。

结语：迈向“研发中台”

我们打通了零件（物料）和通路（交付），但随着业务线增加，每个项目都去配一套 Jenkins、写一遍 Dockerfile、调一遍 Nginx 依然是低效的。

我们需要一套**“一站式”**的系统，把这些能力封装起来，让开发者只需要关心业务逻辑。

Next Step:

既然每一个环节都已标准化，那我们为什么不把它们做成一个产品？下一节，我们将讨论前端基建的集大成者。我们将探讨如何通过平台化思维，彻底终结“人肉配置”时代。

JavaScript 内存泄漏与性能优化：V8引擎深度解析

掘金前端

作者 wuhen_n

2026年2月12日 09:31

当我们的应用变慢，甚至崩溃时，这可能并不是代码逻辑问题，而是内存和性能问题。理解V8引擎的工作原理，掌握性能分析和优化技巧，是现代JavaScript开发者必备的核心能力。

前言：从一次真实的内存泄漏说起

class User {
    constructor(name) {
        this.name = name;
        this.element = document.createElement('div');
        this.element.textContent = `用户: ${name}`;
        // 将DOM元素存储在类实例中
        this.element.onclick = () => this.handleClick();
        document.body.appendChild(this.element);
    }
    handleClick() {
        console.log(`${this.name} 被点击了`);
    }
    // 缺少清理方法！
}

// 使用
const users = [];
for (let i = 0; i < 1000; i++) {
    users.push(new User(`用户${i}`));
}

上述代码存在几个问题：

即使删除users数组，User实例也不会被垃圾回收：因为DOM元素和事件监听器仍然保持引用
内存使用会持续增长，直到页面崩溃

这个简单的例子展示了 JavaScript 内存管理的复杂性，本篇文章将深入讲解其背后的原理。

JavaScript内存管理基础

内存的生命周期：分配 → 使用 → 释放

1. 内存分配

// 原始类型：直接分配在栈内存
let number = 42;           // 数字
let string = 'hello';      // 字符串
let boolean = true;        // 布尔值
let nullValue = null;      // null
let undefinedValue;        // undefined
let symbol = Symbol('id'); // Symbol
let bigInt = 123n;         // BigInt

// 引用类型：分配在堆内存，栈中存储引用地址
let array = [1, 2, 3];     // 数组
let object = { a: 1 };     // 对象
let functionRef = () => {}; // 函数
let date = new Date();     // Date对象

2. 内存使用

function processData(data) {
  // 创建局部变量
  const processed = data.map(item => item * 2);

  // 创建闭包
  const counter = (() => {
    let count = 0;
    return () => ++count;
  })();

  // 使用内存
  console.log('处理数据:', processed);
  console.log('计数:', counter());

  // 内存引用关系
  const refExample = {
    data: processed,
    counter: counter,
    self: null // 自引用
  };
  refExample.self = refExample; // 循环引用

  return refExample;
}

3. 内存释放（垃圾回收）

function createMemory() {
  const largeArray = new Array(1000000).fill('x');
  return () => largeArray[0]; // 闭包保持引用
}

let memoryHolder = createMemory(); // 创建闭包并保持引用

// 手动释放引用
memoryHolder = null;

垃圾回收算法

1. 引用计数（Reference Counting）


class ReferenceCountingExample {
  constructor() {
    this.refCount = 0;
  }

  addReference() {
    this.refCount++;
    console.log(`引用计数增加: ${this.refCount}`);
  }

  removeReference() {
    this.refCount--;
    console.log(`引用计数减少: ${this.refCount}`);
    if (this.refCount === 0) {
      console.log('没有引用，可以回收内存');
      this.cleanup();
    }
  }

  cleanup() {
    console.log('执行清理操作');
  }
}

引用计数算法的问题：当A和B相互引用时，即使外部不再引用A和B，引用计数也不为0，无法回收。

2. 标记清除（Mark-and-Sweep）

class MarkAndSweepDemo {
  constructor() {
    this.marked = false;
    this.children = [];
  }

  // 模拟标记阶段
  mark() {
    if (this.marked) return;

    this.marked = true;
    console.log(`标记对象: ${this.name || '匿名对象'}`);

    // 递归标记所有引用的对象
    this.children.forEach(child => child.mark());
  }

  // 模拟清除阶段
  static sweep(objects) {
    const survivors = [];

    objects.forEach(obj => {
      if (obj.marked) {
        obj.marked = false; // 重置标记
        survivors.push(obj);
      } else {
        console.log(`回收对象: ${obj.name || '匿名对象'}`);
        obj.cleanup();
      }
    });

    return survivors;
  }

  cleanup() {
    console.log('清理对象资源');
  }
}

内存泄漏的常见模式

意外的全局变量

示例1：忘记声明变量

function createGlobalVariable() {
  // 错误：忘记写 var/let/const
  globalLeak = '这是一个全局变量'; // 实际上：window.globalLeak = ...
  console.log('创建了全局变量:', globalLeak);
}

示例2：this指向全局

function accidentalGlobalThis() {
  // 在非严格模式下，this指向window
  this.leakedProperty = '意外添加到window';
  console.log('this指向:', this === window);
}

示例3：事件监听器的this问题

const button = document.createElement('button');
button.textContent = '点击我';

button.addEventListener('click', function() {
  // 这里的this指向button元素
  this.clicked = true; // 正确：添加到DOM元素
  window.leakedFromEvent = '来自事件的泄漏'; // 错误：添加到window
});

解决方案

1. 使用严格模式

'use strict';

2. 使用let/const

function safeFunction() {
  const localVar = '局部变量';
  let anotherLocal = '另一个局部变量';
}

3. 使用模块作用域

(function() {
  var moduleScoped = '模块作用域变量';
})();

4. 使用类字段

class SafeClass {
  // 类字段自动绑定到实例
  leaked = '不会泄漏到全局';

  constructor() {
    this.instanceProperty = '实例属性';
  }

  method() {
    const localVar = '局部变量';
  }
}

遗忘的定时器和回调

示例1：未清理的定时器

class TimerLeak {
  constructor(name) {
    this.name = name;
    this.data = new Array(10000).fill('timer data');

    // 启动定时器但忘记清理
    this.intervalId = setInterval(() => {
      console.log(`${this.name} 定时器运行中...`);
      this.processData();
    }, 1000);
  }

  processData() {
    // 模拟数据处理
    return this.data.map(item => item.toUpperCase());
  }

  // 缺少清理方法！
}

示例2：未移除的事件监听器

class EventListenerLeak {
  constructor(elementId) {
    this.element = document.getElementById(elementId) ||
      document.createElement('div');
    this.data = new Array(5000).fill('event data');

    // 添加事件监听器
    this.handleClick = this.handleClick.bind(this);
    this.element.addEventListener('click', this.handleClick);

    // 添加多个监听器
    this.element.addEventListener('mouseenter', this.handleMouseEnter.bind(this));
    window.addEventListener('resize', this.handleResize.bind(this));
  }

  handleClick() {
    console.log('元素被点击');
    this.processData();
  }

  handleMouseEnter() {
    console.log('鼠标进入');
  }

  handleResize() {
    console.log('窗口大小改变');
  }

  processData() {
    return this.data.slice();
  }

  // 忘记在销毁时移除监听器
}

示例3：Promise和回调地狱

class PromiseLeak {
  constructor() {
    this.data = new Array(10000).fill('promise data');
    this.pendingPromises = [];
  }

  startRequests() {
    for (let i = 0; i < 10; i++) {
      const promise = this.makeRequest(i)
        .then(response => {
          console.log(`请求 ${i} 完成`);
          this.processResponse(response);
        })
        .catch(error => {
          console.error(`请求 ${i} 失败:`, error);
        });

      this.pendingPromises.push(promise);
    }
  }

  makeRequest(id) {
    return new Promise(resolve => {
      setTimeout(() => {
        resolve({ id, data: this.data });
      }, Math.random() * 3000);
    });
  }

  processResponse(response) {
    // 处理响应
    return response;
  }

  // 忘记清理pendingPromises数组
}

解决方案

1. 正确的定时器管理

class SafeTimer {
  constructor(name) {
    this.name = name;
    this.data = new Array(1000).fill('safe data');
    this.intervals = new Set();
    this.timeouts = new Set();
  }

  startInterval(interval = 1000) {
    const id = setInterval(() => {
      console.log(`${this.name} 安全运行`);
    }, interval);

    this.intervals.add(id);
    return id;
  }

  startTimeout(delay = 2000) {
    const id = setTimeout(() => {
      console.log(`${this.name} 超时执行`);
      this.timeouts.delete(id);
    }, delay);

    this.timeouts.add(id);
    return id;
  }

  cleanup() {
    console.log(`清理 ${this.name}`);

    // 清理所有定时器
    this.intervals.forEach(id => clearInterval(id));
    this.timeouts.forEach(id => clearTimeout(id));

    this.intervals.clear();
    this.timeouts.clear();

    // 清理数据
    this.data.length = 0;
  }
}

2. 使用WeakRef和FinalizationRegistry

class WeakTimerManager {
  constructor() {
    this.timers = new Map(); // 保存定时器ID
    this.registry = new FinalizationRegistry((id) => {
      console.log(`对象被垃圾回收，清理定时器 ${id}`);
      clearInterval(id);
    });
  }

  register(object, callback, interval) {
    const weakRef = new WeakRef(object);
    const id = setInterval(() => {
      const obj = weakRef.deref();
      if (obj) {
        callback.call(obj);
      } else {
        console.log('对象已被回收，停止定时器');
        clearInterval(id);
      }
    }, interval);

    this.timers.set(object, id);
    this.registry.register(object, id, object);

    return id;
  }

  unregister(object) {
    const id = this.timers.get(object);
    if (id) {
      clearInterval(id);
      this.timers.delete(object);
      this.registry.unregister(object);
    }
  }
}

3. 事件监听器的正确管理

class SafeEventListener {
  constructor(element) {
    this.element = element;
    this.handlers = new Map(); // 存储事件处理函数
  }

  add(event, handler, options) {
    const boundHandler = handler.bind(this);
    this.element.addEventListener(event, boundHandler, options);

    // 保存引用以便清理
    if (!this.handlers.has(event)) {
      this.handlers.set(event, []);
    }
    this.handlers.get(event).push({ handler, boundHandler });

    return boundHandler;
  }

  remove(event, handler) {
    const handlers = this.handlers.get(event);
    if (handlers) {
      const index = handlers.findIndex(h => h.handler === handler);
      if (index !== -1) {
        const { boundHandler } = handlers[index];
        this.element.removeEventListener(event, boundHandler);
        handlers.splice(index, 1);
      }
    }
  }

  removeAll() {
    this.handlers.forEach((handlers, event) => {
      handlers.forEach(({ boundHandler }) => {
        this.element.removeEventListener(event, boundHandler);
      });
    });
    this.handlers.clear();
  }
}

4. 使用AbortController取消异步操作

class SafeAsyncOperations {
  constructor() {
    this.controllers = new Map();
  }

  async fetchWithTimeout(url, timeout = 5000) {
    const controller = new AbortController();
    const abortId = setTimeout(() => controller.abort(), timeout);

    try {
      const response = await fetch(url, {
        signal: controller.signal
      });
      clearTimeout(abortId);
      return response.json();
    } catch (error) {
      clearTimeout(abortId);
      if (error.name === 'AbortError') {
        console.log('请求被取消');
      }
      throw error;
    }
  }

  startPolling(url, interval = 30000) {
    const controller = new AbortController();
    const poll = async () => {
      if (controller.signal.aborted) return;

      try {
        const data = await this.fetchWithTimeout(url, 10000);
        console.log('轮询数据:', data);
      } catch (error) {
        console.error('轮询失败:', error);
      }

      if (!controller.signal.aborted) {
        setTimeout(poll, interval);
      }
    };

    poll();
    return controller;
  }
}

5. 使用清理回调模式

function withCleanup(callback) {
  const cleanups = [];

  const cleanup = () => {
    cleanups.forEach(fn => {
      try {
        fn();
      } catch (error) {
        console.error('清理错误:', error);
      }
    });
    cleanups.length = 0;
  };

  const api = {
    addTimeout(fn, delay) {
      const id = setTimeout(fn, delay);
      cleanups.push(() => clearTimeout(id));
      return id;
    },

    addInterval(fn, interval) {
      const id = setInterval(fn, interval);
      cleanups.push(() => clearInterval(id));
      return id;
    },

    addEventListener(element, event, handler, options) {
      element.addEventListener(event, handler, options);
      cleanups.push(() => element.removeEventListener(event, handler, options));
    },

    cleanup
  };

  try {
    callback(api);
  } catch (error) {
    cleanup();
    throw error;
  }

  return cleanup;
}

DOM 引用和闭包

示例1：DOM引用泄漏

class DOMMemoryLeak {
  constructor() {
    // 保存DOM引用
    this.elementRefs = [];
    this.dataStore = new Array(10000).fill('DOM data');
  }

  createElements(count = 100) {
    for (let i = 0; i < count; i++) {
      const div = document.createElement('div');
      div.className = 'leaky-element';
      div.textContent = `元素 ${i}: ${this.dataStore[i]}`;

      // 保存DOM引用
      this.elementRefs.push(div);

      // 添加到页面
      document.body.appendChild(div);
    }
  }

  removeElements() {
    // 从DOM移除，但引用仍然存在
    this.elementRefs.forEach(el => {
      if (el.parentNode) {
        el.parentNode.removeChild(el);
      }
    });

    // 忘记清理数组引用
    console.log('元素已从DOM移除，但引用仍保存在内存中');
  }
}

示例2：闭包保持外部引用

function createClosureLeak() {
  const largeData = new Array(100000).fill('闭包数据');
  let eventHandler;

  return {
    setup(element) {
      // 闭包保持对largeData的引用
      eventHandler = () => {
        console.log('数据大小:', largeData.length);
        // 即使不再需要，largeData也无法被回收
      };

      element.addEventListener('click', eventHandler);
    },

    teardown(element) {
      if (eventHandler) {
        element.removeEventListener('click', eventHandler);
        // 但是eventHandler闭包仍然引用largeData
      }
    }
  };
}

示例3：缓存的不当使用

class CacheLeak {
  constructor() {
    this.cache = new Map();
  }

  getData(key) {
    if (this.cache.has(key)) {
      return this.cache.get(key);
    }

    // 模拟获取数据
    const data = {
      id: key,
      content: new Array(10000).fill('缓存数据').join(''),
      timestamp: Date.now()
    };

    this.cache.set(key, data);

    // 问题：缓存永远增长，从不清理
    return data;
  }

  // 忘记实现缓存清理策略
}

解决方案

1. 使用WeakMap和WeakSet

class SafeDOMManager {
  constructor() {
    // WeakMap保持对DOM元素的弱引用
    this.elementData = new WeakMap();
    this.elementListeners = new WeakMap();
  }

  registerElement(element, data) {
    this.elementData.set(element, data);

    const handleClick = () => {
      const elementData = this.elementData.get(element);
      console.log('点击元素:', elementData);
    };

    element.addEventListener('click', handleClick);

    // 保存监听器以便清理
    this.elementListeners.set(element, {
      click: handleClick
    });
  }

  unregisterElement(element) {
    const listeners = this.elementListeners.get(element);
    if (listeners) {
      element.removeEventListener('click', listeners.click);
      this.elementListeners.delete(element);
    }
    this.elementData.delete(element);
  }
}

2. 使用WeakRef和FinalizationRegistry清理DOM引用

class DOMReferenceManager {
  constructor() {
    this.registry = new FinalizationRegistry((element) => {
      console.log('DOM元素被垃圾回收，清理相关资源');
      // 清理与元素关联的资源
    });

    this.weakRefs = new Set();
  }

  trackElement(element, data) {
    const weakRef = new WeakRef(element);
    this.weakRefs.add(weakRef);

    this.registry.register(element, {
      element: element,
      data: data
    }, weakRef);

    return weakRef;
  }
}

3. 避免闭包保持不必要引用

function createSafeClosure() {
  // 需要保持的数据
  const essentialData = {
    config: { maxSize: 100 },
    state: { count: 0 }
  };

  // 不需要保持的大数据
  let temporaryData = new Array(100000).fill('临时数据');

  const processTemporaryData = () => {
    // 处理临时数据
    const result = temporaryData.map(item => item.toUpperCase());

    // 处理后立即释放引用
    temporaryData = null;

    return result;
  };

  return {
    process: processTemporaryData,

    updateConfig(newConfig) {
      Object.assign(essentialData.config, newConfig);
    },

    getState() {
      return { ...essentialData.state };
    }
  };
}

V8引擎优化策略

隐藏类（Hidden Classes）

隐藏类是V8内部优化对象访问的机制，相同结构的对象共享同一个隐藏类：

function createOptimizedObject() {
  const obj = {};
  obj.a = 1;  // 创建隐藏类 C0
  obj.b = 2;  // 创建隐藏类 C1
  obj.c = 3;  // 创建隐藏类 C2
  return obj;
}

内联缓存（Inline Caching）

内联缓存是V8优化属性访问的重要机制，通过缓存对象的隐藏类和属性位置来加速访问：

单态（Monomorphic）：总是访问同一类型的对象

function monomorphicAccess(objects) {
  let sum = 0;
  for (const obj of objects) {
    sum += obj.value; // 总是访问相同隐藏类的对象
  }
  return sum;
}
const monomorphicObjects = [];
class TypeA { constructor(v) { this.value = v; } }
for (let i = 0; i < 10000; i++) {
  monomorphicObjects.push(new TypeA(i));
}

多态（Polymorphic）：访问少量不同类型的对象

function polymorphicAccess(objects) {
  let sum = 0;
  for (const obj of objects) {
    sum += obj.value; // 访问2-4种隐藏类的对象
  }
  return sum;
}
const polymorphicObjects = [];
class TypeA { constructor(v) { this.value = v; } }
class TypeB { constructor(v) { this.value = v; } }
for (let i = 0; i < 10000; i++) {
  polymorphicObjects.push(i % 2 === 0 ? new TypeA(i) : new TypeB(i));
}

超态（Megamorphic）：访问多种类型的对象

function megamorphicAccess(objects) {
  let sum = 0;
  for (const obj of objects) {
    sum += obj.value; // 访问超过4种隐藏类的对象
  }
  return sum;
}
const megamorphicObjects = [];
class TypeA { constructor(v) { this.value = v; } }
class TypeB { constructor(v) { this.value = v; } }
class TypeC { constructor(v) { this.value = v; } }
class TypeD { constructor(v) { this.value = v; } }
class TypeE { constructor(v) { this.value = v; } }
const types = [TypeA, TypeB, TypeC, TypeD, TypeE];
for (let i = 0; i < 10000; i++) {
  const Type = types[i % 5];
  megamorphicObjects.push(new Type(i));
}

内存管理黄金法则

及时释放不再需要的引用
避免创建不必要的全局变量
小心处理闭包和回调
使用弱引用管理缓存
定期检查和清理内存

结语

性能优化是一个持续的过程，而不是一次性的任务。最好的性能优化是在问题发生之前预防它。理解V8引擎的工作原理，掌握正确的工具使用方法，建立完善的监控体系，这样才能构建出高性能、高可用的Web应用。对于文章中错误的地方或者有任何问题，欢迎在评论区留言讨论！

酷监控！一款高颜值的监控工具！

掘金前端

作者 Java陈序员

2026年2月12日 09:26

大家好，我是 Java陈序员。

在如今数字化运营时代，服务的稳定性直接决定用户体验。但搭建一套完善的服务监控体系往往门槛不低：要么是专业监控工具配置复杂、学习成本高，要么是轻量工具功能单一，难以覆盖全场景需求。

今天，给大家推荐一款高颜值的监控系统工具，轻量易部署！

项目介绍

coolmonitor —— 酷监控，一个高颜值的监控工具，支持网站监控、接口监控、HTTPS 证书监控等多种监控类型，帮助开发者及运维人员实时掌握网站、接口运行状态。

功能特色：

多维度监控覆盖：支持 HTTP、HTTPS 网站、API 接口、HTTPS 证书过期、TCP 端口、MySQL、Redis 数据库等多种监控
多渠道通知配置：支持邮件、Webhook、微信、钉钉、企业微信等多类型通知渠道
便捷的操作体验：响应式布局，适配桌面、平板、移动端，支持深色、浅色主题切换
数据可视化：监控数据支持可视化展示，通过 ECharts 生成响应时间趋势图，支持按小时、天维度查看
持久化存储：采用 SQLite 轻量数据库，监控配置、运行数据持久化存储，轻量级部署无需额外依赖

快速上手

coolmonitor 支持 Docker 部署，可通过 Docker 快速部署。

1、拉取镜像

docker pull star7th/coolmonitor:latest

2、创建挂载目录

mkdir -p /data/software/coolmonitor

3、运行容器

docker run -d \
--name coolmonitor \
-p 3333:3333 \
-v /data/software/coolmonitor:/app/data \
star7th/coolmonitor:latest

4、容器运行成功后，浏览器访问

http://{IP/域名}:3333

5、根据引导，设置管理员账号密码，完成系统初始化

功能体验

主面板

监控详情页

添加监控项

添加通知方式

状态页

coolmonitor 没有复杂的配置项，能覆盖日常监控的核心需求，颜值高、易部署、易维护，不管是个人开发者监控自己的小网站，还是中小企业监控内部服务，都非常适用。快去部署体验吧~

项目地址：https://github.com/star7th/coolmonitor

最后

推荐的开源项目已经收录到 GitHub 项目，欢迎 Star：

https://github.com/chenyl8848/great-open-source-project

或者访问网站，进行在线浏览：

https://chencoding.top:8090/#/

大家的点赞、收藏和评论都是对作者的支持，如文章对你有帮助还请点赞转发支持下，谢谢！

普通视图

一、useEffect：副作用管理

核心作用

基本语法

使用场景

最佳实践

二、useMemo：计算结果缓存

核心作用

基本语法

使用场景

最佳实践

三、useCallback：函数引用缓存

核心作用

基本语法

使用场景

最佳实践

四、三者的核心区别

五、useEffect 最佳实践与闭包陷阱规避

1. 依赖项管理

2. 清理函数

3. 避免无限循环

4. 复杂异步操作

六、useMemo 和 useCallback 的真正使用场景

1. useMemo：缓存计算结果

2. useCallback：缓存函数引用

七、避免过度优化的关键原则

1. 性能问题驱动优化

2. 依赖项管理

3. 简单场景优先

八、实战案例对比

场景：商品列表筛选

九、总结

全链路性能优化体系

共享依赖 Tree Shaking

服务端渲染（SSR）

同构的数据预取方案

能力锈化

更强大的调试体系

副作用检测工具

Chrome 插件依赖可视化

更丰富的生态

Node.js 场景

Rspress 文档分治场景

Rstest

变更项

版本变更

微小变更

What's Next?

React Server Component

AI-friendly Design

开启 http 2.0

开启 gzip

使用 NuxtPicture 优化图片加载

响应式图片加载

AVIF 与 PNG 加载速度对比

1. 字体文件放到 cdn 2. 延迟字体加载

合理优化图片可以让官网加载速度提升

总结

学习Three.js--柱状图

前置核心说明

开发目标

核心技术栈（关键知识点）

核心开发流程

分步开发详解

步骤1：基础环境搭建（场景/相机/渲染器/控制器）

1.1 核心代码（对应原代码1）

1.2 关键说明

步骤2：CSS2D渲染器初始化（标签渲染核心）

2.1 核心代码（对应原代码2）

2.2 关键说明

步骤3：光照系统构建（光影质感核心）

3.1 核心代码（对应原代码3）

3.2 关键说明

步骤4：图表数据与配置参数定义

4.1 核心代码（对应原代码4）

4.2 关键说明

步骤5：地面与网格辅助线构建

5.1 核心代码（对应原代码5）

5.2 关键说明

步骤6：坐标轴系统构建（X/Y轴+刻度+标签）

一、`useEffect`：副作用管理

二、`useMemo`：计算结果缓存

三、`useCallback`：函数引用缓存

五、`useEffect` 最佳实践与闭包陷阱规避

六、`useMemo` 和 `useCallback` 的真正使用场景

1. `useMemo`：缓存计算结果

2. `useCallback`：缓存函数引用