Markdown 图片加载问题解决指南
问题描述
在 Markdown 文档中,图片加载失败通常有以下几种原因:
本地路径问题:图片文件路径不正确或文件不存在
相对路径问题:文档移动后相对路径失效
网络限制:某些环境下无法访问外部图片链接
图床服务问题:使用的图床服务不稳定或已关闭
解决方案:使用图床
什么是图床?
图床(Image Hosting)是一种在线图片存储服务,可以将图片上传到云端服务器,然后通过 URL 链接在 Markdown 文档中引用。
图床的优势
稳定性:专业的图床服务提供稳定的图片访问
跨平台:在任何设备上都能正常显示图片
加载速度:CDN 加速,图片加载更快
永久链接:避免因文件移动导致的链接失效
常用图床服务推荐
1. GitHub 图床(免费但是不推荐)
1 |  |
优点:免费、稳定、与 GitHub 项目集成
缺点:需要公开仓库、国内访问可能较慢
2. Gitee 图床(强烈推荐)
1 |  |
优点:国内访问速度快、免费
缺点:需要公开仓库
5. 免费公共图床
SM.MS:https://sm.ms
Imgur:https://imgur.com
Postimages:https://postimages.org
如何使用图床
步骤 1:选择图床服务
根据需求选择合适的图床服务:
- 个人项目:推荐 Gitee
步骤 2:上传图片
以 Gitee 图床为例:
创建 Gitee 仓库
上传图片到仓库
获取图片的 raw 链接
步骤 3:在 Markdown 中使用
1 |  |
步骤 4:批量处理现有图片
如果已有 Markdown 文档需要迁移图片:
将所有本地图片上传到图床
使用文本编辑器的查找替换功能批量更新链接
实际操作示例
示例 1:GitHub 图床使用
在 GitHub 创建仓库
my-images上传图片
linux-structure.png到images/文件夹获取图片链接:
https://raw.githubusercontent.com/yourname/my-images/main/images/linux-structure.png在 Markdown 中使用:
1

示例 2:使用免费图床 SM.MS
上传图片
复制 Markdown 链接
直接粘贴到文档中
最佳实践
1. 图片命名规范
使用有意义的文件名:
linux-directory-structure.png✅image1.png❌
2. 图片压缩
上传前压缩图片以减少加载时间:
使用 TinyPNG:https://tinypng.com
使用 Squoosh:https://squoosh.app
3. 备份策略
重要图片建议在多平台备份:
主图床:GitHub
备份图床:Gitee 或云存储
4. 监控图片状态
定期检查图片链接是否有效,可以使用工具:
浏览器开发者工具
在线链接检查器
故障排除
常见问题及解决方案
问题 1:图片显示红叉或无法加载
检查链接是否正确
确认图片是否已上传
检查网络连接
工具推荐
图床管理工具
PicGo:跨平台的图床上传工具
支持多种图床服务
一键上传和获取链接
使用图床是解决 Markdown 图片加载问题的最佳方案。选择适合的图床服务,遵循最佳实践,可以确保图片稳定可靠地显示。
对于技术文档,推荐使用 Gitee 图床;
记住:定期检查图片链接,确保文档的长期可访问性。
PicGo + Gitee 图床完整教程
含 Typora 一键联动(Windows / macOS / Linux 通用)
目标:截图 → 自动上传到 Gitee → Markdown 中直接粘贴外链
成本:0 元,耗时:10 分钟
1. 准备软件
| 工具 | 下载地址 | 备注 |
|---|---|---|
| Node.js ≥ 14 | https://nodejs.org | PicGo 依赖 |
| PicGo ≥ 2.3 | https://github.com/Molunerfinn/PicGo/releases | 图床客户端 |
| Typora ≥ 1.0 | https://typora.io | Markdown 编辑器 |
2. Gitee 侧一次性配置
2.1 新建仓库
- 登录 Gitee → 右上角 「+ 新建仓库」
- 填写示例
- 仓库名称:
imgbed(随意) - 路径:
imgbed - 公开 / 私有均可(私有仓库外链需登录后才能查看,建议公开)
- 勾选 使用 README 初始化仓库(防止空仓库报错)
- 仓库名称:
- 创建后记住 仓库完整路径:
1
https://gitee.com/你的用户名/imgbed
2.2 生成私人令牌
- 头像 → 设置 → 安全设置 → 私人令牌
- 生成新令牌 → 仅勾选
projects→ 复制令牌(只出现一次)。
3. 安装 PicGo 及插件
- 安装 Node.js(一路 Next)。
- 安装 PicGo(Windows 选
.exe,macOS 选.dmg)。 - 打开 PicGo → 插件设置 → 搜索 gitee-uploader → 点击 安装。
- 安装完成后重启 PicGo。
4. 配置 Gitee 图床
进入 图床设置 → Gitee:
| 字段 | 示例 | 说明 |
|---|---|---|
| repo | 用户名/imgbed |
仅填 用户名/仓库名 |
| branch | master 或 main |
看仓库默认分支 |
| token | 刚才复制的令牌 | 私人令牌 |
| path | img/ |
上传子目录,可留空 |
| customUrl | 留空 | 自建 CDN 用,不填即可 |
| message | upload from picgo |
提交信息,随意 |
点击 确定 → 设为默认图床。
5. 测试上传
- 方式一:直接拖拽图片到 PicGo 主界面
- 方式二:截图后按默认快捷键
Ctrl+Shift+P(可在 PicGo 设置里改)
上传成功日志出现绿色 success 即 OK,外链会自动复制到剪贴板:
1 |  |
6. Typora 一键联动
6.1 设置 Typora
- 打开 Typora → 偏好设置 → 图像
- 按下图配置

| 选项 | 值 |
|---|---|
| 插入图片时 | 上传图片 |
| 上传服务 | PicGo (app) |
| PicGo 路径 | 浏览到 PicGo.exe 或 PicGo.app |
- 点击 验证图片上传 → 出现绿色 √ 即成功。
6.2 使用场景
- 截图 → 在 Typora 中
Ctrl+V
→ 图片自动上传到 Gitee → 自动替换为外链
7. 常见问题速查
| 问题 | 解决 |
|---|---|
| 上传提示 403 | 令牌权限不足,重新勾选 projects |
| 外链 404 | 仓库私有或分支名字填错 |
| macOS 权限 | 首次运行 PicGo 需在「系统设置 → 隐私与安全」允许 |
| Linux 无法启动 | 需安装 AppImageLauncher 或手动 chmod +x |
8. 进阶玩法(可选)
- 压缩插件:在 PicGo 插件商店搜索 compress 或 tinypng,上传前自动压缩。
- jsDelivr 加速:把
customUrl改成1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16https://cdn.jsdelivr.net/gh/用户名/imgbed@master
```
国外访问速度更快。
- **版本回滚**:Gitee 仓库自带 Git 历史,误删可找回。
---
## 9. 一键命令行脚本(可选)
如果你更喜欢终端,可全局安装 CLI 版:
```bash
npm i picgo -g
picgo set uploader gitee
picgo use uploader gitee
picgo upload demo.png
至此,PicGo + Gitee + Typora 图床链路全部打通,写博客、写文档、写 README 再也不用手动传图!