X 图片批量保存器详细部署笔记

本文用于把 x_media_downloader 部署到另一台 Windows 电脑，并确保 Chrome 登录、系统代理、图片保存和断点续传都能正常工作。

当前版本：

  • 本地下载服务：v1.3.1
  • Chrome 扩展：v1.3.0
  • 适用系统：Windows 10 / Windows 11
  • 推荐浏览器：Google Chrome
  • Node.js 最低建议版本：20.18.1
  • 推荐 Node.js 版本：当前 LTS 或 Node.js 24

一、部署后会得到什么

程序由两部分组成：

  1. Chrome 扩展：使用目标电脑上当前 Chrome 的 X 登录状态，扫描账号媒体页。
  2. 本地下载服务：接收图片地址，使用系统代理下载图片并直接写入指定文件夹。

运行流程为：

当前 Chrome 登录 X
        ↓
Chrome 扩展扫描账号媒体页
        ↓
本地服务读取 Windows/Chrome 代理
        ↓
从 pbs.twimg.com 下载原图
        ↓
保存到用户指定的本地文件夹

程序不会安装系统服务，不会修改 X 密码，不会把 Chrome 登录信息复制到程序目录，也不会监听局域网地址。本地网页只绑定在 127.0.0.1。

二、目标电脑需要准备什么

必需项目

  • Windows 10 或 Windows 11。
  • Google Chrome。
  • Node.js 20.18.1 或更高版本。
  • 可以登录 X 的网络环境。
  • 如果目标电脑访问 X 需要代理，需要一个带 HTTP 或 Mixed 端口的本地代理。

推荐配置

  • Node.js 当前 LTS 64 位版本。
  • 至少预留数 GB 图片存储空间。
  • 把程序放在普通可写目录，不要放进 C:\Program Files。
  • 程序目录确定后尽量不要移动，因为 Chrome 加载的是固定路径下的扩展文件夹。

推荐目录示例：

D:\Tools\x_media_downloader

或：

C:\Users\你的用户名\Documents\x_media_downloader

三、应该复制哪些文件

推荐的干净部署包

复制以下内容到目标电脑：

x_media_downloader\
├─ extension\
├─ public\
├─ src\
├─ test\
├─ package.json
├─ package-lock.json
├─ README.md
├─ 部署笔记.md
├─ 启动下载器.bat
└─ 安装当前 Chrome 扩展.bat

其中 test 文件夹不是运行必需，但建议保留，方便在目标电脑上检查部署是否完整。

不建议直接复制的内容

以下内容属于当前电脑的运行数据，做全新部署时可以不复制：

data\
downloads\
node_modules\

原因：

  • data 可能包含旧电脑的保存路径和运行日志。
  • downloads 可能是旧电脑生成的下载内容。
  • node_modules 可以在目标电脑通过 npm ci 重新生成。

如果只是希望最快完成部署，也可以把 node_modules 一起复制。当前运行依赖是纯 JavaScript 包，在 Windows 电脑之间通常可以直接使用，但重新安装依赖更规范。

四、如果还要迁移已经下载的图片

如果希望在另一台电脑上继续旧任务，除了程序目录，还要复制原来的图片保存文件夹。

必须尽量完整复制：

  • 所有 .jpg、.png、.webp 等图片。
  • .x-media-cache-用户名.json。
  • download_manifest-用户名.json。

例如：

EmiriaShiroi\
├─ 2037374616063312092_photo1_HEY1abMagAAIQR4.jpg
├─ 其他图片……
├─ .x-media-cache-EmiriaShiroi.json
└─ download_manifest-EmiriaShiroi.json

在新电脑上开始任务时，把“图片保存文件夹”填写为这个迁移后的目录。程序会检查已有文件并跳过，只下载缺少的图片。

如果只复制图片而不复制缓存，已有图片仍不会重复保存，但程序可能需要重新打开更多帖子来解析图片地址，速度会慢一些。

五、安装 Node.js

1. 下载

在目标电脑打开：

https://nodejs.org/

下载 Windows 64 位的 LTS 安装程序。

2. 安装

安装时保持默认选项，并确保安装程序把 Node.js 加入系统 PATH。

3. 验证

打开 PowerShell 或命令提示符，执行：

node -v
npm -v

正常示例：

v24.11.1
11.6.2

如果提示“不是内部或外部命令”，关闭当前终端并重新打开。如果仍无效，重新安装 Node.js，并确认启用了加入 PATH 的选项。

六、安装项目依赖

当前本地服务使用 undici 提供代理下载能力。新电脑第一次运行时，启动下载器.bat 会在缺少依赖时自动执行 npm ci --omit=dev。也可以提前手动安装，便于发现和处理网络问题。

PowerShell 方法

假设程序位于：

D:\Tools\x_media_downloader

执行：

Set-Location 'D:\Tools\x_media_downloader'
npm ci --omit=dev

命令提示符方法

cd /d "D:\Tools\x_media_downloader"
npm ci --omit=dev

成功时通常会看到类似：

added 1 package
found 0 vulnerabilities

npm ci 会按照 package-lock.json 安装确定版本的依赖，适合在其他电脑上进行可重复部署。

如果 npm 安装也需要代理

有些代理软件虽然开启了 Windows 系统代理，但 npm 不一定自动使用。可以只在当前 PowerShell 窗口临时设置代理：

$env:HTTP_PROXY = 'http://127.0.0.1:10808'
$env:HTTPS_PROXY = 'http://127.0.0.1:10808'
npm ci --omit=dev

把 10808 替换为目标电脑代理软件的实际 HTTP 或 Mixed 端口。

关闭这个 PowerShell 窗口后，临时环境变量会自动失效，不会永久修改系统。

完全离线部署

如果目标电脑不能访问 npm 软件源，可以在已正常运行的电脑上把整个 node_modules 文件夹一并复制过去。目标电脑仍然需要安装 Node.js，但不需要再次运行 npm ci。

七、安装 Chrome 扩展

自动打开安装位置

在目标电脑双击：

安装当前 Chrome 扩展.bat

脚本会：

  • 打开 chrome://extensions/。
  • 打开程序目录中的 extension 文件夹。

在 Chrome 中操作

  1. 在扩展管理页右上角开启“开发者模式”。
  2. 点击左上角“加载已解压的扩展程序”。
  3. 选择程序目录中的整个 extension 文件夹。
  4. 确认扩展卡片已经出现并处于启用状态。

正确选择示例：

D:\Tools\x_media_downloader\extension

不要选择 background.js、manifest.json 或程序根目录，必须选择 extension 文件夹本身。

重要注意事项

  • 扩展加载后不要随意移动或重命名程序目录。
  • 如果移动了目录，需要在 Chrome 中删除旧扩展并重新加载新位置。
  • Chrome 关闭后，扩展仍会保留；不需要每次重新安装。
  • 扩展使用目标电脑当前 Chrome 的登录状态，因此不要使用另外新开的临时浏览器配置。

八、准备 X 登录状态

  1. 在目标电脑的正常 Chrome 窗口打开：
https://x.com/home
  1. 正常完成登录。
  2. 确认能打开需要下载的账号主页和媒体页。
  3. 不要把账号密码输入下载器页面；下载器不需要也不会保存密码。

如果 X 显示验证码、登录限制或安全验证，应先在 Chrome 中人工完成，再启动下载任务。

九、配置代理

自动检测规则

本地服务启动时按下面的优先级检测代理：

  1. HTTPS_PROXY、HTTP_PROXY、ALL_PROXY 等环境变量。
  2. Windows 当前用户的系统代理，也就是 Chrome 通常使用的代理。
  3. 如果没有检测到代理，则使用直连。

对域名分流代理的要求

如果代理软件使用域名规则分流，应确保以下域名能够通过可用线路：

x.com
twitter.com
pbs.twimg.com
abs.twimg.com

图片主要来自：

pbs.twimg.com

代理端口类型

程序当前支持 HTTP/HTTPS 代理地址。大多数 Clash、Mihomo、V2Ray 客户端的 HTTP 端口或 Mixed 端口都可以使用。

例如：

http://127.0.0.1:10808

如果代理软件只提供纯 SOCKS 端口，应在代理软件中同时开启 HTTP 或 Mixed 端口。

启动顺序

推荐顺序：

  1. 先启动代理软件。
  2. 开启系统代理。
  3. 再启动下载器。

如果下载器启动后才修改代理地址、端口或系统代理开关，应关闭并重新启动下载器，使它重新检测配置。

