使用自托管WOPI主机时Office for Web生产环境无法编辑文档

已知信息梳理 #

• 开发环境（ngrok代理本地WOPI）：预览、编辑全正常，编辑时会触发文件锁定请求
• 预发布生产环境（自托管WOPI）：预览正常，编辑弹错Sorry this document can't be opened for editing；Office能拿到带UserCanWrite=true的元数据，但完全没发锁定请求
• 两边用的是同一个测试版Office端点，Office页面和WOPI代码完全一致

必查排查点 #

1. HTTPS证书是重灾区 #

Office for Web对WOPI主机的证书要求比预览严格得多，开发环境ngrok的证书是CA信任的，所以没问题，但预发布环境很可能栽在这：

• 别用自签名证书，必须上受信任CA签发的证书
• 检查证书的SAN字段，必须包含预发布WOPI的域名（只填CN不行）
• 确认证书链完整，浏览器访问WOPI接口时不能有证书警告

验证工具：用openssl s_client -connect your-wopi-domain:443看证书链，或者直接用Chrome访问https://your-wopi-domain/wopi/files/test-id看地址栏证书状态。

2. CORS配置漏了编辑相关规则 #

预览只需要基础CORS，但编辑涉及LOCK/UNLOCK/PUT这些请求，预发布环境的CORS大概率没配全：

• 必须返回Access-Control-Allow-Origin，值要包含Office测试端点的域名（比如https://word-web-test.officeapps.live.com，具体看浏览器Network里的请求Origin）
• Access-Control-Allow-Methods要加LOCK、UNLOCK、PUT、OPTIONS
• Access-Control-Allow-Headers必须包含X-WOPI-Lock、X-WOPI-Override、Authorization这些头

3. 元数据的隐性必填字段没填对 #

别以为只给UserCanWrite=true就够了，以下字段缺一个都可能让Office放弃编辑：

• BaseFileName：必须是带扩展名的合法文件名（比如report.docx，不能只叫report）
• Size：要和实际文件字节数完全一致
• Version：必须是唯一标识（每次文件改了要更新，Office靠这个判断文件状态）

4. 网络层拦截了锁定请求 #

预发布环境的防火墙、WAF、反向代理很可能拦了LOCK请求（毕竟这不是GET/POST这种常见方法）：

• 查WOPI主机的访问日志，看有没有收到LOCK请求（开发环境有，预发布没有就是被拦了）
• 检查代理/防火墙规则，放行LOCK、UNLOCK方法
• 确认WOPI主机的443端口能被Office的测试端点正常访问（可以用curl从公网测）

5. 临时验证：用ngrok代理预发布WOPI #

把预发布的WOPI主机用ngrok代理起来，然后在预发布环境用这个ngrok地址测试编辑，如果能正常编辑，说明问题肯定出在自托管环境的证书或网络配置上。

快速验证步骤 #

1. 用Postman模拟流程：先GET元数据，再发LOCK请求到/wopi/files/{fileId}/contents，看WOPI有没有正常响应200
2. 开浏览器F12看Network和Console：找有没有隐藏的证书错误、CORS错误日志
3. 对比开发和预发布环境的请求头，重点看Origin、Authorization、WOPI相关头的差异

内容的提问来源于stack exchange，提问作者Niall Curtis