问题复现:首页的文章时间突然全部消失

早上九点,我照例打开墨点博客检查更新,发现首页显示的文章时间全部变成了空白:

【博客动态】
· 墨点博客迁移记:从 Halo Docker 到 Cloudflare Pages 的完整实践
  阅读时间:分钟 ← ❌ 这里本该是"5分钟前"
· 内网服务上公网全攻略:端口映射、反向代理、隧道三种方案对比
  阅读时间:分钟

更糟的是,归档页面 /archives 直接崩了——所有文章都堆在”未知日期”组里,按时间排序的功能完全失效。

排查:从表象到根源

第一轮:检查日期格式

先看文章 Front Matter,格式看起来正常:

---
title: 墨点博客迁移记:从 Halo Docker 到 Cloudflare Pages 的完整实践
slug: halo-to-cloudflare-pages-migration
date: 2024-11-20T08:30:00Z
---

在 Astro 页面里输出原始数据:

---
import { getCollection } from 'astro:content';
const posts = await getCollection('posts');
---
{posts.map(p => (
  <div>
    <h3>{p.data.title}</h3>
    <pre>日期类型:{typeof p.data.date}</pre>
    <pre>日期原始值:{String(p.data.date)}</pre>
  </div>
))}

结果让人意外:

日期类型:object
日期原始值:Wed Nov 20 2024 08:30:00 GMT+0000

发现 1:p.data.date 是 Date 对象,不是字符串。

第二轮:定位格式化问题

首页的时间格式化逻辑:

---
function fmtTime(date) {
  // ❌ 这里有问题
  const iso = date.toISOString();  // TypeError: date.toISOString is not a function
  // 实际运行时:date 有时是 Date 对象,有时是字符串
}
---

问题出在 YAML 解析。Astro 的 content collections 使用 js-yaml 解析 Front Matter,而 YAML 规范会把符合 ISO 格式的字符串自动转换为 Date 对象。

第三轮:验证三种错误现象

  1. 首页 time 空:

    // 错误的格式化函数
    function formatDateForHome(date) {
      // date 可能是 "2024-11-20T08:30:00Z" 或 Date 对象
      const match = date.match(/(\d{4})-(\d{2})-(\d{2})/);
      // ❌ 当 date 是 Date 对象时,match 为 null
      return match ? `${match[1]}-${match[2]}-${match[3]}` : '';
    }
  2. 归档分组失效:

    // archives.astro 中的错误代码
    const groups = posts.reduce((acc, p) => {
      const key = p.data.date.slice(0, 7); // "2024-11"
      // ❌ p.data.date 是 Date 对象时,没有 slice 方法
      acc[key] = acc[key] || [];
      acc[key].push(p);
      return acc;
    }, {});
  3. 排序错乱:

    // 错误的排序
    const sorted = posts.sort((a, b) => {
      // ❌ Date 对象直接比较字符串
      return String(a.data.date).localeCompare(String(b.data.date));
      // 结果:"Wed Nov 20 2024 ..." 按字母排序,不是按时间先后
    });

错误原因:YAML 的类型转换

Astro 内容集合的核心代码简化如下:

// 类似 Astro 内部的逻辑
import { parse } from 'js-yaml';

const frontmatter = parse(`
---
title: 示例文章
date: 2024-11-20T08:30:00Z
---`);

console.log(typeof frontmatter.date);  // "object"
console.log(frontmatter.date instanceof Date);  // true

js-yaml 转换规则:

  • 2024-11-20 → Date 对象
  • 2024-11-20T08:30:00Z → Date 对象
  • 2024-11-20 08:30:00 → 字符串(因为空格)
  • "2024-11-20" → 字符串(加引号阻止转换)

这种隐式转换是 YAML 标准的一部分,但在内容集合的上下文里带来了类型不确定性。

修复方案:三种解法对比

方案 A:强制字符串表示(失败)

最初尝试在 Front Matter 里加引号:

