OmniTools 0.7.0 配置参数详解

目标：把 OmniTools 0.7.0 的全部配置面逐段逐项讲清——它没有服务端配置文件与环境变量，配置由「构建期（vite/package.json）、托管期（Nginx）、浏览器端（多语言）」三层构成，本篇逐项给出默认值、语义、修改方式与生效验证回显，并沉淀一份全部条目实测生效的生产配置模板。全部验证在 Ubuntu 24.04 + Nginx 1.24.0 实测环境完成。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS x86_64；
• 软件：OmniTools 0.7.0（commit 5f8f4c7），源码 /opt/omni-tools，产物站点根 /var/www/omnitools；
• 构建/运行工具：Node.js 20.20.2、npm 10.8.2（构建期），nginx/1.24.0 (Ubuntu)、systemd 255（托管期）；
• 服务端口：8143；安装过程见 《Ubuntu 24.04 安装 OmniTools 0.7.0 指南》；
• 实测方法：每项配置均以「修改 → 重载/重建 → curl 实测回显」闭环验证，浏览器端行为以源码实读（v0.7.0）加产物核对为据。

二、前置条件

• 已按安装篇完成 OmniTools 0.7.0 部署并能通过 curl http://localhost:8143/ 拿到 200；
• 具备 sudo 权限（改 Nginx 配置与 MIME 表需要）；
• 重新构建需要源码目录 /opt/omni-tools 仍在（构建期配置修改需重建产物；托管期配置只需 reload）。

三、参数查看与修改方式

先建立配置面全景。对 v0.7.0 源码全量检索 import.meta.env 与 process.env. 的结果为零命中，即应用运行时不存在环境变量；也没有服务端配置文件。全部配置分布在三层：

查看方式：

# 构建期配置入口（版本号注入、依赖预构建排除、测试配置都在这个文件）
cat /opt/omni-tools/vite.config.ts
# 应用版本号（构建注入的源头）
grep '"version"' /opt/omni-tools/package.json
# 托管期配置
cat /etc/nginx/sites-available/omnitools.conf
grep -n "javascript" /etc/nginx/mime.types

实测回显（输出节选（实测首尾））：

