WebView 实现与打包

快速打包

共享WebView仓库：

aippt-frontend-addin

要求Node.js 22.x和pnpm workspace可用。生产环境离线包：

pnpm install
pnpm run build:offline

产物：

packages/aippt-plugin-webview/dist/offline.zip

offline.zip供Windows NSIS和macOS PKG使用。两个平台的发布脚本都不会构建或拉取前端；WebView有改动时，必须先构建并同步这个ZIP，再执行平台打包。

测试环境配置：

客户端API：https://web-plugin.wxbjq.top/api/
Ribbon后台：https://web-plugin.wxbjq.top/admin/#/product/menuConfig/ribbon
Windows注册表：Client_OverrideUrl或OverrideUrl
macOS Defaults：Client_OverrideUrl

切换测试环境只覆盖OverrideUrl，不额外写env=feature。删除OverrideUrl后回到正式环境。sop-plugin.wxbjq.top/admin属于另一套后台数据，不能用于配置web-plugin.wxbjq.top客户端下发的Ribbon。

测试Ribbon中的在线页面必须使用https://web-plugin.wxbjq.top/...。Windows WebView2可能允许HTTP页面继续请求，但macOS WKWebView受App Transport Security和混合内容限制，HTTP登录页会出现页面框架已加载、接口请求显示Network anomaly的现象。

1. 构建目标

目标	命令	产物	用途
offline	`pnpm run build:offline`	`dist/offline.zip`	Windows、macOS本地安装包
online	`pnpm run build:online`	`dist/online/`	部署到Web服务器
desktop	`pnpm run build:desktop`	`dist/desktop.zip`	只包含桌面入口
pre-release	`pnpm run build:pre-release:<target>`	对应预发产物	预发环境

pnpm run build依次构建offline和online。

2. offline.zip结构

ZIP内部没有offline/顶层目录，解压后直接得到：

*.html
*-<contenthash>.bundle.js
css/
images/
favicon.ico

offline目标包含：

src/pages/offline/*
src/pages/desktop/index.tsx

因此offline.zip同时包含业务HTML和desktop.html。

Webpack把Git commit和构建时间注入HTML，JS和CSS文件名包含8位content hash。当前不生成独立manifest或校验文件。

3. 同步到平台仓库

平台	清空并解压到	额外操作
Windows	`aippt_windows_addin/src/AiPPTAddin/offline/`	更新`offline/0sync.txt`
macOS	`aippt-macos-addin/App/macos-app/src/offline/`	无版本标记文件

同步前必须清空目标目录，避免旧的带Hash文件进入安装包。

人工边界到这里结束。后续平台编译、Payload组装、安装和本地WebView加载由各平台脚本完成：

4. Windows集成摘要

src/AiPPTAddin/offline
→ MSBuild CopyToOutputDirectory
→ src/Publish/AiPPT-public/offline
→ NSISAPPSetup*/App/offline
→ Setup.exe中的$INSTDIR/offline
→ LocalAppData/offline
→ WebView2加载offline/<page>.html

完整打包和缺失处理见Windows插件实现与打包 > 离线WebView如何进入Setup。

5. macOS集成摘要

App/macos-app/src/offline
→ Xcode复制到AiPPT.app/Contents/Resources/offline
→ 打包脚本复制到AiPPTAddin.bundle/Contents/Resources/offline
→ PKG
→ PowerPoint沙盒Application Support/AiPPT/offline
→ WKWebView加载offline/<page>.html

完整打包和缺失处理见macOS插件实现与打包 > WebView离线资源。

6. 运行时更新

Windows和macOS客户端安装后都会查询服务端offline包版本。发现更新时下载新的offline.zip，解压到各自的运行时home目录。安装包中的offline资源是首次启动和离线兜底版本，服务端包是后续更新来源。

运行时通信协议见AiPPT Web通信协议与平台适配。

7. 发布检查

offline.zip能正常解压；
ZIP根目录存在desktop.html；
业务HTML及其Hash JS/CSS全部存在；
Windows目标目录已更新0sync.txt；
Windows Setup包含offline/desktop.html；
macOS App和bundle都包含offline目录；
安装后Windows WebView2和macOS WKWebView能打开离线页面；
平台安装包版本与本次WebView commit有发布记录对应。

8. 相关代码

aippt-frontend-addin/package.json
aippt-frontend-addin/packages/aippt-plugin-webview/package.json
aippt-frontend-addin/packages/aippt-plugin-webview/webpack.base.js
aippt-frontend-addin/packages/aippt-plugin-webview/webpack.prod.js

AiPPT 插件文档

探索