include_str 与 include_bytes ​

核心概念 ​

include_str! 和 include_bytes! 是 Rust 的内置宏,在编译时将外部文件的内容嵌入到二进制文件中。include_str! 将文件内容作为 &'static str 嵌入(要求文件是合法的 UTF-8 编码),include_bytes! 将文件内容作为 &'static [u8; N] 嵌入(接受任意二进制文件)。

这两个宏在编译时读取文件,文件内容直接成为二进制的一部分。不需要在运行时读取文件系统,因此程序可以作为单个可执行文件分发,不依赖外部文件。

rust
// 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! 详解 ​

rust
// 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! 详解 ​

rust
// 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 文件编译错误正常工作
字符串操作直接使用需要转换

路径解析规则 ​

rust
// 路径相对于 **当前源文件** 所在的目录

// 假设项目结构:
// 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);
}

基本示例 ​

rust
// 一个完整的嵌入文件使用示例

// 嵌入版本信息(假设项目根目录有 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") 可以构建基于项目根的绝对路径。