node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

Yworkshell

起点改造 前端构建服务工具

注意

正在进行npm服务化改造,环境依赖很多,脚手架服务开发中

About

基于Gulp(v4.0),配合起点Node服务框架的本地模板构建工具。

功能特性

  • 自动化流程
    • Sass > CSS
    • JS压缩和eslint检查
    • CSS Sprite精灵图自动生成
    • 图片自动优化(压缩体积)
    • 去缓存文件Reversion(递增版本号)
    • 静态资源Combo

快速开始

首先请根据你的系统安装Node.js环境。

  • 下载安装
    1. git clone http://git.code.oa.com/qidian_proj/Qidian.git 或者svn checkout具体的项目仓库
    2. 进入项目文件夹目录,执行npm install -g ,若日志提示permission denied 权限的问题,请执行sudo npm install

注意

Windows用户请使用cmber或者git bash等终端,原声的CMD太弱了缺失许多linux命令,可能会导致一些任务处理失败。

初始

请注意配置.yconfig文件,在这里可以配置项目对应的静态资源文件夹路径,本地调试所需的端口等。

构建工具目录结构

QidianViewsTool/
├── gulp           // Gulp 任务目录
│   ├── build.js      // gulp build
│   ├── clean.js    // gulp clean folder and files
│   ├── combo.js       // gulp combo
│   ├── deploy.js       // gulp zip
│   ├── images.js // gulp images
│   ├── javascript.js // gulp sprites
│   ├── sass.js    // gulp sass
│   ├── sprites.js  // gulp sprites (to modified)
│   │
│   │
│   ├── hash-tag-map
│   │   ├──rev-manifest.json // 静态资源hash映射表
│   │   └──rev-verionId.json //静态资源增量版本号映射表
├── package.json // 任务package.json
└── src            // 项目目录,详见下述项目结构 ↓↓↓
│   ├── json
│   ├── node-config
│   ├── static
│    └── views // gulp配置入口
├── .yconfig  // 构建工具基础配置
├── .csscombo.json // gulp-csscombo 配置文件
├── .eslintrc  // eslint 配置文件
├── .gitignore // git忽略文件
├── gulpfile.js // gulp任务流配置
├── index.js // 本地服务入口
├── package.json // 项目说明和依赖
├── README.md // 说明文档

开发项目目录结构

src/                          // 项目目录
├── src                           // 源文件目录
│   ├── json                       // 模拟调试后台通信cgi和ajax接口目录
│   │ ├──ajax // 本地模拟ajax
│   │ └──page // 本地模拟cgi
│   │ ├── ajaxmap.js // ajax GET请求映射config
│   │ ├── ajaxpostmap.js ajax POST请求映射config
│   │
│   ├── node-config // **重要** Node框架机所依赖的config
│   │ ├── domain_alias.js // 设置域名别名,框架机会根据header hosts头处理映射逻辑
│   │ ├── dynamic_routermap.js   // Dynamic框架机路由映射config
│   │ ├── static_routermap.js  //  Static框架机API和生成html路径映射config
│   │ ├── local_dev_routermap.js // 本地调试动态和静态混合使用的路由config
│   │ ├── minify.js // 服务端渲染 html 压缩级别config
│   │ ├── server.js // 框架机环境、L5、资源路径等config
├── static                           // 静态资源开发路径, `gulp watch {.sass,.css.js}`会监听此目录下的文件
│   ├── qd  // 该目录资源对应线上 qidian.gtimg.com/qd/ 路径
│   │ ├── css // .sass 文件存放路径
│   │ ├── images // 静态图片资源存放路径
│   │ ├── js // 静态资源存放路径
├── views                          // 生产目录,具体的项目模板文件
 │   │  ├── rank.qidian.com
│   │ ├── free.qidian.com
│   │ ├── all.qidian.com
│   │ ├── index.html
├──  ├── list.html

任务说明

