移动开发 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 和折叠屏上都一样流畅。

Android 开发从入门到精通：环境搭建、Kotlin、Compose、架构、系统能力与发布全指南

Thu, 10 Aug 2023 09:10:00 +0800

Android 开发从入门到精通：环境搭建、Kotlin、Compose、架构、系统能力与发布全指南

目标读者：想进入 Android 开发的新人，或者写过一阵 Java/旧版 XML 布局、想切换到现代技术栈（Kotlin + Compose）的同学。
知识骨架参考《Android 编程权威指南》（Big Nerd Ranch Guide），结合 2026 年的技术现状做了取舍，按「由浅入深」重新编排。
姊妹篇：《前端 UI 开发从入门到精通（Vue 技术栈）》——写 UI 的心法，两端是相通的。

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

flowchart LR
    A["一 环境搭建<br/>能跑起 Hello World"] --> B["二 Kotlin 基础<br/>语法 + 协程"]
    B --> C["三 Compose 界面<br/>写出第一个页面"]
    C --> D["四 架构与生命周期<br/>从写页面到写应用"]
    D --> E["五 网络与存储<br/>数据从哪来 存到哪去"]
    E --> F["六 系统能力<br/>定位 通知 唤醒 适配"]
    F --> G["七 质量与发布<br/>测试 调试 签名上线"]
    G --> H["八 AI 时代<br/>让 AI 写 80% 的代码"]
    style H fill:#e8f4e8

为什么是这个顺序？前三篇解决「能不能写出来」；第四篇解决「代码多了以后会不会散架」；第五、六篇解决「能不能和服务器、和操作系统打交道」；第七篇解决「敢不敢发给真实用户」；第八篇解决「如何持续快下去」。

第一篇环境搭建：90% 的新人倒在这一关

先泼一盆冷水再给你信心：Android 开发的门槛不在写代码，而在环境。新人放弃 Android 的第一大原因不是学不会语法，而是装了三天 Android Studio 跑不起来一个 Hello World。所以环境放在最前面，并且写得足够细。

1.1 你需要安装的三样东西

flowchart TD
    A["JDK 17+<br/>编译 Kotlin/Java 的底座"] --> D["Android Studio"]
    B["Android SDK<br/>系统 API + 平台工具 adb"] --> D
    C["Android Emulator<br/>或一台真机"] --> D
    D --> E["能跑起 Hello World<br/>= 入门完成一半"]

好消息是 2026 年的 Android Studio 已经是「全家桶」安装：下载安装包一路 Next，JDK（内嵌 JBR）、SDK、模拟器全都有了。真正需要你动手的只有三件事：

下载地址认准官方：developer.android.google.cn（国内可直连）。别去下载站，装到捆绑了全家桶的旧版本是新人常见悲剧。
第一次启动时让它下载 SDK，默认勾选 Android SDK Platform、SDK Build-Tools、Android Emulator 即可。
配环境变量（命令行构建和 AI 工具都会用到）：

# Windows: 系统环境变量里添加
ANDROID_HOME=C:\Users\你的用户名\AppData\Local\Android\Sdk
# Path 里追加
%ANDROID_HOME%\platform-tools   # adb 在这里
%ANDROID_HOME%\cmdline-tools\latest\bin

验证：新开一个终端跑 adb version，有输出即成功。

1.2 第一个项目：别折腾，用模板

New Project → Empty Activity（注意选 Empty Activity，这是 Compose 模板；不要选带 “Views” 后缀的，那是旧 XML 布局）。点 Run，等模拟器起来，看到 “Hello Android” 就算通关。

1.3 踩坑故事一：Gradle 同步转了一小时的圈

现象：新建项目后底部状态栏 “Gradle Sync” 转圈一小时不动，或者报 Could not resolve com.android.tools.build:gradle:x.x.x。

原因：Gradle 要从国外 Maven 仓库下载几百 MB 的构建工具和依赖，国内直连极慢。这是国内 Android 新人的「成人礼」。

解法：给项目根目录的 settings.gradle.kts 换上国内镜像（阿里源）：

