@1j01/live-server 中文文档教程

Question

Live Server: CSP Fork

Fork Changes

此分支添加了对内容安全策略 (CSP) 的支持。

如果在 标签中设置了 Content-Security-Policy 标头，服务器将修改它以允许加载 live-server 注入的脚本，以及它使用的 web 套接字连接用于样式表更新。

示例：

<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'self'">

变成：

<meta http-equiv="Content-Security-Policy" content="default-src 'nonce-53c70de06ed2ca9452aa092bdfd6d0fc' ; connect-src ws: wss: http: https: ; style-src 'self'">

它并不完美，有很多边缘情况需要考虑，但我试图让它合理地保留您的 CSP。

它为注入的脚本标签添加一个随机数，如果它存在，则添加到 script-src-elem 指令，否则 script-src，或 default-src 如果两者都不存在。 （如果这三个都不存在，则不需要添加，但 CSP 是不安全的，允许任意内联脚本。）

如果必须添加 connect-src 指令，则它继承自default-src 这样它就不会混淆地限制 connect-src。 它应该只扩展允许的范围。

Package Description

这是一个具有实时重新加载功能的小型开发服务器。 使用它来破解您的 HTML/JavaScript/CSS 文件，但不能用于部署最终站点。

使用此功能有两个原因：

1. AJAX requests don't work with the file:// protocol due to security restrictions, i.e. you need a server if your site fetches content through JavaScript.
2. Having the page reload automatically after changes to files can accelerate development.

您无需安装任何浏览器插件或手动将代码片段添加到您的页面即可使重新加载功能正常工作，请参阅下面的“工作原理”部分了解更多信息。 如果您不想/不需要实时重新加载，您可能应该使用更简单的方法，例如以下基于 Python 的单行代码：

python -m SimpleHTTPServer

Installation

您需要 node.js 和 npm。 您可能应该在全球范围内安装它。

Npm 方式

npm install -g @1j01/live-server

手动方式

git clone https://github.com/1j01/live-server
cd live-server
npm install # Local dependencies if you want to hack
npm install -g # Install globally

Usage from command line

在您的项目目录中发出命令 live-server。 或者，您可以添加路径作为命令行参数。

这将自动启动默认浏览器。 当您对任何文件进行更改时，浏览器将重新加载页面 - 除非它是 CSS 文件，在这种情况下，更改将在不重新加载的情况下应用。

命令行参数：

• --port=NUMBER - select port to use, default: PORT env var or 8080
• --host=ADDRESS - select host address to bind to, default: IP env var or 0.0.0.0 ("any address")
• --no-browser - suppress automatic web browser launching
• --browser=BROWSER - specify browser to use instead of system default
• --quiet | -q - suppress logging
• --verbose | -V - more logging (logs all requests, shows all listening IPv4 interfaces, etc.)
• --open=PATH - launch browser to PATH instead of server root
• --watch=PATH - comma-separated string of paths to exclusively watch for changes (default: watch everything)
• --ignore=PATH - comma-separated string of paths to ignore (anymatch-compatible definition)
• --ignorePattern=REGEXP - Regular expression of files to ignore (ie .*\.jade) (DEPRECATED in favor of --ignore)
• --no-css-inject - reload page on CSS change, rather than injecting changed CSS
• --middleware=PATH - path to .js file exporting a middleware function to add; can be a name without path nor extension to reference bundled middlewares in middleware folder
• --entry-file=PATH - serve this file (server root relative) in place of missing files (useful for single page apps)
• --mount=ROUTE:PATH - serve the paths contents under the defined route (multiple definitions possible)
• --spa - translate requests from /abc to /#/abc (handy for Single Page Apps)
• --wait=MILLISECONDS - (default 100ms) wait for all changes, before reloading
• --htpasswd=PATH - Enables http-auth expecting htpasswd file located at PATH
• --cors - Enables CORS for any origin (reflects request origin, requests with credentials are supported)
• --https=PATH - PATH to a HTTPS configuration module
• --https-module=MODULE_NAME - Custom HTTPS module (e.g. spdy)
• --proxy=ROUTE:URL - proxy all requests for ROUTE to URL
• --help | -h - display terse usage hint and exit
• --version | -v - display version and exit

默认选项：

如果文件 ~/.live-server.json 存在，它将被加载并用作命令行上 live-server 的默认选项。 有关选项名称，请参阅“从节点使用”。

Usage from node

var liveServer = require("@1j01/live-server");

