Skip to content

Commit

Permalink
docs: add warning about hmr fails when filename has hash (#8917)
Browse files Browse the repository at this point in the history 
Co-authored-by: neverland <[email protected]>
  • Loading branch information
@LingyuCoder @chenjiahan
LingyuCoder and chenjiahan authored Jan 2, 2025
1 parent 46e8278 commit cfbbccc
Show file tree
Hide file tree
Showing 2 changed files with 63 additions and 51 deletions.
56 changes: 31 additions & 25 deletions website/docs/en/config/output.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -506,51 +506,51 @@ The template string below can be used to replace the corresponding file name. Di

Content that can be replaced at the compilation level.

| Template | Description |
| ---------- | ------------------------ |
| [fullhash] | full hash of compilation |
| Template | Description |
| ------------ | ------------------------ |
| `[fullhash]` | full hash of compilation |

### Chunk Context

Content that can be replaced at the chunk level.

| template | description |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [id] | The current chunk id |
| [name] | Use name when chunk name exists, otherwise use chunk id |
| [chunkhash] | The hash value of the chunk, computed from all elements of type in the current chunk |
| [contenthash] | The hash value of the chunk, computed from the elements that contain only the content of that type. For example, if a module of type JavaScript is generated, only the hash of all JavaScript-typed modules in the current chunk is used. |
| template | description |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[id]` | The current chunk id |
| `[name]` | Use name when chunk name exists, otherwise use chunk id |
| `[chunkhash]` | The hash value of the chunk, computed from all elements of type in the current chunk |
| `[contenthash]` | The hash value of the chunk, computed from the elements that contain only the content of that type. For example, if a module of type JavaScript is generated, only the hash of all JavaScript-typed modules in the current chunk is used. |

### Module Context

Content that can be replaced at the module level.

| Template | Description |
| ------------- | ---------------------- |
| [id] | The id of the module |
| [hash] | The hash of the module |
| [contenthash] | hash of module content |
| Template | Description |
| --------------- | ---------------------- |
| `[id]` | The id of the module |
| `[hash]` | The hash of the module |
| `[contenthash]` | hash of module content |

### File Context

Content that can be replaced at the file level.

| Template | Description |
| ---------- | --------------------------------------------------------------------------------- |
| [file] | Filename and path, without query or fragment |
| [query] | Query with leading `?` |
| [fragment] | Fragment with leading `#` |
| [base] | Only filename (including extensions), without path |
| [filebase] | Same, but deprecated |
| [path] | Only path, without filename |
| [name] | Only filename without extension or path |
| [ext] | Extension with leading `.` (not available for [output.filename](#outputfilename)) |
| Template | Description |
| ------------ | --------------------------------------------------------------------------------- |
| `[file]` | Filename and path, without query or fragment |
| `[query]` | Query with leading `?` |
| `[fragment]` | Fragment with leading `#` |
| `[base]` | Only filename (including extensions), without path |
| `[filebase]` | Same, but deprecated |
| `[path]` | Only path, without filename |
| `[name]` | Only filename without extension or path |
| `[ext]` | Extension with leading `.` (not available for [output.filename](#outputfilename)) |

Substitutions available on URL-level:

| Template | Description |
| -------- | ----------- |
| [url] | URL |
| `[url]` | URL |

:::tip

Expand Down Expand Up @@ -597,6 +597,12 @@ type ModulePathData = {
};
```

:::warning
When developing locally, it's recommended to avoid using hash values in filenames.

This is because entry files and chunks split by [`optimization.splitChunks`](/plugins/webpack/split-chunks-plugin) are loaded via `<script>` tags in HTML files. If filenames contain hash values, HMR will not work as HTML files cannot be dynamically loaded.
:::

## output.globalObject

- **Type:** `string`
Expand Down
58 changes: 32 additions & 26 deletions website/docs/zh/config/output.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -503,50 +503,50 @@ module.exports = {

可在 compilation 层面替换的内容

| 模板 | 描述 |
| ---------- | ----------------------- |
| [fullhash] | compilation 的完整 hash |
| 模板 | 描述 |
| ------------ | ----------------------- |
| `[fullhash]` | compilation 的完整 hash |

### Chunk Context

可在 chunk 层面替换的内容：

| 模板 | 描述 |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [id] | 当前 chunk id |
| [name] | 当 chunk name 存在则使用名称，否则使用 chunk id |
| [chunkhash] | chunk 的 hash 值，通过当前 chunk 中所有类型的元素计算所得 |
| [contenthash] | chunk 的 hash 值，通过只包含该类型内容的元素计算所得。如：生成 JavaScript 类型的文件则只会使用当前 chunk 中所有 JavaScript 模块计算所得的 hash |
| 模板 | 描述 |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `[id]` | 当前 chunk id |
| `[name]` | 当 chunk name 存在则使用名称，否则使用 chunk id |
| `[chunkhash]` | chunk 的 hash 值，通过当前 chunk 中所有类型的元素计算所得 |
| `[contenthash]` | chunk 的 hash 值，通过只包含该类型内容的元素计算所得。如：生成 JavaScript 类型的文件则只会使用当前 chunk 中所有 JavaScript 模块计算所得的 hash |

### Module Context

可在 module 层面替换的内容：

| 模板 | 描述 |
| ------------- | --------------- |
| [id] | 模块的 id |
| [hash] | 模块的 hash |
| [contenthash] | 模块内容的 hash |
| 模板 | 描述 |
| --------------- | --------------- |
| `[id]` | 模块的 id |
| `[hash]` | 模块的 hash |
| `[contenthash]` | 模块内容的 hash |

### File Context

可在 file 层面替换的内容：

| 模板 | 描述 |
| ---------- | --------------------------------------------------------------------------------------------- |
| [file] | 文件名和路径，不包括查询或片段 |
| [query] | 文件 query，包含 `?` |
| [fragment] | 以 `#` 开头的片段名 |
| [base] | 只翻译文件名（包括扩展名），不包括路径名 |
| [path] | 文件路径，不包含文件名 |
| [name] | 文件名，不包含扩展名和文件路径 |
| [ext] | 扩展名，包含 `.` （仅支持在 [output.assetModuleFilename](#outputassetmodulefilename) 里使用） |
| 模板 | 描述 |
| ------------ | --------------------------------------------------------------------------------------------- |
| `[file]` | 文件名和路径，不包括查询或片段 |
| `[query]` | 文件 query，包含 `?` |
| `[fragment]` | 以 `#` 开头的片段名 |
| `[base]` | 只翻译文件名（包括扩展名），不包括路径名 |
| `[path]` | 文件路径，不包含文件名 |
| `[name]` | 文件名，不包含扩展名和文件路径 |
| `[ext]` | 扩展名，包含 `.` （仅支持在 [output.assetModuleFilename](#outputassetmodulefilename) 里使用） |

在 URL 级别上可用的替换：

| 模板 | 描述 |
| ----- | ---- |
| [url] | URL |
| 模板 | 描述 |
| ------- | ---- |
| `[url]` | URL |

:::tip

Expand Down Expand Up @@ -591,6 +591,12 @@ type ModulePathData = {
};
```

:::warning
在进行本地开发时，建议避免在文件名中使用 hash 值。

这是因为入口文件以及被 [`optimization.splitChunks`](/plugins/webpack/split-chunks-plugin) 拆分出的 chunks 都会通过 HTML 文件中的 `<script>` 标签进行加载。此时若文件名内包含 hash 值，则会由于 HTML 无法被动态加载而使得热更新失效。
:::

## output.globalObject

- **类型：** `string`
Expand Down

0 comments on commit cfbbccc

Please sign in to comment.