简介这份jxbrowser-7.19整合包面向需要在Java桌面应用中嵌入浏览器内核的开发者适合Swing、SWT、JavaFX项目以及Windows、Linux、macOS含ARM多平台交付场景可用于解决网页渲染、JS交互与跨端组件集成问题。压缩包共1359个文件约437.21MB主体为1345个HTML格式的Javadoc文档另含10个各平台JAR、示例Browser.java及少量前端资源便于按模块查阅API和直接接入指定容器组件。已有2599人学习下载。借助完整版Javadoc、分平台依赖与Browser.java示例读者可快速定位类与方法、核对版本配套关系并参考示例完成浏览器视图初始化、容器嵌入及跨平台依赖选择减少自行拼包和排查兼容问题的时间。1. jxbrowser 7.19 值不值得下Swing 老壳要跑现代前端时的最后一张牌上周又有人来问客户端里嵌运营后台还有没有别的路。他那边情况很典型七八年的老客户端页面从 jQuery 换到 Vue 3JEditorPane打开直接白屏JavaFX 的 WebView 碰到可选链和??就报语法错换壳成本又压不下来。这时候 jxbrowser java 这条路就会被重新翻出来——它把完整的 Chromium 以独立进程方式嵌进 JVM页面在真内核里跑JVM 只管窗口和胶水代码。7.19 是 7.x 这条线上网上能找到的最新版属于收尾版本API 已经定型坑也基本被人踩完反而比追新版本更适合拿去落地。适合谁桌面壳不能动、必须渲染现代前端、能接受商业授权的项目不适合只贴一段静态 HTML或者新项目一开始就奔着新主版本去的情况。2. 拆包先看结构7.19 的 artifact 分工与运行前提拿到一个几十上百兆的压缩包最忌讳的是直接扔进 IDE 跑个main看它报什么错。7.x 的依赖结构和 6.x 完全不是一回事核心包和平台包是分开的先搞清楚哪几个 jar 是必须的能省掉后面一半的排查时间。2.1 核心包与平台包五个 artifact 各管什么jxbrowser这个 artifact 里只有 Java API、事件定义和跨进程通信的胶水没有 Chromium 内核。真正让页面渲染起来的是平台包它按操作系统和架构拆成好几个你得按目标平台挑。加上 Swing/SWT 的视图适配层一个能跑的最小组合通常是三个 jar。artifact里面是什么什么时候必须加jxbrowserJava API、回调和事件模型不含内核永远jxbrowser-win64Windows x64 的 Chromium 二进制目标平台是 Windows 64 位jxbrowser-linux64Linux x64 的 Chromium 二进制部署在 Linux 桌面或瘦客户端jxbrowser-mac/jxbrowser-mac-arm64macOS Intel / Apple Silicon有 Mac 用户jxbrowser-swing/jxbrowser-swt把 Browser 画进 Swing / SWT 容器的 View用 Swing 或 SWT判断自己有没有拿全最快的办法不是看名字是看体积核心包只有几百 KB 到一两 MB平台包是几十到上百 MB。如果解压出来所有 jar 都只有一两兆那八成是只拿到了 core 或者被人重新打包过。另外如果你的发行方式是 fat jar把三个平台的二进制全塞进去安装包会直接膨胀两三倍常见做法是用 Maven profile 按平台分开打构建机上出三份产物。提示依赖里出现多个平台包不会导致启动失败但会让启动时的目录扫描变慢也容易在打包工具里被误删能按平台切就按平台切。2.2 运行前提JDK、系统版本与目录权限7.x 这条线对 JDK 8 是友好的这也是很多人明知道有新主版本还留在 7.19 的原因——手上的老客户端跑在 JDK 8 上升 JDK 的排期比引一个浏览器组件还长。但这个友好有边界系统层面该满足的还得满足否则现象会非常迷惑进程起来了窗口也有了就是一片白。项要求说明JDK8 及以上7.x 线不强制 11这是它相对新主版本的主要优势WindowsWin10 及以上7.19 内置的 Chromium 版本已经不照顾 Win7别在这上面浪费时间Linux需要libnss3、libatk、libgbm、libasound2等运行库缺库的表现是进程秒退日志里能看到 loader 报错磁盘用户数据目录可写预留几百 MB内核解压、缓存、GPU 缓存都落在这里目录路径尽量不含中文和空格解压和加载本地资源时容易出玄学问题Linux 上缺库这条特别值得单独说。容器化部署的时候基础镜像里往往只有 JREChromium 需要的那一堆.so一个都没有现象就是Engine.newInstance直接抛异常堆栈里全是 native 加载失败。我的习惯是上线前在一台干净的目标机上先跑一次引擎初始化跑通了再谈业务代码。2.3 最小可运行工程三个依赖加二十行启动代码先把依赖钉死在同一版本上核心包、平台包、视图包的版本号必须完全一致混版本是后面各种诡异崩溃的源头。!-- pom.xml 片段三件套版本必须一致 -- dependencies dependency groupIdcom.teamdev.jxbrowser/groupId artifactIdjxbrowser/artifactId version7.19/version /dependency dependency groupIdcom.teamdev.jxbrowser/groupId artifactIdjxbrowser-win64/artifactId version7.19/version /dependency dependency groupIdcom.teamdev.jxbrowser/groupId artifactIdjxbrowser-swing/artifactId version7.19/version /dependency /dependencies启动代码不要写成先 new 一个浏览器再想办法塞进窗口7.x 的对象创建顺序是有讲究的Engine 管进程和磁盘 profileBrowser 管一个页面实例BrowserView 只是把这个实例画到 Swing 容器里。顺序错了不会立刻报错但后面关闭和释放会一团乱。public class Demo { public static void main(String[] args) { // 授权 key 从启动参数读别硬编码进仓库 EngineOptions options EngineOptions.newBuilder(RenderingMode.HARDWARE_ACCELERATED) .licenseKey(System.getProperty(jxbrowser.license, )) .userDataDir(Paths.get(System.getProperty(user.home), .demoapp, chromium)) .build(); Engine engine Engine.newInstance(options); // 起一个 Chromium 进程组 Browser browser engine.newBrowser(); // 一 Engine 可以开很多 Browser SwingUtilities.invokeLater(() - { BrowserView view BrowserView.newInstance(browser); // 视图必须在 EDT 里建 JFrame frame new JFrame(demo); frame.setDefaultCloseOperation(WindowConstants.DISPOSE_ON_CLOSE); frame.add(view, BorderLayout.CENTER); frame.setSize(1200, 800); frame.setVisible(true); browser.navigation().loadUrl(https://example.com); }); // 兜底释放顺序必须是 browser 先于 engine Runtime.getRuntime().addShutdownHook(new Thread(() - { browser.close(); engine.close(); })); } }几个参数值得停一下。licenseKey走系统属性传入别写死在代码里7.19 的校验不是错了立刻报而是可能先跑一段时间、换机器或者重启后才出现功能受限等到现场演示才发现就来不及补救了。userDataDir决定了缓存、localStorage、cookie 落在哪不指定就会落到默认目录后面你会花时间找它。RenderingMode.HARDWARE_ACCELERATED走 GPU 合成滚动和视频明显更跟手但在虚拟机和远程桌面里是个雷第 5 章会细说。依赖拉下来之后先别急着写业务花一分钟确认拿到的是真平台包JAR~/.m2/repository/com/teamdev/jxbrowser/jxbrowser-win64/7.19/jxbrowser-win64-7.19.jar ls -lh $JAR # 几十到上百 MB 才正常几 MB 说明拿错了 unzip -l $JAR | head -n 20 # 看顶层目录是否有内核相关的目录或文件这一步看着多余实际上能过滤掉一大类启动就抛异常的问题。很多流传的包被重新打包过平台包里的东西被剥掉了外壳却留着名字体积对不上是最直接的信号。3. 页面怎么装进窗口三层模型与 EngineOptions 的四个关键参数代码能跑起来只是第一步。真正在项目里落地绕不开两个决定Engine 开几个、参数怎么配。这两件事配错了不会立刻崩但会以内存莫名其妙涨关掉窗口进程还在换个环境就白屏的形式在联调后期集中爆发。3.1 Engine、Browser、View为什么不是一个对象搞定Engine 对应一整套 Chromium 进程组和一份磁盘上的用户数据目录它是最重的那个对象创建一次要解压内核、拉起主进程和若干子进程耗时通常在几百毫秒到两三秒。Browser 是页面级实例相当于一个标签页创建成本极低几十毫秒。BrowserView 就是个 Swing 组件负责把 Browser 的画面贴到容器上。这个分层带来的第一个结论一个应用只开一个 Engine需要几个页面就开几个 Browser。第二个结论Engine 之间不共享 cookie、缓存和 localStorage因为它们的用户数据目录是各自独立的。很多人为了隔离不同模块的登录态顺手开了好几个 Engine结果内存翻两三倍关窗口时还留下一堆孤儿进程——这笔账在客户端上是很贵的。还有一个容易被忽略的生命周期细节browser.close()之后绑在它上面的 BrowserView 不能再用再往里加东西就是未定义行为engine.close()会连带关掉它下面所有 Browser。关闭顺序反过来的话偶发情况下会卡在 native 层等一个已经没人管的子进程。3.2 EngineOptions四个真正影响行为的参数参数列表很长但日常会调的就那么几个。剩下的默认值基本合理除非你明确知道自己要什么否则别乱动。参数作用常用取值设错的后果renderingMode走 GPU 合成还是离屏渲染HARDWARE_ACCELERATED/OFF_SCREEN虚拟机里黑屏、截图拿不到内容userDataDir缓存与登录态的落地目录应用数据目录下的固定子目录每次启动都要重新登录licenseKey授权校验从配置或启动参数注入运行一段时间后功能受限remoteDebuggingPort暴露调试端口仅开发环境开启如 9222生产环境白送一个调试入口渲染模式的选择有个经验判断物理机、有独显或较新的集显、用户直接盯着屏幕看用硬件加速远程桌面、虚拟机、云桌面、CI 里跑截图用离屏渲染。后者性能差一些但不会因为拿不到 GPU 上下文而给你一片黑。这个切换在配置文件里做成开关比在代码里写死要省事得多。// 生产环境常用的一套配置注意 chromiumDir 的写法在不同小版本间有差异 EngineOptions options EngineOptions.newBuilder( true.equals(System.getProperty(app.offscreen)) ? RenderingMode.OFF_SCREEN : RenderingMode.HARDWARE_ACCELERATED) .licenseKey(System.getProperty(jxbrowser.license, )) .userDataDir(Paths.get(appDataDir(), chromium)) .chromiumDir(Paths.get(appDir(), chromium)) // 指向随包发布的离线内核目录 .remoteDebuggingPort(Integer.getInteger(app.debug.port, 0)) // 0 表示不开启 .build();chromiumDir这个参数是离线部署的关键指向你自己放内核的目录引擎就不会往默认位置解压。如果你的小版本里 Builder 上没有这个方法等价的开关是通过启动参数传系统属性jxbrowser.chromium.dir两条路殊途同归用-D传进去效果一样。remoteDebuggingPort传 0 就是不开启开发期传 9222 之后用任意 Chromium 内核的浏览器打开127.0.0.1:9222就能看到当前页面等于把 DevTools 白拿过来了——这个能力在排查前端白屏时的价值比翻日志高一个量级。3.3 三条加载路径远程 URL、本地文件、内存 HTML页面来源无非三种各自的坑不一样。远程 URL 最省心但要处理加载失败和超时本地文件要处理相对路径和跨域内存 HTML 最灵活但它的页面来源是空白源很多前端能力直接用不了。// 1) 远程地址加载完成后再注入脚本否则拿到 null browser.navigation().loadUrlAndWait(https://example.com/dashboard); // 2) 本地文件必须转成 URI直接传路径字符串在 Windows 上会被盘符搞崩 Path page Paths.get(web, index.html).toAbsolutePath(); browser.navigation().loadUrl(page.toUri().toString()); // 3) 内存里的 HTML适合报表预览、邮件正文这类一次性内容 browser.navigation().loadHtml(htmlbodyh1report/h1/body/html);loadUrlAndWait会阻塞到加载完成方便是方便但千万别在 EDT 上调用否则整个界面卡住。本地文件那条路上file://协议下的fetch、XMLHttpRequest和部分存储能力都受同源策略限制前端如果用了模块化加载很容易直接报跨域错误。常见做法是内嵌一个极简 HTTP 服务指向本地目录用 JDK 自带的com.sun.net.httpserver就够几行代码把web目录挂到127.0.0.1的随机端口上页面用正常 http 源加载一切前端能力都回来了。这个改动很小但能省掉后面反复解释为什么浏览器里好好的放进客户端就报错的时间。4. Java 与页面互调脚本注入、对象桥接与 DOM 操作嵌浏览器的项目八成以上的实际工作量不在显示页面而在Java 和页面之间传数据。比如桌面端要把当前登录用户传给页面、页面上的按钮要触发本地文件导出、批量任务要读页面表格里的行数做进度。这三件事对应三套机制用错了不是不能用是会在某个边界上翻车。4.1 从 Java 执行脚本返回值、时机与失效句柄executeJavaScript是同步的调用线程会等 Chromium 那边算完再返回所以它既是最好用的工具也是最容易把界面卡死的地方。返回值会按 JS 类型映射回 Java数字、字符串、布尔直接拿对象和数组拿到的是一个JsObject句柄。Frame frame browser.mainFrame().orElseThrow(() - new IllegalStateException(页面还没加载)); // 简单值直接按类型接 String title frame.executeJavaScript(document.title); // 复杂结构让 JS 侧 JSON.stringifyJava 侧用 Jackson 之类解析最省心 String json frame.executeJavaScript( JSON.stringify({rows: document.querySelectorAll(tbody tr).length, url: location.href})); MapString, Object info new ObjectMapper().readValue(json, Map.class); // 主动注入一段脚本比如埋点、样式覆盖返回值忽略 frame.executeJavaScript(document.body.classList.add(embedded););几个边界必须记住。第一执行时机页面还在加载时调用mainFrame()可能拿不到或者拿到一个还没开始解析的空文档返回值全是 null。稳妥的写法是等导航完成事件或者直接用loadUrlAndWait。第二JsObject是句柄不是快照页面一跳转之前拿到的句柄就失效了继续用会抛异常——这个错误在单页应用里特别容易出现因为路由切换不一定会触发你监听的导航事件。第三同步调用不要放在 EDT 上一段几百毫秒的脚本足够让用户感觉到窗口顿了一下。4.2 让页面调用 Java对象桥接与回调线程反过来的方向靠对象桥接把一个 Java 对象挂到 window 上页面里就能像调普通 JS 方法一样调它。7.x 的做法是给类和方法打注解然后把实例塞进 window 的属性里。JsAccessible // 类必须标注否则注入时直接抛异常 public class Bridge { JsAccessible public String currentUser() { return Session.get().userName(); // 只读数据回调线程里直接取没问题 } JsAccessible public void exportCsv(String payload) { // 回调不在 EDT 上动 Swing 组件必须切回去 SwingUtilities.invokeLater(() - progressBar.setValue(100)); Files.writeString(Paths.get(out.csv), payload); } } // 注入先拿 window再挂属性 frame.executeJavaScript(window).putProperty(bridge, new Bridge());页面侧写起来就是普通的 JSwindow.bridge.currentUser()。这里有两个约束值得提前跟前端说清楚。一是参数和返回值的类型有限制基本类型、字符串和JsObject是安全的自定义 POJO 基本传不过去惯例是双方约定用 JSON 字符串。二是回调线程不是 EDT在回调里直接setText或者repaint属于典型翻车点现象是偶发卡死或者界面不刷新日志里什么都没有排查起来极其难受。我的做法是在桥接类里就把invokeLater包好对外只暴露安全的方法别把这个约定留给每个调用方自己记。4.3 不写脚本也能改页面DOM API 的适用边界7.x 补了一套 DOM 操作 API能在 Java 侧直接查元素、读文本、拿属性不用拼字符串脚本。对做自动化测试和表单填写的场景挺友好。Document doc frame.document(); doc.findElement(By.id(username)).ifPresent(e - System.out.println(e.innerText())); doc.findElements(By.tagName(a)).forEach(a - System.out.println(a.attribute(href))); doc.findElement(By.cssSelector(.status)).ifPresent(e - System.out.println(e.innerText()));它好用但有个性能上的硬边界DOM API 的每次调用都是一次跨进程往返。查十个元素就是十次 IPC批量处理几百个节点的时候耗时会是同等executeJavaScript的十几倍。血泪经验是这么分的——零星取值、断言页面状态、点一个按钮用 DOM API代码干净批量遍历、批量填表、需要读取计算样式写成一段 JS 一次执行完返回 JSON。把这条分界线画清楚能避免很多为什么嵌了浏览器以后界面特别肉的困惑。5. 避坑与排查五个把项目卡住的现场下面这几条不是我编出来的理论是这类项目里出现频率最高、且最容易在联调后期才暴露的问题。每一条都按你看到什么、为什么、怎么改来写照着对号入座就行。5.1 启动就崩日志里说找不到内核现象Engine.newInstance直接抛异常堆栈里能看到与二进制、路径相关的内容窗口根本没出来。原因几乎都是依赖不全只引了jxbrowser核心包或者打包工具把平台包当成没被引用的依赖剔掉了或者 CI 里给平台包设了provided作用域本地跑得好流水线出来的包就是废的。解决办法是按顺序查三件事mvn dependency:tree看平台包在不在依赖树里直接去target目录看最终的 jar 或 lib 目录里有没有那个几十 MB 的文件如果用了 shade 或 spring-boot 的 repackage检查有没有把它排除掉。还有一种隐蔽情况是内网仓库同步不完整拉下来的平台包是个几百 KB 的空壳ls -lh一看体积就知道。5.2 窗口关了进程还在第二次启动内存翻倍现象任务管理器里躺着若干 Chromium 子进程主程序已经退出反复启动几次之后机器内存肉眼可见地涨。原因是没有显式关闭 Browser 和 Engine只调了frame.dispose()——那只关掉了 Swing 窗口浏览器实例和它的进程组还活着。异常路径下更明显业务代码抛了异常后面的清理逻辑根本没执行。解决思路是把关闭做成不可绕过的在main里注册 shutdown hook 兜底业务侧的窗口关闭回调里显式调browser.close()容器级的地方统一管engine.close()。关闭前如果需要保留登录态先把 cookie 落盘再关。别指望 GC这些对象持有的是 native 资源回收时机完全不受你控制。5.3 IDE 里好好的打成安装包就白屏现象开发机上一切正常装到用户机器上窗口出来了内容一片白或者只在远程桌面里白。原因通常有两个。一个是安装目录不可写引擎解压内核失败又不报明显错误另一个是硬件加速在虚拟显卡、远程桌面、老集显上拿不到上下文合成结果就是黑的。对策很直接userDataDir一律指向用户数据目录Windows 上就是%LOCALAPPDATA%下面不要用安装目录启动时做一次内核目录可写性检查不可写就立刻打日志告诉用户而不是让页面白着渲染模式做成可配置检测到远程会话或虚拟机就自动退回离屏渲染。还有一个附加项安装路径里的中文和空格在部分环境里会让本地资源加载失败尽量引导用户装到纯英文路径。5.4 偶发卡死日志里什么都没有现象绝大多数时候正常偶尔整个窗口僵住几秒甚至十几秒事后日志干干净净。原因基本是两个线程问题叠加一是回调线程里直接操作 Swing 组件二是 EDT 上执行了同步脚本或loadUrlAndWait。前者会让 Swing 的重绘和事件分发进入不确定状态后者直接阻塞了事件分发线程。排查办法是加线程检查在桥接方法、事件回调、脚本执行这三类入口处打印当前线程名跑一轮业务就能看出谁不在 EDT 上。修法是所有跨线程的 UI 操作统一走SwingUtilities.invokeLater所有同步的浏览器调用挪到后台线程或者换成异步的写法。这类问题改完之后不会立刻看起来变好因为本来就是偶发得靠压测跑一段时间才能确认。5.5 每次启动都要重新登录或者换台机器登录态就没了现象用户抱怨客户端记不住登录状态明明勾了记住我。原因多半是userDataDir没固定——用了临时目录、用了随机子目录、或者被安装程序在升级时清掉了。另一个原因是同时开了多个 Engine 指向同一个目录Chromium 对用户数据目录有单实例约束第二个实例要么起不来要么写坏数据。处理方式目录固定成应用数据本文还有配套的精品资源点击获取