Apache NetBeans 31 项目开发实践指南

Apache NetBeans 31 项目开发实践指南，从零创建可被 NetBeans 打开的 Maven Java 项目并完成命令行构建运行、IDE 打开、模块启停与 JVM 内存调优，命令与回显均在 Ubuntu 22.04.5 + JDK21 实测

Apache NetBeansApache NetBeans2026/10/11

Apache NetBeans 31 项目开发实践指南

目标：以一个真实 Maven Java 项目为例，演示 Apache NetBeans 31 从用户目录初始化、项目创建、命令行构建运行、IDE 打开到模块启停与 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，安装目录 /opt/netbeans，启动器 /opt/netbeans/bin/netbeans
  • Maven：Apache Maven 3.6.3（/usr/share/maven）
  • 示例项目：com.example:nb-demo:1.0.0（/tmp/nb-demo）
  • 用户目录：/root/.netbeans/31（默认）；缓存目录：/root/.cache/netbeans/31

二、前置条件

按《Ubuntu 22.04 安装 Apache NetBeans 31 指南》完成安装（方案 A/B zip 或方案 C snap 均可），netbeans --help 可正常输出；另需 Maven 用于命令行构建演示：

sudo apt-get install -y maven
mvn -version

实测回显（前两行）：

Apache Maven 3.6.3
Maven home: /usr/share/maven

三、认识用户目录（userdir）

NetBeans 把「安装目录」（只读的程序本体）与「用户目录」（个人配置、缓存、日志）分离。默认用户目录带版本号后缀，首次运行任一命令即自动创建：

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

实测回显：

31
31

查看版本标记文件：

cat /root/.netbeans/31/.lastUsedVersion

实测回显：

31

用户目录内的关键内容（实测清单）：

  • .lastUsedVersion：最近使用版本号（31）；
  • .superId：本机唯一标识（UUID 形式）；
  • config/：个人配置（Preferences/、窗口布局 Windows2/ 等）；
  • var/log/messages.log：运行日志（含完整系统信息，排障首选）；
  • var/cache/：模块缓存（all-modules.dat、all-layers.dat 等）。

💡 说明：安装目录与用户目录分离意味着多用户可共享同一份 /opt/netbeans 安装，各人配置互不影响（见「九、多用户隔离实践」）。

四、创建可被 NetBeans 打开的 Maven 项目

NetBeans 原生识别 Maven 项目（以 pom.xml 为项目锚点），无需专用项目文件。创建标准布局：

mkdir -p /tmp/nb-demo/src/main/java/com/example

写入 pom.xml（/tmp/nb-demo/pom.xml）：

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>nb-demo</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>
  <properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
</project>

写入主类 /tmp/nb-demo/src/main/java/com/example/App.java：

package com.example;

public class App {
    public static void main(String[] args) {
        System.out.println("Hello from Apache NetBeans demo project");
    }
}

💡 说明：maven.compiler.source/target 设为 17 时项目字节码目标为 Java 17，而 IDE 自身仍运行在 Java 21 上，两者互不影响；实际开发中可将项目编译目标按需调整。

五、命令行构建与运行验证

5.1 构建（mvn package）