// settings.gradle.kts
pluginManagement {
    repositories {
        maven("https://maven.aliyun.com/repository/gradle-plugin")
        maven("https://maven.aliyun.com/repository/google")
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {
    repositories {
        maven("https://maven.aliyun.com/repository/google")
        maven("https://maven.aliyun.com/repository/central")
        google()
        mavenCentral()
    }
}

教训：镜像要放在 google() 前面，Gradle 按顺序找，先命中镜像就不用走官方源了。同样的思路适用于一切包管理器（npm、pip、Maven）——「换源」是国内开发者的通用生存技能。

1.4 踩坑故事二：AGP、Gradle、JDK 的三角恋情

现象：拉下同事的项目，构建报错 Unsupported class file major version 65 或 Minimum supported Gradle version is x.x。

原因：Android 开发有三个版本必须互相匹配，这是新人最懵的地方：

flowchart TD
    A["Android Gradle Plugin (AGP)<br/>项目级 build.gradle 里声明"] -->|"要求"| B["Gradle 版本<br/>gradle-wrapper.properties"]
    A -->|"要求"| C["JDK 版本<br/>Android Studio 内嵌或系统"]
    B -.->|"版本对照表<br/>查官方文档"| C
    style A fill:#fff3cd

AGP 8.x 要求 Gradle 8.x + JDK 17。
报错时不要瞎改，打开 Google 官方的「Android Gradle 插件版本说明」对照表，三者对齐。

教训：项目里 gradle-wrapper.properties 锁定了 Gradle 版本是有深意的——它保证任何同事、任何 CI 机器拉下代码构建结果一致。新人最容易犯的错就是全局升级 Gradle 然后所有老项目全炸。

第二篇 Kotlin 基础：写给会别的语言的人

环境通了，接下来是语言。如果你会 Java 或 JavaScript，这一篇很快；如果是零基础，建议搭配《Kotlin 核心编程》或官方教程把例子都敲一遍。

2.1 十分钟速览：和 Java/JS 的核心差异

// 1. val / var：不可变优先
val name = "方糖猫"        // 不可变，类似 const
var age = 3               // 可变
// age = "三"             // ❌ 类型推导为 Int，改 String 编译报错

// 2. 空安全：类型系统层面消灭 NPE
var nickname: String? = null
// nickname.length        // ❌ 编译不过，必须处理 null
val len = nickname?.length ?: 0   // ?. 安全调用 + ?: 默认值

// 3. when 表达式：加强版 switch
val desc = when (age) {
    in 0..2 -> "幼猫"
    3 -> "壮年"
    else -> "老猫"
}

// 4. data class：一行顶 Java 五十行
data class User(val id: Long, val name: String, val email: String = "")
// 自动生成 equals/hashCode/toString/copy

// 5. 函数式：lambda 和集合操作
val names = users.filter { it.name.isNotBlank() }
                 .map { it.name }

// 6. 扩展函数：给别人的类加方法
fun String.isEmail(): Boolean = this.contains("@")
"ftmao@example.com".isEmail()   // true

空安全是 Kotlin 最值得吹的设计。Java 程序员的一生之敌 NullPointerException，在 Kotlin 里被类型系统提前拦下——String? 和 String 是两个不同的类型，编译器强迫你处理 null。

2.2 协程：异步代码同步写

App 开发的核心动作是「发起网络请求 → 更新界面」，而且网络请求绝不能跑在主线程（否则界面卡死，系统直接弹 ANR 杀掉你的 App）。协程让这件事写得像同步代码：

// viewModelScope 是 ViewModel 自带的协程作用域，页面销毁自动取消
fun loadUsers() {
    viewModelScope.launch {
        _uiState.value = UiState.Loading
        try {
            // withContext(Dispatchers.IO) 切到 IO 线程执行耗时操作
            val users = withContext(Dispatchers.IO) {
                api.getUsers()        // 挂起函数：等结果，但不阻塞线程
            }
            _uiState.value = UiState.Success(users)   // 回到主线程更新 UI
        } catch (e: Exception) {
            _uiState.value = UiState.Error(e.message ?: "未知错误")
        }
    }
}

sequenceDiagram
    participant UI as 主线程(UI)
    participant CO as 协程
    participant IO as IO 线程池
    UI->>CO: viewModelScope.launch
    CO->>IO: withContext(IO) 发起网络请求
    Note over UI: 主线程不阻塞<br/>界面照常响应触摸
    IO-->>CO: 请求返回
    CO-->>UI: 切回主线程更新状态
    UI->>UI: Compose 自动重组界面

思考：协程最难的不是语法，是「作用域」的概念——协程挂在谁的 scope 上，决定了它什么时候被取消。用 viewModelScope 而不是裸 GlobalScope.launch，你的协程就会随页面销毁自动取消，不会内存泄漏。这是面试高频题，更是线上事故高频源。现在只需要记住结论，第四篇讲完生命周期后你会真正理解为什么。

第三篇用 Compose 写出第一个界面

语言有了，马上写界面——学习正反馈来得越早越好。

3.1 从 XML 到 Compose：一次范式革命

旧时代的 Android UI 是「XML 写布局 + Java/Kotlin 找控件 + 手动 setText」，命令式的，状态和视图靠人肉同步。Compose 是声明式的：UI 是状态的函数。

flowchart LR
    subgraph old["旧时代：命令式"]
        A1["XML 布局"] --> B1["findViewById"] --> C1["手动 setText/setVisibility"]
        C1 --> D1["状态变了？<br/>记得手动再 set 一遍<br/>(漏了就出 bug)"]
    end
    subgraph new["Compose：声明式"]
        A2["状态 State"] -->|"状态变化自动触发重组"| B2["@Composable 函数<br/>UI = f(state)"]
    end
    style new fill:#e8f4e8

写过 Vue/React 的人会秒懂——这和前端框架的响应式是同一种思想，只是语法换成了 Kotlin。

3.2 主流 UI 组件「库」：答案比前端简单

前端有 Element Plus / Ant Design / Naive UI 群雄割据，Android 的答案简单得多：

flowchart TD
    Q{"做什么样的 App？"}
    Q -->|"绝大多数情况"| A["Material 3 (material3)<br/>官方出品 随 SDK 维护"]
    Q -->|"要高度自定义设计"| B["Compose Foundation 无样式组件<br/>+ 自建 Design System"]
    Q -->|"跨端 iOS + Android"| C["Compose Multiplatform<br/>或 Flutter(另一条技术栈)"]

Material 3（androidx.compose.material3）：官方组件库，Button、Card、TextField、Dialog、Scaffold、NavigationBar 一应俱全，且深度适配系统特性（深色主题、动态取色）。先用它，用到不够用再谈别的。这和前端「别和组件库对着干」是同一个道理——对抗官方设计体系的自定义，维护成本极高。
accompanist 已成历史：早年 Compose 功能不全，靠 accompanist 库补（下拉刷新、权限等），2026 年这些能力已全部并入官方库，新项目不要再引入。
第三方生态里值得一提的：Coil（图片加载，事实标准）、Compose Destinations（类型安全导航）。

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

把 Kotlin、协程、Compose、Material 3 串起来——这是每个 App 都有的页面：

@Composable
fun LoginScreen(viewModel: LoginViewModel = viewModel()) {
    val state by viewModel.uiState.collectAsState()

    Scaffold { padding ->
        Column(
            modifier = Modifier
                .padding(padding)
                .fillMaxSize()
                .padding(24.dp),
            verticalArrangement = Arrangement.Center,
        ) {
            OutlinedTextField(
                value = state.email,
                onValueChange = viewModel::onEmailChange,
                label = { Text("邮箱") },
                isError = state.emailError != null,
                supportingText = { state.emailError?.let { Text(it) } },
                modifier = Modifier.fillMaxWidth(),
            )
            Spacer(Modifier.height(16.dp))
            OutlinedTextField(
                value = state.password,
                onValueChange = viewModel::onPasswordChange,
                label = { Text("密码") },
                visualTransformation = PasswordVisualTransformation(),
                modifier = Modifier.fillMaxWidth(),
            )
            Spacer(Modifier.height(24.dp))
            Button(
                onClick = viewModel::login,
                enabled = !state.loading,
                modifier = Modifier.fillMaxWidth(),
            ) {
                if (state.loading) {
                    CircularProgressIndicator(Modifier.size(20.dp))
                } else {
                    Text("登录")
                }
            }
        }
    }
}

对应的 ViewModel，注意状态管理的写法：

data class LoginUiState(
    val email: String = "",
    val password: String = "",
    val emailError: String? = null,
    val loading: Boolean = false,
)

class LoginViewModel : ViewModel() {
    private val _uiState = MutableStateFlow(LoginUiState())
    val uiState: StateFlow<LoginUiState> = _uiState.asStateFlow()

    fun onEmailChange(v: String) {
        _uiState.update { it.copy(email = v, emailError = null) }
    }

    fun login() {
        val s = _uiState.value
        if (!s.email.contains("@")) {
            _uiState.update { it.copy(emailError = "邮箱格式不对") }
            return
        }
        viewModelScope.launch {
            _uiState.update { it.copy(loading = true) }
            try {
                delay(1500)  // 假装发请求
                // api.login(s.email, s.password)
                _uiState.update { it.copy(loading = false) }
            } catch (e: Exception) {
                _uiState.update { it.copy(loading = false) }
            }
        }
    }
}

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

单一数据源：整个页面的所有状态装进一个 UiState data class，UI 只读它。改状态用 update { it.copy(...) } 不可变更新，和前端 Redux/Pinia 一个思想。
UI 状态的状态机：登录按钮有「正常 / 加载中 / 禁用」形态，错误有「无错 / 有错」形态——「UI 本质是状态机」，在任何平台都成立。

3.4 踩坑故事三：列表滑动卡成 PPT

现象：LazyColumn 展示 500 条消息，滑动掉帧明显。

排查与解法，按出现频率排序：

flowchart TD
    A["LazyColumn 卡顿"] --> B{"Composable 里<br/>有耗时计算吗？"}
    B -->|"有，最常见"| C["用 remember 缓存计算结果<br/>remember(list) { expensive(list) }"]
    B -->|"没有"| D{"item 有稳定的 key 吗？"}
    D -->|"没写 key"| E["items(list, key = { it.id })<br/>没 key 时位置变动全量重组"]
    D -->|"写了"| F{"在 Debug 包测的？"}
    F -->|"是，冤枉了"| G["换 Release 包测！<br/>Debug 包 Compose 性能差数倍"]
    style G fill:#ffe4e1

教训：第三条最坑——Compose 的 Debug 包性能不代表线上。无数新人在 Debug 包测出「卡顿」，花两天优化，打完 Release 包发现根本不卡。性能问题永远以 Release 包为准。

3.5 踩坑故事四：旋转屏幕，数据全没了

现象：页面填了一半表单，用户一转屏幕，输入全没了。

原因：旋转屏幕默认会销毁并重建 Activity。存在 Composable 局部变量里的状态随重建灰飞烟灭。

解法分三层，按持久程度选：

// 1. remember：只管重组不丢，不管重建 —— 最弱
var text by remember { mutableStateOf("") }

// 2. rememberSaveable：重建也能恢复（进 Bundle，有大小限制）
var text by rememberSaveable { mutableStateOf("") }

// 3. ViewModel + StateFlow：配置变更（旋转、深浅色切换）都不丢 —— 正道
//    状态放 ViewModel 里，Activity 重建 ViewModel 不重建

感悟：Android 的「生命周期地狱」本质上是系统在告诉你：UI 是廉价的，随时会被销毁；状态是珍贵的，要放在比 UI 活得久的地方。这个坑也是下一篇的入口——旋转只是「销毁」的一种，更狠的还在后面。

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

前三篇你能写出一个页面了。但真实 App 是几十个页面、在几亿台不可控的设备上被随意切换、随时被杀。这一篇建立组织代码的地基——《Android 编程权威指南》全书真正想教的就是这一篇的东西。

4.1 Activity 生命周期：不是八股，是保命符

生命周期回调几乎每个教程都有，但多数人只背了图没理解「什么时候会走哪条边」：

stateDiagram-v2
    [*] --> onCreate: 启动
    onCreate --> onStart
    onStart --> onResume: 获得焦点，可交互
    onResume --> onPause: 被半透明遮挡(弹窗)
    onPause --> onResume: 回到前台
    onPause --> onStop: 完全不可见(跳别的页面/按Home)
    onStop --> onRestart: 从后台回来
    onRestart --> onStart
    onStop --> onDestroy: 用户退出或系统回收
    onDestroy --> [*]

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

可见性配对：onStart/onStop 管「看不看得见」（注册/注销广播监听放这里），onResume/onPause 管「能不能交互」（相机、传感器这类独占资源放这里）。放错层级是资源泄漏的常见来源。
onDestroy 不保证被调用：进程被系统直接杀死时，什么回调都不会来。重要数据不能指望「退出时再保存」。

踩坑故事五：切后台半小时，回来从头再来

现象：用户在表单页填到一半，切出去回了个微信，半小时后切回来，App 重新从启动页加载，填的内容全没了。

原因：这不是 3.5 节旋转屏幕那种配置变更，而是进程死亡（Process Death）——App 在后台久了，系统内存不足时直接杀掉整个进程。ViewModel 也跟着进程一起死了，3.5 节的三层方案全部失效。

解法：ViewModel 里的关键状态用 SavedStateHandle，它会把数据写入进程死亡也能存活的 Bundle：

class FormViewModel(private val state: SavedStateHandle) : ViewModel() {
    // 进程被杀再恢复，draft 还在
    var draft: String
        get() = state["draft"] ?: ""
        set(value) { state["draft"] = value }
}

怎么测试：开发者选项里打开「不保留活动（Don’t keep activities）」，或者在 App 切后台后执行 adb shell am kill <包名> 模拟进程死亡。不测这一关，你永远不知道自己的状态恢复写对了没有——这是权威指南反复强调而多数教程略过的点。

4.2 四大组件与 Intent：Android 的「宪法」

flowchart TD
    A["Activity<br/>一页界面"] --- E["Intent 把它们串起来"]
    B["Service<br/>无界面的后台工作<br/>(今天多由 WorkManager/前台服务承担)"] --- E
    C["BroadcastReceiver<br/>监听系统/应用事件<br/>开机完成 网络变化"] --- E
    D["ContentProvider<br/>跨进程共享结构化数据<br/>联系人 媒体库"] --- E

应知应会的点不在概念，而在分寸：

Intent 分显式/隐式：显式指定类名跳自己 App 的页面；隐式声明「我想看一张图片 / 打开一个网页」，系统找能干的 App 来接。隐式 Intent 配合 intent-filter，就是 Android 应用间协作的全部基础——第六篇的 App 唤醒全靠它。
Task 与返回栈：启动的 Activity 层层叠在一个任务栈里，返回键出栈。第六篇的 launchMode 就是在控制这个栈的行为。
今天的比重：新项目里 Service 大多被 WorkManager 和协程替代，BroadcastReceiver 的系统广播被限制得越来越严，ContentProvider 多数时候你只是「使用者」（读联系人、读相册）。概念要懂，但别再像十年前的教程那样上来先写三个 Service。

4.3 Fragment：Compose 时代怎么看它

权威指南的老版本用了大量篇幅讲 Fragment——它是 View 时代组织页面的核心。2026 年的答案：

新项目：单 Activity + Compose + Navigation 库，页面就是 Composable，不需要 Fragment。
绕不开的场景：维护老项目、集成只有 View 版本的第三方 SDK（某些地图、支付 SDK），以及系统级 UI（如 PreferenceFragmentCompat）。

所以对待 Fragment 的正确姿势是：看懂生命周期比 Activity 多一层（view 的生命周期和 Fragment 本身分离），够用即可，不必深入。把省下的时间投给 Compose。

4.4 架构：MVVM + Repository + 单向数据流

权威指南从 MVC 讲到 MVVM 的演进，核心思想收敛成今天 Google 官方推荐的这张图：

flowchart TD
    subgraph UI层
        A["Composable<br/>只负责渲染和上报事件"]
    end
    subgraph 状态层
        B["ViewModel<br/>持有 UiState(StateFlow)<br/>暴露事件处理函数"]
    end
    subgraph 数据层
        C["Repository<br/>数据的唯一入口<br/>决定走网络还是缓存"]
        D["Retrofit<br/>远程数据"]
        E["Room / DataStore<br/>本地数据"]
    end
    A -->|"用户事件"| B
    B -->|"StateFlow 数据流"| A
    B --> C
    C --> D
    C --> E

三条铁律，比记住「MVVM」三个字母重要得多：

UI 不直接碰网络和数据库——Composable 里出现 Retrofit 调用，就是架构腐烂的开始。
数据向下流，事件向上流（UDF）：UI 只读状态、只发事件，ViewModel 改状态。3.3 节的登录 Demo 就是这个模式。
Repository 是数据的唯一入口：ViewModel 不关心数据来自网络还是 Room 缓存，这让「离线优先」的 App 成为可能——先展示 Room 里的旧数据，网络回来再刷新。

注意这张图里数据层的两个角色——Retrofit 和 Room。它们就是下一篇的主角。

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

架构定了，现在填数据层的肉。这一篇学完，你就能写出「联网 CRUD + 离线缓存」的完整 App 了。

5.1 联网的第一步：权限与明文拦截

踩坑故事六：请求发出去了，App 里却报 CLEARTEXT 错误

现象：Retrofit 请求发出去了，模拟器浏览器也能打开接口地址，App 里却报 CLEARTEXT communication not permitted。

原因，两个新手必踩的组合拳：

AndroidManifest.xml 忘了声明网络权限（Android 不像前端，联网要申请）：

<manifest ...>
    <uses-permission android:name="android.permission.INTERNET" />
</manifest>

Android 9+ 默认禁止 HTTP 明文请求，测试环境是 http:// 就会撞上。开发期放行：

<application
    android:usesCleartextTraffic="true"   <!-- 仅限 debug 包这么干 -->
    ...>

教训：上线前把明文流量关掉，让后端上 HTTPS。安全这类事情，「先放行以后再收」基本等于永远不收。

5.2 Retrofit：网络层的事实标准

移动端网络层的标准组合：Retrofit（定义接口）+ OkHttp（发请求）+ 协程（写异步）。

// 1. 接口定义：挂起函数 + 注解，Kotlin 协程原生支持
interface ApiService {
    @GET("users")
    suspend fun getUsers(@Query("page") page: Int): ApiResponse<List<User>>

    @POST("login")
    suspend fun login(@Body body: LoginRequest): ApiResponse<LoginData>
}

// 2. OkHttp：拦截器统一带 token、打日志、配超时
val okHttp = OkHttpClient.Builder()
    .connectTimeout(10, TimeUnit.SECONDS)
    .readTimeout(15, TimeUnit.SECONDS)
    .addInterceptor { chain ->
        val req = chain.request().newBuilder()
            .addHeader("Authorization", "Bearer ${TokenHolder.token}")
            .build()
        chain.proceed(req)
    }
    .addInterceptor(HttpLoggingInterceptor().setLevel(HttpLoggingInterceptor.Level.BODY))
    .build()

// 3. Retrofit 组装
val api = Retrofit.Builder()
    .baseUrl("https://api.example.com/")   // ⚠️ 必须以 / 结尾，见踩坑故事七
    .client(okHttp)
    .addConverterFactory(GsonConverterFactory.create())
    .build()
    .create(ApiService::class.java)

踩坑故事七：baseUrl 结尾少了一个斜杠

现象：Retrofit 初始化直接 crash：IllegalArgumentException: baseUrl must end in /。

教训：几乎每个 Android 开发者都撞过一次。顺手记住另一个相关坑：@GET 里的相对路径如果以 / 开头，会丢弃 baseUrl 的路径段——baseUrl("https://x.com/api/") 配 @GET("/users") 实际请求的是 https://x.com/users，/api 没了。

踩坑故事八：拦截器里打印了 body，业务层就拿不到数据了

现象：在自定义拦截器里写了 response.body()!!.string() 打日志，结果业务层解析永远失败。

原因：OkHttp 的响应体是流，只能消费一次。

解法：打日志用官方 HttpLoggingInterceptor（上面 Demo 里已带）；自定义拦截器里要读内容，用 peekBody：

val bodyText = response.peekBody(1024 * 1024).string()  // ✅ 复制一份读，不影响原流

移动端特有的提醒：手机用户会进电梯、进地铁、切 Wi-Fi 和流量，弱网和断线是常态而不是异常。超时必须配、失败要给重试入口、一次抖动失败别急着弹「网络异常」的全屏错误——静默重试一次，体验天差地别。

5.3 本地存储：四个层级，各管各的

「存东西」在 Android 里不是一件事，先想清楚存什么：

flowchart TD
    Q{"要存什么？"}
    Q -->|"键值对<br/>设置项 / token"| A["DataStore<br/>(SharedPreferences 的接班人)"]
    Q -->|"结构化数据<br/>离线缓存 / 消息列表"| B["Room 数据库<br/>(下一节详解)"]
    Q -->|"图片 / 日志 / 大文件"| C["App 私有目录<br/>context.filesDir"]
    Q -->|"要存进相册 / 共享给用户"| D["MediaStore API<br/>(不要直接写 /sdcard)"]

键值存储的 Demo，协程化的 DataStore 用法：

val Context.dataStore by preferencesDataStore(name = "settings")
val KEY_TOKEN = stringPreferencesKey("token")

suspend fun saveToken(context: Context, token: String) {
    context.dataStore.edit { it[KEY_TOKEN] = token }
}

// 读取是 Flow，可以在 ViewModel 里直接 collect
val tokenFlow: Flow<String?> = context.dataStore.data.map { it[KEY_TOKEN] }

踩坑故事九：SharedPreferences 引发的 ANR

现象：老项目用户反馈「切换页面偶尔卡死」，ANR 日志里堆栈停在 QueuedWork.waitToFinish()。

原因：SharedPreferences.apply() 号称异步，但系统会在 Activity 停顿时把磁盘写入队列 flush 完才放行——数据多了，主线程就在这等着。另外首次 getSharedPreferences() 的读盘也发生在主线程。

解法：新项目一律 DataStore（协程挂起，天然不阻塞主线程）；老项目遇到这类 ANR，迁移 DataStore 是治本方案。

踩坑故事十：targetSdk 升到 30，读不到文件了

现象：原来「把文件存到 /sdcard/Download」的代码，升级 targetSdk 后全部失败。

原因：Android 10 引入分区存储（Scoped Storage），App 再也不能随意读写公共目录了。

解法分级：

App 自己的文件 → 用 context.filesDir / cacheDir，不需要任何权限，卸载自动清理。
图片视频要进相册 → 走 MediaStore API。
让用户选文档 → 走 SAF（系统文件选择器）。
想申请 MANAGE_EXTERNAL_STORAGE 一把梭？Google Play 会拒审，除非你是文件管理器类 App。

感悟：分区存储当年被骂得很惨，但回头看是对的——它终结了「每个 App 都在 SD 卡根目录拉一坨文件夹」的蛮荒时代。适配它的正确姿势不是对抗（到处找绕过方案），而是按数据的归属选 API：属于自己的放私有目录，属于用户的走 MediaStore。

5.4 Room：编译期检查 SQL 的数据库

结构化数据（消息列表、账单、离线缓存）的答案。完整三件套 Demo：

// 1. Entity：一张表
@Entity(tableName = "expenses")
data class Expense(
    @PrimaryKey(autoGenerate = true) val id: Long = 0,
    val title: String,
    val amount: Double,
    val createdAt: Long,
)

// 2. DAO：操作表的方法，SQL 在编译期校验
@Dao
interface ExpenseDao {
    @Query("SELECT * FROM expenses ORDER BY createdAt DESC")
    fun observeAll(): Flow<List<Expense>>   // 返回 Flow：数据变了 UI 自动更新

    @Insert
    suspend fun insert(expense: Expense)

    @Delete
    suspend fun delete(expense: Expense)
}

// 3. Database：单例持有
@Database(entities = [Expense::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun expenseDao(): ExpenseDao
}

val db = Room.databaseBuilder(context, AppDatabase::class.java, "app.db").build()

@Query 返回 Flow 是 Room 最优雅的用法——数据库一变，Flow 发射新值，Compose 自动重组，「增删改 → 界面刷新」这条链路不用写一行通知代码。

踩坑故事十一：加了个字段，老用户升级就闪退

现象：新版给 Expense 加了一个 category 字段，自己测没问题，上线后老用户打开就崩：IllegalStateException: A migration from 1 to 2 was required。

原因：Room 用 version 管理表结构。老用户手机里的库还是 version 1 的结构，新代码按 version 2 读，Room 要求你提供 Migration（怎么从 1 迁移到 2），你没有提供。

解法：

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE expenses ADD COLUMN category TEXT NOT NULL DEFAULT ''")
    }
}
Room.databaseBuilder(...)
    .addMigrations(MIGRATION_1_2)
    // 开发期偷懒可以用 .fallbackToDestructiveMigration()（清库重建）
    // 上线前必须删掉 —— 那是拿用户数据开玩笑
    .build()

教训：数据库字段变更和接口变更一样，是对存量用户的承诺。每次改 Entity，先想「老用户的库里有什么」。

第六篇系统能力：定位、通知、唤醒与平台适配

到这里，你的 App 已经「自成一体」了。这一篇让它和操作系统、和其他 App、和真实世界的几亿台设备打交道。系统能力的坑有一个共同特征：Demo 里都好好的，一到用户手机上就出事。

6.1 定位：别再用 LocationManager 了

官方推荐的是 Google Play 服务里的 FusedLocationProviderClient——它自动在 GPS、基站、Wi-Fi 之间选最优来源，比你手写 LocationManager 监听省心得多。

权限申请的关键流程（Android 12 之后有变化）：

flowchart TD
    A["请求定位权限<br/>ACCESS_FINE + ACCESS_COARSE"] --> B{"用户怎么选的？"}
    B -->|"精确授权"| C["高精度定位<br/>米级"]
    B -->|"Android 12+ 只给『大致位置』"| D["只有约 3km 精度<br/>⚠️ 代码必须兼容这种情况"]
    B -->|"拒绝"| E["优雅降级<br/>引导手动选择城市"]
    B -->|"需要后台定位"| F["必须再单独申请<br/>ACCESS_BACKGROUND_LOCATION<br/>且只能跳设置页让用户手动开"]

获取定位的 Demo（配合 kotlinx-coroutines-play-services 的 await()）：

val fused = LocationServices.getFusedLocationProviderClient(context)

suspend fun getCurrentLocation(): Location? {
    return try {
        fused.getCurrentLocation(
            Priority.PRIORITY_HIGH_ACCURACY,
            CancellationTokenSource().token,
        ).await()
    } catch (e: SecurityException) {
        null   // 权限被收回
    }
}

踩坑故事十二：定位永远是 null，或者位置是三天前的

现象：getLastLocation() 一会儿返回 null，一会儿返回几个小时前的旧坐标。

原因：这个方法只是读系统缓存——最近有别的 App 定位过才有值，它自己不会发起定位。

解法：像上面 Demo 那样用 getCurrentLocation() 主动请求一次新定位。需要持续追踪（跑步轨迹这类）再用 requestLocationUpdates()。

踩坑故事十三：坐标偏了五百米，人都站到河里了

现象：GPS 拿到的经纬度画到高德地图上，位置偏移了几百米，用户「站在」马路对面的河里。

原因：国内坐标系的经典天坑——世界上同时存在三种坐标：

flowchart LR
    A["GPS 芯片原始坐标<br/>WGS-84"] -->|"国测局加密算法"| B["GCJ-02 火星坐标<br/>高德/腾讯/Google 国内用"]
    B -->|"百度再加密一次"| C["BD-09<br/>百度地图专用"]
    A -.->|"直接画到高德地图<br/>❌ 偏移 300-600 米"| D["线上事故"]
    style D fill:#ffe4e1

教训：用什么地图 SDK 就转成什么坐标。FusedLocationProviderClient 返回的是 WGS-84，上高德地图前先用高德 SDK 的 CoordinateConverter 转 GCJ-02；接百度地图就转 BD-09。永远不要自己写转换算法，加密参数不公开，网上的「破解版公式」精度堪忧。

6.2 消息通知：两段历史决定了今天的写法

通知 API 看着简单，但它是 Android 版本行为变更的重灾区。先记住这两个分水岭：

flowchart LR
    A["Android 8 (API 26)<br/>通知必须归属<br/>NotificationChannel"] --> B["Android 13 (API 33)<br/>通知变成运行时权限<br/>POST_NOTIFICATIONS"]
    B --> C["今天的完整姿势<br/>建渠道 + 申请权限<br/>缺一不可"]

完整 Demo：

// 第 1 步：建渠道（App 启动时建，重复调用无副作用）
val channel = NotificationChannel(
    "order",                          // 渠道 id
    "订单消息",                        // 用户在系统设置里看到的名字
    NotificationManager.IMPORTANCE_HIGH,
)
context.getSystemService(NotificationManager::class.java)
    .createNotificationChannel(channel)

// 第 2 步：Android 13+ 运行时申请权限
val launcher = rememberLauncherForActivityResult(
    ActivityResultContracts.RequestPermission()
) { granted -> /* 记录用户选择，别循环弹 */ }
launcher.launch(Manifest.permission.POST_NOTIFICATIONS)

// 第 3 步：发通知
val notification = NotificationCompat.Builder(context, "order")
    .setSmallIcon(R.drawable.ic_notification)   // 必须，否则直接抛异常
    .setContentTitle("订单已发货")
    .setContentText("您的包裹正在派送")
    .setAutoCancel(true)                        // 点击后自动消失
    .build()
NotificationManagerCompat.from(context).notify(1, notification)

踩坑故事十四：通知死活不显示

按出现概率排查：

flowchart TD
    A["通知不显示"] --> B{"建 Channel 了吗？"}
    B -->|"没建（Android 8+ 直接静默丢弃）"| C["补上 createNotificationChannel"]
    B -->|"建了"| D{"Channel 的 importance<br/>是不是 LOW/MIN？"}
    D -->|"是"| E["⚠️ 渠道等级一旦创建<br/>代码里改不了！<br/>只能换渠道 id 或引导用户去设置"]
    D -->|"否"| F{"Android 13+ 申请<br/>POST_NOTIFICATIONS 了吗？"}
    F -->|"没申请"| G["补运行时权限申请"]
    style E fill:#ffe4e1

第二个分支最阴：渠道等级创建后被系统记住，你在代码里把 IMPORTANCE_LOW 改成 IMPORTANCE_HIGH 毫无作用，要么换一个新的渠道 id，要么引导用户去系统设置里改。

关于推送（Push）多说两句：本地通知只是通知的一半，另一半是服务器推消息下来。这里国内生态是割裂的：

FCM（Google 推送）在国内不可用。
国内正道是厂商通道：华为、小米、OPPO、vivo、荣耀各自的推送 SDK。它们是系统级通道，App 被杀也能收到。
第三方聚合（个推、极光）可以一套代码接多家厂商通道，小团队首选。
只靠自己的长连接保活推消息？国产 ROM 杀后台从不手软，重要消息（订单、支付）务必走厂商通道。

6.3 App 唤醒：Deep Link、拉起与被拉起

4.2 节讲了隐式 Intent 和 intent-filter 的原理，这一节把它用起来。「唤醒」分两个方向：别人拉起你，你拉起别人。

flowchart TD
    Q{"从哪拉起你的 App？"}
    Q -->|"网页/短信里的 https 链接"| A["App Links<br/>需域名资产验证 体验最好"]
    Q -->|"其他 App / 二维码"| B["自定义 Scheme<br/>myapp://detail/123<br/>简单但可被抢注"]
    Q -->|"通知点击"| C["PendingIntent<br/>配 FLAG_IMMUTABLE"]

Manifest 里声明可唤起入口（Android 12+ 必须显式 android:exported）：

<activity
    android:name=".DetailActivity"
    android:exported="true"
    android:launchMode="singleTask">   <!-- ⚠️ 见踩坑故事十五 -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="https"
            android:host="ftmao.com"
            android:pathPrefix="/app" />
    </intent-filter>
</activity>

踩坑故事十五：从链接唤起后，页面参数是旧的，或者叠了三四层

现象：App 已在后台时点击链接，打开的还是上次的旧内容；多点几次链接，返回键要按四下才退出去。

原因：默认 launchMode="standard" 每次唤醒都新建一个 Activity 实例，叠在任务栈顶（4.2 节的返回栈）；而且热启动时新参数走 onNewIntent() 回调，不走 onCreate()——只在 onCreate 里读 intent 的代码自然漏掉。

解法：singleTask + 两个入口都处理：

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    handleDeepLink(intent)
}

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    handleDeepLink(intent)   // 热启动的参数在这里
}

