最常翻车的是模板中{{ .site.baseurl }}未被替换，导致浏览器静默丢弃base标签引发404；须确保base href值为合法路径且以/结尾，与前端路由base配置严格一致。
服务端模板里写 {{ .Site.BaseURL }} 但没替换就发到浏览器
这是最常翻车的点：模板里写了占位符，构建或渲染时没被真实路径替换，浏览器收到的是字面量 <base href="%7B%7B%20.Site.BaseURL%20%7D%7D">。浏览器一看这不是合法 URL（既不以 /、http://、https:// 也不以 // 开头），直接静默丢弃整个 <base> 标签——后续所有 src="logo.png" 全按当前页面 URL 解析，上线即 404。
实操建议：
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 部署前用 curl 或浏览器开发者工具查看源码，确认
<base href="...>%20%E7%9A%84%E5%80%BC%E6%98%AF%E7%9C%9F%E5%AE%9E%E8%B7%AF%E5%BE%84%EF%BC%8C%E4%B8%8D%E6%98%AF%E6%9C%AA%E8%A7%A3%E6%9E%90%E7%9A%84%E6%A8%A1%E6%9D%BF%E5%AD%97%E7%AC%A6%E4%B8%B2 %0A - Hugo%20%E7%94%A8%E6%88%B7%E6%A3%80%E6%9F%A5%20
config.toml%20%E4%B8%AD%20baseURL%20%E6%98%AF%E5%90%A6%E8%AE%BE%E5%AF%B9%EF%BC%8C%E4%B8%94%E6%9E%84%E5%BB%BA%E5%91%BD%E4%BB%A4%E6%9C%AA%E7%A6%81%E7%94%A8%E5%8F%98%E9%87%8F%E8%A7%A3%E6%9E%90%EF%BC%88%E5%A6%82%20hugo%20--minify%20%E9%BB%98%E8%AE%A4%E4%BF%9D%E7%95%99%EF%BC%89 %0A - Jekyll%20%E7%94%A8%E6%88%B7%E7%A1%AE%E8%AE%A4%20
_config.yml%20%E7%9A%84%20url%20%E5%92%8C%20baseurl%20%E7%BB%84%E5%90%88%E5%90%8E%E8%83%BD%E7%94%9F%E6%88%90%E5%90%88%E6%B3%95%E6%A0%B9%E7%9B%B8%E5%AF%B9%E8%B7%AF%E5%BE%84%EF%BC%88%E5%A6%82%20url:%20https://example.com%20+%20baseurl:%20"> → <code>href="/blog/"） - 若用 Node.js SSR（如 Express + EJS），确保
res.render()传入的base变量已拼好完整路径，且结尾带斜杠
<base href> 值结尾缺斜杠导致 Firefox 截断路径
写成 <base href="/myapp"> 看似没问题，但 Firefox 和 Opera 会把它截成 /myappcss/（把 css/ 直接粘到末尾），结果 <link href="css/app.css"> 变成请求 /myappcss/app.css，404。
实操建议：
- 根相对路径必须以
/结尾：<base href="/myapp/"> - 绝对 URL 也建议结尾带斜杠：
<base href="https://cdn.example.com/v2/">，避免某些 CDN 对路径拼接异常 - 别依赖协议相对 URL（
//cdn...）来省事——如果页面本身是file://协议（本地双击打开），它会失效
SSR 模板拼接时 header 和 page 各 render 一个 <base>
常见于组件化 SSR 架构：Layout 组件里写了一个 <base>，某个子页面又动态插入一个。浏览器只认第一个，第二个被忽略；控制台可能报 Multiple base elements detected. Only the first one is used.，但你未必看到。
实操建议：
- 把
<base>放到全局 Layout 的最顶部，且禁止任何子组件、中间件、插件再尝试注入 - 用正则或 HTML parser 在构建后验证最终 HTML 中
<base> 出现次数是否为 1 - 如果必须动态决定路径（如多租户站点），改用构建时环境变量注入，而非运行时条件渲染
SPA 场景下 <base href> 和前端路由 base 配置不一致
HTML 里写了 <base href="/admin/">，但 Vue Router 的 createRouter({ base: '/admin/' }) 没配，或者配成了 '/dashboard/'。结果：静态资源（JS/CSS）能加载，但 router.push('/users') 跳到 /users 而非 /admin/users，路由匹配失败。
实操建议：
- HTML 的
<base href>和前端路由的base配置项必须完全一致，包括结尾斜杠 - Vue Router 用户检查
router.options.base是否生效；React Router v6+ 用户确认<router basename="/admin/"></router>包住了整个应用 - 避免在 HTML 中写
<base>却让路由库用默认base: '/'—— 这种割裂会让跳转和资源加载走两套逻辑，问题极难复现
build.base）和 HTML 的 <base href> 同时启用且值相同，资源路径就可能被拼两次，比如 /admin//admin/js/app.js。这种错误不会报错，只会静默 404。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
