uniky 1.0.13 → 1.0.15

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/package.json

@@ -1,29 +1,30 @@
 {
   "name": "uniky",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "uni-app 开发工具库，包含 hooks、http 请求和 vite 插件",
   "type": "module",
-  "main": "./dist/lib/index.js",
-  "module": "./dist/lib/index.js",
-  "types": "./dist/lib/index.d.ts",
+  "main": "./src/lib/index.ts",
+  "module": "./src/lib/index.ts",
+  "types": "./src/lib/index.ts",
   "exports": {
     ".": {
-      "types": "./dist/lib/index.d.ts",
-      "import": "./dist/lib/index.js"
+      "types": "./src/lib/index.ts",
+      "import": "./src/lib/index.ts"
     },
     "./plugin": {
-      "types": "./dist/plugin/index.d.ts",
-      "import": "./dist/plugin/index.js"
+      "types": "./src/plugin/index.ts",
+      "import": "./src/plugin/index.ts"
     }
   },
   "sideEffects": false,
   "files": [
-    "dist",
-    "README.md"
+    "src/lib",
+    "src/plugin",
+    "README.md",
+    "CHANGELOG.md",
+    "ARCHITECTURE.md"
   ],
   "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "npm run build",
     "publish:auto": "bash publish.sh"
   },
   "keywords": [

package/src/lib/hook/index.ts

@@ -0,0 +1,2 @@
+// created by zhuxietong on 2026-01-30 16:37
+export * from './useParam.js';

package/src/lib/hook/useParam.ts

@@ -0,0 +1,114 @@
+import { onLoad } from '@dcloudio/uni-app'
+import { onMounted, ref } from 'vue'
+
+export const useParam = <Q extends object = {}, J extends object = {}>(
+  callBack?: (params: { option: Partial<Q & J>; query: Partial<Q>; json: Partial<J> }) => void,
+) => {
+  const query = ref<Partial<Q>>({})
+  const json = ref<Partial<J>>({})
+  const param = ref<Partial<Q & J>>({})
+
+  onLoad((op?: AnyObject) => {
+    let jsonObj: any = {}
+    let queryObj: any = {}
+
+    if (!op || Object.keys(op).length === 0) {
+      param.value = {} as any
+      query.value = {} as any
+      json.value = {} as any
+      callBack?.({ option: {} as any, query: {} as any, json: {} as any })
+      return
+    }
+
+    const decodedOp: { [k: string]: any } = {}
+    for (const key in op) {
+      if (typeof op[key] === 'string') {
+        if (key === 'json') {
+          try {
+            decodedOp[key] = JSON.parse(decodeURIComponent(op[key]))
+            jsonObj = decodedOp[key]
+            json.value = jsonObj
+          } catch (e) {}
+          continue
+        }
+        decodedOp[key] = decodeURIComponent(op[key])
+      } else {
+        decodedOp[key] = op[key]
+      }
+    }
+
+    try {
+      queryObj = { ...decodedOp }
+      delete queryObj.json
+      query.value = queryObj
+    } catch (e) {}
+
+    param.value = { ...jsonObj, ...queryObj }
+    callBack?.({ option: param.value as any, query: query.value as any, json: json.value as any })
+  })
+
+  return {
+    query,
+    param,
+    json,
+  }
+}
+
+export const useMountedLoad = <Q extends object = {}, J extends object = {}>(
+  callBack?: (params: { option: Partial<Q & J>; query: Partial<Q>; json: Partial<J> }) => void,
+) => {
+  const query = ref<Partial<Q>>({})
+  const json = ref<Partial<J>>({})
+  const param = ref<Partial<Q & J>>({})
+
+  onLoad((op?: AnyObject) => {
+    let jsonObj: any = {}
+    let queryObj: any = {}
+
+    if (!op || Object.keys(op).length === 0) {
+      param.value = {} as any
+      query.value = {} as any
+      json.value = {} as any
+      return
+    }
+
+    const decodedOp: { [k: string]: any } = {}
+    for (const key in op) {
+      if (typeof op[key] === 'string') {
+        if (key === 'json') {
+          try {
+            decodedOp[key] = JSON.parse(decodeURIComponent(op[key]))
+            jsonObj = decodedOp[key]
+            json.value = jsonObj
+          } catch (e) {}
+          continue
+        }
+        decodedOp[key] = decodeURIComponent(op[key])
+      } else {
+        decodedOp[key] = op[key]
+      }
+    }
+
+    try {
+      queryObj = { ...decodedOp }
+      delete queryObj.json
+      query.value = queryObj
+    } catch (e) {}
+
+    param.value = { ...jsonObj, ...queryObj }
+  })
+
+  onMounted(() => {
+    callBack?.({
+      option: (param.value || {}) as any,
+      query: (query.value || {}) as any,
+      json: (json.value || {}) as any
+    })
+  })
+
+  return {
+    query,
+    param,
+    json,
+  }
+}

package/src/lib/http/index.ts

@@ -0,0 +1,2 @@
+// created by zhuxietong on 2026-01-30 16:37
+export * from './ky.js';