时间：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 博客从一个虚拟主机搬到另一个虚拟主机；也含「网站突然坏了要恢复」的应急流程更新时间：2026-10-07（第 2 版，新增星辰云主机恢复经验）一、开工前：先要齐这些信息

新主机那边要问客服/在面板里找到：

项目例子在哪找FTP 地址 + 端口mf.iqy.im　21主机开通邮件 / 面板FTP 账号 / 密码ocjffuda / xxx同上面板地址 + 账号密码https://xxx/qingyun/index.php同上数据库地址/名/账号/密码localhost / ocjffuda / …同上数据库管理入口https://xxx:4413/mysql/同上站点根目录名/wwwroot（也可能是 /htdocs、/public_html）面板文件管理里看一眼能不能选 PHP 版本要能选到 7.4面板「PHP 版本」页主机平台类型荧控制台（星辰云/轻云）还是标准 cPanel/DirectAdmin看面板界面（见下面「平台类型」）

⚠️ 三个必查项，少一个都可能白搬：

FTP 能不能连上（有些主机只给网页文件管理器）要不要备案（国内主机没备案 = 绑不了域名）PHP 版本能不能选到 7.4（Typecho 1.3 在 7.2 下会全站白屏）⭐ 先认清你的主机是哪种平台（很重要）

荧控制台（星辰云 aspanel.starzv.com、轻云 mf.iqy.im/qingyun 都是这套）有个特殊规矩：

FTP 里传上去的文件，网站读不到；必须用面板的「文件管理」上传才算数。

所以：

如果面板地址是 /vhost/ 或 /qingyun/ 这种 → 属于荧控制台 → 文件一律走面板「文件管理」上传标准 cPanel/DirectAdmin 类 → FTP 直接传就行

判断方法很简单：用 FTP 传个小文件上去，浏览器访问一下；能访问就是普通平台，404 就是荧控制台。

二、搬家六步第 1 步：备份现在的网站（两个东西）

① 网站文件：用 FTP 工具（FileZilla）把站点根目录整个下载到本地

② 数据库：

打开现在的数据库管理页（phpMyAdmin）登录左侧点一下自己的数据库名（⚠️ 千万别选「整个服务器」）顶部点「导出」→ 选 「快速」 → 格式 SQL → 点「执行」下载得到一个 .sql 文件

③ 顺手清理 SQL（很重要，不然到新主机会报错）：用记事本打开这个 .sql，删掉这两类行：

CREATE DATABASE IF NOT EXISTS `旧库名` ... ; ← 整行删掉 USE `旧库名`; ← 整行删掉

另外如果文件里还有别的数据库的段落（比如别人的 test 库），从那一行开始后面的全删。

第 2 步：文件放到新主机面板 → 文件管理 → 进 wwwroot 目录

把本地下载的网站文件全部上传

普通平台（cPanel）：用 FileZilla 把文件夹内容拖进 /wwwroot荧控制台：必须用面板的「文件管理」上传（FTP 传的不生效）上传完检查：/wwwroot 里应该直接是 admin、usr、var、index.php、config.inc.php⚠️ 不要出现多一层文件夹（比如 /wwwroot/wwwroot/）

如果用 zip 上传，注意两件事：

一定要用没问题的 zip。Windows 自带压缩工具打的包在 Linux 面板解压会坏（文件名变成带 \ 的一坨）。判断方法：解压后如果看到 var\Typecho\Db.php 这种名字，就是坏了，删掉重来。⚠️ 面板自动解压会「跳过已存在的文件」！所以整包传完解压后，必须把 config.inc.php 再单独上传一次覆盖掉旧的（这一步最常被漏，漏了网站就报数据库错误）。第 3 步：数据库导进去打开新主机的 phpMyAdmin，登录左侧点新主机的数据库名顶部「导入」→ 选择第 1 步那个清理好的 .sql拉到底点「执行」看到 「导入成功，执行了 XX 条语句」 就对了第 4 步：改 config.inc.php（关键！）

网站根目录的 config.inc.php 里存着旧主机的数据库信息，必须改成新主机的：

