事件循环（Event Loop）是前端开发中极其重要的基础内容，作为前端开发者必须要掌握的内容。同时在日常的工作或者面试中也是高频的话题。

在讲事件循环之前，先了解一下计算机科学中的两个基本执行单元：进程和线程。

进程

进程是操作系统中资源分配的基本单位。它是程序的一次执行过程，拥有自己独立的内存空间、代码、数据等资源。一个进程可以包含多个线程，它们共享进程的资源，但是每个线程有自己的执行路径。在Windows系统中，一个运行的应用程序，如xx.exe，就是一个进程。

线程

线程是进程中的一个执行任务，是处理器任务调度和执行的基本单位。它是比进程更小的能独立运行的基本单位。线程共享其所属进程的地址空间和资源，但拥有自己的程序计数器、虚拟机栈和本地方法栈。线程之间的切换开销小于进程，因此被称为轻量级进程。

通过示意图，我们可以更好的理解他们的关系。每个应用程序，至少有一个进程，进程之间相互独立，如果要通信，也需要双方同意。每个进程至少有一个线程，所以在进程开启后会自动创建一个线程来运行代码，称之为主线程。如果要同时执行多块代码，主线程就会启动更多的线程来执行代码，所以一个进程中可以包含多个线程。

浏览器

浏览器是一个多进程多线程的应用程序。浏览器内部工作极其复杂，为了减少连环崩坏的几率，它会自动启动多个进程。

以 Chrome 为例，通过快捷键 shift + esc，可以快速打开浏览器的任务管理器，可以看见有多个进程在运行。

前端开发最关注的是渲染进程，每开启一个 Tab 页，就会有一个渲染进程。渲染进程下面一般是，主线程、合成线程、栅格线程、IO线程、Workder相关线程。 其中有一个误解就是会认为有一个独立的JS引擎线程，但实际上，JS引擎是运行在主线程中的，它与HTML/CSS解析、样式计算、布局、绘制串行执行，会与 GUI 渲染互斥，所以JS会阻塞渲染。 参考官方核心文档-Threading and Tasks in Chrome。

浏览器中的事件循环机制

事件循环是单线程 JS 支持异步的核心机制。当执行栈中的同步任务执行完毕并清空后，事件循环会按照特定规则，从任务队列中提取并执行异步任务的回调函数。本质上，它是“事件驱动”模式在 JS 运行环境中的具体调度实现。

事件驱动

浏览器异步任务的执行原理背后其实是一套事件驱动的机制。事件触发、任务选择和任务执行都是由事件驱动机制来完成的。NodeJS 和浏览器的设计都是基于事件驱动的，简而言之就是由特定的事件来触发特定的任务，这里的事件可以是用户的操作触发的，如 click 事件；也可以是程序自动触发的，比如浏览器中定时器线程在计时结束后会触发定时器事件。

在事件驱动中，当有事件触发后，被触发的事件（上面所说的回调函数）会按顺序暂时存在一个队列中，待 JS 的同步任务执行完成后，会从这个队列中取出要处理的事件并进行处理。那么具体什么时候取任务、优先取哪些任务，这就由事件循环流程来控制了。

执行栈与任务队列

JS 在解析一段代码时，会把同步代码按照顺序排在执行栈中，然后依次执行里面的函数。当遇到异步任务就会交给其他线程处理，待当前执行栈中的所有同步代码执行完成后，会从任务队列中去取出早已完成的异步任务的回调函数加入执行栈继续执行，遇到异步任务又交给其他线程处理,…如此循环往复。

JS 按顺序执行执行栈中的方法，每次执行一个方法时，会为这个方法生成独有的执行环境（上下文 context)，待这个方法执行完成后，销毁当前的执行环境，并从栈中弹出此方法（即消费完成），然后继续下一个方法。

可见，在事件驱动的模式下，至少包含了一个执行循环来检测任务队列是否有新的任务。通过不断循环去取出异步回调来执行，这个过程就是事件循环，而每一次循环就是一个事件周期或称为一次 tick。

任务分类

任务没有优先级，但是消息队列有优先级，消息队列不止一个。

每一个任务都有任务类型，同一个类型的任务必须在同一个队列。浏览器必须准备一个微队列，微队列的优先级优先所有其他队列。

在以前，只有宏任务队列和微任务队列。但是随着浏览器的复杂度急剧发展，W3C不再使用宏队列的说法。

在目前的 chrome的实现中，至少包含了下面的队列：

• 延时队列：用于存放定时器到达后的回调函数，优先级「中」
• 交互队列：用于存放用户操作后的事件处理任务，优先级「高」
• 微队列：用于存在需要最快执行的任务，优先级「最高」

