如何配置Astro以将CSS与HTML分离输出？

问题描述 #

默认情况下，Astro会将CSS复制并注入到每个HTML文件的<style>标签中。我有一个小型网站，仅包含几个页面和少量CSS：

• CSS主要存放在外部文件src/style/base.css中
• 部分样式位于跨页面复用的组件内

目前所有样式都被打包到<head>内的<style>元素中，导致无法使用Astro Purgecss、uCSS、UnCSS这类工具——它们仅在HTML与CSS分文件存放时才能生效。

我习惯保留旧的视觉效果样式以便随时复用，依赖构建工具移除未使用的样式，现在需要配置Astro输出单个CSS文件的方法。

解决方案 #

1. 修改Astro配置文件 #

在项目根目录的astro.config.mjs中添加Vite构建配置，禁用CSS代码分割并指定单个CSS文件的输出规则：

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    build: {
      // 禁用CSS代码分割，合并所有CSS为单个文件
      cssCodeSplit: false,
      rollupOptions: {
        output: {
          // 自定义CSS文件的输出路径与命名，可按需修改
          assetFileNames: 'assets/style.[hash].css',
        },
      },
    },
  },
});

2. 全局引入基础CSS #

在根布局组件（通常是src/layouts/Layout.astro）中引入你的全局CSS文件，组件内的样式会自动合并到最终的单个CSS文件中：

---
// 引入全局基础样式
import '../style/base.css';
---
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>你的网站标题</title>
</head>
<body>
  <!-- 页面内容插槽 -->
  <slot />
</body>
</html>

3. 验证构建结果 #

执行npm run build完成构建后，查看dist目录：

• 所有CSS会被合并为你指定的单个文件
• 每个HTML文件会通过<link rel="stylesheet">标签引入该CSS文件

此时HTML与CSS已分离存放，即可正常使用PurgeCSS等工具进行未使用样式的清理。

内容的提问来源于stack exchange，提问作者dotnetCarpenter