D3 版本演进全解：从 D3 4.0 模块化到 D3 7.0 ES Modules 的重大变更

2026-09-06 11:31:44作者：冯爽妲Honey

Bring data to life with SVG, Canvas and HTML. :bar_chart::chart_with_upwards_trend::tada:

项目地址：https://gitcode.com/GitHub_Trending/d3/d3

D3 的 CHANGES.md 是一份聚焦"破坏性变更"的权威文档，它不按补丁级别展开，而是记录 D3 4.0、5.0、6.0、7.0 四个大版本中真正影响 API 与运行时的重大改动。本文以该文档为主干，逐版本还原每个里程碑的核心变更——命名空间扁平化、事件模型重构、原生集合与迭代器、Delaunay 替换 Voronoi、Promise 化数据加载、纯 ES Modules 交付——并结合当前仓库的 src/index.js、package.json、rollup.config.js 与 test/d3-test.js 等源码，说明这些变更是如何在工程层面落地和验证的。读完后，你将能够准确判断一段 D3 代码所处的版本世代，并在升级时定位每一处需要改写的 API。

文档定位：只讲重大变更，不讲补丁

CHANGES.md 开篇即声明其边界：

本文档只覆盖重大变更（major changes）。对于 minor 与 patch 级别的变更，请查看 release notes。

这一约束非常重要：它意味着本文档是一份"升级指南"而非"完整 changelog"。它只关心那些会让旧代码报错、改变行为或要求改写习惯的改动。文档按版本倒序组织，最新的 D3 7.0 在最前，逐层回溯到 D3 4.0。下文按此顺序逐版本展开，并在每个版本末尾用仓库源码佐证其交付形态。

D3 7.0：交付为纯 ES Modules，收紧空值与域值语义

D3 7.0 于 2021 年 6 月 11 日发布，是本仓库当前所处的版本世代（package.json 中 version 为 7.9.0）。相比前几个版本，7.0 的变更集中在"基础设施"与"边界语义"两个层面，改动点不多但影响深远。

交付形态：纯 ES Modules 与 Node.js 12+

D3 7.0 起以纯 ES modules（ESM）形式交付，并要求 Node.js 12 或更高版本。这一点在当前仓库中有直接证据：

package.json 中显式声明 "type": "module"，并在 "engines" 中锁定 "node": ">=12"，与文档所述完全一致。
package.json 的 "exports" 字段区分了两种入口："umd" 指向 ./dist/d3.min.js（面向 <script> 标签的 UMD 构建），"default" 指向 ./src/index.js（面向打包器的 ES module 源）。这正是"纯 ESM 交付"在包管理层面的体现。
入口文件 src/index.js 由 30 条 export * from "d3-xxx" 组成，逐模块转出 d3-array、d3-selection、d3-scale、d3-force 等微库的全部导出。这说明 D3 7.x 的"总包"本质上是一层 ESM 再导出，符号级别的可 tree-shaking 性正是依赖这种纯 ESM 结构。

这一形态由 rollup.config.js 进一步固化：该配置产出三套构建产物——UMD 版 dist/d3.js、ESM 版 dist/d3.mjs、以及用 terser 压缩的 dist/d3.min.js。值得注意的是压缩配置里 mangle.reserved 保留了 InternMap 与 InternSet 两个名字（见 rollup.config.js），它们与下面要讲的"序数域改用 InternMap"直接相关。

空值语义收紧：d3.bin、d3.ascending 与 d3.descending

7.0 对 null 的比较语义做了统一收紧：

d3.bin 现在会忽略 null 值（分箱时不再把 null 当作有效数据参与分箱）。
d3.ascending 与 d3.descending 不再认为 null 是可比较的值——排序比较器遇到 null 时的行为被明确改变。

这类改动的意义在于让空值在"排序 / 分箱"这类数值管道里表现更一致、更可预测，避免 null 被隐式参与数值比较而产生的意外顺序。

序数比例尺的域改用 InternMap

序数比例尺（ordinal scales）现在使用 InternMap 管理 domain，域值的去重方式从"通过 object.toString 强制转为字符串"改为"通过 object.valueOf 强制转为主值（primitive）"。

这一变化对以对象作为 domain 的序数比例尺有实际影响：两个 valueOf 返回相同主值的对象会被视为同一个域项，而与 toString 的表示解耦。配合 rollup.config.js 中保留的 InternMap 名字，可以确认 InternMap 是 7.x 中一个受支持、需要保持可读性的内部数据结构。

