NW.js 入门教程：环境搭建与运行第一个 Hello World

一、认识 NW.js：它与普通网页及其他方案的本质差异

在开始操作前，有必要明确 NW.js 的运行特征。很多初学者容易产生一种直觉误解：“NW.js 不就是一个套了壳的浏览器吗，为什么不直接在 Chrome 中双击 HTML 打开？”

这种说法看似合理，因为 NW.js 的渲染窗口确实由开源的 Chromium 提供，页面排版所用的技术也完全是标准的 HTML、CSS 和 JavaScript。但两者的核心分歧在于安全沙箱与操作系统调用权限。普通浏览器严格禁止网页 JavaScript 直接访问本地磁盘、执行底层系统命令或探测硬件参数；而 NW.js 在底层将 Chromium 渲染引擎与 Node.js 运行时进行了深度融合。

另一个常见的对比是 Electron。虽然两者都能用 Web 技术开发桌面客户端，但在上下文设计上存在明显差别。在 Electron 中，主进程（Node.js 环境）与渲染进程（Chromium 网页环境）是完全隔离的两个独立进程，网页如果想要读取文件，必须通过预加载脚本（preload）或 IPC 进程间通信向主进程发起请求。而在 NW.js 中，Node.js 与 DOM 运行在同一个统一上下文（Mixed / Unified Context）中。这意味着你可以在 <script> 标签里直接书写 const fs = require('fs') 或 const os = require('os')，并把读取到的系统信息直接通过 document.getElementById 写入网页节点，省去了冗长的通信胶水代码。

二、环境准备：下载与安装 NW.js SDK 运行环境

NW.js 的安装机制非常轻量：它不需要像传统桌面软件那样经历繁琐的安装向导，官方分发的本质上是一个已经完成编译打包的独立可执行程序压缩包。

1. 认准版本类型：必须选择 SDK 版本

在下载页面中，官方针对每个版本通常提供两种构型（Flavors）：

• Normal（普通版）：仅包含运行时，体积较小。但该版本去除了 Chromium 的开发者工具（DevTools），在窗口中按下 F12 或右键检查不会有任何反应。
• SDK（开发版）：文件名中明确带有 -sdk- 标识。内置了完整的 DevTools 调试面板，能够输出控制台日志、设置断点并检查 DOM 树。在学习与开发阶段，必须下载 SDK 版本，否则出现脚本语法错误或路径引用失效时，将无法看到具体的错误报错堆栈。

2. 解压与环境变量配置

下载对应操作系统的压缩包后，将其解压到本地合适的目录。例如：

• Windows：解压到 D: ools wjs-sdk\，该目录下能看到 nw.exe。
• macOS：解压后得到 nwjs.app，可移动至 /Applications/nwjs-sdk.app 或个人开发工具目录。
• Linux：解压后可看到可执行文件 nw。

为了在任意工程目录下均可方便地输入 nw 启动项目，建议将该可执行文件所在目录加入系统环境变量 PATH 中。如果你暂时不想改动环境变量，也可以在后续执行命令时直接使用该文件的绝对路径，或者在当前工程中通过 npx nw 方式驱动。

三、构建第一个 Hello World 工程

NW.js 运行一个项目所需的文件极少。一个合法的最小工程只需要一个根目录以及两个文件：记录元信息的 package.json，以及承载界面与逻辑的 index.html。

1. 创建工程目录

在本地终端中创建一个新的项目文件夹并进入该目录：

mkdir nw-hello-world
cd nw-hello-world

2. 编写清单文件 package.json

在 nw-hello-world 目录下新建文件 package.json。这个文件是 NW.js 启动时读取的入口清单，负责告知运行时主界面在哪里、初始窗口多大、是否允许调整尺寸等。写入以下完整配置：

{
  "name": "nw-hello-world",
  "version": "1.0.0",
  "main": "index.html",
  "window": {
    "title": "我的第一个 NW.js 窗口",
    "width": 780,
    "height": 520,
    "min_width": 500,
    "min_height": 380,
    "resizable": true,
    "position": "center"
  }
}

关键字段解释：

• name：应用英文包名，需符合 npm 包名规范（全小写、无特殊空格）。
• main：最核心字段。指定窗口加载的第一个资源路径，通常是相对路径的 HTML 文件（如 index.html），也可以是指向远程的 URL 或 Node.js 启动脚本。
• window：桌面窗口属性配置对象。width 和 height 控制初始窗口像素尺寸；position: "center" 让窗口弹出时自动在屏幕居中显示。

3. 编写用户界面与集成脚本 index.html

