node-pdf2img 0.1.6 → 0.1.8

package/README.md

@@ -157,6 +157,32 @@ const result = await convert('./document.pdf', {
 });
 ```
 
+### pages 参数说明
+
+`pages` 参数控制要转换的页面：
+
+- **空数组 `[]` 或不传**：转换所有页面
+- **指定页码数组**：只转换指定页面（1-based）
+
+```javascript
+// 转换所有页面（推荐）
+await convert('./document.pdf', { pages: [] });
+
+// 只转换第 1、3、5 页
+await convert('./document.pdf', { pages: [1, 3, 5] });
+```
+
+> **最佳实践**：如果需要转换所有页面，直接使用 `convert()` 并传空 `pages` 数组，**不要**先调用 `getPageCount()` 获取页数再传入。这样可以避免 URL 输入时重复下载 PDF 文件。
+>
+> ```javascript
+> // ❌ 不推荐：URL 会被下载两次
+> const pageCount = await getPageCount(url);
+> const result = await convert(url, { pages: Array.from({length: pageCount}, (_, i) => i + 1) });
+>
+> // ✅ 推荐：直接转换所有页面
+> const result = await convert(url, { pages: [] });
+> ```
+
 ### 自定义渲染宽度
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-pdf2img",
-    "version": "0.1.6",
+    "version": "0.1.8",
     "description": "High-performance PDF to image converter using PDFium native renderer",
     "type": "module",
     "main": "./src/index.js",
@@ -55,7 +55,7 @@
         "p-limit": "^7.2.0",
         "piscina": "^5.1.4",
         "sharp": "^0.33.0",
-        "node-pdf2img-native": "^1.1.7"
+        "node-pdf2img-native": "^1.1.9"
     },
     "devDependencies": {
         "@types/node": "^20.0.0"

package/src/core/converter.js

@@ -15,63 +15,16 @@
  */
 
 import fs from 'fs';
-import path from 'path';
-import os from 'os';
-import { pipeline } from 'stream/promises';
-import { fileURLToPath } from 'url';
-import pLimit from 'p-limit';
-import Piscina from 'piscina';
 import { createLogger } from '../utils/logger.js';
-import { RENDER_CONFIG, TIMEOUT_CONFIG, SUPPORTED_FORMATS, getExtension, getMimeType } from './config.js';
+import { RENDER_CONFIG, SUPPORTED_FORMATS } from './config.js';
 import * as nativeRenderer from '../renderers/native.js';
+import { getThreadCount, getThreadPoolStats, destroyThreadPool } from './thread-pool.js';
+import { downloadToTempFile } from './downloader.js';
+import { saveToFiles, uploadToCos, DEFAULT_CONCURRENCY } from './output-handler.js';
+import { InputType, detectInputType, renderPages } from './renderer.js';
 
 const logger = createLogger('Converter');
 
-// ==================== 线程池初始化 ====================
-
-// 获取 worker.js 的路径
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const workerPath = path.resolve(__dirname, '../worker.js');
-
-// 创建全局线程池实例
-// 线程数默认为 CPU 核心数，可通过环境变量调整
-const threadCount = parseInt(process.env.PDF2IMG_THREAD_COUNT, 10) || os.cpus().length;
-
-let piscina = null;
-
-/**
- * 获取或创建线程池实例（懒加载）
- */
-function getThreadPool() {
-    if (!piscina) {
-        piscina = new Piscina({
-            filename: workerPath,
-            maxThreads: threadCount,
-            idleTimeout: 30000, // 空闲 30 秒后销毁线程
-        });
-        logger.info(`Thread pool initialized with ${threadCount} workers`);
-    }
-    return piscina;
-}
-
-/**
- * 默认并发限制
- */
-const DEFAULT_CONCURRENCY = {
-    FILE_IO: 10,      // 文件写入并发数
-    COS_UPLOAD: 8,    // COS 上传并发数
-};
-
-/**
- * 输入类型枚举
- */
-export const InputType = {
-    FILE: 'file',
-    URL: 'url',
-    BUFFER: 'buffer',
-};
-
 /**
  * 输出类型枚举
  */
@@ -81,279 +34,8 @@ export const OutputType = {
     COS: 'cos',        // 上传到腾讯云 COS
 };
 
-/**
- * 检测输入类型
- */
-function detectInputType(input) {
-    if (Buffer.isBuffer(input)) {
-        return InputType.BUFFER;
-    }
-    if (typeof input === 'string') {
-        if (input.startsWith('http://') || input.startsWith('https://')) {
-            return InputType.URL;
-        }
-        return InputType.FILE;
-    }
-    throw new Error('Invalid input: must be a file path, URL, or Buffer');
-}
-
-/**
- * 从 URL 获取文件大小
- */
-async function getRemoteFileSize(url) {
-    const response = await fetch(url, {
-        method: 'HEAD',
-        signal: AbortSignal.timeout(TIMEOUT_CONFIG.DOWNLOAD_TIMEOUT),
-    });
-
-    if (!response.ok) {
-        throw new Error(`Failed to get file size: ${response.status} ${response.statusText}`);
-    }
-
-    const contentLength = response.headers.get('content-length');
-    if (!contentLength) {
-        throw new Error('Server did not return Content-Length header');
-    }
-
-    return parseInt(contentLength, 10);
-}
-
-/**
- * 流式下载远程文件到临时文件
- */
-async function downloadToTempFile(url) {
-    const response = await fetch(url, {
-        signal: AbortSignal.timeout(TIMEOUT_CONFIG.DOWNLOAD_TIMEOUT),
-    });
-
-    if (!response.ok) {
-        throw new Error(`Failed to download file: ${response.status} ${response.statusText}`);
-    }
-
-    const tempDir = os.tmpdir();
-    const tempFile = path.join(tempDir, `pdf2img_${Date.now()}_${Math.random().toString(36).slice(2)}.pdf`);
-    
-    const fileStream = fs.createWriteStream(tempFile);
-    
-    try {
-        await pipeline(response.body, fileStream);
-        return tempFile;
-    } catch (err) {
-        try {
-            await fs.promises.unlink(tempFile);
-        } catch {}
-        throw err;
-    }
-}
-
-/**
- * 保存单个页面到文件
- */
-async function savePageToFile(page, outputDir, prefix, ext) {
-    if (!page.success || !page.buffer) {
-        return { ...page, outputPath: null };
-    }
-
-    try {
-        const filename = `${prefix}_${page.pageNum}.${ext}`;
-        const outputPath = path.join(outputDir, filename);
-        await fs.promises.writeFile(outputPath, page.buffer);
-
-        return {
-            pageNum: page.pageNum,
-            width: page.width,
-            height: page.height,
-            success: true,
-            outputPath,
-            size: page.buffer.length,
-        };
-    } catch (err) {
-        return {
-            pageNum: page.pageNum,
-            width: page.width,
-            height: page.height,
-            success: false,
-            error: `File save failed: ${err.message}`,
-            outputPath: null,
-        };
-    }
-}
-
-/**
- * 保存渲染结果到文件
- */
-async function saveToFiles(pages, outputDir, prefix = 'page', format = 'webp', concurrency = DEFAULT_CONCURRENCY.FILE_IO) {
-    await fs.promises.mkdir(outputDir, { recursive: true });
-
-    const ext = getExtension(format);
-    const limit = pLimit(concurrency);
-
-    const results = await Promise.all(
-        pages.map(page => limit(() => savePageToFile(page, outputDir, prefix, ext)))
-    );
-
-    return results.sort((a, b) => a.pageNum - b.pageNum);
-}
-
-/**
- * 上传单个页面到 COS
- */
-async function uploadPageToCos(page, cos, cosConfig, keyPrefix, ext, mimeType) {
-    if (!page.success || !page.buffer) {
-        return { ...page, cosKey: null };
-    }
-
-    try {
-        const key = `${keyPrefix}/page_${page.pageNum}.${ext}`;
-
-        await new Promise((resolve, reject) => {
-            cos.putObject({
-                Bucket: cosConfig.bucket,
-                Region: cosConfig.region,
-                Key: key,
-                Body: page.buffer,
-                ContentType: mimeType,
-            }, (err) => {
-                if (err) reject(err);
-                else resolve();
-            });
-        });
-
-        return {
-            pageNum: page.pageNum,
-            width: page.width,
-            height: page.height,
-            success: true,
-            cosKey: key,
-            size: page.buffer.length,
-        };
-    } catch (err) {
-        return {
-            pageNum: page.pageNum,
-            width: page.width,
-            height: page.height,
-            success: false,
-            error: `Upload failed: ${err.message}`,
-            cosKey: null,
-        };
-    }
-}
-
-/**
- * 上传渲染结果到 COS
- */
-async function uploadToCos(pages, cosConfig, keyPrefix, format = 'webp', concurrency = DEFAULT_CONCURRENCY.COS_UPLOAD) {
-    const COS = (await import('cos-nodejs-sdk-v5')).default;
-
-    const cos = new COS({
-        SecretId: cosConfig.secretId,
-        SecretKey: cosConfig.secretKey,
-    });
-
-    const ext = getExtension(format);
-    const mimeType = getMimeType(format);
-    const limit = pLimit(concurrency);
-
-    const results = await Promise.all(
-        pages.map(page => limit(() => uploadPageToCos(page, cos, cosConfig, keyPrefix, ext, mimeType)))
-    );
-
-    return results.sort((a, b) => a.pageNum - b.pageNum);
-}
-
-/**
- * 使用线程池渲染 PDF 页面
- * 
- * 主线程负责协调，工作线程负责 CPU 密集型任务
- * 
- * @param {string|Buffer} input - 输入
- * @param {string} inputType - 输入类型
- * @param {number[]} pages - 页码数组
- * @param {Object} options - 选项
- * @returns {Promise<Object>} 渲染结果
- */
-async function renderPages(input, inputType, pages, options) {
-    const startTime = Date.now();
-    let filePath = null;
-    let pdfBuffer = null;
-    let tempFile = null;
-    let numPages;
-
-    // 准备输入
-    if (inputType === InputType.FILE) {
-        try {
-            await fs.promises.access(input, fs.constants.R_OK);
-        } catch {
-            throw new Error(`File not found or not readable: ${input}`);
-        }
-        filePath = input;
-        numPages = nativeRenderer.getPageCountFromFile(filePath);
-    } else if (inputType === InputType.BUFFER) {
-        pdfBuffer = Buffer.isBuffer(input) ? input : Buffer.from(input);
-        numPages = nativeRenderer.getPageCount(pdfBuffer);
-    } else if (inputType === InputType.URL) {
-        const fileSize = await getRemoteFileSize(input);
-        logger.debug(`Remote file size: ${(fileSize / 1024 / 1024).toFixed(2)}MB, downloading...`);
-        tempFile = await downloadToTempFile(input);
-        filePath = tempFile;
-        numPages = nativeRenderer.getPageCountFromFile(filePath);
-    }
-
-    // 确定目标页码
-    let targetPages;
-    if (pages.length === 0) {
-        targetPages = Array.from({ length: numPages }, (_, i) => i + 1);
-    } else {
-        targetPages = pages.filter(p => p >= 1 && p <= numPages);
-    }
-
-    logger.debug(`Rendering ${targetPages.length} pages using thread pool (${threadCount} workers)`);
-
-    // 获取线程池
-    const pool = getThreadPool();
-
-    try {
-        // 为每一页创建任务并提交到线程池
-        const tasks = targetPages.map(pageNum => {
-            const task = {
-                pageNum,
-                options,
-            };
-            
-            if (filePath) {
-                task.filePath = filePath;
-            } else if (pdfBuffer) {
-                // 注意：Buffer 会被序列化传递给工作线程
-                // 对于大文件，建议先保存到临时文件再传递路径
-                task.pdfBuffer = pdfBuffer;
-            }
-            
-            // 提交任务到线程池
-            return pool.run(task);
-        });
-
-        // 等待所有页面的并行处理完成
-        const results = await Promise.all(tasks);
-
-        results.sort((a, b) => a.pageNum - b.pageNum);
-
-        return {
-            success: true,
-            numPages,
-            pages: results,
-            totalTime: Date.now() - startTime,
-            renderTime: results.reduce((sum, p) => sum + (p.renderTime || 0), 0),
-            encodeTime: results.reduce((sum, p) => sum + (p.encodeTime || 0), 0),
-        };
-    } finally {
-        // 清理临时文件
-        if (tempFile) {
-            try {
-                await fs.promises.unlink(tempFile);
-            } catch {}
-        }
-    }
-}
+// 重新导出 InputType
+export { InputType };
 
 /**
  * PDF 转图片
@@ -497,6 +179,8 @@ export async function convert(input, options = {}) {
         outputResult = normalizedPages.sort((a, b) => a.pageNum - b.pageNum);
     }
 
+    const threadCount = getThreadCount();
+
     return {
         success: true,
         numPages: result.numPages,
@@ -511,13 +195,15 @@ export async function convert(input, options = {}) {
         threadPool: {
             workers: threadCount,
         },
+        // 流式渲染统计（仅 URL 输入时存在）
+        ...(result.streamStats && { streamStats: result.streamStats }),
     };
 }
 
 /**
  * 获取 PDF 页数（异步版本）
  *
- * @param {string|Buffer} input - PDF 输入（文件路径或 Buffer）
+ * @param {string|Buffer} input - PDF 输入（文件路径、URL 或 Buffer）
  * @returns {Promise<number>} 页数
  */
 export async function getPageCount(input) {
@@ -530,6 +216,23 @@ export async function getPageCount(input) {
     }
     
     if (typeof input === 'string') {
+        // 检查是否是 URL
+        if (input.startsWith('http://') || input.startsWith('https://')) {
+            // URL 输入：下载到临时文件后获取页数
+            const tempFile = await downloadToTempFile(input);
+            try {
+                return nativeRenderer.getPageCountFromFile(tempFile);
+            } finally {
+                // 清理临时文件
+                try {
+                    await fs.promises.unlink(tempFile);
+                } catch {
+                    // 忽略清理错误
+                }
+            }
+        }
+        
+        // 本地文件路径
         try {
             await fs.promises.access(input, fs.constants.R_OK);
         } catch {
@@ -538,7 +241,7 @@ export async function getPageCount(input) {
         return nativeRenderer.getPageCountFromFile(input);
     }
     
-    throw new Error('Invalid input: must be a file path or Buffer');
+    throw new Error('Invalid input: must be a file path, URL, or Buffer');
 }
 
 /**
@@ -577,35 +280,5 @@ export function getVersion() {
     return nativeRenderer.getVersion();
 }
 
-/**
- * 获取线程池统计信息
- */
-export function getThreadPoolStats() {
-    if (!piscina) {
-        return {
-            initialized: false,
-            workers: threadCount,
-        };
-    }
-    return {
-        initialized: true,
-        workers: threadCount,
-        completed: piscina.completed,
-        waitTime: piscina.waitTime,
-        runTime: piscina.runTime,
-        utilization: piscina.utilization,
-    };
-}
-
-/**
- * 销毁线程池
- * 
- * 在应用关闭时调用，释放工作线程资源
- */
-export async function destroyThreadPool() {
-    if (piscina) {
-        await piscina.destroy();
-        piscina = null;
-        logger.info('Thread pool destroyed');
-    }
-}
+// 重新导出线程池相关函数
+export { getThreadPoolStats, destroyThreadPool };

package/src/core/downloader.js

@@ -0,0 +1,98 @@
+/**
+ * 远程文件下载模块
+ * 
+ * 提供流式下载和文件大小获取功能
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { pipeline } from 'stream/promises';
+import { createLogger } from '../utils/logger.js';
+import { TIMEOUT_CONFIG } from './config.js';
+
+const logger = createLogger('Downloader');
+
+/**
+ * 延迟函数
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * 从 URL 获取文件大小
+ * 
+ * @param {string} url - 远程文件 URL
+ * @returns {Promise<number>} 文件大小（字节）
+ */
+export async function getRemoteFileSize(url) {
+    const response = await fetch(url, {
+        method: 'HEAD',
+        signal: AbortSignal.timeout(TIMEOUT_CONFIG.DOWNLOAD_TIMEOUT),
+    });
+
+    if (!response.ok) {
+        throw new Error(`Failed to get file size: ${response.status} ${response.statusText}`);
+    }
+
+    const contentLength = response.headers.get('content-length');
+    if (!contentLength) {
+        throw new Error('Server did not return Content-Length header');
+    }
+
+    return parseInt(contentLength, 10);
+}
+
+/**
+ * 流式下载远程文件到临时文件（带重试）
+ * 
+ * @param {string} url - 远程文件 URL
+ * @param {number} maxRetries - 最大重试次数
+ * @returns {Promise<string>} 临时文件路径
+ */
+export async function downloadToTempFile(url, maxRetries = 3) {
+    let lastError;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        const tempFile = path.join(os.tmpdir(), `pdf2img_${Date.now()}_${Math.random().toString(36).slice(2)}.pdf`);
+        
+        try {
+            const response = await fetch(url, {
+                signal: AbortSignal.timeout(TIMEOUT_CONFIG.DOWNLOAD_TIMEOUT),
+            });
+
+            if (!response.ok) {
+                throw new Error(`Failed to download file: ${response.status} ${response.statusText}`);
+            }
+
+            const fileStream = fs.createWriteStream(tempFile);
+            await pipeline(response.body, fileStream);
+            return tempFile;
+        } catch (err) {
+            lastError = err;
+            
+            // 清理临时文件
+            try {
+                await fs.promises.unlink(tempFile);
+            } catch {}
+
+            const isRetryable = err.code === 'EPIPE' || 
+                               err.code === 'ECONNRESET' || 
+                               err.code === 'ETIMEDOUT' ||
+                               err.code === 'ECONNREFUSED' ||
+                               err.code === 'UND_ERR_SOCKET' ||
+                               err.name === 'AbortError';
+            
+            if (isRetryable && attempt < maxRetries) {
+                const delay = Math.pow(2, attempt - 1) * 1000;
+                logger.debug(`Download failed (${err.code || err.message}), retrying in ${delay}ms (attempt ${attempt}/${maxRetries})`);
+                await sleep(delay);
+            } else if (!isRetryable) {
+                break;
+            }
+        }
+    }
+
+    throw new Error(`Download failed after ${maxRetries} attempts: ${lastError.message}`);
+}

package/src/core/output-handler.js

@@ -0,0 +1,176 @@
+/**
+ * 输出处理模块
+ * 
+ * 负责将渲染结果保存到文件或上传到 COS
+ */
+
+import fs from 'fs';
+import path from 'path';
+import pLimit from 'p-limit';
+import { createLogger } from '../utils/logger.js';
+import { getExtension, getMimeType } from './config.js';
+
+const logger = createLogger('OutputHandler');
+
+/**
+ * 默认并发限制
+ */
+export const DEFAULT_CONCURRENCY = {
+    FILE_IO: 10,      // 文件写入并发数
+    COS_UPLOAD: 4,    // COS 上传并发数（降低以减少 EPIPE 错误）
+};
+
+/**
+ * 延迟函数
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * 保存单个页面到文件
+ */
+async function savePageToFile(page, outputDir, prefix, ext) {
+    if (!page.success || !page.buffer) {
+        return { ...page, outputPath: null };
+    }
+
+    try {
+        const filename = `${prefix}_${page.pageNum}.${ext}`;
+        const outputPath = path.join(outputDir, filename);
+        await fs.promises.writeFile(outputPath, page.buffer);
+
+        return {
+            pageNum: page.pageNum,
+            width: page.width,
+            height: page.height,
+            success: true,
+            outputPath,
+            size: page.buffer.length,
+        };
+    } catch (err) {
+        return {
+            pageNum: page.pageNum,
+            width: page.width,
+            height: page.height,
+            success: false,
+            error: `File save failed: ${err.message}`,
+            outputPath: null,
+        };
+    }
+}
+
+/**
+ * 保存渲染结果到文件
+ * 
+ * @param {Array} pages - 渲染结果数组
+ * @param {string} outputDir - 输出目录
+ * @param {string} prefix - 文件名前缀
+ * @param {string} format - 输出格式
+ * @param {number} concurrency - 并发数
+ * @returns {Promise<Array>} 保存结果
+ */
+export async function saveToFiles(pages, outputDir, prefix = 'page', format = 'webp', concurrency = DEFAULT_CONCURRENCY.FILE_IO) {
+    await fs.promises.mkdir(outputDir, { recursive: true });
+
+    const ext = getExtension(format);
+    const limit = pLimit(concurrency);
+
+    const results = await Promise.all(
+        pages.map(page => limit(() => savePageToFile(page, outputDir, prefix, ext)))
+    );
+
+    return results.sort((a, b) => a.pageNum - b.pageNum);
+}
+
+/**
+ * 上传单个页面到 COS（带重试）
+ */
+async function uploadPageToCos(page, cos, cosConfig, keyPrefix, ext, mimeType, maxRetries = 3) {
+    if (!page.success || !page.buffer) {
+        return { ...page, cosKey: null };
+    }
+
+    const key = `${keyPrefix}/page_${page.pageNum}.${ext}`;
+    let lastError;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            await new Promise((resolve, reject) => {
+                cos.putObject({
+                    Bucket: cosConfig.bucket,
+                    Region: cosConfig.region,
+                    Key: key,
+                    Body: page.buffer,
+                    ContentType: mimeType,
+                }, (err) => {
+                    if (err) reject(err);
+                    else resolve();
+                });
+            });
+
+            return {
+                pageNum: page.pageNum,
+                width: page.width,
+                height: page.height,
+                success: true,
+                cosKey: key,
+                size: page.buffer.length,
+            };
+        } catch (err) {
+            lastError = err;
+            const isRetryable = err.code === 'EPIPE' || 
+                               err.code === 'ECONNRESET' || 
+                               err.code === 'ETIMEDOUT' ||
+                               err.code === 'ECONNREFUSED' ||
+                               (err.statusCode && err.statusCode >= 500);
+            
+            if (isRetryable && attempt < maxRetries) {
+                // 指数退避：1s, 2s, 4s...
+                const delay = Math.pow(2, attempt - 1) * 1000;
+                logger.debug(`Page ${page.pageNum} upload failed (${err.code || err.message}), retrying in ${delay}ms (attempt ${attempt}/${maxRetries})`);
+                await sleep(delay);
+            } else if (!isRetryable) {
+                break;
+            }
+        }
+    }
+
+    return {
+        pageNum: page.pageNum,
+        width: page.width,
+        height: page.height,
+        success: false,
+        error: `Upload failed after ${maxRetries} attempts: ${lastError.message}`,
+        cosKey: null,
+    };
+}
+
+/**
+ * 上传渲染结果到 COS
+ * 
+ * @param {Array} pages - 渲染结果数组
+ * @param {Object} cosConfig - COS 配置
+ * @param {string} keyPrefix - COS key 前缀
+ * @param {string} format - 输出格式
+ * @param {number} concurrency - 并发数
+ * @returns {Promise<Array>} 上传结果
+ */
+export async function uploadToCos(pages, cosConfig, keyPrefix, format = 'webp', concurrency = DEFAULT_CONCURRENCY.COS_UPLOAD) {
+    const COS = (await import('cos-nodejs-sdk-v5')).default;
+
+    const cos = new COS({
+        SecretId: cosConfig.secretId,
+        SecretKey: cosConfig.secretKey,
+    });
+
+    const ext = getExtension(format);
+    const mimeType = getMimeType(format);
+    const limit = pLimit(concurrency);
+
+    const results = await Promise.all(
+        pages.map(page => limit(() => uploadPageToCos(page, cos, cosConfig, keyPrefix, ext, mimeType)))
+    );
+
+    return results.sort((a, b) => a.pageNum - b.pageNum);
+}

package/src/core/renderer.js

@@ -0,0 +1,224 @@
+/**
+ * PDF 渲染模块
+ * 
+ * 负责 PDF 页面的渲染逻辑，支持本地文件、Buffer 和 URL 输入
+ */
+
+import fs from 'fs';
+import { createLogger } from '../utils/logger.js';
+import * as nativeRenderer from '../renderers/native.js';
+import { getThreadPool, getThreadCount } from './thread-pool.js';
+import { getRemoteFileSize, downloadToTempFile } from './downloader.js';
+
+const logger = createLogger('Renderer');
+
+/**
+ * 输入类型枚举
+ */
+export const InputType = {
+    FILE: 'file',
+    URL: 'url',
+    BUFFER: 'buffer',
+};
+
+/**
+ * 流式渲染阈值（小于此值使用下载模式）
+ */
+const STREAM_THRESHOLD = 2 * 1024 * 1024; // 2MB
+
+/**
+ * 检测输入类型
+ * 
+ * @param {string|Buffer} input - 输入
+ * @returns {string} 输入类型
+ */
+export function detectInputType(input) {
+    if (Buffer.isBuffer(input)) {
+        return InputType.BUFFER;
+    }
+    if (typeof input === 'string') {
+        if (input.startsWith('http://') || input.startsWith('https://')) {
+            return InputType.URL;
+        }
+        return InputType.FILE;
+    }
+    throw new Error('Invalid input: must be a file path, URL, or Buffer');
+}
+
+/**
+ * 使用线程池渲染 PDF 页面
+ * 
+ * 主线程负责协调，工作线程负责 CPU 密集型任务
+ * 
+ * @param {string|Buffer} input - 输入
+ * @param {string} inputType - 输入类型
+ * @param {number[]} pages - 页码数组
+ * @param {Object} options - 选项
+ * @returns {Promise<Object>} 渲染结果
+ */
+export async function renderPages(input, inputType, pages, options) {
+    const startTime = Date.now();
+
+    // URL 输入：优先使用流式渲染
+    if (inputType === InputType.URL) {
+        return renderPagesFromUrl(input, pages, options, startTime);
+    }
+
+    // 本地文件或 Buffer 输入：使用线程池渲染
+    return renderPagesFromLocal(input, inputType, pages, options, startTime);
+}
+
+/**
+ * 从 URL 渲染 PDF 页面（流式）
+ * 
+ * 使用 HTTP Range 请求按需获取数据，避免完整下载
+ */
+async function renderPagesFromUrl(url, pages, options, startTime) {
+    // 获取文件大小
+    const fileSize = await getRemoteFileSize(url);
+    
+    // 小文件直接下载后渲染，避免多次 Range 请求开销
+    if (fileSize < STREAM_THRESHOLD) {
+        logger.debug(`Remote file size: ${(fileSize / 1024 / 1024).toFixed(2)}MB (< 2MB), using download mode`);
+        return renderPagesWithDownload(url, pages, options, startTime);
+    }
+
+    logger.debug(`Remote file size: ${(fileSize / 1024 / 1024).toFixed(2)}MB, using stream rendering`);
+
+    try {
+        // 使用流式渲染
+        const result = await nativeRenderer.renderFromStream(url, fileSize, pages, options);
+
+        return {
+            success: true,
+            numPages: result.numPages,
+            pages: result.pages,
+            totalTime: Date.now() - startTime,
+            renderTime: result.pages.reduce((sum, p) => sum + (p.renderTime || 0), 0),
+            encodeTime: result.pages.reduce((sum, p) => sum + (p.encodeTime || 0), 0),
+            streamStats: result.streamStats,
+        };
+    } catch (err) {
+        // 流式渲染失败，回退到下载后渲染
+        logger.warn(`Stream rendering failed: ${err.message}, falling back to download`);
+        return renderPagesWithDownload(url, pages, options, startTime);
+    }
+}
+
+/**
+ * 下载后渲染（回退方案）
+ */
+async function renderPagesWithDownload(url, pages, options, startTime) {
+    const tempFile = await downloadToTempFile(url);
+    const threadCount = getThreadCount();
+    
+    try {
+        const numPages = nativeRenderer.getPageCountFromFile(tempFile);
+        
+        // 确定目标页码
+        let targetPages;
+        if (pages.length === 0) {
+            targetPages = Array.from({ length: numPages }, (_, i) => i + 1);
+        } else {
+            targetPages = pages.filter(p => p >= 1 && p <= numPages);
+        }
+
+        logger.debug(`Rendering ${targetPages.length} pages using thread pool (${threadCount} workers)`);
+
+        const pool = getThreadPool();
+        
+        const tasks = targetPages.map(pageNum => {
+            return pool.run({
+                pageNum,
+                options,
+                filePath: tempFile,
+            });
+        });
+
+        const results = await Promise.all(tasks);
+        results.sort((a, b) => a.pageNum - b.pageNum);
+
+        return {
+            success: true,
+            numPages,
+            pages: results,
+            totalTime: Date.now() - startTime,
+            renderTime: results.reduce((sum, p) => sum + (p.renderTime || 0), 0),
+            encodeTime: results.reduce((sum, p) => sum + (p.encodeTime || 0), 0),
+        };
+    } finally {
+        try {
+            await fs.promises.unlink(tempFile);
+        } catch {}
+    }
+}
+
+/**
+ * 从本地文件或 Buffer 渲染 PDF 页面
+ */
+async function renderPagesFromLocal(input, inputType, pages, options, startTime) {
+    let filePath = null;
+    let pdfBuffer = null;
+    let numPages;
+    const threadCount = getThreadCount();
+
+    // 准备输入
+    if (inputType === InputType.FILE) {
+        try {
+            await fs.promises.access(input, fs.constants.R_OK);
+        } catch {
+            throw new Error(`File not found or not readable: ${input}`);
+        }
+        filePath = input;
+        numPages = nativeRenderer.getPageCountFromFile(filePath);
+    } else if (inputType === InputType.BUFFER) {
+        pdfBuffer = Buffer.isBuffer(input) ? input : Buffer.from(input);
+        numPages = nativeRenderer.getPageCount(pdfBuffer);
+    }
+
+    // 确定目标页码
+    let targetPages;
+    if (pages.length === 0) {
+        targetPages = Array.from({ length: numPages }, (_, i) => i + 1);
+    } else {
+        targetPages = pages.filter(p => p >= 1 && p <= numPages);
+    }
+
+    logger.debug(`Rendering ${targetPages.length} pages using thread pool (${threadCount} workers)`);
+
+    // 获取线程池
+    const pool = getThreadPool();
+
+    // 为每一页创建任务并提交到线程池
+    const tasks = targetPages.map(pageNum => {
+        const task = {
+            pageNum,
+            options,
+        };
+        
+        if (filePath) {
+            task.filePath = filePath;
+        } else if (pdfBuffer) {
+            // 注意：Buffer 会被序列化传递给工作线程
+            // 对于大文件，建议先保存到临时文件再传递路径
+            task.pdfBuffer = pdfBuffer;
+        }
+        
+        // 提交任务到线程池
+        return pool.run(task);
+    });
+
+    // 等待所有页面的并行处理完成
+    const results = await Promise.all(tasks);
+
+    results.sort((a, b) => a.pageNum - b.pageNum);
+
+    return {
+        success: true,
+        numPages,
+        pages: results,
+        totalTime: Date.now() - startTime,
+        renderTime: results.reduce((sum, p) => sum + (p.renderTime || 0), 0),
+        encodeTime: results.reduce((sum, p) => sum + (p.encodeTime || 0), 0),
+    };
+}

package/src/core/thread-pool.js

@@ -0,0 +1,78 @@
+/**
+ * 线程池管理模块
+ * 
+ * 使用 Piscina 管理工作线程池，用于 CPU 密集型任务
+ */
+
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import Piscina from 'piscina';
+import { createLogger } from '../utils/logger.js';
+
+const logger = createLogger('ThreadPool');
+
+// 获取 worker.js 的路径
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const workerPath = path.resolve(__dirname, '../worker.js');
+
+// 线程数默认为 CPU 核心数，可通过环境变量调整
+const threadCount = parseInt(process.env.PDF2IMG_THREAD_COUNT, 10) || os.cpus().length;
+
+let piscina = null;
+
+/**
+ * 获取或创建线程池实例（懒加载）
+ */
+export function getThreadPool() {
+    if (!piscina) {
+        piscina = new Piscina({
+            filename: workerPath,
+            maxThreads: threadCount,
+            idleTimeout: 30000, // 空闲 30 秒后销毁线程
+        });
+        logger.info(`Thread pool initialized with ${threadCount} workers`);
+    }
+    return piscina;
+}
+
+/**
+ * 获取线程数
+ */
+export function getThreadCount() {
+    return threadCount;
+}
+
+/**
+ * 获取线程池统计信息
+ */
+export function getThreadPoolStats() {
+    if (!piscina) {
+        return {
+            initialized: false,
+            workers: threadCount,
+        };
+    }
+    return {
+        initialized: true,
+        workers: threadCount,
+        completed: piscina.completed,
+        waitTime: piscina.waitTime,
+        runTime: piscina.runTime,
+        utilization: piscina.utilization,
+    };
+}
+
+/**
+ * 销毁线程池
+ * 
+ * 在应用关闭时调用，释放工作线程资源
+ */
+export async function destroyThreadPool() {
+    if (piscina) {
+        await piscina.destroy();
+        piscina = null;
+        logger.info('Thread pool destroyed');
+    }
+}

package/src/index.d.ts

@@ -92,10 +92,10 @@ export function convert(input: string | Buffer, options?: ConvertOptions): Promi
 /**
  * 获取 PDF 页数
  *
- * @param input - PDF 文件路径或 Buffer
+ * @param input - PDF 文件路径、URL 或 Buffer
  * @returns 页数
  */
-export function getPageCount(input: string | Buffer): number;
+export function getPageCount(input: string | Buffer): Promise<number>;
 
 /**
  * 检查原生渲染器是否可用