﻿---
title: "配置字典：GA4 访问统计、AI 阅读补充说明"
description: "以实际代码说明 GA4 和 AI 阅读补充字段的类型、默认值、校验、输出位置、语言覆盖与配置边界。"
url: "https://demo.anglefeint.com/zh/blog/config-analytics-ai/"
language: "zh"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-13T00:00:00.000Z"
---

# 配置字典：GA4 访问统计、AI 阅读补充说明

第一次发布可读[部署教程](https://demo.anglefeint.com/zh/blog/starter-guide-deployment/)，其中介绍统计 ID 获取和公开文本用途。配置文件位置见[安装与站点信息](https://demo.anglefeint.com/zh/blog/starter-guide-1-configure-your-site/)，其他模块从[配置字典总入口](https://demo.anglefeint.com/zh/blog/config-reference/)进入。

这两组配置写在 `src/site.config.ts` 顶层，与 site、theme 同级：analytics 是访问统计，aiReadableContent 是公开站点文字补充。它们互不依赖，开启统计不需要填写 AI 补充，生成公开文本也不需要统计 ID。

## analytics.googleAnalyticsId：GA4 标识

| 路径 | 类型 / 默认值 | 状态、作用与限制 | 示例值 |
| --- | --- | --- | --- |
| analytics | { googleAnalyticsId: string } / { googleAnalyticsId: ‘’ } | 配置容器，部分覆盖即可；没有额外 enabled 字段 | { googleAnalyticsId: ‘G-XXXXXXXXXX’ } |
| analytics.googleAnalyticsId | string / ‘’ | 条件生效：有效 ID、生产构建且未命中本地地址跳过规则时加载 GA4。空字符串或纯空白关闭；首尾空白会移除。正则为 ^G-\[A-Z0-9\]+$，前缀及后续字母必须大写；格式错误会在组件解析时抛错 | ‘G-XXXXXXXXXX’ |

这是 GA4 网页数据流的 Measurement ID，不是数字属性 ID、GTM 容器 ID、旧 UA ID 或 API 密钥。示例只演示格式，正式使用替换为自己的真实值。校验不要求固定字符数量，也不会联网验证 ID 是否属于有效数据流；不要把“通过正则”理解成“已收到统计”。

```ts
analytics: {
  googleAnalyticsId: 'G-XXXXXXXXXX',
},
```

关闭统计可合并：

```ts
analytics: { googleAnalyticsId: '' },
```

合并到现有 `defineThemeConfig({...})`，不要重复创建 analytics。一个 ID 用于接入公共框架的各语言页面，没有按语言或页面分别配置 ID 的字段。

### 哪些情况下会加载？

| 环境或地址 | 当前主题行为 |
| --- | --- |
| npm run dev | 不输出统计加载器；但字段仍先解析，错误格式不保证被忽略 |
| 生产构建，ID 为空 | 不输出统计加载器 |
| 生产构建，访问 localhost 或其 .localhost 子域 | 加载器提前返回，不初始化主题的统计队列，也不请求 Google |
| 生产构建，访问 127. 开头地址、0.0.0.0、::1 或 \[::1\] | 同样跳过；地址比较先转小写 |
| 生产构建，访问局域网 IP 或远程预览域名 | 不因它是“预览”自动排除；配置了 ID 就会尝试加载 |
| 生产构建，正式域名与有效格式 ID | 初始化一次 gtag 队列，异步插入 Google 客户端 |

主题执行 js 初始化和 config 命令，没有额外再手动发送一条 page\_view，也没有添加搜索词、播放器操作等自定义事件。重复执行同一加载器有一次性标记，但不会识别你通过其他工具另装的一套统计；已有手工脚本或 GTM 时，应确认没有重复安装。

已有 window.dataLayer 和 window.gtag 会被保留；主题没有附带同意管理面板、自动同意设置、代理上报、排除域名列表或自定义事件配置。当前 ID 不通过专用 PUBLIC\_GA\_\* 环境变量自动覆盖；环境控制需由你自己的 site.config 显式处理，不能随意填一个变量名期待主题读取。

公共组件对旧自定义适配器缺少 ANALYTICS 分支的情况按未配置处理，这是内部兼容兜底，不是另一个推荐填写的配置路径。实际仍只填写 analytics.googleAnalyticsId。

## aiReadableContent：全局公开补充

类型为可省略的 MachineReadableSupplement 对象，主题默认未设置。省略时仍生成机器阅读文件，只是不附加这组额外说明；填写 {} 也不是关闭导出的开关。

| 完整路径 | 类型 / 默认值 | 状态、作用与限制 | 示例值 |
| --- | --- | --- | --- |
| aiReadableContent.notes | string，可省略 / 未设置，输出为空 | 条件生效：向公开文本加入 Markdown 站点说明；空字符串或纯空白不输出该部分。不是文章正文替换，也不是给某个 AI 的私有提示 | ‘本站内容是个人学习笔记，可能持续修订。’ |
| aiReadableContent.links | { label: string; href: string }\[\]，可省略 / 未设置，输出空列表 | 条件生效：附加公开链接；数组整体替换，\[\] 清空；没有公开条数上限，不自动抓取链接目标内容 | \[{ label: ‘项目主页’, href: ‘[https://example.com/project/’](https://example.com/project/%E2%80%99) }\] |
| aiReadableContent.links\[\].label | string，必填 / 无 | 条件生效：显示名称必须 trim 后非空；生成时将换行折为空格，并转义反斜杠与方括号。不会从目标页面自动获取标题 | ‘项目主页’ |
| aiReadableContent.links\[\].href | string，必填 / 无 | 条件生效：必须非空，按发布根 URL 解析；解析后仅允许 HTTP(S)，且不能带用户名或密码。非法值会报错，不验证目标存在或可访问 | ‘[https://example.com/project/](https://example.com/project/)’ |

notes 和 links 没有通用字符长度配置；必须遵守对应类型。错误类型、空白链接名称、非网页协议或带凭据的链接可能阻止构建。主题不执行补充中的命令，也不调用模型生成这些说明。

### Markdown 和相对链接如何处理？

notes 保留 Markdown 文字、格式和代码示例；其中解析到的 Markdown 链接、图片与引用定义的目标会转成绝对地址，并接受相同的 HTTP(S) 与无凭据校验。代码块里的链接示例不作为真正目标改写。不要把它理解成任意 HTML 的完整校验器或网页截图服务。

链接解析基准是**站点公开根 URL，包含 Astro base**，不是当前文章 URL，也不是当前语言目录。例如发布根是 [https://example.com/project/：](https://example.com/project/%EF%BC%9A)

| 配置中的 href 或 Markdown 目标 | 解析结果 |
| --- | --- |
| zh/blog/ | [https://example.com/project/zh/blog/](https://example.com/project/zh/blog/) |
| /zh/blog/ | [https://example.com/zh/blog/](https://example.com/zh/blog/) |
| [https://docs.example.com/guide/](https://docs.example.com/guide/) | 保持该外部网址 |

所以子路径部署时，单个 / 开头会从域名根计算，不自动保留 /project/。这与音乐等组件对根路径添加 BASE\_URL 的处理不同，不能混用规则。mailto:、tel:、file:、javascript: 等不用于这组附加链接；正文中的正常联系链接有自己的导出规则，不代表补充链接也接受相同协议。

### 全局示例

```ts
aiReadableContent: {
  notes: '本站内容是个人学习笔记，可能持续修订。详情见[文章列表](zh/blog/)。',
  links: [
    { label: '项目主页', href: 'https://example.com/project/' },
  ],
},
```

## 按语言覆盖 aiReadableContent

完整前缀为 `i18n.locales.<语言>.aiReadableContent`，同样是可省略的 MachineReadableSupplement，默认未设置。下面字段作用与全局字段一致，差异是未设置时逐字段继承全局值：

| 相对字段 | 类型 / 默认值 | 作用与限制 | 示例值 |
| --- | --- | --- | --- |
| notes | string，可省略 / 继承全局 notes | 条件生效：该语言公开文本的补充；‘’ 或纯空白明确清空，不回退到另一语言 | ‘中文内容持续更新。’ |
| links | { label: string; href: string }\[\]，可省略 / 继承全局 links | 条件生效：覆盖整个附加链接数组，\[\] 明确清空，不与全局列表追加合并 | \[\] |
| links\[\].label | string，必填 / 无 | 有自定义条目时必填；校验与转义规则和全局相同 | ‘中文文章’ |
| links\[\].href | string，必填 / 无 | 有自定义条目时必填；解析基准仍是发布根，不是该语言目录 | ‘zh/blog/’ |

例如只换中文说明、隐藏中文附加链接：

```ts
i18n: {
  locales: {
    zh: {
      aiReadableContent: {
        notes: '中文内容持续更新。',
        links: [],
      },
    },
  },
},
```

只覆盖 notes 时仍继承全局 links；只写 {} 会继承两项。undefined 被忽略，不是清空指令。此对象不走 meta.fallback，不从英文或其他回退语言拷贝补充，详见[语言字典](https://demo.anglefeint.com/zh/blog/config-languages/#fallback)。

根 llms.txt 始终使用全局补充；语言覆盖用于该语言的索引、合集和单篇 Markdown。因此无效的全局补充不能靠在每种语言中清空来绕过，根索引仍会处理它。

## 补充进入哪些公开产物？

以下路径以网站发布根为基准；子路径部署时加上该发布前缀。只有实际导出了内容的语言才生成对应语言索引和合集，不因填写语言补充就凭空创建文章。

| 产物 | 补充位置与内容 |
| --- | --- |
| llms.txt | 根入口；全局 notes 放在语言目录之前，links 作为额外链接区。没有可导出内容时仍可包含全局补充 |
| `<语言>/llms.txt` | 语言入口；使用该语言覆盖后的说明与附加链接，按 Articles / Fragments / About 分类链接到已有公开文档 |
| `<语言>/llms-full.txt` | 该语言的公开全文合集；说明与附加链接在文档正文集合之前 |
| 文章对应的 index.md 等 Markdown | 原正文之后追加分隔线、站点补充标记和有效说明，不混成文章作者正文的一部分 |
| `<语言>/about/index.md` | About 的公开介绍和联系内容，以及当前可达的 AI 静态文本面板；末尾按相同规则追加补充，不导出整个工具运行配置 |
| `<语言>/fragments/index.md` | 分页碎片合并后的公开内容，保留稳定 ID 链接；末尾追加补充，不按每一分页生成重复全文合集 |

单篇 Markdown 的实际路径由构建 HTML 文件位置决定，index.html 对应 index.md；自定义 Astro 输出形式可能不同，不要手工拼造并覆盖生成文件。导出页面还会获得指向 Markdown 和对应语言索引的发现链接。

导出器只处理已标记、可公开索引且 canonical 同源的文章、About 和 Fragments；默认不把首页、列表、Decoder 工具表单或评论 iframe 导成文章。正文链接、代码、表格等从构建后内容转换，不会把未渲染的任意配置文件打包公开。About 的 AI 弹窗是已公开可打开的静态文字，填写前同样按公开资料对待。

search: false 只退出 Pagefind，不退出这些机器阅读产物。清空 notes/links 不关闭正文导出；没有 aiReadableContent.enabled、排除某篇、AI 服务地址、模型参数或 API key 字段。这些文件提供可读取的公开材料，不保证任何模型抓取、引用或提高排名。

生成器会保护不属于自身历史清单的同名文件，冲突时报错；不要在 public 或构建目录手工放一份相同路径的 llms.txt 或 Markdown 与之抢占。修正来源配置后重新构建，部署时完整上传生成产物；构建通过不代表线上已更新或某个模型已读取。

## 相关设置与当前配置边界

*   网站公开地址由 site.url、环境覆盖和 Astro 发布 base 共同影响；根索引标题与描述使用当前站点上下文。站点信息和部署方式见[发布教程](https://demo.anglefeint.com/zh/blog/starter-guide-deployment/)，不要在补充文字里修改网址就期待 canonical 一起变化。
*   语言启停影响标准页面生成；关闭不等于自动清除托管平台旧文件。补充文字不创建译文，相关配置见[语言字典](https://demo.anglefeint.com/zh/blog/config-languages/#ai-context)。
*   GA4 只影响统计加载，不控制搜索、RSS 或机器阅读；静态补充也没有自己的界面按钮、翻译文案或访问统计开关。
*   当前 GA4 ID 和所有补充字段都有消费位置，没有额外的过期字段需要填写。旧适配器缺少统计分支仅按未启用兼容，不是启用方式。

修改后需要重新构建部署。统计结果仍可能受浏览器拦截、网络或统计端设置影响；本地文本生成检查不能代替线上统计验收。返回[配置字典总入口](https://demo.anglefeint.com/zh/blog/config-reference/)查其他模块。
