企业官网建设流程全解析

Glance 如何用 $include 把 glance.yml 拆分成多文件并定位行号错乱的报错？

【免费下载链接】glanceA self-hosted dashboard that puts all your feeds in one place项目地址: https://gitcode.com/GitHub_Trending/gla/glance

当 Glance 的配置文件glance.yml越写越长，你通常会把不同页面或小组件的配置拆到独立文件里，用$include指令从主配置引入。这样做会遇到一个典型的坑：拆分后一旦出现 YAML 解析错误，报错给出的行号往往不是错的真正位置，因为 Glance 是在解析 YAML 之前就把 include 的文件内容合并进主配置的。本文按 docs/configuration.md 中 "Including other config files" 一节给出的方法，演示如何完成拆分、如何确认拆分生效，以及在行号错乱时如何用config:print命令定位真实出错位置。

用 $include 把配置拆成多个文件

$include后面跟相对路径或绝对路径；相对路径是相对于主配置文件所在目录解析的。include 的文件里同样可以使用${ENV_VAR}环境变量语法，对 include 文件的修改也会触发热加载，这一点和修改主配置文件的效果一致。

把每个页面的配置拆成独立文件时，写法是：

pages: - $include: home.yml - $include: videos.yml - $include: homelab.yml

更常见的是把单个 widget 拆出去，例如文档示例中的glance.yml：

pages: - name: Home columns: - size: full widgets: - $include: rss.yml - name: News columns: - size: full widgets: - type: group widgets: - $include: rss.yml - type: reddit subreddit: news

被引入的rss.yml有两个硬性要求：

• 文件内不能有多余缩进，值要写在顶层，缩进会由 Glance 根据 include 所在位置自动补上；
• $include指令必须独占一行，并带有正确的缩进。

对应的rss.yml内容（值位于顶层）：

- type: rss title: News feeds: - url: ${RSS_URL}

$include并不限于pages属性，配置文件的任何位置都可以使用，只要满足上面"独占一行、缩进正确"两个条件。

确认拆分后的配置已生效

Glance 支持自动重载配置：保存后无需重启容器或服务。判断新配置是否被接受，可以看两种现象（见 docs/configuration.md 的 "Auto reload" 一节）：

• 如果启动时配置就无效，Glance 会直接报错退出；
• 如果启动成功后再修改出错误，错误会打印在控制台，Glance 会继续用旧配置运行，直到修改到没有错误时才加载新配置。

所以拆文件改完保存后，观察控制台：没有新错误输出，说明含$include的新配置已被解析并接受；如果看到解析错误，就进入下一步定位。

行号错乱时用 config:print 定位报错

当报错行号对不上你打开的那个文件时，不要直接按行号改。先理解原因：include 是在 YAML 解析之前做的文本级合并（YAML 本身不支持文件引用），所以报错行号对应的是合并后的大文件，而不是你编辑的子文件。

Glance 为此提供了config:print命令，用于打印 include 全部解析后的完整配置，配合less -N显示行号：

glance --config /path/to/glance.yml config:print | less -N

/path/to/glance.yml换成你的主配置文件路径。该命令对应 cli.go 中列出的config:print Print the parsed config file with embedded includes，实现见 main.go。

如果你的 Glance 跑在 Docker 容器里，文档给出的是这条等价命令：

docker run --rm -v ./glance.yml:/app/config/glance.yml glanceapp/glance config:print | less -N

注意它的前提：要打印的配置必须位于当前工作目录且文件名就叫glance.yml，否则需要相应调整挂载路径。该命令以一次性容器运行（--rm结束即清理），不会改动你现有容器的数据。

按输出核对出错位置

config:print | less -N的输出是 include 已经展开、并带行号的完整配置，也就是 Glance 实际拿去解析的那份内容。定位步骤：

1. 拿控制台报错里的行号，在less -N输出中找到同一行号；
2. 该行列出的就是合并后的实际内容，据此判断问题出在主文件还是某个被引入的文件里；
3. 修正对应文件保存，控制台不再报新错即表示新配置已加载。

如果config:print本身就输出Could not parse config file: ...，说明连 include 展开这一步都没成功（比如路径写错、文件读不到），此时先修路径问题，再重新执行上面的命令。

限制与边界

• 被引入文件的值必须写在顶层，多余的缩进不会被自动纠正；
• 相对路径相对于主配置文件解析，不是相对于当前工作目录，在 Docker 场景下尤其容易写错；
• include 支持递归引入，源码中设置了递归深度上限（CONFIG_INCLUDE_RECURSION_DEPTH_LIMIT = 20，见 config.go），超过会报recursion depth limit of 20 reached；
• 修改环境变量不会触发自动重载，需要手动重启；
• 重载配置会清空缓存数据，频繁改动配置可能触发某些 API 的限流，这是文档明确标注的代价。

【免费下载链接】glanceA self-hosted dashboard that puts all your feeds in one place项目地址: https://gitcode.com/GitHub_Trending/gla/glance