Cikio

Hash路由技术原理与设计解析

Cikio — Sun, 27 Sep 2026 00:00:00 GMT

1. 定义

Hash 路由（又称锚点路由）是一种基于浏览器 URL 中 # 号之后的部分来实现前端页面状态管理与视图切换的技术方案。其核心特征为：路径变更不触发服务器请求，完全由前端 JavaScript 控制渲染逻辑。

在单页应用（SPA）架构中，Hash 路由与 History 路由并列为两大主流前端路由实现方式。

2. 技术基础：浏览器底层机制

Hash 路由的可行性建立在两个浏览器原生机制之上：

2.1 `#` 的 HTTP 协议语义

根据 RFC 3986（URI 通用语法规范），URL 中的 # 标识符称为 fragment（片段标识符），其语义为”指向当前资源内的一个次级资源”（如章节锚点）。

关键特性：

fragment 部分不会被发送至服务器，仅由客户端解析。
修改 fragment 不会触发页面重新加载，因为资源定位符（scheme + host + path + query）未发生变化。
浏览器不会在 fragment 变化时向服务器发起新请求。

技术内涵：这实质上是将”路由解析权”从服务端转移至客户端，使前端获得了路径状态的管理能力。

2.2 `hashchange` 事件

HTML5 规范定义了 hashchange 事件，当 URL 的片段标识符（即 # 及之后的部分）发生变化时，浏览器自动触发该事件。

事件对象属性：

属性	描述
`oldURL`	变化前的完整 URL
`newURL`	变化后的完整 URL

通过监听此事件，前端应用可以感知路由变化并执行相应的视图更新逻辑。

3. 核心工作原理

Hash 路由的运行流程可拆解为四个环节：

① 用户操作（点击链接 / 浏览器前进后退 / 手动修改地址栏）
        ↓
② location.hash 发生变更
        ↓
③ 浏览器触发 hashchange 事件（页面不刷新）
        ↓
④ 事件监听回调执行路由匹配 → 渲染对应视图

3.1 路由变更的触发方式

触发方式	是否触发 `hashchange`	备注
`<a href="#/about">` 点击	✅ 是	浏览器默认行为
`window.location.hash = '#/about'`	✅ 是	唯一正确的编程式修改方式
`window.location.hash = '/about'`（不带 `#`）	❌ 否	赋值会被忽略（`#` 是必需的前缀）
`history.pushState(null, '', '#/about')`	❌ 否	`pushState()` 修改哈希值时不会触发 `hashchange` 事件。且根据 HTML 标准，`pushState` 的 URL 参数中 fragment 部分可能被忽略或处理方式与预期不同。不推荐通过此方式修改 hash。
`history.replaceState(null, '', '#/about')`	❌ 否	`replaceState()` 修改哈希值时同样不会触发 `hashchange` 事件。
浏览器前进/后退（同源内 hash 变化）	✅ 是	仅当实际 hash 值发生变化时触发
页面刷新	❌ 否（通过 `DOMContentLoaded` 恢复）	刷新后 `location.hash` 保留，需手动读取并渲染

核心结论：

编程式修改 hash 的唯一正确方式是 window.location.hash = '#/path'。该方法会同步更新地址栏、location.hash 属性，并自动触发 hashchange 事件。

pushState() 和 replaceState() 无论是否修改了 hash，都不会触发 hashchange 事件。

3.2 路由匹配策略

路由匹配的具体算法是各路由库的设计选择，而非 Hash 路由的固有原理。不同的路由库（如 React Router、Vue Router）对动态路由（如 /user/:id）的匹配优先级和算法（如正则、路径评分）各不相同。

以下为一种常见的匹配策略示例：

// 1. 定义路由表（路径 → 视图构造函数/组件）
const routeTable = new Map([
  ['/home', HomeComponent],
  ['/user/:id', UserComponent],
  ['/settings', SettingsComponent]
]);

// 2. 解析当前路径（支持动态参数）
function parseHash() {
  const raw = location.hash.slice(1); // 去掉 '#'
  const [path, queryString] = raw.split('?');
  // 解析查询参数
  const params = new URLSearchParams(queryString || '');
  return { path, params };
}

// 3. 路由匹配（示例：精确匹配优先）
function matchRoute(path) {
  // 精确匹配优先，再遍历动态路由
  // 返回 { component, params }
}

4. 优势分析

4.1 零服务器依赖

