团队开发与基础封装（一）

本页对应 团队开发与基础封装，共 7 段视频，约 1 小时 9 分。

学习目标

• 能够说明小程序开发权限与体验权限的申请流程、适用人员及成员数量限制，并完成项目成员或体验成员的添加操作。
• 能够按业务代码与非业务代码分离的原则调整小程序目录结构，并正确配置 project.config.json 中的小程序根目录与自定义 NPM 构建路径。
• 能够在小程序项目中启用 Less 或 Sass，并通过定义变量、引用变量验证样式预处理功能生效。
• 能够使用 VS Code 打开小程序项目，安装并配置 WXML 语法高亮与 Prettier 格式化插件，验证代码高亮和自动格式化效果。
• 能够拉取并启动“享+生活”项目，完成分支与远程仓库调整、依赖安装及 NPM 构建，并使用小程序开发者工具预览和调试。
• 能够封装消息反馈与网络请求工具，配置接口基础路径和响应拦截器，并通过全局对象方式调用验证封装功能正常工作。

知识点

为什么团队开发要先申请权限

为什么需要：个人开发时，自己既是管理员，又使用个人 AppID，所以可以直接创建项目、写代码、预览调试。进入团队开发后，通常使用的是企业 AppID，而开发者一般不是小程序后台管理员，不能直接拿企业 AppID 开发。
怎么想：先明确“我是什么角色”。如果是写代码的程序员，就申请开发者权限；如果是测试、产品、客户，只需要体验小程序，就申请体验者权限。
怎么做：向项目负责人提供自己的微信号，由负责人在小程序管理后台添加成员；开发者还要向负责人或同事获取企业 AppID。
易错点：不要把“体验”当成“开发”，体验成员不能写代码；微信号要提供准确，否则后台搜索不到；企业 AppID 不要手抄，复制更稳妥。

两种权限的分工

为什么需要：团队里不是所有人都要写代码，但所有人都可能需要看到小程序效果。权限分开，既能保证开发安全，也方便测试和验收。
怎么想：开发者权限面向程序员，用于使用企业 AppID 创建、导入、开发小程序；体验者权限面向测试、产品、客户，用于在小程序未上线时体验功能、发现 bug、提出改进意见。
怎么做：开发者提供微信号并获取企业 AppID；体验者提供微信号，由管理员在后台添加，或通过体验码扫码申请。
易错点：项目成员和体验成员是两类成员，不要加错位置；体验者只能体验，不能修改代码。

申请开发者权限

为什么需要：只有被添加为项目成员，开发者才能使用企业 AppID 开发小程序。
怎么想：先让负责人把自己加入项目成员，再拿到企业 AppID，最后去创建或导入项目。
怎么做：登录小程序管理后台，进入“成员管理”，找到“项目成员”，点击添加成员，填写开发者微信号并搜索，出现头像后分配权限。转写稿中后台可分配“运营者、开发者、数据分析者”，实际按需要勾选，确认添加后由管理员微信扫码并确认。企业 AppID 的获取路径是：开发 → 开发管理 → 开发设置，在开发设置中复制 AppID。
易错点：添加后需要管理员扫码授权，不能只点“确认添加”就结束；AppID 要复制完整；创建项目时如果使用企业 AppID，前提是已经获得开发者权限。

申请体验者权限

为什么需要：测试、产品、客户需要在小程序上线前体验功能，但他们不应拥有写代码的权限。
怎么想：体验权限有两种常见入口：后台直接添加，或让体验者扫码申请后由管理员审核。
怎么做：后台方式是在“成员管理”的“体验成员”处点击添加，填写体验者微信号并搜索，确认后添加。扫码方式是在版本管理中找到体验码，发给测试、产品或客户；对方扫码后界面会提示申请体验权限，管理员看到申请后点击允许即可。
易错点：转写稿里的“体验嘛”按语境应理解为“体验码”；扫码申请不是自动通过，必须管理员允许；体验成员添加成功后才能在列表中看到。

人数限制与预览限制

为什么需要：权限不是无限添加的，而且预览二维码也不是公开链接。
怎么想：团队开发要提前规划成员数量；预览前先确认自己是否已被添加为项目成员或体验成员。
怎么做：转写稿明确，项目成员最多添加 15 个，体验成员最多也是 15 个。点击“预览”生成的二维码，只有项目成员或体验成员扫码才能打开小程序。
易错点：不要以为拿到预览二维码就能打开；如果未被添加权限，扫码也打不开；人数接近上限时要及时清理或规划成员。

完成权限后创建或导入项目

