Skip to content

Commit a1c5ac4

Browse files
authored
Merge pull request #930 from vitejs/sync-7d52e910-1
docs(en): merge docs-cn/sync-docs into docs-cn/dev @ 7d52e91
2 parents 5d68ec7 + 59948dc commit a1c5ac4

26 files changed

+1374
-289
lines changed

.vitepress/config.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { defineConfig, DefaultTheme } from 'vitepress'
2+
import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
23
import { buildEnd } from './buildEnd.config'
34

45
const ogDescription = 'Next Generation Frontend Tooling'
@@ -393,5 +394,8 @@ export default defineConfig({
393394
])
394395
return pageData
395396
},
397+
markdown: {
398+
codeTransformers: [transformerTwoslash()],
399+
},
396400
buildEnd,
397401
})

.vitepress/theme/composables/sponsor.ts

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { ref, onMounted } from 'vue'
1+
import { ref, onMounted, onUnmounted } from 'vue'
22

33
interface Sponsors {
44
special: Sponsor[]
@@ -13,6 +13,10 @@ interface Sponsor {
1313
name: string
1414
img: string
1515
url: string
16+
/**
17+
* Expects to also have an **inversed** image with `-dark` postfix.
18+
*/
19+
hasDark?: true
1620
}
1721

1822
// shared data across instances so we load only once.
@@ -58,12 +62,40 @@ const viteSponsors: Pick<Sponsors, 'special' | 'gold'> = {
5862
name: 'Transloadit',
5963
url: 'https://transloadit.com/?utm_source=vite&utm_medium=referral&utm_campaign=sponsorship&utm_content=website',
6064
img: '/transloadit.svg',
65+
hasDark: true,
6166
},
6267
],
6368
}
6469

