环境配置与变量

页面摘要： Strapi 特定的环境变量和 .env 用法支持按环境进行配置，并提供 env() 辅助函数用于类型转换。

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

TIP

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

Strapi 的环境变量 {#strapi}

Strapi 提供以下环境变量：

Setting	Description	Type	Default value
`STRAPI_TELEMETRY_DISABLED`	不向 Strapi 发送遥测使用数据	`Boolean`	`false`
`ADMIN_PATH`	管理面板所挂载的路径。默认为 `admin.url` 的路径名，并在构建时注入到管理面板 JS bundle 中，以便前端知道其挂载位置。	`String`	`'/admin'`
`STRAPI_ADMIN_BACKEND_URL`	管理面板用于访问后端服务器的 URL。当后端与管理面板共享同一来源时，该值解析为 `server.url` 的路径名（通常为 `'/'`）；否则解析为完整的后端 URL。该值在构建时被注入到管理面板 JS bundle 中，因此如果你需要固定特定 URL，请在运行 `strapi build` 之前覆盖它。	`String`	`auto-derived`
`STRAPI_LICENSE`	用于激活企业版（Enterprise Edition）的许可证密钥	`String`	`undefined`
`NODE_ENV`	应用程序运行所在的环境类型。

TIP

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

当管理面板从你的项目构建时（例如自托管部署），此方式有效。Strapi Cloud 不会将 STRAPI_ADMIN_* 变量暴露给管理面板前端。

`.env` 文件示例

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

.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

.env

变量可能因创建项目时选择的选项而异。

# Server
HOST=0.0.0.0
PORT=1337

# Secrets
APP_KEYS=appkeyvalue1,appkeyvalue2,appkeyvalue3,appkeyvalue4
API_TOKEN_SALT=anapitokensalt
ADMIN_JWT_SECRET=youradminjwtsecret
TRANSFER_TOKEN_SALT=transfertokensaltvalue
ENCRYPTION_KEY=yourencryptionkey

# Database
DATABASE_CLIENT=sqlite
DATABASE_HOST=
DATABASE_PORT=
DATABASE_NAME=
DATABASE_USERNAME=
DATABASE_PASSWORD=
DATABASE_SSL=false
DATABASE_FILENAME=.tmp/data.db

为配合会话管理配置设置以下环境变量以进行安全身份验证：

# 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

环境配置

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

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

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

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

JavaScript


module.exports = {
  host: '127.0.0.1',
};


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

TypeScript


export default ({ env }) => ({
  host: '127.0.0.1',
});


export default ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
});

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

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

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

访问并转换变量 — 了解如何使用 env() 工具访问并转换环境变量。

环境配置与变量

Strapi 的环境变量 {#strapi}

.env 文件示例

环境配置

`.env` 文件示例