十、第一次启动下载器

双击：

启动下载器.bat

正常情况下会出现一个命令窗口，并自动打开：

http://127.0.0.1:17831/

如果 17831 已被占用，程序会继续尝试 17832 至 17850。应使用程序自动打开的页面，不要手动固定使用错误端口。

命令窗口不能关闭

命令窗口就是本地服务本身。下载期间关闭它会停止任务。关闭后已完成图片仍会保留，下次启动可以续传。

页面应显示的关键信息

正常示例：

当前 Chrome 已连接（v1.3.0）
下载代理：http://127.0.0.1:10808

如果不需要代理，也可能显示：

下载代理：直连

十一、首次部署验证步骤

建议不要一上来就测试几千张图片。先用一个图片数量较少的公开账号验证。

  1. 打开下载器页面。
  2. 确认“当前 Chrome 已连接”。
  3. 确认“下载代理”显示正确。
  4. 填写 X 账号地址，例如：
https://x.com/username
  1. 填写一个新的保存目录，例如：
D:\XImages\username
  1. 并行数量选择 1（推荐，最稳）。
  2. 点击“检查当前 Chrome”。
  3. 点击“开始下载”。
  4. 等待状态从“扫描中”进入“下载中”。
  5. 确认新增文件数量开始增加。
  6. 完成后点击“打开保存文件夹”。
  7. 检查图片可以正常打开。

完成后还可以在程序目录运行：

npm test

当前版本应显示 10 项测试全部通过。

十二、正常使用流程

每次使用只需要：

  1. 启动代理软件并确认线路可用。
  2. 保持正常 Chrome 已登录 X。
  3. 双击 启动下载器.bat。
  4. 检查 Chrome 和代理状态。
  5. 输入账号地址与保存目录。
  6. 点击“开始下载”。

Chrome 扩展通常只需首次部署时加载一次。

十三、迁移后的断点续传验证

如果从旧电脑迁移了图片目录：

  1. 在新电脑选择迁移后的图片目录。
  2. 使用同一个 X 用户地址开始任务。
  3. 页面中的“已有”数量应快速增加。
  4. 已有文件不会重复下载。
  5. 缺失文件会计入“新增文件”。

任务可以随时停止。再次开始时会重新扫描，但已经保存的图片会自动跳过。

十四、常见部署错误

1. 双击启动后提示找不到 Node.js

原因：

  • 没有安装 Node.js。
  • Node.js 没有加入 PATH。
  • 安装后没有重新打开终端。

处理：

node -v

如果仍无法识别，重新安装 Node.js。

2. 提示找不到 undici

常见错误包含：

ERR_MODULE_NOT_FOUND
Cannot find package 'undici'

原因：目标电脑没有安装项目依赖。

处理：

Set-Location '程序目录'
npm ci --omit=dev

3. npm 安装超时

原因：npm 没有使用目标电脑的代理。

处理：

$env:HTTP_PROXY = 'http://127.0.0.1:你的端口'
$env:HTTPS_PROXY = 'http://127.0.0.1:你的端口'
npm ci --omit=dev

4. 页面显示“Chrome 扩展未连接”

检查：

  1. chrome://extensions/ 中扩展是否存在。
  2. 扩展是否已启用。
  3. 加载的是否是当前程序目录中的 extension 文件夹。
  4. 刷新下载器页面。
  5. 必要时在扩展卡片上点击“重新加载”。

5. 页面显示扩展版本过旧

在 chrome://extensions/ 中找到该扩展，点击“重新加载”，然后刷新下载器页面。

6. Chrome 能打开 X，但下载图片一直超时

先看页面的“下载代理”。

如果显示“直连”，但目标电脑访问 X 必须走代理：

  1. 开启代理软件的系统代理。
  2. 确认使用的是 HTTP 或 Mixed 端口。
  3. 关闭下载器命令窗口。
  4. 重新双击 启动下载器.bat。

如果代理地址正确但仍超时，检查代理软件是否把 pbs.twimg.com 分流到了可用线路。

7. 扫描数量明显偏少

X 媒体页偶尔不会一次加载完整。可以重新运行一次；已有图片会自动跳过，不会重复下载。

