跳到主要内容

图片存放规范与分类教程

当前图片都放在哪里​

当前站点文章里使用的图片，主要统一存放在：

static/image_photo/

这是现在仓库里的主图片目录。

例如当前已经存在这些分类目录：

  • static/image_photo/AMFMDSB/
  • static/image_photo/diansai/
  • static/image_photo/Hal/
  • static/image_photo/shangke/
  • static/image_photo/shengcun/
  • static/image_photo/tjc/
  • static/image_photo/typora/
  • static/image_photo/仪器/

另外还有一个特殊文件：

  • static/image_photo/background.jpg：首页背景图专用
  • static/image_photo/自定义背景说明.md：背景图维护说明

为什么图片放在这里​

Docusaurus 会把 static/ 目录下的文件作为站点静态资源直接发布。

所以：

  • 仓库里的实际存放路径是：static/image_photo/分类名/文件名
  • Markdown 里的访问路径写成：/image_photo/分类名/文件名

例如：

![](/image_photo/shangke/css.png)

它实际对应的仓库文件是：

static/image_photo/shangke/css.png

图片引用规则​

在 Markdown 文档中插入图片时，统一使用下面这种写法：

![](/image_photo/分类名/文件名.png)

例如：

![](/image_photo/diansai/image-20251118120923354.png)
![](/image_photo/Hal/配置.jpg)
![](/image_photo/shengcun/68da877dbb82a.jpg)

不建议这样写​

不要在当前 Docusaurus 文档里继续使用下面这种旧路径思路：

![](../../../public/image_photo/xxx.png)

原因：

  • 这是旧项目或参考项目里的写法
  • 当前项目实际统一走 static/image_photo/
  • 使用 /image_photo/... 更直观，也更方便维护

图片分类怎么建​

原则：按文章主题或内容类型建文件夹，不要把所有图片堆在同一个目录。

推荐分类方式​

1. 按专题分类​

适合一篇文章或一组同主题文章共用一批图片。

例如：

  • static/image_photo/diansai/：电赛相关
  • static/image_photo/Hal/：HAL 库相关
  • static/image_photo/AMFMDSB/：调制解调相关
  • static/image_photo/typora/：Typora 教程相关

2. 按系列文章分类​

如果后面某个专题会持续更新，建议单独建目录，不要混放。

例如将来新增：

  • static/image_photo/git/
  • static/image_photo/linux/
  • static/image_photo/vue/

3. 特殊用途单独固定文件​

某些全站级资源可以单独固定命名。

例如：

  • static/image_photo/background.jpg：首页背景图固定文件名

新增图片的标准操作步骤​

步骤 1：先判断图片属于哪个主题​

先看文章属于哪个分类，再决定放到哪个文件夹里。

例如：

  • 电赛文章 → 放到 static/image_photo/diansai/
  • HAL 相关文章 → 放到 static/image_photo/Hal/
  • 上课总结文章 → 放到 static/image_photo/shangke/

如果现有目录都不合适，就新建一个新的主题目录。

步骤 2：把图片放到对应目录​

例如你要给 Git 教程加图片，可以新建：

static/image_photo/git/

然后把图片放进去：

static/image_photo/git/git-log.png
static/image_photo/git/git-branch.png

步骤 3：在 Markdown 里按站点路径引用​

![](/image_photo/git/git-log.png)
![](/image_photo/git/git-branch.png)

步骤 4：启动站点后检查是否能显示​

如果图片不显示，优先检查这几项：

  1. 文件是否真的放在 static/image_photo/ 下
  2. Markdown 路径是否以 /image_photo/ 开头
  3. 文件名大小写是否一致
  4. 图片后缀是否写对（.png、.jpg、.jpeg、.webp、.gif）

命名规范建议​

推荐做法​

1. 优先使用有语义的文件名​

例如：

  • adc-waveform.png
  • git-branch-merge.png
  • stm32-clock-config.jpg

这样后续维护时，一眼就知道图片内容。

2. 同一篇文章的连续截图可以统一命名​

例如：

  • git-step-1.png
  • git-step-2.png
  • git-step-3.png

3. 保留历史截图文件名也可以​

像下面这种自动导出的文件名，当前仓库里已经大量存在：

  • image-20251118120923354.png
  • 68ee41ce75fa9.png

这种不是不能用，但后期可读性较差。新内容如果有时间，建议尽量改成有语义的名字。

文件格式建议​

常用图片格式建议如下：

  • png：截图、界面图、流程图
  • jpg / jpeg：照片类、体积优先的图片
  • webp：压缩率更高，适合网页展示
  • gif：动图演示

建议​

  • 截图类优先 png
  • 照片类优先 jpg 或 webp
  • 超大图片尽量压缩后再放入仓库，避免仓库体积膨胀

什么时候需要新建分类目录​

满足下面任一情况，就建议新建目录：

  1. 新文章主题和现有目录明显不属于同一类
  2. 某个主题后续会持续更新
  3. 一组图片只服务于某个独立系列文章
  4. 混放后会导致目录难找、难维护

示例​

如果你要新增一篇关于 Git 的教程，不建议把图片放到：

  • static/image_photo/shangke/
  • static/image_photo/typora/

而应该新建：

static/image_photo/git/

当前项目的实际分类参考​

当前图片目录已经基本按主题分类，可以继续沿用这个思路：

分类目录用途说明
static/image_photo/AMFMDSB/AM / FM / DSB 等通信相关内容
static/image_photo/diansai/电赛相关图片
static/image_photo/Hal/STM32 HAL 库相关图片
static/image_photo/shangke/上课总结、课程类图片
static/image_photo/shengcun/学校生存指南相关图片
static/image_photo/tjc/陶晶驰相关内容
static/image_photo/typora/Typora / 图文教程相关图片
static/image_photo/仪器/仪器设备相关图片

特殊说明：首页背景图​

首页背景图不是随便命名的普通文章配图，它使用固定文件：

static/image_photo/background.jpg

页面中引用的是：

/image_photo/background.jpg

如果要替换首页背景图，请直接参考：

  • static/image_photo/自定义背景说明.md

最佳实践​

  1. 统一放在 static/image_photo/ 下
  2. 按主题建目录，不要混放
  3. Markdown 中统一使用 /image_photo/... 引用
  4. 新图片尽量使用有语义的英文或中文文件名
  5. 同一篇文章的图片尽量放在同一个目录
  6. 大图先压缩，再提交到仓库
  7. 不要随意修改已有图片路径，否则旧文章会直接失效

常见问题​

Q1：我能不能把图片放到 docs/ 目录里？​

可以，但不建议作为当前项目的主方案。

当前项目已经形成统一习惯：文章配图放 static/image_photo/。继续保持这个约定，后续最省事。

Q2：为什么我图片明明上传了，但页面不显示？​

优先检查：

  • 路径是不是写成了 /image_photo/...
  • 文件是不是放在了 static/image_photo/...
  • 文件名大小写是否一致
  • 后缀名是否一致

Q3：原来图片已经放错目录了，要不要移动？​

如果文章已经在引用，直接移动会导致旧文路径失效。

更稳妥的做法是：

  • 新文章按新规范放
  • 旧文章如果要整理，连同 Markdown 引用一起改

相关文件​

  • static/image_photo/ - 当前图片主目录
  • static/image_photo/自定义背景说明.md - 首页背景图说明
  • docs/Z_维护/ - 维护类文档目录

一句话结论​

当前项目的图片，默认就放在：

static/image_photo/

写文章时，统一按下面格式引用：

![](/image_photo/分类名/文件名)