Hash 路由完全在前端运行，无需任何服务端配置（如 Nginx rewrite 规则）。即便使用 file:// 协议直接打开 HTML 文件，路由依然正常工作。

4.2 浏览器兼容性

hashchange 事件在主流浏览器中支持良好。在 IE8 中，该事件可通过 attachEvent('onhashchange', callback) 方式实现监听。onhashchange 属性方式在 IE9 之后得到更广泛支持。对于 IE7 及更早版本，通常需要通过 setInterval 轮询 location.hash 来模拟。

4.3 状态持久化

页面刷新后，location.hash 保留不变，应用可通过 DOMContentLoaded 事件读取并恢复至刷新前的路由状态。

4.4 天然的导航历史

每次 hash 变更自动产生一条浏览器历史记录，用户的前进/后退操作得到原生支持，无需额外维护历史栈。

4.5 隔离性

Hash 路由的路径信息与服务器资源路径隔离，不会与后端 API 路由产生命名冲突（例如 /api/users 与 #/users 互不干扰）。

5. 局限性

局限	说明
SEO 不友好	搜索引擎爬虫通常不执行 JavaScript，无法抓取 `#` 后的动态内容（Google 虽可索引部分 SPA 内容，但存在限制与延迟）
URL 美观度	地址栏包含 `#`，视觉上不如纯净路径
锚点冲突	页面原生锚点跳转（如 `#section-1`）与路由路径（`#/home`）共用同一命名空间。实际工程中，采用 `#/` 前缀统一风格即可规避冲突，传统锚点功能可通过 JS 滚动控制替代，属于工程实践问题，可通过设计规范轻松规避，并非根本性局限
服务端接收不到	`#` 后的所有内容不发送至服务端，日志分析、服务端鉴权等场景需通过其他方式（如 Cookie、Header）传递状态

6. 与 History 路由的技术对比

对比维度	Hash 路由	History 路由（基于 History API）
实现基础	`hashchange` 事件	`history.pushState` + `popstate`
地址格式	`xxx.com/#/path`	`xxx.com/path`
服务器配置	无需	需配置 fallback（否则刷新返回 404）
SEO 支持	差	优（配合 SSR/预渲染）
路径参数传递	URL 长度限制（同 HTTP）	URL 长度限制（同 HTTP），额外支持 `state` 对象传递非 URL 数据（注意：该数据不持久化，刷新页面后丢失，需另行存储如 localStorage）
服务端日志记录	无法记录完整路径	可记录完整路径

7. 实现参考（框架无关）

以下为一个遵循关注点分离原则的 Hash 路由最小实现：

class HashRouter {
  constructor(routes, { defaultRoute = '/home' } = {}) {
    this.routes = routes;
    this.defaultRoute = defaultRoute;
    this.currentPath = defaultRoute;

    // 绑定事件
    window.addEventListener('hashchange', this._onHashChange.bind(this));
    window.addEventListener('DOMContentLoaded', this._onHashChange.bind(this));

    // 初始化
    this._navigate(this._getCurrentPath());
  }

  _getCurrentPath() {
    return location.hash.slice(1) || this.defaultRoute;
  }

  _onHashChange() {
    const path = this._getCurrentPath();
    this._navigate(path);
  }

  _navigate(path) {
    const route = this.routes.find(r => r.path === path);
    if (route) {
      this.currentPath = path;
      route.render();
    } else {
      // 404 处理
      this._handleNotFound(path);
    }
  }

  _handleNotFound(path) {
    const fallback = this.routes.find(r => r.path === '*') || null;
    if (fallback) {
      fallback.render();
    } else {
      console.warn(`[HashRouter] 未匹配到路由: ${path}`);
    }
  }

  // 编程式导航 —— 直接操作 location.hash
  push(path) {
    // 标准方式：赋值给 location.hash，自动触发 hashchange
    location.hash = path.startsWith('#') ? path : `#${path}`;
  }

  // 替换当前历史记录条目
  replace(path) {
    const normalizedPath = path.startsWith('#') ? path : `#${path}`;
    // 直接通过 location.hash 修改，会触发 hashchange
    // 注意：这会新增一条历史记录，如需替换语义，可配合 history.replaceState 使用
    // 但需注意 replaceState 本身不会触发 hashchange
    location.hash = normalizedPath;
    // 如需替换当前历史条目而非新增，可额外调用：
    // history.replaceState(null, '', location.href);
  }
}

7.1 关于 `hashchange` 与 History API 的重要说明

