用C#开发PDF文档处理功能,如何在解析前校验文件并识别损坏文档?

发布人:A5数据发布时间:2026-11-17 14:28阅读量:3

上传接口收到一个名为 report.pdf 的文件时,文件名、扩展名和浏览器提交的 Content-Type 都不能证明它真的是可解析的 PDF。更可靠的做法是把校验分成两层:先检查文件本身的基本结构,再交给 PDF 解析器打开并遍历页面内容。只有两层都通过,才进入正式的文本、表格或业务字段解析。

校验流程应该怎样划分

PDF 文件的异常通常不只有一种表现,可以按处理阶段分为以下几类:

  1. 文件输入异常:文件不存在、大小为 0、超过业务限制,或者上传过程尚未完成。
  2. 格式特征异常:文件头不是 %PDF-,文件可能是 HTML 错误页、图片、压缩包,或者只是被错误地改成了 .pdf 后缀。
  3. 结构异常:交叉引用表、对象、Trailer、对象流或文件尾部信息缺失。
  4. 页面内容异常:文件能够打开,但某个页面的内容流、字体、过滤器或对象解析失败。
  5. 业务限制异常:文件加密、没有页面、页数过多,或者当前解析器不支持其中的某项 PDF 特性。

因此,不能只用下面这种判断:

if (Path.GetExtension(fileName).Equals(".pdf",
    StringComparison.OrdinalIgnoreCase))
{
    // 直接解析
}

这个判断最多只能作为界面提示,不能作为安全校验或解析前置条件。

一个适合接入上传服务的流程是:

上传完成并写入临时文件
        ↓
文件大小与基本特征检查
        ↓
PDF 解析器打开文件
        ↓
读取页数并遍历所有页面
        ↓
按业务要求进入文本、表格或附件解析

需要特别注意,很多 PDF 解析器采用延迟读取。仅仅执行“打开文档”不一定会访问所有页面,更不能据此判断文档的每一页都没有损坏。

准备 .NET 项目和校验模型

下面的示例以 .NET 8 和 iText 7.2.x 的 Kernel API 为基础,NuGet 包使用 itext7。例如可以固定到项目已经审核过的版本:

dotnet add package itext7 --version 7.2.5

iText 的授权方式需要结合项目发布模式确认。AGPL 或商业授权的适用条件可能不同,商业项目不应只复制代码后忽略依赖许可。

先定义校验状态。状态不要只设计成 true 或 false,否则调用方无法区分“文件损坏”“需要密码”和“超过业务限制”。

namespace PdfPreflightDemo;

public enum PdfCheckStatus
{
    Valid,

    FileNotFound,
    EmptyFile,
    TooLarge,
    HeaderMissing,
    EofMarkerMissing,

    Encrypted,
    NoPages,
    PageLimitExceeded,

    MalformedOrUnsupported,
    Unreadable
}

public sealed class PdfValidationOptions
{
    // 示例值:100 MiB,不代表所有项目都适用
    public long MaxBytes { get; init; } = 100L * 1024 * 1024;

    // 示例值:5000 页,应根据业务文档类型调整
    public int MaxPages { get; init; } = 5000;

    // 严格模式下,要求文件尾部能够找到 %%EOF
    public bool RequireEofMarker { get; init; } = true;

    // 是否遍历每一页并执行内容解析
    public bool ParsePageContent { get; init; } = true;
}

public sealed record PdfCheckResult(
    PdfCheckStatus Status,
    long FileLength,
    int? PageCount,
    bool HasEofMarker,
    string Message)
{
    public bool Accepted => Status == PdfCheckStatus.Valid;
}

这里的 100L <em> 1024 </em> 1024 是 100 MiB,而不是十进制意义上的 100 MB。如果系统的上传限制使用十进制 MB,需要统一配置口径,避免网关、应用和校验器设置不一致。

HasEofMarker 单独保留下来,是因为缺少 %%EOF 可以作为异常信号,但它并不等于解析器一定无法读取。部分解析器能够对某些不完整文件进行恢复,因此是否将它直接判定为拒绝,应由项目的严格程度决定。

