# html2pdf

**Repository Path**: huangyu_li/html2pdf

## Basic Information

- **Project Name**: html2pdf
- **Description**: 完美保真 HTML 转 PDF 工具，高度还原
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# html2pdf: HTML 转 PDF 服务 (离线部署版)

基于 Python + Playwright + FastAPI，使用真实 Chromium 内核渲染，完美还原网页样式（Flexbox、Grid、JS 图表渲染及现代 CSS），并通过 HTTP API 提供转换服务。

## 一、环境准备

```bash
# 安装依赖
uv sync

# 离线安装 Chromium 内核（参考下方 二、离线安装 Chromium）
# 安装系统级图形库依赖
uv run playwright install-deps chromium

# 安装中文字体
sudo apt-get install fonts-wqy-microhei fonts-wqy-zenhei -y
```

## 二、离线安装 Chromium 内核

### 1. 手动下载内核包

在有网络的电脑上下载 Playwright 指定版本的 Chrome 压缩包：
[chrome-linux64.zip](https://cdn.playwright.dev/builds/cft/147.0.7727.15/linux64/chrome-linux64.zip)

将 `chrome-linux64.zip` 上传到 Linux 服务器。

### 2. 部署

```bash
mkdir -p ~/.cache/ms-playwright/chromium-1217
unzip chrome-linux64.zip -d ~/.cache/ms-playwright/chromium-1217/
chmod +x ~/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome
touch ~/.cache/ms-playwright/chromium-1217/INSTALLATION_COMPLETE
rm chrome-linux64.zip
```

> Chromium 版本号可通过环境变量 `CHROMIUM_VERSION` 覆盖，默认为 `1217`。

## 三、启动服务

```bash
uv run app.py
# 或指定端口
uv run uvicorn app:app --host 0.0.0.0 --port 8000
```

## 四、API 接口

### GET /api/health

健康检查。

### POST /api/convert/zip

上传 zip 包，返回包含所有 PDF 的 zip 包。

**zip 包格式要求：**

```
archive.zip
├── index.html          # 主页面
├── report.html         # 其他页面
├── css/
│   └── style.css       # 样式文件
├── js/
│   └── app.js          # 脚本文件
└── images/
    └── logo.png        # 图片资源
```

所有 .html/.htm 文件（包括子目录）会被分别转换为对应的 PDF，并保持原有目录结构。HTML 文件中通过相对路径引用的资源（CSS、JS、图片）均可正常加载。

**请求参数 (multipart/form-data)：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| file | file | 是 | - | .zip 文件 |
| page_format | string | 否 | A4 | 页面格式 (A4, Letter 等) |
| margin_top | string | 否 | 10mm | 上边距 |
| margin_bottom | string | 否 | 10mm | 下边距 |
| margin_left | string | 否 | 10mm | 左边距 |
| margin_right | string | 否 | 10mm | 右边距 |
| print_background | bool | 否 | true | 是否保留 CSS 背景 |
| wait_timeout | float | 否 | 1.0 | 页面加载后额外等待秒数 |

**示例：**

```bash
curl -X POST http://localhost:8000/api/convert/zip \
  -F "file=@archive.zip" \
  -F "page_format=A4" \
  -o converted_pdfs.zip
```

### POST /api/convert/url

将在线 URL 转换为 PDF 并直接返回 PDF 文件。
`url` 必须带有 `http://` 或 `https://` 协议前缀。

```bash
curl -X POST http://localhost:8000/api/convert/url \
  -F "url=https://example.com" \
  -o output.pdf
```

## 五、命令行模式

`main.py` 保留为简单的 CLI 演示入口：

```bash
uv run main.py
#
```

## 六、配置

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| CHROMIUM_VERSION | 1217 | Playwright Chromium 内核版本号 |