1. Android 文件上传为什么总在真机上翻车从 NetworkOnMainThreadException 说起Android 端做文件上传很多人第一次写都会踩同一个坑在 Activity 里直接 new 一个 HttpClient 发请求模拟器上跑得好好的换到真机 Android 4.0 以上直接崩日志里一行android.os.NetworkOnMainThreadException。这不是代码写错了而是 Android 从 API 11 开始强制要求网络访问不能放在主线程否则阻塞 UI 导致 ANR。你要么自己开 Thread要么用异步框架把线程调度这件事包掉。我试过最原始的写法new Thread(){...}.start()里面跑HttpClient.executeMethod()跑通是能跑通但问题一堆。子线程里拿到结果想更新 UI必须runOnUiThread()回主线程上传大文件时没有进度回调用户看着转圈不知道卡在哪超时设置散落在HttpConnectionManager里改一个参数要翻半天。更麻烦的是一旦要加鉴权头、要换 endpoint、要排查 401代码里 URL 和 token 硬编码得到处都是改一次编译一次。所以这篇聚焦的场景很明确Android 端用异步 HTTP 框架配合第三方 HttpClient 完成文件上传的完整链路覆盖权限申请、Multipart 组装、进度回调、超时重试最后把请求 endpoint 和鉴权配置统一挪到 TaoToken 管理方便排查 401 和超时。适合谁看正在写 Android 上传功能、被主线程异常和超时问题折腾、想把网络层配置收拢到一处的开发者。核心检索词就是 android 异步 http 框架、HttpClient 上传文件、Multipart 组装、超时重试。先说结论第三方 HttpClientApache commons-httpclient 3.x适合理解 Multipart 底层组装原理异步 HTTP 框架如 android-async-http适合快速落地。两者不是二选一而是理解 落地的组合。下面我会先讲清楚两种方式的差异和各自的坑再给出可复制的依赖配置和封装类最后把 endpoint 和鉴权切到 TaoToken 统一管理。权限这块先交代清楚。Android 6.0 以上读文件要动态申请READ_EXTERNAL_STORAGEAndroid 10 以上分区存储又变了如果你上传的是应用私有目录文件用getExternalFilesDir()可以免权限。网络权限INTERNET是普通权限manifest 里声明即可。很多人上传失败不是代码问题是文件路径拿不到或者权限没给日志里FileNotFoundException一出来就往网络层找原因方向就错了。还有一个容易被忽略的点上传的文件大小。小文件几十 KB用哪种方式都行但超过 1MB 就要考虑超时和重试。默认连接超时 10 秒、读取超时可能更长弱网环境下大文件上传中途断掉没有重试机制就得用户手动再点一次。异步框架的RequestParams支持文件流但进度回调需要自己包一层MultipartEntity或者用框架自带的进度接口。把这些前置问题理清楚后面的配置和代码才有意义。接下来先讲 TaoToken 的前置准备因为 endpoint 和鉴权统一管理之后你排查 401 和超时会轻松很多。2. TaoToken 前置准备把 endpoint 与鉴权从硬编码里解放出来在写上传代码之前先把请求的 endpoint 和鉴权配置规划好。传统写法里 URL 直接写死在post(url, params, handler)里token 塞在 header 里一旦要换环境或者排查 401就得全局搜索替换。更合理的做法是把这些配置抽到一个统一的接入层TaoToken 就是干这个的它提供统一的 API 入口把模型调用、鉴权、endpoint 管理收拢到一处你只需要在客户端配置 Base URL 和 Key。TaoToken 的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 这个不加 UTM。注意这里说的是把上传请求的 endpoint 和鉴权配置改到 TaoToken 统一管理不是让你把文件传到 TaoToken 本身而是借助它统一的接入层来管理请求配置方便排查 401 和超时。如果你只是做纯文件上传到自己的服务器也可以参考这套配置管理思路。前置准备分三步。第一步拿到 API Key。访问 https://taotoken.net/api-keys 创建 Key这个 Key 就是你请求时放在 header 里的凭证。第二步确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api 所有请求基于这个地址拼接路径。第三步选定 Model ID。如果你上传文件后要调用模型处理比如图片理解、文档解析需要指定模型 ID如果只是纯上传Model ID 可以先留空但配置结构里要预留字段。为什么要在 Android 上传场景里引入这套配置因为 401 和超时是上传功能最常见的两类问题。401 通常是 Key 失效、header 没带上、或者 Base URL 拼错超时通常是 endpoint 不通、网络策略限制、或者超时参数设得太短。如果 URL 和 Key 散落在代码各处排查时你得一个个确认如果收拢到一处配置改一个地方就能验证。这里给一个配置结构的设计思路后面第三节会给可复制的 JSON 片段。核心字段就三个Base URL、API Key、Model ID。在 Android 里可以放在local.properties或者BuildConfig里避免硬编码进源码。注意不要把 Key 提交到 Git这是基本安全习惯。关于 Coding Plan如果你的场景是长期编码、Agent 调用可以了解 https://taotoken.net/coding-plan 。模型对话调试可以用 https://taotoken.net/models 。接入文档在 https://taotoken.net/doc 。这些入口在后面 CTA 部分会再提这里先建立认知TaoToken 提供的是统一的接入和配置管理能力帮你把鉴权和 endpoint 从业务代码里解耦。配置管理还有一个好处多环境切换。开发环境、测试环境、生产环境的 endpoint 和 Key 不同如果硬编码每次切换都要改代码重新打包。用统一配置层改配置文件即可。Android 里可以用buildTypes配合buildConfigField实现后面会给具体写法。最后提醒一点TaoToken 是合法的 API 接入服务不要把它和任何非法中转混为一谈。我们用它就是看中统一的鉴权管理和 endpoint 配置让上传功能的网络层更清晰、更好排查。前置准备做完接下来进入可复制的配置和代码环节。3. 可复制配置依赖、权限、封装类与 settings 片段这一节给可直接复制的配置和代码。先看依赖。第三方 HttpClient 方式需要三个 jarcommons-fileupload、commons-io、commons-httpclient。异步框架方式推荐用 android-async-httpGradle 依赖如下// 异步 HTTP 框架 implementation com.loopj.android:android-async-http:1.4.11 // 第三方 HttpClient如需理解 Multipart 底层 implementation commons-httpclient:commons-httpclient:3.1 implementation commons-io:commons-io:2.11.0 implementation commons-fileupload:commons-fileupload:1.5权限在AndroidManifest.xml里声明uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE android:maxSdkVersion32 /Android 6.0 以上动态申请读权限Android 10 以上如果上传私有目录文件可免权限。接下来是配置片段。把 Base URL、Key、Model ID 抽到local.propertiesTAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_MODEL_ID你的模型ID在build.gradle里读取并注入BuildConfigandroid { buildTypes { debug { buildConfigField String, BASE_URL, \${localProperties[TAOTOKEN_BASE_URL] ?: }\ buildConfigField String, API_KEY, \${localProperties[TAOTOKEN_API_KEY] ?: }\ buildConfigField String, MODEL_ID, \${localProperties[TAOTOKEN_MODEL_ID] ?: }\ } } }如果你用 settings 风格的配置文件比如某些工具链可以写成 JSON{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model_id: 你的模型ID, timeout_connect_ms: 10000, timeout_read_ms: 30000, max_retries: 2 }注意路径和字段名要和你的实际读取逻辑一致别一边写base_url一边读baseUrl。接下来是上传封装类。先看异步框架的封装public class UploadManager { private final AsyncHttpClient client; public UploadManager() { client new AsyncHttpClient(); client.setConnectTimeout(10000); client.setResponseTimeout(30000); client.setMaxRetriesAndTimeout(2, 3000); } public void uploadFile(File file, String endpoint, UploadCallback callback) { if (file null || !file.exists() || file.length() 0) { callback.onFail(文件不存在或为空); return; } RequestParams params new RequestParams(); try { params.put(file, file); } catch (FileNotFoundException e) { callback.onFail(文件读取失败: e.getMessage()); return; } String url BuildConfig.BASE_URL endpoint; client.addHeader(Authorization, Bearer BuildConfig.API_KEY); client.post(url, params, new AsyncHttpResponseHandler() { Override public void onSuccess(int statusCode, Header[] headers, byte[] responseBody) { callback.onSuccess(new String(responseBody)); } Override public void onFailure(int statusCode, Header[] headers, byte[] responseBody, Throwable error) { callback.onFail(HTTP statusCode : (error ! null ? error.getMessage() : unknown)); } Override public void onProgress(long bytesWritten, long totalSize) { callback.onProgress(bytesWritten, totalSize); } }); } }回调接口public interface UploadCallback { void onSuccess(String response); void onFail(String error); void onProgress(long written, long total); }第三方 HttpClient 的 Multipart 组装方式核心是MultipartRequestEntityHttpClient client new HttpClient(); PostMethod post new PostMethod(url); Part[] parts { new FilePart(file, file) }; post.setRequestEntity(new MultipartRequestEntity(parts, post.getParams())); post.setRequestHeader(Authorization, Bearer BuildConfig.API_KEY); HttpConnectionManager mgr client.getHttpConnectionManager(); mgr.getParams().setConnectionTimeout(10000); client.executeMethod(post);对比一下异步框架三步搞定自动处理线程和 UI 回调HttpClient 需要手动开线程、手动回主线程、手动设超时。所以落地推荐异步框架HttpClient 用来理解 Multipart 的 boundary 和 part 组装原理。配置和封装都齐了下一节验证请求。4. 验证请求与成功结果抓包、日志与进度回调确认代码写完不代表跑通得验证。验证分三层日志、抓包、结果确认。先说日志。异步框架的onSuccess和onFailure里打日志把 statusCode 和 responseBody 打出来Override public void onSuccess(int statusCode, Header[] headers, byte[] responseBody) { Log.d(Upload, status statusCode body new String(responseBody)); }如果 statusCode 是 200 但 body 是错误信息说明服务端返回了业务错误不是网络问题。如果 statusCode 是 401直接看 header 里 Authorization 有没有带上Key 是不是过期。如果 statusCode 是 0 或者抛异常多半是连接超时或者 endpoint 不通。抓包验证。Android 端可以用 Charles 或 Fiddler 抓 HTTP 请求看 Multipart 的 boundary 是否正确、Content-Type 是不是multipart/form-data、文件 part 的 filename 和 content-type 有没有。注意 HTTPS 抓包需要装证书Android 7.0 以上默认不信任用户证书需要在network_security_config.xml里配置。抓包能看到请求体里文件的二进制内容确认文件确实被组装进去了。进度回调验证。上传大文件时onProgress应该持续回调written 递增到 total。如果一直不回调可能是文件太小一次性发完了或者框架版本不支持。实测下来1MB 以上的文件进度回调比较明显。你可以在进度回调里更新 ProgressBar确认 UI 线程更新正常。成功结果的确认标准statusCode 200、responseBody 里服务端返回上传成功的标识比如文件 ID 或 URL、进度回调走完 100%、没有异常日志。如果这四条都满足说明链路通了。如果 statusCode 200 但服务端说文件为空检查params.put(file, file)的 key 和服务端接收的字段名是否一致这是最常见的字段名不匹配问题。再验证一下 endpoint 和鉴权切到 TaoToken 后的效果。把 Base URL 改成https://taotoken.net/apiKey 用你在 https://taotoken.net/api-keys 创建的重新跑一次。如果返回 401检查 header 格式是不是Bearer sk-xxx有些服务要求Authorization: sk-xxx不带 Bearer看文档确认。如果超时把 connectTimeout 调到 15 秒再试弱网环境下 10 秒可能不够。验证通过后建议加一个重试机制。异步框架自带setMaxRetriesAndTimeout但只对连接失败重试对 401 这种鉴权失败不重试重试也没用。业务层可以自己包一层onFailure 里判断 statusCode如果是 5xx 或超时延迟 2 秒重试一次最多两次。重试时注意不要重复上传已经成功的文件用文件 MD5 或者服务端返回的幂等 ID 去重。日志和抓包都确认后把关键信息记下来成功的 endpoint、Key 的前缀、超时参数、文件大小。这些是后面排查问题的基线。下一节讲常见错误。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth上传功能跑不通报错就那么几类。逐个对照。401 Unauthorized。这是鉴权问题不是网络问题。检查三处header 里 Authorization 有没有带上、Key 是不是过期或被删、Base URL 拼接后路径对不对。如果你用的是 TaoToken去 https://taotoken.net/api-keys 确认 Key 状态。注意 header 格式有的服务要Bearer前缀有的不要看接入文档 https://taotoken.net/doc 。还有一种情况是 Key 里带了空格或者换行复制的时候容易带进去trim 一下。local proxy failed。这个报错通常出现在你配置了本地代理或者抓包工具没关。Android 模拟器默认走宿主机的代理如果你开了 Charles 但没配好请求会走代理然后失败。检查client.setProxy()有没有设、模拟器的代理设置、抓包工具是否在运行。真机上如果连了 WiFi 且 WiFi 配了代理也会出现这个。关掉代理或者配好抓包证书再试。reading choices 相关报错。这个通常出现在你调用模型接口、返回体解析失败时。比如你上传文件后期望返回 JSON但服务端返回了 HTML 错误页解析就报 reading choices 之类的错。检查 responseBody 的实际内容别直接丢给 JSON 解析器。先打日志看原始返回确认 Content-Type 是application/json再解析。OAuth 相关报错。如果你用的是 OAuth 流程拿 tokentoken 过期或者 scope 不对会报错。检查 token 有效期、refresh 逻辑、scope 是否包含上传权限。OAuth 的 token 和 API Key 不是一回事别混用。如果你只是简单上传用 API Key 就够了不用上 OAuth。还有一个高频错误NetworkOnMainThreadException。这个前面讲过网络请求必须在子线程。异步框架自动处理但如果你在onSuccess里又发了同步请求还是会崩。所有网络操作都走异步。超时错误。SocketTimeoutException或ConnectTimeoutException。检查 endpoint 是否可达、超时参数是否太短、文件是否太大。大文件上传建议把 read timeout 设到 60 秒以上。弱网环境下加 retry。文件相关错误。FileNotFoundException检查路径和权限OutOfMemoryError检查是不是把整个文件读进内存了要用流式上传IllegalArgumentException检查params.put的 key 是不是空。对照这些报错逐个排查基本能覆盖 90% 的上传问题。排查时记住一个原则先确认是网络层、鉴权层还是业务层的问题别一上来就改代码。日志和抓包是你的第一手证据。6. 把上传链路收拢到统一接入层CTA 与后续调试入口上传功能跑通之后下一步是把网络层配置收拢别让 URL 和 Key 散落在业务代码里。TaoToken 提供统一的 API 入口和鉴权管理适合做这件事。具体入口按场景分流排查 401、超时、鉴权问题去 API Keys 页面 https://taotoken.net/api-keys 确认 Key 状态接入文档 https://taotoken.net/doc 看 header 格式和 endpoint 规范。验证模型返回、调试上传后的处理逻辑用模型对话 https://taotoken.net/models 。长期编码、Agent 调用场景了解 Coding Plan https://taotoken.net/coding-plan 。控制台在 https://taotoken.net/console API 入口是 https://taotoken.net/api 。配置管理的核心就三件套Base URL、API Key、Model ID。这三个字段在local.properties或 settings 片段里配好通过BuildConfig注入业务代码只读不写。这样换环境、换 Key、排查问题都只改一处。Claude Code 接入场景下Base URL 填https://taotoken.net/apiKey 填你的 API KeyModel ID 按文档选。Cline MCP 或 Codex auth.json 场景同理三件套配齐。最后给一个实用技巧上传功能加一个「诊断模式」在设置里能切换 endpoint 和超时参数不用重新打包就能验证不同配置。配合日志开关排查问题时把请求 URL、header、statusCode、耗时都打出来。这样下次再遇到 401 或超时你手里有完整证据链不用猜。上传链路本身不复杂复杂的是配置散落和错误定位。把 endpoint 和鉴权收拢到统一接入层把日志和抓包做成习惯剩下的就是按报错逐个击破。