@windcoder/astro-theme-orchid 0.2.1 → 0.4.0

package/README.md

@@ -2,13 +2,15 @@
 
 清新简约的 Astro 博客主题，以 **Astro Integration** 形式提供：站点只做三件事——声明域名、接入主题、传入配置；页面、样式引擎、路由全部由主题注入。支持版本化升级与组件覆盖（`src/overrides/` 同名替换，升级永不覆盖站点定制）。
 
+> 部分功能设计参考了 [Firefly](https://github.com/CuteLeaf/Firefly) 主题，在此致谢。
+
 ## 特性一览
 
-- **页面**：首页（featured/cover/compact/text 四种卡片混排）、文章页（TOC/相关推荐/分享海报/打赏入口）、归档（按年折叠）、分类、标签、专题、画廊（含加密相册）、友链、留言板、打赏、关于
+- **页面**：首页（featured/cover/compact/text 四种卡片混排）、文章页（TOC/相关推荐/分享海报/打赏入口）、归档（按年折叠）、分类、标签、专题、画廊（含加密相册）、友链、追番、留言板、打赏、关于
 - **写作增强**：LaTeX（KaTeX + mhchem）、Mermaid 双主题、PlantUML、Callouts、GitHub 卡片、图语法（figure/九宫格）、Expressive Code 代码块（双主题/行号/折叠/复制/语言徽标）、邮箱防爬
 - **互动系统**：评论五套（Artalk / Twikoo / Waline / Giscus / Disqus）、文章加密、过时提醒、公告、广告位
 - **个性化**：深浅模式、hue 动态调色、樱花飘落、背景壁纸、音乐播放器（跨页不断播）、Live2D 看板娘、i18n（zh-CN / en）
-- **工程化**：配置启动即校验（Zod）、OG 分享图、LQIP 占位、字体子集化、站点统计四件套（GA / Clarity / Umami / 51.la）、RSS / sitemap
+- **工程化**：配置启动即校验（Zod）、OG 分享图、LQIP 占位、字体子集化、站点统计四件套（GA / Clarity / Umami / 51.la）、RSS / sitemap、PWA 可安装（manifest + 离线兜底 Service Worker）
 
 ## 快速上手
 
@@ -81,7 +83,7 @@ site/
 完整配置说明与文章 frontmatter 全字段表统一放在 demo 站「主题使用指南」系列文章（源文件在本仓库 `site/src/content/posts/`），按主题分组：
 
 - 基础：《站点基础配置》｜《导航栏》｜《首页横幅》｜《侧边栏与小组件》｜《个人资料卡》｜《版权声明》｜《文章列表与归档》
-- 功能：《文章页功能》｜《内容渲染》｜《樱花特效》｜《音乐播放器》｜《Live2D 看板娘》｜《字体》｜《评论系统》｜《公告》｜《站点统计》｜《广告位》｜《友链》｜《赞助》｜《画廊》｜《独立页面》
+- 功能：《文章页功能》｜《内容渲染》｜《樱花特效》｜《音乐播放器》｜《Live2D 看板娘》｜《字体》｜《评论系统》｜《公告》｜《站点统计》｜《广告位》｜《友链》｜《追番》｜《PWA》｜《赞助》｜《画廊》｜《独立页面》
 - 写作：《写作指南》（frontmatter 全字段与增强语法）｜《MDX 指南》（MDX 启用与踩坑修复）
 
 ## 定制与覆盖

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@windcoder/astro-theme-orchid",
-	"version": "0.2.1",
+	"version": "0.4.0",
 	"description": "清新简约的 Astro 博客主题，以 Integration 形式提供，支持版本化升级与组件覆盖",
 	"type": "module",
 	"keywords": [
@@ -64,7 +64,9 @@
 		"satori": "^0.47.1",
 		"sharp": "^0.35.5",
 		"subset-font": "^2.5.0",
-		"tailwindcss": "^4.3.2"
+		"tailwindcss": "^4.3.2",
+		"web-vitals": "^6.2.3",
+		"yaml": "^2.9.1"
 	},
 	"devDependencies": {
 		"@types/pako": "^2.0.3",

package/scripts/check-friends.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * 友链存活检测（§4.90）：读取构建产物 dist/friends/index.html，抽取友链卡片
+ * （a.friend-card + .friend-name），并发探测各站点可达性，输出检测报告。
+ *
+ * 设计为发布后/定时（CI cron）手动运行，不挂进 build——构建保持离线可复现。
+ *
+ * 用法（站点根目录）：
+ *   node node_modules/@windcoder/astro-theme-orchid/scripts/check-friends.mjs \
+ *     [--dist dist] [--timeout 8000] [--retries 1] [--concurrency 6] \
+ *     [--json report.json] [--fail-on-dead]
+ *
+ * 判级：ok = 2xx/3xx；warn = 403/405/406/429/999（常见反爬拦截，未必失联）；
+ * dead = 网络层失败（解析/超时/拒绝）与其余 4xx/5xx。网络层失败与 5xx 重试。
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const UA =
+	"Mozilla/5.0 (compatible; OrchidFriendChecker/+https://github.com/iwinder/qy-astro-theme-orchid)";
+/** 这些状态码通常是 WAF/反爬拦截而非失联，只警告不定罪 */
+const WARN_CODES = new Set([403, 405, 406, 429, 999]);
+
+function parseArgs(argv) {
+	const args = {
+		dist: "dist",
+		timeout: 8000,
+		retries: 1,
+		concurrency: 6,
+		json: "",
+		failOnDead: false,
+	};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--dist") args.dist = argv[++i];
+		else if (a === "--timeout") args.timeout = Number(argv[++i]);
+		else if (a === "--retries") args.retries = Number(argv[++i]);
+		else if (a === "--concurrency") args.concurrency = Number(argv[++i]);
+		else if (a === "--json") args.json = argv[++i];
+		else if (a === "--fail-on-dead") args.failOnDead = true;
+		else if (a === "--help" || a === "-h") {
+			console.log(
+				"用法：node check-friends.mjs [--dist dist] [--timeout 8000] [--retries 1] [--concurrency 6] [--json report.json] [--fail-on-dead]",
+			);
+			process.exit(0);
+		}
+	}
+	return args;
+}
+
+function decodeEntities(s) {
+	return s
+		.replace(/&amp;/g, "&")
+		.replace(/&lt;/g, "<")
+		.replace(/&gt;/g, ">")
+		.replace(/&quot;/g, '"')
+		.replace(/&#39;/g, "'");
+}
+
+/** 从友链页 HTML 抽取 [{ title, url }]（主题自有标记，结构稳定） */
+export function extractFriends(html) {
+	const out = [];
+	const re =
+		/<a class="friend-card card" href="([^"]+)"[\s\S]*?<div class="friend-name">([\s\S]*?)<\/div>/g;
+	let m;
+	while (true) {
+		m = re.exec(html);
+		if (!m) break;
+		out.push({
+			url: decodeEntities(m[1]),
+			title: decodeEntities(m[2].replace(/<[^>]+>/g, "")).trim(),
+		});
+	}
+	return out;
+}
+
+/** HTTP 状态码 → ok/warn/dead 判级（0 = 网络层失败） */
+export function classify(code) {
+	if (code === 0) return "dead";
+	if (code >= 200 && code < 400) return "ok";
+	if (WARN_CODES.has(code)) return "warn";
+	return "dead";
+}
+
+/** 单次探测：GET + 超时 + 立即丢弃响应体（只看状态码） */
+async function probeOnce(url, timeout) {
+	const started = Date.now();
+	try {
+		const res = await fetch(url, {
+			redirect: "follow",
+			signal: AbortSignal.timeout(timeout),
+			headers: { "user-agent": UA, accept: "text/html,*/*;q=0.8" },
+		});
+		res.body?.cancel().catch(() => {});
+		return { code: res.status, ms: Date.now() - started, msg: "" };
+	} catch (err) {
+		const cause = err?.cause?.code ?? err?.code ?? "";
+		const msg =
+			err?.name === "TimeoutError" || err?.name === "AbortError"
+				? "超时"
+				: cause === "ENOTFOUND" || cause === "EAI_AGAIN"
+					? "域名无法解析"
+					: cause === "ECONNREFUSED"
+						? "连接被拒绝"
+						: cause === "ECONNRESET"
+							? "连接被重置"
+							: cause === "CERT_HAS_EXPIRED" ||
+									cause === "UNABLE_TO_VERIFY_LEAF_SIGNATURE"
+								? "证书异常"
+								: String(cause || err?.message || err);
+		return { code: 0, ms: Date.now() - started, msg };
+	}
+}
+
+/** 带重试探测：网络层失败与 5xx 重试（4xx 定局重试无意义） */
+export async function probe(url, { timeout, retries }) {
+	let last = await probeOnce(url, timeout);
+	for (let i = 0; i < retries && (last.code === 0 || last.code >= 500); i++) {
+		last = await probeOnce(url, timeout);
+	}
+	return { ...last, state: classify(last.code) };
+}
+
+/** CJK 感知的终端定宽 */
+function pad(s, width) {
+	let visual = 0;
+	for (const ch of s) visual += ch.codePointAt(0) > 0xff ? 2 : 1;
+	return visual >= width ? s : s + " ".repeat(width - visual);
+}
+
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+	const pagePath = resolve(args.dist, "friends", "index.html");
+	let html;
+	try {
+		html = readFileSync(pagePath, "utf8");
+	} catch {
+		console.error(
+			`[check-friends] 找不到 ${pagePath}\n  友链页未开启（pages.friends: false）或尚未构建；先 pnpm build 再检测。`,
+		);
+		process.exit(0);
+	}
+
+	const friends = extractFriends(html);
+	if (!friends.length) {
+		console.log("[check-friends] 友链页无友链卡片，无事可做。");
+		process.exit(0);
+	}
+	console.log(
+		`[check-friends] 共 ${friends.length} 条友链，并发 ${args.concurrency}，超时 ${args.timeout}ms，重试 ${args.retries} 次\n`,
+	);
+
+	const results = new Array(friends.length);
+	let cursor = 0;
+	async function worker() {
+		while (cursor < friends.length) {
+			const idx = cursor++;
+			const { url, title } = friends[idx];
+			process.stdout.write(`  探测 ${title} …\r`);
+			const r = await probe(url, args);
+			results[idx] = { ...r, title, url };
+		}
+	}
+	await Promise.all(
+		Array.from({ length: Math.min(args.concurrency, friends.length) }, worker),
+	);
+
+	const ICON = { ok: "✓", warn: "⚠", dead: "✗" };
+	console.log(
+		"\n┌────┬──────┬────────┬────────┬──────────────────────┬──────────────────────────────────────┐",
+	);
+	console.log(
+		`│ ${pad("状态", 2)} │ ${pad("站点", 18)} │ ${pad("HTTP", 6)} │ ${pad("耗时", 6)} │ ${pad("说明", 20)} │ 链接`,
+	);
+	console.log(
+		"├────┼──────┼────────┼────────┼──────────────────────┼──────────────────────────────────────┤",
+	);
+	for (const r of results) {
+		const note = r.state === "warn" ? "疑似反爬拦截，请人工复核" : r.msg;
+		console.log(
+			`│ ${ICON[r.state]}  │ ${pad(r.title, 18)} │ ${pad(String(r.code || "-"), 6)} │ ${pad(`${r.ms}ms`, 6)} │ ${pad(note, 20)} │ ${r.url}`,
+		);
+	}
+	console.log(
+		"└────┴──────┴────────┴────────┴──────────────────────┴──────────────────────────────────────┘",
+	);
+
+	const ok = results.filter((r) => r.state === "ok").length;
+	const warn = results.filter((r) => r.state === "warn").length;
+	const dead = results.filter((r) => r.state === "dead").length;
+	console.log(`\n[check-friends] 完成：ok ${ok} / warn ${warn} / dead ${dead}`);
+	if (warn)
+		console.log(
+			"  ⚠ warn 为常见反爬状态码（403/405/406/429/999），浏览器开一下再决定是否下架",
+		);
+	if (dead) {
+		for (const r of results.filter((x) => x.state === "dead"))
+			console.log(`  ✗ ${r.title} <${r.url}> ${r.msg || `HTTP ${r.code}`}`);
+	}
+
+	if (args.json) {
+		const report = {
+			checkedAt: new Date().toISOString(),
+			total: friends.length,
+			ok,
+			warn,
+			dead,
+			results: results.map(({ title, url, state, code, ms, msg }) => ({
+				title,
+				url,
+				state,
+				code,
+				ms,
+				msg,
+			})),
+		};
+		writeFileSync(resolve(args.json), `${JSON.stringify(report, null, 2)}\n`);
+		console.log(`  报告已写入 ${resolve(args.json)}`);
+	}
+
+	if (args.failOnDead && dead > 0) process.exit(1);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+	main();
+}

