181 lines
4.3 KiB
Markdown
181 lines
4.3 KiB
Markdown
# DocsAPI 加载错误故障排除指南
|
||
|
||
## 错误信息
|
||
|
||
```
|
||
📡 事件: onError, 数据: DocsAPI is not loaded. Check server URL.
|
||
```
|
||
|
||
## 常见原因和解决方案
|
||
|
||
### 1. 服务器 URL 不正确 ⚠️
|
||
|
||
**问题**: 您使用的是示例 URL `https://doc.example.com/`，这不是一个真实的服务器。
|
||
|
||
**解决方案**:
|
||
- 使用您自己的 ONLYOFFICE Document Server 地址
|
||
- 确保服务器地址格式正确（不要有多余的斜杠）
|
||
|
||
```bash
|
||
# ❌ 错误 - 示例 URL
|
||
--dart-define ONLYOFFICE_SERVER_URL=https://doc.example.com/
|
||
|
||
# ✅ 正确 - 您的实际服务器
|
||
--dart-define ONLYOFFICE_SERVER_URL=https://your-real-server.com
|
||
```
|
||
|
||
### 2. 服务器无法访问 🌐
|
||
|
||
**检查步骤**:
|
||
|
||
1. **在浏览器中测试 API 脚本 URL**:
|
||
```
|
||
https://your-server.com/web-apps/apps/api/documents/api.js
|
||
```
|
||
如果无法打开，说明服务器不可访问。
|
||
|
||
2. **检查网络连接**:
|
||
```bash
|
||
# 测试服务器是否可达
|
||
ping your-server.com
|
||
|
||
# 或使用 curl
|
||
curl -I https://your-server.com/web-apps/apps/api/documents/api.js
|
||
```
|
||
|
||
3. **检查防火墙和代理设置**
|
||
|
||
### 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 配置**:
|
||
|
||
1. 确保 Document Server 正在运行
|
||
2. 检查服务器日志
|
||
3. 验证 API 端点是否正常
|
||
|
||
## 调试步骤
|
||
|
||
### 步骤 1: 验证服务器 URL
|
||
|
||
在代码中添加调试输出：
|
||
|
||
```dart
|
||
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: 在浏览器中测试
|
||
|
||
1. 打开浏览器
|
||
2. 访问 API 脚本 URL:
|
||
```
|
||
https://your-server.com/web-apps/apps/api/documents/api.js
|
||
```
|
||
3. 如果能看到 JavaScript 代码，说明服务器正常
|
||
4. 如果看到 404 或连接错误，说明服务器配置有问题
|
||
|
||
### 步骤 3: 检查 WebView 控制台
|
||
|
||
在应用运行时，查看 WebView 的 JavaScript 控制台输出：
|
||
|
||
- Android: 使用 `adb logcat` 查看日志
|
||
- iOS: 使用 Xcode 控制台查看日志
|
||
|
||
### 步骤 4: 测试网络连接
|
||
|
||
```dart
|
||
// 在应用启动时测试连接
|
||
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
|
||
```
|
||
|
||
## 获取帮助
|
||
|
||
如果以上步骤都无法解决问题：
|
||
|
||
1. **检查服务器日志**: 查看 ONLYOFFICE Document Server 的日志文件
|
||
2. **查看浏览器控制台**: 在浏览器中打开编辑器，查看是否有错误
|
||
3. **测试官方示例**: 在浏览器中测试 ONLYOFFICE 官方示例是否正常工作
|
||
4. **联系服务器管理员**: 确认服务器配置是否正确
|
||
|
||
## 改进的错误信息
|
||
|
||
新版本的插件会提供更详细的错误信息，包括：
|
||
- 完整的脚本 URL
|
||
- 检查清单
|
||
- 建议的解决方案
|
||
|
||
请确保使用最新版本的代码。
|
||
|