Apache NetBeans 31 配置参数详解

目标：系统讲解 Apache NetBeans 31 的配置层次——全局启动配置 etc/netbeans.conf、命令行覆盖项与用户目录（userdir）运行时文件——的核心参数、默认值与改法，并给出生产环境配置模板，已在 Ubuntu 22.04.5 实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（amd64）
JDK：OpenJDK 21.0.12.1，路径 /usr/lib/jvm/java-21-openjdk-amd64（NetBeans 31 要求 Java 21+）
NetBeans：Apache NetBeans IDE 31，安装目录 /opt/netbeans
全局配置：/opt/netbeans/etc/netbeans.conf
簇清单：/opt/netbeans/etc/netbeans.clusters
默认用户目录：/root/.netbeans/31；默认缓存目录：/root/.cache/netbeans/31
运行日志：/root/.netbeans/31/var/log/messages.log

二、前置条件

已按《Ubuntu 22.04 安装 Apache NetBeans 31 指南》完成安装，netbeans --help 可正常输出，安装目录为 /opt/netbeans。本篇围绕「启动配置 → 命令行覆盖 → 运行时生成」三层参数展开。

三、参数查看与修改方式

3.1 配置层次定位

NetBeans 的参数分三层，优先级从高到低：

命令行选项：--userdir、--jdkhome、-J<jvm_option> 等，单次运行生效，优先级最高（conf 注释原文：can be overridden by explicit command line switches）；
全局启动配置：/opt/netbeans/etc/netbeans.conf，持久生效，所有用户共用（snap 安装则在 snap 内部对应路径）；
用户目录运行时文件：~/.netbeans/31/config/ 下各模块 Preferences，由 IDE 运行时读写，不作为启动参数入口。

3.2 查看生效的运行环境（messages.log）

任一次运行后，用户目录日志头部记录全部生效值：

grep -A6 "System Info" /root/.netbeans/31/var/log/messages.log | head -8

实测回显：

>System Info:
  Product Version         = Apache NetBeans IDE 31
  Operating System        = Linux version 6.8.0-138-generic running on amd64
  Java; VM; Vendor        = 21.0.12.1; OpenJDK 64-Bit Server VM 21.0.12.1+1-1-22.04.4-Ubuntu; Ubuntu
  Runtime                 = OpenJDK Runtime Environment 21.0.12.1+1-1-22.04.4-Ubuntu
  Java Home               = /usr/lib/jvm/java-21-openjdk-amd64
  System Locale; Encoding = en_US (nb); UTF-8

同块中的 User Directory、Cache Directory、Installation（簇清单）行分别对应三类路径参数的生效值：

  User Directory          = /root/.netbeans
  Cache Directory         = /root/.netbeans/var/cache
  Installation            = /opt/netbeans/nb
                            /opt/netbeans/ergonomics
                            /opt/netbeans/ide
                            /opt/netbeans/extide
                            /opt/netbeans/java
                            /opt/netbeans/apisupport
                            /opt/netbeans/webcommon
                            /opt/netbeans/websvccommon
                            /opt/netbeans/enterprise
                            /opt/netbeans/profiler
                            /opt/netbeans/php
                            /opt/netbeans/harness
                            /opt/netbeans/cpplite
                            /opt/netbeans/groovy
                            /opt/netbeans/javafx
                            /opt/netbeans/platform

3.3 修改 netbeans.conf 并验证生效

编辑 /opt/netbeans/etc/netbeans.conf，例如设置 JDK 路径（取消注释 netbeans_jdkhome）：

netbeans_jdkhome="/usr/lib/jvm/java-21-openjdk-amd64"

用全新 userdir 运行一次命令行命令后验证：

grep "Java Home" /root/.netbeans-conf-test/var/log/messages.log

实测回显：

  Java Home               = /usr/lib/jvm/java-21-openjdk-amd64

四、参数总览

/opt/netbeans/etc/netbeans.conf 支持的键：