那么有什么办法可以添加任务到微队列呢？

• Promise：当 Promise 决议后，其 .then、.catch、.finally 的回调会进入微队列。
• queueMicrotask：提供了专门用于添加微任务的原生 API（推荐）。
• MutationObserver：浏览器中用于监听 DOM 变化触发的回调，也属于微任务。
• process.nextTick（Node.js）：虽不是标准微任务，但执行时机甚至比微任务更早。

定时器误差

事件循环中，总是先执行同步代码之后，才会去任务队列中取任务执行。那么如果同步代码执行时间过长，就会导致定时器不准时执行。 同步代码耗时越长，定时器误差就越大。不仅仅是同步代码，由于微任务的优先级最高，所以微任务也会影响计时，假设同步代码中有一个死循环或者微任务中递归不断在启动其他微任务，那么宏任务里面的代码可能永远得不到执行。所以主线程代码的执行效率提升是一件很重要的事情。

总结

通篇来看，我们可以得出以下核心结论：

1. 单线程是基石：JavaScript 是一门单线程语言，其引擎运行在浏览器的渲染进程主线程中，执行过程与 GUI 渲染互斥。
2. 事件驱动是模式：浏览器通过事件驱动机制管理异步任务，事件触发后产生回调任务，并按类型进入不同的任务队列（如微队列、延时队列、交互队列）。
3. 事件循环是核心：它是连接“同步执行栈”与“异步任务队列”的调度官。基本逻辑是：执行同步代码（清空栈） -> 执行并清空所有微任务 -> 必要时进行 UI 渲染 -> 提取下一个异步回调，如此往复。
4. 性能导向：理解事件循环不仅是为了应付面试，更是为了在开发中意识到主线程的宝贵。避免长时间同步阻塞和微任务堆积，是确保定时器精准、页面丝滑响应的关键。

掌握了事件循环，就掌握了 JavaScript 在浏览器中运行的“心跳”。

在工作中，我们经常会遇到需要生成PDF的业务，比如合同、报告等。

后端生成 PDF

对于前端来说，最省事的就是后端生成 PDF 文件，前端根据返回的 URL 地址进行下载。

URL 下载

如果后端直接返回一个可访问的 URL 地址，我们可以通过以下几种方式进行下载：

window.open / href

这是最简单的方式，但缺点是无法控制下载后的文件名，且受浏览器拦截政策影响。

const downloadByUrl = (url: string) => {
  window.open(url, '_blank')
}

a 标签

通过创建虚拟锚点并利用 download 属性，可以更好地控制下载行为。

/**
 * 通过 URL 下载文件
 * @param url 文件地址
 * @param fileName 自定义文件名
 */
export const downloadFileByUrl = (url: string, fileName?: string) => {
  const link = document.createElement('a')
  link.href = url

  // 如果提供了文件名，则设置 download 属性
  if (fileName) {
    link.download = fileName
  }

  link.target = '_blank'
  link.style.display = 'none'
  document.body.appendChild(link)

  link.click()

  // 清理
  document.body.removeChild(link)
}

文件流下载

如果后端返回的是文件流（Blob），由于浏览器无法直接解析这种数据格式作为下载源，我们需要通过 URL.createObjectURL 将其转换为一个临时的 blob:URL，然后利用 <a> 标签触发下载。

/**
 * 通过文件流下载文件
 * @param data 文件流数据 (Blob | ArrayBuffer | string)
 * @param fileName 下载后的文件名
 * @param mimeType 文件的 MIME 类型 (可选，如果不传则尝试从 data 中获取或使用默认值)
 */
export const downloadFileByStream = (data: any, fileName: string, mimeType?: string) => {
  // 1. 优先获取数据的类型
  const type = mimeType || (data instanceof Blob ? data.type : 'application/octet-stream')

  // 2. 将数据封装为 Blob 对象
  const blob = data instanceof Blob ? data : new Blob([data], { type })

  // 3. 创建一个临时的 URL 指向该 Blob 对象
  const blobURL = window.URL.createObjectURL(blob)

  // 4. 创建虚拟锚点触发下载
  const link = document.createElement('a')
  link.href = blobURL
  link.download = fileName
  link.style.display = 'none'
  document.body.appendChild(link)

  link.click()

  // 5. 下载执行后释放 URL 对象和 DOM 节点
  document.body.removeChild(link)
  // 不释放可能导致内存泄露，过早释放可能会导致下载失败，可以延迟触发
  window.URL.revokeObjectURL(blobURL)
}

window.print()

