前端 on 方糖猫Blog

微信小程序开发从入门到精通：环境搭建、WXML/WXSS、组件库、架构、平台能力与发布全指南

Wed, 16 Aug 2023 09:40:00 +0800

微信小程序开发从入门到精通：环境搭建、WXML/WXSS、组件库、架构、平台能力与发布全指南

目标读者：想进入小程序开发的前端同学，或者写过 Vue/React、想搞清楚「小程序和网页开发到底差在哪」的同学。
知识骨架与编排方式参考姊妹篇《Android 开发从入门到精通》——同样是「由浅入深、踩坑驱动」。写 UI 的心法还可以看《前端 UI 开发从入门到精通（Vue 技术栈）》，小程序的组件化思想和 Vue 一脉相承。

全文共八篇，顺序就是学习的顺序——每一篇都依赖前一篇打下的基础：

flowchart LR
    A["一 环境搭建<br/>注册 AppID 跑起 Hello World"] --> B["二 语法基础<br/>WXML/WXSS/JS/JSON 四件套"]
    B --> C["三 UI 组件库<br/>写出像样的页面"]
    C --> D["四 架构与生命周期<br/>从写页面到写应用"]
    D --> E["五 网络与存储<br/>数据从哪来 存到哪去"]
    E --> F["六 平台能力<br/>登录 订阅消息 分享 支付"]
    F --> G["七 质量与发布<br/>性能 体验版 审核上线"]
    G --> H["八 AI 时代<br/>让 AI 写 80% 的代码"]
    style H fill:#e8f4e8

为什么是这个顺序？前三篇解决「能不能写出来」；第四篇解决「页面多了以后会不会散架」；第五、六篇解决「能不能和后端、和微信这个平台打交道」；第七篇解决「敢不敢提交审核发给真实用户」；第八篇解决「如何持续快下去」。

第一篇环境搭建：比 Android 友好，但坑藏在「账号」里

先说好消息：小程序的环境搭建是整个客户端开发里最友好的——不用装 JDK，不用配 SDK，不用 Gradle 转圈。坏消息是：门槛从「装软件」转移到了「注册账号」，而账号相关的坑往往要在提交审核那天才爆出来。

1.1 你需要准备的三样东西

flowchart TD
    A["小程序账号 (AppID)<br/>mp.weixin.qq.com 注册"] --> D["微信开发者工具"]
    B["微信开发者工具<br/>官方 IDE 写代码 + 模拟器 + 调试"] --> E["能跑起 Hello World<br/>= 入门完成一半"]
    C["微信扫码登录<br/>一个微信号即可"] --> D
    D --> E

动手清单：

注册小程序账号：到 mp.weixin.qq.com 选择「小程序」注册，拿到 AppID（在「开发管理 → 开发设置」里）。注意一个邮箱只能绑定一个微信公众产品账号。
下载微信开发者工具：认准官方页面，选稳定版（Stable Build）。它是「编辑器 + 模拟器 + 调试器 + 发布工具」四合一，写小程序不需要再装别的。
新建项目：填入 AppID，模板选「不使用云服务」的最小模板，后端服务选「不使用模板」。模拟器里看到 Hello World 即通关。

如果只是学习不打算发布，也可以在新建项目时选「测试号」，跳过注册——但测试号很多能力（支付、订阅消息、发布）用不了，建议还是注册一个正式的个人账号。

1.2 踩坑故事一：类目选错，审核排队两周白排

现象：朋友的小程序功能全部做完，信心满满提交审核，第二天被拒：「所选类目与小程序实际内容不符」。改类目需要提供《增值电信业务经营许可证》——他没有。推倒重来，换了个人主体账号重新注册，前面所有配置全部作废。

原因：注册时选择的服务类目和主体类型（个人 / 企业）在注册后很难改，而且直接决定你的小程序能做什么：

flowchart TD
    Q{"小程序要做什么？"}
    Q -->|"内容展示 / 工具<br/>不涉及交易"| A["个人主体即可<br/>注册免费 门槛低"]
    Q -->|"电商 / 需要微信支付"| B["必须企业主体<br/>+ 对应经营类目"]
    Q -->|"医疗 / 金融 / 社交"| C["企业主体 + 行业资质<br/>提前查资质清单再动手"]
    style C fill:#ffe4e1

教训：先查类目，再写代码。微信官方有《小程序开放的服务类目》文档，写清楚每个类目需要什么资质。个人主体不能碰电商交易、不能做陌生人社交——无数个人开发者做到一半才发现「个人号不支持」，这是小程序生态最贵的一个坑，因为它爆在最后一步。

1.3 踩坑故事二：「不校验合法域名」的虚假安全感

现象：开发期接口调得好好的，一到真机预览就白屏，控制台报 request:fail url not in domain list。

原因：小程序的 wx.request 只能请求在 mp 后台预先配置过的 HTTPS 域名（request 合法域名）。开发者工具里有个「详情 → 本地设置 → 不校验合法域名」的开关，很多人开发期一直勾着它，勾到忘记它的存在——而真机上这个开关不存在（除非打开调试模式）。

解法：

去 mp 后台「开发管理 → 开发设置 → 服务器域名」配置 request 合法域名，必须 HTTPS，且域名要 ICP 备案。
开发期就把「不校验合法域名」关掉，让问题暴露在写代码的时候，而不是发给产品经理体验的时候。

教训：小程序的「域名校验」和 Android 的「明文流量拦截」是同一类东西——平台用白名单逼你上 HTTPS。这类安全约束的特点是「先放行以后再收」基本等于永远不收，第一天就把域名配好。

第二篇语法基础：四个文件就是一个页面

环境通了，接下来是语言。小程序的语法对前端来说几乎没有学习成本——它就是「受限版的 Vue」：模板 + 数据绑定 + 指令 + 组件化。这一篇的重点不是语法本身，而是它和自由 Web 的差异，坑全在差异里。

2.1 一个页面 = 四个文件

flowchart TD
    A["index.wxml<br/>模板 ≈ HTML<br/>写结构"] --- P["一个页面"]
    B["index.wxss<br/>样式 ≈ CSS<br/>多了 rpx 单位"] --- P
    C["index.js<br/>逻辑：Page({...})<br/>data + 生命周期 + 事件处理"] --- P
    D["index.json<br/>配置：导航栏标题<br/>引入哪些组件"] --- P
    P --> E["在 app.json 的 pages 数组里<br/>注册路径才算存在"]

全局还有一组 app.js / app.json / app.wxss：App 的生命周期、全局配置（页面注册、tabBar、窗口样式）、全局样式。

一个最小页面长这样：

<!-- pages/index/index.wxml -->
<view class="container">
  <text class="title">{{title}}</text>
  <view wx:for="{{todos}}" wx:key="id" class="todo">
    <text class="{{item.done ? 'done' : ''}}">{{item.text}}</text>
  </view>
  <button bindtap="onAdd">添加</button>
</view>

// pages/index/index.js
Page({
  data: {
    title: '我的待办',
    todos: [
      { id: 1, text: '学会 WXML', done: true },
      { id: 2, text: '学会 setData', done: false },
    ],
  },

  onAdd() {
    const todos = this.data.todos.concat({
      id: Date.now(),
      text: '新任务',
      done: false,
    });
    // ⚠️ 改数据必须走 setData，直接 this.data.todos = todos 界面不会刷新
    this.setData({ todos });
  },
});

2.2 setData：小程序开发的第一性原理

小程序的视图和逻辑跑在两个不同的线程：视图层是 WebView，逻辑层是 JSCore。你在 JS 里改 data，要通过 setData 把数据序列化后跨线程发给视图层，界面才会更新。

sequenceDiagram
    participant L as 逻辑层 (JSCore)
    participant B as 原生桥 (Native)
    participant V as 视图层 (WebView)
    L->>B: this.setData({ todos })
    Note over B: 数据序列化传输<br/>大对象 / 高频调用都在这里变慢
    B->>V: 更新 data
    V->>V: 重新渲染 WXML

这一个架构事实解释了小程序里 80% 的性能问题和 80% 的新手困惑：

直接赋值 this.data.x = 1 数据变了但界面不刷新——因为没有经过那座桥。
setData 传几十 KB 的大对象会卡——桥上的运输成本。
在 onPageScroll 里每次滚动都 setData 会卡成 PPT——桥上堵车。

现在只需要记住结论：setData 是有成本的，数据要小、频率要低。 第七篇会专门讲怎么优化。

2.3 十分钟速览：和 Vue 的核心差异

Page({
  // 1. 数据：必须先声明在 data 里，模板才能用
  data: { count: 0, list: [] },

  // 2. 改数据：setData，支持路径写法
  onInc() {
    this.setData({ count: this.data.count + 1 });
    // 深层路径：this.setData({ 'list[0].done': true })
  },

  // 3. 没有计算属性，官方方案是 WXS 或 setData 时算好
  //    （新语法支持 computed 需引第三方库，见第四篇）

  // 4. 生命周期：onLoad / onShow / onReady / onHide / onUnload
  onLoad(options) {
    // options 里是页面跳转带来的参数：/pages/detail?id=1 → options.id === '1'
  },
  onShow() {
    // 每次页面显示都会来（包括从下一页返回），刷新数据的常见位置
  },
});

WXML 指令对照表（会 Vue 的看一眼就够）：

Vue	小程序 WXML
`v-if`	`wx:if`
`v-else`	`wx:else`
`v-for`	`wx:for`，配合 `wx:key`
`@click`	`bindtap`
`:src="url"`	`src="{{url}}"`
`v-model`	没有，手写 `value="{{x}}" bindinput="onInput"`

感悟：小程序没有 v-model 是刻意的——双向绑定在「两线程架构」下是个性能陷阱，官方逼着你显式处理每一次输入。理解这一点，你就理解了小程序 API 设计的整体气质：宁可啰嗦，不可模糊。

2.4 rpx：一个单位解决屏幕适配

小程序做了件 Android 和 Web 都很羡慕的事：定义了 rpx（responsive pixel），屏幕宽度恒为 750rpx。设计稿按 750 宽出图，iPhone 6/7/8 上 1rpx = 0.5px，在更宽的机型上等比放大。样式里写 width: 375rpx 就是「半屏宽」，不用算任何比例。

踩坑故事三：rpx 用在不该用的地方

现象：海报生成页用了 Canvas 手绘，按设计稿把字号写成 28rpx，导出图片在小屏手机上文字糊成一团。

原因：Canvas 2D 接口、以及 wx.createSelectorQuery 拿到的尺寸单位都是物理 px，不是 rpx。rpx 只活在 WXSS 里。

解法：涉及 Canvas / JS 计算尺寸的地方，先换算：

const { pixelRatio, windowWidth } = wx.getWindowInfo();
const rpxToPx = (rpx) => (rpx * windowWidth) / 750;

教训：记住 rpx 的管辖范围只有 WXSS。凡是在 JS 里处理尺寸，第一件事就是确认单位。

2.5 踩坑故事四：回调里的 this 指向丢了

现象：wx.request 的 success 回调里 this.setData(...) 报错 Cannot read property 'setData' of undefined。

// ❌ 经典错误：普通函数的 this 不是页面实例
wx.request({
  url: 'https://api.example.com/todos',
  success: function (res) {
    this.setData({ todos: res.data });  // this 是 undefined
  },
});

// ✅ 解法一：箭头函数（词法 this），今天的推荐写法
wx.request({
  url: 'https://api.example.com/todos',
  success: (res) => {
    this.setData({ todos: res.data });
  },
});

教训：这是 JavaScript 的老问题，但它是每个小程序新手的「成人礼」。统一用箭头函数写回调，这个问题就绝迹了。顺手把 var that = this 这种上古写法从代码里清除出去。

第三篇 UI 组件库：别从零画按钮

语法有了，马上写界面。小程序自带一套基础组件（view、text、button、image、scroll-view、swiper……），但它们是「零件」不是「成品」——没有现成的日历、下拉刷新、商品卡片。这一篇解决两个问题：选什么组件库，以及怎么用它写出一个像样的页面。

3.1 主流组件库怎么选

flowchart TD
    Q{"做什么样的小程序？"}
    Q -->|"电商 / 通用业务<br/>组件要全"| A["vant-weapp (有赞)<br/>生态最大 文档最细"]
    Q -->|"要腾讯系设计风格<br/>长期维护"| B["TDesign (腾讯官方)<br/>设计规范完整"]
    Q -->|"京东系 / 多端"| C["NutUI (京东)"]
    Q -->|"一套代码同时出<br/>小程序 + H5 + App"| D["跨端框架<br/>Taro / uni-app<br/>⚠️ 见 3.4 节的权衡"]

vant-weapp：有赞出品，事实上的生态老大。组件全（60+），电商场景（商品、优惠券、地址编辑）开箱即用，社区问题几乎都能搜到答案。不知道选什么就选它。
TDesign：腾讯官方，设计体系完整，维护稳定。和 vant-weapp 二选一主要看设计稿更接近哪个风格。
NutUI：京东出品，风格轻量，多端版本（Taro）做得好。
基础组件之外值得一提的：wxml-to-canvas（海报生成）、echarts-for-weixin（图表）、computed / mobx-miniprogram（下一篇的主角）。

引入方式（以 vant-weapp 为例）：小程序从 2019 年起支持 npm，但和 Web 的 npm 用法不一样，多一步「构建」：

npm i @vant/weapp -S

然后在开发者工具里点「工具 → 构建 npm」，再在页面的 json 里声明：

{
  "usingComponents": {
    "van-button": "@vant/weapp/button/index",
    "van-field": "@vant/weapp/field/index"
  }
}

3.2 踩坑故事五：npm 装了，组件死活找不到

现象：npm install 成功，usingComponents 也写了，模拟器报 Component is not found in path "@vant/weapp/button/index"。

原因：小程序构建工具不直接读 node_modules，需要「工具 → 构建 npm」把它编译成 miniprogram_npm 目录。装完包没构建、或者 app.json 同级目录结构不对（project.config.json 里 miniprogramRoot 配错），都会撞上这个报错。

解法：构建 npm 后重启编译；团队项目把 miniprogram_npm 加入 git 忽略，但要在 README 里写明「拉代码后先构建 npm」——新人入职第一天栽在这上面的比例高得离谱。

3.3 Demo：一个五脏俱全的登录页

把数据绑定、事件、vant-weapp 组件串起来——每个小程序都有的页面：

<!-- pages/login/login.wxml -->
<view class="page">
  <van-field
    value="{{form.phone}}"
    label="手机号"
    placeholder="请输入手机号"
    error-message="{{errors.phone}}"
    bind:change="onPhoneChange"
  />
  <van-field
    value="{{form.code}}"
    label="验证码"
    placeholder="请输入验证码"
    bind:change="onCodeChange"
  >
    <van-button slot="button" size="small" type="primary"
      disabled="{{countdown > 0}}"
      bindtap="onSendCode">
      {{countdown > 0 ? countdown + 's 后重发' : '发送验证码'}}
    </van-button>
  </van-field>

  <van-button type="primary" block round
    loading="{{loading}}"
    bindtap="onLogin">
    登录
  </van-button>
</view>

// pages/login/login.js
Page({
  data: {
    form: { phone: '', code: '' },
    errors: { phone: '' },
    countdown: 0,
    loading: false,
  },

  onPhoneChange(e) {
    // van-field 的值在 e.detail 里
    this.setData({
      'form.phone': e.detail,
      'errors.phone': '',
    });
  },

  onCodeChange(e) {
    this.setData({ 'form.code': e.detail });
  },

  onSendCode() {
    if (!/^1\d{10}$/.test(this.data.form.phone)) {
      this.setData({ 'errors.phone': '手机号格式不对' });
      return;
    }
    this.setData({ countdown: 60 });
    this.timer = setInterval(() => {
      const next = this.data.countdown - 1;
      this.setData({ countdown: next });
      if (next <= 0) clearInterval(this.timer);
    }, 1000);
    // api.sendSmsCode(this.data.form.phone)
  },

  onLogin() {
    const { phone, code } = this.data.form;
    if (!/^1\d{10}$/.test(phone)) {
      this.setData({ 'errors.phone': '手机号格式不对' });
      return;
    }
    this.setData({ loading: true });
    // 第五篇会把它换成真正的请求封装
    setTimeout(() => {
      this.setData({ loading: false });
      wx.switchTab({ url: '/pages/home/home' });
    }, 800);
  },

  onUnload() {
    clearInterval(this.timer);  // ⚠️ 页面销毁要清定时器
  },
});

设计要点（这些比语法值钱）：

表单状态装进一个 form 对象，更新用 setData 的路径语法（'form.phone': value），只传变化的那一小条数据过线程桥——2.2 节的第一性原理在这里第一次兑现。
按钮的「正常 / 加载中 / 禁用」形态由状态驱动，UI 本质是状态机，这在 Vue、Android、小程序里是同一句话。
定时器在 onUnload 里清掉——页面销毁了定时器还在跑，轻则无效 setData 报错刷屏，重则内存泄漏。这是第四篇生命周期的预演。

