---
title: "从注册表安装插件"
method: POST
path: "/jsplugins/registry/install"
tags: ["JS插件管理"]
---

# 从注册表安装插件

`POST /jsplugins/registry/install`

从注册表中的 download_url 下载 ZIP 并安装插件。如果 entry_path 已存在且属于同一作者，则自动走更新路径。支持 GitHub 代理（含 api.github.com 私有仓库 Release 资源的下载，代理端需开启 FORWARD_AUTHORIZATION_API 才会转发 token）。可选传入 token 字段用于从需要认证的私有源下载；若未提供 token 但提供了 source_url（「全部」聚合模式），后端会自动从 plugin_registries 配置解析该源存储的 token。
若 entry_path 已被本地一个**不同作者**的插件占用，返回 409 且不做任何写入（不落盘、不动 static 目录、不改数据库）。前端应向用户说明会替换原插件后，带 overwrite=true 重发本请求。

## Request body

- HandlersRegistryInstallRequest
  - `download_url` string
  - `github_proxy` string
  - `overwrite` boolean — Overwrite 为 true 时允许覆盖掉本地已装的同 entry_path 但不同作者的插件。 默认 false：这种情况返回 409，由前端二次确认后带该字段重发。
  - `source_url` string — SourceURL 插件所属订阅源 URL。「全部」聚合模式安装时回传： 当未显式提供 token 时，后端据此从 plugin_registries 配置解析该源的 token。
  - `token` string

## Response `200`

安装结果（更新已有插件）

- HandlersJsPluginUploadResponse
  - `failed` integer
  - `message` string
  - `results` HandlersJsPluginUploadResult[]
    - `error` string
    - `file_name` string
    - `plugin` JspluginJSPlugin
      - `author` string
      - `created_at` string
      - `description` string
      - `download_url` string
      - `entry_hash` string — main.js/main.jsc 内容 SHA256
      - `entry_path` string — 路由前缀（如 "myplugin"）
      - `external_paths` string[] — 可访问的外部绝对路径目录
      - `file_mod_time` string
      - `file_path` string — ZIP 文件相对路径
      - `homepage` string
      - `icon` string
      - `id` integer
      - `license` string
      - `main` string — 入口文件路径（如 "main.js"）
      - `min_host_version` string
      - `name` string
      - `permissions` string[] — 权限列表
      - `public_paths` string[] — 无需 JWT 认证的路径前缀
      - `render_engine` string — RenderEngine 插件页渲染引擎："webview" / "webf"；空串 = 跟随宿主默认（当前 webview）。 刻意不加 omitempty：客户端需要能稳定读到该字段并自行把空串映射为默认引擎。
      - `status` 'active' | 'inactive' | 'error'
      - `update_url` string
      - `updated_at` string
      - `version` string
      - `zip_hash` string — ZIP 文件 SHA256
    - `success` boolean
  - `success` integer
  - `total` integer

## Other responses

- `201` — 安装结果（新插件）
- `400` — 请求格式错误
- `409` — entry_path 已被另一个作者的插件占用，需用户确认后带 overwrite=true 重试
- `500` — 下载或安装失败

---

[API](https://skmtc.net/songloft-org/apis/songloft-api.md) · [All operations](https://skmtc.net/songloft-org/apis/songloft-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/songloft-org/songloft-api/versions/ee41778dbf8f/schema)