CircuitJS1 Desktop Mod：离线电路仿真工具的技术探秘

2026-02-06 04:18:07作者：董斯意

核心架构解析

项目空间布局

CircuitJS1 Desktop Mod采用模块化分层架构，主要工作区包含5大功能模块：

📂 核心代码区 (src/main/java/com/lushprojects/circuitjs1/client)
存放电路元件实现类（如ResistorElm.java电阻元件、OpAmpElm.java运算放大器）和核心仿真引擎CirSim.java，采用GWT框架实现Java到JavaScript的跨平台转换。

💻 前端资源站 (war/)
包含网页入口文件circuitjs.html、样式表style.css和预编译电路示例（circuits/目录下的555定时器等18种经典电路模板），是应用运行时的"展示橱窗"。

🛠️ 构建工具箱 (scripts/)
提供开发辅助脚本，其中dev_n_build.js是项目构建的"交通枢纽"，集成了从GWT编译到NW.js打包的全流程控制逻辑。

🔧 补丁管理区 (patches/)
存储17个功能改进补丁（如LDRElm.patch光敏电阻优化），采用差异文件格式记录对原始代码的定制化修改。

📦 输出缓冲区 (out/)
构建完成的可执行文件会自动输出到该目录，支持Windows（x32/x64）、Linux（x32/x64）和macOS（x64/arm64）多平台分发。

💡 新手友好提示

项目架构就像餐厅厨房：src/是后厨（核心制作区），war/是用餐区（用户交互区），scripts/是传菜系统（流程控制）。理解这种分区有助于快速定位功能模块，比如要修改电阻元件特性，直接到src/client/ResistorElm.java即可。

关键入口探索

应用启动流程

CircuitJS1采用"双入口"设计，满足不同使用场景需求：

1. 桌面应用入口 🖥️

通过NW.js实现的桌面客户端启动路径：

npm start → scripts/dev_n_build.js → 启动NW.js运行时 → 加载war/circuitjs.html

关键文件解析：

package.json中的"start": "node scripts/dev_n_build.js --rungwt"定义启动命令
war/circuitjs.html加载GWT编译后的仿真引擎circuitjs1.nocache.js
自定义样式通过<link rel="stylesheet" href="font/fontello.css">引入字体图标

2. 网页应用入口 🌐

纯浏览器运行模式通过Maven构建：

npm run buildgwt → Maven编译GWT项目 → 输出到target/site/ → 直接打开index.html

启动特征：

无需安装NW.js运行时，依赖浏览器内置JavaScript引擎
受浏览器安全策略限制，本地文件操作功能会受限
适合快速演示和轻量级电路设计

💡 新手友好提示

开发时推荐使用npm run devmode启动开发模式，该模式会自动监控代码变化并热更新，就像用智能炒锅炒菜——火候（编译状态）会自动调节，无需反复启停炉灶。

配置逻辑解密

构建系统配置

项目采用Maven+Node.js双引擎驱动，关键配置文件形成"三层控制链"：

1. Maven构建蓝图 (`pom.xml`)

核心配置项：

<groupId>com.lushprojects.circuitjs1</groupId>  <!-- 项目身份标识 -->
<artifactId>circuitjs1mod</artifactId>         <!-- 构件名称 -->
<version>1.3.2</version>                       <!-- 版本号 -->
<packaging>war</packaging>                     <!-- 打包类型为Web应用 -->

<!-- GWT编译插件配置 -->
<plugin>
  <groupId>net.ltgt.gwt.maven</groupId>
  <artifactId>gwt-maven-plugin</artifactId>
  <version>1.0-rc-9</version>
  <configuration>
    <moduleName>com.lushprojects.circuitjs1.circuitjs1</moduleName>  <!-- 主模块入口 -->
    <sourceLevel>1.8</sourceLevel>  <!-- Java语言版本 -->
    <compilerArgs>
      <compilerArg>-style</compilerArg>
      <compilerArg>OBFUSCATED</compilerArg>  <!-- JS代码混淆压缩 -->
    </compilerArgs>
  </configuration>
</plugin>

2. Node脚本控制器 (`package.json`)

定义6个核心构建命令：

"scripts": {
  "dev": "node scripts/dev_n_build.js",        // 开发菜单
  "buildgwt": "node scripts/dev_n_build.js --buildgwt",  // 编译GWT
  "build": "node scripts/dev_n_build.js --buildall",     // 全平台构建
  "full": "node scripts/dev_n_build.js --fullrebuild"    // 完全重建
}

3. 多平台打包器 (`scripts/dev_n_build.js`)

该脚本实现"智能构建决策"，关键逻辑包括：

自动检测缺失的NW.js运行时并从定制源下载
根据命令行参数选择构建目标平台（如npm run build -- --win-x64仅构建Windows 64位版本）
实现增量构建优化，已编译文件不会重复处理

常见问题排查

🔍 问题1：GWT编译失败

症状：执行npm run buildgwt时提示"Java版本不兼容"
解决：检查pom.xml中<sourceLevel>1.8</sourceLevel>配置，确保本地JDK版本≥1.8但<11（GWT 2.8.2不支持高版本Java）

🔍 问题2：NW.js下载超时

症状：构建时卡在"Downloading NW.js"步骤
解决：修改dev_n_build.js中的downloadUrl为国内镜像，或手动下载对应版本（如nwjs-v0.64.1-mod1-win-x64.zip）并放入out/nwjs_cache/目录

💡 新手友好提示

Maven配置就像奶茶配方：<dependencies>是原料清单（依赖库），<plugins>是制作步骤（编译插件），<properties>是口味参数（编译选项）。修改版本号时要同步检查pom.xml和package.json，保持"配方"一致性。

项目演进史

该项目起源于Paul Falstad的Java Applet电路模拟器，2013年经Iain Sharp移植为Web应用，2020年SEVA77通过NW.js封装为桌面版，2023年升级支持Apple Silicon芯片。技术栈演进逻辑：Java→GWT→NW.js，始终遵循"保留核心功能+扩展平台支持"的迭代路线。