先交代一下背景。我日常绝大部分时间泡在终端里写代码、查日志、跑脚本都在命令行完成。有一次写代码时突然想到一个点子想立刻发条推文记录下来结果切到浏览器、打开页面、登录、输入、点击发布这一套动作下来少说也要半分钟。更别扭的是切回终端后思路已经断了刚才那个点子的上下文全丢了。这类情况反复出现几次之后我实在忍不了决定自己动手做一个命令行发推工具也就是现在这个 twitter-cli。这个工具的核心价值就一句话把发推这件事从浏览器里的一个操作变成终端里的一条命令。你不需要打开任何界面不需要在窗口之间反复切换直接在终端里敲一行命令就能完成发布、查看时间线、删除推文等操作。它适合所有重度终端用户、开发者、独立站长以及任何希望提高社交网络操作效率的人。今天这篇文章就把整个项目的完整思路写下来从API申请、认证流程、核心代码实现到实际使用中遇到的各种坑和优化方案全部摊开讲清楚希望能给想做类似命令行工具的朋友一些参考。文章不算短但每一个环节都是我实际踩过坑之后沉淀下来的值得耐心看完。1. 为什么需要一个命令行发推工具终端党的日常痛先聊聊这个工具诞生的真实动机。可能有人会觉得发推文嘛打开网页点一下就行了搞个命令行工具是不是多此一举我以前也这么想直到自己高频使用之后才意识到这里面的效率差距比想象中大得多。1.1 场景痛点切换窗口的上下文丢失写过代码的人都有这种体验当你的大脑完全沉浸在某个逻辑里突然被外部干扰打断重新集中注意力往往需要几分钟。切换窗口去发一条推文看似只是几秒钟的动作实际上是一个完整的上下文切换过程——你要从代码世界跳到社交网络世界发完之后再跳回来。这个过程很碎碎到你可能意识不到它的成本但一天发生七八次累计起来就是很大的损耗。更尴尬的是浏览器里有时候会遇到页面刷新导致登录态丢失、输入框卡顿、编辑器自动补全干扰等问题。这些杂音在终端里统统不存在。命令行工具的特性决定了它天然适合这种高频、轻量、确定性的操作。1.2 命令行工具能做什么功能边界先想清楚动手之前我列了一个功能清单原则是只做高频操作不做大而全。最终确定下来的核心功能有四个发推文支持普通文本推文后续又加了图片上传。查看时间线拉取首页时间线按时间倒序展示支持分页。删除推文这个功能一开始觉得不重要实际用起来才发现是刚需——发错了、撤回重发命令行里一条命令就能搞定。多账号切换我手里有几个不同的账号个人号、项目号命令行工具可以做到一键切换不用反复登录。当时没有做的功能包括私信、通知流、点赞和转推。原因很简单——这些操作的频率和场景在终端里不一定比浏览器更顺手。工具的价值不在于功能多少而在于把少数几个高频操作做到极致流畅。1.3 技术选型为什么用 Node.js Twitter API v2技术选型我纠结过一段时间。可以用 Python、Go、Rust也可以用 Node.js。最终选了 Node.js原因非常现实第一Twitter 官方提供的 SDK 和示例代码里JavaScript 的例子最全社区资料也最多遇到问题好排查。第二Node.js 生态里处理 OAuth、HTTP 请求都很方便代码量比 Python 少很多。第三我自己主力开发语言是 JavaScript维护成本最低。API 版本我直接选了Twitter API v2没有犹豫。虽然 v1.1 的生态更老、资料更多但 v2 是当前官方主推的版本功能在持续补全而且 2023 年起 v1.1 的很多接口已经开始走下坡路新项目没必要开历史倒车。最终技术栈是组件选择说明运行时Node.js 18原生支持 fetch减少一个依赖认证OAuth 2.0 PKCE适合命令行场景的授权码流程APITwitter API v2官方当前主推版本依赖仅用 2 个核心库不搞大而全保持轻量2. API申请与认证命令行工具的第一道坎很多人在做Twitter第三方工具时最后卡住的往往不是代码而是API申请和认证流程。这一节我把完整过程写清楚特别是命令行场景下比较特殊的认证方式。2.1 开发者账号与Project创建这些细节容易被忽略要在 Twitter 开放的开发者平台上创建一个应用流程本身不算复杂注册开发者账号、创建 Project、创建 App、生成密钥和令牌。但有几个细节容易被忽略实际做的时候会卡人。第一个细节是开发者账号必须要先通过审核。新注册的开发者账号通常处于沙盒状态API权限非常有限需要提交一个简单的用途说明审核通过后才具备完整的 API v2 访问能力。我就是在这上面折腾了一轮——一开始以为注册完就能用结果好多接口返回 Forbidden排查了半天才发现是账号权限等级不够。第二个细节是App 的权限级别User Access Level。你可以在 App 设置页面里看到权限从低到高分为三档只读、读写、读写私信。发推文需要至少读写权限否则 POST 接口会被拒。这个非常关键我自己就曾经因为权限没调而白白调试了一整个晚上。第三个细节是OAuth 2.0 客户端类型的选择。Twitter API v2 的 OAuth 2.0 目前支持两种客户端一种是标准的 Web 应用模式Authorization Code PKCE另一种是机器对机器模式采用独立命令字样的Client Credentials通常会用于多用户、服务器侧token交换。命令行工具最适合用的是Authorization Code with PKCE因为它不需要存储客户端密钥安全性对本地工具更友好。2.2 OAuth流程在命令行里怎么落地PKCE的完整路径命令行应用认证最大的难点在于没有浏览器回调地址。Web 应用可以直接配置回调 URLhttp://localhost:3000/callback让浏览器跳回本地但命令行工具想要的方式应该是用户在终端里执行命令程序自动打开浏览器让用户完成授权然后拿到授权码再换 Token——这一流程对命令行工具是完全可以接受的。具体的落地路径是这样的用户在终端执行twitter-cli login。程序生成一个code_verifier随机字符串和code_challenge对 verifier 做 SHA-256 后 Base64URL 编码。程序拼接授权 URL用系统默认浏览器打开URL 里带response_typecode、redirect_uri、以及上一步算出的code_challenge。用户授权完成后回调地址会收到一个?codexxx参数。关键在于回调必须有一个本地监听服务来接收这个 code。我用了 Node.js 的http模块在本地起一个临时端口页面收到 code 之后立即展示授权成功请关闭页面同时把 code 传回主程序。拿着 code、verifier、redirect_uri 去换取 Access Token 和 Refresh Token。把 Token 加密存储到本地配置文件授权流程完成。这个流程写清楚之后其实不复杂但要在命令行里跑通有几个环节需要特别注意第一code_verifier 最少43个字符、最多128个字符且只能包含字母、数字和部分特殊字符。如果随机构造不合规授权服务器会直接报错。第二每个授权 code 只能用一次过期时间很短几分钟。如果换 Token 失败只能重跑整个流程。第三不能用 127.0.0.1 和 localhost 混用。授权 URL 里填的回调域名是localhost那本地监听的地址必须也用localhost。有时候系统 DNS 解析localhost会先走 IPv6而你的服务监听在 IPv4 上就会连接失败。2.3 Token存储与刷新安全性和便利性怎么平衡Token 存储这件事我前后改了三版一开始是纯文本放配置文件后来觉得太危险最终用的是Node.js crypto做对称加密后存储。Access Token 的有效期是2小时Refresh Token 的有效期比较长。关键点在于Access Token 过期之后用 Refresh Token 去刷新返回的不仅是一对新 Token同时旧的 Refresh Token 也会作废。如果你在多个地方同时运行这个工具后刷新的会顶掉先前的这是 OAuth 2.0 的默认行为踩过坑的人都知道。我的实现思路是每次调用 API 之前检查 Access Token 的过期时间如果快过期了就先自动刷新再发请求这个逻辑封装在请求层上层调用方完全无感。3. 核心代码拆解从发一条推到完整CLI功能功能清单和认证流程想清楚了接下来就进入真正的代码环节。我会把核心模块逐个拆开讲代码基于 Node.js 18使用内置fetch不依赖额外的 HTTP 库。3.1 主程序入口与子命令路由命令行的交互逻辑我用了一个很轻量的方式实现——直接解析process.argv没有引入commander这类参数库因为我的子命令只有四个参数结构也不复杂自己手写路由反而更清晰可控。#!/usr/bin/env node const { handleLogin } require(./commands/login); const { handlePostTweet } require(./commands/post); const { handleTimeline } require(./commands/timeline); const { handleDelete } require(./commands/delete); const args process.argv.slice(2); const [command, ...rest] args; switch (command) { case login: handleLogin(); break; case post: handlePostTweet(rest); break; case timeline: handleTimeline(rest); break; case delete: handleDelete(rest); break; case help: default: printHelp(); }入口这块有意识地保持薄每个子命令的逻辑单独放到commands/目录下方便后续扩展。如果你要加新功能只需要在commands/里新增一个文件然后在入口加一个case分支就行。printHelp()里我会把所有子命令的用法和参数列出来这样用户敲twitter-cli help就能快速查阅省去看文档的麻烦。3.2 发推功能最核心的一条路发推文的逻辑其实很直白组装请求、带上认证头、POST 到/2/tweets端点。但代码写起来有几个容易出错的细节。async function postTweet(text, mediaIds []) { const { accessToken } await loadTokens(); const body { text }; if (mediaIds.length 0) { body.media { media_ids: mediaIds }; } const response await fetch(https://api.example-v2.example/v2/tweets, { method: POST, headers: { Authorization: Bearer ${accessToken}, Content-Type: application/json }, body: JSON.stringify(body) }); if (!response.ok) { const error await response.json(); throw new Error(发布失败 (${response.status}): ${JSON.stringify(error)}); } const data await response.json(); console.log(发布成功: https://example.com/${data.data.id}); return data.data; }这里我想强调三个细节都是实测中反复踩过的坑。第一Token 加载之后要检查过期时间。我在loadTokens()内部已经做了自动刷新所以这里拿到的accessToken一定是可用的。这也提醒你不要在调用层做 Token 判断统一在封装层处理否则每个命令都得复制一遍刷新逻辑。第二请求头必须带 UTF-8 编码。虽然 JSON 格式默认就是 UTF-8但显式声明可以避免某些代理服务器和中间件做错误的内容识别。第三创建推文成功后返回的 data 里只有 id没有完整推文内容。如果你需要在终端里回显发出去的完整内容得再调一次 GET 接口去取详情或者直接把本地输入的内容打印出来。我选择了后者省一次请求。3.3 时间线读取与其实现细节读取时间线用的是/2/users/:id/timelines/reverse_chronological这个端点但它要求使用 OAuth 2.0 User Context 认证也就是必须带着用户的 Access Token 去请求。这意味着用户必须至少授权一次之后才能读取时间线。async function getTimeline(userId, sinceId null) { let url https://api.example-v2.example/v2/users/${userId}/timelines/reverse_chronological; const params new URLSearchParams({ tweet.fields: created_at,public_metrics, max_results: 20 }); if (sinceId) { params.set(since_id, sinceId); } const response await fetch(${url}?${params.toString()}, { headers: { Authorization: Bearer ${accessToken} } }); const data await response.json(); return data.data || []; }这段代码里有几个点值得展开讲。tweet.fields是可选的扩展字段。默认情况下 API 返回的推文对象只有id和text两个字段。如果你想拿发布时间、转发数、点赞数这些信息必须显式指定。这个设计让 API 的响应体保持精简同时也提醒开发者在做第三方客户端时要会精打细算地选字段。max_results的取值范围是 5 到 100。我在命令行展示的场景下用 20 比较合适——太多了刷屏太少了分页请求次数多。如果你的终端窗口足够大可以拿 40 左右平衡体验和请求量。分页游标是用next_token实现的。官方不叫页码而是一个透传 token指向当前结果的下一页。这个next_token的有效期是 16 分钟所以如果你要翻好几页尽量一次性拿完别隔太久再翻。关于时间线的排版我在终端里用了一个轻量方案每条推文展示作者、时间、文本、转发数和点赞数用不同颜色区分。文本超过终端宽度时自动截断——这里涉及到中文字符宽度的问题下一节会专门讲。3.4 删除功能流程上容易被忽视的点删除推文的 API 非常简单DELETE /2/tweets/:id一行代码就够。但实际使用中真正难的是如何快速拿到要删除推文的 ID。我的做法是先走时间线列出最近20条推文每条前面加上序号。用户执行twitter-cli delete之后交互式输入序号程序根据序号匹配到推文 ID再执行删除。这个交互逻辑比直接要求用户粘贴数字 ID 友好得多。删除操作是不可逆的所以在代码里我加了一层二次确认输入序号之后程序会把该推文的文本内容预览出来让用户确认是否真的删除。这个体验很重要因为终端命令一时手快的代价很高。4. 真实使用中踩过的坑API限额、中文长度与媒体上传功能全部开发完成、能正常跑通之后真正的考验才开始。这一节记录的是我在实际日常使用中遇到的三类问题每一类都花了不少时间排查。4.1 每个月1500条免费推文的配额怎么分配才合理Twitter API v2 的免费套餐Essential access有一个硬性指标每个月可以创建的推文数上限是1500条。这个 1500 条看着不少但如果你像我一样把它用在自动化和测试上很快就见底了。我一开始没注意这个配额开发阶段狂发测试推文一天之内发了几十条带各种格式的测试内容结果不到一周配额就告急了。后来我学乖了总结出一套分配策略日常真实使用每天最多两三条一个月不超过100条。自动化测试尽量用DELETE接口回收。删除推文是否占配额我没有完全验证过但至少创建后删除可以让你的时间线不至于被垃圾内容淹没。开发调试用沙盒环境如果你不具备独立沙盒条件就统一用一个专门测试账号来发避免打扰主账号的联系人和读者。还有一个细节配额是按照 UTC 月份重置的不是从你注册日开始算。具体重置时刻是当月第一天零点UTC也就是北京时间早上8点。我因为没摸清这个时间点曾经在月底最后一天被拒第二天一早又能发了才发现配额重置的这个规律。4.2 中文字符宽度计算与截断策略终端里显示推文文本需要处理的最头疼的问题之一就是字符宽度不一致。英文和标点是单宽度中文和部分符号在大多数终端里是双宽度。你在代码里看到的字符串.slice(0, 30)在英文场景下好用遇到中文文本就乱了——截断后可能只显示半行或者终端窗口排版错乱。我写了一个专门计算终端显示宽度的函数function terminalWidth(str) { let width 0; for (const ch of str) { const codePoint ch.codePointAt(0); // 中文字符范围以及全角符号统一按双宽度处理 if ( (codePoint 0x1100 codePoint 0x115F) || (codePoint 0x2E80 codePoint 0xA4CF) || (codePoint 0xAC00 codePoint 0xD7A3) || (codePoint 0xF900 codePoint 0xFAFF) || (codePoint 0xFE10 codePoint 0xFE19) || (codePoint 0xFE30 codePoint 0xFE6F) || (codePoint 0xFF00 codePoint 0xFF60) || (codePoint 0xFFE0 codePoint 0xFFE6) ) { width 2; } else { width 1; } } return width; }有了这个函数我就可以实现真正意义上的截断从第一个字符开始累加宽度直到超过窗口宽度然后加上省略号。这个逻辑说起来简单但没有现成的库可以直接用因为大多数 JavaScript 字符串方法都是以 UTF-16 编码的视角来操作字符遇到 emoji 之类的特殊字符还会有偏差。4.3 媒体上传的流程坑带图片发推是刚需但 Twitter API v2 的媒体上传并不像文本那么直接。你需要先走一遍分片上传流程拿到一个media_id然后再在创建推文时把media_id挂上去。这套流程我没用官方 SDK 的情况下踩了不少坑挑几个重点说说。第一图片文件有大小上限。免费权限下单张图片最大 5MB超过会被拒绝。这个限制不算苛刻但手机拍摄的照片动辄 8-10MB上传前必须压缩。第二分片大小必须是 1MB 的倍数。我当时传一个 3.2MB 的文件分片大小不小心设成了 700KB结果一直报参数错误。改成 1MB 对齐之后立刻通了。第三上传和创建推文之间有一个处理延迟。media_id拿到之后后台需要时间处理图片通常几秒钟。如果你立刻用这个 ID 发推有可能报media_ids无效。稳妥做法是等待 2-3 秒再发推。async function uploadMedia(buffers) { // 第一步初始化上传会话拿到 upload_media_id for (let chunk of chunks) { // 第二步按分片逐块上传 // 第三步确定上传完成 } // 等待后台处理 await new Promise(resolve setTimeout(resolve, 3000)); return mediaId; }这段伪代码的实际实现里每个请求都要带上不同的请求头参数相当于一个三步握手流程。细节比较多但原理清楚之后代码并不难写。5. 更进一步的优化把 twitter-cli 变成自己真正顺手的样子第一个能用的版本跑通之后剩下的时间我一直在打磨细节。这个阶段做的事情不宏大但对日常使用的流畅度提升非常明显。5.1 多账号管理与一键切换多账号管理是命令行工具相对浏览器的一个显著优势——你可以预先把几个账号的 Token 都存好然后随时切换。我的设计是每登录一个账号时要求给它起一个别名比如work、personal。配置文件里存的是别名到 Token 的映射。执行twitter-cli use personal就能切换到个人号执行twitter-cli account list看当前有哪些账号。有一个安全细节必须强调每个账号的 Token 都用不同密钥加密。我开始图省事用一个统一的全局密钥安全隐患很大。后来改成每个账号独立生成密钥主密钥是本地环境变量。5.2 定时发布的几种做法日常使用中我经常遇到现在想到了一个点子但不想立刻发出去、想晚上再发的需求。命令行工具本身不带定时功能但我用脚本来搞定一是在系统自带的定时任务里绑定twitter-cli post 内容命令设定时间即可发布。操作系统里配置固定计划相对简单适合每天固定时间发布的内容。二是写一个简单的循环脚本每分钟检查一次待发布列表#!/usr/bin/env bash while true; do now$(date %H:%M) if [ $now 20:00 ]; then twitter-cli post 晚上八点的准点分享 fi sleep 30 done这个脚本的逻辑极其朴素但足够解决定时发推这个需求。需要更复杂的时间表达式可以用node-schedule之类的能力不过个人使用来说脚本方案最透明、最容易掌控。5.3 和其他命令行工具的组合玩法twitter-cli 最大的变现有趣之处在于可以和其他命令行工具叠加组合产生112的效果。分享两个我实际用了很久的组合。第一个组合是配合一些命令行便签工具。我工作流定的习惯是灵光一现的想法随手记录整理成型之后再用 twitter-cli 发布。这比直接在浏览器里输入内容更符合创作节奏——先积累后发布。第二个组合是配合 shell 的管道和脚本做自动化。比如把今天完成任务的信息交给twitter-cli生成一条推文发出去。类似场景还包括git log --oneline -5 | twitter-cli post --stdin这样就把发布一条推文变成了命令行世界里一个普通的、可组合的环节。程序的精髓在于组合而命令行恰恰是所有工具组合成本最低的地方。我个人在实际使用中的体会是这类工具的核心价值其实不在于少切了几次窗口而在于它把社交网络的发布动作重新纳入到了命令行的工作流里让发布这个动作可以被脚本化、可以被编程、可以被组合。当你习惯了这种流畅之后再回头用网页版反而会觉得哪里不对。如果你也正在做类似的事情无论是给别的平台写命令行工具还是给 twitter-cli 增加新的功能希望这篇文章里记录的思路和踩坑过程能帮你少走一些弯路。我走了不少弯路才把这些细节攒齐你直接拿去用就好。