selectAll 对"类数组"的转换

形如元素 childNodes 这类"类数组"（array-like，例如一个活的 NodeList）现在会在 d3.selectAll 与 selection.selectAll 中被转换为真正的数组。这让 selectAll 可以直接接受 DOM 原生返回的类数组集合，无需调用方手动 Array.from，也让选择器与迭代器语义（见下一节 D3 6.0）保持一致。

D3 6.0：原生集合、迭代器与事件模型的整体重构

D3 6.0 于 2020 年 8 月 26 日发布，是四个大版本中改动面最广的一次。它围绕三条主线展开：拥抱 ES2015 原生能力、引入更强的高阶聚合函数、以及统一事件传递方式。文档同时提到，超过 450 个官方示例已更新到 D3 6.0。

主线一：使用原生集合并接受迭代器

D3 6.0 起使用原生 Map 和 Set，并且**接受迭代器（iterables）**作为输入。这条主线在仓库层面有清晰的落点：src/index.js 导出的 d3-scale、d3-selection 等模块的 3.x 版本（见 prebuild.sh 中 d3-scale.v4.js、d3-selection.v3.js 的复制）正是 6.0 世代对应的微库版本，而 D3 7.x 的总包继续以 Map/Set 语义运行。文档在多个模块章节反复出现"Accept iterables"，覆盖 d3-hierarchy、d3-scale、d3-selection（selection.data、d3.selectAll）、d3-shape 等，说明"可迭代输入"是贯穿 6.0 的统一契约。

主线二：d3.group / d3.rollup 取代 d3.nest

d3.group 与 d3.rollup 是 6.0 引入的强聚合函数，直接取代了旧的 d3.nest，并能与 d3-hierarchy、d3-selection 良好协作。这属于典型的"用原生集合 + 更简洁的 API 替换旧工具"的路径：旧的 d3.nest 被从核心中移除，d3.group/d3.rollup 成为一等公民。

与此同时，d3-array 新增了一批辅助函数，文档明确列举的代表包括：d3.greatest、d3.quickselect、d3.fsum，以及 d3.group/d3.groups、d3.index/d3.indexes、d3.rollup/d3.rollups、d3.maxIndex/d3.minIndex、d3.least/d3.leastIndex、d3.bin、d3.count、d3.cumsum、d3.Adder、d3.quantileSorted、bisector.center 等。此外还允许 d3.cross 接受超过两个可迭代输入，并让 d3.quantile 接受未排序输入。

主线三：事件直接传给监听器，移除 d3.event 全局

这是 6.0 最具"范式转移"色彩的改动：D3 现在把事件直接传给监听器，取代了全局的 d3.event，使 D3 与原生 JavaScript 及大多数框架保持一致。换句话说，监听器签名的第一个参数就是原生 event 对象，不再有"通过 d3.event 间接获取当前事件"的隐式约定。

这一改变波及所有会产生事件的模块。文档在各模块章节中反复出现同一句式："Change xxx.on to pass the event directly to listeners"，涉及 d3-selection 的 selection.on、d3-brush 的 brush.on、d3-drag 的 drag.on、d3-zoom 的 zoom.on、以及 d3-transition 的 transition.on。同时，d3-selection 移除了 selection.on 监听器中的 index 与 group 参数，并彻底删除了 d3.event、d3.mouse、d3.touch、d3.touches、d3.customEvent、d3.clientPoint、d3.sourceEvent 等旧全局，代之以新的 d3.pointer 与 d3.pointers。

图形与数值：d3-delaunay 取代 d3-voronoi

d3-delaunay（基于 Vladimir Agafonkin 的 Delaunator）取代了 d3-voronoi，在性能、健壮性与"最近点搜索"（find）上都有显著提升；同时社区另有面向球面地理数据的 d3-geo-voronoi。
d3-random 大幅扩充，并加入用于可复现随机性的快速线性同余生成器（linear congruential generator）。
d3-chord 新增有向（directed）与转置（transposed）和弦图布局。
d3-scale 新增一种 radial（径向）比例尺类型。

各模块变更要点

文档对 6.0 的改动按模块逐一列出，这里提炼与升级最相关的部分：

