图片优化

🎯 系统概述

这个图片尺寸优化系统为你的 Hugo 网站提供了完整的图片性能优化解决方案，包括：

🚀 自动尺寸检测: 批量为 Markdown 中的图片添加 width 和 height 属性
📱 响应式显示: 自动适配不同屏幕尺寸
⚡ 性能优化: 减少布局偏移 (CLS)，提升用户体验
🔧 开发工具: 提供便捷的脚本和代码片段

📁 文件结构

├── scripts/
│   ├── add-image-dimensions.js     # 批量添加图片尺寸脚本
│   ├── check-image-dimensions.js   # 检查图片尺寸状态脚本
│   └── monitor-progress.js         # 监控脚本进度
├── .vscode/
│   ├── markdown-image.code-snippets    # Markdown图片代码片段
│   └── hugo-snippets.code-snippets     # Hugo相关代码片段
├── assets/
│   ├── js/image-optimization.js    # 前端图片优化脚本
│   └── scss/components/_image-optimization.scss  # 图片样式
└── layouts/_default/_markup/
    └── render-image.html           # Hugo图片渲染模板

🚀 快速开始

1. 初始化系统

运行以下命令为所有现有图片添加尺寸信息：

npm run add-image-dimensions

2. 检查状态

查看当前图片尺寸覆盖率：

npm run check-image-dimensions

3. 监控进度

实时监控批量处理进度：

node scripts/monitor-progress.js

✍️ 在 Markdown 中使用

基础语法

![图片描述](image.webp)
{width=800 height=600}

高级属性

![图片描述](image.webp)
{width=800 height=600 class="img-responsive" loading=lazy}

支持的属性

width: 图片宽度
height: 图片高度
class: CSS 类名
style: 内联样式
loading: 加载方式 (lazy/eager)

🔧 VSCode 代码片段

在 VSCode 中输入以下前缀可快速插入图片：

img: 基础图片（带尺寸）
imglocal: 本地图片
imgsvg: SVG 图片
imgres: 响应式图片
figure: Hugo figure 短码
archimg: 架构图
flowimg: 流程图

📊 脚本详解

add-image-dimensions.js

功能: 批量为 Markdown 文件中的图片添加尺寸属性

特性:

支持本地和远程图片
自动检测 SVG 尺寸
智能跳过已有尺寸的图片
支持多种图片格式

工作流程:

扫描所有 Markdown 文件
解析图片链接
获取图片尺寸
添加 width/height 属性
保存更新后的文件

check-image-dimensions.js

功能: 检查和统计图片尺寸覆盖情况

输出信息:

总图片数量
已有尺寸的图片数量
覆盖率百分比
详细的文件列表

🎨 样式系统

响应式图片

系统自动为所有图片应用响应式样式：

img {
  max-width: 100%;
  height: auto;
  display: block;
  margin: 1.5em auto;
}

移动端优化

在移动设备上，所有图片自动适配屏幕宽度：

@media (max-width: 768px) {
  img[width][height] {
    width: 100% !important;
    height: auto !important;
  }
}

🔍 Hugo 模板功能

智能属性解析

Hugo 模板能够：

解析 Markdown 中的自定义属性
应用默认尺寸（针对本地图片）
生成优化的 HTML 结构
处理图片加载错误

图片格式支持

JPEG/PNG: 自动生成 WebP 版本（生产环境）
WebP: 直接使用
SVG: 保持矢量格式
GIF: 保持动画效果

🛠️ 故障排除

常见问题

脚本运行缓慢
网络图片需要下载检测
建议在网络良好时运行
某些图片无法获取尺寸
检查图片 URL 是否可访问
验证图片格式是否支持
VSCode 片段不生效
确保文件类型为 Markdown
重启 VSCode 编辑器

调试命令

# 查看详细日志
tail -f image-processing.log

# 检查特定文件
node scripts/check-image-dimensions.js | grep "filename"

# 手动测试单个图片
node -e "const sizeOf = require('image-size'); console.log(sizeOf('path/to/image'))"

📈 性能优化效果

使用此系统后，你的网站将获得：

减少 CLS: 提前定义图片尺寸，避免布局跳动
更快加载: 懒加载和预加载优化
更好 SEO: 图片属性完整，提升搜索引擎评分
用户体验: 响应式图片，适配所有设备

🔄 维护建议

定期检查

建议每月运行一次检查脚本：

npm run check-image-dimensions

新图片处理

添加新博客文章后：

npm run add-image-dimensions

配置更新

系统配置位于：

config/_default/config.toml - Hugo 配置
package.json - NPM 脚本
assets/scss/ - 样式文件

🤝 贡献指南

如需改进此系统：

修改脚本逻辑：编辑 scripts/ 目录下的文件
更新样式：修改 assets/scss/components/_image-optimization.scss
改进模板：编辑 layouts/_default/_markup/render-image.html
添加功能：更新 assets/js/image-optimization.js

💡 提示: 此系统设计为零配置使用，但提供了丰富的自定义选项来满足不同需求。