|
1 | | -#构建产物 |
| 1 | +#Build Artifacts |
2 | 2 |
|
3 | | -本章节将会分析默认示例执行`ssr build`命令后的构建产物来帮助开发者更好的理解应用。`ssr`框架的构建产物都非常清晰且数量相比于同类型的框架非常少，从文件名中即可看出代表的含义 |
| 3 | +This chapter will analyze the build artifacts after executing the`ssr build`command on the default example to help developers better understand the application. The build artifacts of the`ssr`framework are very clear and the quantity is much smaller compared to similar frameworks. The meaning can be seen from the file names. |
4 | 4 |
|
5 | | -##产物类型 |
| 5 | +##Artifact Types |
6 | 6 |
|
7 | | -相比于传统的`SPA`应用只会构建出纯客户端用到的文件。服务端渲染场景下我们会分别构建出服务端用到的产物和客户端用到的产物 |
| 7 | +Compared to traditional`SPA`applications that only build pure client-side files, in server-side rendering scenarios, we build artifacts for both server-side and client-side use separately. |
8 | 8 |
|
9 | 9 | ```shell |
10 | 10 | $ tree build |
11 | 11 | build |
12 | | -├── client#客户端构建产物文件夹 |
13 | | -│ ├── asset-manifest.json#客户端构建产物清单，包含源文件到生成后的文件的映射 |
14 | | -│ └── static#静态资源 |
15 | | -│ ├── css |
16 | | -│ │ ├── Page.9b4ee7a2.chunk.css#公共样式 |
17 | | -│ │ ├── detail-id.802a30ee.chunk.css# render$id页面样式 |
18 | | -│ │ └── index.e0ee4d68.chunk.css# index/render页面样式 |
19 | | -│ └── js |
20 | | -│ ├── Page.bd84ae30.chunk.js#公共业务js代码 |
21 | | -│ ├── detail-id-fetch.88ffa1dd.chunk.js# fetch$id文件 |
22 | | -│ ├── detail-id.7718bdb4.chunk.js# render$id文件 |
23 | | -│ ├── index-fetch.07aa86b0.chunk.js# fetch文件 |
24 | | -│ ├── index.b76c09e5.chunk.js# render文件 |
25 | | -│ ├── runtime~Page.3f285250.js#无需关注，提供 webpack 自身的一些 api，意义上等于老版本的webpack生成的manifest.js |
26 | | -│ └── vendor.92dcc0b4.chunk.js#第三方模块 |
27 | | -└── server#服务端构建产物文件夹 |
28 | | - ├── Page.server.js#服务端 bundle，通过框架底层的server-entry方法构建而出 |
29 | | - └── static#该文件夹非Vite本地开发场景用不到，无需关注 |
| 12 | +├── client#client-side build artifacts folder |
| 13 | +│├── asset-manifest.json#client-side build artifacts manifest, contains mapping from source files to generated files |
| 14 | +│└── static#static resources |
| 15 | +│ ├── css |
| 16 | +│ │├── Page.9b4ee7a2.chunk.css#common styles |
| 17 | +│ │├── detail-id.802a30ee.chunk.css# render$idpage styles |
| 18 | +│ │└── index.e0ee4d68.chunk.css# index/renderpage styles |
| 19 | +│ └── js |
| 20 | +│├── Page.bd84ae30.chunk.js#common businessjscode |
| 21 | +│├── detail-id-fetch.88ffa1dd.chunk.js# fetch$idfile |
| 22 | +│├── detail-id.7718bdb4.chunk.js# render$idfile |
| 23 | +│├── index-fetch.07aa86b0.chunk.js# fetchfile |
| 24 | +│├── index.b76c09e5.chunk.js# renderfile |
| 25 | +│├── runtime~Page.3f285250.js#no need to pay attention, provides somewebpackAPIs, equivalent tomanifest.js generated by old versions of webpack |
| 26 | +│└── vendor.92dcc0b4.chunk.js#third-party modules |
| 27 | +└── server#server-side build artifacts folder |
| 28 | + ├── Page.server.js#server-side bundle, built through the framework's underlyingserver-entrymethod |
| 29 | + └── static#this folder is not used in non-Vitelocal development scenarios, no need to pay attention |
30 | 30 | └── css |
31 | 31 | ├── Page.66b88dee.css |
32 | 32 | └── Page.css |
33 | 33 | ``` |
34 | 34 |
|
35 | | -##客户端产物类型分析详解 |
| 35 | +##Detailed Analysis of Client-Side Artifact Types |
36 | 36 |
|
37 | | -对于`client`文件夹构建出来的东西有经验的开发者会很熟悉。客户端构建产物通过[client-entry](https://github.com/zhangyuang/ssr/blob/dev/packages/plugin-vue3/src/entry/client-entry.ts)生成， 唯一的区别就是在服务端渲染场景下我们调用的框架API为`hydrate`水合模式而不是`render`普通渲染模式 |
| 37 | +Experienced developers will be familiar with what's built in the`client`folder. Client-side build artifacts are generated through[client-entry](https://github.com/zhangyuang/ssr/blob/dev/packages/plugin-vue3/src/entry/client-entry.ts). The only difference is that in server-side rendering scenarios, the frameworkAPIwe call is`hydrate`hydration mode instead of`render`normal rendering mode. |
38 | 38 |
|
39 | | -开发者可以通过`GENERATE_ANALYSIS=true npm run build`来可视化生成客户端构建产物，来判断`tree shaking`有没有生效有没有引入没有使用的文件 |
| 39 | +Developers can use`GENERATE_ANALYSIS=true npm run build`to visually generate client-side build artifacts to determine whether`tree shaking`is effective and whether unused files are introduced. |
40 | 40 |
|
41 | | -##服务产物端类型分析详解 |
| 41 | +##Detailed Analysis of Server-Side Artifact Types |
42 | 42 |
|
43 | | -这里我们着重提一下服务端构建产物中的`Page.server.js` |
| 43 | +Here we specifically mention`Page.server.js`in the server-side build artifacts. |
44 | 44 |
|
45 | | -该文件为`commonjs`格式在`Node.js`环境中被调用。由框架源码中的[server-entry](https://github.com/zhangyuang/ssr/blob/dev/packages/plugin-vue3/src/entry/server-entry.ts)文件构建而得到。该文件只会包含业务代码，也就是前端组件。由于`Node.js`环境无法直接使用`ESM`语法或识别`JSX`语法以及样式文件，所以我们需要做一层构建处理，保证构建后的产物能够在`Node.js`环境成功执行。 |
| 45 | +This file is in`commonjs`format and called in the`Node.js`environment. It's built from the[server-entry](https://github.com/zhangyuang/ssr/blob/dev/packages/plugin-vue3/src/entry/server-entry.ts)file in the framework source code. This file only contains business code, namely frontend components. Since the`Node.js`environment cannot directly use`ESM`syntax or recognize`JSX`syntax and style files, we need to do a layer of build processing to ensure that the built artifacts can be successfully executed in the`Node.js`environment. |
46 | 46 |
|
47 | | -对于服务端文件的构建我们通常会开启`externals`选项，也就是将第三方模块的依赖外置。举个例子 |
| 47 | +For server-side file builds, we usually enable the`externals`option, which means externalizing third-party module dependencies. For example: |
48 | 48 |
|
49 | 49 | ```js |
50 | | -//源码 |
| 50 | +//Source code |
51 | 51 | importReactfrom'react' |
52 | 52 |
|
53 | | -//构建后 |
| 53 | +//After build |
54 | 54 | constReact=require('react') |
55 | 55 | ``` |
56 | 56 |
|
57 | | -在构建时并不会将`react`的源码一起打包进来，而是运行时动态的从`node_modules`文件夹中加载模块。这样保证了我们服务端构建产物的体积，只包含纯业务代码也能够让我们在出错时能够迅速定位问题。但这样的方式要求我们在部署环境需要存在`node_modules`文件夹并且包含生产环境中会动态加载的所有模块。 |
| 57 | +During build time, the source code of`react`is not packaged together, but modules are dynamically loaded from the`node_modules`folder at runtime. This ensures the size of our server-side build artifacts, containing only pure business code and allowing us to quickly locate problems when errors occur. However, this approach requires the deployment environment to have a`node_modules`folder and contain all modules that will be dynamically loaded in the production environment. |
58 | 58 |
|
59 | | -###常见错误解决 |
| 59 | +###Common Error Solutions |
60 | 60 |
|
61 | | -由于我们开启了`externals`选项，这里在一些场景可能会出问题。例如我们加载的第三方模块在代码中写死了依赖的另外的模块是`ESM`格式的。例如一些第三方模块会使用`lodash-es`而不是`lodash`来运行。针对这样的依赖，我们没办法外置再去动态加载，这样会导致错误。针对这种模块格式错误的问题，或是依赖了样式文件的模块。我们仍需要处理它，将代码与服务端构建产物打包在一起。而不是运行时再去动态加载。这里我们可以通过框架提供的[whiteList](./api$config#whiteList)配置来设置需要特殊处理的模块 |
| 61 | +Since we enabled the`externals`option, this may cause problems in some scenarios. For example, the third-party modules we load have hard-coded dependencies on other modules that are in`ESM`format. For example, some third-party modules will use`lodash-es`instead of`lodash`to run. For such dependencies, we can't externalize and then dynamically load them, which would cause errors. For such module format errors, or modules that depend on style files, we still need to process them by packaging the code together with server-side build artifacts instead of dynamically loading at runtime. Here we can use the[whiteList](./api$config#whiteList)configuration provided by the framework to set modules that need special handling. |