val-blog/org/cases/val_blog/docs/05-routing-fix.md

05-routing-fix.md - 子路径路由修复

问题描述

通过 Tailscale 路径 /blog 访问博客时，除首页外其他链接会跳转到 OpenClaw Web 控制页根路径。

根本原因： Hugo 配置中 baseURL 设置为 http://localhost:1313/，未包含 /blog 子路径前缀，导致生成的 HTML 链接指向 / 而非 /blog/。

修复方案

1. 修改 config.toml

文件： site/config.toml

- baseURL = "http://localhost:1313/"
+ baseURL = "/blog/"

设置相对路径 /blog/，使 Hugo 生成的所有链接都带 /blog 前缀。

2. 修改 baseof.html 模板

文件： site/layouts/_default/baseof.html

将硬编码的绝对路径替换为 Hugo 模板函数：

原始代码	修复后
href="/css/main.css"	href="{{ "css/main.css" | absURL }}"
href="/"	href="{{ "" | absURL }}"
href="/journey"	href="{{ "journey" | absURL }}"

说明：

• absURL 函数会基于 baseURL 生成完整路径（如 /blog/css/main.css）
• 对于文章列表页使用 .RelPermalink（已自动处理子路径）

3. 修改 docker-compose.yml

文件： docker-compose.yml

- command: ["server", "-D", "--bind", "0.0.0.0", "--baseURL", "http://localhost:1313"]
+ command: ["server", "-D", "--bind", "0.0.0.0", "--baseURL", "http://localhost:1313/blog/"]

确保容器启动时使用正确的 baseURL。

验证步骤

本地验证

# 1. 启动服务
cd /Users/guchen/.openclaw/workspace/org/cases/val_blog
docker compose up -d

# 2. 验证首页访问
curl -s http://127.0.0.1:1313/blog/ | grep -E 'href='

# 3. 验证文章页访问
curl -s http://127.0.0.1:1313/blog/journey/ | grep -E 'href='

# 4. 验证生成静态文件的链接
docker exec val-blog-dev hugo -d /tmp/hugo-public
docker exec val-blog-dev grep -r 'href=' /tmp/hugo-public/index.html

预期结果：

• 所有 href 属性都包含 /blog/ 前缀
• CSS 链接：http://localhost:1313/blog/css/main.css
• 导航链接：http://localhost:1313/blog/、http://localhost:1313/blog/journey
• 文章链接：/blog/journey/xxx/

Tailscale 验证

通过 Tailscale 访问时，确保以下映射配置：

# 查看当前 Tailscale serve 配置
tailscale status
tailscale serve status

# 如需添加 /blog 路径映射（如果尚未配置）
tailscale serve --http=80 tcp:1313
# 然后在控制台将 /blog 路径映射到 Hugo 服务

回滚方案

如需回滚到根路径配置，执行以下操作：

1. config.toml:

   baseURL = "http://localhost:1313/"
   

2. baseof.html:

   <link rel="stylesheet" href="/css/main.css" />
   <a href="/">首页</a>
   <a href="/journey">旅程</a>
   

3. docker-compose.yml:

   command: ["server", "-D", "--bind", "0.0.0.0", "--baseURL", "http://localhost:1313"]
   

Tailscale Serve 建议命令

如果需要调整 Tailscale 路径映射：

# 方式一：仅映射 /blog 路径
tailscale serve http://127.0.0.1:1313/blog

# 方式二：查看当前映射状态
tailscale serve status

# 方式三：添加自定义域名的路径映射（需要 DNS 配置）
tailscale serve --bg your-domain.ts.net http://127.0.0.1:1313/blog

修改文件清单

文件	操作
site/config.toml	修改 baseURL
site/layouts/_default/baseof.html	替换硬编码链接
docker-compose.yml	更新启动命令