Gulp+Flask 静态文件版本管理最佳实践

最近了解了前端静态文件版本的管理方案，结合目前自己正在做的 Python Web 项目 EveryClass 总结了一套最佳前端静态文件版本方案。

公认的静态文件命名方案为

main_c0f13f3.css

，其中

c0f13f3

为文件 hash。有关于为什么不使用

main.css?v=xxx

的形式，请参考这篇知乎回答。我在此基础上进行了一个小优化，修改成了

main_v1_c0f13f3.css

，主要是考虑到了前端界面可能会有大版本更新的问题，如果只使用hash值非常不便于直观地提示文件版本。这样做的另外一个好处是：如果静态文件版本已经更新到了v20，完全可以把v1删掉，用v1做前缀可以在 CDN 上快速找到并删掉所有v1版本的文件。

需要注意的是，静态文件服务器需要配置让静态文件缓存永不过期。如果只是304协商缓存的话就达不到比较好的优化速度的效果了。

在我的这个项目中，前端自动化使用的是 Gulp、后端 python web 框架使用的是 Flask。如何结合这两者呢？我的解决方案如下：

首先上一个文件目录：

/src/*.py
/src/templates
/src/static/*.js
/src/static/*.css
/dist/static/*.js
/dist/static/*.css

其中 /src 是源文件目录，CSS文件名命名规范为：style-v1.css（名称-v1.css）；/dist是 Gulp 的输出目录（发布到静态服务器）。Gulp 进行的动作主要是uglify、versioning。至于模板文件，我觉得交给 Flask 管理比较好。

在 flask app 中写模板filter：

# If STATIC_VERSIONED, use versioned file like 'style_v1_c012dr.css' instead of 'style_v1.css'
@app.template_filter('versioned')
def version_filter(filename):
if app.config['STATIC_VERSIONED']:
new_filename = app.config['STATIC_MANIFEST'][filename]
return new_filename
return filename

在模板文件中使用 filter：

<link rel="stylesheet" type="text/css" href="{{ url_for('static', filename='style-v1.css'|versioned) }}">

gulpfile.js：

var gulp = require('gulp');
var gutil = require('gulp-util');
var concat = require('gulp-concat');                            //Concat CSS files
var minifyCss = require('gulp-clean-css');                      //Compress CSS
var rev = require('gulp-rev');                                  //File revision

//CSS
gulp.task('cssCompress', function() {
gulp.src('./src/everyclass/static/*-v1.css')
//.pipe(concat('style.min.css'))                        //Concat CSS files
.pipe(minifyCss())                                      //Compress
.pipe(rev())                                            //Revision
.pipe(gulp.dest('./dist/'))                             //Output
.pipe(rev.manifest())                                   //Generate rev-manifest.json
.pipe(gulp.dest('./src/everyclass'));                   //Save rev-manifest.json for flask app
});

gulp.task('copyDistToSrc',function(){
gulp.src('./dist/*.css')
.pipe(gulp.dest('./src/everyclass/static'));
});

//Task Sets
gulp.task('default', ['css']);
gulp.task('css', ['cssCompress', 'copyDistToSrc']);

//Watch tasks
gulp.task('watch-css',function(){
gulp.watch('./src/everyclass/static/*.css',['cssCompile']);
});

运行

gulp css

，它会做这么几件事：

- 压缩 css 并放置在 /dist目录

- 生成manifest文件，并放置在 flask app 目录下，提供给 flask app 使用

- 拷贝 /dist 中的文件到 /src/static（因为本地调试的时候还是需要用 src 文件夹里的css调试，访问不到/dist目录）

部署方式：

- 将/dist里的静态文件部署到 CDN（比如七牛CDN提供了 qshell）

- 打包 src 到网页服务器，修改文件权限（如果需要），uWSGI 平滑 reload 到新版本（可写脚本自动化完成）

参考文章：

1. Autoversioning static assets in Flask