1. 第一周路线图：微信小程序开发到底先做什么

如果你刚打开微信小程序开发这个大门，第一周最容易犯的错误不是写不出代码，而是被铺天盖地的资料劝退。这个“week1”之所以值钱，是因为它帮你把混乱的起点理成一条线：注册账号、装工具、跑通第一个页面、完成一个能点能用的Demo、在真机上预览发布。

先说结论：一周时间足够让一个零基础的人从“不知道什么是appid”走到“把自己的小程序放到手机上打开”。前提是别贪多，别一上来就研究组件库、云函数、支付流程这些进阶内容。第一周的核心目标是建立“全链路感知”——从账号体系、开发工具、基础语法，到调试发布，每个环节都走一遍，不求精通，但求不慌。

这条路线背后的逻辑很简单：微信小程序不是纯前端的事，你的代码要跑在微信的宿主环境里，所以要理解平台的规矩。账号是入口，没有AppID你连真机预览都做不了；工具是阵地，所有开发都在微信开发者工具里完成；语法是基本功，WXML、WXSS、JavaScript三件套缺一不可；而做一个完整的Demo，是为了把前面所有知识点黏合起来。

说实话，我见过太多人第一周冲去学框架、学UI库、学各种奇技淫巧，最后连一个按钮的事件都没跑通过。微信小程序开发的第一周，最重要的不是炫技，而是把环境、语法、调试这三块地基打牢，后面第二周、第三周才有可能去谈性能优化和架构设计。

1.1 第一周目标拆解：用5个任务替代漫无目的的学习

与其给你一份100小时的视频课清单，我建议把第一周拆成5个具体任务，每个任务都有明确的交付物：

为什么一定要有交付物？因为微信小程序开发是强反馈型活动，你写三行代码，模拟器立刻给你渲染结果。这种反馈如果配合明确的目标，学习效率极高；如果只是漫无目的地看文档，很容易陷入“看懂了，写不出来”的窘境。

我在带新人的时候一直强调：第一周不要写笔记型的代码，要写能用型的代码。哪怕是抄官方示例，也要一行一行敲进去，然后改掉几个参数，看看会发生什么。这个“改参数观察现象”的过程，才是你真正理解小程序运行机制的时候。

1.2 为什么这个顺序不能乱：从平台规则反推学习路径

很多人会问：为什么不能直接学WXML语法？为什么非得先注册账号？答案在于微信小程序的“权限墙”。没有AppID，开发者工具只能用游客模式，很多能力（比如真机预览、请求域名、上传代码）全被锁死，你花两个小时写的页面只能看着模拟器里的假数据发呆。

反过来，如果你先拿下账号和工具，每学一个语法点都能立刻在真机上验证，而且是带真实数据验证。这种“平台规则反推学习路径”的思路，贯穿整个微信小程序开发过程：先搞清楚平台允许什么、限制什么，再去想怎么实现。

举一个最简单的例子：小程序要求所有request请求的域名必须是在后台配置过的合法域名。如果你不知道这条规则，第一周去请求一个接口，报错“url not in domain list”，你会一脸懵；但你知道了规则，就知道开发阶段可以用“不校验合法域名”的选项绕过，上线前再补配置。这就是平台规矩的价值——它不是来为难你的，是来保护用户数据安全的。

第一周就把这些规矩摸个大概，后面的路会顺很多。

2. 账号与工具：小程序开发的基础设施搭建

说实话，注册小程序账号这件事，看似简单，实际能卡住一半的新手。不是说流程复杂，而是大家在“个人主体”和“企业主体”之间反复横跳，导致后面某些能力无法开通，又得退回重来。

2.1 注册账号：个人主体与企业主体的天壤之别

微信小程序后台注册的时候，需要选择主体类型：个人、企业、政府、媒体等。个人主体最大的优势是免费、审核快、只要身份证就能搞定，适合第一周学习练手；但你要知道它的边界：个人主体不支持微信支付、不支持部分类目（比如直播、金融类），获取用户手机号的能力也受限。

企业主体则几乎解锁全部能力，但要走营业执照认证，对公账户打款验证或者法人人脸识别，周期大概1-3天。如果你最终目标是做一个商业项目，建议直接用企业主体注册，不要先个人后迁移，因为小程序的主体一旦注册，后续变更非常麻烦，基本等于重做。

注册完成后，你会得到一个AppID（形如wx开头的一串字符）和AppSecret。第一周你只需要用到AppID，AppSecret主要用于后端调用接口获取access_token，现在还不用碰。

