JavaScript on 方糖猫Blog

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 文档

前端开发从入门到精通：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 组织界面，用工程化把这一切交付给真实用户。

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

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

《princes》：用 Cocos Creator 写一款餐厅经营放置小游戏

Sat, 05 Sep 2020 21:00:00 +0800

《princes》：用 Cocos Creator 写一款餐厅经营放置小游戏

继《去赶海吧》之后，把更早做的一款餐厅经营小游戏也整理开源了，照例写篇文章介绍玩法和实现上的技术点。仓库名叫 princes（历史遗留命名，内容其实是餐厅），代码里还住着不少从其他项目移民过来的残留，这次一并"考古"出来。

开源地址：https://gitee.com/soulnew/princes
技术栈：Cocos Creator 2.3.4 + JavaScript
平台：微信小游戏（竖屏 720×1280）
规模：39 个脚本，约 4200 行代码，单主场景

游戏核心玩法一句话概括：开一家餐厅，顾客自动上门排队等位、走到餐桌点餐、用餐完留下金币，你点击收金币，再用金币解锁更多食物、餐桌和顾客皮肤——放置 + 点击收菜的经典经营循环。

一、玩法介绍

1.1 核心循环

玩家几乎不直接操作角色，核心是"看店 + 点击收钱 + 花钱解锁"：

graph LR
    A[顾客自动上门<br/>每15秒补1个] --> B{有空餐桌?}
    B -->|有| C[A*寻路走到餐桌]
    B -->|没有| D[门口排队等位]
    D -->|有空桌释放| C
    C --> E[头顶弹气泡点单]
    E --> F[用餐5秒<br/>点击气泡可加速]
    F --> G[桌边产出一堆金币]
    G --> H[玩家点击拾取]
    H --> I[解锁新食物/餐桌/顾客]
    I --> A

几个关键设计：

餐桌是稀缺资源：场上最多 10 个顾客（maxPlayer = 10），没桌子的顾客会在门口按队列序号排开站位，有空桌释放时队首补位、全队前移；
点单匹配：每个顾客皮肤有自己的"可点菜单"（foodList），随机点一道——这道菜已解锁就正常产金币，没解锁就显示"没有这道菜"的图标，等于告诉你"该去商店解锁了"；
巡游消费：顾客吃完饭不直接走，而是从酒柜、古董花瓶、海滩桌等 6 类装饰家具里洗牌出一份"参观清单"，逐件走过去参观，每件停留几秒再留下一笔金币——买装饰家具不只是好看，是真的能多赚钱；
邀请按钮：等不及可以点"邀请"立刻来一位顾客，这个入口同时服务每日任务和成就。

1.2 四屏地图与翻页

餐厅不是一张单屏地图，而是四个房间：海滩（left1）、大厅（mid）、剧院（right1）、花园（down1）。顾客在房间之间穿行时走"传送门"格子——比如大厅到海滩，先寻路到 (0,11) 这个门，切换父节点到海滩场景节点，再从海滩的入口格 (12,11) 继续寻路。

相机不是跟随式的，而是手动拖拽翻页：单轴锁定滑动，滑过屏宽 1/10 左右翻页、屏高 1/14 上下翻页。门口还有两个服务员（waiterPlayer），有顾客进门就弹出欢迎气泡 5 秒——不做实际传菜逻辑，纯氛围组。

1.3 成长线：解锁三件套

金币花在三个商店面板上：

商店	内容	解锁的意义
食物	54 道菜，价格 100~153 递增	顾客点单能匹配上，用餐才产金币
家具	大厅 6 组餐桌（每组 3 级升级）+ 各房间散桌 + 装饰家具	新餐桌 = 多一个接待座位；装饰家具 = 巡游产金币点
顾客	50 种皮肤	新皮肤进入上门顾客的随机池

顾客皮肤的名字很有梗：学士、水电工、警长、老板、小青龙、法师、熊猫、海贼、管道工、侦探、伯爵、外星人、厨神、牙医、流浪歌手、开膛手、屠夫、王少爷、腹肌男、特工K、机器人……基本是把能想到的梗都塞进去了。

1.4 成就与每日任务

