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

$ 发布 2026-11-13 | | 更新 2026-11-13
语境: 以实际代码说明 GA4 和 AI 阅读补充字段的类型、默认值、校验、输出位置、语言覆盖与配置边界。

统计 ID、生产加载条件,以及公开机器阅读文本中的站点补充。


输出
词 3.1k 令牌 4.1k

第一次发布可读部署教程,其中介绍统计 ID 获取和公开文本用途。配置文件位置见安装与站点信息,其他模块从配置字典总入口进入。

这两组配置写在 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 是否属于有效数据流;不要把“通过正则”理解成“已收到统计”。

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

关闭统计可合并:

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/’ }]
aiReadableContent.links[].label string,必填 / 无 条件生效:显示名称必须 trim 后非空;生成时将换行折为空格,并转义反斜杠与方括号。不会从目标页面自动获取标题 ‘项目主页’
aiReadableContent.links[].href string,必填 / 无 条件生效:必须非空,按发布根 URL 解析;解析后仅允许 HTTP(S),且不能带用户名或密码。非法值会报错,不验证目标存在或可访问 ‘https://example.com/project/’

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

Markdown 和相对链接如何处理?

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

链接解析基准是站点公开根 URL,包含 Astro base,不是当前文章 URL,也不是当前语言目录。例如发布根是 https://example.com/project/:

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

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

全局示例

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/’

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

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

只覆盖 notes 时仍继承全局 links;只写 {} 会继承两项。undefined 被忽略,不是清空指令。此对象不走 meta.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 共同影响;根索引标题与描述使用当前站点上下文。站点信息和部署方式见发布教程,不要在补充文字里修改网址就期待 canonical 一起变化。
  • 语言启停影响标准页面生成;关闭不等于自动清除托管平台旧文件。补充文字不创建译文,相关配置见语言字典。
  • GA4 只影响统计加载,不控制搜索、RSS 或机器阅读;静态补充也没有自己的界面按钮、翻译文案或访问统计开关。
  • 当前 GA4 ID 和所有补充字段都有消费位置,没有额外的过期字段需要填写。旧适配器缺少统计分支仅按未启用兼容,不是启用方式。

修改后需要重新构建部署。统计结果仍可能受浏览器拦截、网络或统计端设置影响;本地文本生成检查不能代替线上统计验收。返回配置字典总入口查其他模块。