注意：在开发者工具里，AppID填个人主体和企业主体产生的差别，直接决定了“真机预览”是否可用。个人主体注册后依然可以上传体验版，所以第一周完全够用。

2.2 开发者工具：稳定版、开发版怎么选

微信开发者工具分为稳定版、预发布版和开发版。第一周请老老实实用稳定版。开发版听起来高级，但bug多、界面变化快，你搜教程时截图对不上版本就会怀疑人生。稳定版虽然更新慢，但生态里的教程、文档、踩坑记录基本都能覆盖。

安装过程没什么技术含量，但有一个细节值得注意：安装路径尽量不要用中文目录。虽然新版工具对中文路径的兼容性好了很多，但项目路径一旦带中文，涉及到一些编译缓存、第三方npm依赖时，偶尔会出现难以排查的诡异问题。我的习惯是统一用纯英文路径，从源头杜绝这种坑。

第一次打开工具，会让你选择“小程序”还是“小游戏”，这里选小程序。然后创建项目时，不要用默认的“Hello World”模板，而是选择“不使用模板，空白目录”。原因是默认模板里附带了一堆演示代码，反而干扰你对目录结构的理解。从空白项目开始，一行一行自己搭起来，印象才深。

2.3 目录结构：小程序项目的骨架解剖

一个最简小程序项目的目录结构大概是这样的：

project/ ├── pages/ │ ├── index/ │ │ ├── index.js │ │ ├── index.json │ │ ├── index.wxml │ │ └── index.wxss ├── app.js ├── app.json ├── app.wxss ├── project.config.json └── sitemap.json

这四个一组的page文件——js、json、wxml、wxss——是微信小程序开发的常态。js管逻辑，json管页面配置，wxml管结构，wxss管样式。这种“一个页面四个文件”的思想一开始会觉得繁琐，但用熟了会发现它强迫你把页面拆得很干净，一个页面的所有东西都内聚在一起。

app.json是全局配置，里面最核心的是pages数组，它告诉小程序有哪些页面，数组第一项就是启动页。这个数组的顺序极其重要，改动了就等于改了入口。很多人踩过的坑是：新建了一个页面，忘了注册到pages数组里，结果编译报错“page not found”。

app.js是应用入口逻辑，你可以在里面调用wx.login获取登录凭证，或者做一些全局初始化。app.wxss是全局样式，officially、每个页面都能用到。project.config.json是工具配置，记录项目编译选项。sitemap.json则用于配置小程序页面是否能被微信索引，第一周可以忽略它。

2.4 第一个页面：Hello World 但要带着思考写

当你创建完空白项目，打开pages/index/index.wxml，输入一行：

<view>Hello World</view>

在模拟器里看到这行字时，你的微信小程序开发week1就正式开始了。但我建议你多做一步：去index.js里改一下data，再回到wxml用{{}}展示出来。

// index.js Page({ data: { message: 'Hello from data' } })

<!-- index.wxml --> <view>{{message}}</view>

这一步的意义在于，你第一次接触了“数据驱动视图”这个核心概念。小程序的做法是：视图层WXML里写模板，逻辑层JS里管数据，两者通过数据绑定和事件系统通信。这和你以前可能接触的jQuery式DOM操作完全不一样——你不是去找节点改文字，而是改数据，框架帮你刷新视图。这个概念通透了，后面学框架都是顺水推舟的事。

3. WXML、WXSS与JavaScript：小程序页面三件套的核心细节

第二三天，你的主要任务是把页面三件套的基本语法过一遍。这一块内容多，但不需要死记硬背，核心就几个点：WXML的组件和模板语法、WXSS的rpx响应式单位、JS里的setData机制。

3.1 WXML：不是HTML，但比HTML更好理解

WXML长得像HTML，用的是标签语法，比如view对应div，text对应span，image对应img。但它在模板能力上更强，最常用的就是数据绑定和列表渲染。

<view wx:for="{{todos}}" wx:key="id"> {{item.text}} </view>

这段代码的意思是：遍历todos数组，每一项渲染成一个view，item就是当前遍历项。wx:key是列表渲染的key，类似前端框架里的key，用来帮助框架精准复用节点，不加的话控制台会给你黄色警告。

还有条件渲染：

<view wx:if="{{isDone}}">已完成</view> <view wx:else>未完成</view>

这个和普通if-else逻辑一致。需要注意的是wx:if和hidden的区别：wx:if是懒渲染，条件不满足时节点直接不存在；hidden是节点存在但使用display:none隐藏。频繁切换用hidden，懒加载大块内容用wx:if。

