Alamofire 5.2调用API时返回JSON无效解码错误如何解决

错误本质 #

你遇到的Code=3840 "Invalid value around character 0."报错，本质是JSONDecoder拿到的响应数据不是合法JSON格式，和你定义的UserModelResponse结构无关，你目前的Model字段映射是正确的。

常见触发原因 #

• 服务端返回的JSON开头带了不可见的UTF-8 BOM头，解码器读取到第0位的非法字符直接报错
• 服务端返回的不是预期的JSON结构：比如请求参数错误触发4xx/5xx错误，服务端返回了HTML错误页、纯文本提示等非JSON内容
• 响应体开头带了多余的调试字符、空格、换行符，破坏了JSON结构
• Alamofire响应序列化配置错误：没有限制成功状态码范围，错误响应也进入了JSON解码逻辑，或者没有配置正确的acceptableContentTypes

排查步骤 #

1. 先打印原始响应的完整字符串，确认实际返回内容：

// 在Alamofire响应回调中加入以下代码
if let data = response.data, let rawContent = String(data: data, encoding: .utf8) {
    print("原始响应内容：\n\(rawContent)")
}

2. 检查响应状态码：如果状态码是4xx/5xx，优先排查请求参数、接口地址、鉴权逻辑是否正确
3. 将打印的原始响应内容复制到JSON校验工具中，确认是否为合法JSON

对应解决方法 #

• 存在UTF-8 BOM头：手动处理Data，删除前3个字节的BOM头后再进行解码，或者要求服务端优化输出，去掉JSON的BOM头
• 服务端返回非JSON错误响应：在Alamofire中限制仅对200~299区间的成功状态码执行JSON解码，错误状态单独做兼容处理
• Content-Type不匹配：自定义Alamofire响应序列化器，添加服务端返回的Content-Type到可接受范围内：

let decoder = JSONDecoder()
AF.request(url, parameters: params)
    .validate(statusCode: 200..<300)
    .responseDecodable(of: UserModelResponse.self, decoder: decoder) { response in
        // 业务逻辑处理
    }

• 响应体带多余前缀字符：定位到多余字符的规律后，先裁剪响应Data再传入解码器，或者要求服务端修正响应输出

内容的提问来源于stack exchange，提问作者Mohamed Elkilany