create-mapv-three

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

快速开始

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

环境要求：Node.js >= 16

使用方法

交互式创建

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

npx create-mapv-three

命令行选项

| 选项 | 简写 | 说明 | | --- | --- | --- | | [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）

需要在 百度地图开放平台 申请 AK。

1. 申请 AK

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

2. 填入项目

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

// 配置百度地图 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/ 目录：

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

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

生成后

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

许可证

MIT