Halo CMS静态资源CDN全局接入配置
Halo CMS 的静态资源默认由服务器直接提供，当访客分布较广或流量上升时，加载速度会明显变慢。
本文针对 600. Halo CMS静态资源CDN全局接入配置 这一需求，从零开始讲解如何将主题静态文件、上传附件等资源全局替换为 CDN 地址，适合刚接触 Halo 的站长或运维人员。
跟着步骤操作后，你能让全站静态资源走 CDN 加速，并学会验证配置是否生效。
准备阶段：确认环境和获取 CDN 信息
开始前需要确认两件事：Halo 的版本和 CDN 服务商提供的加速域名。
Halo 1.x 和 2.x 的配置文件路径不同，本文以 Halo 2.x 为例，1.x 用户可参考对应版本的 application.yaml 调整。
- 一台已安装 Halo 的服务器，能通过 SSH 登录。
- 一个已备案并配置好 CNAME 的 CDN 加速域名，例如
cdn.example.com。 - CDN 回源地址指向你的 Halo 站点域名，回源协议建议与站点一致（HTTP 或 HTTPS）。
- 记录 CDN 服务商提供的 回源 Host 和 端口，后续配置会用到。
登录服务器，找到 Halo 的工作目录。
如果使用 Docker 部署，配置文件通常在宿主机的 ~/.halo2 或 /root/.halo2；
如果是 jar 包部署，一般在 ~/.halo2 下。
用以下命令确认：
ls -la ~/.halo2看到 application.yaml 文件即表示路径正确。
修改配置文件实现全局替换
Halo 2.x 支持通过 application.yaml 中的 halo.external-url 和 halo.attachment 等配置影响资源地址，但全局 CDN 替换需要借助反向代理或主题模板变量。
推荐在 Nginx 反向代理层 做静态资源重定向，这样无需改动 Halo 源码，升级也不受影响。
在 Nginx 站点配置中加入以下规则，将 /upload/ 和 /assets/ 路径的请求 302 跳转到 CDN：
location ~* ^/(upload|assets)/ {
rewrite ^/(.*)$ https://cdn.example.com/$1 redirect;
}如果希望 HTML 中的资源链接直接输出 CDN 域名，可以修改 Halo 主题模板。
进入 Halo 后台，点击 外观 -> 主题 -> 编辑，找到 theme.yaml 或模板文件，将 static 资源引用的 {{ theme.assets }} 替换为 CDN 地址。
例如：
修改后保存，并重启 Halo 服务使配置生效：
docker restart halo或 jar 包部署时执行 systemctl restart halo。
避坑指南：常见错误与处理
配置过程中容易遇到几个问题，提前了解可以少走弯路。
- CDN 回源 404：检查 CDN 回源地址是否指向 Halo 站点根目录，回源 Host 是否与站点域名一致。如果 Halo 使用了非标准端口，回源端口要同步修改。
- HTTPS 混合内容警告：如果站点是 HTTPS，CDN 也必须启用 HTTPS，否则浏览器会拦截资源。在 CDN 控制台申请证书并开启强制跳转。
- 缓存不更新：修改主题后 CDN 可能仍返回旧文件，需要在 CDN 控制台手动刷新
/themes/和/upload/目录的缓存。 - 后台无法登录：如果误将
/api/或/admin/也跳转到 CDN，会导致登录失败。确保重定向规则只匹配静态资源路径。
验证 CDN 是否生效
配置完成后，通过以下方法确认静态资源已走 CDN：
- 浏览器打开网站，按 F12 进入 网络 面板，刷新页面。
- 查看 CSS、JS、图片等资源的 域名 列，如果显示
cdn.example.com而非你的主域名，说明替换成功。 - 使用
curl命令检查响应头：
curl -I https://cdn.example.com/themes/your-theme/style.css返回 200 OK 且带有 X-Cache 或 Via 头（不同 CDN 名称不同），表示 CDN 已缓存。
如果返回 301 或 302，检查重定向规则是否循环。
另一个验证点是 回源流量。
在 CDN 控制台查看回源带宽，如果明显低于总请求带宽，说明大部分请求已被 CDN 边缘节点响应。
常见疑问
Halo 1.x 和 2.x 的配置方式一样吗？
不一样。Halo 1.x 使用 application.yaml 中的 halo.external-url 控制资源地址，而 2.x 更依赖反向代理和主题模板。建议先确认版本，再参考对应文档。
CDN 加速域名需要备案吗？
如果服务器在中国大陆，CDN 域名通常需要备案。具体以服务商要求为准，可查看其官方文档。
配置后网站打不开怎么办？
先检查 Nginx 配置语法：nginx -t。如果报错，根据提示修改。若无法定位，暂时注释掉 CDN 重定向规则，恢复原状后再逐步排查。
静态资源走 CDN 后，后台附件上传会受影响吗？
不会。上传接口仍指向源站，只有读取附件的 URL 被替换为 CDN。如果上传后无法预览，检查 CDN 是否已刷新缓存。
完成以上步骤后，你的 Halo 站点静态资源已经通过 CDN 全局加速。
建议定期观察 CDN 命中率和网站加载速度，根据实际效果调整缓存过期时间。
如果遇到异常，优先回看避坑部分，逐项排查。
