TailwindCSS Typography 插件怎么用才稳？

Typography 插件适合解决什么问题？

如果页面里有 Markdown、CMS 富文本、博客正文或文档内容，直接用 Tailwind 原子类逐个给 h2、p、ul、code、blockquote 写样式会很累。@tailwindcss/typography 的作用就是给这类“长文本内容”提供一套默认排版样式。

它的核心类名是 prose。把 prose 加到内容容器上，容器里的标题、段落、列表、链接、代码、引用等元素都会获得更适合阅读的样式。

html
<article class="prose">
  <h2>标题</h2>
  <p>这里是一段来自 Markdown 或 CMS 的正文。</p>
  <a href="/docs">查看文档</a>
</article>

这种写法特别适合不方便逐个控制标签的内容来源，比如 Markdown 渲染后的文章页、CMS 后台录入的富文本、文档站正文、产品介绍页里的长文案模块。用户生成内容也可以用，但前提是已经做好 XSS 过滤。

Tailwind v3 怎么安装和配置？

在 Tailwind v3 中，Typography 是官方插件，但需要手动安装并加入 tailwind.config.js。

bash
npm install -D @tailwindcss/typography

然后在配置里引入插件：

js
// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './content/**/*.{md,mdx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [require('@tailwindcss/typography')],
}

如果文章内容在 content、posts、docs 这类目录里，记得把路径加入 content 扫描范围。否则 Tailwind 可能不会生成你在模板或 MDX 里用到的类名。

Tailwind v4 怎么使用？

Tailwind v4 的配置方式更偏向 CSS 入口文件。Typography 插件可以通过 @plugin 引入：

css
@import "tailwindcss";
@plugin "@tailwindcss/typography";

如果项目已经升级到 v4，就不要照搬 v3 的 plugins: [require(...)] 写法。实际项目里最稳的做法是先确认当前 Tailwind 版本，再选对应配置方式。

prose 类怎么控制字号和宽度？

prose 默认会限制正文宽度，让长段落更好读。这个限制对文章页通常是好事，但对后台预览、全宽文档、落地页模块可能会显得太窄。

html
<article class="prose prose-lg max-w-none">
  ...
</article>

常用类：

类名	作用
prose	启用 Typography 默认排版
prose-sm	更小的正文排版
prose-base	默认尺寸
prose-lg	更适合文章页的稍大字号
prose-xl	更醒目的长文排版
max-w-none	取消 Typography 默认最大宽度

如果是博客详情页，prose prose-lg 通常就够用；如果页面外层已经控制了宽度，可以加上 max-w-none，避免被插件再限制一次。

深色模式怎么处理？

Typography 插件内置了深色模式反转样式，常用类是 dark:prose-invert。

html
<article class="prose prose-slate dark:prose-invert">
  ...
</article>

prose-invert 会让正文、标题、引用、代码等颜色更适合深色背景。如果项目本身使用 Tailwind 的 dark 类模式，外层切换 dark 后，这段内容就会自动适配。

prose-slate、prose-zinc 这些颜色类有什么用？

Typography 提供了一组颜色主题，常见的有 prose-slate、prose-gray、prose-zinc、prose-neutral、prose-stone。

html
<article class="prose prose-slate">
  ...
</article>

它们会影响正文、标题、引用、边框、代码等元素的整体色调。一般来说，prose-slate 偏清爽，适合技术文章；prose-zinc 和 prose-neutral 更中性，适合后台、文档站或产品页。

颜色类不建议频繁混用。一个站点最好统一一种正文色调，否则不同文章页看起来会像拼在一起的。

如何单独修改链接、代码和图片样式？

Typography 插件支持元素修饰符，格式通常是 prose-元素名:工具类。

html
<article
  class="prose prose-slate max-w-none
         prose-a:text-blue-600 prose-a:no-underline hover:prose-a:underline
         prose-code:rounded prose-code:bg-slate-100 prose-code:px-1
         prose-img:rounded-xl prose-img:shadow-sm"
>
  ...
</article>

常用元素修饰符包括 prose-a:*、prose-headings:*、prose-h2:*、prose-p:*、prose-ul:*、prose-li:*、prose-code:*、prose-pre:*、prose-blockquote:*、prose-img:*。

这比在全局 CSS 里写 .article a {} 更可控，也更符合 Tailwind 的写法。

not-prose 什么时候用？

