Next.js环境变量配置正确但libsql客户端报URL_INVALID错误

问题重现 #

创建libsql客户端的代码片段：

console.log(process.env.TURSO_DATABASE_URL);
const libsql = createClient({
  url: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!
});

运行应用时出现错误：

LibsqlError: URL_INVALID: The URL 'undefined' is not in a valid format

额外信息 #

• libsql版本：0.7.0
• prisma版本：^5.15.1

已尝试操作：确认环境变量配置正确、重启开发服务器、通过console.log验证环境变量加载情况

原因分析 #

1. Next.js环境变量访问权限限制

   • 客户端组件无法直接读取未加NEXT_PUBLIC_前缀的环境变量，这类变量会被Next.js在构建时剔除，导致运行时获取到undefined
   • 若你在客户端组件中初始化libsql客户端，即使.env文件配置正确，也会出现变量未加载的情况

2. 环境变量文件格式错误

   • .env文件中变量定义存在多余空格（如TURSO_DATABASE_URL = libsql://xxx），会导致Node.js无法正确解析变量值
   • 变量值被不必要的引号包裹，也可能引发解析异常（不过此场景下直接返回undefined更可能是未读取到变量）

3. 代码运行环境不匹配

   • libsql的authToken属于敏感信息，若在客户端初始化客户端，不仅会暴露敏感数据，还会因为服务器变量未加载导致URL失效

解决方案 #

1. 区分代码运行环境调整变量 #

• 服务器端场景（API路由/Server组件/Server Action）：

  • 确保.env.local文件放在项目根目录，变量定义无多余空格，格式如下：

    TURSO_DATABASE_URL=libsql://your-db-name.turso.io
    TURSO_AUTH_TOKEN=your-auth-token
    

  • 重启开发服务器，确保变量重新加载

• 客户端场景（不推荐直接初始化客户端）：

  • 若必须在客户端操作，将变量前缀改为NEXT_PUBLIC_：

    NEXT_PUBLIC_TURSO_DATABASE_URL=libsql://your-db-name.turso.io
    NEXT_PUBLIC_TURSO_AUTH_TOKEN=your-auth-token
    

  • 更新代码中的变量引用：

    const libsql = createClient({
      url: process.env.NEXT_PUBLIC_TURSO_DATABASE_URL!,
      authToken: process.env.NEXT_PUBLIC_TURSO_AUTH_TOKEN!
    });
    

  注意：authToken属于敏感信息，暴露在客户端存在安全风险，建议通过API路由中转数据库操作

2. 验证环境变量加载有效性 #

• 服务器端：在API路由或Server组件中打印变量，确认是否正确加载：

  // app/api/test/route.js
  export async function GET() {
    console.log("DB URL:", process.env.TURSO_DATABASE_URL);
    console.log("Auth Token:", process.env.TURSO_AUTH_TOKEN);
    return new Response("Check server logs");
  }
  

• 客户端：仅能打印NEXT_PUBLIC_前缀的变量，可在组件中添加：

  console.log("Client DB URL:", process.env.NEXT_PUBLIC_TURSO_DATABASE_URL);
  

3. 优化客户端数据库访问方式 #

最佳实践是将libsql客户端初始化放在服务器端，客户端通过调用API路由或Server Action来执行数据库操作：

// app/api/db-query/route.js
import { createClient } from '@libsql/client';

export async function POST(request) {
  const libsql = createClient({
    url: process.env.TURSO_DATABASE_URL!,
    authToken: process.env.TURSO_AUTH_TOKEN!
  });
  // 执行数据库操作
  const result = await libsql.execute("SELECT * FROM your_table");
  return Response.json(result);
}

客户端通过fetch调用该接口即可，避免敏感信息暴露和变量加载问题

内容的提问来源于stack exchange，提问作者sarthak kuwar