Convert to it 生产环境部署最佳实践Nginx 配置与反向代理完整指南【免费下载链接】convertTruly universal online file converter项目地址: https://gitcode.com/GitHub_Trending/convert7/convertConvert to it是一款号称真正通用的在线文件转换工具支持图片、文档、音频、视频等数千种格式之间的转换。它最大的特点是所有转换逻辑都在浏览器端通过 WebAssembly 完成服务器只负责分发静态资源——这决定了它天生适合用Nginx部署也决定了生产环境中 Nginx 配置与反向代理的要点。一、先理解部署形态为什么它只需要一个 Nginx很多在线转换工具需要重型后端来处理上传的文件而 Convert to it 的架构完全不同文件不会上传到服务器整个转换流程在用户浏览器内完成。这意味着生产环境只需要一个nginx:stable-alpine容器来托管构建产物。查看 docker/Dockerfile 可以看到官方镜像采用两阶段构建构建阶段基于oven/bun运行 Vite 构建并执行cache:build生成格式列表缓存首次构建需安装 Chromium因此较慢运行阶段仅将dist产物拷贝到 Nginx 的/usr/share/nginx/html/convert目录二、一键部署Docker Compose 起步仓库的 docker/docker-compose.yml 非常简洁核心就三件事拉取官方预构建镜像、映射8080:80端口、设置restart: unless-stopped自动重启策略。# 在仓库根目录执行 docker compose -f docker/docker-compose.yml up -d启动后服务运行在http://localhost:8080/convert/。注意末尾的/convert/子路径不是笔误——vite.config.js 中base: /convert/决定了整个站点挂载在子路径下这是后面所有 Nginx 配置的地基。三、逐行解析官方 Nginx 配置官方配置见 docker/nginx/default.conf总共只有三条核心指令但每一条都是最佳实践指令作用新手易踩的坑location /→return 302把根路径 302 跳转到/convert/直接访问域名会 404必须先重定向root /usr/share/nginx/html静态资源根目录产物在html/convert子目录而非根目录try_files $uri $uri/ /convert/index.htmlSPA 回退到 index.html缺失回退会导致刷新页面 404第三条try_files是关键Convert to it 是单页应用SPA前端路由没有对应的物理文件任何未命中的请求都必须回退到/convert/index.html由前端接管路由。漏掉这一行是部署后首页能打开、刷新就白屏的最常见原因。四、反向代理把文件转换服务挂到已有 Nginx 后面如果服务器上已有 Nginx 实例更推荐用反向代理方式集成避免端口冲突并方便统一管理 HTTPS。假设你的域名是files.example.com完整配置参考server { listen 443 ssl; server_name files.example.com; # 根路径跳转到子路径与官方 default.conf 行为一致 location / { return 302 /convert/; } # 反向代理到 Convert to it 容器 location /convert/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 大文件友好前端会加载较大的 WASM 二进制 client_max_body_size 200m; proxy_http_version 1.1; proxy_set_header Connection ; } }反向代理场景的 3 个关键检查点WASM 资源路径不要动构建时 vite.config.js 会把 FFmpeg、ImageMagick、Pandoc 等 WASM 二进制统一放到/convert/wasm/下这些资源由同一 location 托管无需单独配置但务必保证代理规则能覆盖/convert/前缀的全部请求。确认 .wasm 的 MIME 类型Nginx 1.21 默认已内置application/wasm旧版本需在types中手动补充否则部分浏览器会拒绝加载 WASM 模块。SPA 回退依然生效容器内部的try_files回退在反代模式下照常工作因为回退发生在被代理的一侧你无需在外层 Nginx 重复配置。五、本地构建自定义镜像可选如果需要自定义构建例如注入自己的版本号使用 docker/docker-compose.override.yml 叠加构建上下文即可docker compose -f docker/docker-compose.yml \ -f docker/docker-compose.override.yml up --build -d该 override 会把镜像构建为convert:dev并传入VITE_COMMIT_SHAdocker构建参数。首次构建预期较慢需安装 Chromium 供 buildCache.js 生成格式缓存后续构建得益于 Docker 层缓存会快很多。六、生产环境部署检查清单通过 HTTPS 访问HTTP 80 端口仅用于 301 跳转根路径location /已配置跳转到/convert/SPA 回退try_files ... /convert/index.html已配置并测试刷新启用 gzip 或 brotli 压缩——前端 JS/WASM 产物压缩率很高为带 hash 的静态资源设置长缓存Cache-Controlindex.html则设为no-cache容器设置了restart: unless-stopped主机重启后服务自动恢复使用固定 tag 的镜像而非latest保证版本可追溯总结Convert to it 的浏览器端转换架构让它的部署异常轻量一个 Nginx 容器 三份配置Dockerfile、default.conf、docker-compose.yml就能上线。掌握base子路径、302 根跳转和 SPA 回退这三个核心点无论是独立部署还是反向代理集成你都能快速把这款通用文件转换工具安全地推到生产环境。【免费下载链接】convertTruly universal online file converter项目地址: https://gitcode.com/GitHub_Trending/convert7/convert创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考