函数 JAVA SCRIPT 函数

js.Build

语法

js.Build [OPTIONS] RESOURCE

返回值

resource.Resource

js.Build 函数使用 evanw/esbuild 包来

  • 捆绑
  • 转译 (TypeScript 和 JSX)
  • 树形摇晃
  • 最小化
  • 创建源映射
{{ with resources.Get "js/main.js" }}
  {{ if hugo.IsDevelopment }}
    {{ with . | js.Build }}
      <script src="{{ .RelPermalink }}"></script>
    {{ end }}
  {{ else }}
    {{ $opts := dict "minify" true }}
    {{ with . | js.Build $opts | fingerprint }}
      <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script>
    {{ end }}
  {{ end }}
{{ end }}

选项

targetPath
（string）如果未设置，则源路径将用作基本目标路径。请注意，如果目标 MIME 类型不同，则目标路径的扩展名可能会更改，例如，当源是 TypeScript 时。
format
（string）输出格式。以下之一：iife、cjs、esm。默认值为 iife，一个自执行函数，适合作为 <script> 标签包含。
params
（map 或 slice）可以在 JS 文件中作为 JSON 导入的参数，例如
{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}

然后在您的 JS 文件中

import * as params from '@params';

请注意，这是为小型数据集设计的，例如配置设置。对于较大的数据，请将文件放入 assets 中并直接导入它们。

minify
（bool）让 js.Build 处理最小化。
loaders
（map）v0.140.0 版本中的新功能 为给定文件类型配置加载器允许您使用 import 语句或 require 调用加载该文件类型。例如，将 .png 文件扩展名配置为使用 data URL 加载器意味着导入 .png 文件会为您提供一个包含该图像内容的 data URL。可用的加载器有 none、base64、binary、copy、css、dataurl、default、empty、file、global-css、js、json、jsx、local-css、text、ts、tsx。请参阅 https://esbuild.org.cn/api/#loader
inject
（slice）此选项允许您自动将全局变量替换为从另一个文件导入的内容。路径名必须相对于 assets。请参阅 https://esbuild.org.cn/api/#inject
shims
（map）此选项允许用另一个组件替换一个组件。一个常见的用例是从 CDN（使用 *shims*）加载诸如 React 之类的依赖项（当在生产环境中时），但在开发期间使用完全捆绑的 node_modules 依赖项运行
{{ $shims := dict "react" "js/shims/react.js"  "react-dom" "js/shims/react-dom.js" }}
{{ $js = $js | js.Build dict "shims" $shims }}

shim 文件可能如下所示

// js/shims/react.js
module.exports = window.React;

// js/shims/react-dom.js
module.exports = window.ReactDOM;

使用以上内容，这些导入应该在两种场景中都有效

import * as React from 'react';
import * as ReactDOM from 'react-dom/client';
target
（string）语言目标。以下之一：es5、es2015、es2016、es2017、es2018、es2019、es2020 或 esnext。默认值为 esnext。
platform v0.140.0 版本中的新功能
（string）browser、node、neutral 之一。默认值为 browser。请参阅 https://esbuild.org.cn/api/#platform
externals
（slice）外部依赖项。使用此选项来修剪您知道永远不会执行的依赖项。请参阅 https://esbuild.org.cn/api/#external
defines
（map）允许定义一组要在构建时执行的字符串替换。应该是一个映射，其中每个键都将被其值替换。
{{ $defines := dict "process.env.NODE_ENV" `"development"` }}
sourceMap
（string）是否从 esbuild 生成 inline、linked 或 external 源映射。链接和外部源映射将写入到目标，输出文件名 + “.map”。当 linked 时，sourceMappingURL 也会写入输出文件。默认情况下，不创建源映射。请注意，linked 选项是在 Hugo 0.140.0 中添加的。
sourcesContent v0.140.0 版本中的新功能
（bool）是否在源映射中包含源文件的内容。默认情况下，这是 true。
JSX v0.124.0 版本中的新功能
（string）如何处理/转换 JSX 语法。以下之一：transform、preserve、automatic。默认值为 transform。值得注意的是，automatic 转换是在 React 17+ 中引入的，将导致自动导入必要的 JSX 帮助函数。请参阅 https://esbuild.org.cn/api/#jsx
JSXImportSource v0.124.0 版本中的新功能
（string）使用哪个库自动导入其 JSX 帮助函数。只有在 JSX 设置为 automatic 时才有效。指定的库需要通过 npm 安装并公开某些导出。请参阅 https://esbuild.org.cn/api/#jsx-import-source

如果您想使用非 React JSX 库（如 Preact），则 JSX 和 JSXImportSource 的组合非常有用，例如

{{ $js := resources.Get "js/main.jsx" | js.Build (dict "JSX" "automatic" "JSXImportSource" "preact") }}

使用以上内容，您可以使用 Preact 组件和 JSX，而无需每次都手动导入 h 和 Fragment

import { render } from 'preact';

const App = () => <>Hello world!</>;

const container = document.getElementById('app');
if (container) render(<App />, container);

从 assets 目录导入 JS 代码

js.Build 完全支持 Hugo 模块 中的虚拟联合文件系统。您可以在这个测试项目中看到一些简单的示例，但简而言之，这意味着您可以执行此操作

import { hello } from 'my/module';

它将解析为分层文件系统中 assets/my/module 内的最顶层的 index.{js,ts,tsx,jsx}。

import { hello3 } from 'my/module/hello3';

将解析为 assets/my/module 内的 hello3.{js,ts,tsx,jsx}。

任何以 . 开头的导入都相对于当前文件解析

import { hello4 } from './lib';

对于其他文件（例如 JSON、CSS），您需要使用包含任何扩展名的相对路径，例如

import * as data from 'my/module/data.json';

assets 之外的文件中的任何导入，或者无法解析为 assets 内组件的任何导入，都将由 ESBuild 解析，其中项目目录作为解析目录（用作查找 node_modules 等的起点）。另请参阅 hugo mod npm pack。如果您的项目中有任何导入的 npm 依赖项，则需要确保在运行 hugo 之前运行 npm install。

另请注意新的 params 选项，该选项可以从模板传递到您的 JS 文件，例如

{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}

然后在您的 JS 文件中

import * as params from '@params';

Hugo 默认会生成一个 assets/jsconfig.json 文件，用于映射导入。这对于代码编辑器中的导航/智能感知功能很有用，但如果您不需要/不想要它，您可以关闭它。

Node.js 依赖

使用 js.Build 函数来包含 Node.js 依赖。

任何在 assets 目录之外的文件中的导入，或者任何无法解析为 assets 目录内的组件的导入，都将由 esbuild 解析，解析时会使用项目目录作为解析目录（作为查找 node_modules 等的起始点）。另请参阅 hugo mod npm pack。如果您的项目中有任何导入的 npm 依赖，您需要在运行 hugo 之前确保运行 npm install。

解析 npm 包（也即位于 node_modules 目录中的包）的起始目录始终是主项目目录。

示例 

{{ $built := resources.Get "js/index.js" | js.Build "main.js" }}

或者带有选项

{{ $externals := slice "react" "react-dom" }}
{{ $defines := dict "process.env.NODE_ENV" `"development"` }}

{{ $opts := dict "targetPath" "main.js" "externals" $externals "defines" $defines }}
{{ $built := resources.Get "scripts/main.js" | js.Build $opts }}
<script src="{{ $built.RelPermalink }}" defer></script>

另请参阅

最后更新时间：2025 年 1 月 16 日: 将目录名、文件名和文件路径格式化为代码 (8051ff818)
改进此页面