结论先行
四个站点统一到 Next.js 15 静态导出，由 Nginx 直接提供静态文件，线上不运行 Next.js 服务。上线只有三步：本机打包 → 上传一个 tar.gz → 服务器执行一条命令切换版本；回滚是另一条命令。
四站构建与静态检查通过，但登录、上传、聊天等真实业务仍需在服务器验收。以下按事实列出每一步和踩过的坑。
环境前提（一次性）
本机装 Node.js 22 或更新版本，四站依赖已安装。服务器为 Linux，装 Nginx、tar、supervisord，你的账号有对应目录写权限。
www、admin、im、passport 四个域名解析到正确服务器，80 端口开放。后端不变：API 8888、WebSocket 8080，头像媒体域名可访问。
Nginx 已把四站 root 指向 /workspace/deploy/{www,admin,im,passport}（一次性配置）。发布只替换这四个目录下的文件，不改 Nginx 配置、不重启后端。
详细步骤
1. 本机：生成发布包
在仓库根目录 sparrow-js 执行：
bash deploy/build-static.sh脚本依次构建 common、admin、im、passport（子站先执行 npm run copy 同步公共代码，再 npm run build），校验四站 out/index.html 后打包。
产物只有一个：artifacts/YYYYMMDDHHmmss.tar.gz，用本机时间命名，顶层是 admin im passport www 四个目录。同名文件不会覆盖，会直接报错。
2. 上传：只传一个文件
用 SFTP 把这个 tar.gz 传到服务器上的压缩包目录（环境变量 ARTIFACTS_DIR，默认是 deploy.sh 同级的 ../artifacts）。
不需要校验文件、不需要服务器脚本，只上传这一个包。
3. 服务器：一条命令切换
bash deploy/deploy.sh默认取时间戳最新的包。脚本先解压校验——拒绝越界路径、链接和特殊文件，检查四站 index.html 存在——再把四站整体替换到 /workspace/deploy/（默认，可用 DEPLOY_DIR 覆盖）。
看到 deploy完成：<包名> -> <目录> 即成功。Nginx 指向同一目录，静态文件即时生效，无需 reload。
4. 浏览器：确认真的可用
依次打开四个入口：主站、管理站、IM、Passport。切换中英文，进内页刷新；用真实账号测登录回跳、跨站登录与退出，测头像 / 文件上传，测 IM 收发和断线重连。
页面能打开但登录或聊天失败，是后端或跨域问题，重传静态文件解决不了。
5. 回滚：恢复上一版
bash deploy/deploy.sh rollback取时间戳第二新的包换回。至少要保留两个时间戳包，否则报错；首次上线没有上一版，需要运维恢复。
踩过的坑
- macOS 打包污染：本机 tar 会写入
._AppleDouble、.DS_Store和com.apple.provenance扩展属性，Linux 解压时报未知文件类型告警。脚本已用COPYFILE_DISABLE=1 --no-xattrs --exclude=.DS_Store处理，不要用手动 tar 命令替代。 - supervisord 中文注释：supervisord 按 ASCII 解析 supervisord.conf，注释含中文会报
'ascii' codec can't decode启动失败。配置文件注释一律用英文。 - supervisor 反复重试 FATAL：被监控进程必须前台运行——tomcat 用
catalina.sh run而非start（start 是守护进程，监控不到会一直重试）。用专属用户运行，重启后重新 chown / chmod，否则读不到环境变量。 - 文件上传超时：nginx 反代大文件时，把
proxy_connect_timeout / proxy_read_timeout / proxy_send_timeout调到 600。 - Node 版本：构建要求 Node 22+，低版本会在构建前直接报错退出。
总结
本机构建 → 上传一个 tar.gz → deploy.sh 切换 → 浏览器验收。出问题用 deploy.sh rollback。发布只换静态文件目录，不动 Nginx 配置和后端进程。