做开发这几年，我一直保持着写技术博客、整理内部文档的习惯。文字部分其实很少出问题，真正让我反复返工的，几乎都是图片：要么自己换台电脑打开发现图全没了，要么读者留言说“图裂了”，要么把同一篇文章搬到另一个平台，排版还在、图片只剩一排占位符。

早期我总觉得配图是“顺手的事”，截个图拖进去就行。被坑过几次之后才认真对待，慢慢攒了一套固定习惯。这篇不聊某个具体产品，就把配图这件事的坑和我的做法按顺序记下来，希望能帮到同样在反复返工的同学。

## 一、我遇到过的几类图片“翻车”

把这些年遇到的情况归一下类，大概是四种：

- **图直接裂掉**：本该是示意图的地方只剩一个破损图标。这种多半是图片地址本身失效了，或者图源做了防盗链、不允许在外站引用。
- **图能打开但很慢**：文字早就出来了，图片一直在转圈，最后要么勉强加载、要么超时。常见于图源和读者离得太远、又没有就近加速。
- **换设备、换平台就丢图**：在自己电脑上一切正常，把文档发给别人或同步到另一台机器，图全没了。原因是图片当时引用的是本地路径，文件没跟着文档一起走。
- **文档迁移后图陆续失效**：刚导出、刚搬运时还能看，过一段时间图一张张挂掉。这通常是因为用了带时效的临时链接，签名一过期图就打不开。

这四种现象看着不同，根子其实是两个：**图片是独立于文字的另一个请求**，以及**我没有把“图源”当成一个需要单独管理的东西**。

## 二、先搞懂图片为什么会出问题

要少返工，得先弄明白一张图在文档里是怎么被加载的，这里给和我当初一样一知半解的同学捋几点。

**图片是一次独立的网络请求。** 文字和排版是跟着文档本身一起到的，而每张图都要浏览器拿着图片地址再去请求一次。这个地址指向的服务器稳不稳定、能不能被读者访问到，直接决定了图能不能显示。也就是说，文档能打开，不代表里面的图能打开。

**很多站点会做防盗链。** 当浏览器去请求一张图时，通常会带上“我是从哪个页面来的”这个信息。一些图源会检查它：如果发现请求是从外站发起的，就拒绝返回图片。你把同一张图的链接从一个平台搬到另一个平台，有时就会因此变成裂图——不是地址写错了，是对方不愿意被这样引用。

**临时签名链接会过期。** 从一些笔记软件、云盘里复制出来的图片地址，后面常常拖着一长串签名参数，它只在一段时间内有效。刚搬运时一切正常，等签名过期，图就陆续挂了。这类链接适合临时访问，不适合作为长期文档的图源。

**还有一些更隐蔽的小问题。** 比如页面整体是加密连接，却引用了未加密的图片，浏览器可能直接拦掉；又比如把好几 MB 的原始截图直接塞进文档，读者打开会非常吃力。这些都属于“当时没感觉、事后添麻烦”的类型。

我之前也专门排查过防盗链和外链配图的机制，结论和上面是一致的：**问题大多不在文档本身，而在图片地址指向的那个图源上。**

## 三、我固定下来的几条配图习惯

搞清楚原因后，我把配图流程固定了下来，核心思路就一句话：**把图片和正文解耦，图源单独管理。** 具体是这么做的。

**第一，给文档指定一个稳定的“图源”，而不是每张图各放各的。** 所有要长期保留的展示图，都统一放到这一个图源里，文档里只引用它给出的地址。这样图源稳不稳定、要不要做加速，我只需要维护一处，不用在几十篇文章里分别操心。

**第二，把图分成两类区别对待。** 一类是要跟着内容版本走的（比如教程里的输入输出样本），数量少、体积小，可以随文档一起存放；另一类是纯展示用的（logo、演示截图、架构图、效果对比），这类统一放进图源，不堆在文档工程里，也避免把仓库或同步盘越塞越大。

