Appearance
可选：私有 npm 部署
SDK 是浏览器依赖，不需要为 SDK 单独运行地图后端。部署包括三部分：私有 npm registry、宿主应用静态文件、文档静态站。 地图瓦片仍由已授权的天地图或自有 XYZ/WMTS 服务提供；Verdaccio 不缓存地图瓦片。
私有 npm
仓库 deploy/README.md 提供服务器逐步操作说明。文件如下：
text
deploy/
├── compose.yaml
├── .env.example
├── .npmrc.example
├── verdaccio/config.yaml
└── nginx/registry.conf.template采用 Verdaccio 6，完整存储挂载到命名卷 shardx-map-registry-storage，其中包含包、内部数据库/密钥及 htpasswd。 后端仅绑定主机回环 127.0.0.1:4873，外部通过 Nginx 的 443 HTTPS 访问。
| 包模式 | 读取 | 发布 | 撤包 | 上游 |
|---|---|---|---|---|
@shardx-map/* | 匿名允许 | 认证账户 | 禁止 | 不配置，防止私有命名空间回源 |
| 其他包 | 匿名允许 | 禁止 | 禁止 | https://registry.npmjs.org/ |
这意味着 SDK 可被任何能访问 registry 的人读取，不是“保密包”。需要保密时由网络边界或读取策略控制。 所有注册账户都是作用域发布者，自助注册始终关闭，由管理员离线添加 bcrypt 账户。 不要临时打开匿名发布或把 htpasswd/token 提交到仓库。
服务器操作顺序
- 配置 DNS、80/443 防火墙与证书链；在
deploy复制.env.example为.env并填写域名。 - 将 TLS 证书放入
deploy/secrets/tls/fullchain.pem，私钥放入privkey.pem，限制权限。 - 根据
deploy/README.md初始化存储卷并交互式创建发布账户。自定义卷名时同步修改账户工具的挂载目标。 - 执行
docker compose config --quiet、docker compose up -d，再从外部验证证书、ping、匿名读取、认证发布权限。 - 记录已测试的镜像 digest、运维联系人、备份与续期方式，完成验收。
模板中的 verdaccio:6 和 nginx:stable-alpine 是可移动标签，生产使用应锁定经过测试的补丁版本/digest。 模板不会申请/续期证书；80 端口默认全部重定向，不含 ACME HTTP challenge。 私钥变更后测试并 reload Nginx。不要用禁用 SSL 校验解决证书错误。
消费方配置
ini
registry=https://registry.npmjs.org/
@shardx-map:registry=https://npm.company.example/
strict-ssl=true匿名安装无需 token。发布者执行：
sh
npm login --auth-type=legacy --registry=https://npm.company.example/
npm whoami --registry=https://npm.company.example/CI token 从秘密管理器注入，只写临时用户级 npm 配置，认证项必须绑定实际 registry 主机。 不要把 token 放在 .npmrc.example、VITE_* 或 URL 中。 默认配置让其他包直连 npm；若团队要统一缓存，可显式将默认 registry 改为此域名。
文档站与宿主应用
在依赖已安装的仓库根目录运行：
sh
npm run dev -w @shardx-map/docs
npm run build -w @shardx-map/docs
npm run preview -w @shardx-map/docs使用仓库根目录的 lockfile 安装依赖，保留主作者维护的依赖安全 overrides；不要在文档 workspace 单独解析另一套依赖。 生产仅发布 apps/docs/.vitepress/dist，不用 preview 服务器作为公网长期服务。 启用了 clean URLs，静态服务器应按 $uri、$uri.html、$uri/ 查找文件，未命中返回站点 404，不能全站回退首页。
文档部署在子路径时通过 DOCS_BASE 构建：
sh
# Linux / macOS
DOCS_BASE=/shardx-map/ npm run build -w @shardx-map/docspowershell
# PowerShell
$env:DOCS_BASE = '/shardx-map/'
npm run build -w @shardx-map/docs
Remove-Item Env:DOCS_BASEDOCS_BASE 须以 / 开始和结尾；静态服务器需在对应前缀下托管输出目录。 宿主 Vite 应用则单独构建其静态文件与 Cesium 资源，检查应用 base、资源根路径、MIME 和缓存策略，见资源部署。 文档站配置不修改 SDK/example，也不会替它们复制资源。