diff --git a/unipay/init.py b/unipay/init.py
index a1c104c..f36cf75 100644
--- a/unipay/init.py
+++ b/unipay/init.py
@@ -65,6 +65,12 @@ def _build_provider_conf(provider_name: str) -> dict:
 		with open(privkey_path, "rb") as f:
 			conf["private_key_pem"] = f.read()
 		del conf["private_key_pem_file"]
+		# 校验 API v3 密钥（AES-256-GCM 需要 32 字节）
+		api_v3_key = conf.get("api_v3_key", "")
+		if not api_v3_key or api_v3_key in ("None", "none", ""):
+			raise ValueError(f"环境变量 WXP_API_V3_KEY 未设置或为占位符: {api_v3_key!r}")
+		if len(api_v3_key.encode()) != 32:
+			raise ValueError(f"WXP_API_V3_KEY 长度应为32字节(用于AES-256-GCM), 当前: {len(api_v3_key.encode())}字节")
 
 	elif provider_name == "alipay":
 		priv_path = conf.get("app_private_key_pem_file", "")