pushState() 和 replaceState() 无论是否修改了 hash，都不会触发 hashchange 事件。
修改 hash 并触发 hashchange 的唯一标准方式是操作 location.hash。
如需在修改 hash 的同时控制历史栈（如替换而非新增），可组合使用 location.hash 赋值与 history.replaceState，但需明确后者不会触发 hashchange，事件仍由前者的赋值操作触发。

8. 适用场景

场景	是否适用	理由
后台管理系统	✅ 强烈推荐	无需 SEO，配置简单，开发效率高
移动端 H5 / WebApp	✅ 推荐	兼容性广，历史记录原生支持
浏览器扩展 / Electron	✅ 推荐	无服务器环境，hash 路由完美适配
官网 / 营销落地页	⚠️ 谨慎	若需 SEO，建议使用 History 模式 + SSR
博客 / 内容型站点	❌ 不推荐	SEO 需求优先级高于开发便捷性

9. 总结

Hash 路由是前端路由演进过程中的经典方案，其核心价值在于利用浏览器原生特性将路由控制权完整赋予前端，同时保持极低的接入成本和良好的兼容性。在单页应用、后台系统、H5 页面等场景中，Hash 路由至今仍是极具竞争力的技术选型。对于需要 SEO 优化的场景，可考虑在其基础上平滑升级至 History 路由方案。

本内容由 Frosti Feed 自动生成，可能存在排版问题；建议直接访问原文：https://www.cikio.cn/blog/hash-routing/

在 Markdown 中测试数学公式

Cikio — Sat, 31 May 2025 00:00:00 GMT

本文用来测试在 Markdown 中使用 $$ 分隔符渲染数学公式的效果。

基础代数

先从一些基础的代数表达式开始。

一元二次方程的求根公式： $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$

一个简单的一次函数： $y = mx + c$

二项式平方的展开： $(a+b)^2 = a^2 + 2ab + b^2$

微积分

下面是一些常见的微积分表达式。

导数的极限定义： $f'(x) = \lim_{h \to 0} \frac{f(x+h) - f(x)}{h}$

一个定积分： $\int_{a}^{b} f(x) dx$

$e^x$ 在 $x=0$ 处的泰勒展开： $e^x = \sum_{n=0}^{\infty} \frac{x^n}{n!} = 1 + x + \frac{x^2}{2!} + \frac{x^3}{3!} + \cdots$

三角学

一些基础的三角恒等式。

毕达哥拉斯恒等式（勾股定理的三角形式）： $\sin^2\theta + \cos^2\theta = 1$

正弦的和角公式： $\sin(\alpha + \beta) = \sin\alpha\cos\beta + \cos\alpha\sin\beta$

欧拉公式： $e^{i\theta} = \cos\theta + i\sin\theta$

统计与概率

统计与概率中常用的一些公式。

一组 $n$ 个数 $x_1, x_2, \ldots, x_n$ 的均值（ $\mu$ ）公式： $\mu = \frac{1}{n} \sum_{i=1}^{n} x_i$

正态分布的概率密度函数： $f(x | \mu, \sigma^2) = \frac{1}{\sqrt{2\pi\sigma^2}} e^{-\frac{(x-\mu)^2}{2\sigma^2}}$

贝叶斯定理： $P(A|B) = \frac{P(B|A)P(A)}{P(B)}$

线性代数

来自线性代数的几个例子。

一个 2×2 矩阵： $A = \begin{pmatrix} a & b \\ c & d \end{pmatrix}$

2×2 矩阵的行列式： $\det(A) = ad - bc$

矩阵 A 与矩阵 B 相乘： $C = AB$

物理

两个很著名的物理公式。

爱因斯坦质能方程： $E = mc^2$

牛顿第二定律： $F = ma$

以上内容可以用来检验各类数学公式的渲染效果。

本内容由 Frosti Feed 自动生成，可能存在排版问题；建议直接访问原文：https://www.cikio.cn/blog/mathematics-examples/

为 Frosti 添加评论系统

Cikio — Tue, 15 Apr 2025 00:00:00 GMT

引言

评论是博客最核心的能力之一，它让读者能够围绕你的内容展开交流。Frosti 已经为基于 Astro 的博客打下了不错的基础，但要加上评论系统还需要额外几步。本文会带你一步步把 Waline 评论系统接入 Frosti 博客。

像 Astro 构建的这类静态站点没有服务端处理能力，因此并不自带评论系统。不过我们可以借助第三方评论服务：后端由它们托管，我们只需把对应的前端组件集成到站点里。

