docs(@vben/docs): align guide docs with current tooling

2026-05-07 10:41:26 +08:00 · 2026-03-14 21:33:55 +08:00
parent 278032c94b
commit 6c274b75b8
11 changed files with 403 additions and 271 deletions
--- a/docs/src/guide/essentials/development.md
+++ b/docs/src/guide/essentials/development.md
@@ -24,18 +24,18 @@

 ### 工具配置

-如果您使用的 IDE 是[vscode](https://code.visualstudio.com/)(推荐)的话，可以安装以下工具来提高开发效率及代码格式化:
+如果您使用的 IDE 是 [vscode](https://code.visualstudio.com/)（推荐）的话，可以安装以下工具来提高开发效率及代码格式化:

 - [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) - Vue 官方插件（必备）。
 - [Tailwind CSS](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) - Tailwindcss 提示插件。
- [CSS Variable Autocomplete](https://marketplace.visualstudio.com/items?itemName=bradlc.vunguyentuan.vscode-css-variables) - Css 变量提示插件。
- [Iconify IntelliSense](https://marketplace.visualstudio.com/items?itemName=antfu.iconify) - Iconify 图标插件
- [i18n Ally](https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally) - i18n 插件
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - 脚本代码检查
- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - 代码格式化
- [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - css 格式化
- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - 单词语法检查
- [DotENV](https://marketplace.visualstudio.com/items?itemName=mikestead.dotenv) - .env 文件 高亮
+- [CSS Variable Autocomplete](https://marketplace.visualstudio.com/items?itemName=vunguyentuan.vscode-css-variables) - CSS 变量提示插件。
+- [Iconify IntelliSense](https://marketplace.visualstudio.com/items?itemName=antfu.iconify) - Iconify 图标插件。
+- [i18n Ally](https://marketplace.visualstudio.com/items?itemName=Lokalise.i18n-ally) - i18n 插件。
+- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - 脚本代码检查。
+- [Oxc](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode) - Oxlint / Oxfmt 集成。
+- [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - CSS 格式检查。
+- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - 单词语法检查。
+- [DotENV](https://marketplace.visualstudio.com/items?itemName=mikestead.dotenv) - `.env` 文件高亮。

 ## Npm Scripts

@@ -51,15 +51,17 @@ npm 脚本是项目常见的配置，用于执行一些常见的任务，比如
    // 构建项目并分析
    "build:analyze": "turbo build:analyze",
    // 构建本地 docker 镜像
-    "build:docker": "./build-local-docker-image.sh",
+    "build:docker": "./scripts/deploy/build-local-docker-image.sh",
    // 单独构建 web-antd 应用
    "build:antd": "pnpm run build --filter=@vben/web-antd",
+    // 单独构建 web-antdv-next 应用
+    "build:antdv-next": "pnpm run build --filter=@vben/web-antdv-next",
    // 单独构建文档
    "build:docs": "pnpm run build --filter=@vben/docs",
    // 单独构建 web-ele 应用
    "build:ele": "pnpm run build --filter=@vben/web-ele",
    // 单独构建 web-naive 应用
-    "build:naive": "pnpm run build --filter=@vben/naive",
+    "build:naive": "pnpm run build --filter=@vben/web-naive",
    // 单独构建 web-tdesign 应用
    "build:tdesign": "pnpm run build --filter=@vben/web-tdesign",
    // 单独构建 playground 应用
@@ -71,48 +73,54 @@ npm 脚本是项目常见的配置，用于执行一些常见的任务，比如
    // 检查循环引用
    "check:circular": "vsh check-circular",
    // 检查拼写
-    "check:cspell": "cspell lint **/*.ts **/README.md .changeset/*.md --no-progress"
+    "check:cspell": "cspell lint **/*.ts **/README.md .changeset/*.md --no-progress",
    // 检查依赖
    "check:dep": "vsh check-dep",
    // 检查类型
    "check:type": "turbo run typecheck",
-    // 清理项目（删除node_modules、dist、.turbo）等目录
+    // 清理项目（删除 node_modules、dist、.turbo）等目录
    "clean": "node ./scripts/clean.mjs",
    // 提交代码
    "commit": "czg",
-    // 启动项目（默认会运行整个仓库所有包的dev脚本）
+    // 启动项目（默认会运行整个仓库所有包的 dev 脚本）
    "dev": "turbo-run dev",
-    // 启动web-antd应用
+    // 启动 web-antd 应用
    "dev:antd": "pnpm -F @vben/web-antd run dev",
+    // 启动 web-antdv-next 应用
+    "dev:antdv-next": "pnpm -F @vben/web-antdv-next run dev",
    // 启动文档
    "dev:docs": "pnpm -F @vben/docs run dev",
-    // 启动web-ele应用
+    // 启动 web-ele 应用
    "dev:ele": "pnpm -F @vben/web-ele run dev",
-    // 启动web-naive应用
+    // 启动 web-naive 应用
    "dev:naive": "pnpm -F @vben/web-naive run dev",
+    // 启动 web-tdesign 应用
+    "dev:tdesign": "pnpm -F @vben/web-tdesign run dev",
    // 启动演示应用
    "dev:play": "pnpm -F @vben/playground run dev",
    // 格式化代码
    "format": "vsh lint --format",
    // lint 代码
    "lint": "vsh lint",
-    // 依赖安装完成之后，执行所有包的stub脚本
+    // 依赖安装完成之后，执行所有包的 stub 脚本
    "postinstall": "pnpm -r run stub --if-present",
-    // 只允许使用pnpm
+    // 只允许使用 pnpm
    "preinstall": "npx only-allow pnpm",
-    // lefthook的安装
-    "prepare": "is-ci || lefthook install",
+    // 安装 lefthook
+    "prepare": "pnpm exec lefthook install",
    // 预览应用
    "preview": "turbo-run preview",
    // 包规范检查
    "publint": "vsh publint",
-    // 删除所有的node_modules、yarn.lock、package.lock.json，重新安装依赖
+    // 删除所有的 node_modules、yarn.lock、package-lock.json，重新安装依赖
    "reinstall": "pnpm clean --del-lock && pnpm install",
+    // 运行 e2e 测试
+    "test:e2e": "turbo run test:e2e",
    // 运行 vitest 单元测试
    "test:unit": "vitest run --dom",
    // 更新项目依赖
-    "update:deps": " pnpm update --latest --recursive",
-    // changeset生成提交集
+    "update:deps": "npx taze -r -w",
+    // changeset 生成提交集
    "version": "pnpm exec changeset version && pnpm install --no-frozen-lockfile"
  }
 }
@@ -134,6 +142,12 @@ pnpm dev
 pnpm dev:antd
 ```

+运行 `web-antdv-next` 应用：
+
+```bash
+pnpm dev:antdv-next
+```
+
 运行 `web-naive` 应用：

 ```bash
@@ -146,6 +160,12 @@ pnpm dev:naive
 pnpm dev:ele
 ```

+运行 `web-tdesign` 应用：
+
+```bash
+pnpm dev:tdesign
+```
+
 运行 `docs` 应用：

 ```bash
@@ -154,11 +174,11 @@ pnpm dev:docs

 ## 区分构建环境

-在实际的业务开发中，通常会在构建时区分多种环境，如测试环境`test`、生产环境`build`等。
+在实际的业务开发中，通常会在构建时区分多种环境，如测试环境 `test`、生产环境 `build` 等。

 此时可以修改三个文件，在其中增加对应的脚本配置来达到区分生产环境的效果。

-以`@vben/web-antd`添加测试环境`test`为例：
+以 `@vben/web-antd` 添加测试环境 `test` 为例：

 - `apps\web-antd\package.json`

@@ -173,7 +193,7 @@ pnpm dev:docs
 },
 ```

-增加命令`"build:test"`, 并将原`"build"`改为`"build:prod"`以避免同时构建两个环境的包。
+增加命令 `"build:test"`，并将原 `"build"` 改为 `"build:prod"` 以避免同时构建两个环境的包。

 - `package.json`

@@ -188,7 +208,7 @@ pnpm dev:docs
 }
 ```

-在根目录`package.json`中加入构建测试环境的命令
+在根目录 `package.json` 中加入构建测试环境的命令。

 - `turbo.json`

@@ -217,17 +237,17 @@ pnpm dev:docs
    ······
 ```

-在`turbo.json`中加入相关依赖的命令
+在 `turbo.json` 中加入相关依赖的命令。

 ## 公共静态资源

-项目中需要使用到的公共静态资源，如：图片、静态HTML等，需要在开发中通过 `src="/xxx.png"` 直接引入的。
+项目中需要使用到的公共静态资源，如：图片、静态 HTML 等，需要在开发中通过 `src="/xxx.png"` 直接引入的。

 需要将资源放在对应项目的 `public/static` 目录下。引入的路径为：`src="/static/xxx.png"`。

 ## DevTools

-项目内置了 [Vue DevTools](https://github.com/vuejs/devtools-next) 插件，可以在开发过程中使用。默认关闭，可在`.env.development` 内开启，并重新运行项目即可：
+项目内置了 [Vue DevTools](https://github.com/vuejs/devtools-next) 插件，可以在开发过程中使用。默认关闭，可在 `.env.development` 内开启，并重新运行项目即可：

 ```bash
 VITE_DEVTOOLS=true
@@ -251,7 +271,7 @@ pnpm dev:docs

 ```bash
 # 请在项目根目录下执行
-# 该命令会删除整个仓库所有的 node_modules、yarn.lock、package.lock.json后
+# 该命令会删除整个仓库所有的 node_modules、yarn.lock、package-lock.json 后
 # 再进行依赖重新安装（安装速度会明显变慢）。
 pnpm reinstall
 ```