Apache NetBeans 31 常用 CLI 命令与工具详解

Apache NetBeans 31 常用 CLI 命令与工具详解，覆盖 netbeans 启动器帮助、版本查看、核心运行选项、模块清单与启停管理、项目打开与语言服务器选项的真实回显与速查表，均在 Ubuntu 22.04.5 + JDK21 实测

Apache NetBeansApache NetBeans2026/10/11

Apache NetBeans 31 常用 CLI 命令与工具详解

目标：详解 Apache NetBeans 31 的命令行入口 bin/netbeans 的全部可用选项，包括帮助与版本查看、JVM 透传、模块清单与启停、项目打开与语言服务器选项，并给出常用命令速查表，所有命令与回显均在 Ubuntu 22.04.5 + JDK21 上实测通过（无桌面环境下命令行功能完整可用）。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（amd64）
  • JDK：OpenJDK 21.0.12.1（NetBeans 31 要求 Java 21+）
  • NetBeans：Apache NetBeans IDE 31（build_info 编号 31-f8ac37e0f2434a7f000fbe3360f1a92aa3ea67bc），安装目录 /opt/netbeans
  • 启动器：/opt/netbeans/bin/netbeans（内部转交 /opt/netbeans/platform/lib/nbexec）
  • 默认用户目录：/root/.netbeans/31

二、工具概览

NetBeans 的 CLI 是单一入口 netbeans（Linux 启动器脚本，Windows 发行包另有 netbeans.exe）。选项分四类：

  • 通用选项：--help、--jdkhome、-J<jvm_option>、--cp:p/--cp:a；
  • 模块管理选项：须与 --modules 组合（--list、--disable、--enable、--install 等）；
  • 项目/文件选项：--open、--open-group、--close-group、--list-groups；
  • 核心界面选项：--laf、--fontsize、--locale、--userdir、--cachedir、--nosplash。

--help 由启动器直接打印；--list 等模块选项则完整引导模块系统后执行，因此首次运行需初始化用户目录缓存（实测 20～30 秒）。

三、前置条件

按《Ubuntu 22.04 安装 Apache NetBeans 31 指南》完成安装并配置命令行入口（PATH 含 /opt/netbeans/bin），Java 21+ 可用。无桌面的服务器可运行除 GUI 相关（--laf/--fontsize/--nosplash 生效窗口）外的全部命令，运行时会提示 DISPLAY 未设置，属正常现象。

四、帮助与版本信息

4.1 netbeans --help

打印全部选项并结束（不启动 IDE）。实测在无显示环境运行（退出码 2）：

netbeans --help

实测全量回显：

Usage: /opt/netbeans/platform/lib/nbexec {options} arguments

General options:
  --help                show this help
  --jdkhome <path>      path to Java(TM) 2 SDK, Standard Edition
  -J<jvm_option>        pass <jvm_option> to JVM

  --cp:p <classpath>    prepend <classpath> to classpath
  --cp:a <classpath>    append <classpath> to classpath
/opt/netbeans/platform/lib/nbexec: WARNING: environment variable DISPLAY is not set
WARNING: package com.sun.java.swing.plaf.windows not in java.desktop
WARNING: package com.apple.laf not in java.desktop
netbeans.user points to a non-existent directory.
Module reload options:
  --reload /path/to/module.jar  install or reinstall a module JAR file

Additional module options:
  --modules
  --refresh                                 Refresh all catalogs
  --list                                    Prints the list of all modules, their versions and enablement status
  --install <arg1>...<argN>                 Installs provided JAR files as modules
  --disable <arg1>...<argN>                 Disable modules for specified codebase names
  --enable <arg1>...<argN>                  Enable modules for specified codebase names
  --update <arg1>...<argN>                  Updates all or specified modules
  --update-all                              Updates all modules
  --extra-uc <arg>                          Add a extra Update Center (URL)
  --direct-disable <arg1>...<argN>          Disable module immediately
  --start-java-language-server [<arg>]      Starts the Java Language Server
  --start-java-debug-adapter-server [<arg>] Starts the Java Debug Adapter Server
  --open file1[:line1]...                   open specified file(s), possibly at given location; can also pass project directories
  --open-group NAME                         open a project group by shortened or full name (or unique substring)
  --close-group                             close any open project group
  --list-groups                             list available project groups

