企业官网建设流程全解析

很多写 Markdown 的朋友，最开始都会把图片存在本地文件夹里。本地存图写文档那会儿确实省心，但一旦换了电脑、想把文章发到博客或者给同事看，问题就出来了：图片全挂，到处都是裂图图标。我那时候最开始用线上图片服务，快是真快，可免费额度说没就没，后来的收费方案对个人玩家不太划算。后来折腾出一套不用花一分钱、又能长期稳定的方案，就是用 Typora 配 PicGo 再挂到 Gitee 上，也就是常说的码云图床。这套方案跑了一阵子，整理一篇完整的配置记录出来，顺便把踩过的坑也一并写清楚。

1. 图床方案选型与整体链路拆解

先聊聊为什么要用图床，以及为什么最后定下来是 Typora 加 PicGo 加 Gitee 这么一套组合。

Markdown 文件本质是纯文本，图片没法像富文本那样“嵌”进文档里。Markdown 里写一张图片，引用的其实是一个 URL 地址。你用本地相对路径，比如![](img/photo.png)，这个路径只在你自己的电脑上有效。发到网上，别人电脑上根本没有img/photo.png这个文件，自然就显示不出来。图床要做的事情，就是把图片文件放到一个互联网上能直接访问的位置，生成一个公网 URL，让谁都能通过这个链接看到图片。

市面上图床方案大致分三类。

第一类是直接用平台自带的图片上传功能，比如在博客后台粘贴图片。这种方案很简单，图片自动传到平台服务器上，但缺点也很明显：图片和平台绑定。你在这家平台发的文章，如果某天想搬到自己的博客或者另一个平台，图片没法跟着走，全还留在原平台。等于文字搬走了，图全留在那儿了，文章还是残缺的。

第二类是找专门的图床服务商。这类服务大多打着“免费图床”的旗号，用起来也确实方便，注册完往上一传就有链接。但我个人不建议把重要图片存这类服务上，免费图床的稳定性往往没有保障，图片链接可能过几个月就失效了。你前期写得越多，后面图片清零的风险就越大，这种方案适合发临时图片，不适合做正经的内容沉淀。

第三类就是自建图床，也就是基于对象存储或者代码托管平台来做。对象存储如各大云的 OSS 服务，稳定性和速度都很好，但要实名认证、开通服务、看计费规则，对只是想写写文档的人来说门槛偏高。代码托管平台的好处是，你本来就在上面放代码，顺手开个仓库存图片，基本零学习成本，也不涉及开通什么额外服务。

Gitee 在这类平台里有个天然优势：国内的访问速度快。写笔记的图基本都是国内访问场景，图片放在国内平台，加载速度会比放在国外服务器上明显快一截。而且 Gitee 个人仓库不限数量，存图片完全够用。我之前也试过其他代码托管平台，要么访问速度不理想，要么免费版有心跳限制，用来当图床总有点别扭。Gitee 没有这些限制，所以最后定下来用它。

这套链路跑起来的流程是这样的：你在 Typora 里写文章，插入一张图片，Typora 把图片交给 PicGo，PicGo 负责把图片上传到 Gitee 的仓库里，上传成功后返回图片的直链地址，Typora 拿到这个地址自动贴到 Markdown 里。整个过程不需要你手动去复制图片、打开网页、上传，再复制链接回来。从你粘贴图片到文档里显示出来，中间几秒钟就完成了，完全是流水线式的体验。

整个方案用到的工具有三个，分工也明确。Typora 是写作前端，负责捕获你粘贴的图片并调用外部程序；PicGo 是中间桥梁，承担了接收图片、上传图片、返回链接的角色；Gitee 是最后的存储位置，图片最终以文件形式躺在仓库里，通过 Gitee 的链接供公网访问。

2. 准备工作：搭建 Gitee 图床仓库并获取访问令牌

整个链路里，Gitee 这端需要准备两样东西：一个存图片的仓库，一串访问令牌（Token）。仓库用来装图片，令牌是 PicGo 上传图片时用来验证身份的凭证。