cd /tmp/nb-demo
mvn -q package
ls target/*.jar

实测回显：

target/nb-demo-1.0.0.jar

5.2 运行（mvn exec:java）

cd /tmp/nb-demo
mvn -q exec:java -Dexec.mainClass=com.example.App

实测输出：

Hello from Apache NetBeans demo project

5.3 直接 java -jar 的已知行为

cd /tmp/nb-demo
java -jar target/nb-demo-1.0.0.jar

实测回显：

no main manifest attribute, in target/nb-demo-1.0.0.jar

💡 说明：默认 maven-jar-plugin 不写 Main-Class 清单项，java -jar 因此失败，属 Maven 标准行为；命令行验证用 exec:java 即可，或在 pom 中为 jar 插件配置 manifest classpath。

六、在 IDE 中打开项目

6.1 命令行打开（--open）

netbeans --open /tmp/nb-demo

在具备图形会话的机器上，该命令会把项目传入正在运行的 NetBeans 实例（无实例则先启动）。实测在无显示环境执行时命令静默返回（退出码 0，仅打印 DISPLAY 警告，不报错也不打开窗口）：

/opt/netbeans/platform/lib/nbexec: WARNING: environment variable DISPLAY is not set

⚠️ 前置说明：NetBeans 是 Swing 图形界面应用，打开项目、代码编辑等 GUI 操作需要桌面环境（X Window System）；本地桌面直接运行 netbeans，远程服务器用 ssh -X 或 VNC 获得图形会话后再执行。GUI 窗口内的操作回显无法在无桌面环境采集，以下以官方操作路径文字说明。

6.2 GUI 操作路径（⚠️ 需桌面环境）

  1. 菜单 File → Open Project…（快捷键 Ctrl+Shift+O），选择 /tmp/nb-demo 目录，NetBeans 以 Maven 项目类型识别并载入；
  2. 项目树上可见 Source Packages → com.example → App.java；
  3. 右键项目 Run（或按 F6）即等价于命令行的 exec:java，输出窗口显示 Hello from Apache NetBeans demo project；
  4. 右键项目 Clean and Build（Shift+F11）等价于 mvn clean package。

6.3 打开历史与项目组

--open 支持带行号打开文件（--open file.java:42）、一次传多个项目目录；--open-group/--list-groups/--close-group 管理项目组（详见《Apache NetBeans 31 常用 CLI 命令与工具详解》）。

七、模块启停实践（按需裁剪功能）

NetBeans 功能由模块（module）组成，服务器/工作机可按需禁用不需要的功能簇。先查看模块清单与状态：

netbeans --userdir /root/.netbeans --modules --list | grep "^org.netbeans.modules.groovy.kit"

实测回显（初始状态）：

org.netbeans.modules.groovy.kit                    1.65                                   Enabled

禁用不需要的 Groovy 支持套件：

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

退出码 0。再次查看确认状态变化：

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

实测回显：

org.netbeans.modules.groovy.kit                    1.65                                   Installed

状态由 Enabled 变为 Installed（已安装但禁用），且跨进程持久。

💡 说明：--modules 系列命令在无桌面服务器上完全可运行；模块状态持久化在用户目录 config/ 下。反向 --enable 的依赖联动与完整规则见《Apache NetBeans 31 常用 CLI 命令与工具详解》。

八、JVM 内存调优实践

NetBeans 是常驻 IDE 进程，与其他服务混部时应限制堆。启动时用 -J 前缀透传 JVM 参数：

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

对运行中的进程验证实际生效堆（进程存活期约 20～30 秒，需及时执行）：

PID=$(pgrep -x java | head -1)
tr "\0" "\n" < /proc/$PID/cmdline | grep -E "^-Xm[sx]"
jcmd $PID VM.flags | tr ' ' '\n' | grep -E 'MaxHeapSize=|InitialHeapSize=' | awk -F= '{printf "%s = %.0f MB\n", $1, $2/1048576}'

实测回显：

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

长期固定值写入 /opt/netbeans/etc/netbeans.conf 的 netbeans_default_options（追加 -J-Xms256m -J-Xmx512m），配置文件优先级与完整参数说明见《Apache NetBeans 31 配置参数详解》。

九、多用户隔离实践

同一台服务器上为不同用途使用独立用户目录，--userdir 即可隔离（配置、锁、日志互不干扰）：

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

实测回显：

.lastUsedVersion  .superId  config  var

团队实践建议：

  • 共享安装：/opt/netbeans 只读共享，成员各自 --userdir（或各自账号下默认 ~/.netbeans/31）；
  • 缓存目录跟随用户目录：命令行只传 --userdir 时缓存默认落在 <userdir>/var/cache（conf 注释明确该规则）；
  • 排障时先看各自用户目录的 var/log/messages.log，其头部 System Info 块记录生效的安装目录与用户目录。

十、注意事项

  • 所有 netbeans 命令行功能在无桌面服务器可用；GUI 操作（打开项目窗口、编辑器）需要桌面环境。
  • Maven 项目以 pom.xml 为锚点，不要手工创建 nbproject/ 目录；只有 NetBeans 专有 Ant 项目才使用 nbproject/。
  • --modules --list 首次运行需初始化缓存，耗时 20～30 秒属正常，后续走缓存加快。
  • 用户目录锁文件 lock 保证同一 userdir 只有一个 IDE 实例；并行测试用不同 --userdir。

十一、常见问题

Q1：--open 在服务器上执行后没有反应

无图形会话时命令静默返回（退出码 0）。先确认桌面环境：echo $DISPLAY 有输出才能弹出 IDE 窗口。

Q2：java -jar target/nb-demo-1.0.0.jar 报 no main manifest attribute

见 5.3 节说明，用 mvn exec:java 运行，或在 pom 的 jar 插件中配置 archive/manifest/mainClass。

Q3：项目上右键 Run 报找不到主类

确认 -Dexec.mainClass（命令行）或 GUI Run 配置中的主类全名 com.example.App 与源码包路径一致。

Q4：--modules --list 报 Need to use also --modules, --refresh

--list 必须与 --modules 组合：netbeans --modules --list。

Q5：如何恢复被禁用的模块

GUI：Tools → Plugins → Installed 勾选启用；命令行 --modules --enable 会先要求补齐依赖链（实测提示 Would also need to enable: ...），详见 CLI 命令详解篇。

十二、参考链接

  • NetBeans 官方 Java 应用开发文档：https://netbeans.apache.org/kb/docs/java/
  • Apache Maven 入门：https://maven.apache.org/guides/getting-started/index.html
  • NetBeans 命令行参数 wiki（conf 内引用）：http://wiki.netbeans.org/FaqWhatIsUserdir