3.4 原生还是跨端框架？一个绕不开的决策

只要做小程序，早晚有人问你：为什么不用 Taro / uni-app，一套代码出五端？我的建议是按团队和业务的真实情况选，而不是按技术情怀：

flowchart TD
    Q{"业务分布在哪？"}
    Q -->|"只发微信小程序<br/>且追求极致体验"| A["原生开发<br/>能力最全 坑最少<br/>新 API 第一天就能用"]
    Q -->|"微信 + 支付宝/抖音多平台<br/>或同时要 H5"| B["uni-app / Taro<br/>用平台差异最小的子集"]
    Q -->|"团队全是 React 技术栈"| C["Taro"]
    Q -->|"团队全是 Vue 技术栈"| D["uni-app"]

踩坑故事六：跨端框架里用了「全平台都支持」的组件，抖音端直接白屏

现象：uni-app 项目用了一个官方组件库的级联选择器，微信端、H5 端正常，发布到抖音小程序直接白屏，排查三天发现是该组件内部用了抖音端不支持的一个 API。

感悟：跨端框架解决的是「语法转换」，解决不了「平台能力差异」。微信小程序的能力更新最快（微信自家的新能力当然先给自己），跨端框架追平永远有时间差。选跨端，就要接受「用所有平台能力的最小公约数」这个约束。小团队单平台起步，先原生，等真的要多端了再迁移，往往比第一天就上跨端框架更划算。

第四篇架构与生命周期：从「写页面」到「写应用」

前三篇你能写出一个页面了。但真实小程序是几十个页面、被用户以你想象不到的顺序跳转、随时被微信切到后台。这一篇建立组织代码的地基。

4.1 生命周期：App、Page、Component 三层

stateDiagram-v2
    [*] --> App_onLaunch: 冷启动(整个小程序只此一次)
    App_onLaunch --> Page_onLoad: 打开第一个页面
    Page_onLoad --> Page_onShow: 页面显示
    Page_onShow --> Page_onReady: 首次渲染完成
    Page_onReady --> Page_onHide: 跳转下一页 / 切后台
    Page_onHide --> Page_onShow: 返回本页 / 回到前台
    Page_onShow --> Page_onUnload: 页面被销毁(redirect/navigateBack)
    Page_onUnload --> [*]

真正值钱的是这三条规则：

onLoad 一生只来一次，onShow 每次显示都来：onLoad 只在页面创建时执行一次，拿着跳转参数；onShow 每次显示都来。「返回时要不要刷新列表」的答案就是把刷新逻辑放 onShow，而不是假设 onLoad 会再来。
onReady 之前别碰节点：wx.createSelectorQuery() 查 DOM 要等首次渲染完成，放 onLoad 里查高度会拿到 0。
小程序没有可靠的「退出回调」：用户按胶囊按钮关掉小程序，onUnload 之后 App 可能还活着，也可能随时被系统回收。重要数据不能指望「退出时再保存」，和 Android 的 onDestroy 不保证调用是同一个道理。

踩坑故事七：编辑页保存返回，列表还是旧数据

现象：从列表页进编辑页，改完保存返回，列表纹丝不动。

原因：返回上一页走的是 navigateBack，上一页的实例没有被销毁，onLoad 不会再执行。

解法，两种主流姿势：

// 解法一：列表页把刷新放 onShow
onShow() {
  this.loadList();   // 返回时自然刷新，缺点是首次会重复加载，加 flag 控制
}

// 解法二：编辑页保存后主动通知上一页（事件总线 / getCurrentPages）
const pages = getCurrentPages();
const prevPage = pages[pages.length - 2];
prevPage.onNeedRefresh?.();   // 直接调上一页的方法
wx.navigateBack();

4.2 页面栈：小程序导航的「宪法」

小程序的页面不是平铺的，是一个栈：

flowchart LR
    subgraph stack["页面栈（最多 10 层）"]
        A["首页<br/>栈底"] --> B["列表页"] --> C["详情页"] --> D["编辑页<br/>栈顶"]
    end
    E["navigateTo<br/>压栈 保持当前页"] -.->|"+1 层"| stack
    F["navigateBack<br/>出栈返回"] -.->|"-1 层"| stack
    G["redirectTo<br/>替换栈顶"] -.->|"层数不变"| stack
    H["reLaunch<br/>清空重开"] -.->|"栈重置"| stack
    I["switchTab<br/>跳 tabBar 页"] -.->|"非 tabBar 页全部出栈"| stack

踩坑故事八：跳转到第十一层，按钮点了没反应

现象：一个「猜你喜欢 → 详情 → 相关推荐 → 详情 → …」的商品浏览链路，用户连点十次之后，再点卡片毫无反应，既不跳转也不报错（老基础库静默失败）。

原因：navigateTo 的页面栈上限是 10 层，到了第 11 次压栈直接失败。

解法：自循环的详情链路用 redirectTo（替换栈顶而不是压栈），或者监测栈深度，满了就 reLaunch 回首页。这也是「返回键要按十下才能退出」这种体验事故的根源——栈越深，用户的返回路径越长。

踩坑故事九：navigateTo 跳 tabBar 页，永远不生效

现象：wx.navigateTo({ url: '/pages/home/home' }) 调用了，纹丝不动。

原因：tabBar 页面不在普通页面栈体系里，必须用 wx.switchTab；反过来，非 tabBar 页不能用 switchTab。两类页面的 URL 在 app.json 里就决定了（tabBar.list 里的那几个），API 选错是唯一可能的原因。

教训：这条错不报错、静默失败，是新人调试时间最长的坑之一。记住口诀：tabBar 用 switchTab，栈满用 redirectTo，重启用 reLaunch，其他 navigateTo。

4.3 组件化与通信：从页面到 Component

页面大了要拆组件。自定义组件也是四文件结构，js 里用 Component({...}) 代替 Page({...})：

// components/price-card/index.js
Component({
  options: {
    styleIsolation: 'isolated',   // ⚠️ 见踩坑故事十
  },
  properties: {
    price: { type: Number, value: 0 },      // 父传子
  },
  data: { /* 组件内部状态 */ },
  methods: {
    onBuy() {
      this.triggerEvent('buy', { price: this.data.price });  // 子传父：派事件
    },
  },
});

<!-- 父页面使用 -->
<price-card price="{{item.price}}" bind:buy="onBuy" />

通信方式的全景：

flowchart TD
    A["父 → 子<br/>properties"] --- S["组件通信"]
    B["子 → 父<br/>triggerEvent 派事件"] --- S
    C["任意组件 ↔ 全局<br/>mobx-miniprogram 绑定"] --- S
    D["页面间<br/>EventChannel(navigateTo 时建立)<br/>或事件总线"] --- S

踩坑故事十：改组件库样式改不动，自己页面的样式却互相污染

现象：给 van-button 写了个覆盖样式死活不生效；反过来，A 页面给 .title 写的红色，B 页面的 .title 也变红了。

原因：小程序的样式隔离规则和直觉相反：

页面之间：样式是全局的！A 页面 WXSS 里的类名会污染 B 页面（同名类）。
组件内部：默认有隔离（isolated），外面的样式进不去，里面的样式出不来——所以改不动组件库。

解法：

页面样式一律加页面级命名空间：.page-order .title { ... }，或者干脆多用组件（组件天然隔离）。
组件需要接收外部样式时，在 options 里调 styleIsolation: 'apply-shared'（外能进内不出）或 shared（双向），改组件库主题时经常要用到。

4.4 全局状态：mobx-miniprogram 就够了

页面多了之后，「用户信息、购物车数量」这类全局状态在几十个页面间传来传去会迅速失控。小程序生态没有 Vuex/Pinia 那样的官方答案，事实标准是 mobx-miniprogram + mobx-miniprogram-bindings：

// stores/user.js
import { observable, action } from 'mobx-miniprogram';

export const userStore = observable({
  userInfo: null,
  get isLoggedIn() {
    return !!this.userInfo;
  },
  setUserInfo: action(function (info) {
    this.userInfo = info;
  }),
});

// 页面绑定：store 变了，页面 data 自动同步
import { createStoreBindings } from 'mobx-miniprogram-bindings';
import { userStore } from '../../stores/user';

Page({
  onLoad() {
    this.storeBindings = createStoreBindings(this, {
      store: userStore,
      fields: ['userInfo', 'isLoggedIn'],
      actions: ['setUserInfo'],
    });
  },
  onUnload() {
    this.storeBindings.destroyStoreBindings();  // ⚠️ 记得销毁
  },
});

思考：这套写法的心智模型和 Vue 的 Pinia + computed 完全一致——「store 是唯一数据源，页面只是绑定」。同时别忘了给 Component 配上官方扩展库 computed 和 watch（mobx-miniprogram 同一作者出品），小程序原生组件没有计算属性，手写派生状态是代码腐烂的起点。

第五篇网络与存储：数据从哪来，存到哪去

架构定了，现在填数据的肉。这一篇学完，你就能写出「登录 + 联网 CRUD + 本地缓存」的完整小程序了。

5.1 wx.request：先把回调包成 Promise

小程序的联网 API 是回调风格的 wx.request，直接用会很快陷入回调地狱（2.5 节那种嵌套套嵌套）。项目第一天就该做的封装：

// utils/request.js
const BASE_URL = 'https://api.example.com';

function request({ url, method = 'GET', data, needAuth = true }) {
  return new Promise((resolve, reject) => {
    wx.request({
      url: BASE_URL + url,
      method,
      data,
      timeout: 10000,
      header: {
        // 统一带 token：小程序没有 Cookie 自动管理，登录态自己维护
        Authorization: needAuth ? `Bearer ${wx.getStorageSync('token')}` : '',
      },
      success(res) {
        if (res.statusCode >= 200 && res.statusCode < 300) {
          resolve(res.data);
        } else if (res.statusCode === 401) {
          // token 过期：清登录态，跳登录页
          wx.removeStorageSync('token');
          wx.reLaunch({ url: '/pages/login/login' });
          reject(new Error('登录已过期'));
        } else {
          reject(new Error(res.data?.message || `请求失败 ${res.statusCode}`));
        }
      },
      fail(err) {
        // 断网、超时、域名不在白名单都走这里
        reject(new Error('网络异常，请稍后重试'));
      },
    });
  });
}

// 使用：async/await，和前端写 axios 一个手感
async onLoad() {
  try {
    const todos = await request({ url: '/todos' });
    this.setData({ todos });
  } catch (e) {
    wx.showToast({ title: e.message, icon: 'none' });
  }
}

设计要点：拦截逻辑（带 token、401 处理、错误归一化）写在这一层，业务代码就只剩一行 await——这和 Android 的 OkHttp 拦截器、前端的 axios 拦截器是同一种分层思想。

踩坑故事十一：401 了，但页面还停在原地

现象：token 过期后接口返回 401，封装的 request 里做了 reLaunch 跳登录页，但用户反馈「偶尔跳不过去」。

原因：wx.reLaunch 跳转登录页时，如果当前页面栈里有 tabBar 页，reLaunch 的目标 URL 带了 query 参数在部分基础库上被丢弃；更隐蔽的是——401 时多个并发请求会触发多次 reLaunch，第二次 reLaunch 打断了第一次。

解法：401 处理加防抖锁：

let isRedirectingToLogin = false;
function handleUnauthorized() {
  if (isRedirectingToLogin) return;
  isRedirectingToLogin = true;
  wx.removeStorageSync('token');
  wx.reLaunch({
    url: '/pages/login/login',
    complete: () => { isRedirectingToLogin = false; },
  });
}

移动端特有的提醒（小程序同理）：微信用户会进电梯、切 Wi-Fi 和流量，弱网和断线是常态而不是异常。timeout 必须配、失败要给重试入口、wx.showToast 报错别弹全屏错误页——静默重试一次，体验天差地别。

5.2 本地存储：wx.setStorage 的分寸

小程序的存储比 Android 简单得多，没有 Room 没有 DataStore，就一个 wx.setStorage / wx.getStorage（异步）和 wx.setStorageSync / wx.getStorageSync（同步）：

flowchart TD
    Q{"要存什么？"}
    Q -->|"token / 用户设置<br/>小键值对"| A["wx.setStorageSync<br/>同步 简单"]
    Q -->|"列表缓存 / 草稿<br/>几 KB 以上的数据"| B["wx.setStorage (异步版)<br/>⚠️ 同步版大数据会卡 UI"]
    Q -->|"要跟随用户换设备<br/>或免后端"| C["微信云开发<br/>云数据库 + 云函数"]
    Q -->|"敏感数据(密码之类)"| D["❌ 别存本地<br/>存 token 不存密码"]

两个数字要记住：单个 key 上限 1MB，总上限 10MB。超出直接写入失败。

踩坑故事十二：storage 同步读写把首页卡死了

现象：首页加载越来越慢，Profiling 发现 getStorageSync 一个调用占了 200ms。

原因：运营活动的弹窗配置、AB 实验分组、用户信息……十几个模块都往 storage 里塞，有个模块把整份商品列表（几百 KB）也存了进去，首页启动时同步读，主线程原地罚站。

解法：

大对象读写一律用异步版（wx.getStorage）。
启动时只读「渲染首屏必需」的字段，其余懒加载。
token 这种小且高频的用同步版没问题——按数据大小和频率选 API，不是按顺手程度。

5.3 云开发：没有后端时的另一条路

如果你是个人开发者、没有自己的服务器，微信云开发（CloudBase）值得单独了解：云数据库（类 MongoDB）、云函数（Node.js）、云存储、云调用（直接调微信 API 免鉴权），在开发者工具里一站式完成，不用买服务器、不用配域名、不用过 ICP 备案——对，云开发的请求不受 1.3 节域名白名单限制，这对个人开发者是巨大优势：

// 免鉴权、免域名配置，一行调用
const db = wx.cloud.database();
const res = await db.collection('todos').where({ done: false }).get();

代价是：数据模型简单、复杂业务（多表事务、复杂查询）不如自建后端灵活，迁移到自有后端的成本不低。工具类、内容类、Demo 项目用云开发；交易核心、复杂业务自建后端。

第六篇平台能力：登录、订阅消息、分享、支付与分包

到这里，你的小程序已经「自成一体」了。这一篇让它和微信这个平台打交道。平台能力的坑有一个共同特征：文档看着简单，但 API 的生命周期变迁极快，照着两年前的教程写必踩坑。

6.1 登录：code 换 openid 的三段握手

小程序登录是平台能力里设计最优雅的一个，也是面试必考题：

sequenceDiagram
    participant MP as 小程序前端
    participant WX as 微信服务器
    participant S as 你的后端
    MP->>WX: wx.login() 拿 code(5分钟有效)
    MP->>S: 把 code 发给自己的后端
    S->>WX: code + appid + secret 换<br/>openid + session_key
    WX-->>S: openid(用户唯一标识) + session_key
    S-->>MP: 签发自家 token(如 JWT)
    Note over MP: 之后所有请求带 token<br/>session_key 永远不出后端

三条铁律：

session_key 绝不能下发到前端——它能解密用户敏感数据，泄漏等于把用户数据大门敞开。
code 只能用一次且 5 分钟过期，换取动作必须在后端做（secret 也不能进前端代码）。
前端维护的是自家 token，不是微信的 code。5.1 节 request 封装里带的 Authorization 就是它。

踩坑故事十三：跟着老教程写 getUserProfile，提交审核被拒

现象：照着 2021 年的教程用 wx.getUserProfile 拿用户头像昵称，真机一调返回 getUserProfile:fail can only be invoked by user TAP gesture 或直接被拒审。

原因：微信在 2022 年回收了 getUserProfile 能力。现在获取头像昵称的官方姿势是两个表单组件：

<!-- 头像：button open-type="chooseAvatar" -->
<button open-type="chooseAvatar" bind:chooseavatar="onChooseAvatar">
  <image src="{{avatarUrl || '/images/default-avatar.png'}}" />
</button>
<!-- 昵称：input type="nickname"，拉起微信输入法半屏 -->
<input type="nickname" placeholder="请输入昵称" bind:blur="onNicknameBlur" />

教训：这是小程序开发最重要的生存技能——微信 API 的废弃和变更极快，任何「照着教程写」的代码都要去官方文档核对一遍最新版本。关注「微信小程序开发者文档」的更新日志，比关注任何公众号都有用。

6.2 订阅消息：推送的正确打开方式

小程序没有 Android 那种「随便推」的通知系统，触达用户的正道是订阅消息：

flowchart LR
    A["用户在小程序里<br/>主动点击按钮"] --> B["wx.requestSubscribeMessage<br/>弹出订阅授权框"]
    B --> C{"用户怎么选？"}
    C -->|"允许"| D["后端在服务通知里<br/>下发一次消息"]
    C -->|"拒绝"| E["⚠️ 同一个模板<br/>短期内不能再弹"]
    C -->|"勾选『总是保持以上选择』"| F["以后静默按上次选择执行"]

