免费开源的文件在线预览终极方案：kkFileView 让工程图纸和办公文档触手可及-平芜编程栈

免费开源的文件在线预览终极方案：kkFileView 让工程图纸和办公文档触手可及

【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView

kkFileView 是一个基于 Spring Boot 的万能文件在线预览开源项目，一句话概括就是：把文件 URL 丢给它，浏览器里直接打开。无需给终端用户装 AutoCAD、Office 或 WPS，DWG 图纸、Word、Excel、PPT、PDF、压缩包、3D 模型甚至 DICOM 医学影像，一个服务全部搞定。

一、不用它的时候，文件预览有多痛

车间看图纸：一张 DWG 落在现场，工人得先借一台装了 AutoCAD 的台式机才能打开；万一 AutoCAD 版本比图纸新，还可能直接报格式不兼容。
跨软件办公：客户发来一份 PPT，你本机 WPS 版本老，字体全跑版；发给同事再看，排版又不一样，最后谁也不知道哪版是"对的"。
压缩包不敢点开：对方发了个 zip 说"资料在里面"，你先下载、再解压、再挨个打开确认没有 exe——一套流程走完，二十分钟没了。

kkFileView 的解法很直接：在服务端把文件转成浏览器能渲染的形态（PDF、图片、SVG、HTML），前端只管展示。

二、kkFileView 是怎么干活的

把它理解成一家餐厅：前台是统一入口/onlinePreview，点单（传一个 Base64 + URL 编码的文件地址）后，FilePreviewFactory这个"调度员"按文件后缀把单分给不同的"档口"——

Office 档口：用 JODConverter 驱动 LibreOffice 进程池，把 docx/pptx 转成 PDF 或逐页图片（转换输出走 officePicture.ftl 这类预览模板）；
CAD 档口：靠 aspose-cad 把 DWG 转成 SVG/PDF/TIF，所以图纸在浏览器里可以无损缩放；
视频档口：JavaCV + FFmpeg 转码，把 rm、avi 这些浏览器不认的格式转成 mp4；
压缩档口：sevenzipjbinding 解压后生成目录树，点里面的文件直接嵌套预览。

所有转换结果都有缓存，同样的文件第二次打开秒出。Office/CAD 这类重转换类文件，预览分两种模式，这是新手最容易懵的地方：

特性	图片模式	PDF 模式
转换产物	每页一张 PNG/JPG	整个文档一个 PDF
加载速度	快（分页加载，大图也不卡）	慢（要整份转换完）
精度	中（像素渲染，放大有锯齿）	高（矢量无损，可搜索文本）
适用场景	文件大、网络差	内网、需要精确查看标注

⚠️ 5.0 版本起，Office 默认已经切到 PDF 模式，且默认隐藏了模式切换按钮，想找回旧体验要显式改配置（后面讲）。

三、格式能力全景

README 支持列表扫一遍，覆盖面远超"文件预览"这个词给人的印象：

办公文档：doc/docx、xls/xlsx（含 xlsm）、ppt/pptx、csv、以及 WPS 的 wps/dps/et，还有 OpenOffice/LibreOffice 全套 odt/ods/odp
图纸工程：dwg、dxf、dwf、step、iges、ifc、brep 等 CAD 格式，以及 obj、3ds、gltf、fbx 等 3D 模型
图文设计：psd、eps、svg、wmf、tiff、drawio、bpmn 流程图、xmind
通用文件：pdf、ofd、rtf、epub、eml/msg 邮件、txt/md/xml 等所有纯文本、zip/rar/7z 压缩包
媒体影像：mp3/wav/mp4 音频视频、avi/rm/mkv 等转码视频、dcm 医疗影像
图片：jpg、png、gif、webp、heic 等，支持缩放、翻转、镜像

Excel 有个彩蛋：xlsx 默认走纯前端解析（SheetJS），服务器基本不干活，大表格预览压力直接卸到浏览器上。