在 Astro 中创建评论组件

在接入具体的评论系统之前，先了解一下 Astro 里组件的创建与使用方式。我们会做一个可复用组件，方便添加到任意页面。

组件结构

评论组件放在 src/components/comments 目录下。先确认这个目录存在：

mkdir -p src/components/comments

集成 Waline

Waline↗ 是一个简单、安全、功能丰富的前后端分离评论系统，可定制程度高，接入也很方便。

第一步：搭建 Waline 后端

在把 Waline 加到站点之前，需要先准备好后端：

创建一个 LeanCloud 应用，用来存放评论数据。
把 Waline 服务端部署到 Vercel 或其他托管平台。

按照 Waline 官方指南↗ 完成后端配置。部署完成后你会得到一个服务端 URL，前端组件需要用到它。

第二步：创建 Waline 组件

接下来创建一个可复用的 Waline 组件：

touch src/components/comments/Waline.astro

把下面的代码写进这个组件：

---
interface Props {
  serverURL: string;
  lang?: string;
  dark?: string;
  emoji?: string[];
  meta?: string[];
  requiredMeta?: string[];
  reaction?: boolean;
  pageview?: boolean;
}

const {
  serverURL,
  lang = "en",
  dark = "html[data-theme-type='dark']",
  emoji = ["https://unpkg.com/@waline/emojis@1.1.0/weibo", "https://unpkg.com/@waline/emojis@1.1.0/bilibili"],
  meta = ["nick", "mail", "link"],
  requiredMeta = [],
  reaction = false,
  pageview = false,
} = Astro.props;
---

<div id="waline-container"></div>

<link rel="stylesheet" href="https://unpkg.com/@waline/client@v3/dist/waline.css" />

<script
  type="module"
  define:vars={{
    serverURL,
    lang,
    dark,
    emoji,
    meta,
    requiredMeta,
    reaction,
    pageview,
  }}
>
  import { init } from "https://unpkg.com/@waline/client@v3/dist/waline.js";

  async function initWaline() {
    const container = document.querySelector("#waline-container");
    if (!container) return;

    init({
      el: "#waline-container",
      serverURL,
      path: location.pathname,
      lang,
      dark,
      emoji,
      meta,
      requiredMeta,
      reaction,
      pageview,
    });
  }

  document.addEventListener("astro:page-load", () => {
    initWaline();
  });

  if (document.readyState !== "loading") {
    initWaline();
  } else {
    document.addEventListener("DOMContentLoaded", initWaline);
  }
</script>

<style>
  #waline-container {
    margin-top: 2rem;
    margin-bottom: 2rem;
  }
</style>

第三步：使用 Waline 组件

现在就可以在 Astro 页面或布局中使用这个 Waline 组件了。下面是把它加到博客文章模板里的写法：

---
// 在博客文章的布局文件中
import Waline from "../../components/comments/Waline.astro";
// 其他导入与 frontmatter……
---

<!-- 你的博客正文 -->
<article>
  <slot />
</article>

<!-- 添加评论区 -->
<section class="comments">
  <h2>评论</h2>
  <Waline serverURL="https://your-waline-server.vercel.app" />
</section>

把 "https://your-waline-server.vercel.app" 换成你自己实际的 Waline 服务端 URL。

问题排查

常见问题

评论不显示： 检查 serverURL 是否配置正确并且可以访问。
样式异常： 确认 Waline 的样式表已正常加载。
部署问题： 如果服务端部署在 Vercel，检查环境变量与部署日志。

本内容由 Frosti Feed 自动生成，可能存在排版问题；建议直接访问原文：https://www.cikio.cn/blog/adding-comment-systems/

在 Frosti 中使用 MDX

Cikio — Fri, 12 Jul 2024 00:00:00 GMT

暂无正文内容。

本内容由 Frosti Feed 自动生成，可能存在排版问题；建议直接访问原文：https://www.cikio.cn/blog/frosti-mdx/

Markdown 语法示例

Cikio — Mon, 01 Jul 2024 00:00:00 GMT

这里演示在 Astro 中编写 Markdown 内容时常用到的一些基础语法。

标题

下面这些 HTML <h1>—<h6> 元素代表六个层级的标题，<h1> 层级最高，<h6> 最低。

H2

H3

H4

H5

H6

段落

这是一段用来演示段落排版的示例文字。Markdown 的段落之间以空行分隔，渲染时会把段落内的换行自动折行；只要行尾不留两个以上空格，就不会被当成强制换行。

