Исправить DATABASE_URL в Prisma Turborepo на Vercel

Понимание проблемы

Ошибка возникает потому, что среда сборки Vercel не наследует переменные окружения из вашего локального окружения или из панели управления Vercel при использовании структуры монорепозитория Turborepo. Пакет Prisma запускается изолированно во время сборки и не может получить доступ к DATABASE_URL, если он явно не предоставлен через правильные каналы.

Согласно документации Turborepo, при развертывании на Vercel необходимо явно настроить переменные окружения в файле turbo.json, чтобы они были доступны во время процессов сборки.

Решение 1: Настройка переменных окружения в turbo.json

Самый простой способ — явно определить DATABASE_URL в определениях задач turbo.json. На основе вашей текущей конфигурации убедитесь, что переменная правильно ограничена.

{
  "$schema": "https://turborepo.com/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build", "^db:generate"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "env": ["DATABASE_URL", "FETCH_BASE_URL", "JWT_SECRET"]
    },
    "db:generate": {
      "cache": false,
      "env": ["DATABASE_URL"]
    },
    "db:migrate": {
      "cache": false,
      "persistent": true,
      "env": ["DATABASE_URL"]
    },
    "db:deploy": {
      "cache": false,
      "env": ["DATABASE_URL"]
    }
  }
}

Ключевые моменты:

• Добавьте DATABASE_URL в массив env для всех соответствующих задач, особенно db:generate.
• Это гарантирует, что переменная будет доступна во время процесса генерации Prisma.
• Согласно Stack Overflow, это самое распространённое решение для данной ошибки.

Решение 2: Конфигурация панели управления Vercel

Независимо от конфигурации turbo.json, вам всё равно нужно задать DATABASE_URL в настройках проекта Vercel.

Пошаговая настройка Vercel

1. Перейдите в панель управления вашего проекта Vercel.
2. Перейдите в Settings → Environment Variables.
3. Добавьте новую переменную окружения:
   • Name: DATABASE_URL
   • Value: ваша строка подключения к базе данных
   • Scope: убедитесь, что она установлена для Production, Preview и Development.

Согласно Answer Overflow, «Чтобы решить эту ошибку, перейдите в настройки проекта на Vercel, откройте Environment Variables и добавьте DATABASE_URL с соответствующим значением.»

4. Убедитесь в наследовании переменной:
   • Vercel должен знать, что эта переменная должна быть доступна всем пакетам.
   • В настройках проекта убедитесь, что переменная не привязана к конкретному приложению.

Решение 3: Обновления конфигурации Prisma

Ваша текущая конфигурация Prisma имеет некоторые недостатки, которые можно улучшить для более надёжного управления переменными окружения.

Обновлённый packages/db/prisma.config.ts

import dotenv from "dotenv";
import { defineConfig, env } from "prisma/config";

// Загрузка переменных окружения из нескольких потенциальных источников
dotenv.config({ path: process.env.NODE_ENV === "production" ? ".env.production" : ".env.local" });
dotenv.config({ path: ".env" }); // резервный вариант из корневого .env
dotenv.config({ path: ".env.example" }); // окончательный резервный вариант

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
  },
  engine: "classic",
  datasource: {
    url: env("DATABASE_URL"),
  },
});

Ключевые улучшения:

• Более надёжный порядок загрузки переменных окружения.
• Поддержка файлов окружения, специфичных для продакшена.
• Улучшенные резервные механизмы.
• Согласно документации Prisma, такой подход рекомендуется для монорепозиториев.

Решение 4: Настройка команды сборки Vercel

Для проектов Turborepo на Vercel может потребоваться изменить команду сборки, чтобы обеспечить правильное наследование переменных окружения.

Переопределение конфигурации Vercel

1. В настройках проекта Vercel:

   • Перейдите в Settings → Build & Development Settings.
   • Переопределите Framework Preset на Next.js.
   • Build Command: cd ../.. && npm run build --filter=web.

