在Windows本地搭建Habitica

向Habitica贡献代码前，您需要搭建网站的本地实例来对您的更改进行调试。本文会向您介绍如何在Windows中执行本地化的操作。

如果您使用的是Windows以外的操作系统（或托管在Windows上但包含不同操作系统的虚拟机），或是想为移动端开发做出贡献，请参阅本地搭建Habitica。

按顺序阅读本文，确保每一步都与教程相符。如果您遇到错误，请务必停止，问题解决后再继续下一步。

通过阅读铁匠指南，您可以获得有关Habitica编码的背景信息，这对本地实例的搭建很重要。

为排除故障做准备[]

本地安装可能无法一次性成功，但我们很乐意为您提供帮助！Habitica使用了很多软件，对于刚刚接触本项目的您来说可能太过复杂。在遇到错误之前，请按照本节内容的所有步骤进行操作以避免安装失败，即使遇到错误，我们也能快速评估您的问题，使您轻松得到帮助。

当您安装Habitica时：

请记录您输入的每个命令及其完整的输出（可以将所有命令和输出保存到一个或多个文本文件中，以便日后查看）
仔细阅读所有输出消息来排查错误。
- 遇到错误时请不要继续操作，直到错误解决，否则后续步骤可能无法正常工作。
- 屏幕截图也许是记录错误的一种简单方法，但截图并不适合分析错误。因此，请尽可能以文本形式提供完整的错误消息，方便管理员将相关内容粘贴到GitHub提问或Google搜索。
若您采取了本教程之外的操作，请记录您所做的不同之处及其原因。便于解答者了解问题发生的关键，以此避免您得到无关的建议。

如果您在修复错误时需要帮助，请将您收集的所有信息上传到GitHub Gist等站点，然后在GitHub中记录问题并告诉我们以下信息：

您使用的Windows版本
任何与标准指令的偏差
本教程要求您记录的信息
链接到您上传的文件
您具体遇到了什么问题

排除故障的一个关键步骤是能够重现问题。为了让他人能够帮助您进行故障排除，除非他们已经熟悉该问题，否则他们通常需要能够在另一个系统上重现该情况。因此，任何可以帮助他人重现问题的信息都是有价值的。您自己也可以尝试重现问题。有时从头开始可以解决问题或帮助您确定问题发生的可能原因。

安装Git[]

如果您还没有GitHub帐户，请创建一个。

在您的机器上安装git（此处提供安装说明）。

在Git中配置行尾转换[]

根据您安装Git的方式，您可能会看到“Configuring the line ending conversions”窗口，类似于旁边的屏幕截图。请尽可能选择“Checkout as-is, commit Unix-style line endings”。

您也可以在Git安装完成后，通过运行下面的git config命令从命令行配置该设置。当您遇到“未找到 git 程序”的相关错误时，请浏览下方的“将Git放入PATH变量”部分，然后再返回此处运行该命令。
git config --global core.autocrlf input

行尾配置是必要的，因为Windows处理行尾的方式与其他操作系统不同。它使用回车符和换行符的组合，\r\n（CRLF），而Unix/Linux/MacOS系统仅使用换行符（LF）字符\n。要强制Windows兼容，您必须设置Git以确保只有LF行尾被提交到Habitica的GitHub存储库。

有关Git中的行尾和空格的更多信息，请参阅Formatting and Whitespace" section in the Pro Git book 。

如果您不想全局配置core.autocrlf，请参阅Dealing with line endings > Per-repository settings以了解如何为单个存储库进行配置。当您已经将Git用于其他项目或未来用于其他项目时，请不要提交.gitattributes文件，所有Habitica开发人员的存储库中都不需要该文件。

将Git添加到PATH环境变量[]

安装Git程序的文件夹必须添加到PATH环境变量中。根据您安装Git的方式，这可能是自动完成的，或者Git安装程序可能为您提供了执行此操作的选项。如果这些都没有发生，您将需要在安装后使用以下步骤手动执行此操作。

要测试Git是否在您的路径中，请打开Windows命令提示符并输入git --help然后按Enter。如果您看到可用Git命令的列表，则Git已经在PATH变量中，您无需手动添加它。如果您看到错误消息或该命令没有输出，请按照以下步骤操作。

找到软件安装时放置Git可执行文件的文件夹。
- 右侧的下拉箭头可以显示文件的路径
  
  如果您不确定Git的位置，在默认安装的情况下，您可以在开始菜单找到它，右键单击Git，然后选择“打开文件位置”。
- 如果该操作找到的是Git的快捷方式而不是实际文件位置，请选择快捷方式，右键单击，再次选择“打开文件位置”。
您也可以在互联网搜索相关文档，自行修改PATH变量（下一节以Windows 10系统为例，展示操作步骤）。
将包含Git程序的文件夹添加到PATH变量中。
再次输入git --help命令检查Git是否包含在您的路径中。如果该命令仍不起作用，可能是您没有添加正确的文件路径。