private fun handleDeepLink(intent: Intent?) {
    val id = intent?.data?.lastPathSegment ?: return
    // 跳详情页
}

反方向（你拉起别的 App）的版本坑：Android 11 引入包可见性限制，packageManager.getPackageInfo("com.tencent.mm") 会抛 NameNotFoundException——不是你代码错了，是系统假装微信不存在。需要在 Manifest 里声明 <queries>：

<queries>
    <package android:name="com.tencent.mm" />
</queries>

6.4 平台适配 tips：碎片化才是 Android 的本体

前端适配的是几个浏览器，Android 适配的是「几十种 ROM × 十几个活跃系统版本 × 无数种屏幕」。以下是我项目里反复用到的适配清单：

屏幕与手势

尺寸单位永远 dp/sp，别碰 px；字号用 sp 才能跟随用户的系统字体设置。
Android 15 起强制 edge-to-edge：内容会画到状态栏和手势导航条下面。用 Compose 的 Scaffold + Modifier.padding(paddingValues) 或 WindowInsets 处理，别自己猜状态栏高度。
折叠屏和平板：用 WindowSizeClass 判断屏幕档位切换单栏/双栏布局，别写死「宽度大于 600dp 就是平板」。

深色模式

颜色全部走 MaterialTheme.colorScheme，一个 Color.White 都不要写死。写死颜色的页面在深色模式下就是一块刺眼白斑，而且这种 bug 只在用户半夜打开 App 时才暴露。

