Hugo如何转义或移除分类标签路径URL中的#等特殊字符

Hugo默认的URL生成逻辑不会转义#、%这类URL保留字符——其中#会被浏览器和静态托管服务识别为锚点分隔符，不会参与文件路径匹配，这就是分类页返回404、Netlify构建失败的核心原因。以下两种方案都可以实现特殊字符的自动清理，不需要手动给每个标签/分类单独配置：

方案1：全局URL替换规则（推荐，Hugo v0.88.0及以上版本支持） #

直接在站点配置文件中添加自定义字符映射，在URL生成阶段统一替换特殊字符，所有页面（文章、分类、标签页）都会自动生效。
以TOML格式的config.toml为例，添加如下配置：

removePathAccents = true

# 自定义URL特殊字符替换映射
[urlize]
  replace = {
    "#" = "-sharp",
    "%" = "-percent",
    "&" = "-and",
    "+" = "-plus"
  }

# 分类、标签页固定使用处理后的slug生成路径
[permalinks]
  tags = "/tags/:slug/"
  categories = "/categories/:slug/"

如果使用YAML格式配置（config.yaml），对应写法为：

removePathAccents: true
urlize:
  replace:
    "#": "-sharp"
    "%": "-percent"
    "&": "-and"
    "+": "-plus"
permalinks:
  tags: "/tags/:slug/"
  categories: "/categories/:slug/"

配置完成后，C#标签会自动生成路径为/tags/c-sharp/的页面，符合技术社区通用的URL命名习惯。

方案2：模板层兼容处理（支持所有Hugo版本） #

如果使用的Hugo版本低于v0.88.0，不支持urlize.replace配置项，可以通过分类模板自动处理slug，实现兼容：

1. 首先在配置文件中明确定义分类规则（和原有配置保持一致即可）：

[taxonomies]
  tag = "tags"
  category = "categories"

2. 打开项目中layouts/_default/term.html模板文件（如果不存在就新建），在模板最顶部添加特殊字符替换逻辑：

{{/* 自动清理分类术语中的URL非法字符 */}}
{{ $rawTerm := .Data.Term | lower }}
{{ $cleanSlug := $rawTerm }}
{{ $cleanSlug = replace $cleanSlug "#" "-sharp" }}
{{ $cleanSlug = replace $cleanSlug "%" "-percent" }}
{{ $cleanSlug = replace $cleanSlug "&" "-and" }}
{{ $cleanSlug = replace $cleanSlug "+" "-plus" }}
{{ .Scratch.Set "termSlug" $cleanSlug }}

3. 后续模板中引用分类链接时，统一使用处理后的slug生成地址即可，示例：

<a href="{{ printf "/tags/%s/" (.Scratch.Get "termSlug") | relURL }}">
  {{ .Data.Term }}
</a>

注意事项：

• 配置完成后必须删除项目根目录下的public缓存目录和.hugo_build.lock文件，再重新执行构建命令，避免旧缓存导致规则不生效。
• 字符替换映射表可以根据自身使用场景按需扩展，不需要局限于示例中列出的几个特殊字符。
• 方案1的全局替换规则同时对普通文章页面生效，文章标题带特殊字符时也会自动生成合法URL，不需要再手动给单篇文章设置url参数。

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