小氢云商城自定义路由系统完整使用教程（含单页示例）

2026-05-29

小氢云商城系统

文章摘要

|

小氢云商城自定义路由系统完整使用教程

适用版本：小氢云商城系统（Go 后端 + 管理后台 web-antd）
阅读对象：站长、运营、二次开发者
最后更新：2026-05-29

一、这套「路由系统」到底是什么？

在小氢云商城里，自定义路由映射系统（后台菜单：路由映射管理）是一套无需改代码、无需重新打包前端就能上线新页面的能力。

你可以把它理解成：

用户访问 URL  →  系统查映射表  →  读取 doc 目录文件 / 装修配置  →  渲染页面

典型用途包括：

落地页、活动页、品牌介绍页
独立 API 文档页、帮助中心
绑定独立域名做品牌站首页
绑定「网站装修项目」做可视化拖拽页面
付费内容页（会员专享资料、教程等）

和 Vue Router 的区别： PC/PE 前端里的 Vue Router 管的是商城 SPA 内部跳转；本文讲的是服务端级别的自定义路由，直接由 Go 中间件拦截 HTTP 请求并返回内容，SEO 友好、可独立访问。

二、整体架构（建议先建立心智模型）

flowchart TD
    A[用户请求 /promo/sale] --> B{是否为 /api/* 或后台路径?}
    B -->|是| C[放行给 API / 静态资源]
    B -->|否| D[CustomRouteMiddleware 中间件]
    D --> E{Redis 缓存命中?}
    E -->|否| F[查 MySQL sky_route_mapping]
    F --> G[写入 Redis 永久缓存]
    E -->|是| H[读取映射配置]
    G --> H
    H --> I{数据源类型}
    I -->|file| J[读取 doc 下 HTML/JS/CSS/PHP 等]
    I -->|decoration| K[读取装修项目 JSON 配置]
    J --> L{访问控制}
    K --> L
    L -->|需登录/付费| M[拦截并展示登录/付费页]
    L -->|通过| N[占位符替换 + 静态路径重写 + 返回内容]

flowchart TD
    A[用户请求 /promo/sale] --> B{是否为 /api/* 或后台路径?}
    B -->|是| C[放行给 API / 静态资源]
    B -->|否| D[CustomRouteMiddleware 中间件]
    D --> E{Redis 缓存命中?}
    E -->|否| F[查 MySQL sky_route_mapping]
    F --> G[写入 Redis 永久缓存]
    E -->|是| H[读取映射配置]
    G --> H
    H --> I{数据源类型}
    I -->|file| J[读取 doc 下 HTML/JS/CSS/PHP 等]
    I -->|decoration| K[读取装修项目 JSON 配置]
    J --> L{访问控制}
    K --> L
    L -->|需登录/付费| M[拦截并展示登录/付费页]
    L -->|通过| N[占位符替换 + 静态路径重写 + 返回内容]

核心存储

层级	作用
MySQL `sky_route_mapping`	持久化所有路由映射配置
Redis	永久缓存映射关系，加速访问
doc 目录	与后端可执行文件同级的文件仓库，存放 HTML/静态资源/PHP 等

缓存键规则

键名 = route_mapping: + md5(全局配置 zhuzhan + 路由路径)
值   = 文件相对路径，如 promo/sale.html

创建、更新、删除映射时系统会自动维护 Redis；也可在后台点击 「刷新缓存」 批量同步。

三、功能清单（一张表看懂能做什么）

功能	说明
路由映射	如 `/about` → `pages/about.html`
域名映射	如 `brand.example.com` 根路径 → 指定页面（需 DNS 解析到服务器）
数据源：文件	HTML / JSON / CSS / JS / PHP / SVG / MD 等文本格式
数据源：装修项目	绑定后台「网站装修」拖拽项目，前端 SPA 动态渲染
设备类型	`pc` 电脑端 / `pe` 手机端 / `def` 通用
强制登录	未登录用户看到内置登录页（需开启用户系统）
付费访问	设置价格，未购买用户看到付费引导页
元数据 Metadata	JSON 表单配置，写入 Cookie，页面内可用 `[元数据]` 占位符读取
占位符变量	自动替换网站标题、备案号、Logo、SEO 等系统配置
静态资源自动映射	页面同级目录下的 `assets/`、`static/`、`css/` 等自动可访问
导入/导出	批量迁移路由配置
在线文件管理	后台可直接上传、编辑 doc 目录文件
访问统计	今日/累计访问量（Redis 统计）
PHP 动态页	配置 PHP 解释器后可执行 `.php` 文件

四、快速上手：5 分钟发布第一个单页

步骤 1：进入管理后台

路径：系统管理 → 路由映射管理（或全局搜索「路由映射」）。

步骤 2：准备页面文件

方式 A — 后台在线创建（推荐新手）

点击 「浏览文件」
在 doc 目录下新建文件夹，如 pages
新建文件 welcome.html，粘贴下方【完整单页示例】代码
保存

方式 B — 服务器手动上传

# 在后端程序同级目录
mkdir -p doc/pages
cp welcome.html doc/pages/welcome.html

# 在后端程序同级目录
mkdir -p doc/pages
cp welcome.html doc/pages/welcome.html

doc 目录若不存在，系统会在首次浏览文件时自动创建。

步骤 3：添加路由映射

点击 「添加路由」，填写：

字段	示例值
映射方式	通过路由
路由路径	`/welcome`
数据源类型	文件
文件路径	`pages/welcome.html`
状态	启用
设备类型	通用

保存后，访问：

https://你的域名/welcome

即可看到页面。

步骤 4：验证

页面标题、Logo 等占位符是否被正确替换
打开浏览器开发者工具 → Network，确认 CSS/JS 加载 200
后台列表中「访问统计」是否增加

五、完整单页 HTML 示例（可直接复制使用）

将以下代码保存为 doc/pages/welcome.html，并映射路由 /welcome：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>[title] - 欢迎页</title>
  <meta name="keywords" content="[seo_keywords]" />
  <meta name="description" content="[seo_description]" />
  <link rel="icon" href="[favicon]" />
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      min-height: 100vh;
      display: flex;
      align-items: center;
      justify-content: center;
      color: #fff;
    }
    .card {
      background: rgba(255,255,255,0.95);
      color: #333;
      border-radius: 16px;
      padding: 48px 40px;
      max-width: 520px;
      width: 90%;
      box-shadow: 0 20px 60px rgba(0,0,0,0.3);
      text-align: center;
    }
    .logo { width: 64px; height: 64px; border-radius: 12px; margin-bottom: 20px; }
    h1 { font-size: 28px; margin-bottom: 12px; }
    p { color: #666; line-height: 1.8; margin-bottom: 24px; }
    .meta { font-size: 13px; color: #999; margin-bottom: 32px; }
    .btn {
      display: inline-block;
      padding: 12px 32px;
      background: #667eea;
      color: #fff;
      text-decoration: none;
      border-radius: 8px;
      font-weight: 600;
      transition: transform 0.2s, box-shadow 0.2s;
    }
    .btn:hover { transform: translateY(-2px); box-shadow: 0 8px 20px rgba(102,126,234,0.4); }
    footer { margin-top: 32px; font-size: 12px; color: #bbb; }
  </style>
</head>
<body>
  <div class="card">
    <img class="logo" src="[logo]" alt="Logo" onerror="this.style.display='none'" />
    <h1>欢迎来到 [title]</h1>
    <p>这是通过<strong>自定义路由系统</strong>发布的独立单页。<br/>无需修改前端代码，后台配置即可上线。</p>
    <div class="meta">
      当前路由：<code>[router]</code><br/>
      站点地址：<a href="[base_url]">[base_url]</a><br/>
      建站时间：[site_time]
    </div>
    <a class="btn" href="[base_url]">进入商城首页</a>
    <footer>
      [RecordNumber] [PoliceRecordNumber]
    </footer>
  </div>

  <script>
    // 元数据占位符已被 Unicode 转码，可安全嵌入
    var routeMeta = "[元数据]";
    if (routeMeta && routeMeta !== "[元数据]") {
      try {
        var meta = JSON.parse(routeMeta);
        console.log('路由元数据:', meta);
      } catch (e) {}
    }
    console.log('自定义路由页面加载成功，路径:', '[router]');
  </script>
</body>
</html>

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>[title] - 欢迎页</title>
  <meta name="keywords" content="[seo_keywords]" />
  <meta name="description" content="[seo_description]" />
  <link rel="icon" href="[favicon]" />
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      min-height: 100vh;
      display: flex;
      align-items: center;
      justify-content: center;
      color: #fff;
    }
    .card {
      background: rgba(255,255,255,0.95);
      color: #333;
      border-radius: 16px;
      padding: 48px 40px;
      max-width: 520px;
      width: 90%;
      box-shadow: 0 20px 60px rgba(0,0,0,0.3);
      text-align: center;
    }
    .logo { width: 64px; height: 64px; border-radius: 12px; margin-bottom: 20px; }
    h1 { font-size: 28px; margin-bottom: 12px; }
    p { color: #666; line-height: 1.8; margin-bottom: 24px; }
    .meta { font-size: 13px; color: #999; margin-bottom: 32px; }
    .btn {
      display: inline-block;
      padding: 12px 32px;
      background: #667eea;
      color: #fff;
      text-decoration: none;
      border-radius: 8px;
      font-weight: 600;
      transition: transform 0.2s, box-shadow 0.2s;
    }
    .btn:hover { transform: translateY(-2px); box-shadow: 0 8px 20px rgba(102,126,234,0.4); }
    footer { margin-top: 32px; font-size: 12px; color: #bbb; }
  </style>
</head>
<body>
  <div class="card">
    <img class="logo" src="[logo]" alt="Logo" onerror="this.style.display='none'" />
    <h1>欢迎来到 [title]</h1>
    <p>这是通过<strong>自定义路由系统</strong>发布的独立单页。<br/>无需修改前端代码，后台配置即可上线。</p>
    <div class="meta">
      当前路由：<code>[router]</code><br/>
      站点地址：<a href="[base_url]">[base_url]</a><br/>
      建站时间：[site_time]
    </div>
    <a class="btn" href="[base_url]">进入商城首页</a>
    <footer>
      [RecordNumber] [PoliceRecordNumber]
    </footer>
  </div>

  <script>
    // 元数据占位符已被 Unicode 转码，可安全嵌入
    var routeMeta = "[元数据]";
    if (routeMeta && routeMeta !== "[元数据]") {
      try {
        var meta = JSON.parse(routeMeta);
        console.log('路由元数据:', meta);
      } catch (e) {}
    }
    console.log('自定义路由页面加载成功，路径:', '[router]');
  </script>
</body>
</html>

这个示例演示了什么？

占位符自动替换：[title]、[logo]、[base_url] 等来自系统配置
纯 CSS 单页：无外部依赖，复制即用
元数据读取：若在后台配置了 Metadata，可通过 [元数据] 在 JS 中使用
备案信息：[RecordNumber]、[PoliceRecordNumber] 自动填充

六、占位符（变量）完整列表

在 所有文本格式文件（HTML、JS、CSS、JSON、TXT、PHP 等）中，以下占位符会在访问时自动替换：

占位符	替换内容
`[title]` / `[Title]` / `[网站标题]`	网站标题
`[base_url]`	系统网址（优先 config.yaml，否则从请求构建）
`[RecordNumber]` / `[备案号]`	ICP 备案号
`[PoliceRecordNumber]` / `[公安备案号]`	公安备案号
`[logo]` / `[favicon]`	网站 Logo / 图标
`[seo_keywords]` / `[SEO关键词]`	SEO 关键词
`[seo_description]` / `[SEO描述]`	SEO 描述
`[site_time]` / `[建站时间]`	建站时间
`[pcurl]` / `[PC背景]`	PC 端背景图 URL
`[peurl]` / `[手机背景]`	手机端背景图 URL
`[router]` / `[ROUTER]`	当前访问的路由路径
`[元数据]` / `[metadata]`	当前路由 Metadata JSON（Unicode 转码，可安全嵌入 script）

注意：二进制文件（图片等）不会做占位符替换，避免损坏文件。

七、静态资源：为什么你的 CSS/JS 能自动加载？

假设你映射了 /landing → campaign/index.html，且文件结构为：

doc/
└── campaign/
    ├── index.html
    ├── assets/
    │   ├── app.js
    │   └── style.css
    └── static/
        └── banner.png

当 index.html 中引用：

<link rel="stylesheet" href="/assets/style.css" />
<script src="/assets/app.js"></script>

<link rel="stylesheet" href="/assets/style.css" />
<script src="/assets/app.js"></script>

系统会自动重写路径为：

/landing/assets/style.css
/landing/assets/app.js

并从 doc/campaign/assets/ 目录读取文件返回。

支持的静态目录前缀

/assets/、/static/、/js/、/css/、/images/、/img/、/fonts/、/libs/、/lib/ 等。

最佳实践

把静态资源放在 HTML 同级或子目录，不要散落到 doc 根目录
打包 UniApp/H5 项目时，直接解压到 doc/某路由名/ 下即可
路径写 /assets/xxx 即可，系统会自动加路由前缀

八、进阶用法

8.1 域名映射（独立品牌站）

场景：shop.example.com 是商城，brand.example.com 想展示品牌首页。

配置步骤：

DNS 将 brand.example.com A 记录解析到服务器 IP
后台添加映射：
- 映射方式：通过域名
- 域名：brand.example.com
- 文件路径：brand/home.html
用户访问 https://brand.example.com/ 时渲染该页面

/api/*、/static/* 等非根路径仍正常走后端，不影响接口。

8.2 绑定网站装修项目

场景：已在「网站装修」里拖拽好了 PC/ 手机页面，想挂到自定义 URL。

数据源类型选 「网站装修项目」
选择对应装修项目 ID
保存后，PC 端 SPA 的 DynamicRoute.vue 会读取装修 JSON 并渲染组件树

装修类型不走直接 HTML 返回，而是注入到前端 SPA 的 sessionStorage，由 Vue 组件渲染。

8.3 PHP 动态页面

在 网站设置 → 基础设置 配置 PHP 解释器路径
上传 doc/api/hello.php
映射 /api-demo → api/hello.php

系统会用 CLI 模式执行 PHP，并传递 HTTP 上下文（Method、Headers、Body 等）。

安全限制：exec、eval、shell_exec、system 等高危函数默认禁用。

8.4 强制登录 & 付费访问

设置	行为
强制登录 = 开启	未登录用户看到内置登录页
付费 + 价格	需先登录，再检查是否已购买该路由

若全局关闭了用户系统（user_code = false），强制登录和付费功能不会生效。

8.5 元数据 Metadata（动态表单）

Metadata 是一个 JSON 数组，描述表单组件（input、select、radio 等）。

后台操作：添加路由 → 元数据 → 「可视化配置」。

页面中使用：

<script>
  var fields = JSON.parse("[元数据]");
  // fields 是表单组件数组，可动态渲染表单
</script>

<script>
  var fields = JSON.parse("[元数据]");
  // fields 是表单组件数组，可动态渲染表单
</script>

系统还会将 Metadata 写入 Cookie（键名 route_meta_ + md5(域名 + 路由)），有效期 30 天，供跨页面读取。

8.6 设备类型分流

同一 URL，可为 PC 和手机配置不同映射：

/promo + 设备类型 pc → promo/pc.html
/promo + 设备类型 pe → promo/mobile.html

系统通过 User-Agent 自动识别设备；调试时可加 ?force_device=pc 或 ?force_device=pe 强制指定。

九、后台文件管理 API（开发者参考）

除可视化「浏览文件」外，还提供完整文件操作接口（均需管理员 Token）：

接口	说明
`GET /api/admin/route-mapping/doc-files?path=xxx`	列出 doc 目录
`POST /api/admin/route-mapping/upload`	上传文件
`POST /api/admin/route-mapping/create-file`	创建文件
`POST /api/admin/route-mapping/update-file`	更新文件内容
`GET /api/admin/route-mapping/read-file`	读取文件
`POST /api/admin/route-mapping/unzip-file`	解压 zip（适合整站 H5 包）

创建映射示例（curl）

TOKEN="你的管理员Token"

curl -X POST http://127.0.0.1:8080/api/admin/route-mapping/create \
  -H "Content-Type: application/json" \
  -H "admin-token: Bearer $TOKEN" \
  -d '{
    "route": "/welcome",
    "route_type": "route",
    "file_path": "pages/welcome.html",
    "source_type": "file",
    "title": "欢迎页",
    "status": 1,
    "device_type": "def",
    "force_login": 0,
    "is_paid": 0
  }'

TOKEN="你的管理员Token"

curl -X POST http://127.0.0.1:8080/api/admin/route-mapping/create \
  -H "Content-Type: application/json" \
  -H "admin-token: Bearer $TOKEN" \
  -d '{
    "route": "/welcome",
    "route_type": "route",
    "file_path": "pages/welcome.html",
    "source_type": "file",
    "title": "欢迎页",
    "status": 1,
    "device_type": "def",
    "force_login": 0,
    "is_paid": 0
  }'

十、导入 / 导出（批量迁移）

导出：勾选路由 → 点击「导出」→ 得到 JSON 配置文件。

导入规则：

按「路由路径 + 设备类型」判重
已存在则更新，不存在则新建
支持 JSON 文件或远程 URL 导入

适合从测试环境迁移到生产环境，或备份路由配置。

十一、请求处理优先级（排查问题时必看）

中间件 CustomRouteMiddleware 的执行顺序：

跳过 /api/*、管理后台路径、砍价分享页
静态资源路径 → 尝试从 doc 目录匹配
根路径 / → 优先尝试域名映射
按路由路径精确匹配（/promo 与 /promo/ 等价）
父路由静态资源 → 如 /landing/css/style.css 找 /landing 映射
未命中 → 交给 SPA 的 NoRoute 处理（404 或装修兜底）

访问控制优先级

全局强制登录中间件
路由级强制登录
路由级付费访问

十二、常见问题 FAQ

Q1：访问自定义路由返回 404？

检查清单：

路由映射状态是否为启用
文件路径是否正确（相对于 doc，不含 doc/ 前缀）
doc 目录下文件是否真实存在
设备类型是否匹配（PC 页设置了 pe -only 时，电脑访问会 404）
点击「刷新缓存」后重试

Q2：改了 HTML 但页面没变化？

文件内容不走 Redis 缓存，改完应即时生效
若仍不变，检查浏览器缓存（Ctrl+F5 / Cmd+Shift+R）
若改了映射配置本身，需刷新路由缓存

Q3：CSS/JS 404？

确认静态资源在 HTML 同级目录的 assets/ 或 static/ 下
HTML 里用 /assets/xxx 相对根路径写法，系统会自动加路由前缀
不要手动写完整路由前缀（除非你知道自己在做什么）

Q4：强制登录设置了但不生效？

检查 用户系统 是否开启（网站设置 → 用户系统）
用户系统关闭时，后台会显示「无效」标签

Q5：能和商城 Vue 路由冲突吗？

自定义路由优先级低于 /api/* 和后台路径
与 PC SPA 路由：若后端中间件已命中并返回内容，则不会进入 Vue；未命中则走 SPA 的 DynamicRoute.vue 兜底
建议：自定义路由使用 /promo/、/landing/ 等独立前缀，避免与商城内置路径冲突

Q6：doc 目录在哪？

与后端可执行程序同级，例如：

/opt/xqy/
├── server          # 后端程序
├── doc/            # ← 这里
│   └── pages/
│       └── welcome.html
└── static/

十三、推荐目录结构

 doc/
 ├── pages/           # 通用单页
 │   ├── about.html
 │   └── contact.html
 ├── campaign/        # 活动页（含静态资源子目录）
 │   ├── index.html
 │   └── assets/
 ├── docs/            # 文档
 │   └── api.html
 └── brand/           # 域名映射专用
     └── home.html

十四、安全注意事项

禁止路径遍历：文件路径不允许 ..，无法访问 doc 外文件
管理接口鉴权：所有配置/文件操作需管理员 Token
PHP 高危函数禁用：生产环境务必配置解释器并审查 PHP 代码
付费页：涉及资金，修改价格前确认已购用户权益策略
唯一路由：同一路由 + 设备类型不可重复，防止映射冲突

十五、总结

你想做什么	怎么做
快速上一个介绍页	doc 放 HTML → 后台添加路由映射 → 访问 URL
上线 H5 活动整包	解压到 doc/xxx/ → 映射 /xxx → 静态资源自动可用
独立域名首页	域名映射 + DNS 解析
可视化拖拽页	数据源选「装修项目」
会员专享内容	开启付费 + 设价格
动态接口页	上传 PHP + 配置解释器

自定义路由系统是小氢云商城最灵活的页面发布通道——运营同学可以独立上线页面，开发同学可以对接 PHP/H5 整包，无需每次改代码发版。

附录：数据库表字段速查

sky_route_mapping 主要字段：

字段	含义
route	路由路径或域名
route_type	`route` 或 `domain`
file_path	doc 下相对路径
source_type	`file` 或 `decoration`
decoration_id	装修项目 ID
force_login	是否强制登录
device_type	pc / pe / def
is_paid / price	付费设置
metadata	元数据 JSON
status	1 启用 / 0 禁用

本文由小氢云商城技术团队整理，基于系统源码与后台「路由映射管理」模块编写。如有疑问，欢迎在评论区留言。

Hello,Ethereal!