var params = {
    port: 8181, // Set the server port. Defaults to 8080.
    host: "0.0.0.0", // Set the address to bind to. Defaults to 0.0.0.0 or process.env.IP.
    root: "/public", // Set root directory that's being served. Defaults to cwd.
    open: false, // When false, it won't load your browser by default.
    ignore: 'scss,my/templates', // comma-separated string for paths to ignore
    file: "index.html", // When set, serve this file (server root relative) for every 404 (useful for single-page applications)
    wait: 1000, // Waits for all changes, before reloading. Defaults to 0 sec.
    mount: [['/components', './node_modules']], // Mount a directory to a route.
    logLevel: 2, // 0 = errors only, 1 = some, 2 = lots
    middleware: [function(req, res, next) { next(); }] // Takes an array of Connect-compatible middleware that are injected into the server middleware stack
};
liveServer.start(params);

HTTPS

为了启用 HTTPS 支持，您需要创建一个配置模块。 该模块必须导出将用于配置 HTTPS 服务器的对象。 这些键与 tls.createServer 的 options 中的键相同。

例如：

var fs = require("fs");

module.exports = {
    cert: fs.readFileSync(__dirname + "/server.cert"),
    key: fs.readFileSync(__dirname + "/server.key"),
    passphrase: "12345"
};

如果使用节点 API，您还可以直接传递一个配置对象而不是模块的路径。

HTTP/2

要获得 HTTP/2 支持，可以通过 --https-module CLI 参数（Node.js 脚本的 httpsModule 选项）提供自定义 HTTPS 模块。 请务必先安装模块。 浏览器不支持 HTTP/2 未加密模式，因此 live-server 不支持。 查看这个问题和我可以使用 HTTP/2 上的页面吗 了解更多详情。

例如来自 CLI(bash)：

live-server \
    --https=path/to/https.conf.js \
    --https-module=spdy \
    my-app-folder/

Troubleshooting

• No reload on changes
  • Open your browser's console: there should be a message at the top stating that live reload is enabled. Note that you will need a browser that supports WebSockets. If there are errors, deal with them. If it's still not working, file an issue.
• Error: watchENOSPC
  • See this suggested solution.
• Reload works but changes are missing or outdated
  • Try using --wait=MS option. Where MS is time in milliseconds to wait before issuing a reload.

How it works

服务器是一个简单的节点应用程序，为工作目录及其子目录提供服务。 它还会监视文件的更改，当发生更改时，它会通过 Web 套接字连接向浏览器发送一条消息，指示它重新加载。 为了让客户端支持这一点，服务器向每个请求的 html 文件注入一小段 JavaScript 代码。 此脚本建立 Web 套接字连接并侦听重新加载请求。 通过从 DOM 中找到引用的样式表并诱使浏览器再次获取和解析它们，可以在不重新加载整个页面的情况下刷新 CSS 文件。

Contributing

我们欢迎贡献！ 有关详细信息，请参阅 CONTRIBUTING.md。

Version history

• v1.3.1
  • Fixed inheriting default-src 'none' for connect-src in CSP (it should drop 'none', to avoid a warning) (@1j01)
  • Fixed redundant nonce in connect-src inherited from modified default-src (it now inherits the original default-src) (@1j01)
  • Fixed missing protocols in case that connect-src is defined (@1j01)
  • Limited published files to live-server.js, index.js, injected.html, and middleware/ (@1j01)
• v1.3.0
  • Added Content-Security-Policy support (@1j01)
• v1.2.1
  • --https-module=MODULE_NAME to specify custom HTTPS module (e.g. spdy) (@pavel)
  • --no-css-inject to reload page on css change instead of injecting the changes (@kylecordes)
  • Dependencies updated to get rid of vulnerabilities in deps
• v1.2.0
  • Add --middleware parameter to use external middlewares
  • middleware API parameter now also accepts strings similar to --middleware
  • Changed file watcher to improve speed (@pavel)
  • --ignore now accepts regexps and globs, --ignorePattern deprecated (@pavel)
  • Added --verbose cli option (logLevel 3) (@pavel)
    • Logs all requests, displays warning when can't inject html file, displays all listening IPv4 interfaces…
  • HTTPS configuration now also accepts a plain object (@pavel)
  • Move --spa to a bundled middleware file
  • New bundled spa-no-assets middleware that works like spa but ignores requests with extension
  • Allow multiple --open arguments (@PirtleShell)
  • Inject to head if body not found (@pmd1991)
  • Update dependencies
• v1.1.0
  • Proxy support (@pavel)
  • Middleware support (@achandrasekar)
  • Dependency updates (@tapio, @rahatarmanahmed)
  • Using Travis CI
