时间：2026-10-08说明：记录我（WorkBuddy）是怎么从你本地电脑、隔着网络去操作远程虚拟主机的。一共 4 次实战。前面讲「怎么控制的」，最后专门讲「遇到问题怎么解决的」。一、总共有 4 条「控制通道」

远程主机不是只有 FTP 一条路。这 4 次下来，实际用到了 4 条通道，各有各的适用场景：

通道能干的事用什么工具什么时候用① FTP传文件、取文件、列目录、建目录、删文件curl（少量）、Python ftplib（批量）普通主机，首选② 面板 WebFTP传文件、解压、删文件Edge 浏览器 + CDP 调试协议荧控制台类主机（FTP 传的文件不生效）③ 数据库管理（phpMyAdmin）导库、执行 SQL、查数据curl + cookie、multipart 上传所有主机④ 网站后台（Typecho）发文章、改主题设置Edge 浏览器 + CDP需要改站内内容时

一句话概括：文件走 FTP / 面板，数据库走 phpMyAdmin，内容走后台——三条腿，缺哪个补哪个。

二、通道 ①：FTP（文件传输）

原理：FTP 就是「远程的文件管理器」，走 21 端口。给你账号密码，就能像操作本地文件夹一样操作服务器目录。

少量文件 —— 用 curl# 列目录 curl -s -u "账号:密码" "ftp://主机/路径/" --list-only # 上传一个文件（-T 后面是本地文件） curl -T 本地文件 -u "账号:密码" "ftp://主机/路径/文件名" # 下载一个文件 curl -u "账号:密码" "ftp://主机/路径/文件名" -o 本地保存名

优点：一条命令搞定，不用装任何东西。缺点：每个文件都要重新连一次，文件一多就慢。

批量文件 —— 用 Python ftplib（关键经验）

第一次备份旧站时我就吃了亏：用 bash 循环一个一个传，跨国延迟下每个文件要 8~11 秒，668 个文件等于一两个小时，而且中途一条连接挂住就全卡死（实测卡了 1.5 小时没进展）。

后来改成 Python + ftplib 多线程，每个线程复用一条控制连接，同样的活 11 分钟跑完：

import ftplib ftp = ftplib.FTP() ftp.connect('主机', 21, timeout=45) ftp.login('账号', '密码') ftp.cwd('/wwwroot') # 列目录 names = ftp.nlst() # 下载 with open('本地文件', 'wb') as f: ftp.retrbinary('RETR 远程文件名', f.write) # 上传 with open('本地文件', 'rb') as f: ftp.storbinary('STOR 远程文件名', f) # 建目录 / 删文件 ftp.mkd('/wwwroot/usr') ftp.delete('/wwwroot/临时文件') ftp.quit()

核心技巧：开 6 条线程，每条线程自己连一次、连着不撒手，探测目录和下载一起做完。别用「一个文件一次连接」的写法。

三、通道 ②：面板 WebFTP（浏览器自动化）

为什么要用它：荧控制台这类平台（星辰云、轻云）有个怪规矩——FTP 传上去的文件，网站读不到。文件只有「通过面板的文件管理上传」才会被平台发布。这时候 FTP 就没用了，得去操作面板的网页界面。

怎么做到「程序遥控浏览器」：用 Edge 浏览器的 CDP（Chrome DevTools 协议）。思路是：

用一个独立配置目录启动 Edge，打开一个调试端口

msedge.exe --remote-debugging-port=9333 --user-data-dir=独立目录 about:blank

程序通过这个端口，直接给浏览器下命令：

Page.navigate —— 打开网页Runtime.evaluate —— 在页面里执行 JS（这是核心，等于我能点任何按钮、填任何表单）DOM.setFileInputFiles —— 把本地文件塞进网页的上传框（网页上传文件本质就是往一个 <input type=file> 塞路径，这个命令直接塞）面板自己的 JS 函数也能直接调，比如进目录、删文件。

上传文件的完整流程（已跑通、可复现）：

打开面板 → 登录点「文件管理」按钮，等一会儿让内嵌网页面板加载出来⚠️ 它默认停在根目录，不是站点根目录 → 要双击 wwwroot 目录项才能进去（这一步用 openDir('wwwroot')，不能硬调跳转函数，会被环境改写成奇怪的本地路径）校验页面上的路径栏确实显示 /wwwroot打开上传对话框 → 拿到上传框的元素编号 → DOM.setFileInputFiles 塞文件 → 点「开始上传」

删除文件：也是调面板自己的函数 selFile('文件名', true) + doCommonOperation('rm')。

四、通道 ③：数据库管理（phpMyAdmin）

原理：phpMyAdmin 就是个网页程序。我从本地用 curl 模拟浏览器登录，拿到会话 cookie，就能像点网页一样提交 SQL、导入数据。

登录（两步）：

# 第 1 步：GET 登录页，从 HTML 里抠出 token 和 set_session curl -c cookie.txt "https://主机/mysql/index.php" # 第 2 步：POST 账号密码 curl -b cookie.txt -c cookie.txt \ --data "route=/" --data "lang=en" \ --data "token=上一步拿到的" --data "set_session=上一步拿到的" \ --data "pma_username=账号" --data "pma_password=密码" \ --data "server=1" \ "https://主机/mysql/index.php"

执行 SQL（比如查表、改配置）：

curl -b cookie.txt \ --data-urlencode "token=xxx" --data-urlencode "db=库名" \ --data-urlencode "sql_query=SELECT COUNT(*) FROM typecho_contents" \ "https://主机/mysql/index.php?route=/sql&db=库名&lang=en&server=1"

导入 SQL 文件（用 multipart 上传）：

curl -b cookie.txt \ -F "token=xxx" \ -F "import_file=@本地.sql;filename=本地.sql;type=text/plain" \ -F "import_type=database" -F "format=sql" -F "skip_queries=0" \ "https://主机/mysql/index.php?route=/import&db=库名&lang=en&server=1"

