Astro 7 + Tailwind 4 建站踩坑记录

这篇文章记录我从零搭一个 Astro 站点时，真正卡住我的几个地方。都是能搜到但答案分散的问题。

一、`npm create astro@latest` 直接失败

报错是：

UNABLE_TO_VERIFY_LEAF_SIGNATURE
unable to verify the first certificate

原因不是网络不通，而是 Node 24 的 TLS 根证书链在处理 giget（Astro 用来拉远程模板的库）时校验失败。

两个解法，按推荐顺序：

解法一（推荐）：升级 npm 到最新版，Node 24 的根证书问题在新版 npm 里已经处理过。

解法二：临时关闭该项目的 SSL 严格校验。

npm config set strict-ssl false --location=project

注意 --location=project —— 这会把配置写进项目目录下的 .npmrc，只影响这个项目，不会污染全局 npm 配置。这是关键，别用 --location=global。

解法三：干脆不用 create-astro。它做的事情无非是复制模板 + 装依赖，手工建目录、手写 package.json 和 astro.config.mjs，再 npm install，效果完全一样，还少一层黑盒。我最后走的就是这条路。

二、Tailwind 4 的接入方式和 3.x 完全不同

如果你搜到的是这种写法：

import tailwind from '@astrojs/tailwind';

export default defineConfig({
  integrations: [tailwind()],
});

这是 3.x 的方式，在 4.x 里已经废弃。

Tailwind 4 的正统接法是走 Vite 插件：

import tailwindcss from '@tailwindcss/vite';

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

而且要装的是 @tailwindcss/vite，不是 @astrojs/tailwind。

配置方式也变了

4.x 没有 tailwind.config.js 了。设计令牌写在 CSS 里：

@import 'tailwindcss';

@theme {
  --color-brand-500: #3b82f6;
  --radius-candy: 20px;
}

@theme 里定义的变量会自动生成对应的工具类（bg-brand-500、rounded-candy）。

插件也改成 CSS 引入：

@plugin '@tailwindcss/typography';

三、Content Collections 的 loader 迁移

Astro 5 开始，type: 'content' 这种写法废弃了，改成显式的 loader：

// 旧写法（已废弃）
const posts = defineCollection({
  type: 'content',
  schema: z.object({ /* ... */ }),
});

// 新写法
import { glob } from 'astro/loaders';

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

另一个容易卡住的地方：渲染函数从 entry.render() 变成了 render(entry)。

---
import { render } from 'astro:content';
const { Content, headings } = await render(entry);
---

后者返回的 headings 可以直接用来生成目录（TOC），比手动解析 Markdown 方便得多。

四、WebGPU 组件不能 SSR

用了 Shaders 这类 WebGPU 库做背景时，组件必须在浏览器里才能初始化。如果直接写：

<HeroShader />

构建时会因为 navigator.gpu 不存在而报错。正确写法：

<HeroShader client:only="react" />

client:only 的意思是跳过 SSR，只在客户端渲染。代价是这块内容不会出现在首屏 HTML 里（对纯装饰性背景来说无所谓）。

五、Shaders 里蓝白渐变会发灰

这个坑最隐蔽。用默认的 RGB 插值做「蓝 → 白」渐变时，中间会经过一段灰蒙蒙的区域。

原因是 RGB 空间下的线性插值不符合人眼感知。

解法：在 Shaders 组件上显式指定 colorSpace="oklab"。

<MeshGradient colorA="#dcebff" colorB="#7dd3fc" colorSpace="oklab" />

oklab 是感知均匀的色彩空间，插值出来的中间色不会脏。这一条对做「糖果感」配色是决定性的。

六、Pagefind 在 dev 模式下必然 404

Pagefind 的索引是构建产物，npm run dev 时 /pagefind/ 目录根本不存在。

如果搜索页直接注入脚本，dev 下会看到一个空白框或者控制台报错。

解法：加载前先探测资源是否存在。

const probe = await fetch('/pagefind/pagefind-ui.css', { method: 'HEAD' }).catch(() => null);
if (!probe?.ok) {
  // 显示「索引尚未生成，请先 npm run build」的提示
}

比静默失败好得多 —— 至少你知道该跑什么命令。

小结

这六个问题里，有四个是版本迁移造成的（Tailwind 3→4、Astro 4→5 的 loader、 Astro 的 render API），两个是环境相关（Node 24 的证书、WebGPU 的 SSR 限制）。

教训是：搜到教程先看日期。前端生态一年一变，2024 年的教程在 2026 年有一半是错的。

一、npm create astro@latest 直接失败