70+
function toggleDarkLogos() {
71+
if (data.value) {
72+
const isDark = document.documentElement.classList.contains('dark')
73+
data.value.forEach(({ items }) => {
74+
items.forEach((s: Sponsor) => {
75+
if (s.hasDark) {
76+
s.img = isDark
77+
? s.img.replace(/(\.\w+)$/, '-dark$1')
78+
: s.img.replace(/-dark(\.\w+)$/, '$1')
79+
}
80+
})
81+
})
82+
}
83+
}
84+
6585
export function useSponsor() {
6686
onMounted(async () => {
87+
const ob = new MutationObserver((list) => {
88+
for (const m of list) {
89+
if (m.attributeName === 'class') {
90+
toggleDarkLogos()
91+
}
92+
}
93+
})
94+
ob.observe(document.documentElement, { attributes: true })
95+
onUnmounted(() => {
96+
ob.disconnect()
97+
})
98+
6799
if (data.value) {
68100
return
69101
}
@@ -72,6 +104,7 @@ export function useSponsor() {
72104
const json = await result.json()
73105

74106
data.value = mapSponsors(json)
107+
toggleDarkLogos()
75108
})
76109

77110
return {

.vitepress/theme/index.ts

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
import { h } from 'vue'
22
import type { Theme } from 'vitepress'
33
import DefaultTheme from 'vitepress/theme'
4+
import TwoslashFloatingVue from '@shikijs/vitepress-twoslash/client'
5+
import '@shikijs/vitepress-twoslash/style.css'
46
import './styles/vars.css'
57
import HomeSponsors from './components/HomeSponsors.vue'
68
import AsideSponsors from './components/AsideSponsors.vue'
@@ -19,6 +21,7 @@ export default {
1921
},
2022
enhanceApp({ app }) {
2123
app.component('SvgImage', SvgImage)
24+
app.use(TwoslashFloatingVue)
2225
},
2326
} satisfies Theme
2427

.vitepress/tsconfig.json

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"compilerOptions": {
3+
"target": "ES2022",
4+
"module": "ESNext",
5+
"moduleResolution": "Bundler",
6+
"strict": true,
7+
"noImplicitOverride": true,
8+
"noUnusedLocals": true,
9+
"esModuleInterop": true,
10+
"noEmit": true
11+
},
12+
"exclude": ["cache", "dist"]
13+
}

config/build-options.md

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,13 +48,22 @@ type ResolveModulePreloadDependenciesFn = (
4848
4949
`resolveDependencies` 函数将为每个动态导入调用,同时带着一个它所依赖的 chunk 列表。并且它还会为每个在入口 HTML 文件中导入的 chunk 调用。 可以返回一个新的依赖关系数组,可能被过滤后变少了,也可能有更多依赖注入进来了,同时它们的路径也被修改过。`deps` 路径是相对于 `build.outDir` 的。若在注入该模块到 HTML head 时使用 `new URL(dep, import.meta.url)` 获取绝对路径,则对于 `hostType === 'js'`,允许返回一个相对于 `hostId` 的路径。
5050
51-
```js
51+
<!-- prettier-ignore-start -->
52+
```js twoslash
53+
/** @type {import('vite').UserConfig} */
54+
const config = {
55+
build: {
56+
// ---cut-before---
5257
modulePreload: {
5358
resolveDependencies: (filename, deps, { hostId, hostType }) => {
5459
return deps.filter(condition)
55-
}
60+
},
61+
},
62+
// ---cut-after---
63+
},
5664
}
5765
```
66+
<!-- prettier-ignore-end -->
5867

5968
解析得到的依赖路径可以再在之后使用 [`experimental.renderBuiltUrl`](../guide/build.md#advanced-base-options) 更改。
6069

config/dep-optimization-options.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,9 @@
1919
:::warning CommonJS
2020
CommonJS 的依赖不应该排除在优化外。如果一个 ESM 依赖被排除在优化外,但是却有一个嵌套的 CommonJS 依赖,则应该为该 CommonJS 依赖添加 `optimizeDeps.include`。例如:
2121

22-
```js
22+
```js twoslash
23+
import { defineConfig } from 'vite'
24+
// ---cut---
2325
export default defineConfig({
2426
optimizeDeps: {
2527
include: ['esm-dep > cjs-dep'],
@@ -37,7 +39,9 @@ export default defineConfig({
3739

3840
**实验性:** 如果你使用的是一个有很多深层导入的库,你也可以指定一个尾部的 glob 模式来一次性地预构建所有深层导入。这将避免在使用新的深层导入时不断地预构建。可以在此 [提供反馈](https://github.com/vitejs/vite/discussions/15833)。例如:
3941

40-
```js
42+
```js twoslash
43+
import { defineConfig } from 'vite'
44+
// ---cut---
4145
export default defineConfig({
4246
optimizeDeps: {
4347
include: ['my-lib/components/**/*.vue'],

config/index.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,9 @@ Vite 也直接支持 TS 配置文件。你可以在 `vite.config.ts` 中使用 `
5050

5151
如果配置文件需要基于(`dev`/`serve``build`)命令或者不同的 [模式](/guide/env-and-mode) 来决定选项,亦或者是一个 SSR 构建(`isSsrBuild`)、一个正在预览的构建产物(`isPreview`),则可以选择导出这样一个函数:
5252

53-
```js
53+
```js twoslash
54+
import { defineConfig } from 'vite'
55+
// ---cut---
5456
export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
5557
if (command === 'serve') {
5658
return {
@@ -65,15 +67,17 @@ export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
6567
})
6668
```
6769

68-
需要注意的是,在 Vite 的 API 中,在开发环境下 `command` 的值为 `serve`(在 CLI 中, `vite dev``vite serve``vite` 的别名),而在生产环境下为 `build``vite build`)。
70+
需要注意的是,在 Vite 的 API 中,在开发环境下 `command` 的值为 `serve`(在 CLI 中, `vite dev``vite serve`[`vite`](/guide/cli#vite) 的别名),而在生产环境下为 `build`[`vite build`](/guide/cli#vite-build))。
6971

7072
`isSsrBuild``isPreview` 是额外的可选标志,用于区分 `build``serve` 命令的类型。一些加载 Vite 配置的工具可能不支持这些标志,而会传递 `undefined`。因此,建议使用 `true``false` 的显式比较。
7173

7274
## 异步配置 {#async-config}
7375

7476
如果配置需要调用一个异步函数,也可以转而导出一个异步函数。这个异步函数也可以通过 `defineConfig` 传递,以便获得更好的智能提示:
7577

76-
```js
78+
```js twoslash
79+
import { defineConfig } from 'vite'
80+
// ---cut---
7781
export default defineConfig(async ({ command, mode }) => {
7882
const data = await asyncFunction()
7983
return {
@@ -88,7 +92,7 @@ export default defineConfig(async ({ command, mode }) => {
8892

8993
注意 Vite 默认是不加载 `.env` 文件的,因为这些文件需要在执行完 Vite 配置后才能确定加载哪一个,举个例子,`root``envDir` 选项会影响加载行为。不过当你的确需要时,你可以使用 Vite 导出的 `loadEnv` 函数来加载指定的 `.env` 文件。
9094

91-
```js
95+
```js twoslash
9296
import { defineConfig, loadEnv } from 'vite'
9397

9498
export default defineConfig(({ command, mode }) => {

config/server-options.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,10 @@
1818

1919
你可以设置 [`dns.setDefaultResultOrder('verbatim')`](https://nodejs.org/api/dns.html#dns_dns_setdefaultresultorder_order) 来禁用这个重新排序的行为。Vite 会将地址打印为 `localhost`
2020

21-
```js
21+
```js twoslash
2222
// vite.config.js
2323
import { defineConfig } from 'vite'
24-
import dns from 'dns'
24+
import dns from 'node:dns'
2525

2626
dns.setDefaultResultOrder('verbatim')
2727

@@ -152,6 +152,8 @@ export default defineConfig({
152152

153153
设置 `server.hmr.overlay``false` 可以禁用开发服务器错误的屏蔽。
154154

155+
`protocol` 是用于设置 HMR 连接使用的 WebSocket 协议的选项,可以是 `ws`(WebSocket)或者 `wss`(WebSocket Secure)。
156+
155157
`clientPort` 是一个高级选项,只在客户端的情况下覆盖端口,这允许你为 websocket 提供不同的端口,而并非在客户端代码中查找。如果需要在 dev-server 情况下使用 SSL 代理,这非常有用。
156158

157159
`server.hmr.server` 被定义后,Vite 将会通过所提供的的服务器来处理 HMR 连接。如果不是在中间件模式下,Vite 将尝试通过已有服务器处理 HMR 连接。这在使用自签证书或想通过网络在某端口暴露 Vite 的情况下,非常有用。
@@ -236,7 +238,7 @@ Vite 服务器的文件监听器默认会监听 `root` 目录,同时会跳过
236238

237239
- **示例:**
238240

239-
```js
241+
```js twoslash
240242
import express from 'express'
241243
import { createServer as createViteServer } from 'vite'
242244

@@ -356,9 +358,9 @@ export default defineConfig({
356358
// 添加到忽略列表中。
357359
sourcemapIgnoreList(sourcePath, sourcemapPath) {
358360
return sourcePath.includes('node_modules')
359-
}
360-
}
361-
};
361+
},
362+
},
363+
})
362364
```
363365

364366
::: tip 注意

config/shared-options.md

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -163,7 +163,14 @@ Vite 有一个“允许的情景”列表,并且会匹配列表中第一个情
163163
- **相关:** [esbuild#preserve-symlinks](https://esbuild.github.io/api/#preserve-symlinks)[webpack#resolve.symlinks
164164
](https://webpack.js.org/configuration/resolve/#resolvesymlinks)
165165

166-
## css.modules {#css-modules}
166+
## html.cspNonce
167+
168+
- **类型:** `string`
169+
- **相关:** [内容安全策略(CSP)](/guide/features#content-security-policy-csp)
170+
171+
一个在生成脚本或样式标签时会用到的 nonce 值占位符。设置此值还会生成一个带有 nonce 值的 meta 标签。
172+
173+
## css.modules
167174

168175
- **类型:**
169176
```ts
@@ -408,7 +415,7 @@ export default defineConfig({
408415

409416
使用自定义 logger 记录消息。可以使用 Vite 的 `createLogger` API 获取默认的 logger 并对其进行自定义,例如,更改消息或过滤掉某些警告。
410417

411-
```js
418+
```ts twoslash
412419
import { createLogger, defineConfig } from 'vite'
413420

414421
const logger = createLogger()

config/ssr-options.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818

1919
这个选项可以防止列出的依赖项在服务端渲染(SSR)时被外部化,这些依赖项将会在构建过程中被打包。默认情况下,只有软链接的依赖项不会被外部化(这是为了HMR)。如果你希望将软链接的依赖项也外部化,可以将其名称传给 `ssr.external` 选项。
2020

21-
如果这个选项设置为 `true`,那么没有任何依赖项会被外部化。然而,如果你在 `ssr.external` 中明确列出了一些依赖项(使用 `string[]` 类型),那么这些依赖项可以优先被外部化。
21+
如果这个选项设置为 `true`,那么没有任何依赖项会被外部化。然而,如果你在 `ssr.external` 中明确列出了一些依赖项(使用 `string[]` 类型),那么这些依赖项可以优先被外部化。如果设置了 `ssr.target: 'node'`,那么 Node.js 的内置模块也会被默认外部化。
2222

2323
需要注意的是,如果 `ssr.noExternal: true``ssr.external: true` 都被设置了,那么 `ssr.noExternal` 将优先生效,没有任何依赖项会被外部化。
2424

guide/api-hmr.md

Lines changed: 27 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,15 @@
88

99
Vite 通过特殊的 `import.meta.hot` 对象暴露手动 HMR API。
1010

11-
```ts
11+
```ts twoslash
12+
import type { ModuleNamespace } from 'vite/types/hot.d.ts'
13+
import type { InferCustomEventPayload } from 'vite/types/customEvent.d.ts'
14+
15+
// ---cut---
1216
interface ImportMeta {
1317
readonly hot?: ViteHotContext
1418
}
1519

16-
type ModuleNamespace = Record<string, any> & {
17-
[Symbol.toStringTag]: 'Module'
18-
}
19-
2020
interface ViteHotContext {
2121
readonly data: any
2222

@@ -32,7 +32,6 @@ interface ViteHotContext {
3232
prune(cb: (data: any) => void): void
3333
invalidate(message?: string): void
3434

35-
// `InferCustomEventPayload` provides types for built-in Vite events
3635
on<T extends string>(
3736
event: T,
3837
cb: (payload: InferCustomEventPayload<T>) => void,
@@ -66,7 +65,9 @@ Vite 在 [`vite/client.d.ts`](https://github.com/vitejs/vite/blob/main/packages/
6665
6766
要接收模块自身,应使用 `import.meta.hot.accept`,参数为接收已更新模块的回调函数:
6867
69-
```js
68+
```js twoslash
69+
import 'vite/client'
70+
// ---cut---
7071
export const count = 1
7172

7273
if (import.meta.hot) {
@@ -89,7 +90,13 @@ Vite 要求这个函数的调用在源代码中显示为 `import.meta.hot.accept
8990
9091
模块也可以接受直接依赖项的更新,而无需重新加载自身:
9192
92-
```js
93+
```js twoslash
94+
// @filename: /foo.d.ts
95+
export declare const foo: () => void
96+
97+
// @filename: /example.js
98+
import 'vite/client'
99+
// ---cut---
93100
import { foo } from './foo.js'
94101

95102
foo()
@@ -115,7 +122,9 @@ if (import.meta.hot) {
115122
116123
一个接收自身的模块或一个期望被其他模块接收的模块可以使用 `hot.dispose` 来清除任何由其更新副本产生的持久副作用:
117124
118-
```js
125+
```js twoslash
126+
import 'vite/client'
127+
// ---cut---
119128
function setupSideEffect() {}
120129

121130
setupSideEffect()
@@ -131,7 +140,9 @@ if (import.meta.hot) {
131140
132141
注册一个回调,当模块在页面上不再被导入时调用。与 `hot.dispose` 相比,如果源代码更新时自行清理了副作用,你只需要在模块从页面上被删除时,使用此方法进行清理。Vite 目前在 `.css` 导入上使用此方法。
133142
134-
```js
143+
```js twoslash
144+
import 'vite/client'
145+
// ---cut---
135146
function setupOrReuseSideEffect() {}
136147

137148
setupOrReuseSideEffect()
@@ -149,7 +160,9 @@ if (import.meta.hot) {
149160
150161
注意,不支持对 `data` 本身的重新赋值。相反,你应该对 `data` 对象的属性进行突变,以便保留从其他处理程序添加的信息。
151162
152-
```js
163+
```js twoslash
164+
import 'vite/client'
165+
// ---cut---
153166
// ok
154167
import.meta.hot.data.someValue = 'hello'
155168

@@ -167,7 +180,9 @@ import.meta.hot.data = { someValue: 'hello' }
167180
168181
请注意,你应该总是调用 `import.meta.hot.accept`,即使你打算随后立即调用 `invalidate`,否则 HMR 客户端将不会监听未来对接收自身模块的更改。为了清楚地表达你的意图,我们建议在 `accept` 回调中调用 `invalidate`,例如:
169182
170-
```js
183+
```js twoslash
184+
import 'vite/client'
185+
// ---cut---
171186
import.meta.hot.accept((module) => {
172187
// 你可以使用新的模块实例来决定是否使其失效。
173188
if (cannotHandleUpdate(module)) {

0 commit comments

Comments
 (0)