# project-gulp

**Repository Path**: aulence/project-gulp

## Basic Information

- **Project Name**: project-gulp
- **Description**: 用于构建项目的Gulp配置
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2019-12-01
- **Last Updated**: 2024-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 用于构建项目的 Gulp 5 配置

***

## 项目介绍

该项目是基于 **Gulp.js** 的最新版本第 5 版来进行自动化构建的常规项目模版，通常用于一些简单的外包项目开发，内含新版本的 **Normalize.css** 对项目样式进行初始化。CSS 预处理使用 SCSS 进行编写，当然如果你对 Less/SCSS 这类预处理语言不熟悉，你也完全可以在“*.scss”里编写原生的 CSS 或依照现有的代码内容进行模仿编写。我们不建议在项目内加入原生 CSS 文件，因为这样会让项目的自动构建变得繁琐且难以维护管理。

本项目模版只针对简单快速的小型项目（基于敏捷型开发的项目），所以不适用与任何大型或使用任何 JS 框架的项目（这些类型的项目请使用 Webpack 来进行模块化开发以提升团队协作性和维护管理效率）。

***



## 安装教程

1. 确保您的电脑上已经有 Node.js 至少18.0以上的版本，并保证 **npm** 或 **npx** 模块处于可用状态（使用 `npm -v` 检查是否安装成功），并也处在一个较新的版本；
2. 全局安装 Gulp.js 命令工具 `npm i -g gulp-cli` 或 `cnpm i -g gulp-cli`，然后输入 `gulp -v` 检查是否安装成功；
3. 下载或使用 **Git** 工具克隆本项目到本地指定文件夹内（启动 Git Bash 工具，输入命令 `git clone git@gitee.com:aulence/project-gulp.git` 或 `git clone https://gitee.com/aulence/project-gulp.git`）；
4. 打开本项目，进入项目根目录下启动指定当前目录的命令行工具（Windows 10 操作系统用户可以按住 <kbd>Shift</kbd> + <kbd>鼠标右键</kbd>，选择“在此处打开 Powershell 窗口”。也可以用组合快捷键先 <kbd>Alt</kbd> + <kbd>F</kbd> 后接键盘的 <kbd>R</kbd> 键打开命令行窗口）；
5. 在打开的命令行内输入命令 `npm i` 或 `cnpm i` 快速地安装自动化构建所需的依赖，使用 Gulp 5 自动化构建的环境就安装完成了。

***

## 使用注意事项

1. 尽可能维持现有的文件夹结构，否则构建可能产生错误，或者构建出来的文件的引用关系也可能发生错误。
2. src 各目录下不同层级不要有同类型但同名的文件，否则 md5 文件重命名的时候可能会产生标记混淆，从而让构建出来的文件可能产生引用错误。如不要出现 src/scripts/index.js 和 src/scripts/utils/index.js 这样两个同属 src/scripts 目录下的同名文件，否则构建过程中产生的 release/rev/**/*.json 文件对 JS 文件的 md5 重命名就会出现错误的概率。



## 使用说明

### 开发阶段

如果是你处于开发阶段可以执行命令:
```powershell
gulp
```
如果之前的安装步骤没有问题，那正常情况下项目的 **src** 目录内的文件就会开始进行编译（这个目录就是我们存放开发文件的目录），并在命令行的最后几行中提供可以访问的本地服务器地址“<http://localhost:8040>”，通过该地址即可预览项目效果。如果该端口被占用了，可以进入根目录下的 **Gulpfile.js** 文件内搜索“8040”关键字进行修改并保存，然后重新运行 `gulp` 命令。

打开这个地址后，可以在编辑器内对 **src** 内对任意文件进行修改，保存文件之后浏览器端就会自动重载更改之后的内容而不用您去手动去刷新浏览器。如果你有一个很大的显示器或者有显示器分屏的话，那这个功能会提升您不少的编码效率。

这时，开发的根目录下会生成 **release** 和 **dist** 两个文件夹。**release** 是用于存放自动化构建需要对应源文件路径信息的一些 JSON 文件，而 **dist** 是构建完成的项目，该目录下虽然项目功能完整，但是不建议将其作为上线文件使用，原因后续会说明。每次执行 `gulp` 命令都会将这两个目录删除而重新生成最新的，所以我们一般不要去手动管理它们。

> 为了提升项目编译效率，在这个开发阶段我们没有对任何的 HTML、CSS、JavaScript 和图片文件进行压缩处理，只是为“*.scss”文件提供了资源映射，方便您在浏览器开发者工具中查找样式效果在源 SCSS 文件中对应的行数。
>
> 为了解决项目文件在更新后出现的文件缓存导致重载功能的无效，我们为所有的CSS和JS文件都添加了 MD5 编码作为文件名的一部分，每次更改文件保存后，在浏览器端都会自动去访问最新版本的 CSS 和 JS 文件。当然这对于需要经常更新服务器线上文件缓存的网站应用来说会特别的省心。



