@astrojs/ tailwind

这个 Astro 整合为项目中的每个 .astro 文件和框架组件带来了 Tailwind 的实用 CSS 类，并支持 Tailwind 配置文件。

¥This Astro integration brings Tailwind’s utility CSS classes to every .astro file and framework component in your project, along with support for the Tailwind configuration file.

为什么选择 Tailwind？

¥Why Tailwind?

Tailwind 允许你使用实用程序类而不是编写 CSS。这些实用程序类大多与特定 CSS 属性设置是一对一的：例如，将 text-lg 添加到元素相当于在 CSS 中设置 font-size: 1.125rem。你可能会发现使用这些预定义的实用程序类可以更轻松地编写和维护你的样式！

¥Tailwind lets you use utility classes instead of writing CSS. These utility classes are mostly one-to-one with a certain CSS property setting: for example, adding the text-lg to an element is equivalent to setting font-size: 1.125rem in CSS. You might find it easier to write and maintain your styles using these predefined utility classes!

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

¥If you don’t like those predefined settings, you can customize the Tailwind configuration file to your project’s design requirements. For example, if the “large text” in your design is actually 2rem, you can change the lg fontSize setting to 2rem.

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

¥Tailwind is also a great choice to add styles to React, Preact, or Solid components, which don’t support a <style> tag in the component file.

注意：通常不鼓励在同一文件中同时使用 Tailwind 和其他样式方法（例如样式组件）。

¥Note: it’s generally discouraged to use both Tailwind and another styling method (e.g. Styled Components) in the same file.

安装

¥Installation

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

¥Astro includes an astro add command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.

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

¥Run one of the following commands in a new terminal window.

npx astro add tailwind

pnpm astro add tailwind

yarn astro add tailwind

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

¥If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.

手动安装

¥Manual Install

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

¥First, install the @astrojs/tailwind and tailwindcss packages using your package manager.

npm install @astrojs/tailwind tailwindcss

pnpm add @astrojs/tailwind tailwindcss

yarn add @astrojs/tailwind tailwindcss

然后，使用 integrations 属性将集成应用于 Astro 配置文件：

¥Then, apply the integration to your Astro config file using the integrations property:

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

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

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

¥Then, create a tailwind.config.mjs file in your project’s root directory. You can use the following command to generate a basic configuration file for you:

npx tailwindcss init

pnpm dlx tailwindcss init

yarn dlx tailwindcss init

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

¥Finally, add this basic configuration to your tailwind.config.mjs file:

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

用法

¥Usage

当你安装集成时，Tailwind 的实用程序类应该立即准备就绪。前往 Tailwind 文档了解如何使用 Tailwind，如果你看到想要尝试的实用程序类，请将其添加到项目的任何 HTML 元素中！

¥When you install the integration, Tailwind’s utility classes should be ready to go right away. Head to the Tailwind docs to learn how to use Tailwind, and if you see a utility class you want to try, add it to any HTML element to your project!

在开发模式下工作以及生产构建时，自动前缀器也会自动设置，因此 Tailwind 类将在较旧的浏览器中工作。

¥Autoprefixer is also set up automatically when working in dev mode, and for production builds, so Tailwind classes will work in older browsers.

配置

¥Configuration

配置 Tailwind

¥Configuring Tailwind

如果你使用“快速安装”说明并对每个提示都选择“是”，你将在项目的根目录中看到一个 tailwind.config.mjs 文件。使用此文件进行 Tailwind 配置更改。你可以了解如何使用此文件在 Tailwind 文档中.conf 自定义 Tailwind。

¥If you used the Quick Install instructions and said yes to each prompt, you’ll see a tailwind.config.mjs file in your project’s root directory. Use this file for your Tailwind configuration changes. You can learn how to customize Tailwind using this file in the Tailwind docs.

如果不存在，请将你自己的 tailwind.config.(js|cjs|mjs|ts|mts|cts) 文件添加到根目录，集成将使用其配置。如果你已经在另一个项目中配置了 Tailwind，并且希望将这些设置带到此项目中，那么这可能会很棒。

¥If it isn’t there, you add your own tailwind.config.(js|cjs|mjs|ts|mts|cts) file to the root directory and the integration will use its configurations. This can be great if you already have Tailwind configured in another project and want to bring those settings over to this one.

配置集成

¥Configuring the Integration

Astro Tailwind 集成处理 Astro 和 Tailwind 之间的通信，并且它有自己的选项。在 astro.config.mjs 文件（不是 Tailwind 配置文件）中更改这些内容，该文件是项目集成设置所在的位置。

