Skip to content

init translation of gulp #76

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 13, 2024
Merged

init translation of gulp #76

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bd666bf
init translation of gulp
hanyujie2002 May 19, 2024
6828a65
Merge branch 'main' into gulp
awxiaoxian2020 May 23, 2024
4e70704
Merge branch 'main' into gulp
awxiaoxian2020 May 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 64 additions & 96 deletions docs/documentation/zh/tutorials/Gulp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,75 +2,67 @@
title: Gulp
layout: docs
permalink: /zh/docs/handbook/gulp.html
oneline: Using TypeScript with Gulp
oneline: 使用 Gulp 和 TypeScript
deprecated: true
---

This quick start guide will teach you how to build TypeScript with [gulp](https://gulpjs.com) and then add [Browserify](https://browserify.org), [terser](https://terser.org), or [Watchify](https://github.com/substack/watchify) to the gulp pipeline.
This guide also shows how to add [Babel](https://babeljs.io/) functionality using [Babelify](https://github.com/babel/babelify).
这个快速入门指南将教你如何使用 [gulp](https://gulpjs.com) 构建 TypeScript 项目，并将 [Browserify](https://browserify.org)、[terser](https://terser.org) 或 [Watchify](https://github.com/substack/watchify) 添加到 gulp 流程中。本指南还展示了如何使用 [Babelify](https://github.com/babel/babelify) 添加 [Babel](https://babeljs.io/) 功能。

We assume that you're already using [Node.js](https://nodejs.org/) with [npm](https://www.npmjs.com/).
我们假设你使用的是 [Node.js](https://nodejs.org/) 和 [npm](https://www.npmjs.com/)。

## Minimal project
## 最小项目

Let's start out with a new directory.
We'll name it `proj` for now, but you can change it to whatever you want.
让我们从建立新目录开始。我们暂且将其命名为 `proj`，但你可以根据需要进行修改。

```shell
mkdir proj
cd proj
```

To start, we're going to structure our project in the following way:
首先，我们将按照以下方式组织我们的项目：

```
proj/
├─ src/
└─ dist/
```

TypeScript files will start out in your `src` folder, run through the TypeScript compiler and end up in `dist`.
TypeScript 文件将始于你的 `src` 文件夹，经过 TypeScript 编译器处理后最终将位于 `dist` 文件夹。

Let's scaffold this out:
让我们创建这些文件夹：

```shell
mkdir src
mkdir dist
```

### Initialize the project
### 初始化项目

Now we'll turn this folder into an npm package.
接下来，我们将把这个文件夹转换为 npm 包。

```shell
npm init
```

You'll be given a series of prompts.
You can use the defaults except for your entry point.
For your entry point, use `./dist/main.js`.
You can always go back and change these in the `package.json` file that's been generated for you.
你将会得到一系列提示。你可以使用默认值，只需修改入口点。对于入口点，请使用 `./dist/main.js`。你随后可以随时返回并在生成的 `package.json` 文件中进行修改。

### Install our dependencies
### 安装依赖项

Now we can use `npm install` to install packages.
First install `gulp-cli` globally (if you use a Unix system, you may need to prefix the `npm install` commands in this guide with `sudo`).
现在我们可以使用 `npm install` 来安装包。首先全局安装 `gulp-cli`（如果你使用的是 Unix 系统，可能需要在本指南中的 `npm install` 命令前加上 `sudo`）。

```shell
npm install -g gulp-cli
```

Then install `typescript`, `gulp` and `gulp-typescript` in your project's dev dependencies.
[Gulp-typescript](https://www.npmjs.com/package/gulp-typescript) is a gulp plugin for TypeScript.
然后在你的项目的开发依赖中安装 `typescript`、`gulp` 和 `gulp-typescript`。[Gulp-typescript](https://www.npmjs.com/package/gulp-typescript) 是一个用于 TypeScript 的 gulp 插件。

```shell
npm install --save-dev typescript [email protected] gulp-typescript
```

### Write a simple example
### 编写一个简单的示例

Let's write a Hello World program.
In `src`, create the file `main.ts`:
让我们编写 Hello World 程序。在 `src` 目录下创建文件 `main.ts`：

```ts
function hello(compiler: string) {
Expand All @@ -79,7 +71,7 @@ function hello(compiler: string) {
hello("TypeScript");
```

In the project root, `proj`, create the file `tsconfig.json`:
在项目根目录（`proj`）下，创建文件 `tsconfig.json`：

```json tsconfig
{
Expand All @@ -91,9 +83,9 @@ In the project root, `proj`, create the file `tsconfig.json`:
}
```

### Create a `gulpfile.js`
### 创建 `gulpfile.js`

In the project root, create the file `gulpfile.js`:
在项目根目录下，创建文件 `gulpfile.js`：

```js
var gulp = require("gulp");
Expand All @@ -105,37 +97,36 @@ gulp.task("default", function () {
});
```

### Test the resulting app
### 测试生成的应用程序

```shell
gulp
node dist/main.js
```

The program should print "Hello from TypeScript!".
该程序应该会输出“Hello from TypeScript!”。

## Add modules to the code
## 向代码添加模块

Before we get to Browserify, let's build our code out and add modules to the mix.
This is the structure you're more likely to use for a real app.
在我们开始使用 Browserify 之前，让我们扩展我们的代码并添加模块。这是你在实际应用程序中更有可能使用的结构。

Create a file called `src/greet.ts`:
创建一个名为 `src/greet.ts` 的文件：

```ts
export function sayHello(name: string) {
return `Hello from ${name}`;
}
```

Now change the code in `src/main.ts` to import `sayHello` from `greet.ts`:
现在将 `src/main.ts` 中的代码更改为从 `greet.ts` 导入 `sayHello`：

```ts
import { sayHello } from "./greet";

console.log(sayHello("TypeScript"));
```

Finally, add `src/greet.ts` to `tsconfig.json`:
最后，将 `src/greet.ts` 添加到 `tsconfig.json`：

```json tsconfig
{
Expand All @@ -147,35 +138,28 @@ Finally, add `src/greet.ts` to `tsconfig.json`:
}
```

Make sure that the modules work by running `gulp` and then testing in Node:
通过运行 `gulp` 并在 Node 中进行测试，确保模块能够正常工作：

```shell
gulp
node dist/main.js
```

Notice that even though we used ES2015 module syntax, TypeScript emitted CommonJS modules that Node uses.
We'll stick with CommonJS for this tutorial, but you could set `module` in the options object to change this.
请注意，即使我们使用了 ES2015 的模块语法，TypeScript 也会生成 Node 使用的 CommonJS 模块。在本教程中，我们将继续使用 CommonJS，但你可以通过在选项对象中设置 `module` 来进行更改。

## Browserify

Now let's move this project from Node to the browser.
To do this, we'd like to bundle all our modules into one JavaScript file.
Fortunately, that's exactly what Browserify does.
Even better, it lets us use the CommonJS module system used by Node, which is the default TypeScript emit.
That means our TypeScript and Node setup will transfer to the browser basically unchanged.
现在让我们将这个项目从 Node 移植到浏览器中。为了做到这一点，我们希望将所有的模块捆绑到单个 JavaScript 文件中。幸运的是，这正是 Browserify 所做的。更好的是，它允许我们使用 Node 所使用的 CommonJS 模块系统，这也是 TypeScript 的默认输出。这意味着我们的 TypeScript 和 Node 设置基本上可以无缝迁移到浏览器中。

First, install browserify, [tsify](https://www.npmjs.com/package/tsify), and vinyl-source-stream.
tsify is a Browserify plugin that, like gulp-typescript, gives access to the TypeScript compiler.
vinyl-source-stream lets us adapt the file output of Browserify back into a format that gulp understands called [vinyl](https://github.com/gulpjs/vinyl).
首先，安装 browserify、[tsify](https://www.npmjs.com/package/tsify) 和 vinyl-source-stream。tsify 是 Browserify 的一个插件，与 gulp-typescript 类似，可以访问 TypeScript 编译器。vinyl-source-stream 让我们能够将 Browserify 的文件输出适配回 gulp 可以理解的一种格式，这种格式名为 [vinyl](https://github.com/gulpjs/vinyl)。

```shell
npm install --save-dev browserify tsify vinyl-source-stream
```

### Create a page
### 创建一个页面

Create a file in `src` named `index.html`:
在 `src` 目录下创建一个名为 `index.html` 的文件：

```html
<!DOCTYPE html>
Expand All @@ -191,7 +175,7 @@ Create a file in `src` named `index.html`:
</html>
```

Now change `main.ts` to update the page:
现在修改 `main.ts` 来更新页面内容：

```ts
import { sayHello } from "./greet";
Expand All @@ -204,8 +188,7 @@ function showHello(divName: string, name: string) {
showHello("greeting", "TypeScript");
```

Calling `showHello` calls `sayHello` to change the paragraph's text.
Now change your gulpfile to the following:
调用 `showHello` 函数会调用 `sayHello` 函数来改变段落的文本内容。现在修改你的 gulpfile 如下所示：

```js
var gulp = require("gulp");
Expand Down Expand Up @@ -238,43 +221,39 @@ gulp.task(
);
```

This adds the `copy-html` task and adds it as a dependency of `default`.
That means any time `default` is run, `copy-html` has to run first.
We've also changed `default` to call Browserify with the tsify plugin instead of gulp-typescript.
Conveniently, they both allow us to pass the same options object to the TypeScript compiler.
这里添加了 `copy-html` 任务，并将其作为 `default` 的依赖项。这意味着每次运行 `default` 任务时，必须首先运行 `copy-html` 任务。我们还将 `default` 修改为使用带有 tsify 插件的 Browserify 调用，而不是使用 gulp-typescript。方便的是，它们都允许我们将相同的选项对象传递给 TypeScript 编译器。

After calling `bundle` we use `source` (our alias for vinyl-source-stream) to name our output bundle `bundle.js`.
在调用 `bundle` 后，我们使用 `source`（我们为 vinyl-source-stream 设置的别名）将输出包命名为 `bundle.js`。

Test the page by running gulp and then opening `dist/index.html` in a browser.
You should see "Hello from TypeScript" on the page.
通过运行 gulp 并在浏览器中打开 `dist/index.html` 来测试页面。你应该在页面上看到“Hello from TypeScript”。

Notice that we specified `debug: true` to Browserify.
This causes tsify to emit source maps inside the bundled JavaScript file.
Source maps let you debug your original TypeScript code in the browser instead of the bundled JavaScript.
You can test that source maps are working by opening the debugger for your browser and putting a breakpoint inside `main.ts`.
When you refresh the page the breakpoint should pause the page and let you debug `greet.ts`.
注意我们在 Browserify 中指定了 `debug: true`。这会导致 tsify 在打包的 JavaScript 文件中生成源映射。源映射允许你在浏览器中调试原始的 TypeScript 代码，而不是打包后的 JavaScript 代码。你可以通过打开浏览器的调试器，并在 `main.ts` 中设置断点来测试源映射是否正常工作。当你刷新页面时，断点应该会暂停页面，并让你调试 `greet.ts` 文件。

## Watchify, Babel, and Terser
## Watchify、Babel 以及 Terser

Now that we are bundling our code with Browserify and tsify, we can add various features to our build with browserify plugins.
现在我们正在使用 Browserify 和 tsify 来打包代码，我们可以通过 browserify 插件添加各种特性到我们的构建过程中。

- Watchify starts gulp and keeps it running, incrementally compiling whenever you save a file.
This lets you keep an edit-save-refresh cycle going in the browser.
- Watchify 启动 gulp 并保持其运行，每当你保存文件时，它会进行增量编译。这使得你可以在浏览器中保持编辑-保存-刷新的循环进行。

- Babel is a hugely flexible compiler that converts ES2015 and beyond into ES5 and ES3.
This lets you add extensive and customized transformations that TypeScript doesn't support.
- Babel 是一个非常灵活的编译器，可以将 ES2015 及更高版本转换为 ES5 和 ES3。这使你可以添加广泛且定制化的转换，而 TypeScript 不支持这些转换。

- Terser compacts your code so that it takes less time to download.
- Terser 可以压缩你的代码，以减少下载时间。

### Watchify

We'll start with Watchify to provide background compilation:
我们将从 Watchify 开始，以提供后台编译功能：

```shell
npm install --save-dev watchify fancy-log
```

Now change your gulpfile to the following:
现在将你的 gulpfile 修改为以下内容：

```shell
npm install --save-dev watchify fancy-log
```

现在将你的 gulpfile 改为以下内容：

```js
var gulp = require("gulp");
Expand Down Expand Up @@ -314,19 +293,15 @@ watchedBrowserify.on("update", bundle);
watchedBrowserify.on("log", fancy_log);
```

There are basically three changes here, but they require you to refactor your code a bit.
这里基本上有三个变化，但它们需要你对代码进行一些重构。

1. We wrapped our `browserify` instance in a call to `watchify`, and then held on to the result.
2. We called `watchedBrowserify.on('update', bundle);` so that Browserify will run the `bundle` function every time one of your TypeScript files changes.
3. We called `watchedBrowserify.on('log', fancy_log);` to log to the console.
1. 我们将 `browserify` 实例包装在 `watchify` 的调用中，并将结果保存下来。
2. 我们调用 `watchedBrowserify.on('update', bundle);`，这样当你的任何一个 TypeScript 文件发生更改时，Browserify 将运行 `bundle` 函数。
3. 我们调用 `watchedBrowserify.on('log', fancy_log);` 将日志记录到控制台中。

Together (1) and (2) mean that we have to move our call to `browserify` out of the `default` task.
And we have to give the function for `default` a name since both Watchify and Gulp need to call it.
Adding logging with (3) is optional but very useful for debugging your setup.
通过 (1) 和 (2)，我们需要将对 `browserify` 的调用移出 `default` 任务。并且我们需要给 `default` 函数一个名称，因为 Watchify 和 Gulp 都需要调用它。添加 (3) 的日志记录是可选的，但对于调试你的设置非常有用。

Now when you run Gulp, it should start and stay running.
Try changing the code for `showHello` in `main.ts` and saving it.
You should see output that looks like this:
现在当你运行 Gulp 时，它应该开始运行并保持运行状态。尝试更改 `main.ts` 中的 `showHello` 函数的代码并保存它。你应该会看到类似以下的输出：

```shell
proj$ gulp
Expand All @@ -342,14 +317,13 @@ proj$ gulp

### Terser

First install Terser.
Since the point of Terser is to mangle your code, we also need to install vinyl-buffer and gulp-sourcemaps to keep sourcemaps working.
首先安装 Terser。由于 Terser 的用途是混淆你的代码，我们还需要安装 vinyl-buffer 和 gulp-sourcemaps 来保持源映射的工作。

```shell
npm install --save-dev gulp-terser vinyl-buffer gulp-sourcemaps
```

Now change your gulpfile to the following:
现在将你的 gulpfile 修改为以下内容：

```js
var gulp = require("gulp");
Expand Down Expand Up @@ -389,9 +363,7 @@ gulp.task(
);
```

Notice that `terser` itself has just one call &mdash; the calls to `buffer` and `sourcemaps` exist to make sure sourcemaps keep working.
These calls give us a separate sourcemap file instead of using inline sourcemaps like before.
Now you can run Gulp and check that `bundle.js` does get minified into an unreadable mess:
请注意，`terser` 本身只有一个调用，`buffer` 和 `sourcemaps` 的调用是为了确保源映射继续工作。这些调用使我们获得了一个单独的源映射文件，而不是像之前那样使用内联源映射。现在可以运行 Gulp，并检查 `bundle.js` 是否被压缩成一个难以阅读的混乱代码：

```shell
gulp
Expand All @@ -400,15 +372,13 @@ cat dist/bundle.js

### Babel

First install Babelify and the Babel preset for ES2015.
Like Terser, Babelify mangles code, so we'll need vinyl-buffer and gulp-sourcemaps.
By default Babelify will only process files with extensions of `.js`, `.es`, `.es6` and `.jsx` so we need to add the `.ts` extension as an option to Babelify.
首先安装 Babelify 和 ES2015 的 Babel preset。与 Terser 类似，Babelify 会混淆代码，因此我们需要 vinyl-buffer 和 gulp-sourcemaps。默认情况下，Babelify 只会处理带有 `.js`、`.es`、`.es6` 和 `.jsx` 扩展名的文件，所以我们需要将 `.ts` 扩展名添加为 Babelify 的选项。

```shell
npm install --save-dev babelify@8 babel-core babel-preset-es2015 vinyl-buffer gulp-sourcemaps
```

Now change your gulpfile to the following:
现在将你的 gulpfile 修改为以下内容：

```js
var gulp = require("gulp");
Expand Down Expand Up @@ -450,9 +420,7 @@ gulp.task(
);
```

We also need to have TypeScript target ES2015.
Babel will then produce ES5 from the ES2015 code that TypeScript emits.
Let's modify `tsconfig.json`:
我们还需要将 TypeScript 的目标设置为 ES2015。然后，Babel 将根据 TypeScript 生成的 ES2015 代码生成 ES5 代码。让我们修改 `tsconfig.json` 文件：

```json tsconfig
{
Expand All @@ -464,4 +432,4 @@ Let's modify `tsconfig.json`:
}
```

Babel's ES5 output should be very similar to TypeScript's output for such a simple script.
对于这样一个简单的脚本，Babel 生成的 ES5 输出应该与 TypeScript 的输出非常相似。
Loading