微信小程序开发（二）目录结构完全指南

Slow菜鸟2026-02-26 13:40

微信小程序开发（二）目录结构完全指南

  • 一、核心概念：两种目录结构
    • [1.1 扁平结构](#1.1 扁平结构)
    • [1.2 包裹结构](#1.2 包裹结构)
    • [1.3 快速对比](#1.3 快速对比)
  • 二、微信开发者工具创建项目时的选择
    • 什么时候会生成包裹结构？
      • [情况1: 选择"云开发模板"](#情况1: 选择"云开发模板")
      • [情况2: 选择"TypeScript 模板"](#情况2: 选择"TypeScript 模板")
      • [情况3: 不选择模板/选择普通模板](#情况3: 不选择模板/选择普通模板)
    • 核心理解
  • 三、重要结论
    • [miniprogram/ 内部结构与扁平结构完全相同！](#miniprogram/ 内部结构与扁平结构完全相同！)
  • 四、小程序的文件组织规则
  • [五、uni-app 编译机制](#五、uni-app 编译机制)
    • [5.1 编译转换：1个文件 → 4个文件](#5.1 编译转换：1个文件 → 4个文件)
    • [5.2 编译后的代码为什么看不懂？](#5.2 编译后的代码为什么看不懂？)
    • [5.3 正确的开发流程](#5.3 正确的开发流程)
    • [⚠️ 重要提醒](#⚠️ 重要提醒)
  • 六、常见问题
    • [Q1: 如何判断项目是哪种结构？](#Q1: 如何判断项目是哪种结构？)
    • [Q2: miniprogram/ 里面的结构和扁平结构一样吗？](#Q2: miniprogram/ 里面的结构和扁平结构一样吗？)
    • [Q3: uni-app 编译后为什么是扁平结构？](#Q3: uni-app 编译后为什么是扁平结构？)
    • [Q4: 可以在微信开发者工具里改 uni-app 的代码吗？](#Q4: 可以在微信开发者工具里改 uni-app 的代码吗？)
  • 七、核心要点总结
    • [1. 两种结构](#1. 两种结构)
    • [2. 判断标准](#2. 判断标准)
    • [3. 结构由创建时决定](#3. 结构由创建时决定)
    • [4. uni-app 编译](#4. uni-app 编译)
    • [5. 开发建议](#5. 开发建议)
  • 八、参考资源

一、核心概念：两种目录结构

微信小程序有两种目录组织方式，区别在于源码的存放位置。

1.1 扁平结构

特点： 源码直接放在项目根目录

复制代码 
项目根目录/
├── app.js                      # 小程序入口逻辑(必需)
├── app.json                    # 小程序全局配置(必需)
├── app.wxss                    # 小程序全局样式(自动生成)
├── pages/                      # 页面目录(必需)
│   └── index/                  # 首页示例
│       ├── index.js            # 页面逻辑(必需)
│       ├── index.wxml          # 页面结构(必需)
│       ├── index.json          # 页面配置(自动生成)
│       └── index.wxss          # 页面样式(自动生成)
├── project.config.json         # 项目配置文件(必需)
├── sitemap.json                # 小程序搜索配置(自动生成)
├── project.private.config.json # 个人配置文件(自动生成)
├── components/                 # 自定义组件目录(可选)
├── utils/                      # 工具函数目录(可选)
├── images/                     # 图片资源目录(可选)
└── .eslintrc.js                # ESLint 配置(某些模板生成)

配置文件：

json 复制代码 
{
  "compileType": "miniprogram"
  // 没有 miniprogramRoot 配置
}

何时生成： 创建项目时不选择模板,或选择普通 JavaScript 模板

1.2 包裹结构

特点： 源码放在 miniprogram/ 子目录

复制代码 
项目根目录/
├── miniprogram/                # 小程序源码目录(必需)
│   ├── app.js                  # 小程序入口逻辑(必需)
│   ├── app.json                # 小程序全局配置(必需)
│   ├── app.wxss                # 小程序全局样式(自动生成)
│   ├── pages/                  # 页面目录(必需)
│   │   └── index/              # 首页示例
│   │       ├── index.js        # 页面逻辑(必需)
│   │       ├── index.wxml      # 页面结构(必需)
│   │       ├── index.json      # 页面配置(自动生成)
│   │       └── index.wxss      # 页面样式(自动生成)
│   ├── sitemap.json            # 小程序搜索配置(自动生成)
│   ├── components/             # 自定义组件目录(可选)
│   ├── utils/                  # 工具函数目录(可选)
│   ├── images/                 # 图片资源目录(可选)
│   └── envList.js              # 云开发环境配置(仅云开发模板)
├── project.config.json         # 项目配置文件(必需)
├── project.private.config.json # 个人配置文件(自动生成)
├── cloudfunctions/             # 云函数目录(仅云开发模板)
├── typings/                    # TypeScript 类型定义(仅TS模板)
├── tsconfig.json               # TypeScript 配置(仅TS模板)
├── package.json                # npm 包配置(仅TS模板)
├── README.md                   # 项目说明文档(仅云开发模板)
└── uploadCloudFunction.sh      # 云函数上传脚本(仅云开发模板)

配置文件：

json 复制代码 
{
  "miniprogramRoot": "miniprogram/",  // ← 关键配置
  "cloudfunctionRoot": "cloudfunctions/"  // 仅云开发模板有
}

何时生成： 创建项目时选择"云开发模板"或"TypeScript 模板"

1.3 快速对比

对比项 扁平结构 包裹结构
源码位置 根目录 miniprogram/
配置标识 无 miniprogramRoot 有 miniprogramRoot
创建时选择 不选模板/普通模板 云开发模板/TS模板

二、微信开发者工具创建项目时的选择

什么时候会生成包裹结构？

微信开发者工具在创建项目时,根据你的选择自动决定目录结构:

情况1: 选择"云开发模板"

微信开发者工具会自动生成包裹结构:

复制代码 
根目录/
├── miniprogram/                # 小程序源码(必然生成)
│   ├── app.js                  # 必需
│   ├── app.json                # 必需
│   ├── app.wxss                # 自动生成
│   ├── pages/                  # 必需
│   ├── sitemap.json            # 自动生成
│   ├── envList.js              # 云开发环境配置(云开发特有)
│   ├── components/             # 可选
│   └── images/                 # 可选
├── cloudfunctions/             # 云函数目录(云开发特有,必然生成)
│   └── quickstartFunctions/    # 示例云函数(可能有)
├── project.config.json         # 必需,自动配置 miniprogramRoot
├── project.private.config.json # 自动生成
├── README.md                   # 云开发说明文档(云开发特有)
└── uploadCloudFunction.sh      # 云函数上传脚本(云开发特有)

配置特征:

json 复制代码 
{
  "miniprogramRoot": "miniprogram/",
  "cloudfunctionRoot": "cloudfunctions/"
}

情况2: 选择"TypeScript 模板"

微信开发者工具会自动生成包裹结构:

复制代码 
根目录/
├── miniprogram/                # TS 源码(必然生成)
│   ├── app.ts                  # 注意是 .ts 文件(必需)
│   ├── app.json                # 必需
│   ├── app.wxss                # 自动生成
│   ├── pages/                  # 必需
│   │   └── index/
│   │       ├── index.ts        # 页面逻辑用 TS(必需)
│   │       ├── index.wxml      # 必需
│   │       ├── index.json      # 自动生成
│   │       └── index.wxss      # 自动生成
│   └── utils/                  # 工具函数(可选)
├── typings/                    # 类型定义(TS模板特有,必然生成)
│   ├── types/                  # 微信 API 类型声明
│   └── index.d.ts              # 全局类型定义
├── project.config.json         # 必需,自动配置 miniprogramRoot
├── project.private.config.json # 自动生成
├── tsconfig.json               # TypeScript 编译配置(TS模板特有,必然生成)
└── package.json                # npm 依赖管理(TS模板特有,必然生成)

配置特征:

json 复制代码 
{
  "miniprogramRoot": "miniprogram/",
  "setting": {
    "useCompilerPlugins": ["typescript"]
  }
}

情况3: 不选择模板/选择普通模板

微信开发者工具会生成扁平结构:

复制代码 
根目录/
├── app.js                      # 直接在根目录(必需)
├── app.json                    # 必需
├── app.wxss                    # 自动生成
├── pages/                      # 必需
│   └── index/                  # 首页示例
├── project.config.json         # 必需,没有 miniprogramRoot
├── sitemap.json                # 自动生成
├── project.private.config.json # 自动生成
├── components/                 # 可选(某些模板会生成)
└── .eslintrc.js                # 可选(某些模板会生成)

核心理解

包裹结构不是开发者自己创建的,而是微信开发者工具根据你创建项目时的选择自动生成的。

选择云开发或 TypeScript 模板 → 工具自动生成 miniprogram/ 目录

三、重要结论

miniprogram/ 内部结构与扁平结构完全相同！

复制代码 
扁平结构:              包裹结构:
根目录/                根目录/
├── app.js             └── miniprogram/  ← 只是多了这一层
├── pages/                 ├── app.js    ← 内容完全相同
└── components/            ├── pages/
                           └── components/

关键理解： miniprogram/ 只是一个容器，不改变内部结构。

四、小程序的文件组织规则

每个页面通常由4个文件组成

复制代码 
pages/index/
├── index.js      # 页面逻辑（必需）
├── index.wxml    # 页面结构（必需）
├── index.json    # 页面配置（可选，但工具会自动生成）
└── index.wxss    # 页面样式（可选，但工具会自动生成）

说明：

  • 微信官方规定：只有 .js 和 .wxml 是必需的
  • 但微信开发者工具创建页面时会自动生成全部4个文件
  • .json 和 .wxss 可以删除，不影响运行

文件命名规则

必须与目录名一致！

复制代码 
✅ 正确：
pages/index/
├── index.js
├── index.json
├── index.wxml
└── index.wxss

❌ 错误：
pages/index/
├── main.js      ← 文件名不一致，会报错！

五、uni-app 编译机制

5.1 编译转换：1个文件 → 4个文件

uni-app 源码（1个文件）：

vue 复制代码 
<!-- pages/index/index.vue -->
<template>
  <view>{{ title }}</view>
</template>

<script>
export default {
  data() {
    return { title: 'Hello' }
  }
}
</script>

<style>
.content { padding: 20px; }
</style>

编译后（4个文件）：

复制代码 
unpackage/dist/dev/mp-weixin/pages/index/
├── index.js      ← 从 <script> 编译 + Vue runtime
├── index.wxml    ← 从 <template> 编译
├── index.json    ← 自动生成页面配置
└── index.wxss    ← 从 <style> 编译

5.2 编译后的代码为什么看不懂？

三个原因：

  1. 编译器转换 - uni-app 编译器将 Vue 语法转换为小程序语法
  2. Vue runtime 注入 - 注入数据绑定、生命周期等运行时代码
  3. 代码优化 - 模块打包、代码压缩等优化处理

结论： 这是正常的编译输出，不要修改编译后的代码！

5.3 正确的开发流程

复制代码 
1. 在 HBuilderX 编写 .vue 源码
   ↓
2. 保存后自动编译到 unpackage/dist/dev/mp-weixin/
   ↓
3. 微信开发者工具自动刷新预览
   ↓
4. 预览和调试
   ↓
5. 修改代码 → 回到步骤1（在 HBuilderX 改）

⚠️ 重要提醒

❌ 不要在微信开发者工具里修改编译后的代码！

  • 每次保存 .vue 文件都会重新编译
  • 编译会覆盖之前的输出
  • 在微信开发者工具里的修改会丢失
  • 必须在 HBuilderX 里改 .vue

六、常见问题

Q1: 如何判断项目是哪种结构？

方法1： 看根目录有没有 app.js

  • 有 → 扁平结构
  • 没有 → 包裹结构

方法2： 看 project.config.json

  • 有 miniprogramRoot → 包裹结构
  • 没有 → 扁平结构

Q2: miniprogram/ 里面的结构和扁平结构一样吗？

完全一样！ 只是外面多了一层容器。

Q3: uni-app 编译后为什么是扁平结构？

因为：

  • uni-app 已完成编译
  • 输出的是纯小程序代码
  • 不需要再构建
  • 直接可用

Q4: 可以在微信开发者工具里改 uni-app 的代码吗？

不可以！ 必须在 HBuilderX 里改 .vue 源码。

七、核心要点总结

1. 两种结构

  • 扁平结构 - 源码在根目录，创建时不选模板
  • 包裹结构 - 源码在 miniprogram/，创建时选云开发或 TS 模板

2. 判断标准

看 project.config.json 中的 miniprogramRoot 配置

3. 结构由创建时决定

微信开发者工具根据你的选择自动生成对应结构，不是开发者后期手动创建

4. uni-app 编译

  • 1个 .vue 文件 → 4个小程序文件
  • 编译后是扁平结构
  • 不要修改编译后的代码
  • 必须在 HBuilderX 里改源码

5. 开发建议

  • 原生开发 - 可以在微信开发者工具里改代码
  • uni-app 开发 - 只能在 HBuilderX 里改代码
  • 微信开发者工具 - 用于预览和调试，不是编辑器

八、参考资源

相关推荐
luffy54592 小时前
微信小程序页面使用类似filter函数的wxs语法
微信小程序·小程序
攀登的牵牛花4 小时前
给女朋友写了个轻断食小程序：去老丈人家也是先动筷了
前端·微信小程序
前端小雪的博客.4 小时前
【保姆级教程】uniAI 插件高效开发 uni-app 微信小程序（附实战案例）
微信小程序·uni-app·ai编程·uniai
小小王app小程序开发4 小时前
海外盲盒小程序抽赏玩法分析（附跨境技术落地要点）
小程序
一叶星殇4 小时前
微信小程序请求拦截器踩坑：避免重复刷新 token
微信小程序·小程序
hello kitty w5 小时前
4. 基本语法
小程序
CHU7290355 小时前
探索淘宝扭蛋机小程序：创意互动与趣味体验的融合
小程序
头发还在的女程序员6 小时前
【免费下载】企业能源管理系统
小程序·策略模式·能源管理
吴声子夜歌19 小时前
小程序——样式与布局
小程序
热门推荐
01GitHub 镜像站点02【OpenClaw 本地实战 Ep.3】突破瓶颈：强制修改 openclaw.json 解锁 32k 上下文记忆03Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services04OpenClaw 使用和管理 MCP 完全指南05AI Agent 平台横评：ZeroClaw vs OpenClaw vs Nanobot06Clawdbot部署教程：解决‘gateway token missing’授权问题的完整步骤07AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南08OpenClaw 安装之（三）DeepSeek模型接入配置和详细配置参数09AI agent：介绍 ZeroClaw 安装，使用10让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南