Files

T

Dai0814 22a177c569 docs: 部署手册拆分为多页，左侧形成三层目录

原单页塞了 13 个二级标题、右侧目录过长。拆成 7 页：
- 概览（含选型指引与环境对照表）
- 路径前缀必读（独立成页，最高频故障）
- 推荐环境：Docker + nginx
- 静态托管部署（nginx 子路径/根路径、Apache、Caddy、对象存储、pnpm）
- 内网与离线部署（4 种方案 + 对比表）
- 本地开发与预览（含新增页面步骤）
- 常见问题（部署/构建/运行三类 + 自检清单）

侧边栏分为三组：部署手册 / 部署方式 / 开发与排错

2026-10-26 17:12:18 +08:00

3.1 KiB

Raw Blame History

title, description, outline

title	description	outline
本地开发与预览	改文档时用 dev 模式，热更新实时看效果	deep

本地开发与预览

适用：修改文档内容、调整配置、本地看效果。

启动开发服务器

npm ci
npm run dev

访问 http://127.0.0.1:5173/docs/

::: warning 地址必须带 /docs/ base: '/docs/' 决定了 dev 服务器入口也在子路径下，直接访问 http://127.0.0.1:5173/ 会 404。 :::

改动 docs/ 下任意 .md 文件会热更新，无需重启。按 Ctrl+C 退出。

局域网访问

需要让同网段其他机器访问时，把监听地址改为 0.0.0.0：

npx vitepress dev . --host 0.0.0.0
# 然后访问 http://<本机IP>:5173/docs/

端口冲突

默认 5173，被占用时换端口：

npx vitepress dev . --port 5174

预览构建产物

dev 模式是源码实时编译，与最终产物有细微差异（如资源路径、代码分割）。发布前建议跑一次真实构建：

npm run build     # 产物在 .vitepress/dist
npm run preview   # http://127.0.0.1:4173/docs/

preview 只是本地起静态服务验证产物，不要用于生产。

目录结构

新增页面时按此结构放置：

iotlcm-docs/
├── docs/                  # 文档源（VitePress srcDir）
│   ├── index.md           # 站点首页
│   ├── manual/            # 使用手册
│   │   ├── web/           # Web 管理端
│   │   └── mini-program/  # 小程序端
│   ├── openapi/           # OpenAPI 合同
│   ├── deploy/            # 部署手册（本手册）
│   └── public/            # 静态资源，映射到站点根路径
│       └── images/        # 文档配图
└── .vitepress/
    ├── config.mts         # 站点配置（导航、侧边栏）
    └── theme/             # 主题定制

新增页面的步骤

在 docs/ 下对应目录新建 xxx.md，写 frontmatter：

---
title: 页面标题
description: 页面描述
outline: deep
---

# 页面标题

在 .vitepress/config.mts 的 sidebar 中注册，否则左侧目录不会显示：

sidebar: {
  '/deploy/': [
    {
      text: '部署手册',
      collapsed: false,
      items: [
        { text: '概览', link: '/deploy/' },
        { text: '新页面', link: '/deploy/xxx' },
      ]
    },
  ],
}

图片放 docs/public/images/，正文用绝对路径引用（public 目录映射到站点根）：
```
![说明](/images/xxx.png)
```

构建产物结构

.vitepress/dist/
├── index.html          # 首页
├── 404.html            # 404 页
├── favicon.png
├── assets/             # JS / CSS / 字体（带 hash）
├── images/             # 来自 docs/public/images
├── manual/             # 各章节
├── openapi/
└── deploy/

注意产物是平铺的，没有 docs/ 子目录——这正是部署时需要处理路径前缀的原因，见路径前缀必读。

3.1 KiB Raw Blame History Unescape Escape