在有些业务上，需要纯前端生成 PDF。

这是调用浏览器原生打印功能最简单的方法。它会将当前页面的内容渲染到打印预览窗口中，用户可以选择保存为 PDF。

其实并不推荐，因为在很多复杂的结构中，需要做很多工作，才能达到理想的效果。 并且会有打印预览弹窗，无法实现无感打印。

const handlePrint = () => {
  window.print()
}

CSS 控制

为了让打印出来的效果更好，我们通常需要使用 @media print 查询来控制打印时的样式。

@media print {
  /* 隐藏不需要打印的元素，如导航栏、侧边栏、按钮 */
  .no-print {
    display: none !important;
  }

  /* 调整打印区域的宽度 */
  .print-container {
    width: 100%;
    margin: 0;
    padding: 0;
  }

  /* 强制分页 */
  .page-break {
    page-break-after: always;
  }
}

html2canvas-pro 与 jsPDF

html2canvas 可以将网页内容转换为图片，然后 jsPDF 可以将图片转换为 PDF。

下面是通用的代码，可用于 95% 的场景，该方法会自动分页，且不会切断元素。

import html2canvas from 'html2canvas-pro' // 推荐使用 pro 版本无缝替代
import jsPDF from 'jspdf'

/**
 * 将指定 DOM 导出为 PDF
 * @param domId 目标 DOM 元素的 ID
 * @param title 导出的文件名
 */
export const exportPdf = async (domId: string, title?: string): Promise<void> => {
  const ele = document.getElementById(domId)
  if (!ele) throw new Error('未找到目标元素')

  const scale = window.devicePixelRatio > 1 ? window.devicePixelRatio : 2

  // 获取所有防截断元素（防止元素被分页切开，如表格行、标题、段落等）
  const nodes = ele.querySelectorAll('tr, h2, h3, h4, h5, p, img')
  const containerRect = ele.getBoundingClientRect()

  // 【优化1】同时收集元素的 top 和 bottom 坐标
  const breakPointsPx = Array.from(nodes).map((node) => {
    const rect = node.getBoundingClientRect()
    return {
      top: rect.top - containerRect.top,
      bottom: rect.bottom - containerRect.top,
    }
  })

  // 生成画布
  const canvas = await html2canvas(ele, {
    scale,
    useCORS: true, // 允许图片跨域
    backgroundColor: '#ffffff',
  })

  const imgDataUrl = canvas.toDataURL('image/jpeg', 1.0)

  // 初始化 PDF 对象：p-竖向，pt-点(单位)，a4-纸张规格
  const pdf = new jsPDF('p', 'pt', 'a4')
  const a4Width = pdf.internal.pageSize.getWidth()
  const a4Height = pdf.internal.pageSize.getHeight()

  // 计算图片缩放比例：根据宽度适配 A4
  const ratio = a4Width / canvas.width
  const imgWidth = a4Width
  const imgHeight = canvas.height * ratio

  // 将坐标单位从 px 转换为 pt (符合 PDF 内部计算)
  const breakPointsPt = breakPointsPx.map((bp) => ({
    top: bp.top * ratio,
    bottom: bp.bottom * ratio,
  }))

  const topMargin = 30 // 页眉预留
  const bottomMargin = 30 // 页脚预留
  const pageContentHeight = a4Height - topMargin - bottomMargin

  let currentRenderY = 0 // 已完成渲染的 Y 轴偏移

  while (currentRenderY < imgHeight) {
    let expectedPageBottom = currentRenderY + pageContentHeight
    let actualPageBottom = expectedPageBottom

    // 【优化2】判断是不是最后一页
    if (expectedPageBottom >= imgHeight) {
      actualPageBottom = imgHeight
    } else {
      // 只有不是最后一页，才去遍历判断是否被截断
      for (let i = 0; i < breakPointsPt.length; i++) {
        const { top, bottom } = breakPointsPt[i]

        // 【优化3】核心判断：元素的头在当前页，但尾巴超出了当前页的底部，说明被“腰斩”了
        if (top > currentRenderY && top < expectedPageBottom && bottom > expectedPageBottom) {
          actualPageBottom = top // 在被截断元素的顶部切一刀，将其整体推到下一页
          break
        }
      }
    }

    if (actualPageBottom === currentRenderY) actualPageBottom = expectedPageBottom

    // 1. 渲染当前页图像（利用负偏移显示指定区域）
    pdf.addImage(imgDataUrl, 'JPEG', 0, topMargin - currentRenderY, imgWidth, imgHeight)

    // 2. 顶部遮罩（覆盖负偏移区域产生的重叠部分）
    if (currentRenderY > 0) {
      pdf.setFillColor(255, 255, 255)
      pdf.rect(0, 0, a4Width, topMargin, 'F')
    }

    // 3. 底部遮罩（留白并遮挡截断处的残影）
    const currentRenderBottomY = topMargin + (actualPageBottom - currentRenderY)
    pdf.setFillColor(255, 255, 255)
    pdf.rect(0, currentRenderBottomY, a4Width, a4Height - currentRenderBottomY, 'F')

    currentRenderY = actualPageBottom

    // 如果还没画完，添加新的一页
    if (currentRenderY + 5 < imgHeight) {
      pdf.addPage()
    }
  }
  const fileName = title ? `${title}_${Date.now()}` : Date.now().toString()
  pdf.save(`${fileName}.pdf`)
}

