PDF 预览不将就:微信小程序“边看边加载”方案的技术决策与实现

微信小程序 PDF 边看边加载方案：从 PDF.js 限制到上传转图片的架构演进

在微信小程序中实现 PDF 在线预览，且要求“边看边加载”，并非一帆风顺。本文记录了我们从技术选型、踩坑到最终落地“上传时预处理 + 静态图片分页加载”的完整过程，希望能为遇到类似问题的开发者提供参考。

一、需求与挑战

项目需要在小程序中嵌入 PDF 文档阅读功能，核心要求只有一条：

用户打开 PDF 后，能像浏览网页一样，滚动或翻页时按需加载，无需等待完整文件下载完毕。

这个需求在 Web 端很常见，PDF.js 可以轻松实现。但到了微信小程序环境，情况就变得复杂了：

小程序没有完整的浏览器环境（无 window、document 对象），PDF.js 无法直接运行。
即使通过 web-view 嵌入 H5 页面来跑 PDF.js，也会受到业务域名、跨域、用户体验一致性等多重限制。
官方提供的 wx.openDocument 必须下载完整文件，无法做到“边看边加载”，大文件会长时间白屏。

因此，我们必须在后端寻找出路，设计一套小程序友好的 PDF 分页加载方案。

二、技术选型与方案对比

2.1 候选方案

方案	实现方式	优点	缺点
A. 前端 PDF.js（`web-view` 嵌入）	小程序内嵌 H5，由 H5 里的 PDF.js 通过 Range 请求按需拉取字节	功能完整，支持文本选择，真正的按需加载	需要维护 H5 页面，配置业务域名，受限于 `web-view` 容器，iOS/Android 表现可能不一致
B. 官方 API（`wx.downloadFile` + `wx.openDocument`）	下载完整 PDF，调用微信内置查看器	实现最简单，无需额外开发	必须全部下载，无法边看边加载，UI 不可定制
C. 后端预转图片 + 分页接口	PDF 上传时异步转成图片，小程序分页请求图片 URL，`<image>` 懒加载	完全自定义 UI，真正的按需加载，性能极佳，全平台一致	需要后端处理，不支持文本选择/复制，存储成本略高

2.2 我们的选择

基于以下考虑，我们最终选择了 方案 C：

产品要求自定义阅读器 UI（进度、缩放、目录等），方案 B 无法满足。
方案 A 在实际测试中，web-view 的加载速度和手势流畅度不如原生组件，且域名配置繁琐。
我们的后端技术栈是 Spring Cloud，可以轻松集成 PDFBox 进行图片转换，并且已有 MinIO 作为对象存储，存储图片成本可控。

结论：用后端“空间换时间”——在 PDF 上传时预先生成所有页面的图片，小程序端只负责按需请求图片地址并展示。

三、后端架构设计与实现（Spring Cloud + MinIO + PDFBox）

3.1 整体流程

3.2 关键技术实现

① PDF 上传接口（触发异步转换）

