---
title: 构建期校验
desc: 两档校验与三向对账——坏数据在构建时报错，而不是上线后悄悄坏掉。
date: "2026-10-30"
order: 2
tags: [Astro, 校验]
---

## 两档校验

`lib/validate.js` 在每次 dev / build 都会跑一遍，分两档：

- **data 模式**（恒开）：schema、角色和结构互验、markers 引用完整性、
  mdx 地址与目录地址的撞车检测；
- **full 模式**（设 `ATLAS_FULL=0` 可临时关）：登记表和页面文件互相对账。

## 它能拦住什么

举几个真实会报错的例子。同一目录下两个章节写了相同的 `order`，构建直接失败：

```txt
[atlas] ../content/posts/building-this-site/publishing/rss.mdx: order 2 与 ../content/posts/building-this-site/publishing/mdx.mdx 重复——同一目录内序号必须唯一
```

往目录里塞 `index.mdx`（目录索引只允许 `index.astro` 承载）：

```txt
[atlas] (index.mdx): ../content/posts/index.mdx 不允许——目录索引一律用 index.astro（写系列引言请在落地页 astro 里写）
```

还有散篇推导出的地址撞上目录、`section` 分组建在系列树之外、markers 引用了
不存在的 id、散篇忘了写日期……全都一样：构建失败，错误信息带着文件路径，
当场改当场好。

## 为什么这么严

静态站怕的不是报错，是错得没声音。章节顺序排错了、链接指空了，页面上一点
动静都没有，等哪天自己翻到了才发现，那时候它已经在线上挂了不知多久。

构建期校验把这类事故拦在本地。报错烦人，但比悄悄坏掉强。