15 条成就分 5 种类型：解锁指定物品、解锁 N 种某类物品、服务 N 个顾客、累计金币（500/5000/10000/30000）、邀请 N 次，奖励统一 5000 金币；
每日任务从 7 条里随机洗牌取 6 条（服务顾客 2 次、累计 800 金币、邀请 2 次、招待指定顾客 2 次等），按本地日期键 年_月_日 翻日重置，还会随机指定"今天要招待某位顾客"。

两个系统都有红点提醒，领取后自动检查链上下一档成就。

二、技术亮点

项目不大（4000 行出头），但有几个点是自己撸出来的轮子，值得展开。

2.1 手写 A* + “传送门"式跨屏寻路

寻路没有用任何库，AStar.js（217 行）是手写的标准实现：

地图是 position.json 里一个 21×13 的一维数组（273 个元素，0 可走，其他障碍），screenManager 按屏幕尺寸算出格子边长，做格坐标到像素坐标的换算；
AStarStep 封装 g/h/position/last，f 是 g+h 的 getter；启发函数用曼哈顿距离，八方向扩展，斜走 14、直走 10（经典的 √2×10 近似）；
拿到格子路径后，把每一格转成 cc.moveTo(1, 像素坐标) 拼成 cc.sequence 播放——每格固定走 1 秒，移动节奏完全由动画序列驱动，不需要 update 里手动插值。

跨屏是这套寻路最有意思的部分——四个房间不是一张大地图，而是各自独立的节点树，靠 6 对"门坐标"缝合：

graph LR
    A[当前房间] -->|寻路到门格 mid_left1| B[门 0,11]
    B -->|切换父节点| C[目标房间]
    C -->|从入口格 left1_mid 继续寻路| D[最终目标]

大地图拆成小地图 + 门对，每个房间的寻路空间始终只有 21×13，复杂度和内存都可控，是小工程里很实用的拆法。

2.2 自研虚拟列表 ListView

Cocos 2.x 官方没有现成的虚拟列表，商店、成就、每日任务的长列表就手写了一个（ListView.js，380 行，项目内最大文件）：

NodePool 复用：划出视野的 item 回池，进入视野的从池里取或 instantiate；
增量填充：_filledIds 记录当前树上已填充的索引，update() 每帧用 content 的滚动偏移算起始 item 索引，变了才触发 updateView，只回收越界的、只补缺失的；
Adapter 模式：ListAdapter 持有数据和 item 脚本名，updateView 里 item.getComponent(componentName).setData(data)——Android ListView 的味道很浓，View 和数据彻底分离；
支持多列网格（oneLineItemNumber）、上拉/下拉回调、监听 refreshScollView 事件做局部刷新。

家具面板没用这个 ListView，而是手写了一个更简的裁剪：视野内 opacity=255、视野外 opacity=0。同一项目里两种方案并存，算是"够用就好"和"造个轮子"的对照组。

2.3 餐桌分配：一个微缩排队系统

realTimeData.js 里藏着一个小小的服务台排队模型：

activeFurnitureData 是"空闲桌池”，顾客来了随机抽一张（splice 取出），用完 push 回去；
没桌时顾客进 waitTableQuenue，按 index/maxPlayer 比例在门口插值站位——队伍有多长，人就排多密；
空桌释放时遍历等待队列，队首补位、全队回调前移。

没有定时器轮询，全靠事件驱动，几十行代码把"等位"这个经营游戏的核心张力做出来了。

2.4 运行时程序化动画：两帧图集走天下

所有角色（50 个顾客皮肤 + 2 个服务员）的走路动画都是运行时代码创建的。AnimationBase.js 只有 23 行：

let clip = cc.AnimationClip.createWithSpriteFrames(frames, 1);
clip.wrapMode = cc.WrapMode.Loop;

美术只需要给每个皮肤画两帧（icon/icon2），代码动态建 clip 循环播放，“两帧鬼畜踏步"反而有一种魔性的喜感。50 套皮肤 = 100 帧图 + 一段 23 行的代码，动画资源维护成本为零。这个思路和《去赶海吧》的皮肤动画一脉相承。

2.5 金币堆：对象池 + 聚合拾取

