urls.Parse
解析给定 URL,返回一个 URL 结构体。
这一页解决什么问题
拿到一条地址后要分别取出它的部分:域名是谁、路径是什么、查询参数有几个、锚点是什么。模板里靠字符串切分很脆弱,urls.Parse 把地址解析成 Go 的 url.URL 结构体,之后就能按字段名取值或调用 Query.Get。
典型场景:判断链接是不是外链(比较主机名)、给外部图片加参数、从带查询串的地址里取出某个参数。
什么时候用,什么时候别用
该用:
- 需要按结构访问地址的各个部分(主机、路径、查询、片段);
- 需要解析查询参数(
Query.Get、Query.Has)。
别用:
- 只是想拼出地址 → 用
urls.AbsURL、urls.RelURL、urls.JoinPath; - 只想判断是不是以
http开头 → 用strings.HasPrefix更快; - 想生成可以放进
<a href>的字符串 → 解析结果需要取.String;只是规范化地址则未必值得解析。
用法
urls.Parse 函数把 URL 解析为一个 URL 结构体。URL 可以是相对形式(一条路径,没有主机名),也可以是绝对形式(以方案开头)。解析无效 URL 时 Hugo 会抛出错误。
go-html-template
{{ $url := "https://example.org:123/foo?a=6&b=7#bar" }}
{{ $u := urls.Parse $url }}
{{ $u.String }} → https://example.org:123/foo?a=6&b=7#bar
{{ $u.IsAbs }} → true
{{ $u.Scheme }} → https
{{ $u.Host }} → example.org:123
{{ $u.Hostname }} → example.org
{{ $u.RequestURI }} → /foo?a=6&b=7
{{ $u.Path }} → /foo
{{ $u.RawQuery }} → a=6&b=7
{{ $u.Query }} → map[a:[6] b:[7]]
{{ $u.Query.a }} → [6]
{{ $u.Query.Get "a" }} → 6
{{ $u.Query.Has "b" }} → true
{{ $u.Fragment }} → bar完整示例(实测)
layouts/_partials/link-parts.htmlgo-html-template
{{ $u := urls.Parse "https://example.org:123/foo?a=6&b=7#bar" }}
主机={{ $u.Hostname }}|路径={{ $u.Path }}|参数 a={{ $u.Query.Get "a" }}|有 b={{ $u.Query.Has "b" }}|锚点={{ $u.Fragment }}Hugo 0.167.0 实测输出:
主机=example.org|路径=/foo|参数 a=6|有 b=true|锚点=bar你应当看到什么:Hostname 去掉了端口(Host 才是 example.org:123),Query.Get "a" 直接拿到字符串 6,Query.Has "b" 返回布尔值。要拿整条地址就用 .String。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'zh-CN'),Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
| 绝对地址(实测上游示例那条) | 各字段如上游表格(Host=example.org:123,Hostname=example.org,Query=map[a:[6] b:[7]]) |
否 |
相对地址(实测 "/foo?a=1#f") |
IsAbs=false,Scheme 与 Host 都是空字符串,Path=/foo,RawQuery=a=1,Fragment=f,String=/foo?a=1#f |
否 |
非法地址(实测 "http://[::1") |
—— | 是,构建失败:error calling Parse: parse "http://[::1": missing ']' in host |
非法地址(实测 "://bad") |
—— | 是,构建失败:error calling Parse: parse "://bad": missing protocol scheme |
| 返回类型 | url.URL 结构体(不是字符串);要字符串请取 .String |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 报错看不懂 | missing ']' in host / missing protocol scheme,整站构建失败 |
传入的地址本身不合法;Hugo 直接让构建失败 | 先用 with 判断来源可信,或在数据源头修正地址 |
| 没报错但结果不对 | 拿到的域名带了端口 | 用的是 Host 而不是 Hostname |
只要主机名就用 .Hostname(实测它去掉 :123) |
| 没报错但结果不对 | Query.Get 取不到值 |
参数名大小写不符,或值在片段(#)之后 |
用 Query.Has 先确认;片段部分用 .Fragment |
| 没报错但结果不对 | 把结构体直接输出 | url.URL 是结构体,不是字符串 |
取 .String 或具体字段 |
更多排查入口见故障排查。