---
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
   ![说明](/images/xxx.png)
   ```

## 构建产物结构

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

注意产物是**平铺**的，没有 `docs/` 子目录——这正是部署时需要处理路径前缀的原因，见 [路径前缀必读](./path-prefix)。