在公众号里贴代码？我觉得把代码变成图片阅读体验更好

hello！大家好！

最近我在写公众号文章的时候，又被代码块折磨了一次。

事情是这样的，文章里只是想放一段配置示例，让读者知道某个 API 怎么调用。电脑上预览还好，代码块有等宽字体，有缩进，也能横向滚动。可是一到手机上，体验立刻变得很差。

读者要么看到一行代码被压得很窄，换行以后缩进全乱；要么需要左右滑动，一不小心又把整篇文章带着动。

我自己作为作者也很痛苦。写文章的时候，代码不是为了让读者复制粘贴一大坨。

很多时候，它只是一个视觉证据：这里确实有一个参数、一个调用方式、一个配置片段、一个关键 diff。

读者需要的是一眼看懂结构，而不是在手机上和横向滚动条搏斗。

所以我最近试着做了一件事：把文章里的关键代码转成图片。

不是所有代码都转。需要复制的完整代码，还是应该放链接、仓库、Gist 或文档页。但在公众号正文里，那些用来解释、展示的代码片段，图片反而更适合阅读。

读者在阅读的时候，通常不会需要复制代码。

代码图片解决的不是“好看”

很多人第一次听到“代码转图片”，会以为它只是让代码变漂亮。

当然，漂亮是有用的。公众号文章本来就是移动端阅读场景，图文排版、留白、色彩、层级都会影响读者愿不愿意继续往下看。

但我真正关心的不是装饰感，而是阅读稳定性。

代码变成图片以后，移动端至少有几个变化：

• 缩进不会被微信编辑器重新解释；

• 长行不会在奇怪的位置硬折断；

• 主题、行号、语言标识可以保持一致；

• 读者不需要左右滑动代码块；

• 作者可以控制图片宽度、留白和背景，让它和正文节奏更合拍。

这对技术文章尤其明显。

比如我写一段 JSON 配置，如果直接贴在公众号里，手机上一换行，层级感就没了。读者原本只需要看 model、tools、messages 之间的关系，结果注意力全被滚动操作占掉。

如果把它转成一张清晰的图片，读者就能像看截图一样扫过去：先看整体结构，再看重点字段。它虽然适合复制，但非常适合理解。

怎么取舍？

正文讲解用图片，完整可复制代码放链接。

也就是说，如果这段代码承担的是“解释”和“展示”的任务，我会把它转成图片；

如果它承担的是“交付”和“复用”的任务，我会给 GitHub、文档页、npm 包、完整示例仓库，或者在文末补一个可复制版本。

比如这些场景很适合代码图片：

• 展示一个 API 请求长什么样；

• 展示某个配置文件的关键字段；

• 展示重构前后的差异；

• 展示 CSS、SQL、正则这种需要语法高亮的片段；

• 展示 Agent 生成的结果摘要；

• 展示“这一段就是问题所在”的代码证据。

这些场景则不适合只放图片：

• 教程里要求读者照着运行的完整代码；

• 很长的源码文件；

• 需要复制的命令；

• 读者可能需要搜索、改写、粘贴到 IDE 的内容。

所以代码图片不是替代代码文本，而是增强读者阅读体验的可选方案。

这就是我做 Codia 的原因

Codia 是我做的一个小工具，目标很直接：把源代码生成适合人阅读、也适合 API 调用的代码图片。

它不是一个只给网页点点点用的小玩具，也不是只能在本地跑的截图脚本。它同时提供了几种入口：

• Playground：在浏览器里粘贴代码，调语言、主题、图片格式、背景、留白、宽度、行号，然后复制或下载图片；

• POST /v1/code/render API：用 JSON 请求生成代码图片，适合脚本、服务端、自动化流程；

• /docs 和 /api/docs：给人看的 API 文档和 OpenAPI 文档；

• /llms.txt：给 Agent 看的说明入口；

• MCP：让支持 MCP 的 Agent 直接调用 render_code_image 或 render_code_image_advanced。

如果你只是偶尔写文章，最简单的方式就是打开 Playground。

把代码粘进去，系统会自动识别语言，比如 typescript、javascript、python、go、json、css；

再选主题、格式、宽度、行号和背景。调到适合公众号正文的宽度后，直接下载图片，插到文章里就行。

如果你已经有自己的写作流程，Codia 更有意义的地方在 API 和 MCP。

手动用法：打开 Playground

最简单的工作流是这样：

1. 写文章时先把代码片段留在 Markdown 里；

2. 发布前挑出真正需要展示的代码；

3. 打开 Codia 的 playground 页面；

4. 粘贴代码，选择语言和主题；

5. 调整各种生成图片的参数，使其满足自己的喜好

6. 复制或者下载图片，放回公众号文章。

公众号里我一般会更关注三个参数。

API 用法：把生成图片变成固定步骤

如果你经常写技术文章，就不应该每次都手动调。

在使用 API 之前，只需要用户登录一下 Chrome 账户，再生成自己的凭证放在请求头里即可！

Codia 提供 POST /v1/code/render，可以从 JSON 生成图片。一个最小请求大概是这样：

