PPysolate SpineREAD THE CODE · UNDERSTAND THE SYSTEM
课程与章节
CODE READING / 37

站点依赖与搜索索引规则

package.json / headers / robots

本章目录

本章要回答的问题： 站点从哪里开始构建，静态 _headers 和 robots.txt 又怎样参与发布后的行为？

输入是 site 目录中的 package manifest 和两个 public 文件；输出分成两部分：pnpm/Node/Astro 的构建命令链，以及部署平台可能转换成 HTTP 响应提示和爬虫规则的静态文本。它们都不启动登录系统，也不改变 runtime。

1. package.json 连接准备、生成和 QA

site/package.json · L1–L16 · 打开完整源码

{
  "name": "pysolate-spine-site",
  "private": true,
  "type": "module",
  "packageManager": "pnpm@10.30.3",
  "scripts": {
    "build": "node scripts/prepare.mjs && astro build && node scripts/verify.mjs",
    "test": "node scripts/prepare.mjs && node scripts/excerpts.test.mjs && node scripts/go-patterns.test.mjs && node scripts/lessons.test.mjs && node scripts/research.test.mjs",
    "dev": "node scripts/prepare.mjs && astro dev",
    "preview": "astro preview",
    "deploy": "bash scripts/deploy.sh"
  },
  "dependencies": {
    "astro": "7.2.4"
  }
}

根对象先声明站点包名、private、ES module 模式和预期的 pnpm 版本。private: true 防止把站点包发布到公共 registry；type: module 让脚本使用 import；packageManager 记录工具版本，减少不同环境解释脚本的差异。

scripts.build 是整条数据流的入口：

node scripts/prepare.mjs
  → astro build
  → node scripts/verify.mjs

shell 的 && 让每一步都依赖前一步成功。准备阶段先写 .generated/，Astro 再把内容和源码数据渲染成 dist，验证器最后检查静态产物。准备或 Astro 失败时不会运行后续阶段；验证失败时 pnpm build 仍然返回失败。

dev 先准备同一份生成数据再启动 Astro 开发服务；preview 只预览已有构建，不重新准备或构建；deploy 把发布委托给 scripts/deploy.sh，manifest 只声明入口，不展开托管细节。依赖区当前声明 Astro 7.2.4，它影响内容 loader、静态路径和 Code 组件的构建行为。

因此，“运行 pnpm preview”不等于“拿到最新源码”：需要先重新执行 build，或明确运行准备阶段。

2. _headers 描述响应级搜索和浏览器策略

site/public/_headers · L1–L5 · 打开完整源码

/*
  X-Robots-Tag: noindex, nofollow, noarchive, nosnippet
  Referrer-Policy: no-referrer
  X-Content-Type-Options: nosniff
  Cache-Control: no-cache

_headers 是部署平台约定的静态配置：第一行 /* 让规则匹配所有路径；其余行声明：

  • X-Robots-Tag 与 HTML meta 保持 noindex、nofollow、noarchive、nosnippet；
  • Referrer-Policy: no-referrer 不向后续请求发送来源 URL；
  • X-Content-Type-Options: nosniff 防止浏览器随意猜测媒体类型；
  • Cache-Control: no-cache 要求缓存重新验证，而不是承诺永不存储。

这些文本只有被支持该约定的托管平台解析并写入 HTTP 响应后才真正生效。本地仓库文件不会自动成为浏览器响应头，验证器也只检查文本契约，不替托管层做线上回读。

3. robots.txt 让 crawler 看见 noindex

site/public/robots.txt · L1–L4 · 打开完整源码

# Crawlers must be able to read the noindex meta/header.
# Disallowing all crawling could hide noindex and leave URL-only search listings.
User-agent: *
Allow: /

前两行注释说明设计原因：如果直接禁止所有抓取，crawler 可能看不到页面里的 noindex，只留下只有 URL 的搜索条目。User-agent: * 将规则应用于所有 crawler，Allow: / 允许它们读取站点路径。

这不是“请求许可”的设置。网络、托管平台、网关或鉴权系统决定谁能请求文件；robots 给 crawler 的是爬取建议；HTML meta 与 X-Robots-Tag 才是索引提示。三者分工不同，Allow: / 不能推出站点私有，noindex 也不能阻止知道 URL 的人访问。

4. 配置如何接回构建验收

pnpm build 会把 public/ 内容复制到 dist，所以 _headers 与 robots.txt 成为验证器可以读取的产物。verify.mjs 检查 headers 的全路径规则和 X-Robots-Tag，检查 robots 的 User-agent: *、Allow: / 以及不存在根路径 Disallow。这样至少能发现文件被漏复制或文本意图被改写。

它仍不能证明目标托管平台解析了 _headers，也不能证明 crawler 的实际行为，更不提供访问鉴权。要沿完整交接继续读 站点构建管线 与 构建后 QA；要看 meta 怎样进入 HTML，读 页面外壳。

读完本章，应能回答：为什么 build 的三个脚本必须串行？robots.txt 为什么允许读取却仍然配合 noindex？哪些配置只在部署平台解析后才具有 HTTP 效果？