发布流程

主流程：官网 TGZ 静态交付

按宝塔部署执行一次 pack，再对同一 TGZ 依次执行 test:install -- --tarball ...、prepare:tgz-demo -- --tarball ...、release:static -- --tarball ...。生成的站点含下载页、SHA-256、独立 Demo 和全部教程。

发布前完成静态检查、单元测试、完整生产浏览器测试，并重复验证曾失败项。记录源码提交/版本标签、包哈希与验证日志。模型单独备份并确认公开展示/再分发许可；真实域名、HTTPS 和天地图授权另行验收。已公开的同版本地址不覆盖。

静态上线保留上一版完整站点，上传新版本后检查所有入口和缺失资源的 404 行为；回退切换根目录即可。SDK 消费者需按锁文件主动升级或回退并重新构建，不会因官网换包自动更新。

可选：私有 npm 发布

以下内容只适用于已部署私有 registry 的团队。官网 TGZ 方案不需要执行 npm run release。

目标包为 @shardx-map/[email protected]，Cesium peer 必须保持 >=1.146.0 <1.147.0。本文是操作说明，不表示该版本已经发布。是否可以发布取决于构建/安装证据、外部验收和发布负责人确认。

准备与质量门禁

在主作者完成仓库集成后，从仓库根目录执行。使用锁文件和与仓库一致的 Node.js/npm，先保留执行日志与环境版本。不要在主作者仍安装依赖、写源码或运行发布任务时并发执行 npm ci。

npm ci
npm audit --audit-level=high
npm run check
npm run test:browser
npm run test:install

check 覆盖仓库定义的类型、格式、lint、单测、构建与包检查；其他脚本各自的覆盖范围和结果必须查看实际输出。审计包含文档构建工具的开发依赖，不只检查 SDK 运行时依赖；VitePress 保持稳定版本时，保留根依赖覆盖并重新验证构建兼容性。本地临时 registry 测试不等于生产 HTTPS registry 验收，离线测试瓦片也不等于真实天地图可达。如果脚本缺失或跳过，记录为未执行，不以文档中的命令替代检查证据。

检查包版本、peer 范围、导出类型、ESM、样式入口、资源复制 CLI、LICENSE 与第三方声明。发布包应保留 Cesium external import，不包含 Cesium 完整构建、静态资源、仓库源码、私密配置或真实 key。

生成与审阅 tarball

npm run pack
npm run check:package

当前仓库打包产物预期为 artifacts/shardx-map-sdk-0.1.0.tgz。必须查看实际文件清单和内容；仅看压缩包大小不能证明没有敏感信息。保存该文件的 SHA-256：

sha256sum artifacts/shardx-map-sdk-0.1.0.tgz

powershell

Get-FileHash artifacts/shardx-map-sdk-0.1.0.tgz -Algorithm SHA256

在仓库外的新消费目录安装这个 tarball 与 [email protected]，复制资源并运行原生 Vite 构建/浏览器验证。安装来源必须为 tarball，不能使用 workspace 链接或源码 alias；检查导入 JS、.d.ts、CSS 和 CLI 均来自包。记录测试用 tarball 的校验和，确认待发布文件与它一致。如果后续重新打包导致内容改变，重新执行相关验证。

发布候选版本

先在真实 HTTPS registry 登录并核对目标：

npm login --auth-type=legacy --registry=https://npm.company.example/
npm whoami --registry=https://npm.company.example/
npm view @shardx-map/[email protected] version --registry=https://npm.company.example/

只有“指定版本确实不存在”的响应才允许作为首次发布依据；证书、网络、超时、401/403 或服务 5xx 均不是版本不存在。不要用 || true 吞掉检查错误。已经发布的版本按不可覆盖处理，修复应升新版本。

发布负责人批准已审核的 tarball 后执行以下有外部写入的步骤：

npm publish artifacts/shardx-map-sdk-0.1.0.tgz \
  --registry=https://npm.company.example/ --tag next --ignore-scripts
npm view @shardx-map/[email protected] version dist.integrity dist.tarball \
  --registry=https://npm.company.example/

显式指定 registry，避免误发公网。next 先作为候选标签；版本号仍是 0.1.0，不因标签变为预发布语义版本。不要在记录中保留 token，dist.tarball 应指向公开 HTTPS 域名，不能泄露容器名或回环 URL。执行后从匿名的新消费项目、干净 npm 缓存按 registry 地址重新安装确切版本并验证，不允许退回本地 tarball 掩盖远端问题。

也可以设置真实 SHARDX_REGISTRY 后使用根目录 npm run release：脚本核对登录和版本不存在，执行全部本地检查及独立安装验证，随后发布经过安装验证的同一个 tarball，默认使用 next 标签。可用 SHARDX_PUBLISH_TAG 显式指定标签。不要在手动发布后再运行它重复发布同一版本。

发布成功后运行 npm run test:registry，核对认证身份、匿名元数据/下载、包完整性及隔离用户配置和缓存的新项目安装。该命令仅验收已发布版本，不执行发布。

提升标签与回退

候选版本完成外部验收后，由发布负责人执行：

npm dist-tag add @shardx-map/[email protected] latest --registry=https://npm.company.example/
npm dist-tag ls @shardx-map/sdk --registry=https://npm.company.example/

发布前记录原 latest 指向。若新版本出问题，已存在上一稳定版本时可将 latest 指回它；首次发布没有可回退版本，应暂停推广、移除不适当标签或发布修复版本，并通知使用者。标签回退不改变按确切版本或已有 lockfile 安装的用户；这些用户需主动升级或回退并重新构建宿主应用。模板禁止 unpublish，不删除已发布历史。不要通过直接修改 storage 文件“修复”版本。

发布记录

在版本页记录版本、实际发布时间、变更、兼容性、已知问题、tarball 校验和与外部验收记录位置。保存执行者、registry 地址、SDK/文档/示例对应源码版本，以及升级与回退办法。秘密与内部地址按组织策略脱敏，不把私密运维记录放入公开文档站。

发布流程 ​

主流程：官网 TGZ 静态交付 ​

可选：私有 npm 发布 ​

准备与质量门禁 ​

生成与审阅 tarball ​

发布候选版本 ​

提升标签与回退 ​

发布记录 ​