关键认知：订阅消息默认是一次性的——用户点一次允许，你只能推一次。长期订阅仅对政务、医疗等特定类目开放。所以正确的产品设计是「在最关键的动作上请求订阅」（下单、预约、打卡），而不是见缝插针地弹。

踩坑故事十四：订阅消息发出去了，用户没收到

按出现概率排查：

模板 ID 不对：模板在 mp 后台「订阅消息」里申请，tmplIds 写错或用了测试模板，发送直接报错。
关键词格式不匹配：模板里的 {{thing1.DATA}}（字符串）、{{amount2.DATA}}（金额）每种类型有严格格式限制，金额必须是数字、字符数超限都会发送失败——失败原因要去查发送接口的返回码，客户端无感知。
用户没订阅 / 订阅次数用完了：一次订阅只够推一次，推完额度清零。
跳转页面未发布：消息配置的 page 路径必须是已发布版本里存在的页面，配了还在开发中的页面，用户点消息会跳到错误页。

6.3 分享与裂变：小程序的增长引擎

小程序生于社交，分享能力是它的原生优势：

// 页面级分享：定义了才有「转发」入口的内容
Page({
  onShareAppMessage() {
    return {
      title: '这个记账小程序太好用了',
      path: '/pages/home/home?from=share&uid=' + this.data.uid,  // ⚠️ 路径带参做裂变归因
      imageUrl: '/images/share-cover.png',  // 5:4 比例，自定义封面
    };
  },
});

应知应会的分寸：

分享无法拿到「是否分享成功」的回调了（早年有，已回收）——「分享成功就送优惠券」这种强制裂变做不了，这也是微信的刻意设计。
朋友圈：小程序不能直接分享到朋友圈（除了特定的「分享到朋友圈」Beta 能力且仅 Android），正道是生成海报图让用户自己发——3.1 节的 wxml-to-canvas 就是干这个的。
裂变归因全靠 path 参数：谁分享的、从哪进来的，都编码在 onShareAppMessage 的 path 里，落地页在 onLoad(options) 里解析。这套机制就是小程序增长黑客的全部基础。

6.4 支付：五步流程，前后端各管一半

微信支付是平台能力里链条最长的，画出来再写代码：

sequenceDiagram
    participant MP as 小程序
    participant S as 你的后端
    participant WX as 微信支付
    MP->>S: 1. 创建订单(商品 金额)
    S->>WX: 2. 统一下单(用商户号密钥签名)
    WX-->>S: prepay_id
    S-->>MP: 3. 返回支付参数(二次签名)
    MP->>WX: 4. wx.requestPayment 拉起收银台
    WX-->>MP: 用户输密码完成
    WX-->>S: 5. ⚠️ 支付结果异步回调(这才是到账依据)

踩坑故事十五：以前端回调为准发货，被刷单薅了羊毛

现象：wx.requestPayment 的 success 回调里直接通知后端「支付成功，发货」，上线一个月被恶意用户用篡改的客户端刷出大量未付款订单。

原因：前端的一切回调都不可信。唯一可信的到账凭证是微信支付服务器推送给你后端的异步回调（pay 通知），验签通过才算数。

教训：这条规则在 Android 内购、Stripe 支付里一模一样——客户端回调只负责 UI 表现，服务端回调才负责业务状态。凡是涉及钱的状态变更，永远以服务端到服务端的通知为准。

另外记住 1.2 节的连锁反应：虚拟商品（课程、会员）在 iOS 端不能走微信支付（苹果规则），要么引导安卓/H5 支付，要么走小程序虚拟支付通道并接受抽成——类目和主体在注册那天就决定了你有没有资格碰这块。

6.5 分包加载：2MB 限制的解法

小程序主包上限 2MB（总包 20MB），所有页面塞一个包很快就会撞线。答案是分包：

// app.json
{
  "pages": ["pages/home/home", "pages/login/login"],
  "subPackages": [
    {
      "root": "packageOrder",
      "pages": ["pages/list/list", "pages/detail/detail"]
    },
    {
      "root": "packageUser",
      "pages": ["pages/profile/profile", "pages/setting/setting"]
    }
  ],
  "preloadRule": {
    "pages/home/home": {
      "network": "wifi",
      "packages": ["packageUser"]
    }
  }
}

flowchart TD
    A["主包 ≤ 2MB<br/>首页 + tabBar 页 + 公共代码"] -->|"用户点进订单模块"| B["订单分包<br/>按需下载"]
    A -->|"Wi-Fi 下预加载"| C["个人中心分包"]
    style A fill:#e8f4e8

设计要点：首页和 tabBar 页必须在主包（启动就加载）；低频功能（设置、关于、客服）果断拆分包；preloadRule 让「首页加载完、Wi-Fi 下静默下载个人中心包」，用户点过去秒开。

第七篇质量与发布：从「能跑」到「敢上线」

功能做完只是上半场。小程序的发布比 Android 多了一道「平台审核」，这是它最独特的一关。

7.1 性能三板斧：setData、分包、图片

小程序性能问题的 90% 集中在这三件事上：

第一板斧：setData 瘦身（2.2 节第一性原理的兑现）

flowchart TD
    A["页面卡顿"] --> B{"setData 传的什么？"}
    B -->|"整个大列表"| C["改成路径更新<br/>'list[3].done': true"]
    B -->|"高频调用<br/>onPageScroll / 倒计时"| D["合并 + 节流<br/>攒一批一次发"]
    B -->|"传了视图用不到的字段"| E["data 里只放渲染需要的数据<br/>其余存 this 普通属性"]

// ❌ 每秒 setData 整个对象
this.setData({ form: this.data.form });

// ✅ 只传变化的字段
this.setData({ 'form.phone': value });

// ✅ 不参与渲染的数据根本别进 data
Page({
  data: { list: [] },
  onLoad() {
    this._rawResponse = null;  // 内部缓存，挂 this 上不挂 data
  },
});

第二板斧：分包——6.5 节已经讲过，启动速度的第一优化项。

第三板斧：图片——列表图一律压缩到展示尺寸的 2 倍以内、用 image 组件的 lazy-load、CDN 域名配进 downloadFile 白名单。首屏图太多时，骨架屏比 loading 转圈的感知快一倍。

踩坑故事十六：倒计时把列表页卡成 PPT

现象：团购列表每个卡片都有「距结束 xx:xx」倒计时，页面滑动掉帧严重。

原因：20 个卡片各自开了 setInterval，每秒 20 次 setData 跨线程传输——桥堵了。

解法：一个全局定时器，每秒算一次所有卡片的剩余时间，合并成一次 setData：

// 一个 timer 驱动全部卡片
this.timer = setInterval(() => {
  const updates = {};
  this.data.list.forEach((item, i) => {
    updates[`list[${i}].remainText`] = formatRemain(item.endTime);
  });
  this.setData(updates);   // 每秒只有这一次过桥
}, 1000);

7.2 调试三板斧：vConsole、真机调试与体验版

开发者工具：模拟器 + Wxml 面板（看最终渲染树）+ AppData 面板（实时看每个页面的 data，排查 setData 问题的第一现场）。
真机调试：开发版小程序右上角胶囊菜单里打开「开发调试」，vConsole 会浮在页面上——手机上看到 console.log、网络请求、storage 内容。真机和模拟器的差异比你想的大：字体渲染、安全区、性能、个别 API 行为都不一样，发布前必须真机过一遍主流程。
体验版：上传代码后在 mp 后台设为体验版，添加体验成员（微信号），扫码即用。它是「发给产品和测试同学」的标准姿势，比 Android 装 APK 优雅得多。

踩坑故事十七：体验版打不开，群里一片「白屏了」

现象：上传体验版后，自己手机正常，测试同学扫码一直白屏。

排查路径：

对方的微信号加进「体验成员」了吗？
你上传后设为体验版了吗？（上传 ≠ 自动成为体验版，要在版本管理里手动选）
对方是不是打开了「调试模式」导致走了别的版本？（体验版打开调试后会加载开发版代码，版本就乱了）

教训：小程序有「开发版 / 体验版 / 线上版」三个版本共存，版本切换的开关藏在各处。发体验版给别人之前，用一个不在体验成员名单里的微信号扫一次——模拟用户的真实路径，这一分钟能省一小时的群聊排查。

7.3 审核与发布：小程序独有的最后一关

flowchart LR
    A["开发者工具<br/>上传代码"] --> B["mp 后台<br/>提交审核"]
    B --> C{"审核结果<br/>几小时到几天"}
    C -->|"通过"| D["手动点『发布』<br/>全量上线"]
    C -->|"拒绝"| E["按驳回原因改<br/>重新排队"]
    D --> F["灰度发布<br/>按比例放量 可回退"]

提高一次过审率的实战清单：

类目和内容对齐（1.2 节）：电商功能挂企业类目，个人号别碰交易。
给用户「不登录也能逛」的路径：审核员会拒绝「打开就强制授权手机号」的小程序。登录应该发生在「需要身份的那个动作」上（下单、收藏），而不是启动时。
测试账号：审核表单里提供测试账号密码或免密通道，审核员进不去你的核心流程必拒。
敏感功能自审：UGC 内容要有举报/审核机制说明；涉及医疗、金融的回答要有资质上传。

感悟：审核这道关常被骂，但它塑造了小程序生态和 App 生态的根本不同——小程序是「寄居」在微信里的，平台既是分发渠道也是监管者。接受这个设定，把审核标准当作产品设计的一部分（登录时机、隐私协议、类目选择），而不是发布前的拦路虎，你的过审率会高得多。

第八篇 AI 时代：怎么少写一半代码把小程序做出来

前七篇是「内功」，这一篇是「兵器」。我的结论和 Android 篇一致：AI 没有让小程序开发变简单，它让「懂行的人」快了 3-5 倍，让「不懂行的人」更快地写出能跑但烂尾的代码。区别在于你怎么用它。

8.1 AI 在小程序开发各环节的胜任度

flowchart LR
    subgraph good["AI 做得极好 放心交出去"]
        A1["单页面骨架<br/>wxml + wxss + Page({...})"]
        A2["表单页 / 列表页<br/>配 vant-weapp 组件"]
        A3["request 封装 / 工具函数"]
        A4["单元测试与类型定义"]
    end
    subgraph mid["AI 能做 但你要盯着"]
        B1["跨页面状态设计"]
        B2["性能优化(setData/分包)"]
        B3["组件库主题定制"]
    end
    subgraph bad["AI 做不好 还得靠人"]
        C1["类目/资质/审核问题<br/>(政策天天变)"]
        C2["真机才出现的 bug<br/>安全区 键盘 滚动"]
        C3["微信 API 的最新变更<br/>(训练数据滞后)"]
    end

第三格要特别说：微信 API 的变更速度（6.1 节 getUserProfile 的故事）恰好打在 AI 的软肋上——训练数据里全是旧 API 的示例。AI 给你写 wx.getUserInfo 时你要能一眼认出「这是 2021 年的写法」。

8.2 实战工作流：需求 → 小程序的 AI 协作五步法

第一步：先写「项目宪法」，再让 AI 写代码。 在项目里放一个 AGENTS.md：

# 项目约定
- 原生小程序（不用跨端框架），组件库 @vant/weapp，less 写样式
- 页面四文件结构：wxml/wxss/js/json，页面样式加命名空间防污染
- 全局状态用 mobx-miniprogram + mobx-miniprogram-bindings，组件配 computed 扩展
- 网络统一走 utils/request.js 封装，async/await，业务代码禁止裸 wx.request
- setData 只传变化字段的路径写法；不参与渲染的数据挂 this 普通属性
- 跳转口诀：tabBar 用 switchTab，自循环链路用 redirectTo，其他 navigateTo
- 回调一律箭头函数；定时器/绑定在 onUnload 里清理
- 登录态：wx.login 拿 code 给后端换 token，前端只存 token，禁存 session_key

注意这份清单里的每一条，都对应着前面某一篇的某个坑——项目宪法本质上是踩坑笔记的浓缩。

第二步：页面级生成，而不是小程序级生成。 不要对 AI 说「给我写一个记账小程序」，要说「按项目约定写一个记账首页：顶部本月支出汇总卡片，下面是账单列表，用 van-cell，下拉刷新，每条显示分类图标、备注、金额」。一次一个页面，AI 的输出质量和你的可控性都最高。

第三步：让它先写数据结构和状态，再写 UI。 先生成页面的 data 结构、接口契约、状态流转，review 通过后再写 wxml——这正是第四、五篇的架构顺序。状态设计错了，UI 写得再漂亮也是白写。

第四步：报错直接喂回去，但分清两类问题。 模拟器里的 JS 报错、组件找不到这类代码级问题，贴给 AI 循环两三次基本能解；但 1.2 节那种账号类目问题、6.1 节那种 API 已废弃问题、真机上才出现的白屏——AI 帮不了，它没有你的 mp 后台权限，也没有真机。这就是为什么 AI 篇必须排在最后：它是放大器，放大的是你前七篇的水平。

第五步：人工 review 的五个必查点。 AI 生成的小程序代码，我每次都只细查五处：① setData 是不是整个大对象往里塞（性能重灾区）；② 定时器和 store 绑定有没有在 onUnload 里清理（泄漏来源）；③ 跳转 API 用对没有（tabBar 页 navigateTo 的静默失败 AI 经常犯）；④ 请求有没有走统一封装、token 处理对不对；⑤ 用的微信 API 是不是已经废弃的版本。其他代码粗看即可——review 的精力要花在 AI 的已知短板上。

8.3 一个真实对比：Demo 小程序的工时变化

第三篇那个登录页 + 一个待办列表页的小程序 Demo，三年前我要写一整天（查 API、调样式、处理状态）。2026 年用 AI 的实际耗时：

pie title 一个双页面 Demo 的 2 小时去哪了
    "写 AGENTS.md 和提示词" : 20
    "AI 生成 + 我 review 修改" : 55
    "AppID/类目/域名配置(AI帮不上)" : 25
    "真机测试与细节打磨" : 20

注意那张饼图里最大的启示：省下来的时间没有消失，它转移到了「描述需求」和「审查代码」上，还有一部分转移到了 AI 永远碰不到的「平台事务」上——注册、类目、域名、审核。AI 时代的核心能力从「打字速度」变成了三样：

把模糊需求拆成精确技术任务的能力——你对第四篇架构的理解越深，给 AI 的指令就越准。
快速判断代码对错的能力——看不懂 setData 成本的人，review 不了 AI 写的小程序代码。
搞定平台事务的能力——类目、资质、审核、API 变更，这些「和微信打交道」的事，一件都外包不出去。

8.4 思考：AI 是放大器，不是替代品

小程序生态和 AI 有一个有趣的共同点：它们都在「消灭记忆型知识的价值」。小程序当年消灭了「会写 Objective-C/Java 才能做移动端」的门槛；AI 今天消灭了「背得出 API 参数才配写代码」的门槛。留下来的价值是同一种东西——判断型知识：

这个状态该放 data 还是挂 this 上？
这个跳转该用 redirectTo 还是 navigateTo？
这个需求个人主体能不能做，会不会死在审核？
AI 写的这段代码用的 API，是不是去年就被回收了？

所以这篇文章前七篇的内容，在 AI 时代不但没有过时，反而更重要了——它们是你在 AI 写完代码后，能说「对」或者「不对」的全部依据。

结语：学习路线收个尾

flowchart LR
    A["第 1 周<br/>注册 AppID + 跑通模板<br/>+ 四件套语法"] --> B["第 2-3 周<br/>vant-weapp 组件库<br/>写 5 个静态页面"]
    B --> C["第 1-2 个月<br/>生命周期 + request 封装<br/>+ 登录流程<br/>写一个联网 CRUD 小程序"]
    C --> D["第 2-4 个月<br/>订阅消息/分享/支付/分包<br/>体验版 审核 发布上线"]
    D --> E["持续<br/>把 AI 变成<br/>你的初级工程师"]

三条反直觉的建议作为结尾：

第一周死磕账号不丢人。类目、主体、域名、备案，这些「和微信打交道」的事才是真正的门槛，写代码反而是最简单的部分。这不是你笨，是这个生态的真实成本。
第一天就用真机预览。模拟器掩盖了安全区、键盘、性能和版本差异问题——你的用户分布在几千种机型的微信里，而小程序的真机预览只要扫个码，这是整个客户端开发里成本最低的真机测试，没有借口不用。
让 AI 写代码，让自己写笔记。每踩一个坑记下「现象、根因、下次怎么一眼认出」，这些笔记是 AI 时代你不可被替代的资产——因为 AI 知道所有答案，但它不知道微信上个月又改了哪个 API，以及你的审核上次为什么被拒。

祝你的 setData 永远轻盈，审核永远一次过，小程序在 iPhone SE 和折叠屏上都一样流畅。

React 从入门到精通：环境搭建、核心语法、组件库选型与 AI 时代的开发方式

Fri, 26 Aug 2022 10:00:00 +0800

React 从入门到精通

目标读者：会 HTML/CSS/JS 基础，想系统学前端框架的同学；或写过 Vue/jQuery 想转 React 的工程师。阅读目标：把环境搭起来、把核心语法学会、把坑提前踩掉、知道组件库怎么选，最后聊聊 AI 时代写前端的新姿势。

