@xiaonoodles/meetfun-i18n 1.2.17 → 1.3.0

package/TROUBLESHOOTING.md

@@ -1,280 +1,280 @@
-# 故障排除指南
-
-## Vue2 项目报错：`export 'createI18n' was not found in 'vue-i18n'`
-
-### 问题描述
-
-在 Vue2 项目中使用 `meetfun-i18n/vue2` 时，遇到以下错误：
-
-```
-ERROR in ./node_modules/meetfun-i18n/dist/index.esm.js
-export 'createI18n' (imported as 'createI18n') was not found in 'vue-i18n'
-```
-
-### 原因
-
-这个错误说明打包工具（Webpack/uni-app）加载了 Vue3 版本的代码（`dist/index.esm.js`），而不是 Vue2 版本（`dist/vue2/index.esm.js`）。
-
-Vue3 的 vue-i18n@9 使用 `createI18n`，而 Vue2 的 vue-i18n@8 使用 `new VueI18n()`，这导致了不兼容。
-
-### 解决方案
-
-#### 方案 1：使用正确的引入路径（推荐）
-
-确保您的引入语句是：
-
-```javascript
-// ✅ 正确 - Vue2 项目
-import { createMeetFunI18n } from 'meetfun-i18n/vue2'
-
-// ❌ 错误 - 这会加载 Vue3 版本
-import { createMeetFunI18n } from 'meetfun-i18n'
-```
-
-#### 方案 2：检查 package.json 中的版本
-
-确保安装了正确版本的依赖：
-
-```bash
-# 检查当前版本
-pnpm list vue vue-i18n
-
-# Vue2 项目应该是：
-# vue: ^2.7.x
-# vue-i18n: ^8.x.x
-
-# 如果版本不对，重新安装
-pnpm remove vue vue-i18n
-pnpm add vue@^2.7.0 vue-i18n@^8.0.0
-```
-
-#### 方案 3：清除缓存并重新安装
-
-```bash
-# 清除 node_modules
-rm -rf node_modules
-
-# 清除锁定文件（根据你的包管理器选择）
-rm package-lock.json  # npm
-rm yarn.lock          # yarn
-rm pnpm-lock.yaml     # pnpm
-
-# 重新安装
-pnpm install
-```
-
-#### 方案 4：Webpack 配置别名（适用于 uni-app）
-
-如果上述方法都不行，可以在 `vue.config.js` 或 Webpack 配置中添加别名：
-
-```javascript
-// vue.config.js
-module.exports = {
-  configureWebpack: {
-    resolve: {
-      alias: {
-        'meetfun-i18n/vue2': 'meetfun-i18n/vue2.js'
-      }
-    }
-  }
-}
-```
-
-### 验证是否正确加载
-
-创建一个测试文件：
-
-```javascript
-// test.js
-import { createMeetFunI18n } from 'meetfun-i18n/vue2'
-console.log('导入成功:', typeof createMeetFunI18n)
-```
-
-如果输出 `导入成功: function`，说明加载正确。
-
----
-
-## 类型定义找不到
-
-### 问题描述
-
-TypeScript 项目报错：找不到模块 `meetfun-i18n/vue2` 的类型定义。
-
-### 解决方案
-
-#### 方案 1：确保安装了最新版本
-
-```bash
-pnpm add meetfun-i18n@latest
-```
-
-#### 方案 2：在 tsconfig.json 中添加类型引用
-
-```json
-{
-  "compilerOptions": {
-    "types": ["meetfun-i18n/vue2"]
-  }
-}
-```
-
-#### 方案 3：手动指定类型
-
-在文件顶部添加：
-
-```typescript
-/// <reference types="meetfun-i18n/vue2" />
-import { createMeetFunI18n } from 'meetfun-i18n/vue2'
-```
-
----
-
-## uni-app 编译报错
-
-### 问题描述
-
-在 uni-app 项目中编译时报错。
-
-### 解决方案
-
-#### 方案 1：确保 HBuilderX 或 CLI 版本最新
-
-```bash
-# 如果使用 CLI
-npm update -g @vue/cli-service-global
-```
-
-#### 方案 2：检查 manifest.json 配置
-
-确保配置了正确的 Vue 版本：
-
-```json
-{
-  "vueVersion": "2"  // Vue2 项目
-}
-```
-
-#### 方案 3：清除编译缓存
-
-在 HBuilderX 中：
-1. 运行 -> 清除缓存
-2. 重新编译
-
-使用 CLI：
-```bash
-rm -rf unpackage
-npm run dev:mp-weixin  # 或其他平台
-```
-
----
-
-## peerDependencies 警告
-
-### 问题描述
-
-安装时出现 peerDependencies 警告。
-
-### 解决方案
-
-这是正常的，因为包支持 Vue2 和 Vue3。确保您安装了正确版本的依赖即可：
-
-**Vue2 项目：**
-```bash
-pnpm add vue@^2.7.0 vue-i18n@^8.0.0
-```
-
-**Vue3 项目：**
-```bash
-pnpm add vue@^3.0.0 vue-i18n@^9.0.0
-```
-
----
-
-## 运行时报错：`uni is not defined`
-
-### 问题描述
-
-在非 uni-app 项目中使用报错。
-
-### 解决方案
-
-本库依赖 uni-app 的 `uni` 全局对象，仅适用于 uni-app 项目。
-
-如果您需要在普通 Vue 项目中使用，可以：
-
-1. 使用原生的 vue-i18n
-2. 或者 mock `uni` 对象（不推荐）
-
----
-
-## 构建产物体积过大
-
-### 问题描述
-
-打包后体积较大。
-
-### 解决方案
-
-#### 方案 1：启用 Tree Shaking
-
-确保使用 ES Module 导入：
-
-```javascript
-// ✅ 好 - 支持 Tree Shaking
-import { createMeetFunI18n } from 'meetfun-i18n/vue2'
-
-// ❌ 不好
-const { createMeetFunI18n } = require('meetfun-i18n/vue2')
-```
-
-#### 方案 2：只导入需要的功能
-
-```javascript
-import { createMeetFunI18n, LANGUAGE_OPTIONS_CONFIGURATION } from 'meetfun-i18n/vue2'
-// 而不是：import * as i18n from 'meetfun-i18n/vue2'
-```
-
----
-
-## 其他常见问题
-
-### Q: 可以在 Vue2 和 Vue3 混合项目中使用吗？
-
-A: 不建议。一个项目应该只使用一个版本的 Vue 和对应的 meetfun-i18n 版本。
-
-### Q: 升级到新版本后出现问题怎么办？
-
-A: 
-1. 查看 [CHANGELOG.md](./CHANGELOG.md) 了解破坏性更改
-2. 清除缓存和 node_modules
-3. 重新安装依赖
-
-### Q: 如何确认使用的是哪个版本？
-
-A: 在代码中添加调试信息：
-
-```javascript
-import { createMeetFunI18n } from 'meetfun-i18n/vue2'
-console.log('meetfun-i18n version:', createMeetFunI18n.toString())
-```
-
----
-
-## 获取帮助
-
-如果以上方法都无法解决问题，请：
-
-1. 检查 [GitHub Issues](https://github.com/meetfun/meetfun-i18n/issues)
-2. 提供以下信息创建新 Issue：
-   - Vue 版本
-   - vue-i18n 版本
-   - meetfun-i18n 版本
-   - 完整的错误信息
-   - 最小复现代码
-
-## 相关文档
-
-- [README.md](./README.md) - 完整使用文档
-- [VUE2_USAGE.md](./VUE2_USAGE.md) - Vue2 使用指南
-- [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) - 迁移指南
-
+# 故障排除指南
+
+## Vue2 项目报错：`export 'createI18n' was not found in 'vue-i18n'`
+
+### 问题描述
+
+在 Vue2 项目中使用 `meetfun-i18n/vue2` 时，遇到以下错误：
+
+```
+ERROR in ./node_modules/meetfun-i18n/dist/index.esm.js
+export 'createI18n' (imported as 'createI18n') was not found in 'vue-i18n'
+```
+
+### 原因
+
+这个错误说明打包工具（Webpack/uni-app）加载了 Vue3 版本的代码（`dist/index.esm.js`），而不是 Vue2 版本（`dist/vue2/index.esm.js`）。
+
+Vue3 的 vue-i18n@9 使用 `createI18n`，而 Vue2 的 vue-i18n@8 使用 `new VueI18n()`，这导致了不兼容。
+
+### 解决方案
+
+#### 方案 1：使用正确的引入路径（推荐）
+
+确保您的引入语句是：
+
+```javascript
+// ✅ 正确 - Vue2 项目
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+
+// ❌ 错误 - 这会加载 Vue3 版本
+import { createMeetFunI18n } from 'meetfun-i18n'
+```
+
+#### 方案 2：检查 package.json 中的版本
+
+确保安装了正确版本的依赖：
+
+```bash
+# 检查当前版本
+pnpm list vue vue-i18n
+
+# Vue2 项目应该是：
+# vue: ^2.7.x
+# vue-i18n: ^8.x.x
+
+# 如果版本不对，重新安装
+pnpm remove vue vue-i18n
+pnpm add vue@^2.7.0 vue-i18n@^8.0.0
+```
+
+#### 方案 3：清除缓存并重新安装
+
+```bash
+# 清除 node_modules
+rm -rf node_modules
+
+# 清除锁定文件（根据你的包管理器选择）
+rm package-lock.json  # npm
+rm yarn.lock          # yarn
+rm pnpm-lock.yaml     # pnpm
+
+# 重新安装
+pnpm install
+```
+
+#### 方案 4：Webpack 配置别名（适用于 uni-app）
+
+如果上述方法都不行，可以在 `vue.config.js` 或 Webpack 配置中添加别名：
+
+```javascript
+// vue.config.js
+module.exports = {
+  configureWebpack: {
+    resolve: {
+      alias: {
+        'meetfun-i18n/vue2': 'meetfun-i18n/vue2.js'
+      }
+    }
+  }
+}
+```
+
+### 验证是否正确加载
+
+创建一个测试文件：
+
+```javascript
+// test.js
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+console.log('导入成功:', typeof createMeetFunI18n)
+```
+
+如果输出 `导入成功: function`，说明加载正确。
+
+---
+
+## 类型定义找不到
+
+### 问题描述
+
+TypeScript 项目报错：找不到模块 `meetfun-i18n/vue2` 的类型定义。
+
+### 解决方案
+
+#### 方案 1：确保安装了最新版本
+
+```bash
+pnpm add meetfun-i18n@latest
+```
+
+#### 方案 2：在 tsconfig.json 中添加类型引用
+
+```json
+{
+  "compilerOptions": {
+    "types": ["meetfun-i18n/vue2"]
+  }
+}
+```
+
+#### 方案 3：手动指定类型
+
+在文件顶部添加：
+
+```typescript
+/// <reference types="meetfun-i18n/vue2" />
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+```
+
+---
+
+## uni-app 编译报错
+
+### 问题描述
+
+在 uni-app 项目中编译时报错。
+
+### 解决方案
+
+#### 方案 1：确保 HBuilderX 或 CLI 版本最新
+
+```bash
+# 如果使用 CLI
+npm update -g @vue/cli-service-global
+```
+
+#### 方案 2：检查 manifest.json 配置
+
+确保配置了正确的 Vue 版本：
+
+```json
+{
+  "vueVersion": "2"  // Vue2 项目
+}
+```
+
+#### 方案 3：清除编译缓存
+
+在 HBuilderX 中：
+1. 运行 -> 清除缓存
+2. 重新编译
+
+使用 CLI：
+```bash
+rm -rf unpackage
+npm run dev:mp-weixin  # 或其他平台
+```
+
+---
+
+## peerDependencies 警告
+
+### 问题描述
+
+安装时出现 peerDependencies 警告。
+
+### 解决方案
+
+这是正常的，因为包支持 Vue2 和 Vue3。确保您安装了正确版本的依赖即可：
+
+**Vue2 项目：**
+```bash
+pnpm add vue@^2.7.0 vue-i18n@^8.0.0
+```
+
+**Vue3 项目：**
+```bash
+pnpm add vue@^3.0.0 vue-i18n@^9.0.0
+```
+
+---
+
+## 运行时报错：`uni is not defined`
+
+### 问题描述
+
+在非 uni-app 项目中使用报错。
+
+### 解决方案
+
+本库依赖 uni-app 的 `uni` 全局对象，仅适用于 uni-app 项目。
+
+如果您需要在普通 Vue 项目中使用，可以：
+
+1. 使用原生的 vue-i18n
+2. 或者 mock `uni` 对象（不推荐）
+
+---
+
+## 构建产物体积过大
+
+### 问题描述
+
+打包后体积较大。
+
+### 解决方案
+
+#### 方案 1：启用 Tree Shaking
+
+确保使用 ES Module 导入：
+
+```javascript
+// ✅ 好 - 支持 Tree Shaking
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+
+// ❌ 不好
+const { createMeetFunI18n } = require('meetfun-i18n/vue2')
+```
+
+#### 方案 2：只导入需要的功能
+
+```javascript
+import { createMeetFunI18n, LANGUAGE_OPTIONS_CONFIGURATION } from 'meetfun-i18n/vue2'
+// 而不是：import * as i18n from 'meetfun-i18n/vue2'
+```
+
+---
+
+## 其他常见问题
+
+### Q: 可以在 Vue2 和 Vue3 混合项目中使用吗？
+
+A: 不建议。一个项目应该只使用一个版本的 Vue 和对应的 meetfun-i18n 版本。
+
+### Q: 升级到新版本后出现问题怎么办？
+
+A: 
+1. 查看 [CHANGELOG.md](./CHANGELOG.md) 了解破坏性更改
+2. 清除缓存和 node_modules
+3. 重新安装依赖
+
+### Q: 如何确认使用的是哪个版本？
+
+A: 在代码中添加调试信息：
+
+```javascript
+import { createMeetFunI18n } from 'meetfun-i18n/vue2'
+console.log('meetfun-i18n version:', createMeetFunI18n.toString())
+```
+
+---
+
+## 获取帮助
+
+如果以上方法都无法解决问题，请：
+
+1. 检查 [GitHub Issues](https://github.com/meetfun/meetfun-i18n/issues)
+2. 提供以下信息创建新 Issue：
+   - Vue 版本
+   - vue-i18n 版本
+   - meetfun-i18n 版本
+   - 完整的错误信息
+   - 最小复现代码
+
+## 相关文档
+
+- [README.md](./README.md) - 完整使用文档
+- [VUE2_USAGE.md](./VUE2_USAGE.md) - Vue2 使用指南
+- [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) - 迁移指南
+