d3-brush：新增 event.mode；brush.on 改为直接传 event；改进多点触控交互。
d3-force：simulation.tick 新增 iterations 参数；新增 forceCenter.strength、forceSimulation.randomSource；所有内置力现在完全确定性（包括对"重合节点"的抖动处理）；force.initialize 现在会接收一个随机源；并改进了默认 phyllotaxis 初始布局（偏移半个半径）。
d3-format：默认负号从连字符 - 改为真正的减号 −；修复 d 对 ≥ 1e21 数值的十进制格式化。
d3-hierarchy：接受迭代器；node 现可迭代（node[Symbol.iterator]）；新增 node.find；node.each / eachAfter / eachBefore 现在会传入遍历索引；并修复了 d3.packSiblings 对超大圆、d3.treemapBinary 与 d3.treemapResquarify 的除零问题。
d3-interpolate：新增 interpolateZoom.rho；d3.piecewise 默认回退到 d3.interpolate；d3.interpolateTransformCss 改用 DOMMatrix 并要求绝对单位。
d3-scale：接受迭代器；新增 diverging.rangeRound、sequential.range、sequential.rangeRound、sequentialQuantile.quantiles、d3.scaleRadial；并修复了 continuous.nice、log.ticks、clamp（含序数量子尺度与"域值多于值域值"的连续尺度）等若干问题。
d3-selection：新增 selection.selectChild / selectChildren、d3.pointer / d3.pointers；selection 现可迭代（selection[Symbol.iterator]）；selection.data 与 d3.selectAll 接受迭代器；并修复 selection.merge(transition) 的错误。
d3-shape：接受迭代器；新增 d3.line(x, y)、d3.area(x, y0, y1)、d3.symbol(type, size) 等简写。
d3-time-format：新增 ISO 8601 周年符号 %G / %g。
d3-transition：新增 transition.easeVarying；transition 现可迭代；并修复 selection.transition（找不到要继承的命名 transition 时报错）与 transition.end（空选择时立即 resolve）。
d3-zoom：新增 zoom.tapDistance；zoom.on 直接传 event；默认 zoom.filter 在按下 Control 键时观察 wheel 事件；默认 zoom.wheelDelta 在按下 Control 键时加快；不再设置 touch-action: none。

破坏性变更清单

D3 6.0 明确引入了一批不向后兼容的变更，文档以独立小节列出，升级时务必逐项核对：

移除 d3.event；selection.on、transition.on、brush.on、drag.on、zoom.on 全部改为直接传 event。
移除 d3.mouse / d3.touch / d3.touches / d3.clientPoint，统一改用 d3.pointer / d3.pointers。
移除 d3.voronoi，改用 d3.Delaunay。
移除 d3.nest，改用 d3.group 与 d3.rollup。
移除 d3.map / d3.set / d3.keys / d3.values / d3.entries，改用原生 Map、Set 与 Object.keys / Object.values / Object.entries。
将 d3.histogram 重命名为 d3.bin；将 d3.scan 重命名为 d3.leastIndex。
d3.interpolateTransformCss 改为要求绝对单位；d3.format 的负值默认用减号而非连字符。

此外，D3 6.0 起要求浏览器支持 ES2015（旧浏览器需自带转译器），并且停止对 Bower 的支持——D3 只通过 npm 与 GitHub 发布。

D3 5.0：数据加载的 Promise 化与 Fetch 化

D3 5.0 于 2018 年 3 月 22 日发布。相比 4.0，5.0 的破坏性改动较少，但其中"数据加载"这一条对日常写代码的人影响最直接。

用 Promise 取代异步回调

D3 5.0 改用 Promise 而非异步回调来加载数据。文档给出了最典型的 CSV 加载对比——v4 的回调写法：

d3.csv("file.csv", function(error, data) {
  if (error) throw error;
  console.log(data);
});

在 v5 中用 Promise 重写：

d3.csv("file.csv").then(function(data) {
  console.log(data);
});

文档特别指出：不需要再手动 rethrow 错误——Promise 会自动 reject，需要时可自行 promise.catch。配合 await 则更简洁：

const data = await d3.csv("file.csv");
console.log(data);

d3-fetch 取代 d3-request，d3-queue 被移除

伴随 Promise 的引入，D3 改用 Fetch API 取代 XMLHttpRequest：d3-request 模块被 d3-fetch 取代。Fetch 支持流式响应等新特性。同时，D3 5.0 废弃并移除了 d3-queue 模块——文档建议用 Promise.all 并行执行一批异步任务，或用并发控制类工具库来管理并发度。

分类色板与 d3-scale-chromatic、d3-contour

