性能最佳实践#

主题的性能问题通常集中在静态资源加载方式、模板中 Finder 的调用次数和图片尺寸上。本页给出各环节的推荐做法。

#静态资源加载

• 使用构建工具（如 Vite）将样式和脚本打包压缩后再分发，不要直接引入源码文件，详见使用 Vite 开发主题。
• 非首屏必需的脚本添加 defer，避免阻塞页面渲染：

<script defer th:src="@{/assets/dist/main.iife.js?v={version}(version=${theme.spec.version})}"></script>

• 在静态资源地址中加入主题版本号参数（如上例），配合 Halo 默认对静态资源输出的长效缓存（Cache-Control: max-age=31536000），主题升级后浏览器会获取到新资源。
• 生产环境保持模板缓存开启；只在开发阶段按准备工作关闭 Thymeleaf 缓存，发布前用接近生产的缓存配置做冒烟测试。

#控制 Finder 调用

模板中每次 Finder 调用都会产生一次数据查询，应控制调用次数和返回的数据量：

• 为 list({...}) 等分页方法设置合理的 size，不要在首页用很大的 size 拉取全量文章。
• 不要在 th:each 循环体内调用 Finder（例如为列表中的每篇文章单独查询作者或评论数），优先使用返回结果中已包含的字段；ListedPostVo 已包含分类、标签和作者信息。
• 同一变量在模板中多次使用时，用 th:with 保存查询结果，避免重复调用。

#图片优化

列表和封面图使用 Halo 生成的缩略图而不是原图，详见图片优化。

#验证

发布前用浏览器开发者工具的 Network 面板检查：首屏请求数量、资源是否被压缩和缓存、图片是否使用了合适的尺寸。有条件的可以使用 Lighthouse 检查性能指标。