@dd-code/uni-tools 1.0.12 → 1.0.14

package/README.md

@@ -2,16 +2,17 @@
 
 `@dd-code/uni-tools` 是一个针对 UniApp 的微信小程序（mp-weixin）模块化解决方案与工具集，目标是让「主应用 + 多子应用（分包）」的开发、联调与构建更顺畅、更自动化。
 
-## 项目简介
-- 面向微信小程序的模块化架构：主应用负责壳与公共能力，子应用以分包形式集成。
-- 自动管理主/子应用的 `app.json`、`pages.json` 等配置合并，减少人工维护成本。
-- 开发态具备文件监听、自动同步与应用间通信能力，提升联调效率。
-- 提供统一 CLI 命令，简化拉取子应用仓库、开发、构建等流程。
+## 特性
+- 主/子应用模块化：主应用负责壳与公共能力，子应用以分包形式接入。
+- 配置自动合并：自动汇总各子应用的 `pages.json` 并生成最终 `app.json`。
+- 开发态联调：监听子应用构建输出并同步至主应用分包目录，支持 WS 通知。
+- 运行时暴露：通过 `@dd-code/runtime` 统一导出公共模块（如 `store/index.js`）。
+- 一体化 CLI：拉取子应用仓库、启动开发、执行构建，开箱即用。
 
 ## 有哪些命令
-- `npx uni-tools fetch`：交互式拉取已配置的子应用仓库到本地工作空间（packages/uni-tools/src/cli.ts:20）。
-- `npx uni-tools serve -p mp-weixin --mode development`：启动开发态；自动识别主/子应用并启动对应插件逻辑（packages/uni-tools/src/cli.ts:14）。
-- `npx uni-tools build -p mp-weixin --mode production`：执行生产构建，按模块化架构输出主应用及分包（packages/uni-tools/src/cli.ts:52）。
+- `npx uni-tools fetch`：交互式拉取子应用仓库到本地（packages/uni-tools/src/cli.ts:20）。
+- `npx uni-tools serve -p mp-weixin --mode development`：启动开发态，识别主/子应用并启用对应插件（packages/uni-tools/src/cli.ts:14）。
+- `npx uni-tools build -p mp-weixin --mode production`：生产构建输出主应用与分包（packages/uni-tools/src/cli.ts:52）。
 - 可选参数：
   - `-p <platform>`：平台，默认 `h5`，支持 `mp-weixin`。
   - `--mode <mode>`：模式，默认 `development`。
@@ -25,18 +26,29 @@
 - 生产构建可控：按环境与模式输出稳定的主应用与分包结构，避免配置漂移与遗漏。
 - 仓库管理简化：通过交互命令拉取/更新子应用仓库，快速搭建本地联调环境。
 
-## 大致的实现逻辑
-- 插件入口与平台分发（packages/uni-tools/src/plugins/mp-weixin.ts:8-22）
-  - 检测当前平台是否为 `mp-weixin`，是则注册一组 Vite 插件：环境初始化、资源处理、Manifest 管理、主应用逻辑等。
-- Manifest 管理与 `app.json` 合并（packages/uni-tools/src/plugins/modules/mp-weixin/plugins/main-app.ts:31-76, 105-119, 261-279）
-  - 读取各子应用的 `pages.json`，生成分包结构并合并到主应用的 `app.json`。
-  - 在 `closeBundle` 钩子中根据当前模式（开发/构建）与是否主应用，决定是否生成或更新最终的 `app.json`。
-- 开发态联调（packages/uni-tools/src/plugins/modules/mp-weixin/plugins/main-app.ts:121-156, 187-245）
-  - 主应用启动 WebSocket 服务，子应用作为客户端连接；
-  - 监听子应用构建输出目录变更（`DistWatcher`），变更时拷贝至主应用对应分包路径，并通过 WS 通知；
-  - 收到子应用变更通知后，主应用实时增量更新 `app.json` 中的对应分包页面配置。
-- 交互式拉取子应用仓库（packages/uni-tools/src/plugins/modules/mp-weixin/gitlib/index.ts）
-  - 使用交互框选择需要拉取的应用，自动将其下载/更新至本地指定目录，便于快速联调。
+## 架构与插件
+- 入口与平台分发：`packages/uni-tools/src/plugins/mp-weixin.ts:8-22`
+- 目录分层：`core/ + plugins/ + server/ + utils`，职责明确、低耦合
+  - `core`：运行时与 `app.json` 处理（如 `core/app-json.ts`、`core/runtime.ts`）
+  - `plugins`：Vite 插件（主应用、exposes 等）
+  - `server`：HTTP/WS 服务
+  - `utils`：通用工具（文件复制、下载等）
+- Manifest 管理与 `app.json` 合并：`packages/uni-tools/src/plugins/modules/mp-weixin/plugins/main-app.ts:31-76, 105-119, 261-279`
+  - 汇总子应用 `pages.json`，渲染为主应用分包配置并写入 `app.json`
+  - 写入采用内容比较，避免频繁重启与重复打包（`core/app-json.ts`）
+- 开发态联调：`packages/uni-tools/src/plugins/modules/mp-weixin/plugins/main-app.ts:121-156, 187-245`
+  - 主应用启动 WS 服务，子应用变更触发同步与增量更新
+  - 监听拷贝使用内容比较，避免无效触发（`utils/copy.ts`）
+
+## 运行时暴露（Runtime Exposes）
+- 目标：在任意页面通过 `@dd-code/runtime` 访问公共模块导出（如 `store/index.js`）
+- 使用方式：
+  - 在页面或模块中 `import { userStore } from '@dd-code/runtime'`
+  - 插件在打包阶段生成 `__mfe_runtime__.js` 于根目录，并将各处引用指向它
+- 实现要点：
+  - `load` 阶段生成占位引用，`generateBundle` 计算相对路径并替换（`packages/uni-tools/src/plugins/modules/mp-weixin/plugins/exposes.ts:91-109`）
+  - 所有 `@dd-code/runtime/*` 形式在 `resolveId` 阶段重定向到同一虚拟模块（保持单一产物）
+  - 可通过 `options.exposes` 扩展需要暴露的模块与导出
 
 ## 配置与环境变量
 - `mfe.json`（项目根目录，packages/uni-tools/src/config/const.ts:1）