先进行不依赖解析器的轻量预检

PDF 文件通常以 %PDF- 开头,并在文件末尾附近出现 %%EOF。这两个检查只适合快速筛选,不足以证明 PDF 结构完整。

文件头不一定必须位于第 0 个字节。有些 PDF 生成器会在文件头前写入少量二进制数据,因此示例会在前 1024 个字节内查找 %PDF-,而不是只比较开头五个字节。

using System.Text;

namespace PdfPreflightDemo;

public static class PdfSignatureCheck
{
    public static bool HasPdfHeader(Stream stream)
    {
        stream.Seek(0, SeekOrigin.Begin);

        byte[] buffer = new byte[1024];
        int read = ReadAtMost(stream, buffer);

        for (int i = 0; i <= read - 5; i++)
        {
            if (buffer[i] == (byte)'%' &&
                buffer[i + 1] == (byte)'P' &&
                buffer[i + 2] == (byte)'D' &&
                buffer[i + 3] == (byte)'F' &&
                buffer[i + 4] == (byte)'-')
            {
                return true;
            }
        }

        return false;
    }

    public static bool HasEofMarker(Stream stream)
    {
        if (!stream.CanSeek || stream.Length == 0)
        {
            return false;
        }

        long tailLength = Math.Min(4096L, stream.Length);
        stream.Seek(-tailLength, SeekOrigin.End);

        byte[] tail = new byte[(int)tailLength];
        int read = ReadAtMost(stream, tail);

        string tailText = Encoding.ASCII.GetString(tail, 0, read);
        return tailText.Contains("%%EOF", StringComparison.Ordinal);
    }

    private static int ReadAtMost(Stream stream, byte[] buffer)
    {
        int total = 0;

        while (total < buffer.Length)
        {
            int count = stream.Read(
                buffer,
                total,
                buffer.Length - total);

            if (count == 0)
            {
                break;
            }

            total += count;
        }

        return total;
    }
}

这个轻量检查有几个明确边界:

先进行不依赖解析器的轻量预检配图

  • 文件头正确,只说明文件具有 PDF 的外部特征,不代表对象和页面可读。
  • 文件尾部存在 %%EOF,只说明能找到结束标记,不代表交叉引用表没有损坏。
  • 末尾缺少 %%EOF,可能来自上传截断、写入未完成或生成器输出不规范。
  • PDF 支持增量更新,文件中可能有多个 %%EOF,因此不应只搜索一个固定位置。
  • 不能因为文件后面有少量尾随数据就直接判定损坏,合法文件可能包含空白或注释。

因此,预检通过后仍必须执行真正的解析。

使用解析器打开并遍历全部页面

下面的校验器将轻量检查和 iText 解析结合起来。代码中的 PdfTextExtractor 不是为了提取最终业务文本,而是为了让页面内容流至少经过一次解析路径。对扫描型 PDF 来说,提取结果为空是正常的,并不代表文档损坏。

使用解析器打开并遍历全部页面配图

using System.IO;
using iText.Kernel.Exceptions;
using iText.Kernel.Pdf;
using iText.Kernel.Pdf.Canvas.Parser;
using iText.Kernel.Pdf.Canvas.Parser.Listener;

namespace PdfPreflightDemo;