用法案例

在 React 中使用该方案：

import { exportPdf } from './utils/pdf'

const ReportPage = () => {
  const handleDownload = async () => {
    try {
      // 传入容器 ID 和文件名
      await exportPdf('pdf-content', '月度分析报告')
    } catch (error) {
      console.error('生成 PDF 失败:', error)
    }
  }

  return (
    <div>
      <button onClick={handleDownload}>下载报告</button>

      {/* 这里的 ID 必须与 exportPdf 传入的一致 */}
      <div id="pdf-content" style={{ padding: '20px', background: '#fff' }}>
        <h2>报表标题</h2>
        <p>这里是很长很长的内容，可能会跨页...</p>
        <table>
          <tbody>
            <tr>
              <td>数据行 1</td>
            </tr>
            {/* 这里的 tr 会被防截断逻辑自动推送到下一页容器中 */}
            <tr>
              <td>数据行 2</td>
            </tr>
          </tbody>
        </table>
      </div>
    </div>
  )
}

PDF 模板架构

当项目中需要管理多个 PDF 模板时，建议采用“容器与显示分离”的架构，这样可以保证模板的纯净度（只负责 UI），同时方便在后台静默生成 PDF。

1. 目录结构

src/
  ├── components/
  │   └── pdf-templates/      # 所有的 PDF UI 模板
  │       ├── Contract.tsx    # 合同模板
  │       ├── Invoice.tsx     # 发票模板
  │       └── index.ts        # 统一导出
  └── utils/
      └── pdf.ts              # 核心 exportPdf 方法

2. 模板编写 (Pure UI)

模板组件应该只接收 data Props，不处理任何业务逻辑。

// src/components/pdf-templates/ContractTemplate.tsx
interface IProps {
  data: any
}

export const ContractTemplate = ({ data }: IProps) => (
  <div id="pdf-render-target" style={{ width: '800px', padding: '40px' }}>
    <h1>{data.title}</h1>
    {/* 自由编写复杂的 PDF 样式 */}
  </div>
)

3. 数据与导出流程

推荐在需要导出 PDF 的页面中，通过一个隐藏的“渲染容器”来实现。这样可以在不影响主页面 UI 的情况下，获取最新的业务数据并生成 PDF。

// src/pages/OrderDetails.tsx
import { useState } from 'react'
import { createPortal } from 'react-dom'
import { exportPdf } from '../utils/pdf'
import { ContractTemplate } from '../components/pdf-templates'

const OrderDetails = () => {
  const [isExporting, setIsExporting] = useState(false)
  const [data, setData] = useState(null)

  const startExport = async () => {
    setIsExporting(true)

    // 1. 获取业务数据 (如从 API 获取)
    const res = await fetchOrderData()
    setData(res)

    // 2. 等待 React 渲染 DOM (利用 setTimeout 确保渲染完成)
    setTimeout(async () => {
      try {
        await exportPdf('pdf-render-target', '业务合同')
      } finally {
        setIsExporting(false)
      }
    }, 100)
  }

  return (
    <div>
      <button onClick={startExport} disabled={isExporting}>
        {isExporting ? '正在生成...' : '下载 PDF'}
      </button>

      {/* 通过 Portal 将模板渲染在屏幕外，实现“无感”生成 */}
      {isExporting &&
        data &&
        createPortal(
          <div style={{ position: 'absolute', left: '-9999px', top: 0 }}>
            <ContractTemplate data={data} />
          </div>,
          document.body
        )}
    </div>
  )
}

4. 架构优势

• 关注点分离：页面只管触发，模板只管绘制，utils 只管转换。
• 数据解耦：PDF 模板的数据可以由父页面统一注入，也可以在 exportPdf 调用前按需加载。
• 用户无感：通过 createPortal 将渲染目标移出可视区域，用户在页面上感知不到“截图”的过程。