package/scripts/generate-lqips.mjs

@@ -1,25 +1,46 @@
 #!/usr/bin/env node
 /**
- * LQIP 生成脚本（M3b-b9，P1-14）：扫描站点 public 下的图片，每张采样
- * 2×2 像素取三色，产出 18 字符 compact hex（三段 rgb hex 拼接），
- * 整体写入站点根 lqips.json（键 → 色，全量重建，增量收益有限故不做）。
+ * LQIP + 缩略图生成脚本（M3b-b9，P1-14；§4.106 扩展双产物；§4.107 外链 LQIP）：
+ * 产出两份构建期元数据：
+ * 1. lqips.json：每张采样 2×2 像素取三色 → 18 字符 compact hex（三段 rgb hex 拼接）。
+ *    两类键：`public:<posix 相对路径>`（站点 public 图片）+ `url:<完整外链 URL>`
+ *    （文章封面/正文首图/相册 urls.txt 等外链图，fetch 下载后同样采样——
+ *    缓存即产物自身：已有 url: 键不重复抓取，`--refresh` 强制重抓）。
+ * 2. thumbs.json：每张 public 图同步生成同目录 `<名>.thumb.webp`（480 宽 q75，
+ *    不放大小图），并记录原图宽高（灯箱打开原图时需正确原始尺寸）。
+ *    外链图不做缩略图（版权/CORS/构建网络依赖，消费端回退原图）。
  *
  * 运行：pnpm --filter site lqip（cwd 必须是 site 根）
- * 消费链路：lqips.json → themeLqipsPlugin（vite.ts）→ virtual:theme/lqips
- *   → utils/lqip.ts getLqipStyle() → 构建期内联渐变（零客户端请求）。
+ * 消费链路：
+ *   lqips.json  → themeLqipsPlugin（vite.ts）→ virtual:theme/lqips
+ *     → utils/lqip.ts getLqipStyle() / rehypeImageEnhance() → 构建期内联渐变；
+ *   thumbs.json → themeLqipsPlugin（vite.ts）→ virtual:theme/thumbs
+ *     → utils/thumb.ts getThumbInfo() → 列表封面构建期换缩略图 URL。
  *
- * 键约定：`public:<posix 相对路径>`。主题图片一律 public 路径或外链
- * （不用 astro:assets），故无需 src: 键；外链/无数据在消费端自然降级纯色。
- * sharp 经本脚本文件位置解析到 theme 包依赖，与 cwd 无关。
+ * 外键一致性约定：url: 键的 URL 必须与渲染期逐字符一致——
+ *   - frontmatter image / 正文首图 / urls.txt 行：原样提取（与 gallery.ts 的
+ *     trim + `#` 注释过滤规则相同）；
+ *   - image:"api"：复刻 utils.ts 的 randomCoverUrl（seedHash + ?v= 追加），
+ *     apis 模板从 site/src/config/*.ts 正则提取首个 apis 数组。
+ * 相册「显式外链 cover」（相册元数据字段）暂不收集：demo 站无此用法，
+ * 且元数据格式多样，出现需求时再扩展。sharp 经本脚本位置解析 theme 依赖。
  */
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import sharp from "sharp";
 
 const cwd = process.cwd();
 const publicDir = path.join(cwd, "public");
