纯前端PDF合并工具开发：基于Astro与PDF-lib的A6面单智能排版方案

1. 项目概述：一个纯前端的PDF标签合并工具

如果你和我一样，经常需要打印大量的A6尺寸的物流面单，看着一张张A4纸只印了一个小标签就被浪费掉，心里总会觉得有点可惜。无论是运营一个小型电商店铺，还是管理仓库发货，这种纸张和耗材的浪费日积月累下来也是一笔不小的开销。市面上虽然有一些桌面软件能处理，但要么收费，要么操作繁琐，还得担心文件隐私。于是，我动手做了一个完全在浏览器里运行的工具——Label Squeeze，它的核心目标就一个：帮你把多个A6面单智能地合并到A4纸上，一张纸打四个标签，省纸省墨省心。

Label Squeeze是一个基于现代Web技术栈构建的纯前端应用。这意味着你上传的所有PDF文件都只在你的电脑内存里处理，不会上传到任何服务器，处理完即销毁，隐私性有绝对保障。它不仅能合并独立的A6 PDF文件，还能智能地从你已有的A4面单PDF中，自动识别并裁剪出位于页面左上角的A6标签区域进行合并，这个功能对于从某些物流平台直接下载的A4格式面单特别有用。整个工具使用Astro作为主框架，搭配Tailwind CSS快速构建界面，核心的PDF操作则交给了强大的pdf-lib库在浏览器端完成。

2. 核心设计思路与技术选型解析

2.1 为什么选择纯前端架构？

在项目启动前，我首先明确了一个核心约束：所有操作必须在客户端完成。这主要基于两点考虑。第一是用户隐私。物流面单包含收发货人地址、电话等敏感信息，让用户上传到第三方服务器存在潜在风险。纯前端处理彻底杜绝了数据泄露的可能。第二是用户体验与成本。省去了服务器端的文件接收、处理、返回链路，意味着更快的响应速度（无需网络往返延迟）和为零的服务器运维成本。用户打开网页即用，没有注册、登录、付费门槛。

当然，纯前端方案也带来了挑战，主要是浏览器的性能和内存限制。处理几十上百页的PDF时，如果实现不当，很容易导致页面卡顿甚至崩溃。这就需要我们在技术选型和代码实现上格外小心。

2.2 技术栈的深度考量

Astro 4.0.0：这是我选择的核心框架。Astro的“岛屿架构”（Islands Architecture）理念非常适合这个工具。我们的页面大部分是静态内容（如使用说明、界面布局），只有文件上传、PDF预览和合并逻辑是交互性的“岛屿”。Astro能自动将这些交互部分拆分为独立的、按需加载的组件，从而让首屏加载极快，SEO友好（因为初始HTML是服务端渲染的）。同时，它原生支持TypeScript和流行的CSS框架，开发体验流畅。

PDF-lib 1.17.1：这是客户端PDF操作的基石。我对比了多个库，如jsPDF和pdf.js的生成模块。PDF-lib的优势在于其API相对直观，对PDF的修改（如合并页面、裁剪、调整尺寸）支持良好，且文档齐全。它的工作原理是在内存中解析PDF二进制数据，构建文档对象模型，然后进行编程式操作，最后再生成新的PDF二进制流。虽然处理超大文件时仍需注意，但对于常规数量的面单，其性能是完全足够的。

PDF.js 3.11.174：专门用于预览。为什么不直接用PDF-lib渲染？因为PDF-lib专注于编辑和创建，而PDF.js是Mozilla出品、经过大量实战检验的PDF渲染引擎，它能高质量地将PDF页面渲染到HTML5 Canvas上，支持缩放、分页等预览常用功能。在项目中，我们将PDF-lib处理后的结果，通过PDF.js渲染给用户预览，实现“所见即所得”。