React 的入门门槛不高，但「会写」和「写对」之间隔着一批经典的坑。这篇按真实学习顺序组织：环境 → 语法 → 心智模型 → 踩坑 → 组件库 → Demo → AI 时代的开发方式。

一、学习路线图

flowchart LR
    A["JS 基础<br/>ES6 语法"] --> B["环境搭建<br/>Node + Vite"]
    B --> C["核心语法<br/>JSX / 组件 / Props / State"]
    C --> D["Hooks<br/>useState / useEffect / 自定义 Hook"]
    D --> E["工程化<br/>路由 / 状态管理 / 组件库"]
    E --> F["进阶<br/>性能优化 / 服务端渲染"]
    F --> G["AI 协同开发"]

二、开发环境搭建（2022 年的正确姿势）

2.1 装 Node：用 nvm，不要官网下载安装包

第一个坑往往出在环境上：老教程让你去 nodejs.org 下安装包，半年后项目要求换个 Node 版本，你就得重装。用 nvm 管理多版本：

# Windows 用 nvm-windows，Mac/Linux 用 nvm
nvm install 16        # 2022 年的 LTS 是 16/18
nvm use 16
node -v               # v16.x.x

国内网络记得配镜像：npm config set registry https://registry.npmmirror.com。

2.2 创建项目：用 Vite，不要 create-react-app

2022 年的第二个坑：老教程还在教 create-react-app（CRA），它启动慢、打包慢、官方已基本停止维护。用 Vite，秒级启动：

npm create vite@latest my-app -- --template react
cd my-app
npm install
npm run dev           # 打开 http://localhost:5173

目录结构：

my-app/
├── index.html          # 入口 HTML
├── package.json
├── vite.config.js
└── src/
    ├── main.jsx        # 挂载根组件
    ├── App.jsx         # 根组件
    └── components/     # 自己的组件放这里

2.3 编辑器与插件

VS Code + 两个必装插件：ES7+ React Snippets（输入 rafce 一键生成组件骨架）、ESLint（边写边提示 Hooks 依赖遗漏等问题）。再开 VS Code 的保存自动格式化（Prettier），团队风格从此不打架。

三、核心语法：记住一个公式就够了

3.1 心智模型：UI = f(state)

React 的全部思想一句话：界面是状态的函数。你不直接操作 DOM，只改数据（state），React 负责把界面更新到和数据一致。

flowchart LR
    S["state 变化<br/>setState"] --> R["React 重新执行组件函数<br/>得到新的虚拟 DOM"]
    R --> D["Diff：对比新旧虚拟 DOM<br/>找出最小差异"]
    D --> DOM["只把差异 patch 到真实 DOM"]

这就是为什么 React 代码里永远不要 document.getElementById 去改 DOM——绕过状态直接改界面，两边就对不上了。

3.2 组件与 JSX

组件就是一个返回 JSX 的函数。JSX 是「长得像 HTML 的 JS」，注意三条规则：标签必须闭合、属性用驼峰（className 不是 class）、JS 表达式放 {} 里：

function Welcome({ name }) {          // props 是父组件传进来的参数
  return <h1 className="title">你好, {name}!</h1>;
}

function App() {
  return <Welcome name="React" />;    // 组件像标签一样使用
}

3.3 state 与事件：让界面动起来

import { useState } from "react";

function Counter() {
  const [count, setCount] = useState(0);   // 声明状态：当前值 + 修改函数

  return (
    <button onClick={() => setCount(count + 1)}>
      点了 {count} 次
    </button>
  );
}

规则：props 是父组件给的（只读），state 是自己的（用 set 函数改）。数据流向永远是父 → 子，这叫单向数据流，是 React 排查问题比双向绑定框架容易的根本原因。

3.4 列表渲染与 key

function TodoList({ items }) {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.text}</li>   // key 用稳定 id，不要用 index！
      ))}
    </ul>
  );
}

3.5 useEffect：处理副作用

数据请求、定时器、订阅这类「和渲染无关的事」放 useEffect：

useEffect(() => {
  fetch("/api/todos")
    .then((r) => r.json())
    .then(setTodos);
}, []);   // 依赖数组为空 = 只在组件首次渲染后执行一次

四、踩坑故事：六个我真实掉进去过的坑

坑 1：setState 是「异步」的，连续 +1 只加了一次

// 想点一下加 3，结果只加了 1
setCount(count + 1);
setCount(count + 1);
setCount(count + 1);

原因：三次 count 读的都是本次渲染的旧值。改法：用函数式更新，每次拿到最新值：

setCount((c) => c + 1);
setCount((c) => c + 1);
setCount((c) => c + 1);   // 这次真的 +3

教训：新 state 依赖旧 state 时，永远用函数形式。

坑 2：useEffect 里 setState，死循环刷爆页面

useEffect(() => {
  setList([...list, newItem]);   // list 变了 → 重新渲染 → effect 又执行 → 死循环
}, [list]);

排查套路：页面卡死/请求刷屏，先找「effect 的依赖里有没有它自己改的东西」。解法通常是改用函数式更新把依赖摘掉：setList((l) => [...l, newItem])，依赖数组就能清空。

坑 3：列表 key 用 index，勾选状态全乱了

Todo 列表勾了第 1 项，删掉它之后，第 2 项变成「已勾选」——因为 key 用 index 时，React 按位置复用 DOM，删除一项后后面所有项位置错位，复用错了组件内部状态。key 必须用数据的稳定 id。

坑 4：直接改 state 对象，界面死活不更新

user.name = "新名字";    // 页面没反应！
setUser(user);           // 还是没反应——引用没变，React 认为没变化

React 靠引用比较判断要不要重渲染。正确姿势是造一个新对象：

setUser({ ...user, name: "新名字" });

数组同理：用 filter/map/concat 造新数组，不要 push/splice。

坑 5：定时器里的 stale closure（闭包旧值）

useEffect(() => {
  const timer = setInterval(() => {
    console.log(count);        // 永远是 0！
  }, 1000);
  return () => clearInterval(timer);
}, []);

effect 只在首次渲染执行，回调里捕获的 count 永远是首次渲染的旧值。解法：把 count 加进依赖数组，或用 useRef 保存最新值。这类 bug 不报错、只是数据不新鲜，最难查——ESLint 的 exhaustive-deps 规则能提前拦住大半，别随手关掉。

坑 6：在组件里定义组件，输入框每敲一个字就失焦

function Form() {
  const Input = () => <input />;   // 每次渲染都是全新组件，DOM 被销毁重建
  return <Input />;
}

组件定义必须放模块顶层。这个坑的典型症状是「input 输入一个字符就丢焦点」，看到这个词直接想到它。

五、底层原理：为什么 React 是这样设计的

前面六个坑，背规则可以避开，但理解原理才能「预判」。这一章讲透四件事：虚拟 DOM 与 Diff、Fiber 架构、渲染两阶段、Hooks 的实现。学完你会发现：第四节所有的坑，都是这四个原理的直接推论。

5.1 虚拟 DOM 与 Diff 算法：用 JS 对象换性能

虚拟 DOM 就是用普通 JS 对象描述界面长什么样（{ type: 'div', props: {...}, children: [...] }）。每次 state 变化，React 重新生成一棵新的虚拟 DOM 树，和旧的对比（Diff），只把差异更新到真实 DOM——直接操作 DOM 慢，操作 JS 对象快，这就是虚拟 DOM 的收益。

全量对比两棵树的算法复杂度是 O(n³)，一万个节点就是十亿次比较，不可用。React 用三条「妥协」策略把它降到 O(n)：

flowchart TB
    subgraph 策略["Diff 的三条妥协策略"]
        T["tree diff：只同层比较<br/>不跨层移动节点"]
        C["component diff：组件类型变了<br/>整棵子树直接销毁重建"]
        E["element diff：同层列表<br/>靠 key 识别 谁移动/新增/删除"]
    end
    T --> R["结果：O(n) 完成对比"]
    C --> R
    E --> R

三条策略各自对应一条实践纪律：

tree diff → 跨层级移动 DOM 节点代价极大，设计组件树时保持层级稳定；
component diff → 同一个位置不要渲染「类型忽变」的组件（<div> 和 <span> 来回切换），类型一变整棵重建；
element diff → 这就是坑 3 的原理：key 是 React 识别「哪个节点是哪个」的唯一依据，用 index 当 key，删除中间项后后面所有 key 全变，React 就把节点张冠李戴了。

5.2 Fiber 架构：把渲染拆成可中断的小任务

React 15 之前，更新是递归遍历组件树，一旦开始就不能停——组件树大了，一帧 16ms 里算不完，页面就掉帧卡顿。React 16 重写架构，引入 Fiber：

Fiber 是什么：每个组件对应一个 Fiber 节点，渲染工作被拆成一个个以 Fiber 为单位的小任务；
怎么连起来：节点之间不用递归，用链表（child 第一个子节点 / sibling 下一个兄弟 / return 父节点）——用指针代替调用栈，所以随时可以暂停、恢复、放弃；
双缓存：内存里同时存在两棵树——屏幕上正在显示的 current 树，和后台正在构建的 workInProgress 树。新树在后台慢慢算，算完一次性把指针切过去，用户永远看不到「渲染到一半」的界面。

flowchart LR
    subgraph 旧架构["React 15 栈调和"]
        A1["递归遍历整棵树<br/>不可中断"] --> A2["大树直接卡顿掉帧"]
    end
    subgraph 新架构["React 16+ Fiber"]
        B1["每个 Fiber 一个小任务<br/>可随时暂停让出主线程"] --> B2["高优先级任务插队<br/>（用户输入 > 列表渲染）"]
        B2 --> B3["workInProgress 树算完<br/>一次性切换"]
    end

时间切片带来的直接体验：输入框输入（高优先级）可以打断长列表渲染（低优先级），输入再也不卡。useTransition 就是把这个优先级能力开放给开发者——把「不紧急的更新」包进 startTransition，界面保持响应。

5.3 渲染两阶段：render 可中断，commit 不可中断

一次更新分两个阶段，分工严格：

flowchart LR
    subgraph R["render 阶段（可中断）"]
        R1["调用组件函数<br/>生成新虚拟 DOM"]
        R2["Diff，算出变更清单"]
    end
    subgraph C["commit 阶段（不可中断）"]
        C1["把变更一次性<br/>写入真实 DOM"]
        C2["执行 useLayoutEffect<br/>再异步执行 useEffect"]
    end
    R --> C

这一阶段划分解释了两个「为什么」：

为什么组件函数里不能有副作用（发请求、改全局变量）：render 阶段可中断、可重试、可能被调用多次，副作用会重复执行。所以副作用必须放 useEffect——它在 commit 之后执行，每次提交只跑一次。坑 2 的死循环本质也是没搞清这个边界：effect 里改 state 触发新一轮 render→commit→effect，链条首尾相接就成了循环。
为什么 setState 看起来是异步的（坑 1）：setState 只是「登记一个更新任务」，组件函数要等 React 调度到 render 阶段才重新执行。你在 setCount 之后立刻读 count，读到的当然是本次渲染的旧值。

5.4 Hooks 的实现：一条链表 + 调用顺序

Hooks 没有魔法。每个 Fiber 节点上挂着一条链表，组件每次调用一个 Hook（useState/useEffect/…），React 就顺着链表取下一个节点存状态：

flowchart LR
    F["Fiber 节点<br/>memoizedState"] --> H1["Hook 节点 1<br/>useState count"]
    H1 --> H2["Hook 节点 2<br/>useState text"]
    H2 --> H3["Hook 节点 3<br/>useEffect"]
    H3 --> N["null"]

关键：状态不是按变量名存的，是按调用顺序存的。第 n 次调用 useState，就拿链表上第 n 个节点。这就是「Hook 不能写在 if/循环里」这条铁律的唯一原因——条件调用会让本次渲染的调用顺序和上次错位，状态全部错位：

// ❌ 条件调用：show 为 false 时少调一次，后面所有 Hook 状态错位
if (show) {
  const [a, setA] = useState(0);
}
const [b, setB] = useState(0);

用一个 20 行的迷你实现体会一下原理：

// 极简版 useState：一个数组 + 一个游标
const hookStates = [];
let cursor = 0;

function useState(initial) {
  const i = cursor++;                    // 本次调用占第 i 个槽位
  hookStates[i] = hookStates[i] ?? initial;
  const setState = (v) => {
    hookStates[i] = typeof v === "function" ? v(hookStates[i]) : v;
    cursor = 0; render();                // 重置游标，重新渲染
  };
  return [hookStates[i], setState];
}

// 每次 render 前 cursor 归零，Hook 按调用顺序对号入座

真实 React 里这个数组换成 Fiber 上的链表、render 换成调度器触发，思想一模一样。也顺带解释了坑 5（stale closure）：effect 回调捕获的是「它创建那次渲染」的作用域，而 Hook 槽位里的状态早已更新——两者不是一份数据，于是读到旧值。

5.5 批量更新：多次 setState 合并成一次渲染

React 会把同一个事件循环里的多次 setState 合并（batching）成一次渲染，避免白白渲染三次。React 18 起连 Promise、setTimeout 里的更新也自动批量。坑 1 的「连续 +1 只加一次」正是批量更新的副产品：三次调用都基于同一个旧值计算，合并后只生效最后一次；函数式更新 setCount(c => c + 1) 之所以能正确累加，是因为每次计算都基于「上一个更新任务的结果」而不是旧快照。

5.6 一张图总结：从 setState 到屏幕更新

flowchart TB
    A["setState 登记更新任务"] --> B["Scheduler 调度<br/>按优先级插队/合并"]
    B --> C["render 阶段（可中断）<br/>沿 Fiber 链表逐个执行组件函数<br/>Hooks 按调用顺序取状态"]
    C --> D["生成 workInProgress 树<br/>Diff 出变更清单"]
    D --> E["commit 阶段（不可中断）<br/>一次性写入真实 DOM"]
    E --> F["执行 useEffect"]
    F -->|"effect 里又 setState"| A

回头看第四节的坑：坑 1 是批量更新、坑 2 是 render/commit 边界、坑 3 是 element diff、坑 4 是引用比较（Diff 的判断依据）、坑 5 是 Hooks 快照机制、坑 6 是 component diff（类型变=重建）。规则会过时，原理不会——这就是先学原理的价值。

六、主流 UI 组件库：选型对比

别从零写按钮和表格，组件库选一个用熟：

组件库	风格	适合场景	备注
Ant Design (antd)	企业级、组件全	中后台管理系统（国内事实标准）	文档中文友好，生态最厚
Material UI (MUI)	Google Material 风格	海外产品、工具类	定制性强
Ant Design Mobile	移动端	H5/混合 APP	与 antd 同门
Tailwind + Headless UI	原子化 CSS	定制化要求高的产品页	没有现成组件，只有样式积木
Chakra UI	简洁现代	快速原型	主题系统好用

中后台选 antd 基本不会错。三分钟搭出一个像样的页面：

import { Table, Button, Form, Input } from "antd";

function UserPage() {
  const columns = [
    { title: "姓名", dataIndex: "name" },
    { title: "邮箱", dataIndex: "email" },
  ];
  return (
    <>
      <Form layout="inline" onFinish={(v) => console.log(v)}>
        <Form.Item name="name" label="姓名"><Input /></Form.Item>
        <Button type="primary" htmlType="submit">查询</Button>
      </Form>
      <Table columns={columns} dataSource={[]} rowKey="id" />
    </>
  );
}

组件库避坑：不要混用两个重型组件库（打包体积爆炸）；版本升级先看迁移指南（antd 4→5 改了样式方案）；表单校验规则写在 rules 里而不是手写 if-else。

七、完整 Demo：一个 Todo App

把前面的知识拼起来——增删改查、状态提升、组件拆分，都在这 60 行里：

import { useState } from "react";

function App() {
  const [todos, setTodos] = useState([]);
  const [text, setText] = useState("");

  const add = () => {
    if (!text.trim()) return;
    setTodos((t) => [...t, { id: Date.now(), text, done: false }]);  // 新数组！
    setText("");
  };

  const toggle = (id) =>
    setTodos((t) => t.map((x) => (x.id === id ? { ...x, done: !x.done } : x)));

  const remove = (id) => setTodos((t) => t.filter((x) => x.id !== id));

  return (
    <div style={{ maxWidth: 400, margin: "40px auto" }}>
      <h1>Todo</h1>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={add}>添加</button>
      <ul>
        {todos.map((item) => (
          <li key={item.id}>
            <span
              onClick={() => toggle(item.id)}
              style={{ textDecoration: item.done ? "line-through" : "none" }}
            >
              {item.text}
            </span>
            <button onClick={() => remove(item.id)}>删除</button>
          </li>
        ))}
      </ul>
      <p>共 {todos.length} 项，完成 {todos.filter((x) => x.done).length} 项</p>
    </div>
  );
}
export default App;

注意里面处处是前面坑点的正确示范：setTodos 全部函数式更新、key 用 id、改对象用展开运算符造新对象。

