secrets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Secrets Management

密钥管理

Core Rules

核心规则

NEVER hardcode secrets, API keys, OAuth2 client IDs/secrets, tokens, passwords, or credentials in source code
ALWAYS store secrets in
```
.env
```
files (or platform-native equivalents like
```
local.properties
```
,
```
.xcconfig
```
)
ALWAYS load secrets from environment variables at runtime
ALWAYS add
```
.env
```
to
```
.gitignore
```
before first commit
ALWAYS provide a
```
.env.example
```
documenting required variables (with empty values)

绝对不要硬编码密钥、API密钥、OAuth2客户端ID/密钥、令牌、密码或凭证到源代码中
始终将密钥存储在
```
.env
```
文件中（或平台原生等效文件，如
```
local.properties
```
、
```
.xcconfig
```
）
始终在运行时从环境变量加载密钥
始终在首次提交前将
```
.env
```
添加到
```
.gitignore
```
中
始终提供一个
```
.env.example
```
文件，记录所需变量（值留空）

Workflow

工作流程

When Writing Code That Uses Secrets

编写使用密钥的代码时

Detect the platform/framework from the project files
Check if
.env
and
.gitignore
are set up — if not, create them
Load secrets from environment variables using the platform's standard pattern
Never use string literals for secret values — always reference
```
process.env.*
```
,
```
os.getenv()
```
, etc.
Add the variable name to
```
.env.example
```
with an empty value and a descriptive comment
Run the scan script to verify no secrets leaked:
```
python3 scripts/scan_secrets.py .
```

从项目文件中识别平台/框架
检查
.env
和
.gitignore
是否已配置——如果没有，创建它们
使用平台的标准方式从环境变量加载密钥
切勿使用字符串字面量存储密钥值——始终引用
```
process.env.*
```
、
```
os.getenv()
```
等
将变量名添加到
```
.env.example
```
中，值留空并添加描述性注释
运行扫描脚本以验证没有密钥泄露：
```
python3 scripts/scan_secrets.py .
```

When Setting Up a New Project

搭建新项目时

Create
```
.env
```
with required variables
Create
```
.env.example
```
mirroring
```
.env
```
structure with empty values (use env-example-template as a starting point)
Add secret-related entries to
```
.gitignore
```
(use gitignore-secrets as reference)
Install the
```
.env
```
loading library for the platform
Add loading code at the application entry point

创建包含所需变量的
```
.env
```
文件
创建与
```
.env
```
结构一致的
```
.env.example
```
文件，值留空（可参考env-example-template作为模板）
将与密钥相关的条目添加到
```
.gitignore
```
中（可参考gitignore-secrets）
安装对应平台的
```
.env
```
加载库
在应用入口处添加密钥加载代码

When Reviewing Code

代码审查时

Run

python3 scripts/scan_secrets.py <project-directory>

to detect:

Hardcoded API keys, tokens, and passwords
OAuth2 client secrets in source
AWS keys, Google API keys, Stripe keys, GitHub tokens
Embedded private keys
Connection strings with credentials
Missing
```
.gitignore
```
entries for
```
.env
```
Missing
```
.env.example
```

运行

python3 scripts/scan_secrets.py <项目目录>

以检测：

硬编码的API密钥、令牌和密码
源代码中的OAuth2客户端密钥
AWS密钥、Google API密钥、Stripe密钥、GitHub令牌
嵌入的私钥
包含凭证的连接字符串
```
.gitignore
```
中缺少
```
.env
```
的条目
缺少
```
.env.example
```
文件

Quick Reference by Platform

各平台快速参考

For platform-specific

.env

loading patterns (install, load, access, framework variants), see references/platforms.md. Covers:

JavaScript/TypeScript: Node.js, Next.js, Vite, React, Nuxt, Remix, Express, NestJS
Python: Django, Flask, FastAPI
Ruby: Rails
Go: godotenv
Java/Kotlin: Spring Boot
PHP: Laravel
Rust: dotenvy
Swift/iOS: Xcode .xcconfig, Vapor
Android/Kotlin: local.properties + BuildConfig
Flutter/Dart: flutter_dotenv
C#/.NET: DotNetEnv, User Secrets
Docker: --env-file, docker-compose env_file
CI/CD: GitHub Actions, GitLab CI, Vercel, Netlify, AWS, GCP, Azure

有关各平台特定的

.env

加载方式（安装、加载、访问、框架变体），请查看references/platforms.md。涵盖以下平台：

JavaScript/TypeScript: Node.js, Next.js, Vite, React, Nuxt, Remix, Express, NestJS
Python: Django, Flask, FastAPI
Ruby: Rails
Go: godotenv
Java/Kotlin: Spring Boot
PHP: Laravel
Rust: dotenvy
Swift/iOS: Xcode .xcconfig, Vapor
Android/Kotlin: local.properties + BuildConfig
Flutter/Dart: flutter_dotenv
C#/.NET: DotNetEnv, User Secrets
Docker: --env-file, docker-compose env_file
CI/CD: GitHub Actions, GitLab CI, Vercel, Netlify, AWS, GCP, Azure

Anti-Patterns to Block

需避免的反模式

Never generate code like:

undefined

切勿生成如下代码：

undefined

BAD - hardcoded secrets

api_key = "sk-1234567890abcdef" client_secret = "my-oauth-secret" DATABASE_URL = "postgres://user:password@host/db" const token = "ghp_xxxxxxxxxxxxxxxxxxxx";


Always generate code like:

api_key = "sk-1234567890abcdef" client_secret = "my-oauth-secret" DATABASE_URL = "postgres://user:password@host/db" const token = "ghp_xxxxxxxxxxxxxxxxxxxx";


应始终生成如下代码：

GOOD - loaded from environment

api_key = os.getenv("API_KEY") const token = process.env.GITHUB_TOKEN;

undefined

api_key = os.getenv("API_KEY") const token = process.env.GITHUB_TOKEN;

undefined

Mobile Platform Notes

移动平台注意事项

iOS: Use
```
.xcconfig
```
files (gitignored) referenced from Xcode build settings — not
```
.env
```
at runtime
Android: Use
```
local.properties
```
(gitignored by default) injected via
```
buildConfigField
```
— not
```
.env
```
at runtime
Flutter:
```
flutter_dotenv
```
bundles
```
.env
```
into the app binary. For truly sensitive secrets, use a backend proxy instead of embedding in the mobile app

iOS：使用
```
.xcconfig
```
文件（已添加到git忽略），从Xcode构建设置中引用——切勿在运行时使用
```
.env
```
Android：使用
```
local.properties
```
（默认已添加git忽略），通过
```
buildConfigField
```
注入——切勿在运行时使用
```
.env
```
Flutter：
```
flutter_dotenv
```
会将
```
.env
```
打包到应用二进制文件中。对于真正敏感的密钥，请使用后端代理，而非嵌入到移动应用中