键	作用	默认值（31 版实测原文）
`netbeans_default_userdir`	用户目录根	`${DEFAULT_USERDIR_ROOT}/31`（Linux 展开为 `~/.netbeans/31`）
`netbeans_default_cachedir`	缓存目录根	`${DEFAULT_CACHEDIR_ROOT}/31`（Linux 展开为 `~/.cache/netbeans/31`）
`netbeans_default_options`	默认 JVM/系统属性透传	`-J-XX:+UseStringDeduplication -J-XX:+UseCompactObjectHeaders -J-Xss2m ...`（全量见 5.3）
`netbeans_jdkhome`	指定 JDK	注释状态（由启动器探测 `PATH` 中的 `java`）
`netbeans_extraclusters`	追加外部模块簇	注释状态

常用命令行覆盖项：

选项	作用	备注
`--userdir <path>`	覆盖用户目录	只传它不传 `--cachedir` 时，缓存落 `<userdir>/var/cache`
`--cachedir <path>`	覆盖缓存目录	必须与 userdir 不同
`--jdkhome <path>`	覆盖 JDK	优先于 `netbeans_jdkhome`
`-J<jvm_option>`	透传 JVM 参数	如 `-J-Xmx512m`
`--locale <lang[:country[:variant]]>`	界面语言	如 `--locale zh_CN`
`--fontsize <size>`	界面基准字号	像素点值
`--laf <类名>`	指定 LookAndFeel	覆盖默认观感
`--nosplash`	关闭启动闪屏	GUI 会话有效

五、核心参数分类详解

5.1 用户目录 `netbeans_default_userdir`

conf 中默认行：

netbeans_default_userdir="${DEFAULT_USERDIR_ROOT}/31"

DEFAULT_USERDIR_ROOT 在 Linux 由启动器展开为 ~/.netbeans（conf 注释原文），因此默认用户目录为 ~/.netbeans/31，root 用户即 /root/.netbeans/31。首次运行后实测：

ls /root/.netbeans/
cat /root/.netbeans/31/.lastUsedVersion

实测回显：

31
31

💡 说明：目录名带版本号是刻意设计——升级到新大版本后旧配置保留在旧目录，首次启动向导会把旧配置导入新目录（导入痕迹在用户目录 var/imported/）。

命令行 --userdir /root/.netbeans-work 可临时改用独立用户目录，用于多实例隔离或故障排查（多用户实践见《Apache NetBeans 31 项目开发实践指南》）。

5.2 缓存目录 `netbeans_default_cachedir`

netbeans_default_cachedir="${DEFAULT_CACHEDIR_ROOT}/31"

Linux 上 DEFAULT_CACHEDIR_ROOT 展开为 ~/.cache/netbeans。缓存可随时删除重建（模块清单、类索引等），首次运行重建时耗时增加。conf 注释的两条硬性规则：

Cachedir must be different from userdir. The same cachedir and userdir would cause problems.（两者不得相同）；
命令行只传 --userdir 不传 --cachedir 时，缓存改为 <userdir>/var/cache。

实测缓存目录内容（首次运行后）：

ls /root/.netbeans/var/cache/ | head -8

实测回显：

all-clusters.dat
all-files.dat
all-installer.dat
all-layers.dat
all-local-layers.dat
all-manifests.dat
all-modules.dat
all-resources.dat

5.3 启动选项 `netbeans_default_options`

该键是启动器透传给 JVM 的默认参数串（-J 前缀项去前缀后传给 JVM）。31 版出厂全量默认值（实测原文，一行）：