八、AI 时代：怎么少写代码完成 APP 开发

写完上面这些，必须承认一件事：这篇博客里 80% 的代码，AI 现在都能直接生成。Todo、表单、表格页这类「模式明确」的代码，人的价值已经不在敲键盘上。我现在的前端开发流程变成了这样：

flowchart LR
    A["人：写清需求<br/>页面结构 / 字段 / 交互 / 接口契约"] --> B["AI：生成组件代码<br/>一次给完整页面而非碎片"]
    B --> C["人：Review + 跑起来验证<br/>重点看 state 设计和依赖数组"]
    C --> D["AI：按反馈迭代<br/>改样式 / 加校验 / 拆组件"]
    D --> E["人：集成进项目<br/>接真实接口 / 统一风格"]

几条实战经验：

描述越具体，代码越能直接用。「写个用户管理页」和「用 antd Table 写用户管理页，列：姓名/邮箱/状态，顶部一个内联查询表单，分页 pageSize 20，数据从 GET /api/users 拿」得到的代码质量天差地别——这和给实习生派活是一个道理。
让 AI 一次生成完整页面，而不是一次次要碎片。碎片代码的集成成本比生成成本高；整页生成后你再删改，快得多。
Review 的重点变了：语法 AI 很少错，要盯的是架构层面的东西——state 放哪层合不合理、useEffect 依赖有没有坑（本文第四节的坑 AI 也会犯）、组件拆分粒度、key 用没用 index。基本功越扎实，Review 越快越准——AI 淘汰的是只会写不会看的人。
工具形态：代码补全（Copilot）管「写着顺」；对话式 IDE（Cursor、Claude Code）管「整个功能」；v0.dev 这类管「从截图/描述直接出页面」。三者是不同粒度，按任务大小选。
APP 整体路径：需求描述 → AI 出页面原型 → 选定组件库统一风格 → AI 按接口文档接数据 → 人工处理鉴权、错误处理、边界情况。一个中后台 CRUD 类 APP，这个流程能把工期压到原来的三分之一。

九、延伸话题：为什么国内流行 Vue，海外是 React 统治

先校准这个说法：不是非黑即白——国内大厂核心产品用 React 的不少（蚂蚁的 Ant Design 就是 React 生态），海外 Laravel 社区也带起了一批 Vue 用户。但总体格局确实存在：国内中小厂、外包、移动端 H5 里 Vue 占比明显高，海外从创业公司到大厂 React 一家独大（npm 全球周下载量 React 常年是 Vue 的数倍）。原因是多层的：

flowchart TB
    subgraph 历史时机["历史时机（2014-2016）"]
        H1["Vue 2014 年发布<br/>作者尤雨溪是华人<br/>中文文档从第一天就是一流的"]
        H2["恰逢国内移动互联网爆发<br/>海量新人入行<br/>需要低门槛框架"]
        H3["AngularJS 在国内已流行<br/>Vue 继承模板+双向绑定心智<br/>平滑承接"]
    end
    subgraph 生态锁定["生态锁定"]
        E1["饿了么 Element UI（2016）<br/>阿里系采用 Vue"]
        E2["Element / Ant Design Vue / Vant<br/>中后台组件库成套"]
        E3["uni-app 用 Vue 语法写小程序<br/>吃透国内小程序红利"]
    end
    subgraph 正循环["正循环"]
        L1["Vue 门槛低 → 培训机构主教 Vue"]
        L2["会 Vue 的人多 → 企业招 Vue 便宜快"]
        L3["企业用 Vue → 岗位多 → 新人继续学 Vue"]
    end
    subgraph 海外对照["海外对照"]
        O1["Facebook 背书 + 自家产品验证"]
        O2["React Native 吃下跨端"]
        O3["Next.js 等元框架强化生态"]
        O4["大厂招聘需求锁定人才供给"]
    end
    H1 & H2 & H3 --> 国内["国内 Vue 流行"]
    E1 & E2 & E3 --> 国内
    L1 --> L2 --> L3 --> 国内
    O1 & O2 & O3 & O4 --> 海外["海外 React 统治"]

拆开看，几个关键变量：

文档与语言的近因效应。Vue 的中文文档从发布第一天就是母语级质量，而 React 中文文档长期靠社区翻译、滞后且质量参差。对自学者，这个差异是决定性的——学什么框架，往往就是「哪份文档看得懂」决定的。
生态位被谁先占住。2016 年饿了么开源 Element UI、阿里系大量采用 Vue，中后台组件库（Element/Ant Design Vue/Vant）成套出现，「Vue + Element」成了国内中后台的标准答案。海外对应位置被 React 的 Ant Design（蚂蚁国际版反哺）、MUI、Next.js 占住。
培训机构的放大器作用。Vue 模板语法接近 HTML、双向绑定写表单快、SFC 单文件组件直观——对从后端/jQuery 转前端的人极其友好，培训周期短、就业反馈快，于是机构主教 Vue，供给端被锁定。
移动端的分野。海外跨端 = React Native，进一步巩固 React；国内跨端的真正战场是小程序，而 uni-app 这类「用 Vue 语法写小程序」的框架吃掉了这块红利，又反过来强化了 Vue 心智。
React 的门槛是真实的。JSX、函数式思维、不可变数据、Hooks 的心智负担（本文四、五章的坑就是证据），对英语文档和工程化基础都有要求——这在海外是标配，在国内快速扩张期的团队里是成本。

对学习者的启示：两个框架的核心思想（组件化、状态驱动 UI、虚拟 DOM）完全相通，Vue3 的组合式 API 和 React Hooks 已经趋同。学会一个，另一个一周能上手——别把宝押在框架上，押在原理上。而且 AI 时代框架差异进一步被抹平：AI 两个都写得很好，你需要的只是读懂它写的是什么的判断力。

十、思考与感悟

1. React 的本质不是语法，是「UI = f(state)」这个心智模型。 Hooks 语法三天能学会，但「什么该进 state、state 放哪层、如何从 state 推导 UI」要想清楚需要几个月。判断一个人 React 水平，不要问语法，问他「这个状态你会放在哪个组件」。

2. 坑大多是「引用」和「时机」两类。 本文六个坑归个类：坑 1/3/4 是没理解引用比较（key 复用、state 不可变），坑 2/5/6 是没理解渲染时机（effect 何时跑、闭包捕获哪次渲染的值）。把「每次渲染都是一次全新函数调用」这句话想透，大半坑自动消失。

3. 组件库是杠杆，不是拐杖。 antd 让中后台效率翻倍，但只会在组件里塞业务逻辑的人，换个库就废了。组件库之上是交互设计，之下是 React 基本功，两头都得懂一点。

4. AI 时代，「读代码」比「写代码」更值钱。 生成不再稀缺，判断力才稀缺。能一眼看出 AI 生成的代码里 useEffect 依赖少了、state 设计反了的人，会把 AI 用得越来越顺手；只会复制粘贴的人，会被 AI 生成的坑埋掉。学基础不是为了手写，是为了 Review。

十一、学习路线建议

第一周：搭好 Vite 环境，跟着官方教程（react.dev 的互动教程质量很高）过完 JSX/组件/state。
第二周：手写 Todo App，故意踩一遍第四节的坑（比如把 key 换成 index 看看怎么乱），踩过才算学会。
第三周：加路由（React Router）和组件库（antd），做一个有列表页+表单页的两页应用。
第四周：接一个真实后端 API，处理 loading/错误/空数据三种状态——真实项目和 Demo 的差距全在这里。
进阶：自定义 Hook 抽逻辑、Context/Zustand 管全局状态、性能优化（memo/useMemo）、Next.js 服务端渲染。

参考资料：

React 官方文档（react.dev）——新版文档质量极高，教程可交互

Vite 官方文档

Ant Design 官方文档

React Router 文档

前端 UI 开发从入门到精通（Vue 技术栈）：HTTP、CSS 与主流组件库实战

Tue, 16 Aug 2022 09:00:00 +0800

前端 UI 开发从入门到精通（Vue 技术栈）：HTTP、CSS 与主流组件库实战

目标读者：会写一点 Vue，但面对「这个布局怎么调」「这个接口怎么接」「组件库样式怎么改」还是会心里发虚的同学。
姊妹篇：《前端开发从入门到精通：JavaScript → TypeScript → Vue 3 实战指南》讲的是语言内功，这篇讲的是 UI 实战。

先说一句可能得罪人的话：很多前端写了两三年业务，其实一直在「UI 开发的入门区」打转。会调组件库的 API ≠ 会做 UI 开发。真正的分水岭在于：你能不能在没有设计稿的情况下把页面排得不难看，能不能在接口报错时五分钟内定位是前端问题还是后端问题，能不能在组件库不满足需求时优雅地绕过去而不是对着它硬改。

这篇文章讲三块内容，对应 UI 开发的三个基本功：

flowchart LR
    A["HTTP<br/>数据从哪来"] --> D["UI 页面"]
    B["CSS<br/>页面长什么样"] --> D
    C["组件库<br/>用什么零件搭"] --> D
    D --> E["一个完整页面<br/>= 数据 + 布局 + 组件"]
    E --> F["精通<br/>= 能排错 能绕坑 能设计"]

HTTP：页面不是孤立的，数据要从服务器来。请求发不出去、发出去收不到、收到了不渲染，每一种「不工作」背后都是一类知识。
CSS：UI 开发的半壁江山。大部分人不是不会 CSS，而是「会一半」——能写出来，但不知道为什么生效、为什么失效。
组件库：Element Plus、Ant Design Vue、Naive UI 怎么选，怎么用出「高级感」，以及怎么避开它们各自的坑。

老规矩，知识点之外，我会穿插真实的踩坑故事和可以运行的 Demo。

第一篇 HTTP：数据是怎么到页面上的

1.1 一次请求的完整旅程

很多新人对 HTTP 的理解停留在「axios.get(url) 然后 .then 拿数据」。我们先看看这一次调用背后发生了什么：

sequenceDiagram
    participant P as 页面组件
    participant A as axios 实例
    participant I as 请求拦截器
    participant B as 浏览器
    participant S as 后端服务
    P->>A: http.get('/api/users')
    A->>I: 带上 token、组装 baseURL
    I->>B: 发起真实网络请求
    B->>S: DNS 解析 → TCP 连接 → TLS 握手 → 发送报文
    S-->>B: 状态码 + 响应体
    B-->>I: 进入响应拦截器
    I-->>A: 统一解包 { code, data, message }
    A-->>P: 返回 data 或抛出业务错误

这张图里每一个环节都可能出错，而「精通」的标志就是：看到现象，能立刻判断问题出在哪一层。

请求根本没发出去（Network 面板里看不到）→ 你的 JS 代码有问题，或者拦截器里 throw 了。
请求发出去了，状态码是 4xx/5xx → 后端或网关的问题，但参数对不对还得你自己查。
状态码 200，但页面上没数据 → 响应拦截器解包逻辑或组件渲染的问题。
状态码是 (blocked:cors) 或者红色的 OPTIONS → 跨域，见下面的踩坑故事。

1.2 先懂协议，再谈封装

不需要背 RFC，但这几件事必须形成肌肉记忆：

方法语义：GET 查询、POST 创建、PUT 全量更新、PATCH 局部更新、DELETE 删除。语义不止是给后端看的——GET 请求会被浏览器和 CDN 缓存、会被浏览器历史记录保留，你拿 GET 做删除操作，等于给自己埋雷。
状态码：200（成功）/ 301 302（重定向）/ 400（参数错，你的锅）/ 401（没登录或 token 过期）/ 403（登录了但没权限）/ 404（路径错）/ 500（后端炸了）/ 502 504（网关或后端挂了）。
Content-Type：application/json 是今天的默认；multipart/form-data 用于文件上传。踩坑点：用 axios 上传文件时不要手动设置 Content-Type，浏览器需要自动生成带 boundary 的头部，手动设置反而会让后端解析不了。

1.3 一个生产可用的请求封装（Demo）

下面是我这些年沉淀下来的一版 axios 封装骨架，去掉公司特定逻辑后依然可直接用：

// src/utils/http.ts
import axios, { AxiosError, type AxiosRequestConfig } from 'axios'
import { ElMessage } from 'element-plus'

// 后端统一响应格式：{ code: 0, data: T, message: 'ok' }
interface ApiResponse<T = unknown> {
  code: number
  data: T
  message: string
}

const http = axios.create({
  baseURL: import.meta.env.VITE_API_BASE ?? '/api',
  timeout: 15000,
})

// 请求拦截：带 token
http.interceptors.request.use((config) => {
  const token = localStorage.getItem('token')
  if (token) config.headers.Authorization = `Bearer ${token}`
  return config
})

// 响应拦截：统一解包 + 统一错误提示
http.interceptors.response.use(
  (res) => {
    const body = res.data as ApiResponse
    if (body.code === 0) return body.data          // 成功：直接把 data 交出去
    if (body.code === 401) {
      // token 过期：清登录态，跳登录页
      localStorage.removeItem('token')
      location.href = '/login'
      return Promise.reject(new Error(body.message))
    }
    ElMessage.error(body.message || '请求失败')
    return Promise.reject(new Error(body.message))
  },
  (err: AxiosError) => {
    // 网络层错误：超时、断网、5xx
    if (err.code === 'ECONNABORTED') ElMessage.error('请求超时，请重试')
    else ElMessage.error(err.response ? `服务异常(${err.response.status})` : '网络异常')
    return Promise.reject(err)
  },
)

export function get<T>(url: string, config?: AxiosRequestConfig) {
  return http.get<unknown, T>(url, config)
}
export function post<T>(url: string, data?: unknown, config?: AxiosRequestConfig) {
  return http.post<unknown, T>(url, data, config)
}

用法：

import { get } from '@/utils/http'

interface User { id: number; name: string; email: string }

const users = await get<User[]>('/users')   // 拿到的就是解包后的 data

这个封装的核心思想只有一句话：让业务代码只关心成功路径。解包、错误提示、登录跳转全部收敛到拦截器里，组件里不需要到处写 if (res.code === 0)。

1.4 踩坑故事一：那个只在测试环境出现的跨域

现象：本地开发一切正常，部署到测试环境后所有接口报 CORS 错误，后端同事说「我配了 Access-Control-Allow-Origin: * 了啊」。

排查：打开 Network 面板，发现带 Authorization 头的请求之前，浏览器先发了一个 OPTIONS 预检请求，而预检请求返回 404——Nginx 配置里只把 GET/POST 转发给了后端，OPTIONS 落到了静态文件规则上。

教训，一次记住三个知识点：

flowchart TD
    A["浏览器要发跨域请求"] --> B{"是简单请求吗？<br/>GET/POST + 无自定义头<br/>+ 特定 Content-Type"}
    B -->|"是"| C["直接发真实请求<br/>靠响应头 ACAO 放行"]
    B -->|"否（比如带 Authorization）"| D["先发 OPTIONS 预检"]
    D --> E{"预检返回 2xx 且<br/>CORS 头齐全？"}
    E -->|"是"| C
    E -->|"否（404/405/缺头）"| F["报 CORS 错误<br/>真实请求根本没发"]
    style F fill:#ffe4e1

带自定义头（如 Authorization）的请求一定会触发预检。
预检失败时，真实请求根本没有发出，后端日志里查不到，容易误判成「后端没问题」。
开发环境不跨域是因为 Vite 的 server.proxy 帮你转发了——代理方案只在开发环境存在，上线后跨域问题会准时出现。

1.5 踩坑故事二：疯狂抖动的搜索框

现象：搜索建议框，用户每敲一个字就发一次请求。结果因为网络延迟，先发的请求后返回，后返回的旧结果覆盖了新结果，搜索「北京」时页面一闪而过地显示「北」的结果。

解法，三板斧，按成本从低到高：

import { refDebounced } from '@vueuse/core'  // 或者手写防抖

// 方案 1：防抖，减少请求次数（300ms 内不重复触发）
const keyword = ref('')
const debouncedKeyword = refDebounced(keyword, 300)

// 方案 2：竞态防护，只接受最后一次请求的结果
let seq = 0
watch(debouncedKeyword, async (kw) => {
  const mySeq = ++seq
  const list = await get<Suggestion[]>('/suggest', { params: { kw } })
  if (mySeq !== seq) return    // 这期间又发了新请求，丢弃旧结果
  suggestions.value = list
})

// 方案 3：AbortController 直接取消旧请求（axios 支持 signal）

真实项目里我通常 1 + 2 组合用。方案 3 最彻底，但要小心把取消错误误报成「请求失败」的 toast。

1.6 思考：请求封装是在封装「约定」

很多人封装 axios 只是在封装函数调用，其实真正值钱的是把团队协作约定固化进代码：token 放哪个头、错误码怎么定、401 怎么处理、超时多久算超时。这些约定一旦写进拦截器，新人在第一天就「被迫」遵守了整个团队的规范。好的基础设施，是让正确的事情自动发生。

第二篇 CSS：UI 开发的半壁江山

2.1 先建立一个心智模型

