简介：一套基于ASP.NET的在线文档预览实现代码，面向Web开发人员，解决在网页中直接预览PDF、PPT、Word、Excel而无需下载或安装Office软件的问题。资源基于ASP.NET Web API构建，主控制器中的CourseViewOnLine方法演示了核心转换流程：先读取Files目录下的源文件，根据pdf与Office扩展名分别调用PdfToHtml和OfficeDocumentToHtml方法，借助Aspose.Cells与Aspose.Slides等组件将文档转换为HTML页面，并输出到viewFiles目录。压缩包大小约31.93MB，主要包含C#源码文件、HTML模板文件等，代码结构清晰、转换路径完整，便于二次开发时理解在线预览的底层逻辑。目前已有1214人参与学习浏览，适合需要快速集成文档预览功能的ASP.NET项目开发者参考，无论是OA系统附件预览还是在线课程资料展示，都能从这套代码中获得直接的实现思路与改造基础。
1. 在线预览 Office 文件，为什么不能只靠浏览器硬开
“asp.net实现在线查看(预览)pdf，ppt，word,excel文件”这个需求，我在企业 OA 和 ERP 项目里被问过很多次。用户不想下载一份 Word 合同或者 Excel 报表到本地再打开，而是希望页面里点一下直接翻页、缩放、打印；对开发者的要求只有一个：不装 Office 也能看。这里有个反直觉的结论：PDF 可以靠浏览器原生打开，但 Word、PPT、Excel 不行，它们会被当成附件下载，或者弹出一堆乱码。所以真正要做的不是“渲染”，而是先把 Office 转成 PDF，再统一交给 PDF 渲染引擎。这篇笔记就是围绕这条链路，给出 ASP.NET 下能直接抄的落地做法，以及我踩过的几个坑。
2. 技术选型：四条渲染路径与一套统一出口
2.1 PDF 可以直接渲染，Office 三件套要先转 PDF
先定调：PDF 是预览的“通用语言”。浏览器对 PDF 的支持已经相当好，Chrome 和 Edge 都能直接打开，但直接调用原生 PDF 查看器有一个问题——你没法控制它，没法禁用下载、没法统一工具栏、也没法在移动端保证一致的手感。所以对于 ASP.NET 项目，我更倾向于用 PDF.js 这类前端库来做渲染，页面完全用<canvas>绘制，工具栏可以自己做。
Office 这边 Word、Excel、PPT 是二进制或 OOXML 格式，浏览器没有原生解析能力。你让用户点击一个 .docx，浏览器会把它下载下来而不是打开。就算用 iframe 嵌进去，也只能看到下载提示。因此常见做法是先在后端把这三类文件转成 PDF，转换之后前端只需要处理一种格式。这个“先转 PDF，再统一预览”的思路，能让整个系统的维护成本低很多：前端逻辑只有一套，后端渲染入口也只有一个。
直接用 iframe 嵌原始 PDF 也不是不行，但受浏览器控制，右键菜单里自带的保存、下载没法屏蔽。PDF.js 对我们来说最大的价值，是能拿到页面渲染完成事件，在加载层显示进度，并且完全由我们的代码控制展示逻辑。比如不想让用户下载，原生查看器右键照样可以保存；用 PDF.js 渲染到 canvas，没有下载按钮就真的没有入口。
2.2 在线预览服务与本地转换的取舍
在 ASP.NET 里做在线预览，最容易想到的是调用第三方在线预览服务。微软 Office Online Viewer 和 Google Docs Viewer 都可以把 Office 文件的 URL 带过去生成预览页，代码量可能不到十行。但你得考虑数据走到第三方服务器带来的隐私问题，尤其 OA 里的合同、工资表这类文件，等于把机密交给了外部。内网部署的项目更是直接卡死，因为服务器可能连不上公网。所以我不建议企业级系统把在线服务作为首选，只适合没有保密要求的公开资料库。
本地方案里，选项主要有 Aspose、Spire、NPOI 和 LibreOffice。Aspose 是商业库，渲染保真度最高，Word、Excel、PPT 分别有对应的组件，但授权费不便宜；Spire 也有免费版，但功能限制多；NPOI 只能读写字符合格式到 Excel，并不能真正“排版输出”，更做不了 PPT。LibreOffice 是开源软件，提供一个 headless 命令行模式，可以用soffice --headless --convert-to pdf把 Office 文件转 PDF，免费、能部署在服务器上，缺点是转换效果受字体影响较大。从性价比和落地速度来看，我一般建议先用 LibreOffice 跑通全链路，遇到排版不达标再局部换成 Aspose。
下面这个表是我做选型时常用的对比：
| 方案 | 成本 | 转换效果 | 内网部署 | 维护成本 | 适合场景 |
|---|---|---|---|---|---|
| 微软 Office Online | 免费 | 高 | 不行 | 低 | 公网公开文档 |
| Google Docs Viewer | 免费 | 高 | 不行 | 低 | 公网临时预览 |
| Aspose | 付费 | 很高 | 可以 | 中 | 合同、报表等正式文档 |
| LibreOffice | 免费 | 一般 | 可以 | 中 | 内部资料、非核心文档 |
| NPOI | 免费 | 低 | 可以 | 低 | 只能处理数据，不适合排版 |
2.3 为什么我最后选了 LibreOffice 加 PDF.js
整套选型组合是这样的：前端用 PDF.js 渲染 PDF；后端用 LibreOffice headless 把 Word、Excel、PPT 转换成 PDF；转换结果按文件哈希缓存；预览时通过 ASP.NET 的输出 Action 将 PDF 流返回给前端。这个组合的好处是每层职责单一，出现问题容易排查。预处理环节可以独立跑任务，预览接口只负责读文件，互不干扰。
如果项目预算充足、对排版保真有硬要求，可以把 LibreOffice 替换成 Aspose：Word 用 Aspose.Words，Excel 用 Aspose.Cells，PPT 用 Aspose.Slides。但要注意，三套组件的 API 风格不一样，不能用一个通用方法一次性处理，我会在后面代码里分别写清楚。LibreOffice 适合先把业务跑起来，等用户开始抱怨“这个表格转换后错位了”，再针对那类文件换 Aspose，成本上是可控的。
2.4 文件类型识别与处理顺序
上传的文件可能后缀是错的，也可能同名不同格式，所以不能只看扩展名。我一般先读文件头几个字节判断真实类型，再决定走哪条转换路径。PDF 走直接预览，Word、Excel、PPT 走转换，其他格式直接拒绝或提示不支持。处理顺序上，先把 PDF 请求直接放行，再对 Office 文件做转换，最后把转换结果写入缓存目录。这样日志里能清晰看到每类文件走了哪条分支，排查问题时少猜。还可以在文件表里加一列file_type，转换前统一规整，避免后来新增 TIF、CAD 文件时把逻辑全堵在一个分支上。
3. 落地实现：ASP.NET 里的完整预览链路
预览页入口通常放在 GridView 文件列表上，点“预览”按钮用 jQuery 插件弹出一个 Modal，内部 iframe 指向预览 Action。列表页不用刷新，js 只需要传文件 ID 给后端。
3.1 用 PDF.js 渲染 PDF 的最小页面
先来一个最小的预览页。假设你的后端已经能返回 PDF 流，前端页面用一个<canvas>来画第一页：
<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <title>在线预览</title> <script src="~/scripts/pdf.min.js"></script> <script src="~/scripts/pdf.worker.js"></script> </head> <body> <canvas id="pdfCanvas" style="width: 100%; border: 1px solid #ccc;"></canvas> <script> // 设置 worker 路径，否则 pdf.js 会从默认地址加载 worker，容易被浏览器拦截 pdfjsLib.GlobalWorkerOptions.workerSrc = '/scripts/pdf.worker.js'; // 这里的 pdfUrl 由后端 Action 返回，同域可避免跨域问题 const pdfUrl = '/Preview/GetPdf?id=' + '@ViewBag.FileId'; let pdfDoc = null; pdfjsLib.getDocument(pdfUrl).promise.then(pdf => { pdfDoc = pdf; return pdf.getPage(1); }).then(page => { const canvas = document.getElementById('pdfCanvas'); const ctx = canvas.getContext('2d'); // 单位是 PDF 点，这里按 1.5 倍缩放，保证文字清晰度 const viewport = page.getViewport({ scale: 1.5 }); canvas.width = viewport.width; canvas.height = viewport.height; const renderContext = { canvasContext: ctx, viewport: viewport }; return page.render(renderContext).promise; }).catch(err => { console.error('PDF 加载失败：', err); }); </script> </body> </html>这段代码的核心是pdfjsLib.getDocument拿 PDF 数据，然后用page.render画到 canvas。pdf.worker.js必须和主库放在同一个目录，并显式指定workerSrc，否则在部分浏览器下会报“Worker was not registered”。scale参数决定渲染清晰度，1.5 适合屏幕浏览，打印场景可以提高到 2。
真正落地时，pdfUrl不要直接用文件名，而是用一个文件 ID 去后端取，这样既能做权限校验，也避免了路径穿越。PDF.js 还支持把整个 viewer 页面嵌入项目，但那个页面自带下载、打印按钮，如果你要控制权限，最好还是自己写这个精简版。对于前端 PDF 解析，我建议固定用 pdf.js 的稳定版，不要频繁升级，它偶尔会调整 worker 加载方式。
3.2 用 LibreOffice headless 把 Office 转 PDF
后端转换是这条链路的重点。先用 LibreOffice 命令行：
public static string ConvertOfficeToPdf(string sourcePath, string outputDir) { // 假设 LibreOffice 安装路径为 C:\Program Files\LibreOffice\program\soffice.exe var sofficePath = @"C:\Program Files\LibreOffice\program\soffice.exe"; var psi = new ProcessStartInfo { FileName = sofficePath, Arguments = string.Format("--headless --convert-to pdf --outdir \"{0}\" \"{1}\"", outputDir, sourcePath), CreateNoWindow = true, UseShellExecute = false, RedirectStandardError = true, RedirectStandardOutput = true }; using (var process = Process.Start(psi)) { process.WaitForExit(60000); // 最长等 60 秒，防止大文件卡死 if (!process.HasExited) { process.Kill(); throw new TimeoutException("LibreOffice 转换超时"); } return Path.Combine(outputDir, Path.GetFileNameWithoutExtension(sourcePath) + ".pdf"); } }注意几点：参数里的--outdir和目标文件路径都加了双引号，这是为了兼容路径里的空格和中文。WaitForExit(60000)表示 60 秒后还不退出就直接 Kill，避免一个异常文件把服务器拖住。LibreOffice 转换时要求输出目录必须存在，否则会静默失败，所以调用前先Directory.CreateDirectory(outputDir)。返回的 PDF 文件名其实是源文件名去掉扩展名加.pdf，最好在调用侧确认文件确实生成了，再去做缓存。
如果换成 Aspose，逻辑就变成了分类型调用：
// Word 转 PDF var wordDoc = new Aspose.Words.Document(sourcePath); wordDoc.Save(pdfPath, Aspose.Words.SaveFormat.Pdf); // Excel 转 PDF var workbook = new Aspose.Cells.Workbook(sourcePath); workbook.Save(pdfPath, Aspose.Cells.SaveFormat.Pdf); // PPT 转 PDF var presentation = new Aspose.Slides.Presentation(sourcePath); presentation.Save(pdfPath, Aspose.Slides.Export.SaveFormat.Pdf);这段代码看着简单，但坑也不少。Aspose 的 Excel 转换默认会按整个工作簿输出，而 LibreOffice 只输出当前活动工作表，后面我在避坑章节细说。另外三套组件都要求电脑上安装对应授权，没有 License 时输出 PDF 会带水印。Aspose 对字体也很敏感，服务器上没装中文字库，转出来的 PDF 中文是方框。
注意：Aspose 的 Excel 转换默认会按整个工作簿输出，而 LibreOffice 只输出当前活动工作表，如果你在对比两者的输出，这是第一个要确认的差异。
3.3 预览页面的文件流输出与权限控制
转换好的 PDF 存放在缓存目录，预览时通过一个专门的 Action 返回：
[HttpGet] public ActionResult GetPdf(string id) { // 根据 id 查数据库得到文件缓存路径 var filePath = docService.GetCachedPdfPath(id); if (string.IsNullOrEmpty(filePath) || !System.IO.File.Exists(filePath)) { return HttpNotFound("预览文件不存在，请重新上传"); } // 校验当前登录用户是否有权访问该文件 if (!permissionService.HasPermission(id, User.Identity.Name)) { return new HttpUnauthorizedResult(); } Response.Clear(); Response.ContentType = "application/pdf"; Response.AddHeader("Content-Disposition", "inline; filename=preview.pdf"); Response.TransmitFile(filePath); return new EmptyResult(); }这段代码有两个细节。一是Content-Disposition必须是inline，这样浏览器才会在页面内打开；如果写成attachment，用户点击预览又变成了下载。二是用Response.TransmitFile而不用File方法，是把文件直接写到响应流，不需要把整个文件读进内存，大文件场景内存占用更低。还需要在web.config里确认maxAllowedContentLength足够大，否则超过限制的文件会被 IIS 直接拦下。
权限控制这里容易被忽略。预览接口和下载接口是两个入口，很多人只在下载接口做了校验，结果预览接口照样能通过 URL 随手访问其他文件。我一般会用文件 ID 做白名单，拿到 ID 后查一次数据库权限，再返回文件。同时，上传环节也要做内容安全校验，可以在全局过滤器里检查 PDF 文件头，不能只信任扩展名，防止上传带异常脚本的文件绕过后续流程。
4. 参数调优与性能：大文件、并发和缓存
4.1 转换超时与任务队列
LibreOffice 转换不是瞬间完成的，一个 10MB 的 PPT 可能需要几十秒。如果在请求线程里同步等，用户的浏览器会一直转圈，时间一长还得面对 IIS 请求超时。常见做法是把转换任务丢到后台队列里，第一次点击预览时先返回“转换中”状态，异步转换完成后再通知前端刷新。队列可以用内存里的ConcurrentQueue，也可以直接挂到数据库表中。
用SemaphoreSlim控制并发数量是必要的一步：
private static readonly SemaphoreSlim ConvertSemaphore = new SemaphoreSlim(2); public static async Task<string> ConvertWithLimitAsync(string sourcePath, string outputDir) { await ConvertSemaphore.WaitAsync(); try { return ConvertOfficeToPdf(sourcePath, outputDir); } finally { ConvertSemaphore.Release(); } }限制并发为 2，是因为 LibreOffice 每个转换进程会占用几百 MB 内存，同时跑 10 个进程很容易把服务器打爆。SemaphoreSlim让后来的请求排队等待，而不是直接并发。如果你用的是 Aspose，不用限制到 2，但也要看服务器内存规格，建议压测时盯着任务管理器。转换超时参数不只影响用户体验，还影响服务器健康，我一般把 60 秒作为硬上限，超过就取消并记录文件路径，方便回头复现。
4.2 缓存策略：按文件哈希做缓存
同一个文件被预览一百次，不应该转换一百次。解决办法是给原始文件算一个 MD5 或 SHA1，转出的 PDF 以哈希值命名。上传时如果发现缓存目录里已存在相同哈希的 PDF，直接复用。数据库里可以记录三列：source_hash、preview_path、created_at。
public static string ComputeSha1(string filePath) { using (var stream = System.IO.File.OpenRead(filePath)) { using (var sha1 = System.Security.Cryptography.SHA1.Create()) { var hash = sha1.ComputeHash(stream); return string.Concat(hash.Select(b => b.ToString("x2"))); } } }计算在文件上传时做一次，把哈希存进数据库。预览时先查缓存，命中就直接返回 PDF 路径，不命中再触发转换。缓存目录建议按月份分文件夹，例如preview/202506/，方便定期清理。清理策略我习惯保留 30 天，超过 30 天的 PDF 删除，源文件还在就下次转换时重新生成。注意清理时不要删除还在被预览请求引用的文件，可以加一个“最近访问时间”字段，被访问过的文件自动续期。
4.3 内存回收与进程复用
LibreOffice 转换进程有个特点：每次调用soffice都会启动一个新的 LibreOffice 实例，转换完退出。如果异常退出没有 Kill 干净，进程残留会占内存。我建议在转换完成后检查进程是否还在，并且设置WaitForExit超时；实在不行就定期重启服务器或者用任务计划清理。对 Aspose 来说，Workbook、Document、Presentation都需要在 finally 里 Dispose，否则文件句柄不释放，会导致删除缓存 PDF 时提示文件被占用。
另外 .NET 站点本身也要注意内存回收。预览大 PDF 时，Response.TransmitFile是异步流式输出，不会占用太多托管内存；但如果你用File.ReadAllBytes再Response.BinaryWrite，一个 200MB 的 PDF 会瞬间吃满内存。所以代码里尽量用流。如果希望复用 LibreOffice 实例，可以启动一个soffice监听服务，用--accept参数接受远程控制，但配置复杂度高，容易引入更多不稳定因素。小型系统不需要，直接命令行最稳，遇到问题 Kill 进程重来就是。
5. 避坑/常见问题/排查：预览环节的 5 个经典翻车现场
5.1 PDF 中文乱码，浏览器预览空白
现象：上传的 Word 转成 PDF 后，预览页面上中文全是方框，或者整个 PDF 白屏。
原因：服务器缺少中文字体，LibreOffice 转 PDF 时找不到字形，只把占位符画上去；另一种情况是 pdf.js 的 worker 路径配置错误，JS 没加载到 worker，渲染失败但控制台提示不明显。常见于云服务器精简版系统。
解决：先在服务器装字体，Linux 装fonts-wqy-zenhei、fonts-wqy-microhei，Windows 把宋体、黑体拷到字体目录；然后检查workerSrc是否指向了可访问的静态 JS 文件。我一般会在转换日志里把 PDF 第一页截图保存下来，一眼就能看出是不是字体问题。如果只是预览白屏，优先看浏览器控制台有没有 404 或跨域报错。
5.2 Word 转换后排版错乱，表格跑出页面
现象：Word 里好好的表格，转换后列宽变了，表格右侧跑出页面边界；有的文档最后一页死活删不掉，预览里多一张空白页。
原因：转换引擎的分页逻辑和 Word 不一样，特别是表格里嵌图片、页边距自定义、公式对象的时候。LibreOffice 对 OOXML 支持不算 100% 完整，复杂文档更容易翻车。还有字体不一致导致行高变化。以前用 POI 做 Word 处理时，设置表格列宽既要写 grid 又要写 cell，漏一个，转 PDF 时照样跑版。
解决：尽量要求用户使用标准模板，不要用未安装的字体；转换前统一设置页边距，或者直接接入 Aspose 来渲染这类关键文档。Aspose.Words 处理表格更接近 Word 原生。如果 Word 最后一页是段落标记导致，可以在源文档里删掉多余空段落再转。最终判定标准要看预览截图，不能只看代码返回成功。这类文档如果用户必须用源文件打印，预览只能用于核对，不能作为最终排版标准。
5.3 PPT 字体和动画丢失，预览和原文件不一样
现象：PPT 转 PDF 后动画效果全部消失，只有静态页面；部分艺术字和图标错位。
原因：PPT 转 PDF 本来就是静态化，动画是 PPT 专有行为，PDF 不承载动画。字体没有嵌入时，播放环境没有安装对应字体，预览效果就差很多。
解决：预览目标不是替代原文件，只是让人快速浏览内容，所以动画丢失可以接受。要减少错位，可以在服务器上安装 PPT 用到的字体包，或者用 PowerPoint 转出 PDF 后再预览。如果用户必须看动画，就不要走 PDF 方案，而是用 HTML5 播放器直接解析 PPTX，但这类组件成熟度不高，成本会上升。折中方案是预览 PDF，同时保留原文件下载，用户想看动画就下载原文件。
5.4 Excel 多工作表只显示第一张
现象：Excel 有多个 Sheet，用 LibreOffice 转出来的 PDF 只有当前活动的第一个 Sheet 内容。
原因：LibreOffice 默认只导出活动工作表，没有像 Excel 那样把整个工作簿逐页输出。Aspose.Cells 默认行为是全部输出，但设置不对时也可能只出第一页。
解决：LibreOffice 转换 Excel 时加参数--convert-to pdf:Calc MS Excel 2007 XML不一定有用，更可靠的方式是直接改用 Aspose.Cells，它会按工作簿生成多个 PDF 页面。如果你的 LibreOffice 版本支持，也可以在转换前用脚本激活所有工作表，但维护麻烦，我一般直接换组件。也可以按 Sheet 拆分成多个 PDF，前端加一个 Sheet 切换按钮，不过预览体验会割裂。记得在测试用例里放一个 3 到 4 个 Sheet 的 Excel，回归时一眼就能看出有没有修好。
5.5 服务器内存暴涨，预览几个文件就卡死
现象：连续预览四五个大文件后，服务器内存升到 90% 以上，再点预览整个网站没响应。
原因：一个是 LibreOffice 转换进程没有及时回收，多个进程叠加；另一个是 ASP.NET 站点进程把大 PDF 读进了内存，比如用了File.ReadAllBytes。我之前遇到过预览 50MB PDF 直接把 w3wp 干崩溃的。
解决：转换进程限制并发，给WaitForExit设超时；输出文件用Response.TransmitFile流式返回；对 PDF 文件大小设上限，超过 100MB 的文件只给下载不给预览。不要把转换和预览放在同一个请求里做同步等待，这是最容易触发内存飙升的动作。监控指标建议记录转换进程数和 w3wp 工作集，一旦某个阈值持续超过，就该检查是不是有残留进程。定期用自动化脚本检查空闲进程，把残留的soffice进程清理掉。
6. 进阶：打印、移动端适配与验证
6.1 给预览页加打印按钮
在线预览绕不开打印需求。pdf.js 本身没有快捷打印按钮，但可以在页面里加一个按钮触发window.print()，然后给预览区域加打印样式：
@media print { body * { visibility: hidden; } #pdfCanvas, #pdfCanvas * { visibility: visible; } #pdfCanvas { position: absolute; left: 0; top: 0; width: 100%; } }这样用户点打印，打印出来的内容只有 PDF 画布。要注意打印清晰度，scale至少要 2，否则打印出来的文字有锯齿。最好在打印按钮旁边放一个“预览前几页”的提示，避免用户没等渲染完就点打印，打出来空白。
6.2 移动端适配与 UA 判断
手机浏览器上直接打开预览页，canvas 的宽度可能超出一屏。我的习惯是响应式处理：页面容器宽度设为屏幕宽度，canvas用 CSS 缩放；同时根据移动端 UA 把scale降低到 1.0，减少 GPU 负担。pointer: coarse媒体查询也可以用来区分触屏，不过后端判断 UA 更简单。
private bool IsMobile() { var ua = Request.UserAgent?.ToLower() ?? ""; return ua.Contains("iphone") || ua.Contains("android") || ua.Contains("ipad"); }移动端还得处理手势缩放，如果允许用户放大，就给 canvas 外包一层带touch-action: pan-x pan-y的容器；不允许就直接禁用浏览器的双指缩放，防止预览页面被缩放后操作混乱。其实对于移动端预览，很多场景只需要看第一页大概内容，所以默认只渲染第一页、加上一页页翻页按钮，比一次性加载整个 PDF 更友好。
6.3 验证方案与监控
我最后的习惯是准备三个测试文件：一个带复杂表格的 Word，一个多 Sheet 的 Excel，一个带图片和格式的 PPT，放在自动化测试目录里。每次部署预览功能，先跑这三类文件，检查转换耗时和输出 PDF 大小；再用脚本访问预览接口，确认返回Content-Type是application/pdf，内容长度跟缓存文件一致。这样能挡住大部分回归问题。
在线预览这个功能，坑不在概念，都在细节。现在每次动转换参数或升级组件，我都会先看一遍转换日志里有没有soffice异常，再看预览页的渲染时间，最后才敢发布到生产环境。希望这个方案能帮你少走点弯路，有需要的地方照着改就能用。
本文还有配套的精品资源，点击获取