版本策略

flowchart LR
    A["minSdk 26<br/>覆盖 95%+ 活跃设备"] --> B["targetSdk 跟着<br/>Google Play 年度要求走"]
    B --> C["行为变更按版本处理<br/>Build.VERSION.SDK_INT 分支"]
    C --> D["能力检测优于版本判断<br/>能查权限就查权限"]

踩坑故事十六：小米上好好的，华为上定时任务就是不执行

现象：提醒功能在小米、Pixel 上正常，部分华为、OPPO 用户反馈「到点不提醒」。

原因：国产 ROM 的后台管控比原生 Android 激进得多——自启动权限、电池优化白名单、后台弹出界面权限，每家厂商的名称、入口、默认策略都不一样。原生 API 层的 AlarmManager、前台服务，到了这些 ROM 上随时可能被「省电策略」干掉。

解法：

周期性、可延迟的任务用 WorkManager——它是 Google 专门为解决各厂商后台差异做的兼容层，会根据系统能力自动选底层实现。
必须精确到点的（闹钟类），检测并引导用户跳转对应设置页（Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS 等），文案讲清楚「不开会怎样」。
重要消息走 6.2 节说的厂商推送通道，别指望自己保活。

感悟：适配的终极心法只有一句——不要假设环境，永远做能力检测。if (Build.VERSION.SDK_INT >= 33)、if (checkSelfPermission(...) == GRANTED)、if (packageManager.resolveActivity(intent) != null) 这些防御性代码写多了，你就从「在我手机上能跑」毕业到「在所有人手机上能跑」。这也是 Android 开发和前端开发气质上最大的不同：前端的环境是相对可控的浏览器，Android 的环境是几亿台你从没见过的手机。

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

功能做完只是上半场。这一篇是把 App 交给真实用户之前的最后一道关。

7.1 测试：少但要有

测试金字塔在移动端同样成立，按性价比排：

flowchart LR
    A["单元测试 多写<br/>ViewModel / 工具函数<br/>毫秒级 不依赖设备"] --> B["Compose UI 测试 精选<br/>核心页面渲染与交互"]
    B --> C["端到端 极少<br/>发版前跑主流程"]

单元测试 Demo（ViewModel + 协程，kotlinx-coroutines-test）：

class LoginViewModelTest {
    @Test
    fun `邮箱格式错误时不发起登录`() = runTest {
        val vm = LoginViewModel()
        vm.onEmailChange("not-an-email")
        vm.login()
        assertEquals("邮箱格式不对", vm.uiState.value.emailError)
        assertFalse(vm.uiState.value.loading)
    }
}

Compose UI 测试 Demo：

class LoginScreenTest {
    @get:Rule
    val rule = createComposeRule()

    @Test
    fun 点击登录按钮触发校验提示() {
        rule.setContent { LoginScreen() }
        rule.onNodeWithText("登录").performClick()
        rule.onNodeWithText("邮箱格式不对").assertIsDisplayed()
    }
}

务实建议：别追求覆盖率数字。给「钱相关的计算、状态机的转移、数据解析」这三类写单元测试，给「登录、主列表、下单」这三条主链路写 UI 测试，投入产出比最高。

7.2 调试三板斧：Logcat、adb 与 Layout Inspector

遇到问题时的三板斧，按使用频率排：

Logcat：分级日志 Log.d/e/w，配上明确的 TAG。经验：TAG 用类名，日志里带上关键 id（订单号、用户 id），半年后排查线上问题你会感谢自己。
adb 命令行，高频就这几条：

adb devices                          # 设备列表
adb install app-debug.apk            # 安装
adb shell am start -n 包名/.MainActivity   # 拉起页面
adb shell am kill 包名                # 模拟进程死亡（4.1 节测试用）
adb logcat -s 你的TAG                 # 只看自己的日志

Layout Inspector：Compose 时代的「布局透视镜」，实时看每个 Composable 的重组次数——重组次数异常飙升，就是 3.4 节性能问题的第一现场。

7.3 国际化与无障碍：专业完成度的分水岭

这两件事区分了「能用的 App」和「专业的 App」：

国际化（i18n）

所有文案进 res/values/strings.xml，代码里用 stringResource(R.string.xxx)，一个中文字符串都不要硬编码——今天不国际化，明天产品说「做个英文版」你就要全文搜索替换。
复数用 <plurals>（英文的 1 item / 2 items 规则不同），别用字符串拼接数字。

无障碍（a11y）

图片和图标按钮加 contentDescription（视障用户的屏幕阅读器 TalkBack 靠它朗读）：

IconButton(onClick = onBack) {
    Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "返回")
}

可点击区域不小于 48dp——Material 组件默认满足，自定义 Canvas 绘制按钮时最容易违规。
最后打开 TalkBack 把自己的 App 主流程走一遍，十分钟，胜过读十篇规范。

7.4 发布：签名、混淆与 AAB

1. 签名（Keystore）：Android 用签名识别「同一开发者」。生成 release keystore 后立刻备份到至少两个安全的地方——丢了它，你的 App 永远无法更新，只能换包名重新上架，用户和评分清零。这不是理论风险，是每个公司都流传过的真实事故。

2. 混淆（R8）：Release 包默认开启，压缩、优化、混淆代码。

踩坑故事十七：Debug 包好好的，Release 包登录一直失败

现象：Debug 一切正常，打完 Release 包，接口返回的 JSON 解析出来所有字段都是 null。

原因：R8 把 data class 的字段名混淆成了 a、b、c，而 Gson 默认靠字段名反射匹配 JSON 的 key——名字没了，匹配全落空。

解法，二选一：

// 方案 A：给序列化模型加 keep 规则（proguard-rules.pro）
-keep class com.example.app.data.model.** { *; }

// 方案 B：换 Moshi/kotlinx-serialization，编译期生成适配器，不靠反射

教训：所有验证都必须用 Release 包做最后一遍。Debug 和 Release 的差异（混淆、压缩、日志）大到足以让「我测过了」变成一句空话——3.4 节的性能测量如此，7.4 节的功能验证同样如此。

3. 打包 AAB：Google Play 要求上传 Android App Bundle（.aab）而非 APK，由 Play 按用户设备分发精简后的安装包。versionCode 单调递增（系统靠它判断更新），versionName 给人看。

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

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

8.1 AI 在 Android 开发各环节的胜任度

flowchart LR
    subgraph good["AI 做得极好 放心交出去"]
        A1["样板代码<br/>ViewModel / data class / Repository"]
        A2["单页面 UI<br/>给我画一个设置页"]
        A3["单元测试"]
        A4["解释报错信息"]
    end
    subgraph mid["AI 能做 但你要盯着"]
        B1["跨页面架构改造"]
        B2["性能优化"]
        B3["依赖升级适配"]
    end
    subgraph bad["AI 做不好 还得靠人"]
        C1["环境/构建问题<br/>(它看不到你的机器)"]
        C2["真机/特定 ROM 才出现的 bug"]
        C3["产品取舍<br/>这个交互要不要做"]
    end

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

这是我自己做一个新 App 时的真实流程：

第一步：先写「项目宪法」，再让 AI 写代码。 在项目里放一个 AGENTS.md / .cursorrules，写明技术栈和约定：

# 项目约定
- Kotlin + Jetpack Compose + Material 3，不用 XML 布局
- 架构：MVVM + Repository，单向数据流，状态全部走 ViewModel + StateFlow + UiState
- 网络：Retrofit + OkHttp + 协程，挂起函数返回 ApiResponse<T>
- 本地：Room 存结构化数据，DataStore 存键值，定时/后台任务用 WorkManager
- 图片加载用 Coil，导航用 Navigation Compose
- 禁止 GlobalScope；禁止硬编码颜色和文案，一律走 MaterialTheme 和 strings.xml
- Room 改 Entity 必须同步提供 Migration 并升 version

没有这份文件，AI 每次生成代码的风格都随机漂移；有了它，AI 的输出稳定得像团队里最守规矩的那个工程师。注意这份清单里的每一条，都对应着前面某一篇的某个坑——项目宪法本质上是踩坑笔记的浓缩。

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

第三步：让它先写数据层和状态，再写 UI。 先生成 Entity/DAO/Repository + UiState + ViewModel，review 通过后再让它写 Composable——这正是第四、五篇的架构顺序。状态设计错了，UI 写得再漂亮也是白写。

第四步：编译错误直接喂回去。 Android Studio 现在集成了 Gemini，编译报错选中 → 问 AI → 应用修复，循环两三次大部分构建问题都能解决。但 1.3、1.4 那种环境级问题 AI 帮不了你——它看不到你本地的 SDK 装在哪个盘；6.4 那种「只在华为手机上复现」的问题它更帮不了——它没有真机。这就是为什么 AI 篇必须排在最后：它是放大器，放大的是你前七篇的水平。

第五步：人工 review 的四个必查点。 AI 生成的 Android 代码，我每次都只细查四处：① 协程作用域是否用了 viewModelScope（内存泄漏重灾区）；② 状态是否放进了 ViewModel 而不是 remember 在深层 Composable 里（旋转和进程死亡丢数据）；③ 网络/IO 是否切了 Dispatchers.IO（ANR 来源）；④ 权限和版本分支有没有做能力检测（AI 爱写「假设权限已授予」的代码）。其他代码粗看即可——review 的精力要花在 AI 的已知短板上。

8.3 一个真实对比：Demo App 的工时变化

3.3 节那个登录页 + 一个用户列表页的小 Demo，三年前我要写一整天（查 API、调布局、处理状态）。2026 年用 AI 的实际耗时：

pie title 一个双页面 Demo 的 2 小时去哪了
    "写 AGENTS.md 和提示词" : 20
    "AI 生成 + 我 review 修改" : 60
    "环境构建问题排查(AI帮不上)" : 25
    "真机测试与细节打磨" : 15

注意那张饼图里最大的启示：省下来的时间没有消失，它转移到了「描述需求」和「审查代码」上。AI 时代的核心能力从「打字速度」变成了两样：

把模糊需求拆成精确技术任务的能力——你对第四篇架构的理解越深，给 AI 的指令就越准。
快速判断代码对错的能力——这恰恰要求你懂前七篇讲的所有基本功。看不懂协程作用域的人，review 不了 AI 写的 Android 代码。

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

每次技术圈出现「AI 能不能取代程序员」的争论，我都想起一个类比：计算器没有取代会计，它淘汰了「只会打算盘的会计」，成就了「用计算器做财务分析的会计」。AI 对 Android 开发者的影响一样：

它消灭了记忆型知识的价值（某个 API 的参数顺序，查得再快也不如 AI 直接生成）。
它放大了判断型知识的价值（这个状态该放 ViewModel 还是 Composable？这个版本冲突该升 AGP 还是降 Gradle？这个定时任务该用 WorkManager 还是 AlarmManager？这次 Room 改表要不要写 Migration？）。

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

结语：学习路线收个尾

