解决 PicGo 上传 GitHub图床及Marp中Github图片编译常见难题指南

[目录]
0.行文概述
1.PicGo图片上传失败
2.*关于在Vscode中Marp图片的编译问题*
3.总结与启示

行文概述

写作本文的动机是本人看到了Awesome Marp，发现使用 $\texttt{Markdown}$ 做PPT若加持一些 $\texttt{CSS},\texttt{JavaScript}$ ，效果也能非常好。然后就发现，按照Awesome Marp的配置教程中，对于没有 $\texttt{JavaScript}$ 基础者而言，需要配置的东西相对较多。对本人而言，费时间最久的则是PicGo的Github图床设置问题。因该问题相对复杂且具有代表，故整理一篇教程。

作为一款广受欢迎的图床上传工具，PicGo 以其便捷性和多平台支持赢得了许多用户的青睐，尤其是配合 GitHub 作为免费图床的方案。然而，在配置 PicGo 连接 GitHub 的过程中，一些“拦路虎”常常会让用户头疼不已。本文将通过一个真实的故障排查案例，详细记录如何一步步解决从 SSL 证书验证失败到找不到目标分支等一系列问题，希望能为遇到类似困境的朋友提供一份清晰的解决指南。

案例背景： 一位用户 (HorseRunningWild，好吧，也就是本人) 在配置 PicGo (v2.3.1 或相近版本) 使用 GitHub 作为图床时，反复遭遇上传失败。

PicGo图片上传失败

本文主要旨在解决两类问题

第一类

unable to verify the first certificate
第二类

同样显示类似上文的"上传失败"，但 $\texttt{error}$ 什么也不报。仅显示“{}”。

第一步：初步诊断与常规检查

面对这类网络相关的错误，我们通常会从几个方面入手：

PicGo 日志分析：
首先我们应该打开PiCGo的日志：

