include_str 与 include_bytes
核心概念
include_str! 和 include_bytes! 是 Rust 的内置宏,在编译时将外部文件的内容嵌入到二进制文件中。include_str! 将文件内容作为 &'static str 嵌入(要求文件是合法的 UTF-8 编码),include_bytes! 将文件内容作为 &'static [u8; N] 嵌入(接受任意二进制文件)。
这两个宏在编译时读取文件,文件内容直接成为二进制的一部分。不需要在运行时读取文件系统,因此程序可以作为单个可执行文件分发,不依赖外部文件。
// include_str! — 嵌入文本文件为 &str
// const README: &str = include_str!("../README.md");
// include_bytes! — 嵌入任意文件为 &[u8]
// const LOGO: &[u8] = include_bytes!("../assets/logo.png");
// 路径相对于当前源文件所在的目录
// 如果在 src/main.rs 中,"../README.md" 指向项目根目录的 README.md
fn main() {
println!("include_str! 在编译时嵌入文本文件");
println!("include_bytes! 在编译时嵌入二进制文件");
}include_str! 详解
// include_str! 将文件内容作为 &'static str 嵌入
// 文件必须是合法的 UTF-8 编码,否则编译失败
// 嵌入配置文件
const DEFAULT_CONFIG: &str = include_str!("../config/default.toml");
// 嵌入 SQL 文件
// const INIT_SQL: &str = include_str!("../sql/init.sql");
// 嵌入模板
// const HTML_TEMPLATE: &str = include_str!("../templates/index.html");
// 嵌入 LICENSE
// const LICENSE: &str = include_str!("../LICENSE");
fn main() {
// 编译时嵌入的内容可以像普通字符串一样使用
println!("默认配置长度: {} 字节", DEFAULT_CONFIG.len());
// 可以在运行时解析
for line in DEFAULT_CONFIG.lines().take(5) {
println!("{}", line);
}
}include_bytes! 详解
// include_bytes! 将文件内容作为 &'static [u8; N] 嵌入
// 接受任意文件,不要求 UTF-8
// 嵌入图片
// const ICON: &[u8] = include_bytes!("../assets/icon.ico");
// 嵌入证书
// const CA_CERT: &[u8] = include_bytes!("../certs/ca.pem");
// 嵌入二进制数据
// const FIRMWARE: &[u8] = include_bytes!("../firmware/v1.bin");
// 嵌入字体
// const FONT: &[u8] = include_bytes!("../fonts/mono.ttf");
fn main() {
// 示例:嵌入一个小的二进制数据
let data: &[u8] = b"binary data example";
println!("数据长度: {} 字节", data.len());
println!("前 6 字节: {:?}", &data[..6]);
println!("include_bytes! 可以嵌入任意格式的文件");
}include_str! vs include_bytes!
| 特性 | include_str! | include_bytes! |
|---|---|---|
| 返回类型 | &'static str | &'static [u8; N] |
| 文件要求 | 必须是 UTF-8 | 任意二进制 |
| 适用场景 | 文本文件 | 图片、证书、二进制数据 |
| 非 UTF-8 文件 | 编译错误 | 正常工作 |
| 字符串操作 | 直接使用 | 需要转换 |
路径解析规则
// 路径相对于 **当前源文件** 所在的目录
// 假设项目结构:
// my-project/
// ├── Cargo.toml
// ├── README.md
// ├── data/
// │ └── config.json
// └── src/
// ├── main.rs
// └── utils/
// └── loader.rs
// 在 src/main.rs 中:
// include_str!("../README.md") → my-project/README.md
// include_str!("../data/config.json") → my-project/data/config.json
// 在 src/utils/loader.rs 中:
// include_str!("../../README.md") → my-project/README.md
// include_str!("../../data/config.json") → my-project/data/config.json
// 也可以从 CARGO_MANIFEST_DIR 出发(使用 concat!)
// include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/data/config.json"))
fn main() {
// 使用 env! 构建绝对路径
let manifest_dir = env!("CARGO_MANIFEST_DIR");
println!("项目根目录: {}", manifest_dir);
}基本示例
// 一个完整的嵌入文件使用示例
// 嵌入版本信息(假设项目根目录有 version.txt)
// const VERSION_INFO: &str = include_str!("../version.txt");
// 用 const 或 static 都可以
// static SQL_SCHEMA: &str = include_str!("../schema.sql");
/// 从嵌入的配置文件解析键值对
fn parse_simple_config(content: &str) -> Vec<(String, String)> {
content
.lines()
.filter(|line| !line.starts_with('#') && !line.is_empty())
.filter_map(|line| {
let mut parts = line.splitn(2, '=');
let key = parts.next()?.trim().to_string();
let value = parts.next()?.trim().to_string();
Some((key, value))
})
.collect()
}
fn main() {
// 模拟嵌入的配置内容
let config_content = "# 应用配置\nname=my-app\nport=8080\nhost=localhost";
let pairs = parse_simple_config(config_content);
for (key, value) in &pairs {
println!("{} = {}", key, value);
}
// 实际使用中:
// let pairs = parse_simple_config(include_str!("../config.txt"));
println!("\ninclude_str! 让配置文件编译进二进制,无需运行时文件读取");
}常见问题
问题一:include_str! 和 fs::read_to_string 有什么区别?
include_str! 在编译时读取文件,内容成为二进制的一部分,运行时不需要文件。fs::read_to_string 在运行时读取文件,需要文件在运行时存在。前者适合嵌入静态资源,后者适合读取可变配置。
问题二:嵌入大文件会怎样?
文件内容会增加二进制的大小。嵌入 10MB 的文件,二进制就会增大约 10MB。对于大文件,考虑运行时下载或使用压缩。
问题三:文件改了需要重新编译吗?
是的。但 Cargo 会自动追踪 include_str! 和 include_bytes! 引用的文件,文件变化时自动触发重新编译。
问题四:可以在 build.rs 生成的文件上使用吗?
可以。include_str!(concat!(env!("OUT_DIR"), "/generated.rs")) 可以包含 build.rs 在 OUT_DIR 中生成的文件。
适用场景
- 默认配置:嵌入默认配置文件
- SQL 语句:嵌入数据库迁移脚本
- 静态资源:嵌入 HTML 模板、CSS、图标
- 证书文件:嵌入 TLS 证书和密钥
- 单文件分发:不依赖外部文件的可执行程序
注意事项
- 路径相对于当前源文件所在目录
include_str!要求文件是 UTF-8 编码- 大文件会显著增加二进制体积
- Cargo 会自动追踪被包含文件的变化
concat!(env!("CARGO_MANIFEST_DIR"), "/path")构建项目根路径- 编译时读取,运行时不需要文件存在
总结
include_str! 和 include_bytes! 在编译时将外部文件嵌入到二进制中。include_str! 返回 &'static str(要求 UTF-8),include_bytes! 返回 &'static [u8; N](任意文件)。路径相对于当前源文件目录。Cargo 自动追踪被包含文件的变化。适用于嵌入默认配置、SQL 脚本、模板、图标、证书等静态资源。大文件会增加二进制体积,需要权衡是否运行时加载。concat!(env!("CARGO_MANIFEST_DIR"), "/path") 可以构建基于项目根的绝对路径。