---
title: "全球化 H5 前端架构实战手记：Vue 3.5 + Vite 5 如何跑出“快、稳、省”"
date: 2026-02-14
description: "白皮书写得再漂亮，线上卡一下用户照样骂。这篇是踩过坑后的交代：Vue 3.5 + Vite 5 当底盘，Unplugin 替你省 import 和路由冲突；UnoCSS 管住样式胖；Pinia 按域拆，别养“宇宙级 Store”；Axios + i18n 把区域和安全藏在底下一层。读起来没那么“史诗”，干起活来舒服得多。"
canonical_url: "https://yijinlee.com/articles/article-5"
tags:
  - "H5 架构"
  - "Vue 3.5"
  - "Vite 5 工程化"
  - "DDD 状态管理"
  - "原子化 CSS"
  - 移动端适配
  - 国际化多语言
  - 前端性能优化
topic: "架构之道"
---

### 写在前面：别拿架构当 PPT

全球化 H5 这事，听起来高大上，干起来全是细活：弱网一抖、语言一切、安卓老机一白屏，用户才不管你是不是 “全栈愿景 2.0”。

我们给自己定的底线很土：**快、稳、省**——少写废话代码，少在线上丢人。口号还是那句老话：**“Less is More, Speed is King.”** 翻译得俗气一点：**机器能干的别手搓，能写进约定的别靠吼。**

**诚实一刻：** 再漂亮的目录，也治不好 “需求截止前一晚才说要兼容某款机”。架构只负责把牌码整齐，不负责替全员背锅。

---

### 一、什么叫 “成功”？别拿 “感觉挺好” 糊弄人

评审会上只认三件事，能对上就行：

**对人的交代：** 样板少、接入快，新人别花三天搞清楚 “import 究竟从哪来”。

**对机的交代：** 首屏顺、交互跟手，用户不会觉得你在让他干等。

**对债的交代：** 半年后还能改，别赌原作者永远秒回消息。

---

### 二、几块板怎么拼：从构建到 “出国门”

#### 1. 构建：Vite 5 + Unplugin，专治手写烦死了

选 Vite 5，图的是在 **速度** 和 **生态** 之间少赌一点。下面三件属于 “花了就回本” 的类别。

**文件路由：** 用 `unplugin-vue-router`。文件即路由，目录即边界；合并分支时少点心梗，比啥都实在。

**自动引入：** `unplugin-auto-import` + `unplugin-vue-components`。`import` 写得手酸又不产粮，能省就省。

**老机兜底：** `@vitejs/plugin-legacy`。现代语法你随便写，别让某个冷门机型替你收 polyfill 学费。

**旁白：** 这三样不是炫技三件套，是 **把重复劳动甩给编译器**，好腾出脑子对付业务 bug——那玩意儿才是真的没完没了。

#### 2. 样式：UnoCSS + 适配流水线，别让 CSS 偷吃带宽

很多项目不是 JS 先胖，是样式一层层叠上去，像过年囤的剩菜。我们是这么拧的。

**UnoCSS：** 按需生成，拒绝 “全站 class 大杂烩”。

**`presetRemToPx (base 4)` + `postcss-mobile-forever`：** 你继续用 px 的手感写，构建阶段它替你跟屏幕讲理。

**最大宽 1000px：** iPad、折叠屏别把页面扯成横幅海报。**稳一点往往比酷一点更积德。**

#### 3. 状态：Pinia 按域切，别养宇宙级 Store

全家桶 Store 走到最后，往往是 **谁也不敢动，动一下就抽奖**。按领域拆（用户、订单、行程…），域里再细分（如 `passengerStore`、`bookStore`），纪律就两条。

**跨域可以，但必须走显式接口**；暗戳戳 import 隔壁算犯规，别跟我谈 “特殊情况”。

**持久化只留关键路径**；临时弹窗状态也塞进 localStorage，等于给半年后的自己挖坑。

`pinia-plugin-persistedstate` 用在刀刃上：刷新、进程被杀，关键流程还能接上——用户叫连续体验，业务叫转化率别掉链子。

#### 4. 出国：Axios 收一层，i18n 别只改字

最怕页面上东一块西一块：**这儿手写 baseURL，那儿偷塞 token，语言切换只换字不换格式**。脏活沉到底下比较好。

**Axios 当轻薄中台：** region、续签、加解密、错误形状，在这里对齐；业务页只管 “我要啥 JSON”。

**Vue I18n 跟组件库握手：** 文案、日期、货币、布局方向 **一起动**，别让用户觉得 “字是中文，钱像美元，日历像从火星拣的”。

---

### 三、数字给老板看，体感给同事摸

长期跑下来，我们常压在这档（业务不同会有浮动，别当魔法 KPI）：

**FCP** 约在 1.0s 内。**TTI** 约在 1.5s 内。新人摸清新模块，冷启动往往能省个大概 **四成**——剩下那一截，多半花在搞清 **产品究竟要啥** 上；那份迷惘，架构救不了，顶多陪你叹气。

更实在的是会议室里话风变了：从 “这锅谁背” 慢慢滑向 “这块能不能复用”。**架构省的有时是性能，有时是加班费，有时是少吵两架的好心情。**

### 收尾一句

最耐打的方案，往往不是堆最新名词，而是 **默认就选得对、边界画得清、半年后你还能笑着改**。它不见得让你拿设计大奖，但大概率换你周五少熬一回。

真线上零事故？那我请你喝咖啡——**不过按规矩，先请测试同学。**

## 参考文章：相关链接

- [Vue 3 · Performance](https://vuejs.org/guide/best-practices/performance.html)（官方文档）— 官方性能实践：组件粒度、异步边界与打包体积，对照「快、稳、省」。
- [Vite · Building for Production](https://vite.dev/guide/build.html)（权威引文）— 生产构建与代码分割基线，解释 Vite 5 如何托住全球化 H5。
- [穿越边界的数字罗盘：全球化移动端 H5 架构的稳态设计](https://yijinlee.com/articles/article-6)（站内深度）— 同系列稳态设计篇，补齐边界与多区域维度。
- [HostApp 核心 H5 架构踩坑与进化史](https://yijinlee.com/articles/article-60)（站内深度）— 跨境电商 HostApp 实战，验证白皮书落地后的坑位。