金币是这个游戏最高频的创建/销毁对象，处理上花了最多心思（git 历史里"金币堆积优化"“金币拾取动画效果修改"好几个 commit 都在打磨这块）：

金币走 cc.NodePool（上限 50），生成时随机旋转、1 秒散落动画到桌边随机位置；
同一格子的金币记入 nearGroup 按堆聚合，面额累加进 valueMap——十份饭钱堆成一坨，而不是十个独立节点；
池满时 getGoldByMoveNearby 从邻居堆"借"一个实体过来复用；
点击一堆 → 整堆回收，合成一个 “+总额” 数字标签飞向屏幕左上角的 HUD，飞行时长按距离等比计算，落地才到账。

性能和手感都照顾到了：节点数有上限，拾取有"整堆收进腰包"的爽感。

2.6 事件驱动与成就三态流转

全局只有一个 50 行的事件中心（eventuality.js，出自 Crockford《JavaScript 语言精粹》里的 eventuality 函数），只有 fire/on/removeListener 三个方法，所有跨模块通信——loadover、addGold、unLock、serverPlayer、invite、arriveAtGate、showDialog——都走它。

成就/每日任务系统（两个 Manager 合计 660 行）建立在这个事件中心上，数据按三态流转：

graph LR
    A[unachieveMap<br/>未达成 按类型分桶] -->|事件计数达标| B[waitPayMap<br/>达成待领取]
    B -->|点击领取| C[已领取<br/>写入存档]
    C -->|自动检查| D[链上下一档成就]

事件一来，只检查对应桶里的成就，不用全表扫描；领取后自动把下一档（服务 10 人 → 服务 50 人 → ……）挪进未达成桶继续监听。

三、整体架构一览

graph TD
    subgraph 场景层
        L[loading.fire<br/>微信分包加载] --> G[game.fire<br/>主场景 103节点]
    end
    subgraph 入口与全局
        G --> GAME[game.js<br/>顾客生成/对象池]
        GL[global.js<br/>playerData/event/realTimeData]
        GAME --> GL
    end
    subgraph 玩法层
        GAME --> P[player.js<br/>顾客AI: 排队/寻路/点单/巡游]
        GAME --> W[waiterPlayer.js<br/>迎宾氛围组]
        GAME --> FM[FurnitureManager<br/>家具摆放/餐桌注册]
        GAME --> GM[GoldManager<br/>金币堆/拾取]
        P --> AS[AStar.js<br/>21×13格子寻路]
        P --> SM[screenManager<br/>格子坐标系/跨屏门]
    end
    subgraph 系统层
        AM[AchievementManager<br/>15条成就]
        DM[DailyTaskManager<br/>每日任务随机6条]
        LV[ListView<br/>自研虚拟列表]
        GUI[guide.js<br/>HUD与五个面板]
    end
    subgraph 数据层
        PD[player-data.js<br/>6份json配置+localStorage存档]
        RT[realTimeData.js<br/>餐桌队列/对象池/运行时状态]
    end
    GL --> AM
    GL --> DM
    GL --> PD
    GL --> RT
    GUI --> LV

数据分三层：defines.js 常量表（配置路径 / 存档键 / 事件名）、player-data.js 持久层（6 份 json 配置 + localStorage 存档，配置是 Excel 手填导出的）、realTimeData.js 运行时状态（对象池、餐桌队列、zIndex 发号器）。首次进游戏送 400 金币，默认解锁每类第一个条目。

四、找茬彩蛋

和《去赶海吧》一样，代码里的瑕疵原样保留，欢迎找茬：

