宝塔 Nginx 静态部署

主方案是官网直接下载 TGZ，无需数据库、Docker、Node 服务或私有 npm。选择 Linux 宝塔中的 Nginx 静态网站，绑定域名并申请 HTTPS。

地址	内容
/	官网文档
/demo/	完整在线演示（PC 最小宽度 1200px）
/demo/tutorials/recipes.html	八类教程的可运行页面
/downloads/	SDK TGZ、独立 Demo ZIP、SHA-256 与验证记录

本机生成完整交付

需要 Node.js ≥22.12.0。仓库根目录执行：

npm ci
npm run check
npm run pack
npm run test:install -- --tarball artifacts/shardx-map-sdk-0.1.0.tgz
npm run prepare:tgz-demo -- --tarball artifacts/shardx-map-sdk-0.1.0.tgz
npm run release:static -- --tarball artifacts/shardx-map-sdk-0.1.0.tgz

打包只执行一次。后续两个脚本传入 --tarball 时不会重新打包。静态交付脚本要求四种独立安装检查通过且 SHA-256 一致，自动生成下载清单、Demo ZIP、官网、/demo/ 和教程页面。

输出为 artifacts/releases/0.1.0/site/ 和同目录的 shardx-map-site-0.1.0.zip。本地输出已存在时脚本拒绝覆盖；需要重做候选时先将整个版本目录移动到备份位置。不要覆盖已对外发布的同版本文件；若 0.1.0 已正式发放，应先升级版本、同步 SDK/Demo 依赖及锁文件。

release:static 固定文档根路径和演示 /demo/，屏蔽构建环境中的天地图 Key 与旧模型 URL。普通 npm run build 仍是本地根路径构建，不可直接拿它替代本步骤的子路径交付。示例模型存在时会完整复制到输出，当前约 107 MiB；不能只传 tileset.json。生产构建生成文件后，还应按验收清单测试交付目录中的页面。

上传与配置

1. 宝塔添加静态站点，绑定真实域名，开启证书、自动续期和 HTTP 跳转 HTTPS。
2. 备份旧站点，解压站点 ZIP，将 site 内的内容直接上传到网站根目录。上传前确认模型数据已获公开展示与再分发许可，否则替换数据再构建。浏览器可访问的数据也可被访问者下载。
3. 保留宝塔证书、root、日志和安全配置，将仓库 deploy/nginx/static-site.conf 的 location 与 gzip 配置合并到现有 server 块。删除/替换原 location /，避免重复定义；若已有 gzip 设置也只保留一份。
4. 在宝塔检查 Nginx 配置，或执行 nginx -t，通过后平滑重载。保留上一版完整目录，切换站点根目录实现回退。

核心路由如下；完整模板还包括 gzip、HTML 更新检查和哈希资源长期缓存：

location = /demo { return 301 /demo/; }
location ^~ /demo/ {
    index index.html;
    try_files $uri $uri/ =404;
}
location ^~ /downloads/ { try_files $uri =404; }
location / {
    index index.html;
    try_files $uri $uri.html $uri/ =404;
}

当前无前端路由，不需要 SPA 首页回退。缺失 JS、Workers、瓦片或模型应返回 404，不能返回 HTML。HTML 和无内容哈希的 Cesium/模型文件使用更新检查；内容哈希资源长期缓存。版本化 TGZ/ZIP 长期缓存的前提是从不覆盖历史地址。

无需上传源码、node_modules、.env.local，不要运行公网 Vite 开发服务。首次使用服务器压缩即可，主示例 JS 较大，拆包作为后续优化。

用户如何使用

普通用户打开 /demo/。开发者在自己的项目中安装官网下载 TGZ 和 cesium@1.146.0、复制 Cesium 静态资源、引入两份 CSS，按快速开始创建地图并在卸载时 destroy。免 Key 的 Natural Earth 可直接使用；天地图需要使用者自己的域名授权 Key。

独立 Demo ZIP 解压后运行 npm ci、npm run dev。无需私有 registry，依赖安装仍需要网络。需要私有 npm 的团队使用可选 registry 流程；npm run release 实际会向该 registry 发布包，本方案不执行它。

上线后验证

访问真实域名，检查文档 clean URL、下载哈希、教程与 /demo/。验证 Workers、Natural Earth、围栏遮罩、全部模型子内容和销毁重建，无内网请求、HTTP 混合内容或缺失资源。再用真实 Key 验证天地图矢量/影像及注记、错误提示和动态署名。域名、证书、授权和线上回退演练未通过之前，不把本地交付记录当作生产上线完成。