-const outFile = path.join(cwd, "lqips.json");
+const srcDir = path.join(cwd, "src");
+const lqipFile = path.join(cwd, "lqips.json");
+const thumbsFile = path.join(cwd, "thumbs.json");
+
+const THUMB_WIDTH = 480;
+const THUMB_QUALITY = 75;
+const THUMB_SUFFIX = ".thumb.webp";
+const FETCH_CONCURRENCY = 5;
+const FETCH_TIMEOUT_MS = 15_000;
+const REFRESH = process.argv.includes("--refresh");
 
 const EXTS = new Set([".png", ".jpg", ".jpeg", ".webp", ".avif"]);
 const EXCLUDED_DIRS = new Set(["node_modules", ".astro", "dist", ".git"]);
@@ -29,7 +50,7 @@ if (!fs.existsSync(publicDir)) {
 	process.exit(1);
 }
 
-/** 递归收集图片相对路径（posix 风格，排除构建/依赖目录） */
+/** 递归收集图片相对路径（posix 风格，排除构建/依赖目录与缩略图产物） */
 function collectImages(dir, base = "") {
 	const out = [];
 	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -41,7 +62,10 @@ function collectImages(dir, base = "") {
 					base ? `${base}/${entry.name}` : entry.name,
 				),
 			);