Tailwind CSS 5.0.0：选择它纯粹是为了开发效率。这种工具类优先的CSS框架，让我在构建响应式、简洁的界面时几乎不需要在CSS文件和HTML组件间来回切换。通过简单的类名组合就能实现复杂的布局和交互状态，特别适合快速迭代的原型开发和单人项目。

TypeScript：在涉及PDF二进制数据操作、复杂的异步流程和尺寸计算时，类型系统能极大减少低级错误。比如，PDF中的坐标和尺寸单位是“点”（point），1点等于1/72英寸，通过TypeScript定义清晰的接口，能避免因单位混淆导致的布局错乱。

3. 核心功能实现与难点剖析

3.1 PDF尺寸与坐标系统：一切的基础

PDF内部的坐标系和尺寸单位是第一个需要厘清的概念。在PDF-lib中，默认使用PDF的原始单位：点（Point）。标准A4纸的尺寸是210mm x 297mm，换算成点是595.276 x 841.890。A6是A4的一半，即105mm x 148mm，对应297.638 x 420.945点。

这里有一个关键细节：PDF的坐标原点(0, 0)默认在页面的左下角，而我们在网页和日常认知中通常以左上角为原点。在实现裁剪和放置时，需要进行坐标转换。例如，要从一个A4页面的左上角裁剪出一个A6区域，我们需要的矩形参数是：x坐标从0开始，y坐标从A4高度减去A6高度开始（因为原点在左下角，左上角的y坐标值最大）。

// 定义A4和A6的尺寸（单位：点） const A4_WIDTH = 595.276; const A4_HEIGHT = 841.890; const A6_WIDTH = 297.638; const A6_HEIGHT = 420.945; /** * 从A4页面裁剪左上角的A6区域 * @param page PDF-lib的PDFPage对象 * @returns 裁剪区域的坐标和尺寸 */ function extractTopLeftA6FromA4(page: PDFPage): { x: number; y: number; width: number; height: number } { // 原点在左下角，左上角的y坐标是页面高度减去A6高度 return { x: 0, y: A4_HEIGHT - A6_HEIGHT, // 计算左上角起始y坐标 width: A6_WIDTH, height: A6_HEIGHT }; }

3.2 智能文件处理流程

用户上传的文件可能是独立的A6面单PDF，也可能是包含一个A6面单的A4 PDF。工具需要自动判断并统一处理。我的实现逻辑如下：

1. 文件类型嗅探与加载：通过FileReader读取用户上传的PDF文件为ArrayBuffer，然后使用PDF-lib的PDFDocument.load方法加载。
2. 页面尺寸检测：获取PDF第一页的尺寸。这里我设定了一个容差范围（比如±5点），来判断页面尺寸是更接近A4还是A6。
3. 分支处理：
   • 如果是A6尺寸：直接将该页面作为一个待合并的标签。
   • 如果是A4尺寸：假设A6标签位于页面左上角（这是绝大多数物流面单的默认布局），调用上述裁剪函数，从该A4页面中提取出A6区域，创建一个新的、只包含这个A6区域内容的PDF页面。
4. 统一为A6页面数组：经过上述步骤，所有输入文件都被转换成了一个由纯A6尺寸页面组成的数组，等待合并。

注意：这里“假设左上角”是一个基于常见场景的简化。在实际操作中，我建议用户先确认一下自己面单模板的布局。如果标签位置不固定，这个工具可能无法正确裁剪。一个可能的增强功能是未来允许用户手动框选裁剪区域。

3.3 A6到A4的合并算法

将多个A6页面合并到A4纸上，本质是一个排版问题。我采用了经典的2x2网格布局，即每张A4纸放置最多4个A6标签。算法步骤如下：

