WangEditor 文件上传配置后图片不显示，如何排查？

Question

WangEditor 图片上传后不显示，常见原因有三：一是服务端返回的 `url` 字段缺失或格式错误（如未返回完整 HTTP/HTTPS 路径，仅返回相对路径或空字符串），导致编辑器无法渲染；二是前端 `uploadImgServer` 配置错误，如跨域未处理、请求超时或未正确设置 `headers`（如 token 认证失败）；三是服务端响应未遵循 WangEditor 要求的 JSON 格式——必须为 `{ errno: 0, data: [{ url: 'https://xxx.jpg' }] }`，`errno ≠ 0` 或 `data` 结构不符均会导致静默失败。排查建议：① 浏览器 Network 面板检查上传请求是否成功、响应内容是否合规；② 查看控制台是否有 `insertImage failed` 类警告；③ 用 Postman 模拟上传，验证服务端逻辑与字段完整性。切忌忽略大小写（如 `Url` ≠ `url`）和 CORS 配置。

Answer 1

```html

一、现象层：图片上传成功但编辑器内无渲染（表象诊断）

用户点击上传按钮后，Network 面板显示 200 OK，控制台无报错，但光标处未插入图片——这是典型的“静默失败”现象。WangEditor 不会抛出显式异常，仅在控制台输出 insertImage failed 警告（需开启详细日志），极易被忽略。该阶段需建立基础观测闭环：上传动作 → 请求发出 → 响应抵达 → 渲染触发。

二、协议层：WangEditor 图片上传的契约规范（JSON Schema 强约束）

WangEditor v5+ 严格遵循以下响应结构，任一字段偏差即中断渲染流程：

{
  "errno": 0,
  "data": [
    {
      "url": "https://cdn.example.com/uploads/2024/06/abc123.jpg"
    }
  ]
}

字段	类型	必填	校验要点
errno	number	✅	必须为 0（非 0 视为业务错误，不尝试渲染）
data	array	✅	必须是数组，且至少含 1 项；data[0] 必须含 url 字段
url	string	✅	必须为完整 URL（含 http:// 或 https://），/uploads/xxx.jpg 或 xxx.jpg 均无效

三、传输层：前端配置与网络链路关键检查点

常见配置陷阱：

• editor.config.uploadImgServer = '/api/upload/image'：若服务端未配置 CORS 头（Access-Control-Allow-Origin: * 或精确域名），浏览器直接拦截响应，Network 显示 Blocked by CORS Policy；
• editor.config.uploadImgHeaders = { Authorization: 'Bearer ' + token }：token 过期或服务端未校验，返回 401，但 WangEditor 仅检查 errno，导致“上传成功却无图”；
• editor.config.uploadImgTimeout = 10000：大图上传超时，请求被中止，Network 中状态为 (failed) net::ERR_TIMED_OUT。

四、服务层：后端实现的典型反模式与修复路径

以下为 Node.js（Express）服务端易错代码对比：

// ❌ 错误示例：返回相对路径 + errno 拼写错误
res.json({ err_no: 0, data: [{ url: '/static/img/1.jpg' }] });

// ✅ 正确示例：全小写字段 + 绝对 URL + errno=0
const fullUrl = `${req.protocol}://${req.get('host')}/uploads/${filename}`;
res.json({ errno: 0, data: [{ url: fullUrl }] });

五、验证层：三层交叉验证法（DevOps 级排障流程）

构建可复现、可度量的验证闭环：

1. Browser DevTools：筛选 XHR，查看请求 Payload（确认 multipart/form-data 含 file 字段）、Response（格式/内容/状态码）；
2. Console 日志：启用 editor.config.debug = true，捕获 uploadImgSuccess / uploadImgError 事件，打印原始响应；
3. Postman 独立验证：构造相同 headers（含 token）、form-data（key=file），比对响应是否与前端一致——剥离前端框架干扰。

六、架构层：生产环境高可用增强建议（面向5年+工程师）

针对大规模应用，需超越单点修复，构建鲁棒性机制：

• 在网关层统一注入 Access-Control-Allow-Origin 与 Access-Control-Allow-Headers，避免每个服务单独配置；
• 服务端响应增加 debug_info 字段（仅 dev 环境），如 { errno: 1, message: "url is relative", debug_info: { raw_url: "/img/x.jpg" } }；
• 前端封装 uploadImgHook，对响应做预校验：if (!res.data?.[0]?.url?.startsWith('http')) throw new Error('Invalid url format')。

七、可视化排障：WangEditor 图片上传全流程状态机

graph LR
A[用户点击上传] --> B{前端校验文件类型/大小}
B -->|通过| C[发起XHR请求]
B -->|拒绝| D[提示“不支持的格式”]
C --> E{HTTP状态码?}
E -->|2xx| F[解析JSON响应]
E -->|非2xx| G[触发uploadImgError事件]
F --> H{errno === 0 ?}
H -->|否| G
H -->|是| I{data[0].url存在且为绝对URL?}
I -->|否| J[控制台警告 insertImage failed]
I -->|是| K[调用editor.cmd.insertImage插入DOM]

```