cmpt-huitu-cli 1.0.2 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cmpt-huitu-cli",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "type": "module",
   "description": "慧图前端项目工程化 CLI 工具",
   "main": "index.js",

package/templates/default/ESM/347/216/257/345/242/203/350/257/264/346/230/216.md

@@ -0,0 +1,164 @@
+# ESM 环境说明
+
+## 什么是 ESM？
+
+**ESM (ES Modules)** 是 JavaScript 的现代模块系统，使用 `import/export` 语法。
+
+### ESM vs CommonJS
+
+| 特性           | ESM (ES Modules)                               | CommonJS                                        |
+| -------------- | ---------------------------------------------- | ----------------------------------------------- |
+| **语法**       | `import/export`                                | `require/module.exports`                        |
+| **加载时机**   | 编译时静态分析                                 | 运行时动态加载                                  |
+| **支持**       | 现代浏览器、Node.js 12+                        | Node.js 传统方式                                |
+| **文件扩展名** | `.mjs` 或 `package.json` 中 `"type": "module"` | `.js` 或 `package.json` 中 `"type": "commonjs"` |
+
+## 为什么项目使用 ESM？
+
+### 1. 项目配置
+
+在 `package.json` 中：
+
+```json
+{
+  "type": "module"
+}
+```
+
+这表示项目使用 ESM 模块系统。
+
+### 2. Vite 默认使用 ESM
+
+Vite 是一个基于 ESM 的构建工具：
+
+- 开发时：直接使用浏览器原生的 ESM
+- 构建时：将代码转换为优化的 ESM 格式
+
+### 3. 现代标准
+
+ESM 是 JavaScript 的官方标准，未来趋势。
+
+## 为什么需要特殊写法？
+
+### 问题：CommonJS 模块兼容性
+
+某些第三方库（如 `dayjs`、`xe-utils`）可能是 **CommonJS 格式**，在 ESM 环境下导入时可能出现问题：
+
+```javascript
+// CommonJS 模块导出方式
+module.exports = {
+  default: function() { ... },
+  // 其他导出
+}
+
+// ESM 导入时
+import dayjs from 'dayjs'  // 可能获取不到 default
+```
+
+### 解决方案
+
+#### 1. Vite 自动处理（推荐）
+
+Vite 会自动将 CommonJS 模块转换为 ESM，**正常情况下不需要特殊写法**：
+
+```javascript
+// ✅ 正常写法（应该可以工作）
+import dayjs from 'dayjs'
+```
+
+#### 2. 配置 optimizeDeps
+
+在 `vite.config.js` 中配置预构建：
+
+```javascript
+optimizeDeps: {
+  include: ['dayjs', 'xe-utils'],  // 告诉 Vite 预构建这些模块
+}
+```
+
+#### 3. 特殊写法（仅在必要时）
+
+如果自动转换失败，才需要使用兼容写法：
+
+```javascript
+// 兼容写法（仅在必要时）
+import * as dayjsModule from 'dayjs'
+const dayjs = dayjsModule.default || dayjsModule
+```
+
+## 实际情况
+
+### dayjs 支持情况
+
+`dayjs` 实际上**同时支持 CommonJS 和 ESM**：
+
+- 有 `main` 字段（CommonJS）
+- 有 `module` 字段（ESM，如果提供）
+- 现代版本应该可以直接使用 `import dayjs from 'dayjs'`
+
+### 为什么会出现问题？
+
+可能的原因：
+
+1. **Vite 预构建未完成**
+   - 首次启动时，Vite 需要预构建依赖
+   - 如果预构建失败或未完成，可能出现导入错误
+
+2. **缓存问题**
+   - Vite 缓存了错误的构建结果
+   - 需要清理 `node_modules/.vite` 缓存
+
+3. **依赖未正确安装**
+   - `dayjs` 未安装或版本不兼容
+   - pnpm 的依赖提升机制导致路径问题
+
+4. **包版本问题**
+   - 某些旧版本的 `dayjs` 可能不完全支持 ESM
+
+## 最佳实践
+
+### 1. 优先使用标准写法
+
+```javascript
+// ✅ 推荐：标准 ESM 导入
+import dayjs from 'dayjs'
+```
+
+### 2. 确保 Vite 配置正确
+
+```javascript
+// vite.config.js
+export default {
+  optimizeDeps: {
+    include: ['dayjs'], // 确保预构建
+  },
+}
+```
+
+### 3. 清理缓存
+
+如果出现问题：
+
+```bash
+rm -rf node_modules/.vite
+pnpm dev
+```
+
+### 4. 仅在必要时使用兼容写法
+
+如果标准写法不工作，再使用兼容写法。
+
+## 总结
+
+**正常情况下，不需要特殊写法！**
+
+- ESM 是标准，应该直接使用 `import dayjs from 'dayjs'`
+- Vite 会自动处理 CommonJS 到 ESM 的转换
+- 如果出现问题，通常是配置或缓存问题，而不是语法问题
+- 特殊写法只是**临时解决方案**，应该优先排查根本原因
+
+## 相关资源
+
+- [MDN: ES Modules](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Guide/Modules)
+- [Vite: 依赖预构建](https://cn.vitejs.dev/guide/dep-pre-bundling.html)
+- [dayjs 官方文档](https://day.js.org/)

package/templates/default/package.json

@@ -25,6 +25,7 @@
     "lodash-es": "^4.17.21",
     "nprogress": "^0.2.0",
     "pinia": "^3.0.3",
+    "vxe-table": "^4.16.20",
     "vue": "^3.5.18",
     "vue-router": "^4.5.1"
   },

package/templates/default/vite.config.js

@@ -96,6 +96,8 @@ export default defineConfig(({ mode, command }) => {
       },
       // import引用可以忽略文件后缀如：import router from './router' === import router from './router/index.js'
       extensions: ['.mjs', '.ts', '.jsx', '.tsx', '.json', '.js', '.vue', '.css', '.scss'],
+      // 确保正确解析 CommonJS 模块，避免重复打包
+      dedupe: ['vxe-table', 'xe-utils'],
     },
 
     // CSS预处理器配置
@@ -120,6 +122,13 @@ export default defineConfig(({ mode, command }) => {
       sourcemap: !isProduction, // 开发保留 sourcemap
       target: ['es2015', 'edge88', 'chrome87'], // 产物目标浏览器
       minify: 'esbuild', // 代码压缩，vite默认使用esbuild，如果需要使用terser，需要安装npm install terser@vitejs/plugin-terser -D
+      // CommonJS 选项配置
+      commonjsOptions: {
+        // 将 CommonJS 模块转换为 ES 模块
+        transformMixedEsModules: true,
+        // 包含的 CommonJS 模块
+        include: [/xe-utils/, /vxe-table/],
+      },
       // 下面要配合 minify: 'terser'，才能生效
       // terserOptions: isProduction
       //   ? {
@@ -146,6 +155,7 @@ export default defineConfig(({ mode, command }) => {
           manualChunks: {
             'x-vuelib': ['vue', 'vue-router', 'pinia', 'axios', 'dayjs', 'lodash-es'],
             'x-eleuilib': ['element-plus'],
+            'x-vxetable': ['vxe-table', 'xe-utils'],
           },
           experimentalMinChunkSize: 2048, // 该选项用于为代码分割设置一个以字节为单位的最小 chunk 大小
           // inlineDynamicImports: true // 该选项用于内联动态引入,该选项只在单页面应用的时候起作用
@@ -179,9 +189,20 @@ export default defineConfig(({ mode, command }) => {
         'dayjs/plugin/weekOfYear',
         'dayjs/plugin/isSameOrBefore',
         'dayjs/plugin/isSameOrAfter',
+        'vxe-table',
+        'xe-utils',
       ], // 默认情况下，不在 node_modules 中的，链接的包不会被预构建
       exclude: ['cmpt-huitu-ui', 'cmpt-huitu-utils'], // 在预构建中强制排除的依赖项
       force: false, // 强制进行依赖预构建
+      esbuildOptions: {
+        // 处理 CommonJS 模块（如 xe-utils）
+        format: 'esm',
+        // 支持 CommonJS
+        supported: {
+          'dynamic-import': true,
+          'import-meta': true,
+        },
+      },
     },
 
     // 下面要配合 minify: 'esbuild'，才能生效

package/templates/default//344/277/256/345/244/215vxe-table/344/276/235/350/265/226/351/227/256/351/242/230.md

@@ -0,0 +1,106 @@
+# 修复 vxe-table 依赖问题
+
+## 问题描述
+
+执行 `pnpm dev` 后，终端报错：
+```
+[vite] Internal server error: Failed to resolve import "vxe-table" from "node_modules/.pnpm/cmpt-huitu-ui@1.0.1/node_modules/cmpt-huitu-ui/index.js?v=8ce970af". Does the file exist?
+```
+
+控制台报错：
+```
+GET http://localhost:3002/node_modules/.pnpm/cmpt-huitu-ui@1.0.1/node_modules/cmpt-huitu-ui/index.js?v=8ce970af net::ERR_ABORTED 500 (Internal Server Error)
+```
+
+## 问题原因
+
+`cmpt-huitu-ui` 包依赖 `vxe-table`，但项目的 `package.json` 中没有直接声明 `vxe-table` 依赖。在使用 pnpm 时，依赖提升机制可能没有正确提升 `vxe-table` 到项目的 `node_modules` 中，导致 Vite 无法解析该模块。
+
+## 解决方案
+
+### 方案 1：手动添加依赖（推荐）
+
+在项目根目录执行：
+
+```bash
+pnpm add vxe-table@^4.16.20
+```
+
+或者使用 npm：
+
+```bash
+npm install vxe-table@^4.16.20
+```
+
+### 方案 2：修改 package.json
+
+在项目的 `package.json` 的 `dependencies` 中添加：
+
+```json
+{
+  "dependencies": {
+    "vxe-table": "^4.16.20",
+    // ... 其他依赖
+  }
+}
+```
+
+然后执行：
+
+```bash
+pnpm install
+```
+
+### 方案 3：配置 pnpm 依赖提升（可选）
+
+如果希望 pnpm 自动提升 `vxe-table`，可以在项目根目录创建 `.npmrc` 文件：
+
+```
+shamefully-hoist=true
+```
+
+然后重新安装依赖：
+
+```bash
+rm -rf node_modules pnpm-lock.yaml
+pnpm install
+```
+
+**注意**：`shamefully-hoist=true` 会让 pnpm 的行为更像 npm，可能会增加 `node_modules` 的大小。
+
+## 验证
+
+修复后，检查以下内容：
+
+1. ✅ `package.json` 中包含 `vxe-table` 依赖
+2. ✅ `node_modules` 中存在 `vxe-table` 目录
+3. ✅ 终端没有 `vxe-table` 相关错误
+4. ✅ 页面正常加载
+5. ✅ `VexTable` 组件可以正常使用
+
+## 预防措施
+
+**对于新创建的项目**：
+
+模板已经更新，新创建的项目会自动包含 `vxe-table` 依赖，不会再出现此问题。
+
+**对于已创建的项目**：
+
+请按照上述方案手动添加 `vxe-table` 依赖。
+
+## 相关依赖
+
+`vxe-table` 的依赖关系：
+- `vxe-table` 依赖 `xe-utils`
+- `cmpt-huitu-ui` 依赖 `vxe-table`
+
+因此，项目中需要同时安装：
+- `vxe-table`（已通过模板添加）
+- `xe-utils`（会自动作为 `vxe-table` 的依赖安装）
+
+## 注意事项
+
+- 确保 `vxe-table` 版本与 `cmpt-huitu-ui` 包中声明的版本兼容（当前为 `^4.16.20`）
+- 如果使用 Monorepo，确保依赖正确安装
+- 清理缓存后重新启动开发服务器
+

package/templates/default//344/277/256/345/244/215xe-utils/351/224/231/350/257/257.md

@@ -0,0 +1,158 @@
+# 修复 xe-utils 导入错误
+
+## 问题描述
+
+执行 `pnpm dev` 后，控制台报错：
+```
+Uncaught SyntaxError: The requested module '/node_modules/.pnpm/xe-utils@3.8.3/node_modules/xe-utils/index.js?v=e03718de' does not provide an export named 'default' (at config.js?v=e03718de:1:8)
+```
+
+## 问题原因
+
+`xe-utils` 是 `vxe-table` 的依赖，是一个 CommonJS 模块。在 Vite 的 ESM 环境下，需要正确预构建和转换。
+
+## 解决方案
+
+### 方案 1：清理缓存并重启（推荐先尝试）
+
+```bash
+# 1. 停止开发服务器（Ctrl+C）
+
+# 2. 删除 Vite 缓存
+rm -rf node_modules/.vite
+
+# 3. 如果使用 pnpm，清理 pnpm 缓存
+rm -rf node_modules/.pnpm
+
+# 4. 重新安装依赖（可选，如果上述步骤无效）
+pnpm install
+
+# 5. 重新启动开发服务器
+pnpm dev
+```
+
+### 方案 2：检查 vite.config.js 配置
+
+确保 `vite.config.js` 中包含以下配置：
+
+```javascript
+export default defineConfig({
+  // ... 其他配置
+
+  // 优化依赖预构建
+  optimizeDeps: {
+    include: [
+      // ... 其他依赖
+      'vxe-table',
+      'xe-utils',
+    ],
+    exclude: ['cmpt-huitu-ui', 'cmpt-huitu-utils'],
+    esbuildOptions: {
+      format: 'esm',
+      supported: {
+        'dynamic-import': true,
+        'import-meta': true,
+      },
+    },
+  },
+
+  // 路径解析配置
+  resolve: {
+    // ... 其他配置
+    dedupe: ['vxe-table', 'xe-utils'],
+  },
+
+  // 构建配置
+  build: {
+    // ... 其他配置
+    commonjsOptions: {
+      transformMixedEsModules: true,
+      include: [/xe-utils/, /vxe-table/],
+    },
+  },
+})
+```
+
+### 方案 3：如果上述方案无效，尝试强制重新构建
+
+在 `vite.config.js` 中临时设置：
+
+```javascript
+optimizeDeps: {
+  // ... 其他配置
+  force: true, // 强制重新构建依赖
+}
+```
+
+然后重启开发服务器。构建完成后，可以改回 `force: false`。
+
+### 方案 4：检查 vxe-table 版本
+
+如果问题仍然存在，可能是 `vxe-table` 版本与 `xe-utils` 版本不兼容。
+
+检查 `cmpt-huitu-ui` 包中的 `vxe-table` 版本：
+
+```bash
+cd node_modules/cmpt-huitu-ui
+cat package.json | grep vxe-table
+```
+
+如果版本过旧，可能需要更新 `cmpt-huitu-ui` 包。
+
+### 方案 5：使用 Vite 插件（最后手段）
+
+如果以上方案都无效，可以创建一个 Vite 插件来处理：
+
+```javascript
+// vite/plugins/fixXeUtils.js
+export default function fixXeUtils() {
+  return {
+    name: 'fix-xe-utils',
+    enforce: 'pre',
+    resolveId(id) {
+      if (id === 'xe-utils') {
+        return id
+      }
+    },
+    load(id) {
+      if (id === 'xe-utils') {
+        // 返回一个包装的 ESM 模块
+        return `
+          import * as xeUtils from 'xe-utils'
+          export default xeUtils
+          export * from 'xe-utils'
+        `
+      }
+    },
+  }
+}
+```
+
+然后在 `vite.config.js` 中使用：
+
+```javascript
+import fixXeUtils from './vite/plugins/fixXeUtils'
+
+export default defineConfig({
+  plugins: [
+    // ... 其他插件
+    fixXeUtils(),
+  ],
+  // ... 其他配置
+})
+```
+
+## 验证
+
+修复后，检查以下内容：
+
+1. ✅ 控制台没有 `xe-utils` 相关错误
+2. ✅ 页面正常加载
+3. ✅ `VexTable` 组件可以正常使用
+
+## 注意事项
+
+- 如果使用 Monorepo，确保 `cmpt-huitu-ui` 包已正确发布并安装
+- 清理缓存后，首次启动可能会较慢（需要重新预构建依赖）
+- 如果问题持续存在，可能需要检查 `vxe-table` 和 `xe-utils` 的版本兼容性
+