如何解决Cargo报错：‘注册表名称包含无效字符’

问题描述 #

近几个月多次遇到同一Cargo错误，使用rustup提供的最新版Cargo，在Kubuntu命令行执行cargo install时触发错误。

错误示例

$ cargo install csvlens
error: invalid character `…` in registry name: `…`, the first character must be a Unicode XID start character (most letters or `_`)

补充信息 #

• [编辑1] 附上Cargo的config.toml文件，为默认配置模板，其中有多行类似token = "…"的占位符内容，与错误信息中的字符一致。
• [编辑2] 注释掉所有使用= "…"语法的行后，成功安装了一个crate。

用户疑问：

1. 问题出在哪里？
   • 是cargo、rust或git的配置/环境问题？
   • 是crate的注册表条目问题，需要等待修复？
   • 是Cargo bug、项目方bug还是本地问题？
2. 问题是什么，为何反复出现？大概4-5个月前cargo install开始失效。
3. 如何绕过该问题，顺利安装crate/命令？

附上~/.config/Cargo/config.toml内容

##  Cargo config.toml
#
#     * see: [Configuration, The Cargo Book](https://doc.rust-lang.org/cargo/reference/config.html)
#
##  paths = ["/path/to/override"] # path dependency overrides

[alias]     # command aliases


[build]
jobs = 4                        #   number of parallel jobs, defaults to # of CPUs
incremental = true              #   whether or not to enable incremental compilation
dep-info-basedir = "…"          #   path for the base directory for targets in depfiles


[doc]
browser = "firefox"             #   browser to use with `cargo doc --open`,
                                #   overrides the `BROWSER` environment variable

[env]
##  Set ENV_VAR_NAME=value for any process run by Cargo
#       ENV_VAR_NAME = "value"
#
#   Set even if already present in environment
#       ENV_VAR_NAME_2 = { value = "value", force = true }
#
#   Value is relative to .cargo directory containing `config.toml`, make absolute
#       ENV_VAR_NAME_3 = { value = "relative/path", relative = true }

[future-incompat-report]
frequency = 'always' # when to display a notification about a future incompat report


[cargo-new]
vcs = "git"              # VCS to use ('git', 'hg', 'pijul', 'fossil', 'none')


[http]
#   debug = false               # HTTP debugging
#   proxy = "host:port"         # HTTP proxy in libcurl format
#   ssl-version = "tlsv1.3"     # TLS version to use
#   ssl-version.max = "tlsv1.3" # maximum TLS version
#   ssl-version.min = "tlsv1.1" # minimum TLS version
#   timeout = 30                # timeout for each HTTP request, in seconds
#   low-speed-limit = 10        # network timeout threshold (bytes/sec)
#   cainfo = "cert.pem"         # path to Certificate Authority (CA) bundle
#   check-revoke = true         # check for SSL certificate revocation
#   multiplexing = true         # HTTP/2 multiplexing
#   user-agent = "…"            # the user-agent header

[install]
#   root = "/some/path"         # `cargo install` destination directory

[net]
#   retry = 3                   # network retries
#   git-fetch-with-cli = true   # use the `git` executable for git operations
#   offline = true              # do not access the network

[net.ssh]
known-hosts = ["..."]       # known SSH host keys

##  [patch.<registry>]
##    Same keys as for [patch] in Cargo.toml


# [profile.<name>]         # Modify profile settings via config.
#   inherits = "dev"         # Inherits settings from [profile.dev].
#   opt-level = 0            # Optimization level.
#   debug = true             # Include debug info.
#   split-debuginfo = '...'  # Debug info splitting behavior.
#   strip = "none"           # Removes symbols or debuginfo.
#   debug-assertions = true  # Enables debug assertions.
#   overflow-checks = true   # Enables runtime integer overflow checks.
#   lto = false              # Sets link-time optimization.
#   panic = 'unwind'         # The panic strategy.
#   incremental = true       # Incremental compilation.
#   codegen-units = 16       # Number of code generation units.
#   rpath = false            # Sets the rpath linking option.
# [profile.<name>.build-override]  # Overrides build-script settings.
#   Same keys for a normal profile.
#   [profile.<name>.package.<name>]  # Override profile for a package.
# Same keys for a normal profile (minus `panic`, `lto`, and `rpath`).


# [registries.<name>]  # registries other than crates.io
#   index = "…"          # URL of the registry index
#   token = "…"          # authentication token for the registry

[registry]
    default = "…"        # name of the default registry
    token = "…"          # authentication token for crates.io


# [source.<name>]      # source definition and replacement
#   replace-with = "…"   # replace this source with the given named source
#   directory = "…"      # path to a directory source
#   registry = "…"       # URL to a registry source
#   local-registry = "…" # path to a local registry source
#   git = "…"            # URL of a git repository source
#   branch = "…"         # branch name for the git repository
#   tag = "…"            # tag name for the git repository
#   rev = "…"            # revision for the git repository


# [target.<triple>]
#   linker = "…"            # linker to use
#   runner = "…"            # wrapper to run executables
#   rustflags = ["…", "…"]  # custom flags for `rustc`

# [target.<cfg>]
#   runner = "…"            # wrapper to run executables
#   rustflags = ["…", "…"]  # custom flags for `rustc`

# [target.<triple>.<links>] # `links` build script override
#   rustc-link-lib = ["foo"]
#   rustc-link-search = ["/path/to/foo"]
#   rustc-flags = ["-L", "/some/path"]
#   rustc-cfg = ['key="value"']
#   rustc-env = {key = "value"}
#   rustc-cdylib-link-arg = ["…"]
#   metadata_key1 = "value"
#   metadata_key2 = "value"


[term]
quiet = false          # whether cargo output is quiet
verbose = false        # whether cargo provides verbose output
color = 'auto'         # whether cargo colorizes output
hyperlinks = true      # whether cargo inserts links into output
progress.when = 'auto' # whether cargo shows progress bar
progress.width = 80    # width of progress bar

问题解答 #

1. 问题根源 #

这是本地配置问题，和Cargo、rust、git本身或者crate的注册表条目无关。
你的~/.config/Cargo/config.toml中，[registry]区块的default = "…"把默认注册表名称设成了占位符…，而Cargo要求注册表名称的首字符必须是Unicode XID起始字符（大多数字母或下划线），…不符合规则，因此触发错误。

2. 问题本质与反复出现原因 #

问题核心就是配置文件里的无效注册表名称。反复出现是因为每次执行cargo install都会读取这个配置文件，只要错误配置存在，就会触发报错。
4-5个月前开始失效，大概率是当时你修改了Cargo配置（比如复制了带占位符的模板、误改了配置项），导致无效配置一直留存。

3. 解决与绕过方法 #

• 彻底解决：修改~/.config/Cargo/config.toml的[registry]区块，将default = "…"改为default = "crates.io"（官方默认注册表）；如果没有配置crates.io的token，把token = "…"注释或删除。另外，其他带…的占位符行（如build.dep-info-basedir = "…"）若没有实际值，也建议注释或删除，避免后续潜在问题。
• 临时绕过：像你之前操作的那样，暂时注释所有带= "…"的配置行，执行完cargo install后再按需恢复（更推荐直接修正配置）。

内容的提问来源于stack exchange，提问作者will