代码转图片怎么实现：代码高亮卡片生成方法

最近在做文章后台时我遇到一个很实际的问题编辑器里的代码块虽然能正常显示但要拿去做分享图、封面图或者文档配图时就不太合适了。一开始我试过手动截图但这种方式效率低而且样式不统一。代码只要改一行就得重新截一次。后来我把一个代码转图片接口接进服务里直接把代码片段渲染成 SVG 卡片需要静态图时再转成 PNG。这样一来代码转图片、代码截图生成、页面展示这几件事就串起来了。1. 我在什么场景下接了这个接口我这次接这个接口核心就是为了解决代码转图片需求。具体场景主要有这几类技术文章里的代码配图分享页里的代码高亮卡片开发者工具结果页的静态展示后台内容生产时的统一素材输出这些场景的共同点很明确代码是拿来展示的不是拿来编辑的。如果只是普通页面里的代码块前端高亮库就够用了但如果要做封面图、分享卡片、静态素材普通代码块并不适合直接使用。这时候就需要一个稳定的代码转图片方案。从实际落地看这类需求本质上也可以叫代码截图生成。只是和手动截图不同接口式的代码截图生成更稳定样式也更统一后续替换内容也更方便。2. 这个接口能做什么这个接口本质上就是一个代码转图片服务也可以理解成code to image。你传入代码、语言、主题、标题之后它会返回渲染好的 SVG 结果部分情况下还能拿到 PNG 数据。我这边实际调通后拿到的返回结构大致是这样{code:200,desc:success,data:{language:typescript,theme:aurora,theme_name:Aurora Glow,title:snippet.ts,line_count:1,truncated:false,width:760,height:172,code_length:28,png_supported:true,scale:2,content_type:image/svgxml,svg:?xml version1.0 ... /svg,png_base64:,png_bytes_length:0,available_themes:{aurora:Aurora Glow,sunset:Sunset Peach},supported_languages:[auto,python,javascript,typescript,json,bash,go,rust]}}对我来说这种代码转图片接口里最关键的字段有这些svg最核心适合直接嵌到页面里png_base64有值时可以直接生成 PNG 文件language确认语法高亮有没有命中theme/theme_name适合做主题切换width/height方便前端控制展示尺寸line_count可以限制超长代码truncated判断内容有没有被截断available_themes前端做主题选择时很好用supported_languages前端和后端都能拿来做参数校验从业务用途上看这个接口比较适合下面几类代码截图生成场景技术文章里的代码配图代码高亮卡片生成分享页里的静态代码图文档系统里的代码截图生成工具结果页里的代码转图片输出3. 接口调用流程整个代码转图片流程不复杂就是把代码内容传给接口再根据返回结果决定是直接展示 SVG还是继续生成 PNG。提交代码内容传语言主题标题调用代码转图片接口返回 SVG 或 PNG 数据页面展示或文件落地请求示例这个接口支持三种请求方式GET queryPOST formPOST JSON我在项目里直接用POST JSON因为后端调用更方便也更适合这类代码截图生成服务。POST /api/code-beautify HTTP/1.1 Host: v1.apizero.cn Content-Type: application/json { code: const sum (a, b) a b;, language: typescript, theme: aurora, title: snippet.ts }返回结果示例下面是我这边调试成功后整理过的精简版返回{code:200,desc:success,data:{language:typescript,theme:aurora,theme_name:Aurora Glow,title:snippet.ts,line_count:1,truncated:false,width:760,height:172,png_supported:true,content_type:image/svgxml,svg:?xml version1.0 ... /svg,png_base64:}}调用逻辑我在服务里一般按这个顺序处理整个代码转图片流程接收代码内容、语言、主题、标题调用代码转图片接口先判断code 200再判断data.svg是否存在页面展示时优先返回 SVG分享图输出时再处理 PNG如果从搜索词角度理解这一步其实就是把“代码截图生成怎么调用”落实成一条标准服务链路。4. Node.js 调用代码下面这段是我实际会放进项目里的写法TypeScript axios可以直接运行。这段代码本质上就是一个最小可用的代码转图片示例。importaxiosfromaxios;importfsfromnode:fs/promises;typeRenderCodeImageResp{code:string;desc:string;data?:{language:string;theme:string;theme_name:string;title:string;line_count:number;truncated:boolean;width:number;height:number;code_length:number;png_supported:boolean;scale:number;content_type:string;svg:string;png_base64:string;png_bytes_length:number;available_themes?:Recordstring,string;supported_languages?:string[];};};asyncfunctionrenderCodeImage(){consturlhttps://v1.apizero.cn/api/code-beautify;constpayload{code:[import axios from axios;,const sum (a: number, b: number) a b;,console.log(sum(1, 2));].join(\n),language:typescript,theme:aurora,title:snippet.ts};const{data}awaitaxios.postRenderCodeImageResp(url,payload,{headers:{Content-Type:application/json},timeout:20000});if(data.code!200||!data.data?.svg){thrownewError(render failed:${data.desc});}constresultdata.data;awaitfs.writeFile(./snippet.svg,result.svg,utf8);if(result.png_base64){constpngBufferBuffer.from(result.png_base64,base64);awaitfs.writeFile(./snippet.png,pngBuffer);}console.log({title:result.title,language:result.language,theme:result.theme,lineCount:result.line_count,size:${result.width}x${result.height},truncated:result.truncated,pngSupported:result.png_supported});}renderCodeImage().catch((err){console.error(err);process.exit(1);});安装依赖npminstallaxios如果你是第一次做代码截图生成这段代码已经足够拿来做本地调试了。如果你是要把代码转图片接进正式业务后面再补缓存、转存、鉴权就行。5. 返回结果怎么处理代码转图片能不能真正接进业务关键不在“能不能出图”而在“出图之后怎么用”。这一段其实也是代码截图生成最容易踩空的地方。页面展示优先用 SVG如果你的场景是技术文章帮助文档知识库页面后台预览页我建议优先用svg。因为在大多数代码转图片场景里SVG 比 PNG 更适合页面内展示。原因很直接清晰度高缩放不糊页面里直接可用不需要额外截图尤其是做代码高亮卡片时SVG 非常适合这种代码截图生成需求。静态输出再决定要不要转 PNG如果你的场景是分享图海报素材消息卡片上传对象存储那就要重点看png_base64。我这边实测时发现接口虽然返回了png_supported: true但png_base64可能为空。所以我的处理方式不是强依赖 PNG而是分两层png_base64有值直接写成 PNG 文件png_base64为空先保存 SVG再走自己的 SVG 转 PNG 逻辑这样做的好处是整条代码转图片链路更稳代码截图生成不会因为某次没回 PNG 就直接失败。参数校验先把无效输入拦住这类代码转图片接口虽然偏展示型但参数最好提前收紧。我一般会先校验code不能为空language是否在支持列表里theme是否在可选主题里title是否为空代码长度是否超出限制特别是supported_languages和available_themes很适合直接给前端做下拉项和表单校验。如果你的业务后面还有导出、分享、分发那前面这一步参数校验对代码截图生成体验影响很大。长代码处理避免图片过长做代码截图生成时最常见的问题不是调不通而是生成出来的图太长不适合分享或展示。所以我一般会结合这几个字段处理line_count超过阈值时提示只截重点代码truncated true时展示“内容已截断”width/height超出预期时不走分享图链路这样可以避免生成一张很长但并不好用的代码转图片结果。异常处理失败时回退到代码块我这边会重点兜住这些情况code ! 200data为空svg为空png_base64为空接口超时网络波动如果图片生成失败我通常会退回原始代码块展示而不是让内容页直接空掉。对于线上业务来说这一点很重要。因为代码转图片失败不应该拖垮正文展示代码截图生成只是增强能力不该成为单点问题。6. 实际使用场景从我自己的接法看代码转图片最适合下面几类业务而且这些场景本身也都很适合做代码截图生成。技术文章里的代码配图有些代码片段主要是给读者看思路不一定要复制执行。这时候直接生成代码高亮图片比手动截图更统一也方便后面替换。这是我最常用的代码转图片场景之一。开发者工具结果展示如果你的工具会输出 SQL、脚本、配置片段、前端代码示例这类结果很适合直接走code to image把文本结果变成可分享素材。这类页面做代码截图生成后观感会明显比纯文本好很多。分享页和活动页很多页面只需要一张“代码效果图”并不需要交互代码块。这时候直接生成 PNG 或 SVG会比手动截图稳定得多。这也是很典型的代码转图片落地方式。文档系统和知识库对于固定示例代码不需要在线编辑只需要稳定展示。直接渲染成 SVG 卡片可以减少前端高亮依赖也方便统一样式。如果你的文档里代码比较多那这种代码截图生成方式会非常省事。7. 小结这次把代码转图片接进项目后我最直观的感受是它解决的不是“代码怎么高亮”而是代码怎么变成可展示、可分发、可复用的素材。如果你的项目里本来就有技术文章、开发者工具、分享图或者文档系统这类代码转图片能力会比较顺手。整体看下来代码截图生成的调用方式不复杂返回字段也比较直接尤其是svg、line_count、available_themes这几个字段实际接起来很好用。