1. 为什么我用 GitHub 当图床需求拆解与方案选型写 Markdown 的人迟早会撞上同一个问题本地截图往编辑器里一粘预览看着挺好一发到博客、笔记软件或者项目文档里图片全变成一个个裂开的图标。原因很简单本地路径./images/demo.png只在你自己的硬盘上成立换台设备、换个平台它就什么都不是。图床这个词听着玄乎说白了就是把图片放到一个公网能访问的地方拿到一条固定的外链用这条链接代替本地路径。而 GitHub 图床就是拿 GitHub 的仓库当这个存储空间靠仓库的公开访问能力把图片暴露出去。这套方案我在自己的 Hexo 博客和几份长期维护的文档里用了三年多零成本、可追溯、能版本回滚对我来说性价比相当高。这篇东西写给三类人刚接触 Markdown 想给博客配图的新手、被第三方图床跑路坑过一次的老玩家以及想把图片资产管理得稍微正规一点的独立开发者。下面从选型逻辑一路讲到踩坑排查全部是我自己跑过的路径。1.1 图床到底帮你解决了什么先把这个概念彻底说透不然后面的选型判断你会没有依据。图床的本质是存储加外链这两件事的组合存储负责把文件放住外链负责让别的地方能引用。传统做法是把图片和文章放在一起跟着项目走这在单机写作时完全没问题但一旦涉及多端同步、多平台分发立刻崩盘。我自己遇到的第一个真实场景是博客文章 Markdown 存在一台机器上图片放在source/images里结果换电脑写作时忘了同步图片目录推上去的文章图片全部 404一篇几千字的教程直接废掉。图床解决的正是这个耦合问题。图片上传到一个公共空间拿到形如https://xxx/2025/06/demo.png的链接这条链接写进 Markdown 之后文章本身变成一个自包含的纯文本文件你把它复制到任何地方——博客、公众号草稿、Issue、给同事的邮件——图片都能正常显示。这是核心价值也是所有图床方案共同要满足的第一需求。第二个价值是编辑体验。用图床之后写作流程会被压缩成截图 → 快捷键上传 → 剪贴板自动变成外链 → 粘贴整个过程两三秒不用手动存文件、不用管命名冲突。这个体验提升对高频写作者来说非常关键因为一旦流程超过十秒人就会开始偷懒最后变成文章里全是此处应有图。第三个价值是可迁移性。图片链接是纯文本只要链接本身长期有效你的文章就永远不依赖某个特定平台。这一点在选型时权重极高后面会展开。1.2 三种主流方案横着比一遍图床方案粗略分三大类商业对象存储、自建服务器、代码托管仓库。我把它们放在同一张表里对比这张表是我当年选型时反复推敲后定下来的判断依据。维度商业对象存储自建服务器GitHub 仓库初期成本低有免费额度高服务器域名人力零长期成本按量计费流量大时明显固定月费闲置也花钱零有软性限制上传体验官方 SDK 成熟工具支持好需要自己写接口工具生态好PicGo 直接支持数据掌控在别人手里完全自己掌控在别人手里但可完整克隆版本管理基本没有看你怎么做原生支持每次上传都是一次 commit可用性风险欠费即停敏感内容会被清理服务器到期、磁盘满、欠费仓库违规被限制或超过容量阈值迁移难度中要批量导出低数据在自己手上低git clone 一把梭这张表里最值得说的是可用性风险这一行。很多人选图床只看免费不免费忽略了一个关键事实图床一旦失效你所有历史文章的图片会同时挂掉而且是批量挂掉那种感觉就像家里所有灯泡一起烧了。所以我判断图床方案的标准不是最便宜而是失效时我能不能带走数据。GitHub 仓库在这一点上得分很高因为整个仓库就是一个完整的 git 仓库克隆下来就是全量备份连历史版本都在。还有一行是版本管理这在其他方案里基本是空白。GitHub 仓库每上传一张图片就是一次 commit意味着你误删了某张图可以精确恢复到删除前的状态你上传了一张有问题的图比如带隐私信息的截图也能从历史里彻底清掉。这种能力在写技术文档时特别有用——文档里的截图经常需要更新旧版本留着反而方便对照。1.3 GitHub 方案的真实边界别把它当成无限仓库讲优点的时候必须把限制讲透不然你用到一半会很难受。GitHub 免费账号的仓库在容量上有明确的软性边界单个文件不能超过 100MB网页端拖拽上传时单个文件限制在 25MB仓库整体建议控制在 1GB 以内超过 5GB 会收到平台的容量提醒。这些数字不是我编的是官方文档里的明确表述。对图床用途来说100MB 的单文件限制完全够用——一张正常压缩过的网页配图通常在 100KB 到 500KB 之间一张高清截图撑死 2MB。真正需要警惕的是仓库体积膨胀。图片是二进制文件git 对二进制的处理效率远低于文本而且每次修改都会产生一个新版本存进历史。假如你习惯性地上传一张图、删掉、再传一张改过的历史里会同时保留两个完整文件。三年下来一个看起来只有 300 张图的仓库实际体积可能到 2GB 以上。我在第二年就遇到过这个坑清理历史花了整整一个下午后面会专门讲怎么处理。另一个必须说清楚的边界是公开性。用 GitHub 仓库做图床仓库必须是公开的意味着任何人拿到链接都能看到你的图片也能翻你的仓库目录。所以有几类图片绝对不要往上放含个人证件、订单号、手机号、住址的截图公司内部系统的界面截图有明确版权归属且未获授权的素材。这不是平台规则问题是你自己该有的基本习惯。上传前用系统自带的截图工具把敏感区域涂掉或者干脆换一张示意图这个动作花不了十秒。2. 动手之前的准备账号、仓库与目录结构准备工作看着琐碎但这一步做对了后面能省掉大量返工。我见过太多人图快仓库随手起个名字、图片全部堆在根目录半年后打开仓库自己都找不到东西在哪里。下面这几点是我自己踩过坑之后固定下来的做法。2.1 建仓库时三个参数别乱选新建仓库的页面上有三个选项容易选错逐个说。第一是仓库可见性必须选 Public。私有仓库的 raw 链接需要携带访问凭证没法直接用在 Markdown 里做图床等于白做。这一点很多人第一步就走偏建完私有仓库折腾半天发现图片加载不出来。第二是是否初始化 README。建议勾上因为它会顺手创建 main 分支。如果你不勾仓库建完是空仓库此时推送代码需要一个初始提交对不熟悉 git 的人来说容易卡住。勾上 README 之后仓库立刻处于可用状态省事。第三是仓库名。名字随你但我建议带一点语义比如img-bed或者blog-assets以后你在别人的配置文件里看到这个仓库名一眼就知道它是干什么的。别用test、aaa这种过半年你自己都要猜。建完之后记下两个信息用户名和仓库名后面所有配置都要用到格式是用户名/仓库名。2.2 目录结构决定你半年后会不会想重来这是我认为整个搭建流程里最容易被低估的一步。图片全部堆在根目录会发生什么第一仓库首页打开是几百个文件名找东西靠肉眼扫描第二不同文章的同名图片会冲突demo.png上传第二遍就直接覆盖第一张而你往往不会及时发现第三将来想批量处理某一个时间段或某一个主题的图片时无从下手。我现在的目录方案是按主题分一级、按年月分二级images/ ├── blog/ │ ├── 2024-03/ │ │ └── gh-pages-01.png │ └── 2024-06/ │ └── picgo-config-01.png ├── notes/ │ └── 2025-01/ │ └── sql-index-01.png └── misc/ └── 2025-06/ └── screenshot-01.png这样做有三个好处。第一物理隔离不同主题、不同月份的图片永远不会重名冲突因为路径天然不同。第二可批量操作要做格式转换或者清理时直接针对某个目录跑一条命令就行。第三便于迁移将来如果你要把某一部分图片搬到别的图床只需要处理对应的子目录。命名上我坚持两条全小写英文加短横线不用中文、不用空格、不用大写字母。中文文件名在某些场景下会被转义成一长串百分号编码链接会变得又丑又容易出错空格在 Markdown 的链接语法里需要转义也是麻烦源头。至于加不加随机后缀看你的工具PicGo 支持按时间戳自动命名我一般开着因为时间戳能天然避免重名代价是可读性差一点但图床的链接本来也没人会去读。2.3 本地工具链准备纯网页操作也能做图床但效率太低建议至少装一个 git 客户端。命令行用户直接用系统自带的 gitWindows 用户如果不想碰命令行装 GitHub Desktop 完全够用图形界面上传图片就是把文件拖进去然后点提交。需要提前配置的只有两行git config --global user.name 你的名字 git config --global user.email 你的邮箱这两行决定了你每次提交时记录的作者信息跟图床功能无关但提交历史上会显示建议填个正常的名字。另外建议准备一个图片压缩工具。图片体积直接决定加载速度和仓库膨胀速度我实测下来同样的截图用无损压缩工具过一遍能小 30%转成 WebP 格式能小 60% 到 70%。Squoosh 是一个网页版工具拖进去选好质量参数下载就行命令行党用 ImageMagick 的mogrify -strip -quality 82一条命令批量处理整个目录。这一步千万别省你现在省下的十秒钟将来会变成几 GB 的仓库和一堆加载缓慢的文章页面。3. 三种落地路径实测从纯手动到全自动准备工作做完接下来是真正把图片传上去。我把上手难度从低到高排了三条路径你可以根据自己的使用频率选也可以先手动跑一遍理解原理再上自动化工具。3.1 纯手动网页拖拽加手拼链接这条路径一次都不用装软件适合偶尔传一两张图的人也适合第一次搭建时用来验证仓库配置是否正确。操作步骤打开你的仓库页面进入你要放图片的目录点Add file菜单里的Upload files把图片拖进虚线框等进度条走完在下方填写提交信息比如add 2025-06 blog images点Commit changes。上传完成后点击图片文件页面上会显示预览右键选择复制图片地址就能拿到链接。注意事项这里复制到的链接格式是https://github.com/用户名/仓库名/blob/main/路径/文件名注意中间是blob这个链接是 GitHub 的网页预览页不是图片直链。图片直链要把github.com换成raw.githubusercontent.com同时把blob换成refs/headshttps://raw.githubusercontent.com/用户名/仓库名/refs/heads/main/images/2025-06/demo.png或者用短格式把blob直接换成raw也能访问https://raw.githubusercontent.com/用户名/仓库名/main/images/2025-06/demo.png这两种写法我都用过日常更推荐短格式因为短、易读、方便手改。手拼链接虽然笨但胜在你对链接结构有完全的掌控后面遇到 404 时排查思路会清晰很多不会出现工具帮我做了什么我都不知道的情况。3.2 半自动PicGo 配置要点与 Token 最小权限这是绝大多数人的最终方案。PicGo 是一个开源的图片上传工具支持把剪贴板里的图片一键传到 GitHub 并把链接自动写回剪贴板。它的配置里有一个关键步骤容易被做错——访问令牌的权限范围。先说令牌怎么拿。打开 GitHub 的设置页找到 Developer settings 里的 Personal access tokens我建议用 Fine-grained tokens 这种细粒度令牌因为它可以精确指定只允许访问某一个仓库。创建时选好过期时间我一般设 90 天到期换新比永不过期的安全Repository access 选Only select repositories勾上你的图床仓库。权限部分只需要给Contents 的 Read and write其他一律不给。这一步很多人直接勾了repo全权限那是粗粒度令牌的做法范围太大一旦令牌泄露别人可以动你所有仓库风险完全没必要承担。拿到令牌后在 PicGo 的图床设置里选 GitHub填这几个字段配置项填什么说明仓库名用户名/仓库名中间的斜杠不能少也不能有空格分支名main老仓库可能是master去仓库首页确认Token刚才生成的令牌粘贴后不要再动末尾不要带空格存储路径images/blog/2025-06/末尾的斜杠建议保留自定义域名留空先用 raw 直链后面配 CDN 时再填设定仓库名格式保持默认影响不大实测心得填完之后点设为默认图床然后上传一张测试图。如果提示 404八成是仓库名写错或者令牌没给 Contents 权限如果提示 401基本就是令牌粘贴时多带了空格很多编辑器复制粘贴会带尾随换行这个坑我踩过两次排查时先看这里。还有一个细节值得说PicGo 的存储路径字段支持时间变量写成images/{yyyy}-{MM}/的话它会自动按当前年月建目录你不用手动改。这个功能配合前面讲的目录结构基本可以做到上传即归档。3.3 命令行批量上传Contents API 脚本如果你需要一次传几十张图或者想把上传集成到构建流程里用 API 比点鼠标快得多。GitHub 提供了一个 Contents API允许通过 HTTP 请求创建文件。#!/usr/bin/env bash # upload.sh - 批量上传当前目录下的 png/jpg 到指定仓库 set -euo pipefail GH_TOKEN你的令牌 OWNER用户名 REPO仓库名 BRANCHmain REMOTE_DIRimages/blog/2025-06 for f in *.png *.jpg *.jpeg; do [ -e $f ] || continue name$(basename $f) content$(base64 -w0 $f) body$(jq -n \ --arg msg upload $name \ --arg c $content \ --arg b $BRANCH \ {message:$msg, content:$c, branch:$b}) curl -sS -X PUT \ -H Authorization: Bearer $GH_TOKEN \ -H Accept: application/vnd.githubjson \ https://api.github.com/repos/$OWNER/$REPO/contents/$REMOTE_DIR/$name \ -d $body /dev/null echo uploaded: $REMOTE_DIR/$name done这段脚本我用了很久要注意三个点。第一base64 -w0里的-w0是必须的不加的话 base64 输出会按 76 字符换行JSON 会解析失败这个错误提示很不直观容易卡半天。第二用jq拼 JSON 是为了避免文件名里有特殊字符时手动转义出错如果系统没装 jq用sudo apt install jq或brew install jq装上。第三如果同名文件已存在这个接口会报 422需要先取文件的sha再带上去做更新脚本里我没处理这种情况因为图床场景下重名本来就应该避免配合时间戳命名基本不会撞上。3.4 全自动用 Actions 给图片做压缩归档上传之后还有一个隐藏的成本图片是原图体积偏大。可以挂一个 GitHub Actions 工作流在图片推上来之后自动压缩一遍压缩结果直接提交回仓库。name: optimize-images on: push: paths: - images/** permissions: contents: write jobs: compress: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Install ImageMagick run: sudo apt-get update sudo apt-get install -y imagemagick - name: Compress PNG and JPEG run: | find images -type f \( -iname *.png -o -iname *.jpg -o -iname *.jpeg \) \ -exec mogrify -strip -quality 82 -resize 1920x1920 {} \; - name: Commit changes run: | git config user.name img-bot git config user.email img-botusers.noreply.github.com if [ -n $(git status --porcelain) ]; then git add -A git commit -m chore: optimize images [skip ci] git push else echo nothing to commit fi这段配置里有三个关键设计值得单独解释。permissions: contents: write是必须的GitHub 从某个版本起默认给 Actions 的令牌只有只读权限不显式声明写权限最后一步推送会直接失败。[skip ci]这个标记写在提交信息里作用是阻止压缩提交再次触发自身否则会陷入无限循环——机器人提交 → 触发工作流 → 又提交很快就把你的 Actions 额度耗光。if [ -n $(git status --porcelain) ]是为了避免没有变化时执行空提交空提交会报错中断工作流虽然不影响功能但每次看到红色的失败标记心里不舒服。-resize 1920x1920里的符号表示只在图片大于这个尺寸时缩小小图不会被放大。1920 这个数字是我权衡后的选择绝大多数显示场景博客正文、文档、聊天分享宽度不会超过 1400 像素1920 留了余量同时能把手机截的长图从四五兆压到几百 KB。4. 链接加速与失效排查图片传上去了链接也能打开但你会发现一个问题raw.githubusercontent.com这个域名在国内访问时快时慢有时候一张图要转好几秒才出来博客页面整体加载体验很差。这一节讲怎么处理以及链接失效时怎么排查。4.1 raw 直链为什么慢CDN 换法怎么用raw.githubusercontent.com是 GitHub 用来分发仓库原始文件的域名本身没有针对国内做节点优化所以响应时间波动很大。解决思路很简单把图片文件交给一个在国内有节点的内容分发网络让它来扛流量。图片是静态文件天然适合这种做法。最常用的选择是 jsDelivr它对公开的代码仓库提供免费的静态资源分发链接格式是这样https://cdn.jsdelivr.net/gh/用户名/仓库名分支名/images/2025-06/demo.png注意几个细节。路径部分是gh/用户名/仓库名分支名/文件路径gh是它区分代码托管平台的标识不能省。分支名那一段是可选的不写默认走默认分支但我强烈建议写上因为显式指定分支之后你切分支或者默认分支变动时链接不会莫名其妙失效。如果想锁定某个具体的提交可以把分支名换成 commit 的短哈希链接就变成永久不变的了——这个做法适合那种发出去就不打算改的正式文档。在 PicGo 里把自定义域名填成https://cdn.jsdelivr.net/gh/用户名/仓库名main之后上传的图片链接会自动带上这个前缀不用手动替换。需要知道的限制jsDelivr 对单个文件有体积门槛官方给的上限在 20MB 量级超过就不提供服务。另外它对仓库整体体积也比较敏感如果你那个仓库膨胀到几 GB它有可能会拒绝分发。所以前面反复强调的控制图片体积在这里体现出了价值——不是洁癖是实实在在影响可用性。除了 jsDelivr也可以自己做更进一步的优化比如在博客的构建流程里把图片链接统一替换成 CDN 域名或者给图片加上loadinglazy属性做懒加载。这两件事都跟图床本身无关但对页面加载速度的影响比换 CDN 还大顺手做掉收益很高。4.2 404 和 403 速查表图片突然打不开是最常见的问题绝大多数原因就那么几个。我把排查过的情形整理成表按出现频率排序。现象最可能的原因排查动作404 Not Found文件名或路径大小写不一致去仓库里逐字符比对路径Linux 下大小写敏感404 Not Found分支名写错main 写成 master打开仓库首页看分支下拉框显示的名字404 Not Found用了blob链接而不是raw链接检查 URL 里是否还留着blob403 Forbidden仓库是私有的仓库设置里改成 Public403 Forbidden令牌权限不足或已过期重新生成令牌并更新 PicGo 配置图片显示成一段文字链接指向的是网页预览而非文件换成 raw 或 CDN 域名链接能开但博客里空白页面使用了 https 而链接是 http全部统一成 https上传报 422仓库里已存在同名文件换文件名或先删除旧文件图片偶尔加载失败CDN 节点缓存未生效或限流换回 raw 链接对比确认是 CDN 侧问题这张表里最值得展开的是大小写问题。Windows 和 macOS 的文件系统默认不区分大小写所以你在本地看Demo.PNG和demo.png感觉没差别但 GitHub 的服务器是区分大小写的一旦链接里的大小写和实际文件名不一致立刻 404。我遇到过最诡异的一次是图片上传后能显示过了一天打不开查了半天才发现是重命名时只改了大写字母git 根本没记录这次改动。403 那个情形也需要特别注意。如果你把图床仓库从 public 改成了 private比如临时想保密那么所有历史文章的图片会同时失效而且是静默失效——除非有人告诉你你根本不知道。所以仓库可见性这个开关改之前一定想清楚。4.3 缓存和历史遗留导致的怪问题有一类问题特别迷惑人图片明明删了或者改名了访问旧链接还能打开。这是 CDN 缓存在起作用。jsDelivr 这类服务会把文件缓存到边缘节点缓存时间可能长达数天甚至更久你更新了仓库内容节点上还是旧版本。处理办法有两个。一是主动刷新jsDelivr 提供了刷新入口在链接前面加上purge路径访问一次即可请求刷新缓存。二是绕过缓存在链接末尾加一个查询参数比如?v2因为 CDN 的缓存键包含查询串加了参数就相当于换了一个新资源。这个技巧在做版本迭代时很实用——你更新了文章里的某张截图直接给链接加个?v2所有读者的浏览器和 CDN 都会重新拉取不用等缓存过期。另一种历史遗留问题是误删图片。Git 的好处在这里体现出来即使你删了文件并提交历史里还有完整记录。恢复方式是在本地克隆仓库用git log --diff-filterD --name-only找出删除该文件的提交然后在那个提交的前一个版本里把文件取出来git checkout 提交哈希^ -- images/2025-06/demo.png取出来之后重新提交一次图片就回来了。注意如果删除操作发生得很久以前仓库历史很长这个操作会比较慢所以还是建议平时做基础备份。5. 长期维护容量、备份与迁移图床这种东西搭建起来只要半小时真正花时间的是后面的维护。我用了三年多总结出几条必须做的动作。5.1 仓库体积控制与历史清理先学会查体积。本地克隆仓库后在根目录执行du -sh .git这个数字是 git 历史占用的空间往往比工作目录大得多。如果发现.git目录体积明显异常说明历史里堆积了大量被删掉的图片。处理方式有两种按代价从低到高。第一种是浅克隆加新建仓库如果历史记录对你没价值直接建一个新仓库把当前工作目录的文件拷过去推上去老仓库归档或者删掉这是最省事的做法代价是丢失所有提交历史。第二种是历史重写用git filter-repo这类工具把历史中的大文件剔除保留提交记录但这个操作会改变所有提交哈希属于破坏性操作执行前必须完整备份而且不要在共享仓库上随便用。我更推荐的做法是从源头控制。上传前统一压缩单张图控制在 500KB 以内不用手机原图直接传先在本地过一遍压缩定期检查仓库体积发现有几百 KB 以上的大图就处理掉。这套习惯坚持下来我那个用了三年的图床仓库到现在才 400MB 出头。5.2 备份与迁移预案任何依赖单一平台的方案都要想清楚平台不用了怎么办。GitHub 图床在这件事上有个天然优势你的数据是完整的 git 仓库克隆下来就是全量备份。我给自己定的规矩是每季度克隆一次到本地移动硬盘成本几秒钟心里踏实。迁移到别处也不难因为你的文章里存的都是完整 URL只要有工具能做批量替换就行。真要做迁移步骤大概是这样把仓库克隆到本地把图片上传到新图床同时记录新旧路径的对应关系用批量替换工具比如sed或者编辑器的全局替换把文章里所有旧域名替换成新域名推上去验证。关键前提是你的域名替换是精确的如果新旧路径结构不一致替换就会出错所以前面强调的URL 里带完整路径其实是在为将来迁移铺路。我建议你至少准备两个备选方案。一个是可以直接切入的备用 CDN比如同时用两个分发服务的域名主域名出问题时能快速切换另一个是完全不同的图床类型比如对象存储万一整个路子走不通可以直接搬。这两条都不用真的部署想清楚流程、写在笔记里就够了。5.3 每月花十分钟做的检查维护图床不需要天天盯着但有几件事值得定期过一遍我固定成一个月一次随便抽三篇历史文章打开看图片是否正常加载早发现 404 早处理看仓库体积有没有异常增长du -sh .git对比上月检查访问令牌的过期时间快到期就提前换别等它失效再折腾看仓库里有没有误传的敏感截图有的话从历史里清掉确认 CDN 域名还能正常访问必要时刷新缓存这套动作加起来不到十分钟但能避免绝大多数某天突然发现所有图都挂了的惨剧。我自己就有过一次教训某篇文章里的三十多张图全部失效读者在评论区问了三天我才发现原因是那篇文章用的链接格式还是早期的blob写法而平台改过一次重定向规则。从那以后我就养成了定期抽查的习惯。6. 踩坑实录与常见问题前面讲了很多应该怎么做这一节讲实际会出什么岔子。这些都是我自己或者身边的人真实遇到的问题比文档里的说明更接近实际情况。6.1 我踩过的几个坑第一个坑是仓库体积失控。刚开始用的时候我完全没有压缩概念手机截图、录屏截帧直接往上传一张图五六兆。半年后发现克隆仓库要等好几分钟一看.git目录已经 1.8GB。处理方式是新建了一个仓库只把当前需要的图片移过去老仓库留作归档。这次经历之后我给自己定了硬规矩上传前一定过一遍压缩压缩后超过 1MB 的图片要单独确认是否真的需要。第二个坑是令牌泄露。早期我把令牌直接写在一个公开的脚本文件里传到了仓库虽然是个临时测试仓库但还是惊出一身冷汗。现在我的做法是令牌一律通过环境变量注入绝不硬编码在文件里GitHub 提交前用git diff --cached扫一眼确认没有意外内容如果真泄露了立刻去设置页删除那个令牌重新生成一个。删除之后旧令牌立刻失效这一步是必须做的光删文件是没用的因为它已经进了历史记录。第三个坑是链接格式不统一。我的文章跨越了好几年早期用blob链接中期用raw链接后面才是 CDN 链接。三种格式混在一起出现问题时排查思路会被打断。后来我做了一次全局梳理把所有链接统一成带分支名的 CDN 格式世界清静了。如果你现在正在起头建议一开始就定好一种格式从此不要再变。第四个坑是关于压缩质量的。有一段时间我把压缩质量设得太激进截图里的代码文字边缘出现了明显的锯齿和色块在手机上看小字很吃力。后来把 JPEG 质量从 65 提到 82PNG 保持无损压缩观感立刻不一样。质量参数不是越小越好尤其是技术文档里的代码截图文字边缘的抗锯齿信息一旦被破坏可读性下降得很明显。6.2 新手最容易卡住的问题清单问题根本原因处理办法网页上传图片失败提示文件过大网页端单文件限制较严先压缩或改用 git 命令行推送git push 报错缺少权限用的是只读令牌或没配置认证检查令牌权限确认包含 Contents 写权限图片在编辑器里能预览Push 后 404本地路径没上传或大小写不一致检查仓库里的实际路径PicGo 上传成功但图片不显示用了网页预览链接而不是直链复制链接时手动改域名换电脑后工具配置全丢配置只存在本地定期导出 PicGo 配置文件备份同一张图反复上传产生多个副本工具没有按内容去重用固定命名规则上传前检查文章里图片排版错乱图片尺寸差异过大上传前统一宽度或压缩时限制最大边长这张表里有一个值得额外说明的点换电脑导致配置丢失。PicGo 的图床配置、令牌都是存在本地的很多人换台机器就懵了不知道怎么配回来。解决办法是定期导出配置文件或者在笔记里把仓库名、分支名、存储路径这些静态信息记下来只有令牌需要重新生成。这个准备工作花两分钟将来能省掉一次完整的排查。另外一个常见问题是图片尺寸不一致导致排版难看。你从不同来源截的图宽度可能是 800、1200、2560 像素混杂放进同一篇文章里会出现明显的参差。最省事的做法是在压缩环节统一把最大边长限制到 1920这样一来所有图片的显示宽度基本一致排版自然就整齐了。前面给的 Actions 配置里那行-resize 1920x1920就是干这件事的顺带还压了体积一举两得。6.3 最后再分享几个我一直在用的小技巧第一个是上传前先重命名。我习惯把文件名改成文章主题-序号的格式比如picgo-config-01.png。这样即使将来链接挂了光看 URL 我大概能想起这是哪张图、在哪篇文章里用过定位问题的速度快很多。第二个是给图床仓库单独建一个 README。里面写清楚这个仓库的用途、目录结构规则、命名规范、令牌的更新周期。听起来有点小题大做但这个 README 在我把仓库交接给同事、或者自己隔了半年再回来维护时救过两次命。第三个是把常用的上传命令做成别名。我在 shell 配置里加了一行把那段批量上传脚本简化成一个短命令写文档时直接imgup *.png就能传完整个目录比打开图形界面拖拽快得多。工具链这东西用得越顺手你越愿意坚持用它图床这种需要长期维护的东西尤其如此。第四个是关于图片格式选择的取舍。截图、图表、带文字的图用 PNG色彩丰富的照片用 JPEG需要同时兼顾质量和体积的场景可以试 WebP。WebP 的兼容性现在基本没问题主流浏览器都支持压缩率比 JPEG 高不少。但要注意文件扩展名必须正确否则 CDN 返回的内容类型会不对浏览器可能直接下载而不是显示。