在Windows 10上设置PATH[]

打开控制面板（又名Windows设置），在搜索框内输入“环境变量”。
选择“编辑系统环境变量”，然后单击“系统属性”对话框底部的“环境变量”按钮。
选择Path，单击编辑，然后将Git的路径添加到新的一行。默认安装路径可能是C:\Program Files\Git\bin或%USERPROFILE%\AppData\Local\Programs\Git\bin（比如，Michael Antonacci\AppData\Local\Programs\Git\bin）或C:\Users\...请按照您电脑的具体情况进行操作。
单击“确定”保存添加的路径。
请再次测试路径是否已修改正确。

安装构建工具[]

安装Visual C++ 2015构建工具。

此步骤可以尝试略过，但最近使用Windows安装的贡献者表示，本地实例的成功搭建可能需要安装Habitica的某些依赖项（例如，bcrypt）。对此您如果有任何见解，可以发帖到Aspiring Blacksmith公会。

如果您在没有安装构建工具的情况下在Windows上成功搭建Habitica，且本地实例运行没有错误，也请在公会中告诉我们。

安装MongoDB[]

自2020年7月15日起，无需手动安装MongoDB。当您按照以下步骤操作时，将自动安装专门用于Habitica的MongoDB实例。也不需要使用MongoDB的标准服务器启动命令手动启动Habitica的MongoDB服务器。

（请注意，如果您为Habitica以外的项目运行MongoDB服务器，它将与Habitica自己的MongoDB实例冲突，因此需要在您的Habitica本地实例运行时停止其他运行MongoDB服务器的项目，停止运行的原因将在下文给出。）

安装Node和NPM[]

本节内容将带您完成node和npm的安装。

重要提示：您必须准确安装的node 14和npm 6。如果您使用任何其他的版本，包括更高的版本，您都将遇到错误。如果您需要在您的开发机器上使用不同的版本来完成与Habitica无关的工作，您可以使用nvm来管理这些版本。

请注意，下面的示例命令仅供参考，可能不包含正确版本的npm，因此请务必在运行之前根据需要调整命令。请务必准确安装的node 14和npm 6

下载并运行最新的Node.js msi安装文件。
在该窗口中以管理员身份启动命令窗口：
1. 输入以下命令检查您是否成功安装了正确版本的node（如果版本错误，请重新下载安装）
  node -v
2. 安装NodeJS的同时也会安装npm。请检查安装是否已完成并使用下列命令核对版本：
  npm -v
  - 如果npm的版本不对，请安装正确的版本。例如，如果需要安装npm 6，请输入npm install -g npm@6

注意：

您可能需要将C:\Program Files\nodejs;C:\Program Files\nodejs\node_modules\npm\bin添加到PATH变量中，使node能在命令行使用。

安装剩下的通用组件[]

以管理员身份启动命令窗口。

执行该命令：
npm install -g mocha

备注：如果您查看Habitica仓库的README文件，您会看到它链接的各类服务，例如Greenkeeper。您不需要在本地搭建中安装它们。

请输入以下指令来安装bcrypt包所需的一些依赖项：
npm install -g node-gyp npm install -g --production windows-build-tools

如果您遇到bcrypt错误，您可能需要安装此处列出的一些额外依赖项：https://github.com/kelektiv/node.bcrypt.js#dependencies。如果您对此有任何反馈或遇到任何问题，请发帖到Aspiring Blacksmiths公会，以便我们改进此文档。

注意
在完成上述步骤后，不要再以管理员身份登录，您使用的计算机账户应该与为Habitica开发代码时使用的账户相同。如果需要提升用户权限，本文将会提醒您使用the Administrator account，除此之外的任何时间，提升的权限会导致问题的发生。

现在请关闭您在之前步骤中打开的所有命令窗口或终端窗口。当您再次需要使用命令/终端窗口时，请打开一个新窗口，以便您的shell环境能检索到目前安装的新软件。

在Github上Fork并Clone项目[]

有多种方法可以获取Habitica代码库的副本，按GitHub上的Fork A Repo进行操作是最简单的方法。

