Convert to it构建体系全解ViteBunTypeScript工程化实践【免费下载链接】convertTruly universal online file converter项目地址: https://gitcode.com/GitHub_Trending/convert7/convertConvert to it! 是一款号称真正通用的浏览器端在线文件转换器它的构建体系基于Vite Bun TypeScript三件套实现了 Web 站点、Docker 容器与 Electron 桌面端的多端工程化实践。本文为你完整拆解这套构建体系的设计思路与落地细节帮助前端新手理解一个大型 Web 工程是如何被工程化组织起来的。 项目总览一个能万物互转的文件转换器传统在线转换工具只支持同类格式互转图片转图片、视频转视频且必须把文件上传到服务器。Convert to it! 的做法完全不同所有转换都在浏览器本地通过 WebAssembly 和 JS 库完成文件不出设备且支持跨媒介转换比如把视频转成 PDF。这种全能体验背后是一套清晰的工程结构路径作用src/main.tsWeb 端入口负责 UI 与转换调度src/FormatHandler.ts定义统一的格式处理器接口src/handlers/index.ts注册全部 70 个转换工具Handlersrc/TraversionGraph.ts转换路径图支持多步接力转换vite.config.jsVite 构建配置WASM 资源拷贝、路径别名tsconfig.jsonTypeScript 编译配置buildCache.js基于 Puppeteer 的格式缓存构建脚本docker/Docker 多阶段构建与 Nginx 部署配置test/图遍历与转换冒烟测试 每个转换工具都被抽象成统一的FormatHandler接口见 README 中的贡献指南新增一种格式支持本质上就是往src/handlers/里加一个文件。⚡ 构建工具链为什么是 Vite Bun打开 package.json 可以看到项目所有脚本都以Bun作为运行时而Vite负责打包bun run dev # 启动 Vite 开发服务器热更新 bun run build # tsc 类型检查 Vite 生产构建 bun run cache:build # 构建格式缓存详见下文 bun run docker # 一键 Docker 构建并启动 bun run desktop:start # 构建并运行 Electron 桌面端这个组合有三个工程上的好处Vite 的秒级启动项目依赖了 FFmpeg、ImageMagick、Pandoc 等大量 WASM 重型库冷启动依赖扫描极耗时Vite 的 ESM 原生开发和optimizeDeps机制让开发体验依然流畅。Bun 的统一运行时不仅跑脚本还用Bun.serve内置 HTTP 服务器承载缓存构建流程见 buildCache.js省去额外安装 Node 服务框架。类型门禁build脚本先执行tsc再vite build保证任何类型错误都无法进入产物。 TypeScript 工程化strict 模式下的取舍tsconfig.json 是一份相当教科书式的现代 TS 配置strict: truenoFallthroughCasesInSwitch开启严格模式杜绝常见低级错误moduleResolution: bundlernoEmit: true典型的Bundler 模式——TS 只负责类型检查真正的编译交给 ViteallowJs: true允许直接引入 JS 库如 WASM 胶水代码同时用types补齐类型定义exclude清单将 src/handlers/qoi-fu、src/handlers/espeakng.js 等vendored第三方源码排除在编译之外——这些目录是作为 Git 子模块引入的外部代码不属于项目自身的质量约束范围paths别名通过自定义路径把qoi-fu、qoa-fu指向预转译的 JS 文件巧妙绕过第三方 TS 源码与项目编译选项不兼容的问题。这种对外部代码做隔离对内部代码零妥协的边界划分是大型项目 TS 工程化的常见手法。 Vite 配置精髓WASM 资源的静态拷贝对于以 WASM 为核心的项目vite.config.js 里最重要的不是打包而是资源调度vite-plugin-static-copy批量拷贝 WASMFFmpeg 核心、ImageMagick、Pandoc、typst 渲染器、libopenmpt 音频库……近 20 个.wasm文件及对应 JS 胶水全部被拷贝到产物的wasm/与js/目录运行时按需懒加载optimizeDeps.exclude把ffmpeg/ffmpeg、sqlite-wasm等 WASM 库排除出预构建避免 Rollup 预处理破坏其加载逻辑base: /convert/部署在子路径下Nginx 会将/302 重定向到/convert/前端资源路径与此严格对齐。页面入口 index.html 保持极简——只有script typemodule srcsrc/main.ts一行真正的模块化启动逻辑全部在 src/main.ts 中完成。 亮点工程用 Puppeteer 自动生成格式缓存项目最巧妙的工程实践在 buildCache.js页面首次加载时需要枚举所有 Handler 的支持格式来生成可从 → 可转至格式列表这个过程很慢控制台会打印Built initial format list.。为让用户不再等待构建脚本做了一次自举用Bun.serve起一个静态服务器托管dist/产物用 Puppeteer 启动无头 ChromiumDocker 构建时复用系统 Chromium通过PUPPETEER_SKIP_DOWNLOAD避免重复下载加载页面并监听控制台日志等到Built initial format list.出现后调用页面上的window.printSupportedFormatCache()取出缓存 JSON写入dist/cache.json--minify模式还会做压缩运行时的加载屏就此消失。用构建时的浏览器代替运行时的浏览器计算这是典型的离线预计算优化思路非常值得学习。 Docker 部署多阶段构建 Nginx 瘦身docker/Dockerfile 是标准的多阶段构建模板构建阶段基于oven/bun:1镜像安装 Chromium供 Puppeteer 使用bun install --frozen-lockfile锁定依赖再执行bun run build与bun run cache:build运行阶段切换到仅几十 MB 的nginx:stable-alpine只把dist/拷贝进去彻底剥离构建工具链。配套的 docker/nginx/default.conf 做了两件事把根路径 302 到/convert/子路径并为 SPA 提供try_files回退。本地自测时可用 docker/docker-compose.override.yml 覆盖为本地构建镜像docker compose -f docker/docker-compose.yml -f docker/docker-compose.override.yml up --build -d服务将在http://localhost:8080/convert/启动端口映射见 docker/docker-compose.yml。️ Electron 桌面端一套代码三端复用得益于纯 Web 技术栈桌面端几乎是白送的src/electron.cjs 注册了自定义app://特权协议把 URL 请求映射回本地dist/文件实现了类 HTTP 的本地资源加载含路径穿越防护bun run desktop:build通过环境变量IS_DESKTOPtrue触发 Vite 的差异构建package.json 中的build字段由 electron-builder 接管一键产出 Windows NSIS 安装包、macOS DMG 与 Linux AppImage。Web 站、容器、桌面 App 共用同一份dist/产物——这正是 Vite TS 工程化带来的一次构建多端分发红利。✅ 测试体系两级测试策略test/ 目录采用两级结构见 README 的 Testing 章节项目级冒烟测试如 test/TraversionGraph.test.ts 验证转换图遍历算法test/commonFormats.test.ts 校验格式定义Handler 级单元测试放在 test/handlers/配合 test/MockedHandler.ts 这个假处理器可以脱离真实 WASM 依赖单独测试解析、序列化等纯逻辑。 快速上手本地开发环境搭建# 1. 克隆仓库必须带子模块否则缺少部分依赖 git clone --recursive https://gitcode.com/GitHub_Trending/convert7/convert # 2. 安装 Bun 后安装依赖 bun install # 3. 启动开发服务器 bunx vite⚠️ 若修改后页面没反应很可能是格式缓存在作怪——可禁用cache.json验证参考 README 的 Local development 章节。 总结Convert to it! 的构建体系给出了一个大型前端工程的优秀范本Vite解决依赖极重项目的打包与开发效率问题Bun统一运行时让脚本、服务器、打包一气呵成TypeScript strict bundler 模式在严格与实用之间取得平衡Puppeteer 自举缓存展示了构建时做重活的巧妙思路多阶段 Docker 自定义协议 Electron让同一份产物通吃三端。理解这套体系你对Web 工程化四个字应该会有全新的认识 【免费下载链接】convertTruly universal online file converter项目地址: https://gitcode.com/GitHub_Trending/convert7/convert创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考