¥The Astro Tailwind integration handles the communication between Astro and Tailwind and it has its own options. Change these in the astro.config.mjs file (not the Tailwind configuration file) which is where your project’s integration settings live.

configFile

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

¥Previously known as config.path in @astrojs/tailwind v3. See the v4 changelog for updating your config.

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

¥If you want to use a different Tailwind configuration file instead of the default tailwind.config.(js|cjs|mjs|ts|mts|cts), specify that file’s location using this integration’s configFile option. If configFile is relative, it will be resolved relative to the current working directory.

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

export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // Example: Provide a custom path to a Tailwind config file
      configFile: './custom-config.mjs',
    }),
  ],
});

applyBaseStyles

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

¥Previously known as config.applyBaseStyles in @astrojs/tailwind v3. See the v4 changelog for updating your config.

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

¥By default, the integration imports a basic base.css file on every page of your project. This basic CSS file includes the three main @tailwind directives:

/* The integration's default injected base.css file */
@tailwind base;
@tailwind components;
@tailwind utilities;

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

¥To disable this default behavior, set applyBaseStyles to false. This can be useful if you need to define your own base.css file (to include a @layer directive, for example). This can also be useful if you do not want base.css to be imported on every page of your project.

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

export default defineConfig({
  // ...
  integrations: [
    tailwind({
      // Example: Disable injecting a basic `base.css` import on every page.
      // Useful if you need to define and/or import your own custom `base.css`.
      applyBaseStyles: false,
    }),
  ],
});

你现在可以 import your own base.css as a local stylesheet。

¥You can now import your own base.css as a local stylesheet.

nesting

设置 true 以应用 tailwindcss/nesting PostCSS 插件，以便你可以编写嵌套的 CSS 声明以及 Tailwind 的语法。默认情况下，此选项为 false。

¥Set true to apply the tailwindcss/nesting PostCSS plugin so you can write nested CSS declarations alongside Tailwind’s syntax. This option is false by default.

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

export default defineConfig({
  integrations: [
    tailwind({
      // Example: Allow writing nested CSS declarations
      // alongside Tailwind's syntax
      nesting: true,
    }),
  ],
});

示例

¥Examples

Astro Tailwind 启动器可让你为使用 Tailwind 进行样式的项目提供基础并运行
Astro 的主页使用 Tailwind。查看它的 Tailwind 配置文件或示例组件
Astro 墨水、萨丽莎博客、Astro 技术博客和溪主题使用 Tailwind 进行样式设置
浏览 GitHub 上的 Astro Tailwind 项目了解更多示例！

故障排除

¥Troubleshooting

`@apply` 指令中不存在类

¥Class does not exist with @apply directives

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

¥When using the @apply directive in an Astro, Vue, Svelte, or another component integration’s <style> tag, it may generate errors about your custom Tailwind class not existing and cause your build to fail.

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

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

¥Instead of using @layer directives in a global stylesheet, define your custom styles by adding a plugin to your Tailwind config to fix it:

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

基于类的修饰符不适用于 `@apply` 指令

¥Class-based modifiers do not work with @apply directives

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

¥Certain Tailwind classes with modifiers rely on combining classes across multiple elements. For example, group-hover:text-gray compiles to .group:hover .text-gray. When this is used with the @apply directive in Astro <style> tags, the compiled styles are removed from the build output because they do not match any markup in the .astro file. The same issue may also happen in framework components that support scoped styles like Vue and Svelte.

要解决此问题，你可以使用内联类：

¥To fix this, you can use inline classes instead:

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

其他的

¥Others

如果你的安装似乎不起作用，请尝试重新启动开发服务器。
如果你编辑并保存文件但没有看到你的网站相应更新，请尝试刷新页面。
如果刷新页面没有更新预览，或者新安装似乎不起作用，请重新启动开发服务器。

如需帮助，请查看 Discord 上的 #support 通道。我们友好的支持小队成员随时为你提供帮助！

¥For help, check out the #support channel on Discord. Our friendly Support Squad members are here to help!

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

¥You can also check our Astro Integration Documentation for more on integrations.

@astrojs/ tailwind

为什么选择 Tailwind？

安装

手动安装

用法

配置

配置 Tailwind

配置集成

configFile

applyBaseStyles

nesting

示例

故障排除

`@apply` 指令中不存在类

基于类的修饰符不适用于 `@apply` 指令

其他的

更多集成

前端框架

@astrojs/alpinejs

@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