菜鸟教程
教程 hono tutorial

Bindings 与环境变量

Hono 的 Bindings 用来描述运行时提供给应用的环境变量和平台绑定。这个概念在 Cloudflare Workers 中尤其常见。

Cloudflare Workers Bindings

在 Workers 中，环境变量、KV、D1、R2 等绑定都通过 c.env 访问：

ts 
import { Hono } from 'hono'

type Bindings = {
  API_TOKEN: string
  DB: D1Database
}

const app = new Hono<{ Bindings: Bindings }>()

app.get('/config', (c) => {
  return c.json({
    hasToken: Boolean(c.env.API_TOKEN),
  })
})

app.get('/users', async (c) => {
  const result = await c.env.DB.prepare('SELECT id, name FROM users').all()
  return c.json(result.results)
})

export default app

Bindings 不会创建变量，它只是告诉 TypeScript 这些绑定应该存在。实际配置仍然要写在 wrangler.jsonc 或 Cloudflare 控制台中。

wrangler 配置示例

jsonc 
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-hono-api",
  "main": "src/index.ts",
  "compatibility_date": "2026-09-29",
  "vars": {
    "API_TOKEN": "dev-token"
  },
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-db",
      "database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ]
}

本地开发时，敏感值应该放在 .dev.vars，不要提交到 Git：

text 
API_TOKEN=local-secret

Node.js 环境变量

Node.js 项目通常从 process.env 读取环境变量：

ts 
const port = Number(process.env.PORT ?? '3000')
const jwtSecret = process.env.JWT_SECRET

if (!jwtSecret) {
  throw new Error('JWT_SECRET is required')
}

然后传给应用工厂：

ts 
import { Hono } from 'hono'

type AppOptions = {
  jwtSecret: string
}

export function createApp(options: AppOptions) {
  const app = new Hono()

  app.get('/health', (c) => {
    return c.json({ ok: true, auth: Boolean(options.jwtSecret) })
  })

  return app
}

入口：

ts 
import { serve } from '@hono/node-server'
import { createApp } from './app'

const app = createApp({
  jwtSecret: process.env.JWT_SECRET ?? '',
})

serve({
  fetch: app.fetch,
  port: Number(process.env.PORT ?? '3000'),
})

不同运行时的建议

场景 建议
Cloudflare Workers 使用 c.env，通过 Bindings 声明类型。
Node.js 在入口读取 process.env，整理为配置对象传入应用。
多运行时共享代码 把环境读取放到平台入口，业务路由只依赖显式传入的配置。

避免在所有业务函数里直接读取环境变量。集中读取和校验配置，更容易测试和迁移。

相关内容