企业官网建设流程全解析

kkFileView 如何用 dev.sh 以资源热加载方式启动服务并修改前端预览模板

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

当你需要调整 kkFileView 的前端预览页面——修改 Freemarker 模板（.ftl）或预览页用到的 CSS/JS，并希望在浏览器里马上看到效果，而不是每次改动都重新打包 jar——仓库内置的dev.sh就是为此准备的启动方式。它会以资源热加载（resource hot reload）方式运行 Spring Boot 服务，使server/src/main/resources/web/下的模板改动在刷新页面后即可生效。适用前提：本机已安装 JDK 21 与 Maven（pom.xml 中java.version为 21，且dev.sh通过 Maven 启动应用）。

启动前的准备

• JDK 21：pom.xml 将java.version、maven.compiler.source/target均设为 21，编译与运行都需要对应版本。
• Maven：dev.sh 最终执行的是mvn spring-boot:run，需要mvn在 PATH 中可用。脚本自身会做一件事：如果设置了JAVA_HOME，会把$JAVA_HOME/bin加到 PATH 前面，确保用你指定的 JDK。
• Office 组件（按需）：README 快速开始说明，Office 文件预览依赖 OpenOffice 或 LibreOffice——Windows 下已内置，Linux 脚本启动模式会自动安装，Mac OS 下需要手动安装。如果你只改模板界面而不实际转换 Office 文档，可以跳过这项。

用 dev.sh 启动服务

在仓库根目录执行：

./server/src/main/bin/dev.sh

脚本内容很短，逐行看它的动作（见 dev.sh）：

#!/bin/bash set -e ROOT_DIR=$(cd "$(dirname "$0")/../../../.." || exit 1; pwd) SERVER_DIR="$ROOT_DIR/server" if [ -n "$JAVA_HOME" ]; then export PATH="$JAVA_HOME/bin:$PATH" fi cd "$SERVER_DIR" || exit 1 mvn spring-boot:run \ -Dspring-boot.run.addResources=true \ -Dspring-boot.run.jvmArguments="-Dfile.encoding=UTF-8 -Dspring.config.location=$SERVER_DIR/src/main/config/application.properties"

三个关键点：

1. -Dspring-boot.run.addResources=true：AGENTS.md 明确把这套组合（spring-boot:run+addResources=true+application.properties）描述为带资源热加载的启动方式，并建议在修改前端模板或 CSS/JS 时优先使用dev.sh，而不是反复重建 jar。
2. 配置文件被显式固定：-Dspring.config.location指向 application.properties。AGENTS.md 特别提醒：仓库默认指向application.properties，如果某环境改用test.properties属于环境级覆盖；改动配置"不生效"时，先确认实际启动命令用的是哪个配置文件。
3. 模板加载配置：application.properties中 FreeMarker 相关配置为spring.freemarker.template-loader-path = classpath:/web/、spring.freemarker.cache = false、spring.freemarker.suffix = .ftl。模板缓存关闭，配合 dev.sh 的热加载启动，server/src/main/resources/web/下的.ftl改动无需重新打包即可被重新读取。

确认服务启动成功

启动后访问http://127.0.0.1:8012/（AGENTS.md 给出的默认本地地址）。按 README.cn.md 快速开始的说明，看到首页界面即代表服务启动成功。端口默认 8012，可通过环境变量KK_SERVER_PORT覆盖（见application.properties中server.port = ${KK_SERVER_PORT:8012}），覆盖后请改用对应端口访问。

修改前端预览模板

模板位于server/src/main/resources/web/目录。AGENTS.md 列出的主要预览模板与用途如下：

修改前有一条来自 AGENTS.md 的硬性建议：先确认预览流程实际选用的是哪一个模板，不要假设两个相似的预览页面共享同一套 CSS 或行为。例如 PDF 预览走pdf.ftl，单张图片走picture.ftl，Office 图片模式走officePicture.ftl，它们是相互独立的页面。

选定模板后直接编辑保存，然后刷新浏览器中的预览页面即可看到效果——这就是选择 dev.sh 的原因：不必执行mvn package再重启。

验证修改生效

AGENTS.md 给出的预览相关改动验证清单（按适用项逐条核对）：

1. 目标 URL 返回200；
2. 选中的模板是预期中的那一个；
3. 目标 UI 元素或样式改动确实存在于渲染后的 HTML 中。

如果改动触及 PDF 预览的兼容性逻辑，AGENTS.md 还给出了定向 Java 测试的示例命令：

mvn -q -pl server -Dtest=PdfViewerCompatibilityTests test

需要跑端到端检查时，见 tests/e2e/README.md。

边界与替代启动方式

• 外部文件预览受限：application.properties中trust.host默认未配置白名单，配置注释说明不配置时系统默认拒绝所有外部文件预览请求，当前默认值仅用于本机测试。如果你用外部地址的 URL 验证预览页却打不开，先检查这一项，再怀疑模板改动。
• 非热加载路径：mvn -q -pl server -DskipTests package用于打包 jar（AGENTS.md 的 Jar build 一节）。这是部署或整体验证用的构建方式，日常改模板时不应走这条路，否则每次都要重新打包重启。

按上述路径，一次典型操作是：./server/src/main/bin/dev.sh启动 → 访问http://127.0.0.1:8012/确认首页 → 定位到实际被选用的.ftl并修改 → 刷新预览页，按"200 / 模板正确 / 改动在渲染 HTML 中"三条核对结果。

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