curl -X POST http://localhost:4300/v1/code/render \

  -H "content-type: application/json" \

  -d '{

    "language": "typescript",

    "theme": "dracula",

    "format": "png",

    "code": "console.log(\"hello codia\")",

    "containerWidth": 600,

    "borderSize": 12,

    "showLineNumbers": true

  }'

默认返回 JSON，里面有 dataUrl、imageBase64、图片元数据和 recordId。如果设置 responseType: "image"，可以直接拿到图片二进制。Pro/Admin 用户还可以用 responseType: "cdnUrl"，把图片上传到配置好的 R2/S3 兼容存储里，直接拿 CDN URL。

这样一来，代码图片就可以进入工作流，而不是停留在“我打开网页手动做一张图”。

比如你可以写一个小脚本，扫描文章里的代码块，把带有特殊标记的代码块发给 Codia，然后把返回的图片地址插回 Markdown。

我很喜欢这种方式，因为它把审美变成了一个稳定步骤：主题、宽度、留白、行号规则都固定下来。以后每篇文章里的代码图看起来是一套系统，稳定性大大提升。

Agent 用法：让 AI 写文章时顺手出图

Codia 还提供 MCP，这个对我自己的写作特别有用。

现在很多文章我会让 Agent 参与：整理资料、改结构、补示例、做发布前检查。以前让 Agent 处理代码图片很麻烦，它得知道 API 怎么调用、图片怎么保存、哪些参数适合文章。

有 MCP 以后，Agent 可以直接调用工具。

Codia 里有两个主要工具：

• render_code_image：适合常见场景，参数比较少，可以选 github、twitter、docs、blog、glass、macos、minimal 这些 preset；

• render_code_image_advanced：适合精细控制，可以设置完整渲染参数，比如 theme、bgColor、borderSize、containerWidth、showLineNumbers 和 quality。

这意味着我可以在写作任务里直接说：

把文中这三段代码生成适合公众号正文的代码图片，JSON 配置用 docs 风格，TypeScript 示例用 blog 风格，图片宽度控制在 600 左右，保留行号。

Agent 就不需要再“理解图片生成原理”，它只要调用 Codia 的工具，把结果放进文章资产流程里。

工具越适合 Agent 调用，写作流程就越容易自动化。尤其是公众号文章这种有固定生产节奏的内容：选题、资料、正文、配图、代码图、封面、排版、草稿，每一步都可以慢慢沉淀成 workflow。

我现在会放进哪些工作流

第一个是公众号写作。

我会在 Markdown 里保留原始代码，发布前让 Agent 判断哪些代码适合图片化。短配置、关键 diff、核心 API 示例转成图片；需要复制的命令保留文本，并给出仓库或文档链接。

第二个是项目文档。

文档正文里有些代码是为了精读，有些只是为了“长这样”。后者很适合转成图片，尤其是 README、产品介绍页、更新日志、社交平台分享图。Codia 的 API 可以让这些图保持统一风格。

第三个是 AI 工作日志。

比如让 Agent 总结一次重构，它可以把关键代码片段、前后对比、配置变化生成代码图片，再配上文字说明。这样分享给团队或发到文章里，比贴一堆 Markdown code block 更容易被读完。

第四个是发布流水线。

如果你的文章本来就从 Markdown 进入某个发布系统，可以在构建阶段做一件事：识别带标记的代码块，调用 Codia 生成图片，上传到图床或 CDN，再把图片 URL 写回最终稿。

像这样给代码块加一个约定：

```ts

const message = "hello codia"

console.log(message)

```

真正发布前，脚本或 Agent 把它变成一张图。原始代码仍然留在仓库里，公众号看到的是图片。

这个思路的好处是，作者不用在写作时打断心流。写的时候还是写 Markdown，发布的时候再统一处理。

不要滥用

代码图片也有代价。

它不能被读者直接复制，搜索引擎也不容易理解图片里的代码，屏幕阅读器体验也会下降。如果一篇教程全是代码图片，那对真正想跟着做的读者并不友好。

所以建议它当成“展示层”，不是“源码层”。

比较理想的做法是：

• 正文里放代码图片，保证移动端阅读顺滑；

• 文末放完整仓库、文档或可复制代码；

• 图片 alt 或上下文说明里写清楚这段代码展示的是什么；

• 长代码拆短，只展示关键部分；

• 不把图片当成唯一的信息来源。

技术内容最终还是要对读者负责。好看的代码图可以降低阅读门槛，但不能牺牲可访问性和可复现性。

最后

公众号是一个很典型的移动端阅读场景，而代码天生更适合横向空间。

该复制的地方，给文本和链接；该阅读的地方，给一张稳定、清晰、有层次的图片。作者少一点排版焦虑，读者少一点手机上左右滑动的烦躁。

Codia 目前就是围绕这个需求做的：给人一个 Playground，给程序一个 API，给 Agent 一个 MCP。你可以手动用，也可以把它接进自己的写作、文档和发布 workflow 里。

Codia 也是我第一个比较完整的个人作品，目前任然处于早期开发阶段，欢迎大家试用看看！