Vue3项目实战：5分钟搞定Highlight.js代码高亮（附常见语言配置）
在Vue3项目中实现代码高亮显示是提升技术文档、博客或教学应用体验的关键细节。Highlight.js作为轻量级语法高亮工具，配合Vue3的插件系统，能快速实现专业级的代码展示效果。本文将手把手带你完成从零集成到多语言配置的全流程，解决实际开发中的版本选择、样式定制等核心问题。
1. 环境准备与基础安装
首先确保你的Vue3项目已经初始化完成。我们推荐使用pnpm作为包管理器（当然yarn或npm也同样适用），它能显著提升依赖安装效率。打开终端，执行以下命令安装核心依赖：
pnpm add highlight.js@11 @highlightjs/vue-plugin@2这里需要特别注意版本匹配问题：
- Vue3必须使用
@highlightjs/vue-plugin的2.x版本 highlight.js当前稳定版本为11.x，与Vue3插件完全兼容
常见踩坑点：很多开发者误装1.x版本的vue-plugin，这会导致Vue3项目运行时报错。如果不慎安装错误版本，先执行
pnpm remove @highlightjs/vue-plugin再重新安装正确版本。
2. 核心集成方案
在项目入口文件（通常是main.ts或main.js）中，我们需要完成三个关键步骤：
- 导入基础样式（推荐stackoverflow-light主题）
- 按需注册需要的编程语言
- 挂载Vue插件
以下是完整的配置示例：
// 样式导入（二选一） import 'highlight.js/styles/stackoverflow-light.css' // 浅色主题 // import 'highlight.js/styles/stackoverflow-dark.css' // 深色主题 // 核心库与插件 import hljs from 'highlight.js/lib/core' import hljsVuePlugin from '@highlightjs/vue-plugin' // 按需语言导入（示例包含6种常见语言） import javascript from 'highlight.js/lib/languages/javascript' import typescript from 'highlight.js/lib/languages/typescript' import java from 'highlight.js/lib/languages/java' import sql from 'highlight.js/lib/languages/sql' import xml from 'highlight.js/lib/languages/xml' import bash from 'highlight.js/lib/languages/bash' // 语言注册 hljs.registerLanguage('javascript', javascript) hljs.registerLanguage('typescript', typescript) hljs.registerLanguage('java', java) hljs.registerLanguage('sql', sql) hljs.registerLanguage('xml', xml) hljs.registerLanguage('bash', bash) // Vue挂载 const app = createApp(App) app.use(hljsVuePlugin) app.mount('#app')3. 组件化实战应用
集成完成后，我们可以在任意Vue组件中使用<highlightjs>标签。下面是一个带语言切换功能的增强型组件示例：
<template> <div class="code-container"> <div class="language-selector"> <select v-model="currentLanguage" @change="updateCode"> <option v-for="lang in languageOptions" :key="lang.value" :value="lang.value" > {{ lang.label }} </option> </select> </div> <highlightjs :language="currentLanguage" :code="currentCode" class="code-block" /> </div> </template> <script setup> import { ref } from 'vue' // 语言选项配置 const languageOptions = [ { value: 'javascript', label: 'JavaScript' }, { value: 'typescript', label: 'TypeScript' }, { value: 'java', label: 'Java' }, { value: 'sql', label: 'SQL' }, { value: 'bash', label: 'Bash' } ] // 示例代码库 const codeSamples = { javascript: `const greet = (name) => { console.log(\`Hello \${name}!\`) }`, typescript: `interface User { id: number name: string } const getUser = (id: number): User => ({ id, name: 'Test' })`, java: `public class Main { public static void main(String[] args) { System.out.println("Hello World"); } }`, sql: `SELECT users.name, orders.total FROM users JOIN orders ON users.id = orders.user_id WHERE orders.created_at > NOW() - INTERVAL '7 days'`, bash: `#!/bin/bash for file in *.txt; do mv "$file" "${file%.txt}.md" done` } const currentLanguage = ref('javascript') const currentCode = ref(codeSamples.javascript) const updateCode = () => { currentCode.value = codeSamples[currentLanguage.value] } </script> <style scoped> .code-container { border: 1px solid #eee; border-radius: 8px; overflow: hidden; } .language-selector { padding: 8px 12px; background: #f5f5f5; border-bottom: 1px solid #eee; } select { padding: 4px 8px; border-radius: 4px; border: 1px solid #ccc; } .code-block { margin: 0; padding: 12px; font-family: 'Fira Code', monospace; } </style>4. 高级配置与优化技巧
4.1 主题定制方案
Highlight.js提供了数十种内置主题，只需替换导入的样式文件即可切换：
// 其他流行主题选择 import 'highlight.js/styles/github.css' // GitHub风格 import 'highlight.js/styles/atom-one-dark.css' // Atom暗色主题 import 'highlight.js/styles/vs2015.css' // VS2015风格如需深度自定义，可以直接覆盖CSS变量：
/* 在全局样式中添加 */ .hljs { --hljs-bg: #f8f8f8; --hljs-color: #333; background: var(--hljs-bg); color: var(--hljs-color); } .hljs-keyword { color: #d73a49; } .hljs-string { color: #032f62; }4.2 性能优化策略
对于大型项目，建议采用以下优化方案：
- 动态语言加载：只在需要时加载语言包
const loadLanguage = async (lang) => { const module = await import(`highlight.js/lib/languages/${lang}`) hljs.registerLanguage(lang, module.default) }- CDN加速方案（适用于静态站点）：
<!-- 在public/index.html中添加 --> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/styles/stackoverflow-light.min.css" > <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/highlight.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/languages/javascript.min.js"></script>- 按需打包配置（vite示例）：
// vite.config.js export default defineConfig({ optimizeDeps: { include: [ 'highlight.js/lib/core', 'highlight.js/lib/languages/javascript', // 其他需要预构建的语言 ] } })4.3 Markdown集成方案
如果你使用Markdown编写文档，可以通过marked.js与highlight.js配合实现自动高亮：
import marked from 'marked' import hljs from 'highlight.js' marked.setOptions({ highlight: function(code, lang) { if (lang && hljs.getLanguage(lang)) { return hljs.highlight(lang, code).value } return hljs.highlightAuto(code).value } }) const htmlContent = marked(` \`\`\`javascript function test() { return "Hello World" } \`\`\` `)5. 常见问题解决方案
Q1：某些语言高亮效果不正常？
- 确认是否正确注册语言：
hljs.registerLanguage('python', python) - 检查语言名称是否与官方文档一致（区分大小写）
Q2：如何扩展自定义语言？
- 创建语言定义文件（如
myLang.js） - 实现语言语法规则
- 通过
registerLanguage注册
Q3：行号显示功能实现推荐使用css计数器方案：
.hljs { counter-reset: line; } .hljs .line::before { counter-increment: line; content: counter(line); display: inline-block; width: 2em; margin-right: 1em; color: #999; text-align: right; }配合代码预处理：
const codeWithLines = code.split('\n') .map(line => `<span class="line">${line}</span>`) .join('\n')Q4：SSR兼容性问题在Nuxt等SSR框架中使用时，需确保只在客户端执行：
onMounted(() => { if (process.client) { const hljs = require('highlight.js') // 初始化逻辑 } })