一个例外：phpMyAdmin 的导出在自动化下拿不到（页面只返回一个"请启用 JavaScript"的空壳），所以导出这一步是让你自己手动点的。

五、通道 ④：网站后台（Typecho）

原理：和面板一样，用 CDP 遥控浏览器登录站点后台，然后模拟「填表 → 点按钮」。

两个关键点：

登录页有跳转，脚本不能一进去就找输入框，要轮询等表单出现再填、再提交登录成功会跳到首页，光看网址会误判（登录成功和失败都可能停在 /）→ 要再打开一次后台首页，确认没被弹回登录页，才算真登录

登录后，发文章就是：打开「撰写」页 → JS 往标题框和正文框塞内容 → 点「发布」；改主题设置同理（打开主题设置页 → 改对应输入框 → 保存）。

六、四次实战一览#任务用了哪些通道结果1旧站全量备份FTP（Python ftplib 多线程）77 个目录 / 1054 个文件 / 32MB，11 分钟完成2替换 favicon面板 WebFTP（CDP）把 2.4MB 的大图换成 13KB，压缩 188 倍3迁移到轻云FTP 上传 zip + FTP 修复目录结构 + phpMyAdmin 导库文件和数据库都部署好并通过验证4星辰云主机恢复面板 WebFTP 上传整包 + 单独覆盖 config + 面板删临时文件站点从 503 恢复为正常访问七、遇到的问题与解决（汇总）

前面没细说的曲折，这里一次讲清「出了什么问题、最后怎么绕过去的」：

遇到的坑最后怎么解决FTP 跨国太慢：每个文件要 8~11 秒改用 Python ftplib 多线程，每线程复用一条连接，从 1.5 小时缩到 11 分钟bash 脚本卡死：循环探测目录 1.5 小时无进展同样的活别用 shell 循环，改用 Python；单条命令都加超时保护HTTP 直连半死不活：想绕开 FTP 走网页下载，结果更慢放弃，还是回到 FTP 正道压缩包解压出来是乱码文件名：Windows 自带压缩工具打的包，路径分隔符是反斜杠，Linux 面板不认，解成一堆 var\Typecho\Db.php改用 Python zipfile 重新打包（强制正斜杠），并校验「0 个反斜杠」荧控制台的 FTP 文件不生效：传上去磁盘上有、FTP 能列出，但网站 404改走面板 WebFTP 上传（这条路才对）面板文件管理器默认不在站点根：文件总落到根目录不能硬调跳转函数（会被环境改写路径），要双击目录项进 wwwroot，并校验路径栏整包解压「跳过已存在文件」：config.inc.php 没被覆盖 → 网站报 Error establishing a database connection整包传完后，再单独把 config.inc.php 传一次覆盖phpMyAdmin 导出自动化拿不到：页面只返回 JS 空壳导出这一步交给用户手动点，我负责清理导入phpMyAdmin 用 curl 登不进（被 Cloudflare 挡，响应里连会话 cookie 都不给）改走 Edge 浏览器 CDP 登录后台登录判断失误：登录成功会跳首页，光看网址会误判登录后再打开后台首页确认没被弹回，才算成功CDN 线路抖动：请求 20~45 秒超时、时好时坏验证时直连源站 IP + Host 头，绕开 CDN导入报 #1044 Access denied：SQL 里带了 CREATE DATABASE 别家库名清理 SQL，删掉建库语句和别人的库段落导入报 #1064 语法错误：读文件时用了 errors='ignore'，静默丢字节破坏了转义涉及 SQL 一律按字节处理，不用会丢字节的读法面板删文件时连带把 wwwroot 删了 → 网站 503教训：删文件只选里面的内容，别把文件夹本身选上；后来用面板删临时文件时严格只选文件八、一句话方法论远程控制虚拟主机，本质就三件事：文件用 FTP（批量就上 Python 多线程）、数据库用 phpMyAdmin（导出让人点、导入用程序）、内容用后台（浏览器自动化）。遇到「传上去没反应」，先问一句：这个平台的 FTP 和网站用的是同一份文件吗？——荧控制台的答案是"不是"，那就必须走面板。

环境：Typecho 1.3.0 + nexmoe 主题 + CommentNotifier 1.8.3，虚拟主机（美国机房，PHP 7.4）时间：2026-10-06 夜一、起因

博客评论通知一直没配成功。现象很明确：

在插件后台点「测试发信」→ 能收到邮件在文章下发一条评论 → 收不到任何邮件

同一个插件、同一套 SMTP 配置，一个通一个不通。这说明问题不在「账号密码对不对」，而在「两条发信路径不一样」。

二、排查：先看配置，再动手2.1 用一个只读诊断脚本读出真实配置

插件的配置存在数据库的 plugin:CommentNotifier 里，从后台界面只能看到表单，看不到原值。写一个一次性 PHP 脚本上传到主题目录，用 HTTP 访问拿输出，读完立刻删除。

脚本要点：

用 SHOW TABLES 自动识别表前缀，不要用正则猜 config.inc.php敏感字段（密码、授权码）打码输出URL 带随机 token，只读不写用完立即删除，并访问一次确认返回 404

读回来的关键配置：

from = 2404999487@qq.com ← 之前填成了 smtp.qq.com，用户已自行改正 fromName = 苏的碎碎念 STMPHost = smtp.qq.com SMTPSecure = ssl SMTPPort = 465 SMTPUserName = 2404999487@qq.com template = Wechat yibu = 1 ← 异步提交：开着

同时测了 SMTP 端口连通性：465 / 587 / 25 全部可通，主机没有封发出站端口，授权码也有效（235 Authentication successful）。

2.2 找到可疑点：异步提交

翻插件源码，发信入口是这样分的：

