简介
本文件面向运维与开发者，提供 DouPHP 小程序的构建、配置管理、发布与部署全流程操作指南。内容覆盖代码编译与资源打包、版本管理、环境配置差异、线上发布步骤、监控与日志方案，以及发布后的维护与更新策略。文档基于仓库内现有实现进行说明，确保可执行性与一致性。
项目结构
DouPHP 的小程序能力由“后端管理端 + 小程序源码包”两部分组成：
- 后端管理端：提供小程序代码包安装、启用、同步配置、系统参数设置等能力。
- 小程序源码包：位于 miniprogram 目录下，包含 default 与 company 两套模板，各自拥有独立的 project.config.json、app.json 与业务页面。
graph TB
A["后台控制器<br/>MiniprogramController"] --> B["服务层<br/>MiniprogramService"]
B --> C["云端门面<br/>Cloud"]
C --> D["小程序代码目录<br/>miniprogram/{slug}"]
D --> E["项目配置<br/>project.config.json"]
D --> F["应用配置<br/>app.json"]
G["系统常量配置<br/>config/system.php"] --> F
H["全局配置<br/>config/config.php"] --> D核心组件
- 后台控制器 MiniprogramController：提供小程序列表、安装、启用、同步配置、发布页入口等接口。
- 服务层 MiniprogramService：负责代码路径定义、代码包扫描、启用/删除包、系统参数初始化与保存、配置同步触发。
- 云端门面 Cloud：聚合云端状态与小程序配置同步能力，内部委托具体服务完成 app.json、路由表与运行时配置的生成与写入。
- 配置体系：
- 全局配置 config.php：定义数据库、站点标识、小程序目录常量、调试开关等。
- 系统常量 config/system.php：声明小程序内置模块、额外页面、不参与生成的模块等。
- 小程序工程配置 project.config.json：编译器选项、忽略/包含规则、TypeScript 编译开关等。
- 小程序应用配置 app.json：页面注册、窗口样式、TabBar、sitemapLocation 等。
- 模板级 setting.php：图片尺寸建议等模板相关提示。
架构总览
下图展示了从后台到小程序代码包的配置同步流程，包括代码包发现、启用切换、配置重写与云侧状态记录。
sequenceDiagram
participant Admin as "后台界面"
participant Ctrl as "MiniprogramController"
participant Svc as "MiniprogramService"
participant Cloud as "Cloud 门面"
participant FS as "文件系统"
participant MP as "小程序代码包"
Admin->>Ctrl : 访问小程序列表/安装/启用/同步
Ctrl->>Svc : listMiniprogramCodeSlugs() / enablePackage(slug) / syncMiniprogramConfig()
Svc->>FS : 读取/创建 MINIPROGRAM_CODE_PATH
Svc->>Cloud : changeMiniprogramConfigFile(domain?)
Cloud-->>MP : 重写 app.json/pages/tabBar/路由表/runtime
Svc->>Cloud : changeUpdateDate(type, cloudId, del?, mode?)
Cloud-->>Admin : 返回成功/失败状态详细组件分析
小程序构建与打包
- 构建工具链：小程序工程使用微信开发者工具进行编译与打包；project.config.json 中启用了 TypeScript 编译插件与多项压缩优化选项。
- 忽略/包含规则：packOptions 中 ignore 排除敏感或动态配置文件（如 config/setting.php），避免将服务端配置打入小程序包。
- 编译产物：由微信开发者工具在本地生成小程序包，随后通过平台上传至微信审核与发布。
flowchart TD
Start(["开始构建"]) --> CheckCfg["检查 project.config.json<br/>compiler/plugins 与 packOptions"]
CheckCfg --> CompileTS["启用 TypeScript 编译"]
CompileTS --> Optimize["开启 WXML/WXSS 压缩与 SourceMap"]
Optimize --> IgnoreCfg["忽略敏感配置如 setting.php"]
IgnoreCfg --> Build["微信开发者工具打包"]
Build --> Output["输出小程序包"]
Output --> End(["结束"])配置管理
- 全局配置（config.php）：定义数据库连接、站点标识、小程序目录常量、应用密钥、调试开关等。
- 系统常量（config/system.php）：声明小程序内置模块、额外页面、不参与 app.json 生成的模块等，影响小程序页面注册与路由。
- 小程序工程配置（project.config.json）：控制编译器行为、忽略规则、库版本、AppID 等。
- 小程序应用配置（app.json）：声明 pages、window、tabBar、usingComponents、sitemapLocation 等。
- 模板级设置（setting.php）：提供图片尺寸建议等模板相关提示。
graph LR
CFG["config.php"] --> CONST["MINIPROGRAM_DIR 常量"]
SYS["config/system.php"] --> APPJSON["app.json 页面/模块注册"]
PCFG["project.config.json"] --> BUILD["编译/打包行为"]
SET["setting.php"] --> UI["模板显示建议"]版本管理与代码包切换
- 代码包目录：MINIPROGRAM_CODE_PATH 指向 miniprogram 目录，支持多 slug 子目录作为不同代码包。
- 包列表与元信息：通过解析 app.wxss 头部注释获取包元数据，并自动寻找截图资源。
- 启用包：enablePackage 会将 default 模板复制到目标 slug 目录，并更新 site.miniprogram_code 为当前启用包。
- 删除包：deletePackage 会删除对应目录并更新云侧更新时间。
flowchart TD
A["选择 slug"] --> B{"slug 是否存在"}
B -- 否 --> X["返回错误"]
B -- 是 --> C{"是否为 default"}
C -- 是 --> D["直接启用"]
C -- 否 --> E["复制 default -> slug"]
E --> F["更新 site.miniprogram_code"]
D --> F
F --> G["生效于后续配置同步"]发布流程（后台驱动的配置同步与云侧状态）
- 同步配置：调用 syncMiniprogramConfig，内部通过 Cloud.changeMiniprogramConfigFile 重写小程序 app.json、路由表与运行时配置。
- 云侧状态：在删除包等操作时，通过 Cloud.changeUpdateDate 更新云侧记录的最近更新时间，便于云端检测变更。
- 发布入口：release 方法提供发布页视图，结合 MINIPROGRAM_DIR 常量用于前端展示与引导。
sequenceDiagram
participant U as "管理员"
participant C as "MiniprogramController"
participant S as "MiniprogramService"
participant CL as "Cloud"
U->>C : 点击“同步配置”
C->>S : syncMiniprogramConfig(domain?)
S->>CL : changeMiniprogramConfigFile(domain?)
CL-->>U : 返回同步结果
U->>C : 进入“发布”页
C-->>U : 渲染发布页含 MINIPROGRAM_DIR环境变量与环境差异
- 全局调试开关：config.php 中的 DOU_DEBUG 控制调试模式。
- 站点与域名：小程序系统参数中包含 miniprogram_domain，用于配置同步时回退到 ROOT_URL。
- 环境差异建议：
- 开发环境：开启调试，关闭严格校验，便于快速迭代。
- 测试环境：关闭调试，保留必要日志，模拟生产行为。
- 生产环境：关闭调试，启用最小化与 SourceMap 按需上传，严格域名与权限校验。
依赖关系分析
- 控制器依赖服务：MiniprogramController 依赖 MiniprogramService 处理业务逻辑。
- 服务依赖云端门面：MiniprogramService 通过 Cloud 门面调用底层安装/更新服务，完成小程序配置重写与云侧状态更新。
- 配置依赖：小程序 app.json 的页面与模块注册受 system.php 的系统常量影响；project.config.json 决定编译与打包行为。
classDiagram
class MiniprogramController {
+index()
+sync()
+release()
+install(request)
+enable(request)
}
class MiniprogramService {
+defineCodePath()
+listMiniprogramCodeSlugs()
+buildMiniprogramListData()
+enablePackage(slug)
+deletePackage(slug)
+syncMiniprogramConfig(domain)
}
class Cloud {
+changeMiniprogramConfigFile(domain)
+changeUpdateDate(type, cloudId, del, mode)
}
MiniprogramController --> MiniprogramService : "调用"
MiniprogramService --> Cloud : "调用"性能考虑
- 编译与打包：启用 TypeScript 编译与 WXML/WXSS 压缩可减少包体积；合理使用 packOptions.ignore 避免冗余文件进入包体。
- 配置同步：仅在必要时触发配置重写，减少不必要的 I/O 与缓存失效。
- 资源加载：遵循 setting.php 的图片尺寸建议，避免过大图片影响首屏加载。
- 调试与日志：生产环境关闭调试，按需开启日志采集与性能埋点，避免过多日志影响性能。
故障排查指南
- 无法列出代码包：确认 MINIPROGRAM_CODE_PATH 存在且可读；检查 FileHelper::getSubdirs 是否能正确扫描。
- 启用包无效：检查 enablePackage 是否成功复制 default 模板并更新 site.miniprogram_code；确认后续配置同步已执行。
- 配置同步失败：核对 Cloud.changeMiniprogramConfigFile 的 domain 参数与 ROOT_URL 回退逻辑；检查小程序 app.json 是否被正确重写。
- 删除包后仍生效：确认 deletePackage 已删除目录并更新云侧更新时间；必要时清理缓存并重载后台。
结论
DouPHP 小程序的发布与部署围绕“代码包管理 + 配置同步 + 云侧状态”展开。通过后台控制器与服务层协作，实现对多代码包的安装、启用、删除与配置重写；借助 project.config.json 与 app.json 控制编译与运行行为。建议在开发、测试、生产三套环境中分别配置调试开关与域名策略，并结合云侧状态记录实现版本追踪与回滚能力。
附录：操作清单
- 构建与打包
- 在微信开发者工具中打开小程序工程（default 或 company）。
- 确认 project.config.json 的 compiler/plugins 与 packOptions 配置。
- 执行编译与打包，生成小程序包。
- 配置管理
- 在后台“小程序系统参数”中设置 miniprogram_appid、miniprogram_appsecret、miniprogram_pay_mch_id、miniprogram_pay_key、miniprogram_domain。
- 如需切换主题包，进入“小程序列表”启用目标 slug。
- 点击“同步配置”以重写小程序 app.json、路由表与运行时配置。
- 发布流程
- 使用微信开发者工具上传小程序包至微信公众平台。
- 提交版本审核，通过后发布上线。
- 发布后在后台查看云侧更新时间与状态。
- 环境与差异
- 开发：开启 DOU_DEBUG，关闭严格校验。
- 测试：关闭 DOU_DEBUG，保留必要日志。
- 生产：关闭 DOU_DEBUG，启用最小化与 SourceMap 按需上传。
- 监控与日志
- 在小程序端接入错误上报与性能埋点（如网络耗时、页面跳转耗时）。
- 在后端集中收集错误日志与用户行为事件，便于问题定位与分析。
- 维护与更新
- 定期备份小程序代码包与配置。
- 采用灰度发布策略，先小范围验证再全量发布。
- 建立回滚预案，出现严重问题时快速回退至上一稳定版本。