企业官网建设流程全解析

Starship Plain Text Symbols 预设：无 Unicode 环境下用纯文本符号打造跨终端提示符

【免费下载链接】starship☄🌌️ The minimal, blazing-fast, and infinitely customizable prompt for any shell!项目地址: https://gitcode.com/GitHub_Trending/st/starship

导读

Starship 的Plain Text Symbols（纯文本符号）预设是一套开箱即用的社区配置，它把提示符中各个模块的默认图标全部替换为纯 ASCII 文本（例如把 Git 分支的换成git、把 Rust 的🦀换成rs），专门解决终端字体缺少 Unicode/Nerd Font 字形时图标显示为方框或乱码的问题。阅读本文后，你将掌握该预设的完整 TOML 内容、一条命令的安装/卸载方法、底层starship preset子命令的实现机制，以及如何按需自定义符号。本文以 docs/pt-PT/presets/plain-text.md 为骨架，并结合本仓库源码进行纵深解读。

一、预设是什么：Starship 社区配置体系

Starship 的 预设（Presets）总览 收录了一系列由社区提交、经过项目维护的现成配置方案，例如 Nerd Font Symbols、Bracketed Segments、Tokyo Night、Catppuccin Powerline 等。每一个预设本质上都是一份完整的starship.toml片段，通过starship preset <名称>命令写入你的配置文件。

Plain Text Symbols 是其中之一，其官方定位是：

This preset changes the symbols for each module into plain text. Great if you don't have access to Unicode.

也就是说：它把每个模块的符号改成纯文本，适合无法使用 Unicode 的环境。典型场景包括：

• 使用不支持 Nerd Font 的旧式终端、远程 SSH 会话、串口或嵌入式终端；
• 终端字体缺失字形导致图标显示为「豆腐块」（tofu）乱码；
• 希望提示符在纯文本日志、CI 输出、文本复制粘贴时保持可读性。

注意：该预设只替换符号（symbol），不改变各模块的format、style等渲染逻辑，因此提示符的整体布局、颜色与模块顺序都保持 Starship 默认行为。

二、一行命令安装与卸载

安装

文档给出的官方安装命令如下：

starship preset plain-text-symbols -o ~/.config/starship.toml

命令含义拆解：

• starship preset：调用 src/main.rs 中定义的Preset子命令，负责输出内置预设；
• plain-text-symbols：预设名称，对应仓库中的 docs/public/presets/toml/plain-text-symbols.toml；
• -o ~/.config/starship.toml：-o/--output指定把预设内容写入目标文件（-f/--force可强制覆盖已存在的文件；-l/--list可列出所有可用预设名）。

执行后，~/.config/starship.toml被替换为预设内容，重启 shell 或新开终端即生效。若你的配置路径不同（例如通过STARSHIP_CONFIG环境变量指定），请相应调整-o参数。

备份与卸载

由于-o是整体覆盖写入，安装前建议先备份现有配置：

cp ~/.config/starship.toml ~/.config/starship.toml.bak

需要恢复时，将备份文件复制回去即可；若之前没有备份，也可以直接删除配置文件中由预设写入的对应小节，或整体删除配置文件回到 Starship 默认外观。

预设的 CLI 实现原理

starship preset命令在 src/print.rs 的preset_command中实现：它先从shadow::get_preset_list()拿到全部预设名，再调用shadow::get_preset_content(name)取出对应 TOML 文本，随后写入-o指定的文件（原子写入，见crate::utils::write_file_atomic）或直接打印到 stdout。这部分代码由 build.rs 在编译期生成：构建脚本会遍历docs/public/presets/toml/目录，把每个.toml文件名转成Preset枚举变体并用include_str!内嵌内容，因此预设清单与仓库中的 TOML 文件一一对应——你在docs/public/presets/toml/下看到多少个.toml，starship preset -l就能列出多少个名字。

三、预设完整配置逐模块解读

以下是该预设的完整 TOML 内容（与 docs/public/presets/toml/plain-text-symbols.toml 一致），我们按功能分组讲解每一段的作用。

3.1 全局与字符提示符

"$schema" = 'https://starship.rs/config-schema.json' continuation_prompt = ". " [character] success_symbol = ">" error_symbol = "x" vimcmd_symbol = "<" vimcmd_visual_symbol = "<" vimcmd_replace_symbol = "<" vimcmd_replace_one_symbol = "<"