-		} else if (EXTS.has(path.extname(entry.name).toLowerCase())) {
+		} else if (
+			EXTS.has(path.extname(entry.name).toLowerCase()) &&
+			!entry.name.endsWith(THUMB_SUFFIX)
+		) {
 			out.push(base ? `${base}/${entry.name}` : entry.name);
 		}
 	}
@@ -49,8 +73,8 @@ function collectImages(dir, base = "") {
 }
 
 /** sharp 2×2 fill 采样 → 取 [0][1][3] 三像素（左上/右上/右下）rgb hex 拼接 */
-async function sampleColors(file) {
-	const { data, info } = await sharp(file)
+async function sampleColors(input) {
+	const { data, info } = await sharp(input)
 		.resize(2, 2, { fit: "fill" })
 		.removeAlpha()
 		.raw()
@@ -64,19 +88,209 @@ async function sampleColors(file) {
 	return hex(0) + hex(1) + hex(3);
 }
 
+/** 生成 480 宽 webp 缩略图（不放大小图），返回 { thumb 相对路径, 原图宽高 } */
+async function makeThumb(rel) {
+	const file = path.join(publicDir, rel);
+	const parsed = path.parse(rel);
+	const thumbRel = path.posix.format({
+		dir: parsed.dir,
+		name: `${parsed.name}.thumb`,
+		ext: ".webp",
+	});
+	const meta = await sharp(file).metadata();
+	await sharp(file)
+		.resize({ width: THUMB_WIDTH, withoutEnlargement: true })
+		.webp({ quality: THUMB_QUALITY })
+		.toFile(path.join(publicDir, thumbRel));
+	return {
+		thumb: thumbRel,
+		width: meta.width ?? 0,
+		height: meta.height ?? 0,
+	};
+}
+
+// ---------- 外链 URL 收集（§4.107） ----------
+
+/** 复刻 utils.ts seedHash（Java String.hashCode 同款），保证与渲染期键一致 */
+function seedHash(str) {
+	let h = 0;
+	for (let i = 0; i < str.length; i++)
+		h = ((h << 5) - h + str.charCodeAt(i)) | 0;
+	return Math.abs(h);
+}
+
+/** 复刻 utils.ts randomCoverUrl：{slug} 替换 + ?v=<hash>（有 query 用 &） */
+function randomCoverUrl(template, slug) {
+	const withSlug = template.includes("{slug}")
+		? template.replaceAll("{slug}", slug)
+		: template;
+	return `${withSlug}${withSlug.includes("?") ? "&" : "?"}v=${seedHash(slug)}`;
+}
+
+/** 从 site/src/config/*.ts 正则提取首个 randomCover.apis 模板（提取不到返回 null） */
+function getApiTemplate() {
+	const configDir = path.join(srcDir, "config");
+	if (!fs.existsSync(configDir)) return null;
+	for (const name of fs.readdirSync(configDir).sort()) {
+		if (!/\.(m|c)?(ts|js)$/.test(name)) continue;
+		const text = fs.readFileSync(path.join(configDir, name), "utf8");
+		const apis = text.match(/apis:\s*\[([^\]]*)\]/);
+		if (apis) {
+			const url = apis[1].match(/["']([^"']+)["']/);
+			if (url) return url[1];
+		}
+	}
+	return null;
+}
+
+/** 正文首个外链图 URL：跳过 ```/~~~ 围栏代码块，md 图片语法或 <img> 均可 */
+function extractFirstImage(body) {
+	let inFence = false;
+	for (const line of body.split("\n")) {
+		if (/^\s*(```|~~~)/.test(line)) {
+			inFence = !inFence;
+			continue;
+		}
+		if (inFence) continue;
+		let m = line.match(/!\[[^\]]*\]\(\s*(https?:\/\/[^)\s]+)/);
+		if (m) return m[1];
+		m = line.match(/<img[^>]*\ssrc=["'](https?:\/\/[^"']+)["']/i);
+		if (m) return m[1];
+	}
+	return null;
+}
+
+/** 收集外链图片 URL：文章 frontmatter image（含 api 确定性解析）+ 正文首图 + 相册 urls.txt */
+function collectRemoteUrls() {
+	const urls = new Set();
+	const apiTemplate = getApiTemplate();
+	const postsDir = path.join(srcDir, "content", "posts");
+	if (fs.existsSync(postsDir)) {
+		const walkMd = (dir) => {
+			const out = [];
+			for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+				if (entry.isDirectory()) out.push(...walkMd(path.join(dir, entry.name)));
+				else if (/\.(md|mdx)$/i.test(entry.name)) out.push(path.join(dir, entry.name));
+			}
+			return out;
+		};
+		for (const file of walkMd(postsDir)) {
+			const text = fs.readFileSync(file, "utf8");
+			const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+			let image;
+			if (fm) {
+				const im = fm[1].match(/^image:\s*["']?([^"'\n]+?)["']?\s*$/m);
+				if (im) image = im[1].trim();
+			}
+			if (image && image !== "api" && /^https?:\/\//.test(image)) {
+				urls.add(image);
+			} else if (image === "api" && apiTemplate) {
+				const slug = path.basename(file).replace(/\.(md|mdx)$/i, "");
+				urls.add(randomCoverUrl(apiTemplate, slug));
+			}
+			// 正文首图（无封面文章它是列表封面；有封面文章供正文增强查表）
+			const body = fm ? text.slice(fm[0].length) : text;
+			const first = extractFirstImage(body);
+			if (first) urls.add(first);
+		}
+	}
+	const galleryDir = path.join(publicDir, "gallery");
+	if (fs.existsSync(galleryDir)) {
+		for (const entry of fs.readdirSync(galleryDir, { withFileTypes: true })) {
+			if (!entry.isDirectory()) continue;
+			const urlsFile = path.join(galleryDir, entry.name, "urls.txt");
+			if (!fs.existsSync(urlsFile)) continue;
+			for (const line of fs.readFileSync(urlsFile, "utf-8").split("\n")) {
+				const u = line.trim();
+				if (u && !u.startsWith("#") && /^https?:\/\//.test(u)) urls.add(u);
+			}
+		}
+	}
+	return [...urls];
+}
+
+/** fetch 外链图 → sharp 采样（超时/非 2xx 抛错由调用方跳过） */
+async function fetchSample(url) {
+	const res = await fetch(url, {
+		signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+		headers: { "user-agent": "orchid-theme-lqip/1.0" },
+	});
+	if (!res.ok) throw new Error(`HTTP ${res.status}`);
+	return sampleColors(Buffer.from(await res.arrayBuffer()));
+}
+
+/** 固定并发的小任务池（保持顺序写 out） */
+async function mapPool(items, limit, fn) {
+	const out = new Array(items.length);
+	let i = 0;
+	async function worker() {
+		while (i < items.length) {
+			const idx = i++;
+			try {
+				out[idx] = await fn(items[idx]);
+			} catch (err) {
+				console.warn(`[lqip] 外链抓取失败，跳过: ${items[idx]} — ${err.message}`);
+			}
+		}
+	}
+	await Promise.all(
+		Array.from({ length: Math.min(limit, items.length) }, () => worker()),
+	);
+	return out;
+}
+
 try {
+	// public 图片：LQIP + 缩略图（照旧重算，public 内容变了要跟上）
 	const files = collectImages(publicDir);
-	const entries = await Promise.all(
-		files.map(async (rel) => [
+	const lqipEntries = [];
+	const thumbEntries = [];
+	for (const rel of files) {
+		lqipEntries.push([
 			`public:${rel}`,
 			await sampleColors(path.join(publicDir, rel)),
-		]),
+		]);
+		thumbEntries.push([`public:${rel}`, await makeThumb(rel)]);
+	}
+
+	// 外链：lqips.json 已有 url: 键即缓存，只抓缺失项
+	let cached = {};
+	if (!REFRESH) {
+		try {
+			cached = Object.fromEntries(
+				Object.entries(JSON.parse(fs.readFileSync(lqipFile, "utf8"))).filter(
+					([k, v]) => k.startsWith("url:") && /^[0-9a-f]{18}$/i.test(v),
+				),
+			);
+		} catch {
+			cached = {};
+		}
+	}
+	const remoteUrls = collectRemoteUrls();
+	const pending = remoteUrls.filter((u) => !(`url:${u}` in cached));
+	console.log(
+		`[lqip] 外链 ${remoteUrls.length} 条（缓存命中 ${remoteUrls.length - pending.length}，待抓 ${pending.length}）`,
 	);
+	const fetched = await mapPool(pending, FETCH_CONCURRENCY, async (url) => [
+		url,
+		await fetchSample(url),
+	]);
+	// 缓存命中的 url: 键原样合并（否则第二次运行会把它从产物中丢掉）
+	for (const [k, v] of Object.entries(cached)) lqipEntries.push([k, v]);
+	for (const pair of fetched) {
+		if (pair) lqipEntries.push([`url:${pair[0]}`, pair[1]]);
+	}
+
 	fs.writeFileSync(
-		outFile,
-		JSON.stringify(Object.fromEntries(entries), null, 2) + "\n",
+		lqipFile,
+		JSON.stringify(Object.fromEntries(lqipEntries), null, 2) + "\n",
+	);
+	fs.writeFileSync(
+		thumbsFile,
+		JSON.stringify(Object.fromEntries(thumbEntries), null, 2) + "\n",
+	);
+	console.log(
+		`[lqip] public ${files.length} 张 + 外链 ${remoteUrls.length - pending.length + fetched.filter(Boolean).length} 条 → ${path.relative(cwd, lqipFile)} + ${path.relative(cwd, thumbsFile)}`,
 	);
-	console.log(`[lqip] ${files.length} 张图片 → ${path.relative(cwd, outFile)}`);
 } catch (err) {
 	console.error("[lqip] 生成失败：", err);
 	process.exit(1);