保姆级：uniapp与HBuilderX开发步骤

"轻松掌握UniApp开发全流程！本文涵盖小程序从零到发布的完整步骤：环境准备（Node.js HBuilderX）、项目创建、目录结构解析（components/uni_modules规范）、页面与组件开发技巧重点解决路径问题（绝对/相对路径配置）、样式失效、跨域和图片引用等高频痛点，附调试技巧（微信开发者工具联调）和发布须知（合法域名配置）。核心API调用、拦截器使用指南一应俱全，助你快速上线！"

小程序开发步骤

• 环境准备
  • 1.开发工具
    • HbuilderX
      • uniApp官方推荐的IDE
      • 下载地址：https://www.dcloud.io/hbuilderx.html
    • 微信开发者工具
      • 调试和预览小程序必需工具
      • 下载地址：https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html
  • 2.node.js环境
    • UniApp需要Node.js环境
      • 下载地址：https://nodejs.org/
      • 安装后验证是否成功
• 创建UniApp项目以及配置
  • 1. 使用HbuilderX创建项目
    • 1. 打开HbuilderX
    • 2. 点击菜单栏 文件 -> 新建 -> 项目
    • 3. 选择uni-app项目类型
      • • 填写名称
        • 选择存放地址
        • 选择uni ui项目模板，日常开发推荐使用该模板，已内置大量常用组件
        • 选择vue版本
        • 其他选项按需选择
    • 4. 点击创建
  • 2. 项目目录结构解析
    • ├── pages // 页面目录 │ ├── index // 首页 │ └── index.vue // 首页vue文件 │ ├── static // 静态资源目录 ├── uni_modules // uni-app的ui组件文件夹 ├── App.vue // 应用入口文件 ├── main.js // 应用入口js文件 ├── manifest.json // 应用配置文件 ├── pages.json // 页面路由和导航栏配置 └── uni.scss // uni-app内置的scss变量
  • 3. 核心文件详解
    • main.js
      • 应用入口文件
        • 初始化vue实力并挂载应用
        • App.mpType = 'app' 标识这是一个小程序应用
      • 文档地址：https://uniapp.dcloud.net.cn/collocation/main.html
    • APP.vue
      • 应用主文件 应用的根组件
        • 包含应用生命周期函数
          • onLaunch：初始化完成时触发
          • onShow：启动或从后台进入前台时触发
          • onHide：从前台进入后台时触发
        • 可以在这里定义全局样式
      • 文档地址：https://uniapp.dcloud.net.cn/collocation/App.html
    • page.json
      • 页面路由基础配置
        • 管理所有页面路由和窗口表现
        • pages：数组配置所有页面路径
        • globalStyle：配置全局窗口样式
      • 可以在page.json中需要自行添加的配置
        • subPackages（分包）
          • 描述：因小程序有体积和资源加载限制，各家小程序平台提供了分包方式，优化小程序的下载和启动速度。默认生成的的目录中只有一个pages包进行页面添加，这个就是主包--放置默认启动页面/TabBar 页面
          • 代码示例
            • • preloadRule （分包预载配置）
                • 描述：配置preloadRule后，在进入小程序某个页面时，由框架自动预下载可能需要的分包，提升进入后续分包页面时的启动速度
                • 参数：
                • 注意
                  • 微信小程序每个分包的大小是2M，总体积一共不能超过20M。
                  • 分包下支持独立的 static 目录，用来对静态资源进行分包。（参考分包目录结构）
          • 分包后的目录结构为
            • ┌─pages │ ├─index │ │ └─index.vue │ └─login │ └─login.vue ├─pagesA //分包 │ ├─static │ └─list │ └─list.vue ├─pagesB //分包 │ ├─static │ └─detail │ └─detail.vue ├─static ├─main.js ├─App.vue ├─manifest.json └─pages.json
          • 分包建议
            • 主包页面控制在1-3个：首页、登录页面
            • 使用独立分包时，可设置"independent"：true
            • 子包页面按功能拆分
        • uni-app官方推荐easycom机制， 无需考虑导入和注册。默认是开启的
          • 组件路径需要符合规范，就可以不用引用、注册，直接在页面中使用
          • 路径规范
            • 安装在项目根目录的components目录下，并符合components/组件名称/组件名称.vue
            • 安装在uni_modules下，路径为uni_modules/插件ID/components/组件名称/组件名称.vue
          • 文件目录格式参考： ┌─components │ └─comp-a │ └─comp-a.vue 符合easycom规范的组件 └─uni_modules [uni_module](/plugin/uni_modules.md)中符合easycom规范的组件 └─uni_modules └─uni-list └─components └─uni-list └─ uni-list.vue
          • 如果有自己引入要扫描的包可以自己在page.json中进行配置
            • 代码
              • "easycom": { "autoscan": true, "custom": { "^uni-(.*)": "@/components/uni-$1.vue", // 匹配components目录内的vue文件 "^vue-file-(.*)": "packageName/path/to/vue-file-$1.vue" // 匹配node_modules内的vue文件 } }
            • 参数：
          • 文档：https://uniapp.dcloud.net.cn/collocation/pages.html#easycom
        • tabBar（一级原生底部导航栏）
          • 如果应用是一个多 tab 应用，可以通过 tabBar 配置项指定一级导航栏，以及 tab 切换时显示的对应页。
          • 代码示例
            • "tabBar": { "color": "#7A7E83", "selectedColor": "#3cc51f", "borderStyle": "black", "backgroundColor": "#ffffff", "list": [{ "pagePath": "pages/component/index", "iconPath": "static/image/icon_component.png", "selectedIconPath": "static/image/icon_component_HL.png", "text": "组件" }, { "pagePath": "pages/API/index", "iconPath": "static/image/icon_API.png", "selectedIconPath": "static/image/icon_API_HL.png", "text": "接口" }] }
          • 注意
            • 可自定义但体验感不如原生tabBar
            • tabBar的path需要在pages主包
          • 文档：https://uniapp.dcloud.net.cn/collocation/pages.html#tabbar
        • 顶部导航栏自定义
          • 代码示例
            • 在page.json进行静态配置
              • { "pages": [ { "path":"pages/index/index", "style":{ "navigationBarTitleText": "titleNView示例" "app-plus":{ //App端扩展配置 "titleNView":{ //原生导航栏配置参数 "backgroundImage":"/static/bg.png" //设置背景图 } } } } ], //... }
            • 在vue页面，通过js代码动态更新
              • <script> export default { //... methods: { changeBackgroundImage(){ // 获取当前窗口 var webview = this.$mp.page.$getAppWebview(); // 调用窗口对象的setStyle方法更新titleNView样式 webview.setStyle({titleNView:{ backgroundImage:"/static/bg.png" //设置背景图 }}); } } } </script>
          • 注意
            • 当navigationStyle设为custom或titleNView设为false时，原生导航栏不显示
              • 非H5端，手机顶部状态栏区域会被页面内容覆盖。这是因为窗体是沉浸式的原因，即全屏可写内容。uni-app提供了状态栏高度的css变量--status-bar-height，如果需要把状态栏的位置从前景部分让出来，可写一个占位div，高度设为css变量。
              • 前端导航栏搭配原生下拉刷新时，微信小程序下iOS需要拉更长才能看到下拉刷新的三个点，而Android是从屏幕顶部下拉，无法从导航栏下方下拉。如果一定要从前端导航栏下拉，小程序下只能放弃原生下拉刷新，纯前端模拟，参考mescroll插件，但这样很容易产生性能问题。目前小程序平台自身没有提供更好的方案
            • 详细文档：https://uniapp.dcloud.net.cn/collocation/pages.html#customnav
          • 功能示例应用：https://ext.dcloud.net.cn/plugin?id=1765
      • page.json所有配置文档地址：https://uniapp.dcloud.net.cn/collocation/pages.html
    • manifest.json
      • 应用配置
        • 应用的配置文件
        • 可以配置小程序的APPID
        • 设置各种平台特有的配置
      • 可添加环境配置
        • 作用：在开发过程中，可以区分当前开发环境运行不同的代码
        • 代码示例
          • "env": { "development": { "VUE_APP_BASE_URL": "https://dev.example.com" //开发环境url }, "production": { "VUE_APP_BASE_URL": "https://api.example.com" //正式环境url } }
        • 调用方式
          • process.env.VUE_APP_BASE_URL------当前环境的url
          • process.env.NODE_ENV------当前环境development 或 production
      • 微信配置文档：https://uniapp.dcloud.net.cn/collocation/manifest.html#mp-weixin
    • uni.scss
      • 整体应用风格控制文件
        • 在代码中无需 import 这个文件即可在scss代码中使用这里的样式变量
        • 可以达到全局可用的效果
      • 文档：https://uniapp.dcloud.net.cn/collocation/uni-scss.html
• 开发步骤
  • 引入拦截器
    • 拦截器作用
      • 自动携带 token
      • 请求/响应统一错误处理
      • 登录状态检查
      • 跳转登录页面等
    • 步骤
      • 1. 配置好环境url（具体看上方manifest.json的环境配置）
      • 2. 创建utils/request.js文件
      • 3. request文件代码示例
        • const IS_DEV = process.env.NODE_ENV === 'development'; const BASE_URL = process.env.VUE_APP_BASE_URL || 'https://dev.example.com'; // 默认开发地址 function showLoading(title = '加载中...') { uni.showLoading({ title, mask: true }); } function hideLoading() { uni.hideLoading(); } export default function request(options = {}) { const { url, method = 'GET', data = {}, header = {}, showLoading: needLoading = true, needAuth = true, loadingText = '加载中...' } = options; const token = uni.getStorageSync('token'); if (needLoading) showLoading(loadingText); return new Promise((resolve, reject) => { uni.request({ url: BASE_URL + url, method, data, header: { 'Content-Type': 'application/json', ...header, ...(needAuth && !IS_DEV ? { 'Authorization': `Bearer ${token}` } : {}) }, success(res) { if (needLoading) hideLoading(); // 开发环境跳过业务状态码判断 if (IS_DEV) { return resolve(res.data); } // 生产环境业务状态码处理 const { statusCode, data: resData } = res; if (statusCode === 200) { const { code, message, data } = resData; if (code === 0) { resolve(data); // 请求成功 } else if (code === 401) { uni.removeStorageSync('token'); uni.showToast({ title: '请先登录', icon: 'none' }); uni.navigateTo({ url: '/pages/login/login' }); reject(resData); } else { uni.showToast({ title: message || '请求失败', icon: 'none' }); reject(resData); } } else { uni.showToast({ title: '服务器错误', icon: 'none' }); reject(res); } }, fail(err) { if (needLoading) hideLoading(); uni.showToast({ title: '网络异常，请稍后重试', icon: 'none' }); reject(err); } }); }); }
      • 4. 调用示例
        • import request from '@/utils/request.js'; export default { methods: { async fetchData() { try { const result = await request({ url: '/api/article/list', method: 'GET', showLoading: true, // 可选：是否显示 loading needAuth: true // 可选：是否校验 token（默认 true） }); console.log('接口返回：', result); } catch (err) { console.error('请求失败：', err); } } } }
      • 5. 参数
        • url 请求地址（相对路径） 必填
        • method 请求方法（GET / POST 等） 'GET'
        • data 请求体数据 {}
        • header 自定义请求头 {}
        • showLoading 是否显示 loading 动画 true
        • loadingText loading 动画文本 '加载中...'
        • needAuth 是否携带 token 并做登录校验 true
  • 组件开发
    • 组件市场下载
    • 自定义组件
      • 与创建页面步骤一致
        • 需要注意命名规范，与使用方式
        • 添加在 components 文件夹下
      • 导入和注册
        • 在comeasy模式且组件路径规范下不需要
        • 传统模式下需要
      • 使用文档地址：https://uniapp.dcloud.net.cn/tutorial/vue-components.html
  • 创建页面
    • 步骤
      • 1. 在 pages 目录上右键 -> 新建页面
      • 2. 输入页面名称，如 home
    • vue页面结构
      • • <template>：页面模板，使用小程序组件如 view, text 等
        • <script>：页面逻辑，包含 data、生命周期、方法等
        • <style>：页面样式，支持 scss/less
    • 页面周期
      • onLoad：页面加载时触发
      • onShow：页面显示时触发
      • onReady：页面初次渲染完成时触发
      • onHide：页面隐藏时触发
      • onUnload：页面卸载时触发
  • API调用
    • 文档地址：https://uniapp.dcloud.net.cn/api/
      • 路由和跳转
        • 常见方法
          • // 保留当前页面，跳转到应用内页面 uni.navigateTo({ url: '/pages/home/home' }) // 关闭当前页面，跳转到应用内页面 uni.redirectTo({ url: '/pages/home/home' }) // 跳转到 tabBar 页面 uni.switchTab({ url: '/pages/index/index' }) // 返回上一页 uni.navigateBack()
        • 页面传参方法
          • 传参页面代码
            • uni.navigateTo({ url: '/pages/detail/detail?id=1&name=test' })
          • 接受页面代码
            • export default { onLoad(options) { console.log(options.id) // 1 console.log(options.name) // 'test' } }
      • 位置
      • 界面
      • 设备
      • ...
• 调试与发布
  • 1. 运行到微信开发者工具
    • 在 HBuilderX 中点击 运行 -> 运行到小程序模拟器 -> 微信开发者工具
    • 确保微信开发者工具已安装并登录
    • 首次运行需要配置微信开发者工具的安装路径
  • 2. 调试技巧
    • 使用console.log输出日志
    • 在微信开发者工具中使用Sources面板调试
    • 使用WXML面板查看页面结构
    • 使用Storage面板查看本地储存
  • 3. 发布小程序
    • 在 HBuilderX 中点击 发行 -> 小程序-微信
    • 填写小程序名称和 AppID
    • 点击发行，会生成一个 dist/build/mp-weixin 目录
    • 在微信开发者工具中导入这个目录
    • 在微信开发者工具中点击 上传 按钮提交审核
• 常见问题解决
  • 样式不生效
    • 检查样式作用域，添加scoped属性
    • 检查样式选择器是否正确
    • 检查是否使用了不支持的选择器
  • 图片路径问题
    • 使用绝对路径
    • 使用相对路径
    • 绝对路径与相对路径的文档地址：https://uniapp.dcloud.net.cn/tutorial/page-path.html
    • 使用网络图片
  • 跨域问题
    • 开发阶段不需要校验合法域名
    • 正式环境需要配置合法域名