Astro 6 升级指南：从 v5 到 v6 的破坏性变更全记录

背景

Astro 6 在 2026 年初正式发布，带来了大量底层改进。但对于已有项目来说，升级并不是 npm install astro@latest 这么简单。我在升级 FisherHub Blog 时踩了一圈坑，记录下来供参考。

核心变更

1. Content Collections API 重构

最大的变化。src/content/config.ts 不再是唯一入口，改为 src/content.config.ts + glob loader：

// ❌ Astro 5 方式
import { defineCollection, z } from 'astro:content';
const blog = defineCollection({
  schema: z.object({ title: z.string() }),
});

// ✅ Astro 6 方式
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.mdx', base: './src/content/blog' }),
  schema: z.object({ title: z.string() }),
});

2. post.render() → render(post)

MDX 渲染方式彻底变了，不再是实例方法：

// ❌ 旧
const { Content } = await post.render();

// ✅ 新
import { render } from 'astro:content';
const { Content } = await render(post);

3. @astrojs/tailwind 废弃

Astro 6 不再支持 @astrojs/tailwind 集成。必须用 @tailwindcss/vite 插件替代：

// astro.config.mjs
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: { plugins: [tailwindcss()] },
});

同时 Tailwind v4 的配置方式从 JS 文件变为 CSS-first（@theme 块）。

4. @astrojs/node 版本要求

必须用 @astrojs/node@^10.x，9.x 不兼容 Astro 6。

升级步骤清单

1. 升级所有 @astrojs/* 包到最新
2. 迁移 content.config.ts
3. 改 post.render() → render(post)
4. 移除 @astrojs/tailwind，安装 @tailwindcss/vite + tailwindcss@^4
5. 删除 tailwind.config.mjs，改用 CSS @theme
6. 给 SSR 动态路由加 export const prerender = true
7. astro build 测试

总结

Astro 6 的改进方向是正确的——更简洁的 API、更好的性能。但破坏性变更确实不少。建议先在分支上升级，逐个修 error，不要在生产环境直接操作。