📝 文字 ● 初级更新于 2026-05-13

如何正确配置 Stripe API 密钥？

TL;DR：Stripe 提供四种密钥：pk_test、sk_test、pk_live、sk_live。可发布密钥（pk）放在客户端代码中，私密密钥（sk）只能放在环境变量里——绝不能出现在客户端代码中。在上线前使用测试密钥，上线时只需在一处（环境变量）替换为正式密钥，无需改动代码。

Stripe 提供四种密钥——可发布密钥和私密密钥，分为测试版和正式版。它们看起来相似，但不能互换使用。只需花五分钟读完本教程，就能避免两大常见 Stripe 事故：私密密钥泄露到公众，以及在测试模式下意外向真实银行卡收费。

每个凭据系统都有其独特的思维模型，Stripe 的设计算是其中较为出色的——一旦理解就会豁然开朗。它有两个维度。第一个维度是可见性：可发布密钥可以安全地放在前端（浏览器、移动应用）；私密密钥只能放在后端服务器上。第二个维度是环境：测试密钥对接沙箱环境，收费是虚拟的，不会产生真实资金流动；正式密钥对接生产环境，每笔交易都是真实资金。两两组合得到：pk_test_…、sk_test_…、pk_live_…、sk_live_…。

初学 Stripe 的开发者出错，几乎都源于混淆了这些密钥。私密密钥被提交到 GitHub 是最经典的事故——公开仓库中的私密密钥往往在推送后数分钟内就会被扫描工具发现。另一个常见事故是在演示时误用了正式密钥——导致某人的银行卡被真实扣款，而非测试扣款。两种事故都可以补救（Stripe 支持轮换密钥，退款也很快），但完全可以提前避免。

本教程涵盖：获取密钥、了解各密钥的使用场景，以及将密钥安全地添加到项目中而不会意外泄露。关于 webhooks 的配套教程会讲解你的服务器实际如何使用这些密钥。

你将学到什么

四种密钥各自的用途
在 Stripe 控制台中如何找到它们
如何存储密钥以避免进入 git
"测试模式切换"及其重要性
如何轮换已泄露的密钥

第 1 步：创建 Stripe 账户

提交业务资料前即可使用测试模式

在 dashboard.stripe.com 注册账户。注册流程很快——填写邮箱、密码和基本业务信息即可。注册完成后你会立即进入测试模式，拥有完整的 API 访问权限和测试密钥。开始集成不需要提交任何验证文件。

正式模式（真实收费）需要 Stripe 验证你的业务信息：公司名称、地址、税务 ID、银行账户。这些可以等到你准备好接受真实付款时再办理。目前，测试模式就是一切。

第 2 步：找到密钥

开发者 → API 密钥

在 Stripe 控制台中，点击顶部导航（或菜单）中的开发者，再点击 API 密钥。你会看到当前模式下的两个密钥：

可发布密钥——以 pk_ 开头。完整显示。可以放在前端代码中、打包进 JavaScript bundle 或暴露在 URL 里。它能标识你的 Stripe 账户，但无法读取敏感数据或独自转移资金。
私密密钥——以 sk_ 开头。默认隐藏，点击"显示"可查看。绝对不能放在任何非可信方能看到的地方——包括前端代码、公开仓库、错误日志、返回给客户端的 JSON 响应。持有此密钥的人可以向银行卡收费、退款、创建客户，并读取所有交易记录。

测试模式的密钥名称中包含 test（pk_test_…、sk_test_…）。切换到正式模式并完成验证后可见的正式密钥则包含 live（pk_live_…、sk_live_…）。

第 3 步：理解测试/正式模式切换

Stripe 界面中最重要的元素

每个 Stripe 控制台页面右上角都有一个切换按钮，显示测试模式（橙色）或正式模式（默认）。该切换控制：

API 密钥页面显示哪些密钥。
哪些 webhook 会触发（测试模式和正式模式各有独立的端点配置）。
你能看到哪些客户和收费记录——它们是相互独立的数据集。
哪些测试卡号有效（测试模式接受 4242 4242 4242 4242；正式模式不接受）。

如果你在开发环境中遇到"客户不存在"的错误，很可能是因为你处于正式模式，却在查找测试模式下的客户（反之亦然）。先检查切换状态；十有八九问题就在这里。

橙色测试模式横幅是你的好朋友。处于测试模式时，Stripe 会在每个页面顶部显示一条橙色横幅。养成扫一眼的习惯。如果你看不到它，却要进行可能造成影响的操作（退款、取消等），说明你处于正式模式——请放慢脚步，谨慎确认。

第 4 步：将密钥放入项目

使用环境变量，而非源文件

三条原则：

绝不硬编码私密密钥。使用环境变量。Node 中：process.env.STRIPE_SECRET_KEY。Python 中：os.environ["STRIPE_SECRET_KEY"]。各语言模式相同。
绝不提交 .env 文件。将 .env 加入 .gitignore。使用包含占位值的 .env.example 来记录环境变量，并提交该文件。
开发环境使用测试密钥，生产环境使用正式密钥。你的生产服务器需要 STRIPE_SECRET_KEY=sk_live_…；开发机上使用 sk_test_…。变量名相同，不同环境的值不同。

对于前端代码，可发布密钥可以打包进 bundle，但最好在构建时通过环境变量注入（NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY、VITE_STRIPE_PUBLISHABLE_KEY 等）。这主要是为了整洁——该值本身并不保密，但这样你在切换测试与正式密钥时无需重新构建代码。

第 5 步：验证是否正常工作

一条 curl 命令，一个断言

在你的后端（或已设置环境变量的终端）中执行：

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -d amount=2000 \
  -d currency=usd \
  -d "source=tok_visa" \
  -d "description=test charge"

如果密钥有效，你会收到包含收费对象的 JSON 响应。如果无效，会收到带有明确错误信息的 401 响应。tok_visa 是 Stripe 的测试 token；该收费是虚拟的，不会产生真实资金流动。

第 6 步：当（不是如果）你泄露了密钥

轮换很快，请做最坏的假设

迟早你（或你的队友）会泄露一个私密密钥——提交到公开仓库、粘贴到共享屏幕的 Slack 频道、出现在别人截图的浏览器开发工具中。解决方法：

在 Stripe 控制台中，选择开发者 → API 密钥 → 轮换私密密钥。旧密钥立即失效，Stripe 会颁发新的密钥。
在所有使用该密钥的环境（生产、预发布、开发）中更新 STRIPE_SECRET_KEY 并重新部署。
审查从泄露到轮换这段时间内账户是否有可疑活动。Stripe 的日志让这项工作非常方便。

不必为了需要轮换密钥而感到羞耻。每个人早晚都会遇到这种情况。成熟的应对方式是"轮换、审查、继续前行"——而不是"恐慌、删账户、从头来过"。

GitHub 会扫描泄露的密钥。如果你将私密密钥推送到公开仓库，Stripe 通常会在数分钟内将其失效——GitHub 会通知 Stripe，Stripe 会自动轮换密钥。这很有帮助（最坏情况的时间窗口很短），但这不能替代防止泄露的根本措施。不要依赖这张安全网。

第 7 步：受限密钥（生产环境安全规范）

"完整私密密钥"并非唯一选项

在生产环境中，可以考虑创建受限密钥——将密钥限定在特定资源的权限范围内（例如"可以创建收费，但无法读取客户信息"）。在控制台中：开发者 → API 密钥 → 受限密钥 → 创建。

如果你的应用只需要创建 Checkout Session，那么拥有该权限的受限密钥比完整私密密钥更安全。万一泄露，造成的损失也仅限于该密钥被授权的操作范围。