修复 Astro 中 markdown.remarkPlugins 弃用警告

什么是弃用（Deprecation）警告？#

在启动 Astro 开发服务器（astro dev）或构建生产项目（astro build）时，你可能会在终端中看到如下黄色警告信息：

[astro] `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` are deprecated. Pass them to `unified({...})` from `@astrojs/markdown-remark` directly instead.

如果你的项目使用了 Remark 或 Rehype 插件（例如用于数学公式的 remark-math、rehype-katex，或者自动生成标题 ID 的 rehypeHeadingIds），Astro 正在提醒你：根级别的 Markdown 插件配置方式已被弃用，取而代之的是全新的独立处理器架构（markdown.processor）。

本文将通俗解析这一变更的设计初衷、新系统的工作原理，以及如何在两分钟内优雅完成配置迁移。

为什么 Astro 要重构 Markdown API？#

通俗比喻（ELI5）#

把 Astro 想象成一个现代化的厨房：

• 过去：Astro 厨房的墙上被焊死了一台特定的烤箱（Unified/Remark/Rehype 引擎）。如果你想调节烘焙温度或增加烤盘插件（remarkPlugins），只能直接在厨房的总控制面板（markdown.remarkPlugins）上接线。
• 现在：Astro 将烤箱位升级为了可插拔的标准卡槽（markdown.processor）。
  • 如果你喜爱庞大的 Remark/Rehype 插件生态，可以插入 Unified 烤箱（@astrojs/markdown-remark）。
  • 如果你追求极致的构建性能，可以插入基于 Rust 打造的超高速 Sätteri 烤箱（@astrojs/markdown-satteri）。

由于 Remark 和 Rehype 插件只属于 Unified 引擎独有的生态，把它们放在 Astro 全局配置中不再符合模块化架构设计。因此，Astro 要求将它们统一定义在 unified({...}) 处理器内部。

flowchart TD
    subgraph Legacy["旧架构（Legacy Architecture）"]
        L_Config["astro.config.mjs (markdown.remarkPlugins / rehypePlugins)"] --> L_Engine["Astro 核心（内置固定的 Unified 解析器）"]
    end

    subgraph Modern["新处理器架构（v6.4+ / v7+）"]
        M_Config["astro.config.mjs (markdown.processor)"]
        M_Config --> M_Choice{"选择 Markdown 处理器"}
        M_Choice -->|unified: remarkPlugins, rehypePlugins| M_Unified["@astrojs/markdown-remark (Unified / Remark / Rehype)"]
        M_Choice -->|satteri: mdastPlugins, hastPlugins| M_Satteri["@astrojs/markdown-satteri (Rust 编写的 Sätteri 引擎)"]
    end

架构演进的核心收益#

1. 核心解耦：Astro 核心不再与 Unified 强绑定，不需要该生态的项目能拥有更轻量的构建体积。
2. 原生 Rust 编译器支持：Astro v7+ 引入 Sätteri 作为默认的零配置 Markdown 处理器，构建速度获得成倍提升。
3. 清晰的配置作用域：各处理器专属选项（remarkPlugins、rehypePlugins、gfm、smartypants）被集中约束在各自的声明块中。

修复步骤（Step-by-Step）#

第一步：安装 @astrojs/markdown-remark#

确保项目中已安装官方 @astrojs/markdown-remark 包：

bun add @astrojs/markdown-remark
# 或
npm install @astrojs/markdown-remark
# 或
pnpm add @astrojs/markdown-remark

第二步：更新 astro.config.ts（或 astro.config.mjs）#

从 @astrojs/markdown-remark 导入 unified，并将插件迁移至 markdown.processor 内：

import { defineConfig } from 'astro/config';
import { unified, rehypeHeadingIds } from '@astrojs/markdown-remark';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [[rehypeKatex, {}], rehypeHeadingIds],
    smartypants: true,
    processor: unified({
      remarkPlugins: [remarkMath],
      rehypePlugins: [
        [rehypeKatex, {}],
        rehypeHeadingIds,
      ],
      gfm: true,
      smartypants: true,
    }),
    // 代码高亮配置依然保留在 markdown 根级
    shikiConfig: {
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
    },
  },
});

[!NOTE] 请注意，代码语法高亮 shikiConfig 依旧直接位于 markdown: { ... } 内部。只有 Markdown 解析相关的选项（remarkPlugins、rehypePlugins、remarkRehype、gfm、smartypants）需要移入 processor: unified({ ... })。

unified({...}) 常用配置选项#

传递给 unified({...}) 的常用配置项一览：

示例：自定义脚注（Footnotes）配置#

如果你之前使用 markdown.remarkRehype 自定义了脚注返回链接，直接移入 unified({...}) 即可：

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';

export default defineConfig({
  markdown: {
    processor: unified({
      remarkRehype: {
        footnoteBackContent: '↩',
        footnoteLabel: '脚注',
      },
    }),
  },
});

备选方案：使用基于 Rust 的 Sätteri 处理器#

如果你的项目无需现有的 Remark/Rehype 插件，且希望最大化构建速度，可选用 Sätteri 处理器：

bun add @astrojs/markdown-satteri

在 astro.config.ts 中配置：

import { defineConfig } from 'astro/config';
import { satteri } from '@astrojs/markdown-satteri';

export default defineConfig({
  markdown: {
    processor: satteri({
      features: {
        gfm: true,
        smartPunctuation: true,
      },
    }),
  },
});

[!TIP] Sätteri 使用为其专有 AST 编写的 mdastPlugins 和 hastPlugins，不兼容 npm 上的传统 Remark/Rehype 插件。若需要 remark-math 等生态插件，建议保留 processor: unified({...})。

第三方集成兼容性#

像 astro-mermaid、@astrojs/mdx 等现代集成都会自动检测 config.markdown.processor。当你配置了 processor: unified({...}) 时，这些集成会自动将必需的转换器安全注入到现有处理器管道中，无须担心兼容冲突。

bun run check
bun run build

完成修改后，再次执行构建命令即可享受零警告的干净终端输出。

总结#

• 警告原因：Astro 弃用了根层级的 markdown.remarkPlugins、markdown.rehypePlugins 和 markdown.remarkRehype。
• 解决方法：从 @astrojs/markdown-remark 导入 unified，并将插件包裹在 markdown.processor: unified({...}) 中。
• 配置边界：shikiConfig 依旧保持在 markdown 层，仅解析器选项进入 unified({...})。

参考资料#

• Astro 官方文档 — Markdown in Astro ↗
• Astro 配置参考 — markdown.processor ↗
• @astrojs/markdown-remark Package on npm ↗
• Sätteri 官方文档 ↗
• Unified.js 官方网站 ↗