Core options:
  --laf <LaF classname> use given LookAndFeel class instead of the default
  --fontsize <size>     set the base font size of the user interface, in points
  --locale <language[:country[:variant]]> use specified locale
  --userdir <path>      use specified directory to store user settings
  --cachedir <path>     use specified directory to store user cache, must be different from userdir
  --nosplash            do not show the splash screen

💡 说明：netbeans.user points to a non-existent directory. 是首次运行前用户目录未创建的正常提示；两条 WARNING: package ... not in java.desktop 来自出厂参数对 Windows/macOS 观感类的引用，在 Linux 上无害。

4.2 版本查看

启动器没有 --version 选项（--help 全量清单中无此项），版本用以下方式查看（实测）：

cat /opt/netbeans/nb/build_info

NetBeans dev build
------------------
Number:   31-f8ac37e0f2434a7f000fbe3360f1a92aa3ea67bc
Date:     5 Aug 2026
Branding:
Branch:   trunk
Tag:
Hg ID:    unknown-revn

或运行任一命令后从用户目录日志读取产品版本：

grep "Product Version" /root/.netbeans/31/var/log/messages.log

  Product Version         = Apache NetBeans IDE 31

snap 安装时还可 snap list netbeans（实测输出 netbeans 31 149 latest/stable apache-netbeans** classic）。

五、核心运行选项

5.1 JVM 透传 -J<jvm_option>

-J 前缀把参数透传给 JVM。限制堆并验证（配合可快速退出的 --modules --list）：

netbeans --userdir /root/.netbeans-mem -J-Xms256m -J-Xmx512m --modules --list > /dev/null 2>&1 &
PID=$(pgrep -x java | head -1)
tr "\0" "\n" < /proc/$PID/cmdline | grep -E "^-Xm[sx]"

实测回显：

-Xms256m
-Xmx512m

用 jcmd 复核生效堆：

jcmd $PID VM.flags | tr ' ' '\n' | grep -E 'MaxHeapSize=|InitialHeapSize=' | awk -F= '{printf "%s = %.0f MB\n", $1, $2/1048576}'

-XX:InitialHeapSize = 256 MB
-XX:MaxHeapSize = 512 MB
-XX:SoftMaxHeapSize = 512 MB

5.2 --jdkhome

指定本次运行使用的 JDK（实测对不兼容 JDK 会明确报错，见本节末尾）：

netbeans --jdkhome /usr/lib/jvm/java-21-openjdk-amd64 --modules --list > /dev/null 2>&1

对低于 21 的 JDK（实测 JDK 17）：

netbeans --jdkhome /usr/lib/jvm/java-17-openjdk-amd64 --userdir /root/.netbeans-jdk17 --modules --list

实测回显（退出码 10）：

Cannot run on older versions of Java than Java 21.
Please install Java 21 or newer or use --jdkhome

5.3 --userdir 与 --cachedir

指定本次运行的用户/缓存目录，--cachedir 不得与 --userdir 相同；只传 --userdir 时缓存自动落在 <userdir>/var/cache：

netbeans --userdir /root/.netbeans-work --modules --list > /dev/null 2>&1
ls /root/.netbeans-work

实测回显：

.lastUsedVersion  .superId  config  var

5.4 界面相关选项

--laf <类名>、--fontsize <字号>、--locale <语言>、--nosplash 仅对图形会话生效（⚠️ 需桌面环境），命令行传参合法但不产生可见效果，例如：

netbeans --locale zh_CN --fontsize 14 --nosplash

六、模块管理命令

6.1 模块清单 --modules --list

打印全部模块的代号（Code Name）、版本与状态。实测（约 20～30 秒完成）：

netbeans --userdir /root/.netbeans --modules --list > /tmp/nb-mods.txt
head -12 /tmp/nb-mods.txt

实测回显：

/opt/netbeans/platform/lib/nbexec: WARNING: environment variable DISPLAY is not set
Code Name                                          Version                                State
-------------------------------------------------- -------------------------------------- -------------
org.netbeans.modules.glassfish.common              1.107                                  Installed
org.netbeans.modules.profiler.j2se                 1.69                                   Installed
org.netbeans.modules.gradle.dependencies           1.10.0.1.1.1                           Installed
org.netbeans.modules.extexecution                  1.82                                   Enabled
org.netbeans.modules.xml.schema.model              1.65.0.1                               Enabled
org.netbeans.modules.options.api                   1.78                                   Enabled
org.netbeans.modules.ide.dashboard                 0.10                                   Enabled
org.netbeans.modules.profiler.oql.language         0.61                                   Installed
org.netbeans.modules.languages.diff                1.66                                   Enabled

