1. 为什么我推荐用 HBuilderX 来写第一个微信小程序很多人第一次接触微信小程序开发第一反应是去下载微信官方开发者工具然后对着空白的项目目录发呆。这没错官方工具确实是小程序开发的标配但如果你同时还想兼顾 H5、App 甚至后续的多端发布单独维护一套微信小程序代码就有点亏了。我自己带过不少零基础的朋友入门实测下来用 HBuilderX 配合 uni-app 框架来写微信小程序对新手是最友好的路径之一。原因很简单uni-app 的语法就是 Vue.js 的语法你写一套代码编译出来可以直接跑在微信小程序、H5、App 上。而 HBuilderX 是 DCloud 官方为 uni-app 量身打造的 IDE下载即用不需要你折腾 Node.js 环境、不需要配 webpack、不需要懂命令行。对于零基础的人来说少一个环节就少踩一个坑。这篇文章我打算把整个流程拆透从 HBuilderX 下载安装、创建 uni-app 项目、理解 rpx 单位、写第一个页面、到最终发行到微信小程序每一步都给出我实际操作的细节和踩过的坑。适合完全没碰过小程序的人也适合写过一点 Vue 但没做过小程序的人。核心关键词就几个HBuilderX、微信小程序、uni-app、Vue.js、rpx我会围绕这几个点反复展开但不会堆砌。先说清楚一个概念免得后面混淆。HBuilderX 是编辑器uni-app 是框架微信小程序是最终运行的目标平台。三者的关系是你在 HBuilderX 里用 uni-app 的语法写代码编译后生成微信小程序的代码再用微信开发者工具打开预览或上传。理解这条链路后面所有操作你都不会迷路。2. 开发前的环境准备与工具选型2.1 HBuilderX 下载与版本选择HBuilderX 目前分两个版本标准版和App 开发版。如果你只做微信小程序和 H5标准版完全够用体积小、启动快。App 开发版多了真机运行、原生插件调试等能力体积大不少。我的建议是新手直接下标准版等真正要打包 App 了再换。下载地址就是 DCloud 官网搜索HBuilderX 下载就能找到。这里有个细节官网会同时提供 Windows 和 Mac 版本Windows 还分 32 位和 64 位。现在基本都是 64 位系统了选 64 位。下载下来是一个压缩包解压到任意目录就能用不需要安装。这一点对新手很友好不会往系统里塞一堆注册表。注意HBuilderX 是绿色软件解压路径里尽量不要有中文和空格比如放在D:\HBuilderX就比D:\我的软件\HBuilderX 编辑器要稳妥。我遇到过路径带中文导致编译缓存异常的情况虽然不常见但避开总没错。关于hbuilderx 历史版本这个搜索词我也说一句。有时候新版本会有一些兼容性问题比如某个插件不兼容、某个编译行为变了。如果你在网上看到别人用某个版本很稳想回退官网的下载页底部一般有历史版本入口。但新手不建议折腾版本直接用最新稳定版就行。2.2 微信开发者工具的安装与关联HBuilderX 负责写代码和编译但预览和上传微信小程序还是得靠微信开发者工具。所以你需要去微信官方文档下载微信开发者工具同样分 Windows 和 Mac 版。安装完之后关键一步是在 HBuilderX 里配置微信开发者工具的路径。路径在工具 → 设置 → 运行配置 → 微信开发者工具路径。把微信开发者工具的安装目录填进去。这一步不配置的话你在 HBuilderX 里点运行到微信小程序它会提示找不到工具。这里有个高频问题微信开发者工具无法通过 HBuilderX 打开。我踩过这个坑原因通常有三个一是路径填错了要填到可执行文件那一层不是文件夹二是微信开发者工具没有开启服务端口需要在微信开发者工具的设置 → 安全设置里把服务端口打开三是两个工具版本差太多。按这个顺序排查基本都能解决。2.3 微信小程序账号的注册要真正上传发布小程序你需要一个微信小程序账号。去微信公众平台注册选择小程序类型。注册过程中需要邮箱这里有个常见误解微信官方并没有指定注册小程序必须使用特定的邮件服务商用户可以使用任何品牌的邮箱QQ 邮箱、163 邮箱都行只要没被注册过。注册完成后你会在后台拿到一个AppID这个很重要后面创建项目时要填。如果你只是本地学习、不发布可以用测试号HBuilderX 创建项目时选测试号也能跑起来。但一旦要真机预览或者上传就必须用正式 AppID。3. 创建第一个 uni-app 项目并理解目录结构3.1 新建项目的正确姿势打开 HBuilderX点左上角文件 → 新建 → 项目。弹出的窗口里左侧选uni-app然后右侧填项目名称比如my-first-miniprogram。模板选择上新手直接选默认模板就行它自带一个 index 页面和基础配置够你跑通流程。Vue 版本这里要注意uni-app 支持 Vue2 和 Vue3。目前新建项目默认可能是 Vue3但网上大量教程和hbuilderx vue2 实战项目还是 Vue2 的写法。如果你跟着老教程学建议在创建时选 Vue2避免语法对不上。Vue3 的组合式 API 和 Vue2 的选项式 API 写法差异不小新手混着看容易懵。创建完成后你会看到这样的目录结构my-first-miniprogram/ ├── pages/ │ └── index/ │ └── index.vue ├── static/ ├── unpackage/ ├── App.vue ├── main.js ├── manifest.json ├── pages.json └── uni.scss我逐个说清楚它们是干嘛的。pages目录放所有页面每个页面一个文件夹里面是.vue文件。static放静态资源图片、字体都丢这里。unpackage是编译输出目录你编译成微信小程序后生成的代码在这里不用手动改。App.vue是应用入口全局样式和生命周期写这里。main.js是 Vue 实例的入口。manifest.json是小程序配置AppID、名称、图标都在这。pages.json是页面路由和导航栏配置非常重要。uni.scss是全局样式变量。3.2 pages.json 与 manifest.json 的关键配置pages.json相当于微信小程序的app.json但 uni-app 帮你做了封装。里面最核心的是pages数组第一个元素就是启动页。每个页面可以配navigationBarTitleText导航栏标题、navigationBarBackgroundColor导航栏背景色等。这里插一个热搜词里提到的点微信小程序顶部导航栏高度。在 uni-app 里如果你用默认导航栏高度是系统控制的你改不了具体像素。但如果你把navigationStyle设成custom就可以自定义导航栏这时候就要自己算高度了。顶部导航栏高度 状态栏高度 44pxiOS或 48pxAndroid。状态栏高度可以用uni.getSystemInfoSync().statusBarHeight拿到。这个后面做自定义导航栏时会用到。manifest.json里找到微信小程序配置把 AppID 填进去。如果你暂时没有可以留空用测试号运行。另外基础库版本从哪设置也是常见问题这个不在 HBuilderX 里设而是在微信开发者工具的详情 → 本地设置 → 调试基础库里选。HBuilderX 编译出来的代码最终基础库版本由微信开发者工具决定。3.3 运行到微信小程序的完整流程配置好路径和 AppID 后点 HBuilderX 顶部菜单运行 → 运行到小程序模拟器 → 微信开发者工具。第一次运行会稍慢因为要编译。编译完成后微信开发者工具会自动打开你就能看到页面了。如果没自动打开检查前面说的服务端口和路径配置。还有一个坑HBuilderX 启动时可能会占用某个端口如果你同时开了多个项目或者端口被别的软件占了会报hbuilderx 启动修改端口相关的错误。这种情况在设置里改一下内置服务器端口就行或者重启 HBuilderX。4. 用 Vue.js 语法写页面与 rpx 布局实战4.1 从 index.vue 看懂一个页面的组成打开pages/index/index.vue你会看到三段结构template、script、style。这就是 Vue 单文件组件的标准写法也是 uni-app 页面的基本形态。template里写 HTML 结构但注意小程序不支持所有 HTML 标签比如div要换成viewspan换成textimg换成image。这是新手最容易犯的错直接复制网页代码过来编译就报错。script里写逻辑Vue2 是export default { data() { return {} }, methods: {} }这种选项式写法。data里定义的数据在模板里用{{ }}绑定。methods里写函数用click绑定到元素上。style里写样式默认支持 scss需要装 sass 插件。HBuilderX 会提示你安装点一下就行。4.2 rpx 单位小程序适配的核心这是重点。微信小程序的屏幕宽度是 750rpx不管你是 iPhone 还是安卓屏幕多宽都是 750rpx。也就是说1rpx 在不同设备上对应的物理像素是不一样的但比例始终一致。你写width: 750rpx在任何手机上都是满屏宽。为什么用 rpx 而不是 px因为 px 是固定像素在 iPhone 6 上看着刚好到 iPhone 14 Pro Max 上就偏小到小屏安卓上就偏大。rpx 是响应式的自动按屏幕宽度缩放。设计稿一般按 750px 宽出你量出来多少 px直接写多少 rpx 就行一比一不用换算。举个例子设计稿上一个按钮宽 200px你就写width: 200rpx。一个卡片左右各留 30px 边距就写padding: 0 30rpx。字体大小也是正文一般 28rpx 到 32rpx标题 36rpx 到 40rpx。提示rpx 虽好但不是所有地方都适合。比如 1px 的边框如果你写 1rpx在某些设备上会渲染不出来或者粗细不均。这种场景建议用 px或者用transform: scaleY(0.5)做 0.5px 边框。这是实战经验文档里不一定写。4.3 写一个带交互的示例页面光看结构没意思我带你写一个实际能用的页面一个简单的待办列表。有输入框、添加按钮、列表展示、点击删除。模板部分template view classcontainer view classinput-row input v-modelinputValue placeholder输入待办事项 classinput / button clickaddTodo classbtn添加/button /view view classlist view v-for(item, index) in todos :keyindex classitem clickremoveTodo(index) text{{ item }}/text /view /view view v-iftodos.length 0 classempty暂无待办/view /view /template逻辑部分export default { data() { return { inputValue: , todos: [] } }, methods: { addTodo() { if (!this.inputValue.trim()) return this.todos.push(this.inputValue.trim()) this.inputValue }, removeTodo(index) { this.todos.splice(index, 1) } } }样式部分.container { padding: 30rpx; } .input-row { display: flex; align-items: center; margin-bottom: 30rpx; } .input { flex: 1; height: 80rpx; border: 1px solid #ddd; border-radius: 8rpx; padding: 0 20rpx; font-size: 28rpx; } .btn { width: 160rpx; height: 80rpx; margin-left: 20rpx; font-size: 28rpx; background-color: #007aff; color: #fff; } .item { padding: 30rpx; border-bottom: 1px solid #eee; font-size: 30rpx; } .empty { text-align: center; color: #999; font-size: 28rpx; margin-top: 60rpx; }这个例子涵盖了数据绑定、事件、列表渲染、条件渲染、rpx 布局基本就是小程序开发的核心操作。你把这个跑通后面做复杂页面就是堆这些技能。4.4 Vue.js 脚本下载与依赖管理热搜词里有vue.js 脚本下载我理解是有人想手动引入 Vue.js。在 uni-app 项目里你不需要手动下载 Vue.js框架已经内置了。你写的就是 Vue 语法编译时框架会处理。如果你在普通网页项目里用 Vue那才需要去官网下载 vue.js 或者用 CDN 引入。别把两件事搞混。5. 发行到微信小程序的详细步骤与常见问题5.1 从运行到发行的区别运行是开发模式代码不压缩方便调试生成的代码在unpackage/dist/dev目录。发行是生产模式代码会压缩混淆体积更小生成在unpackage/dist/build目录。真正上传到微信后台的必须是发行版本。操作路径HBuilderX 菜单发行 → 小程序-微信。第一次点会要求你填微信开发者工具的路径如果之前没配然后它会自动编译并打开微信开发者工具加载的是 build 目录的代码。5.2 上传代码与提交审核在微信开发者工具里点右上角上传按钮填版本号和项目备注确认上传。上传成功后去微信公众平台后台在版本管理里能看到刚上传的版本点提交审核。审核通过后点发布小程序就正式上线了。这里有个细节上传前要确保manifest.json里的 AppID 是正式的不是测试号。测试号上传会失败。另外小程序的类目、隐私协议这些也要在后台配好否则审核会被打回。5.3 常见报错与排查速查表我把实际开发中高频遇到的问题整理成表方便你对照排查。问题现象可能原因解决方法运行到微信小程序无反应微信开发者工具路径未配或服务端口未开检查设置里的路径开启微信开发者工具的安全设置服务端口编译报错 component does not have a method事件绑定的方法名写错或未在 methods 中定义检查click绑定的方法名与 methods 中的一致页面白屏启动页路径配置错误或页面文件缺失检查 pages.json 中 pages 数组第一项路径是否正确rpx 布局错乱混用了 px 和 rpx或父容器宽度未撑满统一用 rpx检查父容器是否有固定宽度限制真机预览样式与模拟器不一致基础库版本差异或机型适配问题在微信开发者工具切换基础库版本用 rpx 替代 px上传失败提示 AppID 无效使用了测试号或 AppID 填错换成正式 AppID检查 manifest.json 配置图片不显示路径用了绝对路径或图片未放 static 目录图片放 static用相对路径引用5.4 几个容易忽略的实操心得第一个心得善用条件编译。uni-app 支持条件编译比如你只想在微信小程序里执行某段代码可以写#ifdef MP-WEIXIN。这在处理平台差异时非常有用比如微信小程序的登录逻辑和 H5 不一样就可以用条件编译隔开。第二个心得pages.json 的 tabBar 配置。如果你要做底部导航在 pages.json 里配 tabBar注意图标路径要放 static 目录且大小建议 81x81px。图标不显示通常是路径错了或者尺寸不对。第三个心得调试时多看控制台。HBuilderX 的控制台和微信开发者工具的控制台都要看。HBuilderX 报的是编译错误微信开发者工具报的是运行错误。两个都干净代码才算真的没问题。第四个心得关于 uni-app 打包 iOS 收费吗这个问题如果你只是打包成微信小程序不涉及 iOS App那完全不收费。只有当你用 uni-app 打包成原生 iOS App 并上架 App Store 时才涉及苹果开发者账号的年费那是苹果收的不是 uni-app 收的。别被搜索结果的标题吓到。6. 从入门到进阶下一步可以做什么跑通上面这套流程你就算正式入门了。接下来可以往几个方向深入。一是把 Vue.js 学扎实组件通信、生命周期、计算属性这些吃透写复杂页面会轻松很多。二是研究微信小程序的 API比如登录、支付、订阅消息这些是实际项目绕不开的。三是了解 uni-app 的多端能力同一套代码编译到 H5 和 App这是它最大的价值。热搜词里还有基于微信小程序的校园跑腿服务平台的设计与实现这类项目实例其实拆开看无非就是用户端下单、骑手端接单、后台管理技术栈还是这些。你把基础打牢做这类项目就是业务逻辑的堆叠技术上没有新东西。我个人在实际操作中的体会是新手最容易卡住的地方不是代码本身而是环境配置和工具联动。HBuilderX 和微信开发者工具之间的路径、端口、AppID 这三样配好后面就顺了。我见过太多人卡在运行没反应这一步就放弃了其实排查下来就是服务端口没开。所以遇到问题别慌按表格里的顺序一个个查基本都能解决。最后分享一个小技巧新建项目后先把pages.json里的导航栏标题改成你自己的项目名再运行一次确认整个链路通了再开始写业务代码。这样能把环境问题和代码问题分开排查起来效率高很多。这个习惯我保持了几年每次开新项目都这么做省了不少来回折腾的时间。