可以发现.log文件中有类似内容

  2025-05-14 07:50:31 [PicGo ERROR] {
"method": "PUT",
"url": "https://api.github.com/repos/picture-bed/repo/contents/images/logo.png",
"statusCode": 0,
"message": "unable to verify the first certificate",
"stack": "Error: unable to verify the first certificate\n    at TLSSocket.onConnectSecure (node:_tls_wrap:1530:34)\n    at TLSSocket.emit (node:events:394:28)\n    at TLSSocket._finishInit (node:_tls_wrap:944:8)\n    at TLSWrap.ssl.onhandshakedone (node:_tls_wrap:725:12)",
"response": {
  "status": 0,
  "statusCode": 0,
  "body": ""
}

unable to verify the first certificate 和 statusCode: 0 是核心线索，表明问题出在网络层，甚至在 HTTP 请求发出之前。

网络环境切换： 遇到上述问题，可首先尝试更换网络。因为本人原本使用的是学校的网络，考虑到学校的网可能会有一些限制，故从切换到手机热点。但问题依旧。这在一定程度上排除了本地路由器配置或特定 ISP 策略的干扰，将疑点更多地引向了计算机本身的配置。
PicGo 配置项 rejectUnauthorized： 既然显示的是类似verify certificate的问题，接下来可能的尝试是在 PicGo 设置中（就在打开日志文件的上一条）的图床部分添加
```
{
"picBed": {
"github": {
  "repo": "your/repo",
  "branch": "main",
  "token": "your-token",
  "path": "images/",
  "customUrl": "",
  "rejectUnauthorized": false  // 新添加的代码
}
```

来尝试绕过 SSL 证书验证。虽然在本案例中用户也尝试过类似设置或默认情况下此选项可能不那么严格，但错误依然顽固。这暗示问题可能比单纯的证书链不完整更深层。

第二步：`curl` 命令显神威，定位DNS解析异常

当应用层面的调试陷入僵局时，动用底层网络诊断工具往往能带来突破。我们在这里会用到curl命令(发音同 “curl”)。curl 是一个非常强大的命令行工具和库 (libcurl)，用于通过 URL 与服务器进行数据传输。它支持多种网络协议，包括HTTP/HTTPS (最常用的，用于网页和 API)等等。在 macOS 和许多 Linux 发行版中，curl 通常是预装的，也就是系统自带的。
在 Windows 10/11 的较新版本中，curl.exe 也已经成为内置命令，可以直接在命令提示符 (CMD) 或 PowerShell 中使用。

curl的基本用法,如获取网页内容 (GET 请求)：

curl https://www.example.com

这会下载https://www.example.com 的 HTML 内容并显示在终端。

而我们需要的则是curl -v

curl -v https://api.github.com

-v (verbose) 参数让 curl 输出了详细的连接过程信息。很快，关键问题浮出水面：

* Host api.github.com:443 was resolved.
* IPv6: (none)
* IPv4: 127.0.0.1  <-- 症结所在！
*   Trying 127.0.0.1:443...
* schannel: next InitializeSecurityContext failed: CRYPT_E_NO_REVOCATION_CHECK (0x80092012) - 吊销功能无法检查证书是否吊销。
* closing connection #0
curl: (35) schannel: next InitializeSecurityContext failed: CRYPT_E_NO_REVOCATION_CHECK (0x80092012) - 吊销功能无法检查证书是否吊销。

重大发现！ api.github.com 竟然被解析到了 127.0.0.1，也就是 localhost（用户自己的电脑）。这意味着 PicGo 和 curl 在尝试连接 GitHub API 时，实际上是在“自己打自己”。本地计算机自然不可能提供 api.github.com 的有效 SSL 证书，因此“无法验证第一个证书”的报错也就顺理成章了。

第三步：揪出 `hosts` 文件中的“内鬼”

什么会导致域名被错误地解析到本地回环地址呢？最常见的元凶就是系统的 hosts 文件。

Windows: C:\Windows\System32\drivers\etc\hosts
macOS/Linux: /etc/hosts

在windows中，可以以管理员身份运行记事本，找到C:\Windows\System32\drivers\etc\hosts。在本人检查其 hosts 文件后，真相大白。原来，一款名为 “Steam++” 的 GitHub 加速软件为了实现其加速功能，修改了 hosts 文件，将大量 GitHub 相关域名（包括我们关心的 api.github.com）指向了 127.0.0.1，企图通过本地代理周转流量。

# Steam++ Start
...
127.0.0.1 steamcdn-a.akamaihd.net
...
127.0.0.1 api.github.com  <-- 就是你！
127.0.0.1 gist.github.com
...
127.0.0.1 github.com
...
# Steam++ End

当然，在此处显然也不是要苛责该加速器，因为确实，要是没有加速器，就只能挂梯子上Github了…

解决方案：
以管理员权限编辑 hosts 文件，将 127.0.0.1 api.github.com 这一行注释掉（在行首加 #）或直接删除。

# 127.0.0.1 api.github.com

修改保存后，务必刷新系统 DNS 缓存：

Windows (管理员CMD): ipconfig /flushdns

再次执行 curl -v https://api.github.com，输出结果令人振奋：

* Host api.github.com:443 was resolved.
* IPv6: (none)
* IPv4: 20.205.243.168  <-- 正确解析到 GitHub 公网 IP！
*   Trying 20.205.243.168:443...
* Connected to api.github.com (20.205.243.168) port 443
...
< HTTP/1.1 200 OK
...

网络通了！SSL 证书问题迎刃而解。

第四步：新挑战——“找不到 master 分支”

满心欢喜地再次尝试 PicGo 上传，然而，新的错误出现了：

{
  "method": "PUT",
  "url": "https://api.github.com/repos/HorseRunningWild/picturebed/contents/images/logo.png",
  "statusCode": 404, // 注意，不再是 0 了！
  "message": "Request failed with status code 404",
  "response": {
    "body": {
      "message": "Branch master not found", // 关键信息！
      "documentation_url": "https://docs.github.com/rest/repos/contents#create-or-update-file-contents"
    }
  }
}

这次的 statusCode: 404 表明 PicGo 已经成功连接并与 GitHub API 服务器进行了通信，但服务器反馈“未找到资源”。具体的错误消息是 Branch master not found。

原因分析：
近年来，出于社区多元化和包容性的考量，GitHub 将新建仓库的默认分支名称从 master 更改为了 main。如果用户的 picturebed 仓库是近期创建的，其默认分支很可能就是 main。而 PicGo 的 GitHub 上传配置中，默认或用户之前配置的分支名可能仍然是 master。但是，截止本文写作期间，PicGo官网的配置手册示例中仍然是 master，容易对新人造成误导。

PicGo 配置中对应的部分：

// PicGo 配置文件中的 githubUploader 部分
"github": {
  "repo": "HorseRunningWild/picturebed",
  "branch": "master", // <-- 这里可能与实际不符，应该改为main
  "token": "ghp_YourTokenHere",
  "path": "images/",
  "customUrl": ""
}

解决方案：

确认仓库实际分支名： 前往 https://github.com/HorseRunningWild/picturebed，查看仓库页面的分支选择器，确认主分支名称（大概率是 main）。
修改 PicGo 配置： 将 PicGo 配置文件中 GitHub 上传器的 branch 字段值从 "master" 修改为实际的分支名，如 "main"。
```
"github": {
  "repo": "HorseRunningWild/picturebed",
  "branch": "main", // 更新为正确的分支名
  // ...
}
```
保存配置，重启 PicGo (如果需要) 后再次尝试上传。

关于在Vscode中Marp图片的编译问题

因为图床毕竟是放在Github中，所以有时会出现，分明将图片的Markdown代码好好地放在IDE中，却无论如何也无法渲染出来。这种问题一般是两种可能：

网络问题。试试挂上VPN，因为国内访问Github的确受限。

或者，也可以直接尝试能否在浏览器种访问自己的图片，比如：
```
https://raw.githubusercontent.com/HorseRunningWild/picturebed/main/images/logo of hrw.jpg
```
如果可以的话，显然就是网络问题了。
检查自己的仓库是否为Public。
其它一些如Vscode中的Markdown插件问题，就不再赘述。

总结与启示

日志是金： 无论是应用程序日志 (PicGo) 还是工具输出 (curl -v)，详细的日志信息都是定位问题的基石。
底层工具的重要性： 当上层应用报错模糊时，使用如 curl, ping, nslookup 等网络诊断工具可以直接探测网络连通性和服务响应情况。
警惕“加速器”的副作用： 各类网络加速或代理工具，尤其是那些会修改系统 hosts 文件的，有时会好心办坏事，干扰特定服务的正常连接。
与时俱进： 关注目标服务（如 GitHub）的默认设置变更，例如默认分支名从 master 到 main 的转变，这可能导致依赖旧设置的工具出现兼容性问题。
系统化排查： 从应用层到网络层，再到系统配置层，逐层排查，由表及里，通常能更有效地找到问题根源。
**对于同样希望使用Awesome-Marp的朋友的建议：**遇到问题可以多看Github上的issue，以及记得在安装PicGo前需要先安装和配置 $\texttt{Node.js}$ ，建议先参考Node.js安装及环境配置超详细教程【Windows系统】