H2数据库的.mv.db文件必须由H2引擎自身初始化，不可通过Java File.createNewFile()等IO操作预先创建——否则会因缺失MVStore头结构导致IO Exception [90028-214]和EOFException，连接失败。本文详解正确创建流程、原理及避坑要点。
h2数据库的`.mv.db`文件必须由h2引擎自身初始化，不可通过java `file.createnewfile()`等io操作预先创建——否则会因缺失mvstore头结构导致`io exception [90028-214]`和`eofexception`，连接失败。本文详解正确创建流程、原理及避坑要点。
❌ 错误做法：手动创建空 .mv.db 文件
你在代码中执行了以下操作：
arquivo.createNewFile(); // ✅ 创建空文件 FileOutputStream fos = new FileOutputStream(arquivo); fos.write(conteudo.getBytes()); // ❌ 写入任意文本（如"Este é o conteúdo..."） fos.close();
这会导致：
- .mv.db 文件并非H2合法数据库文件，而只是一个普通文本文件；
- H2启动时尝试读取MVStore格式头部（固定偏移量处的元数据块），但该位置为空或为乱码 → 触发 EOFException 和 [90028-214] 错误；
- 日志中 Reading from file ... failed at 31 (length 31), read 31, remaining 8161 明确指出：H2期望读取至少 8192 字节的合法存储头，却只读到 31 字节即 EOF。
⚠️ 关键认知：.mv.db 不是“容器文件”，而是 MVStore 持久化存储的二进制快照，其结构（Chunk Header、Root Block、Page Tree等）必须由 H2 的 MVStore.Builder 严格生成，无法人工构造。
✅ 正确做法：让 H2 自动创建并初始化数据库
只需通过标准 JDBC 连接 URL 触发 H2 初始化，无需预创建文件或目录（H2 会自动创建目录与合法数据库文件）：
String dbPath = "C:/Users/lopes/teste3"; // 注意：不带 .mv.db 后缀！
String url = "jdbc:h2:" + dbPath + ";DB_CLOSE_ON_EXIT=FALSE;AUTO_SERVER=TRUE";
try (Connection conn = DriverManager.getConnection(url, "sa", "")) {
// 第一次连接时，H2 自动创建 C:/Users/lopes/teste3.mv.db（含完整MVStore结构）
System.out.println("✅ 数据库已成功初始化：" + dbPath + ".mv.db");
// 可选：建表、插入初始数据
try (Statement stmt = conn.createStatement()) {
stmt.execute("CREATE TABLE IF NOT EXISTS users(id IDENTITY, name VARCHAR)");
stmt.execute("INSERT INTO users(name) VALUES ('admin')");
}
} catch (SQLException e) {
e.printStackTrace();
}
✅ 关键参数说明：
| 参数 | 作用 | 推荐值 |
|---|---|---|
| DB_CLOSE_ON_EXIT=FALSE | 防止JVM退出时自动关闭数据库（避免嵌入式场景意外丢数据） | FALSE |
| AUTO_SERVER=TRUE | 启用自动服务器模式，允许多进程/线程安全访问同一文件 | TRUE（尤其适用于GUI应用多次连接） |
| INIT= | 可选：指定SQL初始化脚本（如 INIT=RUNSCRIPT FROM 'init.sql'） | 按需使用 |
? 提示：路径中绝对不要包含 .mv.db 后缀。H2 会自动添加该后缀。若写成 jdbc:h2:C:/.../teste3.mv.db，H2 将尝试创建 teste3.mv.db.mv.db，导致路径错误或新建空库。
? 验证与调试建议
检查文件真实性：
使用十六进制编辑器（如 HxD）打开生成的 .mv.db 文件，前 8 字节应为 0x00 0x00 0x00 0x00 0x4D 0x56 0x53 0x74（ASCII "MVSt"），这是 MVStore 的 magic header。启用H2调试日志：
在连接URL中添加 ;TRACE_LEVEL_FILE=3，H2 将输出详细存储层日志，便于定位初始化阶段问题。-
权限与路径安全：
确保目标目录可写（尤其 Windows 下 C:\Users\...\ 路径可能受UAC限制），推荐优先使用用户主目录：String dbPath = "~/myapp/db"; // 自动解析为 C:\Users\<user>\myapp\db</user>
?️ 最佳实践总结
- ✅ 永远让 H2 创建数据库文件：仅通过 JDBC URL 连接触发初始化；
- ✅ 路径不带 .mv.db：H2 自动追加，避免歧义；
- ✅ 首次连接后立即建表/初始化数据：确保数据库处于可用状态；
- ✅ 生产环境务必备份：.mv.db 文件损坏后恢复困难，建议定期导出 SQL（SCRIPT TO 'backup.sql'）；
- ❌ 禁止：File.createNewFile()、FileWriter 写入、复制粘贴 .mv.db 文件（除非使用 org.h2.tools.Recover 工具）。
遵循此规范，你的应用程序即可安全、可靠地支持用户自助创建 H2 数据库，彻底规避 [90028-214] 类错误。