如果连续多次都偏少：

  • 检查 X 页面是否能持续向下滚动。
  • 检查是否出现 X 登录限制。
  • 检查代理线路是否稳定。
  • 稍后再试，避免短时间频繁扫描。

8. 下载停止按钮没有立即结束

新版会先中断当前连接；如果 Chrome 后台没有响应，本地任务会在约 3 秒内强制释放。不要反复连续点击停止按钮。

9. “打开保存文件夹”没有弹出窗口

可能是资源管理器窗口在后台。可以点击“复制保存路径”，然后粘贴到资源管理器地址栏。

10. 页面打不开

检查启动命令窗口是否仍然存在。也可以观察窗口中显示的实际端口。

如果端口冲突，程序会自动换端口。不要同时启动很多个下载器实例。

十五、Windows 安全软件与防火墙

程序只监听本机回环地址：

127.0.0.1

其他局域网设备无法直接访问该页面。

如果 Windows 防火墙询问是否允许 Node.js：

  • 通常允许专用网络即可。
  • 不需要为了本工具开放公共网络访问。
  • 不要手动把端口映射到公网。

某些杀毒软件可能阻止 .bat 文件、Node.js 或 Chrome 开发者扩展。遇到时应检查拦截记录，并仅对确认过的程序目录放行。

十六、升级方法

只更新本地服务或网页

如果更新内容只涉及：

  • src。
  • public。
  • package.json 或 package-lock.json。

操作步骤：

  1. 停止当前任务。
  2. 关闭下载器命令窗口。
  3. 覆盖新版本文件。
  4. 在程序目录执行：
npm ci --omit=dev
  1. 重新启动下载器。
  2. 刷新页面。

更新了 Chrome 扩展

如果 extension 文件夹有变化，还需要：

  1. 打开 chrome://extensions/。
  2. 找到 X 图片批量保存器。
  3. 点击“重新加载”。
  4. 刷新下载器页面。

不需要删除已经下载的图片或缓存。

十七、备份建议

建议备份两类内容：

程序备份

保存以下源文件即可：

extension
public
src
test
package.json
package-lock.json
两个 .bat 文件
README.md
部署笔记.md

node_modules 可以重新生成，不是必须备份。

下载结果备份

整个账号图片目录一起备份，包括：

  • 图片文件。
  • .x-media-cache-用户名.json。
  • download_manifest-用户名.json。

十八、卸载方法

本工具没有注册 Windows 服务，也没有安装到系统目录。

卸载步骤：

  1. 停止下载任务并关闭命令窗口。
  2. 打开 chrome://extensions/。
  3. 删除 X 图片批量保存器扩展。
  4. 删除程序目录。

图片保存目录与程序目录可以分开保留。删除程序不会自动删除已经下载的图片。

十九、目标电脑部署检查清单

部署完成后逐项确认：

  • Chrome 已安装。
  • Node.js 版本不低于 20.18.1。
  • node -v 和 npm -v 能正常执行。
  • 已执行 npm ci --omit=dev，或已经复制 node_modules。
  • Chrome 开发者模式已开启。
  • 已加载程序目录中的 extension 文件夹。
  • 当前 Chrome 已正常登录 X。
  • 代理软件已启动。
  • 页面显示正确的下载代理地址。
  • 页面显示“当前 Chrome 已连接”。
  • “检查当前 Chrome”能够确认登录。
  • 测试账号能够扫描并下载至少一张图片。
  • “停止任务”可以在约 3 秒内结束。
  • “打开保存文件夹”指向正确目录。
  • 保存目录中没有残留 .part 文件。
  • npm test 的 10 项测试全部通过。

二十、推荐的最简部署方案

如果不需要迁移旧图片，最简步骤只有这些：

1. 在目标电脑安装 Chrome 和 Node.js。
2. 复制干净的 x_media_downloader 程序目录。
3. 在程序目录运行 npm ci --omit=dev。
4. 双击“安装当前 Chrome 扩展.bat”，加载 extension 文件夹。
5. 在当前 Chrome 登录 X。
6. 启动代理并开启系统代理。
7. 双击“启动下载器.bat”。
8. 确认 Chrome 和代理状态后开始下载。

如果需要迁移旧任务，再额外复制原图片目录、缓存文件和下载清单即可。

原始文件下载：quark 网盘