chore: update tutorial cn docs

farm-fe · Mar 9, 2024 · 4088875 · 4088875
1 parent 60c7636
commit 4088875
Show file tree

Hide file tree

Showing 6 changed files with 214 additions and 44 deletions.
diff --git a/docs/tutorials/2-start.md b/docs/tutorials/2-start.md
@@ -240,7 +240,7 @@ export default defineConfig({
   // ...
 });
 ```
-When building for production, the injected resources url would be `https://cdn.com/index-s2f3.s14dqwa.js`. For example, in your output html, all `<script>` and `<link`> would be:
+When building, the injected resources url would be `https://cdn.com/index-s2f3.s14dqwa.js`. For example, in your output html, all `<script>` and `<link`> would be:
 
 ```html {4,8}
 <html>

diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/0-overview.md b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/0-overview.md
@@ -6,17 +6,17 @@ Vue项目也得到了Farm的全力支持。 Farm中可以直接使用`Vite`的`@
 :::
 
 你将学习：
-* 如何从头开始构建一个生产就绪的 Farm React 项目。 我们将介绍如何添加流行组件
+* 如何从头开始构建一个生产就绪的 Farm React 项目。 我们将介绍配置常用插件、添加常见组件库等。
 * Farm的基本概念，如`input`、`output`、`dev-server`、`HMR`和`plugins`
 * Farm的日常配置和常用插件。
 
 我们的目标是通过本教程简化您使用 Farm 生态系统的开发体验。 如果您想从其他工具迁移到 Farm，它也会很有帮助。
 
 :::note
-本教程是`从头开始构建 Farm React 项目`，如果您想快速启动一个新的 Farm 项目，请使用我们的官方模板和命令`pnpm create farm`。
+本教程将 `从头开始构建 Farm React 项目`，如果您想快速启动一个新的 Farm 项目，请使用我们的官方模板和命令 `pnpm create farm`。
 :::
 
-跟着我们的教程，开启你的超快农场开发之旅吧！
+跟着我们的教程，开启你的 Farm 极速开发之旅吧！
 
 * [1. 创建 Farm React 项目](/docs/tutorials/create)
 * [2. 使用 Farm 开发项目](/docs/tutorials/start)

diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/1-create.md b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/1-create.md
@@ -2,7 +2,7 @@
 在本章中，我们将从头开始创建一个新的 Farm React 项目，并以开发模式启动它。
 
 :::note
-在本教程中，我们使用`pnpm`作为默认包管理器。 本章是`从头开始构建 Farm React 项目`，如果您想快速启动一个新的 Farm 项目，请使用我们的官方模板和命令`pnpm create farm`。
+在本教程中，我们使用 `pnpm` 作为默认包管理器。 本章将 `从头开始构建 Farm React 项目`，如果您想快速启动一个新的 Farm 项目，请使用我们的官方模板和命令 `pnpm create farm`。
 :::
 
 ## 创建一个 Npm 包