A 代价函数传错参*（AStar.js:87）：算邻居格移动代价时，_costToMove(borderPosition, finish) 把终点当成上一个节点传了进去，导致大量格子被按斜走 14 计费、g 值普遍虚高。好在曼哈顿 h 也偏小，错误互相稀释，路还是能找对，只是已经不是标准 A* 了。
全项目调了一个不存在的方法：事件中心只实现了 removeListener，但十几处 onDestroy 里都在调 global.event.off(...)——调用即 TypeError，只是主场景从不销毁所以没炸过。就算有 off，传进去的也是新建箭头函数，永远匹配不上原监听器。
死代码雷区（utils/pathSearch.js）：另一套从未被实例化的 A*，里面有 this.year = '2002' 调试残留、原型方法引用闭包变量（调用即 ReferenceError）、严格模式下裸赋值，是从网上教程抄来没跑通的草稿。paopao.js 和 food.js 则是从泡泡龙/三消项目移民来的——food.js 的 onLoad 会调一个不存在的方法，挂上节点必崩，所以它谁也没挂。
拼写宇宙：createPalyer、walktoTabel、distence、memuPanel 全文通行；最惨的是 awarddiamand（成就表）和 awarddiamond（家具表）两种拼法并存，AchievementItem.getAward 只认前者，家具表里的钻石奖励永远读不到。
每日任务污染成就存档（DailyTaskManager.js:220）：每日服务计数误写进了成就用的总计数键；payAward 的 switch 里还有两个永远进不去的 undefined case。

另外 defines.js 里挂着 9 个根本不存在的配置路径（engineerNameConfig……“工程师"暴露了这是从另一个项目复制来的），food.json 里 54 道菜的名字是"食物1"到"食物54”——明显的占位数值没来得及填。

五、写在最后

从 git 历史能还原出开发顺序：跨屏寻路 → 桌子排队 → 成就系统 → 每日任务 → 钻石 → 金币特效与堆积优化 → 层级修正——先把核心玩法立住，再一层层包外围系统，最后打磨手感。

这是一个典型的个人开发者"麻雀型"项目：4000 行代码里同时住着写得相当讲究的虚拟列表、排队模型、跨屏寻路，和成堆的复制粘贴残留、拼写错误与失效代码。亮点和找茬各占一半，反而更适合做"真实项目代码考古"的样本——毕竟真实项目从来不是教科书。

源码在 https://gitee.com/soulnew/princes，欢迎 Star，也欢迎提 Issue 交流。

Cocos Creator 2.x 实战笔记：动画、事件、向量、资源与避坑指南

Sat, 28 Dec 2019 14:00:00 +0800

Cocos Creator 2.x 实战笔记：动画、事件、向量、资源与避坑指南

本文基于 Cocos Creator 2.x（cc.* API）整理，覆盖从动作动画、输入事件、位置向量、场景管理、音效、资源加载到摄像机跟随等高频知识点。虽然 3.x 已全面转向 TypeScript 与新的组件系统，但 2.x 的核心思想——节点树 + 组件 + 生命周期 + Action 系统——仍然是理解引擎设计的最佳入口。

一、高层次思想：Cocos Creator 在组织什么？

Cocos Creator 的核心理念可以概括为一句话：

“节点（Node）负责层级与变换，组件（Component）负责行为与表现。”

graph TD
    A[Scene 场景] --> B[Canvas]
    B --> C[Node 节点]
    C --> D[Transform 变换]
    C --> E[Sprite 渲染]
    C --> F[Script 脚本]
    C --> G[AudioSource 音效]
    C --> H[PhysicsCollider 物理]
    D --> I[position / rotation / scale]
    F --> J[onLoad / start / update]

1.1 节点树 = 变换层级

每个 cc.Node 都有父节点，子节点的变换会继承父节点。理解这一点才能避免“为什么我改了坐标没效果？”这类问题。

World Space（世界坐标系）
   │
   ├── Canvas (Design Resolution: 720x1280)
   │      ├── Player (position: 0, -400)
   │      │      ├── Head (position: 0, 80)    ← 子节点相对父节点
   │      │      └── Gun  (position: 60, 0)
   │      └── Enemy

1.2 组件生命周期

stateDiagram-v2
    [*] --> onLoad: 场景初始化
    onLoad --> onEnable: 节点激活
    onEnable --> start: 第一次 update 前
    start --> update: 每帧调用
    update --> lateUpdate: update 之后
    lateUpdate --> update: 下一帧
    update --> onDisable: 节点禁用
    onDisable --> onEnable: 重新激活
    onDisable --> onDestroy: 销毁节点

避坑指南 #1：onLoad 中适合获取节点引用和初始化数据；start 中适合访问其他组件（此时场景中所有节点的 onLoad 都已执行完毕）。不要把耗时的初始化放在 update 里。

二、动作系统（Action）：让节点“动起来”