CSS 难学的根源是：它不是一个「语言」，而是一堆相互独立的机制的合集。布局、层叠、盒模型、格式化上下文各自为政，你以为是玄学的问题，拆开看都是明确的规则。

mindmap
  root((CSS 四大机制))
    盒模型
      content-box
      border-box
      margin 折叠
    布局
      normal flow 文档流
      flex 一维布局
      grid 二维布局
      position 定位
    层叠
      优先级 选择器权重
      继承
      z-index 与层叠上下文
    格式化上下文
      BFC
      IFC

入门阶段我建议只抓两条主线：盒模型 + flex/grid 布局，能解决 90% 的日常问题；层叠和 BFC 等踩到坑再回头补。

2.2 盒模型：一切从盒子开始

flowchart LR
    subgraph box["border-box 盒模型"]
        M["margin<br/>(外边距，不算进盒子)"] --> B["border<br/>边框"]
        B --> P["padding<br/>内边距"]
        P --> C["content<br/>内容"]
    end

一句话规则：项目全局设置 box-sizing: border-box，然后你写的 width: 200px 就是「视觉上的 200px 宽」，padding 和 border 往内挤，不再往外扩。这条规则值得写进每个项目的 reset 里：

*, *::before, *::after {
  box-sizing: border-box;
}

2.3 布局：Flex 管一维，Grid 管二维

记住这个分工就不会纠结选型：

一排或一列的元素（导航栏、表单行、卡片列表的某一排）→ Flex。
有行有列的整体结构（页面骨架、照片墙、仪表盘）→ Grid。

Flex 日常 90% 的用法就这几个：

.toolbar {
  display: flex;
  align-items: center;      /* 交叉轴居中（垂直居中） */
  justify-content: space-between; /* 主轴两端对齐 */
  gap: 12px;                /* 元素间距，别再给子元素写 margin-right 了 */
}

.toolbar .spacer {
  flex: 1;                  /* 占满剩余空间，把后面的元素顶到最右 */
  min-width: 0;             /* ⚠️ 踩坑点，见 2.5 */
}

Grid 搭页面骨架，三行 CSS 出「头-侧-主」经典布局：

.admin-layout {
  display: grid;
  height: 100vh;
  grid-template:
    "header header" 56px
    "aside  main"   1fr
    / 220px 1fr;
}
.admin-layout > header { grid-area: header; }
.admin-layout > aside  { grid-area: aside; }
.admin-layout > main   { grid-area: main; overflow: auto; }

grid-template 的「ASCII 画」语法是我认为 CSS 里最优雅的设计之一——布局长什么样，代码里就画成什么样。

2.4 现代 CSS 三件套：变量、容器查询、:has()

如果你的项目不再需要兼容 IE（2026 年了，真的不需要了），这三样东西能显著减少 JS 代码量：

:root {
  --primary: #409eff;
  --radius: 6px;
}
[data-theme='dark'] {
  --primary: #79bbff;
}

.btn {
  background: var(--primary);
  border-radius: var(--radius);
}

/* :has() —— 终于可以「父选子」了 */
.form-item:has(.el-input.is-error) {
  border-color: red;
}

CSS 变量配合 Vue 更是绝配——在组件里改一个变量，整个子树的样式跟着变，比传 props 干净得多：

<template>
  <section :style="{ '--card-color': themeColor }">
    <slot />
  </section>
</template>

2.5 踩坑故事三：flex: 1 了，为什么还是不生效

现象：侧边栏固定宽度 + 主内容 flex: 1 的经典布局，主内容里放了一张表格，结果表格把主内容越撑越宽，整个页面出现了横向滚动条。

原因：flex 子项的默认 min-width 是 auto，意思是「最小也不能比内容窄」。表格内容很宽，flex: 1 就压不住它。

解法：一行代码，但不知道的人能查一下午：

.main { flex: 1; min-width: 0; overflow: auto; }

同理，grid 里是 minmax(0, 1fr)。这是前端面试的高频题，更是实际项目的高频坑。

2.6 踩坑故事四：z-index: 9999 的军备竞赛

现象：项目里的 z-index 从 10 涨到 100，再到 999、9999，最后有人写了 z-index: 2147483647（32 位整数最大值），结果弹窗还是被遮罩盖住。

原因：z-index 只在同一个层叠上下文内比较。某个父元素一旦因为 transform、opacity < 1、position: fixed 等属性创建了新的层叠上下文，它内部天大的 z-index 也突破不了父级的层级。

flowchart TD
    R["根层叠上下文"] --> A["父容器 A<br/>z-index: 10<br/>(因 transform 成为新层叠上下文)"]
    R --> B["遮罩层 B<br/>z-index: 100"]
    A --> C["弹窗 C<br/>z-index: 99999999<br/>❌ 依然被 B 盖住"]
    style C fill:#ffe4e1

解法：别玩军备竞赛。Vue 项目里弹窗、通知这类组件一律用 <Teleport to="body"> 挂到 body 下，跳出业务 DOM 的层叠上下文，然后从一份常量表里管理有限的几个层级：

// src/constants/z-index.ts —— 全项目只允许用这几个值
export const Z_INDEX = {
  dropdown: 1000,
  sticky: 1020,
  overlay: 1030,
  modal: 1040,
  toast: 1050,
} as const

2.7 踩坑故事五：scoped 样式改不动组件库

现象：想改 Element Plus 按钮的圆角，在 .vue 文件里写了 .el-button { border-radius: 20px; }，毫无效果。

原因：Vue 的 scoped 会给你的选择器加上 [data-v-xxx] 属性后缀，而组件库渲染出来的 DOM 上没有这个属性，选择器匹配不上。

解法：用深度选择器 :deep()：

<style scoped>
/* ✅ 正确：穿透 scoped，作用到子组件内部 DOM */
.my-page :deep(.el-button) {
  border-radius: 20px;
}

/* 注意：前面最好带一个自己页面的类名，避免穿透后污染全局 */
</style>

更进一步的感悟：单组件改样式用 :deep()，但如果是全局性的设计调整（比如全公司项目按钮都用 20px 圆角），应该用组件库的 CSS 变量定制（见第三篇），而不是到处写覆盖。覆盖样式是技术债，CSS 变量才是正路。

2.8 一个完整的小 Demo：响应式卡片列表

把上面讲的 flex/grid、CSS 变量、响应式串起来：

<template>
  <div class="card-grid">
    <article v-for="item in list" :key="item.id" class="card">
      <h3>{{ item.title }}</h3>
      <p>{{ item.desc }}</p>
    </article>
  </div>
</template>

<style scoped>
.card-grid {
  /* 自动填充：每列至少 260px，剩下的均分。不需要媒体查询！ */
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
  gap: 16px;
  padding: 16px;
}
.card {
  border: 1px solid var(--border-color, #e4e7ed);
  border-radius: 8px;
  padding: 16px;
  transition: box-shadow 0.2s;
}
.card:hover {
  box-shadow: 0 4px 16px rgb(0 0 0 / 10%);
}
</style>

repeat(auto-fill, minmax(260px, 1fr)) 这一行值得抄进你的代码库：一行 CSS 实现「宽屏四列、窄屏一列」的响应式，不需要任何媒体查询和 JS。

2.9 思考：CSS 的功夫在「约束」不在「技巧」

年轻时我以为 CSS 高手是知道很多冷门属性的人。后来带项目才发现，CSS 写得好的人，是给自己设了约束的人：颜色只用变量表里那十几个、间距只用 4 的倍数、z-index 只用常量表里的值。没有约束的自由发挥，三个月后就变成没人敢动的样式屎山。这其实也是设计系统（Design System）的思想雏形。

第三篇主流 UI 组件库：选型、驾驭与避坑

3.1 2026 年的 Vue 组件库格局

flowchart TD
    Q{"你的项目是什么类型？"}
    Q -->|"中后台管理系统"| A["Element Plus<br/>或 Ant Design Vue"]
    Q -->|"追求现代 DX 和 TypeScript"| B["Naive UI"]
    Q -->|"Material Design 风格 / 海外项目"| C["Vuetify"]
    Q -->|"高度定制设计 / 自有设计体系"| D["无样式方案<br/>Headless UI / Radix Vue<br/>+ Tailwind CSS"]

逐个说说我深度使用后的体感：

Element Plus：国内中后台的事实标准。生态最大、资料最多、招人最好招。缺点是默认样式有点「年代感」，以及某些复杂组件（表格、表单）的细节坑比较多。团队项目、要交接给别人的项目，选它不会错。
Ant Design Vue：蚂蚁设计体系的 Vue 移植版，设计规范完整、文档里连「什么时候该用什么组件」都讲了。表单项的校验体验比 Element Plus 细腻。缺点：Vue 版毕竟是移植，更新节奏和细节打磨略逊于 React 版。
Naive UI：一个「很有性格」的库——TypeScript 原生写成，主题系统全部走 JS/TS（不是 CSS 变量），配合 Volar 类型提示非常爽。个人项目、新项目我首推它。缺点是生态相对小，遇到问题搜答案没 Element Plus 那么容易。
Vuetify：Material Design 的完整实现，功能大而全。海外项目或甲方指定 Material 风格时用。包体积偏大，需要做好按需引入。

3.2 踩坑故事六：一次「手贱」升级引发的全站样式错乱

现象：pnpm update 顺手把 Element Plus 从 2.3 升到了 2.7，页面上所有 el-select 的下拉框宽度和位置全乱了。

原因：Element Plus 在中间版本重构了下拉浮层的实现（从旧的 popper 换成新版 floating 机制），类名和结构都变了，我们项目里靠 :deep(.el-select-dropdown) 写的覆盖样式全部失效。

教训，三条：

组件库锁版本：package.json 里组件库版本号不要带 ^，写死，升级走单独 PR，升级前把 CHANGELOG 里的 Breaking Changes 看完。
少写 deep 覆盖，多用官方变量：Element Plus 2.x 大部分视觉定制都能通过 CSS 变量完成：

// styles/element-theme.scss —— 官方推荐的定制方式
@forward 'element-plus/theme-chalk/src/common/var.scss' with (
  $colors: ('primary': ('base': #6c5ce7)),
  $border-radius: ('base': 8px),
);

给 UI 留回归测试的预算：哪怕只是几张关键页面的截图对比（Playwright 的 toHaveScreenshot()），也能让这类升级从「全站翻车」变成「CI 变红，改完再发」。

3.3 踩坑故事七：表格一万行，页面卡成 PPT

现象：后端一次返回了一万条数据（「反正前端会分页的嘛」），el-table 直接渲染，页面滚动时帧率掉到个位数。

解法路线图：

flowchart TD
    A["大数据量表格卡顿"] --> B{"能说服后端分页吗？"}
    B -->|"能，首选"| C["服务端分页<br/>每页 20-50 条"]
    B -->|"不能，数据必须一次展示"| D["虚拟滚动<br/>el-table-v2 / vxe-table"]
    D --> E{"还需要复杂单元格？"}
    E -->|"是"| F["vxe-table<br/>虚拟滚动 + 复杂表格之王"]
    E -->|"否，纯展示"| G["el-table-v2<br/>官方虚拟表格"]

几句实在话：

长列表性能问题，第一解永远是分页。一万条数据对人没有任何浏览价值，只有检索价值。
真要全量展示，普通 el-table 趁早放弃，直接上虚拟滚动（只渲染可视区域的几十行 DOM）。
表格重渲染还常因为每一行都内联了处理函数和作用域插槽，数据量大时把行组件抽出来 + v-memo 能再救一把。

3.4 踩坑故事八：表单校验「有时候不触发」

现象：el-form 的校验规则明明写了，用户快速输入时偶尔能绕过校验提交。

原因：两个叠加问题——表单项的 prop 和 v-model 绑定的字段名不一致（校验根本没绑定上），以及提交时没有 await formRef.validate()，直接发了请求。

正确姿势，背下来这个模板：

<template>
  <el-form ref="formRef" :model="form" :rules="rules">
    <!-- prop 必须等于 form 里的字段名，一字不差 -->
    <el-form-item label="邮箱" prop="email">
      <el-input v-model="form.email" />
    </el-form-item>
  </el-form>
</template>

<script setup lang="ts">
import type { FormInstance, FormRules } from 'element-plus'

const formRef = ref<FormInstance>()
const form = reactive({ email: '' })
const rules: FormRules = {
  email: [
    { required: true, message: '邮箱必填', trigger: 'blur' },
    { type: 'email', message: '邮箱格式不对', trigger: 'blur' },
  ],
}

async function submit() {
  // ✅ 校验不过直接 return，永远不要让请求绕过校验
  const valid = await formRef.value?.validate().catch(() => false)
  if (!valid) return
  await post('/users', form)
}
</script>

3.5 综合 Demo：一个「五脏俱全」的用户管理页

把三篇内容合在一起：HTTP 封装拿数据、Grid/Flex 做布局、Element Plus 出组件。这是中后台最常见的页面形态，也是检验三项基本功的试金石：

<template>
  <div class="user-page">
    <!-- 工具栏：Flex 布局，左侧搜索，右侧操作 -->
    <div class="toolbar">
      <el-input
        v-model="keyword"
        placeholder="搜索用户名"
        clearable
        style="width: 240px"
        @input="onSearch"
      />
      <el-button type="primary" @click="openCreate">新建用户</el-button>
    </div>

    <!-- 表格：服务端分页 -->
    <el-table v-loading="loading" :data="users" stripe>
      <el-table-column prop="name" label="姓名" />
      <el-table-column prop="email" label="email" show-overflow-tooltip />
      <el-table-column label="操作" width="160">
        <template #default="{ row }">
          <el-button link type="primary" @click="openEdit(row)">编辑</el-button>
          <el-button link type="danger" @click="remove(row)">删除</el-button>
        </template>
      </el-table-column>
    </el-table>

    <el-pagination
      v-model:current-page="page"
      v-model:page-size="pageSize"
      :total="total"
      layout="total, prev, pager, next"
      @current-change="fetchUsers"
    />
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { ElMessageBox, ElMessage } from 'element-plus'
import { get, post } from '@/utils/http'

interface User { id: number; name: string; email: string }

const users = ref<User[]>([])
const total = ref(0)
const page = ref(1)
const pageSize = ref(20)
const keyword = ref('')
const loading = ref(false)

let seq = 0   // 竞态防护：只认最后一次请求
async function fetchUsers() {
  const mySeq = ++seq
  loading.value = true
  try {
    const res = await get<{ list: User[]; total: number }>('/users', {
      params: { page: page.value, size: pageSize.value, kw: keyword.value },
    })
    if (mySeq !== seq) return
    users.value = res.list
    total.value = res.total
  } finally {
    if (mySeq === seq) loading.value = false
  }
}

let timer: ReturnType<typeof setTimeout>
function onSearch() {
  clearTimeout(timer)
  timer = setTimeout(() => { page.value = 1; fetchUsers() }, 300)  // 防抖
}

async function remove(row: User) {
  await ElMessageBox.confirm(`确认删除 ${row.name}？`, '警告', { type: 'warning' })
  await post(`/users/${row.id}/delete`)
  ElMessage.success('已删除')
  fetchUsers()
}

onMounted(fetchUsers)
</script>

<style scoped>
.user-page {
  padding: 16px;
}
.toolbar {
  display: flex;
  justify-content: space-between;
  align-items: center;
  margin-bottom: 16px;
}
</style>

这个页面看起来平平无奇，但里面藏着前面讲的所有功课：请求解包、loading 状态、防抖、竞态防护、服务端分页、flex 工具栏、scoped 样式。「精通」从来不是会多少奇技淫巧，而是这些基本功每一环都不掉链子。

第四篇从「会用」到「精通」：我的几点感悟

4.1 UI 的本质是状态，样式是状态的投影

写久了你会发现，一个页面真正的复杂度不在布局，而在状态：加载中、为空、加载失败、部分成功、无权限、已过期……新手只设计「一切正常」的那个画面，老手写组件前先列状态机：

stateDiagram-v2
    [*] --> Loading: 进入页面
    Loading --> Empty: 请求成功 数据为空
    Loading --> Success: 请求成功 有数据
    Loading --> Error: 请求失败
    Error --> Loading: 点击重试
    Success --> Loading: 刷新/搜索

每个状态对应的 UI 都提前想好，页面就永远不会有「白屏」「转圈转到天荒地老」这种低级体验问题。

4.2 别和组件库对着干

我年轻时花过两周时间，试图把 Element 的表格改成设计师画的「无边框卡片式表格」，覆盖了上百行样式，升级到下个版本全废了。后来的做法是：在组件库的设计体系内做选择，而不是对抗它。设计师给的稿子和组件库默认风格差距大时，拿着组件库的主题定制能力去和设计谈，99% 的情况能在「改三个 CSS 变量」的范围内达成一致。剩下 1% 真正需要高度定制的场景，那就该上无样式方案（Headless UI + Tailwind），而不是魔改有样式库。

4.3 学习路线建议

flowchart LR
    A["第 1-2 个月<br/>HTTP 基础 + flex/grid<br/>能独立写出页面"] --> B["第 3-6 个月<br/>吃透一个组件库<br/>+ 请求封装 + 表单表格"]
    B --> C["第 6-12 个月<br/>性能 虚拟滚动<br/>主题定制 设计系统"]
    C --> D["一年以后<br/>组件设计本身<br/>给团队写基础设施"]

几个反直觉的建议：

CSS 不要靠看视频学，靠调。把你欣赏的网站用 DevTools 打开，把它的布局一层层拆出来，比任何课程都快。
组件库文档要通读一遍，不是背 API，而是知道「它有什么」。不知道有 el-table-v2 的人，遇到性能问题只会想到魔改。
每踩一个坑，写三条笔记：现象、根因、以后怎么一眼认出它。这篇文章里的故事，就是这么攒出来的。

结语

回到开头那张图：UI 页面 = 数据 + 布局 + 组件。HTTP 决定数据来不来得了，CSS 决定页面好不好看，组件库决定你搭得快不快。三样都是「入门一个月、精通好几年」的东西，但好在它们的学习曲线有一个共同点——坑是有限集。本文里的八个坑，你每绕开一个，就离精通近了一步。

祝你的页面没有横向滚动条，弹窗永远在最上层。

前端开发从入门到精通：JavaScript → TypeScript → Vue 3 实战指南

Wed, 10 Aug 2022 09:00:00 +0800

前端开发从入门到精通：JavaScript → TypeScript → Vue 3 实战指南

目标读者：会一点 HTML/CSS，想系统进入前端世界；或者写过大半年 Vue，但总觉得「代码能跑，心里没底」的同学。

这篇文章是我这些年写前端、带新人、修线上事故的一份复盘。它不讲完所有 API（MDN 和官方文档做得比我好），而是讲三件事：

主干知识：每个阶段真正重要的 20% 是什么。
踩坑故事：我自己和身边人真实踩过的坑，比知识点本身更值钱。
思考与感悟：为什么这条路线是 JavaScript → TypeScript → Vue 3，而不是反过来。

先给一张全文的路线图：

flowchart LR
    A["HTML / CSS<br/>页面骨架与样式"] --> B["JavaScript<br/>让页面动起来"]
    B -->|"语言内功"| C["执行模型<br/>作用域 闭包 原型<br/>事件循环 异步"]
    C --> D["TypeScript<br/>类型系统<br/>编译期排错"]
    D --> E["Vue 3<br/>响应式 + 组件化"]
    E --> F["工程化<br/>Vite / Pinia / Router"]
    F --> G["真实项目<br/>能写 能改 能扛事"]

很多新人想跳过 B 和 D 直接学 E，结果写 setup 里的每一行代码都像在背课文。框架是皮，语言是骨。这篇文章的顺序，就是我认为唯一正确的顺序。

第一篇 JavaScript：先把语言的骨头长出来

1.1 JavaScript 到底是什么

一句话版本：一门单线程、基于事件循环、动态类型的脚本语言。

flowchart TB
    subgraph 浏览器
        A["调用栈 Call Stack<br/>同步代码在这里执行"]
        B["宏任务队列<br/>setTimeout / setInterval / IO"]
        C["微任务队列<br/>Promise.then / queueMicrotask"]
        D["Event Loop"]
    end
    A -->|"栈空了就问 D"| D
    D -->|"先清空"| C
    C -->|"清空了再取"| B
    B --> A

「单线程」是理解 JavaScript 一切怪异行为的总钥匙：因为它只有一个调用栈，所以耗时操作绝对不能阻塞它，于是有了回调、Promise、async/await 这一整条异步进化链。

1.2 事件循环：一道面试题背后的真功夫

先看这段代码，你猜输出是什么？

console.log('1');

setTimeout(() => console.log('2'), 0);

Promise.resolve().then(() => console.log('3'));

console.log('4');

答案是 1 4 3 2。规则只有两条：

同步代码在调用栈里，先跑完。
栈空之后，先清空所有微任务，再取一个宏任务。

踩坑故事 1：一个 0ms 的 setTimeout 引发的「灵异事件」

早年我维护一个老后台系统，有个 bug 时好时坏：弹窗打开后表单偶尔是空的。翻代码发现数据加载和弹窗渲染是两拨人写的，中间靠一个 setTimeout(..., 0) 「协调顺序」。它的潜台词是「让数据先加载完」——但 0ms 宏任务只是排到下一轮，数据请求是网络 IO，什么时候回来全看运气。上线第一周没事，用户网络一差就炸。

修复方法不是把 0 改成 100（那是赌得更大），而是用 Promise 把依赖关系显式写出来：fetchData().then(openDialog)。从那以后我立了个规矩：代码里出现魔法数字延时，一律当 bug 处理。

1.3 作用域与闭包：var 的原罪

for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100);
}
// 输出：3 3 3

因为 var 没有块级作用域，循环结束后 i 只有一个，三个回调共享同一个 i。改成 let 就好了，因为 let 每次迭代都创建一个新的绑定。

for (let i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100);
}
// 输出：0 1 2