• $schema：为编辑器提供 JSON Schema 校验与自动补全；
• continuation_prompt：多行输入时的续行提示符，从默认的箭头改为灰点.；
• [character]：主提示符符号。成功时显示绿色>，上一条命令失败显示红色x，Vim 模式下按状态分别显示<（normal/visual/replace 用不同颜色区分）。

3.2 Git 相关模块

[git_commit] tag_symbol = " tag " [git_status] ahead = ">" behind = "<" diverged = "<>" renamed = "r" deleted = "x" [git_branch] symbol = "git " truncation_symbol = "..."

• git_commit.tag_symbol：tag 提交前的标记，从默认标签图标改为tag；
• git_status：领先远端>、落后<、分叉<>、重命名r、删除x，均为纯 ASCII；
• git_branch.symbol：分支名前的符号改为git，truncation_symbol保留默认的...表示截断。

3.3 云平台与容器

[aws] symbol = "aws " [azure] symbol = "az " [gcloud] symbol = "gcp " [kubernetes] symbol = "kubernetes " [container] symbol = "container " [docker_context] symbol = "docker " [openstack] symbol = "openstack "

把 AWS、Azure、GCP、Kubernetes、容器、Docker 上下文、OpenStack 的模块符号统一改成对应小写英文缩写 + 空格，保证在纯文本终端中一眼可辨。

3.4 电池与系统信息

[battery] full_symbol = "full " charging_symbol = "charging " discharging_symbol = "discharging " unknown_symbol = "unknown " empty_symbol = "empty " [hostname] ssh_symbol = "ssh " [os.symbols] AIX = "aix " Alpine = "alp " Arch = "rch " Debian = "deb " Fedora = "fed " Ubuntu = "ubnt " Windows = "win " # …（共 50+ 个发行版条目）

• [battery]：电量五种状态（满电/充电/放电/未知/耗尽）分别显示英文单词；
• [hostname]：SSH 连接时主机名前缀从默认图标改为ssh；
• [os.symbols]：为操作系统模块维护了一张发行版缩写表，从 AIX、Alpine、Arch 到 Windows 共 50 余个条目，例如AlmaLinux = "alma "、CentOS = "cent "、Macos = "mac "、NixOS = "nix "、Ubuntu = "ubnt "。这是整个预设中体量最大的一张映射表，其键名与 src/modules/os.rs 中支持的系统标识一一对应。

3.5 编程语言运行时

[c] symbol = "C " [cpp] symbol = "C++ " [cobol] symbol = "cobol " [python] symbol = "py " [rust] symbol = "rs " [go] # 实际文件键名为 [golang] symbol = "go " [nodejs] symbol = "nodejs " [ruby] symbol = "rb " [dotnet] format = "via $symbol($version )(target $tfm )" symbol = ".NET " # …（buf、bun、conda、crystal、cmake、daml、dart、deno、elixir、elm、 # erlang、fennel、fortran、gleam、gradle、guix_shell、haskell、haxe、 # java、julia、kotlin、lua、maven、mojo、nim、ocaml、odin、opa、perl、 # php、pixi、purescript、quarto、raku、red、rlang、scala、solidity、 # swift、typst、vagrant、v 系、zig 等模块均按同样思路替换）

每个语言模块的symbol都替换为便于识别的短文本：C、C++、py、rs、go、nodejs、rb、.NET等。特别地，[dotnet]同时重写了format，使提示符以via .NET (版本)(target …)的形式呈现——这是该预设中少数同时调整格式而非仅换符号的模块。

3.6 其他常用模块

[directory] read_only = " ro" [jobs] symbol = "*" [memory_usage] symbol = "memory " [package] symbol = "pkg " [shlvl] symbol = "shlvl " [status] symbol = "x " not_executable_symbol = "noexec" not_found_symbol = "notfound" sigint_symbol = "sigint" signal_symbol = "sig" [sudo] symbol = "sudo " [fossil_branch] symbol = "fossil " truncation_symbol = "..." [hg_branch] symbol = "hg " truncation_symbol = "..." [jj_bookmark] symbol = "jj " truncation_symbol = "..." [pijul_channel] symbol = "pijul " truncation_symbol = "..."