如果 prose 容器里有一块内容不想被 Typography 接管，可以给那块内容加 not-prose。

html
<article class="prose">
  <p>这段会使用 Typography 样式。</p>

  <div class="not-prose">
    <button class="rounded bg-blue-600 px-4 py-2 text-white">
      这个按钮不受 prose 影响
    </button>
  </div>
</article>

典型场景是文章正文里嵌入组件，比如按钮、卡片、提示框、交互式 Demo。它们本来就有自己的样式，不应该被 prose 的段落、链接、列表规则改掉。

有一个细节要注意：not-prose 里面不要再嵌套新的 prose，这类嵌套在实际项目里容易出现样式不符合预期。需要新的长文区域时，最好把它放到外层结构里单独处理。

如何自定义 Typography 样式？

如果只是改几个元素，优先用 prose-a:*、prose-code:* 这类修饰符。需要站点级统一样式时，再考虑在主题里扩展 typography。

Tailwind v3 可以在 tailwind.config.js 里这样写：

js
module.exports = {
  theme: {
    extend: {
      typography: ({ theme }) => ({
        DEFAULT: {
          css: {
            '--tw-prose-links': theme('colors.blue.600'),
            '--tw-prose-bold': theme('colors.slate.900'),
            h2: {
              scrollMarginTop: '5rem',
            },
            code: {
              fontWeight: '500',
            },
          },
        },
      }),
    },
  },
  plugins: [require('@tailwindcss/typography')],
}

Typography 内部大量使用 CSS 变量，例如 --tw-prose-body、--tw-prose-headings、--tw-prose-links、--tw-prose-code。改变量通常比硬改一堆选择器更稳。

在 Markdown 或 CMS 页面里怎么落地？

真实项目里，Typography 最常见的用法是包住渲染后的 HTML。

tsx
export function Article({ html }: { html: string }) {
  return (
    <article
      className="prose prose-slate prose-lg max-w-none dark:prose-invert"
      dangerouslySetInnerHTML={{ __html: html }}
    />
  )
}

如果内容来自 CMS 或用户输入，重点不是 prose，而是安全处理。渲染前要做 HTML 清洗，避免把恶意脚本一起渲染出来。Typography 只负责排版，不负责内容安全。

MDX 场景会更灵活一些。普通正文交给 prose，交互组件放进 not-prose，这样排版和组件样式不互相打架。

常见问题怎么避免？

正文太窄

这是 prose 默认最大宽度导致的。页面外层已经控制宽度时，给正文加 max-w-none。

html
<article class="prose max-w-none">
  ...
</article>

深色模式下颜色不对

检查是否加了 dark:prose-invert，以及项目的深色模式是否真的生效。只写 prose-invert 会让它一直使用暗色排版，不一定符合预期。

自定义类没有生成

先看 content 扫描路径。Markdown、MDX、CMS 模板、组件目录如果没被扫描，Tailwind 就可能删掉没识别到的类。

对于动态拼接类名也要小心：

js
const size = 'lg'
const className = `prose-${size}`

这种写法可能不会被 Tailwind 正确识别。更稳的方式是写完整类名，或在配置里 safelist。

组件样式被 prose 改乱

在文章里嵌按钮、卡片、表单时，用 not-prose 包起来。不要让 Typography 去管理本来就有设计规范的组件。

prose 嵌套 prose

尽量避免。外层已经是长文排版时，里面再放一个 prose，可能会出现间距、字体、颜色重复叠加的问题。需要分区时，用普通容器拆开更清楚。

一套比较稳的默认写法

技术文章或文档页可以从下面这套类名开始：

html
<article
  class="prose prose-slate prose-lg max-w-none dark:prose-invert
         prose-a:text-blue-600 prose-a:no-underline hover:prose-a:underline
         prose-code:rounded prose-code:bg-slate-100 prose-code:px-1
         dark:prose-code:bg-slate-800"
>
  ...
</article>

这套写法覆盖了几个关键点：正文排版、阅读尺寸、深色模式、全宽控制、链接样式和行内代码样式。后续如果要调品牌色或标题间距，再放到主题配置里统一处理。

Typography 插件最适合管理不可控的长文本内容。能用 prose 解决的，不必给每个标签手写一遍样式；不该被它接管的组件，就用 not-prose 隔开。把这条边界分清，文章页和文档页的排版会省很多事。