/puppeteer-server

🦩 Puppeteer + Node.js 后端模板, 基于 ESM + Koa + Rollup + TypeScript + ESLint (v9)实现后台服务, 快速将任意网页转换为 PDF / 图像快照, 支持爬取合并多个网页自动生成为 PDF 文件，支持 Cookie 注入、PDF 水印和页眉页脚插入

Primary LanguageTypeScriptMIT LicenseMIT

Puppeteer Server

中文 | English

📤 迁移到 Playwright

为了体验更好的功能和更广泛的浏览器支持，目前新版代码已全部无缝迁移到 Playwright

Playwright 仓库: koa-playwright-server

介绍

🦩 Koa + ESM + TypeScript + Rollup + Nodemon + Puppeteer + ESLint (v9)

  • 能够将任意网页快速生成为 PDF、图片。

  • 支持将多个网页合并，并最终生成一个 PDF 文件，支持 Cookie 的注入、PDF 水印的添加和页眉页脚的插入。

✨ 特性

  • ✅ 自带 TypeScript + ES Module 环境

  • 🌈 解耦了业务层和控制层

  • 🛡 可能是 Puppeteer 项目的最佳实践

  • 🧩 可配置的路由

  • 🚧 内置 Eslint (v9) 语法风格检查

  • ⚡ 使用 Rollup 快速构建

  • 🔌 内置了 PDF 水印、页眉和页脚，可自行修改及扩展

  • 🧲 支持合并多个 PDF 文件

  • 🔥 支持 Nodemon 开发环境下的模块热更新

截图

  • 示例：合并多个网站到一个 PDF 文件

📦 详见 示例代码1、示例代码2

image

🎯 前序准备

请确保安装了 Node.js(>= 20.x)

项目结构

├── src
│   ├── controllers/ ---  控制层，负责调用业务层的接口
│   ├── services/    ---  业务层，负责编写具体的业务代码
│   ├── config.ts    ---  用于导出一些全局变量
│   ├── main.ts      ---  入口文件
│   └── routes.ts    ---  用于配置路由元信息 👉 路由配置

⚡ 快速开始

1. 安装

pnpm install

2. 开发环境运行

pnpm dev

3. 生产环境运行

该项目已内置 pm2，在构建完毕后运行 pnpm start 即可使用 pm2 管理进程。

运行 pnpm build 进行构建，然后运行 pnpm start 启动由 pm2 管理的进程:

  • 打包构建
pnpm build
  • 运行
pnpm start # 端口号为 8080
# 或直接运行
node dist/bundle.esm.js # 端口号为 5000

核心接口

  • GET /image

用于生成一张图片

curl --location --request GET \
'http://localhost:5000/image?url=https://www.baidu.com' \
--output test-image.png
  • GET /simple-pdf

用于生成一个 PDF 文件

curl --location --request GET \
'http://localhost:5000/simple-pdf?url=https://www.google.com/' \
--output test-simple-pdf.pdf
  • POST /pdf

可生成一个带有自定义页眉和页脚的 PDF（页眉页脚的内容可通过参数来控制是否显示）

curl --location --request POST 'http://localhost:5000/pdf' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'url=http://www.google.com' \
--data-urlencode 'cookies[0].name=token' \
--data-urlencode 'cookies[0].value=9s2d4c16-f072-16eg-b134-0642ap190006' \
--data-urlencode 'cookies[0].domain=www.google.com' --output test-complex-pdf.pdf

👆 /pdf 请求参数

字段 说明 类型 默认值
url 目标网站 string —
cookies 如果网站需要提前内置 sessionId cookie, 一般用作需要登录才能访问的网站，则添加此字段即可 Array<{ name, value, domain }> []
hasMargin 是否生成出的 PDF 含有内边距空白 boolean true
isLandscape 是否生成横向的 PDF boolean false
hiddenWatermark 是否隐藏水印 boolean false
attachment 展示自定义页眉页脚，前提是需要将 hasMargin 设置为 true { header, footer } —
  • POST /combine-pdf

用于将多个 PDF 文件合并到一个文件

查看 示例代码1、示例代码2

👆 /combine-pdf 请求参数

字段 说明 类型 默认值
pdfList 目标网站集合，参数类型为数组，数组内每一项即为一个 /pdf 所需的参数 Array<{ pdfItem }> []

路由配置

为了使路由元数据更具可读性和透明性，这里采用了配置化的方式

你可以创建一个 数组，然后将路由元信息写入该 数组 中，并在 src/routes.ts 中重用它

const routes: Array<RouteConfig> = [
  {
    path: '/',
    method: 'get',
    action: homeController.hello
  },
  // here...
]

许可证

✌️

MIT

FOSSA Status