作者：Yihui Xie
译者：郑宝童
日期：2021.06.16

5.3 Serve the book

Instead of running render_book() or preview_chapter() over and over again, you can actually live preview the book in the web browser, and the only thing you need to do is save the Rmd file. The function serve_book() in bookdown can start a local web server to serve the HTML output based on the servr package (Xie 2021c).

无需一遍又一遍地运行 render_book() 或 preview_chapter() ，您实际上可以在网络浏览器中实时预览这本书，您唯一需要做的就是保存 Rmd 文件。 bookdown 中的函数 serve_book() 可以启动本地 Web 服务器来提供基于 servr 包 (Xie 2021c) 的 HTML 输出。

  1. serve_book(dir = ".", output_dir = "_book", preview = TRUE, 
  2.   in_session = TRUE, quiet = FALSE, ...)

You pass the root directory of the book to the dir argument, and this function will start a local web server so you can view the book output using the server. The default URL to access the book output is [http://127.0.0.1:4321](http://127.0.0.1:4321). If you run this function in an interactive R session, this URL will be automatically opened in your web browser. If you are in the RStudio IDE, the RStudio Viewer will be used as the default web browser, so you will be able to write the Rmd source files and preview the output in the same environment (e.g., source on the left and output on the right).

您将书籍的根目录传递给 dir 参数，此函数将启动本地 Web 服务器，以便您可以使用服务器查看书籍输出。访问图书输出的默认 URL 是 http://127.0.0.1:4321。如果您在交互式 R 会话中运行此函数，此 URL 将在您的 Web 浏览器中自动打开。如果您在 RStudio IDE 中，RStudio Viewer 将用作默认的 Web 浏览器，因此您将能够编写 Rmd 源文件并在相同的环境中预览输出（例如，左侧的是源文件和右侧的是输出）。

The server will listen to changes in the book root directory: whenever you modify any files in the book directory, serve_book() can detect the changes, recompile the Rmd files, and refresh the web browser automatically. If the modified files do not include Rmd files, it just refreshes the browser (e.g., if you only updated a certain CSS file). This means once the server is launched, all you have to do next is simply write the book and save the files. Compilation and preview will take place automatically as you save files.

服务器将监听 book 根目录中的更改：每当您修改 book 目录中的任何文件时， serve_book() 可以检测更改，重新编译 Rmd 文件，并自动刷新 Web 浏览器。如果修改后的文件不包含 Rmd 文件，它只会刷新浏览器（例如，如果您只更新了某个 CSS 文件）。这意味着一旦服务器启动，您接下来要做的就是简单地写书并保存文件。保存文件时将自动进行编译和预览。

If it does not really take too much time to recompile the whole book, you may set the argument preview = FALSE, so that every time you update the book, the whole book is recompiled, otherwise only the modified chapters are recompiled via preview_chapter(). The arguments in ... are passed to servr::httw(), and please refer to its help page to see all possible options, such as daemon and port. There are pros and cons of using in_session = TRUE or FALSE:

如果真的不需要太多时间重新编译整本书，你可以设置参数 preview = FALSE ，这样每次更新本书时，都会重新编译整本书，否则修改章节只通过preview_chapter()重新编译 。 ... 中的参数传递给 servr::httw() ，请参阅其帮助页面以查看所有可能的选项，例如 daemon 和 port。使用 in_session = TRUE 或 FALSE 有利也有弊：

  • For in_session = TRUE, you will have access to all objects created in the book in the current R session: if you use a daemonized server (via the argument daemon = TRUE), you can check the objects at any time when the current R session is not busy; otherwise you will have to stop the server before you can check the objects. This can be useful when you need to interactively explore the R objects in the book. The downside of in_session = TRUE is that the output may be different with the book compiled from a fresh R session, because the state of the current R session may not be clean.

  • 对于 in_session = TRUE ，您将可以访问当前 R 会话中书中创建的所有对象：如果您使用daemonized服务器（可以通过参数 daemon = TRUE），您可以在R会话不忙时随时检查对象当前；否则，您必须先停止服务器，然后才能检查对象。当您需要以交互方式探索本书中的 R 对象时，这会很有用。in_session = TRUE 的缺点是输出可能与在新 R 会话编译的书不同，因为当前 R 会话的状态可能不干净。

    • For in_session = FALSE, you do not have access to objects in the book from the current R session, but the output is more likely to be reproducible since everything is created from new R sessions. Since this function is only for previewing purposes, the cleanness of the R session may not be a big concern.

  • 对于 in_session = FALSE，您无法从当前 R 会话访问书中的对象，但输出更有可能重现，因为所有内容都是在新的 R 会话中创建的。由于此功能仅用于预览目的，因此 R 会话的清洁度并不是一个问题。

    You may choose in_session = TRUE or FALSE depending on your specific use cases. Eventually, you should run render_book() from a fresh R session to generate a reliable copy of the book output.

您可以根据您的特定用例选择 in_session = TRUE 或 FALSE，。最终，您需要在新的 R 会话中运行 render_book() 以生成书籍输出的可靠副本。

References

Xie, Yihui. 2021c. Servr: A Simple Http Server to Serve Static Files or Dynamic Documents. https://github.com/yihui/servr.