From 09e410df00e3bbee4e8d3b34b0875c671168ad41 Mon Sep 17 00:00:00 2001 From: ZF sun <34314687@qq.com> Date: Sat, 24 Jan 2026 17:40:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0readme=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E7=BB=93=E6=9E=84=E5=92=8C=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 重构readme文档结构，使用更清晰的markdown格式和emoji图标 添加详细的开发调试说明和发布流程 补充构建脚本说明和版本历史记录 --- readme.md | 232 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 133 insertions(+), 99 deletions(-) diff --git a/readme.md b/readme.md index eeb484c..7a29950 100644 --- a/readme.md +++ b/readme.md @@ -1,112 +1,146 @@ # 小程序及快应用前端源码 +## 1. 📋 项目说明 -## 项目说明 +该项目基于 **uni-app** 开发构建，请使用 [HBuilderX](https://www.dcloud.io/hbuilderx.html) 进行代码开发及构建发布。 -该项目基于 uniapp 开发构建，请使用(HBuilderX)[https://www.dcloud.io/hbuilderx.html] 进行代码开发及构建发布。 +## 2. 🛠️ 开发说明 -## 开发说明 +- 源码基于 **Vue2** 版本 +- SCSS 采用 **dart-sass** 进行编译输出 - 源码基于Vue2版本，scss采用dart-sass进行编译输出。 +## 3. 🔧 开发调试说明 +### 3.1 注意事项 -## 开发调试说明 +- 应用访问等关键参数的配置来源于 `./common/js/config.js` -### 注意点 +### 3.2 本地调试 -应用访问等关键参数的配置来源于 `./common/js/config.js` - - - - - -## 发布说明 - -### 小程序发布 - - - -#### 基本操作步骤：（通用版/定制化版） - -#### 【前置准备】 -1. 在项目根目录打开终端安装依赖“npm install”（已有依赖可跳过此步骤）。 -#### 【发布构建】 -2. 使用HBuilderX打开项目； -3. 选择菜单栏「发行」 → 「小程序-微信」→ 「发行」，等待构建完成。（⚠️注：底部控制台弹出"请在微信小程序开发者工具中点击上传"后再执行下一步）； -4. 打开资源管理器→项目根目录，右键选择「在终端中打开」，执行"npm run mp-weixin"命令并回车； - -5. 找到项目根目录 /unpackage/dist/build 下生成的 mp-weixin 压缩包 - -💡例如：mp-weixin-2026-01-23-1769152056146.zip;同时该目录下会生成未压缩的 mp-weixin 目录。 - -#### 【验证与重命名】 -6. 打开该目录下同时生成未压缩的 mp-weixin 目录，找到site.js文件，将文件内的uniacid值改为当前客户编号（如：2812）并保存； -7. 打开微信开发者工具，导入「mp-weixin」目录，点击「编译」，在开发者工具控制台验证有无报错，以及能否返回对应客户的业务数据； - -8. 确保无误后将生成的mp-weixin的压缩包重命名，格式为：定制化-客户编号-域名-mp-weixin-当前日期-生成编号.zip。 -***（📌通用版无需重命名）*** - -💡例如：custom-2812-xcx.aigc-quickapp.com-mp-weixin-2026-01-22-1769152056146.zip - -🚫压缩包命名禁止包含 / \ : * ? " < > | 等特殊字符。 - - -#### 【交付与最终发布】🔍🔍 -9. 将重命名后的文件发送给技术人员； ***（📌通用版直接将生成的 mp-weixin 压缩包直接发送给技术人员）*** - -10. 技术人员操作：解压压缩包 → 确认site.js中的uniacid为客户编号 → 用微信开发者工具导入解压后的代码目录 → 编译验证无误后 → 上传发布。 - - - - - - -### 快应用发布 - - -#### 基本操作（通用版/定制化版） - - - -#### 【发布构建】 -1. 使用HBuilderX打开项目； - -2. 打开项目根目录的manifest.json文件，切换至可视化配置界面：依次点击「Web 配置」→「运行的基础配置」，修改路径中的客户编号；***（📌通用版保留原有/hwappx/common/）*** - -💡例如：/hwappx/2811/，其中2811为定制化版客户编号； - -3. 选择菜单栏「发行」 → 「自定义发行」 →「H5-xcx.aigc-quickapp.com」，先修改以下配置： -网站标题：快应用 -网站域名：当前客户域名（示例：xcx.aigc-quickapp.com） -确认后点击「发行」等待构建完成。 - -⚠️注：底部控制台弹出“项目 lucky_shop 导出Web成功，路径为：D:\项目文件\项目根目录\unpackage\dist\build\web”后再执行下一步 - -💡例如：项目 lucky_shop 导出Web成功，路径为：D:\0.项目源码\lucky_shop\unpackage\dist\build\web - -4. 按控制台提示的路径找到web目录，将该目录下所有文件手动打包成一个.zip压缩包（仅打包文件，不包含外层web目录）； - -#### 【重命名】 -5. 按版本类型规范重命名压缩包： - -📌通用版：hwappx-common-域名-时间.zip -例如： hwappx-common-xcx.aigc-quickapp.com-2026-01-24.zip - -📌定制化：客户名称-定制化---hwappx-客户编号-域名-时间.zip - 例如：POCT检测分析平台-定制化---hwappx-2811-xcx.aigc-quickapp.com-2026-01-24.zip - -🚫压缩包命名禁止包含 / \ : * ? " < > | 等特殊字符 - -#### 【交付与最终发布】🔍🔍 -6. 将重命名后的压缩包发送给运维人员； - -7. 运维人员操作： - -① 解压压缩包； - -② 打开快应用开发者工具，导入解压后的代码目录； - -③ 验证代码无报错后，执行上传发布操作。 +`.local.config.js.example` 是本地调试配置示例。 + +拷贝 `.local.config.js.example` 为 `.local.config.js` 文件，默认开发调试模式会自动加载该文件 + +--- + +## 4. 📦 发布说明 + +### 4.1 小程序发布 + +#### 4.1.1 基本操作步骤（通用版/定制化版） + +##### 4.1.1.1 【前置准备】 +1. 在项目根目录打开终端安装依赖： + ```bash + npm install + ``` + *已有依赖可跳过此步骤* + +##### 4.1.1.2 【发布构建】 +1. 使用 HBuilderX 打开项目 +2. 选择菜单栏「发行」 → 「小程序-微信」→ 「发行」，等待构建完成 + ⚠️ **注意**：底部控制台弹出"请在微信小程序开发者工具中点击上传"后再执行下一步 +3. 打开资源管理器→项目根目录，右键选择「在终端中打开」，执行命令： + ```bash + npm run mp-weixin + ``` +4. 找到项目根目录 `/unpackage/dist/build` 下生成的 mp-weixin 压缩包 + 💡 **示例**：`mp-weixin-2026-01-23-1769152056146.zip` + *同时该目录下会生成未压缩的 `mp-weixin` 目录* + +##### 4.1.1.3 【验证与重命名】 +1. 打开未压缩的 `mp-weixin` 目录，找到 `site.js` 文件，将文件内的 `uniacid` 值改为当前客户编号（如：2812）并保存 +2. 打开微信开发者工具，导入「mp-weixin」目录，点击「编译」，在开发者工具控制台验证有无报错，以及能否返回对应客户的业务数据 +3. 确保无误后将生成的 mp-weixin 压缩包重命名 + - **定制化版**格式：`定制化-客户编号-域名-mp-weixin-当前日期-生成编号.zip` + - **通用版**无需重命名 + + 💡 **示例**：`custom-2812-xcx.aigc-quickapp.com-mp-weixin-2026-01-22-1769152056146.zip` + + 🚫 **禁止**：压缩包命名禁止包含 `/ \ : * ? " < > |` 等特殊字符 + +##### 4.1.1.4 【交付与最终发布】🔍 +1. 将重命名后的文件发送给技术人员 + *📌通用版直接将生成的 mp-weixin 压缩包发送给技术人员* +2. **技术人员操作流程**： + - 解压压缩包 + - 确认 `site.js` 中的 `uniacid` 为客户编号 + - 用微信开发者工具导入解压后的代码目录 + - 编译验证无误后，上传发布 + +--- + +### 4.2 快应用发布 + +#### 4.2.1 基本操作（通用版/定制化版） + +##### 4.2.1.1 【发布构建】 +1. 使用 HBuilderX 打开项目 +2. 打开项目根目录的 `manifest.json` 文件，切换至可视化配置界面： + 1. 依次点击「Web 配置」→「运行的基础配置」 + 2. 修改路径中的客户编号 + 3. 📌 **通用版**保留原有 `/hwappx/common/` + + 💡 **示例**：`/hwappx/2811/`，其中 2811 为定制化版客户编号 + +3. 选择菜单栏「发行」 → 「自定义发行」 →「H5-xcx.aigc-quickapp.com」，修改以下配置： + 1. **网站标题**：快应用 + 2. **网站域名**：当前客户域名（示例：xcx.aigc-quickapp.com） + 3. 确认后点击「发行」等待构建完成 + + ⚠️ **注意**：底部控制台弹出“项目 lucky_shop 导出Web成功，路径为：D:\项目文件\项目根目录\unpackage\dist\build\web”后再执行下一步 + 💡 **示例**：`项目 lucky_shop 导出Web成功，路径为：D:\0.项目源码\lucky_shop\unpackage\dist\build\web` + +4. 按控制台提示的路径找到 `web` 目录，将该目录下所有文件手动打包成一个 `.zip` 压缩包 + *仅打包文件，不包含外层 web 目录* + +##### 4.2.1.2 【重命名】 +1. 按版本类型规范重命名压缩包： + - **通用版**：`hwappx-common-域名-时间.zip` + 💡 **示例**：`hwappx-common-xcx.aigc-quickapp.com-2026-01-24.zip` + + - **定制化版**：`客户名称-定制化---hwappx-客户编号-域名-时间.zip` + 💡 **示例**：`POCT检测分析平台-定制化---hwappx-2811-xcx.aigc-quickapp.com-2026-01-24.zip` + + 🚫 **禁止**：压缩包命名禁止包含 `/ \ : * ? " < > |` 等特殊字符 + +##### 4.2.1.3 【交付与最终发布】🔍 +1. 将重命名后的压缩包发送给运维人员 +2. **运维人员操作流程**： + 1. 解压压缩包 + 2. 打开快应用开发者工具，导入解压后的代码目录 + 3. 验证代码无报错后，执行上传发布操作 + +--- + +## 5. 📝 构建脚本说明 + +### 5.1 可用的 npm 脚本命令 + +| 命令 | 说明 | +|------|------| +| `npm run mp-weixin` | 默认构建（production模式，包含ZIP文件） | +| `npm run mp-weixin:patch` | 只打补丁（production模式，不创建ZIP文件） | +| `npm run mp-weixin:dev` | 开发模式构建（development模式，包含ZIP文件） | +| `npm run mp-weixin:dev:patch` | 只打补丁（development模式，不创建ZIP文件） | + +### 5.2 构建脚本功能 + +- 复制 `project.config.json` 和 `project.private.config.json` 文件到构建目录 +- 复制 `site.js` 文件到构建目录 +- 在 `vendor.js` 文件开头追加 `import site from "../site.js";` 语句 +- 支持创建构建结果的 ZIP 压缩包 +- 自动打开 ZIP 文件所在目录 + +--- + +## 6. 🔄 版本历史 + +### 6.1 v1.3 +- 修复微信小程序构建脚本，支持复制 `project.config.json` 和 `project.private.config.json` 文件 +- 增强构建脚本功能，添加命令行参数支持 +- 在 `package.json` 中添加相关 npm 脚本命令 +- 优化脚本执行逻辑，提高可靠性和灵活性