diff --git a/README.md b/README.md index 41be94b..f9e7c5c 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,15 @@ Behavior that only exists on `main` and not in the latest release is marked "Unr pages below. [docs/changes.md](docs/changes.md) lists it, and [docs/install-from-source.md](docs/install-from-source.md) gets you `main`. +## Use cases + +By hand, Flutter is a download, an unpack and an edit of `~/.bashrc`, again for every machine and +every version. With the plugin it is `vfox install` and `vfox use`, and `~/.bashrc` has the one +line that hooks vfox into your shell and nothing about Flutter. [docs/use-cases.md](docs/use-cases.md) +sets the two side by side and goes through the situations the plugin is for: a new machine, or one +that has a hand-made install; projects and teams that each use their own Flutter version; upgrading +and going back; trying a beta; a mirror in China; scripts and IDEs; and ARM64 machines. + ## Versions and names A version is a release as `vfox search flutter` prints it: `3.47.4`, or a beta such as diff --git a/README_CN.md b/README_CN.md index d31b059..91ac912 100644 --- a/README_CN.md +++ b/README_CN.md @@ -38,6 +38,10 @@ dart --version 只存在于 `main`、还没进入最新发布版的行为,在下面各页里标有“未发布”。完整列表见 [docs/zh-CN/changes.md](docs/zh-CN/changes.md),想直接用上 `main`,见 [docs/zh-CN/install-from-source.md](docs/zh-CN/install-from-source.md)。 +## 使用场景 + +手动安装 Flutter,就是下载、解压,再改一次 `~/.bashrc`,每台机器、每个版本都要重来一遍。用这个插件只需要 `vfox install` 和 `vfox use`,`~/.bashrc` 里只有把 vfox 挂到 Shell 上的那一行,没有任何和 Flutter 有关的内容。[docs/zh-CN/use-cases.md](docs/zh-CN/use-cases.md) 把两种做法并排放在一起,并逐个讲了插件适用的场景:新机器,或者已经手动装过 Flutter 的机器;各个项目、整个团队各用各的 Flutter 版本;升级与回退;试用 beta;中国的镜像;脚本与 IDE;以及 ARM64 机器。 + ## 版本与命名 版本就是 `vfox search flutter` 打印出的发布版本:`3.47.4`,或者 `3.50.0-0.1.pre` 这样的 beta。后面加 `-x64` 或 `-arm64`,表示要这个架构而不是本机架构;`stable` 和 `beta` 代表该渠道当前指向的版本。版本必须整串匹配,所以 `flutter@3.47` 不会选中最新的 3.47.x。`vfox use`、`vfox uninstall` 和 `vfox exec` 要写已安装的名字,也就是 `vfox list flutter` 里显示的那个。`flutter@latest` 是列表的第一行,即最新的稳定版。名字、安装后的命名和列表的顺序见 [docs/zh-CN/versions.md](docs/zh-CN/versions.md)。 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 704e1e0..4a6342f 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -166,7 +166,7 @@ Minutes later the same API answered in a second. Without a 429 a failing request - **A release you expect is missing from `vfox search`.** vfox keeps the result for 12 hours. `vfox config cache.availableHookDuration 0` turns the cache off. Flutter's index may not have it yet either, or your mirror's copy may not. - **`3.47.4` and `3.47.4-x64` are two installs.** On an x64 machine they are the same Flutter, see [versions.md](versions.md#installed-names). - **Uninstalling a version switched the global one.** vfox selects the first entry left in `vfox list flutter` when you uninstall the version in use, and that can be a beta. -- **`flutter` is a different Flutter than `vfox use` says.** Another Flutter earlier in your `PATH` wins, such as a manual install in `~/develop/flutter` or one from a package manager. `command -v flutter` shows which one runs, and its path should start with `~/.vfox/sdks/flutter/bin` or, in a project, `.vfox/sdks/flutter/bin`. +- **`flutter` is a different Flutter than `vfox use` says.** Another Flutter earlier in your `PATH` wins, such as a manual install in `~/develop/flutter` or one from a package manager. `command -v flutter` shows which one runs, and its path should start with `~/.vfox/sdks/flutter/bin` or, in a project, `.vfox/sdks/flutter/bin`. A project's choice applies only in the directory that holds its `.vfox.toml`, not in the subdirectories, and vfox changes `PATH` when the prompt is shown, so `cd project && flutter run` on one line still runs the Flutter of the directory you came from, see [use-cases.md](use-cases.md#projects-on-different-flutter-versions). - **Flutter says "A new version of Flutter is available!" and suggests `flutter upgrade`.** Ignore it: `flutter upgrade` moves the SDK under vfox, see [flutter-upgrade.md](flutter-upgrade.md). `vfox install flutter@stable` is the upgrade. `flutter --no-version-check` leaves the banner out. - **`FLUTTER_ROOT` is not set.** The plugin sets only `PATH`. The `flutter` script finds its own directory. - **`dart` is there without a Dart plugin.** The Flutter SDK includes the Dart SDK, and `dart` is in its `bin`. There is no need to add the [vfox-dart](https://github.com/version-fox/vfox-dart) plugin next to it. diff --git a/docs/use-cases.md b/docs/use-cases.md new file mode 100644 index 0000000..5c43558 --- /dev/null +++ b/docs/use-cases.md @@ -0,0 +1,184 @@ +# Use cases + +[中文](zh-CN/use-cases.md) | [English](use-cases.md) + +What the plugin is for, as situations you may be in. Each one gives the commands with the plugin, says what the same takes by hand where that helps, and links to the page that has the details. The commands were run in Bash on Ubuntu 26.04.1 (x64) with vfox 1.0.13 and plugin 0.2.5 on 2026-11-03, when Flutter's release index had `3.47.9` as `stable` and `3.50.0-0.3.pre` as `beta`. What vfox itself does (the shell hook, the scopes, `vfox install --all`) is what 1.0.13 does, and other versions may differ. + +## A new machine + +Installing Flutter by hand is a download, an unpack and an edit of `~/.bashrc`, and the address of the download depends on the operating system, the channel and the version. The plugin does the same with three commands. + +### Ubuntu 26.04.1 + +Execute in Bash, + +```bash +curl --location --output /tmp/flutter_linux.tar.xz https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_3.47.4-stable.tar.xz +mkdir -p ~/develop/ +tar -xf /tmp/flutter_linux.tar.xz -C ~/develop/ +rm -rf /tmp/flutter_linux.tar.xz +echo 'export PATH="$HOME/develop/flutter/bin:$PATH"' >> ~/.bashrc +source ~/.bashrc +``` + +With the plugin that is, + +```bash +vfox add flutter +vfox install flutter@3.47.4 +vfox use --global flutter@3.47.4 +``` + +Both end with the same Flutter on the `PATH`, and `flutter --version --no-version-check` starts with `Flutter 3.47.4 • channel stable • https://github.com/flutter/flutter.git`. The archive is the same file, too. Step by step: + +| By hand | With the plugin | +| --- | --- | +| Build the address of the archive from the operating system, the channel and the version, and `curl` it | `vfox install flutter@3.47.4` finds the release in Flutter's release index, which lists the archive for your operating system and CPU | +| Nothing compares the download with a checksum | vfox verifies it against the SHA-256 of the index and prints `Verifying checksum ...` | +| `mkdir -p ~/develop/` and `tar -xf ...` put one Flutter in one place, `~/develop/flutter` | Every version gets a directory of its own, `~/.vfox/cache/flutter/v-3.47.4/flutter-3.47.4/` | +| `rm -rf /tmp/flutter_linux.tar.xz` | vfox removes the archive after unpacking | +| `echo ... >> ~/.bashrc` and `source ~/.bashrc` | `vfox use --global flutter@3.47.4` | + +The last row is the point. vfox has to be hooked into your shell once, with a line that has nothing to do with Flutter and that every SDK you manage with vfox shares (vfox's [quick start](https://vfox.dev/guides/quick-start.html) has the line for other shells): + +```bash +echo 'eval "$(vfox activate bash)"' >> ~/.bashrc +source ~/.bashrc +``` + +After that nothing about Flutter is ever added to `~/.bashrc`, edited in it or removed from it: not when you install another version, not when you switch, not when you uninstall. `vfox use` stops in a shell without the hook: `vfox requires hook support. Please ensure vfox is properly initialized with 'vfox activate'`. The hook runs before each prompt, so a terminal that was open before you switched picks the new choice up at its next prompt. By hand every open terminal has to run `source ~/.bashrc` or be restarted, and the `echo` line puts the `PATH` line in a second time when you run it a second time. + +On macOS and Windows the steps by hand are the same, with the `.zip` for your CPU (`flutter_macos_arm64_3.47.4-stable.zip`, `flutter_windows_3.47.4-stable.zip`) and `~/.zshrc` or your user `Path` variable. The three commands with the plugin stay the same, and only the line that hooks vfox into your shell depends on the shell, see [platforms.md](platforms.md). + +## You already installed Flutter by hand + +Until you select a version with vfox, `flutter` is still the copy in `~/develop/flutter`. Install the version you use, select it, and ask which `flutter` runs. + +### Ubuntu 26.04.1 + +Execute in Bash, + +```bash +vfox install flutter@3.47.4 +vfox use --global flutter@3.47.4 +command -v flutter +``` + +`command -v flutter` prints `~/.vfox/sdks/flutter/bin/flutter` with your home directory spelled out. vfox puts its directory in front of the old one in `PATH`, whether the `PATH` line comes before or after the hook in `~/.bashrc`, so the new Flutter runs without any other change. To tidy up, look up the old line: + +```bash +grep -n 'develop/flutter/bin' ~/.bashrc +``` + +Delete the line it prints in your editor, open a new terminal (the one you are in still has the old `PATH`), and remove the old SDK: + +```bash +rm -rf ~/develop/flutter +``` + +Flutter's own settings (`~/.config/flutter`) and the pub cache (`~/.pub-cache`) are in your home directory, not in the SDK, so they carry over to the new install. + +## Projects on different Flutter versions + +An older app has to stay on `3.44.0` while a new one uses `3.47.4`. By hand that is two directories and a `PATH` that you change whenever you switch. With the plugin each version is installed once, and each project says which one it uses: + +```bash +vfox install flutter@3.44.0 +vfox install flutter@3.47.4 +cd ~/work/legacy_app +vfox use --project flutter@3.44.0 +cd ~/work/new_app +vfox use --project flutter@3.47.4 +``` + +`vfox use --project` writes the choice to `.vfox.toml` in the project directory (`flutter = "3.44.0"` under `[tools]`) and links the SDK at `.vfox/sdks/flutter`. While you are in that directory `flutter` is the project's Flutter, and in any other directory it is the one you chose with `--global`: + +``` +$ cd ~/work/legacy_app +$ flutter --version --no-version-check | sed -n 1p +Flutter 3.44.0 • channel stable • https://github.com/flutter/flutter.git +$ cd ~/work/new_app +$ flutter --version --no-version-check | sed -n 1p +Flutter 3.47.4 • channel stable • https://github.com/flutter/flutter.git +``` + +Every version is a full SDK on disk, see [platforms.md](platforms.md#requirements). Three things about the scopes: + +- **The choice applies in the directory that holds `.vfox.toml`, not in its subdirectories.** In `~/work/legacy_app/lib`, `flutter` comes from the session or the global choice. `vfox current flutter` shows which version applies where you are. +- **The hook changes `PATH` when the prompt is shown.** `cd ~/work/new_app && flutter run` on one line still runs the Flutter of the directory you came from. `cd` first and run `flutter` after. +- **`.vfox/` stays out of git.** vfox adds it to the `.gitignore` of the project when there is one and prints `Added '.vfox/' to .gitignore`. It does not create a `.gitignore`. + +## A team on one Flutter + +Commit `.vfox.toml` and the `.gitignore` change, and everybody builds the project with the Flutter it was written for, and not with whichever one their machine happens to have. Someone who clones the project runs this in its directory: + +```bash +vfox add flutter +vfox install --all +vfox use --project flutter@3.44.0 +``` + +`vfox install --all` installs the versions that `.vfox.toml` lists, and asks first (`--yes` skips the question). It does not select them. That is what `vfox use --project` is for, with the version from `.vfox.toml`, and it writes the same `.vfox.toml` again, so git has nothing new to commit. `vfox add flutter` comes first because on a machine without the plugin, `vfox install --all` only adds the plugin, and the SDK follows with the next one. + +## Upgrading, and going back + +A new Flutter is installed next to the old one, and nothing changes until you select it. `vfox install flutter@stable` installs the release the stable channel points to (`3.47.9` on 2026-11-03): + +```bash +vfox install flutter@stable +vfox use --global flutter@3.47.9 +``` + +If the new release breaks something, the old one is still installed: + +```bash +vfox use --global flutter@3.47.4 +``` + +`vfox uninstall flutter@3.47.9` removes the release you do not want, and only its directory. `flutter upgrade` changes the SDK in place instead, where vfox does not see it, and what `vfox list flutter` says is then no longer what runs, see [flutter-upgrade.md](flutter-upgrade.md). That is why you can ignore the "A new version of Flutter is available!" box that suggests `flutter upgrade`: `vfox install flutter@stable` is the upgrade, see [troubleshooting.md](troubleshooting.md#things-that-look-wrong-and-are-not). + +## Trying a beta in one terminal + +```bash +vfox install flutter@beta +vfox use --session flutter@3.50.0-0.3.pre +``` + +The session choice is for this terminal. The others keep the version they had, and a new terminal does not have the beta. The beta stays installed until you `vfox uninstall flutter@3.50.0-0.3.pre`. `flutter@beta` is replaced by the release it points to (`3.50.0-0.3.pre` on 2026-11-03), and `vfox use` takes that name, see [channels.md](channels.md#use-the-version-not-the-channel). + +## A mirror + +When `storage.googleapis.com` is slow or cannot be reached, the address by hand changes its host, for example to the CFUG mirror: + +```bash +curl --location --output /tmp/flutter_linux.tar.xz https://storage.flutter-io.cn/flutter_infra_release/releases/stable/linux/flutter_linux_3.47.4-stable.tar.xz +``` + +With the plugin you set `FLUTTER_STORAGE_BASE_URL` once, and every install takes the index and the archive from there: + +```bash +export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn +vfox install flutter@3.47.4 +``` + +The `flutter` tool reads the same variable for what it downloads when you first use it, so keep it set in your shell and not only while you install. How to make it permanent, the other mirrors, and `PUB_HOSTED_URL` for packages, which the plugin does not touch, are in [mirror.md](mirror.md). + +## Scripts, containers and IDEs + +`vfox use` needs the hook, which a script, a container build or a CI step does not have. `vfox exec` runs one command with the Flutter you name, hook or not: + +```bash +vfox exec flutter@3.47.4 -- flutter --version --no-version-check +``` + +An IDE that should follow your global choice can take `~/.vfox/sdks/flutter` as its Flutter SDK path, and then needs no change when you switch versions. See [Where Flutter is](troubleshooting.md#where-flutter-is). + +## ARM64 machines and OpenHarmony + +Google publishes no Flutter archive for Linux ARM64 or Windows ARM64, so by hand Flutter comes from a `git clone` of `flutter/flutter`. The plugin does that for the plain name: + +```bash +vfox install flutter@3.47.4 +``` + +It offers the releases whose Flutter tool runs with a native Dart SDK there, see [arm64.md](arm64.md). The OpenHarmony fork of Flutter on gitcode.com installs the same way (`vfox install flutter@3.41.10-ohos-1.0.0`), see [ohos.md](ohos.md). diff --git a/docs/versions.md b/docs/versions.md index 04fbcb9..5cade6d 100644 --- a/docs/versions.md +++ b/docs/versions.md @@ -96,7 +96,7 @@ Pick the scope with `vfox use`'s flags: `--global`, `--project` or `--session`. | `--project` | `.vfox.toml` in the current directory | `.vfox/sdks/flutter/bin` in that directory | | `--session` | the current shell only | a directory under `~/.vfox/tmp` | -`.vfox.toml` holds the installed name (`flutter = "3.47.4"`). Commit it, so that the project builds with one Flutter for everybody, and keep `.vfox/` out of git: vfox does not add it to your `.gitignore`. vfox also reads an asdf `.tool-versions` (`flutter 3.47.4`) when its `legacyVersionFile.enable` setting is on, which it is by default in vfox 1.0.13. The plugin has no legacy file of its own, so `.fvmrc` and FVM's `.fvm` directory are not read. +`.vfox.toml` holds the installed name (`flutter = "3.47.4"`). Commit it, so that the project builds with one Flutter for everybody, and keep `.vfox/` out of git: vfox 1.0.13 adds it to the `.gitignore` of the project when there is one (it prints `Added '.vfox/' to .gitignore`), and does not create a `.gitignore`. The choice applies in the directory that holds `.vfox.toml` and not in its subdirectories, where `flutter` comes from the session or the global choice, see [use-cases.md](use-cases.md#projects-on-different-flutter-versions). vfox also reads an asdf `.tool-versions` (`flutter 3.47.4`) when its `legacyVersionFile.enable` setting is on, which it is by default in vfox 1.0.13. The plugin has no legacy file of its own, so `.fvmrc` and FVM's `.fvm` directory are not read. The plugin adds `/bin` to `PATH`. That puts `flutter` and `dart` on it. It sets no `FLUTTER_ROOT`, and `~/.pub-cache/bin`, where `dart pub global activate` puts executables, stays yours to add. diff --git a/docs/zh-CN/troubleshooting.md b/docs/zh-CN/troubleshooting.md index 40188e9..d2a9746 100644 --- a/docs/zh-CN/troubleshooting.md +++ b/docs/zh-CN/troubleshooting.md @@ -166,7 +166,7 @@ gitcode.com 限制匿名客户端的请求次数。超出限制时它回答 HTTP - **预期的版本在 `vfox search` 里没有。** vfox 会把结果缓存 12 小时。`vfox config cache.availableHookDuration 0` 可以关掉缓存。也可能是 Flutter 的索引里还没有它,或者你的镜像那份里还没有。 - **`3.47.4` 和 `3.47.4-x64` 是两份安装。** 在 x64 机器上它们是同一个 Flutter,见 [versions.md](versions.md#已安装的名称)。 - **卸载一个版本后,全局版本被换掉了。** 卸载正在使用的版本时,vfox 会选 `vfox list flutter` 里剩下的第一项,那可能是个 beta。 -- **`flutter` 运行的不是 `vfox use` 选的那个 Flutter。** `PATH` 里更靠前的另一个 Flutter 会胜出,比如手动装在 `~/develop/flutter` 的,或者包管理器装的。`command -v flutter` 能看到实际运行的是哪一个,它的路径应当以 `~/.vfox/sdks/flutter/bin` 开头,在项目里则是 `.vfox/sdks/flutter/bin`。 +- **`flutter` 运行的不是 `vfox use` 选的那个 Flutter。** `PATH` 里更靠前的另一个 Flutter 会胜出,比如手动装在 `~/develop/flutter` 的,或者包管理器装的。`command -v flutter` 能看到实际运行的是哪一个,它的路径应当以 `~/.vfox/sdks/flutter/bin` 开头,在项目里则是 `.vfox/sdks/flutter/bin`。项目里的选择只在 `.vfox.toml` 所在的目录生效,子目录里不生效;vfox 又是在提示符出现时才改 `PATH`,所以把 `cd project && flutter run` 写在一行里,运行的还是上一个目录的 Flutter,见 [use-cases.md](use-cases.md#项目用不同的-flutter-版本)。 - **Flutter 说“A new version of Flutter is available!”并建议执行 `flutter upgrade`。** 别理它:`flutter upgrade` 会在 vfox 的背后改动 SDK,见 [flutter-upgrade.md](flutter-upgrade.md)。`vfox install flutter@stable` 才是升级。`flutter --no-version-check` 可以不显示这条提示。 - **`FLUTTER_ROOT` 没有设置。** 插件只设置 `PATH`。`flutter` 脚本会自己找到它所在的目录。 - **没有装 Dart 插件,`dart` 却在。** Flutter SDK 包含 Dart SDK,`dart` 就在它的 `bin` 里。不需要再另外添加 [vfox-dart](https://github.com/version-fox/vfox-dart) 插件。 diff --git a/docs/zh-CN/use-cases.md b/docs/zh-CN/use-cases.md new file mode 100644 index 0000000..45f7b30 --- /dev/null +++ b/docs/zh-CN/use-cases.md @@ -0,0 +1,184 @@ +# 使用场景 + +[中文](use-cases.md) | [English](../use-cases.md) + +下面按你可能遇到的场景,讲这个插件用在哪些地方。每个场景都给出用插件的命令,在有助于理解的地方说明手动做同样的事要怎么做,并链接到有详细说明的那一页。命令是 2026-11-03 在 Ubuntu 26.04.1(x64)的 Bash 里,用 vfox 1.0.13 和插件 0.2.5 运行的,当时 Flutter 发布索引里的 `stable` 是 `3.47.9`,`beta` 是 `3.50.0-0.3.pre`。vfox 自己的行为(Shell 钩子、作用域、`vfox install --all`)按 1.0.13 的实际表现来写,其他版本可能不同。 + +## 一台新机器 + +手动安装 Flutter,就是下载、解压,再改一次 `~/.bashrc`,而且下载地址要根据操作系统、渠道和版本自己拼。插件用三条命令完成同样的事。 + +### Ubuntu 26.04.1 + +在 Bash 中执行: + +```bash +curl --location --output /tmp/flutter_linux.tar.xz https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_3.47.4-stable.tar.xz +mkdir -p ~/develop/ +tar -xf /tmp/flutter_linux.tar.xz -C ~/develop/ +rm -rf /tmp/flutter_linux.tar.xz +echo 'export PATH="$HOME/develop/flutter/bin:$PATH"' >> ~/.bashrc +source ~/.bashrc +``` + +用插件就是: + +```bash +vfox add flutter +vfox install flutter@3.47.4 +vfox use --global flutter@3.47.4 +``` + +两种做法最后 `PATH` 上都是同一个 Flutter,`flutter --version --no-version-check` 的第一行都是 `Flutter 3.47.4 • channel stable • https://github.com/flutter/flutter.git`,下载的压缩包也是同一个文件。逐步对照: + +| 手动 | 用插件 | +| --- | --- | +| 根据操作系统、渠道和版本拼出压缩包的地址,再用 `curl` 下载 | `vfox install flutter@3.47.4` 在 Flutter 的发布索引里找到这个版本,索引里列有对应你的操作系统和 CPU 的压缩包 | +| 没有哪一步会拿校验和比对下载的文件 | vfox 用索引里的 SHA-256 校验,并打印 `Verifying checksum ...` | +| `mkdir -p ~/develop/` 和 `tar -xf ...` 把一个 Flutter 放在一个固定的位置 `~/develop/flutter` | 每个版本都有自己的目录 `~/.vfox/cache/flutter/v-3.47.4/flutter-3.47.4/` | +| `rm -rf /tmp/flutter_linux.tar.xz` | vfox 解压之后自己删除压缩包 | +| `echo ... >> ~/.bashrc` 和 `source ~/.bashrc` | `vfox use --global flutter@3.47.4` | + +最后一行才是关键。vfox 本身需要挂到 Shell 上,只做一次,这一行和 Flutter 无关,所有交给 vfox 管理的 SDK 共用它(其他 Shell 的写法见 vfox 的[快速入门](https://vfox.dev/zh-hans/guides/quick-start.html)): + +```bash +echo 'eval "$(vfox activate bash)"' >> ~/.bashrc +source ~/.bashrc +``` + +此后,`~/.bashrc` 里不会再添加、修改或删除任何和 Flutter 有关的内容:装另一个版本、切换版本、卸载,都不用。在没有挂钩子的 Shell 里,`vfox use` 会直接停下:`vfox requires hook support. Please ensure vfox is properly initialized with 'vfox activate'`。钩子在每次出现提示符之前运行,所以切换之前就已经开着的终端,到下一个提示符就会采用新的选择。手动的话,每个开着的终端都得执行 `source ~/.bashrc` 或者重新打开,而且 `echo` 那一行执行第二次,`PATH` 那一行就会被再写进去一次。 + +在 macOS 和 Windows 上,手动的步骤是一样的,换成对应你 CPU 的 `.zip`(`flutter_macos_arm64_3.47.4-stable.zip`、`flutter_windows_3.47.4-stable.zip`),改的是 `~/.zshrc` 或者你的用户 `Path` 变量。用插件的三条命令不变,只有把 vfox 挂到 Shell 上的那一行因 Shell 而异,见 [platforms.md](platforms.md)。 + +## 已经手动装过 Flutter + +在你用 vfox 选定版本之前,`flutter` 仍然是 `~/develop/flutter` 里的那一份。装上你在用的版本,选中它,再问一下实际运行的是哪个 `flutter`。 + +### Ubuntu 26.04.1 + +在 Bash 中执行: + +```bash +vfox install flutter@3.47.4 +vfox use --global flutter@3.47.4 +command -v flutter +``` + +`command -v flutter` 打印的是 `~/.vfox/sdks/flutter/bin/flutter`,其中的主目录会展开成完整路径。vfox 把自己的目录放在 `PATH` 里旧目录的前面,不管 `PATH` 那一行在 `~/.bashrc` 里是在钩子之前还是之后,所以不用改别的,新的 Flutter 就会运行。要收拾旧的,先找到旧的那一行: + +```bash +grep -n 'develop/flutter/bin' ~/.bashrc +``` + +在编辑器里删掉它打印出来的那一行,再打开一个新终端(你现在这个还带着旧的 `PATH`),然后删除旧的 SDK: + +```bash +rm -rf ~/develop/flutter +``` + +Flutter 自己的设置(`~/.config/flutter`)和 pub 缓存(`~/.pub-cache`)在你的主目录里,不在 SDK 里,所以它们会原样用于新装的版本。 + +## 项目用不同的 Flutter 版本 + +一个老应用必须停在 `3.44.0`,新的用 `3.47.4`。手动的话,就是两个目录,加上每次切换都要改的 `PATH`。用插件,每个版本只装一次,由每个项目自己说明用哪一个: + +```bash +vfox install flutter@3.44.0 +vfox install flutter@3.47.4 +cd ~/work/legacy_app +vfox use --project flutter@3.44.0 +cd ~/work/new_app +vfox use --project flutter@3.47.4 +``` + +`vfox use --project` 把选择写进项目目录里的 `.vfox.toml`(`[tools]` 下的 `flutter = "3.44.0"`),并把 SDK 链接到 `.vfox/sdks/flutter`。你在这个目录里时,`flutter` 就是项目的 Flutter,在其他任何目录里则是用 `--global` 选的那个: + +``` +$ cd ~/work/legacy_app +$ flutter --version --no-version-check | sed -n 1p +Flutter 3.44.0 • channel stable • https://github.com/flutter/flutter.git +$ cd ~/work/new_app +$ flutter --version --no-version-check | sed -n 1p +Flutter 3.47.4 • channel stable • https://github.com/flutter/flutter.git +``` + +每个版本在磁盘上都是一个完整的 SDK,见 [platforms.md](platforms.md#前提条件)。关于作用域,有三点要知道: + +- **选择在 `.vfox.toml` 所在的目录里生效,子目录里不生效。** 在 `~/work/legacy_app/lib` 里,`flutter` 来自会话或全局的选择。`vfox current flutter` 会告诉你当前所在的位置用的是哪个版本。 +- **钩子在提示符出现时才改 `PATH`。** 把 `cd ~/work/new_app && flutter run` 写在一行里,运行的还是你来的那个目录的 Flutter。先 `cd`,再运行 `flutter`。 +- **`.vfox/` 不要提交进 git。** 项目里已有 `.gitignore` 时,vfox 会把它加进去,并打印 `Added '.vfox/' to .gitignore`。它不会新建 `.gitignore`。 + +## 团队统一 Flutter 版本 + +把 `.vfox.toml` 和 `.gitignore` 的改动提交进仓库,大家构建项目用的就是它当初所写的那个 Flutter,而不是各自机器上碰巧装着的那个。克隆项目的人在它的目录里执行: + +```bash +vfox add flutter +vfox install --all +vfox use --project flutter@3.44.0 +``` + +`vfox install --all` 会安装 `.vfox.toml` 里列出的版本,装之前会先问一下(加 `--yes` 就不问了)。它不会选中这些版本,选中是 `vfox use --project` 的事,版本号取自 `.vfox.toml`,它写出来的 `.vfox.toml` 和原来一样,所以 git 里没有新的改动可提交。`vfox add flutter` 要放在前面,因为在没有插件的机器上,`vfox install --all` 只会把插件加上,SDK 要等下一次。 + +## 升级与回退 + +新的 Flutter 装在旧的旁边,你选中它之前什么都不会变。`vfox install flutter@stable` 安装的是 stable 渠道当前指向的版本(2026-11-03 是 `3.47.9`): + +```bash +vfox install flutter@stable +vfox use --global flutter@3.47.9 +``` + +如果新版本弄坏了什么,旧的还装着: + +```bash +vfox use --global flutter@3.47.4 +``` + +`vfox uninstall flutter@3.47.9` 会删掉你不想要的那个版本,而且只删它的目录。`flutter upgrade` 则是就地改动 SDK,vfox 看不到,这时 `vfox list flutter` 说的就不再是实际运行的那个版本了,见 [flutter-upgrade.md](flutter-upgrade.md)。所以 Flutter 打出的那个建议执行 `flutter upgrade` 的 "A new version of Flutter is available!" 提示框可以不理会:`vfox install flutter@stable` 就是升级,见 [troubleshooting.md](troubleshooting.md#看起来不对但其实正常的现象)。 + +## 在一个终端里试用 beta + +```bash +vfox install flutter@beta +vfox use --session flutter@3.50.0-0.3.pre +``` + +会话级的选择只对这个终端有效。其他终端保持原来的版本,新开的终端也没有 beta。beta 一直装着,直到你执行 `vfox uninstall flutter@3.50.0-0.3.pre`。`flutter@beta` 会换成它指向的版本(2026-11-03 是 `3.50.0-0.3.pre`),`vfox use` 要写的是这个名字,见 [channels.md](channels.md#用版本号不要用渠道名)。 + +## 镜像 + +`storage.googleapis.com` 很慢或者连不上时,手动的话就要把地址里的主机换掉,比如换成 CFUG 的镜像: + +```bash +curl --location --output /tmp/flutter_linux.tar.xz https://storage.flutter-io.cn/flutter_infra_release/releases/stable/linux/flutter_linux_3.47.4-stable.tar.xz +``` + +用插件,只要设置一次 `FLUTTER_STORAGE_BASE_URL`,之后每次安装都从那里取索引和压缩包: + +```bash +export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn +vfox install flutter@3.47.4 +``` + +`flutter` 工具首次使用时下载东西,读的也是这个变量,所以它要一直保持在你的 Shell 里,而不只是在安装的时候。怎样让它永久生效、其他的镜像,以及插件不管的、用于拉取包的 `PUB_HOSTED_URL`,见 [mirror.md](mirror.md)。 + +## 脚本、容器和 IDE + +`vfox use` 需要钩子,而脚本、容器构建和 CI 步骤里没有钩子。`vfox exec` 用你指定的 Flutter 运行一条命令,有没有钩子都行: + +```bash +vfox exec flutter@3.47.4 -- flutter --version --no-version-check +``` + +想让 IDE 跟着你的全局选择走,可以把 `~/.vfox/sdks/flutter` 设为它的 Flutter SDK 路径,切换版本时就不用再改。见 [Flutter 在哪里](troubleshooting.md#flutter-在哪里)。 + +## ARM64 机器和 OpenHarmony + +Google 没有为 Linux ARM64 和 Windows ARM64 发布 Flutter 压缩包,所以手动的话,Flutter 来自 `flutter/flutter` 的一次 `git clone`。插件对不带后缀的名字就是这样做的: + +```bash +vfox install flutter@3.47.4 +``` + +它只提供那里能用原生 Dart SDK 运行 Flutter 工具的版本,见 [arm64.md](arm64.md)。gitcode.com 上的 OpenHarmony 分支版 Flutter 也是同样的装法(`vfox install flutter@3.41.10-ohos-1.0.0`),见 [ohos.md](ohos.md)。 diff --git a/docs/zh-CN/versions.md b/docs/zh-CN/versions.md index ffdd5a5..2838066 100644 --- a/docs/zh-CN/versions.md +++ b/docs/zh-CN/versions.md @@ -96,7 +96,7 @@ vfox uninstall flutter@3.47.4-x64 | `--project` | 当前目录里的 `.vfox.toml` | 那个目录里的 `.vfox/sdks/flutter/bin` | | `--session` | 只在当前 Shell 里 | `~/.vfox/tmp` 下的某个目录 | -`.vfox.toml` 里写的是已安装的名字(`flutter = "3.47.4"`)。把它提交进仓库,大家构建项目时用的就是同一个 Flutter;`.vfox/` 则不要提交:vfox 不会替你把它加进 `.gitignore`。vfox 在 `legacyVersionFile.enable` 打开时还会读取 asdf 的 `.tool-versions`(`flutter 3.47.4`),vfox 1.0.13 默认是打开的。插件自己没有旧版本文件的支持,所以不会读取 `.fvmrc` 和 FVM 的 `.fvm` 目录。 +`.vfox.toml` 里写的是已安装的名字(`flutter = "3.47.4"`)。把它提交进仓库,大家构建项目时用的就是同一个 Flutter;`.vfox/` 则不要提交:项目里已有 `.gitignore` 时,vfox 1.0.13 会替你把它加进去(打印 `Added '.vfox/' to .gitignore`),没有 `.gitignore` 时它不会替你新建。这个选择只在 `.vfox.toml` 所在的目录里生效,子目录里不生效,那里的 `flutter` 来自会话或全局的选择,见 [use-cases.md](use-cases.md#项目用不同的-flutter-版本)。vfox 在 `legacyVersionFile.enable` 打开时还会读取 asdf 的 `.tool-versions`(`flutter 3.47.4`),vfox 1.0.13 默认是打开的。插件自己没有旧版本文件的支持,所以不会读取 `.fvmrc` 和 FVM 的 `.fvm` 目录。 插件会把 `/bin` 加进 `PATH`,`flutter` 和 `dart` 就都在里面了。它不会设置 `FLUTTER_ROOT`,也不会把 `dart pub global activate` 放可执行文件的 `~/.pub-cache/bin` 加进去,这个要你自己加。