1. 创建目标A4文档：使用PDF-lib创建一个新的空白PDF文档。
2. 分页循环：遍历所有待合并的A6页面，每4个一页（最后一页可能不足4个）。
3. 计算位置：对于当前A4页上的第i个位置（i从0到3），计算其左上角在A4页上的坐标。
   • 第0个（左上角）：x=0, y=A4_HEIGHT - A6_HEIGHT
   • 第1个（右上角）：x=A6_WIDTH, y=A4_HEIGHT - A6_HEIGHT
   • 第2个（左下角）：x=0, y=A4_HEIGHT - 2 * A6_HEIGHT
   • 第3个（右下角）：x=A6_WIDTH, y=A4_HEIGHT - 2 * A6_HEIGHT
4. 嵌入页面：使用PDF-lib的目标A4页.drawPage(A6页, { x, y, width: A6_WIDTH, height: A6_HEIGHT })方法，将A6页面像贴图一样画到A4页的指定位置。
5. 生成最终PDF：所有页面排版完成后，调用doc.save()生成一个包含合并后所有A4页的PDF文件二进制数据，供用户下载。

3.4 实时预览与用户体验优化

“实时预览”是提升工具可用性的关键。我的实现方案是：

1. 异步处理与状态管理：文件上传、PDF解析、合并计算都是异步操作。我使用了一个中央状态（比如Vue的reactive对象或Solid的signal）来管理文件列表、处理状态和预览数据。任何文件列表的变动（增、删、排序）都会触发一个防抖的处理流程。
2. 预览生成：合并计算完成后，得到的PDF二进制数据（一个Uint8Array）并不会直接保存。而是将其转换为一个Blob URL（URL.createObjectURL(new Blob([data], { type: 'application/pdf' }))）。
3. 集成PDF.js Viewer：在页面中嵌入一个<iframe>或使用PDF.js提供的PDFViewer组件，将其src属性设置为上一步生成的Blob URL。这样用户就能立即在网页中看到合并后的PDF效果，包括多页导航。
4. 性能与反馈：
   • 加载指示器：在处理过程中，禁用下载按钮并显示“处理中...”的提示或旋转图标。
   • 错误处理：用友好的Toast通知提示用户文件损坏、密码保护或尺寸不符等问题。
   • 内存清理：预览的Blob URL在使用后（如下载或新预览生成时）通过URL.revokeObjectURL()及时释放，避免内存泄漏。

4. 前端工程化与部署实践

4.1 基于Astro的项目结构

Label Squeeze的代码结构遵循了Astro的最佳实践，保持了清晰和可维护性。

src/ ├── components/ # 可复用的Astro/框架组件 │ ├── FileUpload.astro │ ├── FileList.astro (集成拖拽排序) │ ├── PdfPreview.astro (集成PDF.js) │ └── Notification.astro ├── layouts/ # 页面布局 │ └── Layout.astro ├── pages/ # 路由页面 │ └── index.astro # 主应用页面 ├── scripts/ # 纯逻辑TS/JS文件 │ ├── pdfProcessor.ts # PDF合并核心逻辑 │ ├── previewManager.ts # 预览控制逻辑 │ └── utils.ts └── styles/ # 全局样式 └── global.css

index.astro是入口，它引入了布局和各个交互组件。关键的PDF处理逻辑被封装在/scripts目录下的纯TypeScript模块中，与UI组件解耦，便于测试和维护。

4.2 拖拽排序的实现

为了让用户能调整标签的打印顺序，我实现了文件列表的拖拽排序。没有引入庞大的拖拽库，而是使用了原生的HTML5 Drag and Drop API，结合一点状态管理来实现。

1. 可拖放属性：为列表中的每个文件项设置draggable="true"。
2. 事件处理：监听dragstart,dragover,drop事件。
   • dragstart: 记录被拖拽元素的索引。
   • dragover: 阻止默认行为以允许放置，并更新视觉反馈（如插入位置高亮）。
   • drop: 再次阻止默认行为，根据拖拽起始索引和放置目标索引，重新排序文件列表状态数组。
3. 状态更新：文件列表顺序一旦改变，就会触发之前提到的响应式状态更新，进而自动重新触发PDF合并与预览生成。

4.3 部署流程：GitHub Actions + FTP