2.1 创建图片仓库：命名、开源与初始化选择

在 Gitee 上新建仓库时，有几个配置项需要认真对待。

仓库名称建议用纯英文加连字符，比如my-image-hosting或pic-bed。这是因为图片 URL 最终会包含仓库名，中文仓库名在拼接 URL 时可能被转义成一堆百分号编码，不仅难看，个别场景下还可能造成兼容问题。用英文名就完全没这些烦心事。

仓库是否公开，取决于你对图片传播范围的要求。私有仓库也能作为图床用，但有一个前提条件：必须配合 Token 认证。在 Gitee 上，私有仓库的文件链接不发 Token 给外部访问者时，是无法直接预览的；但你只要在访问图片的 URL 里带上 Token 参数，链接依然可以被浏览器加载。问题是这样的链接会赤裸裸地暴露你的令牌，一旦链接被别人拿到，你的仓库也就等于被看到了。除非你的图片真的极度私密，我建议直接建公开仓库，图片本身就希望被访问，公开了反而省事。

初始化仓库那一栏还有一个选项叫“使用 Readme 文件初始化这个仓库”。建议勾上它。这个选项会自动帮你生成master分支并完成初始提交。不勾选的话，仓库是空的，PicGo 上传时可能要处理分支不存在、仓库为空等边界情况，配置起来更麻烦。勾选后仓库自带主分支结构，后面配置 PicGo 时直接用主分支的名字即可，省去不少弯路。

仓库建好后，进入仓库首页，记得看一眼地址栏。完整的仓库地址一般长这样：https://gitee.com/你的用户名/你的仓库名。后面配置 PicGo 时，仓库信息里的owner填用户名，repo填仓库名，这两个值不要填反。

2.2 申请私有令牌：权限设置与安全须知

Gitee 的 Token 机制，用来替代账号密码完成第三方程序的授权。这个令牌在 Gitee 上叫做“私人令牌”，生成入口在个人设置里面：点头像进入个人主页，找到“设置”一栏，然后进入“私人令牌”页面，点击“生成新令牌”。

生成令牌时有一份权限列表需要勾选。PicGo 需要读取仓库信息、上传文件到仓库的能力，所以基本只要把projects相关的权限勾上就行。我当时勾选的是projects下的所有权限，实测下来上传图片完全够用。不建议图省事把所有权限全勾了，令牌权限越大，泄露后的风险也越高。够用就好，这是最基础的安全常识。

提交生成请求后，页面会展示一串新令牌。这串令牌只会出现这一次，刷新页面后就再也看不到了，务必当场复制保存。如果忘了复制，只能重新生成一个新令牌。令牌本身是字母数字组成的字符串，通常会以开头几个字母标识，可以把它想象成你仓库的一把备用钥匙，谁拿到它谁就能往你仓库里传文件。

安全上还要提一句：这个令牌建议放在自己的密码管理器或者私人笔记里，不要提交到代码仓库，不要写在配置文件里上传到 GitHub、Gitee 这类公开地方。如果发现令牌可能泄露了，最快的处置方式就是去令牌管理页面删掉它、重新生成一个新令牌，再更新 PicGo 里的配置。

2.3 版本选择提示：软件版本与仓库结构的配合

仓库建好了，令牌拿到了，这端的准备工作就结束了。有一点提醒一下，Gitee 的仓库分支名，新仓库默认是master。PicGo 配置里填的branch字段要和仓库的实际分支名完全对应，否则上传时会报“分支不存在”之类的错误。

很多人在这一步卡住，其实不是配置写错了，而是仓库分支名和配置里的分支名对不上。比如仓库实际分支是master，配置文件里填了main，那上传必然失败。开工前先在仓库页面确认好分支名，再填到配置里，可以少走不少弯路。

3. PicGo 安装与 Gitee 图床插件配置

PicGo 是这条链路里承上启下的角色。先安装 PicGo 客户端，再装 Gitee 插件，然后把仓库信息和令牌填进去，上传通道就算通了。

