docs: update (#4)

* chore: update deps

* chore: update siteTitle, add local search

* docs: update

.vitepress/config.ts

@@ -77,7 +77,7 @@ export default defineConfig({
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     logo: '/logo.svg',
-    siteTitle: 'Vitesse',
+    siteTitle: 'Vitesse Uni App',
     nav: [
       { text: '快速开始', link: '/getting-started/installation', activeMatch: '/getting-started' },
       { text: '指南', link: '/guide/concepts/auto-imports', activeMatch: '/guide' },
@@ -179,5 +179,29 @@ export default defineConfig({
       pattern: 'https://github.com/uni-helper/vitesse-uni-app-docs/edit/main/:path',
       text: '在 GitHub 上编辑本页',
     },
+
+    search: {
+      provider: 'local',
+      options: {
+        locales: {
+          zh: {
+            translations: {
+              button: {
+                buttonText: '搜索文档',
+                buttonAriaLabel: '搜索文档'
+              },
+              modal: {
+                noResultsText: '无法找到相关结果',
+                resetButtonTitle: '清除查询条件',
+                footer: {
+                  selectText: '选择',
+                  navigateText: '切换'
+                }
+              }
+            }
+          }
+        }
+      }
+    },
   },
 })

eslint.config.js

@@ -0,0 +1,3 @@
+import antfu from '@antfu/eslint-config'
+
+export default antfu()

getting-started/data-fetching.md

@@ -1,37 +1,29 @@
 # 数据获取
 
-你可以使用任何你喜欢的第三方请求库来获取数据。默认情况下，直接使用 `uni.request` 即可。
+你可以使用你喜欢的第三方请求库来获取数据。一般情况下，直接使用 `uni-app` 内置方法即可。
 
-## `uni.request`
+## `uni-app` 内置方法
 
-这是 uni 内置的网络请求方法。
+`uni-app` 提供了 [uni.request](https://uniapp.dcloud.net.cn/api/request/request.html)、[uni.uploadFile](https://uniapp.dcloud.net.cn/api/request/network-file.html#uploadfile)、[uni.downloadFile](https://uniapp.dcloud.net.cn/api/request/network-file.html#downloadfile)、[WebSocket](https://uniapp.dcloud.net.cn/api/request/websocket.html) 等支持。一般情况下，你可以直接使用它们。
 
-```ts
-uni.request({
-  url: 'https://www.example.com/request',
-  data: {
-    text: 'uni.request'
-  },
-  header: {
-    'custom-header': 'hello' // 自定义请求头信息
-  },
-  success: (res) => {
-    console.log(res.data)
-  }
-})
-```
+## axios
 
+如果你更喜欢 [axios](https://github.com/axios/axios) 及其相关生态，你可以使用 [@uni-helper/axios-adapter](https://github.com/uni-helper/axios-adapter)。它是专为 `uni-app` 打造的 `axios` 适配器，支持全平台！
+
+```ts
+import axios from 'axios'
+import { createUniAppAxiosAdapter } from '@uni-helper/axios-adapter'
 
-::: tip
-你可以在[这里](https://uniapp.dcloud.net.cn/api/request/request.html#)阅读文档。
-:::
+axios.defaults.adapter = createUniAppAxiosAdapter()
+const { data, isFinished } = useAxios('/user?ID=12345')
+```
 
-## uni-network
+## @uni-helper/uni-network
 
-这是一个为 `uni-app` 打造的 [基于 Promise](https://javascript.info/promise-basics) 的 HTTP 客户端，灵感和代码绝大部分源于 `[email protected]`。
+[@uni-helper/uni-network](https://github.com/uni-helper/uni-network) 是一个为 `uni-app` 打造的基于 `Promise` 的 HTTP 客户端，灵感和代码绝大部分源于 `[email protected]`。`@uni-helper/uni-network` 在底层做了 `uni-app` 适配，体积更小，TypeScript 类型更贴近 `uni-app`。
 
 ```ts
-import un from '@uni-helper/uni-network'
+import { un } from '@uni-helper/uni-network'
 
 try {
   const response = await un.get('/user?ID=12345')
@@ -41,23 +33,3 @@ catch (error) {
   console.error(error)
 }
 ```
-
-::: tip
-你可以在[这里](https://github.com/uni-helper/uni-network)阅读文档。
-:::
-
-## axios
-
-如果你更喜欢 axios 或者为了享受其相关生态，你还可以使用由 Uni Helper 团队开发的 [axios-adapter](https://github.com/uni-helper/axios-adapter)，它是专为 uni-app 打造的 axios 适配器，支持全平台！
-
-```ts
-import axios from 'axios'
-import { createUniAppAxiosAdapter } from '@uni-helper/axios-adapter'
-
-axios.defaults.adapter = createUniAppAxiosAdapter()
-const { data, isFinished } = useAxios('/user?ID=12345')
-```
-
-::: tip
-你可以阅读 [axios 的文档](https://axios-http.com/docs/intro) 和 [axios-adapter 的文档](https://github.com/uni-helper/axios-adapter)了解更多信息。
-:::

getting-started/deployment.md

@@ -14,30 +14,166 @@ pnpm build:h5
 
 ## 小程序
 
-使用下面的命令来打包：
+以微信小程序为例，使用下面的命令来打包：
 
 ```bash
-# 微信小程序
 pnpm build:mp-weixin
 ```
 
 产物位于 `dist/build/mp-weixin`, 使用微信开发者工具上传即可。
 
 ::: tip
-如若想自动上传到微信小程序，可查看[这里](https://juejin.cn/post/7272316909051346959)
+如果想自动上传到微信小程序，可直接使用 [uni-mini-ci](https://www.npmjs.com/package/uni-mini-ci)，或参考 [这篇文章](https://juejin.cn/post/7272316909051346959) 自行配置。
 :::
 
-::: tip
-要发行其他小程序，执行 `pnpm build:mp-<platform>`打包，并使用对应开发者工具上传即可，具体可查看 package.json 的 scripts 部分。
-:::
+要发行其他小程序，执行 `pnpm build:mp-<platform>`打包，并使用对应开发者工具上传即可，具体可查看 `package.json` 的 `scripts` 部分。
 
-## App
+## APP
 
 ### 离线打包
 
 - [android](https://nativesupport.dcloud.net.cn/AppDocs/usesdk/android.html)
 - [ios](https://nativesupport.dcloud.net.cn/AppDocs/usesdk/ios.html)
 
 ::: warning
-你任然可以使用 HBuilderX 提供的"安心"打包功能，但是由于这种方式强依赖 HBuilderX，故不做推荐
+你仍然可以使用 HBuilderX 提供的“安心”打包功能，但是由于这种方式强依赖 HBuilderX，故不做推荐。
 :::
+
+## 兼容性
+
+默认情况下，你不需要调整兼容性相关的构建配置，这是因为较新的浏览器、手机、小程序运行环境提供了较好的兼容性支持。
+
+但理想很丰满，现实很骨感，总有用户不想换掉自己的旧设备、旧浏览器，而你恰好又需要关怀这些用户。这时候，你就需要调整兼容性相关的构建配置了。
+
+### VueCLI
+
+对于部分正在使用 VueCLI 的历史项目，请参考 [文档](https://cli.vuejs.org/zh/config/#transpiledependencies) 设置 `transpileDependencies`，VueCLI 会自动增加 JavaScript 和 CSS 的支持。
+
+### Vite
+
+Vite 底层使用了 [esbuild](https://esbuild.github.io/)，你可以设置 `build.target` 和 `build.cssTarget` 来做兼容。
+
+```ts
+import { defineConfig } from 'vite'
+import uni from '@dcloudio/vite-plugin-uni'
+
+export default defineConfig({
+  build: {
+    // esbuild 最低支持 es6
+    target: 'es6', // JavaScript 语法支持
+    cssTarget: 'es6' // CSS 语法支持
+  },
+  plugins: [uni()]
+})
+
+```
+
+但 esbuild 没有覆盖到所有需要兼容的情况。对于 JavaScript，esbuild 没有注入 [Polyfills](https://developer.mozilla.org/en-US/docs/Glossary/Polyfill)，这也意味着部分 JavaScript API 不可用。遗憾的是，你无法直接使用 `@vitejs/plugin-legacy` 或 `@vitejs/plugin-legacy-swc`，甚至设置 `@dcloudio/vite-plugin-uni` 中的 `viteLegacyOptions` 也 [只会在 H5 中 生效](https://github.com/dcloudio/uni-app/issues/3842)，此时只可以使用 `core-js` 来手动注入。
+
+::: code-group
+
+```ts [src/main.ts]
+/** #ifdef MP */
+// 只有构建小程序时手动注入 Polyfills
+// 可以按实际情况调整
+import 'core-js/actual/array/at'
+// ❌ 不要像下面这样做，会占用大量小程序体积且没有必要
+// import 'core-js/actual'
+/** #endif */
+import { createSSRApp } from 'vue'
+import { createPinia } from 'pinia'
+import App from './App.vue'
+
+const pinia = createPinia()
+
+export function createApp() {
+  const app = createSSRApp(App).use(pinia);
+  return {
+    app,
+  }
+}
+```
+
+```ts [vite.config.ts]
+import { defineConfig } from 'vite'
+import uni from '@dcloudio/vite-plugin-uni'
+import { isH5 } from '@uni-helper/uni-env'
+import legacy from 'vite-plugin-legacy'
+// 或者使用 vite-plugin-legacy-swc
+// import legacy from 'vite-plugin-legacy-swc'
+
+export default defineConfig({
+  build: {
+    // 最低支持 es6
+    target: 'es6', // JavaScript 语法支持
+    cssTarget: 'es6' // CSS 语法支持
+  },
+  plugins: [
+    uni(),
+    // 只有构建 H5 时应用插件自动注入 Polyfills
+    // 可以按实际情况调整
+    isH5 ? legacy() : null
+  ]
+})
+
+```
+
+:::
+
+::: tip
+你可以使用 [core-js-compat](https://github.com/zloirock/core-js/blob/master/packages/core-js-compat/README.md) 来确定具体的 Polyfills。
+:::
+
+对于 CSS，可以使用 [PostCSS](https://postcss.org/) 和 [postcss-preset-env](https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env)。
+
+```bash
+pnpm install postcss postcss-preset-env -D
+```
+
+::: code-group
+
+```ts [postcss.config.ts]
+import postcssPresetEnv from 'postcss-preset-env';
+
+const plugins = []
+if (process.env.NODE_ENV === 'production') {
+  plugins.push(
+    postcssPresetEnv({
+      // 自定义相应目标
+      // 微信小程序 2.11.2 开始支持 Vue3，对应 chrome53 和 ios10
+      browsers: ['chrome>=53', 'ios>=10']
+    })
+  )
+}
+
+export default {
+  plugins
+}
+```
+
+```ts [vite.config.ts]
+import { defineConfig } from 'vite'
+import uni from '@dcloudio/vite-plugin-uni'
+import postcssConfig from './postcss.config'
+
+export default defineConfig({
+  build: {
+    cssTarget: 'chrome61'
+  },
+  css: {
+    postcss: postcssConfig
+  },
+  plugins: [uni()]
+})
+
+```
+
+:::
+
+::: warning
+你可以在 [dcloudio/uni-app#3367](https://github.com/dcloudio/uni-app/issues/3367) 了解为什么要在 Vite 配置文件内设置 PostCSS。
+:::
+
+### 构建小程序
+
+对于小程序，你可以直接设置小程序最低基础库要求，以排除部分过于老旧的设备。

getting-started/installation.md

@@ -13,14 +13,15 @@
 
 ### 前置依赖
 
-- **Node.js** - v16.10.0 或者更高
-- **文本编辑器** - 推荐使用 VS Code 并使用 Volar 插件
-- **终端** - 为了运行 `uni` 命令
+- **Node.js** - v18.19.0 或者更高
+- **文本编辑器** - 推荐使用 [VS Code](https://code.visualstudio.com/) 并使用 [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) 插件
+- **终端** - 为了运行 `uni` 命令，Windows 推荐 Git Bash，Linux 和 macOS 推荐 zsh
 
 ::: details 最佳实践
 
-- **Node.js**: 总是使用偶数版本 (例如 18, 20)
-- **Volar**: 推荐启用接管模式 (takeover)
+- **Node.js**: 总是使用偶数版本 (即 [LTS 版本](https://nodejs.org/en/about/previous-releases)，例如 18, 20)
+- **Volar**: 推荐启用 [接管模式 takeover mode](https://cn.vuejs.org/guide/typescript/overview#volar-takeover-mode)
+
 :::
 
 打开终端，然后使用以下命令：

getting-started/introduction.md

@@ -1,15 +1,16 @@
 # 介绍
 
-vitess-uni-app 是一个开源模板，具有直观且可扩展的方式来使用 `Vue` & `uni-app` 创建类型安全、高性能和生产级的跨端应用。
+vitess-uni-app 是一个基于 `Vue` 和 `uni-app` 的开源模板，采用直观且可扩展的方式创建类型安全、高性能和生产级的跨端应用。你可以直接开始编写 `.vue` 文件，而无需从头开始配置。
 
-你可以直接开始编写 `.vue` 文件，而无需从头开始配置。
-
-vitesse-uni-app 没有绑定编辑器，你可以使用任何方式任何编辑器进行开发。
+vitesse-uni-app 灵感源于 [vitesse](https://github.com/antfu/vitesse)。
 
 ## 为什么
 
-- 不要 HBuilderX
-- 拥抱 npm 生态
+`uni-app` 背后的公司 DCloudio 选择创建自己的生态，比如 HBuilderX、uni_modules 等。这部分工作对部分开发者来说意义非凡，他们可以轻松上手并享受社区提供的一切资源。
+
+但是，`uni-app` 社区生态远不如 npm 生态繁荣，我们常常需要求助于 npm 生态来实现部分需求，而 `uni-app` 的黑盒性阻碍了这一点。
+
+vitesse-uni-app 充分拥抱开放生态，比如 VS Code 和 npm，希望能带给你更好的体验。
 
 ## 主要依赖