Question

Astro 集成 为你项目中的每一个 .astro 文件和 框架组件 带来 Tailwind 的实用 CSS 类，同时支持 Tailwind 配置文件。

为什么是 Tailwind？

Tailwind 让你直接使用实用类而不是编写 CSS。这些实用类大多与某个 CSS 属性设置一一对应：例如，在一个元素上添加text-lg，相当于在 CSS 中设置font-size: 1.125rem。你也许会发现使用这些预定义的实用类更容易编写和维护你的样式！

如果你不喜欢这些预定义的设置，你可以根据你项目的设计要求定制 Tailwind 配置文件。例如，如果你设计中的“大文本”实际上是2rem，你可以将lg字体大小设置改为2rem。

Tailwind 也是为 React、Preact 或 Solid 组件添加样式的不错选择，这些组件不支持组件文件中的 <style> 标签。

注意：一般来说，我们不鼓励在同一个文件中同时使用 Tailwind 和另一种样式方法（例如，样式组件）。

安装

Astro 包含了一个 astro add 命令，用于自动设置官方集成。如果你愿意，可以改为手动安装集成。

在新的终端窗口中运行以下其中一个命令。

• npm
• pnpm
• Yarn

npx astro add tailwind

pnpm astro add tailwind

yarn astro add tailwind

如果你遇到任何问题，请随时在 GitHub 上向我们报告并尝试下面的手动安装步骤。

手动安装

首先，使用你的包管理器安装 @astrojs/tailwind 和 tailwindcss。

• npm
• pnpm
• Yarn

npm install @astrojs/tailwind tailwindcss

pnpm add @astrojs/tailwind tailwindcss

yarn add @astrojs/tailwind tailwindcss

然后，使用 integrations 属性将集成应用到你的 Astro 配置文件中：

astro.config.mjs

import { defineConfig } from 'astro/config';import tailwind from '@astrojs/tailwind';
export default defineConfig({
  // ...
  integrations: [tailwind()],
});

然后，在你的项目根目录下创建一个 tailwind.config.mjs 文件。你可以使用以下命令来生成一个基本的配置文件：

• npm
• pnpm
• Yarn

npx tailwindcss init

pnpm dlx tailwindcss init

yarn dlx tailwindcss init

最后，可将如下基本配置添加到你的 tailwind.config.mjs 文件中：

tailwind.config.mjs

/** @type {import('tailwindcss').Config} */
export default {  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  theme: {
    extend: {},
  },
  plugins: [],
};

使用

当你安装集成后，Tailwind 的实用类应该马上就可以使用了。前往 Tailwind 文档学习如何使用 Tailwind，如果你看到一个你想尝试的实用类，就把它添加到你项目的任何 HTML 元素中去吧！

Autoprefixer 也是在开发模式和生产模式下工作时自动设置的，所以 Tailwind 类将在旧的浏览器中工作。

配置

配置 Tailwind

如果你使用了快速安装，并且每个选项都选是，你会在你项目的根目录下看到一个 tailwind.config.mjs 文件。使用这个文件来修改你的 Tailwind 配置。你可以在 Tailwind 文档中学习如何使用这个文件来定制 Tailwind。

如果没有该文件，你可以在根目录下添加你自己的 tailwind.config.(js|cjs|mjs|ts|mts|cts) 文件，集成将使用其配置。如果你已经在另一个项目中配置了 Tailwind，并想把这些设置带到这个项目中来，这也不错。

配置集成

Astro Tailwind 集成处理 Astro 和 Tailwind 之间的通信，它有自己的设置。在 astro.config.mjs 文件（不是 Tailwind 配置文件）中改变这些，这里是你项目的集成设置所在。

configFile

以前在 @astrojs/tailwind v3 中被称为 config.path。请参阅 v4 更改日志 以更新你的配置。

如果你想使用不同的 Tailwind 配置文件，而不是默认的 tailwind.config.(js|cjs|mjs|ts|mts|cts)，请使用本集成的 configFile 选项指定该文件的位置。如果 configFile 是相对路径，则会相对于当前工作目录解析。

警告

