若gemini json mode返回内容无法解析，需依次检查：一、正确设置response_mime_type和response_schema；二、完整接收流式响应并校验完整性；三、预处理文本去除bom、markdown包裹等格式偏差；四、用类型守卫验证解析结果结构；五、捕获非200响应及格式异常并降级处理。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在 Node.js 项目中调用 Gemini API 并启用 JSON Mode，但返回内容无法被正确解析为合法 JSON 或结构缺失，则可能是由于响应格式未严格符合 JSON Schema 约束、流式响应未完整接收或解析逻辑未适配 Gemini 的实际输出行为。以下是处理该问题的步骤：
一、确保请求头与参数正确启用 JSON Mode
Gemini 的 JSON Mode 需显式声明 response_mime_type 并指定 schema，否则模型可能忽略结构化约束。仅设置 temperature 或 topK 不足以触发严格 JSON 输出。
1、在 request body 中设置 response_mime_type: "application/json"。
2、通过 response_schema 字段传入符合 JSON Schema Draft-07 的对象，例如 { type: "object", properties: { name: { type: "string" }, count: { type: "integer" } }, required: ["name"] }。
3、避免在 prompt 中使用“请以 JSON 格式返回”等自然语言指令，Gemini JSON Mode 下该提示冗余且可能干扰 schema 执行。
二、完整接收流式响应并校验完整性
Gemini API 在 JSON Mode 下仍可能以 chunk 形式分段返回内容，尤其当响应较大时；若提前终止读取或未等待 done 事件，将导致 JSON 语法错误（如缺少结尾大括号）。
1、使用 fetch 的 ReadableStream 接口逐块读取 body，累积所有 chunk 到字符串变量中。
2、监听 stream 的 controller.signal.onabort 和 response.body.getReader().read() 的 done 标志，确保循环执行至 done === true。
3、对拼接后的完整字符串执行 JSON.parse() 前，先用正则 /^\s*\{[\s\S]*\}\s*$|^(\s*\[[\s\S]*\]\s*)$/ 粗筛是否以 { 或 [ 开头并以对应符号结尾。
三、预处理响应文本以修复常见 JSON 格式偏差
Gemini JSON Mode 实际输出可能包含 Markdown 代码块包裹（```json ... ```）、BOM 字符、尾部逗号或单引号，这些均会导致原生 JSON.parse 失败，需在解析前清洗。
1、移除 UTF-8 BOM：对原始字符串执行 str.replace(/^\uFEFF/, "")。
2、剥离 Markdown 代码块：用正则 str.replace(/^```json\s*([\s\S]*)\s*```$/i, "$1") 提取内部内容。
3、替换单引号为双引号并移除尾部逗号：使用 JSON5.parse（需安装 json5 包）替代原生 JSON.parse，它支持单引号、尾逗号和注释。
四、定义运行时类型守卫验证解析结果
即使 JSON.parse 成功，返回对象字段也可能缺失、类型错位或值为空，直接访问可能引发运行时错误。需在解析后立即执行结构校验。
1、基于原始 response_schema 构建 TypeScript 类型或 JavaScript 校验函数，例如检查 obj.name 是否为 string 且非空字符串。
2、对数值字段使用 Number.isInteger(obj.count) 而非 typeof obj.count === "number"，防止浮点数误判。
3、对嵌套对象字段，采用可选链 + 严格相等判断：obj?.metadata?.version === "1.0"。
五、捕获并重试非 200 响应与格式异常
Gemini 可能在 JSON Mode 下返回 200 状态码但 body 为 error 对象（如 { error: { code: "INVALID_ARGUMENT", message: "Schema validation failed" } }），或因 token 超限截断 JSON，需区分处理。
1、解析响应前，先检查 status 是否为 200，且 Content-Type 是否包含 application/json。
2、尝试解析后，若抛出 SyntaxError，记录原始响应体前 200 字符用于调试，并触发降级逻辑——改用非 JSON Mode 请求并手动提取 JSON 片段。
3、对 schema 验证失败（字段缺失/类型不符），返回 null 并附带结构化错误信息（字段名、期望类型、实际值），不抛出未捕获异常。