date: "2024-11-20T08:30:00Z"  # 引号阻止自动转换

问题:Astro 的 markdown 插件链在 js-yaml 之后还有处理,引号会被去掉,最终仍是 Date 对象。

方案 B:统一转字符串(过渡方案)

建立转换函数,把 Date 对象统一转成 ISO 字符串:

function safeDate(d) {
  if (d instanceof Date) {
    return isNaN(d.getTime()) ? '' : d.toISOString();
  }
  return String(d || '');
}

但每个页面都要调用这个函数,容易漏掉。

方案 C:内容层拦截(最终方案)

在内容集合的 schema 里定义类型转换:

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const posts = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.string()
      .transform(str => {
        // 拦截 YAML 的 Date 对象转换
        if (str instanceof Date) {
          return str.toISOString();
        }
        return str;
      })
      .refine(val => /^\d{4}-\d{2}-\d{2}/.test(val), {
        message: '日期必须为 ISO 格式,如 2024-11-20',
      }),
  }),
});

然而,这里有个坑:z.string() 已经拒绝了 Date 对象,transform 函数根本接收不到 Date。

方案 D:使用联合类型(成功)

const posts = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.union([
      z.string(),
      z.date().transform(d => d.toISOString()),
    ]).refine(val => typeof val === 'string', {
      message: '日期最终应为字符串',
    }),
  }),
});

测试后发现仍然有问题——Astro 的内容集合加载期在 schema 校验之前。

最终方案:页面层防御性代码

经过一轮轮测试,我意识到最可靠的方案是在页面层做防御性处理:

---
// src/pages/archives.astro
import { getCollection } from 'astro:content';

// 核心修复函数
function toIso(d) {
  if (!d) return '';
  if (d instanceof Date) {
    return isNaN(d.getTime()) ? '' : d.toISOString().slice(0, 10);
  }
  // 处理字符串
  const m = String(d).match(/(\d{4})-(\d{2})-(\d{2})/);
  return m ? `${m[1]}-${m[2]}-${m[3]}` : '';
}

const all = await getCollection('posts');
const posts = all
  .map(p => ({
    ...p,
    // 关键:在这里统一转换
    iso: toIso(p.data.date),
  }))
  .sort((a, b) => b.iso.localeCompare(a.iso));
---

修复后的正确代码

1. 工具函数统一放置

// src/utils/date.ts
export function normalizeDate(input: unknown): string {
  if (!input) return '';
  
  // 情况1:Date 对象
  if (input instanceof Date) {
    return isNaN(input.getTime()) 
      ? '' 
      : input.toISOString().slice(0, 10); // "2024-11-20"
  }
  
  // 情况2:ISO 字符串
  const str = String(input);
  const match = str.match(/^(\d{4})-(\d{2})-(\d{2})/);
  if (match) {
    return `${match[1]}-${match[2]}-${match[3]}`;
  }
  
  // 情况3:其他格式
  try {
    const date = new Date(str);
    if (!isNaN(date.getTime())) {
      return date.toISOString().slice(0, 10);
    }
  } catch {
    // 解析失败
  }
  
  return '';
}

2. 首页时间显示

---
import { normalizeDate } from '../utils/date';
import { getCollection } from 'astro:content';

const posts = (await getCollection('posts'))
  .filter(p => !p.data.draft)
  .map(p => ({
    ...p,
    dateIso: normalizeDate(p.data.date),
    // 计算相对时间
    timeAgo: getTimeAgo(p.data.date),
  }))
  .slice(0, 10);
---

{posts.map(p => (
  <article>
    <h3>{p.data.title}</h3>
    <time datetime={p.dateIso}>{p.timeAgo}</time>
  </article>
))}

3. 归档页面重构

---
import { normalizeDate } from '../utils/date';