通过跳转https://github.com/HabitRPG/habitica并单击“Fork”按钮来创建Habitica的存储库。这会在您自己的GitHub帐户中创建Habitica存储库的副本。
1. 如果您之前已经对存储库进行了fork，请确保您的fork是最新的。
在您的机器上，打开命令提示符或终端窗口，然后切换到你想要复制Habitica代码库的目录。
使用以下命令克隆您的Habitica存储库副本（将“YourUsername”替换为您的GitHub用户名）。这会将Habitica的代码复制到您的机器上，将存储库放入当前目录下的新“habitica”目录中。
git clone https://github.com/YourUsername/habitica.git
切换到上述步骤创建的“habitica”目录：
cd habitica
除非另有说明，否则请停留在该目录中，以执行此页面上的所有后续操作。
配置Git以将你的fork与Habitica的存储库同步。
git remote add upstream https://github.com/HabitRPG/habitica.git
通过输入git remote -v验证所有设置是否正确，除了您的GitHub用户名，其他输出内容应与下文一致：

  origin   https://github.com/YourUsername/habitica.git (fetch)
  origin   https://github.com/YourUsername/habitica.git (push)
  upstream https://github.com/HabitRPG/habitica.git (fetch)
  upstream https://github.com/HabitRPG/habitica.git (push)

留在正确的分支和目录中[]

克隆Habitica的存储库后，默认情况下您将位于develop分支。这是在本地安装Habitica时使用的正确分支。如果您不小心切换到其他分支，那必须在继续安装前使用git checkout develop切换回develop分支。您可以使用git branch检查您所在的分支（旁边带有星号的分支是您当前所在的分支）。

完成上述所有步骤后，您将进入Habitica的顶级目录。除非另有说明，否则您必须保留在该目录中以执行此页面上的所有后续步骤。下文的所有命令都是基于您位于该目录的情况下编写的。如果您出于任何原因更改该目录，请在继续执行此页面上的说明之前更改回该目录。如果您想检查您是否在正确的目录中，请查找名为config.json.example的文件 - 如果您在当前目录中看到该文件，那么您就在正确的目录中。

Habitica初始化配置[]

通过复制（而不是重命名）示例文件来创建您自己的config.json配置文件副本：
copy config.json.example config.json

如有需要，请编辑config.json：

通常您无需更改该文件，如有需要，您随时可以对其编辑。
一般只有在更改Habitica的Express服务器使用的端口时才需要编辑config.json。默认情况下，它使用端口3000，除非您计算机上运行的其他软件正在使用相同的端口，否则无需修改它。如果端口使用冲突，请在config.json中找到BASE_URL和PORT行并将端口更改为合适的数字。两者需使用相同的数字。
无需更改ADMIN_EMAIL的值。它已被弃用，将来可能会被删除。
请不要编辑config.json.example。

通过执行mkdir website\build
创建目录如果此操作报错，请忽略该错误并继续下一步。

请将任何可能正在读取存储库本地副本的应用程序或文件资源管理器窗口关闭。如果任何文件被任何Windows进程锁定，则以下安装步骤可能会失败。对于杀毒软件，请在其设置中排除Habitica文件夹，以便在安装完成前杀毒软件不会扫描存储库。更多相关内容，请参阅GitHub评论。

安装Habitica特定组件[]

安装Habitica特定的npm包：
npm install

如果该命令显示错误，请尝试重新运行它两到三次，以防故障是由于从Internet检索包时超时造成的。

如果这没有帮助，请运行npm ci，这将删除node_modules文件夹并重新安装所有软件包，安装过程中的差异请参阅some differences in the installation process。

如果仍然报错，或者此页面上的任何后续步骤显示缺少模块或文件，请按照第一节“为排除故障做准备”中的内容进行操作。

启动Habitica Web服务器[]

如果您为Habitica以外的项目运行MongoDB服务器，它将与Habitica自己的MongoDB实例发生冲突。现在请使用MongoDB的标准服务器停止命令停止该实例（您可以在运行完Habitica的服务器之后重新启动它。）
确保您的计算机或虚拟机上设置的时间正确，否则您将看到“RequestTimeTooSkewed”错误。
在一个命令提示符或终端中：
- 使用npm run mongo:dev启动Habitica自己的MongoDB实例
- 等到您看到Started replica set on "mongodb://localhost:27017?replicaSet=rs"，然后再继续下一步。（第一次运行时，它会在Habitica的目录中下载并安装MongoDB，所以这需要几分钟。）
- 在Mongo命令完成运行前，请不要再操作此终端。
在第二个命令提示符或终端窗口中，使用以下命令启动Habitica Web服务器：
npm start
在第三个命令提示符或终端窗口中，使用npm run client:dev构建网站客户端。这将在您保存对客户端文件的更改时自动重建，同时遇到任何错误都会告知您。
参照下文，查看这三个命令的输出。如果您已经发现错误，这部分可能会对您有帮助。

查看服务器输出[]

npm run mongo:dev命令的输出应该类似于下面的示例。您可能会看到细微的差异（例如，不同的版本号）。