WXML的典型应用场景就是“循环渲染列表 + 条件渲染状态”。第一周把这个组合练熟，你的项目就已经能撑起80%的页面结构了。另外一个值得记的事件绑定：bindtap、bindinput、bindchange，这些是在组件上直接绑定的，比如：

<input bindinput="handleInput" />

3.2 WXSS：rpx响应式单位与flex布局

WXSS和普通CSS大体相同，但多了一个核心单位rpx。rpx的设计逻辑很简单：不管什么手机屏幕宽度，一律按750rpx来切分。也就是说，iPhone 6的375px等于750rpx，iPhone 12 Pro的390px也等于750rpx，你用rpx写100宽度，在不同屏幕上显示的比例是一致的。

这个小设计的实用价值非常大。以前做H5适配，要用rem、vw或者媒体查询，写起来麻烦；小程序里直接：

.container { width: 100%; padding: 24rpx; display: flex; flex-direction: column; }

像24rpx这样的间距，在窄屏和宽屏上视觉比例一致，不用额外适配。flex布局在WXSS里也是重头戏，几乎所有页面布局都可以用flex搞定：水平居中、垂直居中、两端对齐、换行排列，一个display:flex加几个属性全解决。

这里有个细节建议：全局样式里先把盒模型统一一下，比如给view和text设置box-sizing: border-box，避免padding撑破容器。在H5时代，这是一个很常见的全局重置方案，在WXSS里同样有效。

3.3 setData机制：数据驱动视图的命脉

小程序里修改数据不能用普通的this.data.message = 'xx'，必须通过this.setData()：

this.setData({ message: '新的值' })

强行用等号赋值，视图不会刷新，因为框架只监听setData触发的变更。理解了这一点，几乎所有的新手bug都能解释清楚：点了按钮没反应，多半是没setData；列表没刷新，多半是改了数组但没setData。

setData是异步的，但数据到视图的更新最终会同步完成。如果你需要在视图更新后再执行某些逻辑，比如获取某个节点的高度，可以在setData的第二个参数回调里做：

