@ubean/seo 0.1.13 → 0.2.0

package/dist/og-image.js

@@ -0,0 +1,444 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "pathe";
+//#region src/og-image.ts
+/**
+* P9-06 OG Image 动态生成
+*
+* 对齐 Next.js `ImageResponse`(基于 Satori + resvg)和 SvelteKit `@vercel/og`。
+*
+* 设计要点:
+* - **零硬依赖**:`satori` 和 `@resvg/resvg-js` 作为 optional peer 依赖,
+*   运行时通过动态 `import()` 加载。未安装时抛出明确的引导错误。
+* - **API 对齐 Next.js**:`ImageResponse` 类接收 Satori 兼容的 React-like
+*   元素树(此处用泛型 `unknown` 表示,因为 Satori 自身接受任意 VDOM),
+*   返回 PNG `Response`。
+* - **内置模板**:`renderOgImage(options)` 提供开箱即用的 OG 图模板,
+*   覆盖 80% 用例(博客/文章/产品页),无需手写 JSX。
+* - **字体加载**:提供 `loadDefaultFont()` 从内置 fetch 加载默认字体;
+*   `loadFontFromFile()`/`loadFontFromUrl()` 辅助自定义字体加载。
+*
+* 对齐:Next.js `ImageResponse` / `@vercel/og` / Astro `astro-og-image`。
+*/
+const DEFAULT_WIDTH = 1200;
+const DEFAULT_HEIGHT = 630;
+const DEFAULT_CACHE_CONTROL = "public, max-age=86400";
+/**
+* 默认字体 URL(使用 Google Fonts 的 Inter 字体,常规字重 400)。
+*
+* 在生产环境建议使用 `loadFontFromFile()` 加载本地字体,避免运行时网络依赖。
+*/
+const DEFAULT_FONT_URL = "https://fonts.gstatic.com/s/inter/v12/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMa1ZL7.woff2";
+/**
+* 默认字体名。
+*/
+const DEFAULT_FONT_NAME = "Inter";
+/**
+* 从 URL 加载字体(返回 Satori 兼容的 `SatoriFont`)。
+*
+* @example
+* ```ts
+* const font = await loadFontFromUrl('https://fonts.gstatic.com/.../inter.woff2', 'Inter');
+* ```
+*/
+async function loadFontFromUrl(url, name, weight = 400, fontStyle = "normal") {
+	const res = await fetch(url);
+	if (!res.ok) throw new Error(`Failed to load font from ${url}: ${res.status} ${res.statusText}`);
+	return {
+		name,
+		data: await res.arrayBuffer(),
+		weight,
+		style: fontStyle
+	};
+}
+/**
+* 从本地文件加载字体。
+*
+* @example
+* ```ts
+* const font = loadFontFromFile('./fonts/inter-regular.woff2', 'Inter');
+* ```
+*/
+function loadFontFromFile(path, name, weight = 400, fontStyle = "normal") {
+	const absPath = isAbsolute(path) ? path : resolve(process.cwd(), path);
+	return {
+		name,
+		data: readFileSync(absPath),
+		weight,
+		style: fontStyle
+	};
+}
+/**
+* 加载默认字体(Inter Regular,从 Google Fonts CDN 拉取)。
+*
+* 注意:此函数依赖网络访问。Cloudflare Workers 等边缘环境需要 fetch API 可用。
+* 离线/生产环境推荐用 `loadFontFromFile()` 替代。
+*/
+function loadDefaultFont() {
+	return loadFontFromUrl(DEFAULT_FONT_URL, DEFAULT_FONT_NAME, 400);
+}
+/**
+* 默认 OG 图模板:渐变背景 + 居中标题 + 副标题 + 底部站点名。
+*
+* 返回 Satori 兼容的 VDOM 树。
+*/
+function defaultTemplate(input) {
+	const themeColor = input.themeColor || "#0f172a";
+	const textColor = input.textColor || "#ffffff";
+	const children = [];
+	const contentChildren = [{
+		type: "div",
+		props: {
+			style: {
+				fontSize: input.title.length > 60 ? "52px" : "72px",
+				fontWeight: 700,
+				lineHeight: 1.2,
+				textAlign: "center",
+				color: textColor,
+				maxWidth: "1000px"
+			},
+			children: input.title
+		}
+	}];
+	if (input.description) contentChildren.push({
+		type: "div",
+		props: {
+			style: {
+				fontSize: "32px",
+				marginTop: "24px",
+				color: textColor,
+				opacity: .8,
+				textAlign: "center",
+				maxWidth: "900px",
+				lineHeight: 1.4
+			},
+			children: input.description
+		}
+	});
+	children.push({
+		type: "div",
+		props: {
+			style: {
+				display: "flex",
+				flexDirection: "column",
+				alignItems: "center",
+				justifyContent: "center",
+				flexGrow: 1,
+				padding: ["0", "80px"]
+			},
+			children: contentChildren
+		}
+	});
+	if (input.siteName) children.push({
+		type: "div",
+		props: {
+			style: {
+				display: "flex",
+				alignItems: "center",
+				padding: [
+					"0",
+					"80px",
+					"60px",
+					"80px"
+				],
+				fontSize: "28px",
+				color: textColor,
+				opacity: .7
+			},
+			children: input.siteName
+		}
+	});
+	if (input.logo) children.unshift({
+		type: "div",
+		props: {
+			style: {
+				display: "flex",
+				alignItems: "center",
+				padding: [
+					"60px",
+					"80px",
+					"0",
+					"80px"
+				],
+				fontSize: "28px",
+				fontWeight: 600,
+				color: textColor
+			},
+			children: input.logo
+		}
+	});
+	return {
+		type: "div",
+		props: {
+			style: {
+				display: "flex",
+				flexDirection: "column",
+				width: "100%",
+				height: "100%",
+				backgroundColor: themeColor,
+				backgroundImage: input.backgroundImage ? `url(${input.backgroundImage})` : `linear-gradient(135deg, ${themeColor} 0%, ${shadeColor(themeColor, -20)} 100%)`,
+				backgroundSize: "cover",
+				backgroundPosition: "center",
+				fontFamily: DEFAULT_FONT_NAME
+			},
+			children
+		}
+	};
+}
+/**
+* 文章模板:左对齐标题 + 日期/作者元信息。
+*/
+function articleTemplate(input) {
+	const themeColor = input.themeColor || "#1e293b";
+	const textColor = input.textColor || "#ffffff";
+	const topSection = input.siteName ? {
+		type: "div",
+		props: {
+			style: {
+				fontSize: "28px",
+				fontWeight: 600,
+				color: textColor,
+				opacity: .7
+			},
+			children: input.siteName
+		}
+	} : null;
+	const middleContent = [{
+		type: "div",
+		props: {
+			style: {
+				fontSize: input.title.length > 80 ? "48px" : "64px",
+				fontWeight: 700,
+				lineHeight: 1.2,
+				color: textColor,
+				maxWidth: "1000px"
+			},
+			children: input.title
+		}
+	}];
+	if (input.description) middleContent.push({
+		type: "div",
+		props: {
+			style: {
+				fontSize: "30px",
+				marginTop: "24px",
+				color: textColor,
+				opacity: .8,
+				maxWidth: "900px",
+				lineHeight: 1.4
+			},
+			children: input.description
+		}
+	});
+	const middleSection = {
+		type: "div",
+		props: {
+			style: {
+				display: "flex",
+				flexDirection: "column",
+				flexGrow: 1,
+				justifyContent: "center"
+			},
+			children: middleContent
+		}
+	};
+	const footerText = [input.author, input.date].filter(Boolean).join(" · ");
+	const allChildren = [
+		topSection,
+		middleSection,
+		{
+			type: "div",
+			props: {
+				style: {
+					display: "flex",
+					alignItems: "center",
+					fontSize: "26px",
+					color: textColor,
+					opacity: .7
+				},
+				children: footerText
+			}
+		}
+	].filter((c) => c !== null);
+	return {
+		type: "div",
+		props: {
+			style: {
+				display: "flex",
+				flexDirection: "column",
+				justifyContent: "space-between",
+				width: "100%",
+				height: "100%",
+				padding: "80px",
+				backgroundColor: themeColor,
+				backgroundImage: `linear-gradient(135deg, ${themeColor} 0%, ${shadeColor(themeColor, -25)} 100%)`,
+				fontFamily: DEFAULT_FONT_NAME
+			},
+			children: allChildren
+		}
+	};
+}
+/**
+* 简单的颜色调亮/调暗工具(用于生成渐变背景)。
+*
+* `percent` 为负数调暗,正数调亮。范围 -100..100。
+*/
+function shadeColor(hex, percent) {
+	const normalized = hex.replace("#", "");
+	if (normalized.length !== 6) return hex;
+	const num = parseInt(normalized, 16);
+	const amt = Math.round(2.55 * percent);
+	const R = Math.max(0, Math.min(255, (num >> 16) + amt));
+	const G = Math.max(0, Math.min(255, (num >> 8 & 255) + amt));
+	const B = Math.max(0, Math.min(255, (num & 255) + amt));
+	return `#${(R << 16 | G << 8 | B).toString(16).padStart(6, "0")}`;
+}
+/**
+* 动态加载 satori。若未安装抛出友好错误。
+*/
+async function loadSatori() {
+	try {
+		const mod = await import("satori");
+		return mod.default || mod;
+	} catch {
+		throw new Error("[ubean/seo] OG image rendering requires `satori` to be installed.\nInstall it with: pnpm add satori @resvg/resvg-js\n(Both are optional peer dependencies of @ubean/seo to keep the base bundle small.)");
+	}
+}
+/**
+* 动态加载 @resvg/resvg-js。若未安装抛出友好错误。
+*/
+async function loadResvg() {
+	try {
+		return await import("@resvg/resvg-js");
+	} catch {
+		throw new Error("[ubean/seo] PNG conversion requires `@resvg/resvg-js` to be installed.\nInstall it with: pnpm add @resvg/resvg-js\n(Optional peer dependency of @ubean/seo.)");
+	}
+}
+/**
+* 把 Satori VDOM 节点渲染为 PNG Buffer(或 SVG 字符串,当 `svgOnly: true` 时)。
+*
+* @returns `{ body, contentType }` —— body 为 Buffer/字符串,contentType 为 MIME 类型
+*/
+async function renderToImage(node, options = {}) {
+	const width = options.width ?? DEFAULT_WIDTH;
+	const height = options.height ?? DEFAULT_HEIGHT;
+	const fonts = options.fonts && options.fonts.length > 0 ? options.fonts : [await loadDefaultFont()];
+	const svg = await (await loadSatori())(node, {
+		width,
+		height,
+		fonts,
+		debug: options.debug ?? false
+	});
+	if (options.svgOnly) return {
+		body: svg,
+		contentType: "image/svg+xml"
+	};
+	const { Resvg } = await loadResvg();
+	const { asPng } = new Resvg(svg, options.resvgOptions).render();
+	return {
+		body: asPng,
+		contentType: "image/png"
+	};
+}
+/**
+* 对齐 Next.js `ImageResponse` 类。接收 Satori VDOM 节点,返回 PNG `Response`。
+*
+* 实现策略:body 使用 `ReadableStream`,在 stream 被 consume 时才执行实际的
+* satori + resvg 渲染。这样构造函数可以保持同步,符合 Next.js
+* `return new ImageResponse(...)` 的用法。
+*
+* @example
+* ```ts
+* // src/routes/og.ts
+* import { ImageResponse, defaultTemplate, loadDefaultFont } from '@ubean/seo/og-image';
+*
+* export const GET = defineHandler(async () => {
+*   const fonts = [await loadDefaultFont()];
+*   const node = defaultTemplate({ title: 'Hello ubean', siteName: 'ubean' });
+*   return new ImageResponse(node, { fonts });
+* });
+* ```
+*
+* 也可用于 `src/opengraph-image.ts` 约定文件:
+* ```ts
+* // src/opengraph-image.ts
+* import { ImageResponse, defaultTemplate, loadDefaultFont } from '@ubean/seo/og-image';
+* export default async function GET() {
+*   const fonts = [await loadDefaultFont()];
+*   return new ImageResponse(defaultTemplate({ title: 'ubean' }), { fonts });
+* }
+* ```
+*/
+var ImageResponse = class extends Response {
+	constructor(node, options = {}) {
+		const cacheControl = options.cacheControl ?? DEFAULT_CACHE_CONTROL;
+		const stream = new ReadableStream({ async start(controller) {
+			try {
+				const { body } = await renderToImage(node, options);
+				if (typeof body === "string") controller.enqueue(new TextEncoder().encode(body));
+				else controller.enqueue(new Uint8Array(body));
+				controller.close();
+			} catch (err) {
+				controller.error(err);
+			}
+		} });
+		super(stream, {
+			status: 200,
+			headers: {
+				"Content-Type": options.svgOnly ? "image/svg+xml" : "image/png",
+				"Cache-Control": cacheControl
+			}
+		});
+	}
+};
+/**
+* 一步到位渲染 OG 图(模板 + 渲染 + Response)。
+*
+* @example
+* ```ts
+* // src/routes/og.ts
+* import { renderOgImage } from '@ubean/seo/og-image';
+* export const GET = defineHandler(async () => {
+*   return renderOgImage({ title: 'Hello world', siteName: 'ubean' });
+* });
+* ```
+*/
+async function renderOgImage(input, options = {}) {
+	const { body, contentType } = await renderToImage(defaultTemplate(input), options);
+	const cacheControl = options.cacheControl ?? DEFAULT_CACHE_CONTROL;
+	return new Response(body, {
+		status: 200,
+		headers: {
+			"Content-Type": contentType,
+			"Cache-Control": cacheControl
+		}
+	});
+}
+/**
+* 用文章模板渲染 OG 图。
+*/
+async function renderArticleOgImage(input, options = {}) {
+	const { body, contentType } = await renderToImage(articleTemplate(input), options);
+	const cacheControl = options.cacheControl ?? DEFAULT_CACHE_CONTROL;
+	return new Response(body, {
+		status: 200,
+		headers: {
+			"Content-Type": contentType,
+			"Cache-Control": cacheControl
+		}
+	});
+}
+/**
+* 检测运行时是否安装了 OG 图渲染所需的依赖。
+* 用于在不实际渲染的情况下判断能力可用性(例如 DevTools 信息展示)。
+*/
+async function isOgImageSupported() {
+	try {
+		await import("satori");
+		await import("@resvg/resvg-js");
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { DEFAULT_FONT_NAME, DEFAULT_FONT_URL, ImageResponse, articleTemplate, defaultTemplate, isOgImageSupported, loadDefaultFont, loadFontFromFile, loadFontFromUrl, renderArticleOgImage, renderOgImage, renderToImage, shadeColor };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ubean/seo",
-  "version": "0.1.13",
-  "description": "SEO utilities for ubean (useSeoMeta, robots, sitemap, manifest)",
+  "version": "0.2.0",
+  "description": "SEO utilities for ubean (useSeoMeta, robots, sitemap, manifest, file conventions, JSON-LD, OG image)",
   "files": [
     "dist"
   ],
@@ -13,27 +13,49 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./conventions": {
+      "types": "./dist/conventions.d.ts",
+      "import": "./dist/conventions.js"
+    },
+    "./og-image": {
+      "types": "./dist/og-image.d.ts",
+      "import": "./dist/og-image.js"
+    },
+    "./json-ld": {
+      "types": "./dist/json-ld.d.ts",
+      "import": "./dist/json-ld.js"
     }
   },
   "dependencies": {
-    "@unhead/vue": "^3.2.3"
+    "@unhead/vue": "^3.3.2",
+    "pathe": "^2.0.3"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "typescript": "7.0.2",
-    "vite-plus": "0.2.6"
+    "vite-plus": "0.2.9"
   },
   "peerDependencies": {
+    "@resvg/resvg-js": "^2.6.0",
+    "satori": "^0.12.0",
     "vue": "^3.0.0"
   },
   "peerDependenciesMeta": {
     "vue": {
       "optional": true
+    },
+    "satori": {
+      "optional": true
+    },
+    "@resvg/resvg-js": {
+      "optional": true
     }
   },
   "scripts": {
     "build": "vp pack",
     "dev": "vp pack --watch",
+    "test": "vp test",
     "typecheck": "tsc --noEmit --skipLibCheck"
   }
 }