Skip to content

Node 后端 ​

需要 npm 包、原生模块或 Node 内置模块时,给插件写一个 preload 脚本。它在插件独立的 Node.js 进程里运行,页面直接 await 调用它挂出的函数。

先想想是否需要 ​

很多事情页面里就能做,不需要 Node:

需求页面里直接用
读写文件、列目录、监听变化ling.fs
运行命令行程序ling.spawn
访问网络fetch(默认允许,见 权限)
压缩解压 ZIPling.zip
处理图片ling.image

preload 需要 node 权限:它以用户的全部权限运行,能绕过其他所有权限,用户在安装和审核时会特别留意。只有真的需要 npm 生态时再用。

写法 ​

plugin.json:

json
{
  "main": "dist/index.html",
  "preload": "preload.cjs",
  "permissions": ["node"]
}

src-ling/preload.cjs:往 window 上挂什么都行,页面里会出现同名全局。

js
const fs = require('node:fs/promises')
const path = require('node:path')

window.services = {
  async search(dir, keyword, onProgress) {
    const names = await fs.readdir(dir)
    const hits = []
    for (const [i, name] of names.entries()) {
      if (name.includes(keyword)) hits.push(path.join(dir, name))
      onProgress(Math.round(((i + 1) / names.length) * 100)) // 回调会推回页面
    }
    return hits
  },
}

// preload 里也有 ling,和页面同一套 API
ling.onPluginEnter(({ code }) => {
  console.log('进入入口', code)
})

页面:

ts
window.ling.onNodeReady(async () => {
  const hits = await window.services.search('/Users/me/Documents', 'report', (percent) => {
    progress.value = percent
  })
})

TypeScript 下给页面声明一下类型:

ts
// src/env.d.ts
declare global {
  interface Window {
    services: {
      search(dir: string, keyword: string, onProgress: (percent: number) => void): Promise<string[]>
    }
  }
}
export {}

文件格式 ​

  • .cjs 按 CommonJS 执行;.mjs 按 ES Module 执行(可以顶层 await);.js 跟随最近的 package.json 的 type。
  • 依赖:用打包工具打成单文件,或者把 node_modules 一起放进插件目录。
  • 原生模块必须按 Node 26 编译,或使用 N-API。

调用规则 ​

情况说明
调用全部异步:await window.services.foo()
能传什么结构化克隆支持的全部类型(对象、数组、Date、Map、Set、BigInt、Error、二进制、循环引用),以及参数里的回调函数。单次不超过 16 MiB,回调每次不超过 1 MiB
传不过去的活对象(模块、socket、类实例的方法):把对象留在 preload 里,只给页面一个 ID,后续按 ID 调用
非函数成员如 window.services.version = '1.0':preload 执行完时拷贝一份给页面,之后不再同步;会变的数据写成函数
延后挂上的成员preload 执行完之后才挂到 window 上的成员,页面看不到
保留名字与页面全局重名,或叫 ling / utools / exports 的成员不交给页面
preload 抛错页面的调用以同名 Error reject

生命周期 ​

  • 每个插件实例一个 Node 进程。插件页面创建时启动,插件销毁时结束(连同它启动的子进程)。
  • 第一次使用 Node 插件时,lingtools 会弹窗下载 Node.js 运行时;第一次打开插件、插件升级后第一次打开时也可能页面先出现、函数后就绪。所以页面加载时就要调用 preload 的,放进 ling.onNodeReady() 里。
  • 后端没能就绪(用户取消下载、preload 报错、进程退出)时,调用以 unavailable reject 并带原因。不会自动重启,重新打开插件就是新进程。
  • 插件的自建窗口和主页面共用同一个 preload 和它的状态。

环境与日志 ​

  • 进程继承 lingtools 的环境变量。macOS 上从访达启动 lingtools 时,PATH 里可能没有 Homebrew、nvm 的目录,调用外部命令时写绝对路径或自己补 PATH。
  • preload 里的 console.* 和子进程输出会写进 lingtools 的日志文件,调试时去那里看。日志位置见 调试与常见问题。

不支持 ​

  • preload 里没有 DOM,不能 require('electron')。
  • 不能把整个模块挂给页面(如 window.https = require('https')),把用到模块的代码包成函数。
  • 自建窗口不能有自己的 preload。