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:

Setting | Description | Type | Default value ||------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|-----------------|| STRAPI_TELEMETRY_DISABLED | Don't send telemetry usage data to Strapi | Boolean | false || STRAPI_LICENSE | The license key to activate the Enterprise Edition | String | undefined || NODE_ENV | Type of environment where the application is running.

production enables specific behaviors (see Node.js documentation for details) | String | 'development' || BROWSER | Open the admin panel in the browser after startup | Boolean | true || ENV_PATH | Path to the file that contains your environment variables | String | './.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_SOURCEMAPS | Forces the bundler to emit source-maps, which is helpful for debugging errors in the admin app. | boolean | false || FAST_REFRESH | (Only applies to webpack)
Use react-refresh to enable "Fast Refresh" for near-instant feedback while developing the Strapi admin panel. | boolean | true || HOST | Address the Strapi server listens on | String | 0.0.0.0 || PORT | Port used by the Strapi server | Number | 1337 || APP_KEYS | Comma-separated keys used to sign cookies and other secrets | String | auto-generated || API_TOKEN_SALT | Salt used when creating API tokens | String | auto-generated || ADMIN_JWT_SECRET | Secret for JWT tokens used in the admin panel | String | auto-generated || JWT_SECRET | Secret for JWT tokens generated by the Users & Permissions feature | String | auto-generated || TRANSFER_TOKEN_SALT | Salt used for transfer tokens by the Data Management feature | String | auto-generated || DATABASE_CLIENT | Database client to use (e.g., sqlite) | String | sqlite || DATABASE_FILENAME | Location of the SQLite database file | String | .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).

示例 .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:

.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:

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: