cmpt-huitu-cli 1.0.3 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cmpt-huitu-cli",
-  "version": "1.0.3",
+  "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/)