@PostMapping("/upload")public ResponseEntity<String> uploadPdf(@RequestParam("file") MultipartFile file) {    String pdfId = UUID.randomUUID().toString();    // 1. 原始文件存到 MinIO（备份）    minioClient.putObject(        PutObjectArgs.builder()            .bucket("pdf-source")            .object(pdfId + ".pdf")            .stream(file.getInputStream(), file.getSize(), -1)            .contentType("application/pdf")            .build()    );    // 2. 初始化数据库记录（状态=PROCESSING）    pdfDocumentService.initRecord(pdfId, file.getOriginalFilename());    // 3. 异步执行转换（使用线程池）    pdfConvertService.asyncConvert(pdfId, file);    return ResponseEntity.ok(pdfId);}

② 异步转换服务（核心）

使用 PDFBox 的 PDDocument 和 PDFRenderer，将每页渲染为图片，并上传至 MinIO。

@Async("pdfConvertExecutor") // 专用线程池public void asyncConvert(String pdfId, MultipartFile file) {    try (PDDocument document = PDDocument.load(file.getBytes(),             MemoryUsageSetting.setupTempFileOnly())) {  // 防止大文件 OOM        PDFRenderer renderer = new PDFRenderer(document);        int totalPages = document.getNumberOfPages();        List<PdfPageImage> pageImages = new ArrayList<>();        for (int i = 0; i < totalPages; i++) {            // 1. 渲染（DPI=150，平衡清晰度和体积）            BufferedImage image = renderer.renderImageWithDPI(i, 150);            ByteArrayOutputStream baos = new ByteArrayOutputStream();            ImageIO.write(image, "webp", baos); // 推荐 WebP 格式            // 2. 上传到 MinIO（公开读的 bucket）            String objectName = String.format("pdf-pages/%s/page_%d.webp", pdfId, i + 1);            minioClient.putObject(                PutObjectArgs.builder()                    .bucket("pdf-pages")                    .object(objectName)                    .stream(new ByteArrayInputStream(baos.toByteArray()), baos.size(), -1)                    .contentType("image/webp")                    .build()            );            // 3. 构造访问 URL（若 bucket 公开，直接拼接；否则预签名）            String url = String.format("https://minio.example.com/pdf-pages/%s", objectName);            pageImages.add(new PdfPageImage(pdfId, i + 1, url, image.getWidth(), image.getHeight()));        }        // 4. 批量入库        pdfPageImageRepository.saveAll(pageImages);        pdfDocumentService.updateStatus(pdfId, "SUCCESS", totalPages);    } catch (Exception e) {        pdfDocumentService.updateStatus(pdfId, "FAILED", 0);        log.error("PDF转换失败, pdfId: {}", pdfId, e);    }}

注意：ImageIO.write(image, "webp", baos) 需要引入 webp-imageio 依赖，让 Java 支持 WebP 编码。如不想引入，可改为 "png"。

③ 分页查询接口（供小程序调用）

@GetMapping("/pages")public ResponseEntity<PageResult> getPages(@RequestParam String pdfId,                                           @RequestParam int page,                                           @RequestParam int size) {    Pageable pageable = PageRequest.of(page - 1, size);    Page<PdfPageImage> imgPage = pdfPageImageRepository.findByPdfId(pdfId, pageable);    PageResult result = new PageResult(        imgPage.getContent().stream().map(PdfPageImage::getImageUrl).collect(Collectors.toList()),        imgPage.getTotalElements(),        imgPage.getTotalPages()    );    return ResponseEntity.ok(result);}

四、小程序端实现（原生 + 懒加载）

小程序端代码变得极其简洁，只需一个 scroll-view 配合 lazy-load 属性。

4.1 页面数据与加载逻辑

Page({  data: {    pdfId: '',          // 从上一页传入    page: 1,    size: 10,    imageList: [],    totalPages: 0,    loading: false,    hasMore: true  },  onLoad(options) {    this.setData({ pdfId: options.pdfId });    this.loadPages(); // 首次加载第一页  },  loadPages() {    if (this.data.loading || !this.data.hasMore) return;    this.setData({ loading: true });    wx.request({      url: 'https://api.example.com/pdf/pages',      data: {        pdfId: this.data.pdfId,        page: this.data.page,        size: this.data.size      },      success: (res) => {        const { list, total, totalPages } = res.data;        this.setData({          imageList: [...this.data.imageList, ...list],          totalPages: totalPages,          page: this.data.page + 1,          hasMore: this.data.page <= totalPages,          loading: false        });      },      fail: () => {        this.setData({ loading: false });        wx.showToast({ title: '加载失败', icon: 'none' });      }    });  },  // 触底加载更多  onReachBottom() {    this.loadPages();  }});

4.2 视图层（WXML）

<scroll-viewscroll-ybindscrolltolower="onReachBottom"style="height:100vh;">  <blockwx:for="{{imageList}}"wx:key="index">    <image      src="{{item}}"       mode="widthFix"       lazy-load="{{true}}"       style="width:100%; display:block;"    />  </block>  <viewwx:if="{{loading}}"class="loading-tip">正在加载...</view>  <viewwx:elif="{{!hasMore}}"class="loading-tip">已加载全部</view></scroll-view>

关键点：

lazy-load 让图片只在即将进入可视区时才真正发起网络请求，实现了“边滚动边加载”。
mode="widthFix" 保证图片宽度撑满屏幕，高度按比例自动缩放。
触底加载下一页，用户体验流畅。

五、方案优势与注意事项

5.1 优势

✅ 完全绕开 PDF.js 限制：小程序端不处理任何 PDF 逻辑，只展示图片。
✅ 真正的边看边加载：懒加载机制保证用户滑动到哪里，图片才加载到哪里，流量消耗极小。
✅ 性能极佳：静态图片 CDN 加速，小程序原生组件渲染，比 web-view 流畅得多。
✅ 完全自定义 UI：可自由添加缩放、页码、目录、水印等交互。
✅ 稳定可靠：不依赖第三方库，不受小程序版本更新影响。

5.2 注意事项

存储成本：需要为每页图片付出存储和 CDN 费用，但相比 PDF 原文件体积，单页 WebP 图片通常只有几十 KB，10 页 PDF 也才几 MB，成本可控。
不支持文本选择/复制：如果业务有强搜索需求，此方案不适用，可考虑方案 A（web-view + PDF.js）或混合方案（封面+文本索引）。
转换失败补偿：务必设置状态机（PROCESSING / SUCCESS / FAILED），并添加定时任务重试失败的 PDF，否则用户可能永远看不到内容。
图片尺寸调优：手机屏幕一般宽度 375~750px，渲染 DPI 设 150 足够，不要用 300DPI 生成巨图。
MinIO 权限：若存储桶设为私有，每次需生成预签名 URL（有有效期）。建议将图片桶设为公开读，URL 永久有效，减少后端签名开销。

六、总结

面对微信小程序 PDF 预览的“边看边加载”需求，我们经历了从 web-view 尝试到后端预处理图片的架构演进，最终选择了一条稳健、高效、可维护的道路：

上传时异步转换 → 存储为图片 → 小程序分页懒加载

这套方案完美匹配了小程序原生能力，将计算压力转移到后端，让前端真正轻量化。目前已在生产环境平稳运行数月，支持日均数千份 PDF 的预览，用户反馈流畅无卡顿。

如果你也遇到类似场景，希望本文能给你一些启发。当然，技术选型没有银弹，根据业务侧重点（是否需复制文本、是否追求极致首屏速度等）选择最适合自己的方案即可。

就写到这里，希望能帮到大家，前端代码这块的是AI生产，没有亲测，前端小伙伴说微信不能用pdf.js，其实我是不太相信的，但是没有做就没有发言权，所以刷到的前端大佬们自行试验。