总结

前端里的 PDF 导出，本质上是三类方案：后端生成后前端下载、浏览器原生打印、前端自行截图并分页导出。不同场景没有绝对最优，关键是先判断你更看重的是开发成本、版式控制，还是最终体验。

如果只是拿到文件就下载，优先走后端；如果页面本来就接近打印稿，可以试试 window.print()；如果需要更强的模板控制和自动分页能力，html2canvas-pro + jsPDF 会更稳。项目一旦涉及多套 PDF 模板，最好尽早把模板、导出逻辑和业务页面拆开。

import Playground from ’../../../components/Playground.tsx’

在写 React 的时候，用的最多的就是 map 方法。这很经典，就不再记录了。

数组方法速查表

对数组的操作，有影响原数组的，也有不影响原数组的。

会修改原数组的方法

这类方法直接改变原数组，是新手最容易出错的点，记录时重点标注 “修改原数组”：

splice 用法

语法：array.splice(start, deleteCount, item1, item2, ...)

• start：开始的位置下标
• deleteCount：删除的数量
• item1, item2, ...：要添加的元素

<Playground client=“react” code={`let team = [‘Alice’, ‘Bob’, ‘Charlie’, ‘Diana’]

// 场景 1：单纯插入（在 Bob 和 Charlie 之,间插入 Eve） const removed1 = team.splice(2, 0, ‘Eve’) console.log(‘team:’, team) // [‘Alice’, ‘Bob’, ‘Eve’, ‘Charlie’, ‘Diana’] console.log(‘removed1:’, removed1) // [] (没有删除任何元素)

// 场景 2：单纯删除（删除最后一个成员 Diana） // -1 表示从倒数第一个元素开始，删除 1 个 const removed2 = team.splice(-1, 1) console.log(‘team:’, team) // [‘Alice’, ‘Bob’, ‘Eve’, ‘Charlie’] console.log(‘removed2:’, removed2) // [‘Diana’]

// 场景 3：替换（将 Bob 替换为 Frank 和 Grace） const removed3 = team.splice(1, 1, ‘Frank’, ‘Grace’) console.log(‘team:’, team) // [‘Alice’, ‘Frank’, ‘Grace’, ‘Eve’, ‘Charlie’] console.log(‘removed3:’, removed3) // [‘Bob’] (Bob 被替换出去了) `} />

fill 用法

语法：array.fill(value, start, end)

• value：要填充的值
• start：开始的位置下标
• end：结束的位置下标

<Playground client=“react” code={`let arr = [1, 2, 3, 4, 5]

// 它的意思是：用 0 填充从索引 1 开始，到索引 3 之前的位置 arr.fill(0, 1, 3)

console.log(arr) // [1, 0, 0, 4, 5] `} />

不会修改原数组的方法

这类方法返回新结果，原数组不变，易和 “修改原数组” 的方法混淆：

遍历与归并方法

无返回值 / 返回特定值，这类方法重点在 “遍历逻辑”，返回值易混淆:

reduce 用法

语法：array.reduce(callback(accumulator, currentValue, currentIndex, array), initialValue)

• callback：回调函数，接收四个参数：
  • accumulator：累计值
  • currentValue：当前元素
  • currentIndex：当前索引
  • array：原数组
• initialValue：初始值（可选）

