# web2pdf

**Repository Path**: luneng17hao/web2pdf

## Basic Information

- **Project Name**: web2pdf
- **Description**: 专为前端工程设计，解决网页转 PDF 时常见的内容截断、分辨率模糊和样式错乱等问题。只需提供 URL，即可自动生成完整、清晰、布局准确的 PDF 文档。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: mian
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-05
- **Last Updated**: 2026-01-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 网页转PDF工具

一个基于 Express + Node.js + TypeScript 的高性能网页转PDF工具，可以将任意网页链接转换为PDF文件，支持Vue/React单页应用，确保内容完整不截断，完美支持中文和Emoji显示。

## ✨ 功能特点

- 🌐 **支持任意网页链接转换** - 支持HTTP/HTTPS协议
- 📄 **完整内容捕获** - 支持懒加载、动态内容，确保内容不截断
- 🇨🇳 **完美中文支持** - 支持中文字体显示，不会出现方块
- 😀 **Emoji支持** - 支持显示各种Emoji表情符号
- ⚛️ **SPA应用支持** - 自动检测并支持Vue、React等单页应用
- 🔍 **可调节放大倍数** - 支持0.5-3.0倍缩放
- 👁️ **浏览器预览** - 生成后可直接在浏览器中预览PDF
- ⚡ **高性能并发** - 支持20个并发请求，浏览器实例池优化
- 🎨 **现代化UI** - 简洁美观的用户界面

## 🛠️ 技术栈

- **后端框架**: Express (Node.js)
- **编程语言**: TypeScript
- **PDF生成引擎**: Playwright (Chromium)
- **前端**: HTML/CSS/JavaScript
- **并发控制**: express-rate-limit

## 📁 项目结构

```
web2pdf/
├── src/
│   ├── index.ts          # Express服务器主文件
│   ├── pdfGenerator.ts   # PDF生成核心逻辑
│   └── browserPool.ts    # 浏览器实例池管理
├── public/
│   └── index.html        # 前端页面
├── dist/                 # TypeScript编译输出
├── pdfs/                 # PDF文件存储目录
├── package.json          # Node.js依赖配置
├── tsconfig.json         # TypeScript配置
└── README.md             # 项目说明文档
```

## 🚀 快速开始

### 安装依赖

```bash
# 安装Node.js依赖
npm install

# 安装Playwright浏览器
npx playwright install chromium
```

### 启动服务

**开发模式（推荐）**

```bash
# 开发模式运行（自动重新编译）
npm run dev
```

**生产模式**

```bash
# 编译TypeScript代码
npm run build

# 启动服务
npm start
```

### 环境变量

可以通过环境变量配置服务：

```bash
# 设置端口（默认5000）
export PORT=5000

# 设置运行环境
export NODE_ENV=production
```

## 🌐 访问应用

启动后，在浏览器中访问：**http://localhost:5000**

## 📖 使用说明

### 基本使用

1. 在输入框中输入要转换的网页URL
2. （可选）设置PDF放大倍数（0.5-3.0，默认1.0）
3. 点击"生成PDF"按钮
4. 等待生成完成后，可以：
   - 点击"预览"在浏览器中查看PDF
   - 点击"下载PDF"保存到本地

### 放大倍数说明

- **0.5 - 0.9**: 缩小显示，适合内容较多的页面
- **1.0**: 原始大小（默认）
- **1.1 - 2.0**: 放大显示，适合需要更清晰的情况
- **2.1 - 3.0**: 大幅放大，适合查看细节

## 🔌 API接口

### POST /generate-pdf

生成PDF文件

**请求体:**
```json
{
  "url": "https://example.com",
  "scale": 1.0
}
```

**参数说明:**
- `url` (必需): 要转换的网页URL
- `scale` (可选): 放大倍数，范围0.5-3.0，默认1.0

**响应:**
```json
{
  "success": true,
  "filename": "uuid.pdf",
  "message": "PDF生成成功"
}
```

**错误响应:**
```json
{
  "error": "错误信息"
}
```

### GET /preview/:filename

在浏览器中预览PDF文件

**示例:**
```
GET /preview/abc123.pdf
```

