Markdown 笔记图片失效解决方案：Gitee+PicGo 图床搭建指南

引言

本地 Markdown 笔记常因图片路径依赖导致跨设备或分享后失效。解决这个问题的核心是搭建一个'图床'——把图片托管到云端，让链接永远有效。

本文将介绍使用 Gitee（国内免费仓库）+ PicGo（自动上传工具）+ Node.js（运行环境）搭建图床的方案，实现国内访问快、完全免费、无缝对接 Obsidian 的效果。

一、概念扫盲：为什么需要这些工具？

在开始操作前，先搞懂四个核心概念：

1. 图床：图片的'云端仓库'

• 定义：专门用来存储图片的云端平台，核心是生成'永久可访问的图片 URL'。
• 解决的痛：本地笔记里的 ![示例](./images/pic.png)，换电脑、分享给别人时，链接必然失效；图床的链接是'云端地址'，在哪台设备打开都能访问。

2. Gitee：国内版'代码托管平台'

• 定义：类似 GitHub，但服务器在国内，是免费的代码/文件托管平台。
• 为什么选 Gitee 当图床？
  • ✅ 访问快：国内节点，不用科学上网，图片加载秒开；
  • ✅ 免费开源：创建'开源仓库'后，图片可被公开访问；
  • ✅ 支持 RAW 链接：仓库里的图片能通过 https://gitee.com/用户名/仓库名/raw/分支/图片路径.png 直接访问。

3. PicGo：图片上传'自动化神器'

• 定义：图片上传客户端，核心是'一键上传本地图片，自动生成网络链接'。
• 核心价值：把'登录 Gitee→找仓库→点击上传→复制链接'的繁琐步骤，压缩成'拖入图片→自动出链接'。
• 为什么需要插件？PicGo 默认不直接支持 Gitee，需要安装 gitee-uploader 插件。

4. Node.js：插件的'动力引擎'

• 定义：让 JavaScript 代码能在电脑本地运行的运行时环境。
• 作用：PicGo 的插件是用 Node.js 开发的，必须安装 Node.js 才能运行这些插件。

二、环境搭建：Node.js 安装

2.1 下载 Node.js

访问 Node.js 官网，选择 LTS 长期支持版。

• Windows 用户选 x64 Installer；
• macOS 选 .pkg 安装包；
• Linux 通过包管理器安装。

2.2 安装与验证

1. 双击安装包，勾选'Add to PATH'；
2. 一路点击'Next'，默认路径安装即可。

打开命令提示符（CMD），输入以下命令验证：

node -v
npm -v

若正常输出版本，说明安装成功。

三、PicGo 安装：图片上传客户端

3.1 下载对应版本

访问 PicGo 官网 或国内镜像，根据系统选择。

• Windows：优先选 PicGo-Setup-xxx-x64.exe；
• macOS：选 PicGo-xxx.dmg；
• Linux：选 PicGo-xxx.AppImage。 建议选 2.4 版本及以上，老版本可能不支持 Gitee 插件。

3.2 安装与启动

1. 双击安装包，按向导完成安装；
2. 启动 PicGo 后，右下角托盘会出现图标，右键→'打开主界面'即可操作。

四、Gitee 配置：创建图片仓库

4.1 新建 Gitee 仓库

1. 填写关键信息：
   • 仓库名称：建议含 img 或者 picture；
   • 可见性：必须选'开源'（否则图片无法公开访问）；
2. 点击'创建'。初始化仓库勾选自动生成 README。

4.2 获取访问令牌（Token）

1. 点击 Gitee 头像→'设置'→'私人令牌'→'生成新令牌'；
2. 配置令牌：
   • 描述：填 PicGo 图床；
   • 权限：仅勾选'projects'（最小必要权限）；
3. 提交后，复制生成的 Token（仅显示一次，务必保存）。

五、PicGo 配置：连接 Gitee 图床

5.1 安装 Gitee 插件

1. 打开 PicGo 主界面→左下角'插件设置'；
2. 命令行手动安装：

npm install picgo-plugin-gitee-uploader -g

3. 先换国内 npm 源（加速下载）：

npm config set registry https://registry.npmmirror.com

4. 搜索框输入 gitee，找到 gitee-uploader 插件，点击'安装'。

5.2 配置 Gitee 图床参数

1. 在 PicGo 中填写关键参数： | 参数 | 填写规则 | 示例 | | --- | --- | --- | | repo | 用户名/仓库名 | your_gitee_name/note-img-bed | | branch | 仓库分支 | master | | token | Gitee Token | xxxxxxxxxxxxx | | path | 图片存储路径 | img/ | | customPath | 按日期分类（可选） | ${year}/${month}/${day} |

2. 回到 PicGo 主界面→'图床设置'→选择'Gitee'→'设为默认图床'。

六、Obsidian 集成：让本地图片自动上传

6.1 安装图片上传插件

1. 打开 Obsidian→'设置'→'社区插件'→'浏览'；
2. 搜索 Image Auto Upload，点击'安装'→'启用'。

6.2 配置 PicGo 服务

1. 在 Obsidian 插件设置中，找到'Image Auto Upload'；
2. 端口：默认 36677，上传接口默认为 http://127.0.0.1:36677/upload；
3. 若被占用，可在 PicGo→'设置'→'设置 Server'中修改端口。

6.3 测试上传

1. 在 Obsidian 中插入本地图片；
2. 查看图片链接：已自动替换为 Gitee 的网络链接；
3. 验证：复制链接到浏览器，若能正常显示图片，则配置成功。

七、常见问题排查

7.1 PicGo 上传失败

• ❌ Node.js 未安装：重新运行 node -v 验证；
• ❌ 仓库路径错误：检查 repo 是否为 用户名/仓库名，path 是否与仓库 img 文件夹一致；
• ❌ Token 权限不足：重新生成 Token，确保勾选 projects 权限。

7.2 Gitee 图片无法访问

• ❌ 路径错误：检查 PicGo 配置的 path 和仓库实际文件夹是否一致；
• ❌ 仓库未开源：进入 Gitee 仓库→'管理'→'基本信息'→设为'开源'。

7.3 Obsidian 上传无反应

• ❌ 端口冲突：修改 PicGo 的 Server 端口，并同步更新 Obsidian 插件配置；
• ❌ PicGo 未启动：确保 PicGo 在后台运行（托盘有图标）。

八、总结

通过 Gitee（存储）+ PicGo（上传）+ Node.js（环境）的组合，实现了本地图片自动转网络链接，跨设备、跨平台访问稳定。配合 Obsidian 插件，写作时'无感上传'，专注内容创作。

附录：工具速链

• Node.js 下载：https://nodejs.org/
• PicGo 官网：https://molunerfinn.com/PicGo/
• Gitee 官网：https://gitee.com/