teee-mapper

v1.0.0

Published

2 months ago

A map SDK for TEEE based on Mapbox GL JS

Downloads

0High
0Medium
0Low

orangewest

map mapbox sdk teee

TeeeMap

这是一个 Mapbox GL 的封装库，提供了更简洁易用的 API，用于封装和扩展 Mapbox GL 的功能。采用多格式输出策略，支持多种使用场景。

打包发布

发布前准备

确保代码已提交到 Git

git add .
git commit -m "准备发布新版本"
git push

检查 package.json 配置
- 确认 name、version、description 等信息正确
- 确认 repository 和 homepage URL 已更新（如果已发布到 GitHub）
- 确认 files 字段包含需要发布的文件（dist）

运行测试

# 构建开发版本并测试
npm run build:dev

# 在浏览器中测试（使用本地服务器）
npx http-server -p 8080 -o test/browser-test.html

构建生产版本

# 构建生产版本（压缩、优化）
npm run build

构建完成后，检查 dist 目录下是否生成了所有必要的文件：

teee-map.cjs - CommonJS 格式
teee-map.js - ES 模块格式
teee-map.umd.js - UMD 格式（开发版）
teee-map.umd.min.js - UMD 格式（压缩版）
index.d.ts 及所有类型定义文件

发布到 npm

0. 注册账号：`https://www.npmjs.com/signup`

1. 登录 npm（如果未登录）

重要：发布前先切换到官方源

# 切换到 npm 官方源
npm set registry https://registry.npmjs.org

# 验证当前源
npm config get registry

登录之前先创建访问令牌（必须）

这是启用 2FA 的替代方案，可以立即使用：

创建细粒度访问令牌（在 npm 网站）：
- 登录 npm 网站：https://www.npmjs.com
- 点击右上角头像 → 选择 "Access Tokens"
- 点击 "Generate New Token"
- 设置令牌信息：
  - Token name：给令牌起个名字（如 "Publish Token"）
  - Expiration：选择过期时间（建议选择较长时间）
  - Select packages：选择 "All packages"
  - Permissions：选择 "Read and Write"
  - ⚠️ 重要：Bypass 2FA：勾选此选项（这样就不需要启用 2FA 也能发布）
- 点击 "Generate Token"
- 立即复制生成的令牌（只显示一次！），保存到安全的地方我的令牌是 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
登录：
```
npm login
```
验证登录：
```
npm whoami
```
如果显示你的用户名，说明登录成功。

注意：

必须使用 npm 5.5.1 或更高版本才能使用访问令牌
截至 2025 年 11 月，仅支持细粒度访问令牌，遗留访问令牌已被移除
创建令牌时，确保勾选 "Bypass 2FA" 选项，这样就不需要启用 2FA 也能发布

2. 检查发布内容（可选但推荐）

# 查看将要发布到 npm 的文件列表
npm pack --dry-run

确认只有必要的文件会被发布（dist 目录）。

3. 发布包(发布之前会自动打包成生产版本的包)

首次发布：

npm publish

更新版本发布：

# 方式一：使用 npm version 自动更新版本号并创建 git tag
npm version patch  # 补丁版本 1.0.0 -> 1.0.1
npm version minor   # 次版本 1.0.0 -> 1.1.0
npm version major   # 主版本 1.0.0 -> 2.0.0

# 然后发布
npm publish

发布测试版本（beta/alpha）：

# 手动修改 package.json 中的 version，例如：1.0.1-beta.1
npm publish --tag beta

4. 验证发布

发布成功后，可以通过以下方式验证：

# 查看包信息
npm view @teee/teee-map

# 在另一个项目中测试安装
npm install @teee/teee-map

版本号管理

遵循语义化版本规范：

主版本号（MAJOR）：不兼容的 API 修改
次版本号（MINOR）：向下兼容的功能性新增
修订号（PATCH）：向下兼容的问题修正

发布检查清单

