robots.txt
用模板生成自定义 robots.txt,控制搜索引擎的抓取范围:开关、查找顺序、安全的最小示例与验证方法。
开始之前,你需要
- 站点能正常构建:
hugo --renderToMemory退出码为 0。 - 知道项目配置文件的路径(通常是项目根目录的
hugo.toml)。
读完之后你能
- 打开 robots.txt 生成,并确认
public/robots.txt的内容与预期一致; - 写出「只屏蔽个别目录、其余开放」的模板,而不是把整站 Disallow 掉;
- 知道模板查找顺序,能在不修改主题的前提下覆盖主题的同名模板;
- 在没有模板的情况下改用
static/robots.txt静态文件。
这一页解决什么问题
robots.txt 是放在站点根目录、给爬虫看的「访问须知」:它声明哪些路径允许抓、哪些不允许。Hugo 可以从模板生成这份文件,好处是规则可以跟着内容走——比如按页面集合生成、按环境生成,而不是手写一份静态清单。
这一页要弄清三件事:怎么打开开关、默认内容是什么、以及模板写错时后果有多严重(一条 Disallow: / 就能让整站从搜索结果里消失)。
启用 robots.txt 生成
要让 Hugo 从模板生成 robots.txt,先修改项目配置:
enableRobotsTXT = true开启之后,Hugo 会在站点根目录输出 robots.txt,默认内容来自内建模板,只有一行:
User-agent: *遵守 Robots 排除标准(Robots Exclusion Protocol)的搜索引擎会把这一行理解为「允许抓取站点上的全部内容」。也就是说,默认行为是完全开放,只有当你需要限制抓取时才有必要自定义。
最小可运行示例与验证
打开开关后直接构建:
hugo你应当看到 public/robots.txt 出现,内容为:
User-agent: *用本地服务器验证更直观(改配置后记得重启 hugo server,它是启动时读取配置的):
hugo server浏览器访问 http://localhost:1313/robots.txt,应当直接显示上面两行文本,而不是站点的 404 页面。如果显示的是 404 页面,说明配置文件里 enableRobotsTXT 没生效(多半是写错了位置或拼写)。
模板查找顺序
可以用自定义模板覆盖内建模板。Hugo 按下面的顺序查找 robots.txt 模板,使用第一个找到的文件:
/layouts/robots.txt/themes/<THEME>/layouts/robots.txt
项目自己的 layouts 目录优先级高于主题目录,因此覆盖主题的写法不需要改动主题文件,把同名文件放进项目 layouts 根目录即可。这也意味着升级主题不会冲掉你的定制,而把改动写进主题目录则会在下次更新时丢失。
模板示例
模板可以访问常规的页面集合与站点对象,因此能按页面动态生成规则。下面这个模板为站点上的每个页面各生成一条 Disallow 指令:
User-agent: *
{{ range .Pages }}
Disallow: {{ .RelPermalink }}
{{ end }}上面这份模板输出的 robots.txt 会给每个页面都加上一条 Disallow 指令,其效果是禁止搜索引擎抓取站点上的任何页面。它准确地演示了「模板能做什么」,但不要原样用于生产站点。
结果长什么样
上面的模板渲染出来是这样(节选):
User-agent: *
Disallow: /
Disallow: /templates/
Disallow: /templates/404/
Disallow: /functions/
...也就是说,除根路径以外,站点上的每个页面都被逐条点名屏蔽了,文件会随着页面数量线性变长。能跑通 ≠ 该这么用:真实站点通常只屏蔽少数路径。
只屏蔽个别目录(推荐写法)
下面的模板反过来用:整站开放,只挡住后台、搜索结果页这类不该被收录的路径,同时声明站点地图的位置。
User-agent: *
Disallow: /admin/
Disallow: /search/
Sitemap: {{ "sitemap.xml" | absURL }}你应当看到 public/robots.txt 的内容与模板一一对应,其中 Sitemap: 一行是绝对地址(例如 https://example.org/sitemap.xml)。用 absURL 而不是手写域名,站点换域名时这份文件不用改。
模板里也可以写 Allow 指令以及针对特定爬虫的 User-agent 分组,这些都属于 robots.txt 本身的语法,与模板写法无关。值得注意的是:Disallow 只是「请求不要抓取」的约定,不能阻止别人访问,真正的访问控制要靠服务器鉴权。
改用静态文件
两者的取舍:静态文件更简单、所见即所得,适合规则基本不变的中小站点;模板适合规则需要跟随内容变化(例如按分类、按语言、按环境开关)的站点。两处同时存在时会互相干扰,只保留一种。
常见坑
| 类别 | 现象 | 原因与处理 |
|---|---|---|
| 命令找不到 | hugo: command not found / 「不是内部或外部命令」 |
Hugo 没装或没进 PATH → 安装 Hugo |
| 没报错但结果不对 | 配置里明明写了 enableRobotsTXT = true,就是没有 public/robots.txt |
键写在了 [params]、[markup] 等表头之后,被当成该表的子键 → 把它移到所有 [table] 之前,重新构建 |
| 没报错但结果不对 | 文件生成了,但内容是旧规则 | 同时存在模板与 static/robots.txt,或浏览器/爬虫缓存了旧文件 → 只保留一处来源,用无痕窗口访问 /robots.txt 复核 |
| 没报错但结果不对 | 站点突然从搜索结果里消失 | 模板照抄了「逐页 Disallow」的示例,等于全站禁止收录 → 改用「只屏蔽个别目录」的写法 |
| 报错看不懂 | 构建时报模板执行失败,行号指向 layouts/robots.txt |
模板里的动作写错(少 end、变量名拼错)→ 按报错行号定位;本文件是纯文本模板,注意冒号后必须留一个空格(Disallow: /admin/) |
更多排查入口见故障排查。