netbeans_default_options="-J-XX:+UseStringDeduplication -J-XX:+UseCompactObjectHeaders -J-Xss2m  -J-Djava.lang.Runtime.level=FINE -J--sun-misc-unsafe-memory-access=warn -J-Dguice_custom_class_loading=CHILD -J-Dapple.laf.useScreenMenuBar=true -J-Dapple.awt.application.appearance=system -J-Dsun.java2d.noddraw=true -J-Dsun.java2d.dpiaware=true -J-Dplugin.manager.check.updates=false -J-Dnetbeans.extbrowser.manual_chrome_plugin_install=yes  -J--enable-native-access=ALL-UNNAMED -J--add-opens=java.base/java.net=ALL-UNNAMED -J--add-opens=java.base/java.lang.ref=ALL-UNNAMED -J--add-opens=java.base/java.lang=ALL-UNNAMED -J--add-opens=java.base/java.security=ALL-UNNAMED -J--add-opens=java.base/java.util=ALL-UNNAMED -J--add-opens=java.base/java.nio=ALL-UNNAMED -J--add-exports=java.base/sun.reflect.annotation=ALL-UNNAMED -J--add-opens=java.prefs/java.util.prefs=ALL-UNNAMED -J--add-opens=java.desktop/javax.swing.plaf.basic=ALL-UNNAMED -J--add-opens=java.desktop/javax.swing.text=ALL-UNNAMED -J--add-opens=java.desktop/javax.swing=ALL-UNNAMED -J--add-opens=java.desktop/java.awt=ALL-UNNAMED -J--add-opens=java.desktop/java.awt.event=ALL-UNNAMED -J--add-opens=java.desktop/sun.awt.X11=ALL-UNNAMED -J--add-opens=java.desktop/javax.swing.plaf.synth=ALL-UNNAMED -J--add-opens=java.desktop/com.sun.java.swing.plaf.windows=ALL-UNNAMED -J--add-opens=java.desktop/com.apple.laf=ALL-UNNAMED -J--add-exports=java.desktop/sun.awt.im=ALL-UNNAMED -J--add-exports=java.desktop/sun.swing=ALL-UNNAMED -J--add-exports=java.desktop/sun.awt.im=ALL-UNNAMED -J--add-exports=java.desktop/com.sun.java.swing.plaf.motif=ALL-UNNAMED -J--add-opens=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED -J--add-opens=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED -J--add-opens=jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED -J--add-opens=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED -J--add-opens=jdk.compiler/com.sun.tools.javac.jvm=ALL-UNNAMED -J--add-opens=jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED -J--add-opens=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED -J--add-opens=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED -J--add-opens=jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED -J--add-opens=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED -J--add-opens=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED -J--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED -J--add-exports=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED -J--add-exports=jdk.compiler/com.sun.tools.javac.comp=ALL-UNNAMED -J--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED -J--add-exports=jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED -J--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED -J--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED -J--add-exports=jdk.compiler/com.sun.tools.javac.processing=ALL-UNNAMED -J--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED -J--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED -J--add-modules=jdk.jshell -J--add-opens=jdk.jshell/jdk.jshell=ALL-UNNAMED -J--add-exports=jdk.jshell/jdk.internal.jshell.debug=ALL-UNNAMED -J--add-exports=jdk.jdeps/com.sun.tools.classfile=ALL-UNNAMED -J--add-exports=jdk.jdeps/com.sun.tools.javap=ALL-UNNAMED -J--add-exports=jdk.internal.jvmstat/sun.jvmstat.monitor=ALL-UNNAMED -J--add-exports=jdk.internal.opt/jdk.internal.opt=ALL-UNNAMED -J--add-exports=java.management/sun.management=ALL-UNNAMED -J-XX:+IgnoreUnrecognizedVMOptions -J-javaagent:\"${BASEDIR}/ide/netbeans-javaagent.jar\""

要点：

大量 --add-opens/--add-exports 是 Java 21 模块系统下 IDE 必需的深反射授权，不要整段删除；追加参数请写在该行末尾；
-J-XX:+IgnoreUnrecognizedVMOptions 让未知 JVM 参数被忽略而不是启动失败，因此跨 JDK 版本追加参数较安全；
-J-javaagent:\"${BASEDIR}/ide/netbeans-javaagent.jar\" 中的 ${BASEDIR} 由启动器替换为安装目录（conf 注释原文：is replaced with the base directory of the NetBeans installation）；
conf 注释原文：默认 -Xmx 由 JVM 自动选择，实际值可在用户目录 var/log/messages.log 查看，可用 -J-Xmx 覆盖。

5.4 JDK 路径 `netbeans_jdkhome`

出厂为注释状态，启动器按 PATH 探测。多 JDK 共存时显式指定：

