TrueGrowth/docs/NPM_CDN_DEPLOY.md

NPM + CDN 部署指南

本文档介绍如何将 Opentu 发布到 npm，并通过免费 CDN 访问。

概述

通过将构建产物发布到 npm，可以利用免费的 CDN 服务（如 unpkg、jsDelivr）托管和访问应用，无需自建服务器。

快速开始

1. 发布到 npm

# 首次发布或版本更新后
pnpm run npm:publish

# 仅测试（不实际发布）
pnpm run npm:publish:dry

# 跳过构建（使用现有构建产物）
pnpm run npm:publish:skip-build

2. 访问应用

发布成功后，可以通过以下 CDN 地址访问：

unpkg (推荐)

# 最新版本
https://unpkg.com/aitu-app/index.html

# 指定版本
https://unpkg.com/aitu-app@0.5.14/index.html

jsDelivr

# 最新版本
https://cdn.jsdelivr.net/npm/aitu-app/index.html

# 指定版本
https://cdn.jsdelivr.net/npm/aitu-app@0.5.14/index.html

技术细节

相对路径配置

为支持 CDN 部署，项目做了以下配置：

1. Vite 配置 (apps/web/vite.config.ts)

   base: process.env.VITE_BASE_URL || './',
   

2. index.html

   • 移除了 <base href="/"> 标签
   • 所有静态资源使用相对路径 ./

发布脚本

scripts/publish-npm.js 执行以下操作：

1. 构建项目（使用相对路径）
2. 在 dist/apps/web 目录生成 npm 专用的 package.json
3. 生成 README.md
4. 移除不必要的文件（如 source maps）
5. 发布到 npm

npm 包结构

aitu-app/
├── index.html          # 入口页面
├── assets/             # JS、CSS、字体等资源
├── icons/              # 图标
├── logo/               # Logo
├── manifest.json       # PWA 配置
├── sw.js               # Service Worker
├── package.json        # npm 包信息
└── README.md           # 包说明

自定义配置

修改包名

编辑 scripts/publish-npm.js 中的 CONFIG.packageName：

const CONFIG = {
  packageName: 'your-custom-name',  // 修改这里
  // ...
};

自定义 CDN 路径

如果需要使用自定义 CDN 路径，可以在构建时设置环境变量：

VITE_BASE_URL=https://your-cdn.com/path/ pnpm run build:web

注意事项

Service Worker

CDN 部署时，Service Worker 的功能可能受限：

• Service Worker 只能在同源或 HTTPS 下运行
• 跨域 CDN 可能需要配置 CORS
• 某些 PWA 功能（如推送通知）可能不可用

缓存更新

CDN 可能有缓存延迟，发布新版本后：

• unpkg: 通常几分钟内更新
• jsDelivr: 可能需要 24 小时，可使用版本号强制更新

版本管理

建议使用版本号访问，确保一致性：

https://unpkg.com/aitu-app@0.5.14/index.html

与传统部署对比

特性	CDN 部署	自建服务器
成本	免费	需付费
配置	零配置	需配置
HTTPS	自动	需配置
全球加速	自带	需额外配置
自定义域名	不支持	支持
Service Worker	受限	完整支持

故障排除

资源 404

检查 index.html 中的路径是否都使用相对路径 ./。

样式/脚本加载失败

确认构建时 base 配置正确：

# 检查构建后的 index.html
cat dist/apps/web/index.html | grep -E 'href=|src='

npm 发布失败

1. 确认已登录 npm：npm whoami
2. 检查包名是否已被占用
3. 确认版本号已更新

相关命令

# 查看当前版本
npm view aitu-app version

# 查看所有版本
npm view aitu-app versions

# 取消发布（24小时内）
npm unpublish aitu-app@0.5.14