闭包就是「函数 + 它出生时看到的词法环境」。下面这个计数器是闭包的标准用法：

function createCounter() {
  let count = 0;          // 外部拿不到，只能通过返回的函数碰它
  return {
    inc() { return ++count; },
    get() { return count; },
  };
}

const counter = createCounter();
counter.inc();
counter.inc();
console.log(counter.get()); // 2

思考：新人常把闭包当面试八股，其实它是 JavaScript 最重要的封装手段。ES Module 普及之前，整个前端世界的模块化都建立在闭包之上（IIFE）。理解了闭包，你就理解了「私有状态」这件事在没有 class 的时代是怎么做到的。

1.4 this：JavaScript 最大的心理阴影

this 的判定规则其实只有一句话：看它怎么被调用，而不是在哪里定义。

flowchart TD
    A["函数被调用时 this 是什么？"] --> B{"new 调用？"}
    B -->|是| C["新创建的对象"]
    B -->|否| D{"call / apply / bind？"}
    D -->|是| E["显式传入的对象"]
    D -->|否| F{"作为对象方法调用 obj.fn()？"}
    F -->|是| G["点号前面的 obj"]
    F -->|否| H["undefined（严格模式）<br/>或 window（非严格）"]
    I["箭头函数：没有自己的 this<br/>永远用定义处的 this"] -.-> A

踩坑故事 2：回调里的 this 丢了

团队新人写过这样的代码：
class UserService {
  constructor() { this.name = '方糖猫'; }
  greet() { console.log(`你好，${this.name}`); }
}
const svc = new UserService();
document.querySelector('#btn').addEventListener('click', svc.greet);
// 点击后输出：你好，undefined
svc.greet 被取出来当回调传递时，调用者变成了 DOM 元素，this 就丢了。排查时新人百思不得其解：「我明明在 class 里定义的！」——这正是 1.4 开头那句话的意思。修法两个：addEventListener('click', () => svc.greet())，或者构造器里 this.greet = this.greet.bind(this)。

这件事对后面学 Vue 很重要：Vue 的 setup 和 Composition API 大量使用普通函数和箭头函数，从根上绕开了 this 的坑，这是它相对 Options API 被推崇的深层原因之一。

1.5 异步进化史：从回调地狱到 async/await

flowchart LR
    A["回调函数<br/>callback"] -->|"嵌套过深<br/>回调地狱"| B["Promise<br/>链式调用"]
    B -->|"then 链仍啰嗦"| C["async / await<br/>同步写法"]
    C -.->|"语法糖"| B

Promise 三种状态的流转是面试和实战的双重重点：

stateDiagram-v2
    [*] --> Pending: new Promise(executor)
    Pending --> Fulfilled: resolve(value)
    Pending --> Rejected: reject(reason) 或抛异常
    Fulfilled --> [*]: .then(onFulfilled)
    Rejected --> [*]: .catch(onRejected)
    note right of Pending
        状态只能流转一次
        且不可逆
    end note

同一个逻辑，三种写法对比：

// 回调时代
getUser(id, function (err, user) {
  if (err) return handle(err);
  getOrders(user.id, function (err, orders) {
    if (err) return handle(err);
    render(orders);
  });
});

// Promise 时代
getUser(id)
  .then(user => getOrders(user.id))
  .then(orders => render(orders))
  .catch(handle);

// async/await 时代
async function showOrders(id) {
  try {
    const user = await getUser(id);
    const orders = await getOrders(user.id);
    render(orders);
  } catch (err) {
    handle(err);
  }
}

踩坑故事 3：await 放进 forEach 里「不生效」
const ids = [1, 2, 3];
ids.forEach(async id => {
  await saveRecord(id);
});
console.log('全部保存完成'); // 这行会先执行！
forEach 不会等回调里的 Promise，它只是把三个 async 函数同时踢出去就完事了。需要串行用 for...of，需要并行用 await Promise.all(ids.map(saveRecord))。这个坑我在 Code Review 里至少见过五次，堪称 async 时代第一坑。

1.6 引用类型与拷贝：看不见的共享

const a = { name: '猫', tags: ['前端'] };
const b = a;            // 不是拷贝，是同一个对象的另一张门牌
b.name = '狗';
console.log(a.name);    // '狗' —— a 也变了

浅拷贝（Object.assign、{...obj}）：只拷第一层，嵌套对象还是共享。
深拷贝：现代浏览器直接用 structuredClone(obj)，别再手写递归了。

踩坑故事 4：改了这个表单，那个弹窗也跟着变

一个配置页有两处编辑入口，打开弹窗时 this.form = rowData。用户在弹窗里改着改着，背后的表格行数据实时跟着变——因为两个变量指向同一个对象。测试没测出来（他们只点了保存），用户取消编辑时发现数据「没保存也生效了」，提了 P1 故障。修法一行：this.form = structuredClone(rowData)。

感悟：JavaScript 里 90% 的「数据莫名变化」，最后都能追到共享引用上。这也是后来 Vue 3 的响应式、Pinia 的 state 管理反复强调「数据流向要清晰」的原因——可变的共享状态是万恶之源。

1.7 Demo：手写防抖与节流

这两个函数是真实项目里用得最多的工具函数，也是检验你闭包和 this 是否真懂了的试金石：

// 防抖：停止触发 n 毫秒后才执行（搜索框联想）
function debounce(fn, delay = 300) {
  let timer = null;
  return function (...args) {
    clearTimeout(timer);              // 闭包记住了上一次的 timer
    timer = setTimeout(() => fn.apply(this, args), delay);
  };
}

// 节流：n 毫秒内最多执行一次（滚动监听）
function throttle(fn, interval = 200) {
  let last = 0;
  return function (...args) {
    const now = Date.now();
    if (now - last >= interval) {
      last = now;
      fn.apply(this, args);
    }
  };
}

// 用法
document.querySelector('#search')
  .addEventListener('input', debounce(e => searchApi(e.target.value), 300));
window.addEventListener('scroll', throttle(onScroll, 200));

记忆法：防抖像电梯门——有人进就重新计时；节流像技能 CD——冷却时间内按了也白按。

1.8 阶段小结

JavaScript 学到什么程度算「入门通关」？我的标准：

能徒手画出事件循环图，并解释任意一段代码的输出顺序。
能写对一个不借助库的 debounce，并且说得清为什么 this 要透传。
知道 let/const 与 var 的全部区别，代码里不再出现 var。
看到共享引用引起的 bug，能在一分钟内定位到「是同一个对象」。

第二篇 TypeScript：给代码买一份编译期保险

2.1 为什么需要 TypeScript

先看一段纯 JavaScript 的日常事故：

function formatPrice(price) {
  return '¥' + price.toFixed(2);
}

formatPrice('19.9');  // 运行时才炸：price.toFixed is not a function

这个错误要到用户点了那个按钮才暴露。TypeScript 做的事，就是把这类错误从「运行时炸给用户看」提前到「写代码时编辑器就红线警告」：

flowchart LR
    A["你写的 TS 代码"] -->|"tsc 编译<br/>类型检查"| B{"有类型错误？"}
    B -->|"是：当场拦住"| C["编辑器红线<br/>CI 直接失败"]
    B -->|"否"| D["擦掉类型<br/>生成纯 JS"]
    D --> E["浏览器运行"]

感悟：很多人对 TS 的第一印象是「麻烦」——要写类型、要应付编译器报错。但我的体会是：TS 不是让你多写代码，而是让你把脑子里本来就该想清楚的东西写下来。一个函数的参数到底是什么形状，本来就该想明白；TS 只是逼你别含糊。项目越大、接手的人越多，这份「写下来」的回报越惊人。

2.2 核心类型速览

// 基础类型
let count: number = 0;
let title: string = '前端之路';
let done: boolean = false;

// 数组与元组
let tags: string[] = ['vue', 'ts'];
let pair: [string, number] = ['vue', 3];

// 联合类型：要么是这个，要么是那个
type Status = 'pending' | 'success' | 'failed';

// interface：描述对象的形状
interface User {
  id: number;
  name: string;
  email?: string;        // 可选
  readonly createdAt: Date;  // 只读
}

// type：更灵活，可以做联合、交叉、映射
type Admin = User & { permissions: string[] };

interface 和 type 的区别不用背，记一句经验法则：描述对象结构优先 interface（可被继承扩展、报错信息更友好），需要联合/交叉/工具类型时用 type。

2.3 泛型：类型的「函数参数」

不写泛型时，你只能二选一：要么 any 放弃检查，要么为每种类型复制一份代码。泛型让你把「类型」当参数传：

// 一个通用的 API 响应包装
interface ApiResponse<T> {
  code: number;
  message: string;
  data: T;
}

interface User {
  id: number;
  name: string;
}

async function fetchUser(id: number): Promise<ApiResponse<User>> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}

// 使用时，data 自动推断为 User，点 name 有提示，点 naem 会报错
const resp = await fetchUser(1);
console.log(resp.data.name);

2.4 类型守卫：收窄的艺术

function handle(value: string | number) {
  if (typeof value === 'string') {
    value.toUpperCase();  // 这里 TS 知道 value 是 string
  } else {
    value.toFixed(2);     // 这里 TS 知道 value 是 number
  }
}

自定义守卫在解析后端数据时特别有用：

function isUser(data: unknown): data is User {
  return typeof data === 'object'
    && data !== null
    && 'id' in data
    && typeof (data as User).id === 'number';
}

const raw: unknown = await (await fetch('/api/user/1')).json();
if (isUser(raw)) {
  console.log(raw.name); // 安全
}

2.5 踩坑故事：那些年我们踩过的 TS 坑

踩坑故事 5：any 是会传染的

接手过一个项目，前人为了赶进度，在一个核心工具函数上写了 (data: any)。这个函数的返回值被到处使用，于是 any 像病毒一样扩散——凡是碰过它的变量全部失去类型检查。半年后统计，全项目 40% 的「类型报错被绕过」都能追到这一个 any。最后的修复花了两个人周，从它开始一层层把类型补回来。

教训：any 不是「暂时不管」，是「把错误埋给未来」。实在搞不定第三方数据的类型，用 unknown——它强迫你使用前先做守卫，安全得多。

踩坑故事 6：as 断言骗过了编译器，没骗过运行时
const user = JSON.parse(localStorage.getItem('user')!) as User;
user.name.toUpperCase(); // 某天 localStorage 里是旧版数据，没有 name 字段，线上白屏
as 的意思是「我比编译器更懂」，运行时零校验。localStorage、接口返回、URL 参数——凡是程序边界进来的数据，都不能信。该写守卫写守卫，别偷懒。

2.6 阶段小结

TS 入门标准：

项目里 any 的出现次数趋近于 0，且每次出现都能说出理由。
能给项目的所有 API 请求和响应写出 interface。
会写 Partial<T>、Pick<T, K>、Record<K, V> 这三个最常用的工具类型。
看到 unknown 不慌，知道用守卫收窄。

第三篇 Vue 3：响应式与组件化的艺术

3.1 Vue 3 解决了什么问题

框架存在的意义，一句话：让视图自动跟随数据变化，你只管改数据。

flowchart LR
    A["你修改数据<br/>state.count++"] --> B["Vue 响应式系统<br/>Proxy 拦截到变化"]
    B --> C["找到依赖该数据的<br/>组件渲染函数"]
    C --> D["重新渲染<br/>虚拟 DOM diff"]
    D --> E["最小化更新真实 DOM"]

没有框架时你要写 document.querySelector('#count').textContent = count；有了 Vue，你写 count++，剩下的它管。心智负担从「操作 DOM」变成「操作数据」，这是前端开发史上最重要的一次抽象升级。

3.2 响应式原理：Proxy 魔法

Vue 2 用 Object.defineProperty，Vue 3 换成了 Proxy。这个改变解决了 Vue 2 的两个著名痛点：

flowchart TB
    subgraph Vue2 的痛点
        A1["新增属性不响应<br/>要 this.$set"]
        A2["数组下标修改不响应<br/>要 splice"]
    end
    subgraph Vue3 Proxy
        B1["拦截整个对象<br/>新增属性也能捕获"]
        B2["数组天然支持"]
    end
    Vue2 的痛点 -->|"升级"| Vue3

