面向网站离线镜像的资源映射设计:鸿蒙PC版 WinHTTrack 双模式任务调度、HTML 与 CSS 链接本地化
WinHTTrack 网站离线镜像工具面向网页资料留存、本地静态站点整理与离线阅读场景。在鸿蒙 PC 上实现这类应用,难点不仅是把页面下载到磁盘,更在于如何组织递归任务、区分页面与资源、建立源地址到本地文件的映射,并让多层目录中的链接在离线环境下继续工作。本文围绕 ohos_HTTrack_electron-main 项目,介绍基于 Electron 壳方案构建纯 JavaScript 镜像引擎的实现过程——涵盖 HTTP(S) 抓取、本地目录复制、HTML/CSS 链接本地化、事件驱动的进度展示、镜像清单生成以及鸿蒙壳工程的打包配置。
需要先说明:本文介绍的是当前工程中的 JavaScript 实现,并非把上游 HTTrack 原生程序重新编译后直接运行。文章以现有源码与提供的应用截图为依据,分别说明已经接通的功能、实现边界和后续完善方向,不将截图中的一次本地样例结果等同于任意网站的完整镜像能力。
欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
AtomGit 仓库地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_HTTrack
一、技术架构分析
1.1 整体架构
本项目采用 Electron 业务层 + 鸿蒙 HAP 壳工程的分层架构,业务内部再拆分为三个部分:
- 渲染层:HTML 和 CSS 构建操作界面,renderer.js 采集参数、发送 IPC 请求、更新文件列表、日志与统计。
- 主进程:main.js 创建窗口,处理输出目录选择、任务启动与停止、历史结果读取、报告生成,并把引擎事件转发给渲染层。
- 镜像引擎:httrack-engine.js 负责源地址识别、网络请求或本地复制、链接抽取与回写、产物清单生成。
鸿蒙工程中,electron 是入口模块,依赖本地 web_engine 模块;业务文件放在 web_engine 的资源目录内,随壳工程一起打包。
鸿蒙 HAP 壳工程
├── electron:应用入口、窗口与运行时集成
└── web_engine:适配层与业务资源
└── resources/app
├── index.html + styles/httrack.css:界面
├── renderer.js:参数、交互、结果展示
│ ├── invoke → 请求启动、停止、目录、结果和报告
│ └── on ← 日志、进度、文件、错误和完成通知
└── main.js
└── httrack-engine.js
├── HTTP(S) 队列抓取
├── 本地目录复制
└── 链接回写 + index.html + manifest.json
这种结构把界面交互与镜像规则分开:调整列表样式不需要改动请求逻辑,修正路径映射也不必重新组织页面布局。引擎没有依赖 Electron 对象,可以单独研究和验证;但完整应用仍然依赖 Electron 运行时及鸿蒙适配层,并不是一个直接用浏览器打开就能完成镜像的静态页面。
1.2 技术方案
| 对比项 | 网站离线镜像的需求 | 本项目采用的方案 |
|---|---|---|
| 内容获取 | 下载页面及其引用资源 | Node.js http/https 请求,页面与资源分类入队 |
| 本地数据 | 整理已有静态站点 | 扫描源目录、复制文件,再统一回写链接 |
| 地址关系 | 在线地址转为离线可访问路径 | 源地址键值映射 + path.posix.relative |
| 任务调度 | 控制抓取范围与请求数量 | 批次并发、页面深度、文件数量和大小参数 |
| 结果展示 | 文件、错误与进度可见 | EventEmitter + Electron IPC + DOM 更新 |
| 结果保存 | 后续能重新查看任务记录 | manifest.json、根索引和上次任务目录记录 |
| 界面实现 | 桌面工具式操作体验 | HTML5/CSS/Vanilla JavaScript、自研下拉与分栏拖拽 |
| 部署方式 | 进入鸿蒙桌面应用体系 | electron 入口模块 + web_engine 资源打包为 HAP |
方案取舍: 当前引擎处理的是网络响应和本地文件,不会启动浏览器去执行目标网站的 JavaScript。因此,它更适合静态页面及结构明确的站点,不应被理解为登录态网站、动态接口和前端应用的通用离线复刻器。
1.3 核心功能清单
| 功能模块 | 具体能力 |
|---|---|
| 双模式入口 | 识别 HTTP(S) 地址、本地绝对目录与 file:// 目录地址 |
| 网络抓取 | GET 请求、指定状态码重定向处理、超时配置、压缩响应处理分支 |
| 本地镜像 | 扫描目录树、按数量与大小筛选文件、保留相对目录结构复制 |
| 链接处理 | 抽取指定 HTML 标签的 href/src/poster/action,以及 CSS url() |
| 链接本地化 | 对映射表中存在的目标计算相对路径,回写 HTML/CSS |
| 任务交互 | 启动与停止请求、运行状态、页面和资源事件、错误清单 |
| 结果浏览 | 按本地路径、源地址或类型搜索;查看页面、资源、字节等统计 |
| 产物记录 | 生成根索引和 manifest.json,记录上次任务输出位置 |
| 报告预览 | 界面生成文本报告;主进程另有 JSON 报告字符串分支 |
| 桌面界面 | Catppuccin Mocha 深色主题、可拖拽侧栏/底栏、自定义关于弹窗 |
这里的“停止”不是断点续传,“复查”不是磁盘完整性校验,“导出”按钮目前也不是报告另存为。把这些概念分清楚,才能让后面的实现说明与实际交互保持一致。
二、环境准备
2.1 开发环境要求
| 项目 | 版本/信息 |
|---|---|
| 开发主机 | 可运行 DevEco Studio 的 Windows 开发环境 |
| 核心框架 | Electron:主进程 Node.js 能力 + 页面渲染与 IPC |
| 业务技术栈 | HTML5/CSS/Vanilla JavaScript |
| 镜像引擎 | Node.js 内置网络、文件、路径、压缩与事件模块 |
| 目标设备声明 | 2in1、tablet;本文围绕鸿蒙 PC 桌面场景展开 |
| 原生库目录 | electron/libs/arm64-v8a |
| 工程 SDK 配置 | compatibleSdkVersion 为 5.0.5(17) |
| 运行系统配置 | runtimeOS 为 HarmonyOS |
| 构建工具 | DevEco Studio、与工程匹配的 HarmonyOS SDK、OHPM/Hvigor |
业务 package.json 没有锁定桌面 Electron 版本。本地调试前,应准备可用且与项目 API 相容的 Electron 环境;不能仅凭一个 npm install 就推断运行时已经齐备。设备类型声明也不等同于所有尺寸与机型已经完成适配测试。
2.2 项目结构
ohos_HTTrack_electron-main/
├── lib.unstripped/ # 调试符号相关原生库
├── ohos_hap/
│ ├── AppScope/ # 应用级包名、图标、显示名配置
│ ├── build-profile.json5 # default 产品、签名与模块配置
│ ├── electron/ # 入口模块
│ │ ├── libs/arm64-v8a/ # Electron 与适配层原生库
│ │ └── src/main/ # Ability、页面与模块声明
│ └── web_engine/ # 适配层与业务资源
│ └── src/main/resources/resfile/resources/app/
│ ├── package.json # 应用入口与启动命令
│ ├── main.js # 窗口、引擎管理、IPC
│ ├── httrack-engine.js # 双模式镜像与链接回写
│ ├── renderer.js # 参数、事件和界面交互
│ ├── index.html # 页面布局
│ ├── styles/
│ │ └── httrack.css # 深色主题
│ └── samples/ # 六份本地样例文件
│ ├── index.html
│ ├── about.html
│ ├── style.css
│ ├── logo.svg
│ └── sub/
│ ├── page3.html
│ └── deep.html
├── README.md
└── README.OpenHarmony_CN.md
业务 app 目录共有 12 个文件,其中 6 个是应用代码与样式配置,另外 6 个是样例站文件。样例不是额外下载的测试数据,而是放在应用资源目录中,供界面通过“本地样例站”预设定位。
2.3 依赖说明
镜像业务没有声明第三方 npm 依赖,核心能力由 Node.js 内置模块实现:
| 模块 | 用途 |
|---|---|
| http / https | 获取页面、资源和 robots.txt,处理响应及重定向 |
| fs | 目录扫描、文件复制、内容回写、清单读写 |
| path | 文件落盘路径拼接与相对路径计算 |
| url | 地址解析、相对引用解析 |
| zlib | gzip、deflate,以及运行时支持时的 Brotli 解压 |
| events / util | EventEmitter 事件模型与原型继承 |
| electron | 窗口、系统目录、目录选择和进程间通信 |
业务 package.json 如下:
{
"name": "winhttrack",
"version": "1.0.0",
"description": "WinHTTrack - 网站离线镜像工具(鸿蒙 PC 适配版)",
"main": "main.js",
"scripts": {
"start": "electron ."
}
}
“无第三方 npm 业务依赖”不等于“整个 HAP 零依赖”。 electron 模块仍通过 file:…/web_engine 引用适配模块,并依赖工程中的原生库与平台工具链。当前业务 package.json 也没有 test 脚本,不能把 npm start 当作自动化测试入口。
三、核心适配流程
本章代码取自当前工程的 main.js、httrack-engine.js、renderer.js、index.html 和 httrack.css。标注为“节选”的片段依赖所在函数的上下文,不是独立应用。
3.1 主进程实现(main.js)
主进程同时承担窗口管理和镜像任务入口的职责。与把网络请求放进渲染页面不同,本项目由主进程持有引擎实例,界面只提交配置和接收结果。
窗口创建:
function createWindow() {
try {
var display = screen.getPrimaryDisplay();
var width = display.workAreaSize.width;
var height = display.workAreaSize.height;
// 防 XComponent 崩溃:frame: true + transparent: false + resizable: true
mainWindow = new BrowserWindow({
width: Math.floor(width * 0.9),
height: Math.floor(height * 0.85),
frame: true,
transparent: false,
resizable: true,
webPreferences: {
nodeIntegration: true,
contextIsolation: false
}
});
mainWindow.loadFile('index.html');
} catch (e) {
console.warn('[WinHTTrack] 创建窗口失败:', e.message);
}
}
窗口按照主显示器工作区的 90% 宽度、85% 高度 创建,保留原生边框,关闭透明窗口并允许调整大小。上面的防崩注释反映了工程采用这一组合的意图,实际稳定性仍需要结合目标设备验证,不能仅靠三个参数作保证。
IPC 通道注册:
主进程实际注册了 7 个请求响应通道:
| 通道 | 职责 |
|---|---|
| mirror:getDefaultDir | 获取默认输出目录 |
| mirror:getSamplesDir | 获取随应用打包的 samples 目录 |
| mirror:chooseDir | 调用目录选择对话框 |
| mirror:start | 创建引擎并提交镜像任务 |
| mirror:stop | 请求停止当前任务 |
| mirror:getLastResult | 读取指定目录或上次记录中的 manifest.json |
| mirror:exportReport | 根据清单生成文本或 JSON 报告字符串 |
启动时先检查当前引擎是否运行、源地址是否为空,再创建新引擎。耗时任务通过 setImmediate 调度,最终结果经 mirror:done 推送;mirror:start 的即时返回只表示任务已提交,不表示镜像已经完成。
事件转发:
function wireEngine(eng) {
eng.on('log', function (entry) {
if (mainWindow && !mainWindow.isDestroyed()) mainWindow.webContents.send('mirror:log', entry);
});
eng.on('progress', function (stats) {
if (mainWindow && !mainWindow.isDestroyed()) mainWindow.webContents.send('mirror:progress', stats);
});
eng.on('page', function (item) {
if (mainWindow && !mainWindow.isDestroyed()) mainWindow.webContents.send('mirror:page', item);
});
eng.on('asset', function (item) {
if (mainWindow && !mainWindow.isDestroyed()) mainWindow.webContents.send('mirror:asset', item);
});
eng.on('error-item', function (item) {
if (mainWindow && !mainWindow.isDestroyed()) mainWindow.webContents.send('mirror:error', item);
});
}
wireEngine 转发五类事件,再加上任务回调中单独发送的 mirror:done,共构成 6 类主进程推送。每次发送前检查窗口是否仍存在,减少窗口销毁后继续发送消息的问题。
3.2 页面布局实现(index.html)
页面采用典型的桌面工具布局:顶部操作区、左侧参数区、右侧结果区、底部日志区。对于镜像工具来说,源地址、抓取参数和错误信息需要同时可见,不适合全部隐藏在逐步向导中。
| 区域 | 主要内容 |
|---|---|
| 顶部工具栏 | 源地址、镜像、停止、复查、导出、状态提示 |
| 快速预设栏 | 本地样例及三个外网站点地址预设 |
| 左侧配置区 | 输出目录、深度、并发、间隔、文件上限、站点限制 |
| 左侧统计区 | 页面、资源、文件、字节、改写链接、错误、耗时 |
| 右侧主区 | 镜像文件列表、错误清单、文件搜索 |
| 底部面板 | 镜像日志、报告预览 |
| 底部状态栏 | 关于入口 |
深度选择使用页面内的自定义下拉,而不是原生 select:
<div id="selDepth" class="custom-select" data-value="2">
<div class="select-display">2 层(默认)<span class="select-arrow">▾</span></div>
<div class="select-dropdown">
<div class="select-option" data-value="1">1 层(仅首页)</div>
<div class="select-option selected" data-value="2">2 层(默认)</div>
<div class="select-option" data-value="3">3 层</div>
<div class="select-option" data-value="5">5 层</div>
<div class="select-option" data-value="10">10 层</div>
</div>
</div>
当前界面深度可选 1、2、3、5、10,并发可选 1、4、8;引擎内部允许的范围分别是 1~30 和 1~16。两者并不矛盾:界面提供常用档位,引擎负责参数约束,但不能把引擎范围描述为界面已经提供的全部选项。
侧栏初始宽度为 300px,可拖拽到 220~460px;底部面板初始高度为 170px,可调整到 100~400px。文件表格使用滚动容器与 sticky 表头,便于在较长清单中维持列标题可见。
3.3 镜像引擎(httrack-engine.js)
镜像引擎的核心不是一个下载函数,而是一组相互配合的数据结构:待处理队列、地址映射、文件清单、待回写文件和错误列表。
1. 用 EventEmitter 组织引擎状态
function WinHTTrackEngine() {
EventEmitter.call(this);
this.opts = null;
this.outDir = '';
this.running = false;
this.visited = {}; // 归一化键 -> 条目
this.queue = [];
this.pages = []; // 需要回写改写的 page/css 条目
this.files = []; // manifest 条目
this.errors = [];
this.bytes = 0;
this.startTime = 0;
this.endTime = 0;
this.robots = null;
}
util.inherits(WinHTTrackEngine, EventEmitter);
其中 pages 并不只存放 HTML 页面,还包含需要回写链接的 CSS;files 才是生成清单的文件条目集合。将“显示类型”和“是否需要回写”分离,可以让 CSS 既显示为资源,又参与链接本地化。
2. 统一源地址入口,区分两种执行方式
WinHTTrackEngine.prototype.parseSource = function (input) {
var s = String(input || '').trim();
if (!s) return { error: '源地址为空' };
// 本地目录模式:file:// URL 或裸路径
if (/^file:\/\//i.test(s)) {
var p = decodeURIComponent(url.parse(s).pathname || '');
if (/^\/[A-Za-z]:/.test(p)) p = p.substring(1);
return this.localSource(p.replace(/\\/g, '/'));
}
if (/^[A-Za-z]:[\/\\]/.test(s) || s.charAt(0) === '/') {
return this.localSource(s.replace(/\\/g, '/'));
}
// http(s) 模式
if (!/^https?:\/\//i.test(s)) s = 'http://' + s;
var parsed;
try {
parsed = url.parse(s);
} catch (e) {
return { error: 'URL 解析失败: ' + e.message };
}
if (!parsed.hostname) return { error: '无法从地址中解析出主机名' };
var start = parsed.protocol + '//' + parsed.host + (parsed.pathname && parsed.pathname !== '/' ? parsed.pathname : '/');
return { mode: 'http', startUrl: start };
};
本地模式进一步检查源路径是否为目录,因此入口不是“选择任意一个 HTML 文件”;网络模式则从地址构造起始 URL。需要注意,当前 start 的拼接没有保留初始查询串,对依赖查询参数定位的入口页应先完善这一逻辑。
3. 本地目录模式:先复制,再统一回写
本地模式在 start 中走独立分支,源码节选如下:
if (this.opts.mode === 'local') {
setImmediate(function () {
self.loadLocalTree();
self.finish(cb);
});
return;
}
loadLocalTree 使用栈扫描目录,收集满足数量与大小条件的文件,按相对路径排序后复制。普通样例目录会形成这样的映射关系:
源目录 samples/index.html → 输出目录/samples_local/index.html
源目录 samples/about.html → 输出目录/samples_local/about.html
源目录 samples/style.css → 输出目录/samples_local/style.css
源目录 samples/sub/page3.html → 输出目录/samples_local/sub/page3.html
复制成功后,文件登记到 visited 和 files,HTML/CSS 进入待回写列表。这样,处理首页里的子目录链接时,目标文件映射已经准备好,不必依赖文件被扫描到的先后顺序。
本地模式并不使用网络递归深度、并发数和请求间隔。 它遍历的是目录树,列表中的深度是相对路径段数。数量、大小筛选仍然生效,但扫描与复制使用同步 API,也没有完善的符号链接循环防护;使用时应选择可信、规模可控的目录,并将输出目录放在源目录之外。
4. HTTP(S) 模式:批次并发与页面深度
网络模式把起始页面以深度 1 放入队列。HTML/CSS 中发现的页面引用按下一层入队,资源引用沿用当前层级;页面深度和资源下载因此可以分别处理。
WinHTTrackEngine.prototype.loop = function (done) {
var self = this;
function step() {
if (!self.running || self.queue.length === 0) return done();
var batch = self.queue.splice(0, self.opts.concurrency);
var pending = batch.length;
batch.forEach(function (item) {
self.fetchOne(item, function () {
if (--pending === 0) {
self.emit('progress', self.stats());
if (self.opts.rateDelay > 0) setTimeout(step, self.opts.rateDelay);
else setImmediate(step);
}
});
});
}
step();
};
这段代码的关键在 pending:必须等当前批次全部回调结束,才进入下一批。因此,它是批次并发调度,不是任意一个请求结束就立即补位的工作池;界面中的“请求间隔”实际作用于批次之间,也不是每一个请求的严格发送间隔。
| 参数 | 引擎默认值 | 实际作用 |
|---|---|---|
| maxDepth | 2 | 网络页面递归深度,约束到 1~30 |
| concurrency | 4 | 每批取出的任务数,约束到 1~16 |
| rateDelay | 0ms | 批次完成后到下一批之间的等待,范围 0~5000ms |
| timeout | 15000ms | 传给网络请求的超时配置,不是整个镜像任务的总时限 |
| maxFiles | 200 | 文件数量控制;当前并发检查仍有越过上限的边界 |
| maxSizeKb | 2048 | 本地文件大小或网络接收字节的筛选依据 |
| singleSite | true | 入队时进行站点 host 检查 |
| skipRobots | false | 默认尝试读取并应用简化的 robots.txt 规则 |
请求层处理 301、302、303、307、308 重定向,最多跟随 5 次;收到压缩响应后,进入 gzip、deflate 或条件支持的 Brotli 分支。当前请求头主动声明的是 gzip、deflate,Brotli 分支存在不代表请求头已经宣告支持 br。
压缩失败时部分分支会保留原始字节,且解压后没有再做大小上限检查。这些属于后续需要强化的错误处理与资源限制,不能把“具有解压分支”写成“所有压缩响应都能正确、安全处理”。
5. 链接抽取:HTML 属性与 CSS url() 分开处理
var TAG_ATTR_RE = /<\s*(a|link|script|img|iframe|source|audio|video|area|embed|frame|form)\b([^>]*)>/gi;
var ATTR_RE = /\s(href|src|poster|action)\s*=\s*("([^"]*)"|'([^']*)')/gi;
var CSS_URL_RE = /url\(\s*('([^']*)'|"([^"]*)"|([^')\s]*))\s*\)/gi;
var SKIP_RE = /^(mailto:|tel:|javascript:|data:|about:|#)/i;
抽取到的引用通过 url.resolve 转为绝对地址,再决定是否入队。邮件、电话、data URL 和纯页内锚点等不作为镜像目标处理。
这种正则方案实现紧凑,适合结构可控的静态页面,但并不是完整 HTML/CSS 解析器:不覆盖所有未加引号属性、srcset、base 标签语义、CSS 引入写法或脚本动态请求。包含 script 标签,只表示可以发现它的 src,不表示引擎会执行脚本。
6. 路径映射:文件系统路径与页面链接分开计算
HTTP 模式把主机名与 URL 路径映射到输出目录,普通无查询串地址的路径形态如下:
https://example.com/ → example.com/index.html
https://example.com/guide → example.com/guide.html
https://example.com/assets/site.css → example.com/assets/site.css
实际落盘使用 Node.js path 处理系统分隔符;写进 HTML/CSS 的链接则使用 path.posix,让链接始终使用正斜杠。
当前路径段会替换一部分非法字符并截断过长名称,但查询串映射仍可能产生冲突,部分文件名还保留问号,在 Windows 上可能无法写入。因此,上述映射适合解释普通路径,不能视为完整的跨平台 URL 文件名编码方案。
7. 链接回写:先查映射,再计算相对路径
下面是 rewriteFile 内部计算目标链接的源码节选:
function toRel(targetLocal) {
var rel = path.posix.relative(pageDir, targetLocal);
return rel || path.posix.basename(targetLocal);
}
function rewriteValue(value) {
if (!value || SKIP_RE.test(value.trim())) return null;
var abs;
try {
abs = url.resolve(entry.url, value.trim());
} catch (e) {
return null;
}
var target = self.visited[self.keyOf(abs)];
if (!target) return null;
changed++;
return toRel(target.local);
}
pageDir 是当前镜像文件的 POSIX 目录。比如从 samples_local/sub/page3.html 指向 samples_local/style.css,计算结果就是 …/style.css。
随后,CSS 将命中的引用替换为 url(“相对路径”);HTML 按原属性的引号形式写回。源码节选如下:
var out;
if (isCss) {
out = text.replace(CSS_URL_RE, function (m0, inner, q1, q2, plain) {
var value = q1 !== undefined ? q1 : (q2 !== undefined ? q2 : plain);
var rel = rewriteValue(value);
return rel === null ? m0 : 'url("' + rel + '")';
});
} else {
out = text.replace(TAG_ATTR_RE, function (tagFull) {
return tagFull.replace(ATTR_RE, function (m0, name, quote, dq, sq) {
var value = dq !== undefined ? dq : sq;
var rel = rewriteValue(value);
if (rel === null) return m0;
var q = dq !== undefined ? '"' : "'";
return ' ' + name + '=' + q + rel + q;
});
});
}
这里遵循的是“有映射才改写”。 未抓取、超出深度或无法匹配的目标保留原属性值;如果原本就是相对链接,保留它并不意味着离线后还能访问。当前对带页面片段的链接也没有完整恢复锚点,文本回写按 UTF-8 处理,特殊编码页面需要另外验证。
另外,“改写链接数”记录的是匹配并处理的引用次数,不等同于去重后的目标数量,也不保证每次处理都使字符串发生变化。
3.4 渲染进程交互(renderer.js)
渲染层通过 ipcRenderer 与主进程通信,不直接执行镜像引擎。任务交互可以概括为:
- 读取源地址、输出目录及各项参数。
- 开始时重置当前展示数据、锁定启动按钮,发送 mirror:start。
- 收到 page/asset/error 等事件后更新文件和错误信息。
- 收到 progress 后刷新统计;收到 done 后恢复按钮并整理结果列表。
停止按钮的实际实现如下:
$('btnStop').addEventListener('click', function () {
ipcRenderer.invoke('mirror:stop').then(function (r) {
if (r.success) setStatus('已请求停止,正在收尾…', 'warn');
else setStatus(r.error || '无运行中任务', 'warn');
}).catch(function () { setStatus('停止操作异常', 'danger'); });
});
文案写的是“已请求停止,正在收尾”,而不是立即宣布任务结束,与引擎的停止语义相对应。
文件列表支持按本地路径、源地址和类型筛选;日志区按等级着色,最多保留 800 行 DOM 日志。这一限制用于控制界面节点数量,不是日志文件归档机制。
分栏拖拽:
function makeResizable(handle, target, dir, min, max) {
handle.addEventListener('mousedown', function (e) {
e.preventDefault();
var start = dir === 'x' ? e.clientX : e.clientY;
var base = dir === 'x' ? target.offsetWidth : target.offsetHeight;
function move(ev) {
var delta = (dir === 'x' ? ev.clientX - start : ev.clientY - start);
var size = Math.max(min, Math.min(max, base + (dir === 'x' ? delta : -delta)));
if (dir === 'x') target.style.width = size + 'px';
else target.style.height = size + 'px';
}
function up() {
document.removeEventListener('mousemove', move);
document.removeEventListener('mouseup', up);
}
document.addEventListener('mousemove', move);
document.addEventListener('mouseup', up);
});
}
拖动期间临时绑定鼠标移动事件,松开后移除监听器。将这类页面行为封装成通用函数,可以同时服务左右分栏和上下分栏,不必引入额外的布局库。
3.5 镜像产物、结果复查与报告预览
任务收尾时,引擎依次进行链接回写、生成根索引、写入 manifest.json。以本地样例为例,输出结构如下:
镜像输出目录/
├── index.html # 镜像页面入口列表
├── manifest.json # 任务元数据、统计、文件与错误清单
└── samples_local/
├── index.html
├── about.html
├── style.css
├── logo.svg
└── sub/
├── page3.html
└── deep.html
其中根索引与 samples_local/index.html 不是同一个文件:前者是引擎生成的导航页,后者是源站首页的镜像。
清单内容:
| 层级 | 字段 |
|---|---|
| 任务信息 | generator、source、mode、outDir、startedAt、finishedAt |
| stats | pages、assets、files、bytes、errors、elapsedMs、rewrittenLinks |
| files 每项 | url、local、type、depth、status、size、missing |
| errors 每项 | url、error |
主进程另在 userData 下写入 winhttrack-last.json,记录成功回调所对应的输出目录、源地址、模式与时间戳。读取历史结果时,如果传入了目录,就以该目录为准;没有传入时,才尝试使用这份上次记录。
复查的本质是重新读取清单:
function loadManifest(outDir) {
var p = path.join(outDir, 'manifest.json');
if (!fs.existsSync(p)) return null;
try {
return JSON.parse(fs.readFileSync(p, 'utf-8'));
} catch (e) {
return null;
}
}
这一实现不重新访问网络,也不逐个检查镜像文件是否还存在,更没有计算文件哈希。它解决的是“重新查看上次记录”,不是断点续抓或产物完整性验证。
报告按钮当前生成文本预览:
$('btnExport').addEventListener('click', function () {
var dir = state.currentOutDir || $('txtOutDir').value.trim();
ipcRenderer.invoke('mirror:exportReport', dir, 'text').then(function (r) {
if (!r.success) {
setStatus('导出失败:' + (r.error || '无镜像结果'), 'warn');
return;
}
$('reportOutput').textContent = r.report;
switchBottomTab('report');
setStatus('报告已生成(见「报告预览」)', 'ok');
}).catch(function () { setStatus('导出操作异常', 'danger'); });
});
主进程能够返回 JSON 字符串,但界面固定传入 text,没有格式选择器,也没有报告保存对话框。已经落盘的 JSON 产物是 manifest.json;报告字符串与报告文件应当分开描述。
还有两个影响结果理解的细节:根目录已有 index.html 时,当前 writeIndex 会直接跳过;统计中的 endTime 在链接回写前设置,因此 elapsedMs 不覆盖后续全部回写和元数据落盘时间。重复测试宜使用新的独立输出目录,不能把该耗时直接当作完整任务的性能基准。
3.6 Catppuccin Mocha 深色主题
界面以 Catppuccin Mocha 配色组织层级,底色、面板、边框与状态色集中定义。下面是主题变量的源码节选:
--base: #1e1e2e;
--mantle: #181825;
--crust: #11111b;
--surface0: #313244;
--surface1: #45475a;
--surface2: #585b70;
--overlay0: #6c7086;
--overlay1: #7f849c;
--text: #cdd6f4;
--subtext0: #a6adc8;
--subtext1: #bac2de;
--blue: #89b4fa;
--green: #a6e3a1;
--red: #f38ba8;
--yellow: #f9e2af;
| 视觉用途 | 对应设计 |
|---|---|
| 工作区层级 | base 用于主背景,mantle/crust 区分工具栏与底栏 |
| 输入与控件 | surface 系列提供输入框底色、边框和悬停层次 |
| 主要操作 | 蓝色强调“镜像”和当前标签 |
| 状态反馈 | 绿色表示正常结果,黄色用于提醒,红色突出错误 |
| 长列表阅读 | 等宽路径文字、固定表头、行悬停背景 |
| 数字统计 | tabular-nums 保持数值宽度更稳定 |
主题共声明 23 个颜色变量,布局以 Flex 为主,没有依赖大型组件库。自研下拉与关于弹层都在当前页面中绘制,便于与整体主题保持一致;键盘操作和焦点管理仍需按桌面无障碍要求继续完善。
四、鸿蒙稳定性适配
4.1 禁用默认菜单栏
工程启动阶段显式关闭硬件加速并移除默认菜单,源码里这两件事各带一行说明注释:
// 防 GPU 白屏:禁用硬件加速
app.disableHardwareAcceleration();
// 去掉顶部 File/Edit/View/Window/Help 默认菜单栏
Menu.setApplicationMenu(null);
移除默认菜单后,应用的主要操作集中在自有工具栏内,不依赖 File/Edit/View 等默认菜单入口。禁用硬件加速是当前工程采用的渲染配置,需要结合实际平台表现权衡,并不是所有鸿蒙应用都必须照搬的固定规则。
4.2 自定义关于弹窗
关于信息使用页面内 fixed 遮罩,不额外创建一个系统弹窗。打开与关闭只切换 hidden 类:
function openAboutDialog() {
var l = document.getElementById('aboutDialogLayer');
if (l) l.classList.remove('hidden');
}
function closeAboutDialog() {
var l = document.getElementById('aboutDialogLayer');
if (l) l.classList.add('hidden');
}
对应的遮罩样式如下:
#aboutDialogLayer.about-layer {
position: fixed;
top: 0; left: 0; right: 0; bottom: 0;
background: rgba(17, 17, 27, 0.72);
display: flex;
align-items: center;
justify-content: center;
z-index: 9999;
}
#aboutDialogLayer.hidden { display: none; }
弹窗显示开源说明、免责声明和许可文字。当前已接通右下角入口与关闭按钮,但没有完整的 Escape 关闭、焦点圈定和焦点恢复逻辑;页面上的许可说明也不能代替代码、原生库及第三方材料的正式许可核验。
4.3 鸿蒙窗口配置与适用边界
主窗口沿用壳工程中的三个组合配置:
| 配置 | 当前取值 | 作用 |
|---|---|---|
| frame | true | 保留系统窗口边框与装饰 |
| transparent | false | 使用非透明窗口 |
| resizable | true | 允许用户调整窗口尺寸 |
窗口宽高从 workAreaSize 计算,避免直接把桌面全部像素尺寸当作可用工作区。外层 try-catch 可以捕获同步创建过程中的异常,但不能覆盖所有异步页面加载失败,也不能替代渲染进程异常处理和真机验证。
这里应区分“工程已采用的配置”与“经过验证的故障结论”:没有对应日志、复现步骤和对照实验,就不应把某个窗口参数写成所有机型崩溃的唯一原因。
4.4 IPC 分层与文件访问边界
本项目没有把文件写入绕到渲染进程,而是让目录选择、镜像读写和报告生成继续集中在主进程及引擎中:
渲染层提交参数
↓ mirror:start
主进程创建引擎、调度执行
↓ 引擎事件
主进程转发日志/进度/文件/错误
↓ mirror:done
渲染层恢复交互并展示结果
这使 UI 不必掌握底层复制与网络细节,也避免把一次耗时任务塞进一个等待最终结果的界面调用中。但 setImmediate 只是事件循环调度,不会自动创建工作线程;同步目录扫描、文件复制和回写仍然会占用主进程。
安全边界同样重要: 当前窗口开启 nodeIntegration、关闭 contextIsolation,页面中也没有配置 CSP。它加载的是应用自带的 index.html,不能把下载来的不可信网页直接替换进这个高权限窗口。未来增加镜像预览时,应使用禁用 Node、启用隔离并限制导航的独立预览环境,同时完善 IPC 输入校验。
五、构建与部署
下面三张图片来自本项目提供的应用截图,依次展示初始界面、本地样例镜像结果和关于弹窗。它们是已有素材,不是本次文章编写时重新构建或测试产生的截图。

