在 Hostinger 共享主机上部署 BentoPDF:构建、.htaccess 路由与 WASM 安全头配置实战指南
在 Hostinger 共享主机上部署 BentoPDF:构建、.htaccess 路由与 WASM 安全头配置实战指南
BentoPDF 是一个纯前端、隐私优先的 PDF 工具箱(The Privacy First PDF Toolkit),所有处理都在浏览器本地完成,构建产物是静态文件,因此可以直接部署到 Hostinger 这类共享主机。本篇指南将带你完成从本地构建、File Manager 上传,到编写完整 .htaccess(安全头、缓存、压缩、多语言路由)的全过程,并深入讲解为什么 WASM 工具需要 COOP/COEP 头、为什么 .mjs 必须声明正确的 MIME 类型,以及子目录部署时 BASE_URL 与 RewriteBase 的联动关系。读完你可以在 Hostinger 上稳定运行 BentoPDF 的全部 PDF 功能,并具备排查 WASM 加载失败、LibreOffice 转换卡住、刷新 404 等常见问题的能力。
前置条件
在开始之前,确认你的环境满足以下要求:
- Hostinger 主机套餐:任意支持文件管理器(File Manager)访问的套餐即可,无需 SSH/终端权限;
- 本地 Node.js:用于在本地完成构建(构建脚本依赖 Node 与 npm);
- 域名解析:已绑定到 Hostinger 的根域名(
yourdomain.com)或准备使用子目录(yourdomain.com/pdf-tools/)。
一个值得注意的事实是:BentoPDF 是纯静态站点,没有数据库、没有后端服务(见 自托管指南 中的系统要求说明),这正是它能跑在共享主机上的根本原因。构建后的 dist 目录就是完整的可部署站点。
第一步:构建项目
将仓库克隆到本地并执行构建:
git clone https://gitcode.com/gh_mirrors/be/bentopdf.git
cd bentopdf
npm install
npm run build
构建完成后,产物位于 dist 文件夹。
从 package.json 的脚本定义可以看到,npm run build 并非一次简单的打包,而是一条完整的流水线:先执行 scripts/generate-blog.mjs 生成博客页面、scripts/generate-static-tool-links.mjs 生成工具站内链接,然后 tsc 做 TypeScript 类型检查,再执行 vite build 完成核心打包,随后依次运行 scripts/enhance-seo-pages.mjs、scripts/generate-i18n-pages.mjs(生成多语言目录)、scripts/generate-sitemap.mjs、scripts/generate-security-headers.mjs 和 scripts/seo-audit.mjs。
其中两点与 Hostinger 部署直接相关:
scripts/generate-i18n-pages.mjs会在dist下生成语言子目录(如dist/de/、dist/zh/),这解释了后续.htaccess中语言路由规则存在的意义;vite.config.ts内置了vite-plugin-compression(Brotli 压缩质量 11、gzip 压缩级别 9,仅对超过 1 KB 的 js/mjs/json/css/html/wasm/svg 生效),因此dist中会同时存在.gz与.br预压缩文件——这就是.htaccess必须处理"防止双重压缩"的原因。
第二步:上传到 Hostinger
根域名部署
- 登录 Hostinger 账户;
- 进入 File Manager → public_html;
- 删除(或先备份)该目录下的既有文件;
- 将本地
dist文件夹的全部内容上传到public_html。
注意上传的是 dist 的内容,而不是 dist 文件夹本身,否则站点会变成 public_html/dist/... 的嵌套结构,导致路由与资源路径全部失效。
子目录部署
如果希望部署在子目录(例如 yourdomain.com/pdf-tools/):
- 使用正确的 base URL 构建:
BASE_URL=/pdf-tools/ npm run build
BASE_URL 会同时影响两个环节(见 vite.config.ts):一是 Vite 的 base 配置(base: (process.env.BASE_URL || '/').replace(/\/?$/, '/')),决定资源引用的根路径;二是 rewriteHtmlPathsPlugin 插件,它会扫描构建产物中所有 HTML 文件,把 href、src、content 属性中以 / 开头的路径统一改写为以 BASE_URL 开头的路径。所以如果忘记在子目录部署时设置 BASE_URL,页面能打开但 JS/CSS 资源会 404。
- 在 Hostinger 中创建目录:
- 进入 File Manager → public_html
- 新建文件夹:
pdf-tools
- 将
dist的全部内容上传到public_html/pdf-tools/。
第三步:创建 .htaccess 文件
在部署目录的根位置(public_html 或 public_html/pdf-tools/)创建 .htaccess 文件。该文件本质上与仓库根目录自带的 .htaccess 同源(仓库自带的用于 bentopdf.com 官方站),你可以直接参考、按需修改域名后使用。
::: warning 重要
子目录部署时,必须把 RewriteBase / 改为 RewriteBase /pdf-tools/(或你的实际目录名),否则所有重写规则的路径基准都会错位。
:::
下面按段落逐块解析这个 .htaccess 的作用与原理。
1. 安全头(WASM 运行的关键)
<IfModule mod_headers.c>
Header always set X-Frame-Options "SAMEORIGIN"
Header always set X-Content-Type-Options "nosniff"
Header always set X-XSS-Protection "1; mode=block"
Header always set Referrer-Policy "strict-origin-when-cross-origin"
Header always set Permissions-Policy "geolocation=(), microphone=(), camera=()"
# REQUIRED for soffice.js (SharedArrayBuffer)
Header always set Cross-Origin-Opener-Policy "same-origin"
Header always set Cross-Origin-Embedder-Policy "require-corp"
</IfModule>
前五项是常规安全加固。最后两项是本项目部署的重中之重:
Cross-Origin-Opener-Policy: same-origin(COOP)Cross-Origin-Embedder-Policy: require-corp(COEP)
BentoPDF 的 Office 文件转换(Word/ODT/Excel/PPT → PDF)依赖 LibreOffice WASM,而 LibreOffice WASM 运行时需要 SharedArrayBuffer。浏览器只有在页面处于 cross-origin isolated(跨源隔离)状态时才会开放 SharedArrayBuffer,而跨源隔离的充要条件就是所有响应同时携带 COOP 与 COEP 头,并且页面运行在安全上下文(HTTPS 或 http://localhost)中。
这一点在开发与预览环境中同样被强制:vite.config.ts 的 server.headers 与 preview.headers 都设置了 Cross-Origin-Opener-Policy: same-origin 和 Cross-Origin-Embedder-Policy: require-corp,与生产 .htaccess 保持一致,确保本地调试与线上行为一致。此外构建流程中的 scripts/generate-security-headers.mjs 还会根据 WASM CDN 源自动生成带 CSP 的 Nginx 头文件(security-headers.conf),可见安全头是该项目贯穿开发、构建、部署全链路的一等公民。
部署完成后可以在浏览器 DevTools Console 验证:
console.log(window.crossOriginIsolated); // 应为 true
console.log(typeof SharedArrayBuffer); // 应为 "function"
2. 浏览器缓存
<IfModule mod_expires.c>
ExpiresActive On
ExpiresByType image/jpeg "access plus 1 year"
ExpiresByType image/png "access plus 1 year"
ExpiresByType image/gif "access plus 1 year"
ExpiresByType image/webp "access plus 1 year"
ExpiresByType image/svg+xml "access plus 1 year"
ExpiresByType image/x-icon "access plus 1 year"
ExpiresByType font/woff2 "access plus 1 year"
ExpiresByType font/woff "access plus 1 year"
ExpiresByType font/ttf "access plus 1 year"
ExpiresByType text/css "access plus 1 month"
ExpiresByType application/javascript "access plus 1 month"
ExpiresByType application/wasm "access plus 1 year"
ExpiresByType application/gzip "access plus 1 year"
ExpiresByType text/html "access plus 0 seconds"
</IfModule>
策略要点:静态资源(图片、字体、WASM)缓存一年;CSS/JS 缓存一个月(因为构建产物文件名带 hash,内容变化后 URL 自然变化,旧缓存不会命中新文件);HTML 缓存 0 秒,保证每次访问都能拿到最新页面,避免多语言/工具页面更新后用户看到旧版本。
3. 压缩(防止双重压缩)
SetEnvIfNoCase Request_URI "\.gz$" no-gzip
SetEnvIfNoCase Request_URI "\.br$" no-gzip
SetEnvIfNoCase Request_URI "\.wasm$" no-gzip
<IfModule mod_deflate.c>
AddOutputFilterByType DEFLATE text/plain
AddOutputFilterByType DEFLATE text/html
AddOutputFilterByType DEFLATE text/xml
AddOutputFilterByType DEFLATE text/css
AddOutputFilterByType DEFLATE application/xml
AddOutputFilterByType DEFLATE application/xhtml+xml
AddOutputFilterByType DEFLATE application/rss+xml
AddOutputFilterByType DEFLATE application/javascript
AddOutputFilterByType DEFLATE application/x-javascript
AddOutputFilterByType DEFLATE application/json
AddOutputFilterByType DEFLATE image/svg+xml
AddOutputFilterByType DEFLATE font/woff
AddOutputFilterByType DEFLATE font/ttf
</IfModule>
这里的三行 SetEnvIfNoCase 是防止双重压缩:由于构建阶段已经用 vite-plugin-compression 生成了 .gz/.br 预压缩文件,如果服务器再对这些文件做一次 gzip,浏览器会拿到"压缩过的压缩文件"而无法解压。.wasm 同样被排除,因为 WASM 通常已经高度优化且很多 WASM 文件本身就以 gzip 形式存储(见下文 soffice.wasm.gz)。
4. MIME 类型与特殊文件处理
AddType application/javascript .js .mjs
AddType application/wasm .wasm
AddType font/woff2 .woff2
AddType font/woff .woff
AddType image/webp .webp
# Handle soffice.wasm.gz correctly
<FilesMatch "soffice\.wasm\.gz$">
ForceType application/wasm
Header set Content-Encoding "gzip"
Header set Cross-Origin-Resource-Policy "cross-origin"
Header append Vary Accept-Encoding
</FilesMatch>
# Handle data.gz
<FilesMatch "soffice\.data\.gz$">
ForceType application/octet-stream
Header set Content-Encoding "gzip"
Header append Vary Accept-Encoding
</FilesMatch>
这一节是容易踩坑的地方,两个关键点:
.mjs→application/javascript:BentoPDF 打包的 PDF 查看器(见public/pdfjs-viewer/、public/pdfjs-annotation-viewer/下的viewer.mjs、pdf_viewer.mjs等)是 ES Module 文件。许多服务器(包括部分 Apache 发行版)的默认mime.types没有.mjs映射,会回退成application/octet-stream,而浏览器对模块脚本执行严格 MIME 检查,直接拒绝执行,表现为签名/表单填写等工具的 iframe 一片空白;- 预压缩的 LibreOffice WASM:
public/libreoffice-wasm/下的soffice.wasm.gz与soffice.data.gz是 gzip 压缩存储的 WASM 与数据文件。它们必须被ForceType强制为application/wasm/application/octet-stream,同时必须带上Content-Encoding: gzip响应头,浏览器才会在下载时自动解压。如果这个头缺失,浏览器会收到原始 gzip 字节而无法解析(控制台出现expected magic word 00 61 73 6d, found 1f 8b 08 08一类的错误——00 61 73 6d是 WASM 魔数,1f 8b是 gzip 魔数)。
5. 重定向与路由
# Canonical WWW (update domain as needed)
RewriteCond %{HTTP_HOST} ^bentopdf\.com [NC]
RewriteRule ^(.*)$ https://www.bentopdf.com/$1 [L,R=301]
# Force HTTPS
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
# Remove trailing slash (except for language root directories)
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI} !^/(de|es|zh|zh-TW|vi|it|id|tr|fr|pt)/$
RewriteCond %{REQUEST_URI} (.+)/$
RewriteRule ^ %1 [R=301,L]
# Existing files/dirs - serve directly
RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^ - [L]
- www 规范化:把裸域
bentopdf.com301 到www.bentopdf.com(部署到自己的域名时记得改成自己的域名,或按需删掉这段); - 强制 HTTPS:所有非 HTTPS 请求 301 到 HTTPS——这不仅是安全要求,更是
SharedArrayBuffer的硬性前提(安全上下文要求); - 去尾斜杠:目录之外的 URL 去掉结尾
/,避免重复内容;但对语言根目录(如/de/)保留,因为语言路由依赖尾斜杠; - 先放行真实文件/目录:如果请求能命中磁盘上的真实文件或目录,直接返回,不再进入后续重写——这是所有静态站点重写规则的标准前置条件。
5.1 语言路由
# Supported languages: de, es, zh, zh-TW, vi, it, id, tr, fr, pt
# English has no prefix - served from root
# English prefix redirects to root (for SEO consistency)
RewriteRule ^en/?$ / [R=301,L]
RewriteRule ^en/(.+)$ /$1 [R=301,L]
# Language prefix root (e.g., /de/ -> /de/index.html)
RewriteCond %{DOCUMENT_ROOT}/$1/index.html -f
RewriteRule ^(de|es|zh|zh-TW|vi|it|id|tr|fr|pt)/?$ /$1/index.html [L]
# Language prefix with path (e.g., /de/merge-pdf -> /de/merge-pdf.html)
RewriteCond %{DOCUMENT_ROOT}/$1/$2.html -f
RewriteRule ^(de|es|zh|zh-TW|vi|it|id|tr|fr|pt)/([^/]+)/?$ /$1/$2.html [L]
BentoPDF 采用静态多语言目录方案:英语无前缀(直接从根目录提供),其余语言使用前缀目录。scripts/generate-i18n-pages.mjs 在构建时按语言生成 dist/<lang>/ 下的完整页面副本,.htaccess 的作用就是把 /{lang}/ 和 /{lang}/{tool} 这类无扩展名的友好 URL 映射到对应的 index.html 或 {tool}.html 实际文件。
两条规则都带 -f 条件:只有目标文件真实存在时才重写,否则放行交给后续规则(避免把 404 请求错误吞掉)。注意 en 前缀会 301 到根目录——这是为了 SEO 一致性,避免同一页面出现两个 URL 造成重复内容。
5.5 文档路由(VitePress)
RewriteCond %{REQUEST_URI} ^/docs
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME}\.html -f
RewriteRule ^(.*)$ $1.html [L]
如果 dist 中包含了 docs 目录(构建脚本 npm run build:with-docs 会调用 scripts/include-docs-in-dist.js 把 VitePress 文档并入 dist),这段规则负责把 /docs/... 下的无扩展名路径追加 .html。若你的部署不需要文档站,可保留也可删除,不影响工具功能。
6. 为存在的文件追加 .html 扩展名(仅根级别)
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME}.html -f
RewriteRule ^([^/]+)$ $1.html [L]
这是非 SPA 路由的核心:BentoPDF 的每个工具都是真实存在的静态 HTML 文件(见 src/pages/ 下的 merge-pdf.html、split-pdf.html 等 130+ 个页面),用户访问 /merge-pdf 时,此规则将其内部重写为 /merge-pdf.html。它只匹配单段路径([^/]+),多段路径交由语言路由或文档路由处理。
7. 错误页面
ErrorDocument 404 /404.html
所有未命中任何规则与文件的请求统一返回自定义 404 页面(对应仓库根目录的 404.html),而不是 Apache 默认的错误页。
子目录 .htaccess 示例
部署在 yourdomain.com/pdf-tools/ 时,把上述内容做如下调整(其余段落保持不变):
RewriteBase /pdf-tools/
# ... (内容同上,但按需更新路径) ...
# Language prefix root
RewriteCond %{DOCUMENT_ROOT}/pdf-tools/$1/index.html -f
RewriteRule ^(de|es|zh|zh-TW|vi|it|id|tr|fr|pt)/?$ /pdf-tools/$1/index.html [L]
# Language prefix with path
RewriteCond %{DOCUMENT_ROOT}/pdf-tools/$1/$2.html -f
RewriteRule ^(de|es|zh|zh-TW|vi|it|id|tr|fr|pt)/([^/]+)/?$ /pdf-tools/$1/$2.html [L]
# Root level .html extension
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME}.html -f
RewriteRule ^([^/]+)$ $1.html [L]
ErrorDocument 404 /pdf-tools/404.html
子目录部署有三个地方必须一致:构建时的 BASE_URL=/pdf-tools/、.htaccess 的 RewriteBase /pdf-tools/、以及语言/404 规则中的 /pdf-tools/ 前缀。这三者任一不一致,都会表现为资源 404 或路由错乱。如果你用的是 VitePress 托管或 Nginx,可以对照 Nginx 部署指南 与 Apache 部署指南 查看对应平台的等价配置。
故障排查
WASM 文件不加载
确认 .htaccess 中 MIME 类型已正确声明:
AddType application/wasm .wasm
如果浏览器仍报 WASM 404,多半是上传时 qpdf.wasm、soffice.wasm.gz 等大文件没有完整上传(见下方"文件上传限制")。另外 WASM 请求的响应头应能看到 Content-Type: application/wasm。
LibreOffice 工具不工作
安全头对 SharedArrayBuffer 至关重要:
Header always set Cross-Origin-Opener-Policy "same-origin"
Header always set Cross-Origin-Embedder-Policy "require-corp"
排查步骤:
- 在浏览器 DevTools → Network 中检查每一个响应是否都带有这两个头;如果头没有生效,联系 Hostinger 支持启用
mod_headers模块(共享主机默认一般已启用,但个别套餐可能关闭); - 确认页面是通过 HTTPS 访问的。
http://localhost可用于本机测试,但http://192.168.x.x这类局域网 HTTP 地址不算安全上下文,浏览器会直接禁用SharedArrayBuffer——这种场景没有纯头部方案,必须上 HTTPS; - 若控制台出现
expected magic word 00 61 73 6d, found 1f 8b 08 08,说明soffice.wasm.gz缺少Content-Encoding: gzip头,检查<FilesMatch "soffice\.wasm\.gz$">段落是否完整; - 最终验证:DevTools Console 运行
console.log(window.crossOriginIsolated),应输出true。
完整的排查思路与各平台对照,可参考 自托管指南 中的"Common Issues"章节。
刷新页面 404
确认 .html 扩展名规则与语言路由配置正确。BentoPDF 使用静态 HTML 文件而非 SPA 路由,所以每次刷新都必须让服务器把无扩展名 URL 重写到真实文件:
# Language routes serve actual files from language directories
RewriteCond %{DOCUMENT_ROOT}/$1/$2.html -f
RewriteRule ^(de|es|zh|zh-TW|vi|it|id|tr|fr|pt)/([^/]+)/?$ /$1/$2.html [L]
# Root level pages
RewriteCond %{REQUEST_FILENAME}.html -f
RewriteRule ^([^/]+)$ $1.html [L]
刷新 404 的常见原因:上传遗漏了某个语言目录、RewriteBase 与部署目录不一致,或 .htaccess 文件编码/换行异常(建议用纯文本编辑器保存为 UTF-8、LF 换行)。
文件上传限制
Hostinger 的文件管理器对单次上传有大小限制,而 BentoPDF 的 dist 中含有体积较大的 WASM 文件(qpdf.wasm、LibreOffice 的 soffice.wasm.gz / soffice.data.gz 等)。如果批量上传失败:
- 将大文件单独上传,不要一次拖入整个目录;
- 可以先用压缩包整体上传到
public_html,再在 File Manager 中解压(注意解压时确认目录层级正确); - 上传完成后抽查关键文件(如
qpdf.wasm、soffice.wasm.gz)的字节数与本地一致,避免静默截断。