图片素材工作流使用指南
约 542 字大约 2 分钟
2026-08-30
图片统一放在 docs/.vuepress/public/assets/，文章中始终使用 /assets/... 引用，不使用 Markdown 同目录相对路径。
目录与命名
| 用途 | 目录 |
|---|---|
| 单篇博客素材 | blog/YYYY/article-slug/ |
| 项目长期素材 | projects/project-slug/ |
| 网站页面与 UI | site/ |
| Logo、头像、公共图标 | common/ |
| 暂时无法归类的文件 | misc/ |
文件建议使用英文 kebab-case 语义化命名，例如 ssh-login.webp、backup-flow.svg。文章封面推荐命名为 cover.webp。
普通截图、照片、UI 和封面优先使用 WebP；流程图、Logo 等矢量素材保留 SVG。
日常流程
创建目录：
pnpm assets:add按提示选择分类。Blog 会要求填写年份（默认当前年）和文章 slug，例如得到：
/assets/blog/2026/mc-server-rsync/提示
这一步可以在创建实际文章后再进行，这样可以直接使用创建文章时得到的链接填入~
将图片放入对应目录，并使用语义化文件名。
在文章或组件中引用：
运行优化任务。交互式终端会先显示预览；输入
y即可在同一终端直接转换图片并更新引用：pnpm images:optimize在无交互的终端中，命令仅执行 dry-run；确认后可显式写入：
pnpm images:optimize -- --apply指定单张图片或目录时，将路径附在命令后，例如：
pnpm images:optimize -- --apply docs/.vuepress/public/assets/blog/2026/mc-server-rsync检查资源健康状态：
pnpm assets:check默认只有 Missing 会阻止命令；需要将 Warning 也视为失败时使用：
pnpm assets:check:strict构建站点：
pnpm docs:build此命令会自动先执行默认的
assets:check。
注意事项
- 不要直接在
assets/根目录放图片。 blog/中必须使用YYYY/article-slug/两级目录。misc/仅作临时兜底；其中有文件时检查会给出 Warning，应尽快归类。- 优化脚本默认只转换 JPG/JPEG/PNG 为 WebP，且节省不足 5% 时跳过；不会在找不到引用时删除原文件。
更新日志
2026/8/30 16:28
查看所有更新日志
07246-📝 docs(repo): 博客&文档更新于