### GET /download/:filename

下载生成的PDF文件

**示例:**
```
GET /download/abc123.pdf
```

### GET /api/pool-stats

查看浏览器池状态（用于监控）

**响应:**
```json
{
  "available": 3,    // 可用浏览器数
  "inUse": 2,        // 使用中的浏览器数
  "total": 5,        // 总浏览器数
  "max": 5,          // 最大浏览器数
  "queue": 0         // 等待队列长度
}
```

## ⚙️ 系统要求

- **Node.js**: >= 18.0.0
- **npm**: >= 8.0.0
- **内存**: 至少 4GB（推荐 8GB）
- **操作系统**: Linux, macOS, Windows

## 🎯 性能优化

### 浏览器实例池

- 使用浏览器实例池复用机制，避免每次请求都创建新浏览器
- 默认最多5个浏览器实例，可同时处理多个请求
- 每个请求使用独立的Context和Page，确保隔离性

### 并发控制

- 最多支持20个并发请求
- 超出限制的请求会自动排队等待
- 使用express-rate-limit进行流量控制

### 内存优化

- 浏览器实例复用，减少内存占用约50-70%
- 自动清理资源，防止内存泄漏
- 优雅关闭机制，确保资源正确释放

## 🔧 配置说明

### 环境变量

- `NODE_ENV`: 运行环境（production/development）
- `PORT`: 服务端口（默认5000）

### 浏览器池配置

在 `src/browserPool.ts` 中可以调整：

- `maxBrowsers`: 最大浏览器实例数（默认5）

## 🐛 故障排除

### 问题：PDF生成失败，提示"Page crashed"

**解决方案:**
- 检查系统内存是否充足（至少4GB）
- 检查目标网站是否可访问
- 尝试减少并发请求数量

### 问题：中文显示为方块

**解决方案:**
- 确保系统已安装中文字体
- Linux系统：安装 `fonts-wqy-zenhei` 或 `fonts-noto-cjk`
- macOS/Windows：通常已内置中文字体

### 问题：内容被截断

**解决方案:**
- 增加页面等待时间
- 检查目标网站是否有懒加载内容
- 使用更大的放大倍数

### 问题：并发请求失败

**解决方案:**
- 检查是否达到并发限制（20个）
- 查看浏览器池状态：`GET /api/pool-stats`
- 增加浏览器池大小或系统内存

### 问题：内存不足

**解决方案:**
- 减少浏览器池大小（修改 `src/browserPool.ts`）
- 减少并发请求数量
- 增加系统内存

### 问题：Playwright浏览器未安装

**解决方案:**
```bash
# 安装Chromium浏览器
npx playwright install chromium
```

## 📝 开发说明

### TypeScript编译

```bash
# 编译TypeScript代码
npm run build

# 监听模式编译（自动重新编译）
npm run watch
```

### 代码结构

- `src/index.ts`: Express服务器，处理HTTP请求和路由
- `src/pdfGenerator.ts`: PDF生成核心逻辑，使用Playwright
- `src/browserPool.ts`: 浏览器实例池管理，实现资源复用

### 添加新功能

1. 修改 `src/pdfGenerator.ts` 添加PDF生成逻辑
2. 修改 `src/index.ts` 添加新的API路由
3. 修改 `public/index.html` 更新前端界面
4. 运行 `npm run build` 编译代码
5. 重启服务测试

## 🔒 安全注意事项

- 生产环境建议使用HTTPS
- 限制可访问的URL白名单（如需要）
- 定期清理PDF文件，避免磁盘空间不足
- 设置合理的超时时间，防止长时间占用资源

## 📊 性能指标

- **单次PDF生成时间**: 5-30秒（取决于网页复杂度）
- **并发处理能力**: 最多20个同时请求
- **内存占用**: 约2-3GB（20个并发时）
- **浏览器实例**: 最多5个，自动复用

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📄 许可证

MIT License

## 🙏 致谢

- [Playwright](https://playwright.dev/) - 强大的浏览器自动化工具
- [Express](https://expressjs.com/) - 快速、简洁的Web框架
- [TypeScript](https://www.typescriptlang.org/) - 类型安全的JavaScript超集