Sciter.js指南 - 桌面GUI开发时使用第三方模块

在写桌面的 GUI 程序时，我们可能需要用到很多其它的东西，但我们又不想自己来全面制造一次轮子，比如 npmjs 有很多第三方模块, 有不少我们是直接可以使用的，提前是它必须是纯 JS. 下面我们就介绍一下怎么样使用。

---

1. Sciter.js 与常见运行时对比

大家给 Sciter.js 当前一个类似于小型更加高效的 nodejs 就好，它解析是基于 QuickJS。这有一些基本的功能的对比。

特性	浏览器	Node.js	Sciter.js
DOM / CSS / UI	✅	❌	✅ (自带 UI 引擎)
CommonJS require()	❌	✅	✅
ES Modules import	✅(现代浏览器)	✅	✅ (Ecma‑2020)
Node 全局 (process,Buffer)	❌	✅	❌(需修改)
原生 C/C++ 扩展	❌	✅ (node‑addon)	✅

结论： 任何依赖 纯 JavaScript、不调用 Node 原生 API 的 npm 包，都有机会在 Sciter 里运行，所以有一定的前提才可以使用，主要集中在语法，它本身的所需的环境。下面我会结合文档和论坛中的方法给大家介绍二种使用的方式。

---

2. 常见接入路径

方案 A --- 打包工具"一步到位" （推荐）

1. 在项目根目录执行

装一个 rollup 打包的工具。

npm init -y && npm i rollup @rollup/plugin-commonjs

2. 新建 rollup.config.js：

配置打包工具

```
import commonjs from "@rollup/plugin-commonjs";
export default {
  input: "src/main.js",       // 入口脚本 (ESM 或 CJS 均可)
  output: {
    file: "dist/app.bundle.js",
    format: "iife"             // 单文件自执行，最兼容 Sciter
  },
  plugins: [commonjs()]        // 将 require() 转为 ESM
};
```

2. 生成打包后的文件

npm run rollup -c

这时会生成 → 生成 dist/app.bundle.js。

4. 在 Sciter HTML 中引入

    <script src="dist/app.bundle.js"></script>

优点： 体积可控、无运行时解析开销、打包阶段即可报错。

方案 B --- 运行时解析 setModuleUrlResolver()

当你想直接 import "lodash-es" 而不预打包时：

import * as sctr from "@sciter";
import * as sys  from "@sys";  // 自带 libuv‑fs
const { fs, path } = sys;

a// 1) 安装依赖：`npm i lodash-es` (需 ESM 版本)

// 2) 注册解析器
sctr.setModuleUrlResolver((name, docDir) => {
  if (name.includes(".") || name.startsWith("/")) return false; // 只处理裸包名
  const base = path.join(docDir, "node_modules", name);
  const pkg  = path.join(base, "package.json");
  if (fs.existsSync(pkg)) {
    const meta  = JSON.parse(fs.readFileSync(pkg));
    const entry = meta.module || meta.browser || meta.main || "index.js";
    return path.join(base, entry);   // 返回绝对文件路径
  }
  return false; // 交给 Sciter 默认规则
});

// 3) 现在可裸导入
import debounce from "lodash-es/debounce.js";
Window.this.on("ready", () => debounce(()=>console.log("OK"),200)());

缺点： 需自己处理路径、package.json 解析；CJS 包仍需预转换。

---

3. npm 包兼容性速查

大家在对比哪些包可以兼容时，需要检查当前想使用的模块的以下几个方面

场景	处理方法
依赖 Node 全局 ( process.env )	globalThis.process = { env: {} } 简易修改或打包时用插件替换
纯 CommonJS (module.exports)	用 Rollup/esbuild 转成 ESM，或在打包时 format:"iife"
原生 Node 扩展 (.node)	不支持；寻找纯 JS 替代
浏览器专属 API (fetch, localStorage)	Sciter v20+ 有 fetch；否则引入 polyfill 或改用 @sys.http
大量小文件依赖	强烈建议打包，避免运行期读磁盘多次

---

4. 常见报错与解决

报错/现象	可能原因	解决方案
Module not found	setModuleUrlResolver 未匹配；路径拼错	打印回调参数，确认返回了绝对路径
require is not defined	在 <script type="module"> 内使用 require	改为 import 或在打包阶段统一格式
process is undefined	包假设 Node 环境	垫片 globalThis.process = {env:{}} 或 rollup‑plugin‑polyfill‑node
QuickJS 解析 __proto__: null 报错	ES2022 新语法	在打包器中加 Babel preset 或升级 Sciter 版本

---