创建新分支后页面CSS与图片资源无法加载如何解决

核心诱因：拆分存放在templates、content目录的HTML片段，最终会被拼接到docs目录下的入口HTML中，所有资源路径的解析基准是最终生成的入口HTML所在位置（docs目录），而非片段文件自身的存放目录，绝大多数加载失败都是路径基准搞混导致的，按以下步骤排查即可：

第一步：先拿浏览器报错定位具体问题 #

• 打开出问题的页面按F12唤起开发者工具，切换到「Network（网络）」面板，刷新页面后筛选CSS、Img类请求，看失败请求的状态和实际请求路径：
  • 如果状态码是404 Not Found：直接看请求的URL路径，核对和实际文件目录结构的差异，比如出现/templates/css/xxx.css这类路径，就是写路径时多算了片段所在的templates/content目录层级
  • 如果状态码是403 Forbidden：是文件权限问题，在bash中执行以下命令给静态资源加可读权限即可：

    chmod -R 755 docs/css docs/img
    

  • 如果请求返回的内容是HTML代码而非CSS/图片：是服务端路由配置错误，静态资源请求被拦截转发到了入口HTML

第二步：统一资源引用规则，从根源避免路径错乱 #

不要在不同片段里各自按当前片段的目录写../这类层级相对路径，拼接后极易出问题，按你的部署场景选一种统一的写法：

• 场景1：用静态服务器托管（Nginx、GitHub Pages、本地开发服务器等，docs作为站点根目录）
  所有片段里的资源引用统一用站点根相对路径，路径最前面加/，基准永远是站点根（也就是docs目录），不受片段存放位置影响，写法示例：

  <!-- 顶部、底部、内容片段里都统一这么写，不用管片段在哪个目录 -->
  <link rel="stylesheet" href="/css/global.css">
  <img src="/img/logo.png" alt="站点logo">
  

• 场景2：本地直接双击打开拼接后的HTML文件预览（无本地服务器）
  这种情况/开头的路径会指向本地磁盘根目录，会加载失败，所有片段里的资源路径统一写相对于docs目录下入口文件的相对路径，不要加../，因为最终拼接入口文件在docs根，css、img目录和入口文件同级，写法示例：

  <link rel="stylesheet" href="css/global.css">
  <img src="img/logo.png" alt="站点logo">
  

第三步：核对拼接逻辑与生成的文件内容 #

• 检查你用来拼接三个HTML片段的bash脚本/构建逻辑，有没有自动给资源路径加前缀、转义字符的逻辑，避免拼接过程篡改路径
• 直接打开拼接完成后存放在docs目录下的入口HTML源码，核对里面的href、src属性值，和你预期的路径是否一致，比如如果看到路径里带../，就手动改成上面说的统一规则的路径，刷新页面验证

第四步：核对服务端配置（线上部署场景） #

• 确认托管服务的静态资源根目录是否正确指向docs目录，不要指到docs的上级或者下级目录
• 检查服务端重写规则，不要把/css/*、/img/*这类静态资源路径的请求拦截转发到入口HTML，静态资源请求要直接返回对应文件

快速验证技巧：直接打开docs目录下拼接好的入口HTML，把其中一个CSS引用临时改成./css/你的css文件名.css，刷新页面如果样式生效，就证明是之前的路径层级写反/写错了，对着目录结构逐段调整路径即可。

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