JS路径错误导致404加载失败：相对路径与绝对路径的正确写法

在网页开发中，当浏览器解析到 <script src="..."> 标签时，会根据当前页面的访问地址与属性中的路径字串拼接成一个完整的请求 URL。如果服务器或本地文件系统在这个目标地址找不到文件，就会触发 HTTP 404（或本地 FILE_NOT_FOUND）错误。解决该问题的核心在于：明确区分以当前 HTML 文件所在目录为基准的“相对路径”与以服务域名根目录为基准的“绝对路径”，并确保实际物理文件结构与拼接出的请求完全一致。

一、定位问题：看懂 404 报错与浏览器真实请求

许多人在遇到脚本加载失败时，第一反应是反复修改路径中的斜杠，这种盲目尝试往往效率低下。排查的第一步，是让浏览器明确告诉你它到底尝试去哪里找这个文件。

无论是在 Chrome、Edge 还是 Firefox 中，浏览器控制台（Console）给出的提示都只表明“未找到”。若要查明原因，请按以下步骤操作：

1. 打开开发者工具：按下 F12 或快捷键 Ctrl+Shift+I（macOS 为 Cmd+Option+I）。
2. 进入 Network（网络）面板：在顶栏筛选器中选中 JS，然后刷新页面（F5 或 Ctrl+R）。
3. 定位红色 404 请求：在列表中找到状态码为红字 404 的脚本名称，单击该项。
4. 查看 Request URL（请求网址）：在右侧面板的 Headers 中，查看浏览器完整拼接后的目标地址，并将其与本地项目目录中的真实存放位置逐层比对。

二、相对路径：语法符号与目录参照机制

相对路径之所以容易产生 404，是因为它的寻址参照点永远是“当前在浏览器中运行的 HTML 文件所在的目录”，而不是你的项目根目录，也不是编写 JS 代码的位置。

1. 相对路径的三种核心写法

• ./ 或不加前缀：表示同级目录。例如 ./main.js 或 main.js，意味着寻找与当前 HTML 处于同一个文件夹下的 main.js 文件。如果脚本在子目录，则写为 ./js/main.js。
• ../：表示向上返回上一级目录。如果需要向上一级并进入同级的另一个目录，可以写为 ../js/main.js。
• ../../：表示向上返回两级目录，每一个 ../ 就代表从当前目录向父级回退一层。

2. 典型项目目录结构示例

假设项目结构如下：

my-web-project/
├── index.html              (主页面)
├── pages/
│   ├── about.html          (关于页面，处于一级子目录)
│   └── user/
│       └── profile.html    (用户资料页，处于二级子目录)
└── assets/
    └── js/
        ├── core.js
        └── helper.js

针对同一个脚本文件 assets/js/core.js，不同深度的 HTML 文件所必须使用的相对路径完全不同：

• 在根目录的 index.html 中：

  <!-- 正确：从根目录直接向下进入 assets/js -->
  <script src="./assets/js/core.js"></script>
  <!-- 或者直接写目录名 -->
  <script src="assets/js/core.js"></script>

• 在一级子目录的 pages/about.html 中：

  <!-- 错误写法：会导致浏览器寻找 pages/assets/js/core.js (404) -->
  <script src="./assets/js/core.js"></script>
  
  <!-- 正确写法：先退出一级到 my-web-project，再进入 assets/js -->
  <script src="../assets/js/core.js"></script>

• 在二级子目录的 pages/user/profile.html 中：

  <!-- 正确写法：需要连续后退两层目录，再进入 assets/js -->
  <script src="../../assets/js/core.js"></script>

三、绝对路径：根相对路径与不同环境下的解析差异

绝对路径分为两类：带协议域名的“完整绝对路径”（如 https://cdn.example.com/app.js）和以单斜杠 / 开头的“服务端根相对路径”（如 /js/app.js）。

日常开发中最常发生 404 灾难的，正是以 / 开头的根相对路径。

1. 根相对路径的核心规则

以单斜杠 / 开头的路径，其寻址基准是当前站点的根域名（Web Server Root），它完全无视当前 HTML 文件在哪个子目录里：

<!-- 无论在 index.html 还是在 pages/user/profile.html 中 -->
<script src="/assets/js/core.js"></script>

在标准 Web 服务器（如 Nginx、Apache、Node.js 容器）下，无论当前页面访问的是 http://localhost:3000/ 还是 http://localhost:3000/pages/user/profile.html，浏览器都会统一向：
http://localhost:3000/assets/js/core.js 发起请求。

2. 两种致命踩坑场景：为什么根路径会失效？

四、现代前端开发中易忽略的 3 个隐蔽陷阱

除了基础写法外，以下三种情况经常会让开发者误以为路径写错了，实际上是解析规则被额外机制改变：

1. <base> 标签的全局基准劫持

如果 HTML 的 <head> 中被意外引入或配置了 <base href="..."> 标签：

<head>
    <base href="https://example.com/static-cdn/">
</head>
<body>
    <!-- 此时看似相对路径，实则全部以 base 的 href 为基准计算！ -->
    <script src="js/app.js"></script>
    <!-- 实际请求：https://example.com/static-cdn/js/app.js -->
</body>

一旦配置了 <base>，所有相对路径都不再以当前文件为基准，排查时务必检查 <head> 中是否存在该标签。

2. 单页面应用（SPA）History 模式的虚拟路由陷阱

在 Vue、React 前端路由使用 history 模式时，URL 地址可能会变为 http://localhost:3000/user/setting/security。实际上这个层级是前端虚拟路由，物理服务器上根本没有 /user/setting/ 目录。
如果此时打包产物中的 script 采用相对路径 ./js/bundle.js，浏览器就会误以为当前在二级子目录下，从而发起 http://localhost:3000/user/setting/js/bundle.js 请求，直接触发 404。

应对方案：SPA 项目在独立域名下应设置构建公共路径为绝对根路径（如 Vite 中的 base: '/'），确保无论路由切到多深的虚拟层级，脚本永远从根目录请求。

3. 大小写敏感与打包工具 Public 目录映射

Windows 和 macOS（默认）的文件系统不区分大小写，你在本地引用 ./js/App.js 时能正常运行；但部署到 Linux 生产服务器时，Linux 对大小写严格敏感，若磁盘上文件名实际为 app.js，则在生产环境必定爆出 404 错误。
此外，在 Vite 或 Webpack 中，放在 public/ 文件夹下的资源在打包时会直接复制到输出根目录。如果你在源码中写了 src="/public/js/app.js"，编译后该路径就会多出一层 public，正确写法应直接为 /js/app.js。

五、总结：路径写法决策模型与速查矩阵

如何保证代码无论在本地还是在线上都能稳定加载？可遵循以下决策准则：

1. 本地简易静态页面：始终启动本地轻量 HTTP 服务（如 VS Code 的 Live Server 插件，或在终端执行 npx serve . / python -m http.server 8000），严禁依赖 file:/// 协议双击调试。
2. 无构建设施的多页站点：统一使用精准计算的相对路径（./ 与 ../），使整个项目文件夹具备整体可移植性。
3. 确定部署在独立域名的前端应用：使用以 / 开头的根相对路径，屏蔽深层子路由对资源定位的干扰。
4. 部署在子路径或静态打包发布至多环境：使用相对根（如 Vite 的 base: './'）或注入环境变量（如 process.env.PUBLIC_URL）。