从.env.local传参创建Upstash Redis实例时遇TypeScript报错

错误原因分析 #

• 环境变量类型不确定性：process.env.UPSTASH_REDIS_REST_URL和process.env.UPSTASH_REDIS_REST_TOKEN在TypeScript中的类型是string | undefined，而Redis构造函数要求传入确定的字符串值。
• 版本适配问题：若使用的是@upstash/redis v2及以上版本，构造函数不再接受{url, token}格式的对象参数，而是需要遵循Requester接口规范或使用官方提供的快捷方法初始化。

具体解决方法 #

方法1：用Redis.fromEnv()自动加载环境变量（推荐） #

新版@upstash/redis提供了fromEnv()静态方法，会自动识别UPSTASH_REDIS_REST_URL和UPSTASH_REDIS_REST_TOKEN这两个默认命名的环境变量，无需手动传参，同时自动处理类型问题：

import { Redis } from "@upstash/redis";

export const db: Redis = Redis.fromEnv();

方法2：手动处理类型并适配构造函数 #

如果需要手动传入参数，先确保环境变量非空，再根据版本适配参数结构：

适配v2版本（Requester接口）

import { Redis } from "@upstash/redis";

// 断言环境变量存在，将类型转为string
const redisUrl = process.env.UPSTASH_REDIS_REST_URL as string;
const redisToken = process.env.UPSTASH_REDIS_REST_TOKEN as string;

export const db: Redis = new Redis({
  fetch: (url, options) => {
    return fetch(url, {
      ...options,
      headers: {
        ...options?.headers,
        Authorization: `Bearer ${redisToken}`
      }
    });
  }
});

适配v1版本（直接传参）

import { Redis } from "@upstash/redis";

// 用非空断言确保类型为string
export const db: Redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!
});

方法3：添加环境变量类型声明 #

在项目根目录创建env.d.ts文件，明确环境变量类型：

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      UPSTASH_REDIS_REST_URL: string;
      UPSTASH_REDIS_REST_TOKEN: string;
    }
  }
}

export {};

之后即可直接正常初始化：

import { Redis } from "@upstash/redis";

export const db: Redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN
});

额外注意事项 #

• 确保.env.local文件已被正确加载：框架项目（如Next.js）默认会自动加载，纯Node项目需借助dotenv包手动加载。
• 检查@upstash/redis版本：执行npm list @upstash/redis查看版本，不同版本的初始化方式差异较大，优先遵循对应版本的官方写法。

内容的提问来源于stack exchange，提问作者Mateusz Cwojdzinski