public static class PdfPreflightValidator
{
    public static PdfCheckResult Validate(
        string path,
        PdfValidationOptions? options = null)
    {
        options ??= new PdfValidationOptions();

        if (!File.Exists(path))
        {
            return new PdfCheckResult(
                PdfCheckStatus.FileNotFound,
                0,
                null,
                false,
                "文件不存在。");
        }

        FileInfo fileInfo;

        try
        {
            fileInfo = new FileInfo(path);
        }
        catch (Exception)
        {
            return new PdfCheckResult(
                PdfCheckStatus.Unreadable,
                0,
                null,
                false,
                "无法读取文件信息。");
        }

        if (fileInfo.Length == 0)
        {
            return new PdfCheckResult(
                PdfCheckStatus.EmptyFile,
                0,
                null,
                false,
                "文件大小为 0。");
        }

        if (options.MaxBytes <= 0 || options.MaxPages <= 0)
        {
            throw new ArgumentOutOfRangeException(
                nameof(options),
                "MaxBytes 和 MaxPages 必须大于 0。");
        }

        if (fileInfo.Length > options.MaxBytes)
        {
            return new PdfCheckResult(
                PdfCheckStatus.TooLarge,
                fileInfo.Length,
                null,
                false,
                "文件超过允许的大小限制。");
        }

        bool hasEofMarker = false;

        try
        {
            // 文件应在上传完成并关闭写入流后再进行校验。
            using var stream = new FileStream(
                path,
                FileMode.Open,
                FileAccess.Read,
                FileShare.Read,
                bufferSize: 64 * 1024,
                options: FileOptions.SequentialScan);

            if (!PdfSignatureCheck.HasPdfHeader(stream))
            {
                return new PdfCheckResult(
                    PdfCheckStatus.HeaderMissing,
                    stream.Length,
                    null,
                    false,
                    "文件头不是可识别的 PDF 特征。");
            }

            hasEofMarker = PdfSignatureCheck.HasEofMarker(stream);

            if (options.RequireEofMarker && !hasEofMarker)
            {
                return new PdfCheckResult(
                    PdfCheckStatus.EofMarkerMissing,
                    stream.Length,
                    null,
                    false,
                    "文件尾部没有找到 %%EOF,可能上传不完整或结构不规范。");
            }

            stream.Seek(0, SeekOrigin.Begin);

            // iText 7.2.x 使用 PdfReader 和 PdfDocument 打开 PDF。
            using var reader = new PdfReader(stream);
            using var document = new PdfDocument(reader);

            int pageCount = document.GetNumberOfPages();

            if (pageCount == 0)
            {
                return new PdfCheckResult(
                    PdfCheckStatus.NoPages,
                    stream.Length,
                    0,
                    hasEofMarker,
                    "PDF 可以打开,但没有可用页面。");
            }

            if (pageCount > options.MaxPages)
            {
                return new PdfCheckResult(
                    PdfCheckStatus.PageLimitExceeded,
                    stream.Length,
                    pageCount,
                    hasEofMarker,
                    "PDF 页数超过业务允许范围。");
            }

            if (options.ParsePageContent)
            {
                for (int pageNumber = 1;
                     pageNumber <= pageCount;
                     pageNumber++)
                {
                    PdfPage page = document.GetPage(pageNumber);

                    // 触发页面对象访问。
                    _ = page.GetPdfObject();

                    // 触发内容流和文本解析路径。
                    // 扫描 PDF 可能返回空字符串,这是正常现象。
                    _ = PdfTextExtractor.GetTextFromPage(
                        page,
                        new LocationTextExtractionStrategy());
                }
            }

            string message = hasEofMarker
                ? "文件头、文件尾和页面内容均可由当前解析器读取。"
                : "页面内容可以读取,但未找到 %%EOF,建议保留警告并复核来源。";

            return new PdfCheckResult(
                PdfCheckStatus.Valid,
                stream.Length,
                pageCount,
                hasEofMarker,
                message);
        }
        catch (BadPasswordException)
        {
            // iText 7.2.x 对无法提供密码的加密文件通常进入此分支。
            return new PdfCheckResult(
                PdfCheckStatus.Encrypted,
                fileInfo.Length,
                null,
                hasEofMarker,
                "PDF 需要密码,不能按未加密文档继续解析。");
        }
        catch (PdfException)
        {
            return new PdfCheckResult(
                PdfCheckStatus.MalformedOrUnsupported,
                fileInfo.Length,
                null,
                hasEofMarker,
                "PDF 结构损坏,或当前解析器不支持其中的特性。");
        }
        catch (UnauthorizedAccessException)
        {
            return new PdfCheckResult(
                PdfCheckStatus.Unreadable,
                fileInfo.Length,
                null,
                hasEofMarker,
                "应用没有读取该文件的权限。");
        }
        catch (IOException)
        {
            return new PdfCheckResult(
                PdfCheckStatus.Unreadable,
                fileInfo.Length,
                null,
                hasEofMarker,
                "文件读取失败,可能仍在写入或底层存储不可用。");
        }
        catch (Exception)
        {
            return new PdfCheckResult(
                PdfCheckStatus.MalformedOrUnsupported,
                fileInfo.Length,
                null,
                hasEofMarker,
                "读取或解析过程中发生未分类异常。");
        }
    }
}

