做Java后端的朋友，应该都碰过这种事：项目换了个环境，开发库还是张白纸；或者新同事一拉代码，本地数据库一片空白，启动直接报“Table doesn't exist”。于是就会想：Spring Boot能不能在启动时，直接把SQL文件给导进去？
这个问题本质上拆开是几层诉求：有的人只是希望空库自动建表、自动造数，快速跑起来；有的人手里有一个几百MB的业务SQL脚本，想通过Spring Boot程序去执行，省得开客户端；还有的人想把自己项目里落盘的sql文件，做成一种可重复的初始化机制。Spring Boot本身确实把“导入SQL文件”这个能力做进了框架，叫spring.sql.init，但它更多覆盖第一类场景。如果你的需求是“运行中任意导一个外部SQL文件”，那就需要自己补充一些代码。
这篇文章会把我折腾这两个方向的经验完整放出来，包含内置机制的原理、参数、版本坑，以及一个能直接改用的自定义SQL执行器，最后是高频问题的排查速查表。小白可以照着配置，老手也能查漏补缺。
1. 拆解需求：这个导入诉求背后通常有四种玩法
1.1 先看清楚自己属于哪一种使用场景
“Spring Boot直接导入SQL文件”这个指令，落到实际项目里往往对应不同动机。我见过的场景大致有四种。
第一，本地开发自举。团队里没人维护一套统一的开发库脚本，新入职的同事拉完代码后，要么找老同事要一份本地备份，要么根据文档手工建表，很痛苦。通过在Spring Boot启动阶段直接执行schema.sql和data.sql，能把建表、基础字典数据一次性跑完，新环境分钟级可用。
第二，演示项目和环境恢复。很多独立演示项目需要造一批演示数据，比如菜单权限、用户账号、商品种子数据。直接在classpath存几个SQL文件，每次启动导入，省去人工准备数据的环节。
第三，业务系统里的“数据库管理/导入”功能。比如后台提供了一个SQL脚本上传入口，运维或实施人员在线执行一段初始化脚本；或者系统启动时检测到某张表为空，自动补录维表数据。这类场景不能依赖Spring Boot默认的初始化时机，必须自己在代码里主动执行SQL文件。
第四，版本升级补数据。项目从一个版本升到另一个版本，需要执行增量SQL，比如加字段、加索引、清洗存量数据。有些人图省事把增量脚本塞进启动流程，这种方式不是完全不行，但要非常小心重复执行的问题。
不管哪种玩法，都绕不开三个关键问题：SQL文件放哪里、什么时候去执行、执行完会不会产生副作用。把这三点想清楚，方案自然就出来了。
1.2 三条主流路线的对比和选型
我通常把Spring Boot导入SQL文件的实现路径归成三类：内置初始化机制、数据库迁移工具、自定义脚本执行器。
内置机制是Spring Boot自动配置出来的，简单直接，适合非生产环境、轻量初始化；迁移工具指的是Flyway、Liquibase这类，适合生产环境和迭代版本管理；自定义执行器则是自己在代码里通过JDBC或JdbcTemplate执行SQL文件，适合做动态管理、特殊业务触发。
| 方案 | 适合场景 | 版本化能力 | 重复执行风险 | 实现成本 |
|---|---|---|---|---|
| spring.sql.init | 开发库自举、演示数据、空库初始化 | 无 | 较高，需脚本幂等 | 极低，配置即可 |
| Flyway/Liquibase | 生产版本升级、多人协作、固定迭代 | 强，有版本表记录 | 低，自动跳过旧版本 | 中，需要引入依赖 |
| 自定义执行器 | 动态导入、后台管理、特殊规则触发 | 需自己实现记录 | 取决于自己怎么写 | 中高，要写不少代码 |
选型有一条我的个人经验：不要因为内置机制不够高级就一上来上Flyway，也不要为了图快把任意SQL都交给内置机制去跑。开发期和演示项目，优先用内置机制；一旦项目要发生产，并且SQL会随版本持续演化，请认真考虑迁移工具。至于自定义执行器，一般只在配合业务逻辑时才出手。
1.3 为什么默认推荐先试内置机制
如果你手里是一个普通Spring Boot项目，并且SQL文件只是想“启动时跑一遍”，那么Spring Boot的spring.sql.init几乎不需要写Java代码，只要在application.properties里配几个参数就能完成。它底层帮我们封装了资源读取、语句分隔、错误处理这些脏活，开发体验相当顺滑。
而且内置机制的配置在Spring Boot 2.5以后逐渐统一，2.7和3.x版本下依然可用，并不是淘汰功能。与其自己写一个粗糙的split(";")循环执行，不如先吃透框架已经提供的能力。
2. 用Spring Boot内置的 SQL Init 机制直接导入SQL文件
2.1 三行配置跑通最小实例
我们先看一个最基础的用法。假设项目src/main/resources目录下有个db/init.sql，里面是建表和数据插入语句，启动Spring Boot时希望它自动执行。只需要在application.properties里写：
spring.sql.init.mode=always spring.sql.init.schema-locations=classpath:db/init.sql spring.sql.init.encoding=UTF-8这段配置的意思很直白：不管数据库是内嵌的还是外部的，启动时都去执行classpath下的db/init.sql。
如果你把文件默认命名为schema.sql或data.sql，并且放到classpath根目录，甚至不需要写schema-locations和>src/main/resources/ ├── application.properties ├── schema.sql └── data.sql
schema.sql一般放DDL语句，建表、建索引；data.sql放DML语句，初始化数据。Spring Boot启动时会先执行schema.sql，再执行data.sql。
这里有个细节：默认情况下，如果你的数据源是嵌入式数据库，比如H2、HSQLDB、DERBY，即使不写spring.sql.init.mode=always，启动也会自动执行schema.sql和data.sql；但是如果连接的是MySQL、PostgreSQL、SQL Server这类外部数据库，Spring Boot默认不会执行它们，必须把mode显式设成always。很多初学者在这里栽跟头，文件明明放着，日志里却看不到执行记录。
2.2 核心参数逐个讲透
Spring Boot的spring.sql.init参数组看起来不多，每个都值得认真理解。
spring.sql.init.mode有三个可选值：embedded、always、never。默认值是embedded，表示只有内嵌数据库才执行初始化脚本；项目接外部数据库时，要改成always；改成never则可以彻底关闭初始化，适用于某些不想跑脚本的环境。
spring.sql.init.schema-locations和spring.sql.init.data-locations分别指定DDL脚本和DML脚本的位置，多个文件用逗号分隔。比如：
spring.sql.init.schema-locations=classpath:db/schema.sql,classpath:db/extend.sql spring.sql.init.data-locations=classpath:db/data.sqlspring.sql.init.separator用于指定SQL语句分隔符，默认是分号;。如果脚本里使用了自定义分隔符，比如SQL Server的GO批处理分隔符，可以改这里。不过要注意，GO并不是标准SQL语法，仅仅把它改成分隔符，执行时数据库端是否认还得看驱动和方言，这点后文会细说。
spring.sql.init.encoding指定脚本文件的编码，这个参数强烈建议写成UTF-8。Windows环境下，很多人用记事本另存为UTF-8带BOM格式，启动时容易报“Unknown character set”或首行乱码问题，指定编码能规避大部分这类坑。
spring.sql.init.continue-on-error决定执行遇到错误时是否继续。默认是false，也就是遇到SQL异常直接抛错，启动失败。如果你手头有一份“部分能成功就行”的脚本，可以改成true，但这是一个危险操作，不建议在数据初始化场景这么用，容易造成“看起来启动成功，实际数据缺一堆”的假象。
spring.sql.init.platform用于多数据库平台切换。比如同一个项目里同时留了schema-mysql.sql和schema-postgresql.sql，设置spring.sql.init.platform=mysql后，Spring Boot会去寻找名为schema-mysql.sql和>spring.jpa.defer-datasource-initialization=true
让Hibernate先完成表结构生成，再执行schema.sql和data.sql。但同时也要意识到，开了这个开关后，JPA的ddl-auto建表可能与你schema.sql里的建表语句形成冲突，所以实践中如果项目走JPA自动建表，SQL初始化脚本里通常不应该再放重复的建表语句，而只放数据导入部分。
如果你的项目还用了MyBatis，事情会简单很多，因为你没有实体关系映射和自动建表机制，表结构完全由SQL脚本控制，内置初始化脚本的执行顺序天然合理。
2.4 内置机制的边界：什么场景下别硬用
spring.sql.init虽然方便，但它的定位非常明确：启动时执行，不做版本记录。只要脚本位置不变，每次启动都会按顺序执行一遍。因此，它不适合下面这些场景：
第一，脚本不是幂等的。比如insert into user ...这类语句，第一次启动成功，第二次启动就报主键冲突。你只能自己写create table if not exists、insert ignore这种幂等语句去规避。
第二，脚本里包含复杂的存储过程、触发器、函数定义。SQL文件解析器在切分语句时是依据分号的，而存储过程内部通常存在大量分号，切分后会变成支离破碎的片段，执行必然报错。
第三，项目需要多人协作并长期演进。如果这个月加一张表，下个月改几个字段，全靠改一个总SQL文件是不现实的。这时候你需要的是Flyway这类版本化迁移工具，每个版本一个独立脚本，工具帮你记录“哪些脚本跑过，哪些没跑过”。
3. 内置机制不够用时，自己写一个SQL文件执行器
3.1 先想清楚这个执行器要管哪些事
当你需要在代码里主动执行SQL文件，比如上传一个SQL脚本后点击“执行”、系统启动时检测到空表自动补数据，那就要自己实现一个轻量执行器了。
一个合格的执行器至少要处理四件事：定位并读取文件、解析SQL语句边界、真实执行、记录和异常处理。很多人第一次写这种工具，会简单粗暴地读文件后按分号切分，循环执行。对纯简单语句可能没问题，但一旦SQL里出现了字符串内容带分号，比如insert into t values('a;b')，必然被拆错，执行时直接语法报错。
先给一个整体设计思路：
1. 确定资源位置：支持classpath:路径、文件系统路径、多个文件上传的临时文件路径 2. 读取并清洗：按UTF-8读取内容，去掉注释（行注释、块注释），去掉首尾空白 3. 拆解语句：识别并保留字符串常量，不在字符串内部分隔符处截断 4. 逐条执行：通过JDBC Statement执行，或交给JdbcTemplate.execute() 5. 异常处理：记录失败的语句文本和原因，按是否需要继续决定终止还是跳过如果每一条SQL想在一个事务里执行，应该在一个Connection上执行并按业务要求决定提交或回滚。如果只是初始化脚本批量执行，每条自动提交通常会省事很多，因为很多DDL语句在MySQL中并不支持事务回滚。
3.2 支持通配符的资源路径读取
Spring框架自带的ResourcePatternResolver可以识别classpath*:这类通配符，方便我们一次拿多个SQL文件。比如初始化脚本都放在sql/init目录下，可以这样取：
public List<Resource> loadInitSqlResources() throws IOException { ResourcePatternResolver resolver = new PathMatchingResourcePatternResolver(); return Arrays.asList(resolver.getResources("classpath*:sql/init/*.sql")); }classpath*:和classpath:有个区别：classpath:只匹配第一个找到的资源；classpath*:会扫描所有依赖JAR中的匹配资源。如果只是扫描自己项目里的文件，两者差别不大，但如果你的工程有多个模块，并且SQL文件分布在不同的JAR包里，用classpath*:更稳妥。
拿到Resource后，用Spring的StreamUtils或JDK11+的Files.readString都能读取内容。推荐用StreamUtils.copyToString并指定字符集，避免平台默认编码的干扰：
public String readSqlContent(Resource resource) throws IOException { try (InputStream is = resource.getInputStream()) { return StreamUtils.copyToString(is, StandardCharsets.UTF_8); } }3.3 兼顾注释和字符串内容的SQL拆解
拆解SQL语句是整个执行器里最需要打磨的地方。一个健壮的拆解函数，必须关心注释和字符串常量，否则再完善的文件读取都白搭。
行注释一般以--开头，块注释以/*开头、*/结尾。不同数据库也支持#注释，比如MySQL。最简单的做法是逐行扫描，把注释内容替换成空格，保留字符串原文的位置，然后用分隔符截断。这样处理有一个好处，注释里面的分号不会被误伤。
字符串处理稍微复杂一点。SQL里的字符串一般用单引号包围，字符串内部连续两个单引号表示转义的单引号。扫描时需要记录当前是否处于字符串状态，只有不在字符串内部的分号，才当作语句分隔符。
有了这个前提，核心代码可以写成一个状态机：
public List<String> splitSqlScript(String script) { List<String> statements = new ArrayList<>(); StringBuilder current = new StringBuilder(); boolean inSingleQuote = false; char[] chars = script.toCharArray(); for (int i = 0; i < chars.length; i++) { char c = chars[i]; if (c == '\'') { inSingleQuote = !inSingleQuote; current.append(c); } else if (c == '-' && i + 1 < chars.length && chars[i + 1] == '-') { while (i < chars.length && chars[i] != '\n') { i++; } } else if (c == '/' && i + 1 < chars.length && chars[i + 1] == '*') { i += 2; while (i + 1 < chars.length && !(chars[i] == '*' && chars[i + 1] == '/')) { i++; } i++; } else if (c == ';' && !inSingleQuote) { String stmt = current.toString().trim(); if (!stmt.isEmpty()) { statements.add(stmt); } current.setLength(0); } else { current.append(c); } } if (current.toString().trim().length() > 0) { statements.add(current.toString().trim()); } return statements; }这个实现能处理大部分常规脚本，但不是完整的SQL解析器。比如碰到存储过程中的BEGIN...END块仍可能出错，碰到PostgreSQL的美元符号字符串$$...$$也有局限。但在非极端场景下，配合简单SQL脚本使用已经足够可靠。真遇到存储过程脚本，我建议尽量用成熟工具，而不是自己硬拆。
3.4 在项目启动时或接收文件后触发执行
文件读取和拆解都准备好了，剩下的就是触发时机。如果希望项目启动完成后执行初始化，可以实现CommandLineRunner或ApplicationRunner接口：
@Component public class SqlInitRunner implements CommandLineRunner { private final JdbcTemplate jdbcTemplate; public SqlInitRunner(JdbcTemplate jdbcTemplate) { this.jdbcTemplate = jdbcTemplate; } @Override public void run(String... args) throws Exception { ResourcePatternResolver resolver = new PathMatchingResourcePatternResolver(); Resource[] resources = resolver.getResources("classpath*:sql/init/*.sql"); for (Resource resource : resources) { String content = StreamUtils.copyToString( resource.getInputStream(), StandardCharsets.UTF_8); List<String> statements = splitSqlScript(content); for (String statement : statements) { jdbcTemplate.execute(statement); } System.out.println("已初始化SQL文件: " + resource.getFilename()); } } }如果同一个项目里有多个CommandLineRunner，并且不同Runner之间有先后要求，可以用@Order注解控制执行顺序。不过Spring Boot的初始化机制本身在数据源和JdbcTemplate准备完成后才会执行Runner，所以不需要担心数据源为空。
如果需要在系统运行过程中接收用户上传的SQL文件后再执行，上述逻辑同样适用，只要把Resource来源换成MultipartFile的输入流即可。额外要做的是权限校验和文件大小限制，避免有人上传超大文件把数据库拖垮。
3.5 别重复造轮子：Spring自带ScriptUtils其实很能打
说到这，我必须插一句：Spring JDBC模块里其实自带了一个脚本工具类，叫org.springframework.jdbc.datasource.init.ScriptUtils。spring.sql.init底层就是靠它干活，它不仅能处理注释，还支持分隔符设置，甚至对部分数据库方言做了兼容。
所以，如果只是想在代码里执行一个指定的SQL文件，并希望逻辑更强健，不必自己写状态机，直接调它就行：
Resource resource = new ClassPathResource("db/init.sql"); try (Connection connection = dataSource.getConnection()) { ScriptUtils.executeSqlScript(connection, new EncodedResource(resource, StandardCharsets.UTF_8)); }ScriptUtils.executeSqlScript有几个可重载版本，可以传入自定义分隔符、是否忽略失败等参数。用Spring原生工具的好处是，项目本身已经引入了spring-jdbc，不需要额外依赖，而且它内部对--注释、/* */注释、字符串中的分号都做了处理，比我上面那个简易版状态机要成熟。
如果项目已经引入了MyBatis，还可以使用MyBatis提供的org.apache.ibatis.jdbc.ScriptRunner。它设计了setLogWriter、setAutoCommit、setStopOnError、setSendFullScript等开关，常用于MyBatis Generator或测试数据初始化，在小规模脚本场景下表现也不错。但它没有依赖Spring的资源抽象，要自己处理文件和字符集。
4. 高频坑位与排查实录
4.1 先收好这张问题速查表
我把实际工作中遇到的导入SQL文件问题整理成一张速查表。如果你启动时遇到异常，可以先对照这里找方向。
| 现象 | 原因 | 解决方案 |
|---|---|---|
| 连接外部数据库，schema.sql不执行 | mode默认embedded | 设置spring.sql.init.mode=always |
| 报错Unknown database或Table不存在 | 脚本执行顺序不对，或库里根本没有库 | 先手动建库，确认dataSource url无误 |
| 启动第二次报主键冲突/表已存在 | data.sql插入语句未做幂等 | 脚本中使用insert ignore/on duplicate key update |
| 提示文件找不到 | SQL文件不在classpath或路径写错 | 使用classpath:前缀，检查resources目录及打包结果 |
| 中文数据变成乱码或SQL语法错误 | 文件编码和配置编码不一致 | 统一UTF-8，配置spring.sql.init.encoding=UTF-8 |
| 存储过程脚本执行到一半报错 | 分号切分把过程体拆乱了 | 换成SCRIPtUtils或MyBatis ScriptRunner处理 |
| Spring Boot 3.x下旧配置无效 | 配置前缀迁移 | 改用spring.sql.init.* |
| SQL Server脚本中GO语句报错 | GO不是SQL关键字 | 使用工具设置分隔符为GO，或删除GO行 |
| 执行到一半失败但启动成功 | continue-on-error被设置为true | 改回false，并逐个处理前置异常 |
4.2 几个典型问题的现场还原与处理经过
第一个典型的例子是外部数据库下初始化脚本不执行。我记得有一次接一个新项目，对方把初始化脚本发过来让我放到工程里，我直接在resources下放了schema.sql，启动后日志里完全没有建表记录，但也没有报错。查了一圈才发现，Spring Boot 2.5以后，spring.sql.init.mode默认是embedded，只有连接H2这类内嵌数据库时才会自动执行。外部MySQL数据库必须显式设置mode=always，否则脚本形同虚设。这个配置不加，脚本文件放对地方也没用。
第二个高频问题是脚本每次启动都执行，导致数据重复。这个问题在内置初始化机制里尤其常见。Spring Boot不会记录SQL文件是否执行过，只要schema.sql和data.sql存在，每次启动都会跑一遍。我第一次在公司内部系统里用这个机制时，硬生生把一张配置表插了两遍数据，启动直接主键冲突。后续我的处理方式很简单：在脚本里把所有插入改成幂等写法，比如MySQL下用insert ignore，建表统一加if not exists。
第三个有意思的问题是Windows环境下文件编码。同事写了个SQL脚本，里面中文注释很规范，但在他电脑上跑得通，换到Linux服务器上就报语法错误。最后排查下来，文件是GBK编码，而Spring Boot初始化时默认按平台编码读取，Linux下是UTF-8，中文注释变成了乱码，个别乱码字符直接破坏了SQL结构。解决办法是文件重新保存成UTF-8，并且配置里明确写上spring.sql.init.encoding=UTF-8。
第四个问题是脚本内含存储过程或者函数。内置初始化机制依赖分隔符拆分SQL，默认按分号拆分，而MySQL的存储过程内部会有大量分号，即使你写了delimiter //也常常不生效。遇到这种脚本，建议不要走schema.sql自动执行，而是单独在代码里调用ScriptUtils，显式设置分隔符，或者干脆用数据库客户端手工执行一次。
4.3 幂等设计与“只跑一次”的多种实现方式
很多人用内置机制跑初始化脚本时，第一反应是问：能不能只跑一次，第二次启动就不跑了？Spring Boot本身没有提供这样的状态记录，但实现方式并不少。
最粗暴的方式是检查目标表是否存在。如果表已经存在，说明建表脚本跑过了，那就跳过；如果数据表是空的，说明数据没初始化，可以插入。这个逻辑可以写在CommandLineRunner里：
Integer count = jdbcTemplate.queryForObject( "select count(*) from information_schema.tables where table_name = 'sys_config'", Integer.class); if (count != null && count == 0) { // 执行初始化SQL }更通用一点的方法是利用数据库的flyway_schema_history这类迁移记录表，自己维护一个脚本执行历史。手动实现版本表有点麻烦，这也是为什么我坚持认为：一旦项目进入多人协同迭代，与其自制一套“只跑一次”逻辑，不如直接把这个诉求交给Flyway。
5. 从开发环境到生产发布的脚本管理路径
5.1 明确区分“初始化”和“迁移”两种脚本职责
我见过不少项目把所有SQL都写在一个巨大的init.sql里，从建库语句到字典数据再到存储过程全部塞进去，开发阶段还凑合，一上生产就灾难。问题在于这类文件虽然解决了“从零搭建”的问题，却没有解决“版本演化”的问题。今天加一个字段，明天删一张表，文件越改越大，最后没人敢动它。
所以现在我习惯把脚本按生命周期拆成两类。
一类是只面向全新环境的初始化脚本，命名类似V1__base_schema.sql、V2__base_data.sql，它们假设数据库是空的，负责搭建完整结构。这类脚本可以交给Flyway管理，也可以配合Spring Boot内置机制在开发环境执行。
另一类面向存量环境的增量脚本，比如V20250110__add_order_no_column.sql。每次变更只针对当前版本的增量差异。这类脚本绝不能由spring.sql.init.mode=always去执行，因为老环境的数据库里可能已经有了某些数据，重复执行会出问题。规范做法是把这类脚本纳入Flyway，让Flyway根据版本号只执行未执行的迁移。
5.2 按环境和数据库组织脚本文件
数据库方言差异很容易被忽略。同样的字段类型，MySQL用bigint，Oracle用number，SQL Server用bigint；自增主键语法也十万八千里。指望一个SQL脚本在所有数据库环境通用，基本不可能。
我的做法是在resources下按数据库和用途两级组织目录：
resources/ ├── db/ │ ├── mysql/ │ │ ├── schema.sql │ │ └── data.sql │ └── postgresql/ │ ├── schema.sql │ └── data.sql然后在配置里通过spring.sql.init.platform或spring.profiles.active动态指定当前环境该加载哪套脚本。比如在application-dev.properties中写：
spring.sql.init.platform=mysql spring.sql.init.schema-locations=classpath:db/mysql/schema.sql spring.sql.init.data-locations=classpath:db/mysql/data.sql5.3 最后分享一点我的实操体会
这套东西前前后后我折腾了三四年，踩过的坑比教程里能写的多得多。如果只让我总结一句：Spring Boot的SQL初始化能力适合解决“从零到跑起来”，但它不负责解决“从跑起来到跑得稳”。开发库随便用spring.sql.init没问题，到了生产环境，尤其是多人协作的迭代项目，版本化迁移工具才是底线，别再省这个成本。
如果你的项目暂时不想引入Flyway，又想控制风险，至少在写SQL文件时养成三个习惯：建表语句全用if not exists；插入数据考虑幂等写法；每次启动前先脑补一遍“这个脚本跑两遍会不会出问题”。这三点在很长一段时间内都能帮你避开大多数启动事故。
