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

# 自定义样式与代码注入

> 适用版本 ≥ 2.0.0 ｜ 后台路径：设置 → 代码注入

主题没有开放在线编辑 CSS 的设置，需要微调样式时走 Halo 的「代码注入」。这一篇给出可安全覆盖的变量、注入位置与升级注意事项。

## 注入位置

| 位置        | 用途           | 写法                                       |
| --------- | ------------ | ---------------------------------------- |
| 代码注入 → 页头 | 引入样式、字体、统计脚本 | `<style>…</style>` 或 `<link>`、`<script>` |
| 代码注入 → 页脚 | 统计脚本、页脚内容    | 会输出在主题的 `<halo:footer />` 扩展点            |

> 页脚扩展点是页脚类插件与自定义脚本的统一出口，主题已补齐，升级不会移除。

## 可覆盖的 CSS 变量

主题的配色与主要尺寸都由变量驱动，覆盖变量比改选择器更稳定。

```css
:root {
  /* 主色与背景 */
  --primary: oklch(0.7 0.14 210);   /* 主色，数字为色相 */
  --page-bg: oklch(0.95 0.01 210);  /* 页面底色 */
  --card-bg: #fff;                  /* 卡片底色 */

  /* 圆角与动效 */
  --radius-large: 1rem;
  --card-hover-duration: 300ms;
  --toc-transition-duration: 150ms;
  --content-delay: 150ms;

  /* 布局尺寸 */
  --navbar-height: 4.5rem;
  --page-width: 84.5rem;
  --banner-height: 35vh;
  --banner-height-home: 65vh;
}
```

常用变量说明：

| 变量                                         | 作用                 |
| ------------------------------------------ | ------------------ |
| `--primary`                                | 主色，按钮、链接、强调元素      |
| `--page-bg` / `--card-bg`                  | 页面底色 / 卡片底色        |
| `--radius-large`                           | 卡片圆角               |
| `--card-hover-duration`                    | 卡片悬浮过渡时长           |
| `--toc-transition-duration`                | 目录高亮过渡时长           |
| `--navbar-height`                          | 导航栏高度，影响吸顶偏移       |
| `--page-width`                             | 两栏布局总宽（三栏另有固定值）    |
| `--banner-height` / `--banner-height-home` | 非首页 / 首页 Banner 高度 |

## 推荐配法

**只换主色**：优先用后台的「主题颜色 → 色调」，不要用 CSS 覆盖 `--primary`。后台设置会同步到访客样式面板，CSS 覆盖会绕过这套机制。

**加宽内容区**：覆盖 `--page-width` 前先确认目标分辨率下的排版效果，三栏布局的总宽是独立值，改这个变量不会影响三栏。

**统一圆角**：只改 `--radius-large` 即可覆盖大多数卡片，按钮等小元素另有固定圆角。

**注入统计脚本**：放在页脚的代码注入里，避免阻塞首屏渲染。

## 注意事项

- **升级可能改 DOM 与类名**：主题迭代会调整结构，基于 `nth-child`、长选择器链的样式最容易失效；优先用 CSS 变量和稳定的语义类
- 不要用 `#id` 选择器覆盖布局，主题里部分 id 被脚本引用，改样式时用类或属性选择器
- 访客在前台改过的样式（色相、卡片样式等）以本地存储为准，会覆盖你的 CSS 默认值，排查时先清站点数据
- 代码注入的内容不会随主题升级被覆盖，但也不会被迁移；换主题后记得备份
- 引入外部脚本前确认来源可信，页头脚本会阻塞渲染，能放页脚就放页脚