<Playground client=“react” code={const arr = [1,2,3]; // 有初始值（推荐）：acc从0开始，cur依次为1、2、3 const sum1 = arr.reduce((acc, cur) => acc + cur, 0); // 6 console.log(sum1) // 无初始值：acc=1，cur=2 → acc=3，cur=3 → 最终6（空数组会报错） const sum2 = arr.reduce((acc, cur) => acc + cur); // 6 console.log(sum2) // 空数组无初始值会报错 const emptySum = [].reduce((acc, cur) => acc + cur); // TypeError} />

查找与判断方法

本文记录我在学习 React 的过程中，所认识到的一些与 useRef 相关的知识，如果其中有什么不对的地方，可以给我发邮件指正，或者在评论区留言，谢谢。

什么是 useRef

useRef 是一个 React Hook，它允许你引用一个不需要用于视图渲染的值。你可以把它生动地看作是一个在组件的整个生命周期内始终保持持久化的小盒子。

每一次调用，它都会返回一个包含 current 属性的可变对象。

const ref = useRef(initialValue)
// ref 的结构：{ current: initialValue }

核心特性

• 持久化存储：在组件的后续渲染中，useRef 将始终返回同一个对象引用。
• 不触发重渲染：更改 ref.current 属性不会触发组件的重新渲染。这使得它非常适合存储那些不影响视图的数据（如定时器 ID）。
• DOM 访问：最常见的用法是将其作为 ref 属性传递给 JSX 节点，React 会自动将 DOM 节点赋值给 current。

常见用法

在了解了 useRef 的基础之后，下面进入几个在实际业务里更常见的用法。

存储定时器 ID

因为 useRef 的变化绝不会触发重渲染，所以它天生就适合用来“藏”那些不需要影响 UI 显示的内部状态数据，比如定时器的 ID。

import { useRef } from 'react'

function MyComponent() {
  const intervalRef = useRef(null)

  useEffect(() => {
    intervalRef.current = setInterval(() => {
      console.log('设置定时器')
    }, 1000)

    // 清理函数
    return () => {
      clearInterval(intervalRef.current)
    }
  }, []) // 空依赖数组表示只在组件挂载时执行

  return <div>{/* 组件内容 */}</div>
}

获取列表 DOM

在 React 中，useRef 通常用于引用单个 DOM 元素。如果你需要获取一个列表（通过 .map() 渲染）中所有子元素的 DOM，不能简单地把同一个 ref 赋给它们，因为后面的元素会覆盖前面的。

最佳实践是使用 useRef 存储一个 Map 对象，并通过回调 Ref (Callback Ref) 将每个 DOM 节点存入这个 Map 中。

这种方法最稳健，因为它可以通过唯一的 ID 准确找到对应的 DOM，即使列表发生排序或增删，引用关系也不会乱。

import { useRef } from 'react'

function CatList() {
  const itemsRef = useRef(null)

  // 惰性初始化
  if (itemsRef.current === null) {
    itemsRef.current = new Map()
  }

  const cats = [
    { id: 1, name: 'Tom' },
    { id: 2, name: 'Jerry' },
    { id: 3, name: 'Garfield' },
  ]

  function scrollToCat(catId) {
    // 3. 使用 Map 获取指定 ID 的 DOM 节点
    const map = itemsRef.current
    const node = map.get(catId)

    if (node) {
      node.scrollIntoView({
        behavior: 'smooth',
        block: 'nearest',
        inline: 'center',
      })

      // 也可以做其他操作，比如改变样式
      node.style.backgroundColor = 'yellow'
      setTimeout(() => (node.style.backgroundColor = ''), 1000)
    }
  }

  return (
    <div>
      <nav>
        <button onClick={() => scrollToCat(1)}>找 Tom</button>
        <button onClick={() => scrollToCat(2)}>找 Jerry</button>
        <button onClick={() => scrollToCat(3)}>找 Garfield</button>
      </nav>

      <ul>
        {cats.map((cat) => (
          <li
            key={cat.id}
            // 2. 使用回调 Ref
            ref={(node) => {
              const map = itemsRef.current
              if (node) {
                // 挂载时：存入 Map
                map.set(cat.id, node)
              } else {
                // React18.x 卸载时：node 为 null，从 Map 中移除
                map.delete(cat.id)
              }

              // React 19 会在卸载时执行这个函数
              return () => {
                map.delete(cat)
              }
            }}
          >
            {cat.name}
          </li>
        ))}
      </ul>
    </div>
  )
}

export default CatList

自定义组件场景

如果你的列表项不是原生的 HTML 标签（如 <li>），而是自定义组件（如 <MyListItem />），你需要确保子组件使用了 forwardRef，否则 ref 无法透传到内部的 DOM 节点。

1. 子组件须使用 forwardRef 暴露 DOM：

import { forwardRef } from 'react'

const MyListItem = forwardRef((props, ref) => {
  return <li ref={ref}>{props.children}</li>
})

export default MyListItem

1. 父组件使用回调分配 Map 保持不变：

// ... map 循环中，将 ref 传递给自定义组件
<MyListItem
  key={cat.id}
  ref={(node) => {
    /* 和上面原生标签相同的 Map 存取逻辑 */
  }}
>
  {cat.name}
</MyListItem>

解决“闭包陷阱”

在 setTimeout、setInterval 或是原生事件监听器中，我们常常会遭遇一个令人头疼的问题：总是读取到“旧”的 State 值（也就是经典的闭包陷阱）。

import { useState, useRef, useEffect } from 'react'

function MessageSender() {
  const [message, setMessage] = useState('')

  // 关键：创建一个 Ref 来“镜像”最新的 message
  const latestMessageRef = useRef('')

  // 每次渲染，都把最新的 state 同步给 ref
  // 这步操作是同步的，且不会触发副作用
  useEffect(() => {
    latestMessageRef.current = message
  }, [message])

  const handleSend = () => {
    setTimeout(() => {
      // 错误写法：console.log(message); // 这里永远是3秒前的值（闭包陷阱）

      // 正确写法：读取 Ref
      alert(`发送消息: ${latestMessageRef.current}`)
    }, 3000)
  }

  return (
    <div className="p-4 border rounded">
      <h3>场景：解决异步闭包问题</h3>
      <input value={message} onChange={(e) => setMessage(e.target.value)} placeholder="输入消息..." />
      <button onClick={handleSend}>3秒后发送</button>
      <p className="text-sm text-gray-500">点击发送后，试着立刻修改输入框内容</p>
    </div>
  )
}

usePrevious：记录上次值

随着重新渲染，React 的机制只负责告诉你现在的 State 是多少，却不会主动保留“上一次”是多少。

import { useState, useEffect, useRef } from 'react'

// 封装成一个通用的 Hook
function usePrevious(value) {
  const ref = useRef()

  useEffect(() => {
    ref.current = value // 在渲染完成后，记录当前值，供下一次渲染使用
  }, [value])

  return ref.current // 返回的是“上一次”的值
}

function StockTicker() {
  const [price, setPrice] = useState(100)
  const prevPrice = usePrevious(price) // 获取上一次的价格

  // 计算趋势
  let trend = ''
  if (prevPrice && price > prevPrice) trend = '涨了'
  if (prevPrice && price < prevPrice) trend = '跌了'

  return (
    <div className="p-4 border rounded mt-4">
      <h3>场景：记录上一次的值</h3>
      <p>当前价格: ${price}</p>
      <p>上次价格: ${prevPrice}</p>
      <p>趋势: {trend}</p>

      <button onClick={() => setPrice((p) => p + 10)}>加价</button>
      <button onClick={() => setPrice((p) => p - 10)}>降价</button>
    </div>
  )
}

useUpdateEffect：跳过首渲染

众所周知，useEffect 默认在组件挂载（Mount）时也会执行一次。但很多时候，我们只想在数据更新（Update）时执行逻辑，也就是要静默跳过首次加载的触发。

import { useState, useEffect, useRef } from 'react'

function AutoSaveForm() {
  const [text, setText] = useState('')
  const isMountedRef = useRef(false) // 标记是否已经挂载

  useEffect(() => {
    // 如果是第一次渲染，将标记设为 true，然后直接结束
    if (!isMountedRef.current) {
      isMountedRef.current = true
      return
    }

    // 从第二次渲染开始，才会执行下面的逻辑
    console.log('正在保存草稿到服务器...', text)
  }, [text])

  return (
    <div className="p-4 border rounded mt-4">
      <h3>场景：跳过首次渲染 (AutoSave)</h3>
      <textarea value={text} onChange={(e) => setText(e.target.value)} placeholder="开始打字以触发自动保存..." />
    </div>
  )
}

useUpdateEffect Hook 写法

import { useState, useEffect, useRef } from 'react'

function useUpdateEffect(effect, deps) {
  const isMountedRef = useRef(false)

  useEffect(() => {
    if (!isMountedRef.current) {
      isMountedRef.current = true
      return
    }

    return effect()
  }, deps)
}

function MyComponent() {
  const [count, setCount] = useState(0)

  // 只在 count 更新时打印日志，首次渲染时不打印
  useUpdateEffect(() => {
    console.log('Count updated:', count)
  }, [count])

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  )
}

