d3-force-3d 构建时预计算 3D 网络布局，减少客户端渲染压力

前言

友链图谱 是一个汇聚了 1600+ 节点、2200+ 连接的 3D 友链网络可视化项目。数据源是 links/*.yml 文件，渲染层基于 3d-force-graph（Three.js + d3-force-3d）。

在上一篇文章中，我介绍了友链图谱从 2D 升级到 3D 的整体架构——包括 3D 力导布局的数学原理、节点渲染和高亮系统。但那时的方案是：构建时只输出数据，客户端自行跑力导仿真。

这个方案有两个痛点：

声明：本文在撰写过程中使用了 AI 工具辅助分析技术资料、整理踩坑经验及润色排版。

思路：构建时预计算位置

「既然 d3-force-3d 在客户端跑，那在构建时（Node.js）也跑一遍不就提前拿到位置了吗？」

d3-force-3d 官方文档明确支持这种做法：

simulation.tick() — "This method can be used in conjunction with simulation.stop to compute a static force layout."

于是我在 Astro API 端点 graph.json.ts 中加入了构建时预计算：

1
import { forceSimulation, forceLink, forceManyBody, forceCenter } from "d3-force-3d";
2

3
const sim = forceSimulation(nodes, 3) // 明确 3 维！
4
    .force(
5
        "link",
6
        forceLink(links)
7
            .id((d) => d.id)
8
            .distance(30),
9
    )
10
    .force("charge", forceManyBody().strength(-60))
11
    .force("center", forceCenter(0, 0, 0)) // 默认 strength=1
12
    .alphaDecay(0.02)
13
    .velocityDecay(0.3);
14

15
for (let i = 0; i < 300; i++) sim.tick();
16
sim.stop();

客户端改成加载预计算位置，直接冻结：

1
.cooldownTicks(0)
2
.cooldownTime(0)

然而……事情没那么简单。

踩坑 1：平面坍塌

跑出来的效果：

1
X: std=635  范围 [-1780, 1594]
2
Y: std=523  范围 [-2107, 1317]
3
Z: std=141  范围  [-200,  200]  ← 被压扁了！
4
3D ratio = 0.223  ⚠️ 扁平

Z 轴被压到只有 ±200，不管怎么调参数——distance=30 还是 40，charge=-60 还是 -120，alphaDecay=0.02 还是 0.005——Z 永远塌在初始半径以内。

原因：forceCenter(0,0,0) 的默认强度是 1.0，而 charge 只有 -60、link 只有 distance=30。center 力比其他力大了两个数量级，强行把所有节点往原点拉，Z 轴首当其冲被消解。

有趣的是，客户端渲染时同样的参数看起来却是"3D 网络"——因为客户端跑到 200 tick 就停了（cooldownTicks），还没收敛到平面，停在了一个好看的暂态。但构建时要的是一劳永逸，不能依赖"没跑完"。

踩坑 2：花哨尝试一一失败

每次调整都离目标差一点，走了很多弯路。

最终方案：三轴等强 + 弱居中

关键洞察是：不要对抗 forceCenter，而是把它减弱到和其他力一个量级。

1
const sim = forceSimulation(nodes, 3)
2
    .force(
3
        "link",
4
        forceLink(links)
5
            .id((d) => d.id)
6
            .distance(40),
7
    )
8
    .force("charge", forceManyBody().strength(-120))
9
    .force("center", forceCenter(0, 0, 0).strength(0.02)) // ← 关键！
10
    .alphaDecay(0.01)
11
    .velocityDecay(0.4);
12

13
for (let i = 0; i < 500; i++) sim.tick();
14
sim.stop();

为什么 0.02 有效？

strength=0.02 意味着每 tick 所有节点只向中心移动 2% 的距离。这刚好抵消整体漂移，但完全不足以压倒 link 和 charge 力。三种力在同一个量级上互相平衡，自然形成 3D 散布。

结果：

1
X: std=478  范围 [-1288, 1265]
2
Y: std=312  范围  [-640, 1315]
3
Z: std=357  范围 [-1076,  802]
4
3D ratio = 0.747  ✅ 良好的 3D 网络

三轴散布均衡，没有平面、没有球壳、没有圆盘，是一个真正的体积网络（volumetric network）。

客户端配置

客户端直接加载预计算位置，不再跑额外仿真：

1
.graphData(graphData)
2
.warmupTicks(0)
3
.cooldownTicks(0)
4
.cooldownTime(0)
5
.d3AlphaDecay(0.02)
6
.d3VelocityDecay(0.3);

注意 link 和 charge 力不能禁用（d3Force(null)），否则 3d-force-graph 的连线渲染会丢失。只要 cooldownTicks(0)，仿真在一 tick 后立即冻结，位置不会被挪动。

效果对比

总结

构建时预计算 3D 力导布局完全可行，关键不是"要不要用 forceCenter"，而是把 forceCenter 的强度降到和其他力一个量级。

项目仓库：xingwangzhe/FriendLinks — 欢迎 star 和 PR！

友链图谱在线体验：https://links.needhelp.icu/