vitepress-theme-mist

Appearance

2025-08-16
390
1.7m

一、开发指南 ​

主题的主入口文件为packages/mist/index.ts，这里的index.ts将会在vitepress站点的.vitepress/theme/index.ts中导入和调用。

二、Workspace 机制详解 ​

1. 项目配置分析 ​

1.1 pnpm-workspace.yaml ​

yaml
# pnpm-workspace.yaml
packages:
  - docs
  - packages/*

这个配置定义了 Workspace 的范围，包含了 packages 目录下的所有子目录。

1.2 packages/mist/package.json ​

json
{
  "private": true,
  "name": "@docs-site/vitepress-theme-mist",
  "version": "1.0.0",
  "description": "",
  "type": "module",
  "main": "./index.ts",
  "module": "./index.ts"
}

关键点：

  • "name": "@docs-site/vitepress-theme-mist" 定义了这个包的唯一标识符
  • "module": "./index.ts" 指定了 ES 模块的入口文件
  • "private": true 表示这个包不会被发布到 npm

1.3 docs/package.json ​

json
{
  "devDependencies": {
    "@docs-site/vitepress-theme-mist": "workspace:*"
  }
}
  • "@docs-site/vitepress-theme-mist": "workspace:*" 声明了一个 Workspace 依赖
  • workspace:* 告诉 pnpm 这个依赖应该从 Workspace 中查找，而不是从 npm 下载

添加对 @docs-site/vitepress-theme-mist 的依赖，可以使用以下命令：

bash
pnpm add -D @docs-site/vitepress-theme-mist@workspace:* --filter @docs-site/vitepress-theme-mist-docs

或者也可以手动添加，然后执行pnpm install。

2. 导入解析过程 ​

当我们执行 import Mist from "@docs-site/vitepress-theme-mist" 时，完整的解析过程如下：

（1）模块解析（Node.js）

  • Node.js 模块解析器在当前目录及父目录中查找 node_modules
  • 在 docs/node_modules/ 中找到 @docs-site/vitepress-theme-mist
  • 发现符号链接：docs/node_modules/@docs-site/vitepress-theme-mist -> ../../packages/mist

（2）包解析（package.json）

  • 读取 packages/mist/package.json 文件
  • 根据 module 字段知道应该加载 ./index.ts 文件

（3）文件加载

  • 加载 packages/mist/index.ts 文件