3.1 PicGo 客户端安装与界面速览

PicGo 是开源的图片上传工具，提供了 Windows、macOS 等桌面版本。去它的官方网站或者项目发布页下载对应系统的安装包，安装过程没有特殊操作，一路默认即可。

装好后打开的界面很简洁，主要是左侧几个功能栏目：“上传区”（默认页）、“图床设置”、“相册”等。“图床设置”里列出了 PicGo 内置支持的各种图床，比如腾讯云、阿里云、七牛云等，往下拉还能看到一个“插件设置”入口，Gitee 图床就是通过插件方式接入的。

PicGo 刚装好时默认是空的，直接去“图床设置”里找 Gitee 是找不到的，因为 Gitee 的插件是社区贡献的、默认不在内置列表里。需要先到“插件设置”页面搜索并安装 Gitee 插件，安装完成后才在“图床设置”里看到 Gitee 的配置入口。这一步很多人漏了，以为默认就有，愣是找不到 Gitee 选项。

安装插件时有一个值得注意的细节：PicGo 的插件本质上依赖 Node.js 环境，如果电脑上没装 Node.js，插件安装可能失败。遇到安装报错，先去装一个 Node.js LTS 版本，再回来安装插件。这个坑我踩过，当时插件一直装不上，看了日志才发现是缺 Node.js 环境。

3.2 Gitee 图床插件配置项逐项拆解

装好插件后，进入图床设置里的 Gitee 配置页。界面会列出几个待填的字段，每个字段的含义和填法都不一样。

repo字段填的是仓库地址的完整路径，但不需要带https://gitee.com/的前缀，格式是“用户名/仓库名”。比如你的用户名是samzhang，仓库名是my-image-hosting，这里就填samzhang/my-image-hosting。严格按这个格式来，不要多加空格，不要多写斜杠。

branch字段填仓库的主分支名，新仓库一般是master。这里填错了会直接导致上传失败，前面已经提过了，再提醒一遍。

token字段填入前面生成的私人令牌。粘贴时注意不要把前后的空格带进去，有些系统复制时会在末尾多带一个换行符，肉眼看不见但程序读到了。

path字段是图片存储的目录路径。比如填img/，图片就会传到仓库下的img目录里；不填就默认传到仓库根目录。个人建议设置一个独立的目录，比如img/或者images/，将来仓库里除了图片还有其他文件时，分类清晰，也方便管理。

customUrl字段比较关键，决定最终生成的图片链接长什么样。这里如果不填，PicGo 默认生成的链接是https://gitee.com/用户名/仓库名/raw/分支名/图片路径，这种格式直接能访问，实测没问题。如果你有自定义域名，可以在这一栏填写自定义域名前缀，PicGo 会用自定义域名/图片路径的形式生成链接。

defaultUrl字段是默认的前缀模板，一般保持默认https://gitee.com不动，除非你知道自己在做什么才去修改。

配置完成后，务必点击图床设置里的“设为默认图床”按钮。这一步的作用是让 PicGo 之后的图片都走 Gitee 这个通道。如果不点，PicGo 可能还在用其他图床配置或者什么都不用，图片上传就会失败或走错地方。

3.3 上传验证与第一张图

配置填好后，直接到 PicGo 的“上传区”拖一张图片进去，看它能不能成功上传并返回链接。这一步先验证 PicGo 本身工作是否正常，后面再接入 Typora 时，出问题了才知道问题出在哪一环。

上传成功的话，“相册”区域会显示刚上传的图片，旁边的链接区出现图片地址。可以把这个链接复制到浏览器里打开，能正常显示图片说明 PicGo 到 Gitee 这一段的链路已经打通了。

如果上传失败，PicGo 界面会给出错误信息。最常见的是 TOKEN 错误或仓库权限不足，常见的就是 TOKEN 复制错了、权限没勾全，或者仓库地址填错了。照着 2.2 节的步骤重新确认一遍，基本能解决。

