使用 check-all-content.mjs 自動檢查與修復 Astro 內容集合格式問題

在維護 Astro 靜態網站時，內容集合（Content Collections）的 frontmatter 格式一致性是確保網站正常構建的關鍵。本文介紹如何使用 check-all-content.mjs 腳本來系統化檢查和修復內容文件格式問題。

問題背景

當 Astro 網站突然出現 id.endsWith is not a function 或類似的構建錯誤時，通常是由於內容文件的 frontmatter 格式問題所致。常見問題包括：

• 字符串字段缺少引號
• 字段類型不正確（如應為數組卻為字符串）
• 日期格式不規範
• 特殊字符未正確轉義

解決方案：check-all-content.mjs

腳本功能

check-all-content.mjs 是一個全面的檢查工具，能夠：

1. 系統性掃描所有內容文件
2. 識別格式問題並提供詳細錯誤信息
3. 建議修復方案並可自動執行修復

基本使用方法

1. 創建檢查腳本

// Mountos Code Lab: check-all-content.mjs
import fs from 'fs';
import path from 'path';
import yaml from 'js-yaml';

console.log('🔍 系統性檢查所有內容文件...\n');

const blogDir = './src/content/blog';
const slugDirs = fs.readdirSync(blogDir, { withFileTypes: true })
  .filter(item => item.isDirectory())
  .map(item => item.name);

console.log(`找到 ${slugDirs.length} 個文章目錄\n`);

let totalProblems = 0;

for (const slug of slugDirs) {
  const filePath = path.join(blogDir, slug, 'index.md');

  if (!fs.existsSync(filePath)) {
    console.log(`❌ ${slug}: 缺少 index.md`);
    totalProblems++;
    continue;
  }

  try {
    const content = fs.readFileSync(filePath, 'utf8');
    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);

    if (!frontmatterMatch) {
      console.log(`❌ ${slug}: 缺少 frontmatter`);
      totalProblems++;
      continue;
    }

    const data = yaml.load(frontmatterMatch[1]);
    const fileProblems = [];

    // 檢查必需字段
    if (!data.title || typeof data.title !== 'string') {
      fileProblems.push('title 問題');
    }

    if (!data.description || typeof data.description !== 'string') {
      fileProblems.push('description 問題');
    }

    if (!data.pubDate) {
      fileProblems.push('pubDate 問題');
    }

    if (fileProblems.length > 0) {
      console.log(`⚠️ ${slug}: ${fileProblems.join(', ')}`);
      totalProblems++;
    } else {
      console.log(`✅ ${slug}: 格式正確`);
    }

  } catch (error) {
    console.log(`❌ ${slug}: ${error.message}`);
    totalProblems++;
  }
}

console.log(`\n📊 總共發現 ${totalProblems} 個問題`);
// [Mountos Code Lab](https://mountos.com/code)

2. 運行檢查

node check-all-content.mjs

進階功能：自動修復

對於常見問題，可以擴展腳本實現自動修復：

// fix-common-issues.mjs
import fs from 'fs';
import path from 'path';
import yaml from 'js-yaml';

console.log('🔧 自動修復常見問題...\n');

const blogDir = './src/content/blog';
const slugDirs = fs.readdirSync(blogDir, { withFileTypes: true })
  .filter(item => item.isDirectory())
  .map(item => item.name);

let fixedCount = 0;

for (const slug of slugDirs) {
  const filePath = path.join(blogDir, slug, 'index.md');

  try {
    const content = fs.readFileSync(filePath, 'utf8');
    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);

    if (!frontmatterMatch) continue;

    let data = yaml.load(frontmatterMatch[1]);
    let modified = false;

    // 自動修復字段類型
    if (data.title && typeof data.title !== 'string') {
      data.title = String(data.title);
      modified = true;
    }

    if (data.description && typeof data.description !== 'string') {
      data.description = String(data.description);
      modified = true;
    }

    if (modified) {
      const newFrontmatter = '---\n' + yaml.dump(data).trim() + '\n---';
      const newContent = content.replace(/^---\n[\s\S]*?\n---/, newFrontmatter);
      fs.writeFileSync(filePath, newContent, 'utf8');
      fixedCount++;
      console.log(`✅ ${slug}: 已修復`);
    }

  } catch (error) {
    console.log(`❌ ${slug}: 修復失敗`);
  }
}

console.log(`\n🎉 完成！修復了 ${fixedCount} 個文件`);

實際應用案例

案例：修復缺少引號的標題

問題文件：

---
title: 這是一個標題: 包含冒號
description: 描述內容
author: Mountos.com
pubDate: 2024-01-01
---

修復後：

---
title: "這是一個標題: 包含冒號"
description: "描述內容"
author: Mountos.com
pubDate: 2024-01-01
---

案例：修復數組字段

問題文件：

---
title: "文章標題"
tags: 單一標籤  # 應該是數組
---

修復後：

---
title: "文章標題"
tags: ["單一標籤"]
---

集成到工作流程

1. 預提交檢查（Git Hook）

在 .git/hooks/pre-commit 中添加：

#!/bin/bash
echo "檢查內容文件格式..."
node check-all-content.mjs
if [ $? -ne 0 ]; then
  echo "請先修復內容文件格式問題"
  exit 1
fi

2. CI/CD 集成

在 GitHub Actions 工作流中：

- name: 檢查內容格式
  run: node check-all-content.mjs

最佳實踐建議

1. 定期檢查：在每次內容更新後運行檢查腳本
2. 自動化修復：對於可自動修復的問題，使用修復腳本
3. 團隊協作：確保所有內容編輯者了解 frontmatter 格式規範
4. 版本控制：將檢查腳本納入版本控制，方便團隊共享

總結

check-all-content.mjs 是一個強大的工具，能夠幫助 Astro 網站維護者：

• 快速定位內容格式問題
• 預防構建失敗
• 保持內容集合的一致性
• 提高團隊協作效率

通過將此工具集成到開發工作流程中，可以顯著減少因內容格式問題導致的網站構建失敗，確保網站的穩定運行。

使用命令：

1. 檢查問題：node check-all-content.mjs
2. 自動修復：node fix-common-issues.mjs
3. 驗證修復結果：npm run build