114 lines
3.6 KiB
Markdown
114 lines
3.6 KiB
Markdown
# 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`、`NEXT_PUBLIC_GTAG_ID`、`NEXT_PUBLIC_TRACKER_APP_ID`。
|
||
|
||
## 打包与部署
|
||
|
||
产物统一为仓库根目录的 **`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。
|
||
- 对接接口字段勿擅自改名映射；列表/详情直接用接口类型字段。
|