$db->addServer(array ( 'host' => 'localhost', ← 一般不用改 'port' => 3306, 'user' => '新主机数据库用户名', ← 改 'password' => '新主机数据库密码', ← 改 'charset' => 'utf8mb4', 'database' => '新主机数据库名', ← 改 'engine' => 'InnoDB', ...

改完传回 /wwwroot/config.inc.php 覆盖（荧控制台走面板上传）。

第 5 步：绑域名 + PHP 版本

在新主机面板里：

域名绑定 → 添加你的域名 → 目录选 wwwroot → 记下面板给出的解析要求（A 记录 IP 或 CNAME）PHP 版本 → 选 7.4 → 保存第 6 步：改域名解析

在 Cloudflare（或你域名的 DNS 服务商）：

找到 blog 那条记录按第 5 步面板给的解析要求修改建议先把小云朵点灰（DNS only）验证，正常了再开橙云三、搬完检查清单

打开你的域名，逐项确认：

[ ] 首页能打开，标题正确[ ] 随便点开 2~3 篇文章，正文、图片正常[ ] 封面图能显示[ ] 后台能登录：你的域名/admin/[ ] 后台 → 外观，主题配置还在（封面图地址池、摘要字数这些）[ ] 速度实测：手机流量 + 电脑都打开试试，明显卡的话考虑换主机

出问题对照表：

现象原因怎么办全站白屏 / 500PHP 版本不是 7.4面板切成 7.4403 / 目录列表文件没传全重新传，检查有没有多一层文件夹样式全乱、图片不显示主题目录没传全检查 /wwwroot/usr/themes/主题名/页面报 Error establishing a database connectionconfig.inc.php 还是旧主机的（解压时被跳过没覆盖）单独上传一次 config.inc.php 覆盖面板显示「空间占用 0 MB」+ 网站 503平台的「已发布内容」被删了（≠ 磁盘文件）走面板文件管理重新上传整包导入 SQL 报 #1044 Access deniedSQL 里带了 CREATE DATABASE删掉那行重新导导入 SQL 报 #1064 语法错误SQL 文件被改坏了重新导出，别用编辑软件乱存刚传的文件访问 404荧控制台的 FTP 文件不生效改用面板「文件管理」上传四、网站突然坏了怎么恢复（应急）

网站打不开时，先分两种情况：

情况 A：面板显示「空间占用 0 MB」或明显偏小→ 平台的「已发布内容」被删了（很可能是删文件时把 wwwroot 整个选上删了）恢复步骤：

面板 → 文件管理 → 进 wwwroot上传网站整包 zip → 解压再单独上传一次 config.inc.php 覆盖（关键，别漏）等 1 分钟，访问网站验证

情况 B：面板有占用，但网站报数据库错误→ 多半是 config.inc.php 里的数据库信息不对恢复步骤：单独上传正确的 config.inc.php 覆盖即可

情况 C：网站 200 但样式乱 / 图片不显示→ 主题文件没传全，检查 /wwwroot/usr/themes/主题名/

五、注意事项旧主机先别退！等新站全部验证 OK 再处理（最好观察一周）搬家期间不要在任何一边写新文章，不然会漏删文件时只删文件夹里面的，别把文件夹本身选了——选的时候特别容易连带，一旦把 wwwroot 一起删掉，网站立刻 503荧控制台特有：FTP 里能看到的文件 ≠ 网站实际用的文件；面板的「文件管理」才是权威换主题相关：主题目录名不能随便改，Typecho 是按目录名存配置的，改名会丢主题设置如果新主机访问慢，先试试手机流量（有的香港线路对某些运营商不友好）；联通能开不代表移动能开六、当前站点信息（2026-10-07）项目值博客地址https://blog.syicxh.cc.cd程序Typecho 1.3 + SuNexmoe 主题（PHP 7.4）现用主机星辰云（香港）：面板 https://aspanel.starzv.com/vhost/，站点根 /wwwroot备用主机轻云互联（香港）：面板 https://mf.iqy.im/qingyun/index.php，站点根 /wwwroot（文件和数据库都已部署好，随时可切）域名解析Cloudflare，指向星辰云七、不想自己弄怎么办

把这份手册 + 密码信息给 AI 助手（WorkBuddy 之类），让它按《给 AI 版手册》操作；或者你自己用 FTP + phpMyAdmin 两块界面手工做，最稳。

AI执行版适用：Typecho 1.3 + SuNexmoe 主题，虚拟主机 → 虚拟主机迁移；含「主机故障恢复」流程沉淀时间：2026-10-07（第 2 版：基于星辰云 → 轻云迁移 + 星辰云恢复两次实战）使用前提：先读「用户偏好与硬性规则」，再按 S0~S7 执行〇、用户偏好与硬性规则（必读）

文件存放：

工作文件（中间产物、脚本、解压目录）→ D:\ProgramData\workbuddy-data\workfiles-<任务名>\交付物（备份、文档、最终包）→ D:\Susuisuinian\博客备份\<分类>\禁止把文件散落在 D:\Xtemp（Bash 的 /tmp）或 C 盘临时目录删除纪律：只删自己明确知道来历的文件；绝不按修改时间批量删共享临时目录（曾误删用户的 QQ 截图，不可恢复）。删除优先用回收站：D:\Program Files\WorkBuddy\resources\app.asar.unpacked\cli\vendor\genie-trash\win32-x64.exe <绝对路径>（输出 OK 在 stderr）用户观感：用户可能全程旁观，喜欢「先给结论、再给数据」；不要长时间静默；长任务必须报进度；卡住要早说，不要闷头试一小时（曾因平台怪架构卡了整晚，用户很不满）。用户明确说「不要动我网站」时，只做本地文件操作。交付物最小化：只交付用户点名要的东西；中间物不要塞给用户看。一、开工前必须向用户索取的信息项目用途旧主机 FTP 地址/端口/账号/密码备份文件旧主机数据库面板地址 + 账号密码导出 SQL新主机 FTP 地址/端口/账号/密码上传文件新主机面板地址 + 账号密码绑域名、改 PHP 版本、传文件新主机数据库地址/库名/账号/密码导入 SQL、改 config新主机站点根目录名通常 /wwwroot，进面板文件管理确认主机平台类型荧控制台？（决定文件怎么传，见 S0）域名 DNS 在哪（Cloudflare？）最后切换解析二、环境与工具（本机已验证可用）工具说明C:/Users/ASUS/.workbuddy/binaries/node/versions/22.22.2-6/node.exeNode（写 CDP 脚本）C:/Users/ASUS/.workbuddy/binaries/python/envs/default/Scripts/python.exePython（含 Pillow）curl（Git Bash 自带）FTP 上传/下载/列目录、HTTP 请求Python ftplib批量 FTP 首选（单连接复用，618 文件约 15 分钟）Edge + CDP面板自动化：msedge.exe --remote-debugging-port=PORT --user-data-dir=独立目录 <url>回收站工具见「硬性规则」第 2 条

⚠️ Bash 里调 cmd/powershell 会被安全策略拦（词面命中即拦），需要 PowerShell 就直接用 PowerShell 工具。

三、执行流程（S0~S7）S0 勘察（5 分钟，必做）# FTP 是否可用 curl -s -u "user:pass" "ftp://host/" --list-only | head # 端口扫描（Bash 内建，无需 nmap） for p in 21 22 80 443; do timeout 5 bash -c "echo > /dev/tcp/IP/$p" && echo "$p 开放"; done # 站点根目录（FTP 根看到 wwwroot？还是就是站点？） curl -s -u "user:pass" "ftp://host/wwwroot/" --list-only | head # 判断面板是什么系统（看 HTML 特征） curl -s "https://面板地址/" | grep -oP '<title>[^<]*'

决策：

荧控制台（面板 URL 含 /vhost/ 或 /qingyun/）→ 文件必须走面板 WebFTP，FTP 传的不发布标准平台 → FTP 路线（最稳）判断方法：FTP 传一个小文件，浏览器访问；404 = 荧控制台S1 备份旧站# 1) 文件：Python ftplib 递归（探测目录 + 下载），或 curl -T / -u "..." "ftp://host/path" # 单文件上传 curl -u "..." "ftp://host/path" -o 本地 # 下载 # 2) 数据库：见下方「phpMyAdmin 坑」

phpMyAdmin 导出坑（重要）：

POST route=/export 走 curl / 自动化常只返回 AJAX 外壳（页面提示 Javascript must be enabled）→ 导出让用户手动在浏览器点（快速 → SQL → 执行），最省事用户导出后务必检查 SQL 头部，清理：CREATE DATABASE、USE、以及别人的库的整段（见 S3）也可用面板自带「数据库备份」（?c=shell&a=mysqldumpout，body passwd=），但可能因缺 PROCESS 权限失败S2 准备上传包# ⚠️ 必须用 Python zipfile（正斜杠）！Windows 自带压缩工具打的包在 Linux 面板解压会变成 # "var\Typecho\Db.php" 这种带反斜杠的扁平文件名 import zipfile, os with zipfile.ZipFile(OUT, 'w', zipfile.ZIP_DEFLATED, compresslevel=9) as z: for dirpath, _, filenames in os.walk(SRC): for fn in filenames: full = os.path.join(dirpath, fn) rel = os.path.relpath(full, SRC).replace('\\', '/') z.write(full, rel)

必须校验：'\\' not in name、顶层结构（admin/、usr/、var/、index.php…）、testzip() 通过、试解压文件数一致。

同时准备新 config.inc.php（数据库凭据换成新主机的，其余不动）：

$db = new \Typecho\Db('Pdo_Mysql', 'typecho_'); $db->addServer(array('host'=>'localhost','port'=>3306,'user'=>'<新用户>','password'=>'<新密码>', 'charset'=>'utf8mb4','database'=>'<新库>','engine'=>'InnoDB','sslCa'=>NULL,'sslVerify'=>false), \Typecho\Db::READ | \Typecho\Db::WRITE);S3 部署到新主机# 普通平台：FTP 上传 zip + 面板解压 curl -T site.zip --connect-timeout 20 -u "user:pass" "ftp://newhost/wwwroot/site.zip" # 荧控制台：必须走面板 WebFTP（见 S8 面板操作速查） # 备选：Python ftplib 直接建目录 + 传 618 个文件（ftp.mkd 建目录）

⭐ 荧控制台部署的关键两条：

整包解压后会「跳过已存在的文件」 → config.inc.php 等旧文件不会被覆盖 → 必须再单独上传一次 config.inc.php（漏了就会 Error establishing a database connection）传完等 20~30 秒让平台发布，再用「直连源站 IP + Host 头」验证

SQL 清理与导入：

curl -k -b ck.txt -F "token=$TOKEN" \ -F "import_file=@clean.sql;filename=clean.sql;type=text/plain" \ -F "is_js_confirmed=0" -F "allow_interrupt=1" -F "import_type=database" \ -F "format=sql" -F "sql_compatibility=NONE" -F "skip_queries=0" \ "https://<dbhost>/mysql/index.php?route=/import&db=<新库>&lang=en&server=1" # 登录 phpMyAdmin（curl）：先 GET 取 token/set_session → POST route=/ 带 pma_username/pma_password # 验证：SELECT 统计 contents / options / 表数量，并核对关键文章标题

SQL 清理规则（Python，按字节处理更安全）：

截掉其他数据库段落（找第二个 -- 数据库： 或 CREATE DATABASE 处截断）删除 CREATE DATABASE ...;、USE ...;⚠️ 读文件用 open(..., encoding='utf-8', errors='ignore') 会静默丢字节，破坏转义 → 涉及 SQL 处理一律字节级操作（'rb'）老主机的 dump 可能夹杂「CR 被转义、LF 是真实换行」的混合格式，某些 MySQL 会报 #1064 → 用新鲜导出替换导出若勾了「整个服务器」，文件里会混进别人的库（如 test）→ 按段落截掉S4 域名 + PHP 版本面板「域名绑定」：域名 → 目录 wwwroot → 记下解析要求（A 记录 IP / CNAME 目标）面板「PHP 版本」：必须 7.4（Typecho 1.3 在 7.2 下全站白屏 500）荧系面板 API 参考：?c=domain&a=add（body domain=xxx&subdir=wwwroot）、?c=index&a=phpset（GET 看版本）/ ?c=index&a=phpset&op=change（POST v=php74）域名解析由用户在 Cloudflare 手动改（AI 无权限）；建议先灰云（DNS only）验证S5 验证# 1) 走域名 curl -sI https://域名/ -o /dev/null -w "%{http_code}\n" # 2) 绕过 CDN 直连源站（CDN 线路抖动时很有用） curl -s -H "Host: 域名" "http://<源站IP>/" -o /dev/null -w "%{http_code}\n" # 3) 逐项：首页标题、文章页、/admin/（302=正常）、静态资源 # 4) 数据库：表数、文章数、关键文章标题 # 5) 速度：手机流量 + 电脑实测，卡就如实告诉用户（曾有主机"能开但更慢"被弃用）S6 收尾归档备份到 D:\Susuisuinian\博客备份\（分类：网站文件 / 主题 / 插件 / 数据库 / 旧站全量 / 文章文档 / 脚本 / 邮件模板 / 迁移手册）更新日记与 MEMORY.md提醒用户：旧主机先别退，验证一周后再处理S7 主机故障恢复（应急）

触发：网站 503 / 白屏 / 报 Error establishing a database connection诊断顺序：

直连源站 IP + Host 头看真实响应（绕 CDN 抖动）

登录主机面板看「空间占用」：

0 MB → 平台「已发布内容」被删（FTP 里可能还有旧文件，但网站不认）→ 走恢复上传正常 → 查 config.inc.php 数据库凭据传 dbtest.php（token 保护，用完删）直接测 DB 连接、PHP 版本、pdo_mysql；能顺便打印 config 里的 user/host 帮你定位恢复动作：面板 WebFTP 上传整包 → 解压 → 单独再传一次 config.inc.php → 等 30 秒验证 → 删诊断脚本⭐ 教训：站点「数据库连不上」经常不是数据库的错，而是解压跳过文件导致 config 没被覆盖。四、荧控制台面板操作速查（星辰云/轻云，CDP 自动化，已验证）

登录：

curl -c ck.txt "https://<面板域名>/vhost/?c=session&a=loginForm" curl -b ck.txt -c ck.txt -L --data "username=<账号>&passwd=<密码>" \ "https://<面板域名>/vhost/index.php?c=session&a=login"

（轻云是 /qingyun/index.php?c=session&a=login，同一套程序）

面板 WebFTP 上传文件（可靠流程）：

点 #fileBtn 打开发文件管理器，等约 16 秒让 iframe 加载⚠️ 文件管理器默认停在根目录 /，不是 /wwwroot

进目录：双击目录项（触发 openDir('wwwroot')）

❌ 不要直接调 loadDir('/wwwroot') —— 会被环境改写成奇怪本地路径（如 D:/Program Files/.../PortableGit/wwwroot）导致上传落到错处校验 #location 字段（注意末尾斜杠，比对时要 normalize）确认已进入 /wwwroot/打开上传对话框 dialog('webftpUpload') → 取 #webftpUploadInput 的 objectId → DOM.requestNode → DOM.setFileInputFiles → 点「开始上传」

面板删除文件：

iframe.contentWindow.selFile('<文件名>', true); iframe.contentWindow.doCommonOperation('rm'); // 跳过 confirm 弹窗

面板数据库备份：?c=shell&a=mysqldumpout（POST body passwd=），轮询 ?c=shell&a=query&session=<返回的 session> 看结果；可能因缺 PROCESS 权限失败。

五、关键坑与对策（血泪表）坑现象对策荧控制台：FTP 文件不发布FTP 传上去的文件磁盘上有、FTP 能列出，但网站 404（连老文件也 404）文件走面板 WebFTP 上传面板「空间占用」≠ 磁盘文件面板显示 0 MB + 网站 503，但 FTP 里文件还在平台只认「面板上传的发布内容」；重新走面板上传zip 自动解压跳过已存在文件传整包后 config.inc.php 没被覆盖 → 报 Error establishing a database connection整包传完再单独上传一次 config.inc.php面板文件管理器默认不在站点根上传的文件落到根目录而不是 /wwwroot双击目录项 openDir('wwwroot') 并校验 #location；别用 loadDir('/wwwroot')Windows 压缩包解压后出现 var\Typecho\Db.php 这类文件名用 Python zipfile 重新打包（正斜杠）Cloudflare 不代理 FTP用域名连 21 端口必超时用源站 IP 连 FTPTypecho 在 PHP 7.2 白屏全站 500、无错误信息面板切 PHP 7.4主题目录名改目录名 → 主题配置丢失（options 表 theme:目录名）目录名保持一致；要改就同步改数据库phpMyAdmin 导出curl/自动化拿到的是 JS 空壳让用户手动导出；或用面板备份功能导出带了 CREATE DATABASE导入新主机报 #1044 Access denied清理 SQL导出勾了「整个服务器」文件里混进别的库（如 test）只导出自己的库；已混入的按段落截掉CDN → 源站线路抖动请求 20~45s 超时、时好时坏用直连源站 IP + Host 头做验证；告知用户是线路问题站点"能开但更慢"换到新主机后用户实测更慢迁移前后都测速；用户以体感为准，别只看状态码长任务卡死bash 循环探测 FTP 目录 1.5h 无进展批量 FTP 用 Python ftplib 多线程；单条命令设 --max-time；发现卡住立刻换方案并告知用户curl -o 的转义\\$f 被 bash 转义成字面量，路径拼接失败用 'C:\path\'"$f" 或改用 Python后台登录自动化登录成功会 302 到 /，只看 URL 会误判登录后跳 dashboard 验证；textarea 写入长度用 JSON.stringify 校验（换行符规范化允许 ±10 误差）清理误删按 mtime 批量删共享 temp → 删掉用户文件只删自己创建的；先列清单再删；用回收站面板里删文件选文件时连带把 wwwroot 文件夹本身选上删了明确只选 wwwroot 里面的内容；删前看清单六、类型化检查表（可复用）

迁移前

[ ] 旧站：FTP 可用？面板可用？数据库可导出？[ ] 新站：FTP 可用？站点根目录名？PHP 版本可切 7.4？要备案吗？平台是不是荧控制台？[ ] 用户提供的凭据齐全？DNS 在谁手上？

迁移中

[ ] 文件包用 Python zipfile 打包并校验（无反斜杠、试解压通过）[ ] SQL 已清理（无 CREATE DATABASE / USE / 别人的库）[ ] config.inc.php 已指向新库，且单独上传覆盖过（荧控制台）[ ] 数据库导入后核对行数与关键文章[ ] 域名绑定 + PHP 7.4[ ] 荧控制台：文件是走面板传的，不是 FTP

迁移后

[ ] 首页 / 文章 / 后台 / 静态资源 全部 200[ ] 主题配置、插件、评论通知 正常[ ] 速度实测（手机流量 + 电脑）[ ] 备份归档到统一路径[ ] 提醒用户旧主机暂缓退订七、站点现状（2026-10-07 更新）项目值博客https://blog.syicxh.cc.cd（Typecho 1.3 + SuNexmoe 主题，PHP 7.4）现用主机星辰云（香港） — 面板 https://aspanel.starzv.com/vhost/（账号 svh_wlrijbq）；FTP 23.238.119.210:21（账号 s1260391）；集群 IP 149.104.21.22 / 149.104.21.25；站点根 /wwwroot；数据库面板 https://amysql.starzv.com/mysql/（库 svh_wlrijbq）备用主机轻云互联（香港）— 面板 https://mf.iqy.im/qingyun/index.php（ocjffuda）；FTP mf.iqy.im:21；站点根 /wwwroot；数据库 mf.iqy.im:4413/mysql/（库 ocjffuda）；IP 104.233.187.187。文件与数据库都已部署并验证正常，只是用户觉得访问更慢而弃用域名解析Cloudflare，blog 记录指向星辰云（未动过）插件5 个（CommentNotifier、FuckAdComment、Links、ThemeSwitcher、TypechoHighLight）已废弃三丰云（备案卡死）、AWS 悉尼（无 FTP）、最早美国主机（数据已迁出）恢复包（可直接重传）D:\Susuisuinian\博客备份\01-网站文件-当前\星辰云恢复包-含星辰云数据库配置.zip备份归档D:\Susuisuinian\博客备份\（01~09 分类）工作目录D:\ProgramData\workbuddy-data\workfiles-轻云迁移\

上一篇写了博客搬家的过程（三台主机、两次翻车、最终落在香港集群），里面提到一个细节：新主机 FTP 连不上，最后是 AI 助手打开一个真实的浏览器窗口，自己填账号密码、自己点按钮、自己上传文件。不少朋友好奇这是怎么做到的——是装了什么神秘的技能包吗？这篇就把它扒开讲清楚。

先回答最关心的问题：不是。没有什么预装的「网页操作技能包」，用的就是浏览器自带的调试协议，配上现场手写的临时脚本。用完就删，下次的脚本是根据当时的页面重新写的。听上去很土，但恰恰是这个思路最通用。

先说 FTP 那部分：命令行直连

在讲浏览器之前，先补一段更早的操作。旧主机时代（FTP 还能用的时候），AI 是怎么直接操作服务器文件的？答案朴素得惊人——curl：

列目录：curl -u 账号:密码 "ftp://主机/路径/" --list-only上传单个文件：curl -T 本地文件 "ftp://主机/路径/文件名"下载：curl -u ... "ftp://主机/文件" -o 本地文件

中间还踩过一个很典型的坑：域名套了 Cloudflare 之后 FTP 突然全超时。原因是 Cloudflare 只代理 HTTP/HTTPS 流量，不代理 FTP。解法是绕过域名，直接用源站 IP 连。

排查端口用的是一个更底层的小技巧：Bash 里 echo > /dev/tcp/IP地址/端口，连得上就是端口开放，连不上就是关闭。没有 nmap 也能快速扫一圈。

重头戏：浏览器是怎么「自己动」的1. 核心武器：Chrome DevTools Protocol（CDP）

你按 F12 打开的开发者工具，背后其实是浏览器开放的一套调试协议——Chrome DevTools Protocol。它能读取页面结构、执行任意 JavaScript、模拟点击、甚至操控文件上传框。Edge、Chrome 都基于 Chromium，所以都支持。

关键一步是带参数启动浏览器：

msedge.exe --remote-debugging-port=9861 --user-data-dir=独立目录 网址

--remote-debugging-port 打开后，浏览器就在本地开了一个调试端口，脚本可以通过 WebSocket 连上去发指令。用的是有头模式（就是正常的浏览器窗口），所以我能全程看见浏览器自己在动，哪一步点错了随时叫停。

2. 模拟人工的完整流程

脚本要干的事，就是把我平时手动上传文件的动作拆解成一条条协议指令：

人的动作脚本对应的指令打开控制台网址启动参数里直接带 URL在登录框输入账号密码Runtime.evaluate 执行 JS 给输入框赋值，然后触发表单提交点「文件管理」菜单Runtime.evaluate 执行 element.click()选择要上传的文件见下文，这是最难的一步点「开始上传」按钮遍历所有 button，找到文字匹配的那个点它3. 文件上传：最难的一环

你可能会说，填表单点按钮不就是执行 JS 吗？对，但文件选择框是个例外。网页里那个 <input type="file">，点击后会弹出操作系统级的文件选择窗口——那不是网页的一部分，JS 根本控制不了。

CDP 为此专门准备了一个接口：DOM.setFileInputFiles。它不走页面交互，而是直接告诉浏览器「把这个本地文件路径塞进这个 input 元素」，效果等同于你手动选好了文件。拿到这个接口的前提是先拿到目标元素的 nodeId，中间又踩了两个坑：

页面的 DOM 树很深，一次性完整遍历会莫名其妙崩掉。解法是先在页面里执行 document.getElementById(...) 拿到元素对象，再用 DOM.requestNode 把它转成 nodeId，完全绕开树遍历上传对话框和文件输入框在主页面里，而文件列表在页面的一个 iframe 里（还是跨域的），结构必须先摸清楚才能下对指令

填好文件、点「开始上传」，然后读页面上的进度条元素确认到了 100%——一次真实的人工操作，就这样被完整复刻了。

4. 意外之喜：上传 zip 自动解压

第一次上传完，刷新文件列表，发现 zip 已经被面板自动解压开了——原本还要找解压按钮的步骤都省了。这类「平台行为」脚本事先不知道，所以每一步之后都要读页面实际状态来决定下一步，而不是死板地按剧本走。这也是模拟人工和按键精灵式录制的本质区别。

几个常见疑问

Q：为什么不用 FTP？这家平台的 FTP 地址根本解析不出来，网页文件管理器是唯一入口。有 FTP 的时候谁愿意写脚本。

Q：为什么不用无头浏览器（headless）？无头模式更快，但出问题时你看不见页面长什么样。这次是有头模式，浏览器窗口就摆在桌面上，相当于全程有人肉监控。调试阶段，看得见比快更重要。

Q：这算 AI 自动化吗？和按键精灵有什么区别？本质区别在适应性。按键精灵是「录制-回放」，页面一改版就废。这次的做法是：先抓取页面分析结构（找登录表单的字段名、找按钮的 ID、分析接口地址），再根据当场的实际页面生成对应的操作指令，每步之后校验结果。页面变了，就重新分析重新写。脚本是一次性的，分析方法才是可复用的。

Q：安全吗？脚本只在我自己的电脑上运行，连接的是本机调试端口（127.0.0.1），不经过任何第三方服务器。账号密码只出现在本地脚本和页面表单里。当然，让 AI 操作账号期间，你最好全程盯着屏幕——就像这次一样。

写在最后

这次搬家让我对「AI 帮忙」有了更具体的体感：它不是一句「帮我传个文件」就变出魔法，而是把一件人工操作拆解成分析页面 → 定位元素 → 转成协议指令 → 校验结果 → 出错重试的循环。工具都是现成的：curl、端口探测、CDP、十行 JS。稀缺的不是工具，是「知道下一步该点什么」的判断力。

博客搬家系列到此完结。有想交流的欢迎评论区见。

关注我的朋友可能知道，这个博客前几天还架在一台美国主机上。访问速度一直不太行，前几天更是直接挂了——用 Cloudflare 的时候满屏 522 错误。趁着这次彻底搬家，把过程记录下来，给同样想搬家的朋友参考。

这次搬家一共碰了三台主机，每一台都踩了坑，最后一台终于稳定落地。全程是让 AI 助手帮我干的活，我只负责最后点一下「确认」。具体 AI 是怎么操作浏览器上传文件的，下一篇单独写，这篇先讲搬家的整体过程。

搬家的原因

旧主机在美国，最大的问题就俩字：慢。国内访客打开页面要绕地球一圈。更要命的是最近域名套上 Cloudflare 之后，源站隔三差五失联，报 522（连接超时）——虽然 FTP 登进去看文件都好好的，就是网页打不开。这种「半死不活」的状态最难受，干脆搬。

第一站：AWS 悉尼主机 —— 卡在 FTP 上

朋友给了一台 AWS 悉尼的虚拟主机，给了 FTP 账号密码。结果第一步就卡死了：21 端口死活连不上。

让 AI 扫了一下端口，真相大白：

端口状态21（FTP）❌ 关闭22（SSH/SFTP）✅ 开放80 / 443✅ 开放

这台主机根本没开 FTP，用的是 SFTP。但问题接踵而至：本机的 curl 不带 SFTP 支持；OpenSSH 的 sftp 命令倒是有，可服务器只接受密钥登录，不收密码。几轮尝试下来全堵死了，加上悉尼机房对国内访客也不算快，果断放弃。

小知识：FTP 和 SFTP 是两个完全不同的协议。FTP 走 21 端口，SFTP 是走 SSH（22 端口）的文件传输，两者客户端不通用。

第二站：三丰云 —— 卡在备案上

第二站是三丰云的免费虚拟主机。文件传了，数据库也导了，一切就绪——然后发现 必须备案。我的域名在 Cloudflare 上解析，走的是海外线路，没有 ICP 备案号，绑定域名这一步直接被卡死。文件在服务器上躺着一个都用不了，只能作罢。

这里提醒一句：国内主机的「免费」往往绑着备案要求，域名没备案的朋友直接跳过这类，选香港或者海外线路。

第三站：星辰云香港集群 —— 最终落地

第三站是星辰云的免费虚拟主机，香港集群，免备案。这台主机的体验就很魔幻了：

1. 又连不上 FTP

给了 FTP 账号密码，但 FTP 主机地址死活解析不出来。查了半天发现这家平台的思路不太一样：它主推网页版文件管理器，FTP 反而是个摆设。

2. 网页文件管理器 + 自动解压

AI 直接分析了控制台的登录接口（好消息：登录没有验证码，可以直接模拟），然后用「有头浏览器」模拟人工操作——打开浏览器窗口，自己填账号密码、点「文件管理」、把本地的 site_backup.zip 塞进上传框、点「开始上传」。我全程就在旁边看着浏览器自己动。

最惊喜的是：面板检测到你上传的是 zip，自动帮你解压到当前目录。619 个文件（Typecho 全套 + 主题 + 插件）一次上传全部就位。

3. 数据库导入

平台自带 phpMyAdmin（5.2.1），标准登录后直接上传 SQL 文件导入。旧库 10 张表、33 条查询，一次通过。

4. 绑定域名

面板里填域名 + 绑定目录，平台给出解析要求：CNAME 指向 hk1-dns.starzv.com。去 Cloudflare 把 blog 的记录从旧的 A 记录改成这条 CNAME，等生效。

5. 开站！……500 白屏？

DNS 生效后满心欢喜地打开网站——满屏 500 空白。排查过程很有意思：

直连集群测静态文件（favicon 之类的图片）：200 正常，说明文件都在、服务器没坏测任何 PHP 页面：全部 500 空白，连 Typecho 的安装检测页都打不开进入主机面板一看：PHP 版本默认是 7.2

Typecho 1.3 在 PHP 7.2 下会直接致命错误白屏。面板里把 PHP 切到 7.4，重启进程——刷新，网站瞬间活了。

三台主机对比总结主机卡在哪结局AWS 悉尼没开 FTP、SFTP 只收密钥放弃三丰云强制要求备案放弃星辰云香港PHP 版本默认 7.2（可自己切）✅ 落地几条经验搬家前先确认三件事：FTP/SFTP 能不能连、要不要备案、PHP 版本能不能自己选。三件事任何一件不满足都白忙zip 打包上传 + 自动解压是最高效的网站迁移方式，比一个一个文件传快太多数据库导入用平台自带的 phpMyAdmin 比命令行省心，导完记得核对表数量换主机后网站 500 白屏，先查 PHP 版本——这个坑比想象中常见域名在 Cloudflare 的话，切换解析就是改一条 CNAME 的事，几分钟生效

现在博客已经在香港集群上稳定运行，国内访问速度比美国主机好了不少。下一篇讲讲这次搬家最硬核的部分：AI 是怎么「模仿人工」操作浏览器完成文件上传的，以及它到底是不是集成了什么神秘技能。

首先要感谢原博主折影轻梦编的Nexmoe。

这篇写清楚我到底改了哪些地方、为什么改，以及踩过的坑。

关于这个二改版项目说明主题名SuNexmoe版本2.0原作者折影轻梦（Nexmoe 1.1）二改作者苏的碎碎念相关网页https://blog.syicxh.cc.cd/index.php/archives/11/交流QQ：2404999487，欢迎使用、交流开源协议Apache License 2.0（原主题与本二改版均为 Apache 2.0）二改内容清单（共 9 项）一、阅读体验1. 首页摘要截断

原版首页用的是 $this->content('')，那个空参数不是字数限制，是「阅读全文」链接的文字。Typecho 的 content() 只认正文里的 <!--more--> 标记 —— 你没写标记，它就输出全文，文章一长列表页就变成一堵墙。

现在改成按字数截断，后台可配：

「首页文章摘要字数」默认 150，填 0 = 不限制（输出全文）「摘要后面的链接文字」默认「阅读全文」，留空则不显示链接文章里如果写了 <!--more-->，优先用标记前的内容2. 头图高度压缩

原版头图高度写死而且很高，遇到竖版大图还会被撑得更高。现在：

首页与文章页头图统一 190px，手机端 150px图片改用绝对定位 + object-fit: cover，无论原图多大（1080×1920 也一样）都裁在框内，不会再把版面顶开

顺便说个坑：这个修复卡了好几天，因为我一开始把 CSS 选择器写成了 #nexmoe-content .nexmoe-single ...，而 nexmoe-single 这个类其实在 <body> 上、是 #nexmoe-content 的父级不是子级 —— 祖先不等于后代，选择器一次都没匹配上，规则从来没生效过。改对之后一测，容器从 500px 立刻变成 190px。教训是：改样式前先确认那个类到底在 DOM 的哪一层，别凭感觉写选择器。

3. 文章目录树（全新功能，替代原版自带的目录）

原版自带一个右侧目录，但那条 .nexmoe-fixed 是 position: fixed; top: 0; height: 100vh; z-index: 1000，而且整份 post.php 里一条媒体查询都没有 —— 也就是说它在手机上也照样显示，还会从屏幕最顶端盖住正文。这是原版的设计缺陷。

我重写了一套：

按正文里的 h1 ~ h4 自动生成层级目录样式：圆点 + 同级竖连线 + 层级缩进，圆点与连线都跟随主题色（改主题色目录会跟着变）点击平滑跳转到对应小节；鼠标悬停变色、圆点放大滚动时自动高亮当前所在小节手机 / 平板不显示，桌面窄屏会自动把正文略微收窄，为目录腾出空间（笔记本 150% 缩放也能看到）二、封面图4. 封面图地址池（原版没有的新功能）

这个功能是我自己加的，起因是发现一个很典型的现象：每篇文章的封面图都一样。

查下来原因很直接。原版逻辑是「每篇文章手动设封面，否则全用同一个默认图」：

<?php if ($this->fields->Cover) { ?><img src="...Cover"><?php } else { ?><img src="<?php echo $this->options->background ?>"><?php } ?>

没给文章单独设封面时，所有文章输出的 URL 完全相同（比如 https://api.xxx.com/api）→ 浏览器只请求一次，剩下几处直接复用同一张图。不是 API 的问题（实测连请求 4 次返回 4 张不同的图）。

现在后台新增「封面图地址池」，一行一个地址，想填几个填几个：

https://picsum.photos/seed/{cid}/1200/600https://你的随机图API地址按文章 ID 轮流取用 → 每篇文章封面都不同，而且同一篇永远是同一张（刷新不会乱变）用「轮流」而不是「真随机」是真随机会导致同一篇每次刷新都换图，看起来很乱地址里支持 {cid} 占位符，会被替换成文章 ID留空则只用「博客默认封面图」每篇文章仍可在「编辑文章 → 自定义缩略图」里单独指定，优先级最高5. 图片加载失败自动隐藏

随机图 API 偶尔返回坏图或超时，现在封面加载失败会自动隐藏，不会出现破图图标。

这里也踩了个坑：一开始写的是无条件 onerror 隐藏，结果首页封面全变成空白灰块。原因是懒加载插件会把 src 挪到 data-src 并清空 src，而 src="" 会被浏览器当成「当前页面地址」去请求 → 失败 → 触发了我的兜底。改成 if(this.getAttribute('src')) 只在真的请求过图片时才处理就好了。

三、评论与通知6. 评论头像改造

原版的评论头像依赖第三方服务 avatar.dawnlab.me，这个服务已经停止服务了，所以所有人的评论头像都是破图。现在改成三级回落：

情况显示QQ 邮箱QQ 官方头像其他邮箱 + 有 GravatarGravatar 头像（走国内可访问的镜像）其他邮箱 + 没有 Gravatar后台可配的随机头像接口Gravatar 服务本身挂了自动换成随机头像

有个实测数据值得记：gravatar.com 官方域名在国内是打不通的（HTTP 000），必须走国内镜像。另外 QQ 头像接口只接受固定尺寸（40 / 100 / 140 / 160 / 640），传 96 会返回 400 → 裂图，这个也一并处理了。

四、外观与配色7. 配色可配置

原版把主题色 #ff4e6a 写死在几十处。现在全部改为 CSS 变量（定义在 :root，所以固定定位的目录也能继承），后台可配三项：

① 主色（链接、标签、按钮等）② 侧栏当前页颜色③ 侧栏悬停颜色

留空即沿用原版配色。

8. 暗色模式补齐

这个主题的暗色模式是整张替换样式表（换 CSS 文件、不加 body 类），所以新增的目录树样式必须写两份。我踩过这个坑：只在亮色版加了样式，暗色下目录是白的看不见。

五、性能与维护9. 静态资源防缓存

CSS / JS 自动附带 ?v=文件修改时间，改完样式刷新即生效，不用再让访客手动强清浏览器缓存，后台还有个「手动刷新缓存」输入框兜底。

这个功能是被逼出来的：原主题引用 CSS 时完全没有版本参数，浏览器缓存后即使服务器上的文件改了也继续用旧的那份，导致「明明改了样式却没效果」，头图高度那个问题反复折腾了好几轮就是这个原因。Typecho 核心自己也不给静态资源加版本号，所以这在 Typecho 里是常态，不是主题的 bug。

安装解压后把 SuNexmoe 文件夹放进 Typecho 的 /usr/themes/ 目录后台 → 外观 → 启用务必去「外观 → 设置」点一次「保存」 —— 二改新增的配置项要保存一次才会生效建议在「设置 → 阅读」里把「每页文章数目」设为 20致谢与协议原主题 Nexmoe 由 折影轻梦 开发：https://github.com/nexmoe/typecho-theme-nexmoe原主题许可为 Apache License 2.0（见主题内 LICENSE），版权归原作者所有，此处原样保留本二改版 SuNexmoe 由 苏的碎碎念 修改，同样以 Apache License 2.0 授权发布（见主题内 LICENSE-APACHE）

欢迎使用、交流。QQ：2404999487

直接上网址

https://random-api.czl.net/ https://jia.baoyu2023.top/archives/random-image-api-collection https://blog.mikus.ink/posts/random-api/ https://api.opics.org/

环境：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'; } // 读不到时的兜底

直接上代码，

<html> <head> <!-- 灯笼样式开始 -->

@media only screen and (max-width: 760px) { .deng-box, .deng-box1 { display:none; } } @media only screen and (min-width: 768px) and (max-width: 1024px) { .right { float: left!important; } } .tc_dl1{ position: relative; left: -21px; top: -8px; } .tc_dl1 img{width: 95px;height: 488px;justify-content: center;} .tc_dl2{position: relative;right: 21px;top:-8px} .tc_dl2 img{width: 95px;height: 488px;} .deng-box { position: fixed; top: 20px; left: 10px; z-index: 3; } .deng-box1 { position: fixed; top: 20px; right: 10px; z-index: 3; } .deng-box1 .deng { position: relative; width: 120px; height: 90px; margin: 50px; background: #d8000f; background: rgba(216, 0, 15, 0.8); border-radius: 50% 50%; -webkit-transform-origin: 50% -100px; -webkit-animation: swing 5s infinite ease-in-out; box-shadow: -5px 5px 30px 4px rgba(252, 144, 61, 1); } .deng { position: relative; width: 120px; height: 90px; margin: 50px; background: #d8000f; background: rgba(216, 0, 15, 0.8); border-radius: 50% 50%; -webkit-transform-origin: 50% -100px; -webkit-animation: swing 3s infinite ease-in-out; box-shadow: -5px 5px 50px 4px rgba(250, 108, 0, 1); } .deng-a { width: 100px; height: 90px; background: #d8000f; background: rgba(216, 0, 15, 0.1); margin: 12px 8px 8px 10px; border-radius: 50% 50%; border: 2px solid #dc8f03; } .deng-b { width: 45px; height: 154px; background: #d8000f; background: rgba(216, 0, 15, 0.1); margin: -4px 8px 8px 26px; border-radius: 50% 50%; border: 2px solid #dc8f03; } .xian { position: absolute; top: -20px; left: 60px; width: 2px; height: 20px; background: #dc8f03; } .shui-a { position: relative; width: 5px; height: 20px; margin: -5px 0 0 59px; -webkit-animation: swing 4s infinite ease-in-out; -webkit-transform-origin: 50% -45px; background: #ffa500; border-radius: 0 0 5px 5px; } .shui-b { position: absolute; top: 14px; left: -2px; width: 10px; height: 10px; background: #dc8f03; border-radius: 50%; } .shui-c { position: absolute; top: 18px; left: -2px; width: 10px; height: 35px; background: #ffa500; border-radius: 0 0 0 5px; } .deng:before { position: absolute; top: -7px; left: 29px; height: 12px; width: 60px; content: " "; display: block; z-index: 999; border-radius: 5px 5px 0 0; border: solid 1px #dc8f03; background: #ffa500; background: linear-gradient(to right, #dc8f03, #ffa500, #dc8f03, #ffa500, #dc8f03); } .deng:after { position: absolute; bottom: -7px; left: 10px; height: 12px; width: 60px; content: " "; display: block; margin-left: 20px; border-radius: 0 0 5px 5px; border: solid 1px #dc8f03; background: #ffa500; background: linear-gradient(to right, #dc8f03, #ffa500, #dc8f03, #ffa500, #dc8f03); } .deng-t { font-family: 华文行楷; font-size: 26px; color: #dc8f03; font-weight: bold; line-height: 44px; text-align: center; } .night .deng-t, .night .deng-box, .night .deng-box1 { background: transparent !important; } @-moz-keyframes swing { 0% { -moz-transform: rotate(-10deg) } 50% { -moz-transform: rotate(10deg) } 100% { -moz-transform: rotate(-10deg) } } @-webkit-keyframes swing { 0% { box-shadow: -5px 5px 50px 4px gold; -webkit-transform: rotate(-10deg) } 50% { box-shadow: -5px 5px 50px 4px rgba(250, 108, 0, 1); -webkit-transform: rotate(10deg) } 100% { box-shadow: -5px 5px 50px 4px gold; -webkit-transform: rotate(-10deg) } }

</head> <body> <div class="deng-box"> <div class="deng"> <div class="xian"> </div> <div class="deng-a"> <div class="deng-b"> <div class="deng-t">新春 <div class="tc_dl1"> <img src="https://cdn.jsdelivr.net/gh/LR787/image/usr/uploads/2021/02/809851633.jpg"/> </div> </div></div> </div> <div class="shuishui-a"><div class="shui-c"></div><div class="shui-b"> </div> </div> </div> </div> <div class="deng-box1"> <div class="deng"> <div class="xian"></div> <div class="deng-a"> <div class="deng-b"><div class="deng-t">快乐 <div class="tc_dl2 "> <img src="https://cdn.jsdelivr.net/gh/LR787/image/usr/uploads/2021/02/4264823773.jpg"/> </div> </div> </div> </div> <div class="shuishui-a"> <div class="shui-c"> </div><div class="shui-b"> </div> </div> </div> </div> <!-- 元宵节灯笼样式结束 --> </body>