注1:./src 为源文件(开发目录),/build 目录为流程自动生成的临时目录。 注2:./_prelease_previews分别为发布之前自动生成的静态资源目录EJS模板目录。 注3:_/tmp为本地模拟server路径的临时目录

1. 初始化任务 npm run init 执行npm init,初始化项目,第一次会先编译和处理所有的静态资源文件,把src开发目录的相关资源经过编译和处理后生成到build目录,此时构建工具会在:3234端口开启一个本地服务,你可以通过localhost:3234访问配置路由的页面。

2.生成不使用combo的模板文件npm run nocombo-publish

执行npm run nocombo-publish,会依次执行

  • gulp clean: 清理./_prelease,./_previews,_/tmp目录下的所有资源
  • gulp build: sass转css,js检查和压缩,复制其他静态资源,在build目录生成本地调试使用的相关文件。
  • gulp revbuild目录下的所有静态资源,通过hash计算,增量生成版本号,在hash-tag-map目录下生成hash和版本号映射表。
  • gulp rev-fix.css.js文件中所有涉及相关静态资源的url路径均替换成版本号后的新url。
  • gulp rev-views 将把views目录下的所有html模板中的静态资源替换成增加了版本号的新url

3.生成使用combo的模板文件npm run publish

在上述nocombo-publish之后,增加一步gulp combo的处理流程,自动将单独的css和js url变成一个combo url。

预览

1.普通开发和调试 npm run dev 开启本地服务,开启gulp watch,实时编译。模板文件使用的是views目录下的文件。

2.预览npm run preview

预览编译和版本化后的模板,模板文件使用的是_previews下的文件。

待解决

  1. 本地combo模拟(由于需要nginx支持,本地调试较为繁琐,此功能滞后)

关于映射

框架机为了解决多环境、多业务支持,本次起点改造通过多域名的方式,隔离和区分环境机器,有诸如devr.qidian.com,oar.qidian.com,rank.qidian.com等多套域名,对应开发环境有localr.qidian.com

若开发具体某个有二级频道的项目,请在views目录下以最终线上路由为基准新建项目文件夹,把相应的模板文件置于其中开发。

请在src/node-config/domain_alias.js中配置域名映射,以便正常启动本地服务。

精灵图生成注意事项

本构建工具已经支持自动生成精灵高清@2x和标清@1x图

命令行输入npm run sprite即可。

注意

注1: 请将二倍的高清icon图标,根据项目需求,放在src/static/images/{某个项目}/sprites/icon-*.png下。

以起点某个{projectA}为例

├── static
│   ├── qd
│   │ ├── css
│   │ ├── images
│   │ │ ├──projectA
│   │ │     │      ├──icon-a.png
│   │ │     │      ├──icon-b.png
│   │ │     │      ├──icon-c.png
│   │ ├── js
 

开发者唯一只需关心的就是icon图标的目录。不需要自己手动配置精灵图scss文件。 工具会根据{某个项目}的名称,对应在build/qd/images/{projectA}/ 生成@2x.png高清图与@1x.png标清图。并在build/qd/css/projectA_sprite.scss

├── build
│   ├── qd
│   │ ├── css
│   │ │ ├── projectA_sprite.scss
│   │ ├── images
│   │ │ ├──projectA
│   │ │     │      ├──sprite
│   │ │     │      │     ├── @2x.png
│   │ │     │      │     ├── @1x.png
│   │ ├── js

若有多个项目{projectB},{projectC}等等,工具均会自动对应生成,开发者只需要在引用精灵的scss文件中使用我们自定义好的宏就好。

$projectA-sprite-normal: '/qd/images/projectA/sprite/@1x.png';
$projectA-sprite-retina: '/qd/images/projectA/sprite/@2x.png';
 
 
//使用精灵图 
 
@include use-sprite($icon-a, $projectA-sprite-normal, $projectA-sprite-retina);
 
//按照上述方法,就可以直接调用某个精灵图了,无需手动调整background-size position等参数。