Action 是 Cocos Creator 2.x 中非常优雅的动画封装。它基于组合模式：简单动作可以拼接成复杂序列。

2.1 跳跃动画：位移 + 缓动曲线

// 跳跃上升
var jumpUp = cc.moveBy(this.jumpDuration, cc.v2(0, this.jumpHeight))
    .easing(cc.easeCubicActionOut());

// 下落
var jumpDown = cc.moveBy(this.jumpDuration, cc.v2(0, -this.jumpHeight))
    .easing(cc.easeCubicActionIn());

// 不断重复
return cc.repeatForever(cc.sequence(jumpUp, jumpDown));

xychart-beta
    title "跳跃高度随时间变化"
    x-axis [0, 0.25, 0.5, 0.75, 1.0]
    y-axis "高度" 0 --> 100
    line [0, 80, 100, 80, 0]

避坑指南 #2：moveBy 是相对移动，moveTo 是绝对移动。跳跃一般用 moveBy，因为落地位置取决于起跳点。如果误用 moveTo，角色会跳到固定世界坐标。

2.2 缩放与回调：序列动作

cc.sequence(
    cc.scaleTo(dua, 0.8, 0.8),
    cc.scaleTo(dua, 1, 1),
    cc.callFunc(() => {
        paopaoNode.destroy();
    })
);

2.3 旋转

var rotationTo = cc.rotateTo(1, 0, 180);
this.paiNode.runAction(rotationTo);

2.4 左右晃动（以锚点为原点）

var seq = cc.sequence(
    cc.rotateTo(0.2, 15),
    cc.rotateTo(0.4, -15),
    cc.rotateTo(0.4, 15),
    cc.rotateTo(0.4, -15),
    cc.rotateTo(0.4, 15),
    cc.rotateTo(0.2, 0),
    cc.delayTime(2)
);
this.node.runAction(cc.repeatForever(seq));

graph LR
    A[初始 0°] --> B[右偏 +15°]
    B --> C[左偏 -15°]
    C --> D[右偏 +15°]
    D --> E[左偏 -15°]
    E --> F[回正 0°]
    F --> G[停顿 2s]
    G --> A

避坑指南 #3：旋转方向遵循引擎约定，正数为顺时针，负数为逆时针。rotateTo 会尽量选择最短路径到达目标角度；如果需要连续多圈旋转，请用 rotateBy。

2.5 点击时按钮放大

// 在按钮的触摸开始/结束时分别放大与恢复
buttonNode.on(cc.Node.EventType.TOUCH_START, () => {
    buttonNode.runAction(cc.scaleTo(0.1, 1.1, 1.1));
});
buttonNode.on(cc.Node.EventType.TOUCH_END, () => {
    buttonNode.runAction(cc.scaleTo(0.1, 1.0, 1.0));
});

三、输入事件：键盘、触摸与鼠标

3.1 键盘事件

cc.systemEvent.on(cc.SystemEvent.EventType.KEY_DOWN, this.onKeyDown, this);

实现监听函数：

onKeyDown(event) {
    switch(event.keyCode) {
        case cc.macro.KEY.a:
            this.accLeft = true;
            break;
        case cc.macro.KEY.d:
            this.accRight = true;
            break;
    }
}

避坑指南 #4：第三个参数 this 不要漏！否则回调里的 this 会指向 cc.systemEvent，导致 this.accLeft 为 undefined。建议在 onDestroy 中移除监听，避免场景切换后事件泄漏。

3.2 触摸 / 鼠标事件

this.node.on('touchstart', this.touchStart, this);
this.node.on('touchend',   this.touchEnd,   this);

枚举与事件名对照：

枚举	字符串事件名	说明
`cc.Node.EventType.TOUCH_START`	`touchstart`	手指按下
`cc.Node.EventType.TOUCH_MOVE`	`touchmove`	手指移动
`cc.Node.EventType.TOUCH_END`	`touchend`	手指抬起（在节点内）
`cc.Node.EventType.TOUCH_CANCEL`	`touchcancel`	系统中断（如来电）
`cc.Node.EventType.MOUSE_DOWN`	`mousedown`	鼠标按下
`cc.Node.EventType.MOUSE_ENTER`	`mouseenter`	鼠标进入节点
`cc.Node.EventType.MOUSE_MOVE`	`mousemove`	鼠标移动
`cc.Node.EventType.MOUSE_LEAVE`	`mouseleave`	鼠标离开节点
`cc.Node.EventType.MOUSE_UP`	`mouseup`	鼠标抬起
`cc.Node.EventType.MOUSE_WHEEL`	`mousewheel`	滚轮滚动