为什么需要：申请权限的最终目的，是能拿着企业 AppID 进入实际开发。
怎么想：权限确认后，就可以在开发者工具中新建或导入小程序项目。
怎么做：新建项目时填写项目名称、选择代码存放目录，把企业 AppID 粘贴到 AppID 位置；转写稿中课堂没有真实企业 AppID，所以用个人 AppID 代替演示，但操作时应理解为“已申请开发者权限后使用企业 AppID”。后续选择“不使用云服务”，点击“基础版本”确定即可。
易错点：课堂演示用个人 AppID 只是替代，不要误以为团队开发仍用个人 AppID；AppID 粘贴后要检查是否完整；项目目录要选空文件夹，避免代码混乱。

本节笔记没有额外图片和代码，核心是后台成员管理与权限申请流程。把开发者、体验者两类成员加对位置，拿到企业 AppID，并记住预览二维码的权限限制，团队开发的第一步就完成了。

为什么需要调整开发环境

小程序原始开发环境比较基础：业务文件、配置文件、依赖文件混在根目录中，项目规模变大后不易管理；样式只写 .wxss，复用和维护成本较高；小程序开发者工具自带编辑器功能也相对有限。转写稿中明确提到，调整开发环境主要围绕三件事：优化目录结构、启用 less/sass、配置 VS Code。下面按“为什么需要 → 怎么想 → 怎么做 → 易错点”展开。

优化目录结构

为什么需要：项目变大后，pages、utils、app.js、app.json、app.wxss 等业务代码，会和 package.json、构建产物、工具配置等非业务文件混在一起，查找和协作都不方便。转写稿的思路是把“跟业务直接相关的代码”放一起，把“跟业务无关的文件和目录”放根目录。

怎么想：新建一个业务代码目录，名称不固定，转写稿中常用 miniprogram。把 pages、utils、app.js、app.json、app.wxss 移入该目录；根目录保留非业务文件。调整后小程序运行会报错，因为开发者工具按原路径找不到业务代码，需要修改 project.config.json。

怎么做：在 project.config.json 中指定 miniprogramRoot，并配置自定义 NPM 构建。笔记代码如下：

{
  "setting": {
    "packNpmManually": true,
    "packNpmRelationList": [
      {
        "miniprogramNpmDistDir": "业务代码所在目录",
        "packageJsonPath": "package.json的路径"
      }
    ]
  },
  "miniprogramRoot": "业务代码所在目录"
}

转写稿的调试过程是：移动文件后先看到报错，保存 miniprogramRoot 后错误消失；之后安装依赖并执行“构建 NPM”，构建结果应放到业务代码目录，package.json 通常在根目录查找。若构建结果没有出现在业务目录，检查 miniprogramNpmDistDir 是否与业务根目录一致。

易错点：目录名不要写错；miniprogramRoot 必须指向真实业务目录；packNpmManually 要设为 true；packageJsonPath 要指向实际存在的 package.json；移动文件后要确认 pages、utils 与 app.* 仍保持正确层级。

启用 less/sass

为什么需要：less/sass 可以用变量、嵌套等能力管理样式，减少重复。转写稿中通过定义变量并让首页 container 文字变红来验证是否生效。

怎么想：小程序通过 project.config.json 的 setting.useCompilerPlugins 启用编译插件，数组里可写 less、sass 或 typescript。笔记要求启用 less/sass，示例启用 sass。

怎么做：在 setting 中加入：

{
  "setting": {
    "useCompilerPlugins": ["sass"]
  }
}

然后把需要使用的 .wxss 文件后缀改为 .scss。转写稿示例中定义 $color: red;，在 .container 中使用 color: $color;，保存后文字变红，说明变量生效。

易错点：不改后缀仍用 .wxss 时，不能直接使用 sass 语法；插件名不要写成 sars 等错误拼写；已有样式迁移时要逐个确认后缀和语法；保存后看编译结果验证。

配置 VS Code

为什么需要：小程序开发者工具基于 VS Code 开发，但编辑器功能相对单一。转写稿建议：用 VS Code 写代码，用小程序开发者工具预览和调试。这样既保留小程序工具的运行能力，又提高编码效率。

怎么想：VS Code 原生支持 .js、.json，但 .wxml、.wxss 默认缺少高亮和提示，需要安装插件；代码格式要统一，则用 Prettier，并让 WXML 插件调用 Prettier 格式化。

怎么做：安装 WXML - Language Service 和 Prettier - Code Formatter，在 VS Code 设置 JSON 中加入笔记配置：

