企业官网建设流程全解析

环境变量配置指南：GenLayer Project Boilerplate中RPC协议、主机与端口的正确设置姿势

【免费下载链接】genlayer-project-boilerplate项目地址: https://gitcode.com/GitHub_Trending/gen/genlayer-project-boilerplate

GenLayer Project Boilerplate 是一个开箱即用的 AI 原生智能合约脚手架项目，内置了足球竞猜（Football Bets）合约、Next.js 15 前端和完整的测试体系。但对于新手来说，环境变量配置往往是第一个"拦路虎"：明明代码没问题，却报KeyError或连接超时。本文用最直白的方式，带你彻底搞懂 GenLayer 项目中RPC 协议、主机与端口三个关键配置的正确设置方法，让你从克隆仓库到成功部署一次通关。

为什么环境变量配置如此重要？

在 GenLayer 生态中，你的应用（合约测试、部署脚本、前端 DApp）都需要通过网络连接到一个 RPC 节点才能工作。这个节点可以是本地的 GenLayer Studio（localnet），也可以是官方托管的 Studio 网络（studionet）。而连接节点需要回答三个问题：

任何一项填错，你的合约部署、集成测试或前端钱包都会失败。所以掌握这套环境变量配置逻辑，是玩转 GenLayer 的第一步。

认识核心配置文件：三个环境变量如何读取

项目把 Python 侧的配置逻辑集中在一个小文件里，路径为config/genlayer_config.py。它的核心代码非常简洁：

import os from dotenv import load_dotenv load_dotenv() def get_config() -> dict: config = { "rpc_protocol": os.environ["RPCPROTOCOL"], "rpc_host": os.environ["RPCHOST"], "rpc_port": os.environ["RPCPORT"], } return config

这里有两个关键点值得注意：

1. 它通过load_dotenv()自动加载项目根目录下的.env文件，所以你的配置应该写在.env里，而不是硬编码。
2. 它使用os.environ["RPCPROTOCOL"]这种必须存在的取值方式——如果某个变量没设置，Python 会直接抛出KeyError异常，这也是新手最常见的报错来源。

因此，三个变量RPCPROTOCOL、RPCHOST、RPCPORT必须同时配置，缺一不可。

两种主流场景的配置方法

场景一：本地开发用 localnet（推荐新手）

本地 GenLayer Studio 默认监听4000端口，对应的配置文件是gltest.config.yaml，你可以在里面看到默认值：

networks: default: localnet localnet: url: "http://127.0.0.1:4000/api" studionet: {}

也就是说，本地环境的正确配置是：

# .env 文件（项目根目录） RPCPROTOCOL=http RPCHOST=127.0.0.1 RPCPORT=4000

⚠️ 注意：本地模式必须先启动 GenLayer Studio，否则这个地址会连接失败。集成测试、部署脚本（deploy/deployScript.ts）默认都走 localnet 链。

场景二：使用官方托管网络 studionet

如果不想本地起节点，直接连官方托管服务，配置改为：

# .env 文件 RPCPROTOCOL=https RPCHOST=studio.genlayer.com RPCPORT=443

https的默认端口就是443，如果你在代码或配置里写成了别的端口，反而会连不上。这个组合与前端默认的https://studio.genlayer.com/api完全对应。

前端环境变量：NEXT_PUBLIC_GENLAYER_RPC_URL 的正确姿势

Python 侧是RPCPROTOCOL/RPCHOST/RPCPORT三件套，而 Next.js 前端则使用一套独立的NEXT_PUBLIC_前缀变量。模板文件在frontend/.env.example，内容如下：

# GenLayer RPC API URL # Default: https://studio.genlayer.com/api NEXT_PUBLIC_GENLAYER_RPC_URL=https://studio.genlayer.com/api # GenLayer Network Configuration NEXT_PUBLIC_GENLAYER_CHAIN_ID=61999 NEXT_PUBLIC_GENLAYER_CHAIN_NAME=GenLayer Studio NEXT_PUBLIC_GENLAYER_SYMBOL=GEN # GenLayer Football Betting Contract Address NEXT_PUBLIC_CONTRACT_ADDRESS=your_contract_address

前端读取这些变量的逻辑位于frontend/lib/genlayer/client.ts，它做了很好的兜底：即使变量缺失，也会回退到https://studio.genlayer.com/api和链 ID61999，保证应用不会因配置缺失直接崩溃。

部署前端前的标准动作是：

1. 把frontend/.env.example复制为frontend/.env
2. 将NEXT_PUBLIC_CONTRACT_ADDRESS换成你实际部署的合约地址
3. 运行cd frontend && npm install && npm run dev

其中NEXT_PUBLIC_GENLAYER_CHAIN_ID=61999还承担着另一个重要任务：前端在连接 MetaMask 钱包时，会用它校验当前是否处于 GenLayer 网络，不一致时自动发起网络切换。如果你改了网络，这个链 ID 也要同步改，否则钱包永远提示"网络错误"。

常见报错与排查清单

把这几个高频坑记下来，能省下大量排查时间：

配置验证与快速启动路径

配置完成后，你可以按下面的顺序快速验证整条链路是否打通：

1. 校验合约：genvm-lint check contracts/football_bets.py（无需网络）
2. 直连测试：pytest tests/direct/ -v（毫秒级，无网络依赖）
3. 部署合约：genlayer deploy（会执行deploy/deployScript.ts）
4. 集成测试：gltest tests/integration/ -v -s（需要 Studio 在线）
5. 启动前端：cd frontend && npm run dev，访问http://localhost:3000/

想要快速开始，可以直接克隆仓库：git clone https://gitcode.com/GitHub_Trending/gen/genlayer-project-boilerplate，然后按上面的步骤从.env配置入手。

总结

GenLayer Project Boilerplate 的环境变量配置并不复杂，核心就一句话：Python 侧配好RPCPROTOCOL、RPCHOST、RPCPORT三件套，前端侧配好NEXT_PUBLIC_GENLAYER_RPC_URL与链参数。本地开发用http://127.0.0.1:4000，线上托管用https://studio.genlayer.com，再把端口、链 ID 和合约地址对号入座，剩下的就是愉快的开发体验了。希望这份环境变量配置指南能帮你少踩坑、快上手，顺利跑通你的第一个 GenLayer 智能合约项目！🚀

【免费下载链接】genlayer-project-boilerplate项目地址: https://gitcode.com/GitHub_Trending/gen/genlayer-project-boilerplate