@@ -70,18 +82,18 @@
 1. 安装依赖：
    - 使用你的包管理器安装 `@dd-code/uni-tools`。
 2. 在 `vite.config.ts` 中启用插件：
-   ```ts
-   import { defineConfig } from 'vite';
-   import uni from '@dcloudio/vite-plugin-uni';
-   import uniTools from '@dd-code/uni-tools';
-
-   export default defineConfig({
-     plugins: [
-       uni(),
-       uniTools()
-     ],
-   });
-   ```
+  ```ts
+  import { defineConfig } from 'vite';
+  import uni from '@dcloudio/vite-plugin-uni';
+  import uniTools from '@dd-code/uni-tools';
+
+  export default defineConfig({
+    plugins: [
+      uni(),
+      uniTools()
+    ],
+  });
+  ```
 3. 拉取子应用仓库：`npx uni-tools fetch`
 4. 启动开发：`npx uni-tools serve -p mp-weixin --mode development`
 5. 构建生产：`npx uni-tools build -p mp-weixin --mode production`
@@ -118,6 +130,11 @@
 - 子应用：分包形式接入，拥有独立 `pages.json` 与资源；构建输出由插件监听并同步。
 - Manifest 与分包配置生成：读取各子应用 `pages.json` 并渲染至主应用 `subPackages`（packages/uni-tools/src/plugins/modules/mp-weixin/plugins/main-app.ts:41-69）。
 
+## 常见问题
+- 端口被占用（`MFE_UNI_SERVE=true`）：HTTP/WS 服务具备幂等复用与端口探测，避免重复 `listen`（packages/uni-tools/src/plugins/modules/mp-weixin/server/http-server.ts）。
+- 开发态频繁重启/重复打包：写入 `app.json` 与文件拷贝均进行内容比较，仅在变更时写入（`core/app-json.ts`、`utils/copy.ts`）。
+- CLI 交互报错（inquirer 兼容）：已采用动态导入并移动到依赖，`npx` 下可正常使用（packages/uni-tools/src/plugins/modules/mp-weixin/gitlib/index.ts, packages/uni-tools/package.json）。
+
 ## 适用场景
 - 同一个小程序中承载多个业务模块/团队的功能分包，需要高效联调与统一发布。
 - 希望减少主/子应用配置的重复劳动与易错区域。
@@ -127,3 +144,54 @@
 - 开发态会根据 `mode`、`isRoot` 等状态决定是否启动 WS 服务与目录监听。
 - 请确保各子应用的 `pages.json` 合法且页面路径正确，便于自动合并。
  - 使用 `--b root` 时需先启动主应用的 HTTP 服务，以便子应用定位 `UNI_OUTPUT_DIR`（packages/uni-tools/src/plugins/modules/mp-weixin/output.ts:39-59）。
