主题
架构总览
一句话结构
一个仓库、四个构建产物、一台 nginx、三个域名。所有计算在前端,服务器只负责发文件。
┌─────────────────────────────┐
浏览器 ──HTTPS──►│ nginx 1.28 (121.43.28.40) │
│ emphant.com → /var/www/emphant
│ emphant.com/m/ → /var/www/emphant/m
│ docs.emphant.com→ /var/www/emphant-docs
│ blog.emphant.com→ /var/www/emphant-blog
└─────────────────────────────┘没有数据库、没有 API、没有容器编排。发布就是「把一批静态文件放到对的目录,然后 reload nginx」。
四个构建产物
| 产物 | 构建工具 | 输出 | 路由方式 |
|---|---|---|---|
| pc-web | Vite 多页 | dist/,100+ 个 index.html | 目录即 URL,/text/word-counter/ |
| mobile-web | Vite 单页 | dist/,一个 index.html + assets | hash 路由,/m/#/t/text/word-counter |
| docs-site | VitePress | dist/,每页一个 HTML | cleanUrls,/guide/quick-start |
| blog-site | VitePress | dist/ + rss.xml | cleanUrls,/posts/<slug> |
为什么主站是多页而不是单页
工具站的核心资产是搜索流量。单页应用的所有工具共用一个 URL 和一个 title,搜索引擎只能收录首页,长尾词全部丢掉。
多页方案下:
- 每个工具独立 URL、独立 title / description / canonical;
- 页面里有静态的使用步骤与 FAQ,不执行 JS 也能读到正文;
- 结构化数据(
WebApplication、FAQPage、BreadcrumbList)按页生成; - 单个工具改动只影响自己那一页,缓存粒度更细。
代价是 HTML 页面多、构建时间长(约 1~2 分钟),但这是静态站,完全可以接受。
为什么手机版是单页
手机版的入口只有一个:用户从分享链接或首页进来,在同一套界面里切换工具。hash 路由让它在 /m/ 子目录下不需要任何服务端 rewrite;base='./' 让产物可以挂到任意子目录或 CDN。
它复用了电脑版的组件与文案数据,只重写移动体验差的工具,详见 双端复用机制。
数据层
工具的定义全部是普通 JS 对象,构建时被三个地方消费:
gen-pages.mjs:生成 HTML、sitemap、栏目页;main.js:首页与栏目页的卡片列表;mobile-web:通过@pc读取同一份数据,生成手机版列表。
因此新增工具只需要改一处数据,三端同时生效。
运行时依赖
工具里用到的第三方库都随构建打进 chunk,没有 CDN 依赖:
| 库 | 用途 | 体积控制 |
|---|---|---|
qrcode | 二维码生成 | 单独 chunk vendor-qrcode |
pinyin-pro | 汉字转拼音 | 单独 chunk vendor-pinyin |
opencc-js | 简繁转换 | 单独 chunk vendor-opencc |
jsqr | 二维码识别 | 按需 import |
pdf-lib / jszip | PDF 合并拆分 | 按需 import |
smol-toml / js-yaml | 数据格式转换 | 按需 import |
只有用户打开对应工具时才会下载对应 chunk。
边界
- 不托管用户文件:没有上传接口,所有处理在浏览器内存里完成;
- 不做账号体系:没有登录态,也就没有用户数据需要保护;
- 不承诺结果正确:彩票、测算类工具都明确写了「仅供娱乐 / 参考」。