#Astro SSR 模式下 UnoCSS 样式丢失问题解析与解决方案

在将 Astro 项目从 SSG（静态生成） 切换为 SSR（服务端渲染） 后，很多人都会遇到一个相同的问题：
👉 页面正常渲染，但样式突然失效，控制台提示类似：

复制GET /assets/index.DmQq-yQC.css 404 (Not Found)

本文将详细分析这个问题的成因，以及最终的解决办法。

#一、问题背景

原本使用 Astro + UnoCSS + SSG 时，一切正常。
但在切换到 SSR 模式（如使用 @astrojs/node 适配器）后，构建成功，运行时却出现：

• 页面无样式；
• 控制台显示 404 Not Found；
• 请求路径类似 /assets/index.XXXX.css；
• 实际上该文件存在于 dist/server/assets/ 下，而非 dist/client/assets/。

#二、问题根源分析

核心原因不在 UnoCSS 本身，而是 Astro SSR 构建流程与 UnoCSS 输出逻辑之间的脱节。

#1. UnoCSS 的行为

当你在 astro.config.mjs 里启用了：

复制UnoCSS({
  injectReset: true
})

UnoCSS 会在构建时生成一份全局重置样式（reset CSS），例如：

复制index.DmQq-yQC.css

在 SSR 模式 下，它会被产出到：

复制dist/server/assets/index.DmQq-yQC.css

因为在 SSR 渲染阶段，这份 CSS 由服务端引入。

#2. Astro SSR 的文件托管逻辑

Astro 的 Node 适配器运行时，只会将 dist/client 作为静态资源目录暴露给浏览器。

也就是说，用户访问 /assets/xxx.css 时，Astro 实际查找的路径是：

复制dist/client/assets/xxx.css

但是 UnoCSS 把文件放到了：

复制dist/server/assets/

结果：文件虽存在，但访问路径对不上，于是返回 404。

#三、问题本质总结

⚠️ 因此，问题的本质不是 UnoCSS 的 bug，而是 SSR 构建产物的“目录不一致”造成的。

#四、解决方案

#✅ 方法：同步 UnoCSS 产物目录

构建完成后，将 dist/server/assets 下的 UnoCSS 产物复制到 dist/client/assets 中，让浏览器能够访问。

例如在 package.json 中添加一个同步脚本：

复制{
  "scripts": {
    "build": "astro build && node scripts/sync-unocss.js"
  }
}

scripts/sync-unocss.js 示例：

复制import fs from "node:fs";
import path from "node:path";

const src = path.resolve("dist/server/assets");
const dest = path.resolve("dist/client/assets");

if (fs.existsSync(src)) {
  fs.mkdirSync(dest, { recursive: true });
  for (const file of fs.readdirSync(src)) {
    const srcFile = path.join(src, file);
    const destFile = path.join(dest, file);
    fs.copyFileSync(srcFile, destFile);
  }
  console.log("✅ UnoCSS assets synced from server → client");
} else {
  console.log("⚠️ dist/server/assets not found");
}

这样在每次 SSR 构建后，reset 样式就能被正确同步到客户端目录中。

#五、验证结果

执行构建：

复制pnpm run build

查看输出：

• dist/client/assets/ 目录中应包含 index.*.css
• 启动 SSR 服务后，浏览器访问 /assets/index.*.css 不再 404
• 样式恢复正常显示 ✅

#六、延伸思考

1. 为什么 SSG 时没问题？
   因为 SSG 构建只产出客户端文件，UnoCSS 的 reset 样式也直接进入 dist/client。

2. 是否可以关闭 injectReset？
   如果你的项目中自行引入了 reset 样式文件，可禁用该选项以规避此问题。

3. 未来方向
   这个问题可能会在未来的 UnoCSS 或 Astro 适配器中被官方修复（例如通过合并产物目录）。

#七、结论

• 问题并非 UnoCSS 的“锅”，而是 Astro SSR 文件组织方式导致的访问不匹配。
• 解决方案是手动同步 UnoCSS 的 reset 样式文件，使其出现在客户端可访问路径中。
• 在 CI/CD 环境中，只需在构建后加一步同步脚本即可彻底解决。

参考配置：

复制// astro.config.mjs
import { defineConfig } from 'astro/config';
import UnoCSS from 'unocss/astro';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({
    mode: 'standalone',
  }),
  integrations: [
    UnoCSS({
      injectReset: true
    }),
  ],
});

🧩 总结一句话：

UnoCSS 把 reset 样式放在了服务端；
Astro 只让浏览器访问客户端；
我们只需把文件搬过去，一切就恢复正常。