如何让Scene Builder开发的JavaFX应用使用指定分辨率并解决适配问题

常见诱因 #

• 高DPI系统缩放冲突：28801800属于高分辨率屏幕，Windows/macOS系统默认会开启125%~150%的全局缩放倍率，旧版本JavaFX（Java 8及更早）的高DPI适配逻辑不完善，会将设置的19201080逻辑像素乘以系统缩放倍率转为物理像素，比如150%缩放时实际物理尺寸会变为2880*1620，再叠加系统窗口标题栏、边框的高度，总窗口高度会超出屏幕可视区域，导致显示异常。
• Stage与Scene尺寸不匹配：如果仅在Scene Builder中设置了根容器的prefWidth/prefHeight为1920*1080，运行代码时没有同步设置Stage的尺寸适配逻辑，或者Stage保留默认的decorated属性（带系统标题栏边框），会挤压Scene的实际渲染区域，导致内容显示不全。
• 布局自适应属性未配置：若根容器未设置maxWidth/maxHeight为USE_COMPUTED_SIZE，或内部布局未绑定窗口尺寸变化监听，窗口尺寸变化时内部内容不会同步调整，会出现内容溢出或大面积留白的问题。

修复方案 #

• 强制关闭JavaFX高DPI自动缩放：启动应用时添加JVM参数，直接禁用高DPI缩放逻辑，让1逻辑像素对应1物理像素，固定分辨率场景优先使用该方案：
  -Dprism.allowhidpi=false
• 代码层面适配系统缩放：初始化Stage时主动获取系统缩放倍率，动态调整Scene的逻辑尺寸，适配不同缩放比例的屏幕：

import javafx.stage.Screen;

// 获取系统缩放倍率
double scale = Screen.getPrimary().getOutputScaleX();
// 初始化Scene时自动适配缩放
Scene scene = new Scene(root, 1920 / scale, 1080 / scale);
stage.setScene(scene);
stage.show();

• 开启布局自适应：在Scene Builder中将根容器的maxWidth、maxHeight属性设置为USE_COMPUTED_SIZE，运行时绑定根容器尺寸与Scene尺寸，实现窗口缩放时内容同步适配：

root.prefWidthProperty().bind(scene.widthProperty());
root.prefHeightProperty().bind(scene.heightProperty());

内容的提问来源于stack exchange，提问作者mkip