Java3D三件套部署与排查：jar与native库对齐

简介：这套Java3D核心库面向Java三维图形编程初学者、课程学习者以及需要维护旧版Java3D项目的开发者，旨在补齐开发与运行三维场景程序所需的基础依赖，可用于场景图构建、几何变换、光照材质设置及与Swing组件集成等练习。压缩包共7个文件，以3个jar库为主体，分别承担核心渲染与场景图管理、向量矩阵运算、图像与工具扩展等职责，并配有2个dll本地运行库、1份rtf许可说明和1个html文档，整体约1.88MB，便于快速配置类路径与排查环境问题。已有428人学习下载，适合作为入门3D图形编程、复现教学案例和搭建旧项目环境的参考资料；借助这些库，读者还能对场景图节点层次、TransformGroup变换、DirectionalLight与PointLight光照、碰撞检测及纹理映射等关键概念进行动手验证，理解Java3D各模块的分工与调用关系。

1. 三个 java 3D 的 3d jar 包，缺一个就起不来

上周帮人恢复一个课程设计里的太阳系演示，代码本身没有改动，换了一台机器之后就在new Canvas3D(config)这一行报出UnsatisfiedLinkError。翻看lib目录才发现，对方只拷贝了j3dcore.jar，另外两个 jar 和 native 动态库都没有一起拷过来。Java3D 这套东西的常见问题主要来自它的交付方式：运行时被拆成核心场景图、工具集、向量数学库三部分，三个 jar 之间是单向依赖关系，再叠加上与版本一一对应的 native 库，任何一处版本对不上，都会在启动时直接失败。这篇记录针对的是这三件套的部署方式，面向需要让老项目重新运行、或者给课程演示补一个 3D 视图的开发者。它解决的是三个具体问题：jar 该怎么放进工程、native 库该怎么对齐、场景跑黑屏之后该从哪里查。API 本身并不复杂。

2. 三件套的职责边界：j3dcore、j3dutils、vecmath 各管什么

在讨论如何放置这三个 jar 之前，需要先说明它们各自负责什么、彼此之间的依赖方向。很多人把这三个包都塞进 classpath，程序仍然崩溃，是因为手上三个文件的版本来源不同，或者压根不是同一套发布包里的东西。

2.1 从一次 NoClassDefFoundError 看依赖链

j3dcore.jar是场景图和渲染管线的本体，包名javax.media.j3d，BranchGroup、TransformGroup、Canvas3D、View都在里面。它的编译期就引用了javax.vecmath下的类型：BoundingSphere的构造参数是Point3d，TransformGroup.setTransform参数是Transform3D，Transform3D内部又组合了Matrix4d和Quat4d。因此只放j3dcore.jar时，报错位置会出现在创建包围球的那一行，看起来像是核心库的问题，实际上是vecmath.jar没有被加载。

反向的依赖同样成立。j3dutils.jar的包名是com.sun.j3d.utils，SimpleUniverse继承自VirtualUniverse，TextureLoader返回javax.media.j3d.Texture，ColorCube、Sphere都是javax.media.j3d.Group的子类。所以依赖方向很明确：vecmath 在底层，j3dcore 依赖它，j3dutils 再依赖 j3dcore；三层单向下沉。我习惯在工程里放一个 30 行的探针类，启动前先跑一次，把每个类实际从哪个文件加载打印出来，这比用肉眼核对lib目录可靠得多。