四、5 分钟跑起来

前置环境：JDK 21+（注意，5.0 起不再支持低版本 JDK）、Maven 3.5+。

克隆源码：

git clone https://gitcode.com/GitHub_Trending/kk/kkFileView cd kkFileView

打包（跳过测试，核心代码在 server 模块）：

mvn -q -pl server -DskipTests package

启动服务：

java -jar server/target/kkFileView-5.0.0.jar

浏览器打开http://localhost:8012，看到首页即成功。拖一个文件上去，或者直接用/onlinePreview接口预览你服务器上的文件。

两个依赖说明：Linux 脚本启动模式会自动装 LibreOffice，Windows 发行包内置（仓库里的 LibreOfficePortable 就是它），Mac 需要手动装。想省事的直接拉官方 Docker 镜像keking/kkfileview-base，Dockerfile 里能看到构建方式。

五、性能关键配置都在哪里

所有可调项集中在 application.properties，全部支持环境变量覆盖，集群部署很友好。

转换线程与超时——这是最影响吞吐的两类参数：

配置项	默认值	说明
`pdf.max.threads`	10	PDF 转换最大并发线程
`pdf.timeout.small/medium/large`	90 / 180 / 300 秒	按文件规模分档的超时阈值
`cad.thread`/`cad.timeout`	5 线程 / 90 秒	CAD 转换并发与超时
`office.plugin.server.ports`	2001,2002	多个 LibreOffice 端口做负载均衡
`office.quality`	80	图片模式渲染质量（1-100）

PDF 智能 DPI 分级是个很实用的设计：0-50 页用 150 DPI，100-200 页降到 96 DPI，超 500 页直接 72 DPI——大文件不再硬撑着高清晰度拖垮内存，小文件也不糊。

经验法则：文件越大、页数越多，优先加线程和放宽超时，而不是无脑堆内存；视频转码（media.convert）特别吃 CPU，不需要的场景建议直接关掉。

六、集成进你自己的系统

接入的核心就一件事：把文件 URL 做Base64 + URL 双重编码，拼到/onlinePreview?url=后面。Java 侧最小示例：

String fileUrl = "http://your-cdn/drawings/mechanical.dwg"; String encoded = URLEncoder.encode( Base64.getEncoder().encodeToString(fileUrl.getBytes(UTF_8)), StandardCharsets.UTF_8).replace("+", "%20"); String previewUrl = "http://kk-server:8012/onlinePreview?url=" + encoded;

拿到previewUrl直接window.open或塞进 iframe 就行。生产环境建议开启kk.key（API 密钥）防刷，用 nginx 反代时记得设base.url。

七、谁在真实使用它

机械制造：车间和工艺人员浏览器直接看图纸，不用申请 AutoCAD 账号；
建筑设计院：多专业互审时，结构图、电气图统一在线看，杜绝"我看的还是旧版"；
企业网盘/OA：作为预览后端嵌进去，替代原来"下载才能打开"的原始体验。

八、避坑指南（必读）

⚠️ 这些坑都是真实会踩的，坦诚列出来：

CAD 转换用的是 aspose-cad 测试版：README 里写得明白"商用请自行购买"。内部用没问题，上商业产品记得评估授权。
JDK 必须是 21+：还按老教程装 JDK 8 的话，打包直接失败。
trust.host默认拒绝一切外部文件预览：防 SSRF 设计，想预览自己 CDN 上的文件必须配白名单（5.0 起支持通配符和 CIDR，老配置升级后要重新核对生效范围）。
delete.source.file默认是 true：转换完会删掉本地源文件省磁盘，如果你的源文件是唯一的，务必先改。
5.0 默认行为变了：Office 默认 PDF 模式且隐藏切换按钮，想保留旧版图片优先体验要设office.preview.type=image和office.preview.switch.disabled=false。
视频转码是资源黑洞：配置里官方都加了"非常消耗 CPU 和内存"的警告，低配机器慎开。