4. Typora 偏好设置：将图片上传无缝接入写作文档流程

PicGo 这端通了，接下来就是把 Typora 接进链路里。Typora 是一款 Markdown 编辑器，内置了“图片插入”和“外部程序调用”能力，这正好是接入 PicGo 的接口。

4.1 打开图片偏好设置

在 Typora 菜单栏找到“文件”，下拉菜单里选“偏好设置”，然后切到“图像”这个标签页。这里集中了 Typora 与图片相关的行为配置。

“插入图片时”这一项，决定 Typora 对粘贴或拖入图片采取什么动作。默认行为一般是复制图片到当前文档的相对路径目录里。我们这里要改成“上传图片”，让 Typora 直接把图片交给外部工具处理，而不是先存本地。

“上传图片服务”或叫“上传服务”，选择“自定义命令”或“PicGo(app)”。Typora 的版本不同，选项名称会有些差异。旧一点的版本有独立的“PicGo(app)”选项，直接用即可；新版本一般归到“自定义命令”里，在命令框里填 PicGo 的可执行文件路径。

关于 PicGo 的可执行文件路径，Windows 上默认装在C:\Users\你的用户名\AppData\Local\Programs\PicGo\PicGo.exe这样的路径下。macOS 上通常是/Applications/PicGo.app/Contents/MacOS/PicGo。填好路径后，Typora 调用这个程序进行图片上传。如果路径填错了，或者程序名对不上，Typora 会提示“上传失败”或“图片上传工具调用失败”。

4.2 配置验证与 Ollama 场景补丁

配置好后，点“验证图片上传选项”按钮。Typora 会拿一张测试图片走一遍完整的链路：调用 PicGo，上传到 Gitee，返回链接。验证成功的标志是弹窗提示上传成功，并显示图片链接；验证失败则会有具体的错误提示。

测试通过后，在 Typora 里写文章时，插入图片的方式就是平常的粘贴。Typora 会自动把图片上传到图床，并在文档里插入返回的 URL。你“看不到”上传过程，因为它是后台完成的，只有右下角或状态栏会有短暂的上传提示。这种全程无感的状态，写作节奏完全不受影响。

我个人在建图床之前，笔记里大量图片都是本地相对路径。接好图床后，一方面新插入的图都是在线链接，另一方面我还做了一个整体体检，把以前的笔记批量处理了一下：把图片文件统一上传到图床，把文档里的本地路径替换成在线 URL。虽然这个过程有点繁琐，但一次性处理后，笔记就变成真正的“纯文本搬家自由”了。

有人问：旧笔记里的图片怎么办？可以用一个思路：把旧笔记和图片目录关系梳理清楚，然后写脚本或手动把图片传到图床，再批量替换 Markdown 里的图片引用。这个比较适合一次性整理，整理完之后笔记就完全脱离本地图片依赖了。

4.3 优化图片存储路径

前面提到 PicGo 的path字段建议设成img/，那样所有图片都会传到仓库的img/目录里。这种单目录方案简单直观，不过如果你图片量特别大，可以考虑用年月维度分目录，比如img/2025/01/，这样仓库按时间归档，后续找图会更清晰。

需要注意的是，Typora 调用 PicGo 时，PicGo 拿到的文件名是 Typora 传过去的。如果 Typora 里的图片本来是“Pasted image 20250101120000.png”这种带空格的文件名，PicGo 生成的链接里文件名也带着空格。虽然 Markdown 语法对带空格链接的支持度还行，但空格还是可能造成一些解析不友好的情况。有一个小技巧：在 Typora 偏好设置里可以配置图片重命名规则，开启重命名后，粘进来的截图会自动变成无空格的命名，上传后链接里就不会出现空格了。

5. 常见问题排查与操作经验实录

这套链路跑下来，碰到问题最多的环节集中在：Token 配置、分支名不匹配、Typora 调用 PicGo 失败、上传成功但不显示这几个方向。整理成一个速查表放这里，遇到问题可以直接对着查。