D3 5.0 移除了 d3.schemeCategory20* 系列分类色板。文档给出的理由是这些二十色方案在设计上有缺陷：分组式配色会错误地暗示数据间关系（共享色相暗示"属于同一组"，明暗相对关系暗示"有先后"）。作为替代，D3 引入 d3-scale-chromatic，实现来自 ColorBrewer 的优色方案，涵盖 categorical、diverging、sequential 单色相与多色相，且都提供离散与连续两种形态。
新增 d3-contour，提供 marching squares（等值线）与密度估计的实现。
d3-selection 新增 selection.clone（插入所选节点的克隆）与 d3.create（创建游离元素）。
地理投影新增 projection.angle，支撑了若干新的多面体投影。

最后，D3 5.0 的 package.json 不再钉死各 D3 依赖模块的精确版本，以此修复 D3 模块"重复安装"的问题。这一点在当前仓库中同样可见：package.json 的 dependencies 里各 d3-xxx 均使用 ^ 范围约束（如 "d3-array": "^3.2.4"、"d3-scale": "^4.0.2"），而非精确版本，与文档所述一致。

D3 4.0：模块化拆分与命名空间扁平化

D3 4.0 于 2016 年 6 月 28 日发布，是四个大版本中"地基工程"最重的一次：它确立了微库化、扁平命名空间与 Rollup 打包的基本形态，而这些形态一直延续到当前的 D3 7.x。

模块化：从一个库变成许多小库

D3 4.0 的核心主张是模块化：D3 不再是一个单体库，而是由许多被设计为协同工作的小库组成，可按需取用；每个库有独立的仓库、独立的所有权与独立的发布节奏；默认包大约组合了三十个这样的微库。这一点在当前仓库里得到精确印证——package.json 的 dependencies 恰列出 30 个 d3-xxx 微库，而 src/index.js 也以 30 条 export * 与之逐一对应。

4.0 的另一个"不可避免的后果"是采用 ES6 模块后命名空间的扁平化：D3 4.0 里每个符号共享一个扁平命名空间，取代 3.x 的嵌套命名空间。典型例子是 d3.scale.linear 变为 d3.scaleLinear、d3.layout.treemap 变为 d3.treemap。采用 ES6 模块还意味着 D3 完全以 strict mode 编写，且"几乎所有 3.x 的代码都被重写"。

从打包角度，4.0 的微库以 ES6 模块编写，并借助 Rollup 做符号级的 tree-shaking 来产出更小包——这正是当前 rollup.config.js 仍用 Rollup（nodeResolve + json 插件，UMD/ESM/min 三产物）的原因。

Axes：默认样式 + 更短语法 + 四个方向构造函数

在 D3 3.x 中，要正确渲染坐标轴需要手动写一段 CSS（fill: none; stroke: #000; shape-rendering: crispEdges; 等），否则轴会渲染得"很丑"。D3 4.0 提供了默认样式与更短语法：不再使用 d3.svg.axis 与 axis.orient，而是为每个方向提供四个构造函数——d3.axisTop、d3.axisRight、d3.axisBottom、d3.axisLeft。这些构造函数直接接收比例尺，因此上面整段代码可简化为：

d3.select(".axis")
    .call(d3.axisBottom(x));

这一改动的视觉效果正是 CHANGES.md 用两张图对比呈现的：下图左为 3.x 需手动补样式时的观感，右为 4.0 默认样式 + 短语法后的观感（默认外观还做了半像素偏移，修复了 Safari 上轴被画成两像素宽的问题）：

此外 4.0 新增了 axis.tickArguments（可检查轴的 tick 参数）、axis.tickSize 只允许单参数设置、innerTickSize / outerTickSize 重命名为 axis.tickSizeInner / axis.tickSizeOuter。

Selections：不可变 + merge + 通用更新模式

D3 4.0 让 selection 变成不可变对象（不再是"通过原型链注入去子类化 Array"），性能更好，内部字段私有化，并新增 selection.nodes。selection.sort 与 selection.data 现在返回新的 selection 而非原地修改；selection.append 不再把 enter 节点并入 update selection。文档据此给出了"通用更新模式"在 3.x 与 4.0 的对照：

// D3 4.0：append 之后用 .merge(circle) 组合 enter 与 update
var circle = svg.selectAll("circle").data(data) // UPDATE
    .style("fill", "blue");

circle.exit().remove(); // EXIT