项目采用了自动化的CI/CD流程，通过GitHub Actions实现一键部署到静态主机。

# .github/workflows/deploy.yml name: Deploy to seohost via FTP on: push: tags: - 'v*' # 推送v开头的标签时触发 workflow_dispatch: # 也支持手动触发 jobs: deploy: runs-on: ubuntu-latest environment: prod # 引用配置的环境变量 steps: - uses: actions/checkout@v3 - name: Setup Node.js uses: actions/setup-node@v3 with: node-version: '18' - name: Install Dependencies run: npm ci - name: Build Project run: npm run build # 执行Astro构建，生成静态文件到`dist`目录 - name: Deploy to FTP uses: SamKirkland/FTP-Deploy-Action@v4 with: server: ${{ secrets.FTP_HOST }} username: ${{ secrets.FTP_USERNAME }} password: ${{ secrets.FTP_PASSWORD }} local-dir: ./dist/ server-dir: ${{ secrets.FTP_ROOT_PATH }}

部署流程说明：

1. 环境配置：在GitHub仓库的Settings -> Environments中创建prod环境，并添加FTP服务器的主机、用户名、密码和路径等密钥。这些信息在Action运行时被安全注入。
2. 触发部署：有两种方式。一是打一个语义化版本标签（如git tag -a v1.2.0 -m "Release v1.2.0" && git push origin v1.2.0），推送到GitHub后自动触发部署。二是在GitHub Actions页面手动触发工作流。
3. 自动执行：Action会拉取代码，安装依赖，运行npm run build（对应Astro的构建命令），将生成的静态文件（HTML, CSS, JS, 资源）通过FTP上传到指定服务器目录。
4. 版本反馈：构建时，我将package.json中的版本号或Git标签名注入到一个全局变量中，并显示在网页页脚，方便用户确认当前使用的版本。

这种部署方式非常适合静态站点，无需服务器端环境，快速且成本低。

5. 开发中遇到的典型问题与解决方案

5.1 内存管理与大文件处理

问题：当用户一次性上传数十个PDF文件时，浏览器内存占用飙升，可能导致页面响应缓慢或崩溃。因为每个PDF文件都需要被完整加载到内存中解析。

解决方案：

1. 分页处理，流式释放：不要一次性加载所有文件的所有页面。实现一个队列，每次只处理一个文件。处理完一个文件（提取出所需的A6页面数据）后，立即调用PDF-lib的doc.cleanup()或确保相关变量被垃圾回收，释放内存。
2. 限制并发与文件大小：在前端设置合理的防护。例如，限制单次上传的文件数量（如20个）或总大小（如50MB），并在UI上给出明确提示。
3. 使用Web Worker（进阶）：将最耗时的PDF解析和合并计算放到Web Worker线程中，避免阻塞主线程导致UI卡顿。不过，由于PDF-lib和PDF.js某些API对DOM有依赖，移入Worker可能需要额外配置或使用特定版本。

5.2 PDF.js 预览与PDF-lib生成的兼容性

问题：使用PDF-lib合并生成的新PDF，在PDF.js中预览时，偶尔会出现内容模糊、错位或根本无法渲染的情况。

排查与解决：

1. 字体嵌入问题：这是最常见的原因。原始A6标签中的字体，在PDF-lib处理时如果没有被正确复制或嵌入到新文档中，PDF.js渲染时就会找不到字体，导致显示异常。
   • 解决：在PDF-lib中复制页面时，使用destDoc.embedPage(page)或destDoc.copyPages(srcDoc, [pageIndex])方法，它们会尝试将页面所需资源（包括字体）一并复制到新文档。确保后续的drawPage操作使用的是复制过来的页面对象。
2. 坐标转换错误：如前所述，PDF坐标系原点在左下角。如果在计算裁剪或放置位置时弄反了Y轴方向，预览内容就会上下颠倒或跑到页面外。
   • 解决：反复检查所有涉及x, y, width, height的计算公式，并编写单元测试，用几个已知尺寸的PDF文件验证输出结果。
