微信小程序配置文件详解：project.config.json与project.private.config.json

微信小程序项目中，project.config.json 和 project.private.config.json 是两个非常重要的配置文件：

---

一、文件作用说明

文件名	类型	说明
project.config.json	公共配置文件	包含项目的基本配置信息，如项目名称、appid、编译设置等，通常提交到版本控制中
project.private.config.json	私有配置文件（敏感）	存储本地开发路径、开发者工具个性化设置等，不应提交到 Git 等版本控制系统中

---

二、project.config.json 配置详解

完整示例（带详细注释）

{
  // 小程序项目名称（显示在开发者工具标题栏）
  "projectname": "我的小程序",

  // 小程序 AppID，唯一标识符
  "appid": "wx8888888888888888",

  // 项目类型：miniProgram（小程序）/ plugin（插件）
  "projecttype": "miniProgram",

  // 项目语言：js / ts / vue / react 等
  "scriptType": "js",

  // 样式语言：css / sass / less / stylus
  "style": "css",

  // 是否启用 ESLint 检查
  "eslintEnable": false,

  // 是否启用 TypeScript 支持
  "useTypescript": false,

  // 是否使用 npm 构建（需配合 npm 构建命令）
  "useCustomCompiler": true,

  // 编译构建相关配置
  "compilerOptions": {
    // 输出目录（相对于项目根目录）
    "outputDir": "dist",
    // 是否压缩输出代码
    "minify": true,
    // 是否启用 source map
    "sourceMap": false
  },

  // 插件配置（仅适用于插件项目）
  "plugins": {},

  // 项目源码目录（默认为当前目录）
  "srcPath": "./",

  // 工具插件配置
  "tools": {
    "minify": {
      "enable": true
    }
  },

  // 项目运行时库版本号（由开发者工具自动生成）
  "libVersion": "2.24.7",

  // 是否启用热更新（Hot Reload）
  "hotReload": true,

  // 开发服务器端口号
  "devServerPort": 10086,

  // 项目描述信息
  "description": "这是一个基础的小程序项目"
}

---

三、project.private.config.json 配置详解

该文件包含本地私有配置，不同开发者之间可能不同。

完整示例（带详细注释）

{
  // 当前用户本地开发工具的窗口布局配置
  "windowState": {
    "width": 1200,
    "height": 800,
    "x": 100,
    "y": 50
  },

  // 最近一次打开的页面路径（用于快速恢复）
  "lastVisitedPage": "pages/index/index",

  // 是否启用自动刷新预览
  "autoRefresh": true,

  // 当前项目使用的调试器类型
  "debuggerType": "wechat",

  // 本地开发路径（每个开发者机器不同）
  "localPath": "/Users/username/projects/my-miniprogram",

  // 远程仓库地址（可选）
  "remoteRepo": "git@github.com:username/my-miniprogram.git",

  // 用户本地偏好设置
  "preferences": {
    // 主题颜色：light / dark
    "theme": "light",
    // 是否启用自动保存
    "autoSave": true,
    // 是否启用代码折叠
    "codeFolding": true
  }
}

⚠️ 注意：此文件通常不在版本控制中提交，建议添加到 .gitignore 中。

---

四、关键配置项对比表格

配置项	所属文件	可选值	说明
projectname	project.config.json	String	项目名称，显示在开发者工具标题栏
appid	project.config.json	String	小程序唯一标识 ID
projecttype	project.config.json	miniProgram / plugin	项目类型
scriptType	project.config.json	js / ts / vue / react	使用的语言类型
style	project.config.json	css / sass / less / stylus	样式语言
eslintEnable	project.config.json	Boolean	是否启用 ESLint
useTypescript	project.config.json	Boolean	是否使用 TypeScript
useCustomCompiler	project.config.json	Boolean	是否使用自定义编译器（npm 构建）
outputDir	project.config.json	String	编译输出目录
minify	project.config.json	Boolean	是否压缩代码
sourceMap	project.config.json	Boolean	是否生成 source map
plugins	project.config.json	Object	插件项目专用配置
srcPath	project.config.json	String	项目源码目录
tools	project.config.json	Object	工具插件配置
libVersion	project.config.json	String	使用的基础库版本
hotReload	project.config.json	Boolean	是否启用热更新
devServerPort	project.config.json	Number	开发服务器端口
description	project.config.json	String	项目描述
windowState	project.private.config.json	Object	开发者工具窗口位置和大小
lastVisitedPage	project.private.config.json	String	上次访问的页面路径
autoRefresh	project.private.config.json	Boolean	是否自动刷新预览
debuggerType	project.private.config.json	String	调试器类型
localPath	project.private.config.json	String	本地开发路径
remoteRepo	project.private.config.json	String	远程仓库地址（可选）
preferences.theme	project.private.config.json	light / dark	主题模式
preferences.autoSave	project.private.config.json	Boolean	是否启用自动保存
preferences.codeFolding	project.private.config.json	Boolean	是否启用代码折叠

---

五、注意事项与最佳实践

• ✅ 不要将 project.private.config.json 提交到 Git，防止泄露个人配置。
• ✅ 在团队协作中，确保所有成员的 project.config.json 保持一致。
• ✅ 如果使用 TypeScript 或 Vue 等框架，务必正确设置 scriptType。
• ✅ useCustomCompiler 设置为 true 时，需配置 npm 构建脚本。
• ✅ minify 和 sourceMap 建议在上线前开启压缩并关闭 source map。
• ✅ libVersion 应保持最新，以获得更好的兼容性和功能支持。

---

六、总结

文件名	是否应提交	是否敏感	主要用途
project.config.json	✅ 是	❌ 否	项目公共配置（AppID、编译设置等）
project.private.config.json	❌ 否	✅ 是	本地开发环境配置（窗口大小、路径等）

通过合理配置这两个文件，可以有效管理项目的全局设置与本地开发偏好，提升开发效率与团队协作一致性。如果你需要我帮你生成一份标准模板或解释某个字段的作用，也可以随时告诉我~