wangyang

4.3 KiB

Raw Permalink Blame History

DocsAPI 加载错误故障排除指南

错误信息

📡 事件: onError, 数据: DocsAPI is not loaded. Check server URL.

常见原因和解决方案

1. 服务器 URL 不正确 ⚠️

问题: 您使用的是示例 URL https://doc.example.com/，这不是一个真实的服务器。

解决方案:

使用您自己的 ONLYOFFICE Document Server 地址
确保服务器地址格式正确（不要有多余的斜杠）

# ❌ 错误 - 示例 URL
--dart-define ONLYOFFICE_SERVER_URL=https://doc.example.com/

# ✅ 正确 - 您的实际服务器
--dart-define ONLYOFFICE_SERVER_URL=https://your-real-server.com

2. 服务器无法访问 🌐

检查步骤:

在浏览器中测试 API 脚本 URL:
```
https://your-server.com/web-apps/apps/api/documents/api.js
```
如果无法打开，说明服务器不可访问。

检查网络连接:

# 测试服务器是否可达
ping your-server.com

# 或使用 curl
curl -I https://your-server.com/web-apps/apps/api/documents/api.js

检查防火墙和代理设置

3. CORS 问题 🔒

问题: 服务器可能没有启用 CORS，导致 WebView 无法加载脚本。

解决方案:

在 ONLYOFFICE Document Server 配置中启用 CORS
检查服务器的 CORS 响应头

4. 脚本路径错误 📁

检查: 确保 API 脚本路径正确：

https://your-server.com/web-apps/apps/api/documents/api.js

常见错误:

❌ https://your-server.com/api.js (缺少路径)
❌ https://your-server.com/web-apps/api.js (路径不完整)
✅ https://your-server.com/web-apps/apps/api/documents/api.js (正确)

5. 服务器配置问题 ⚙️

检查 ONLYOFFICE Document Server 配置:

确保 Document Server 正在运行
检查服务器日志
验证 API 端点是否正常

调试步骤

步骤 1: 验证服务器 URL

在代码中添加调试输出：

void main() {
  print('=== 服务器配置检查 ===');
  print('Server URL: $_serverUrl');
  print('File URL: $_fileUrl');
  print('Expected API URL: $_serverUrl/web-apps/apps/api/documents/api.js');
  print('====================');
  
  runApp(const AdvancedDemoApp());
}

步骤 2: 在浏览器中测试

打开浏览器

访问 API 脚本 URL:

https://your-server.com/web-apps/apps/api/documents/api.js

如果能看到 JavaScript 代码，说明服务器正常
如果看到 404 或连接错误，说明服务器配置有问题

步骤 3: 检查 WebView 控制台

在应用运行时，查看 WebView 的 JavaScript 控制台输出：

Android: 使用 adb logcat 查看日志
iOS: 使用 Xcode 控制台查看日志

步骤 4: 测试网络连接

// 在应用启动时测试连接
Future<void> testServerConnection() async {
  try {
    final url = Uri.parse('$_serverUrl/web-apps/apps/api/documents/api.js');
    final response = await http.head(url);
    
    if (response.statusCode == 200) {
      print('✅ 服务器连接正常');
    } else {
      print('❌ 服务器返回错误: ${response.statusCode}');
    }
  } catch (e) {
    print('❌ 无法连接到服务器: $e');
  }
}

快速检查清单

服务器 URL 是真实的，不是示例 URL
服务器 URL 格式正确（没有多余的斜杠）
可以在浏览器中访问 API 脚本 URL
网络连接正常
服务器已启用 CORS
Document Server 正在运行
防火墙没有阻止连接

常见服务器 URL 格式

标准安装

https://documentserver.example.com

子路径安装

https://example.com/documentserver

本地开发

http://localhost:8080

注意: 本地开发时，Android 模拟器使用 10.0.2.2 而不是 localhost:

http://10.0.2.2:8080

获取帮助

如果以上步骤都无法解决问题：

检查服务器日志: 查看 ONLYOFFICE Document Server 的日志文件
查看浏览器控制台: 在浏览器中打开编辑器，查看是否有错误
测试官方示例: 在浏览器中测试 ONLYOFFICE 官方示例是否正常工作
联系服务器管理员: 确认服务器配置是否正确

改进的错误信息

新版本的插件会提供更详细的错误信息，包括：

完整的脚本 URL
检查清单
建议的解决方案

请确保使用最新版本的代码。

4.3 KiB Raw Permalink Blame History Unescape Escape