{
  "minapp-vscode.wxmlFormatter": "prettier",
  "minapp-vscode.prettier": {
    "useTabs": false,
    "tabWidth": 2,
    "printWidth": 80,
    "singleQuote": false
  },
  "[wxml]": {
    "editor.defaultFormatter": "qiu8310.minapp-vscode"
  },
  "minapp-vscode.formatMaxLineCharacters": 80,
}

转写稿的验证过程是：打开 .wxml 后先没有高亮，安装插件后出现高亮；若未立即生效可重启 VS Code。保存 WXML 时，长行会按 80 字符换行，属性分行显示。注意只把 VS Code 当编辑器，预览、调试仍在开发者工具中完成。

易错点：插件名和配置键不要拼错；配置追加到已有设置时注意逗号；[wxml] 的默认格式化器要指向 WXML 插件；不要误以为 VS Code 能替代开发者工具的预览调试。

课件图示

代码示例

1. project.config.json：优化目录结构 + 启用 sass

{
  "description": "项目配置文件",
  "projectname": "mpdemo",
  "appid": "wx1234567890abcdef",
  "compileType": "miniprogram",
  "miniprogramRoot": "miniprogram/",
  "setting": {
    "packNpmManually": true,
    "packNpmRelationList": [
      {
        "miniprogramNpmDistDir": "./miniprogram",
        "packageJsonPath": "./package.json"
      }
    ],
    "useCompilerPlugins": ["sass"]
  }
}

要点与易错点

• miniprogramRoot 指向业务代码所在目录。把 pages、utils、app.js、app.json、app.wxss 拖进 miniprogram/ 后，如果不配置这一项，小程序打包时就找不到代码，会直接报错。
• miniprogramNpmDistDir 通常和 miniprogramRoot 保持一致（构建产物属于业务代码，最终要被页面加载）。
• packageJsonPath 指向根目录下的 package.json；必须先执行 npm install 生成该文件，否则路径无效。
• packNpmManually: true 表示自定义 NPM 构建，默认值是 false，需要手动改成 true。
• useCompilerPlugins 默认不存在，需要手动添加；数组可选 "less" / "sass" / "typescript"。启用后把 .wxss 改成 .scss（或 .less）才能用变量等语法，不改后缀继续用 .wxss 也没问题。
• 目录名（如 miniprogram）可以自定义，但配置里写的名字必须和实际目录完全一致。

---

2. utils/toast.js：消息反馈（轻提示）封装

// utils/toast.js
const toast = {
  /**
   * 消息反馈（轻提示）
   * @param {string} title 文字提示内容
   */
  toast(title = '数据加载失败...') {
    wx.showToast({
      title,
      mask: true,
      icon: 'none',
    })
  },
}

// 方式一：模块导出
export default toast

// 方式二：挂到全局对象 wx 上（推荐）
wx.toast = toast

// app.js
// 执行 utils/toast.js，把封装好的 toast 挂到全局对象 wx 上
import './utils/toast'

App({
  onLaunch() {},
})

// pages/index/index.js
Page({
  onLoad() {
    // 全局对象方式调用（推荐）
    wx.toast.toast('页面加载完成了...')
  },
})

要点与易错点

• 封装的意义：wx.showToast 每次都要传 mask、icon，封装后只需传 title，调用更简洁。
• title 给了默认值 '数据加载失败...'，不传参数时也不会报错。
• 想用 wx.toast 这种方式，必须在 app.js 里 import './utils/toast' 执行一次；如果忘记写这一行，wx.toast 就是 undefined，调用会报错。
• 生命周期是 onLoad（L 大写），不是 onload；VS Code 自动提示给出的小写形式不要直接采用。
• 想让 VS Code 对 wx.showToast 等 API 有提示，需安装「微信小程序开发工具」插件。
• 文档注释 /** ... */ 会被 VS Code 提取，鼠标悬停方法时能看到参数说明。

---

3. utils/http.js：网络请求封装（wechat-http）

// utils/http.js
import http from 'wechat-http'

// 配置接口基础路径（从接口文档复制，末尾的斜杠不要）
http.baseURL = 'https://api.example.com'

// 响应拦截器：只保留 data，其余 config / cookies / header 全部过滤掉
http.intercept.response = (res) => {
  const { data } = res
  return data
}

// 挂到全局对象
wx.http = http

export default http

// app.js
import './utils/toast'
import './utils/http'

App({
  onLaunch() {},
})

// pages/index/index.js
Page({
  async onLoad() {
    // 全局对象方式调用，只写接口路径部分
    const res = await wx.http.get('/接口路径')
    console.log(res)
  },
})