图 1:初始界面。 顶部是镜像任务入口,左侧是目录与参数,右侧为文件/错误列表,底部预留日志和报告预览区域。默认深度为 2,并发为 4,最大文件数为 200,单文件上限为 2048 KB。

图 2:本地样例结果。 截图显示 6 个镜像文件、4 个页面、2 个资源、16 处链接处理和 0 条错误,界面耗时为 39ms。这里的 6 个文件是清单中的镜像条目,不包括额外生成的根索引与 manifest.json;39ms 仅是这张截图的统计值,并非全链路性能承诺。截图中的深度 5 是预设参数,本地目录复制并不按网络爬取深度裁剪。

图 3:关于弹窗。 采用页面内遮罩和居中面板,背景仍保留镜像结果,用户可在不离开主界面的情况下查看说明并关闭弹窗。
5.1 本地调试
在已经准备好可调用 Electron 的开发环境中,进入业务 app 目录后启动:
Set-Location 'D:\A鸿蒙项目\GitCode\四期\ohos_HTTrack_electron-main\ohos_hap\web_engine\src\main\resources\resfile\resources\app'
npm start
这里运行的是 package.json 中的 electron .,不是普通浏览器预览,也不是 HAP 构建。若提示找不到 Electron,应先配置开发运行时,而不是反复执行没有声明依赖的安装命令。
建议优先按本地样例验证操作链:
- 点击“本地样例站”,确认源地址自动填入 samples 的实际目录。
- 选择位于源目录之外、具有写权限的独立输出目录。
- 点击“镜像”,观察文件、资源、日志及统计的变化。
- 在输出目录检查 samples_local、根 index.html 和 manifest.json。
- 点击“复查”查看清单,点击“导出”查看文本报告。
- 在普通浏览器或隔离环境中检查镜像页面的导航、样式和图片,不在开启 Node 的应用窗口中加载外来内容。
外网站点预设只是地址快捷入口,不代表当前网络、站点授权、访问规则或镜像完整性已经得到验证。网络测试应使用自有或获授权的站点,并从低并发、小规模任务开始。
5.2 部署到鸿蒙壳工程
当前工程的业务部署位置是:
ohos_hap/web_engine/src/main/resources/resfile/resources/app/
main.js、httrack-engine.js、renderer.js、index.html、package.json、styles 和 samples 需要一起进入该目录。只更新页面而遗漏引擎,或者只复制 JavaScript 而遗漏样例与样式,都会造成资源与逻辑版本不一致。
本工程直接在上述资源目录中维护业务代码。若之后另设独立开发目录,应建立明确的源码同步流程,保证进入 HAP 的文件与本地调试版本一致;build 目录中的中间产物不应作为日常修改入口。
样例定位由主进程使用 path.join(__dirname, ‘samples’) 完成。界面初始化后通过 mirror:getSamplesDir 获取路径,因此不需要把某台设备上的资源绝对路径写死到 HTML 中。
5.3 构建 HAP 包
使用 DevEco Studio 打开 ohos_hap 工程,先完成 SDK、OHPM 依赖与签名配置检查,再构建 electron 入口模块。当前配置中的关键值如下:
| 配置位置 | 当前值 |
|---|---|
| build-profile.json5 产品 | default |
| 产品 runtimeOS | HarmonyOS |
| 产品 compatibleSdkVersion | 5.0.5(17) |
| electron 模块 target | default,应用于 default 产品 |
| electron 模块类型 | entry |
| electron 本地模块依赖 | web_engine:file:…/web_engine |
| AppScope 包名 | com.huawei.ohos_electron,仍为模板值 |
| AppScope app_name | Electron,仍为模板显示名 |
若开发环境已经提供可调用的 hvigorw 命令,可在 ohos_hap 根目录按以下参数构建调试 HAP:
hvigorw assembleHap --mode module -p product=default -p module=electron@default -p buildMode=debug
命令中的 default 来自当前工程产品配置,electron@default 表示模块与 target,不应把项目目录名称直接当成产品名。若当前环境未提供该命令入口,应使用 DevEco Studio 对应的构建操作,或按本机工具链配置调用 Hvigor。
发布前还需完成: 为应用设置独立包名与正确显示名,核对相关语言资源和 Ability 标签,保持包名、证书、Profile 与签名配置一致,检查模板快捷方式及权限声明,并核实原生库和项目材料的许可证。不能以默认调试配置代替正式发布准备。
本节给出的是当前配置对应的操作说明;本次文章整理没有执行 HAP 构建、安装或新增真机验证,不能据此宣称已经完成发布验收。
六、常见问题与解决方案
以下问题依据当前源码链路整理。“待完善”表示建议的后续实现,不表示这些修改已经落入工程。
Q1:目录选择失败后,为什么提示手动输入,却无法编辑路径?
问题现象: 主进程在目录对话框失败时返回“请手动输入路径”,但左侧输出目录框无法输入。
根因分析: index.html 中 txtOutDir 带有 readonly 属性。提示文案描述了一个当前界面没有开放的备用操作。
解决: 当前先使用“默认”目录或恢复可用的目录选择流程,并确认目标目录可写。若要真正支持手动输入,需要同步开放输入、增加路径校验并调整提示;仅更换提示文字或仅移除 readonly 都不等于完成了路径安全与权限处理。
Q2:文件已经复制,为什么还有链接打不开?
问题现象: 文件数看起来正常,但个别页面跳转失败、图片或样式未完整呈现。
根因分析: 链接只有在映射表存在目标时才回写,未命中的原属性会保留。当前样例首页就引用了 docs/report.html,而提供的六份样例文件中并没有这个文件;这种缺失引用并不会自动变成一次下载错误。因此,“0 错误”不等于“全部链接有效”。
此外,网络镜像还可能受到页面深度、站点范围、解析覆盖和字符编码限制。srcset、动态接口、未完整保留的查询串与锚点,也不能靠增加并发解决。
解决: 先检查目标是否真实存在、是否进入清单,再检查链接的解析和映射。后续应补充缺失引用报告、查询串安全编码、锚点保留及更完整的 HTML/CSS 解析;不要把所有链接失效都归因于鸿蒙文件访问。
Q3:设置了最大文件数与单文件上限,为什么仍不能视为严格资源限制?
问题现象: 并发任务的最终文件数可能越过设定值,压缩内容解压后也可能大于接收上限。
根因分析: 网络任务在发起请求前检查 files.length,但同批多个请求可能同时通过检查。队列只有 visited 去重,没有完整的排队中/请求中集合;同一地址也可能在登记前被重复请求。网络大小检查发生在压缩响应接收阶段,解压之后没有第二次上限检查。
解决: 当前使用小规模、低并发的授权目标。待完善时,应增加任务名额预留、queued/inflight 去重、解压后大小与总量限制,以及一次性完成回调保护。超时、错误和主动中止等分支也应确保一个任务只结束一次。
Q4:调用了 setImmediate,为什么大目录镜像时停止操作仍可能延迟?
问题现象: 本地目录较大时,用户点击停止不能立即中断复制。
根因分析: setImmediate 只是推迟执行,loadLocalTree 内部仍使用 readdirSync、statSync、copyFileSync 等同步调用,循环也没有持续检查停止标志。网络 stop 则主要修改 running 并清空队列,没有统一销毁全部在途请求。
解决: 当前选择规模可控、没有复杂符号链接的独立源目录。后续可改为异步分片遍历或独立工作进程,记录并取消请求句柄,并在扫描、复制、回写之间检查取消状态;同时补齐目录越界、符号链接循环和源输出重叠检查。
教训: 异步入口、后台执行、可取消任务是三个不同概念,需要分别设计。
Q5:显示“完成”或点击“导出”,是否代表所有文件都已正确保存?
问题现象: 点击导出没有出现保存窗口,或者界面结果与实际目录内容不完全一致。
根因分析: 导出按钮只把文本放到报告预览区。网络路径中,文件条目登记发生在实际写入之前;根索引和 manifest 写入失败会记录错误,但收尾函数仍可能返回 success: true,已经取得的统计快照也不一定包含后续写入错误。复查只读清单,不验证文件。
另外,任务完成消息中的文件和错误列表分别截取前 2000 项、前 200 项,而角标显示总数;manifest 使用完整列表。新任务开始时旧的 currentOutDir 也未一并清空,报告可能仍指向上次结果。
解决: 使用新的独立输出目录,核对日志、manifest 和实际产物,并确认报告中的源与目录。后续应将成功登记移到落盘之后,统一收尾错误与完成状态,清理旧任务展示状态,增加文件验证,并单独实现报告另存为功能。
Q6:启用了站点限制和 robots.txt,是否就可以安全抓取任意站点?
问题现象: 界面存在相关选项,容易让人误认为它们已经构成完整的访问边界和合规保证。
根因分析: 当前 robots.txt 只做简化的 Disallow 前缀匹配,并且过滤掉了值为“/”的规则,无法正确执行这类整站禁止声明;重定向目标没有重新经过完整的站点准入检查。请求配置还设置了 rejectUnauthorized: false,并在部分 HTTPS 连接错误时尝试降级 HTTP。
解决: 当前网络验证应限定在自有或获授权的受控环境,不用于敏感资料采集。面向真实站点前,应恢复证书校验、取消自动协议降级,完善 robots.txt 解析,对重定向及每个目标重新检查访问策略,遵守站点规则、内容许可与合理速率。
教训: “请求能够成功”不能代替身份校验、访问授权和协议安全;默认勾选的功能也不意味着实现已经完整。
Q7:修改了页面标题,为什么安装后的名称仍是 Electron,或者构建参数不生效?
问题现象: 页面中显示 WinHTTrack,但系统应用名称还是模板值;构建时找不到指定产品或 target。
根因分析: 页面 title、AppScope 的 app_name 和入口 Ability 的 label 属于不同配置。当前 AppScope 显示名仍为 Electron,包名仍为 com.huawei.ohos_electron;构建产品实际是 default,并不是项目目录名。
解决: 分别核对 AppScope、入口模块及实际语言资源,统一正式应用标识;使用 product=default、module=electron@default 对应当前构建配置。如果出现签名别名、证书或 Profile 不匹配,应检查同一套签名材料与应用标识,不在文章或代码中公开签名密码。
同时确认修改的是 web_engine/src/main/resources/resfile/resources/app 下的业务源码,重新构建并安装目标产物。只修改本地副本或旧 build 目录,不会自动更新设备上已经安装的应用。
七、总结
WinHTTrack 鸿蒙 PC 适配工程把一个网站离线镜像工具拆成了可理解的几个环节:源识别、任务调度、内容获取、路径映射、链接回写和结果展示。它的价值在于用规模较小的 JavaScript 业务层,把网络模式与本地模式接入同一套桌面操作界面,并通过清单与事件把处理过程显式呈现出来。
| 核心特性 | 实现方案 |
|---|---|
| 双模式镜像 | HTTP(S) 队列抓取 + 本地目录扫描复制 |
| 页面/资源分类 | 扩展名、内容类型与回写标记分别处理 |
| 链接本地化 | URL 解析 + visited 映射 + POSIX 相对路径 |
| 可观察任务 | EventEmitter + 7 个请求响应 IPC + 6 类推送 |
| 镜像产物 | 文件目录、根 index.html、manifest.json |
| 历史与报告 | 清单复查、上次目录记录、文本报告预览 |
| 桌面交互 | 深色主题、自研下拉、分栏拖拽、关于遮罩 |
| 鸿蒙集成 | electron 入口 + web_engine 适配层与资源打包 |
关键经验:
- 下载文件只是第一步,地址关系才是离线镜像的核心。 路径映射、查询串、锚点与缺失引用必须独立验证,不能只看文件数和完成提示。
- 架构分层需要与执行语义一起设计。 主进程集中管理任务有利于维护,但同步 I/O、取消请求、并发配额和结果落盘仍要逐项完善,不能把 setImmediate 当成后台线程。
- 适配记录应明确区分源码能力、截图现象与发布验证。 本地样例可以帮助观察主链路,不能替代真实网站兼容性、网络安全、签名配置和真机回归测试。
当前工程已经形成从参数输入到双模式处理、链接回写、清单与报告展示的实现主线。继续面向正式使用推进时,应优先完善传输安全、访问规则、路径映射、任务取消和产物一致性,再补充更复杂页面的解析能力与平台回归验证。这样的适配过程,既保留了 Electron 壳方案复用前端与 Node.js 能力的优势,也让每一项功能的完成范围有据可查。
更多推荐




所有评论(0)