第3章项目结构与基础配置

3、项目结构与基础配置：小程序项目目录结构解析

好，咱们直接进入正题。这一章我带你拆解抖音小程序的骨架——项目结构。说白了，你写小程序就像盖房子，得先知道哪是承重墙、哪是水电管。我刚开始带团队时，发现很多新人上来就写代码，结果项目一复杂，连配置文件在哪都找不到。嗯，咱们别犯这个错。

3.1 项目目录结构全景

你新建一个抖音小程序项目后，默认会看到这样的结构：

my-miniapp/
├── app.json          # 全局配置
├── app.js            # 全局逻辑
├── app.css           # 全局样式
├── project.config.json # 项目配置
├── sitemap.json      # 搜索索引配置
├── pages/            # 页面目录
│   ├── index/
│   │   ├── index.js
│   │   ├── index.css
│   │   ├── index.json
│   │   └── index.ttml
│   └── logs/
│       ├── logs.js
│       ├── logs.css
│       ├── logs.json
│       └── logs.ttml
└── components/       # 公共组件目录
    └── my-component/
        ├── my-component.js
        ├── my-component.css
        ├── my-component.json
        └── my-component.ttml

这个结构其实很直观。每个页面都是一个文件夹，里面放四个文件。组件也是同理。我个人习惯把 components/ 放在根目录，这样所有页面都能引用。曾经有个项目，我把组件散落在各个页面里，后来维护起来简直想哭。

3.2 app.json：全局配置的核心

app.json 是小程序的「总开关」。你想想看，小程序启动时第一个读的就是它。它决定了哪些页面存在、窗口长什么样、底部导航怎么排。

一个典型的 app.json 长这样：

{
  "pages": [
    "pages/index/index",
    "pages/logs/logs",
    "pages/user/user"
  ],
  "window": {
    "navigationBarTitleText": "我的小程序",
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "backgroundColor": "#f5f5f5",
    "backgroundTextStyle": "dark"
  },
  "tabBar": {
    "color": "#999999",
    "selectedColor": "#07c160",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "images/home.png",
        "selectedIconPath": "images/home-active.png"
      },
      {
        "pagePath": "pages/user/user",
        "text": "我的",
        "iconPath": "images/user.png",
        "selectedIconPath": "images/user-active.png"
      }
    ]
  },
  "networkTimeout": {
    "request": 10000,
    "connectSocket": 5000
  }
}

关键点：

pages 数组的第一项就是小程序的首页。顺序很重要，别搞反了。
tabBar 最多支持 5 个 tab，多了会报错。我踩过这个坑。
networkTimeout 单位是毫秒，默认 60 秒，建议调小一点，用户体验更好。

3.3 页面配置：覆盖全局的局部设置

每个页面都有自己的 .json 文件。它用来覆盖 app.json 中的 window 配置。说白了，就是「局部优先」原则。

举个例子，你首页想用绿色导航栏，但其他页面保持白色：

// pages/index/index.json
{
  "navigationBarTitleText": "首页",
  "navigationBarBackgroundColor": "#07c160",
  "navigationBarTextStyle": "white",
  "enablePullDownRefresh": true,
  "onReachBottomDistance": 50
}

这里要注意：enablePullDownRefresh 开启后，记得在 .js 里监听 onPullDownRefresh 事件，否则下拉没反应。我曾经有个项目，开了下拉刷新但忘了写监听，用户疯狂下拉，页面纹丝不动……嗯，挺尴尬的。

3.4 sitemap.json：让小程序被搜到

这个文件很多人会忽略。它控制着小程序页面能否被搜索引擎索引。说白了，就是决定你的页面能不能在抖音搜索里被找到。

{
  "rules": [
    {
      "action": "allow",
      "page": "pages/index/index",
      "params": ["id", "type"],
      "matching": "exact"
    },
    {
      "action": "disallow",
      "page": "pages/user/user"
    }
  ]
}

我的建议：

核心页面（首页、商品详情）设为 allow。
个人中心、后台页面设为 disallow，避免隐私泄露。
matching 参数有 exact、prefix、suffix 三种，默认是 prefix。我一般用 exact，更精确。

3.5 主题与基础样式

抖音小程序支持 CSS 变量，你可以用它来做主题切换。我个人非常喜欢这个特性，比写死颜色值灵活多了。

在 app.css 中定义全局变量：

/* app.css */
page {
  --primary-color: #07c160;
  --secondary-color: #ff6b6b;
  --bg-color: #f5f5f5;
  --text-color: #333333;
  --font-size-base: 28rpx;
  --spacing-base: 20rpx;
}

然后在页面里直接用：

/* pages/index/index.css */
.container {
  background-color: var(--bg-color);
  padding: var(--spacing-base);
}

.title {
  color: var(--primary-color);
  font-size: var(--font-size-base);
}

为什么要用 CSS 变量？你想想看，如果有一天产品经理说「把主色从绿色改成蓝色」，你只需要改 app.css 里一个值，所有页面自动更新。我曾经在一个老项目里硬编码了 200 多处颜色值，改到凌晨三点……从那以后，我所有项目都强制用 CSS 变量。

避坑指南：

抖音小程序的 CSS 变量兼容性很好，但别用太新的 CSS 特性，比如 :has() 选择器，部分低版本抖音不支持。
单位尽量用 rpx，它会根据屏幕宽度自适应。我见过有人用 px，结果在不同手机上布局全乱了。
全局样式别写太多，避免污染页面。我习惯只定义变量和基础重置，具体样式放页面级。

3.6 组件目录的最佳实践

组件放在 components/ 下，每个组件一个文件夹。命名建议用中划线，比如 my-component，而不是 myComponent。为什么？因为抖音小程序的标签名强制用小写中划线，保持一致更省心。

一个组件的 .json 文件要声明 component: true：

// components/my-component/my-component.json
{
  "component": true,
  "usingComponents": {}
}

然后在页面里引用：

// pages/index/index.json
{
  "usingComponents": {
    "my-component": "/components/my-component/my-component"
  }
}

经验之谈：

组件路径用绝对路径（以 / 开头），避免相对路径的混乱。
组件内部不要依赖全局样式，要自包含。我见过组件因为全局样式被覆盖，显示异常，排查了半天。
如果组件需要接收外部样式，用 externalClasses 属性，别直接操作 DOM。

3.7 项目配置：project.config.json

这个文件是开发工具用的，不参与小程序运行。但它很重要，决定了你的项目在团队协作时的一致性。

{
  "setting": {
    "urlCheck": false,
    "es6": true,
    "postcss": true,
    "minified": true
  },
  "appid": "你的appid",
  "projectname": "我的小程序"
}

urlCheck 建议开发时设为 false，否则请求非 HTTPS 接口会报错。上线前记得改回 true。我有个同事忘了改，结果线上版本请求全挂了……嗯，那天他加班到很晚。

3.8 小结

这一章的内容其实不难，但很重要。项目结构就像房子的骨架，配置就是水电图。你把这些搞清楚了，后面写代码才会顺手。下一章我们开始写第一个页面，到时候你会真正感受到「配置驱动」的威力。

记住一句话：好的项目结构，能让你少加一半的班。