31 版全量统计（实测）：

tail -n +3 /tmp/nb-mods.txt | awk '{print $NF}' | sort | uniq -c

      2 -------------
    323 Enabled
    497 Installed
     11 state

即 831 个模块：Enabled（启用）323 个、Installed（已安装但默认禁用）497 个，另有 11 个 fod. 前缀的按需特性模块状态列显示 Unknown state（如 fod.org.netbeans.modules.java.kit 1.68 Unknown state）。

⚠️ 注意：--list 单独使用会失败——实测 netbeans --list 退出码 173，并在标准错误输出 Need to use also --modules, --refresh。--list 必须与 --modules 组合。

6.2 禁用模块 --modules --disable

参数是模块的 Code Name（6.1 清单第一列）。实测禁用 Groovy 支持套件：

netbeans --userdir /root/.netbeans --modules --disable org.netbeans.modules.groovy.kit
netbeans --userdir /root/.netbeans --modules --list 2>/dev/null | grep "^org.netbeans.modules.groovy.kit"

禁用后再查，状态已持久变化：

org.netbeans.modules.groovy.kit                    1.65                                   Installed

紧急禁用异常模块可用 --modules --direct-disable <代号>（跳过常规停用流程立即写状态）。

6.3 启用模块 --modules --enable

启用「默认禁用」的模块时，启动器会逐个提示缺失的依赖（实测，均未生效）：

netbeans --userdir /root/.netbeans --modules --enable org.netbeans.modules.groovy.kit

Would also need to enable: {StandardModule:org.netbeans.modules.java.sourceui jarFile: /opt/netbeans/java/modules/org-netbeans-modules-java-sourceui.jar=[]}

netbeans --userdir /root/.netbeans --modules --enable org.netbeans.modules.java.sourceui

Would also need to enable: {StandardModule:org.netbeans.modules.java.j2seplatform jarFile: /opt/netbeans/java/modules/org-netbeans-modules-java-j2seplatform.jar=[]}

netbeans --userdir /root/.netbeans --modules --enable org.netbeans.modules.groovy.kit org.netbeans.modules.java.sourceui

Would also need to enable: {StandardModule:org.netbeans.modules.j2ee.metadata jarFile: /opt/netbeans/java/modules/org-netbeans-modules-j2ee-metadata.jar=[]}

💡 说明：--enable 需要整条依赖链同时启用，命令行逐级补齐繁琐；批量启用推荐 GUI 的 Tools → Plugins，或按提示的顺序把缺失依赖逐个加入同一命令（如 --enable A B C ...）直到提示消失。

6.4 安装、更新与更新中心

命令作用说明
--modules --install <jar1> <jar2> ...把本地 jar 安装为模块jar 须为合法模块包
--modules --update <代号>...更新指定模块从已配置更新中心解析
--modules --update-all更新全部可更新模块需更新中心可达
--modules --extra-uc <URL>追加额外更新中心当前会话有效
--modules --refresh刷新更新目录缓存与 --list 组合可强制重建
--reload /path/to/module.jar开发期重载模块 jar模块开发调试用

更新类命令依赖网络与更新中心配置；离线服务器上执行会因无法解析更新中心而无可更新项。

七、项目与文件打开

7.1 --open

打开文件或项目目录（支持 文件[:行号] 形式，可一次传多个参数，也可传项目目录）：

netbeans --open /tmp/nb-demo
netbeans --open /tmp/nb-demo/src/main/java/com/example/App.java:1

⚠️ 前置说明：打开动作需要图形会话。实测无显示环境执行 netbeans --open /opt/netbeans/README.html 时命令静默返回（退出码 0，仅 DISPLAY 警告），既不报错也不弹窗——GUI 操作请在桌面环境或 ssh -X/VNC 会话中执行。

7.2 项目组

命令作用
--open-group NAME按名称（或唯一子串）打开项目组
--list-groups列出可用项目组
--close-group关闭当前打开的项目组

项目组在 GUI 的 File → Project Groups 中创建后，才能用上述命令行按组批量打开/关闭。

八、无头服务器与编辑器集成选项

8.1 语言服务器与调试适配器选项

--help 清单中的 --start-java-language-server / --start-java-debug-adapter-server 用于把 NetBeans 的 Java 语言能力以 LSP/DAP 服务形式提供给外部编辑器。实测直接运行：

