WPS加载项部署运行问题排查方法

所有问题排查都是基于加载项目录结构没有问题的情况下进行排查的，必须确保ribbon.xml和index.html在项目根目录下，且index.html中引入的js的路径没有问题。

排查首先开启调试器：

1. oem.ini地址

windows

安装路径\WPS Offlce\一串数字（版本号）\offlce6\cfgs\

linux

/opt/kingsoft/wps-office/office6/cfgs/

uos

/opt/apps/cn.wps.wps-office-pro/files/kingsoft/wps-office/office6/cfgs/

2. 国产机修改之后，需要重启WPS

普通Linux

终端执行 quickstartoffice restart

uos

终端执行

cd /opt/apps/cn.wps.wps-office-pro/files/bin

./quickstartoffice restart

1、排查问题导航

1.1 无法唤起WPS客户端：排查 version或runParams接口报错

1.2 WPS打开了，但是文档未打开，分两种情况(确保oem.ini中Support栏下配置了JsApiShowWebDebugger=true)

1.2.1 WPS中点击新建，alt+f12能打开调试工具

不能：排查publish模式或者jsplugins.xml模式（第四条或第五条）

能：排查加载项正常，但是未打开文档（第六条）

1.3 WPS打开后，提示 xxx is not undefined

2、version或runParams接口报错

2.1、查看58890端口是否有访问

先排查网络策略，是否有开启网络代理，并代理了http:127.0.0.1，如果有，则取消代理
在浏览器地址栏中访问http://127.0.0.1:58890/version接口(如果端口通了,则会返回1.0.0或者1.0.1)
如果无法访问，则清除浏览器缓存
(火狐浏览器较特殊，勾选为总是询问)
在浏览器的f12中执行
window.location.href = "ksoWPSCloudSvr://start=RelayHttpServer"
弹出需要唤起本地应用的窗口后，点击确定
再次访问c接口(如果端口通了,则会返回1.0.0或者1.0.1)如果不好使，则向下排查

2.2、端口有启动，但是还是打不开

如果业务系统是https环境，那么需要排查是否导入证书。

https://kdocs.cn/l/cnQFKof5HYe5

[金山文档] https支持.docx

如果业务系统是http环境，杀死进程，再通过OA助手尝试打开

Windows 杀进程

taskkill /f /t /im wps.exe

taskkill /f /t /im wpspdf.exe

taskkill /f /t /im wpp.exe

taskkill /f /t /im et.exe

taskkill /f /t /im weboffice.exe

Linux杀进程

终端执行 quickstartoffice restart

Uos

终端执行

cd /opt/apps/cn.wps.wps-office-pro/files/bin

./quickstartoffice restart

杀死进程后，OA助手调起时还是请求错误，卸载重装

2.3、查看自定义浏览器协议是否正确（只针对windows）

win+r 输入regedit.exe ;然后回车

在地址栏中输入HKEY_CLASSES_ROOT\ksoWPSCloudSvr\shell\open\command，看看注册表中的这个地址对应的文件是否存在

如果不存在，则将这个文件的地址指向自己安装目录下的ksolaunch.exe，在浏览器中再次访问。找到ksolaunch.exe的步骤：

鼠标右击桌面WPS图标，点击打开文件位置

点击地址栏的WPS Office

修改注册表中ksolaunch.exe文件地址

3、文件权限排查

需要保证oem.ini文件有读写的权限，本地的jsaddons文件夹也必须要有读写的权限

3.1、Windows

oem.ini

安装路径\WPS Offlce\一串数字（版本号）\offlce6\cfgs\，建议修改cfgs目录的权限

示例：

鼠标右键点击电脑左下角win图标 ,点击 windowsPowerShell(管理员)（A）

找到自己需要改变权限的目录，cd 进入目录

3.2、Linux

oem.ini

普通linux机器

/opt/kingsoft/wps-office/office6/cfgs

uos

/opt/apps/cn.wps.wps-office-pro/files/kingsoft/wps-office/office6/cfgs/

示例：

sudo chmod -R 777 /opt/kingsoft/wps-office/office6/cfgs

4、 Publish模式排查步骤

4.1、安装前检查

版本是否支持排查

Windows：企业版2020.04.25之后版本（8876及以后的版本）

Linux：企业版2020.05.30之后版本（9524及以后的版本）

4.2、安装后排查

安装后，查看本地是否生成publish.xml文件

windows

win + r

输入%appdata% 回车

查看kingsoft\wps\jsaddons文件夹,

Linux

cd ~/.local/share/Kingsoft/wps/jsaddons文件

如果没有生成，则执行步骤4，文件权限排查

publish.xml 无效

检查url是否正确

在线模式：url+ribbon.xml是否可以访问

离线模式：url在浏览器中是否可以下载