netbeans_jdkhome="/usr/lib/jvm/java-21-openjdk-amd64"

生效验证见「三、3.3」（Java Home 行实测一致）。临时换 JDK 用命令行 --jdkhome <路径>，无需改配置文件。

5.5 模块簇 `netbeans.clusters` 与 `netbeans_extraclusters`

安装目录按功能划分为模块簇（cluster），加载顺序由 /opt/netbeans/etc/netbeans.clusters 定义（去注释后原文）：

platform nb ergonomics ide extide java apisupport webcommon websvccommon enterprise mobility profiler python php identity harness cnd cndext cpplite dlight groovy extra javacard javafx rust

外部自研模块簇通过 netbeans_extraclusters 追加：

netbeans_extraclusters="/opt/my-cluster1:/opt/my-cluster2"

生效后 messages.log 的 Installation 块与运行命令的 --clusters 序列中会出现追加簇。

5.6 JVM 内存参数

堆限制在启动时透传（临时）：

netbeans --userdir /root/.netbeans-mem -J-Xms256m -J-Xmx512m --modules --list > /dev/null 2>&1 &

对运行中的进程验证：

PID=$(pgrep -x java | head -1)
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

长期固定写入 netbeans_default_options 行尾（追加 -J-Xms256m -J-Xmx512m）。IDE 是常驻重内存应用，与生产服务混部时建议 256～512MB 起步并按工作负载上调；图形界面大项目索引时内存峰值更高，纯命令行（模块管理）场景 256～512MB 足够。

5.7 用户目录运行时文件

首次运行后用户目录结构（实测）：

/root/.netbeans/
├── .lastUsedVersion          # 最近使用版本（31）
├── .superId                  # 本机唯一标识（UUID）
├── lock                      # 实例锁（保证同一 userdir 单实例）
├── config/
│   ├── Preferences/org/netbeans/modules/...   # 各模块偏好
│   ├── Windows2/ Windows2Local/               # 窗口布局
│   └── org-netbeans-api-project-libraries/
└── var/
    ├── cache/                # 模块缓存（见 5.2）
    ├── imported/             # 旧版本配置导入痕迹
    └── log/messages.log      # 运行日志（排障首选）

偏好文件为 Java properties 格式，例如模块自动更新的刷新配置（实测内容）：

cat /root/.netbeans/config/Preferences/org/netbeans/modules/autoupdate/ui.properties

time_of_refresh_update_centers=4

⚠️ 注意：config/ 下的文件由 IDE 写入，手工修改前先关闭 NetBeans 实例（删除 lock 前确认无进程），避免运行中被覆盖。

六、生产环境配置模板

6.1 桌面/开发工作站模板（16GB 内存、SSD、日常 GUI 开发）

适用场景：独立开发机，图形界面日常使用，保留出厂深反射参数、追加显式堆与关闪屏。两步落地：

第一步，编辑 /opt/netbeans/etc/netbeans.conf，设置 JDK 路径（取消注释并赋值）：

netbeans_jdkhome="/usr/lib/jvm/java-21-openjdk-amd64"

第二步，在 netbeans_default_options 行末追加堆参数（不动出厂原值，命令实测有效）：

sed -i 's#^netbeans_default_options="\(.*\)"$#netbeans_default_options="\1 -J-Xms512m -J-Xmx1024m"#' /opt/netbeans/etc/netbeans.conf

验证追加成功（应输出 1）：

grep -c " -J-Xms512m -J-Xmx1024m" /opt/netbeans/etc/netbeans.conf

实测回显：

💡 说明：开发机堆可放宽到 1～2GB，独立工作机无需严控；出厂参数串（5.3 节）由 sed 原样保留。

6.2 服务器/混部主机模板（4GB 可用内存、与其他服务共处、仅命令行功能）

适用场景：与后端服务混部的 Ubuntu 服务器，仅用 --modules 系列、--open 传参等命令行能力，堆严格受限：

sed -i 's#^netbeans_default_options="\(.*\)"$#netbeans_default_options="\1 -J-Xms256m -J-Xmx512m"#' /opt/netbeans/etc/netbeans.conf
grep -c " -J-Xms256m -J-Xmx512m" /opt/netbeans/etc/netbeans.conf

