jha-1046-hjsq-web

海角社区 H5 / Web（Next.js 16 · React 19 · pnpm）。

环境要求

• Node.js >= 20.9（打包 Linux sharp 推荐 22，npm >= 10.9.2）
• pnpm 10+
• 本机 SSH 私钥（默认 ~/.ssh/id_ed25519），需已加入对应服务器 authorized_keys

本地开发

pnpm install
pnpm dev          # development.env
pnpm dev:test     # test.env

浏览器打开 http://localhost:26122。

常用命令：

命令	说明
pnpm lint	ESLint
pnpm build	正式环境构建
pnpm build:test	测试环境构建

环境配置

配置文件在 config/（可另加 *.local.env，勿提交密钥）：

文件	用途
config/development.env	本地开发
config/test.env	测试构建 / 测试服
config/production.env	正式构建 / 正式服

关键变量示例：API_PROXY_TARGET / NEXT_PUBLIC_API_BASE_URL、PORT、NEXT_PUBLIC_SITE_URL。

打包与部署

产物统一为仓库根目录的 web_hjsq_h5.tar.gz（及 web_hjsq_h5.md5）。

流程：build → standalone（start.mjs）→ 补 Linux sharp → tar.gz → scp → 远程更新脚本。

测试服

默认：root@172.104.181.99:22889 → /server/web_hjsq/h5，远程执行 run.sh；应用端口 26122（config/test.env）。

pnpm pack:gz:test        # 打包并推送（等同 pnpm deploy:test）
pnpm pack:gz:test:only   # 只打包，不上传

等价远程步骤：

scp -P 22889 web_hjsq_h5.tar.gz root@172.104.181.99:/server/web_hjsq/h5
ssh -p 22889 root@172.104.181.99 "cd /server/web_hjsq/h5 && bash run.sh"

可选环境变量：DEPLOY_TEST_HOST、DEPLOY_TEST_DIR、DEPLOY_TEST_REMOTE_SCRIPT、DEPLOY_SSH_IDENTITY、DEPLOY_SCP_PORT、DEPLOY_SSH_PORT。

正式服

默认：server@34.92.204.175:22889 → /home/server/web_hjsq/h5，远程执行 rsupdate.sh。

pnpm pack:gz             # 打包并推送（等同 pnpm deploy:prod）
pnpm pack:gz:only        # 只打包，不上传（等同 pnpm package:prod）

等价远程步骤：

scp -P 22889 web_hjsq_h5.tar.gz server@34.92.204.175:/home/server/web_hjsq/h5
ssh -p 22889 server@34.92.204.175 "bash /home/server/web_hjsq/h5/rsupdate.sh"

可选环境变量：DEPLOY_JUMP_HOST、DEPLOY_JUMP_DIR、DEPLOY_REMOTE_SCRIPT、DEPLOY_SSH_IDENTITY、DEPLOY_SCP_PORT、DEPLOY_SSH_PORT、DEPLOY_TARGET_ARCH、DEPLOY_TARGET_LIBC。

服务器启动注意

Standalone 必须用包内入口，不要 next start：

node start.mjs
# 或
pm2 start ecosystem.config.cjs

缺少 .next/BUILD_ID 时会出现 production-start-no-build-id。测试构建本地目录仍是 .next-test，但打进 web_hjsq_h5.tar.gz 后会规范为 .next。若解压报 File exists（pnpm 软链冲突），先清理旧 node_modules 再跑更新脚本。

目录速览

config/                 # 各环境 env
scripts/
  next-env.ts           # 按环境跑 next
  package-standalone.ts # 整理 standalone + start.mjs
  prepare-production-runtime.ts  # 补 Linux sharp
  package-prod.sh       # 正式一键打包/推送
  package-test.sh       # 测试一键打包/推送
deploy_prod.sh / deploy_test.sh
src/                    # 应用代码

约定（简要）

• 接口图片展示走 DecryptedImage / 解密链路，勿裸用接口 URL。
• 带 slug 的资源路由优先用 slug，不要用数字 id。
• 对接接口字段勿擅自改名映射；列表/详情直接用接口类型字段。