总结

useRef 的核心价值，不是“替代 state”，而是保存那些需要跨渲染保留、但又不该触发视图更新的数据。

如果只是操作 DOM，useRef 可以让你拿到元素实例；如果是处理定时器、异步回调、上一轮数据这类状态外信息，它又能提供一个稳定、可变的容器。把它用在合适的地方，代码会比“硬塞进 state”更自然，也更符合 React 的数据流设计。

序言

本博客使用的是 Astro 框架，使用静态模式生成的静态博客，这意味着博客内容，在构建的时候就已经固定了，需要更新内容的话，要重新构建。

如果使用的是 Vercel 或者 Netlify 部署，那么每次更新 Github 仓库的时候，都会自动触发一次构建，从而更新博客。

但是我把博客部署在了轻量云服务器上，这样就会出现一个问题，就是每次修改博客内容，都需要重新登录服务器，然后执行代码拉取、构建博客的，这样效率非常低，流程过于长。

这个时候就要请出 Github 的利器 Webhooks 来解决这个问题。

Webhooks

Webhooks 是 Github 提供的自动化服务，支持在仓库内容变动时，向指定 URL 实时推送 POST 请求，实现无需人工干预的自动处理。

这是一种“被动推送”机制，这种推送机制的核心特点：

• 实时：事件发生后几乎立刻推送，无需轮询。
• 自动：无需人工干预，自动处理。
• 灵活：可以自定义接收端的处理逻辑。

