编译 v-no

The documentation is a work in progress, and English edition is just an empty shell for now. I will translate it when Chinese edition has done.

v-no 使用 Vue CLI 进行开发，编译它并不需要掌握 Vue.js 的相关知识。

如果你想用 v-no 搭建自己的网站，可以考虑使用随版本号更新的网站模板。更新网站内容和绝大部分的可配置项都不需要你进行编译，只有当模板使用的环境变量不能满足你的部署需求时（部署到根域名下某个目录，或者需要更多语言的语法高亮支持），你才有必要阅读以下内容。

编译步骤
目录结构
现代模式
环境变量
编译 Prism.js

编译步骤

最通常不过的 Node.js 项目编译：

首先确认你安装有 Node.js 和 Yarn 包管理器。
然后克隆或下载 v-no 项目仓库到本地。
进入项目目录，执行：

yarn && yarn build

目录结构

编译完成的文件会输出在 dist 目录下。这是默认的目录结构：

dist
│   index.html
│   archives.md
│   categories.md
│   common.md
│   index.md
│   README.md
│   search.md
│
└─── uploads
│   │   favicon.png
│   │   logo.png
│
└─── assets
    │   config.js
    │
    └─── css
    │   │   app.[hash].css
    │   │   main.[hash].css
    │   │   prismjs.[hash].css
    │
    └─── js
        │   app.[hash].js
        │   chunk-vendors.[hash].js
        │   file.[hash].js
        │   main.[hash].js
        │   markdown.[hash].js
        │   prismjs.[hash].js

高亮的行指示的是路径固定的重要文件。

其中 index.html、assets/css/* 和 assets/js/* 是编译后的代码文件。

assets/config.js 包含应用的一些可配置项。它默认指定了 favicon.png 和六个 .md 文件的路径。uploads/logo.png 则是作为示例被 index.md 引用。

现代模式

现代模式是 Vue CLI 提供的一种构建选择。

v-no 在这个模式下编译的 .js 文件体积能减少 16% ~ 18% 左右，执行性能也会相应提高。不过你也有必要同时提供一份为老旧浏览器准备的传统代码，以防遇到还用着祖传软件的访客们。v-no 的部署大小会因此变成原来的两倍，浏览器会选择其中一种版本的代码进行加载。

这是以现代模式进行构建的指令，你需要酌情考虑是否使用它：

yarn run build-modern

这是它输出的 dist 目录结构（省略了和普通构建没有区别的地方）：

dist
│   index.html
│
└─── assets
    │
    └─── js
        │   app.[hash].js
        │   app-legacy.[hash].js
        │   chunk-vendors.[hash].js
        │   chunk-vendors-legacy.[hash].js
        │   file.[hash].js
        │   file-legacy.[hash].js
        │   main.[hash].js
        │   main-legacy.[hash].js
        │   markdown.[hash].js
        │   markdown-legacy.[hash].js
        │   prismjs.[hash].js
        │   prismjs-legacy.[hash].js

高亮的行指示的就是传统版本的代码文件。

如果你只想部署现代版本的代码，也可以手动清理掉它们。然后移除 index.html 中包含 nomodule 的相关代码。它们格式化后会是这个样子:

<script>
  !function() {
    var e = document, t = e.createElement('script');
    if (!('noModule' in t) && 'onbeforeload' in t) {
      var n = !1;
      e.addEventListener('beforeload', function(e) {
        if (e.target === t) n = !0;
        else if (!e.target.hasAttribute('nomodule') || !n) return;
        e.preventDefault();
      }, !0), t.type = 'module', t.src = '.', e.head.appendChild(t), t.remove();
    }
  }();</script><script src="/assets/js/chunk-vendors-legacy.[hash].js" nomodule></script><script src="/assets/js/app-legacy.[hash].js" nomodule></script>

环境变量

v-no 有几个会影响编译结果的环境变量，它们储存在项目根目录下的 .env 文件中。

这是默认的 .env 文件：

VUE_APP_PUBLIC_PATH=/
VUE_APP_INDEX_PATH=index.html
VUE_APP_CDN_URL=PRISM_LANGUAGES=markup,css,clike,javascript

变量说明：


`VUE_APP_PUBLIC_PATH`	应用的部署路径。如果部署到根域名（`http://localhost/`），它就是 `/`；如果部署到根域名下的某个目录（`http://localhost/v-no-doc/`），它是这个目录的路径（`/v-no-doc/`）。请避免让此项留空，或使用相对路径，这会让 v-no 产生许多预料之外的问题。
`VUE_APP_INDEX_PATH`	主页 HTML 文件的输出路径，它是应用的唯一入口。如果要进行预渲染，请避免让它和同名 `.md` 文件处于同一目录（同名 `.md` 文件的预渲染页面会把它覆盖掉）。通常建议在需要预渲染时把此项改为 `-/index.html`。
`VUE_APP_CDN_URL`	网站使用的 CDN 地址，需要以 `/` 结尾。它可以让 v-no 自身代码文件和配置文件也能使用 CDN 链接，以达到全站 CDN 的目的。配置文件的 `cdn` 配置项会在启用它进行编译后失效。如果此项为空，它会被忽略。
`PRISM_LANGUAGES`	Prism.js 会高亮的语言列表，注意用英文逗号进行分隔。你可以参考 Prism.js 支持的语言填写。如果此项为空，会将 Prism.js 的打包体积压到最小。

VUE_APP_PUBLIC_PATH 和 VUE_APP_INDEX_PATH 直接传递给 vue.config.js，它们对应 Vue CLI 文档里的 publicPath 和 indexPath。

如果 VUE_APP_CDN_URL 不为空，它会在生产环境构建时替换掉 VUE_APP_PUBLIC_PATH。

一般不建议直接修改 .env 文件。你可以把它复制一份，改名为 .env.local，它会覆盖 .env 里的同名变量。这些文件都是交由 Vue CLI 解析的，你也有官方文档可以参考。

编译 Prism.js

v-no 使用 babel-plugin-prismjs 对 Prism.js 按需编译。它的相关代码会被单独打包在 assets/js/prismjs.[hash].js 文件，体积会随着 PRISM_LANGUAGES 环境变量的改动而产生变化。

但我不知道为什么如果不修改导入了 Prism.js 的代码文件，它就不会使用新的环境变量进行编译。具体表现为编译后的 prismjs.[hash].js 文件的大小和 Hash 值都没有发生变化。

为了确保对 Prism.js 相关变量的更新能够生效，你需要在编译前对 src/ts/async/prismjs.ts 做出一点不影响代码逻辑的小改动。比如增加一个空行，等编译完成再把它删去。

: This page is open source, improve it

Graph