Skip to main content

环境配置和变量

🌐 Environment configuration and variables

Page summary:

Strapi 特定的环境变量和 .env usage 启用每个环境的配置，并且提供 env() 辅助工具来转换值。

Strapi 提供了特定的环境变量名称。在环境文件中定义它们（例如，.env）将使这些变量及其值在你的代码中可用。

🌐 Strapi provides specific environment variable names. Defining them in an environment file (e.g., .env) will make these variables and their values available in your code.

Tip

env() 工具可以用来获取环境变量的值和将变量转换为不同类型。

🌐 An env() utility can be used to retrieve the value of environment variables and cast variables to different types.

此外，可以为不同环境创建特定的配置。

🌐 Additionally, specific configurations for different environments can be created.

Strapi 的环境变量​

🌐 Strapi's environment variables

Strapi 提供以下环境变量：

🌐 Strapi provides the following environment variables:

SettingDescriptionTypeDefault value
STRAPI_TELEMETRY_DISABLEDDon't send telemetry usage data to StrapiBooleanfalse
ADMIN_PATHPath the admin panel is served under. Defaults to the pathname of admin.url and is also injected into the admin JS bundle at build time so the front end knows where it is mounted.String'/admin'
STRAPI_ADMIN_BACKEND_URLURL the admin panel uses to reach the back-end server. When the back end and the admin panel share the same origin, the value resolves to the pathname of server.url (typically '/'); otherwise it resolves to the full back-end URL. The value is injected into the admin JS bundle at build time, so override it before running strapi build if you need to pin a specific URL.Stringauto-derived
STRAPI_LICENSEThe license key to activate the Enterprise EditionStringundefined
NODE_ENVType of environment where the application is running.

production enables specific behaviors (see Node.js documentation for details)		String'development'
BROWSEROpen the admin panel in the browser after startupBooleantrue
ENV_PATHPath to the file that contains your environment variablesString'./.env'
STRAPI_PLUGIN_I18N_INIT_LOCALE_CODE

Optional		Initialization locale for the application, if the Internationalization (i18n) feature is installed and enabled on Content-Types (see Configuration of i18n in production environments)String'en'
STRAPI_ENFORCE_SOURCEMAPSForces the bundler to emit source-maps, which is helpful for debugging errors in the admin app.booleanfalse
FAST_REFRESH(Only applies to webpack)
Use react-refresh to enable "Fast Refresh" for near-instant feedback while developing the Strapi admin panel.		booleantrue
HOSTAddress the Strapi server listens onString0.0.0.0
PORTPort used by the Strapi serverNumber1337
APP_KEYSComma-separated keys used to sign cookies and other secretsStringauto-generated
API_TOKEN_SALTSalt used when creating API tokensStringauto-generated
ADMIN_JWT_SECRETSecret for JWT tokens used in the admin panel. Required when admin.serveAdminPanel is true (the default); can be omitted for API-only deployments running with serveAdminPanel: false.Stringauto-generated
JWT_SECRETSecret for JWT tokens generated by the Users & Permissions featureStringauto-generated
TRANSFER_TOKEN_SALTSalt used for transfer tokens by the Data Management featureStringauto-generated
DATABASE_CLIENTDatabase client to use (e.g., sqlite)Stringsqlite
DATABASE_FILENAMELocation of the SQLite database fileString.tmp/data.db
Tip

在环境变量名称前加上 STRAPI_ADMIN_ 会将该变量暴露给管理员前端（例如，STRAPI_ADMIN_MY_PLUGIN_VARIABLE 可以通过 process.env.STRAPI_ADMIN_MY_PLUGIN_VARIABLE 访问）。

🌐 Prefixing an environment variable name with STRAPI_ADMIN_ exposes the variable to the admin front end (e.g., STRAPI_ADMIN_MY_PLUGIN_VARIABLE is accessible through process.env.STRAPI_ADMIN_MY_PLUGIN_VARIABLE).

当管理员面板是从你的项目构建时，这个方法有效，例如在自托管部署中。Strapi Cloud 不会向管理员前端暴露 STRAPI_ADMIN_* 变量。

