为什么你的 SPA 网址必须包含 `#`？—— 前端路由 Hash 模式深度解析

为什么你的 SPA 网址必须包含 `#`？------ 前端路由 Hash 模式深度解析

文章目录

[为什么你的 SPA 网址必须包含 `#`？------ 前端路由 Hash 模式深度解析](#`？—— 前端路由 Hash 模式深度解析)
- 一、一个让开发者困惑的现象
- [二、现象复现：两种 URL，两种命运](#二、现象复现：两种 URL，两种命运)
- [三、基石：HTTP 请求中的 URL 结构](#三、基石：HTTP 请求中的 URL 结构)
- - 真实请求抓包对比
- [四、Hash 模式工作原理：SPA 的"秘密通道"](#四、Hash 模式工作原理：SPA 的“秘密通道”)
- - [1. 传统多页应用（MPA）的工作方式](#1. 传统多页应用（MPA）的工作方式)
  - [2. 单页应用（SPA）的困境](#2. 单页应用（SPA）的困境)
  - [3. Hash 模式的巧妙解决](#3. Hash 模式的巧妙解决)
  - [4. JavaScript 如何监听 Hash 变化](#4. JavaScript 如何监听 Hash 变化)
- [五、为什么你的 URL 里还有 `index.html`？](#五、为什么你的 URL 里还有 index.html？)
- [六、Hash 模式 vs History 模式：全面对比](#六、Hash 模式 vs History 模式：全面对比)
- - [History 模式如何解决"直接访问 404"？](#History 模式如何解决“直接访问 404”？)
- [七、实战：将你的项目从 Hash 模式迁移到 History 模式](#七、实战：将你的项目从 Hash 模式迁移到 History 模式)
- - [步骤 1：修改前端路由配置](#步骤 1：修改前端路由配置)
  - [步骤 2：配置服务器（以 Nginx 为例）](#步骤 2：配置服务器（以 Nginx 为例）)
  - [步骤 3：处理 404 页面](#步骤 3：处理 404 页面)
  - 其他服务器示例
- [八、常见误区与 FAQ](#八、常见误区与 FAQ)
- - [Q1：Hash 模式会影响 SEO 吗？](#Q1：Hash 模式会影响 SEO 吗？)
  - [Q2：Hash 模式有什么安全风险吗？](#Q2：Hash 模式有什么安全风险吗？)
  - [Q3：为什么刷新页面时，Hash 模式不会丢状态？](#Q3：为什么刷新页面时，Hash 模式不会丢状态？)
  - Q4：URL 太长包含 `#`，复制分享给别人会有影响吗？
  - [Q5：我的项目必须用 `index.html#/xxx`，如何改成 `/#/xxx`？](#/xxx，如何改成 /#/xxx`？)
- 九、总结

从 http://yourwebsite.com:81/index.html#/example_page 说起，揭开单页应用路由的神秘面纱。

一、一个让开发者困惑的现象

你是否遇到过这样的情况：开发了一个现代化的单页应用（SPA ，Single Page Application ），部署到服务器后，用户必须通过类似 http://yourwebsite.com:81/index.html#/example_page 这样的 URL 才能正常访问页面。如果手动去掉 # 或者直接访问子路径，迎接你的就是冰冷的 404 Not Found。

这并非 Bug，而是单页应用路由机制中的 Hash 模式 在起作用。本文将从 HTTP 协议、浏览器行为、前端路由原理等多个维度，为你彻底讲清其中的技术逻辑。

二、现象复现：两种 URL，两种命运

假设你有一个 SPA 部署在 http://yourwebsite.com:81/，下面两个 URL 会有截然不同的结果：

URL	结果
`http://yourwebsite.com:81/index.html#/example_page`	✅ 正常显示页面
`http://yourwebsite.com:81/index.html/example_page`	❌ 404 页面（或服务器错误）

为什么多了一个 # 就能决定生死？问题的根源要从浏览器与服务器的通信协议说起。

三、基石：HTTP 请求中的 URL 结构

一个完整的 URL 包含以下几个部分：

复制代码

http://domain:port/path/to/file?query=value#hash
\___/  \______/ \__________/ \_________/ \___/
 协议    主机+端口      路径         查询      哈希

其中 # 及其后面的部分称为 URL Hash （或锚点、片段标识符）。HTTP 规范明确规定：Hash 部分不会被发送到服务器。

真实请求抓包对比

当你在浏览器地址栏输入：

复制代码

http://yourwebsite.com:81/index.html#/dashboard

浏览器实际发送给服务器的请求行是：

复制代码

GET /index.html HTTP/1.1
Host: yourwebsite.com:81

服务器完全看不到 #/dashboard 这部分内容。它只负责找到并返回 /index.html 这个文件。

四、Hash 模式工作原理：SPA 的"秘密通道"

1. 传统多页应用（MPA）的工作方式

过去，每个 URL 路径对应服务器上的一个真实 HTML 文件。点击"关于我们"链接 → 请求 /about.html → 服务器返回完整页面 → 浏览器刷新。这种方式天然支持直接访问任意路径，因为服务器上确实有对应的文件。

2. 单页应用（SPA）的困境

现代 SPA（Vue/React/Angular）只有一个真正的 HTML 文件 ------ index.html。所有的"页面切换"都是通过 JavaScript 动态替换 DOM 元素来模拟的，不会向服务器请求新的 HTML。

但这里有一个致命问题：如果用户直接访问 http://yourwebsite.com:81/index.html/example_page（没有 #），浏览器会老老实实向服务器请求 /index.html/example_page 这个完整路径。服务器上并没有这个文件------项目只有一个 index.html，而 /example_page 只是一个前端逻辑意义上的"虚拟路由"。于是服务器返回 404 Not Found。

3. Hash 模式的巧妙解决

Hash 模式完美地绕开了这个矛盾：

用户访问 ：http://yourwebsite.com:81/index.html#/example_page
浏览器请求 ：只请求 http://yourwebsite.com:81/index.html（# 之后被丢弃）
服务器响应 ：正常返回 index.html
浏览器加载 ：页面中的 JavaScript 启动，读取 window.location.hash 的值（#/example_page）
前端路由 ：根据 hash 路径 #/example_page 匹配到对应的组件，动态渲染页面

而且，当用户点击 SPA 内部的导航链接时，JavaScript 只会修改 location.hash，不会触发页面刷新，完全符合 SPA 的丝滑体验。

4. JavaScript 如何监听 Hash 变化

前端路由库（如 Vue Router、React Router）内部利用浏览器的 hashchange 事件来监测 URL 中 # 部分的变化：

javascript 复制代码

window.addEventListener('hashchange', () => {
  const currentPath = window.location.hash.slice(1) // 去掉开头的 '#'
  // 根据 currentPath 渲染对应的页面组件
  renderComponent(currentPath)
})

每次 hash 变化，前端路由都会重新解析路径，更新视图，但整个过程没有任何网络请求。

五、为什么你的 URL 里还有 `index.html`？

你注意到示例 URL 是 .../index.html#/example_page，而不是更常见的 ...#/example_page。

通常，SPA 可以配置为在根路径直接返回 index.html，比如访问 http://yourwebsite.com:81/ 时服务器自动返回 index.html。此时内部路由可以是 http://yourwebsite.com:81/#/example_page。

而示例场景中出现了显式的 index.html，可能原因有：

服务器未配置默认索引 ：当你访问 http://yourwebsite.com:81/ 时，服务器没有自动返回 index.html（或配置不生效），用户必须显式写出文件。
构建配置的 publicPath ：前端打包工具（如 Webpack、Vite）将 publicPath 设为了 /index.html 或相对路径，导致路由基础路径包含了文件名。
静态文件托管方式：某些简易 HTTP 服务器或文件系统直接暴露目录，需要指定具体文件。

但无论是否显式写出 index.html，# 后面的路由机制完全一样。可以理解为：index.html 是入口文件，# 之后的内容是前端路由的"用户状态"。

六、Hash 模式 vs History 模式：全面对比

目前主流 SPA 框架支持两种路由模式：

对比项	Hash 模式	History 模式
URL 示例	`example.com/#/user/profile`	`example.com/user/profile`
服务器是否需要配置	否，开箱即用	是，必须配置 fallback
直接访问子路径	✅ 正常工作	❌ 会 404（无服务器配置）
刷新页面	✅ 正常	⚠️ 需服务器配合
SEO 友好度	差（搜索引擎忽略 # 后内容）	好
浏览器兼容性	所有浏览器，包括 IE6+	IE10+ 及所有现代浏览器
原理	利用 `hashchange` 事件	利用 `pushState` / `replaceState` API

History 模式如何解决"直接访问 404"？

History 模式同样只有一个 index.html，但通过服务器重写规则实现"所有请求都返回 index.html"：

nginx 复制代码

# Nginx 配置示例
location / {
    try_files $uri $uri/ /index.html;
}

这样，用户访问 /user/profile 时，Nginx 发现该路径不存在，就会返回 index.html，然后前端代码根据 /user/profile 这个路径渲染对应页面。服务器配置是 History 模式能否正常工作的关键。

七、实战：将你的项目从 Hash 模式迁移到 History 模式

如果你希望去掉 URL 中难看的 # 和可能的 index.html，可以按以下步骤操作。

步骤 1：修改前端路由配置

Vue Router（Vue 3）：

javascript 复制代码

import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),  // 改用 History 模式
  routes: [...]
})

React Router v6：

jsx 复制代码

import { BrowserRouter } from 'react-router-dom'

function App() {
  return <BrowserRouter>...</BrowserRouter>
}

Angular：

typescript 复制代码

RouterModule.forRoot(routes, { useHash: false })  // 默认就是 History 模式

步骤 2：配置服务器（以 Nginx 为例）

nginx 复制代码

server {
    listen 81;
    server_name yourwebsite.com;

    root /path/to/your/dist;   # 项目构建产物目录
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # 可选：处理静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

步骤 3：处理 404 页面

History 模式需要额外注意：当用户访问了一个不存在的真实路径（如 /not-exist）且前端也没有匹配路由时，服务器依然会返回 index.html，然后前端需要展示自定义的 404 页面。如果希望服务器直接返回 404 状态码，可以在前端路由的 fallback 中处理。

其他服务器示例

Apache（.htaccess）：

apache 复制代码

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

Node.js (Express)：

javascript 复制代码

const express = require('express')
const path = require('path')
const app = express()

app.use(express.static(path.join(__dirname, 'dist')))
app.get('*', (req, res) => {
  res.sendFile(path.join(__dirname, 'dist', 'index.html'))
})

GitHub Pages / 静态托管：

GitHub Pages 对 History 模式的支持有限，官方推荐使用 Hash 模式，或者通过 404.html 做 fallback 的 hack。一般建议内部系统、管理后台等无 SEO 要求的继续用 Hash 模式。

八、常见误区与 FAQ

Q1：Hash 模式会影响 SEO 吗？

会。搜索引擎（如 Google）虽然会执行 JavaScript，但 # 之后的内容通常不被视为独立页面。如果需要 SEO（例如 C 端产品），必须使用 History 模式。

Q2：Hash 模式有什么安全风险吗？

没有直接风险。# 之后的内容不会传到服务器，因此无法用于传递敏感 session 数据（必须放在查询参数或 POST body 中）。

Q3：为什么刷新页面时，Hash 模式不会丢状态？

因为刷新时浏览器请求的是 index.html（不含 hash），服务器正确返回后，前端代码重新读取当前 location.hash 并渲染，所以用户的"页面位置"得以保留。

Q4：URL 太长包含 `#`，复制分享给别人会有影响吗？

不会有功能影响，对方打开后会看到同样的页面。但如果对方用的不是 SPA 或禁用了 JavaScript，可能看不到正确内容（极少数情况）。

Q5：我的项目必须用 `index.html#/xxx`，如何改成 `/#/xxx`？

检查服务器的默认索引配置。在 Nginx 中添加 index index.html;，并确保访问根路径 / 时不出现目录列表。如果仍然不行，检查前端 publicPath 是否被错误设置成了 ./index.html。

九、总结

Hash 模式 ：简单、无需服务器配置，利用 # 不会发送到服务器的特性，实现 SPA 的路由。缺点是 URL 带 #，对 SEO 不友好。
History 模式：URL 干净，需要服务器配置 fallback，适合需要 SEO 的场景。
示例中出现 index.html#/ 是因为服务器默认索引配置或构建路径问题，核心路由机制仍然是 # 之后的 hash 路由。

理解了背后的原理，无论遇到 /#/ 还是 index.html#/，你都能从容应对。如果你现在正被 Hash 模式的折中方案所困扰，不妨评估你的项目是否需要 SEO，再决定是否迁移到 History 模式。如果需要迁移，按照上述步骤操作即可。

进一步阅读：

为什么你的 SPA 网址必须包含 `#`？—— 前端路由 Hash 模式深度解析