奕澄Markdown

简体中文

English

简体中文

English

外观

服务器地址图床

约 1522 字大约 5 分钟

2026-11-01

服务器地址图床会将本地图片通过 HTTP POST 上传到你指定的图片接口，再把接口返回的图片 URL 插入 Markdown。它适合已经有自建图片服务，或能够提供 PicGo 风格上传接口的场景。

奕澄Markdown提供的是上传客户端，不包含图床服务器。你需要自行准备可访问的上传接口和图片存储服务。

配置前确认接口约定

当前服务器图床使用固定的上传与响应约定。配置前请确认接口能够直接支持以下格式。

上传请求

  • 请求方法：POST。
  • 请求类型：multipart/form-data。
  • 图片文件字段名：file。
  • 上传时保留图片原始文件名。
  • 连接和读取超时时间均为 30 秒。

请求结构示例如下：

POST /upload HTTP/1.1
Content-Type: multipart/form-data; boundary=...

file=@cover.png

当前图床配置中没有自定义请求头、鉴权 Header 或额外表单字段的入口。如果接口必须依赖 Authorization、额外 token 字段或自定义签名参数才能上传，需要先由服务端调整为兼容上述直接上传方式。

成功响应

接口必须返回 HTTP 2xx 状态码，响应体为 JSON，并在顶层包含非空的 url 字段：

{
  "url": "https://img.example.com/2026/cover.png"
}

url 必须是以 http 开头的图片绝对地址，建议使用 HTTPS。上传成功后，应用会把这个值原样作为 Markdown 图片地址。

以下响应不能直接按当前约定识别：

  • 纯文本 URL，而不是 JSON。
  • 将地址放在 data.url 等嵌套字段中。
  • 返回 result 数组，但没有顶层 url。
  • HTTP 状态为 4xx、5xx。
  • 返回 2xx，但 url 为空或不是有效的 HTTP 图片地址。

图片 URL 的访问要求

接口返回的地址应当：

  • 长期有效，不使用很快就会过期的临时签名链接。
  • 无需登录或携带上传凭证即可加载。
  • 能从需要阅读文档的设备访问。
  • 与实际上传图片对应，而不是 HTML 页面或登录跳转地址。

添加服务器地址图床

  1. 打开 设置 > 图床设置。

  2. 点击右上角新建按钮，选择 新建图床。

  3. 将类型设为 服务器地址。

  4. 填写 图床名称，例如“我的图片服务”。

  5. 在 空间地址 中填写完整的上传接口地址，例如：

    https://img.example.com/upload

  6. 如需立即使用，打开 是否启用；如果已有默认图床，保存时按提示确认是否切换。

  7. 点击顶部确认按钮保存。

这里的“空间地址”必须是实际上传接口，不是图床网站首页、图片浏览页面或存储目录地址。服务器图床不使用“图床根目录”字段，图片保存路径、重命名策略和目录结构均由服务端接口决定。

在编辑器中使用

  1. 确认该图床已启用为默认图床。
  2. 进入 个性化设置 > 编辑器 > 编辑器应用图床，确认开关已打开。
  3. 新建测试文档并插入一张本地图片。
  4. 上传完成后，检查 Markdown 中是否出现接口返回的 URL。

例如：

![封面](https://img.example.com/2026/cover.png)

对于之前已经保存在本地的图片，可长按图片或在电脑端右键图片，选择：

  • 上传此图片到图床。
  • 上传全部本地图片到图床。

手动上传同样使用当前默认图床。如果编辑器应用图床已关闭、未设置默认图床或配置不可用，上传会失败并保留本地图片。

上传失败时会发生什么

服务器上传只读取本地图片，不会因为上传而删除、移动或修改源文件。出现网络异常、超时、HTTP 错误或响应格式不符时：

  1. 应用显示上传失败提示。
  2. 自动插图流程回退为本地相对路径。
  3. 已落地的本地图片继续保留。
  4. 修复接口或网络后，可通过图片菜单重新上传。

删除文档、图床配置或本地图片，不会自动删除服务器上已经上传的图片；远程文件的生命周期由你的图床服务管理。

常见问题排查

提示“图床地址不能为空”

返回图床编辑页，在 空间地址 中填写完整上传接口，并保存。

提示 HTTP 4xx 或 5xx

根据状态码检查接口路径、服务端鉴权、请求大小限制、存储权限和服务运行状态。当前客户端会按固定字段 file 上传，也请确认服务端没有要求其他文件字段名。

提示“响应格式不符”

即使接口返回 2xx，也必须返回顶层带 url 的 JSON。请检查实际响应体，而不是只检查上传文件是否已经存入服务器。

上传超时

检查设备到服务器的网络、DNS、HTTPS 证书、服务处理速度以及图片大小。当前连接和读取超时均为 30 秒，大文件或慢接口可能需要优化服务端与网络。

上传成功但 Markdown 图片无法显示

复制返回的 URL 到不登录图床账户的浏览器中测试。如果需要登录、返回 HTML、链接已过期或只能内网访问，它就不适合作为跨环境文档图床链接。

插图仍然使用本地相对路径

依次确认：默认图床是否启用、编辑器应用图床是否打开、图片是否为本地来源，以及是否出现上传失败提示。如果正在编辑云端镜像文档，还需检查是否被自动 云端资源上传 优先处理；需要强制走图床时，使用图片菜单中的显式 上传到图床 操作。