四、位置向量 Vec2：2D 游戏的数学基础

4.1 生成与设置位置

var pos = cc.v2(randX, randY);
newStar.setPosition(pos);

4.2 距离、长度与运算

// 计算当前节点与玩家之间的距离
var dist = this.node.position.sub(playerPos).mag();

// 返回向量长度
var len = dir.mag();

// 自加（修改原向量）
v.addSelf(cc.v2(5, 5));

// 返回新向量（不修改原向量）
var vnew = v.add(cc.v2(5, 5));

// 缩放
var v = cc.v2(10, 10);
v.mul(5);   // 返回 Vec2 {x: 50, y: 50}
console.log(v); // 仍打印 Vec2 {x: 10, y: 10}

// 判断相等
var res = v.equals(cc.v2(10, 10)); // true

避坑指南 #5：addSelf、mulSelf、subSelf 等方法会修改原向量；不带 Self 的版本会返回新向量。在 update 中计算方向时，若不想意外修改 this.node.position，请使用非 Self 版本。

4.3 线性插值（Lerp）

var v  = cc.v2(10, 10);
var v1 = cc.v2(5, 5);
var v3 = cc.v2(0, 0); // 存储结果
v.lerp(v1, 0.5, v3);  // 在 v 与 v1 之间取 50%
console.log(v3);      // Vec2 {x: 7.5, y: 7.5}

4.4 坐标转换

方法	原点	用途
`convertToWorldSpaceAR(point)`	节点锚点	局部坐标 → 世界坐标
`convertToNodeSpaceAR(point)`	节点锚点	世界坐标 → 局部坐标
`convertToWorldSpace(point)`	节点左下角	不建议，除非 UI 特殊需求
`convertToNodeSpace(point)`	节点左下角	不建议

graph LR
    subgraph 世界坐标系
        direction TB
        A[World Origin] --> B[Player]
    end
    subgraph 局部坐标系
        direction TB
        C[Anchor Point] --> D[(100, 100)]
    end
    B -->|convertToWorldSpaceAR| D
    D -->|convertToNodeSpaceAR| B

避坑指南 #6：Cocos 编辑器默认以锚点（Anchor）为原点，因此优先使用带 AR 的方法。左下角为原点的方法主要用于兼容旧项目或特殊 UI 对齐。

五、场景与生命周期

5.1 重新加载场景

cc.director.loadScene('game');

避坑指南 #7：loadScene 会销毁当前场景所有节点。如果需要在切换前保存数据（如分数、关卡进度），请先写入本地存储，再调用加载。

5.2 暂停与恢复

// 暂停游戏逻辑，但渲染和 UI 响应仍在
cc.director.pause();

// 恢复
cc.director.resume();

常用于弹出结算面板或暂停菜单。

六、透明度、音效与组件

6.1 透明度渐变（实现缓慢消失）

update(dt) {
    this.node.opacity -= 100 * dt;
    if (this.node.opacity <= 0) {
        this.node.destroy();
    }
}

6.2 音效

properties: {
    scoreAudio: {
        default: null,
        type: cc.AudioClip
    }
}

// 播放音效（false 表示不循环）
cc.audioEngine.playEffect(this.scoreAudio, false);

避坑指南 #8：背景音乐请用 playMusic，音效用 playEffect。微信小游戏对同时播放的音频数量有限制，过量的 playEffect 可能导致后续音效被丢弃。

6.3 getComponent：获取组件

newStar.getComponent('Star').game = this;

避坑指南 #9：getComponent 是 Node 的方法，JS 中的方法和属性都挂在组件上。不要把脚本逻辑直接写在场景或节点上，而要写在组件脚本里。

七、屏幕、包围盒与资源加载

7.1 获取视图大小

var winSize = cc.director.getWinSize();

7.2 包围盒