另外主要注意的是图片的构建处理会比较消耗时间，所以我们没有默认开启对图片文件变动的构建处理，所以当您往项目的“src/images”文件夹内添加了新的图片资源后，可以新开一个命令行窗口并使用命令 `gulp moveImgToDist`，它会自动将这些新的文件拷贝一份到项目发布文件 **dist** 目录下。



### 项目上线打包

如果您一个周期的开发工作已经完成，需要将文件传到服务器上了，千万不要用 `gulp` 命令后直接生成的**dist**，因为这里面会充斥着各种 ES6 的代码，以及未经压缩的 HTML、CSS、JS、图片、音频、视频和一些其它文件，这会让您代码的注释和网站的资源完全暴露给了所有用户，对网站的代码安全非常不利。而且未经压缩的文件体积过大，也会使得网站加载的速度变慢。所以，我们应该使用以下命令来执行全面的构建：
```powershell
gulp build
```
通过该命令构建后，发布目录 **dist** 下的所有资源都会经过压缩混淆处理，图片文件也会添加MD5码并压缩一定的体积（只限于 **src/images** 目录）。特别是对于 JS 文件而言，它不仅进行了压缩，还对里面的代码进行了混淆，让想“借用”您代码的开发者根本无从下手，如：

```javascript
/**
 * JavaScript功能
 * 日期：2019-12-1 19:08:05
 * 作者：Verning Aulence
 */
import { showIntlDateTime } from './utils/index.js';

// 全局变量
const GLOBAL = {
	author: 'Verning Aulence',
	titleName() {
		return document.querySelector('head > title').textContent;
	},
};

/**
 * 页面加载完成后执行
 */
window.addEventListener('load', () => {
	console.log(`您好，${GLOBAL.author}！`);
	console.log(`现在的时间是：${showIntlDateTime(new Date())}`);
	// 判断当前所处页面
	onthePageName(GLOBAL);
});

/**
 * 判断当前所处页面
 */
function onthePageName(global) {
	const titleName = global.titleName();
	console.log(`您当前处于“${titleName}”页面上。`);
	const navList = document.querySelectorAll('header nav li');
	switch (titleName) {
		case '网站首页':
			navList[0].querySelector('a').classList.add('active');
			break;
		case '网站子页面':
			navList[1].querySelector('a').classList.add('active');
			break;
		default:
			navList[0].querySelector('a').classList.add('active');
	}
}
```

会被编译成

```javascript
import{showIntlDateTime}from"./utils/index.js";let GLOBAL={author:"Verning Aulence",titleName(){return document.querySelector("head > title").textContent}};function onthePageName(e){var e=e.titleName(),t=(console.log(`\u60a8\u5f53\u524d\u5904\u4e8e“${e}”\u9875\u9762\u4e0a。`),document.querySelectorAll("header nav li"));switch(e){case"\u7f51\u7ad9\u9996\u9875":t[0].querySelector("a").classList.add("active");break;case"\u7f51\u7ad9\u5b50\u9875\u9762":t[1].querySelector("a").classList.add("active");break;default:t[0].querySelector("a").classList.add("active")}}window.addEventListener("load",()=>{console.log(`\u60a8\u597d\uff0c${GLOBAL.author}\uff01`),console.log("\u73b0\u5728\u7684\u65f6\u95f4\u662f\uff1a"+showIntlDateTime(new Date)),onthePageName(GLOBAL)});
```
这会让人失去任何“借用”代码的欲望（由于编译性能问题，将中文转换为Unicode功能在原配置文件 **Gulpfile.js** 中处于被注释状态，可以根据需要解除注释）。

完成这些步骤后，您就可以将目录 **dist** 手动提取出来修改为适合的名称，或将该目录内的文件传到服务器上了。



### 其它命令

```powershell
# 删除所有自动生成的目录
gulp delFile
```

```powershell
# 将图片资源拷贝到发布目录下
gulp moveImgToDist
```



## 项目更新日志

### 2024-09-19

1. chore: 删除构建包 gulp-autoprefixer 及其相关使用，防止部分 CSS 特性无效的问题
2. feat: 让子页面脚本增加 ESM 的支持
3. refactor: 重构了样式表结构和编码风格
4. refactor: 重构了全局公共脚本和模块化的引用
5. chore: 减小了 logo 的尺寸
6. feat: 优化了 short-tips 插件的易用性和样式表现
7. fix: JS 文件以 common 命名会编译错误，已改为 common-script
8. feat: 增加了社交媒体网站分享时的图文信息内容的展示配置
9. chore: 删除了不在受 node 支持的 node-sass 依赖


### 2024-09-26

1. feat: 现在对 ESM 开发获得更好的体验
2. feat: JS 文件以及 JS 模块文件的缓存会得到更好的更新
3. feat: 丰富了文件结构，styles 文件目录内新增 module-styles 目录，支持细化样式模块
4. style: 调整了全局代码的样式规范
5. feat: 调整了首页和子页面的样式表现
6. feat: 完成相册查看共鞥和模态框的样式规范升级