1. 前言

本不想写这篇，因为看着官网文档写着挺简单的，但实际操作起来却是步步坑。于是怒而把过程细节重演一次并记录下来，于是就有了这篇。

2. 环境准备（Windows10下）

按照官网给出的Prerequisites，结合自身的实际情况，需要准备如下内容：

1. Git-for-windows 。 可以同时满足GIT和Linux环境的要求。
2. nvm - Node Version Manager 。同时满足nodejs和yarn的安装需求；而且可以在多个版本之间自由切换，相较于独立安装nodejs方便不少。
3. Docker Desktop。Windows下的Docker自然就是选择它了。

2.1 安装nvm

这一步将安装关键的nodejs和yarn。

######################################### 1. 安装
# 如果这一步报错"Could not resolve host: raw.githubusercontent.com", 那就干脆浏览器下载这个install.sh脚本, 然后再本地执行
# 官方说明: https://github.com/nvm-sh/nvm?tab=readme-ov-file#wsl-troubleshooting
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

######################################### 2. 配置
# 以上 install.sh 脚本执行后，不出意外出现如下提示:
#	$ ./install.sh
#	=> Downloading nvm from git to '/c/Users/lqzkc/.nvm'
#	=> Cloning into 'C:/Users/lqzkc/.nvm'...
#	remote: Enumerating objects: 365, done.
#	remote: Counting objects: 100% (365/365), done.
#	remote: Compressing objects: 100% (313/313), done.
#	remote: Total 365 (delta 43), reused 166 (delta 26), pack-reused 0
#	Receiving objects: 100% (365/365), 365.08 KiB | 1.28 MiB/s, done.
#	Resolving deltas: 100% (43/43), done.
#	* (HEAD detached at FETCH_HEAD)
#	  master
#	=> Compressing and cleaning up git repository
#	
#	=> Profile not found. Tried ~/.bashrc, ~/.bash_profile, ~/.zprofile, ~/.zshrc, and ~/.profile.
#	=> Create one of them and run this script again
#	   OR
#	=> Append the following lines to the correct file yourself:
#	
#	export NVM_DIR="$HOME/.nvm"
#	[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
#	
#	=> Close and reopen your terminal to start using nvm or run the following to use it now:
#	
#	export NVM_DIR="$HOME/.nvm"
#	[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm

# 2.1 按照上面命令行输出的提示, 创建一个 ~/.profile文件, 并写入其给出的内容; 
vi ~/.profile

# 2.2 重新打开git命令行, 执行上述内容
export NVM_DIR="$HOME/.nvm"
	[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm

######################################### 3. 验证
# 验证nvm安装成功
nvm -v

# 已经安装了哪些版本的nodejs
nvm ls

# 卸载指定版本nodejs
nvm uninstall 16

# 当前使用的nodejs版本
nvm current

# 安装指定版本nodejs
#	注意：如果你之前配置过nodejs, 可能出现如下提示. 按照提示操作即可.
nvm install 18
    Downloading and installing node v18.20.2...
    Downloading https://nodejs.org/dist/v18.20.2/node-v18.20.2-win-x64.zip...
    ######################################################################## 100.0%
    Computing checksum with sha256sum
    Checksums matched!
    Your user’s .npmrc file (${HOME}/.npmrc)
    has a `globalconfig` and/or a `prefix` setting, which are incompatible with nvm.
    Run `nvm use --delete-prefix v18.20.2` to unset it.
nvm use 18      # 指定使用指定版本的nodejs
node -v         # 验证node安装成功
npm -v          

# 设置默认使用的nodejs版本
nvm alias default 18.20.2

######################################### 4. 安装yarn
# https://classic.yarnpkg.com/en/docs/install#windows-stable
npm install --global yarn

yarn -v

2.2 git和docker安装

参考上方给出的链接地址下载安装即可。相关的文档一大堆，这里不再重复，避免偏离本文重点。

3. 创建模板项目

相关的官方文档写得挺简单：

# 键入这一条命令， 在弹出的输入行中键入你想要创建的项目名，例如my-backstage-app
npx @backstage/create-app@latest
# 启动项目
#	如果一切顺利, 该命令执行完毕之后浏览器将自动打开 localhost:3000 地址.
cd my-backstage-app
yarn dev

3.1 典型错误: fails on the yarn install step

这应该算是本文出现的最大原因。

解决的方案其实官方文档里已经给出了 —— 安装node-gyp的依赖项python和visualstudio2022-workload-vctools：

我这里其实就是将其简化下，并且给出几条优化建议：

1. 最简单的安装方式自然是如这里建议的：

# 1. 先安装Chocolatey。以管理员权限打开cmd.exe命令行提示
@powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin

choco -v   # 验证

# 2. 使用Chocolatey安装python和visualstudio2022-workload-vctools
#	注意：这里建议以管理员身份打开powershell，并且架起全局梯子, 节点选美丽国
choco install python visualstudio2022-workload-vctools -y

2. 另外的方案是分开安装python和visualstudio2022-workload-vctools。很多时候我们是有python编程需求的，所以一般都是建议使用pyenv-win。而对于visualstudio2022-workload-vctools的安装，依然是参考官方文档。

3.2 再次启动

cd my-backstage-app
yarn install
yarn tsc

yarn dev

3.3 验证

http://localhost:3000/

4. 相关

1. backstage-getting-started
2. isolated-vm#requirements
3. VSCode - plugin - backstage