• directory.read_only：只读目录在路径后追加ro；
• jobs：后台任务数符号从✦改为*；
• status：错误退出码显示红色x，同时为「不可执行」「命令未找到」「SIGINT 中断」「其他信号」提供noexec/notfound/sigint/sig纯文本标识；
• 各 VCS 模块（fossil、hg、jj、pijul）的符号与截断符也一并纯文本化。

完整内容约 340 行，覆盖了 Starship 全部内置模块的符号层，可直接在仓库 docs/public/presets/toml/plain-text-symbols.toml 中查看，也可用starship preset -l确认预设名、用starship preset plain-text-symbols（不加-o）直接预览完整 TOML 到终端。

四、预设文件如何被编译进二进制：从 TOML 到starship preset

这一节从源码角度说明为什么「改仓库里的 TOML 文件」就能改变starship preset的输出：

1. build.rs 的gen_presets_hook在编译期扫描docs/public/presets/toml/目录；
2. 每个*.toml文件名去掉扩展名后生成一个print::Preset("plain-text-symbols")枚举变体，同时用include_str!把文件内容嵌入二进制；
3. 生成的get_preset_list()与get_preset_content(name)被 src/print.rs 的preset_command调用；
4. src/main.rs 的Commands::Preset把 CLI 参数路由到preset_command，支持--output、--force、--list。

因此在当前仓库中，预设的「事实来源」就是docs/public/presets/toml/目录下的 12 个 TOML 文件；文档 docs/presets/plain-text.md 通过 VuePress 的<<< @/public/presets/toml/plain-text-symbols.toml语法直接把该文件内嵌展示，并提供了 TOML 下载入口。

此外，写入配置的过程最终会走到 src/configure.rs 的write_configuration：它用toml_edit解析现有配置文件并原子写回（crate::utils::write_file_atomic），保证 TOML 注释与格式在更新时尽量保留。

五、效果预览

上图来自仓库 docs/public/presets/img/plain-text-symbols.png，是该预设的实际运行截图：可以看到目录、Git 状态、语言运行时等模块的符号全部以纯文本呈现，即使在没有 Nerd Font 的终端中也能正常渲染。如果你只需要「去掉 Nerd Font 图标」而保留 emoji 与 powerline 符号，可参考同目录下的 No Nerd Fonts 预设，两者目标场景略有差异。

六、自定义与进阶：在预设基础上微调

starship preset输出的是完整配置而非增量补丁，因此你可以在安装后直接编辑~/.config/starship.toml微调：

• 只改某个符号：例如把 Python 符号改回带图标版本，只需把[python]下的symbol = "py "改为你需要的任意字符串（如symbol = "🐍 "），其余配置保持不变；
• 恢复默认符号：删除对应小节（如[python]），Starship 会自动回落到该模块的默认symbol；
• 批量自定义：参考 src/configs/ 目录下各模块的配置结构（例如 python.rs），所有模块的symbol都是可配置字符串，纯文本预设只是提供了一套覆盖全模块的现成取值。

若想验证效果，可使用：

starship explain # 显示当前提示符各模块的渲染来源 starship timings # 查看各模块耗时，确认预设没有引入性能问题

七、适用范围与注意事项

• 适用前提：需要 Starship 已安装且版本中包含preset子命令（本仓库源码 src/main.rs 中该子命令长期存在，starship preset -l可即时验证）；
• 覆盖行为：-o直接覆盖目标文件，务必先备份；
• 不改动模块顺序：该预设只替换符号与个别format，不会改变format中模块的排列，因此与自定义format配置不会冲突，只是符号被整体替换；
• 与 No Nerd Font 预设的区别：No Nerd Fonts 预设 的目标是「不使用任何 Nerd Font 字形，但保留 emoji 与 powerline 符号」，而 Plain Text Symbols 更进一步，把所有符号都降级为纯 ASCII 文本，兼容性最强，适合 SSH、旧终端、纯文本环境等极端场景。

结语

Plain Text Symbols 预设以「纯文本符号」为单一目标，用一张覆盖 50+ 发行版、30+ 语言运行时及全部内置模块的符号映射表，让 Starship 提示符在不依赖任何特殊字体的前提下保持完整可读性。通过本文的 TOML 逐段拆解与preset命令的源码级解析，你可以直接使用它，也可以以此为模板，为自己的环境定制一套专属的纯文本符号集。

【免费下载链接】starship☄🌌️ The minimal, blazing-fast, and infinitely customizable prompt for any shell!项目地址: https://gitcode.com/GitHub_Trending/st/starship