Node 后端
需要 npm 包、原生模块或 Node 内置模块时,给插件写一个 preload 脚本。它在插件独立的 Node.js 进程里运行,页面直接 await 调用它挂出的函数。
先想想是否需要
很多事情页面里就能做,不需要 Node:
| 需求 | 页面里直接用 |
|---|---|
| 读写文件、列目录、监听变化 | ling.fs |
| 运行命令行程序 | ling.spawn |
| 访问网络 | fetch(默认允许,见 权限) |
| 压缩解压 ZIP | ling.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 报错、进程退出)时,调用以
unavailablereject 并带原因。不会自动重启,重新打开插件就是新进程。 - 插件的自建窗口和主页面共用同一个 preload 和它的状态。
环境与日志
- 进程继承 lingtools 的环境变量。macOS 上从访达启动 lingtools 时,
PATH里可能没有 Homebrew、nvm 的目录,调用外部命令时写绝对路径或自己补PATH。 - preload 里的
console.*和子进程输出会写进 lingtools 的日志文件,调试时去那里看。日志位置见 调试与常见问题。
不支持
- preload 里没有 DOM,不能
require('electron')。 - 不能把整个模块挂给页面(如
window.https = require('https')),把用到模块的代码包成函数。 - 自建窗口不能有自己的 preload。