⚡

Bknd环境变量配置Skill bknd-env-config

此技能用于配置 Bknd 项目的环境变量，涵盖创建 .env 文件、管理秘密、环境变量注入到配置中，以及平台特定的设置。适用于开发和生产环境，提升应用安全性和部署灵活性。关键词：环境变量配置、秘密管理、Bknd 框架、DevOps 部署、云原生应用。

DevOps 0 次安装 0 次浏览 更新于 3/8/2026

名称：bknd-env-config 描述：在配置 Bknd 项目的环境变量时使用。涵盖 .env 文件、秘密管理、环境注入配置、平台特定变量和生产安全。

环境变量配置

为 Bknd 应用程序配置开发和生产环境变量。

前提条件

  • Bknd 项目已初始化（存在 bknd.config.ts）
  • 了解您的部署目标（本地、Cloudflare、Vercel 等）

何时使用 UI 模式

  • 通过管理面板查看当前配置
  • 不适用于环境变量 - 所有操作都通过代码/文件完成

何时使用代码模式

  • 创建 .env 文件
  • 在 bknd.config.ts 中配置秘密
  • 设置平台特定的环境变量
  • 所有环境配置任务

代码方法

步骤 1：创建 .env 文件

在项目根目录创建 .env：

# 数据库
DB_URL=file:data.db
DB_TOKEN=

# 认证
JWT_SECRET=你的密钥-这里最小32字符

# 服务器
PORT=3000

# 开发
LOCAL=true

步骤 2：在配置中注入环境变量

通过 bknd.config.ts 中的 env 参数访问环境变量：

import type { CliBkndConfig } from "bknd";

export default {
  app: (env) => ({
    connection: {
      url: env.DB_URL ?? "file:data.db",
      authToken: env.DB_TOKEN,
    },
    auth: {
      jwt: {
        secret: env.JWT_SECRET ?? "dev-secret-change-in-prod",
      },
    },
  }),
} satisfies CliBkndConfig;

env 参数接收从 .env 文件和系统环境加载的所有环境变量。

步骤 3：使用 .dev.vars 进行开发覆盖（可选）

Bknd 按顺序加载环境文件（后加载的优先级更高）：

  1. .env - 基础配置
  2. .dev.vars - 开发特定覆盖（Cloudflare 风格）

创建 .dev.vars 用于本地开发覆盖：

# .dev.vars - 仅开发，覆盖 .env
DB_URL=:memory:
JWT_SECRET=dev-only-secret

常见环境变量

数据库

变量 描述 示例
DB_URL 数据库连接 URL file:data.db, libsql://db.turso.io
DB_TOKEN LibSQL/Turso 认证令牌 eyJhbGciOiJFZERTQSIs...

认证

变量 描述 示例
JWT_SECRET JWT 签名密钥（最小32字符） your-very-long-secret-key-here
GOOGLE_CLIENT_ID Google OAuth 客户端 ID 123456.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET Google OAuth 密钥 GOCSPX-xxx
GITHUB_CLIENT_ID GitHub OAuth 客户端 ID Iv1.abc123
GITHUB_CLIENT_SECRET GitHub OAuth 密钥 secret_xxx

媒体/存储

变量 描述 示例
S3_ACCESS_KEY S3/R2 访问密钥 AKIAIOSFODNN7EXAMPLE
S3_SECRET_KEY S3/R2 秘密密钥 wJalrXUtnFEMI/K7MDENG/...
S3_ENDPOINT S3 兼容端点 https://bucket.s3.region.amazonaws.com
CLOUDINARY_CLOUD_NAME Cloudinary 云名称 my-cloud
CLOUDINARY_API_KEY Cloudinary API 密钥 123456789012345
CLOUDINARY_API_SECRET Cloudinary API 秘密 abcdefghijk...

服务器

变量 描述 默认值
PORT 服务器端口 3000
LOCAL 禁用遥测 -
NODE_ENV / ENVIRONMENT 环境模式 development

完整配置示例

import type { CliBkndConfig } from "bknd";
import { em, entity, text } from "bknd";

const schema = em({
  posts: entity("posts", { title: text().required() }),
});

export default {
  app: (env) => ({
    // 数据库
    connection: {
      url: env.DB_URL ?? "file:data.db",
      authToken: env.DB_TOKEN,
    },

    // 生产标志
    isProduction: env.NODE_ENV === "production",

    // 将所有秘密传递给应用
    secrets: env,
  }),

  config: {
    data: schema.toJSON(),

    // 使用基于环境的秘密进行认证
    auth: {
      enabled: true,
      jwt: {
        secret: env.JWT_SECRET,
        issuer: "my-app",
      },
      strategies: {
        password: { enabled: true },
        google: env.GOOGLE_CLIENT_ID ? {
          config: {
            name: "google",
            type: "oidc",
            client: {
              client_id: env.GOOGLE_CLIENT_ID,
              client_secret: env.GOOGLE_CLIENT_SECRET,
            },
          },
        } : undefined,
      },
    },

    // 使用基于环境的适配器配置进行媒体处理
    media: {
      enabled: true,
      adapter: {
        type: "s3",
        config: {
          access_key: env.S3_ACCESS_KEY,
          secret_access_key: env.S3_SECRET_KEY,
          url: env.S3_ENDPOINT,
        },
      },
    },
  },
} satisfies CliBkndConfig;

平台特定配置

Cloudflare Workers/Pages

使用 wrangler.toml 用于非秘密变量，仪表板用于秘密：

# wrangler.toml
[vars]
ENVIRONMENT = "production"

