跳到主要内容

图片存放规范与分类教程

当前图片放在哪里​

现有文章图片已经统一迁移到：

static/image_photo/articles/<文章名>/

例如：

static/image_photo/articles/GitHub入门/
static/image_photo/articles/电赛HAL库FFT/
static/image_photo/articles/课程嵌入式课程分享总结/
static/image_photo/articles/如何使用Typora+秀米+PicGo快速编写微信公众号/

全站特殊资源仍放在根目录：

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

图片引用规则​

Markdown 中统一使用站点绝对路径：

![](/image_photo/articles/文章名/图片.png)

例如：

![](/image_photo/articles/GitHub入门/image-20260420083956361.png)
![](/image_photo/articles/课程嵌入式课程分享总结/esp.png)

仓库中的实际文件是：

static/image_photo/articles/GitHub入门/image-20260420083956361.png
static/image_photo/articles/课程嵌入式课程分享总结/esp.png

不要继续使用下面这些路径：

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

旧文章已经通过脚本完成迁移，引用的路径不需要再手工修改。

让 Typora 显示图片​

1. Typora 复制图片到指定文件夹​

打开：

Typora → 文件 → 偏好设置 → 图像

在“当插入图片时”选择：

复制图片到指定文件夹

“指定文件夹”填写：

E:\Doc_Log\BlogBok\static\image_photo\articles\${filename}\

也可以使用正斜杠：

E:/Doc_Log/BlogBok/static/image_photo/articles/${filename}/

说明：

  • E:\Doc_Log\BlogBok 是当前项目根目录。
  • ${filename} 是 Typora 支持的变量，表示当前文章名。
  • 以后在新文章中粘贴图片，Typora 会自动复制到 static/image_photo/articles/<当前文章名>/。
  • 这里建议使用绝对路径，因为 Typora 的相对路径是相对于当前 Markdown 文件解析的；docs 下不同文章层级不同，../static 无法对所有文章通用。

2. 为什么还要配置 typora-root-url​

Typora 会把 /image_photo/... 当成磁盘根目录。为了让已有文章在 Typora 中正常预览，需要在 YAML Front Matter 中配置：

---
typora-root-url: ../../static/
---

不同层级对应不同路径：

文章位置typora-root-url
docs/文章.md../static/
docs/分类/文章.md../../static/
docs/分类/子分类/文章.md../../../static/

项目已经提供自动维护命令：

npm run fix:typora-images

该命令会检查所有包含 /image_photo/ 的文章，并自动补全或修正 typora-root-url。

已有图片的批量整理​

项目提供图片整理脚本：

npm run organize:images

默认是预览模式，只显示将要移动的图片和引用修改，不会更改文件。

确认无误后执行：

npm run organize:images:apply

脚本会：

  1. 扫描 docs/ 和 blog/ 中的图片引用；
  2. 将图片移动到 static/image_photo/articles/<文章名>/；
  3. 将 Markdown 图片地址统一改成 /image_photo/articles/<文章名>/文件名；
  4. 自动处理同名文件冲突；
  5. 多篇文章共用的图片会放入 static/image_photo/articles/_shared/；
  6. 自动执行 fix:typora-images，更新文章的 Typora 根路径。

新增文章的标准操作​

方式一：使用 Typora 自动复制​

配置好上面的“复制图片到指定文件夹”后：

  1. 在 docs/ 中创建新文章；
  2. 直接从剪贴板粘贴图片；
  3. Typora 自动将图片保存到 static/image_photo/articles/<文章名>/；
  4. 图片链接可能写成相对路径或本机绝对路径；
  5. 执行一次整理命令，统一为网站标准路径并更新 Typora 根路径：
npm run organize:images:apply

方式二：手动放置图片​

  1. 创建文章对应目录：
static/image_photo/articles/文章名/
  1. 将图片放入该目录：
static/image_photo/articles/文章名/step-1.png
static/image_photo/articles/文章名/step-2.png
  1. 文章中这样引用：
![](/image_photo/articles/文章名/step-1.png)
![](/image_photo/articles/文章名/step-2.png)

文件命名建议​

优先使用有语义的文件名：

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

同一篇文章的连续截图建议统一命名：

step-1.png
step-2.png
step-3.png

Typora 自动生成的文件名也可以保留，例如：

image-20260420083956361.png

但后期可读性较弱，重要图片建议改成更有语义的名字。

文件格式建议​

格式适用场景
png截图、界面图、流程图
jpg / jpeg照片、体积较大的实拍图
webp网页展示、需要高压缩率
gif动图演示

大图应先压缩再提交到仓库，避免仓库体积持续膨胀。

特殊说明：首页背景图​

首页背景图使用固定文件：

static/image_photo/background.jpg

页面引用：

![](/image_photo/background.jpg)

替换说明见：

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

最佳实践​

  1. 普通文章图片统一放在 static/image_photo/articles/<文章名>/。
  2. 全站固定资源才放在 static/image_photo/ 根目录。
  3. Markdown 中统一使用 /image_photo/articles/...。
  4. Typora 复制图片使用绝对路径加 ${filename}。
  5. 新图片尽量使用有语义的文件名。
  6. 大图先压缩再提交。
  7. 整理旧图片时优先使用 npm run organize:images 预览。
  8. 修改完成后重新构建网站，确认所有图片都能显示。

常见问题​

Q1：为什么 Typora 中图片不显示？​

确认文章 Front Matter 中存在：

typora-root-url: ../../static/

如果路径层级不对，执行：

npm run fix:typora-images

然后重新打开文章。

Q2：Typora 的“指定文件夹”为什么不建议填相对路径？​

Typora 的相对路径是相对于当前 Markdown 文件解析的。docs/ 下的文章可能位于不同深度，因此同一个 ../static 不能覆盖所有文章。使用项目绝对路径最稳定。

Q3：我在 Typora 中粘贴图片后，为什么没有进入当前文章目录？​

检查指定文件夹是否填写为：

E:\Doc_Log\BlogBok\static\image_photo\articles\${filename}\

并确认 ${filename} 变量没有拼写错误。

Q4：移动图片后网站图片失效怎么办？​

运行以下命令检查并更新 Typora 根路径：

npm run organize:images
npm run fix:typora-images

然后执行：

npm run build

根据构建输出检查是否还存在缺失文件。

一句话结论​

文章图片统一放在：

static/image_photo/articles/<文章名>/

Markdown 中统一引用：

![](/image_photo/articles/文章名/图片.png)

Typora 复制图片目录填写：

E:\Doc_Log\BlogBok\static\image_photo\articles\${filename}\