circle.enter().append("circle") // ENTER
    .style("fill", "green")
  .merge(circle) // ENTER + UPDATE
    .style("stroke", "black");

其他 4.0 的 selection 变化：selection.enter / selection.exit 在未 join 数据时返回空选择而非 TypeError；selection.append 默认把新元素插入到 update selection 中"后续元素"之前，从而保持 DOM 与数据的相对顺序；enter selection 成为与普通 selection 完全一致的"普通 selection"；重复 key 的数据现在总是进入 enter selection，使 enter/exit 行为对称。此外新增 selection.raise / selection.lower / selection.dispatch，并引入 d3.local（绑定到 DOM 元素的局部状态）。

Scales：band / point 取代 rangeBands / rangePoints

4.0 用两个新的序数子类替换了旧的 ordinal.rangeBands / rangeRoundBands 与 rangePoints / rangeRoundPoints：

// 3.x
var x = d3.scale.ordinal()
    .domain(["a", "b", "c"])
    .rangeBands([0, width]);

// 4.0：等价的 band scale
var x = d3.scaleBand()
    .domain(["a", "b", "c"])
    .range([0, width]);

band scale 提供 band.padding / paddingInner / paddingOuter、band.bandwidth / step 与 band.align；point scale 提供 point.padding，其 bandwidth 恒为零，并新增 point.step。分类色板也从"专用构造函数"变成"简单颜色数组"，例如 d3.scale.category10() 等价于 d3.scaleOrdinal(d3.schemeCategory10)。4.0 还引入了 sequential scale（用固定输出插值器而非 range），并内置了 viridis、inferno、magma、plasma 等插值器，配合 d3.quantize 也可用于 quantile / quantize / threshold 尺度。

Shapes：可渲染到 Canvas + 曲线 API + 符号类型 API + stack 重构

4.0 让形状不再局限于 SVG，可渲染到 Canvas：形状生成器支持可选 context（传入 CanvasRenderingContext2D 即可渲染为 canvas 路径）。文档给出的饼图片段：

var arc = d3.arc()
    .outerRadius(radius - 10)
    .innerRadius(0)
    .context(context);

// 对给定数据 d 渲染一段圆弧
context.beginPath();
arc(d);
context.fill();

底层上，形状通过 d3-path 在 context 为空时把 canvas 路径方法序列化为 SVG path 数据。4.0 还引入了 curve API（line.curve / area.curve 取代 interpolate），曲线以"curve 接口"实现而非返回 SVG 字符串的函数，从而可渲染到 SVG 或 Canvas；新增参数化的 Catmull-Rom 样条（d3.curveCatmullRom / Closed / Open）、d3.curveNatural（自然三次样条）、修复了 monotone 曲线的多个 bug 并引入 d3.curveMonotoneY。符号类型也改为"传符号对象而非字符串"（d3.symbolCircle、d3.symbolStar、d3.symbolWye 等），并彻底重构了 stack 布局 API（d3.stack 接受表格输入，stack.keys / order / offset 取代旧的 d3.layout.stack）。

Timers 与 Transitions：外部可停止 + 后台冻结时间

d3-timer：3.x 里定时器只能靠回调返回 true 来自终止；4.0 改为 timer.stop，使定时器无需自终止、可被外部停止，资源能被立即同步释放。文档示例：

var t = d3.timer(function(elapsed) {
  console.log(elapsed);
  if (elapsed >= 1000) {
    t.stop();
  }
});

4.0 还新增 timer.restart（保持调用优先级地重启 / 替换回调 / 改 delay 或参考时间），并把 d3.timer.flush 改名为 d3.timerFlush。更关键的是，4.0 通过在后台冻结时间来避免"页面回前台时成千上万个排队的 transition 同时执行"导致浏览器卡死——文档明确建议用 d3.interval 取代 setInterval 来周期性触发 transition。

d3-transition：selection.transition 现在可接受一个 transition 实例以与既有 transition 同步；链式 transition 的 delay 改为相对"前一个"transition；selection.interrupt 现在取消所有已排队的 transition 并立即释放资源；新增 d3.active（选取某节点当前活跃 transition，用于"无限往复"动画）。文档给出了用 d3.active 实现红蓝往复的完整示例。

其他模块的 4.0 变化（要点）