写长文时也值得留意可读性：段落过长会让读者失去耐心，把一大段拆成几个自然段，阅读节奏会更舒服。

图片

语法

![图片替代文本](./图片的完整或相对路径)

输出

引用

引用（blockquote）元素用于标注取自其他来源的内容，可以带上出处说明（出处需写在 footer 或 cite 元素内），也可以包含批注、缩写等行内变化。

不带出处的引用

语法

> 引用块里的内容会以左侧竖线加缩进的形式呈现。
> **注意**：引用块内同样可以使用 _Markdown 语法_。

输出

引用块里的内容会以左侧竖线加缩进的形式呈现。注意：引用块内同样可以使用 Markdown 语法。

带出处的引用

语法

> 不要通过共享内存来通信，而要通过通信来共享内存。<br>
> — <cite>Rob Pike[^1]</cite>

输出

不要通过共享内存来通信，而要通过通信来共享内存。
— Rob Pike¹

表格

语法

| 斜体   | 粗体     | 代码   |
| ------ | -------- | ------ |
| _斜体_ | **粗体** | `代码` |

输出

斜体	粗体	代码
斜体	粗体	`代码`

代码块

语法

在新起的一行写 3 个反引号 ``` 再写代码片段，最后用另一行 3 个反引号收尾；想让代码带上语言相关的语法高亮，就在开头那 3 个反引号后面写一个语言名，例如 html、javascript、css、markdown、typescript、txt、bash。

```cpp
#include <bits/stdc++.h>
using namespace std;
const int N = 1e5 + 5;
int n, k, a[N];
long long ans;
vector<int> v[N];
int main()
{
    scanf("%d%d", &n, &k);
    for (int i = 1; i <= n; i++)
    {
        scanf("%d", &a[i]);
        v[i % k].push_back(a[i]);
    }
    for (int i = 0; i < k; i++)
        sort(v[i].rbegin(), v[i].rend());
    for (int i = 0; i < k; i++)
    {
        for (int j = 0; j + 1 < v[i].size(); j += 2)
        {
            ans += v[i][j] + v[i][j + 1];
        }
    }
    printf("%lld\n", ans);
    return 0;
}
```

输出

#include <bits/stdc++.h>
using namespace std;
const int N = 1e5 + 5;
int n, k, a[N];
long long ans;
vector<int> v[N];
int main()
{
    scanf("%d%d", &n, &k);
    for (int i = 1; i <= n; i++)
    {
        scanf("%d", &a[i]);
        v[i % k].push_back(a[i]);
    }
    for (int i = 0; i < k; i++)
        sort(v[i].rbegin(), v[i].rend());
    for (int i = 0; i < k; i++)
    {
        for (int j = 0; j + 1 < v[i].size(); j += 2)
        {
            ans += v[i][j] + v[i][j + 1];
        }
    }
    printf("%lld\n", ans);
    return 0;
}

列表类型

有序列表

语法

1. 第一项
2. 第二项
3. 第三项

输出

第一项
第二项
第三项

无序列表

语法

- 列表项
- 另一项
- 还有一项

输出

列表项
另一项
还有一项

嵌套列表

语法

- 水果
  - 苹果
  - 橙子
  - 香蕉
- 乳制品
  - 牛奶
  - 奶酪

输出

水果
- 苹果
- 橙子
- 香蕉
乳制品
- 牛奶
- 奶酪

其他元素

语法

<abbr title="Graphics Interchange Format">GIF</abbr> 是一种位图图像格式。

H<sub>2</sub>O

X<sup>n</sup> + Y<sup>n</sup> = Z<sup>n</sup>

按 <kbd>CTRL</kbd>+<kbd>ALT</kbd>+<kbd>Delete</kbd> 结束会话。

大多数<mark>蝾螈</mark>是夜行动物，以昆虫、蠕虫和其他小生物为食。

输出

GIF 是一种位图图像格式。

H₂O

Xⁿ + Yⁿ = Zⁿ

按 CTRL+ALT+Delete 结束会话。

大多数蝾螈是夜行动物，以昆虫、蠕虫和其他小生物为食。

以上引文摘自 Rob Pike 在 2015 年 11 月 18 日 Gopherfest 上的演讲↗。 ↩

本内容由 Frosti Feed 自动生成，可能存在排版问题；建议直接访问原文：https://www.cikio.cn/blog/markdown-style-guide/

使用 MDX

Cikio — Sat, 02 Jul 2022 00:00:00 GMT