webcc - 站点发布优化工具

最后更新:2018-05-05

@module webcc 站点发布优化工具

Webcc用于Web站点优化,即生成用于发布的Web应用目录。
一般要求源代码使用git管理,通过git命令查询源文件列表及版本差异,实现增量编译、自动化发布等功能。

也可以脱离git独立使用,这时要求指定源文件列表,通过设置环境变量WEBCC_LS_CMD,例如:

export WEBCC_LS_CMD='find . -type f'
# export WEBCC_LS_CMD='find . -type f | grep -v .svn | grep -v .git'
# export WEBCC_LS_CMD='svn ls -R | egrep -v "/$"'
webcc {srcDir}

webcc进入{srcDir}目录,执行WEBCC_LS_CMD命令得到源文件列表,分别进行处理,生成发布目录,默认为"output_web"目录。

注意:

Usage:

处理源目录,生成发布目录
webcc {srcDir} [-o {outDir=output_web}]

webcc单个命令调用
webcc -cmd {cmd} [-o {outFile}] [-minify yes]

webcc命令可在html文件中使用,例如做JS/CSS合并压缩:

<!-- WEBCC_BEGIN MERGE=lib-app -->
<link rel="stylesheet" href="lib/mui.css" />
<link rel="stylesheet" href="app.css" />

<script src="lib/common.js"></script>
<script src="lib/app_fw.js"></script>
<script src="app.js"></script>
<!-- WEBCC_END -->

WEBCC_BEGIN后面,用MERGE=输出文件基本名(basename)的格式(不要写全名如lib-app.js), MERGE=lib-app表示根据link及script标签自动合并生成 lib-app.min.js / lib-app.min.css。

它等价于

<!-- WEBCC_BEGIN -->
<link rel="stylesheet" href="lib/mui.css" />
<link rel="stylesheet" href="app.css" />

<script src="lib/common.js"></script>
<script src="lib/app_fw.js"></script>
<script src="app.js"></script>
<!-- WEBCC_USE_THIS
// 除了//开头的注释和 WEBCC_CMD 开头的命令,其它部分均直接输出
WEBCC_CMD mergeCss -o lib-app.min.css -minify yes lib/mui.css app.css
WEBCC_CMD mergeJs -o lib-app.min.js -minify yes lib/common.js lib/app_fw.js app.js
WEBCC_END -->

WEBCC_USE_THIS标识可区分开发时用的内容和发布时用的内容,例如开发时和发布后使用两套JS,可以这样设置:

<!-- WEBCC_BEGIN -->
    <script src="lib/react/react.development.js"></script>
    <script src="lib/react/react-dom.development.js"></script>
<!-- WEBCC_USE_THIS
    <script src="lib/react/react.production.min.js"></script>
    <script src="lib/react/react-dom.production.min.js"></script>
WEBCC_END -->

这就支持开发时使用development版本的库,而发布时使用production版本的库。
用多个库时常常通过设置MERGE来合并,比如

<!-- WEBCC_BEGIN MERGE=react -->
    <script src="lib/react/react.development.js"></script>
    <script src="lib/react/react-dom.development.js"></script>
<!-- WEBCC_USE_THIS
    <script src="lib/react/react.production.min.js"></script>
    <script src="lib/react/react-dom.production.min.js"></script>
WEBCC_END -->

发布时可将两个production的库合并成一个react.min.js文件。

如果要内嵌JS/CSS,在MERGE后不指定名称即可:

<!-- WEBCC_BEGIN MERGE -->
<link rel="stylesheet" href="index.css" />
<link rel="stylesheet" href="icon.css" />
<script src="index.js"></script>
<!-- WEBCC_END -->

它等价于

<!-- WEBCC_BEGIN -->
<link rel="stylesheet" href="index.css" />
<link rel="stylesheet" href="icon.css" />
<script src="index.js"></script>
<!-- WEBCC_USE_THIS
<style>
WEBCC_CMD mergeCss -minify yes index.css icon.css
</style>
<script>
WEBCC_CMD mergeJs -minify yes index.js
</script>
WEBCC_END -->

在发布时,WEBCC_BEGIN到WEBCC_USE_THIS下的内容将被移除,而 WEBCC_USE_THIS到 WEBCC_END间的内容被保留到发布版本中。
如果其中出现形如 WEBCC_CMD {cmd} {args} 的内容,则会调用webcc命令做处理。

当在webcc.conf.php中指定HASH规则时,上述webcc命令将会执行。例:

$RULES = [
    'm2/index.html' => 'HASH',
]

注意:

@see webcc-mergeJs 合并及压缩JS

@see webcc-mergeCss 合并CSS

@see webcc-mergePage 合并逻辑页

@key webcc.conf.php webcc配置

用法可参考文档:Web应用部署

@key __HASH__ hash标识

格式:

{file}?__HASH__

或可指定相对于当前文件的相对路径{relDir},一般用于js文件中。

{file}?__HASH__,{relDir}

例如:

