# create-mapv-three

> 用于快速创建 MapV-Three 应用的脚手架工具，基于 Vite，开箱即用。

<p align="center">
  <img src="https://raw.githubusercontent.com/wahddbing/mapv-three-assets/main/result1.webp" width="48%" alt="effect-preview-1" />
  <img src="https://raw.githubusercontent.com/wahddbing/mapv-three-assets/main/result2.webp" width="48%" alt="effect-preview-2" />
</p>

## 快速开始

```bash
npx create-mapv-three my-app
cd my-app
npm install
npm run dev
```

> 环境要求：**Node.js >= 16**

## 使用方法

### 交互式创建

直接执行命令，按提示选择项目名、模板和包管理器：

```bash
npx create-mapv-three
```

<p align="center">
  <img src="https://raw.githubusercontent.com/wahddbing/mapv-three-assets/main/usage.webp" width="600" alt="interactive-usage" />
</p>


## 命令行选项

| 选项 | 简写 | 说明 |
| --- | --- | --- |
| `[project-name]` | — | 项目目录名 |
| `--template <id>` | `-t` | 选择模板 |
| `--pm <name>` | `-m` | 包管理器：`npm` / `yarn` / `pnpm` |
| `--version` | `-V` | 显示版本号 |
| `--help` | `-h` | 显示帮助信息 |

## 内置模板

| 模板 ID | 说明 |
| --- | --- |
| `base` | 基础模板（Engine + DynamicSky + Vite） |
| `vue-baidu-map` | Vue 3 + 百度地图 |
| `react-baidu-map` | React 18 + 百度地图 |
| `vue-baidu-map-offline` | Vue 3 + 百度地图（离线包） |
| `react-baidu-map-offline` | React 18 + 百度地图（离线包） |

## 项目命名

只允许 **小写字母、数字、连字符（`-`）**，且不能以 `-` 开头或结尾。

## 配置 AK

**在线版**模板（`vue-baidu-map` / `react-baidu-map`）启动前必须配置 AK，否则地图无法加载；**离线包版**模板（`*-offline`）无需强制配置 AK，直接放入离线包即可使用。

### 一、在线版 AK 配置（`vue-baidu-map` / `react-baidu-map`）

需要在 [百度地图开放平台](https://lbsyun.baidu.com/) 申请 AK。

#### 1. 申请 AK

1. 登录 [百度地图开放平台](https://lbsyun.baidu.com/)（无账号请先注册并完成实名认证）
2. 进入控制台 → **应用管理** → **我的应用** → **创建应用**
3. 填写应用信息：
   - **应用名称**：自定义，例如 `my-mapv-app`
   - **应用类型**：选择 **浏览器端**
   - **启用服务**：勾选 `JavaScript API GL`（其他按需勾选）
   - **Referer 白名单**：开发阶段填 `*`，上线后改为线上域名（如 `https://yourdomain.com/*`）
4. 提交后在应用列表复制 **访问应用（AK）** 字符串

#### 2. 填入项目

打开 `src/components/BaiduMap.vue`（或 React 版的 `BaiduMap.jsx`），把占位符替换为申请到的 AK：

```js
// 配置百度地图 AK
mapvthree.BaiduMapConfig.ak = '你申请到的AK'
```

> 💡 推荐用环境变量管理：在项目根目录新建 `.env.local`，写入 `VITE_BAIDU_AK=你的AK`，代码改为 `mapvthree.BaiduMapConfig.ak = import.meta.env.VITE_BAIDU_AK`，避免 AK 提交到代码仓库。

### 二、离线包版配置（`vue-baidu-map-offline` / `react-baidu-map-offline`）

离线包版**无需强制配置 AK**，鉴权由离线包自身完成，只需放入离线包并配置好资源路径即可使用。

#### 1. 放置离线包

把 `@baidu/mapv-three` 离线包解压到项目的 `packages/mapv-three/` 目录：

```text
my-app/
└── packages/
    └── mapv-three/
        ├── package.json
        ├── dist/
        └── ...
```

然后执行 `npm install`，本地包会被链入 `node_modules`。


## 生成后

```bash
cd my-app
npm install        # 或 yarn / pnpm install
npm run dev        # 启动开发服务器
npm run build      # 构建生产包
```

## 许可证

MIT