if ($plugin->yibu == 1) { Helper::requestService('send', $param); // 异步：交给 Typecho 的服务机制 } else { self::send($param); // 同步：当场直发 }

测试邮件走的是同步路径（由浏览器发起 {siteUrl}/zemail?...），而真实评论走的是异步路径。

2.3 异步路径到底做了什么

Helper::requestService() 最终会注册一个 responder，在本次请求响应结束之后，由 服务器自己 去请求：

POST {siteUrl}/action/service?do=async

而这段代码里有一句致命的处理：

} catch (\Exception $e) { return; // 出错就静默返回，不记录、不提示 }

也就是说：只要服务器访问不了自己，这封邮件就会悄无声息地消失，你在任何地方都看不到报错。

2.4 验证：服务器能不能访问自己

在诊断脚本里加一段，让服务器用 siteUrl 请求自己：

服务器自访问 siteUrl → HTTP 0 错误: Certificate key usage inadequate for attempted operation

证书校验失败，服务器无法通过 HTTPS 访问自己的域名 —— 这正是异步请求失败的原因。

匹配现象：

场景谁发起请求结果测试邮件浏览器✅ 正常评论通知（异步）服务器自己❌ SSL 失败 → 静默丢弃三、修复

把「异步提交」关掉，改回同步直发（就是测试邮件走的那条链路）：

yibu = 0

代价是评论提交时会多等 SMTP 一两秒，但换来的是确定性：失败会报错，不再静默丢失。

一句话结论：Typecho 插件的「异步提交」在虚拟主机上经常坏，因为它依赖服务器访问自己的域名。遇到「测试邮件正常但评论通知收不到」，第一个要查的就是这个开关。四、附带问题：发件人显示成了真名

用户反馈：邮件能收到，但收件箱里显示的发件人是自己的真名，不是配置里写的「苏的碎碎念」。

4.1 先确认到底是谁的问题

不猜，直接实测。方法：

用免费临时邮箱服务 mail.tm 的 API 建一个测试邮箱手写 SMTP 会话（Node 的 tls.connect 连 smtp.qq.com:465），从用户的 QQ 邮箱发一封测试信读临时邮箱收到的原始邮件头const msg = [ 'From: ' + enc('苏的碎碎念') + ' <2404999487@qq.com>', 'To: <' + to + '>', 'Subject: ...', ... ].join('\r\n');注意：curl 走 --url smtps:// 时容易卡在 AUTH 阶段（返回 334），不如手写会话可控。4.2 结果"from": { "address": "2404999487@qq.com", "name": "苏的碎碎念" }

邮件头里的发件人显示名完全正确。

4.3 结论

问题不在插件配置，在 QQ 邮箱自己的显示规则：

当你收到「由你自己的账号发出」的邮件时，QQ 邮箱会用你账号的邮箱昵称来显示，而不是邮件头里的 From 名字。

改法：QQ 邮箱 → 设置 → 账号 → 发件人姓名，改成想要的名字。

五、顺手修的：邮件模板预览页

后台的模板预览页有两个毛病：灰底只铺了一半、两个头像都是裂图。

原因是 template/preview.php 里有它自己的一套占位符替换表，而模板里新加的 {avatar}、{Pavatar}、{Phide} 不在里面，于是被原样输出成了 src="{avatar}"。

修复：

给预览页的替换表补上这三个占位符，头像用模拟 QQ 号（12345 / 123456）生成地址给 <body> 加 background-color:#ededed; margin:0; min-height:100vh，让灰底铺满六、重做文章目录树

原版主题自带的右侧目录有几个问题：position: fixed; top:0; height:100vh，从屏幕最顶端开始，且没有任何媒体查询 —— 手机上照样显示、直接盖住正文。

新做的目录树：

按正文里的 h1~h4 自动生成层级结构，圆点 + 竖连线 + 层级缩进点击平滑跳转，滚动时自动高亮当前小节position: fixed 固定在文章右侧，不随正文滚动踩坑记录

坑 1：element.style.display = '' 不等于「显示」

wrap.style.display = ''; // ✗ 只是清掉了内联样式，反而回落到 CSS 里的 display:none wrap.style.display = 'block'; // ✓ 必须显式写

当时目录结构已经正确生成（21 个链接、4 层嵌套、无报错），但页面上就是看不见，就是这一行的锅。

坑 2：文章宽度固定，屏越窄右侧余量越小

一开始用固定 200px 宽的目录 + 1280px 的隐藏阈值，结果 1366 / 1440 的笔记本全都看不到。要改成按可用空间自适应宽度。

七、经验总结「测试能过、实际不行」= 两条路径不一样。先找出两者分别走哪条代码路径，而不是反复改配置。失败被静默吞掉是最难查的 bug。看到 catch { return; } 就要警惕。别靠猜，用只读脚本把真实配置读出来。后台界面显示的和数据库里存的不一定一回事。改数据库前必须先备份原值。这次给插件停/启用时，第一版脚本没先 Plugin::init() 就写回，把插件列表写空了，靠提前存的备份才恢复回来。临时脚本用完立即删，并访问一次确认 404。发件人显示名这类问题，用临时邮箱读原始邮件头，一次就能分清是「配置错」还是「收件方行为」。

环境：Typecho 1.3.0 + nexmoe 主题，实测用 Chrome DevTools Protocol 读取真实渲染值时间：2026-10-07 凌晨一、起因：四条反馈

文章目录树做完之后，收到四条意见：

鼠标悬停时那块背景是直角的，要更圆润圆点和竖连线是灰色的，应该用主题色目录树压到正文了，没必要所有设备都显示 —— 顺带问：原主题是让所有设备都看到目录树吗？我这台笔记本（华硕天选3，Windows 缩放 150%）看不到目录树

前三条是样式与显示范围问题，第四条是布局问题 —— 而且根因完全不在目录本身。

二、原主题的目录：确实是「所有设备都显示」

先回答疑问。把用户最初下载的原版主题包解出来对比：

原版 post.php 里一条 @media 都没有，而且目录的定位是：

.nexmoe-post-right .nexmoe-fixed { position: fixed; z-index: 1000; height: 100vh; display: inline-block; top: 0; }

top: 0 + height: 100vh —— 从屏幕最顶端开始、占满整屏高度。

结论：原版就是所有设备都显示，在手机上还会直接盖住正文。 这是原版主题的设计缺陷，不是后加的。

所以这次的改法是：只在桌面宽屏显示，手机 / 平板 / 窄窗口一律不显示。

三、圆角与配色3.1 圆角.wb-toc a { border-radius: 4px; /* 改前：几乎看不出圆角 */ border-radius: 10px; /* 改后：明显的胶囊感 */ }3.2 圆点和竖连线改用主题色

改前的写法是「跟随文字颜色」：

.wb-toc a::before { background: currentColor; /* 文字是灰的，所以圆点也是灰的 */ opacity: .35; } .wb-toc ul ul::before { background: rgba(0,0,0,.09); /* 竖连线：写死的淡灰 */ }

改成直接取主题色变量：

.wb-toc a::before { background: var(--n-theme); opacity: .55; } .wb-toc ul ul::before { background: rgba(var(--n-theme-rgb), .35); } .wb-toc a:hover { color: var(--n-theme); background: rgba(var(--n-theme-rgb), .1); } .wb-toc a.active { color: var(--n-theme); background: rgba(var(--n-theme-rgb), .16); }

关键前提：主题色变量定义在 :root 上：

<style id="nexmoe-theme-color"> :root { --n-theme: <?php echo $__nThemeColor; ?>; --n-theme-rgb: <?php echo $__nThemeRgb; ?>; } </style>

因为是 :root，固定定位（position: fixed）的元素也能继承到，所以目录可以直接用主题色。用户以后改主题色，目录会自动跟着变。

实测确认：

目录项 border-radius : 10px 圆点 background-color : rgb(255, 78, 106) 竖连线 background-color : rgba(255, 78, 106, 0.35)四、压到正文 + 笔记本看不到：同一个根因4.1 先量，不要猜

用 Chrome DevTools Protocol 把文章容器整条结构链的盒子信息全部读出来：

var el = document.querySelector('#nexmoe-content .nexmoe-post'); while (el && el.tagName !== 'BODY') { var r = el.getBoundingClientRect(), cs = getComputedStyle(el); // 记录 rect / margin / padding / width / position el = el.parentElement; }

读出来的结果（视口 1280）：

< html > width=1265px < body > width=1100px padding-left=240px ← 病灶在这里 #nexmoe-content width=860px .nexmoe-primary width=860px .nexmoe-post width=820px rect: 343→11634.2 根因

主题把 body 硬编码成固定宽度：

body { width: 1100px; /* 固定，不是 100% */ padding-left: 240px; /* 左侧留给侧栏 */ margin: 0 auto; /* 在视口里居中 */ }

所以：视口再宽，正文右侧的留白也只有 (视口 - 1100) / 2。

1920 视口 → 右侧 402px，目录放得下1536 视口 → 右侧 245px，勉强1280 视口 → 右侧只有 118px，放不下

1280 是什么概念？Windows 缩放到 150% 的 1920 屏，CSS 视口宽度正好是 1280。这就是笔记本看不到目录的原因。

4.3 第一次尝试（失败）：把文章整体左移

思路很自然：左侧那 240px 看起来是空的，把文章左移就能腾出右侧空间。

/* 第一版（错误方案） */ body.nexmoe-single #nexmoe-content { left: max(-150px, min(0px, calc((100vw - 1580px) / 2))); }

数据上看是成功的：1280 视口下右侧余量从 118px 变成 232px，目录 200px 宽显示正常。

但截图一出来就露馅了：文章左移后，撞上了左侧的「文章分类 / 标签云」侧栏 —— 文章标题和正文左侧被侧栏盖住了一半。

原因：那 240px 并不是空白，它是 .nexmoe-secondary 侧栏的位置，只是在 1024px 以下才会 display: none。

教训：改布局一定要截图看整体，只量「目标元素」的数值会漏掉相邻元素的冲突。4.4 最终方案：让文章在窄屏下收窄

既然不能左移，就换个方向：把文章本身变窄一点，两侧各让出一部分空间。文章保持居中，右侧就稳定空出一块。

@media screen and (min-width: 1024px) { body.nexmoe-single .nexmoe-post { max-width: min(820px, max(640px, calc(100vw - 720px))); margin-left: auto; margin-right: auto; } }

宽度随视口线性变化：

视口文章宽度≥1540820px（保持原样，大屏完全不受影响）1440720px1366646px≤1280640px（下限）

只作用于文章页 / 独立页（body.nexmoe-single），首页和归档页不受影响。

4.5 实测结果

用调试协议逐档量（13 档，从 1920 到 390）：

视口正文位置目录结论1920663→14831503→1703（宽 200）不重叠，间距 20px1600503→13231343→1543（宽 200）不重叠1536473→12891309→1509（宽 200）不重叠1440473→11931213→1413（宽 200）不重叠1366473→11191139→1339（宽 200）不重叠1280（150% 缩放笔记本）433→10731093→1271（宽 178）不重叠1200 及以下—不显示已隐藏手机 390—不显示已隐藏

另外还校验了一条硬约束：左侧常驻的抽屉图标条占视口 0~80px，正文左边缘必须大于 82px —— 全部档位最小是 305px，安全。

五、显示门槛的最终参数var MIN_W = 130, MAX_W = 200, GAP = 20, EDGE = 10; if (window.innerWidth < 1152) { wrap.style.display = 'none'; return; } var avail = window.innerWidth - postRect.right - GAP - EDGE; if (avail < MIN_W) { wrap.style.display = 'none'; return; } wrap.style.width = Math.round(Math.min(MAX_W, avail)) + 'px'; wrap.style.left = Math.round(postRect.right + GAP) + 'px'; wrap.style.display = 'block'; // 必须显式写 block

配合 CSS 的媒体查询（两份样式表都要写，因为暗色模式是替换样式表、不换 body 类）：

@media screen and (max-width: 1279px) { .wb-toc-wrap { display: none !important; } }

改完后的完整效果：

≥1280px 视口：显示目录，宽度 178~200px 自适应≤1200px：不显示圆点、连线、悬停底色全部跟随主题色暗色模式单独一套（文字浅白 + 主题色点缀）六、经验总结「元素异常」先量再改。用调试协议读 getBoundingClientRect() 和 getComputedStyle()，比反复改代码让用户上传试错快得多。量一个元素不够，要看整条结构链。这次的根因在 <body> 上，只看 .nexmoe-post 永远找不到。改完必须截图看整体。第一次的「左移」方案数据全对，但视觉上撞了侧栏 —— 数据对不等于效果对。别再踩 style.display = '' 这个坑：它只会清掉内联样式，反而回落到 CSS 里的 display: none。主题色变量定义在 :root 时，position: fixed 的元素也能继承，不用重复注入。响应式阈值要对着真实场景定。Windows 常见缩放下：1920@150% = 1280、1920@125% = 1536、1440@125% = 1152 —— 定断点时要按这些实际值算，而不是按屏幕分辨率。

Typecho 插件排查实录：从装不上到发不出邮件环境：Typecho 1.3.0 · PHP 7.4.33 · 虚拟主机（美国节点）记录一次把插件从「全挂」修到「能用」的完整过程，含可直接复用的排查方法。引言

一次集中排查了 5 个插件的三类问题：

装不上 —— 点启用要么「无法启用插件」，要么直接 500发不出邮件 —— CommentNotifier 报 MAIL FROM command failed, 502 Invalid parameters头像不显示 —— 评论区头像全是破图

三类问题看起来无关，其实根因只有两个：Typecho 的插件命名规则，和外部服务的可用性。

一、插件装不上：文件夹名必须等于类名1.1 现象

后台点「启用」，跳转到：

/index.php/action/plugins-edit?activate=Links-1.2.7

然后报「无法启用插件」，或者「页面没有找到」。

1.2 原因

Typecho 加载插件时，用文件夹名去拼期望的类名。源码在 var/Typecho/Plugin.php 的 portal() 方法：

public static function portal(string $pluginName, string $path): array { switch (true) { case file_exists($pluginFileName = $path . '/' . $pluginName . '/Plugin.php'): $className = "\\" . PLUGIN_NAMESPACE . "\\{$pluginName}\\Plugin"; break; case file_exists($pluginFileName = $path . '/' . $pluginName . '.php'): $className = "\\" . PLUGIN_NAMESPACE . "\\" . $pluginName; break; default: throw new PluginException('Missing Plugin ' . $pluginName, 404); } return [$pluginFileName, $className]; }

关键：$pluginName 来自 URL 的 activate 参数，也就是文件夹名。

文件夹叫 Links → 期望类 \TypechoPlugin\Links\Plugin文件夹叫 Links-1.2.7 → 期望类 \TypechoPlugin\Links-1.2.7\Plugin ← 含连字符，根本不是合法类名

文件里写的类名叫什么，完全不影响。找不到期望的类名，class_exists() 返回 false，就是「无法启用插件」或 500。

1.3 常见踩坑对照你下载的文件夹名里面的类名Typecho 期望的类名结果Links-1.2.7Links_Plugin\TypechoPlugin\Links-1.2.7\Plugin✗typecho-Comment2MailComment2Mail_Plugin\TypechoPlugin\typecho-Comment2Mail\Plugin✗ColorHighlight-for-typecho-masterColorHighlight_Plugin...\ColorHighlight-for-typecho-master\Plugin✗wzTypechoCodeHighlight_Plugin\TypechoPlugin\wz\Plugin✗LinksLinks_Plugin\TypechoPlugin\Links\Plugin✓

规律：GitHub 打包下载的仓库，文件夹名往往带 -master、-1.2.7、-main 后缀，必须去掉。

1.4 正确写法（Typecho 1.2 / 1.3）

目录结构

usr/plugins/ └── MyPlugin/ ← 文件夹名 = 类名 └── Plugin.php

Plugin.php 完整示例

<?php namespace TypechoPlugin\MyPlugin; // ← 必须与文件夹名一致 use Typecho\Plugin\PluginInterface; use Typecho\Widget\Helper\Form; if (!defined('__TYPECHO_ROOT_DIR__')) { exit; } class Plugin implements PluginInterface // ← 类名就叫 Plugin { public static function activate() { /* ... */ } public static function deactivate() { /* ... */ } public static function config(Form $form) { /* ... */ } public static function personalConfig(Form $form) {} // 可选但建议保留 }

⚠️ 三个易错点：

不要用老接口 Typecho_Plugin_Interface —— 1.2 起已换成命名空间写法，用错直接 500插件文件省略结尾 ?> 是标准做法，不要加文件夹名不要加版本后缀。我在这上面栽过：把插件目录命名成 Lantern_1.2，结果点启用直接「页面没有找到」二、启用时报 500：一个藏在源码里的真 bug

有些老插件即使文件夹名改对了，启用仍然 500。以下是排查出的两类原因。

2.1 PHP 里 || 返回的不是布尔值

某访问统计插件的建表失败分支：

if (('Mysql' == $type && $code == (1050 || '42S01'))) {

1050 || '42S01' 在 PHP 里恒等于 1 —— || 返回第一个真值，而 1050 是真值。所以这个判断等价于 $code == 1，「数据表已存在」的判断永远不成立，必然走进 else 抛异常 → 500。

原意是「错误码是 1050（表已存在）或 42S01（表不存在）就当作成功」，想用 || 表达「或」，写错了。

正确改法（不依赖错误码，更稳）：

// 先探测表是否存在 try { $db->query("SELECT 1 FROM `$table` LIMIT 1", \Typecho\Db::READ); return '数据表已存在，插件启用成功'; } catch (\Throwable $e) { // 不存在，继续建表 }2.2 老 API 类名在 1.3 下的对应关系Typecho 1.1 老写法Typecho 1.2 / 1.3 写法Typecho_Db::get()Typecho\Db::get()Typecho_Widget::widget('Widget_Options')Widget\Options::alloc()Typecho_Request::getInstance()Typecho\Request::getInstance()Typecho_Plugin_ExceptionTypecho\Plugin\ExceptionTypecho_Plugin_InterfaceTypecho\Plugin\PluginInterface

1.3 保留了一部分兼容别名，所以有些老代码「看起来能跑」，但迟早出问题，建议一并改掉。

三、邮件发不出去：发件邮箱填成了服务器地址3.1 现象

CommentNotifier 报错：

The following From address failed: : MAIL FROM command failed, Invalid paramenters ,502,SMTP server error: MAIL FROM command failed Detail: Invalid paramenters SMTP code: 5023.2 定位方法：用一次性诊断脚本读真实配置

邮件插件的配置存在数据库里，从后台看不出全貌。可以上传一个带 token 的只读 PHP 脚本，读完立即删除。

脚本要点：

// 1. 用 SHOW TABLES 自动识别表前缀（不要用正则去猜 config.inc.php） $r = mysqli_query($conn, "SHOW TABLES"); while ($row = mysqli_fetch_array($r)) { $tables[] = $row[0]; } foreach ($tables as $t) { if (substr($t, -7) === 'options') { $prefix = substr($t, 0, -7); break; } } // 2. 读各插件配置，密码字段掩码 $r = mysqli_query($conn, "SELECT value FROM `{$prefix}options` WHERE name='plugin:CommentNotifier' LIMIT 1"); // 3. URL 带 token，只有自己知道 if ($_GET['k'] !== '你的随机token') { http_response_code(404); exit; }

查出 CommentNotifier 的实际配置：

STMPHost = smtp.qq.com ✓ SMTPUserName = 2404999487@qq.com ✓ SMTPPassword = (16位) ✓ SMTPSecure = ssl / SMTPPort = 465 ✓ from = smtp.qq.com ✗ ← 问题在这里

「SMTP邮箱地址」被填成了服务器地址 smtp.qq.com，而不是邮箱地址。

3.3 复现验证

诊断脚本里真实走一遍 SMTP 握手，只到 MAIL FROM 就断开（不发信）：

✓ 登录: 235 Authentication successful ✓ MAIL FROM:<2404999487@qq.com> → 250 OK 【复现】MAIL FROM:<smtp.qq.com> → 502 Invalid input

报错完全一致，根因确认。

3.4 QQ 邮箱的正确配置项目值邮件推送方式SMTPSMTP服务器地址smtp.qq.comSMTP登录用户你的QQ号@qq.comSMTP邮箱地址（发件邮箱）你的QQ号@qq.com，必须与登录用户一致SMTP登录密码授权码（不是 QQ 密码）加密方式SSL，端口 465；或 TLS，端口 587发信方案传统直发（直连 SMTP）

授权码获取：QQ邮箱 → 设置 → 账号 → 开启 POP3/SMTP 服务 → 生成授权码。

要点：QQ 邮箱要求 MAIL FROM 的地址必须等于认证账号，写别的（哪怕是同域的别名）都会被拒。

四、评论头像不显示4.1 原因：主题依赖的第三方服务已经死了

主题的 comments.php 里写死了头像来源：

$host = '//avatar.dawnlab.me'; // QQ 邮箱 → //avatar.dawnlab.me/qq/{qq} // 其他 → //avatar.dawnlab.me/gravatar/{md5}

实测 avatar.dawnlab.me 返回 HTTP 000（连不上），服务已停。所以所有评论头像都是破图。

4.2 各头像源的国内可达性实测

头像 URL 是访客浏览器去加载的，所以国内可达性是首要指标：

头像源HTTP 状态备注q1.qlogo.cn（QQ官方）200 ✓稳定gravatar.loli.net（Gravatar 国内镜像）200 ✓推荐weavatar.com200 ✓备选cravatar.cn时好时坏不稳定secure.gravatar.com（官方）000 ✗国内被墙www.gravatar.com（官方）000 ✗国内被墙avatar.dawnlab.me000 ✗服务已停

关键结论：Gravatar 官方域名在国内打不通，必须用镜像。

4.3 方案：d=404 + onerror

需求是「有 Gravatar 就用，没有就用随机头像」。不需要在后端做判断，用 HTTP 状态码 + JS 回落即可：

<img src="https://gravatar.loli.net/avatar/{md5}?s=100&r=G&d=404" onerror="this.onerror=null;this.src='{随机头像API}'">该邮箱有 Gravatar → 正常返回图片，显示该邮箱没有 Gravatar → Gravatar 返回 404 → 触发 onerror → 换成随机头像镜像本身挂了 → 同样触发 onerror → 换成随机头像

三种情况全覆盖。d=404 是关键 —— 不加它，Gravatar 会返回一张默认图（200），onerror 就不会触发。

4.4 邮件里不能用这套方案

邮件客户端会过滤 JavaScript，onerror 无效。所以邮件模板里的头像必须用「总能出图」的地址：

https://gravatar.loli.net/avatar/{md5}?s=96&r=G&d=mp

d=mp（mystery person）保证没有 Gravatar 时也返回一张图，不会破图。

五、哪些插件该淘汰

排查后，站上这几个插件建议处理：

插件状态建议CommentNotifier唯一配置正确、可用的邮件提醒保留，改 from 一处即可CommentToMail配置 port=25 + ssl 不匹配停用Comment2Mail无配置记录停用CommentsByQQ依赖 pxwei.com/php_api.php，实测 404；且用 1.1 老接口停用AvatarQQ用 1.1 老接口，1.3 下不可用；功能已被主题头像逻辑覆盖停用关于 CommentsByQQ 的真相

它的实现是：

curl_setopt($ch, CURLOPT_URL, "http://www.pxwei.com/php_api.php?qq=" . $options->plugin('CommentsByQQ')->qq . "&url=" . $comment->permalink);

它把请求转发给第三方的 pxwei.com，由那个服务推送 QQ 消息。

域名还活着，但 php_api.php 返回 404，接口已下线 → 插件彻底失效它还是个通知类插件，不是头像插件，容易和邮件提醒功能重复

网上流传的「QQ 机器人打通」版本是另一个实现（基于 NoneBot + go‑cqhttp），需要你自己长期运行一个 QQ 机器人：

go‑cqhttp 已于 2024 年停止维护替代方案是 NapCat / Lagrange.OneBot（OneBot 协议）需要一台常开的设备跑机器人，且有账号被风控/冻结的风险

如果不想折腾，用邮件提醒就足够了。

六、经验总结6.1 交付插件前，先核对命名# 看插件里的命名空间最后一段 grep -n "^namespace" usr/plugins/*/Plugin.php

文件夹名必须与命名空间最后一段完全一致，不能加任何后缀。

6.2 「CSS 写了却不生效」先实测，别猜

用 Chrome DevTools Protocol 直接读元素的真实渲染值，不要靠推断反复上传试错：

chrome.exe --headless --remote-debugging-port=9333 --window-size=1440,900 about:blank # 然后用 Node 内置 WebSocket 连上去发 Runtime.evaluate

关键 JS：

var r = el.getBoundingClientRect(); // 真实渲染尺寸 var cs = getComputedStyle(el); // 实际生效的样式 img.naturalWidth + 'x' + img.naturalHeight; // 图片原始尺寸 // 列出所有匹配的选择器，判断哪条规则真的生效 document.styleSheets[i].cssRules[j].selectorText

这次就是靠它才发现：CSS 规则完全正确，但选择器方向写反了 —— 把类加在 <body> 上，却写成 #content .那个类 ...（要求它是 #content 的后代），而实际它是祖先，选择器一次都没匹配上。

6.3 改数据库前必须先备份

用脚本批量停用插件时要小心：Typecho\Plugin::export() 在没有先 Plugin::init($data) 的情况下返回空数组，直接写回数据库会把所有插件配置清空。

正确做法：

$data = json_decode($row['value'], true); // 先从库里读出来 \Typecho\Plugin::init($data); // 喂给 Plugin \Typecho\Plugin::deactivate($name); // 再操作 $db->query($db->update('table.options') ->rows(['value' => json_encode(\Typecho\Plugin::export())]) ->where('name = ?', 'plugins'));

并且操作前先把原值存一份，出问题能立刻回滚。

6.4 外部依赖是最大的不确定性

这次三个问题里，两个来自外部服务：

主题头像依赖的 avatar.dawnlab.me —— 服务已停CommentsByQQ 依赖的 pxwei.com/php_api.php —— 接口已下线

凡是把功能寄托在别人的免费服务上的，都要有失效预案。 Gravatar 官方域名在国内被墙这件事，也说明「用官方源」不等于「更可靠」。

6.5 排查顺序建议

遇到插件问题，按这个顺序走，能少走弯路：

文件夹名对不对（占一半以上的问题）看 PHP 错误日志（500 的具体原因都在里面）用诊断脚本读真实配置（后台看到的不一定是实际值）实测外部依赖是否可达（curl -o /dev/null -w "%{http_code}"）实测页面真实渲染（别靠猜）附：常用的几行命令# 测外部服务可达性 curl -sL --connect-timeout 8 -o /dev/null -w "%{http_code} %{content_type}\n" "https://example.com/img.png" # 看插件命名空间 grep -n "^namespace" usr/plugins/*/Plugin.php # 看某个文件是否被改过（对比原始包） diff <(unzip -p plugin.zip path/file) path/file

为了修改封面图高度折腾了一晚上，Workbuddy模型由Space-Bunny转Deepseek4.1flash终于给修好，还生成了个Skill.md，给大家参考参考。

name: webpage-render-measuredescription: 当浏览器自动化工具（agent-browser 等）在本机起不来、或「CSS 明明写了却不生效」「元素尺寸不对」这类问题时，用本机已有的 Chromium 通过 Chrome DevTools Protocol 精确测量网页元素的真实渲染尺寸与生效样式，并能整页截图。也含「Typecho 主题/插件通过 FTP 部署」的完整流程与命名规则。agent_created: true

网页真实渲染测量（CDP 直连）什么时候用用户说「CSS 改了没效果」「元素太大/太高/位置不对」，需要知道元素实际渲染成什么样需要知道到底是哪条 CSS 规则生效了（而不是靠推测）agent-browser 或其它浏览器自动化工具的守护进程在本机起不来（Windows 上常见，报 SIGTERM 无输出）

需要给页面截图看效果

核心原则：先实测，再动手改。 不要在没看到实际渲染值的情况下反复改代码然后让用户上传试错。

前提：找到 Chromiumagent-browser 起不来不代表没有浏览器。Playwright 装的 Chromium 通常还在：ls "C:/Users/ASUS/AppData/Local/ms-playwright/" # 看有哪些版本目录find "C:/Users/ASUS/AppData/Local/ms-playwright/chromium-*/" -name "chrome.exe" | head -3

典型路径：

C:\Users\ASUS\AppData\Local\ms-playwright\chromium-1234\chrome-win64\chrome.exe也可以用系统自带的 Edge（Windows 必有）：C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe

方法一：整页截图（最简单）

CHROME="C:/Users/ASUS/AppData/Local/ms-playwright/chromium-1234/chrome-win64/chrome.exe""$CHROME" --headless --disable-gpu --no-sandbox --hide-scrollbars \ --window-size=1440,2400 --virtual-time-budget=15000 \ --screenshot="C:/path/out.png" "https://example.com"

--virtual-time-budget=15000 给 JS 和图片 15 秒加载时间，必须加，否则截图是空的截图后用 Read 工具直接查看（能看图）--window-size 高度给大一点可以看到整页输出 wsalookup 之类的 stderr 报错可以忽略方法二：精确测量（关键武器）

用 --remote-debugging-port 启动，通过 CDP 发 JS 拿真实渲染值。重大便利：Node 22 内置了全局 WebSocket，所以不需要 playwright 等任何依赖。见 scripts/measure.js（可直接改 URL 使用）。核心步骤：

spawn 启动 Chrome，带 --headless --remote-debugging-port=9333轮询 http://127.0.0.1:9333/json 直到拿到 target用 new WebSocket(target.webSocketDebuggerUrl) 连上发 Page.enable / Runtime.enable / Page.navigatesleep(8000~9000) 等图片和 JS 加载完（关键，不等就是拿到加载前的值）Runtime.evaluate 跑 JS，取回 getBoundingClientRect() + getComputedStyle()结束后 ws.close() + child.kill()测量脚本要抓什么// 元素真实渲染尺寸var r = el.getBoundingClientRect();r.width, r.height

// 生效的计算样式var cs = getComputedStyle(el);cs.height, cs.maxHeight, cs.position, cs.objectFit, cs.overflow

// 图片原始尺寸（判断是不是图片本身太大）img.naturalWidth, img.naturalHeight, img.complete

// 有没有内联样式在捣乱img.getAttribute('style')

// 列出所有匹配的选择器及其声明 —— 定位"哪条规则真的生效"for (sheet of document.styleSheets) for (rule of sheet.cssRules)

if (rule.selectorText.includes('目标类名')) rule.selectorText, rule.style.height, ...模拟手机视口

await send('Emulation.setDeviceMetricsOverride', { width: 390, height: 800, deviceScaleFactor: 1, mobile: true });await send('Page.navigate', { url });await sleep(8000);

坑

不等加载就测 → 拿到加载前的值（图片未加载时尺寸是 0 或占位值）

Node 版本：WebSocket 是 Node 22 才有的全局变量。用旧 Node 会报 WebSocket is not definedChrome 每次启动需要 1~3 秒，轮询要留够次数（25 次 × 600ms）Emulation.setDeviceMetricsOverride 之后要重新 Page.navigate 才生效常见真凶对照表现象检查什么

CSS 规则看着完全正确、优先级也对，但不生效选择器方向写反了。把类加在 上，却写成 #content .那个类 ...（要求它是 #content 的后代）。实测 getComputedStyle 会暴露真实值 ≠ 期望值

元素比预期高/大

先看 cs.height 实际值；再看容器和内容的 getBoundingClientRect()

图片撑开容器

看 naturalWidth/naturalHeight。图片本身是竖版大图时，仅限制容器高度不够，要 position:absolute + object-fit:cover 让它脱离文档流

改了没效果

看资源 URL 有没有 ?v= 版本号；没有就是缓存问题配套：Typecho 主题/插件的 FTP 部署

命名规则（Typecho 1.2/1.3，最容易踩的坑）

Typecho 按文件夹名拼出期望的类名：// var/Typecho/Plugin.php 的 portal()$className = "\\" . PLUGIN_NAMESPACE . "\\{$pluginName}\Plugin";// 即 \TypechoPlugin\<文件夹名>\Plugin规则：文件夹名必须严格等于类名约定，不能加 _1.2、_v3、-master 之类后缀。插件正确结构：<?phpnamespace TypechoPlugin\Xxx; // Xxx 必须等于文件夹名use Typecho\Plugin\PluginInterface;class Plugin implements PluginInterface{

public static function activate(): string { ... } public static function deactivate(): string { ... } public static function config(Form $form) { ... }

}

不要用老接口 Typecho_Plugin_Interface（1.2+ 已移除）插件文件省略结尾 ?> 是标准做法类名对不上 → 后台点启用报「无法启用插件」或直接 500FTP操作列目录

curl -s -u "用户名:密码" "ftp://主机/路径/" --list-only

下载

curl -s -u "用户名:密码" "ftp://主机/路径/文件" -o 本地文件

上传

curl -s -u "用户名:密码" -T 本地文件 "ftp://主机/路径/文件" -w "%{http_code}\n"

成功返回 226常见虚拟主机根目录是 /wwwroot（不一定是 /www）Typecho 根：/wwwroot/ 下有 var、usr、admin、index.php、config.inc.php主题在 /wwwroot/usr/themes/<主题名>/插件在 /wwwroot/usr/plugins/<插件名>/改文件前先把服务器原文件下载备份交付完整主题包

给用户上传用的包要给完整主题（可直接整体覆盖），不要只给改动的几个文件。用 Node 手写 zip 时注意：

local header 和 central directory 的 flags 都要设 0x0800（UTF-8 文件名），否则中文文件名乱码排除 .bak、.DS_Store、__MACOSX、.git压缩后比原文件大时回落到 store（method=0）打完包要回读验证：逐个 entry inflate → 算 CRC32 → 比对大小 → 与磁盘源文件逐字节比对给主题加防缓存（避免"改了没效果"）Typecho 核心自己不给静态资源加版本号，所以改 CSS 后浏览器一直用缓存。修法：// 用文件修改时间做版本号$ver = @filemtime(__DIR__ . '/../source/css/style.css');if (!$ver) { $ver = '1.0'; } // 读不到时的兜底