在同一目录下创建 index.html。为了充分验证 NW.js 区别于普通浏览器的能力，我们不仅渲染常规的文本标题，更直接在内嵌 <script> 中引入 Node.js 内置的 os 与 process 模块，读取宿主机的操作系统平台、CPU 架构以及底层环境版本号：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>Hello NW.js</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
      background-color: #F8F9FA;
      color: #2D3748;
      padding: 30px;
      margin: 0;
    }
    .card {
      background: #FFFFFF;
      border: 1px solid #E2E8F0;
      border-radius: 8px;
      padding: 24px;
      box-shadow: 0 2px 6px rgba(0, 0, 0, 0.05);
    }
    h1 {
      font-size: 22px;
      color: #1A202C;
      margin-top: 0;
    }
    .info-list {
      margin-top: 16px;
      list-style: none;
      padding: 0;
    }
    .info-list li {
      padding: 8px 0;
      border-bottom: 1px solid #EDF2F7;
      font-size: 14px;
      display: flex;
    }
    .info-list .label {
      width: 140px;
      font-weight: 600;
      color: #718096;
    }
    .info-list .value {
      color: #2B6CB0;
      font-family: monospace;
    }
  </style>
</head>
<body>
  <div class="card">
    <h1>Hello World, NW.js!</h1>
    <p>当前页面正运行在混合上下文环境中，以下数据由前端脚本直接调用 Node.js API 采集：</p>
    
    <ul class="info-list">
      <li><span class="label">操作系统平台：</span><span class="value" id="val-platform">加载中...</span></li>
      <li><span class="label">CPU 处理器架构：</span><span class="value" id="val-arch">加载中...</span></li>
      <li><span class="label">NW.js 运行版本：</span><span class="value" id="val-nw">加载中...</span></li>
      <li><span class="label">内置 Node.js 版本：</span><span class="value" id="val-node">加载中...</span></li>
      <li><span class="label">内置 Chromium 版本：</span><span class="value" id="val-chromium">加载中...</span></li>
    </ul>
  </div>

  <script>
    // 验证核心特性：直接在网页内引入 Node 原生模块，无需任何构建工具或打包器
    const os = require('os');

    // 将系统原生接口数据填充到 HTML DOM 节点中
    document.getElementById('val-platform').textContent = `${os.type()} (${os.platform()})`;
    document.getElementById('val-arch').textContent = os.arch();
    document.getElementById('val-nw').textContent = process.versions['nw'] || '未知';
    document.getElementById('val-node').textContent = process.versions['node'];
    document.getElementById('val-chromium').textContent = process.versions['chromium'];

    console.log('Hello World 启动就绪，Node 环境正常绑定！');
  </script>
</body>
</html>

四、运行与结果验证

完成上述两个文件的编写后，即可启动并观察实际运行效果。执行 NW.js 的基本规则是：将应用的根目录（即含有 package.json 的文件夹路径）作为参数传递给 nw 二进制程序。

1. 各平台的具体启动命令

请确保终端当前正处于 nw-hello-world 目录下，根据你的系统选用相应方式：

方式一：如果已将 nw 配置进系统环境变量

# 启动当前所在目录
nw .

方式二：使用解压路径直接调用

• Windows（CMD 或 PowerShell）：

  D:	ools
  wjs-sdk
  w.exe .

• macOS（Terminal）：

  /Applications/nwjs-sdk.app/Contents/MacOS/nwjs .

• Linux（Bash）：

  /opt/nwjs-sdk/nw .

2. 打开 DevTools 进行调试验证

由于我们下载的是 SDK 版本，在弹出的窗口内按下键盘上的 F12（macOS 快捷键通常为 Cmd + Option + I），Chromium 开发者工具面板会立刻在侧边或独立窗口中弹出。

在 DevTools 的 Console（控制台）中，不仅可以看到代码中输出的日志，更可以直接在命令行交互输入测试 Node API：

// 在 DevTools Console 中输入并回车：
require('fs').readdirSync('.')
// 输出：['index.html', 'package.json']

如果能正确输出当前目录下的文件名数组，便证明 Node.js 的文件读写与当前网页界面已经处于同一个执行空间内，环境搭建完全成功。

五、新手高频问题排查与注意事项

在初次搭建过程中，如果程序未按预期工作，可以对照以下诊断清单按顺序排查：

六、总结与后续实践路径

完成本文的步骤后，你已经成功掌握了 NW.js 最核心的开发链路：理解其 Chromium 与 Node.js 结合的无缝上下文架构，通过 package.json 声明桌面窗口属性，并在 index.html 中直接书写具备本地系统交互能力的 JavaScript 代码。

在此基础之上，你可以继续尝试引入第三方 npm 模块（如 sqlite3 进行本地数据库存储、serialport 进行硬件串口通信），或者将现有的 Vue、React 前端构建工程打包产物直接放置为 main 入口，逐步扩展出功能强大的企业级桌面应用。