flowchart LR
    A["第 1 周<br/>环境搭建 + 跑通模板<br/>+ Kotlin 语法"] --> B["第 2-4 周<br/>Compose 基础<br/>写 5 个静态页面"]
    B --> C["第 2-3 个月<br/>架构 + 网络 + Room<br/>写一个完整的<br/>联网 CRUD App"]
    C --> D["第 3-6 个月<br/>定位/通知/唤醒/适配<br/>测试 签名 发布上架"]
    D --> E["持续<br/>把 AI 变成<br/>你的初级工程师"]

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

第一周死磕环境不丢人。每个 Android 老兵都经历过 Gradle 转圈的下午，这不是你笨，是这个生态的真实成本。
用真机开发，而且要用不止一台。模拟器掩盖了低端机的性能问题，单品牌真机掩盖了 ROM 碎片化问题——你的用户分布在十几种厂商的手机上。
让 AI 写代码，让自己写笔记。每踩一个坑记下「现象、根因、下次怎么一眼认出」，这些笔记是 AI 时代你不可被替代的资产——因为 AI 知道所有答案，但它不知道你的项目昨天为什么炸。

祝你的 Gradle 永远秒同步，keystore 永远有备份，App 在华为和小米上都一样坚挺。

iOS 开发从入门到精通：环境搭建、Swift 语法、系统特性与 AI 时代的高效开发

Wed, 02 Aug 2023 08:30:00 +0800

iOS 开发从入门到精通：环境搭建、Swift 语法、系统特性与 AI 时代的高效开发

目标读者：会一门编程语言（前端、后端都行），想进入 iOS 开发；或者写过大半年 iOS，但对证书、内存、系统权限、上架总觉得心里没底的同学。

这篇文章是我从「被证书签名折磨到怀疑人生」到「能独立上架一个 App」的完整复盘。照例不讲完所有 API（Apple 官方文档比我权威），只讲五件事，由浅到深排布：

环境搭建：新人第一道鬼门关，很多人还没写代码就死在这里。
Swift 语法主干：真正重要的 20%。
UI 技术选型：SwiftUI 还是 UIKit，以及那些绕不开的第三方库。
系统特性与中级内功：页面写得好只是前台功夫，和系统打交道、把 App 做「上线级」才是后台功夫。
AI 时代的开发方式：怎么让 AI 帮你写掉 70% 的代码，以及剩下的 30% 为什么恰恰最值钱。

先给一张全文路线图：

flowchart LR
    A["环境搭建<br/>Xcode / 证书 / 模拟器"] --> B["Swift 语言<br/>Optional / 闭包 / 协议"]
    B --> C["UI 开发<br/>SwiftUI 或 UIKit"]
    C --> D["系统特性<br/>定位 存储 网络 通知 唤起"]
    D --> E["中级内功<br/>生命周期 架构 测试 发布"]
    E --> F["AI 协同开发<br/>更少代码 更快交付"]

第一篇环境搭建：新人劝退第一关

1.1 你需要什么

iOS 开发有个绕不开的前提：你需要一台 Mac。Apple 的生态是封闭的，Xcode 只跑在 macOS 上。

flowchart TB
    A["Mac（macOS 最新版）"] --> B["App Store 下载 Xcode<br/>约 10GB+"]
    B --> C["Xcode 内含<br/>编译器 / 模拟器 / 调试器"]
    C --> D["注册 Apple ID<br/>免费，可跑真机（7 天签名）"]
    D --> E["付费开发者账号<br/>99 美元/年，上架必备"]

预算建议：M 系列芯片的 Mac mini 是性价比之选；硬盘务必 512GB 起步——Xcode 本体加几个模拟器系统镜像，轻松吃掉 100GB。

踩坑故事 1：App Store 下载 Xcode 卡了三天

新人第一天，App Store 下载 Xcode 进度条走到 80% 反复失败。这是 App Store 的祖传毛病。正确姿势：去 Apple Developer 官网下载 .xip 安装包，或者用开源的 Xcode 版本管理器 xcodes 安装。后者还能同时管理多个 Xcode 版本，老项目用旧版、新项目用新版，互不打架。

1.2 证书与签名：iOS 开发的「百慕大三角」

开发阶段你迟早会撞见这个错误：

Code Signing Error: No signing certificate "iOS Development" found

先理解原理，再看图：

flowchart LR
    A["你的 Mac<br/>私钥 + CSR"] -->|"请求"| B["Apple 开发者后台<br/>签发证书"]
    B --> C["描述文件 Provisioning Profile<br/>绑定：证书 + 设备 + AppID"]
    C --> D["Xcode 打包时用私钥签名"]
    D --> E["iPhone 验证签名后允许运行"]

三样东西必须对应上：证书（你是谁）、AppID（哪个应用）、设备（哪台手机）。任何一个对不上，真机就跑不起来。

踩坑故事 2：上线前夜，证书被同事 Revoke 了

公司账号多人共用，一位同事在自己电脑上「修复」签名问题时，随手点了 Revoke 旧证书——全团队的 CI 打包瞬间全部失败，第二天就是提审截止日。连夜重新生成证书、更新描述文件、改 CI 配置，凌晨四点才出包。

两条教训：第一，优先用 Xcode 的 Automatically manage signing，别手动折腾证书；第二，团队共用账号时，证书动任何操作前在群里吼一声。有条件的话上 fastlane match，用 Git 仓库统一管理证书，谁也别乱动。

1.3 第一个 App：5 分钟跑起来

Xcode → Create New Project → iOS → App，Interface 选 SwiftUI，Language 选 Swift。然后你就得到了一个能跑的 App：

import SwiftUI

struct ContentView: View {
    var body: some View {
        VStack {
            Image(systemName: "globe")
                .imageScale(.large)
            Text("Hello, iOS!")
        }
        .padding()
    }
}

Cmd + R 跑模拟器。第一次编译会慢（在构建模块缓存），之后增量编译很快。

第二篇 Swift 语法：只吃主干

Swift 是一门现代、严谨、有点「强迫症」的语言。它的设计哲学一句话概括：让错误尽量发生在编译期，而不是用户的手机上。

2.1 可选类型（Optional）：Swift 的灵魂

这是 Swift 与其他语言最大的心智差异，也是新人崩溃的第一来源：

var name: String? = "方糖猫"   // ? 表示：可能有值，也可能是 nil

// 错误：编译不过
// print(name.count)

// 正确姿势一：if let 解包
if let unwrapped = name {
    print(unwrapped.count)
}

// 正确姿势二：guard let（函数里更常用）
func greet(name: String?) {
    guard let name = name else {
        print("没名字"); return
    }
    print("你好，\(name)")
}

// 正确姿势三：?? 提供默认值
print(name ?? "匿名")

flowchart TD
    A["拿到一个 Optional 值"] --> B{"确定它永远有值？"}
    B -->|"99% 的情况：不确定"| C["if let / guard let / ??<br/>安全解包"]
    B -->|"确定（极少）"| D["! 强制解包"]
    D -.->|"万一它是 nil"| E["💥 直接崩溃闪退"]

踩坑故事 3：一个 ! 毁掉的评分

接手过一个老项目，前任开发为了省事到处强制解包：dict["avatar"]!、array.first!、Int(str)!。某天后端接口调整，一个字段从必有变成可能缺失，线上崩溃率当天飙到 3%，App Store 评分一周掉了 1.2 分。

修复原则很简单，执行起来要毅力：全项目搜 !，每一个都要能说出「它为什么不可能为 nil」，说不出的就改成安全解包。Crashlytics 的崩溃报表里，强制解包常年霸榜，这是 iOS 界公开的秘密。

2.2 struct 与 class：值类型和引用类型的分野

// struct：值类型，拷贝的是内容本身
struct Point { var x: Int; var y: Int }
var p1 = Point(x: 1, y: 1)
var p2 = p1
p2.x = 99
print(p1.x)  // 还是 1，互不影响

// class：引用类型，拷贝的是「门牌号」
class ViewModel { var title = "" }
let vm1 = ViewModel()
let vm2 = vm1
vm2.title = "改了"
print(vm1.title)  // "改了"，两个变量指向同一个对象

这个区别和 JavaScript 里「基本类型 vs 对象」一模一样，但 Swift 把它变成了显式的设计决策。经验法则：数据模型一律用 struct，需要共享状态和身份标识（ViewModel、Service）才用 class。

2.3 闭包与循环引用：内存管理必修课

Swift 用 ARC 自动管理内存，但有一个经典陷阱：两个 class 互相强引用，谁都释放不掉。

flowchart LR
    A["ViewController<br/>强引用"] --> B["Service"]
    B -->|"闭包捕获 self<br/>强引用回去"| A
    C["打破循环：闭包里写 [weak self]"] -.-> B

class DetailViewController: UIViewController {
    let service = DataService()

    func load() {
        // 错误：service 的闭包强引用 self，self 强引用 service，内存泄漏
        // service.fetch { self.updateUI() }

        // 正确：[weak self] 让闭包弱引用
        service.fetch { [weak self] data in
            self?.updateUI(with: data)
        }
    }
}

踩坑故事 4：越用越卡的 App

一个信息流 App 被用户投诉「刷十分钟就卡死」。用 Xcode 的 Memory Graph 一查：每进入一个详情页就泄漏一个 ViewController，退出页面后内存一点没降。罪魁祸首就是详情页里七八个网络回调闭包全都没写 [weak self]。逐页修复后，内存曲线从「阶梯式上升」变成了正常的「上下波动」。

感悟：前端开发者转 iOS 最容易在这里翻车——JavaScript 的垃圾回收帮你兜了底，而 Swift 的 ARC 是引用计数，循环引用它不回收。写闭包时肌肉记忆地加上 [weak self]，是 iOS 开发者的职业本能。

2.4 异步：async/await 与结构化并发

Swift 的 async/await 和 JavaScript 的很像，但多了「结构化并发」的约束：

struct User: Codable {
    let id: Int
    let name: String
}

func fetchUser(id: Int) async throws -> User {
    let url = URL(string: "https://api.example.com/users/\(id)")!
    let (data, _) = try await URLSession.shared.data(from: url)
    return try JSONDecoder().decode(User.self, from: data)
}

// 调用处
Task {
    do {
        let user = try await fetchUser(id: 1)
        print(user.name)
    } catch {
        print("请求失败：\(error)")
    }
}

需要并行时，用 async let——它保证所有并发任务在离开作用域前完成，不会像 JS 的 forEach(async...) 那样「放出去就没人管」：

async let user = fetchUser(id: 1)
async let orders = fetchOrders(userId: 1)
let (u, o) = try await (user, orders)  // 两个请求并行发出，这里等齐

2.5 协议（Protocol）：Swift 的接口哲学

protocol Drawable {
    func draw()
}

extension Drawable {
    func draw() { print("默认实现：画一个方块") }  // 协议可以有默认实现！
}

struct Circle: Drawable {
    func draw() { print("画一个圆") }
}

协议 + 默认实现（POP，面向协议编程）是 Swift 相对 Java/OC 的一大进化。第三方库大量用它做抽象，读源码时满屏都是。

2.6 阶段小结

Swift 入门标准：

看到 ? 和 ! 能条件反射地想「这里会不会是 nil」。
能徒手解释 struct 和 class 的三个区别（拷贝语义、继承、ARC）。
写闭包时下意识加 [weak self]。
会用 Codable 一行解析 JSON，不再手写字典取值。

第三篇 UI 开发：SwiftUI 还是 UIKit

3.1 两条路线的正面比较

flowchart TB
    subgraph UIKit["UIKit（2008 - ）"]
        A1["命令式：手动改 UI"]
        A2["生态成熟 资料多"]
        A3["老项目全是它"]
    end
    subgraph SwiftUI["SwiftUI（2019 - ）"]
        B1["声明式：UI = f(状态)"]
        B2["代码量少一半"]
        B3["iOS 13+ 才有"]
    end
    Q{"2026 年，学哪个？"}
    Q --> UIKit
    Q --> SwiftUI

UIKit 是命令式的：你手动创建 label、设 frame、加到视图层级。SwiftUI 是声明式的：你描述「状态是这样时，界面该长这样」，框架负责同步。写前端的同学会发现，SwiftUI 的思想和 Vue/React 一脉相承——数据驱动视图。

我的建议：学 SwiftUI 为主，UIKit 懂个大概。新项目几乎都是 SwiftUI 起手，但存量项目、某些复杂控件（高度自定义的列表、绘图）依然是 UIKit 的天下，两者通过 UIViewRepresentable / UIHostingController 互相嵌套，不是非此即彼。

