CMS 后台空白或报错

现象 1：admin 页面完全空白

原因：Docusaurus dev server（npm run start）将所有非 HTML 路由 fallback 到 index.html，导致 /admin/config.yml 请求返回 HTML 而非 YAML。

解决：使用 npm run build + npm run serve 代替 npm run start。

现象 2：报错 "Error loading the CMS configuration" / "YAMLSemanticError: Map keys must be unique"

原因：config.yml 文件中 backend 等 key 重复出现（之前写入时意外追加了旧配置）。

解决：

1. 检查 static/config.yml 是否有重复内容
2. 确保只有一个完整的配置块
3. 同步到 static/admin/config.yml 和 build/config.yml

# 同步 config
Copy-Item static\config.yml static\admin\config.yml -Force
# build 后自动复制，或手动：
Copy-Item static\config.yml build\config.yml -Force

现象 3：CMS 登录后，集合页面不显示文章

原因：collection 配置中 filter 规则过滤掉了文件。

解决：移除 filter，改用：

extension: "md"
format: "frontmatter"

现象 4：点击文章报错 "Unrecognized front-matter format"

原因：Markdown 文件缺少 --- 开头的 frontmatter 块（如 README.md）。

解决：为每个 md 文件添加 frontmatter：

---
title: "文档标题"
---

批量修复脚本见 knowledgebase-site/fix-readme.js。

现象 5：CMS 加载缓慢或 decap-cms.js 加载失败

原因：CDN 网络不稳定。

解决：已将 decap-cms.js 下载到 static/admin/decap-cms.js 本地加载。如需更新版本，从 unpkg.com 下载替换。

CMS 配置文件位置说明

Decap CMS 在站点根目录 /config.yml 加载配置。当前项目中存在以下副本：

路径	用途
static/config.yml	源文件，build 后复制到 build/config.yml
static/admin/config.yml	备份，未实际使用
build/config.yml	运行时 CMS 加载的配置文件

修改配置后必须同步：

# 编辑 static/config.yml，然后：
Copy-Item static\config.yml static\admin\config.yml -Force
npm run build   # 会自动将 static/ 内容复制到 build/