Document Edge Updates (#20)

* ci: 更新 CI 相关的版本：node、useage scripts * feat: 移除无用依赖，更新 vitepress 版本和文档版本，便于修改文档引用 * chore: update redeme.md * feat: 更新 Vitepress 的配置项：添加本地搜索，更新导航栏内容等 * docs: 重新整理，移除框架与现有文档不同之处（可能还有 doge），现有内容整理精简合并，更加紧凑 * chore: vitepress config small change * feat: 文档目录小更新 --------- Co-authored-by: jhlz <[email protected]>
vbenjs · May 10, 2024 · 5436a67 · 5436a67
1 parent 8fe64ba
commit 5436a67
Show file tree

Hide file tree

Showing 15 changed files with 1,235 additions and 882 deletions.
diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml
@@ -14,19 +14,19 @@ jobs:
       # 下载仓库代码 / 校验
       - name: Checkout
         # actions/checkout@v3 是 github 官方的一个action，用于 clone 该仓库的源码到工作流中
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       # 安装 pnpm
       - name: Setup pnpm
-        uses: pnpm/action-setup@v2
-        with:
-          version: 6
+        uses: pnpm/action-setup@v3
 
       # 安装 node
       - name: Setup node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '16.x'
+          node-version: 20
           cache: 'pnpm'
 
       # 安装依赖项
@@ -38,7 +38,7 @@ jobs:
         run: pnpm docs:build
 
       - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./public

diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
@@ -1,19 +1,22 @@
+
+import { version } from '../../package.json';
+
 const nav = [
+  {
+    text: "在线预览",
+    link: "https://vben.mufei88.com/"
+  },
   {
     text: "指南",
     items: [
-      { text: "介绍", link: "/guide/introduction" },
-      { text: "项目结构", link: "/guide/directory" },
+      { text: "快速了解", link: "/guide/quick-understanding" },
       { text: "路由", link: "/guide/router" },
       { text: "配置", link: "/guide/config" },
     ],
   },
   {
     text: "组件",
-    items: [
-      { text: "介绍", link: "/packages/vbenComponent/introduction" },
-      { text: "Fetch扩展", link: "/packages/vbenComponent/fetch" },
-    ],
+    items: getPackagesIntro(),
   },
   {
     text: "集成",
@@ -25,18 +28,34 @@ const nav = [
   {
     text: "社区",
     items: [
+      {
+        text: "KOOK",
+        link: "https://kook.top/6ZPFKi",
+      },
       {
         text: "QQ频道",
         link: "https://pd.qq.com/s/ahgh62mni",
       },
       {
-        text: "QQ群1 4286109",
+        text: "源码仓库",
+        link: "https://github.com/vbenjs/vben3",
       },
-        {
-        text: "QQ群2 435706828",
+      {
+        text: "文档仓库",
+        link: "https://github.com/vbenjs/vben3-doc",
       },
     ],
   },
+  {
+    text: version,
+    items: [
+      {
+        text: "更新日志",
+        link: "https://github.com/vbenjs/vben3/blob/master/CHANGELOG.md",
+      }
+
+    ]
+  }
 ];
 
 const sidebar = [
@@ -45,11 +64,9 @@ const sidebar = [
     items: [
       { text: "介绍", link: "/guide/introduction" },
       { text: "快速了解", link: "/guide/quick-understanding" },
-      { text: "项目结构", link: "/guide/directory" },
       { text: "构建 & 部署", link: "/guide/deploy" },
       { text: "配置", link: "/guide/config" },
       { text: "路由", link: "/guide/router" },
-      { text: "更新日志", link: "/guide/uplog" },
     ],
   },
   {
@@ -61,7 +78,7 @@ const sidebar = [
     text: "其它",
     items: [
       { text: "常见问题", link: "/other/faq" },
-      { text: "加入我们", link: "/other/follow" },
+      { text: "添砖加瓦", link: "/other/follow" },
     ],
   },
 ];
@@ -91,19 +108,30 @@ export default {
   title: "Vben Admin 3",
   description: "Vben Admin 3 Doc",
   base: "/vben3-doc/",
-  repo: "vbenjs/vben3-doc",
+  head: [['link', {rel: 'icon', href: '/vben3-doc/vben.png'}]],
   ignoreDeadLinks: true,
+
+  markdown: {
+    lineNumbers: true
+  },
+
   lastUpdated: true,
   outDir: "../public",
   themeConfig: {
     logo: "/vben.svg",
     darkModeSwitchLabel: "Dark",
+    outline: {
+      label: "本文目录"
+    },
+    search: {
+      provider: 'local'
+    },
     nav,
     sidebar,
     socialLinks: [{ icon: "github", link: "https://github.com/vbenjs/vben3" }],
     editLink: {
       pattern: "https://github.com/vbenjs/vben3-doc/edit/master/docs/:path",
-      text: "编辑此页",
+      text: "帮助完善本页！",
     },
     footer: {
       copyright: `MIT License Copyright ©️ 2024-present Vben`

diff --git a/docs/guide/config.md b/docs/guide/config.md
@@ -1,87 +1,23 @@
 # 配置说明
 
-## 关于环境配置
+## 环境变量
 
-对于系统的使用者来说，一般首先修改配置文件，进行定制化修改以符合自己业务/学习使用。环境配置推荐查看 Vite 官网的 [Env Variables and Modes](https://vitejs.dev/guide/env-and-mode.html) 说明，对于理解很有帮助。
+Vite 从 dotenv 文件读取环境变量，例如 `.env`、`.env.[mode]` 等文件。`.env.[mode]` 这种形式配置相比于 `.env` 具有 **更高的优先级**，即 `.env.xxx` 会覆盖 `.env` 的 **相同配置**。
 
-:::tip
-只有以 VITE_ 开头的变量会被嵌入到客户端侧的包中， 访问方法：
-```
-console.log(import.meta.env.VITE_PROT);
-```
-以 VITE_GLOB_* 开头的的变量，在编译的时候，会被加入_app.config.js配置文件当中.
-:::
+- `.env`：所有情况下都会被加载，所以可以放置通用配置，例如开发、测试、生产等等环境所需的公共变量
+- `.env.development`：开发环境配置，dev 模式启动读取
+- `.env.production`：生产环境配置，build 模式启动读取
 
-### 通用配置 .env
-
-该配置文件位于 `apps/admin/` 路径下，`.env` 无论在什么环境下都会被加载，因此公共的配置可以放在这里面。
-
-```bash apps/admin/.env
-# 网站标题
-VITE_GLOB_APP_TITLE = Vben Admin
-# 简称，用于配置文件名字 不要出现空格、数字开头等特殊字符
-VITE_GLOB_APP_SHORT_NAME = vben_admin
-```
-
-### 开发环境配置 .env.development
+:::tip
 
-项目以开发环境启动的时候加载该配置文件，该配置文件位于 `apps/admin/` 路径下。
+- 只有前缀 `VITE_` 的变量才会暴露给 Vite 处理的代码，并且 Vite 在解析时会把变量全部 **读取为字符串**，所以在使用时需要自己转为需要的类型。
 
-```
-# 是否开启mock数据，关闭时需要自行对接后台接口
-VITE_USE_MOCK=true
-# 资源公共路径,需要以 /开头和结尾
-VITE_PUBLIC_PATH=/
-# 是否删除Console.log
-VITE_DROP_CONSOLE=false
-# 本地开发代理，可以解决跨域及多地址代理
-# 如果接口地址匹配到，则会转发到http://localhost:3000，防止本地出现跨域问题
-# 可以有多个，注意多个不能换行，否则代理将会失效
-VITE_PROXY=[["/api","http://localhost:3000"],["api1","http://localhost:3001"],["/upload","http://localhost:3001/upload"]]
-# 接口地址
-# 如果没有跨域问题，直接在这里配置即可
-VITE_GLOB_API_URL=/api
-# 文件上传接口  可选
-VITE_GLOB_UPLOAD_URL=/upload
-# 接口地址前缀，有些系统所有接口地址都有前缀，可以在这里统一加，方便切换
-VITE_GLOB_API_URL_PREFIX=
-```
-:::warning 注意
+- 默认情况下，vite 在 `dev` 命令下使用 development 模式运行，`build` 命令在 production 模式下运行。
 
-这里配置的 `VITE_PROXY` 以及 `VITE_GLOB_API_URL`， /api 需要是唯一的，不要和接口已有的名字冲突。
+- 更多使用方法参考 [Vite#Env Variables and Modes](https://vitejs.dev/guide/env-and-mode.html)。
 
-如果你的接口是 http://localhost:3000/api 之类的，请考虑将 VITE_GLOB_API_URL=/xxxx 换成别的名字。
 :::
 
-### 生产环境配置 .env.production
-
-项目以生产环境启动的时候加载该配置文件，该配置文件位于 `apps/admin/` 路径下。
-
-```
-# 是否开启mock
-VITE_USE_MOCK=true
-# 接口地址 可以由nginx做转发或者直接写实际地址
-VITE_GLOB_API_URL=/api
-# 文件上传地址 可以由nginx做转发或者直接写实际地址
-VITE_GLOB_UPLOAD_URL=/upload
-# 接口地址前缀，有些系统所有接口地址都有前缀，可以在这里统一加，方便切换
-VITE_GLOB_API_URL_PREFIX=
-# 是否删除Console.log
-VITE_DROP_CONSOLE=true
-# 资源公共路径,需要以 / 开头和结尾
-VITE_PUBLIC_PATH=/
-# 打包是否输出gz｜br文件
-# 可选: gzip | brotli | none
-# 也可以有多个, 例如 ‘gzip’|'brotli',这样会同时生成 .gz和.br文件
-VITE_BUILD_COMPRESS = 'gzip'
-# 打包是否压缩图片
-VITE_USE_IMAGEMIN = false
-# 打包是否开启pwa功能
-VITE_USE_PWA = false
-# 是否兼容旧版浏览器。开启后打包时间会慢一倍左右。会多打出旧浏览器兼容包,且会根据浏览器兼容性自动使用相应的版本
-VITE_LEGACY = false
-```
-
 ## 关于 _app.config.js
 
 :::info 作用
@@ -132,7 +68,9 @@ export const useGlobSetting = (): SettingWrap => {
 };
 ```
 
-## 关于 pnpm-workspace.yaml
+## 项目仓库管理方式
+
+`pnpm-workspace.yaml` 是 monorepo 方式管理的标志。
 
 ```yaml pnpm-workspace.yaml
 packages:
@@ -144,36 +82,35 @@ packages:
 
 该文件表示告诉 pnpm 该项目/存储库是一个 monorepo 项目，并且该项目有如上四个 workspace，分别位于 `packages`、`apps`、`configs`、`scripts`，这些文件夹内都是独立的 app 或者 pkg。想要了解有关 workspace 的更多内容，请👉[这里](https://www.pnpm.cn/workspaces)。
 
-举个例子，我们在项目中一般需要 **使用/封装** 工具类，并把该类放在统一的包下面，利于管理。以本项目为例，`packages/utils` 下面有多个工具类，那么如何引入到 app 下面呢？
+使用这种方式管理的好处就是可以重复的使用以前造好的轮子，并且很方便的使用，而不用在不同项目间来回的拷贝。对于自己公司内部的前端业务个人认为是最适合不过的，所有前端项目都可以在一个仓库下管理，统一风格和工具，便于维护。
 
-首先想到的就是安装、导入、调用，我们来 try 一下！
+如果想要切换某些工具，那么就使用新玩具封装成趁手的利器，在需要使用的业务模块中引入即可，也不干扰其它工具。
 
-```bash
-# 进入到需要使用工具类的 app 模块
-cd apps/admin
-# 添加 pkg 下的工具类
-pnpm add @vben/utils
-```
+如果是外包也可以使用，开发完交付后业务模块的代码交给客户，就可以删掉接入其它新项目。
 
-然后就可以在 app 中导入并正常使用 `packages/utils` 中的工具啦！欸，欸，欸，不对呀，那我要是自己在 packages 中新建其它的库呢？
+### 🌰 小栗子
 
-:::tip 小栗子
-好，假设我们现在需要自定义一个小小的加/解密的库，并把该库放到 packages 下，然后在 app 的模块中引入，这该如何做呢？
-:::
+以本项目为例，`packages/utils` 下面有很多工具类，都是使用不同的库进行封装的，在需要使用的地方导入后调用就完事儿啦。
+
+那么问题来了，如果要是自己在 packages 中新建其它的组件呢？
+
+假设现在准备将 Vue 的状态管理工具从 Vuex 切换到 Pinia，为了使用更加的方便，我们决定自己封装一下放进项目中，同时呢，也不删除以前已经封装好的 Vuex。然后将业务模块中使用的 Vuex 替换成 Pinia。这该如何做呢？
 
-1. 在 `packages` 目录下初始化库；
+第一时间想到的就是基于 Pinia 封装，然后在使用的模块中安装、导入、调用，我们来 try 一下！这和把大象装进冰箱的步骤一样：
+
+1. 在 `packages` 目录下初始化一个状态管理模块；
 
     ```bash
     cd packages
-    mkdir secret && cd secret
+    mkdir pinia-store && cd pinia-store
     pnpm init
     ```
 
-2. 修改 `package.json`，然后在创建入口文件添加相应的方法（如果需要添加 ts 的配置等相关内容，创建并填充 `tsconfig.json`，此处示例不需要）；
+2. 根据自己需要完善 `package.json`，然后在创建入口文件添加相应的方法（如果需要添加 ts 的配置等相关内容，创建并填充 `tsconfig.json`，此处示例不需要）；
 
     ```bash secret/package.json
     {
-      "name": "@vben/secret",
+      "name": "@vben/pinia-store",
       "private": true,
       "version": "0.0.1",
       "author": "vben",
@@ -182,42 +119,43 @@ pnpm add @vben/utils
     }
     ```
 
-3. 在需要使用的模块中安装依赖，然后就可以调用啦；
+3. 在需要使用的模块中安装依赖，然后就可以愉快的调用啦；
 
     ```bash
+    # 进入对应的业务模块的路径
     cd app/admin
     # 添加依赖
-    pnpm add @vben/secret
+    pnpm add @vben/pinia-store
     ```
 
     :::danger 添加依赖时可能会出现以下错误：
-
 
     ```bash
-    $ pnpm add @vben/secret
+    $ pnpm add @vben/pinia-store
        ERR_PNPM_FETCH_404  GET https://registry.npmmirror.com/@vben%2Fexample: Not Found - 404
 
       This error happened while installing a direct dependency of YourLocalPath
 
-      @vben/secret is not in the npm registry, or you have no permission to fetch it.
+      @vben/pinia-store is not in the npm registry, or you have no permission to fetch it.
 
       No authorization header was set for the request.
       ../..                                    | Progress: resolved 110, reused 110, downloaded 0, added 0
     ```
 
-    如果失败，可以 **手动** 在应用该库模块的 `package.json` 文件中添加依赖，然后使用 `pnpm i` 即可完成安装，之后就可以导入该工具方法并使用啦。
+    如果失败，可以 **手动** 在需要使用该工具的业务模块的 `package.json` 文件中添加依赖，然后再使用 `pnpm i` 即可完成安装并导入该工具进行使用。
 
     ```json
     {
       "devDependencies": {
         ...
-        "@vben/secret": "workspace:*"
+        "@vben/pinia-store": "workspace:*"
       }
     }
     ```
+
     :::
 
-### 在根目录中使用命令行直接对 apps 中的模块添加依赖
+### 在根目录中使用命令行直接对 apps 中的核心业务模块添加依赖
 
 1. 在 **根目录** 的 `package.json` 文件中添加以下内容：
 
@@ -237,4 +175,3 @@ pnpm add @vben/utils
 ```bash
 pnpm admin add [package]
 ```
-