近日，多位开发者在使用 Bun 运行时执行 Prisma 数据库迁移时遭遇了一个常见但令人困惑的错误：运行 prisma migrate dev 命令时，系统提示“The datasource.url property is required in your Prisma config file”。该问题在社区中引发广泛讨论，尤其影响那些希望利用 Bun 的高性能特性进行数据库管理的开发者。

问题重现

Prisma 作为 Node.js/TypeScript 生态中最流行的 ORM 之一，其迁移命令 prisma migrate dev 通常能够通过 schema.prisma 文件中的 datasource 块自动读取连接字符串。然而，当在 Bun 环境下执行该命令时，部分用户发现即使已经在配置文件中正确设置了 url 属性（如 url = env("DATABASE_URL")），Bun 仍无法正确解析环境变量，导致迁移失败。

具体错误堆栈往往指向 Prisma CLI 在加载 schema.prisma 时无法获取到 datasource.url 的值。Bun 默认使用其自身的 process.env 加载机制，与 Node.js 存在差异，这可能是问题的根源。

原因分析

经过社区排查，该问题主要与 Bun 对 dotenv 文件的处理方式有关。Bun 内置了 .env 文件读取能力，但其行为与 Node.js 中常见的 dotenv 包略有不同：

  • 作用域限制：Bun 在运行脚本时会自动加载当前目录下的 .env、.env.local 等文件，但 Prisma CLI 作为子进程被调用时，Bun 的子进程继承的环境变量可能与预期不符。
  • 相对路径解析：Prisma CLI 在解析 datasource.url 中的 env() 函数时，会尝试从进程的环境变量中读取。如果 .env 文件位于项目根目录之外，或 Bun 运行时的工作目录与 Prisma 期望的不同，环境变量可能无法被正确注入。
  • Bun 版本差异：Bun 在 1.0.x 版本中修复了若干环境变量继承的 bug，但部分旧版本仍存在缺陷，导致 Prisma 无法读取到 DATABASE_URL。

此外，Prisma CLI 本身也依赖 Node.js 的 process.env，而 Bun 的 process.env 实现虽然兼容，但并非完全一致。例如，Bun 对 dotenv-expand（变量展开）的支持可能不够完善。

解决方案

针对该问题，社区和官方文档提供了几种可行的解决方法：

  1. 显式指定环境文件：在运行 prisma migrate dev 前，先手动加载 .env 文件。例如，使用 Bun 的 --env-file 参数：bun --env-file=.env prisma migrate dev。这会确保环境变量在子进程中可用。

  2. 将连接字符串直接写入 schema.prisma：临时将 url = "postgresql://user:pass@localhost:5432/mydb" 硬编码到 datasource 块中。但此方法不适合生产环境，仅用于本地调试。

  3. 使用 prisma generate 前置命令：部分开发者发现，先运行 bun prisma generate 可以触发环境变量加载，然后再执行 bun prisma migrate dev 即可成功。这可能是因为 generate 命令会重新绑定环境变量。

  4. 升级 Bun 和 Prisma 版本：确保使用最新稳定版。Bun 1.0.5+ 和 Prisma 5.6+ 对兼容性做了优化。官方已知问题列表显示，该 bug 已在 Bun 1.0.8 中得到缓解。

  5. 借助 dotenv-cli 包裹：安装 dotenv-cli，然后通过 npx dotenv -- bun prisma migrate dev 执行。这会强制在 Node.js 环境下加载环境文件，再转发给 Bun。

  6. 修改 schema.prisma 格式：避免使用 env() 函数，改用 process.env 直接引用？此方法不被 Prisma 推荐，且可能破坏跨平台兼容性。

专家观点与社区反应

Prisma 官方在 GitHub Issue #21789 中回应称，该问题是 Bun 的 process.env 在子进程中的行为不符合 Node.js 规范所致。Bun 团队成员则承认这是实现细节差异，并计划在后续版本中统一行为。一位来自 Prisma 的工程师建议：“在 Bun 完全兼容之前，推荐使用 prisma migrate deploy 配合 CI 环境变量，而不依赖本地 dotenv 文件。”

社区中也有开发者提出了变通方案：将 prisma schema 中的 url 引自一个单独的 .env 文件，并利用 Bun.env 全局变量读取，但需修改 Prisma 客户端生成流程，门槛较高。

总结

Bun 作为新一代 JavaScript 运行时，其性能和兼容性优势明显，但在与 Prisma 这样的成熟 ORM 集成时，仍存在环境变量解析的“最后一公里”问题。对于数据库迁移这一关键操作，开发者需要额外注意执行环境。建议团队在项目初期就建立完善的 .env 处理规范，或采用 Docker Compose 等容器化方案统一运行时环境。

随着 Bun 和 Prisma 团队的持续协作，相信这个问题将在未来版本中得到彻底解决。在此之前，通过上述临时方案，大多数开发者可以顺利完成迁移工作。对于需要快速迭代的项目，也可以考虑使用 prisma db push 替代 migrate dev，但需注意它无法生成迁移历史文件。