loadScript("cordova/cordova.js?__HASH__,.."); // 表示该文件相对当前文件的路径应该是 ../cordova/cordova.js 
loadScript("cordova-ios/cordova.js?__HASH__,../m"); // 表示该文件相对当前文件的路径应该是 ../m/cordova-ios/cordova.js

@fn webcc-mergeCss CSS合并

webcc -cmd mergeCss {cssFile1} ... [-o {outFile}]

CSS合并,以及对url相对路径进行修正。

例:

webcc -cmd mergeCss lib/a.css b.css -o out.css

注意:只处理相对路径,带协议的情况不处理:

url(data:...)
url(http:...)

路径处理示例:

// 处理 url(...) 中的路径
eg.  srcDir='lib', outDir='.'
curDir='.' (当前路径相对outDir的路径)
prefix = {curDir}/{srcDir} = ./lib = lib
url(1.png) => url(lib/1.png)
url(../image/1.png) => url(lib/../image/1.png) => url(image/1.png)

eg2. srcDir='lib', outDir='m2/css'
curDir='../..' (当前路径相对outDir的路径)
prefix = {curDir}/{srcDir} = ../../lib
url(1.png) => url(../lib/1.png)
url(../image/1.png) => url(../../lib/../image/1.png) => url(../../image/1.png) (lib/..被合并)

TODO: 暂不支持eg3的情况,即outFile不允许以".."开头。
eg3. srcDir='lib', outDir='../m2/css'
curDir='../../html' (假设当前实际dir为'prj/html')
prefix = {curDir}/{srcDir} = ../../html/lib
url(1.png) => url(../../html/lib/1.png)
url(../image/1.png) => url(../../html/lib/../image/1.png) => url(../../html/image/1.png)

@fn webcc-mergePage 逻辑页合并

webcc -cmd mergePage {page1} ... [-usePageTemplate yes]

将逻辑页的html文件及其链接的js文件,处理后嵌入主html。

例:命令行

webcc -cmd mergePage ../server/m2/page/home.html

例:在html中隐式调用

<!-- WEBCC_BEGIN -->
page/home.html
page/login.html
page/login1.html
page/me.html
<!-- WEBCC_END -->

<!-- WEBCC_BEGIN -->
<!-- WEBCC_USE_THIS
WEBCC_CMD mergePage page/home.html page/login.html page/login1.html page/me.html
WEBCC_END -->

注意:

支持两种方式:(通过选项 "-usePageTemplate 1" 选择)

例如,逻辑页order.html引用order.js,格式为:

<div mui-initfn="initPageOrder" mui-script="order.js">
</div>
  1. 使用script标签嵌入主页面(缺省):

    <script type="text/html" id="tpl_order">
        <!-- order.html内容, 其mui-script属性被删除,代之以直接嵌入JS内容 -->
        <div mui-initfn="initPageOrder" >
        </div>
    </script>
    
    <script>
    // order.js内容
    </script>
  2. 使用template标签嵌入主页面(H5标准,目前兼容性还不够):

    <template id="tpl_order">
    <!-- order.html 内容 -->
    <div mui-initfn="initPageOrder" >
        <script>
        // order.js内容
        </script>
    </div>
    </template>

@fn webcc-mergeJs JS合并及压缩

webcc -cmd mergeJs {jsFile1} ... [-o {outFile}]

将js文件合并生成一个文件,并做简单压缩处理(去注释、压缩空白)
如果源文件名含有.min.js(如jquery.min.js),则认为已压缩,不重新压缩。

例:

webcc -cmd mergeJs lib/jquery.min.js lib/app_fw.js app.js [-o lib_app.js]

在压缩时,需要用到外部jsmin工具,该工具在webcc相同目录下。

@module jdcloud-build

筋斗云框架上线部署工具。支持ftp/git两种方式部署。

使用本工具步骤:

要求相关工具:

使用FTP上线,编写build_web.sh如下:

export OUT_DIR=../product-online
export FTP_PATH=ftp://server/path/
export FTP_AUTH=www:hello
tool/jdcloud-build.sh

使用git上线:

export OUT_DIR=../product-online
export GIT_PATH=user@server:path/jdcloud
tool/jdcloud-build.sh

在上线时要求输入密码,可以通过设置ssh证书签名方式免密登录。

如果同时设置了GIT_PATH与FTP_PATH,会优先使用git方式上线。

通过环境变量向jdcloud-build脚本传参数,可用变量如下所述。

@var OUT_DIR

必须指定。
输出目录,即发布版本库的目录,一般起名为{project}-online.

@var FTP_PATH

@var FTP_AUTH

使用ftp上线时,指定线上地址,如ftp://server/path。FTP_AUTH格式为{user}:{pwd}.

@var GIT_PATH

使用git上线时,指定线上版本库地址。如 GIT_PATH=user@server:path/jdcloud

@var CHECK_BRANCH

online版本库可以使用多分支,每个分支对应一个线上地址。
如果指定分支,则要求在上线时online版本库分支与指定相同,否则出错。

@var CFG_PLUGINS

如果指定,则plugin文件夹下只上传指定的插件,plugin/index.php和未指定的插件均不上传,例:

CFG_PLUGINS=plugin1,plugin2
Generated by jdcloud-gendoc