Astryx翻译站点

学习目标

通过本教程，你将掌握如何利用 Astryx 开源设计系统，快速搭建一个完全可定制的、集成 AI 代理的 Web 界面。你将学会：

• 安装并初始化 Astryx 项目
• 自定义组件样式与行为
• 接入 AI 代理功能
• 解决常见部署问题

前置条件

• 已安装 Node.js 18+ 和 npm 9+
• 基本了解 React 或 Vue 组件化开发
• 拥有一个 GitHub 账号（用于克隆仓库）
• 可选：一个 OpenAI API 密钥（如需启用 AI 代理）

分步操作

步骤 1：克隆项目并安装依赖

1. 打开终端，执行以下命令克隆 Astryx 仓库：

   git clone https://github.com/atmeta/astryx.git
   cd astryx

2. 安装项目依赖：

   npm install

• 预期结果：node_modules 文件夹生成，无报错。
• 注意：如果网络受限，使用 npm install --registry=https://registry.npmmirror.com。

步骤 2：启动开发服务器

1. 运行启动命令：

   npm run dev

2. 在浏览器中打开 http://localhost:3000。

• 预期结果：看到一个包含按钮、表单、卡片等基础组件的示例页面。
• 排查：如果端口被占用，修改 package.json 中的 dev 脚本，添加 --port 4000。

步骤 3：自定义组件样式

Astryx 使用 CSS 变量进行主题定制，所有变量定义在 src/styles/variables.css 中。

1. 打开 src/styles/variables.css，找到以下变量：

   --color-primary: #007bff;
   --border-radius: 4px;

2. 修改为你的品牌色：

   --color-primary: #ff6600;
   --border-radius: 8px;

3. 保存文件，浏览器自动热更新。

• 预期结果：所有按钮、链接、边框变为橙色，圆角增大。
• 注意：如需覆盖单个组件样式，可在 src/components/YourComponent.module.css 中使用 :global 选择器。

步骤 4：集成 AI 代理

Astryx 内置 AIProvider 组件，用于连接 AI 模型。

1. 在 src/App.jsx 中，导入 AIProvider：

   import { AIProvider } from '@astryx/ai';

2. 包裹你的应用，并传入 API 密钥（示例使用环境变量）：

   <AIProvider apiKey={import.meta.env.VITE_OPENAI_API_KEY} model="gpt-4">
     <YourApp />
   </AIProvider>

3. 在任意组件中使用 useAI hook 调用 AI 代理：

   const { ask } = useAI();
   const response = await ask('生成一个登录表单的代码');

• 预期结果：response 返回 AI 生成的代码片段。
• 注意：VITE_OPENAI_API_KEY 需在项目根目录创建 .env 文件并写入。
• 排查：如果返回 401 错误，检查 API 密钥是否有效，或模型是否支持。

步骤 5：构建生产版本

1. 运行构建命令：

   npm run build

2. 输出文件位于 dist/ 目录。

• 预期结果：生成压缩后的 HTML、CSS、JS 文件。
• 注意：如果使用 AI 代理，确保 .env 中的密钥在生产环境中也配置（如通过 CI/CD 注入）。

常见问题

下一步

• 查看 src/examples/ 目录下的完整示例
• 阅读官方文档：https://astryx.atmeta.com/docs
• 在 GitHub 仓库提交 Issue 反馈问题