流程

通过上面的流程图，可以看到自动化部署的核心步骤：

1. Github 仓库内容变更（如 push、merge 等）；
2. Github Webhook 触发，向服务器发送 POST 请求；
3. 服务器接收 Webhook，执行自动化脚本（如拉取代码、安装依赖、构建、重启服务等）；
4. 部署完成，网站自动更新。

起飞

先从服务器开始，再到 Github 配置 webhook，先有服务，才能更好的配置。

准备工作

以下两种安装 nodejs 和 npm（已安装，可以忽略）的方法，选择其一即可。

• 普通安装方式：

sudo apt install nodejs npm -y

安装完后可以用下面命令检查版本：

node -v
npm -v

• 使用nvm安装：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 重新加载 shell
source ~/.bashrc
# 安装最新版 node（会自带 npm）
nvm install node

建目录

目录都在放 /var/www 中，你可以用自己的目录替代，以下都以此目录为基准。

www
├── project
├── webhooks
│   ├── log
│   ├── hookMain
│   └── sh

创建一个跟项目目录同级的 /var/www/webhooks 目录，用于放置 webhook 服务相关的文件和脚本。

cd /var/www
mkdir webhooks

创建三个子目录， log、hookMain、sh，log 用于保存日志，hookMain 用于存放 express 服务，sh 用于存放 bash 脚本。

cd webhooks
mkdir log
mkdir hookMain
mkdir sh

写脚本

进入 sh 目录，创建 deploy.sh:

cd sh
nano deploy.sh

写入以下内容：

#!/bin/bash
set -e

# 日志输出到指定目录
exec >> /var/www/webhooks/log/webhook.log 2>&1

echo "Starting deployment at $(date)"


cd /var/www/project
git pull origin master
npm install
npm run build

echo "Deployment completed at $(date)"

保存后赋予执行权限：

chmod +x /var/www/webhooks/sh/deploy.sh

写服务

进入 hookMain 目录，初始化 npm，并安装 express、dotenv：

cd hookMain
npm init -y
npm install express dotenv

创建 .env 文件，写入你的 GitHub Webhook 密钥（自定义，在创建 Webhook 时填写）

echo "WEBHOOK_SECRET=你的github密钥" > .env

创建 index.js，并写入以下内容：

require('dotenv').config()
const express = require('express')
const { exec } = require('child_process')
const crypto = require('crypto')
const app = express()

// 你在 GitHub 设置的密钥
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET

app.use(express.raw({ type: 'application/json' }))

// 验证签名函数
function verifySignature(signature, payload) {
  if (!signature) return false

  const expectedSignature = 'sha256=' + crypto.createHmac('sha256', WEBHOOK_SECRET).update(payload).digest('hex')

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))
}

app.post('/API', (req, res) => {
  const signature = req.headers['x-hub-signature-256']
  const payload = req.body

  // 验证签名
  if (!verifySignature(signature, payload)) {
    console.log('Invalid signature, rejecting webhook')
    return res.status(401).send('Unauthorized')
  }

  console.log('Webhook verified and received at:', new Date())

  // 解析 JSON 数据
  const body = JSON.parse(payload.toString())
  console.log('Repository:', body.repository?.name)
  console.log('Pusher:', body.pusher?.name)

  exec('/var/www/webhooks/sh/deploy.sh', (error, stdout, stderr) => {
    if (error) {
      console.error('Deploy error:', error)
    } else {
      console.log('Deploy success:', stdout)
    }
  })

  res.send('Deployment triggered')
})

app.listen(9001, '127.0.0.1', () => {
  console.log('Webhook server running on port 9001')
})

启动服务

安装pm2，并启动服务，设置开机自启动：

npm install -g pm2

pm2 start index.js --name webhook-server
pm2 save
pm2 startup

Nginx 反向代理

server {
    # 其他Nginx配置


    # 监听github的webhooks
    location /API {
    proxy_pass http://127.0.0.1:9001;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 其他Nginx配置
}

设置 Webhooks

1. 登录 GitHub，进入项目，点击 Settings，找到 Webhooks，点击 Add webhook。
2. 填写 Webhook URL，选择 Content type 为 application/json，输入 Secret（之前在 .env 中设置的），点击 Add webhook。

结尾

到这一步，使用webhooks实现自动化更新项目的流程全部完成。