> For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt.

# 性能最佳实践

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

## 静态资源加载

- 使用构建工具（如 Vite）将样式和脚本打包压缩后再分发，不要直接引入源码文件，详见[使用 Vite 开发主题](https://docs.halo.run/developer-guide/theme/vite.md)。
- 非首屏必需的脚本添加 `defer`，避免阻塞页面渲染：

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

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

## 控制 Finder 调用

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

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

## 图片优化

列表和封面图使用 Halo 生成的缩略图而不是原图，详见[图片优化](https://docs.halo.run/developer-guide/theme/image-optimization.md)。

## 验证

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