# 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`

## 本地开发

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

浏览器打开 [http://localhost:26122](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`）。

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

等价远程步骤：

```bash
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`。

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

等价远程步骤：

```bash
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`：

```bash
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。
- 对接接口字段勿擅自改名映射；列表/详情直接用接口类型字段。