3. PDF.js版本与配置：不同版本的PDF.js默认配置可能不同。
   • 解决：确保使用稳定版本，并在初始化PDF.js查看器时，显式设置disableFontFace=false等可能影响渲染的选项。

5.3 拖拽排序的视觉与交互优化

问题：原生拖拽API提供的视觉反馈比较简陋，在不同浏览器中行为不一致，且很难实现平滑的动画效果。

解决方案：

1. 自定义拖拽镜像：在dragstart事件中，可以创建一个自定义的、半透明的元素作为拖拽跟随镜像，替代浏览器默认的截图，这样视觉效果更统一。
2. 使用dataTransfer.setData：在dragstart中，使用e.dataTransfer.setData('text/plain', index)存储被拖拽项的索引。在drop事件中通过e.dataTransfer.getData('text/plain')获取，这样即使拖拽过程中鼠标经过了其他元素，也能正确获取源数据。
3. CSS过渡动画：在拖拽排序完成后，更新列表的DOM顺序。通过CSS的transition属性为列表项的位置变化添加平滑的动画，提升用户体验。可以给文件列表容器设置transition: transform 0.3s ease，然后通过改变order或直接操作DOM位置来触发动画。

5.4 响应式设计与移动端适配

问题：工具的核心操作是文件上传和预览，在手机小屏幕上，文件列表和PDF预览区域的布局容易拥挤，操作不便。

解决方案：

1. Tailwind响应式断点：充分利用Tailwind的响应式工具类。例如，在小屏幕上（md:以下），将水平排列的文件列表改为垂直堆叠；将预览区域从侧边栏调整到文件列表下方。
2. 触摸友好的交互：在移动端，用触摸事件补充或替代部分鼠标事件。例如，为文件列表项添加长按触发拖拽的替代方案（虽然体验不如桌面）。确保所有按钮和点击区域有足够大的尺寸（至少44x44像素）。
3. 预览区域优化：在移动端，PDF预览可能不适合全页显示。可以改为提供一个缩略图，点击后以模态框（Modal）或全屏方式打开PDF.js查看器，提供更好的阅读体验。

6. 性能优化与最佳实践总结

经过这个项目的开发，我总结了几条对于构建复杂前端工具至关重要的性能优化点：

1. 惰性加载与代码分割：利用Astro或现代打包工具（如Vite）的代码分割能力，将PDF.js这样较大的第三方库从主包中分离，仅在使用预览功能时才动态加载。
2. 防抖与异步队列：文件列表的每次变化（尤其是拖拽排序时）都会触发合并计算。必须使用防抖函数（如Lodash的_.debounce）确保在用户停止操作后再开始计算，避免不必要的、密集的计算连续触发。
3. 对象URL的生命周期管理：每次生成新的预览Blob URL后，务必记得用URL.revokeObjectURL(oldUrl)释放之前的URL。这是一个常见的记忆泄露点。
4. 提供明确的进度反馈：对于可能耗时的操作（如处理包含很多图片的PDF），如果可能，将处理过程分解为多个步骤，并更新进度条或文字提示，让用户知道应用正在工作，而非卡死。
5. 优雅降级与错误边界：检测浏览器是否支持所需的API（如File API, Drag and Drop）。如果不支持，显示友好的提示信息，而不是让界面崩溃。用try...catch包裹核心的PDF处理逻辑，捕获可能出现的异常（如损坏的PDF文件），并以用户能理解的方式告知。

这个项目从构思到上线，最大的体会是：将一个看似简单的需求（合并PDF）做深做透，会遇到许多意料之外的细节挑战，从PDF内部的坐标体系，到浏览器内存管理，再到跨平台的交互体验。但解决这些问题的过程，正是前端开发从“写页面”到“构建应用”的进阶之路。工具虽小，却涵盖了现代前端开发的多个关键环节，是一次非常扎实的实践。