uniky 1.0.12 → 1.0.14

package/ARCHITECTURE.md

@@ -0,0 +1,233 @@
+# uniky 架构说明
+
+## 📦 混合发布模式
+
+从 v1.0.13 开始，`uniky` 采用**混合发布模式**，结合了源码发布和编译发布的优势。
+
+## 🗂️ 目录结构
+
+```
+uniky/
+├── src/
+│   ├── lib/              # TypeScript 源码（发布）
+│   │   ├── hook/
+│   │   │   ├── index.ts
+│   │   │   └── useParam.ts
+│   │   ├── http/
+│   │   │   ├── index.ts
+│   │   │   └── ky.ts
+│   │   └── index.ts
+│   │
+│   └── plugin/           # TypeScript 源码（编译）
+│       ├── index.ts
+│       ├── pages.defined.ts
+│       └── global.defined.ts
+│
+└── dist/
+    └── plugin/           # 编译后的 JS（发布）
+        ├── index.js
+        ├── index.d.ts
+        ├── pages.defined.js
+        ├── pages.defined.d.ts
+        ├── global.defined.js
+        └── global.defined.d.ts
+```
+
+## 📋 发布内容
+
+根据 `package.json` 的 `files` 字段：
+
+```json
+"files": [
+  "src/lib",      // ← lib 的 TS 源码
+  "dist/plugin",  // ← plugin 的编译 JS
+  "README.md"
+]
+```
+
+## 🎯 为什么采用混合模式？
+
+### lib 部分 - TypeScript 源码
+
+**原因**:
+- 在运行时被用户代码导入使用
+- 用户的 Vite 构建工具会处理 TS 编译
+- peerDependencies (vue, @dcloudio/uni-app) 由用户项目提供
+
+**优势**:
+- ✅ 避免依赖冲突 - 使用项目自己的依赖版本
+- ✅ 更好的类型支持 - 直接使用源码类型定义
+- ✅ 调试更方便 - 可以直接查看和调试源码
+- ✅ 体积更小 - 不包含重复的编译代码
+
+**使用示例**:
+```typescript
+// 在用户项目代码中
+import { useParam } from 'uniky';  // ← 导入 src/lib/hook/useParam.ts
+
+const params = useParam();
+```
+
+### plugin 部分 - 编译后的 JavaScript
+
+**原因**:
+- 在 Vite 配置文件中使用
+- Vite 加载配置文件时使用 esbuild
+- esbuild 在某些环境会尝试用 `require()` 加载模块
+- 编译为 JS 可以避免 ESM 兼容性问题
+
+**优势**:
+- ✅ 兼容性好 - 支持各种 Node.js 环境
+- ✅ 加载更快 - 无需实时编译
+- ✅ 类型完整 - 包含 `.d.ts` 类型定义
+
+**使用示例**:
+```typescript
+// vite.config.ts
+import { unikyPlugin } from 'uniky/plugin';  // ← 导入 dist/plugin/index.js
+
+export default defineConfig({
+  plugins: [
+    uni(),
+    ...unikyPlugin()  // ← 编译后的 JS 插件
+  ]
+});
+```
+
+## ⚙️ package.json 配置
+
+```json
+{
+  "type": "module",
+  "main": "./src/lib/index.ts",
+  "module": "./src/lib/index.ts",
+  "types": "./src/lib/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/lib/index.ts",
+      "import": "./src/lib/index.ts"
+    },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "import": "./dist/plugin/index.js"
+    }
+  }
+}
+```
+
+### 解读
+
+- **`"."`** - 主入口（lib）
+  - 指向 TypeScript 源码
+  - 用户项目构建工具会处理
+
+- **`"./plugin"`** - 插件入口
+  - 指向编译后的 JavaScript
+  - 包含类型定义文件
+
+## 🔧 构建配置
+
+### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "outDir": "./dist",
+    // ... 其他配置
+  },
+  "include": ["src/plugin/**/*"],      // ← 只编译 plugin
+  "exclude": ["src/lib/**/*"]          // ← 排除 lib
+}
+```
+
+### 构建脚本
+
+```json
+{
+  "scripts": {
+    "build": "tsc",                    // 只编译 plugin
+    "prepublishOnly": "npm run build"  // 发布前自动构建
+  }
+}
+```
+
+## 🚀 工作流程
+
+### 开发流程
+
+1. 修改 `src/lib/*` - 无需编译
+2. 修改 `src/plugin/*` - 需要运行 `npm run build`
+3. 使用 `npm link` 链接到测试项目
+4. 清除 Vite 缓存：`rm -rf node_modules/.vite`
+
+### 发布流程
+
+```bash
+# 方式一：自动发布脚本
+npm run publish:auto
+
+# 方式二：手动发布
+npm run build        # 编译 plugin
+npm publish          # 发布到 npm
+```
+
+`prepublishOnly` 钩子确保发布前自动编译。
+
+## 💡 最佳实践
+
+### 对于库用户
+
+1. **使用 lib**:
+```typescript
+import { useParam } from 'uniky';
+```
+- 确保项目支持 TypeScript
+- Vite 会自动处理编译
+- 不需要任何特殊配置
+
+2. **使用 plugin**:
+```typescript
+import { unikyPlugin } from 'uniky/plugin';
+```
+- 直接使用，无需担心 ESM 问题
+- 已编译为 JS，兼容性好
+
+### 对于库开发者
+
+1. **修改 lib 代码**:
+   - 直接修改 `src/lib/**/*`
+   - 无需编译
+
+2. **修改 plugin 代码**:
+   - 修改 `src/plugin/**/*`
+   - 运行 `npm run build`
+   - 测试编译后的代码
+
+3. **发布新版本**:
+   - 运行 `npm run publish:auto`
+   - 自动编译 + 发布
+
+## 🎓 技术要点
+
+1. **ESM 模块系统**
+   - `"type": "module"` 声明包为 ESM
+   - 所有导入使用 `.js` 扩展名
+   - Node.js 内置模块使用 `node:` 前缀
+
+2. **TypeScript 编译**
+   - 只编译 plugin 部分
+   - 生成 `.js` 和 `.d.ts` 文件
+   - 保持 ESM 模块格式
+
+3. **依赖管理**
+   - peerDependencies 避免依赖冲突
+   - 用户项目提供实际依赖
+   - 开发时安装 devDependencies
+
+## 📚 参考资料
+
+- [Node.js ESM 文档](https://nodejs.org/api/esm.html)
+- [TypeScript 模块解析](https://www.typescriptlang.org/docs/handbook/module-resolution.html)
+- [Vite 插件开发](https://vitejs.dev/guide/api-plugin.html)

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.13] - 2024-01-30
+
+### Changed
+- **重要变更：采用混合发布模式**
+  - **lib 部分**：保持 TypeScript 源码（`src/lib/**/*`），由用户项目构建工具处理
+    - 避免依赖冲突，使用项目自己的 vue、@dcloudio/uni-app 等依赖
+    - 更好的类型支持和调试体验
+  - **plugin 部分**：编译为 JavaScript（`dist/plugin/**/*`）
+    - 解决 Vite 配置文件加载时的 ESM 兼容性问题
+    - 包含完整的类型定义文件（`.d.ts`）
+  - 更新 `tsconfig.json`，只编译 `src/plugin` 目录
+  - 更新 `package.json` exports 配置，分别指向源码和编译文件
+
+### Fixed
+- **彻底修复 ESM 兼容性问题**
+  - 修复了 `uniky/plugin` 在 Vite 配置文件加载时被 `require()` 导致的 ESM 错误
+  - 将 Node.js 内置模块导入改为使用 `node:` 前缀 (如 `node:fs`, `node:path`)
+  - 在所有相对导入中添加 `.js` 扩展名，确保 ESM 环境下正确解析
+  - 验证在 uni-shell 项目中正常运行，无警告
+
+### Added
+- 添加了 `tsconfig.json` 配置文件，提供完整的 TypeScript 编译配置
+- 在 README 中新增"架构说明"章节，详细说明混合发布模式的优势
+- 在 README 中新增"故障排除"章节，包含 7 种常见 ESM 错误的解决方案
+- 在 README 中新增"开发说明"章节，包含本地开发和发布流程
+- 为 uni-shell 项目创建 `UPDATE_UNIKY.md` 更新指南
+
+### 如何更新
+
+在使用 `uniky` 的项目中执行：
+
+```bash
+# 如果是从 npm 安装
+npm update uniky
+
+# 如果是本地开发使用 npm link
+cd /path/to/uniky
+npm run build
+npm link
+
+cd /path/to/your-project
+npm link uniky
+rm -rf node_modules/.vite  # 清除 Vite 缓存
+```
+
+## [1.0.12] - 2024-01-30
+
+### Changed
+- 全部编译为 JavaScript（已在 1.0.13 中改为混合模式）
+
+## [1.0.11] - 2024-01-30
+
+### Fixed
+- 初步 ESM 兼容性修复（未完全解决）
+
+### Added
+- 添加了基础的 TypeScript 和 ESM 支持
+- 在 README 中新增故障排除章节
+
+### Changed
+- 优化了 `package.json` 配置，添加 `sideEffects: false`
+
+## [1.0.10] - 2024-01-30
+
+### Initial Release
+- 提供 uni-app 常用 hooks
+- 提供 HTTP 请求封装
+- 提供 Vite 插件：
+  - `pagesDefinedPlugin`: 从 pages.json 生成类型安全的路由定义
+  - `globalDefinedPlugin`: 自动收集并生成全局类型定义

package/README.md

@@ -4,10 +4,10 @@ uni-app 开发工具库，提供常用的 hooks、http 请求封装和 vite 插
 
 ## 特性
 
-- ✅ 直接使用 TypeScript 源码，无需编译
+- ✅ 混合发布模式：lib 使用 TS 源码，plugin 编译为 JS
 - ✅ 与用户项目共享依赖，避免冲突
 - ✅ 完整的类型支持
-- ✅ 开箱即用的 Vite 插件
+- ✅ 开箱即用的 Vite 插件，兼容各种构建环境
 
 ## 安装
 
@@ -207,14 +207,26 @@ npm link uniky
 
 ## 架构说明
 
-本库直接发布 TypeScript 源码，不进行编译。这样做的好处：
+本库采用**混合发布模式**：
 
-1. **避免依赖冲突**：使用项目自己的 vue、@dcloudio/uni-app 等依赖
-2. **类型支持更好**：直接使用源码类型定义
-3. **调试更方便**：可以直接查看和调试源码
-4. **体积更小**：不包含编译后的代码
+### lib 部分 - TypeScript 源码
+- 直接发布 TS 源码（`src/lib/**/*`）
+- 由用户项目的构建工具（Vite）处理编译
+- 优势：
+  - 避免依赖冲突，使用项目自己的 vue、@dcloudio/uni-app 等依赖
+  - 类型支持更好，直接使用源码类型定义
+  - 调试更方便，可以直接查看和调试源码
+  - 体积更小，不包含编译后的代码
 
-用户项目的构建工具（如 Vite）会自动处理这些 TypeScript 文件的编译。
+### plugin 部分 - 编译后的 JavaScript
+- 编译为 JS 文件（`dist/plugin/**/*`）
+- 包含完整的类型定义（`.d.ts` 文件）
+- 原因：
+  - Vite 配置文件在加载时使用 esbuild
+  - esbuild 在某些环境下会尝试用 `require()` 加载模块
+  - 编译为 JS 可以避免 ESM 兼容性问题
+
+这种混合模式结合了两种方式的优势，既保持了库的灵活性，又确保了插件的兼容性。
 
 ## 发布
 
@@ -254,6 +266,41 @@ npm run publish:auto
 5. 确认后发布到 npm
 6. 可选自动提交到 git
 
+## 开发说明
+
+### 本地开发
+
+1. 克隆仓库
+```bash
+git clone https://github.com/zhuxietong/uniky.git
+cd uniky
+```
+
+2. 安装依赖
+```bash
+npm install
+```
+
+3. 构建 plugin（仅编译 plugin 部分）
+```bash
+npm run build
+```
+
+4. 链接到本地项目
+```bash
+npm link
+cd /path/to/your-project
+npm link uniky
+```
+
+### 发布流程
+
+```bash
+npm run publish:auto
+```
+
+发布前会自动执行 `npm run build`，编译 plugin 部分。
+
 ## License
 
 MIT

package/dist/plugin/global.defined.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from 'vite';
+export default function globalDefinedPlugin(): Plugin;
+//# sourceMappingURL=global.defined.d.ts.map

package/dist/plugin/global.defined.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global.defined.d.ts","sourceRoot":"","sources":["../../src/plugin/global.defined.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAWnC,MAAM,CAAC,OAAO,UAAU,mBAAmB,IAAI,MAAM,CA6TpD"}

package/dist/plugin/global.defined.js

@@ -0,0 +1,284 @@
+// 该插件用于作为 vite.config.ts 中 作为插件；
+// 该插件用于收集 src/autoGen/global文件夹下的ts文件 所有export 导出的内容， 并将其合并为一个全局定义文件 src/autoGen/global.d.ts 文件 同时，生成一个 /src/autoGen/global.install.ts 文件.
+// 以便在项目中全局使用这些类型定义，避免了手动维护全局类型定义文件的麻烦。
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export default function globalDefinedPlugin() {
+    const globalDir = 'src/autoGen/global';
+    const globalDtsPath = 'src/autoGen/global.d.ts';
+    const installTsPath = 'src/autoGen/global.install.ts';
+    /**
+     * 递归获取目录下所有 .ts 文件（排除 .d.ts 和 install.ts）
+     */
+    function getTsFiles(dir) {
+        const files = [];
+        if (!fs.existsSync(dir)) {
+            return files;
+        }
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...getTsFiles(fullPath));
+            }
+            else if (entry.isFile() && entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts') && entry.name !== 'global.install.ts') {
+                files.push(fullPath);
+            }
+        }
+        return files;
+    }
+    /**
+     * 解析 TypeScript 文件，提取所有 export 的内容
+     */
+    function parseExports(filePath) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const exports = [];
+        // 匹配 export default
+        const defaultExportRegex = /export\s+default\s+(function|class|const|let|var)?\s*([a-zA-Z_$][a-zA-Z0-9_$]*)?/g;
+        let match;
+        while ((match = defaultExportRegex.exec(content)) !== null) {
+            if (match[2]) {
+                exports.push({
+                    name: match[2],
+                    type: match[1] || 'const',
+                    isDefault: true,
+                    filePath
+                });
+            }
+        }
+        // 匹配 export function
+        const functionRegex = /export\s+(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
+        while ((match = functionRegex.exec(content)) !== null) {
+            exports.push({
+                name: match[1],
+                type: 'function',
+                isDefault: false,
+                filePath
+            });
+        }
+        // 匹配 export const/let/var
+        const varRegex = /export\s+(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
+        while ((match = varRegex.exec(content)) !== null) {
+            exports.push({
+                name: match[1],
+                type: 'const',
+                isDefault: false,
+                filePath
+            });
+        }
+        // 匹配 export class
+        const classRegex = /export\s+(?:abstract\s+)?class\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
+        while ((match = classRegex.exec(content)) !== null) {
+            exports.push({
+                name: match[1],
+                type: 'class',
+                isDefault: false,
+                filePath
+            });
+        }
+        // 匹配 export interface
+        const interfaceRegex = /export\s+interface\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
+        while ((match = interfaceRegex.exec(content)) !== null) {
+            exports.push({
+                name: match[1],
+                type: 'interface',
+                isDefault: false,
+                filePath
+            });
+        }
+        // 匹配 export type
+        const typeRegex = /export\s+type\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
+        while ((match = typeRegex.exec(content)) !== null) {
+            exports.push({
+                name: match[1],
+                type: 'type',
+                isDefault: false,
+                filePath
+            });
+        }
+        // 匹配 export enum
+        const enumRegex = /export\s+(?:const\s+)?enum\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
+        while ((match = enumRegex.exec(content)) !== null) {
+            exports.push({
+                name: match[1],
+                type: 'enum',
+                isDefault: false,
+                filePath
+            });
+        }
+        // 匹配 export { ... }
+        const namedExportRegex = /export\s*{([^}]+)}/g;
+        while ((match = namedExportRegex.exec(content)) !== null) {
+            const names = match[1].split(',').map(n => n.trim().split(/\s+as\s+/)[0].trim());
+            for (const name of names) {
+                if (name) {
+                    exports.push({
+                        name,
+                        type: 'const',
+                        isDefault: false,
+                        filePath
+                    });
+                }
+            }
+        }
+        return exports;
+    }
+    /**
+     * 生成 global.d.ts 文件内容
+     */
+    function generateGlobalDts(allExports) {
+        const imports = new Map();
+        // 按文件分组导出
+        for (const exp of allExports) {
+            const relativePath = path.relative('src/autoGen', exp.filePath).replace(/\\/g, '/').replace(/\.ts$/, '');
+            if (!imports.has(relativePath)) {
+                imports.set(relativePath, new Set());
+            }
+            if (!exp.isDefault) {
+                imports.get(relativePath).add(exp.name);
+            }
+        }
+        let content = '// 自动生成的全局类型定义文件\n';
+        content += '// 请勿手动修改\n\n';
+        // 生成 import 语句
+        for (const [filePath, names] of imports) {
+            if (names.size > 0) {
+                content += `import type { ${Array.from(names).join(', ')} } from './${filePath}';\n`;
+            }
+        }
+        content += '\n';
+        // 生成全局声明
+        content += 'declare global {\n';
+        // 对于函数、常量、类等，添加到全局
+        const globalItems = allExports.filter(exp => !exp.isDefault && exp.type !== 'interface' && exp.type !== 'type');
+        if (globalItems.length > 0) {
+            for (const exp of globalItems) {
+                if (exp.type === 'function') {
+                    content += `  const ${exp.name}: typeof import('./${path.relative('src/autoGen', exp.filePath).replace(/\\/g, '/').replace(/\.ts$/, '')}').${exp.name};\n`;
+                }
+                else if (exp.type === 'const') {
+                    content += `  const ${exp.name}: typeof import('./${path.relative('src/autoGen', exp.filePath).replace(/\\/g, '/').replace(/\.ts$/, '')}').${exp.name};\n`;
+                }
+                else if (exp.type === 'class') {
+                    content += `  const ${exp.name}: typeof import('./${path.relative('src/autoGen', exp.filePath).replace(/\\/g, '/').replace(/\.ts$/, '')}').${exp.name};\n`;
+                }
+            }
+        }
+        content += '}\n\n';
+        content += 'export {};\n';
+        return content;
+    }
+    /**
+     * 生成 global.install.ts 文件内容
+     */
+    function generateInstallTs(allExports) {
+        const imports = new Map();
+        // 按文件分组导出
+        for (const exp of allExports) {
+            const relativePath = './global/' + path.relative(path.join('src', 'autoGen', 'global'), exp.filePath).replace(/\\/g, '/').replace(/\.ts$/, '');
+            if (!imports.has(relativePath)) {
+                imports.set(relativePath, { names: new Set(), hasDefault: false });
+            }
+            const importInfo = imports.get(relativePath);
+            if (exp.isDefault) {
+                importInfo.hasDefault = true;
+                importInfo.defaultName = exp.name;
+            }
+            else if (exp.type !== 'interface' && exp.type !== 'type') {
+                importInfo.names.add(exp.name);
+            }
+        }
+        let content = '// 自动生成的全局安装文件\n';
+        content += '// 请勿手动修改\n\n';
+        // 生成 import 语句
+        for (const [filePath, info] of imports) {
+            if (info.hasDefault && info.names.size > 0) {
+                content += `import ${info.defaultName}, { ${Array.from(info.names).join(', ')} } from '${filePath}';\n`;
+            }
+            else if (info.hasDefault) {
+                content += `import ${info.defaultName} from '${filePath}';\n`;
+            }
+            else if (info.names.size > 0) {
+                content += `import { ${Array.from(info.names).join(', ')} } from '${filePath}';\n`;
+            }
+        }
+        content += '\n';
+        content += '/**\n';
+        content += ' * 安装全局定义\n';
+        content += ' * 在 main.ts 中调用此函数以注册全局变量\n';
+        content += ' */\n';
+        content += 'export function installGlobals() {\n';
+        // 将导出的内容挂载到 globalThis
+        const globalItems = allExports.filter(exp => exp.type !== 'interface' && exp.type !== 'type');
+        for (const exp of globalItems) {
+            const name = exp.isDefault ? (imports.get('./global/' + path.relative(path.join('src', 'autoGen', 'global'), exp.filePath).replace(/\\/g, '/').replace(/\.ts$/, ''))?.defaultName || exp.name) : exp.name;
+            content += `  (globalThis as any).${exp.name} = ${name};\n`;
+        }
+        content += '}\n';
+        return content;
+    }
+    /**
+     * 生成所有文件
+     */
+    function generate() {
+        try {
+            const tsFiles = getTsFiles(globalDir);
+            if (tsFiles.length === 0) {
+                console.log('[globalDefined] 未找到任何 TypeScript 文件');
+                return;
+            }
+            // 收集所有导出
+            const allExports = [];
+            for (const file of tsFiles) {
+                const exports = parseExports(file);
+                allExports.push(...exports);
+            }
+            if (allExports.length === 0) {
+                console.log('[globalDefined] 未找到任何导出');
+                return;
+            }
+            // 生成 global.d.ts
+            const dtsContent = generateGlobalDts(allExports);
+            fs.writeFileSync(globalDtsPath, dtsContent, 'utf-8');
+            console.log(`[globalDefined] 已生成 ${globalDtsPath}`);
+            // 生成 global.install.ts
+            const installContent = generateInstallTs(allExports);
+            fs.writeFileSync(installTsPath, installContent, 'utf-8');
+            console.log(`[globalDefined] 已生成 ${installTsPath}`);
+            console.log(`[globalDefined] 共处理 ${tsFiles.length} 个文件，${allExports.length} 个导出`);
+        }
+        catch (error) {
+            console.error('[globalDefined] 生成失败:', error);
+        }
+    }
+    return {
+        name: 'vite-plugin-global-defined',
+        buildStart() {
+            // 构建开始时生成文件
+            generate();
+        },
+        configureServer(server) {
+            // 监听 src/autoGen/global 目录下的文件变化
+            server.watcher.add(globalDir);
+            server.watcher.on('change', (file) => {
+                if (file.includes('src/autoGen/global') && file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.includes('global.install.ts')) {
+                    console.log(`[globalDefined] 检测到文件变化: ${file}`);
+                    generate();
+                }
+            });
+            server.watcher.on('add', (file) => {
+                if (file.includes('src/autoGen/global') && file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.includes('global.install.ts')) {
+                    console.log(`[globalDefined] 检测到新文件: ${file}`);
+                    generate();
+                }
+            });
+            server.watcher.on('unlink', (file) => {
+                if (file.includes('src/autoGen/global') && file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.includes('global.install.ts')) {
+                    console.log(`[globalDefined] 检测到文件删除: ${file}`);
+                    generate();
+                }
+            });
+        }
+    };
+}
+//# sourceMappingURL=global.defined.js.map