netbeans --userdir /root/.netbeans-lsp --start-java-language-server

实测回显（报错，未启动服务）：

Unrecognized option --start-java-language-server

原因（实测证据）：该选项由 Java 语言服务器模块提供，而 bin 发行包中该模块默认禁用：

netbeans --userdir /root/.netbeans --modules --list 2>/dev/null | grep "java.lsp.server"

org.netbeans.modules.java.lsp.server               2.17.0.1.2.12.1.17.32.6.2.8.1.8.1.1.13 Installed

⚠️ 注意：在无桌面服务器上使用 LSP 集成，需先启用 org.netbeans.modules.java.lsp.server 及其依赖链（GUI Tools → Plugins 或按 6.3 的依赖提示逐级 --enable），之后再次运行 --start-java-language-server 才能启动服务；--start-java-debug-adapter-server 同理。

九、常用命令速查

命令作用关键说明
netbeans --help打印全部选项无显示环境可用
netbeans --jdkhome <路径>指定 JDKJava 21 以下直接拒绝
netbeans -J-Xmx512m ...透传 JVM 参数堆限制用 -J-Xms/-J-Xmx
netbeans --userdir <路径>指定用户目录多实例隔离
netbeans --cachedir <路径>指定缓存目录不得与 userdir 相同
netbeans --modules --list模块清单必须与 --modules 组合
netbeans --modules --disable <代号>禁用模块状态持久
netbeans --modules --enable <代号>启用模块需整条依赖链
netbeans --modules --direct-disable <代号>立即禁用跳过常规流程
netbeans --modules --install <jar>安装本地模块 jar多 jar 空格分隔
netbeans --modules --update-all更新全部模块需更新中心可达
netbeans --modules --refresh刷新更新目录可与 --list 组合
netbeans --reload <jar>开发期重载模块模块开发用
netbeans --open <项目/文件[:行]>打开项目/文件需图形会话
netbeans --open-group NAME打开项目组需先在 GUI 创建
netbeans --list-groups列出项目组同上
netbeans --close-group关闭项目组同上
netbeans --start-java-language-server启动 Java LSP 服务需先启用 lsp.server 模块
netbeans --start-java-debug-adapter-server启动 DAP 服务同上
netbeans --nosplash关闭闪屏GUI 生效
netbeans --locale zh_CN指定界面语言GUI 生效
netbeans --fontsize 14界面基准字号GUI 生效
netbeans --laf <类名>指定观感GUI 生效

十、注意事项

  • 模块代号以 --modules --list 第一列为准（如 org.netbeans.modules.groovy.kit），不要用显示名。
  • 所有写状态的命令（--disable/--enable/--install）落到对应 userdir 的 config/，多 userdir 场景务必带同一个 --userdir。
  • --help 无显示环境退出码为 2，--list 缺 --modules 退出码 173，均不影响判断输出内容。
  • 系统属性透传也可用 -J-D<key>=<value>（如 -J-Dplugin.manager.check.updates=false），与 conf 中出厂写法一致。

十一、常见问题

Q1：netbeans --list 报 Need to use also --modules, --refresh

--list 只描述模块清单能力，必须组合 --modules：netbeans --modules --list。

Q2：没有 --version，怎么在脚本里取版本号

grep -m1 "Product Version" <userdir>/var/log/messages.log（先运行一次任意命令生成日志），或 cat /opt/netbeans/nb/build_info 的 Number: 行。

Q3：--enable 加了模块名却没生效

按「Would also need to enable: ...」提示补齐依赖链；一条命令可带多个代号，逐级补齐直到提示消失，再复查 --modules --list。

Q4：--start-java-language-server 报 Unrecognized option

该选项依赖默认禁用的 java.lsp.server 模块（见八、8.1），先启用模块再运行。

Q5：无桌面服务器能跑哪些命令

--help、--modules 全系列、--jdkhome/--userdir/--cachedir/-J* 均可用；--open 与界面类选项需要桌面环境（X11 转发或 VNC）。

十二、参考链接

  • NetBeans 官方文档：https://netbeans.apache.org/kb/docs/
  • Apache NetBeans 下载页：https://netbeans.apache.org/download/
  • userdir FAQ（conf 内引用）：http://wiki.netbeans.org/FaqWhatIsUserdir
  • NetBeans 平台模块开发：https://netbeans.apache.org/tutorials/