expo-gaode-map 2.0.0-alpha.6 → 2.0.0

package/DEPLOY_DOCS.md

@@ -0,0 +1,209 @@
+# 📚 文档网站部署指南
+
+本文档说明如何部署 expo-gaode-map 的文档网站到 GitHub Pages。
+
+## 🌟 项目结构
+
+```
+expo-gaode-map/
+├── website/                      # 文档网站目录
+│   ├── docs/                    # 文档源文件
+│   │   ├── .vitepress/         # VitePress 配置
+│   │   │   └── config.mts      # 网站配置文件
+│   │   ├── guide/              # 指南文档
+│   │   ├── api/                # API 文档
+│   │   ├── examples/           # 示例文档
+│   │   └── index.md            # 首页
+│   ├── package.json            # 依赖配置
+│   └── README.md               # 网站说明
+└── .github/
+    └── workflows/
+        └── deploy-docs.yml     # 自动部署配置
+```
+
+## 🚀 快速部署
+
+### 方式一：GitHub Actions 自动部署（推荐）
+
+1. **启用 GitHub Pages**
+   
+   进入你的 GitHub 仓库设置：
+   - 点击 `Settings` > `Pages`
+   - 在 **Source** 下选择 `GitHub Actions`
+
+2. **推送代码**
+   
+   ```bash
+   git add .
+   git commit -m "Add documentation website"
+   git push origin main
+   ```
+
+3. **等待部署完成**
+   
+   - 进入仓库的 `Actions` 标签页
+   - 查看 "Deploy Docs" 工作流的运行状态
+   - 部署成功后，访问: `https://<your-username>.github.io/expo-gaode-map/`
+
+### 方式二：本地构建后手动部署
+
+1. **安装依赖**
+   
+   ```bash
+   cd website
+   npm install
+   ```
+
+2. **构建网站**
+   
+   ```bash
+   npm run docs:build
+   ```
+
+3. **部署到 GitHub Pages**
+   
+   ```bash
+   # 进入构建产物目录
+   cd docs/.vitepress/dist
+   
+   # 初始化 git 仓库
+   git init
+   git add -A
+   git commit -m 'Deploy documentation'
+   
+   # 推送到 gh-pages 分支
+   git push -f git@github.com:<your-username>/expo-gaode-map.git main:gh-pages
+   
+   cd ../../../..
+   ```
+
+4. **配置 GitHub Pages**
+   
+   - 进入 `Settings` > `Pages`
+   - Source 选择 `Deploy from a branch`
+   - Branch 选择 `gh-pages` 和 `/ (root)`
+
+## 🔧 配置说明
+
+### 修改 Base URL
+
+如果你的 GitHub 仓库名不是 `expo-gaode-map`，需要修改配置：
+
+**文件:** `website/docs/.vitepress/config.mts`
+
+```ts
+export default defineConfig({
+  base: '/your-repo-name/',  // 修改为你的仓库名
+  // ...
+})
+```
+
+**文件:** `.github/workflows/deploy-docs.yml`
+
+确保工作流配置正确（当前配置已经是通用的，通常不需要修改）。
+
+### 自定义域名（可选）
+
+如果要使用自定义域名：
+
+1. 在 `website/docs/public/` 目录下创建 `CNAME` 文件
+2. 文件内容为你的域名，例如: `docs.yoursite.com`
+3. 在你的域名 DNS 设置中添加 CNAME 记录指向 `<username>.github.io`
+
+## 📝 本地开发
+
+### 启动开发服务器
+
+```bash
+cd website
+npm install
+npm run docs:dev
+```
+
+访问 http://localhost:5173 查看文档。
+
+### 预览生产版本
+
+```bash
+npm run docs:build
+npm run docs:preview
+```
+
+## 🎨 自定义文档
+
+### 添加新页面
+
+1. 在相应目录下创建 `.md` 文件
+2. 在 `config.mts` 中添加导航和侧边栏配置
+3. 编写文档内容
+
+### 修改主题
+
+VitePress 支持主题自定义，详见 [VitePress 文档](https://vitepress.dev/guide/custom-theme)。
+
+## ✅ 验证部署
+
+部署完成后，访问以下 URL 验证：
+
+- **首页:** `https://<username>.github.io/expo-gaode-map/`
+- **快速开始:** `https://<username>.github.io/expo-gaode-map/guide/getting-started`
+- **API 文档:** `https://<username>.github.io/expo-gaode-map/api/`
+
+## 🐛 常见问题
+
+### 1. 页面样式丢失或 404
+
+**问题:** 部署后页面样式丢失或资源 404
+
+**解决方案:** 检查 `base` 配置是否正确设置为 `/your-repo-name/`
+
+### 2. GitHub Actions 部署失败
+
+**问题:** Actions 工作流运行失败
+
+**解决方案:**
+- 检查 GitHub Pages 是否已启用
+- 确保选择了 "GitHub Actions" 作为 Source
+- 查看 Actions 日志获取详细错误信息
+
+### 3. 本地可以访问，部署后无法访问
+
+**问题:** 本地开发正常，部署后无法访问
+
+**解决方案:**
+- 确认 GitHub Pages 设置正确
+- 等待几分钟让 DNS 传播
+- 清除浏览器缓存
+
+### 4. 中文路径问题
+
+**问题:** 包含中文的文件名导致 URL 编码问题
+
+**解决方案:** 使用英文文件名，在文档内容中使用中文标题
+
+## 📚 参考资源
+
+- [VitePress 官方文档](https://vitepress.dev/)
+- [GitHub Pages 文档](https://docs.github.com/en/pages)
+- [GitHub Actions 文档](https://docs.github.com/en/actions)
+
+## 🤝 贡献文档
+
+欢迎改进文档！
+
+1. Fork 本仓库
+2. 创建特性分支
+3. 修改文档内容
+4. 提交 Pull Request
+
+## 📄 许可证
+
+MIT
+
+---
+
+**需要帮助？**
+
+- 📝 [提交 Issue](https://github.com/TomWq/expo-gaode-map/issues)
+- 💬 [参与讨论](https://github.com/TomWq/expo-gaode-map/discussions)
+- 💬 加入 QQ 群: 952241387

package/PUBLISHING.md

@@ -1,244 +1,262 @@
-# 发布到 NPM 指南
+# 发布流程
 
-本文档说明如何将 `expo-smartrefreshlayout` 发布到 npm。
+本文档说明如何发布 `expo-gaode-map` 的新版本。
 
-## 📋 发布前检查清单
+## 发布前准备
 
-在发布之前，请确保：
+### 1. 确保所有测试通过
 
-- [x] README.md 文档完整且准确
-- [x] package.json 配置正确
-- [x] 所有代码已提交到 Git
-- [ ] 构建成功无错误
-- [ ] 版本号已更新
-- [ ] 已有 npm 账号并已登录
+```bash
+# 运行测试
+npm test
+
+# 运行 lint 检查
+npm run lint
+```
+
+### 2. 更新版本号
 
-## 🚀 发布步骤
+编辑 `package.json` 中的版本号,遵循 [语义化版本](https://semver.org/lang/zh-CN/) 规则:
 
-### 1. 注册/登录 npm 账号
+- **主版本号(Major)**: 不兼容的 API 修改
+- **次版本号(Minor)**: 向下兼容的功能性新增
+- **修订号(Patch)**: 向下兼容的问题修正
 
-如果你还没有 npm 账号，需要先注册：
+或者使用 npm 命令自动更新版本号:
 
 ```bash
-# 注册账号（如果还没有）
-npm adduser
+# 修订版本 (1.0.0 -> 1.0.1)
+npm version patch
 
-# 或者登录已有账号
-npm login
+# 次版本 (1.0.0 -> 1.1.0)
+npm version minor
+
+# 主版本 (1.0.0 -> 2.0.0)
+npm version major
 ```
 
-按照提示输入：
-- Username（用户名）
-- Password（密码）
-- Email（邮箱）
-- OTP（如果启用了双因素认证）
+### 3. 更新 CHANGELOG
 
-验证是否登录成功：
-```bash
-npm whoami
-```
+在 `CHANGELOG.md` 中记录本次更新的内容:
 
-### 2. 检查 .npmignore 文件
+```markdown
+## [版本号] - YYYY-MM-DD
 
-确保 `.npmignore` 文件配置正确，避免发布不必要的文件。当前项目已配置。
+### Added (新增)
+- 新功能描述
 
-### 3. 清理并构建项目
+### Changed (变更)
+- 变更内容描述
 
-```bash
-# 清理之前的构建
-npm run clean
+### Fixed (修复)
+- Bug 修复描述
 
-# 重新构建
-npm run build
+### Breaking Changes (破坏性变更)
+- 不兼容的变更说明
 ```
 
-构建完成后，会在 `build/` 目录生成编译后的文件。
+## 发布步骤
 
-### 4. 测试构建结果
-
-在发布前，建议先测试构建结果：
+### 1. 清理构建产物
 
 ```bash
-# 查看会被发布的文件列表
-npm pack --dry-run
+npm run clean
+```
 
-# 或者创建一个本地 tarball 测试
-npm pack
+### 2. 构建项目
+
+```bash
+# 构建主模块和 Config Plugin
+npm run build
 ```
 
-这会显示将要发布到 npm 的所有文件。
+这个命令会:
+- 编译 TypeScript 源代码到 `build/` 目录
+- 编译 Config Plugin 到 `plugin/build/` 目录
 
-### 5. 更新版本号
+### 3. 验证构建产物
 
-使用 npm version 命令更新版本号（这会自动创建 git tag）：
+确认以下文件已生成:
 
 ```bash
-# 修复版本（0.1.0 -> 0.1.1）
-npm version patch
+# 主模块构建产物
+ls -la build/
 
-# 次要版本（0.1.0 -> 0.2.0）
-npm version minor
-
-# 主要版本（0.1.0 -> 1.0.0）
-npm version major
+# Config Plugin 构建产物
+ls -la plugin/build/
 ```
 
-或者手动修改 `package.json` 中的 `version` 字段。
+### 4. 本地测试(可选但推荐)
 
-### 6. 发布到 npm
+在发布前,可以在本地测试包:
 
 ```bash
-# 正式发布
-npm publish
+# 打包到本地
+npm pack
 
-# 如果是第一次发布公开包，需要添加 --access public
-npm publish --access public
+# 会生成 expo-gaode-map-x.x.x.tgz 文件
+# 在测试项目中安装:
+# npm install /path/to/expo-gaode-map-x.x.x.tgz
 ```
 
-**注意**：
-- 首次发布必须使用 `--access public`，因为默认是私有包
-- 发布后无法撤销，只能发布新版本
-- 包名不能与已存在的包重复
+### 5. 发布到 npm
 
-### 7. 验证发布
+#### 发布稳定版本
 
-发布成功后，可以：
-
-1. 访问 npm 页面查看：
-   ```
-   https://www.npmjs.com/package/expo-smartrefreshlayout
-   ```
+```bash
+# 发布到 latest 标签(默认)
+npm publish --tag latest
 
-2. 尝试安装测试：
-   ```bash
-   # 在另一个项目中测试安装
-   npm install expo-smartrefreshlayout
-   ```
+# 或使用快捷脚本
+npm run publish:latest
+```
 
-3. 查看包信息：
-   ```bash
-   npm info expo-smartrefreshlayout
-   ```
+#### 发布预发布版本
 
-### 8. 提交代码到 Git
+如果是 alpha、beta 等预发布版本:
 
 ```bash
-# 添加所有更改
-git add .
-
-# 提交更改
-git commit -m "chore: publish version 0.1.0"
+# 发布到 next 标签
+npm publish --tag next
 
-# 推送到远程仓库（包括 tags）
-git push origin main --tags
+# 或使用快捷脚本
+npm run publish:next
 ```
 
-## 🔄 发布新版本
+用户安装时:
+```bash
+# 安装稳定版
+npm install expo-gaode-map
 
-当需要发布新版本时：
-∑
-1. 修改代码并测试
-2. 更新 README.md（如果有 API 变化）
-3. 运行 `npm run build` 重新构建
-4. 更新版本号：`npm version patch/minor/major`
-5. 发布：`npm publish`
-6. 推送到 Git：`git push origin main --tags`
+# 安装预发布版
+npm install expo-gaode-map@next
+```
 
-## 📝 版本号规范（语义化版本）
+### 6. 创建 Git 标签
 
-版本号格式：`主版本号.次版本号.修订号`（例如：1.2.3）
+```bash
+# 创建标签
+git tag -a v版本号 -m "Release v版本号"
 
-- **主版本号（Major）**：不兼容的 API 修改
-- **次版本号（Minor）**：向下兼容的功能性新增
-- **修订号（Patch）**：向下兼容的问题修正
+# 推送标签到远程
+git push origin v版本号
 
-例如：
-- `0.1.0` -> `0.1.1`：修复 bug
-- `0.1.0` -> `0.2.0`：添加新功能
-- `0.1.0` -> `1.0.0`：重大更新，可能不兼容旧版本
+# 或推送所有标签
+git push --tags
+```
 
-## ⚠️ 常见问题
+### 7. 创建 GitHub Release
 
-### 1. 包名已存在
+1. 访问 GitHub 仓库的 Releases 页面
+2. 点击 "Create a new release"
+3. 选择刚创建的标签
+4. 填写 Release 标题和说明(可以从 CHANGELOG 复制)
+5. 点击 "Publish release"
 
-如果提示包名已被占用，需要修改 `package.json` 中的 `name` 字段：
+## 完整发布命令(推荐)
 
-```json
-{
-  "name": "@your-username/expo-smartrefreshlayout"
-}
-```
+```bash
+# 1. 清理
+npm run clean
 
-使用 npm scope 可以避免命名冲突。
+# 2. 构建(包含主模块和插件)
+npm run build
 
-### 2. 需要双因素认证（2FA）
+# 3. 测试
+npm test
+npm run lint
 
-如果账号启用了 2FA，发布时需要提供 OTP：
+# 4. 发布到 npm
+npm run publish:latest  # 稳定版
+# 或
+npm run publish:next    # 预发布版
 
-```bash
-npm publish --otp=123456
+# 5. 提交代码和标签
+git add .
+git commit -m "chore: release v版本号"
+git tag -a v版本号 -m "Release v版本号"
+git push origin main
+git push origin v版本号
 ```
 
-### 3. 构建失败
+## 发布文档网站(可选)
 
-确保安装了所有依赖：
+如果更新了文档,也需要部署文档网站:
 
 ```bash
-npm install
+cd website
 npm run build
+# 然后根据你的部署方式部署 docs/.vitepress/dist 目录
 ```
 
-### 4. 发布权限问题
+## 回滚版本
 
-确保你已登录正确的 npm 账号：
+如果发布后发现问题,可以废弃某个版本:
 
 ```bash
-npm whoami
-npm login
+# 废弃特定版本
+npm deprecate expo-gaode-map@版本号 "这个版本有问题,请使用 x.x.x 版本"
+
+# 取消发布(发布后24小时内)
+npm unpublish expo-gaode-map@版本号
 ```
 
-## 🎯 发布检查脚本
+## 发布检查清单
 
-你可以创建一个脚本来自动化发布前检查：
+- [ ] 更新版本号
+- [ ] 更新 CHANGELOG.md
+- [ ] 运行 `npm run clean`
+- [ ] 运行 `npm run build`
+- [ ] 运行 `npm test`
+- [ ] 运行 `npm run lint`
+- [ ] 确认 `build/` 目录有构建产物
+- [ ] 确认 `plugin/build/` 目录有构建产物
+- [ ] 本地测试 npm pack
+- [ ] 发布到 npm
+- [ ] 创建 Git 标签
+- [ ] 推送标签到 GitHub
+- [ ] 创建 GitHub Release
+- [ ] 在测试项目中验证新版本
 
-```bash
-#!/bin/bash
+## 注意事项
 
-echo "🔍 检查 Git 状态..."
-if [[ -n $(git status -s) ]]; then
-    echo "❌ 有未提交的更改，请先提交"
-    exit 1
-fi
+1. **Config Plugin 构建**: 确保 `plugin/build/` 目录包含在发布包中
+2. **`.npmignore` 配置**: 确认不需要的文件被排除
+3. **发布权限**: 确保你有 npm 包的发布权限
+4. **npm 登录**: 发布前确保已登录 `npm login`
+5. **双因素认证**: 如果启用了 2FA,准备好认证码
 
-echo "🧹 清理构建..."
-npm run clean
+## 常见问题
 
-echo "🔨 开始构建..."
-npm run build
+### 发布失败: 权限不足
 
-echo "✅ 构建成功！"
-echo "📦 预览将要发布的文件："
-npm pack --dry-run
+```bash
+# 检查登录状态
+npm whoami
 
-echo ""
-echo "准备发布！请运行："
-echo "  npm version patch  # 或 minor/major"
-echo "  npm publish --access public"
+# 重新登录
+npm login
 ```
 
-## 📚 相关资源
+### 构建产物不存在
 
-- [npm 官方文档](https://docs.npmjs.com/)
-- [语义化版本规范](https://semver.org/lang/zh-CN/)
-- [Expo Modules 文档](https://docs.expo.dev/modules/overview/)
+```bash
+# 确保构建成功
+npm run build
 
-## 🎉 首次发布
+# 检查 .npmignore 是否错误排除了构建产物
+cat .npmignore
+```
 
-如果这是首次发布，建议：
+### 版本已存在
 
-1. 先发布 `0.1.0` 版本进行测试
-2. 收集用户反馈
-3. 修复问题后发布 `0.1.1`、`0.1.2` 等
-4. 功能稳定后发布 `1.0.0` 正式版
+```bash
+# 无法覆盖已发布的版本,需要更新版本号
+npm version patch
+```
+
+## 相关链接
 
-祝发布顺利！🚀
+- [npm 发布文档](https://docs.npmjs.com/cli/v10/commands/npm-publish)
+- [语义化版本规范](https://semver.org/lang/zh-CN/)
+- [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)

package/README.en.md

@@ -32,29 +32,6 @@ yarn add expo-gaode-map
 pnpm add expo-gaode-map
 ```
 
-### Try 2.0 Beta Version 🚀
-
-> ⚠️ **Important**: Version 2.0 contains breaking changes with significant API adjustments. See [Migration Guide](docs/MIGRATION.md)
-
-If you want to try the latest 2.0 alpha version (with improved architecture and better type support):
-
-```bash
-npm install expo-gaode-map@next
-# or
-yarn add expo-gaode-map@next
-# or
-pnpm add expo-gaode-map@next
-```
-
-**Major Changes in 2.0:**
-- ✅ Unified API calling method (`ExpoGaodeMapModule`)
-- ✅ Complete TypeScript type support
-- ✅ Removed unnecessary wrapper layers, direct native module calls
-- ⚠️ **Not backward compatible**, code updates required per [Migration Guide](docs/MIGRATION.md)
-
-**Version Comparison:**
-- `1.x` (Stable): `import { initSDK, start, stop } from 'expo-gaode-map'`
-- `2.0` (Beta): `import { ExpoGaodeMapModule } from 'expo-gaode-map'`
 
 ### Expo Projects
 
@@ -224,8 +201,7 @@ Includes:
 - [API Documentation](docs/API.en.md) - Complete API reference
 - [Usage Examples](docs/EXAMPLES.en.md) - Detailed code examples
 - [Initialization Guide](docs/INITIALIZATION.en.md) - SDK initialization and permission management
-- [Architecture Documentation](docs/ARCHITECTURE.en.md) - Project structure and file descriptions
-- [Migration Guide](docs/MIGRATION.md) - Migration guide from v1.x to v2.0
+- [Architecture Documentation](docs/ARCHITECTURE.en.md) - Project structure and file 
 
 ## 🎨 Advanced Usage