Flutter Rest API仅debug模式正常 Web及release APK调用异常

问题本质是debug模式的宽松校验、默认辅助配置和release/Web生产环境的严格规则不一致导致，按运行场景可分为两类原因：

Android release端特有原因 #

• 网络权限缺失：Debug模式下Flutter会自动给应用授予临时网络权限，不需要显式配置，但release版必须在AndroidManifest.xml中声明INTERNET权限，否则直接被系统拦截所有网络请求。
• 明文HTTP请求被拦截：Android 9及以上版本默认禁止应用发起明文HTTP请求，debug模式不会触发这个限制，release环境下如果接口是HTTP协议且没有配置放行规则，请求会直接被拒绝。
• R8混淆/资源压缩导致逻辑异常：release构建默认开启代码混淆、无用代码/资源裁剪，如果JSON序列化实体类、网络库核心类被错误混淆或裁剪，会出现请求发送成功但响应解析失败、请求逻辑直接崩溃的情况，表面看起来像接口不通。
• HTTPS证书强校验不通过：Debug模式下Flutter默认放宽了SSL证书校验逻辑，自签名证书、过期证书、域名不匹配的证书都能正常访问，但release模式会严格校验证书链，非法证书的请求会被直接阻断。

Flutter Web端特有原因 #

• 浏览器CORS跨域限制：Flutter本地debug调试时，自带的开发服务会自动做代理转发，绕过浏览器同源策略限制，但release模式部署/运行时，浏览器会拦截跨域请求，只要后端没配置正确的CORS响应头，请求根本发不出去。
• 混合内容拦截：如果Web应用是通过HTTPS协议部署的，而接口用的是HTTP协议，浏览器会默认拦截这种不安全的混合内容请求，debug模式下本地服务是HTTP协议，不会触发这个限制。
• 接口地址配置错误：很多人把接口基地址写死为localhost/127.0.0.1，debug时服务跑在本地能正常访问，Web部署后这个地址指向的是访问用户的本地设备，APK装到手机上指向的是手机本地回环地址，自然无法请求。

• 先拿具体错误日志定位问题，别盲目试错：Android端直接执行flutter run --release连真机运行，该模式和正式签名包行为完全一致，看控制台抛出的具体异常是权限拒绝、证书错误、解析失败还是超时；Web端直接打开浏览器开发者工具，看Console面板的报错、Network面板的请求状态码和响应信息，先定位错误类型。
• 检查Android基础网络配置：确认AndroidManifest.xml的根节点（和application节点平级）下加了<uses-permission android:name="android.permission.INTERNET" />；如果用HTTP接口，在application节点加上android:usesCleartextTraffic="true"，更规范的做法是单独配置network-security-config，只放行实际使用的HTTP域名。
• 排查混淆影响：临时把android/app/build.gradle里release构建块的minifyEnabled和shrinkResources都设为false，重新构建测试，如果恢复正常就是混淆规则问题，需要在proguard规则里添加对应保留项：保留所有JSON序列化对应的实体类，比如-keep class 你的项目实体类包路径.** { *; }，如果用了json_serializable等代码生成库，确保实体类注解配置正确。
• 校验HTTPS证书有效性：直接在系统浏览器里访问接口地址，如果弹出证书风险提示，说明证书不符合要求，release环境必须使用正规CA签发的、在有效期内、域名匹配的证书，不要在release包里保留全局忽略证书校验的调试代码。
• Web端跨域问题修复：如果Console报CORS相关错误，要么让后端给接口配置正确的CORS响应头（包含Access-Control-Allow-Origin、Access-Control-Allow-Methods、Access-Control-Allow-Headers字段），要么在部署Web服务时配置反向代理，把接口路径的请求统一转发到后端服务地址，不要尝试在前端代码里绕过浏览器跨域限制，生产环境无效。
• 校验环境配置：检查代码里的接口地址判断逻辑，确认kReleaseMode下读取的是正确的生产环境地址，不要出现debug下硬编码测试地址、release下地址为空或填错的情况，可以在应用启动时打印当前使用的接口基地址，在release环境下验证配置是否正确。

• 不要为了省事全局放开明文流量、全局忽略证书校验，尽量只针对使用的业务域名做配置，避免引入安全风险。
• Web端不要用localhost作为接口地址，必须填写可被用户端正常访问的实际域名或IP。
• 正式打包前先跑flutter run --release做验证，排查效率远高于打完签名包再安装测试。

内容的提问来源于stack exchange，提问作者Rana Ali Ashar