快速开始

从零写出一个能跑的脚本，大约五分钟。

1. 打开自定义脚本页

设置 → 系统 → 开发者模式 打开，左侧导航会多出「自定义脚本」，点进去。

2. 新建脚本

点右上角 新建脚本，填一个文件名。不写 .js 后缀会自动补上：

user-stats.js

创建后会自动带一份起手模板，并切到「代码」标签页。

3. 写点东西

把模板换成下面这段——统计每个用户各有多少作品：

exports.meta = {
  name: '用户作品数统计',
  description: '按作品数量从多到少列出所有用户'
}

exports.run = async (api) => {
  const rows = api.db.query(`
    SELECT u.nickname, COUNT(p.id) AS cnt
    FROM users u
    LEFT JOIN posts p ON p.user_id = u.id
    GROUP BY u.id
    ORDER BY cnt DESC
  `)

  rows.forEach((row) => api.log(`${row.nickname}: ${row.cnt}`))

  return { users: rows.length }
}

4. 保存并运行

按 ⌘/Ctrl + S 保存，或者点右下角「保存」。 标题栏的「未保存」标记消失就说明存好了。

然后点右上角 运行。页面会自动切到「输出」标签页，api.log 的内容实时往下刷：

09:41:02  ▶ 开始运行「用户作品数统计」
09:41:02  张三: 128
09:41:02  李四: 96
09:41:02  ✔ 运行完成，耗时 12 ms

运行会先保存

有未保存的修改时点「运行」，会先把当前内容存盘再执行——脚本跑的是磁盘上的文件， 不先保存就会跑到旧代码。

5. 出错了怎么办

写错语法或忘了导出 run，保存时不会被拦住，但脚本条目上会出现一个橙色警告， 详情栏里写明原因，「运行」按钮变灰：

脚本必须导出 run 函数：exports.run = async (api) => {}

改完再保存，警告会消失。保存永远是允许的，写到一半的草稿不会被挡在门外。

运行时报错则会在输出面板里以红色显示，并带上出错信息：

09:41:02  ✖ 运行失败：api.db.query 仅允许 SELECT / WITH 查询，写入请用 api.db.exec

6. 从内置脚本抄起

不想从空白开始，可以选一个内置脚本，在「代码」标签页读它的源码， 点 以此为模板新建 得到一份可编辑的副本。内置脚本和你自己写的是同一套写法， 复制过来直接就能跑。

接下来

• 脚本要跑很久、需要中途停止？看 运行与停止
• 想知道 api 上还有什么？看 API 参考
• 想看完整的实战例子？看 示例脚本