其中上传成功但浏览器打不开图片这一条，我见过很多次。根本原因大多是customUrl配得不严谨，或者branch分支名大小写写错了。Gitee 的 URL 对大小写敏感，Master和master是两个不同的路径。打开 Gitee 仓库页面，把地址栏里的分支名原样复制到配置里，能避免不少这种问题。

Typora 调用 PicGo 失败的另一个冷门原因是防火墙拦截。Windows 系统的防火墙有时会拦截 PicGo 的网络访问，明面上 Typora 显示上传失败，实际是 PicGo 根本没把图片发出去。遇到这种情况，把 PicGo 加入防火墙的白名单，或者临时关掉防火墙试一次，就知道是不是这个原因了。

换电脑时格外的注意事项：PicGo 的配置和令牌都保存在本机，换电脑后需要重新装一遍 PicGo、配上 Token，Typora 也得重新指一次命令路径。不是说你 Gitee 仓库建好了就万事大吉，三方工具的配置都要重新来一遍。不过好在按前面的步骤操作，十分钟不到就能完成一套配置。

另外要说的一个体会是：不要把主仓库当图床。图床图片是高频更新、大量文件堆积的仓库，它和你的代码仓库混在一起，会让仓库体积越来越大，拉取代码时也会变慢。我现在是单独建了一个图床仓库，让它专门接收图片，代码仓库保持干净。这个习惯坚持下来后，不管图床仓库怎么折腾都不影响代码工作，心理负担也小很多。

6. 从本地图片到在线图床的迁移经验

如果你的笔记体系里已经积累了相当数量的本地图片，直接把图片转到图床并替换引用，是一次性整理的好机会。整理的做法不复杂，但涉及大量文件的场景里，有一些细节值得提前想清楚。

先梳理图片分布。旧笔记的图片路径一般有两类：一类是相对于 Markdown 文档的相对路径，比如./images/xxx.png；另一类是项目的固定静态资源目录，比如docs/images/xxx.png。前者需要逐个文档处理，后者可以把整个目录打包传到仓库里，再根据目录结构生成链接，最后批量替换 Markdown 文件中的引用。

上传大目录时，PicGo 支持批量拖拽，也可以把整目录先打包传到仓库，这个方案对一次处理几百张图片更快。上传完成后，整理出一张“原文件名 -> 新链接”的对照表，然后写一个简单的查找替换脚本，把 Markdown 里所有旧路径替换成新链接。

替换后务必抽查验证。Markdown 渲染器对图片 URL 的处理宽容度不高，个别链接末尾多一个空格、少一个斜杠，都会导致整张图出不来。建议用脚本统一检查所有 Markdown 文件，匹配 Markdown 图片语法，逐个请求链接，看返回状态码是不是 200。这一步能把遗漏的坏链全部找出来，一步到位。

7. 写在最后的操作心得

这套 Typora + PicGo + Gitee 的方案，我已经用了相当长一段时间，期间只有一次 Gitee 仓库临时故障导致图片短暂无法访问，整体稳定性还是对得起它的免费属性的。作为个人笔记、技术文档、博客配图的图床方案，它完全够用。唯一要留意的，还是那句话：别把令牌放到公开地方，别把私密图片传到公开仓库。这套系统适合的是技术文章配图、学习笔记插图、生活记录照片这一类的常规内容，需要真正私密管理的文件本来就该走本地加密或其他私有存储方案，而不是往任何图床里塞。

整个过程配置下来，真正的成本主要在那一次性的十来分钟设置。以后每次写文章、记笔记，插入图片就像粘贴图片一样轻松，图片自动上传、链接自动生成，Markdown 文档随时可以搬走、发布、分享，再也不会出现换个地方看文章全是裂图的尴尬事。如果说有什么建议给刚开始用 Typora 的朋友，我想说：图床这步不要拖，写笔记从第一天就用在线图床，省下的都是后面对着一堆失效链接叹气的时间。