this.setData({ activeIndex: 1 }, () => { // 视图已更新，可以测量节点了 })

另一个要点是性能：不要把大数组整体setData。比如一个1000条数据的列表，你只改了其中一条，最优做法是精准定位修改那条数据而不是整个数组重新传入。第一周你可能感受不到差别，但这个习惯要尽早养成，否则第二周做复杂页面时会发现界面卡顿明显。

4. 第一周实战：用待办清单把三件套串起来

如果说前面是“点状学习”，那第四天到第六天你应该做个“面状项目”。待办清单（Todo List）是我最推荐的第一周练手项目：需求清晰、交互闭环、能覆盖列表渲染、输入事件、数据变更、样式布局等核心知识点，又没有任何业务复杂度。

4.1 需求拆解：一个待办清单的极简功能集

这个Demo只需要四个功能：

• 在输入框里添加一条待办
• 点击待办项切换完成状态
• 删除某条待办（带一个简单的确认交互）
• 显示当前未完成的数量

不要想着做编辑、拖拽排序、分类分组，那些是第二三周的事。第一周的项目价值在于“把每行代码的作用讲清楚”。

页面结构拆成三块：上部是一个输入框和添加按钮，中部是待办列表，底部是一个统计信息。用微信小程序开发的话，最外层用一个container包住，列表用wx:for渲染，每一条item里放一个“完成状态”的小圆点和文字，右侧放删除按钮。

4.2 代码实现：JS、WXML、WXSS三个文件一次写完

先看JS逻辑。用data存两个东西：todos数组和inputValue字符串。数组里每一项是一个对象：

Page({ data: { todos: [], inputValue: '' }, onInput(event) { this.setData({ inputValue: event.detail.value }) }, addTodo() { const text = this.data.inputValue.trim() if (!text) return const todos = [...this.data.todos, { id: Date.now(), text: text, done: false }] this.setData({ todos, inputValue: '' }) }, toggleTodo(e) { const id = e.currentTarget.dataset.id const todos = this.data.todos.map(t => t.id === id ? { ...t, done: !t.done } : t ) this.setData({ todos }) }, deleteTodo(e) { const id = e.currentTarget.dataset.id const todos = this.data.todos.filter(t => t.id !== id) this.setData({ todos }) } })

这里有几个关键点要说清楚。onInput的作用是把输入框里的实时值同步到inputValue，这个值是受控的——你在WXML里的input的value绑定的是{{inputValue}}，你输入它变，你setData清空它也会变，这就是“受控组件”的概念。Date.now()生成id，是为了给每条待办一个唯一标识。数据绑定的><view class="container"> <view class="header"> <input class="input" placeholder="输入待办事项" value="{{inputValue}}" bindinput="onInput" /> <button class="add-btn" bindtap="addTodo">添加</button> </view> <view class="list"> <view class="todo-item" wx:for="{{todos}}" wx:key="id"> <view class="todo-text {{item.done ? 'done' : ''}}" bindtap="toggleTodo" >.container { display: flex; flex-direction: column; height: 100vh; padding: 24rpx; box-sizing: border-box; background: #f7f8fa; } .header { display: flex; gap: 16rpx; margin-bottom: 24rpx; } .input { flex: 1; background: #fff; border-radius: 12rpx; padding: 16rpx 24rpx; font-size: 30rpx; } .add-btn { width: 140rpx; background: #07c160; color: #fff; border-radius: 12rpx; font-size: 30rpx; line-height: 80rpx; height: 80rpx; } .todo-item { display: flex; justify-content: space-between; align-items: center; background: #fff; margin-bottom: 16rpx; padding: 20rpx 24rpx; border-radius: 12rpx; } .done { text-decoration: line-through; color: #999; }

这个样式里用到了flex的space-between来把左侧文字和右侧删除按钮分到两端，用text-decoration: line-through来做完成态的视觉反馈。这些写法都是实际项目中出现频率极高的模式，练完这个Demo，你基本已经具备独立写一个简单页面的能力了。

4.3 交互细节：按钮事件穿透与空状态

第一个版本跑通容易，但要在意细节。第一个需要打磨的细节是“空状态”：当todos列表为空时，页面应该显示“暂无待办事项，先添加一条吧”，而不是一个空白区域。这个体验差异，直接决定了你的Demo给人的专业感。

第二个细节是button在微信小程序里的默认样式带了很多自带效果——边框、阴影、默认背景色。如果你不想用原生按钮样式，可以用plain属性或者直接用view去模拟按钮。我的建议是：第一周先熟悉button原生样式，第二周再去考虑样式重置。

还有一个常见问题：删除按钮和切换状态按钮点击事件会互相穿透吗？实际上不会，因为这俩各自独立绑定了事件。但如果你把删除按钮包在一个绑定了toggle事件的view内部，点击删除时会同时触发外层事件，这就是事件冒泡。解决办法是给内层加catchtap替代bindtap，catch会阻止冒泡。这个知识点第一周就能遇到，值得记下来。

5. 调试、预览与发布：让小程序离开模拟器

项目做出来后，最后一个环节是验证和上线。很多新手沉迷于模拟器里的开发，等到要真机预览时才手忙脚乱。从week1开始就要养成“模拟器只是开发环境，手机才是真实环境”的意识。

5.1 模拟器与真机的差异：两个最容易翻车的地方

模拟器里的渲染结果是以开发机为基准的，字体、安全区、键盘弹出逻辑都和真机不完全一致。第一周你至少会遇到两个差异：

• 底部安全区。带刘海屏和Home指示条的真机，页面底部的内容会被白色横条遮挡。解决思路是给底部内容预留安全距�，微信提供的viewport-fit这样的适配方案，在页面json或全局json里配置"window"里的"navigationStyle"等。最稳妥的做法是在底部footer加padding-bottom: env(safe-area-inset-bottom)。
• 键盘。真机上点击input会弹出键盘，如果页面没有做“调整键盘弹出时内容上移”的处理，输入框很可能被键盘遮住。小程序有adjust-position属性控制，第一周知道它的存在即可，真机测试时再针对性处理。

真机预览的操作是：开发者工具点击“预览”按钮，会生成一个二维码，用微信扫码就能在手机上打开。扫码前确认你的微信号必须是这个小程序的“体验成员”，工具里会提示操作。个人主体的小程序，默认创建者就能预览。

5.2 常见报错与排查思路：引导你Debug而不是到处问

第一周密集写代码，报错是家常便饭。我的原则是：先读报错信息，再查代码，最后才上网搜。很多新手一报错就去复制报错全文到搜索引擎，其实控制台已经把答案端到眼前了。

下面列几个Week1常见报错的高发区：

排查逻辑其实就三步走：先看控制台报错定位到文件是哪一行，再检查那一行的变量名、事件名、路径是否正确，最后检查数据流——是不是setData没触发、或者触发时机不对。

5.3 上传体验版与审核：第一周要不要提交？

你可以不上传正式审核，但一定要试试“上传”这个动作。在工具右上角点击“上传”，填版本号和备注，它会把你的代码传到微信后台，生成一个开发版。然后你在后台“版本管理”里把开发版设为“体验版”，就能分享给朋友扫码体验。

整个过程是第一周最有成就感的时刻：代码不在你的电脑里，而在微信的云上，别人扫一扫就能用。至于提审（提交审核），第一周完全可以不做，因为审核需要类目说明、用户隐私保护指引这些材料，流程走一半容易打击积极性。

但如果你的目标是快速上线，建议至少了解一下流程：提交审核时需要选择服务类目，比如“工具-效率”，如果涉及用户信息收集，还需要配置用户隐私保护指引并说明采集信息的目的。现在平台对用户隐私管控比较严格，提交前一定要自查是否涉及收集用户信息。

注意：上传体验版之前，一定要在后台的“成员管理”里把测试者的微信加入体验成员列表，否则人家扫码打不开，只会看到“暂无权限”的提示。这个坑我至少见人踩过三次。

6. 常见问题与排查技巧实录：第一周避坑指南

最后这一块，我按真实进度把第一周最容易踩的坑整理成一个速查合集。这些坑不是从文档里抄来的，是实际走过一遍后印象最深的几个。

6.1 数据绑定与视图更新的“血泪教训”

第一个高频问题：为什么我的页面点击按钮后完全没有反应？排排看：bindtap有没有拼对？t函数有没有定义？函数里的this指向对不对？如果你在函数里用了普通的function而不是Page方法，this极有可能指向undefined。尤其当你用wx.request的回调去setData时，回调里的this已经不再是之前的this了。

解决办法有两类：函数前面用箭头函数捕获this，或者在外面缓存const that = this再用that.setData。第一周你会反复遇到这类问题，请从一开始就养成箭头函数的习惯：

wx.request({ url: 'https://example.com', success: (res) => { this.setData({ data: res.data }) } })

第二个高频问题：为什么我改了data里的数组，视图却没有更新？回想一下setData的机制。如果你直接this.data.todos.push(newItem)然后期望页面自己刷新，这是不可能的。你必须完整地setData。这也是为什么我在待办清单里用了展开运算符[...this.data.todos, {...}]而不是push——因为前者能立刻得到一个新数组，然后setData。

6.2 异步与缓存：新手最容易忽略的两件事

第三趴：生命周期和异步。小程序的onLoad、onShow是异步时机的，如果你在onLoad里请求数据，在onShow里也请求数据，有可能出现两次请求互相覆盖。第一周还没到做复杂状态管理的时候，但你要意识到这些都是有“时序”的，解决问题的第一反应是看触发顺序对不对。

第四趴：开发者工具的缓存。改代码后页面不更新，十有八九是编译缓存问题。处理办法不是疯狂重启模拟器，而是点“编译”按钮旁边的“清缓存”下拉菜单，清掉编译缓存和文件缓存，再重新编译。比重启工具有效得多。如果你改的是app.json里的页面配置、插件配置，有些改动确实需要重启工具才能生效。

6.3 代码规范与手感：从week1就开始养成的习惯

最后说几个我强烈建议从第一周就培养的编码手感：

• 组件命名用语义化驼峰，样式class用小写短横线。不要混着来，否则第二周连同一个人都看不懂自己的代码。
• 删除无用代码。第一周大家喜欢把注释掉的代码留着，结果页面文件越来越大。为什么不留？因为git是我们的时光机，删掉的代码永远找得回，注释堆砌只会干扰阅读。
• 每个页面调完一个功能，就用工具里的“预览”看一眼真机效果。节奏是“模拟器改了立刻看，真机每半天验一次”，只在模拟器调，真机一上全是问题，很容易心态崩掉。

我在实际带第一周新人的时候还发现一个规律：大多数人不是被某个具体语法卡死的，而是死在“遇到问题不知道用什么关键词去搜”。所以，下面这个“搜索关键词表”比代码本身更值钱：

第一周结束时，你应该能对自己的项目说清楚这样一句话：这个项目有哪些页面、页面间如何跳转、数据如何流动、哪里有权限限制、哪里会有性能隐患。如果都能答上来，那你的week1绝对比单纯看完一套视频课的人强得多。

最后再分享一个小技巧：每周开始前，把本周要学的知识点写在一张纸上，每完成一个就划掉一个。这个动作机械但有效，尤其是微信小程序开发这种知识点密、反馈又很强的领域，看着清单被一条条划掉，比任何教程都更能支撑你走下去。