Colors：所有颜色暴露 color.opacity；d3.color 成为主解析入口；toString 返回 rgb()/rgba() 整数通道串；新增 d3.cubehelix 颜色空间与 color.displayable。
Dispatches：改为通用的 dispatch.call / dispatch.apply（类型作为首参），dispatch.on 接受多个类型名，新增 dispatch.copy。
Dragging：d3.behavior.drag 改名 d3.drag；drag.origin 由 drag.subject 取代；新增 drag.container、event.on、event.active、d3.dragEnable / d3.dragDisable。
DSV：CSV/TSV 各方法扁平化重命名（如 d3.csv.parse → d3.csvParse）；dsv.parse 暴露 data.columns。
Easings：从字符串标识改为符号（如 d3.easeCubicInOut），并为可参数化缓动提供命名参数（poly.exponent、elastic.amplitude / period、back.overshoot）。
Forces：d3.layout.force 改名 d3.forceSimulation；改用 velocity Verlet；力变得可扩展、可按节点/链接配置；新增 forceX / forceY、centering 与 collision 力；节点默认按 phyllotaxis 排布以避免不确定性；新增 alphaMin / alphaDecay / alphaTarget 等控温接口。
Quadtrees：d3.geom.quadtree 由 d3.quadtree 取代并彻底重写——非递归（避免大量重合点导致的栈溢出）、存储更省、更快；新增 visitAfter、remove / removeAll、copy / data / size / root、extent / cover，find 支持可选搜索半径。
Geographies / Time / Time-Formats / Voronoi / Zoom：同样遵循扁平化重命名（如 d3.geo.stream → d3.geoStream、d3.time.day → d3.timeDay、d3.time.format → d3.timeFormat），并各有行为增强（投影默认 clip、时间区间新增 interval.count 与自定义 d3.timeInterval、zoom 支持 translateExtent 平移约束与 transform.rescaleX 等）。

说明：以上各模块的逐条重命名与行为对照，均出自 CHANGES.md 对应小节；文档中提到的外部示例与迁移指南链接此处一律以文字概述代替，具体符号清单请以该文档为准。

仓库结构如何支撑这套演进

把四个版本放在一起看，CHANGES.md 描述的每次"交付形态"演进，都能在当前仓库的工程文件里找到对应的落地证据，形成"文档声明 → 源码实现 → 测试验证"的闭环：

ESM 交付（7.0）：package.json 的 "type": "module"、"exports"（umd → dist/d3.min.js，default → src/index.js）与 "engines": { "node": ">=12" }；src/index.js 的 30 条 export * 就是 ESM 再导出形态本身。
微库化（4.0 确立、7.x 延续）：package.json 的 30 个 d3-xxx 依赖（带 ^ 范围约束，印证 5.0 "不钉死精确版本"）与 src/index.js 一一对应；prebuild.sh 把各微库及其历史版本（d3-array.v3.js、d3-scale.v4.js、d3-time-format.v4.js 等）复制进 docs/public，用于文档站对照多版本 API。
构建产物：rollup.config.js 产出 UMD dist/d3.js、ESM dist/d3.mjs、压缩 dist/d3.min.js 三套，且保留 InternMap / InternSet 名字（呼应 7.0 序数域改用 InternMap）。
一致性测试：test/d3-test.js 遍历 package.json.dependencies 的每个模块，逐一 import 并断言其每个导出（除 version 外）都出现在 d3 命名空间里——这正是对"总包 = 各微库再导出"这一契约的自动化校验，也侧面印证了 4.0 以来"扁平命名空间 + 微库组合"的稳定结构。
测试入口：package.json 的 "test" 脚本为 mocha 'test/**/*-test.js' && eslint src test，说明 D3 以 mocha 跑测试、以 eslint 约束 src 与 test。

结语：如何把这份文档当作升级路线图

CHANGES.md 的价值在于它把"哪些改动会破坏你的代码"单独抽了出来。实用的读法是：

先定位世代：确认你的代码用的是回调还是 Promise（4/5 分界）、是否引用 d3.event（6 分界）、依赖 ESM 还是 UMD（7 分界）。
按版本倒查破坏项：升级跨 6.0 时重点处理事件签名（selection.on 等首参变 event）、d3.nest→d3.group/d3.rollup、d3.voronoi→d3.Delaunay；跨 5.0 时重点把数据加载改为 Promise/await；跨 4.0 时重点做扁平命名与 merge 通用更新模式。
用仓库源码核对：涉及交付与符号导出时，对照 src/index.js、package.json 与 test/d3-test.js；涉及构建与打包时对照 rollup.config.js。