实测回显（追加成功）：

并配置命令行入口：

echo 'export NETBEANS_HOME=/opt/netbeans' > /etc/profile.d/netbeans.sh
echo 'export PATH=$NETBEANS_HOME/bin:$PATH' >> /etc/profile.d/netbeans.sh
source /etc/profile.d/netbeans.sh

6.3 共享安装 + 多用户隔离模板（团队服务器、成员各自配置）

适用场景：多人共用一份 /opt/netbeans（只读），每人独立 userdir 与 cachedir。管理员在全局 conf 中保持默认；成员在自己的 shell 配置中固定私有目录：

alias netbeans='/opt/netbeans/bin/netbeans --userdir /home/ops/netbeans-user --cachedir /home/ops/netbeans-cache'

⚠️ 注意：--userdir 与 --cachedir 指向的两个目录不得相同（conf 硬性规则）；成员目录需对本人可写。

七、常见问题

Q1：改了 netbeans.conf 不生效

确认三点：改的是实际使用的那份安装（which netbeans）；参数写在正确的键里（JVM 参数必须带 -J 前缀并落在 netbeans_default_options）；改后重开实例（用户目录 lock 释放）。生效值以 var/log/messages.log 头部 System Info 为准。

Q2：追加 JVM 参数后启动失败报无法识别的选项

出厂参数已含 -J-XX:+IgnoreUnrecognizedVMOptions，理论上未知参数会被忽略；若仍失败，检查是否漏写 -J 前缀（如把 -Xmx512m 写成裸值）或把选项写进了错误的键。

Q3：--userdir 与 --cachedir 设成同一个目录

conf 注释明确「Cachedir must be different from userdir」，相同会引发缓存与配置互写异常。两者分开并在磁盘容量规划上给缓存目录留 1GB 以上余量。

Q4：升级大版本后旧配置丢失

默认新版本使用 ~/.netbeans/<新版本> 全新目录；首次启动自动导入旧版配置（var/imported/ 记录）。若需要继续用旧目录，显式 --userdir ~/.netbeans/31（跨大版本共用 userdir 有兼容风险，不建议）。

Q5：如何查看 IDE 实际使用的堆大小

除 jcmd <pid> VM.flags 外，用户目录 var/log/messages.log 与 GUI Help → About 均可核对；conf 注释指明默认堆由 JVM 自动选择并记录在 messages.log。

八、参考链接

NetBeans userdir FAQ（conf 内引用）：http://wiki.netbeans.org/FaqWhatIsUserdir
NetBeans 官方文档：https://netbeans.apache.org/kb/docs/
Apache NetBeans 下载与发行说明：https://netbeans.apache.org/download/

Apache NetBeans 31 配置参数详解

Apache NetBeans 31 配置参数详解

一、环境信息

二、前置条件

三、参数查看与修改方式

3.1 配置层次定位

3.2 查看生效的运行环境（messages.log）

3.3 修改 netbeans.conf 并验证生效

四、参数总览

五、核心参数分类详解

5.1 用户目录 netbeans_default_userdir

5.2 缓存目录 netbeans_default_cachedir

5.3 启动选项 netbeans_default_options

5.4 JDK 路径 netbeans_jdkhome

5.5 模块簇 netbeans.clusters 与 netbeans_extraclusters

5.6 JVM 内存参数

5.7 用户目录运行时文件

六、生产环境配置模板

6.1 桌面/开发工作站模板（16GB 内存、SSD、日常 GUI 开发）

6.2 服务器/混部主机模板（4GB 可用内存、与其他服务共处、仅命令行功能）

6.3 共享安装 + 多用户隔离模板（团队服务器、成员各自配置）

七、常见问题

八、参考链接

5.1 用户目录 `netbeans_default_userdir`

5.2 缓存目录 `netbeans_default_cachedir`

5.3 启动选项 `netbeans_default_options`

5.4 JDK 路径 `netbeans_jdkhome`

5.5 模块簇 `netbeans.clusters` 与 `netbeans_extraclusters`