> habitica@4.148.1 mongo:dev /home/alys/code/habitica > run-rs -v 4.2.8 -l ubuntu1804 --keep --dbpath mongodb-data --number 1 --quiet Skipping purge Running '/home/alys/code/habitica/node_modules/run-rs/4.2.8/mongod' [ 27017 ] Restarting replica set... Started replica set on "mongodb://localhost:27017?replicaSet=rs"

启动服务器的输出（来自npm start命令）应该类似于下面的示例。您可能会在系统中看到细微的差异（例如，不同的日期、时间和版本号）。斜体文字描述了您可能看到的信息类型，仅供参考。

> habitica@4.116.8 start /home/username/habitica > gulp nodemon [18:39:02] Using gulpfile ~/habitica/gulpfile.js [18:39:02] Starting 'nodemon'... [18:39:02] Finished 'nodemon' after 25 ms [18:39:02] [nodemon] 1.19.4 [18:39:02] [nodemon] to restart at any time, enter `rs` [18:39:02] [nodemon] watching dir(s): [directory path(s) here] [18:39:02] [nodemon] watching extensions: js,mjs,json [18:39:02] [nodemon] starting `node ./website/server/index.js` (node:3348) [ "DeprecationWarnings" might be here and/or below; they do not indicate an error ] 2019-10-20T08:39:08.767Z - info: Express server listening on port 3000 2019-10-20T08:39:08.960Z - info: Connected with Mongoose.

构建网站客户端的输出（来自npm run client:dev命令）分两个阶段出现，首先是构建客户端时的一些初始文本（可能会从屏幕上清除），接下来会显示客户端一切就绪。

第一阶段应该类似于下面的示例，最后一行快速变化。斜体文字描述了您可能看到的信息类型，仅供参考。

> habitica@4.116.8 client:dev /home/username/habitica > cd website/client && npm run serve > habitica-client@1.0.0 serve /home/username/habitica/website/client > vue-cli-service serve INFO Starting development server... 42% building 2584/2635 modules 51 active ... [file paths here]

第二阶段应该类似于下面的示例。斜体部分仅供参考。

DONE Compiled successfully in 12652ms 6:56:45 PM App running at: - Local: http://localhost:8080/ - Network: http://your.IP.address:8080/ Note that the development build is not optimized. To create a production build, run npm run build. [仅供参考]

如果您看到与以上示例不同的输出，特别是发现错误或者显著的警告信息时，在继续下一步之前，请自行解决或使用本文顶部的“为排除故障做准备”部分中的指南提交错误报告。下文例举了典型的的错误信息：

错误示例：: 请首先检查是否使用了正确版本的node和npm，如上文中安装Node和NPM这一节所述。如果您使用了nvm，请注意版本切换。因为它可能在您没有意识到的情况下切换了版本。
ECONNREFUSED and/or Proxy error: Could not proxy request /api/v..... from localhost:8080 to http://localhost:3000: 如上文中安装MongoDB这一节所述，检查您的本地数据库服务器是否正在运行。
npm ERR! code ELIFECYCLE: 如果您使用的是Linux或Docker，则此错误很可能是因为nodemon需要的文件监视程序比inotify提供的要多。在Ubuntu和类似的Linux发行版上，您可以使用以下命令执行此操作：
echo fs.inotify.max_user_watches=524288 | sudo tee /etc/sysctl.d/50-max-user-watches.conf && sudo sysctl --system
对于其他发行版，请参阅您的发行版的文档。此issue包括了相关错误示例。

如果npm run mongo:dev和npm start以及npm run client:dev的输出看起来没问题，即可进行下一步——网站测试。如果您不太确定本地配置是否良好，请继续运行程序，直到网站发生故障，再解决输出中显示的问题。

在浏览器中测试网站[]

打开浏览器访问http://localhost:8080以测试应用程序。该网站与https://habitica.com类似，仅在左下角的“任务”页面上增加了“调试”菜单（请暂时忽略它；它在本页末尾链接的文档中进行了描述，您暂时不会用到它）。

如果您已进入网站的首页但网站没有完成加载，或者打开登录页面但登录按钮没有任何作用，请清除“localhost”域的本地存储。您可以通过单击http://localhost:8080/static/clear-browser-data上的红色“清除数据”按钮或使用浏览器的JavaScript控制台（有关如何在默认浏览器中清除本地存储的信息，请百度一下）然后重新加载首页。

您可以创建一个或多个帐户进行测试。本地安装使用的数据库托管在您的机器上；它与Habitica本身使用的数据库不同，因此您无法使用普通的Habitica帐户。

后续步骤：使用本地安装[]

现在您已在本地安装了Habitica网站，请阅读使用您的本地安装来修改Habitica的网站和API以了解如何贡献代码。

更多内容请参阅铁匠指南，其中包括软件所用的技术、Habitica代码结构、如何做出贡献以及其他相关信息。