From 6f4e287ca39644f3c2f61b38872028b4886c78de Mon Sep 17 00:00:00 2001
From: eric <xiaoshuang.eric@gmail.com>
Date: Thu, 12 Mar 2026 04:05:58 -0500
Subject: [PATCH] 's'

---
 README.md                          |  1 +
 docs/DEPLOYMENT.md                 | 61 ++++++++++++++++++++++++++++++
 scripts/generate-encryption-key.js | 13 +++++++
 3 files changed, 75 insertions(+)
 create mode 100644 docs/DEPLOYMENT.md
 create mode 100644 scripts/generate-encryption-key.js

diff --git a/README.md b/README.md
index d7e03b1..112b229 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,7 @@ ZPAY、PocketBase、MinIO 配置与 `C:\project\digital` 保持一致，复制 `
 
 | 变量 | 说明 | 默认值 |
 |------|------|--------|
+| `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` | Server Actions 加密密钥（**生产部署必设**，避免 "Failed to find Server Action"） | 无，需用 `node scripts/generate-encryption-key.js` 生成 |
 | `NEXT_PUBLIC_POCKETBASE_URL` | PocketBase 地址 | `https://pocketbase.hackrobot.cn` |
 | `NEXT_PUBLIC_API_URL` / `PAYMENT_API_URL` | payjsapi 地址 | `https://api.hackrobot.cn` |
 | `PAYMENT_PROVIDER` | 支付提供商（payjsapi 环境变量） | `xorpay` / `zpay` |
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
new file mode 100644
index 0000000..951e8ea
--- /dev/null
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,61 @@
+# 部署说明
+
+## 解决 "Failed to find Server Action" 错误
+
+在 PM2 自托管 Next.js 时，若出现以下错误：
+
+```
+Error: Failed to find Server Action. This request might be from an older or newer deployment.
+```
+
+**原因**：Next.js 为 Server Actions 使用加密密钥，每次构建会重新生成。部署后客户端可能仍缓存旧版本 JS，导致请求的 action ID 与服务器不匹配。
+
+**解决方案**：在**构建时**设置固定加密密钥 `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY`，使多次部署使用相同密钥。
+
+### 步骤
+
+1. **生成密钥**（仅需执行一次，之后复用同一密钥）：
+
+   ```bash
+   node scripts/generate-encryption-key.js
+   ```
+
+2. **在构建前设置环境变量**：
+
+   ```bash
+   export NEXT_SERVER_ACTIONS_ENCRYPTION_KEY="<上一步输出的 base64 字符串>"
+   pnpm build
+   ```
+
+   或在 `.env` / `.env.production` 中添加：
+
+   ```
+   NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=<base64 字符串>
+   ```
+
+3. **重新构建并重启**：
+
+   ```bash
+   pnpm build
+   pm2 restart vip
+   ```
+
+4. **建议用户清除缓存**：部署后若仍有问题，可让用户执行硬刷新（Ctrl+Shift+R）或清除浏览器缓存。
+
+---
+
+## PM2 部署流程
+
+```bash
+# 1. 安装依赖
+pnpm install
+
+# 2. 设置 NEXT_SERVER_ACTIONS_ENCRYPTION_KEY 后构建
+export NEXT_SERVER_ACTIONS_ENCRYPTION_KEY="你的密钥"
+pnpm build
+
+# 3. 启动
+pnpm start
+# 或使用 PM2
+pm2 start npm --name vip -- start
+```
diff --git a/scripts/generate-encryption-key.js b/scripts/generate-encryption-key.js
new file mode 100644
index 0000000..059136b
--- /dev/null
+++ b/scripts/generate-encryption-key.js
@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * 生成 Next.js Server Actions 加密密钥
+ * 用于解决 "Failed to find Server Action" 部署错误
+ *
+ * 用法: node scripts/generate-encryption-key.js
+ * 将输出的 base64 字符串设置为环境变量 NEXT_SERVER_ACTIONS_ENCRYPTION_KEY
+ * 在构建时设置（pnpm build 前 export 或 .env 中配置）
+ */
+const crypto = require("crypto");
+const key = crypto.randomBytes(32).toString("base64");
+console.log("将以下值设置为 NEXT_SERVER_ACTIONS_ENCRYPTION_KEY：\n");
+console.log(key);