微信小程序开发全攻略·文章版｜01 入门与环境搭建

微信小程序入门：从注册账号到跑通第一个页面，一篇讲清环境搭建

📊 交互式知识图谱在线版：https://mcnj5s80gkfh.doubaoapps.com/app/app_17fuyxrd8p2

摘要 ：这是《2026 最全微信小程序开发全攻略》的第一篇笔记，对应课程第 1-4 集（约 36 分钟）。文章讲清楚三件事：微信小程序到底是什么、它和网页 / 原生 App 有什么区别；如何在微信公众平台注册一个小程序账号并拿到开发必需的 AppID；以及如何安装微信开发者工具、看懂标准目录结构与 .wxml / .wxss / .js / .json 四类文件的分工，最后手写一个可交互的 Hello World 页面。学完本文，你应当能独立在本机搭好开发环境、新建并运行一个自己的小程序项目。本文适合：有一点 HTML/CSS/JavaScript 基础、想转行或兼职接小程序外包的前端新人，以及想快速做一个自家店铺 / 工具类小程序的创业者。建议边读边在开发者工具里跟着敲，每完成一个小节就亲手运行一次，效果最好；遇到任何报错，先看 Console 里的行号再回去定位，不要急着怀疑自己。

目录

• [1. 微信小程序是什么：定位、优势与前景](#1. 微信小程序是什么：定位、优势与前景)

• [2. 注册小程序账号：从公众平台到拿到 AppID](#2. 注册小程序账号：从公众平台到拿到 AppID)

• [3. 安装并认识微信开发者工具](#3. 安装并认识微信开发者工具)

• [4. 看懂小程序目录结构与四类文件](#4. 看懂小程序目录结构与四类文件)

• [5. 跑通你的第一个页面（Hello World）](#5. 跑通你的第一个页面（Hello World）)

• [6. 常见报错与易错点](#6. 常见报错与易错点)

• [7. 本模块视频清单](#7. 本模块视频清单)

• [8. 常用配置与 API 速查表](#8. 常用配置与 API 速查表)

• [9. 学习打卡清单](#9. 学习打卡清单)

• [10. 知识图谱](#10. 知识图谱)

相关延伸阅读

• 李沐《动手学深度学习》191集课程全解析：模块拆解与学习路径

• 吴恩达《面向开发者的提示词工程》精读

• 吴恩达《Model Context Protocol (MCP) 教程》精读（一）

• 多模态大模型教程笔记：ViT·CLIP·SAM·Stable Diffusion

1. 微信小程序是什么：定位、优势与前景

微信小程序是一种内嵌在微信里、无需下载安装即可使用的轻量级应用，官方把它的产品理念概括为"用完即走"。用户不需要像装普通 App 那样去应用商店下载、等待安装、占用桌面空间，而是通过扫码、搜索、微信分享、聊天小程序卡片、下拉聊天框、"附近的小程序"等入口直接打开；用完退出即可，不会像原生 App 那样常驻后台、频繁推送，显著节省手机内存与电量。

对开发者来说，小程序最吸引人的一点是：它的技术栈和传统网页前端高度相似。布局写 WXML（你可以粗略理解为小程序版的 HTML）、样式写 WXSS（小程序版的 CSS）、业务逻辑写 JavaScript，再加上一个 JSON 配置层。因此，一名已经会写网页的前端工程师，迁移到小程序开发的学习曲线非常平缓，大量 CSS 选择器、盒模型、flex 布局的经验可以直接复用。与此同时，小程序并不只是"跑在微信里的网页"：它提供了一整套原生组件 （视图容器、表单、音视频、地图、相机、画布等）和一组 wx.* 开头的微信能力 API（登录、获取位置、扫码、支付、分享、缓存、网络请求），让你的 H5 页面能够调用接近原生 App 的系统能力。

很多人会问：我已经会做 H5 网页了，为什么还要学小程序？这三者的定位差异可以概括如下：

形态	运行环境	安装	能力	典型场景
网页 H5	手机浏览器	无需	受浏览器沙箱限制	活动页、传播落地页
微信小程序	微信宿主内	无需，即开即用	可调用微信原生能力（登录/支付/分享/音视频）	店铺、政务、工具、服务
原生 App	iOS / Android 系统	需下载安装	能力最全、性能最好	重交互、长留存产品

那为什么要专门学它？可以从三个角度看：

• 流量角度：微信是国内用户使用时长最高的超级 App，小程序天然寄生在聊天、群、公众号、朋友圈分享链路里，获客成本远低于让用户去应用商店下载一个 App。一个小店、一个预约工具、一个查询类服务，做成小程序往往是性价比最高的选择。

• 开发角度：官方提供了免费、功能完善的微信开发者工具，组件和 API 高度标准化，加上这套课程把"从注册到发布"的完整链路打通，零基础一天就能跟下来做出一个能跑的 demo。

• 职业角度：小程序开发是前端招聘中的常见技能点，掌握它既可以接外包项目，也能在企业里承接微信生态相关业务，对简历是实实在在的加分项。

📝 补充说明：小程序自 2017 年上线以来随微信生态快速迭代，能力从最初的基础视图、表单扩展到音视频、广告、云开发、小程序插件等。学习时不必死记历史版本差异，以微信官方最新文档为准即可。

学习这门课，心态上有两点建议。其一，不要被"一天学会"的宣传带着走而跳过动手环节 。这门课节奏快、信息密度高，适合先整体过一遍建立地图，再回到自己的项目里逐节敲一遍代码；只看不敲，三天后基本会忘光。其二，遇到报错是常态，不是你学不会。小程序的报错信息大多会在调试器 Console 里给出文件名、行号和原因，学会顺着行号回去看代码，是比背 API 更重要的基本功。把环境搭通、把第一个按钮点出反应，就是你这一阶段最大的里程碑------后面所有复杂页面，本质上都是在这个"数据驱动视图"的最小闭环上不断叠加组件和逻辑。

2. 注册小程序账号：从公众平台到拿到 AppID

在写第一行代码之前，你需要一个属于自己的小程序账号。整个过程是在微信公众平台完成的，和注册一个网站账号差不多，关键在于选对账号类型、拿到 AppID。📝

第一步，浏览器打开 mp.weixin.qq.com，点击首页的"立即注册"。这里会列出多种账号类型：订阅号、服务号、小程序、企业微信等。一定要选择"小程序"------选错成公众号，后面是无法调用小程序能力的。

第二步，填写一个从来没有注册过公众平台、也没有绑定过个人微信的邮箱。这个邮箱会作为登录账号，注册后登录邮箱、收激活邮件、点击激活链接。

注册时如果系统提示"该邮箱已被占用"，说明这个邮箱以前注册过别的公众平台账号，换一个全新邮箱即可；如果你既想学习又不想用主邮箱，完全可以专门注册一个邮箱来管理小程序，避免和日常账号混在一起。整个注册流程通常几分钟就能走完，真正需要耐心的是后面填写名称、简介和服务类目这一步------名称一年能改的次数有限，简介和类目会影响小程序被搜索到的效果，建议认真想清楚再提交。

第三步，选择主体类型。个人开发者选"个人"即可，凭身份证号 + 本人微信扫码就能完成主体验证，完全免费，非常适合学习阶段；如果未来要开通微信支付、认证名称、更高级的接口，再去注册企业/组织类主体。需要注意，个人主体有能力限制，例如不能开通微信支付，这点在做商业项目前要先查官方文档确认。

第四步，填写管理员姓名、身份证号，用管理员本人的微信扫码完成人脸/身份验证。注册成功后，进入小程序管理后台，填写小程序名称、图标、简介和服务类目。

整个流程里最重要的产出物是 AppID（小程序 ID） 。它在后台的"开发 → 开发管理 → 开发设置"里可以找到，形如 wx1234abcd5678ef90。AppID 是你这个小程序的唯一身份标识，创建项目时要填、调用微信能力时要识别它、上线发布也要靠它。

这里把个人主体和企业主体的常见差异列一张表，做项目前先对号入座，免得做到一半发现能力被卡：

能力 / 主体	个人主体	企业 / 组织主体
注册成本	免费，身份证 + 本人微信即可	需营业执照，部分需认证费
微信支付	一般不支持	可开通
小程序名称	受限重名保护	命名空间更完整
接口权限	满足学习与展示类需求	可申请更多高级接口
适合人群	学生、个人练习、作品集	商业项目、接单、正式产品

这里有两个新手最容易踩的坑：

• AppID 和 AppSecret 不是一回事。 AppID 是公开标识，可以写在前端代码里；AppSecret 是服务端调用接口的密钥，只能保存在你自己的服务器上，绝对不能写进小程序前端，否则会被他人盗用、伪造身份。

• 学习阶段没有 AppID 也能先体验。 新建项目时可以选择"测试号"或使用"不使用云服务"，工具会临时分配一个测试 AppID，用来学习组件和 API 完全够用；但一旦要真机预览、发布上线，就必须换成你自己注册的真实 AppID。

3. 安装并认识微信开发者工具

📝 微信开发者工具是官方提供的免费 IDE，把代码编辑、真机模拟器、调试器、真机预览、上传发布集成在一个软件里，不用自己搭环境。安装步骤如下：

1. 到官方下载页 developers.weixin.qq.com/miniprogram/dev/devtools/download.html，选择稳定版（Stable Build），按你的系统下载 Windows 64 位或 Mac 版本。建议用稳定版而不是体验版，避免遇到未修复的 bug。

2. 安装后启动，用小程序管理员或已被添加为开发者的微信扫码登录。

3. 点击"+ 新建项目"，选择一个空的本地目录，填入你的 AppID（学习时可选测试号），后端服务选择"不使用云服务"，模板选择"JavaScript - 基础模板"，确定后工具会自动生成一套可直接运行的示例代码。

打开工具后，界面主要分成三块，先混个脸熟，后面天天都要用：

刚新建出来的项目并不是空文件夹，官方模板已经替你写好了一套可运行的示例：pages/index 里有一个默认首页，app.json 里登记了页面并设好了导航栏标题，app.js 里有一个最朴素的 App() 注册。你可以先把示例跑起来看看效果，再一步步把它改成自己的东西------这种"先有一个能跑的最小骨架，再往里填血肉"的方式，比从完全空白开始要踏实得多。如果模板里带了你暂时用不上的文件（比如示例的日志打印、占位图片），可以大胆删掉，删之前知道它是干嘛的即可。

区域	作用
模拟器	在电脑上模拟不同手机机型、网络环境下的运行效果，改代码实时刷新
编辑器	左侧目录树 + 右侧代码编辑，带语法高亮、自动补全和格式化
调试器	类似 Chrome DevTools，含 Console（日志）、Network（请求）、Storage（缓存）、AppData（页面数据）、Wxml（结构）面板

顶部还有几个高频按钮：

• 编译：重新构建并刷新模拟器。改了代码没生效，先点它；它还支持"自定义编译条件"，可以指定从某个页面启动、并带上启动参数，调试深页面时非常有用。

• 预览 / 真机调试：生成一个二维码，用你的手机微信扫码，就能在真实手机上看到效果，还能在电脑上远程调试真机的日志。

• 上传：把当前代码打包上传成一个"开发版本"，之后到网页管理后台把它提交审核，审核通过即可发布给用户。

• 清缓存：一键清除数据缓存、文件缓存、授权、网络缓存。这是解决"我明明改了代码但页面纹丝不动"的第一法宝。

调试时有个经验法则：看数据用 AppData 面板，看网络用 Network 面板，打日志用 console.log ，看结构和样式用 Wxml 面板。 这套思路和前端浏览器调试几乎一模一样，前端同学上手毫无障碍。

再补充几个调试上的实用技巧：在 AppData 面板里你可以直接双击某个字段临时改成别的值，界面立刻跟着变，用来快速验证"如果数据是这样，页面会怎样"特别高效；Network 面板里每条请求都能看到请求头、请求体和返回结果，调接口时先在这里确认数据到底有没有回来、长什么样，再去业务代码里找问题。真机调试时，开发者工具会把手机上的 console 日志同步到电脑，等于你在电脑上给手机里的页面打断点、看变量，和调试本地页面体验一致。遇到"电脑模拟器好好的，一到手机就不对"这类问题，多半是尺寸单位、触控事件或网络环境差异，切到真机调试看一眼日志，问题基本无处藏身。

4. 看懂小程序目录结构与四类文件

📝 新建项目后，别着急写代码，先花十分钟把目录结构看明白。一个标准小程序长这样：

my-miniprogram/
├── pages/                # 页面目录，每个页面一个独立文件夹
│   └── index/
│       ├── index.wxml    # 页面结构（类比 HTML）
│       ├── index.wxss    # 页面样式（类比 CSS，仅本页生效）
│       ├── index.js      # 页面逻辑：数据、生命周期、事件函数
│       └── index.json    # 页面配置（可选）
├── app.js                # 小程序逻辑入口：注册 App、全局生命周期
├── app.json              # 全局配置：页面路由、窗口样式、tabBar
├── app.wxss              # 全局样式，对所有页面生效
├── project.config.json   # 开发者工具的项目配置（AppID、编译选项等）
└── sitemap.json          # 配置页面是否允许被微信搜索收录

小程序约定每个页面是一个文件夹，文件夹里固定有四个同名、不同后缀的文件。这四类文件的分工要刻在脑子里：

文件类型	类比网页	职责
.wxml	HTML	描述页面长什么样，使用 view、text、button 等小程序组件，支持数据绑定和事件绑定
.wxss	CSS	描述样式。除了普通 CSS，还新增了 rpx 响应式尺寸单位
.js	JavaScript	逻辑层。app.js 里调用 App() 注册小程序；页面 js 里调用 Page() 定义数据和行为
.json	配置文件	app.json 管全局，页面 .json 管单页。必须是标准 JSON，不能写注释

这里有两个概念第一次接触会觉得新鲜：

• rpx（responsive pixel） ：这是小程序独有的响应式单位。规则是 750rpx = 屏幕宽度。也就是说，无论在 375px 还是 414px 宽的手机上，你写 375rpx 就永远占屏幕一半宽度。设计稿如果是按 750 宽度出的，直接把标注里的 px 换成 rpx 即可，省去了自己算缩放。

• 全局与局部的分层 ：app.wxss 里写的样式对每个页面都生效；而页面自己的 .wxss 只作用于本页。app.json 是全局总配置，页面 .json 里的同名配置会覆盖全局。理解这套"全局默认、页面覆盖"的规则，后面配导航栏、tabBar 时就不会乱。

关于 rpx 再举一个具体例子帮你建立直觉：设计稿常见宽度是 750px，设计师标注"卡片左右各留 20px 边距、标题字号 32px"。因为 750rpx 正好等于屏幕整宽，标注里的 px 数值可以原样换成 rpx ------边距写 20rpx、字号写 32rpx。这样在 375px 宽的手机上，32rpx 实际渲染约 16px；在 414px 宽的手机上约 17.6px，卡片始终左右贴边距、占满比例一致，你完全不用为不同屏幕写两套样式。反过来，如果你用固定 px，小屏手机上元素可能偏大、大屏上偏小，这就是 rpx 存在的意义。小程序的盒模型、flex 布局和 CSS 几乎一致：display:flex、justify-content、align-items、flex-direction 都能正常用，本套课程后续做列表、导航、居中排版都靠它。

小程序的盒模型、flex 布局和 CSS 几乎一致：display:flex、justify-content、align-items、flex-direction 都能正常用，本套课程后续做列表、导航、居中排版都靠它。

光说不练假把式。下面动手写一个最简单但可交互的页面：页面上显示一句话和一个按钮，点按钮，文字就变。

先看结构文件 pages/index/index.wxml：

<view class="container">
  <text>{{message}}</text>
  <button type="primary" bindtap="onTap">点我试试</button>
</view>

这里有两个关键点：{``{message}} 是数据绑定 ，它会从页面的 data 里取名叫 message 的值显示出来；bindtap="onTap" 表示给这个按钮绑定了一个点击事件，点击时会执行页面 js 里名为 onTap 的函数。

再写逻辑文件 pages/index/index.js：

Page({
  data: {
    message: '你好，小程序！'
  },
  onTap() {
    this.setData({ message: '你点了按钮，数据更新成功' })
  }
})

样式 pages/index/index.wxss：

.container {
  padding: 40rpx;
  display: flex;
  flex-direction: column;
  align-items: center;
}

text {
  font-size: 36rpx;
  margin-bottom: 30rpx;
}

最后，确保 app.json 的 pages 数组里注册了这个页面：

{
  "pages": [
    "pages/index/index"
  ],
  "window": {
    "navigationBarTitleText": "我的第一个小程序"
  }
}

保存后点"编译"，模拟器里就能看到文字；点一下按钮，文字变化------这就完成了小程序最核心的"数据驱动视图 "闭环：用户操作 → 触发事件函数 → 调用 setData 修改数据 → 框架自动重新渲染界面。

这几行代码背后藏着三个后面会反复用到的约定，值得在这里就讲透：第一，data 里的每个字段都可以在 WXML 里用 {``{}} 双花括号引用，它既是展示内容，也可以塞进属性里，比如 {``{message}}、class="box-{``{type}}"；第二，事件函数里 this 指向当前页面实例，所以改数据必须写 this.setData(...)，而不是忘了 this；第三，setData 接收一个对象，只更新你列出的字段，没列出的字段保持不变，它是异步执行的，真正的渲染完成时机可以在第二个参数的回调里拿到。把这三点刻进脑子，后面写任何页面都不会再犯"改了数据页面不动"的错误。

6. 常见报错与易错点

作为入门篇，把新手最容易卡住的几个坑集中说清楚：

1. 直接给 this.data.message 赋值，页面却不更新。 这是初学者第一大错。小程序不监听数据变化，必须调用 this.setData({ message: '新值' }) 才会触发界面刷新。记住口诀：改数据，用 setData。

2. app.json 报错"Unexpected token"。 JSON 文件不能写注释（//）、不能有多余的尾逗号。如果你在配置里加了 // 这是注释，整个项目都会编译失败。

3. 新建了页面却白屏。 每个新页面都必须在 app.json 的 pages 数组里登记路径，否则小程序根本不知道这个页面存在。pages 数组的第一项，默认就是小程序启动后打开的首页。

4. 改了代码没反应。 先确认点了"编译"；还不行就"清缓存 → 全部清除"后重新编译。前端开发里改文件没生效，十有八九是缓存。

5. 真机预览白屏/请求失败。 开发阶段请在开发者工具详情里勾选"不校验合法域名"，否则 wx.request 请求你自己的测试服务器会被微信拦截------这是因为正式环境只允许请求在后台配置过的合法域名。

再补充两个高频疑问。一个是"为什么我写的 <image> 图片不显示"：多半是 src 路径写错，或者用了本地图片但没放进项目目录；网络图片则要确认域名合法、链接确实可访问。另一个是"样式为什么不生效"：先检查类名有没有拼错、.wxss 文件名和页面是不是同名同目录，再确认是不是被更高优先级的选择器覆盖了；小程序的样式优先级规则和 CSS 一致，写得越具体优先级越高，调试不生效时用开发者工具的 Wxml 面板选中节点，右边就能看到实际命中了哪些样式、哪些被划掉。把这几条养成习惯，入门阶段九成以上的"玄学 bug"都能在五分钟内定位。

7. 本模块视频清单

本模块共 4 集，总时长约 36 分钟，全部为 B 站合集 BV18VTW6TEwE 的分 P：

集	章节标题	时长	链接
01	微信小程序简介	8:50	观看 p1
02	微信小程序账号申请 📝	5:23	观看 p2
03	微信小程序开发者工具 📝	14:15	观看 p3
04	小程序目录结构 📝	8:02	观看 p4

注：除第 1 集依据课程本地 AI 总结整理外，其余各集依据集标题与微信官方标准流程补全（标 📝），实际界面请以你安装的稳定版开发者工具和官方文档为准。跟着这 4 集把环境跑通后，就可以进入模块二，正式学习用 app.json 配置页面路由、窗口和底部 tabBar 了。

8. 常用配置与 API 速查表

名称	作用	关键参数 / 备注
AppID	小程序唯一身份标识	在管理后台"开发设置"获取，创建项目必填
AppSecret	服务端接口密钥	仅存服务器，严禁写入前端代码
app.json → pages	注册全部页面路径	数组第一项为启动首页
app.json → window	全局窗口表现	导航栏标题、颜色、背景色等
Page()	注册一个页面	入参对象含 data、生命周期、事件函数
this.setData()	更新数据并刷新视图	传入要更新的对象，只改列出的字段
rpx	响应式尺寸单位	750rpx 等于屏幕宽度

9. 学习打卡清单

• 完成第 1 集：微信小程序简介

• 完成第 2 集：微信小程序账号申请

• 完成第 3 集：微信小程序开发者工具

• 完成第 4 集：小程序目录结构

• 已注册小程序账号（或准备好测试号）并拿到 AppID

• 已安装稳定版微信开发者工具并成功新建项目

• 能说清 .wxml / .wxss / .js / .json 四类文件的分工

• 已用 setData 跑通一个可交互的 Hello World

10. 知识图谱

本模块的学习路径可以归纳为一条"从认识到跑通"的链路：

• 认识阶段：小程序定位（即用即走、依托微信生态） → 对比 H5 / 原生 App → 明确学习价值

• 准备阶段：公众平台注册 → 选"小程序"类型 → 主体验证 → 拿到 AppID（与 AppSecret 区分）

• 工具阶段：下载稳定版开发者工具 → 扫码登录 → 新建项目 → 认识模拟器 / 编辑器 / 调试器三大区域

• 结构阶段 ：理解 pages/ 目录 → 掌握四类文件分工 → 理解 rpx 与全局/局部分层

• 实战阶段：写 wxml 结构 → 写 js 数据与事件 → setData 驱动视图 → 编译看到效果

四类文件的协作关系如下：

在继续往下学之前，建议你把这个目录结构和四类文件的分工在白纸上默写一遍：新建一个页面时要建哪个文件夹、四个后缀各写什么、新页面要去哪里注册。这是后面每写一个页面都会重复的动作，现在形成肌肉记忆，后面才不会每次都翻文档。同时把"改数据必须 setData"这一条单独记在便签上，它会在你整个小程序开发生涯里反复救你一次又一次。

文件	输入 → 输出	在链路中的角色
.wxml	绑定 {``{data}}、绑定 bindtap	负责"展示什么、用户点哪"
.js	data 提供初始数据，事件里 setData	负责"数据是什么、点击后做什么"
.wxss	选择器 + rpx 样式	负责"长什么样"
.json	pages 注册、window 标题	负责"全局怎么配"

📊 交互式知识图谱在线版：https://mcnj5s80gkfh.doubaoapps.com/app/app_17fuyxrd8p2