3.2 SwiftUI 核心三板斧

struct CounterView: View {
    @State private var count = 0          // 状态：一变 UI 自动刷新

    var body: some View {
        VStack(spacing: 16) {             // 布局：VStack / HStack / ZStack
            Text("点击了 \(count) 次")
                .font(.title)
            Button("点我 +1") {
                count += 1
            }
            .buttonStyle(.borderedProminent)
        }
        .padding()
    }
}

三个概念吃透，SwiftUI 就懂了一半：

@State：组件私有的状态，改了自动刷新 UI。
View 协议 + body：每个界面都是「状态的函数」。
修饰符链：.font().padding().background() 这种链式调用，顺序不同结果可能不同。

踩坑故事 5：修饰符顺序引发的「灵异布局」
Text("你好")
    .padding()
    .background(Color.blue)   // 背景包住 padding，蓝底很大

Text("你好")
    .background(Color.blue)
    .padding()                // 先蓝底再撑开，padding 是透明的
新人以为修饰符像 CSS 一样「无顺序」，调了俩小时布局没对上设计稿。记住：SwiftUI 的每个修饰符都返回一个新 View，修饰符是从内往外一层层包裹的。想不通就念口诀：「谁在前，谁靠里」。

3.3 数据流：状态从哪来，往哪去

SwiftUI 的状态管理有一套属性包装器，选错一个就是 bug 温床：

flowchart TB
    A["@State<br/>本组件私有的值类型状态"]
    B["@StateObject<br/>本组件创建并拥有的 ViewModel"]
    C["@ObservedObject<br/>外面传进来的 ViewModel<br/>我不拥有 只是观察"]
    D["@EnvironmentObject<br/>全局注入的对象<br/>深层子孙直接取用"]
    E["@Binding<br/>父组件状态的引用<br/>子组件可以回写"]

踩坑故事 6：@ObservedObject 导致的状态「复活」

一个表单页用 @ObservedObject var vm = FormViewModel()——看着没问题，但这个 ViewModel 应该在父级创建并持有。结果父视图每次刷新，子视图的 ViewModel 就被重建，用户填到一半的表单数据凭空消失。

修法一行：改成 @StateObject（本组件是主人）或让父级用 @StateObject 创建后传入（子级用 @ObservedObject 接收）。记忆法：谁创建，谁 StateObject；只接收，就 ObservedObject。这条规则和 Vue 里「状态的唯一权威来源」异曲同工。

3.4 主流组件库与工具库

iOS 的第三方库生态这些年收敛得很厉害，下面是真正高频出现的：

库	干什么	备注
SnapKit	UIKit 布局的 DSL	手写 Auto Layout 必备
Kingfisher	图片异步加载与缓存	图片界的标配
Alamofire	网络请求封装	纯 SwiftUI 新项目可用原生 `URLSession`
Lottie	播放 AE 导出的动画 JSON	复杂动效的唯一解
KeychainAccess	钥匙串存取	存 token 见第四篇
SwiftLint	代码风格检查	团队项目标配

包管理工具的选择也已经尘埃落定：

flowchart LR
    A["CocoaPods<br/>老牌 重 侵入工程文件"] -.->|"逐渐淡出"| C
    B["Carthage<br/>去中心化 手动"] -.->|"边缘化"| C
    C["SPM Swift Package Manager<br/>Apple 官方 Xcode 内置<br/>新项目首选"]

新项目一律 SPM。CocoaPods 只在维护老项目时才会碰到了。

踩坑故事 7：一个第三方库拖垮整个编译

项目里接了一个功能很全但质量堪忧的统计 SDK，它要求旧版 Alamofire，而我们网络层已经升到新版，版本冲突导致 SPM 解析失败；更糟的是它混编了 OC，桥接头文件改动让全量编译时间从 3 分钟涨到 11 分钟。最后痛下决心自研了那部分功能（实际只有 200 行代码），编译时间回落，还少了一坨黑盒。

感悟：引第三方库的成本不是接入那一天，而是之后每一年。评估标准是：核心功能是否不可替代？维护是否活跃？能不能用 200 行自研替代？苹果的官方 API 每年都在吃掉第三方库的地盘（比如 URLSession 已经很好用），优先用官方的。

3.5 Demo：一个完整的 SwiftUI 待办 App

把上面的知识串起来——列表、状态、ViewModel、本地持久化，这个 Demo 可以直接跑：

import SwiftUI

// MARK: - 模型（值类型，Codable 方便持久化）
struct Todo: Identifiable, Codable {
    var id = UUID()
    var text: String
    var done: Bool = false
}

// MARK: - ViewModel
class TodoStore: ObservableObject {
    @Published var todos: [Todo] = [] {
        didSet { save() }                    // 数据一变就落盘
    }

    private let key = "todos_v1"

    init() { load() }

    func add(_ text: String) {
        let trimmed = text.trimmingCharacters(in: .whitespaces)
        guard !trimmed.isEmpty else { return }
        todos.append(Todo(text: trimmed))
    }

    func delete(at offsets: IndexSet) {
        todos.remove(atOffsets: offsets)
    }

    private func save() {
        if let data = try? JSONEncoder().encode(todos) {
            UserDefaults.standard.set(data, forKey: key)
        }
    }

    private func load() {
        guard let data = UserDefaults.standard.data(forKey: key),
              let saved = try? JSONDecoder().decode([Todo].self, from: data)
        else { return }
        todos = saved
    }
}

// MARK: - 视图
struct TodoListView: View {
    @StateObject private var store = TodoStore()   // 本视图创建并拥有
    @State private var newText = ""

    var body: some View {
        NavigationStack {
            List {
                ForEach($store.todos) { $todo in    // $ 生成 Binding，可回写
                    HStack {
                        Image(systemName: todo.done ? "checkmark.circle.fill"
                                                    : "circle")
                            .foregroundStyle(todo.done ? .green : .gray)
                            .onTapGesture { todo.done.toggle() }
                        Text(todo.text)
                            .strikethrough(todo.done)
                    }
                }
                .onDelete(perform: store.delete)     // 侧滑删除，白送
            }
            .navigationTitle("待办（\(store.todos.filter { !$0.done }.count)）")
            .safeAreaInset(edge: .bottom) {
                HStack {
                    TextField("回车添加", text: $newText)
                        .textFieldStyle(.roundedBorder)
                        .onSubmit {
                            store.add(newText)
                            newText = ""
                        }
                }
                .padding()
                .background(.bar)
            }
        }
    }
}

不到 80 行，你得到了：增删改查、勾选完成、侧滑删除、重启不丢数据。同等功能用 UIKit 写，代码量至少翻两倍——这就是声明式 UI 的威力。

第四篇 iOS 系统特性：定位、存储、网络、通知与唤起

页面写得好只是「前台功夫」，App 和系统打交道的能力才是「后台功夫」。这一篇讲五个真实 App 绕不开的系统能力。它们的坑有一个共同特征：Demo 里都好好的，一到用户手机上就出事。

4.1 定位：权限分级比 API 本身重要

iOS 定位用 CoreLocation，API 本身不复杂，复杂的是权限体系这些年越收越紧：

flowchart TD
    A["请求定位权限"] --> B{"Info.plist 配了用途说明？<br/>NSLocationWhenInUseUsageDescription"}
    B -->|"没配"| C["💥 不弹窗甚至直接崩溃<br/>新人第一坑"]
    B -->|"配了"| D{"用户怎么选的？"}
    D -->|"使用 App 期间允许"| E["前台定位可用"]
    D -->|"始终允许"| F["后台也能定位<br/>需先拿前台权限再升级"]
    D -->|"拒绝"| G["优雅降级<br/>引导去系统设置"]
    E --> H{"iOS 14+ 用户开了<br/>『精确位置』吗？"}
    H -->|"开了"| I["米级精度"]
    H -->|"关了"| J["⚠️ 只有约 1-3km 精度<br/>代码必须兼容"]

发起定位的 Demo：

import CoreLocation

class LocationService: NSObject, CLLocationManagerDelegate {
    private let manager = CLLocationManager()
    private var continuation: CheckedContinuation<CLLocation?, Never>?

    override init() {
        super.init()
        manager.delegate = self
        manager.desiredAccuracy = kCLLocationAccuracyBest
    }

    func currentLocation() async -> CLLocation? {
        manager.requestWhenInUseAuthorization()   // 触发权限弹窗
        return await withCheckedContinuation { cont in
            self.continuation = cont
            manager.requestLocation()             // 请求一次新定位
        }
    }

    func locationManager(_ m: CLLocationManager, didUpdateLocations locs: [CLLocation]) {
        continuation?.resume(returning: locs.last)
        continuation = nil
    }

    func locationManager(_ m: CLLocationManager, didFailWithError error: Error) {
        continuation?.resume(returning: nil)
        continuation = nil
    }
}

踩坑故事 9：外卖 App 定位把用户送到了两公里外

一个本地生活 App 上线后收到大量投诉：「定位的取货点离我两公里」。排查发现这批用户都在 iOS 14+ 的权限弹窗里关掉了**「精确位置」开关**——这是 Apple 给的模糊定位选项，App 拿到的坐标被人为偏移了。

解法：拿到定位后检查 manager.accuracyAuthorization，如果是 .reducedAccuracy，在 UI 上明确提示「当前为模糊定位，可能影响取货点推荐」，并给一键跳系统设置的入口。这个开关在权限弹窗里毫不起眼，但对 LBS 类 App 是生死线。

另外提醒做国内地图的同学：iOS 原生定位返回的是 WGS-84 坐标，画到高德地图前要转 GCJ-02，接百度地图要转 BD-09——坐标系天坑在 Android 和 iOS 上是同一口，偏移几百米、用户「站在河里」的事故两边都不少见。

4.2 本地存储：四个层级，各管各的

「存东西」在 iOS 里不是一件事，先想清楚存什么：

flowchart TD
    Q{"要存什么？"}
    Q -->|"设置项 开关 小数据"| A["UserDefaults<br/>最简单 明文存储"]
    Q -->|"token 密码 敏感信息"| B["Keychain<br/>系统级加密<br/>卸载 App 后还在"]
    Q -->|"结构化数据<br/>离线缓存 消息列表"| C["SwiftData / Core Data<br/>见 5.3 节"]
    Q -->|"图片 日志 大文件"| D["沙盒文件目录<br/>Documents / Caches"]

踩坑故事 10：token 存进 UserDefaults，跟着 iTunes 备份「裸奔」

安全团队做渗透测试时发现：App 的登录 token 存在 UserDefaults 里，用 iTunes 做一个未加密备份，就能在备份文件里直接读到明文 token——拿着它就能以用户身份调通所有接口。

UserDefaults 的 plist 文件明文躺在沙盒里，还会进 iCloud/iTunes 备份。敏感信息唯一的正确归宿是 Keychain：
import KeychainAccess
let keychain = Keychain(service: "com.example.myapp")
try keychain.set(token, key: "accessToken")
let saved = try keychain.get("accessToken")
顺带记住 Keychain 的一个反直觉特性：App 卸载重装后，Keychain 里的数据还在。利用它可以做「卸载重装免登录」，但也别拿它存不该留的东西。

沙盒目录的分工也值得一提：

flowchart LR
    A["Documents/<br/>用户产生的数据<br/>会被 iCloud 备份"] --> S["沙盒"]
    B["Library/Caches/<br/>可重建的缓存<br/>系统空间不足时会清"] --> S
    C["tmp/<br/>临时文件<br/>随时可能被清"] --> S

把几个 GB 的缓存视频塞进 Documents，用户的 iCloud 备份会被撑爆，审核也可能找你麻烦——缓存进 Library/Caches，这是规矩。

4.3 网络：URLSession 的完整封装

2.4 节讲了 async/await 的姿势，这里把网络层补完。iOS 新项目的网络层可以完全不用第三方库，URLSession 已经够用：

enum APIError: Error {
    case httpError(Int)
    case decodingError
}

actor APIClient {
    static let shared = APIClient()
    var token: String?

    private let session: URLSession = {
        let config = URLSessionConfiguration.default
        config.timeoutIntervalForRequest = 15    // 弱网常态，超时必须配
        return URLSession(configuration: config)
    }()

    func get<T: Decodable>(_ path: String) async throws -> T {
        var request = URLRequest(url: URL(string: "https://api.example.com\(path)")!)
        if let token {
            request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
        }
        let (data, response) = try await session.data(for: request)
        guard let http = response as? HTTPURLResponse else { throw APIError.httpError(-1) }
        guard (200..<300).contains(http.statusCode) else { throw APIError.httpError(http.statusCode) }
        do {
            return try JSONDecoder().decode(T.self, from: data)
        } catch {
            throw APIError.decodingError
        }
    }
}

