最近在做文章后台时，我遇到一个很实际的问题：编辑器里的代码块虽然能正常显示，但要拿去做分享图、封面图或者文档配图时就不太合适了。
一开始我试过手动截图，但这种方式效率低，而且样式不统一。代码只要改一行，就得重新截一次。后来我把一个代码转图片接口接进服务里，直接把代码片段渲染成 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/svg+xml","svg":"<?xml version='1.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。
请求示例
这个接口支持三种请求方式：
- GET query
- POST form
- POST 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/svg+xml","svg":"<?xml version='1.0' ... </svg>","png_base64":""}}调用逻辑
我在服务里一般按这个顺序处理整个代码转图片流程：
- 接收代码内容、语言、主题、标题
- 调用代码转图片接口
- 先判断
code === "200" - 再判断
data.svg是否存在 - 页面展示时优先返回 SVG
- 分享图输出时再处理 PNG
如果从搜索词角度理解，这一步其实就是把“代码截图生成怎么调用”落实成一条标准服务链路。
4. Node.js 调用代码
下面这段是我实际会放进项目里的写法，TypeScript + axios，可以直接运行。这段代码本质上就是一个最小可用的代码转图片示例。
importaxiosfrom"axios";importfsfrom"node: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?:Record<string,string>;supported_languages?:string[];};};asyncfunctionrenderCodeImage(){consturl="https://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.post<RenderCodeImageResp>(url,payload,{headers:{"Content-Type":"application/json"},timeout:20000});if(data.code!=="200"||!data.data?.svg){thrownewError(`render failed:${data.desc}`);}constresult=data.data;awaitfs.writeFile("./snippet.svg",result.svg,"utf8");if(result.png_base64){constpngBuffer=Buffer.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 !== "200"data为空svg为空png_base64为空- 接口超时
- 网络波动
如果图片生成失败，我通常会退回原始代码块展示，而不是让内容页直接空掉。
对于线上业务来说，这一点很重要。因为代码转图片失败不应该拖垮正文展示，代码截图生成只是增强能力，不该成为单点问题。
6. 实际使用场景
从我自己的接法看，代码转图片最适合下面几类业务，而且这些场景本身也都很适合做代码截图生成。
技术文章里的代码配图
有些代码片段主要是给读者看思路，不一定要复制执行。这时候直接生成代码高亮图片，比手动截图更统一，也方便后面替换。这是我最常用的代码转图片场景之一。
开发者工具结果展示
如果你的工具会输出 SQL、脚本、配置片段、前端代码示例，这类结果很适合直接走code to image，把文本结果变成可分享素材。这类页面做代码截图生成后，观感会明显比纯文本好很多。
分享页和活动页
很多页面只需要一张“代码效果图”，并不需要交互代码块。这时候直接生成 PNG 或 SVG，会比手动截图稳定得多。这也是很典型的代码转图片落地方式。
文档系统和知识库
对于固定示例代码，不需要在线编辑，只需要稳定展示。直接渲染成 SVG 卡片，可以减少前端高亮依赖，也方便统一样式。
如果你的文档里代码比较多，那这种代码截图生成方式会非常省事。
7. 小结
这次把代码转图片接进项目后，我最直观的感受是：它解决的不是“代码怎么高亮”，而是代码怎么变成可展示、可分发、可复用的素材。
如果你的项目里本来就有技术文章、开发者工具、分享图或者文档系统，这类代码转图片能力会比较顺手。整体看下来，代码截图生成的调用方式不复杂，返回字段也比较直接，尤其是svg、line_count、available_themes这几个字段，实际接起来很好用。