const all = await getCollection('posts');
const posts = all
  .filter(p => !p.data.draft)
  .map(p => ({
    post: p,
    slug: p.data.slug || p.id.replace(/\.md$/, ''),
    iso: normalizeDate(p.data.date),
  }))
  .filter(p => p.iso) // 过滤掉无效日期
  .sort((a, b) => b.iso.localeCompare(a.iso));

// 按年月分组
const byMonth = posts.reduce((acc, item) => {
  const month = item.iso.slice(0, 7); // "2024-11"
  if (!acc[month]) acc[month] = [];
  acc[month].push(item);
  return acc;
}, {});
---

预防措施

1. 写文章时规范日期格式

创建模板文件 tools/posts/template.md:

---
title: 标题
slug: english-slug
date: 2024-11-20              # 只写日期,不写时间
# 或者明确标记
publishTime: "2024-11-20T08:30:00Z"  # 加引号
categories: 技术
tags: 标签1, 标签2
---

2. 添加内容校验脚本

#!/usr/bin/env python3
# tools/validate_dates.py
import yaml
import glob
import re

def check_date(val):
    """检查日期值是否可能被解析为 Date 对象"""
    patterns = [
        r'^\d{4}-\d{2}-\d{2}$',
        r'^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$',
        r'^\d{4}/\d{2}/\d{2}$',
    ]
    return any(re.match(p, str(val)) for p in patterns)

errors = []
for f in glob.glob('src/content/**/*.md'):
    with open(f, encoding='utf-8') as fp:
        content = fp.read()
        if '---' in content:
            parts = content.split('---', 2)
            if len(parts) >= 2:
                try:
                    fm = yaml.safe_load(parts[1])
                    if 'date' in fm and check_date(fm['date']):
                        print(f"⚠️  {f}: YAML 可能将日期解析为 Date 对象")
                        errors.append(f)
                except yaml.YAMLError:
                    pass

if errors:
    print(f"\n建议修改:在这些文件的 date 值上加引号")

3. 测试用例

创建测试文件确保后续修改不会破坏:

// test/date-normalize.test.ts
import { normalizeDate } from '../src/utils/date';

describe('normalizeDate', () => {
  test('Date 对象转换', () => {
    const date = new Date('2024-11-20T08:30:00Z');
    expect(normalizeDate(date)).toBe('2024-11-20');
  });

  test('ISO 字符串转换', () => {
    expect(normalizeDate('2024-11-20T08:30:00Z')).toBe('2024-11-20');
    expect(normalizeDate('2024-11-20')).toBe('2024-11-20');
  });

  test('无效日期返回空字符串', () => {
    expect(normalizeDate('invalid')).toBe('');
    expect(normalizeDate(new Date('invalid'))).toBe('');
    expect(normalizeDate(null)).toBe('');
    expect(normalizeDate(undefined)).toBe('');
  });
});

为什么这个问题容易忽视?

  1. 开发阶段不暴露:本地开发时,如果所有文章的 date 都是统一格式,可能一直正常
  2. 渐进式出现:写新文章时才用新格式,旧文章仍正常
  3. 静默失败:match() 失败返回 null,显示为空,不会抛异常
  4. 类型系统逃逸:TypeScript 在构建期无法检测运行时的 YAML 转换

经验教训

  1. 不信任外部数据:即使是自己写的 Front Matter,解析器也可能改变类型
  2. 防御性编程:对于日期这种易变类型,始终做类型检查和转换
  3. 建立数据管道:内容加载 → 数据清洗 → 页面使用,中间要有明确的转换层
  4. 编写测试:涉及日期处理的代码必须有测试用例

一句话总结

YAML 的 2024-11-20 不是字符串,是 Date 对象。在 Astro 内容集合里,永远用 instanceof Date 检查一遍。


问题发现时间:2024-11-20
修复时间:2024-11-21
稳定性:已稳定运行 30+ 天
影响范围:首页、归档页、分类页的时间显示

下一篇,我将分享 Cloudflare 缓存规则的实际应用和踩过的坑。