• v1.0.0
  • HTTPS support (@pavel)
  • HTTP Basic authentication support (@hey-johnnypark)
  • CORS support (@pavel)
  • Support mounting single files (@pavel)
  • --spa cli option for single page apps, translates requests from /abc to /#/abc (@evanplaice)
  • Check IP env var for default host (@dotnetCarpenter)
  • Fix ignorePattern from config file (@cyfersystems)
  • Fix test running for Windows (@peterhull90)
• v0.9.2
  • Updated most dependencies to latest versions
  • --quiet now silences warning about injection failure
  • Giving explicit --watch paths now disables adding mounted paths to watching
• v0.9.1
  • --ignorePattern=REGEXP exclude files from watching by regexp (@psi-4ward)
  • --watch=PATH cli option to only watch given paths
• v0.9.0
  • --mount=ROUTE:PATH cli option to specify alternative routes to paths (@pmentz)
  • --browser=BROWSER cli option to specify browser to use (@sakiv)
  • Improved error reporting
  • Basic support for injecting the reload code to SVG files (@dotnetCarpenter, @tapio)
  • LiveServer.shutdown() function to close down the server and file watchers
  • If host parameter is given, use it for browser URL instead of resolved IP
  • Initial testing framework (@harrytruong, @evanplaice, @tapio)
• v0.8.2
  • Load initial settings from ~/.live-server.json if exists (@mikker)
  • Allow --port=0 to select random port (@viqueen)
  • Fix injecting when file extension is not lower case (@gusgard)
  • Fail gracefully if browser does not support WebSockets (@mattymaloney)
  • Switched to a more maintained browser opening library
• v0.8.1
  • Add --version / -v command line flags to display version
  • Add --host cli option to mirror the API parameter
  • Once again use 127.0.0.1 instead of 0.0.0.0 as the browser URL
• v0.8.0
  • Support multiple clients simultaneously (@dvv)
  • Pick a random available port if the default is in use (@oliverzy, @harrytruong)
  • Fix Chrome sometimes not applying CSS changes (@harrytruong)
  • --ignore=PATH cli option to not watch given server root relative paths (@richardgoater)
  • --entry-file=PATH cli option to specify file to use when request is not found (@izeau)
  • --wait=MILLISECONDS cli option to wait specified time before reloading (@leolower, @harrytruong)
• v0.7.1
  • Fix hang caused by trying to inject into fragment html files without </body>
  • logLevel parameter in library to control amount of console spam
  • --quiet cli option to suppress console spam
  • --open=PATH cli option to launch browser in specified path instead of root (@richardgoater)
  • Library's noBrowser: true option is deprecated in favor of open: false
• v0.7.0
  • API BREAKAGE: LiveServer library now takes parameters in an object
  • Add possibility to specify host to the lib
  • Only inject to host page when working with web components (e.g. Polymer) (@davej)
  • Open browser to 127.0.0.1, as 0.0.0.0 has issues
  • --no-browser command line flag to suppress browser launch
  • --help command line flag to display usage
• v0.6.4
  • Allow specifying port from the command line: live-server --port=3000 (@Pomax)
  • Don't inject script as the first thing so that DOCTYPE remains valid (@wmira)
  • Be more explicit with listening to all interfaces (@inadarei)
• v0.6.3
  • Fix multiple _cacheOverride parameters polluting css requests
  • Don't create global variables in the injected script
• v0.6.2
  • Fix a deprecation warning from send
• v0.6.1
  • Republish to fix npm troubles
• v0.6.0
  • Support for using as node library (@dpgraham)
• v0.5.0
  • Watching was broken with new versions of watchr > 2.3.3
  • Added some logging to console
• v0.4.0
  • Allow specifying directory to serve from command line
• v0.3.0
  • Directory listings
• v0.2.0
  • On-the-fly CSS refresh (no page reload)
  • Refactoring
• v0.1.1
  • Documentation and meta tweaks
• v0.1.0
  • Initial release

License

使用来自 Connect 和 Roots< 的 MIT 许可代码/a>。

（麻省理工学院许可证）

版权所有 (c) 2012 Tapio Vierros

特此免费授予任何获得本软件和相关文档文件（“软件”）副本的人不受限制地处理本软件，包括但不限于限制使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，并允许软件的接收人这样做，但须满足以下条件：

上述版权通知和本许可通知应包含在软件的所有副本或重要部分中。

本软件“按原样”提供，不提供任何明示或暗示的保证，包括但不限于对适销性、特定用途的适用性和非侵权的保证。 在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权行为还是其他方面，由软件或软件的使用或其他交易引起、由软件引起或与之相关软件。