title: WPS 插件注册流程 date: 2026-08-27 tags:

WPS
加载项注册
publish.html
私有化 status: active

WPS 插件注册流程

WPS私有化加载项通过网页注册，不安装EXE。用户打开publish.html，页面唤起WPS本地中继并写入加载项URL。

1. 最短注册步骤

部署wps-com静态目录；
浏览器访问publish.html；
允许浏览器打开ksowpscloudsvr://；
等待页面连接WPS本地中继；
点击安装或注册；
重启WPS演示；
检查顶部是否出现AiPPT Tab。

成功判定：重启WPS演示后顶部出现AiPPT Tab。

注册页还可以列出和删除已注册的WPS加载项。

注册失败按现象查 6. 注册失败现象，平台差异查 7. Windows注册检查和 8. Linux/UOS注册检查。部署目录要求见 2. 注册所需文件。

2. 注册所需文件

部署目录至少包含：

wps-com/
├── manifest.xml
├── ribbon.xml
├── index入口脚本
├── images/
├── offline/
└── 其他静态资源
 
publish.html

publish.html中的serverUrl必须指向wps-com目录，而不是总ZIP或online页面目录。

3. 注册时序

sequenceDiagram
    actor User as 用户
    participant Browser as 浏览器
    participant Protocol as ksowpscloudsvr协议
    participant Relay as WPS本地HTTP中继
    participant WPS as WPS演示
    participant Server as 私有化静态服务

    User->>Browser: 打开publish.html
    Browser->>Protocol: ksowpscloudsvr://start=RelayHttpServer
    Protocol->>WPS: 唤起WPS本地服务
    WPS->>Relay: 启动本地HTTP中继
    Browser->>Relay: 注册jsaddons地址
    Relay->>WPS: 保存加载项serverUrl
    WPS->>Server: 请求manifest.xml和ribbon.xml
    Server-->>WPS: 返回加载项静态文件
    WPS-->>User: 显示AiPPT Ribbon

4. publish.html如何生成

脚本：

packages/aippt-plugin-wps-com/scripts/generate-wps-publish.mjs

命令：

pnpm --filter aippt-plugin-wps-com publish:html

内部执行：

清空wpsjs publishlist.json
→ npx wpsjs publish --serverUrl <url>
→ 生成wps-addon-publish/publish.html
→ 回写public/publish.html
→ 回写dist/wps-com/publish.html
→ 恢复publishlist.json

serverUrl优先级：

WPS_PUBLISH_SERVER_URL环境变量；
private-deploy-config.json中的wpsComBaseUrl；
本机局域网地址http://<ip>:3889/。

5. 本地开发注册

启动开发服务：

pnpm --filter aippt-plugin-wps-com dev

默认端口：

生成本地publish页面：

WPS_PUBLISH_SERVER_URL=http://<开发机局域网IP>:3889/ \
pnpm --filter aippt-plugin-wps-com publish:html

WPS所在机器必须能访问开发机IP和3889端口。

6. 注册失败现象

现象	检查
点击无反应	浏览器外部协议权限、协议注册
页面显示连接失败	WPS本地Relay没有启动
注册成功但无Ribbon	ribbon.xml URL、WPS缓存、重启WPS
Ribbon有按钮但无图标	images/meta.json和图片路径
按钮打开404	pluginBaseUrl和offline目录
页面能开但API失败	apiBaseUrl、反向代理和Token

7. Windows注册检查

WPS已经安装；
ksowpscloudsvr协议已注册；
浏览器允许外部协议；
本地Relay端口没有被安全软件拦截；
serverUrl返回HTTP 200；
manifest.xml和ribbon.xml可直接访问。

8. Linux/UOS注册检查

Linux桌面环境可能错误处理自定义协议。重点检查：

ksowpscloudsvr://

已知问题：

DDE或dde-open把私有协议改成http://；
WPS按大小写匹配协议；
浏览器没有外部协议权限；
WPS没有注册RelayHttpServer；
UOS安全策略拦截协议启动。

排查顺序：

从终端或浏览器直接打开协议；
确认WPS进程收到调用；
确认本地Relay启动；
用浏览器开发者工具检查publish页面请求；
直接访问serverUrl下的manifest.xml和ribbon.xml。

9. 代码位置

packages/aippt-plugin-wps-com/public/publish.html
packages/aippt-plugin-wps-com/public/ribbon.xml
packages/aippt-plugin-wps-com/manifest.xml
packages/aippt-plugin-wps-com/scripts/generate-wps-publish.mjs
scripts/private-deploy-config.json

AiPPT 插件文档

探索