+
+## 接入指南（主/子应用）
+- 主应用配置
+  - 在 `vite.config.ts` 中启用插件并声明暴露映射：
+    ```ts
+    import { defineConfig } from 'vite';
+    import uni from '@dcloudio/vite-plugin-uni';
+    import uniTools from '@dd-code/uni-tools';
+
+    export default defineConfig({
+      plugins: [
+        uni(),
+        uniTools({
+          exposes: {
+            '.': '@/store/index',       // -> @dd-code/runtime
+            './axios': '@/axios/index', // -> @dd-code/runtime/axios
+          }
+        })
+      ],
+    });
+    ```
+  - 键规则：以 `.` 开头，`'.'` 表示根运行时入口，`'./xxx'` 表示子入口；值为主应用 `src/` 下模块路径，支持 `@/` 别名。
+- 子应用使用
+  - 在任意页面或模块中直接引用：
+    ```ts
+    import { userStore } from '@dd-code/runtime';
+    import { axios } from '@dd-code/runtime/axios';
+    ```
+  - 构建后，运行时文件输出为根目录 `__mfe_runtime__.js`，各子入口统一指向该文件的导出。
+- 运行与构建约定
+  - 主应用 `.env.development`：
+    ```
+    MFE_UNI_IS_ROOT=true
+    MFE_UNI_CODE=your-project-code
+    MFE_UNI_SERVE=true
+    UNI_PLATFORM=mp-weixin
+    ```
+  - 子应用 `.env.development`：
+    ```
+    MFE_UNI_IS_ROOT=false
+    MFE_UNI_CODE=your-project-code
+    MFE_APP_CODE=modules/your-app
+    MFE_UNI_SERVE=true
+    UNI_PLATFORM=mp-weixin
+    ```
+  - 开发：主/子应用分别执行 `npx uni-tools serve -p mp-weixin --mode development`，联调时主应用作为 WS 服务端，子应用作为客户端。
+  - 子应用直写主应用（不联调）：在主应用启动 HTTP 接口后执行 `npx uni-tools build -p mp-weixin --mode development --b root`，产物将按 `appCode` 写入主应用输出目录。
+- 验证与排错
+  - 构建后检查根目录是否存在 `__mfe_runtime__.js`。
+  - 若子入口未生效，确认主应用 `exposes` 配置键值对应正确，且导出为命名导出。
+  - 避免无效重启：确保 `app.json` 与文件拷贝只在内容变化时写入（已内置比较）。

package/dist/cli.js

@@ -3,6 +3,7 @@
 
 var shared = require('@dd-code/shared');
 var path = require('path');
+var fsExtra = require('fs-extra');
 var fs = require('fs');
 require('crypto');
 require('chokidar');
@@ -118,6 +119,17 @@ var loadViteConfig = function (mode) {
     var ROOT = process.cwd();
     return loadEnv(mode, ROOT, "MFE_");
 };
+var unlinkDeepDirOrFile = function (filePath) {
+    try {
+        if (fsExtra.pathExistsSync(filePath)) {
+            // 同步检查是否存在
+            fsExtra.removeSync(filePath); // 同步递归删除
+        }
+    }
+    catch (err) {
+        console.error("删除文件夹失败：", err);
+    }
+};
 
 // 项目 Git 子模块路径
 var PROJECT_GIT_PATH = "src/subtree";
@@ -253,6 +265,7 @@ var fetchAppsRepo = function () { return __awaiter(void 0, void 0, void 0, funct
                     if (repoUrl) {
                         var fileName = appCode.replace(/\//g, "_");
                         var dir = PROJECT_GIT_PATH;
+                        unlinkDeepDirOrFile(path.join(dir, fileName));
                         checkAndgenreDir(dir);
                         child_process.execSync("cd ".concat(dir, " && git clone ").concat(repoUrl, " ").concat(fileName), {
                             stdio: "inherit",

package/dist/cli.mjs.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { program } from '@dd-code/shared';
 import path from 'path';
+import fsExtra from 'fs-extra';
 import fs from 'fs';
 import 'crypto';
 import 'chokidar';
@@ -116,6 +117,17 @@ var loadViteConfig = function (mode) {
     var ROOT = process.cwd();
     return loadEnv(mode, ROOT, "MFE_");
 };
+var unlinkDeepDirOrFile = function (filePath) {
+    try {
+        if (fsExtra.pathExistsSync(filePath)) {
+            // 同步检查是否存在
+            fsExtra.removeSync(filePath); // 同步递归删除
+        }
+    }
+    catch (err) {
+        console.error("删除文件夹失败：", err);
+    }
+};
 
 // 项目 Git 子模块路径
 var PROJECT_GIT_PATH = "src/subtree";
@@ -251,6 +263,7 @@ var fetchAppsRepo = function () { return __awaiter(void 0, void 0, void 0, funct
                     if (repoUrl) {
                         var fileName = appCode.replace(/\//g, "_");
                         var dir = PROJECT_GIT_PATH;
+                        unlinkDeepDirOrFile(path.join(dir, fileName));
                         checkAndgenreDir(dir);
                         execSync("cd ".concat(dir, " && git clone ").concat(repoUrl, " ").concat(fileName), {
                             stdio: "inherit",

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+interface IUniConfigOptions {
+    exposes?: Record<string, string>;
+}
+
 /**
  * 创建 dd-code Uni 插件
  * @description 根据配置文件和传入选项创建插件实例
@@ -9,6 +13,6 @@
  *   customOption: 'value'
  * });
  */
-declare const _default: (options?: Record<string, any>) => any[];
+declare const _default: (options?: IUniConfigOptions) => any[];
 
 export { _default as default };