如果不可以，则部署环境出错了。

如果可以，打开开发者工具中的network，刷新页面，查看runparams接口返回。如果是错误，执行步骤2，runParams接口报错排查

查看本地是否有jsplugins.xml文件（没有则不用管）,

如果有，a、删除oem.ini中的JsApiPlugin=true选项，b、删除oem.ini中的JSPluginsServer，c、删除jsplugins.xml文件

国产机上，如果有生成publish.xml文件，文档未打开，在终端使用quickstartoffice restart重启一下WPS看看

5、jsplugins.xml模式排查步骤

5.1、oem.ini配置

oem.ini地址

windows

安装路径\WPS Offlce\一串数字（版本号）\offlce6\cfgs\

linux

/opt/kingsoft/wps-office/office6/cfgs/

uos

/opt/apps/cn.wps.wps-office-pro/files/kingsoft/wps-office/office6/cfgs/

JsApiPlugin：是否开启加载项，想要加载项加载成功，必须等于true

JsApiShowWebDebugger:是否开启调试模式，建议开发环境开启，正式环境关闭

JSPluginsServer:加载项项目配置文件，该地址必须能在浏览器中可访问

jsplugns.xml配置

参考文章：加载项在线模式和离线模式.docx

本文件中的URL属性值必须可以通过浏览器中可访问，确保配置都是正确可访问

本地WPS是否为预装版（安装包文件名中是否带有preload），linux上就算不带，也一般都是预装版。

如果是预装版，则需要将WPS进程全部杀死，配置才会生效

windows

taskkill /f /t /im wps.exe

taskkill /f /t /im wpspdf.exe

taskkill /f /t /im wpp.exe

taskkill /f /t /im et.exe

taskkill /f /t /im weboffice.exe

linux

重启机器或执行quickstartoffice restart

执行业务系统调起WPS。

5.2、jsplugins.xml是否同步到本地

查看本地是否有jsplugins.xml文件

windows

win + r

输入%appdata% 回车

查看kingsoft\wps\jsaddons文件夹,查看jsplugins.xml文件是否为你线上的文件

linux

cd ~/.local/share/Kingsoft/wps/jsaddons 查看jsplugins.xml文件是否为你线上的文件

如果是，则再次检查是jsplugins.xml配置，对应的模式是否都能访问

查看本地是否有publish.xml文件（没有则不用管）,如果有，查看该文件中的加载项名字是否重复（必须保证加载项名称唯一），如果有，则删除publish.xml文件。

linux上如果这个文件是新增的，需要quickstartoffice restart重启一下WPS，才会重新去读取

如果排查完成后还是未能成功加载，请在群里联系金山的项目经理，并大致告诉他自己加载项目前的问题（最好能有截图）和已排查的项，方便查看是否有遗漏排查，也减少不必要的排查，节约您的时间。

6、加载项正常，但是未打开文档

该现象表现为WPS进程正常启动了，点击新建图标，新建文档后，alt+f12能正常打开调试工具。

6.1 不落地模式只支持标准的ooxml格式文件（表格：xlsx,xls 文字：doc,docx，演示：ppt,pptx）。如果是其他格式文档，那么请使用落地模式进行打开

6.2 调起时指定的加载项名称是否正确

业务系统在调起WPS时，需要指定在WPS中由哪一个加载项来接收参数，并且由该加载项的哪个函数来解析这个参数。

图片中的WpsOAAssist就是加载项的名称，这个名称需要与jsplugins.xml文件或publish.xml文件中的name。

dispatcher对应该name的加载项中接收参数的函数。

6.3 代码是否有报错

打开一个空白文档，按alt+f12打开WPS调试工具。

查看WPS调试器，加载项代码会否有报错，阻断了WPS加载项

6.4 文档url链接是否正确

浏览器中清除浏览器缓存（为了校验是否做了登录校验）

打开浏览器调试器

输入url下载文档

查看文档是否可以下载

不落地模式时，url中尽量不要有特殊字符（如：冒号、分号、反斜杠等）

查看network中的文档下载的请求，查看请求的Content-Disposition

后端返回时，Content-Disposition的返回要求是：

name使用utf-8编码（可能造成乱码或者文档打不开的情况）

filename不要写成fileName

文件名不要用双引号或者单引号引起来

不要使用* =utf-8

7、xxx is not undefined

该情况是因为找不到对应的方法或者属性而报的错，所以需要进行以下排查：

在WPS程序中新建文档，alt+f12，查看控制台是否有报错
控制台输入window.location.href，查看url是否正常
控制台输入console.log(window)，查看window对象是否正常，自己注册到window对象上的属性或方法是否正常
查看source中js文件是否加载完全
打印一下提示报错信息的父级，查看父级是否有该属性或方法