命令、文件和配置

命令进入终端

终端是您为计算机输入指令的窗口。在 Visual Studio Code 中，首先使用文件 → 打开文件夹打开您的 supastack 文件夹，然后选择终端 → 新终端。新终端在该文件夹中启动。在 Windows 上，使用终端 + 按钮旁边的菜单选择 PowerShell。在 macOS 或 Linux 终端中使用 macOS/Linux 块。

仅粘贴命令块的内容，一次一个命令，然后按 Enter。请勿粘贴周围的 Markdown 反引号、PS C:\... 等提示或示例输出。以#开头的行是解释；他们不管理任何东西。等待每个安装命令完成，然后再输入下一个命令。服务器命令持续运行，并且在您停止它之前不会返回新的提示。

检查终端正在使用哪个文件夹

存储库根是指包含 package.json、pnpm-workspace.yaml、apps 和 packages 的顶级 supastack 文件夹。除非步骤另有说明，否则请在此处运行命令。下面的命令打印当前文件夹；文件列表应显示 package.json。在 Windows PowerShell pwd 和 ls 中也可以使用。

如果列表只显示 apps/desktop 的内容，输入 cd ../.. 并按 Enter 返回根目录。如果显示的是您的主文件夹，输入 cd 加空格再加上克隆的完整路径（含空格时用引号括起来）。通常更简单的做法是在编辑器中打开项目文件夹并新建一个终端。

pwd
ls

配置位于文件中，而不是终端中

像 AI_PROVIDER=fake 这样的块是配置文本。在编辑器中打开命名的 .env 文件，找到以 AI_PROVIDER= 开头的行，替换其值并使用 Ctrl + S（macOS 上的 Command + S）保存。 KEY=value 形式中，每个设置占一行。不要添加 Markdown 反引号。避免在一个文件中重复复制同一密钥。

数据库迁移命令使用根目录的 .env，Web 后端使用 apps/web/.env.local——在仅含 Desktop 的 checkout 中，该文件属于单独的后端存储库。桌面外壳不读取 .env 文件：SUPASTACK_APP_URL 是启动时通过命令行传入的终端环境设置，而不是存储在文件中的配置。请保留示例文件原样以备日后参考。

名称以点开头的文件可能隐藏在您的文件管理器中；编辑器的资源管理器显示了它们。确保文件名完全是 .env.local，而不是 .env.local.txt。这些本地文件可以包含密码，并且被排除在 Git 之外；不要上传它们或将其内容粘贴到支持消息中。

• 查找各个设置的含义

让开发命令保持运行；用另一个终端执行命令

桌面开发命令会编译 Rust 外壳并在运行期间打开窗口。测试窗口时请保持它的终端打开。服务器命令会持续运行，在您停止它之前不会返回新的提示符。

要在服务器处于活动状态时运行另一个命令，请在编辑器中选择 Terminal → New Terminal。新终端是同一项目的一个单独窗口。要停止服务器，请选择其终端并按 Ctrl + C 一次。在 Windows 上，如果询问终止批处理作业，请键入 Y 并按 Enter。等待正常提示后再重新启动。

修改外壳设置后，用 Ctrl + C 停止桌面命令并重新运行。Rust 核心在每次启动时重新编译；更改 SUPASTACK_APP_URL 意味着在下一次运行时传入新值，而不是编辑某个已保存的文件。

corepack pnpm --filter @supastack/desktop dev

阅读失败并寻求有用的帮助

如果安装返回红色错误文本，请停止该步骤。阅读第一个错误，而不是继续启动应用程序。找不到命令通常意味着缺少工具；没有package.json通常意味着错误的文件夹； ECONNREFUSED通常表示所需的服务器或数据库未运行； EADDRINUSE 表示另一个进程已使用该端口。

寻求帮助时，请提供您的操作系统、指南 URL 和步骤号、您输入的确切命令以及第一条错误消息。删除任何数据库 URL 的密码、API 密钥、令牌和密码部分。不要发送您的 .env 文件。错误的屏幕截图可能会有所帮助，但可复制的文本更容易诊断。

• 解决特定设置失败