var first_xMax = bgList[0].getBoundingBox().xMax;

getBoundingBox() 返回父节坐标系下的轴向对齐包围盒（AABB），包含 xMin、xMax、yMin、yMax、width、height 等属性。

7.3 加载图片

cc.loader.load(
    { url: "res/raw-assets/resource/texture/gold.png", type: 'png' },
    (err, texture) => {
        var fra   = this.spr2.getComponent(cc.Sprite);
        var sframe = new cc.SpriteFrame(
            texture,
            new cc.rect(20, 20, 100, 120)
        );
        fra.spriteFrame = sframe;
    }
);

cc.rect(20, 20, 100, 120) 表示从图片的 (20, 20) 开始，取宽 100、高 120 的矩形区域，即图片中 (20, 20) 到 (120, 140) 的内容。

避坑指南 #10：微信小游戏对图片尺寸有限制，长宽都不能超过 2048。超出此限制会导致加载失败或显示异常，导入资源前请先检查尺寸。

7.4 加载 Prefab

cc.loader.loadRes(`prefab/game08/${randIdx}`, cc.Prefab, (err, res) => {
    this.drawing = cc.instantiate(res);
    this.drawing.group = "drawing";
});

八、本地存储

// 写入
cc.sys.localStorage.setItem("finishLevel", this.curLevel);

// 读取（注意转换类型，localStorage 只存字符串）
var level = parseInt(cc.sys.localStorage.getItem("finishLevel") || 0);

避坑指南 #11：localStorage 只能存储字符串。存储对象时请先 JSON.stringify，读取后再 JSON.parse。微信小游戏有本地存储上限，重要数据建议结合云端存档。

九、摄像机跟随

9.1 主角简单跟随

// this.node 为 Camera 节点
update(dt) {
    var targetPos = this.player.position;
    this.node.position = targetPos;
}

9.2 主角自然跟随（平滑插值）

update(dt) {
    var targetPos = this.player.position;
    var currentPos = this.node.position;
    currentPos.lerp(targetPos, 0.1, currentPos);
    this.node.position = currentPos;
}

graph LR
    A[Camera 当前位置] -->|lerp 0.1| B[Player 当前位置]
    B --> C[下一帧继续插值]
    C --> D[最终重合]

十、调试、绘制与更新策略

10.1 cc.log

cc.log("只在发布时勾选调试模式才起效");

10.2 Graphics 画图

var g = this.node.getComponent(cc.Graphics);
g.moveTo(0, 0);
g.lineTo(100, 100);
g.stroke();

10.3 打包更新

发布时勾选 MD5 Cache，避免浏览器/微信缓存旧资源。
热更新需配合 cc.assetManager.loadBundle 或官方热更新方案。

cc.assetManager.loadBundle('level2', (err, bundle) => {
    bundle.loadDir('prefabs', (err, assets) => {
        // ...
    });
});

十一、物理关节：旋转关节 RevoluteJoint

// cc.RevoluteJoint 可约束两个刚体围绕一个点旋转
var joint = nodeA.addComponent(cc.RevoluteJoint);
joint.connectedBody = nodeB.getComponent(cc.RigidBody);
joint.anchor = cc.v2(0, 0);
joint.connectedAnchor = cc.v2(0, 50);

常用于门铰链、钟摆、车轮等效果。

十二、帧率与屏幕适配

12.1 锁定帧率

let fps = (cc.sys.os == cc.sys.OS_IOS) ? 40 : 40;
cc.game.setFrameRate(fps);

if (cc.sys.platform == cc.sys.WECHAT_GAME) {
    wx.setPreferredFramesPerSecond(fps);
}

12.2 分辨率适配

let frameSize = cc.view.getFrameSize();
let scrall = frameSize.width / frameSize.height;

cc.view.setResolutionPolicy(cc.ResolutionPolicy.EXACT_FIT);
cc.view.setOrientation(cc.macro.ORIENTATION_LANDSCAPE);

cc.Canvas.instance.fitWidth  = false;
cc.Canvas.instance.fitHeight = false;

let isFitWidth = scrall < 1.77;
cc.Canvas.instance.fitWidth  = isFitWidth;
cc.Canvas.instance.fitHeight = !isFitWidth;