public class DepCheck { public static void main(String[] args) { // 三个 jar 各取一个代表类，验证是否都能被加载，并打印来源路径 String[] probes = { "javax.vecmath.Point3d", // 来自 vecmath.jar "javax.media.j3d.BranchGroup", // 来自 j3dcore.jar "com.sun.j3d.utils.universe.SimpleUniverse" // 来自 j3dutils.jar }; for (String name : probes) { try { Class<?> clazz = Class.forName(name); String from = clazz.getProtectionDomain() .getCodeSource().getLocation().toString(); System.out.println("[OK] " + name + " <- " + from); } catch (Throwable t) { System.out.println("[FAIL] " + name + " : " + t); } } } }

getProtectionDomain().getCodeSource().getLocation()返回的是类被加载的那个 jar 的绝对路径，这一行信息在排查“是不是同时放了两个版本”时尤其有用。参数上没有什么可调的，唯一需要注意的是编译这个探针类时 classpath 里必须有三个 jar，否则Class.forName拿到的字符串虽然合法，但反射加载会失败。跑出来的结果如果三行全是[OK]且路径指向同一个目录，说明依赖层没问题；如果出现两个不同的目录，基本可以确定是版本混搭。

2.2 vecmath 里那些容易写反的变换顺序

vecmath.jar提供的是javax.vecmath包，常用类就五个：Point3d/Point3f表示位置，Vector3d/Vector3f表示方向，Matrix4d是 4×4 矩阵，Transform3D是封装好的刚体变换，Quat4d用于四元数插值。新手最常出错的地方是Transform3D.mul的方向：a.mul(b)的语义是a = a × b，而双参数的a.mul(b, c)才是a = b × c并且覆盖a的旧值。矩阵乘法不满足交换律，写反了就是“物体先平移再旋转”和“先旋转再平移”的区别，视觉上表现为模型绕着错误的轴转。

// 构造一个组合变换：先绕 Y 轴转 45 度，再沿 Z 轴后退 5 个单位 Transform3D rot = new Transform3D(); rot.rotY(Math.PI / 4); // 角度单位是弧度，不是度 Transform3D trans = new Transform3D(); trans.setTranslation(new Vector3d(0, 0, -5)); Transform3D combined = new Transform3D(); combined.mul(trans, rot); // combined = trans × rot，先转后移

需要注意rotY的参数是弧度，Math.PI / 4对应 45 度；如果有人写的rotY(45)就是 45 弧度，模型会转过一大圈后看起来原地不动。setTranslation接受的是Vector3d，如果直接传Point3d，编译期就会拒绝，这是有意为之的设计。另外，Transform3D有setScale、setRotation这些批量覆盖方法，一旦调用其中一个，之前的平移分量会被清零；我一般是在新建的Transform3D上按“缩放、旋转、平移”的顺序依次mul，而不是反复调用setXxx。

2.3 j3dutils 里那些“看着该在 core 里”的类

下表把三个 jar 里会用到的东西按出现频率列了出来，方便判断某个 import 找不到时应该去补哪个文件。

容易误判的典型情况有两种：看到SimpleUniverse不在javax.media.j3d下，就以为它是 JDK 自带；看到OrbitBehavior不在 core 里，就放弃鼠标交互，自己手写监听器。实际上鼠标旋转、缩放、平移三种交互j3dutils都已经封装好了，分别对应OrbitBehavior、MouseRotate、MouseZoom，后者属于com.sun.j3d.utils.behaviors.mouse包。只有涉及拾取和拖拽这类定制交互时，才需要自己继承Behavior编写。

2.4 版本对齐与 classpath 的组织方式

三个 jar 必须出自同一次发布。最常见的事故是有人从不同来源各拿到一个文件：vecmath.jar是 1.5.2 的，j3dcore.jar是 1.6.0 的，单独看都能加载，组合起来在调用Transform3D的新方法时抛NoSuchMethodError。判断办法就是 2.1 节的探针，看三个路径是否在同一目录。版本号本身不用纠结太多，比较流行的两个版本是 1.5.2 和 1.6.0，前者对老 JDK 更友好，后者在 JDK 8 上更稳定；如果工程要跑在 JDK 8 上，我会优先选 1.6.0。

classpath 的顺序其实不影响加载结果——只要类存在就会被找到——但会影响你排查问题时的直觉判断。我习惯固定写成vecmath.jar在前的顺序，并且在lib目录里只保留一套文件，不搞lib64、lib-backup这种平行目录，因为一旦有第二套文件存在，lib/*通配符就会把两套都装进来，加载到什么就变成了随机情况。

3. 把最小可运行场景跑起来：从 Canvas3D 到 SimpleUniverse

依赖关系理清之后就可以动手了。这一章的目标是得到一个能打开窗口、显示一个自转立方体的完整工程，把编译、运行、打包三步都走通，后面所有复杂场景都是在这个骨架上增加内容。

3.1 工程结构与依赖放置

我不太建议一上来就使用构建工具来拉取依赖，因为老版本的 Java3D 在公共仓库里的坐标经常变，而且 native 库不跟着 jar 走，依赖虽然齐全，运行时照样会失败。更稳妥的方式是手动建lib和native两个目录，编译和运行时显式指定参数。

demo3d/ ├── lib/ │ ├── vecmath.jar │ ├── j3dcore.jar │ └── j3dutils.jar ├── native/ │ ├── j3dcore-ogl.dll # Windows │ └── libj3dcore-ogl.so # Linux ├── src/ │ └── demo/Hello3D.java └── out/ # 编译输出，不存在时手动 mkdir

编译命令在 Windows 和 Linux 上只差一个分隔符，Windows 是分号，其余平台是冒号。-encoding UTF-8不要省略，老工程里的中文注释不少，源文件编码和默认编码不一致时javac会直接报错。

# Windows javac -encoding UTF-8 -cp "lib/*" -d out src/demo/Hello3D.java # Linux / macOS javac -encoding UTF-8 -cp "lib/*" -d out src/demo/Hello3D.java

-cp "lib/*"里的通配符由 JVM 自己展开，不需要手动写全每个 jar；但引号一定要加，否则 shell 会先把星号展开成一个文件列表，在文件多的时候反而出错。-d out指定输出根目录，包名demo会自动在out下建子目录。

3.2 第一个能转的立方体

下面这段是我常用的最小骨架，三十多行，包含场景图、变换组、插值器和视角设置，改颜色或者换模型都很方便。

package demo; import com.sun.j3d.utils.geometry.ColorCube; import com.sun.j3d.utils.universe.SimpleUniverse; import javax.media.j3d.*; import javax.vecmath.Point3d; public class Hello3D { public Hello3D() { // 1. 创建 SimpleUniverse，内部会建好 Locale、ViewingPlatform 和 Canvas3D SimpleUniverse universe = new SimpleUniverse(); // 2. 变换组，必须显式打开写权限，否则插值器运行时抛 CapabilityNotSetException TransformGroup tg = new TransformGroup(); tg.setCapability(TransformGroup.ALLOW_TRANSFORM_WRITE); tg.setCapability(TransformGroup.ALLOW_TRANSFORM_READ); // 3. 立方体边长 1.0，默认居中原点 tg.addChild(new ColorCube(1.0)); // 4. 旋转插值器：-1 表示无限循环，4000 是周期毫秒 Alpha alpha = new Alpha(-1, 4000); RotationInterpolator rotator = new RotationInterpolator(alpha, tg); // 5. 调度范围必须覆盖物体，默认包围球太小会导致行为被裁掉 BoundingSphere bounds = new BoundingSphere(new Point3d(0, 0, 0), 100.0); rotator.setSchedulingBounds(bounds); // 6. 组装：根节点 -> 变换组 -> 立方体，行为挂在变换组上 BranchGroup root = new BranchGroup(); root.addChild(tg); tg.addChild(rotator); root.compile(); universe.addBranchGraph(root); // 把相机拉到 z 正方向约 2.4 处，正好框住 -1 到 1 的物体 universe.getViewingPlatform().setNominalViewingTransform(); } public static void main(String[] args) { System.setProperty("sun.awt.noerasebackground", "true"); new Hello3D(); } }

几个参数值得单独说明。Alpha(-1, 4000)的第一个参数是循环次数，-1表示无限循环，第二个参数是单圈周期，单位毫秒；把它改成1000就是每秒一圈，改成20000就是慢速自转。RotationInterpolator默认绕 Y 轴从 0 转到 2π，如果需要指定轴向，用四参数构造版本传入自定义的Transform3D和起止弧度。setNominalViewingTransform()把相机放在能看到 z 轴 -1 到 1 这段空间的位置上，物体超出这个范围就看不见，新手以为渲染失败，其实是被裁剪掉了。

3.3 native 库的加载与 java.library.path

j3dcore.jar里有一部分方法是native的，具体实现放在j3dcore-ogl.dll（Windows）、libj3dcore-ogl.so（Linux）或.jnilib（macOS）里。JVM 找不到它时抛的UnsatisfiedLinkError: no j3dcore-ogl in java.library.path是整个部署流程里出现频率最高的错误。解决办法是把 native 目录通过-Djava.library.path传进去。

# Windows java -cp "out;lib/*" -Djava.library.path=native demo.Hello3D # Linux / macOS java -cp "out:lib/*" -Djava.library.path=native demo.Hello3D

路径参数写相对路径时可以正常使用，因为 JVM 会按启动时的工作目录解析；但一旦把程序打成可执行 jar 分发出去，相对路径就会以用户双击时的工作目录为准，基本必失败。稳妥一点的做法是在main方法最前面调一次System.load，把动态库从 jar 内解压到临时目录再加载。另外一个细节是位数必须匹配：64 位的 JVM 只能加载 64 位的 dll，32 位的 javaw 配 64 位库会直接报Can't load IA 32-bit .dll on a AMD 64-bit platform，这个错误信息和UnsatisfiedLinkError长得很像，但原因完全不同。

3.4 打成分发 jar 时的 manifest 写法

要交给别人运行，就得把 classpath 写进MANIFEST.MF的Class-Path。这里有个容易出问题的地方：manifest 的每一行都不能超过 72 字节，超过的部分要在下一行以一个空格开头续写，换行符必须是 CRLF。

Manifest-Version: 1.0 Main-Class: demo.Hello3D Class-Path: lib/vecmath.jar lib/j3dcore.jar lib/j3dutils.jar SplashScreen-Image: res/splash.png

Class-Path里的多个条目用空格分隔，路径相对于 jar 自身所在目录，这一点和-cp的相对路径语义不一样，很多人在这里出错：用-cp时相对当前工作目录，写进 manifest 之后相对 jar 文件位置。另外Main-Class指定的类必须带完整包名且不能带.class后缀。如果条目多到需要折行，续行开头那个空格是语法的一部分，编辑器自动去掉行尾空白时会把这一行清空，jar 就打不开了。

4. 场景图与行为：把静态模型变成能动的东西

骨架跑通之后，下一步是让场景有交互。Java3D 的场景图是一棵树，所有动态修改都要通过 capability 位预先授权，理解这套约束比记住 API 名字更重要。

4.1 BranchGroup 与 TransformGroup 的挂载规则

场景图里有两种容器：BranchGroup是挂载点，可以整体插入或移除；TransformGroup持有变换矩阵，用来定位子节点。一棵典型的树是Locale → BranchGroup → TransformGroup → Shape3D，行为节点可以挂在任意Group下面。这里有两类权限需要区分清楚：setCapability是运行时修改属性的许可，ALLOW_CHILD_REMOVE是运行时增删子节点的许可。transformGroup.setTransform(...)报CapabilityNotSetException，就是因为没有提前打开ALLOW_TRANSFORM_WRITE。

BranchGroup root = new BranchGroup(); root.setCapability(BranchGroup.ALLOW_DETACH); // 允许从场景中整体摘除 root.setCapability(BranchGroup.ALLOW_CHILD_REMOVE); // 允许移除子节点 TransformGroup tg = new TransformGroup(); tg.setCapability(TransformGroup.ALLOW_TRANSFORM_WRITE); tg.setCapability(TransformGroup.ALLOW_TRANSFORM_READ); // 摘除时必须先脱离父节点，直接 detach 会在下次渲染时抛异常 root.detach();

ALLOW_DETACH只在根BranchGroup上才有意义，挂在TransformGroup上不会生效。摘除节点的顺序是先detach()再丢弃引用，否则对象还挂在活的场景图里，只是你手上没有指针了，内存不会释放；这类泄漏在频繁切换模型的演示程序里很常见，切换十几次之后帧率就会明显下降。

4.2 插值器不动的三个常见原因

RotationInterpolator写好之后物体不转，绝大多数情况可以归到三类原因上。第一是SchedulingBounds缺失或者范围太小，行为只在包围球范围内生效，相机一旦移出范围，行为就停止；第二是Alpha的周期参数写成了 0 或者负数以外的值，导致插值区间异常；第三是行为节点挂错了位置，挂在了BranchGroup上而不是带动画的TransformGroup上，于是转的是根节点而不是模型。

Alpha alpha = new Alpha(-1, Alpha.INCREASING_ENABLE, 0, 0, 4000, 0, 0, 0, 0, 0); TransformGroup spin = new TransformGroup(); spin.setCapability(TransformGroup.ALLOW_TRANSFORM_WRITE); RotationInterpolator rotator = new RotationInterpolator(alpha, spin); // 调度范围要比场景实际尺寸大一圈，留出相机移动余量 rotator.setSchedulingBounds(new BoundingSphere(new Point3d(), 500.0)); rotator.setEnable(true); // 默认就是 true，但复用时记得手动打开 spin.addChild(rotator);

Alpha.INCREASING_ENABLE这个参数控制插值曲线，默认的线性递增用两参数构造就够；需要“转过去再转回来”的往复效果时，把INCREASING_ENABLE | DECREASING_ENABLE都打开，并分别给出加速、匀速、减速三段的时长。setEnable(false)是暂停行为最轻量的做法，不需要从场景图里摘节点，恢复时再置回true即可，比反复detach/addChild省事得多。

4.3 纹理与 Appearance 的参数组合

给Shape3D上纹理要同时设置三处：Appearance上的TextureAttributes、PolygonAttributes，以及Shape3D本身的Texture。纹理图片通过TextureLoader读入，注意它的第二个参数byReference，传false表示把像素数据完整读进内存，传true则是在渲染时才去读原文件，前者更安全，后者在文件被移动后会变成白模。

TextureLoader loader = new TextureLoader("res/brick.jpg", null); Texture texture = loader.getTexture(); texture.setBoundaryModeS(Texture.WRAP); texture.setBoundaryModeT(Texture.WRAP); TextureAttributes ta = new TextureAttributes(); ta.setTextureMode(TextureAttributes.MODULATE); // 纹理与材质颜色相乘 PolygonAttributes pa = new PolygonAttributes(); pa.setCullFace(PolygonAttributes.CULL_NONE); // 双面可见，避免单面渲染背面消失 Appearance app = new Appearance(); app.setTexture(texture); app.setTextureAttributes(ta); app.setPolygonAttributes(pa);

MODULATE是纹理色与材质色相乘，想要纹理原样显示就设成REPLACE，两者在暗色材质上的差异很明显。CULL_NONE会带来大约一倍的填充开销，只在模型有薄面或者需要看到内壁时打开，正常封闭模型保持默认的CULL_BACK。如果纹理贴上去是纯白色，先检查图片路径是不是相对工作目录而不是相对 classpath，TextureLoader的字符串参数走的是文件系统路径。

4.4 compile() 的时机与代价

BranchGroup.compile()会把子树整理成渲染器友好的内部结构，能明显提升静态场景的绘制效率。代价是编译之后不能再增删子节点，只能修改带 capability 的属性。判断标准很简单：这个子树里的结构在运行期会不会变。会变的（比如此起彼伏的粒子、动态添加的模型）就别编译；纯展示的静态背景、地形、模型本体，编译之后帧率通常有肉眼可见的提升。

提示：对还没有加入Locale的BranchGroup调compile()是安全的，但对已经 live 的节点调会抛IllegalStateException。顺序是先组装、编译，最后addBranchGraph。

5. 避坑与排查：三件套部署里最容易翻车的五件事

下面五条都是我实际遇到过、并且能在十分钟内定位的问题。每条按现象、原因、解决三段写，遇到同类报错时可以直接对号入座。

5.1 UnsatisfiedLinkError：库名对但路径不对

现象是启动即崩，堆栈第一行是java.lang.UnsatisfiedLinkError: no j3dcore-ogl in java.library.path。原因有两类：一是 native 目录根本没通过-Djava.library.path传进去，JVM 只在默认路径里找；二是传了但文件名不匹配，比如把j3dcore-ogl.dll改名成了j3dcore.dll，JVM 按固定名字加载，改了名就找不到。解决办法是先打印一次实际搜索路径确认参数生效，再把文件名和平台位数对齐。

// 放在 main 方法第一行，启动时打印 JVM 实际搜索的 native 路径 System.out.println("library.path = " + System.getProperty("java.library.path")); System.out.println("os.arch = " + System.getProperty("os.arch"));

os.arch输出amd64说明是 64 位 JVM，此时lib目录里必须是 64 位的动态库。如果确认路径和文件名都对，还有一种少见情况：Linux 上动态库缺少依赖的.so文件，ldd libj3dcore-ogl.so会列出not found的条目，补齐系统库即可。

5.2 窗口打开但一片黑

现象是窗口正常弹出、标题栏也在，客户区就是纯背景色，转动物体看不见。原因按概率排：相机位置没有设置，默认视角在原点附近，物体可能整个在背后；场景里没有光源，纯几何体在无光照材质下渲染成黑色；或者ViewingPlatform的setNominalViewingTransform没有调用。解决办法是依次加一个AmbientLight、调一次视角、再确认BranchGroup确实addBranchGraph过。

BoundingSphere worldBounds = new BoundingSphere(new Point3d(), 1000.0); AmbientLight ambient = new AmbientLight(true, new Color3f(1f, 1f, 1f)); ambient.setInfluencingBounds(worldBounds); DirectionalLight dir = new DirectionalLight(true, new Color3f(1f, 1f, 1f), new Vector3f(-1f, -1f, -1f)); dir.setInfluencingBounds(worldBounds);

AmbientLight的第一个参数是Color3f而不是int颜色值，这点和 AWT 的习惯不同。光源同样需要setInfluencingBounds，范围没覆盖到物体时光源等于不存在，症状和没加光源一模一样。

5.3 嵌进 Swing 之后白块或卡死

现象是把Canvas3D放进JFrame的ContentPane之后，要么整块白，要么窗口拖动时画面撕裂。原因是重绘时序和 AWT 的默认擦除行为冲突。我一般先关掉 AWT 背景擦除，再给Canvas3D单独套一个BorderLayout容器，最后设置setDoubleBufferEnable(true)。

System.setProperty("sun.awt.noerasebackground", "true"); JFrame frame = new JFrame("3D"); frame.getContentPane().setLayout(new BorderLayout()); GraphicsConfiguration config = SimpleUniverse.getPreferredConfiguration(); Canvas3D canvas = new Canvas3D(config); canvas.setDoubleBufferEnable(true); frame.getContentPane().add(canvas, BorderLayout.CENTER);

getPreferredConfiguration()会挑选支持 3D 的GraphicsConfiguration，如果直接用默认配置，某些集成显卡上拿不到硬件加速，就会退化成软件渲染，帧率掉到个位数。setDoubleBufferEnable必须在Canvas3D加入容器之前调用，加进去之后再改不生效。

5.4 高 DPI 下画面只画左下角

现象是在 4K 屏或者缩放比例 150% 的显示器上，画面只占据窗口左下角一小块，其余部分是空白。原因是Canvas3D拿到的是逻辑像素尺寸，而渲染器按物理像素绘图，两者比例不一致。解决办法是在创建画布后手动同步Screen3D的尺寸，或者给 JVM 加上 UI 缩放参数。

Canvas3D canvas = new Canvas3D(config); Screen3D screen = canvas.getScreen3D(); // 物理尺寸按 96 DPI 折算，配合系统缩放比例使用 screen.setSize(1920, 1080); screen.setPhysicalScreenWidth(0.0254 * 1920 / 96.0); screen.setPhysicalScreenHeight(0.0254 * 1080 / 96.0);

setSize的单位是像素，setPhysicalScreenWidth的单位是米，按 96 DPI 折算就是每英寸 0.0254 米。这两个值必须成比例，只改一个会导致视角被拉伸变形。如果程序需要跨不同缩放的机器分发，更省事的做法是启动参数里加-Dsun.java2d.uiScale=1.0，放弃高 DPI 适配换取渲染正确。

5.5 混版本导致的 ClassCastException

现象是代码编译通过、运行时在某个类型转换处抛ClassCastException或者NoSuchMethodError，报错信息里出现的类名和你 import 的完全一样。原因是 classpath 里有两份同名类，分别来自不同版本的 jar，JVM 按加载顺序取了其中一份，而另一份里的配套类型来自另一个版本。解决办法是用 2.1 节的探针确认来源，把lib目录清理成单一套，并检查打包脚本里有没有把依赖复制两遍。

注意：用lib/*这种通配符时，目录里任何残留的.jar都会被加载，包括j3dcore.jar.bak被系统重命名产生的备份文件，也常被误认为.jar。

6. 进阶：用一个帧率探针验证三件套是否真的生效

判断部署是否成功，不该只看“窗口有没有出来”，而要看渲染管线有没有在持续出帧。我常用的办法是继承Canvas3D，在postSwap()里做计数，每秒打印一次帧率。这个方法不依赖额外工具，也不需要改场景代码，把Canvas3D的创建换掉即可。

public class ProbeCanvas3D extends Canvas3D { private long windowStart = System.nanoTime(); private int frames = 0; public ProbeCanvas3D(GraphicsConfiguration config) { super(config); setDoubleBufferEnable(true); // 不开启双缓冲，postSwap 不会被稳定回调 } @Override public void postSwap() { super.postSwap(); // 必须调用父类，否则画面不刷新 frames++; long now = System.nanoTime(); if (now - windowStart >= 1_000_000_000L) { System.out.println("FPS = " + frames); frames = 0; windowStart = now; } } }

postSwap()是每帧前后台缓冲交换完成后回调的钩子，重写时必须先调super.postSwap()，否则交换动作被覆盖，画面会停留在首帧。窗口大小固定为 1 秒，1_000_000_000L换算成毫秒就是一秒，改小到 500 毫秒可以让读数更灵敏。跑起来之后，静止不动的场景在独立显卡上应该是 60 左右，如果只有个位数，说明GraphicsConfiguration没拿到硬件加速，回到 5.3 节检查配置获取方式。

再补一个环境自检的小习惯：程序启动时把三个 jar 的来源、native 路径、os.arch和 JVM 版本一次性打印到日志。看着啰嗦，但下一次换机器出问题时，这四行信息能把定位时间从半天压缩到几分钟。血泪经验是版本问题从来不报“版本错误”，它报的是某个看起来毫无关联的空指针或者类型转换失败。

从那以后我每次拿到一个 Java3D 老工程，都先跑一遍依赖探针再谈业务逻辑，源码一行不改也能先判断出是环境问题还是代码问题。希望帮到你。

本文还有配套的精品资源，点击获取