通过 CLI 设置秘密：

npx wrangler secret put JWT_SECRET
npx wrangler secret put DB_TOKEN

在配置中访问：

import type { CloudflareBkndConfig } from "bknd/adapter/cloudflare";

export default {
  app: (env) => ({
    connection: env.DB,  // D1 绑定
    isProduction: env.ENVIRONMENT === "production",
    secrets: env,
  }),
} satisfies CloudflareBkndConfig;

Vercel

使用 Vercel 仪表板或 CLI 设置环境变量：

vercel env add JWT_SECRET production
vercel env add DB_URL production

或使用 .env.local 进行本地开发（由 Next.js 自动加载）：

# .env.local
DB_URL=file:data.db
JWT_SECRET=dev-secret

Docker

通过 docker-compose 或 -e 标志传递：

# docker-compose.yml
services:
  app:
    environment:
      - DB_URL=file:/data/app.db
      - JWT_SECRET=${JWT_SECRET}
    env_file:
      - .env.production

生成 .env 模板

使用 CLI 从配置生成环境变量模板：

# 输出所需秘密作为模板
npx bknd secrets --template --format env

# 保存到文件
npx bknd secrets --template --format env --out .env.example

这会创建一个没有实际值的模板，安全用于版本控制。

同步秘密选项

在配置更改时自动生成 .env.example：

export default {
  syncSecrets: {
    enabled: true,
    outFile: ".env.example",
    format: "env",  // 或 "json"
  },
  app: (env) => ({ ... }),
} satisfies CliBkndConfig;

基于环境的功能标志

根据环境有条件地启用功能：

export default {
  app: (env) => ({
    connection: { url: env.DB_URL ?? "file:data.db" },
  }),
  config: {
    auth: {
      enabled: true,
      // 仅在生产环境中启用 OAuth（需要秘密）
      strategies: {
        password: { enabled: true },
        google: env.GOOGLE_CLIENT_ID ? {
          config: {
            name: "google",
            type: "oidc",
            client: {
              client_id: env.GOOGLE_CLIENT_ID,
              client_secret: env.GOOGLE_CLIENT_SECRET,
            },
          },
        } : undefined,
      },
    },
    // 仅在 S3 访问密钥存在时启用 S3 媒体
    media: env.S3_ACCESS_KEY ? {
      enabled: true,
      adapter: {
        type: "s3",
        config: {
          access_key: env.S3_ACCESS_KEY,
          secret_access_key: env.S3_SECRET_KEY,
          url: env.S3_ENDPOINT,
        },
      },
    } : {
      enabled: false,
    },
  },
} satisfies CliBkndConfig;

数据库连接优先级

Bknd 按以下顺序解析数据库连接：

  1. --db-url CLI 参数
  2. 配置文件 connection.url
  3. --memory 标志（使用 :memory:）
  4. DB_URL 环境变量
  5. 回退：file:data.db

验证

检查环境加载：

# 服务器日志显示连接来源
npx bknd run
# 查找："使用来自 ... 的连接"

测试环境注入：

// 临时在配置中记录环境变量
app: (env) => {
  console.log("加载的环境变量：", Object.keys(env));
  return { ... };
},

验证秘密命令：

npx bknd secrets --template

常见问题

.env 未加载

问题： 配置中环境变量未定义

修复： 检查文件位置和格式：

# .env 必须在项目根目录（与 bknd.config.ts 同级）
ls -la .env

# 值周围不要加引号
DB_URL=file:data.db     # 正确
DB_URL="file:data.db"   # 可能导致问题

JWT_SECRET 太短

问题： 认证失败或警告弱密钥

修复： 使用最小32字符：

# 生成安全密钥
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# 或
openssl rand -hex 32

秘密在版本控制中

问题： 提交了包含真实秘密的 .env

修复：

# 添加到 .gitignore
echo ".env" >> .gitignore
echo ".env.local" >> .gitignore
echo ".dev.vars" >> .gitignore

# 如果已提交，从 git 历史中移除
git rm --cached .env

平台环境变量不可用

问题： 部署应用中 env.VAR 未定义

修复： 平台特定设置：

  • Vercel： 通过仪表板或 vercel env add 添加
  • Cloudflare： 通过 wrangler secret put 或仪表板添加
  • Docker： 检查 compose 文件中的 environment: 或 env_file:

生产中使用了错误回退

问题： 在生产环境中使用开发默认值

修复： 快速失败而不是回退：

app: (env) => {
  if (!env.JWT_SECRET && env.NODE_ENV === "production") {
    throw new Error("生产中需要 JWT_SECRET");
  }
  return {
    auth: {
      jwt: { secret: env.JWT_SECRET ?? "dev-only" },
    },
  };
},

应该做的和不应该做的

应该做：

  • 使用 .env.example 作为模板（无真实值）
  • 使用加密安全随机性生成 JWT_SECRET
  • 在生产中使用平台特定的秘密管理
  • 在应用启动时验证所需秘密
  • 使用 syncSecrets 保持 .env.example 更新

不应该做：

  • 提交包含真实秘密的 .env
  • 使用弱或短的 JWT 秘密
  • 在配置文件中硬编码秘密
  • 跨环境使用相同秘密
  • 记录包含秘密的环境变量

相关技能

  • bknd-local-setup - 初始项目设置
  • bknd-setup-auth - 配置认证
  • bknd-oauth-setup - OAuth 提供商配置
  • bknd-storage-config - 存储适配器配置
  • bknd-production-config - 生产配置
  • bknd-deploy-hosting - 部署选项