12.3 常用设计分辨率

分辨率	比例	适用场景
720 × 1280	9:16	竖屏手游最常见
640 × 960	2:3	早期 iPhone 经典
1080 × 1920	9:16	高清竖屏
1280 × 720	16:9	横屏手游

graph TD
    A[设计分辨率 720x1280] --> B[实际屏幕分辨率]
    B --> C{选择适配策略}
    C -->|FIT_WIDTH| D[宽度铺满，高度可能裁剪/留黑]
    C -->|FIT_HEIGHT| E[高度铺满，宽度可能裁剪/留黑]
    C -->|EXACT_FIT| F[拉伸铺满，可能变形]
    C -->|SHOW_ALL| G[等比缩放，全部可见，可能留黑]
    C -->|NO_BORDER| H[等比缩放，铺满屏幕，可能裁剪]

十三、网络同步：Colyseus

对于多人实时游戏，Colyseus 是 Cocos Creator 常用的 Node.js 状态同步框架。

同步方式	核心思想	适用场景
状态同步	服务端权威，客户端插值预测	MMO、卡牌、休闲对战
帧同步	只同步输入，客户端各自演算	RTS、MOBA、格斗

避坑指南 #12：帧同步对浮点数一致性和随机种子要求极高。Cocos 2.x 默认使用 JavaScript 浮点运算，跨平台（iOS/Android/微信）可能出现不一致，需统一数学库与随机算法。

十四、避坑清单速查表

编号	避坑点
1	初始化放 `onLoad`，跨组件访问放 `start`
2	`moveBy` 相对移动，`moveTo` 绝对移动，别混用
3	旋转方向：正顺负逆；多圈旋转用 `rotateBy`
4	注册事件必须传 `this`，切场景时记得 `off`
5	向量运算区分 `Self` 与非 `Self` 版本
6	坐标转换优先用带 `AR` 的方法
7	`loadScene` 前保存必要数据
8	音乐用 `playMusic`，音效用 `playEffect`
9	逻辑写在组件脚本里，不要直接挂在节点上
10	微信小游戏图片尺寸不能超过 2048×2048
11	`localStorage` 只存字符串，对象需 JSON 序列化
12	帧同步注意浮点一致性与随机种子

十五、总结

Cocos Creator 2.x 的开发可以归纳为以下流程：

graph LR
    A[搭建场景节点树] --> B[挂载脚本组件]
    B --> C[处理输入事件]
    C --> D[在 update 中更新逻辑]
    D --> E[使用 Action 或逐帧修改属性实现动画]
    E --> F[加载资源 / 切换场景 / 保存数据]

掌握 节点-组件模型、生命周期、Action 组合、Vec2 运算、坐标转换、屏幕适配 这六大核心后，2D 游戏开发中大部分问题都能迎刃而解。希望这份笔记能成为你项目中的速查手册。

JavaScript on 方糖猫Blog

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 统治

十、思考与感悟

十一、学习路线建议

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

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

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

1.1 JavaScript 到底是什么

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

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

1.4 this：JavaScript 最大的心理阴影

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

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

1.7 Demo：手写防抖与节流

1.8 阶段小结

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

2.1 为什么需要 TypeScript

2.2 核心类型速览

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

2.4 类型守卫：收窄的艺术

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

2.6 阶段小结

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

3.1 Vue 3 解决了什么问题

3.2 响应式原理：Proxy 魔法

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

3.4 Composition API：setup 语法糖

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

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

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

3.8 Demo：一个完整的 TodoList

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

3.10 Vue Router：单页应用的路由

第四篇 工程化与心智成长

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

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

4.3 一些真心话

结语

《princes》：用 Cocos Creator 写一款餐厅经营放置小游戏

《princes》：用 Cocos Creator 写一款餐厅经营放置小游戏

一、玩法介绍

1.1 核心循环

1.2 四屏地图与翻页

1.3 成长线：解锁三件套

1.4 成就与每日任务

二、技术亮点

2.1 手写 A* + “传送门"式跨屏寻路

2.2 自研虚拟列表 ListView

2.3 餐桌分配：一个微缩排队系统

2.4 运行时程序化动画：两帧图集走天下

第四篇工程化与心智成长