写博客最烦的不是写而是发。我之前手上有好几个平台要同步每次写完一篇长文先要把标题复制过去再把Markdown源码转成HTML图片一张张传到后台图库然后手动设置标签、分类、封面图最后还要检查一遍格式才能点发布。这一套流程下来十分钟起步熟手也一样。尤其那种几千字的深度文章中间夹着代码块、表格、公式到了博客后台全散架光是修排版就够憋屈的。后来我就想能不能自己写一个发布插件把本地写好的Markdown文章一键推到博客后台说干就干我把需求拆开从抓包分析、接口封装到文案生成、图片上传、定时发布断断续续搞了两周做了一个真正能用的“博客发布插件”。这篇就把整个流程、踩过的坑、留下的代码框架都整理出来给想在博客自动化上少走弯路的朋友做个参考。1. 为什么会有这个想法博客发布这件事有多烦1.1 手动发布的真实痛点写作的人都有这种感觉真正花心思的是内容本身可发布环节却极尽琐碎。我用的是本地Markdown编辑器习惯把所有素材先写成.md文件图片统一放在一个images目录下。问题在于博客后台的编辑器大多是富文本模式它不认Markdown语法。你需要先把文章转成HTML再一段段检查。遇到过三种特别典型的崩溃场景代码块缩进丢失Python代码的高亮全没了一眼望去全是挤在一起的灰色文本。表格在粘贴时被富文本编辑器拆成一段段文字结构直接报废。本地相对路径的图片比如复制到后台后还要一张张手动点击上传再重新插入链接。这些还只是在“能把文章发出去”这个层面上的问题。如果你有多个博客平台、多个账号或者想在固定的时间段发文比如早上流量高峰前那手工操作的成本会进一步叠加。我统计过自己最慢的一次一篇四千字的文章从准备发布到真正发布成功前后花了将近二十分钟其中大部分时间都浪费在排版调整和图片处理上。1.2 为什么挑中和讯博客作为目标选哪个平台作为插件的首个兼容目标我其实纠结过一阵。最终选中和讯博客倒不是因为它功能多强而是它有明显的“老平台”气质界面稳定、用户习惯成熟、后台承载了大量老用户的写作需求但官方一直没有提供像样的开放API更没有一键导入Markdown这种现代功能。这就意味着这个平台的发布流程是最值得被“自动化拯救”的。说得直白一些像一些新型博客平台本身就内置了Markdown支持和图床功能反而不太需要折腾插件。真正的需求集中在那些历史悠久、后台技术栈偏老的平台上。它们没有API但你依然可以通过分析后台表单结构、保留登录Cookie、模拟浏览器提交请求的方式实现自动发布。这是我最终把项目命名定为“和讯博客发布插件”的直接原因它面向的不是某个单点需求而是老平台普遍存在的自动化空白。1.3 这个插件到底适合谁用写这个插件之前我认真想过受众。它并不是给所有人准备的对以下几类人价值最大每天或每周固定产出文章的博客作者希望把“发布”这件事压缩到一条命令。同时维护多个博客账号需要把同一篇文章同步到不同平台的用户。写技术文章为主大量涉及代码块、公式、表格对排版一致性要求较高的博主。对Python有一定了解愿意自己动手修修补补、调整发布参数的折腾型玩家。如果你只是偶尔写一篇随笔那没必要上插件直接在网页后台写就好。但如果你和我一样把博客当成一个长期内容仓库那“一键发布”带来的效率提升是实打实的。2. 整体设计与技术选型2.1 功能清单哪些是刚需哪些是锦上添花动手写代码之前我先把功能需求拆成了两栏一类是“没有它就不叫插件”的刚需另一类是“有它体验才算完整”的加分项。优先级功能说明状态刚需登录态保持自动读取本机保存的Cookie避免每次重复登录已完成刚需Markdown转HTML完成语法解析、代码高亮、公式占位已完成刚需图片自动上传读取本地图片上传到博客图床替换链接已完成刚需标题/正文/标签/分类映射从YAML配置中读取元信息填入发布接口已完成加分定时发布指定发布时间按计划提交已实现加分多账号切换支持配置文件分组方便切换身份已实现加分草稿模式不直接发布先存入草稿箱已实现加分失败重试网络异常时自动重试N次已实现加分历史记录记录每次发布的对象与结果用于查重已实现一开始我只想做个最简单能用的版本但写完初版后发现如果只支持“立即发布”一条路使用场景太窄。比如我想在深夜写完文章第二天早上八点再发出去就不得不设个定时任务把脚本包起来。后来干脆把定时逻辑集成进插件里配置文件里写一句publish_time: 2026-07-20 08:00:00脚本就能等到时间再自动调用发布接口。2.2 技术栈为什么用Python而不是浏览器扩展在选型上我认真对比过三条路线浏览器扩展、Python命令行工具、本地Web服务。浏览器扩展是最符合“插件”二字直觉的方案。它可以直接读取你正在浏览的网页调用后台的发布接口UI上也能做得很轻巧。但这里有个现实问题我需要处理本地Markdown文件、批量上传图片、解析本地YAML配置浏览器扩展的全套权限申请和文件读取机制反而更啰嗦。尤其是本地文件路径的读取在扩展里要申请“文件系统访问权限”还经常遇到沙箱限制。Python方案的优点是几乎没有边界文件读取、HTTP请求、重试机制、多账号切换全都用标准库加少量第三方包就能解决。而且Python写起来快改起来也快。如果以后想把它变成一个带GUI的工具完全可以在命令行版的基础上再包一层。我最终选择的方式是命令行工具为主本地Web服务为辅。命令行负责最核心的发布逻辑Web服务只在需要可视化配置的时候启动。这个选择还有一个隐藏好处命令行工具可以直接放在自动化管道里。比如我配了一个文件监听服务当我保存文章文件后它会自动触发发布脚本真正做到“保存即发布”。2.3 整体工作流设计整个插件的工作流是这么串起来的读取配置文件拿到博客地址、账号、默认标签、分类等信息。读取文章文件Markdown格式用front matter区块解析标题、发布时间、标签。解析正文里的图片路径逐个上传到博客平台图床。把Markdown转换成HTML针对不同后台做轻量修正比如旧平台的表格兼容性。携带Cookie或其他鉴权信息调用后台表单接口提交。根据返回结果确认发布成功或写入草稿箱。这一段流程里真正最核心的技术难点不在“调用接口”而在“接口调用前的准备工作”。如果把博客后台提交比作去窗口办事那登录态是身份证、处理过的HTML是装好袋的材料、图片上传是先把附件交进去材料没准备好窗口跑一趟再多次也没用。所以我在设计阶段就把“数据预处理”和“请求提交”拆成两层文件处理层保证内容质量请求层专心保证提交成功。3. 核心细节解析与实操要点3.1 登录与接口对接没有开放API怎么办和讯博客这类老平台没有对外开放的API却没有关死后台表单。处理思路是“模拟浏览器提交”但前提是你得搞清楚后台的表单结构。我的实操路径是打开浏览器开发者工具切换到网络面板勾选Preserve log。手动在后台发起一次发布动作观察它提交到哪个URL。找到表单数据字段列表对比前台输入和POST请求体的映射关系。检查是否存在csrf token等一次性令牌有的话需要在请求前从后台页面中提取。我实际抓包时发现这个平台的后台提交请求带有两个鉴权字段一个长会话Cookie一个页面隐藏的token字段。Cookie是从登录接口拿来的token是在后台编辑页面加载时生成的。因此脚本需要先模拟“打开编辑页面”从HTML里提取token再把这个token拼到发布请求里。这里有个非常容易踩的坑有些平台会校验请求头里的Referer字段如果Referer不符合后台页面的地址请求会被拒绝。所以封装请求时我会把Referer设置成编辑页面的完整URL而不是博客首页。这类细节在接口文档里永远不会写只能靠抓包对比才能发现。3.2 Markdown排版纯文本到标准HTML的转换Markdown转HTML我用了Python的markdown库加了一组常用扩展extra表格、删除线、codehilite代码高亮、toc目录树、sane_lists列表修正。依赖很少核心代码如下import markdown def md_to_html(text): extensions [ markdown.extensions.extra, markdown.extensions.codehilite, markdown.extensions.toc, markdown.extensions.sane_lists, ] md markdown.Markdown(extensionsextensions, output_formathtml5) return md.convert(text)转换之后还需要做一道“平台适配”。比如有些旧后台不认HTML5的figure、figcaption标签我就需要把这类标签改写成更朴素的div结构。还有代码块的class属性codehilite扩展默认会输出classcodehilite但平台后端的样式表不一定包含这部分CSS导致高亮失效。我的处理方式是在发布时把相关CSS样式内联进文章的style区域这样无论平台自带什么样式代码块至少能保持基本配色。代码块处理还有一个小细节如果你直接把Markdown源码的缩进空格转成HTML某些平台会自动把连续多个空格合并导致代码变形。对策是先把代码块包裹在pre标签里再把内部空格替换成nbsp;虽然字符会变长一些但至少显示正确。3.3 图片自动上传本地图片如何替换成线上链接文章里引用本地图片最常见的方式有两种相对路径和相对路径加尺寸参数。比如插件要做的事情是扫描所有格式提取图片路径上传到博客图床再把原来的路径替换成图床返回的URL。图片上传接口我同样是通过抓包定位的返回结果通常是JSON里面包含图片ID和可直接访问的URL。上传这块有三个关键点文件类型检查。尽量只允许png、jpg、jpeg、gif、webp其他格式直接报错跳过避免接口返回畸形数据。文件大小限制。部分平台图床对单张图片有大小限制有些是2MB有些是5MB超过的话需要先压缩再上传。我在脚本里加了一个自动压缩逻辑用Pillow把超限图片的质量降到85%尺寸宽度降到2000像素以内实测既保清晰度又能过审。链接替换的时机。等到所有图片都上传成功后再替换链接中途失败的话要回滚不能留一半本地路径一半线上链接。代码大概长这样import re IMAGE_PATTERN re.compile(r!\[([^\]]*)\]\(([^)])\)) def upload_and_replace_images(content, uploader): matches IMAGE_PATTERN.findall(content) for alt, path in matches: local_path path.split( )[0] if not local_path.startswith((http://, https://)): url uploader.upload(local_path) content content.replace(path, url) return content特别提醒一下Markdown里的图片路径有时会带一个空格之后的“标题文字”比如解析时如果不把空格分隔的后半部分去掉脚本会把整段./a.png 标题当成路径去访问直接报错。这是一个非常隐蔽的Bug我头一回跑的时候卡了半天。3.4 标签、分类与发布时间处理老平台的标签和分类通常不是直接通过文本字段设置的而是通过后台内置的接口绑定。有时候你在请求体里放一个tags字段服务端未必接受。我在抓包时发现和讯博客后台其实有两个独立接口一个负责文章主体内容保存一个负责文章标签关联。发布时必须先保存正文拿到新文章的ID再调用标签绑定接口才能最终在文章页看到标签。发布时间也是一样平台后台不一定支持让你指定过去或未来的时间戳。解决方案有两种一是平台本身开放了publish_time字段那就直接用二是平台不支持那就只能在本地排个定时任务等到时间再触发发布脚本。我的插件两种策略都支持如果配置了publish_time字段先检查平台接口是否接受不接受的话自动切换到定时发布模式。这里还涉及一个时间格式问题不同平台对时间的格式要求不同有的是标准ISO格式2026-07-20 08:00:00有的是时间戳还有的要用YYYY/MM/DD HH:mm:ss。所以在配置层做一次格式统一再在接口适配层做转换能省掉很多麻烦。4. 从零到一的完整实现过程4.1 工程初始化与依赖安装工程结构我按“可扩展”的方向来设计不只为某一个平台服务。目录长这样blog_publisher/ ├── main.py # 入口地址参数分发 ├── config.yaml # 默认配置文件 ├── articles/ │ └── 2026-07-20-hello.md ├── publisher/ │ ├── __init__.py │ ├── auth.py # 登录与Cookie管理 │ ├── converter.py # Markdown转HTML │ ├── images.py # 图片上传与路径替换 │ ├── client.py # 博客后台接口封装 │ └── utils.py # 公共工具 ├── logs/ └── requirements.txt依赖比较少核心就这几个pip install requests pyyaml markdown pillow为什么用requests而不是更重的httpx因为目前所有请求都是同步的并发上传场景也只需要简单的线程池requests足够稳定。用pyyaml解析配置是因为YAML写起来比JSON舒服得多嵌套结构一眼能看懂。pillow只用于图片压缩没有它也能跑只是遇到超限图片会直接失败体验差很多。4.2 发布主流程核心代码入口文件main.py的逻辑很直接接收文章路径参数读取配置执行发布。import argparse import logging import sys from publisher.auth import AuthManager from publisher.converter import md_to_html from publisher.images import upload_and_replace_images from publisher.client import BlogClient logging.basicConfig(levellogging.INFO, format%(asctime)s - %(message)s) logger logging.getLogger(__name__) def load_front_matter(text): 解析Markdown文件开头的---块 if text.startswith(---): end text.find(---, 3) if end ! -1: fm text[3:end].strip() body text[end 3:].strip() return fm, body return , text def main(): parser argparse.ArgumentParser(description博客发布插件) parser.add_argument(file, helpMarkdown文章路径) parser.add_argument(--config, defaultconfig.yaml) parser.add_argument(--draft, actionstore_true, help保存为草稿) args parser.parse_args() with open(args.file, encodingutf-8) as f: raw f.read() front_matter, content load_front_matter(raw) # 简化的front matter解析实际建议用python-frontmatter库 config yaml.safe_load(front_matter) if front_matter else {} auth AuthManager(args.config) session auth.get_session() client BlogClient(session, config) html md_to_html(content) html upload_and_replace_images(html, client.upload_image) post_data { title: config.get(title) or 未命名文章, body: html, category: config.get(category, 默认分类), tags: config.get(tags, []), } if args.draft: post_data[status] draft result client.publish(post_data) logger.info(发布成功: %s, result.get(url)) if __name__ __main__: main()front matter区块的解析是文章元信息的关键。虽然我上面为了清晰用了简化写法实际项目里建议直接用python-frontmatter这个库它能更可靠地处理编码、多行字符串、日期类型等问题。我初版手写了解析逻辑结果在处理带冒号的标题时翻车了后来还是换了库。client.py里的发布逻辑要特别注意不能用一次性会话。原因在于token的获取、Cookie的刷新、图片的上传、正文的提交每一步都需要复用同一个session对象。用requests.Session()把状态保持住能避免很多“明明登录了又提示未登录”的诡异问题。4.3 配置文件与密钥管理配置文件要拆成两类config.yaml是长驻配置包含平台地址、默认标签、重试次数密钥类信息登录密码、Cookie串单独放到.env文件中不入库也不贴给别人看。# config.yaml platform: hexun base_url: https://blog.example.com default_category: 技术随笔 default_tags: [随笔, 技术] retry_times: 3 upload_images: true cover_field: false publish_time: 密钥管理我用的是dotenv思路让代码从环境变量读敏感信息from dotenv import load_dotenv import os load_dotenv() username os.getenv(BLOG_USERNAME) password os.getenv(BLOG_PASSWORD) cookie os.getenv(BLOG_COOKIE)密码字段并不是每次都需要的。如果你已经手动登录过一次平台可以把浏览器里的Cookie复制出来存到.env脚本直接用Cookie发请求这样可以避免反复登录、也可以减少账号密码在本地存储带来的安全风险。但Cookie也有有效期失效后脚本会提示你重新登录并更新Cookie。4.4 封装成真正好用的命令行工具写完入口代码后还需要让它用起来足够顺手。我在config.yaml里维护了一份文章清单配合一个简单的shell命令就可以做到“所有待发布文章一键扫描、全部发布”。命令行使用示例# 发布单篇文章 python main.py articles/2026-07-20-hello.md # 发布并以草稿保存 python main.py articles/2026-07-20-hello.md --draft # 指定额外配置 python main.py articles/2026-07-20-hello.md --config my_site.yaml如果你不习惯每天敲命令可以再加一层文件监听。我写了一个watch.py脚本用watchdog监听文章目录的文件修改事件当检测到.md文件被保存后自动调用main.py执行发布。这样写作流程变成在编辑器里打开文章改完顺手保存博客那边已经更新了。有点像“保存就编译”的开发体验文章编辑因此变得零摩擦。5. 实战中的高频踩坑记录5.1 登录态过期连环失败最折磨人的问题是Cookie失效。你第一次调试时一切正常第二天再跑请求突然被平台拒绝。原因很直接后台会话有有效期可能只有几个小时。解决思路有两个脚本里加入“检测未登录”的逻辑比如发布接口返回的JSON里包含特定的未登录错误码就立刻停止并提示用户重新登录。设计一套多Cookie轮换机制在.env里保存多个历史Cookie遇到一个失效自动换下一个全部失效再停止。我还遇到过一个更离谱的情况平台对同一个Cookie做了“单点登录”约束换了设备或浏览器登录后旧Cookie立即失效。所以每次更新Cookie后一定要记得同步更新到.env否则下次运行又是白屏报错。5.2 图片路径明明是好的却上传失败这个坑让我排查了很久。原因是Markdown里图片路径是相对路径而文章正文里有多个章节其中有一个章节的路径写错了比如写成了../images/xxx.png但脚本的工作目录是项目根目录导致文件读取时找不到。后来我把图片路径统一改为“绝对基于文章文件所在目录”解析不再基于命令行当前目录。具体做法是从args.file中取出绝对路径再拼接上图片相对路径这样就与你在哪个目录下执行命令无关了。类似这样from pathlib import Path article_path Path(args.file).resolve() image_path article_path.parent / local_path如果你不这么做只要你的命令行当前目录和文章所在目录不一致图片上传就会出问题。5.3 代码块高亮失效缩进全乱我在技术文章里大量使用代码块因此对代码块显示效果非常敏感。初版转换后的HTML在网页预览时代码块整体变成了一个灰色的方块没有行号、没有高亮。分析后发现codehilite扩展生成的CSS类名平台后台的样式表没有覆盖。解决方法是把代码高亮需要的CSS样式直接注入到文章的head区域这样无论平台默认样式多简陋至少能保证本地风格。缩进全乱的另一个原因是部分平台后台对pre标签内部连续空格的解析有bug会自动压缩。解决方法是把代码块内的空格替换成nbsp;换行保留为\n。这个方法虽然会让HTML源码变大但展示效果稳定。我建议只在遇到平台兼容性问题时开启不必默认打开。5.4 一篇文章被重复发布调试期间最不敢做的事就是重跑脚本因为稍不注意后台就会出现两篇同样的文章。平台通常不会做“同名文章去重”判断所以我必须在客户端侧加历史记录。我的做法是在logs/publish_history.json里存下文章的文件名和文章标题的哈希值每次发布前检查一次如果发现同一个文件已经成功发布过就提示选择“覆盖发布”还是“忽略”。import json import hashlib def check_duplicate(title): history load_history() h hashlib.sha256(title.encode()).hexdigest() return h in history覆盖发布时新文章ID会和旧文章ID不同最好能把旧文章标记为失效或删除。但平台后台不一定提供删除接口因此我目前只是保留新文章由用户手动在后台清理旧的。5.5 常见问题速查表现象可能原因解决办法请求401错误Cookie过期或失效重新登录平台后台复制最新Cookietoken缺失没有先访问编辑页在发布前先请求编辑页提取新版token图片上传失败图片超过平台大小限制用Pillow压缩后重传图片路径报错路径基于命令行目录解析改为基于文章文件所在目录解析Markdown转HTML乱码编码不一致文件统一保存为UTF-8读取时指定编码发布成功但页面404分类或标签接口未绑定检查正文保存与标签关联接口是否都调用定时发布未触发时间格式不对统一为ISO字符串让接口适配层转换重复发布没有历史记录记录成功发布文章的哈希值并检查6. 后续还可以怎么扩展这个插件目前的形态已经足够我日常使用但它的架构还有比较大的扩展空间。我自己的计划是第一把目标平台从单一平台扩展成多平台适配层。现在客户端接口已经封装成BlogClient类新增平台的成本主要是写一个新的适配器核心文件处理和排版逻辑完全通用。如果有精力甚至可以做一个“全平台一键分发”的版本。第二增加一个文章管理面板。我设想用本地Web页面展示所有待发布文章的状态可以勾选哪些文章要发布、哪些要定时、哪些要撤回。菜单可以做成邻接列表的形式不用单独连数据库。第三把图片上传抽象成多个图床适配器。现在上传用的博客自带的图床但其实可以增加对公开图床的支持这样就不受单个平台图片空间的限制。代码层面只需要抽象一个uploader接口然后为每个图床写一个实现类。第四增加AI润色或排版建议能力。现在很多编辑器都有AI插件可以顺手做一个文章检查步骤在发布前自动检测是否存在“标题重复”“图片缺失”“代码块未闭合”等常见问题。把这个能力放到发布插件里等于给发布流程加了一道质检。这些扩展每一项都不算难关键是把基础框架打牢固让后续的模块可以像插积木一样补充上去。最后聊一点个人体会。做这个插件的初衷其实不是“省那十分钟”而是想把发布流程变得可控、可复用、可追溯。当写作和发布彻底分离之后你会发现自己的心态也会变写的时候只想把内容写透不再挂念那些嵌套性极差的排版问题因为你知道后面有一整套自动化流程在兜底。这种“写归写、发归发”的爽快感才是这个插件带给我最大的回报。
