常见问题

插件加载后无反应？

现象：在 Such 中加载插件文件后，没有任何通知，插件列表中也没有显示。

可能原因和解决方法：

window.source 未正确赋值

检查插件代码中是否包含 window.source = { ... }，且对象包含 id、name、version、author 四个必填字段。

// 确保这四个字段都有值
window.source = {
  id: 'MY_PLUGIN',
  name: '我的插件',
  version: '1.0.0',
  author: 'YourName'
}

代码语法错误

插件代码中的语法错误会导致加载失败。检查 Such 开发者控制台中的错误日志。
id 格式不规范

id 必须使用大写字母 + 下划线，例如 SUCH_MY_PLUGIN。不支持小写字母、连字符、数字开头的 id。

权限不足报错怎么办？

现象：调用 suchmusic.fetch() 时报错 未声明权限 "fetch"。

解决方法：在 window.source 中添加 permissions 字段：

window.source = {
  // ... 其他字段
  permissions: ['fetch']  // 添加所需权限
}

之后重新加载插件使新权限生效。

敏感操作确认弹窗太多？

现象：批量处理文件时，每个文件操作都弹出确认窗口。

解决方法：

在确认弹窗中勾选「本次会话不再询问」，当前运行会话中同类操作将不再弹出确认
这不会绕过安全检查，只是对当前会话免确认
重启 Such 后确认会恢复

console.log 在哪查看？

插件中的 console.log 输出会显示在两个位置：

Such 开发者控制台：在 Such 设置中开启「开发者模式」后可见
插件详情页的日志面板：如果你在 uiSchema 中配置了 log 类型的 field

如何处理异步操作？

插件方法可以是 async function：

window.source = {
  // ...

  async startProcess() {
    this.setProps({ statusText: '处理中...' })

    // ✅ 可以使用 await
    const result = await suchmusic.fetch('https://api.example.com/data')
    const data = await result.json()

    this.setProps({ statusText: '完成' })
    return data
  }
}

ℹ️ uiSchema 中的按钮绑定的方法可以是同步或异步，异步方法会自动等待完成。

如何调试插件代码？

console.log 大法：在关键位置添加 console.log 输出变量值
桌面通知：使用 window.notify() 在关键步骤通知用户
错误捕获：在所有异步操作外包裹 try/catch，捕获并显示错误详情
UI 状态显示：在 uiSchema 中添加 log 和 tag 字段，通过 setProps 实时展示状态

async debugExample() {
  console.log('当前 props:', JSON.stringify(this.props))
  try {
    const result = await suchmusic.execProgram('unknown-tool', [])
    console.log('执行结果:', result)
  } catch (err) {
    console.error('执行失败:', err.message)
    window.notify('调试: ' + err.message, 'error')
  }
}

插件可以调用多个外部 API 吗？

可以。只要在 permissions 中声明了 fetch 权限，插件可以调用任意 HTTP(S) 地址：

permissions: ['fetch']

async getData() {
  const api1 = await suchmusic.fetch('https://api1.example.com')
  const api2 = await suchmusic.fetch('https://api2.example.com')
  return { data1: await api1.json(), data2: await api2.json() }
}

可以在插件中创建多个歌单吗？

可以。歌单操作 API 没有数量限制：

permissions: ['playlist']

async batchCreate() {
  for (const name of ['歌单A', '歌单B', '歌单C']) {
    await suchmusic.createPlaylist(name, [])
    console.log('已创建: ' + name)
  }
}

插件更新机制是怎样的？

checkUpdate() 由插件开发者自行实现，宿主不提供内置更新服务
用户手动在插件管理中点击「检查更新」
如果 checkUpdate 返回 { hasNew: true }，宿主会提示用户有新版本
用户需手动下载并重新加载新版本插件文件

插件可以访问文件系统吗？

可以通过 fileOp API 访问，但需要声明 file_system 权限且每次操作需要用户确认（敏感操作）。

permissions: ['file_system']

async saveConfig() {
  const config = JSON.stringify({ version: this.version })
  await suchmusic.fileOp('write', 'config.json', config)
}

常见问题

On this page