小程序project.json怎么写

小程序project.json配置全解析：从入门到精通

在小程序开发中，project.json 是项目根目录下的核心配置文件，它如同项目的“说明书”，定义了小程序的全局配置、页面路径、窗口样式、编译设置等关键信息，正确编写 project.json 是保障小程序正常运行、优化开发体验的基础，本文将从文件结构、核心配置项、常见场景及最佳实践出发，带你全面 project.json 的编写方法。

初识 project.json：文件定位与基础结构

project.json 是小程序项目的全局配置文件，位于项目根目录下（与 app.js、app.json、app.wxss 同级），它主要用于配置项目的页面路由、窗口表现、编译模式、第三方库依赖等全局性参数,是小程序框架加载和运行项目的重要依据。

基础结构示例：

{
  "pages": [
    "pages/index/index",
    "pages/logs/logs"
  ],
  "window": {
    "backgroundTextStyle": "light",
    "navigationBarBackgroundColor": "#fff",
    "navigationBarTitleText": "WeChat",
    "navigationBarTextStyle": "black"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#3cc51f",
    "borderStyle": "black",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "iconPath": "images/home.png",
        "selectedIconPath": "images/home-active.png",
        "text": "首页"
      },
      {
        "pagePath": "pages/logs/logs",
        "iconPath": "images/logs.png",
        "selectedIconPath": "images/logs-active.png",
        "text": "日志"
      }
    ]
  },
  "style": "v2",
  "sitemapLocation": "sitemap.json"
}

核心配置项详解

project.json 的配置项可分为全局配置、窗口配置、导航配置、TabBar配置、编译配置等几大类,以下逐一展开说明。

pages：页面路由配置

pages 是 project.json 中最核心的配置项，用于注册小程序的所有页面路径，框架会根据该配置自动生成页面路由，并在启动时加载首页（pages 数组的第一项）。

• 配置格式：字符串数组，每个元素表示一个页面的路径（从项目根目录算起，需包含文件名和扩展名）。
• 示例：

  "pages": [
    "pages/index/index",     // 首页
    "pages/user/user",       // 用户页
    "pages/detail/detail"    // 详情页
  ]

• 动态页面处理：若存在动态页面（如根据参数加载不同内容），需提前在 pages 中注册所有可能的路径（如 pages/detail/detail），无需为每个参数值单独注册。

window：全局窗口样式配置

window 用于配置小程序的全局窗口表现，包括导航栏、背景色、文字样式等，影响所有页面的默认展示效果。

• 示例：

  "window": {
    "navigationBarTitleText": "我的小程序",
    "navigationBarBackgroundColor": "#ff6b6b",
    "navigationBarTextStyle": "white",
    "enablePullDownRefresh": true,
    "onReachBottomDistance": 100
  }

tabBar：底部标签栏配置

tabBar 用于配置小程序的底部标签栏，方便用户快速切换核心页面，一个 tabBar 最多包含 5 个标签，最少 2 个。

标签对象（list 内部）：
| 配置项 | 类型 | 说明 | |--------|------|------| | pagePath | String | 标签对应的页面路径（必须在 pages 中注册） | | text | String | 标签名称（最多 4 个字符） | | iconPath | String | 未选中时的图标路径（尺寸建议 81px×81px） | | selectedIconPath | String | 选中时的图标路径（尺寸建议 81px×81px） |

• 示例：

  "tabBar": {
    "color": "#999999",
    "selectedColor": "#ff6b6b",
    "borderStyle": "white",
    "backgroundColor": "#f8f8f8",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "images/tab-home.png",
        "selectedIconPath": "images/tab-home-active.png"
      },
      {
        "pagePath": "pages/logs/logs",
        "text": "日志",
        "iconPath": "images/tab-logs.png",
        "selectedIconPath": "images/tab-logs-active.png"
      }
    ]
  }

style：样式兼容配置

style 用于指定小程序的样式版本，影响组件的默认样式表现，目前支持 v1（旧版样式）和 v2（新版样式，默认）。

• 推荐配置：

  "style": "v2"

• 作用：开启 v2 样式后，组件默认使用更现代的设计（如按钮圆角、输入框边距等），且会废弃部分旧样式属性（如 button::after 的边框样式）。

sitemapLocation：站点地图配置

sitemapLocation 用于指定小程序站点地图文件的路径，帮助微信搜索收录小程序页面，默认值为 "sitemap.json"（需手动创建文件）。

• 示例：

  "sitemapLocation": "sitemap.json"

• sitemap.json 作用：通过配置 rules 字段，声明哪些页面允许被索引、哪些页面禁止被索引，提升小程序在微信搜索中的曝光率。

condition：编译条件配置

condition 用于配置开发环境的编译条件，可在开发者工具中快速预览特定页面或场景（如分享、弹窗）。

• 配置字段：

  • current：当前选中的编译条件（如页面路径、事件触发）。
  • list：编译条件列表，每个元素是一个条件对象。

• 示例：

  "condition": {
    "current": 0,
    "list": [
      {
        "name": "首页预览",
        "path": "pages/index/index",
        "query": "id=123"
      },
      {
        "name": "分享预览",
        "path": "pages/detail/detail",
        "query": "share=true"
      }
    ]
  }

• 作用：开发时无需手动切换页面，通过 condition 可快速跳转到指定页面并携带参数，提升调试效率。

进阶配置：多环境与自定义编译

多环境配置（开发/生产/测试）

通过 project.json 可结合小程序的环境变量（env）实现多环境配置（如开发、测试、生产环境的 API 地址不同）。

• 步骤：
  1. 在项目根目录创建 .env 文件（如 .env.development、.env.production），定义环境变量：

     # .env.development
     BASE_API=http