WPS如何加载npm安装的wpsjs加载项？

Question

常见问题： 使用 `npm install @wpsjs/addin` 安装官方 SDK 后，开发者常误以为执行 `npm run dev` 或 `npm start` 即可直接在 WPS 中加载加载项，但实际 WPS 并不识别 node_modules 中的源码或 npm 包路径。WPS 加载项必须以符合规范的 ZIP 包（含 manifest.xml、HTML/JS 资源及正确签名）形式，通过「开发工具 → 加载项管理 → 本地安装」手动导入；而 npm 安装仅提供开发依赖（如 TypeScript 类型定义、构建脚本、CLI 工具等），不生成可运行的加载项包。若未执行 `npm run build` 构建生产资源、未配置正确的 manifest.xml（如 AppId、Hosts、Permissions）、或未用 WPS 开发者工具签名，将导致“加载失败”“无效清单文件”“无法识别的插件格式”等错误。简言之：npm 安装 ≠ 加载项部署，它只是开发起点，而非运行入口。

Answer 1

```html

一、认知层：厘清 npm 安装的本质与加载项生命周期

开发者首次接触 @wpsjs/addin 时，常将 npm install 类比为「安装插件」——这是典型的平台迁移认知偏差。WPS 加载项（Add-in）本质是基于 Office JS 规范的 Web 应用容器化产物，其运行模型严格遵循「声明式清单（manifest.xml）→ 静态资源打包 → WPS 运行时沙箱加载」三阶段闭环。而 npm install @wpsjs/addin 仅完成开发链路的依赖注入：提供 @types/wps 类型定义、wps-addin-cli 构建工具、webpack.config.js 模板及 manifest.xml 样例。它不生成任何可被 WPS 直接解析的二进制包，亦不注册任何系统级入口。

二、构建层：从源码到 ZIP 包的关键流水线

真正的加载项交付物必须经由标准化构建流程生成。典型工作流如下：

src/ (TS/JS/HTML/CSS)
  ├─ manifest.xml ← 必须含有效 AppId、<Hosts>（如 <Host Name="WPS.Document"/>）、<Permissions>（如 "ReadWriteDocument"）
  ├─ taskpane.html
  └─ taskpane.js
↓ npm run build（调用 wps-addin-cli build）
dist/
  ├─ manifest.xml（校验后输出）
  ├─ taskpane.html（内联 CSS/JS 或正确引用 dist/ 资源路径）
  ├─ taskpane.js（已转译、压缩、source-map 剥离）
  └─ assets/（图片、字体等静态资源）
↓ zip -r myaddin.zip manifest.xml taskpane.* assets/
↓ 使用 WPS 开发者工具签名（生成 .sig 文件并注入 ZIP）

三、配置层：manifest.xml 的 7 大致命陷阱（高频报错根源）

字段	常见错误	验证方式
<AppId>	使用占位符 XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX 未替换为真实 GUID	WPS 开发者工具「应用管理」中申请后复制粘贴
<Hosts>	误写为 <Host Name="Word">（WPS 不识别 Office 命名空间）	必须为 "WPS.Document", "WPS.Spreadsheet", "WPS.Presentation"
<Permissions>	设为 "ReadWriteMailbox"（Outlook 专属权限，在 WPS 中无效）	仅支持 "ReadDocument", "ReadWriteDocument", "Restricted"

四、签名层：为何“本地安装”失败？签名不是可选步骤

WPS 自 2023 年起强制要求所有本地加载项 ZIP 必须含有效数字签名（.sig）。未签名 ZIP 将直接触发 ERR_INVALID_ADDIN_FORMAT；签名密钥过期或证书链不完整则报 ERR_SIGNATURE_VERIFICATION_FAILED。签名过程不可跳过，且必须使用官方 WPS 开发者工具 完成——第三方签名工具（如 signtool.exe）生成的证书 WPS 不认可。

五、调试层：dev-server ≠ 加载项热更新 —— 真实调试路径图解

graph LR
  A[启动 dev-server] -->|localhost:3000/taskpane.html| B[浏览器访问调试 UI]
  B --> C{WPS 是否加载此 URL？}
  C -->|否| D[手动修改 manifest.xml 的 <SourceLocation> 指向 http://localhost:3000/taskpane.html]
  D --> E[WPS 启动时自动拉取远程 HTML]
  E --> F[需开启 CORS、HTTPS 代理或禁用 WPS 安全策略（仅限开发机）]
  C -->|是| G[仍需 manifest 签名 + 本地安装 ZIP，否则提示 “清单文件未签名”]

六、工程实践：5 年以上开发者应建立的自动化检查清单

1. CI/CD 流水线中集成 wps-addin-cli validate 校验 manifest 结构合法性
2. 构建脚本强制执行 npm run build && npm run sign 双阶段原子操作
3. Git Hook（pre-commit）拦截未填写 <AppId> 或空 <ProviderName> 的 manifest 提交
4. 开发环境启用 WPS_DEBUG=1 环境变量，捕获控制台中 wps.runtime 初始化异常
5. 生产构建产物 ZIP 必须通过 wps-addin-cli verify myaddin.zip 全链路验证

七、架构视角：为什么 WPS 不支持 node_modules 热加载？

根本原因在于安全模型差异：Node.js 是通用运行时，而 WPS 加载项运行于受限 Web View（Chromium Embedded Framework），其资源加载策略完全隔离于 Node.js 生态。WPS 主进程禁止访问任意本地路径（包括 node_modules），仅允许从 ZIP 包内解压后的内存文件系统或预注册 HTTP 端点读取资源。这与 VS Code 插件（基于 Electron）、Figma 插件（基于 iframe 沙箱）的设计哲学一致——强调交付物确定性、攻击面收敛与跨版本兼容性保障。

```