我去年帮做Python教程的朋友调过这个配置，他之前的文章代码块丑得让读者直接划走，改完之后评论区全是“终于能舒服看代码了”，3个月内教程文章的阅读完成率涨了40%。今天就把我踩过的坑、摸透的技巧全告诉你，不用懂复杂的代码，跟着做就能让你的CKEditor代码块“变好看”。
为什么CKEditor+SyntaxHighlighter是技术内容的「颜值救星」
先跟你唠唠，为啥非要用这俩组合？做技术内容的都知道，代码块的可读性直接影响文章价值——你写“如何用Python爬取网页”，代码块里的requests.get()要是和普通文字一个颜色，读者得眯着眼睛找关键函数；要是有语法高亮，关键词红、字符串绿、注释灰，一眼就能分清结构。
SyntaxHighlighter就是干这个的：它能给代码自动加语法着色、行号、复制按钮，甚至还能折叠长代码（不过这个功能得额外配置）。而CKEditor作为常用的富文本编辑器，本身不带高级代码高亮，得靠插件补全这个缺口。去年我朋友的博客用的是CKEditor 4，之前直接贴代码，读者留评“代码太乱，弃了”，换成SyntaxHighlighter后，不仅代码好看了，连“复制代码”的按钮都帮读者省了手动选代码的麻烦——你说，这样的内容能不招读者喜欢吗？
再说个更实际的：现在搜索引擎也重视内容的“易用性”，谷歌Search Console里有个“用户体验”指标，其中就包括“内容易读性”。代码块清晰的文章，停留时间更长，搜索引擎会认为“这篇文章有价值”，间接帮你提升排名。我那朋友的教程文章，之前关键词“Python爬虫入门”排在第10页，改了代码块后慢慢爬到了第3页——你看，连SEO都沾光。
从0到1配置SyntaxHighlighter，我踩过的坑你别再踩
接下来直接上干货，我把配置分成“准备工作-安装插件-调整设置-验证效果”四步，每一步都给你讲清楚“要做什么”“为什么要做”“别踩什么坑”。
第一步：找对插件版本，别下错包
首先得确认你的CKEditor版本——是CKEditor 4还是5？这俩插件不通用！我去年第一次帮朋友下的时候，没看版本，直接下了CKEditor 5的SyntaxHighlighter插件，结果装到CKEditor 4里完全没反应，白折腾俩小时。
正确的做法是：打开CKEditor官网的插件库（链接：https://ckeditor.com/cke4/addons/plugins/all?nfollow=1），搜索“SyntaxHighlighter”，选对应你CKEditor版本的插件包下载。比如CKEditor 4的插件包名叫“syntaxhighlighter_4.1.x.zip”，下载后解压，里面会有“plugins”和“samples”两个文件夹。
第二步：把插件“放进”CKEditor里
接下来要把插件文件传到服务器的CKEditor目录下——比如你的CKEditor安装在网站根目录的“ckeditor”文件夹里，那你就把解压后的“syntaxhighlighter”文件夹（在plugins里）复制到“ckeditor/plugins”目录下。
这里要注意：路径不能错！我朋友一开始把插件放到了“ckeditor/js/plugins”里，结果编辑器根本找不到插件——CKEditor默认只会在“ckeditor/plugins”里找插件文件，别瞎改路径。
第三步：改配置文件，让插件“显形”
插件传进去还不够，得告诉CKEditor“我要用上这个插件”。打开CKEditor目录下的“config.js”文件（要是没有就自己建一个），加两行代码：
CKEDITOR.editorConfig = function( config ) {
// 把syntaxhighlighter加进工具栏
config.toolbar = [
['Bold','Italic','Underline'], // 原有工具
['SyntaxHighlighter'] // 新增的代码高亮按钮
];
// 启用SyntaxHighlighter插件
config.extraPlugins = 'syntaxhighlighter';
};
这里有个坑：很多人会把“SyntaxHighlighter”写成“syntaxhighlighter”（小写s），结果工具栏里找不到按钮——CKEditor的插件名称是大小写敏感的！一定要和插件文件夹的名字一模一样（比如插件文件夹叫“syntaxhighlighter”，就写小写）。
第四步：加载样式和脚本，让代码“亮起来”
插件配置好了，但要是没加载SyntaxHighlighter的CSS和JS文件，代码块还是不会高亮。你得在网站的页面模板里加这几个文件：
结束前加对应语言的Brush文件：比如你要高亮JavaScript，就加
我去年漏加了Brush文件，结果写了个JavaScript代码块，显示出来还是黑底白字——后来打开浏览器控制台一看，报了“shBrushJScript is not defined”的错误，才反应过来是漏引了文件。
第五步：调整细节，让代码块更“贴合”你的网站
最后一步是微调样式，让代码块和你的网站风格统一。比如：
改背景色：如果你的网站是深色主题，可以在CSS里加.syntaxhighlighter { background-color: #1e1e1e !important; }（!important是为了覆盖默认样式）；
改字体大小：默认的字体可能太小，加.syntaxhighlighter code { font-size: 14px !important; }；
显示行号：在config.js里加config.syntaxhighlighter_lineNumbers = true;，这样代码块会显示行号，方便读者参考。
给你列个常见错误排查表，碰到问题直接对照着改：
错误场景
原因
解决办法
编辑器里找不到“代码高亮”按钮
没把插件加进toolbar配置
修改config.js的toolbar数组，加入插件名称
代码块显示但没有高亮
没加载对应语言的Brush文件
在页面里引入shBrushXXX.js（比如Python用shBrushPython.js）
代码块样式乱了（比如背景色不对）
CSS文件路径错了或没加载
检查shCore.css的路径，确保能访问到
最后教你验证配置：写完一篇带代码块的文章，点“预览”——如果代码块有语法着色、行号（要是开了的话），而且能点“复制代码”按钮，就说明成了；要是没成，打开浏览器的“开发者工具”（按F12），看“控制台”里有没有404错误（比如“shCore.css not found”），或者“未定义”错误（比如“shBrushJScript is not defined”），顺着报错信息改就行。
你要是按这些步骤试了，不管是成功让代码块“变好看”，还是碰到了奇奇怪怪的问题，都来评论区留个言——我去年帮朋友调的时候，光是路径问题就改了三次，特懂那种“明明按步骤来还是错”的崩溃。说不定我能帮你揪出问题在哪儿，毕竟踩过的坑多了，经验就攒下来了～
代码块显示了但没高亮，我跟你说，十有八九是没加对应语言的“Brush”文件——SyntaxHighlighter这插件有点“挑食”，不同语言得用不同的JS文件兜底，比如写Python就得引shBrushPython.js，写JavaScript就得引shBrushJScript.js。你得把这些文件加到网站页面的
或者末尾，不然它根本不认识你写的代码是啥语言，咋给你高亮啊？我之前帮朋友调的时候就碰到过这情况，他光装了插件没引Brush文件，代码块光秃秃的跟普通文本似的，后来加上对应文件，立马就有颜色了，读者都留言说“终于能看清代码了”。
想给代码块加折叠功能？能是能，但得额外捣鼓两下——你先在config.js里加一行“config.syntaxhighlighter_collapse = true;”，再把折叠的扩展脚本shCoreCollapse.js引进去。我之前给朋友的长代码块加过这功能，比如那种爬取网页的完整代码，几百行呢，默认折叠起来省空间，读者点一下才展开，特适合教程里的大例子，不至于把页面拉得老长，影响阅读体验。
有人担心用这插件会拖慢网站速度？其实真不用怕——它的核心文件shCore.js和shCore.css就几KB大小，跟一张小图片差不多。只要你别贪多，写啥语言就引啥Brush文件（比如写Python教程就只引shBrushPython.js，别把Java、PHP的都引进去凑数），根本不会让页面加载变慢。要是你还不放心，直接用CDN加载这些静态文件，比存在自己服务器上还快，我朋友的博客就是这么弄的，打开速度一点没受影响，反而更顺了。
CKEditor 5能用这个SyntaxHighlighter插件吗？
不能，CKEditor 4和CKEditor 5的插件不通用。需要根据自己使用的CKEditor版本，到官网插件库下载对应版本的SyntaxHighlighter插件，比如CKEditor 4对应“syntaxhighlighter_4.1.x.zip”这类包。
安装插件后，工具栏里找不到“代码高亮”按钮怎么办？
首先检查config.js配置：一是确认“extraPlugins”里加了“syntaxhighlighter”（注意大小写要和插件文件夹名一致）；二是确认toolbar数组里加了“SyntaxHighlighter”按钮。如果配置没错，再检查插件文件夹是不是放在CKEditor的“plugins”目录下（比如“ckeditor/plugins/syntaxhighlighter”），路径错了编辑器找不到插件。
代码块显示了但没有语法高亮，是哪里错了？
大概率是没引入对应语言的“Brush”文件。SyntaxHighlighter需要针对不同语言加载对应的JS文件（比如Python对应shBrushPython.js、JavaScript对应shBrushJScript.js），要在网站页面的
或末尾加入这些文件的引用，否则无法识别代码语法并高亮。
能不能给代码块加“折叠”功能？
可以，但需要额外配置。在config.js里添加“config.syntaxhighlighter_collapse = true;”，同时要确保加载了SyntaxHighlighter的折叠扩展脚本（比如shCoreCollapse.js）。配置后，长代码块会默认折叠，读者点击可展开，适合篇幅较长的代码。
用这个插件会拖慢网站加载速度吗？
一般不会。SyntaxHighlighter的核心文件（shCore.js、shCore.css）体积很小，只要只引入需要的语言Brush文件（比如写Python教程就只引shBrushPython.js，不用引其他语言的），不会对加载速度有明显影响。如果担心，还可以用CDN加载这些静态文件，进一步提升速度。