简化版原理，三十行代码让你理解响应式：

// 极简响应式：不是生产实现，只为理解原理
let activeEffect = null;

function reactive(obj) {
  return new Proxy(obj, {
    get(target, key) {
      track(target, key);        // 收集依赖：谁在用我
      return Reflect.get(target, key);
    },
    set(target, key, value) {
      const result = Reflect.set(target, key, value);
      trigger(target, key);      // 派发更新：通知用我的人
      return result;
    },
  });
}

const state = reactive({ count: 0 });
effect(() => console.log(state.count)); // 建立依赖
state.count++;                           // 自动打印新值

理解了「get 时收集依赖、set 时派发更新」，Vue 3 的响应式在你眼里就没有魔法了。

3.3 第一个 Vue 3 应用：环境搭建

Vue 3 时代的标配工具链是 Vite（冷启动毫秒级，谁用谁知道）：

npm create vite@latest my-app -- --template vue-ts
cd my-app
npm install
npm run dev

项目结构速览：

flowchart TB
    A["src/"] --> B["main.ts<br/>应用入口"]
    A --> C["App.vue<br/>根组件"]
    A --> D["components/<br/>业务组件"]
    A --> E["stores/<br/>Pinia 状态"]
    A --> F["router/<br/>路由"]
    B -->|"createApp(App)<br/>.use(router)<br/>.use(pinia)<br/>.mount('#app')"| C

3.4 Composition API：setup 语法糖

这是 Vue 3 写法的核心。一个计数器组件：

<script setup lang="ts">
import { ref, computed } from 'vue';

const count = ref(0);

// computed：依赖 count，自动缓存，自动更新
const double = computed(() => count.value * 2);

function increment() {
  count.value++;  // 注意：script 里要 .value，template 里不用
}
</script>

<template>
  <p>当前：{{ count }}，翻倍：{{ double }}</p>
  <button @click="increment">+1</button>
</template>

ref vs reactive，新人必问的问题，我的答案：

统一用 ref，除非你明确知道自己在做什么。
ref 包基本类型和对象都行，行为一致；reactive 只能包对象，且解构会失去响应式（见下面的坑）。

3.5 踩坑故事：Vue 3 的那些坑

踩坑故事 7：解构 reactive，响应式当场消失
<script setup lang="ts">
import { reactive } from 'vue';

const state = reactive({ count: 0, name: '猫' });
const { count } = state;  // 完蛋：count 只是个普通数字了

setTimeout(() => { state.count = 99; }, 1000);
// 模板里的 {{ count }} 永远停在 0
</script>
解法：要么不解构（state.count），要么用 toRefs(state)。这个坑的原理很直白：解构出来的是那一刻的值，跟 Proxy 再没有关系了。想通这一点，你对响应式的理解就及格了。

踩坑故事 8：watch 监听对象，怎么不触发？
const user = ref({ name: '猫', age: 3 });

watch(user, (val) => console.log('变了'));  // user.value.age = 4 时不触发！
watch 默认只盯引用的变化（整个对象被替换），user.value.age = 4 改的是内部属性，引用没变。要么 watch(user, cb, { deep: true })，要么更推荐——监听 getter，精确指定你关心什么：
watch(() => user.value.age, (val) => console.log('年龄变了', val));
deep: true 会递归遍历整个对象，大对象上性能开销不小。我见过一个列表页卡成 PPT，就是有人给万行数据加了 deep watch。

踩坑故事 9：v-for 用 index 当 key，列表一排序就乱
<li v-for="(item, index) in list" :key="index">{{ item.name }}</li>
用 index 当 key，列表中间插入或删除一项时，Vue 的 diff 会复用错误的 DOM 和组件状态。真实的症状是：删除第二行，结果第三行的勾选状态「跑」到了第二行上。key 必须用数据里唯一且稳定的标识，通常是 item.id。没有 id？那就造一个，别用 index。

3.6 组件通信：一张图说清所有方式

flowchart TB
    P["父组件"] -->|"props 单向传下去"| C["子组件"]
    C -->|"emit 事件冒上去"| P
    S["兄弟组件 A"] -->|"共享状态"| Store["Pinia Store"]
    Store --> S2["兄弟组件 B"]
    G["祖组件"] -->|"provide"| GG["隔代孙组件"]

铁律只有一条：props 是单向的，子组件不许直接改。

<!-- 子组件：定义 props 和 emits -->
<script setup lang="ts">
const props = defineProps<{ title: string; count: number }>();
const emit = defineEmits<{ (e: 'update', value: number): void }>();

function onClick() {
  // props.count++;  // 错误！单向数据流被破坏
  emit('update', props.count + 1);  // 正确：通知父组件去改
}
</script>

踩坑故事 10：子组件直接改 props，两个人的状态打架

一个弹窗子组件收到父组件传来的 visible，关闭按钮直接写 props.visible = false。表面上能用（基本类型甚至会报错，对象类型能偷偷改成功），但父组件的状态没跟着变，于是出现「弹窗关了，父组件还以为它开着，下次点不开」的灵异 bug。

Vue 官方把这叫做单向数据流，我更愿意叫它「状态的唯一权威来源」：每个状态只能有一个主人，其他人想要变化，只能向主人申请。这条原则在 Pinia、React、Redux 里是通用的，值得刻进肌肉记忆。

3.7 生命周期：什么时候干什么事

flowchart LR
    A["setup()<br/>最早的时机"] --> B["onBeforeMount"]
    B --> C["onMounted<br/>DOM 已就绪<br/>发请求 操作 DOM"]
    C --> D["onBeforeUpdate"]
    D --> E["onUpdated"]
    E -.->|"数据再变"| D
    C --> F["onBeforeUnmount"]
    F --> G["onUnmounted<br/>清定时器 解绑事件"]

最常见的需求对应关系：

发接口请求：onMounted（或 setup 里直接发，视 SSR 需求而定）。
注册定时器/事件监听：onMounted 里注册，onUnmounted 里必须清理，否则组件反复挂载会内存泄漏。

<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue';

let timer: number;

onMounted(() => {
  timer = window.setInterval(fetchData, 5000);
});

onUnmounted(() => {
  clearInterval(timer);  // 不清这个，路由来回切几次就有 N 个定时器在跑
});
</script>

3.8 Demo：一个完整的 TodoList

把上面的知识全部串起来，这是一个可以直接跑的真实组件：

<script setup lang="ts">
import { ref, computed } from 'vue';

interface Todo {
  id: number;
  text: string;
  done: boolean;
}

const todos = ref<Todo[]>([]);
const newText = ref('');
let nextId = 1;

const remaining = computed(() => todos.value.filter(t => !t.done).length);

function addTodo() {
  const text = newText.value.trim();
  if (!text) return;
  todos.value.push({ id: nextId++, text, done: false });
  newText.value = '';
}

function removeTodo(id: number) {
  todos.value = todos.value.filter(t => t.id !== id);
}
</script>

<template>
  <div class="todo">
    <h2>待办（还剩 {{ remaining }} 件）</h2>
    <input
      v-model="newText"
      placeholder="回车添加"
      @keyup.enter="addTodo"
    />
    <ul>
      <!-- 注意：key 用 item.id，不是 index -->
      <li v-for="item in todos" :key="item.id">
        <label :class="{ done: item.done }">
          <input type="checkbox" v-model="item.done" />
          {{ item.text }}
        </label>
        <button @click="removeTodo(item.id)">删除</button>
      </li>
    </ul>
  </div>
</template>

<style scoped>
.done { text-decoration: line-through; color: #999; }
</style>

这个不到 50 行的组件里，藏着这些考点：ref + 泛型、计算属性、v-model 双向绑定、事件修饰符（@keyup.enter）、列表渲染的 key、scoped 样式。面试时让你手写一个，能 10 分钟写出来且 key 用对，Vue 基础就算过关。

3.9 Pinia：跨组件状态的正确姿势

组件多了以后，「A 改了状态 B 也要知道」的需求越来越多，props 一层层传会疯掉。Pinia 是 Vue 3 官方推荐的状态管理：

// stores/user.ts
import { defineStore } from 'pinia';

interface UserState {
  name: string;
  token: string | null;
}

export const useUserStore = defineStore('user', {
  state: (): UserState => ({
    name: '',
    token: null,
  }),
  getters: {
    isLoggedIn: (state) => state.token !== null,
  },
  actions: {
    async login(name: string, password: string) {
      const res = await loginApi(name, password);
      this.name = res.name;
      this.token = res.token;
    },
    logout() {
      this.name = '';
      this.token = null;
    },
  },
});

组件里使用：

<script setup lang="ts">
import { useUserStore } from '@/stores/user';
import { storeToRefs } from 'pinia';

const userStore = useUserStore();
const { name, isLoggedIn } = storeToRefs(userStore); // 保持响应式
// const { name } = userStore;  // 又踩坑 7：解构丢响应式！
</script>

注意 storeToRefs——它和 toRefs 解决的是同一个问题，所以我说坑 7 是 Vue 3 第一大坑，它会换着花样反复出现。

3.10 Vue Router：单页应用的路由

// router/index.ts
import { createRouter, createWebHistory } from 'vue-router';

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', component: () => import('@/views/Home.vue') },
    { path: '/user/:id', component: () => import('@/views/User.vue') },
    { path: '/admin', component: () => import('@/views/Admin.vue'),
      meta: { requiresAuth: true } },
  ],
});

// 路由守卫：登录校验的标准位置
router.beforeEach((to) => {
  const userStore = useUserStore();
  if (to.meta.requiresAuth && !userStore.isLoggedIn) {
    return { path: '/login', query: { redirect: to.fullPath } };
  }
});

export default router;

注意路由组件用 () => import(...) 的懒加载写法——首屏只加载首页代码，其余按需加载，这是性能优化的免费午餐。

第四篇工程化与心智成长

4.1 一个项目从代码到上线的完整链路

flowchart LR
    A["本地开发<br/>vite dev 热更新"] --> B["提交代码<br/>ESLint + 类型检查"]
    B --> C["构建<br/>vite build<br/>压缩 分包 指纹"]
    C --> D["部署<br/>静态资源上 CDN / Nginx"]
    D --> E["线上监控<br/>错误上报 性能指标"]
    E -.->|"发现 bug"| A

4.2 从入门到精通的真实分水岭

我带过不少新人，观察下来，「入门」到「精通」之间隔着的从来不是更多 API，而是这几件事：

能从现象推回原理。弹窗数据不同步，能想到共享引用；列表状态错乱，能想到 key；数据改了视图没变，能想到响应式丢失。原理是那把万能钥匙。
对异步有敬畏心。接口时序、竞态、取消请求，这些才是真实项目里最贵的 bug 来源。
状态有主人。任何一份数据，都能一句话说清「谁拥有它、谁能改它」。
敢看源码。从 structuredClone 到 Vue 的 track/trigger，你会发现那些「魔法」拆开看都朴素得很。

4.3 一些真心话

关于学习顺序：直接学 Vue 能不能干活？能。但你会在第一次遇到 this 丢失、响应式消失、异步时序问题时卡住，因为你缺的是底下的地基。JavaScript → TypeScript → Vue 3 这条路看着绕，其实是最短的。

关于框架之争：React、Vue、Angular 吵了很多年，但响应式、组件化、单向数据流这些核心思想是相通的。把一门学透，换另一门是周级别的事；门门都浅尝，换哪门都是从头开始。

关于 AI 时代：现在让 AI 写一个 TodoList 只要十秒钟。但上面那些坑——共享引用、解构丢响应式、await forEach——AI 生成的代码照样会犯，而能看出来它错了的人，才能驾驭它。越是工具强大，基本功越不是可有可无，而是你最硬的议价能力。

结语

这条路线走下来，你收获的不仅是「会写 Vue」，而是一套完整的思维方式：用 JavaScript 理解运行，用 TypeScript 管理复杂度，用 Vue 组织界面，用工程化把这一切交付给真实用户。

入门的标志是你能写出功能；精通的标志，是你能在深夜的故障群里，三分钟说出一句：「我知道问题出在哪。」

祝你也早日成为那样的人。

前端 on 方糖猫Blog

微信小程序开发从入门到精通：环境搭建、WXML/WXSS、组件库、架构、平台能力与发布全指南

微信小程序开发从入门到精通：环境搭建、WXML/WXSS、组件库、架构、平台能力与发布全指南

第一篇 环境搭建：比 Android 友好，但坑藏在「账号」里

1.1 你需要准备的三样东西

1.2 踩坑故事一：类目选错，审核排队两周白排

1.3 踩坑故事二：「不校验合法域名」的虚假安全感

第二篇 语法基础：四个文件就是一个页面

2.1 一个页面 = 四个文件

2.2 setData：小程序开发的第一性原理

2.3 十分钟速览：和 Vue 的核心差异

2.4 rpx：一个单位解决屏幕适配

2.5 踩坑故事四：回调里的 this 指向丢了

第三篇 UI 组件库：别从零画按钮

3.1 主流组件库怎么选

3.2 踩坑故事五：npm 装了，组件死活找不到

3.3 Demo：一个五脏俱全的登录页

3.4 原生还是跨端框架？一个绕不开的决策

第四篇 架构与生命周期：从「写页面」到「写应用」

4.1 生命周期：App、Page、Component 三层

4.2 页面栈：小程序导航的「宪法」

4.3 组件化与通信：从页面到 Component

4.4 全局状态：mobx-miniprogram 就够了

第五篇 网络与存储：数据从哪来，存到哪去

5.1 wx.request：先把回调包成 Promise

5.2 本地存储：wx.setStorage 的分寸

5.3 云开发：没有后端时的另一条路

第六篇 平台能力：登录、订阅消息、分享、支付与分包

6.1 登录：code 换 openid 的三段握手

6.2 订阅消息：推送的正确打开方式

6.3 分享与裂变：小程序的增长引擎

6.4 支付：五步流程，前后端各管一半

6.5 分包加载：2MB 限制的解法

第七篇 质量与发布：从「能跑」到「敢上线」

7.1 性能三板斧：setData、分包、图片

7.2 调试三板斧：vConsole、真机调试与体验版

7.3 审核与发布：小程序独有的最后一关

第八篇 AI 时代：怎么少写一半代码把小程序做出来

8.1 AI 在小程序开发各环节的胜任度

8.2 实战工作流：需求 → 小程序的 AI 协作五步法

8.3 一个真实对比：Demo 小程序的工时变化

8.4 思考：AI 是放大器，不是替代品

结语：学习路线收个尾

React 从入门到精通：环境搭建、核心语法、组件库选型与 AI 时代的开发方式

React 从入门到精通

一、学习路线图

二、开发环境搭建（2022 年的正确姿势）

2.1 装 Node：用 nvm，不要官网下载安装包

2.2 创建项目：用 Vite，不要 create-react-app

2.3 编辑器与插件

三、核心语法：记住一个公式就够了

3.1 心智模型：UI = f(state)

3.2 组件与 JSX

3.3 state 与事件：让界面动起来

3.4 列表渲染与 key

3.5 useEffect：处理副作用

四、踩坑故事：六个我真实掉进去过的坑

坑 1：setState 是「异步」的，连续 +1 只加了一次

坑 2：useEffect 里 setState，死循环刷爆页面

坑 3：列表 key 用 index，勾选状态全乱了

坑 4：直接改 state 对象，界面死活不更新

坑 5：定时器里的 stale closure（闭包旧值）

坑 6：在组件里定义组件，输入框每敲一个字就失焦

五、底层原理：为什么 React 是这样设计的

5.1 虚拟 DOM 与 Diff 算法：用 JS 对象换性能

5.2 Fiber 架构：把渲染拆成可中断的小任务

5.3 渲染两阶段：render 可中断，commit 不可中断

5.4 Hooks 的实现：一条链表 + 调用顺序

5.5 批量更新：多次 setState 合并成一次渲染

5.6 一张图总结：从 setState 到屏幕更新

六、主流 UI 组件库：选型对比

七、完整 Demo：一个 Todo App

八、AI 时代：怎么少写代码完成 APP 开发

九、延伸话题：为什么国内流行 Vue，海外是 React 统治

十、思考与感悟

十一、学习路线建议

前端 UI 开发从入门到精通（Vue 技术栈）：HTTP、CSS 与主流组件库实战

前端 UI 开发从入门到精通（Vue 技术栈）：HTTP、CSS 与主流组件库实战

第一篇 HTTP：数据是怎么到页面上的

1.1 一次请求的完整旅程

第一篇环境搭建：比 Android 友好，但坑藏在「账号」里

第二篇语法基础：四个文件就是一个页面

第四篇架构与生命周期：从「写页面」到「写应用」

第五篇网络与存储：数据从哪来，存到哪去

第六篇平台能力：登录、订阅消息、分享、支付与分包

第七篇质量与发布：从「能跑」到「敢上线」

第三篇主流 UI 组件库：选型、驾驭与避坑

第四篇从「会用」到「精通」：我的几点感悟

第四篇工程化与心智成长