🌐 This works when the admin panel is built from your project, for example in self-hosted deployments. Strapi Cloud does not expose STRAPI_ADMIN_* variables to the admin front end.

示例 .env 文件​

🌐 Example .env file

在创建新项目时，Strapi CLI 会生成一个 .env 文件和一个 .env.example 文件。这些文件包含自动生成的安全密钥和类似于以下的数据库设置：

🌐 The Strapi CLI generates an .env and an .env.example file when creating a new project. The files contain automatically-generated security keys and database settings similar to the following:

.env.example
HOST=0.0.0.0
PORT=1337
APP_KEYS="toBeModified1,toBeModified2"
API_TOKEN_SALT=tobemodified
ADMIN_JWT_SECRET=tobemodified
TRANSFER_TOKEN_SALT=tobemodified
JWT_SECRET=tobemodified
ENCRYPTION_KEY=tobemodified

设置这些环境变量以实现与 sessions management 配置的安全认证：

🌐 Set these environment variables for secure authentication with sessions management configuration:

terminal
.env
# Admin authentication
ADMIN_JWT_SECRET=your-admin-secret-key

# Cookie domain (optional)
ADMIN_COOKIE_DOMAIN=yourdomain.com

# Users & Permissions JWT secret
JWT_SECRET=your-content-api-secret-key

# Users & Permissions session management
UP_JWT_MANAGEMENT=refresh  # or 'legacy-support'
UP_SESSIONS_ACCESS_TTL=604800  # 1 week in seconds
UP_SESSIONS_MAX_REFRESH_TTL=2592000  # 30 days in seconds
UP_SESSIONS_IDLE_REFRESH_TTL=604800  # 7 days in seconds
UP_SESSIONS_HTTPONLY=false  # true for HTTP-only cookies
UP_SESSIONS_COOKIE_NAME=strapi_up_refresh
UP_SESSIONS_COOKIE_SAMESITE=lax
UP_SESSIONS_COOKIE_PATH=/
UP_SESSIONS_COOKIE_SECURE=false  # true in production

环境配置​

🌐 Environment configurations

可以使用以下命名和结构约定创建配置：./config/env/{environment}/{filename}。当你需要针对特定环境的特定静态配置，并且使用环境变量不是最佳解决方案时，这非常有用。

🌐 Configurations can be created with the following naming and structure conventions: ./config/env/{environment}/{filename}. This is useful when you need specific static configurations for specific environments and using environment variables is not the best solution.

这些配置将合并到 ./config 文件夹中定义的基础配置中。环境基于 NODE_ENV 环境变量，默认值为 development。

🌐 These configurations will be merged into the base configurations defined in the ./config folder. The environment is based on the NODE_ENV environment variable, which defaults to development.

当使用 NODE_ENV=production 启动 Strapi 时，它会从 ./config/* 和 ./config/env/production/* 加载配置。在生产配置中定义的所有内容都会覆盖默认配置。结合环境变量，这种模式变得非常强大。

🌐 When starting Strapi with NODE_ENV=production it will load the configuration from ./config/* and ./config/env/production/*. Everything defined in the production configuration will override the default configuration. In combination with environment variables this pattern becomes really powerful.

例如，使用以下配置文件将为你提供启动服务器的各种选项：

🌐 For instance, using the following configuration files will give you various options to start the server:

./config/server.js

module.exports = {
  host: '127.0.0.1',
};
./config/env/production/server.js

module.exports = ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
});

使用这些配置文件，服务器将根据传递的环境变量在各个端口上启动：

🌐 With these configuration files the server will start on various ports depending on the environment variables passed:

terminal
yarn start                                   # uses host 127.0.0.1
NODE_ENV=production yarn start               # uses host defined in .env. If not defined, uses 0.0.0.0
HOST=10.0.0.1 NODE_ENV=production yarn start # uses host 10.0.0.1

要深入了解如何在代码中使用环境变量，请参考以下指南：

🌐 To learn deeper about how to use environment variables in your code, please refer to the following guide:

On this page