wangyang
/
yx_only_office_flutter
1
0
Fork 0
Code Pull Requests Actions Releases Activity
yx_only_office_flutter/docs/PERMISSIONS_AND_NETWORK_CON...

5.0 KiB
Raw Permalink Blame History

权限和网络安全配置指南

问题描述

如果遇到 "DocsAPI 未加载成功" 错误，即使服务器可以访问，通常是因为 Android/iOS 的网络安全策略阻止了 WebView 加载外部资源。

Android 配置

1. AndroidManifest.xml

确保在 android/app/src/main/AndroidManifest.xml 中添加了以下配置：

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 网络权限 -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    
    <application
        android:usesCleartextTraffic="true"
        android:networkSecurityConfig="@xml/network_security_config"
        ...>
        ...
    </application>
</manifest>

2. network_security_config.xml

创建文件 android/app/src/main/res/xml/network_security_config.xml：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <!-- 允许所有 HTTPS 连接 -->
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
            <certificates src="user" />
        </trust-anchors>
    </base-config>
    
    <!-- 允许特定域名的 HTTP 连接（如果需要） -->
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">localhost</domain>
        <domain includeSubdomains="true">10.0.2.2</domain>
    </domain-config>
</network-security-config>

3. 目录结构

确保目录结构正确：

android/app/src/main/res/
└── xml/
    └── network_security_config.xml

iOS 配置

Info.plist

在 ios/Runner/Info.plist 中添加：

<key>NSAppTransportSecurity</key>
<dict>
    <!-- 允许所有 HTTPS 连接 -->
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

或者只允许特定域名（更安全）：

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>document.23544.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <false/>
        </dict>
    </dict>
</dict>

验证配置

1. 检查文件是否存在

Android:

ls -la example/android/app/src/main/res/xml/network_security_config.xml

iOS:

grep -A 5 "NSAppTransportSecurity" example/ios/Runner/Info.plist

2. 重新构建应用

配置更改后，需要完全重新构建应用：

# 清理构建缓存
flutter clean

# 重新获取依赖
flutter pub get

# 重新构建
flutter run

3. 检查日志

运行应用后，查看日志中是否有：

  • ✅ 页面加载完成
  • ✅ DocsAPI loaded successfully
  • ❌ 如果有错误，查看具体的错误信息

常见问题

Q: 配置后仍然无法加载？

A: 尝试以下步骤：

  1. 完全清理并重建:

    flutter clean
cd android && ./gradlew clean && cd ..
flutter pub get
flutter run

  2. 检查网络权限:

    • 确保 AndroidManifest.xml 中有 INTERNET 权限
    • 确保应用有网络访问权限（在设备设置中检查）

  3. 检查服务器证书:

    • 如果使用自签名证书，需要在 network_security_config.xml 中添加证书配置

  4. 查看详细日志:

    • 运行应用时查看控制台输出
    • 查看是否有 JavaScript 错误

Q: 生产环境是否安全？

A: 当前配置允许所有 HTTPS 连接，适合开发环境。生产环境建议：

  1. Android: 只允许特定域名

    <domain-config cleartextTrafficPermitted="false">
    <domain includeSubdomains="true">your-server.com</domain>
</domain-config>

  2. iOS: 只允许特定域名（见上方 iOS 配置示例）

Q: 是否需要其他权限？

A: 对于基础功能，只需要：

  • INTERNET - 网络访问
  • ACCESS_NETWORK_STATE - 检查网络状态

如果使用图片插入功能，还需要：

  • CAMERA - 相机权限
  • READ_EXTERNAL_STORAGE - 读取存储权限（Android）
  • WRITE_EXTERNAL_STORAGE - 写入存储权限（Android）

测试清单

  • AndroidManifest.xml 包含 INTERNET 权限
  • AndroidManifest.xml 引用了 network_security_config
  • network_security_config.xml 文件存在且配置正确
  • iOS Info.plist 包含 NSAppTransportSecurity 配置
  • 执行了 flutter clean 和重新构建
  • 在浏览器中可以访问 API 脚本 URL
  • 应用日志显示页面加载完成
  • 应用日志显示 DocsAPI 加载成功

相关文件

  • example/android/app/src/main/AndroidManifest.xml
  • example/android/app/src/main/res/xml/network_security_config.xml
  • example/ios/Runner/Info.plist

参考文档