这段代码有几个重要设计点。

为什么要遍历所有页面

如果只写下面的代码:

using var reader = new PdfReader(path);
using var document = new PdfDocument(reader);

int pageCount = document.GetNumberOfPages();

它只能证明解析器完成了部分初始化。某些文档的第一页正常,但后面的页面对象、内容流或字体对象已经损坏。只有继续执行:

for (int pageNumber = 1;
     pageNumber <= document.GetNumberOfPages();
     pageNumber++)
{
    PdfPage page = document.GetPage(pageNumber);
    _ = PdfTextExtractor.GetTextFromPage(
        page,
        new LocationTextExtractionStrategy());
}

才更有机会发现后续页面中的异常。

不过,页面遍历仍然不是渲染验收。PDF 可能能被文本解析器读取,却在特定字体、透明度、图像解码或图形操作上无法正常显示。如果业务需要确认“用户看到的页面也能渲染”,还需要增加渲染引擎生成缩略图或页面位图的检查。

为什么不能把所有异常都叫作“损坏”

PdfException 可能对应多种原因:

  • 交叉引用表被截断;
  • 对象编号或偏移量不正确;
  • 页面树指向不存在的对象;
  • 图片或字体流无法解码;
  • 内容流中有当前解析器不能处理的特性;
  • 文档确实损坏。

因此,示例将它们归为 MalformedOrUnsupported,而不是直接向最终用户承诺“文件一定损坏”。如果项目固定使用某个具体版本的解析器,可以根据该版本的异常类型继续细分;当升级 PDF 库时,也应重新核对异常映射。

加密文件应单独处理。它不是损坏文件,用户可能只是需要提供密码。如果业务允许输入密码,应通过受控的密码参数构造 ReaderProperties,不要把密码写入日志、错误信息或校验结果:

var properties = new ReaderProperties()
    .SetPassword(System.Text.Encoding.UTF8.GetBytes(password));

using var reader = new PdfReader(stream, properties);
using var document = new PdfDocument(reader);

密码是否正确、是否允许继续处理,应由业务规则决定。校验器只需要把“需要密码”和“结构解析失败”区分开。

在上传和正式解析之间接入

应用应在文件完成写入后调用校验器。不要一边接收上传流,一边让解析器读取同一个仍在增长的文件,否则很容易得到“文件尾缺失”或“随机读取失败”的结果。

一个简化的接入方式如下:

using PdfPreflightDemo;

string storedPath = uploadStoragePath;

// storedPath 应由服务端生成,不能直接使用用户提交的路径。
PdfCheckResult check = PdfPreflightValidator.Validate(
    storedPath,
    new PdfValidationOptions
    {
        MaxBytes = 100L * 1024 * 1024,
        MaxPages = 2000,
        RequireEofMarker = true,
        ParsePageContent = true
    });

switch (check.Status)
{
    case PdfCheckStatus.Valid:
        // 进入已有的正式解析流程。
        // 例如:提取文本、识别表格或读取业务字段。
        ParsePdfBusinessData(storedPath);
        break;

    case PdfCheckStatus.Encrypted:
        // 提示用户提供密码,或转入人工处理。
        RejectUpload("该 PDF 受到密码保护。");
        break;

    case PdfCheckStatus.HeaderMissing:
    case PdfCheckStatus.EmptyFile:
    case PdfCheckStatus.EofMarkerMissing:
    case PdfCheckStatus.MalformedOrUnsupported:
        RejectUpload("文件不是可处理的完整 PDF,或文件结构无法读取。");
        break;

    case PdfCheckStatus.TooLarge:
    case PdfCheckStatus.PageLimitExceeded:
        RejectUpload("文件超过当前业务允许的处理范围。");
        break;

    case PdfCheckStatus.Unreadable:
        RetryOrReportStorageProblem();
        break;

    default:
        RejectUpload(check.Message);
        break;
}

