Astro项目中shikiji-transformers无法在MDX内容生效的问题

核心问题分析 #

你的配置存在两个关键问题：

• MDX未单独配置shiki转换器：@astrojs/mdx会独立处理MDX文件的markdown规则，全局的markdown.shikiConfig不会自动继承到MDX的处理逻辑中。
• 错误导入所有转换器：直接传递Object.values(transformers)会引入冗余甚至冲突的转换器，且TransformerNotationHighlight是工厂函数，需要调用生成实例才能生效。

修复步骤 #

1. 分别配置Markdown和MDX的shiki选项 #

修改Astro配置文件，给MDX集成单独设置与全局Markdown一致的shiki配置：

import { defineConfig } from "astro/config";
import mdx from "@astrojs/mdx";
import { TransformerNotationHighlight } from 'shikiji-transformers';

export default defineConfig({
  site: "https://www.sanderboer.nl/",
  prefetch: true,
  // 处理普通Markdown文件
  markdown: {
    syntaxHighlight: "shiki",
    shikiConfig: {
      transformers: [TransformerNotationHighlight()]
    },
  },
  integrations: [
    mdx({
      // 单独处理MDX文件的markdown规则
      markdown: {
        syntaxHighlight: "shiki",
        shikiConfig: {
          transformers: [TransformerNotationHighlight()]
        },
      }
    }),
  ],
});

2. 仅导入并初始化需要的转换器 #

不要一次性导入所有转换器，只引入TransformerNotationHighlight并调用它生成可用实例——这是很多新手容易忽略的点，该转换器并非直接可用的对象，必须通过函数调用初始化。

3. 验证代码块格式 #

确保你的代码块是在MDX/Markdown文件中，且注释格式严格符合要求：

export function foo() {
  console.log('Highlighted') // [!code highlight]
}

注意：注释必须为单行注释，[!code highlight]需紧跟在//后，无多余空格。

4. 版本兼容性确认 #

你的依赖版本是兼容的：Astro 4.x内置的shiki为v1.x版本，shikiji-transformers@0.10.2恰好适配该版本，无需调整依赖版本。

验证方式 #

修改配置后重启Astro开发服务器，通过浏览器开发者工具检查目标代码行，若成功生效，该行会被添加highlighted类名，同时呈现对应的高亮样式。

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