**第三，大图先压缩，关键信息不只用图表达。** 截图在放进文档前先压一遍，别把原始大图直接塞进去。同时坚持给每张图写说明文字，重要结论不要只放在图里——万一图真没加载出来，读者至少知道那里本该是什么。

**第四，命名和目录有个简单规范。** 用能看懂的文件名，按主题分目录，避免一堆“截图1、截图2”或者同名文件互相覆盖。这一条看似不起眼，等你要回头找一张半年前的图时就知道有用了。

**第五，改图尽量“原地更新”。** 演示图难免要反复改，如果改一次就换一个新地址，就得回头去文档里把旧地址逐个替换，很容易漏。我会优先选择能“同名覆盖、地址不变”的方式放图，图更新了、文档里的链接不用动，省掉很多重复劳动。

## 四、图源具体怎么选

这是被问得最多的一点。说实话没有标准答案，常见的路子有这么几种，差别主要在“要花多少精力”：

- **自己用对象存储再套一层内容分发网络**：最可控，图源、加速、缓存、防盗链都能自己定，但要自己去开通、配置和维护；
- **放在代码仓库或静态资源库里**：适合和代码强相关的图，但展示图堆多了会让工程变臃肿，更新还可能受缓存影响；
- **用现成的图片托管服务**：上传后直接拿地址，压缩、加速、同名覆盖这些通常都已经处理好，省心，但要挑一个能长期稳定使用的。

我自己属于“不想为配图专门维护一套基础设施”的那种，更倾向于第三种：挑一个能长期稳定使用、又支持同名覆盖的现成服务，截图改好重新传一遍、地址不变，文档不用跟着改。但这纯粹是个人图省事的办法，并不是什么最优解——对基础设施有要求、或者愿意自己折腾的话，自建对象存储再加一层内容分发网络会更可控。大家按项目规模和自己愿意投入的精力来选就好，没必要照搬任何一种。

## 五、发布前我会过一遍的图片自检清单

最后是我每次发布或迁移文档前，会顺手过一遍的小清单：

- 换个网络环境，或者请不同地区的朋友实际打开看一眼，确认图都能显示；
- 图片引用和页面保持一致的加密方式，不混入会被拦掉的地址；
- 大图都压缩过，没有把好几 MB 的原始截图直接塞进去；
- 每张图都写了说明文字，关键信息不依赖图片才能看懂；
- 原本指向本地、或带临时签名的展示图，都换成了稳定图源的地址；
- 如果文档在代码仓库里，顺手确认一下工程体积还能接受。

配图这件事给我的最大体会是：它本质上是个“一次配置、长期省心”的活。早期我每次都临时处理，结果反复返工；后来把图源单独管理、把流程固定下来，这类“图裂了、图丢了”的问题就很少再出现，省下的时间其实远多于当初花在梳理上的功夫。希望这份习惯清单对你也有用。

做开发这几年，我一直保持着写技术博客、整理内部文档的习惯。文字部分其实很少出问题，真正让我反复返工的，几乎都是图片：要么自己换台电脑打开发现图全没了，要么读者留言说“图裂了”，要么把同一篇文章搬到另一个平台，排版还在、图片只剩一排占位符。

写了几年技术博客，关于配图我踩过的坑和固定下来的几条习惯

结合自己写技术博客和整理文档的经历，梳理配图常见的裂图、加载慢、换设备丢图、迁移后失效四类问题，解释图片独立请求、防盗链、临时签名过期、混合内容等机制，并给出图源管理的几条固定习惯和发布前自检清单。

职业发展

开发工具

后端

配图翻车是技术写作常见痛点，本文系统梳理图裂、加载慢、跨平台丢图等四大类问题根源，并给出图源独立管理、图片分类、压缩优化、命名规范、原地更新五大实操习惯，附发布前自检清单，帮助开发者彻底告别图片返工。

CDN免费试用


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

写了几年技术博客，关于配图我踩过的坑和固定下来的几条习惯-腾讯云开发者社区-腾讯云

写了几年技术博客，关于配图我踩过的坑和固定下来的几条习惯

写了几年技术博客，关于配图我踩过的坑和固定下来的几条习惯

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