实际项目中,ParsePdfBusinessData 和 RejectUpload 应替换为已有的服务方法。校验结果中的 Message 可以用于内部日志或管理后台,但不建议把底层解析器的原始异常文本直接返回给上传者,因为异常信息可能包含内部路径、对象编号或依赖库细节。

临时文件建议使用服务端随机名称,并保存到应用专用目录。上传流程至少应满足以下条件:

  • 先将上传流完整写入临时文件,再开始 PDF 校验;
  • 应用层和网关层都设置文件大小上限;
  • 不信任扩展名、MIME 类型和客户端文件名;
  • 校验失败时保留必要的状态记录,但按数据保留策略清理临时文件;
  • 若需要后续人工分析,应将原始文件复制到隔离目录,不要在原文件上直接修复或覆盖;
  • 解析完成后删除临时副本时,应确认业务数据已经持久化。

不同状态的处理方式

下面的表格可以直接用于设计接口返回码或管理后台状态。

校验状态通常原因是否等同于文件损坏建议处理
Valid文件结构和页面内容可被当前解析器读取否进入正式业务解析
HeaderMissingHTML、图片、压缩包或错误文件被改成 PDF 后缀通常不是 PDF拒绝并提示重新上传
EofMarkerMissing上传截断、生成未完成、文件尾缺失高度可疑,但不一定绝对损坏严格业务直接拒绝,宽松业务进入隔离复核
Encrypted文档需要密码或权限口令否提示提供密码,或转人工处理
NoPagesPDF 页面树为空不一定是结构损坏如果业务需要页面,则拒绝
PageLimitExceeded页数超过处理资源或业务上限否要求拆分文件或改用异步处理
MalformedOrUnsupported对象、交叉引用、内容流损坏或特性不支持可能是拒绝、隔离或要求重新导出
Unreadable权限、锁定、存储错误或文件仍在写入否重试或检查存储流程
TooLarge文件超过大小限制否按业务规则拒绝或转异步处理

其中,EofMarkerMissing 值得单独说明。若应用面对的是财务、合同、归档等要求较高的文件,可以保持 RequireEofMarker = true,让缺少结束标记的文件在进入解析器前就被拦截。若应用主要处理来源复杂的历史 PDF,并且解析器具备恢复能力,可以设置为 false,但必须将 HasEofMarker = false 作为警告保存,而不是当作完全正常的文件。

通过示例文件验证结果

验收时不要只用一个能够正常打开的 PDF。至少准备以下几类副本进行测试:

通过示例文件验证结果配图

测试文件构造或来源预期结果
普通文本 PDF含两页可复制文本Valid,页数为 2
扫描型 PDF页面主要是图片,没有文本层通常为 Valid,提取文本为空不应直接失败
改名的 HTML 文件将错误页保存为 sample.pdfHeaderMissing
截断副本只对测试副本删除末尾部分通常为 EofMarkerMissing 或 MalformedOrUnsupported
加密 PDF未提供密码Encrypted
空白页面 PDF文档有页面但没有文字只要页面结构正常,仍可为 Valid
多页后部异常 PDF前几页正常,后续页面对象损坏遍历到异常页时返回 MalformedOrUnsupported
超大或超多页 PDF超过配置限制TooLarge 或 PageLimitExceeded

如果要构造截断文件,只能对测试副本操作,不要直接修改用户上传的原始文件。更安全的测试方式是先复制文件,再对复制品使用文件流调整长度。测试目标是验证状态分支,不是修复原始文档。