[ ] 代码已提交到 Git
[ ] package.json 中的版本号已更新
[ ] package.json 中的 repository 和 homepage URL 正确
[ ] 已运行 npm run build 构建生产版本
[ ] 已测试构建后的文件可以正常使用
[ ] dist 目录包含所有必要的文件
[ ] README.md 文档完整且准确
[ ] 已登录 npm（npm whoami 验证）
[ ] 已运行 npm pack --dry-run 检查发布内容

常见问题

发布失败：403 Forbidden - Two-factor authentication required
- 登录之前先创建访问令牌（必须）
直接设置 token
```
   npm config set //registry.npmjs.org/:_authToken YOUR_TOKEN_HERE
```
然后可以直接发布
```
npm publish
```
发布失败：包名已存在
- 检查包名是否已被占用
- 如果包名被占用，需要修改 package.json 中的 name 字段
- 包名不能与别人的包名太过相似
发布失败：版本号已存在
- 更新 package.json 中的 version 字段
- 或使用 npm version 命令自动更新
发布后无法立即安装
- npm 镜像同步可能需要几分钟
- 可以尝试清除 npm 缓存：npm cache clean --force

撤销已发布的版本

# 24小时内可以撤销
npm unpublish @teee/teee-map@版本号

# 注意：如果包已被下载，建议发布新版本而不是撤销

安装使用

npm install @teee/teee-map

使用示例

1. Node.js 环境

const TeeeMap = require('@teee/teee-map');
// 自动使用 dist/teee-map.cjs.js

2. 现代前端项目（Webpack/Vite）

// 需要先引入 mapbox-gl 的 CSS
import 'mapbox-gl/dist/mapbox-gl.css';

// 默认导出：导入 TeeeMap 类
import TeeeMap from '@teee/teee-map';

// 命名导出：导入其他功能
import {
  generateStationConfig,
  generateStationGeomConfig,
  stationGraphStyle,
  stationGeomStyle,
} from '@teee/teee-map';

// TypeScript 类型导入
import type {
  TeeeMapOptions,
  StationConfig,
  StationGeomConfig,
} from '@teee/teee-map';

// 使用示例
const map = new TeeeMap('map-container', {
  accessToken: 'your-mapbox-token',
  center: [116.3974, 39.9093],
  zoom: 13,
});

// 使用命名导出
const stationConfig = generateStationConfig('station001', {
  urlTemplate: 'https://example.com/tiles/{z}/{x}/{y}.pbf',
});

注意：在模块化项目中，默认导出和命名导出都可以直接使用，不需要像浏览器 UMD 格式那样使用 TeeeMap.default。

3. 浏览器直接引入

<!-- 需要先导入 mapbox-gl 的 JS 和 CSS -->
<link href="https://unpkg.com/mapbox-gl/dist/mapbox-gl.css" rel="stylesheet" />
<script src="https://unpkg.com/mapbox-gl/dist/mapbox-gl.js"></script>
<script src="./dist/teee-map.umd.min.js"></script>
<!-- 或者开发环境：<script src="./dist/teee-map.umd.js"></script> -->
<script>
  // 处理 UMD 导出：默认导出在 TeeeMap.default 上
  const TeeeMapClass = TeeeMap.default || TeeeMap;

  // 命名导出直接在 TeeeMap 对象上
  const { generateStationConfig, generateStationGeomConfig } = TeeeMap;

  // 使用默认导出
  const map = new TeeeMapClass('map-container', {
    accessToken: 'your-mapbox-token',
  });

  // 使用命名导出
  const stationConfig = generateStationConfig('station001', {
    urlTemplate: 'https://example.com/tiles/{z}/{x}/{y}.pbf',
  });
</script>

注意事项

mapbox-gl 作为 peer dependency，需要在使用项目中单独安装：
```
npm install mapbox-gl
```
必须引入 mapbox-gl 的 CSS：
- 在模块化项目中：import 'mapbox-gl/dist/mapbox-gl.css'
- 在浏览器中：<link href="https://unpkg.com/mapbox-gl/dist/mapbox-gl.css" rel="stylesheet" />
Node.js 版本要求: >= 20.0.0