不建议改变这一点，因为它可能导致与 Tailwind 整合的其他工具出现问题，比如官方的 Tailwind VSCode 扩展。

astro.config.mjs

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';


export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // 示例：为 Tailwind 配置文件提供一个自定义路径
      configFile: './custom-config.mjs',
    }),
  ],
});

applyBaseStyles

以前在 @astrojs/tailwind v3 中被称为 config.applyBaseStyles。请参阅 v4 更改日志以更新你的配置。

默认情况下，该集成在你项目的每个页面上都导入一个基本的 base.css 文件。这个基本的 CSS 文件包括三个主要的 @tailwind 指令：

base.css

/* 集成的默认注入的 base.css 文件 */
@tailwind base;
@tailwind components;
@tailwind utilities;

要禁用这个默认行为，请将 applyBaseStyles 设置为 false。如果你需要定义你自己的 base.css 文件（例如包括一个@layer 指令），这可能很有用。如果你不希望 base.css 被导入你的项目的每一个页面，这也很有用。

astro.config.mjs

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';


export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // 示例：在每个页面上禁用注入基本的`base.css`导入。
      // 如果你需要定义或导入你自己的 "base.css"，这很有用。
      applyBaseStyles: false,
    }),
  ],
});

你现在可以导入你自己的 base.css 作为本地样式表 。

nesting

设置为 true 以应用 tailwindcss/nesting PostCSS 插件，这样你就可以在兼容 Tailwind 语法的基础上编写嵌套的 CSS 声明。此选项默认为 false。

astro.config.mjs

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';


export default defineConfig({
  integrations: [
    tailwind({
      // 示例：允许在 Tailwind 的语法基础上编写嵌套的 CSS 声明
      nesting: true,
    }),
  ],
});

例子

• Astro Tailwind Starter 为你提供一个基础的、使用 Tailwind 进行样式设计的可运行项目
• Astro 的主页使用 Tailwind。查看其 Tailwind 配置文件或示例组件
• Astro Ink、Sarissa Blog、Astro Tech Blog和 Creek 主题使用 Tailwind 进行样式设计
• 浏览 GitHub 上的 Astro Tailwind 项目以获得更多的例子！

故障排除

使用 @apply 指令时提示类不存在

当在 Astro、Vue、Svelte 或其他组件集成的 <style> 标签中使用 @apply 指令时，它可能会产生关于你的自定义 Tailwind 类不存在的错误，并导致你的构建失败。

error   The `text-special` class does not exist. If `text-special` is a custom class, make sure it is defined within a `@layer` directive.

通过在你的 Tailwind 配置中添加一个插件来定义你的自定义样式来修复它，而不是在全局样式表中使用@layer指令，添加如下内容：

tailwind.config.mjs

export default {
  // ...
  plugins: [
    function ({ addComponents, theme }) {
      addComponents({
        '.btn': {
          padding: theme('spacing.4'),
          margin: 'auto',
        },
      });
    },
  ],
};

基于类的修改器不能与 @apply 指令一起工作

某些带有修饰符的 Tailwind 类依赖于跨多个元素的组合类。例如，group-hover:text-gray 编译为 .group:hover .text-gray。当这与 Astro <style> 标签中的 @apply 指令一起使用时，编译后的样式会从构建输出中删除，因为它们与 .astro 文件中的任何标记不匹配。同样的问题也可能发生在支持范围样式的框架组件中，如 Vue 和 Svelte。

为了解决这个问题，你可以使用内联类来代替：

<p class="text-black group-hover:text-gray">Astro</p>

其他

• 如果你的安装似乎不成功，尝试重新启动开发服务器。
• 如果你编辑并保存了一个文件，但没有看到你的网站有相应的更新，试着刷新页面。
• 如果刷新页面并没有更新你的预览，或者新的安装似乎没有效果，那么就重新启动开发服务器。

如需帮助，请查看 Discord 上的 #support 频道。我们友好的支持小组成员将在这里提供帮助！

你也可以查看我们的 Astro 集成文档，了解更多关于集成的信息。

更多集成

UI 框架

• 

  @astrojs/alpinejs

• 

  @astrojs/lit

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSR 适配器

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

其他集成

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind

Recipes