还应检查结果是否符合以下预期:

  • 文件后缀不是 .pdf,但文件内容是合法 PDF 时,不应仅因为后缀不同就判定失败;
  • 文件后缀是 .pdf,但内容是 HTML 或图片时,应被基本预检拦截;
  • 只有文本为空的扫描件仍应通过结构校验;
  • 前几页正常、后几页损坏时,完整遍历能够发现异常;
  • 同一个文件重复校验时,页数和状态应保持一致;
  • 上传文件尚未写完时,服务不会把临时的文件尾缺失误认为最终结果。

严格校验、宽松校验和独立检查的取舍

只做文件头和文件尾检查

这种方式消耗很小,适合在上传入口快速筛除明显错误文件,但无法发现页面对象、交叉引用和内容流问题。它只能作为第一道门,不能替代 PDF 解析器。

使用当前业务解析器遍历页面

这是最适合常规业务的方案。校验和后续解析使用同一类 PDF 能力,能提前发现正式解析阶段会遇到的多数问题,也不需要引入额外命令行进程。

缺点是它会消耗 CPU、内存和时间。对大量扫描件、超长文档或来源不可信的公开上传接口,应配合文件大小、页数、并发数和队列限制。

额外使用独立结构检查工具

如果归档或文档治理场景要求更强的结构诊断,可以在隔离环境中使用独立 PDF 检查工具,例如 qpdf 的检查命令:

qpdf --check input.pdf

这类工具通常更适合作为运维诊断或离线复核,不一定适合作为每个 Web 请求的同步依赖。应用需要额外处理进程启动开销、可执行文件部署、超时、退出码、临时路径和命令参数安全问题。它的结构检查结果也不能替代业务所需的文本抽取或页面渲染验证。

如果项目因授权或功能原因更换 .NET PDF 库,应保留现有的文件大小、文件头、文件尾和业务限制层,只替换“打开文档、读取页数、遍历页面内容”的实现。不同库对损坏文件的容错程度不同,不能把某个库能够打开的结果直接当作所有解析器都能正常处理。

资源限制和安全边界

PDF 解析不应被当作普通字符串读取。文件可能包含大量页面、嵌套对象、压缩数据或复杂内容流,即使文件大小不大,也可能消耗较多 CPU 和内存。

实际服务中可以采用以下限制:

  • 设置文件字节数上限;
  • 设置最大页数;
  • 限制同时进行 PDF 解析的任务数;
  • 对公开上传设置单文件解析时间上限;
  • 将特别复杂或来源不明的文件放入后台队列;
  • 对高风险场景使用独立工作进程,而不是仅用 Task.Run 模拟超时;
  • 记录状态、耗时、页数和文件哈希,便于定位重复失败文件。

Task.Run 不能真正终止已经进入底层解析库的工作。如果需要强制限制解析时间,应让独立工作进程执行解析,在超时后终止该进程,并清理其临时目录。对于内部可信文件,可以采用较轻量的线程池方案;对于开放上传入口,则应把资源隔离放在更高优先级。

文件哈希也可以用于确认上传前后是不是同一份文件,但哈希本身不能证明 PDF 没有损坏。只有在存在可信的预期哈希值时,哈希比对才具有完整性验证意义。

经过上述处理后,调用方得到的不再只是“能不能打开”的布尔值,而是包括文件大小、页数、文件尾状态和具体失败类别的结果。正常文件进入正式解析,密码文件进入授权处理,资源超限文件进入业务限制分支,结构异常文件则可以被拒绝或隔离,后续排查不会再与权限、上传未完成和格式不支持混在一起。

A5数据提供香港、美国、日本等地区的物理服务器,涵盖不同CPU、内存及SSD、NVMe存储配置,可用于承载文件上传接口、PDF解析任务和相关业务数据处理;各地资源可结合应用访问区域与负载安排。企业亦提供域名与SSL证书业务,支持网站及接口通过域名提供HTTPS加密连接,为文档上传与处理应用的运行入口和基础资源提供配套选择。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9966.html

相关推荐