0. 目录
- 1. 前言
- 2. 环境准备（Windows10下）
- 2.1 安装nvm
- 2.2 git和docker安装
- 3. 创建模板项目
- 3.1 典型错误: fails on the `yarn install` step
- 3.2 再次启动
- 3.3 验证
- 4. 相关
1. 前言
本不想写这篇，因为看着官网文档写着挺简单的，但实际操作起来却是步步坑。于是怒而把过程细节重演一次并记录下来，于是就有了这篇。
2. 环境准备（Windows10下）
按照官网给出的Prerequisites，结合自身的实际情况，需要准备如下内容：
- Git-for-windows 。 可以同时满足GIT和Linux环境的要求。
- nvm - Node Version Manager 。同时满足nodejs和yarn的安装需求；而且可以在多个版本之间自由切换，相较于独立安装nodejs方便不少。
- 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. 先安装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
- 另外的方案是分开安装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. 相关
- backstage-getting-started
- isolated-vm#requirements
- VSCode - plugin - backstage
