Dai0814
22a177c569
原单页塞了 13 个二级标题、右侧目录过长。拆成 7 页： - 概览（含选型指引与环境对照表） - 路径前缀必读（独立成页，最高频故障） - 推荐环境：Docker + nginx - 静态托管部署（nginx 子路径/根路径、Apache、Caddy、对象存储、pnpm） - 内网与离线部署（4 种方案 + 对比表） - 本地开发与预览（含新增页面步骤） - 常见问题（部署/构建/运行三类 + 自检清单） 侧边栏分为三组：部署手册 / 部署方式 / 开发与排错
126 lines
3.1 KiB
Markdown
126 lines
3.1 KiB
Markdown
---
|
||
title: 本地开发与预览
|
||
description: 改文档时用 dev 模式，热更新实时看效果
|
||
outline: deep
|
||
---
|
||
|
||
# 本地开发与预览
|
||
|
||
适用：修改文档内容、调整配置、本地看效果。
|
||
|
||
## 启动开发服务器
|
||
|
||
```bash
|
||
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`：
|
||
|
||
```bash
|
||
npx vitepress dev . --host 0.0.0.0
|
||
# 然后访问 http://<本机IP>:5173/docs/
|
||
```
|
||
|
||
## 端口冲突
|
||
|
||
默认 5173，被占用时换端口：
|
||
|
||
```bash
|
||
npx vitepress dev . --port 5174
|
||
```
|
||
|
||
## 预览构建产物
|
||
|
||
`dev` 模式是源码实时编译，与最终产物有细微差异（如资源路径、代码分割）。发布前建议跑一次真实构建：
|
||
|
||
```bash
|
||
npm run build # 产物在 .vitepress/dist
|
||
npm run preview # http://127.0.0.1:4173/docs/
|
||
```
|
||
|
||
`preview` 只是本地起静态服务验证产物，**不要用于生产**。
|
||
|
||
## 目录结构
|
||
|
||
新增页面时按此结构放置：
|
||
|
||
```text
|
||
iotlcm-docs/
|
||
├── docs/ # 文档源（VitePress srcDir）
|
||
│ ├── index.md # 站点首页
|
||
│ ├── manual/ # 使用手册
|
||
│ │ ├── web/ # Web 管理端
|
||
│ │ └── mini-program/ # 小程序端
|
||
│ ├── openapi/ # OpenAPI 合同
|
||
│ ├── deploy/ # 部署手册（本手册）
|
||
│ └── public/ # 静态资源，映射到站点根路径
|
||
│ └── images/ # 文档配图
|
||
└── .vitepress/
|
||
├── config.mts # 站点配置（导航、侧边栏）
|
||
└── theme/ # 主题定制
|
||
```
|
||
|
||
## 新增页面的步骤
|
||
|
||
1. 在 `docs/` 下对应目录新建 `xxx.md`，写 frontmatter：
|
||
|
||
```markdown
|
||
---
|
||
title: 页面标题
|
||
description: 页面描述
|
||
outline: deep
|
||
---
|
||
|
||
# 页面标题
|
||
```
|
||
|
||
2. 在 `.vitepress/config.mts` 的 `sidebar` 中注册，否则左侧目录不会显示：
|
||
|
||
```ts
|
||
sidebar: {
|
||
'/deploy/': [
|
||
{
|
||
text: '部署手册',
|
||
collapsed: false,
|
||
items: [
|
||
{ text: '概览', link: '/deploy/' },
|
||
{ text: '新页面', link: '/deploy/xxx' },
|
||
]
|
||
},
|
||
],
|
||
}
|
||
```
|
||
|
||
3. 图片放 `docs/public/images/`，正文用绝对路径引用（public 目录映射到站点根）：
|
||
|
||
```markdown
|
||
|
||
```
|
||
|
||
## 构建产物结构
|
||
|
||
```text
|
||
.vitepress/dist/
|
||
├── index.html # 首页
|
||
├── 404.html # 404 页
|
||
├── favicon.png
|
||
├── assets/ # JS / CSS / 字体（带 hash）
|
||
├── images/ # 来自 docs/public/images
|
||
├── manual/ # 各章节
|
||
├── openapi/
|
||
└── deploy/
|
||
```
|
||
|
||
注意产物是**平铺**的，没有 `docs/` 子目录——这正是部署时需要处理路径前缀的原因，见 [路径前缀必读](./path-prefix)。
|