sync into main

guide/backend-integration.md

@@ -76,6 +76,10 @@
        "file": "assets/shared-ChJ_j-JJ.css",
        "src": "_shared-ChJ_j-JJ.css"
      },
+     "logo.svg": {
+       "file": "assets/logo-BuPIv-2h.svg",
+       "src": "logo.svg"
+     },
      "baz.js": {
        "file": "assets/baz-B2H3sXNv.js",
        "name": "baz",
@@ -101,11 +105,31 @@
    }
    ```
 
-   - 清单是一个 `Record<name, chunk>` 结构的对象。
-   - 对于 入口 或动态入口 chunk，键是相对于项目根目录的资源路径。
-   - 对于非入口 chunk，键是生成文件的名称并加上前缀 `_`。
-   - 当 [`build.cssCodeSplit`](/config/build-options.md#build-csscodesplit) 为 `false` 时生成的 CSS 文件，键为 `style.css`。
-   - Chunk 将信息包含在其静态和动态导入上（两者都是映射到清单中相应 chunk 的键），以及任何与之相关的 CSS 和资源文件。
+   manifest 具有 `Record<name, chunk>` 结构，其中每个块遵循 `ManifestChunk` 接口：
+
+   ```ts
+   interface ManifestChunk {
+     src?: string
+     file: string
+     css?: string[]
+     assets?: string[]
+     isEntry?: boolean
+     name?: string
+     names?: string[]
+     isDynamicEntry?: boolean
+     imports?: string[]
+     dynamicImports?: string[]
+   }
+   ```
+
+清单中的每个条目代表以下之一：
+- **Entry chunks**：由 [`build.rollupOptions.input`](https://rollupjs.org/configuration-options/#input) 中指定的文件生成。这些块的 isEntry 属性设置为 true，其键值是项目根目录的相对 src 路径。
+- **Dynamic entry chunks**：由动态导入生成。这些块的 isDynamicEntry 属性设置为 true，其键值是项目根目录的相对 src 路径。
+- **Non-entry chunks**：其键值是生成文件的基本名称加上前缀 `_`。
+- **Asset chunks**：由导入的资源（例如图片、字体）生成。其键值是项目根目录的相对 src 路径。
+- **CSS 文件**：当 [`build.cssCodeSplit`](/config/build-options.md#build-csscodesplit) 为 `false` 时，将生成一个带有 `style.css` 键的 CSS 文件。当 `build.cssCodeSplit` 不为 `false` 时，键的生成方式与 JS 代码块类似（即，入口代码块不带 `_` 前缀，非入口代码块带 `_` 前缀）。
+
+代码块将包含其静态和动态导入的信息（两者都是映射到清单中相应代码块的键），以及它们对应的 CSS 和资源文件（如果有）。
 
 4. 你可以利用这个文件来渲染带有哈希文件名的链接或预加载指令。
 
@@ -129,16 +153,12 @@
    <link rel="modulepreload" href="/{{ chunk.file }}" />
    ```
 
-   具体来说，一个生成 HTML 的后端在给定 manifest 文件和一个入口文件的情况下，
-   应该包含以下标签：
-
-   - 对于入口文件 chunk 的 `css` 列表中的每个文件，都应包含一个 `<link rel="stylesheet">` 标签。
-   - 递归追踪入口文件的 `imports` 列表中的所有 chunk，并为每个导入的 chunk 的每个 CSS 文件
-     包含一个 `<link rel="stylesheet">` 标签。
-   - 对于入口文件 chunk 的 `file` 键的标签（对于 JavaScript 是
-     `<script type="module">`，对于 CSS 是 `<link rel="stylesheet">`）
-   - 可选项，对于每个导入的 JavaScript chunk 的 `file` 键的 `<link rel="modulepreload">` 标签，
-     同样从入口文件 chunk 开始递归追踪导入。
+   具体来说，后端生成 HTML 时，若给定一个清单文件（manifest file）和一个入口点（entry point），应包含以下标签。
+   注意，为获得最佳性能，建议遵循以下顺序：
+   1. 为入口点代码块的 `css` 列表中的每个文件添加 `<link rel="stylesheet">` 标签（如果存在）。
+   2. 递归跟踪入口点 `imports` 列表中的所有代码块，并为每个导入代码块的 `css` 列表（如果存在）中的每个 CSS 文件添加 `<link rel="stylesheet">` 标签。
+   3. 为入口点代码块的 `file` 键添加一个标签。对于 JavaScript，可以是 `<script type="module">`；对于 CSS，可以是 `<link rel="stylesheet">`。
+   4. （可选）为每个导入的 JavaScript 代码块的 `file` 添加 `<link rel="modulepreload">` 标签，同样从入口点代码块开始递归跟踪导入。
 
    按照上面的示例 manifest，对于入口文件 `views/foo.js`，在生产环境中应包含以下标签：
 

guide/troubleshooting.md

@@ -146,6 +146,10 @@ import './Foo.js' // 应该为 './foo.js'
 
 你需要通过 `http` 协议访问该文件。最简单的办法就是使用 `npx vite preview`。
 
+### 由于区分大小写，没有这样的文件或目录错误 {#no-such-file-or-directory-error-due-to-case-sensitivity}
+
+如果您遇到类似 `ENOENT: no such file or directory` 或者 `Module not found` 之类的错误，这通常是因为您的项目是在不区分大小写的文件系统（Windows / macOS）上开发的，但在区分大小写的文件系统（Linux）上构建时发生的。请确保导入的大小写正确。
+
 ## 优化依赖 {#optimize-dependencies}
 
 ### 链接本地包时过期预构建依赖项 {#outdated-pre-bundled-deps-when-linking-to-a-local-package}

index.md

@@ -15,12 +15,12 @@ markdownStyles: false
 import { useData } from 'vitepress'
 import { onBeforeUnmount, onMounted, ref } from 'vue'
 
-import Hero from '.vitepress/theme/components/landing/1. hero-section/HeroSection.vue'
+import Hero from './.vitepress/theme/components/landing/1. hero-section/HeroSection.vue'
 import FeatureSection from './.vitepress/theme/components/landing/2. feature-section/FeatureSection.vue'
 import FrameworksSection from './.vitepress/theme/components/landing/3. frameworks-section/FrameworksSection.vue'
 import CommunitySection from './.vitepress/theme/components/landing/4. community-section/CommunitySection.vue'
 import SponsorSection from './.vitepress/theme/components/landing/5. sponsor-section/SponsorSection.vue'
-import GetStartedSection from '.vitepress/theme/components/landing/6. get-started-section/GetStartedSection.vue'
+import GetStartedSection from './.vitepress/theme/components/landing/6. get-started-section/GetStartedSection.vue'
 import FeatureInstantServerStart from './.vitepress/theme/components/landing/2. feature-section/FeatureInstantServerStart.vue'
 import FeatureHMR from './.vitepress/theme/components/landing/2. feature-section/FeatureHMR.vue'
 import FeatureRichFeatures from './.vitepress/theme/components/landing/2. feature-section/FeatureRichFeatures.vue'