@@ -115,7 +115,7 @@ const root = createRoot(container);
 root.render(<div>A React Page compiled by Farm</div>);
 ```
 
-## Start Your Farm Project!
+## 启动 Farm 项目!
 现在一切都准备好了，将启动脚本添加到您的`package.json`中：
 ```json title="package.json" {6}
 {

diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/2-start.md b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/2-start.md
@@ -198,6 +198,64 @@ export default defineConfig({
 请参阅 [使用 Farm 插件](/docs/using-plugins) 了解有关 Farm 插件的更多信息。
 :::
 
+## 配置 public 目录
+对于不需要编译的资源，可以将它们放在 public 目录下。 在`public`下添加`favicon.ico`：
+
+```text {3-4}
+.
+├── ...
+└── public
+    └── favicon.icon
+```
+
+然后`favicon`即可用于您的网站。 你还可以放入一些可以直接获取的静态资源，例如图片：
+
+```text {5-6}
+.
+├── ...
+└── public
+    ├── favicon.icon
+    └── images
+        └── background.png
+```
+
+:::note
+使用配置选项 **[publicDir](/docs/config/shared#publicdir)** 自定义您的公共目录。
+:::
+
+## 配置 publicPath
+使用 `compilation.output.publicPath` 配置动态资源加载的 `url 前缀` 以及将 `<script>` 和 `<link>` 标签注入到 `html` 中时。 我们在 `farm.config.ts` 中添加以下配置:
+
+```ts title="farm.config.ts" {5-7}
+// ...
+export default defineConfig({
+  compilation: {
+    output: {
+      publicPath: process.env.NODE_ENV === 'production' ? 'https://cdn.com' : '/'
+    }
+  }
+  // ...
+});
+```
+
+在构建时，注入的资源 URL 将类似 `https://cdn.com/index-s2f3.s14dqwa.js`。 例如，在输出 html 中，所有 `<script>` 和 `<link`> 将为：
+
+```html {4,8}
+<html>
+  <head>
+    <!-- ... -->
+    <link href="https://cdn.com/index-a23e.s892s1.css" />
+  </head>
+  <body>
+    <!-- ... -->
+    <script src="https://cdn.com/index-s2f3.s14dqwa.js"></script>
+  </body>
+</html>
+```
+
+当加载动态脚本和CSS时，动态获取的资源url也将是：`https://cdn.com/<asset-path>`
+
+
 ## 配置 Alias 以及 Externals
 Alias 和 externals 是最常用的配置之一, 在 Farm 中，可以使用 `compilation.resolve.alias` 和 `compilation.externals` 配置项:
 
@@ -225,11 +283,7 @@ export default defineConfig({
 ### 常用配置
 配置示例：
 ```ts
-import type { UserConfig } from '@farmfe/core';
-
-function defineConfig(config: UserConfig) {
-   return config;
-}
+import { defineConfig } from '@farmfe/core';
 
 export default defineConfig({
    // 所有开发服务器选项都在 server 下
@@ -249,19 +303,15 @@ export default defineConfig({
 ```
 对于上面的示例，我们使用了以下选项：
 * **打开**：自动打开指定端口的浏览器
-* **端口**：将开发服务器端口设置为“9001”
+* **端口**：将开发服务器端口设置为`9001`
 * **hmr**：设置 hmr 端口和监视文件，我们忽略 `auto_generate` 目录下的文件更改。
 
 
 ### Setup Proxy
 配置服务器代理。 基于[koa-proxies](https://www.npmjs.com/package/koa-proxies)实现，具体选项参考其文档，示例：
 
 ```ts
-import type { UserConfig } from '@farmfe/core';
-
-function defineConfig(config: UserConfig) {
-   return config;
-}
+import { defineConfig } from '@farmfe/core';
 
 export default defineConfig({
     server: {
@@ -274,5 +324,21 @@ export default defineConfig({
      },
    },
 });
+```
+
+## 配置 root 和 envDir
+使用`root`和`envDir`指定项目根目录和加载环境变量的目录。 在`farm.config.ts`中添加以下选项：
 
-```
+```ts title="farm.config.ts"
+import path from 'node:path';
+import { defineConfig } from '@farmfe/core';
+
+export default defineConfig({
+  root: path.join(process.cwd(), 'client'),
+  envDir: 'my-env-dir'
+});
+```
+
+:::note
+有关 `envDir` 的详细信息，请参阅[环境变量和模式](/docs/features/env)
+:::
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/3-build.md b/i18n/zh/docusaurus-plugin-content-docs/current/tutorials/3-build.md
@@ -1,30 +1,130 @@
 # 3. 使用 Farm 构建生产项目
-默认情况下，Farm 已经为生产构建开启了以下功能的支持：
-* **`Tree Shake`**：裁剪和过滤无关模块和代码
-* **`压缩`**：对产物进行压缩和混淆，减少产物体积
-* **`自动注入 Polyfill`**：Farm 默认对项目降级到 ES5，这意味着 Farm 构建的产物几乎可以在所有浏览器上运行
-* **`自动进行局部打包`**: 依据依赖关系以及大小，将项目进行局部打包，对于每次资源请求，生成 25 个左右的资源，在保证并行加载性能的同时，尽可能提升缓存命中率
-
-## 添加 build script
-在 `package.json` 中添加 build script:
-```json title="package.json" {7}
+默认情况下，Farm 已启用对生产版本的以下功能的支持：
+* **`Tree Shake`**：裁剪和过滤不相关的模块和代码
+* **`压缩`**：压缩并破坏输出资源。
+* **`自动注入Polyfill`**：默认情况下Farm降级到现代浏览器(ES7)，如果需要旧版浏览器支持，请配置[`targetEnv`](/docs/config/compilation-options#output-targetenv)
+* **`自动局部打包`**：根据依赖关系和大小，对项目进行部分打包。 对于每个资源请求，会生成大约25个资源，以保证并行加载性能，并尽可能提高缓存命中率。
+
+## 配置输出目录
+在 `package.json` 中添加构建脚本：
+
+```json title="package.json" {7-8}
 {
-  "name": "1-create-a-project",
-  "version": "1.0.0",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "start": "farm start",
-    "build": "farm build"
-  },
-  // ... ignore other fields 
+   "name": "1-create-a-project",
+   "version": "1.0.0",
+   "scripts": {
+     "test": "echo \"Error: no test specified\" && exit 1",
+     "start": "farm start",
+     "build": "farm build",
+     "preview": "farm preview"
+   },
+   // ...ignore other fields
 }
 ```
-然后执行 `npm run build` 即可。
 
-## 配置 Tree Shake 和压缩
-## Configure Tree Shake and compression
-* [Tree Shake](/docs/features/tree-shake)
-* [Minification](/docs/features/minification)
+然后执行`npm run build`，构建的资源将被生成到`build`目录
+
+```text
+build
+├─ favicon.ico
+├─ index.html
+├─ index_02bc.bd68e90b.js
+├─ index_02bc.bd68e90b.js.map
+├─ index_1c74.4b50f73e.js
+├─ index_7734.440d56a3.js
+├─ index_880b.4631ecee.js
+├─ index_8d49.63f7b906.css
+├─ index_8d49.63f7b906.css.map
+├─ index_9025.84e1f8e6.js
+├─ index_ca37.f2c276ef.js
+├─ index_ef2f.e25349d8.js
+├─ index_f346.369a7312.js
+```
+
+如果您想自定义资源生成的路径，您可以使用：
+* [`output.filename`](/docs/config/compilation-options#outputfilename)
+* [`output.assetsFilename`](/docs/config/compilation-options#outputassetsfilename)
+
+```ts
+import defineConfig from '@farmfe/core';
+
+export default defineConfig({
+  compilation: {
+    output: {
+      path: 'build',
+      filename: 'assets/[name].[hash].[ext]',
+      assetsFilename: 'static/[resourceName].[ext]'
+    }
+  }
+})
+```
+
+对于上面的示例，所有`js/css`将被发送到`build/assets/`（例如：`build/assets/index-ea54.abbe3e.js`）。 所有静态资源（例如图像）都将发送到`build/static`（例如：`build/static/background.png`）
+
+## 预览构建的资源
+资源构建完成后，您可以通过`npm run Preview`进行预览：
+
+```sh
+$ npm run preview
+
+> [email protected] preview
+> farm preview
+
+[ Farm ] Using config file at /root/tutorials/3-build-for-production/farm.config.ts
+[ Farm ] preview server running at: 
+
+[ Farm ] > Local:   http://localhost:1911/
+[ Farm ] > Network: http://198.18.0.1:1911/
+[ Farm ] > Network: http://10.242.197.146:1911/
+[ Farm ] > Network: http://192.168.1.31:1911/
+```
+
+打开`http://localhost:1911/`来预览项目。
+
+## 浏览器兼容性
+默认情况下，Farm 将项目构建到本机支持`async/await`的现代浏览器：
+
+* Chrome >= 62
+* Firefox >= 63
+* Safari >= 13.1
+* Edge >= 79
+
+可以使用 [output.targetEnv](/docs/config/compilation-options#output-targetenv) 来配置目标浏览器：
+
+```ts
+import { defineConfig } from '@farmfe/core';
+
+export default defineConfig({
+  compilation: {
+    output: {
+      targetEnv: 'browser-legacy'
+    }
+  }
+})
+```
+
+在上面的例子中，Farm 会将语法降级为 `es5` 并自动注入 polyfill。 然后我们必须安装`core-js@3`来进行`polyfill`注入：
+
+```sh
+pnpm add -D core-js@3
+```
+
+:::note
+* 如果您的目标是旧版浏览器，则需要手动安装 `core-js@3`。
+* 如果你想更精确地配置浏览器目标，请参阅[语法 Downgrade 和 Polyfill](/docs/advanced/polyfill)
+:::
+
+## 配置 Tree Shake 和 Minify
+出于性能原因，像`treeShake`和`minify`这样的生产优化在`development`中默认被`禁用`，而在`生产`中默认被`启用`。 但如果手动配置了`treeShake`或`minify`，则无论`development`或`productive`都将使用默认值。
+
+有关 Tree Shake 和 Minify 的详细信息，请参阅：
+* [Tree Shake](/docs/advanced/tree-shake)
+* [Minification](/docs/advanced/minification)
+
 
 ## 配置局部打包策略
-* [Partial Bundling](/docs/features/partial-bundling)
+:::note
+详细信息参考[局部打包](/docs/advanced/partial-bundling)。
+:::
+
+Farm 已经启用了打包的最佳实践，请确保您确实需要手动配置打包策略，参考[局部打包](/docs/advanced/partial-bundling) 了解详情。
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/why-farm.md b/i18n/zh/docusaurus-plugin-content-docs/current/why-farm.md
@@ -4,6 +4,10 @@ sidebar_position: 2
 
 # 为什么需要 Farm？
 
+## Farm 是什么？
+Farm 是一个非常快的基于 Rust 的 Web 构建工具，类似 `webpack` 和 `vite`，但**更快**。 farm `resolve, load, transform` 所有 `asset(js/jsx/ts/tsx、css/sass/less、html、静态资源、json 等)`，并将它们打包成一系列`可部署文件`。 Farm 是一个速度极快的构建工具，可帮助您构建更快的 `web/nodejs` 应用程序。
+
+## 为什么需要 Farm？
 随着 web 项目规模的扩大，构建性能已经成为主要瓶颈，对于一个庞大的项目，使用 webpack 编译可能需要 10min 甚至更多，一次 hmr 更新可能需要 10s 甚至更多，严重降低了研发效率。
 
 因此我们急需极速的构建工具，解决项目编译性能问题。然后 vite/snowpack 这样的 unbundled 工具应运而生，此类工具主要有下面三个特性：
@@ -17,11 +21,11 @@ sidebar_position: 2
 * **拆包优化困难**： 受限于 Rollup，拆包配置不够灵活、易用。
 * 而 Vite 在 dev 上之所以这么快，esbuild 功不可没，它是用 go 编写的。 Go 利用了原生平台的优势，远快于 Js。
 
-事实上，我们真正需要的是一个快速、强大、一致的 Web 构建工具，可以在解决上述问题的基础上，提供更加极致的编译效率。因此我们开发了 Farm。
+事实上，我们真正需要的是一个快速、强大、一致的 Web 构建工具，可以在解决上述问题的基础上，提供更加极致的编译效率。因此我们设计并开发了 Farm。
 
-:::note
+<!-- :::note
 Farm 的设计主要都是针对 web 浏览器场景（包括 pc、移动、webview 等等），期望从构建速度到资源加载速度全方面提升 web 性能。因此 Farm 不会尝试成为一个传统意义上的通用打包器，Farm 的打包只是为了减少资源请求时的模块数量。
-:::
+::: -->
 
 <!-- 但是如果使用 JS 编写构建工具，受限于 JS 单线程以及解释执行的限制，很难在现有的 JS 打包工具如 Rollup 或者 Webpack 基础上有很大的性能提升（当然有的构建工具比如 vite 在 dev 环境绕过打包，这种情况我们将在后文讨论）。因此我们需要引入原生语言的能力，Rust 就是一个非常好的选择，Rust 拥有内存安全、性能优秀等特性，同时 Rust 也有不少前端开源生态比如 SWC 编译器（SWC 可以简单理解为 Babel 的 Rust 替代），基于现有生态也能够更加方便地实现前端构建工具。 -->