Nuxt Content 代码高亮功能失效问题排查指南

问题现象描述

在使用 Nuxt Content 模块时，开发者发现 Markdown 文件中的代码块无法正常显示语法高亮效果。具体表现为代码块被渲染为普通文本，没有应用 Shiki 高亮相关的 CSS 类名。

典型配置示例

开发者通常会按照官方文档配置高亮主题：

content: {
  highlight: {
    theme: {
      default: "github-light",
      dark: "github-dark",
      sepia: "monokai",
    },
  },
},

问题排查过程

1. 基础检查：首先确认 Nuxt Content 模块已正确安装和配置，代码块语法符合规范。

2. 网络请求分析：通过浏览器开发者工具检查网络请求，发现 /api/_mdc 接口未被正常调用。

3. 中间件影响：深入排查后发现项目中存在全局中间件，该中间件的访问限制规则过于严格，导致 /api/_mdc 接口请求被拦截。

解决方案

1. 调整中间件规则：修改中间件配置，将 /api/_mdc 路径加入白名单。

2. 验证修复：清除缓存后重新加载页面，确认代码高亮功能恢复正常。

经验总结

1. API 依赖：Nuxt Content 的代码高亮功能依赖 /api/_mdc 接口，任何拦截该接口的中间件都会导致高亮失效。

2. 常见陷阱：类似问题也出现在使用 nuxt-security 等安全模块时，特别是配置了 basic-auth 认证的情况。

3. 调试技巧：可以通过修改 node_modules 中的源码添加调试日志（如 rehype-nuxt.js 文件），但需注意这仅适用于开发调试。

最佳实践建议

1. 中间件设计：开发全局中间件时应考虑 Nuxt 内部 API 路径的特殊性。

2. 文档补充：建议在项目文档中明确说明 /api/_mdc 和 /api/_content 的依赖关系。

3. 渐进式配置：添加新中间件时采用逐步收紧的策略，避免一次性设置过于严格的规则。

技术原理延伸

Nuxt Content 的代码高亮功能是通过 Shiki 实现的，其工作流程包括：

1. 客户端检测到代码块
2. 向 /api/_mdc 发送请求获取高亮处理结果
3. 将返回的 HTML 片段和 CSS 类名应用到页面

这一设计实现了服务端渲染的高亮处理，同时保持了客户端的灵活性。理解这一流程有助于快速定位类似问题。