踩坑故事 11：测试环境一切正常，正式包所有请求都失败

联调时后端给的是 http:// 测试地址，为了图快在 Info.plist 里加了 NSAppTransportSecurity → NSAllowsArbitraryLoads = YES，全局放开了 HTTP。提审时被 Apple 要求说明理由，更糟的是正式环境的某个 CDN 域名忘了配证书，HTTPS 升级漏了它——而全局开关掩盖了问题，直到审核人员用特定网络环境才暴露。

ATS（App Transport Security）是 Apple 强制 HTTPS 的机制，默认拦截明文 HTTP。正确姿势不是全局放开，而是用 NSExceptionDomains 为个别域名开白名单，并推动后端全量 HTTPS。审核时对任意加载开关是要写书面理由的，别给自己找事。

4.4 消息通知：iOS 最省心也最「一生一次」的能力

通知分两种：本地通知（App 自己定时触发，如提醒事项）和远程推送（服务器经 APNs 推下来）。

先说一个 iOS 相对 Android 的巨大优势：推送通道统一走 APNs。Apple 的推送服务是系统级的，App 被杀了也能收到通知——不存在 Android 那种「华为小米 OPPO 各接一套厂商通道」的割裂生态。这是 iOS 开发者少有的幸福时刻。

flowchart LR
    A["你的服务器"] -->|"携带 deviceToken"| B["APNs<br/>Apple 推送服务"]
    B -->|"系统级投递"| C["用户手机<br/>App 被杀也能收到"]
    D["App 启动时<br/>registerForRemoteNotifications"] -->|"拿到 deviceToken 上报服务器"| A

本地通知的 Demo（提醒类 App 的核心）：

import UserNotifications

// 第 1 步：申请权限（时机见踩坑故事 12）
let center = UNUserNotificationCenter.current()
let granted = try await center.requestAuthorization(options: [.alert, .sound, .badge])

// 第 2 步：排一个 5 秒后的通知
let content = UNMutableNotificationContent()
content.title = "该喝水了"
content.body = "起来活动一下"
content.sound = .default

let trigger = UNTimeIntervalNotificationTrigger(timeInterval: 5, repeats: false)
let request = UNNotificationRequest(identifier: "drink", content: content, trigger: trigger)
try await center.add(request)

踩坑故事 12：通知权限弹窗，一生只有一次机会

新人常在 App 启动第一屏就调 requestAuthorization——用户还没搞懂这 App 是干嘛的，看到弹窗本能地点了「不允许」。这一拒就是永久：之后再调用不会弹任何窗口，想改只能引导用户自己去系统设置里翻，转化率惨不忍睹。一个工具类 App 的推送开启率，因为这个改动从 12% 涨到 47%。

正确姿势：先弹一个自己的预引导页，讲清楚「开启通知能及时收到订单状态」，用户点了「好的」再触发系统弹窗。被预引导页拒绝没有任何代价——系统弹窗那张底牌还攥在手里。

另一个高频坑：App 在前台时，推送默认不弹横幅、不响铃，需要实现 UNUserNotificationCenterDelegate 的 willPresent 方法并返回 [.banner, .sound]，否则用户在 App 里操作时收消息毫无感知。

4.5 App 唤起：Universal Links 与 URL Scheme

「唤起」分两个方向：别人拉起你（短信、网页、二维码里的链接），你拉起别人。

flowchart TD
    Q{"从哪拉起你的 App？"}
    Q -->|"网页/短信里的 https 链接"| A["Universal Links<br/>需配置 apple-app-site-association<br/>体验最好 不可抢注"]
    Q -->|"其他 App / 二维码"| B["URL Scheme<br/>myapp://detail/123<br/>简单但可被其他 App 抢注"]

Universal Links 配置要点：在 Xcode 的 Signing & Capabilities 里加 Associated Domains（applinks:ftmao.com），并在你的网站根路径放一个 apple-app-site-association 文件（无后缀的 JSON）。接收端用 SwiftUI 的 onOpenURL：

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    // 解析 https://ftmao.com/app/detail/123
                    if let id = url.pathComponents.last {
                        router.navigate(to: .detail(id: id))
                    }
                }
        }
    }
}

踩坑故事 13：Universal Link 全配置好了，就是不生效

按出现概率排查：
flowchart TD
 A["点了链接只开 Safari 不拉起 App"] --> B{"AASA 文件能访问吗？ https://域名/apple-app-site-association"}
 B -->|"404 或要求登录"| C["文件没放对位置 必须无后缀 纯 JSON"]
 B -->|"能访问"| D{"中间有重定向吗？"}
 D -->|"有"| E["⚠️ AASA 文件不允许重定向 包括 http 跳 https"]
 D -->|"没有"| F{"是在 Safari 地址栏 直接输入的吗？"}
 F -->|"是"| G["地址栏输入不会触发 必须在网页/短信里『点击』"]
 F -->|"否"| H{"之前长按选过 『在 Safari 打开』？"}
 H -->|"是"| I["系统记住了你的选择 长按链接选『在 App 中打开』恢复"]
最后一条最隐蔽：用户在链接上长按选过一次「在 Safari 中打开」，iOS 就记住了这个域名不再拉起 App，之后怎么点都没反应。测试同事就栽在这上面，以为功能坏了，其实只是他自己的手机被系统「记住」了。

4.6 平台适配：iOS 的约束比碎片化更值得关注

iOS 没有 Android 那种几十种 ROM 的碎片化，但 Apple 用另一种方式给你立规矩——权限、隐私、后台管得更严。以下是反复用到的适配清单：

深色模式

颜色全部用语义色（Color.primary、Color(.systemBackground)）或 Asset Catalog 里配置深色变体，一个写死的 Color.white 背景都不要有——写死颜色的页面在深色模式下就是一块刺眼白斑，而且这种 bug 只在用户半夜打开 App 时才暴露。

动态字体（Dynamic Type）

用 .font(.body)、.font(.title) 这类系统文本样式，字号会跟随用户在系统设置里的偏好自动缩放。写死 .font(.system(size: 14)) 的 App，把字体调大的老年用户看到的依然是小字。

安全区

刘海屏、灵动岛、底部 Home 指示条都会侵占显示区域。底部操作栏用 safeAreaInset(edge: .bottom) 而不是写死 padding，3.5 节的 Demo 里就是这么做的。

后台运行：iOS 是「假后台」，别指望它

flowchart TD
    A["App 切到后台"] --> B["几秒内被挂起<br/>代码停止执行"]
    B --> C{"想继续干活？"}
    C -->|"短时间收尾"| D["beginBackgroundTask<br/>申请约 30 秒"]
    C -->|"周期性任务"| E["BGTaskScheduler<br/>系统决定何时执行"]
    C -->|"等服务器消息"| F["静默推送唤醒<br/>APNs content-available"]

踩坑故事 14：下载功能切后台就「暂停」，用户骂声一片

一个资料下载功能在 Demo 里完美，上线后用户反馈「切到微信回个消息，下载就停了」。原因正是上图：iOS 挂起后台 App 只需几秒。解法是改用 URLSession 的后台配置（URLSessionConfiguration.background）——下载由系统进程接管，App 被杀了都在继续，完成后系统再唤醒你的 App 回调。

感悟：iOS 的假后台不是缺陷，是 Apple 对续航和隐私的坚持。适配它的姿势不是对抗（研究各种保活黑科技，审核还会被拒），而是把任务交给系统：下载给后台 URLSession，定时任务给 BGTaskScheduler，消息给 APNs。系统级方案永远比自己保活可靠。

第五篇中级应知应会：从「能跑」到「上线级」

前四篇能让你写出一个能跑的 App，这一篇补的是不常踩坑但绝不能不知道的硬知识——它们是中级和初级的分水岭。

5.1 App 生命周期：状态恢复是必修课

SwiftUI 时代的生命周期入口在 @main 的 App 结构体和 scenePhase：

stateDiagram-v2
    [*] --> active: App 启动，可交互
    active --> inactive: 来电话/下拉通知栏/切多任务
    inactive --> active: 回到前台
    inactive --> background: 完全切入后台
    background --> inactive: 从后台回来
    background --> [*]: 系统挂起后杀死进程
    note right of background
        进程死亡时不会有任何回调
        重要数据不能指望「退出时再保存」
    end note

@main
struct MyApp: App {
    @Environment(\.scenePhase) private var scenePhase

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .onChange(of: scenePhase) { _, newPhase in
            if newPhase == .background {
                // 切后台时保存草稿、暂停播放器
            }
        }
    }
}

踩坑故事 15：切出去回了个微信，半小时的表单白填了

用户在表单页填到一半，切出去回了条微信，半小时后切回来，App 从启动页重新加载，填的内容全没了。这不是 bug，是进程死亡——App 在后台久了，系统内存不足时直接杀掉整个进程，ViewModel 跟着一起死。

解法分两层：轻量状态（页面位置、草稿）用 @SceneStorage，它会把数据写入进程死亡也能存活的系统存储；重量级数据（表单草稿）在 scenePhase 变 background 时落盘。怎么测？App 切后台后，在 Xcode 里点 Stop 再手动从手机桌面点开——就模拟了进程被杀再恢复。不测这一关，你永远不知道状态恢复写对了没有。

5.2 架构：MVVM + 单向数据流

SwiftUI 和 MVVM 是天生的搭档：

flowchart TD
    subgraph UI层
        A["SwiftUI View<br/>只负责渲染和上报事件"]
    end
    subgraph 状态层
        B["ViewModel<br/>持有 @Published 状态<br/>暴露事件处理函数"]
    end
    subgraph 数据层
        C["Service / Repository<br/>数据的唯一入口<br/>决定走网络还是缓存"]
        D["APIClient<br/>远程数据"]
        E["SwiftData / UserDefaults<br/>本地数据"]
    end
    A -->|"用户事件"| B
    B -->|"状态驱动刷新"| A
    B --> C
    C --> D
    C --> E

三条铁律，比记住「MVVM」三个字母重要得多：

View 不直接碰网络和数据库——SwiftUI 视图里出现 URLSession，就是架构腐烂的开始。
数据向下流，事件向上流：View 只读状态、只发事件，ViewModel 改状态。
ViewModel 不 import SwiftUI：不碰 UI 才能被单元测试覆盖（见 5.4），也才能让 AI（第六篇）安全地帮你改逻辑。

5.3 SwiftData：结构化数据的现代答案

第三篇的 Demo 用 UserDefaults 存 Todo，只够玩具级。真实 App 的结构化数据用 SwiftData（iOS 17+，Core Data 的现代封装）：

import SwiftData

@Model
final class Expense {
    var title: String
    var amount: Double
    var createdAt: Date

    init(title: String, amount: Double) {
        self.title = title
        self.amount = amount
        self.createdAt = .now
    }
}

// 视图里直接用 @Query 查询：数据变了 UI 自动更新
struct ExpenseListView: View {
    @Query(sort: \Expense.createdAt, order: .reverse) private var expenses: [Expense]
    @Environment(\.modelContext) private var context

    var body: some View {
        List(expenses) { expense in
            Text("\(expense.title)：\(expense.amount, format: .currency(code: "CNY"))")
        }
        .onAppear {
            context.insert(Expense(title: "咖啡", amount: 32))  // 自动保存
        }
    }
}

@Query 是 SwiftData 最优雅的用法——数据库一变，查询结果自动更新，UI 自动刷新，「增删改 → 界面刷新」这条链路不用写一行通知代码。需要支持 iOS 15/16 的老项目退回 Core Data，纯本地队列需求也可以考虑轻量的 GRDB（直接写 SQL）。

踩坑故事 16：加了个字段，老用户升级就闪退

新版给 Expense 加了一个 category 字段，自己全新安装测试没问题，上线后老用户打开就崩。原因：老用户手机里的数据库还是旧表结构，新代码按新结构读，版本对不上。

