如何更改数据库类型

EasyAdminBlazor 的数据访问基于 FreeSql。模板默认使用 SQLite（连接串 Data Source=easyadminblazor.db），零配置即可运行；正式项目需要换用 MySQL、SQL Server、PostgreSQL 等数据库时，只需要改三处：

更换对应的 FreeSql 数据库驱动包；
修改 Program.cs 中的 DataType；
修改 appsettings.json 中的连接字符串。

更多数据库适配说明见 FreeSql 官方文档。

1. 先看模板默认配置

模板生成的 Program.cs 里，默认是这样配置的：

FreeSqlBuilder = a => a
    .UseConnectionString(DataType.Sqlite, configuration["ConnectionStrings:default"])
    .UseMonitorCommand(cmd => System.Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] {cmd.CommandText}\r\n"))
    .UseAutoSyncStructure(true)

对应的 appsettings.json：

{
  "ConnectionStrings": {
    "Default": "Data Source=easyadminblazor.db"
  }
}

切换数据库时，DataType 和连接字符串要同时改，并安装对应的 NuGet 驱动包。

2. 支持的数据库对照表

数据库	`DataType`	NuGet 包	连接字符串示例
SQLite（模板默认）	`DataType.Sqlite`	`FreeSql.Provider.Sqlite`	`Data Source=easyadminblazor.db`
MySQL / MariaDB	`DataType.MySql`	`FreeSql.Provider.MySqlConnector`（推荐）	`Data Source=127.0.0.1;Port=3306;User ID=root;Password=你的密码;Initial Catalog=yourdb;Charset=utf8mb4;SslMode=none`
SQL Server	`DataType.SqlServer`	`FreeSql.Provider.SqlServer`	`Data Source=localhost;User Id=sa;Password=你的密码;Initial Catalog=yourdb;Encrypt=True;TrustServerCertificate=True`
PostgreSQL	`DataType.PostgreSQL`	`FreeSql.Provider.PostgreSQL`	`Host=localhost;Port=5432;Database=yourdb;Username=postgres;Password=你的密码`
Oracle	`DataType.Oracle`	`FreeSql.Provider.Oracle`	见 FreeSql 官方文档
其他/国产数据库	见 FreeSql 文档	见 FreeSql 文档	见 FreeSql 官方文档

提示：FreeSql.Provider.MySqlConnector 基于开源社区驱动，是 FreeSql 官方推荐的首选；MySQL 官方驱动对应 FreeSql.Provider.MySql。

3. 修改步骤（以换成 MySQL 为例）

第一步：替换 NuGet 包

在项目根目录执行：

# 先移除模板默认的 SQLite 驱动（可留，不影响运行）
dotnet remove package FreeSql.Provider.Sqlite

# 安装目标数据库的驱动
dotnet add package FreeSql.Provider.MySqlConnector

换成其它数据库时，把第二句换成对应驱动包即可，例如：

dotnet add package FreeSql.Provider.SqlServer     # SQL Server
dotnet add package FreeSql.Provider.PostgreSQL    # PostgreSQL
dotnet add package FreeSql.Provider.Oracle        # Oracle

第二步：修改 Program.cs

把 FreeSqlBuilder 里的 DataType.Sqlite 改成 DataType.MySql：

FreeSqlBuilder = a => a
    .UseConnectionString(DataType.MySql, configuration["ConnectionStrings:default"])
    .UseMonitorCommand(cmd => System.Console.WriteLine($"[{DateTime.Now:HH:mm:ss}] {cmd.CommandText}\r\n"))
    .UseAutoSyncStructure(true)

第三步：修改连接字符串

在 appsettings.json 中改成目标数据库连接：

{
  "ConnectionStrings": {
    "Default": "Data Source=127.0.0.1;Port=3306;User ID=root;Password=你的密码;Initial Catalog=yourdb;Charset=utf8mb4;SslMode=none"
  }
}

生产环境建议不要提交数据库密码，可以用环境变量覆盖，例如 ConnectionStrings__Default=...。

第四步：启动验证

先在数据库服务器上创建好一个空数据库（如 yourdb），SQLite 会自动创建 .db 文件，不需要这一步；
开发环境保持 UseAutoSyncStructure(true)，首次启动会自动同步表结构并初始化默认管理员（admin / 123yyq）；
启动后登录后台，确认登录、菜单、用户管理等页面正常；
验证通过后再按部署上线发布，生产环境建议把 UseAutoSyncStructure 改为 false。

4. 已有 SQLite 数据怎么办

切换数据库类型不会自动迁移旧数据。如果项目里已经录入了业务数据，需要先自行导出再导入：

数据量不大：直接在 SQLite 管理工具里导出表数据，再导入到新库；
数据量较大：建议用数据库迁移/ETL 工具处理；
刚创建、还没有业务数据：直接切库，首次启动自动建表即可。

5. 常见问题

启动报“数据库连接不上”

确认目标数据库服务已启动；
确认账号密码、端口、库名正确；
确认 appsettings.json 或环境变量里配置的就是你改的那个连接串；
远程数据库还要检查防火墙和安全组。

MySQL 中文乱码

连接字符串里加上 Charset=utf8mb4，并确认数据库本身使用 utf8mb4 字符集。

SQL Server 连接报证书相关错误

本地/测试环境使用自签名证书时，在连接串中加 TrustServerCertificate=True。

已经装了多个驱动包

不会冲突：实际使用哪个数据库由 Program.cs 里的 DataType 决定。只是建议把用不到的驱动包移除，减小发布体积。

运行时报“找不到某数据库类型映射”

通常是装了包但 DataType 与包不匹配，或 Program.cs 还是 DataType.Sqlite。对照上面的对照表检查一遍。