{
  "name": "omni-tools",
  "description": "This project offers a variety of online tools to help with everyday tasks, ...",
  "version": "0.7.0",
...
server {
    listen 8143;
    listen [::]:8143;
...
8:    application/javascript                           js mjs;

修改流程约定：托管期参数改完必须先 nginx -t 语法校验再 reload（回显见各节）；构建期参数改完执行 npm run build，构建回显以 ✓ built in Ns 收尾才可覆盖部署（sudo cp -r dist/. /var/www/omnitools/）。

四、参数总览

关键差异：构建期参数影响「产物长什么样」，改后要重建；托管期参数影响「请求怎么被服务」，改后 reload 即生效；浏览器端参数打包在产物里，用户感知最强但运维改动最少。

五、核心参数分类详解

5.1 版本号注入：define.__APP_VERSION__ 与 __COMMIT_HASH__

vite.config.ts 的 define 段（v0.7.0 源码实读）把 package.json 的 version 字段与当前 git 短哈希编译成常量注入产物，导航栏据此渲染 v0.7.0 (5f8f4c7) 并把哈希链接到对应源码快照。验证注入已生效：

grep -o "0\.7\.0" /var/www/omnitools/assets/index-*.js | head -2

/opt/omni-tools/dist/assets/index-DwBApu-w.js:0.7.0

要点：版本号唯一来源是 package.json 的 "version"；发版时先改这里再构建，页面版本标识随之更新——这也是判断「线上跑的是哪个构建」最直接的核对点。

5.2 依赖预构建排除：optimizeDeps.exclude 与 Worker 格式

vite.config.ts 中 optimizeDeps: { exclude: ['@ffmpeg/ffmpeg', '@ffmpeg/util'] } 把 ffmpeg 引擎排除出 Vite 的依赖预构建（预构建会把依赖打包成单个 CommonJS 兼容分块，而 ffmpeg 引擎必须以独立 Worker + ESM 方式在浏览器后台线程运行），配套 worker: { format: 'es' } 指定 Worker 产物为 ES 模块格式。实测佐证：构建产物中存在独立的引擎分块 dist/assets/worker-engine-BCCrxWYm-B_ZYudPj.js（688.05 kB，构建日志实测），且全量 228 个产物文件中无 ffmpeg 预打包分块。

⚠️ 注意：这两项是官方为多媒体工具设定的必要构建配置，自研二开时若删掉 optimizeDeps.exclude，视频/音频工具会在运行时报 Worker 初始化错误。

5.3 单元测试配置：test.*（vitest）

同一文件的 test 段定义测试环境（源码实读）：globals: true（测试文件免导入 describe/it）、environment: 'happy-dom'（内存 DOM 实现，不启真实浏览器）、setupFiles: '.vitest/setup'、include: ['**/*.test.{ts,tsx}']。实测全量测试通过：

 Test Files  74 passed (74)
      Tests  695 passed (695)
   Start at  14:37:31
   Duration  13.64s (transform 1.89s, setup 6.11s, collect 21.29s, tests 2.06s, environment 14.82s, prepare 8.55s)

要点：happy-dom 让 695 个用例在 13.64 秒内跑完（真实浏览器方案要慢百倍），这是 CI 门禁的配置基础；端到端测试走独立配置（playwright.config.ts，见命令篇）。

5.4 监听与站点根：listen / server_name / root / index

listen 8143;
listen [::]:8143;
server_name _;
root /var/www/omnitools;
index index.html;

逐项：listen 8143 为 IPv4 监听端口，第二行覆盖 IPv6；server_name _ 表示接受任意 Host（内网按 IP 访问即可）；root 指向部署产物目录；index 指定入口页。验证（实测回显）：

$ curl -sI http://localhost:8143/ | head -6
HTTP/1.1 200 OK
Server: nginx/1.24.0 (Ubuntu)
Date: Wed, 28 Oct 2026 14:32:30 GMT
Content-Type: text/html
Content-Length: 834
Last-Modified: Wed, 28 Oct 2026 14:32:17 GMT

Content-Length: 834 即入口 index.html 的真实大小，可作为站点根指向正确性的快速核对值。

5.5 单页应用路由回退：try_files

location / {
    try_files $uri $uri/ /index.html;
}

语义：先找同名文件，再找同名目录，都未命中则内部重定向到入口页，由前端路由（react-router-dom）接管 URL。这是单页应用的必需项，官方打包制品内同样内置该条（v0.7.0 官方构建描述中的配置补丁实读）。验证：访问一个「不存在的深层路径」（实际是某个工具页的路由）：

$ curl -s -o /dev/null -w "%{http_code} %{content_type}\n" http://localhost:8143/image/compress
200 text/html

返回 200 text/html 而非 404，回退生效。缺这条时刷新任意工具页都会 404（安装篇 8.4 节排障实录）。

5.6 静态资源长缓存：/assets/ 的 expires 与 immutable

location /assets/ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}

语义：构建产物 JS/CSS 文件名带内容哈希（如 index-uZupkAMA.js），内容一变文件名就变，因此可以放心让浏览器缓存 30 天并标记 immutable（浏览器连协商请求都不发）。实测回显：

Cache-Control: max-age=2592000
Cache-Control: public, immutable

max-age=2592000 即 30 天。⚠️ 注意 Nginx 的 add_header 继承规则：一个 location 内只要出现自己的 add_header，就不再继承上一级的 add_header（expires 模块生成的 Cache-Control 不受此影响，二者会叠加）；因此本批把安全响应头放在 server 段（5.10 节）时，/assets/ 内的响应不含该头，属预期行为。

5.7 入口页禁缓存：/index.html 的 no-cache（本批新增项）

入口页本身没有哈希文件名，若被浏览器长期缓存，发新版后用户会拿着旧的 index.html 去加载已经不存在的旧哈希资源而白屏。因此给它单独配 no-cache（允许缓存但每次必须向服务器验证新鲜度）：

location = /index.html {
    add_header Cache-Control "no-cache";
}

实测（默认未配置时该响应无 Cache-Control 头；配置后回显）：

$ curl -sI http://localhost:8143/ | grep -i cache-control
Cache-Control: no-cache

同时确认哈希资源的长缓存不受影响（回显见 5.6 节，max-age=2592000 保持）。这是官方制品未覆盖、自建托管时应补上的一项。

5.8 文本压缩：gzip 三参数

gzip on;
gzip_comp_level 5;
gzip_min_length 1024;
gzip_types text/plain text/css application/javascript application/json image/svg+xml;

逐项：gzip on 总开关；gzip_comp_level 5 压缩级别 1～9（5 是压缩率与 CPU 耗时的平衡点，静态站点由 Nginx 实时压缩，级别再高只增加首字节延迟）；gzip_min_length 1024 小于 1KB 的响应不压（压了反而更大）；gzip_types 补充压缩类型（Nginx 默认只压 text/html，必须显式加 application/javascript 与 application/json 才能覆盖 JS 与语言包）。实测效果（1.1MB 主 JS）：

$ curl -sI -H "Accept-Encoding: gzip" http://localhost:8143/assets/index-uZupkAMA.js | grep -i content-encoding
Content-Encoding: gzip

构建日志标称该文件原始 1,103.56 kB、gzip 270.23 kB（压缩率约 76%），实测传输 271,785 字节，与标称一致。语言包同样受益（application/json 在压缩类型表内）。

5.9 MIME 映射：.mjs → application/javascript

/etc/nginx/mime.types 中需保证该行包含 mjs：

8:    application/javascript                           js mjs;

语义与验证：产物含 4 个 .mjs 模块脚本（PDF 渲染 worker、ONNX 推理分块），默认表只映射 js，.mjs 会按默认类型 application/octet-stream 返回；浏览器对模块脚本执行严格 MIME 校验，直接拒绝执行，表现为 PDF/AI 抠图工具白屏。修复前后实测对比：

修复前：Content-Type: application/octet-stream
修复后：Content-Type: application/javascript

修改方式（官方打包制品在构建时做同一处补丁，v0.7.0 官方构建描述实读）：

sudo sed -i -E "s|(application/javascript\s+)js;|\1js mjs;|" /etc/nginx/mime.types
sudo nginx -t && sudo systemctl reload nginx

5.10 安全响应头：X-Content-Type-Options

add_header X-Content-Type-Options nosniff;

语义：禁止浏览器对响应做 MIME 嗅探改判（配合 5.9 的严格 MIME 校验，杜绝把任何响应当脚本执行的猜测路径）。实测回显：

$ curl -sI http://localhost:8143/site.webmanifest | grep -i x-content
X-Content-Type-Options: nosniff

⚠️ 注意继承规则（同 5.6 节）：该头在 server 段声明，凡自带 add_header 的 location（如 /assets/、/index.html）不继承它；如需全覆盖，在各 location 内重复声明即可。本批按最小改动保留 server 段声明。

5.11 多语言配置：supportedLngs / fallbackLng / lookupLocalStorage / loadPath

语言体系由 src/i18n/index.ts 定义（v0.7.0 源码实读）：supportedLngs 列出 11 种界面语言（en/de/es/fr/pt/ja/hi/nl/ru/uk/zh）；fallbackLng: 'en'（缺词回退英文）；lookupLocalStorage: 'lang'（语言偏好存浏览器 localStorage 的 lang 键）；loadPath: '/locales/{{lng}}/{{ns}}.json'（语言包按「语言/命名空间」两级从产物目录加载，13 个命名空间对应 12 个工具分类加全局 translation）。实测核对：

ls /var/www/omnitools/locales | tr '\n' ' '          # 产物内的语言目录
ls /var/www/omnitools/locales/en | tr '\n' ' '       # en 语言的命名空间文件
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8143/locales/en/translation.json

de en es fr hi ja nl pt ru uk zh
audio.json converters.json csv.json image.json json.json list.json number.json pdf.json string.json time.json translation.json video.json xml.json
200

11 个语言目录、13 个命名空间文件与配置完全对应，语言包 URL 可达。要点：新增或修订翻译改的是 public/locales/<语言>/<命名空间>.json 源文件，改后需重新构建；用户侧语言切换立即生效（写入 localStorage），运维无法集中强制某语言（这是客户端架构的固有特性）。

5.12 PWA 与静态元数据：site.webmanifest / robots.txt / _redirects / gs.js

产物根目录的四类静态元数据（均可直接 curl 验证）：

• site.webmanifest：PWA 安装清单，内容实读为应用名 OmniTools、192/512 两级 maskable 图标、display: standalone、主题色 #ffffff；实测 curl -sI /site.webmanifest 返回 200。注意 Ubuntu 24.04 的 Nginx 默认 MIME 表无 webmanifest 映射，实测返回 Content-Type: application/octet-stream——浏览器对该清单不执行严格校验，安装功能不受影响，若需规范化可在 mime.types 补一行 application/manifest+json webmanifest;；
• robots.txt：搜索引擎抓取规则，实测返回 200；内网部署建议直接改为 Disallow: / 全站禁抓；
• _redirects：内容为 /* /index.html 200，是 Netlify/Cloudflare Pages 类托管平台的 SPA 回退声明，供把产物放到这类平台时使用；自建 Nginx 场景对应 5.5 节的 try_files，二者留一即可；
• gs.js：源码注释实读为 Ghostscript WASM 的占位文件（PS 转 PDF 工具的预留依赖，官方注释明示为 placeholder），当前不参与运行，属于官方预留位，无需配置。

六、生产配置模板

适用场景：内网团队工具站（50 人以下）、2 核 2GB 内存、NVMe 或 SATA SSD、Ubuntu 24.04 + Nginx 1.24，与安装篇方案 A 配套。以下模板的每一项都在 5.4～5.10 节验证过实测回显，可直接整文件落地：

server {
    listen 8143;
    listen [::]:8143;
    server_name _;
    root /var/www/omnitools;
    index index.html;

    add_header X-Content-Type-Options nosniff;

    # 单页应用路由回退（官方制品同款，缺它刷新即 404）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 入口页禁缓存：保证发版后浏览器立即拿到新版本清单
    location = /index.html {
        add_header Cache-Control "no-cache";
    }

    # 带内容哈希的静态资源长缓存（文件名含哈希，内容变即改名）
    location /assets/ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    gzip on;
    gzip_comp_level 5;
    gzip_min_length 1024;
    gzip_types text/plain text/css application/javascript application/json image/svg+xml;
}

配套一次性系统级修改（MIME 表，命令见 5.9 节）与部署节奏（构建产物覆盖站点根后 systemctl reload nginx）。该模板资源占用极低：站点为纯静态托管，实测 Nginx 常驻内存数十 MB 级，服务器剩余内存可全部留给其他业务；磁盘按产物 46MB 计，预留 200MB 足够多版本轮转。

七、常见问题（FAQ）

Q1：发新版后部分用户还是旧版界面？ 入口页被浏览器缓存所致。按 5.7 节给 /index.html 配 no-cache 并 reload；已中招的用户强刷（Ctrl+F5）一次即可恢复。哈希资源（/assets/）不存在此问题，文件名变了 URL 就变了。

Q2：gzip 明明配了，响应里没有 Content-Encoding: gzip？ 按顺序排查三点（均为实测常见根因）：请求未带 Accept-Encoding: gzip（curl 默认不带，需 -H "Accept-Encoding: gzip"，浏览器自动带）；响应体小于 gzip_min_length 1024；响应类型不在 gzip_types 表内（例如 application/json 漏配则语言包不压缩）。验证命令与回显见 5.8 节。

Q3：site.webmanifest 返回 application/octet-stream 有影响吗？ 实测返回 200 且浏览器正常识别（该清单无严格 MIME 校验）；如需规范化按 5.12 节补 application/manifest+json webmanifest; 映射。同类思路适用于一切「类型不重要但路径必须可达」的静态元数据。

Q4：改了构建期配置（vite.config.ts / package.json）为什么不生效？ 构建期参数只在新构建时进入产物：npm run build → sudo cp -r dist/. /var/www/omnitools/ 两步都做完才算生效；只改源码不构建，或构建了不覆盖站点根，线上均无变化。核对版本标识（5.1 节的产物 grep）可确认产物新旧。

八、参考链接

• v0.7.0 vite.config.ts（define/optimizeDeps/worker/test 配置源）：https://github.com/iib0011/omni-tools/blob/v0.7.0/vite.config.ts
• v0.7.0 src/i18n/index.ts（多语言配置源）：https://github.com/iib0011/omni-tools/blob/v0.7.0/src/i18n/index.ts
• v0.7.0 官方构建描述文件（托管适配依据）：https://github.com/iib0011/omni-tools/blob/v0.7.0/Dockerfile
• Nginx add_header 继承规则：https://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header
• Nginx try_files：https://nginx.org/en/docs/http/ngx_http_core_module.html#try_files
• i18next 浏览器语言检测选项：https://www.i18next.com/projects/advanced-configuration
• 本专栏系列篇章：组件定位与选型见 《OmniTools 介绍与选型指南》，从零安装与 systemd 服务化见 《Ubuntu 24.04 安装 OmniTools 0.7.0 指南》，构建测试与维护命令见 《OmniTools 0.7.0 常用 CLI 命令与工具详解》。