2. Root Directory: Установите apps/web (или ваш конкретный каталог приложения).

Согласно Dotenv documentation, «Ваш первый деплой, скорее всего, завершится неудачей, потому что вам нужно добавить несколько пользовательских настроек. Установите Build & Development Settings → Framework Preset на Next.js и переопределите команду сборки с cd ../.. && npm run build --filter=web».

Устранение распространённых проблем

Проблема 1: Переменные всё ещё недоступны

Если вы выполнили все шаги и всё равно сталкиваетесь с проблемами:

1. Проверьте область действия переменной: убедитесь, что DATABASE_URL не привязана к конкретному приложению.
2. Проверьте имена переменных: убедитесь, что нет опечаток.
3. Тестируйте локально: используйте dotenvx run -- pnpm run db:generate, чтобы проверить локально.

Проблема 2: Команда Prisma не найдена

Согласно руководству по развертыванию Prisma на Vercel, если вы видите ошибку prisma: command not found:

• Переместите prisma из devDependencies в обычные зависимости в package.json.
• Или используйте пользовательский путь вывода и включите Prisma Client в контроль версий.

Проблема 3: Отсутствуют файлы движка запросов

Тот же руководитель Prisma упоминает, что в монорепозиториях вы можете столкнуться с отсутствием файлов, таких как libquery_engine-rhel-openssl-3.0.x.so.node. Решение — убедиться, что файлы правильно включены в процесс сборки.

Лучшие практики работы с переменными окружения в Turborepo

1. Иерархия переменных окружения

Создайте чёткую иерархию переменных окружения:

.env.local          # Локальные переопределения (не коммитятся)
.env.production     # Переменные продакшена
.env.example        # Шаблон (коммитится в git)

2. Переменные, специфичные для пакета

Для пакетов, которым нужны конкретные переменные, настройте их в turbo.json:

{
  "tasks": {
    "db:generate": {
      "env": ["DATABASE_URL", "DATABASE_AUTH_TOKEN"]
    }
  }
}

3. Сборка, специфичная для окружения

Согласно лучшим практикам Turborepo, используйте конфигурации, зависящие от окружения:

{
  "globalDependencies": ["**/.env.local", "**/.env.${{TURBO_ENV}}"]
}

4. Безопасное управление переменными

• Никогда не коммитите чувствительные переменные в контроль версий.
• Используйте .env.example как шаблон.
• Документируйте необходимые переменные для каждого пакета.

Источники

1. Prisma Documentation - Using Prisma with Turborepo
2. Vercel Turborepo Deployment Guide
3. Stack Overflow - Environment variable not set during build on Vercel
4. Answer Overflow - Prisma + Turborepo build fails in Vercel
5. Dotenv - Deploy a Turborepo App to Vercel
6. Prisma Documentation - Deploy to Vercel
7. Turborepo - Using Environment Variables
8. GitHub Discussion - Global Environment Variables from Root

Заключение

Чтобы решить проблему с переменной окружения DATABASE_URL при развертывании Turborepo на Vercel, необходимо реализовать многоуровневый подход:

1. Настройте turbo.json — явно включите DATABASE_URL в массивы env для всех релевантных задач.
2. Настройте панель управления Vercel — добавьте переменную с правильным диапазоном доступа.
3. Обновите конфигурацию Prisma — обеспечьте надёжную загрузку переменных окружения.
4. Настройте параметры сборки Vercel — убедитесь, что монорепозиторий обрабатывается корректно.

Ключевой вывод: переменные окружения в Turborepo требуют явной конфигурации на нескольких уровнях — как в файле сборки, так и в настройках платформы развертывания. Следуя этим шагам последовательно, вы гарантируете доступность DATABASE_URL во время генерации Prisma и устраните ошибки развертывания.

Проверяйте каждое изменение поэтапно и убедитесь, что переменные окружения корректно загружаются как в локальной разработке, так и в продакшене.