# 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
- 检查清单
- 建议的解决方案

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