要点与易错点

• 先安装：npm install wechat-http，然后在小程序开发者工具里点「工具 → 构建 NPM」，构建完在 miniprogram/miniprogram_npm 下能看到 wechat-http 才能使用；不构建就用不了。
• baseURL 末尾的 / 要去掉，否则和接口路径拼接会出现 //。
• 拦截器里 return 什么，外面就拿到什么；return data 后 res 就是业务数据本身，不再是完整的响应对象。
• 请求接口报「不在合法域名列表」，是因为域名没配置到小程序后台；课上可临时勾选「不校验合法域名」。
• 用全局方式必须在 app.js 里 import './utils/http' 执行一次，否则 wx.http 不存在。
• wechat-http 支持 Promise，因此可以配合 async / await 写请求代码。

常见错误

1. 现象：新同事扫预览二维码提示无权限；原因：二维码仅项目成员/体验成员可打开，未添加对应成员；修法：管理员在成员管理中添加项目成员或体验成员，再让其扫码。
2. 现象：调整目录后开发者工具编译报错、找不到页面；原因：业务代码已移入子目录，但 miniprogramRoot 未同步；修法：修改 project.config.json 的 miniprogramRoot 指向实际业务目录，保存后重新编译。
3. 现象：npm 安装 wechat-http、wux 等后页面仍找不到模块；原因：只安装未构建，或 packNpmManually、packNpmRelationList 未配置/路径错误；修法：确认 package.json 存在，配置自定义 NPM 构建，miniprogramNpmDistDir 指向业务目录，执行“构建 NPM”。
4. 现象：启用 sass 后变量、嵌套不生效；原因：只加 useCompilerPlugins 未把 .wxss 改为 .scss，或数组值写错；修法：配置 ["sass"]，将样式文件后缀改为 .scss，重新编译验证。
5. 现象：VS Code 中 WXML/WXSS 无高亮、保存不格式化；原因：未安装 WXML Language Service/Prettier，或 WXML 默认格式化器与 Prettier 未关联；修法：安装插件并配置 defaultFormatter 与 minapp-vscode.wxmlFormatter 为 prettier，必要时重启 VS Code。
6. 现象：页面调用 wx.$toast 或 wx.$http 报 undefined；原因：对应 util/http 文件未在 app.js 中 import 执行，未挂到全局对象；修法：在 app.js 入口 import 并执行对应文件，确认挂载语句执行后再调用。
7. 现象：请求接口报“合法域名”错误；原因：接口域名未加入小程序后台 request 合法域名；修法：后台配置域名；仅本地学习可临时勾选“不校验合法域名”，上线前必须配置。
8. 现象：git push 失败；原因：仍使用讲师仓库地址/无权限，或分支未改；修法：新建自己的远程仓库，修改 remote 地址，按需将分支改为 main/master 后再推送。

练习

1. 给只有体验权限的测试同学发预览码仍打不开，列出你的排查顺序与处理清单。
2. 完成目录迁移后编译报错：检查 project.config.json 并修复；再安装一个 npm 包，验证构建产物位置是否正确。
3. 启用 sass 并定义一个变量，验证首页文字颜色变化；若失败，列出至少 3 个排查点。
4. 用 VS Code 打开项目，完成 WXML 高亮与 Prettier 格式化配置，保存一个长 WXML 验证效果。
5. 封装一个全局方法并在页面调用；若页面中为 undefined，定位入口加载与挂载问题。

原视频对照

#	视频	时长
1	小程序团队开发-申请权限	11:34
2	小程序团队开发-优化目录结构	10:22
3	小程序团队开发-启用less或sass	03:52
4	小程序团队开发-配置VSCode	09:12
5	享+生活-项目启动	10:16
6	享+生活-基础封装（消息反馈）	12:25
7	享+生活-基础封装（网络请求）	11:52

小结

1. 团队开发先确认 AppID 与成员权限，预览/体验同样受成员身份限制。
2. 目录调整必须同步 project.config.json，否则编译和构建都会失效。
3. npm 依赖在小程序中“安装≠可用”，构建配置与构建动作要同时到位。
4. sass/less 属于编译期能力，配置、后缀、重新编译三者缺一不可。
5. VS Code 主要承担编码，预览调试仍回开发者工具；插件与格式化配置要配套。
6. 全局封装依赖入口执行，未在 app.js 加载就不要在页面直接调用。
7. 网络请求先解决合法域名，再用拦截器收敛响应数据；上线前不能依赖“不校验域名”。