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

# 从注册表安装插件

`POST /jsplugins/registry/install`

从注册表中的 download_url 下载 ZIP 并安装插件。如果 entry_path 已存在则自动走更新路径。支持 GitHub 代理。可选传入 token 字段用于从需要认证的私有源下载；若未提供 token 但提供了 source_url（「全部」聚合模式），后端会自动从 plugin_registries 配置解析该源存储的 token。

## Request body

- HandlersRegistryInstallRequest
  - `download_url` string
  - `github_proxy` string
  - `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 认证的路径前缀
      - `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` — 请求格式错误
- `500` — 下载或安装失败

---

[API](https://skmtc.dev/songloft-org/apis/songloft-api.md) · [All operations](https://skmtc.dev/songloft-org/apis/songloft-api/llms.txt) · [OpenAPI document](https://skmtc.dev/songloft-org/apis/songloft-api/revisions/7cbe0940a38b?raw)