一、先看清：小程序项目的基础结构

刚创建项目后，微信开发者工具的 “编辑” 面板会显示这样的文件结构（核心文件夹已标注）：

你的项目名/

├─ miniprogram/ # 小程序主代码目录（开发核心区）

│ ├─ pages/ # 页面文件夹（必用）

│ ├─ components/ # 自定义组件文件夹（常用）

│ ├─ utils/ # 工具函数文件夹（推荐）

│ ├─ images/ # 图片资源文件夹（推荐）

│ ├─ app.js # 全局入口脚本（必用）

│ ├─ app.json # 全局配置文件（必用）

│ └─ app.wxss # 全局样式文件（常用）

├─ node_modules/ # 第三方依赖文件夹（按需出现）

├─ project.config.json# 项目个性化配置（自动生成）

├─ sitemap.json # 微信索引配置（自动生成）

└─ package.json # 依赖管理文件（按需出现）

---

二、逐个拆解：每个文件夹放什么？怎么用？

（一）核心工作区：miniprogram/ 文件夹

这是小程序的 “主战场”，99% 的开发工作都在这里进行，所有业务代码、组件和资源都要往里放。

1. pages/：页面的 “专属房间”（必须用！）

作用：存放小程序的所有页面，每个页面单独占一个子文件夹，是用户能直接看到的界面载体。

内部规则：每个页面文件夹里固定有 4 个文件（可缺省 2 个），且文件名必须和文件夹名一致：

• 页面名.wxml：页面结构文件（类似网页的 HTML），写按钮、文字等可见元素，比如：

<!-- pages/index/index.wxml -->

<view class="title">欢迎来到我的小程序</view>

<button bindtap="sayHi">点我问好</button>

• 页面名.wxss：页面样式文件（类似 CSS），给元素设置颜色、大小，只对当前页面生效。

• 页面名.js：页面逻辑文件，处理点击事件、数据计算等，比如：

// pages/index/index.js

Page({

data: { name: "小白" }, // 页面初始数据

sayHi() {

wx.showToast({ title: `你好，${this.data.name}` })

}

})

• 页面名.json：页面配置文件，修改当前页面的导航栏颜色、标题等，会覆盖全局配置。

新手技巧：右键pages→“新建目录”→输入页面名（如login），再右键新目录→“新建 Page”→输入同名，工具会自动生成 4 个文件，还会在app.json里注册路径！

2. components/：可复用的 “零件库”（推荐用！）

作用：存放自定义组件，比如导航栏、商品卡片等，能在多个页面重复使用，避免写重复代码。

举个例子：做电商小程序时，每个商品页面都需要 “加入购物车” 按钮，就可以做成cart-btn组件放在这里，然后在首页、详情页直接调用。

使用规则：和页面类似，每个组件也是 4 个文件，但需要在组件的json里声明 “我是组件”：

// components/cart-btn/cart-btn.json

{ "component": true }

3. utils/：公共工具 “工具箱”（推荐用！）

作用：存放全局通用的函数，比如时间格式化、手机号验证等，一次编写到处调用。

使用步骤：

1. 在utils里新建format-time.js：

// 格式化时间为"2025-10-10"

function formatDate(date) {

return `${date.getFullYear()}-${date.getMonth()+1}-${date.getDate()}`

}

module.exports = { formatDate } // 导出函数

1. 在页面的js里引入使用：

const { formatDate } = require('../../utils/format-time.js')

console.log(formatDate(new Date())) // 输出当前日期

4. images/：图片资源 “仓库”（推荐用！）

作用：存放图标、背景图等静态资源，避免图片和代码混在一起导致混乱。

注意事项：

• 只支持png和jpg格式，其他格式（如 webp）无法显示；

• 引用时用相对路径，比如<image src="/images/logo.png"></image>。

（二）全局配置文件：miniprogram/ 下的 3 个核心文件

这 3 个文件在miniprogram根目录，控制整个小程序的全局行为：

• app.js：小程序入口文件，启动时最先执行，可初始化全局数据，比如：

App({

onLaunch() { // 小程序启动时触发

wx.login() // 自动获取用户登录状态

},

globalData: { userInfo: null } // 全局共享数据

})

• app.json：小程序 “总配置表”，必须注册所有页面路径，比如：

{

"pages": [

"pages/index/index", // 排在第一位的是首页

"pages/login/login"

],

"window": {

"navigationBarTitleText": "我的小程序" // 全局导航栏标题

}

}

• app.wxss：全局样式文件，定义的样式会作用于所有页面，比如设置全局文字颜色：

/* app.wxss */

text { color: #333; }

（三）根目录其他文件：了解即可，不用乱改

1. node_modules/：第三方 “外援库”

作用：当你用npm安装第三方工具（比如请求库axios）时，这个文件夹会自动出现，存放所有依赖包。

新手注意：不要手动修改里面的文件，卸载依赖用npm uninstall 包名即可。

2. project.config.json：你的 “个性化设置”

作用：记录你对开发者工具的自定义配置，比如项目名称、appid、编译设置等。

比如你设置了 “不校验域名”，这个配置会保存在这里，换电脑开发时会自动同步。

3. sitemap.json：小程序的 “SEO 配置”

作用：控制小程序页面是否允许微信搜索索引，类似网页的sitemap.xml。

默认开启索引，若某页面不想被搜到，可在里面配置排除：

{

"rules": [{ "page": "pages/login/login", "disallow": true }]

}

4. package.json：依赖 “说明书”

作用：记录项目依赖的第三方包名称和版本，比如你安装了lodash，这里会显示：

{

"dependencies": { "lodash": "^4.17.21" }

}

换环境开发时，执行npm install就能自动安装所有依赖。

---

三、新手避坑指南：3 个关键原则

1. 页面必须注册：新页面一定要在app.json的pages数组里添加路径，否则工具找不到页面；

1. 文件命名规范：文件夹和文件全部用小写英文，比如user-center而非 “用户中心”，避免报错；

1. 资源路径正确：引用utils或images里的内容时，用../回退目录（比如页面里引用 utils：../../utils/xxx.js）。

四、目录结构速查表

文件夹 / 文件	核心作用	存放内容举例
pages/	页面载体	首页、登录页、详情页的 4 类文件
components/	复用组件	导航栏、商品卡片组件
utils/	工具函数	时间格式化、数据验证函数
images/	静态资源	图标、背景图、商品图片
app.json	全局配置	页面路径、导航栏样式
node_modules/	第三方依赖	npm 安装的库（如 axios）