拓冰网站定制 
forc-publish使用 Sway 的 forc 插件将包发布到 forc.pub 注册表【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway本篇技术指南以forc-publishSway 智能合约开发工具链 forc 的官方发布插件为核心讲解如何将 Sway 包智能合约、标准库、工具库打包并上传到 forc.pub 注册表涵盖认证方式、命令行参数、底层发布流程、打包细节与本地开发调试方案。读完本文你将掌握forc publish的完整用法、三种 token 认证机制的优先级与实现原理以及如何搭建本地注册表环境进行端到端测试。一、forc-publish 是什么forc-publish是 Sway 生态中 ForcFuel OrchestratorSway 项目的构建与包管理工具的一个子命令插件负责把当前目录下的 Sway 包上传到注册表默认 forc.pub。它的定位在 Cargo.toml 中写得很明确Forc subcommand for uploading a package to the registry。从 main.rs 的 CLI 定义可以看到它只暴露两个参数参数类型默认值说明--tokenOptionString无上传时使用的认证 token--registry-urlStringhttps://api.forc.pub目标注册表 URL其中--registry-url的默认值来自源码中的常量FORC_PUB_URL: str https://api.forc.pub见 main.rs。一条命令背后的完整流程forc publish的执行主流程非常清晰对应 main.rs 中的run()函数共分四步解析认证 token调用get_auth_token(config.token, None)获取认证凭证创建压缩包在临时目录中执行create_tarball_from_current_dir将当前目录打包为sway-project.tgz上传通过ForcPubClient::upload将压缩包以 gzip 格式 POST 到注册表的upload_project端点发布拿到服务端返回的upload_id后调用ForcPubClient::publish携带 Bearer token 完成正式发布成功后终端打印Published name version的绿色提示。整个过程基于tokio异步运行时异常时通过println_error打印错误并返回非零退出码见 main.rs。二、认证方式与优先级发布到注册表需要身份认证。forc-publish依次尝试以下三种途径获取 token按优先级从高到低排列实现见 credentials.rs 的get_auth_token--token命令行参数优先级最高直接使用环境变量FORC_PUB_TOKEN通过std::env::var(FORC_PUB_TOKEN)读取~/.forc/credentials.toml配置文件读取[registry]段的token字段交互式输入兜底若以上均未命中CLI 会提示Paste your auth token found on https://forc.pub/tokens below:等待用户粘贴 token并将其自动写入~/.forc/credentials.toml见 credentials.rs。credentials.toml 文件格式配置文件结构如下这也是 README 中给出的官方格式[registry] token YOUR_TOKEN几个值得注意的细节文件固定放在~/.forc/目录下文件名恒为credentials.toml常量CREDENTIALS_FILE见 credentials.rs目录路径由forc_util::user_forc_directory()解析该文件可以由 CLI 自动创建README 明确说明运行不带--token参数的 CLI 即可自动生成此凭据文件。也就是说第一次发布时只需在提示符处粘贴 token后续发布都会自动从该文件读取从源码看解析失败如 TOML 格式错误会被静默忽略并继续走交互式输入分支不会直接报错credentials.rs内置了四组单元测试分别覆盖 CLI 参数、环境变量、文件读取和用户输入四种路径见 credentials.rs可作为理解认证逻辑的参考。三、打包前校验validate_dir在创建压缩包之前forc-publish会先对当前目录执行一系列合法性校验validate_dir见 validate.rs目的是尽早报错、避免把不合格的包发到注册表必须存在Forc.toml否则返回ForcTomlNotFound错误Forc.toml not found in the current directory[project]段必须声明version缺少时返回MissingVersionFieldmissing version field in [project] section of Forc.toml所有依赖必须用版本号声明遍历[dependencies]任何以 git 或 path 形式声明的依赖都会导致DependencyMissingVersion错误报错信息为dep_name is not a forc.pub dependency, depend on it using version.不支持 Workspace 清单若Forc.toml是 workspace 清单直接返回WorkspaceNotSupported提示需逐个成员分别部署。对应的正反例测试数据都存放在 tests/data 下success_with_deps/Forc.toml合法清单包含version 0.0.0可正常通过without_version/Forc.toml缺少version字段校验失败deps_without_version/依赖未带版本号校验失败success_with_no_deps/无依赖的合法包校验通过。这意味着要成功发布Forc.toml至少要满足类似下面这样含版本号且依赖均带版本[project] authors [Your Name youexample.com] entry lib.sw license Apache-2.0 name my_sway_lib implicit-std false version 0.1.0 [dependencies] some_lib { version 0.2.0 }四、打包细节tarball 的生成与 README 预处理校验通过后create_tarball_from_current_dir见 tarball.rs负责把当前目录打包成 gzip 压缩的 tar 归档产物固定命名为sway-project.tgz。整个过程分三步1. 复制项目并排除out/目录使用walkdir遍历当前目录逐文件复制到临时目录跳过所有out目录Sway 的编译输出目录见 tarball.rs。这是打包体积优化的关键编译产物不应进入注册表。单元测试test_create_tarball_excludes_out_dir专门验证了归档中不包含out/见 tarball.rs。2. 预处理 README.md若项目中存在README.md会调用flatten_markdown将其中的{{#include ...}}引用内联展开后再写入归档见 tarball.rs。这个预处理由 md_pre_process 模块实现用正则\{\{#include\s([^\}])\}\}扫描 include 指令构建 Markdown 文件的依赖图通过拓扑排序确定展开顺序叶子文件先展开若检测到 include 循环引用返回Cycle错误若引用的文件不存在返回MissingInclude错误预处理失败不会中止发布只会打印 warningFailed to flatten README.md includes后继续。该模块内置了单文件、简单 include、嵌套 include、多 include、缺失 include、循环检测共六组测试见 md_pre_process/mod.rs。3. 写入 tar 归档最后用tar::Builder将临时目录整体写入 gzip 编码器生成最终 tarball 并返回其临时路径。五、上传与发布HTTP 协议细节ForcPubClient见 forc_pub_client.rs封装了与注册表服务端交互的两个 HTTP 调用使用reqwest实现上传阶段POST /upload_project请求 URL 为registry-url/upload_project?forc_version版本其中forc_version来自crate_version!()编译时的 forc-publish 版本号请求头Content-Type: application/gzipbody 直接携带 tarball 二进制字节响应是SSEServer-Sent Events流服务端逐条推送data: event事件第一条通常是进度提示如uploading...客户端用\r\x1b[2K回车符原地刷新进度行最后一条是 JSON 格式的{upload_id: uuid}客户端逐条解析能反序列化为UploadResponse即返回upload_id若data以{开头但解析失败视为服务端错误 JSON返回ApiResponseError服务端若 60 秒无响应会关闭流此时返回ServerError。wiremock 测试test_upload_success/test_upload_server_error完整模拟了这两种响应见 forc_pub_client.rs。发布阶段POST /publish请求 URL 为registry-url/publish请求头Content-Type: application/json以及Authorization: Bearer auth_token这就是认证 token 真正被使用的环节见 forc_pub_client.rsbody 为{upload_id: uuid}PublishRequest成功时返回{name: ..., version: ...}PublishResponseCLI 据此打印Published name version失败时如 401 Unauthorized、500 Internal Server Error通过Error::from_response解析错误 JSON 中的error字段并包装为ApiResponseError见 error.rs。test_publish_unauthorized、test_publish_server_error分别验证了这两类错误路径。六、本地开发对接本地注册表README 给出了官方推荐的本地产研工作流运行 forc.pubforc.pub 注册表服务端的源码仓库在其 Web 界面创建 API token执行forc publish --registry-url http://localhost:8080通过--registry-url覆盖默认的https://api.forc.pub即可把包发布到本地实例。结合前文认证优先级本地调试时也可用环境变量注入 tokenFORC_PUB_TOKENyour_local_token forc publish --registry-url http://localhost:8080本地调试建议在项目根目录含合法Forc.toml执行以便通过validate_dir校验。若当前目录不是 Sway 包会立即得到Forc.toml not found in the current directory错误。七、常见错误速查错误信息含义解决办法Forc.toml not found in the current directory当前目录不是 Sway 包在包根目录执行forc publishmissing version field in [project] section of Forc.tomlForc.toml缺version在[project]补上version 0.x.ydep is not a forc.pub dependency, depend on it using version.依赖用 git/path 形式声明改为版本依赖如{ version 0.2.0 }Workspace is not supported yet, deploy each member separately尝试发布 workspace 清单进入具体成员目录单独发布401 Unauthorizedtoken 无效或未提供检查--token/FORC_PUB_TOKEN/credentials.tomlServer error上传流超时或非预期中断检查注册表服务状态后重试以上错误类型均在 error.rs 中定义是排查问题最直接的依据。八、源码导航如果你想深入阅读实现推荐按以下顺序浏览main.rsCLI 入口与主流程编排credentials.rstoken 解析优先级与凭据文件读写validate.rs发布前合法性校验tarball.rs项目复制、排除out/、README 预处理与归档打包forc_pub_client.rs上传/发布的 HTTP 客户端md_pre_processREADME{{#include}}展开tests/data发布校验的正反例测试数据。结语forc-publish虽然只是一个短小精悍的 forc 插件却完整覆盖了校验 → 打包 → 上传 → 发布的包发布闭环认证上支持命令行参数、环境变量、凭据文件与交互式输入四级降级策略打包上自动剔除编译产物并预处理 README协议上基于 gzip 上传与 SSE 进度流、Bearer token 鉴权发布。结合本地 forc.pub 实例与--registry-url参数开发者完全可以在本地完整演练一遍 Sway 包发布流程。【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 forc-publish：使用 Sway 的 forc 插件将包发布到 forc.pub 注册表
forc-publish使用 Sway 的 forc 插件将包发布到 forc.pub 注册表【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway本篇技术指南以forc-publishSway 智能合约开发工具链 forc 的官方发布插件为核心讲解如何将 Sway 包智能合约、标准库、工具库打包并上传到 forc.pub 注册表涵盖认证方式、命令行参数、底层发布流程、打包细节与本地开发调试方案。读完本文你将掌握forc publish的完整用法、三种 token 认证机制的优先级与实现原理以及如何搭建本地注册表环境进行端到端测试。一、forc-publish 是什么forc-publish是 Sway 生态中 ForcFuel OrchestratorSway 项目的构建与包管理工具的一个子命令插件负责把当前目录下的 Sway 包上传到注册表默认 forc.pub。它的定位在 Cargo.toml 中写得很明确Forc subcommand for uploading a package to the registry。从 main.rs 的 CLI 定义可以看到它只暴露两个参数参数类型默认值说明--tokenOptionString无上传时使用的认证 token--registry-urlStringhttps://api.forc.pub目标注册表 URL其中--registry-url的默认值来自源码中的常量FORC_PUB_URL: str https://api.forc.pub见 main.rs。一条命令背后的完整流程forc publish的执行主流程非常清晰对应 main.rs 中的run()函数共分四步解析认证 token调用get_auth_token(config.token, None)获取认证凭证创建压缩包在临时目录中执行create_tarball_from_current_dir将当前目录打包为sway-project.tgz上传通过ForcPubClient::upload将压缩包以 gzip 格式 POST 到注册表的upload_project端点发布拿到服务端返回的upload_id后调用ForcPubClient::publish携带 Bearer token 完成正式发布成功后终端打印Published name version的绿色提示。整个过程基于tokio异步运行时异常时通过println_error打印错误并返回非零退出码见 main.rs。二、认证方式与优先级发布到注册表需要身份认证。forc-publish依次尝试以下三种途径获取 token按优先级从高到低排列实现见 credentials.rs 的get_auth_token--token命令行参数优先级最高直接使用环境变量FORC_PUB_TOKEN通过std::env::var(FORC_PUB_TOKEN)读取~/.forc/credentials.toml配置文件读取[registry]段的token字段交互式输入兜底若以上均未命中CLI 会提示Paste your auth token found on https://forc.pub/tokens below:等待用户粘贴 token并将其自动写入~/.forc/credentials.toml见 credentials.rs。credentials.toml 文件格式配置文件结构如下这也是 README 中给出的官方格式[registry] token YOUR_TOKEN几个值得注意的细节文件固定放在~/.forc/目录下文件名恒为credentials.toml常量CREDENTIALS_FILE见 credentials.rs目录路径由forc_util::user_forc_directory()解析该文件可以由 CLI 自动创建README 明确说明运行不带--token参数的 CLI 即可自动生成此凭据文件。也就是说第一次发布时只需在提示符处粘贴 token后续发布都会自动从该文件读取从源码看解析失败如 TOML 格式错误会被静默忽略并继续走交互式输入分支不会直接报错credentials.rs内置了四组单元测试分别覆盖 CLI 参数、环境变量、文件读取和用户输入四种路径见 credentials.rs可作为理解认证逻辑的参考。三、打包前校验validate_dir在创建压缩包之前forc-publish会先对当前目录执行一系列合法性校验validate_dir见 validate.rs目的是尽早报错、避免把不合格的包发到注册表必须存在Forc.toml否则返回ForcTomlNotFound错误Forc.toml not found in the current directory[project]段必须声明version缺少时返回MissingVersionFieldmissing version field in [project] section of Forc.toml所有依赖必须用版本号声明遍历[dependencies]任何以 git 或 path 形式声明的依赖都会导致DependencyMissingVersion错误报错信息为dep_name is not a forc.pub dependency, depend on it using version.不支持 Workspace 清单若Forc.toml是 workspace 清单直接返回WorkspaceNotSupported提示需逐个成员分别部署。对应的正反例测试数据都存放在 tests/data 下success_with_deps/Forc.toml合法清单包含version 0.0.0可正常通过without_version/Forc.toml缺少version字段校验失败deps_without_version/依赖未带版本号校验失败success_with_no_deps/无依赖的合法包校验通过。这意味着要成功发布Forc.toml至少要满足类似下面这样含版本号且依赖均带版本[project] authors [Your Name youexample.com] entry lib.sw license Apache-2.0 name my_sway_lib implicit-std false version 0.1.0 [dependencies] some_lib { version 0.2.0 }四、打包细节tarball 的生成与 README 预处理校验通过后create_tarball_from_current_dir见 tarball.rs负责把当前目录打包成 gzip 压缩的 tar 归档产物固定命名为sway-project.tgz。整个过程分三步1. 复制项目并排除out/目录使用walkdir遍历当前目录逐文件复制到临时目录跳过所有out目录Sway 的编译输出目录见 tarball.rs。这是打包体积优化的关键编译产物不应进入注册表。单元测试test_create_tarball_excludes_out_dir专门验证了归档中不包含out/见 tarball.rs。2. 预处理 README.md若项目中存在README.md会调用flatten_markdown将其中的{{#include ...}}引用内联展开后再写入归档见 tarball.rs。这个预处理由 md_pre_process 模块实现用正则\{\{#include\s([^\}])\}\}扫描 include 指令构建 Markdown 文件的依赖图通过拓扑排序确定展开顺序叶子文件先展开若检测到 include 循环引用返回Cycle错误若引用的文件不存在返回MissingInclude错误预处理失败不会中止发布只会打印 warningFailed to flatten README.md includes后继续。该模块内置了单文件、简单 include、嵌套 include、多 include、缺失 include、循环检测共六组测试见 md_pre_process/mod.rs。3. 写入 tar 归档最后用tar::Builder将临时目录整体写入 gzip 编码器生成最终 tarball 并返回其临时路径。五、上传与发布HTTP 协议细节ForcPubClient见 forc_pub_client.rs封装了与注册表服务端交互的两个 HTTP 调用使用reqwest实现上传阶段POST /upload_project请求 URL 为registry-url/upload_project?forc_version版本其中forc_version来自crate_version!()编译时的 forc-publish 版本号请求头Content-Type: application/gzipbody 直接携带 tarball 二进制字节响应是SSEServer-Sent Events流服务端逐条推送data: event事件第一条通常是进度提示如uploading...客户端用\r\x1b[2K回车符原地刷新进度行最后一条是 JSON 格式的{upload_id: uuid}客户端逐条解析能反序列化为UploadResponse即返回upload_id若data以{开头但解析失败视为服务端错误 JSON返回ApiResponseError服务端若 60 秒无响应会关闭流此时返回ServerError。wiremock 测试test_upload_success/test_upload_server_error完整模拟了这两种响应见 forc_pub_client.rs。发布阶段POST /publish请求 URL 为registry-url/publish请求头Content-Type: application/json以及Authorization: Bearer auth_token这就是认证 token 真正被使用的环节见 forc_pub_client.rsbody 为{upload_id: uuid}PublishRequest成功时返回{name: ..., version: ...}PublishResponseCLI 据此打印Published name version失败时如 401 Unauthorized、500 Internal Server Error通过Error::from_response解析错误 JSON 中的error字段并包装为ApiResponseError见 error.rs。test_publish_unauthorized、test_publish_server_error分别验证了这两类错误路径。六、本地开发对接本地注册表README 给出了官方推荐的本地产研工作流运行 forc.pubforc.pub 注册表服务端的源码仓库在其 Web 界面创建 API token执行forc publish --registry-url http://localhost:8080通过--registry-url覆盖默认的https://api.forc.pub即可把包发布到本地实例。结合前文认证优先级本地调试时也可用环境变量注入 tokenFORC_PUB_TOKENyour_local_token forc publish --registry-url http://localhost:8080本地调试建议在项目根目录含合法Forc.toml执行以便通过validate_dir校验。若当前目录不是 Sway 包会立即得到Forc.toml not found in the current directory错误。七、常见错误速查错误信息含义解决办法Forc.toml not found in the current directory当前目录不是 Sway 包在包根目录执行forc publishmissing version field in [project] section of Forc.tomlForc.toml缺version在[project]补上version 0.x.ydep is not a forc.pub dependency, depend on it using version.依赖用 git/path 形式声明改为版本依赖如{ version 0.2.0 }Workspace is not supported yet, deploy each member separately尝试发布 workspace 清单进入具体成员目录单独发布401 Unauthorizedtoken 无效或未提供检查--token/FORC_PUB_TOKEN/credentials.tomlServer error上传流超时或非预期中断检查注册表服务状态后重试以上错误类型均在 error.rs 中定义是排查问题最直接的依据。八、源码导航如果你想深入阅读实现推荐按以下顺序浏览main.rsCLI 入口与主流程编排credentials.rstoken 解析优先级与凭据文件读写validate.rs发布前合法性校验tarball.rs项目复制、排除out/、README 预处理与归档打包forc_pub_client.rs上传/发布的 HTTP 客户端md_pre_processREADME{{#include}}展开tests/data发布校验的正反例测试数据。结语forc-publish虽然只是一个短小精悍的 forc 插件却完整覆盖了校验 → 打包 → 上传 → 发布的包发布闭环认证上支持命令行参数、环境变量、凭据文件与交互式输入四级降级策略打包上自动剔除编译产物并预处理 README协议上基于 gzip 上传与 SSE 进度流、Bearer token 鉴权发布。结合本地 forc.pub 实例与--registry-url参数开发者完全可以在本地完整演练一遍 Sway 包发布流程。【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考