Next.js博客项目中Markdown使用highlight.js代码高亮不生效问题

核心原因 #

你当前遇到的样式不生效，本质是两种常见场景导致的：

1. remark转换阶段没有注入highlight.js所需的高亮样式类
2. 客户端执行高亮的时机不对，或者类名匹配规则不匹配

方案1：服务端预渲染高亮（推荐适配Next.js SSG/SSR场景） #

这种方案直接在Markdown转HTML的阶段就完成高亮类注入，不需要客户端额外运行JS，性能更好也不会有hydration问题。

• 第一步：安装依赖
  npm install remark-highlight.js highlight.js
• 第二步：调整remark转换配置，注意插件顺序必须把高亮插件放在remark-html之前
  示例代码：

import remark from 'remark'
import remarkHtml from 'remark-html'
import remarkHighlight from 'remark-highlight.js'

// 你的Markdown转HTML方法
const mdToHtml = async (mdContent) => {
  const res = await remark()
    .use(remarkHighlight) // 高亮插件在前
    .use(remarkHtml)
    .process(mdContent)
  return res.toString()
}

• 第三步：引入highlight.js主题样式
  在_app.js或者对应文章页面引入你需要的主题CSS即可，比如：
  import 'highlight.js/styles/github-dark.css'

方案2：客户端手动触发高亮 #

如果要保留客户端执行高亮的逻辑，需要调整执行时机适配Next.js的渲染逻辑：

import { useEffect } from 'react'
import hljs from 'highlight.js'
import 'highlight.js/styles/github.css'

export default function ArticlePage({ htmlContent }) {
  // 等待DOM渲染完成后再执行高亮
  useEffect(() => {
    hljs.highlightAll()
  }, [htmlContent]) // 文章内容变化时重新执行高亮

  return <div dangerouslySetInnerHTML={{ __html: htmlContent }} />
}

常见排查点 #

• 打开浏览器控制台查看code标签元素，确认是否已经生成hljs类以及对应语言的高亮类，如果没有生成就是插件配置顺序错误
• 检查样式是否被全局样式覆盖：如果hljs的样式被划了删除线，说明你全局的pre/code样式优先级更高，可以给你的文章容器加自定义类提升权重，比如：

.markdown-container pre code.hljs {
  background: #0d1117;
  color: #c9d1d9;
}

• 确认你引入的主题CSS路径正确，不同版本的highlight.js主题路径可能存在差异，可在node_modules/highlight.js/styles目录下核对你需要的主题文件名。

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