SwiftData 对只新增带默认值的可选字段这类轻量变更能自动迁移，但改字段类型、加必填字段就必须手写 Schema 的迁移计划（VersionedSchema + SchemaMigrationPlan）。教训和 Android 的 Room 一模一样：数据库字段变更是对存量用户的承诺，每次改 @Model，先想「老用户的库里有什么」。开发期可以偷懒删库重装，上线前必须真机装旧版、覆盖安装新版测一遍升级路径。

5.4 测试：少但要有

测试金字塔在移动端同样成立，按性价比排：

flowchart LR
    A["单元测试 多写<br/>ViewModel / 工具函数<br/>毫秒级 不依赖设备"] --> B["UI 测试 精选<br/>核心页面主流程"]
    B --> C["端到端 极少<br/>发版前人工跑一遍"]

单元测试 Demo（Swift Testing，Xcode 16 起的新框架）：

import Testing
@testable import MyApp

struct LoginViewModelTests {
    @Test func 邮箱格式错误时不发起登录() async {
        let vm = LoginViewModel()
        vm.email = "not-an-email"
        await vm.login()
        #expect(vm.emailError == "邮箱格式不对")
        #expect(vm.isLoading == false)
    }
}

务实建议：别追求覆盖率数字。给「钱相关的计算、状态机的转移、数据解析」这三类写单元测试，给「登录、主列表、下单」这三条主链路写 XCUITest，投入产出比最高。UI 层还可以用 SnapshotTesting（截图对比测试）防止 UI 被无意改坏。

5.5 调试三板斧：断点、Memory Graph 与 Instruments

遇到问题时的三板斧，按使用频率排：

断点 + LLDB：po variableName 打印对象，条件断点（右键断点设条件）只在特定数据时停下。经验：别用 print 大法调异步代码，断点比日志可靠得多。
Memory Graph：调试栏的小图标一键生成内存快照，泄漏的对象、循环引用的环都画成图——踩坑故事 4 就是靠它破的案。
Instruments：性能问题终极武器。Time Profiler 找卡顿（主线程耗时调用栈一目了然）、Leaks 查泄漏、Network 看请求瀑布流。发布前拿 Time Profiler 把主流程过一遍，是专业团队的基本功。

日志方面，正经项目用 os.Logger 替代 print——分级、可过滤、能在真机的 Console.app 里回看，排查线上问题时你会感谢自己。

5.6 国际化与无障碍：专业完成度的分水岭

这两件事区分了「能用的 App」和「专业的 App」：

国际化（i18n）

所有文案进 String Catalog（Localizable.xcstrings，Xcode 15+），代码里直接写英文 key，一个硬编码的中文字符串都不要留——今天不国际化，明天产品说「做个英文版」你就要全文搜索替换。
复数和变量用 catalog 的复数规则，别用字符串拼接数字。

无障碍（a11y）

图标按钮加 .accessibilityLabel("返回")——视障用户的 VoiceOver 靠它朗读界面。
可点击区域不小于 44×44 pt，系统组件默认满足，自定义绘制的按钮最容易违规。
配合 4.6 节的 Dynamic Type：字号放大五倍后布局不炸，这条顺带也服务了老年用户。
最后打开 VoiceOver 把自己的 App 主流程走一遍，十分钟，胜过读十篇规范。

5.7 发布上架：TestFlight、审核与隐私合规

flowchart LR
    A["Archive 打包"] --> B["上传到 App Store Connect"]
    B --> C["TestFlight 内测<br/>邀请码分发给测试人员"]
    C --> D["填写元数据<br/>截图 关键词 隐私清单"]
    D --> E["提审"]
    E --> F{"审核"}
    F -->|"通过"| G["发布"]
    F -->|"被拒"| H["看 Resolution Center<br/>改完重提"]

几个中级必懂的点：

TestFlight 是正式发布前的缓冲区：内部测试 100 人免审核，外部测试 1 万人需过一个简化审核。任何「我测过了」的说法，都应该建立在 TestFlight 包上——它和生产包走的是同一条签名和分发链路。
截图和预览视频分尺寸（6.7 寸、6.5 寸、iPad），用模拟器 Cmd+S 截，或 fastlane snapshot 批量生成。
审核时长通常 24-48 小时，紧急情况可以申请加急审核（Accelerated Review），但一年没几次额度，别浪费在「产品经理想早点上」这种事上。

踩坑故事 8（重提）：隐私清单引发的连环拒审

Apple 要求声明 App 用到的「必要理由 API」（文件时间戳、UserDefaults 等）以及所有收集的数据类型。我们第一次提审被打回：用的一个旧版三方统计库偷偷采集了设备 ID，隐私声明里却没写。更新 SDK、补隐私清单（PrivacyInfo.xcprivacy）、重提，前后耗了一周。

教训：隐私合规要在开发期就设计，不是提审前补作业。能不接的统计 SDK 就别接，接了就得为它的一切行为负责——结合踩坑故事 7，第三方库的两笔账（编译成本和合规成本）要一起算。

第六篇 AI 时代：怎么少写代码把 App 做出来

这部分是我最近两年工作方式最大的变化，也是这篇文章最想说的。

6.1 现实：AI 能写多少 iOS 代码

我的实测结论：AI 写 SwiftUI 页面的完成度约 70-90%，写 ViewModel 和业务逻辑约 60-80%，处理证书、签名、上架合规约等于 0。

flowchart TB
    A["需求 / 设计稿"] --> B["人：拆成清晰的任务<br/>写 Prompt"]
    B --> C["AI：生成 View + ViewModel 初稿"]
    C --> D["人：Review + 跑起来验证"]
    D --> E{"有问题？"}
    E -->|"截图 + 报错喂回去"| C
    E -->|"没问题"| F["人：处理 AI 干不了的<br/>签名 / 性能 / 审核"]
    F --> G["提审上架"]

关键变化是：你的角色从「写代码的人」变成「拆任务、验收代码、兜底的人」。

6.2 高效 Prompt 的三个套路

套路一：给足上下文，别让 AI 猜。 差的 Prompt 是「帮我写个登录页」；好的 Prompt 是：

用 SwiftUI 写一个登录页。要求：iOS 17 的 NavigationStack；ViewModel 用 @Observable 宏；账号密码字段校验（账号为邮箱格式，密码至少 8 位）；登录按钮在请求中显示 ProgressView 并禁用；错误用 alert 展示。Model 层已有 struct AuthResponse: Codable { token: String }，网络调用留一个 func login(email:password:) async throws -> AuthResponse 的协议方法，不要写死实现。

上下文越具体（部署版本、已有类型、项目约定），AI 产出能直接用得越多。

套路二：截图驱动开发。 SwiftUI 的一大红利是「所见即所得」特别适合多模态 AI：把设计稿截图发给 AI 生成初版界面，跑起来后再把模拟器截图发回去说「间距不对，标题字号小了」，来回两轮，像素级还原度能到九成。这在 UIKit 时代是不可想象的。

套路三：让 AI 先写测试和协议，再写实现。 先让它定义 protocol UserService，再生成实现和单元测试。有了测试护栏，AI 后续改代码翻车时你能立刻发现——没有测试的 AI 代码，就像没有保险的跑车。

6.3 Demo：一次真实的 AI 协同开发记录

3.5 节那个 TodoList，我用 AI 辅助重写过一版，真实过程是这样：

第一轮（2 分钟）：把半成品代码贴给 AI，说「加上本地持久化，用 UserDefaults + Codable」。它给出了 didSet 里 save 的方案——直接可用。
第二轮（踩坑）：AI 自作主张把 Todo.id 改成了 Int 自增，导致重启后 id 冲突、删除错乱。**这是 AI 代码的典型问题：它能跑通 happy path，但对「持久化后 id 唯一性」这种隐含约束没概念。**我让它改回 UUID()，并补了一条测试。
第三轮：让它加「侧滑删除」和「底部输入栏」，一次通过。

总耗时约 40 分钟，纯手写我估计要 3 小时。省下来的 2 小时 20 分钟去哪了？ 一部分花在 Review AI 的代码上——这恰恰是核心价值所在。

6.4 什么 AI 干不了，什么你必须会

flowchart LR
    subgraph AI擅长["AI 擅长，放手让它写"]
        A1["样板页面 / CRUD 界面"]
        A2["Codable 模型 单元测试"]
        A3["格式化 转换等工具函数"]
    end
    subgraph 人必须懂["AI 容易翻车，人必须把关"]
        B1["内存与生命周期<br/>weak self 状态所有权"]
        B2["系统权限与后台模型<br/>定位 通知 假后台"]
        B3["签名 上架 隐私合规"]
        B4["性能调优<br/>Instruments 读调用栈"]
    end

看出来了吗？AI 干不了的，恰好是这篇文章前面所有「踩坑故事」涉及的东西：循环引用、状态所有权、权限时机、进程死亡、签名、合规。AI 生成的代码照样犯「@ObservedObject 当主人用」「闭包没写 weak self」这些错——能一眼看出它错的人，才能真正驾驭它。

6.5 一些真心话

关于学习路径：「AI 都能写了，还要不要学语法？」——正因为 AI 能写，你才更要懂原理。看不懂的代码你不敢上线，看不懂的 bug 你修不了。AI 时代的学习重心从「记住 API」转向「理解原理 + 会拆任务 + 会验收」。

关于 SwiftUI vs UIKit 的争论：AI 的语料里 SwiftUI 越来越占主流，声明式代码也更适合 AI 生成和修改。这条技术路线的选择，AI 因素已经足以成为加分项。

关于独立开发者：AI 把「一个人做出一个上架 App」的门槛降到了历史最低。设计稿可以 AI 出，代码可以 AI 写大半，连应用图标的文案都能 AI 润色。真正的瓶颈回到了最古老的地方：你想做一个什么东西，它解决谁的问题。技术不再是门槛，判断力才是。

结语

回头看这条路：环境搭建教你敬畏平台规则，Swift 语法教你与编译器合作，UI 选型教你权衡范式，系统特性教你「把任务交给系统」，中级内功教你把 App 做到上线级，而 AI 协同教你把重心放回「想清楚要什么」。

入门的标志是你的 App 能跑在手机上；精通的标志，是审核被拒、线上崩溃、定位漂移、AI 生成了一坨看似能跑的代码时，你都知道问题出在哪、下一步做什么。

祝你的第一个 App 早日上架。

移动开发 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 是放大器，不是替代品

结语：学习路线收个尾

Android 开发从入门到精通：环境搭建、Kotlin、Compose、架构、系统能力与发布全指南

Android 开发从入门到精通：环境搭建、Kotlin、Compose、架构、系统能力与发布全指南

第一篇 环境搭建：90% 的新人倒在这一关

1.1 你需要安装的三样东西

1.2 第一个项目：别折腾，用模板

1.3 踩坑故事一：Gradle 同步转了一小时的圈

1.4 踩坑故事二：AGP、Gradle、JDK 的三角恋情

第二篇 Kotlin 基础：写给会别的语言的人

2.1 十分钟速览：和 Java/JS 的核心差异

2.2 协程：异步代码同步写

第三篇 用 Compose 写出第一个界面

3.1 从 XML 到 Compose：一次范式革命

3.2 主流 UI 组件「库」：答案比前端简单

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

3.4 踩坑故事三：列表滑动卡成 PPT

3.5 踩坑故事四：旋转屏幕，数据全没了

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

4.1 Activity 生命周期：不是八股，是保命符

4.2 四大组件与 Intent：Android 的「宪法」

4.3 Fragment：Compose 时代怎么看它

4.4 架构：MVVM + Repository + 单向数据流

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

5.1 联网的第一步：权限与明文拦截

5.2 Retrofit：网络层的事实标准

5.3 本地存储：四个层级，各管各的

5.4 Room：编译期检查 SQL 的数据库

第六篇 系统能力：定位、通知、唤醒与平台适配

6.1 定位：别再用 LocationManager 了

6.2 消息通知：两段历史决定了今天的写法

6.3 App 唤醒：Deep Link、拉起与被拉起

6.4 平台适配 tips：碎片化才是 Android 的本体

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

7.1 测试：少但要有

7.2 调试三板斧：Logcat、adb 与 Layout Inspector

7.3 国际化与无障碍：专业完成度的分水岭

7.4 发布：签名、混淆与 AAB

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

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

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

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

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

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

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

第一篇环境搭建：90% 的新人倒在这一关

第三篇用 Compose 写出第一个界面

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

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

第六篇系统能力：定位、通知、唤醒与平台适配

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

第一篇环境搭建：新人劝退第一关

第五篇中级应知应会：从「能跑」到「上线级」